Skip to content

Add per-area debt budgets / SLOs with CI gating #252

Description

@cursor

Summary

Add per-area debt budgets / SLOs so teams can cap how much debt a directory or package is allowed to carry and gate CI when an area regresses past its budget.

Motivation

Baselines freeze all current debt globally; quality gates apply repo-wide severity policy. Neither lets a team say "the new src/payments module must stay under 20 issues" or "src/legacy may not get worse." Per-area budgets give teams a burn-down target and protect freshly-cleaned areas from backsliding.

Proposed behavior

  • New config block:
    {
      "budgets": {
        "src/payments": { "maxIssues": 20, "maxHigh": 0 },
        "src/legacy":   { "maxIssues": 250 }
      }
    }
  • During scan, aggregate issues per matching path glob and compare against the budget.
  • A budget breach fails the gate (respecting existing --gate / exit-code policy) with a clear per-area message and remaining headroom.
  • debtlens scan --budget-report prints a per-area table (used / budget / headroom) without failing.

Implementation surface

  • Extend src/config/schema.ts, src/config/loadConfig.ts, src/config/validateConfig.ts, and src/config/mergeConfig.ts for the budgets block; reuse src/config/workspaces.ts glob matching.
  • New src/core/budgets.ts to evaluate budgets against ScanResult; integrate with src/core/gatePresets.ts / src/core/severity.ts exit-code policy.
  • Reporter support for the budget table.
  • Schema drift test (tests/config/schema.test.ts) + budget evaluation tests.

Acceptance criteria

  • budgets validated by schema and merged with documented precedence.
  • Breaches fail the gate with per-area detail; --budget-report is non-failing.
  • Glob matching consistent with existing package/workspace resolution.
  • Docs + CHANGELOG updated.
  • 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