rungate 0.6.0 → 0.8.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 (164) hide show
  1. package/hooks/ActionVerificationGate.hook.ts +96 -0
  2. package/hooks/AgentBriefGuard.hook.ts +38 -0
  3. package/hooks/AgentVerdictCapture.hook.ts +87 -0
  4. package/hooks/AutoVerifyGate.hook.ts +79 -0
  5. package/hooks/BashToolGuard.hook.ts +65 -0
  6. package/hooks/BashWriteGuard.hook.ts +60 -0
  7. package/hooks/CommitEnforcement.hook.ts +130 -0
  8. package/hooks/DocHygiene.hook.ts +148 -0
  9. package/hooks/GateEnforcement.hook.ts +58 -0
  10. package/hooks/GateResultProtection.hook.ts +69 -0
  11. package/hooks/HarnessAFKGate.hook.ts +85 -0
  12. package/hooks/HookCurrency.hook.ts +99 -0
  13. package/hooks/IssueCloseGuard.hook.ts +149 -0
  14. package/hooks/MergeGuard.hook.ts +58 -0
  15. package/hooks/PostCompact.hook.ts +60 -0
  16. package/hooks/ProjectStateSync.hook.ts +103 -0
  17. package/hooks/SkillGuard.hook.ts +69 -0
  18. package/hooks/SpecConformityTrigger.hook.ts +43 -0
  19. package/hooks/SpecSCGuard.hook.ts +123 -0
  20. package/hooks/StaleTTLCleanup.hook.ts +141 -0
  21. package/hooks/TaskCompleted.hook.ts +51 -0
  22. package/hooks/TeamInit.hook.ts +85 -0
  23. package/hooks/TestSuiteGuard.hook.ts +70 -0
  24. package/hooks/TestSuiteRelease.hook.ts +85 -0
  25. package/hooks/TopLevelCdGuard.hook.ts +108 -0
  26. package/hooks/VerifyPhaseLock.hook.ts +84 -0
  27. package/hooks/WorkflowStateGuard.hook.ts +40 -0
  28. package/hooks/lib/agent-config.json +9 -0
  29. package/hooks/lib/agentDetection.ts +201 -0
  30. package/hooks/lib/comment-template.ts +86 -0
  31. package/hooks/lib/findWorkflow.ts +101 -0
  32. package/hooks/lib/parseStdin.ts +37 -0
  33. package/hooks/lib/paths.ts +111 -0
  34. package/hooks/lib/utils.ts +338 -0
  35. package/lib/affected-tests.ts +427 -0
  36. package/lib/agent-audit.ts +2 -3
  37. package/lib/agent-worktree.ts +287 -0
  38. package/lib/agents-md-sections.ts +81 -16
  39. package/lib/bash-write-guard.ts +373 -0
  40. package/lib/behavioral-cache.ts +150 -2
  41. package/lib/branch-cleanup.ts +279 -7
  42. package/lib/branch-protection.ts +790 -0
  43. package/lib/brief-ac-alignment.ts +104 -0
  44. package/lib/brief-references.ts +205 -0
  45. package/lib/bun-version.ts +93 -14
  46. package/lib/check-remedy.ts +140 -0
  47. package/lib/ci-checkout.ts +17 -0
  48. package/lib/ci-history-depth.ts +159 -0
  49. package/lib/ci-setup-step.ts +96 -0
  50. package/lib/claude-code-action.ts +85 -0
  51. package/lib/claude-tool-vocabulary.ts +188 -0
  52. package/lib/cli-commands.ts +15 -0
  53. package/lib/commit-sha.ts +42 -0
  54. package/lib/commit-subject.ts +90 -0
  55. package/lib/compliance-report.ts +377 -45
  56. package/lib/compliance.ts +191 -17
  57. package/lib/config-loader.ts +39 -1
  58. package/lib/config-trackable.ts +400 -0
  59. package/lib/conformity.ts +1087 -100
  60. package/lib/containment.ts +238 -0
  61. package/lib/content-hash.ts +24 -0
  62. package/lib/create-sc.ts +249 -16
  63. package/lib/dev-liveness.ts +180 -0
  64. package/lib/discovery-branch-points.ts +432 -0
  65. package/lib/discovery-stability.ts +481 -0
  66. package/lib/distribution-currency.ts +236 -0
  67. package/lib/doc-routing.ts +157 -0
  68. package/lib/evidence-prevalidator.ts +224 -2
  69. package/lib/evidence-satisfiability.ts +534 -12
  70. package/lib/failure-intake.ts +323 -0
  71. package/lib/fallow-availability.ts +157 -0
  72. package/lib/fs-write-capabilities.ts +232 -0
  73. package/lib/gate-enforcement.ts +222 -28
  74. package/lib/gate-names.ts +72 -0
  75. package/lib/gate-result-protection.ts +427 -0
  76. package/lib/gate-run-split.ts +147 -0
  77. package/lib/generators/agents-md.ts +140 -32
  78. package/lib/git-isolation.ts +140 -0
  79. package/lib/github.ts +15 -0
  80. package/lib/google-auth-action.ts +93 -0
  81. package/lib/harness-project.ts +48 -0
  82. package/lib/harness-provenance.ts +255 -0
  83. package/lib/hook-evidence.ts +235 -0
  84. package/lib/hook-scopes.ts +386 -0
  85. package/lib/hook-target-tree.ts +398 -0
  86. package/lib/hook-trees.ts +447 -0
  87. package/lib/intake-sources.ts +380 -0
  88. package/lib/js-top-level-code.ts +78 -10
  89. package/lib/junit-checks.ts +52 -0
  90. package/lib/late-env-spawn.ts +331 -0
  91. package/lib/launch-base.ts +376 -0
  92. package/lib/line-citation.ts +372 -0
  93. package/lib/orphan-reaper.ts +468 -0
  94. package/lib/parity-binding.ts +205 -0
  95. package/lib/paths.ts +96 -3
  96. package/lib/per-test-timeouts.ts +219 -0
  97. package/lib/phase2-decomposition.ts +1 -1
  98. package/lib/plan-coverage.ts +151 -0
  99. package/lib/prior-branch.ts +201 -8
  100. package/lib/process-table.ts +146 -0
  101. package/lib/project-state-derivation.ts +219 -0
  102. package/lib/project-state-root.ts +258 -0
  103. package/lib/published-artifact.ts +669 -0
  104. package/lib/readdir-sorted.ts +45 -0
  105. package/lib/review-execution-reading.ts +206 -0
  106. package/lib/review-tool-agreement.ts +433 -0
  107. package/lib/rule-promotion.ts +234 -0
  108. package/lib/rule-retirement.ts +525 -0
  109. package/lib/run-branch.ts +612 -0
  110. package/lib/rungate-schema.ts +19 -0
  111. package/lib/runner-home.ts +274 -0
  112. package/lib/sc-id-cross-tree.ts +103 -15
  113. package/lib/sc-ids.ts +121 -13
  114. package/lib/sc-reservations.ts +289 -0
  115. package/lib/scaffold/ai-review-findings.ts +409 -0
  116. package/lib/scaffold/ai-review-step.ts +5406 -64
  117. package/lib/scaffold/defaults.ts +82 -1
  118. package/lib/scaffold/managed-workflow.ts +587 -192
  119. package/lib/scaffold/owned-files.ts +152 -45
  120. package/lib/scaffold/pre-push-hook.ts +49 -5
  121. package/lib/scaffold/steps.ts +1836 -275
  122. package/lib/scaffold/workflow-census.ts +217 -0
  123. package/lib/scaffold/workflow-drift.ts +217 -0
  124. package/lib/scaffold/write-steps.ts +4 -0
  125. package/lib/scan-budget.ts +247 -0
  126. package/lib/scanner.ts +43 -51
  127. package/lib/scratch-roots.ts +50 -5
  128. package/lib/screenshot-discovery.ts +121 -0
  129. package/lib/screenshot-upload.ts +41 -1
  130. package/lib/secret-patterns.ts +511 -8
  131. package/lib/security-verdict.ts +1 -1
  132. package/lib/shell-path-interpolation.ts +594 -0
  133. package/lib/ship-mode.ts +219 -0
  134. package/lib/source-slice.ts +294 -0
  135. package/lib/stale-cleanup.ts +37 -3
  136. package/lib/suite-flake.ts +278 -0
  137. package/lib/suite-measurement.ts +23 -4
  138. package/lib/suite-run-reading.ts +241 -1
  139. package/lib/suite-timeout-margin.ts +193 -0
  140. package/lib/test-case-bodies.ts +883 -0
  141. package/lib/test-case-deletion.ts +653 -0
  142. package/lib/test-census.ts +97 -29
  143. package/lib/test-command-positions.ts +274 -0
  144. package/lib/test-suite-lock.ts +159 -16
  145. package/lib/text-dependents.ts +875 -0
  146. package/lib/tool-probe.ts +31 -9
  147. package/lib/top-level-cd.ts +393 -0
  148. package/lib/tree-entries.ts +89 -0
  149. package/lib/ts-ast.ts +200 -0
  150. package/lib/walk-test-files.ts +97 -0
  151. package/lib/workflow-actions.ts +263 -0
  152. package/lib/workflow-security.ts +29 -0
  153. package/lib/workflow-taint.ts +732 -0
  154. package/lib/worktree-cleanup.ts +65 -38
  155. package/lib/worktree-collect.ts +177 -5
  156. package/lib/worktree-repo.ts +68 -3
  157. package/package.json +4 -1
  158. package/scripts/ai-review-findings.ts +45 -0
  159. package/scripts/check-installed-hook-currency.ts +825 -0
  160. package/scripts/create-sc.ts +21 -1
  161. package/scripts/extract-constraints.ts +107 -7
  162. package/scripts/generate-code-map.ts +23 -30
  163. package/scripts/scaffold-project.ts +8 -1
  164. package/scripts/sync-sc-status.ts +77 -16
@@ -0,0 +1,274 @@
1
+ /**
2
+ * Who owns the harness work root, and may this process delete inside it (#904).
3
+ *
4
+ * ## The harm this exists to stop
5
+ *
6
+ * `lib/stale-cleanup.ts` walks every top-level directory under the harness
7
+ * work root and renames or deletes it on `mtime` and `phase` alone. It has
8
+ * never had an ownership check. A self-hosted pool that runs several runner
9
+ * processes under one service account shares a `$HOME`, so those runners also
10
+ * share `$HOME/.rungate` — and a SessionStart on runner-5 archives runner-4's
11
+ * live run directory the moment runner-4's `workflow-state.json` looks stale.
12
+ *
13
+ * The failure that produces is NON-LOCAL. Runner-4 fails in a step that did
14
+ * nothing wrong, because a sibling moved a file underneath it. It reads as a
15
+ * flaky test, which is the worst possible disguise for a contention bug.
16
+ *
17
+ * ## Why this is not the `$HOME`-in-the-workflow fix
18
+ *
19
+ * The cheapest wrong fix is `HOME: ${{ runner.temp }}/home` in the workflow
20
+ * YAML. The symptom goes away for CI and the harness keeps its one unguarded
21
+ * `$HOME` assumption: a consumer who runs the same jobs without that line
22
+ * gets the original bug back, and nothing in the harness says so. The check
23
+ * here is on the sweep's behaviour, so it is unaffected by that line either
24
+ * way — which is the point. A regression test that goes green when you edit
25
+ * the workflow file is testing the workflow file.
26
+ *
27
+ * ## Why an empty `$HOME` cannot see this
28
+ *
29
+ * `scripts/test-clean-env.ts` runs suites with `HOME` at an empty `mkdtemp`.
30
+ * An empty work root archives nothing whether the sweep is ownership-aware or
31
+ * not, so the isolation bug is invisible to exactly the suites that look most
32
+ * rigorous. The discriminating input is a work root that is POPULATED with
33
+ * another runner's directory: the ownership-blind sweep archives it, the
34
+ * guarded one refuses and names the owner.
35
+ *
36
+ * ## The lifecycle, and why auto-claim is safe only when vacant
37
+ *
38
+ * Claiming a root that already holds state would let whichever runner booted
39
+ * first assume ownership of everybody's work — the original bug with a marker
40
+ * file on top. So a claim happens only when there is nothing to destroy:
41
+ *
42
+ * - vacant root, no marker → claim it, sweep (a no-op this time round)
43
+ * - marker names this runner → sweep, exactly as before
44
+ * - marker names another → REFUSE, and name the other runner
45
+ * - occupied, no marker → REFUSE; nothing here can be attributed
46
+ * - not on a runner at all → sweep, exactly as before
47
+ *
48
+ * The last line is why this change is inert on a developer's machine and in
49
+ * every existing test: `RUNNER_NAME` is a GitHub Actions variable, so off a
50
+ * runner the verdict is `unscoped` and the sweep behaves as it always has.
51
+ *
52
+ * Once each runner has its own `HOME` (#904's infrastructure half), each
53
+ * private root is vacant on its first job, claims itself, and sweeps normally
54
+ * forever after. This check is what converts that isolation into something
55
+ * measurable instead of something assumed.
56
+ *
57
+ * ## Zero is not success
58
+ *
59
+ * A refused sweep returns `archived: 0`, which is indistinguishable from "a
60
+ * clean root with nothing to archive". That ambiguity is the reason
61
+ * `sweep: false` and `reason` exist as fields rather than as a log line:
62
+ * silence, `0` and `null` must not all mean the same thing.
63
+ */
64
+
65
+ import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from "fs";
66
+ import { join } from "path";
67
+
68
+ /** Basename of the ownership marker written at the root of the work dir. */
69
+ export const WORK_ROOT_OWNER_FILE = ".owner";
70
+
71
+ /**
72
+ * Directory entries that do not count as occupancy.
73
+ *
74
+ * `.archive` is excluded only when it is EMPTY — an archive holding another
75
+ * runner's directories is occupancy, and treating the directory's mere
76
+ * existence as vacancy would let a root be claimed out from under the very
77
+ * state the sweep already moved there.
78
+ */
79
+ const VACANCY_EXEMPT = new Set([WORK_ROOT_OWNER_FILE, ".archive"]);
80
+
81
+ export const WORK_ROOT_REFUSED_SHARED =
82
+ "the harness work root is claimed by a DIFFERENT runner, so the stale " +
83
+ "sweep refused: archiving here would move a sibling runner's live state " +
84
+ "out from under it, and the job that fails is the sibling's, not this one " +
85
+ "(#904). Give each runner its own HOME.";
86
+
87
+ export const WORK_ROOT_REFUSED_UNATTRIBUTED =
88
+ "the harness work root already holds run state but records no owning " +
89
+ "runner, so the stale sweep refused: on a shared HOME nothing here can be " +
90
+ "attributed to this runner, and an unattributed delete is the bug (#904).";
91
+
92
+ export const WORK_ROOT_REFUSED_UNNAMABLE =
93
+ "RUNNER_NAME is set but contains no characters usable as an owner id, so " +
94
+ "the stale sweep refused: this runner cannot be told apart from a sibling " +
95
+ "and ownership cannot be decided (#904).";
96
+
97
+ export type WorkRootState =
98
+ | "unscoped"
99
+ | "vacant"
100
+ | "claimed"
101
+ | "owned"
102
+ | "shared"
103
+ | "unattributed"
104
+ | "unnamable";
105
+
106
+ export interface WorkRootVerdict {
107
+ /** May this process delete or archive inside the work root? */
108
+ readonly sweep: boolean;
109
+ readonly state: WorkRootState;
110
+ /** This process's runner id, or `null` when not running on a runner. */
111
+ readonly runner: string | null;
112
+ /** The id recorded in the marker file, or `null` when there is none. */
113
+ readonly owner: string | null;
114
+ /** One of the exported refusal constants, and non-null exactly when `sweep` is false. */
115
+ readonly reason: string | null;
116
+ }
117
+
118
+ /**
119
+ * Filesystem-safe form of a runner name.
120
+ *
121
+ * GitHub Actions names hosted runners "GitHub Actions 2" — spaces and all —
122
+ * so the raw value is not usable as a path component or a stable token.
123
+ */
124
+ function slugifyRunner(raw: string): string {
125
+ return raw
126
+ .trim()
127
+ .toLowerCase()
128
+ .replace(/[^a-z0-9._-]+/g, "-")
129
+ .replace(/^[-.]+|[-.]+$/g, "");
130
+ }
131
+
132
+ /**
133
+ * This process's runner id, or `null` when it is not running on a runner.
134
+ *
135
+ * Returns `null` for BOTH "absent" and "unusable", so callers that need to
136
+ * tell a developer's laptop from a misconfigured runner must read
137
+ * `workRootOwnership`'s verdict instead — `null` here is deliberately not a
138
+ * licence to sweep.
139
+ */
140
+ export function runnerId(env: NodeJS.ProcessEnv = process.env): string | null {
141
+ const slug = slugifyRunner(env.RUNNER_NAME ?? "");
142
+ return slug === "" ? null : slug;
143
+ }
144
+
145
+ /**
146
+ * An `.archive` that cannot be read counts as OCCUPIED, not as empty — an
147
+ * unreadable directory is a thing this process knows nothing about, and the
148
+ * safe reading of "I could not tell" is "do not claim this root".
149
+ */
150
+ function archiveIsEmpty(workRoot: string): boolean {
151
+ try {
152
+ return readdirSync(join(workRoot, ".archive")).length === 0;
153
+ } catch {
154
+ return false;
155
+ }
156
+ }
157
+
158
+ function isVacant(workRoot: string): boolean {
159
+ let names: string[];
160
+ try {
161
+ names = readdirSync(workRoot);
162
+ } catch {
163
+ // Unreadable or absent: there is nothing here this process could destroy.
164
+ return true;
165
+ }
166
+ for (const name of names) {
167
+ if (!VACANCY_EXEMPT.has(name)) return false;
168
+ if (name === ".archive" && !archiveIsEmpty(workRoot)) return false;
169
+ }
170
+ return true;
171
+ }
172
+
173
+ function readOwner(workRoot: string): string | null {
174
+ const marker = join(workRoot, WORK_ROOT_OWNER_FILE);
175
+ if (!existsSync(marker)) return null;
176
+ try {
177
+ const recorded = readFileSync(marker, "utf-8").trim();
178
+ return recorded === "" ? null : recorded;
179
+ } catch {
180
+ return null;
181
+ }
182
+ }
183
+
184
+ /**
185
+ * Record `runner` as the owner of `workRoot`.
186
+ *
187
+ * Exported so that a consumer provisioning a genuinely private `HOME` can
188
+ * claim it up front rather than waiting for a vacant-root job to do it.
189
+ * Idempotent, and deliberately silent on failure: an unwritable root is
190
+ * reported by the next verdict as `unattributed`, which refuses, rather than
191
+ * by throwing out of a SessionStart hook.
192
+ */
193
+ export function claimWorkRoot(workRoot: string, runner: string): boolean {
194
+ try {
195
+ mkdirSync(workRoot, { recursive: true });
196
+ writeFileSync(join(workRoot, WORK_ROOT_OWNER_FILE), `${runner}\n`);
197
+ return true;
198
+ } catch {
199
+ return false;
200
+ }
201
+ }
202
+
203
+ /**
204
+ * Decide whether this process may delete inside `workRoot`.
205
+ *
206
+ * Claims a vacant root as a side effect; see the module docblock for why that
207
+ * is the only case in which claiming cannot harm a sibling.
208
+ */
209
+ export function workRootOwnership(
210
+ workRoot: string,
211
+ env: NodeJS.ProcessEnv = process.env,
212
+ ): WorkRootVerdict {
213
+ const raw = env.RUNNER_NAME ?? "";
214
+ if (raw.trim() === "") {
215
+ return { sweep: true, state: "unscoped", runner: null, owner: null, reason: null };
216
+ }
217
+
218
+ const runner = slugifyRunner(raw);
219
+ if (runner === "") {
220
+ return {
221
+ sweep: false,
222
+ state: "unnamable",
223
+ runner: null,
224
+ owner: null,
225
+ reason: WORK_ROOT_REFUSED_UNNAMABLE,
226
+ };
227
+ }
228
+
229
+ const owner = readOwner(workRoot);
230
+ if (owner !== null) {
231
+ return owner === runner
232
+ ? { sweep: true, state: "owned", runner, owner, reason: null }
233
+ : {
234
+ sweep: false,
235
+ state: "shared",
236
+ runner,
237
+ owner,
238
+ reason: WORK_ROOT_REFUSED_SHARED,
239
+ };
240
+ }
241
+
242
+ if (!isVacant(workRoot)) {
243
+ return {
244
+ sweep: false,
245
+ state: "unattributed",
246
+ runner,
247
+ owner: null,
248
+ reason: WORK_ROOT_REFUSED_UNATTRIBUTED,
249
+ };
250
+ }
251
+
252
+ const claimed = claimWorkRoot(workRoot, runner);
253
+ return {
254
+ sweep: true,
255
+ state: claimed ? "claimed" : "vacant",
256
+ runner,
257
+ owner: claimed ? runner : null,
258
+ reason: null,
259
+ };
260
+ }
261
+
262
+ /**
263
+ * The log line a refusing sweep emits.
264
+ *
265
+ * One formatter so the reason, the two runner ids and the path always travel
266
+ * together: a refusal that named neither party would be exactly as mysterious
267
+ * as the silent delete it replaces.
268
+ */
269
+ export function workRootRefusalLine(workRoot: string, verdict: WorkRootVerdict): string {
270
+ return (
271
+ `REFUSED sweep state=${verdict.state} runner=${verdict.runner ?? "?"} ` +
272
+ `owner=${verdict.owner ?? "none"} path=${workRoot} :: ${verdict.reason}`
273
+ );
274
+ }
@@ -51,7 +51,7 @@
51
51
  * on, which is the fastest way to build a refusal everyone learns to click
52
52
  * past. Fix the allocator that mints collisions; do not alarm on the fossils.
53
53
  */
54
- import { execFileSync } from "child_process";
54
+ import { execFileSync, spawnSync } from "child_process";
55
55
  import { existsSync, readdirSync, readFileSync, statSync } from "fs";
56
56
  import { join } from "path";
57
57
 
@@ -60,18 +60,30 @@ import { isFixtureScId, scDeclarationPattern, scHeadingDeclarationPattern } from
60
60
  /**
61
61
  * One place ids were looked for, and whether the look succeeded.
62
62
  *
63
- * `worktree` and `refs` are this module's own two sources. The other three
64
- * are the legs `allocateScNumber` composes on top of them (#593) — the
65
- * spec's own content, the spec registry, and the ids spelled in source. They
66
- * live in the same shape because the question a reader asks is one question:
67
- * which widths produced this number, and did any of them fail to run.
63
+ * `worktree` and `refs` are this module's own two sources. The other four
64
+ * are the legs `allocateScNumber` composes on top of them (#593, #725) — the
65
+ * spec's own content, the spec registry, the ids spelled in source, and the
66
+ * reservation store. They live in the same shape because the question a
67
+ * reader asks is one question: which widths produced this number, and did any
68
+ * of them fail to run.
69
+ *
70
+ * `reservations` is the only leg that is not a reading of ids somebody has
71
+ * already written down. It is a reading of ids somebody has DECLARED they are
72
+ * about to write down, which is the half the other five structurally cannot
73
+ * see (#725).
68
74
  */
69
75
  export interface SourceReading {
70
76
  label: string;
71
- kind: "worktree" | "refs" | "spec-content" | "registry" | "source-mentions";
77
+ kind: "worktree" | "refs" | "spec-content" | "registry" | "source-mentions" | "reservations";
72
78
  /** `read` means the ids below came from here; `skipped` means they did not. */
73
79
  status: "read" | "skipped";
74
- /** Why it was skipped. Absent on a successful read. */
80
+ /**
81
+ * Why it was skipped — or, on a PARTIAL read, what it could not reach
82
+ * (#606). A leg over four directories that opened three of them is `read`
83
+ * for the three and still owes an account of the fourth; folding that into
84
+ * `skipped` would make it indistinguishable from a leg that opened none.
85
+ * Absent only on a read that reached everything it was pointed at.
86
+ */
75
87
  reason?: string;
76
88
  /** How many distinct ids this source contributed. */
77
89
  found: number;
@@ -163,22 +175,92 @@ function idsInSpecsDir(specsDir: string): string[] {
163
175
  return ids;
164
176
  }
165
177
 
178
+ /**
179
+ * One ref per distinct `specs/` tree, and `null` if that cannot be worked out.
180
+ *
181
+ * `git grep <ref>` searches that ref's tree from scratch. Two refs whose
182
+ * `specs/` is the SAME tree object therefore do the same search twice and
183
+ * return the same lines, because the ids are a pure function of the bytes
184
+ * under `specs/` and a tree SHA is a hash of exactly those bytes. Dropping
185
+ * the second is not a narrowing of what is read — it is the same reading with
186
+ * the repeats removed, which is why it needs no judgement call about which
187
+ * branches "matter". Measured on this repository: 1638 refs, 326 distinct
188
+ * trees, identical id set of 1656 — 0 missing, 0 extra (#1132).
189
+ *
190
+ * 533 of those refs resolve to no `specs/` at all and are dropped outright. A
191
+ * ref with no `specs/` directory cannot match `-- specs/*.md`, so grepping it
192
+ * was always going to return nothing.
193
+ *
194
+ * `null` means the question could not be answered — a `git` that does not
195
+ * support the batching, or output that does not line up with the input. The
196
+ * caller then greps every ref, which is slow and correct. Guessing at a
197
+ * partial mapping would be fast and wrong, and the wrongness is a reissued
198
+ * id rather than an error anyone would see.
199
+ */
200
+ function refsByDistinctSpecsTree(root: string, refs: string[]): string[] | null {
201
+ const probe = spawnSync("git", ["cat-file", "--batch-check=%(objectname) %(objecttype)"], {
202
+ cwd: root,
203
+ input: refs.map(r => `${r}^{tree}:specs\n`).join(""),
204
+ encoding: "utf-8",
205
+ timeout: 120_000,
206
+ maxBuffer: 64 * 1024 * 1024,
207
+ });
208
+ if (probe.error || probe.status !== 0) return null;
209
+ const lines = (probe.stdout ?? "").split("\n").filter(l => l !== "");
210
+ // One line in, one line out. If that does not hold, the index below is
211
+ // pairing a SHA with the wrong ref, and a representative chosen for the
212
+ // wrong tree drops ids that are really there.
213
+ if (lines.length !== refs.length) return null;
214
+
215
+ const representative = new Map<string, string>();
216
+ for (let i = 0; i < lines.length; i++) {
217
+ // `<sha> tree` for a ref that has one; `<input> missing` for a ref that
218
+ // does not. Only the first shape is a tree worth searching.
219
+ const match = /^([0-9a-f]{40}) tree$/.exec(lines[i]);
220
+ if (match === null) continue;
221
+ if (!representative.has(match[1])) representative.set(match[1], refs[i]);
222
+ }
223
+ return [...representative.values()];
224
+ }
225
+
166
226
  /**
167
227
  * Ids declared in `specs/` on any ref this repository holds — local branches
168
228
  * and remote-tracking branches both.
169
229
  *
170
230
  * One `git grep` over every ref at once rather than a checkout each: measured
171
231
  * at 0.17s over 1087 refs, against minutes for the obvious implementation.
232
+ *
233
+ * ## …and at 1638 refs that was 7.3s, on the hot path of allocating one id
234
+ *
235
+ * The comment above aged into a wrong number rather than a stale one (#1132).
236
+ * `git grep` over N refs costs N tree searches, and this repository grew from
237
+ * 1087 refs to 1638 while the work per ref stayed the same, so allocating a
238
+ * single SC id came to 17.4s end to end — past the 15s its own caller allows
239
+ * it. The cost is in the ref COUNT, and the ref count is a fact about how
240
+ * many branches are in flight, not about the change being made.
241
+ *
242
+ * `refsByDistinctSpecsTree` removes the repeats rather than picking a
243
+ * narrower population, so the id set is unchanged by construction. The
244
+ * tempting fix is to read `origin/main` only; measured here that reads 1646
245
+ * ids of 1656, and the ten it loses are the ids on unmerged branches, which
246
+ * are precisely the ones this leg exists to see (#503). Its highest id
247
+ * happened to match, so the allocated number was identical and the loss would
248
+ * not have shown up as a wrong answer until the day it collided.
249
+ *
250
+ * `grepped` is reported next to `refs` so a test can bind the scoping without
251
+ * binding a clock — a wall-clock assertion over this is flaky by
252
+ * construction, and the thing that makes it slow is the count.
172
253
  */
173
- function idsInRefs(root: string): { ids: string[]; refs: number; failure: string | null } {
254
+ export function idsInRefs(root: string): { ids: string[]; refs: number; grepped: number; failure: string | null } {
174
255
  let refList: string;
175
256
  try {
176
257
  refList = git(root, ["for-each-ref", "--format=%(refname)", "refs/heads", "refs/remotes"]);
177
258
  } catch (err) {
178
- return { ids: [], refs: 0, failure: (err as Error).message.split("\n")[0] };
259
+ return { ids: [], refs: 0, grepped: 0, failure: (err as Error).message.split("\n")[0] };
179
260
  }
180
- const refs = refList.split("\n").filter(r => r.trim() !== "");
181
- if (refs.length === 0) return { ids: [], refs: 0, failure: null };
261
+ const allRefs = refList.split("\n").filter(r => r.trim() !== "");
262
+ if (allRefs.length === 0) return { ids: [], refs: 0, grepped: 0, failure: null };
263
+ const refs = refsByDistinctSpecsTree(root, allRefs) ?? allRefs;
182
264
 
183
265
  const ids: string[] = [];
184
266
  // Batched: a ref list this long overruns the argument limit in one call.
@@ -202,12 +284,12 @@ function idsInRefs(root: string): { ids: string[]; refs: number; failure: string
202
284
  // a failure. Anything else is a failure, and the caller must hear it.
203
285
  const status = (err as { status?: number }).status;
204
286
  if (status === 1) continue;
205
- return { ids, refs: refs.length, failure: (err as Error).message.split("\n")[0] };
287
+ return { ids, refs: allRefs.length, grepped: refs.length, failure: (err as Error).message.split("\n")[0] };
206
288
  }
207
289
  for (const m of out.matchAll(scDeclarationPattern())) ids.push(m[2]);
208
290
  for (const m of out.matchAll(scHeadingDeclarationPattern())) ids.push(m[1]);
209
291
  }
210
- return { ids, refs: refs.length, failure: null };
292
+ return { ids, refs: allRefs.length, grepped: refs.length, failure: null };
211
293
  }
212
294
 
213
295
  /**
@@ -271,7 +353,13 @@ export function readScNamespace(root: string): ScNamespaceReading {
271
353
  } else {
272
354
  for (const id of refs.ids) record(id, "refs");
273
355
  sources.push({
274
- label: `refs (${refs.refs} local and remote-tracking)`,
356
+ // Both numbers, because they are different facts. `refs` is how wide
357
+ // the reading was; `grepped` is how many searches that cost. Printing
358
+ // only the second would read as a narrower reading than it is, and
359
+ // printing only the first hides the one number #1132 was about.
360
+ label: refs.grepped === refs.refs
361
+ ? `refs (${refs.refs} local and remote-tracking)`
362
+ : `refs (${refs.refs} local and remote-tracking, ${refs.grepped} distinct specs/ trees searched)`,
275
363
  kind: "refs",
276
364
  status: "read",
277
365
  found: new Set(refs.ids).size,
package/lib/sc-ids.ts CHANGED
@@ -193,9 +193,49 @@ export function isFixtureScId(id: string): boolean {
193
193
  * declaredById EVERY form. The namespace as it actually is, which is what
194
194
  * ambiguity and allocation have to be computed over.
195
195
  */
196
+ /**
197
+ * Whether the `specs/` this registry was built from was actually enumerated
198
+ * (#606).
199
+ *
200
+ * `buildScRegistry([])` is a registry with no declarations, and it means "this
201
+ * tree declares nothing" — a reading. A caller that could not list `specs/` at
202
+ * all produces the same empty maps and means the opposite, and before this
203
+ * field existed nothing downstream could tell them apart:
204
+ * `allocateScNumber`'s registry leg reported `found: reg.declaredById.size`
205
+ * with `status: "read"` for both. `0` from a width that was consulted and `0`
206
+ * from a width that was skipped are the same number and opposite facts
207
+ * (`.claude/rules/config-access.md`).
208
+ *
209
+ * The reason travels with the status because "install something" fixes a
210
+ * missing directory and nothing else does — a skip with no reason is a skip
211
+ * nobody can act on.
212
+ */
213
+ export interface ScRegistryEnumeration {
214
+ status: "enumerated" | "unenumerated";
215
+ /** Why `specs/` could not be enumerated. Absent when it was. */
216
+ reason?: string;
217
+ }
218
+
196
219
  export interface ScRegistry {
197
220
  byId: Map<string, string[]>;
198
221
  declaredById: Map<string, string[]>;
222
+ /** Where the declarations came from, or why they could not be collected. */
223
+ enumeration: ScRegistryEnumeration;
224
+ }
225
+
226
+ /**
227
+ * A registry whose `specs/` could NOT be listed (#606).
228
+ *
229
+ * Empty maps, like `buildScRegistry([])` — and the only thing separating the
230
+ * two is this flag, which is the point. A consumer handed one of these must
231
+ * not report the registry width as consulted.
232
+ */
233
+ export function unenumeratedScRegistry(reason: string): ScRegistry {
234
+ return {
235
+ byId: new Map(),
236
+ declaredById: new Map(),
237
+ enumeration: { status: "unenumerated", reason },
238
+ };
199
239
  }
200
240
 
201
241
  /** The template's ids are placeholders — `isTemplateSpec` already skips it. */
@@ -276,7 +316,9 @@ export function buildScRegistry(specs: Array<{ file: string; content: string }>)
276
316
  record(declaredById, d.id, file);
277
317
  }
278
318
  }
279
- return { byId, declaredById };
319
+ // Enumerated by construction: the caller handed over the list of specs it
320
+ // read. An empty list is a tree that declares nothing, which is a reading.
321
+ return { byId, declaredById, enumeration: { status: "enumerated" } };
280
322
  }
281
323
 
282
324
  /**
@@ -396,8 +438,42 @@ export interface ScMentionInSource {
396
438
  inComment: boolean;
397
439
  }
398
440
 
441
+ /** A directory the walk met and could not open, with the reason it gave. */
442
+ export interface ScSourceDirUnwalkable {
443
+ /** Relative to `root` where that is possible, absolute otherwise. */
444
+ dir: string;
445
+ reason: string;
446
+ }
447
+
399
448
  /**
400
- * Every numeric SC id spelled anywhere under `SC_SOURCE_DIRS`.
449
+ * What the source walk found AND where it could not look (#606).
450
+ *
451
+ * The walk returns silently from a directory it cannot open, which is right
452
+ * for the walk — a consumer whose tests live in `tests/` has no `test/` and
453
+ * that is not an error. It is wrong for a CALLER that then reports the result
454
+ * as a completed read: a tree with four readable, present, genuinely empty
455
+ * source directories and a tree with none of them both produce zero ids, and
456
+ * only one of them has been measured.
457
+ *
458
+ * So the count and the coverage travel together. A scan that reports a
459
+ * verdict reports its own coverage
460
+ * (`.claude/rules/checks-must-be-able-to-fail.md`).
461
+ */
462
+ export interface ScSourceMentionsReading {
463
+ mentions: ScMentionInSource[];
464
+ /** Which of `SC_SOURCE_DIRS` were opened. Never contains an unwalkable dir. */
465
+ walked: string[];
466
+ /**
467
+ * Every directory `readdirSync` refused — a top-level `SC_SOURCE_DIRS`
468
+ * entry or anything nested beneath one, because the fail-open is the same
469
+ * `catch` in both positions.
470
+ */
471
+ unwalkable: ScSourceDirUnwalkable[];
472
+ }
473
+
474
+ /**
475
+ * Every numeric SC id spelled anywhere under `SC_SOURCE_DIRS`, with an
476
+ * account of which of those directories were actually walked (#606).
401
477
  *
402
478
  * Deliberately NOT restricted to declaring forms. The allocator's question is
403
479
  * "could handing out this number break something", and a fixture spelled in
@@ -407,18 +483,28 @@ export interface ScMentionInSource {
407
483
  * (`.claude/rules/claiming-sc-coverage.md`); this is a different question
408
484
  * asked for a different purpose, and widening it here cannot credit anything.
409
485
  */
410
- export function scMentionsInSource(root: string): ScMentionInSource[] {
486
+ export function scMentionsInSource(root: string): ScSourceMentionsReading {
411
487
  const { readdirSync, readFileSync } = require("fs") as typeof import("fs");
412
- const { join } = require("path") as typeof import("path");
488
+ const { join, relative } = require("path") as typeof import("path");
413
489
  const { commentMask } = require("./strip-js-comments") as typeof import("./strip-js-comments");
414
490
  const out: ScMentionInSource[] = [];
491
+ const unwalkable: ScSourceDirUnwalkable[] = [];
415
492
 
416
- const walk = (dir: string): void => {
493
+ /** True when the directory was opened. The return value is the whole fix. */
494
+ const walk = (dir: string): boolean => {
417
495
  let entries;
418
496
  try {
419
497
  entries = readdirSync(dir, { withFileTypes: true });
420
- } catch {
421
- return; // a source dir this consumer does not have
498
+ } catch (err) {
499
+ // A source dir this consumer does not have. Still not an error — but
500
+ // the caller hears about it, because "walked and found nothing" and
501
+ // "never opened" were the same answer until #606.
502
+ const rel = relative(root, dir);
503
+ unwalkable.push({
504
+ dir: rel === "" || rel.startsWith("..") ? dir : rel,
505
+ reason: (err as Error).message,
506
+ });
507
+ return false;
422
508
  }
423
509
  for (const e of entries) {
424
510
  if (e.name === "node_modules" || e.name === ".git") continue;
@@ -432,20 +518,42 @@ export function scMentionsInSource(root: string): ScMentionInSource[] {
432
518
  out.push({ id: m[0], file: p.slice(root.length + 1), inComment: mask[m.index!] === true });
433
519
  }
434
520
  }
521
+ return true;
435
522
  };
436
- for (const d of SC_SOURCE_DIRS) walk(join(root, d));
437
- return out;
523
+
524
+ const walked: string[] = [];
525
+ for (const d of SC_SOURCE_DIRS) if (walk(join(root, d))) walked.push(d);
526
+ return { mentions: out, walked, unwalkable };
438
527
  }
439
528
 
440
- /** Ids spelled in source, with the files that spell them. */
441
- export function scIdsSpelledInSource(root: string): Map<string, string[]> {
529
+ /** Ids spelled in source, with the files that spell them, and the coverage. */
530
+ export interface ScIdsSpelledReading {
531
+ ids: Map<string, string[]>;
532
+ walked: string[];
533
+ unwalkable: ScSourceDirUnwalkable[];
534
+ }
535
+
536
+ /**
537
+ * Ids spelled in source, keeping the walk's own account of where it looked.
538
+ *
539
+ * ONE place builds the id map, so `scIdsSpelledInSource` and the allocator's
540
+ * source-mentions leg cannot be two deciders that agree
541
+ * (`.claude/rules/checks-must-be-able-to-fail.md`, fourth shape).
542
+ */
543
+ export function scIdsSpelledInSourceReading(root: string): ScIdsSpelledReading {
544
+ const reading = scMentionsInSource(root);
442
545
  const found = new Map<string, string[]>();
443
- for (const m of scMentionsInSource(root)) {
546
+ for (const m of reading.mentions) {
444
547
  const files = found.get(m.id) ?? [];
445
548
  if (!files.includes(m.file)) files.push(m.file);
446
549
  found.set(m.id, files);
447
550
  }
448
- return found;
551
+ return { ids: found, walked: reading.walked, unwalkable: reading.unwalkable };
552
+ }
553
+
554
+ /** Ids spelled in source, with the files that spell them. */
555
+ export function scIdsSpelledInSource(root: string): Map<string, string[]> {
556
+ return scIdsSpelledInSourceReading(root).ids;
449
557
  }
450
558
 
451
559
  /**