@jitsusama/agentic-harness.core 0.1.0

package/dist/review/providers/github/authoring.js

@@ -0,0 +1,350 @@
+/**
+ * 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 { unlink, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { run } from "../../../exec/index.js";
+import { githubChange, ownerRepoFromKey } from "./claims.js";
+import { labelsAndAssignees } from "./fields.js";
+/** `owner/name`, as every GitHub route wants it. */
+function slugOf(repo) {
+    const owned = ownerRepoFromKey(repo.key);
+    if (!owned)
+        throw new Error(`${repo.key} is not a GitHub repo key`);
+    return `${owned.owner}/${owned.repo}`;
+}
+/** Build the authoring facet. */
+export function githubAuthoring(exec) {
+    /**
+     * One API call carrying a JSON body.
+     *
+     * The temp file is cleaned up in a finally, and a failure to clean
+     * it up is swallowed: a leftover file is harmless, and letting it
+     * fail would turn a successful write into a reported error.
+     */
+    async function send(method, route, payload, what) {
+        const file = join(tmpdir(), `pi-review-authoring-${Date.now()}-${Math.random()}.json`);
+        try {
+            await writeFile(file, JSON.stringify(payload), "utf8");
+            return await run(exec, "gh", ["api", "--method", method, route, "--input", file], what);
+        }
+        finally {
+            try {
+                await unlink(file);
+            }
+            catch {
+                // A leftover temp file is harmless, and failing to remove
+                // one must not fail the write that already succeeded.
+            }
+        }
+    }
+    /** A GraphQL mutation, for the two things REST will not do. */
+    async function mutate(query, id, what) {
+        await run(exec, "gh", ["api", "graphql", "-f", `query=${query}`, "-F", `id=${id}`], what);
+    }
+    /** One API call with no body, for the routes that take none. */
+    async function call(method, route, what) {
+        await run(exec, "gh", ["api", "--method", method, route], what);
+    }
+    /**
+     * Apply a set edit to labels or assignees.
+     *
+     * Both live on the issue rather than the pull request. GitHub models a
+     * pull request as an issue with a branch attached, so `PATCH
+     * /pulls/{n}` takes a title, a body and a base and knows nothing about
+     * labels; the `/issues/{n}` routes own those. The pull request
+     * representation does report them on the way out, which is why reading
+     * costs nothing extra and writing costs a separate call.
+     *
+     * `add` and `remove` are native here, and that is the point of
+     * {@link SetEdit}: doing either through a wholesale replace means
+     * reading the current list and writing it back, which drops whatever
+     * anybody else changed in between.
+     */
+    async function applySetEdit(ref, field, edit) {
+        const issue = `repos/${slugOf(ref.repo)}/issues/${ref.id}`;
+        const what = `changing the ${field} of pull request ${ref.id}`;
+        if (edit.action === "clear") {
+            await send("PATCH", issue, { [field]: [] }, what);
+            return;
+        }
+        if (edit.action === "set") {
+            await send("PATCH", issue, { [field]: edit.value }, what);
+            return;
+        }
+        if (edit.value.length === 0)
+            return;
+        if (edit.action === "add") {
+            await send("POST", `${issue}/${field}`, { [field]: edit.value }, what);
+            return;
+        }
+        // Removing differs between the two, which is GitHub's asymmetry
+        // rather than a choice here: a label is named in the path, one call
+        // each, and assignees come off together in a body.
+        if (field === "assignees") {
+            await send("DELETE", `${issue}/assignees`, { assignees: edit.value }, what);
+            return;
+        }
+        for (const label of edit.value) {
+            await call("DELETE", `${issue}/labels/${encodeURIComponent(label)}`, what);
+        }
+    }
+    /** The node id GitHub's GraphQL wants, which REST does not carry. */
+    async function nodeId(ref) {
+        const stdout = await run(exec, "gh", ["api", `repos/${slugOf(ref.repo)}/pulls/${ref.id}`, "--jq", ".node_id"], `reading the id of pull request ${ref.id}`);
+        return stdout.trim();
+    }
+    return {
+        async propose(draft) {
+            const raw = await send("POST", `repos/${slugOf(draft.repo)}/pulls`, {
+                base: draft.base,
+                head: draft.head,
+                title: draft.title,
+                body: draft.body,
+                // Always sent, never omitted. This backend defaults to
+                // ready and another defaults to draft, so an absent flag
+                // means two different things and the same call would
+                // produce a different change depending on where it landed.
+                draft: draft.draft,
+            }, `proposing ${draft.head} onto ${draft.base}`);
+            const proposed = proposalFrom(draft.repo, raw);
+            // A second call, because the create route does not take them: a
+            // pull request is an issue with a branch, and labels belong to
+            // the issue half. Sent after the change exists rather than not
+            // at all, since a caller who asked for a label and silently did
+            // not get one has no way to tell.
+            if (draft.labels?.length) {
+                await applySetEdit(proposed.ref, "labels", {
+                    action: "add",
+                    value: draft.labels,
+                });
+            }
+            if (draft.assignees?.length) {
+                await applySetEdit(proposed.ref, "assignees", {
+                    action: "add",
+                    value: draft.assignees,
+                });
+            }
+            return proposed;
+        },
+        async edit(ref, edit) {
+            const payload = {};
+            if (edit.title) {
+                payload.title = edit.title.action === "clear" ? "" : edit.title.value;
+            }
+            if (edit.body) {
+                payload.body = edit.body.action === "clear" ? "" : edit.body.value;
+            }
+            if (edit.base) {
+                if (edit.base.action === "clear") {
+                    // A change with no base is not a change. Sending an empty
+                    // string here would be accepted as a branch named "" and
+                    // rejected far from the call that caused it.
+                    throw new Error("A change has to target something, so its base cannot be cleared. Set it to another branch instead.");
+                }
+                payload.base = edit.base.value;
+            }
+            if (edit.labels)
+                await applySetEdit(ref, "labels", edit.labels);
+            if (edit.assignees)
+                await applySetEdit(ref, "assignees", edit.assignees);
+            // Read the change back rather than PATCHing nothing, for an edit
+            // that only touched labels. Sending an empty body here is
+            // accepted and returns the change unchanged, so this is about
+            // saying what happened rather than about correctness.
+            const route = `repos/${slugOf(ref.repo)}/pulls/${ref.id}`;
+            const raw = Object.keys(payload).length === 0
+                ? await run(exec, "gh", ["api", route], `reading pull request ${ref.id} back`)
+                : await send("PATCH", route, payload, `editing pull request ${ref.id}`);
+            return proposalFrom(ref.repo, raw);
+        },
+        async setDraft(ref, draft) {
+            // Not a field on the pull request. GitHub moves a change
+            // between draft and ready only through these two mutations,
+            // which is why this is its own method rather than part of edit.
+            const id = await nodeId(ref);
+            await mutate(draft ? CONVERT_TO_DRAFT : MARK_READY, id, `${draft ? "returning" : "readying"} pull request ${ref.id}`);
+        },
+        async close(ref, comment) {
+            // The comment goes first. A close that fails afterwards still
+            // leaves the reason behind, where the other order leaves a
+            // silently shut change nobody can account for.
+            if (comment !== undefined && comment.trim() !== "") {
+                await send("POST", `repos/${slugOf(ref.repo)}/issues/${ref.id}/comments`, { body: comment }, `saying why pull request ${ref.id} is being closed`);
+            }
+            await send("PATCH", `repos/${slugOf(ref.repo)}/pulls/${ref.id}`, { state: "closed" }, `closing pull request ${ref.id}`);
+        },
+        async reopen(ref) {
+            await send("PATCH", `repos/${slugOf(ref.repo)}/pulls/${ref.id}`, { state: "open" }, `reopening pull request ${ref.id}`);
+        },
+        async merge(ref, request) {
+            const answered = await send("PUT", `repos/${slugOf(ref.repo)}/pulls/${ref.id}/merge`, {
+                // Only when asked. Which merge a repo wants is its settled
+                // policy, and choosing one here would rewrite history a way
+                // the project did not pick.
+                ...(request.method === undefined
+                    ? {}
+                    : { merge_method: request.method }),
+                ...(request.expectedHead === undefined
+                    ? {}
+                    : { sha: request.expectedHead }),
+            }, `merging pull request ${ref.id}`);
+            // This endpoint lands the change then and there, so `merged` is the
+            // honest word for it. A repo fronted by GitHub's own merge queue does
+            // not merge through here at all, which is why there is no second case.
+            //
+            // The sha is passed on when the answer carries one and left out when
+            // it does not, rather than being defaulted to the head we sent: absent
+            // means unreported, and a commit is the one field a caller might go
+            // and look up.
+            const commit = shaFrom(answered);
+            return { kind: "merged", ...(commit === undefined ? {} : { commit }) };
+        },
+        async rerun(ref, which) {
+            // Actions reruns are keyed by run and a change is not a run, so
+            // the head commit is the join between them. Read back rather
+            // than taken on trust: a rerun aimed at a commit that has been
+            // pushed past spends CI on code nobody is looking at.
+            const head = await run(exec, "gh", [
+                "pr",
+                "view",
+                ref.id,
+                "--repo",
+                slugOf(ref.repo),
+                "--json",
+                "headRefOid",
+                "--jq",
+                ".headRefOid",
+            ], `reading the head of pull request ${ref.id}`);
+            const sha = head.trim();
+            if (sha === "") {
+                return {
+                    kind: "declined",
+                    reason: "its head commit could not be read",
+                };
+            }
+            const listed = await run(exec, "gh", [
+                "api",
+                `/repos/${slugOf(ref.repo)}/actions/runs?head_sha=${sha}&per_page=20`,
+                "--jq",
+                ".workflow_runs[] | [.id, .name] | @tsv",
+            ], `listing workflow runs for ${sha.slice(0, 7)}`);
+            const runs = listed
+                .split("\n")
+                .map((line) => line.split("\t"))
+                .flatMap(([id, name]) => id && name && (which === undefined || name === which)
+                ? [{ id, name }]
+                : []);
+            // Declined rather than a start nobody made. A repo can report
+            // checks this cannot rerun, because a check can come from any
+            // app and only Actions has runs, and a silent no-op here reads
+            // as "CI is going again" while nothing is.
+            if (runs.length === 0) {
+                return {
+                    kind: "declined",
+                    reason: which === undefined
+                        ? `no GitHub Actions run exists for ${sha.slice(0, 7)}, so whatever reports these checks is not Actions and has to be rerun where it lives`
+                        : `no GitHub Actions run named ${which} exists for ${sha.slice(0, 7)}`,
+                };
+            }
+            for (const { id } of runs) {
+                await send("POST", `repos/${slugOf(ref.repo)}/actions/runs/${id}/rerun`, {}, `rerunning workflow run ${id}`);
+            }
+            return { kind: "started", ...(which ? { which } : {}) };
+        },
+        async requestReviewers(ref, actors) {
+            // GitHub accepts an empty request and does nothing with it,
+            // which would leave a caller believing it asked somebody.
+            if (actors.length === 0)
+                return;
+            await send("POST", `repos/${slugOf(ref.repo)}/pulls/${ref.id}/requested_reviewers`, { reviewers: actors }, `requesting reviewers on pull request ${ref.id}`);
+        },
+    };
+    /** The change the API handed back, read the way a fetch reads one. */
+    function proposalFrom(repo, stdout) {
+        const raw = JSON.parse(stdout);
+        if (typeof raw !== "object" || raw === null) {
+            throw new Error("GitHub answered with something that is not a change.");
+        }
+        return restProposal(repo, raw);
+    }
+}
+/** Move a ready change back to draft. */
+const CONVERT_TO_DRAFT = "mutation($id: ID!) { convertPullRequestToDraft(input: {pullRequestId: $id}) { pullRequest { id } } }";
+/** Move a draft change to ready. */
+const MARK_READY = "mutation($id: ID!) { markPullRequestReadyForReview(input: {pullRequestId: $id}) { pullRequest { id } } }";
+/** A string, or nothing. */
+function str(value) {
+    return typeof value === "string" && value !== "" ? value : undefined;
+}
+/** The commit a merge answer names, when it names one and the text parses. */
+function shaFrom(answered) {
+    try {
+        const body = JSON.parse(answered);
+        if (typeof body !== "object" || body === null)
+            return undefined;
+        return str(body.sha);
+    }
+    catch {
+        // The merge went through; only the sha is unreadable. Failing the call
+        // over that would turn a landed change into a reported error, which is
+        // the one outcome worse than not naming the commit.
+        return undefined;
+    }
+}
+/** A nested object, or an empty one. */
+function nested(value, key) {
+    const held = value[key];
+    return typeof held === "object" && held !== null
+        ? held
+        : {};
+}
+/**
+ * One pull request as REST spells it.
+ *
+ * A local copy rather than the proposals facet's, because that one is
+ * private to its module and exporting it would widen a surface only to
+ * save a dozen lines. If a third caller appears, that is the moment to
+ * move it.
+ */
+function restProposal(repo, raw) {
+    const id = String(raw.number ?? "");
+    const state = raw.merged_at
+        ? "merged"
+        : str(raw.state) === "closed"
+            ? "closed"
+            : "open";
+    return {
+        ref: githubChange(repo, id),
+        title: str(raw.title) ?? "",
+        body: str(raw.body) ?? "",
+        state,
+        draft: raw.draft === true,
+        author: { id: str(nested(raw, "user").login) ?? "" },
+        base: str(nested(raw, "base").ref) ?? "",
+        head: str(nested(raw, "head").ref) ?? "",
+        ...(str(nested(raw, "head").sha)
+            ? { headCommit: str(nested(raw, "head").sha) }
+            : {}),
+        ...(str(raw.created_at) ? { createdAt: str(raw.created_at) } : {}),
+        ...(str(raw.updated_at) ? { updatedAt: str(raw.updated_at) } : {}),
+        ...(str(raw.html_url) ? { url: str(raw.html_url) } : {}),
+        ...labelsAndAssignees(raw),
+    };
+}

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

@@ -0,0 +1,49 @@
+/**
+ * What GitHub recognizes as one of its own.
+ *
+ * Pure pattern matching, deliberately separate from anything
+ * that runs a command, because claiming happens on every
+ * resolution and must stay cheap. The Graphite URL is included
+ * because it is a different view onto the same pull request,
+ * not a different backend.
+ */
+import type { ChangeRef, RepoLocator } from "../../change.js";
+import type { RepoProbe } from "../../provider.js";
+/** Provider id, used as the prefix of every repo key it mints. */
+export declare const GITHUB_PROVIDER_ID = "github";
+/** The repo key GitHub uses: `github:owner/repo`. */
+export declare function githubRepoKey(owner: string, repo: string): string;
+/** Owner and repo from a GitHub remote URL, if it is one. */
+export declare function ownerRepoFromRemote(remoteUrl: string): {
+    owner: string;
+    repo: string;
+} | null;
+/** Owner and repo from a repo key this provider minted. */
+export declare function ownerRepoFromKey(key: string): {
+    owner: string;
+    repo: string;
+} | null;
+/**
+ * A reference to a pull request in a repo this provider
+ * already identified. Every GitHub reference is built here, so
+ * one place decides how a pull request is spelled: the way a
+ * person writes it, which is also what `gh` accepts back.
+ */
+export declare function githubChange(repo: RepoLocator, id: string): ChangeRef;
+/**
+ * Recognize a reference. A bare number needs a repo to belong
+ * to, and only counts when that repo is one of GitHub's: a
+ * number typed while standing in a gitstream checkout is not a
+ * GitHub pull request.
+ */
+export declare function claimGitHubReference(input: string, repo?: RepoLocator): ChangeRef | null;
+/** Recognize a checkout by its remotes. */
+export declare function claimGitHubRepo(probe: RepoProbe): RepoLocator | null;
+/**
+ * Who GitHub attributes content to once its author is gone.
+ *
+ * A deleted account comes back as a null author, and GitHub itself
+ * reassigns that content to the ghost user, so this is reporting
+ * what the forge says rather than filling a hole with a guess.
+ */
+export declare const GHOST = "ghost";

package/dist/review/providers/github/claims.js

@@ -0,0 +1,136 @@
+/**
+ * What GitHub recognizes as one of its own.
+ *
+ * Pure pattern matching, deliberately separate from anything
+ * that runs a command, because claiming happens on every
+ * resolution and must stay cheap. The Graphite URL is included
+ * because it is a different view onto the same pull request,
+ * not a different backend.
+ */
+/** Provider id, used as the prefix of every repo key it mints. */
+export const GITHUB_PROVIDER_ID = "github";
+const PULL_URL = /^https?:\/\/github\.com\/([^/]+)\/([^/]+)\/pull\/(\d+)/;
+const GRAPHITE_URL = /^https?:\/\/app\.graphite\.com\/github\/pr\/([^/]+)\/([^/]+)\/(\d+)/;
+const SHORT_FORM = /^([^/\s]+)\/([^/#\s]+)#(\d+)$/;
+const BARE_NUMBER = /^#?(\d+)$/;
+const HTTPS_REMOTE = /^https?:\/\/(?:[^@]+@)?github\.com\/([^/]+)\/([^/]+?)(?:\.git)?$/;
+const SSH_REMOTE = /^git@github\.com:([^/]+)\/(.+?)(?:\.git)?$/;
+/** The repo key GitHub uses: `github:owner/repo`. */
+export function githubRepoKey(owner, repo) {
+    return `${GITHUB_PROVIDER_ID}:${owner}/${repo}`;
+}
+/** Owner and repo from a GitHub remote URL, if it is one. */
+export function ownerRepoFromRemote(remoteUrl) {
+    const https = HTTPS_REMOTE.exec(remoteUrl);
+    if (https)
+        return { owner: https[1], repo: https[2] };
+    const ssh = SSH_REMOTE.exec(remoteUrl);
+    if (ssh)
+        return { owner: ssh[1], repo: ssh[2] };
+    return null;
+}
+/** Owner and repo from a repo key this provider minted. */
+export function ownerRepoFromKey(key) {
+    const prefix = `${GITHUB_PROVIDER_ID}:`;
+    if (!key.startsWith(prefix))
+        return null;
+    const [owner, repo] = key.slice(prefix.length).split("/");
+    return owner && repo ? { owner, repo } : null;
+}
+function change(owner, repo, number) {
+    return githubChange({ key: githubRepoKey(owner, repo) }, number);
+}
+/**
+ * The richer of two locators for the same repo.
+ *
+ * A reference written out in full carries an owner and a name and nothing
+ * else, so it used to describe the repo as a key alone even when the
+ * caller was standing in a checkout of it. Anything wanting the working
+ * copy then had nowhere to look: a round asking for a snapshot pinned to
+ * the commit under review was refused for a repo with "neither a local
+ * checkout nor a remote", and reviewers silently read the mutable
+ * directory they happened to be in instead.
+ *
+ * Only ever the same repo. Keys are compared before anything is borrowed,
+ * because standing in one checkout says nothing about where a different
+ * repo lives, and quietly attaching the wrong path would have a round
+ * review the wrong code.
+ */
+function enriched(named, probed) {
+    if (!probed || probed.key !== named.key)
+        return named;
+    return {
+        ...named,
+        ...(probed.remoteUrl === undefined ? {} : { remoteUrl: probed.remoteUrl }),
+        ...(probed.localPath === undefined ? {} : { localPath: probed.localPath }),
+    };
+}
+/**
+ * A reference to a pull request in a repo this provider
+ * already identified. Every GitHub reference is built here, so
+ * one place decides how a pull request is spelled: the way a
+ * person writes it, which is also what `gh` accepts back.
+ */
+export function githubChange(repo, id) {
+    const owned = ownerRepoFromKey(repo.key);
+    return {
+        provider: GITHUB_PROVIDER_ID,
+        repo,
+        id,
+        label: owned ? `${owned.owner}/${owned.repo}#${id}` : `${repo.key}#${id}`,
+    };
+}
+/**
+ * Recognize a reference. A bare number needs a repo to belong
+ * to, and only counts when that repo is one of GitHub's: a
+ * number typed while standing in a gitstream checkout is not a
+ * GitHub pull request.
+ */
+export function claimGitHubReference(input, repo) {
+    const trimmed = input.trim();
+    // Each explicit form is told what the caller is standing in, so a
+    // reference to the repo around you knows where that repo is on disk.
+    const here = (named) => ({
+        ...named,
+        repo: enriched(named.repo, repo),
+    });
+    const pull = PULL_URL.exec(trimmed);
+    if (pull)
+        return here(change(pull[1], pull[2], pull[3]));
+    const graphite = GRAPHITE_URL.exec(trimmed);
+    if (graphite)
+        return here(change(graphite[1], graphite[2], graphite[3]));
+    const short = SHORT_FORM.exec(trimmed);
+    if (short)
+        return here(change(short[1], short[2], short[3]));
+    const bare = BARE_NUMBER.exec(trimmed);
+    if (!bare || !repo)
+        return null;
+    const owned = ownerRepoFromKey(repo.key);
+    // Enriched like the rest. This form reads the repo off the probe to
+    // understand the number at all, and then threw the rest of it away by
+    // rebuilding the locator from the owner and name it had just read.
+    return owned ? here(change(owned.owner, owned.repo, bare[1])) : null;
+}
+/** Recognize a checkout by its remotes. */
+export function claimGitHubRepo(probe) {
+    for (const remoteUrl of probe.remoteUrls ?? []) {
+        const owned = ownerRepoFromRemote(remoteUrl);
+        if (!owned)
+            continue;
+        return {
+            key: githubRepoKey(owned.owner, owned.repo),
+            remoteUrl,
+            ...(probe.repoRoot ? { localPath: probe.repoRoot } : {}),
+        };
+    }
+    return null;
+}
+/**
+ * Who GitHub attributes content to once its author is gone.
+ *
+ * A deleted account comes back as a null author, and GitHub itself
+ * reassigns that content to the ghost user, so this is reporting
+ * what the forge says rather than filling a hole with a guess.
+ */
+export const GHOST = "ghost";

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

@@ -0,0 +1,18 @@
+/**
+ * Reading and writing the conversation on a GitHub change.
+ *
+ * Three of GitHub's habits are absorbed here rather than
+ * leaked. It calls the two sides of a diff LEFT and RIGHT,
+ * which is a display convention, so the neutral old and new
+ * are translated at this boundary. It keeps review threads in
+ * GraphQL and reactions in REST, with different id systems, so
+ * message ids are minted with a prefix saying which route they
+ * belong to. And it pages review threads a hundred at a time,
+ * so the reader keeps asking until GitHub says there is no
+ * more; stopping at the first page silently loses the tail of
+ * a long review.
+ */
+import type { Exec } from "../../../exec/index.js";
+import type { ConversationFacet } from "../../provider.js";
+/** Build the conversation facet. */
+export declare function githubConversation(exec: Exec): ConversationFacet;