stopslop 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,292 @@
+import { KnipConfiguration } from "knip";
+
+//#region src/types.d.ts
+type FindingKind = 'cognitive-complexity' | 'god-module' | 'god-class' | 'multiple-exported-classes' | 'duplicate-code' | 'unused-export' | 'unused-dependency' | 'unused-file' | 'orphan-feature';
+type Severity = 'info' | 'warn';
+/** A single reported problem. Identity is `file + symbol` (see baseline, Stage 3). */
+interface Finding {
+  kind: FindingKind;
+  file: string;
+  symbol: string;
+  line: number;
+  severity: Severity;
+  message: string;
+  /** Structured payload for --json consumers and --details rendering. */
+  data?: Record<string, unknown>;
+  /** True while thresholds are pre-calibration defaults. */
+  preliminary?: boolean;
+}
+/** A parsed source file with everything analyzers need, produced once per file. */
+interface ParsedFile {
+  /** Relative path from the analysis root, POSIX separators. */
+  relPath: string;
+  absPath: string;
+  source: string;
+  /** oxc Program node (ESTree-like). Typed loosely; we treat nodes structurally. */
+  program: OxcNode;
+  /** Convert a 0-based offset into a 1-based line number. */
+  lineAt: (offset: number) => number;
+}
+/** Loose AST node. oxc returns ESTree-shaped nodes with byte/UTF-16 offsets. */
+interface OxcNode {
+  type: string;
+  start: number;
+  end: number;
+  [key: string]: unknown;
+}
+interface Analyzer {
+  name: string;
+  /** Stage 1 analyzers: pure AST work, one file at a time. */
+  analyzeFile?(file: ParsedFile, ctx: AnalyzeContext): Finding[];
+  /** Stage 2 analyzers (Knip, Clone Alert): whole-project, async. */
+  analyzeProject?(ctx: ProjectContext): Promise<Finding[]>;
+}
+interface AnalyzeContext {
+  config: ResolvedConfig;
+}
+interface ProjectContext {
+  root: string;
+  files: ParsedFile[];
+  config: ResolvedConfig;
+  /** Non-fatal notes from an engine (e.g. "knip skipped: no package.json"). */
+  notes: string[];
+  /**
+   * 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
+   * drops that signal instead of scoring it as clean.
+   */
+  metrics: Partial<ProjectMetrics>;
+}
+/** Signals the score is computed from. Absent = not measured (≠ measured zero). */
+interface ProjectMetrics {
+  /** Duplicated physical lines / total physical lines, 0..1. */
+  duplicationRatio: number;
+  /** Set only once Knip has actually produced results. */
+  deadCodeMeasured: boolean;
+}
+interface GodGate {
+  enabled: boolean;
+  /** Dispersion axis: several unrelated responsibility groups with real boundaries. */
+  minMembers: number;
+  minClusters: number;
+  minComplexity: number;
+  /** Size axis (WMC): a monolith too large to be one unit, even if fully connected. */
+  sizeMembers: number;
+  sizeComplexity: number;
+}
+interface CognitiveGate {
+  enabled: boolean;
+  /** Functions strictly above this cognitive-complexity score are reported. */
+  threshold: number;
+}
+interface MultiClassGate {
+  enabled: boolean;
+  /** Files with more than this many exported classes are reported. */
+  maxPerFile: number;
+}
+/** Clone Alert gate. */
+interface DuplicatesGate {
+  enabled: boolean;
+  /** Minimum duplicated token span reported as a clone (Clone Alert default: 50). */
+  minTokens: number;
+  /** Minimum physical lines a clone must span — kills dense one-liner matches. */
+  minLines: number;
+  /** Ignore identifier names when matching — catches renamed copy-paste. */
+  ignoreIdentifiers: boolean;
+  /** Ignore literal values when matching. */
+  ignoreLiterals: boolean;
+}
+/** Knip gate. Each issue class can be turned off on its own. */
+interface DeadCodeGate {
+  enabled: boolean;
+  /** Unused exports and exported types — high confidence. */
+  exports: boolean;
+  /** Unused (dev)dependencies in package.json — high confidence. */
+  dependencies: boolean;
+  /** Unused files — depends on entry-point detection; reported as info. */
+  files: boolean;
+  /** Symbols kept alive by nothing but their own paired test. */
+  orphans: boolean;
+  /** Treat the project as production-only (drops test-only usage). */
+  production: boolean;
+}
+/**
+ * Slop score: weighted sum of per-KLOC densities, each rising from its floor
+ * and saturating at its budget. See docs/score.md — the formula is published,
+ * not a black box.
+ */
+interface ScoreConfig {
+  weights: ScoreSignals;
+  /** Density (per KLOC; duplication is a 0..1 ratio) that saturates a signal. */
+  budgets: ScoreSignals;
+  /**
+   * Density below which a signal contributes nothing. Zero for most signals;
+   * duplication has a real floor — a few percent of duplicated lines is the
+   * baseline of any living codebase (benchmark corpus p25 ≈ 5%), not slop.
+   */
+  floors: ScoreSignals;
+}
+interface ScoreSignals {
+  god: number;
+  complexity: number;
+  duplication: number;
+  deadCode: number;
+}
+interface ResolvedConfig {
+  cognitiveComplexity: CognitiveGate;
+  godModule: GodGate;
+  godClass: GodGate;
+  multipleExportedClasses: MultiClassGate;
+  duplicates: DuplicatesGate;
+  deadCode: DeadCodeGate;
+  /** Complete Knip configuration, sourced only from stopslop.json#knip. */
+  knip: KnipConfiguration;
+  score: ScoreConfig;
+  /** fan-in fraction above which a member is treated as a hub (0..1). */
+  hubFanInRatio: number;
+  ignore: string[];
+  /** Whether current thresholds are pre-calibration defaults. */
+  preliminary: boolean;
+}
+//#endregion
+//#region src/score.d.ts
+type SlopLevel = 'clean' | 'low' | 'moderate' | 'high' | 'legacy-grade';
+interface SlopScore {
+  /** 0..100. */
+  score: number;
+  level: SlopLevel;
+  kloc: number;
+  loc: number;
+  /** Raw signal values: per-KLOC densities, duplication as a 0..1 ratio. */
+  densities: Partial<ScoreSignals>;
+  /** Each signal's contribution to the score, in points. */
+  contributions: Partial<ScoreSignals>;
+  /**
+   * How many signals actually fed the score, out of all of them. A partial
+   * score is NOT comparable with a full one: the missing weight is renormalized
+   * away, so an unmeasured signal is imputed from the others and pushes the
+   * number up. Callers must surface this.
+   */
+  signalCount: number;
+  totalSignals: number;
+  /**
+   * Share (0..100) of the reference corpus this repo is sloppier than, on the
+   * core signals (god + duplication + complexity) all 41 corpus repos measure
+   * identically. Absent when a core signal was not measured.
+   */
+  percentile?: number;
+}
+interface ScoreInput {
+  findings: Finding[];
+  /** Physical lines across the analyzed files. */
+  loc: number;
+  metrics: Partial<ProjectMetrics>;
+  config: ResolvedConfig;
+}
+declare function computeScore(input: ScoreInput): SlopScore;
+/** Bands are labels for the score, not extra thresholds — same preliminary caveat. */
+declare function levelFor(score: number): SlopLevel;
+//#endregion
+//#region src/config.d.ts
+/**
+ * Default thresholds. First-pass calibrated on the 22-repo corpus (see
+ * docs/thresholds.md); still flagged PRELIMINARY until validated against the
+ * Stage-4 victim repo. The god gates are a conjunction (members AND clusters AND
+ * complexity), so `minMembers` is kept sensitive — precision comes from the
+ * cluster + complexity requirement, not from a high member floor.
+ * Full reference: docs/configuration.md.
+ */
+declare const DEFAULT_CONFIG: ResolvedConfig;
+/**
+ * User-facing config shape (`stopslop.json`). Every field optional and
+ * deep-merged over defaults. A check accepts `false` to disable it, or a
+ * partial object to override its thresholds.
+ */
+interface StopSlopConfig {
+  /** Editor-only pointer to the published StopSlop JSON Schema. */
+  $schema?: string;
+  cognitiveComplexity?: number | false;
+  godModule?: Partial<Omit<GodGate, 'enabled'>> | false;
+  godClass?: Partial<Omit<GodGate, 'enabled'>> | false;
+  multipleExportedClasses?: Partial<Omit<MultiClassGate, 'enabled'>> | false;
+  duplicates?: Partial<Omit<DuplicatesGate, 'enabled'>> | false;
+  deadCode?: Partial<Omit<DeadCodeGate, 'enabled'>> | false;
+  /** Complete JSON-compatible Knip config. Project-local Knip configs are ignored. */
+  knip?: KnipConfiguration;
+  score?: {
+    weights?: Partial<ScoreSignals>;
+    budgets?: Partial<ScoreSignals>;
+    floors?: Partial<ScoreSignals>;
+  };
+  hubFanInRatio?: number;
+  ignore?: string[];
+}
+declare function resolveConfig(raw: StopSlopConfig | undefined): ResolvedConfig;
+/** Load `stopslop.json` from `dir` (or an explicit path). Missing file → defaults. */
+declare function loadConfig(dir: string, explicitPath?: string): ResolvedConfig;
+//#endregion
+//#region src/baseline.d.ts
+/** One accepted finding, as persisted in the baseline file. */
+interface BaselineRecord {
+  kind: Finding['kind'];
+  file: string;
+  symbol: string;
+}
+/**
+ * Stable identity of a finding. Identity, not content: a god class mutates on
+ * every edit (an agent keeps appending to it), so a content hash would break
+ * constantly — `kind + file + symbol` stays put while the class grows.
+ *
+ * Duplicates are the exception: their `symbol` is already a content fingerprint
+ * (see duplicates.ts), so they key on `kind + symbol` alone and a clone that
+ * moves between files stays baselined — the property the fingerprint exists for.
+ */
+declare function fingerprint(f: Pick<Finding, 'kind' | 'file' | 'symbol'>): string;
+/** Fingerprints of every finding recorded in the baseline file. */
+declare function readBaseline(path: string): Set<string>;
+/**
+ * Serialize findings to the baseline file. Deduplicated by fingerprint and sorted
+ * by (kind, file, symbol) — no line numbers, no messages — so the file stays a
+ * stable, reviewable, churn-free diff as the code around a finding shifts.
+ */
+declare function writeBaseline(path: string, findings: Finding[]): void;
+/** Split findings into the ones not in the baseline (reported) and the count suppressed. */
+declare function applyBaseline(findings: Finding[], accepted: Set<string>): {
+  kept: Finding[];
+  suppressed: number;
+};
+//#endregion
+//#region src/index.d.ts
+interface AnalyzeResult {
+  root: string;
+  fileCount: number;
+  /** Physical lines across the analyzed files. */
+  loc: number;
+  findings: Finding[];
+  slop: SlopScore;
+  metrics: Partial<ProjectMetrics>;
+  errors: string[];
+  /** Non-fatal notes from the Stage-2 engines (skipped checks, and why). */
+  notes: string[];
+  config: ResolvedConfig;
+  elapsedMs: number;
+  /**
+   * When a baseline is applied, how many findings it suppressed (accepted
+   * legacy). `findings` then holds only the new ones. Unset without a baseline.
+   * The slop score is always the full, honest state and is never gated.
+   */
+  baselineSuppressed?: number;
+  /** Git revision used as a temporary baseline for this analysis. */
+  gitBase?: {
+    ref: string;
+    commit: string;
+    suppressed: number;
+  };
+}
+/** File-level (Stage 1) plus project-level (Stage 2: Clone Alert, Knip) analyzers. */
+declare function defaultAnalyzers(): Analyzer[];
+declare function analyze(root: string, config: ResolvedConfig, analyzers?: Analyzer[]): Promise<AnalyzeResult>;
+/** 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 };

package/dist/index.js

@@ -0,0 +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";
+export { DEFAULT_CONFIG, analyze, analyzeGitBase, applyBaseline, computeScore, defaultAnalyzers, fingerprint, levelFor, loadConfig, readBaseline, resolveConfig, writeBaseline };

package/package.json

@@ -0,0 +1,77 @@
+{
+  "name": "stopslop",
+  "version": "0.1.0",
+  "description": "Detects AI-agent slop that linters miss: over-complex functions, god modules/classes, dumped responsibilities.",
+  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/BaryshevRS/stopslop.git"
+  },
+  "homepage": "https://github.com/BaryshevRS/stopslop#readme",
+  "bugs": {
+    "url": "https://github.com/BaryshevRS/stopslop/issues"
+  },
+  "bin": {
+    "stopslop": "dist/cli.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./schema.json": "./schema.json"
+  },
+  "files": [
+    "dist",
+    "schema.json"
+  ],
+  "engines": {
+    "node": "^20.19.0 || >=22.12.0"
+  },
+  "packageManager": "pnpm@10.1.0",
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "prebuild": "pnpm schema:check",
+    "build": "tsdown",
+    "dev": "tsdown --watch",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:package": "node scripts/package-smoke.mjs",
+    "audit:prod": "pnpm audit --prod",
+    "ci:check": "pnpm test && pnpm typecheck && pnpm build",
+    "release:check": "pnpm ci:check && pnpm audit:prod && pnpm test:package",
+    "prepublishOnly": "pnpm release:check",
+    "calibrate": "tsx scripts/calibrate.ts",
+    "typecheck": "tsc --noEmit",
+    "schema:generate": "tsx scripts/generate-config-schema.ts",
+    "schema:check": "tsx scripts/generate-config-schema.ts --check"
+  },
+  "dependencies": {
+    "clone-alert": "^1.1.3",
+    "knip": "^6.26.0",
+    "oxc-parser": "^0.139.0",
+    "picocolors": "^1.1.1"
+  },
+  "devDependencies": {
+    "@arethetypeswrong/core": "^0.18.1",
+    "@types/node": "^22.10.0",
+    "publint": "^0.3.8",
+    "tsdown": "^0.21.10",
+    "tsx": "^4.19.0",
+    "typescript": "^5.7.0",
+    "vitest": "^3.0.0"
+  },
+  "keywords": [
+    "ai",
+    "slop",
+    "code-smell",
+    "god-class",
+    "god-module",
+    "cognitive-complexity",
+    "lcom",
+    "static-analysis"
+  ]
+}