stopslop 0.1.0

package/dist/cli.js

@@ -0,0 +1,427 @@
+#!/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 { createHash } from "node:crypto";
+import pc from "picocolors";
+//#region src/report/terminal.ts
+const KIND_LABEL = {
+	"god-module": "god module",
+	"god-class": "god class",
+	"cognitive-complexity": "complex fn",
+	"multiple-exported-classes": "multi-class file",
+	"duplicate-code": "clone",
+	"unused-export": "unused export",
+	"unused-dependency": "unused dep",
+	"unused-file": "unused file",
+	"orphan-feature": "orphan feature"
+};
+const KIND_ORDER = Object.keys(KIND_LABEL);
+/** Findings per kind shown before collapsing into a "+N more" line. */
+const MAX_PER_KIND = 12;
+function renderTerminal(result, details) {
+	const lines = [];
+	const { findings } = result;
+	lines.push("");
+	lines.push(pc.bold(pc.cyan("  stopslop")) + pc.dim(`  ${result.fileCount} files  ${formatKloc(result.loc)}  ${result.elapsedMs}ms`));
+	lines.push("");
+	lines.push(renderScore(result));
+	if (result.gitBase !== void 0) lines.push("  " + pc.dim(`git base: ${result.gitBase.ref} (${result.gitBase.commit.slice(0, 12)}) · ${result.gitBase.suppressed} existing · ${findings.length} new`));
+	else if (result.baselineSuppressed !== void 0) lines.push("  " + pc.dim(`baseline: ${result.baselineSuppressed} accepted · ${findings.length} new`));
+	lines.push("");
+	if (findings.length === 0) {
+		const msg = result.gitBase !== void 0 ? `✓ no new slop since ${result.gitBase.ref}` : result.baselineSuppressed !== void 0 ? "✓ no new slop since baseline" : "✓ no slop signals";
+		lines.push("  " + pc.green(msg));
+		lines.push("");
+		lines.push(renderFooter(result).join("\n"));
+		return lines.join("\n");
+	}
+	const counts = countByKind(findings);
+	const chips = KIND_ORDER.filter((k) => counts[k] > 0).map((k) => `${pc.bold(String(counts[k]))} ${pluralize(KIND_LABEL[k], counts[k])}`);
+	lines.push("  " + chips.join(pc.dim("  ·  ")));
+	lines.push("");
+	const shown = {};
+	for (const f of findings) if ((shown[f.kind] = (shown[f.kind] ?? 0) + 1) <= MAX_PER_KIND) lines.push(renderFinding(f, details));
+	for (const kind of KIND_ORDER) {
+		const hidden = counts[kind] - MAX_PER_KIND;
+		if (hidden > 0) lines.push("  " + pc.dim(`… ${hidden} more ${pluralize(KIND_LABEL[kind], hidden)} (--json for all)`));
+	}
+	lines.push(...renderFooter(result));
+	return lines.join("\n");
+}
+/** The headline: one comparable number, with the densities it came from. */
+function renderScore(result) {
+	const { score, level, densities, signalCount, totalSignals, percentile } = result.slop;
+	const paint = LEVEL_COLOR$1[level];
+	const partial = signalCount < totalSignals ? pc.yellow(` — ${signalCount}/${totalSignals} signals, see notes`) : "";
+	const anchor = percentile !== void 0 ? pc.dim(`  ·  worse than ${percentile}% of reference repos`) : "";
+	const head = `  slop level: ${paint(pc.bold(level))} ${pc.dim(`(${score.toFixed(1)}/100)`)}${anchor}${partial}`;
+	const parts = [];
+	if (densities.god !== void 0) parts.push(`god units ${densities.god.toFixed(2)}/KLOC`);
+	if (densities.complexity !== void 0) parts.push(`complex fns ${densities.complexity.toFixed(2)}/KLOC`);
+	if (densities.duplication !== void 0) parts.push(`duplication ${(densities.duplication * 100).toFixed(1)}%`);
+	if (densities.deadCode !== void 0) parts.push(`dead code ${densities.deadCode.toFixed(2)}/KLOC`);
+	return parts.length > 0 ? head + "\n  " + pc.dim(parts.join("  ·  ")) : head;
+}
+const LEVEL_COLOR$1 = {
+	clean: pc.green,
+	low: pc.green,
+	moderate: pc.yellow,
+	high: pc.red,
+	"legacy-grade": pc.red
+};
+function renderFooter(result) {
+	const lines = [""];
+	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`));
+	lines.push("  " + pc.dim("clones: Clone Alert  ·  dead code: Knip"));
+	lines.push("");
+	return lines;
+}
+function renderFinding(f, details) {
+	const tag = tagFor(f);
+	const loc = pc.dim(`${f.file}:${f.line}`);
+	const out = [`  ${tag} ${f.message}`, `      ${loc}`];
+	if (f.kind === "duplicate-code") {
+		const rest = (f.data?.occurrences ?? []).slice(1);
+		const list = details ? rest : rest.slice(0, 3);
+		for (const o of list) out.push("      " + pc.dim(`also ${o.file}:${o.startLine}-${o.endLine}`));
+		if (!details && rest.length > list.length) out.push("      " + pc.dim(`also +${rest.length - list.length} more`));
+		return out.join("\n");
+	}
+	if (details && (f.kind === "god-module" || f.kind === "god-class")) {
+		const axis = f.data?.axis;
+		const groups = f.data?.groups ?? [];
+		const standalone = f.data?.standalone ?? [];
+		const hubs = f.data?.hubs ?? [];
+		if (hubs.length > 0) out.push("      " + pc.dim("cohesion held together by: ") + pc.yellow(hubs.join(", ")));
+		if (axis === "size" && groups.length < 3) {
+			out.push("      " + pc.dim("densely coupled — no clean split boundaries; decompose by responsibility manually"));
+			if (groups.length >= 2) {
+				out.push("      " + pc.dim("partial grouping:"));
+				groups.forEach((c, i) => out.push("        " + pc.dim(`${i + 1}.`) + " " + c.join(", ")));
+			}
+		} else {
+			out.push("      " + pc.dim(`${groups.length} responsibility groups (suggested split boundaries):`));
+			groups.forEach((c, i) => {
+				out.push("        " + pc.dim(`${i + 1}.`) + " " + c.join(", "));
+			});
+			if (standalone.length > 0) out.push("      " + pc.dim(`+ ${standalone.length} standalone: `) + pc.dim(previewList(standalone)));
+		}
+	}
+	return out.join("\n");
+}
+function formatKloc(loc) {
+	return loc >= 1e3 ? `${(loc / 1e3).toFixed(1)} KLOC` : `${loc} LOC`;
+}
+function pluralize(label, n) {
+	if (n === 1) return label;
+	return /(s|x|ch|sh)$/.test(label) ? `${label}es` : `${label}s`;
+}
+function previewList(names, max = 8) {
+	if (names.length <= max) return names.join(", ");
+	return names.slice(0, max).join(", ") + `, …+${names.length - max}`;
+}
+function tagFor(f) {
+	const label = ` ${KIND_LABEL[f.kind]} `;
+	switch (f.kind) {
+		case "god-module":
+		case "god-class": return pc.bgRed(pc.white(pc.bold(label)));
+		case "cognitive-complexity":
+		case "duplicate-code": return pc.bgYellow(pc.black(label));
+		case "unused-export":
+		case "unused-dependency":
+		case "unused-file": return pc.bgMagenta(pc.white(label));
+		case "orphan-feature": return pc.bgRed(pc.white(pc.bold(label)));
+		default: return pc.bgBlue(pc.white(label));
+	}
+}
+function countByKind(findings) {
+	const counts = Object.fromEntries(KIND_ORDER.map((k) => [k, 0]));
+	for (const f of findings) counts[f.kind]++;
+	return counts;
+}
+const KINDS = [
+	"god-module",
+	"god-class",
+	"duplicate-code",
+	"cognitive-complexity",
+	"unused-export",
+	"unused-dependency",
+	"unused-file",
+	"orphan-feature",
+	"multiple-exported-classes"
+];
+/** Stable, versioned JSON for agents/CI. Sets replaced with sorted arrays. */
+function toJson(result) {
+	return JSON.stringify({
+		schemaVersion: 6,
+		tool: "stopslop",
+		engines: {
+			duplicates: "clone-alert",
+			deadCode: "knip"
+		},
+		root: result.root,
+		fileCount: result.fileCount,
+		loc: result.loc,
+		elapsedMs: result.elapsedMs,
+		preliminaryThresholds: result.config.preliminary,
+		slop: result.slop,
+		...result.baselineSuppressed === void 0 ? {} : { baseline: {
+			suppressed: result.baselineSuppressed,
+			new: result.findings.length
+		} },
+		...result.gitBase === void 0 ? {} : { gitBase: {
+			...result.gitBase,
+			new: result.findings.length
+		} },
+		thresholds: {
+			cognitiveComplexity: result.config.cognitiveComplexity,
+			godModule: result.config.godModule,
+			godClass: result.config.godClass,
+			multipleExportedClasses: result.config.multipleExportedClasses,
+			duplicates: result.config.duplicates,
+			deadCode: result.config.deadCode,
+			knip: result.config.knip,
+			score: result.config.score,
+			hubFanInRatio: result.config.hubFanInRatio
+		},
+		summary: summarize(result),
+		findings: result.findings,
+		notes: result.notes,
+		errors: result.errors
+	}, null, 2);
+}
+function summarize(result) {
+	const counts = Object.fromEntries(KINDS.map((k) => [k, 0]));
+	for (const f of result.findings) counts[f.kind] = (counts[f.kind] ?? 0) + 1;
+	return counts;
+}
+//#endregion
+//#region src/report/sarif.ts
+/** GitHub Code Scanning-compatible SARIF 2.1.0 report. */
+function toSarif(result) {
+	const rules = [];
+	const seenRules = /* @__PURE__ */ new Set();
+	for (const finding of result.findings) {
+		if (seenRules.has(finding.kind)) continue;
+		seenRules.add(finding.kind);
+		rules.push({
+			id: finding.kind,
+			shortDescription: { text: describeKind(finding.kind) },
+			defaultConfiguration: { level: sarifLevel(finding.severity) }
+		});
+	}
+	const sarif = {
+		$schema: "https://json.schemastore.org/sarif-2.1.0.json",
+		version: "2.1.0",
+		runs: [{
+			tool: { driver: {
+				name: "stopslop",
+				rules
+			} },
+			results: result.findings.map((finding) => ({
+				ruleId: finding.kind,
+				level: sarifLevel(finding.severity),
+				message: { text: finding.message },
+				locations: locationsFor(result.root, finding),
+				partialFingerprints: { primaryLocationLineHash: createHash("sha256").update(fingerprint(finding)).digest("hex") }
+			}))
+		}]
+	};
+	return `${JSON.stringify(sarif, null, 2)}\n`;
+}
+function sarifLevel(severity) {
+	return severity === "warn" ? "warning" : "note";
+}
+function describeKind(kind) {
+	const description = kind.replaceAll("-", " ");
+	return `${description.charAt(0).toUpperCase()}${description.slice(1)}`;
+}
+function locationsFor(root, finding) {
+	const primaryUri = artifactUri(root, finding.file);
+	if (!primaryUri || !isLine(finding.line)) return [];
+	const occurrences = Array.isArray(finding.data?.occurrences) ? finding.data.occurrences.flatMap((value) => {
+		const parsed = parseOccurrence(root, value);
+		return parsed ? [parsed] : [];
+	}) : [];
+	const primary = occurrences.find((occurrence) => occurrence.uri === primaryUri && occurrence.startLine === finding.line);
+	const locations = [location(primaryUri, finding.line, primary?.endLine)];
+	const seen = new Set([JSON.stringify([primaryUri, finding.line])]);
+	for (const occurrence of occurrences) {
+		const key = JSON.stringify([occurrence.uri, occurrence.startLine]);
+		if (seen.has(key)) continue;
+		seen.add(key);
+		locations.push(location(occurrence.uri, occurrence.startLine, occurrence.endLine));
+	}
+	return locations;
+}
+function parseOccurrence(root, value) {
+	if (!value || typeof value !== "object") return void 0;
+	const { file, startLine, endLine } = value;
+	if (typeof file !== "string" || !isLine(startLine)) return void 0;
+	const uri = artifactUri(root, file);
+	if (!uri) return void 0;
+	return {
+		uri,
+		startLine,
+		...isLine(endLine) && endLine >= startLine ? { endLine } : {}
+	};
+}
+function location(uri, startLine, endLine) {
+	return { physicalLocation: {
+		artifactLocation: { uri },
+		region: {
+			startLine,
+			...endLine === void 0 ? {} : { endLine }
+		}
+	} };
+}
+function artifactUri(root, file) {
+	const normalizedRoot = root.replaceAll("\\", "/");
+	const normalizedFile = file.replaceAll("\\", "/");
+	const relative = normalizedFile.startsWith("/") || /^[A-Za-z]:\//.test(normalizedFile) ? posix.relative(normalizedRoot, normalizedFile) : normalizedFile;
+	const normalized = posix.normalize(relative).replace(/^\.\//, "");
+	if (normalized === "." || normalized === ".." || normalized.startsWith("../") || normalized.startsWith("/") || /^[A-Za-z][A-Za-z\d+.-]*:/.test(normalized)) return;
+	return normalized.split("/").map(encodeURIComponent).join("/");
+}
+function isLine(value) {
+	return typeof value === "number" && Number.isInteger(value) && value > 0;
+}
+//#endregion
+//#region src/report/badge.ts
+const LEVEL_COLOR = {
+	clean: "brightgreen",
+	low: "green",
+	moderate: "yellow",
+	high: "orange",
+	"legacy-grade": "red"
+};
+/** shields.io endpoint JSON for a slop badge. */
+function toBadge(result) {
+	const { score, level, signalCount, totalSignals } = result.slop;
+	const partial = signalCount < totalSignals ? "*" : "";
+	const payload = {
+		schemaVersion: 1,
+		label: "slop",
+		message: score === 0 ? "0 slop" : `${level} (${score.toFixed(0)}/100)${partial}`,
+		color: LEVEL_COLOR[level]
+	};
+	return `${JSON.stringify(payload, null, 2)}\n`;
+}
+//#endregion
+//#region src/cli.ts
+function parseArgs(argv) {
+	const args = {
+		path: ".",
+		format: "text",
+		details: false,
+		fast: false,
+		updateBaseline: false,
+		help: false
+	};
+	const positional = [];
+	for (let i = 0; i < argv.length; i++) {
+		const a = argv[i];
+		if (a === "--json") args.format = "json";
+		else if (a === "--format") args.format = parseFormat(optionValue("--format", argv[++i]));
+		else if (a.startsWith("--format=")) args.format = parseFormat(optionValue("--format", a.slice(9)));
+		else if (a === "--details" || a === "-d") args.details = true;
+		else if (a === "--fast") args.fast = true;
+		else if (a === "--help" || a === "-h") args.help = true;
+		else if (a === "--config") args.config = optionValue("--config", argv[++i]);
+		else if (a.startsWith("--config=")) args.config = optionValue("--config", a.slice(9));
+		else if (a === "--base") args.base = optionValue("--base", argv[++i]);
+		else if (a.startsWith("--base=")) args.base = optionValue("--base", a.slice(7));
+		else if (a === "--baseline") args.baseline = optionValue("--baseline", argv[++i]);
+		else if (a.startsWith("--baseline=")) args.baseline = optionValue("--baseline", a.slice(11));
+		else if (a === "--update-baseline") args.updateBaseline = true;
+		else if (a.startsWith("-")) throw new Error(`unknown option '${a}'`);
+		else positional.push(a);
+	}
+	if (positional.length > 1) throw new Error("expected at most one path");
+	if (positional[0]) args.path = positional[0];
+	return args;
+}
+function optionValue(option, raw) {
+	if (!raw || raw.startsWith("-")) throw new Error(`${option} requires a value`);
+	return raw;
+}
+function parseFormat(raw) {
+	if (raw === "text" || raw === "json" || raw === "sarif" || raw === "shields") return raw;
+	throw new Error(`unknown --format '${raw ?? ""}' (expected text, json, sarif, or shields)`);
+}
+const HELP = `stopslop — find AI-agent slop that linters miss
+
+Usage:
+  stopslop [path]            analyze a directory or file (default: .)
+
+Options:
+  --format <fmt>             text (default) · json · sarif · shields (badge JSON)
+  --json                     alias for --format json
+  --details, -d              show cluster composition, hubs, all clone sites
+  --fast                     AST checks only: skip clones and dead code
+  --config <file>            path to a stopslop.json config
+  --base <ref>               gate only on findings absent from this Git revision
+  --baseline <file>          gate only on findings not in this baseline file
+  --update-baseline          write the current findings to --baseline and exit 0
+  --help, -h                 show this help
+
+Checks: complexity, god module/class (own) · clones (Clone Alert) · dead code (Knip)
+Exit codes: 0 clean · 1 findings · 2 error
+
+Baseline: adopt an existing repo's findings, then fail only on new ones.
+  --base is mutually exclusive with --baseline and --update-baseline.
+  stopslop . --base main                                            # gate vs Git
+  stopslop . --baseline .stopslop-baseline.json --update-baseline   # record
+  stopslop . --baseline .stopslop-baseline.json                     # gate on new`;
+async function main() {
+	const args = parseArgs(process.argv.slice(2));
+	if (args.help) {
+		process.stdout.write(HELP + "\n");
+		process.exit(0);
+	}
+	try {
+		validateArgs(args);
+		const config = loadConfig(args.path, args.config);
+		if (args.fast) {
+			config.duplicates.enabled = false;
+			config.deadCode.enabled = false;
+		}
+		const result = args.base ? await analyzeGitBase(args.path, args.base, config) : await analyze(args.path, config);
+		if (args.updateBaseline) {
+			writeBaseline(args.baseline, result.findings);
+			process.stderr.write(`stopslop: baseline written to ${args.baseline} (${result.findings.length} findings accepted)\n`);
+			process.exit(0);
+		}
+		let reported = result;
+		if (args.baseline) {
+			const { kept, suppressed } = applyBaseline(result.findings, readBaseline(args.baseline));
+			reported = {
+				...result,
+				findings: kept,
+				baselineSuppressed: suppressed
+			};
+		}
+		if (args.format === "json") process.stdout.write(toJson(reported) + "\n");
+		else if (args.format === "sarif") process.stdout.write(toSarif(reported));
+		else if (args.format === "shields") {
+			process.stdout.write(toBadge(result));
+			process.exit(0);
+		} else process.stdout.write(renderTerminal(reported, args.details) + "\n");
+		process.exit(reported.findings.length > 0 ? 1 : 0);
+	} catch (err) {
+		process.stderr.write("stopslop: " + err.message + "\n");
+		process.exit(2);
+	}
+}
+function validateArgs(args) {
+	if (args.base && (args.baseline || args.updateBaseline)) throw new Error("--base is mutually exclusive with --baseline and --update-baseline");
+	if (args.updateBaseline && !args.baseline) throw new Error("--update-baseline requires --baseline <file>");
+}
+main().catch((err) => {
+	process.stderr.write("stopslop: " + err.message + "\n");
+	process.exit(2);
+});
+//#endregion
+export {};