Dead code audit and strict workspace lint enforcement #240

New issue

Closed

opened 2025-12-28 19:59:05 -08:00 by jwilger · 0 comments

jwilger commented

2025-12-28 19:59:05 -08:00

(Migrated from github.com)

Background

The discovery of vestigial LocalCoordinator code reveals a subtle gap in quality enforcement. The project already has strict linting:

#![forbid(dead_code)] - strictest level, cannot be overridden
#![deny(clippy::allow_attributes)] - prevents #[allow(...)]
build.rs scans for #[allow] usage

How did dead code slip through?

The underscore prefix (_coordinator) is Rust's OFFICIAL escape hatch from dead_code warnings. When you write _foo, you're telling the compiler "I know this is unused, suppress the warning." This is legitimate for:

Implementing traits that require certain fields for Drop behavior
Placeholder bindings in pattern matching
RAII guards where the value matters but is never read

But it was MISUSED for vestigial code that should have been removed.

The Real Problem

Underscore-prefixed fields bypass dead_code - by design, but easily misused
No periodic audit - code rots, documentation drifts from reality
No lint catches unused struct fields - rustc and clippy don't have a lint for "struct field stored but never accessed"
Documentation-code sync is manual - ARCHITECTURE.md can claim traits exist that don't

Audit Scope

Phase 1: Underscore-Prefix Audit

Systematically review EVERY _foo pattern in the codebase. For each occurrence, document:

Location
Is it genuinely needed? (Drop, trait requirement, pattern binding)
Or is it suppressing dead code that should be removed?

Phase 2: Documentation-Code Sync

Verify every type/trait mentioned in docs exists:

ARCHITECTURE.md - Extract all type names, grep for their definitions
ADR files - Ensure superseded ADRs don't describe current code
Doc comments - All ignore examples should compile if un-ignored

Phase 3: Lint Configuration Consolidation

Migrate to workspace-level configuration (Cargo 1.74+) using [workspace.lints] for single source of truth.

Phase 4: Add Missing Lint Coverage

Consider adding:

clippy::unused_self - methods that don't use self
clippy::unused_async - async functions that don't await
Custom CI script for underscore-prefix audit

Acceptance Criteria

All underscore-prefixed items have documented justification or are removed
Workspace lints consolidated to [workspace.lints] in root Cargo.toml
All crates use [lints] workspace = true
Documentation matches actual code (no phantom abstractions)

Migrated from beads issue: eventcore-igt

## Background The discovery of vestigial LocalCoordinator code reveals a subtle gap in quality enforcement. The project already has strict linting: - `#![forbid(dead_code)]` - strictest level, cannot be overridden - `#![deny(clippy::allow_attributes)]` - prevents `#[allow(...)]` - build.rs scans for `#[allow]` usage **How did dead code slip through?** The underscore prefix (`_coordinator`) is Rust's OFFICIAL escape hatch from dead_code warnings. When you write `_foo`, you're telling the compiler "I know this is unused, suppress the warning." This is legitimate for: - Implementing traits that require certain fields for Drop behavior - Placeholder bindings in pattern matching - RAII guards where the value matters but is never read But it was MISUSED for vestigial code that should have been removed. ## The Real Problem 1. **Underscore-prefixed fields bypass dead_code** - by design, but easily misused 2. **No periodic audit** - code rots, documentation drifts from reality 3. **No lint catches unused struct fields** - rustc and clippy don't have a lint for "struct field stored but never accessed" 4. **Documentation-code sync is manual** - ARCHITECTURE.md can claim traits exist that don't ## Audit Scope ### Phase 1: Underscore-Prefix Audit Systematically review EVERY `_foo` pattern in the codebase. For each occurrence, document: - Location - Is it genuinely needed? (Drop, trait requirement, pattern binding) - Or is it suppressing dead code that should be removed? ### Phase 2: Documentation-Code Sync Verify every type/trait mentioned in docs exists: 1. **ARCHITECTURE.md** - Extract all type names, grep for their definitions 2. **ADR files** - Ensure superseded ADRs don't describe current code 3. **Doc comments** - All `ignore` examples should compile if un-ignored ### Phase 3: Lint Configuration Consolidation Migrate to workspace-level configuration (Cargo 1.74+) using `[workspace.lints]` for single source of truth. ### Phase 4: Add Missing Lint Coverage Consider adding: - `clippy::unused_self` - methods that don't use self - `clippy::unused_async` - async functions that don't await - Custom CI script for underscore-prefix audit ## Acceptance Criteria - [ ] All underscore-prefixed items have documented justification or are removed - [ ] Workspace lints consolidated to `[workspace.lints]` in root Cargo.toml - [ ] All crates use `[lints] workspace = true` - [ ] Documentation matches actual code (no phantom abstractions) --- *Migrated from beads issue: eventcore-igt*