[0xisk]

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:

• The old sidecar merged every contract in a directory into one hidden file keyed by file name, so a reader had to know the mock naming scheme to find its entry. One file per contract with a source field removes that.
• The published API of @openzeppelin/compact-builder is unchanged: index.ts never re-exported the circuit-info helpers. The rename is module-internal.
• The only consumer of the old file is compact-lint fill-constraints --no-compile on the open lint stack; feat(compact-lint): biome output, compact.toml, sections, timings, artifacts #189 carries the matching reader change. compact-contracts has no reader and can drop .circuit-info.json from its .gitignore once this ships.
• .gitignore here loses the .circuit-info.json block; feat(compact-lint): add the fill-constraints command #185/feat(compact-lint): biome output, compact.toml, sections, timings, artifacts #189 touch the same lines, so whichever lands second takes a one-line conflict.

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.

[coderabbitai]

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.}