pi-lens 2.2.9 → 3.0.0

package/commands/clients/file-kinds.js

@@ -0,0 +1,177 @@
+/**
+ * File Kind Detection for pi-lens
+ *
+ * Centralized file type detection to avoid duplication across clients.
+ * Maps file extensions and paths to semantic file kinds.
+ */
+import { basename, extname } from "node:path";
+// --- Extension Maps ---
+const KIND_EXTENSIONS = {
+    jsts: [".js", ".jsx", ".ts", ".tsx", ".mjs", ".cjs", ".svelte"],
+    python: [".py"],
+    go: [".go"],
+    rust: [".rs"],
+    cxx: [
+        ".c",
+        ".cc",
+        ".cpp",
+        ".cxx",
+        ".h",
+        ".hh",
+        ".hpp",
+        ".hxx",
+        ".ixx",
+        ".ipp",
+        ".inl",
+        ".tpp",
+        ".txx",
+    ],
+    cmake: [".cmake"],
+    shell: [".sh", ".bash", ".zsh", ".fish"],
+    json: [".json", ".jsonc", ".json5"],
+    markdown: [".md", ".mdx"],
+    css: [".css", ".scss", ".sass", ".less"],
+    yaml: [".yaml", ".yml"],
+};
+// Reverse map: extension → file kind (for fast lookup)
+const EXT_TO_KIND = new Map();
+for (const [kind, exts] of Object.entries(KIND_EXTENSIONS)) {
+    for (const ext of exts) {
+        EXT_TO_KIND.set(ext.toLowerCase(), kind);
+    }
+    // Also register without leading dot
+    for (const ext of exts) {
+        if (ext.startsWith(".")) {
+            EXT_TO_KIND.set(ext.slice(1).toLowerCase(), kind);
+        }
+    }
+}
+// Special filenames that indicate a file kind
+const SPECIAL_FILENAMES = [
+    { pattern: /^CMakeLists\.txt$/i, kind: "cmake" },
+    { pattern: /^Makefile$/i, kind: "shell" },
+    { pattern: /^ Dockerfile(\.\w+)?$/i, kind: "shell" },
+];
+// --- Detection Functions ---
+/**
+ * Detect the file kind from a file path.
+ * Returns the semantic file kind or undefined if unknown.
+ */
+export function detectFileKind(filePath) {
+    if (!filePath || typeof filePath !== "string") {
+        return undefined;
+    }
+    // Check special filenames first
+    const base = basename(filePath);
+    for (const { pattern, kind } of SPECIAL_FILENAMES) {
+        if (pattern.test(base)) {
+            return kind;
+        }
+    }
+    // Check by extension
+    const ext = extname(filePath).toLowerCase();
+    return EXT_TO_KIND.get(ext);
+}
+/**
+ * Check if a file kind is supported by a specific tool or capability.
+ *
+ * @example
+ * // Check if TypeScript file
+ * if (isFileKind(filePath, "jsts")) { ... }
+ *
+ * // Check for multiple kinds
+ * if (isFileKind(filePath, ["jsts", "python"])) { ... }
+ */
+export function isFileKind(filePath, kind) {
+    const detected = detectFileKind(filePath);
+    if (!detected)
+        return false;
+    if (Array.isArray(kind)) {
+        return kind.includes(detected);
+    }
+    return detected === kind;
+}
+/**
+ * Get all file kinds that match a given file extension.
+ * Useful for listing which tools might handle a file.
+ */
+export function getFileKindsForExtension(ext) {
+    const normalizedExt = ext.startsWith(".") ? ext : `.${ext}`;
+    const kind = EXT_TO_KIND.get(normalizedExt.toLowerCase());
+    return kind ? [kind] : [];
+}
+/**
+ * Check if a file kind represents a code file (not config/markdown).
+ */
+export function isCodeKind(kind) {
+    return ["jsts", "python", "go", "rust", "cxx", "shell"].includes(kind);
+}
+/**
+ * Check if a file kind represents a text/config file.
+ */
+export function isConfigKind(kind) {
+    return ["json", "yaml", "markdown", "css"].includes(kind);
+}
+/**
+ * Get human-readable description of a file kind.
+ */
+export function getFileKindLabel(kind) {
+    const labels = {
+        jsts: "JavaScript/TypeScript",
+        python: "Python",
+        go: "Go",
+        rust: "Rust",
+        cxx: "C/C++",
+        cmake: "CMake",
+        shell: "Shell",
+        json: "JSON",
+        markdown: "Markdown",
+        css: "CSS",
+        yaml: "YAML",
+    };
+    return labels[kind] ?? kind;
+}
+/**
+ * Get file extensions for a file kind.
+ */
+export function getExtensionsForKind(kind) {
+    return [...(KIND_EXTENSIONS[kind] ?? [])];
+}
+/**
+ * Check if a file should be scanned for linting/formatting.
+ * Excludes test files, generated files, etc.
+ */
+export function isScannableFile(filePath) {
+    const kind = detectFileKind(filePath);
+    if (!kind)
+        return false;
+    // Exclude test files for most kinds
+    const base = basename(filePath);
+    if (base.includes(".test.") ||
+        base.includes(".spec.") ||
+        base.startsWith("test-") ||
+        base.startsWith("spec-")) {
+        return false;
+    }
+    // Only scan code and config files
+    return isCodeKind(kind) || isConfigKind(kind);
+}
+/**
+ * Get the language identifier for LSP/tools that use language IDs.
+ */
+export function getLanguageId(kind) {
+    const languageIds = {
+        jsts: "typescript",
+        python: "python",
+        go: "go",
+        rust: "rust",
+        cxx: "cpp",
+        cmake: "cmake",
+        shell: "shell",
+        json: "json",
+        markdown: "markdown",
+        css: "css",
+        yaml: "yaml",
+    };
+    return languageIds[kind] ?? "plaintext";
+}

package/commands/clients/file-utils.js

@@ -0,0 +1,40 @@
+/**
+ * Shared file path utilities for pi-lens
+ */
+/**
+ * Directories to exclude from all scans (build outputs, dependencies, caches).
+ * Used consistently across all scanners to avoid noise from generated files.
+ */
+export const EXCLUDED_DIRS = [
+    "node_modules",
+    ".git",
+    "dist",
+    "build",
+    ".next",
+    ".pi-lens",
+    ".pi", // pi agent directory
+    ".ruff_cache", // Python linter cache
+    "venv",
+    ".venv",
+    "coverage",
+    "__pycache__",
+    ".tox",
+    ".pytest_cache",
+];
+/**
+ * Check if file path is a test/fixture/mock file.
+ * Used by secrets scanner, rate command, and dispatch runners
+ * to skip these files (false positives on fake credentials, etc).
+ */
+export function isTestFile(filePath) {
+    const normalized = filePath.replace(/\\/g, "/");
+    return (normalized.includes(".test.") ||
+        normalized.includes(".spec.") ||
+        normalized.includes("/test/") ||
+        normalized.includes("/tests/") ||
+        normalized.includes("__tests__/") ||
+        normalized.includes("test-utils") ||
+        normalized.startsWith("test-") ||
+        normalized.includes(".fixture.") ||
+        normalized.includes(".mock."));
+}

package/commands/clients/jscpd-client.js

@@ -0,0 +1,169 @@
+/**
+ * jscpd Client for pi-lens
+ *
+ * Detects copy-paste / duplicate code blocks across the project.
+ * Helps the agent avoid unknowingly duplicating logic that already exists.
+ *
+ * Requires: npm install -D jscpd
+ * Docs: https://github.com/kucherenko/jscpd
+ */
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { safeSpawn } from "./safe-spawn.js";
+// --- Client ---
+export class JscpdClient {
+    available = null;
+    log;
+    constructor(verbose = false) {
+        this.log = verbose ? (msg) => console.error(`[jscpd] ${msg}`) : () => { };
+    }
+    isAvailable() {
+        if (this.available !== null)
+            return this.available;
+        const result = safeSpawn("npx", ["jscpd", "--version"], {
+            timeout: 5000,
+        });
+        this.available = !result.error && result.status === 0;
+        return this.available;
+    }
+    /**
+     * Scan a directory for duplicate code blocks.
+     * Uses a temp output dir to capture JSON report.
+     * @param isTsProject - If true, excludes .js files (they're compiled artifacts in TS projects)
+     */
+    scan(cwd, minLines = 5, minTokens = 50, isTsProject = false) {
+        // Return early for non-existent or empty directories
+        if (!fs.existsSync(cwd)) {
+            return {
+                success: false,
+                clones: [],
+                duplicatedLines: 0,
+                totalLines: 0,
+                percentage: 0,
+            };
+        }
+        const entries = fs.readdirSync(cwd);
+        const hasSourceFiles = entries.some((e) => /\.(ts|tsx|js|jsx)$/.test(e) && !e.endsWith(".d.ts"));
+        if (!hasSourceFiles) {
+            return {
+                success: true,
+                clones: [],
+                duplicatedLines: 0,
+                totalLines: 0,
+                percentage: 0,
+            };
+        }
+        if (!this.isAvailable()) {
+            return {
+                success: false,
+                clones: [],
+                duplicatedLines: 0,
+                totalLines: 0,
+                percentage: 0,
+            };
+        }
+        const outDir = path.join(os.tmpdir(), `pi-lens-jscpd-${Date.now()}`);
+        fs.mkdirSync(outDir, { recursive: true });
+        // Build ignore pattern - exclude .js in TS projects (compiled artifacts)
+        const baseIgnores = "**/node_modules/**,**/dist/**,**/build/**,**/.git/**,**/.pi-lens/**,**/*.md,**/*.txt,**/*.json,**/*.yaml,**/*.yml,**/*.toml,**/*.lock,**/*.test.*,**/*.spec.*,**/*.poc.test.*,**/__tests__/**,**/tests/**";
+        const ignorePattern = isTsProject
+            ? `${baseIgnores},**/*.js,**/*.jsx`
+            : baseIgnores;
+        try {
+            safeSpawn("npx", [
+                "jscpd",
+                ".",
+                "--min-lines",
+                String(minLines),
+                "--min-tokens",
+                String(minTokens),
+                "--reporters",
+                "json",
+                "--output",
+                outDir,
+                "--ignore",
+                ignorePattern,
+            ], {
+                timeout: 30000,
+                cwd,
+            });
+            const reportPath = path.join(outDir, "jscpd-report.json");
+            if (!fs.existsSync(reportPath)) {
+                return {
+                    success: true,
+                    clones: [],
+                    duplicatedLines: 0,
+                    totalLines: 0,
+                    percentage: 0,
+                };
+            }
+            return this.parseReport(reportPath);
+        }
+        catch (err) {
+            this.log(`Scan error: ${err.message}`);
+            return {
+                success: false,
+                clones: [],
+                duplicatedLines: 0,
+                totalLines: 0,
+                percentage: 0,
+            };
+        }
+        finally {
+            try {
+                fs.rmSync(outDir, { recursive: true, force: true });
+            }
+            catch (err) {
+                void err;
+            }
+        }
+    }
+    formatResult(result, maxClones = 8) {
+        if (!result.success || result.clones.length === 0)
+            return "";
+        const pct = result.percentage.toFixed(1);
+        let output = `[jscpd] ${result.clones.length} duplicate block(s) — ${pct}% of codebase (${result.duplicatedLines}/${result.totalLines} lines):\n`;
+        for (const clone of result.clones.slice(0, maxClones)) {
+            const a = `${path.basename(clone.fileA)}:${clone.startA}`;
+            const b = `${path.basename(clone.fileB)}:${clone.startB}`;
+            output += `  ${clone.lines} lines — ${a} ↔ ${b}\n`;
+        }
+        if (result.clones.length > maxClones) {
+            output += `  ... and ${result.clones.length - maxClones} more\n`;
+        }
+        return output;
+    }
+    // --- Internal ---
+    parseReport(reportPath) {
+        try {
+            const data = JSON.parse(fs.readFileSync(reportPath, "utf-8"));
+            // Stats live in statistics.total, not statistics.clones
+            const total = data.statistics?.total ?? {};
+            const duplicatedLines = total.duplicatedLines ?? 0;
+            const totalLines = total.lines ?? 0;
+            const percentage = total.percentage ??
+                (totalLines > 0 ? (duplicatedLines / totalLines) * 100 : 0);
+            const rawClones = data.duplicates ?? [];
+            const clones = rawClones.map((c) => ({
+                fileA: c.firstFile?.name ?? "",
+                startA: c.firstFile?.start ?? 0,
+                fileB: c.secondFile?.name ?? "",
+                startB: c.secondFile?.start ?? 0,
+                lines: c.lines ?? 0,
+                tokens: c.tokens ?? 0,
+            }));
+            return { success: true, clones, duplicatedLines, totalLines, percentage };
+        }
+        catch (err) {
+            void err;
+            return {
+                success: false,
+                clones: [],
+                duplicatedLines: 0,
+                totalLines: 0,
+                percentage: 0,
+            };
+        }
+    }
+}

package/commands/clients/knip-client.js

@@ -0,0 +1,211 @@
+/**
+ * Knip Client for pi-local
+ *
+ * Detects unused exports, files, dependencies, and more.
+ * Essential for safe refactoring — I need to know what's dead code
+ * before I can clean it up.
+ *
+ * Requires: npm install -D knip
+ * Docs: https://knip.dev/
+ */
+import * as path from "node:path";
+import { safeSpawn } from "./safe-spawn.js";
+// --- Client ---
+export class KnipClient {
+    knipAvailable = null;
+    log;
+    constructor(verbose = false) {
+        this.log = verbose
+            ? (msg) => console.error(`[knip] ${msg}`)
+            : () => { };
+    }
+    /**
+     * Check if knip CLI is available
+     */
+    isAvailable() {
+        if (this.knipAvailable !== null)
+            return this.knipAvailable;
+        const result = safeSpawn("npx", ["knip", "--version"], {
+            timeout: 10000,
+        });
+        this.knipAvailable = !result.error && result.status === 0;
+        if (this.knipAvailable) {
+            this.log(`Knip available`);
+        }
+        return this.knipAvailable;
+    }
+    /**
+     * Run knip analysis on the project
+     */
+    analyze(cwd, ignore) {
+        if (!this.isAvailable()) {
+            return {
+                success: false,
+                issues: [],
+                unusedExports: [],
+                unusedFiles: [],
+                unusedDeps: [],
+                unlistedDeps: [],
+                summary: "Knip not available. Install with: npm install -D knip",
+            };
+        }
+        const targetDir = cwd || process.cwd();
+        try {
+            const args = [
+                "knip",
+                "--reporter=json",
+                "--include",
+                "files,exports,types,dependencies,unlisted",
+            ];
+            if (ignore && ignore.length > 0) {
+                args.push("--ignore", ignore.join(","));
+            }
+            const result = safeSpawn("npx", args, {
+                timeout: 30000,
+                cwd: targetDir,
+            });
+            // Knip exits 0 on success (even with issues), 1 on errors
+            const output = result.stdout || "";
+            this.log(`Knip output length: ${output.length}`);
+            if (output.length < 500) {
+                this.log(`Knip output sample: ${output}`);
+            }
+            if (!output.trim()) {
+                return {
+                    success: true,
+                    issues: [],
+                    unusedExports: [],
+                    unusedFiles: [],
+                    unusedDeps: [],
+                    unlistedDeps: [],
+                    summary: "No issues found",
+                };
+            }
+            return this.parseOutput(output);
+        }
+        catch (err) {
+            this.log(`Analysis error: ${err.message}`);
+            return {
+                success: false,
+                issues: [],
+                unusedExports: [],
+                unusedFiles: [],
+                unusedDeps: [],
+                unlistedDeps: [],
+                summary: `Error: ${err.message}`,
+            };
+        }
+    }
+    /**
+     * Find unused exports in a specific file
+     */
+    findUnusedExports(filePath) {
+        const result = this.analyze(path.dirname(filePath));
+        const basename = path.basename(filePath);
+        return result.unusedExports
+            .filter((e) => e.file?.includes(basename))
+            .map((e) => e.name);
+    }
+    /**
+     * Format results for LLM consumption
+     */
+    formatResult(result, maxItems = 20) {
+        if (!result.success)
+            return `[Knip] ${result.summary}`;
+        if (result.issues.length === 0)
+            return "";
+        let output = `[Knip] ${result.issues.length} issue(s)`;
+        if (result.unusedExports.length)
+            output += ` — ${result.unusedExports.length} unused export(s)`;
+        if (result.unusedFiles.length)
+            output += ` — ${result.unusedFiles.length} unused file(s)`;
+        if (result.unusedDeps.length)
+            output += ` — ${result.unusedDeps.length} unused dep(s)`;
+        if (result.unlistedDeps.length)
+            output += ` — ${result.unlistedDeps.length} unlisted dep(s)`;
+        output += ":\n";
+        // Show unused exports first (most useful for refactoring)
+        if (result.unusedExports.length > 0) {
+            output += "\n  Unused exports:\n";
+            for (const issue of result.unusedExports.slice(0, maxItems)) {
+                const loc = issue.file ? ` (${path.basename(issue.file)})` : "";
+                output += `    - ${issue.name}${loc}\n`;
+            }
+            if (result.unusedExports.length > maxItems) {
+                output += `    ... and ${result.unusedExports.length - maxItems} more\n`;
+            }
+        }
+        // Show unused files
+        if (result.unusedFiles.length > 0) {
+            output += "\n  Unused files:\n";
+            for (const issue of result.unusedFiles.slice(0, 10)) {
+                output += `    - ${issue.name}\n`;
+            }
+        }
+        // Show unused deps (might be worth removing)
+        if (result.unusedDeps.length > 0) {
+            output += "\n  Unused dependencies:\n";
+            for (const issue of result.unusedDeps) {
+                output += `    - ${issue.package || issue.name}\n`;
+            }
+        }
+        return output;
+    }
+    // --- Internal ---
+    parseOutput(output) {
+        try {
+            const data = JSON.parse(output);
+            const issues = [];
+            const unusedExports = [];
+            const unusedFiles = [];
+            const unusedDeps = [];
+            const unlistedDeps = [];
+            // Knip JSON format: { issues: [ { file, exports:[], files:[], dependencies:[], ... } ] }
+            const fileEntries = data.issues ?? [];
+            for (const entry of fileEntries) {
+                const file = entry.file ?? "";
+                const push = (arr, type, target) => {
+                    for (const item of arr) {
+                        const issue = {
+                            type,
+                            name: item.name ?? item.symbol ?? String(item),
+                            file,
+                            line: item.line,
+                            package: item.package,
+                        };
+                        issues.push(issue);
+                        target.push(issue);
+                    }
+                };
+                push(entry.exports ?? [], "export", unusedExports);
+                push(entry.types ?? [], "export", unusedExports);
+                push(entry.files ?? [], "file", unusedFiles);
+                push(entry.dependencies ?? [], "dependency", unusedDeps);
+                push(entry.devDependencies ?? [], "devDependency", unusedDeps);
+                push(entry.unlisted ?? [], "unlisted", unlistedDeps);
+            }
+            return {
+                success: true,
+                issues,
+                unusedExports,
+                unusedFiles,
+                unusedDeps,
+                unlistedDeps,
+                summary: `Found ${issues.length} issues`,
+            };
+        }
+        catch (err) {
+            void err;
+            this.log("Failed to parse knip JSON output");
+            return {
+                success: false,
+                issues: [],
+                unusedExports: [],
+                unusedFiles: [],
+                unusedDeps: [],
+                unlistedDeps: [],
+                summary: "Failed to parse output",
+            };
+        }
+    }
+}