Repository navigation
build(compact-linter): ship prebuilt binaries through npm - #186
Conversation
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.
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.
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.
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.
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.
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.
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.
|
Important Review skippedAuto incremental reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the
|
| Layer / File(s) | Summary |
|---|---|
Package and binary resolution packages/linter/*, crates/compact-lint/README.md, Cargo.toml, .gitignore |
Adds the npm package, CLI wrapper, platform target mapping, checksum verification, caching, download handling, release settings, and installation documentation. |
Validation coverage packages/linter/test/*, packages/linter/vitest.config.ts |
Tests target mapping, checksum parsing, overrides, downloads, caching, errors, argument forwarding, exit codes, and npm-to-Cargo version matching. |
Release automation
| Layer / File(s) | Summary |
|---|---|
Synchronized versioning .github/workflows/release.yml |
Adds compact-linter release selection, Rust setup, Cargo version synchronization, validation, and a combined npm/Cargo commit. |
Native binary publishing .github/workflows/release-publish.yml |
Adds package detection outputs, four-target binary builds, smoke tests, artifact handling, checksum generation, GitHub release creation, and npm publishing. |
Release documentation README.md, RELEASING.md |
Documents package installation, Node.js requirements, release ordering, binary assets, version synchronization, release notes, and publishing setup. |
Estimated code review effort: 4 (Complex) | ~60 minutes
Change: Feature
Sequence Diagram(s)
sequenceDiagram
participant User
participant compactLinter
participant BinaryResolver
participant ReleaseAssets
participant NativeBinary
User->>compactLinter: run compact-linter arguments
compactLinter->>BinaryResolver: resolve version and host target
BinaryResolver->>ReleaseAssets: fetch binary and checksum manifest
ReleaseAssets-->>BinaryResolver: return release assets
BinaryResolver->>NativeBinary: verify, cache, and execute binary
NativeBinary-->>User: return output and exit status
Merge Risk: 
High · previous review cc81e
-
Common installation environments can fail at runtime, while the release workflow can expose credentials or publish artifacts inconsistent with their source tag. These issues should be fixed before merge.
Pre-merge checks: 
4
-
Full details: Title check
-
Explanation
The title uses the conventional commit form and names the scope
compact-linter. It states the main change: prebuilt native binaries are shipped through npm. The raw summary confirms the npm wrapper downloads host-specificcompact-lintbinaries from GitHub releases with checksum verification, and the release workflow builds and uploads those binaries. The title is specific and matches the changeset. It does not cover the rename, versioning, or docs, which is acceptable.
-
Finishing Touches
-
🧪 Generate unit tests (beta)
-
- Create PR with unit tests
- Commit unit tests in branch
build/compact-lint-release
-
- Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.
A rabbit checked the checksum bright
And cached the linter overnight
Four little targets crossed the sky
Rust and npm versions now comply
The release drums began to play
And compact-linter hopped away
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.
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.
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.
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.
A symlinked directory inside the corpus makes the recursion loop, and a symlinked file is walked twice. Skip both.
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.
A constructor with no side effects; matches the rest of Tag.
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.
# Conflicts: # crates/compact-lint/src/check.rs # crates/compact-lint/src/rules.rs
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.
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.
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.
…traints # Conflicts: # crates/compact-lint/src/config.rs # crates/compact-lint/src/fix.rs
A constructor with no side effects; matches the rest of Tag.
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.
Main carries #182 squashed, including its last three review fixes. Kept this branch's Issue/target split and ported them onto it: * normalize explicit paths in target.rs * accept a note after the rows count * report an undocumented circuit under docs = none as missing-constraints; fix inserts a doc comment holding only the constraints line
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.
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.
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.
# Conflicts: # Cargo.lock # crates/compact-lint/README.md # crates/compact-lint/src/config.rs # crates/compact-lint/src/edit.rs # crates/compact-lint/src/fix.rs # crates/compact-lint/src/lib.rs # crates/compact-lint/src/main.rs # crates/compact-lint/src/rules.rs # crates/compact-lint/src/target.rs
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.
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.
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.
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.
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.
# Conflicts: # crates/compact-lint/README.md
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.
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.
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.
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.
Types of changes
No linked issue. Last PR of the
compact-lintstack: how the binary reaches users. After this, two PRs in compact-contracts wirecheckintochecks.ymlandfill-constraintsintoprepare-release.yml.Not visible in the diff:
@openzeppelin/compact-linterunderpackages/linter, matching the other four package names; the crate, binary and release assets keep thecompact-lintname. The rename is the second and third commit; squash on merge.compact-linter/v<version>on first run, verifies it against thechecksums.txtpublished inside the npm package, and caches it per user. Install stays offline-safe and--ignore-scriptssafe because nothing runs at install time.COMPACT_LINT_BINARYbypasses the download.npm publish. For the other four packages, detection moved into its owndetectjob, which the binary matrix and the publish both read. Detection and the binary build therefore run before thecompact-npm-prodapproval; the tag, the release and the npm publish stay behind it. A re-run of any package now fails when the version's tag names another commit.x86_64-unknown-linux-gnuleg was built here. Theubuntu-24.04-arm,macos-15-intelandmacos-15legs, and thealways()gate onpublish, are exercised the first time the workflow runs.@openzeppelin/compact-lintertakes theNPM_TOKENpath; register it as an npm Trusted Publisher right after. RELEASING.md says how.casestatements into a script. This PR adds one arm to each, so whichever lands second re-applies three lines.checksums.txtexits 2 and caches nothing.Start with
RELEASING.md(thecompact-lintsection), thenpackages/linter/src/binary.ts, thenrelease-publish.yml.PR Checklist
Summary by CodeRabbit
New Features
@openzeppelin/compact-linter, a Node.js CLI for running the Compact linter without installing Rust.Documentation
Release Improvements