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,323 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Observed failures, mined from the one source that is always in the tree:
|
|
3
|
+
* `fix:` and `Revert` commit subjects (#545).
|
|
4
|
+
*
|
|
5
|
+
* ## Why this source, and not the three others #545 names
|
|
6
|
+
*
|
|
7
|
+
* #545 lists four intake sources — correction language in transcripts, revert
|
|
8
|
+
* and fix-up commits, CI failures on merged PRs, and gate refusals in
|
|
9
|
+
* `workflow-state.json`. Three of them are unreachable from a check running in
|
|
10
|
+
* the configuration CI runs it in:
|
|
11
|
+
*
|
|
12
|
+
* | Source | Needs | Present under an empty `HOME`, no credentials |
|
|
13
|
+
* |---|---|---|
|
|
14
|
+
* | `git log` fix/revert | the repository | **yes** |
|
|
15
|
+
* | CI failures on merged PRs | an authenticated API client | no |
|
|
16
|
+
* | Gate refusals | a populated `~/.rungate` run store | no |
|
|
17
|
+
* | Transcripts | a session store, and a confidentiality decision | no |
|
|
18
|
+
*
|
|
19
|
+
* A miner whose input is absent on a runner has no failing input there and
|
|
20
|
+
* passes vacuously, which is the defect class this repository pays for most
|
|
21
|
+
* often. `git log` is the only one of the four that is offline, in-tree, dated
|
|
22
|
+
* and citable by construction.
|
|
23
|
+
*
|
|
24
|
+
* ## Why a commit subject is a rule candidate at all
|
|
25
|
+
*
|
|
26
|
+
* The thing #544 has to rank on is *a specific observed failure*, not a
|
|
27
|
+
* general principle — "a two-run window cannot falsify a three-arrival model"
|
|
28
|
+
* rather than "verify before asserting". Signal-phrase extraction over prose
|
|
29
|
+
* produces the second kind, 1,010 times on one consumer, with no dates.
|
|
30
|
+
*
|
|
31
|
+
* This repository's commit convention already produces the first kind. Four
|
|
32
|
+
* subjects from `main`, unaltered, beside the hand-written rule each one
|
|
33
|
+
* corresponds to:
|
|
34
|
+
*
|
|
35
|
+
* | Subject | The rule somebody later wrote by hand |
|
|
36
|
+
* |---|---|
|
|
37
|
+
* | `fix(#960): the drift reading stops consulting a config the reviewer can write` | *a control whose input the measured thing can write is not a control* |
|
|
38
|
+
* | `fix(#921): take the containment reading off $HOME` | *run the guard in the configuration CI runs it in* |
|
|
39
|
+
* | `fix(#926, #962): give the bookkeeping list a reachability witness` | *never source a fixture from the list it tests* |
|
|
40
|
+
* | `fix(#506): CONFIG-1 reads the source it could not reach, instead of refusing over it` | *an unreadable position refuses; it does not read as clean* |
|
|
41
|
+
*
|
|
42
|
+
* Each arrives carrying a sha, an ISO date and the issue numbers it cites.
|
|
43
|
+
* Evidence is a property of this source rather than something a scorer infers
|
|
44
|
+
* from text shape, and that is the whole reason #544's promotion criterion can
|
|
45
|
+
* be mechanical.
|
|
46
|
+
*
|
|
47
|
+
* ## WHAT THIS DOES NOT COVER
|
|
48
|
+
*
|
|
49
|
+
* This is a classifier, so the honest question is what it misclassifies. Each
|
|
50
|
+
* escape below is asserted as a case in `test/failure-intake-promotion.test.ts`
|
|
51
|
+
* rather than described here and left unmeasured — a documented escape nobody
|
|
52
|
+
* ran is a sentence, not a boundary.
|
|
53
|
+
*
|
|
54
|
+
* - **A trivial `fix:` is mined as though it were an incident.** `fix(#1): the
|
|
55
|
+
* typo in the README heading (#2)` carries a sha, a date and two issue
|
|
56
|
+
* numbers, so it outranks every doc-prose candidate. Nothing here reads the
|
|
57
|
+
* diff, and "was this failure worth a rule" is not a question a subject line
|
|
58
|
+
* can answer. Narrowing by diff size or by touched path is the obvious next
|
|
59
|
+
* move and is deliberately not taken here, because a narrowing measured
|
|
60
|
+
* against nothing is the other half of this defect class.
|
|
61
|
+
* - **A defect fixed under `feat:` is invisible.** `feat(#892): the collect
|
|
62
|
+
* refusal says whether the copies it refuses are the same bytes` is on `main`
|
|
63
|
+
* and is rule-shaped; it is not mined, because widening to every
|
|
64
|
+
* conventional type would admit `chore` and `docs` with it.
|
|
65
|
+
* - **A revert of a revert reads as a failure.** `Revert "Revert "fix(#7): …""`
|
|
66
|
+
* is a re-land — the original change was right after all — and is classified
|
|
67
|
+
* as a revert anyway.
|
|
68
|
+
* - **A subject with no description is dropped, not reported.** `fix(#5):` with
|
|
69
|
+
* nothing after it falls under the ten-character floor and leaves no trace in
|
|
70
|
+
* the reading. It is counted in `commitsScanned` and nowhere else.
|
|
71
|
+
*
|
|
72
|
+
* The first two are the ones that matter: they are a false positive and a false
|
|
73
|
+
* negative of the SAME classifier, and closing either without measuring the
|
|
74
|
+
* other is how a detector ends up refusing every commit or seeing none.
|
|
75
|
+
*/
|
|
76
|
+
import { spawnSync } from "child_process";
|
|
77
|
+
import { existsSync } from "fs";
|
|
78
|
+
import { join } from "path";
|
|
79
|
+
import { contentHash } from "./content-hash";
|
|
80
|
+
|
|
81
|
+
/** Where a candidate's evidence came from. */
|
|
82
|
+
/**
|
|
83
|
+
* `gate-refusal` is produced by `lib/intake-sources.ts`, not by this module
|
|
84
|
+
* (#545). It lives here because `CandidateEvidence` is the one declaration
|
|
85
|
+
* every producer writes against — a second kind union would be two tables
|
|
86
|
+
* agreeing until they did not.
|
|
87
|
+
*/
|
|
88
|
+
export type EvidenceKind = "fix-commit" | "revert-commit" | "gate-refusal";
|
|
89
|
+
|
|
90
|
+
export interface CandidateEvidence {
|
|
91
|
+
kind: EvidenceKind;
|
|
92
|
+
/** The commit's ISO 8601 committer date. A candidate without one is not evidence-backed. */
|
|
93
|
+
date: string;
|
|
94
|
+
/** The commit sha. The citation a reader can check. */
|
|
95
|
+
citation: string;
|
|
96
|
+
/** Every `#N` the subject names, in order of appearance, deduplicated. */
|
|
97
|
+
issues: number[];
|
|
98
|
+
}
|
|
99
|
+
|
|
100
|
+
export interface EvidenceCandidate {
|
|
101
|
+
/** The failure, in the committer's own words. Never re-derived. */
|
|
102
|
+
rule: string;
|
|
103
|
+
/** `git:<short sha>`, so a candidate says where to look without a line number that rots. */
|
|
104
|
+
source: string;
|
|
105
|
+
/** The whole subject, kept so the reading never has to be re-parsed to be read. */
|
|
106
|
+
context: string;
|
|
107
|
+
hash: string;
|
|
108
|
+
evidence: CandidateEvidence;
|
|
109
|
+
}
|
|
110
|
+
|
|
111
|
+
/**
|
|
112
|
+
* Why a reading is not a reading. Exported because a caller that wants to
|
|
113
|
+
* distinguish the cases must compare against the producer's own spelling
|
|
114
|
+
* rather than a second copy of it.
|
|
115
|
+
*/
|
|
116
|
+
export const NOT_A_GIT_REPOSITORY = "NOT_A_GIT_REPOSITORY";
|
|
117
|
+
export const SHALLOW_HISTORY = "SHALLOW_HISTORY";
|
|
118
|
+
export const GIT_LOG_FAILED = "GIT_LOG_FAILED";
|
|
119
|
+
|
|
120
|
+
/**
|
|
121
|
+
* How far back to read. Bounded on purpose: HYGIENE-6 is a caller, and #508
|
|
122
|
+
* records that check timing out at 5001ms because a scan it owned had become
|
|
123
|
+
* load-sensitive. One `git log` is one subprocess, and this cap keeps its
|
|
124
|
+
* output bounded as well.
|
|
125
|
+
*/
|
|
126
|
+
export const MAX_COMMITS_SCANNED = 500;
|
|
127
|
+
|
|
128
|
+
export interface FailureIntakeReading {
|
|
129
|
+
/**
|
|
130
|
+
* The single discriminator. `unmeasuredReasons` and this field are two
|
|
131
|
+
* projections of one computation, so they cannot disagree.
|
|
132
|
+
*/
|
|
133
|
+
reading: "MEASURED" | "UNMEASURED";
|
|
134
|
+
unmeasuredReasons: string[];
|
|
135
|
+
/**
|
|
136
|
+
* Commits the log actually returned. A reading that produced no candidates
|
|
137
|
+
* over 500 commits and one that produced none over 1 are the same empty
|
|
138
|
+
* list, and only this number tells them apart.
|
|
139
|
+
*/
|
|
140
|
+
commitsScanned: number;
|
|
141
|
+
candidates: EvidenceCandidate[];
|
|
142
|
+
}
|
|
143
|
+
|
|
144
|
+
const CONVENTIONAL_FIX = /^fix(?:\(([^)]*)\))?!?:\s*(.+)$/;
|
|
145
|
+
const REVERT = /^Revert\s+"(.+)"\s*$/;
|
|
146
|
+
const TRAILING_PR = /\s*\(#\d+\)\s*$/;
|
|
147
|
+
const ISSUE_REF = /#(\d+)/g;
|
|
148
|
+
|
|
149
|
+
/**
|
|
150
|
+
* The floor a candidate's text has to clear, matching the one
|
|
151
|
+
* `extractSignalPhrases` applies to doc prose so the two producers do not
|
|
152
|
+
* disagree about what counts as a sentence.
|
|
153
|
+
*/
|
|
154
|
+
const MIN_RULE_LENGTH = 10;
|
|
155
|
+
|
|
156
|
+
export interface ClassifiedSubject {
|
|
157
|
+
kind: EvidenceKind;
|
|
158
|
+
rule: string;
|
|
159
|
+
issues: number[];
|
|
160
|
+
}
|
|
161
|
+
|
|
162
|
+
/**
|
|
163
|
+
* THE detector. One binding, so there is one thing to mutate — a second place
|
|
164
|
+
* deciding "is this commit a reported failure" would survive any mutation of
|
|
165
|
+
* this one and the guard would go green for the wrong reason.
|
|
166
|
+
*
|
|
167
|
+
* Returns `null` for a subject that reports no failure.
|
|
168
|
+
*/
|
|
169
|
+
export function classifyCommitSubject(subject: string): ClassifiedSubject | null {
|
|
170
|
+
const trimmed = subject.trim();
|
|
171
|
+
|
|
172
|
+
const reverted = REVERT.exec(trimmed);
|
|
173
|
+
if (reverted) {
|
|
174
|
+
const inner = reverted[1];
|
|
175
|
+
const innerFix = CONVENTIONAL_FIX.exec(inner);
|
|
176
|
+
const description = describe(innerFix ? innerFix[2] : inner);
|
|
177
|
+
if (!description) return null;
|
|
178
|
+
return { kind: "revert-commit", rule: description, issues: issueRefs(trimmed) };
|
|
179
|
+
}
|
|
180
|
+
|
|
181
|
+
const fixed = CONVENTIONAL_FIX.exec(trimmed);
|
|
182
|
+
if (fixed) {
|
|
183
|
+
const description = describe(fixed[2]);
|
|
184
|
+
if (!description) return null;
|
|
185
|
+
return { kind: "fix-commit", rule: description, issues: issueRefs(trimmed) };
|
|
186
|
+
}
|
|
187
|
+
|
|
188
|
+
return null;
|
|
189
|
+
}
|
|
190
|
+
|
|
191
|
+
/**
|
|
192
|
+
* The sentence, with the trailing `(#PR)` the squash merge appended removed.
|
|
193
|
+
* The PR number is not discarded — `issueRefs` reads it off the whole subject
|
|
194
|
+
* — it is removed from the TEXT, because a rule that ends in a bare number
|
|
195
|
+
* reads as a citation rather than a statement.
|
|
196
|
+
*/
|
|
197
|
+
function describe(raw: string): string | null {
|
|
198
|
+
const text = raw.replace(TRAILING_PR, "").trim().replace(/[.;]$/, "");
|
|
199
|
+
return text.length >= MIN_RULE_LENGTH ? text : null;
|
|
200
|
+
}
|
|
201
|
+
|
|
202
|
+
function issueRefs(subject: string): number[] {
|
|
203
|
+
const seen: number[] = [];
|
|
204
|
+
for (const m of subject.matchAll(ISSUE_REF)) {
|
|
205
|
+
const n = Number(m[1]);
|
|
206
|
+
if (!seen.includes(n)) seen.push(n);
|
|
207
|
+
}
|
|
208
|
+
return seen;
|
|
209
|
+
}
|
|
210
|
+
|
|
211
|
+
function gitStdout(root: string, args: string[]): { status: number; out: string; err: string } {
|
|
212
|
+
const r = spawnSync("git", ["-C", root, ...args], {
|
|
213
|
+
timeout: 60_000,
|
|
214
|
+
maxBuffer: 16 * 1024 * 1024,
|
|
215
|
+
encoding: "utf-8",
|
|
216
|
+
});
|
|
217
|
+
if (r.error) return { status: -1, out: "", err: r.error.message };
|
|
218
|
+
return { status: r.status ?? -1, out: r.stdout ?? "", err: (r.stderr ?? "").trim() };
|
|
219
|
+
}
|
|
220
|
+
|
|
221
|
+
/**
|
|
222
|
+
* Mine `fix:` and `Revert` commits into evidence-bearing candidates.
|
|
223
|
+
*
|
|
224
|
+
* Three states are refusals rather than empty readings, and the third is the
|
|
225
|
+
* one this module exists to be honest about:
|
|
226
|
+
*
|
|
227
|
+
* - **no repository** — nothing to read. A scaffolded project with no `.git`
|
|
228
|
+
* hits this and it is not a failure of the project.
|
|
229
|
+
* - **`git log` could not run** — including a repository with no commits at
|
|
230
|
+
* all, which exits 128. An empty history is not a history with no fixes.
|
|
231
|
+
* - **a shallow clone** — the reading is of a truncated history, so zero
|
|
232
|
+
* candidates means nothing. `actions/checkout@v4` with no `fetch-depth`
|
|
233
|
+
* clones to depth 1, so this is the state a CI runner is in by default and
|
|
234
|
+
* the reading there is UNMEASURED on every run, not a silent pass.
|
|
235
|
+
*
|
|
236
|
+
* In every case the candidates found so far are still returned. Withholding
|
|
237
|
+
* them would make a refusal and an empty tree look alike from the outside,
|
|
238
|
+
* which is the shape being avoided.
|
|
239
|
+
*/
|
|
240
|
+
export function mineFixCommits(
|
|
241
|
+
root: string,
|
|
242
|
+
options?: { maxCommits?: number },
|
|
243
|
+
): FailureIntakeReading {
|
|
244
|
+
const unmeasuredReasons: string[] = [];
|
|
245
|
+
const empty = (): FailureIntakeReading => ({
|
|
246
|
+
reading: "UNMEASURED",
|
|
247
|
+
unmeasuredReasons,
|
|
248
|
+
commitsScanned: 0,
|
|
249
|
+
candidates: [],
|
|
250
|
+
});
|
|
251
|
+
|
|
252
|
+
if (!existsSync(join(root, ".git"))) {
|
|
253
|
+
unmeasuredReasons.push(NOT_A_GIT_REPOSITORY);
|
|
254
|
+
return empty();
|
|
255
|
+
}
|
|
256
|
+
|
|
257
|
+
const shallow = gitStdout(root, ["rev-parse", "--is-shallow-repository"]);
|
|
258
|
+
if (shallow.status === 0 && shallow.out.trim() === "true") {
|
|
259
|
+
unmeasuredReasons.push(SHALLOW_HISTORY);
|
|
260
|
+
}
|
|
261
|
+
|
|
262
|
+
const max = options?.maxCommits ?? MAX_COMMITS_SCANNED;
|
|
263
|
+
// %x1f is the ASCII unit separator: it cannot occur in a subject, so the
|
|
264
|
+
// split cannot be defeated by a commit message containing the delimiter.
|
|
265
|
+
const log = gitStdout(root, [
|
|
266
|
+
"log",
|
|
267
|
+
"--no-merges",
|
|
268
|
+
`-n${max}`,
|
|
269
|
+
"--format=%H%x1f%cI%x1f%s",
|
|
270
|
+
]);
|
|
271
|
+
if (log.status !== 0) {
|
|
272
|
+
unmeasuredReasons.push(`${GIT_LOG_FAILED}: ${log.err || "(no stderr)"}`);
|
|
273
|
+
return empty();
|
|
274
|
+
}
|
|
275
|
+
|
|
276
|
+
const lines = log.out.split("\n").filter((l) => l.length > 0);
|
|
277
|
+
const candidates: EvidenceCandidate[] = [];
|
|
278
|
+
const seen = new Set<string>();
|
|
279
|
+
|
|
280
|
+
for (const line of lines) {
|
|
281
|
+
const [sha, date, subject] = line.split("\u001f");
|
|
282
|
+
if (!sha || !date || subject === undefined) continue;
|
|
283
|
+
const classified = classifyCommitSubject(subject);
|
|
284
|
+
if (!classified) continue;
|
|
285
|
+
const hash = contentHash(classified.rule);
|
|
286
|
+
// The dedup key carries the KIND; the hash does not.
|
|
287
|
+
//
|
|
288
|
+
// Those are two different questions and the first draft asked only one.
|
|
289
|
+
// `Revert "fix(#921): take the containment reading off $HOME"` describes
|
|
290
|
+
// the same sentence as the commit it reverts and means the opposite
|
|
291
|
+
// thing, so a key of the sentence alone drops one of the two — measured,
|
|
292
|
+
// as the first red this module's battery produced.
|
|
293
|
+
//
|
|
294
|
+
// The HASH stays the sentence, because the hash is what
|
|
295
|
+
// `reference/rejected-constraints.md` matches on, and a
|
|
296
|
+
// veto is a judgement about a sentence. So vetoing one vetoes both, which
|
|
297
|
+
// is the intended reading and is asserted rather than assumed.
|
|
298
|
+
const key = `${classified.kind}:${hash}`;
|
|
299
|
+
// Newest first, so the first occurrence of a repeated sentence is the one
|
|
300
|
+
// kept — a re-land cites the most recent observation, not the oldest.
|
|
301
|
+
if (seen.has(key)) continue;
|
|
302
|
+
seen.add(key);
|
|
303
|
+
candidates.push({
|
|
304
|
+
rule: classified.rule,
|
|
305
|
+
source: `git:${sha.slice(0, 8)}`,
|
|
306
|
+
context: subject,
|
|
307
|
+
hash,
|
|
308
|
+
evidence: {
|
|
309
|
+
kind: classified.kind,
|
|
310
|
+
date,
|
|
311
|
+
citation: sha,
|
|
312
|
+
issues: classified.issues,
|
|
313
|
+
},
|
|
314
|
+
});
|
|
315
|
+
}
|
|
316
|
+
|
|
317
|
+
return {
|
|
318
|
+
reading: unmeasuredReasons.length > 0 ? "UNMEASURED" : "MEASURED",
|
|
319
|
+
unmeasuredReasons,
|
|
320
|
+
commitsScanned: lines.length,
|
|
321
|
+
candidates,
|
|
322
|
+
};
|
|
323
|
+
}
|
|
@@ -75,6 +75,7 @@ export function resetFallowAvailability(): void {
|
|
|
75
75
|
*/
|
|
76
76
|
export type FallowUnavailable =
|
|
77
77
|
| { kind: "not-installed"; reason: string }
|
|
78
|
+
| { kind: "timed-out"; reason: string }
|
|
78
79
|
| { kind: "run-failed"; reason: string };
|
|
79
80
|
|
|
80
81
|
export function fallowNotInstalled(): FallowUnavailable {
|
|
@@ -116,6 +117,162 @@ export function fallowRunFailed(detail: string): FallowUnavailable {
|
|
|
116
117
|
};
|
|
117
118
|
}
|
|
118
119
|
|
|
120
|
+
/**
|
|
121
|
+
* The budget, and there is exactly one of it (#935).
|
|
122
|
+
*
|
|
123
|
+
* It is BOTH the spawn's `timeout` and the per-test timeout every FALLOW
|
|
124
|
+
* registration is given, because the defect this constant exists to prevent
|
|
125
|
+
* is the two disagreeing. `lib/conformity.ts` spawned with `timeout: 30_000`
|
|
126
|
+
* inside a `test()` that passed no timeout at all — so bun killed the body at
|
|
127
|
+
* its 5000ms default and the 30s was unreachable, a budget nothing could
|
|
128
|
+
* spend. Measured on `hornjason/agentgrit` PR #310: FALLOW-1 died at 5010ms
|
|
129
|
+
* on a commit that changed two markdown files, four times in one day.
|
|
130
|
+
*
|
|
131
|
+
* A second literal anywhere is the whole bug returning, so
|
|
132
|
+
* `test/fallow-budget-reading.test.ts` holds the population of other budget
|
|
133
|
+
* spellings at zero rather than trusting this comment.
|
|
134
|
+
*/
|
|
135
|
+
export const FALLOW_BUDGET_MS = 30_000;
|
|
136
|
+
|
|
137
|
+
/**
|
|
138
|
+
* A run the clock killed.
|
|
139
|
+
*
|
|
140
|
+
* Its own kind, and NOT a flavour of `run-failed`, because the two send an
|
|
141
|
+
* operator to different places: one says go and look at the tool, this one
|
|
142
|
+
* says the tool was still working when we stopped it. It carries the budget
|
|
143
|
+
* because that is the number the reader would change, and the elapsed time
|
|
144
|
+
* because a run killed at the budget and a run killed by something else at
|
|
145
|
+
* 200ms are different facts.
|
|
146
|
+
*/
|
|
147
|
+
export function fallowTimedOut(budgetMs: number, elapsedMs: number): FallowUnavailable {
|
|
148
|
+
return {
|
|
149
|
+
kind: "timed-out",
|
|
150
|
+
reason:
|
|
151
|
+
`fallow is installed and was still running when the ${budgetMs}ms budget expired ` +
|
|
152
|
+
`(killed after ${elapsedMs}ms) — no static analysis reading was produced. This is ` +
|
|
153
|
+
`UNMEASURED, not a clean result: raise the budget, or warm the index before the run`,
|
|
154
|
+
};
|
|
155
|
+
}
|
|
156
|
+
|
|
157
|
+
/** Only the fields the classifier is allowed to read, so a test can plant one. */
|
|
158
|
+
export interface FallowSpawnResult {
|
|
159
|
+
stdout: { toString(): string };
|
|
160
|
+
stderr?: { toString(): string };
|
|
161
|
+
exitCode: number | null;
|
|
162
|
+
exitedDueToTimeout?: boolean;
|
|
163
|
+
}
|
|
164
|
+
|
|
165
|
+
export type FallowReading<T> = { data: T } | { unavailable: FallowUnavailable };
|
|
166
|
+
|
|
167
|
+
/**
|
|
168
|
+
* The ONE place in the tree that spawns fallow (#935, #621).
|
|
169
|
+
*
|
|
170
|
+
* There were two — `lib/conformity.ts` and `scripts/generate-code-map.ts` —
|
|
171
|
+
* each with its own `timeout: 30_000` literal and only one of them
|
|
172
|
+
* classifying anything. Two positions answering one question with nothing
|
|
173
|
+
* comparing them: mutate either and the other carries on spawning, which is
|
|
174
|
+
* `.claude/rules/checks-must-be-able-to-fail.md`'s fourth shape.
|
|
175
|
+
*
|
|
176
|
+
* **The classification ORDER is the fix, not the `timed-out` arm.** A killed
|
|
177
|
+
* process writes nothing, so a run that exceeded the budget satisfies the
|
|
178
|
+
* empty-stdout branch too — and whichever is tested first decides what the
|
|
179
|
+
* operator is told. Reading `exitedDueToTimeout` second is how a 30-second
|
|
180
|
+
* hang got reported as `fallow is not installed (not a declared dependency)`
|
|
181
|
+
* on a tree where fallow is exactly pinned. An operator acting on that goes
|
|
182
|
+
* and declares a dependency that is already there.
|
|
183
|
+
*
|
|
184
|
+
* `available` and `spawn` are injected rather than reached for, so a case can
|
|
185
|
+
* force a timeout without waiting for one and can prove the absent-tool arm
|
|
186
|
+
* never spawns at all. Both default to the real thing.
|
|
187
|
+
*/
|
|
188
|
+
export function runFallowJson<T>(
|
|
189
|
+
root: string,
|
|
190
|
+
args: string[],
|
|
191
|
+
opts?: {
|
|
192
|
+
budgetMs?: number;
|
|
193
|
+
available?: (root: string) => boolean;
|
|
194
|
+
spawn?: (argv: string[], options: Record<string, unknown>) => FallowSpawnResult;
|
|
195
|
+
},
|
|
196
|
+
): FallowReading<T> {
|
|
197
|
+
const budgetMs = opts?.budgetMs ?? FALLOW_BUDGET_MS;
|
|
198
|
+
const isAvailable = opts?.available ?? fallowAvailable;
|
|
199
|
+
if (!isAvailable(root)) return { unavailable: fallowNotInstalled() };
|
|
200
|
+
|
|
201
|
+
const spawn =
|
|
202
|
+
opts?.spawn ??
|
|
203
|
+
((argv: string[], options: Record<string, unknown>) =>
|
|
204
|
+
Bun.spawnSync(argv, options as Parameters<typeof Bun.spawnSync>[1]) as FallowSpawnResult);
|
|
205
|
+
|
|
206
|
+
const startedAt = Date.now();
|
|
207
|
+
const result = spawn(["npx", "fallow", ...args, "--format", "json", "--quiet"], {
|
|
208
|
+
cwd: root,
|
|
209
|
+
env: { ...process.env, NODE_NO_WARNINGS: "1" },
|
|
210
|
+
timeout: budgetMs,
|
|
211
|
+
});
|
|
212
|
+
const elapsedMs = Date.now() - startedAt;
|
|
213
|
+
|
|
214
|
+
// FIRST, and the order is the whole point — see the docstring above.
|
|
215
|
+
if (result.exitedDueToTimeout) return { unavailable: fallowTimedOut(budgetMs, elapsedMs) };
|
|
216
|
+
|
|
217
|
+
const stdout = result.stdout.toString().trim();
|
|
218
|
+
if (!stdout) {
|
|
219
|
+
const stderr = result.stderr?.toString().trim() ?? "";
|
|
220
|
+
return {
|
|
221
|
+
unavailable: fallowRunFailed(stderr || `exit ${result.exitCode}, no output`),
|
|
222
|
+
};
|
|
223
|
+
}
|
|
224
|
+
// fallow's own error envelope. It is well-formed JSON, so it would parse
|
|
225
|
+
// and be returned as a reading of zero issues.
|
|
226
|
+
if (stdout.startsWith('{"error"')) return { unavailable: fallowRunFailed(stdout) };
|
|
227
|
+
try {
|
|
228
|
+
return { data: JSON.parse(stdout) as T };
|
|
229
|
+
} catch (e) {
|
|
230
|
+
return {
|
|
231
|
+
unavailable: fallowRunFailed(`output did not parse as JSON (${(e as Error).name})`),
|
|
232
|
+
};
|
|
233
|
+
}
|
|
234
|
+
}
|
|
235
|
+
|
|
236
|
+
/**
|
|
237
|
+
* Pay the cold index build once, before anyone is being timed for it.
|
|
238
|
+
*
|
|
239
|
+
* fallow builds an index on first use: ~1.5s cold against ~455ms warm,
|
|
240
|
+
* measured. Four checks run in sequence and the FIRST one pays it, which is
|
|
241
|
+
* why FALLOW-1 looked slow and the three after it looked fast. It was never
|
|
242
|
+
* FALLOW-1 — it is whichever check runs first, and moving the checks around
|
|
243
|
+
* would move the symptom without touching the cause.
|
|
244
|
+
*
|
|
245
|
+
* Failures are deliberately swallowed: this is a warm-up, and every caller
|
|
246
|
+
* takes its own reading immediately afterwards and reports its own outcome.
|
|
247
|
+
* A warm-up that could fail a suite would be a second decider for whether
|
|
248
|
+
* fallow works.
|
|
249
|
+
*
|
|
250
|
+
* It takes the same seam `runFallowJson` does, and that is not symmetry for
|
|
251
|
+
* its own sake. Without it the only assertable property is WHERE the call
|
|
252
|
+
* sits in the source, and a warm-up short-circuited to `return` is invisible
|
|
253
|
+
* to a position check — measured, as row M7 of this change's battery, which
|
|
254
|
+
* came back 0 of 14. Worse, fallow is not installed on this machine or on
|
|
255
|
+
* CI, so `fallowAvailable` is false and the real function returns without
|
|
256
|
+
* spawning too: there was no input anywhere in this repository on which the
|
|
257
|
+
* no-op and the original behaved differently. That is not a check that is
|
|
258
|
+
* blind, it is a row that could not be run
|
|
259
|
+
* (`.claude/rules/checks-must-be-able-to-fail.md`, *before you believe a 0*).
|
|
260
|
+
*/
|
|
261
|
+
export function warmFallow(
|
|
262
|
+
root: string,
|
|
263
|
+
opts?: Parameters<typeof runFallowJson>[2],
|
|
264
|
+
): void {
|
|
265
|
+
// No availability check of its own, deliberately. It had one, and
|
|
266
|
+
// `runFallowJson` opens with the same question — two deciders answering it
|
|
267
|
+
// about the same root, which is behaviourally one and which no test can
|
|
268
|
+
// tell apart. The battery said so before any of this was argued: deleting
|
|
269
|
+
// the guard here was 0 of 15, because the one below it still refused
|
|
270
|
+
// (`.claude/rules/checks-must-be-able-to-fail.md`, fourth shape). There is
|
|
271
|
+
// no input only this copy could reach, so the honest fix is to collapse
|
|
272
|
+
// rather than to invent a case for it.
|
|
273
|
+
runFallowJson(root, ["dead-code"], opts);
|
|
274
|
+
}
|
|
275
|
+
|
|
119
276
|
/**
|
|
120
277
|
* The line a generated document carries in place of a section it could not
|
|
121
278
|
* produce.
|