Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions .github/pull_request_template.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,4 +6,5 @@ SPDX-License-Identifier: MIT

- [ ] If this PR fixes a bug, searched `tests/e2e-cucumber/expectations.toml` for the fixed ticket ID and removed/narrowed any now-stale xfail rows.
- [ ] If this PR adds a new subcommand or subsystem, its domain implementation lives in its own file per `docs/architecture.md` (the clap declaration in `cli.rs` and the dispatch wiring in `main.rs`/`lib.rs` are expected, not a violation).
- [ ] If this PR adds, renames or removes a production source file, `docs/architecture.md` has the matching entry (`cargo xtask check-architecture-doc` fails otherwise), and the prose of any entry whose file changed role still describes it, which the check cannot verify.
- [ ] Every new or changed user-facing message was read against the code path that runs after it, and its test asserts the resulting state — not only the wording — per AGENTS.md §3. Covers claims of an outcome, remediation advice naming a command, and promises that something will *not* happen.
8 changes: 8 additions & 0 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -165,6 +165,10 @@ jobs:
# `heavy`-gated) doesn't silently skip the test that reads it.
- 'docs/ci-hardware-testing.md'
- 'tests/e2e-cucumber/README.md'
# `cargo xtask check-architecture-doc` (clippy job) compares this
# module map with the source tree; deleting or rewording an entry
# can break it though no *.rs file moved.
- 'docs/architecture.md'
# license_headers_hook_has_no_file_type_filter (xtask) reads this
# file's license-headers hook config; an edit here that reopens the
# file-type-filter gap must still run that test on the PR.
Expand Down Expand Up @@ -1420,6 +1424,10 @@ jobs:
if: needs.changes.outputs.rust == 'true'
run: cargo xtask check-crate-edges

- name: Every production source file has an entry in docs/architecture.md
if: needs.changes.outputs.rust == 'true'
run: cargo xtask check-architecture-doc

- name: Published Doctor catalog is current
if: needs.changes.outputs.rust == 'true'
run: cargo xtask catalog --check
Expand Down
20 changes: 20 additions & 0 deletions .pre-commit-config.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -119,6 +119,26 @@ repos:
stages: [pre-commit]
groups: [local-tools] # runs in the dedicated `docs-links` CI job

# Module map: every production source file needs an entry in
# docs/architecture.md. `lychee` above only checks that links already in the
# doc resolve; this is the other direction, so a new file nobody wrote an
# entry for fails. Pre-commit for fast feedback, pre-push for a commit made
# with --no-verify: it reads the working tree, not the pushed commits, so it
# only agrees with CI when the tree is clean, and CI is the gate. It reads the
# whole tree, so it is not narrowed to changed files: a rename or deletion
# anywhere can change the answer, and a delete-only commit has no changed
# files to match a filter.
- repo: local
hooks:
- id: architecture-doc
name: every source file is in docs/architecture.md
entry: cargo xtask check-architecture-doc
language: system
always_run: true
pass_filenames: false
stages: [pre-commit, pre-push]
groups: [local-tools] # runs in the `clippy` CI job (compiles xtask)

# Rust + PowerShell: mirror the CI checks using the local toolchain.
- repo: local
hooks:
Expand Down
5 changes: 5 additions & 0 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -227,6 +227,10 @@ Keep docs and behavior claims in sync while editing:
file outside it), and a link leaving a skill folder in `skills/`
(published or embedded elsewhere, §7). This covers citations you add or
edit, not converting existing bare paths in an unrelated change
- when you add, rename or remove a production source file, update its entry in
`docs/architecture.md` in the same change; `cargo xtask check-architecture-doc`
fails on a file with no entry (§6), but not on an entry whose description
went stale
- when a statement such as "X is not supported" or "there is no Y" becomes false,
grep the same surfaces for the old claim before pushing
- write the PR body from the final diff, not the first commit, and re-read it after
Expand Down Expand Up @@ -274,6 +278,7 @@ Guardrails:
- `crates/rocm-engine-protocol` is a contract surface; verify all impacted engines after protocol changes
- first-party crate-layering invariants (e.g. `rocmd` must never depend on `rocm`) are enforced by `cargo xtask check-crate-edges` (`xtask/src/crate_edges.rs`); a new first-party dependency edge failing that check means the edge needs review, not a bypass
- source file size is checked by `cargo xtask check-module-size` ([`module_size.rs`](xtask/src/module_size.rs)): no source file may exceed 1,500 production lines (test-gated items excluded), with one limit for every file and no exemption mechanism. A PR that would push a file past it splits the file in the same change; do not raise the limit or opt a file out. Merely editing a file that is already over the limit does not by itself require a split: those files are split under their own tickets, and the check cannot become blocking until none is left. Today the CI step and pre-commit hook only report; see `docs/architecture.md`
- every production source file (a `.rs` file under `apps/*/src`, `crates/*/src` or `engines/*/src`) has an entry in `docs/architecture.md`, enforced by `cargo xtask check-architecture-doc` ([architecture_doc.rs](xtask/src/architecture_doc.rs)) in the `clippy` CI job and in the `architecture-doc` prek hook at commit and push. Add the entry in the same change as the file. Do not add the file to the check's `EXEMPT` list to make it pass: that list holds only what was uncited when the check was added and is meant to shrink: its size is capped by `EXEMPT_CEILING`, so growing it is a visible, reviewed exception. Remove an entry from it when you document that file. The check reads no prose, so keeping an entry's description true is still on you
- preserve strict GPU-required behavior; do not introduce silent CPU fallback
- respect platform gates (for example, native Windows handling for vLLM)
- pin third-party GitHub Actions to a full commit SHA with a trailing `# vX.Y.Z` comment, never a moving tag (`@v2`, `@main`); a retagged or compromised action otherwise enters CI silently. Bump the SHA and comment together when upgrading
Expand Down
6 changes: 4 additions & 2 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -46,7 +46,7 @@ prek install # fast checks on every commit
prek install -t pre-push # heavier checks on push (clippy + tests of the crates the push affects)
```

`prek` runs the same checks locally that CI enforces: `cargo fmt`, `clippy`, `cargo test`, `ruff` (Python), `shellcheck` (shell), PowerShell syntax, license headers (`hawkeye`), markdown links (`lychee`), and the generated manifests (`MANIFEST.md`, `THIRD_PARTY_NOTICES.txt`).
`prek` runs the same checks locally that CI enforces: `cargo fmt`, `clippy`, `cargo test`, `ruff` (Python), `shellcheck` (shell), PowerShell syntax, license headers (`hawkeye`), markdown links (`lychee`), the module map (`cargo xtask check-architecture-doc`), and the generated manifests (`MANIFEST.md`, `THIRD_PARTY_NOTICES.txt`).

The pre-push hooks (`cargo clippy`, the e2e harness clippy and `cargo test`) check only the crates your push affects: the crates whose files changed plus every crate that depends on them, selected the way CI's `cargo xtask affected` does. They check the whole workspace when a change cannot be confined to specific crates (the lockfile, the root manifest, the toolchain file, workflow files, a doc an xtask test reads, or a path no crate owns), and when the affected crates cannot be determined at all, for example because the remote branch tip is not fetched locally or the pushed range lists no changed files. They also add the crates whose tests read files from outside their own crate: any Rust file adds `xtask`, whose contract tests scan every source file, and `README.md`, `docs/` and `skills/` add `rocm` and `xtask`. Each step prints the scope it chose and why. A push that changes no Rust file runs none of the cargo steps, whatever else it changes (a lockfile-only push included). A green hook is an early warning and not the gate: on pull requests CI lints the whole workspace, but its Linux test job runs only the affected crates, and the whole workspace's tests run in the Windows debug job, in the merge queue and on `main`. To see what a push would check without compiling anything, run `cargo xtask pre-push-check test --dry-run --base origin/main` (the steps are `clippy`, `clippy-e2e` and `test`).

Expand Down Expand Up @@ -85,10 +85,12 @@ cargo install lychee@0.24.2 --locked # pinned to match the CI docs-links job (

### Module organization

New subcommands and subsystems default to their own file from day one. Don't let them grow inside `main.rs`/`lib.rs` waiting for a future extraction pass. See `docs/architecture.md` for the two extraction patterns in use, the current module map, and the module-organization convention in full. Its file links, including every concrete file citation in the per-crate inventories, are checked for resolution (not prose accuracy) by the `docs-links` job below; its section headings and directory names stay bare and unchecked.
New subcommands and subsystems default to their own file from day one. Don't let them grow inside `main.rs`/`lib.rs` waiting for a future extraction pass. See `docs/architecture.md` for the two extraction patterns in use, the current module map, and the module-organization convention in full. Its file links, including every concrete file citation in the per-crate inventories, are checked for resolution (not prose accuracy) by the `docs-links` job below, and every production source file must appear in it (see below); its section headings and directory names stay bare and unchecked.

Crate-layering invariants, such as `rocmd` never depending on `rocm`, are enforced by `cargo xtask check-crate-edges` (`xtask/src/crate_edges.rs`). File size is checked by `cargo xtask check-module-size` (`xtask/src/module_size.rs`): no source file may exceed 1,500 production lines, test code excluded, and a change that would cross the limit splits the file instead. Editing a file that is already over the limit does not by itself require a split; those files are split under their own tickets. For now the CI step and the `cargo-module-size` pre-commit hook report offenders without failing.

Every production source file, meaning a `.rs` file under `apps/*/src`, `crates/*/src` or `engines/*/src`, must have an entry in `docs/architecture.md`: a relative markdown link to it, which has to render as a link (a path inside an HTML comment, a code block or a code span does not count, and neither does a malformed link such as one missing its `)`, or an image). Use an inline `[text](path)` link with its text on one line; reference-style links, a `?query` suffix and root-relative paths are not recognised. `build.rs` files and the `tests/` and `examples/` trees are out of scope. `cargo xtask check-architecture-doc` (`xtask/src/architecture_doc.rs`) enforces that in the `clippy` CI job and in the `architecture-doc` prek hook, which runs on every commit and every push, over the whole tree. A new file with no entry fails it. This is the opposite direction to the `lychee` check below, which only confirms that links already in the doc still resolve. Test-only helpers (`test_support.rs`, `test_env.rs`, `*_proptests.rs`, `*_props.rs`, `*_properties.rs`) need no entry. The files that had none when the check was added are listed in `EXEMPT` in `xtask/src/architecture_doc.rs`; that list is meant to shrink, and its size is capped by `EXEMPT_CEILING` in the same file, so growing it is a visible, reviewed exception rather than a way to make the check pass. When you document one of them, remove it from `EXEMPT` in the same change, or the check fails on the stale entry. The check does not read the prose of an entry, so keeping a description true when a file's role changes is still up to you.

Every local (relative-path) Markdown link and `#anchor` fragment in the repository (outside `docs/rocm-docs/`, which `docs-build` covers instead, and hidden directories such as `.github/`, which neither check walks) is checked by the `docs-links` CI job and by the `lychee` prek hook above, both configured by `lychee.toml` (which lists the current exclusions). Both run offline only, so they don't catch broken external `https://` links.

Since only links are checked, cite a specific repository file as a link relative to the citing file, `[fix.rs](../crates/rocm-core/src/fix.rs)` from `docs/`, rather than a bare backtick path, which nothing checks. The full rule, including the link forms that fail the check and the places it doesn't apply (`.github/`, links leaving a `skills/` folder, and `docs/rocm-docs/` along with the files it includes, which are this file and README.md), is in AGENTS.md section 5 ("Investigate rocm-cli Before Editing"); it applies to citations you add or edit.
Expand Down
4 changes: 4 additions & 0 deletions docs/architecture.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,8 @@ This is the living module map for rocm-cli. It's a contributor-facing reference

> Before relying on any entry below, verify current file and function boundaries directly (e.g. `grep`) rather than trusting this doc's wording. Module boundaries shift as the codebase grows, and a stale-but-plausible-looking note is worse than an explicit prompt to check. Every concrete file citation in the Module map's per-crate inventories below — except "the old agent.rs" in the `rocm-dash-tui` entry (historical prose about a deleted file) and `report.json` in the `crates/e2e-report` entry (cucumber's untracked generated output) — is a relative markdown link rather than a bare filename, checked offline by [lychee](https://github.com/lycheeverse/lychee) in CI (the `docs-links` job, config in `lychee.toml`) — a moved or deleted file fails CI immediately, naming the broken link. That check doesn't check that the surrounding prose (e.g. which extraction pattern a module follows) is still accurate; the caution above still applies to everything but link resolution.

A second check runs the other way: `cargo xtask check-architecture-doc` ([`architecture_doc.rs`](../xtask/src/architecture_doc.rs)) fails when a production source file — a `.rs` file under `apps/*/src`, `crates/*/src` or `engines/*/src` — has no link in this document, so a new module cannot land without an entry. Only a link that renders as one counts: a path inside an HTML comment, a code block or a code span does not, and neither does a malformed link (one missing its `[` or `)`, or with an escaped bracket), an image, or the outer brackets of a link that contains another link. Write the entry as an inline `[text](path)` link with its text on one line; `<path>` delimiters around the destination are accepted, but reference-style links, a `?query` suffix and root-relative paths are not. `build.rs` files and the `tests/` and `examples/` trees are out of scope. It runs in the `clippy` CI job and in the `architecture-doc` prek hook, at commit and at push. Test-only helpers (`test_support.rs`, `test_env.rs`, `*_proptests.rs`, `*_props.rs`, `*_properties.rs`) need no entry. The files that were uncited when the check was added, mostly in the dashboard crates, are listed in its `EXEMPT` constant; documenting one means removing it from that list in the same change.

## Module organization convention

New subcommands and subsystems default to their own file from day one — they should not grow inside `main.rs`/`lib.rs` waiting for a future extraction pass. Two extraction patterns already exist in the codebase; use whichever fits:
Expand Down Expand Up @@ -289,6 +291,8 @@ The other three dashboard crates are described at crate level here, not module b

A contract surface: verify all impacted engines after any protocol change here (see [`AGENTS.md`](../AGENTS.md)).

- [`lib.rs`](../crates/rocm-engine-protocol/src/lib.rs) — the whole crate: the protocol and recipe-contract version constants, the request/response envelopes and the per-method request and response types for the `EngineMethod` calls (`detect`, `install`, `capabilities`, `resolve_model`, `launch`, `healthcheck`, `endpoint`, `stop`, `logs`), the `DevicePolicy` and `GpuSelection` types with the GPU-visibility helpers engines apply to a child process, engine-plugin binary naming and discovery, and the endpoint API key file carrier (`ENDPOINT_API_KEY_FILE_ENV`, `resolve_endpoint_api_key`, `is_public_bind_host`) that `rocm` and `rocmd` share.

### `crates/rocm-deps`

Pinned versions of the third-party runtimes rocm-cli manages (from workspace-root [`runtime-deps.toml`](../runtime-deps.toml), turned into constants by [`build.rs`](../crates/rocm-deps/build.rs)). Small and already single-purpose; not part of the modularization effort's target list.
Expand Down
16 changes: 16 additions & 0 deletions docs/testing.md
Original file line number Diff line number Diff line change
Expand Up @@ -51,6 +51,22 @@ The counting rules are unit-tested in `xtask/src/module_size.rs`:
cargo test -p xtask module_size
```

### Module map check

Every production source file must have an entry in [architecture.md](architecture.md). The
check runs in the `clippy` CI job and in the `architecture-doc` prek hook, and you can run it
on its own:

```bash
cargo xtask check-architecture-doc
```

It fails on a `.rs` file under `apps/*/src`, `crates/*/src` or `engines/*/src` that the doc
does not link, and on a stale entry in the `EXEMPT` list in
[architecture_doc.rs](../xtask/src/architecture_doc.rs). Test-only helpers need no entry. The
`lychee` check is complementary, not redundant: it confirms that links already in the doc
resolve, and says nothing about a file the doc never mentions.

### Tests that touch the environment

`std::env::set_var` / `remove_var` change state shared by every thread in the
Expand Down
Loading
Loading