pi-lens 2.2.9 → 3.0.0

package/clients/dispatch/runners/shellcheck.test.ts

@@ -0,0 +1,129 @@
+/**
+ * Tests for shellcheck runner
+ */
+
+import * as fs from "node:fs";
+import { createRequire } from "node:module";
+import * as path from "node:path";
+import { describe, expect, it } from "vitest";
+import type { DispatchContext } from "../types.js";
+
+function createMockContext(filePath: string): DispatchContext {
+	return {
+		filePath,
+		cwd: process.cwd(),
+		kind: "shell" as any,
+		autofix: false,
+		deltaMode: false,
+		baselines: { get: () => [], add: () => {}, save: () => {} } as any,
+		pi: {} as any,
+		hasTool: async () => false,
+		log: () => {},
+	};
+}
+
+// Helper for safe file cleanup
+function safeUnlink(filePath: string): void {
+	try {
+		if (fs.existsSync(filePath)) {
+			fs.unlinkSync(filePath);
+		}
+	} catch {
+		// Ignore cleanup errors on Windows
+	}
+}
+
+describe("shellcheck runner", () => {
+	const require = createRequire(import.meta.url);
+
+	it("should have correct runner definition", async () => {
+		const shellcheckModule = await import("./shellcheck.js");
+		const runner = shellcheckModule.default;
+
+		expect(runner.id).toBe("shellcheck");
+		expect(runner.appliesTo).toEqual(["shell"]);
+		expect(runner.priority).toBe(20);
+		expect(runner.enabledByDefault).toBe(true);
+		expect(runner.skipTestFiles).toBe(false);
+	});
+
+	it("should detect shellcheck availability", () => {
+		const { spawnSync } =
+			require("node:child_process") as typeof import("node:child_process");
+		const result = spawnSync("shellcheck", ["--version"], {
+			encoding: "utf-8",
+			timeout: 10000,
+			shell: true,
+		});
+		expect(
+			result.error || result.status !== 0 ? "not available" : "available",
+		).toBeTruthy();
+	});
+
+	it("should detect undefined variable", async () => {
+		const tmpFile = path.join(
+			process.env.TEMP || "/tmp",
+			`shellcheck_test_${Date.now()}.sh`,
+		);
+		fs.writeFileSync(
+			tmpFile,
+			["#!/bin/bash", "# Test script with issues", 'echo "\$UNDEFINED_VAR"', ""].join("\n"),
+		);
+
+		try {
+			const shellcheckModule = await import("./shellcheck.js");
+			const runner = shellcheckModule.default;
+			const result = await runner.run(createMockContext(tmpFile));
+
+			if (result.status !== "skipped") {
+				expect(result.diagnostics.length).toBeGreaterThanOrEqual(1);
+				expect(
+					result.diagnostics.some(
+						(d) =>
+							d.tool === "shellcheck" &&
+							(d.message.includes("undefined") ||
+								d.message.includes("SC2154")),
+					),
+				).toBe(true);
+			}
+		} finally {
+			safeUnlink(tmpFile);
+		}
+	});
+
+	it("should pass clean shell scripts", async () => {
+		const tmpFile = path.join(
+			process.env.TEMP || "/tmp",
+			`shellcheck_ok_${Date.now()}.sh`,
+		);
+		fs.writeFileSync(
+			tmpFile,
+			[
+				"#!/bin/bash",
+				"# Clean shell script",
+				"set -euo pipefail",
+				"",
+				"main() {",
+				'    local name="\${1:-world}"',
+				'    echo "Hello, \${name}!"',
+				"}",
+				"",
+				'main "\$@"',
+				"",
+			].join("\n"),
+		);
+
+		try {
+			const shellcheckModule = await import("./shellcheck.js");
+			const runner = shellcheckModule.default;
+			const result = await runner.run(createMockContext(tmpFile));
+
+			if (result.status !== "skipped") {
+				expect(result.diagnostics.length).toBe(0);
+				expect(result.status).toBe("succeeded");
+			}
+		} finally {
+			safeUnlink(tmpFile);
+		}
+	});
+});

package/clients/dispatch/runners/shellcheck.ts

@@ -0,0 +1,188 @@
+/**
+ * Shellcheck runner for dispatch system
+ *
+ * Industry-standard linter for shell scripts (bash, sh, zsh).
+ * Detects syntax errors, undefined variables, quoting issues, and best practices.
+ *
+ * Why shellcheck?
+ * - Industry standard (used in CI/CD everywhere)
+ * - Comprehensive checks (syntax, variables, quotes, best practices)
+ * - JSON output for easy parsing
+ * - Available on all platforms (apt, brew, cargo, etc.)
+ *
+ * Alternative considered: bash-language-server
+ * - LSP approach like OpenCode uses
+ * - Richer features but heavier
+ * - shellcheck is simpler and faster for basic linting
+ *
+ * Install: apt install shellcheck, brew install shellcheck, or cargo install shellcheck
+ *
+ * Config: .shellcheckrc (optional, zero-config works)
+ */
+
+import { safeSpawn } from "../../safe-spawn.js";
+import {
+	createAvailabilityChecker,
+	createConfigFinder,
+} from "./utils/runner-helpers.js";
+import type {
+	Diagnostic,
+	DispatchContext,
+	RunnerDefinition,
+	RunnerResult,
+} from "../types.js";
+
+const shellcheck = createAvailabilityChecker("shellcheck", ".exe");
+const findShellcheckConfig = createConfigFinder(".shellcheckrc");
+
+/**
+ * Parse shellcheck JSON output
+ *
+ * Format: Array of check objects
+ * [{
+ *   "file": "script.sh",
+ *   "line": 10,
+ *   "endLine": 10,
+ *   "column": 5,
+ *   "endColumn": 10,
+ *   "level": "warning",
+ *   "code": 2154,
+ *   "message": "var is referenced but not assigned.",
+ *   "fix": null
+ * }]
+ *
+ * Levels: "error", "warning", "info", "style"
+ */
+function parseShellcheckOutput(raw: string, filePath: string): Diagnostic[] {
+	const diagnostics: Diagnostic[] = [];
+
+	if (!raw.trim()) {
+		return diagnostics;
+	}
+
+	try {
+		const parsed = JSON.parse(raw) as Array<{
+			file?: string;
+			line?: number;
+			endLine?: number;
+			column?: number;
+			endColumn?: number;
+			level?: string;
+			code?: number;
+			message?: string;
+			fix?: unknown;
+		}>;
+
+		if (!Array.isArray(parsed)) {
+			return diagnostics;
+		}
+
+		for (const item of parsed) {
+			if (!item.message || !item.line) continue;
+
+			// Map shellcheck levels to our severity
+			const severityMap: Record<string, "error" | "warning" | "info"> = {
+				error: "error",
+				warning: "warning",
+				info: "info",
+				style: "info",
+			};
+			const severity = severityMap[item.level || "warning"] || "warning";
+
+			const ruleCode = item.code ? `SC${item.code}` : "unknown";
+
+			diagnostics.push({
+				id: `shellcheck-${item.line}-${ruleCode}`,
+				message: `[${ruleCode}] ${item.message}`,
+				filePath,
+				line: item.line,
+				column: item.column || 1,
+				severity,
+				semantic: severity === "error" ? "blocking" : "warning",
+				tool: "shellcheck",
+				rule: ruleCode,
+				fixable: !!item.fix,
+			});
+		}
+	} catch {
+		// JSON parse failed, return empty
+		return diagnostics;
+	}
+
+	return diagnostics;
+}
+
+const shellcheckRunner: RunnerDefinition = {
+	id: "shellcheck",
+	appliesTo: ["shell"],
+	priority: 20,
+	enabledByDefault: true,
+	skipTestFiles: false, // Shell scripts in test directories should still be checked
+
+	async run(ctx: DispatchContext): Promise<RunnerResult> {
+		// Skip if shellcheck is not installed
+		if (!shellcheck.isAvailable(ctx.cwd || process.cwd())) {
+			return { status: "skipped", diagnostics: [], semantic: "none" };
+		}
+
+		// Check if user explicitly disabled shellcheck
+		if (ctx.pi.getFlag("no-shellcheck")) {
+			return { status: "skipped", diagnostics: [], semantic: "none" };
+		}
+
+		// Determine shell dialect from file extension
+		const shellDialect = ctx.filePath.endsWith(".zsh")
+			? "bash"
+			: ctx.filePath.endsWith(".fish")
+				? "bash"
+				: ctx.filePath.endsWith(".sh")
+					? "bash"
+					: "bash"; // Default to bash for generic shell files
+
+		// Build args
+		// --format json: JSON output
+		// --shell: Specify shell dialect (bash, sh, zsh, ksh, busybox)
+		// --severity: Minimum severity (we'll filter ourselves)
+		const args: string[] = [
+			"--format",
+			"json",
+			"--shell",
+			shellDialect,
+		];
+
+		// Check for config file
+		const configPath = findShellcheckConfig(ctx.cwd);
+		if (!configPath) {
+			// No config file, use default settings
+			// Exclude "style" and "info" by default to reduce noise
+			args.push("--severity", "warning");
+		}
+
+		args.push(ctx.filePath);
+
+		const result = safeSpawn(shellcheck.getCommand()!, args, {
+			timeout: 15000,
+		});
+
+		// shellcheck exits with code 1 if issues found, 0 if clean
+		if (result.status === 0 && !result.stdout?.trim()) {
+			return { status: "succeeded", diagnostics: [], semantic: "none" };
+		}
+
+		// Parse diagnostics
+		const raw = result.stdout + result.stderr;
+		const diagnostics = parseShellcheckOutput(raw, ctx.filePath);
+
+		if (diagnostics.length === 0) {
+			return { status: "succeeded", diagnostics: [], semantic: "none" };
+		}
+
+		return {
+			status: "failed",
+			diagnostics,
+			semantic: "warning",
+		};
+	},
+};
+
+export default shellcheckRunner;

package/clients/dispatch/runners/similarity.js

@@ -0,0 +1,230 @@
+/**
+ * Similarity Runner: Detect semantic code reuse opportunities
+ *
+ * Uses Amain's 57×72 state matrix algorithm to find similar functions.
+ * Integrated into dispatch flow as a warning (non-blocking) suggestion.
+ */
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import * as ts from "typescript";
+import { EXCLUDED_DIRS } from "../../file-utils.js";
+import { buildProjectIndex, findSimilarFunctions, loadIndex, } from "../../project-index.js";
+import { buildStateMatrix, countTransitions } from "../../state-matrix.js";
+// ============================================================================
+// Configuration
+// ============================================================================
+const CONFIG = {
+    SIMILARITY_THRESHOLD: 0.75, // 75% minimum similarity
+    MIN_TRANSITIONS: 20, // Skip functions with <20 AST transitions
+    MAX_SUGGESTIONS: 3, // Max 3 suggestions per file
+    USAGE_THRESHOLD: 2, // Only suggest utilities with 2+ uses (placeholder)
+};
+// ============================================================================
+// Runner Implementation
+// ============================================================================
+const similarityRunner = {
+    id: "similarity",
+    appliesTo: ["jsts"], // TypeScript/JavaScript only for MVP
+    priority: 35, // After ts-lsp, before ast-grep
+    enabledByDefault: true,
+    async run(ctx) {
+        const { filePath } = ctx;
+        // Only check TypeScript files
+        if (!filePath.match(/\.tsx?$/)) {
+            return { status: "skipped", diagnostics: [], semantic: "none" };
+        }
+        // Load file content
+        const content = await fs.readFile(filePath, "utf-8").catch(() => null);
+        if (!content) {
+            return { status: "skipped", diagnostics: [], semantic: "none" };
+        }
+        // Find project root and load index
+        const projectRoot = await findProjectRoot(filePath);
+        if (!projectRoot) {
+            return { status: "skipped", diagnostics: [], semantic: "none" };
+        }
+        const index = await loadOrBuildIndex(projectRoot);
+        if (!index || index.entries.size === 0) {
+            return { status: "skipped", diagnostics: [], semantic: "none" };
+        }
+        // Parse the file
+        const sourceFile = ts.createSourceFile(filePath, content, ts.ScriptTarget.Latest, true, ts.ScriptKind.TS);
+        // Extract functions and check for similarities
+        const newFunctions = extractFunctions(sourceFile, content);
+        const diagnostics = [];
+        for (const func of newFunctions) {
+            // Guardrail: Skip tiny functions
+            if (func.transitionCount < CONFIG.MIN_TRANSITIONS) {
+                continue;
+            }
+            // Find similar functions in index
+            const matches = findSimilarFunctions(func.matrix, index, CONFIG.SIMILARITY_THRESHOLD, CONFIG.MAX_SUGGESTIONS);
+            // Create diagnostic for each match
+            for (const match of matches) {
+                // Skip if it's the same function (self-match by path/name)
+                if (match.targetId ===
+                    `${path.relative(projectRoot, filePath)}:${func.name}`) {
+                    continue;
+                }
+                diagnostics.push({
+                    id: `similarity-${func.name}-${match.targetId}`,
+                    tool: "similarity",
+                    filePath,
+                    line: func.line,
+                    column: func.column,
+                    message: buildSuggestionMessage(func, match),
+                    severity: "warning", // 🟡 Not blocking
+                    semantic: "warning",
+                });
+            }
+        }
+        // Return limited number of suggestions
+        const limitedResults = diagnostics.slice(0, CONFIG.MAX_SUGGESTIONS);
+        if (limitedResults.length === 0) {
+            return { status: "succeeded", diagnostics: [], semantic: "none" };
+        }
+        return {
+            status: "succeeded",
+            diagnostics: limitedResults,
+            semantic: "warning",
+        };
+    },
+};
+function extractFunctions(sourceFile, _fullContent) {
+    const functions = [];
+    function visit(node) {
+        // Function declarations
+        if (ts.isFunctionDeclaration(node) && node.name) {
+            const { line, character } = sourceFile.getLineAndCharacterOfPosition(node.getStart(sourceFile));
+            const funcCode = getNodeText(node, sourceFile);
+            const matrix = buildStateMatrix(funcCode);
+            const transitionCount = countTransitions(matrix);
+            functions.push({
+                name: node.name.text,
+                line: line + 1, // 1-indexed
+                column: character + 1, // 1-indexed
+                matrix,
+                transitionCount,
+                signature: getSignature(node),
+            });
+        }
+        // Arrow functions assigned to const
+        if (ts.isVariableStatement(node)) {
+            extractArrowFunctions(node, functions, sourceFile);
+        }
+        ts.forEachChild(node, visit);
+    }
+    visit(sourceFile);
+    return functions;
+}
+function extractArrowFunctions(node, functions, sourceFile) {
+    for (const decl of node.declarationList.declarations) {
+        if (!ts.isIdentifier(decl.name) || !decl.initializer) {
+            continue;
+        }
+        const func = decl.initializer;
+        if (!ts.isArrowFunction(func) && !ts.isFunctionExpression(func)) {
+            continue;
+        }
+        const { line, character } = sourceFile.getLineAndCharacterOfPosition(node.getStart(sourceFile));
+        const funcCode = getNodeText(func, sourceFile);
+        const matrix = buildStateMatrix(funcCode);
+        const transitionCount = countTransitions(matrix);
+        functions.push({
+            name: decl.name.text,
+            line: line + 1,
+            column: character + 1,
+            matrix,
+            transitionCount,
+            signature: getArrowSignature(func),
+        });
+    }
+}
+function getNodeText(node, sourceFile) {
+    return sourceFile.text.substring(node.getStart(sourceFile), node.getEnd());
+}
+function getSignature(node) {
+    const params = node.parameters
+        .map((p) => (ts.isIdentifier(p.name) ? p.name.text : "param"))
+        .join(", ");
+    return `(${params})`;
+}
+function getArrowSignature(node) {
+    const params = node.parameters
+        .map((p) => (ts.isIdentifier(p.name) ? p.name.text : "param"))
+        .join(", ");
+    return `(${params})`;
+}
+// ============================================================================
+// Message Building
+// ============================================================================
+function buildSuggestionMessage(func, match) {
+    const similarityPct = Math.round(match.similarity * 100);
+    const parts = match.targetId.split(":");
+    const file = parts[0];
+    const name = parts[1] || match.targetName;
+    const location = `${file}:1`; // TODO: get actual line
+    return `Function '${func.name}' has ${similarityPct}% similarity to existing utility '${name}()' in ${location}. Consider reusing the existing utility.`;
+}
+// ============================================================================
+// Index Management
+// ============================================================================
+const indexCache = new Map();
+async function findProjectRoot(filePath) {
+    let dir = path.dirname(filePath);
+    while (dir !== path.dirname(dir)) {
+        try {
+            await fs.access(path.join(dir, "package.json"));
+            return dir;
+        }
+        catch {
+            dir = path.dirname(dir);
+        }
+    }
+    return null;
+}
+async function loadOrBuildIndex(projectRoot) {
+    // Check cache
+    const cached = indexCache.get(projectRoot);
+    if (cached) {
+        return cached;
+    }
+    // Try to load existing index
+    const existing = await loadIndex(projectRoot);
+    if (existing) {
+        indexCache.set(projectRoot, existing);
+        return existing;
+    }
+    // Build new index
+    const { glob } = await import("glob");
+    // Build ignore patterns from centralized EXCLUDED_DIRS
+    const ignorePatterns = [
+        ...EXCLUDED_DIRS.map((d) => `**/${d}/**`),
+        "**/*.test.ts",
+        "**/*.spec.ts",
+        "**/*.poc.test.ts",
+    ];
+    const files = await glob("**/*.ts", {
+        cwd: projectRoot,
+        ignore: ignorePatterns,
+    });
+    if (files.length === 0) {
+        return null;
+    }
+    const absoluteFiles = files.map((f) => path.join(projectRoot, f));
+    const index = await buildProjectIndex(projectRoot, absoluteFiles);
+    indexCache.set(projectRoot, index);
+    return index;
+}
+// ============================================================================
+// Testing Helper
+// ============================================================================
+export async function buildIndexForTesting(projectRoot) {
+    const index = await loadOrBuildIndex(projectRoot);
+    if (!index) {
+        throw new Error("Failed to build index");
+    }
+    return index;
+}
+export { CONFIG };
+export default similarityRunner;