balladeer 1.0.14 → 1.0.16

package/dist/commands/judge.d.ts

@@ -0,0 +1,271 @@
+import { type BehaviorMap } from "../behavior-map-schema.js";
+import { type HeadlessAgentOptions, type HeadlessAgentResult, type HeadlessClient, type LoginCheck } from "../headless-agent.js";
+import { type HookHost } from "../judge-hook.js";
+import { type PromiseDocument, type PromiseReader } from "../promise-meaning.js";
+/**
+ * `balladeer judge`: for a change about to leave this machine, ask the person's
+ * own coding agent, one promise at a time, whether the change keeps it.
+ *
+ * A verdict is only as good as its evidence, so the runner does not take a
+ * judge's word for a break. A judge that says "broken" must hand back a command,
+ * and the runner runs that command itself, once at head and once in a clean
+ * checkout of base: it must fail with the change and pass without it. Anything
+ * short of that is "could not tell", with the reason kept. Nothing here ever
+ * says a promise is protected; a judge's "kept" is a local reading of one
+ * change, not a check that holds.
+ */
+export declare const JUDGE_VERDICT_SCHEMA_VERSION = "balladeer-judge-verdict/v1";
+export declare const JUDGE_CONFIG_SCHEMA_VERSION = "balladeer-judge-config/v1";
+export declare const JUDGE_CONFIG_PATH = ".continuity/judge.json";
+export declare const JUDGE_LOG_DIRECTORY = ".continuity/judge-log";
+export declare const STILL_JUDGING = "still judging; rerun `balladeer judge --wait`";
+export type JudgeConfig = Readonly<{
+    schemaVersion: typeof JUDGE_CONFIG_SCHEMA_VERSION;
+    mode: "report" | "block";
+    topK: number;
+    concurrency: number;
+    budgetSeconds: number;
+    sampleBelowLine: number;
+    alwaysJudge: readonly string[];
+    client: HeadlessClient | "auto";
+    /**
+     * From the push hook, also read the change for rules no promise records and
+     * hand at most three to the pushing session as offers. Off unless set.
+     */
+    offers: boolean;
+    /**
+     * Which pushes are read when offers are on: only those that repair
+     * something ("fixes", the default), or every change ("all").
+     */
+    offersOn: "fixes" | "all";
+    /** How many offers one push may hand to the person: one by default, three at most. */
+    maxOffers: number;
+}>;
+export declare const DEFAULT_JUDGE_CONFIG: JudgeConfig;
+/**
+ * `.continuity/judge.json`, with the contract's defaults for anything absent.
+ * A field that is present and wrong keeps its default and is named, so a typo
+ * in a team's config is visible rather than quietly ignored.
+ */
+export declare function readJudgeConfig(root: string): {
+    config: JudgeConfig;
+    problems: string[];
+};
+export type JudgeVerdict = {
+    schemaVersion: typeof JUDGE_VERDICT_SCHEMA_VERSION;
+    promiseId: string;
+    semanticDigest: string;
+    base: string;
+    head: string;
+    verdict: "kept" | "broken" | "could_not_tell";
+    reproduction: {
+        command: string;
+        cwd: string;
+        failsOnHead: boolean;
+        passesOnBase: boolean;
+        digest: string;
+    } | null;
+    reproductionRejected: string | null;
+    exercisedCases: string[];
+    notes: string;
+    judge: {
+        client: HeadlessClient;
+        model: string;
+        durationMs: number;
+        inputTokens: number;
+        outputTokens: number;
+    };
+    briefRevision: string;
+    mapUsed: boolean;
+    linkedTestRun: {
+        file: string;
+        outcome: "pass" | "fail" | "error" | "none";
+    };
+};
+/** A command's exit, as one run of a reproduction or a linked test. */
+export type CommandRun = Readonly<{
+    exitCode: number | null;
+    timedOut: boolean;
+    aborted: boolean;
+    output: string;
+}>;
+export declare function runShell(command: string, cwd: string, options: Readonly<{
+    env: NodeJS.ProcessEnv;
+    timeoutMs: number;
+    signal?: AbortSignal;
+}>): Promise<CommandRun>;
+export type ReproductionCheck = Readonly<{
+    failsOnHead: boolean;
+    passesOnBase: boolean;
+    digest: string;
+    rejected: string | null;
+    /** The budget ran out while it was being run, so there is no answer yet. */
+    stopped: boolean;
+}>;
+/**
+ * Run a judge's reproduction both ways.
+ *
+ * At head, in the judge's own checkout, reset to head so a judge that left it
+ * on base cannot fool the check. At base, in a fresh checkout of base, with the
+ * files the judge added carried across so a new test exists on both sides. It
+ * must exit non-zero at head and zero at base; either disagreeing rejects it,
+ * and the reason says which.
+ */
+export declare function verifyReproduction(input: Readonly<{
+    root: string;
+    headTree: string;
+    head: string;
+    base: string;
+    command: string;
+    cwd: string;
+    env: NodeJS.ProcessEnv;
+    timeoutMs?: number;
+    signal?: AbortSignal;
+    scratch?: string;
+}>): Promise<ReproductionCheck>;
+/**
+ * How this repository runs one test file, when it can be told from the files
+ * alone. A runner that cannot be told is `none`, and the judge is left to find
+ * its own way.
+ */
+export declare function linkedTestCommand(tree: string, file: string): string | undefined;
+type JudgeAnswer = Readonly<{
+    verdict: JudgeVerdict["verdict"];
+    reproduction?: Readonly<{
+        command: string;
+        cwd: string;
+    }>;
+    exercisedCases: string[];
+    notes: string;
+}>;
+/** The judge's final JSON, read strictly enough that a malformed answer is not a verdict. */
+export declare function readJudgeAnswer(json: Record<string, unknown> | undefined): JudgeAnswer | undefined;
+export type JudgePromiseInput = Readonly<{
+    root: string;
+    promise: PromiseDocument;
+    map?: BehaviorMap;
+    base: string;
+    head: string;
+    changedFiles: readonly string[];
+    login: LoginCheck;
+    env: NodeJS.ProcessEnv;
+    timeoutMs?: number;
+    signal?: AbortSignal;
+    scratch?: string;
+    runAgent?: (options: HeadlessAgentOptions) => Promise<HeadlessAgentResult>;
+}>;
+export type JudgeOutcome = Readonly<{
+    status: "judged";
+    verdict: JudgeVerdict;
+}> | Readonly<{
+    status: "stopped";
+}> | Readonly<{
+    status: "not_judged";
+    reason: string;
+}>;
+/**
+ * One promise judged against one change, with its reproduction verified.
+ *
+ * Returns `stopped` when the caller's budget ran out first, which is not a
+ * verdict and is never logged as one: the push is either held or told the
+ * judge is still running, never let through as if it had been judged.
+ */
+export declare function judgePromise(input: JudgePromiseInput): Promise<JudgeOutcome>;
+export type JudgeArguments = Readonly<{
+    promises?: readonly string[];
+    topK?: number;
+    base?: string;
+    head?: string;
+    json: boolean;
+    mode?: "report" | "block";
+    wait: boolean;
+    hook?: HookHost;
+    installHook?: HookHost | "agents";
+    fromFile?: string;
+    map?: string;
+    repo?: string;
+    client?: HeadlessClient | "auto";
+    repository?: string;
+    controlPlane: string;
+}>;
+export declare const JUDGE_USAGE = "  npx -y balladeer@latest judge [--promises <id,id>] [--top <k>] [--base <ref>] [--head <ref>]\n                  [--report-only | --block] [--wait] [--json] [--client auto|claude|codex]\n                  [--from-file <promise.json> [--map <map.json>]]\n                  [--hook claude|codex|git] [--install-hook [claude|codex|git]]\n      Judge whether this change keeps the promises it could break, one promise\n      at a time, on your own Claude Code or Codex login. A break counts only\n      with a command that fails with the change and passes without it, and\n      this command runs it both ways itself; anything unproven is \"could not\n      tell\". Report mode prints one line per promise and never stops anything;\n      --block exits 2 on a reproduced break, and when judges are still running\n      at the time limit it holds the push rather than letting it through.\n      --wait runs without the time limit. Promises come from --promises, else\n      the top of `balladeer risk`, else every mapped promise, plus\n      .continuity/judge.json's alwaysJudge and a small random sample. Verdicts\n      are kept in .continuity/judge-log/, which git ignores. --install-hook\n      adds the push hook to .claude/settings.json and .codex/hooks.json, or\n      .git/hooks/pre-push with git. With \"offers\": true in that file, the push\n      hook also reads the change for rules no promise records and offers at\n      most three to whoever is pushing; it records nothing and never holds a\n      push (see `balladeer offers`).\n";
+export declare function parseJudgeArguments(argv: readonly string[]): JudgeArguments;
+/** The subset of `balladeer-risk/v1` this command reads. */
+export type RiskEntry = Readonly<{
+    promiseId: string;
+    score: number;
+    band: string;
+}>;
+/** Read a risk report out of whatever `balladeer risk --json` printed. */
+export declare function readRiskOutput(stdout: string): RiskEntry[] | undefined;
+/**
+ * The commit a change is measured from: the fork point with the remote default
+ * branch, else with this branch's upstream, else the parent of head.
+ */
+export declare function defaultBase(root: string, head: string): Promise<string | undefined>;
+export declare function changedFiles(root: string, base: string, head: string): Promise<string[]>;
+export type Selection = Readonly<{
+    promiseId: string;
+    why: "file" | "named" | "risk" | "sample" | "mapped" | "always";
+}>;
+/**
+ * Which promises to judge: named ones, else the top of the risk report plus a
+ * random sample below its line, else every mapped promise; then `alwaysJudge`.
+ * The sample is what keeps the ranking honest: a break found below the line is
+ * a miss the ranking made, counted rather than never seen.
+ */
+export declare function selectPromises(input: Readonly<{
+    named?: readonly string[];
+    risk?: readonly RiskEntry[];
+    mapped: readonly string[];
+    config: JudgeConfig;
+    topK?: number;
+    random: () => number;
+}>): Selection[];
+/**
+ * Append verdicts to today's log. The directory carries its own `.gitignore`,
+ * so a verdict log never lands in a commit whatever the repository ignores.
+ */
+export declare function appendVerdicts(root: string, verdicts: readonly JudgeVerdict[], now: Date): void;
+/** A verdict already reached for exactly this promise, meaning, change and brief. */
+export declare function findLoggedVerdict(root: string, key: Readonly<{
+    promiseId: string;
+    semanticDigest: string;
+    base: string;
+    head: string;
+}>, now: Date): JudgeVerdict | undefined;
+/** One line per verdict, the promise named by its title and id. */
+export declare function verdictLine(verdict: JudgeVerdict, title: string, reused?: boolean): string;
+export type JudgeDependencies = Readonly<{
+    runAgent?: (options: HeadlessAgentOptions) => Promise<HeadlessAgentResult>;
+    resolveLogin?: (requested: HeadlessClient | "auto", prefer?: HeadlessClient) => Promise<LoginCheck | undefined>;
+    riskReport?: (root: string, base: string, head: string) => Promise<readonly RiskEntry[] | undefined>;
+    /** `null` means "no connection", without trying to find one. */
+    reader?: PromiseReader | null;
+    random?: () => number;
+    now?: () => Date;
+    stdin?: () => Promise<string>;
+    scratch?: string;
+    /** Replaces the judge itself, for tests of the flow around it. */
+    judge?: (input: JudgePromiseInput) => Promise<JudgeOutcome>;
+    /** The agent run that reads the change for offers, when they are on. */
+    offerAgent?: (options: HeadlessAgentOptions) => Promise<HeadlessAgentResult>;
+}>;
+export type JudgeRunOptions = Readonly<{
+    args: JudgeArguments;
+    cwd: string;
+    environment: NodeJS.ProcessEnv;
+    write: (text: string) => void;
+    error: (text: string) => void;
+    deps?: JudgeDependencies;
+}>;
+/** `balladeer judge`, from arguments already parsed. */
+export declare function runJudge(options: JudgeRunOptions): Promise<number>;
+/** `balladeer judge ...` from raw arguments, as `cli.ts` hands them over. */
+export declare function judgeCommand(argv: readonly string[], io: Readonly<{
+    cwd: string;
+    environment: NodeJS.ProcessEnv;
+    write: (text: string) => void;
+    error: (text: string) => void;
+}>): Promise<number>;
+export {};