# Project scaffolding

Standards for laying out a Rust project, common to CLIs and servers.
Read `binary.md` or `server.md` for project-type-specific additions
on top of this file.

## Project structure

Single crate with both library and binary targets. All domain logic
lives in the library; the binary is a thin shell.

```
project/
├── Cargo.toml
├── build.rs                # Sets <NAME>_VERSION (→ versioning.md).
├── Cargo.lock              # Committed — it's a binary.
├── justfile
├── .gitignore              # /target
├── .cargo/
│   └── mutants.toml        # Excludes equivalent/unreachable mutations.
├── .github/workflows/
│   ├── ci.yml
│   └── release.yml         # Binaries only — see binary.md.
├── bin/
│   └── coverage            # Coverage gate script (→ coverage.md).
├── src/
│   ├── lib.rs              # Library root — re-exports modules.
│   ├── error.rs            # thiserror + miette::Diagnostic enum.
│   ├── (domain modules)
│   └── bin/<name>/
│       ├── main.rs          # Entrypoint — see binary.md or server.md.
│       └── ...
├── tests/
│   ├── cli.rs              # CLI integration tests via assert_cmd.
│   │                       # (or api.rs for server integration tests)
│   └── property.rs         # Hegeltest property tests (→ property-testing.md).
└── migrations/             # If using a database.
```

## Cargo.toml

```toml
[package]
name = "<name>"
version = "0.1.0"
edition = "2024"

[[bin]]
name = "<name>"
path = "src/bin/<name>/main.rs"

[dependencies]
fs-err = "*"
miette = { version = "*", features = ["fancy"] }
thiserror = "*"
tokio = { version = "*", features = ["full"] }
tracing = "*"
tracing-subscriber = { version = "*", features = ["env-filter"] }

[dev-dependencies]
hegeltest = "*"
tempfile = "*"

[lints.clippy]
self_named_module_files = "warn"
unwrap_used = "warn"
expect_used = "warn"
panic = "warn"
indexing_slicing = "warn"
arithmetic_side_effects = "warn"
```

Project-type-specific deps (`clap` for CLIs, `axum` for servers) go in
`binary.md` / `server.md` and are added on top of this baseline.

Notes on this template:

- `miette` with the `fancy` feature — pretty diagnostic rendering for
  binaries; the library still derives `miette::Diagnostic` so error
  detail survives through tests and library consumers.
- `hegeltest` — property-based testing built on the Hypothesis engine,
  with built-in shrinking.
- `[lints.clippy]` — `self_named_module_files` enforces `foo/mod.rs`
  over `foo.rs` for directory modules (P-MOD in `style.md`). The rest
  are panic-discipline lints: `unwrap`, `expect`, raw `panic!`, slice
  indexing, and unchecked arithmetic are denial-of-service bugs waiting
  for untrusted input. All are lint levels, so they live here rather
  than in `.clippy.toml`. See
  `style.md` "Panic discipline" for rationale and how to opt out at a
  single call site when an invariant is genuinely local.
- A project that's already a multi-crate workspace hoists the block to
  `[workspace.lints.clippy]` in the root manifest. Each member must opt
  in with `[lints] workspace = true`; a member without it gets no lints
  and Cargo won't warn.

Cross-cutting choices (edition, lock file, fs-err, tracing, tokio
features) are explained in `SKILL.md`.

## Error pattern

Template (rationale in `SKILL.md`):

```rust
// src/error.rs
use miette::Diagnostic;

#[derive(Debug, thiserror::Error, Diagnostic)]
pub enum MyError {
    #[error("not found: {0}")]
    #[diagnostic(
        code(myapp::not_found),
        help("check the input identifier and try again"),
    )]
    NotFound(String),

    #[error("io error: {0}")]
    #[diagnostic(code(myapp::io))]
    Io(#[from] std::io::Error),
}
```

## justfile

```just
default: all

fmt:
    cargo fmt --all

check:
    cargo check --workspace

clippy:
    cargo clippy --workspace -- -D warnings

coverage:
    ./bin/coverage

mutants:
    #!/usr/bin/env bash
    set -uo pipefail
    cargo mutants --timeout-multiplier 3 -j4
    rc=$?
    # 0 = all caught, 3 = timeouts (infinite loops from mutants, still caught).
    if [ "$rc" -eq 0 ] || [ "$rc" -eq 3 ]; then
        exit 0
    fi
    exit "$rc"

all: fmt clippy coverage

install:
    cargo install --locked --path .
```

The `coverage` recipe delegates to `bin/coverage` so the logic stays
shellcheck-clean and editable outside the justfile. Copy this skill's
`coverage.sh` reference file to `bin/coverage` in the new project and
give it the executable bit (`chmod +x bin/coverage`). Read
`coverage.sh` for the full source. Key design:

- `bin/coverage` uses a separate `CARGO_TARGET_DIR` — prevents
  instrumented and non-instrumented artifacts from mixing, which causes
  phantom uncovered lines with grcov.
- 100% coverage on library code only — `--keep-only 'src/**'
  --ignore 'src/bin/**'`. Binary code is tested via integration tests
  but not measured.
- `covdir` output — machine-readable JSON, parsed with `jq` for a
  clean summary. Exclusion markers (`cov-excl-line`, etc.) are
  documented in `coverage.md`.
- `mutants` tolerates exit code 3 — `cargo mutants` returns 3 for
  timeouts (infinite loops caused by mutations). These count as
  caught because the mutant broke the program.

## CI workflow

```yaml
# .github/workflows/ci.yml
name: CI

on:
  push:
    branches: [main]
  pull_request:

jobs:
  ci:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@SHA # v4
        with:
          persist-credentials: false
      - run: rustup component add clippy rustfmt llvm-tools
      - run: cargo install grcov cargo-mutants just
      - run: cargo fmt --check
      - run: just clippy coverage
      - run: just mutants
```

Pin all actions to commit SHAs with a version comment (`@<sha> # v4`).
Resolve the SHA for each tag at generation time:

```bash
git ls-remote https://github.com/<owner>/<repo> <tag> | cut -f1
```

`cargo fmt --check` instead of `just fmt` — CI should fail on
unformatted code, not silently fix it.

## Testing

Unit tests live in each module, using `tempfile` for isolation when
state is involved.

Integration tests differ by project type — see `binary.md` or
`server.md` for templates.

Property tests in `tests/property.rs` use hegeltest. See
`property-testing.md`.

Mutation testing via `just mutants` catches code that tests execute
but don't verify. See `mutation-testing.md`.

## Prerequisites

```bash
rustup component add clippy rustfmt llvm-tools
cargo install grcov cargo-mutants just
```