rungate 0.5.0 → 0.7.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/lib/affected-tests.ts +398 -0
- package/lib/agent-audit.ts +2 -3
- package/lib/agent-worktree.ts +287 -0
- package/lib/agents-md-sections.ts +209 -0
- package/lib/behavioral-cache.ts +150 -2
- package/lib/branch-diff.ts +139 -0
- package/lib/branch-protection.ts +790 -0
- package/lib/brief-ac-alignment.ts +104 -0
- package/lib/brief-references.ts +205 -0
- package/lib/bun-version.ts +347 -0
- package/lib/check-remedy.ts +140 -0
- package/lib/ci-checkout.ts +18 -1
- package/lib/ci-history-depth.ts +159 -0
- package/lib/ci-setup-step.ts +96 -0
- package/lib/claude-code-action.ts +85 -0
- package/lib/claude-tool-vocabulary.ts +188 -0
- package/lib/cli-commands.ts +15 -0
- package/lib/commit-sha.ts +42 -0
- package/lib/commit-subject.ts +90 -0
- package/lib/compliance-report.ts +377 -45
- package/lib/compliance.ts +196 -20
- package/lib/config-loader.ts +51 -1
- package/lib/config-trackable.ts +391 -0
- package/lib/conformity.ts +1272 -189
- package/lib/containment.ts +238 -0
- package/lib/content-hash.ts +24 -0
- package/lib/context-docs.ts +143 -28
- package/lib/create-brief.ts +2 -1
- package/lib/create-sc.ts +323 -4
- package/lib/dev-liveness.ts +180 -0
- package/lib/discovery-branch-points.ts +432 -0
- package/lib/discovery-stability.ts +481 -0
- package/lib/distribution-currency.ts +186 -0
- package/lib/doc-routing.ts +157 -0
- package/lib/doc-scan-targets.ts +9 -0
- package/lib/evidence-command-transport.ts +160 -0
- package/lib/evidence-prevalidator.ts +246 -2
- package/lib/evidence-satisfiability.ts +534 -12
- package/lib/failure-intake.ts +317 -0
- package/lib/fallow-availability.ts +286 -0
- package/lib/fs-write-capabilities.ts +232 -0
- package/lib/gate-refusal-currency.ts +112 -0
- package/lib/gate-run-split.ts +147 -0
- package/lib/gate-timeouts.ts +82 -0
- package/lib/generators/agent-briefs.ts +4 -1
- package/lib/generators/agents-md.ts +204 -48
- package/lib/generators/code-map.ts +2 -1
- package/lib/generators/types.ts +8 -0
- package/lib/git-dates.ts +55 -0
- package/lib/git-isolation.ts +140 -0
- package/lib/github.ts +15 -0
- package/lib/google-auth-action.ts +93 -0
- package/lib/harness-project.ts +48 -0
- package/lib/harness-provenance.ts +255 -0
- package/lib/hook-evidence.ts +235 -0
- package/lib/hook-scopes.ts +386 -0
- package/lib/hook-target-tree.ts +398 -0
- package/lib/hook-trees.ts +447 -0
- package/lib/js-top-level-code.ts +78 -10
- package/lib/junit-checks.ts +536 -0
- package/lib/launch-base.ts +253 -0
- package/lib/line-citation.ts +372 -0
- package/lib/local-calendar-day.ts +78 -0
- package/lib/orphan-reaper.ts +468 -0
- package/lib/parity-binding.ts +205 -0
- package/lib/per-test-timeouts.ts +219 -0
- package/lib/plan-coverage.ts +151 -0
- package/lib/prior-branch.ts +201 -8
- package/lib/process-table.ts +146 -0
- package/lib/project-state-derivation.ts +219 -0
- package/lib/project-state-root.ts +258 -0
- package/lib/project-state-shape.ts +59 -0
- package/lib/promote-outputs.ts +6 -2
- package/lib/published-artifact.ts +525 -0
- package/lib/readdir-sorted.ts +45 -0
- package/lib/report-provenance.ts +156 -0
- package/lib/review-execution-reading.ts +206 -0
- package/lib/review-tool-agreement.ts +433 -0
- package/lib/rule-promotion.ts +234 -0
- package/lib/rule-retirement.ts +525 -0
- package/lib/run-branch.ts +612 -0
- package/lib/rungate-schema.ts +19 -0
- package/lib/runner-home.ts +274 -0
- package/lib/sc-claim-forms.ts +75 -0
- package/lib/sc-id-cross-tree.ts +323 -0
- package/lib/sc-ids.ts +121 -13
- package/lib/sc-reservations.ts +289 -0
- package/lib/scaffold/ai-review-findings.ts +403 -0
- package/lib/scaffold/ai-review-step.ts +4777 -0
- package/lib/scaffold/managed-workflow.ts +587 -192
- package/lib/scaffold/owned-files.ts +186 -39
- package/lib/scaffold/pre-push-hook.ts +49 -5
- package/lib/scaffold/rehearsal.ts +205 -71
- package/lib/scaffold/steps.ts +1517 -293
- package/lib/scaffold/workflow-census.ts +217 -0
- package/lib/scaffold/workflow-drift.ts +217 -0
- package/lib/scaffold/write-steps.ts +10 -4
- package/lib/scan-budget.ts +247 -0
- package/lib/scanner.ts +80 -62
- package/lib/scratch-roots.ts +50 -5
- package/lib/screenshot-discovery.ts +121 -0
- package/lib/screenshot-upload.ts +41 -1
- package/lib/secret-patterns.ts +511 -8
- package/lib/ship-mode.ts +219 -0
- package/lib/source-slice.ts +294 -0
- package/lib/spec-listing.ts +148 -0
- package/lib/spec-requirements.ts +209 -0
- package/lib/stale-cleanup.ts +37 -3
- package/lib/suite-flake.ts +278 -0
- package/lib/suite-measurement.ts +23 -4
- package/lib/suite-run-reading.ts +411 -1
- package/lib/suite-timeout-margin.ts +193 -0
- package/lib/test-case-bodies.ts +883 -0
- package/lib/test-case-deletion.ts +653 -0
- package/lib/test-census.ts +97 -29
- package/lib/test-command-positions.ts +274 -0
- package/lib/test-command.ts +133 -0
- package/lib/test-suite-lock.ts +325 -26
- package/lib/tool-probe.ts +142 -0
- package/lib/top-level-cd.ts +393 -0
- package/lib/tracked-vs-ignored.ts +234 -0
- package/lib/tree-entries.ts +89 -0
- package/lib/ts-ast.ts +200 -0
- package/lib/validators/spec-validators.ts +3 -2
- package/lib/walk-test-files.ts +97 -0
- package/lib/workflow-actions.ts +263 -0
- package/lib/worktree-collect.ts +177 -5
- package/lib/worktree-repo.ts +36 -1
- package/package.json +2 -1
- package/scripts/ai-review-findings.ts +45 -0
- package/scripts/audit-specs.ts +247 -12
- package/scripts/audit-transcript.ts +2 -1
- package/scripts/convert-spec.ts +2 -1
- package/scripts/create-sc.ts +37 -7
- package/scripts/create-spec.ts +2 -1
- package/scripts/create-success.ts +2 -1
- package/scripts/extract-constraints.ts +197 -26
- package/scripts/generate-code-map.ts +62 -28
- package/scripts/scaffold-project.ts +12 -2
- package/scripts/split-spec.ts +2 -1
- package/scripts/sync-sc-status.ts +127 -14
- package/scripts/sync-spec-tests.ts +2 -1
|
@@ -0,0 +1,386 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Every settings scope, read before anything is concluded about one hook
|
|
3
|
+
* (#713, #910).
|
|
4
|
+
*
|
|
5
|
+
* A LEAF module whose only relative dependency is `hook-trees`, so there is
|
|
6
|
+
* one thing to mutate and one extractor deciding what a command is.
|
|
7
|
+
*
|
|
8
|
+
* ## The defect this exists to make unavailable
|
|
9
|
+
*
|
|
10
|
+
* Twice in three weeks, a census counted the hooks in ONE settings scope,
|
|
11
|
+
* found zero, and reported that as absence.
|
|
12
|
+
*
|
|
13
|
+
* - #713 read `~/.claude/settings.json` and reported `AgentBriefGuard` "dead
|
|
14
|
+
* in both trees — wired nowhere". It is registered in the repo's PROJECT
|
|
15
|
+
* settings as `bun ${CLAUDE_PROJECT_DIR}/hooks/AgentBriefGuard.hook.ts`.
|
|
16
|
+
* - #910 read this repository's own registries and reported
|
|
17
|
+
* `TestSuiteRelease.hook.ts` and `ProjectStateSync.hook.ts` "in NO registry"
|
|
18
|
+
* and never able to fire. Both are registered in `~/.claude/settings.json`
|
|
19
|
+
* and have been throughout — measured 2026-10-21, parsed rather than
|
|
20
|
+
* grepped.
|
|
21
|
+
*
|
|
22
|
+
* Same error, opposite scope. `lib/hook-trees.ts` records the first one in its
|
|
23
|
+
* own header and says *"Read EVERY settings scope before concluding anything
|
|
24
|
+
* about one hook"*, and a census that read one shipped anyway. A sentence in a
|
|
25
|
+
* docblock is not a rule (`.claude/rules/config-access.md`).
|
|
26
|
+
*
|
|
27
|
+
* ## Why this is a refusal and not a wider reader
|
|
28
|
+
*
|
|
29
|
+
* The repair that suggests itself is to read more scopes. That is
|
|
30
|
+
* `.claude/rules/checks-must-be-able-to-fail.md`'s fifth shape waiting to
|
|
31
|
+
* happen: it fixes the two instances and leaves the next narrow reading free
|
|
32
|
+
* to report confident absence again, because nothing says a reading has to be
|
|
33
|
+
* complete before a verdict comes out of it.
|
|
34
|
+
*
|
|
35
|
+
* So `hookRegistration` THROWS unless it is handed a reading for every scope
|
|
36
|
+
* in `REGISTRATION_SCOPES`, and an unreadable scope must carry a reason. A
|
|
37
|
+
* caller that opened one file gets a refusal, not an answer.
|
|
38
|
+
*
|
|
39
|
+
* ## The asymmetry, which is the correctness argument
|
|
40
|
+
*
|
|
41
|
+
* A POSITIVE is conclusive from a single scope: a command naming the hook is
|
|
42
|
+
* a registration, whatever the other four say. A NEGATIVE is conclusive from
|
|
43
|
+
* no number of scopes short of all of them. So:
|
|
44
|
+
*
|
|
45
|
+
* | reading | verdict |
|
|
46
|
+
* |---|---|
|
|
47
|
+
* | named by at least one scope | `registered` |
|
|
48
|
+
* | named by none, every scope read | `unregistered` |
|
|
49
|
+
* | named by none, some scope unreadable | `unmeasured` |
|
|
50
|
+
*
|
|
51
|
+
* `unmeasured` is the state CI is in — `~/.claude/settings.json` is machine
|
|
52
|
+
* state and no runner has one — and it is reported rather than skipped,
|
|
53
|
+
* because `0`, `{}`, `null`, `SKIP` and a skipped test are indistinguishable
|
|
54
|
+
* from success and a reading is not.
|
|
55
|
+
*/
|
|
56
|
+
|
|
57
|
+
import { join } from "path";
|
|
58
|
+
|
|
59
|
+
import { commandNamesHook, settingsCommands } from "./hook-trees";
|
|
60
|
+
|
|
61
|
+
/**
|
|
62
|
+
* Every position that can register a hook, in one declaring position.
|
|
63
|
+
*
|
|
64
|
+
* `repo-registry` is `.claude/rungate/hooks.json` through
|
|
65
|
+
* `lib/config-loader.ts`, not a settings document, so it has no path here —
|
|
66
|
+
* see `settingsScopePaths`, and the case asserting the two cover this list
|
|
67
|
+
* between them.
|
|
68
|
+
*
|
|
69
|
+
* Adding a scope is one edit, and it makes every existing reading incomplete
|
|
70
|
+
* until its callers supply the new one. That is the intended cost: a scope
|
|
71
|
+
* nobody reads must not be a scope a verdict silently ignores.
|
|
72
|
+
*/
|
|
73
|
+
export const REGISTRATION_SCOPES = [
|
|
74
|
+
"repo-registry",
|
|
75
|
+
"project-settings",
|
|
76
|
+
"project-local-settings",
|
|
77
|
+
"user-settings",
|
|
78
|
+
"user-local-settings",
|
|
79
|
+
] as const;
|
|
80
|
+
|
|
81
|
+
export type RegistrationScope = (typeof REGISTRATION_SCOPES)[number];
|
|
82
|
+
|
|
83
|
+
export interface ScopeReading {
|
|
84
|
+
scope: RegistrationScope;
|
|
85
|
+
/** Commands read from this scope. `null` means the scope could not be read. */
|
|
86
|
+
commands: string[] | null;
|
|
87
|
+
/** Why it could not be read. REQUIRED when `commands` is null. */
|
|
88
|
+
unreadable?: string;
|
|
89
|
+
}
|
|
90
|
+
|
|
91
|
+
/** A reading that cannot support a verdict. Never a verdict of its own. */
|
|
92
|
+
export class IncompleteScopeReadingError extends Error {
|
|
93
|
+
constructor(message: string) {
|
|
94
|
+
super(message);
|
|
95
|
+
this.name = "IncompleteScopeReadingError";
|
|
96
|
+
}
|
|
97
|
+
}
|
|
98
|
+
|
|
99
|
+
export type RegistrationVerdict = "registered" | "unregistered" | "unmeasured";
|
|
100
|
+
|
|
101
|
+
export interface HookRegistration {
|
|
102
|
+
hook: string;
|
|
103
|
+
verdict: RegistrationVerdict;
|
|
104
|
+
/** The scopes whose commands name this hook. */
|
|
105
|
+
registeredIn: RegistrationScope[];
|
|
106
|
+
/** The scopes this run could not read. */
|
|
107
|
+
unreadable: RegistrationScope[];
|
|
108
|
+
detail: string;
|
|
109
|
+
}
|
|
110
|
+
|
|
111
|
+
/**
|
|
112
|
+
* Who owns a scope, which decides what an ABSENT file means there.
|
|
113
|
+
*
|
|
114
|
+
* This distinction is the whole of #199 and #479 and it is easy to lose. For
|
|
115
|
+
* a scope the repo owns, a file that is not there is a complete reading: it
|
|
116
|
+
* registers nothing, and that is a fact CI can assert. For a scope on the
|
|
117
|
+
* machine, a file that is not there is **no reading at all** — every runner
|
|
118
|
+
* lacks `~/.claude/settings.json`, and treating that as "registers nothing"
|
|
119
|
+
* is how a check comes to report hooks unregistered that are registered.
|
|
120
|
+
*
|
|
121
|
+
* Collapsing the two was measured, not reasoned about: with every absent file
|
|
122
|
+
* read as unreadable, this repo has no `.claude/settings.local.json`, so
|
|
123
|
+
* every verdict on every machine carried an unreadable scope and `AC-4` could
|
|
124
|
+
* never conclude `unregistered` — a check that cannot fail
|
|
125
|
+
* (`.claude/rules/checks-must-be-able-to-fail.md`). Found by battery row M6
|
|
126
|
+
* coming back 4 against a predicted 1.
|
|
127
|
+
*/
|
|
128
|
+
export type ScopeOwnership = "repo" | "machine";
|
|
129
|
+
|
|
130
|
+
/**
|
|
131
|
+
* Where each settings scope lives, given a repo root and a home directory.
|
|
132
|
+
*
|
|
133
|
+
* Takes both rather than reading `process.env` or `homedir()`, for the reason
|
|
134
|
+
* `reconcile` takes documents: a function that reads ambient state can only be
|
|
135
|
+
* tested against ambient state.
|
|
136
|
+
*/
|
|
137
|
+
export function settingsScopePaths(
|
|
138
|
+
repoRoot: string,
|
|
139
|
+
home: string,
|
|
140
|
+
): { scope: RegistrationScope; path: string; ownership: ScopeOwnership }[] {
|
|
141
|
+
return [
|
|
142
|
+
{
|
|
143
|
+
scope: "project-settings",
|
|
144
|
+
path: join(repoRoot, ".claude", "settings.json"),
|
|
145
|
+
ownership: "repo",
|
|
146
|
+
},
|
|
147
|
+
{
|
|
148
|
+
scope: "project-local-settings",
|
|
149
|
+
path: join(repoRoot, ".claude", "settings.local.json"),
|
|
150
|
+
ownership: "repo",
|
|
151
|
+
},
|
|
152
|
+
{ scope: "user-settings", path: join(home, ".claude", "settings.json"), ownership: "machine" },
|
|
153
|
+
{
|
|
154
|
+
scope: "user-local-settings",
|
|
155
|
+
path: join(home, ".claude", "settings.local.json"),
|
|
156
|
+
ownership: "machine",
|
|
157
|
+
},
|
|
158
|
+
];
|
|
159
|
+
}
|
|
160
|
+
|
|
161
|
+
/**
|
|
162
|
+
* Assemble a complete reading from a filesystem.
|
|
163
|
+
*
|
|
164
|
+
* ONE binding for "which scopes exist and how are they read", so a caller
|
|
165
|
+
* cannot have its own idea of the scope list — three files in this tree did,
|
|
166
|
+
* and two of them were wrong in opposite directions.
|
|
167
|
+
*
|
|
168
|
+
* `readFile` is injected and returns `null` for a file that is not there, so
|
|
169
|
+
* this module keeps no `fs` import and a case can drive an absent scope
|
|
170
|
+
* without touching the machine. A file that EXISTS and cannot be read or
|
|
171
|
+
* parsed must throw out of `readFile` or out of `settingsCommands` — a
|
|
172
|
+
* corrupt settings file is not a settings file with no hooks in it
|
|
173
|
+
* (`.claude/rules/config-access.md`).
|
|
174
|
+
*
|
|
175
|
+
* `repoRegistryCommands` comes from the caller because the registry is
|
|
176
|
+
* resolved by `lib/config-loader.ts`, which supports two layouts and is not a
|
|
177
|
+
* settings document.
|
|
178
|
+
*
|
|
179
|
+
* What an absent file means depends on who owns the scope — see
|
|
180
|
+
* `ScopeOwnership`. The result is validated before it is returned: a reader
|
|
181
|
+
* that assembled an incomplete reading must fail where it read, not where
|
|
182
|
+
* somebody later drew a conclusion from it.
|
|
183
|
+
*/
|
|
184
|
+
export function readRegistrationScopes(
|
|
185
|
+
repoRoot: string,
|
|
186
|
+
home: string,
|
|
187
|
+
readFile: (path: string) => string | null,
|
|
188
|
+
repoRegistryCommands: string[],
|
|
189
|
+
): ScopeReading[] {
|
|
190
|
+
const readings: ScopeReading[] = settingsScopePaths(repoRoot, home).map(
|
|
191
|
+
({ scope, path, ownership }) => {
|
|
192
|
+
const doc = readFile(path);
|
|
193
|
+
if (doc !== null) return { scope, commands: settingsCommands([doc]) };
|
|
194
|
+
if (ownership === "repo") {
|
|
195
|
+
// A committed scope that is not in the tree registers nothing, and
|
|
196
|
+
// that is a reading rather than the absence of one.
|
|
197
|
+
return { scope, commands: [] };
|
|
198
|
+
}
|
|
199
|
+
return {
|
|
200
|
+
scope,
|
|
201
|
+
commands: null,
|
|
202
|
+
unreadable: `${path} is not on this machine, and it is machine state the repo does not own`,
|
|
203
|
+
};
|
|
204
|
+
},
|
|
205
|
+
);
|
|
206
|
+
readings.push({ scope: "repo-registry", commands: repoRegistryCommands });
|
|
207
|
+
assertEveryScopeRead(readings);
|
|
208
|
+
return readings;
|
|
209
|
+
}
|
|
210
|
+
|
|
211
|
+
/**
|
|
212
|
+
* Refuse a reading that cannot support a verdict.
|
|
213
|
+
*
|
|
214
|
+
* Exported so a caller can establish completeness once before a loop, and so
|
|
215
|
+
* there is exactly one binding deciding what "complete" means. Every entry
|
|
216
|
+
* point below goes through it; none re-derives the question.
|
|
217
|
+
*/
|
|
218
|
+
export function assertEveryScopeRead(readings: ScopeReading[]): void {
|
|
219
|
+
const seen = readings.map(r => r.scope);
|
|
220
|
+
const missing = REGISTRATION_SCOPES.filter(s => !seen.includes(s));
|
|
221
|
+
if (missing.length > 0) {
|
|
222
|
+
throw new IncompleteScopeReadingError(
|
|
223
|
+
`a registration verdict needs a reading for every scope and ${missing.join(", ")} ` +
|
|
224
|
+
`${missing.length === 1 ? "was" : "were"} not supplied. Reading one scope and taking zero ` +
|
|
225
|
+
`hits as absence is #713 and #910; supply the scope with commands, or with ` +
|
|
226
|
+
`commands: null and a reason saying why it could not be read.`,
|
|
227
|
+
);
|
|
228
|
+
}
|
|
229
|
+
const duplicated = [...new Set(seen.filter((s, i) => seen.indexOf(s) !== i))];
|
|
230
|
+
if (duplicated.length > 0) {
|
|
231
|
+
throw new IncompleteScopeReadingError(
|
|
232
|
+
`${duplicated.join(", ")} was supplied more than once, so the reading covers fewer scopes ` +
|
|
233
|
+
`than it has entries. Completeness is over the SET of scopes, never the count.`,
|
|
234
|
+
);
|
|
235
|
+
}
|
|
236
|
+
for (const r of readings) {
|
|
237
|
+
const reason = (r.unreadable ?? "").trim();
|
|
238
|
+
if (r.commands === null && reason === "") {
|
|
239
|
+
throw new IncompleteScopeReadingError(
|
|
240
|
+
`${r.scope} reports no commands and does not say why. An unreadable scope and a scope ` +
|
|
241
|
+
`nobody opened produce the same empty reading, and which of those happened is the ` +
|
|
242
|
+
`whole question.`,
|
|
243
|
+
);
|
|
244
|
+
}
|
|
245
|
+
if (r.commands !== null && reason !== "") {
|
|
246
|
+
throw new IncompleteScopeReadingError(
|
|
247
|
+
`${r.scope} carries both commands and a reason it could not be read, so no caller can ` +
|
|
248
|
+
`tell which of the two is the reading.`,
|
|
249
|
+
);
|
|
250
|
+
}
|
|
251
|
+
}
|
|
252
|
+
}
|
|
253
|
+
|
|
254
|
+
/**
|
|
255
|
+
* One hook's registration, over a complete reading of every scope.
|
|
256
|
+
*
|
|
257
|
+
* Reports nothing about which TREE a registration points into — that is
|
|
258
|
+
* `wrongTreeViolations`' question in `lib/hook-trees.ts`, and answering it
|
|
259
|
+
* here as well would be two deciders for one question
|
|
260
|
+
* (`.claude/rules/checks-must-be-able-to-fail.md`, the fourth shape).
|
|
261
|
+
*/
|
|
262
|
+
export function hookRegistration(hook: string, readings: ScopeReading[]): HookRegistration {
|
|
263
|
+
assertEveryScopeRead(readings);
|
|
264
|
+
|
|
265
|
+
const needle = `${hook}.hook.ts`;
|
|
266
|
+
// `commandNamesHook`, never `c.includes(needle)`: a substring match reports
|
|
267
|
+
// `other-TestSuiteRelease.hook.ts` and `TestSuiteRelease.hook.ts.bak` as
|
|
268
|
+
// registrations of `TestSuiteRelease`, so a hook that is NOT registered
|
|
269
|
+
// reads as registered. That is #910's defect mirrored, and it would make
|
|
270
|
+
// the `registered` verdict — the one branch that is conclusive from a
|
|
271
|
+
// single scope — the easiest of the three to forge.
|
|
272
|
+
const registeredIn = readings
|
|
273
|
+
.filter(r => (r.commands ?? []).some(c => commandNamesHook(c, hook)))
|
|
274
|
+
.map(r => r.scope);
|
|
275
|
+
const unreadable = readings.filter(r => r.commands === null).map(r => r.scope);
|
|
276
|
+
|
|
277
|
+
// A positive is conclusive from one scope; a negative is conclusive from
|
|
278
|
+
// none short of all of them. The order of these two branches IS the
|
|
279
|
+
// asymmetry — swapping them would make a hook that is demonstrably
|
|
280
|
+
// registered report `unmeasured` because some unrelated scope was absent.
|
|
281
|
+
if (registeredIn.length > 0) {
|
|
282
|
+
return {
|
|
283
|
+
hook,
|
|
284
|
+
verdict: "registered",
|
|
285
|
+
registeredIn,
|
|
286
|
+
unreadable,
|
|
287
|
+
detail: `registered in ${registeredIn.join(", ")}`,
|
|
288
|
+
};
|
|
289
|
+
}
|
|
290
|
+
|
|
291
|
+
if (unreadable.length > 0) {
|
|
292
|
+
const reasons = readings
|
|
293
|
+
.filter(r => r.commands === null)
|
|
294
|
+
.map(r => `${r.scope}: ${r.unreadable}`)
|
|
295
|
+
.join("; ");
|
|
296
|
+
return {
|
|
297
|
+
hook,
|
|
298
|
+
verdict: "unmeasured",
|
|
299
|
+
registeredIn: [],
|
|
300
|
+
unreadable,
|
|
301
|
+
detail:
|
|
302
|
+
`no scope this run could read names ${needle}, and ${unreadable.join(", ")} could not be ` +
|
|
303
|
+
`read (${reasons}). This is not "not registered" — it is a reading nobody was able to ` +
|
|
304
|
+
`take, which is exactly what #910 reported as absence.`,
|
|
305
|
+
};
|
|
306
|
+
}
|
|
307
|
+
|
|
308
|
+
return {
|
|
309
|
+
hook,
|
|
310
|
+
verdict: "unregistered",
|
|
311
|
+
registeredIn: [],
|
|
312
|
+
unreadable: [],
|
|
313
|
+
detail: `all ${REGISTRATION_SCOPES.length} scopes were read and none names ${needle}`,
|
|
314
|
+
};
|
|
315
|
+
}
|
|
316
|
+
|
|
317
|
+
/**
|
|
318
|
+
* Hook files that nothing the repo owns has placed — the CI-enforceable half.
|
|
319
|
+
*
|
|
320
|
+
* `hookRegistration` answers "is it registered", and on a runner that answer
|
|
321
|
+
* is `unmeasured` for every machine-scoped hook, so a guard built on it is
|
|
322
|
+
* fail-open there. Measured on the first draft of #910 with one input — a
|
|
323
|
+
* hook file registered in no scope at all — run twice, differing only in
|
|
324
|
+
* `HOME`: red where every scope is readable, **green in the CI
|
|
325
|
+
* configuration**. Absence must never read as clean.
|
|
326
|
+
*
|
|
327
|
+
* So this asks a question a runner CAN answer. Not "is it registered", which
|
|
328
|
+
* is machine state, but **"does anything the repo owns say where this hook
|
|
329
|
+
* lives?"** Two ways to say so, and a hook may take either:
|
|
330
|
+
*
|
|
331
|
+
* 1. a repo-owned scope NAMES it — `.claude/settings.json`, its `.local`
|
|
332
|
+
* sibling, or `.claude/rungate/hooks.json`, whose entry carries both the
|
|
333
|
+
* command and the `scope` the repo claims for it; or
|
|
334
|
+
* 2. its own header declares why it is registered nowhere.
|
|
335
|
+
*
|
|
336
|
+
* A hook taking neither is one about which the repository has no opinion at
|
|
337
|
+
* all, and that is the state `ProjectStateSync` and `TestSuiteRelease` were
|
|
338
|
+
* in when a census declared them unregistered.
|
|
339
|
+
*
|
|
340
|
+
* **There is deliberately no third way through a registry `scope: "user"`
|
|
341
|
+
* declaration.** A draft had one, and it was a second decider: an entry
|
|
342
|
+
* declaring the scope also carries the command that names the hook, so
|
|
343
|
+
* clause 1 catches every input the extra clause did. Measured — removing it
|
|
344
|
+
* was 1 red, and the one red was its own fixture, with nothing in the live
|
|
345
|
+
* tree able to tell the two versions apart (battery row N7).
|
|
346
|
+
*
|
|
347
|
+
* **Every reading handed here must be readable.** A repo-owned scope is
|
|
348
|
+
* committed, so an unreadable one is a broken checkout rather than an
|
|
349
|
+
* absence, and returning an empty list for it would reinstate the fail-open
|
|
350
|
+
* this function exists to close.
|
|
351
|
+
*/
|
|
352
|
+
export function unplacedHooks(input: {
|
|
353
|
+
hooks: string[];
|
|
354
|
+
repoReadings: ScopeReading[];
|
|
355
|
+
declaredUnregistered: string[];
|
|
356
|
+
}): string[] {
|
|
357
|
+
const unreadable = input.repoReadings.filter(r => r.commands === null).map(r => r.scope);
|
|
358
|
+
if (unreadable.length > 0) {
|
|
359
|
+
// ONE site, named so a battery row can anchor on it.
|
|
360
|
+
throw new IncompleteScopeReadingError(
|
|
361
|
+
`${unreadable.join(", ")} is repo-owned and read as unreadable. A committed scope that is ` +
|
|
362
|
+
`not in the tree registers nothing, which is a reading; a scope that cannot be read is ` +
|
|
363
|
+
`a broken checkout, and answering from it would make this guard fail open.`,
|
|
364
|
+
);
|
|
365
|
+
}
|
|
366
|
+
if (input.repoReadings.length === 0) {
|
|
367
|
+
throw new IncompleteScopeReadingError(
|
|
368
|
+
"no repo-owned scope was supplied, so every hook would read as unplaced for no reason",
|
|
369
|
+
);
|
|
370
|
+
}
|
|
371
|
+
return input.hooks.filter(hook => {
|
|
372
|
+
if (input.repoReadings.some(r => (r.commands ?? []).some(c => commandNamesHook(c, hook)))) {
|
|
373
|
+
return false;
|
|
374
|
+
}
|
|
375
|
+
return !input.declaredUnregistered.includes(hook);
|
|
376
|
+
});
|
|
377
|
+
}
|
|
378
|
+
|
|
379
|
+
/** The same verdict for a list of hooks, over one reading. */
|
|
380
|
+
export function registrationCensus(
|
|
381
|
+
hooks: string[],
|
|
382
|
+
readings: ScopeReading[],
|
|
383
|
+
): HookRegistration[] {
|
|
384
|
+
assertEveryScopeRead(readings);
|
|
385
|
+
return hooks.map(h => hookRegistration(h, readings));
|
|
386
|
+
}
|