@jitsusama/agentic-harness.core 0.1.0

package/dist/review/decided.d.ts

@@ -0,0 +1,58 @@
+/**
+ * What has already been settled about a change's findings.
+ *
+ * Deciding a finding has an effect somewhere else: promoting puts it in
+ * a draft, dismissing drops it, queueing makes it work. None of those
+ * leave a mark on the finding, so a listing of what was raised reads
+ * identically before and after a session of deciding, and the second
+ * reader cannot tell a finding nobody has looked at from one already
+ * dealt with.
+ *
+ * That was noticed once and solved once, for fixes only. This is the
+ * same fact for the other two verdicts, so it is recorded the same way:
+ * one small ledger per change, beside the findings themselves.
+ *
+ * It is deliberately not the fix queue. A queued fix carries how to do
+ * it, the commit that did it and the reason it was abandoned; a verdict
+ * carries none of that. Merging them would put four optional fields on
+ * a record that mostly wants two.
+ */
+import type { ChangeRef } from "./change.js";
+/**
+ * What was decided.
+ *
+ * `fix` is here for completeness of the record even though the fix
+ * queue owns the work, so one read answers "has this been dealt with"
+ * for every verdict rather than for two of three.
+ *
+ * Named for the tool's `settle` parameter, and deliberately not
+ * `Verdict`, which this library already uses for what you say about a
+ * whole change: approve, request changes, comment. Those are different
+ * kinds of judgement and sharing a name would invite passing one where
+ * the other belongs.
+ */
+export type Settlement = "promote" | "dismiss" | "fix";
+/** One settled finding. */
+export interface Decision {
+    findingId: number;
+    verdict: Settlement;
+    /** What the decider said, when they said anything. */
+    note?: string;
+    decidedAt: string;
+}
+/** The ledger of what has been settled on one change. */
+export interface DecisionLedger {
+    /**
+     * Settle a finding, or re-settle one.
+     *
+     * Changing your mind is ordinary, so unlike a fix outcome this
+     * overwrites rather than refusing. What would be wrong is silence:
+     * a re-decision that kept the old verdict would make the listing
+     * lie.
+     */
+    record(change: ChangeRef, findingId: number, verdict: Settlement, note?: string): Promise<Decision>;
+    /** Every decision on this change, oldest first. */
+    list(change: ChangeRef): Promise<Decision[]>;
+}
+/** A ledger of decisions, stored under `root`. */
+export declare function createDecisionLedger(root: string): DecisionLedger;

package/dist/review/decided.js

@@ -0,0 +1,67 @@
+/**
+ * What has already been settled about a change's findings.
+ *
+ * Deciding a finding has an effect somewhere else: promoting puts it in
+ * a draft, dismissing drops it, queueing makes it work. None of those
+ * leave a mark on the finding, so a listing of what was raised reads
+ * identically before and after a session of deciding, and the second
+ * reader cannot tell a finding nobody has looked at from one already
+ * dealt with.
+ *
+ * That was noticed once and solved once, for fixes only. This is the
+ * same fact for the other two verdicts, so it is recorded the same way:
+ * one small ledger per change, beside the findings themselves.
+ *
+ * It is deliberately not the fix queue. A queued fix carries how to do
+ * it, the commit that did it and the reason it was abandoned; a verdict
+ * carries none of that. Merging them would put four optional fields on
+ * a record that mostly wants two.
+ */
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { changeKey } from "./keys.js";
+/** Where one change's decisions live. */
+function fileFor(root, change) {
+    return join(root, `${changeKey(change)}.json`);
+}
+/** Read the ledger, treating anything unreadable as empty. */
+async function read(path) {
+    try {
+        const parsed = JSON.parse(await readFile(path, "utf8"));
+        return Array.isArray(parsed) ? parsed : [];
+    }
+    catch {
+        // Absent, truncated or not JSON: nothing has been decided that we
+        // can prove, and refusing to read would block the whole listing
+        // over a record that is only an aid to the reader.
+        return [];
+    }
+}
+/** A ledger of decisions, stored under `root`. */
+export function createDecisionLedger(root) {
+    return {
+        async record(change, findingId, verdict, note) {
+            const path = fileFor(root, change);
+            const held = await read(path);
+            const decision = {
+                findingId,
+                verdict,
+                ...(note === undefined ? {} : { note }),
+                decidedAt: new Date().toISOString(),
+            };
+            // Replace in place so a re-decision keeps its position, which
+            // keeps the listing order stable across a change of mind.
+            const at = held.findIndex((one) => one.findingId === findingId);
+            if (at === -1)
+                held.push(decision);
+            else
+                held[at] = decision;
+            await mkdir(dirname(path), { recursive: true });
+            await writeFile(path, `${JSON.stringify(held, null, 2)}\n`, "utf8");
+            return decision;
+        },
+        async list(change) {
+            return await read(fileFor(root, change));
+        },
+    };
+}

package/dist/review/diff.d.ts

@@ -0,0 +1,116 @@
+/**
+ * The diff model, in git's own dialect.
+ *
+ * Every backend surveyed can produce a unified diff, and
+ * unified diff is the only representation all of them share,
+ * so it is the substrate's diff currency. A file has an old
+ * side and a new side, which is what git calls them; the
+ * forge convention of "left" and "right" stays inside the
+ * providers that invented it.
+ */
+/** How a file changed between the two sides. */
+export type DiffStatus = "added" | "deleted" | "modified" | "renamed";
+/**
+ * Which side of the diff something sits on. Git's own words:
+ * the forge convention of "left" and "right" stays inside the
+ * providers that invented it.
+ */
+export type DiffSide = "old" | "new";
+/** One line of a hunk, numbered on whichever sides hold it. */
+export interface DiffLine {
+    kind: "context" | "added" | "removed";
+    /** Line number on the old side, when it exists there. */
+    oldLine?: number;
+    /** Line number on the new side, when it exists there. */
+    newLine?: number;
+    /** Line content, without the leading marker. */
+    text: string;
+}
+/** A contiguous run of changed lines. */
+export interface DiffHunk {
+    oldStart: number;
+    oldCount: number;
+    newStart: number;
+    newCount: number;
+    /** Heading git guessed for the enclosing section. */
+    section?: string;
+    lines: DiffLine[];
+}
+/** One file's worth of diff. */
+export interface DiffFile {
+    /** Path on the old side; absent when the file was added. */
+    oldPath?: string;
+    /** Path on the new side; absent when the file was deleted. */
+    newPath?: string;
+    status: DiffStatus;
+    /** Blob id of the old side, when the diff reports it. */
+    oldBlob?: string;
+    /** Blob id of the new side, when the diff reports it. */
+    newBlob?: string;
+    /** Rename similarity percentage, for renames. */
+    similarity?: number;
+    /** True when git declined to show content. */
+    binary?: boolean;
+    hunks: DiffHunk[];
+}
+/** A parsed unified diff. */
+export interface DiffModel {
+    files: DiffFile[];
+}
+/**
+ * The `@@` line for this hunk, as git would write it.
+ *
+ * Reconstructed from the parts rather than kept as text,
+ * because a provider that built a hunk itself never had the
+ * line, and storing both invites them to disagree. Git omits
+ * the count when a range covers exactly one line, so this does
+ * too: the header is fed back to tools that expect git's own
+ * spelling.
+ */
+export declare function hunkHeader(hunk: DiffHunk): string;
+/**
+ * The one path this file is known by, for matching and lookup.
+ *
+ * The new side wins, falling back to the old for a file that
+ * was deleted. Distinct from `displayPath` on purpose: a label
+ * can say a file moved, but anything comparing paths needs a
+ * single real one, and a rename shown as a journey would match
+ * nothing.
+ */
+export declare function filePath(file: DiffFile): string;
+/**
+ * The path to put in front of a person.
+ *
+ * The new side by default, since that is where the code now
+ * lives, but a rename says both halves: a reader who knows the
+ * old name needs to find it, and one who knows neither needs
+ * to see that the move happened at all.
+ */
+export declare function displayPath(file: DiffFile): string;
+/**
+ * How many lines this file added and removed.
+ *
+ * Counted from the hunks rather than carried as a field,
+ * because a diff that arrived as text has no other source and
+ * a second source would be a second thing to get wrong. A
+ * binary file has no hunks and so counts as neither.
+ */
+export declare function changeCounts(file: DiffFile): {
+    additions: number;
+    deletions: number;
+};
+/**
+ * This line's number on one side, when it exists there.
+ *
+ * An added line has no old number and a removed line has no
+ * new one, so the answer is honestly absent rather than zero.
+ */
+export declare function lineNumberOn(line: DiffLine, side: DiffSide): number | undefined;
+/**
+ * Parse git's unified diff output into a `DiffModel`.
+ *
+ * Tolerant by design: a diff arrives from whichever backend
+ * produced it, so an unrecognized header line is skipped
+ * rather than treated as an error.
+ */
+export declare function parseUnifiedDiff(text: string): DiffModel;

package/dist/review/diff.js

@@ -0,0 +1,237 @@
+/**
+ * The diff model, in git's own dialect.
+ *
+ * Every backend surveyed can produce a unified diff, and
+ * unified diff is the only representation all of them share,
+ * so it is the substrate's diff currency. A file has an old
+ * side and a new side, which is what git calls them; the
+ * forge convention of "left" and "right" stays inside the
+ * providers that invented it.
+ */
+/**
+ * The `@@` line for this hunk, as git would write it.
+ *
+ * Reconstructed from the parts rather than kept as text,
+ * because a provider that built a hunk itself never had the
+ * line, and storing both invites them to disagree. Git omits
+ * the count when a range covers exactly one line, so this does
+ * too: the header is fed back to tools that expect git's own
+ * spelling.
+ */
+export function hunkHeader(hunk) {
+    const side = (start, count) => count === 1 ? `${start}` : `${start},${count}`;
+    const range = `@@ -${side(hunk.oldStart, hunk.oldCount)} +${side(hunk.newStart, hunk.newCount)} @@`;
+    return hunk.section ? `${range} ${hunk.section}` : range;
+}
+/**
+ * The one path this file is known by, for matching and lookup.
+ *
+ * The new side wins, falling back to the old for a file that
+ * was deleted. Distinct from `displayPath` on purpose: a label
+ * can say a file moved, but anything comparing paths needs a
+ * single real one, and a rename shown as a journey would match
+ * nothing.
+ */
+export function filePath(file) {
+    return file.newPath ?? file.oldPath ?? "";
+}
+/**
+ * The path to put in front of a person.
+ *
+ * The new side by default, since that is where the code now
+ * lives, but a rename says both halves: a reader who knows the
+ * old name needs to find it, and one who knows neither needs
+ * to see that the move happened at all.
+ */
+export function displayPath(file) {
+    if (file.status === "renamed" && file.oldPath && file.newPath) {
+        return `${file.oldPath} -> ${file.newPath}`;
+    }
+    return filePath(file);
+}
+/**
+ * How many lines this file added and removed.
+ *
+ * Counted from the hunks rather than carried as a field,
+ * because a diff that arrived as text has no other source and
+ * a second source would be a second thing to get wrong. A
+ * binary file has no hunks and so counts as neither.
+ */
+export function changeCounts(file) {
+    let additions = 0;
+    let deletions = 0;
+    for (const hunk of file.hunks) {
+        for (const line of hunk.lines) {
+            if (line.kind === "added")
+                additions += 1;
+            else if (line.kind === "removed")
+                deletions += 1;
+        }
+    }
+    return { additions, deletions };
+}
+/**
+ * This line's number on one side, when it exists there.
+ *
+ * An added line has no old number and a removed line has no
+ * new one, so the answer is honestly absent rather than zero.
+ */
+export function lineNumberOn(line, side) {
+    return side === "old" ? line.oldLine : line.newLine;
+}
+const FILE_HEADER = /^diff --git /;
+const FILE_HEADER_PATHS = /^diff --git a\/(.+) b\/(.+)$/;
+const INDEX_LINE = /^index ([0-9a-f]+)\.\.([0-9a-f]+)/;
+const SIMILARITY_LINE = /^similarity index (\d+)%/;
+const HUNK_HEADER = /^@@ -(\d+)(?:,(\d+))? \+(\d+)(?:,(\d+))? @@ ?(.*)$/;
+const NO_NEWLINE = /^\\ No newline/;
+/**
+ * Start a file from its `diff --git` header. The header is
+ * the only place a binary file or a bare mode change names
+ * its paths, since git omits the `---` and `+++` pair for
+ * those; when the pair is present it overrides these.
+ */
+function startFile(header) {
+    const file = { status: "modified", hunks: [] };
+    const paths = FILE_HEADER_PATHS.exec(header);
+    if (paths) {
+        file.oldPath = paths[1];
+        file.newPath = paths[2];
+    }
+    return file;
+}
+/**
+ * Strip the `a/` or `b/` prefix git puts on diff paths.
+ * `/dev/null` means the file does not exist on that side.
+ */
+function diffPath(raw) {
+    if (raw === "/dev/null")
+        return undefined;
+    return raw.replace(/^[ab]\//, "");
+}
+function readHunkHeader(line) {
+    const match = HUNK_HEADER.exec(line);
+    if (!match)
+        return undefined;
+    const [, oldStart, oldCount, newStart, newCount, section] = match;
+    return {
+        oldStart: Number(oldStart),
+        // git omits the count when the range covers one line.
+        oldCount: oldCount === undefined ? 1 : Number(oldCount),
+        newStart: Number(newStart),
+        newCount: newCount === undefined ? 1 : Number(newCount),
+        ...(section ? { section } : {}),
+        lines: [],
+    };
+}
+/**
+ * Append one body line to a hunk, numbering it on whichever
+ * sides it exists on. Returns the advanced cursors.
+ */
+function readBodyLine(hunk, line, oldLine, newLine) {
+    const text = line.slice(1);
+    if (line.startsWith("+")) {
+        hunk.lines.push({ kind: "added", newLine, text });
+        return { oldLine, newLine: newLine + 1 };
+    }
+    if (line.startsWith("-")) {
+        hunk.lines.push({ kind: "removed", oldLine, text });
+        return { oldLine: oldLine + 1, newLine };
+    }
+    hunk.lines.push({ kind: "context", oldLine, newLine, text });
+    return { oldLine: oldLine + 1, newLine: newLine + 1 };
+}
+/**
+ * Read one of the header lines that sit between a file
+ * header and its first hunk: paths, mode changes, renames,
+ * blob ids and the binary marker.
+ */
+function readFileHeader(file, line) {
+    if (line.startsWith("--- ")) {
+        file.oldPath = diffPath(line.slice(4));
+        return;
+    }
+    if (line.startsWith("+++ ")) {
+        file.newPath = diffPath(line.slice(4));
+        return;
+    }
+    if (line.startsWith("new file mode")) {
+        file.status = "added";
+        // The header named both sides; an added file has no old one.
+        file.oldPath = undefined;
+        return;
+    }
+    if (line.startsWith("deleted file mode")) {
+        file.status = "deleted";
+        file.newPath = undefined;
+        return;
+    }
+    if (line.startsWith("rename from ")) {
+        file.status = "renamed";
+        file.oldPath = line.slice("rename from ".length);
+        return;
+    }
+    if (line.startsWith("rename to ")) {
+        file.status = "renamed";
+        file.newPath = line.slice("rename to ".length);
+        return;
+    }
+    if (line.startsWith("Binary files")) {
+        file.binary = true;
+        return;
+    }
+    const similarity = SIMILARITY_LINE.exec(line);
+    if (similarity) {
+        file.similarity = Number(similarity[1]);
+        return;
+    }
+    const index = INDEX_LINE.exec(line);
+    if (index) {
+        file.oldBlob = index[1];
+        file.newBlob = index[2];
+    }
+}
+/**
+ * Parse git's unified diff output into a `DiffModel`.
+ *
+ * Tolerant by design: a diff arrives from whichever backend
+ * produced it, so an unrecognized header line is skipped
+ * rather than treated as an error.
+ */
+export function parseUnifiedDiff(text) {
+    const files = [];
+    let file;
+    let hunk;
+    let oldLine = 0;
+    let newLine = 0;
+    for (const line of text.split("\n")) {
+        if (FILE_HEADER.test(line)) {
+            file = startFile(line);
+            files.push(file);
+            hunk = undefined;
+            continue;
+        }
+        if (!file)
+            continue;
+        const header = readHunkHeader(line);
+        if (header) {
+            hunk = header;
+            file.hunks.push(hunk);
+            oldLine = hunk.oldStart;
+            newLine = hunk.newStart;
+            continue;
+        }
+        if (hunk) {
+            // The no-newline marker annotates the line above it
+            // rather than being a line of its own.
+            if (NO_NEWLINE.test(line))
+                continue;
+            if (line === "")
+                continue;
+            ({ oldLine, newLine } = readBodyLine(hunk, line, oldLine, newLine));
+            continue;
+        }
+        readFileHeader(file, line);
+    }
+    return { files };
+}

package/dist/review/draft/continuation.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Putting a remark under a bullet without breaking the bullet.
+ *
+ * Every remark worth making runs past one line: a header, a
+ * blank, then the reasoning. Markdown ends a list at the first
+ * blank line that is not followed by indented text, so indenting
+ * only the opening line detaches the reasoning, which then reads
+ * as loose prose belonging to nobody.
+ *
+ * This lives on its own because it was got wrong twice, in the
+ * publish plan and again in the document renderer, and the second
+ * one was only caught by reading the output of a real review.
+ */
+/**
+ * Indent every line of a body so it stays inside its list item.
+ *
+ * A blank line keeps its blankness rather than being padded to
+ * the indent, because padding leaves trailing whitespace on every
+ * paragraph break.
+ */
+export declare function indentUnderBullet(body: string, indent?: string): string;
+/** A bullet whose body survives its own line breaks. */
+export declare function bullet(label: string, body: string, indent?: string): string;

package/dist/review/draft/continuation.js

@@ -0,0 +1,32 @@
+/**
+ * Putting a remark under a bullet without breaking the bullet.
+ *
+ * Every remark worth making runs past one line: a header, a
+ * blank, then the reasoning. Markdown ends a list at the first
+ * blank line that is not followed by indented text, so indenting
+ * only the opening line detaches the reasoning, which then reads
+ * as loose prose belonging to nobody.
+ *
+ * This lives on its own because it was got wrong twice, in the
+ * publish plan and again in the document renderer, and the second
+ * one was only caught by reading the output of a real review.
+ */
+/** How far a continuation line sits under its bullet. */
+const INDENT = "  ";
+/**
+ * Indent every line of a body so it stays inside its list item.
+ *
+ * A blank line keeps its blankness rather than being padded to
+ * the indent, because padding leaves trailing whitespace on every
+ * paragraph break.
+ */
+export function indentUnderBullet(body, indent = INDENT) {
+    return body
+        .split("\n")
+        .map((line) => (line.trim() === "" ? "" : `${indent}${line}`))
+        .join("\n");
+}
+/** A bullet whose body survives its own line breaks. */
+export function bullet(label, body, indent = INDENT) {
+    return `- ${label}\n${indentUnderBullet(body, indent)}`;
+}

package/dist/review/draft/fanout.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Publishing one review across a stack.
+ *
+ * A draft is about one change, so a review of a stack is several
+ * drafts published together. The fan-out exists because publishing
+ * them one at a time by hand loses the only thing a caller needs
+ * afterwards: which changes now carry the review and which do not.
+ *
+ * The rule inside one plan applies again here, one level up. A change
+ * that failed does not stop the changes after it, because stopping
+ * leaves a partly published review with no record of which part
+ * landed, and the caller's only recourse is to post everything twice
+ * or abandon the lot. So every change reports its own outcome,
+ * execution continues past a failure, and the answer says plainly what
+ * is left.
+ *
+ * Publishing is sequential rather than concurrent. Six reviews landing
+ * at once on a stack is six notifications in an unpredictable order to
+ * whoever is watching it, and a rate limit hit halfway through
+ * concurrent posts leaves a mess that is harder to describe than a
+ * slow success.
+ */
+import type { ChangeRef } from "../change.js";
+import type { ReviewProvider } from "../provider.js";
+import type { PublishPlan } from "./plan.js";
+import { type PublishOutcome } from "./publish.js";
+/** One change in the stack, and what to publish to it. */
+export interface StackPublishEntry {
+    /** The change's ref, which is how a reader names it. */
+    ref: string;
+    change: ChangeRef;
+    plan: PublishPlan;
+}
+/** What became of one change. */
+export interface ChangePublishOutcome {
+    ref: string;
+    change: ChangeRef;
+    outcome: PublishOutcome;
+}
+/** What became of the whole fan-out. */
+export interface StackPublishOutcome {
+    /** True only when every change landed everything. */
+    ok: boolean;
+    /** In the order the entries were given. */
+    changes: ChangePublishOutcome[];
+    /** Refs that carry their whole review now. */
+    landed: string[];
+    /** Refs a retry should send again. */
+    remaining: string[];
+}
+/**
+ * Publish a review to every change in a stack.
+ *
+ * Entries are published in the order given, which a caller should make
+ * stack order so a reader meets the remarks the way the stack applies.
+ */
+export declare function publishAcross(entries: readonly StackPublishEntry[], provider: ReviewProvider): Promise<StackPublishOutcome>;

package/dist/review/draft/fanout.js

@@ -0,0 +1,46 @@
+/**
+ * Publishing one review across a stack.
+ *
+ * A draft is about one change, so a review of a stack is several
+ * drafts published together. The fan-out exists because publishing
+ * them one at a time by hand loses the only thing a caller needs
+ * afterwards: which changes now carry the review and which do not.
+ *
+ * The rule inside one plan applies again here, one level up. A change
+ * that failed does not stop the changes after it, because stopping
+ * leaves a partly published review with no record of which part
+ * landed, and the caller's only recourse is to post everything twice
+ * or abandon the lot. So every change reports its own outcome,
+ * execution continues past a failure, and the answer says plainly what
+ * is left.
+ *
+ * Publishing is sequential rather than concurrent. Six reviews landing
+ * at once on a stack is six notifications in an unpredictable order to
+ * whoever is watching it, and a rate limit hit halfway through
+ * concurrent posts leaves a mess that is harder to describe than a
+ * slow success.
+ */
+import { publishPlan } from "./publish.js";
+/**
+ * Publish a review to every change in a stack.
+ *
+ * Entries are published in the order given, which a caller should make
+ * stack order so a reader meets the remarks the way the stack applies.
+ */
+export async function publishAcross(entries, provider) {
+    const changes = [];
+    const landed = [];
+    const remaining = [];
+    for (const entry of entries) {
+        const outcome = await publishPlan(entry.plan, provider);
+        changes.push({ ref: entry.ref, change: entry.change, outcome });
+        // A plan with no operations lands trivially. Calling it remaining
+        // would keep a retry alive forever over a change nobody had a
+        // remark about.
+        if (outcome.ok)
+            landed.push(entry.ref);
+        else
+            remaining.push(entry.ref);
+    }
+    return { ok: remaining.length === 0, changes, landed, remaining };
+}