stopslop 0.2.0 → 1.1.0

package/COMPATIBILITY.md

@@ -0,0 +1,31 @@
+# Compatibility
+
+Last updated: 1.1.0
+
+StopSlop follows Semantic Versioning. Stable surfaces change incompatibly only
+in a major release. Experimental surfaces may change in a minor release; such
+changes are called out in the changelog.
+
+| Surface | Tier | Compatibility policy |
+| --- | --- | --- |
+| CLI flags and exit codes | Stable | New flags may be added; existing flags and exit code meanings change only in a major release. |
+| Versioned JSON report | Stable | Fields may be added within a `schemaVersion`; removing or changing one increments it and requires a major release. |
+| SARIF 2.1.0 report | Stable | New rules and optional properties may be added; existing required fields remain compatible. |
+| `stopslop.json` schema | Stable | New settings may be added; configuration valid in a 1.x release stays valid in every later 1.x release. |
+| Programmatic Node.js API | Experimental | Exported functions and TypeScript types may change in a minor release. |
+
+Findings and scores are not a compatibility surface. Detector fixes, threshold
+calibration, and Knip or Clone Alert updates can change what a release reports
+for the same code; such changes are called out in the changelog. Pin the
+StopSlop version in CI when a gate must not move without a commit.
+
+## 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)
+[![StopSlop](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,50 @@ 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.
 
+### Dead-code configuration
+
+Knip settings go under `knip` in `stopslop.json`. A project's own `knip.json`,
+`.knip.json`, `knip.config.*` and `package.json#knip` are never read, so an
+analysis does not change with whatever happens to sit in the directory.
+Everything in [Knip's configuration reference](https://knip.dev/reference/configuration)
+works there unchanged.
+
+You do not have to work out what belongs there. Run the analysis and Knip
+reports what its configuration is missing — which workspace it never reached,
+which declared entry point resolved to nothing — under **config hints**, with
+the file count each one accounts for:
+
+```
+  config hints  (from Knip)
+  packages/core  ·  12 files
+    Add entry and/or refine project files in workspaces["packages/core"] (12 unused files)
+  → Knip settings live under `knip` in stopslop.json (knip.json is not read)
+    reference: https://knip.dev/reference/configuration
+```
+
+Address them, run again, repeat until they are gone. Until then dead code is
+reported but left out of the score, because a run without entry points reports
+live files as unreachable. The same list is in `configHints` of `--format json`.
+
+## 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 and may change in a minor release; see
+[COMPATIBILITY.md](COMPATIBILITY.md).
+
 ## Design and limitations
 
 - StopSlop supports `.js`, `.jsx`, `.mjs`, `.cjs`, `.ts`, and `.tsx` source.
@@ -246,19 +303,53 @@ complete configuration.
   directories are excluded by default.
 - A high score does not prove poor engineering, and a low score does not prove
   correctness. StopSlop measures structural overproduction, not total quality.
-- Dead-code accuracy depends on Knip knowing the project's entry points.
+- Dead-code accuracy depends on Knip knowing the project's entry points; the
+  run says so through config hints when it does not.
 - A baseline accepts finding identities. If an accepted function becomes more
   complex without changing identity, the score rises but the gate stays clear.
 
 Architecture, research references, and the boundary between published methods
 and StopSlop heuristics are documented in [ARCH.md](ARCH.md).
 
+## 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,22 @@
+{
+  "$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", "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.",
+    "Knip settings go under `knip` in stopslop.json; a project's own knip.json or package.json#knip is never read. Do not write one up front — run the analysis and follow the `config hints` it prints, which come from Knip and name what is missing."
+  ]
+}

package/dist/cli.js

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
-import { a as loadConfig, d as readBaseline, f as writeBaseline, l as applyBaseline, n as analyzeGitBase, t as analyze, u as fingerprint } from "./src.js";
-import { posix } from "node:path";
+import { c as loadConfig, d as fingerprint, f as readBaseline, n as analyzeGitBase, p as writeBaseline, s as configFilePath, t as analyze, u as applyBaseline } from "./src.js";
+import { posix, relative, sep } from "node:path";
 import { createHash } from "node:crypto";
 import pc from "picocolors";
 //#region src/report/terminal.ts
@@ -69,8 +69,29 @@ const LEVEL_COLOR = {
 	high: pc.red,
 	"legacy-grade": pc.red
 };
+/**
+* What Knip says is missing from the configuration. This block is the whole
+* setup story: a dead-code run is only as good as its entry points, and Knip
+* is the one that knows which of them came up empty. The last line names the
+* file to edit — the one thing Knip cannot know, and the thing an agent
+* otherwise guesses wrong by writing knip.json, which StopSlop never reads.
+*/
+function renderConfigHints(result) {
+	if (result.configHints.length === 0) return [];
+	const lines = ["", "  " + pc.bold("config hints") + pc.dim("  (from Knip)")];
+	for (const hint of result.configHints) {
+		const where = hint.workspace && hint.workspace !== hint.identifier ? `  in ${hint.workspace}` : "";
+		const size = hint.size === void 0 ? "" : `  ·  ${hint.size} files`;
+		lines.push(`  ${pc.yellow(hint.identifier)}${pc.dim(where + size)}`);
+		lines.push("    " + pc.dim(hint.message));
+	}
+	const file = relative(result.root, configFilePath(result.root, result.config)).split(sep).join("/");
+	lines.push("  " + pc.dim(`→ Knip settings live under \`knip\` in ${file} (knip.json is not read)`));
+	lines.push("  " + pc.dim("  reference: https://knip.dev/reference/configuration"));
+	return lines;
+}
 function renderFooter(result) {
-	const lines = [""];
+	const lines = [...renderConfigHints(result), ""];
 	for (const note of result.notes) lines.push("  " + pc.dim(note));
 	if (result.config.preliminary) lines.push("  " + pc.yellow("thresholds are preliminary (pre-calibration) — see docs/thresholds.md"));
 	if (result.errors.length > 0) lines.push("  " + pc.dim(`${result.errors.length} file(s) skipped on error`));
@@ -189,6 +210,12 @@ function toJson(result) {
 		summary: summarize(result),
 		findings: result.findings,
 		notes: result.notes,
+		configHints: result.configHints,
+		/** Where Knip settings are read from. Nowhere else is consulted. */
+		configFile: {
+			path: relative(result.root, configFilePath(result.root, result.config)).split(sep).join("/"),
+			property: "knip"
+		},
 		errors: result.errors
 	}, null, 2);
 }

package/dist/index.d.ts

@@ -44,12 +44,35 @@ interface Analyzer {
 interface AnalyzeContext {
   config: ResolvedConfig;
 }
+/**
+ * What Knip reports as missing from its configuration, computed from the run it
+ * just did. Knip owns this judgement — it knows which entry pattern matched
+ * nothing and which workspace it never reached, and it counts the files that
+ * hang off each. StopSlop adds one thing Knip cannot know: where the
+ * configuration lives.
+ */
+interface ConfigHint {
+  /** Knip's hint type: `workspace-unconfigured`, `package-entry`, `ignore`, … */
+  type: string;
+  /** What it is about — a workspace key, a path, a dependency name. */
+  identifier: string;
+  /** Knip's own wording. */
+  message: string;
+  /** Workspace the hint belongs to — what tells two identical ones apart. */
+  workspace?: string;
+  /** File the hint is about, relative to the analyzed root. */
+  filePath?: string;
+  /** Unused files attributable to this hint, where Knip counted them. */
+  size?: number;
+}
 interface ProjectContext {
   root: string;
   files: ParsedFile[];
   config: ResolvedConfig;
   /** Non-fatal notes from an engine (e.g. "knip skipped: no package.json"). */
   notes: string[];
+  /** Configuration Knip found missing. Empty when it has nothing to say. */
+  configHints: ConfigHint[];
   /**
    * What the Stage-2 engines actually measured. An engine that was disabled —
    * or that bailed out at runtime — leaves its entry unset, and the score then
@@ -147,6 +170,12 @@ interface ResolvedConfig {
   ignore: string[];
   /** Whether current thresholds are provisional. False for the calibrated defaults. */
   preliminary: boolean;
+  /**
+   * The stopslop.json `loadConfig` read — or looked for, when there is none.
+   * Unset for an in-memory `resolveConfig()`; the analyzed root's own
+   * stopslop.json stands in then.
+   */
+  configFile?: string;
 }
 //#endregion
 //#region src/score.d.ts
@@ -267,6 +296,8 @@ interface AnalyzeResult {
   errors: string[];
   /** Non-fatal notes from the Stage-2 engines (skipped checks, and why). */
   notes: string[];
+  /** What Knip reports as missing from `stopslop.json#knip`, from this run. */
+  configHints: ConfigHint[];
   config: ResolvedConfig;
   elapsedMs: number;
   /**
@@ -288,4 +319,4 @@ declare function analyze(root: string, config: ResolvedConfig, analyzers?: Analy
 /** Gate the current working tree against findings present at a Git revision. */
 declare function analyzeGitBase(root: string, baseRef: string, config: ResolvedConfig, analyzers?: Analyzer[]): Promise<AnalyzeResult>;
 //#endregion
-export { AnalyzeResult, type Analyzer, type BaselineRecord, DEFAULT_CONFIG, type Finding, type ParsedFile, type ResolvedConfig, type SlopLevel, type SlopScore, type StopSlopConfig, analyze, analyzeGitBase, applyBaseline, computeScore, defaultAnalyzers, fingerprint, levelFor, loadConfig, readBaseline, resolveConfig, writeBaseline };
+export { AnalyzeResult, type Analyzer, type BaselineRecord, type ConfigHint, DEFAULT_CONFIG, type Finding, type ParsedFile, type ResolvedConfig, type SlopLevel, type SlopScore, type StopSlopConfig, analyze, analyzeGitBase, applyBaseline, computeScore, defaultAnalyzers, fingerprint, levelFor, loadConfig, readBaseline, resolveConfig, writeBaseline };

package/dist/index.js

@@ -1,2 +1,2 @@
-import { a as loadConfig, c as levelFor, d as readBaseline, f as writeBaseline, i as DEFAULT_CONFIG, l as applyBaseline, n as analyzeGitBase, o as resolveConfig, r as defaultAnalyzers, s as computeScore, t as analyze, u as fingerprint } from "./src.js";
+import { a as levelFor, c as loadConfig, d as fingerprint, f as readBaseline, i as computeScore, l as resolveConfig, n as analyzeGitBase, o as DEFAULT_CONFIG, p as writeBaseline, r as defaultAnalyzers, t as analyze, u as applyBaseline } from "./src.js";
 export { DEFAULT_CONFIG, analyze, analyzeGitBase, applyBaseline, computeScore, defaultAnalyzers, fingerprint, levelFor, loadConfig, readBaseline, resolveConfig, writeBaseline };

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.