# How to Format and Lint Rust Code in the Macro Repository

> Learn to format and lint Rust code in the macro repository using just check. This command streamlines cargo fmt and cargo clippy checks for changed files.

- Repository: [Macro/macro](https://github.com/macro-inc/macro)
- Tags: how-to-guide
- Published: 2026-08-21

---

**To format and lint Rust code in the Macro repository, run `just check`, which wraps `cargo fmt` and `cargo clippy` into a single gate that validates only changed files by default.**

The `macro-inc/macro` codebase relies on the `just` command runner to standardize code quality workflows across all contributions. Maintaining consistent formatting and strict linting is enforced through unified check gates that wrap Rust's native tooling. This guide explains how to format and lint Rust code in Macro using the project's `justfile` recipes and underlying Cargo commands.

## The `just check` Command Gate

The primary entry point for Rust code quality is the `just check` recipe defined in the repository's `justfile`. According to [`docs/STYLE_GUIDE.md`](https://github.com/macro-inc/macro/blob/main/docs/STYLE_GUIDE.md), this command serves as the single gate for both formatting and linting, printing violations as `file:line [rule-id]` and displaying the exact commands required to fix each issue.

### Fast Check for Changed Files

By default, `just check` performs a differential analysis against `origin/main`, targeting only files modified in your current branch. This provides rapid feedback during iterative development:

```bash
just check

```

### Full Workspace Validation

To validate the entire workspace—including TypeScript files and all Rust crates—use the full target:

```bash
just check full

```

## Formatting Rust Code in Macro

Formatting is handled by **rustfmt** invoked through `cargo fmt`. The repository provides the explicit shortcut `just fmt`, which calls the formatter with the exact flags defined in the `justfile`.

For manual execution outside the just wrapper:

```bash
cargo fmt          # Format workspace members

cargo fmt --all    # Format every crate including path dependencies

```

The [`rust-toolchain.toml`](https://github.com/macro-inc/macro/blob/main/rust-toolchain.toml) file at the repository root pins the exact Rust toolchain version, including `rustfmt`, ensuring deterministic formatting results across all contributor environments and CI pipelines.

## Linting with Clippy

Linting is performed by **Clippy** via `cargo clippy`. The `just clippy` recipe provides the standardized invocation used in continuous integration, which treats warnings as errors.

Direct command-line invocation:

```bash
cargo clippy --workspace -- -D warnings

```

The [`docs/STYLE_GUIDE.md`](https://github.com/macro-inc/macro/blob/main/docs/STYLE_GUIDE.md) references **rule CS-41**, which discourages ad-hoc `#[allow(...)]` annotations in favor of `#[expect(...)]` to document intentional lint deviations.

## CI Enforcement

The GitHub Actions workflow defined in [`.github/workflows/code_check_conventions.yml`](https://github.com/macro-inc/macro/blob/main/.github/workflows/code_check_conventions.yml) executes `just check` on every pull request. This ensures that no code reaches the main branch without passing both formatting and clippy validation, preventing style regressions from entering the codebase.

## Summary

- The `macro-inc/macro` repository uses `just check` as the single gate for formatting and linting Rust code.
- Run `just check` for fast differential checks against `origin/main`, or `just check full` for complete workspace validation.
- Underlying tools are `cargo fmt` (accessible via `just fmt`) and `cargo clippy` (accessible via `just clippy`).
- The [`rust-toolchain.toml`](https://github.com/macro-inc/macro/blob/main/rust-toolchain.toml) file pins the exact formatter version for reproducible results across environments.
- CI enforces these checks via [`.github/workflows/code_check_conventions.yml`](https://github.com/macro-inc/macro/blob/main/.github/workflows/code_check_conventions.yml).

## Frequently Asked Questions

### What is the difference between `just check` and `just check full`?

`just check` analyzes only files changed compared to `origin/main`, providing rapid feedback during development. `just check full` validates the entire workspace including TypeScript files and is recommended before final submission or when preparing a pull request for review.

### Can I run formatting or linting separately without `just check`?

Yes. Use `just fmt` to run `cargo fmt` only, or `just clippy` to run `cargo clippy` only. These shortcuts respect the repository's `justfile` configuration and use the same flags as the unified check gate, ensuring consistency with CI.

### How does Macro ensure consistent formatting across different machines?

The repository includes a [`rust-toolchain.toml`](https://github.com/macro-inc/macro/blob/main/rust-toolchain.toml) file that pins the exact Rust toolchain version, including `rustfmt`. This ensures all contributors and CI pipelines use identical formatting rules, preventing style drift between development environments.

### Why does the STYLE_GUIDE prefer `#[expect(...)]` over `#[allow(...)]`?

According to [`docs/STYLE_GUIDE.md`](https://github.com/macro-inc/macro/blob/main/docs/STYLE_GUIDE.md) rule CS-41, `#[expect(...)]` is preferred because it explicitly denotes that a lint violation is expected and documented. This approach discourages suppressing warnings without acknowledging the intentional deviation, whereas `#[allow(...)]` can hide issues silently.