check-code-quality

Rust Code Quality Checks

When to Use

• After completing significant code changes
• Before creating commits
• Before creating pull requests
• When user says "check code quality", "run quality checks", "make sure code is good", etc.

Non-Blocking Execution via Subagents

Long-running verification commands (such as ./check.fish --test, ./check.fish --doc, ./check.fish --quick-doc, and ./check.fish --full) can take multiple minutes. To keep the primary conversation responsive and unblocked:

1. Fast Synchronous Checks: Lightweight checks like ./check.fish --check (fast typecheck) and ./check.fish --fmt take only a few seconds and can run directly in the conversation.
2. Long-Running Checks via Subagent: Delegate time-consuming checks to a background subagent (e.g., invoke_subagent with TypeName: "self").
3. Continuous Collaboration: While the subagent runs tests or builds docs in the background, the primary agent remains completely free to converse, review diffs, answer questions, or plan next steps with the user.

Quick Approach (Recommended)

Run the comprehensive check script which handles everything automatically:

./check.fish --full

This runs all checks in order: typecheck → build → clippy → tests → doctests → docs

Benefits of using check.fish --full:

• ICE recovery: Automatically cleans cache and retries on Internal Compiler Errors
• Toolchain escalation: If ICE persists, escalates to rust-toolchain-update.fish to find a stable nightly
• Config change detection: Auto-cleans stale artifacts when Cargo.toml or toolchain changes
• Performance optimized: Uses tmpfs, ionice, and parallel jobs for speed

Other check.fish Commands

For granular control, use individual commands:

Command	What it runs
./check.fish --check	cargo check (fast typecheck)
./check.fish --build	cargo build (compile production)
./check.fish --clippy	cargo clippy --all-targets (linting)
./check.fish --fmt	cargo fmt + cargo rustdoc-fmt on git-changed files
./check.fish --test	cargo test + doctests
./check.fish --doc	cargo doc --no-deps (quick docs)
./check.fish --quick-doc	cargo doc --no-deps (fastest, no staging/sync)
./check.fish --full	All of the above + lychee link rot check

Step-by-Step Approach (Alternative)

If you need more control or want to run checks manually:

1. Fast Typecheck

./check.fish --check
# (runs: cargo check)

Quickly verifies the code compiles without generating artifacts.

2. Compile Production Code

./check.fish --build
# (runs: cargo build)

Ensures production code builds successfully.

3. Format Rustdoc Comments

Invoke the write-documentation skill to format rustdoc comments using cargo rustdoc-fmt.

This formats markdown tables, converts inline links to reference-style, and ensures dashes, en dashes, or em dashes (-, –, or —) are not used to connect sentences/clauses (prefer separate sentences or colons/semicolons).

4. Generate Documentation

./check.fish --quick-doc
# (runs: cargo doc --no-deps, directly to serving dir - fastest for iteration)

Verify there are no documentation build warnings or errors. Use --quick-doc for fast feedback during development. Use --doc for final verification before commits (includes staging/sync).

If there are link warnings, use the /fix-intradoc-links command to resolve them.

Heading Anchor (Slug) Integrity: If you modified any heading text (e.g., # My Heading), the automatically generated HTML anchor (e.g., #my-heading) will change.

• Identify Changes: Look for changed headings in git-dirty files.
• Proactive Search: Use grep_search to find any existing links (e.g., path#old-slug) that point to the old anchors and update them.
• Validation: While cargo doc warns about many broken fragments, proactive searching prevents "orphan" links in external documentation or complex intra-doc paths.

CRITICAL: Never remove intra-doc links to fix warnings. When you encounter:

• Unresolved link to a symbol → Fix the path using crate:: prefix (see write-documentation skill)
• Unresolved link to a test module → Add #[cfg(any(test, doc))] visibility (see organize-modules skill)
• Unresolved link to a platform-specific module → Use #[cfg(all(any(test, doc), target_os = "..."))]

Links provide refactoring safety - cargo doc catches stale references. Converting to plain backticks removes this protection.

5. Link Rot Check (External URLs)

Included automatically in ./check.fish --full. Runs lychee on git-modified files to detect broken external URLs in rustdoc comments.

cargo doc --no-deps (step 4) validates intra-doc links but not external HTTP/HTTPS URLs. lychee fills that gap. Config in lychee.toml (repo root) excludes known false positives (example file:// URIs, test fixture URLs, sites that block automated requests).

If lychee reports 404s, fix the URL by finding the new location. See the task file task/add-lychee-to-detect-link-rot.md for the full categorization of findings.

6. Clean Inline Crate Prefixes

Invoke the remove-crate-prefix skill to ensure the codebase follows the strict "Clean Imports over Inline Absolute Paths" rule before finalizing quality checks.

7. Git Diff Audit (Surgical Precision)

git diff

Inspect git diff on all modified files to audit line-by-line that only intended modifications were made and zero collateral formatting, lost comments, or doc section drift occurred.

8. Linting

./check.fish --clippy
# or invoke the `run-clippy` skill

Runs clippy and enforces code style standards. You MUST fix all warnings. Do not just report them. If ./check.fish --clippy reports warnings, use cargo clippy --all-targets --fix --allow-dirty to auto-fix where possible, and manually fix any remaining warnings. Never ignore warnings during a quality check.

9. Concurrency Safety Check

Invoke the concurrency-safety skill to verify thread-safety patterns.

Checklist:

• Loud Lock Releases: Are drop(guard) calls explicit and as early as possible?
• Chain of Custody: Are MutexGuards passed and returned by value to prevent stale usage?
• Ergonomic Atomics: Is AtomicU8Ext used instead of raw load/store?
• No Deadlocks: Are locks released before calling macros or long-running async blocks?

10. Bounds Safety Check

Invoke the check-bounds-safety skill to verify index and length handling.

Checklist:

• Type Safety: Are Index and Length types used instead of raw usize?
• Correct Trait: Is ArrayBoundsCheck used for buffer access and CursorBoundsCheck for positioning?
• CSI Zero Prevention: Are TermRowDelta and TermColDelta used for relative cursor movement?
• Off-by-One: verify index < length for access and index <= length for cursor.

11. Audit Test Coverage (Zero Bloat) on Modified Files

For every source file that is modified in the current working tree, invoke the check-test-coverage skill:

• Branch-Targeted Verification: Ensure all custom logic branches, match arms, error paths, and state transitions are covered by tests.
• Eliminate Test Bloat: Confirm zero test bloat (no redundant tests asserting standard library behaviors, compiler derives like #[derive(Default)], or third-party macros like strum and clap).
• One Test per Branch: Confirm that each test serves a distinct purpose covering our code.

12. Run All Tests

./check.fish --test
# (runs: cargo test --all-targets && cargo test --doc)

Runs all tests (unit, integration, doctests).

• Test Scope Principle: Ensure tests strictly target our codebase's branches, state transitions, and logic paths (see organize-tests skill). Do NOT write redundant tests that merely re-verify standard library or third-party crate behaviors.
• If tests fail, use the Task tool with subagent_type='test-runner' to fix failures.

13. Stress Test (Optional - After Major Refactors)

After major refactors or changes that affect process spawning, PTY tests, or async infrastructure, run the full test suite 20 times back-to-back to detect flaky regressions:

for i in {1..20}; do echo "=== Run $i/20 ===" && cargo test --all-targets -- --nocapture 2>&1 | grep -E "^test result:" | head -3 || { echo "FAILED on run $i"; exit 1; }; done && echo "ALL 20 RUNS PASSED"

When to run:

• After refactoring PTY test infrastructure (generate_pty_test!, spawn_controlled_in_pty)
• After changes to process lifecycle, signal handling, or async I/O code
• After modifying the resilient reactor thread (RRT) restart logic
• Before merging large cross-cutting changes that touch many test files

14. Cross-Platform Verification (Optional)

For code with platform-specific #[cfg] gates (especially Unix-only code), verify Windows compatibility:

cargo rustc -p <crate_name> --target x86_64-pc-windows-gnu -- --emit=metadata

This checks that #[cfg(unix)] and #[cfg(not(unix))] gates compile correctly on Windows without needing a full cross-compiler toolchain.

When to run:

• After adding or modifying #[cfg(unix)] or #[cfg(target_os = "...")] attributes
• When working on platform-abstraction code
• Before committing changes to DirectToAnsi input handling or other Unix-specific code

15. Final Step: Manual Review

A task, phase, or sub-phase is not complete until a manual review has been performed by the user. This is the final verification before marking a task as done.

• Type-Safe Errors: Did you use custom error types (enums/structs with thiserror and miette) instead of raw String for Result errors?
• No .and_then(): Did you avoid using .and_then() for Option/Result combinators, preferring idiomatic ? ope

---

Content truncated.