diff options
Diffstat (limited to 'docs/rust-linting-proposal.md')
| -rw-r--r-- | docs/rust-linting-proposal.md | 76 |
1 files changed, 63 insertions, 13 deletions
diff --git a/docs/rust-linting-proposal.md b/docs/rust-linting-proposal.md index 65f800f..ba5b5cf 100644 --- a/docs/rust-linting-proposal.md +++ b/docs/rust-linting-proposal.md @@ -13,8 +13,9 @@ The best current design is: ``` 3. Keep the runner orchestration-only: source-file cap, `fmt --check`, `clippy`, tests, then optional deeper gates. -4. Pin an exact stable toolchain so lint drift is a conscious upgrade event. -5. Centralize repo-wide Clippy carve-outs and structural thresholds in the root manifest, and force local suppressions to carry reasons. +4. Check in project-local Cargo target-dir config so opted-in repos build under `/data/main/cargo-target/<project-slug>`. +5. Pin an exact stable toolchain so lint drift is a conscious upgrade event. +6. Centralize repo-wide Clippy carve-outs and structural thresholds in the root manifest, and force local suppressions to carry reasons. The local corpus already converges on this. The newer `adequate_*`, `memcp`, `outpost`, and `picmash` workspaces are structurally superior to the older `check.py` / shell-script pattern because they put policy in manifest tables instead of command-line tails. @@ -73,6 +74,7 @@ Across the stricter workspaces, the same repo-wide Clippy exceptions keep reappe - numeric pragmatism: `cast_*`, `float_cmp`, `implicit_hasher` - blanket-annotation fatigue: `must_use_candidate`, `return_self_not_must_use` - API-shape micro-optimizations: `needless_pass_by_value`, `trivially_copy_pass_by_ref`, `ref_option`, `unused_async` +- token-economy imports: `wildcard_imports`, `enum_glob_use`, and rustc glob import/reexport lints That is not random drift anymore. It is a de facto house profile and should be made explicit. @@ -181,6 +183,22 @@ Implication: - library-heavy repos should define `[workspace.lints.rustdoc]` - the deeper check posture should include a docs build +### 10. Cargo config is the right home for project-local target dirs + +Cargo supports `build.target-dir` in `.cargo/config.toml`, and command-line `--target-dir` overrides it. The clean starter posture is therefore a checked-in repo-local config: + +```toml +[build] +target-dir = "/data/main/cargo-target/<project-slug>" +``` + +Implication: + +- use `.cargo/config.toml` for repo-local target-dir policy +- do not pass `--target-dir` from check runners, CI, or manifest-owned command vectors +- do not mutate user-global Cargo config during bootstrap or retrofit +- repos not yet retrofitted can continue to inherit the developer's global Cargo default + ## Proposed Starter-Pack Design ### 1. Source-of-truth layout @@ -206,6 +224,9 @@ unused_crate_dependencies = "warn" unused_lifetimes = "deny" unused_qualifications = "deny" unused_results = "deny" +ambiguous_glob_imports = "allow" +ambiguous_glob_reexports = "allow" +hidden_glob_reexports = "allow" [workspace.lints.rustdoc] broken_intra_doc_links = "deny" @@ -229,6 +250,9 @@ missing_errors_doc = "allow" missing_panics_doc = "allow" multiple_crate_versions = "allow" +enum_glob_use = "allow" +wildcard_imports = "allow" + items_after_statements = "allow" many_single_char_names = "allow" match_same_arms = "allow" @@ -269,9 +293,6 @@ clippy_command = [ "--workspace", "--all-targets", "--all-features", - "--", - "-D", - "warnings", ] test_command = ["cargo", "test", "--workspace", "--all-targets", "--all-features"] doc_command = ["cargo", "doc", "--workspace", "--all-features", "--no-deps"] @@ -318,7 +339,7 @@ Add the source-file cap alongside the command vectors: ```toml [workspace.metadata.rust-starter.source_files] -max_lines = 2500 +max_lines = 3000 include = ["*.rs", "**/*.rs"] exclude = [] ``` @@ -329,7 +350,28 @@ Why this belongs here: - keeping the threshold in root metadata still makes the manifest the policy source of truth - the runner can stay generic by enforcing a small schema instead of hard-coding repo-specific paths or numbers -### 2. Toolchain posture +### 2. Project-local Cargo target directory + +Check in `.cargo/config.toml`: + +```toml +# Replace `rust-starter-template` with the target repository slug. +# This is a repo-local ratchet only; do not mutate user-global Cargo config. + +[build] +target-dir = "/data/main/cargo-target/rust-starter-template" +``` + +Use the repo directory basename as the default slug. If two local repos would +collide, append a short stable disambiguator. The goal is to keep artifacts off +the source disk without depending on wrappers or repeating `--target-dir` in +every command. + +This is deliberately not a global Cargo-config migration. A repo opts in by +checking in the file; otherwise the user's existing global Cargo default remains +the fallback. + +### 3. Toolchain posture Check in a `rust-toolchain.toml` like: @@ -342,7 +384,7 @@ components = ["clippy", "rustfmt"] Use an exact stable patch at scaffold time and bump it deliberately. Do not float on `"stable"` if the goal is reproducible strictness. -### 3. Exception policy +### 4. Exception policy This is the center of gravity. If the exception policy is wrong, the rest becomes theater. @@ -402,7 +444,7 @@ The starter baseline should cherry-pick only the restriction lints with durable That is aggressive without becoming absurd. -### 4. Fast gate versus deep gate +### 5. Fast gate versus deep gate #### Fast gate @@ -410,7 +452,7 @@ This should be the canonical local verification gate: 1. enforce the source-file cap from `workspace.metadata.rust-starter.source_files` 2. `cargo fmt --all --check` -3. `cargo clippy --workspace --all-targets --all-features -- -D warnings` +3. `cargo clippy --workspace --all-targets --all-features` 4. `cargo test --workspace --all-targets --all-features` This is the default industrial baseline. @@ -438,7 +480,7 @@ Add a heavier gate for mature repos: If the feature graph explodes, degrade to `--each-feature` or grouped feature subsets instead of abandoning feature-matrix coverage entirely. -### 5. Strong optional strengthenings +### 6. Strong optional strengthenings #### Explicit `check-cfg` declarations @@ -483,6 +525,12 @@ Run a scheduled CI job against the latest stable toolchain without updating the That is the old pattern. It is operationally inferior to manifest-owned policy. +### Passing `--target-dir` from runners or CI + +That is target-dir folklore, not policy. Put repo-local Cargo output routing in +`.cargo/config.toml`; leave user-global Cargo config alone and keep command +vectors portable. + ### Treating `clippy::too_many_lines` as a file-size limit That lint is about function length. It is not a substitute for a hard source-file cap, and pretending otherwise guarantees drift. @@ -507,13 +555,13 @@ If the goal is "force industrial-grade linting", ambient toolchain drift is the Use this style: -> Set up Rust linting with the `rust-starter` industrial profile: link target `AGENTS.md` to [docs/rust-style-doctrine.md](/home/main/programming/projects/rust_starter/docs/rust-style-doctrine.md); pin an exact stable `rust-toolchain.toml`; put repo policy only in root `[workspace.lints.{rust,rustdoc,clippy}]` plus manifest-owned canonicalization and verification command vectors and source-file-cap metadata in `workspace.metadata`; make every crate opt into `[lints] workspace = true`; make the default local `check` path canonicalize first, but keep a non-mutating `verify` path for CI; cherry-pick restriction bans instead of enabling `clippy::restriction`; keep repo-wide Clippy carve-outs centralized and commented in `Cargo.toml`; and require local suppressions to use `#[expect(..., reason = "...")]` unless a permanent `#[allow(..., reason = "...")]` is truly justified. +> Set up Rust linting with the `rust-starter` industrial profile: link target `AGENTS.md` to [docs/rust-style-doctrine.md](/home/main/programming/projects/rust_starter/docs/rust-style-doctrine.md); install project-local `.cargo/config.toml` with `[build] target-dir = "/data/main/cargo-target/<project-slug>"` without changing user-global Cargo config; pin an exact stable `rust-toolchain.toml`; put repo policy only in root `[workspace.lints.{rust,rustdoc,clippy}]` plus manifest-owned canonicalization and verification command vectors and source-file-cap metadata in `workspace.metadata`; make every crate opt into `[lints] workspace = true`; make the default local `check` path canonicalize first, but keep a non-mutating `verify` path for CI; cherry-pick restriction bans instead of enabling `clippy::restriction`; keep repo-wide Clippy carve-outs centralized and commented in `Cargo.toml`; and require local suppressions to use `#[expect(..., reason = "...")]` unless a permanent `#[allow(..., reason = "...")]` is truly justified. That is long, but it is precise and inferable by a model. ## Bottom Line -The starter pack should standardize the newer Cargo-centric pattern already emerging locally, harden it with toolchain pinning, distinguish manifest-owned policy from runner orchestration, export a first-class canonicalization pipeline, enforce a manifest-backed hard source-file cap, tighten suppression discipline with `reason = "..."`, and add an optional deeper gate for feature matrices, docs, dependency hygiene, and public API drift. +The starter pack should standardize the newer Cargo-centric pattern already emerging locally, add repo-local Cargo target-dir config for `/data/main/cargo-target/<project-slug>`, harden it with toolchain pinning, distinguish manifest-owned policy from runner orchestration, export a first-class canonicalization pipeline, enforce a manifest-backed hard source-file cap, tighten suppression discipline with `reason = "..."`, and add an optional deeper gate for feature matrices, docs, dependency hygiene, and public API drift. The single strongest improvement over the current local state is not any one lint. It is moving the center of gravity from bespoke scripts to manifest-owned policy. @@ -523,6 +571,8 @@ Primary sources: - Cargo manifest `lints` section: <https://doc.rust-lang.org/cargo/reference/manifest.html#the-lints-section> - Cargo workspaces and inherited lint tables: <https://doc.rust-lang.org/cargo/reference/workspaces.html#the-lints-table> +- Cargo configuration and `build.target-dir`: <https://doc.rust-lang.org/cargo/reference/config.html#buildtarget-dir> +- Cargo build cache layout: <https://doc.rust-lang.org/cargo/reference/build-cache.html> - `cargo fix`: <https://doc.rust-lang.org/cargo/commands/cargo-fix.html> - Cargo’s unstable `[lints.cargo]` namespace: <https://doc.rust-lang.org/nightly/cargo/reference/unstable.html#cargo-lints> - Clippy overview and lint-group guidance: <https://doc.rust-lang.org/stable/clippy/> |