Summary
Add a detector for commented-out code blocks and redundant "narration" comments — comments that restate what the next line literally does. Both are common AI-assistance artifacts and reinforce DebtLens's AI-era maintainability positioning.
Motivation
Commented-out code rots and confuses readers (version control already preserves history), and narrate-the-obvious comments add noise without intent. Neither is caught today, and both align with the product identity ("patterns that slip in when teams move fast with assistants").
Proposed behavior
commented-out-code: contiguous comment lines that parse as plausible code (assignments, calls, control flow, balanced brackets) above a configurable minimum line count. Conservative heuristics to avoid flagging prose, license headers, examples in docstrings, or directive comments.
redundant-comment (optional second rule / config-gated): single-line comments immediately above a statement that closely paraphrase the code (e.g. // increment counter above counter++). Lower confidence, advisory only.
Config: commentedOutCode.minLines, allow/ignore patterns; reuse the comment-scanning infrastructure already used by todo-comment.
Implementation surface
- New
src/detectors/commentedOutCode.ts reusing comment extraction patterns from src/detectors/todoComment.ts and src/utils/strings.ts.
- Optionally extend to Python/Kotlin/SFC via their existing comment-aware TODO detectors.
- Register in
src/detectors/index.ts / src/config/packs.ts; docs in docs/rules.md.
Acceptance criteria
Difficulty: medium.
Summary
Add a detector for commented-out code blocks and redundant "narration" comments — comments that restate what the next line literally does. Both are common AI-assistance artifacts and reinforce DebtLens's AI-era maintainability positioning.
Motivation
Commented-out code rots and confuses readers (version control already preserves history), and narrate-the-obvious comments add noise without intent. Neither is caught today, and both align with the product identity ("patterns that slip in when teams move fast with assistants").
Proposed behavior
commented-out-code: contiguous comment lines that parse as plausible code (assignments, calls, control flow, balanced brackets) above a configurable minimum line count. Conservative heuristics to avoid flagging prose, license headers, examples in docstrings, or directive comments.redundant-comment(optional second rule / config-gated): single-line comments immediately above a statement that closely paraphrase the code (e.g.// increment counterabovecounter++). Lower confidence, advisory only.Config:
commentedOutCode.minLines, allow/ignore patterns; reuse the comment-scanning infrastructure already used bytodo-comment.Implementation surface
src/detectors/commentedOutCode.tsreusing comment extraction patterns fromsrc/detectors/todoComment.tsandsrc/utils/strings.ts.src/detectors/index.ts/src/config/packs.ts; docs indocs/rules.md.Acceptance criteria
commentedOutCode.minLinesconfigurable.npm run test:allpasses.Difficulty: medium.