balladeer 1.0.15 → 1.0.17

package/dist/commands/map.d.ts

@@ -0,0 +1,164 @@
+import { type BehaviorMap, type BehaviorMapLinkedTest } from "../behavior-map-schema.js";
+import { type HeadlessAgentOptions, type HeadlessAgentResult, type HeadlessClient, type LoginCheck } from "../headless-agent.js";
+import { type PromiseDocument, type PromiseReader } from "../promise-meaning.js";
+/** Tools a map builder or a judge may use, and the ones refused whatever else is allowed. */
+export declare const AGENT_TOOLS: readonly ["Read", "Grep", "Glob", "Bash"];
+export declare const REFUSED_TOOL_RULES: readonly ["Bash(git push:*)", "Bash(gh:*)"];
+export type MapArguments = Readonly<{
+    promiseId?: string;
+    all: boolean;
+    check: boolean;
+    stale: boolean;
+    fromFile?: string;
+    repo?: string;
+    out?: string;
+    client: HeadlessClient | "auto";
+    timeoutMs: number;
+    json: boolean;
+    repository?: string;
+    controlPlane: string;
+    /** `--link-test`: add one test to a promise's map, with no model and no server. */
+    linkTest?: Readonly<{
+        promiseId: string;
+        file: string;
+        name: string;
+        cases: string[];
+    }>;
+}>;
+export declare const MAP_USAGE = "  npx -y balladeer@latest map <promise id> | --all | --check | --stale\n                [--from-file <promise.json>] [--repo <root>] [--out <dir>]\n                [--client auto|claude|codex] [--timeout <seconds>] [--json]\n  npx -y balladeer@latest map --link-test <promise id> <test file>\n                [--name <test name>] [--case <case id>]... [--repo <root>] [--json]\n      Build a behavior map for a promise with your own coding agent: where its\n      behavior starts, the code on its path, what it depends on, the tests that\n      exercise it and where each failing case would show. The agent works in a\n      throwaway read-only checkout, on the Claude Code or Codex login already on\n      this machine, and the map is written to .continuity/behavior-maps/<id>.json\n      for your team to commit. It never leaves this machine. --all maps every\n      agreed promise; --check reports maps whose code or meaning has moved\n      (exit 1 when any has) and --stale prints just their ids, both without a\n      model. --from-file reads the promise from a file instead of Balladeer.\n      --link-test adds a test in this repository to a promise's existing map,\n      naming the cases it covers (passing-1, failing-2), so later judges run it\n      and a change to it counts as risk to the promise. It changes nothing else\n      in the map, calls no model and sends nothing anywhere.\n";
+export declare function parseMapArguments(argv: readonly string[]): MapArguments;
+export type MapDependencies = Readonly<{
+    runAgent?: (options: HeadlessAgentOptions) => Promise<HeadlessAgentResult>;
+    /** `null` means "no connection", without looking for one. */
+    reader?: PromiseReader | null;
+    now?: () => Date;
+    login?: LoginCheck;
+}>;
+export type BuildMapInput = Readonly<{
+    root: string;
+    promise: PromiseDocument;
+    client: HeadlessClient | "auto";
+    env: NodeJS.ProcessEnv;
+    timeoutMs: number;
+    prefer?: HeadlessClient;
+    login?: LoginCheck;
+    scratch?: string;
+    now?: () => Date;
+    runAgent?: (options: HeadlessAgentOptions) => Promise<HeadlessAgentResult>;
+}>;
+export type BuildMapResult = Readonly<{
+    ok: true;
+    map: BehaviorMap;
+    agent: HeadlessAgentResult;
+    dropped: string[];
+    /** Closed-list fields the agent filled with a word the contract does not have, read as the nearest allowed one. */
+    coerced: string[];
+}> | Readonly<{
+    ok: false;
+    reason: string;
+    agent?: HeadlessAgentResult;
+    errors?: string[];
+}>;
+/**
+ * One promise's behavior map, built by the person's own agent from the code at
+ * HEAD, in a disposable checkout, and checked against the contract before it is
+ * returned. Nothing is written here; the caller decides where the map goes.
+ */
+export declare function buildBehaviorMap(input: BuildMapInput): Promise<BuildMapResult>;
+export declare function agentFailure(agent: HeadlessAgentResult): string;
+/**
+ * The agent's answer made into a map: the runner's own fields filled in, paths
+ * made repository-relative, and every entry whose file does not exist at the
+ * mapped commit dropped and named, because a map pointing at nothing reads as
+ * stale forever. The meaning excerpt is taken from the promise itself rather
+ * than from the agent's copy, so a transcription slip cannot change it.
+ */
+export declare function mapFromAgent(json: Record<string, unknown>, context: Readonly<{
+    promise: PromiseDocument;
+    sha: string;
+    client: HeadlessClient;
+    model: string;
+    at: string;
+    tree: string;
+}>): {
+    map: unknown;
+    dropped: string[];
+    coerced: string[];
+};
+export type Staleness = Readonly<{
+    stale: boolean;
+    reasons: string[];
+    /** False when no current digest was available, so meaning drift is unanswered. */
+    digestChecked: boolean;
+}>;
+/**
+ * Whether a map still points at real code, answered without a model.
+ *
+ * Stale when a mapped symbol is no longer in its file (a plain search for its
+ * name, the way a person would grep for it), when a mapped file is gone, or,
+ * when the current digest is known, when the promise's meaning has moved on
+ * since the map was built.
+ */
+export declare function mapStaleness(root: string, map: BehaviorMap, currentDigest?: string): Staleness;
+export type StoredMap = Readonly<{
+    promiseId: string;
+    path: string;
+    map?: BehaviorMap;
+    errors?: string[];
+}>;
+/** Every map in a directory, read and checked; an unreadable one is listed with why. */
+export declare function readBehaviorMaps(directory: string): StoredMap[];
+export declare function readBehaviorMap(root: string, promiseId: string): BehaviorMap | undefined;
+export type LinkTestResult = Readonly<{
+    ok: true;
+    changed: boolean;
+    path: string;
+    entry: BehaviorMapLinkedTest;
+}> | Readonly<{
+    ok: false;
+    reason: string;
+    message: string;
+}>;
+/**
+ * The map's text with one entry added at the end of its top-level
+ * `linkedTests` list, and every other character left where it was, so the
+ * change a reviewer reads is the new entry and one comma. The entry is written
+ * the way this repository's formatter writes JSON: an object per line group,
+ * two-space indents, and the case list on one line while it fits in a
+ * hundred columns. Undefined when the list cannot be found.
+ */
+export declare function insertLinkedTest(text: string, entry: BehaviorMapLinkedTest): string | undefined;
+/**
+ * Link one test in this repository to a promise's behavior map, the way a
+ * person would by hand, without a model: the test is appended to the map's
+ * `linkedTests` unless an equal entry is already there, and nothing else in
+ * the map changes. The map must already exist, the file must exist inside this
+ * repository and not be ignored by git (a test git ignores never reaches the
+ * repository's suite), the list must have room, and the result must pass the
+ * map checker. The map is written beside itself and renamed into place.
+ */
+export declare function linkTestToMap(input: Readonly<{
+    root: string;
+    directory: string;
+    cwd: string;
+    promiseId: string;
+    file: string;
+    name: string;
+    cases: readonly string[];
+}>): Promise<LinkTestResult>;
+export type MapOptions = Readonly<{
+    args: MapArguments;
+    cwd: string;
+    environment: NodeJS.ProcessEnv;
+    write: (text: string) => void;
+    deps?: MapDependencies;
+}>;
+/** `balladeer map`, from arguments already parsed. */
+export declare function runMap(options: MapOptions): Promise<number>;
+/** `balladeer map ...` from raw arguments, as `cli.ts` hands them over. */
+export declare function mapCommand(argv: readonly string[], io: Readonly<{
+    cwd: string;
+    environment: NodeJS.ProcessEnv;
+    write: (text: string) => void;
+    error: (text: string) => void;
+}>): Promise<number>;