feat: add cargo xtask lint-extended subcommand for comment/repetition smells

.github/workflows/tests.yaml

@@ -29,7 +29,7 @@ env:
 
 jobs:
   # ---------------------------------------------------------------------------
-  # Lint (fmt + clippy + rustdoc)
+  # Lint (fmt + clippy + rustdoc + extended-lint)
   # ---------------------------------------------------------------------------
 
   lint:
@@ -47,6 +47,13 @@ jobs:
       - name: Documentation
         run: make doc
 
+      - name: Fetch extended-lint diff base
+        run: |
+          git fetch origin "${GITHUB_BASE_REF:-main}":"refs/remotes/origin/${GITHUB_BASE_REF:-main}" --depth=1
+
+      - name: Extended lint
+        run: make extended-lint
+
   # ---------------------------------------------------------------------------
   # Build + test
   # ---------------------------------------------------------------------------

CONTRIBUTING.md

@@ -23,6 +23,7 @@ make build          # workspace build
 make test           # all tests
 make fmt            # format with nightly rustfmt
 make lint           # clippy + nightly fmt check
+make extended-lint  # diff-scoped heuristic checks (TODOs, comment slop, repetition), via xtask
 make audit          # cargo audit + cargo deny check
 ```
 

Cargo.toml

@@ -6,6 +6,9 @@ rust-version = "1.96"
 license = "MIT"
 publish = false
 
+[workspace]
+members = ["xtask"]
+
 [features]
 integration = []
 

Containerfile

@@ -21,12 +21,18 @@ WORKDIR /src
 
 # The manifest declares an explicit [[bench]], so cargo refuses to parse
 # it unless that file exists. Stub it alongside src/ or this layer fails
-# before a single dependency is compiled.
+# before a single dependency is compiled. The `xtask` workspace member is
+# a dev-only tool never shipped in this image; `-p praxis-operator` keeps
+# it out of the build target, but cargo still needs its manifest and a
+# target file present to resolve the workspace, so it gets a permanent
+# stub rather than being swapped for real source later.
 COPY Cargo.toml Cargo.lock ./
-RUN mkdir -p src benches \
+COPY xtask/Cargo.toml xtask/Cargo.toml
+RUN mkdir -p src benches xtask/src \
     && printf '//! stub\nfn main() {}\n' > src/main.rs \
     && printf 'fn main() {}\n' > benches/config_generation.rs \
-    && cargo build --release --locked \
+    && printf 'fn main() {}\n' > xtask/src/main.rs \
+    && cargo build --release --locked -p praxis-operator \
     && rm -rf src
 
 # ---------------------------------------------------------------------------
@@ -39,7 +45,7 @@ RUN mkdir -p src benches \
 COPY src src
 COPY benches benches
 RUN touch src/main.rs \
-    && cargo build --release --locked \
+    && cargo build --release --locked -p praxis-operator \
     && cp target/release/praxis-operator /usr/local/bin/
 
 # ---------------------------------------------------------------------------

Makefile

@@ -1,5 +1,5 @@
 .PHONY: all build release check test lint fmt doc audit clean
-.PHONY: coverage-check
+.PHONY: coverage-check extended-lint
 .PHONY: require-container-engine images container praxis-image
 .PHONY: kind-up kind-down kind-reset conformance smoke-test
 .PHONY: dev-env dev-conformance dev-cycle dev-integration dev-push
@@ -46,6 +46,9 @@ lint:
 	cargo clippy --all-targets -- -D warnings
 	cargo +nightly fmt --all -- --check
 
+extended-lint:
+	cargo run -p xtask -- lint-extended
+
 fmt:
 	cargo +nightly fmt --all
 
@@ -197,6 +200,7 @@ help:
 	@echo ""
 	@echo "Quality:"
 	@echo "  lint               clippy + nightly rustfmt check"
+	@echo "  extended-lint      diff-scoped heuristic checks (TODOs, comment slop, repetition)"
 	@echo "  fmt                format with nightly rustfmt"
 	@echo "  doc                build docs with warnings denied"
 	@echo "  audit              cargo audit + cargo deny"

docs/conventions.md

@@ -25,6 +25,12 @@
 - **cargo-audit**: Check for vulnerable dependencies
 - **cargo-deny**: Enforce supply chain safety policies
 - **rustdoc**: Generate the API documentation
+- **`xtask lint-extended`** (`make extended-lint`): diff-scoped
+  heuristic checks for patterns clippy can't catch structurally --
+  leftover `TODO`/`FIXME` markers, commented-out code, narrating "what"
+  comments, repeated literals that should be named constants, weak
+  identifier names, and new clippy suppressions. Only scans lines added
+  since the diff base, so pre-existing code is never relitigated.
 
 ### Comments vs Tracing
 

xtask/Cargo.toml

@@ -0,0 +1,33 @@
+[package]
+name = "xtask"
+version = "0.1.0"
+edition = "2024"
+rust-version = "1.96"
+license = "MIT"
+publish = false
+
+[dependencies]
+anyhow = "1.0.100"
+regex = "1.13.1"
+
+[lints.rust]
+dead_code = "deny"
+unsafe_code = "deny"
+missing_docs = "deny"
+unreachable_pub = "deny"
+unused_imports = "deny"
+unused_variables = "deny"
+trivial_casts = "deny"
+trivial_numeric_casts = "deny"
+unused_qualifications = "deny"
+
+[lints.clippy]
+# unwrap_used/expect_used/panic are intentionally not denied here: this is a
+# dev-only build tool (not shipped production code), and its regexes are
+# compile-time-constant literals compiled once into `LazyLock` statics, where
+# `.unwrap()` is the standard idiom (a bad pattern would fail on first run).
+todo = "deny"
+unimplemented = "deny"
+dbg_macro = "deny"
+print_stdout = "allow"
+print_stderr = "allow"