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.
- package/README.md +132 -101
- package/bin/wachiman.js +1 -1
- package/package.json +2 -3
- package/skills/wachiman-loop/SKILL.md +91 -0
- package/skills/wachiman-review/SKILL.md +2 -2
- package/src/call-message.ts +26 -3
- package/src/cli.ts +113 -18
- package/src/config.ts +99 -32
- package/src/connectors/local-git.ts +102 -14
- package/src/cost.ts +48 -1
- package/src/doctor/checks.ts +1 -1
- package/src/engine.ts +910 -89
- package/src/estimate.ts +64 -0
- package/src/fidelity/block.ts +263 -0
- package/src/fidelity/claims-call.ts +172 -0
- package/src/fidelity/claims.ts +69 -0
- package/src/fidelity/digest.ts +80 -0
- package/src/fidelity/grade.ts +242 -0
- package/src/fidelity/inert.ts +25 -0
- package/src/fidelity/rules.ts +166 -0
- package/src/fidelity/sink.ts +135 -0
- package/src/fidelity/summary.ts +16 -0
- package/src/fidelity/types.ts +93 -0
- package/src/formats.ts +16 -3
- package/src/history/fingerprint.ts +1 -1
- package/src/history/store.ts +44 -6
- package/src/init/options.ts +1 -1
- package/src/ledger.ts +306 -0
- package/src/local.ts +23 -5
- package/src/loop/command.ts +441 -0
- package/src/loop/state.ts +88 -0
- package/src/loop/stop-rule.ts +98 -0
- package/src/providers/claude-code.ts +48 -13
- package/src/providers/codex.ts +8 -7
- package/src/providers/index.ts +6 -3
- package/src/providers/types.ts +13 -3
- package/src/sinks/common.ts +3 -3
- package/src/sinks/json.ts +13 -2
- package/src/skills/install.ts +4 -4
- package/src/status/command.ts +1 -1
- package/src/store/command.ts +109 -0
- package/src/store/figures.ts +153 -0
- package/src/store/html.ts +138 -0
- package/src/store/index.ts +298 -0
- package/templates/caller-workflow.yml +84 -57
- package/templates/wachiman-review-caller.yml +13 -0
|
@@ -0,0 +1,441 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* `wachiman loop`: one review round per call (ADR 0034). A round is a local review with history on,
|
|
3
|
+
* a comparison with the rounds before it, and an outcome the caller can branch on. The agent fixes
|
|
4
|
+
* between calls; this command never edits code.
|
|
5
|
+
*
|
|
6
|
+
* Exit codes: 0 converged, 10 findings still open, 11 stopped without converging (`round cap`,
|
|
7
|
+
* `review failed`), 2 usage error, 130 interrupted.
|
|
8
|
+
*
|
|
9
|
+
* The review is `runLocal` itself, asked for result `/2` with history on, so the account rules, the
|
|
10
|
+
* prompt and the history are exactly those of `wachiman local`. Round 1 reviews the whole range from
|
|
11
|
+
* `--base`; a later round reviews the commits since the previous round's head, as an ordinary range.
|
|
12
|
+
* A round with no new commit makes no model call: it re-reads the verdicts and reports again.
|
|
13
|
+
*/
|
|
14
|
+
import { UsageError } from "../config";
|
|
15
|
+
import { neutralise, SEVERITY, TOPIC, type ReviewResult } from "../engine";
|
|
16
|
+
import { spawnGit } from "../evidence";
|
|
17
|
+
import { readReviewResultFormat } from "../formats";
|
|
18
|
+
import { wachimanHome } from "../accounts/config";
|
|
19
|
+
import { MIN_LINE_CHARS, stripWhitespace, titleKey } from "../history/fingerprint";
|
|
20
|
+
import { replay, type ReplayedFinding } from "../history/match";
|
|
21
|
+
import { historyRoot, readRuns, readVerdicts, repositoryKey } from "../history/store";
|
|
22
|
+
import { LOCAL_FLAGS, parseFlags, runLocal, type LocalArgs, type LocalDeps } from "../local";
|
|
23
|
+
import { location, sha7 } from "../sinks/common";
|
|
24
|
+
import { LOOP_STATE_FORMAT, readLoop, writeLoop, type LedgerEntry, type LoopState } from "./state";
|
|
25
|
+
import { evaluate, isRefutedBy, roundCapReached, type Decision, type LoopFinding, type LoopStatus, type OpenFinding, type Released } from "./stop-rule";
|
|
26
|
+
|
|
27
|
+
export const LOOP_RESULT_FORMAT = "wachiman.loop-round/1";
|
|
28
|
+
export const DEFAULT_MAX_ROUNDS = 3;
|
|
29
|
+
|
|
30
|
+
export const loopUsage = `wachiman loop [--base <ref>] [--max-rounds <n>] [--max-depth <n>] [--repo-dir <dir>]
|
|
31
|
+
[--format terminal|json] [--profile <name>] [--verify | --no-verify]`;
|
|
32
|
+
|
|
33
|
+
export interface LoopArgs {
|
|
34
|
+
/** Starts a loop (round 1 reviews the whole range from here). Absent: continue the open loop. */
|
|
35
|
+
base?: string;
|
|
36
|
+
maxRounds: number;
|
|
37
|
+
format: "terminal" | "json";
|
|
38
|
+
profile?: string;
|
|
39
|
+
verify: boolean | undefined;
|
|
40
|
+
maxDepth?: number;
|
|
41
|
+
}
|
|
42
|
+
|
|
43
|
+
/** The flags `loop` takes, a subset of `local`'s plus `--max-rounds`. */
|
|
44
|
+
const LOOP_LOCAL_FLAGS = LOCAL_FLAGS.filter((f) => ["--base", "--format", "--profile", "--verify", "--no-verify", "--max-depth"].includes(f));
|
|
45
|
+
|
|
46
|
+
/** The arguments after `loop` (`--repo-dir` is already taken out). Both `--x v` and `--x=v`. */
|
|
47
|
+
export function parseLoopArgs(argv: string[]): LoopArgs {
|
|
48
|
+
let maxRounds = DEFAULT_MAX_ROUNDS;
|
|
49
|
+
let seenMax = false;
|
|
50
|
+
const rest: string[] = [];
|
|
51
|
+
for (let i = 0; i < argv.length; i++) {
|
|
52
|
+
const arg = argv[i];
|
|
53
|
+
if (arg === "--max-rounds" || arg.startsWith("--max-rounds=")) {
|
|
54
|
+
if (seenMax) throw new UsageError("--max-rounds was given twice.");
|
|
55
|
+
seenMax = true;
|
|
56
|
+
const v = arg === "--max-rounds" ? argv[++i] : arg.slice("--max-rounds=".length);
|
|
57
|
+
if (v === undefined || v === "" || v.startsWith("--")) throw new UsageError("--max-rounds needs a value.");
|
|
58
|
+
if (!/^[1-9]\d*$/.test(v) || !Number.isSafeInteger(Number(v))) throw new UsageError(`--max-rounds must be a positive integer, got "${v}".`);
|
|
59
|
+
maxRounds = Number(v);
|
|
60
|
+
} else rest.push(arg);
|
|
61
|
+
}
|
|
62
|
+
const local = parseFlags(rest, "loop", LOOP_LOCAL_FLAGS);
|
|
63
|
+
if (local.paths.length > 0) throw new UsageError(`loop takes no path or argument ("${local.paths[0]}"): it reviews the committed branch.`);
|
|
64
|
+
if (local.format === "markdown") throw new UsageError("--format must be terminal or json for loop.");
|
|
65
|
+
return {
|
|
66
|
+
...(local.base !== undefined ? { base: local.base } : {}),
|
|
67
|
+
maxRounds,
|
|
68
|
+
format: local.format as "terminal" | "json",
|
|
69
|
+
...(local.profile !== undefined ? { profile: local.profile } : {}),
|
|
70
|
+
verify: local.verify,
|
|
71
|
+
...(local.maxDepth !== undefined ? { maxDepth: local.maxDepth } : {}),
|
|
72
|
+
};
|
|
73
|
+
}
|
|
74
|
+
|
|
75
|
+
export interface LoopDeps extends LocalDeps {
|
|
76
|
+
/** The review of one round; `runLocal` unless a test says otherwise. */
|
|
77
|
+
review?: typeof runLocal;
|
|
78
|
+
}
|
|
79
|
+
|
|
80
|
+
type Why = "round cap" | "review failed";
|
|
81
|
+
|
|
82
|
+
/** What one call reports, in terminal and JSON form. */
|
|
83
|
+
export interface RoundReport {
|
|
84
|
+
branch: string;
|
|
85
|
+
round: number;
|
|
86
|
+
maxRounds: number;
|
|
87
|
+
/** What the round reviewed. */
|
|
88
|
+
range: { kind: "whole"; base: string } | { kind: "since-previous-round"; from: string } | { kind: "none"; head: string };
|
|
89
|
+
head: string;
|
|
90
|
+
open: OpenFinding[];
|
|
91
|
+
released: Released[];
|
|
92
|
+
notes: LoopFinding[];
|
|
93
|
+
outcome: { status: "converged" | "open" | "stopped"; reason?: Why; message: string };
|
|
94
|
+
exitCode: 0 | 10 | 11;
|
|
95
|
+
}
|
|
96
|
+
|
|
97
|
+
const GIT_TIMEOUT_MS = 30_000;
|
|
98
|
+
const git = (repoDir: string, args: string[]) => spawnGit(args, { cwd: repoDir, timeoutMs: GIT_TIMEOUT_MS });
|
|
99
|
+
|
|
100
|
+
function currentBranch(repoDir: string): string {
|
|
101
|
+
const out = git(repoDir, ["symbolic-ref", "--short", "-q", "HEAD"]);
|
|
102
|
+
if (out.status !== 0 || out.stdout.trim() === "") throw new UsageError("HEAD is detached; the loop is kept per branch, so check out a branch.");
|
|
103
|
+
return out.stdout.trim();
|
|
104
|
+
}
|
|
105
|
+
|
|
106
|
+
function headOf(repoDir: string): string {
|
|
107
|
+
const out = git(repoDir, ["rev-parse", "--verify", "HEAD^{commit}"]);
|
|
108
|
+
if (out.status !== 0) throw new UsageError("HEAD has no commit yet; commit the change first.");
|
|
109
|
+
return out.stdout.trim();
|
|
110
|
+
}
|
|
111
|
+
|
|
112
|
+
/** `old path -> new path` for the files the range renamed. */
|
|
113
|
+
function renamesIn(repoDir: string, from: string, head: string): Map<string, string> {
|
|
114
|
+
const out = git(repoDir, ["diff", "--name-status", "-M", from, head]);
|
|
115
|
+
const map = new Map<string, string>();
|
|
116
|
+
if (out.status !== 0) return map;
|
|
117
|
+
for (const line of out.stdout.split("\n")) {
|
|
118
|
+
const [kind, oldPath, newPath] = line.split("\t");
|
|
119
|
+
if (kind?.startsWith("R") && oldPath && newPath) map.set(oldPath, newPath);
|
|
120
|
+
}
|
|
121
|
+
return map;
|
|
122
|
+
}
|
|
123
|
+
|
|
124
|
+
/**
|
|
125
|
+
* Whether the finding's cited region changed in the file at HEAD, by the rule the history uses when
|
|
126
|
+
* it settles a finding: the cited line is gone from the file; or, with no line to search for, the
|
|
127
|
+
* file's blob differs.
|
|
128
|
+
*/
|
|
129
|
+
function regionChanged(repoDir: string, head: string, path: string, t: Pick<ReplayedFinding, "lineText" | "blobSha">): boolean {
|
|
130
|
+
if (t.lineText !== undefined) {
|
|
131
|
+
const shown = git(repoDir, ["show", `${head}:${path}`]);
|
|
132
|
+
return shown.status !== 0 || !shown.stdout.split("\n").some((l) => stripWhitespace(l) === t.lineText);
|
|
133
|
+
}
|
|
134
|
+
const blob = git(repoDir, ["rev-parse", `${head}:${path}`]);
|
|
135
|
+
return blob.status !== 0 || t.blobSha === undefined || blob.stdout.trim() !== t.blobSha;
|
|
136
|
+
}
|
|
137
|
+
|
|
138
|
+
/**
|
|
139
|
+
* What `regionChanged` compares against later: the cited line without whitespace, or the file's blob
|
|
140
|
+
* when the line is too short, repeated or missing, as the history fingerprints a finding.
|
|
141
|
+
*/
|
|
142
|
+
function fingerprintAt(repoDir: string, head: string, path: string, line: number): { lineText?: string; blobSha?: string } {
|
|
143
|
+
const shown = git(repoDir, ["show", `${head}:${path}`]);
|
|
144
|
+
if (shown.status === 0 && Number.isInteger(line) && line >= 1) {
|
|
145
|
+
const lines = shown.stdout.split("\n");
|
|
146
|
+
const text = line <= lines.length ? stripWhitespace(lines[line - 1]) : "";
|
|
147
|
+
if (text.length >= MIN_LINE_CHARS && lines.filter((l) => stripWhitespace(l) === text).length === 1) return { lineText: text };
|
|
148
|
+
}
|
|
149
|
+
const blob = git(repoDir, ["rev-parse", `${head}:${path}`]);
|
|
150
|
+
return blob.status === 0 ? { blobSha: blob.stdout.trim() } : {};
|
|
151
|
+
}
|
|
152
|
+
|
|
153
|
+
/** A complete `/2` result whose findings all carry their history id. */
|
|
154
|
+
type IdentifiedResult = ReviewResult & { findings: { id: string }[] };
|
|
155
|
+
type Attempt = { ok: true; result: IdentifiedResult } | { ok: false; why: string } | { interrupted: true };
|
|
156
|
+
|
|
157
|
+
/** One review call: succeeds only with a complete `/2` result in which every finding has a history id. */
|
|
158
|
+
function attempt(args: LocalArgs, repoDir: string, env: Record<string, string | undefined>, io: LoopIo, deps: LoopDeps): Attempt {
|
|
159
|
+
let out = "";
|
|
160
|
+
let code: number;
|
|
161
|
+
try {
|
|
162
|
+
code = (deps.review ?? runLocal)(args, repoDir, env, { stdout: (t) => (out += t), stderr: io.stderr, engineVersion: io.engineVersion }, deps);
|
|
163
|
+
} catch (error) {
|
|
164
|
+
if (error instanceof UsageError) throw error;
|
|
165
|
+
return { ok: false, why: error instanceof Error ? error.message : String(error) };
|
|
166
|
+
}
|
|
167
|
+
if (code === 130) return { interrupted: true };
|
|
168
|
+
if (code !== 0) return { ok: false, why: `the review exited ${code}` };
|
|
169
|
+
let parsed: ReviewResult;
|
|
170
|
+
try {
|
|
171
|
+
parsed = JSON.parse(out);
|
|
172
|
+
readReviewResultFormat(parsed);
|
|
173
|
+
} catch {
|
|
174
|
+
return { ok: false, why: "the review did not return a result" };
|
|
175
|
+
}
|
|
176
|
+
if (parsed.execution.stop !== "complete") return { ok: false, why: `the review stopped early (${parsed.execution.stop})` };
|
|
177
|
+
if (parsed.coverage.partial) return { ok: false, why: "the review left files unread" };
|
|
178
|
+
if (parsed.findings.some((f: { id?: string }) => typeof f.id !== "string")) return { ok: false, why: "the review's history entry was not saved, so its findings have no id" };
|
|
179
|
+
return { ok: true, result: parsed as IdentifiedResult };
|
|
180
|
+
}
|
|
181
|
+
|
|
182
|
+
interface LoopIo {
|
|
183
|
+
stdout: (text: string) => void;
|
|
184
|
+
stderr: (line: string) => void;
|
|
185
|
+
engineVersion: string;
|
|
186
|
+
}
|
|
187
|
+
|
|
188
|
+
const withVerdicts = (ledger: LedgerEntry[], verdicts: ReturnType<typeof readVerdicts>): LoopFinding[] =>
|
|
189
|
+
ledger.map((e) => ({ ...e, ...(verdicts.get(e.id) ? { verdict: { verdict: verdicts.get(e.id)!.verdict, reason: verdicts.get(e.id)!.reason } } : {}) }));
|
|
190
|
+
|
|
191
|
+
export function runLoop(args: LoopArgs, repoDir: string, env: Record<string, string | undefined>, io: LoopIo, deps: LoopDeps = {}): number {
|
|
192
|
+
const root = historyRoot(wachimanHome(env));
|
|
193
|
+
const key = repositoryKey(repoDir).key;
|
|
194
|
+
const branch = currentBranch(repoDir);
|
|
195
|
+
const head = headOf(repoDir);
|
|
196
|
+
// With --base the old state is about to be replaced, so one this version cannot read is no obstacle.
|
|
197
|
+
let existing: LoopState | undefined;
|
|
198
|
+
try {
|
|
199
|
+
existing = readLoop(root, key, branch);
|
|
200
|
+
} catch (error) {
|
|
201
|
+
if (args.base === undefined || !(error instanceof UsageError)) throw error;
|
|
202
|
+
}
|
|
203
|
+
|
|
204
|
+
let state: LoopState;
|
|
205
|
+
if (args.base !== undefined) {
|
|
206
|
+
if (existing?.status === "open" && existing.rounds.length > 0) io.stderr(`loop: starting over on ${branch}; the open loop had run ${existing.rounds.length} round(s).`);
|
|
207
|
+
state = { format: LOOP_STATE_FORMAT, branch, base: args.base, status: "open", rounds: [], ledger: [] };
|
|
208
|
+
} else if (!existing) {
|
|
209
|
+
throw new UsageError(`No loop is open on ${branch}; start one with \`wachiman loop --base <ref>\`.`);
|
|
210
|
+
} else if (existing.status === "converged") {
|
|
211
|
+
throw new UsageError(`The loop on ${branch} converged at round ${existing.rounds.length}; start a new one with \`wachiman loop --base <ref>\`.`);
|
|
212
|
+
} else state = existing;
|
|
213
|
+
|
|
214
|
+
const verdicts = () => readVerdicts(root, key);
|
|
215
|
+
const roundsRun = state.rounds.length;
|
|
216
|
+
const render = (report: RoundReport) => {
|
|
217
|
+
io.stdout(args.format === "json" ? renderJson(report) : renderTerminal(report));
|
|
218
|
+
return report.exitCode;
|
|
219
|
+
};
|
|
220
|
+
|
|
221
|
+
// Stop before another round when the cap is reached: no model call.
|
|
222
|
+
if (args.base === undefined && roundCapReached(roundsRun, args.maxRounds)) {
|
|
223
|
+
const decision = evaluate(withVerdicts(state.ledger, verdicts()));
|
|
224
|
+
return render(
|
|
225
|
+
report(state, roundsRun, args, head, { kind: "none", head }, decision, 11, {
|
|
226
|
+
status: "stopped",
|
|
227
|
+
reason: "round cap",
|
|
228
|
+
message: `Stopped without converging: round cap. ${roundsRun} round(s) ran (--max-rounds ${args.maxRounds}) and ${plural(decision.open.length, "finding")} still ${decision.open.length === 1 ? "keeps" : "keep"} the loop open. Raise --max-rounds to continue, or start a new loop with --base. A stop is never an approval.`,
|
|
229
|
+
}),
|
|
230
|
+
);
|
|
231
|
+
}
|
|
232
|
+
|
|
233
|
+
const previous = state.rounds.at(-1);
|
|
234
|
+
const round = roundsRun + 1;
|
|
235
|
+
const now = () => new Date().toISOString();
|
|
236
|
+
|
|
237
|
+
// No new commit since the last round: nothing to review. The verdicts may have changed.
|
|
238
|
+
if (previous && previous.head === head) {
|
|
239
|
+
const decision = evaluate(withVerdicts(state.ledger, verdicts()));
|
|
240
|
+
state = { ...state, rounds: [...state.rounds, { round, head, at: now() }], status: decision.converged ? "converged" : "open" };
|
|
241
|
+
writeLoop(root, key, state);
|
|
242
|
+
io.stderr(`loop: no commit since round ${previous.round} (${sha7(head)}); nothing was reviewed, the verdicts were read again.`);
|
|
243
|
+
return render(report(state, round, args, head, { kind: "none", head }, decision, decision.converged ? 0 : 10, finish(decision, round, args)));
|
|
244
|
+
}
|
|
245
|
+
|
|
246
|
+
const dirty = git(repoDir, ["status", "--porcelain", "--untracked-files=no"]);
|
|
247
|
+
if (dirty.status === 0 && dirty.stdout.trim() !== "") io.stderr("loop: uncommitted changes are not reviewed; commit the fix first.");
|
|
248
|
+
|
|
249
|
+
const from = previous ? previous.head : args.base ?? state.base;
|
|
250
|
+
const localArgs: LocalArgs = {
|
|
251
|
+
paths: [],
|
|
252
|
+
format: "json",
|
|
253
|
+
resultVersion: 2,
|
|
254
|
+
agentPrompt: false,
|
|
255
|
+
history: true,
|
|
256
|
+
verify: args.verify,
|
|
257
|
+
base: from,
|
|
258
|
+
...(args.profile !== undefined ? { profile: args.profile } : {}),
|
|
259
|
+
...(args.maxDepth !== undefined ? { maxDepth: args.maxDepth } : {}),
|
|
260
|
+
};
|
|
261
|
+
let made = attempt(localArgs, repoDir, env, io, deps);
|
|
262
|
+
if ("ok" in made && !made.ok) {
|
|
263
|
+
io.stderr(`loop: the review failed (${made.why}); trying once more.`);
|
|
264
|
+
made = attempt(localArgs, repoDir, env, io, deps);
|
|
265
|
+
}
|
|
266
|
+
if ("interrupted" in made) return 130;
|
|
267
|
+
if (!made.ok) {
|
|
268
|
+
// The round is not recorded; a fresh loop is, so the next call can retry it without --base.
|
|
269
|
+
if (args.base !== undefined) writeLoop(root, key, state);
|
|
270
|
+
const decision = evaluate(withVerdicts(state.ledger, verdicts()));
|
|
271
|
+
return render(
|
|
272
|
+
report(state, round, args, head, { kind: "none", head }, decision, 11, {
|
|
273
|
+
status: "stopped",
|
|
274
|
+
reason: "review failed",
|
|
275
|
+
message: `Stopped without converging: review failed. The review call failed twice (${made.why}). Round ${round} was not recorded; run \`wachiman loop\` again to retry it. A stop is never an approval.`,
|
|
276
|
+
}),
|
|
277
|
+
);
|
|
278
|
+
}
|
|
279
|
+
|
|
280
|
+
const { result } = made;
|
|
281
|
+
const decision = settle(state, result, repoDir, key, root, previous?.head ?? from, verdicts());
|
|
282
|
+
state = {
|
|
283
|
+
...state,
|
|
284
|
+
rounds: [...state.rounds, { round, head: result.change.head.sha, at: now() }],
|
|
285
|
+
ledger: decision.ledger,
|
|
286
|
+
status: decision.decision.converged ? "converged" : "open",
|
|
287
|
+
};
|
|
288
|
+
writeLoop(root, key, state);
|
|
289
|
+
const range: RoundReport["range"] = previous ? { kind: "since-previous-round", from: previous.head } : { kind: "whole", base: from };
|
|
290
|
+
return render(report(state, round, args, result.change.head.sha, range, decision.decision, decision.decision.converged ? 0 : 10, finish(decision.decision, round, args)));
|
|
291
|
+
}
|
|
292
|
+
|
|
293
|
+
/**
|
|
294
|
+
* The new ledger and the decision after a round. The loop decides from the round's own result and the
|
|
295
|
+
* code, never from the history's settled map (a review outside the loop writes to the same history).
|
|
296
|
+
* In a round that reads a finding's file: reported again means open; not reported with its cited
|
|
297
|
+
* line gone means probably fixed; not reported with the line still there means not repeated, which
|
|
298
|
+
* still counts. A round that does not read the file keeps the previous state.
|
|
299
|
+
*/
|
|
300
|
+
function settle(
|
|
301
|
+
state: LoopState,
|
|
302
|
+
result: IdentifiedResult,
|
|
303
|
+
repoDir: string,
|
|
304
|
+
key: string,
|
|
305
|
+
root: string,
|
|
306
|
+
rangeFrom: string,
|
|
307
|
+
verdicts: ReturnType<typeof readVerdicts>,
|
|
308
|
+
): { ledger: LedgerEntry[]; decision: Decision } {
|
|
309
|
+
const head = result.change.head.sha;
|
|
310
|
+
const renames = renamesIn(repoDir, rangeFrom, head);
|
|
311
|
+
const expected = new Set(result.coverage.expected);
|
|
312
|
+
const readThisRound = new Set(result.coverage.reviewed.filter((p) => expected.has(p)));
|
|
313
|
+
const dropped = (result.verification?.entries ?? []).filter((e) => e.outcome === "dropped" && e.status === "refuted");
|
|
314
|
+
const droppedKeys = dropped.map((d) => ({ path: d.path, topic: d.topic, titleKey: titleKey(d.title) }));
|
|
315
|
+
type Reported = { id: string; path: string; line: number; severity: LedgerEntry["severity"]; topic: LedgerEntry["topic"]; title: string };
|
|
316
|
+
const findings = result.findings as unknown as Reported[];
|
|
317
|
+
|
|
318
|
+
const prior = state.ledger.map((e) => ({ ...e, path: renames.get(e.path) ?? e.path }));
|
|
319
|
+
// A reported finding is the ledger entry with its id, or failing that the one in the same file with the same topic and title.
|
|
320
|
+
const reportedBy = new Map<string, Reported>();
|
|
321
|
+
const unmatched: Reported[] = [];
|
|
322
|
+
for (const f of findings) {
|
|
323
|
+
const e = prior.find((x) => x.id === f.id && !reportedBy.has(x.id));
|
|
324
|
+
if (e) reportedBy.set(e.id, f);
|
|
325
|
+
else unmatched.push(f);
|
|
326
|
+
}
|
|
327
|
+
const fresh: Reported[] = [];
|
|
328
|
+
for (const f of unmatched) {
|
|
329
|
+
const e = prior.find((x) => !reportedBy.has(x.id) && x.path === f.path && x.topic === f.topic && titleKey(x.title) === titleKey(f.title));
|
|
330
|
+
if (e) reportedBy.set(e.id, f);
|
|
331
|
+
else fresh.push(f);
|
|
332
|
+
}
|
|
333
|
+
|
|
334
|
+
// Fingerprints of entries written before the loop kept them come from the history, by id: data only, never a status.
|
|
335
|
+
let past: Map<string, ReplayedFinding> | undefined;
|
|
336
|
+
const fingerprintOf = (e: LedgerEntry) => {
|
|
337
|
+
if (e.lineText !== undefined || e.blobSha !== undefined) return e;
|
|
338
|
+
past ??= new Map(replay(readRuns(root, key, () => {}), verdicts).findings.map((f) => [f.firstId, f]));
|
|
339
|
+
return past.get(e.id);
|
|
340
|
+
};
|
|
341
|
+
const seen = (f: Reported): LedgerEntry => ({
|
|
342
|
+
id: f.id,
|
|
343
|
+
path: f.path,
|
|
344
|
+
line: f.line,
|
|
345
|
+
severity: f.severity,
|
|
346
|
+
topic: f.topic,
|
|
347
|
+
title: f.title,
|
|
348
|
+
status: "open",
|
|
349
|
+
refuted: false,
|
|
350
|
+
...fingerprintAt(repoDir, head, f.path, f.line),
|
|
351
|
+
});
|
|
352
|
+
|
|
353
|
+
const ledger: LedgerEntry[] = [
|
|
354
|
+
...prior.map((e): LedgerEntry => {
|
|
355
|
+
const again = reportedBy.get(e.id);
|
|
356
|
+
if (again) return { ...seen(again), id: e.id };
|
|
357
|
+
const refuted =
|
|
358
|
+
e.refuted ||
|
|
359
|
+
droppedKeys.some((d) => isRefutedBy(d, { path: e.path, topic: e.topic, titleKey: titleKey(e.title) }));
|
|
360
|
+
const fp = readThisRound.has(e.path) ? fingerprintOf(e) : undefined;
|
|
361
|
+
if (!fp || (fp.lineText === undefined && fp.blobSha === undefined)) return { ...e, refuted };
|
|
362
|
+
return { ...e, refuted, linesChanged: undefined, lineText: fp.lineText, blobSha: fp.blobSha, status: regionChanged(repoDir, head, e.path, fp) ? "probably-fixed" : "not-repeated" };
|
|
363
|
+
}),
|
|
364
|
+
...fresh.map(seen),
|
|
365
|
+
];
|
|
366
|
+
return { ledger, decision: evaluate(withVerdicts(ledger, verdicts)) };
|
|
367
|
+
}
|
|
368
|
+
|
|
369
|
+
function finish(d: Decision, round: number, args: LoopArgs): RoundReport["outcome"] {
|
|
370
|
+
if (d.converged) {
|
|
371
|
+
return {
|
|
372
|
+
status: "converged",
|
|
373
|
+
message:
|
|
374
|
+
round === 1
|
|
375
|
+
? "Converged: nothing keeps the loop open. Round 1 reviewed the whole range. This is not an approval."
|
|
376
|
+
: "Converged on incremental rounds: round 1 reviewed the whole range and later rounds only the commits after the previous round. Interactions between a fix and code outside those commits were not re-read. This is not an approval.",
|
|
377
|
+
};
|
|
378
|
+
}
|
|
379
|
+
const left = args.maxRounds - round;
|
|
380
|
+
return {
|
|
381
|
+
status: "open",
|
|
382
|
+
message: `${plural(d.open.length, "finding")} ${d.open.length === 1 ? "keeps" : "keep"} the loop open. Fix each one and commit, or judge it wrong with a reason (wachiman history --verdict <id> wrong --reason "<why>"), then run \`wachiman loop\` again. ${left > 0 ? `${plural(left, "round")} left of ${args.maxRounds}.` : `That was round ${round} of ${args.maxRounds}; the next call stops at the round cap.`}`,
|
|
383
|
+
};
|
|
384
|
+
}
|
|
385
|
+
|
|
386
|
+
const plural = (n: number, word: string) => `${n} ${word}${n === 1 ? "" : "s"}`;
|
|
387
|
+
|
|
388
|
+
function report(
|
|
389
|
+
state: LoopState,
|
|
390
|
+
round: number,
|
|
391
|
+
args: LoopArgs,
|
|
392
|
+
head: string,
|
|
393
|
+
range: RoundReport["range"],
|
|
394
|
+
d: Decision,
|
|
395
|
+
exitCode: 0 | 10 | 11,
|
|
396
|
+
outcome: RoundReport["outcome"],
|
|
397
|
+
): RoundReport {
|
|
398
|
+
return { branch: state.branch, round, maxRounds: args.maxRounds, range, head, open: d.open, released: d.released, notes: d.notes, outcome, exitCode };
|
|
399
|
+
}
|
|
400
|
+
|
|
401
|
+
const cleanFinding = (f: LoopFinding) => ({ id: f.id, path: f.path, line: f.line, severity: f.severity, topic: f.topic, title: f.title, status: f.status });
|
|
402
|
+
|
|
403
|
+
export function renderJson(r: RoundReport): string {
|
|
404
|
+
const doc = {
|
|
405
|
+
format: LOOP_RESULT_FORMAT,
|
|
406
|
+
branch: r.branch,
|
|
407
|
+
round: r.round,
|
|
408
|
+
maxRounds: r.maxRounds,
|
|
409
|
+
range: r.range,
|
|
410
|
+
head: r.head,
|
|
411
|
+
exitCode: r.exitCode,
|
|
412
|
+
outcome: r.outcome,
|
|
413
|
+
open: r.open.map((f) => ({ ...cleanFinding(f), ...(f.unreasonedWrong ? { unreasonedWrong: true } : {}) })),
|
|
414
|
+
released: r.released.map((x) => ({ ...cleanFinding(x.finding), why: x.why, ...(x.reason ? { reason: x.reason } : {}) })),
|
|
415
|
+
notes: r.notes.map(cleanFinding),
|
|
416
|
+
};
|
|
417
|
+
return `${JSON.stringify(doc, null, 2)}\n`;
|
|
418
|
+
}
|
|
419
|
+
|
|
420
|
+
const row = (f: LoopFinding) => `${SEVERITY[f.severity].emoji} ${SEVERITY[f.severity].word} · ${TOPIC[f.topic].word} ${location(f)} ${neutralise(f.title).replace(/\s+/g, " ")} (id ${f.id})`;
|
|
421
|
+
|
|
422
|
+
export function renderTerminal(r: RoundReport): string {
|
|
423
|
+
const range =
|
|
424
|
+
r.range.kind === "whole"
|
|
425
|
+
? `the whole range from ${neutralise(r.range.base)}`
|
|
426
|
+
: r.range.kind === "since-previous-round"
|
|
427
|
+
? `the commits since round ${r.round - 1} (${sha7(r.range.from)})`
|
|
428
|
+
: "no review this call";
|
|
429
|
+
const lines = [`wachiman loop · ${neutralise(r.branch)} · round ${r.round} of ${r.maxRounds} · ${range} → ${sha7(r.head)}`, ""];
|
|
430
|
+
lines.push(`Keeps the loop open (${r.open.length}):`);
|
|
431
|
+
for (const f of r.open) lines.push(` ${row(f)}`, ` history: ${f.status}${f.unreasonedWrong ? " · judged wrong without a reason: still counts" : ""}`);
|
|
432
|
+
if (r.open.length === 0) lines.push(" none");
|
|
433
|
+
lines.push("", `No longer open (${r.released.length}):`);
|
|
434
|
+
for (const x of r.released) lines.push(` ${x.why} ${row(x.finding)}${x.reason ? `\n reason: ${neutralise(x.reason)}` : ""}`);
|
|
435
|
+
if (r.released.length === 0) lines.push(" none");
|
|
436
|
+
lines.push("", `Notes, never counted (${r.notes.length}):`);
|
|
437
|
+
for (const f of r.notes) lines.push(` ${row(f)}`);
|
|
438
|
+
if (r.notes.length === 0) lines.push(" none");
|
|
439
|
+
lines.push("", `Outcome (exit ${r.exitCode}): ${r.outcome.message}`);
|
|
440
|
+
return `${lines.join("\n")}\n`;
|
|
441
|
+
}
|
|
@@ -0,0 +1,88 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* What `wachiman loop` keeps per branch beside the history (ADR 0034): the base the loop started
|
|
3
|
+
* from, the head of every round and the findings it has seen. It is read at the start of a call
|
|
4
|
+
* and rewritten at its end; the review itself is saved by the history, not here.
|
|
5
|
+
*/
|
|
6
|
+
import { UsageError } from "../config";
|
|
7
|
+
import { SEVERITY, TOPIC } from "../engine";
|
|
8
|
+
import { readLoopFile, writeLoopFile } from "../history/store";
|
|
9
|
+
import type { LoopStatus } from "./stop-rule";
|
|
10
|
+
|
|
11
|
+
export const LOOP_STATE_FORMAT = "wachiman.loop-state/1";
|
|
12
|
+
|
|
13
|
+
/** A finding the loop has seen, as of the last round. The verdict is read fresh from the history every time. */
|
|
14
|
+
export interface LedgerEntry {
|
|
15
|
+
id: string;
|
|
16
|
+
path: string;
|
|
17
|
+
line: number;
|
|
18
|
+
severity: keyof typeof SEVERITY;
|
|
19
|
+
topic: keyof typeof TOPIC;
|
|
20
|
+
title: string;
|
|
21
|
+
status: LoopStatus;
|
|
22
|
+
/** The verifier dropped it with a checked disproof; stays true until a round reports it again. */
|
|
23
|
+
refuted: boolean;
|
|
24
|
+
/** Only in states written by the first version of the loop: a `not-repeated` entry whose lines changed counted as released. */
|
|
25
|
+
linesChanged?: boolean;
|
|
26
|
+
/** The cited line without whitespace, or the file's blob when there is no such line: what a later round compares. */
|
|
27
|
+
lineText?: string;
|
|
28
|
+
blobSha?: string;
|
|
29
|
+
}
|
|
30
|
+
|
|
31
|
+
export interface LoopRound {
|
|
32
|
+
round: number;
|
|
33
|
+
/** The full sha of HEAD when the round ran. */
|
|
34
|
+
head: string;
|
|
35
|
+
at: string;
|
|
36
|
+
}
|
|
37
|
+
|
|
38
|
+
export interface LoopState {
|
|
39
|
+
format: typeof LOOP_STATE_FORMAT;
|
|
40
|
+
branch: string;
|
|
41
|
+
/** The ref the loop started from, as typed after `--base`. */
|
|
42
|
+
base: string;
|
|
43
|
+
/** `open` until a round converges. */
|
|
44
|
+
status: "open" | "converged";
|
|
45
|
+
rounds: LoopRound[];
|
|
46
|
+
ledger: LedgerEntry[];
|
|
47
|
+
}
|
|
48
|
+
|
|
49
|
+
const STATUSES: readonly string[] = ["new", "open", "probably-fixed", "not-repeated", "unknown"];
|
|
50
|
+
|
|
51
|
+
function valid(s: any, branch: string): s is LoopState {
|
|
52
|
+
return (
|
|
53
|
+
s &&
|
|
54
|
+
typeof s === "object" &&
|
|
55
|
+
s.format === LOOP_STATE_FORMAT &&
|
|
56
|
+
s.branch === branch &&
|
|
57
|
+
typeof s.base === "string" &&
|
|
58
|
+
(s.status === "open" || s.status === "converged") &&
|
|
59
|
+
Array.isArray(s.rounds) &&
|
|
60
|
+
s.rounds.every((r: any) => r && Number.isInteger(r.round) && typeof r.head === "string" && typeof r.at === "string") &&
|
|
61
|
+
Array.isArray(s.ledger) &&
|
|
62
|
+
s.ledger.every(
|
|
63
|
+
(e: any) =>
|
|
64
|
+
e &&
|
|
65
|
+
typeof e.id === "string" &&
|
|
66
|
+
typeof e.path === "string" &&
|
|
67
|
+
typeof e.line === "number" &&
|
|
68
|
+
e.severity in SEVERITY &&
|
|
69
|
+
e.topic in TOPIC &&
|
|
70
|
+
typeof e.title === "string" &&
|
|
71
|
+
STATUSES.includes(e.status) &&
|
|
72
|
+
typeof e.refuted === "boolean" &&
|
|
73
|
+
(e.linesChanged === undefined || typeof e.linesChanged === "boolean") &&
|
|
74
|
+
(e.lineText === undefined || typeof e.lineText === "string") &&
|
|
75
|
+
(e.blobSha === undefined || typeof e.blobSha === "string"),
|
|
76
|
+
)
|
|
77
|
+
);
|
|
78
|
+
}
|
|
79
|
+
|
|
80
|
+
/** The branch's loop, or undefined when none was started. A file that does not read as a loop state is a usage error naming what to do. */
|
|
81
|
+
export function readLoop(root: string, key: string, branch: string): LoopState | undefined {
|
|
82
|
+
const raw = readLoopFile(root, key, branch);
|
|
83
|
+
if (raw === undefined) return undefined;
|
|
84
|
+
if (!valid(raw, branch)) throw new UsageError(`The loop state of ${branch} is not readable by this version; start a new loop with \`wachiman loop --base <ref>\`.`);
|
|
85
|
+
return raw;
|
|
86
|
+
}
|
|
87
|
+
|
|
88
|
+
export const writeLoop = (root: string, key: string, state: LoopState) => writeLoopFile(root, key, state.branch, state);
|
|
@@ -0,0 +1,98 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The stop rule of `wachiman loop` (ADR 0034 decision 5), pure: no filesystem, no git, no model.
|
|
3
|
+
* The command gathers one `LoopFinding` per finding the loop has seen and this module says which
|
|
4
|
+
* of them keep the loop open.
|
|
5
|
+
*
|
|
6
|
+
* The loop stays open while a 🔴 Blocker or 🟠 Fix is new, open or not-repeated, not refuted by the
|
|
7
|
+
* verifier and not judged `wrong` with a reason. 🟡 Consider and ⚪ Info are listed as notes and
|
|
8
|
+
* never count.
|
|
9
|
+
*
|
|
10
|
+
* The command sets the status from the round's own result and the code, not from the history: a
|
|
11
|
+
* finding the round reported again is `open`; in a file the round read, one it did not report is
|
|
12
|
+
* `probably-fixed` when its cited line is gone and `not-repeated` (still counts) when the line is
|
|
13
|
+
* still there; a file the round did not read keeps the previous status, so an `unknown` Blocker or
|
|
14
|
+
* Fix from a state written by the first version stays open until its file is read. When the cited
|
|
15
|
+
* line is short, repeated or line 0, the file's blob is fingerprinted instead and any edit to the
|
|
16
|
+
* file releases the finding. `linesChanged` exists only in states written by the first version.
|
|
17
|
+
*/
|
|
18
|
+
import type { Severity, Topic } from "../engine";
|
|
19
|
+
import type { VerdictWord } from "../history/types";
|
|
20
|
+
|
|
21
|
+
export type LoopStatus = "new" | "open" | "probably-fixed" | "not-repeated" | "unknown";
|
|
22
|
+
|
|
23
|
+
export interface LoopFinding {
|
|
24
|
+
/** The history id, the finding's first id. */
|
|
25
|
+
id: string;
|
|
26
|
+
path: string;
|
|
27
|
+
line: number;
|
|
28
|
+
severity: Severity;
|
|
29
|
+
topic: Topic;
|
|
30
|
+
title: string;
|
|
31
|
+
/** The status after this round, decided by the loop. */
|
|
32
|
+
status: LoopStatus;
|
|
33
|
+
/** The verifier dropped this finding with a checked disproof in this round. */
|
|
34
|
+
refuted: boolean;
|
|
35
|
+
/** Only from a state written by the first version of the loop: a `not-repeated` finding whose lines changed counts as released. */
|
|
36
|
+
linesChanged?: boolean;
|
|
37
|
+
verdict?: { verdict: VerdictWord; reason?: string };
|
|
38
|
+
}
|
|
39
|
+
|
|
40
|
+
export type ReleaseWhy = "probably-fixed" | "refuted" | "judged wrong";
|
|
41
|
+
|
|
42
|
+
export interface OpenFinding extends LoopFinding {
|
|
43
|
+
/** Judged `wrong` with no reason: it is listed and still counts. */
|
|
44
|
+
unreasonedWrong?: true;
|
|
45
|
+
}
|
|
46
|
+
|
|
47
|
+
export interface Released {
|
|
48
|
+
finding: LoopFinding;
|
|
49
|
+
why: ReleaseWhy;
|
|
50
|
+
/** The reason the developer or agent gave, for `judged wrong`. */
|
|
51
|
+
reason?: string;
|
|
52
|
+
}
|
|
53
|
+
|
|
54
|
+
export interface Decision {
|
|
55
|
+
open: OpenFinding[];
|
|
56
|
+
released: Released[];
|
|
57
|
+
/** 🟡 and ⚪ that are not released: listed, never counted. */
|
|
58
|
+
notes: LoopFinding[];
|
|
59
|
+
converged: boolean;
|
|
60
|
+
}
|
|
61
|
+
|
|
62
|
+
const COUNTS: readonly Severity[] = ["blocker", "fix"];
|
|
63
|
+
|
|
64
|
+
export function evaluate(findings: LoopFinding[]): Decision {
|
|
65
|
+
const open: OpenFinding[] = [];
|
|
66
|
+
const released: Released[] = [];
|
|
67
|
+
const notes: LoopFinding[] = [];
|
|
68
|
+
for (const f of findings) {
|
|
69
|
+
const reason = f.verdict?.verdict === "wrong" ? f.verdict.reason?.trim() : undefined;
|
|
70
|
+
if (!COUNTS.includes(f.severity)) {
|
|
71
|
+
// A note a verdict, the verifier or a fix already settled is not worth listing again.
|
|
72
|
+
if (f.status === "probably-fixed" || f.refuted || reason) continue;
|
|
73
|
+
notes.push(f);
|
|
74
|
+
} else if (reason) released.push({ finding: f, why: "judged wrong", reason });
|
|
75
|
+
else if (f.refuted) released.push({ finding: f, why: "refuted" });
|
|
76
|
+
else if (f.status === "probably-fixed" || (f.status === "not-repeated" && f.linesChanged)) released.push({ finding: f, why: "probably-fixed" });
|
|
77
|
+
else open.push(f.verdict?.verdict === "wrong" ? { ...f, unreasonedWrong: true } : f);
|
|
78
|
+
}
|
|
79
|
+
return { open, released, notes, converged: open.length === 0 };
|
|
80
|
+
}
|
|
81
|
+
|
|
82
|
+
/** A loop that already ran `max` rounds stops before another one: three by default. */
|
|
83
|
+
export const roundCapReached = (roundsRun: number, max: number) => roundsRun >= max;
|
|
84
|
+
|
|
85
|
+
/**
|
|
86
|
+
* Whether a candidate the verifier dropped with a checked disproof is a finding the loop already
|
|
87
|
+
* tracks. A dropped candidate has no history id (it was never reported), so it is matched the way
|
|
88
|
+
* the history matches a title: the same file, the same topic and the same title key. Nothing weaker
|
|
89
|
+
* is used, because here a match closes a finding: a line number or a cited line is shared by
|
|
90
|
+
* different claims, and a disproof of one must not release another. A finding the verifier
|
|
91
|
+
* re-titled stays open, and the agent can judge it `wrong` with a reason.
|
|
92
|
+
*/
|
|
93
|
+
export function isRefutedBy(
|
|
94
|
+
dropped: { path: string; topic: Topic; titleKey: string },
|
|
95
|
+
tracked: { path: string; topic: Topic; titleKey: string },
|
|
96
|
+
): boolean {
|
|
97
|
+
return dropped.path === tracked.path && dropped.topic === tracked.topic && dropped.titleKey === tracked.titleKey;
|
|
98
|
+
}
|