yadflow 4.9.0 → 4.11.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 (155) hide show
  1. package/CHANGELOG.md +184 -0
  2. package/README.md +15 -5
  3. package/bin/commands.mjs +11 -1
  4. package/bin/yad.mjs +203 -14
  5. package/cli/agent-guard-worker.mjs +13 -0
  6. package/cli/agent-guard.mjs +1797 -73
  7. package/cli/agent-rules.mjs +64 -5
  8. package/cli/argv-flags.mjs +2 -2
  9. package/cli/brain/vendor/LICENSE-graphology-library.txt +21 -0
  10. package/cli/brain/vendor/LICENSE-graphology.txt +21 -0
  11. package/cli/brain/vendor/LICENSE-sigma.txt +12 -0
  12. package/cli/brain/vendor/graphology-library.min.js +2 -0
  13. package/cli/brain/vendor/graphology.umd.min.js +2 -0
  14. package/cli/brain/vendor/sigma.min.js +1369 -0
  15. package/cli/brain/view/app.js +382 -0
  16. package/cli/brain/view/index.html +63 -0
  17. package/cli/brain/view/live.css +228 -0
  18. package/cli/brain/view/live.html +110 -0
  19. package/cli/brain/view/live.js +884 -0
  20. package/cli/brain/view/style.css +141 -0
  21. package/cli/brain-about.mjs +206 -0
  22. package/cli/brain-activity.mjs +285 -0
  23. package/cli/brain-skills.mjs +118 -0
  24. package/cli/brain-vendor.mjs +71 -0
  25. package/cli/brain-view.mjs +344 -0
  26. package/cli/brain.mjs +810 -0
  27. package/cli/ci-check.mjs +48 -4
  28. package/cli/codeowners-command.mjs +72 -6
  29. package/cli/commit.mjs +17 -3
  30. package/cli/docs.mjs +2 -0
  31. package/cli/doctor.mjs +151 -25
  32. package/cli/epic-state.mjs +186 -4
  33. package/cli/epic.mjs +26 -10
  34. package/cli/errors.mjs +2 -1
  35. package/cli/find-product.mjs +69 -15
  36. package/cli/fold.mjs +31 -6
  37. package/cli/foundation-publish.mjs +256 -0
  38. package/cli/gate.mjs +29 -3
  39. package/cli/git-read.mjs +38 -0
  40. package/cli/guard-stream.mjs +409 -0
  41. package/cli/guide.mjs +3 -1
  42. package/cli/hook.mjs +102 -9
  43. package/cli/issue-links.mjs +61 -0
  44. package/cli/issues-act.mjs +371 -0
  45. package/cli/issues-write.mjs +441 -0
  46. package/cli/issues.mjs +513 -0
  47. package/cli/lib.mjs +37 -2
  48. package/cli/lifecycle.mjs +7 -0
  49. package/cli/local-page.mjs +138 -0
  50. package/cli/machine.mjs +1 -1
  51. package/cli/manifest.mjs +59 -3
  52. package/cli/map/view/app.js +712 -0
  53. package/cli/map/view/index.html +50 -0
  54. package/cli/map/view/style.css +142 -0
  55. package/cli/map-view.mjs +186 -0
  56. package/cli/map.mjs +637 -0
  57. package/cli/members.mjs +9 -15
  58. package/cli/next.mjs +1 -1
  59. package/cli/openpr.mjs +26 -6
  60. package/cli/plan.mjs +127 -0
  61. package/cli/platform.mjs +159 -4
  62. package/cli/product-index.mjs +1 -1
  63. package/cli/protection.mjs +53 -3
  64. package/cli/reconcile.mjs +9 -3
  65. package/cli/report.mjs +9 -3
  66. package/cli/reports-dir.mjs +391 -0
  67. package/cli/reports.mjs +65 -0
  68. package/cli/run-checks.mjs +15 -4
  69. package/cli/scan.mjs +314 -0
  70. package/cli/setup.mjs +42 -8
  71. package/cli/standup.mjs +120 -78
  72. package/cli/status.mjs +6 -5
  73. package/cli/story-frames.mjs +17 -6
  74. package/cli/test-agents-file.mjs +985 -12
  75. package/cli/test-brain-activity.mjs +753 -0
  76. package/cli/test-brain-view.mjs +381 -0
  77. package/cli/test-brain.mjs +795 -0
  78. package/cli/test-build.mjs +25 -0
  79. package/cli/test-ci-check.mjs +469 -10
  80. package/cli/test-guide.mjs +218 -0
  81. package/cli/test-machine.mjs +59 -0
  82. package/cli/test-map.mjs +615 -0
  83. package/cli/test-node.mjs +15 -0
  84. package/cli/test-reports.mjs +382 -0
  85. package/cli/test-run-checks.mjs +21 -0
  86. package/cli/test-setup-agent.mjs +14 -0
  87. package/cli/test-story-frames.mjs +74 -4
  88. package/cli/test-worktree.mjs +24 -3
  89. package/cli/toolbox-connect.mjs +259 -0
  90. package/cli/toolbox.mjs +187 -12
  91. package/cli/update-commit.mjs +101 -9
  92. package/cli/usage.mjs +8 -4
  93. package/package.json +12 -4
  94. package/skills/sdlc/config.yaml +1 -1
  95. package/skills/sdlc/module-help.csv +3 -1
  96. package/skills/yad-analysis/SKILL.md +4 -0
  97. package/skills/yad-architecture/SKILL.md +22 -4
  98. package/skills/yad-backfill/SKILL.md +4 -0
  99. package/skills/yad-change/SKILL.md +7 -1
  100. package/skills/yad-change/references/triage.md +2 -0
  101. package/skills/yad-checks/SKILL.md +15 -7
  102. package/skills/yad-checks/references/check-gates.md +70 -35
  103. package/skills/yad-checks/templates/checks/build-test-lint.sh +7 -0
  104. package/skills/yad-checks/templates/checks/install-deps.sh +6 -0
  105. package/skills/yad-checks/templates/checks/member-check.mjs +3 -2
  106. package/skills/yad-checks/templates/checks/package-manager.sh +42 -0
  107. package/skills/yad-checks/templates/checks/risk-map-check.sh +2 -2
  108. package/skills/yad-checks/templates/checks/verified-commits.sh +3 -3
  109. package/skills/yad-checks/templates/github/yad-checks.yml +358 -69
  110. package/skills/yad-checks/templates/github/yad-pr-text.yml +118 -0
  111. package/skills/yad-checks/templates/github/yad-product-checks.yml +130 -54
  112. package/skills/yad-checks/templates/github/yad-product-pr-text.yml +131 -0
  113. package/skills/yad-checks/templates/github/yad-update-guard.yml +2 -1
  114. package/skills/yad-checks/templates/github/yad-verified-commits.yml +49 -3
  115. package/skills/yad-checks/templates/gitlab/yad-checks.gitlab-ci.yml +80 -20
  116. package/skills/yad-checks/templates/gitlab/yad-product-checks.gitlab-ci.yml +59 -9
  117. package/skills/yad-checks/templates/gitlab/yad-update-guard.gitlab-ci.yml +1 -0
  118. package/skills/yad-checks/templates/gitlab/yad-verified-commits.gitlab-ci.yml +49 -1
  119. package/skills/yad-checks/templates/hooks/agent-guard.mjs +44 -10
  120. package/skills/yad-checks/templates/hooks/ledger-guard-cursor.mjs +12 -6
  121. package/skills/yad-checks/templates/hooks/yad-activity.mjs +238 -0
  122. package/skills/yad-commit/SKILL.md +3 -1
  123. package/skills/yad-connect-design/SKILL.md +42 -10
  124. package/skills/yad-connect-design/references/design-context.md +35 -5
  125. package/skills/yad-connect-design/references/design-registry.md +3 -3
  126. package/skills/yad-connect-learning/SKILL.md +12 -2
  127. package/skills/yad-connect-repos/SKILL.md +18 -0
  128. package/skills/yad-connect-testing/SKILL.md +22 -5
  129. package/skills/yad-connect-testing/references/testing-context.md +1 -1
  130. package/skills/yad-discovery/SKILL.md +11 -0
  131. package/skills/yad-discovery/references/foundation-schema.md +11 -0
  132. package/skills/yad-docs/templates/app/package-lock.json +18 -10
  133. package/skills/yad-docs/templates/app/package.json +6 -1
  134. package/skills/yad-epic/SKILL.md +7 -0
  135. package/skills/yad-epic/references/state-schema.md +50 -1
  136. package/skills/yad-guide/SKILL.md +8 -4
  137. package/skills/yad-implement/SKILL.md +117 -4
  138. package/skills/yad-implement/references/implement-conventions.md +2 -1
  139. package/skills/yad-issues/SKILL.md +54 -0
  140. package/skills/yad-learn/SKILL.md +4 -0
  141. package/skills/yad-open-pr/SKILL.md +6 -0
  142. package/skills/yad-pr-template/SKILL.md +2 -1
  143. package/skills/yad-pr-template/templates/checks/pr-template.sh +8 -4
  144. package/skills/yad-pr-template/templates/checks/pr-title.sh +42 -6
  145. package/skills/yad-product-bridge/references/bridge.md +28 -0
  146. package/skills/yad-product-bridge/templates/github/yad-gate-sync.yml +25 -11
  147. package/skills/yad-product-bridge/templates/gitlab/yad-gate-sync.gitlab-ci.yml +38 -14
  148. package/skills/yad-run/SKILL.md +5 -0
  149. package/skills/yad-scan/SKILL.md +51 -0
  150. package/skills/yad-spec/SKILL.md +32 -2
  151. package/skills/yad-stories/SKILL.md +22 -4
  152. package/skills/yad-stories/references/story-schema.md +1 -1
  153. package/skills/yad-test-cases/SKILL.md +18 -2
  154. package/skills/yad-ui/SKILL.md +43 -8
  155. package/skills/yad-checks/templates/gitlab/.gitlab-ci.yml +0 -49
package/cli/ci-check.mjs CHANGED
@@ -22,7 +22,7 @@ import fs from 'node:fs';
22
22
  import path from 'node:path';
23
23
  import { c, log, ok, warn, fail, info, hand, run, exists, readJSON, isPlainObject, forTerminal, asArg } from './lib.mjs';
24
24
  import { REQUIRED_CHECKS, REPO_WIRING, PRODUCT_WIRING, PROJECT_FILES, PRODUCT_LINK, productConfigPath, isVerifiedLedger } from './manifest.mjs';
25
- import { readCiSettings, protectionLine } from './protection.mjs';
25
+ import { readCiSettings, protectionLine, configuredGitUrl } from './protection.mjs';
26
26
  import { repoActions, productActions } from './plan.mjs';
27
27
  import { judgeRepo, runnable } from './workspace.mjs';
28
28
  import { isSolo } from './gate.mjs';
@@ -223,10 +223,12 @@ function rowIds(t, platform, solo) {
223
223
  return [
224
224
  'protected',
225
225
  ...(t.ciRuns ? ['required-checks'] : []),
226
- ...(platform === 'gitlab' && t.ciRuns ? ['skipped-pipelines'] : []),
226
+ ...(platform === 'gitlab' && t.ciRuns ? ['skipped-pipelines', 'merge-trains'] : []),
227
+ ...(platform !== 'gitlab' && t.ciRuns ? ['merge-queue', 'up-to-date'] : []),
227
228
  ...(platform === 'gitlab' && !(t.kind === 'product' && t.ciRuns) ? ['direct-push'] : []),
228
229
  'force-push', 'deletion',
229
230
  ...(!solo ? ['stale-approvals'] : []),
231
+ ...(platform === 'gitlab' && !solo ? ['author-approval', 'committer-approval'] : []),
230
232
  ...(platform === 'gitlab' ? ['discussions'] : []),
231
233
  ...(t.kind === 'code' || t.ciRuns ? ['signed-commits'] : []),
232
234
  ];
@@ -302,6 +304,25 @@ function githubRows(add, root, t, s, { branch, web, rulesPage, settings, solo, p
302
304
  if (!missing.length) add('required-checks', 'ok', `all ${jobs.length} of yad's checks must pass before a merge (who is on a ruleset's bypass list is not read${adminsFree ? '; classic protection lets admins bypass them' : ''})`);
303
305
  else if (why) add('required-checks', 'unknown', `not seen as required: ${missing.join(', ')} (${why})`, settings(rulesPage, steps));
304
306
  else add('required-checks', 'gap', `not required before a merge: ${missing.join(', ')} — a pull request can merge with these failing`, settings(rulesPage, steps));
307
+
308
+ // #433: yad's checks start on pull_request only, and judge the range from the PR's base. A merge queue
309
+ // waits for checks on its own merge_group runs, which never come, and each queue entry also holds the PRs
310
+ // ahead of it. Real support is E166. GraphQL answers for a queue set by a ruleset or by classic protection;
311
+ // a ruleset's merge_queue rule proves one too, when GraphQL could not be read.
312
+ const byRule = inRules(s, (r) => r?.type === 'merge_queue');
313
+ const queue = s.mergeQueue === 'on' || byRule === true ? true : s.mergeQueue === 'off' ? false : null;
314
+ const queueStep = `Turn off "Require merge queue" for ${branch}, in the branch ruleset or in classic branch protection (${web}/settings/branches): yad's checks do not run in a merge queue yet.`;
315
+ if (queue === true) add('merge-queue', 'gap', `the merge queue is on for ${branch}: yad's checks do not run in it, so a queued pull request is dropped from the queue when its checks time out — or, once they run there, is judged together with the pull requests ahead of it`, settings(rulesPage, [queueStep]));
316
+ else if (queue === false) add('merge-queue', 'ok', `no merge queue is on for ${branch}`);
317
+ else add('merge-queue', 'unknown', 'not known whether a merge queue is on (it could not be read through GitHub\'s GraphQL API)', settings(rulesPage, [queueStep]));
318
+
319
+ // #433: "Require branches to be up to date" runs the checks again when the base moves, so the gates that read
320
+ // the base's state (the contract lock, the open epics, the risk map) judge the base the PR merges into.
321
+ const strict = either(inRules(s, (r) => r?.type === 'required_status_checks' && r.parameters?.strict_required_status_checks_policy === true),
322
+ inClassic(s, (cl) => (isPlainObject(cl.required_status_checks) ? cl.required_status_checks.strict === true : false)));
323
+ const strictStep = 'In the branch ruleset\'s status checks rule, turn on "Require branches to be up to date before merging".';
324
+ if (strict === true) add('up-to-date', 'ok', 'a pull request must be up to date with the base before it merges, so the checks judge the base it merges into');
325
+ else add('up-to-date', 'suggest', strict === false ? 'a pull request can merge without being up to date: the checks that read the base (the contract lock, open epics, the risk map) may have judged an older base' : `not known whether a pull request must be up to date before it merges (${why})`, settings(rulesPage, [strictStep]));
305
326
  }
306
327
 
307
328
  const row = (id, ruleType, classicKey, okText, gapText, unknownText, step) => {
@@ -345,6 +366,19 @@ function gitlabRows(add, t, s, { branch, rulesPage, mrPage, settings, solo }) {
345
366
  if (skipped === false) add('skipped-pipelines', 'ok', 'a skipped pipeline does not count as passed');
346
367
  else if (skipped === true) add('skipped-pipelines', 'gap', 'a skipped pipeline counts as passed, so a merge can skip yad\'s checks', settings(mrPage, [skipStep]));
347
368
  else add('skipped-pipelines', 'unknown', `not known whether a skipped pipeline counts as passed (${unread})`, settings(mrPage, [skipStep]));
369
+
370
+ // #433: a merge train's pipeline runs on the MRs ahead of it too, while yad's checks judge the range from the
371
+ // target branch, so they would judge those MRs' commits as this one's. Real support is E166. The setting is
372
+ // GitLab Premium. A train needs merged-results pipelines, so either one reported off proves no train; a
373
+ // project that reports neither is GitLab Free, or a login that cannot see them: not known.
374
+ const trains = !pr ? null : bool(pr.merge_trains_enabled) ?? (pr.merge_pipelines_enabled === false ? false : null);
375
+ const trainStep = 'Merge requests → Merge options → turn off "Enable merge trains" (yad\'s checks do not run in a merge train yet).';
376
+ if (trains === true) add('merge-trains', 'gap', 'merge trains are on: yad\'s checks would judge the merge requests ahead in the train as part of this one', settings(mrPage, [trainStep]));
377
+ else if (trains === false) add('merge-trains', 'ok', 'merge trains are off');
378
+ else add('merge-trains', 'unknown', `not known whether merge trains are on (${pr ? 'the project does not report the setting: it needs GitLab Premium, or your login cannot see it' : unread})`, settings(mrPage, [trainStep]));
379
+ // Merged-results pipelines run on a merge commit GitLab makes, which the gates judge like a normal run.
380
+ const merged = pr ? bool(pr.merge_pipelines_enabled) : null;
381
+ if (merged !== null) add('merged-results', 'ok', merged ? 'merged-results pipelines are on: yad\'s checks support them' : 'merged-results pipelines are off (yad\'s checks support them if you turn them on)');
348
382
  }
349
383
 
350
384
  // The project's protected-branch entries for this branch. In a person's own namespace they are the whole
@@ -391,6 +425,16 @@ function gitlabRows(add, t, s, { branch, rulesPage, mrPage, settings, solo }) {
391
425
  const step = 'Merge request approvals → turn on "Remove all approvals when commits are added to the source branch".';
392
426
  if (reset === true) add('stale-approvals', 'ok', 'approvals are removed when new commits are added');
393
427
  else add('stale-approvals', 'suggest', reset === false ? 'approvals stay when new commits are added' : 'not known whether approvals are removed on a new push (the approval settings need GitLab Premium, or could not be read)', settings(mrPage, [step]));
428
+ // #433: an approval counts toward the rule only when it comes from someone other than who wrote the change.
429
+ const premium = 'the approval settings need GitLab Premium, or could not be read';
430
+ const author = bool(s.approvals?.merge_requests_author_approval);
431
+ const authorStep = 'Merge request approvals → Approval settings → turn on "Prevent approval by author" (named "Prevent approval by merge request creator" on some GitLab versions).';
432
+ if (author === false) add('author-approval', 'ok', 'the author of a merge request cannot approve it');
433
+ else add('author-approval', 'suggest', author === true ? 'the author of a merge request can approve it' : `not known whether the author can approve their own merge request (${premium})`, settings(mrPage, [authorStep]));
434
+ const committer = bool(s.approvals?.merge_requests_disable_committers_approval);
435
+ const committerStep = 'Merge request approvals → Approval settings → turn on "Prevent approvals by users who add commits".';
436
+ if (committer === true) add('committer-approval', 'ok', 'someone who added commits to a merge request cannot approve it');
437
+ else add('committer-approval', 'suggest', committer === false ? 'someone who added commits to a merge request can approve it' : `not known whether someone who added commits can approve (${premium})`, settings(mrPage, [committerStep]));
394
438
  }
395
439
  const disc = bool(pr?.only_allow_merge_if_all_discussions_are_resolved);
396
440
  const discStep = 'Merge checks → turn on "All threads must be resolved".';
@@ -430,7 +474,7 @@ export function ciTargets(root, { repo = null } = {}) {
430
474
  const onDisk = typeof entry.path === 'string' && entry.path && runnable(judgeRepo(root, entry));
431
475
  return {
432
476
  name: entry.name, kind: 'code', entry, ciRuns: true,
433
- target: { platform: entry.platform || null, gitUrl: (typeof entry.git_url === 'string' && entry.git_url) || (onDisk ? origin(path.resolve(root, entry.path)) : null), branch: branchOf(entry) },
477
+ target: { platform: entry.platform || null, gitUrl: configuredGitUrl(entry.git_url, () => (onDisk ? origin(path.resolve(root, entry.path)) : null)) || null, branch: branchOf(entry) },
434
478
  };
435
479
  };
436
480
  if (repo !== null) {
@@ -442,7 +486,7 @@ export function ciTargets(root, { repo = null } = {}) {
442
486
  name: 'Product', kind: 'product', wired, ciRuns: wired,
443
487
  // The verified ledger asked for, by its name or its older spellings, whether or not a platform is set.
444
488
  wantsVerified: config.ledger === 'verified' || (typeof config.ledger !== 'string' && (config.bridge_enabled === true || config.bridge === true)),
445
- target: { platform: config.platform || null, gitUrl: config.git_url || origin(root), branch: branchOf(config) },
489
+ target: { platform: config.platform || null, gitUrl: configuredGitUrl(config.git_url, () => origin(root)) || null, branch: branchOf(config) },
446
490
  };
447
491
  return { targets: [product, ...entries.map(code)] };
448
492
  }
@@ -8,6 +8,9 @@
8
8
  // Two kinds of answer, kept apart:
9
9
  // FACTS — a line that matches no file, a GitHub file of 3 MB or more, a second file the platform never
10
10
  // reads, a line this reader cannot read. `yad doctor` prints these too.
11
+ // And (#426) the gate files no line gives an owner: checks/ and every CI file. A PR can change what a
12
+ // gate does through them, so the advice is a CODEOWNERS rule plus a required Code Owner review. yad still
13
+ // never writes that rule: it prints the lines to add (`unguardedHint`).
11
14
  // A HINT — the @logins with no commit in the last 90 days that carries their noreply address. Only a
12
15
  // hint: a person may commit under a work address. Printed by this command only, never by the doctor,
13
16
  // and only where a noreply address is evidence (a github.com or gitlab.com remote).
@@ -15,8 +18,8 @@ import { spawnSync } from 'node:child_process';
15
18
  import fs from 'node:fs';
16
19
 
17
20
  import { c, fail, hand, info, log, ok, run, warn, emitJSON } from './lib.mjs';
18
- import { deadLines, diskCodeowners, parseCodeowners } from './codeowners.mjs';
19
- import { OWNER_WINDOW, recentLoginsFor, repoFiles, targets } from './riskmap-command.mjs';
21
+ import { deadLines, diskCodeowners, ownersFor, parseCodeowners } from './codeowners.mjs';
22
+ import { OWNER_WINDOW, gitEnv, recentLoginsFor, repoFiles, targets } from './riskmap-command.mjs';
20
23
  import { PUBLIC_HOST, remoteHost } from './openpr.mjs';
21
24
  import { detectPlatform } from './platform.mjs';
22
25
 
@@ -32,6 +35,48 @@ function submodulesOf(repoRoot) {
32
35
  return r.stdout.split('\0').filter((l) => l.startsWith('160000 ')).map((l) => l.slice(l.indexOf('\t') + 1));
33
36
  }
34
37
 
38
+ // #426 — the files that decide what a gate does on a PR: every gate script under checks/, and EVERY CI file
39
+ // for this platform — not only yad's. A required check is matched by job name, so a PR could add its own
40
+ // workflow with a job named `spec-link` that passes; on GitLab the root .gitlab-ci.yml decides what is
41
+ // included at all. Only in a repo where yad's gates are installed (a file in checks/, or a yad-* CI file): a
42
+ // repo connected for code context alone has no gate to guard. Tracked files only, as the platform sees them;
43
+ // null when git cannot list them.
44
+ export const GATE_CI_LINES = { github: ['/.github/workflows/'], gitlab: ['/.gitlab-ci.yml', '/.gitlab/ci/'] };
45
+ function gateFiles(repoRoot, platform) {
46
+ const paths = platform === 'gitlab' ? ['checks', '.gitlab-ci.yml', '.gitlab/ci'] : ['checks', '.github/workflows'];
47
+ const r = spawnSync('git', ['ls-files', '-z', '--', ...paths], { cwd: repoRoot, encoding: 'utf8', maxBuffer: 1 << 30, env: gitEnv() });
48
+ if (r.status !== 0) return null;
49
+ const all = r.stdout.split('\0').filter(Boolean);
50
+ const checks = all.filter((f) => f.startsWith('checks/'));
51
+ const ci = all.filter((f) => !f.startsWith('checks/'));
52
+ if (!checks.length && !ci.some((f) => /(^|\/)yad-[^/]*\.ya?ml$/.test(f))) return { checks: [], ci: [] };
53
+ return { checks, ci };
54
+ }
55
+ // The gate files with no owner whose review the platform can require: no line matches, the last match lists
56
+ // no owner, or (GitLab) only an `^[optional]` section names one. With no CODEOWNERS (`parsed` null), all.
57
+ function unguardedOf(g, parsed) {
58
+ const owned = (f) => !!parsed && ownersFor(parsed, [f]).owners.some((o) => !o.optional);
59
+ const checks = g.checks.filter((f) => !owned(f));
60
+ const ci = g.ci.filter((f) => !owned(f));
61
+ return checks.length || ci.length ? { checks, ci } : null;
62
+ }
63
+ // `checks/ (3 files) and 2 CI files`.
64
+ export function unguardedWords(u) {
65
+ return [...(u.checks.length ? [`checks/ (${plural(u.checks.length, 'file')})`] : []), ...(u.ci.length ? [plural(u.ci.length, 'CI file')] : [])].join(' and ');
66
+ }
67
+ // What to do, for the person: the lines to add and the setting that makes them count. Printed, never written.
68
+ // `/checks/` only when gate scripts are unguarded: in a repo with no checks/ that line would match no file,
69
+ // itself a finding; and where every script already has an owner it is not needed.
70
+ export function unguardedHint(platform, u = { checks: [1] }) {
71
+ const hasChecks = u.checks.length > 0;
72
+ const setting = platform === 'gitlab'
73
+ ? 'turn on "Code owner approval" for the protected default branch (GitLab Premium)'
74
+ : 'turn on "Require review from Code Owners" for the default branch';
75
+ const lines = [...(hasChecks ? ['/checks/'] : []), ...GATE_CI_LINES[platform === 'gitlab' ? 'gitlab' : 'github']].map((l) => `\`${l} @<owner>\``);
76
+ const listed = lines.length > 1 ? `${lines.slice(0, -1).join(', ')} and ${lines.at(-1)}` : lines[0];
77
+ return `add ${listed} to CODEOWNERS through a PR, and ${setting} — see "Who may change the gates" in docs/branch-protection.md (yad never writes CODEOWNERS)`;
78
+ }
79
+
35
80
  // A pattern is printed as written unless it holds an `@`: E67's rule that no e-mail address is ever printed.
36
81
  const shownPattern = (d) => (d.pattern.includes('@') ? '' : ` (\`${d.negate ? '!' : ''}${d.pattern}\`)`);
37
82
 
@@ -53,7 +98,12 @@ export function checkCodeowners(repoRoot, { platform = null, remote, hint = fals
53
98
  if (!plat) return { ...base, unknown: 'yad cannot tell whether this repo is on GitHub or GitLab (no `platform` in repos.json, and the origin remote names neither) — pass --platform' };
54
99
  const co = diskCodeowners(repoRoot, plat);
55
100
  if (co.unknown) return { ...base, unknown: co.unknown };
56
- if (co.none) return { ...base, none: co.none };
101
+ if (co.none) {
102
+ const g = gateFiles(repoRoot, plat);
103
+ if (!g) return { ...base, unknown: 'git could not list the files in this repo' };
104
+ const unguarded = unguardedOf(g, null);
105
+ return { ...base, none: co.none, ...(unguarded ? { unguarded } : {}) };
106
+ }
57
107
  const out = { ...base, path: co.path, ignored: co.ignored };
58
108
  if (co.tooBig) return { ...out, tooBig: true };
59
109
  // Only now the file list: it is slow on a large repo, and a repo with no CODEOWNERS never needs it.
@@ -62,6 +112,10 @@ export function checkCodeowners(repoRoot, { platform = null, remote, hint = fals
62
112
  const parsed = parseCodeowners(co.text, plat);
63
113
  out.notRead = parsed.skipped;
64
114
  out.dead = deadLines(parsed, files, { submodules: submodulesOf(repoRoot) });
115
+ const g = gateFiles(repoRoot, plat);
116
+ if (!g) return { ...base, unknown: 'git could not list the files in this repo' };
117
+ const unguarded = unguardedOf(g, parsed);
118
+ if (unguarded) out.unguarded = unguarded;
65
119
  if (hint) out.inactive = inactiveOwners(repoRoot, parsed, plat, url);
66
120
  return out;
67
121
  }
@@ -104,6 +158,12 @@ export function codeownersFindings(r) {
104
158
  for (const d of r.dead) {
105
159
  out.push({ code: 'matches-nothing', line: d.line, message: `line ${d.line}${shownPattern(d)} ${d.negate ? 'excludes' : 'matches'} no file in this repo` });
106
160
  }
161
+ if (r.unguarded) {
162
+ const words = unguardedWords(r.unguarded);
163
+ out.push({ code: 'unguarded', checks: r.unguarded.checks.length, ci: r.unguarded.ci.length,
164
+ message: r.none ? `no CODEOWNERS, so ${words} have no code owner — a pull request can change what the gates do with no code owner's review`
165
+ : `no line in ${r.path} that yad can read gives ${words} an owner whose review ${name} can require — a pull request can change what the gates do with no code owner's review` });
166
+ }
107
167
  return out;
108
168
  }
109
169
 
@@ -113,8 +173,13 @@ function printRepo(name, r) {
113
173
  log(c.bold(`\ncodeowners — ${name}`));
114
174
  if (!r.git) { warn('no files on disk to check (not a git repo, or a bare one) — skipped'); return; }
115
175
  if (r.unknown) { warn(`CODEOWNERS: not known — ${r.unknown}`); return; }
116
- if (r.none) { info(`none — ${r.none}; nothing to check`); return; }
176
+ if (r.none && !r.unguarded) { info(`none — ${r.none}; nothing to check`); return; }
117
177
  const findings = codeownersFindings(r);
178
+ if (r.none) {
179
+ for (const f of findings) warn(f.message);
180
+ hand(unguardedHint(r.platform, r.unguarded));
181
+ return;
182
+ }
118
183
  for (const f of findings) warn(f.message);
119
184
  if (!findings.length) ok(`${r.path}: every line yad can read matches a file`);
120
185
  const i = r.inactive;
@@ -131,7 +196,8 @@ function printRepo(name, r) {
131
196
  const nc = Object.entries(i.notChecked).map(([k, n]) => plural(n, ...(KIND_WORD[k] || [k])));
132
197
  if (nc.length) info(`not checked for recent commits: ${nc.join(', ')} — the hint reads only @logins`);
133
198
  }
134
- if (findings.length) hand(`fix ${r.path} in ${name} through a PR — the warnings are advisory: CODEOWNERS is a hint, and yad never enforces it`);
199
+ if (findings.some((f) => f.code !== 'unguarded')) hand(`fix ${r.path} in ${name} through a PR — the warnings are advisory: CODEOWNERS is a hint, and yad never enforces it`);
200
+ if (r.unguarded) hand(unguardedHint(r.platform, r.unguarded));
135
201
  }
136
202
 
137
203
  export async function runCodeowners(root, { action = 'check', name, json = false, platform = null, write = false } = {}) {
@@ -160,7 +226,7 @@ export async function runCodeowners(root, { action = 'check', name, json = false
160
226
  emitJSON({ ok: true, repos: repos.map((r) => ({
161
227
  name: r.name, git: r.git, platform: r.platform ?? null, path: r.path ?? null,
162
228
  ...(r.none ? { none: r.none } : {}), ...(r.unknown ? { unknown: r.unknown } : {}),
163
- findings: r.git && !r.unknown && !r.none ? codeownersFindings(r) : [],
229
+ findings: r.git && !r.unknown ? codeownersFindings(r) : [],
164
230
  ...(r.inactive ? { inactive: r.inactive } : {}),
165
231
  })) });
166
232
  return { ok: true, repos };
package/cli/commit.mjs CHANGED
@@ -10,6 +10,7 @@
10
10
  // and the CI `ledger-guard` check, which quotes it — can see why. It opens this machine's hook and
11
11
  // nothing more: CI still fails the commit, because anyone can type a trailer.
12
12
  import path from 'node:path';
13
+ import { spawnSync } from 'node:child_process';
13
14
  import fs from 'node:fs';
14
15
  import { c, log, ok, info, warn, fail, run, exists } from './lib.mjs';
15
16
  import {
@@ -71,7 +72,11 @@ export async function runCommit(root, opts = {}) {
71
72
  if (opts.manual && opts.reason === undefined) { fail('--manual needs --reason "<why>" — the reason is recorded in the commit as a Ledger-Override trailer'); process.exitCode = 1; return; }
72
73
  if (!opts.manual && opts.reason !== undefined) { fail('--reason is only for --manual (the ledger override)'); process.exitCode = 1; return; }
73
74
 
74
- const staged = run('git', ['diff', '--cached', '--name-only'], { cwd: root }).stdout.split('\n').filter(Boolean);
75
+ // NUL-separated and spawned directly (run() trims, and git quotes an unusual name without -z — `Café.cs.meta`
76
+ // would read as "Assets/Caf\303\251.cs.meta" and miss its partner below).
77
+ const listed = spawnSync('git', ['diff', '--cached', '--name-only', '-z'], { cwd: root, encoding: 'utf8', maxBuffer: 64 * 1024 * 1024 });
78
+ if (listed.error || listed.status !== 0) { fail(`git could not list the staged files (${listed.error ? listed.error.message : (listed.stderr || '').trim() || `exit ${listed.status}`}) — check git is installed and this is a git repo`); process.exitCode = 1; return; }
79
+ const staged = listed.stdout.split('\0').filter(Boolean);
75
80
  if (!staged.length) { fail('nothing staged — `git add` your atomic change first'); process.exitCode = 1; return; }
76
81
 
77
82
  // An override is recorded only when there is something to override: a staged file the Product's
@@ -85,8 +90,17 @@ export async function runCommit(root, opts = {}) {
85
90
  return;
86
91
  }
87
92
 
88
- if (staged.length > ATOMIC_FILE_LIMIT && !opts.force) {
89
- fail(`${staged.length} files staged (atomic guard: ≤${ATOMIC_FILE_LIMIT}). Split the change, or pass --force.`);
93
+ // In a Unity repo (#321), Unity writes a `.meta` beside each file and folder it imports (it holds the ID): a
94
+ // staged `X.meta` whose `X` is staged too, or is a folder holding a staged file, goes with it and is not
95
+ // counted. Only there, and only with its partner: a lone `.meta` still counts. Staged paths are from the
96
+ // repo's top, so the Unity check is made there too (root is a subfolder only under --manual).
97
+ const top = run('git', ['rev-parse', '--show-toplevel'], { cwd: root }).stdout || root;
98
+ const unity = exists(path.join(top, 'ProjectSettings', 'ProjectVersion.txt')) && exists(path.join(top, 'Assets'));
99
+ const companion = (f) => unity && f.endsWith('.meta') && (staged.includes(f.slice(0, -5)) || staged.some((g) => g.startsWith(`${f.slice(0, -5)}/`)));
100
+ const counted = staged.filter((f) => !companion(f));
101
+ if (counted.length > ATOMIC_FILE_LIMIT && !opts.force) {
102
+ const metas = staged.length - counted.length;
103
+ fail(`${counted.length} files staged (atomic guard: ≤${ATOMIC_FILE_LIMIT}${metas ? `; ${metas} Unity .meta file${metas === 1 ? '' : 's'} beside them not counted` : ''}). Split the change, or pass --force.`);
90
104
  for (const f of staged) info(f);
91
105
  process.exitCode = 1;
92
106
  return;
package/cli/docs.mjs CHANGED
@@ -176,6 +176,7 @@ pages:
176
176
  # Set the YAD_RUNNER_TAGS / YAD_NODE_VERSION CI/CD variables to route this job to a tag-locked runner or
177
177
  # change its Node line; a shell-executor runner ignores \`image:\` and needs Node on its host.
178
178
  tags: [$YAD_RUNNER_TAGS]
179
+ timeout: 15 minutes
179
180
  image: node:\${YAD_NODE_VERSION}
180
181
  variables:
181
182
  YAD_NODE_VERSION: "22"
@@ -202,6 +203,7 @@ concurrency:
202
203
  jobs:
203
204
  build-deploy:
204
205
  runs-on: ubuntu-latest
206
+ timeout-minutes: 15
205
207
  permissions:
206
208
  contents: read
207
209
  pages: write # publish the site