stopslop 0.1.1 → 0.2.0

package/README.md

@@ -1,329 +1,267 @@
-# stopslop
+# StopSlop
 
-[![slop](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/BaryshevRS/stopslop/main/stopslop-badge.json)](https://github.com/BaryshevRS/stopslop)
+[![AI slop](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/BaryshevRS/stopslop/main/stopslop-badge.json)](https://github.com/BaryshevRS/stopslop)
 
-> **0.1 preview.** The CLI and report formats are usable in CI; compatibility
-> tiers and the pre-1.0 change policy are documented in
-> [COMPATIBILITY.md](COMPATIBILITY.md). Requires Node.js 20.19+ or 22.12+.
+**Stop AI-generated code from becoming instant legacy.**
 
-**Slop is instant legacy.** A linter checks *how* code is written. **stopslop**
-checks whether the agent *overproduced junk* — over-complex functions, god
-modules/classes, and responsibilities dumped into one file. It measures how much
-uncleaned, unrefactored overproduction a repo carries — whether that took an
-agent a week or a team a decade. Zero style or type rules; it is not a competitor
-to ESLint/Biome/Oxlint.
+Coding agents are good at making code compile. They are also good at making too
+much of it: tangled functions, god files, copied blocks, dead exports, and entire
+features that pass their own tests but are never connected to the application.
+
+StopSlop catches that structural overproduction before it becomes permanent.
+It complements ESLint, Biome, and Oxlint rather than repeating their style and
+type rules.
 
 ```bash
 npx stopslop .
 ```
 
-Or install it in the project so CI uses the version pinned in your lockfile:
+It runs locally against JavaScript and TypeScript. No account. No source-code
+upload.
+
+> **0.1 preview:** Requires Node.js 20.19+ or 22.12+. Public surfaces and the
+> pre-1.0 change policy are documented in [COMPATIBILITY.md](COMPATIBILITY.md).
+
+## What it catches
+
+- **Tangled functions** using cognitive complexity from the SonarSource
+  specification.
+- **God classes and god modules** that mix unrelated responsibilities or have
+  grown into densely connected monoliths.
+- **Useful split boundaries** for god units when cohesion exposes responsibility
+  groups that should move together.
+- **Copy-pasted blocks**, with optional identifier normalization to catch copies
+  whose variables were renamed.
+- **Dead exports, dependencies, and files.**
+- **Orphan features** kept alive only by their own paired test but called by no
+  production code.
+- **Files exporting multiple classes**, a common sign that generation kept
+  appending instead of designing.
+
+Complexity and structural analysis are implemented by StopSlop. Clone detection
+uses [Clone Alert](https://www.npmjs.com/package/clone-alert); dead-code analysis
+uses [Knip](https://knip.dev). StopSlop detects code patterns, not whether a human
+or an AI wrote them.
+
+## Start with one command
+
+Run without installing:
 
 ```bash
-pnpm add --save-dev stopslop
-pnpm exec stopslop .
+npx stopslop .
 ```
 
-## What it finds
-
-- **Cognitive complexity** — functions that are hard to follow, scored by the
-  G. Ann Campbell / SonarSource specification.
-- **God class** — flagged on either of two axes: **dispersion** (methods split
-  into several unrelated responsibility groups — LCOM4 cohesion + hub removal,
-  with clean split boundaries) or **size/WMC** (a densely-connected monolith too
-  large to be one unit — the "everything is honestly connected but it's 2k lines"
-  class an agent produces, which cohesion can't and shouldn't split).
-- **God module** — the same, applied to a file's top-level definitions: a
-  "dump" of unrelated functions/classes/constants.
-- **Multiple exported classes** in one file.
-- **Clones** — copy-pasted blocks, *including ones whose variables were renamed*
-  (identifiers are normalized before matching). Engine:
-  [Clone Alert](https://www.npmjs.com/package/clone-alert).
-- **Dead code** — unused exports, unused dependencies, unreachable files. Engine:
-  [Knip](https://knip.dev), driven through its programmatic session API and
-  configured exclusively under `stopslop.json#knip`.
-- **Orphan features** — a function no production code calls, kept alive by
-  nothing but its own paired test. A feature that was generated together with
-  its test and never wired in: the test is green, the code does nothing. Read
-  off Knip's module graph; the finding names both halves to delete.
-
-The last two checks are other people's engines, and we say so in the output.
-Everything above them is ours.
-
-Each god finding lists the responsibility groups by member name — ready-made
-refactor boundaries.
+Or pin it in the project so local runs and CI use the same version:
 
-```
-  god class  Class ExpressAdapter: 41 methods across 4 unrelated responsibility groups (+27 standalone)
-      4 responsibility groups (suggested split boundaries):
-        1. close, closeOpenConnections, initHttpServer, trackOpenConnections
-        2. applyStreamHeaders, reply, setHeaderIfNotExists
-        3. set, setBaseViewsDir, setViewEngine
-        4. isMiddlewareApplied, registerParserMiddleware
+```bash
+npm install --save-dev stopslop
+npx stopslop .
 ```
 
-## Slop level
+The default report gives you the full repository score, the signal densities,
+and a grouped finding list. Add `--details` to show all clone locations and the
+suggested split boundaries for god units; use `--json` for every finding.
 
-One number, so a repo can be compared with itself over time and with other repos
-regardless of size — absolute counts just track how big the codebase is.
+```text
+  stopslop  27 files  4.3 KLOC  980ms
 
-```
-  slop level: moderate (49.4/100)
-  god units 0.00/KLOC  ·  complex fns 5.81/KLOC  ·  duplication 3.7%  ·  dead code 5.09/KLOC
+  slop level: low (22.3/100)  ·  worse than 49% of reference repos
+  god units 0.00/KLOC  ·  complex fns 4.42/KLOC  ·  duplication 0.8%
+  baseline: 23 accepted · 0 new
+
+  ✓ no new slop since baseline
 ```
 
-Every signal is a **density** (per KLOC; duplication is a share of lines). Each
-rises linearly from a *floor* (below it the density is the baseline of any
-living codebase — not slop) to a *budget* (the density at which the signal is as
-bad as it gets), then saturates, and is weighted:
+Exit codes are made for CI: `0` means clear, `1` means findings, and `2` means
+the analysis itself failed.
 
-```
-score = 100 · Σ wᵢ · sat(xᵢ) / Σ wᵢ        (i = enabled signals)
-sat(x) = clamp((x − floorᵢ) / (budgetᵢ − floorᵢ), 0, 1)
-```
+## Adopt an existing codebase without cleaning it first
 
-| signal | xᵢ | weight | floor | budget |
-|---|---|---|---|---|
-| god units | (god modules + god classes) / KLOC | 0.35 | 0 | 0.1 |
-| duplication | duplicated lines / total lines | 0.25 | 0.05 | 0.30 |
-| complexity | over-complex functions / KLOC | 0.20 | 0 | 4 |
-| dead code | (unused exports + deps + files) / KLOC | 0.20 | 0 | 4 |
+You do not need a perfect repository to start. Record today's findings once,
+commit them, and fail only when a change adds an unaccepted finding:
 
-Floors and budgets are calibrated on a benchmark of **41 mature TypeScript OSS
-repos (9.4 MLOC)** — angular, react, playwright, nextjs, svelte, vue and the
-like: a floor is what ordinary repos carry (~p25), a budget is past anything in
-the reference corpus (~max/p90).
-The report also anchors the number against that corpus directly:
+```bash
+# Record accepted legacy.
+npx stopslop . \
+  --baseline .stopslop-baseline.json \
+  --update-baseline
 
+git add .stopslop-baseline.json
+
+# Use the same file as the CI gate.
+npx stopslop . --baseline .stopslop-baseline.json
 ```
-  slop level: moderate (43.0/100)  ·  worse than 60% of reference repos
-```
 
-Bands: `clean` <10 · `low` <25 · `moderate` <50 · `high` <75 · `legacy-grade` ≥75.
-A disabled check leaves the formula entirely (it is not scored as clean).
-Weights, floors, and budgets are configurable — details and rationale in
-[docs/score.md](docs/score.md). **The densities are the facts; the score is an
-aggregate.**
+The baseline is a sorted, reviewable list of finding identities. Updating it is
+an explicit acceptance of debt, so baseline changes should be reviewed like
+source changes.
+
+The baseline never lowers the score. These three surfaces answer different
+questions:
+
+| Surface | What it tells you |
+| --- | --- |
+| Findings | What needs attention in this run |
+| Gate | Whether any finding remains unaccepted |
+| Score | How much slop the complete repository carries, including accepted legacy |
 
-## Slop badge
+A baselined run therefore remains honest: the report can show
+`moderate (43/100)`, `30 accepted`, and `0 new` while the gate is green.
 
-Show off a clean codebase with a [shields.io](https://shields.io/badges/endpoint-badge)
-badge. `--format shields` prints a shields **endpoint JSON** to stdout — host it
-(a committed file, a gist, anywhere reachable) and point shields at it:
+## Put the gate in your README
 
-```sh
-stopslop . --format shields > stopslop-badge.json
+The badge is deliberately binary. It is a public CI status, not a miniature
+analytics report.
+
+```text
+AI slop | clear       0 unaccepted findings
+AI slop | detected    1 or more unaccepted findings
 ```
 
+Generate the [Shields endpoint JSON](https://shields.io/badges/endpoint-badge)
+with the same baseline used by CI:
+
+```bash
+npx stopslop . \
+  --baseline .stopslop-baseline.json \
+  --format shields > stopslop-badge.json
+```
+
+Commit or publish `stopslop-badge.json`, then add this Markdown:
+
 ```md
-[![slop](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/OWNER/REPO/main/stopslop-badge.json)](https://github.com/OWNER/REPO)
+[![AI slop](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/OWNER/REPO/main/stopslop-badge.json)](https://github.com/OWNER/REPO)
 ```
 
-shields fetches the JSON and renders the badge, so it refreshes whenever you
-regenerate the file. The message is the level and score; the color comes from a
-fixed scale, tuned to reward near-zero slop:
-
-| Result | Color | |
-| --- | --- | --- |
-| **`0 slop`** | 🟢 bright green | the flex — nothing to clean up |
-| **`clean` <10** | 🟢 bright green | clean |
-| **`low` <25** | 🟢 green | a little debt |
-| **`moderate` <50** | 🟡 yellow | has debt |
-| **`high` <75** | 🟠 orange | needs attention |
-| **`legacy-grade` ≥75** | 🔴 red | reads like accumulated legacy |
-
-`--format shields` always exits `0` (it is badge generation, not a gate), so a CI
-step can regenerate it without failing the build. A score built from a subset of
-the signals (a check was disabled or bailed out) is inflated, so its message is
-marked with a `*` — run the full set for a comparable badge. Regenerate it in CI
-to keep it fresh:
+Without `--baseline` or `--base`, `clear` requires zero findings across the
+entire scan. With a baseline, it requires zero findings outside the committed
+baseline. The full score is still present in the terminal and JSON reports.
+
+`--format shields` exits `0` for both `clear` and `detected` so a publishing step
+can write the current state. An incomplete or failed analysis exits `2` before
+emitting a badge.
+
+## Gate pull requests
+
+Use a committed baseline for a stable, explicitly reviewed allowlist:
 
 ```yaml
-      - run: npx stopslop . --format shields > stopslop-badge.json
-      # then commit the file (or push it to a gist) so shields serves the latest value
+- name: Reject new AI slop
+  run: npx stopslop . --baseline .stopslop-baseline.json
 ```
 
-## Usage
+Or compare the working tree directly with the target branch and keep no baseline
+file:
 
-```
-stopslop [path]            analyze a directory or file (default: .)
-  --format <fmt>           text (default) · json · sarif · shields (badge JSON)
-  --json                   alias for --format json (stable, versioned schema)
-  --details, -d            show cluster composition, hubs, all clone sites
-  --fast                   AST checks only: skip clones and dead code
-  --config <file>          path to a stopslop.json
-  --base <ref>             gate only on findings absent from this Git revision
-  --baseline <file>        gate only on findings not in this baseline
-  --update-baseline        write current findings to --baseline and exit 0
+```bash
+npx stopslop . --base origin/main
 ```
 
-Exit codes: `0` clean · `1` findings · `2` error.
+`--base` analyzes both revisions and reports findings that exist only in the
+current tree. CI must check out enough Git history to resolve the base revision.
+The command never switches your branch or changes the index.
 
-### For an agent loop
+For GitHub Code Scanning, emit SARIF before propagating the gate failure:
 
 ```bash
-stopslop --json > slop.json   # feed to the agent: clusters are the split boundaries
+npx stopslop . --base origin/main --format sarif > stopslop.sarif
 ```
 
-### Git-base gate
+## Send the findings back to the agent
 
-For pull requests, `--base <ref>` analyzes both the current working tree and the
-given Git revision, then reports only findings absent from the base:
+The JSON report is stable and versioned. Feed it into the next coding-agent turn
+instead of paraphrasing terminal output:
 
-```sh
-stopslop . --base origin/main
-stopslop . --base origin/main --format sarif > stopslop.sarif
+```bash
+npx stopslop . --json > slop-report.json
 ```
 
-The current tree is analyzed as-is, including uncommitted changes. The base is
-checked out detached into a fresh directory under the operating system's temp
-directory. StopSlop links the installed dependency context (`node_modules` and
-supported generated directories) into that checkout, analyzes the same project
-subdirectory on both sides, and removes the temporary worktree in `finally`.
-It never switches the user's branch or edits the index or working files.
+God-unit findings include member groups that serve as concrete refactoring
+boundaries. Clone findings include every occurrence. Baseline and Git-base runs
+retain the complete score while returning only new findings.
 
-This is an identity gate, not a metric diff: an existing finding with the same
-StopSlop fingerprint is accepted; a fingerprint seen only in the current tree is
-new. The full current slop score remains unchanged. `--base` is mutually
-exclusive with `--baseline` and `--update-baseline`.
+## Score: trend the repository, do not gate on the number
 
-`--format sarif` emits SARIF 2.1.0 for GitHub Code Scanning. It has the normal
-gate exit codes (`0` clean, `1` findings, `2` error), so upload the report before
-re-failing the job:
+The `0..100` slop score normalizes findings by KLOC, so a repository can be
+compared with itself over time instead of merely growing a larger raw count. It
+combines four densities: god units, duplication, over-complex functions, and
+dead code.
 
-```yaml
-name: stopslop
-on: pull_request
-
-permissions:
-  contents: read
-  security-events: write
-
-jobs:
-  stopslop:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v6
-        with:
-          fetch-depth: 0
-      - id: scan
-        continue-on-error: true
-        run: npx stopslop . --base "origin/${{ github.base_ref }}" --format sarif > stopslop.sarif
-      - if: always() && steps.scan.outcome != 'cancelled'
-        uses: github/codeql-action/upload-sarif@v4
-        with:
-          sarif_file: stopslop.sarif
-          category: stopslop
-      - if: steps.scan.outcome == 'failure'
-        run: exit 1
-```
+Floors and budgets are anchored in a benchmark of 41 mature TypeScript
+repositories totaling 9.4 MLOC. The weights remain an explicit judgement call,
+not a scientific truth. That is why the binary gate uses findings rather than an
+arbitrary score cutoff.
 
-## Baseline (adopting an existing project)
+The complete formula, calibration rationale, limitations, and corpus comparison
+are in [docs/score.md](docs/score.md) and
+[docs/thresholds.md](docs/thresholds.md).
 
-A mature or already-sloppy repo can light up red on day one. A **baseline** lets
-you accept today's findings as legacy and gate CI only on what is added
-afterwards — the honest answer to "this codebase is old and complex, but I don't
-want the agent making it *worse*."
+## CLI
 
-```sh
-# 1. Record today's findings (writes the file, exits 0)
-stopslop . --baseline .stopslop-baseline.json --update-baseline
+```text
+stopslop [path]            analyze a directory or file (default: .)
 
-# 2. In CI: fail only on findings not in the baseline
-stopslop . --baseline .stopslop-baseline.json
+  --format <fmt>           text (default) · json · sarif · shields
+  --json                   alias for --format json
+  --details, -d            show split groups, hubs, and all clone locations
+  --fast                   skip clone and dead-code analysis
+  --config <file>          use a specific stopslop.json
+  --base <ref>             gate on findings absent from a Git revision
+  --baseline <file>        gate on findings absent from a baseline file
+  --update-baseline        replace the baseline with current findings
+  --help, -h               show help
 ```
 
-The baseline is a small, sorted JSON file you commit and review in pull requests.
-A finding's identity is `kind + file + symbol` — no line numbers, no messages — so
-a baselined god class stays accepted as it grows, and the file produces a stable,
-churn-free diff. Clones key on their content fingerprint alone, so they stay
-suppressed even when moved between files. Re-run `--update-baseline` to re-adopt
-after an intentional change.
-
-Use this committed file when you want a deliberately reviewed, stable allowlist.
-Use `--base` when the target branch itself should be the source of truth and no
-baseline artifact should be maintained. They share fingerprints but are separate
-CLI modes; one does not read or rewrite the other's state.
-
-**The baseline never touches the slop score or the badge.** The score is the
-honest state of the repo ("how much uncleaned code is here"); the baseline is
-only a CI gate ("don't add more"). A gated run reports the new findings and its
-score line reads e.g. `moderate (43.0/100)` with `baseline: 30 accepted · 1 new`
-below it — the number stays truthful while CI fails only on the one new finding.
+Invalid configuration, no supported source files, and hard analysis errors exit
+with code `2` before StopSlop emits a report, badge, or baseline.
 
-## Config (`stopslop.json`)
+## Configuration
 
-Every metric is configurable — thresholds, and each check can be turned off with
-`false`. All fields are optional and merged over the defaults.
+StopSlop works without configuration. To tune a check, add `stopslop.json`:
 
 ```json
 {
   "$schema": "https://unpkg.com/stopslop/schema.json",
-  "cognitiveComplexity": 15,
-  "godModule": { "minMembers": 15, "minClusters": 3, "minComplexity": 150, "sizeMembers": 37, "sizeComplexity": 350 },
-  "godClass": { "minMembers": 12, "minClusters": 3, "minComplexity": 90, "sizeMembers": 30, "sizeComplexity": 200 },
-  "multipleExportedClasses": { "maxPerFile": 1 },
-  "duplicates": { "minTokens": 50, "minLines": 5, "ignoreIdentifiers": true, "ignoreLiterals": false },
-  "deadCode": { "exports": true, "dependencies": true, "files": true, "production": false },
-  "knip": {
-    "workspaces": {
-      ".": { "entry": ["src/index.ts"] },
-      "packages/*": { "entry": ["src/index.ts"], "project": ["src/**/*.ts"] }
-    }
+  "cognitiveComplexity": 20,
+  "duplicates": {
+    "minTokens": 100,
+    "minLines": 10,
+    "ignoreIdentifiers": true
   },
-  "score": { "weights": { "god": 0.35 }, "budgets": { "duplication": 0.3 }, "floors": { "duplication": 0.05 } },
-  "hubFanInRatio": 0.5,
   "ignore": ["**/*.generated.ts"]
 }
 ```
 
-| key | what it tunes |
-|---|---|
-| `cognitiveComplexity` | report functions above this score (or `false` to disable) |
-| `godClass` / `godModule` | `min*` = dispersion axis (unrelated groups); `size*` = size/WMC axis (a monolith too big even if fully connected); or `false` |
-| `multipleExportedClasses` | `maxPerFile` classes per file before flagging; or `false` |
-| `duplicates` | clone size floors and token normalization; or `false` |
-| `deadCode` | which Knip issue classes to report; or `false` |
-| `knip` | complete JSON-compatible Knip config, including `workspaces` |
-| `score` | slop-level weights, floors, and budgets |
-| `hubFanInRatio` | fan-in fraction that marks a shared "hub" member for removal |
-| `ignore` | extra exclude globs on top of the built-ins |
-
-Set a check to `false` to disable it, e.g. `"godModule": false`.
-
-`stopslop.json` is the only Knip configuration source. StopSlop does not load or
-execute `knip.json`, `.knip.json`, or `knip.config.*`; `package.json#knip` is
-discarded and never merged with `knip`. The published `schema.json` provides editor
-completion and validation for both StopSlop fields and the installed Knip
-configuration surface. StopSlop deliberately has no config generator or init
-wizard; project-aware generation belongs to separate tooling.
-
-For a single-package project, put `entry` and `project` directly under `knip`.
-For a monorepo, put them under `knip.workspaces`: Knip intentionally ignores
-top-level `entry` and `project` when multiple workspaces are present.
-
-**Full reference with every field, defaults, and examples:
-[docs/configuration.md](docs/configuration.md).** Defaults are calibrated on a
-22-repo TypeScript corpus ([docs/thresholds.md](docs/thresholds.md)) and marked
-*preliminary* in output until validated further.
-
-## How it works & why the numbers
-
-Architecture, literature references, and which parts are our heuristics:
-[ARCH.md](ARCH.md). Implementation plan: [PLAN.md](PLAN.md).
-
-Under the hood: **complexity and god module/class are ours**; clones are
-[Clone Alert](https://www.npmjs.com/package/clone-alert) and dead code is
-[Knip](https://knip.dev).
+Every field is optional. Set a check to `false` to disable it. The published
+schema provides editor completion and rejects unknown or invalid properties.
+
+See [docs/configuration.md](docs/configuration.md) for every field, default, and
+Knip workspace example. See [stopslop.example.json](stopslop.example.json) for a
+complete configuration.
+
+## Design and limitations
+
+- StopSlop supports `.js`, `.jsx`, `.mjs`, `.cjs`, `.ts`, and `.tsx` source.
+- Tests, generated code, build output, dependencies, and common framework output
+  directories are excluded by default.
+- A high score does not prove poor engineering, and a low score does not prove
+  correctness. StopSlop measures structural overproduction, not total quality.
+- Dead-code accuracy depends on Knip knowing the project's entry points.
+- A baseline accepts finding identities. If an accepted function becomes more
+  complex without changing identity, the score rises but the gate stays clear.
+
+Architecture, research references, and the boundary between published methods
+and StopSlop heuristics are documented in [ARCH.md](ARCH.md).
 
 ## Development
 
 ```bash
 pnpm install
 pnpm test
+pnpm typecheck
 pnpm build
-pnpm test:package       # install and execute the packed npm artifact
-pnpm release:check      # complete pre-publish gate
-pnpm schema:generate      # refresh schema.json after a Knip/config change
-pnpm calibrate            # regenerate docs/thresholds.md from a corpus
+pnpm test:package
+pnpm release:check
 ```
+
+MIT licensed. See [LICENSE](LICENSE).

package/dist/cli.js

@@ -51,7 +51,7 @@ function renderTerminal(result, details) {
 /** The headline: one comparable number, with the densities it came from. */
 function renderScore(result) {
 	const { score, level, densities, signalCount, totalSignals, percentile } = result.slop;
-	const paint = LEVEL_COLOR$1[level];
+	const paint = LEVEL_COLOR[level];
 	const partial = signalCount < totalSignals ? pc.yellow(` — ${signalCount}/${totalSignals} signals, see notes`) : "";
 	const anchor = percentile !== void 0 ? pc.dim(`  ·  worse than ${percentile}% of reference repos`) : "";
 	const head = `  slop level: ${paint(pc.bold(level))} ${pc.dim(`(${score.toFixed(1)}/100)`)}${anchor}${partial}`;
@@ -62,7 +62,7 @@ function renderScore(result) {
 	if (densities.deadCode !== void 0) parts.push(`dead code ${densities.deadCode.toFixed(2)}/KLOC`);
 	return parts.length > 0 ? head + "\n  " + pc.dim(parts.join("  ·  ")) : head;
 }
-const LEVEL_COLOR$1 = {
+const LEVEL_COLOR = {
 	clean: pc.green,
 	low: pc.green,
 	moderate: pc.yellow,
@@ -290,24 +290,21 @@ function isLine(value) {
 }
 //#endregion
 //#region src/report/badge.ts
-const LEVEL_COLOR = {
-	clean: "brightgreen",
-	low: "green",
-	moderate: "yellow",
-	high: "orange",
-	"legacy-grade": "red"
-};
-/** shields.io endpoint JSON for a slop badge. */
+/** shields.io endpoint JSON for the AI-slop gate. */
 function toBadge(result) {
-	const { score, level, signalCount, totalSignals } = result.slop;
-	const partial = signalCount < totalSignals ? "*" : "";
-	const payload = {
+	const clear = result.findings.length === 0;
+	return `${JSON.stringify({
 		schemaVersion: 1,
-		label: "slop",
-		message: score === 0 ? "0 slop" : `${level} (${score.toFixed(0)}/100)${partial}`,
-		color: LEVEL_COLOR[level]
-	};
-	return `${JSON.stringify(payload, null, 2)}\n`;
+		label: "AI slop",
+		message: clear ? "clear" : "detected",
+		color: clear ? "brightgreen" : "red"
+	}, null, 2)}\n`;
+}
+//#endregion
+//#region src/analysis-completeness.ts
+function assertAnalysisComplete(result) {
+	if (result.fileCount === 0) throw new Error("analysis incomplete: no supported source files found");
+	if (result.errors.length > 0) throw new Error(`analysis incomplete: ${result.errors.join("; ")}`);
 }
 //#endregion
 //#region src/cli.ts
@@ -389,6 +386,7 @@ async function main() {
 			config.deadCode.enabled = false;
 		}
 		const result = args.base ? await analyzeGitBase(args.path, args.base, config) : await analyze(args.path, config);
+		assertAnalysisComplete(result);
 		if (args.updateBaseline) {
 			writeBaseline(args.baseline, result.findings);
 			process.stderr.write(`stopslop: baseline written to ${args.baseline} (${result.findings.length} findings accepted)\n`);
@@ -406,7 +404,7 @@ async function main() {
 		if (args.format === "json") process.stdout.write(toJson(reported) + "\n");
 		else if (args.format === "sarif") process.stdout.write(toSarif(reported));
 		else if (args.format === "shields") {
-			process.stdout.write(toBadge(result));
+			process.stdout.write(toBadge(reported));
 			process.exit(0);
 		} else process.stdout.write(renderTerminal(reported, args.details) + "\n");
 		process.exit(reported.findings.length > 0 ? 1 : 0);

package/dist/index.d.ts

@@ -13,7 +13,7 @@ interface Finding {
   message: string;
   /** Structured payload for --json consumers and --details rendering. */
   data?: Record<string, unknown>;
-  /** True while thresholds are pre-calibration defaults. */
+  /** Compatibility marker for reports produced with provisional thresholds. */
   preliminary?: boolean;
 }
 /** A parsed source file with everything analyzers need, produced once per file. */
@@ -145,7 +145,7 @@ interface ResolvedConfig {
   /** fan-in fraction above which a member is treated as a hub (0..1). */
   hubFanInRatio: number;
   ignore: string[];
-  /** Whether current thresholds are pre-calibration defaults. */
+  /** Whether current thresholds are provisional. False for the calibrated defaults. */
   preliminary: boolean;
 }
 //#endregion
@@ -184,14 +184,13 @@ interface ScoreInput {
   config: ResolvedConfig;
 }
 declare function computeScore(input: ScoreInput): SlopScore;
-/** Bands are labels for the score, not extra thresholds — same preliminary caveat. */
+/** Bands are labels for the score, not extra detection thresholds. */
 declare function levelFor(score: number): SlopLevel;
 //#endregion
 //#region src/config.d.ts
 /**
- * Default thresholds. First-pass calibrated on the 22-repo corpus (see
- * docs/thresholds.md); still flagged PRELIMINARY until validated against the
- * Stage-4 victim repo. The god gates are a conjunction (members AND clusters AND
+ * Default thresholds calibrated on the 22-repo corpus (see
+ * docs/thresholds.md). The god gates are a conjunction (members AND clusters AND
  * complexity), so `minMembers` is kept sensitive — precision comes from the
  * cluster + complexity requirement, not from a high member floor.
  * Full reference: docs/configuration.md.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "stopslop",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "Detects AI-agent slop that linters miss: over-complex functions, god modules/classes, dumped responsibilities.",
   "type": "module",
   "license": "MIT",
@@ -47,18 +47,26 @@
     "calibrate": "tsx scripts/calibrate.ts",
     "typecheck": "tsc --noEmit",
     "schema:generate": "tsx scripts/generate-config-schema.ts",
-    "schema:check": "tsx scripts/generate-config-schema.ts --check"
+    "schema:check": "tsx scripts/generate-config-schema.ts --check",
+    "commitlint": "commitlint",
+    "prepare": "simple-git-hooks 1>&2"
+  },
+  "simple-git-hooks": {
+    "commit-msg": "pnpm exec commitlint --edit \"$1\""
   },
   "dependencies": {
     "clone-alert": "^1.1.3",
-    "knip": "^6.26.0",
+    "knip": "6.31.0",
     "oxc-parser": "^0.139.0",
     "picocolors": "^1.1.1"
   },
   "devDependencies": {
     "@arethetypeswrong/core": "^0.18.1",
+    "@commitlint/cli": "^21.1.0",
+    "@commitlint/config-conventional": "^21.1.0",
     "@types/node": "^22.10.0",
     "publint": "^0.3.8",
+    "simple-git-hooks": "^2.13.1",
     "tsdown": "^0.21.10",
     "tsx": "^4.19.0",
     "typescript": "^5.7.0",

package/schema.json

@@ -466,6 +466,9 @@
             "catalog": {
               "$ref": "#/definitions/knip/definitions/ruleValue"
             },
+            "catalogReferences": {
+              "$ref": "#/definitions/knip/definitions/ruleValue"
+            },
             "cycles": {
               "$ref": "#/definitions/knip/definitions/ruleValue"
             },
@@ -639,6 +642,7 @@
               "enumMembers",
               "namespaceMembers",
               "catalog",
+              "catalogReferences",
               "cycles"
             ]
           }
@@ -1007,6 +1011,10 @@
               "title": "markdownlint plugin configuration (https://knip.dev/reference/plugins/markdownlint)",
               "$ref": "#/definitions/knip/definitions/plugin"
             },
+            "marko": {
+              "title": "marko plugin configuration (https://knip.dev/reference/plugins/marko)",
+              "$ref": "#/definitions/knip/definitions/plugin"
+            },
             "mdx": {
               "title": "mdx plugin configuration (https://knip.dev/reference/plugins/mdx)",
               "$ref": "#/definitions/knip/definitions/plugin"
@@ -1107,6 +1115,10 @@
               "title": "openapi-ts plugin configuration (https://knip.dev/reference/plugins/openapi-ts)",
               "$ref": "#/definitions/knip/definitions/plugin"
             },
+            "openclaw": {
+              "title": "openclaw plugin configuration (https://knip.dev/reference/plugins/openclaw)",
+              "$ref": "#/definitions/knip/definitions/plugin"
+            },
             "orval": {
               "title": "orval plugin configuration (https://knip.dev/reference/plugins/orval)",
               "$ref": "#/definitions/knip/definitions/plugin"
@@ -1323,6 +1335,10 @@
               "title": "tauri plugin configuration (https://knip.dev/reference/plugins/tauri)",
               "$ref": "#/definitions/knip/definitions/plugin"
             },
+            "temporal": {
+              "title": "temporal plugin configuration (https://knip.dev/reference/plugins/temporal)",
+              "$ref": "#/definitions/knip/definitions/plugin"
+            },
             "travis": {
               "title": "travis plugin configuration (https://knip.dev/reference/plugins/travis)",
               "$ref": "#/definitions/knip/definitions/plugin"