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.
- package/hooks/ActionVerificationGate.hook.ts +96 -0
- package/hooks/AgentBriefGuard.hook.ts +38 -0
- package/hooks/AgentVerdictCapture.hook.ts +87 -0
- package/hooks/AutoVerifyGate.hook.ts +79 -0
- package/hooks/BashToolGuard.hook.ts +65 -0
- package/hooks/BashWriteGuard.hook.ts +60 -0
- package/hooks/CommitEnforcement.hook.ts +130 -0
- package/hooks/DocHygiene.hook.ts +148 -0
- package/hooks/GateEnforcement.hook.ts +58 -0
- package/hooks/GateResultProtection.hook.ts +69 -0
- package/hooks/HarnessAFKGate.hook.ts +85 -0
- package/hooks/HookCurrency.hook.ts +99 -0
- package/hooks/IssueCloseGuard.hook.ts +149 -0
- package/hooks/MergeGuard.hook.ts +58 -0
- package/hooks/PostCompact.hook.ts +60 -0
- package/hooks/ProjectStateSync.hook.ts +103 -0
- package/hooks/SkillGuard.hook.ts +69 -0
- package/hooks/SpecConformityTrigger.hook.ts +43 -0
- package/hooks/SpecSCGuard.hook.ts +123 -0
- package/hooks/StaleTTLCleanup.hook.ts +141 -0
- package/hooks/TaskCompleted.hook.ts +51 -0
- package/hooks/TeamInit.hook.ts +85 -0
- package/hooks/TestSuiteGuard.hook.ts +70 -0
- package/hooks/TestSuiteRelease.hook.ts +85 -0
- package/hooks/TopLevelCdGuard.hook.ts +108 -0
- package/hooks/VerifyPhaseLock.hook.ts +84 -0
- package/hooks/WorkflowStateGuard.hook.ts +40 -0
- package/hooks/lib/agent-config.json +9 -0
- package/hooks/lib/agentDetection.ts +201 -0
- package/hooks/lib/comment-template.ts +86 -0
- package/hooks/lib/findWorkflow.ts +101 -0
- package/hooks/lib/parseStdin.ts +37 -0
- package/hooks/lib/paths.ts +111 -0
- package/hooks/lib/utils.ts +338 -0
- package/lib/affected-tests.ts +427 -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/bash-write-guard.ts +373 -0
- package/lib/behavioral-cache.ts +150 -2
- package/lib/branch-cleanup.ts +279 -7
- 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 +400 -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 +236 -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 +323 -0
- package/lib/fallow-availability.ts +157 -0
- package/lib/fs-write-capabilities.ts +232 -0
- package/lib/gate-enforcement.ts +222 -28
- package/lib/gate-names.ts +72 -0
- package/lib/gate-result-protection.ts +427 -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/intake-sources.ts +380 -0
- package/lib/js-top-level-code.ts +78 -10
- package/lib/junit-checks.ts +52 -0
- package/lib/late-env-spawn.ts +331 -0
- package/lib/launch-base.ts +376 -0
- package/lib/line-citation.ts +372 -0
- package/lib/orphan-reaper.ts +468 -0
- package/lib/parity-binding.ts +205 -0
- package/lib/paths.ts +96 -3
- package/lib/per-test-timeouts.ts +219 -0
- package/lib/phase2-decomposition.ts +1 -1
- 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 +669 -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 +103 -15
- package/lib/sc-ids.ts +121 -13
- package/lib/sc-reservations.ts +289 -0
- package/lib/scaffold/ai-review-findings.ts +409 -0
- package/lib/scaffold/ai-review-step.ts +5406 -64
- package/lib/scaffold/defaults.ts +82 -1
- 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 +1836 -275
- 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/security-verdict.ts +1 -1
- package/lib/shell-path-interpolation.ts +594 -0
- 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/text-dependents.ts +875 -0
- 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/workflow-security.ts +29 -0
- package/lib/workflow-taint.ts +732 -0
- package/lib/worktree-cleanup.ts +65 -38
- package/lib/worktree-collect.ts +177 -5
- package/lib/worktree-repo.ts +68 -3
- package/package.json +4 -1
- package/scripts/ai-review-findings.ts +45 -0
- package/scripts/check-installed-hook-currency.ts +825 -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,447 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Two hook trees, and which one a registration names (#713).
|
|
3
|
+
*
|
|
4
|
+
* A LEAF module with no relative imports, so there is one thing to mutate.
|
|
5
|
+
*
|
|
6
|
+
* ## The state this exists to hold
|
|
7
|
+
*
|
|
8
|
+
* Hooks are wired from two trees — `${PAI_HOOKS_DIR}` (`~/.pai/hooks`, 55
|
|
9
|
+
* files) and `${RUNGATE_HOOKS_DIR}` (`~/Projects/rungate/hooks`, 18). Eight
|
|
10
|
+
* NAMES exist as files in both, and all eight have diverged: the `.pai`
|
|
11
|
+
* copies are the old monolithic versions, rungate's are the refactored thin
|
|
12
|
+
* triggers. Nothing in either tree says which copy wins; the answer lives
|
|
13
|
+
* only in a settings file.
|
|
14
|
+
*
|
|
15
|
+
* That is how `OrphanProcessCleanup` survived (#712) — a `.pai` hook doing a
|
|
16
|
+
* harness job, which nobody re-read because it looked like settled
|
|
17
|
+
* infrastructure.
|
|
18
|
+
*
|
|
19
|
+
* ## What this module does NOT answer, which is most of the question
|
|
20
|
+
*
|
|
21
|
+
* **Whether a declared hook is registered at all is `reconcile`'s question**,
|
|
22
|
+
* in `test/hook-registration-reconciler.test.ts` (#199, #479). That file
|
|
23
|
+
* already splits the inventory by `scope`, enforces the project-scoped half
|
|
24
|
+
* against the committed `.claude/settings.json`, and reports the user-scoped
|
|
25
|
+
* half as UNMEASURED on every run. Answering it a second time here would be
|
|
26
|
+
* two deciders for one question — they would agree on every input anyone has,
|
|
27
|
+
* and a mutation of either would leave the other holding the case up
|
|
28
|
+
* (`.claude/rules/checks-must-be-able-to-fail.md`, the fourth shape).
|
|
29
|
+
*
|
|
30
|
+
* So nothing below reports a hook as missing. `registrationTree` is handed
|
|
31
|
+
* commands that already exist and answers a question `reconcile` does not
|
|
32
|
+
* ask: **which tree does this command point into.**
|
|
33
|
+
*
|
|
34
|
+
* That blindness is the live gap #713 names. `registeredIn` matches
|
|
35
|
+
* `/([A-Za-z][A-Za-z0-9]*)\.hook\.ts/`, so
|
|
36
|
+
* `bun ${PAI_HOOKS_DIR}/IssueCloseGuard.hook.ts` satisfies it exactly as well
|
|
37
|
+
* as the rungate path does. A hook this repo owns could be re-pointed at the
|
|
38
|
+
* superseded 554-line `.pai` copy and every check in the tree stays green.
|
|
39
|
+
*
|
|
40
|
+
* ## Read EVERY settings scope before concluding anything about one hook
|
|
41
|
+
*
|
|
42
|
+
* #713 reported `AgentBriefGuard` as "dead in both trees — wired nowhere".
|
|
43
|
+
* It is not. It is registered in the PROJECT settings as
|
|
44
|
+
* `bun ${CLAUDE_PROJECT_DIR}/hooks/AgentBriefGuard.hook.ts`, which resolves to
|
|
45
|
+
* the rungate copy; the measurement read `~/.claude/settings.json` alone and
|
|
46
|
+
* took zero hits as absence. That is the #646 trap — a negative result over a
|
|
47
|
+
* store you did not write, with the error pointing toward believing nothing
|
|
48
|
+
* happened — and the control nobody ran is "is this hook wired ANYWHERE?".
|
|
49
|
+
*
|
|
50
|
+
* `settingsCommands` therefore takes a LIST of documents. A caller that reads
|
|
51
|
+
* one scope gets an answer about one scope and has to say so.
|
|
52
|
+
*
|
|
53
|
+
* ## Why the tree is decided by PATH VARIABLE and not by substring
|
|
54
|
+
*
|
|
55
|
+
* `${CLAUDE_PROJECT_DIR}/hooks/X.hook.ts` and `${PAI_HOOKS_DIR}/X.hook.ts`
|
|
56
|
+
* both contain the hook's name, so deciding by name matches a commented-out
|
|
57
|
+
* line, a `description` field and the other tree's registration equally. The
|
|
58
|
+
* roots are the only thing that distinguishes them.
|
|
59
|
+
*/
|
|
60
|
+
|
|
61
|
+
/** The path variables each tree is spelled with, in any settings scope. */
|
|
62
|
+
const RUNGATE_ROOTS = ["${RUNGATE_HOOKS_DIR}", "${CLAUDE_PROJECT_DIR}/hooks"];
|
|
63
|
+
const PAI_ROOTS = ["${PAI_HOOKS_DIR}", "/.pai/hooks"];
|
|
64
|
+
|
|
65
|
+
export type HookTree = "rungate" | "pai";
|
|
66
|
+
|
|
67
|
+
/**
|
|
68
|
+
* Which tree one command points into.
|
|
69
|
+
*
|
|
70
|
+
* `unknown` is a reading, not a default: a command naming neither root is
|
|
71
|
+
* something nobody has classified, and reporting it as rungate would be the
|
|
72
|
+
* silent substitution this repo keeps paying for.
|
|
73
|
+
*/
|
|
74
|
+
export function registrationTree(command: string): HookTree | "unknown" {
|
|
75
|
+
if (RUNGATE_ROOTS.some(r => command.includes(r))) return "rungate";
|
|
76
|
+
if (PAI_ROOTS.some(r => command.includes(r))) return "pai";
|
|
77
|
+
return "unknown";
|
|
78
|
+
}
|
|
79
|
+
|
|
80
|
+
/**
|
|
81
|
+
* Every `command` string anywhere under a settings document's `hooks` key.
|
|
82
|
+
*
|
|
83
|
+
* Walks rather than indexing a known shape: the schema nests
|
|
84
|
+
* event → matcher-group → `hooks[]` and has gained a level before. A reader
|
|
85
|
+
* that knew one shape would return nothing for the next one, and nothing is
|
|
86
|
+
* indistinguishable from a tree with no `.pai` registrations in it.
|
|
87
|
+
*
|
|
88
|
+
* A document that does not parse THROWS. A corrupt settings file is not a
|
|
89
|
+
* settings file with no hooks in it (`.claude/rules/config-access.md`).
|
|
90
|
+
*/
|
|
91
|
+
export function settingsCommands(docs: string[]): string[] {
|
|
92
|
+
const out: string[] = [];
|
|
93
|
+
const walk = (node: unknown): void => {
|
|
94
|
+
if (Array.isArray(node)) { node.forEach(walk); return; }
|
|
95
|
+
if (node === null || typeof node !== "object") return;
|
|
96
|
+
const rec = node as Record<string, unknown>;
|
|
97
|
+
if (typeof rec.command === "string") out.push(rec.command);
|
|
98
|
+
Object.values(rec).forEach(walk);
|
|
99
|
+
};
|
|
100
|
+
for (const doc of docs) {
|
|
101
|
+
const parsed = JSON.parse(doc) as { hooks?: unknown };
|
|
102
|
+
walk(parsed?.hooks ?? {});
|
|
103
|
+
}
|
|
104
|
+
return out;
|
|
105
|
+
}
|
|
106
|
+
|
|
107
|
+
/**
|
|
108
|
+
* The hook file a command actually EXECUTES, as a basename.
|
|
109
|
+
*
|
|
110
|
+
* ## Three matchers, each narrower than the last, and why there was a third
|
|
111
|
+
*
|
|
112
|
+
* 1. `command.includes("X.hook.ts")` — satisfied by `other-X.hook.ts`, by
|
|
113
|
+
* `X.hook.ts.bak`, by the name in any path fragment.
|
|
114
|
+
* 2. **token membership** — any `.hook.ts`-shaped token anywhere in the
|
|
115
|
+
* string. Narrower, and the same class: measured on the #976 branch, all
|
|
116
|
+
* four of these returned `true` for `IssueCloseGuard`:
|
|
117
|
+
*
|
|
118
|
+
* bun run x.ts # IssueCloseGuard.hook.ts
|
|
119
|
+
* bun run x.ts ; echo IssueCloseGuard.hook.ts
|
|
120
|
+
* bun run x.ts && cat IssueCloseGuard.hook.ts
|
|
121
|
+
* SOME=1 bun run x.ts --note IssueCloseGuard.hook.ts
|
|
122
|
+
*
|
|
123
|
+
* A hook counted as registered because its name appeared near a command
|
|
124
|
+
* that never runs it. Tokenising narrowed the hole; it did not remove it,
|
|
125
|
+
* and the diff implied otherwise.
|
|
126
|
+
* 3. the **executed argument** — what this does now.
|
|
127
|
+
*
|
|
128
|
+
* Recorded as three steps deliberately. Three PRs in one day have replaced a
|
|
129
|
+
* matcher that was wrong about its subject with one carrying the same
|
|
130
|
+
* property a level down, and the way that keeps happening is a diff that
|
|
131
|
+
* reads as though the class were closed.
|
|
132
|
+
*
|
|
133
|
+
* ## What this does
|
|
134
|
+
*
|
|
135
|
+
* Truncate at the first `#`, `;`, `&&`, `||` or `|`; drop leading `VAR=`
|
|
136
|
+
* assignments, an `env` prefix, a known interpreter and a `run`/`exec`
|
|
137
|
+
* subcommand; skip `--flag=value` flags and REFUSE on a bare one; basename
|
|
138
|
+
* the **first positional** and compare it by equality.
|
|
139
|
+
*
|
|
140
|
+
* ## WHAT THIS DOES NOT COVER
|
|
141
|
+
*
|
|
142
|
+
* An argv parse has its own differentials. These are the ones still open,
|
|
143
|
+
* named here rather than left for the next reader to infer from the diff —
|
|
144
|
+
* **a stated limit is an answer; silence reads as coverage.** Each has a
|
|
145
|
+
* case in `test/hook-registration-evidence.test.ts` AC-6h asserting the
|
|
146
|
+
* stated behaviour, so this list cannot drift from the code without a red.
|
|
147
|
+
*
|
|
148
|
+
* | spelling | read as |
|
|
149
|
+
* |---|---|
|
|
150
|
+
* | `sh -c "bun X.hook.ts"` — the command is inside a quoted string | NOT naming it |
|
|
151
|
+
* | a wrapper script that `exec`s the hook | NOT naming it |
|
|
152
|
+
* | a `$VAR`-built path whose variable holds the file name | NOT naming it |
|
|
153
|
+
* | `make x && bun X.hook.ts` — executed in a LATER segment | NOT naming it |
|
|
154
|
+
* | `bun --inspect X.hook.ts` — a bare flag before the script | NOT naming it |
|
|
155
|
+
* | `bun -- X.hook.ts` — the end-of-flags separator | NOT naming it |
|
|
156
|
+
* | a computed specifier — `bun "$(resolve X)"` | NOT naming it |
|
|
157
|
+
*
|
|
158
|
+
* **Every one errs toward reporting a registration that exists as absent**,
|
|
159
|
+
* and that is the direction chosen rather than tolerated. For
|
|
160
|
+
* `hookRegistration` a missed registration becomes `unregistered` or
|
|
161
|
+
* `unmeasured`, which `AC-4`/`AC-4b` turn red — loud, and someone fixes the
|
|
162
|
+
* spelling. The opposite error is a guard reporting clean about its own
|
|
163
|
+
* subject, which is what #910 cost.
|
|
164
|
+
*
|
|
165
|
+
* So do not "fix" a false red by widening this. The two legal repairs are to
|
|
166
|
+
* add the spelling to the parse, or to change the registration to one the
|
|
167
|
+
* parse reads. No registry command in this tree carries a flag at all
|
|
168
|
+
* (measured: 0 of 19), which is why the bare-flag refusal costs nothing
|
|
169
|
+
* today and is the safe default for whatever is added tomorrow.
|
|
170
|
+
*
|
|
171
|
+
* `wrongTreeViolations` below deliberately still SELECTS by substring, and
|
|
172
|
+
* #981 is why: the error directions are opposite there, so a narrow parse
|
|
173
|
+
* could silently stop reporting a hook genuinely wired to the superseded
|
|
174
|
+
* tree. What #981 changed is that a selected string is now CLASSIFIED by this
|
|
175
|
+
* parse, with everything the parse rejects reported as `unparsed` rather than
|
|
176
|
+
* dropped. Its docblock carries the error-direction table — so the cheap
|
|
177
|
+
* generalisation "reuse this parser everywhere" still has a written reason
|
|
178
|
+
* not to, and the thing that was wrong is fixed.
|
|
179
|
+
*/
|
|
180
|
+
const INTERPRETERS = new Set([
|
|
181
|
+
"bun", "bunx", "node", "npx", "npm", "pnpm", "yarn", "deno", "ts-node", "tsx",
|
|
182
|
+
]);
|
|
183
|
+
const SUBCOMMANDS = new Set(["run", "exec"]);
|
|
184
|
+
const SEPARATORS = new Set(["#", ";", "&&", "||", "|", "&"]);
|
|
185
|
+
|
|
186
|
+
/**
|
|
187
|
+
* The executed hook file as a PATH — the first positional, un-basenamed.
|
|
188
|
+
*
|
|
189
|
+
* The one parse. `executedHookFile` is its basename projection and
|
|
190
|
+
* `hookRegistrationPath` is its per-hook projection, so there is a single
|
|
191
|
+
* binding to mutate and no second spelling of the argv walk.
|
|
192
|
+
*
|
|
193
|
+
* The path is what `wrongTreeViolations` classifies, and the basename is what
|
|
194
|
+
* every registration reading compares. Both come from here; they cannot
|
|
195
|
+
* disagree about which token ran.
|
|
196
|
+
*/
|
|
197
|
+
export function executedHookPath(command: string): string | null {
|
|
198
|
+
const tokens: string[] = [];
|
|
199
|
+
for (const raw of command.split(/\s+/).filter(Boolean)) {
|
|
200
|
+
// A separator ends the first command, whether it stands alone or is
|
|
201
|
+
// glued to the token before it (`x.ts;`, `x.ts&&`).
|
|
202
|
+
if (SEPARATORS.has(raw)) break;
|
|
203
|
+
const cut = raw.search(/[#;|&]/);
|
|
204
|
+
if (cut === 0) break;
|
|
205
|
+
if (cut > 0) {
|
|
206
|
+
tokens.push(raw.slice(0, cut));
|
|
207
|
+
break;
|
|
208
|
+
}
|
|
209
|
+
tokens.push(raw);
|
|
210
|
+
}
|
|
211
|
+
|
|
212
|
+
let i = 0;
|
|
213
|
+
// Leading `VAR=value` assignments, and an `env` prefix that introduces more.
|
|
214
|
+
while (i < tokens.length && /^[A-Za-z_][A-Za-z0-9_]*=/.test(tokens[i])) i++;
|
|
215
|
+
if (tokens[i] === "env") {
|
|
216
|
+
i++;
|
|
217
|
+
while (i < tokens.length && /^[A-Za-z_][A-Za-z0-9_]*=/.test(tokens[i])) i++;
|
|
218
|
+
}
|
|
219
|
+
const bare = (t: string) => t.replace(/^['"]+|['"]+$/g, "");
|
|
220
|
+
if (i < tokens.length && INTERPRETERS.has(bare(tokens[i]).split("/").pop() ?? "")) i++;
|
|
221
|
+
if (i < tokens.length && SUBCOMMANDS.has(bare(tokens[i]))) i++;
|
|
222
|
+
// The flag run is where an argv parse silently becomes wrong, and it is the
|
|
223
|
+
// differential a review found in the first version of this parse:
|
|
224
|
+
// `bun --preload Foo.hook.ts run real.ts` PRELOADS Foo and EXECUTES
|
|
225
|
+
// real.ts, so a loop that skips flags and then takes the next token reports
|
|
226
|
+
// a file that never ran as the registration.
|
|
227
|
+
//
|
|
228
|
+
// A `--flag=value` carries its value in its own token, so skipping it
|
|
229
|
+
// cannot swallow the script. A BARE flag may or may not consume the next
|
|
230
|
+
// token, and the only way to know is a list of value-taking flags — which
|
|
231
|
+
// goes stale the next time bun adds one, and a stale allowlist defaulting
|
|
232
|
+
// to "this was safe to skip" is the fail-open direction. So a bare flag is
|
|
233
|
+
// REFUSED: `null`, no registration read, loud.
|
|
234
|
+
while (i < tokens.length && bare(tokens[i]).startsWith("-")) {
|
|
235
|
+
if (!bare(tokens[i]).includes("=")) return null;
|
|
236
|
+
i++;
|
|
237
|
+
}
|
|
238
|
+
if (i >= tokens.length) return null;
|
|
239
|
+
|
|
240
|
+
const arg = bare(tokens[i]);
|
|
241
|
+
const base = arg.slice(arg.lastIndexOf("/") + 1);
|
|
242
|
+
return /^[A-Za-z0-9_-]+\.hook\.ts$/.test(base) ? arg : null;
|
|
243
|
+
}
|
|
244
|
+
|
|
245
|
+
/** The executed hook file as a BASENAME. A projection of `executedHookPath`. */
|
|
246
|
+
export function executedHookFile(command: string): string | null {
|
|
247
|
+
const path = executedHookPath(command);
|
|
248
|
+
return path === null ? null : path.slice(path.lastIndexOf("/") + 1);
|
|
249
|
+
}
|
|
250
|
+
|
|
251
|
+
/**
|
|
252
|
+
* The PATH `command` executes, when what it executes is `<hook>.hook.ts`.
|
|
253
|
+
*
|
|
254
|
+
* The one comparison. `commandNamesHook` is its boolean projection, so a
|
|
255
|
+
* reading cannot say "this command names the hook" and hand back a path
|
|
256
|
+
* belonging to something else.
|
|
257
|
+
*/
|
|
258
|
+
export function hookRegistrationPath(command: string, hook: string): string | null {
|
|
259
|
+
const path = executedHookPath(command);
|
|
260
|
+
if (path === null) return null;
|
|
261
|
+
return path.slice(path.lastIndexOf("/") + 1) === `${hook}.hook.ts` ? path : null;
|
|
262
|
+
}
|
|
263
|
+
|
|
264
|
+
/**
|
|
265
|
+
* Does `command` EXECUTE `<hook>.hook.ts`?
|
|
266
|
+
*
|
|
267
|
+
* The single predicate every registration reading goes through, so there is
|
|
268
|
+
* one binding to mutate and one place a narrowing or a widening lands.
|
|
269
|
+
*/
|
|
270
|
+
export function commandNamesHook(command: string, hook: string): boolean {
|
|
271
|
+
return hookRegistrationPath(command, hook) !== null;
|
|
272
|
+
}
|
|
273
|
+
|
|
274
|
+
export interface TreeViolation {
|
|
275
|
+
hook: string;
|
|
276
|
+
/**
|
|
277
|
+
* `unparsed` is NOT a tree. It is the reading for a string that mentions the
|
|
278
|
+
* hook and is not a command executing it — see `wrongTreeViolations`.
|
|
279
|
+
*/
|
|
280
|
+
tree: HookTree | "unknown" | "unparsed";
|
|
281
|
+
command: string;
|
|
282
|
+
detail: string;
|
|
283
|
+
}
|
|
284
|
+
|
|
285
|
+
/**
|
|
286
|
+
* Registrations of a hook this repo OWNS that do not name the rungate tree.
|
|
287
|
+
*
|
|
288
|
+
* Reports nothing for a hook with no registration — that is `reconcile`'s
|
|
289
|
+
* finding, and duplicating it here would make this the second decider for a
|
|
290
|
+
* question that already has one. The input this binding alone can see is a
|
|
291
|
+
* registration that EXISTS and points at the superseded copy.
|
|
292
|
+
*
|
|
293
|
+
* ## Why SELECTION is still a substring, and the fix was NOT `executedHookFile`
|
|
294
|
+
*
|
|
295
|
+
* #981 is the issue, and it exists because the cheap generalisation —
|
|
296
|
+
* *"#976 replaced the substring with the argv parse in `hook-scopes.ts`, do
|
|
297
|
+
* the same here"* — makes this site WORSE. The error directions are opposite:
|
|
298
|
+
*
|
|
299
|
+
* | | over-broad | narrow parse |
|
|
300
|
+
* |---|---|---|
|
|
301
|
+
* | `hookRegistration` (#976) | a hook that is NOT registered reads as registered — a guard reporting clean about its own subject, #910's defect | a real registration reads as absent → `unregistered` → **loud** |
|
|
302
|
+
* | here | a violation that is not real → an investigation → **loud** | a hook genuinely wired to the superseded tree **silently stops being reported**, which is #713 entire |
|
|
303
|
+
*
|
|
304
|
+
* So selection keeps the substring and nothing is ever dropped for failing to
|
|
305
|
+
* parse. What changed is that a selected string is now CLASSIFIED by the argv
|
|
306
|
+
* parse, in three readings instead of two:
|
|
307
|
+
*
|
|
308
|
+
* | reading | what it means |
|
|
309
|
+
* |---|---|
|
|
310
|
+
* | `pai` | the command EXECUTES this hook, from the superseded tree |
|
|
311
|
+
* | `unknown` | it EXECUTES this hook, from a path naming neither root |
|
|
312
|
+
* | `unparsed` | it mentions the hook and is not a command executing it |
|
|
313
|
+
*
|
|
314
|
+
* Before, a `# TestSuiteRelease.hook.ts` in a comment was reported as
|
|
315
|
+
* *"registered by a command naming neither tree's path variable"* — a
|
|
316
|
+
* sentence about a string that is not a registration at all. It is still
|
|
317
|
+
* reported, because dropping it is the direction that goes silent; it is now
|
|
318
|
+
* reported as the thing it is.
|
|
319
|
+
*
|
|
320
|
+
* ## The tree is read off the EXECUTED PATH, not the whole command
|
|
321
|
+
*
|
|
322
|
+
* `registrationTree(command)` would read
|
|
323
|
+
* `bun ${PAI_HOOKS_DIR}/X.hook.ts # see ${RUNGATE_HOOKS_DIR}` as **rungate**
|
|
324
|
+
* and drop it — a genuine `.pai` registration, silenced by a word in a
|
|
325
|
+
* comment. That is the same over-broad-substring class the issue is about,
|
|
326
|
+
* one level down, so it is closed here rather than left for the next reader:
|
|
327
|
+
* the classifier is handed `hookRegistrationPath`'s path and sees only the
|
|
328
|
+
* token that runs.
|
|
329
|
+
*
|
|
330
|
+
* ## WHAT THIS DOES NOT COVER
|
|
331
|
+
*
|
|
332
|
+
* Every escape below is an UNDER-report, and each has a case in
|
|
333
|
+
* `test/hook-tree-divergence.test.ts` asserting the stated behaviour, so this
|
|
334
|
+
* list cannot drift from the code without a red.
|
|
335
|
+
*
|
|
336
|
+
* | spelling | read as |
|
|
337
|
+
* |---|---|
|
|
338
|
+
* | `bun "$HOOK_FILE"` — the file NAME is in a variable, so the string never contains `X.hook.ts` | not selected at all, so not reported |
|
|
339
|
+
* | a wrapper script that `exec`s the hook without naming it | not selected at all, so not reported |
|
|
340
|
+
* | `sh -c "bun ${PAI_HOOKS_DIR}/X.hook.ts"` | selected, reported `unparsed` — the quoting is not unwrapped, so the tree is not read |
|
|
341
|
+
* | `make x && bun ${PAI_HOOKS_DIR}/X.hook.ts` — executed in a LATER segment | selected, reported `unparsed` |
|
|
342
|
+
*
|
|
343
|
+
* The first two are the ones nothing here can reach: a string that does not
|
|
344
|
+
* contain the hook's file name cannot be selected by any reading of these
|
|
345
|
+
* commands, and recovering it needs a shell rather than a parser. They are
|
|
346
|
+
* the boundary, stated, because a stated limit is an answer and silence reads
|
|
347
|
+
* as coverage.
|
|
348
|
+
*/
|
|
349
|
+
export function wrongTreeViolations(owned: string[], commands: string[]): TreeViolation[] {
|
|
350
|
+
const out: TreeViolation[] = [];
|
|
351
|
+
for (const hook of owned) {
|
|
352
|
+
// SELECTION stays over-broad on purpose — see the table above.
|
|
353
|
+
for (const command of commands.filter(c => c.includes(`${hook}.hook.ts`))) {
|
|
354
|
+
const path = hookRegistrationPath(command, hook);
|
|
355
|
+
if (path === null) {
|
|
356
|
+
const executes = executedHookFile(command);
|
|
357
|
+
out.push({
|
|
358
|
+
hook,
|
|
359
|
+
tree: "unparsed",
|
|
360
|
+
command,
|
|
361
|
+
detail:
|
|
362
|
+
`${hook} is named by this string, which is not a command that executes it ` +
|
|
363
|
+
`(${executes ? `the first command executes ${executes}` : "no executed hook file could be read from it"}), ` +
|
|
364
|
+
`so no tree can be read from it and it is not evidence of any registration: ${command}`,
|
|
365
|
+
});
|
|
366
|
+
continue;
|
|
367
|
+
}
|
|
368
|
+
const tree = registrationTree(path);
|
|
369
|
+
if (tree === "rungate") continue;
|
|
370
|
+
out.push({
|
|
371
|
+
hook,
|
|
372
|
+
tree,
|
|
373
|
+
command,
|
|
374
|
+
detail:
|
|
375
|
+
tree === "pai"
|
|
376
|
+
? `${hook} is owned by this repo and registered from the .pai tree, which holds the ` +
|
|
377
|
+
`superseded copy: ${command}`
|
|
378
|
+
: `${hook} is registered by a command naming neither tree's path variable, so which ` +
|
|
379
|
+
`copy runs cannot be read from it: ${command}`,
|
|
380
|
+
});
|
|
381
|
+
}
|
|
382
|
+
}
|
|
383
|
+
return out;
|
|
384
|
+
}
|
|
385
|
+
|
|
386
|
+
export interface HookTreeCensus {
|
|
387
|
+
reading: "MEASURED" | "UNMEASURED";
|
|
388
|
+
unmeasuredReasons: string[];
|
|
389
|
+
/** Hook names present as files in BOTH trees. */
|
|
390
|
+
duplicates: string[];
|
|
391
|
+
pai: string[];
|
|
392
|
+
rungate: string[];
|
|
393
|
+
}
|
|
394
|
+
|
|
395
|
+
const HOOK_FILE = /\.hook\.ts$/;
|
|
396
|
+
|
|
397
|
+
/**
|
|
398
|
+
* Both trees, listed, with the duplicate names named.
|
|
399
|
+
*
|
|
400
|
+
* `listDir` is injected so a case can drive an unreadable directory without
|
|
401
|
+
* touching the filesystem, and so this module stays a leaf with no `fs`
|
|
402
|
+
* import.
|
|
403
|
+
*
|
|
404
|
+
* **A directory that cannot be read is UNMEASURED and NOT an empty list.**
|
|
405
|
+
* Zero duplicates found between two directories nobody opened is the reading
|
|
406
|
+
* SC-1 exists to refuse, and it is what CI sees: `~/.pai` is machine state
|
|
407
|
+
* and does not exist on a runner.
|
|
408
|
+
*/
|
|
409
|
+
export function hookTreeCensus(
|
|
410
|
+
paiDir: string,
|
|
411
|
+
rungateDir: string,
|
|
412
|
+
listDir: (dir: string) => string[] | null,
|
|
413
|
+
): HookTreeCensus {
|
|
414
|
+
const reasons: string[] = [];
|
|
415
|
+
const read = (dir: string, label: string): string[] => {
|
|
416
|
+
const entries = listDir(dir);
|
|
417
|
+
if (entries === null) {
|
|
418
|
+
reasons.push(
|
|
419
|
+
`the ${label} hook tree at ${dir} could not be read, so a duplicate between the two ` +
|
|
420
|
+
`trees cannot be ruled out. This is not "no duplicates".`,
|
|
421
|
+
);
|
|
422
|
+
return [];
|
|
423
|
+
}
|
|
424
|
+
return entries.filter(n => HOOK_FILE.test(n)).map(n => n.replace(HOOK_FILE, "")).sort();
|
|
425
|
+
};
|
|
426
|
+
|
|
427
|
+
const pai = read(paiDir, "PAI");
|
|
428
|
+
const rungate = read(rungateDir, "rungate");
|
|
429
|
+
|
|
430
|
+
// ONE decider for "an unreadable tree contributes no duplicates": `read`
|
|
431
|
+
// returns an empty list beside its reason, so the intersection below is
|
|
432
|
+
// empty by construction. A `reasons.length === 0 ? … : []` guard here as
|
|
433
|
+
// well would be a second decider for the same question — mutating it was
|
|
434
|
+
// row M8 of the battery and measured **0 red**, because there is no input
|
|
435
|
+
// on which the two versions differ. Per
|
|
436
|
+
// `.claude/rules/checks-must-be-able-to-fail.md` that is a collapsed pair,
|
|
437
|
+
// not a gap in the cases, so it was collapsed rather than banked.
|
|
438
|
+
const duplicates = pai.filter(n => rungate.includes(n));
|
|
439
|
+
|
|
440
|
+
return {
|
|
441
|
+
reading: reasons.length === 0 ? "MEASURED" : "UNMEASURED",
|
|
442
|
+
unmeasuredReasons: reasons,
|
|
443
|
+
duplicates,
|
|
444
|
+
pai,
|
|
445
|
+
rungate,
|
|
446
|
+
};
|
|
447
|
+
}
|