@jitsusama/agentic-harness.core 0.1.0

package/dist/review/attach.js

@@ -0,0 +1,357 @@
+/**
+ * Which change a call is about, when the caller did not say.
+ *
+ * Every review tool used to demand a change on every call, so
+ * reading a diff and then its threads meant naming the same
+ * pull request twice, and the second naming was where typos
+ * lived. A session attaches to what it is working on instead,
+ * and a call without a change acts on that.
+ *
+ * The rule is the browser integration's, because it was learned
+ * the same way and there is no reason for two answers to the
+ * same question. What differs is only the vocabulary: sessions
+ * are opened and changes are attached.
+ */
+import { mkdir, readdir, readFile, rm, stat, writeFile, } from "node:fs/promises";
+import { join } from "node:path";
+import { changeKey } from "./keys.js";
+/**
+ * Carry one session's attachments into another.
+ *
+ * For a fork, which is the same work continued under a new session
+ * id. Scoping attachments by session is what stopped one session
+ * retargeting another's round, and it made a fork start with nothing
+ * attached, so the first call after one either refused for want of a
+ * change or acted on whatever was named by hand. Neither is what
+ * forking means.
+ *
+ * A copy rather than a move: the session forked from is still there
+ * and still working on what it was working on.
+ *
+ * Never overwrites a change the fork already holds, and carried ones
+ * are attached oldest first, so the parent's order survives and
+ * anything the fork attaches afterwards outranks all of it. That
+ * ordering is the point rather than a detail: `changeInPlay` takes the
+ * most recent when a call names nothing, so an inherited change
+ * outranking what this session just said it was working on would act
+ * on the wrong one and announce it as the most recent.
+ *
+ * Written through the store's own `attach`, so the record's shape and
+ * the sequence rule stay in one place. Reading through a store and
+ * writing around it is how two spellings of one format come about.
+ *
+ * Awaited at session start, unlike the reclamations it sits beside.
+ * Those are about the machine; this is about the answer to the next
+ * call, and a fork whose first review call lands before the copy
+ * finishes sees the refusal this exists to prevent.
+ *
+ * Advisory in what it reads: what it cannot read it does not carry,
+ * and nothing about a fork fails over it.
+ *
+ * Returns how many were carried.
+ */
+export async function inheritAttachments(root, from, to) {
+    // Reading and writing one directory, where every name collides with
+    // itself, is a way to lose an attachment rather than keep one.
+    if (safeName(from) === safeName(to))
+        return 0;
+    const parent = createAttachmentStore(root, from);
+    const fork = createAttachmentStore(root, to);
+    let held;
+    let mine;
+    try {
+        held = await parent.list();
+        mine = await fork.list();
+    }
+    catch {
+        // An unreadable directory carries nothing. An attachment is a
+        // convenience and never the record of anything.
+        return 0;
+    }
+    const already = new Set(mine.map((one) => changeKey(one.change)));
+    // Newest first, as `list` answers, since each one goes below the
+    // last: the parent's order comes out the same way up.
+    const carrying = held.filter((one) => !already.has(changeKey(one.change)));
+    let carried = 0;
+    for (const one of carrying) {
+        try {
+            await fork.inherit(one.change);
+            carried += 1;
+        }
+        catch {
+            // One that cannot be written is one the fork attaches again
+            // by hand, which is a smaller loss than a fork that fails to
+            // start over a convenience.
+        }
+    }
+    return carried;
+}
+/**
+ * Give back the directories of sessions that have stopped using them.
+ *
+ * Scoping attachments per session means one directory per session for
+ * as long as the state directory lives, so something has to take them
+ * back. Age is judged on the newest attachment inside, not on the
+ * directory itself: a directory's timestamp moves when an entry is
+ * added or removed and stands still when one is rewritten in place, so
+ * a session that keeps freshening the same change would age as though
+ * nobody had touched it. The one asking is never swept regardless,
+ * because a long-lived session attaches its work once and then only
+ * reads it, which is exactly the shape an age rule mistakes for
+ * abandonment.
+ *
+ * Files are left alone. Attachments made before scoping existed sit
+ * flat in the root and belong to no session, so no session's rule
+ * should decide their fate; deleting somebody's attachment to tidy up
+ * is a poor trade for the disk it returns. They cost bytes and are
+ * invisible to every scoped caller.
+ *
+ * Putting them on this clock was tried and taken back out. An orphan
+ * is by definition a file nothing has written since scoping landed, so
+ * judging one by its own age gives no grace to the population it
+ * targets: on any machine where scoping shipped a month ago, every one
+ * of them goes on the first session start after the sweep ships. A
+ * month of grace that protects nobody it was written for is not an
+ * argument, and eighty kilobytes is not a reason to go looking for a
+ * better one.
+ *
+ * An empty directory is swept, since it holds nothing anybody can
+ * lose.
+ *
+ * Returns how many were taken back.
+ */
+export async function pruneAttachments(root, options) {
+    let entries;
+    try {
+        entries = await readdir(root, { withFileTypes: true });
+    }
+    catch {
+        // Nothing has ever been attached, so there is nothing to reclaim.
+        return 0;
+    }
+    const cutoff = Date.now() - options.olderThanMs;
+    // Through the same rewriting the store used to build the directory
+    // name, or a session whose id holds a character a path cannot carry
+    // would fail to match its own and be swept by the sweep that
+    // promises never to touch it.
+    const mine = options.keep === undefined ? undefined : safeName(options.keep);
+    let taken = 0;
+    for (const entry of entries) {
+        if (!entry.isDirectory())
+            continue;
+        if (entry.name === mine)
+            continue;
+        const path = join(root, entry.name);
+        try {
+            if ((await newestWithin(path)) > cutoff)
+                continue;
+            await rm(path, { recursive: true, force: true });
+            taken += 1;
+        }
+        catch {
+            // Another session may be writing here, or may have removed it
+            // already. Reclaiming disk is advisory: what it cannot take
+            // back this time it will find again next time.
+        }
+    }
+    return taken;
+}
+/**
+ * When anything in this directory was last written.
+ *
+ * Zero for one holding nothing, which reads as long ago and is right:
+ * an empty directory has nothing to lose.
+ */
+async function newestWithin(path) {
+    const names = await readdir(path);
+    let newest = 0;
+    for (const name of names) {
+        try {
+            newest = Math.max(newest, (await stat(join(path, name))).mtimeMs);
+        }
+        catch {
+            // Removed while being read, by another session's sweep or its
+            // own detach. It cannot be the newest thing here if it is
+            // already gone.
+        }
+    }
+    return newest;
+}
+/**
+ * File name for an attachment.
+ *
+ * Keyed by the provider-scoped change key rather than the label,
+ * because a label is for people: two systems can spell the same
+ * repo differently, and a label carrying a slash or a pair of
+ * dots would otherwise name a path outside the store. The key is
+ * hashed to a flat name for the same reason.
+ */
+function fileFor(change) {
+    return `${safeName(changeKey(change))}.json`;
+}
+/**
+ * One path segment, from a name that came from somewhere else.
+ *
+ * A change key or a session id is whatever the provider or the host
+ * chose, so one carrying a slash or a pair of dots would name a path
+ * outside the store.
+ */
+function safeName(name) {
+    const safe = name.replace(/[^A-Za-z0-9._-]/g, "_").replace(/^\.+/, "_");
+    return safe === "" ? "_" : safe;
+}
+/** Read one attachment, or nothing when it is unreadable. */
+async function readAttachment(path) {
+    try {
+        const parsed = JSON.parse(await readFile(path, "utf8"));
+        if (typeof parsed !== "object" ||
+            parsed === null ||
+            !("change" in parsed) ||
+            !("attachedAt" in parsed) ||
+            typeof parsed.seq !== "number") {
+            return undefined;
+        }
+        return parsed;
+    }
+    catch {
+        // An attachment is a convenience, never the record of
+        // anything. A file half-written by a kill, or left by an
+        // older shape of this type, should cost the reader nothing:
+        // they attach again and carry on.
+        return undefined;
+    }
+}
+/**
+ * Attachments on disk, one flat directory of JSON files.
+ *
+ * The same idiom as the draft store, and for the same reasons:
+ * legible to somebody who goes looking, cheap to list, and with
+ * no index that can fall out of step with the files it claims to
+ * describe.
+ */
+export function createAttachmentStore(root, sessionId) {
+    // One directory per session. What a session is working on is a fact
+    // about that session, and keeping every session's answer in one
+    // place made the newest of them everybody's: a round in one session
+    // was silently retargeted by another session attaching its own work,
+    // and the judge that followed consolidated a different repository's
+    // council while reporting success. Two sessions attached to the same
+    // change also need their own file, or detaching in one detaches in
+    // the other.
+    //
+    // Required, with no unscoped branch to fall into. It used to be
+    // optional, on the reasoning that a caller with no session cannot be
+    // racing one, and the caller that had no session id to give was the
+    // one that raced: it passed undefined every time and every session
+    // shared this root. A caller with nothing better to say can pass
+    // anything stable and unique to itself, which is a decision it can
+    // make and this cannot.
+    const mine = join(root, safeName(sessionId));
+    /** One attachment on disk, at the position it was given. */
+    async function write(change, seq) {
+        await mkdir(mine, { recursive: true });
+        const record = {
+            change,
+            attachedAt: new Date().toISOString(),
+            seq,
+        };
+        await writeFile(join(mine, fileFor(change)), JSON.stringify(record, null, 2), "utf8");
+    }
+    return {
+        async attach(change) {
+            const held = await this.list();
+            const highest = held.reduce((max, a) => Math.max(max, a.seq), 0);
+            await write(change, highest + 1);
+        },
+        async inherit(change) {
+            // Below the lowest rather than above the highest, and below
+            // zero once nothing is lower. The counter only has to climb
+            // within a session for the order to mean what it says, and
+            // what a fork inherits happened before the session began.
+            const held = await this.list();
+            const lowest = held.reduce((min, a) => Math.min(min, a.seq), 1);
+            await write(change, lowest - 1);
+        },
+        async detach(label) {
+            const found = (await this.list()).find((a) => a.change.label === label);
+            if (!found)
+                return false;
+            await rm(join(mine, fileFor(found.change)), { force: true });
+            return true;
+        },
+        async list() {
+            let names;
+            try {
+                names = await readdir(mine);
+            }
+            catch {
+                // Nothing has been attached yet, so there is no
+                // directory. That is not a failure to report.
+                return [];
+            }
+            const read = await Promise.all(names
+                .filter((name) => name.endsWith(".json"))
+                .map((name) => readAttachment(join(mine, name))));
+            return read
+                .filter((a) => a !== undefined)
+                .sort((a, b) => b.seq - a.seq);
+        },
+    };
+}
+/**
+ * Which attached change a call should act on.
+ *
+ * An explicit name is never second-guessed: somebody who names a
+ * change means that change, and a typo is better reported than
+ * quietly redirected to whatever else happens to be attached.
+ *
+ * With nothing named, one attached change is used and said out
+ * loud, so the reader knows what was read or written. Several
+ * stay a refusal rather than a guess, because acting on the
+ * wrong change is worse than being asked which one, and the
+ * hint only breaks that tie when it points at something actually
+ * attached.
+ */
+export function changeInPlay(asked, hint, attached) {
+    if (asked !== undefined)
+        return { label: asked };
+    if (hint !== undefined && attached.includes(hint))
+        return { label: hint };
+    const [newest, ...rest] = attached;
+    if (newest === undefined)
+        return { candidates: attached };
+    if (rest.length === 0) {
+        return {
+            label: newest,
+            note: `Using ${newest}, the only change attached.`,
+        };
+    }
+    // Recency settles it, because attaching a change is how you say what you
+    // are working on now. This used to refuse whenever two were attached, on
+    // the grounds that choosing could report on the wrong change, and the
+    // result was worse than the risk: a second attachment paralysed every
+    // tool, and the way out was to detach something. Meanwhile `attach`
+    // promised that later calls could leave the change out, and the listing
+    // promised newest first, and the store had kept a monotonic sequence all
+    // along for exactly this. Three claims that only a rule like this makes
+    // true.
+    //
+    // Said out loud every time, and it names the others, because the whole
+    // objection to choosing was silence rather than choice: a person who
+    // meant the other one has to be told which was taken and that the rest
+    // are still there.
+    return {
+        label: newest,
+        note: `Using ${newest}, attached most recently. Also attached: ${rest.join(", ")}. Name a change to act on one of those instead.`,
+    };
+}
+/** Say what to choose between, when the choice cannot be made here. */
+export function chooseChange(candidates) {
+    if (candidates.length === 0) {
+        return ("No change is attached. Run review attach with a change, or a " +
+            "base and head, and everything after it will act on that.");
+    }
+    return (`Several changes are attached: ${candidates.join(", ")}. Name the ` +
+        "one to act on, since choosing for you could report on the wrong " +
+        "change.");
+}

package/dist/review/authoring.d.ts

@@ -0,0 +1,84 @@
+/**
+ * Whether an authoring intent will work here, asked before trying.
+ *
+ * Reviewing degrades gracefully: a comment that cannot anchor becomes
+ * prose and the reader still gets the remark. Authoring does not. A
+ * retarget that means something different on this backend moves changes
+ * nobody asked to move, and a push to a change sitting in a merge queue
+ * ejects it and everything batched with it. The cheap moment to find
+ * out is before the call, not from a rejected request.
+ *
+ * So this answers three things rather than one: whether it will work,
+ * why not, and what to do instead. The third is what makes a refusal
+ * useful. A caller told only that something is unsupported has to go
+ * and read a CLI's help to find the door that is open, and every
+ * difference encoded here was found by doing exactly that.
+ */
+import type { AuthoringCapabilities, PersonForm } from "./capabilities.js";
+import { type QueueState } from "./queue.js";
+/** Something a caller wants to do to a proposal. */
+export interface AuthoringIntent {
+    kind: "propose" | "propose-stack"
+    /**
+     * Changing a change's own text: title, body, labels, assignees.
+     *
+     * Kept apart from `retarget` because only moving the base is a
+     * retarget, and conflating them refused a title change on a
+     * backend where retargeting happens to be a stack operation.
+     */
+     | "edit" | "retarget" | "set-draft" | "close" | "reopen" | "merge" | "request-reviewers"
+    /**
+     * Asking CI to run again.
+     *
+     * Not in {@link MUTATES}: a rerun starts a build, it does not
+     * move the branch or the base, so it does not eject a change
+     * from a merge queue the way an edit or a retarget does.
+     */
+     | "rerun-checks";
+    /** Naming reviewers as part of proposing. */
+    withReviewers?: boolean;
+    /**
+     * Where the change stands with a merge queue, read from the
+     * proposal rather than decided by the caller.
+     *
+     * This was a boolean, and a boolean was wrong twice over. Nothing
+     * ever set it, so the refusal below could not be reached; and it
+     * could not tell a change batched with fifty others from one being
+     * tested alone, which is the whole difference between an expensive
+     * mistake and a cheap one.
+     */
+    queue?: QueueState;
+}
+/**
+ * Whether it will work, and what to do instead when it will not.
+ *
+ * The permitted arm carries an optional `caution`, for the case that is
+ * neither safe nor refusable: a backend that has a merge queue and could
+ * not tell us where this change stands in it. Refusing would make every
+ * unreachable queue a read-only backend, and permitting silently hands
+ * somebody an expensive mistake with no warning. So it is permitted, out
+ * loud, and the confirmation gate is where a person decides.
+ */
+export type Offerable = {
+    ok: true;
+    caution?: string;
+} | {
+    ok: false;
+    reason: string;
+    instead?: string;
+};
+/** Whether this provider will accept this intent, and what to say. */
+/**
+ * Whether any of these are not the form the backend names people in.
+ *
+ * A phrase naming the offenders and the form wanted, or undefined when
+ * every one of them will do. Checked before the request, because a
+ * backend that refuses an assignee on the create route refuses it after
+ * the change exists.
+ *
+ * Nothing is translated. A login cannot be turned into an email without
+ * asking somebody who knows, and guessing one from the other is how a
+ * change gets assigned to a person who does not exist.
+ */
+export declare function misnamedPeople(who: string[], form: PersonForm): string | undefined;
+export declare function offerable(intent: AuthoringIntent, capabilities: AuthoringCapabilities | undefined, providerId: string): Offerable;

package/dist/review/authoring.js

@@ -0,0 +1,203 @@
+/**
+ * Whether an authoring intent will work here, asked before trying.
+ *
+ * Reviewing degrades gracefully: a comment that cannot anchor becomes
+ * prose and the reader still gets the remark. Authoring does not. A
+ * retarget that means something different on this backend moves changes
+ * nobody asked to move, and a push to a change sitting in a merge queue
+ * ejects it and everything batched with it. The cheap moment to find
+ * out is before the call, not from a rejected request.
+ *
+ * So this answers three things rather than one: whether it will work,
+ * why not, and what to do instead. The third is what makes a refusal
+ * useful. A caller told only that something is unsupported has to go
+ * and read a CLI's help to find the door that is open, and every
+ * difference encoded here was found by doing exactly that.
+ */
+import { queueRefusal } from "./queue.js";
+/**
+ * Intents that change the change itself.
+ *
+ * Merging is deliberately absent: a queue exists to merge things, so
+ * merging is not a mutation the queue objects to. Closing is absent for
+ * the same reason a queue does not care, and because a caller closing
+ * an enqueued change has already decided.
+ */
+const MUTATES = new Set([
+    "edit",
+    "retarget",
+    "set-draft",
+]);
+/** Whether this provider will accept this intent, and what to say. */
+/**
+ * Whether any of these are not the form the backend names people in.
+ *
+ * A phrase naming the offenders and the form wanted, or undefined when
+ * every one of them will do. Checked before the request, because a
+ * backend that refuses an assignee on the create route refuses it after
+ * the change exists.
+ *
+ * Nothing is translated. A login cannot be turned into an email without
+ * asking somebody who knows, and guessing one from the other is how a
+ * change gets assigned to a person who does not exist.
+ */
+export function misnamedPeople(who, form) {
+    if (form === "unknown" || who.length === 0)
+        return undefined;
+    // An address has an @ and a login does not. Crude on purpose: the job is
+    // to catch a whole set given in the other form, which is what happens
+    // when somebody carries habits from one backend to another, not to
+    // validate an address.
+    const wrong = who.filter((one) => one.includes("@") !== (form === "email"));
+    if (wrong.length === 0)
+        return undefined;
+    const wanted = form === "email"
+        ? "an email address, as this backend names people"
+        : "a login, as this backend names people";
+    return `${wrong.join(", ")} ${wrong.length === 1 ? "is not" : "are not"} ${wanted}.`;
+}
+export function offerable(intent, capabilities, providerId) {
+    if (capabilities === undefined) {
+        return {
+            ok: false,
+            reason: `The ${providerId} provider does not author changes, so there is nothing here to ${intent.kind.replace("-", " ")}.`,
+        };
+    }
+    // Asked before the per-intent questions, because a queue ejection is
+    // expensive whatever the intent was and the answer does not depend
+    // on whether the backend could otherwise do it.
+    const queued = capabilities.refusesWhileEnqueued && MUTATES.has(intent.kind);
+    if (queued) {
+        const refusal = queueRefusal(intent.queue, providerId);
+        if (refusal)
+            return { ok: false, ...refusal };
+    }
+    // Having a queue and not knowing where the change sits in it is its own
+    // answer: on some backends the queue lives somewhere the change's own
+    // API cannot see, so silence there is ignorance rather than safety.
+    //
+    // It decorates the answer instead of being one. Returning it directly
+    // skipped every per-intent question below, which permitted a retarget
+    // on a backend that had just said it could not do one. Three tests
+    // caught that, which is the only reason this reads as it does.
+    const answer = decide(intent, capabilities, providerId);
+    if (!answer.ok || !queued || intent.queue !== undefined)
+        return answer;
+    return {
+        ...answer,
+        caution: `${providerId} has a merge queue and did not say where this change stands in it. If it is queued, this ejects it and everything batched with it. Check before approving.`,
+    };
+}
+/** What this provider says about this intent, queue aside. */
+function decide(intent, capabilities, providerId) {
+    switch (intent.kind) {
+        case "propose":
+            return proposable(intent, capabilities, providerId);
+        case "edit":
+            // Every backend surveyed can change a change's own text. The
+            // queue check above is the only thing that stops an edit, which
+            // is the whole reason this is not folded into `retarget`.
+            return { ok: true };
+        case "propose-stack":
+            return capabilities.proposeStack
+                ? { ok: true }
+                : {
+                    ok: false,
+                    reason: `The ${providerId} provider proposes one change at a time.`,
+                    instead: "Propose each change in the stack in dependency order, roots first.",
+                };
+        case "retarget":
+            return retargetable(capabilities, providerId);
+        case "set-draft":
+            return capabilities.setDraft
+                ? { ok: true }
+                : {
+                    ok: false,
+                    reason: `The ${providerId} provider cannot move an existing change between draft and ready.`,
+                    instead: "Decide draft or ready when the change is proposed, since this backend fixes it then.",
+                };
+        case "reopen":
+            return capabilities.reopen
+                ? { ok: true }
+                : {
+                    ok: false,
+                    reason: `The ${providerId} provider cannot reopen a closed change.`,
+                    instead: "Propose the work again as a new change.",
+                };
+        case "close":
+            return capabilities.close
+                ? { ok: true }
+                : {
+                    ok: false,
+                    reason: `The ${providerId} provider cannot close a change.`,
+                };
+        case "merge":
+            return capabilities.merge
+                ? { ok: true }
+                : {
+                    ok: false,
+                    reason: `The ${providerId} provider cannot merge a change.`,
+                };
+        case "request-reviewers":
+            return reviewable(capabilities, providerId);
+        case "rerun-checks":
+            return capabilities.rerunChecks
+                ? { ok: true }
+                : {
+                    ok: false,
+                    reason: `The ${providerId} provider cannot ask CI to run again.`,
+                    instead: "Retrigger it wherever that backend's CI is driven from, which is not always the same system that hosts the change.",
+                };
+    }
+}
+/** Proposing, and whether reviewers can ride along. */
+function proposable(intent, capabilities, providerId) {
+    if (!capabilities.propose) {
+        return {
+            ok: false,
+            reason: `The ${providerId} provider cannot propose a change.`,
+        };
+    }
+    if (intent.withReviewers === true && capabilities.reviewersAt === "never") {
+        return {
+            ok: false,
+            reason: `The ${providerId} provider has no notion of requested reviewers.`,
+            instead: "Propose the change, then ask people to look at it yourself.",
+        };
+    }
+    return { ok: true };
+}
+/** Retargeting, which is not the same operation on every backend. */
+function retargetable(capabilities, providerId) {
+    if (capabilities.retarget === "change")
+        return { ok: true };
+    if (capabilities.retarget === "stack") {
+        return {
+            ok: false,
+            reason: `On ${providerId} a change's base is not set on the change. Retargeting is a stack operation there, so moving one change means resubmitting the stack it sits in.`,
+            instead: "Restack locally so the change sits on the base you want, then submit the stack.",
+        };
+    }
+    return {
+        ok: false,
+        reason: `The ${providerId} provider cannot change what a proposal targets.`,
+        instead: "Close this change and propose it again against the base you want.",
+    };
+}
+/** Requesting reviewers after the fact, which one backend will not do. */
+function reviewable(capabilities, providerId) {
+    if (capabilities.reviewersAt === "any-time")
+        return { ok: true };
+    if (capabilities.reviewersAt === "creation") {
+        return {
+            ok: false,
+            reason: `The ${providerId} provider takes reviewers only as a change is created.`,
+            instead: "Name the reviewers when proposing. On an existing change, ask them directly instead.",
+        };
+    }
+    return {
+        ok: false,
+        reason: `The ${providerId} provider has no notion of requested reviewers.`,
+        instead: "Ask people to look at it yourself.",
+    };
+}