aislop 0.2.0 → 0.2.1

package/README.md

@@ -10,25 +10,87 @@
 
 `aislop` is a unified code-quality CLI that catches the lazy patterns AI coding tools leave behind. One command, one score out of 100.
 
+`aislop` helps teams review AI-assisted code faster by combining formatting, linting, maintainability, AI-pattern detection, architecture checks, and security checks into a single report.
+
+## See it in action
+
+### Scan
+
+![aislop scan demo](assets/scan.gif)
+
+### Fix
+
+![aislop fix demo](assets/fix.gif)
+
+## Quick start
+
+```bash
+# scan your project
+npx aislop scan
+
+# auto-fix what can be fixed safely
+npx aislop fix
+
+# CI mode (JSON output + quality gate)
+npx aislop ci
 ```
-$ npx aislop scan
 
-aislop Scan v0.2.0
+Sample output:
+
+```text
+aislop scan v0.2.0
 
   ✓ Project my-app (typescript)
   Source files: 142
 
-  ✓ Formatting:      done (0 issues)
-  ✓ Linting:         done (2 warnings)
-  ✓ Code Quality:    done (1 warning)
-  ! Maintainability:  done (4 warnings)
-  ✓ Security:        done (0 issues)
-
-  Score: 80/100 (Healthy)
+  ✓ Formatting: done (0 issues)
+  ! Linting: done (2 warnings)
+  ! Code Quality: done (1 warning)
+  ✓ Maintainability: done (0 issues)
+  ✓ Security: done (0 issues)
+
+------------------------------------------------------------
+Summary
+  Score: 89/100 (Healthy)
+  Issues: 0 errors, 3 warnings
+  Auto-fixable: 2
+  Files: 142
+  Time: 2.3s
+------------------------------------------------------------
 ```
 
 ---
 
+## Why aislop
+
+AI-generated changes often pass review because problems are spread across many files and many categories.
+`aislop` gives you one view and one score.
+
+- **One command, full picture**: formatting + lint + maintainability + AI slop + security (+ architecture)
+- **Score-based quality gate**: use a single 0-100 score in CI and PR checks
+- **Auto-fix support**: remove unused imports, apply lint suggestions, and format in one pass
+- **Duplication visibility**: flag repeated blocks and encourage extraction into shared modules
+- **Software engineering best practices**: enforce function/file size limits, nesting limits, dead code cleanup, and safer patterns
+- **Works across stacks**: TypeScript, JavaScript, Python, Go, Rust, Ruby, PHP, Expo/React Native
+- **Zero-config start**: run `npx aislop scan` and get useful output immediately
+
+## What it catches
+
+Six engines run in parallel: **Formatting**, **Linting**, **Code Quality**, **AI Slop Detection**, **Security**, and **Architecture** (opt-in).
+
+| Engine | Examples |
+|---|---|
+| Formatting | Biome, ruff, gofmt, cargo fmt, rubocop, php-cs-fixer |
+| Linting | oxlint, ruff, golangci-lint, clippy, expo-doctor |
+| Code Quality | Function/file size limits, deep nesting, duplication, dead code, unused dependencies (knip) |
+| AI Slop | Trivial comments, swallowed exceptions, unused imports, console leftovers, type assertion abuse, TODO stubs |
+| Security | Hardcoded secrets, eval, innerHTML, SQL/shell injection, dependency audits |
+| Architecture | Custom import bans, layering rules, required patterns |
+
+See the full [rules reference](docs/rules.md).
+
+---
+
 ## Installation
 
 ```bash
@@ -67,7 +129,7 @@ aislop scan --json         # output JSON
 ### Fix issues automatically
 
 ```bash
-aislop fix                 # auto-fix formatting + lint issues
+aislop fix                 # auto-fix unused imports, formatting, and lint fixes
 ```
 
 ### Use in CI pipelines
@@ -76,6 +138,19 @@ aislop fix                 # auto-fix formatting + lint issues
 aislop ci                  # JSON output, exits 1 if score < threshold
 ```
 
+### Common workflow
+
+```bash
+# before commit
+aislop scan --staged
+
+# during local cleanup
+aislop fix
+
+# full project check
+aislop scan
+```
+
 ### Other commands
 
 ```bash
@@ -103,6 +178,7 @@ npx aislop scan --staged
 - uses: actions/setup-node@v6
   with:
     node-version: 20
+- run: npm ci
 - run: npx aislop ci
 ```
 
@@ -119,34 +195,6 @@ ci:
 
 ---
 
-## Why aislop?
-
-AI-generated code passes review because issues are spread across dozens of files. No single linter catches all of them. `aislop` does:
-
-- **AI-specific pattern detection** — trivial comments, thin wrappers, generic names, swallowed exceptions, `as any` casts
-- **Multi-language** — TypeScript, JavaScript, Python, Go, Rust, Ruby, PHP, Expo/React Native
-- **Single score** — one number to gate PRs, track in CI, and trend over time
-- **Zero config** — run `npx aislop scan` and get results immediately
-- **Framework-aware** — auto-detects Next.js, React, Expo, Vite, Remix, Django, Flask, FastAPI
-- **Batteries included** — ships with oxlint, biome, knip; downloads ruff and golangci-lint on install
-
-## What it catches
-
-Six engines run in parallel: **Formatting**, **Linting**, **Code Quality**, **AI Slop Detection**, **Security**, and **Architecture** (opt-in).
-
-| Engine | Examples |
-|---|---|
-| Formatting | Biome, ruff, gofmt, cargo fmt, rubocop, php-cs-fixer |
-| Linting | oxlint, ruff, golangci-lint, clippy, expo-doctor |
-| Code Quality | Function/file size limits, deep nesting, duplication, dead code, unused dependencies (knip) |
-| AI Slop | Trivial comments, swallowed exceptions, unused imports, console leftovers, type assertion abuse, TODO stubs |
-| Security | Hardcoded secrets, eval, innerHTML, SQL/shell injection, dependency audits |
-| Architecture | Custom import bans, layering rules, required patterns |
-
-See the full [rules reference](docs/rules.md) for all 30+ built-in rules.
-
----
-
 ## Documentation
 
 | Topic | Link |

package/dist/cli.js

@@ -872,6 +872,7 @@ const JS_EXTENSIONS = new Set([
 	".cjs"
 ]);
 const PY_EXTENSIONS = new Set([".py"]);
+const REMOVE_MARKER = "\0__AISLOP_REMOVE__";
 const extractJsImportedSymbols = (lines) => {
 	const symbols = [];
 	const importLines = /* @__PURE__ */ new Set();
@@ -980,32 +981,47 @@ const isSymbolUsed = (name, content, importLines, lines) => {
 	}
 	return false;
 };
+const analyzeFile = (filePath) => {
+	if (isAutoGenerated(filePath)) return null;
+	let content;
+	try {
+		content = fs.readFileSync(filePath, "utf-8");
+	} catch {
+		return null;
+	}
+	const ext = path.extname(filePath);
+	const lines = content.split("\n");
+	let symbols;
+	let importLines;
+	if (JS_EXTENSIONS.has(ext)) {
+		const result = extractJsImportedSymbols(lines);
+		symbols = result.symbols;
+		importLines = result.importLines;
+	} else if (PY_EXTENSIONS.has(ext)) {
+		const result = extractPyImportedSymbols(lines);
+		symbols = result.symbols;
+		importLines = result.importLines;
+	} else return null;
+	return {
+		lines,
+		symbols,
+		importLines,
+		ext
+	};
+};
+const getUnusedSymbols = (lines, symbols, importLines) => {
+	const content = lines.join("\n");
+	return symbols.filter((symbol) => !isSymbolUsed(symbol.name, content, importLines, lines));
+};
 const detectUnusedImports = async (context) => {
 	const files = getSourceFiles(context);
 	const diagnostics = [];
 	for (const filePath of files) {
-		if (isAutoGenerated(filePath)) continue;
-		let content;
-		try {
-			content = fs.readFileSync(filePath, "utf-8");
-		} catch {
-			continue;
-		}
-		const ext = path.extname(filePath);
+		const analysis = analyzeFile(filePath);
+		if (!analysis) continue;
 		const relativePath = path.relative(context.rootDirectory, filePath);
-		const lines = content.split("\n");
-		let symbols;
-		let importLinesSet;
-		if (JS_EXTENSIONS.has(ext)) {
-			const result = extractJsImportedSymbols(lines);
-			symbols = result.symbols;
-			importLinesSet = result.importLines;
-		} else if (PY_EXTENSIONS.has(ext)) {
-			const result = extractPyImportedSymbols(lines);
-			symbols = result.symbols;
-			importLinesSet = result.importLines;
-		} else continue;
-		for (const symbol of symbols) if (!isSymbolUsed(symbol.name, content, importLinesSet, lines)) diagnostics.push({
+		const unused = getUnusedSymbols(analysis.lines, analysis.symbols, analysis.importLines);
+		for (const symbol of unused) diagnostics.push({
 			filePath: relativePath,
 			engine: "ai-slop",
 			rule: "ai-slop/unused-import",
@@ -1922,14 +1938,11 @@ const parseBiomeJsonOutput = (output, rootDir) => {
 const fixBiomeFormat = async (context) => {
 	const targets = getBiomeTargets(context);
 	if (targets.length === 0) return;
-	const result = await runBiome([
-		"check",
+	await runBiome([
+		"format",
 		"--write",
-		"--formatter-enabled=true",
-		"--linter-enabled=false",
 		...targets
 	], context.rootDirectory, 6e4);
-	if (result.exitCode !== 0) throw new Error(result.stderr || result.stdout || `Biome exited with code ${result.exitCode}`);
 };
 
 //#endregion
@@ -2492,6 +2505,7 @@ const fixOxlint = async (context) => {
 			"-c",
 			configPath,
 			"--fix",
+			"--fix-suggestions",
 			"."
 		];
 		const result = await runSubprocess(process.execPath, args, {
@@ -3180,14 +3194,13 @@ const logger = {
 * Application version — injected at build time by tsdown from package.json.
 * The fallback should always match the "version" field in package.json.
 */
-const APP_VERSION = "0.2.0";
+const APP_VERSION = "0.2.1";
 
 //#endregion
 //#region src/output/layout.ts
 const formatElapsed$1 = (elapsedMs) => elapsedMs < 1e3 ? `${Math.round(elapsedMs)}ms` : `${(elapsedMs / 1e3).toFixed(1)}s`;
 const printCommandHeader = (commandName) => {
-	logger.log(highlighter.bold(`aislop ${commandName}`));
-	logger.log(highlighter.dim(`v${APP_VERSION}`));
+	logger.log(`${highlighter.bold(`aislop ${commandName.toLowerCase()}`)} ${highlighter.dim(`v${APP_VERSION}`)}`);
 	logger.break();
 };
 const formatProjectSummary = (project) => `Project ${highlighter.info(project.projectName)} (${highlighter.info(project.languages.join(", "))})`;
@@ -3198,81 +3211,6 @@ const printProjectMetadata = (project) => {
 	logger.break();
 };
 
-//#endregion
-//#region src/output/pager.ts
-const DEFAULT_COLUMNS = 80;
-const DEFAULT_ROWS = 24;
-const ANSI_PATTERN = new RegExp(String.raw`\u001B\[[0-?]*[ -/]*[@-~]`, "g");
-const stripAnsi = (text) => text.replace(ANSI_PATTERN, "");
-const resolvePagerCommand = () => {
-	const pager = process.env.PAGER?.trim();
-	if (pager) {
-		const [command, ...args] = pager.split(/\s+/);
-		if (command) return {
-			command,
-			args
-		};
-	}
-	return {
-		command: "less",
-		args: [
-			"-R",
-			"-F",
-			"-X"
-		]
-	};
-};
-const writeToStdout = (text) => {
-	process.stdout.write(text);
-};
-const pipeToPager = async (command, args, text) => new Promise((resolve) => {
-	let settled = false;
-	const finish = (success) => {
-		if (settled) return;
-		settled = true;
-		resolve(success);
-	};
-	try {
-		const child = spawn(command, args, {
-			stdio: [
-				"pipe",
-				"inherit",
-				"inherit"
-			],
-			windowsHide: true
-		});
-		child.once("error", () => finish(false));
-		child.once("close", (code) => finish(code === 0));
-		child.stdin?.on("error", () => void 0);
-		child.stdin?.end(text);
-	} catch {
-		finish(false);
-	}
-});
-const countRenderedLines = (text, columns = DEFAULT_COLUMNS) => {
-	const width = Math.max(1, columns);
-	return text.split("\n").reduce((count, line) => {
-		const visibleLine = stripAnsi(line).replaceAll("	", "    ");
-		return count + Math.max(1, Math.ceil(visibleLine.length / width));
-	}, 0);
-};
-const shouldPageOutput = (text, options = {}) => {
-	if (text.trim().length === 0) return false;
-	const stdinIsTTY = options.stdinIsTTY ?? Boolean(process.stdin.isTTY);
-	const stdoutIsTTY = options.stdoutIsTTY ?? Boolean(process.stdout.isTTY);
-	if (!stdinIsTTY || !stdoutIsTTY) return false;
-	const rows = Math.max(1, options.rows ?? process.stdout.rows ?? DEFAULT_ROWS);
-	return countRenderedLines(text, Math.max(1, options.columns ?? process.stdout.columns ?? DEFAULT_COLUMNS)) > rows - 1;
-};
-const printMaybePaged = async (text) => {
-	if (!shouldPageOutput(text)) {
-		writeToStdout(text);
-		return;
-	}
-	const pager = resolvePagerCommand();
-	if (!await pipeToPager(pager.command, pager.args, text)) writeToStdout(text);
-};
-
 //#endregion
 //#region src/output/scan-progress.ts
 const SPINNER_FRAMES = [
@@ -3882,12 +3820,13 @@ const scanCommand = async (directory, config, options) => {
 		console.log(JSON.stringify(jsonOut, null, 2));
 		return { exitCode };
 	}
-	await printMaybePaged([
+	const output = [
 		"",
 		allDiagnostics.length === 0 ? `${highlighter.success("  ✓ No issues found.")}\n` : renderDiagnostics(allDiagnostics, options.verbose),
 		renderSummary(allDiagnostics, scoreResult, elapsedMs, projectInfo.sourceFileCount, config.scoring.thresholds),
 		""
-	].join("\n"));
+	].join("\n");
+	process.stdout.write(output);
 	return { exitCode };
 };
 
@@ -4037,6 +3976,99 @@ const doctorCommand = async (directory) => {
 	printDoctorConclusion(isAllGood());
 };
 
+//#endregion
+//#region src/engines/ai-slop/unused-imports-fix.ts
+const fixUnusedImports = async (context) => {
+	const files = getSourceFiles(context);
+	for (const filePath of files) {
+		const analysis = analyzeFile(filePath);
+		if (!analysis) continue;
+		const unused = getUnusedSymbols(analysis.lines, analysis.symbols, analysis.importLines);
+		if (unused.length === 0) continue;
+		const unusedNames = new Set(unused.map((u) => u.name));
+		const lines = [...analysis.lines];
+		const symbolsByLine = /* @__PURE__ */ new Map();
+		for (const sym of analysis.symbols) {
+			const arr = symbolsByLine.get(sym.line) ?? [];
+			arr.push(sym);
+			symbolsByLine.set(sym.line, arr);
+		}
+		const linesToRemove = /* @__PURE__ */ new Set();
+		for (const [lineNo, syms] of symbolsByLine) {
+			const lineIdx = lineNo - 1;
+			const allUnused = syms.every((s) => unusedNames.has(s.name));
+			const importSpan = getImportSpan(lineIdx, analysis.importLines);
+			if (allUnused) for (const idx of importSpan) linesToRemove.add(idx);
+			else if (JS_EXTENSIONS.has(analysis.ext)) rewriteJsImportSpan(lines, importSpan, syms, unusedNames);
+			else if (PY_EXTENSIONS.has(analysis.ext)) rewritePyImportLine(lines, lineIdx, syms, unusedNames);
+		}
+		if (linesToRemove.size === 0 && unused.length === 0) continue;
+		const sortedRemove = [...linesToRemove].sort((a, b) => b - a);
+		for (const idx of sortedRemove) lines.splice(idx, 1);
+		const filtered = lines.filter((l) => l !== REMOVE_MARKER);
+		while (filtered.length > 0 && filtered[0].trim() === "") filtered.shift();
+		fs.writeFileSync(filePath, filtered.join("\n"));
+	}
+};
+const getImportSpan = (startIdx, importLines) => {
+	const span = [startIdx];
+	let idx = startIdx + 1;
+	while (importLines.has(idx)) {
+		span.push(idx);
+		idx++;
+	}
+	return span;
+};
+const rewriteJsImportSpan = (lines, span, syms, unusedNames) => {
+	const fullImport = span.map((i) => lines[i]).join("\n");
+	const namedMatch = fullImport.match(/\{([^}]+)\}/s);
+	if (!namedMatch) return;
+	const unusedNamed = syms.filter((s) => !s.isDefault && !s.isNamespace && unusedNames.has(s.name));
+	if (unusedNamed.length === 0) return;
+	const unusedNamedSet = new Set(unusedNamed.map((s) => s.name));
+	const keptSpecifiers = namedMatch[1].split(",").map((s) => s.trim()).filter(Boolean).filter((spec) => {
+		const parts = spec.split(/\s+as\s+/);
+		const localName = parts.length > 1 ? parts[1].trim().replace(/^type\s+/, "") : parts[0].trim().replace(/^type\s+/, "");
+		return !unusedNamedSet.has(localName);
+	});
+	if (keptSpecifiers.length === 0) {
+		if (syms.find((s) => s.isDefault && !unusedNames.has(s.name))) {
+			const rewritten = fullImport.replace(/,\s*\{[^}]*\}/s, "").replace(/\{[^}]*\}\s*,?\s*/s, "");
+			lines[span[0]] = rewritten.replace(/\n/g, " ").replace(/\s+/g, " ");
+			for (let i = 1; i < span.length; i++) lines[span[i]] = REMOVE_MARKER;
+		}
+		return;
+	}
+	const fromMatch = fullImport.match(/\}\s*(from\s+.+)$/s);
+	const fromClause = fromMatch ? fromMatch[1].trim() : "";
+	const importPrefix = fullImport.match(/^(import\s+(?:\w+\s*,\s*)?)/);
+	const prefix = importPrefix ? importPrefix[1] : "import ";
+	const wasMultiLine = span.length > 1;
+	let newImport;
+	if (wasMultiLine && keptSpecifiers.length > 2) {
+		const indentMatch = lines[span[1]]?.match(/^(\s+)/);
+		const indent = indentMatch ? indentMatch[1] : "	";
+		newImport = `${prefix}{\n${keptSpecifiers.map((s) => `${indent}${s},`).join("\n")}\n} ${fromClause}`;
+	} else newImport = `${prefix}{ ${keptSpecifiers.join(", ")} } ${fromClause}`;
+	lines[span[0]] = newImport;
+	for (let i = 1; i < span.length; i++) lines[span[i]] = REMOVE_MARKER;
+};
+const rewritePyImportLine = (lines, lineIdx, syms, unusedNames) => {
+	const fromMatch = lines[lineIdx].match(/^(\s*from\s+[\w.]+\s+import\s+)(.+)$/);
+	if (!fromMatch) return;
+	const prefix = fromMatch[1];
+	const importPart = fromMatch[2].replace(/#.*$/, "").trim();
+	const hasParen = importPart.startsWith("(");
+	const keptSpecifiers = importPart.replace(/[()]/g, "").split(",").map((s) => s.trim()).filter((spec) => {
+		const parts = spec.split(/\s+as\s+/);
+		const localName = parts.length > 1 ? parts[1].trim() : parts[0].trim();
+		return !unusedNames.has(localName);
+	});
+	if (keptSpecifiers.length === 0) return;
+	const joined = keptSpecifiers.join(", ");
+	lines[lineIdx] = hasParen ? `${prefix}(${joined})` : `${prefix}${joined}`;
+};
+
 //#endregion
 //#region src/commands/fix.ts
 const uniqueFiles = (diagnostics) => [...new Set(diagnostics.map((d) => d.filePath))];
@@ -4091,7 +4123,7 @@ const runFixStep = async (name, detect, applyFix, options) => {
 	}
 	lines.push(...getFilePreviewLines("Affected", uniqueFiles(before), options.verbose));
 	if (after.length > 0) lines.push(...getFilePreviewLines("Remaining", uniqueFiles(after), options.verbose));
-	await printMaybePaged(`${lines.join("\n")}\n\n`);
+	process.stdout.write(`${lines.join("\n")}\n\n`);
 	return result;
 };
 const createEngineContext = (rootDirectory, projectInfo, config) => ({
@@ -4134,13 +4166,7 @@ const fixCommand = async (directory, config, options = {
 	printProjectMetadata(projectInfo);
 	const context = createEngineContext(resolvedDir, projectInfo, config);
 	const steps = [];
-	if (config.engines.format) {
-		if (projectInfo.languages.includes("typescript") || projectInfo.languages.includes("javascript")) steps.push(await runFixStep("JS/TS formatting", () => runBiomeFormat(context), () => fixBiomeFormat(context), options));
-		if (projectInfo.languages.includes("python") && projectInfo.installedTools.ruff) steps.push(await runFixStep("Python formatting", () => runRuffFormat(context), () => fixRuffFormat(resolvedDir), options));
-		else if (projectInfo.languages.includes("python")) logger.warn("  Python detected but ruff is not installed; skipping Python formatting fixes.");
-		if (projectInfo.languages.includes("go") && projectInfo.installedTools.gofmt) steps.push(await runFixStep("Go formatting", () => runGofmt(context), () => fixGofmt(resolvedDir), options));
-		else if (projectInfo.languages.includes("go")) logger.warn("  Go detected but gofmt is not installed; skipping Go formatting fixes.");
-	}
+	if (config.engines["ai-slop"]) steps.push(await runFixStep("Unused imports", () => detectUnusedImports(context), () => fixUnusedImports(context), options));
 	if (config.engines.lint) {
 		if (projectInfo.languages.includes("typescript") || projectInfo.languages.includes("javascript")) steps.push(await runFixStep("JS/TS lint fixes", () => runOxlint(context), () => fixOxlint(context), options));
 		if (projectInfo.languages.includes("python") && projectInfo.installedTools.ruff) steps.push(await runFixStep("Python lint fixes", () => runRuffLint(context), () => fixRuffLint(resolvedDir), options));
@@ -4149,6 +4175,13 @@ const fixCommand = async (directory, config, options = {
 	if (config.engines["code-quality"]) {
 		if (projectInfo.languages.includes("typescript") || projectInfo.languages.includes("javascript")) steps.push(await runFixStep("Unused dependencies", () => runKnipDependencyCheck(resolvedDir), () => fixUnusedDependencies(resolvedDir), options));
 	}
+	if (config.engines.format) {
+		if (projectInfo.languages.includes("typescript") || projectInfo.languages.includes("javascript")) steps.push(await runFixStep("JS/TS formatting", () => runBiomeFormat(context), () => fixBiomeFormat(context), options));
+		if (projectInfo.languages.includes("python") && projectInfo.installedTools.ruff) steps.push(await runFixStep("Python formatting", () => runRuffFormat(context), () => fixRuffFormat(resolvedDir), options));
+		else if (projectInfo.languages.includes("python")) logger.warn("  Python detected but ruff is not installed; skipping Python formatting fixes.");
+		if (projectInfo.languages.includes("go") && projectInfo.installedTools.gofmt) steps.push(await runFixStep("Go formatting", () => runGofmt(context), () => fixGofmt(resolvedDir), options));
+		else if (projectInfo.languages.includes("go")) logger.warn("  Go detected but gofmt is not installed; skipping Go formatting fixes.");
+	}
 	if (steps.length === 0) logger.dim("  No applicable auto-fixers found for this project.");
 	else {
 		logger.break();
@@ -4289,7 +4322,7 @@ const rulesCommand = async (directory) => {
 			lines.push("");
 		}
 	}
-	await printMaybePaged(`${lines.join("\n")}\n`);
+	process.stdout.write(`${lines.join("\n")}\n`);
 };
 
 //#endregion

package/dist/{engine-info-DpU0WTTj.js → engine-info-DFze-2GQ.js}

@@ -3,7 +3,7 @@
 * Application version — injected at build time by tsdown from package.json.
 * The fallback should always match the "version" field in package.json.
 */
-const APP_VERSION = "0.2.0";
+const APP_VERSION = "0.2.1";
 
 //#endregion
 //#region src/output/engine-info.ts