rungate 0.8.2 → 0.8.3

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 (63) hide show
  1. package/bin/rungate.ts +11 -6
  2. package/config/prove-evidence.schema.json +21 -3
  3. package/gates/.gate-salt +1 -1
  4. package/gates/gate-executor.ts +153 -1
  5. package/gates/prove.test.ts +12 -6
  6. package/gates/schema.ts +69 -6
  7. package/gates/workflow.test.ts +12 -5
  8. package/hooks/DocHygiene.hook.ts +2 -1
  9. package/hooks/GateResultProtection.hook.ts +28 -7
  10. package/hooks/HookCurrency.hook.ts +48 -1
  11. package/hooks/VerifyPhaseLock.hook.ts +25 -8
  12. package/hooks/WorkflowStateGuard.hook.ts +24 -7
  13. package/lib/ai-review-jury.ts +725 -0
  14. package/lib/ai-review-rounds.ts +791 -4
  15. package/lib/ai-review-unmeasured.ts +361 -0
  16. package/lib/bash-write-guard.ts +1235 -102
  17. package/lib/cli-commands.ts +252 -11
  18. package/lib/closing-reference-audit.ts +163 -0
  19. package/lib/conformity.ts +12 -0
  20. package/lib/create-sc.ts +45 -12
  21. package/lib/derived-spec.ts +206 -0
  22. package/lib/file-claims.ts +335 -0
  23. package/lib/finding-arbiter.ts +502 -28
  24. package/lib/finding-jury.ts +48 -1
  25. package/lib/finding-pr-routing.ts +333 -0
  26. package/lib/frontmatter.ts +16 -0
  27. package/lib/gate-check-audit.ts +259 -0
  28. package/lib/generators/agents-md.ts +29 -0
  29. package/lib/github.ts +112 -7
  30. package/lib/hook-tree-currency.ts +494 -0
  31. package/lib/issue-closure-audit.ts +161 -14
  32. package/lib/issue-create-override.ts +53 -3
  33. package/lib/issue-filing-gate.ts +1073 -76
  34. package/lib/local-review-rounds.ts +523 -0
  35. package/lib/organize.ts +10 -0
  36. package/lib/project-state-shape.ts +56 -5
  37. package/lib/repo-path.ts +94 -0
  38. package/lib/report-provenance.ts +65 -3
  39. package/lib/risk-tier.ts +302 -0
  40. package/lib/rounds-to-pass.ts +274 -0
  41. package/lib/rule-row-drift.ts +199 -0
  42. package/lib/sc-claim-forms.ts +33 -5
  43. package/lib/sc-guard.ts +11 -1
  44. package/lib/sc-id-cross-tree.ts +17 -2
  45. package/lib/sc-ids.ts +71 -6
  46. package/lib/sc-reservations.ts +158 -14
  47. package/lib/scaffold/ai-review-findings.ts +1157 -18
  48. package/lib/scaffold/ai-review-step.ts +3798 -76
  49. package/lib/scaffold/ai-review-unmeasured-workflow.ts +243 -0
  50. package/lib/scaffold/owned-files.ts +14 -0
  51. package/lib/scaffold/steps.ts +83 -9
  52. package/lib/scratch-roots.ts +93 -3
  53. package/lib/spec-updater.ts +16 -0
  54. package/lib/validators/spec-validators.ts +28 -2
  55. package/package.json +2 -1
  56. package/scripts/ai-review-findings.ts +41 -1
  57. package/scripts/arbitrate-finding.ts +330 -12
  58. package/scripts/audit-specs.ts +225 -23
  59. package/scripts/create-sc.ts +11 -0
  60. package/scripts/detect-sc-drift.ts +10 -2
  61. package/scripts/record-ai-review-unmeasured.ts +370 -0
  62. package/scripts/split-spec.ts +12 -0
  63. package/scripts/sync-sc-status.ts +11 -0
@@ -0,0 +1,494 @@
1
+ /**
2
+ * How OLD are the bytes a hook registration resolves to (#1216).
3
+ *
4
+ * `lib/hook-target-tree.ts` answers *which directory* a registration names.
5
+ * This answers *which commit that directory is on*, and it exists because the
6
+ * first question has been standing in for the second — its own header says so
7
+ * at the end: `hook-target-tree` "answers which directory, never which
8
+ * commit", and `specs/HOOK-ARCHITECTURE-SPEC.md` repeats the caution under
9
+ * *Which tree the table was measured against*.
10
+ *
11
+ * ## The cost, measured twice in one day
12
+ *
13
+ * On 2026-10-23 the finding arbiter merged as #1282 and then adjudicated
14
+ * nothing for several hours. `RUNGATE_HOOKS_DIR` resolves to
15
+ * a hand-maintained working tree, and that tree was **14 commits behind
16
+ * `origin/main`** — it did not contain the arbiter that had just merged. A
17
+ * hand `fetch` + `merge --ff-only` turned it on, and it went stale again
18
+ * within hours, twice the same day (`62536bd3` → `9f2080d6` → `7817f1df`).
19
+ *
20
+ * Nothing on disk said which `main` those hooks were. **A hook that is absent
21
+ * and a hook that is fourteen commits old produce the same observation** —
22
+ * the code runs and finds nothing — and only one of them is a bug in the
23
+ * code.
24
+ *
25
+ * Same class as *An Unreleased Fix Looks Like a Fixed Bug*: a `lib/` fix is
26
+ * dormant until the next publish. Worse here, because a published package
27
+ * carries a version number and a working tree carries nothing at all.
28
+ *
29
+ * ## This is a READING. It does not move anything
30
+ *
31
+ * No `fetch`, no `merge`, no write of any kind. Silently updating a directory
32
+ * somebody is executing from is worse than saying it is old: the operator
33
+ * loses the one moment where they could have noticed, and a hook changing
34
+ * under a running session is a failure mode nobody is looking for. Every git
35
+ * invocation below is a query.
36
+ *
37
+ * Not fetching has a consequence the reading must own: the base is the
38
+ * TARGET directory's own `origin/main`, whose freshness depends on when that
39
+ * tree last fetched. A tree that has never fetched can read `current` against
40
+ * a remote-tracking ref that is itself months old. That is why every line
41
+ * names the base SHA — two directories reporting different `origin/main`
42
+ * SHAs is visible at a glance, and a reader who wants certainty can fetch by
43
+ * hand. Reporting a number without the ref it was taken against would be the
44
+ * same defect one level up.
45
+ *
46
+ * ## Three states, and the third is not a rounding of the first
47
+ *
48
+ * | state | means |
49
+ * |---|---|
50
+ * | `current` | the directory's HEAD contains every commit on the base |
51
+ * | `behind` | N commits on the base are not in that HEAD, N and both SHAs named |
52
+ * | `unmeasured` | not a working tree, absent, base unresolvable, or dirty |
53
+ *
54
+ * `unmeasured` never degrades to `current`. The whole defect is that a
55
+ * reading nobody could take looks exactly like a clean one — the three
56
+ * fail-open shapes in `lib/hook-target-tree.ts`'s header are the same list,
57
+ * one question earlier.
58
+ *
59
+ * **Uncommitted changes read as `unmeasured`, not `current`.** Bytes that
60
+ * correspond to no commit cannot be certified against one, and a hand-edited
61
+ * live hook is precisely how a tree gets code nothing merged. But dirtiness
62
+ * can only ever prevent a `current` reading — it never masks a `behind` one,
63
+ * because "14 behind, and also edited" is strictly more useful than
64
+ * "unmeasured".
65
+ *
66
+ * ## Where the reading has to appear
67
+ *
68
+ * Three surfaces were weighed; two are rejected here rather than in a PR
69
+ * comment, because the rejections are the argument for the one that was
70
+ * taken.
71
+ *
72
+ * - **A case in an existing suite.** CI has no `~/.claude/settings.json`, so
73
+ * on a runner the reading is UNMEASURED by construction — a permanent
74
+ * refusal, or a permanent skip. And it reaches whoever runs the suite,
75
+ * never the session whose hooks are the stale ones. Those are different
76
+ * people on different machines, and only the second can act.
77
+ * - **A line in each hook's own output.** Fourteen registrations firing on
78
+ * every tool call is a message an operator stops reading, which is the
79
+ * failure `hooks/HookCurrency.hook.ts`'s CADENCE note already argues
80
+ * against. It also inverts: the copy that is fourteen commits old is
81
+ * exactly the one that does not contain the reporting code, so the stale
82
+ * hooks would be the silent ones and the current hooks would do all the
83
+ * reporting.
84
+ * - **A startup report — taken.** Once per session, in the session whose
85
+ * hooks those are, printed beside `#879`'s reading, which is this one
86
+ * asked of `.git/hooks` instead.
87
+ *
88
+ * That third bullet's objection applies to the reporter too, and the answer
89
+ * is structural: `HookCurrency` is registered twice — through
90
+ * `${RUNGATE_HOOKS_DIR}` in `.claude/rungate/hooks.json`, which is subject to
91
+ * the staleness it reports, and through `${CLAUDE_PROJECT_DIR}` in the repo's
92
+ * `.claude/settings.json`, which resolves to the session's own checkout and
93
+ * is not. **A reporter must be reachable by a path that cannot be stale for
94
+ * the reason it reports**, and the second registration is what makes that
95
+ * true here.
96
+ *
97
+ * ## Why `ahead` is not a fourth state
98
+ *
99
+ * A directory carrying local commits on top of the base still contains every
100
+ * merged commit, so every merged fix reaches it. That is the question this
101
+ * module asks. Whether the extra commits should exist is a different one and
102
+ * `lib/hook-target-tree.ts` already refuses to answer two questions at once.
103
+ */
104
+
105
+ import {
106
+ type TargetTreeCensus,
107
+ readEnvScopes,
108
+ registeredTreeCensus,
109
+ } from "./hook-target-tree";
110
+ import { readRegistrationScopes } from "./hook-scopes";
111
+ import { gitIsolatedArgs, gitIsolatedEnv } from "./git-isolation";
112
+
113
+ /** One git query's result. `status` is the exit code; a non-zero one is a reading. */
114
+ export interface GitResult {
115
+ status: number;
116
+ stdout: string;
117
+ }
118
+
119
+ /**
120
+ * Run git in a directory.
121
+ *
122
+ * Injected rather than imported, for the reason `readFile` is injected into
123
+ * `readRegistrationScopes`: a function that reaches for `child_process`
124
+ * itself can only be tested against whatever repositories happen to be on the
125
+ * machine running the suite.
126
+ *
127
+ * It must NOT throw for a non-zero exit — a directory that is not a
128
+ * repository is the single most important case here, and an exception would
129
+ * have to be caught somewhere that could turn it into silence.
130
+ */
131
+ export type GitRunner = (dir: string, args: string[]) => GitResult;
132
+
133
+ /**
134
+ * `spawnSync`, narrowed to what the runner below needs.
135
+ *
136
+ * Injected so this module keeps no `child_process` import, for the same
137
+ * reason `readFile` is injected: a function that reaches for the machine can
138
+ * only be tested against the machine.
139
+ */
140
+ export type SpawnGit = (
141
+ command: string,
142
+ args: string[],
143
+ options: { encoding: "utf-8"; env: NodeJS.ProcessEnv; timeout: number },
144
+ ) => { status: number | null; stdout: string | null };
145
+
146
+ /** Per-invocation budget. A wedged directory must become a reading, not a hang. */
147
+ export const GIT_TIMEOUT_MS = 5_000;
148
+
149
+ /**
150
+ * The ONE isolated runner, and the only one anything in production may use.
151
+ *
152
+ * ## Why this is not an optional hardening
153
+ *
154
+ * `git -C <dir>` reads that directory's `.git/config`, and several of its
155
+ * keys are EXECUTABLE: `core.fsmonitor` is a command git runs, `core.hooksPath`
156
+ * points at hooks git fires, `core.excludesFile` decides what git can see.
157
+ * `lib/git-isolation.ts` holds the measured table.
158
+ *
159
+ * The exposure is sharper here than at any other call site in this tree,
160
+ * and it comes from the feature's own premise. The directories this module
161
+ * reads are the ones `RUNGATE_HOOKS_DIR` and friends resolve to — a
162
+ * hand-maintained worktree that **this module exists because nobody is
163
+ * watching**. And it runs at SessionStart, in every session on the machine.
164
+ * An unisolated reader would be a hook written to report that an unsupervised
165
+ * directory is stale, which executes whatever that unsupervised directory
166
+ * tells it to.
167
+ *
168
+ * Measured 2026-10-23 on a planted repository with the key in its own
169
+ * `.git/config` (not `~/.gitconfig`), git 2.x:
170
+ *
171
+ * | poisoned key | unisolated | isolated |
172
+ * |---|---|---|
173
+ * | `core.fsmonitor` → a script writing a marker | **marker written twice — git ran it** | not run |
174
+ * | `core.excludesFile` → a list naming the edited hook | **`current`** | `unmeasured` |
175
+ *
176
+ * The second row is the one specific to this module: poisoning
177
+ * `core.excludesFile` in the unwatched tree blinds the uncommitted-bytes
178
+ * check, so a hand-edited hook certifies as matching a merged commit. The
179
+ * directory gets to lie about its own cleanliness to the reading whose job
180
+ * is to catch exactly that.
181
+ *
182
+ * `safe.directory` comes along from `GIT_ISOLATION_CONFIG` and is
183
+ * load-bearing rather than a loosening — neutralising the global file
184
+ * removes the ownership exception with it, and reading a worktree we
185
+ * deliberately do not own is this module's whole job.
186
+ *
187
+ * Both halves or neither: the `-c` flags are the only thing covering the
188
+ * checkout's own `.git/config`, and the env vars are the only thing covering
189
+ * files nobody enumerated. That is why one binding builds both, instead of a
190
+ * convention each caller follows.
191
+ */
192
+ export function spawnGitRunner(spawn: SpawnGit, timeoutMs = GIT_TIMEOUT_MS): GitRunner {
193
+ const env = gitIsolatedEnv();
194
+ return (dir, args) => {
195
+ const r = spawn("git", gitIsolatedArgs(["-C", dir, ...args]), {
196
+ encoding: "utf-8",
197
+ env,
198
+ timeout: timeoutMs,
199
+ });
200
+ // A timed-out or killed child reports `status: null`. Mapping that to a
201
+ // non-zero code makes it UNMEASURED, which is the honest reading — the
202
+ // alternative is a SessionStart that hangs on a poisoned fsmonitor.
203
+ return { status: r.status ?? 1, stdout: r.stdout ?? "" };
204
+ };
205
+ }
206
+
207
+ export type CurrencyState = "current" | "behind" | "unmeasured";
208
+
209
+ export interface DirectoryCurrency {
210
+ dir: string;
211
+ state: CurrencyState;
212
+ /** Commits on the base that this HEAD does not contain. `null` unless `behind`. */
213
+ behind: number | null;
214
+ /** The ref the comparison was taken against, as written. */
215
+ base: string;
216
+ /** What the base resolved to IN THIS DIRECTORY, so a reader can compare two rows. */
217
+ baseSha: string | null;
218
+ headSha: string | null;
219
+ /** How many hook registrations execute out of this directory. */
220
+ registrations: number;
221
+ detail: string;
222
+ }
223
+
224
+ export interface RegistrationCurrency {
225
+ reading: "MEASURED" | "UNMEASURED";
226
+ unmeasuredReasons: string[];
227
+ /** One row per distinct directory, sorted, worst state first. */
228
+ directories: DirectoryCurrency[];
229
+ /** Registrations whose path never resolved to a directory at all. */
230
+ unresolved: number;
231
+ /** Registrations this run looked at. Zero is UNMEASURED, not agreement. */
232
+ examined: number;
233
+ }
234
+
235
+ const SHORT = 8;
236
+
237
+ function short(sha: string): string {
238
+ return sha.slice(0, SHORT);
239
+ }
240
+
241
+ function unmeasured(
242
+ dir: string,
243
+ base: string,
244
+ registrations: number,
245
+ reason: string,
246
+ ): DirectoryCurrency {
247
+ return {
248
+ dir,
249
+ state: "unmeasured",
250
+ behind: null,
251
+ base,
252
+ baseSha: null,
253
+ headSha: null,
254
+ registrations,
255
+ detail: `${dir} could not be compared with ${base}: ${reason}`,
256
+ };
257
+ }
258
+
259
+ /**
260
+ * The currency of ONE directory.
261
+ *
262
+ * Ordered so each refusal names the cheapest distinct cause. A single
263
+ * "could not read it" would be a refusal nobody can act on — "not a working
264
+ * tree" and "the tree has no `origin/main`" need different repairs, and the
265
+ * second one is a tree someone cloned without a remote, not a stale one.
266
+ */
267
+ export function directoryCurrency(
268
+ dir: string,
269
+ base: string,
270
+ git: GitRunner,
271
+ registrations = 0,
272
+ ): DirectoryCurrency {
273
+ const top = git(dir, ["rev-parse", "--show-toplevel"]);
274
+ if (top.status !== 0) {
275
+ return unmeasured(
276
+ dir,
277
+ base,
278
+ registrations,
279
+ "it is not inside a git working tree — it is absent, or it is a hand-copied directory, and " +
280
+ "either way nothing there relates those bytes to any merged commit",
281
+ );
282
+ }
283
+
284
+ const head = git(dir, ["rev-parse", "--verify", "--quiet", "HEAD^{commit}"]);
285
+ if (head.status !== 0 || head.stdout.trim() === "") {
286
+ return unmeasured(dir, base, registrations, "it has no HEAD commit");
287
+ }
288
+
289
+ const tip = git(dir, ["rev-parse", "--verify", "--quiet", `${base}^{commit}`]);
290
+ if (tip.status !== 0 || tip.stdout.trim() === "") {
291
+ return unmeasured(
292
+ dir,
293
+ base,
294
+ registrations,
295
+ `${base} is not a ref in that tree, so nothing there says which ${base} those bytes came ` +
296
+ `from. This reading never fetches, so an unfetched remote is a refusal and not a pass`,
297
+ );
298
+ }
299
+
300
+ const headSha = head.stdout.trim();
301
+ const baseSha = tip.stdout.trim();
302
+
303
+ // `HEAD..base` — commits reachable from the base that this HEAD does not
304
+ // contain. The direction is the whole measurement: transposed, the live
305
+ // tree measured on 2026-10-23 reads 1 rather than 14, and 14 is the number
306
+ // that matters. `test/unit/hook-tree-currency.test.ts` pins it with a
307
+ // fixture that is behind by 3 AND ahead by 1, so no transposition can
308
+ // produce the expected count.
309
+ const count = git(dir, ["rev-list", "--count", `${headSha}..${baseSha}`]);
310
+ const raw = count.stdout.trim();
311
+ if (count.status !== 0 || !/^\d+$/.test(raw)) {
312
+ return unmeasured(
313
+ dir,
314
+ base,
315
+ registrations,
316
+ `the commit count between HEAD and ${base} could not be read`,
317
+ );
318
+ }
319
+ const behind = Number(raw);
320
+
321
+ if (behind > 0) {
322
+ return {
323
+ dir,
324
+ state: "behind",
325
+ behind,
326
+ base,
327
+ baseSha,
328
+ headSha,
329
+ registrations,
330
+ detail:
331
+ `${dir} is at ${short(headSha)}, ${behind} commit(s) behind ${base} ` +
332
+ `(${short(baseSha)}) in that tree. Anything merged in those ${behind} commit(s) is on ` +
333
+ `main and is not running`,
334
+ };
335
+ }
336
+
337
+ // Only reached when the directory is otherwise current, by design: see the
338
+ // header. A dirty tree that is also behind keeps its `behind` reading.
339
+ const dirty = git(dir, ["status", "--porcelain", "--", dir]);
340
+ if (dirty.status !== 0) {
341
+ return unmeasured(dir, base, registrations, "its working-tree status could not be read");
342
+ }
343
+ const modified = dirty.stdout.split("\n").filter(l => l.trim() !== "").length;
344
+ if (modified > 0) {
345
+ return unmeasured(
346
+ dir,
347
+ base,
348
+ registrations,
349
+ `its HEAD is ${base} (${short(baseSha)}) but ${modified} path(s) under it are uncommitted, ` +
350
+ `so the bytes that execute correspond to no commit`,
351
+ );
352
+ }
353
+
354
+ return {
355
+ dir,
356
+ state: "current",
357
+ behind: 0,
358
+ base,
359
+ baseSha,
360
+ headSha,
361
+ registrations,
362
+ detail: `${dir} is at ${short(headSha)}, which contains every commit on ${base}`,
363
+ };
364
+ }
365
+
366
+ /** `current` last, so the rows that need acting on are the ones at the top. */
367
+ const ORDER: Record<CurrencyState, number> = { behind: 0, unmeasured: 1, current: 2 };
368
+
369
+ /**
370
+ * The currency of every directory a resolved registration lands in.
371
+ *
372
+ * Takes the census rather than re-resolving anything: `registeredTreeCensus`
373
+ * is the one binding that decides which directory a registration names, and a
374
+ * second resolver here would be two deciders for one question
375
+ * (`.claude/rules/checks-must-be-able-to-fail.md`, the fourth shape).
376
+ *
377
+ * This is also `registeredTreeCensus`'s first caller outside `test/`. It was
378
+ * shipped by #1006 and nothing in production has ever called it — a library
379
+ * function with no production caller is not shipped, however well tested.
380
+ */
381
+ export function registrationCurrency(
382
+ census: TargetTreeCensus,
383
+ base: string,
384
+ git: GitRunner,
385
+ ): RegistrationCurrency {
386
+ const reasons = [...census.unmeasuredReasons];
387
+
388
+ const perDir = new Map<string, number>();
389
+ for (const r of [...census.inRepo, ...census.foreign]) {
390
+ if (r.resolved === null) continue;
391
+ const dir = r.resolved.slice(0, r.resolved.lastIndexOf("/"));
392
+ perDir.set(dir, (perDir.get(dir) ?? 0) + 1);
393
+ }
394
+
395
+ const directories = [...perDir.entries()]
396
+ .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
397
+ .map(([dir, n]) => directoryCurrency(dir, base, git, n));
398
+
399
+ for (const d of directories) {
400
+ if (d.state !== "current") reasons.push(d.detail);
401
+ }
402
+
403
+ if (directories.length === 0) {
404
+ reasons.push(
405
+ `no registration resolved to a directory, so no tree's age was read. Zero directories ` +
406
+ `compared is not agreement — an empty row list here means the run found nothing to ` +
407
+ `look at`,
408
+ );
409
+ }
410
+
411
+ return {
412
+ reading: reasons.length === 0 ? "MEASURED" : "UNMEASURED",
413
+ unmeasuredReasons: reasons,
414
+ directories: directories.sort((a, b) => ORDER[a.state] - ORDER[b.state]),
415
+ unresolved: census.unresolved.length,
416
+ examined: census.examined,
417
+ };
418
+ }
419
+
420
+ /**
421
+ * Assemble the whole reading from a machine.
422
+ *
423
+ * Every input is injected — `readFile`, the owned-hook list, the registry
424
+ * commands and `git` — so this module keeps no `fs` and no `child_process`
425
+ * import and a case can drive an absent scope, an empty tree or a directory
426
+ * that is not a repository without touching the machine running the suite.
427
+ * `lib/hook-scopes.ts` and `lib/hook-target-tree.ts` are both built this way
428
+ * and the reason is the same one.
429
+ *
430
+ * `base` has no default. A default here would be a second place deciding
431
+ * which branch a tree is measured against, and the caller already has to
432
+ * know (`.claude/rules/config-access.md`: a built-in substituted silently is
433
+ * the anti-pattern).
434
+ */
435
+ export function readRegistrationCurrency(input: {
436
+ repoRoot: string;
437
+ home: string;
438
+ base: string;
439
+ readFile: (path: string) => string | null;
440
+ ownedHooks: string[];
441
+ registryCommands: string[];
442
+ git: GitRunner;
443
+ }): RegistrationCurrency {
444
+ const census = registeredTreeCensus(
445
+ input.ownedHooks,
446
+ readRegistrationScopes(input.repoRoot, input.home, input.readFile, input.registryCommands),
447
+ readEnvScopes(input.repoRoot, input.home, input.readFile),
448
+ input.repoRoot,
449
+ );
450
+ return registrationCurrency(census, input.base, input.git);
451
+ }
452
+
453
+ /**
454
+ * The reading, as lines a human reads at session start.
455
+ *
456
+ * The headline carries all three counts rather than picking a class, so a
457
+ * `behind` row and an `unmeasured` row can never hide behind each other —
458
+ * which is the shape of the defect, not a formatting preference. Directories
459
+ * that are `current` get no row: they are the ones nobody has to do anything
460
+ * about, and a report whose every line is routine is a report nobody reads.
461
+ */
462
+ export function currencyReportLines(r: RegistrationCurrency): string[] {
463
+ const n = (s: CurrencyState) => r.directories.filter(d => d.state === s).length;
464
+ const behind = n("behind");
465
+ const unread = n("unmeasured");
466
+ const current = n("current");
467
+ const total = r.directories.length;
468
+
469
+ if (total === 0) {
470
+ return [`Hook tree currency UNMEASURED: ${r.unmeasuredReasons.join("; ")}`];
471
+ }
472
+
473
+ const lines: string[] = [
474
+ behind === 0 && unread === 0
475
+ ? `Hook tree currency: ${current} director(ies) current with ${r.directories[0]!.base}`
476
+ : `Hook tree currency: ${current} current, ${behind} BEHIND, ${unread} UNMEASURED — ` +
477
+ `of ${total} director(ies) hook registrations execute from`,
478
+ ];
479
+
480
+ for (const d of r.directories) {
481
+ if (d.state === "current") continue;
482
+ const tag = d.state === "behind" ? `BEHIND ${d.behind}` : "UNMEASURED";
483
+ lines.push(` ${tag}: ${d.detail} [${d.registrations} registration(s)]`);
484
+ }
485
+
486
+ if (r.unresolved > 0) {
487
+ lines.push(
488
+ ` UNMEASURED: ${r.unresolved} registration(s) name a path that resolves to no directory ` +
489
+ `at all, so their age was not read either`,
490
+ );
491
+ }
492
+
493
+ return lines;
494
+ }