@jitsusama/agentic-harness.core 0.1.0

package/dist/review/provider.d.ts

@@ -0,0 +1,306 @@
+/**
+ * The provider contract: facets, not one interface.
+ *
+ * A monolithic interface would force every backend to
+ * pretend. A bare git repo has stack topology and diffs and
+ * no conversation anywhere; a forge has all of it. Rather
+ * than have the repo throw from half its methods, a provider
+ * implements the facets it has and consumers ask before they
+ * reach.
+ *
+ * Claiming is separate from doing. Every registered provider
+ * gets a look at a reference or a repo and says whether it
+ * recognizes it, so adding a backend never means editing a
+ * resolver.
+ */
+import type { Anchor } from "./anchor.js";
+import type { Capabilities } from "./capabilities.js";
+import type { Actor, ChangeRef, ChangeState, Proposal, RepoLocator } from "./change.js";
+import type { ChecksRollup, RerunOutcome } from "./checks.js";
+import type { Message, Posted, Reaction, Review, Thread, WireReview } from "./conversation.js";
+import type { Stack } from "./stack.js";
+/** What a provider is shown when asked to claim a repo. */
+export interface RepoProbe {
+    /** Absolute path to a local checkout, when there is one. */
+    repoRoot?: string;
+    /** Remote URLs configured in that checkout. */
+    remoteUrls?: string[];
+}
+/** Which changes to list. */
+export interface ChangeFilter {
+    state?: ChangeState;
+    /** Provider-scoped actor id. */
+    author?: string;
+    base?: string;
+    head?: string;
+    limit?: number;
+}
+/** Reading hosted changes. */
+export interface ProposalsFacet {
+    fetch(ref: ChangeRef): Promise<Proposal>;
+    /** Unified diff in git's dialect. */
+    diff(ref: ChangeRef): Promise<string>;
+    checks?(ref: ChangeRef): Promise<ChecksRollup>;
+    list?(repo: RepoLocator, filter: ChangeFilter): Promise<Proposal[]>;
+    /**
+     * Materialize the change's commits in a local repo and
+     * return the ref they landed on. This is what lets a
+     * consumer diff, blame or check out a change without
+     * knowing which backend hosts it.
+     */
+    fetchAsRef?(ref: ChangeRef, repoRoot: string): Promise<string>;
+    /**
+     * One file's contents at a commit.
+     *
+     * For showing a person a whole file when the diff only carries
+     * the lines that changed. It belongs to the provider because
+     * the answer has to come from the system hosting the change: a
+     * repository can be mirrored, and reading the mirror returns
+     * content that is plausible and stale.
+     *
+     * Absent where a provider has no way to serve a file it does
+     * not have locally.
+     */
+    fileAt?(ref: ChangeRef, path: string, at: string): Promise<string>;
+}
+/** A local ref, for providers that read stacks off disk. */
+export interface LocalBranch {
+    repo: RepoLocator;
+    ref: string;
+}
+/** Reading stack topology. */
+export interface StackingFacet {
+    /**
+     * The stack containing this ref or change, with its
+     * provenance marked. Partial answers are expected: a
+     * provider reports what it can see rather than failing.
+     */
+    stack(subject: ChangeRef | LocalBranch): Promise<Stack>;
+    /**
+     * Point every change in the stack back at what it now sits on.
+     *
+     * Optional, and its absence is not a gap. A backend with no notion
+     * of a stack has nothing to implement here, and the substrate moves
+     * each change in turn through {@link AuthoringFacet.edit} instead,
+     * which is the whole operation on such a backend rather than a
+     * degraded form of it.
+     *
+     * Implement it where the backend holds the stack itself, since
+     * moving one change without the others would leave the backend's
+     * own model inconsistent, and a walk that stops half way would
+     * leave it inconsistent and say it succeeded partly.
+     */
+    restack?(subject: ChangeRef | LocalBranch): Promise<Stack>;
+}
+/** Reading and writing the conversation on a change. */
+export interface ConversationFacet {
+    reviews(ref: ChangeRef): Promise<Review[]>;
+    threads(ref: ChangeRef): Promise<Thread[]>;
+    messages(ref: ChangeRef): Promise<Message[]>;
+    postReview(ref: ChangeRef, review: WireReview): Promise<Posted>;
+    /**
+     * Reply into a thread. Takes the whole thread because the
+     * backends key a reply differently: one by the thread,
+     * one by the comment that started it.
+     */
+    reply(ref: ChangeRef, thread: Thread, body: string): Promise<Posted>;
+    resolve(ref: ChangeRef, thread: Thread): Promise<void>;
+    unresolve?(ref: ChangeRef, thread: Thread): Promise<void>;
+    /** A remark about the change as a whole. */
+    comment(ref: ChangeRef, body: string): Promise<Posted>;
+    /** A standalone anchored remark, outside any review. */
+    commentOn?(ref: ChangeRef, anchor: Anchor, body: string): Promise<Posted>;
+    react?(ref: ChangeRef, subject: Message, reaction: Reaction): Promise<void>;
+    unreact?(ref: ChangeRef, subject: Message, reaction: Reaction): Promise<void>;
+    /**
+     * Who the calling principal is, as this backend names them.
+     *
+     * Needed for any question about your own remarks: which threads are mine,
+     * whether my findings were answered, whether I have already reviewed this.
+     * Every one of those is unanswerable without it, and the tempting
+     * alternatives are worse than a refusal. Matching a display name matches
+     * the wrong person eventually; taking the most recent reviewer assumes the
+     * caller is whoever spoke last.
+     *
+     * Optional because a backend may genuinely not say. A caller that cannot
+     * learn who it is should refuse the question rather than answer it about
+     * somebody else.
+     */
+    viewer?(repo: RepoLocator): Promise<Actor>;
+}
+/** A field being changed, where clearing differs from leaving. */
+export type FieldEdit<T> = {
+    action: "set";
+    value: T;
+} | {
+    action: "clear";
+};
+/**
+ * A set being changed, where adding differs from replacing.
+ *
+ * Labels and assignees need more than {@link FieldEdit} offers. Adding
+ * one label through a wholesale `set` means reading the current list
+ * first and writing it back, which loses whatever somebody else added in
+ * between, and that race is precisely what a busy change is full of.
+ *
+ * The backends express these natively: `gh pr edit` takes `--add-label`
+ * and `--remove-label` beside `--label`. A provider whose backend can
+ * only replace implements `add` by reading first, which is its business
+ * rather than the contract's.
+ */
+export type SetEdit<T> = {
+    action: "set";
+    value: T[];
+} | {
+    action: "add";
+    value: T[];
+} | {
+    action: "remove";
+    value: T[];
+} | {
+    action: "clear";
+};
+/** What to change about a proposal. */
+export interface ProposalEdit {
+    title?: FieldEdit<string>;
+    body?: FieldEdit<string>;
+    base?: FieldEdit<string>;
+    /** Labels, named as the backend names them. */
+    labels?: SetEdit<string>;
+    /**
+     * Assignees, named as the backend names people. GitHub wants logins
+     * and Meteorite wants Shopify email addresses, which is why this is
+     * a string rather than an {@link Actor}: the caller is passing the
+     * backend's own identifier through, not a resolved person.
+     */
+    assignees?: SetEdit<string>;
+}
+/** What to propose. */
+export interface ProposalDraft {
+    repo: RepoLocator;
+    base: string;
+    head: string;
+    title: string;
+    body: string;
+    /**
+     * Whether it opens as a draft. Required, deliberately.
+     *
+     * The backends disagree about what silence means: one defaults a new
+     * change to ready and another defaults it to draft. An optional flag
+     * would make the same call produce a live change on one and an
+     * invisible one on the other, and the caller who gets it wrong finds
+     * out either from a surprised reviewer or from a change nobody ever
+     * looked at. Saying so every time costs a word.
+     */
+    draft: boolean;
+    /** Labels to open it with, where the backend has labels. */
+    labels?: string[];
+    /** Assignees to open it with, in the backend's own naming. */
+    assignees?: string[];
+    /**
+     * Reviewers to open it with, for a backend that takes them only then.
+     *
+     * Without this, `reviewersAt: "creation"` was a value nothing could
+     * honour. It says the backend takes reviewers as the change is made, and
+     * the only route the contract offered was `requestReviewers` afterwards,
+     * which is precisely what such a backend cannot do. So a caller naming
+     * reviewers on a creation-only provider had them silently dropped, or
+     * asked for them after the one moment they could be given.
+     *
+     * A provider declaring `"any-time"` may ignore this and be asked through
+     * `requestReviewers` instead. One declaring `"creation"` reads them here.
+     */
+    reviewers?: string[];
+}
+/** How a change should be integrated. */
+export interface MergeRequest {
+    /**
+     * Strategy, in the provider's vocabulary. Omitted when
+     * the provider offers only one, which one of them does.
+     */
+    method?: string;
+    /**
+     * Refuse unless the head is still this commit. Every
+     * backend surveyed supports the guard and it is the only
+     * protection against merging work you have not seen.
+     */
+    expectedHead?: string;
+}
+/**
+ * What a merge call actually did.
+ *
+ * Merging used to return nothing, so the only thing a caller could say was that it had
+ * asked. On a backend that merges when asked, saying `merged` is true. On one fronted by
+ * a queue it is a lie with consequences: the change has been accepted for a batch that
+ * may still fail CI and never land, and a caller told `merged` goes on to prune the
+ * branch and report the work done. The same call, the same success, two different facts.
+ *
+ * A refusal is not a case here. Refusing to merge is decided before the call, by the
+ * objection path, so what reaches this point has been accepted and the only open question
+ * is what acceptance meant.
+ */
+export type MergeOutcome = 
+/** In the base branch now. The commit when the backend named one. */
+{
+    kind: "merged";
+    commit?: string;
+}
+/** Accepted by a queue. It lands later, or it fails CI and does not. */
+ | {
+    kind: "enqueued";
+    detail?: string;
+};
+/**
+ * Creating and changing proposals.
+ *
+ * Typed now, implemented later. The shapes are here so the
+ * authoring flows have a home and nothing in the reviewing
+ * half gets designed into a corner that authoring cannot fit
+ * through.
+ */
+export interface AuthoringFacet {
+    propose(draft: ProposalDraft): Promise<Proposal>;
+    /** Propose a whole stack in dependency order. */
+    proposeStack?(drafts: ProposalDraft[]): Promise<Proposal[]>;
+    edit(ref: ChangeRef, edit: ProposalEdit): Promise<Proposal>;
+    setDraft?(ref: ChangeRef, draft: boolean): Promise<void>;
+    close(ref: ChangeRef, comment?: string): Promise<void>;
+    reopen?(ref: ChangeRef): Promise<void>;
+    merge(ref: ChangeRef, request: MergeRequest): Promise<MergeOutcome>;
+    requestReviewers?(ref: ChangeRef, actors: string[]): Promise<void>;
+    /**
+     * Ask CI to run again, optionally naming one pipeline.
+     *
+     * A write, which is why it is here and not beside `checks`, and
+     * what runs is the backend's business. The contract says only
+     * that somebody was asked and, through `RerunOutcome`, whether
+     * they agreed.
+     */
+    rerun?(ref: ChangeRef, which?: string): Promise<RerunOutcome>;
+}
+/** A backend the substrate can review through. */
+export interface ReviewProvider {
+    /** Stable id, e.g. `github`, `meteorite`, `git`. */
+    id: string;
+    /**
+     * Claim priority. Lower numbers are asked first, so a
+     * specialist can out-claim a generalist: during a mirror
+     * migration the new backend must win the repo the old one
+     * still recognizes.
+     */
+    priority: number;
+    /**
+     * Recognize a reference: a URL, a short form, a bare
+     * number, a branch. Returns null when it means nothing to
+     * this provider. Cheap and synchronous.
+     */
+    claimReference(input: string, repo?: RepoLocator): ChangeRef | null;
+    /** Recognize a repo from a checkout or its remotes. */
+    claimRepo(probe: RepoProbe): RepoLocator | null;
+    /** What this provider can do for this repo. */
+    capabilities(repo: RepoLocator): Capabilities;
+    proposals?: ProposalsFacet;
+    stacking?: StackingFacet;
+    conversation?: ConversationFacet;
+    authoring?: AuthoringFacet;
+}

package/dist/review/provider.js

@@ -0,0 +1,16 @@
+/**
+ * The provider contract: facets, not one interface.
+ *
+ * A monolithic interface would force every backend to
+ * pretend. A bare git repo has stack topology and diffs and
+ * no conversation anywhere; a forge has all of it. Rather
+ * than have the repo throw from half its methods, a provider
+ * implements the facets it has and consumers ask before they
+ * reach.
+ *
+ * Claiming is separate from doing. Every registered provider
+ * gets a look at a reference or a repo and says whether it
+ * recognizes it, so adding a backend never means editing a
+ * resolver.
+ */
+export {};

package/dist/review/providers/git/index.d.ts

@@ -0,0 +1,23 @@
+/**
+ * The git provider: a repo with no forge behind it.
+ *
+ * This is the provider that proves the contract is honest.
+ * A checkout has topology and diffs and no conversation
+ * anywhere, so it implements stacking and nothing else, and a
+ * consumer that asks whether it can post a review gets a
+ * straight no rather than a method that throws.
+ *
+ * Parentage comes from the upstream a branch records, which is
+ * what every local stacking tool surveyed uses and what plain
+ * `git branch --set-upstream-to` writes. Reading only that,
+ * plus merge-base for the fork point, keeps this provider
+ * truthful about ordinary git; the tool-specific conventions
+ * (metadata refs, state files) each make a further fidelity
+ * claim and belong in providers of their own.
+ */
+import type { ProviderDeps } from "../../../exec/index.js";
+import type { ReviewProvider } from "../../provider.js";
+/** Provider id. */
+export declare const GIT_PROVIDER_ID = "git";
+/** Build the git provider. */
+export declare function createGitProvider(deps: ProviderDeps): ReviewProvider;

package/dist/review/providers/git/index.js

@@ -0,0 +1,214 @@
+/**
+ * The git provider: a repo with no forge behind it.
+ *
+ * This is the provider that proves the contract is honest.
+ * A checkout has topology and diffs and no conversation
+ * anywhere, so it implements stacking and nothing else, and a
+ * consumer that asks whether it can post a review gets a
+ * straight no rather than a method that throws.
+ *
+ * Parentage comes from the upstream a branch records, which is
+ * what every local stacking tool surveyed uses and what plain
+ * `git branch --set-upstream-to` writes. Reading only that,
+ * plus merge-base for the fork point, keeps this provider
+ * truthful about ordinary git; the tool-specific conventions
+ * (metadata refs, state files) each make a further fidelity
+ * claim and belong in providers of their own.
+ */
+import { run } from "../../../exec/index.js";
+/** Provider id. */
+export const GIT_PROVIDER_ID = "git";
+/**
+ * Claim priority. Last: a bare checkout is the fallback when
+ * no forge recognizes the repo, never the first answer.
+ */
+const GIT_PRIORITY = 900;
+/** How far to walk before deciding the config is cyclic. */
+const MAX_DEPTH = 16;
+/** The repo key a local checkout gets. */
+function localKey(repoRoot) {
+    return `local:${repoRoot}`;
+}
+/** A branch name, however the caller spelled it. */
+function branchName(ref) {
+    return ref.replace(/^refs\/heads\//, "");
+}
+/** What a bare repo can do. */
+function gitCapabilities() {
+    return { stacking: { provenance: "derived", fanOut: true } };
+}
+/** Build the stacking facet over a checkout. */
+function gitStacking(exec) {
+    /** The branch this one tracks, when it records one. */
+    async function upstreamOf(root, branch) {
+        const result = await exec("git", [
+            "-C",
+            root,
+            "config",
+            "--get",
+            `branch.${branch}.merge`,
+        ]);
+        // A branch with no upstream exits nonzero, which is an
+        // answer rather than a failure.
+        if (result.code !== 0)
+            return undefined;
+        const value = result.stdout.trim();
+        return value ? branchName(value) : undefined;
+    }
+    /** Every branch paired with the upstream it records. */
+    async function upstreamMap(root) {
+        const stdout = await run(exec, "git", [
+            "-C",
+            root,
+            "for-each-ref",
+            "--format=%(refname:short)|%(upstream:short)",
+            "refs/heads",
+        ], "listing branches");
+        const pairs = new Map();
+        for (const line of stdout.split("\n")) {
+            const [branch, upstream] = line.split("|");
+            if (!branch || !upstream)
+                continue;
+            pairs.set(branch.trim(), branchName(upstream.trim()));
+        }
+        return pairs;
+    }
+    async function tipOf(root, branch) {
+        const result = await exec("git", ["-C", root, "rev-parse", branch]);
+        return result.code === 0 ? result.stdout.trim() : undefined;
+    }
+    async function forkPointOf(root, branch, parent) {
+        const result = await exec("git", [
+            "-C",
+            root,
+            "merge-base",
+            parent,
+            branch,
+        ]);
+        return result.code === 0 ? result.stdout.trim() : undefined;
+    }
+    return {
+        async stack(subject) {
+            if ("id" in subject) {
+                throw new Error("the git provider reads a stack from a branch, not a hosted change");
+            }
+            const root = subject.repo.localPath;
+            if (!root) {
+                throw new Error(`${subject.repo.key} has no local checkout to read`);
+            }
+            const cursorBranch = branchName(subject.ref);
+            // Upwards: follow each branch's recorded upstream.
+            const ancestors = [];
+            const seen = new Set([cursorBranch]);
+            let climbing = await upstreamOf(root, cursorBranch);
+            let trunk;
+            for (let depth = 0; depth < MAX_DEPTH && climbing; depth++) {
+                if (seen.has(climbing))
+                    break;
+                const above = await upstreamOf(root, climbing);
+                if (!above) {
+                    // The branch that tracks nothing is the trunk, and
+                    // the trunk is not part of the stack.
+                    trunk = climbing;
+                    break;
+                }
+                seen.add(climbing);
+                ancestors.unshift(climbing);
+                climbing = above;
+            }
+            // Downwards: whoever records one of ours as upstream.
+            const pairs = await upstreamMap(root);
+            const descendants = [];
+            let frontier = [cursorBranch];
+            for (let depth = 0; depth < MAX_DEPTH && frontier.length > 0; depth++) {
+                const next = [];
+                for (const parent of frontier) {
+                    for (const [branch, upstream] of pairs) {
+                        if (upstream !== parent || seen.has(branch))
+                            continue;
+                        seen.add(branch);
+                        descendants.push({ branch, parent });
+                        next.push(branch);
+                    }
+                }
+                frontier = next;
+            }
+            const chain = [...ancestors, cursorBranch];
+            const nodes = [];
+            for (const [index, branch] of chain.entries()) {
+                const parent = index === 0 ? trunk : chain[index - 1];
+                nodes.push(await describe(root, branch, index === 0 ? undefined : parent, parent));
+            }
+            for (const { branch, parent } of descendants) {
+                nodes.push(await describe(root, branch, parent, parent));
+            }
+            return {
+                provenance: "derived",
+                ...(trunk ? { trunk } : {}),
+                nodes,
+                cursor: ancestors.length,
+            };
+        },
+    };
+    /**
+     * One node. `parent` is the link to report; `against` is
+     * what to measure the fork point from, which for a root is
+     * the trunk even though the trunk is not its parent in the
+     * stack.
+     */
+    async function describe(root, branch, parent, against) {
+        const headCommit = await tipOf(root, branch);
+        const forkPoint = against
+            ? await forkPointOf(root, branch, against)
+            : undefined;
+        // Behind means the thing this branch left has moved since it left. The
+        // fork point is where they last agreed, so comparing it against that
+        // thing's tip is the whole question, and both are already to hand.
+        //
+        // This is the only warning the stack view carries and it was declared
+        // and never set, by any provider, so a stack needing a restack drew
+        // exactly like a current one and a reader built on a stale base. It
+        // stays absent rather than false when there is nothing to measure
+        // against, since the field means "where the provider can tell" and a
+        // root with no trunk named cannot.
+        const ahead = against ? await tipOf(root, against) : undefined;
+        const behindParent = forkPoint && ahead ? forkPoint !== ahead : undefined;
+        return {
+            ref: branch,
+            ...(parent ? { parent } : {}),
+            ...(headCommit ? { headCommit } : {}),
+            ...(forkPoint ? { forkPoint } : {}),
+            ...(behindParent === undefined ? {} : { behindParent }),
+        };
+    }
+}
+/** Build the git provider. */
+export function createGitProvider(deps) {
+    return {
+        id: GIT_PROVIDER_ID,
+        priority: GIT_PRIORITY,
+        claimReference(input, repo) {
+            // Without a repo there is nothing to read a branch or a
+            // range against, so this is not ours to claim.
+            if (!repo)
+                return null;
+            const trimmed = input.trim();
+            if (!trimmed)
+                return null;
+            // A plain ref names itself; there is no number to add.
+            return {
+                provider: GIT_PROVIDER_ID,
+                repo,
+                id: trimmed,
+                label: trimmed,
+            };
+        },
+        claimRepo(probe) {
+            if (!probe.repoRoot)
+                return null;
+            return { key: localKey(probe.repoRoot), localPath: probe.repoRoot };
+        },
+        capabilities: gitCapabilities,
+        stacking: gitStacking(deps.exec),
+    };
+}

package/dist/review/providers/github/authoring.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Making and changing pull requests on GitHub.
+ *
+ * Every write goes through the REST API with a JSON body on disk,
+ * rather than through `gh pr create` and its siblings. The porcelain
+ * commands are friendlier to type and worse to call: they infer the
+ * base from the current checkout, they read a title out of the last
+ * commit when one is not given, and their flags have defaults that
+ * change what an omitted argument means. A caller here has already
+ * decided all of that, and inference at this layer would quietly
+ * overrule it.
+ *
+ * The body goes through a file for the same reason a commit message
+ * does. A pull request body is prose with newlines, quotes and
+ * backticks in it, and putting that on a command line is a quoting bug
+ * waiting for the first person who writes a shell snippet in a
+ * description.
+ */
+import { type Exec } from "../../../exec/index.js";
+import type { AuthoringFacet } from "../../provider.js";
+/** Build the authoring facet. */
+export declare function githubAuthoring(exec: Exec): AuthoringFacet;