balladeer 1.0.17 → 1.0.18

package/dist/risk/graph-cache.js

@@ -0,0 +1,291 @@
+import { createHash, randomBytes } from "node:crypto";
+import { closeSync, fstatSync, mkdirSync, openSync, readFileSync, realpathSync, renameSync, unlinkSync, writeFileSync, constants, } from "node:fs";
+import { isAbsolute, join, resolve } from "node:path";
+import { performance } from "node:perf_hooks";
+import { configHome } from "../store.js";
+import { readBlobs, resolveCommit, tryGit } from "./git.js";
+import { buildImportGraphFromParsed, isGraphSource, parseImports, } from "./import-graph.js";
+import { extensionOf, isScriptPath, isTestPath } from "./paths.js";
+import { graphTreeEntries } from "./pipeline.js";
+import { declaredSymbols, loadTypeScript } from "./symbols.js";
+/**
+ * The repository graph of one commit, built from a cache on this laptop.
+ *
+ * What a file imports and which names it declares depend only on its own
+ * content, so they are kept per blob, and a commit parses only the blobs this
+ * laptop has not read before. How those imports resolve depends on the whole
+ * tree, so that is worked out again on every build, from the cached
+ * specifiers; it is cheap. The cache sits in Balladeer's config home, one file
+ * per repository (all worktrees of a repository share it), and holds file
+ * paths' blob ids, import specifiers and declared names. It is never committed
+ * and never sent anywhere.
+ */
+/** Bumped whenever what is read out of a blob changes, so old entries are read again. */
+export const GRAPH_CACHE_VERSION = 1;
+export const GRAPH_CACHE_DIRECTORY = "graph-cache";
+const MAX_CACHE_BYTES = 256 * 1024 * 1024;
+/**
+ * Names a script file makes available beyond its declarations: `default` for
+ * `export default`, each name or alias in `export { a, b as c }`, a namespace
+ * re-export's name, and the names bound by `export const { a, b } = ...` or
+ * `export const [a, b] = ...`.
+ */
+export function exportClauseNames(text) {
+    const found = new Set();
+    const source = text.replace(/\/\*[\s\S]*?\*\//g, "");
+    if (/(?:^|[\s;])export\s+default\b/.test(source))
+        found.add("default");
+    for (const match of source.matchAll(/\bexport\s+(?:type\s+)?\{([^}]*)\}/g)) {
+        for (const part of (match[1] ?? "").split(",")) {
+            const words = part
+                .trim()
+                .replace(/^type\s+/, "")
+                .split(/\s+as\s+/);
+            const name = (words[1] ?? words[0] ?? "").trim();
+            if (/^[A-Za-z_$][\w$]*$/.test(name))
+                found.add(name);
+        }
+    }
+    for (const match of source.matchAll(/\bexport\s+\*\s+as\s+([A-Za-z_$][\w$]*)/g))
+        if (match[1] !== undefined)
+            found.add(match[1]);
+    for (const match of source.matchAll(/\bexport\s+(?:const|let|var)\s+\{([^}]*)\}\s*=/g)) {
+        for (const part of (match[1] ?? "").split(",")) {
+            const name = (part.split(":")[1] ?? part.split(":")[0] ?? "").split("=")[0]?.trim() ?? "";
+            if (/^[A-Za-z_$][\w$]*$/.test(name))
+                found.add(name);
+        }
+    }
+    for (const match of source.matchAll(/\bexport\s+(?:const|let|var)\s+\[([^\]]*)\]\s*=/g)) {
+        for (const part of (match[1] ?? "").split(",")) {
+            const name = part
+                .split("=")[0]
+                ?.replace(/^\.\.\./, "")
+                .trim() ?? "";
+            if (/^[A-Za-z_$][\w$]*$/.test(name))
+                found.add(name);
+        }
+    }
+    return [...found];
+}
+/**
+ * Whether a graph file belongs in the anchoring index: product source, so not
+ * a test, and (from `anchor-brief/v3`) not a story or a mock.
+ */
+export function isIndexSource(file) {
+    return (!isTestPath(file) &&
+        /\.(?:[cm]?[jt]sx?|py)$/.test(file) &&
+        !/\.stories\.|(?:^|\/)(?:__mocks__|mocks?|\.storybook)\//.test(file));
+}
+/** Which symbol reader a repository gets: its own TypeScript compiler, or the patterns. */
+function symbolReader(root) {
+    const typescript = loadTypeScript(root);
+    return typescript === undefined ? "regex" : `typescript@${typescript.version}`;
+}
+/** The names a file declares and exports, read the way the anchoring index reads them. */
+export function readSymbols(file, text, root) {
+    const lines = text.split("\n");
+    const exported = [];
+    const names = new Set();
+    for (const symbol of declaredSymbols(file, text, root).symbols) {
+        names.add(symbol.name);
+        const line = lines[symbol.startLine - 1] ?? "";
+        if (!/^\s*export\b/.test(line) && !/\.py$/.test(file))
+            continue;
+        if (exported.some((entry) => entry.name === symbol.name))
+            continue;
+        exported.push({ name: symbol.name, kind: symbol.kind });
+    }
+    if (isScriptPath(file))
+        for (const name of exportClauseNames(text))
+            names.add(name);
+    return { exported, names: [...names] };
+}
+function sha256(text) {
+    return createHash("sha256").update(text).digest("hex");
+}
+/** The cache file of the repository a checkout belongs to, shared by all its worktrees. */
+export function graphCachePath(root, environment) {
+    let common = tryGit(root, ["rev-parse", "--git-common-dir"])?.trim() ?? "";
+    if (common === "")
+        common = join(root, ".git");
+    if (!isAbsolute(common))
+        common = resolve(root, common);
+    try {
+        common = realpathSync(common);
+    }
+    catch {
+        /* A path that cannot be resolved is keyed as written. */
+    }
+    return join(configHome(environment), GRAPH_CACHE_DIRECTORY, `${sha256(common).slice(0, 32)}.json`);
+}
+function readCache(path) {
+    let fd;
+    try {
+        fd = openSync(path, constants.O_RDONLY | constants.O_NOFOLLOW);
+        const stat = fstatSync(fd);
+        if (!stat.isFile() || stat.size > MAX_CACHE_BYTES)
+            return new Map();
+        const parsed = JSON.parse(readFileSync(fd, "utf8"));
+        if (parsed?.version !== GRAPH_CACHE_VERSION || parsed.blobs === null)
+            return new Map();
+        if (typeof parsed.blobs !== "object")
+            return new Map();
+        return new Map(Object.entries(parsed.blobs));
+    }
+    catch {
+        return new Map();
+    }
+    finally {
+        if (fd !== undefined)
+            closeSync(fd);
+    }
+}
+function writeCache(path, blobs) {
+    const directory = join(path, "..");
+    mkdirSync(directory, { recursive: true, mode: 0o700 });
+    const temporary = `${path}.${randomBytes(8).toString("hex")}.tmp`;
+    const document = {
+        version: GRAPH_CACHE_VERSION,
+        blobs: Object.fromEntries(blobs),
+    };
+    try {
+        writeFileSync(temporary, JSON.stringify(document), { flag: "wx", mode: 0o600 });
+        renameSync(temporary, path);
+    }
+    finally {
+        try {
+            unlinkSync(temporary);
+        }
+        catch {
+            /* Renamed, or never written. */
+        }
+    }
+}
+/**
+ * The graph of `rev`, from this laptop's cache where it can be. With
+ * `cache: false` nothing is read from or written to disk, which is the plain
+ * build every time.
+ */
+export function buildRepositoryGraph(input) {
+    const started = performance.now();
+    const { root } = input;
+    const environment = input.environment ?? process.env;
+    const sha = resolveCommit(root, input.rev);
+    const { entries, all } = graphTreeEntries(root, sha);
+    const useCache = input.cache !== false;
+    const path = useCache ? graphCachePath(root, environment) : undefined;
+    const cache = path === undefined ? new Map() : readCache(path);
+    const reader = symbolReader(root);
+    const byPath = new Map(entries.map((entry) => [entry.path, entry]));
+    const keyOf = (entry) => `${entry.sha}.${extensionOf(entry.path)}`;
+    const touched = new Set();
+    let parsed = 0;
+    let reused = 0;
+    const sources = entries.filter((entry) => isGraphSource(entry.path));
+    const missing = sources.filter((entry) => !cache.has(keyOf(entry)));
+    const manifests = entries
+        .filter((entry) => !isGraphSource(entry.path))
+        .map((entry) => entry.path);
+    const texts = readBlobs(root, sha, [...manifests, ...missing.map((entry) => entry.path)]);
+    for (const entry of sources) {
+        const key = keyOf(entry);
+        touched.add(key);
+        if (cache.has(key)) {
+            reused += 1;
+            continue;
+        }
+        parsed += 1;
+        const text = texts.get(entry.path);
+        const blob = {
+            imports: text === undefined ? null : (parseImports(entry.path, text) ?? null),
+        };
+        // The index reads every product source file's names, so they are read now, in this
+        // same pass over the blob; a test's names are read only if something asks.
+        if (text !== undefined && isIndexSource(entry.path))
+            blob.symbols = { reader, ...readSymbols(entry.path, text, root) };
+        cache.set(key, blob);
+    }
+    const graph = buildImportGraphFromParsed(entries.map((entry) => entry.path), (file) => texts.get(file), (file) => {
+        const entry = byPath.get(file);
+        return entry === undefined ? undefined : (cache.get(keyOf(entry))?.imports ?? undefined);
+    });
+    const graphFiles = new Set(graph.files);
+    const prepareNames = (files) => {
+        const stale = files
+            .map((file) => byPath.get(file))
+            .filter((entry) => entry !== undefined && graphFiles.has(entry.path))
+            .filter((entry) => cache.get(keyOf(entry))?.symbols?.reader !== reader);
+        if (stale.length === 0)
+            return;
+        const read = readBlobs(root, sha, stale.map((entry) => entry.path));
+        for (const entry of stale) {
+            const blob = cache.get(keyOf(entry)) ?? { imports: null };
+            const text = read.get(entry.path);
+            blob.symbols =
+                text === undefined
+                    ? { reader, exported: [], names: [] }
+                    : { reader, ...readSymbols(entry.path, text, root) };
+            cache.set(keyOf(entry), blob);
+            parsed += 1;
+        }
+    };
+    const symbolsOf = (file) => {
+        const entry = byPath.get(file);
+        if (entry === undefined || !graphFiles.has(file))
+            return undefined;
+        prepareNames([file]);
+        return cache.get(keyOf(entry))?.symbols;
+    };
+    const namesMemo = new Map();
+    return {
+        root,
+        sha,
+        graph,
+        tree: new Set(all.map((entry) => entry.path)),
+        exportedNames: (file) => symbolsOf(file)?.exported,
+        declaredNames: (file) => {
+            const memo = namesMemo.get(file);
+            if (memo !== undefined)
+                return memo;
+            const names = symbolsOf(file)?.names;
+            if (names === undefined)
+                return undefined;
+            const set = new Set(names);
+            namesMemo.set(file, set);
+            return set;
+        },
+        prepareNames,
+        save: () => {
+            if (path === undefined)
+                return;
+            try {
+                // What this commit used first, then what earlier builds kept, up to twice as much
+                // again, so moving between branches stays warm without the file growing forever.
+                const kept = new Map();
+                for (const key of touched) {
+                    const blob = cache.get(key);
+                    if (blob !== undefined)
+                        kept.set(key, blob);
+                }
+                const limit = Math.max(kept.size * 3, 5000);
+                for (const [key, blob] of cache) {
+                    if (kept.size >= limit)
+                        break;
+                    if (!kept.has(key))
+                        kept.set(key, blob);
+                }
+                writeCache(path, kept);
+            }
+            catch {
+                /* The cache is a convenience; a build without it is only slower. */
+            }
+        },
+        stats: () => ({
+            files: graph.files.length,
+            parsed,
+            reused,
+            ms: Math.round(performance.now() - started),
+        }),
+    };
+}

package/dist/risk/import-graph.d.ts

@@ -25,6 +25,42 @@ export type FileReader = (path: string) => string | undefined;
 export declare function workingTreeReader(root: string): FileReader;
 /** JSON with comments and trailing commas, the way tsconfig files are written. */
 export declare function parseLooseJson(text: string): unknown;
+/**
+ * One Python import statement as written, before it is resolved against the
+ * repository. What a file says it imports depends only on its own text, so it
+ * can be read once per blob and kept; what that resolves to depends on the
+ * whole tree and is worked out on every build.
+ */
+export type PythonImport = Readonly<{
+    kind: "relative";
+    dots: number;
+    module: string;
+    names: readonly string[];
+}> | Readonly<{
+    kind: "from";
+    module: string;
+    names: readonly string[];
+}> | Readonly<{
+    kind: "import";
+    modules: readonly string[];
+}>;
+/** What one file imports, as written: script specifiers, or Python statements. */
+export type ParsedImports = Readonly<{
+    script: readonly string[];
+}> | Readonly<{
+    python: readonly PythonImport[];
+}>;
+/** The Python import statements in a file, in order, as written. */
+export declare function parsePythonImports(source: string): PythonImport[];
+/** The largest file whose imports are read; a bigger one is in the graph with no edges out. */
+export declare const MAX_IMPORT_SOURCE_CHARACTERS = 2000000;
+/** Whether the graph scans a path at all: TypeScript, JavaScript and Python, not `.d.ts`. */
+export declare function isGraphSource(path: string): boolean;
+/**
+ * What one file imports, as written, or nothing when the file is not one the
+ * graph reads or is too large to read.
+ */
+export declare function parseImports(path: string, source: string): ParsedImports | undefined;
 /**
  * Builds the import graph over `files` (repository-relative paths). Only
  * TypeScript, JavaScript and Python files are scanned; `package.json` and
@@ -32,6 +68,13 @@ export declare function parseLooseJson(text: string): unknown;
  * `read` defaults to the working tree under `root`.
  */
 export declare function buildImportGraph(root: string, files: readonly string[], read?: FileReader): ImportGraph;
+/**
+ * The same graph, from each file's imports as written. `read` is asked only
+ * for the `package.json` and `tsconfig` files that say how specifiers resolve;
+ * `parsed` answers for every source file, which is what lets a laptop keep
+ * what it read per blob and parse only the files a commit changed.
+ */
+export declare function buildImportGraphFromParsed(files: readonly string[], read: FileReader, parsed: (file: string) => ParsedImports | undefined): ImportGraph;
 /**
  * Everything the starting files depend on: follow imports outward. A file at
  * distance 2 is imported by something the starting files import.

package/dist/risk/import-graph.js

@@ -335,7 +335,45 @@ function importedNames(list) {
         ?.trim() ?? "")
         .filter((name) => /^\w+$/.test(name));
 }
-function pythonImports(workspace, from, source) {
+/** The Python import statements in a file, in order, as written. */
+export function parsePythonImports(source) {
+    const found = [];
+    // Parenthesized name lists joined, so `from x import (\n a,\n b)` reads as one line.
+    const text = source.replace(/\(([^()]*)\)/g, (whole, inner) => inner.includes("\n") ? inner.replace(/\n/g, " ") : whole);
+    for (const line of text.split("\n")) {
+        const relative = /^\s*from\s+(\.+)([\w.]*)\s+import\s+(.+)$/.exec(line);
+        if (relative) {
+            found.push({
+                kind: "relative",
+                dots: (relative[1] ?? ".").length,
+                module: relative[2] ?? "",
+                names: importedNames(relative[3] ?? ""),
+            });
+            continue;
+        }
+        const absoluteFrom = /^\s*from\s+([A-Za-z_][\w.]*)\s+import\s+(.+)$/.exec(line);
+        if (absoluteFrom) {
+            found.push({
+                kind: "from",
+                module: absoluteFrom[1] ?? "",
+                names: importedNames(absoluteFrom[2] ?? ""),
+            });
+            continue;
+        }
+        const absolute = /^\s*import\s+([A-Za-z_][\w.]*(?:\s*,\s*[A-Za-z_][\w.]*)*)/.exec(line);
+        if (absolute) {
+            found.push({
+                kind: "import",
+                modules: (absolute[1] ?? "").split(",").map((raw) => raw
+                    .trim()
+                    .split(/\s+as\s+/)[0]
+                    ?.trim() ?? ""),
+            });
+        }
+    }
+    return found;
+}
+function resolvePythonImports(workspace, from, statements) {
     const found = new Set();
     const add = (file) => {
         if (file !== undefined && file !== from)
@@ -357,43 +395,30 @@ function pythonImports(workspace, from, source) {
         }
         return undefined;
     };
-    // Parenthesized name lists joined, so `from x import (\n a,\n b)` reads as one line.
-    const text = source.replace(/\(([^()]*)\)/g, (whole, inner) => inner.includes("\n") ? inner.replace(/\n/g, " ") : whole);
-    for (const line of text.split("\n")) {
-        const relative = /^\s*from\s+(\.+)([\w.]*)\s+import\s+(.+)$/.exec(line);
-        if (relative) {
-            const directory = relativeDirectory((relative[1] ?? ".").length);
+    for (const statement of statements) {
+        if (statement.kind === "relative") {
+            const directory = relativeDirectory(statement.dots);
             if (directory === undefined)
                 continue;
-            const dotted = relative[2] ?? "";
-            const names = importedNames(relative[3] ?? "");
+            const dotted = statement.module;
             if (dotted.length > 0) {
                 add(moduleFile(directory, dotted));
-                for (const name of names)
+                for (const name of statement.names)
                     add(moduleFile(directory, `${dotted}.${name}`));
             }
             else {
                 // `from . import x`: x is a module beside this file, or a name its package defines.
-                for (const name of names)
+                for (const name of statement.names)
                     add(moduleFile(directory, name) ?? moduleFile(directory, "__init__"));
             }
-            continue;
         }
-        const absoluteFrom = /^\s*from\s+([A-Za-z_][\w.]*)\s+import\s+(.+)$/.exec(line);
-        if (absoluteFrom) {
-            const dotted = absoluteFrom[1] ?? "";
-            for (const name of importedNames(absoluteFrom[2] ?? ""))
-                add(resolvePythonModule(workspace, `${dotted}.${name}`));
-            add(resolvePythonModule(workspace, dotted));
-            continue;
+        else if (statement.kind === "from") {
+            for (const name of statement.names)
+                add(resolvePythonModule(workspace, `${statement.module}.${name}`));
+            add(resolvePythonModule(workspace, statement.module));
         }
-        const absolute = /^\s*import\s+([A-Za-z_][\w.]*(?:\s*,\s*[A-Za-z_][\w.]*)*)/.exec(line);
-        if (absolute) {
-            for (const raw of (absolute[1] ?? "").split(",")) {
-                const dotted = raw
-                    .trim()
-                    .split(/\s+as\s+/)[0]
-                    ?.trim() ?? "";
+        else {
+            for (const dotted of statement.modules) {
                 // `import a.b.c` binds a, a.b and a.b.c; the deepest file is the one used.
                 const segments = dotted.split(".");
                 for (let length = segments.length; length > 0; length -= 1) {
@@ -408,6 +433,25 @@ function pythonImports(workspace, from, source) {
     }
     return [...found];
 }
+/** The largest file whose imports are read; a bigger one is in the graph with no edges out. */
+export const MAX_IMPORT_SOURCE_CHARACTERS = 2_000_000;
+/** Whether the graph scans a path at all: TypeScript, JavaScript and Python, not `.d.ts`. */
+export function isGraphSource(path) {
+    return isScript(path) || isPython(path);
+}
+/**
+ * What one file imports, as written, or nothing when the file is not one the
+ * graph reads or is too large to read.
+ */
+export function parseImports(path, source) {
+    if (source.length > MAX_IMPORT_SOURCE_CHARACTERS)
+        return undefined;
+    if (isScript(path))
+        return { script: scriptSpecifiers(source) };
+    if (isPython(path))
+        return { python: parsePythonImports(source) };
+    return undefined;
+}
 /**
  * Builds the import graph over `files` (repository-relative paths). Only
  * TypeScript, JavaScript and Python files are scanned; `package.json` and
@@ -415,30 +459,40 @@ function pythonImports(workspace, from, source) {
  * `read` defaults to the working tree under `root`.
  */
 export function buildImportGraph(root, files, read = workingTreeReader(root)) {
+    return buildImportGraphFromParsed(files, read, (file) => {
+        const source = read(file);
+        return source === undefined ? undefined : parseImports(file, source);
+    });
+}
+/**
+ * The same graph, from each file's imports as written. `read` is asked only
+ * for the `package.json` and `tsconfig` files that say how specifiers resolve;
+ * `parsed` answers for every source file, which is what lets a laptop keep
+ * what it read per blob and parse only the files a commit changed.
+ */
+export function buildImportGraphFromParsed(files, read, parsed) {
     const normalized = files.map((file) => file.replace(/\\/g, "/").replace(/^\.\//, ""));
     const workspace = buildWorkspace(normalized, read);
     const imports = {};
     const importedBy = {};
     const scanned = [];
     for (const file of normalized) {
-        const script = isScript(file);
-        const python = isPython(file);
-        if (!script && !python)
+        if (!isGraphSource(file))
             continue;
         scanned.push(file);
-        const source = read(file);
-        if (source === undefined || source.length > 2_000_000)
+        const written = parsed(file);
+        if (written === undefined)
             continue;
         const targets = new Set();
-        if (script) {
-            for (const specifier of scriptSpecifiers(source)) {
+        if ("script" in written) {
+            for (const specifier of written.script) {
                 const target = resolveScript(workspace, file, specifier);
                 if (target !== undefined && target !== file)
                     targets.add(target);
             }
         }
         else {
-            for (const target of pythonImports(workspace, file, source))
+            for (const target of resolvePythonImports(workspace, file, written.python))
                 targets.add(target);
         }
         if (targets.size === 0)

package/dist/risk/pipeline.d.ts

@@ -1,3 +1,4 @@
+import { type TreeEntry } from "./git.js";
 import { type ImportGraph } from "./import-graph.js";
 import { type ResourceRef } from "./resources.js";
 import type { BehaviorMap, ChangeExtraction, Delta, Intent, RiskReport } from "./contract.js";
@@ -16,6 +17,16 @@ export declare function readBehaviorMaps(directory: string): {
 };
 /** Every resource the maps name, including sink resources, for the extraction to look for directly. */
 export declare function watchedResources(maps: readonly BehaviorMap[]): ResourceRef[];
+/**
+ * The blobs of a commit's tree the import graph reads: source files and the
+ * manifests that say how their imports resolve, without vendored or built
+ * folders and without anything over a megabyte. `all` is the whole listing,
+ * for a caller that also needs to know what else the tree holds.
+ */
+export declare function graphTreeEntries(root: string, rev: string): {
+    entries: TreeEntry[];
+    all: TreeEntry[];
+};
 /** The import graph of the tree at a commit, read from git rather than the working tree. */
 export declare function buildGraphAt(root: string, rev: string): ImportGraph;
 export type AssessOptions = Readonly<{
@@ -32,6 +43,8 @@ export type AssessOptions = Readonly<{
     deltas?: readonly Delta[];
     /** The change's intent from its description or a model; else it is read from the commits. */
     intent?: Intent;
+    /** The import graph at head when the caller already built it, so it is not built twice. */
+    graph?: ImportGraph;
 }>;
 export type Assessment = Readonly<{
     report: RiskReport;

package/dist/risk/pipeline.js

@@ -65,9 +65,15 @@ export function watchedResources(maps) {
 }
 const GRAPH_EXTENSIONS = new Set(["ts", "tsx", "mts", "cts", "js", "jsx", "mjs", "cjs", "py"]);
 const MAX_GRAPH_FILE_BYTES = 1_000_000;
-/** The import graph of the tree at a commit, read from git rather than the working tree. */
-export function buildGraphAt(root, rev) {
-    const entries = listTree(root, rev).filter((entry) => {
+/**
+ * The blobs of a commit's tree the import graph reads: source files and the
+ * manifests that say how their imports resolve, without vendored or built
+ * folders and without anything over a megabyte. `all` is the whole listing,
+ * for a caller that also needs to know what else the tree holds.
+ */
+export function graphTreeEntries(root, rev) {
+    const all = listTree(root, rev);
+    const entries = all.filter((entry) => {
         if (entry.size > MAX_GRAPH_FILE_BYTES)
             return false;
         if (/(?:^|\/)(?:node_modules|vendor|dist|build|\.next|coverage)\//.test(entry.path))
@@ -79,6 +85,11 @@ export function buildGraphAt(root, rev) {
             base === "jsconfig.json" ||
             /^tsconfig\..*json$/.test(base));
     });
+    return { entries, all };
+}
+/** The import graph of the tree at a commit, read from git rather than the working tree. */
+export function buildGraphAt(root, rev) {
+    const { entries } = graphTreeEntries(root, rev);
     const paths = entries.map((entry) => entry.path);
     const blobs = readBlobs(root, rev, paths);
     return buildImportGraph(root, paths, (path) => blobs.get(path));
@@ -103,7 +114,7 @@ export async function assessChange(options) {
         ...(options.deltas === undefined ? {} : { deltas: [...options.deltas] }),
         ...(intent === undefined ? {} : { intent }),
     };
-    const graph = buildGraphAt(options.root, head);
+    const graph = options.graph ?? buildGraphAt(options.root, head);
     const priors = options.priors === false
         ? undefined
         : typeof options.priors === "object"

package/dist/wire.d.ts

@@ -5,14 +5,14 @@
  * runtime dependency at all: Node 22 builtins and global fetch, nothing else.
  * A contract test compares the scope list below against the server's.
  */
-export declare const CLI_VERSION = "1.0.17";
+export declare const CLI_VERSION = "1.0.18";
 export declare const CLI_INVOCATION = "npx -y balladeer@latest";
 export declare const CLIENT_HEADER = "x-balladeer-client";
 /** What the last background update came to: `started:1.0.17`, `installed:1.0.17`, `failed:exit-1`, `unstartable:launcher`. */
 export declare const UPDATE_STATE_HEADER = "x-balladeer-update-state";
 /** Which host's hook made this guidance fetch: `claude` or `codex`. */
 export declare const HOOK_HOST_HEADER = "x-balladeer-hook";
-export declare const CLIENT_HEADER_VALUE = "balladeer/1.0.17";
+export declare const CLIENT_HEADER_VALUE = "balladeer/1.0.18";
 export declare const DEFAULT_CONTROL_PLANE = "https://envelopes.balladeer.ai";
 export type DelegatedScope = "repository:enroll" | "agent:issue" | "ci:connect" | "workspace:invite" | "candidate:propose";
 export declare const DELEGATED_SCOPES: readonly DelegatedScope[];
@@ -729,7 +729,23 @@ export type JsonStep = Readonly<{
  * this machine, or judges still running when the time ran out. Verdicts
  * themselves are printed as `balladeer-judge-verdict/v1` objects.
  */
+/**
+ * What the push check's anchoring did before it selected promises: which it
+ * anchored, which it could not and why, what the calls cost and how many
+ * anchorings are left today on this laptop. `message` is the line a person
+ * reads.
+ */
  | Readonly<{
+    step: "anchors";
+    message: string;
+    anchored: readonly string[];
+    notAnchored: readonly Readonly<{
+        promiseId: string;
+        reason: string;
+    }>[];
+    tokens: number;
+    remainingToday: number;
+}> | Readonly<{
     step: "judge";
     status: "not_judged" | "still_judging" | "nothing_to_judge";
     reason: string;

package/dist/wire.js

@@ -5,7 +5,7 @@
  * runtime dependency at all: Node 22 builtins and global fetch, nothing else.
  * A contract test compares the scope list below against the server's.
  */
-export const CLI_VERSION = "1.0.17";
+export const CLI_VERSION = "1.0.18";
 export const CLI_INVOCATION = "npx -y balladeer@latest";
 export const CLIENT_HEADER = "x-balladeer-client";
 /** What the last background update came to: `started:1.0.17`, `installed:1.0.17`, `failed:exit-1`, `unstartable:launcher`. */

package/package.json

@@ -1,10 +1,15 @@
 {
   "name": "balladeer",
-  "version": "1.0.17",
+  "version": "1.0.18",
   "description": "Set up Balladeer from your terminal, or from a coding agent's.",
   "license": "Apache-2.0",
   "private": false,
-  "//": "repository and homepage are deliberately absent: the source repository is private, and a registry page linking somewhere a reader cannot open is worse than one that links nowhere. Add both when the repository is public, and delete this note when you do.",
+  "//": "repository names this private GitHub repository because npm trusted publishing requires it: the release workflow (.github/workflows/release.yml) publishes with no npm token and no passkey only when package.json's repository matches the repository the workflow runs in. Robert approved the registry page showing the repository name on 30 September 2026. homepage stays absent while the repository is private.",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Bobby-tables1/balladeer.git",
+    "directory": "packages/cli"
+  },
   "type": "module",
   "publishConfig": {
     "access": "public"