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

package/README.md

@@ -38,13 +38,14 @@ It reports the cost class of every circuit in your contract.
 ```text
 $ nite-zk profile Sample.compact
 
-  circuit        rows      k   capacity   cost
-  bump             24      5         32     1x
-  balanceOf       305      9        512    16x
-  register        368      9        512    16x
-  insert32       2299     13       8192   256x
-
-  4 circuits, toolchain 0.31.1, zkir 2.1.0, 0.4s
+  circuit     rows   k  capacity  cost  est. prove
+  bump          24   5        32    1x        ~10ms
+  balanceOf    305   9       512   16x       ~165ms
+  register     368   9       512   16x       ~165ms
+  insert32    2299  13      8192  256x         ~2.6s
+
+  4 circuits, toolchain 0.31.1, midnight-zkir 2.1.0, 0.9s
+  est. prove is modelled as 2^k on an uncalibrated default. Run `nite-zk calibrate` to anchor it.
 ```
 
 `k` is the number that matters. `cost` is `2^k` expressed relative to the cheapest circuit in the contract, so you can see at a glance which circuits dominate your proving budget.
@@ -370,20 +371,21 @@ Anything outside this range is rejected with a clear error naming the version fo
 ## Command line surface
 
 ```text
-nite-zk profile <source...>   Report rows, k and relative cost per circuit
+nite-zk profile <source...>   Report rows, k, cost and estimated proving time
 nite-zk save <source...>      Write zk-budget.json from current measurements
 nite-zk check [<source...>]   Compare against zk-budget.json
 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
 
-  --estimate                  Show modelled proving time per circuit
+  --no-estimate               Hide the modelled proving time column
   --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
   --budget <file>             Use a different baseline path
   --strict                    check: fail on circuits missing from the budget
+  --replace                   save: overwrite the budget instead of merging
   --no-color                  Plain output (NO_COLOR is honoured too)
   --no-cache                  Ignore cached measurements for this run
   +VERSION                    Pin the Compact toolchain, e.g. +0.31.1
@@ -401,6 +403,23 @@ Wrote zk-budget.json: 2 contracts, 16 circuits
 `check` then reads every contract back out of the budget, so CI stays one step
 whether the repository holds one contract or ten.
 
+Contracts can also be added one at a time. `save` merges into an existing
+budget rather than replacing it, and says what it did:
+
+```text
+$ nite-zk save packages/mint/src/mint.compact
+Wrote /repo/zk-budget.json
+  1 contract, 3 circuits
+  added:   packages/mint/src/mint.compact
+  kept:    packages/pool/src/lending.compact
+```
+
+`--replace` writes a fresh file when you do want the old entries gone.
+
+The budget is written relative to the working directory, and `save` prints the
+full path it wrote, so running it from the wrong directory is visible
+immediately rather than leaving a file somewhere unexpected.
+
 ### Comparing against a branch
 
 ```text
@@ -420,8 +439,9 @@ check without committing a budget file first.
 
 ### Estimated proving time
 
-`--estimate` models proving time as `time = rate * 2^k`, since a Halo2 proof is
-dominated by work over the full `2^k` domain.
+`profile` shows an estimated proving time by default, modelled as
+`time = rate * 2^k`, since a Halo2 proof is dominated by work over the full
+`2^k` domain. `--no-estimate` hides the column.
 
 The rate is machine specific, so the shipped default is only an order of
 magnitude. Time one real proof and record it, and every estimate becomes

package/dist/budget.d.ts

@@ -44,6 +44,22 @@ export interface ContractCosts {
 }
 /** Build a budget granting every circuit exactly what it currently costs. */
 export declare function budgetFrom(contracts: ContractCosts[], toolchainLine: string): Budget;
+export interface MergeSummary {
+    added: string[];
+    updated: string[];
+    kept: string[];
+}
+/**
+ * Fold a new save into an existing budget.
+ *
+ * Saving one contract must not silently discard the others. A monorepo is
+ * saved a contract at a time, and without merging each save wipes the previous
+ * one, which looks like it worked and quietly loses the ceilings you committed.
+ */
+export declare function mergeBudgets(existing: Budget, incoming: Budget): {
+    budget: Budget;
+    summary: MergeSummary;
+};
 export declare function writeBudget(path: string, budget: Budget): void;
 export declare function readBudget(path: string): Budget;
 /** Every contract the budget describes. */

package/dist/budget.js

@@ -24,6 +24,33 @@ export function budgetFrom(contracts, toolchainLine) {
         contracts: out,
     };
 }
+/**
+ * Fold a new save into an existing budget.
+ *
+ * Saving one contract must not silently discard the others. A monorepo is
+ * saved a contract at a time, and without merging each save wipes the previous
+ * one, which looks like it worked and quietly loses the ceilings you committed.
+ */
+export function mergeBudgets(existing, incoming) {
+    const contracts = { ...existing.contracts };
+    const summary = { added: [], updated: [], kept: [] };
+    for (const [source, contract] of Object.entries(incoming.contracts)) {
+        (source in contracts ? summary.updated : summary.added).push(source);
+        contracts[source] = contract;
+    }
+    for (const source of Object.keys(existing.contracts)) {
+        if (!(source in incoming.contracts) && source.length > 0)
+            summary.kept.push(source);
+    }
+    return {
+        budget: { ...incoming, contracts },
+        summary: {
+            added: summary.added.sort(),
+            updated: summary.updated.sort(),
+            kept: summary.kept.sort(),
+        },
+    };
+}
 export function writeBudget(path, budget) {
     writeFileSync(path, `${JSON.stringify(budget, null, 2)}\n`, "utf8");
 }

package/dist/cli.d.ts

@@ -5,6 +5,7 @@ interface Options {
     ref?: string;
     json: boolean;
     strict: boolean;
+    replace: boolean;
     deep: boolean;
     estimate: boolean;
     noColor: boolean;

package/dist/cli.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import { dirname, isAbsolute, relative, resolve } from "node:path";
 import { analyze } from "./analyze.js";
-import { DEFAULT_BUDGET_PATH, budgetFrom, budgetSources, check, readBudget, writeBudget, } from "./budget.js";
+import { DEFAULT_BUDGET_PATH, budgetFrom, budgetSources, check, mergeBudgets, readBudget, writeBudget, } from "./budget.js";
 import { cacheKey, readCache, writeCache } from "./cache.js";
 import { setColorEnabled } from "./colors.js";
 import { compileSkipZk } from "./compile.js";
@@ -17,7 +17,7 @@ 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 profile <source...>   Report rows, k, cost and estimated proving time
   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
@@ -27,13 +27,14 @@ Usage:
                                 Anchor proving estimates to a real proof
 
 Options:
-  --estimate                    Show modelled proving time per circuit
+  --no-estimate                 Hide the modelled proving time column
   --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
+  --replace                     save: overwrite the budget instead of merging
   --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
@@ -47,8 +48,9 @@ export function parseArgs(argv) {
         sources: [],
         json: false,
         strict: false,
+        replace: false,
         deep: false,
-        estimate: false,
+        estimate: true,
         noColor: false,
         noCache: false,
         budget: DEFAULT_BUDGET_PATH,
@@ -61,10 +63,14 @@ export function parseArgs(argv) {
             opts.json = true;
         else if (arg === "--strict")
             opts.strict = true;
+        else if (arg === "--replace")
+            opts.replace = true;
         else if (arg === "--deep")
             opts.deep = true;
         else if (arg === "--estimate")
             opts.estimate = true;
+        else if (arg === "--no-estimate")
+            opts.estimate = false;
         else if (arg === "--no-color")
             opts.noColor = true;
         else if (arg === "--no-cache")
@@ -260,12 +266,36 @@ export async function run(argv) {
     // 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 fresh = budgetFrom(run_.contracts.map((c) => ({ source: relative(base, resolve(c.source)), costs: c.costs })), line);
+    // Merge rather than overwrite. Saving one contract at a time is the normal
+    // way to set up a monorepo, and replacing the file each time would discard
+    // ceilings that are already committed, silently and while reporting success.
+    let existing;
+    if (!opts.replace) {
+        try {
+            existing = readBudget(opts.budget);
+        }
+        catch {
+            existing = undefined;
+        }
+    }
+    const merged = existing ? mergeBudgets(existing, fresh) : { budget: fresh, summary: undefined };
+    writeBudget(opts.budget, merged.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");
+    const written = resolve(opts.budget);
+    process.stdout.write(`Wrote ${written}\n` +
+        `  ${run_.contracts.length} contract${run_.contracts.length === 1 ? "" : "s"}, ` +
+        `${circuits} circuit${circuits === 1 ? "" : "s"}\n`);
+    const s_ = merged.summary;
+    if (s_) {
+        if (s_.added.length)
+            process.stdout.write(`  added:   ${s_.added.join(", ")}\n`);
+        if (s_.updated.length)
+            process.stdout.write(`  updated: ${s_.updated.join(", ")}\n`);
+        if (s_.kept.length)
+            process.stdout.write(`  kept:    ${s_.kept.join(", ")}\n`);
+    }
+    process.stdout.write("Check it in, then run `nite-zk check` in CI.\n");
     return 0;
 }
 export async function main(argv) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nite-framework/nite-zk-profiler",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "description": "See what a Compact circuit costs to prove, without generating proving keys",
   "type": "module",
   "bin": {