Skip to content

feat(builder): write circuit-info.json into the artifact dir - #191

Merged
0xisk merged 1 commit into
mainfrom
feat/builder-circuit-info-in-artifacts
Sep 16, 2026
Merged

0xisk merged 1 commit into
mainfrom
feat/builder-circuit-info-in-artifacts

Conversation

@0xisk

@0xisk 0xisk commented Sep 16, 2026 •

Copy link
Copy Markdown
Member

Types of changes

  • Bugfix (non-breaking change which fixes an issue)
  • New feature (non-breaking change which adds functionality)
  • Breaking change (fix or feature that would cause existing functionality to not work as expected)
  • Documentation Update (if none of the other choices apply)

Every ZK compile through CompactCompiler now writes <artifacts>/<Contract>/circuit-info.json beside the compiler's compiler/contract-info.json, and nothing into the source tree. --skip-zk writes nothing, as before.

Not visible in the diff:

PR Checklist

  • I have read the Contributing Guide
  • I have added tests that prove my fix is effective or that my feature works
  • I have added documentation of new methods and any new behavior or changes to existing behavior
  • CI Workflows Are Passing

Summary by CodeRabbit

  • New Features

    • Circuit compilation now generates a circuit-info.json file in each contract’s artifact directory.
    • Metadata includes the source path, generation time, circuit names, constraint values, and row counts.
    • Artifact paths support flattened output by default and preserve source subdirectories when hierarchical output is enabled.
    • Existing metadata files are replaced with current compilation details rather than merged.
  • Documentation

    • Added documentation describing artifact directory layouts and metadata generation, including the --skip-zk exception.

The parsed `k` / `rows` per circuit went to a hidden `.circuit-info.json`
beside the compiled source, merged per directory and keyed by file
name. Measurements are build output, not source, so they now land in
the contract's own artifact directory beside `compiler/`, one file per
contract with the source path recorded inside it.

`artifactDir` is the single place the flattened / hierarchical layout is
computed, shared by the compile step and the writer.
@0xisk
0xisk requested review from a team as code owners September 16, 2026 03:45
@coderabbitai

coderabbitai Bot commented Sep 16, 2026 •

Copy link
Copy Markdown

Review Change StackReview Change Stack

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info
⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Essentials

Run ID: 9217c146-eb83-4e7d-a802-1cf54b6d0ba0

📥 Commits

Reviewing files that changed from the base of the PR and between e8090bc and 072f136.

📒 Files selected for processing (7)
  • .gitignore
  • packages/builder/README.md
  • packages/builder/src/Compiler.ts
  • packages/builder/src/services/CompilerService.ts
  • packages/builder/src/utils.ts
  • packages/builder/test/Compiler.test.ts
  • packages/builder/test/utils.test.ts
💤 Files with no reviewable changes (1)
  • .gitignore

Included review availability: 4 reviews are currently available. Your included PR review attempts over the past 7 days set your current allowance at 5 reviews per hour.


Walkthrough

The builder now writes per-contract circuit-info.json files under resolved artifact directories. It supports flattened and hierarchical layouts, replaces the previous source-directory cache format, updates compiler integration, and adds documentation and tests.

Changes

Artifact metadata output

Layer / File(s) Summary
Artifact resolution and metadata persistence
packages/builder/src/utils.ts, packages/builder/test/utils.test.ts
Added artifactDir and replaced writeCircuitInfoJson with writeCircuitInfo. Metadata now records the source, generation time, and ordered circuit constraints in circuit-info.json.
Compiler integration and output routing
packages/builder/src/Compiler.ts, packages/builder/src/services/CompilerService.ts, packages/builder/test/Compiler.test.ts
Compilation uses the shared artifact directory resolver and writes metadata to the resolved contract artifact directory. Tests verify the generated file and parsed circuit metadata.
Artifact layout documentation and repository cleanup
packages/builder/README.md, .gitignore
Documented flattened and hierarchical artifact layouts. Removed the obsolete .circuit-info.json ignore rule.

Priority: ⬇️ Low

Estimated code review effort: 3 (Moderate) | ~20 minutes

Change: Feature

Sequence Diagram(s)

sequenceDiagram
  participant CompilerService
  participant CompactCompiler
  participant artifactDir
  participant writeCircuitInfo
  participant FileSystem
  CompilerService->>artifactDir: resolve compilation output directory
  CompilerService->>CompactCompiler: compile source into artifact directory
  CompactCompiler->>artifactDir: resolve metadata directory
  CompactCompiler->>writeCircuitInfo: write source and circuit constraints
  writeCircuitInfo->>FileSystem: create directory and replace circuit-info.json
Loading

Suggested reviewers: andrew-fleming

Merge Risk: ⚪ Minimal · up to 072f1

No verified merge-blocking behavior remains in the changed artifact metadata flow.

🚥 Pre-merge checks | ✅ 5
✅ Passed checks (5 passed)
Check name Status Explanation
Description Check ✅ Passed Check skipped - CodeRabbit’s high-level summary is enabled.
Title check ✅ Passed The title clearly and concisely describes the primary change: writing circuit-info.json into the artifact directory.
Docstring Coverage ✅ Passed Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 3 functions across 5 files. (1 skipped: 1 …
Linked Issues check ✅ Passed Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check ✅ Passed Check skipped because no linked issues were found for this pull request.
✨ Finishing Touches
📝 Generate docstrings
  • Create stacked PR
  • Commit on current branch
🧪 Generate unit tests (beta)
  • Create PR with unit tests
  • Commit unit tests in branch feat/builder-circuit-info-in-artifacts

A rabbit hops through artifacts bright
New circuit notes land just right
Flat or nested, paths now align
Metadata follows a clearer design
The builder thumps its feet: compile!

Comment @coderabbitai help to get the list of available commands.

@0xisk
0xisk merged commit 9599e1e into main Sep 16, 2026
10 checks passed
@0xisk
0xisk deleted the feat/builder-circuit-info-in-artifacts branch September 16, 2026 08:03
0xisk added a commit that referenced this pull request Nov 17, 2026
Since #191 the builder writes circuit-info.json into the artifact
directory, so the `.circuit-info.json` beside a source is compact-lint's
own cache.
0xisk added a commit that referenced this pull request Nov 17, 2026
* feat(tree-sitter-compact): add declaration-level Compact grammar

Adds a Cargo workspace and a tree-sitter grammar that resolves every
Compact declaration to a named node while leaving bodies, parameter
lists and expressions opaque. The grammar exists to feed a doc-comment
linter, so precision stops at the declaration boundary and the full
expression grammar is out of scope.

* grammar: fourteen declaration kinds with `name` fields, recursive
  module bodies, three comment kinds as extras, structured type
  expressions so nested generic arguments resolve.
* binding: native Rust binding, generated parser committed, CI fails
  when regeneration changes it.
* tests: tree-sitter corpus plus a Rust corpus test that rejects any
  ERROR or MISSING node over the upstream formatter fixtures, the
  in-repo Compact sources, and an optional external tree.

* refactor(compact-tree-sitter): rename the grammar crate

Every crate in this workspace is named compact-*, so the grammar
crate follows suit instead of the tree-sitter-<lang> convention.
The grammar name in tree-sitter.json and the generated C symbol
stay `compact`; only the Cargo package and its directory move.

* feat(compact-lint): add the check command

Adds the compact-lint CLI with one subcommand, check, that enforces
per-declaration-kind doc-comment templates from compact-lint.toml and
optionally runs compact format --check. Findings print one per line
as path:line:col: rule: message on stdout; exit 1 on findings, 2 on
any error. fix and fill-constraints come later and only add tables
to the same toml.

* doc: tags parsed into an ordered list with line and column, so a
  finding points at the @ of the offending tag.
* rules: missing-doc, missing-tag, forbidden-tag, module-name,
  missing-constraints, constraints-format, constraints-placeholder
  (--strict), parse, format. Constraints apply to exported non-pure
  circuits only.
* config: every field optional, unknown keys and tags without their @
  rejected; an explicit --config is a preset anchored at the cwd.
* tests: one fixture case per rule through the binary, plus unit
  tests per module.

* feat(compact-lint): add the fix command

Adds fix, which rewrites doc comments so a following check is clean
for every rule it covers and a second fix is a no-op. Detection now
yields a structured Issue that check renders as a Finding and fix
renders as an Edit, so the two subcommands cannot disagree.

* fix: doc skeletons above undocumented declarations, missing tags in
  config order (a missing @description adopts prose that opens the
  body), the constraints placeholder after the description block,
  tag renames from the new [tags] rename map, and @module name
  repairs. Edits on one comment merge into a single replacement;
  files are rewritten atomically with their line ending and
  permissions kept.
* target: config and path resolution shared by check and fix.
* config: [fix] placeholder and [tags] rename, both validated.
* tests: one before/after fixture per rule through the binary, run
  on a temp copy and followed by check and a second fix.

* feat(compact-lint): add the fill-constraints command

Adds fill-constraints, which measures every circuit that already
carries the constraints tag and writes k and rows into it. The values
exist only on the compiler terminal output, so each measurement
source compiles once under a pty and the progress lines are parsed.
A library module is measured through the mock contract that exports
its circuit names; presets compile themselves.

* measure: portable-pty compile, escape and redraw cleanup, proof
  filter from contract-info.json, and the .circuit-info.json cache
  in the shape the TypeScript builder writes so both tools share it.
* source: overrides, then self globs, then mock templates.
* fill: rewrite only the tag value; unmeasured circuits stay as they
  are and exit 1; --no-compile reads the cache; --dry-run writes
  nothing, the cache included.
* tests: a fake compact script drives the pty path in CI; a captured
  transcript pins the parser.

* test(compact-lint): track the seeded cache fixture

The root .gitignore drops every .circuit-info.json, so the cache the
fill-no-compile case reads never reached CI and the test failed there.

* ci(rust): stop persisting checkout credentials

The default checkout leaves the job's GITHUB_TOKEN in
.git/config, so any later step or build script in the job can
read and reuse it. Nothing in this workflow talks to the remote
after checkout, so opt out.

* docs(compact-tree-sitter): correct the name field claim

Both the grammar header and the README said every declaration
node carries a `name` field. Four do not, and a consumer that
reads `name` unconditionally gets nothing back for them.

* test(compact-tree-sitter): skip symlinks in the corpus walk

A symlinked directory inside the corpus makes the recursion
loop, and a symlinked file is walked twice. Skip both.

* fix(compact-lint): resolve explicit paths against cwd

Discovery matches exclude globs against paths relative to the
config's directory, but an explicit CLI path stayed relative to
the process cwd. Running `check archive` from a subdirectory
produced `archive/X.compact`, which never matched an exclude
written as `contracts/archive/**`, so excluded files were
silently linted. Anchor relative CLI paths at cwd first; the
display step still strips cwd, so the report is unchanged.

* refactor(compact-lint): mark Tag::new must_use

A constructor with no side effects; matches the rest of Tag.

* fix(compact-lint): check constraints under docs = none

The constraints rule ran after the per-kind docs gate, so
kinds.circuit.docs = "none" silently disabled it. The rule is
fixed rather than configurable, so it now runs before the gate;
only the required-tag loop stays behind it.

* fix(compact-lint): skip inserting a tag a rename supplies

A config that forbids @return, renames it to @returns and
requires @returns produced both a rename edit and an insert
edit on the same doc comment, so fix left the comment with
@returns twice. Drop the insert when a rename in that comment
already yields the missing tag.

* fix(compact-lint): validate the fix placeholder

The placeholder is written onto a `*` line of a generated doc
comment. An empty one produced a blank tag line, a multi-line
one broke the comment layout, and one containing `*/` closed
the comment early and corrupted the source. Reject all three at
load time instead.

* fix(compact-lint): validate rename against forbid

A rename only fires from a forbidden-tag finding, so a key that
tags.forbid does not list is dead config the author expects to
work. A value that tags.forbid does list makes fix rewrite one
finding into another, so a second run reports the replacement.
Reject both at load time.

* fix(compact-lint): write through a unique temp file

The staging file was `<name>.compact.tmp` beside the source and
written with fs::write, so a pre-existing file of that name was
truncated, and the predictable name let anything else with write
access to the directory plant one. Create a sibling
`.<name>.<pid>.<nanos>.tmp` exclusively instead, write through
the handle, and remove it when a later step fails.

* docs(compact-lint): tag output fences as text

Bare fences trip markdownlint MD040 and give the renderer
nothing to go on.

* fix(compact-lint): keep leading parent components

normalize popped on every `..`, so a parent-relative
constraints template or CLI path lost its leading `..` and
first_existing probed a path under the working directory
instead of beside it. Only cancel a `..` that has a real
component to cancel.

* feat(compact-lint): add the check command

Adds the compact-lint CLI with one subcommand, check, that enforces
per-declaration-kind doc-comment templates from compact-lint.toml and
optionally runs compact format --check. Findings print one per line
as path:line:col: rule: message on stdout; exit 1 on findings, 2 on
any error. fix and fill-constraints come later and only add tables
to the same toml.

* doc: tags parsed into an ordered list with line and column, so a
  finding points at the @ of the offending tag.
* rules: missing-doc, missing-tag, forbidden-tag, module-name,
  missing-constraints, constraints-format, constraints-placeholder
  (--strict), parse, format. Constraints apply to exported non-pure
  circuits only.
* config: every field optional, unknown keys and tags without their @
  rejected; an explicit --config is a preset anchored at the cwd.
* tests: one fixture case per rule through the binary, plus unit
  tests per module.

* fix(compact-lint): resolve explicit paths against cwd

Discovery matches exclude globs against paths relative to the
config's directory, but an explicit CLI path stayed relative to
the process cwd. Running `check archive` from a subdirectory
produced `archive/X.compact`, which never matched an exclude
written as `contracts/archive/**`, so excluded files were
silently linted. Anchor relative CLI paths at cwd first; the
display step still strips cwd, so the report is unchanged.

* refactor(compact-lint): mark Tag::new must_use

A constructor with no side effects; matches the rest of Tag.

* fix(compact-lint): check constraints under docs = none

The constraints rule ran after the per-kind docs gate, so
kinds.circuit.docs = "none" silently disabled it. The rule is
fixed rather than configurable, so it now runs before the gate;
only the required-tag loop stays behind it.

* fix(compact-lint): keep the closing */ on a module-name fix

set_module_name replaced the first word after @module, which
swallowed a `*/` sharing that word or standing alone after the tag,
so the comment ran on and turned the module into comment text.
Split the terminator off before the rewrite. As a backstop, fix
reparses the rewritten text and refuses to write when its
declarations change.

* fix(compact-lint): move delimiter-line text before inserting

Tag and prose searches covered only the lines between `/**` and
`*/`, so a tag or prose sharing either delimiter line was missed: an
insertion split a tag from its continuation and opening prose was
never adopted. Before any insertion, move that text onto a body line
of its own, as the one-liner expansion already did.

* fix(compact-lint): write the constraints tag only once

A rename to the constraints tag still let missing-constraints insert
a `k=?, rows=?` line above the renamed one, and that placeholder hid
the measured value. Listing the constraints tag in kinds.circuit.tags
duplicated it the same way, through the skeleton and through
missing-tag. Skip those inserts when another edit on the same
comment already writes the tag.

* fix(compact-lint): keep a note when k/rows match

fill-constraints compared the whole first line, so a current value with
a note such as `(zkir-v3)` read as stale and was rewritten without it.
Compare only the k/rows part; a changed value still drops the note.

* docs(compact-lint): drop the shared-cache claim

Since #191 the builder writes circuit-info.json into the artifact
directory, so the `.circuit-info.json` beside a source is compact-lint's
own cache.

* fix(compact-lint): keep edits saved during a fill

fill-constraints read every source before compiling and wrote the old
text back afterwards, so a change saved during a compile was lost. Each
file is now read again before the first write, and a changed one stops
the run with nothing written.

* fix(compact-lint): measure under NO_COLOR

Compiler 0.34.0 prints no progress lines when NO_COLOR is set, so every
circuit read as unmeasured and the empty list replaced the cache entry.
The compiler no longer inherits NO_COLOR, and a compile that proves a
circuit without printing its measurement is an error that leaves the
cache alone.

* refactor(compact-lint): share one path normalize

* fix(compact-lint): measure up to 500 circuits per compile

The compiler prints only as many circuit lines as the pty has rows. At
60 rows a larger contract lost lines, which now fails the compile.
0xisk added a commit that referenced this pull request Nov 17, 2026
* feat(tree-sitter-compact): add declaration-level Compact grammar

Adds a Cargo workspace and a tree-sitter grammar that resolves every
Compact declaration to a named node while leaving bodies, parameter
lists and expressions opaque. The grammar exists to feed a doc-comment
linter, so precision stops at the declaration boundary and the full
expression grammar is out of scope.

* grammar: fourteen declaration kinds with `name` fields, recursive
  module bodies, three comment kinds as extras, structured type
  expressions so nested generic arguments resolve.
* binding: native Rust binding, generated parser committed, CI fails
  when regeneration changes it.
* tests: tree-sitter corpus plus a Rust corpus test that rejects any
  ERROR or MISSING node over the upstream formatter fixtures, the
  in-repo Compact sources, and an optional external tree.

* refactor(compact-tree-sitter): rename the grammar crate

Every crate in this workspace is named compact-*, so the grammar
crate follows suit instead of the tree-sitter-<lang> convention.
The grammar name in tree-sitter.json and the generated C symbol
stay `compact`; only the Cargo package and its directory move.

* feat(compact-lint): add the check command

Adds the compact-lint CLI with one subcommand, check, that enforces
per-declaration-kind doc-comment templates from compact-lint.toml and
optionally runs compact format --check. Findings print one per line
as path:line:col: rule: message on stdout; exit 1 on findings, 2 on
any error. fix and fill-constraints come later and only add tables
to the same toml.

* doc: tags parsed into an ordered list with line and column, so a
  finding points at the @ of the offending tag.
* rules: missing-doc, missing-tag, forbidden-tag, module-name,
  missing-constraints, constraints-format, constraints-placeholder
  (--strict), parse, format. Constraints apply to exported non-pure
  circuits only.
* config: every field optional, unknown keys and tags without their @
  rejected; an explicit --config is a preset anchored at the cwd.
* tests: one fixture case per rule through the binary, plus unit
  tests per module.

* feat(compact-lint): add the fix command

Adds fix, which rewrites doc comments so a following check is clean
for every rule it covers and a second fix is a no-op. Detection now
yields a structured Issue that check renders as a Finding and fix
renders as an Edit, so the two subcommands cannot disagree.

* fix: doc skeletons above undocumented declarations, missing tags in
  config order (a missing @description adopts prose that opens the
  body), the constraints placeholder after the description block,
  tag renames from the new [tags] rename map, and @module name
  repairs. Edits on one comment merge into a single replacement;
  files are rewritten atomically with their line ending and
  permissions kept.
* target: config and path resolution shared by check and fix.
* config: [fix] placeholder and [tags] rename, both validated.
* tests: one before/after fixture per rule through the binary, run
  on a temp copy and followed by check and a second fix.

* feat(compact-lint): add the fill-constraints command

Adds fill-constraints, which measures every circuit that already
carries the constraints tag and writes k and rows into it. The values
exist only on the compiler terminal output, so each measurement
source compiles once under a pty and the progress lines are parsed.
A library module is measured through the mock contract that exports
its circuit names; presets compile themselves.

* measure: portable-pty compile, escape and redraw cleanup, proof
  filter from contract-info.json, and the .circuit-info.json cache
  in the shape the TypeScript builder writes so both tools share it.
* source: overrides, then self globs, then mock templates.
* fill: rewrite only the tag value; unmeasured circuits stay as they
  are and exit 1; --no-compile reads the cache; --dry-run writes
  nothing, the cache included.
* tests: a fake compact script drives the pty path in CI; a captured
  transcript pins the parser.

* test(compact-lint): track the seeded cache fixture

The root .gitignore drops every .circuit-info.json, so the cache the
fill-no-compile case reads never reached CI and the test failed there.

* build(compact-lint): ship prebuilt binaries through npm

Adds the @openzeppelin/compact-lint npm package, a Node bin that
fetches the prebuilt compact-lint binary for the host from the GitHub
release of the same version, verifies it against checksums.txt, caches
it inside the package, and passes arguments and exit codes through.
COMPACT_LINT_BINARY skips the download for source builds and
air-gapped CI.

* release.yml: compact-lint bumps package.json and the crate version
  together and refreshes Cargo.lock.
* release-publish.yml: detection becomes its own job; a four-runner
  matrix builds the Linux and macOS binaries and the publish job
  creates the GitHub release with the assets before npm publish, so
  the package never points at a release that is not there yet.
* Cargo.toml: stripped, thin-LTO release profile (3.3 MiB binary).
* tests: target mapping, checksum verification, the download path
  against a local server, pass-through, and a guard that the npm and
  crate versions agree.

* build(compact-linter): name the npm package compact-linter

The published packages are compact-builder, compact-cli,
compact-deployer and compact-simulator, so the wrapper follows the
same shape as @openzeppelin/compact-linter under packages/linter,
with a compact-linter bin and a compact-linter/v<version> release
tag. The crate, its binary and the release asset names stay
compact-lint.

* build(compact-linter): finish the compact-linter rename

Carries the content half of the rename: manifest name and bin,
release tag path, stderr prefix, workflows, docs and the lockfile.
The previous commit only moved the directory.

* ci(rust): stop persisting checkout credentials

The default checkout leaves the job's GITHUB_TOKEN in
.git/config, so any later step or build script in the job can
read and reuse it. Nothing in this workflow talks to the remote
after checkout, so opt out.

* docs(compact-tree-sitter): correct the name field claim

Both the grammar header and the README said every declaration
node carries a `name` field. Four do not, and a consumer that
reads `name` unconditionally gets nothing back for them.

* test(compact-tree-sitter): skip symlinks in the corpus walk

A symlinked directory inside the corpus makes the recursion
loop, and a symlinked file is walked twice. Skip both.

* fix(compact-lint): resolve explicit paths against cwd

Discovery matches exclude globs against paths relative to the
config's directory, but an explicit CLI path stayed relative to
the process cwd. Running `check archive` from a subdirectory
produced `archive/X.compact`, which never matched an exclude
written as `contracts/archive/**`, so excluded files were
silently linted. Anchor relative CLI paths at cwd first; the
display step still strips cwd, so the report is unchanged.

* refactor(compact-lint): mark Tag::new must_use

A constructor with no side effects; matches the rest of Tag.

* fix(compact-lint): check constraints under docs = none

The constraints rule ran after the per-kind docs gate, so
kinds.circuit.docs = "none" silently disabled it. The rule is
fixed rather than configurable, so it now runs before the gate;
only the required-tag loop stays behind it.

* fix(compact-lint): skip inserting a tag a rename supplies

A config that forbids @return, renames it to @returns and
requires @returns produced both a rename edit and an insert
edit on the same doc comment, so fix left the comment with
@returns twice. Drop the insert when a rename in that comment
already yields the missing tag.

* fix(compact-lint): validate the fix placeholder

The placeholder is written onto a `*` line of a generated doc
comment. An empty one produced a blank tag line, a multi-line
one broke the comment layout, and one containing `*/` closed
the comment early and corrupted the source. Reject all three at
load time instead.

* fix(compact-lint): validate rename against forbid

A rename only fires from a forbidden-tag finding, so a key that
tags.forbid does not list is dead config the author expects to
work. A value that tags.forbid does list makes fix rewrite one
finding into another, so a second run reports the replacement.
Reject both at load time.

* fix(compact-lint): write through a unique temp file

The staging file was `<name>.compact.tmp` beside the source and
written with fs::write, so a pre-existing file of that name was
truncated, and the predictable name let anything else with write
access to the directory plant one. Create a sibling
`.<name>.<pid>.<nanos>.tmp` exclusively instead, write through
the handle, and remove it when a later step fails.

* docs(compact-lint): tag output fences as text

Bare fences trip markdownlint MD040 and give the renderer
nothing to go on.

* fix(compact-lint): keep leading parent components

normalize popped on every `..`, so a parent-relative
constraints template or CLI path lost its leading `..` and
first_existing probed a path under the working directory
instead of beside it. Only cancel a `..` that has a real
component to cancel.

* feat(compact-lint): add the check command

Adds the compact-lint CLI with one subcommand, check, that enforces
per-declaration-kind doc-comment templates from compact-lint.toml and
optionally runs compact format --check. Findings print one per line
as path:line:col: rule: message on stdout; exit 1 on findings, 2 on
any error. fix and fill-constraints come later and only add tables
to the same toml.

* doc: tags parsed into an ordered list with line and column, so a
  finding points at the @ of the offending tag.
* rules: missing-doc, missing-tag, forbidden-tag, module-name,
  missing-constraints, constraints-format, constraints-placeholder
  (--strict), parse, format. Constraints apply to exported non-pure
  circuits only.
* config: every field optional, unknown keys and tags without their @
  rejected; an explicit --config is a preset anchored at the cwd.
* tests: one fixture case per rule through the binary, plus unit
  tests per module.

* fix(compact-lint): resolve explicit paths against cwd

Discovery matches exclude globs against paths relative to the
config's directory, but an explicit CLI path stayed relative to
the process cwd. Running `check archive` from a subdirectory
produced `archive/X.compact`, which never matched an exclude
written as `contracts/archive/**`, so excluded files were
silently linted. Anchor relative CLI paths at cwd first; the
display step still strips cwd, so the report is unchanged.

* refactor(compact-lint): mark Tag::new must_use

A constructor with no side effects; matches the rest of Tag.

* fix(compact-lint): check constraints under docs = none

The constraints rule ran after the per-kind docs gate, so
kinds.circuit.docs = "none" silently disabled it. The rule is
fixed rather than configurable, so it now runs before the gate;
only the required-tag loop stays behind it.

* fix(compact-lint): keep the closing */ on a module-name fix

set_module_name replaced the first word after @module, which
swallowed a `*/` sharing that word or standing alone after the tag,
so the comment ran on and turned the module into comment text.
Split the terminator off before the rewrite. As a backstop, fix
reparses the rewritten text and refuses to write when its
declarations change.

* fix(compact-lint): move delimiter-line text before inserting

Tag and prose searches covered only the lines between `/**` and
`*/`, so a tag or prose sharing either delimiter line was missed: an
insertion split a tag from its continuation and opening prose was
never adopted. Before any insertion, move that text onto a body line
of its own, as the one-liner expansion already did.

* fix(compact-lint): write the constraints tag only once

A rename to the constraints tag still let missing-constraints insert
a `k=?, rows=?` line above the renamed one, and that placeholder hid
the measured value. Listing the constraints tag in kinds.circuit.tags
duplicated it the same way, through the skeleton and through
missing-tag. Skip those inserts when another edit on the same
comment already writes the tag.

* fix(compact-lint): keep a note when k/rows match

fill-constraints compared the whole first line, so a current value with
a note such as `(zkir-v3)` read as stale and was rewritten without it.
Compare only the k/rows part; a changed value still drops the note.

* docs(compact-lint): drop the shared-cache claim

Since #191 the builder writes circuit-info.json into the artifact
directory, so the `.circuit-info.json` beside a source is compact-lint's
own cache.

* fix(compact-lint): keep edits saved during a fill

fill-constraints read every source before compiling and wrote the old
text back afterwards, so a change saved during a compile was lost. Each
file is now read again before the first write, and a changed one stops
the run with nothing written.

* fix(compact-lint): measure under NO_COLOR

Compiler 0.34.0 prints no progress lines when NO_COLOR is set, so every
circuit read as unmeasured and the empty list replaced the cache entry.
The compiler no longer inherits NO_COLOR, and a compile that proves a
circuit without printing its measurement is an error that leaves the
cache alone.

* refactor(compact-lint): share one path normalize

* fix(compact-lint): measure up to 500 circuits per compile

The compiler prints only as many circuit lines as the pty has rows. At
60 rows a larger contract lost lines, which now fails the compile.

* fix(compact-linter): cache the binary per user

The binary was cached under `.cache/` inside the installed package,
which is read-only under Yarn Plug'n'Play and in global or container
installs, so the first run failed with EROFS or EACCES. It now goes to
`$XDG_CACHE_HOME` or `~/.cache` on Linux and `~/Library/Caches` on
macOS.

* fix(compact-linter): never replace published release assets

A manual re-run from a later commit could rebuild the binaries and
--clobber them, with checksums.txt, onto the old tag's release. New
installs then verified the replaced binary against the replaced
checksums.

* The detect job fails when the version's tag names another commit,
  and every job checks out the commit detect checked.
* An existing release keeps its assets; the re-run ships its
  checksums.txt instead of uploading.
* The npm package carries checksums.txt, and the launcher verifies
  downloads against it, never the release's copy.

* fix(compact-linter): reject musl hosts

Node reports linux on musl systems such as Alpine, so the launcher
downloaded a glibc binary that cannot start there. A musl host now
fails with a message pointing at a source build and
COMPACT_LINT_BINARY.

* ci(compact-linter): keep the binary build token-free

* docs: describe the release dependency graph

* ci(compact-linter): check the commit after checkout

CodeQL reads a checkout of another job's output as untrusted code.
Check out the dispatched ref as before, and fail when it is not the
commit the detect job checked.
0xisk added a commit that referenced this pull request Nov 18, 2026
…tifacts (#189)

* feat(tree-sitter-compact): add declaration-level Compact grammar

Adds a Cargo workspace and a tree-sitter grammar that resolves every
Compact declaration to a named node while leaving bodies, parameter
lists and expressions opaque. The grammar exists to feed a doc-comment
linter, so precision stops at the declaration boundary and the full
expression grammar is out of scope.

* grammar: fourteen declaration kinds with `name` fields, recursive
  module bodies, three comment kinds as extras, structured type
  expressions so nested generic arguments resolve.
* binding: native Rust binding, generated parser committed, CI fails
  when regeneration changes it.
* tests: tree-sitter corpus plus a Rust corpus test that rejects any
  ERROR or MISSING node over the upstream formatter fixtures, the
  in-repo Compact sources, and an optional external tree.

* refactor(compact-tree-sitter): rename the grammar crate

Every crate in this workspace is named compact-*, so the grammar
crate follows suit instead of the tree-sitter-<lang> convention.
The grammar name in tree-sitter.json and the generated C symbol
stay `compact`; only the Cargo package and its directory move.

* feat(compact-lint): add the check command

Adds the compact-lint CLI with one subcommand, check, that enforces
per-declaration-kind doc-comment templates from compact-lint.toml and
optionally runs compact format --check. Findings print one per line
as path:line:col: rule: message on stdout; exit 1 on findings, 2 on
any error. fix and fill-constraints come later and only add tables
to the same toml.

* doc: tags parsed into an ordered list with line and column, so a
  finding points at the @ of the offending tag.
* rules: missing-doc, missing-tag, forbidden-tag, module-name,
  missing-constraints, constraints-format, constraints-placeholder
  (--strict), parse, format. Constraints apply to exported non-pure
  circuits only.
* config: every field optional, unknown keys and tags without their @
  rejected; an explicit --config is a preset anchored at the cwd.
* tests: one fixture case per rule through the binary, plus unit
  tests per module.

* feat(compact-lint): add the fix command

Adds fix, which rewrites doc comments so a following check is clean
for every rule it covers and a second fix is a no-op. Detection now
yields a structured Issue that check renders as a Finding and fix
renders as an Edit, so the two subcommands cannot disagree.

* fix: doc skeletons above undocumented declarations, missing tags in
  config order (a missing @description adopts prose that opens the
  body), the constraints placeholder after the description block,
  tag renames from the new [tags] rename map, and @module name
  repairs. Edits on one comment merge into a single replacement;
  files are rewritten atomically with their line ending and
  permissions kept.
* target: config and path resolution shared by check and fix.
* config: [fix] placeholder and [tags] rename, both validated.
* tests: one before/after fixture per rule through the binary, run
  on a temp copy and followed by check and a second fix.

* feat(compact-lint): add the fill-constraints command

Adds fill-constraints, which measures every circuit that already
carries the constraints tag and writes k and rows into it. The values
exist only on the compiler terminal output, so each measurement
source compiles once under a pty and the progress lines are parsed.
A library module is measured through the mock contract that exports
its circuit names; presets compile themselves.

* measure: portable-pty compile, escape and redraw cleanup, proof
  filter from contract-info.json, and the .circuit-info.json cache
  in the shape the TypeScript builder writes so both tools share it.
* source: overrides, then self globs, then mock templates.
* fill: rewrite only the tag value; unmeasured circuits stay as they
  are and exit 1; --no-compile reads the cache; --dry-run writes
  nothing, the cache included.
* tests: a fake compact script drives the pty path in CI; a captured
  transcript pins the parser.

* test(compact-lint): track the seeded cache fixture

The root .gitignore drops every .circuit-info.json, so the cache the
fill-no-compile case reads never reached CI and the test failed there.

* build(compact-lint): ship prebuilt binaries through npm

Adds the @openzeppelin/compact-lint npm package, a Node bin that
fetches the prebuilt compact-lint binary for the host from the GitHub
release of the same version, verifies it against checksums.txt, caches
it inside the package, and passes arguments and exit codes through.
COMPACT_LINT_BINARY skips the download for source builds and
air-gapped CI.

* release.yml: compact-lint bumps package.json and the crate version
  together and refreshes Cargo.lock.
* release-publish.yml: detection becomes its own job; a four-runner
  matrix builds the Linux and macOS binaries and the publish job
  creates the GitHub release with the assets before npm publish, so
  the package never points at a release that is not there yet.
* Cargo.toml: stripped, thin-LTO release profile (3.3 MiB binary).
* tests: target mapping, checksum verification, the download path
  against a local server, pass-through, and a guard that the npm and
  crate versions agree.

* build(compact-linter): name the npm package compact-linter

The published packages are compact-builder, compact-cli,
compact-deployer and compact-simulator, so the wrapper follows the
same shape as @openzeppelin/compact-linter under packages/linter,
with a compact-linter bin and a compact-linter/v<version> release
tag. The crate, its binary and the release asset names stay
compact-lint.

* build(compact-linter): finish the compact-linter rename

Carries the content half of the rename: manifest name and bin,
release tag path, stderr prefix, workflows, docs and the lockfile.
The previous commit only moved the directory.

* feat(compact-lint): render biome-style diagnostics

The one-line `path:line:col: rule: message` output is replaced by a
Biome-shaped block per diagnostic: header with the rule name and a
FIXABLE / FIXED badge, the message under a level glyph, a code frame
with the span underlined, one advice line, and the fix as a line diff.

* Levels: every rule reports at error, warn, info or off, set in a
  `[rules]` table. Placeholders and unmeasured circuits default to
  warn so they no longer fail a run; `--strict` promotes placeholders.
  Exit 1 needs an error, or a warning with `--error-on-warnings`.
* Reporters: `default`, `concise` (one line per diagnostic) and
  `github` (workflow commands, escaped per the spec). Diagnostics go
  to stdout; the truncation notice and the `Checked N files in T.`
  summary go to stderr. `--max-diagnostics` caps what is shown at 20.
* fix and fill-constraints render through the same reporter, with
  Safe / Unsafe fix titles and an Applied fix title after a write.

* refactor(compact-lint): read the [lint] table of compact.toml

One project, one config file. compact-deploy already owns
`compact.toml`, so the linter moves its settings under a `[lint]`
table there and `compact-lint.toml` goes away before anything ships.

* The linter parses the whole document but deserialises only `lint`;
  every other table is another tool's and is ignored. A file with no
  `[lint]` table is a config error, no file at all keeps the built-in
  defaults.
* The `version` key is dropped: tables are namespaced per tool and the
  deployer's file has none either.
* A deployer test pins that its loader strips the `[lint]` table, so
  the two tools keep sharing the file without a schema change.

* feat(compact-lint): lint doc sections against a template

Module headers in compact-contracts are a sequence of named sections
(`@notice Privacy:`, `@dev Performance:`, …). A bare `@notice` entry
cannot tell them apart, so a config entry may now carry a heading.

* `kinds.<kind>.tags` entries read `@tag` or `@tag Heading`; a headed
  entry matches only the occurrence whose value opens `Heading:`.
  `kinds.<kind>.sections` lists every allowed section in template
  order and, when set, is the order `tags` entries must also appear in.
* `unknown-section` (warn) reports a heading the template does not
  list, gated per tag so free-form tags stay untouched. `tag-order`
  (error) reports the first block out of template order; its fix
  reorders the listed blocks and leaves unlisted ones in their slots.
* `fix` inserts a missing section as `@tag Heading:` plus a placeholder
  line, after its nearest present predecessor in the order.
* The linter ships no section list. The example config carries a
  starting point for compact-contracts.

* feat(compact-lint): add --timings phase breakdown

A run on 39 files takes about 3 s, and nothing in the output said that
97% of it is the `compact format --check` subprocess. `--timings`
prints a per-phase wall-clock table on stderr after the summary,
longest phase first with a detail column naming what it worked on, so
a slow run points at its own cause.

Phases are recorded unconditionally and printed only under the flag.
The total is the sum of the phases, not the run's wall clock.

* feat(compact-lint): read measurements from the artifact dir

The builder now writes `<artifacts>/<Contract>/circuit-info.json`
beside the compiler's own output instead of a hidden per-directory
sidecar in the source tree. `fill-constraints` follows: `--no-compile`
reads that file, and the linter's own compiles write it to the same
place, so a full ZK `yarn compile` in CI is all the fill step needs.

* `[lint.constraints] artifacts` names the tree, relative to
  compact.toml; `--artifacts` overrides it. The temp-dir default is
  gone, compiler output is kept where the builder keeps it.
* Lookup is `<artifacts>/<Stem>/` first, then a walk for a hierarchical
  tree; two hits for one stem is an error.
* `.gitignore` drops the sidecar block; the fixture moves under
  `artifacts/` with an exception for the test tree.

* ci(rust): stop persisting checkout credentials

The default checkout leaves the job's GITHUB_TOKEN in
.git/config, so any later step or build script in the job can
read and reuse it. Nothing in this workflow talks to the remote
after checkout, so opt out.

* docs(compact-tree-sitter): correct the name field claim

Both the grammar header and the README said every declaration
node carries a `name` field. Four do not, and a consumer that
reads `name` unconditionally gets nothing back for them.

* test(compact-tree-sitter): skip symlinks in the corpus walk

A symlinked directory inside the corpus makes the recursion
loop, and a symlinked file is walked twice. Skip both.

* fix(compact-lint): resolve explicit paths against cwd

Discovery matches exclude globs against paths relative to the
config's directory, but an explicit CLI path stayed relative to
the process cwd. Running `check archive` from a subdirectory
produced `archive/X.compact`, which never matched an exclude
written as `contracts/archive/**`, so excluded files were
silently linted. Anchor relative CLI paths at cwd first; the
display step still strips cwd, so the report is unchanged.

* refactor(compact-lint): mark Tag::new must_use

A constructor with no side effects; matches the rest of Tag.

* fix(compact-lint): check constraints under docs = none

The constraints rule ran after the per-kind docs gate, so
kinds.circuit.docs = "none" silently disabled it. The rule is
fixed rather than configurable, so it now runs before the gate;
only the required-tag loop stays behind it.

* fix(compact-lint): skip inserting a tag a rename supplies

A config that forbids @return, renames it to @returns and
requires @returns produced both a rename edit and an insert
edit on the same doc comment, so fix left the comment with
@returns twice. Drop the insert when a rename in that comment
already yields the missing tag.

* fix(compact-lint): validate the fix placeholder

The placeholder is written onto a `*` line of a generated doc
comment. An empty one produced a blank tag line, a multi-line
one broke the comment layout, and one containing `*/` closed
the comment early and corrupted the source. Reject all three at
load time instead.

* fix(compact-lint): validate rename against forbid

A rename only fires from a forbidden-tag finding, so a key that
tags.forbid does not list is dead config the author expects to
work. A value that tags.forbid does list makes fix rewrite one
finding into another, so a second run reports the replacement.
Reject both at load time.

* fix(compact-lint): write through a unique temp file

The staging file was `<name>.compact.tmp` beside the source and
written with fs::write, so a pre-existing file of that name was
truncated, and the predictable name let anything else with write
access to the directory plant one. Create a sibling
`.<name>.<pid>.<nanos>.tmp` exclusively instead, write through
the handle, and remove it when a later step fails.

* docs(compact-lint): tag output fences as text

Bare fences trip markdownlint MD040 and give the renderer
nothing to go on.

* fix(compact-lint): keep leading parent components

normalize popped on every `..`, so a parent-relative
constraints template or CLI path lost its leading `..` and
first_existing probed a path under the working directory
instead of beside it. Only cancel a `..` that has a real
component to cancel.

* docs(compact-lint): tag output fences as text

Bare fences trip markdownlint MD040 and give the renderer
nothing to go on.

* fix(compact-lint): keep section entries out of the rename skip

A rename writes a bare tag, so it cannot supply a headed entry
such as `@notice Security`; skipping the insert left the section
missing and a second check still reported it.

* feat(compact-lint): add the check command

Adds the compact-lint CLI with one subcommand, check, that enforces
per-declaration-kind doc-comment templates from compact-lint.toml and
optionally runs compact format --check. Findings print one per line
as path:line:col: rule: message on stdout; exit 1 on findings, 2 on
any error. fix and fill-constraints come later and only add tables
to the same toml.

* doc: tags parsed into an ordered list with line and column, so a
  finding points at the @ of the offending tag.
* rules: missing-doc, missing-tag, forbidden-tag, module-name,
  missing-constraints, constraints-format, constraints-placeholder
  (--strict), parse, format. Constraints apply to exported non-pure
  circuits only.
* config: every field optional, unknown keys and tags without their @
  rejected; an explicit --config is a preset anchored at the cwd.
* tests: one fixture case per rule through the binary, plus unit
  tests per module.

* fix(compact-lint): resolve explicit paths against cwd

Discovery matches exclude globs against paths relative to the
config's directory, but an explicit CLI path stayed relative to
the process cwd. Running `check archive` from a subdirectory
produced `archive/X.compact`, which never matched an exclude
written as `contracts/archive/**`, so excluded files were
silently linted. Anchor relative CLI paths at cwd first; the
display step still strips cwd, so the report is unchanged.

* refactor(compact-lint): mark Tag::new must_use

A constructor with no side effects; matches the rest of Tag.

* fix(compact-lint): check constraints under docs = none

The constraints rule ran after the per-kind docs gate, so
kinds.circuit.docs = "none" silently disabled it. The rule is
fixed rather than configurable, so it now runs before the gate;
only the required-tag loop stays behind it.

* fix(compact-lint): keep the closing */ on a module-name fix

set_module_name replaced the first word after @module, which
swallowed a `*/` sharing that word or standing alone after the tag,
so the comment ran on and turned the module into comment text.
Split the terminator off before the rewrite. As a backstop, fix
reparses the rewritten text and refuses to write when its
declarations change.

* fix(compact-lint): move delimiter-line text before inserting

Tag and prose searches covered only the lines between `/**` and
`*/`, so a tag or prose sharing either delimiter line was missed: an
insertion split a tag from its continuation and opening prose was
never adopted. Before any insertion, move that text onto a body line
of its own, as the one-liner expansion already did.

* fix(compact-lint): write the constraints tag only once

A rename to the constraints tag still let missing-constraints insert
a `k=?, rows=?` line above the renamed one, and that placeholder hid
the measured value. Listing the constraints tag in kinds.circuit.tags
duplicated it the same way, through the skeleton and through
missing-tag. Skip those inserts when another edit on the same
comment already writes the tag.

* fix(compact-lint): keep a note when k/rows match

fill-constraints compared the whole first line, so a current value with
a note such as `(zkir-v3)` read as stale and was rewritten without it.
Compare only the k/rows part; a changed value still drops the note.

* docs(compact-lint): drop the shared-cache claim

Since #191 the builder writes circuit-info.json into the artifact
directory, so the `.circuit-info.json` beside a source is compact-lint's
own cache.

* fix(compact-lint): keep edits saved during a fill

fill-constraints read every source before compiling and wrote the old
text back afterwards, so a change saved during a compile was lost. Each
file is now read again before the first write, and a changed one stops
the run with nothing written.

* fix(compact-lint): measure under NO_COLOR

Compiler 0.34.0 prints no progress lines when NO_COLOR is set, so every
circuit read as unmeasured and the empty list replaced the cache entry.
The compiler no longer inherits NO_COLOR, and a compile that proves a
circuit without printing its measurement is an error that leaves the
cache alone.

* refactor(compact-lint): share one path normalize

* fix(compact-lint): measure up to 500 circuits per compile

The compiler prints only as many circuit lines as the pty has rows. At
60 rows a larger contract lost lines, which now fails the compile.

* fix(compact-linter): cache the binary per user

The binary was cached under `.cache/` inside the installed package,
which is read-only under Yarn Plug'n'Play and in global or container
installs, so the first run failed with EROFS or EACCES. It now goes to
`$XDG_CACHE_HOME` or `~/.cache` on Linux and `~/Library/Caches` on
macOS.

* fix(compact-linter): never replace published release assets

A manual re-run from a later commit could rebuild the binaries and
--clobber them, with checksums.txt, onto the old tag's release. New
installs then verified the replaced binary against the replaced
checksums.

* The detect job fails when the version's tag names another commit,
  and every job checks out the commit detect checked.
* An existing release keeps its assets; the re-run ships its
  checksums.txt instead of uploading.
* The npm package carries checksums.txt, and the launcher verifies
  downloads against it, never the release's copy.

* fix(compact-linter): reject musl hosts

Node reports linux on musl systems such as Alpine, so the launcher
downloaded a glibc binary that cannot start there. A musl host now
fails with a message pointing at a source build and
COMPACT_LINT_BINARY.

* ci(compact-linter): keep the binary build token-free

* docs: describe the release dependency graph

* ci(compact-linter): check the commit after checkout

CodeQL reads a checkout of another job's output as untrusted code.
Check out the dispatched ref as before, and fail when it is not the
commit the detect job checked.

* fix(compact-lint): insert a section below every paragraph

An inserted tag or section landed after the first paragraph of the
block before it, so the later paragraphs of a multi-paragraph
@description moved under the new section. Insertion now anchors on
the last non-blank line before the next tag. The constraints line
keeps its first-paragraph anchor.

* fix(compact-lint): move delimiter text before a reorder

The tag-order fix permuted only the body lines, so text on the /** or
*/ line stayed put while the blocks around it moved, landing a
statement under another section. A reorder now moves that text onto
its own body line first, as an insertion already does.

An edit that leaves the text unchanged is no longer reported or
counted as a fix.

* fix(compact-lint): compile a fill dry run into a temp dir

A dry run compiled into the configured artifacts tree, so a preview
replaced the builder's compiler output for each contract it measured.
It now compiles into a temporary directory removed after each
compile; --no-compile still reads the configured tree. The fill
tests compare the whole tree after a dry run.

* fix(compact-lint): take the fill exit code from rule levels

fill-constraints exited 1 for any unmeasured circuit at every level
but off, unlike check and fix. In compact-contracts the module
initialize circuits cannot be measured, so a CI step running it failed
every time. The exit code now follows the diagnostic levels and
--error-on-warnings.

* docs(compact-lint): drop the kept-artifact claim

compactc replaces a contract's output directory when it compiles, so
a compile that prints no measurement cannot promise the old artifact
survives. What holds is that no circuit-info.json is written.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants