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,253 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Is the session's cwd a safe place to cut agent worktrees from? (#644)
|
|
3
|
+
*
|
|
4
|
+
* ## The thing this does NOT do, stated first
|
|
5
|
+
*
|
|
6
|
+
* It does not derive the worktree base. `workflows/ship.js:1235` has pinned
|
|
7
|
+
* `opts.cwd = PROJECT_ROOT` for every worktree-isolated spawn since
|
|
8
|
+
* `804b9a43` on 2026-09-23, and there is no spawn path that bypasses it —
|
|
9
|
+
* all six roles resolve to `isolation: 'worktree'` and no call site sets it
|
|
10
|
+
* explicitly. **Rungate already passes the explicit argument.**
|
|
11
|
+
*
|
|
12
|
+
* It does not hold. `isolation: 'worktree'` is resolved by the agent
|
|
13
|
+
* runtime against the SESSION'S cwd, and `opts.cwd` is applied to the
|
|
14
|
+
* spawned agent afterwards. Run `wf_5e3ed885-98c` on 2026-10-14 put a
|
|
15
|
+
* remediation Marcus in a worktree of one consumer's repository while
|
|
16
|
+
* working an issue in another — three weeks after the pin landed. The
|
|
17
|
+
* repositories are named on #218; they are deliberately not named here,
|
|
18
|
+
* because the harness must not name its consumers (#304, SC-A1).
|
|
19
|
+
*
|
|
20
|
+
* So the one thing rungate controls is whether the run STARTS. This refuses
|
|
21
|
+
* at launch, before any agent is spawned, when the session's cwd would
|
|
22
|
+
* produce a worktree the run does not want.
|
|
23
|
+
*
|
|
24
|
+
* ## Two failures, one input
|
|
25
|
+
*
|
|
26
|
+
* Both of #644's failures are the same fact wearing different clothes, and
|
|
27
|
+
* the silent one is worse:
|
|
28
|
+
*
|
|
29
|
+
* 1. cwd is not a git repository at all. The runtime says *"not in a git
|
|
30
|
+
* repository and no WorktreeCreate hooks are configured… to use
|
|
31
|
+
* worktree isolation with other VCS systems"*, which is about the
|
|
32
|
+
* session's cwd while naming neither it nor the session. A reader
|
|
33
|
+
* configures hooks they do not need and still has the bug.
|
|
34
|
+
* 2. cwd IS a git repository, in another project or on another branch.
|
|
35
|
+
* Nothing fails. The run cuts its worktrees from somebody else's work
|
|
36
|
+
* and succeeds onto the wrong base, found later by the PR behaving
|
|
37
|
+
* oddly.
|
|
38
|
+
*
|
|
39
|
+
* A check that covers only the first is the cheapest wrong fix for this
|
|
40
|
+
* issue, named in #644's own body: it fixes the symptom that announces
|
|
41
|
+
* itself and leaves the one that does not.
|
|
42
|
+
*
|
|
43
|
+
* ## Why a refusal and not a repair
|
|
44
|
+
*
|
|
45
|
+
* `process.chdir()` would be the repair, and it is not available to a
|
|
46
|
+
* workflow script, nor would it be right: the session's cwd is shared with
|
|
47
|
+
* the operator and with whatever they do next. A run that quietly moved it
|
|
48
|
+
* would be a side effect outside its own worktrees, which is #640's
|
|
49
|
+
* complaint about the shared primary, arriving from the other direction.
|
|
50
|
+
*
|
|
51
|
+
* ## Three readings, not two
|
|
52
|
+
*
|
|
53
|
+
* `SAME_REPO` is not the same as `SAME_CHECKOUT`. The shared primary sits on
|
|
54
|
+
* `rungate/run-<issue>` for the life of a run (#640) — the same repository
|
|
55
|
+
* as `projectRoot`, a different working tree, on a branch belonging to
|
|
56
|
+
* another issue. Collapsing that into "same repo, fine" is the precondition
|
|
57
|
+
* blindness in `.claude/rules/checks-must-be-able-to-fail.md`: every natural
|
|
58
|
+
* fixture runs from the right directory, so the branch where cwd and
|
|
59
|
+
* `projectRoot` are the same repo and disagree anyway is outside the
|
|
60
|
+
* battery's reach entirely.
|
|
61
|
+
*/
|
|
62
|
+
import { spawnSync } from "child_process";
|
|
63
|
+
|
|
64
|
+
import { readWorktreeRemote, redactRemote, repoSlug } from "./worktree-repo";
|
|
65
|
+
|
|
66
|
+
/**
|
|
67
|
+
* A path or branch name, quoted and redacted.
|
|
68
|
+
*
|
|
69
|
+
* `worktreeDiskIdentity` in the sibling module redacts everything it
|
|
70
|
+
* interpolates, and a control that does not is a parity gap a reader has
|
|
71
|
+
* to notice. Paths and branch names are not usually credential-bearing —
|
|
72
|
+
* but they come from the environment, a worktree can live under a
|
|
73
|
+
* directory named after one, and `redactRemote` leaves an ordinary path
|
|
74
|
+
* untouched, so the check costs nothing and the omission costs a leak
|
|
75
|
+
* nobody is looking for.
|
|
76
|
+
*/
|
|
77
|
+
const safe = (v: unknown) => JSON.stringify(redactRemote(String(v)));
|
|
78
|
+
|
|
79
|
+
/** Every refusal and every pass travels through one of these. */
|
|
80
|
+
export type LaunchBaseReading =
|
|
81
|
+
/** cwd and projectRoot are the same working tree. The only clean answer. */
|
|
82
|
+
| { reading: "SAME_CHECKOUT"; cwd: string; projectRoot: string }
|
|
83
|
+
/** cwd is a git repository, and not one git can resolve a toplevel for. */
|
|
84
|
+
| { reading: "CWD_NOT_A_REPO"; cwd: string; projectRoot: string; refusal: string }
|
|
85
|
+
/** cwd is a repository in a DIFFERENT project. Failure 2, loud version. */
|
|
86
|
+
| { reading: "DIFFERENT_REPO"; cwd: string; projectRoot: string; refusal: string }
|
|
87
|
+
/** Same repository, different working tree or branch. Failure 2, quiet version. */
|
|
88
|
+
| { reading: "DIFFERENT_CHECKOUT"; cwd: string; projectRoot: string; refusal: string }
|
|
89
|
+
/**
|
|
90
|
+
* Something could not be read. NOT a pass: a reading that could not be
|
|
91
|
+
* taken is indistinguishable from a clean one, and only one of them is
|
|
92
|
+
* reportable (`.claude/rules/config-access.md`).
|
|
93
|
+
*/
|
|
94
|
+
| { reading: "UNMEASURED"; cwd: string; projectRoot: string; refusal: string };
|
|
95
|
+
|
|
96
|
+
/** `git -C <dir> rev-parse --show-toplevel`, or `null`. */
|
|
97
|
+
function toplevel(dir: string): string | null {
|
|
98
|
+
if (typeof dir !== "string" || !dir.trim()) return null;
|
|
99
|
+
const got = spawnSync("git", ["-C", dir, "rev-parse", "--show-toplevel"], {
|
|
100
|
+
timeout: 10_000,
|
|
101
|
+
encoding: "utf-8",
|
|
102
|
+
});
|
|
103
|
+
if (got.error || got.status !== 0) return null;
|
|
104
|
+
const out = String(got.stdout || "").trim();
|
|
105
|
+
return out === "" ? null : out;
|
|
106
|
+
}
|
|
107
|
+
|
|
108
|
+
/** `git -C <dir> rev-parse --abbrev-ref HEAD`, or `null`. */
|
|
109
|
+
function branchOf(dir: string): string | null {
|
|
110
|
+
const got = spawnSync("git", ["-C", dir, "rev-parse", "--abbrev-ref", "HEAD"], {
|
|
111
|
+
timeout: 10_000,
|
|
112
|
+
encoding: "utf-8",
|
|
113
|
+
});
|
|
114
|
+
if (got.error || got.status !== 0) return null;
|
|
115
|
+
const out = String(got.stdout || "").trim();
|
|
116
|
+
return out === "" ? null : out;
|
|
117
|
+
}
|
|
118
|
+
|
|
119
|
+
/**
|
|
120
|
+
* The reading for one launch.
|
|
121
|
+
*
|
|
122
|
+
* ONE discriminator, `reading`. Every other field is a projection of the
|
|
123
|
+
* same two probes taken here and nowhere else, so no two of them can
|
|
124
|
+
* disagree — and a caller that only wants a boolean derives it with
|
|
125
|
+
* `launchBaseRefusal` rather than re-asking git.
|
|
126
|
+
*
|
|
127
|
+
* The comparison is by RESOLVED TOPLEVEL first and by remote slug second,
|
|
128
|
+
* in that order and for a reason. Two worktrees of one repository have
|
|
129
|
+
* different toplevels and the same remote; two clones of one repository
|
|
130
|
+
* have different toplevels and the same remote as well. Only the toplevel
|
|
131
|
+
* separates "the tree the run was handed" from "another tree of the same
|
|
132
|
+
* project", and that distinction is the whole of failure 2's quiet half.
|
|
133
|
+
*/
|
|
134
|
+
export function launchBaseReading(cwd: string, projectRoot: string): LaunchBaseReading {
|
|
135
|
+
// RAW for probing, REDACTED for reporting, and the two are never mixed
|
|
136
|
+
// up: `git -C` must receive the real path, and a redacted one would send
|
|
137
|
+
// the probe to a directory that does not exist — which resolves to
|
|
138
|
+
// CWD_NOT_A_REPO and reads exactly like the finding this module exists
|
|
139
|
+
// to report. Everything returned is built from `here`; everything handed
|
|
140
|
+
// to git comes from `raw`.
|
|
141
|
+
const raw = { cwd: String(cwd ?? ""), projectRoot: String(projectRoot ?? "") };
|
|
142
|
+
// Redacted ON THE READING, not at each call site. `check-launch-base.ts`
|
|
143
|
+
// serialises the whole object, and a caller that had to remember to
|
|
144
|
+
// redact is a control one caller will forget.
|
|
145
|
+
const here = { cwd: redactRemote(raw.cwd), projectRoot: redactRemote(raw.projectRoot) };
|
|
146
|
+
|
|
147
|
+
if (!raw.projectRoot.trim()) {
|
|
148
|
+
return {
|
|
149
|
+
...here,
|
|
150
|
+
reading: "UNMEASURED",
|
|
151
|
+
refusal:
|
|
152
|
+
"no projectRoot was given, so there is nothing for the launching session's working directory to be " +
|
|
153
|
+
"compared against — a run that cannot state which tree it is for cannot check that it is in it",
|
|
154
|
+
};
|
|
155
|
+
}
|
|
156
|
+
|
|
157
|
+
const rootTop = toplevel(raw.projectRoot);
|
|
158
|
+
if (rootTop === null) {
|
|
159
|
+
return {
|
|
160
|
+
...here,
|
|
161
|
+
reading: "UNMEASURED",
|
|
162
|
+
refusal:
|
|
163
|
+
`projectRoot ${safe(here.projectRoot)} is not a git repository git can resolve. ` +
|
|
164
|
+
"This is the run's own argument and not the launching session's working directory, so it is reported " +
|
|
165
|
+
"as unmeasured rather than as the cwd problem this check exists for",
|
|
166
|
+
};
|
|
167
|
+
}
|
|
168
|
+
|
|
169
|
+
const cwdTop = toplevel(raw.cwd);
|
|
170
|
+
if (cwdTop === null) {
|
|
171
|
+
// Failure 1, said about the right input. The runtime's own message for
|
|
172
|
+
// this state names neither the directory nor the fact that it is the
|
|
173
|
+
// SESSION's, and recommends VCS hook configuration that is irrelevant.
|
|
174
|
+
return {
|
|
175
|
+
...here,
|
|
176
|
+
reading: "CWD_NOT_A_REPO",
|
|
177
|
+
refusal:
|
|
178
|
+
`the launching session's working directory ${safe(here.cwd)} is not a git repository. ` +
|
|
179
|
+
`projectRoot ${safe(here.projectRoot)} is one, and is correct — but agent worktrees ` +
|
|
180
|
+
"are cut by the runtime from the SESSION's directory, not from projectRoot, so this run " +
|
|
181
|
+
"would die at the first isolated spawn. This is not a VCS-configuration problem and " +
|
|
182
|
+
"WorktreeCreate hooks will not fix it: cd into projectRoot and relaunch",
|
|
183
|
+
};
|
|
184
|
+
}
|
|
185
|
+
|
|
186
|
+
if (cwdTop === rootTop) return { ...here, reading: "SAME_CHECKOUT" };
|
|
187
|
+
|
|
188
|
+
// Different trees. Which KIND of different decides what the operator does
|
|
189
|
+
// next, so the two are never collapsed.
|
|
190
|
+
const cwdRemote = readWorktreeRemote(cwdTop);
|
|
191
|
+
const rootRemote = readWorktreeRemote(rootTop);
|
|
192
|
+
const cwdSlug = repoSlug(cwdRemote.url);
|
|
193
|
+
const rootSlug = repoSlug(rootRemote.url);
|
|
194
|
+
|
|
195
|
+
if (cwdSlug === null || rootSlug === null) {
|
|
196
|
+
// A tree with no resolvable origin is not a tree we can clear. Refusing
|
|
197
|
+
// rather than passing: the guard must not go inert for exactly the
|
|
198
|
+
// misconfigured checkout most likely to need it (#218's reasoning).
|
|
199
|
+
return {
|
|
200
|
+
...here,
|
|
201
|
+
reading: "UNMEASURED",
|
|
202
|
+
refusal:
|
|
203
|
+
`the launching session's working directory ${safe(cwdTop)} and projectRoot ` +
|
|
204
|
+
`${safe(rootTop)} are different trees, and at least one of them has no origin ` +
|
|
205
|
+
`remote this can resolve (cwd: ${cwdSlug ?? redactRemote(String(cwdRemote.error ?? cwdRemote.url))}, ` +
|
|
206
|
+
`projectRoot: ${rootSlug ?? redactRemote(String(rootRemote.error ?? rootRemote.url))}). ` +
|
|
207
|
+
"Whether they are the same project is therefore unknown, and unknown is not clean",
|
|
208
|
+
};
|
|
209
|
+
}
|
|
210
|
+
|
|
211
|
+
if (cwdSlug !== rootSlug) {
|
|
212
|
+
return {
|
|
213
|
+
...here,
|
|
214
|
+
reading: "DIFFERENT_REPO",
|
|
215
|
+
refusal:
|
|
216
|
+
`the launching session's working directory ${safe(cwdTop)} is a checkout of ${cwdSlug}, but ` +
|
|
217
|
+
`this run targets ${rootSlug} at ${safe(rootTop)}. Agent worktrees are cut by the ` +
|
|
218
|
+
"runtime from the SESSION's directory, so this run would do its work in the wrong repository " +
|
|
219
|
+
"and succeed — which is how run wf_5e3ed885-98c put a remediation agent in a checkout of " +
|
|
220
|
+
"one consumer's repository while working an issue in another (#218). cd into projectRoot and relaunch",
|
|
221
|
+
};
|
|
222
|
+
}
|
|
223
|
+
|
|
224
|
+
// Same project, different working tree. The quiet one: nothing fails, and
|
|
225
|
+
// the run lands on whatever branch that tree happens to be parked on.
|
|
226
|
+
const cwdBranch = branchOf(cwdTop);
|
|
227
|
+
const rootBranch = branchOf(rootTop);
|
|
228
|
+
return {
|
|
229
|
+
...here,
|
|
230
|
+
reading: "DIFFERENT_CHECKOUT",
|
|
231
|
+
refusal:
|
|
232
|
+
`the launching session's working directory ${safe(cwdTop)} and projectRoot ` +
|
|
233
|
+
`${safe(rootTop)} are two different working trees of the same repository ` +
|
|
234
|
+
`(${rootSlug}) — cwd is on ${cwdBranch ?? "an unreadable branch"} and projectRoot is on ` +
|
|
235
|
+
`${rootBranch ?? "an unreadable branch"}. Agent worktrees are cut by the runtime from the ` +
|
|
236
|
+
"SESSION's directory, so this run would cut from a tree it was not handed, and nothing would " +
|
|
237
|
+
"fail. A shared primary parked on another issue's run branch is exactly this state (#640). " +
|
|
238
|
+
"cd into projectRoot and relaunch",
|
|
239
|
+
};
|
|
240
|
+
}
|
|
241
|
+
|
|
242
|
+
/**
|
|
243
|
+
* The refusal string for a launch, or `null` when there is nothing to say.
|
|
244
|
+
*
|
|
245
|
+
* Derived from `launchBaseReading` and never from a second probe, so the
|
|
246
|
+
* boolean and the reading cannot disagree. `SAME_CHECKOUT` is the only
|
|
247
|
+
* reading that clears: UNMEASURED refuses with the rest, because a check
|
|
248
|
+
* that could not be run is not a check that passed.
|
|
249
|
+
*/
|
|
250
|
+
export function launchBaseRefusal(cwd: string, projectRoot: string): string | null {
|
|
251
|
+
const reading = launchBaseReading(cwd, projectRoot);
|
|
252
|
+
return reading.reading === "SAME_CHECKOUT" ? null : reading.refusal;
|
|
253
|
+
}
|
|
@@ -0,0 +1,372 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Read a `path.ts:<N>` citation, and refuse to call it correct (#541).
|
|
3
|
+
*
|
|
4
|
+
* `lib/source-anchor.ts` (#514) is the form this repository is moving TO: a
|
|
5
|
+
* citation that carries the text it is about, so the resolver reports the
|
|
6
|
+
* position instead of the document asserting it. This module is about the
|
|
7
|
+
* 231 citations still written the old way, and the measurement that says
|
|
8
|
+
* why they need a guard rather than a cleanup:
|
|
9
|
+
*
|
|
10
|
+
* Of `specs/GATE-CONTRACTS-SPEC.md`'s seven line citations, the three under
|
|
11
|
+
* a test were correct and **three of the four unguarded ones were already
|
|
12
|
+
* wrong** — `gate-executor.ts:1725` pointed at a `parseFloat`,
|
|
13
|
+
* `evidence-prevalidator.ts:208` at a comment, `scaffold-rungate-config.ts:66`
|
|
14
|
+
* at an unrelated `existsSync`. Each pointed at a plausible-looking line in
|
|
15
|
+
* the right file, and nobody had noticed because nothing could.
|
|
16
|
+
*
|
|
17
|
+
* Two readings follow from that, and both are refusals of a comfortable
|
|
18
|
+
* default:
|
|
19
|
+
*
|
|
20
|
+
* **There is no VALID.** `LineReading` has two arms. A citation that
|
|
21
|
+
* resolves is `UNMEASURED`, not correct: the file exists and the line
|
|
22
|
+
* exists, and whether it is the line the sentence describes is not something
|
|
23
|
+
* this code can decide. A 75% staleness rate in the unguarded half of one
|
|
24
|
+
* document is the argument against reporting "ok" — `0`, `null`, `SKIP` and
|
|
25
|
+
* a green tick are all indistinguishable from a correct answer, and a
|
|
26
|
+
* refusal naming the reading is not.
|
|
27
|
+
*
|
|
28
|
+
* **A citation that cannot be resolved has a named cause.** A file that
|
|
29
|
+
* moved, a bare basename, a basename matching two files, a line past the
|
|
30
|
+
* end — four different repairs, so four different readings. "This citation
|
|
31
|
+
* is broken" is not actionable; `steps.ts:43` is ambiguous between two files
|
|
32
|
+
* and `src/api/auth.ts:23` names nothing at all, and the fix for one is not
|
|
33
|
+
* the fix for the other.
|
|
34
|
+
*
|
|
35
|
+
* The enforcement splits the same way, which is the only honest split
|
|
36
|
+
* available: the anchor form is DECIDABLE, so `citationFailures` is a hard
|
|
37
|
+
* gate over every document in the tree; the line form is not, so the
|
|
38
|
+
* population is held by a both-ways ratchet that records what it banked.
|
|
39
|
+
*/
|
|
40
|
+
import { existsSync, readFileSync, readdirSync, realpathSync, statSync } from "fs";
|
|
41
|
+
import { join, resolve, sep } from "path";
|
|
42
|
+
|
|
43
|
+
import { anchorCitations, citationFailures } from "./source-anchor";
|
|
44
|
+
|
|
45
|
+
/**
|
|
46
|
+
* `path.ts:<N>`, optionally opening a code span.
|
|
47
|
+
*
|
|
48
|
+
* Deliberately NOT matching the historical prose form. "line 4462 of ship.js
|
|
49
|
+
* as it then stood" is a paragraph whose whole point is that the line no
|
|
50
|
+
* longer exists, and refusing it would be refusing the document for being
|
|
51
|
+
* about history. The two forms are distinguished by the colon and nothing
|
|
52
|
+
* else, which is why that boundary is asserted rather than described.
|
|
53
|
+
*/
|
|
54
|
+
export const LINE_CITATION = /`?\b([A-Za-z0-9_./-]+\.(?:ts|js|json)):(\d+)\b/g;
|
|
55
|
+
|
|
56
|
+
export interface LineCitation {
|
|
57
|
+
path: string;
|
|
58
|
+
line: number;
|
|
59
|
+
raw: string;
|
|
60
|
+
}
|
|
61
|
+
|
|
62
|
+
export type BrokenCause =
|
|
63
|
+
| "NO_SUCH_FILE"
|
|
64
|
+
| "UNQUALIFIED_PATH"
|
|
65
|
+
| "AMBIGUOUS_PATH"
|
|
66
|
+
| "PAST_END_OF_FILE"
|
|
67
|
+
| "OUTSIDE_REPOSITORY";
|
|
68
|
+
|
|
69
|
+
/**
|
|
70
|
+
* Two arms. Adding a third that means "fine" would undo the whole module.
|
|
71
|
+
*/
|
|
72
|
+
export type LineReading =
|
|
73
|
+
| { reading: "BROKEN"; cause: BrokenCause; cite: LineCitation; detail: string }
|
|
74
|
+
| { reading: "UNMEASURED"; cite: LineCitation; detail: string };
|
|
75
|
+
|
|
76
|
+
/** Raised when a document that should carry citations yields none (#621). */
|
|
77
|
+
export class NoLineCitationsError extends Error {
|
|
78
|
+
constructor(message: string) {
|
|
79
|
+
super(message);
|
|
80
|
+
this.name = "NoLineCitationsError";
|
|
81
|
+
}
|
|
82
|
+
}
|
|
83
|
+
|
|
84
|
+
/** Every line citation in a document, in order. */
|
|
85
|
+
export function lineCitations(doc: string): LineCitation[] {
|
|
86
|
+
const out: LineCitation[] = [];
|
|
87
|
+
// Anchor citations contain a path and a quoted fragment, and a fragment
|
|
88
|
+
// can end in `.ts:12`. Removing them first stops the new form being
|
|
89
|
+
// counted as an instance of the old one.
|
|
90
|
+
const text = doc.replace(/`[A-Za-z0-9_./-]+@"[^"`]*"`/g, " ");
|
|
91
|
+
for (const m of text.matchAll(LINE_CITATION)) {
|
|
92
|
+
out.push({ path: m[1], line: Number.parseInt(m[2], 10), raw: m[0] });
|
|
93
|
+
}
|
|
94
|
+
return out;
|
|
95
|
+
}
|
|
96
|
+
|
|
97
|
+
const SKIP_DIRS = new Set([
|
|
98
|
+
".git",
|
|
99
|
+
"node_modules",
|
|
100
|
+
"worktrees",
|
|
101
|
+
"dist",
|
|
102
|
+
"build",
|
|
103
|
+
"coverage",
|
|
104
|
+
".next",
|
|
105
|
+
".bun",
|
|
106
|
+
]);
|
|
107
|
+
|
|
108
|
+
function walk(root: string, rel: string, out: string[], want: (p: string) => boolean): void {
|
|
109
|
+
let entries;
|
|
110
|
+
try {
|
|
111
|
+
entries = readdirSync(join(root, rel), { withFileTypes: true });
|
|
112
|
+
} catch {
|
|
113
|
+
// A directory that cannot be read is not an empty directory. Nothing in
|
|
114
|
+
// this walk can repair that, but it must not be reported as "nothing
|
|
115
|
+
// here" either, so the caller's control — a floor on the count — is what
|
|
116
|
+
// catches it rather than a silent zero.
|
|
117
|
+
return;
|
|
118
|
+
}
|
|
119
|
+
for (const e of entries) {
|
|
120
|
+
if (e.name.startsWith(".") && e.name !== ".claude" && e.name !== ".github") continue;
|
|
121
|
+
const next = rel ? `${rel}/${e.name}` : e.name;
|
|
122
|
+
// `isDirectory()` is false for a symlink, which is what keeps the walk
|
|
123
|
+
// out of the `node_modules` link a worktree carries.
|
|
124
|
+
if (e.isDirectory()) {
|
|
125
|
+
if (SKIP_DIRS.has(e.name)) continue;
|
|
126
|
+
walk(root, next, out, want);
|
|
127
|
+
} else if (e.isFile() && want(next)) {
|
|
128
|
+
out.push(next);
|
|
129
|
+
}
|
|
130
|
+
}
|
|
131
|
+
}
|
|
132
|
+
|
|
133
|
+
/** Every repository-relative file path, for deciding whether a basename is unique. */
|
|
134
|
+
export function repoFileIndex(root: string): string[] {
|
|
135
|
+
const out: string[] = [];
|
|
136
|
+
walk(root, "", out, () => true);
|
|
137
|
+
return out.sort();
|
|
138
|
+
}
|
|
139
|
+
|
|
140
|
+
/** Every markdown document in the tree. */
|
|
141
|
+
export function markdownDocuments(root: string): string[] {
|
|
142
|
+
const out: string[] = [];
|
|
143
|
+
walk(root, "", out, p => p.endsWith(".md"));
|
|
144
|
+
return out.sort();
|
|
145
|
+
}
|
|
146
|
+
|
|
147
|
+
/**
|
|
148
|
+
* What a line citation can be said about, which is never that it is right.
|
|
149
|
+
*/
|
|
150
|
+
export function readLineCitation(root: string, index: string[], cite: LineCitation): LineReading {
|
|
151
|
+
const { path } = cite;
|
|
152
|
+
const broken = (cause: BrokenCause, detail: string): LineReading =>
|
|
153
|
+
({ reading: "BROKEN", cause, cite, detail });
|
|
154
|
+
|
|
155
|
+
// `join` concatenates a leading slash rather than absorbing it, so an
|
|
156
|
+
// absolute citation reads `<root>/etc/passwd` and the containment check
|
|
157
|
+
// below has nothing to say about it. Refused on its own, because a
|
|
158
|
+
// citation written absolute means something other than what its author
|
|
159
|
+
// thinks it means.
|
|
160
|
+
if (path.startsWith("/")) {
|
|
161
|
+
return broken("OUTSIDE_REPOSITORY", `${path} is absolute — citations are repository-relative`);
|
|
162
|
+
}
|
|
163
|
+
const full = join(root, path);
|
|
164
|
+
if (!resolve(full).startsWith(resolve(root) + sep)) {
|
|
165
|
+
return broken("OUTSIDE_REPOSITORY", `${path} resolves outside the repository`);
|
|
166
|
+
}
|
|
167
|
+
|
|
168
|
+
if (existsSync(full) && statSync(full).isFile()) {
|
|
169
|
+
// The symlink question the lexical check cannot answer: a link inside
|
|
170
|
+
// the tree whose target is outside it passes containment and then reads
|
|
171
|
+
// a file that is not in the repository at all.
|
|
172
|
+
if (!realpathSync(full).startsWith(realpathSync(resolve(root)) + sep)) {
|
|
173
|
+
return broken("OUTSIDE_REPOSITORY", `${path} is a symlink whose target is outside the repository`);
|
|
174
|
+
}
|
|
175
|
+
const lines = readFileSync(full, "utf-8").split("\n").length;
|
|
176
|
+
if (cite.line > lines) {
|
|
177
|
+
return broken("PAST_END_OF_FILE", `${path} has ${lines} lines, so line ${cite.line} is not in it`);
|
|
178
|
+
}
|
|
179
|
+
return {
|
|
180
|
+
reading: "UNMEASURED",
|
|
181
|
+
cite,
|
|
182
|
+
detail:
|
|
183
|
+
`${path}:${cite.line} names a line that exists; whether it is the line this sentence ` +
|
|
184
|
+
`describes cannot be decided mechanically`,
|
|
185
|
+
};
|
|
186
|
+
}
|
|
187
|
+
|
|
188
|
+
// Not a path in this repository. It may still be a basename somebody wrote
|
|
189
|
+
// instead of one, which is a different defect with a different repair.
|
|
190
|
+
const suffix = `/${path}`;
|
|
191
|
+
const candidates = index.filter(f => f === path || f.endsWith(suffix));
|
|
192
|
+
if (candidates.length === 0) {
|
|
193
|
+
return broken("NO_SUCH_FILE", `${path} names no file in the repository`);
|
|
194
|
+
}
|
|
195
|
+
if (candidates.length > 1) {
|
|
196
|
+
return broken(
|
|
197
|
+
"AMBIGUOUS_PATH",
|
|
198
|
+
`${path} matches ${candidates.length} files (${candidates.join(", ")}), so it names no site`,
|
|
199
|
+
);
|
|
200
|
+
}
|
|
201
|
+
return broken(
|
|
202
|
+
"UNQUALIFIED_PATH",
|
|
203
|
+
`${path} is not a repository path; it probably means ${candidates[0]}, and writing that down ` +
|
|
204
|
+
`is the repair`,
|
|
205
|
+
);
|
|
206
|
+
}
|
|
207
|
+
|
|
208
|
+
export interface DocumentCensus {
|
|
209
|
+
broken: number;
|
|
210
|
+
unmeasured: number;
|
|
211
|
+
anchors: number;
|
|
212
|
+
readings: LineReading[];
|
|
213
|
+
anchorFailures: string[];
|
|
214
|
+
}
|
|
215
|
+
|
|
216
|
+
/**
|
|
217
|
+
* Count one document's citations by reading.
|
|
218
|
+
*
|
|
219
|
+
* `expectCitations` is the ratchet's statement that this document carries
|
|
220
|
+
* some. When it does and none are found, this THROWS — because a checker
|
|
221
|
+
* that finds zero citations in every document is in perfect agreement, and
|
|
222
|
+
* zero strings are trivially all fine. Returning an empty census would fold
|
|
223
|
+
* a dead pattern into a clean result, which is the exact shape #621
|
|
224
|
+
* describes: the refusal has to escape.
|
|
225
|
+
*/
|
|
226
|
+
export function documentCensus(
|
|
227
|
+
root: string,
|
|
228
|
+
index: string[],
|
|
229
|
+
docPath: string,
|
|
230
|
+
expectCitations: boolean,
|
|
231
|
+
): DocumentCensus {
|
|
232
|
+
const full = join(root, docPath);
|
|
233
|
+
if (!existsSync(full)) {
|
|
234
|
+
throw new NoLineCitationsError(
|
|
235
|
+
`${docPath} is banked in the citation ratchet and is not in the tree. If the document was ` +
|
|
236
|
+
`removed or renamed, delete or move its entry in the same commit.`,
|
|
237
|
+
);
|
|
238
|
+
}
|
|
239
|
+
const text = readFileSync(full, "utf-8");
|
|
240
|
+
const cites = lineCitations(text);
|
|
241
|
+
if (expectCitations && cites.length === 0) {
|
|
242
|
+
throw new NoLineCitationsError(
|
|
243
|
+
`${docPath} is banked in the citation ratchet as carrying line citations and the census ` +
|
|
244
|
+
`found none. Either every one of them was converted — in which case delete the entry's ` +
|
|
245
|
+
`broken and unmeasured counts in the same commit — or LINE_CITATION has stopped matching, ` +
|
|
246
|
+
`in which case this guard was about to pass over the whole tree.`,
|
|
247
|
+
);
|
|
248
|
+
}
|
|
249
|
+
const readings = cites.map(c => readLineCitation(root, index, c));
|
|
250
|
+
return {
|
|
251
|
+
broken: readings.filter(r => r.reading === "BROKEN").length,
|
|
252
|
+
unmeasured: readings.filter(r => r.reading === "UNMEASURED").length,
|
|
253
|
+
anchors: anchorCitations(text).length,
|
|
254
|
+
readings,
|
|
255
|
+
anchorFailures: citationFailures(root, text),
|
|
256
|
+
};
|
|
257
|
+
}
|
|
258
|
+
|
|
259
|
+
export interface RatchetEntry {
|
|
260
|
+
broken: number;
|
|
261
|
+
unmeasured: number;
|
|
262
|
+
anchors: number;
|
|
263
|
+
note?: string;
|
|
264
|
+
}
|
|
265
|
+
|
|
266
|
+
export interface CitationRatchet {
|
|
267
|
+
meaning: string[];
|
|
268
|
+
documents: Record<string, RatchetEntry>;
|
|
269
|
+
}
|
|
270
|
+
|
|
271
|
+
/**
|
|
272
|
+
* The banked population, read from `.claude/line-citation-ratchet.json`.
|
|
273
|
+
*
|
|
274
|
+
* A tree with no file gets no entries — zero tolerance, which is the right
|
|
275
|
+
* default for a project that has never had the defect. `lib/` travels into
|
|
276
|
+
* every scaffolded project and rungate's own numbers have no business there.
|
|
277
|
+
*/
|
|
278
|
+
export function readCitationRatchet(root: string): CitationRatchet {
|
|
279
|
+
const p = join(root, ".claude", "line-citation-ratchet.json");
|
|
280
|
+
if (!existsSync(p)) return { meaning: [], documents: {} };
|
|
281
|
+
const raw = JSON.parse(readFileSync(p, "utf-8"));
|
|
282
|
+
const documents: Record<string, RatchetEntry> = {};
|
|
283
|
+
for (const [k, v] of Object.entries(raw.documents ?? {})) {
|
|
284
|
+
const e = v as Record<string, unknown>;
|
|
285
|
+
if (typeof e?.broken !== "number" || typeof e?.unmeasured !== "number" || typeof e?.anchors !== "number") {
|
|
286
|
+
// A malformed entry is not an absent one. Skipping it silently would
|
|
287
|
+
// turn a typo into an exemption, which is the fail-open this file is
|
|
288
|
+
// about; the comparison below then reports the document as unbanked.
|
|
289
|
+
continue;
|
|
290
|
+
}
|
|
291
|
+
documents[k] = { broken: e.broken, unmeasured: e.unmeasured, anchors: e.anchors };
|
|
292
|
+
}
|
|
293
|
+
return { meaning: Array.isArray(raw.meaning) ? raw.meaning.map(String) : [], documents };
|
|
294
|
+
}
|
|
295
|
+
|
|
296
|
+
/**
|
|
297
|
+
* Turn the census into refusals. THE binding — one place to mutate.
|
|
298
|
+
*
|
|
299
|
+
* Both directions, per number. Over the banked count fails, and so does
|
|
300
|
+
* under it: an entry that has stopped being true is an entry nobody will
|
|
301
|
+
* ever remove, and the file rots into a number nobody lowers.
|
|
302
|
+
*
|
|
303
|
+
* Three numbers rather than one, because a single total cannot see progress
|
|
304
|
+
* happen. Qualifying `ship.js:<N>` to `workflows/ship.js:<N>` deletes
|
|
305
|
+
* nothing and adds nothing, and converting a line citation to the anchor
|
|
306
|
+
* form looks, to a total, exactly like deleting it. **The arithmetic cannot
|
|
307
|
+
* forbid a deletion — a paragraph is allowed to go away — so what it does
|
|
308
|
+
* instead is make the three numbers move differently, so a reviewer reading
|
|
309
|
+
* the diff can tell a conversion from a deletion.** That distinction is the
|
|
310
|
+
* point of the file and it is written into the file.
|
|
311
|
+
*
|
|
312
|
+
* Anchor citations are NOT ratcheted for correctness: an anchor carries its
|
|
313
|
+
* own text, so whether it still names a site is decidable, and there is
|
|
314
|
+
* nothing to tolerate. Their failures are returned as hard violations here
|
|
315
|
+
* for every document in the tree — enforce the half the repository owns,
|
|
316
|
+
* and report the other half as UNMEASURED.
|
|
317
|
+
*/
|
|
318
|
+
export function citationRatchetViolations(
|
|
319
|
+
root: string,
|
|
320
|
+
index: string[],
|
|
321
|
+
docs: string[],
|
|
322
|
+
ratchet: CitationRatchet,
|
|
323
|
+
): string[] {
|
|
324
|
+
const out: string[] = [];
|
|
325
|
+
const seen = new Set<string>();
|
|
326
|
+
|
|
327
|
+
for (const doc of docs) {
|
|
328
|
+
const entry = ratchet.documents[doc];
|
|
329
|
+
seen.add(doc);
|
|
330
|
+
const census = documentCensus(root, index, doc, (entry?.broken ?? 0) + (entry?.unmeasured ?? 0) > 0);
|
|
331
|
+
|
|
332
|
+
for (const f of census.anchorFailures) {
|
|
333
|
+
out.push(`${doc}: an anchor citation no longer names a site — ${f}`);
|
|
334
|
+
}
|
|
335
|
+
|
|
336
|
+
if (!entry) {
|
|
337
|
+
if (census.broken + census.unmeasured > 0) {
|
|
338
|
+
out.push(
|
|
339
|
+
`${doc} is not in .claude/line-citation-ratchet.json and carries ` +
|
|
340
|
+
`${census.broken + census.unmeasured} line citations. A document absent from the ratchet ` +
|
|
341
|
+
`is allowed none: the migration window is exactly when the next one gets written.`,
|
|
342
|
+
);
|
|
343
|
+
}
|
|
344
|
+
continue;
|
|
345
|
+
}
|
|
346
|
+
|
|
347
|
+
const rows: [keyof RatchetEntry & string, number, number][] = [
|
|
348
|
+
["broken", census.broken, entry.broken],
|
|
349
|
+
["unmeasured", census.unmeasured, entry.unmeasured],
|
|
350
|
+
["anchors", census.anchors, entry.anchors],
|
|
351
|
+
];
|
|
352
|
+
for (const [name, found, banked] of rows) {
|
|
353
|
+
if (found === banked) continue;
|
|
354
|
+
out.push(
|
|
355
|
+
found > banked
|
|
356
|
+
? `${doc}: ${found} ${name} citations, ${banked} banked. Bank the number in the same ` +
|
|
357
|
+
`commit that earned it, and say in the PR why it went up.`
|
|
358
|
+
: `${doc}: ${found} ${name} citations, ${banked} banked. Lower it — or delete the entry ` +
|
|
359
|
+
`if the document has none left. A stale entry is a number nobody lowers.`,
|
|
360
|
+
);
|
|
361
|
+
}
|
|
362
|
+
}
|
|
363
|
+
|
|
364
|
+
for (const doc of Object.keys(ratchet.documents)) {
|
|
365
|
+
if (seen.has(doc)) continue;
|
|
366
|
+
out.push(
|
|
367
|
+
`${doc} is banked in .claude/line-citation-ratchet.json and was not among the documents ` +
|
|
368
|
+
`scanned. Delete its entry in the same commit that removed or renamed it.`,
|
|
369
|
+
);
|
|
370
|
+
}
|
|
371
|
+
return out;
|
|
372
|
+
}
|