stopslop 0.2.0 → 1.1.0

package/docs/configuration.md

@@ -0,0 +1,257 @@
+# 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.
+
+Every run lists what Knip finds missing from this configuration under **config
+hints** (`configHints` in `--format json`): a workspace it never reached, an
+entry pattern that matched nothing, and how many unused files each accounts
+for. While Knip reports the project or a workspace as unconfigured, dead-code
+findings are shown but excluded from the score — without entry points, live
+files come back unreachable.
+
+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,115 @@
+# 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, and
+`configHints` lists what Knip reports as missing from `stopslop.json#knip`.
+
+## 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. That surface is experimental and may
+change in a minor release; see the [compatibility policy](../COMPATIBILITY.md).

package/docs/score.md

@@ -0,0 +1,134 @@
+# 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
+  Knip reports the run as unconfigured (its `top-level-unconfigured` or
+  `workspace-unconfigured` config hint: more files unreachable than anything but
+  missing entry points explains) — 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*.

package/docs/thresholds.md

@@ -0,0 +1,105 @@
+# Threshold calibration
+
+Two lenses on the same corpus:
+
+- **Count percentiles** — each entity counts once. "pXX = N" means XX% of
+  entities score ≤ N. This is what we use for defaults: a god finding should be
+  the worst ~1–5% of entities.
+- **LOC-weighted percentiles** — the Alves/Ypma/Visser (ICSM 2010) methodology:
+  each entity weighted by LOC, so "pXX = N" means XX% of *code volume* sits in
+  entities ≤ N. Kept for reference; it skews high because large entities are
+  both more complex and hold more volume.
+
+Corpus: 22 TypeScript repositories, 65,817 analyzed files (tests, fixtures,
+generated and bundled code excluded). The per-repository counts are listed
+below.
+
+## Count percentiles (basis for defaults)
+
+### Function
+| metric | n | p50 | p75 | p90 | p95 | p99 |
+|---|---|---|---|---|---|---|
+| cognitive complexity | 108102 | 0 | 2 | 7 | 13 | 38 |
+
+### Class (≥3 methods)
+| metric | n | p50 | p75 | p90 | p95 | p99 |
+|---|---|---|---|---|---|---|
+| methods | 2940 | 6 | 12 | 23 | 32 | 64 |
+| responsibility groups (≥2) | 2940 | 1 | 1 | 2 | 2 | 4 |
+| Σ cognitive complexity | 2940 | 8 | 24 | 58 | 93 | 207 |
+
+### Module (≥5 top-level fns)
+| metric | n | p50 | p75 | p90 | p95 | p99 |
+|---|---|---|---|---|---|---|
+| top-level definitions | 2819 | 8 | 11 | 16 | 22 | 37 |
+| responsibility groups (≥2) | 2819 | 1 | 1 | 2 | 2 | 3 |
+| Σ cognitive complexity | 2819 | 21 | 54 | 109 | 167 | 354 |
+
+## LOC-weighted percentiles (Alves, reference)
+
+### Function
+| metric | n | p50 | p75 | p90 | p95 | p99 |
+|---|---|---|---|---|---|---|
+| cognitive complexity | 108102 | 4 | 16 | 45 | 95 | 309 |
+
+### Class (≥3 methods)
+| metric | n | p50 | p75 | p90 | p95 | p99 |
+|---|---|---|---|---|---|---|
+| methods | 2940 | 15 | 30 | 57 | 74 | 111 |
+| responsibility groups (≥2) | 2940 | 1 | 1 | 2 | 3 | 5 |
+| Σ cognitive complexity | 2940 | 41 | 104 | 205 | 341 | 825 |
+
+### Module (≥5 top-level fns)
+| metric | n | p50 | p75 | p90 | p95 | p99 |
+|---|---|---|---|---|---|---|
+| top-level definitions | 2819 | 10 | 17 | 29 | 38 | 72 |
+| responsibility groups (≥2) | 2819 | 1 | 1 | 2 | 2 | 4 |
+| Σ cognitive complexity | 2819 | 51 | 128 | 280 | 455 | 1175 |
+
+## Final defaults
+
+A god finding is rare by construction, but the detector does not compare each
+metric with an independent p95 cutoff. It has two alternative axes:
+
+- **dispersion** requires members **and** responsibility groups **and** total
+  complexity together, so its member floor can stay sensitive;
+- **size/WMC** requires both a high member count and high total complexity, even
+  when the unit is cohesive.
+
+| gate | members | groups | Σ complexity | final setting |
+|---|---:|---:|---:|---|
+| cognitive complexity | — | — | 15 | `cognitiveComplexity: 15` |
+| class dispersion | 12 | 3 | 90 | `godClass: 12 / 3 / 90` |
+| class size/WMC | 30 | — | 200 | `godClass: 30 / 200` |
+| module dispersion | 15 | 3 | 150 | `godModule: 15 / 3 / 150` |
+| module size/WMC | 37 | — | 350 | `godModule: 37 / 350` |
+
+The size thresholds sit near the count p95–p99 tail. On the dispersion axis,
+three substantive groups are already rare (between class p95 and p99; module
+p99), and the conjunction with complexity supplies the precision. Raising the
+member floor itself to p95 would make the conjunction unnecessarily blind to
+smaller units that clearly contain three unrelated responsibilities.
+
+## Per-repo file counts
+- angular: 1971 files
+- angular-components: 1971 files
+- chakra-ui: 2359 files
+- create-react-app: 122 files
+- gatsby: 3086 files
+- ionic-framework: 508 files
+- material-ui: 26447 files
+- nest: 1306 files
+- nextjs: 4498 files
+- ng-bootstrap: 527 files
+- ng-bootstrap-fresh: 527 files
+- nx: 3330 files
+- playwright: 788 files
+- primeng: 2743 files
+- react: 1711 files
+- react-bootstrap: 440 files
+- remix: 805 files
+- shadcn-ui: 3473 files
+- storybook: 2617 files
+- svelte: 2299 files
+- taiga-ui: 2770 files
+- tanstack-table: 1519 files

package/llms.txt

@@ -0,0 +1,27 @@
+# StopSlop
+
+> Static analysis and CI gating for structural AI code slop in JavaScript and TypeScript. StopSlop finds cognitive complexity, god classes and modules, duplicate code, dead code, orphan features, and responsibility boundaries. It reports code patterns, not authorship.
+
+Run without installing: `npx stopslop .`. Exit codes are `0` for a clear gate, `1` for detected findings, and `2` for an analysis error. Requires Node.js 20.19+ or 22.12+.
+
+Dead-code settings live under `knip` in `stopslop.json` — a project's own `knip.json` or `package.json#knip` is never read. Nothing needs to be written up front: the run prints `config hints` from Knip naming the workspace or entry point that is missing, and dead code stays out of the score until they are resolved.
+
+## Start here
+
+- [Overview, installation, CLI and badge](https://raw.githubusercontent.com/BaryshevRS/stopslop/main/README.md)
+- [Configuration reference](https://raw.githubusercontent.com/BaryshevRS/stopslop/main/docs/configuration.md)
+- [CI baselines, Git comparison, SARIF and agent reports](https://raw.githubusercontent.com/BaryshevRS/stopslop/main/docs/ci-and-automation.md)
+- [Typed Node.js API](https://raw.githubusercontent.com/BaryshevRS/stopslop/main/docs/node-api.md)
+
+## How it works
+
+- [Score formula and interpretation](https://raw.githubusercontent.com/BaryshevRS/stopslop/main/docs/score.md)
+- [Default thresholds and calibration](https://raw.githubusercontent.com/BaryshevRS/stopslop/main/docs/thresholds.md)
+- [Architecture and methodology](https://raw.githubusercontent.com/BaryshevRS/stopslop/main/ARCH.md)
+- [Compatibility policy](https://raw.githubusercontent.com/BaryshevRS/stopslop/main/COMPATIBILITY.md)
+
+## Package
+
+- [npm package](https://www.npmjs.com/package/stopslop)
+- [JSON Schema](https://unpkg.com/stopslop/schema.json)
+- [GitHub repository](https://github.com/BaryshevRS/stopslop)