stopslop 0.2.0 → 1.0.0

package/COMPATIBILITY.md

@@ -0,0 +1,26 @@
+# Compatibility
+
+Last updated: 0.2.0 (2026-08-05)
+
+StopSlop is pre-1.0. Public surfaces are usable, but none are declared stable
+yet. Breaking preview changes require a minor release and are called out in the
+changelog. Experimental surfaces may change in any release.
+
+| Surface | Tier | Compatibility policy |
+| --- | --- | --- |
+| CLI flags and exit codes | Preview | Existing flags and exit meanings are preserved within a minor line. |
+| Versioned JSON report | Preview | Breaking payload changes increment `schemaVersion`. |
+| SARIF 2.1.0 report | Preview | New rules and optional properties may be added; existing required fields remain compatible. |
+| `stopslop.json` schema | Preview | Existing valid configuration remains valid within a minor line. |
+| Programmatic Node.js API | Experimental | Exported functions and TypeScript types may change before 1.0. |
+
+## Runtime support
+
+- Node.js 20.19+, 22.12+, and 24.
+- ESM only.
+- Git-base gating requires the `git` executable and a non-shallow checkout that
+  contains the requested base revision.
+
+## Deprecations
+
+None.

package/README.md

@@ -1,6 +1,7 @@
 # StopSlop
 
-[![AI 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) [![clone-alert: 0 clones](https://img.shields.io/badge/clone--alert-0%20clones-brightgreen)](https://github.com/BaryshevRS/clone-alert) [![CI](https://github.com/BaryshevRS/stopslop/actions/workflows/ci.yml/badge.svg)](https://github.com/BaryshevRS/stopslop/actions/workflows/ci.yml) [![npm version](https://img.shields.io/npm/v/stopslop.svg)](https://www.npmjs.com/package/stopslop)
+<!-- clone-alert badge: pnpm exec clone-alert --minimum-tokens 100 --files src --format shields --no-fail-on-violation -->
 
 **Stop AI-generated code from becoming instant legacy.**
 
@@ -8,9 +9,10 @@ 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.
+StopSlop is a static analyzer for JavaScript and TypeScript codebases under
+heavy AI-agent change. It catches that structural overproduction before it
+becomes permanent. It complements ESLint, Biome, Oxlint, SonarQube, and
+SonarCloud rather than repeating their style and type rules.
 
 ```bash
 npx stopslop .
@@ -19,9 +21,6 @@ npx stopslop .
 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
@@ -56,6 +55,14 @@ Or pin it in the project so local runs and CI use the same version:
 ```bash
 npm install --save-dev stopslop
 npx stopslop .
+
+# pnpm
+pnpm add -D stopslop
+pnpm exec stopslop .
+
+# Yarn
+yarn add --dev stopslop
+yarn stopslop .
 ```
 
 The default report gives you the full repository score, the signal densities,
@@ -130,9 +137,12 @@ npx stopslop . \
 Commit or publish `stopslop-badge.json`, then add this Markdown:
 
 ```md
-[![AI 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/BaryshevRS/stopslop)
 ```
 
+Replace `OWNER/REPO` in the image URL with your repository. Keep the outer link
+unchanged: clicking the badge takes readers to StopSlop.
+
 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.
@@ -167,6 +177,9 @@ For GitHub Code Scanning, emit SARIF before propagating the gate failure:
 npx stopslop . --base origin/main --format sarif > stopslop.sarif
 ```
 
+See [CI and automation](docs/ci-and-automation.md) for a complete workflow that
+uploads SARIF and still preserves StopSlop's exit code.
+
 ## Send the findings back to the agent
 
 The JSON report is stable and versioned. Feed it into the next coding-agent turn
@@ -239,6 +252,24 @@ 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.
 
+## Node.js API
+
+StopSlop ships ESM JavaScript and TypeScript declarations for programmatic use:
+
+```ts
+import { analyze, loadConfig } from 'stopslop';
+
+const root = process.cwd();
+const result = await analyze(root, loadConfig(root));
+
+console.log(result.slop.score, result.findings);
+```
+
+The API also exports the resolved defaults, scoring helpers, baseline helpers,
+and report types. See the [Node.js API guide](docs/node-api.md) for Git-base
+analysis, typed configuration, result semantics, and custom analyzers. The API
+is experimental before 1.0; see [COMPATIBILITY.md](COMPATIBILITY.md).
+
 ## Design and limitations
 
 - StopSlop supports `.js`, `.jsx`, `.mjs`, `.cjs`, `.ts`, and `.tsx` source.
@@ -253,12 +284,45 @@ complete configuration.
 Architecture, research references, and the boundary between published methods
 and StopSlop heuristics are documented in [ARCH.md](ARCH.md).
 
+## FAQ
+
+### Is StopSlop an AI-generated code detector?
+
+No. It does not guess who wrote a line of code. It finds structural waste that
+coding agents often produce—duplicate blocks, over-complex functions, god
+classes and modules, dead code, and orphan features—and reports the same issue
+when a human wrote it.
+
+### How is StopSlop different from ESLint, SonarQube, SonarCloud, or Knip?
+
+ESLint and similar linters focus on local rules. SonarQube and SonarCloud are
+broad quality platforms. Knip specializes in unused code and dependencies.
+StopSlop is a local, zero-account AI code quality gate focused on structural
+overproduction. It combines several signals into one report and keeps accepted
+legacy visible through its score while blocking only new findings through a
+baseline or Git comparison. Knip and
+[Clone Alert](https://www.npmjs.com/package/clone-alert) power two of those
+signals.
+
+### Can I add StopSlop to a legacy repository?
+
+Yes. Generate `.stopslop-baseline.json`, review and commit it, then use that same
+file in CI. Existing findings remain in the score and report as accepted debt;
+only unaccepted findings fail the gate.
+
+### Does StopSlop support monorepos and CI code scanning?
+
+Yes. Configure Knip workspaces under `stopslop.json#knip.workspaces` for accurate
+dead-code analysis in a monorepo. Use SARIF for GitHub Code Scanning, JSON for
+automation and coding agents, or the Shields format for a README status badge.
+
 ## Development
 
 ```bash
 pnpm install
 pnpm test
 pnpm typecheck
+pnpm check:clones
 pnpm build
 pnpm test:package
 pnpm release:check

package/context7.json

@@ -0,0 +1,21 @@
+{
+  "$schema": "https://context7.com/schema/context7.json",
+  "projectTitle": "StopSlop",
+  "description": "Static analysis and CI gate for AI code slop in JavaScript and TypeScript: cognitive complexity, god units, duplicate code, dead code, orphan features, SARIF and baselines.",
+  "folders": ["docs"],
+  "excludeFolders": [],
+  "excludeFiles": ["CHANGELOG.md", "ISSUE_KNIP.md", "RELEASING.md"],
+  "rules": [
+    "StopSlop detects structural code patterns; it does not determine whether code was written by a human or AI.",
+    "Run StopSlop without installing it with `npx stopslop .`. It requires Node.js ^20.19.0 or >=22.12.0 and analyzes JavaScript, JSX, TypeScript and TSX.",
+    "Exit code 0 means no unaccepted findings, 1 means findings were detected, and 2 means analysis or configuration failed.",
+    "Adopt an existing repository with `--baseline .stopslop-baseline.json --update-baseline`, commit that file, then use the same `--baseline` option in CI to reject only new findings.",
+    "A baseline changes the gate and reported findings but never lowers the full-repository slop score.",
+    "Use `--base <git-ref>` to compare against a Git revision without maintaining a baseline file. CI must fetch enough Git history to resolve that ref.",
+    "Report formats are text, json, sarif and shields. Use JSON for coding agents, SARIF for code scanning and shields for the binary `AI slop | clear` badge.",
+    "StopSlop works without configuration. Put optional overrides in `stopslop.json` and use `$schema: https://unpkg.com/stopslop/schema.json` for editor validation.",
+    "Use `--fast` only when intentionally skipping duplicate-code and dead-code analysis; it runs the AST checks for cognitive complexity and god units.",
+    "The Node API is ESM and typed: call `resolveConfig()` before `analyze()`, or call `loadConfig()` to read stopslop.json. The slop score always describes the complete analyzed repository.",
+    "Clone detection is powered by Clone Alert and dead-code analysis by Knip. Configure Knip only under the `knip` property in stopslop.json."
+  ]
+}

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*.

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,25 @@
+# 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+.
+
+## 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)

package/package.json

@@ -1,9 +1,11 @@
 {
   "name": "stopslop",
-  "version": "0.2.0",
-  "description": "Detects AI-agent slop that linters miss: over-complex functions, god modules/classes, dumped responsibilities.",
+  "version": "1.0.0",
+  "description": "Static analysis for AI-generated JavaScript and TypeScript: find cognitive complexity, god classes/modules, duplicate code, dead code and orphan features.",
   "type": "module",
   "license": "MIT",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/BaryshevRS/stopslop.git"
@@ -18,12 +20,20 @@
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
-      "import": "./dist/index.js"
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
     },
-    "./schema.json": "./schema.json"
+    "./schema.json": "./schema.json",
+    "./package.json": "./package.json"
   },
   "files": [
-    "dist",
+    "dist/**/*",
+    "docs/**/*.md",
+    "README.md",
+    "COMPATIBILITY.md",
+    "LICENSE",
+    "llms.txt",
+    "context7.json",
     "schema.json"
   ],
   "engines": {
@@ -40,8 +50,9 @@
     "test": "vitest run",
     "test:watch": "vitest",
     "test:package": "node scripts/package-smoke.mjs",
+    "check:clones": "clone-alert --minimum-tokens 100 --files src --format text --fail-on-violation",
     "audit:prod": "pnpm audit --prod",
-    "ci:check": "pnpm test && pnpm typecheck && pnpm build",
+    "ci:check": "pnpm test && pnpm typecheck && pnpm check:clones && pnpm build",
     "release:check": "pnpm ci:check && pnpm audit:prod && pnpm test:package",
     "prepublishOnly": "pnpm release:check",
     "calibrate": "tsx scripts/calibrate.ts",
@@ -74,12 +85,41 @@
   },
   "keywords": [
     "ai",
+    "ai-code",
+    "ai-generated-code",
+    "ai-code-quality",
+    "ai-slop",
     "slop",
+    "slop-detector",
+    "vibe-coding",
+    "static-analysis",
+    "code-analysis",
+    "code-quality",
     "code-smell",
+    "technical-debt",
+    "javascript",
+    "typescript",
+    "jsx",
+    "tsx",
+    "cli",
+    "lint",
+    "ci",
+    "quality-gate",
+    "code-scanning",
+    "github-actions",
+    "sarif",
+    "baseline",
     "god-class",
     "god-module",
     "cognitive-complexity",
     "lcom",
-    "static-analysis"
+    "cohesion",
+    "duplicate-code",
+    "copy-paste-detector",
+    "dead-code",
+    "unused-code",
+    "orphan-code",
+    "monorepo",
+    "code-review"
   ]
 }