@compilr-dev/agents-coding-python 0.1.0

package/dist/tools/find-dead-code.js

@@ -0,0 +1,422 @@
+/**
+ * findDeadCode Tool
+ *
+ * Find potentially unused functions, classes, and variables in Python code.
+ * Uses static analysis to identify code that may be dead.
+ */
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import { defineTool, createSuccessResult, createErrorResult, } from "@compilr-dev/agents";
+import { parseFile, parseFunction, parseClass, } from "../parser/python-parser.js";
+// Tool description
+const TOOL_DESCRIPTION = `Find potentially unused functions, classes, and variables in Python code.
+Analyzes the codebase to identify code that may be dead (never used).
+Useful for cleanup and reducing code size.`;
+// Tool input schema
+const TOOL_INPUT_SCHEMA = {
+    type: "object",
+    properties: {
+        path: {
+            type: "string",
+            description: "Directory to analyze",
+        },
+        includeTests: {
+            type: "boolean",
+            description: "Include test files in analysis (default: false)",
+            default: false,
+        },
+        checkFunctions: {
+            type: "boolean",
+            description: "Check for unused functions (default: true)",
+            default: true,
+        },
+        checkClasses: {
+            type: "boolean",
+            description: "Check for unused classes (default: true)",
+            default: true,
+        },
+        checkVariables: {
+            type: "boolean",
+            description: "Check for unused variables (default: false)",
+            default: false,
+        },
+        maxFiles: {
+            type: "number",
+            description: "Maximum files to analyze (default: 100)",
+            default: 100,
+        },
+    },
+    required: ["path"],
+};
+// Default exclusions
+const DEFAULT_EXCLUDE = [
+    "node_modules",
+    "__pycache__",
+    ".git",
+    "venv",
+    ".venv",
+    "env",
+    "dist",
+    "build",
+    ".tox",
+    ".eggs",
+];
+const TEST_PATTERNS = ["test_", "_test.py", "tests/", "test/", "conftest.py"];
+/**
+ * findDeadCode tool
+ */
+export const findDeadCodeTool = defineTool({
+    name: "find_dead_code_python",
+    description: TOOL_DESCRIPTION,
+    inputSchema: TOOL_INPUT_SCHEMA,
+    execute: executeFindDeadCode,
+});
+/**
+ * Execute the findDeadCode tool
+ */
+async function executeFindDeadCode(input) {
+    const { path: inputPath, includeTests = false, checkFunctions = true, checkClasses = true, checkVariables = false, maxFiles = 100, } = input;
+    try {
+        const resolvedPath = path.resolve(inputPath);
+        // Check if path exists
+        try {
+            await fs.access(resolvedPath);
+        }
+        catch {
+            return createErrorResult(`Path not found: ${resolvedPath}`);
+        }
+        const stats = await fs.stat(resolvedPath);
+        if (!stats.isDirectory()) {
+            return createErrorResult("findDeadCode requires a directory path");
+        }
+        // Collect files
+        const files = [];
+        await collectFiles(resolvedPath, files, includeTests, maxFiles);
+        // Build symbol index
+        const definitions = [];
+        const usages = new Set();
+        const importedSymbols = new Set();
+        // First pass: collect all definitions and usages
+        for (const file of files) {
+            await analyzeFile(file, definitions, usages, importedSymbols);
+        }
+        // Find dead code
+        const deadCode = [];
+        // Stats
+        let totalFunctions = 0;
+        let unusedFunctions = 0;
+        let totalClasses = 0;
+        let unusedClasses = 0;
+        let totalVariables = 0;
+        let unusedVariables = 0;
+        for (const def of definitions) {
+            // Skip __init__.py files (typically exports)
+            if (def.path.endsWith("__init__.py")) {
+                continue;
+            }
+            // Skip dunder methods (always considered used)
+            if (def.isDunderMethod) {
+                continue;
+            }
+            const isUsed = usages.has(def.name) || importedSymbols.has(def.name);
+            // Check functions
+            if (def.kind === "function" && checkFunctions) {
+                totalFunctions++;
+                if (!isUsed && !def.isPrivate) {
+                    // Non-private, not used
+                    unusedFunctions++;
+                    deadCode.push({
+                        name: def.name,
+                        path: def.path,
+                        line: def.line,
+                        kind: "function",
+                        confidence: "medium",
+                        reason: "Function is not called or imported anywhere in the codebase",
+                    });
+                }
+                else if (!isUsed && def.isPrivate) {
+                    // Private function not used in the file
+                    unusedFunctions++;
+                    deadCode.push({
+                        name: def.name,
+                        path: def.path,
+                        line: def.line,
+                        kind: "function",
+                        confidence: "high",
+                        reason: "Private function is not called anywhere in the file",
+                    });
+                }
+            }
+            // Check classes
+            if (def.kind === "class" && checkClasses) {
+                totalClasses++;
+                if (!isUsed) {
+                    unusedClasses++;
+                    deadCode.push({
+                        name: def.name,
+                        path: def.path,
+                        line: def.line,
+                        kind: "class",
+                        confidence: def.isPrivate ? "high" : "medium",
+                        reason: def.isPrivate
+                            ? "Private class is not used anywhere in the file"
+                            : "Class is not instantiated or referenced anywhere in the codebase",
+                    });
+                }
+            }
+            // Check variables
+            if (def.kind === "variable" && checkVariables) {
+                totalVariables++;
+                if (!isUsed) {
+                    unusedVariables++;
+                    deadCode.push({
+                        name: def.name,
+                        path: def.path,
+                        line: def.line,
+                        kind: "variable",
+                        confidence: "medium",
+                        reason: "Variable is not referenced after declaration",
+                    });
+                }
+            }
+        }
+        const result = {
+            path: resolvedPath,
+            deadCode,
+            stats: {
+                filesAnalyzed: files.length,
+                totalFunctions,
+                unusedFunctions,
+                totalClasses,
+                unusedClasses,
+                totalVariables,
+                unusedVariables,
+            },
+        };
+        return createSuccessResult(result);
+    }
+    catch (error) {
+        return createErrorResult(`Failed to find dead code: ${error instanceof Error ? error.message : String(error)}`);
+    }
+}
+/**
+ * Collect files to analyze
+ */
+async function collectFiles(dirPath, files, includeTests, maxFiles, currentDepth = 0) {
+    if (currentDepth > 10 || files.length >= maxFiles)
+        return;
+    try {
+        const entries = await fs.readdir(dirPath, { withFileTypes: true });
+        for (const entry of entries) {
+            if (files.length >= maxFiles)
+                break;
+            const fullPath = path.join(dirPath, entry.name);
+            // Skip excluded directories
+            if (entry.isDirectory()) {
+                if (DEFAULT_EXCLUDE.includes(entry.name))
+                    continue;
+                if (!includeTests && (entry.name === "tests" || entry.name === "test"))
+                    continue;
+                await collectFiles(fullPath, files, includeTests, maxFiles, currentDepth + 1);
+            }
+            else if (entry.isFile()) {
+                // Only include Python files
+                if (fullPath.endsWith(".py") && !fullPath.endsWith(".pyi")) {
+                    // Skip test files if not including tests
+                    if (!includeTests &&
+                        TEST_PATTERNS.some((p) => fullPath.includes(p))) {
+                        continue;
+                    }
+                    files.push(fullPath);
+                }
+            }
+        }
+    }
+    catch {
+        // Ignore permission errors
+    }
+}
+/**
+ * Analyze a file for definitions and usages
+ */
+async function analyzeFile(filePath, definitions, usages, importedSymbols) {
+    try {
+        const parseResult = await parseFile(filePath);
+        const { tree, source } = parseResult;
+        const rootNode = tree.rootNode;
+        // Collect definitions
+        for (const child of rootNode.children) {
+            // Function definitions
+            if (child.type === "function_definition" ||
+                child.type === "async_function_definition") {
+                const funcInfo = parseFunction(child, source);
+                const isPrivate = funcInfo.name.startsWith("_") && !funcInfo.name.startsWith("__");
+                const isDunderMethod = funcInfo.name.startsWith("__") && funcInfo.name.endsWith("__");
+                definitions.push({
+                    name: funcInfo.name,
+                    path: filePath,
+                    line: funcInfo.line,
+                    kind: "function",
+                    isPrivate,
+                    isDunderMethod,
+                });
+            }
+            // Class definitions
+            if (child.type === "class_definition") {
+                const classInfo = parseClass(child, source);
+                const isPrivate = classInfo.name.startsWith("_");
+                definitions.push({
+                    name: classInfo.name,
+                    path: filePath,
+                    line: classInfo.line,
+                    kind: "class",
+                    isPrivate,
+                    isDunderMethod: false,
+                });
+                // Also collect methods
+                const body = child.childForFieldName("body");
+                if (body) {
+                    for (const member of body.children) {
+                        if (member.type === "function_definition" ||
+                            member.type === "async_function_definition") {
+                            const methodInfo = parseFunction(member, source);
+                            const isMethodPrivate = methodInfo.name.startsWith("_") &&
+                                !methodInfo.name.startsWith("__");
+                            const isMethodDunder = methodInfo.name.startsWith("__") &&
+                                methodInfo.name.endsWith("__");
+                            // Don't add methods as separate definitions for dead code detection
+                            // (they're part of the class)
+                            if (!isMethodDunder && isMethodPrivate) {
+                                definitions.push({
+                                    name: `${classInfo.name}.${methodInfo.name}`,
+                                    path: filePath,
+                                    line: methodInfo.line,
+                                    kind: "method",
+                                    isPrivate: true,
+                                    isDunderMethod: false,
+                                });
+                            }
+                        }
+                    }
+                }
+            }
+            // Import statements - track what's imported
+            if (child.type === "import_statement") {
+                const nameNode = child.childForFieldName("name");
+                if (nameNode) {
+                    importedSymbols.add(nameNode.text);
+                }
+            }
+            if (child.type === "import_from_statement") {
+                // from module import name1, name2
+                for (const c of child.children) {
+                    if (c.type === "dotted_name" || c.type === "aliased_import") {
+                        const alias = c.childForFieldName("alias");
+                        const name = c.childForFieldName("name");
+                        if (alias) {
+                            importedSymbols.add(alias.text);
+                        }
+                        else if (name) {
+                            importedSymbols.add(name.text);
+                        }
+                        else if (c.type === "dotted_name") {
+                            importedSymbols.add(c.text.split(".")[0]);
+                        }
+                    }
+                }
+            }
+            // Top-level assignments (module-level variables)
+            if (child.type === "expression_statement") {
+                const expr = child.children[0];
+                if (expr?.type === "assignment") {
+                    const left = expr.childForFieldName("left");
+                    if (left?.type === "identifier") {
+                        const isPrivate = left.text.startsWith("_");
+                        definitions.push({
+                            name: left.text,
+                            path: filePath,
+                            line: child.startPosition.row + 1,
+                            kind: "variable",
+                            isPrivate,
+                            isDunderMethod: false,
+                        });
+                    }
+                }
+            }
+        }
+        // Collect usages (identifiers)
+        collectUsages(rootNode, usages, definitions);
+    }
+    catch {
+        // Ignore errors
+    }
+}
+/**
+ * Collect all identifier usages in the AST
+ */
+function collectUsages(node, usages, definitions) {
+    // Skip definition nodes
+    if (node.type === "function_definition" ||
+        node.type === "async_function_definition" ||
+        node.type === "class_definition") {
+        const nameNode = node.childForFieldName("name");
+        // Still recurse into the body
+        for (const child of node.children) {
+            if (child !== nameNode) {
+                collectUsages(child, usages, definitions);
+            }
+        }
+        return;
+    }
+    // Track identifier usages
+    if (node.type === "identifier") {
+        const parent = node.parent;
+        // Skip if this is a definition site
+        if (parent &&
+            (parent.type === "function_definition" ||
+                parent.type === "async_function_definition" ||
+                parent.type === "class_definition") &&
+            parent.childForFieldName("name") === node) {
+            return;
+        }
+        // Skip if this is the left side of an assignment (definition)
+        if (parent?.type === "assignment" &&
+            parent.childForFieldName("left") === node) {
+            return;
+        }
+        // Skip if this is a parameter
+        if (parent?.type === "typed_parameter" ||
+            parent?.type === "default_parameter") {
+            return;
+        }
+        usages.add(node.text);
+    }
+    // Track attribute access (obj.method)
+    if (node.type === "attribute") {
+        const attr = node.childForFieldName("attribute");
+        if (attr) {
+            usages.add(attr.text);
+        }
+    }
+    // Recurse
+    for (const child of node.children) {
+        collectUsages(child, usages, definitions);
+    }
+}
+/**
+ * Factory function to create a customized findDeadCode tool
+ */
+export function createFindDeadCodeTool(options) {
+    return defineTool({
+        name: "find_dead_code_python",
+        description: TOOL_DESCRIPTION,
+        inputSchema: TOOL_INPUT_SCHEMA,
+        execute: async (input) => {
+            const modifiedInput = {
+                ...input,
+                maxFiles: input.maxFiles ?? options?.defaultMaxFiles,
+            };
+            return executeFindDeadCode(modifiedInput);
+        },
+    });
+}

package/dist/tools/find-duplicates.d.ts

@@ -0,0 +1,65 @@
+/**
+ * findDuplicates Tool
+ *
+ * Detect duplicate code blocks in Python files using content hashing.
+ * Helps identify opportunities for refactoring and code reuse.
+ */
+import type { Tool } from "@compilr-dev/agents";
+/**
+ * Input for findDuplicates tool
+ */
+export interface FindDuplicatesInput {
+    /** Directory to analyze */
+    path: string;
+    /** Minimum lines for a duplicate (default: 6) */
+    minLines?: number;
+    /** Minimum tokens for a duplicate (default: 50) */
+    minTokens?: number;
+    /** Ignore identical files (default: true) */
+    ignoreIdenticalFiles?: boolean;
+    /** Maximum files to analyze (default: 100) */
+    maxFiles?: number;
+}
+/**
+ * Code location
+ */
+export interface CodeLocation {
+    path: string;
+    startLine: number;
+    endLine: number;
+}
+/**
+ * Duplicate group
+ */
+export interface DuplicateGroup {
+    id: string;
+    lines: number;
+    tokens: number;
+    locations: CodeLocation[];
+    sample: string;
+}
+/**
+ * Result of findDuplicates
+ */
+export interface FindDuplicatesResult {
+    path: string;
+    duplicates: DuplicateGroup[];
+    stats: {
+        filesAnalyzed: number;
+        duplicateGroups: number;
+        totalDuplicateLines: number;
+        percentageDuplicate: number;
+    };
+}
+/**
+ * findDuplicates tool
+ */
+export declare const findDuplicatesTool: Tool<FindDuplicatesInput>;
+/**
+ * Factory function to create a customized findDuplicates tool
+ */
+export declare function createFindDuplicatesTool(options?: {
+    defaultMinLines?: number;
+    defaultMaxFiles?: number;
+}): Tool<FindDuplicatesInput>;
+//# sourceMappingURL=find-duplicates.d.ts.map

package/dist/tools/find-duplicates.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"find-duplicates.d.ts","sourceRoot":"","sources":["../../src/tools/find-duplicates.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAUH,OAAO,KAAK,EAAE,IAAI,EAAuB,MAAM,qBAAqB,CAAC;AAErE;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,2BAA2B;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,iDAAiD;IACjD,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,mDAAmD;IACnD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,6CAA6C;IAC7C,oBAAoB,CAAC,EAAE,OAAO,CAAC;IAC/B,8CAA8C;IAC9C,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,YAAY,EAAE,CAAC;IAC1B,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,cAAc,EAAE,CAAC;IAC7B,KAAK,EAAE;QACL,aAAa,EAAE,MAAM,CAAC;QACtB,eAAe,EAAE,MAAM,CAAC;QACxB,mBAAmB,EAAE,MAAM,CAAC;QAC5B,mBAAmB,EAAE,MAAM,CAAC;KAC7B,CAAC;CACH;AAiED;;GAEG;AACH,eAAO,MAAM,kBAAkB,2BAK7B,CAAC;AAmQH;;GAEG;AACH,wBAAgB,wBAAwB,CAAC,OAAO,CAAC,EAAE;IACjD,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B,GAAG,IAAI,CAAC,mBAAmB,CAAC,CAc5B"}