Mega-refactor #15

0xpantera · 2025-07-01T18:22:55Z

bargo v0.2.0 — Mega-refactor PR (Phases 1 → 7)

Highlights

Phase	Key deliverable
1 – Helper dedup	Removed duplicated `handle_*` helpers; global flags now reach every command.
2 – Command execution unify	`run_nargo_command` helper + smoke tests; build is `-Dwarnings` clean.
3 – Backend trait & auto-declare	`Backend` + polymorphic dispatch; stateful back-ends; Cairo deploy auto-declares.
4 – Runner abstraction	`CmdSpec` + `Runner`; `DryRunRunner` with command history & fake outputs.
5 – Util slice	Split `util/` into `io`, `log`, `format`, `timer`; added `cmd_spec!` macro.
6 – Rich error context	`eyre::WrapErr` on every external boundary; `CairoError` / `EvmError` enums.
7 – Integration tests & goldens	Fixture Noir circuit, golden snapshots, DryRunRunner workflows.

What’s new

Polymorphic back-ends (CairoBackend, EvmBackend) replace match ladders.
Auto-declare on Cairo deploy with --auto-declare / --no-declare.
Universal dry-run: every external tool funnels through Runner; history plus stubbed output.
Structured utilities: IO helpers, coloured log helpers, neat format helpers, accurate timers.
Helpful errors: breadcrumb context and backend-specific enums.
Robust CI & tests: 92 total tests, golden-file checks, race-free parallel execution.
Docs: module-level rustdoc, expanded README (testing, errors), CHANGELOG fully up to date.

Developer impact

// one-liner tool call
run_tool(cfg, "bb", &["prove", "--scheme", "ultra_honk"]);

// concise CmdSpec
let spec = cmd_spec!("forge", ["create", "Verifier.sol"], cwd = "./contracts");

// mock runner in tests
let cfg = Config::test_with_runner(Arc::new(DryRunRunner::default()));

Error chains now show context, for example:

Error: could not read ./target/bb/<pkg>.json
    at cairo::bb_operations::generate_starknet_proof
    Caused by: No such file or directory (os error 2)

Verification

cargo check --workspace --all-targets --all-features -Dwarnings → clean
cargo test → 92 tests green
cargo doc --workspace --no-deps -q → no warnings
No unsafe code added
Dry‑run output unchanged for all commands

Review tips

Core files – src/runner.rs, src/backend.rs, everything in util/.
Commits are prefixed with their phase (phase‑4, phase‑6, …) to ease review.
Golden snapshots live in tests/goldens/; refresh them with
UPDATE_GOLDENS=1 cargo test.

The module now has a shared run_nargo_command helper that consolidates argument building, logging, and dry-run handling. This avoids duplicating command execution logic across command modules.

The new tests verify the behavior of --dry-run, --verbose and --pkg flags across various commands including check, clean, rebuild, cairo gen and evm gen.

The changes introduce a new Backend trait that provides a common interface for Cairo and EVM proof system implementations, along with a factory pattern for creating backend instances. Command dispatching is updated to use this new abstraction.

The commit adds downcasting support via `as_any_mut()` to the Backend trait and changes all Backend trait methods to take `&mut self`. This enables safe downcasting to concrete backend types and allows backends to maintain internal state.

The changes add automatic contract declaration capability to the Cairo deploy command, while deprecating the standalone 'declare' command in favor of this integrated approach.

Adds command execution abstraction with Runner trait and implements auto-declare behavior for Cairo deploy. Includes comprehensive test coverage and documentation for the new functionality. Deprecates the separate Cairo declare command in favor of integrated auto-declare.

The changes simplify backend configuration and improve the deployment flow by: - Replacing individual backend setters with a unified configure() method - Moving declare functionality to be internal-only - Updating user-facing messages to promote auto-declare

The commit verifies deployment output differences between auto-declare and no-declare modes through integration tests, ensuring the feature works as expected.

The commit migrates all bb command executions to use the centralized command runner abstraction, providing consistent handling of dry-run mode and logging across the codebase. The main changes: - Add run_bb_command helper in common.rs for standardized bb execution - Update all bb operations to take Config and use the runner - Remove redundant dry-run message printing - Add TODO noting bb backend can be removed in next checkpoint

The commit moves command execution to a runner abstraction providing consistent dry-run handling, logging, and testability. Legacy direct execution functions have been removed from bb, foundry, garaga, and nargo backend modules.

The added configuration parameter allows for dry-run mode and runner abstraction in Garaga functions, consistent with other commands.

The changes migrate various command executions (nargo, garaga, foundry) to use a common runner abstraction, removing direct backend calls in favor of a more unified approach to command execution.

The change removes a redundant forge command execution function in favor of a more general tool runner interface.

This commit removes the direct garaga command execution backend in favor of the unified runner-based approach. All garaga functionality is now handled through the common command runner interface for better testing and consistency.

The changes consolidate all external tool execution into two main functions: run_tool() for standard execution and run_tool_capture() for capturing stdout. This replaces the previous tool-specific helper functions which are now deprecated.

The commit adds command history tracking to DryRunRunner and unifies external command execution through a new run_tool() interface. This makes it easier to test command execution flows by inspecting the recorded command history rather than parsing stdout.

This extends the dry run runner to generate tool-specific fake outputs for testing and store captured outputs in command history.

This commit restructures utility code into more focused modules: - Move common I/O operations into new `io.rs` module - Create dedicated `format.rs` module for text formatting - Rename `output.rs` to `log.rs` for logging utilities - Add documentation and examples for each module - Add unit tests for new functionality The changes improve code organization and make the utilities more maintainable without changing their behavior.

Adds improved error handling for file operations and introduces a dedicated error module for the Cairo backend with structured error types.

The commit adds more descriptive error context using color_eyre's WrapErr trait throughout the codebase. This helps with debugging by providing better error messages that include file paths and operation details when failures occur.

test structure with fixture-based workflow testing - Use golden file snapshots to verify build artifacts and output - Ensure thread-safety with ScopedDir guards for parallel tests - Implement DryRunRunner for command execution verification - Add comprehensive test coverage documentation

0xpantera added 30 commits June 24, 2025 23:01

refactor: split into core crate

86422b2

phase-2: cleanup helpers, dedup enum, clippy green

869a533

Extract nargo command execution into common helper

9e78d33

The module now has a shared run_nargo_command helper that consolidates argument building, logging, and dry-run handling. This avoids duplicating command execution logic across command modules.

Add smoke tests for CLI commands with dry-run flag

b268e04

The new tests verify the behavior of --dry-run, --verbose and --pkg flags across various commands including check, clean, rebuild, cairo gen and evm gen.

Add CHANGELOG.md detailing changes

5e8ff96

Add comprehensive test coverage for backend trait system

1b1bcd4

Add Cairo backend implementation for Starknet proofs

08d31be

Add EVM backend implementation and trait bindings

f827d14

Add auto-declare feature to Cairo deploy command

62a497a

The changes add automatic contract declaration capability to the Cairo deploy command, while deprecating the standalone 'declare' command in favor of this integrated approach.

Remove Cairo declare command and refactor deploy config

0c173d2

Add integration test for auto-declare vs no-declare output

0139a61

The commit verifies deployment output differences between auto-declare and no-declare modes through integration tests, ensuring the feature works as expected.

Remove direct command execution in backend modules

16c34f9

The commit moves command execution to a runner abstraction providing consistent dry-run handling, logging, and testability. Legacy direct execution functions have been removed from bb, foundry, garaga, and nargo backend modules.

Add Config param to Garaga command functions

73051b7

The added configuration parameter allows for dry-run mode and runner abstraction in Garaga functions, consistent with other commands.

Add foundry commands to runner abstraction

d8b1993

Consolidate command execution through runner abstraction

2ae3d21

The changes migrate various command executions (nargo, garaga, foundry) to use a common runner abstraction, removing direct backend calls in favor of a more unified approach to command execution.

Remove foundry backend run with output function

4e3f821

The change removes a redundant forge command execution function in favor of a more general tool runner interface.

Remove old garaga backend implementation

fe1448c

This commit removes the direct garaga command execution backend in favor of the unified runner-based approach. All garaga functionality is now handled through the common command runner interface for better testing and consistency.

Add serde_json dependency

b87936f

Enhance DryRunRunner with realistic test outputs

3e1c79e

This extends the dry run runner to generate tool-specific fake outputs for testing and store captured outputs in command history.

Add thiserror dependency

cbbbe56

Add comprehensive error handling docs and tests

554e014

Add error handling and error types for Cairo backend

34b106f

Adds improved error handling for file operations and introduces a dedicated error module for the Cairo backend with structured error types.

0xpantera added 4 commits July 1, 2025 18:50

Add error handling and dedicated EVM error types

941efe9

Improve error messages with WrapErr

52d9964

The commit adds more descriptive error context using color_eyre's WrapErr trait throughout the codebase. This helps with debugging by providing better error messages that include file paths and operation details when failures occur.

Add assert_fs and path-slash dependencies

0518b56

0xpantera self-assigned this Jul 1, 2025

0xpantera force-pushed the refactor-staging branch 3 times, most recently from 80573f2 to 68ced07 Compare July 1, 2025 20:10

Release version 0.2.0

8b47c42

0xpantera force-pushed the refactor-staging branch from 68ced07 to 8b47c42 Compare July 1, 2025 20:15

0xpantera marked this pull request as ready for review July 1, 2025 20:16

0xpantera merged commit c0f11f8 into main Jul 1, 2025
0 of 2 checks passed

0xpantera deleted the refactor-staging branch July 1, 2025 20:16

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Mega-refactor #15

Mega-refactor #15

Uh oh!

0xpantera commented Jul 1, 2025

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Mega-refactor #15

Mega-refactor #15

Uh oh!

Conversation

0xpantera commented Jul 1, 2025

bargo v0.2.0 — Mega-refactor PR (Phases 1 → 7)

Highlights

What’s new

Developer impact

Verification

Review tips

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants