Skip to content

Add composite god-file / kitchen-sink module detector #261

Description

@cursor

Summary

Add a composite "god file" / kitchen-sink module detector that flags modules doing too much by combining multiple existing signals — large size, many exports, and high responsibility spread — into one finding.

Motivation

DebtLens already detects individual symptoms (large-function, api-surface-sprawl, barrel-file). But a module can pass each individual threshold while still being an unmaintainable catch-all. A composite rule that fires when several signals co-occur catches the "everything lives here" file that single-axis rules miss.

Proposed behavior

  • god-file: fires when a module crosses a combination of thresholds, e.g. total lines + export count + number of top-level functions/classes + distinct concern indicators (mixed I/O, UI, and domain logic).
  • Confidence scales with how many independent axes are exceeded.
  • Suggestion: split by responsibility, extract cohesive submodules, define a clear public entrypoint.

Config: godFile.maxLines, godFile.maxExports, godFile.maxTopLevelDecls, and the minimum number of axes required to fire.

Implementation surface

  • New src/detectors/godFile.ts that reuses metrics computed by apiSurfaceSprawl.ts and the size logic in largeFunction.ts / src/utils/lines.ts.
  • Register in src/detectors/index.ts; include in core pack.
  • Docs in docs/rules.md; fixtures: a true god file vs a large-but-cohesive module (must not fire on the latter).

Acceptance criteria

  • Fires only when multiple axes are exceeded (configurable minimum).
  • Does not fire on large-but-cohesive single-purpose modules.
  • Confidence reflects number of axes exceeded.
  • Documented + npm run test:all passes.

Difficulty: medium.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions