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

package/dist/diff.js

@@ -0,0 +1,64 @@
+import { spawn, spawnSync } from "node:child_process";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join, relative, resolve } from "node:path";
+import { ProfilerError } from "./errors.js";
+function git(args, cwd) {
+    const res = spawnSync("git", args, { encoding: "utf8", cwd });
+    return { status: res.status, out: `${res.stdout ?? ""}`.trim(), err: `${res.stderr ?? ""}`.trim() };
+}
+/** Repository root, so ref paths can be resolved the way git sees them. */
+export function repoRoot() {
+    const res = git(["rev-parse", "--show-toplevel"]);
+    if (res.status !== 0) {
+        throw new ProfilerError("Not a git repository", "`nite-zk diff` compares against a git ref, so it needs to run inside a repository.");
+    }
+    return res.out;
+}
+function assertRefExists(ref) {
+    if (git(["rev-parse", "--verify", `${ref}^{commit}`]).status !== 0) {
+        throw new ProfilerError(`Unknown git ref: ${ref}`, "Pass a branch, tag or commit that exists, for example `nite-zk diff main`.");
+    }
+}
+/**
+ * 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 async function materialise(ref) {
+    assertRefExists(ref);
+    const dir = mkdtempSync(join(tmpdir(), "nite-zk-diff-"));
+    const cleanup = () => rmSync(dir, { recursive: true, force: true });
+    const status = await new Promise((resolvePromise) => {
+        const archive = spawn("git", ["archive", "--format=tar", ref]);
+        const untar = spawn("tar", ["-x", "-C", dir]);
+        archive.stdout.pipe(untar.stdin);
+        let failed = "";
+        archive.stderr.on("data", (d) => (failed += d));
+        untar.on("close", (code) => resolvePromise(code));
+        archive.on("error", () => resolvePromise(null));
+    });
+    if (status !== 0) {
+        cleanup();
+        throw new ProfilerError(`Could not export ${ref}`, "git archive failed. Check the ref is reachable from this repository.");
+    }
+    return { dir, cleanup };
+}
+/** Where a working tree path lives inside the exported ref. */
+export function pathWithinRef(source, root, refDir) {
+    return join(refDir, relative(root, resolve(source)));
+}
+export function diffCosts(ref, before, after) {
+    const beforeK = new Map(before.map((c) => [c.circuit, c.k]));
+    const afterK = new Map(after.map((c) => [c.circuit, c.k]));
+    const names = [...new Set([...beforeK.keys(), ...afterK.keys()])].sort();
+    const rows = names.map((circuit) => ({
+        circuit,
+        before: beforeK.get(circuit),
+        after: afterK.get(circuit),
+    }));
+    const regressed = rows.some((r) => r.before !== undefined && r.after !== undefined && r.after > r.before);
+    return { ref, rows, regressed };
+}

package/dist/estimate.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Proving cost model.
+ *
+ * A Halo2 proof is dominated by FFTs and multi scalar multiplications over the
+ * full 2^k domain, so the work is proportional to 2^k up to a log factor that
+ * is small across the range circuits actually occupy. That gives
+ *
+ *     time = msPerDomainRow * 2^k
+ *
+ * with a single machine dependent constant.
+ *
+ * The default constant is anchored on measured key generation, which performs
+ * comparable domain work on the same machine: 10547ms at k=15, so
+ * 10547 / 2^15 = 0.322 ms per domain row. Proving is not key generation, so
+ * treat the default as an order of magnitude, and calibrate to make it real.
+ */
+export declare const DEFAULT_MS_PER_DOMAIN_ROW = 0.322;
+export interface Calibration {
+    msPerDomainRow: number;
+    /** What the number came from, so a stale calibration can be recognised. */
+    observedMs: number;
+    observedK: number;
+    recordedAt: string;
+}
+export interface ProvingEstimate {
+    ms: number;
+    calibrated: boolean;
+}
+export declare function estimateProvingMs(k: number, calibration?: Calibration): ProvingEstimate;
+/** Turn one observed proof into the machine constant. */
+export declare function calibrationFrom(observedMs: number, observedK: number): Calibration;
+export declare function calibrationPath(budgetPath: string): string;
+export declare function readCalibration(budgetPath: string): Calibration | undefined;
+export declare function writeCalibration(budgetPath: string, calibration: Calibration): void;
+/** Human readable duration, for estimates that span milliseconds to minutes. */
+export declare function formatDuration(ms: number): string;
+/** Human readable byte size. */
+export declare function formatBytes(bytes: number): string;

package/dist/estimate.js

@@ -0,0 +1,85 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+/*
+ * There is deliberately no key size prediction here.
+ *
+ * Key size looked predictable from k: three unrelated circuits at k=13 agreed
+ * within 0.11%, and a synthetic k=15 circuit matched a production one to 0.08%.
+ * It does not hold. At k=16 a production circuit produced 19,524,757 bytes and
+ * a synthetic one 38,513,181, a factor of two apart, with identical verifier
+ * key sizes.
+ *
+ * The likely cause is the extended evaluation domain, which Halo2 sizes by
+ * maximum gate degree. That is not reported by mock-compile, so from k alone
+ * there is no way to tell which case a circuit is in. A figure that is exact
+ * at one k and 2x wrong at the next is worse than no figure, so key size comes
+ * only from --deep, where it is measured.
+ */
+/**
+ * Proving cost model.
+ *
+ * A Halo2 proof is dominated by FFTs and multi scalar multiplications over the
+ * full 2^k domain, so the work is proportional to 2^k up to a log factor that
+ * is small across the range circuits actually occupy. That gives
+ *
+ *     time = msPerDomainRow * 2^k
+ *
+ * with a single machine dependent constant.
+ *
+ * The default constant is anchored on measured key generation, which performs
+ * comparable domain work on the same machine: 10547ms at k=15, so
+ * 10547 / 2^15 = 0.322 ms per domain row. Proving is not key generation, so
+ * treat the default as an order of magnitude, and calibrate to make it real.
+ */
+export const DEFAULT_MS_PER_DOMAIN_ROW = 0.322;
+export function estimateProvingMs(k, calibration) {
+    const rate = calibration?.msPerDomainRow ?? DEFAULT_MS_PER_DOMAIN_ROW;
+    return { ms: rate * 2 ** k, calibrated: calibration !== undefined };
+}
+/** Turn one observed proof into the machine constant. */
+export function calibrationFrom(observedMs, observedK) {
+    return {
+        msPerDomainRow: observedMs / 2 ** observedK,
+        observedMs,
+        observedK,
+        recordedAt: new Date().toISOString(),
+    };
+}
+export function calibrationPath(budgetPath) {
+    return join(dirname(budgetPath), ".nite-zk-calibration.json");
+}
+export function readCalibration(budgetPath) {
+    const file = calibrationPath(budgetPath);
+    if (!existsSync(file))
+        return undefined;
+    try {
+        const parsed = JSON.parse(readFileSync(file, "utf8"));
+        return typeof parsed.msPerDomainRow === "number" && parsed.msPerDomainRow > 0
+            ? parsed
+            : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+export function writeCalibration(budgetPath, calibration) {
+    const file = calibrationPath(budgetPath);
+    mkdirSync(dirname(file), { recursive: true });
+    writeFileSync(file, `${JSON.stringify(calibration, null, 2)}\n`, "utf8");
+}
+/** Human readable duration, for estimates that span milliseconds to minutes. */
+export function formatDuration(ms) {
+    if (ms < 1000)
+        return `${Math.round(ms)}ms`;
+    if (ms < 60_000)
+        return `${(ms / 1000).toFixed(1)}s`;
+    return `${Math.floor(ms / 60_000)}m${Math.round((ms % 60_000) / 1000)}s`;
+}
+/** 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`;
+}

package/dist/measure.d.ts

@@ -13,11 +13,20 @@ export interface Measurement {
  * report that reads as a successful one.
  */
 export declare function parseReport(text: string): Measurement[];
+/** Parse the single file form, whose report names the path rather than the circuit. */
+export declare function parseSingle(text: string, circuit: string): Measurement;
+/** Measure every circuit in a single sequential `zkir` invocation. */
+export declare function measure(zkirDir: string, toolchain: Toolchain, source: string): Measurement[];
 /**
- * Measure every circuit in one `zkir` invocation.
+ * Measure every circuit, several at a time.
+ *
+ * `mock-compile-many` walks the directory sequentially, and its cost is
+ * dominated by the largest circuits: on a nine circuit contract it spent 17s,
+ * of which one circuit accounted for 5.5s. Running the single file form
+ * concurrently cuts that to roughly 9s on eight cores, and each process stays
+ * around 58 MB, so the concurrency is bounded by cores rather than memory.
  *
- * `mock-compile-many` is used rather than per file `mock-compile` because the
- * single file form reports the file path instead of the circuit name, which
- * would leave circuit names to be recovered from filenames.
+ * The single file report names the path instead of the circuit, but the file is
+ * `<circuit>.zkir`, so the name comes from the filename.
  */
-export declare function measure(zkirDir: string, toolchain: Toolchain, source: string): Measurement[];
+export declare function measureParallel(zkirDir: string, toolchain: Toolchain, source: string, onProgress?: (done: number, total: number) => void, concurrency?: number): Promise<Measurement[]>;

package/dist/measure.js

@@ -1,10 +1,14 @@
-import { spawnSync } from "node:child_process";
-import { existsSync } from "node:fs";
+import { spawn, spawnSync } from "node:child_process";
+import { existsSync, readdirSync } from "node:fs";
+import { availableParallelism } from "node:os";
+import { basename, join } from "node:path";
 import { NoProvableCircuitsError, ProfilerError } from "./errors.js";
 /** `  circuit "name" (k=9, rows=305)` */
 const CIRCUIT_LINE = /^\s*circuit\s+"([^"]+)"\s+\(k=(\d+),\s*rows=(\d+)\)\s*$/;
 /** `Mock compiling 2 circuits:` */
 const HEADER_LINE = /^Mock compiling (\d+) circuits?:/m;
+/** Single file form: `Mock compiling circuit "/abs/path.zkir" (k=9, rows=305)` */
+const SINGLE_LINE = /\(k=(\d+),\s*rows=(\d+)\)/;
 /**
  * Parse a `zkir mock-compile-many` report.
  *
@@ -36,17 +40,25 @@ export function parseReport(text) {
     }
     return measurements;
 }
-/**
- * Measure every circuit in one `zkir` invocation.
- *
- * `mock-compile-many` is used rather than per file `mock-compile` because the
- * single file form reports the file path instead of the circuit name, which
- * would leave circuit names to be recovered from filenames.
- */
-export function measure(zkirDir, toolchain, source) {
-    if (!existsSync(zkirDir)) {
-        throw new NoProvableCircuitsError(source);
+/** Parse the single file form, whose report names the path rather than the circuit. */
+export function parseSingle(text, circuit) {
+    const m = text.match(SINGLE_LINE);
+    if (!m) {
+        throw new ProfilerError(`Could not parse the zkir report for ${circuit}`, text.trim() || "(no output)");
     }
+    return { circuit, k: Number(m[1]), rows: Number(m[2]) };
+}
+function zkirFiles(zkirDir, source) {
+    if (!existsSync(zkirDir))
+        throw new NoProvableCircuitsError(source);
+    const files = readdirSync(zkirDir).filter((f) => f.endsWith(".zkir"));
+    if (files.length === 0)
+        throw new NoProvableCircuitsError(source);
+    return files;
+}
+/** Measure every circuit in a single sequential `zkir` invocation. */
+export function measure(zkirDir, toolchain, source) {
+    zkirFiles(zkirDir, source);
     const res = spawnSync(toolchain.zkirPath, ["mock-compile-many", zkirDir], {
         encoding: "utf8",
     });
@@ -59,9 +71,52 @@ export function measure(zkirDir, toolchain, source) {
     if (res.status !== 0) {
         throw new ProfilerError("zkir mock-compile-many failed", output.trim() || `zkir exited with status ${res.status}`);
     }
-    const measurements = parseReport(output);
-    if (measurements.length === 0) {
-        throw new NoProvableCircuitsError(source);
-    }
-    return measurements.sort((a, b) => a.circuit.localeCompare(b.circuit));
+    return parseReport(output).sort((a, b) => a.circuit.localeCompare(b.circuit));
+}
+/**
+ * Measure every circuit, several at a time.
+ *
+ * `mock-compile-many` walks the directory sequentially, and its cost is
+ * dominated by the largest circuits: on a nine circuit contract it spent 17s,
+ * of which one circuit accounted for 5.5s. Running the single file form
+ * concurrently cuts that to roughly 9s on eight cores, and each process stays
+ * around 58 MB, so the concurrency is bounded by cores rather than memory.
+ *
+ * The single file report names the path instead of the circuit, but the file is
+ * `<circuit>.zkir`, so the name comes from the filename.
+ */
+export async function measureParallel(zkirDir, toolchain, source, onProgress, concurrency = Math.max(1, availableParallelism())) {
+    const files = zkirFiles(zkirDir, source);
+    const results = [];
+    let done = 0;
+    let next = 0;
+    onProgress?.(0, files.length);
+    const runOne = (file) => new Promise((resolvePromise, reject) => {
+        const child = spawn(toolchain.zkirPath, ["mock-compile", join(zkirDir, file)]);
+        let out = "";
+        child.stderr.on("data", (d) => (out += d));
+        child.stdout.on("data", (d) => (out += d));
+        child.on("error", (e) => reject(new ProfilerError(`Could not run ${toolchain.zkirPath}`, String(e))));
+        child.on("close", (code) => {
+            if (code !== 0) {
+                reject(new ProfilerError(`zkir mock-compile failed for ${basename(file, ".zkir")}`, out.trim() || `zkir exited with status ${code}`));
+                return;
+            }
+            try {
+                const m = parseSingle(out, basename(file, ".zkir"));
+                onProgress?.(++done, files.length);
+                resolvePromise(m);
+            }
+            catch (e) {
+                reject(e);
+            }
+        });
+    });
+    const worker = async () => {
+        while (next < files.length) {
+            results.push(await runOne(files[next++]));
+        }
+    };
+    await Promise.all(Array.from({ length: Math.min(concurrency, files.length) }, () => worker()));
+    return results.sort((a, b) => a.circuit.localeCompare(b.circuit));
 }

package/dist/progress.d.ts

@@ -0,0 +1,19 @@
+/**
+ * A spinner for the wait, which on a large contract is ten seconds or more.
+ *
+ * Everything goes to stderr so that `nite-zk profile --json > out.json` stays
+ * clean, and it disables itself when stderr is not a terminal so CI logs do not
+ * fill with redraw frames.
+ */
+export declare class Progress {
+    private timer;
+    private frame;
+    private label;
+    private readonly active;
+    constructor(enabled?: boolean);
+    start(label: string): void;
+    update(label: string): void;
+    private render;
+    /** Clear the line so the report starts on clean output. */
+    stop(): void;
+}

package/dist/progress.js

@@ -0,0 +1,51 @@
+import { dim } from "./colors.js";
+const FRAMES = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
+/**
+ * A spinner for the wait, which on a large contract is ten seconds or more.
+ *
+ * Everything goes to stderr so that `nite-zk profile --json > out.json` stays
+ * clean, and it disables itself when stderr is not a terminal so CI logs do not
+ * fill with redraw frames.
+ */
+export class Progress {
+    timer;
+    frame = 0;
+    label = "";
+    active;
+    constructor(enabled = true) {
+        this.active =
+            enabled &&
+                process.stderr.isTTY === true &&
+                (process.env.NO_COLOR === undefined || process.env.NO_COLOR === "");
+    }
+    start(label) {
+        this.label = label;
+        if (!this.active)
+            return;
+        // Draw once up front, so the first phase is visible immediately rather than
+        // after the first tick.
+        this.render();
+        this.timer = setInterval(() => this.render(), 80);
+        this.timer.unref?.();
+    }
+    update(label) {
+        this.label = label;
+        // Redraw straight away so a phase change shows even if the next tick is
+        // still 80ms out.
+        this.render();
+    }
+    render() {
+        if (!this.active)
+            return;
+        const spin = FRAMES[this.frame++ % FRAMES.length];
+        process.stderr.write(`\r\x1b[K${dim(`${spin} ${this.label}`)}`);
+    }
+    /** Clear the line so the report starts on clean output. */
+    stop() {
+        if (this.timer)
+            clearInterval(this.timer);
+        this.timer = undefined;
+        if (this.active)
+            process.stderr.write("\r\x1b[K");
+    }
+}

package/dist/report.d.ts

@@ -1,9 +1,23 @@
-import type { CircuitCost } from "./analyze.ts";
-import type { CheckResult } from "./budget.ts";
+import type { CheckResult, ContractCosts } from "./budget.ts";
+import { type DeepMeasurement } from "./deep.ts";
+import type { DiffResult } from "./diff.ts";
+import { type Calibration } from "./estimate.ts";
 import type { Toolchain } from "./toolchain.ts";
-/** Human readable per circuit cost table. */
-export declare function formatProfile(costs: CircuitCost[], toolchain: Toolchain, elapsedMs: number): string;
-/** Human readable budget comparison. */
+export type DeepByCircuit = Map<string, DeepMeasurement>;
+export interface ProfileOptions {
+    toolchain: Toolchain;
+    elapsedMs: number;
+    deep?: DeepByCircuit;
+    cached?: boolean;
+    calibration?: Calibration;
+    showEstimate?: boolean;
+}
+/** Per circuit cost table, one block per contract. */
+export declare function formatProfile(contracts: ContractCosts[], opts: ProfileOptions): string;
+/** Budget comparison, grouped by contract when there is more than one. */
 export declare function formatCheck(result: CheckResult): string;
-export declare function profileJson(costs: CircuitCost[], toolchain: Toolchain): string;
+/** Comparison against a git ref. */
+export declare function formatDiff(result: DiffResult): string;
+export declare function profileJson(contracts: ContractCosts[], opts: ProfileOptions): string;
 export declare function checkJson(result: CheckResult): string;
+export declare function diffJson(result: DiffResult): string;