yadflow 4.5.2 → 4.7.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (101) hide show
  1. package/CHANGELOG.md +206 -0
  2. package/README.md +4 -1
  3. package/bin/commands.mjs +5 -1
  4. package/bin/yad.mjs +174 -18
  5. package/cli/artifact-status.mjs +88 -20
  6. package/cli/build.mjs +1372 -0
  7. package/cli/checkpoint.mjs +2 -2
  8. package/cli/commit.mjs +1 -0
  9. package/cli/dial.mjs +21 -1
  10. package/cli/docs.mjs +6 -1
  11. package/cli/doctor.mjs +133 -26
  12. package/cli/epic-state.mjs +396 -123
  13. package/cli/errors.mjs +2 -0
  14. package/cli/find-product.mjs +36 -2
  15. package/cli/fold.mjs +9 -5
  16. package/cli/gate-local.mjs +9 -1
  17. package/cli/gate.mjs +442 -33
  18. package/cli/history.mjs +22 -2
  19. package/cli/hook.mjs +3 -1
  20. package/cli/index-command.mjs +2 -2
  21. package/cli/ledger.mjs +60 -0
  22. package/cli/lib.mjs +12 -1
  23. package/cli/lifecycle/defaults/1.json +96 -0
  24. package/cli/lifecycle/lifecycle.schema.json +121 -0
  25. package/cli/lifecycle.mjs +695 -0
  26. package/cli/next.mjs +34 -11
  27. package/cli/openpr.mjs +81 -5
  28. package/cli/platform.mjs +21 -0
  29. package/cli/pr-list.mjs +49 -3
  30. package/cli/product-index.mjs +6 -3
  31. package/cli/product-token.mjs +186 -0
  32. package/cli/productcommit.mjs +33 -0
  33. package/cli/recommend.mjs +3 -1
  34. package/cli/repo-publish.mjs +2 -2
  35. package/cli/run-checks.mjs +586 -0
  36. package/cli/ship-drift.mjs +384 -0
  37. package/cli/standup.mjs +1 -1
  38. package/cli/status.mjs +282 -0
  39. package/cli/test-build.mjs +1559 -0
  40. package/cli/test-run-checks.mjs +603 -0
  41. package/cli/test-worktree.mjs +520 -0
  42. package/cli/thread.mjs +50 -3
  43. package/cli/tidy.mjs +2 -2
  44. package/cli/toolbox.mjs +36 -5
  45. package/cli/workspace.mjs +4 -1
  46. package/cli/worktree-record.mjs +53 -0
  47. package/cli/worktree.mjs +379 -0
  48. package/package.json +4 -3
  49. package/skills/sdlc/config.yaml +28 -20
  50. package/skills/sdlc/module-help.csv +1 -1
  51. package/skills/yad-backfill/references/backfill.md +8 -1
  52. package/skills/yad-backfill/templates/checks/backfill-check.sh +54 -6
  53. package/skills/yad-change/SKILL.md +3 -0
  54. package/skills/yad-checks/SKILL.md +47 -5
  55. package/skills/yad-checks/references/check-gates.md +124 -12
  56. package/skills/yad-checks/templates/checks/build-test-lint.sh +22 -3
  57. package/skills/yad-checks/templates/checks/commit-message.sh +8 -2
  58. package/skills/yad-checks/templates/checks/contract-check.sh +354 -48
  59. package/skills/yad-checks/templates/checks/epic-open.sh +87 -14
  60. package/skills/yad-checks/templates/checks/ledger-guard.sh +3 -3
  61. package/skills/yad-checks/templates/checks/lineage-check.sh +88 -15
  62. package/skills/yad-checks/templates/checks/member-check.mjs +206 -35
  63. package/skills/yad-checks/templates/checks/package-manager.sh +41 -4
  64. package/skills/yad-checks/templates/checks/product-checkout.sh +161 -13
  65. package/skills/yad-checks/templates/checks/reconcile-debt-check.sh +94 -15
  66. package/skills/yad-checks/templates/checks/risk-map-check.sh +2 -2
  67. package/skills/yad-checks/templates/checks/spec-link.sh +63 -4
  68. package/skills/yad-checks/templates/checks/verified-commits.sh +23 -5
  69. package/skills/yad-checks/templates/github/yad-checks.yml +8 -8
  70. package/skills/yad-checks/templates/gitlab/.gitlab-ci.yml +3 -0
  71. package/skills/yad-checks/templates/gitlab/yad-checks.gitlab-ci.yml +4 -4
  72. package/skills/yad-checks/templates/gitlab/yad-product-checks.gitlab-ci.yml +16 -3
  73. package/skills/yad-checks/templates/gitlab/yad-update-guard.gitlab-ci.yml +5 -1
  74. package/skills/yad-checks/templates/gitlab/yad-verified-commits.gitlab-ci.yml +5 -1
  75. package/skills/yad-commit/SKILL.md +4 -2
  76. package/skills/yad-docs/templates/app/package-lock.json +395 -106
  77. package/skills/yad-docs/templates/app/package.json +2 -2
  78. package/skills/yad-engineer-review/SKILL.md +45 -20
  79. package/skills/yad-engineer-review/references/ship-and-record.md +42 -8
  80. package/skills/yad-epic/references/state-schema.md +83 -20
  81. package/skills/yad-implement/SKILL.md +75 -13
  82. package/skills/yad-implement/references/implement-conventions.md +8 -1
  83. package/skills/yad-implement/templates/.gitmessage +3 -0
  84. package/skills/yad-open-pr/SKILL.md +21 -0
  85. package/skills/yad-pr-template/SKILL.md +6 -2
  86. package/skills/yad-pr-template/templates/checks/pr-template.sh +85 -4
  87. package/skills/yad-pr-template/templates/checks/pr-title.sh +1 -1
  88. package/skills/yad-pr-template/templates/github/pull_request_template.md +1 -1
  89. package/skills/yad-pr-template/templates/gitlab/merge_request_templates/Default.md +1 -1
  90. package/skills/yad-product-bridge/SKILL.md +14 -1
  91. package/skills/yad-product-bridge/references/bridge.md +29 -5
  92. package/skills/yad-product-bridge/templates/gitlab/yad-gate-sync.gitlab-ci.yml +9 -4
  93. package/skills/yad-reconcile/SKILL.md +30 -0
  94. package/skills/yad-review-gate/SKILL.md +8 -2
  95. package/skills/yad-review-gate/references/gating.md +26 -1
  96. package/skills/yad-run/SKILL.md +52 -28
  97. package/skills/yad-run/references/run-loop.md +42 -21
  98. package/skills/yad-spec/SKILL.md +142 -17
  99. package/skills/yad-spec/references/spec-handoff.md +68 -5
  100. package/skills/yad-status/SKILL.md +7 -0
  101. package/skills/yad-stories/references/story-schema.md +1 -1
@@ -43,7 +43,7 @@ const say = (s) => process.stdout.write(`${s}\n`);
43
43
  const fail = (s) => { say(`FAIL [member-check]: ${s}`); rc = 1; };
44
44
  const git = (...args) => {
45
45
  const r = spawnSync('git', args, { encoding: 'utf8', maxBuffer: 1 << 28 });
46
- return { ok: r.status === 0, out: r.stdout || '' };
46
+ return { ok: r.status === 0, out: r.stdout || '', status: r.status };
47
47
  };
48
48
  const hash = (email) => {
49
49
  const e = String(email || '').trim().toLowerCase();
@@ -53,8 +53,8 @@ const parse = (text) => { try { return JSON.parse(text); } catch { return null;
53
53
 
54
54
  // The Product's settings under either name (product.json from 4.0, hub.json before). Drift between the two
55
55
  // is refused by the other gates and the CLI; here the first one found is read.
56
- const settings = parse(fs.existsSync('.sdlc/product.json') ? fs.readFileSync('.sdlc/product.json', 'utf8')
57
- : fs.existsSync('.sdlc/hub.json') ? fs.readFileSync('.sdlc/hub.json', 'utf8') : 'null');
56
+ const settingsFile = ['.sdlc/product.json', '.sdlc/hub.json'].find((f) => fs.existsSync(f)) || null;
57
+ const settings = settingsFile ? parse(fs.readFileSync(settingsFile, 'utf8')) : null;
58
58
  const platform = settings?.platform === 'github' || settings?.platform === 'gitlab' ? settings.platform : null;
59
59
  // The Product's host, from its clone URL (`git@host:…` or `https://host/…`), else the platform's own.
60
60
  function hostOf(url) {
@@ -68,17 +68,125 @@ const productHost = hostOf(settings?.git_url) || hostOf(git('remote', 'get-url',
68
68
  const onProduct = (a) => a?.platform === platform && String(a?.host || '').toLowerCase() === productHost;
69
69
 
70
70
  const base = process.argv[2];
71
- if (!base) { say('FAIL [member-check]: usage: node checks/member-check.mjs <base-ref>'); process.exit(1); }
72
- if (!git('rev-parse', '--verify', '-q', `${base}^{commit}`).ok) { say(`FAIL [member-check]: cannot resolve the base ref ${base} (fetch-depth: 0?)`); process.exit(1); }
71
+ if (!base) { say('FAIL [member-check]: usage: node checks/member-check.mjs <base-ref> — the job must pass the base ref (the branch the PR targets), as yad-product-checks.yml (GitHub) and yad-product-checks.gitlab-ci.yml (GitLab) do'); process.exit(1); }
72
+ if (!git('rev-parse', '--verify', '-q', `${base}^{commit}`).ok) { say(`FAIL [member-check]: cannot resolve the base ref ${base} — check the code out with full history (GitHub: actions/checkout with fetch-depth: 0; GitLab: GIT_DEPTH: "0")`); process.exit(1); }
73
73
 
74
74
  // Every path the PR touches, with its status. NUL-separated, no renames (a rename is a delete plus an add,
75
75
  // and each is judged).
76
- const diff = git('diff', '--no-renames', '--name-status', '-z', `${base}...HEAD`);
77
- if (!diff.ok) { say('FAIL [member-check]: git could not list the changed files'); process.exit(1); }
76
+ //
77
+ // What the PR changes is what MERGING it into the base makes it (#368), read as contract-check reads it
78
+ // (#363 reviews 1, 3-5). A diff from the merge base (`<base>...HEAD`) reads from ONE of several: on a
79
+ // GitLab MR pipeline (the branch tip, not a merge commit), a hand-resolved merge could bring a member file
80
+ // in that the diff never lists. `git merge-tree --write-tree` (git 2.38+) builds the merge without touching
81
+ // anything, and the diff runs from the base to it. A branch that does not merge cleanly fails closed: the
82
+ // platform cannot merge it either. An older git falls back to the one merge base, failing closed when
83
+ // there are several, when the base removed or moved a file the branch changes (the real merge would
84
+ // follow it), when the base has moved on and the branch changes member files, or when the base moved a
85
+ // folder's files into the members folder and the branch adds a file to that folder (a merge that follows
86
+ // folder renames would carry it in). No merge base at all fails closed too.
87
+ const HISTORY = 'check the code out with full history (GitHub: actions/checkout with fetch-depth: 0; GitLab: GIT_DEPTH: "0")';
88
+ const bases = git('merge-base', '--all', base, 'HEAD').out.split('\n').filter(Boolean);
89
+ if (!bases.length) { say(`FAIL [member-check]: '${base}' and HEAD share no history (a shallow clone has no merge base), so the changed files cannot be listed — ${HISTORY}, and give a base this branch shares history with, then run again`); process.exit(1); }
90
+ const built = git('merge-tree', '--write-tree', '--no-messages', base, 'HEAD');
91
+ const mergeTree = built.out.split('\n')[0].trim();
92
+ let from;
93
+ let to;
94
+ if (built.status === 0 && mergeTree && git('rev-parse', '--verify', '-q', `${mergeTree}^{tree}`).ok) {
95
+ from = git('rev-parse', '--verify', '-q', `${base}^{commit}`).out.trim();
96
+ to = mergeTree;
97
+ if (bases.length > 1) say(`note [member-check]: '${base}' and HEAD have ${bases.length} merge bases — the change is read as the merge into ${base} makes it`);
98
+ } else if (built.status === 1) {
99
+ say(`FAIL [member-check]: this branch does not merge cleanly into ${base}, so what it changes there cannot be read — merge ${base} into the branch, resolve the conflicts, then push again`);
100
+ process.exit(1);
101
+ } else if (built.status !== 129) { // 129: git's usage error, which a git older than 2.38 gives for --write-tree (as contract-check reads it)
102
+ say(`FAIL [member-check]: git could not build the merge of this branch into ${base} (git merge-tree exit ${built.status}) — ${HISTORY}, then run again`);
103
+ process.exit(1);
104
+ } else if (bases.length !== 1) {
105
+ say(`FAIL [member-check]: '${base}' and HEAD have ${bases.length} merge bases, and this git (older than 2.38) cannot build the merge into ${base} — merge ${base} into the branch, then push again`);
106
+ process.exit(1);
107
+ } else {
108
+ from = bases[0];
109
+ to = 'HEAD';
110
+ // The fallback reads the branch's own diff, so an edit to a file the base has since removed or moved
111
+ // would follow the rename into the merge unseen: such a path fails closed.
112
+ const names = (r, keep) => { const v = r.out.split('\0').filter(Boolean); const o = []; for (let i = 0; i + 1 < v.length; i += 2) if (keep(v[i][0])) o.push(v[i + 1]); return o; };
113
+ const goneRead = git('diff', '--no-renames', '--diff-filter=D', '--name-status', '-z', from, base);
114
+ const mineRead = git('diff', '--no-renames', '--name-status', '-z', from, 'HEAD');
115
+ if (!goneRead.ok || !mineRead.ok) { say(`FAIL [member-check]: git could not list what changed since this branch split off from ${base} — ${HISTORY}, then run again`); process.exit(1); }
116
+ const gone = new Set(names(goneRead, () => true));
117
+ // Every path, not only member files: a base rename from elsewhere INTO the members folder must be caught.
118
+ if (names(mineRead, (s) => s === 'M' || s === 'T').some((f) => gone.has(f))) {
119
+ say(`FAIL [member-check]: ${base} removed or moved a file this branch changes, and this git (older than 2.38) cannot follow it into the merge — merge ${base} into the branch, then push again`);
120
+ process.exit(1);
121
+ }
122
+ // The rules below read the files as the merge would hold them, and this git reads them at HEAD. Once the
123
+ // base has moved on, the merge can hold member files HEAD does not show: a file both sides changed (review
124
+ // 1), a file the branch renamed in and the base edited at its old path, a file the base added that the clash
125
+ // check must see (review 2). So a branch that changes member files fails closed until it holds the base.
126
+ // Any spelling of the folder counts (the twin rule below names it), read the way a case-blind disk reads it.
127
+ const baseTip = git('rev-parse', '--verify', '-q', `${base}^{commit}`).out.trim();
128
+ const memberish = (f) => f.normalize('NFKC').toLowerCase().startsWith('.sdlc/members');
129
+ if (baseTip !== from && names(mineRead, () => true).some(memberish)) {
130
+ say(`FAIL [member-check]: ${base} has moved on since this branch split off, and this git (older than 2.38) cannot read the member files this branch changes as the merge would hold them — merge ${base} into the branch, then push again`);
131
+ process.exit(1);
132
+ }
133
+ // A folder the base moved into the members folder (its files deleted there, member files added): a merge
134
+ // that follows folder renames (merge.directoryRenames=true) carries a file the branch adds to that folder
135
+ // in as a member file this diff never shows. Git's default makes it a conflict; this closes it either way.
136
+ if (baseTip !== from) {
137
+ const baseRead = git('diff', '--no-renames', '--name-status', '-z', from, base);
138
+ if (!baseRead.ok) { say(`FAIL [member-check]: git could not list what changed since this branch split off from ${base} — ${HISTORY}, then run again`); process.exit(1); }
139
+ // Every folder a path sits in (never the top level, which git never renames).
140
+ const folders = (f) => { const out = []; for (let i = f.indexOf('/'); i > 0; i = f.indexOf('/', i + 1)) out.push(f.slice(0, i)); return out; };
141
+ // Git renames a folder only when it is gone on that side: the folders of the base's deletions, less any
142
+ // the base still holds — a folder that held only subfolders counts too (review 4).
143
+ const stillThere = new Set(git('ls-tree', '-r', '-d', '--name-only', '-z', base).out.split('\0').filter(Boolean));
144
+ const gone = new Set(names(baseRead, (s) => s === 'D').flatMap(folders).filter((d) => !stillThere.has(d)));
145
+ const movedIn = names(baseRead, (s) => s === 'A').some(memberish);
146
+ if (movedIn && gone.size && names(mineRead, (s) => s === 'A').some((f) => folders(f).some((d) => gone.has(d)))) {
147
+ say(`FAIL [member-check]: ${base} moved files into the members folder from a folder this branch adds a file to, and this git (older than 2.38) cannot tell where the merge puts it — merge ${base} into the branch, then push again`);
148
+ process.exit(1);
149
+ }
150
+ }
151
+ }
152
+ const diff = git('diff', '--no-renames', '--name-status', '-z', from, to);
153
+ // Where every rule below reads the files (review 1): what the merge into the base holds — the tree git
154
+ // built, or HEAD on an older git, where any case the merge could hold differently has failed closed above.
155
+ const AT = to;
156
+ if (!diff.ok) { say('FAIL [member-check]: git could not list the changed files — check the code out with full history (GitHub: actions/checkout with fetch-depth: 0; GitLab: GIT_DEPTH: "0"), and give a base this branch shares history with, then run again'); process.exit(1); }
78
157
  const parts = diff.out.split('\0').filter(Boolean);
79
158
  const all = [];
80
159
  for (let i = 0; i + 1 < parts.length; i += 2) all.push({ status: parts[i][0], path: parts[i + 1] });
81
160
 
161
+ // How to take member files out, the one rule every message uses (#381 review 4): a file this PR brings in
162
+ // (not on the base) is dropped from it; one the base holds — even one this PR edits — is deleted with git
163
+ // rm, which any PR may do (a deletion is never refused).
164
+ // "On the base" means the commit the diff above starts from (review 7): the base itself when the merge was
165
+ // built (#368), the one merge base on an older git. The path is read literally, never as a pattern.
166
+ const split = from;
167
+ const modeOnBase = (p) => {
168
+ const t = spawnSync('git', ['--literal-pathspecs', 'ls-tree', '-z', split, '--', p], { encoding: 'utf8' });
169
+ const [meta, at] = (t.status === 0 ? t.stdout : '').split('\0')[0].split('\t');
170
+ return at === p ? meta.slice(0, 6) : null;
171
+ };
172
+ // A FILE there (a folder is not one), and a plain one (not a link).
173
+ const onBase = (p) => { const m = modeOnBase(p); return !!m && m !== '040000'; };
174
+ const plainOnBase = (p) => ['100644', '100755'].includes(modeOnBase(p));
175
+ // A path as a command takes it: shell-quoted unless it is plain (review 5), so a name with a space pastes whole.
176
+ const q = (p) => (/^[A-Za-z0-9._\/@+-]+$/.test(p) ? p : `'${p.replace(/'/g, "'\\''")}'`);
177
+ // How to UNDO this PR's change to one file (review 6) — not to remove it: the base's copy, if the base holds
178
+ // one, comes back; a file only this PR added goes. A teammate's file the PR edited is never deleted by it.
179
+ // The command restores the copy the diff compares against: the base's, or (older git) the merge base's.
180
+ const restoreFrom = to === 'HEAD' ? `${base}...HEAD` : base;
181
+ const undo = (p) => (onBase(p) ? `restore ${q(p)} to the base's copy (git checkout ${q(restoreFrom)} -- ${q(p)})`
182
+ : `drop ${q(p)} from this pull request (git rm it on this branch)`);
183
+ const removal = (paths) => {
184
+ const here = paths.filter((p) => !onBase(p));
185
+ const there = paths.filter(onBase);
186
+ return [...(here.length ? [`drop ${here.map(q).join(' and ')} from this pull request (git rm it on this branch)`] : []),
187
+ ...(there.length ? [`git rm ${there.map(q).join(' ')} (any pull request may delete a member file)`] : [])].join('; ');
188
+ };
189
+
82
190
  // A path as a case-insensitive, Unicode-folding file system sees it: `.sdlc/Members/x` and `.ſdlc/members/x`
83
191
  // land in `.sdlc/members/` on macOS and Windows.
84
192
  // A deletion is never judged here: removing a twin is how one is cleaned up (review 2).
@@ -86,28 +194,59 @@ const fold = (p) => p.normalize('NFKC').toLowerCase();
86
194
  for (const { status, path } of all) {
87
195
  if (status === 'D') continue;
88
196
  const f = fold(path);
89
- if ((f === '.sdlc' || f.startsWith('.sdlc/')) && !(path === '.sdlc' || path.startsWith('.sdlc/'))) fail(`${JSON.stringify(path)} is another spelling of .sdlc/ — a macOS or Windows checkout reads it as the Product's own folder, unjudged`);
90
- else if ((f === '.sdlc/members' || f.startsWith(DIR)) && !path.startsWith(DIR)) fail(`${JSON.stringify(path)} is another spelling of ${DIR} — a macOS or Windows checkout reads it as a member file this gate does not judge`);
197
+ if ((f === '.sdlc' || f.startsWith('.sdlc/')) && !(path === '.sdlc' || path.startsWith('.sdlc/'))) fail(`${JSON.stringify(path)} is another spelling of .sdlc/, which a macOS or Windows checkout reads as the Product's own folder, unjudged — move it into the real .sdlc/ folder (git mv), or delete it`);
198
+ // `.sdlc/members` itself, a link where the folder goes, is the folder check's below, not a second spelling.
199
+ else if ((f === '.sdlc/members' || f.startsWith(DIR)) && !path.startsWith(DIR) && path !== '.sdlc/members') fail(`${JSON.stringify(path)} is another spelling of ${DIR}, which a macOS or Windows checkout reads as a member file this gate does not judge — move it into the real ${DIR} folder (git mv), or delete it`);
91
200
  }
92
- // The folders themselves must be folders at HEAD, and nothing under them a link.
201
+ // The folders themselves must be folders in the merge, and nothing under them a link.
93
202
  for (const p of ['.sdlc', '.sdlc/members']) {
94
- const t = git('ls-tree', 'HEAD', '--', p).out.trim();
95
- if (t && !t.startsWith('040000 ')) fail(`${p} is not a folder at HEAD (a link?) — member files are read only from a real ${DIR}`);
203
+ const t = git('ls-tree', AT, '--', p).out.trim();
204
+ if (t && !t.startsWith('040000 ')) fail(`${p} is not a folder in this change (a link?), and member files are read only from a real ${DIR} — replace it with a real folder that holds the files themselves`);
205
+ }
206
+ // Names of one file (twins): keep ONE per group, take every other out (reviews 4-6). Kept first: a plain file
207
+ // (a link is refused in this same run), then a copy the base holds (a new one was meant as another file),
208
+ // then the ASCII lower-case name `yad member add` writes. Nothing is renamed: taking the others out clears the clash. When this PR
209
+ // brings in that lower-case name beside a base copy, it may be its person's own `yad member add` run — the
210
+ // message says how to keep it instead.
211
+ const lowerName = (p) => { const n = p.slice(p.lastIndexOf('/') + 1); return n === n.toLowerCase() && /^[\x20-\x7e]*$/.test(n); };
212
+ function twins(group) {
213
+ const old = group.filter((g) => onBase(g.path));
214
+ const rank = (g) => (g.plain ? 0 : 2) + (lowerName(g.path) ? 0 : 1);
215
+ // A link is refused in this same run, so it is kept only when every name is one (review 6).
216
+ const plain = group.filter((g) => g.plain);
217
+ const pick = plain.length ? plain : group;
218
+ const pickOld = pick.filter((g) => old.includes(g));
219
+ const keep = [...(pickOld.length ? pickOld : pick)].sort((x, y) => rank(x) - rank(y))[0].path;
220
+ const own = old.length ? group.find((g) => !old.includes(g) && g.plain && lowerName(g.path) && g.path !== keep) : null;
221
+ const instead = own ? `; or, if ${q(own.path)} is your own file as yad member add writes it, keep it and ${removal(group.filter((g) => g !== own).map((g) => g.path))}` : '';
222
+ fail(`${group.map((g) => g.path).join(' and ')} are one file on macOS and Windows — keep ${q(keep)}: ${removal(group.filter((g) => g.path !== keep).map((g) => g.path))}${instead}`);
96
223
  }
97
- const tree = git('ls-tree', '-r', '-z', 'HEAD', '--', DIR).out.split('\0').filter(Boolean);
224
+ const tree = git('ls-tree', '-r', '-z', AT, '--', DIR).out.split('\0').filter(Boolean);
98
225
  const folded = new Map();
99
226
  for (const line of tree) {
100
227
  const [meta, p] = line.split('\t');
101
- if (!meta.startsWith('100644 ') && !meta.startsWith('100755 ')) fail(`${p} is not a plain file (a link?) — a member file is never read through one`);
228
+ const plain = meta.startsWith('100644 ') || meta.startsWith('100755 ');
229
+ // Where the base held a plain file, this PR's link is undone, never deleted: a deletion passes, and would
230
+ // remove that person (review 7). A link the base already held was never read, so deleting it loses nothing.
231
+ const linkFix = plainOnBase(p) ? undo(p) : onBase(p) ? `replace it with the file itself, or git rm it: the gate never read it, so nothing is lost`
232
+ : `replace it with the file itself (yad member add writes it), or ${undo(p)}`;
233
+ if (!plain) fail(`${p} is not a plain file (a link?), and a member file is never read through one — ${linkFix}`);
102
234
  const k = fold(p);
103
- if (folded.has(k)) fail(`${p} and ${folded.get(k)} are one file on macOS and Windows — keep one`);
104
- folded.set(k, p);
235
+ folded.set(k, [...(folded.get(k) || []), { path: p, plain }]);
105
236
  }
237
+ for (const group of folded.values()) if (group.length > 1) twins(group);
106
238
  if (rc) process.exit(rc);
107
239
 
108
240
  const changed = all.filter((c) => c.path.startsWith(DIR));
109
241
  if (!changed.length) { say('PASS [member-check]: no member file changed'); process.exit(0); }
110
- if (!platform) { say('FAIL [member-check]: member files changed, but the Product names no platform — nothing can be proven'); process.exit(1); }
242
+ // Where to set it: the file the gate read, or the one `yad setup` writes when there is none (review 1).
243
+ if (!platform) {
244
+ const fix = !settingsFile ? 'there is no .sdlc/product.json: run yad setup in the Product, or write the file with "platform" ("github" or "gitlab")'
245
+ : !settings || typeof settings !== 'object' || Array.isArray(settings) ? `${settingsFile} is not valid JSON or not an object: fix it, and set "platform" ("github" or "gitlab") in it`
246
+ : `set "platform" ("github" or "gitlab") in ${settingsFile}`;
247
+ say(`FAIL [member-check]: member files changed, but the Product names no platform, so nothing can be proven — ${fix}`);
248
+ process.exit(1);
249
+ }
111
250
 
112
251
  // Who opened the PR/MR, asked of the platform's own record.
113
252
  // Returns { login, id }: the numeric id is what stays with a person when a login is renamed and reused.
@@ -118,20 +257,40 @@ async function prAuthor() {
118
257
  const iid = process.env.CI_MERGE_REQUEST_IID;
119
258
  const token = process.env.GITLAB_TOKEN || process.env.SDLC_API_TOKEN;
120
259
  if (!url || !project || !iid) return null;
121
- if (!token) { fail('no API token (GITLAB_TOKEN or SDLC_API_TOKEN) to read who opened this MR — a member file cannot be checked without it; add the token as a masked CI/CD variable'); return null; }
260
+ if (!token) { fail('no API token (GITLAB_TOKEN or SDLC_API_TOKEN) to read who opened this MR — a member file cannot be checked without it; add a GITLAB_TOKEN masked CI/CD variable with the read_api scope, whose user can see the project'); return null; }
122
261
  try {
123
262
  const r = await fetch(`${url}/projects/${encodeURIComponent(project)}/merge_requests/${encodeURIComponent(iid)}`, { headers: { 'PRIVATE-TOKEN': token } });
124
- if (!r.ok) { fail(`could not read the MR (HTTP ${r.status})`); return null; }
263
+ // What to change, by what GitLab answered, as pr-template says it (#381). Only a refusal is the
264
+ // token's fault; anything else is said as it is, with no advice to change the token.
265
+ if (!r.ok) {
266
+ const name = process.env.GITLAB_TOKEN ? 'GITLAB_TOKEN' : 'SDLC_API_TOKEN';
267
+ const why = {
268
+ 401: `${name} was not accepted (expired, revoked, or not a valid token here) — renew or replace it`,
269
+ 403: `${name} was refused — give it the read_api scope`,
270
+ 404: `${name}'s user cannot see this project — use a token of a project member with Reporter access or more`,
271
+ }[r.status] || 'GitLab did not answer with the MR — run the job again later';
272
+ fail(`could not read the MR (HTTP ${r.status}): ${why}`);
273
+ return null;
274
+ }
125
275
  const mr = await r.json();
126
276
  return { login: mr?.author?.username || null, id: Number(mr?.author?.id) || null };
127
- } catch (e) { fail(`could not read the MR: ${e.message}`); return null; }
277
+ } catch (e) { fail(`could not read the MR: ${e.message} — check that CI_API_V4_URL (${url}) is reachable from the runner and answers as GitLab's API, then run the job again`); return null; }
128
278
  }
129
279
 
130
280
  const who = await prAuthor();
131
281
  if (rc) process.exit(rc);
132
282
  const author = who?.login || null;
133
283
  const authorId = who?.id || null;
134
- if (!author || !LOGIN_RE.test(author)) { say(`FAIL [member-check]: cannot tell who opened this ${platform === 'github' ? 'PR' : 'MR'}${author ? ` (${author} is a bot)` : ''} — a member file is changed only by its own person`); process.exit(1); }
284
+ // Two causes, each with its own fix (#381): the job did not say who opened it, or a bot did.
285
+ if (!author || !LOGIN_RE.test(author)) {
286
+ const what = platform === 'github' ? 'PR' : 'MR';
287
+ const fix = author ? `a member file is changed only by its own person: open the ${what} as that person`
288
+ : platform === 'github' ? 'the job must pass PR_AUTHOR and PR_AUTHOR_ID from the pull_request event (github.event.pull_request.user.login and .id), as yad-product-checks.yml does'
289
+ : who ? 'the merge request API named no author; run the job again'
290
+ : 'run the job in a merge request pipeline, which sets CI_API_V4_URL, CI_PROJECT_ID and CI_MERGE_REQUEST_IID, as yad-product-checks.gitlab-ci.yml does';
291
+ say(`FAIL [member-check]: cannot tell who opened this ${what}${author ? ` (${author} is a bot)` : ''} — ${fix}`);
292
+ process.exit(1);
293
+ }
135
294
 
136
295
  const fileAt = (ref, path) => { const r = git('show', `${ref}:${path}`); return r.ok ? parse(r.out) : null; };
137
296
  const emailsOf = (rec) => new Set(Array.isArray(rec?.emails) ? rec.emails.filter((h) => typeof h === 'string' && HASH_RE.test(h)) : []);
@@ -146,41 +305,45 @@ function githubLogin(sha) {
146
305
  return login;
147
306
  }
148
307
 
308
+ // The fix for a file that is not the author's own as `yad member add` writes it.
309
+ // It pushes its own branch (yad/member/<login>) and PR, so the file is dropped from any other PR.
310
+ const again = (p) => `write the file again with yad member add, run by its own person (it opens its own pull request); if this is another pull request, ${undo(p)}`;
311
+
149
312
  const prCommits = git('log', '--format=%H%x1f%ae', `${base}..HEAD`).out.split('\n').filter(Boolean).map((l) => { const [sha, email] = l.split('\x1f'); return { sha, hash: hash(email) }; });
150
313
 
151
314
  for (const { status, path } of changed) {
152
315
  const name = path.slice(DIR.length);
153
316
  if (status === 'D') { say(`PASS [member-check]: ${path} removed (removing a member can only make the count larger)`); continue; }
154
- if (name.includes('/') || !name.endsWith('.json')) { fail(`${path}: only <platform>-<login>.json files belong in ${DIR}`); continue; }
155
- if (name !== `${platform}-${author.toLowerCase()}.json`) { fail(`${path}: a PR may add or change only its author's own member file (${platform}-${author.toLowerCase()}.json) — use \`yad member remove <login> --reason\` to remove someone else's`); continue; }
156
- const rec = fileAt('HEAD', path);
157
- if (!rec || !Array.isArray(rec.accounts)) { fail(`${path}: not a member file (no "accounts" list)`); continue; }
317
+ if (name.includes('/') || !name.endsWith('.json')) { fail(`${path}: only <platform>-<login>.json files belong in ${DIR} — move it to ${DIR}${platform}-<login>.json, or remove it`); continue; }
318
+ if (name !== `${platform}-${author.toLowerCase()}.json`) { fail(`${path}: a PR may add or change only its author's own member file (${platform}-${author.toLowerCase()}.json) — ${undo(path)}, and change only ${platform}-${author.toLowerCase()}.json, which yad member add writes. To remove someone else, use yad member remove <login> --reason "<why>" in a pull request of its own`); continue; }
319
+ const rec = fileAt(AT, path);
320
+ if (!rec || !Array.isArray(rec.accounts)) { fail(`${path}: not a member file (no "accounts" list) — ${again(path)}`); continue; }
158
321
  const here = rec.accounts.filter(onProduct);
159
- if (here.length !== 1) { fail(`${path}: must hold exactly one ${platform} account on ${productHost}, the author's own (it holds ${here.length})`); continue; }
160
- if (String(here[0].login || '').toLowerCase() !== author.toLowerCase()) { fail(`${path}: does not hold ${author}'s own ${platform} account on ${productHost}`); continue; }
322
+ if (here.length !== 1) { fail(`${path}: must hold exactly one ${platform} account on ${productHost}, the author's own (it holds ${here.length}) — ${again(path)}`); continue; }
323
+ if (String(here[0].login || '').toLowerCase() !== author.toLowerCase()) { fail(`${path}: does not hold ${author}'s own ${platform} account on ${productHost} — ${again(path)}`); continue; }
161
324
  // The numeric id: a login can be renamed away and registered again by someone else.
162
- if (!authorId) { fail(`${path}: cannot tell the numeric id of who opened this ${platform === 'github' ? 'PR (PR_AUTHOR_ID)' : 'MR'}`); continue; }
163
- if (here[0].id !== authorId) { fail(`${path}: the account id in the file (${here[0].id ?? 'none'}) is not the author's (${authorId})`); continue; }
325
+ if (!authorId) { fail(`${path}: cannot tell the numeric id of who opened this ${platform === 'github' ? 'PR (PR_AUTHOR_ID) — the job must pass PR_AUTHOR_ID from the pull_request event (github.event.pull_request.user.id), as yad-product-checks.yml does' : 'MR — the merge request API gave no author id; run the job again'}`); continue; }
326
+ if (here[0].id !== authorId) { fail(`${path}: the account id in the file (${here[0].id ?? 'none'}) is not the author's (${authorId}) — ${again(path)}`); continue; }
164
327
  const was = fileAt(base, path);
165
328
  const wasHere = Array.isArray(was?.accounts) ? was.accounts.filter(onProduct) : [];
166
- if (wasHere.length && wasHere[0].id !== authorId) { fail(`${path}: belonged to account id ${wasHere[0].id}, not ${author}'s (${authorId}) — a reused login does not take over a member file; remove it first`); continue; }
329
+ if (wasHere.length && wasHere[0].id !== authorId) { fail(`${path}: belonged to account id ${wasHere[0].id}, not ${author}'s (${authorId}), and a reused login does not take over a member file — remove the old file first with yad member remove ${author.toLowerCase()} --reason "<why>", in a pull request of its own`); continue; }
167
330
  if (platform !== 'github') { say(`PASS [member-check]: ${path} belongs to ${author} (on GitLab its emails feed the team list only)`); continue; }
168
331
  // EVERY email in a changed file is proven, not only the new ones (review 5): an email that reached the
169
332
  // branch while this gate was off or edited would otherwise ride along on any later change.
170
333
  const added = [...emailsOf(rec)];
171
334
  for (const h of added) {
172
335
  const proof = prCommits.filter((c) => c.hash === h).find((c) => String(githubLogin(c.sha) || '').toLowerCase() === author.toLowerCase());
173
- if (!proof) fail(`${path}: holds an email no commit in this PR proves — GitHub must attribute a commit authored by that email to ${author} (\`yad member add\` writes one such commit per email; verify the email on the account)`);
336
+ if (!proof) fail(`${path}: holds an email no commit in this PR proves (a commit authored by that email that GitHub attributes to ${author}) — verify the email on ${author}'s account, then run yad member add, which writes one such commit per email`);
174
337
  }
175
338
  if (!rc) say(`PASS [member-check]: ${path} belongs to ${author}${added.length ? `; ${added.length} email(s), each proven by a commit GitHub attributes to them` : ''}`);
176
339
  }
177
340
 
178
- // No account on the Product's platform and no email in two files, across every member file at HEAD.
341
+ // No account on the Product's platform and no email in two files, across every member file in the merge.
179
342
  const files = tree.map((l) => l.split('\t')[1]).filter((p) => p.endsWith('.json'));
180
343
  const accounts = new Map();
181
344
  const emails = new Map();
182
345
  for (const p of files) {
183
- const rec = fileAt('HEAD', p);
346
+ const rec = fileAt(AT, p);
184
347
  // Keyed on each file's OWN account only (review 2): an OTHER account two files claim is not refused here —
185
348
  // the CLI matches it to nobody — or whoever claimed someone's account first would block its owner.
186
349
  const login = p.slice(DIR.length).replace(new RegExp(`^${platform}-`), '').replace(/\.json$/, '');
@@ -188,10 +351,18 @@ for (const p of files) {
188
351
  accounts.set(k, [...new Set([...(accounts.get(k) || []), p])]);
189
352
  for (const h of emailsOf(rec)) emails.set(h, [...(emails.get(h) || []), p]);
190
353
  }
191
- for (const [k, list] of accounts) if (list.length > 1) fail(`the account ${k} is in ${list.join(' and ')} — one account belongs to one member`);
354
+ // The key comes from the file NAME, and two well-named files that share one are twins, refused above. So a
355
+ // clash here is a file named other than <platform>-<login>.json — which `yad member remove` cannot reach:
356
+ // it removes the well-named one (review 1).
357
+ const named = (p) => new RegExp(`^${platform}-[^/]+\\.json$`).test(p.slice(DIR.length));
358
+ const STALE = 'remove a stale file with yad member remove <login> --reason "<why>"';
359
+ // A misnamed file in a clash is taken out by `removal` (review 3, 4); `STALE` only when none is misnamed —
360
+ // two well-named files with one key are twins, refused above, so for accounts it is a guard, not a path today.
361
+ const misnamed = (list) => { const odd = list.filter((p) => !named(p)); return odd.length ? `${removal(odd)}. Only ${platform}-<login>.json files are member files` : null; };
362
+ for (const [k, list] of accounts) if (list.length > 1) fail(`the account ${k} is in ${list.join(' and ')}, and one account belongs to one member — ${misnamed(list) || STALE}`);
192
363
  // On GitLab an email is never proven and never used by the count, so a shared one is not refused: refusing it
193
364
  // would let whoever listed someone's known address first block that person (review 3). The CLI pairs it
194
365
  // with nobody.
195
- if (platform === 'github') for (const [, list] of emails) if (list.length > 1) fail(`one email is in ${list.join(' and ')} — one email belongs to one member`);
366
+ if (platform === 'github') for (const [, list] of emails) if (list.length > 1) fail(`one email is in ${list.join(' and ')}, and one email belongs to one member — ${misnamed(list) || `remove it from the file it does not belong in (that file's own person runs yad member add again, which keeps only the emails their account has verified), or ${STALE}`}`);
196
367
 
197
368
  process.exit(rc);
@@ -85,11 +85,43 @@ yad_package_manager_spec() {
85
85
  # shellcheck disable=SC2016
86
86
  node --input-type=module -e '
87
87
  import fs from "node:fs";
88
- let pkg;
88
+ // Characters that must never reach the CI log as they are: control characters (an ESC starts a
89
+ // terminal colour code), line and paragraph separators, text-direction marks (U+202E shows the
90
+ // rest of the line backwards) and zero-width characters. The same list as cli/detect.mjs UNSAFE.
91
+ const UNSAFE = /[\u0000-\u001f\u007f-\u009f\u061c\u200b-\u200f\u2028\u2029\u202a-\u202e\u2060-\u2064\u2066-\u2069\ufeff]/;
92
+ let text, pkg;
89
93
  // npm strips a UTF-8 byte-order mark before parsing (Windows editors often write one); do the same
90
94
  // so a manifest npm itself installs from is not rejected here.
91
- try { pkg = JSON.parse(fs.readFileSync("package.json", "utf8").replace(/^\uFEFF/, "")); }
92
- catch { process.stderr.write("FAIL [package-manager]: package.json is not valid JSON.\n"); process.exit(1); }
95
+ try { text = fs.readFileSync("package.json", "utf8").replace(/^\uFEFF/, ""); }
96
+ catch (error) {
97
+ process.stderr.write(`FAIL [package-manager]: package.json could not be read (${String(error.code ?? error.message).replace(new RegExp(`${UNSAFE.source}+`, "g"), " ")}) — let the CI user read the file.\n`);
98
+ process.exit(1);
99
+ }
100
+ try { pkg = JSON.parse(text); }
101
+ catch (error) {
102
+ // The parser message can quote bytes of the file: control characters and line separators become
103
+ // spaces and it is cut short, so a crafted package.json cannot start a second line in the CI log.
104
+ // Node words the place as "… in JSON at position N" or "… after JSON at position N"; Node 22+
105
+ // adds its own "(line X column Y)", which is dropped so every Node line prints the same text.
106
+ // Read only at the end of the message: an "Unexpected token" message quotes the file, and the
107
+ // file could hold the words "at position".
108
+ const place = / at position (\d+)(?: \(line \d+ column \d+\))?$/;
109
+ const position = place.exec(error.message);
110
+ const reason = error.message.replace(place, "").replace(/ in JSON$/, "")
111
+ .replace(new RegExp(`${UNSAFE.source}+`, "g"), " ").trim().slice(0, 200);
112
+ let where = "";
113
+ if (position) {
114
+ // JSON allows CRLF, LF and a bare CR between values; an editor counts each as a new line.
115
+ const lines = text.slice(0, Number(position[1])).split(/\r\n|\r|\n/);
116
+ const line = lines.length;
117
+ // Counted in characters, not UTF-16 units, so an emoji is one column, as in an editor.
118
+ const column = [...lines[line - 1]].length + 1;
119
+ where = ` at line ${line}, column ${column}`;
120
+ }
121
+ const fix = where ? "fix package.json at that place" : "fix package.json; the parser message says what it found";
122
+ process.stderr.write(`FAIL [package-manager]: package.json is not valid JSON${where} (${reason}) — ${fix}.\n`);
123
+ process.exit(1);
124
+ }
93
125
  if (pkg === null || typeof pkg !== "object" || Array.isArray(pkg)) {
94
126
  process.stderr.write("FAIL [package-manager]: package.json must be a JSON object.\n"); process.exit(1);
95
127
  }
@@ -97,7 +129,12 @@ yad_package_manager_spec() {
97
129
  process.stderr.write("FAIL [package-manager]: packageManager must be a string.\n"); process.exit(1);
98
130
  }
99
131
  if (pkg.packageManager && /[\r\n]/.test(pkg.packageManager)) {
100
- process.stderr.write(`FAIL [package-manager]: packageManager ${JSON.stringify(pkg.packageManager)} must name an exact semantic version.\n`);
132
+ process.stderr.write("FAIL [package-manager]: packageManager holds a line break — remove it, so the value is one line like pnpm@9.15.0.\n");
133
+ process.exit(1);
134
+ }
135
+ // The value is printed in later messages, so an UNSAFE character in it is refused.
136
+ if (pkg.packageManager && UNSAFE.test(pkg.packageManager)) {
137
+ process.stderr.write("FAIL [package-manager]: packageManager holds an invisible or control character — remove it, so the value is plain text like pnpm@9.15.0.\n");
101
138
  process.exit(1);
102
139
  }
103
140
  process.stdout.write(pkg.packageManager || "");