rungate 0.8.2 → 0.8.3
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/bin/rungate.ts +11 -6
- package/config/prove-evidence.schema.json +21 -3
- package/gates/.gate-salt +1 -1
- package/gates/gate-executor.ts +153 -1
- package/gates/prove.test.ts +12 -6
- package/gates/schema.ts +69 -6
- package/gates/workflow.test.ts +12 -5
- package/hooks/DocHygiene.hook.ts +2 -1
- package/hooks/GateResultProtection.hook.ts +28 -7
- package/hooks/HookCurrency.hook.ts +48 -1
- package/hooks/VerifyPhaseLock.hook.ts +25 -8
- package/hooks/WorkflowStateGuard.hook.ts +24 -7
- package/lib/ai-review-jury.ts +725 -0
- package/lib/ai-review-rounds.ts +791 -4
- package/lib/ai-review-unmeasured.ts +361 -0
- package/lib/bash-write-guard.ts +1235 -102
- package/lib/cli-commands.ts +252 -11
- package/lib/closing-reference-audit.ts +163 -0
- package/lib/conformity.ts +12 -0
- package/lib/create-sc.ts +45 -12
- package/lib/derived-spec.ts +206 -0
- package/lib/file-claims.ts +335 -0
- package/lib/finding-arbiter.ts +502 -28
- package/lib/finding-jury.ts +48 -1
- package/lib/finding-pr-routing.ts +333 -0
- package/lib/frontmatter.ts +16 -0
- package/lib/gate-check-audit.ts +259 -0
- package/lib/generators/agents-md.ts +29 -0
- package/lib/github.ts +112 -7
- package/lib/hook-tree-currency.ts +494 -0
- package/lib/issue-closure-audit.ts +161 -14
- package/lib/issue-create-override.ts +53 -3
- package/lib/issue-filing-gate.ts +1073 -76
- package/lib/local-review-rounds.ts +523 -0
- package/lib/organize.ts +10 -0
- package/lib/project-state-shape.ts +56 -5
- package/lib/repo-path.ts +94 -0
- package/lib/report-provenance.ts +65 -3
- package/lib/risk-tier.ts +302 -0
- package/lib/rounds-to-pass.ts +274 -0
- package/lib/rule-row-drift.ts +199 -0
- package/lib/sc-claim-forms.ts +33 -5
- package/lib/sc-guard.ts +11 -1
- package/lib/sc-id-cross-tree.ts +17 -2
- package/lib/sc-ids.ts +71 -6
- package/lib/sc-reservations.ts +158 -14
- package/lib/scaffold/ai-review-findings.ts +1157 -18
- package/lib/scaffold/ai-review-step.ts +3798 -76
- package/lib/scaffold/ai-review-unmeasured-workflow.ts +243 -0
- package/lib/scaffold/owned-files.ts +14 -0
- package/lib/scaffold/steps.ts +83 -9
- package/lib/scratch-roots.ts +93 -3
- package/lib/spec-updater.ts +16 -0
- package/lib/validators/spec-validators.ts +28 -2
- package/package.json +2 -1
- package/scripts/ai-review-findings.ts +41 -1
- package/scripts/arbitrate-finding.ts +330 -12
- package/scripts/audit-specs.ts +225 -23
- package/scripts/create-sc.ts +11 -0
- package/scripts/detect-sc-drift.ts +10 -2
- package/scripts/record-ai-review-unmeasured.ts +370 -0
- package/scripts/split-spec.ts +12 -0
- package/scripts/sync-sc-status.ts +11 -0
package/lib/repo-path.ts
ADDED
|
@@ -0,0 +1,94 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* One function that turns a string into a comparable repository path (#1437).
|
|
3
|
+
*
|
|
4
|
+
* Covers CRC-E2's precondition (CODE-REVIEW-CONVERGENCE-SPEC.md): a classifier
|
|
5
|
+
* that reads the change can only be trusted if both sides of every path
|
|
6
|
+
* comparison were spelled by the same hand.
|
|
7
|
+
*
|
|
8
|
+
* ## Why this is its own module
|
|
9
|
+
*
|
|
10
|
+
* The first version of this lived inside `lib/scaffold/ai-review-findings.ts`,
|
|
11
|
+
* where it decides whether a finding names a file the pull request touched.
|
|
12
|
+
* `lib/risk-tier.ts` needs the identical question answered — does this changed
|
|
13
|
+
* path sit under a sensitive prefix — and two private answers to one question
|
|
14
|
+
* are behaviourally ONE decider with a dead copy nobody can identify
|
|
15
|
+
* (`.claude/rules/checks-must-be-able-to-fail.md`, the fourth shape).
|
|
16
|
+
*
|
|
17
|
+
* So the function lives here and both import it. The findings module still
|
|
18
|
+
* carries its own copy while #1435 is open; collapsing that one into this
|
|
19
|
+
* import is a one-line follow-up once #1435 lands, and it is deliberately NOT
|
|
20
|
+
* done from this branch — chaining onto an unmerged tip replays commits a
|
|
21
|
+
* squash merge is about to rewrite.
|
|
22
|
+
*
|
|
23
|
+
* ## What it refuses, and why refusing is the point
|
|
24
|
+
*
|
|
25
|
+
* A path it cannot read returns `null`, and every caller must decide what
|
|
26
|
+
* `null` means for it. Both current callers decide the same way — toward the
|
|
27
|
+
* stricter answer, blocking or HIGH — because the alternative is a gate that
|
|
28
|
+
* fails open on input it did not understand, which is the exact defect the
|
|
29
|
+
* push review found in the findings module's round one: six spellings of a
|
|
30
|
+
* file that WAS in the change list each read as "not in the change list" and
|
|
31
|
+
* demoted a `critical` to CLEAN.
|
|
32
|
+
*
|
|
33
|
+
* Git C-quoting (`"lib/\303\251.ts"`) is refused rather than decoded. Decoding
|
|
34
|
+
* it wrongly is the same fail-open wearing a different hat, and a caller that
|
|
35
|
+
* is told "I could not read this" can route to a person; a caller handed a
|
|
36
|
+
* mis-decoded path cannot tell that anything happened.
|
|
37
|
+
*/
|
|
38
|
+
|
|
39
|
+
/**
|
|
40
|
+
* A repository-relative path in a single spelling, or `null` when the input
|
|
41
|
+
* cannot be read as one.
|
|
42
|
+
*
|
|
43
|
+
* Normalises: backslash separators, a leading `./`, leading slashes, a
|
|
44
|
+
* trailing `:line` or `:line:col` suffix, and case. Refuses: anything that is
|
|
45
|
+
* not a string, a git C-quoted path, and anything whose remaining shape is not
|
|
46
|
+
* a plain sequence of path segments.
|
|
47
|
+
*/
|
|
48
|
+
export function normaliseRepoPath(value: unknown): string | null {
|
|
49
|
+
if (typeof value !== "string") return null;
|
|
50
|
+
let p = value.trim().replace(/\\/g, "/");
|
|
51
|
+
// A C-quoted path is refused, not decoded — see the module docblock.
|
|
52
|
+
if (p.startsWith('"') && p.endsWith('"')) return null;
|
|
53
|
+
p = p.replace(/^\/+/, "").replace(/:\d+(?::\d+)?$/, "");
|
|
54
|
+
|
|
55
|
+
// Dot segments are COLLAPSED, not stripped once. A single `.replace(/^\.\//)`
|
|
56
|
+
// removes one leading `./` and leaves `././lib/a.ts` as `./lib/a.ts`, which
|
|
57
|
+
// the shape test below accepts — `.` and `..` are both legal matches for
|
|
58
|
+
// `[\w.@+-]+`. The result compares unequal to `lib/a.ts` and every caller
|
|
59
|
+
// reads that as "a different file", which is this module's fail-open in its
|
|
60
|
+
// purest form: an attacker-chosen spelling of a path that IS in the change
|
|
61
|
+
// list reads as one that is not. Found by the push review on #1435.
|
|
62
|
+
//
|
|
63
|
+
// A `..` that would leave the repository root is refused rather than
|
|
64
|
+
// clamped: `../outside.ts` is not a repository-relative path, and silently
|
|
65
|
+
// turning it into `outside.ts` invents a file.
|
|
66
|
+
const out: string[] = [];
|
|
67
|
+
for (const segment of p.split("/")) {
|
|
68
|
+
if (segment === "" || segment === ".") continue;
|
|
69
|
+
if (segment === "..") {
|
|
70
|
+
if (out.pop() === undefined) return null;
|
|
71
|
+
continue;
|
|
72
|
+
}
|
|
73
|
+
out.push(segment);
|
|
74
|
+
}
|
|
75
|
+
p = out.join("/");
|
|
76
|
+
if (p === "") return null;
|
|
77
|
+
|
|
78
|
+
return /^(?:[\w.@+-]+\/)*[\w.@+-]+$/.test(p) ? p.toLowerCase() : null;
|
|
79
|
+
}
|
|
80
|
+
|
|
81
|
+
/**
|
|
82
|
+
* Does `path` sit at or under `prefix`? Both sides are normalised first.
|
|
83
|
+
*
|
|
84
|
+
* Segment-aware on purpose: `.github/workflows` must not match
|
|
85
|
+
* `.github/workflows-archive/x.yml`, which a bare `startsWith` would.
|
|
86
|
+
* Returns false when either side cannot be read — the caller decides what an
|
|
87
|
+
* unreadable path means, and this function never invents an answer.
|
|
88
|
+
*/
|
|
89
|
+
export function underPrefix(path: unknown, prefix: string): boolean {
|
|
90
|
+
const p = normaliseRepoPath(path);
|
|
91
|
+
const q = normaliseRepoPath(prefix.replace(/\/+$/, ""));
|
|
92
|
+
if (p === null || q === null) return false;
|
|
93
|
+
return p === q || p.startsWith(`${q}/`);
|
|
94
|
+
}
|
package/lib/report-provenance.ts
CHANGED
|
@@ -42,7 +42,23 @@ import { reviewIsCurrent } from "./security-verdict";
|
|
|
42
42
|
/** The exit code of a stale or unmeasurable reading. One site, so it can be mutated. */
|
|
43
43
|
export const STALE_EXIT = 1;
|
|
44
44
|
|
|
45
|
+
/**
|
|
46
|
+
* The refusal when the directory read is not the one under review (#1348).
|
|
47
|
+
*
|
|
48
|
+
* One site, so `test/report-provenance.test.ts` can prove the refusal fires
|
|
49
|
+
* rather than inferring it from an exit code that a dozen other conditions
|
|
50
|
+
* also produce.
|
|
51
|
+
*/
|
|
52
|
+
export const WRONG_TREE = "UNMEASURED: wrong tree";
|
|
53
|
+
|
|
45
54
|
export interface ProvenanceReading {
|
|
55
|
+
/**
|
|
56
|
+
* The directory the reading was taken in. Always present: a SHA does not
|
|
57
|
+
* say where it was read, and that is the fact a reader cannot reconstruct.
|
|
58
|
+
*/
|
|
59
|
+
root: string;
|
|
60
|
+
/** The branch checked out at `root`, or null for a detached HEAD. */
|
|
61
|
+
branch: string | null;
|
|
46
62
|
/** The commit the report describes. */
|
|
47
63
|
measured: string | null;
|
|
48
64
|
/** The commit the branch ends at now, or null when it could not be read. */
|
|
@@ -67,6 +83,16 @@ function git(root: string, args: string[]): string | null {
|
|
|
67
83
|
}
|
|
68
84
|
}
|
|
69
85
|
|
|
86
|
+
/**
|
|
87
|
+
* The branch checked out at `root`. Null for a detached HEAD, an empty
|
|
88
|
+
* answer, or a directory that is not a repository — all three are "there is
|
|
89
|
+
* no branch here", which is a different fact from any branch name.
|
|
90
|
+
*/
|
|
91
|
+
export function branchAt(root: string): string | null {
|
|
92
|
+
const branch = git(root, ["rev-parse", "--abbrev-ref", "HEAD"]);
|
|
93
|
+
return branch === null || branch === "" || branch === "HEAD" ? null : branch;
|
|
94
|
+
}
|
|
95
|
+
|
|
70
96
|
/**
|
|
71
97
|
* The ref whose tip a report should be aged against.
|
|
72
98
|
*
|
|
@@ -75,8 +101,8 @@ function git(root: string, args: string[]): string | null {
|
|
|
75
101
|
* has not been pushed. Detached HEAD has no branch and says so.
|
|
76
102
|
*/
|
|
77
103
|
export function defaultRef(root: string): string | null {
|
|
78
|
-
const branch =
|
|
79
|
-
if (branch === null
|
|
104
|
+
const branch = branchAt(root);
|
|
105
|
+
if (branch === null) return null;
|
|
80
106
|
if (git(root, ["rev-parse", "--verify", "--quiet", `refs/remotes/origin/${branch}`]) !== null) {
|
|
81
107
|
return `origin/${branch}`;
|
|
82
108
|
}
|
|
@@ -93,12 +119,35 @@ export function provenanceReading(
|
|
|
93
119
|
root: string,
|
|
94
120
|
measured?: string,
|
|
95
121
|
ref?: string,
|
|
122
|
+
expectBranch?: string,
|
|
96
123
|
): ProvenanceReading {
|
|
97
124
|
const measuredSha = measured ?? git(root, ["rev-parse", "HEAD"]);
|
|
125
|
+
const branch = branchAt(root);
|
|
126
|
+
|
|
127
|
+
// Before anything else, because a reading taken in the wrong directory is
|
|
128
|
+
// not stale and not current — it is about a different tree, and every
|
|
129
|
+
// other field below would be a true statement about the wrong thing.
|
|
130
|
+
if (expectBranch !== undefined && branch !== expectBranch) {
|
|
131
|
+
return {
|
|
132
|
+
root,
|
|
133
|
+
branch,
|
|
134
|
+
measured: measuredSha,
|
|
135
|
+
tip: null,
|
|
136
|
+
ref: null,
|
|
137
|
+
current: false,
|
|
138
|
+
reason:
|
|
139
|
+
`${WRONG_TREE}: ${root} is on ${branch ?? "no branch"}, not ${expectBranch}. ` +
|
|
140
|
+
`A command reads the directory it ran in, which here is not the one under ` +
|
|
141
|
+
`review — re-run it in the worktree holding ${expectBranch}.`,
|
|
142
|
+
};
|
|
143
|
+
}
|
|
144
|
+
|
|
98
145
|
const resolvedRef = ref ?? defaultRef(root);
|
|
99
146
|
|
|
100
147
|
if (resolvedRef === null) {
|
|
101
148
|
return {
|
|
149
|
+
root,
|
|
150
|
+
branch,
|
|
102
151
|
measured: measuredSha,
|
|
103
152
|
tip: null,
|
|
104
153
|
ref: null,
|
|
@@ -117,6 +166,8 @@ export function provenanceReading(
|
|
|
117
166
|
const tip = git(root, ["rev-parse", "--verify", `${resolvedRef}^{commit}`]);
|
|
118
167
|
if (tip === null) {
|
|
119
168
|
return {
|
|
169
|
+
root,
|
|
170
|
+
branch,
|
|
120
171
|
measured: measuredSha,
|
|
121
172
|
tip: null,
|
|
122
173
|
ref: resolvedRef,
|
|
@@ -132,6 +183,8 @@ export function provenanceReading(
|
|
|
132
183
|
// two to parity; this is the library side, imported rather than repeated.
|
|
133
184
|
const currency = reviewIsCurrent(measuredSha, tip);
|
|
134
185
|
return {
|
|
186
|
+
root,
|
|
187
|
+
branch,
|
|
135
188
|
measured: measuredSha,
|
|
136
189
|
tip,
|
|
137
190
|
ref: resolvedRef,
|
|
@@ -143,9 +196,18 @@ export function provenanceReading(
|
|
|
143
196
|
};
|
|
144
197
|
}
|
|
145
198
|
|
|
146
|
-
/**
|
|
199
|
+
/**
|
|
200
|
+
* The block to paste at the top of a report. Always states the directory
|
|
201
|
+
* and both commits.
|
|
202
|
+
*
|
|
203
|
+
* The directory line is first because it is the one a reader cannot
|
|
204
|
+
* reconstruct from the others (#1348): two SHAs describe a tree without
|
|
205
|
+
* saying which checkout they were read in, and a report whose reviewer was
|
|
206
|
+
* sitting in another worktree looks exactly like one whose reviewer was not.
|
|
207
|
+
*/
|
|
147
208
|
export function provenanceBlock(reading: ProvenanceReading): string {
|
|
148
209
|
const lines = [
|
|
210
|
+
`Measured in: ${reading.root} (branch ${reading.branch ?? "none"})`,
|
|
149
211
|
`Measured against: ${reading.measured ?? "UNKNOWN"}`,
|
|
150
212
|
`Branch tip (${reading.ref ?? "unresolved"}): ${reading.tip ?? "UNKNOWN"}`,
|
|
151
213
|
reading.current
|
package/lib/risk-tier.ts
ADDED
|
@@ -0,0 +1,302 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Risk tiers, and the classifier that reads a change to set one (#1437).
|
|
3
|
+
*
|
|
4
|
+
* Covers CRC-E1, CRC-E2, CRC-E4 (specs/CODE-REVIEW-CONVERGENCE-SPEC.md,
|
|
5
|
+
* Layer 5 — human approval scaled by risk).
|
|
6
|
+
*
|
|
7
|
+
* ## What problem this is pointed at
|
|
8
|
+
*
|
|
9
|
+
* Measured on this repository on 2026-10-23 at 19:15Z: 15 open pull requests,
|
|
10
|
+
* 2 with auto-merge armed. Nine were red on `ai-review` and not one of them
|
|
11
|
+
* for a defect in its own code — five because `main` had moved
|
|
12
|
+
* `.github/workflows/ai-review.yml` underneath them, and five because they
|
|
13
|
+
* EDIT that file, which the action refuses by construction.
|
|
14
|
+
*
|
|
15
|
+
* The thing deciding whether each of those merges was a person reading
|
|
16
|
+
* fifteen diffs. That is the bottleneck a tier is for: a change that needs
|
|
17
|
+
* nobody should not wait for somebody.
|
|
18
|
+
*
|
|
19
|
+
* ## CRC-E2 — the change sets the tier, not the author
|
|
20
|
+
*
|
|
21
|
+
* `classifyChange` takes a change. There is no author, actor, login, team or
|
|
22
|
+
* branch name in `ChangeUnderReview`, and `test/risk-tier.test.ts` asserts
|
|
23
|
+
* that the key set contains no such field, because the criterion is about
|
|
24
|
+
* what the function is ALLOWED to read and a docblock promising it cannot be
|
|
25
|
+
* checked. A classifier that can see who wrote something will eventually be
|
|
26
|
+
* asked to be lenient about it.
|
|
27
|
+
*
|
|
28
|
+
* ## CRC-E4 — a CI workflow file always needs a human
|
|
29
|
+
*
|
|
30
|
+
* `ALWAYS_HIGH_PREFIXES` is the floor and it is not reachable from config.
|
|
31
|
+
* Owner-listed sensitive paths ADD to it; nothing subtracts. A deployment
|
|
32
|
+
* that could configure its way out of "a CI workflow file needs a person"
|
|
33
|
+
* has a setting whose only use is to switch the criterion off, and the
|
|
34
|
+
* criterion exists because that is the change class where switching it off is
|
|
35
|
+
* most attractive and worst.
|
|
36
|
+
*
|
|
37
|
+
* Today this repository satisfies CRC-E4 by accident and in its worst form:
|
|
38
|
+
* `ai-review` refuses any pull request whose copy of its own workflow file
|
|
39
|
+
* differs from the default branch's, so a change to the reviewer cannot pass
|
|
40
|
+
* the reviewer, and the documented escape — the `ai-review-override` label —
|
|
41
|
+
* WAIVES the check rather than routing to a person. A waiver records nothing
|
|
42
|
+
* about whether anybody read the diff. A tier does.
|
|
43
|
+
*
|
|
44
|
+
* ## UNMEASURED is not LOW
|
|
45
|
+
*
|
|
46
|
+
* A change list that could not be read is not a small change. Every refusal
|
|
47
|
+
* here returns `tier: null` with the entries that caused it, and a caller
|
|
48
|
+
* that treats `null` as "fine" has rebuilt the fail-open this module exists
|
|
49
|
+
* to avoid. `.claude/rules/config-access.md` calls the alternative *Silent
|
|
50
|
+
* Default Substitution*; in a risk classifier it is the whole failure.
|
|
51
|
+
*
|
|
52
|
+
* ## Where the numbers came from, and CRC-E9
|
|
53
|
+
*
|
|
54
|
+
* `LOW_MAX_FILES` and `LOW_MAX_LINES` start strict and are not evidence-based
|
|
55
|
+
* yet — nothing in this repository has measured what size of change reaches
|
|
56
|
+
* main without a defect. CRC-E9 ("tiers start strict and loosen with
|
|
57
|
+
* evidence") is the criterion that makes them move, and it is deliberately
|
|
58
|
+
* not implemented here: loosening needs a recorded outcome to loosen against,
|
|
59
|
+
* and the ledger that would hold it does not carry tiers yet. Starting strict
|
|
60
|
+
* and staying there is the honest state, and it is the direction this is
|
|
61
|
+
* allowed to be wrong in.
|
|
62
|
+
*/
|
|
63
|
+
|
|
64
|
+
import { underPrefix, normaliseRepoPath } from "./repo-path";
|
|
65
|
+
|
|
66
|
+
/** Low needs no human, medium one, high two. */
|
|
67
|
+
export type RiskTier = "low" | "medium" | "high";
|
|
68
|
+
|
|
69
|
+
export interface TierPolicy {
|
|
70
|
+
/** CRC-E1: how many PEOPLE must approve. An agent is never one of them. */
|
|
71
|
+
readonly humansRequired: 0 | 1 | 2;
|
|
72
|
+
readonly meaning: string;
|
|
73
|
+
}
|
|
74
|
+
|
|
75
|
+
/**
|
|
76
|
+
* CRC-E1: the tiers, written down, in one place.
|
|
77
|
+
*
|
|
78
|
+
* `humansRequired` is a count of people. CRC-E6 — an agent's approval never
|
|
79
|
+
* counts as a person's — is a property of whoever reads this number, and this
|
|
80
|
+
* repository cannot currently observe it: branch protection declares no
|
|
81
|
+
* required reviews, so there is no approval state for an agent to pollute.
|
|
82
|
+
* The field is named `humansRequired` rather than `approvalsRequired` so that
|
|
83
|
+
* the day there is one, the distinction is already in the type.
|
|
84
|
+
*/
|
|
85
|
+
export const RISK_TIERS: Record<RiskTier, TierPolicy> = {
|
|
86
|
+
low: {
|
|
87
|
+
humansRequired: 0,
|
|
88
|
+
meaning: "Checks are the review. Arm auto-merge and move on.",
|
|
89
|
+
},
|
|
90
|
+
medium: {
|
|
91
|
+
humansRequired: 1,
|
|
92
|
+
meaning: "One person reads the diff before it merges.",
|
|
93
|
+
},
|
|
94
|
+
high: {
|
|
95
|
+
humansRequired: 2,
|
|
96
|
+
meaning: "Two people read the diff. No waiver substitutes for either.",
|
|
97
|
+
},
|
|
98
|
+
};
|
|
99
|
+
|
|
100
|
+
/**
|
|
101
|
+
* CRC-E4's floor. Any changed path at or under one of these is HIGH, and no
|
|
102
|
+
* configuration can lower it.
|
|
103
|
+
*
|
|
104
|
+
* `.github/workflows/` is a GitHub fact, not a consumer-specific value, which
|
|
105
|
+
* is why it is built in rather than read from a project's config — a consumer
|
|
106
|
+
* that has never configured anything still gets the criterion.
|
|
107
|
+
*/
|
|
108
|
+
export const ALWAYS_HIGH_PREFIXES: readonly string[] = [".github/workflows"];
|
|
109
|
+
|
|
110
|
+
/** Below these a change may be LOW. They start strict — see CRC-E9 above. */
|
|
111
|
+
export const LOW_MAX_FILES = 5;
|
|
112
|
+
export const LOW_MAX_LINES = 150;
|
|
113
|
+
|
|
114
|
+
export type RiskReason =
|
|
115
|
+
/** CRC-E4, the built-in floor. */
|
|
116
|
+
| "CI_WORKFLOW_FILE"
|
|
117
|
+
/** CRC-E4, an owner-listed path. */
|
|
118
|
+
| "OWNER_SENSITIVE_PATH"
|
|
119
|
+
/** Too many files or lines to call small. */
|
|
120
|
+
| "SIZE"
|
|
121
|
+
/** The size of the change was not supplied, so it is not known to be small. */
|
|
122
|
+
| "SIZE_UNKNOWN"
|
|
123
|
+
/** Nothing raised it. */
|
|
124
|
+
| "NO_ESCALATION";
|
|
125
|
+
|
|
126
|
+
export type RiskRefusal =
|
|
127
|
+
/** The list could not be read at all — a caller passed null. */
|
|
128
|
+
| "CHANGED_FILES_UNREADABLE"
|
|
129
|
+
/** The list was read and is empty. A change touching nothing is not small. */
|
|
130
|
+
| "CHANGED_FILES_EMPTY"
|
|
131
|
+
/** At least one entry is not a repository path. */
|
|
132
|
+
| "CHANGED_FILE_UNREADABLE"
|
|
133
|
+
/**
|
|
134
|
+
* An owner CONFIGURED a sensitive path the classifier cannot read.
|
|
135
|
+
*
|
|
136
|
+
* This is the refusal it is most tempting to skip, and the most dangerous
|
|
137
|
+
* to. `underPrefix` returns false on a prefix it cannot read, so a
|
|
138
|
+
* configured `billing/**` or `src/auth/*` would match nothing, every path
|
|
139
|
+
* under it would read as not-sensitive, and the owner would see LOW on
|
|
140
|
+
* exactly the changes they wrote the setting to catch. The classifier
|
|
141
|
+
* being silent is what makes it worse than having no setting at all.
|
|
142
|
+
*/
|
|
143
|
+
| "SENSITIVE_PATH_UNREADABLE";
|
|
144
|
+
|
|
145
|
+
export interface ChangeUnderReview {
|
|
146
|
+
/**
|
|
147
|
+
* Every path the change touches. `null` means the list could not be read,
|
|
148
|
+
* which is UNMEASURED and never LOW.
|
|
149
|
+
*/
|
|
150
|
+
readonly changedFiles: readonly unknown[] | null;
|
|
151
|
+
/** Added plus deleted lines. Absent means unknown, which is never LOW. */
|
|
152
|
+
readonly linesChanged?: number;
|
|
153
|
+
/** Owner-listed sensitive paths. These ADD to the floor; none subtracts. */
|
|
154
|
+
readonly sensitivePaths?: readonly string[];
|
|
155
|
+
}
|
|
156
|
+
|
|
157
|
+
export interface RiskReading {
|
|
158
|
+
/** `null` is UNMEASURED. It is not a tier and it is not LOW. */
|
|
159
|
+
readonly tier: RiskTier | null;
|
|
160
|
+
readonly humansRequired: number | null;
|
|
161
|
+
readonly reasons: readonly RiskReason[];
|
|
162
|
+
readonly refusals: readonly RiskRefusal[];
|
|
163
|
+
/** Human-readable lines naming what was read and what it implied. */
|
|
164
|
+
readonly detail: readonly string[];
|
|
165
|
+
}
|
|
166
|
+
|
|
167
|
+
/**
|
|
168
|
+
* CRC-E4, as ONE exported decision site.
|
|
169
|
+
*
|
|
170
|
+
* Every escalation to HIGH goes through this function, so a mutation of it is
|
|
171
|
+
* a mutation of the whole criterion and `test/risk-tier.test.ts` can prove the
|
|
172
|
+
* classifier is able to fail. A later branch that inlines its own prefix
|
|
173
|
+
* comparison bypasses that mutation and the criterion goes green having
|
|
174
|
+
* witnessed nothing — `.claude/rules/checks-must-be-able-to-fail.md`.
|
|
175
|
+
*
|
|
176
|
+
* Returns `null` when nothing about the path forces HIGH. An unreadable path
|
|
177
|
+
* also returns `null` here: it is not a REASON for HIGH, it is a refusal, and
|
|
178
|
+
* `classifyChange` handles it one layer up so the two states stay distinct.
|
|
179
|
+
*/
|
|
180
|
+
export function alwaysHighReason(
|
|
181
|
+
path: unknown,
|
|
182
|
+
sensitivePaths: readonly string[] = [],
|
|
183
|
+
): RiskReason | null {
|
|
184
|
+
for (const prefix of ALWAYS_HIGH_PREFIXES) {
|
|
185
|
+
if (underPrefix(path, prefix)) return "CI_WORKFLOW_FILE";
|
|
186
|
+
}
|
|
187
|
+
for (const prefix of sensitivePaths) {
|
|
188
|
+
if (underPrefix(path, prefix)) return "OWNER_SENSITIVE_PATH";
|
|
189
|
+
}
|
|
190
|
+
return null;
|
|
191
|
+
}
|
|
192
|
+
|
|
193
|
+
/**
|
|
194
|
+
* Read a change and say which tier it is in, or refuse.
|
|
195
|
+
*
|
|
196
|
+
* The order is deliberate and is the same ordering lesson as the filing gate:
|
|
197
|
+
* **refusals are read before escalations are counted.** A list with an
|
|
198
|
+
* unreadable entry is UNMEASURED even if another entry already forced HIGH,
|
|
199
|
+
* because "HIGH, and also I could not read part of this" is a reading the
|
|
200
|
+
* caller must see rather than one it should be spared.
|
|
201
|
+
*/
|
|
202
|
+
export function classifyChange(change: ChangeUnderReview): RiskReading {
|
|
203
|
+
const detail: string[] = [];
|
|
204
|
+
const { changedFiles, linesChanged, sensitivePaths = [] } = change;
|
|
205
|
+
|
|
206
|
+
if (changedFiles === null) {
|
|
207
|
+
return unmeasured(["CHANGED_FILES_UNREADABLE"], [
|
|
208
|
+
"The changed-file list could not be read. A change whose extent is " +
|
|
209
|
+
"unknown is UNMEASURED, never low risk.",
|
|
210
|
+
]);
|
|
211
|
+
}
|
|
212
|
+
if (changedFiles.length === 0) {
|
|
213
|
+
return unmeasured(["CHANGED_FILES_EMPTY"], [
|
|
214
|
+
"The changed-file list was read and is empty. Either the change " +
|
|
215
|
+
"touches nothing, or the list was produced wrongly; those are " +
|
|
216
|
+
"different facts and neither is low risk.",
|
|
217
|
+
]);
|
|
218
|
+
}
|
|
219
|
+
|
|
220
|
+
// The CONFIGURED side is read before the change is. `underPrefix` refuses a
|
|
221
|
+
// prefix it cannot read by returning false, which at this call site would
|
|
222
|
+
// mean "not sensitive" — so the decision it defers to the caller is taken
|
|
223
|
+
// here, explicitly, and taken toward refusing.
|
|
224
|
+
const badPrefixes = sensitivePaths.filter(
|
|
225
|
+
s => normaliseRepoPath(typeof s === "string" ? s.replace(/\/+$/, "") : s) === null,
|
|
226
|
+
);
|
|
227
|
+
if (badPrefixes.length > 0) {
|
|
228
|
+
return unmeasured(["SENSITIVE_PATH_UNREADABLE"], [
|
|
229
|
+
`${badPrefixes.length} configured sensitive path(s) could not be read ` +
|
|
230
|
+
`as a repository path: ` +
|
|
231
|
+
`${badPrefixes.slice(0, 3).map(p => JSON.stringify(p)).join(", ")}. ` +
|
|
232
|
+
`Globs are not supported — write the directory. A prefix the ` +
|
|
233
|
+
`classifier cannot read is a prefix it cannot enforce, and matching ` +
|
|
234
|
+
`nothing would report LOW on exactly the paths the setting exists ` +
|
|
235
|
+
`to catch.`,
|
|
236
|
+
]);
|
|
237
|
+
}
|
|
238
|
+
|
|
239
|
+
const unreadable = changedFiles.filter(p => normaliseRepoPath(p) === null);
|
|
240
|
+
if (unreadable.length > 0) {
|
|
241
|
+
return unmeasured(["CHANGED_FILE_UNREADABLE"], [
|
|
242
|
+
`${unreadable.length} of ${changedFiles.length} changed-file entr(ies) ` +
|
|
243
|
+
`could not be read as a repository path: ` +
|
|
244
|
+
`${unreadable.slice(0, 3).map(p => JSON.stringify(p)).join(", ")}. ` +
|
|
245
|
+
`A path the classifier cannot read is a path it cannot compare ` +
|
|
246
|
+
`against a sensitive prefix.`,
|
|
247
|
+
]);
|
|
248
|
+
}
|
|
249
|
+
|
|
250
|
+
const reasons = new Set<RiskReason>();
|
|
251
|
+
for (const path of changedFiles) {
|
|
252
|
+
const reason = alwaysHighReason(path, sensitivePaths);
|
|
253
|
+
if (reason !== null) {
|
|
254
|
+
reasons.add(reason);
|
|
255
|
+
detail.push(
|
|
256
|
+
`${normaliseRepoPath(path)} forces HIGH (${reason}): ` +
|
|
257
|
+
`${RISK_TIERS.high.meaning}`,
|
|
258
|
+
);
|
|
259
|
+
}
|
|
260
|
+
}
|
|
261
|
+
if (reasons.size > 0) return at("high", [...reasons], detail);
|
|
262
|
+
|
|
263
|
+
if (typeof linesChanged !== "number" || !Number.isFinite(linesChanged)) {
|
|
264
|
+
detail.push(
|
|
265
|
+
"The size of this change was not supplied, so it is not known to be " +
|
|
266
|
+
"small. Unknown size is MEDIUM, not LOW.",
|
|
267
|
+
);
|
|
268
|
+
return at("medium", ["SIZE_UNKNOWN"], detail);
|
|
269
|
+
}
|
|
270
|
+
if (changedFiles.length > LOW_MAX_FILES || linesChanged > LOW_MAX_LINES) {
|
|
271
|
+
detail.push(
|
|
272
|
+
`${changedFiles.length} file(s) and ${linesChanged} line(s) changed, ` +
|
|
273
|
+
`over the LOW ceiling of ${LOW_MAX_FILES} file(s) and ` +
|
|
274
|
+
`${LOW_MAX_LINES} line(s).`,
|
|
275
|
+
);
|
|
276
|
+
return at("medium", ["SIZE"], detail);
|
|
277
|
+
}
|
|
278
|
+
|
|
279
|
+
detail.push(
|
|
280
|
+
`${changedFiles.length} file(s) and ${linesChanged} line(s) changed, no ` +
|
|
281
|
+
`sensitive path touched. ${RISK_TIERS.low.meaning}`,
|
|
282
|
+
);
|
|
283
|
+
return at("low", ["NO_ESCALATION"], detail);
|
|
284
|
+
}
|
|
285
|
+
|
|
286
|
+
function at(
|
|
287
|
+
tier: RiskTier,
|
|
288
|
+
reasons: RiskReason[],
|
|
289
|
+
detail: string[],
|
|
290
|
+
): RiskReading {
|
|
291
|
+
return {
|
|
292
|
+
tier,
|
|
293
|
+
humansRequired: RISK_TIERS[tier].humansRequired,
|
|
294
|
+
reasons,
|
|
295
|
+
refusals: [],
|
|
296
|
+
detail,
|
|
297
|
+
};
|
|
298
|
+
}
|
|
299
|
+
|
|
300
|
+
function unmeasured(refusals: RiskRefusal[], detail: string[]): RiskReading {
|
|
301
|
+
return { tier: null, humansRequired: null, reasons: [], refusals, detail };
|
|
302
|
+
}
|