Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
97 lines (77 loc) · 3.93 KB

CONTRIBUTING.md

File metadata and controls

97 lines (77 loc) · 3.93 KB
Raw

Contributing to DebtLens

DebtLens is a maintainability scanner with optional rule packs. A good rule should make maintainers say, "yes, I would want to review that before merging."

Read docs/rule-packs.md for how core rules, framework packs, and reporting/CI fit together before proposing new detectors.

Local setup

npm install
npm run typecheck       # type-check src
npm run typecheck:tests # type-check the test sources too
npm test                # run the node:test suite (via tsx)
npm run test:all        # all of the above
npm run build
node dist/cli/index.js scan examples/react --min-severity info

For a guided first contribution, start with docs/contributing-first-pr.md.

Contribution workflow

  1. Pick a layer and issue from docs/rule-packs.md and docs/good-first-issues.md, or the contributor roadmap project.
  2. Comment before starting medium, large, or RFC-style work so maintainers can help shape the approach.
  3. Keep the PR focused on one issue or one tightly related batch.
  4. Add or update tests for behavior changes.
  5. Update docs when CLI flags, config, reporters, rules, packs, or Action behavior changes.
  6. Before opening the PR, run:
npm run typecheck
npm run typecheck:tests
npm test
npm run build

Rule review bar

Maintainers should be able to review a detector without guessing its policy. A rule PR should include:

  • one true-positive fixture,
  • one near-miss or false-positive fixture that must stay quiet,
  • documented default thresholds and severity,
  • confidence scoring rationale,
  • reviewable evidence and a concrete suggestion,
  • docs in docs/rules.md and docs/rule-packs.md,
  • schema/template updates when new config keys are added,
  • calibration fixture updates when existing showcase or quality bounds change.

For language or framework packs that need a new parser, start with an RFC-style doc before adding runtime dependencies. See docs/language-pack-rfc.md for the Python and Vue parser evaluation pattern.

Adding a rule

  1. Decide whether the rule belongs in the core pack or a framework pack (see docs/rule-packs.md).
  2. State the false-positive bar before coding: what common pattern should not fire?
  3. Add a detector in src/detectors/<ruleName>.ts.
  4. Export it from src/detectors/index.ts.
  5. Add default thresholds in src/config/defaults.ts if needed.
  6. Document the rule in docs/rules.md and note its pack in docs/rule-packs.md when adding a new id.
  7. Add a test in tests/detectors/<ruleName>.test.ts using the runDetector helper — include a true positive and a near-miss that must not fire.
  8. Add or update a calibration fixture when the rule changes cross-rule finding volume.
  9. Explain the confidence score and include reviewable evidence/suggestions.
  10. Check whether the rule affects baselines, SARIF, JSON schema examples, or showcase docs.
  11. If the rule will ship through a plugin or organization policy package, document the package install and CI path (see docs/policy-packages.md).

A detector must return issues with:

  • clear message
  • severity
  • confidence (0–1; see docs/rules.md for how scores are interpreted and assigned per rule)
  • file and line
  • evidence
  • suggestion

Avoid rules that claim to detect whether code was generated by AI. DebtLens focuses on maintainability outcomes, not authorship.

Adding a reporter

Reporters should render from the stable ScanResult object. If you add a reporter or change public output:

  1. Add focused reporter tests.
  2. Update CLI format parsing if there is a new --format value.
  3. Update README and Action docs when the format is user-facing.
  4. Keep existing reporter output stable unless the issue explicitly calls for a change.