@jitsusama/agentic-harness.core 0.1.0

package/dist/review/change.d.ts

@@ -0,0 +1,155 @@
+/**
+ * What a review looks at: repos, hosted changes and the
+ * targets a review session can be pointed at.
+ *
+ * The vocabulary is git's wherever git has a word for the
+ * thing. A repo is named by a locator rather than an
+ * owner/name pair, because not every backend has owners. A
+ * hosted change carries an opaque, provider-scoped id,
+ * because the backends disagree on whether that is a
+ * number, a UUID, a branch or a range. A review target is
+ * deliberately wider than a hosted change: a range of
+ * commits or a stack of branches is reviewable whether or
+ * not anyone has proposed it anywhere.
+ */
+import type { Landability } from "./landing.js";
+import type { QueueState } from "./queue.js";
+/**
+ * Where a repo lives. Providers claim locators; the `key`
+ * is the stable identity everything else is scoped by.
+ */
+export interface RepoLocator {
+    /** Stable identity, e.g. `github:Shopify/world`. */
+    key: string;
+    /** Remote URL, when the repo has one. */
+    remoteUrl?: string;
+    /** Absolute path to a local checkout, when there is one. */
+    localPath?: string;
+}
+/**
+ * A change hosted by a provider: a GitHub pull request, a
+ * gitstream pull, a GitLab merge request. The `id` is
+ * opaque and only meaningful to the provider that minted
+ * it; nothing outside the provider may parse it.
+ */
+export interface ChangeRef {
+    /** Id of the provider that owns this change. */
+    provider: string;
+    /** Repo the change belongs to. */
+    repo: RepoLocator;
+    /** Provider-scoped identity. Never parsed by consumers. */
+    id: string;
+    /**
+     * Short human name for this change, in whatever form its
+     * own system uses: `Shopify/world#123` for a GitHub pull
+     * request, and whatever Meteorite or GitLab call theirs.
+     *
+     * Carried on the reference rather than asked of the
+     * provider, because a consumer that reloaded a reference
+     * from disk still has to be able to name it, and should
+     * not need a live provider or a request to do so.
+     */
+    label: string;
+}
+/**
+ * What a review session is looking at.
+ *
+ * `proposal` is a change someone is hosting. `range` is any
+ * two endpoints in a repo, which is how an unposted branch
+ * gets reviewed. `stack` is an ordered set of refs reviewed
+ * as one body of work, whether or not proposals exist for
+ * its members.
+ */
+export type ReviewTarget = {
+    kind: "proposal";
+    change: ChangeRef;
+} | {
+    kind: "range";
+    repo: RepoLocator;
+    base: string;
+    head: string;
+} | {
+    kind: "stack";
+    repo: RepoLocator;
+    refs: string[];
+};
+/**
+ * Where a hosted change stands. Deliberately three values:
+ * draft-ness and locked-ness are flags, not states, because
+ * the backends disagree about whether they are states and
+ * agree that these three are.
+ */
+export type ChangeState = "open" | "merged" | "closed";
+/** Someone who acted. Identity is provider-scoped. */
+export interface Actor {
+    /** How the provider names them: login, email, or id. */
+    id: string;
+    /** Display name, when the provider offers one. */
+    name?: string;
+}
+/** A hosted change, read back. */
+export interface Proposal {
+    ref: ChangeRef;
+    title: string;
+    body: string;
+    state: ChangeState;
+    draft: boolean;
+    author: Actor;
+    /** Ref the change would merge into. */
+    base: string;
+    /** Ref holding the proposed work. */
+    head: string;
+    /** Tip commit of `head`, when the provider reports it. */
+    headCommit?: string;
+    createdAt?: string;
+    updatedAt?: string;
+    /** Web location for humans. */
+    url?: string;
+    /**
+     * How big the change is, when the provider says.
+     *
+     * Carried rather than derived because a consumer that only
+     * wants to state the size should not have to fetch and count a
+     * whole diff, and every backend reports this alongside the rest
+     * of the change. Absent means unreported, which is not the same
+     * as zero.
+     */
+    additions?: number;
+    deletions?: number;
+    changedFiles?: number;
+    /**
+     * Where the change stands with a merge queue, when the backend
+     * has one and says.
+     *
+     * Carried on the proposal because the authoring gate has to know
+     * before it acts, and a caller cannot be trusted to have asked:
+     * the gate spent a release reading this off an intent nobody set,
+     * which made it unreachable. Absent means the provider has no
+     * queue or did not report one, which is not the same as unqueued.
+     */
+    queue?: QueueState;
+    /**
+     * Whether it could land, and what is in the way.
+     *
+     * Absent where the backend does not say. That is not the same as clear to
+     * land, and the narration keeps them apart: a change nobody has judged
+     * reads as unreported rather than as ready.
+     */
+    landing?: Landability;
+    /**
+     * Labels on the change, where the backend has labels.
+     *
+     * An empty array and an absent field are different facts: the first
+     * says the backend has labels and this change has none, the second
+     * says nobody reported any.
+     */
+    labels?: string[];
+    /** Who it is assigned to, where the backend assigns changes. */
+    assignees?: Actor[];
+    /**
+     * Anything the provider knows that the neutral model
+     * does not name. Consumers may read it opportunistically;
+     * nothing in the substrate depends on it.
+     */
+    extensions?: Record<string, unknown>;
+}

package/dist/review/change.js

@@ -0,0 +1,15 @@
+/**
+ * What a review looks at: repos, hosted changes and the
+ * targets a review session can be pointed at.
+ *
+ * The vocabulary is git's wherever git has a word for the
+ * thing. A repo is named by a locator rather than an
+ * owner/name pair, because not every backend has owners. A
+ * hosted change carries an opaque, provider-scoped id,
+ * because the backends disagree on whether that is a
+ * number, a UUID, a branch or a range. A review target is
+ * deliberately wider than a hosted change: a range of
+ * commits or a stack of branches is reviewable whether or
+ * not anyone has proposed it anywhere.
+ */
+export {};

package/dist/review/checks.d.ts

@@ -0,0 +1,56 @@
+/**
+ * CI state for a change.
+ *
+ * The interesting distinction is between a check that failed
+ * and a check that has not reported yet. One backend
+ * represents the latter as a null status rather than a
+ * pending one, and a consumer that folds the two together
+ * will tell someone their change is broken when nothing has
+ * run.
+ */
+/** Where one check stands. */
+export type CheckState = "passing" | "failing" | "pending"
+/** Registered but yet to report anything. */
+ | "unreported" | "skipped";
+/** One check. */
+export interface Check {
+    name: string;
+    state: CheckState;
+    url?: string;
+    /** True when the change cannot merge without it. */
+    required?: boolean;
+    summary?: string;
+}
+/**
+ * What came of asking for checks to run again.
+ *
+ * A union rather than nothing, because the two outcomes need
+ * different things from the reader. `started` means CI has been
+ * asked and the answer will arrive later, so a caller polls or
+ * waits. `declined` means the backend understood and refused, and
+ * the reason belongs to the backend rather than to us: a change
+ * that has already landed, a queue that will not accept a retry, a
+ * pipeline nobody recognizes.
+ *
+ * `which` echoes back what was actually rerun. Asking for one
+ * pipeline by name and being given all of them is a difference the
+ * caller cannot otherwise see, and it costs real CI minutes.
+ */
+export type RerunOutcome = {
+    kind: "started";
+    which?: string;
+    url?: string;
+} | {
+    kind: "declined";
+    reason: string;
+};
+/** Every check on a change, plus the answer people want. */
+export interface ChecksRollup {
+    /**
+     * The rollup. `pending` while anything required is still
+     * running or unreported; `failing` when anything required
+     * failed.
+     */
+    state: CheckState;
+    checks: Check[];
+}

package/dist/review/checks.js

@@ -0,0 +1,11 @@
+/**
+ * CI state for a change.
+ *
+ * The interesting distinction is between a check that failed
+ * and a check that has not reported yet. One backend
+ * represents the latter as a null status rather than a
+ * pending one, and a consumer that folds the two together
+ * will tell someone their change is broken when nothing has
+ * run.
+ */
+export {};

package/dist/review/config.d.ts

@@ -0,0 +1,71 @@
+/**
+ * What the user gets to decide about provider selection.
+ *
+ * Two knobs, both of which exist because guessing is worse
+ * than asking. A repo mapping pins a repo to a provider with
+ * ordered fallbacks, which is what a migration needs: while
+ * one repo lives on two backends at once, the person doing
+ * the work is the only one who knows which of them is the
+ * real one today. A reference mapping teaches the substrate
+ * a URL or short form no provider recognizes, so an internal
+ * link shape can be adopted without shipping code.
+ */
+/** Pins a repo to providers, first registered one winning. */
+export interface RepoMapping {
+    /**
+     * Matched as a substring against the checkout path and
+     * each of its remote URLs. Substring rather than a
+     * pattern because the thing people have to hand is a repo
+     * name, and `Shopify/world` should just work.
+     */
+    match: string;
+    /**
+     * Provider ids in preference order. Ids that are not
+     * registered are skipped, which is what makes this safe
+     * to write before the provider ships.
+     */
+    providers: string[];
+    /**
+     * Where this repo is checked out, for reading it.
+     *
+     * Without it, the only repo reviewable from a session is
+     * the one the session is sitting in: a round elsewhere
+     * either reads the wrong project or, since that was
+     * stopped, refuses. Nothing else can supply this, because
+     * which directory holds a repo is a fact about this
+     * machine and no provider knows it.
+     */
+    path?: string;
+}
+/** Teaches the substrate a reference shape. */
+export interface ReferenceMapping {
+    /**
+     * Regular expression matched against the whole reference.
+     * Named groups `repo` and `id` are read when present.
+     */
+    pattern: string;
+    /** Provider to hand the match to. */
+    provider: string;
+    /** Repo key to use when the pattern names no `repo`. */
+    repo?: string;
+}
+/** The `review` section of the package config. */
+export interface ReviewConfig {
+    repos?: RepoMapping[];
+    references?: ReferenceMapping[];
+}
+/** What parsing the section produced, and anything wrong with it. */
+export interface LoadedReviewConfig {
+    config: ReviewConfig;
+    /** Complaints about the section, for the user to see. */
+    problems: string[];
+}
+/**
+ * Parse the `review` section of the package config, reporting
+ * anything malformed.
+ *
+ * Pure: the section is handed in already read, so this has no
+ * opinion about where the package config file lives or how it is
+ * loaded from disk — that is a host adapter's job.
+ */
+export declare function parseReviewSection(section: unknown): LoadedReviewConfig;

package/dist/review/config.js

@@ -0,0 +1,125 @@
+/**
+ * What the user gets to decide about provider selection.
+ *
+ * Two knobs, both of which exist because guessing is worse
+ * than asking. A repo mapping pins a repo to a provider with
+ * ordered fallbacks, which is what a migration needs: while
+ * one repo lives on two backends at once, the person doing
+ * the work is the only one who knows which of them is the
+ * real one today. A reference mapping teaches the substrate
+ * a URL or short form no provider recognizes, so an internal
+ * link shape can be adopted without shipping code.
+ */
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function stringList(value) {
+    return Array.isArray(value)
+        ? value.filter((entry) => typeof entry === "string")
+        : [];
+}
+function readRepoMappings(value, problems) {
+    if (value === undefined)
+        return [];
+    if (!Array.isArray(value)) {
+        problems.push("review.repos should be a list of mappings.");
+        return [];
+    }
+    const mappings = [];
+    for (const [index, entry] of value.entries()) {
+        if (!isRecord(entry) ||
+            typeof entry.match !== "string" ||
+            entry.match.trim().length === 0) {
+            // Non-empty, because matching is a substring test and every
+            // string contains the empty one: an empty match claims every
+            // repo there is, which for a mapping carrying a path means
+            // every round in every repo reads one directory.
+            problems.push(`review.repos[${index}] needs a non-empty "match" string.`);
+            continue;
+        }
+        const providers = stringList(entry.providers);
+        // Absolute and non-empty. A relative path is resolved against
+        // whatever directory the session happens to be in, which is the
+        // thing this field exists to stop mattering, and `~` is the
+        // shell's expansion rather than one node does. Both fail far from
+        // here and read as "that is not a checkout".
+        const said = typeof entry.path === "string" ? entry.path.trim() : "";
+        if (said.length > 0 && !said.startsWith("/")) {
+            problems.push(`review.repos[${index}].path must be an absolute path; "${said}" is relative${said.startsWith("~") ? ", and a leading ~ is the shell's expansion rather than one node performs" : ""}.`);
+            continue;
+        }
+        const path = said.length > 0 ? said : undefined;
+        // One or the other. A mapping used to be a way to pin a provider
+        // and nothing else, so an empty list meant an entry that did
+        // nothing; now it can also be the only place that says where a
+        // repo lives, and saying that is a whole job.
+        if (providers.length === 0 && path === undefined) {
+            problems.push(`review.repos[${index}] needs at least one provider id, or a "path" saying where the repo is checked out.`);
+            continue;
+        }
+        mappings.push({
+            match: entry.match,
+            providers,
+            ...(path === undefined ? {} : { path }),
+        });
+    }
+    return mappings;
+}
+function readReferenceMappings(value, problems) {
+    if (value === undefined)
+        return [];
+    if (!Array.isArray(value)) {
+        problems.push("review.references should be a list of mappings.");
+        return [];
+    }
+    const mappings = [];
+    for (const [index, entry] of value.entries()) {
+        if (!isRecord(entry) ||
+            typeof entry.pattern !== "string" ||
+            typeof entry.provider !== "string") {
+            problems.push(`review.references[${index}] needs a "pattern" and a "provider".`);
+            continue;
+        }
+        try {
+            new RegExp(entry.pattern);
+        }
+        catch (error) {
+            problems.push(`review.references[${index}] has an unusable pattern: ${error instanceof Error ? error.message : String(error)}`);
+            continue;
+        }
+        mappings.push({
+            pattern: entry.pattern,
+            provider: entry.provider,
+            ...(typeof entry.repo === "string" ? { repo: entry.repo } : {}),
+        });
+    }
+    return mappings;
+}
+/**
+ * Parse the `review` section of the package config, reporting
+ * anything malformed.
+ *
+ * Pure: the section is handed in already read, so this has no
+ * opinion about where the package config file lives or how it is
+ * loaded from disk — that is a host adapter's job.
+ */
+export function parseReviewSection(section) {
+    if (section === undefined)
+        return { config: {}, problems: [] };
+    if (!isRecord(section)) {
+        return {
+            config: {},
+            problems: ["The review config section should be an object."],
+        };
+    }
+    const problems = [];
+    const repos = readRepoMappings(section.repos, problems);
+    const references = readReferenceMappings(section.references, problems);
+    return {
+        config: {
+            ...(repos.length > 0 ? { repos } : {}),
+            ...(references.length > 0 ? { references } : {}),
+        },
+        problems,
+    };
+}

package/dist/review/conventions.d.ts

@@ -0,0 +1,35 @@
+/**
+ * The authoring conventions, checked where authoring actually happens.
+ *
+ * A guardian intercepts shell commands, so `gh pr create` is held to
+ * the PR format, the title convention and the prose standard. Proposing
+ * a change through `review_offer` never touches a shell: it builds a
+ * JSON body and posts it to an API. Left alone, that is a way to route
+ * around every convention this package enforces, and the better the
+ * tool got the more attractive that route became.
+ *
+ * So the same three checks run here, over the same detectors, before
+ * anything is sent. This is not the guardian's code copied: the
+ * detectors are pure and shared, and only the response differs. A
+ * guardian blocks a command and relents to a human on a repeat, because
+ * it cannot rewrite the words. A tool can simply be called again with a
+ * better body, so a refusal here is a plain refusal with no relent
+ * path, which is also why it cannot loop.
+ *
+ * The same formatters too. This used to tally an issue word against the
+ * offending text, which said "use Canadian English spelling" without
+ * naming the word, and printed the title rule's internal word list as
+ * though it were a diagnosis: `sentence-case: fix(review, replay,
+ * whole, resolution`. The guardian's blocks already name the word and
+ * its replacement, and explain what Title Case wants, so both paths now
+ * say the same thing and there is one place to improve it.
+ */
+/**
+ * A refusal naming what to fix about a proposal, or nothing.
+ *
+ * The order matters and is the guardian's: structure, then title, then
+ * prose. There is no point polishing the words in a section that should
+ * not exist, and a wrong title should be caught alongside the structure
+ * rather than after the writing has been redone.
+ */
+export declare function proposalComplaint(title: string | undefined, body: string | undefined): string | undefined;

package/dist/review/conventions.js

@@ -0,0 +1,58 @@
+/**
+ * The authoring conventions, checked where authoring actually happens.
+ *
+ * A guardian intercepts shell commands, so `gh pr create` is held to
+ * the PR format, the title convention and the prose standard. Proposing
+ * a change through `review_offer` never touches a shell: it builds a
+ * JSON body and posts it to an API. Left alone, that is a way to route
+ * around every convention this package enforces, and the better the
+ * tool got the more attractive that route became.
+ *
+ * So the same three checks run here, over the same detectors, before
+ * anything is sent. This is not the guardian's code copied: the
+ * detectors are pure and shared, and only the response differs. A
+ * guardian blocks a command and relents to a human on a repeat, because
+ * it cannot rewrite the words. A tool can simply be called again with a
+ * better body, so a refusal here is a plain refusal with no relent
+ * path, which is also why it cannot loop.
+ *
+ * The same formatters too. This used to tally an issue word against the
+ * offending text, which said "use Canadian English spelling" without
+ * naming the word, and printed the title rule's internal word list as
+ * though it were a diagnosis: `sentence-case: fix(review, replay,
+ * whole, resolution`. The guardian's blocks already name the word and
+ * its replacement, and explain what Title Case wants, so both paths now
+ * say the same thing and there is one place to improve it.
+ */
+import { detectProseViolations, formatProseBlock } from "../prose/index.js";
+import { detectSectionViolations, formatSectionBlock, PR_SECTIONS, } from "../sections/index.js";
+import { detectTitleViolations, formatTitleBlock } from "../title/index.js";
+/**
+ * A refusal naming what to fix about a proposal, or nothing.
+ *
+ * The order matters and is the guardian's: structure, then title, then
+ * prose. There is no point polishing the words in a section that should
+ * not exist, and a wrong title should be caught alongside the structure
+ * rather than after the writing has been redone.
+ */
+export function proposalComplaint(title, body) {
+    const written = body !== undefined && body.trim() !== "";
+    const named = title !== undefined && title.trim() !== "";
+    // Every class at once, in the guardian's order. Returning at the first
+    // one made each fix reveal the next: a body was refused for its
+    // sections, then for its title, then for an emdash, and every round
+    // trip through the tool was another chance for something else to go
+    // wrong. One refusal that says everything costs one rewrite.
+    const blocks = [
+        written
+            ? formatSectionBlock(detectSectionViolations(body, PR_SECTIONS), "pull request", "github-pr-format")
+            : "",
+        named
+            ? formatTitleBlock(detectTitleViolations(title), "pull request", "github-pr-format")
+            : "",
+        written ? formatProseBlock(detectProseViolations(body)) : "",
+    ].filter((block) => block !== "");
+    if (blocks.length === 0)
+        return undefined;
+    return blocks.join("\n").trimEnd();
+}

package/dist/review/conversation.d.ts

@@ -0,0 +1,98 @@
+/**
+ * What people said about a change.
+ *
+ * Three shapes, because the backends agree there are three:
+ * a review (a verdict with a summary), a thread (an anchored
+ * exchange), and a message (a remark about the change as a
+ * whole). They are separate feeds, not one list, and
+ * flattening them would lose the distinction every backend
+ * bothers to keep.
+ *
+ * Thread identity is opaque on purpose. The backends key a
+ * reply differently, one by the thread and one by the
+ * comment that started it, so a caller hands back the whole
+ * thread and the provider takes whichever key it needs.
+ */
+import type { Anchor } from "./anchor.js";
+import type { Actor } from "./change.js";
+/**
+ * The reactions available. Both forges surveyed support
+ * exactly this set, so it is modelled as a closed list
+ * rather than an open string.
+ */
+export type Reaction = "+1" | "-1" | "laugh" | "confused" | "heart" | "hooray" | "rocket" | "eyes";
+/** How many people reacted one way, and whether you did. */
+export interface ReactionCount {
+    reaction: Reaction;
+    count: number;
+    /** True when the authenticated actor is among them. */
+    mine?: boolean;
+}
+/** Something someone wrote. */
+export interface Message {
+    /** Provider-scoped id. Never parsed by consumers. */
+    id: string;
+    author: Actor;
+    body: string;
+    createdAt?: string;
+    updatedAt?: string;
+    url?: string;
+    reactions?: ReactionCount[];
+}
+/** An anchored exchange about part of a change. */
+export interface Thread {
+    /** Provider-scoped id. Never parsed by consumers. */
+    id: string;
+    resolved: boolean;
+    /** Who resolved it, when the provider records that. */
+    resolvedBy?: Actor;
+    /**
+     * Where the thread attaches. Absent for threads a
+     * provider hangs off the review rather than a line.
+     */
+    anchor?: Anchor;
+    /**
+     * Whether the thread's anchor still describes the change.
+     * Absent when the provider cannot tell, which is
+     * different from known-current.
+     */
+    stale?: boolean;
+    /** In the order they were written. */
+    comments: Message[];
+}
+/**
+ * A reviewer's position. The three every backend can express,
+ * whether as an event, a vote or a trailer. A provider that
+ * knows a fourth reports it through its own extensions
+ * rather than widening this.
+ */
+export type Verdict = "approve" | "request-changes" | "comment";
+/** A submitted review. */
+export interface Review {
+    id: string;
+    author: Actor;
+    verdict: Verdict;
+    body: string;
+    submittedAt?: string;
+    url?: string;
+    /** Provider vocabulary for the verdict, when it differs. */
+    nativeVerdict?: string;
+}
+/** One anchored remark within a review being posted. */
+export interface AnchoredComment {
+    anchor: Anchor;
+    body: string;
+}
+/** A review about to be posted. */
+export interface WireReview {
+    verdict: Verdict;
+    /** The summary. Some providers require one for a verdict. */
+    body: string;
+    comments: AnchoredComment[];
+}
+/** What a provider hands back after writing something. */
+export interface Posted {
+    /** Provider-scoped id of what was created, when known. */
+    id?: string;
+    url?: string;
+}

package/dist/review/conversation.js

@@ -0,0 +1,16 @@
+/**
+ * What people said about a change.
+ *
+ * Three shapes, because the backends agree there are three:
+ * a review (a verdict with a summary), a thread (an anchored
+ * exchange), and a message (a remark about the change as a
+ * whole). They are separate feeds, not one list, and
+ * flattening them would lose the distinction every backend
+ * bothers to keep.
+ *
+ * Thread identity is opaque on purpose. The backends key a
+ * reply differently, one by the thread and one by the
+ * comment that started it, so a caller hands back the whole
+ * thread and the provider takes whichever key it needs.
+ */
+export {};