quality-gate

name

quality-gate

description

Use before finishing or opening a PR for a large / multi-file change to drizzle-cube, to ensure code quality does not regress. Runs `fallow audit` (complexity, duplication, dead code, circular deps scoped to the diff, reporting issues the change *introduces*) plus a `madge` circular-dependency snapshot. Report-only — it always exits 0 and never blocks; read the verdict as advice. Use when the user says "check quality", "make sure quality doesn't regress", "is this PR clean", or after a refactor touching many files.

Quality Regression Gate

A "don't make it worse" gate for drizzle-cube. The hard part of static analysis on a mature codebase is noise: there are already 373 high-complexity functions, 120 duplicate clone groups, and 20 circular dependencies. Reporting those on every change is useless.

The gate is built around one tool that solves this: fallow audit scopes analysis to the changed files and distinguishes findings the change introduced from findings it inherited. The default new-only gate fails only on introduced findings. That — and only that — is what "quality doesn't regress" means here. Inherited debt is reported for context but never blocks.

When to use

• After a refactor or feature touching several files, before committing / opening a PR.
• When the user asks to verify a change is clean or that quality hasn't regressed.
• NOT needed for one-line fixes or doc/test-only edits — the gate's value is on large diffs.

This gate is the static-analysis layer. It complements, and does not replace, npm run typecheck, npm run lint, and npm test. For a full pre-PR check, run those too.

Documentation Context

If the change affects public docs, examples, or agent-facing guidance, review https://www.drizzle-cube.dev/llms.txt to understand the published documentation surface before reporting quality findings. Do not run this quality gate solely because of a one-line or documentation-only edit; the guidance above still applies.

The one command that matters

npm run quality                 # fallow audit, base auto-detected (merge-base vs main/origin)

fallow audit auto-detects the base as the git merge-base against the branch's upstream or origin/main, so on a feature branch no argument is needed. To pin the base explicitly (pass args through npm with --):

npm run quality -- --base main
npm run quality -- --base "$(git merge-base main HEAD)"

Report-only: npm run quality always exits 0 — it never fails the build. The wrapper runs fallow audit and then forces a clean exit, so the gate is advisory, not blocking. You still read the verdict (pass / warn / fail) and the introduced findings from the report — treat a fail verdict as "worth a look / mention in the PR," not as a hard stop. The verdict ignores inherited findings — watch for the line audit gate excluded N inherited findings, which confirms pre-existing debt was not counted against the change.

Want it to block again? Drop the sh -c '… ; exit 0' wrapper in the quality script (package.json) back to plain fallow audit, or add --ci for a CI-friendly failing gate.

Reading the result precisely (JSON)

For an unambiguous machine-readable verdict, ask for JSON and read verdict + attribution.*_introduced:

npm run quality --silent -- --format json

{
  "verdict": "pass" | "warn" | "fail",
  "attribution": {
    "gate": "new-only",
    "dead_code_introduced": 0,      // <- these *_introduced fields drive the verdict
    "complexity_introduced": 0,
    "duplication_introduced": 0,
    "dead_code_inherited": 8,       // <- inherited: reported, never affects the verdict
    "complexity_inherited": 17,
    "duplication_inherited": 93
  }
}

A clean change has all three *_introduced fields at 0 and verdict: "pass".

Supplementary snapshot (informational — do NOT gate on it)

quality:health has no new-vs-inherited attribution, so on this codebase it always reports the full backlog. Use it to understand a finding or look at the whole picture — never as a pass/fail signal:

npm run quality:health      # fallow health: full complexity/duplication/maintainability score

Circular dependencies are covered by the gate itself — npm run quality (fallow audit) reports them under "Structure" with introduced-vs-inherited attribution, and quality:health lists them all. There is no separate circular-dependency script.

Occasional architecture check (madge, on demand)

fallow is the source of truth for circular dependencies and ignores import type cycles (not runtime hazards). On the rare occasion you want either (a) a visual dependency graph, or (b) to surface type-only import tangles that fallow deliberately hides, reach for madge via npx — it is intentionally NOT a pinned dependency or part of the gate:

npx madge --circular --extensions ts,tsx src              # includes type-only cycles (noisier)
npm run quality:graph                                      # writes dependency-graph.svg (needs graphviz)

This is an exploratory tool, not a regression check — its output has no introduced-vs-inherited attribution and will always show the full inherited backlog.

Acting on a fail verdict

The gate is report-only, so a fail verdict doesn't stop anything — but the introduced findings are still worth addressing (or calling out in the PR). fallow prints each with a file:line and a docs link. Typical fixes:

Introduced finding	What to do
Complexity (function over CRAP / cyclomatic / cognitive threshold)	Extract helpers; split the new function. Most drizzle-cube modules already follow a builder/planner split — mirror it.
Duplication (new clone group)	Hoist the shared logic. Note existing cross-engine clones in executors//adapters/ are inherited and expected — don't churn them.
Dead code (new unused export/file)	Delete it, or wire it up. Before deleting an "unused" export, confirm with npx fallow dead-code --trace <file>:<export> (a public API re-exported from an entry point can look unused).
Circular dependency	Break the cycle, usually by moving a shared type into a leaf types/* module.

False positives

If a finding is genuinely a false positive (e.g. a public export consumed only by package consumers), suppress it inline rather than restructuring:

// fallow-ignore-next-line complexity
// fallow-ignore-next-line unused-dependencies
// fallow-ignore-file circular-dependencies

Prefer fixing over suppressing. Suppress only with a one-line reason, and never suppress to get a green gate on a finding you actually introduced.

How it's wired

• fallow@2.95.0 and madge@8.0.0 are pinned devDependencies (package.json).
• Scripts: quality, quality:health, quality:graph.
• The quality script is sh -c 'fallow audit "$@"; exit 0' -- — it runs the full audit (forwarding any -- … args) but always exits 0, making the gate report-only / advisory. To restore a blocking gate, change it back to plain fallow audit (or fallow audit --ci).
• No fallow.config — defaults are used intentionally. The gate is new-only, so inherited debt (the 5 false-positive unused devDeps, 20 circular deps, existing duplication) is reported but never affects the verdict. Add a config only if you later want tunable thresholds or to exclude dist/generated dirs from duplication.