diff --git a/.cargo/config.toml b/.cargo/config.toml index 0d27fbe..3cd3665 100644 --- a/.cargo/config.toml +++ b/.cargo/config.toml @@ -3,7 +3,6 @@ check-all = "clippy --all-targets --workspace -- -D warnings" test-all = "test --workspace" cov = "llvm-cov --workspace --ignore-filename-regex main\\.rs --summary-only" -verify = ["fmt --all -- --check", "check-all", "test-all"] # Dogfooding: build the runnable daemon + reference CLI in release mode. build-release = ["build", "--release", "-p", "nunciod", "-p", "nuncio-cli"] # Remove the entire workspace target directory (all crates, all profiles). diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 9316241..b3c72cd 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -2,9 +2,9 @@ name: CI Quality Gates & Build Pipeline on: push: - branches: [ main, dev ] + branches: [ main, dev, rc ] pull_request: - branches: [ main, dev ] + branches: [ main, dev, rc ] env: CARGO_TERM_COLOR: always diff --git a/.idea/runConfigurations/Cargo_Verify.xml b/.idea/runConfigurations/Cargo_Verify.xml deleted file mode 100644 index c457f2c..0000000 --- a/.idea/runConfigurations/Cargo_Verify.xml +++ /dev/null @@ -1,16 +0,0 @@ - - - - diff --git a/CLAUDE.md b/CLAUDE.md index 235d070..7cd5f89 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -60,7 +60,16 @@ Cargo aliases (defined in `.cargo/config.toml`): cargo check-all # = clippy --all-targets --workspace -- -D warnings (the lint gate) cargo test-all # = test --workspace cargo cov # = llvm-cov --workspace --ignore-filename-regex main.rs --summary-only (informational; needs cargo-llvm-cov) -cargo verify # = fmt --all --check + check-all + test-all +``` + +There is no `cargo verify` alias — Cargo aliases are a single command's argv and +cannot chain subcommands. Run the full gate as three separate commands (this is +exactly what the pre-commit hook runs): + +```bash +cargo fmt --all -- --check +cargo check-all +cargo test-all ``` Common commands: @@ -92,7 +101,9 @@ A shared RustRover setup lives in `.idea/` (the useful parts are tracked; - *Run nunciod (daemon)* — start the daemon. - *Run nuncio-cli (system status)* — drive it (start the daemon first). - *Cargo Build Release (daemon + CLI)* — `cargo build-release`. - - *Cargo Check All* · *Cargo Test All* · *Cargo Verify (fmt + clippy + tests)* — the gates. + - *Cargo Check All* · *Cargo Test All* — the gates (run `cargo fmt --all -- --check` + separately; there is no combined run configuration, since Cargo aliases and + RustRover run configurations can't chain subcommands). - *Cargo Coverage* — informational `llvm-cov` (needs `cargo-llvm-cov` installed). - Tip: set Clippy as the external linter (Settings → Rust → External Linters) so the editor mirrors the `-D warnings` gate. diff --git a/README.md b/README.md index 6f51eac..a71f8f4 100644 --- a/README.md +++ b/README.md @@ -52,10 +52,13 @@ repositories (roadmap Phase 5). cargo build --workspace # build everything cargo check-all # clippy, all targets, warnings-as-errors (the gate) cargo test-all # run the whole test suite -cargo verify # fmt --check + check-all + test-all cargo test -p nuncio-store # test a single crate ``` +There is no `cargo verify` alias (Cargo aliases can't chain subcommands). Run the +full local gate as three separate commands — `cargo fmt --all -- --check`, +`cargo check-all`, `cargo test-all` — which is exactly what the pre-commit hook runs. + Cargo aliases are defined in [`.cargo/config.toml`](.cargo/config.toml). ## Documentation diff --git a/docs/BACKLOG.md b/docs/BACKLOG.md index adb250f..eeee56b 100644 --- a/docs/BACKLOG.md +++ b/docs/BACKLOG.md @@ -9,7 +9,8 @@ Ordered, executable stories for the first two phases of [`ROADMAP.md`](ROADMAP.m Each story has acceptance criteria (AC) and a rough size (S ≤1d, M ≈2–4d, L ≈1wk). Do them roughly top-to-bottom; within an epic, stories are mostly independent unless noted. **Definition of done for every story:** engine + (where applicable) -proto + CLI + offline test, and `cargo verify` green. +proto + CLI + offline test, and the local gate green (`cargo fmt --all -- --check`, +`cargo check-all`, `cargo test-all`). --- @@ -41,7 +42,7 @@ proto + CLI + offline test, and `cargo verify` green. `nuncio-core`). **AC:** `cargo check-all` exits 0 locally and in CI. - **0.C.2 Align CI to the local gate** (S). CI runs `cargo clippy --workspace` without `--all-targets`; make CI run `cargo check-all` so CI and local are - identical. **AC:** CI and `cargo verify` enforce the same lints. + identical. **AC:** CI and the local gate enforce the same lints. - **0.C.3 Replace the coverage gate** (M). Drop the gamed 100%-line gate (it excludes all `main.rs` and incentivized stub+matching-test theater) for a realistic threshold on engine crates plus a **required** mock-server E2E job. diff --git a/docs/DEVELOPING-IN-RUSTROVER.md b/docs/DEVELOPING-IN-RUSTROVER.md index 27669a7..aebf39b 100644 --- a/docs/DEVELOPING-IN-RUSTROVER.md +++ b/docs/DEVELOPING-IN-RUSTROVER.md @@ -110,9 +110,17 @@ RustRover's Cargo test integration is the fastest inner loop. ## 5. Quality gates (run before you commit/push) The Git pre-commit hook runs `fmt` + `clippy -D warnings` (all targets) + the full -test suite on every `git commit`, so make these green first: +test suite on every `git commit`, so make these green first. There is no combined +`cargo verify` alias — a Cargo alias is a single command's argv and can't chain +subcommands, so run the three checks separately (this is exactly what the +pre-commit hook does): + +```bash +cargo fmt --all -- --check +cargo check-all +cargo test-all +``` -- **Cargo Verify (fmt + clippy + tests)** — the whole gate in one click (= `cargo verify`). - **Cargo Check All** — just clippy, all targets, warnings-as-errors. - **Cargo Test All** — the suite. - **Cargo Coverage** — informational `llvm-cov` (needs `cargo-llvm-cov`; not a gate). @@ -120,8 +128,8 @@ test suite on every `git commit`, so make these green first: (= `cargo build-release`), i.e. what you ship for real dogfooding. Because the toolchain is pinned (1.97.1) and native, **green here == green in CI** — -so a clean *Cargo Verify* means a clean commit and (once CI minutes are back) a -clean pipeline. +so running `cargo fmt --all -- --check` plus *Cargo Check All* and *Cargo Test All* +clean means a clean commit and (once CI minutes are back) a clean pipeline. --- @@ -137,9 +145,11 @@ clean pipeline. | Cargo Build Release (daemon + CLI) | `build-release` | no | | Cargo Check All | `check-all` | no | | Cargo Test All | `test-all` | no | -| Cargo Verify (fmt + clippy + tests) | `verify` | no | | Cargo Coverage | `cov` (informational) | no | +There is no run configuration for the fmt check (`cargo fmt --all -- --check`) — +run it from the Terminal alongside *Cargo Check All* and *Cargo Test All*. + To make your own: **Run → Edit Configurations → + → Cargo Command**, set the command (e.g. `run -p nuncio-cli -- mail read --id abc`), and tick *Store as project file* to share it (it lands in `.idea/runConfigurations/`). @@ -151,7 +161,8 @@ project file* to share it (it lands in `.idea/runConfigurations/`). 1. Edit code; the editor lints (clippy) and formats-on-save as you go. 2. Run the nearest **test via its gutter icon** to check your change; **Debug** it if you need to step through. -3. When the feature/fix is done, run **Cargo Verify** — that's the commit gate. +3. When the feature/fix is done, run `cargo fmt --all -- --check`, **Cargo Check + All**, and **Cargo Test All** — that's the commit gate. 4. Commit (the hook re-runs the gate). Conventional Commits, feature branches off `dev` (see `CLAUDE.md`). 5. To see it end-to-end, run **nunciod** and drive it from the Terminal. @@ -170,7 +181,8 @@ project file* to share it (it lands in `.idea/runConfigurations/`). - **"Where's the TUI/GUI?"** Archived under `_reference/`; they'll be rebuilt as separate native client repos (roadmap Phase 5). They are not in the workspace. - **CI is currently paused** (GitHub Actions minutes). That's fine — the pinned - native toolchain makes your local *Cargo Verify* equivalent to CI. + native toolchain makes your local `fmt --check` + *Cargo Check All* + *Cargo Test + All* run equivalent to CI. --- diff --git a/docs/HANDOFF.md b/docs/HANDOFF.md index 0e58da7..11d950b 100644 --- a/docs/HANDOFF.md +++ b/docs/HANDOFF.md @@ -6,7 +6,8 @@ machine (or a new LLM) picks up the work cold. ## TL;DR 1. `git checkout dev` — the canonical branch (Phases 0–2 done + the roadmap). It is - green under the pinned toolchain (1.97.1); `cargo verify` passes. + green under the pinned toolchain (1.97.1); `cargo fmt --all -- --check`, + `cargo check-all`, and `cargo test-all` all pass. 2. Read, in order: [`CLAUDE.md`](../CLAUDE.md), [`docs/ROADMAP.md`](ROADMAP.md), [`docs/STORY-WORKFLOW.md`](STORY-WORKFLOW.md), [`docs/ARCHITECTURE.md`](ARCHITECTURE.md). @@ -61,7 +62,10 @@ commit/push, review-before-close, honest-error over green-lie.** 1. Clone the repo; `git checkout dev`. The toolchain (1.97.1) installs automatically from `rust-toolchain.toml`. Native OS build (not WSL) — the daemon needs the OS keyring. -2. `cargo verify` (fmt + clippy `-D warnings` all-targets + test-all) — confirm green. +2. Confirm green: `cargo fmt --all -- --check`, then `cargo check-all` (clippy + `-D warnings` all-targets), then `cargo test-all`. (There is no combined + `cargo verify` alias — Cargo aliases can't chain subcommands — but this is + exactly what the pre-commit hook runs.) 3. Run it: `cargo run -p nunciod` (daemon), then drive with `cargo run -p nuncio-cli -- system status`. See `docs/RUNNING.md` / `docs/DEVELOPING-IN-RUSTROVER.md`. diff --git a/docs/ROADMAP.md b/docs/ROADMAP.md index 9ebd486..352dc0f 100644 --- a/docs/ROADMAP.md +++ b/docs/ROADMAP.md @@ -27,8 +27,9 @@ property of the **contract**, not of anyone's discipline. These are non-negotiable and apply to every item below: 1. **A capability is done only when engine + proto + CLI command + offline E2E - test all exist together**, and `cargo verify` (fmt + clippy `-D warnings` - all-targets + `test-all`) is green. + test all exist together**, and the local gate (`cargo fmt --all -- --check`, + `cargo check-all` (clippy `-D warnings` all-targets), `cargo test-all`) is + green. 2. **No fabricated success.** A path that cannot do the real thing returns an honest `Unimplemented`/error — never canned data, never a fake "sent". 3. **The `.proto` files are the contract.** The `nuncio-proto` contract-stability @@ -188,5 +189,6 @@ scheduled here or folded back into the engine as they earn their place. Each milestone maps to GitHub issues (numbers above). Every capability is built via one implementer + a spec/quality review gate + an offline E2E, committed only -when `cargo verify` is green and the proto golden is consistent. Issues close -only after the review step — never on a green build alone. +when the local gate (fmt + clippy `-D warnings` + tests) is green and the proto +golden is consistent. Issues close only after the review step — never on a green +build alone. diff --git a/docs/STORY-WORKFLOW.md b/docs/STORY-WORKFLOW.md index 5e57655..b9f8cc4 100644 --- a/docs/STORY-WORKFLOW.md +++ b/docs/STORY-WORKFLOW.md @@ -21,9 +21,11 @@ implement; the PO reviews and merges. Do not merge your own work. A story is done only when **all** of these hold: 1. **engine + proto (if the API surface changes) + CLI command + offline E2E test exist together** and prove the capability end to end. -2. `cargo verify` is green — that is `cargo fmt --all -- --check`, +2. The full local gate is green — that is `cargo fmt --all -- --check`, `cargo check-all` (clippy `--all-targets --workspace -D warnings`, **zero** - warnings), and `cargo test-all` (`cargo test --workspace`). **0 ignored tests.** + warnings), and `cargo test-all` (`cargo test --workspace`), run as three + separate commands (there is no combined `cargo verify` alias — Cargo aliases + can't chain subcommands). **0 ignored tests.** 3. **No fabricated success.** A path that cannot do the real thing returns an honest `Unimplemented`/error — never canned data, never a fake "sent"/"ok". (Anti-pattern to never imitate: a client that logs "fetching…" and returns a @@ -86,9 +88,10 @@ proto story is open. Non-proto stories (engine-only, CLI-only) can run in parall 2. TDD where practical. Keep commits Conventional (`feat(scope): …`, `fix(scope): …`), imperative, <72-char subject, **no AI attribution**, no issue refs in code (a `Refs #NNN` in the commit message is fine). -3. Before pushing, make `cargo verify` green. The pre-commit hook enforces it. +3. Before pushing, make sure `cargo fmt --all -- --check`, `cargo check-all`, and + `cargo test-all` are all green. The pre-commit hook enforces this. 4. Open a **PR to `dev`** (never to `main`). In the PR body: link the issue, - summarize what you built, **paste the gate output** (`cargo verify` result + + summarize what you built, **paste the gate output** (fmt/clippy/test results + test counts) as evidence, and list any decisions or follow-ups. If you found a real bug outside your scope, **file a new issue** — do not silently fix or ignore it.