Skip to content

build(compact-linter): ship prebuilt binaries through npm - #186

Merged
0xisk merged 50 commits into
mainfrom
build/compact-lint-release
Nov 17, 2026
Merged

0xisk merged 50 commits into
mainfrom
build/compact-lint-release

Conversation

@0xisk

@0xisk 0xisk commented Sep 15, 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)

No linked issue. Last PR of the compact-lint stack: how the binary reaches users. After this, two PRs in compact-contracts wire check into checks.yml and fill-constraints into prepare-release.yml.

Not visible in the diff:

  • The npm package is @openzeppelin/compact-linter under packages/linter, matching the other four package names; the crate, binary and release assets keep the compact-lint name. The rename is the second and third commit; squash on merge.
  • The npm package is a thin bin, not a bundle. It downloads the host binary from the GitHub release compact-linter/v<version> on first run, verifies it against the checksums.txt published inside the npm package, and caches it per user. Install stays offline-safe and --ignore-scripts safe because nothing runs at install time. COMPACT_LINT_BINARY bypasses the download.
  • The publish workflow now creates the GitHub release itself for this package, with the four assets, before npm publish. For the other four packages, detection moved into its own detect job, which the binary matrix and the publish both read. Detection and the binary build therefore run before the compact-npm-prod approval; 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.
  • Only the x86_64-unknown-linux-gnu leg was built here. The ubuntu-24.04-arm, macos-15-intel and macos-15 legs, and the always() gate on publish, are exercised the first time the workflow runs.
  • The first publish of @openzeppelin/compact-linter takes the NPM_TOKEN path; register it as an npm Trusted Publisher right after. RELEASING.md says how.
  • refactor(release): extract package resolution into a tested script #151 moves the same case statements into a script. This PR adds one arm to each, so whichever lands second re-applies three lines.
  • Verified locally with the packed tarball in a Yarn 4.10.3 Plug'n'Play project, against a local HTTP server standing in for the release: a cold cache downloads and caches, a second run makes no request, and a replaced asset served with a matching replaced checksums.txt exits 2 and caches nothing.

Start with RELEASING.md (the compact-lint section), then packages/linter/src/binary.ts, then release-publish.yml.

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

    • Added @openzeppelin/compact-linter, a Node.js CLI for running the Compact linter without installing Rust.
    • Automatically downloads, verifies, caches, and executes native binaries for supported platforms.
    • Supports custom binary locations and configurable release sources.
    • Provides clear errors for unsupported platforms, download failures, and checksum mismatches.
  • Documentation

    • Added installation, usage, platform, environment-variable, and source-build guidance.
    • Documented the linter in the project overview and changelog.
  • Release Improvements

    • Added automated multi-platform binary publishing with checksums and prerelease support.

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.
@coderabbitai

coderabbitai Bot commented Sep 15, 2026 •

Copy link
Copy Markdown

Review Change StackReview Change Stack

Important

Review skipped

Auto incremental reviews are disabled on this repository.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

Run configuration

  • Source mode: Auto
  • Repository: Unavailable
  • Branch: Unavailable
  • File: No configuration file from this repository applied
  • Commit: Unavailable
  • Layers: Organization UI
  • Review profile: CHILL
  • Plan: Advanced
  • Run ID: 3007a82e-6e81-4550-81ff-a9cd2c939e96

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

  • Trigger review

Walkthrough

The PR adds the @openzeppelin/compact-linter package. It resolves and verifies native binaries, forwards CLI execution, tests the behavior, synchronizes npm and Cargo versions, and automates multi-platform GitHub and npm releases.

Changes

Compact linter package

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
Loading
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: Passed 4

Check name Status Explanation
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.
Title check Passed 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 …
Description Check Passed Check skipped - CodeRabbit’s high-level summary is enabled.
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-specific compact-lint binaries 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.

Share

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

@0xisk
0xisk added this pull request to stack #183 September 15, 2026 09:33
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.
@0xisk 0xisk changed the title build(compact-lint): ship prebuilt binaries through npm build(compact-linter): ship prebuilt binaries through npm Sep 15, 2026
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.
@0xisk
0xisk marked this pull request as ready for review September 15, 2026 10:37
@0xisk
0xisk requested review from a team as code owners September 15, 2026 10:37
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
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.
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
0xisk added 15 commits October 13, 2026 09:16
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.
Base automatically changed from feat/compact-lint-fill-constraints to main November 17, 2026 14:20
# 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.
@0xisk
0xisk enabled stacked auto-merge (squash) November 17, 2026 17:36
@0xisk
0xisk merged commit 5a19f13 into main Nov 17, 2026
11 checks passed
@0xisk
0xisk deleted the build/compact-lint-release branch November 17, 2026 19:06
0xisk added a commit that referenced this pull request Nov 17, 2026
…nostics

Brings in the final #184, #185 and #186 review fixes. The fixtures
they added move to compact.toml, the note fixture reads its seeded
measurement from the artifact dir, and their expectations are
regenerated in the new diagnostic format.
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.

3 participants