stopslop 0.1.2 → 1.0.0

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,15 @@ 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
@@ -413,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/docs/ci-and-automation.md

@@ -0,0 +1,100 @@
+# CI and automation
+
+StopSlop has three stable exit codes: `0` means the gate is clear, `1` means
+findings were detected, and `2` means analysis or configuration failed. Pin the
+package version in `devDependencies` so local runs and CI use the same rules.
+
+## Reject new findings with a committed baseline
+
+Create the baseline once and review it like source code:
+
+```bash
+npx stopslop . \
+  --baseline .stopslop-baseline.json \
+  --update-baseline
+git add .stopslop-baseline.json
+```
+
+Then use the same file in CI:
+
+```yaml
+- name: Reject new AI slop
+  run: npx stopslop . --baseline .stopslop-baseline.json
+```
+
+The baseline suppresses accepted findings from the gate. It never removes them
+from the full-repository score.
+
+## Compare a pull request with its Git base
+
+This mode needs the base revision to exist locally:
+
+```yaml
+- uses: actions/checkout@v7
+  with:
+    fetch-depth: 0
+
+- name: Reject AI slop added by this change
+  run: npx stopslop . --base origin/main
+```
+
+`--base` and `--baseline` are alternative gates. Do not pass them together.
+
+## Publish SARIF without hiding the gate failure
+
+The scan may exit `1` after writing valid SARIF. Let the upload step run, then
+propagate the original result. The workflow or job needs permission to publish
+code-scanning results:
+
+```yaml
+permissions:
+  contents: read
+  security-events: write
+```
+
+Then add the scan, upload, and enforcement steps:
+
+```yaml
+- name: Scan with StopSlop
+  id: stopslop
+  continue-on-error: true
+  run: npx stopslop . --base origin/main --format sarif > stopslop.sarif
+
+- name: Upload StopSlop SARIF
+  if: always() && hashFiles('stopslop.sarif') != ''
+  uses: github/codeql-action/upload-sarif@v4
+  with:
+    sarif_file: stopslop.sarif
+
+- name: Enforce StopSlop gate
+  if: steps.stopslop.outcome == 'failure'
+  run: exit 1
+```
+
+An exit code of `2` does not emit a report, preventing an incomplete analysis
+from being published as a trustworthy result.
+
+## Give structured findings to a coding agent
+
+```bash
+npx stopslop . --format json > slop-report.json
+```
+
+The JSON schema version is included in the document. Findings carry stable
+`kind`, `file`, `symbol`, `line`, `message`, and optional structured `data`
+fields. God-unit data includes responsibility groups; duplicate-code data
+includes clone locations.
+
+## Generate a binary Shields badge
+
+Use the same baseline as CI:
+
+```bash
+npx stopslop . \
+  --baseline .stopslop-baseline.json \
+  --format shields > stopslop-badge.json
+```
+
+The badge says `AI slop | clear` when the gate has no unaccepted findings and
+`AI slop | detected` otherwise. Accepted legacy remains visible in the terminal
+and JSON score.

package/docs/configuration.md

@@ -0,0 +1,252 @@
+# Configuration
+
+stopslop reads `stopslop.json` from the analyzed directory (or `--config <path>`).
+Every field is optional and merged over the defaults, so a config only needs the
+knobs you want to change. Defaults are calibrated on a 22-repo TypeScript corpus
+(see [thresholds.md](thresholds.md)).
+
+The CLI validates StopSlop-owned fields at runtime as well as publishing the
+schema: unknown properties, wrong types, and out-of-range values are errors
+rather than silently ignored configuration.
+
+## Full example (all defaults)
+
+```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": false, "ignoreLiterals": false },
+  "deadCode": { "exports": true, "dependencies": true, "files": true, "orphans": true, "production": false },
+  "knip": {
+    "workspaces": {
+      ".": { "entry": ["src/index.ts"] },
+      "packages/*": { "entry": ["src/index.ts"], "project": ["src/**/*.ts"] }
+    }
+  },
+  "score": {
+    "weights": { "god": 0.35, "duplication": 0.25, "complexity": 0.2, "deadCode": 0.2 },
+    "budgets": { "god": 0.1, "duplication": 0.3, "complexity": 4, "deadCode": 4 },
+    "floors": { "god": 0, "duplication": 0.05, "complexity": 0, "deadCode": 0 }
+  },
+  "hubFanInRatio": 0.5,
+  "ignore": []
+}
+```
+
+## Disabling a check
+
+Set any check to `false` to turn it off entirely:
+
+```json
+{
+  "godModule": false,
+  "multipleExportedClasses": false
+}
+```
+
+## Metrics
+
+### `cognitiveComplexity` — number | false
+
+Functions whose cognitive complexity (Campbell / SonarSource spec) is **strictly
+above** this value are reported. Default **15** (the Sonar community default; on
+the corpus it sits between count p95 ≈ 13 and p99 ≈ 38). Lower = stricter.
+
+```json
+{ "cognitiveComplexity": 20 }
+```
+
+### `godClass` / `godModule` — object | false
+
+A class (or a module's top-level definitions) is flagged on **either** of two
+axes — see [ARCH.md](../ARCH.md) for the reasoning.
+
+| field | meaning | default (class / module) |
+|---|---|---|
+| `minMembers` | dispersion axis: minimum methods / top-level definitions | 12 / 15 |
+| `minClusters` | dispersion axis: minimum **substantive** responsibility groups (≥2 members) | 3 / 3 |
+| `minComplexity` | dispersion axis: minimum total (Σ) cognitive complexity | 90 / 150 |
+| `sizeMembers` | size/WMC axis: method count that alone signals a monolith | 30 / 37 |
+| `sizeComplexity` | size/WMC axis: total complexity (WMC) that alone signals a monolith | 200 / 350 |
+
+- **Dispersion** fires when `members ≥ minMembers AND groups ≥ minClusters AND
+  Σcomplexity ≥ minComplexity` — a class doing several unrelated things, with
+  clean split boundaries in the report.
+- **Size (WMC)** fires when `members ≥ sizeMembers AND Σcomplexity ≥
+  sizeComplexity` — a densely-connected monolith too large to be one unit, even
+  if fully cohesive. Reported honestly as "no automatic split boundaries".
+
+Raise `size*` for fewer, higher-confidence size findings; raise `minClusters` to
+demand more distinct responsibilities before flagging dispersion.
+
+```json
+{
+  "godClass": { "sizeMembers": 45, "sizeComplexity": 300 },
+  "godModule": false
+}
+```
+
+### `multipleExportedClasses` — object | false
+
+Flags files exporting **more than** `maxPerFile` classes. Default `maxPerFile`
+**1** (i.e. flag 2+). Informational severity.
+
+```json
+{ "multipleExportedClasses": { "maxPerFile": 2 } }
+```
+
+### `duplicates` — object | false
+
+Copy-paste detection, powered by [Clone Alert](https://www.npmjs.com/package/clone-alert).
+Only the files stopslop discovered are fed to it, so the ignore rules above apply
+here too.
+
+| field | meaning | default |
+|---|---|---|
+| `minTokens` | minimum duplicated token span reported as a clone | 50 |
+| `minLines` | minimum physical lines a clone must span (its tightest occurrence) | 5 |
+| `ignoreIdentifiers` | normalize identifier names before matching (Type-2 clones) | `false` |
+| `ignoreLiterals` | normalize literal values before matching | `false` |
+
+The default is **exact matching (Type-1 clones)** — the reported percentage is
+real copy-paste. Set `ignoreIdentifiers: true` to also catch Type-2 clones (an
+agent copy-pasting a block and renaming the variables); the cost is that
+structurally-similar boilerplate matches too, which inflates the duplication
+ratio on component libraries by several points. `minLines` keeps dense
+one-liners (config tables, long template strings) from matching on token count
+alone; turn it up to only see substantial clones.
+
+```json
+{ "duplicates": { "minTokens": 100, "minLines": 10, "ignoreIdentifiers": true } }
+```
+
+### `deadCode` — object | false
+
+Unused code, powered by [Knip](https://knip.dev) via its programmatic session API
+(no CLI spawn). This section controls which Knip findings StopSlop reports and
+whether Knip runs in production mode. It is StopSlop policy, not Knip's own
+configuration.
+
+| field | meaning | default |
+|---|---|---|
+| `exports` | report unused exports and unused exported types (warn) | `true` |
+| `dependencies` | report unused (dev)dependencies from package.json (warn) | `true` |
+| `files` | report files unreachable from any entry point (info) | `true` |
+| `orphans` | report functions kept alive by nothing but their own paired test (warn) | `true` |
+| `production` | analyze as production-only: usage from tests no longer counts | `false` |
+
+Unused files are **info**, not warn, on purpose: they depend on entry-point
+detection, which misfires on projects with unconventional entries. Verify before
+deleting — or configure `entry` under `stopslop.json#knip`.
+
+An **orphan feature** is a function or class no production code calls, imported
+by exactly one file: its own paired test. The trace of a generated feature that
+was never wired in — a plain unused export has an innocent explanation ready,
+this one has almost none. The finding names both halves to delete, source symbol
+and test file, because removing either alone breaks the build or leaves a green
+test standing over nothing. It is reported and deliberately never scored: the
+point is to get the pair deleted, and a weight in the number removes no code.
+
+Symbols still used inside their own file are excluded, as are shared test
+helpers, stories, and non-callable constants — every one of them a way for a
+live symbol to look like an orphan. Orphans need Knip to see the test files at
+all, which means either a test-runner plugin it recognises or `entry` patterns
+covering the tests.
+
+```json
+{ "deadCode": { "files": false, "production": true } }
+```
+
+### `knip` — object
+
+The complete JSON-compatible [Knip configuration](https://knip.dev/reference/configuration).
+This is the **only** Knip configuration StopSlop uses. It never reads, merges,
+or executes project `knip.json`, `.knip.json`, or `knip.config.*` files. The
+root `package.json` is still project metadata, but its `knip` field is discarded
+and never merged. Move any settings StopSlop should use into this property.
+
+```json
+{
+  "knip": {
+    "ignoreDependencies": ["optional-adapter"],
+    "workspaces": {
+      ".": { "entry": ["src/index.ts"] },
+      "packages/*": { "entry": ["src/index.ts"], "project": ["src/**/*.ts"] },
+      "packages/cli": { "entry": ["src/cli.ts"] }
+    }
+  }
+}
+```
+
+Workspace keys and overrides follow Knip unchanged: `.` configures the root,
+glob keys select groups of packages, and a more specific key can override a
+group. In a detected monorepo without `knip.workspaces`, findings are still
+shown but excluded from the dead-code score because entry-point detection is
+not trustworthy enough to grade the repository.
+
+In a single-package project, `entry` and `project` belong directly under
+`knip`. In a monorepo they belong under `knip.workspaces`; Knip ignores the
+top-level forms once multiple workspaces are present.
+
+One Knip default is changed: StopSlop sets `ignoreExportsUsedInFile` to `true`.
+Knip otherwise reports an export nothing imports even when the symbol is used
+inside its own file — a `export` keyword wider than it needs to be, which no
+behaviour depends on. That is a style nit rather than the structural waste
+StopSlop reports. Set it back to `false` under `knip` to get Knip's own default;
+the granular per-symbol-type form works as documented upstream.
+
+The package ships `schema.json`. Add
+`"$schema": "https://unpkg.com/stopslop/schema.json"` for editor completion,
+field descriptions, and validation. StopSlop consumes configuration only; it
+does not infer or generate project settings. That project inspection is kept as
+a boundary for future external tooling (such as an MCP server).
+
+### `score` — object
+
+Weights, floors, and budgets of the slop level. A signal contributes nothing
+below its floor, rises linearly, and saturates at its budget. Full formula and
+rationale (all anchors measured on a 41-repo benchmark of mature TypeScript
+OSS): [score.md](score.md).
+
+```json
+{
+  "score": {
+    "weights": { "god": 0.35, "duplication": 0.25, "complexity": 0.2, "deadCode": 0.2 },
+    "budgets": { "god": 0.1, "duplication": 0.3, "complexity": 4, "deadCode": 4 },
+    "floors": { "god": 0, "duplication": 0.05, "complexity": 0, "deadCode": 0 }
+  }
+}
+```
+
+Weights need not sum to 1 — the score divides by the sum of the weights that
+actually ran. Disabling a check removes its signal from the formula entirely
+rather than scoring it as clean. The "worse than N% of reference repos" anchor
+is recomputed with your weights/floors/budgets, so a custom config re-ranks the
+corpus with the same yardstick it applies to your repo.
+
+## Engine knobs
+
+### `hubFanInRatio` — number (0..1)
+
+A member referenced by more than this fraction of the unit's methods is treated
+as a "hub" (shared glue), removed from the cohesion graph, and the responsibility
+groups are recomputed — so a class held together by one shared field still splits
+into its real parts. Default **0.5**. Lower = more aggressive splitting.
+
+### `ignore` — string[]
+
+Extra glob patterns (matched against POSIX-relative paths) to exclude, on top of
+the built-in excludes (`node_modules`, `dist`/`build`, tests, fixtures, `.d.ts`,
+minified/bundled files, and generator subtrees such as openapi-generator).
+
+```json
+{ "ignore": ["**/*.generated.ts", "src/legacy/**"] }
+```
+
+## Reference
+
+The JSON report (`--json`) echoes the fully-resolved config under `thresholds`,
+so you can confirm exactly what ran.

package/docs/node-api.md

@@ -0,0 +1,114 @@
+# Node.js API
+
+StopSlop ships a typed ESM API for tools that need findings and metrics in
+memory instead of a CLI report. It requires Node.js `^20.19.0 || >=22.12.0`.
+
+## Analyze with defaults
+
+Resolve configuration before calling `analyze`:
+
+```ts
+import { analyze, resolveConfig } from 'stopslop';
+
+const result = await analyze(process.cwd(), resolveConfig(undefined));
+
+for (const finding of result.findings) {
+  console.log(finding.kind, finding.file, finding.line, finding.message);
+}
+
+console.log({
+  score: result.slop.score,
+  level: result.slop.level,
+  errors: result.errors,
+  notes: result.notes,
+});
+```
+
+`findings` contains the issues that should fail the current gate. `slop` always
+describes the complete analyzed repository. Check `errors` before trusting a
+result; `notes` explains non-fatal skips by project-level engines.
+
+## Load `stopslop.json`
+
+`loadConfig` reads `stopslop.json` from the analysis root and returns the
+resolved defaults plus overrides:
+
+```ts
+import { analyze, loadConfig } from 'stopslop';
+
+const root = process.cwd();
+const result = await analyze(root, loadConfig(root));
+```
+
+To build configuration in code, pass the user-facing shape to `resolveConfig`:
+
+```ts
+import { analyze, resolveConfig, type StopSlopConfig } from 'stopslop';
+
+const input: StopSlopConfig = {
+  cognitiveComplexity: 20,
+  duplicates: { minTokens: 100, minLines: 10 },
+  deadCode: { files: false },
+};
+
+const result = await analyze(process.cwd(), resolveConfig(input));
+```
+
+Unknown fields and invalid values throw instead of being ignored.
+
+## Compare with a Git revision
+
+`analyzeGitBase` returns only findings absent from the selected revision while
+retaining the current repository's complete score:
+
+```ts
+import { analyzeGitBase, loadConfig } from 'stopslop';
+
+const root = process.cwd();
+const result = await analyzeGitBase(root, 'origin/main', loadConfig(root));
+
+if (result.errors.length > 0) process.exitCode = 2;
+else if (result.findings.length > 0) process.exitCode = 1;
+```
+
+The ref must resolve in the local Git repository. StopSlop creates a temporary
+detached worktree; it does not switch the current branch or modify the index.
+
+## Extend the analyzer list
+
+Pass a third argument to append a custom analyzer to the built-in set:
+
+```ts
+import {
+  analyze,
+  defaultAnalyzers,
+  resolveConfig,
+  type Analyzer,
+} from 'stopslop';
+
+const custom: Analyzer = {
+  name: 'project-policy',
+  analyzeFile(file) {
+    return file.source.includes('DO NOT SHIP')
+      ? [{
+          kind: 'unused-file',
+          file: file.relPath,
+          symbol: 'DO NOT SHIP',
+          line: 1,
+          severity: 'warn',
+          message: 'Unresolved project marker',
+        }]
+      : [];
+  },
+};
+
+const result = await analyze(
+  process.cwd(),
+  resolveConfig(undefined),
+  [...defaultAnalyzers(), custom],
+);
+```
+
+Custom analyzers currently return the published `Finding` union, so use an
+existing finding kind for integrations. Treat that surface as pre-1.0; see the
+[compatibility policy](../COMPATIBILITY.md).

package/docs/score.md

@@ -0,0 +1,133 @@
+# Slop level: the formula
+
+The slop level is one number in `0..100` plus a band label. It exists so that a
+repo can be compared **with itself over time** and **with other repos**, which
+raw finding counts cannot do: a 200 KLOC monorepo will always "win" on absolute
+counts without being any sloppier per line written.
+
+Nothing here is a black box, and nothing here is science. The **densities are
+the facts**; the score is a weighted aggregate over them, with heuristic weights
+and budgets that you can change.
+
+## The formula
+
+```
+score = 100 · Σ wᵢ · sat(xᵢ) / Σ wᵢ
+sat(x) = clamp((x − floorᵢ) / (budgetᵢ − floorᵢ), 0, 1)
+```
+
+where `i` ranges over the **enabled** signals:
+
+| signal | xᵢ (density) | weight wᵢ | floor | budget |
+|---|---|---|---|---|
+| `god` | (god modules + god classes) / KLOC | 0.35 | 0 | 0.1 |
+| `duplication` | duplicated lines / total lines (0..1) | 0.25 | 0.05 | 0.30 |
+| `complexity` | over-complex functions / KLOC | 0.20 | 0 | 4 |
+| `deadCode` | (unused exports + deps) / KLOC | 0.20 | 0 | 4 |
+
+Below the floor a signal contributes nothing — that density is the baseline of
+any living codebase, not slop. At the budget the contribution saturates.
+
+Only `warn`-severity findings feed the score. `info` findings — unused *files*,
+which hang entirely on Knip's entry-point detection — are reported but never
+scored: a misdetected entry point must not outweigh a real god class.
+
+Bands: `clean` <10 · `low` <25 · `moderate` <50 · `high` <75 · `legacy-grade` ≥75.
+The top band is `legacy-grade`, not "severe": a high score means the code reads
+like accumulated legacy — true whether a team wrote it over a decade or an agent
+produced it last week. It is a description, not a verdict on the engineers.
+
+Three properties are deliberate:
+
+- **Size independence.** Every signal is a rate, not a count. Four god classes in
+  20 KLOC score exactly like one in 5 KLOC.
+- **Saturation.** `min(1, …)` caps each signal at its budget: a repo with 100 god
+  modules is not "20× worse" than one with 5 — it is simply maxed out on that
+  axis, and the other axes still matter. Without the cap, one pathological file
+  would drown out everything else.
+- **A check that did not run leaves the formula.** If you turn off `deadCode` — or
+  if Knip bails out because the project's dependencies are not installed, or the
+  project is a monorepo without `stopslop.json#knip.workspaces` (where Knip's
+  entry-point detection produces a landslide of false "unused") — its weight drops out of the
+  denominator instead of contributing zero. Not measuring something must never
+  read as a clean bill of health. The terminal report shows only the signals
+  that were actually measured, and says in a note why one is missing.
+
+`multiple-exported-classes` is reported but not scored: it is a structural hint,
+not a quantity of slop, and it correlates with the god-module signal already.
+
+## Where the numbers come from
+
+Honestly: the **weights are a judgement call**; the **floors and budgets are
+measured**, not invented. Every non-zero anchor comes from a 41-repo / 9.4 MLOC
+benchmark run over mature TypeScript OSS (angular, react, playwright, nextjs,
+svelte, vue-core, nest, vite, material-ui and the like — the corpus ships in
+`src/corpus.ts`), by one rule: a *floor* is what ordinary repos carry (~p25), a
+*budget* is "past anything in the reference corpus" (~max/p90). The calibrated
+defaults remain configurable (`score.weights`, `score.budgets`, `score.floors`).
+
+- **Weights** encode what we claim slop *is*. Misplaced structure (god units) and
+  copy-paste are the expensive kinds — they are what an agent produces when it
+  keeps appending instead of refactoring, and they are what a human has to undo
+  by hand. A single hairy function or a stale export is cheaper to fix, so
+  complexity and dead code weigh less. `god` (0.35) > `duplication` (0.25) >
+  `complexity` = `deadCode` (0.20).
+- **`god` budget = 0.1/KLOC** — corpus median 0.013, half the repos at exactly 0,
+  worst repo (playwright) at 0.071. No floor: a single god unit is already slop.
+- **`duplication` floor = 5%, budget = 30%** — corpus p25 ≈ 5% (unavoidable
+  boilerplate of a living TS codebase), p90 ≈ 31% (mantine). The first-guess
+  budget (10%, the jscpd convention) sat *below the corpus median of ~13%*: the
+  signal saturated on ¾ of the corpus, became a constant +25 points for nearly
+  everyone, and compressed all 42 benchmark scores into 27..56 — a scale with
+  only two live bands. Measured beats conventional.
+- **`complexity` budget = 4/KLOC** — the detection threshold is already the count
+  p95 of the calibration corpus ([thresholds.md](thresholds.md)); the corpus
+  maximum of repos crossing it is 3.31/KLOC (svelte — a compiler, i.e. honestly
+  complex). 4 = past anything in the corpus.
+- **`deadCode` budget = 4/KLOC** — ≈ p75 of the sub-corpus where dead code was
+  actually measurable; one unused export/dependency every 250 lines means the
+  project has stopped removing what it stopped using. This is the noisiest
+  signal (it leans on Knip config quality, and a library's public API reads as
+  "unused exports"), which is why it carries the smallest weight and never
+  enters the corpus percentile below.
+
+## "Worse than N% of reference repos"
+
+Alongside the absolute score, the report anchors the repo against the reference
+corpus: the share of the 41 benchmark repos with a strictly lower **core score**
+— the score computed from the three signals measured identically everywhere
+(god, duplication, complexity; dead code is excluded as infrastructure-dependent).
+The comparison uses *your* weights/floors/budgets, so a custom config re-ranks
+the corpus with the same yardstick it applies to your repo. It appears only when
+all three core signals were measured (`--fast` has no percentile).
+
+This is context, not a second verdict: "43/100, worse than 60% of reference
+repos" tells you where the number sits among codebases nobody calls slop.
+
+## What the score means — and what it does *not*
+
+The score is **"how much uncleaned, suspicious code is left"**, not a verdict on
+engineering quality. The intended reading:
+
+- Clean it up and the number goes to zero: no god units, no duplication, no dead
+  code → 0, whether the code was written by a human or an agent. Fix the god
+  class, deduplicate, remove dead exports — the score follows.
+- Its primary use is comparing a repo **with itself over time** (did the agent's
+  last week of commits push it up?). Cross-repo comparison is meaningful but
+  needs the caveat below.
+- A genuinely complex domain scores high honestly: playwright tops the corpus
+  ranking because it really does carry the corpus's highest god-unit density
+  (0.071/KLOC) and near-maximal density of over-complex functions. The score
+  reports that; it does not know (or claim to know) that the complexity is
+  well-earned. High score = "a lot here would need justification", not "bad
+  engineers".
+
+Other non-goals:
+
+- `deadCode` anchors are the weakest: the signal depends on Knip configuration
+  and misreads a library's public API as unused exports (see above).
+- It does not weigh a finding by how bad it is individually (a complexity-80
+  function counts the same as a complexity-16 one). Severity lives in the
+  findings, not the score.
+- It is not a quality score. Clean code with zero slop signals can still be bad
+  code — stopslop only claims to measure *overproduction*.