wachiman 1.12.0 → 1.14.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.
Files changed (46) hide show
  1. package/README.md +132 -101
  2. package/bin/wachiman.js +1 -1
  3. package/package.json +2 -3
  4. package/skills/wachiman-loop/SKILL.md +91 -0
  5. package/skills/wachiman-review/SKILL.md +2 -2
  6. package/src/call-message.ts +26 -3
  7. package/src/cli.ts +113 -18
  8. package/src/config.ts +99 -32
  9. package/src/connectors/local-git.ts +102 -14
  10. package/src/cost.ts +48 -1
  11. package/src/doctor/checks.ts +1 -1
  12. package/src/engine.ts +910 -89
  13. package/src/estimate.ts +64 -0
  14. package/src/fidelity/block.ts +263 -0
  15. package/src/fidelity/claims-call.ts +172 -0
  16. package/src/fidelity/claims.ts +69 -0
  17. package/src/fidelity/digest.ts +80 -0
  18. package/src/fidelity/grade.ts +242 -0
  19. package/src/fidelity/inert.ts +25 -0
  20. package/src/fidelity/rules.ts +166 -0
  21. package/src/fidelity/sink.ts +135 -0
  22. package/src/fidelity/summary.ts +16 -0
  23. package/src/fidelity/types.ts +93 -0
  24. package/src/formats.ts +16 -3
  25. package/src/history/fingerprint.ts +1 -1
  26. package/src/history/store.ts +44 -6
  27. package/src/init/options.ts +1 -1
  28. package/src/ledger.ts +306 -0
  29. package/src/local.ts +23 -5
  30. package/src/loop/command.ts +441 -0
  31. package/src/loop/state.ts +88 -0
  32. package/src/loop/stop-rule.ts +98 -0
  33. package/src/providers/claude-code.ts +48 -13
  34. package/src/providers/codex.ts +8 -7
  35. package/src/providers/index.ts +6 -3
  36. package/src/providers/types.ts +13 -3
  37. package/src/sinks/common.ts +3 -3
  38. package/src/sinks/json.ts +13 -2
  39. package/src/skills/install.ts +4 -4
  40. package/src/status/command.ts +1 -1
  41. package/src/store/command.ts +109 -0
  42. package/src/store/figures.ts +153 -0
  43. package/src/store/html.ts +138 -0
  44. package/src/store/index.ts +298 -0
  45. package/templates/caller-workflow.yml +84 -57
  46. package/templates/wachiman-review-caller.yml +13 -0
@@ -0,0 +1,242 @@
1
+ /**
2
+ * The PR Confidence grade (ADR 0033, spec section 3), a pure function: the model proposes claims
3
+ * and facts, the engine decides the letter. The first matching row of the table wins, so an
4
+ * incomplete run is `cannot say` whatever else is true, and no row ever depends on a number the
5
+ * model states. There are no plus signs yet (slice 2c).
6
+ *
7
+ * | Grade | When |
8
+ * | cannot say | the run did not finish, files unread, a new commit not reviewed, the text changed |
9
+ * | C | no checkable claim; a contradicted claim; an open Blocker |
10
+ * | B | an unverified claim; an unexplained file; an open Fix; a risk level of high |
11
+ * | A- | a medium risk fact, a dropped risk fact, a place that needs a person, an open Consider |
12
+ * | A | none of the above |
13
+ */
14
+ import type { RiskKind, RiskLevel, RiskMap } from "../risk";
15
+ import { unexplainedFiles } from "./claims";
16
+ import type {
17
+ Assignment,
18
+ Attention,
19
+ AttentionGroup,
20
+ ChangedFile,
21
+ Claim,
22
+ Fidelity,
23
+ Grade,
24
+ OpenFinding,
25
+ } from "./types";
26
+
27
+ /**
28
+ * The level each risk fact kind sets. A copy of `KIND_LEVEL` in `risk.ts`, kept here so this module
29
+ * loads no runtime code from the engine; a test fails if the two drift apart.
30
+ */
31
+ export const FACT_LEVEL: Record<RiskKind, RiskLevel> = {
32
+ "data-migration": "high",
33
+ irreversible: "high",
34
+ auth: "high",
35
+ money: "high",
36
+ concurrency: "medium",
37
+ "public-contract": "medium",
38
+ "config-or-ci": "medium",
39
+ dependency: "low",
40
+ };
41
+
42
+ /** What the grade reads from the risk map (ADR 0031). */
43
+ export type GradeRisk = Pick<RiskMap, "level" | "facts" | "judgement" | "pathReasons" | "droppedFacts">;
44
+
45
+ /** How the run ended and what it read. Every field is required, so a caller cannot forget one and get a letter. */
46
+ export interface RunState {
47
+ finished: boolean;
48
+ /** Set when the engine stopped the run on its own limit. */
49
+ stoppedBy?: "spend-ceiling" | "depth-cap";
50
+ unreadFiles: number;
51
+ /** The claims call read only the start of the title and body: claims after the cut were never judged. */
52
+ textTruncated?: boolean;
53
+ /** The commit this review read. */
54
+ reviewedCommit: string;
55
+ /** The commit the pull request has now. Different from `reviewedCommit`: the review of the new one is not done. */
56
+ headCommit: string;
57
+ /** Digest of the author's text when the claims were read. */
58
+ digestAtRead: string;
59
+ /** Digest of the author's text at the moment the block is written. */
60
+ digestAtWrite: string;
61
+ }
62
+
63
+ export interface GradeInput {
64
+ claims: Claim[];
65
+ assignments: Assignment[];
66
+ changedFiles: ChangedFile[];
67
+ /** Findings of this review that are still open. */
68
+ openFindings: OpenFinding[];
69
+ riskMap: GradeRisk;
70
+ run: RunState;
71
+ /** How many A-graded pull requests the owner has judged (decision 16). Default 0. */
72
+ judgedAGrades?: number;
73
+ }
74
+
75
+ export type GradeResult = Pick<
76
+ Fidelity,
77
+ "grade" | "reasons" | "trial" | "judgedAGrades" | "questions" | "unexplainedFiles" | "sensitivePaths"
78
+ >;
79
+
80
+ const SEVERITY_WORD = { blocker: "Blocker", fix: "Fix", consider: "Consider", info: "Info" } as const;
81
+ const SEVERITY_EMOJI = { blocker: "🔴", fix: "🟠", consider: "🟡", info: "⚪" } as const;
82
+
83
+ const count = (n: number, one: string, many: string) => (n === 1 ? `One ${one}` : `${n} ${many}`);
84
+
85
+ const byPathThenLine = (a: Attention, b: Attention) =>
86
+ a.path < b.path ? -1 : a.path > b.path ? 1 : (a.line ?? 0) - (b.line ?? 0);
87
+
88
+ /**
89
+ * The places that need a person, one entry each, ordered by file then line. Nothing here caps the
90
+ * list, but the judgement items arrive already cut to three by buildRiskMap (src/risk.ts), so at
91
+ * most three of them appear here and count in the A- reason.
92
+ */
93
+ function placesNeedingAttention(input: GradeInput, unexplained: string[]): Attention[] {
94
+ const places: Attention[] = [];
95
+ for (const c of input.claims) {
96
+ const at = c.status === "contradicted" ? c.evidence[0] : undefined;
97
+ if (at) {
98
+ places.push({ kind: "contradicted-claim", path: at.path, line: at.line, text: `claim contradicted: ${c.text}` });
99
+ }
100
+ }
101
+ for (const path of unexplained) {
102
+ places.push({ kind: "unexplained", path, text: "no claim in the pull request explains this change." });
103
+ }
104
+ for (const f of input.openFindings) {
105
+ if (f.severity === "info") continue;
106
+ const place: Attention = {
107
+ kind: "finding",
108
+ path: f.path,
109
+ severity: f.severity,
110
+ text: `${SEVERITY_EMOJI[f.severity]} ${SEVERITY_WORD[f.severity]}: ${f.title}`,
111
+ };
112
+ if (f.line > 0) place.line = f.line;
113
+ places.push(place);
114
+ }
115
+ for (const f of input.riskMap.facts) {
116
+ if (FACT_LEVEL[f.kind] === "low") continue;
117
+ places.push({ kind: "risk-fact", path: f.path, line: f.line, text: `${f.kind}: ${f.why}` });
118
+ }
119
+ for (const j of input.riskMap.judgement) {
120
+ places.push({ kind: "judgement", path: j.path, line: j.line, text: `needs a person (${j.kind}): ${j.why}` });
121
+ }
122
+ return places.sort(byPathThenLine);
123
+ }
124
+
125
+ /** The paths the risk map marks as sensitive: a medium or high path rule, or a fact that is not low. */
126
+ function sensitivePathsOf(risk: GradeRisk): string[] {
127
+ const paths = new Set<string>();
128
+ for (const r of risk.pathReasons) paths.add(r.path);
129
+ for (const f of risk.facts) if (FACT_LEVEL[f.kind] !== "low") paths.add(f.path);
130
+ return [...paths].sort();
131
+ }
132
+
133
+ function cannotSayReasons(run: RunState): string[] {
134
+ const reasons: string[] = [];
135
+ if (run.stoppedBy === "spend-ceiling") reasons.push("The run stopped at the spend ceiling");
136
+ else if (run.stoppedBy === "depth-cap") reasons.push("The run stopped at the depth cap");
137
+ else if (!run.finished) reasons.push("The run did not finish");
138
+ if (run.textTruncated) reasons.push("The pull request text was too long to read in full");
139
+ if (run.unreadFiles > 0) {
140
+ reasons.push(run.unreadFiles === 1 ? "One file was not read" : `${run.unreadFiles} files were not read`);
141
+ }
142
+ if (run.reviewedCommit !== run.headCommit) reasons.push("The review of the new commit has not finished");
143
+ if (run.digestAtRead !== run.digestAtWrite) reasons.push("The pull request text changed while the review was running");
144
+ return reasons;
145
+ }
146
+
147
+ export function computeGrade(input: GradeInput): GradeResult {
148
+ const { claims, riskMap } = input;
149
+ const unexplained = unexplainedFiles(input.changedFiles, input.assignments, claims);
150
+ const questions = placesNeedingAttention(input, unexplained);
151
+ const judgedAGrades = input.judgedAGrades ?? 0;
152
+ const sensitivePaths = sensitivePathsOf(riskMap);
153
+ const result = (grade: Grade, reasons: string[]): GradeResult => ({
154
+ grade,
155
+ reasons,
156
+ trial: grade === "A" || grade === "A-",
157
+ judgedAGrades,
158
+ questions,
159
+ unexplainedFiles: unexplained,
160
+ sensitivePaths,
161
+ });
162
+
163
+ const stopped = cannotSayReasons(input.run);
164
+ if (stopped.length > 0) return result("cannot say", stopped);
165
+
166
+ const openOf = (severity: OpenFinding["severity"]) => input.openFindings.filter((f) => f.severity === severity);
167
+ const blockers = openOf("blocker");
168
+ const fixes = openOf("fix");
169
+ const considers = openOf("consider");
170
+ const contradicted = claims.filter((c) => c.status === "contradicted");
171
+ const unverified = claims.filter((c) => c.status === "unverified");
172
+ const checkable = claims.filter((c) => c.status !== "vague");
173
+
174
+ const c: string[] = [];
175
+ if (checkable.length === 0) c.push("The pull request does not say what it changes");
176
+ for (const claim of contradicted) c.push(`Claim contradicted: ${claim.text}`);
177
+ if (blockers.length > 0) c.push(count(blockers.length, "open Blocker", "open Blockers"));
178
+ if (c.length > 0) return result("C", c);
179
+
180
+ const highFacts = [
181
+ ...new Set(riskMap.facts.filter((f) => FACT_LEVEL[f.kind] === "high").map((f) => f.kind)),
182
+ ];
183
+ const high = riskMap.level === "high" || highFacts.length > 0;
184
+ const b: string[] = [];
185
+ for (const claim of unverified) b.push(`Claim not verified: ${claim.text}`);
186
+ if (unexplained.length > 0) b.push(count(unexplained.length, "unexplained change", "unexplained changes"));
187
+ if (fixes.length > 0) b.push(count(fixes.length, "open Fix", "open Fixes"));
188
+ if (high) b.push(`The risk level is high${highFacts.length > 0 ? `: ${highFacts.join(", ")}` : ""}`);
189
+ if (b.length > 0) return result("B", b);
190
+
191
+ const mediumFacts = riskMap.facts.filter((f) => FACT_LEVEL[f.kind] === "medium");
192
+ const aMinus: string[] = [];
193
+ if (mediumFacts.length > 0) aMinus.push(count(mediumFacts.length, "medium-risk fact", "medium-risk facts"));
194
+ if (riskMap.droppedFacts > 0) {
195
+ aMinus.push(
196
+ count(
197
+ riskMap.droppedFacts,
198
+ "risk fact could not be placed in the change",
199
+ "risk facts could not be placed in the change",
200
+ ),
201
+ );
202
+ }
203
+ if (riskMap.judgement.length > 0) {
204
+ aMinus.push(
205
+ riskMap.judgement.length === 1 ? "One place needs a person" : `${riskMap.judgement.length} places need a person`,
206
+ );
207
+ }
208
+ if (considers.length > 0) aMinus.push(count(considers.length, "open Consider finding", "open Consider findings"));
209
+ if (aMinus.length > 0) return result("A-", aMinus);
210
+
211
+ return result("A", []);
212
+ }
213
+
214
+ /** The fidelity the engine records for a review: the grade and what it was computed from. */
215
+ export function buildFidelity(input: GradeInput): Fidelity {
216
+ return {
217
+ claims: input.claims,
218
+ ...computeGrade(input),
219
+ digest: input.run.digestAtRead,
220
+ reviewedCommit: input.run.reviewedCommit,
221
+ };
222
+ }
223
+
224
+ /** The attention list grouped by file. The order of files and of items within a file is kept. */
225
+ export function groupByFile(items: Attention[]): AttentionGroup[] {
226
+ const groups = new Map<string, Attention[]>();
227
+ for (const item of items) {
228
+ const group = groups.get(item.path);
229
+ if (group) group.push(item);
230
+ else groups.set(item.path, [item]);
231
+ }
232
+ return [...groups].map(([path, list]) => ({ path, items: list }));
233
+ }
234
+
235
+ /**
236
+ * The miss rate that `judged` pull requests with no serious miss bound at 95% confidence (decision
237
+ * 16 and spec section 6): 0 misses in 30 gives about 9.5%. Undefined before any is judged.
238
+ */
239
+ export function trialBound(judged: number): number | undefined {
240
+ if (!Number.isInteger(judged) || judged <= 0) return undefined;
241
+ return 1 - 0.05 ** (1 / judged);
242
+ }
@@ -0,0 +1,25 @@
1
+ /**
2
+ * Author or model text as one inert line of markdown: one line, no HTML tag, no link, no code span,
3
+ * no mention, no autolink, no issue or pull request reference (`#12`, `owner/repo#12`, `GH-12`: a
4
+ * reference in a description would cross-link, and with a closing keyword could close, that issue).
5
+ * An ampersand is escaped so an entity such as `&#35;12` cannot spell a reference or a mention. A bare
6
+ * commit SHA is left alone: GitHub links it but does not write to the commit. The backslash is
7
+ * escaped first, so a backslash in the text cannot cancel the escape placed before a bracket or
8
+ * a backtick (`\[x\](u)` would otherwise become `\\[x\\](u)`, a live link). Other markdown,
9
+ * emphasis for one, stays as written: it is one line, not a block.
10
+ */
11
+ export function inertText(text: string): string {
12
+ return text
13
+ .replace(/\s+/g, " ")
14
+ .trim()
15
+ .replaceAll("\\", "\\\\")
16
+ .replaceAll("&", "&amp;")
17
+ .replaceAll("<", "&lt;")
18
+ .replaceAll("[", "\\[")
19
+ .replaceAll("]", "\\]")
20
+ .replaceAll("`", "\\`")
21
+ .replaceAll("@", "@​")
22
+ .replaceAll("://", ":​//")
23
+ .replace(/(#|GH-)(?=\d)/gi, "$1\u200b")
24
+ .replace(/www\./gi, (m) => `${m.slice(0, 3)}​.`);
25
+ }
@@ -0,0 +1,166 @@
1
+ /**
2
+ * The fixed rules that explain a changed file without a claim (ADR 0033 decision 2): lockfiles,
3
+ * generated files, formatting-only changes and tests of a confirmed claim. The list is short on
4
+ * purpose and decided by the engine, never by the model: a file no rule here covers, and no claim
5
+ * explains, is reported as unexplained. Rules look at the path, and at the diff only for
6
+ * formatting. A file that says in its own text that it is generated is not trusted: an author
7
+ * could write that line into hand-written code. A path is trusted on purpose, even for generated
8
+ * names the engine still reviews: the list is short and a person sees a path in the file list.
9
+ */
10
+ import type { ChangedFile } from "./types";
11
+
12
+ export type RuleName = "lockfile" | "generated" | "formatting-only" | "test-of-confirmed-claim";
13
+
14
+ const LOCKFILES = new Set([
15
+ "bun.lock",
16
+ "bun.lockb",
17
+ "package-lock.json",
18
+ "npm-shrinkwrap.json",
19
+ "yarn.lock",
20
+ "pnpm-lock.yaml",
21
+ "Cargo.lock",
22
+ "go.sum",
23
+ "poetry.lock",
24
+ "Pipfile.lock",
25
+ "uv.lock",
26
+ "Gemfile.lock",
27
+ "composer.lock",
28
+ "Podfile.lock",
29
+ "flake.lock",
30
+ "mix.lock",
31
+ "gradle.lockfile",
32
+ "packages.lock.json",
33
+ ]);
34
+
35
+ // Generated is decided by path alone. `dist`, `build`, `out`, `*.map` and `worker-configuration.d.ts`
36
+ // are skipped by the engine by default; `generated/`, `__generated__/`, `*.pb.go`, `*_pb2.py` and
37
+ // `*.min.css` are reviewed but still trusted by their path, because a generator owns those names.
38
+ const GENERATED_DIRS = new Set(["generated", "__generated__", "dist", "build", "out"]);
39
+ const GENERATED_NAME = [
40
+ /\.generated\.[^./]+$/,
41
+ /\.pb\.go$/,
42
+ /_pb2(?:_grpc)?\.pyi?$/,
43
+ /\.min\.(?:js|css)$/,
44
+ /\.map$/,
45
+ /^worker-configuration\.d\.ts$/,
46
+ ];
47
+
48
+ const TEST_DIRS = new Set(["test", "tests", "__tests__", "__snapshots__", "spec", "specs"]);
49
+
50
+ /** Where a change of whitespace can change what the program does, so it is never formatting. */
51
+ const WHITESPACE_SENSITIVE_EXT = new Set(["py", "pyi", "yml", "yaml", "mk", "pug", "haml", "coffee", "nim", "md", "markdown", "mdx", "rst"]);
52
+ const MULTILINE_STRING_OPENER = ["`", '"""', "<<"];
53
+ const WHITESPACE_SENSITIVE_NAME = new Set(["Makefile", "makefile", "GNUmakefile"]);
54
+
55
+ const baseName = (path: string) => path.slice(path.lastIndexOf("/") + 1);
56
+ const dirSegments = (path: string) => path.split("/").slice(0, -1);
57
+ const extension = (name: string) => (name.includes(".") ? name.slice(name.lastIndexOf(".") + 1) : "");
58
+ const withoutExtension = (name: string) => (name.includes(".") ? name.slice(0, name.lastIndexOf(".")) : name);
59
+
60
+ export const isLockfile = (path: string): boolean => LOCKFILES.has(baseName(path)) || baseName(path).endsWith(".lock");
61
+
62
+ export const isGeneratedPath = (path: string): boolean =>
63
+ dirSegments(path).some((s) => GENERATED_DIRS.has(s)) || GENERATED_NAME.some((re) => re.test(baseName(path)));
64
+
65
+ export function isTestPath(path: string): boolean {
66
+ const name = baseName(path);
67
+ return (
68
+ dirSegments(path).some((s) => TEST_DIRS.has(s)) ||
69
+ /\.(?:test|spec)\.[^./]+$/.test(name) ||
70
+ /_test\.[^./]+$/.test(name) ||
71
+ /^test_[^/]+$/.test(name) ||
72
+ name.endsWith(".snap")
73
+ );
74
+ }
75
+
76
+ /**
77
+ * True when every hunk of the patch that changes anything removes and adds the same number of lines
78
+ * and each added line equals the removed line at its place once the whitespace at its two edges is
79
+ * trimmed. Whitespace inside a line is never touched, so a string literal, `a - -b` against `a --b`,
80
+ * a run of spaces made one, or a statement split or joined over lines is a change. A hunk with a
81
+ * backtick, a `"""` text block or a `<<` heredoc opener, on a changed line or on a context line
82
+ * around it, is never formatting: the value of such a multiline string depends on its indentation (a
83
+ * `<<` shift operator is caught too, which only makes the file unexplained). An opener further above
84
+ * than the hunk's context is not seen.
85
+ * Code that moved between hunks, a changed token, a patch with nothing changed and no patch at all
86
+ * are all false.
87
+ */
88
+ export function isFormattingOnly(patch: string | undefined): boolean {
89
+ if (!patch) return false;
90
+ let inHunk = false;
91
+ let removed: string[] = [];
92
+ let added: string[] = [];
93
+ let context: string[] = [];
94
+ let changedHunks = 0;
95
+ const close = (): boolean => {
96
+ const changed = removed.length + added.length > 0;
97
+ if (changed) changedHunks++;
98
+ const template = [...removed, ...added, ...context].some((line) => MULTILINE_STRING_OPENER.some((opener) => line.includes(opener)));
99
+ const same = removed.length === added.length && removed.every((line, i) => line.trim() === added[i]!.trim());
100
+ const ok = !changed || (same && !template);
101
+ removed = [];
102
+ added = [];
103
+ context = [];
104
+ return ok;
105
+ };
106
+ for (const line of patch.split("\n")) {
107
+ if (line.startsWith("@@")) {
108
+ if (inHunk && !close()) return false;
109
+ inHunk = true;
110
+ } else if (!inHunk) {
111
+ continue;
112
+ } else if (line.startsWith("-")) {
113
+ removed.push(line.slice(1));
114
+ } else if (line.startsWith("+")) {
115
+ added.push(line.slice(1));
116
+ } else if (line.startsWith(" ")) {
117
+ context.push(line.slice(1));
118
+ }
119
+ }
120
+ if (inHunk && !close()) return false;
121
+ return changedHunks > 0;
122
+ }
123
+
124
+ /**
125
+ * The part of a test's path that names what it tests, without the test directory, the test marker
126
+ * of the name and the extension: `test/fidelity/grade.test.ts` gives `fidelity/grade`.
127
+ */
128
+ function testSubject(path: string): string {
129
+ const name = baseName(path);
130
+ const stem = withoutExtension(name.endsWith(".snap") ? name.slice(0, -".snap".length) : name)
131
+ .replace(/\.(?:test|spec)$/, "")
132
+ .replace(/_test$/, "")
133
+ .replace(/^test_/, "");
134
+ return [...dirSegments(path).filter((s) => !TEST_DIRS.has(s)), stem].join("/");
135
+ }
136
+
137
+ /** True when a path in `confirmed` is the source of this test: the same path, or the same tail. */
138
+ function testsAConfirmedFile(testPath: string, confirmed: ReadonlySet<string>): boolean {
139
+ const subject = testSubject(testPath);
140
+ for (const source of confirmed) {
141
+ if (isTestPath(source)) continue;
142
+ const bare = withoutExtension(source);
143
+ if (bare === subject || bare.endsWith(`/${subject}`)) return true;
144
+ }
145
+ return false;
146
+ }
147
+
148
+ /**
149
+ * The rule that explains this file without a claim, or undefined: the file stays unexplained unless
150
+ * a claim covers it. `confirmedPaths` holds the paths a confirmed claim explains; it is what makes a
151
+ * test explained.
152
+ */
153
+ export function explainedByRule(
154
+ file: ChangedFile,
155
+ ctx: { confirmedPaths?: ReadonlySet<string> } = {},
156
+ ): RuleName | undefined {
157
+ if (isLockfile(file.path)) return "lockfile";
158
+ if (isGeneratedPath(file.path)) return "generated";
159
+ const name = baseName(file.path);
160
+ const sensitive = WHITESPACE_SENSITIVE_EXT.has(extension(name)) || WHITESPACE_SENSITIVE_NAME.has(name);
161
+ if (!sensitive && isFormattingOnly(file.patch)) return "formatting-only";
162
+ if (isTestPath(file.path) && ctx.confirmedPaths && testsAConfirmedFile(file.path, ctx.confirmedPaths)) {
163
+ return "test-of-confirmed-claim";
164
+ }
165
+ return undefined;
166
+ }
@@ -0,0 +1,135 @@
1
+ /**
2
+ * Writing PR Confidence into the pull request description (ADR 0033 decisions 11 and 14), and the
3
+ * reset that runs before any model call. Everything here is best-effort: the review is the record
4
+ * and is already posted, so a failed read or write of the description is a warning, never an error.
5
+ * Nothing is written in a dry run.
6
+ *
7
+ * The block goes into the description as it is now, read right before the write, so an edit made
8
+ * while the review ran is kept. The same read gives the commit and the text the grade is checked
9
+ * against: a grade whose claims were read from text that has changed is written as `cannot say`. A
10
+ * review whose commit is no longer the head writes nothing: the run for the newer commit owns the
11
+ * block.
12
+ */
13
+ import type { GhFn } from "../engine";
14
+ import { cannotSayBlock, renderBlock, upsertBlock } from "./block";
15
+ import { claimsDigest } from "./digest";
16
+ import { computeGrade } from "./grade";
17
+ import type { Fidelity } from "./types";
18
+
19
+ /** What the reset block says: no review of this commit has finished. */
20
+ export const RESET_REASON = "The review of this commit has not finished";
21
+
22
+ export interface SinkDeps {
23
+ gh: GhFn;
24
+ dryRun: boolean;
25
+ log: (line: string) => void;
26
+ warn: (line: string) => void;
27
+ /** The clock, in ms, for the date in the block. Default: `Date.now`. */
28
+ now?: () => number;
29
+ }
30
+
31
+ interface Live {
32
+ headRefOid: string;
33
+ title: string;
34
+ body: string;
35
+ }
36
+
37
+ function readLive(gh: GhFn, repo: string, pr: number): Live {
38
+ const live = JSON.parse(gh(["pr", "view", String(pr), "-R", repo, "--json", "headRefOid,title,body"])) as Partial<Live>;
39
+ if (typeof live.headRefOid !== "string" || live.headRefOid === "") throw new Error("the pull request has no head commit");
40
+ return { headRefOid: live.headRefOid, title: live.title ?? "", body: live.body ?? "" };
41
+ }
42
+
43
+ const dateOf = (deps: SinkDeps) => new Date((deps.now ?? Date.now)()).toISOString().slice(0, 10);
44
+
45
+ /**
46
+ * The grade as it stands at the moment of writing. A review whose commit is still the head and
47
+ * whose text is the one the claims were read from keeps its grade (the same object); any other is
48
+ * `cannot say` with the reason, no trial mark and no letter.
49
+ */
50
+ export function failClosed(f: Fidelity, now: { headCommit: string; title: string; body: string }): Fidelity {
51
+ const stale = computeGrade({
52
+ claims: [],
53
+ assignments: [],
54
+ changedFiles: [],
55
+ openFindings: [],
56
+ riskMap: { level: "low", facts: [], judgement: [], pathReasons: [], droppedFacts: 0 },
57
+ run: {
58
+ finished: true,
59
+ unreadFiles: 0,
60
+ reviewedCommit: f.reviewedCommit,
61
+ headCommit: now.headCommit,
62
+ digestAtRead: f.digest,
63
+ digestAtWrite: claimsDigest(now.title, now.body),
64
+ },
65
+ });
66
+ if (stale.grade !== "cannot say") return f;
67
+ return { ...f, grade: "cannot say", reasons: stale.reasons, trial: false };
68
+ }
69
+
70
+ /** Puts `block` into the live description. Returns false when nothing needed writing. */
71
+ function write(deps: SinkDeps, repo: string, pr: number, live: Live, block: string): boolean {
72
+ const next = upsertBlock(live.body, block);
73
+ if (deps.dryRun) {
74
+ deps.log(`--- PR Confidence block (dry run, not written) ---\n${block}`);
75
+ return false;
76
+ }
77
+ if (next === live.body) return false;
78
+ deps.gh(["api", "-X", "PATCH", `repos/${repo}/pulls/${pr}`, "--input", "-"], JSON.stringify({ body: next }));
79
+ return true;
80
+ }
81
+
82
+ export interface Publish {
83
+ /** The commit the review read. */
84
+ headSha: string;
85
+ /** The grade; absent for a review that cannot give one (an incremental or scoped review). */
86
+ fidelity?: Fidelity;
87
+ /** Why there is no grade, when `fidelity` is absent. */
88
+ partialReason?: string;
89
+ /** The posted review comment, when GitHub said where it is. */
90
+ reviewUrl?: string;
91
+ /** `https://github.com/owner/repo`. */
92
+ permalinkBase: string;
93
+ }
94
+
95
+ /** The block after a review: the grade, or `cannot say` when the text has moved on. A newer head writes nothing. */
96
+ export function publishConfidence(deps: SinkDeps, repo: string, pr: number, p: Publish): void {
97
+ try {
98
+ const live = readLive(deps.gh, repo, pr);
99
+ const date = dateOf(deps);
100
+ if (live.headRefOid !== p.headSha) {
101
+ // The review read an older commit. The run for the newer commit owns the block (it reset it,
102
+ // and may have finished): writing here could wipe its grade.
103
+ deps.log(`PR Confidence not written: the pull request has a newer commit (${live.headRefOid.slice(0, 7)}) than this review's ${p.headSha.slice(0, 7)}.`);
104
+ return;
105
+ }
106
+ let block: string;
107
+ if (!p.fidelity) {
108
+ block = cannotSayBlock(p.headSha, p.partialReason ?? RESET_REASON, { date, reviewUrl: p.reviewUrl });
109
+ } else {
110
+ const f = failClosed(p.fidelity, { headCommit: live.headRefOid, title: live.title, body: live.body });
111
+ block = renderBlock(f, { reviewUrl: p.reviewUrl, reviewedCommit: p.headSha, date, permalinkBase: p.permalinkBase });
112
+ }
113
+ write(deps, repo, pr, live, block);
114
+ } catch (error) {
115
+ deps.warn(`PR Confidence: the description could not be updated (${String(error).slice(0, 200)}). The review is posted.`);
116
+ }
117
+ }
118
+
119
+ /**
120
+ * The reset (decision 14): before any model call, the block becomes `cannot say` for the commit
121
+ * under review, so a run that is cancelled during the push wait, fails or hits the ceiling leaves no
122
+ * letter from an earlier commit. A run that finds a newer head is stale: the newer run resets it.
123
+ */
124
+ export function resetConfidence(deps: SinkDeps, repo: string, pr: number, commit?: string): void {
125
+ try {
126
+ const live = readLive(deps.gh, repo, pr);
127
+ if (commit !== undefined && commit !== live.headRefOid) {
128
+ deps.log(`PR Confidence reset skipped: the pull request has a newer commit (${live.headRefOid.slice(0, 7)}) than this run's ${commit.slice(0, 7)}.`);
129
+ return;
130
+ }
131
+ write(deps, repo, pr, live, cannotSayBlock(live.headRefOid, RESET_REASON, { date: dateOf(deps) }));
132
+ } catch (error) {
133
+ deps.warn(`PR Confidence: the description block could not be reset (${String(error).slice(0, 200)}).`);
134
+ }
135
+ }
@@ -0,0 +1,16 @@
1
+ /**
2
+ * The short PR Confidence result the review comment carries (ADR 0033 decision 14: the review body
3
+ * is the record, the description holds a mirror). One line. A reason can hold a claim's text, which
4
+ * comes from the author, so each reason goes through `inertText`: one line that cannot open a
5
+ * link, a code span, a tag, an autolink or a mention.
6
+ */
7
+ import { inertText } from "./inert";
8
+ import type { Fidelity } from "./types";
9
+
10
+ const A_MEANS = "Every claim has cited evidence and no change is unexplained";
11
+
12
+ export function fidelitySummary(f: Fidelity): string {
13
+ const label = f.trial ? `${f.grade} (trial)` : f.grade;
14
+ const why = f.grade === "A" ? [A_MEANS] : f.reasons.map(inertText);
15
+ return `**PR Confidence: ${label}.**${why.length > 0 ? ` ${why.join("; ")}.` : ""}`;
16
+ }
@@ -0,0 +1,93 @@
1
+ /**
2
+ * The shapes of PR Confidence (ADR 0033, spec section 3). Pure data: nothing here reads a file,
3
+ * a repository or a model. The model proposes claims; the engine checks them and computes the
4
+ * grade from the checked facts.
5
+ */
6
+ import type { Severity } from "../engine";
7
+
8
+ export const CLAIM_STATUSES = ["confirmed", "contradicted", "unverified", "vague"] as const;
9
+ export type ClaimStatus = (typeof CLAIM_STATUSES)[number];
10
+
11
+ /** A place in the new side of the change that a claim rests on. `endLine` makes a range. */
12
+ export interface Evidence {
13
+ path: string;
14
+ line: number;
15
+ endLine?: number;
16
+ }
17
+
18
+ /** One statement in the pull request title or body (decision 8). */
19
+ export interface Claim {
20
+ text: string;
21
+ status: ClaimStatus;
22
+ evidence: Evidence[];
23
+ }
24
+
25
+ /** Says which claim a changed file serves; `claim` is an index into the claims array (decision 9). */
26
+ export interface Assignment {
27
+ path: string;
28
+ claim: number;
29
+ }
30
+
31
+ /** A changed file as the engine sees it. `patch` is the unified diff of the file when it is known. */
32
+ export interface ChangedFile {
33
+ path: string;
34
+ patch?: string;
35
+ }
36
+
37
+ export const GRADES = ["cannot say", "C", "B", "A-", "A"] as const;
38
+ export type Grade = (typeof GRADES)[number];
39
+
40
+ /** A finding still open at the end of the review, as far as the grade needs it. */
41
+ export interface OpenFinding {
42
+ severity: Severity;
43
+ path: string;
44
+ /** 0 for a finding about the whole file. */
45
+ line: number;
46
+ title: string;
47
+ }
48
+
49
+ export type AttentionKind =
50
+ | "contradicted-claim"
51
+ | "unexplained"
52
+ | "finding"
53
+ | "risk-fact"
54
+ | "judgement";
55
+
56
+ /** One place that needs a person. `line` is absent when the whole file is meant. */
57
+ export interface Attention {
58
+ kind: AttentionKind;
59
+ path: string;
60
+ line?: number;
61
+ text: string;
62
+ /** Only for a finding: how serious it is, so the block can say which place to look at first. */
63
+ severity?: Severity;
64
+ }
65
+
66
+ /** The places that need attention in one file. */
67
+ export interface AttentionGroup {
68
+ path: string;
69
+ items: Attention[];
70
+ }
71
+
72
+ /** What the engine records about a pull request review (result field `fidelity`, `/2` only). */
73
+ export interface Fidelity {
74
+ claims: Claim[];
75
+ unexplainedFiles: string[];
76
+ grade: Grade;
77
+ /** Why the grade is not higher, most important first. Empty for an A. */
78
+ reasons: string[];
79
+ /** True for every A and A- until the owner has judged enough A-graded pull requests (decision 16). */
80
+ trial: boolean;
81
+ /** How many A-graded pull requests the owner has judged so far. */
82
+ judgedAGrades: number;
83
+ /**
84
+ * Every place that needs a person, ordered by file then line. The judgement items are capped at
85
+ * three upstream (buildRiskMap), so at most three of those are listed.
86
+ */
87
+ questions: Attention[];
88
+ /** Paths the risk map marks as sensitive. */
89
+ sensitivePaths: string[];
90
+ /** Digest of the author's text (title and body without Wachiman's block) the claims were read from. */
91
+ digest: string;
92
+ reviewedCommit: string;
93
+ }