Add stale feature-flag debt detector

[cursor]

Summary

Add a stale feature-flag debt detector that flags feature flags which appear to be permanently on/off or are no longer referenced, so dead conditional paths get cleaned up.

type: rfc — flag conventions vary widely; design the configuration/detection contract before implementation.

Motivation

Feature flags accumulate and become debt: flags hardcoded to true/false, flags defined but never read, or both branches kept long after a rollout completes. This dead conditional complexity is exactly the kind of maintainability rot DebtLens targets, and it complements the incoming AI-workflow-instruction-drift pack.

Proposed behavior (to refine in RFC)

• Configurable flag access patterns, e.g. flags(...), isEnabled("..."), useFlag("..."), or constant maps — there is no universal convention, so detection is config-driven.
• stale-feature-flag signals:
  • flag constant/key assigned a literal true/false and used only in if/ternary branches (always-on/always-off).
  • flag key defined in a known registry but never referenced.
  • both branches of a flag check kept where one is unreachable given a literal value.
• Suggestion: remove the flag check and the dead branch once rollout is complete.

Implementation surface

• New src/detectors/featureFlagDebt.ts; configuration under a featureFlags block in src/config/schema.ts (access patterns, registry path/glob).
• Reuse identifier/literal helpers in src/utils/identifiers.ts and src/utils/ast.ts.
• Register in src/detectors/index.ts; likely its own opt-in pack in src/config/packs.ts.
• Docs + RFC notes in docs/rules.md / a short RFC section.

Acceptance criteria

• RFC defines the configurable access-pattern/registry contract and non-goals.
• Detects always-on/always-off flags and unreferenced flags with config-driven patterns.
• Conservative defaults; opt-in pack to avoid noise.
• Documented + npm run test:all passes.

Difficulty: large.