Files
skillshare/ai_docs/tests/config_keeps_comments_runbook.md
T
Willie 2d5849a0ef fix(config): keep YAML anchors and aliases when a command writes the config (#551)
* fix(config): keep YAML anchors and aliases when a command writes the config

Every writer re-encodes the in-memory struct, which has no anchors, so a
command such as `target a --add-exclude` expanded `&shared` / `*shared`
under targets and projects and the lists stopped following each other.
The comment pass added for #525 already pairs each old node with the one
that replaced it; relinkAliases uses the same pairs to put anchors back and
turn unedited alias values into aliases again.

An anchored node keeps its anchor and the aliases that still hold its old
value follow its new value, as the file declares. An alias that was edited
keeps its own list and leaves the anchored one alone. Output is sorted by
name, so the anchor moves to the first place the group appears: an alias
may not precede its anchor.

Fixes #546

* fix(config): keep YAML merge keys when a command writes the config

A command rewrites config.yaml from the Go struct, which holds the merged
keys of `<<: *base` and not the merge itself, so every merge key was written
out expanded and later edits of the anchored mapping no longer reached the
mappings that merged it. relinkAliases already restored anchors and aliases
from the old/new node pairing; relinkMerge now does the same for merge keys,
including `<<: [*a, *b]`, merges in nested mappings and in project-config
target items.

A key stays written out when the old mapping set it itself, or when its value
is no longer the one its merge source gives it. yaml.v3 merges are shallow, so
such a key replaces the merged value as a whole and what is written always
decodes to the config the command meant to save. A source that was removed, or
that holds a key the mapping no longer has, is not merged back.

Output order is not the old file's order, so an anchor that would follow its
first merge key moves onto it (`<<: &base`). The next write pairs that mapping
with the alias that still shows its value, so the file stays stable.

The runbook steps for anchors now write their own config: mdproof re-runs the
setup before each step, so step 7 and 8 never saw the config of step 6
(Codex review on #551). Steps for merge keys are added the same way.

* fix(config): let edits of an anchored mapping that add or remove a key reach its mergers

A command that added a key to an anchored mapping (the first `agents:`
block via `target base --agent-mode copy`) made relinkMerge refuse the
merge source: the merging mapping's pre-edit data lacked the key, which
was read as "the command removed it". The merge key was dropped and the
merger written out expanded, so later edits of the anchor no longer
reached it.

A source is now refused only when the merging mapping had a key before
the write and the command removed it. A key the source gained does not
count.

The symmetric case is fixed with it: a key removed from the anchored
mapping stayed written out under a merger that still held the old merged
value. An unedited key that the merger did not set itself now follows
the source that gave it, whatever that source now says (a changed value,
a removed key, or the next source of `<<: [*a, *b]`). A key the merger
set itself, or that the command edited, stays written out.

Tests cover add, remove and change of a key on the anchored mapping and
on the merging mapping, a key from either source of a merge list, nested
merges, projects, project-config target items and chained merges. Runbook
step 11 covers the real binary.

* fix(config): keep every comment when a write relinks merge keys and aliases

Rewriting a merge key replaced the original merge items and covered keys with
new nodes and carried over only the comments of the key and the list itself, so
a comment on an item of `<<:` followed by `- *a # note` was lost on any write,
and so was the trailing comment of a removed key when the mapping was left with
keys the merge supplies.

Comments now follow the entry they were on: a merge item's to the alias that
replaces it, those of an item that is no longer merged to the next item, and
those of a key the merge supplies to the next key still written, or in front of
the merge key when none is. The merge list keeps its flow or block style so item
comments stay on their lines.

Sweeping the rest of the relink paths for the same loss found more places where
yaml.v3 drops or moves a comment: the comment after an anchor on a block mapping
collided with its first key's comment, a line comment on a block collection or
on a key with an empty value is not written, and an anchored collection's head
comment moved on the next write. These are settled once on the written tree, and
the body of an inline merge source gets its comments paired too.
2026-10-13 11:14:06 +08:00

12 KiB

CLI E2E Runbook: config.yaml Keeps Its Comments

Verifies that commands which write config.yaml keep every comment in it: head, inline and trailing comments, comments with odd spacing or no space after #, comments on nested keys and list items, and comments on a key the command removed. It also checks that YAML anchors, aliases and merge keys (<<: *base) survive.

Origin: #525 — on 0.25.4 target --mode copy --target-naming prefixed dropped marker comments a user's script relied on. #546 — on 0.25.5 the same write expanded &anchor / *alias pairs under targets and projects. Merge keys were expanded the same way.

Scope

  • Global mode, config.yaml written by target (set and remove)
  • Every comment survives, including the ones on the removed target
  • The schema header appears once
  • An anchored list keeps its anchor and its alias after an edit; editing the aliased list gives it its own copy and leaves the anchored one alone
  • A merge key (<<: *base) stays after an edit and only the keys the mapping sets itself are written out; editing the anchored mapping reaches a mapping that merges it (a key it gains included), and removing the anchored mapping writes the merged keys out
  • Comments on the items of a merge list, and on a key the command removed from a mapping that is left with merged keys only, are not lost

Environment

Run inside the devcontainer with ssenv isolation (--init). mdproof replaces $HOME, so the config is reached through $XDG_CONFIG_HOME. mdproof's setup re-runs init before every step, so steps 6 to 13 each write their own config instead of relying on an earlier step.

Steps

1. Setup: a config full of comments

CFG=$XDG_CONFIG_HOME/skillshare/config.yaml
cat > "$CFG" <<'YAML'
#ddddsxx
sources:
  skills: SRC/skills #inline1
#   weird   spacing   #  here
mode: merge #ddddsxx2
targets:
  #ddddsxx3 nested
  claude:
    skills:
      path: HOME/.claude/skills # path note
  universal: # will be removed
    skills:
      path: HOME/.agents/skills #ddddsxx4
ignore:
  - .DS_Store #ddddsxx5
  # between items
  - .git/
#ddddsxx6 end
YAML
sed -i "s|SRC|$XDG_CONFIG_HOME/skillshare|; s|HOME|$HOME|g" "$CFG"
echo "comments=$(grep -c '#' "$CFG")"

Expected:

  • exit_code: 0
  • comments=11

2. Set a target option

ss target claude --mode copy --target-naming prefixed

Expected:

  • exit_code: 0

3. Every comment is still there and the value changed

CFG=$XDG_CONFIG_HOME/skillshare/config.yaml
grep -c "target_naming: prefixed" "$CFG"
for c in '#ddddsxx$' '#inline1' 'weird   spacing' '#ddddsxx2' '#ddddsxx3 nested' '# path note' '# will be removed' '#ddddsxx4' '#ddddsxx5' '# between items' '#ddddsxx6 end'; do grep -q -- "$c" "$CFG" && echo "kept $c" || echo "LOST $c"; done
echo "schema-headers=$(grep -c 'yaml-language-server' "$CFG")"
echo "lost-count=$(grep -c 'LOST' <<<"$(for c in ddddsxx inline1 spacing note removed between; do grep -q "$c" "$CFG" || echo LOST; done)")"

Expected:

  • exit_code: 0
  • 1
  • kept #ddddsxx$
  • kept # will be removed
  • kept # between items
  • schema-headers=1
  • lost-count=0

4. Remove a target

ss target remove universal

Expected:

  • exit_code: 0

5. The removed target's comments moved to the end of targets

CFG=$XDG_CONFIG_HOME/skillshare/config.yaml
grep -c "universal:" "$CFG"
echo "lost-count=$(grep -c 'LOST' <<<"$(for c in ddddsxx ddddsxx2 ddddsxx3 ddddsxx4 ddddsxx5 ddddsxx6 inline1 spacing note removed between; do grep -q "$c" "$CFG" || echo LOST; done)")"
awk '/^targets:/{t=1} t&&/will be removed/{print "orphans-under-targets"; exit} /^ignore:/{exit}' "$CFG"

Expected:

  • exit_code: 0
  • 0
  • lost-count=0
  • orphans-under-targets

6. Editing the anchored target keeps the anchor and the alias

CFG=$XDG_CONFIG_HOME/skillshare/config.yaml
cat > "$CFG" <<'YAML'
sources:
  skills: SRC/skills
targets:
  claude:
    skills:
      path: HOME/.claude/skills
      include: &shared
        - demo
  codex:
    skills:
      path: HOME/.codex/skills
      include: *shared
YAML
sed -i "s|SRC|$XDG_CONFIG_HOME/skillshare|; s|HOME|$HOME|g" "$CFG"
ss target claude --add-exclude 'old-*'
echo "anchors=$(grep -c '&shared' "$CFG") aliases=$(grep -c '\*shared' "$CFG")"
grep -c -- "- old-\*" "$CFG"

Expected:

  • exit_code: 0
  • anchors=1 aliases=1
  • 1

7. Editing the aliased target gives it its own list

CFG=$XDG_CONFIG_HOME/skillshare/config.yaml
cat > "$CFG" <<'YAML'
sources:
  skills: SRC/skills
targets:
  claude:
    skills:
      path: HOME/.claude/skills
      include: &shared
        - demo
  codex:
    skills:
      path: HOME/.codex/skills
      include: *shared
YAML
sed -i "s|SRC|$XDG_CONFIG_HOME/skillshare|; s|HOME|$HOME|g" "$CFG"
ss target codex --add-include extra
echo "aliases=$(grep -c '\*shared' "$CFG")"
echo "extra=$(grep -c -- '- extra' "$CFG")"
awk '/^  claude:/{c=1} /^  codex:/{c=0} c&&/- extra/{n++} END{print "claude-extras=" n+0}' "$CFG"

Expected:

  • exit_code: 0
  • aliases=0
  • extra=1
  • claude-extras=0

8. A merge key survives an edit and only local keys stay written out

claude merges zshared and sets its own skills; codex only merges. Targets are written in name order, so the anchor moves onto the first merge key that uses it.

CFG=$XDG_CONFIG_HOME/skillshare/config.yaml
cat > "$CFG" <<'YAML'
sources:
  skills: SRC/skills
targets:
  zshared: &shared
    skills:
      path: HOME/.shared/skills
      mode: copy
  claude:
    # inherits the shared settings
    <<: *shared
    skills:
      path: HOME/.claude/skills
  codex:
    <<: *shared
YAML
sed -i "s|SRC|$XDG_CONFIG_HOME/skillshare|; s|HOME|$HOME|g" "$CFG"
mode() { ss target list --json | tr -d ' \n' | grep -o "\"name\":\"$1\",\"path\":\"[^\"]*\",\"mode\":\"[a-z]*\"" | sed 's/.*"mode"://'; }
ss target claude --add-exclude 'old-*'
echo "merges=$(grep -c '<<:' "$CFG")"
echo "anchors=$(grep -c '&shared' "$CFG") aliases=$(grep -c '\*shared' "$CFG")"
echo "comment=$(grep -c '# inherits the shared settings' "$CFG")"
echo "codex-own-keys=$(awk '/^  codex:/{c=1;next} /^  [a-z]/{c=0} c' "$CFG" | grep -c -v '<<:')"
echo "codex-mode=$(mode codex)"

Expected:

  • exit_code: 0
  • merges=2
  • anchors=1 aliases=2
  • comment=1
  • codex-own-keys=0
  • codex-mode="copy"

9. Editing the anchored target reaches the merging target, an override stays local

CFG=$XDG_CONFIG_HOME/skillshare/config.yaml
cat > "$CFG" <<'YAML'
sources:
  skills: SRC/skills
targets:
  zshared: &shared
    skills:
      path: HOME/.shared/skills
      mode: copy
  claude:
    # inherits the shared settings
    <<: *shared
    skills:
      path: HOME/.claude/skills
  codex:
    <<: *shared
YAML
sed -i "s|SRC|$XDG_CONFIG_HOME/skillshare|; s|HOME|$HOME|g" "$CFG"
mode() { ss target list --json | tr -d ' \n' | grep -o "\"name\":\"$1\",\"path\":\"[^\"]*\",\"mode\":\"[a-z]*\"" | sed 's/.*"mode"://'; }
ss target zshared --mode symlink
echo "merges=$(grep -c '<<:' "$CFG")"
echo "codex-mode=$(mode codex)"
echo "claude-mode=$(mode claude)"

Expected:

  • exit_code: 0
  • merges=2
  • codex-mode="symlink"
  • claude-mode="merge"

10. Removing the anchored target writes the merged keys out

CFG=$XDG_CONFIG_HOME/skillshare/config.yaml
cat > "$CFG" <<'YAML'
sources:
  skills: SRC/skills
targets:
  zshared: &shared
    skills:
      path: HOME/.shared/skills
      mode: copy
  claude:
    # inherits the shared settings
    <<: *shared
    skills:
      path: HOME/.claude/skills
  codex:
    <<: *shared
YAML
sed -i "s|SRC|$XDG_CONFIG_HOME/skillshare|; s|HOME|$HOME|g" "$CFG"
mode() { ss target list --json | tr -d ' \n' | grep -o "\"name\":\"$1\",\"path\":\"[^\"]*\",\"mode\":\"[a-z]*\"" | sed 's/.*"mode"://'; }
ss target remove zshared
echo "merges=$(grep -c '<<:' "$CFG") anchors=$(grep -c '&shared' "$CFG") aliases=$(grep -c '\*shared' "$CFG")"
echo "comment=$(grep -c '# inherits the shared settings' "$CFG")"
echo "codex-mode=$(mode codex)"

Expected:

  • exit_code: 0
  • merges=0 anchors=0 aliases=0
  • comment=1
  • codex-mode="copy"

11. A key added to the anchored target reaches the merging targets

base has no agents block yet; work only merges and home sets its own skills.

CFG=$XDG_CONFIG_HOME/skillshare/config.yaml
cat > "$CFG" <<'YAML'
sources:
  skills: SRC/skills
targets:
  base: &base
    agent: claude
    config_dir: HOME/.base
    skills:
      mode: copy
  work:
    <<: *base
    config_dir: HOME/.work
  home:
    <<: *base
    config_dir: HOME/.home
    skills:
      mode: symlink
YAML
sed -i "s|SRC|$XDG_CONFIG_HOME/skillshare|; s|HOME|$HOME|g" "$CFG"
ss target base --agent-mode copy
echo "merges=$(grep -c '<<:' "$CFG") anchors=$(grep -c '&base' "$CFG")"
echo "agents-blocks=$(grep -c 'agents:' "$CFG")"
echo "agent-copy=$(ss target list --json | tr -d ' \n' | grep -o '"agentMode":"copy"' | wc -l)"

Expected:

  • exit_code: 0
  • merges=2 anchors=1
  • agents-blocks=1
  • agent-copy=3

12. Comments on the items of a merge list stay on them

alpha and beta sort before claude, so their anchors stay where they are.

CFG=$XDG_CONFIG_HOME/skillshare/config.yaml
cat > "$CFG" <<'YAML'
sources:
  skills: SRC/skills
targets:
  alpha: &a
    skills:
      path: HOME/.alpha/skills
  beta: &b
    agents:
      path: HOME/.beta/agents
  claude:
    <<:
      # about the first source
      - *a # line a
      - *b # line b
    skills:
      path: HOME/.claude/skills
YAML
sed -i "s|SRC|$XDG_CONFIG_HOME/skillshare|; s|HOME|$HOME|g" "$CFG"
ss target claude --add-exclude 'old-*'
echo "merges=$(grep -c '<<:' "$CFG")"
echo "comments=$(grep -c -e '# about the first source' -e '# line a' -e '# line b' "$CFG")"
echo "line-a=$(grep -c -e '- \*a # line a' "$CFG")"
echo "line-b=$(grep -c -e '- \*b # line b' "$CFG")"

Expected:

  • exit_code: 0
  • merges=1
  • comments=3
  • line-a=1
  • line-b=1

13. Comments of a removed key stay when only merged keys are left

claude sets one key of its own, exclude, with comments around it. Removing it must not drop them, although the keys left in claude come from the merge.

CFG=$XDG_CONFIG_HOME/skillshare/config.yaml
cat > "$CFG" <<'YAML'
sources:
  skills: SRC/skills
targets:
  base: &shared
    skills:
      path: HOME/.shared/skills
      mode: copy
  claude:
    <<: *shared
    # why the exclude
    exclude:
      - old-* # drop the old ones
    # end of the exclude
YAML
sed -i "s|SRC|$XDG_CONFIG_HOME/skillshare|; s|HOME|$HOME|g" "$CFG"
ss target claude --remove-exclude 'old-*'
echo "merges=$(grep -c '<<:' "$CFG") exclude=$(grep -c 'exclude:' "$CFG")"
echo "comments=$(grep -c -e '# why the exclude' -e '# drop the old ones' -e '# end of the exclude' "$CFG")"

Expected:

  • exit_code: 0
  • merges=1 exclude=0
  • comments=3

Pass Criteria

  • Step 3: all 11 comments present after target set, schema header once.
  • Step 5: universal gone, all 11 comments still present, the removed target's comments sit inside the targets section.
  • Step 6: the &shared anchor and its *shared alias are both still there.
  • Step 7: codex no longer aliases shared, and claude did not gain extra.
  • Step 8: both <<: keys are still there with one anchor and two aliases of it, codex writes nothing but its merge key and still loads as copy.
  • Step 9: codex follows the edit of the anchored target; claude, which sets its own skills, does not.
  • Step 10: no <<:, anchor or alias is left, codex still loads as copy, and the comment on the removed merge key is still in the file.
  • Step 11: both <<: keys and the anchor are still there, the new agents block is written once under base, and all three targets load it.
  • Step 12: the merge list is still there and each of its three comments is written once, the line comments on the item they were on.
  • Step 13: the merge key is still there, exclude is gone, and its three comments are all still in the file.