@intentius/chant 0.124.40 → 0.124.41

package/dist/lifecycle/target-lock.js

@@ -0,0 +1,286 @@
+/**
+ * Target locks (#4293): a pull request holds a lock on each target its
+ * change reaches, so no other pull request applies or locks those targets
+ * until it merges or closes, or someone runs `chant unlock` on it.
+ *
+ * A target is a name the caller picks: a component, a workspace member, or
+ * a lexicon's own unit such as a Terraform root. The locks of one gate live
+ * in one file, `_locks/<gate>.json` on `chant/lifecycle`, under the member's
+ * ledger prefix in a workspace member (./git.ts `ledgerDir`). The gate is
+ * the pull-request loop's, `pr-apply` unless the pipeline names another, so
+ * two pipelines with their own gates keep their own locks.
+ *
+ * Every change is a new commit on the branch, written with the read-then-CAS
+ * the other ledgers use and then pushed. A lock counts only once the remote
+ * has it: when the push is refused because another writer moved the branch,
+ * the local commit is dropped, the branch is read again and the decision is
+ * made again. So two jobs that lock the same target at once cannot both win.
+ * A repository with no remote is one machine, and the local write decides.
+ *
+ * A lock held by a pull request that is no longer open is released: the
+ * holder merged or closed. The caller says which pull requests are open
+ * (`isOpen`, from the forge). Without it every lock counts as held, and only
+ * `chant unlock` releases one.
+ *
+ * The file is coordination, not a record of work. ws-074 holds: the
+ * repository is the database, and the file is one more ledger on the
+ * branch, so any clone can read who holds what.
+ */
+import { getRuntime } from "../runtime-adapter.js";
+import { fetchLifecycleStatus, pushLifecycleStatus, readBlobBySha, readPathSha, RefCASConflictError, writeBlobToPath, } from "./git.js";
+import { resolveMemberLedger } from "./member-ledger.js";
+/** The directory on `chant/lifecycle` that holds the lock files. */
+export const LOCKS_DIR = "_locks";
+const STATE_BRANCH = "chant/lifecycle";
+/** A scratch ref this module owns, for reading the remote tip after a refused push. */
+const PROBE_REF = "refs/chant/target-lock-probe";
+const ATTEMPTS = 5;
+export const TARGET_LOCK_STAGES = ["plan", "apply", "lock"];
+/** The path of `gate`'s lock file on `chant/lifecycle`, under a member's prefix when it has one. */
+export function targetLockPath(gate, memberPrefix = "") {
+    return `${memberPrefix}${LOCKS_DIR}/${gate}.json`;
+}
+/** A gate name that is safe as a file name. */
+export function targetLockGateProblem(gate) {
+    return /^[A-Za-z0-9][A-Za-z0-9_.-]{0,127}$/.test(gate) ? null : `the gate name ${JSON.stringify(gate)} is not a lock file name: letters, digits, '.', '_' and '-', starting with a letter or digit`;
+}
+const isStage = (v) => typeof v === "string" && TARGET_LOCK_STAGES.includes(v);
+/** Parse a lock file. Anything that is not a version 1 file with a map of locks reads as no locks; a malformed entry is dropped. */
+export function parseTargetLocks(text) {
+    if (!text)
+        return { version: 1, locks: {} };
+    try {
+        const doc = JSON.parse(text);
+        if (doc?.version === 1 && doc.locks && typeof doc.locks === "object" && !Array.isArray(doc.locks)) {
+            const locks = {};
+            for (const [target, raw] of Object.entries(doc.locks)) {
+                if (!raw || !Number.isInteger(raw.pr) || typeof raw.by !== "string" || typeof raw.at !== "string" || !isStage(raw.stage))
+                    continue;
+                locks[target] = { pr: raw.pr, by: raw.by, at: raw.at, stage: raw.stage, ...(typeof raw.head === "string" ? { head: raw.head } : {}) };
+            }
+            return { version: 1, locks };
+        }
+    }
+    catch {
+        // An unreadable file holds no locks.
+    }
+    return { version: 1, locks: {} };
+}
+/** The file's text: targets sorted, so two writes of the same locks are the same blob. */
+export function renderTargetLocks(file) {
+    const locks = Object.fromEntries(Object.keys(file.locks).sort().map((t) => [t, file.locks[t]]));
+    return `${JSON.stringify({ version: 1, locks }, null, 2)}\n`;
+}
+/** Fetch `chant/lifecycle`, refusing a ledger this checkout cannot read: a lock decided on a stale branch is no lock. */
+async function fetchForLocks(cwd) {
+    const fetched = await fetchLifecycleStatus({ cwd });
+    if (fetched.status === "diverged")
+        throw new Error(`the local ${STATE_BRANCH} has forked from ${fetched.remote}'s, so the locks cannot be read: ${fetched.stderr}`);
+    if (fetched.status === "unreachable")
+        throw new Error(`cannot fetch ${STATE_BRANCH} from ${fetched.remote}, so the locks cannot be read${fetched.stderr ? `: ${fetched.stderr}` : ""}`);
+}
+async function readCurrent(gate, cwd) {
+    const sha = await readPathSha(LOCKS_DIR, `${gate}.json`, { cwd });
+    return { sha, file: parseTargetLocks(sha ? await readBlobBySha(sha, { cwd }) : null) };
+}
+/** The locks of `gate` as the remote holds them now, fetched first. */
+export async function readTargetLocks(gate, opts = {}) {
+    const problem = targetLockGateProblem(gate);
+    if (problem)
+        throw new Error(problem);
+    await fetchForLocks(opts.cwd);
+    return (await readCurrent(gate, opts.cwd)).file;
+}
+/** A memo of `isOpen`, so one decision asks the forge about each pull request once. */
+function openMemo(isOpen) {
+    const seen = new Map();
+    return (pr) => {
+        if (!isOpen)
+            return Promise.resolve(true);
+        if (!seen.has(pr))
+            seen.set(pr, isOpen(pr));
+        return seen.get(pr);
+    };
+}
+/** The locks on `targets` that an open pull request other than `pr` holds, by target. */
+async function heldIn(file, targets, pr, open) {
+    const held = [];
+    for (const target of [...new Set(targets)].sort()) {
+        const l = file.locks[target];
+        if (l && l.pr !== pr && (await open(l.pr)))
+            held.push({ target, ...l });
+    }
+    return held;
+}
+/**
+ * The locks on `targets` that an open pull request other than `pr` holds.
+ * Reads only: an apply calls this to refuse a target another pull request
+ * holds. `pr` null (an apply of a green commit) counts every open holder.
+ */
+export async function heldTargetLocks(gate, targets, pr, opts = {}) {
+    if (targets.length === 0)
+        return [];
+    const file = await readTargetLocks(gate, opts);
+    return heldIn(file, targets, pr, openMemo(opts.isOpen));
+}
+/** The local tip of `chant/lifecycle`, or "" when there is none. */
+async function localTip(cwd) {
+    const out = await getRuntime().spawn(["git", "rev-parse", "--verify", "--quiet", `refs/heads/${STATE_BRANCH}`], { cwd });
+    return out.exitCode === 0 ? out.stdout.trim() : "";
+}
+/**
+ * After a refused push: drop the lock commit `ours` from the local branch by
+ * moving it to the remote's tip, so the next attempt reads what the other
+ * writer pushed. Done only when `parent`, the tip before the write, is in
+ * the remote's history, so no other local commit is lost. Throws otherwise.
+ */
+async function dropRefusedWrite(remote, ours, parent, cwd) {
+    const rt = getRuntime();
+    const env = { LC_ALL: "C", LANGUAGE: "" };
+    const probe = await rt.spawn(["git", "fetch", "--force", remote, `${STATE_BRANCH}:${PROBE_REF}`], { cwd, env });
+    if (probe.exitCode !== 0)
+        throw new Error(`the push of the locks was refused and ${STATE_BRANCH} could not be read again from ${remote}: ${probe.stderr.trim()}`);
+    try {
+        if (parent) {
+            const contains = await rt.spawn(["git", "merge-base", "--is-ancestor", parent, PROBE_REF], { cwd, env });
+            if (contains.exitCode !== 0)
+                throw new Error(`the push of the locks was refused, and the local ${STATE_BRANCH} holds commits ${remote} does not; push or fetch ${STATE_BRANCH} and lock again`);
+        }
+        const tip = (await rt.spawn(["git", "rev-parse", "--verify", PROBE_REF], { cwd, env })).stdout.trim();
+        const moved = await rt.spawn(["git", "update-ref", `refs/heads/${STATE_BRANCH}`, tip, ours], { cwd, env });
+        if (moved.exitCode !== 0)
+            throw new Error(`could not drop the refused lock commit from ${STATE_BRANCH}: ${moved.stderr.trim()}`);
+        await rt.spawn(["git", "update-ref", `refs/remotes/${remote}/${STATE_BRANCH}`, tip], { cwd, env });
+    }
+    finally {
+        await rt.spawn(["git", "update-ref", "-d", PROBE_REF], { cwd, env });
+    }
+}
+/**
+ * Write `next` over the file read at `sha`, then push. Returns null when the
+ * branch moved under the write (locally or on the remote), so the caller
+ * reads and decides again.
+ */
+async function writeAndPush(gate, sha, next, message, cwd) {
+    const parent = await localTip(cwd);
+    let commit;
+    try {
+        commit = await writeBlobToPath(LOCKS_DIR, `${gate}.json`, renderTargetLocks(next), message, { cwd, expectPriorPathSha: sha });
+    }
+    catch (err) {
+        if (err instanceof RefCASConflictError)
+            return null;
+        throw err;
+    }
+    const push = await pushLifecycleStatus({ cwd });
+    switch (push.status) {
+        case "pushed":
+            return { pushed: true };
+        case "no-remote":
+        case "not-recorded":
+            return { pushed: false };
+        case "stale":
+            await dropRefusedWrite(push.remote, commit, parent, cwd);
+            await fetchForLocks(cwd);
+            return null;
+        case "failed":
+            throw new Error(`the locks were written but the push of ${STATE_BRANCH} to ${push.remote} failed, so they do not count yet: ${push.stderr}`);
+    }
+}
+/**
+ * Lock `targets` for pull request `holder.pr`. A target locked by another
+ * pull request that is still open is held, and nothing is locked. A target
+ * locked by one that merged or closed is taken over, and its lock dropped.
+ * Targets this pull request already holds stay its own, with the new head.
+ * An apply or a `chant lock` takes over the pull request's own plan locks;
+ * a plan keeps its own apply and `chant lock` locks as they are. With
+ * `releaseStalePlan`, the pull request's plan locks on targets it no longer
+ * reaches are released.
+ */
+export async function takeTargetLocks(gate, targets, holder, opts = {}) {
+    const problem = targetLockGateProblem(gate);
+    if (problem)
+        throw new Error(problem);
+    for (const t of targets)
+        if (t.trim() === "")
+            throw new Error("a lock target is a non-empty name");
+    const wanted = [...new Set(targets)].sort();
+    const open = openMemo(opts.isOpen);
+    await fetchForLocks(opts.cwd);
+    for (let attempt = 1; attempt <= ATTEMPTS; attempt++) {
+        const { sha, file } = await readCurrent(gate, opts.cwd);
+        const held = await heldIn(file, wanted, holder.pr, open);
+        if (held.length > 0)
+            return { ok: false, held };
+        const next = { version: 1, locks: {} };
+        const released = [];
+        const expired = [];
+        for (const [target, l] of Object.entries(file.locks)) {
+            if (l.pr === holder.pr) {
+                if (opts.releaseStalePlan && l.stage === "plan" && !wanted.includes(target)) {
+                    released.push(target);
+                    continue;
+                }
+            }
+            else if (opts.isOpen && !(await open(l.pr))) {
+                expired.push(target);
+                continue;
+            }
+            next.locks[target] = l;
+        }
+        for (const target of wanted) {
+            const own = file.locks[target];
+            next.locks[target] = holder.stage === "plan" && own?.pr === holder.pr && own.stage !== "plan" ? own : holder;
+        }
+        const done = { ok: true, taken: wanted, released: released.sort(), expired: expired.sort() };
+        if (renderTargetLocks(next) === renderTargetLocks(file) && sha !== null)
+            return { ...done, pushed: false };
+        if (wanted.length === 0 && released.length === 0 && expired.length === 0)
+            return { ...done, pushed: false };
+        const wrote = await writeAndPush(gate, sha, next, `Lock ${wanted.length} target${wanted.length === 1 ? "" : "s"} of ${gate} for pull request ${holder.pr} (${holder.stage})`, opts.cwd);
+        if (wrote)
+            return { ...done, pushed: wrote.pushed };
+    }
+    throw new Error(`could not write the locks of ${gate}: ${STATE_BRANCH} kept moving; lock again`);
+}
+/**
+ * Release the locks pull request `pr` holds on `gate`: every one, or only
+ * those on `targets`. Returns the targets released, sorted.
+ */
+export async function releaseTargetLocks(gate, pr, opts = {}) {
+    const problem = targetLockGateProblem(gate);
+    if (problem)
+        throw new Error(problem);
+    await fetchForLocks(opts.cwd);
+    for (let attempt = 1; attempt <= ATTEMPTS; attempt++) {
+        const { sha, file } = await readCurrent(gate, opts.cwd);
+        const mine = Object.keys(file.locks)
+            .filter((t) => file.locks[t].pr === pr && (!opts.targets || opts.targets.includes(t)))
+            .sort();
+        if (mine.length === 0)
+            return { released: [], pushed: false };
+        const next = { version: 1, locks: Object.fromEntries(Object.entries(file.locks).filter(([t]) => !mine.includes(t))) };
+        const wrote = await writeAndPush(gate, sha, next, `Unlock ${mine.length} target${mine.length === 1 ? "" : "s"} of ${gate} held by pull request ${pr}`, opts.cwd);
+        if (wrote)
+            return { released: mine, pushed: wrote.pushed };
+    }
+    throw new Error(`could not write the locks of ${gate}: ${STATE_BRANCH} kept moving; unlock again`);
+}
+/** The lock file's path for the project at `cwd`, for messages. */
+export async function targetLockPathAt(gate, cwd) {
+    const { prefix } = await resolveMemberLedger(cwd ?? process.cwd());
+    return targetLockPath(gate, prefix);
+}
+const STAGE_WORDS = { plan: "planned", apply: "applied", lock: "locked with chant lock" };
+/**
+ * One line naming the targets others hold, for a refusal or a note.
+ * `name` says how the forge names a holder (GitLab: `merge request !7`).
+ */
+export function describeHeldTargetLocks(held, name = (pr) => `pull request ${pr}`) {
+    const byPr = new Map();
+    for (const h of held)
+        byPr.set(h.pr, [...(byPr.get(h.pr) ?? []), h]);
+    return [...byPr]
+        .map(([pr, hs]) => `${hs.map((h) => h.target).join(", ")} ${hs.length === 1 ? "is" : "are"} locked by ${name(pr)} (${STAGE_WORDS[hs[0].stage]} by ${hs[0].by})`)
+        .join("; ");
+}

package/dist/op/activities/activity-contracts.d.ts

@@ -121,6 +121,36 @@ export declare const behaviourFindingContract: import("../index.js").ActivityCon
     pullRequest?: string | undefined;
     mergeRequest?: string | undefined;
 }>;
+/**
+ * The review agent (#4299). `changeSet` is `composeChangeSet`'s document,
+ * checked only for the fields the prompt reads. `returns` names what a later
+ * step may read; no gate reads it.
+ */
+export declare const reviewAgentContract: import("../index.js").ActivityContract<{
+    op: string;
+    changeSet?: {
+        [x: string]: unknown;
+        digest: string;
+        entries: unknown[];
+    } | undefined;
+    changeSetFile?: string | undefined;
+    mode?: "comment" | "report" | undefined;
+    title?: string | undefined;
+    description?: string | undefined;
+    base?: string | undefined;
+    instructions?: string | undefined;
+    command?: string | undefined;
+    keyEnv?: string | undefined;
+    timeout?: number | undefined;
+}, {
+    mode: "comment" | "report";
+    risk: "high" | "low" | "medium" | "unknown";
+    exitCode: number | null;
+    summary: string;
+    commentUrl?: string | undefined;
+    pullRequest?: string | undefined;
+    mergeRequest?: string | undefined;
+}>;
 /**
  * The propose-only template upgrade (#2550, ws-032). `args` mirrors
  * `ProposeWorkspaceUpgradeArgs` without its test hooks. `returns` names what

package/dist/op/activities/activity-contracts.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"activity-contracts.d.ts","sourceRoot":"","sources":["../../../src/op/activities/activity-contracts.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAMH,eAAO,MAAM,yBAAyB;;SAGrC,CAAC;AAEF,eAAO,MAAM,qBAAqB;;;;;;;EAIjC,CAAC;AAEF;;;;;;;;;GASG;AACH,eAAO,MAAM,gBAAgB;;;;;;;;;;;;;;;;;;;;;;EAmB5B,CAAC;AAEF,eAAO,MAAM,iBAAiB;;;;;;;;;EAgB7B,CAAC;AAEF,eAAO,MAAM,qBAAqB;;SAGjC,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,wBAAwB;;;;;;;;;EAUpC,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,wBAAwB;;;;;;;;;;;;;;;;;;;EAuBpC,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,+BAA+B;;;;;;;;;;;;;;;;;;;;;;;;;;EA8B3C,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,sBAAsB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAgClC,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,oBAAoB;;;;;;;;;;;;;;;;;;;;;;EAkBhC,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,qBAAqB;;;;;;;;;;;;EAIjC,CAAC;AAOF,eAAO,MAAM,wBAAwB;;;;;;;;;;;;;EAIpC,CAAC;AAEF,eAAO,MAAM,8BAA8B;;;;;;;;;;;;;;EAI1C,CAAC;AAEF,eAAO,MAAM,yBAAyB;;;;;;;;;;;;;;EAIrC,CAAC;AAEF,eAAO,MAAM,mBAAmB;;;;;;;;;;;EAW/B,CAAC;AAEF,eAAO,MAAM,qBAAqB;;;;;;;;;;;;;;;;EAWjC,CAAC;AAUF,eAAO,MAAM,cAAc;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EA6B1B,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,2BAA2B;;;;;;;;;;;;;;;;EAoBvC,CAAC;AAEF,eAAO,MAAM,6BAA6B;;;;;;;;;;;;;;;;EAWzC,CAAC;AAWF,eAAO,MAAM,mBAAmB;;;;;;;;;;;EAQ/B,CAAC;AAEF,eAAO,MAAM,oBAAoB;;;;YAIhC,CAAC;AAEF,eAAO,MAAM,kBAAkB;;;;;;;;;;;;;;;;;;;;;EAU9B,CAAC;AAEF,eAAO,MAAM,oBAAoB;;;;;;;;;;;;;EAIhC,CAAC;AAEF,eAAO,MAAM,oBAAoB;;;;;;;;;;;;EAIhC,CAAC;AAEF,eAAO,MAAM,qBAAqB;;;;;;;;;;;;;;;EASjC,CAAC"}
+{"version":3,"file":"activity-contracts.d.ts","sourceRoot":"","sources":["../../../src/op/activities/activity-contracts.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAMH,eAAO,MAAM,yBAAyB;;SAGrC,CAAC;AAEF,eAAO,MAAM,qBAAqB;;;;;;;EAIjC,CAAC;AAEF;;;;;;;;;GASG;AACH,eAAO,MAAM,gBAAgB;;;;;;;;;;;;;;;;;;;;;;EAmB5B,CAAC;AAEF,eAAO,MAAM,iBAAiB;;;;;;;;;EAgB7B,CAAC;AAEF,eAAO,MAAM,qBAAqB;;SAGjC,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,wBAAwB;;;;;;;;;EAUpC,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,wBAAwB;;;;;;;;;;;;;;;;;;;EAuBpC,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,mBAAmB;;;;;;;;;;;;;;;;;;;;;;;;EAwB/B,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,+BAA+B;;;;;;;;;;;;;;;;;;;;;;;;;;EA8B3C,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,sBAAsB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAgClC,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,oBAAoB;;;;;;;;;;;;;;;;;;;;;;EAkBhC,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,qBAAqB;;;;;;;;;;;;EAIjC,CAAC;AAOF,eAAO,MAAM,wBAAwB;;;;;;;;;;;;;EAIpC,CAAC;AAEF,eAAO,MAAM,8BAA8B;;;;;;;;;;;;;;EAI1C,CAAC;AAEF,eAAO,MAAM,yBAAyB;;;;;;;;;;;;;;EAIrC,CAAC;AAEF,eAAO,MAAM,mBAAmB;;;;;;;;;;;EAW/B,CAAC;AAEF,eAAO,MAAM,qBAAqB;;;;;;;;;;;;;;;;EAWjC,CAAC;AAUF,eAAO,MAAM,cAAc;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EA6B1B,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,2BAA2B;;;;;;;;;;;;;;;;EAoBvC,CAAC;AAEF,eAAO,MAAM,6BAA6B;;;;;;;;;;;;;;;;EAWzC,CAAC;AAWF,eAAO,MAAM,mBAAmB;;;;;;;;;;;EAQ/B,CAAC;AAEF,eAAO,MAAM,oBAAoB;;;;YAIhC,CAAC;AAEF,eAAO,MAAM,kBAAkB;;;;;;;;;;;;;;;;;;;;;EAU9B,CAAC;AAEF,eAAO,MAAM,oBAAoB;;;;;;;;;;;;;EAIhC,CAAC;AAEF,eAAO,MAAM,oBAAoB;;;;;;;;;;;;EAIhC,CAAC;AAEF,eAAO,MAAM,qBAAqB;;;;;;;;;;;;;;;EASjC,CAAC"}

package/dist/op/activities/activity-contracts.js

@@ -107,6 +107,32 @@ export const behaviourFindingContract = activityContract("behaviourFinding", z.s
     pullRequest: z.string().optional(),
     mergeRequest: z.string().optional(),
 }));
+/**
+ * The review agent (#4299). `changeSet` is `composeChangeSet`'s document,
+ * checked only for the fields the prompt reads. `returns` names what a later
+ * step may read; no gate reads it.
+ */
+export const reviewAgentContract = activityContract("reviewAgent", z.strictObject({
+    op: z.string(),
+    changeSet: z.object({ digest: z.string(), entries: z.array(z.unknown()) }).passthrough().optional(),
+    changeSetFile: z.string().optional(),
+    mode: z.enum(["comment", "report"]).optional(),
+    title: z.string().optional(),
+    description: z.string().optional(),
+    base: z.string().optional(),
+    instructions: z.string().optional(),
+    command: z.string().optional(),
+    keyEnv: z.string().optional(),
+    timeout: z.number().positive().optional(),
+}), z.object({
+    mode: z.enum(["comment", "report"]),
+    risk: z.enum(["low", "medium", "high", "unknown"]),
+    exitCode: z.number().nullable(),
+    summary: z.string(),
+    commentUrl: z.string().optional(),
+    pullRequest: z.string().optional(),
+    mergeRequest: z.string().optional(),
+}));
 /**
  * The propose-only template upgrade (#2550, ws-032). `args` mirrors
  * `ProposeWorkspaceUpgradeArgs` without its test hooks. `returns` names what

package/dist/op/activities/index.d.ts

@@ -38,6 +38,8 @@ export { lexiconUpgrade, isPinned, isRolling, severityToLabel, upgradeBranchName
 export type { LexiconUpgradeArgs, LexiconUpgradeResult, LexiconUpgradeMode, SupportedLexicon, SemverLabel, CheckPinnedFn, CheckRollingFn, GhRunner, ApplyBumpFn, } from "./lexicon-upgrade.js";
 export { predictBehaviour, behaviourFinding, behaviourFindingMarker, declaredEdgeCoverage, baseRefFrom, headRefFrom, noBaseRefMessage, noContributedRowsMessage, } from "./predict-behaviour.js";
 export type { PredictBehaviourArgs, BehaviourFindingArgs, BehaviourFindingResult, BehaviourFindingMode, BehaviourFindingDeps, BaseCheckout, } from "./predict-behaviour.js";
+export { reviewAgent, reviewMarker } from "./review-agent.js";
+export type { ReviewAgentArgs, ReviewAgentResult, ReviewAgentMode, ReviewRisk } from "./review-agent.js";
 export { proposeWorkspaceUpgrade } from "./propose-upgrade.js";
 export type { ProposeWorkspaceUpgradeArgs, ProposeWorkspaceUpgradeResult, ProposeUpgradeMode, CommandRunner, } from "./propose-upgrade.js";
 export { changeCoverage } from "./change-coverage.js";

package/dist/op/activities/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/op/activities/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/op/activities/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AACrC,YAAY,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAQ9C,OAAO,EAAE,YAAY,EAAE,MAAM,QAAQ,CAAC;AACtC,YAAY,EAAE,gBAAgB,EAAE,MAAM,QAAQ,CAAC;AAK/C,OAAO,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AACnC,YAAY,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAE5D,OAAO,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,cAAc,CAAC;AAEnD,OAAO,EAAE,aAAa,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAC7E,YAAY,EAAE,iBAAiB,EAAE,mBAAmB,EAAE,eAAe,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,mBAAmB,EAAE,MAAM,kBAAkB,CAAC;AAC3J,OAAO,EAAE,mBAAmB,EAAE,qBAAqB,EAAE,MAAM,mBAAmB,CAAC;AAC/E,YAAY,EAAE,uBAAuB,EAAE,yBAAyB,EAAE,yBAAyB,EAAE,2BAA2B,EAAE,MAAM,mBAAmB,CAAC;AACpJ,YAAY,EAAE,aAAa,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAE7D,OAAO,EAAE,iBAAiB,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC/D,OAAO,EAAE,gBAAgB,EAAE,sBAAsB,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AAC3F,YAAY,EAAE,oBAAoB,EAAE,sBAAsB,EAAE,0BAA0B,EAAE,qBAAqB,EAAE,mBAAmB,EAAE,MAAM,cAAc,CAAC;AACzJ,YAAY,EAAE,qBAAqB,EAAE,iBAAiB,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AAEjG,OAAO,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAC3C,YAAY,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAEpD,OAAO,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAC7C,YAAY,EAAE,eAAe,EAAE,iBAAiB,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AAiB1F,OAAO,EACL,WAAW,EACX,aAAa,EACb,sBAAsB,EACtB,yBAAyB,EACzB,uBAAuB,EACvB,mBAAmB,GACpB,MAAM,aAAa,CAAC;AACrB,YAAY,EAAE,eAAe,EAAE,eAAe,EAAE,aAAa,EAAE,cAAc,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAEvH,OAAO,EAAE,WAAW,EAAE,eAAe,EAAE,iBAAiB,EAAE,MAAM,SAAS,CAAC;AAC1E,YAAY,EACV,eAAe,EACf,iBAAiB,EACjB,mBAAmB,EACnB,qBAAqB,EACrB,WAAW,EACX,UAAU,EACV,UAAU,EACV,YAAY,EACZ,UAAU,EACV,UAAU,EACV,cAAc,EACd,iBAAiB,EACjB,eAAe,EACf,UAAU,EACV,WAAW,GACZ,MAAM,SAAS,CAAC;AAKjB,OAAO,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AACtC,YAAY,EAAE,cAAc,EAAE,MAAM,UAAU,CAAC;AAE/C,OAAO,EAAE,aAAa,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AACrE,YAAY,EAAE,iBAAiB,EAAE,mBAAmB,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAE7F,OAAO,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAC/C,YAAY,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAC;AAE5E,OAAO,EAAE,wBAAwB,EAAE,gBAAgB,EAAE,wBAAwB,EAAE,MAAM,kBAAkB,CAAC;AACxG,YAAY,EACV,iBAAiB,EACjB,mBAAmB,EACnB,iBAAiB,EACjB,oBAAoB,EACpB,wBAAwB,EACxB,iBAAiB,EACjB,mBAAmB,GACpB,MAAM,kBAAkB,CAAC;AAE1B,OAAO,EAAE,wBAAwB,EAAE,mBAAmB,EAAE,wBAAwB,EAAE,MAAM,kBAAkB,CAAC;AAC3G,YAAY,EACV,iBAAiB,EACjB,mBAAmB,EACnB,iBAAiB,EACjB,oBAAoB,EACpB,wBAAwB,EACxB,eAAe,EACf,iBAAiB,EACjB,qBAAqB,GACtB,MAAM,kBAAkB,CAAC;AAE1B,OAAO,EAAE,YAAY,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAC5D,YAAY,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,gBAAgB,EAAE,sBAAsB,EAAE,MAAM,YAAY,CAAC;AAEjH,OAAO,EACL,cAAc,EACd,QAAQ,EACR,SAAS,EACT,eAAe,EACf,iBAAiB,EACjB,cAAc,EACd,mBAAmB,GACpB,MAAM,mBAAmB,CAAC;AAC3B,YAAY,EACV,kBAAkB,EAClB,oBAAoB,EACpB,kBAAkB,EAClB,gBAAgB,EAChB,WAAW,EACX,aAAa,EACb,cAAc,EACd,QAAQ,EACR,WAAW,GACZ,MAAM,mBAAmB,CAAC;AAM3B,OAAO,EACL,gBAAgB,EAChB,gBAAgB,EAChB,sBAAsB,EACtB,oBAAoB,EACpB,WAAW,EACX,WAAW,EACX,gBAAgB,EAChB,wBAAwB,GACzB,MAAM,qBAAqB,CAAC;AAC7B,YAAY,EACV,oBAAoB,EACpB,oBAAoB,EACpB,sBAAsB,EACtB,oBAAoB,EACpB,oBAAoB,EACpB,YAAY,GACb,MAAM,qBAAqB,CAAC;AAK7B,OAAO,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAC3D,YAAY,EAAE,eAAe,EAAE,iBAAiB,EAAE,eAAe,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AAItG,OAAO,EAAE,uBAAuB,EAAE,MAAM,mBAAmB,CAAC;AAC5D,YAAY,EACV,2BAA2B,EAC3B,6BAA6B,EAC7B,kBAAkB,EAClB,aAAa,GACd,MAAM,mBAAmB,CAAC;AAI3B,OAAO,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AACnD,YAAY,EAAE,kBAAkB,EAAE,oBAAoB,EAAE,MAAM,mBAAmB,CAAC;AAOlF,OAAO,EAAE,MAAM,EAAE,MAAM,UAAU,CAAC;AAClC,YAAY,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AAGzD,OAAO,EAAE,WAAW,EAAE,YAAY,EAAE,UAAU,EAAE,YAAY,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,WAAW,CAAC;AAC7G,YAAY,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,kBAAkB,EAAE,mBAAmB,EAAE,iBAAiB,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC"}

package/dist/op/activities/index.js

@@ -43,6 +43,10 @@ export { lexiconUpgrade, isPinned, isRolling, severityToLabel, upgradeBranchName
 // collects every exported function as an activity, so `createBehaviourFinding`
 // and `checkoutBase` stay on the module.
 export { predictBehaviour, behaviourFinding, behaviourFindingMarker, declaredEdgeCoverage, baseRefFrom, headRefFrom, noBaseRefMessage, noContributedRowsMessage, } from "./predict-behaviour.js";
+// The review agent (#4299): a model reviews the change set against the pull
+// request's own text and posts one sticky note. Only the activity and its
+// marker are re-exported, since the registry collects every exported function.
+export { reviewAgent, reviewMarker } from "./review-agent.js";
 // The propose-only template upgrade (#2550). Loads the workspace code on first
 // call only, so importing this module loads nothing under `workspace/`.
 export { proposeWorkspaceUpgrade } from "./propose-upgrade.js";

package/dist/op/activities/review-agent.d.ts

@@ -0,0 +1,137 @@
+/**
+ * The `reviewAgent` activity (#4299): a model compares what a pull request
+ * says it does with what its change set would do, and the finding is posted
+ * as one sticky note on the pull request.
+ *
+ * Lifted from terragucci's `review-agent.ts` (INTENTIUS/terragucci e6cb431,
+ * `packages/terragucci/src/review-agent.ts`): the prompt, the `risk:` line,
+ * the default command and the quoting of untrusted text are its. What differs
+ * is where the plan comes from. terragucci reads a Terraform plan note; here
+ * the input is the change-set document `composeChangeSet` returns, so every
+ * lexicon's plan can be reviewed.
+ *
+ * The review never approves and never gates. The activity posts through
+ * {@link reconcilePr} in `comment` mode and nothing else: no review, no
+ * approval, no status. Its result is data a later step may read; no gate reads
+ * it, and an agent principal never counts toward a quorum
+ * (`../gate-approval.ts`).
+ *
+ * The model command runs with the prompt on stdin and prints the review on
+ * stdout. Its environment is built from scratch ({@link reviewCommandEnv}):
+ * the model key and a few process basics, never a forge token. The
+ * instructions file is read from the base branch with `git show`, so a pull
+ * request that edits it changes nothing until it merges.
+ */
+import type { ChangeSetDocument } from "../../change-set.js";
+import { reconcilePr } from "./reconcile.js";
+/** The Claude Code release the default review command runs (terragucci's pin). */
+export declare const REVIEW_CLAUDE_CODE_VERSION = "2.1.290";
+/**
+ * The default review command: Claude Code in print mode with no tools, no MCP
+ * servers, no project settings and no session kept. The prompt arrives on
+ * stdin and the review leaves on stdout.
+ */
+export declare const REVIEW_COMMAND: string;
+/** Where the review instructions live on the base branch unless `instructions` names another file. */
+export declare const REVIEW_INSTRUCTIONS = ".chant/review.md";
+/** The environment variable that holds the model's key unless `keyEnv` names another. */
+export declare const REVIEW_KEY_ENV = "ANTHROPIC_API_KEY";
+export declare const REVIEW_RISKS: readonly ["low", "medium", "high"];
+export type ReviewRisk = (typeof REVIEW_RISKS)[number];
+/** How the review leaves the run. */
+export type ReviewAgentMode = "comment" | "report";
+export interface ReviewAgentArgs {
+    /** The Op this step belongs to. It keys the note's marker ({@link reviewMarker}). */
+    op: string;
+    /** The change set to review: `composeChangeSet`'s `document`, usually a step output. */
+    changeSet?: ChangeSetDocument;
+    /** A file holding the change-set document, read when `changeSet` is not given. */
+    changeSetFile?: string;
+    /** `comment` posts the note on the triggering pull or merge request; `report` returns it. Default: `comment`. */
+    mode?: ReviewAgentMode;
+    /** The pull request's title. Default: read from the run's event. */
+    title?: string;
+    /** The pull request's description. Default: read from the run's event. */
+    description?: string;
+    /** The base branch the instructions are read from. Default: `GITHUB_BASE_REF`, then `CI_MERGE_REQUEST_TARGET_BRANCH_NAME`. */
+    base?: string;
+    /** The instructions file on the base branch. Default: {@link REVIEW_INSTRUCTIONS}. */
+    instructions?: string;
+    /** The model command, run through the shell. Default: {@link REVIEW_COMMAND}. */
+    command?: string;
+    /** The variable that holds the model's key, the one secret the command sees. Default: {@link REVIEW_KEY_ENV}. */
+    keyEnv?: string;
+    /** Minutes the command may run. Default: 10. */
+    timeout?: number;
+}
+export interface ReviewAgentResult {
+    mode: ReviewAgentMode;
+    /** The risk the review's last `risk:` line names, or `unknown`. Informational: nothing gates on it. */
+    risk: ReviewRisk | "unknown";
+    /** The command's exit code, or null when it was killed or could not start. */
+    exitCode: number | null;
+    /** The note's Markdown, whether or not it was posted. */
+    summary: string;
+    commentUrl?: string;
+    pullRequest?: string;
+    mergeRequest?: string;
+}
+/** The note's hidden marker, keyed on the Op. Its prefix differs from every `reconcilePr` and behaviour marker. */
+export declare function reviewMarker(op: string): string;
+/** Text as it goes between the prompt's tags: a closing tag of ours inside it cannot end the section. */
+export declare function quoted(text: string): string;
+/** The change set as the prompt carries it: one line per entry that changes something, members that failed, and holes. */
+export declare function changeSetText(doc: ChangeSetDocument): string;
+export interface ReviewPromptParts {
+    title: string;
+    description: string;
+    changeSet: ChangeSetDocument;
+    /** The base branch's instructions, or undefined when it has none. */
+    instructions?: string;
+    instructionsPath: string;
+    base: string;
+}
+/** The review's prompt. Everything the author wrote and everything made from the change is quoted as data. */
+export declare function reviewPrompt(p: ReviewPromptParts): string;
+/** The risk the review's last `risk:` line names, or unknown. */
+export declare function riskOf(review: string): ReviewRisk | "unknown";
+/** The note's body. The review is the model's text: shown, never trusted, and no HTML comment of it survives. */
+export declare function reviewNoteBody(o: {
+    review: string;
+    exitCode: number | null;
+    digest: string;
+    instructions: "base" | "none";
+}): string;
+/** The variables the review command sees: the model key and process basics. Never a forge or cloud token. */
+export declare function reviewCommandEnv(env: Record<string, string | undefined>, keyEnv: string): Record<string, string>;
+/** The pull request's title and description from the run: the event payload on GitHub and Forgejo, CI variables on GitLab. */
+export declare function pullRequestTextFrom(env: Record<string, string | undefined>, payload?: unknown): {
+    title: string;
+    description: string;
+};
+/** What a run of the model command returns. */
+export interface CommandOutcome {
+    stdout: string;
+    exitCode: number | null;
+}
+export type RunReviewCommand = (command: string, input: string, env: Record<string, string>, timeoutMs: number, signal?: AbortSignal) => Promise<CommandOutcome>;
+/** Run the command through the shell with the prompt on stdin. A failure is an outcome, not a throw: the note says so. */
+export declare const runReviewCommand: RunReviewCommand;
+/** Read a file at the base branch, or undefined when it has none. */
+export type ShowAtBase = (base: string, path: string, signal?: AbortSignal) => Promise<string | undefined>;
+/** `git show` of the base branch's copy, fetching the branch at depth one first since a CI clone may not carry it. */
+export declare const showAtBase: ShowAtBase;
+export interface ReviewAgentDeps {
+    run?: RunReviewCommand;
+    show?: ShowAtBase;
+    post?: typeof reconcilePr;
+    env?: Record<string, string | undefined>;
+    /** Read the event payload. Default: `GITHUB_EVENT_PATH` parsed, or undefined. */
+    event?: () => Promise<unknown>;
+    readFile?: (path: string) => Promise<string>;
+}
+/** Build the activity with its side effects injected, so a test drives it with fakes. */
+export declare function createReviewAgent(deps?: ReviewAgentDeps): (args: ReviewAgentArgs, signal?: AbortSignal) => Promise<ReviewAgentResult>;
+/** Review the pull request's change set with the configured model and post the finding as one sticky note. Never approves, never gates. */
+export declare const reviewAgent: (args: ReviewAgentArgs, signal?: AbortSignal) => Promise<ReviewAgentResult>;
+//# sourceMappingURL=review-agent.d.ts.map

package/dist/op/activities/review-agent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"review-agent.d.ts","sourceRoot":"","sources":["../../../src/op/activities/review-agent.ts"],"names":[],"mappings":"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"}