@jitsusama/agentic-harness.core 0.1.0

package/dist/review/engine.d.ts

@@ -0,0 +1,106 @@
+/**
+ * The layer consumers actually talk to.
+ *
+ * Everything below this is deliberately separate: a model, a
+ * provider contract, a resolver, a draft. That separation is
+ * what makes each piece testable, but a consumer should not
+ * have to assemble them. So the engine does it: hand it a
+ * reference or a checkout, get back something that knows its
+ * own provider, capabilities, diff and stack, and can open a
+ * draft about itself.
+ */
+import type { Exec } from "../exec/index.js";
+import type { Capabilities } from "./capabilities.js";
+import type { ChangeRef, Proposal, RepoLocator, ReviewTarget } from "./change.js";
+import type { ChecksRollup } from "./checks.js";
+import type { ReviewConfig } from "./config.js";
+import type { DiffModel } from "./diff.js";
+import type { DraftDeps, ReviewDraft } from "./draft/handle.js";
+import type { DraftStore } from "./draft/store.js";
+import type { ConversationFacet, RepoProbe, ReviewProvider } from "./provider.js";
+import type { ResolvedVia } from "./resolve.js";
+import type { Stack } from "./stack.js";
+/** What the engine needs to work. */
+export interface ReviewEngineDeps {
+    exec: Exec;
+    store: DraftStore;
+    /** The user's `review` config section, when there is one. */
+    config?: ReviewConfig;
+}
+/** Which local refs to review. */
+export type LocalSpec = {
+    base: string;
+    head: string;
+} | {
+    refs: string[];
+};
+/** A target with its provider and everything reachable from it. */
+export interface BoundTarget {
+    target: ReviewTarget;
+    provider: ReviewProvider;
+    repo: RepoLocator;
+    /**
+     * How this provider came to own the target.
+     *
+     * Carried because a failure reads completely differently depending on
+     * the answer. A reference resolved by claim landed on a provider that
+     * recognized its shape, and a shape like `owner/repo#n` belongs to no
+     * system in particular, so a not-found is as likely to mean the wrong
+     * system as a missing change. Resolved by config, the same not-found
+     * means what it says, and suggesting a pin would be noise about a pin
+     * that already decided.
+     */
+    via: ResolvedVia;
+    capabilities: Capabilities;
+    /** The hosted change, when the target is one. */
+    proposal(): Promise<Proposal | null>;
+    /** Unified diff, from the provider or from local git. */
+    diff(): Promise<string>;
+    /** The same diff, parsed. */
+    diffModel(): Promise<DiffModel>;
+    /** The stack, when the provider can read one. */
+    stack(): Promise<Stack | null>;
+    /** CI state, when the provider reports it. */
+    checks(): Promise<ChecksRollup | null>;
+    /** The conversation, or null when nothing hosts this target. */
+    conversation: ConversationFacet | null;
+}
+/** A checkout's provider, and what it can do here. */
+export interface ServingRepo {
+    provider: ReviewProvider;
+    repo: RepoLocator;
+    via: ResolvedVia;
+    capabilities: Capabilities;
+}
+/** The substrate, assembled. */
+export interface ReviewEngine {
+    /** What a directory says about the repo it sits in. */
+    probe(cwd: string): Promise<RepoProbe>;
+    /** Resolve a reference, throwing the resolver's guidance. */
+    resolve(input: string, cwd?: string): Promise<BoundTarget>;
+    /**
+     * Bind a change whose system is already known.
+     *
+     * For a caller that resolved once and kept the answer. Going
+     * back through {@link resolve} would ask every provider to
+     * claim the name again, and claiming depends on the directory
+     * the question is asked from, so the same change can bind to a
+     * different system on a later call. That is exactly how a
+     * review reaches a mirror instead of the system of record.
+     */
+    bound(change: ChangeRef): Promise<BoundTarget>;
+    /** Review refs in a checkout, hosted or not. */
+    fromLocal(repoRoot: string, spec: LocalSpec): Promise<BoundTarget>;
+    /**
+     * Who serves this checkout, with nothing to review yet.
+     *
+     * For "what can be done here", which is asked before there is a change
+     * to ask it about. {@link fromLocal} needs refs, so answering through it
+     * meant inventing a base and a head nobody named.
+     */
+    serving(cwd: string): Promise<ServingRepo>;
+    openDraft(target: ReviewTarget): Promise<ReviewDraft>;
+}
+/** Build the engine. */
+export declare function createReviewEngine(deps: ReviewEngineDeps): ReviewEngine;
+export type { DraftDeps };

package/dist/review/engine.js

@@ -0,0 +1,243 @@
+/**
+ * The layer consumers actually talk to.
+ *
+ * Everything below this is deliberately separate: a model, a
+ * provider contract, a resolver, a draft. That separation is
+ * what makes each piece testable, but a consumer should not
+ * have to assemble them. So the engine does it: hand it a
+ * reference or a checkout, get back something that knows its
+ * own provider, capabilities, diff and stack, and can open a
+ * draft about itself.
+ */
+import { run } from "../exec/index.js";
+import { resolveRepo, resolveTarget } from "./bind.js";
+import { parseUnifiedDiff } from "./diff.js";
+import { openDraft } from "./draft/handle.js";
+import { getReviewProvider } from "./register.js";
+import { resolveReference } from "./resolve.js";
+/** The two endpoints of whatever the target covers. */
+function endpointsOf(target) {
+    if (target.kind === "range") {
+        return { base: target.base, head: target.head };
+    }
+    if (target.kind === "stack") {
+        // A stack's diff is everything from below its first ref to
+        // the tip of its last.
+        return {
+            base: target.refs[0] ?? "HEAD",
+            head: target.refs.at(-1) ?? "HEAD",
+        };
+    }
+    throw new Error("a hosted change has no local endpoints");
+}
+/**
+ * The provider a change names, or a refusal that names it back.
+ *
+ * A change carrying a system nobody registered almost always
+ * means an extension did not load, and saying which system is
+ * missing is what points at it.
+ */
+function providerFor(id) {
+    const provider = getReviewProvider(id);
+    if (!provider) {
+        throw new Error(`This change belongs to ${id}, and no ${id} provider is registered, so it cannot be reached. The extension that contributes it may not be loaded.`);
+    }
+    return provider;
+}
+/** Build the engine. */
+export function createReviewEngine(deps) {
+    const draftDeps = { store: deps.store };
+    async function probe(cwd) {
+        const top = await deps.exec("git", [
+            "-C",
+            cwd,
+            "rev-parse",
+            "--show-toplevel",
+        ]);
+        // Not being in a repo is an ordinary answer, not a failure:
+        // a reference can still be a URL.
+        if (top.code !== 0)
+            return {};
+        const repoRoot = top.stdout.trim();
+        const remotes = await deps.exec("git", [
+            "-C",
+            repoRoot,
+            "config",
+            "--get-regexp",
+            "^remote\\..*\\.url$",
+        ]);
+        const remoteUrls = remotes.code === 0
+            ? remotes.stdout
+                .split("\n")
+                .map((line) => line.trim().split(/\s+/)[1])
+                .filter((url) => Boolean(url))
+            : [];
+        return { repoRoot, remoteUrls };
+    }
+    /** Wrap a resolved target in everything reachable from it. */
+    function bind(target, provider, repo, via) {
+        let diffText;
+        async function readDiff() {
+            if (target.kind === "proposal") {
+                if (!provider.proposals) {
+                    throw new Error(`the ${provider.id} provider cannot read a diff`);
+                }
+                try {
+                    return await provider.proposals.diff(target.change);
+                }
+                catch (error) {
+                    // A big change is the case a diff is most wanted for and the one
+                    // that failed hardest: a backend that caps its own diff route
+                    // answered with a raw upstream refusal and the read was over,
+                    // while the same provider offered `fetchAsRef` for exactly this
+                    // and nothing reached for it. Bringing the commits down and
+                    // diffing them locally has no such cap.
+                    return await diffFromRef(target.change, error);
+                }
+            }
+            const root = repo.localPath ?? target.repo.localPath;
+            if (!root) {
+                throw new Error(`${repo.key} has no local checkout to diff`);
+            }
+            const { base, head } = endpointsOf(target);
+            return run(deps.exec, "git", ["-C", root, "diff", `${base}...${head}`], `diffing ${base}...${head}`);
+        }
+        /**
+         * The diff read from a ref the provider fetched, when its own route
+         * would not answer.
+         *
+         * The original failure is carried into anything said here, because the
+         * fallback can fail for reasons of its own and being told only about
+         * the second one sends somebody after the wrong problem.
+         */
+        async function diffFromRef(change, cause) {
+            const why = cause instanceof Error ? cause.message : String(cause);
+            const fetchAsRef = provider.proposals?.fetchAsRef;
+            const root = repo.localPath ?? change.repo.localPath;
+            if (!fetchAsRef || !root) {
+                throw new Error(`${why}\n\nThe ${provider.id} provider ${fetchAsRef ? `has no local checkout of ${repo.key} to read ${change.label} into` : "cannot fetch a change as a ref"}, so there is no way around that. Read the change a file at a time instead.`);
+            }
+            const head = await fetchAsRef(change, root);
+            // The base is not fetched with it, and the diff is against the base.
+            // Asking the provider what the base is costs one read and beats
+            // guessing at a default branch name.
+            const base = (await provider.proposals?.fetch(change))?.base;
+            if (base === undefined) {
+                throw new Error(`${why}\n\n${change.label} was fetched to ${head}, but the ${provider.id} provider did not say what it is based on, so there is nothing to diff it against.`);
+            }
+            const read = await deps.exec("git", [
+                "-C",
+                root,
+                "diff",
+                `${base}...${head}`,
+            ]);
+            if (read.code !== 0) {
+                // Both causes, because the fallback fails for its own reasons and
+                // hearing only the second sends somebody after the wrong problem.
+                // The usual one is a checkout that has never seen the base.
+                throw new Error(`${why}\n\nReading it from a fetched ref instead did not work either: diffing ${base}...${head} in ${root} said ${read.stderr.trim() || `exit ${read.code}`}. Fetch ${base} into that checkout and try again.`);
+            }
+            return read.stdout;
+        }
+        function diff() {
+            // One read per bound target: a diff is asked for by the
+            // council, the planner and the renderer in turn.
+            diffText ??= readDiff();
+            return diffText;
+        }
+        return {
+            target,
+            provider,
+            repo,
+            via,
+            capabilities: provider.capabilities(repo),
+            conversation: target.kind === "proposal" ? (provider.conversation ?? null) : null,
+            async proposal() {
+                if (target.kind !== "proposal" || !provider.proposals)
+                    return null;
+                return provider.proposals.fetch(target.change);
+            },
+            diff,
+            async diffModel() {
+                return parseUnifiedDiff(await diff());
+            },
+            async stack() {
+                if (!provider.stacking)
+                    return null;
+                if (target.kind === "proposal") {
+                    return provider.stacking.stack(target.change);
+                }
+                const { head } = endpointsOf(target);
+                return provider.stacking.stack({ repo, ref: head });
+            },
+            async checks() {
+                if (target.kind !== "proposal" || !provider.proposals?.checks) {
+                    return null;
+                }
+                return provider.proposals.checks(target.change);
+            },
+        };
+    }
+    /** Resolve a target to its provider, throwing the guidance. */
+    function bindTargetOrThrow(target, context) {
+        const resolved = resolveTarget(target, {
+            ...(deps.config ? { config: deps.config } : {}),
+            ...(context.probe ? { probe: context.probe } : {}),
+        });
+        if (!resolved.resolved)
+            throw new Error(resolved.message);
+        return bind(target, resolved.provider, resolved.repo, resolved.via);
+    }
+    return {
+        probe,
+        async resolve(input, cwd) {
+            const probed = cwd ? await probe(cwd) : undefined;
+            const resolution = resolveReference(input, {
+                ...(deps.config ? { config: deps.config } : {}),
+                ...(probed ? { probe: probed } : {}),
+            });
+            if (!resolution.resolved)
+                throw new Error(resolution.message);
+            const target = {
+                kind: "proposal",
+                change: resolution.change,
+            };
+            return bind(target, resolution.provider, resolution.change.repo, resolution.via);
+        },
+        async bound(change) {
+            // A change kept from an earlier resolution names its own provider,
+            // which is the whole reason this path exists rather than asking
+            // again. Nothing was claimed here, so nothing about claiming is
+            // true of it: it resolved the way a pin does, by being told.
+            return bind({ kind: "proposal", change }, providerFor(change.provider), change.repo, "config-repo");
+        },
+        async serving(cwd) {
+            const probed = await probe(cwd);
+            const resolved = resolveRepo(probed, {
+                ...(deps.config ? { config: deps.config } : {}),
+            });
+            if (!resolved.resolved)
+                throw new Error(resolved.message);
+            return {
+                provider: resolved.provider,
+                repo: resolved.repo,
+                via: resolved.via,
+                capabilities: resolved.provider.capabilities(resolved.repo),
+            };
+        },
+        async fromLocal(repoRoot, spec) {
+            const probed = await probe(repoRoot);
+            const repo = {
+                key: `local:${probed.repoRoot ?? repoRoot}`,
+                localPath: probed.repoRoot ?? repoRoot,
+            };
+            const target = "refs" in spec
+                ? { kind: "stack", repo, refs: spec.refs }
+                : { kind: "range", repo, base: spec.base, head: spec.head };
+            return bindTargetOrThrow(target, { probe: probed });
+        },
+        openDraft: (target) => openDraft(target, draftDeps),
+    };
+}
+/** Kept so the stub compiles against its imports. */
+void [openDraft, parseUnifiedDiff, resolveReference, resolveTarget, run];

package/dist/review/events.d.ts

@@ -0,0 +1,59 @@
+/**
+ * The bus contract between the substrate and its providers.
+ *
+ * A provider registers over the event bus rather than by
+ * importing the registry, so a provider can live in a
+ * different package from the host without either one
+ * depending on the other's module graph. The names are
+ * versioned because the payload is a public contract; a
+ * breaking change ships as `:v2` beside the old one rather
+ * than quietly changing what `:v1` means.
+ *
+ * Both directions of the handshake matter. The host emits
+ * `REVIEW_READY` when its registry is live, and a provider
+ * listens for it so it can re-register after the host
+ * reloads. A provider also emits `REVIEW_REGISTER_PROVIDER`
+ * on its own activation, in case the host was already up.
+ * Either order works, and both are idempotent.
+ *
+ * A consumer needs the same courtesy for the opposite reason.
+ * The bus does not replay, so a consumer that activated after
+ * the host missed the announcement and has no way to know it
+ * happened. `REVIEW_REQUEST_SUBSTRATE` is how it asks; the host
+ * answers by announcing itself again. Load order therefore
+ * decides nothing, which is the point: an extension cannot
+ * choose when it is loaded relative to another.
+ */
+import type { ReviewEngine } from "./engine.js";
+import type { ReviewProvider } from "./provider.js";
+/** Emitted by the host once its registry accepts providers. */
+export declare const REVIEW_READY = "review:ready:v1";
+/** Emitted by a provider to register itself with the host. */
+export declare const REVIEW_REGISTER_PROVIDER = "review:provider:register:v1";
+/**
+ * Emitted by a consumer asking the host to announce itself, for
+ * when the consumer loaded second and missed {@link REVIEW_READY}.
+ */
+export declare const REVIEW_REQUEST_SUBSTRATE = "review:request:v1";
+/** What the host hands out over {@link REVIEW_READY}. */
+export interface ReviewSubstrateApi {
+    /** Register a provider. Replaces one with the same id. */
+    registerProvider(provider: ReviewProvider): void;
+    /** Ids of every registered provider, in claim order. */
+    listProviders(): readonly string[];
+    /**
+     * The host's own engine.
+     *
+     * Shared rather than rebuilt, so a consumer resolves against
+     * the same registry the host announced. A consumer with its
+     * own engine would see only the providers it registered
+     * itself, which means a provider that arrived over the bus
+     * would be invisible to it: exactly the case this contract
+     * exists to serve.
+     *
+     * Asked for rather than handed over, because building it
+     * means reading configuration from disk, and the
+     * announcement cannot wait on that.
+     */
+    engine(): Promise<ReviewEngine>;
+}

package/dist/review/events.js

@@ -0,0 +1,35 @@
+/**
+ * The bus contract between the substrate and its providers.
+ *
+ * A provider registers over the event bus rather than by
+ * importing the registry, so a provider can live in a
+ * different package from the host without either one
+ * depending on the other's module graph. The names are
+ * versioned because the payload is a public contract; a
+ * breaking change ships as `:v2` beside the old one rather
+ * than quietly changing what `:v1` means.
+ *
+ * Both directions of the handshake matter. The host emits
+ * `REVIEW_READY` when its registry is live, and a provider
+ * listens for it so it can re-register after the host
+ * reloads. A provider also emits `REVIEW_REGISTER_PROVIDER`
+ * on its own activation, in case the host was already up.
+ * Either order works, and both are idempotent.
+ *
+ * A consumer needs the same courtesy for the opposite reason.
+ * The bus does not replay, so a consumer that activated after
+ * the host missed the announcement and has no way to know it
+ * happened. `REVIEW_REQUEST_SUBSTRATE` is how it asks; the host
+ * answers by announcing itself again. Load order therefore
+ * decides nothing, which is the point: an extension cannot
+ * choose when it is loaded relative to another.
+ */
+/** Emitted by the host once its registry accepts providers. */
+export const REVIEW_READY = "review:ready:v1";
+/** Emitted by a provider to register itself with the host. */
+export const REVIEW_REGISTER_PROVIDER = "review:provider:register:v1";
+/**
+ * Emitted by a consumer asking the host to announce itself, for
+ * when the consumer loaded second and missed {@link REVIEW_READY}.
+ */
+export const REVIEW_REQUEST_SUBSTRATE = "review:request:v1";

package/dist/review/failed.d.ts

@@ -0,0 +1,46 @@
+/**
+ * What a failure against a hosted change should say.
+ *
+ * A provider's own error is about its own request, which is the right thing
+ * for it to report and not enough to act on. `gh: Not Found (HTTP 404)` is the
+ * example that prompted this: it named neither the change, nor the provider
+ * asked for it, nor the one setting that decides which provider gets asked.
+ *
+ * The missing fact is how the provider came to own the reference. A shape like
+ * `owner/repo#n` belongs to no system in particular, so a reference resolved
+ * by claim landed on whichever provider recognized the shape first, and a
+ * not-found there is as likely to mean the wrong system as a missing change.
+ * Resolved from config, the same not-found means what it says.
+ */
+import type { RepoLocator } from "./change.js";
+import type { ResolvedVia } from "./resolve.js";
+/** Just enough of a bound target to explain a failure against it. */
+export interface FailureContext {
+    provider: {
+        id: string;
+    };
+    repo: RepoLocator;
+    via: ResolvedVia;
+}
+/**
+ * True when a message reads like the system was asked about something it does
+ * not have.
+ *
+ * Deliberately narrow. A 422 is the backend understanding the request and
+ * rejecting its contents, which is a real answer about a real change, and
+ * decorating it with "you may be on the wrong system" would be wrong and
+ * would train a reader to skip the decoration when it counts.
+ */
+export declare function readsAsMissing(message: string): boolean;
+/**
+ * A failure message with the context needed to act on it.
+ *
+ * Takes the message as thrown rather than composing one, since whatever threw
+ * already said what it was attempting, and a second prefix in front of that
+ * reads like two failures.
+ *
+ * Adds nothing when the failure is not a not-found, and nothing when config
+ * already decided the provider, since a pin cannot be the advice when a pin
+ * is what got us here.
+ */
+export declare function explainFailure(message: string, context: FailureContext): string;

package/dist/review/failed.js

@@ -0,0 +1,56 @@
+/**
+ * What a failure against a hosted change should say.
+ *
+ * A provider's own error is about its own request, which is the right thing
+ * for it to report and not enough to act on. `gh: Not Found (HTTP 404)` is the
+ * example that prompted this: it named neither the change, nor the provider
+ * asked for it, nor the one setting that decides which provider gets asked.
+ *
+ * The missing fact is how the provider came to own the reference. A shape like
+ * `owner/repo#n` belongs to no system in particular, so a reference resolved
+ * by claim landed on whichever provider recognized the shape first, and a
+ * not-found there is as likely to mean the wrong system as a missing change.
+ * Resolved from config, the same not-found means what it says.
+ */
+/**
+ * True when a message reads like the system was asked about something it does
+ * not have.
+ *
+ * Deliberately narrow. A 422 is the backend understanding the request and
+ * rejecting its contents, which is a real answer about a real change, and
+ * decorating it with "you may be on the wrong system" would be wrong and
+ * would train a reader to skip the decoration when it counts.
+ */
+export function readsAsMissing(message) {
+    const lowered = message.toLowerCase();
+    return (lowered.includes("not found") ||
+        lowered.includes("404") ||
+        lowered.includes("could not resolve to") ||
+        lowered.includes("no such"));
+}
+/**
+ * A failure message with the context needed to act on it.
+ *
+ * Takes the message as thrown rather than composing one, since whatever threw
+ * already said what it was attempting, and a second prefix in front of that
+ * reads like two failures.
+ *
+ * Adds nothing when the failure is not a not-found, and nothing when config
+ * already decided the provider, since a pin cannot be the advice when a pin
+ * is what got us here.
+ */
+export function explainFailure(message, context) {
+    const stated = message;
+    if (!readsAsMissing(message))
+        return stated;
+    if (context.via !== "claim")
+        return stated;
+    const owned = context.repo.key.split(":").slice(1).join(":");
+    const named = owned === "" ? context.repo.key : owned;
+    return [
+        stated,
+        "",
+        `The ${context.provider.id} provider was asked, because it recognized the shape of that reference rather than because anything said ${named} is served there.`,
+        `If another system serves ${named}, pin it under review.repos, or name the change by its url.`,
+    ].join("\n");
+}

package/dist/review/finding.d.ts

@@ -0,0 +1,81 @@
+/**
+ * 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 type { Anchor } from "./anchor.js";
+import type { ChangeRef } from "./change.js";
+/**
+ * Conventional Comments labels, which say what kind of remark
+ * this is before it says anything else.
+ */
+export type ConventionalLabel = "praise" | "nitpick" | "suggestion" | "issue" | "todo" | "question" | "thought" | "chore" | "note";
+/** How much it matters, when whatever raised it says. */
+export type FindingSeverity = "critical" | "medium" | "minor";
+/**
+ * Where a finding came from.
+ *
+ * No forge appears here, and none should: this says which pass of
+ * which run raised the thing, which is a fact about the reviewing
+ * rather than about what hosts the change. A finding somebody
+ * typed is `hand`, and it is deliberately not called `user`,
+ * since the agent writing one by hand is the same act.
+ */
+export type FindingOrigin = {
+    kind: "hand";
+} | {
+    kind: "reviewer";
+    runId: string;
+    reviewerId: string;
+} | {
+    kind: "judge";
+    runId: string;
+    reviewerId: string;
+};
+/** One observation about a change. */
+export interface Finding {
+    /**
+     * Stable within a change, climbing and never reused, because
+     * people refer to findings by number out loud and a number
+     * that gets recycled makes a conversation wrong later.
+     */
+    id: number;
+    /** Where it points, witness and all. */
+    anchor: Anchor;
+    label: ConventionalLabel;
+    /** The one-line claim. */
+    subject: string;
+    /** The argument for it. */
+    discussion: string;
+    origin: FindingOrigin;
+    severity?: FindingSeverity;
+    /** How sure the producer was, where it says. */
+    confidence?: number;
+    /**
+     * Reviewer ids that raised the same thing, set when a pass
+     * consolidates several into one. Agreement is evidence, so it
+     * is worth keeping rather than collapsing.
+     */
+    raisedBy?: string[];
+}
+/** Findings held per change, outliving whatever produced them. */
+export interface FindingStore {
+    /** Add findings to a change, numbering them as they land. */
+    record(change: ChangeRef, findings: Omit<Finding, "id">[]): Promise<Finding[]>;
+    /** Every finding on a change, in the order they were raised. */
+    list(change: ChangeRef): Promise<Finding[]>;
+    /** Forget a change's findings, without rewinding its numbering. */
+    clear(change: ChangeRef): Promise<void>;
+}
+/** Findings on disk, one file per change. */
+export declare function createFindingStore(root: string): FindingStore;