yadflow 4.6.0 → 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 (96) hide show
  1. package/CHANGELOG.md +170 -0
  2. package/README.md +4 -1
  3. package/bin/commands.mjs +5 -1
  4. package/bin/yad.mjs +167 -15
  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 +357 -9
  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 +364 -22
  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/next.mjs +34 -11
  23. package/cli/openpr.mjs +81 -5
  24. package/cli/platform.mjs +21 -0
  25. package/cli/pr-list.mjs +5 -3
  26. package/cli/product-index.mjs +6 -3
  27. package/cli/product-token.mjs +186 -0
  28. package/cli/productcommit.mjs +33 -0
  29. package/cli/recommend.mjs +3 -1
  30. package/cli/repo-publish.mjs +2 -2
  31. package/cli/run-checks.mjs +586 -0
  32. package/cli/ship-drift.mjs +49 -18
  33. package/cli/standup.mjs +1 -1
  34. package/cli/status.mjs +282 -0
  35. package/cli/test-build.mjs +1559 -0
  36. package/cli/test-run-checks.mjs +603 -0
  37. package/cli/test-worktree.mjs +520 -0
  38. package/cli/thread.mjs +4 -0
  39. package/cli/tidy.mjs +2 -2
  40. package/cli/toolbox.mjs +36 -5
  41. package/cli/workspace.mjs +4 -1
  42. package/cli/worktree-record.mjs +53 -0
  43. package/cli/worktree.mjs +379 -0
  44. package/package.json +3 -3
  45. package/skills/sdlc/config.yaml +1 -1
  46. package/skills/sdlc/module-help.csv +1 -1
  47. package/skills/yad-backfill/templates/checks/backfill-check.sh +9 -9
  48. package/skills/yad-change/SKILL.md +3 -0
  49. package/skills/yad-checks/SKILL.md +34 -5
  50. package/skills/yad-checks/references/check-gates.md +69 -10
  51. package/skills/yad-checks/templates/checks/build-test-lint.sh +22 -3
  52. package/skills/yad-checks/templates/checks/commit-message.sh +8 -2
  53. package/skills/yad-checks/templates/checks/contract-check.sh +61 -33
  54. package/skills/yad-checks/templates/checks/epic-open.sh +87 -14
  55. package/skills/yad-checks/templates/checks/ledger-guard.sh +3 -3
  56. package/skills/yad-checks/templates/checks/lineage-check.sh +88 -15
  57. package/skills/yad-checks/templates/checks/member-check.mjs +206 -35
  58. package/skills/yad-checks/templates/checks/package-manager.sh +41 -4
  59. package/skills/yad-checks/templates/checks/product-checkout.sh +161 -13
  60. package/skills/yad-checks/templates/checks/reconcile-debt-check.sh +94 -15
  61. package/skills/yad-checks/templates/checks/risk-map-check.sh +2 -2
  62. package/skills/yad-checks/templates/checks/spec-link.sh +63 -4
  63. package/skills/yad-checks/templates/checks/verified-commits.sh +23 -5
  64. package/skills/yad-checks/templates/github/yad-checks.yml +8 -8
  65. package/skills/yad-checks/templates/gitlab/.gitlab-ci.yml +3 -0
  66. package/skills/yad-checks/templates/gitlab/yad-checks.gitlab-ci.yml +4 -4
  67. package/skills/yad-checks/templates/gitlab/yad-product-checks.gitlab-ci.yml +16 -3
  68. package/skills/yad-checks/templates/gitlab/yad-update-guard.gitlab-ci.yml +5 -1
  69. package/skills/yad-checks/templates/gitlab/yad-verified-commits.gitlab-ci.yml +5 -1
  70. package/skills/yad-commit/SKILL.md +4 -2
  71. package/skills/yad-docs/templates/app/package-lock.json +395 -106
  72. package/skills/yad-docs/templates/app/package.json +2 -2
  73. package/skills/yad-engineer-review/SKILL.md +45 -20
  74. package/skills/yad-engineer-review/references/ship-and-record.md +42 -8
  75. package/skills/yad-epic/references/state-schema.md +75 -16
  76. package/skills/yad-implement/SKILL.md +75 -13
  77. package/skills/yad-implement/references/implement-conventions.md +8 -1
  78. package/skills/yad-implement/templates/.gitmessage +3 -0
  79. package/skills/yad-open-pr/SKILL.md +21 -0
  80. package/skills/yad-pr-template/SKILL.md +6 -2
  81. package/skills/yad-pr-template/templates/checks/pr-template.sh +85 -4
  82. package/skills/yad-pr-template/templates/checks/pr-title.sh +1 -1
  83. package/skills/yad-pr-template/templates/github/pull_request_template.md +1 -1
  84. package/skills/yad-pr-template/templates/gitlab/merge_request_templates/Default.md +1 -1
  85. package/skills/yad-product-bridge/SKILL.md +14 -1
  86. package/skills/yad-product-bridge/references/bridge.md +5 -2
  87. package/skills/yad-product-bridge/templates/gitlab/yad-gate-sync.gitlab-ci.yml +9 -4
  88. package/skills/yad-reconcile/SKILL.md +9 -3
  89. package/skills/yad-review-gate/SKILL.md +4 -0
  90. package/skills/yad-review-gate/references/gating.md +26 -1
  91. package/skills/yad-run/SKILL.md +52 -28
  92. package/skills/yad-run/references/run-loop.md +42 -21
  93. package/skills/yad-spec/SKILL.md +137 -16
  94. package/skills/yad-spec/references/spec-handoff.md +50 -3
  95. package/skills/yad-status/SKILL.md +7 -0
  96. package/skills/yad-stories/references/story-schema.md +1 -1
@@ -27,7 +27,7 @@ product_config() {
27
27
  if [ -n "${SDLC_PRODUCT_CONFIG:-}" ]; then printf '%s' "$SDLC_PRODUCT_CONFIG"; return 0; fi
28
28
  if [ -n "${SDLC_HUB_CONFIG:-}" ]; then printf '%s' "$SDLC_HUB_CONFIG"; return 0; fi
29
29
  if [ -f .sdlc/product.json ] && [ -f .sdlc/hub.json ] && ! cmp -s .sdlc/product.json .sdlc/hub.json; then
30
- echo "FAIL [product-settings]: .sdlc/product.json and .sdlc/hub.json say different things — they are one file under two names until v5. Run \`yad migrate\` in the Product to choose the copy to keep, and commit both." >&2
30
+ echo "FAIL [product-settings]: .sdlc/product.json and .sdlc/hub.json say different things — they are one file under two names until v5. In the Product, run \`yad migrate --apply --keep product\` (or \`--keep hub\`) to choose the copy to keep, then commit both files." >&2
31
31
  return 1
32
32
  fi
33
33
  if [ -f .sdlc/product.json ]; then printf '%s' .sdlc/product.json; else printf '%s' .sdlc/hub.json; fi
@@ -60,7 +60,7 @@ BASE="${1:-${SDLC_BASE:-$(resolve_base)}}"
60
60
  [ -n "${1:-}" ] || [ -n "${SDLC_BASE:-}" ] || echo "note [lineage-check]: no base given — diffing against '${BASE}'."
61
61
 
62
62
  if ! git rev-parse --verify --quiet "${BASE}^{commit}" >/dev/null; then
63
- echo "FAIL [lineage-check]: base ref '${BASE}' not found — fetch full history / check the base branch."
63
+ echo "FAIL [lineage-check]: base ref '${BASE}' not found — check the code out with full history (GitHub: actions/checkout with fetch-depth: 0; GitLab: GIT_DEPTH: \"0\"), and give a base that names a fetched branch (the first argument, or SDLC_BASE)."
64
64
  exit 1
65
65
  fi
66
66
  RANGE="${BASE}..HEAD"
@@ -135,7 +135,7 @@ record_path() {
135
135
  }
136
136
  product_for() {
137
137
  _link="specs/$1/link.md"
138
- prod=""; prod_note=""; prod_fail=""
138
+ prod=""; prod_note=""; prod_fail=""; _fix_where="product-repo in specs/$1/link.md"; _fix_when=""; _src="product-repo"; _fix_eg="../../.yad/product, from the story's folder"
139
139
  yad_tmp # here, in this shell: a $(…) below would set it, and its EXIT trap, in a subshell only
140
140
  product_rel="$(link_val product-repo "$_link")"
141
141
  _from="$_link"
@@ -188,6 +188,17 @@ SIBLINGS
188
188
  }${_link} names product-repo '${product_rel}', but ${_from} on ${BASE} says '${_base_rel}' — the Product is read from the base value; a new one counts once it merges."
189
189
  product_rel="$_base_rel"
190
190
  fi
191
+ # What a failure below tells the person to change (#351): the source that was read. Only on a first
192
+ # spec (the base names no Product) is it this PR's own link.md, which counts at once; anything else is
193
+ # read from the base, so a change to it counts only after it merges.
194
+ if [ -n "$_use_rec" ]; then
195
+ _src="path '${_rec}' in .sdlc/product-link.json"; _fix_eg=".yad/product, from the repo root"
196
+ _fix_where="path in .sdlc/product-link.json"; _fix_when=", and merge that change on its own first: a value counts once ${BASE} has it"
197
+ elif [ -n "$_base_rel" ]; then
198
+ _fix_where="product-repo in ${_from}"; _fix_when=", and merge that change on its own first: a value counts once ${BASE} has it"
199
+ else
200
+ _fix_where="product-repo in ${_link}"; _fix_when=" in this pull request"
201
+ fi
191
202
  # A Product this repo keeps, asked of the base first (see above). Both joins resolve_product may pick.
192
203
  case "$product_rel" in
193
204
  '') _cands="" ;;
@@ -217,7 +228,7 @@ CANDS
217
228
  case "$prod" in /*) _pc="$prod" ;; *) _pc="./$prod" ;; esac
218
229
  _phys="$(cd -P "$_pc" 2>/dev/null && pwd -P)" || _phys=""
219
230
  if [ -z "$_phys" ]; then
220
- prod_fail="product-repo resolves to '${prod}', a folder the gate cannot enter to check where it really is — so it is not read."
231
+ prod_fail="${_src} resolves to '${prod}', a folder the gate cannot enter to check where it really is — so it is not read. Point ${_fix_where} at a folder the job can read${_fix_when}."
221
232
  return 0
222
233
  fi
223
234
  # Not inside this repo's own git folder (review 7). git never lists `.git/` as tracked, yet a PR
@@ -230,7 +241,7 @@ CANDS
230
241
  _p="$_phys"
231
242
  while :; do
232
243
  if [ "$_p" -ef "$_gd" ]; then
233
- prod_fail="product-repo resolves to '${prod}', inside this repo's own git folder — what is there is git's, shaped by branch names, not a Product."
244
+ prod_fail="${_src} resolves to '${prod}', inside this repo's own git folder — what is there is git's, shaped by branch names, not a Product. Point ${_fix_where} at the Product checkout (${_fix_eg})${_fix_when}."
234
245
  return 0
235
246
  fi
236
247
  case "$_p" in /|'') break ;; esac
@@ -262,15 +273,18 @@ CANDS
262
273
  $_kept
263
274
  KEPT
264
275
  [ -n "$_kept_here" ] || return 0
265
- if [ -n "$product_rel" ]; then _what="product-repo '${product_rel}' reaches nothing"; else _what="link.md names no product-repo"; fi
276
+ if [ -n "$_use_rec" ]; then _what="path '${_rec}' in .sdlc/product-link.json reaches nothing"
277
+ elif [ -n "$product_rel" ]; then _what="product-repo '${product_rel}' reaches nothing"; else _what="link.md names no product-repo"; fi
266
278
  if [ "$(printf '%s' "$_kept_here" | grep -c .)" -gt 1 ]; then
267
- prod_fail="${_what}, and ${BASE} keeps more than one Product holding ${_epic_of} ($(printf '%s' "$_kept_here" | tr '\n' ' ' | sed -E 's/ +$//')) — the gate cannot tell which is meant."
279
+ prod_fail="${_what}, and ${BASE} keeps more than one Product holding ${_epic_of} ($(printf '%s' "$_kept_here" | tr '\n' ' ' | sed -E 's/ +$//')) — the gate cannot tell which is meant. Set ${_fix_where} to one of them${_fix_when}."
268
280
  return 0
269
281
  fi
270
282
  _k="$(printf '%s' "$_kept_here" | head -1)"
271
283
  prod_note="${prod_note:+$prod_note
272
284
  }${_what} here; the Product this repo keeps at '${_k}' on ${BASE} holds ${_epic_of}, so that one is read."
273
285
  product_rel="$_k"
286
+ # The value read did not resolve to it: the gate picked it. Say so in what base_product prints.
287
+ _src="${_what}, so the Product this repo keeps"
274
288
  [ "$_k" != . ] || _k=""
275
289
  base_product "$_k"
276
290
  return 0
@@ -282,12 +296,12 @@ KEPT
282
296
  tracked_verdict() {
283
297
  case "$1" in
284
298
  entry:*)
285
- prod_fail="product-repo reaches the Product through '${1#*:}', a symlink, submodule or file this repo tracks — what is behind it is this PR's to choose. Point product-repo at the Product itself."
299
+ prod_fail="${_src} reaches the Product through '${1#*:}', a symlink, submodule or file this repo tracks — what is behind it is this PR's to choose. Point ${_fix_where} at the Product itself${_fix_when}."
286
300
  return 0 ;;
287
301
  tree:*)
288
302
  _r="${1#*:}"
289
303
  if git cat-file -e "${BASE}:${_r:+$_r/}.sdlc/product.json" 2>/dev/null || git cat-file -e "${BASE}:${_r:+$_r/}.sdlc/hub.json" 2>/dev/null; then base_product "$_r"; return 0; fi
290
- prod_fail="product-repo resolves to '${_r:-.}', which holds files this repo tracks, but ${BASE} does not track '${_r:+$_r/}.sdlc/product.json' (or the older hub.json) there, so it is not a Product kept in this repo. Untrack those files (git rm -r --cached '${_r:-.}') or point product-repo at the Product."
304
+ prod_fail="${_src} resolves to '${_r:-.}', which holds files this repo tracks, but ${BASE} does not track '${_r:+$_r/}.sdlc/product.json' (or the older hub.json) there, so it is not a Product kept in this repo. Untrack those files (git rm -r --cached '${_r:-.}'), or point ${_fix_where} at the Product${_fix_when}."
291
305
  return 0 ;;
292
306
  esac
293
307
  return 1
@@ -320,7 +334,7 @@ KEPT
320
334
  base_product() {
321
335
  _r="$1"; _e="${_r:+$_r/}epics"
322
336
  if [ "$(git cat-file -t "${BASE}:${_e}" 2>/dev/null)" != tree ]; then
323
- prod_fail="product-repo resolves to '${_r:-.}', a Product this repo keeps, and ${BASE} has no '${_e}' folder — there is nothing on the base to read."
337
+ prod_fail="${_src} resolves to '${_r:-.}', a Product this repo keeps, and ${BASE} has no '${_e}' folder — there is nothing on the base to read. Merge that Product's epics into ${BASE} first, or point ${_fix_where} at the Product checkout${_fix_when}."
324
338
  return 0
325
339
  fi
326
340
  # (awk reads to the end rather than stopping at the first hit: stopping left `tr` writing into a
@@ -349,7 +363,7 @@ base_product() {
349
363
  GIT_INDEX_FILE="${_arch_dir}.idx" git ls-files -z -- ':(glob)**/.gitattributes' |
350
364
  GIT_INDEX_FILE="${_arch_dir}.idx" xargs -0 git update-index --force-remove -- &&
351
365
  GIT_WORK_TREE="${_arch_dir}/${_e}" GIT_INDEX_FILE="${_arch_dir}.idx" git checkout-index -a -f; } >/dev/null 2>&1; then
352
- prod_fail="product-repo resolves to '${_r:-.}', a Product this repo keeps, and '${_e}' could not be read from ${BASE}."
366
+ prod_fail="${_src} resolves to '${_r:-.}', a Product this repo keeps, and '${_e}' could not be read from ${BASE} — run the job again; if it repeats, check the code out with full history and no partial-clone filter (GitHub: actions/checkout with fetch-depth: 0; GitLab: GIT_DEPTH: \"0\")."
353
367
  return 0
354
368
  fi
355
369
  _arch_key="x$_r"
@@ -442,6 +456,61 @@ resolve_product() {
442
456
  esac
443
457
  }
444
458
 
459
+ # --- shared SHA exemption (byte-identical in spec-link / lineage-check / epic-open / reconcile-debt-check;
460
+ # --- the gates are deliberately standalone, so it is duplicated, not sourced) ---
461
+ # A commit already on a shared branch cannot be reworded without rewriting that branch, so one bad trailer
462
+ # would fail every later PR whose range still holds it — and a release PR to the default branch walks the
463
+ # whole release, so it fails again on every release until that commit reaches the base. `.sdlc/gate-exempt`
464
+ # names such commits, one full SHA per line, `#` comments allowed; every per-commit gate passes
465
+ # them, so a commit is waived once, in a reviewed change, instead of on every pipeline. A listed commit
466
+ # skips EVERY check of the gate, not only its trailer's — a sealed epic or a frozen thread included. SDLC_GATE_EXEMPT
467
+ # names another path in the repo. It comes from the pipeline config, which a PR may change where the PR's
468
+ # own pipeline runs; it still names a file on the BASE whose every entry must be a full SHA, so it cannot
469
+ # list the PR's own commits — and a PR that changes the pipeline could drop the gates anyway, which
470
+ # required checks and branch protection, not this script, prevent. The list is read from the BASE, never from this PR — a PR that could
471
+ # list its own commits would wave itself past every gate; an entry counts once it merges. An entry must be
472
+ # a FULL hex SHA: git reads 40 hex characters (64 in a SHA-256 repo) as a commit, but looks a short one up as a tag or branch name
473
+ # first — so a tag named like a listed short SHA would stand in for another commit, and a short SHA also
474
+ # grows ambiguous as the repo grows. An entry that is not one, or names no commit here, exempts nothing;
475
+ # both are said as notes, so a typo is visible.
476
+ GATE_EXEMPT_FILE="${SDLC_GATE_EXEMPT:-.sdlc/gate-exempt}"
477
+ exempt_shas=''
478
+ load_exempt_shas() {
479
+ # Three dots: against the merge base, so a base that moved on is not mistaken for this PR's change.
480
+ # Only exit 1 means "it changed"; an error (no merge base) says nothing about the file.
481
+ _ex_rc=0
482
+ git diff --quiet "${BASE}...HEAD" -- "$GATE_EXEMPT_FILE" 2>/dev/null || _ex_rc=$?
483
+ if [ "$_ex_rc" -eq 1 ]; then
484
+ echo "note [$1]: ${GATE_EXEMPT_FILE} changes in this PR — the list is read from ${BASE}, not from this PR; the new one counts once it merges."
485
+ fi
486
+ git cat-file -e "${BASE}:${GATE_EXEMPT_FILE}" 2>/dev/null || return 0
487
+ _ex_list="$(git show "${BASE}:${GATE_EXEMPT_FILE}" 2>/dev/null | sed -E 's/#.*//; s/^[[:space:]]+//; s/[[:space:]]+$//')" || _ex_list=""
488
+ while IFS= read -r _ex; do
489
+ [ -z "$_ex" ] && continue
490
+ case "$_ex" in
491
+ *[!0123456789abcdef]*) echo "note [$1]: ${GATE_EXEMPT_FILE} entry '${_ex}' is not a lowercase hex SHA — it exempts nothing." ; continue ;;
492
+ esac
493
+ if [ "${#_ex}" -ne 40 ] && [ "${#_ex}" -ne 64 ]; then
494
+ echo "note [$1]: ${GATE_EXEMPT_FILE} entry '${_ex}' is not a full SHA (40 characters, or 64 in a SHA-256 repo) — it exempts nothing (a short one could be taken over by a tag or branch of that name)."
495
+ continue
496
+ fi
497
+ _ex_full="$(git rev-parse --verify --quiet "${_ex}^{commit}" 2>/dev/null)" || _ex_full=""
498
+ # Only an entry git reads back as exactly itself: hex of the other hash's length (64 in a SHA-1 repo,
499
+ # 40 in a SHA-256 one) is looked up as a tag or branch name first, so a ref of that name would stand in;
500
+ # and an annotated tag's own SHA peels to its commit's — the list names commits, as rev-list walks them.
501
+ if [ -z "$_ex_full" ] || [ "$_ex_full" != "$_ex" ]; then
502
+ echo "note [$1]: ${GATE_EXEMPT_FILE} entry '${_ex}' is not the full SHA of a commit here — it exempts nothing."
503
+ continue
504
+ fi
505
+ exempt_shas="${exempt_shas}${_ex_full}
506
+ "
507
+ done <<EXEMPT_LIST
508
+ $_ex_list
509
+ EXEMPT_LIST
510
+ }
511
+ is_exempt_sha() { [ -n "$exempt_shas" ] && printf '%s' "$exempt_shas" | grep -qxF "$1"; }
512
+ load_exempt_shas lineage-check
513
+
445
514
  commits="$(git rev-list --no-merges "$RANGE")"
446
515
  if [ -z "$commits" ]; then
447
516
  echo "PASS [lineage-check]: no non-merge commits in ${RANGE}"
@@ -454,6 +523,10 @@ while IFS= read -r sha; do
454
523
  short="$(git log -1 --format=%h "$sha")"
455
524
  subject="$(git log -1 --format=%s "$sha")"
456
525
  task="$(git log -1 --format='%(trailers:key=Task,valueonly)' "$sha" | awk '!f && length($0) { print; f = 1 }')"
526
+ if is_exempt_sha "$sha"; then
527
+ echo "PASS [lineage-check]: ${short} '${subject}' — SHA exemption (${GATE_EXEMPT_FILE} on ${BASE})"
528
+ continue
529
+ fi
457
530
  # The type exemption waives the REQUIREMENT for an owning epic, not the VALIDITY of one that is
458
531
  # claimed — same rule spec-link applies. Exempting on the subject alone would let `chore(x): …` plus
459
532
  # a Task trailer pointing at an orphaned/sealed epic bypass this gate entirely.
@@ -479,7 +552,7 @@ while IFS= read -r sha; do
479
552
  fi
480
553
  epic="$(link_val epic "$link")"
481
554
  if [ -z "$epic" ]; then
482
- echo "FAIL [lineage-check]: ${short} ${task} — link.md has no 'epic:' (cannot place it in a thread)."
555
+ echo "FAIL [lineage-check]: ${short} ${task} — ${link} has no 'epic:' (cannot place it in a thread). Set epic: $(story_epic "$story") in it: a story's epic is the prefix of its id."
483
556
  rc=1
484
557
  continue
485
558
  fi
@@ -504,7 +577,7 @@ while IFS= read -r sha; do
504
577
  continue
505
578
  fi
506
579
  if [ ! -f "$epicmd" ]; then
507
- echo "FAIL [lineage-check]: ${short} ${task} -> epic ${epic} does not exist in the product repo (orphan story link)."
580
+ echo "FAIL [lineage-check]: ${short} ${task} -> epic ${epic} does not exist in the product repo (orphan story link). Check the story id in the Task trailer; if ${epic} is new, merge its Shape review PRs into the Product's default branch first."
508
581
  rc=1
509
582
  continue
510
583
  fi
@@ -531,12 +604,12 @@ while IFS= read -r sha; do
531
604
  # A change/defect/hotfix epic MUST thread to a real parent.
532
605
  parent="$(fm_val parent "$epicmd")"
533
606
  if [ -z "$parent" ]; then
534
- echo "FAIL [lineage-check]: ${short} ${task} -> ${epic} is type:${wtype} but declares no 'parent:' — a change-epic must thread to its predecessor."
607
+ echo "FAIL [lineage-check]: ${short} ${task} -> ${epic} is type:${wtype} but declares no 'parent:' — a change-epic must thread to its predecessor. Add parent: <the epic it changes> to epics/${epic}/epic.md in the Product, through its review PR (the yad-change skill writes it); \`yad thread\` lists the threads."
535
608
  rc=1
536
609
  continue
537
610
  fi
538
611
  if [ ! -f "${prod}/epics/${parent}/epic.md" ]; then
539
- echo "FAIL [lineage-check]: ${short} ${task} -> ${epic} threads to '${parent}', but epics/${parent}/ does not exist in the Product (orphan thread)."
612
+ echo "FAIL [lineage-check]: ${short} ${task} -> ${epic} threads to '${parent}', but epics/${parent}/ does not exist in the Product (orphan thread). Fix parent: in epics/${epic}/epic.md to an epic the Product has, or merge ${parent}'s Shape review PRs into the Product's default branch first."
540
613
  rc=1
541
614
  continue
542
615
  fi
@@ -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);