@jitsusama/agentic-harness.core 0.1.0

package/dist/review/finding.js

@@ -0,0 +1,85 @@
+/**
+ * A produced finding, held by the substrate.
+ *
+ * Something reviewed a change and has an observation about it.
+ * That observation outlives the thing that produced it: a council
+ * run ends, the session carries on, and the findings have to still
+ * be there to be read, curated and turned into remarks. So the
+ * substrate holds them, not whichever machinery raised them.
+ *
+ * A finding points at a place through the same `Anchor` a remark
+ * uses. That is deliberate rather than convenient: it means a
+ * finding carries a witness commit, so one raised against an
+ * earlier commit can be told it has gone stale instead of being
+ * posted at a line that has since moved.
+ */
+import { mkdir, readFile, rm, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { changeKey } from "./keys.js";
+/** Findings on disk, one file per change. */
+export function createFindingStore(root) {
+    async function read(change) {
+        try {
+            const raw = await readFile(join(root, fileFor(change)), "utf8");
+            const parsed = JSON.parse(raw);
+            if (typeof parsed === "object" &&
+                parsed !== null &&
+                "findings" in parsed &&
+                Array.isArray(parsed.findings)) {
+                const ledger = parsed;
+                return {
+                    findings: ledger.findings,
+                    issued: ledger.issued ?? ledger.findings.length,
+                };
+            }
+        }
+        catch {
+            // No file, or one nothing can read. Either way this
+            // change has no findings to report, which is an answer
+            // rather than a failure.
+        }
+        return { findings: [], issued: 0 };
+    }
+    async function write(change, ledger) {
+        await mkdir(root, { recursive: true });
+        await writeFile(join(root, fileFor(change)), JSON.stringify(ledger, null, 2), "utf8");
+    }
+    return {
+        async record(change, raised) {
+            const ledger = await read(change);
+            const added = raised.map((finding, index) => ({
+                ...finding,
+                id: ledger.issued + index + 1,
+            }));
+            await write(change, {
+                findings: [...ledger.findings, ...added],
+                issued: ledger.issued + added.length,
+            });
+            return added;
+        },
+        async list(change) {
+            return (await read(change)).findings;
+        },
+        async clear(change) {
+            const ledger = await read(change);
+            if (ledger.issued === 0) {
+                await rm(join(root, fileFor(change)), { force: true });
+                return;
+            }
+            await write(change, { findings: [], issued: ledger.issued });
+        },
+    };
+}
+/**
+ * One file per change.
+ *
+ * Keyed by the change's key rather than its label, because a
+ * label is for people and can hold characters a path cannot, and
+ * two systems can spell one label the same way.
+ */
+function fileFor(change) {
+    const safe = changeKey(change)
+        .replace(/[^A-Za-z0-9._-]/g, "_")
+        .replace(/^\.+/, "_");
+    return `${safe}.json`;
+}

package/dist/review/fix.d.ts

@@ -0,0 +1,147 @@
+/**
+ * Findings somebody decided to fix rather than say.
+ *
+ * A review produces two kinds of conclusion, and only one of them is a
+ * remark. The other is work: a finding you agree with on your own
+ * change is not something to post, it is something to go and do. This
+ * is where those wait.
+ *
+ * The walk is deliberately not autonomous. `next` says what to work on
+ * and nothing else; the editing, the checking and the commit happen in
+ * the caller's own loop, where a person can interrupt at any point.
+ * Then `record` says what became of it. A queue that applied its own
+ * fixes would be a queue nobody could stop halfway.
+ *
+ * Nothing is ever removed. A fix that was abandoned stays with the
+ * reason it was abandoned, because somebody deciding a finding was
+ * wrong is a judgement worth reading back, and a queue that forgets
+ * its refusals will offer the same finding again next week.
+ *
+ * Two kinds of thing land here, and for a while only one of them
+ * could. A finding is something a reviewer raised, ours or a model's.
+ * A thread is somebody else's remark on our change, waiting for an
+ * answer, and working through those is the commonest review journey
+ * there is: it is what a person does on the morning after a review.
+ * A queue that held only findings could not represent that day at
+ * all, so it was a worklist for the rarer half of the work.
+ */
+import type { ChangeRef } from "./change.js";
+import type { Finding } from "./finding.js";
+/** What became of a queued fix. */
+export type FixOutcome = {
+    kind: "committed";
+    commit: string;
+} | {
+    kind: "skipped";
+    reason: string;
+}
+/**
+ * Answered in the conversation, with no code change.
+ *
+ * Only a thread can end this way, and it is not a skip. A remark
+ * answered by explaining why the code is as it is has been dealt
+ * with, and recording it as skipped would put it in the same bucket
+ * as one nobody got to.
+ */
+ | {
+    kind: "answered";
+    reply: string;
+};
+/**
+ * What a queued item is about.
+ *
+ * A discriminated union rather than two optional fields, so a reader
+ * cannot forget to check which one it has. The two need different
+ * things done to them: a finding is closed by a commit, a thread is
+ * closed by an answer and often a commit as well.
+ */
+export type FixSubject = {
+    kind: "finding";
+    finding: Finding;
+} | {
+    kind: "thread";
+    thread: QueuedThread;
+};
+/**
+ * The part of a thread worth carrying into the queue.
+ *
+ * Flattened rather than holding the whole {@link Thread}, because a
+ * queue entry is read weeks later and the live thread will have moved
+ * on. What is kept is what a person needs to recognise the item
+ * without fetching anything: who said it, where, and what they said.
+ */
+export interface QueuedThread {
+    /** Provider-scoped id, so the answer can be posted to it later. */
+    id: string;
+    /** Who opened it, when the provider says. */
+    author?: string;
+    /** Where it attaches, as a path and line when it has one. */
+    where?: string;
+    /** The opening remark, which is what is being answered. */
+    said: string;
+}
+/** One item on the queue. */
+export interface QueuedFix {
+    /** Stable within a change, and what `record` is called with. */
+    findingId: number;
+    /**
+     * What the item is about.
+     *
+     * Optional only for the sake of ledgers written before threads
+     * could be queued; {@link subjectOf} fills it in from the older
+     * shape rather than making every reader handle both.
+     */
+    subject?: FixSubject;
+    /**
+     * The finding, as the first version of this file stored it.
+     *
+     * Kept so an existing queue still reads. Nothing writes it now.
+     */
+    finding?: Finding;
+    /** What whoever queued it knew about how to fix it. */
+    note?: string;
+    /** Absent while it is still pending. */
+    outcome?: FixOutcome;
+}
+/**
+ * What an entry is about, however old the entry is.
+ *
+ * The migration lives here rather than in a one-shot rewrite of every
+ * file on disk. A queue is small, read often and written rarely, so
+ * adapting on read costs nothing and cannot half-finish. Returns
+ * undefined only for an entry that carries neither, which is a
+ * corrupt record rather than an old one.
+ */
+export declare function subjectOf(entry: QueuedFix): FixSubject | undefined;
+/** A one-line description of what a queued item is, for a listing. */
+export declare function describeSubject(entry: QueuedFix): string;
+/** How the queue stands. */
+export interface FixTally {
+    pending: number;
+    committed: number;
+    skipped: number;
+    /** Threads answered in the conversation, with no code change. */
+    answered: number;
+}
+/** The queue of fixes for a change. */
+export interface FixQueue {
+    queue(change: ChangeRef, finding: Finding, note?: string): Promise<void>;
+    /**
+     * Put somebody's remark on the worklist.
+     *
+     * Numbered in the same sequence as findings, because a person
+     * working through a morning's review does not care which half of
+     * the surface an item came from, and two numbering schemes on one
+     * change would make "item 4" ambiguous out loud. Answers the number
+     * it was given.
+     */
+    queueThread(change: ChangeRef, thread: QueuedThread, note?: string): Promise<number>;
+    /** The oldest fix with no outcome yet. */
+    next(change: ChangeRef): Promise<QueuedFix | undefined>;
+    record(change: ChangeRef, findingId: number, outcome: FixOutcome): Promise<void>;
+    /** Everything ever queued, settled or not, in order. */
+    list(change: ChangeRef): Promise<QueuedFix[]>;
+    tally(change: ChangeRef): Promise<FixTally>;
+}
+/** A queue kept on disk, one file per change. */
+export declare function createFixQueue(root: string): FixQueue;

package/dist/review/fix.js

@@ -0,0 +1,175 @@
+/**
+ * Findings somebody decided to fix rather than say.
+ *
+ * A review produces two kinds of conclusion, and only one of them is a
+ * remark. The other is work: a finding you agree with on your own
+ * change is not something to post, it is something to go and do. This
+ * is where those wait.
+ *
+ * The walk is deliberately not autonomous. `next` says what to work on
+ * and nothing else; the editing, the checking and the commit happen in
+ * the caller's own loop, where a person can interrupt at any point.
+ * Then `record` says what became of it. A queue that applied its own
+ * fixes would be a queue nobody could stop halfway.
+ *
+ * Nothing is ever removed. A fix that was abandoned stays with the
+ * reason it was abandoned, because somebody deciding a finding was
+ * wrong is a judgement worth reading back, and a queue that forgets
+ * its refusals will offer the same finding again next week.
+ *
+ * Two kinds of thing land here, and for a while only one of them
+ * could. A finding is something a reviewer raised, ours or a model's.
+ * A thread is somebody else's remark on our change, waiting for an
+ * answer, and working through those is the commonest review journey
+ * there is: it is what a person does on the morning after a review.
+ * A queue that held only findings could not represent that day at
+ * all, so it was a worklist for the rarer half of the work.
+ */
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { changeKey } from "./keys.js";
+/**
+ * What an entry is about, however old the entry is.
+ *
+ * The migration lives here rather than in a one-shot rewrite of every
+ * file on disk. A queue is small, read often and written rarely, so
+ * adapting on read costs nothing and cannot half-finish. Returns
+ * undefined only for an entry that carries neither, which is a
+ * corrupt record rather than an old one.
+ */
+export function subjectOf(entry) {
+    if (entry.subject !== undefined)
+        return entry.subject;
+    if (entry.finding !== undefined) {
+        return { kind: "finding", finding: entry.finding };
+    }
+    return undefined;
+}
+/** A one-line description of what a queued item is, for a listing. */
+export function describeSubject(entry) {
+    const subject = subjectOf(entry);
+    if (subject === undefined)
+        return "an item with nothing recorded on it";
+    if (subject.kind === "finding")
+        return subject.finding.subject;
+    const { thread } = subject;
+    const who = thread.author === undefined ? "somebody" : thread.author;
+    const where = thread.where === undefined ? "" : ` on ${thread.where}`;
+    return `${who}${where}: ${thread.said}`;
+}
+/** A queue kept on disk, one file per change. */
+export function createFixQueue(root) {
+    async function read(change) {
+        try {
+            const raw = await readFile(join(root, fileFor(change)), "utf8");
+            const parsed = JSON.parse(raw);
+            if (typeof parsed === "object" &&
+                parsed !== null &&
+                "fixes" in parsed &&
+                Array.isArray(parsed.fixes)) {
+                return { fixes: parsed.fixes };
+            }
+        }
+        catch {
+            // No file, or one nothing can read. Either way this change has
+            // nothing queued, which is an answer rather than a failure.
+        }
+        return { fixes: [] };
+    }
+    async function write(change, ledger) {
+        await mkdir(root, { recursive: true });
+        await writeFile(join(root, fileFor(change)), JSON.stringify(ledger, null, 2), "utf8");
+    }
+    return {
+        async queue(change, finding, note) {
+            const ledger = await read(change);
+            if (ledger.fixes.some((one) => one.findingId === finding.id)) {
+                // Queued twice means fixed twice, or worse, fixed once and
+                // then reported as still outstanding.
+                throw new Error(`Finding ${finding.id} is already queued for fixing on ${change.label}.`);
+            }
+            ledger.fixes.push({
+                findingId: finding.id,
+                subject: { kind: "finding", finding },
+                ...(note === undefined || note.trim() === ""
+                    ? {}
+                    : { note: note.trim() }),
+            });
+            await write(change, ledger);
+        },
+        async queueThread(change, thread, note) {
+            const ledger = await read(change);
+            const already = ledger.fixes.find((one) => {
+                const subject = subjectOf(one);
+                return subject?.kind === "thread" && subject.thread.id === thread.id;
+            });
+            if (already) {
+                // Same reasoning as a finding queued twice, and more likely
+                // here: a caller sweeping unresolved threads will sweep the
+                // same ones again tomorrow.
+                throw new Error(`That thread is already on the worklist for ${change.label}, as item ${already.findingId}.`);
+            }
+            // One sequence for both kinds. Findings carry numbers minted by
+            // the finding store, so this takes the next number above
+            // everything present rather than counting its own entries,
+            // which would collide the moment a finding was queued after it.
+            const id = ledger.fixes.reduce((top, one) => Math.max(top, one.findingId), 0) + 1;
+            ledger.fixes.push({
+                findingId: id,
+                subject: { kind: "thread", thread },
+                ...(note === undefined || note.trim() === ""
+                    ? {}
+                    : { note: note.trim() }),
+            });
+            await write(change, ledger);
+            return id;
+        },
+        async next(change) {
+            const { fixes } = await read(change);
+            // Insertion order, so the same queue read twice is the same
+            // queue. A reader who saw a list and then asked for the next
+            // one should get the one they were looking at.
+            return fixes.find((one) => one.outcome === undefined);
+        },
+        async record(change, findingId, outcome) {
+            const ledger = await read(change);
+            const held = ledger.fixes.find((one) => one.findingId === findingId);
+            if (held === undefined) {
+                throw new Error(`Finding ${findingId} is not queued for fixing on ${change.label}, so there is nothing to record against it.`);
+            }
+            if (held.outcome !== undefined) {
+                // The first answer is the true one. Overwriting would let a
+                // later mistake erase a commit that really happened.
+                throw new Error(`Finding ${findingId} was already recorded as ${held.outcome.kind}. Reopen it by queueing the follow-up as its own finding.`);
+            }
+            held.outcome = outcome;
+            await write(change, ledger);
+        },
+        async list(change) {
+            return (await read(change)).fixes;
+        },
+        async tally(change) {
+            const { fixes } = await read(change);
+            return {
+                pending: fixes.filter((one) => one.outcome === undefined).length,
+                committed: fixes.filter((one) => one.outcome?.kind === "committed")
+                    .length,
+                skipped: fixes.filter((one) => one.outcome?.kind === "skipped").length,
+                answered: fixes.filter((one) => one.outcome?.kind === "answered")
+                    .length,
+            };
+        },
+    };
+}
+/**
+ * File name for a change's queue.
+ *
+ * Folded to something safe, so a change key carrying a slash or a pair
+ * of dots cannot name a path outside the queue directory.
+ */
+function fileFor(change) {
+    const safe = changeKey(change)
+        .replace(/[^A-Za-z0-9._-]/g, "_")
+        .replace(/^\.+/, "_");
+    return `${safe}.json`;
+}

package/dist/review/followup.d.ts

@@ -0,0 +1,84 @@
+/**
+ * Coming back to a change you have already reviewed.
+ *
+ * The audit round asks where an inbound thread stands: somebody remarked on my
+ * change and I need to answer honestly. This is the mirror, and it was missing.
+ * I left findings on somebody else's change, they pushed, and the question is
+ * whether they addressed them or simply resolved the thread. Those two look
+ * identical in a thread listing, and only one of them is fine.
+ *
+ * It is deliberately a computation rather than a round. No model is needed to
+ * notice that a thread was closed with no reply and no change to the code under
+ * it. Asking one would be slower, more expensive and less certain, and it would
+ * dress a fact up as a judgement.
+ *
+ * What it cannot do is say whether the change was the *right* change. That needs
+ * reading the diff, which is a review, and this is the thing that tells you
+ * which threads are worth re-reading.
+ */
+import type { Actor } from "./change.js";
+import type { Thread } from "./conversation.js";
+/**
+ * How one of my remarks was received, now the change has moved on.
+ *
+ * Called a reception rather than a standing because the audit round already
+ * owns that word for the opposite direction: where an inbound thread stands
+ * against my change. Two different questions sharing one noun would make every
+ * later reader check which one they were holding.
+ */
+export type Reception = 
+/** Somebody replied after my last remark. Read it. */
+"answered"
+/** The anchor no longer describes the change, so something moved under it. */
+ | "changed"
+/**
+ * Closed with no reply, and nothing here shows the code moved.
+ *
+ * The one worth looking at, and worth stating carefully. It does not claim
+ * the code is unchanged, because that is not knowable from a thread: a
+ * remark can be answered by a conversation elsewhere, or be wrong, or be
+ * about something the author decided against. What it says is narrower and
+ * still useful: the thread says settled and nothing in the thread supports
+ * that, so it is the one to re-read.
+ */
+ | "resolved-quietly"
+/** Still open and nobody has replied. */
+ | "waiting"
+/** Not one of mine, so there is nothing to say about it. */
+ | "unknown";
+/** One of my threads, and how it was received. */
+export interface FollowUp {
+    thread: Thread;
+    reception: Reception;
+    /** Said in words, for a listing. */
+    because: string;
+}
+/**
+ * How one thread was received, for the actor who remarked on it.
+ *
+ * Order matters. A reply is the strongest signal, because somebody wrote words
+ * aimed at the remark; a moved anchor is next, because something happened even
+ * if nobody said so. Quiet is only reported once neither of those is true.
+ *
+ * What this deliberately does **not** do is read `stale: false` as "the code did
+ * not move". Those are different claims, and the backends prove it: GitHub's
+ * flag is whether the diff hunk is still present, so false does correlate with
+ * unchanged code, while Meteorite reports false always, because its server keeps
+ * the witness commit reachable and an anchor there can never strand. Inferring
+ * "nothing changed" from that would accuse an author who fixed the code of
+ * closing a thread and ignoring it, on the backend where most of this work
+ * happens. So a positive `stale` is evidence and its absence is not evidence of
+ * the opposite.
+ */
+export declare function receptionOf(thread: Thread, viewer: Actor): Reception;
+/**
+ * My threads on a change, and where each stands.
+ *
+ * Only threads I spoke in, since a thread I never joined is somebody else's
+ * conversation and belongs to the audit round instead. Ordered so the ones
+ * worth attention come first: a thread closed in silence, then one waiting, then
+ * the ones something has already happened to.
+ */
+export declare function followUpOn(threads: readonly Thread[], viewer: Actor): readonly FollowUp[];
+/** How many of each reception, for a one-line summary. */
+export declare function tallyReceptions(found: readonly FollowUp[]): Partial<Record<Reception, number>>;

package/dist/review/followup.js

@@ -0,0 +1,123 @@
+/**
+ * Coming back to a change you have already reviewed.
+ *
+ * The audit round asks where an inbound thread stands: somebody remarked on my
+ * change and I need to answer honestly. This is the mirror, and it was missing.
+ * I left findings on somebody else's change, they pushed, and the question is
+ * whether they addressed them or simply resolved the thread. Those two look
+ * identical in a thread listing, and only one of them is fine.
+ *
+ * It is deliberately a computation rather than a round. No model is needed to
+ * notice that a thread was closed with no reply and no change to the code under
+ * it. Asking one would be slower, more expensive and less certain, and it would
+ * dress a fact up as a judgement.
+ *
+ * What it cannot do is say whether the change was the *right* change. That needs
+ * reading the diff, which is a review, and this is the thing that tells you
+ * which threads are worth re-reading.
+ */
+/** Whether two actors are the same person, as this backend names them. */
+function same(one, other) {
+    // Ids only. A display name is not an identity: two people share one, and
+    // one person changes theirs, and matching on it eventually attributes
+    // somebody else's remark to you.
+    return one.id === other.id;
+}
+/** The last comment in a thread written by this actor. */
+function lastFrom(thread, who) {
+    let at = -1;
+    thread.comments.forEach((comment, index) => {
+        if (same(comment.author, who))
+            at = index;
+    });
+    return at;
+}
+/**
+ * How one thread was received, for the actor who remarked on it.
+ *
+ * Order matters. A reply is the strongest signal, because somebody wrote words
+ * aimed at the remark; a moved anchor is next, because something happened even
+ * if nobody said so. Quiet is only reported once neither of those is true.
+ *
+ * What this deliberately does **not** do is read `stale: false` as "the code did
+ * not move". Those are different claims, and the backends prove it: GitHub's
+ * flag is whether the diff hunk is still present, so false does correlate with
+ * unchanged code, while Meteorite reports false always, because its server keeps
+ * the witness commit reachable and an anchor there can never strand. Inferring
+ * "nothing changed" from that would accuse an author who fixed the code of
+ * closing a thread and ignoring it, on the backend where most of this work
+ * happens. So a positive `stale` is evidence and its absence is not evidence of
+ * the opposite.
+ */
+export function receptionOf(thread, viewer) {
+    const mine = lastFrom(thread, viewer);
+    if (mine === -1)
+        return "unknown";
+    const after = thread.comments.slice(mine + 1);
+    if (after.some((comment) => !same(comment.author, viewer))) {
+        return "answered";
+    }
+    if (thread.stale === true)
+        return "changed";
+    return thread.resolved ? "resolved-quietly" : "waiting";
+}
+/**
+ * Why a reception reads the way it does, in words a listing can print.
+ *
+ * The wording carries the uncertainty, which is where it belongs. A quiet
+ * resolution reads differently depending on whether the backend says anything
+ * about the anchor at all, and saying which of the two you are looking at is the
+ * difference between a reader who checks and a reader who accuses.
+ */
+function becauseOf(reception, thread) {
+    switch (reception) {
+        case "answered":
+            return "somebody replied after your remark";
+        case "changed":
+            return "the anchor no longer describes the change, so something moved under it";
+        case "resolved-quietly": {
+            const who = thread.resolvedBy === undefined
+                ? "resolved"
+                : `resolved by ${thread.resolvedBy.name ?? thread.resolvedBy.id}`;
+            return thread.stale === undefined
+                ? `${who} with no reply, and this backend does not say whether the code moved`
+                : `${who} with no reply, and the anchor still describes the change`;
+        }
+        case "waiting":
+            return "still open, and nobody has replied";
+        case "unknown":
+            return "you have not spoken in this thread";
+    }
+}
+/**
+ * My threads on a change, and where each stands.
+ *
+ * Only threads I spoke in, since a thread I never joined is somebody else's
+ * conversation and belongs to the audit round instead. Ordered so the ones
+ * worth attention come first: a thread closed in silence, then one waiting, then
+ * the ones something has already happened to.
+ */
+export function followUpOn(threads, viewer) {
+    const rank = {
+        "resolved-quietly": 0,
+        waiting: 1,
+        answered: 2,
+        changed: 3,
+        unknown: 4,
+    };
+    return threads
+        .filter((thread) => lastFrom(thread, viewer) !== -1)
+        .map((thread) => {
+        const reception = receptionOf(thread, viewer);
+        return { thread, reception, because: becauseOf(reception, thread) };
+    })
+        .sort((one, other) => rank[one.reception] - rank[other.reception]);
+}
+/** How many of each reception, for a one-line summary. */
+export function tallyReceptions(found) {
+    const counted = {};
+    for (const one of found) {
+        counted[one.reception] = (counted[one.reception] ?? 0) + 1;
+    }
+    return counted;
+}