@nite-framework/nite-zk-profiler 0.1.3 → 0.2.0

package/dist/cli.js

@@ -1,33 +1,56 @@
 #!/usr/bin/env node
+import { dirname, isAbsolute, relative, resolve } from "node:path";
 import { analyze } from "./analyze.js";
-import { DEFAULT_BUDGET_PATH, budgetFrom, check, readBudget, writeBudget, } from "./budget.js";
+import { DEFAULT_BUDGET_PATH, budgetFrom, budgetSources, check, readBudget, writeBudget, } from "./budget.js";
+import { cacheKey, readCache, writeCache } from "./cache.js";
+import { setColorEnabled } from "./colors.js";
 import { compileSkipZk } from "./compile.js";
+import { measureDeep } from "./deep.js";
+import { diffCosts, materialise, pathWithinRef, repoRoot } from "./diff.js";
 import { ProfilerError } from "./errors.js";
-import { measure } from "./measure.js";
-import { checkJson, formatCheck, formatProfile, profileJson } from "./report.js";
+import { calibrationFrom, readCalibration, writeCalibration } from "./estimate.js";
+import { measureParallel } from "./measure.js";
+import { Progress } from "./progress.js";
+import { checkJson, diffJson, formatCheck, formatDiff, formatProfile, profileJson, } from "./report.js";
 import { SUPPORTED_RANGES, resolveToolchain } from "./toolchain.js";
+import { toolVersion } from "./version.js";
 const USAGE = `nite-zk - see what a Compact circuit costs to prove
 
 Usage:
-  nite-zk profile <source>     Report rows, k and relative cost per circuit
-  nite-zk save <source>        Write zk-budget.json from current measurements
-  nite-zk check <source>       Measure and compare against zk-budget.json
+  nite-zk profile <source...>   Report rows, k and relative cost per circuit
+  nite-zk save <source...>      Write zk-budget.json from current measurements
+  nite-zk check [<source...>]   Compare against zk-budget.json
+                                Sources are optional once saved, since the
+                                budget records which contracts it describes.
+  nite-zk diff <ref> [<source>] Compare a contract against a git ref
+  nite-zk calibrate --observed <ms> --at-k <k>
+                                Anchor proving estimates to a real proof
 
 Options:
-  --json                       Machine readable output
-  --out <dir>                  Compile into a specific directory (kept)
-  --budget <file>              Budget path (default: ${DEFAULT_BUDGET_PATH})
-  --strict                     check: fail on circuits missing from the budget
-  +VERSION                     Pin the Compact toolchain, e.g. +0.31.1
-  -h, --help                   Show this message
-  -v, --version                Show the tool version
+  --estimate                    Show modelled proving time per circuit
+  --deep                        Also generate real proving keys and report
+                                measured setup time and prover key size
+  --json                        Machine readable output
+  --out <dir>                   Compile into a specific directory (kept)
+  --budget <file>               Budget path (default: ${DEFAULT_BUDGET_PATH})
+  --strict                      check: fail on circuits missing from the budget
+  --no-color                    Plain output (also honours NO_COLOR)
+  --no-cache                    Ignore cached measurements for this run
+  +VERSION                      Pin the Compact toolchain, e.g. +0.31.1
+  -h, --help                    Show this message
+  -v, --version                 Show the tool version
 
 Supported Compact toolchains: ${SUPPORTED_RANGES.join(", ")}
 `;
 export function parseArgs(argv) {
     const opts = {
+        sources: [],
         json: false,
         strict: false,
+        deep: false,
+        estimate: false,
+        noColor: false,
+        noCache: false,
         budget: DEFAULT_BUDGET_PATH,
         help: false,
         version: false,
@@ -38,6 +61,14 @@ export function parseArgs(argv) {
             opts.json = true;
         else if (arg === "--strict")
             opts.strict = true;
+        else if (arg === "--deep")
+            opts.deep = true;
+        else if (arg === "--estimate")
+            opts.estimate = true;
+        else if (arg === "--no-color")
+            opts.noColor = true;
+        else if (arg === "--no-cache")
+            opts.noCache = true;
         else if (arg === "-h" || arg === "--help")
             opts.help = true;
         else if (arg === "-v" || arg === "--version")
@@ -46,70 +77,200 @@ export function parseArgs(argv) {
             opts.out = argv[++i];
         else if (arg === "--budget")
             opts.budget = argv[++i] ?? DEFAULT_BUDGET_PATH;
+        else if (arg === "--observed")
+            opts.observedMs = Number(argv[++i]);
+        else if (arg === "--at-k")
+            opts.atK = Number(argv[++i]);
         else if (arg.startsWith("+"))
             opts.versionArg = arg;
         else if (!opts.command)
             opts.command = arg;
-        else if (!opts.source)
-            opts.source = arg;
+        else if (opts.command === "diff" && opts.ref === undefined)
+            opts.ref = arg;
+        else
+            opts.sources.push(arg);
     }
     return opts;
 }
-/** Compile and measure. Shared by all three commands. */
-function profileSource(source, opts) {
-    // Monotonic, so a wall clock adjustment mid run cannot produce a negative
-    // or wildly wrong duration.
-    const started = performance.now();
+/** Compile and measure one contract. */
+async function profileOne(source, opts, progress, label) {
+    progress.update(`${label}compiling`);
     const toolchain = resolveToolchain(opts.versionArg);
-    const compiled = compileSkipZk(source, toolchain, opts.out);
+    const compiled = await compileSkipZk(source, toolchain, opts.out);
     try {
-        const costs = analyze(measure(compiled.zkirDir, toolchain, source));
-        return { costs, toolchain, elapsedMs: performance.now() - started };
+        // The compile is the cheap half, so it always runs and its output keys the
+        // cache. Identical IR cannot produce different constraint counts.
+        const key = opts.noCache ? undefined : cacheKey(compiled.zkirDir, toolchain);
+        let measurements = key ? readCache(key) : undefined;
+        const cached = measurements !== undefined;
+        if (!measurements) {
+            measurements = await measureParallel(compiled.zkirDir, toolchain, source, (d, t) => progress.update(`${label}measuring  ${d}/${t}`));
+            if (key)
+                writeCache(key, measurements);
+        }
+        let deep;
+        if (opts.deep) {
+            const results = await measureDeep(measurements, compiled.zkirDir, toolchain, (c, i, n) => progress.update(`${label}generating proving keys  ${i + 1}/${n}  ${c}`));
+            deep = new Map(results.map((r) => [r.circuit, r]));
+        }
+        return { costs: analyze(measurements), toolchain, deep, cached };
     }
     finally {
         compiled.cleanup();
     }
 }
-export function run(argv) {
+/** Compile and measure every requested contract. */
+async function profileAll(sources, opts) {
+    const started = performance.now();
+    const progress = new Progress(!opts.json);
+    progress.start("resolving toolchain");
+    try {
+        const contracts = [];
+        let toolchain;
+        let deep;
+        let cached = true;
+        for (const [i, source] of sources.entries()) {
+            const label = sources.length > 1 ? `[${i + 1}/${sources.length}] ` : "";
+            const r = await profileOne(source, opts, progress, label);
+            contracts.push({ source, costs: r.costs });
+            toolchain = r.toolchain;
+            if (r.deep)
+                deep = new Map([...(deep ?? []), ...r.deep]);
+            if (!r.cached)
+                cached = false;
+        }
+        progress.stop();
+        return { contracts, toolchain, deep, cached, elapsedMs: performance.now() - started };
+    }
+    finally {
+        progress.stop();
+    }
+}
+/** Paths recorded in a budget are relative to the budget file. */
+function sourcesFromBudget(budgetPath, recorded) {
+    const base = dirname(resolve(budgetPath));
+    return recorded.map((s) => (isAbsolute(s) ? s : resolve(base, s)));
+}
+function profileOptions(opts, run) {
+    return {
+        toolchain: run.toolchain,
+        elapsedMs: run.elapsedMs,
+        deep: run.deep,
+        cached: run.cached,
+        calibration: readCalibration(opts.budget),
+        showEstimate: opts.estimate,
+    };
+}
+async function runDiff(opts) {
+    if (!opts.ref) {
+        throw new ProfilerError("diff needs a git ref", "    nite-zk diff main src/Main.compact");
+    }
+    const root = repoRoot();
+    const sources = opts.sources.length
+        ? opts.sources
+        : sourcesFromBudget(opts.budget, budgetSources(readBudget(opts.budget)));
+    if (sources.length !== 1) {
+        throw new ProfilerError("diff compares one contract at a time", `Got ${sources.length} contracts. Name the one to compare:\n    nite-zk diff ${opts.ref} src/Main.compact`);
+    }
+    const source = sources[0];
+    const after = await profileAll([source], opts);
+    const exported = await materialise(opts.ref);
+    try {
+        const basePath = pathWithinRef(source, root, exported.dir);
+        const before = await profileAll([basePath], opts);
+        const result = diffCosts(opts.ref, before.contracts[0].costs, after.contracts[0].costs);
+        process.stdout.write(opts.json ? `${diffJson(result)}\n` : formatDiff(result));
+        return result.regressed ? 1 : 0;
+    }
+    finally {
+        exported.cleanup();
+    }
+}
+export async function run(argv) {
     const opts = parseArgs(argv);
+    if (opts.noColor || opts.json)
+        setColorEnabled(false);
+    // Checked before the no-command case, since `nite-zk -v` carries no command
+    // and would otherwise fall through to the usage text.
+    if (opts.version) {
+        process.stdout.write(`nite-zk-profiler ${toolVersion()}\n`);
+        return 0;
+    }
     if (opts.help || !opts.command) {
         process.stdout.write(USAGE);
         return opts.command ? 0 : 1;
     }
-    if (opts.version) {
-        process.stdout.write("nite-zk-profiler 0.1.0\n");
-        return 0;
-    }
-    if (!["profile", "save", "check"].includes(opts.command)) {
+    const known = ["profile", "save", "check", "diff", "calibrate"];
+    if (!known.includes(opts.command)) {
         process.stderr.write(`Unknown command: ${opts.command}\n\n${USAGE}`);
         return 1;
     }
-    if (!opts.source) {
-        process.stderr.write(`${opts.command} needs a source file\n\n${USAGE}`);
-        return 1;
-    }
-    const { costs, toolchain, elapsedMs } = profileSource(opts.source, opts);
-    if (opts.command === "profile") {
-        process.stdout.write(opts.json
-            ? `${profileJson(costs, toolchain)}\n`
-            : formatProfile(costs, toolchain, elapsedMs));
+    if (opts.command === "calibrate") {
+        if (!opts.observedMs || !opts.atK) {
+            throw new ProfilerError("calibrate needs an observed proof", "Time one real proof, then record it:\n" +
+                "    nite-zk calibrate --observed 9000 --at-k 16\n" +
+                "where --observed is milliseconds and --at-k is that circuit's k.");
+        }
+        const calibration = calibrationFrom(opts.observedMs, opts.atK);
+        writeCalibration(opts.budget, calibration);
+        process.stdout.write(`Calibrated: ${calibration.msPerDomainRow.toFixed(4)} ms per domain row, ` +
+            `from ${opts.observedMs}ms at k=${opts.atK}.\n` +
+            "Estimates now use this machine's rate. Re-run `nite-zk calibrate` if the prover changes.\n");
         return 0;
     }
-    if (opts.command === "save") {
-        // Record the supported line rather than the exact patch version, so a
-        // routine toolchain bump inside 0.31.x does not invalidate the budget.
-        const budget = budgetFrom(costs, `${toolchain.version.split(".").slice(0, 2).join(".")}.x`);
-        writeBudget(opts.budget, budget);
-        process.stdout.write(`Wrote ${opts.budget} with ${costs.length} circuit${costs.length === 1 ? "" : "s"}\n`);
+    if (opts.command === "diff")
+        return runDiff(opts);
+    if (opts.command !== "check" && opts.sources.length === 0) {
+        throw new ProfilerError(`${opts.command} needs at least one source file`, `    nite-zk ${opts.command} src/Main.compact`);
+    }
+    if (opts.command === "check") {
+        // Read the budget first, so a missing one is reported before spending time
+        // on a compile, and so it can supply the source paths.
+        const budget = readBudget(opts.budget);
+        const recorded = budgetSources(budget);
+        const sources = opts.sources.length
+            ? opts.sources
+            : sourcesFromBudget(opts.budget, recorded);
+        if (sources.length === 0) {
+            throw new ProfilerError("check needs a source file", `${opts.budget} does not record which contracts it describes.\n` +
+                "Either pass them:\n    nite-zk check src/Main.compact\n" +
+                "or rewrite the budget so it remembers:\n    nite-zk save src/Main.compact");
+        }
+        const run_ = await profileAll(sources, opts);
+        // Compare using the paths as the budget records them.
+        const base = dirname(resolve(opts.budget));
+        const keyed = run_.contracts.map((c, i) => ({
+            source: opts.sources.length ? relative(base, resolve(c.source)) : recorded[i] ?? c.source,
+            costs: c.costs,
+        }));
+        const result = check(keyed, budget, opts.strict);
+        process.stdout.write(opts.json ? `${checkJson(result)}\n` : formatCheck(result));
+        return result.failed ? 1 : 0;
+    }
+    const run_ = await profileAll(opts.sources, opts);
+    if (opts.command === "profile") {
+        const o = profileOptions(opts, run_);
+        process.stdout.write(opts.json ? `${profileJson(run_.contracts, o)}\n` : formatProfile(run_.contracts, o));
         return 0;
     }
-    const result = check(costs, readBudget(opts.budget), opts.strict);
-    process.stdout.write(opts.json ? `${checkJson(result)}\n` : formatCheck(result));
-    return result.failed ? 1 : 0;
+    // save
+    //
+    // Record the supported line rather than the exact patch version, so a routine
+    // toolchain bump inside 0.31.x does not invalidate the budget. Sources are
+    // stored relative to the budget file so the pair stays portable.
+    const base = dirname(resolve(opts.budget));
+    const line = `${run_.toolchain.version.split(".").slice(0, 2).join(".")}.x`;
+    const budget = budgetFrom(run_.contracts.map((c) => ({ source: relative(base, resolve(c.source)), costs: c.costs })), line);
+    writeBudget(opts.budget, budget);
+    const circuits = run_.contracts.reduce((n, c) => n + c.costs.length, 0);
+    process.stdout.write(`Wrote ${opts.budget}: ${run_.contracts.length} contract${run_.contracts.length === 1 ? "" : "s"}, ` +
+        `${circuits} circuit${circuits === 1 ? "" : "s"}\n` +
+        "Check it in, then run `nite-zk check` in CI.\n");
+    return 0;
 }
-export function main(argv) {
+export async function main(argv) {
     try {
-        return run(argv);
+        return await run(argv);
     }
     catch (e) {
         if (e instanceof ProfilerError) {
@@ -126,5 +287,5 @@ export function main(argv) {
 const invokedDirectly = process.argv[1] !== undefined &&
     /(?:^|[\\/])(?:cli\.(?:ts|js)|nite-zk)$/.test(process.argv[1]);
 if (invokedDirectly) {
-    process.exit(main(process.argv.slice(2)));
+    main(process.argv.slice(2)).then((code) => process.exit(code));
 }

package/dist/colors.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Minimal ANSI styling.
+ *
+ * Deliberately not a dependency. A profiler that prints a table needs eight
+ * escape codes, and a zero dependency CLI is easier to trust and audit than one
+ * that pulls a package in to add colour.
+ */
+/** Test seam, and lets the CLI force plain output for `--json`. */
+export declare function setColorEnabled(value: boolean): void;
+declare const CODES: {
+    readonly reset: 0;
+    readonly bold: 1;
+    readonly dim: 2;
+    readonly red: 31;
+    readonly green: 32;
+    readonly yellow: 33;
+    readonly blue: 34;
+    readonly magenta: 35;
+    readonly cyan: 36;
+    readonly gray: 90;
+};
+export type Style = keyof typeof CODES;
+export declare const bold: (t: string) => string;
+export declare const dim: (t: string) => string;
+export declare const red: (t: string) => string;
+export declare const green: (t: string) => string;
+export declare const yellow: (t: string) => string;
+export declare const cyan: (t: string) => string;
+export declare const gray: (t: string) => string;
+export declare const boldRed: (t: string) => string;
+export declare const boldYellow: (t: string) => string;
+/**
+ * Colour a circuit by how much it costs relative to the cheapest one here.
+ * The thresholds are deliberately coarse: the point is to make the expensive
+ * circuits findable at a glance, not to encode a precise scale.
+ */
+export declare function costColor(relativeCost: number): (t: string) => string;
+/** Width of a string once escape sequences are discounted. */
+export declare function visibleLength(text: string): number;
+export {};

package/dist/colors.js

@@ -0,0 +1,69 @@
+/**
+ * Minimal ANSI styling.
+ *
+ * Deliberately not a dependency. A profiler that prints a table needs eight
+ * escape codes, and a zero dependency CLI is easier to trust and audit than one
+ * that pulls a package in to add colour.
+ */
+/**
+ * Honours the NO_COLOR convention, FORCE_COLOR, and whether stdout is a
+ * terminal, so piping to a file or a CI log produces clean text.
+ */
+function colorEnabled() {
+    if (process.env.NO_COLOR !== undefined && process.env.NO_COLOR !== "")
+        return false;
+    if (process.env.FORCE_COLOR !== undefined && process.env.FORCE_COLOR !== "0")
+        return true;
+    return process.stdout.isTTY === true;
+}
+let enabled = colorEnabled();
+/** Test seam, and lets the CLI force plain output for `--json`. */
+export function setColorEnabled(value) {
+    enabled = value;
+}
+const CODES = {
+    reset: 0,
+    bold: 1,
+    dim: 2,
+    red: 31,
+    green: 32,
+    yellow: 33,
+    blue: 34,
+    magenta: 35,
+    cyan: 36,
+    gray: 90,
+};
+function wrap(text, ...styles) {
+    if (!enabled || styles.length === 0)
+        return text;
+    const open = styles.map((s) => `[${CODES[s]}m`).join("");
+    return `${open}${text}[${CODES.reset}m`;
+}
+export const bold = (t) => wrap(t, "bold");
+export const dim = (t) => wrap(t, "dim");
+export const red = (t) => wrap(t, "red");
+export const green = (t) => wrap(t, "green");
+export const yellow = (t) => wrap(t, "yellow");
+export const cyan = (t) => wrap(t, "cyan");
+export const gray = (t) => wrap(t, "gray");
+export const boldRed = (t) => wrap(t, "bold", "red");
+export const boldYellow = (t) => wrap(t, "bold", "yellow");
+/**
+ * Colour a circuit by how much it costs relative to the cheapest one here.
+ * The thresholds are deliberately coarse: the point is to make the expensive
+ * circuits findable at a glance, not to encode a precise scale.
+ */
+export function costColor(relativeCost) {
+    if (relativeCost >= 32)
+        return boldRed;
+    if (relativeCost >= 8)
+        return red;
+    if (relativeCost >= 2)
+        return yellow;
+    return green;
+}
+/** Width of a string once escape sequences are discounted. */
+export function visibleLength(text) {
+    // eslint-disable-next-line no-control-regex
+    return text.replace(/\[[0-9;]*m/g, "").length;
+}

package/dist/compile.d.ts

@@ -13,4 +13,4 @@ export interface CompileResult {
  * `--skip-zk` is what makes profiling fast enough to sit in an edit loop: it
  * emits the IR and skips key generation, which is the slow part.
  */
-export declare function compileSkipZk(source: string, toolchain: Toolchain, outDir?: string): CompileResult;
+export declare function compileSkipZk(source: string, toolchain: Toolchain, outDir?: string): Promise<CompileResult>;

package/dist/compile.js

@@ -1,4 +1,4 @@
-import { spawnSync } from "node:child_process";
+import { spawn } from "node:child_process";
 import { mkdtempSync, rmSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join, resolve } from "node:path";
@@ -9,7 +9,7 @@ import { ProfilerError } from "./errors.js";
  * `--skip-zk` is what makes profiling fast enough to sit in an edit loop: it
  * emits the IR and skips key generation, which is the slow part.
  */
-export function compileSkipZk(source, toolchain, outDir) {
+export async function compileSkipZk(source, toolchain, outDir) {
     const temporary = outDir === undefined;
     const target = temporary
         ? mkdtempSync(join(tmpdir(), "nite-zk-"))
@@ -18,21 +18,30 @@ export function compileSkipZk(source, toolchain, outDir) {
     if (toolchain.versionArg)
         args.push(toolchain.versionArg);
     args.push("--skip-zk", resolve(source), target);
-    const res = spawnSync("compact", args, { encoding: "utf8" });
     const cleanup = () => {
         if (temporary)
             rmSync(target, { recursive: true, force: true });
     };
-    if (res.error) {
+    // Spawned asynchronously rather than with spawnSync so the event loop stays
+    // free. A synchronous spawn blocks timers, which freezes the progress
+    // display for the whole compile.
+    const { status, output, error } = await new Promise((resolvePromise) => {
+        const child = spawn("compact", args);
+        let out = "";
+        child.stdout.on("data", (d) => (out += d));
+        child.stderr.on("data", (d) => (out += d));
+        child.on("error", (e) => resolvePromise({ status: null, output: out, error: e }));
+        child.on("close", (code) => resolvePromise({ status: code, output: out }));
+    });
+    if (error) {
         cleanup();
-        throw new ProfilerError("Could not run `compact compile`", String(res.error));
+        throw new ProfilerError("Could not run `compact compile`", String(error));
     }
-    if (res.status !== 0) {
+    if (status !== 0) {
         // The compiler's own diagnostics are better than anything worth inventing
         // here, so they are passed through unchanged.
-        const diagnostics = `${res.stdout ?? ""}${res.stderr ?? ""}`.trim();
         cleanup();
-        throw new ProfilerError(`Compilation failed for ${source}`, diagnostics || `compact exited with status ${res.status}`);
+        throw new ProfilerError(`Compilation failed for ${source}`, output.trim() || `compact exited with status ${status}`);
     }
     return { outDir: target, zkirDir: join(target, "zkir"), cleanup };
 }

package/dist/deep.d.ts

@@ -0,0 +1,24 @@
+import type { Measurement } from "./measure.ts";
+import type { Toolchain } from "./toolchain.ts";
+export interface DeepMeasurement extends Measurement {
+    /** Wall clock time to generate the proving and verifying keys, in ms. */
+    setupMs: number;
+    /** Size of the generated prover key, in bytes. */
+    proverKeyBytes: number;
+}
+/**
+ * Generate real proving keys and measure how long it takes.
+ *
+ * This is the expensive counterpart to `mock-compile`. It is opt in because it
+ * does the work the fast path deliberately skips, which is minutes rather than
+ * seconds on a contract full of high `k` circuits.
+ *
+ * Two things come out of it that cannot be derived from `k` alone: the actual
+ * setup time on this machine, and the prover key size, which is what users end
+ * up downloading and holding in memory.
+ */
+export declare function measureDeep(measurements: Measurement[], zkirDir: string, toolchain: Toolchain, onProgress?: (circuit: string, index: number, total: number) => void): Promise<DeepMeasurement[]>;
+/** Human readable byte size. */
+export declare function formatBytes(bytes: number): string;
+/** Human readable duration. */
+export declare function formatMs(ms: number): string;

package/dist/deep.js

@@ -0,0 +1,60 @@
+import { spawn } from "node:child_process";
+import { mkdtempSync, rmSync, statSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { ProfilerError } from "./errors.js";
+/**
+ * Generate real proving keys and measure how long it takes.
+ *
+ * This is the expensive counterpart to `mock-compile`. It is opt in because it
+ * does the work the fast path deliberately skips, which is minutes rather than
+ * seconds on a contract full of high `k` circuits.
+ *
+ * Two things come out of it that cannot be derived from `k` alone: the actual
+ * setup time on this machine, and the prover key size, which is what users end
+ * up downloading and holding in memory.
+ */
+export async function measureDeep(measurements, zkirDir, toolchain, onProgress) {
+    const workDir = mkdtempSync(join(tmpdir(), "nite-zk-keys-"));
+    const results = [];
+    try {
+        for (const [i, m] of measurements.entries()) {
+            onProgress?.(m.circuit, i, measurements.length);
+            const irFile = join(zkirDir, `${m.circuit}.zkir`);
+            const pk = join(workDir, `${m.circuit}.pk`);
+            const vk = join(workDir, `${m.circuit}.vk`);
+            const started = performance.now();
+            // Async so the progress display keeps animating. Key generation is the
+            // longest wait this tool has, so a frozen spinner here reads as a hang.
+            const { status, err } = await new Promise((resolvePromise) => {
+                const child = spawn(toolchain.zkirPath, ["compile", irFile, pk, vk]);
+                let captured = "";
+                child.stderr.on("data", (d) => (captured += d));
+                child.on("close", (code) => resolvePromise({ status: code, err: captured }));
+            });
+            const setupMs = performance.now() - started;
+            if (status !== 0) {
+                throw new ProfilerError(`Key generation failed for ${m.circuit}`, err.trim() || `zkir compile exited with ${status}`);
+            }
+            results.push({ ...m, setupMs, proverKeyBytes: statSync(pk).size });
+        }
+    }
+    finally {
+        rmSync(workDir, { recursive: true, force: true });
+    }
+    return results;
+}
+/** Human readable byte size. */
+export function formatBytes(bytes) {
+    if (bytes < 1024)
+        return `${bytes} B`;
+    if (bytes < 1024 * 1024)
+        return `${(bytes / 1024).toFixed(0)} KB`;
+    return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+}
+/** Human readable duration. */
+export function formatMs(ms) {
+    if (ms < 1000)
+        return `${ms.toFixed(0)}ms`;
+    return `${(ms / 1000).toFixed(1)}s`;
+}

package/dist/diff.d.ts

@@ -0,0 +1,30 @@
+import type { CircuitCost } from "./analyze.ts";
+export interface DiffRow {
+    circuit: string;
+    /** Absent when the circuit does not exist on the base ref. */
+    before?: number;
+    /** Absent when the circuit was removed. */
+    after?: number;
+}
+export interface DiffResult {
+    ref: string;
+    rows: DiffRow[];
+    /** True when any circuit costs more than it did on the base ref. */
+    regressed: boolean;
+}
+/** Repository root, so ref paths can be resolved the way git sees them. */
+export declare function repoRoot(): string;
+/**
+ * Materialise a ref into a temporary directory.
+ *
+ * `git archive` is used rather than a worktree or a checkout, because it never
+ * touches the working tree or the index. Profiling a branch must not disturb
+ * uncommitted work.
+ */
+export declare function materialise(ref: string): Promise<{
+    dir: string;
+    cleanup: () => void;
+}>;
+/** Where a working tree path lives inside the exported ref. */
+export declare function pathWithinRef(source: string, root: string, refDir: string): string;
+export declare function diffCosts(ref: string, before: CircuitCost[], after: CircuitCost[]): DiffResult;