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.
Files changed (63) hide show
  1. package/bin/rungate.ts +11 -6
  2. package/config/prove-evidence.schema.json +21 -3
  3. package/gates/.gate-salt +1 -1
  4. package/gates/gate-executor.ts +153 -1
  5. package/gates/prove.test.ts +12 -6
  6. package/gates/schema.ts +69 -6
  7. package/gates/workflow.test.ts +12 -5
  8. package/hooks/DocHygiene.hook.ts +2 -1
  9. package/hooks/GateResultProtection.hook.ts +28 -7
  10. package/hooks/HookCurrency.hook.ts +48 -1
  11. package/hooks/VerifyPhaseLock.hook.ts +25 -8
  12. package/hooks/WorkflowStateGuard.hook.ts +24 -7
  13. package/lib/ai-review-jury.ts +725 -0
  14. package/lib/ai-review-rounds.ts +791 -4
  15. package/lib/ai-review-unmeasured.ts +361 -0
  16. package/lib/bash-write-guard.ts +1235 -102
  17. package/lib/cli-commands.ts +252 -11
  18. package/lib/closing-reference-audit.ts +163 -0
  19. package/lib/conformity.ts +12 -0
  20. package/lib/create-sc.ts +45 -12
  21. package/lib/derived-spec.ts +206 -0
  22. package/lib/file-claims.ts +335 -0
  23. package/lib/finding-arbiter.ts +502 -28
  24. package/lib/finding-jury.ts +48 -1
  25. package/lib/finding-pr-routing.ts +333 -0
  26. package/lib/frontmatter.ts +16 -0
  27. package/lib/gate-check-audit.ts +259 -0
  28. package/lib/generators/agents-md.ts +29 -0
  29. package/lib/github.ts +112 -7
  30. package/lib/hook-tree-currency.ts +494 -0
  31. package/lib/issue-closure-audit.ts +161 -14
  32. package/lib/issue-create-override.ts +53 -3
  33. package/lib/issue-filing-gate.ts +1073 -76
  34. package/lib/local-review-rounds.ts +523 -0
  35. package/lib/organize.ts +10 -0
  36. package/lib/project-state-shape.ts +56 -5
  37. package/lib/repo-path.ts +94 -0
  38. package/lib/report-provenance.ts +65 -3
  39. package/lib/risk-tier.ts +302 -0
  40. package/lib/rounds-to-pass.ts +274 -0
  41. package/lib/rule-row-drift.ts +199 -0
  42. package/lib/sc-claim-forms.ts +33 -5
  43. package/lib/sc-guard.ts +11 -1
  44. package/lib/sc-id-cross-tree.ts +17 -2
  45. package/lib/sc-ids.ts +71 -6
  46. package/lib/sc-reservations.ts +158 -14
  47. package/lib/scaffold/ai-review-findings.ts +1157 -18
  48. package/lib/scaffold/ai-review-step.ts +3798 -76
  49. package/lib/scaffold/ai-review-unmeasured-workflow.ts +243 -0
  50. package/lib/scaffold/owned-files.ts +14 -0
  51. package/lib/scaffold/steps.ts +83 -9
  52. package/lib/scratch-roots.ts +93 -3
  53. package/lib/spec-updater.ts +16 -0
  54. package/lib/validators/spec-validators.ts +28 -2
  55. package/package.json +2 -1
  56. package/scripts/ai-review-findings.ts +41 -1
  57. package/scripts/arbitrate-finding.ts +330 -12
  58. package/scripts/audit-specs.ts +225 -23
  59. package/scripts/create-sc.ts +11 -0
  60. package/scripts/detect-sc-drift.ts +10 -2
  61. package/scripts/record-ai-review-unmeasured.ts +370 -0
  62. package/scripts/split-spec.ts +12 -0
  63. package/scripts/sync-sc-status.ts +11 -0
@@ -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
+ }
@@ -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 = git(root, ["rev-parse", "--abbrev-ref", "HEAD"]);
79
- if (branch === null || branch === "" || branch === "HEAD") return 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
- /** The block to paste at the top of a report. Always states both commits. */
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
@@ -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
+ }