rungate 0.6.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 +81 -16
- package/lib/behavioral-cache.ts +150 -2
- 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 +93 -14
- package/lib/check-remedy.ts +140 -0
- package/lib/ci-checkout.ts +17 -0
- 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 +191 -17
- package/lib/config-loader.ts +39 -1
- package/lib/config-trackable.ts +391 -0
- package/lib/conformity.ts +1087 -100
- package/lib/containment.ts +238 -0
- package/lib/content-hash.ts +24 -0
- package/lib/create-sc.ts +249 -16
- 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/evidence-prevalidator.ts +224 -2
- package/lib/evidence-satisfiability.ts +534 -12
- package/lib/failure-intake.ts +317 -0
- package/lib/fallow-availability.ts +157 -0
- package/lib/fs-write-capabilities.ts +232 -0
- package/lib/gate-run-split.ts +147 -0
- package/lib/generators/agents-md.ts +140 -32
- 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 +52 -0
- package/lib/launch-base.ts +253 -0
- package/lib/line-citation.ts +372 -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/published-artifact.ts +525 -0
- package/lib/readdir-sorted.ts +45 -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-id-cross-tree.ts +19 -7
- 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 +4661 -64
- package/lib/scaffold/managed-workflow.ts +587 -192
- package/lib/scaffold/owned-files.ts +152 -45
- package/lib/scaffold/pre-push-hook.ts +49 -5
- package/lib/scaffold/steps.ts +1413 -244
- package/lib/scaffold/workflow-census.ts +217 -0
- package/lib/scaffold/workflow-drift.ts +217 -0
- package/lib/scaffold/write-steps.ts +4 -0
- package/lib/scan-budget.ts +247 -0
- package/lib/scanner.ts +43 -51
- 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/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 +241 -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-suite-lock.ts +159 -16
- package/lib/tool-probe.ts +31 -9
- package/lib/top-level-cd.ts +393 -0
- package/lib/tree-entries.ts +89 -0
- package/lib/ts-ast.ts +200 -0
- 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/create-sc.ts +21 -1
- package/scripts/extract-constraints.ts +107 -7
- package/scripts/generate-code-map.ts +23 -30
- package/scripts/scaffold-project.ts +8 -1
- package/scripts/sync-sc-status.ts +77 -16
|
@@ -0,0 +1,235 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Evidence that a hook fired, and what it decided (#910).
|
|
3
|
+
*
|
|
4
|
+
* ## Why this exists
|
|
5
|
+
*
|
|
6
|
+
* #910's registration claim was wrong and was corrected by parsing the
|
|
7
|
+
* settings. Its execution claim could not be corrected, because there was
|
|
8
|
+
* nothing to correct it against: neither `TestSuiteRelease.hook.ts` nor
|
|
9
|
+
* `ProjectStateSync.hook.ts` wrote anything anywhere, so no search could ask
|
|
10
|
+
* whether either had ever run.
|
|
11
|
+
*
|
|
12
|
+
* That is `.claude/rules/checks-must-be-able-to-fail.md`'s #646 shape with the
|
|
13
|
+
* store removed entirely. The rule there is *"before believing an empty search
|
|
14
|
+
* over a store you did not write, name a string that must be PRESENT if the
|
|
15
|
+
* store has anything in it at all"*. For these two hooks there was no such
|
|
16
|
+
* string, and so no reading of their execution was available to anyone —
|
|
17
|
+
* including whoever picks up the issue next.
|
|
18
|
+
*
|
|
19
|
+
* ## The distinction a record has to preserve
|
|
20
|
+
*
|
|
21
|
+
* A hook that fired and deliberately declined, and a hook that never fired,
|
|
22
|
+
* are the same observation when nothing is written. They have different fixes,
|
|
23
|
+
* so they must look different:
|
|
24
|
+
*
|
|
25
|
+
* | outcome | means |
|
|
26
|
+
* |---|---|
|
|
27
|
+
* | no record at all | the call was out of the hook's population, or the hook did not run |
|
|
28
|
+
* | `declined-*` | it ran, reached the decision, and chose not to act |
|
|
29
|
+
* | the acting outcome | it ran and did the thing |
|
|
30
|
+
*
|
|
31
|
+
* **Only in-population calls are recorded.** Both hooks are attached to tool
|
|
32
|
+
* events that fire on every Bash call and every Write and Edit in every
|
|
33
|
+
* session, so recording every invocation would produce a file nobody can read
|
|
34
|
+
* — and the question is about full-suite commands and `project-state.json`
|
|
35
|
+
* writes, not about every tool call. The hook headers say which population
|
|
36
|
+
* each one records.
|
|
37
|
+
*
|
|
38
|
+
* ## Never throw
|
|
39
|
+
*
|
|
40
|
+
* A `PostToolUse` hook that throws fails the tool call it is attached to. So
|
|
41
|
+
* `appendEvidence` returns `false` rather than raising — and returns it rather
|
|
42
|
+
* than swallowing it, because a write that did not happen is not a write that
|
|
43
|
+
* happened, and a caller that wants to know can ask.
|
|
44
|
+
*/
|
|
45
|
+
|
|
46
|
+
import { createHash } from "crypto";
|
|
47
|
+
import { appendFileSync, chmodSync, mkdirSync } from "fs";
|
|
48
|
+
import { homedir } from "os";
|
|
49
|
+
import { dirname, join } from "path";
|
|
50
|
+
|
|
51
|
+
export const HOOK_EVIDENCE_FILE = "hook-firings.jsonl";
|
|
52
|
+
|
|
53
|
+
/**
|
|
54
|
+
* The evidence file holds no raw command and no raw error text.
|
|
55
|
+
*
|
|
56
|
+
* A Bash tool call routinely carries leading environment assignments —
|
|
57
|
+
* `SOME_TOKEN=... bun test` — and an exception message routinely quotes the
|
|
58
|
+
* path or argv that produced it. Writing either verbatim turns an append-only
|
|
59
|
+
* log into a credential store that nothing rotates, in a file whose whole
|
|
60
|
+
* purpose is to be read later by somebody who was not there.
|
|
61
|
+
*
|
|
62
|
+
* So a record carries a non-reversible DISCRIMINATOR plus a classification
|
|
63
|
+
* drawn from a fixed vocabulary. That keeps every question the evidence
|
|
64
|
+
* exists to answer — did it fire, what did it decide, was it the same command
|
|
65
|
+
* as last time — and answers none of the questions a secret would.
|
|
66
|
+
*
|
|
67
|
+
* Raised by the security review of PR #970, findings 1 and 2.
|
|
68
|
+
*/
|
|
69
|
+
export function digest(value: string): string {
|
|
70
|
+
// 16 hex characters: enough to correlate two runs of the same command,
|
|
71
|
+
// far too little to invert, and short enough that nobody is tempted to
|
|
72
|
+
// paste it anywhere as though it were the original.
|
|
73
|
+
return createHash("sha256").update(value).digest("hex").slice(0, 16);
|
|
74
|
+
}
|
|
75
|
+
|
|
76
|
+
/**
|
|
77
|
+
* The runner words a command contains, drawn from a FIXED vocabulary.
|
|
78
|
+
*
|
|
79
|
+
* Allowlisted rather than extracted, which is the property that matters: the
|
|
80
|
+
* output is a subset of this list, so no input can push an unexpected
|
|
81
|
+
* substring of the command into the record. A classification cannot leak;
|
|
82
|
+
* a pass-through can.
|
|
83
|
+
*/
|
|
84
|
+
const SUITE_VOCABULARY = [
|
|
85
|
+
"bun",
|
|
86
|
+
"npm",
|
|
87
|
+
"pnpm",
|
|
88
|
+
"yarn",
|
|
89
|
+
"npx",
|
|
90
|
+
"test",
|
|
91
|
+
"vitest",
|
|
92
|
+
"jest",
|
|
93
|
+
"--parallel",
|
|
94
|
+
"--no-isolate",
|
|
95
|
+
"--coverage",
|
|
96
|
+
] as const;
|
|
97
|
+
|
|
98
|
+
export function suiteTokens(command: string): string[] {
|
|
99
|
+
const seen = new Set(command.split(/\s+/).map(t => t.replace(/^['"]+|['"]+$/g, "")));
|
|
100
|
+
return SUITE_VOCABULARY.filter(word => seen.has(word));
|
|
101
|
+
}
|
|
102
|
+
|
|
103
|
+
/**
|
|
104
|
+
* A command reduced to what the evidence actually needs.
|
|
105
|
+
*
|
|
106
|
+
* One binding, so every hook records the same shape and there is one place to
|
|
107
|
+
* mutate when asking whether redaction is load-bearing.
|
|
108
|
+
*/
|
|
109
|
+
export function commandDigestFacts(command: string): {
|
|
110
|
+
commandDigest: string;
|
|
111
|
+
suiteTokens: string[];
|
|
112
|
+
} {
|
|
113
|
+
return { commandDigest: digest(command), suiteTokens: suiteTokens(command) };
|
|
114
|
+
}
|
|
115
|
+
|
|
116
|
+
/** An error reduced to a class name and a digest — never its message. */
|
|
117
|
+
export function errorFacts(e: unknown): { errorClass: string; errorDigest: string } {
|
|
118
|
+
const raw = e instanceof Error ? `${e.name}: ${e.message}` : String(e);
|
|
119
|
+
const name = e instanceof Error ? e.name : typeof e;
|
|
120
|
+
return {
|
|
121
|
+
// Constructor names are identifiers. Anything else is refused rather
|
|
122
|
+
// than passed through, because `e.name` is writable.
|
|
123
|
+
errorClass: /^[A-Za-z_][A-Za-z0-9_]*$/.test(name) ? name : "UNCLASSIFIED",
|
|
124
|
+
errorDigest: digest(raw),
|
|
125
|
+
};
|
|
126
|
+
}
|
|
127
|
+
|
|
128
|
+
export interface HookFiring {
|
|
129
|
+
/** ISO-8601, so a record can be compared against a run. */
|
|
130
|
+
at: string;
|
|
131
|
+
hook: string;
|
|
132
|
+
/** What the hook decided. `declined-*` for a deliberate no-op. */
|
|
133
|
+
outcome: string;
|
|
134
|
+
detail?: Record<string, unknown>;
|
|
135
|
+
}
|
|
136
|
+
|
|
137
|
+
/**
|
|
138
|
+
* Where the evidence lives, from an environment and a home directory.
|
|
139
|
+
*
|
|
140
|
+
* Both are parameters rather than reads of `process.env` and `homedir()`, so
|
|
141
|
+
* a case can drive this without touching the machine's real work directory.
|
|
142
|
+
* `RUNGATE_WORK_DIR` is the same override every other hook in this tree
|
|
143
|
+
* honours (`hooks/StaleTTLCleanup.hook.ts`, `hooks/lib/paths.ts`).
|
|
144
|
+
*/
|
|
145
|
+
export function hookEvidencePath(
|
|
146
|
+
env: Record<string, string | undefined> = process.env,
|
|
147
|
+
home: string = homedir(),
|
|
148
|
+
): string {
|
|
149
|
+
return join(env.RUNGATE_WORK_DIR || join(home, ".rungate"), HOOK_EVIDENCE_FILE);
|
|
150
|
+
}
|
|
151
|
+
|
|
152
|
+
/**
|
|
153
|
+
* One record, rendered.
|
|
154
|
+
*
|
|
155
|
+
* Pure, and the single place the on-disk shape is decided, so a case can
|
|
156
|
+
* assert the shape without a filesystem and the writer cannot disagree with
|
|
157
|
+
* the reader about it.
|
|
158
|
+
*/
|
|
159
|
+
export function firingLine(
|
|
160
|
+
hook: string,
|
|
161
|
+
outcome: string,
|
|
162
|
+
detail: Record<string, unknown>,
|
|
163
|
+
at: Date,
|
|
164
|
+
): string {
|
|
165
|
+
const record: HookFiring = { at: at.toISOString(), hook, outcome };
|
|
166
|
+
if (Object.keys(detail).length > 0) record.detail = detail;
|
|
167
|
+
// JSONL: the trailing newline terminates THIS record. Without it a crash
|
|
168
|
+
// mid-append leaves two records concatenated into one unparseable line, and
|
|
169
|
+
// the reader below would refuse the whole file over it.
|
|
170
|
+
return `${JSON.stringify(record)}\n`;
|
|
171
|
+
}
|
|
172
|
+
|
|
173
|
+
/**
|
|
174
|
+
* Read records back.
|
|
175
|
+
*
|
|
176
|
+
* A line that does not parse is DROPPED rather than throwing, and this is the
|
|
177
|
+
* one place in this tree where that is the right call: the file is appended to
|
|
178
|
+
* concurrently by hooks in unrelated sessions, so a torn final line is an
|
|
179
|
+
* expected state of a log and not a corrupt config. The distinction
|
|
180
|
+
* `.claude/rules/config-access.md` protects is about a document whose absence
|
|
181
|
+
* and whose corruption mean different things; here both mean "no record", and
|
|
182
|
+
* a reader that threw would make the evidence unreadable exactly when it is
|
|
183
|
+
* most wanted.
|
|
184
|
+
*/
|
|
185
|
+
export function parseFirings(text: string): HookFiring[] {
|
|
186
|
+
const out: HookFiring[] = [];
|
|
187
|
+
for (const line of text.split("\n")) {
|
|
188
|
+
if (!line.trim()) continue;
|
|
189
|
+
try {
|
|
190
|
+
out.push(JSON.parse(line) as HookFiring);
|
|
191
|
+
} catch {
|
|
192
|
+
continue;
|
|
193
|
+
}
|
|
194
|
+
}
|
|
195
|
+
return out;
|
|
196
|
+
}
|
|
197
|
+
|
|
198
|
+
/**
|
|
199
|
+
* Append one rendered line, creating the directory.
|
|
200
|
+
*
|
|
201
|
+
* Returns `false` on any failure and NEVER throws — see the module docblock.
|
|
202
|
+
*/
|
|
203
|
+
export function appendEvidence(path: string, line: string): boolean {
|
|
204
|
+
try {
|
|
205
|
+
// 0o700 / 0o600. The file records which suites ran, when, and from which
|
|
206
|
+
// worktree, for every session on the machine — a shape worth keeping to
|
|
207
|
+
// the owning user even with the redaction above. `mode` applies only on
|
|
208
|
+
// creation, so an existing file is corrected explicitly; a chmod failure
|
|
209
|
+
// must not lose the record, which is why it is caught separately.
|
|
210
|
+
mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
|
|
211
|
+
appendFileSync(path, line, { mode: 0o600 });
|
|
212
|
+
try {
|
|
213
|
+
chmodSync(path, 0o600);
|
|
214
|
+
} catch {
|
|
215
|
+
/* the record is written; its mode is a hardening, not the evidence */
|
|
216
|
+
}
|
|
217
|
+
return true;
|
|
218
|
+
} catch {
|
|
219
|
+
return false;
|
|
220
|
+
}
|
|
221
|
+
}
|
|
222
|
+
|
|
223
|
+
/**
|
|
224
|
+
* The one call a hook makes.
|
|
225
|
+
*
|
|
226
|
+
* One binding, so there is one thing to mutate and one site to grep for when
|
|
227
|
+
* asking which hooks are observable at all.
|
|
228
|
+
*/
|
|
229
|
+
export function recordHookFiring(
|
|
230
|
+
hook: string,
|
|
231
|
+
outcome: string,
|
|
232
|
+
detail: Record<string, unknown> = {},
|
|
233
|
+
): boolean {
|
|
234
|
+
return appendEvidence(hookEvidencePath(), firingLine(hook, outcome, detail, new Date()));
|
|
235
|
+
}
|
|
@@ -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
|
+
}
|