RatchetQA

RatchetQA is a high-performance quality gate for technical debt metrics. It freezes the first measured state as a baseline, then fails CI when metrics get worse beyond the configured acceptable threshold. The baseline is the historical floor: future changes should keep quality equal or improve it, and tolerated regressions must stay inside the metric threshold.

Collectors run in real time when supported tools are installed in the target project:

• Typecheck: runs the package check script by default.
• Coverage: runs the package coverage script by default, then parses coverage/coverage-summary.json.
• Linter: runs the package lint script by default and expects JSON output or a configured JSON report.
• Duplication: runs the jscpd API.
• Oversized files: walks the filesystem directly.

If a tool is not installed, RatchetQA falls back to configured JSON report paths where applicable.

npm install --save-dev ratchetqa
npx ratchetqa init
npx ratchetqa check

Commands:

• ratchetqa init: starts an interactive guide that lets you choose test, coverage, lint, typecheck, config, and baseline setup; selected packages are installed along the way.
• ratchetqa init --install: installs default test/lint tools when missing, then configures and writes the baseline without prompts.
• ratchetqa init --skip-baseline: configures the project without writing ratchet-baseline.json.
• ratchetqa baseline: scans the project and writes ratchet-baseline.json; fails if a baseline already exists.
• ratchetqa baseline --update: advances an existing baseline to the current metrics only when no metric regressed.
• ratchetqa baseline --force: exceptional recovery only, such as replacing a corrupt baseline or migrating an incompatible schema.
• ratchetqa check: scans the project, compares against the baseline, writes ratchet-report.json, prints a Markdown table, and exits 1 only after all collectors complete if any metric regressed.

If ratchetqa check fails, fix the regression instead of replacing the baseline: add tests for coverage drops, remove duplicated code, split oversized files, or resolve lint findings.

ratchet.config.json is the only configuration file. ratchet-baseline.json records only schemaVersion, generatedAt, and the collector metric snapshot.

Optional ratchet.config.json:

{
  "$schema": "./node_modules/ratchetqa/ratchet.schema.json",
  "ignore": ["node_modules", "dist", "coverage"],
  "oversizedFiles": {
    "maxLines": 1000,
    "includeExtensions": [".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs"]
  },
  "coverage": {
    "summaryPaths": ["coverage/coverage-summary.json", "coverage-summary.json"],
    "script": "coverage",
    "timeoutMs": 120000,
    "minimumPct": 75
  },
  "linter": {
    "reportPaths": ["eslint-report.json", "biome-report.json"],
    "script": "lint",
    "timeoutMs": 120000,
    "maximumErrors": 0,
    "maximumWarnings": 0,
    "maximumTotal": 0
  },
  "typecheck": {
    "script": "check",
    "timeoutMs": 120000,
    "maximumErrors": 0
  },
  "limits": {
    "maxFiles": 20000,
    "maxDepth": 50,
    "maxFileBytes": 10485760
  },
  "duplication": {
    "paths": ["."],
    "maximumPct": 0,
    "maximumFragments": 0
  }
}

The $schema key enables editor hover documentation, autocomplete, and validation in JSON-aware editors. ratchetqa init adds it automatically for new config files.

Metric threshold values are stored in ratchet-baseline.json and ratchet-report.json. For lower-is-worse metrics such as coverage, the threshold is the minimum acceptable value. For higher-is-worse metrics such as linter findings, typecheck errors, oversized files, and duplication, the threshold is the maximum acceptable value.

Oversized files are tracked per file. A baseline records each file currently above oversizedFiles.maxLines; those files may shrink but not grow. Files below maxLines can grow while they remain under the limit, but a new file crossing the limit fails the check.

License

RatchetQA is released under the MIT License. See LICENSE.md.