@compilr-dev/agents-coding-python 0.1.0

package/dist/tools/find-patterns.js

@@ -0,0 +1,477 @@
+/**
+ * findPatterns Tool
+ *
+ * Find code patterns, anti-patterns, and code smells in Python code.
+ * Uses regex and AST-based pattern matching.
+ */
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import { defineTool, createSuccessResult, createErrorResult, } from "@compilr-dev/agents";
+import { parseFile, parseFunction } from "../parser/python-parser.js";
+// Tool description
+const TOOL_DESCRIPTION = `Find code patterns, anti-patterns, and code smells in Python code.
+Searches for common issues like security vulnerabilities, performance problems, and maintainability concerns.
+Supports built-in patterns or custom pattern definitions.`;
+// Tool input schema
+const TOOL_INPUT_SCHEMA = {
+    type: "object",
+    properties: {
+        path: {
+            type: "string",
+            description: "Directory to analyze",
+        },
+        patterns: {
+            type: "array",
+            description: "Custom patterns to search for (uses built-in if not specified)",
+            items: {
+                type: "object",
+                properties: {
+                    name: { type: "string" },
+                    description: { type: "string" },
+                    type: { type: "string" },
+                    matcher: { type: "string" },
+                    severity: { type: "string" },
+                },
+            },
+        },
+        categories: {
+            type: "array",
+            description: "Pattern categories to include (default: all)",
+            items: {
+                type: "string",
+                enum: ["security", "performance", "maintainability", "all"],
+            },
+        },
+        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",
+];
+// Built-in Python patterns
+const BUILTIN_PATTERNS = [
+    // Security patterns
+    {
+        name: "eval-usage",
+        description: "Use of eval() can lead to code injection vulnerabilities",
+        type: "anti-pattern",
+        matcher: "\\beval\\s*\\(",
+        severity: "error",
+        category: "security",
+    },
+    {
+        name: "exec-usage",
+        description: "Use of exec() can lead to code injection vulnerabilities",
+        type: "anti-pattern",
+        matcher: "\\bexec\\s*\\(",
+        severity: "error",
+        category: "security",
+    },
+    {
+        name: "hardcoded-secret",
+        description: "Potential hardcoded secret or API key",
+        type: "anti-pattern",
+        matcher: "(password|secret|api_key|apikey|token|private_key)\\s*=\\s*[\"'][^\"']+[\"']",
+        severity: "error",
+        category: "security",
+    },
+    {
+        name: "sql-injection-risk",
+        description: "String formatting in SQL query (potential injection)",
+        type: "anti-pattern",
+        matcher: "(execute|cursor\\.execute)\\s*\\([^)]*(%|format|f['\"])",
+        severity: "error",
+        category: "security",
+    },
+    {
+        name: "pickle-usage",
+        description: "pickle can execute arbitrary code when loading untrusted data",
+        type: "anti-pattern",
+        matcher: "pickle\\.load",
+        severity: "warning",
+        category: "security",
+    },
+    {
+        name: "shell-injection-risk",
+        description: "shell=True with user input can lead to command injection",
+        type: "anti-pattern",
+        matcher: "subprocess\\.(call|run|Popen)\\([^)]*shell\\s*=\\s*True",
+        severity: "error",
+        category: "security",
+    },
+    // Performance patterns
+    {
+        name: "print-statement",
+        description: "print() left in code (should use logging in production)",
+        type: "smell",
+        matcher: "\\bprint\\s*\\(",
+        severity: "info",
+        category: "performance",
+    },
+    {
+        name: "mutable-default-arg",
+        description: "Mutable default argument (list, dict, set) is a common bug source",
+        type: "anti-pattern",
+        matcher: "def\\s+\\w+\\s*\\([^)]*=\\s*\\[\\]|def\\s+\\w+\\s*\\([^)]*=\\s*\\{\\}",
+        severity: "warning",
+        category: "performance",
+    },
+    {
+        name: "global-variable",
+        description: "Global variable usage makes code harder to test and reason about",
+        type: "smell",
+        matcher: "\\bglobal\\s+\\w+",
+        severity: "warning",
+        category: "performance",
+    },
+    {
+        name: "nested-loops",
+        description: "Deeply nested loops may indicate O(n²) or worse complexity",
+        type: "smell",
+        matcher: "for\\s+[^:]+:\\s*[^#]*for\\s+[^:]+:\\s*[^#]*for\\s+",
+        severity: "warning",
+        category: "performance",
+    },
+    // Maintainability patterns
+    {
+        name: "bare-except",
+        description: "Bare except catches all exceptions including SystemExit and KeyboardInterrupt",
+        type: "anti-pattern",
+        matcher: "except\\s*:",
+        severity: "warning",
+        category: "maintainability",
+    },
+    {
+        name: "star-import",
+        description: "Star imports pollute namespace and hide dependencies",
+        type: "anti-pattern",
+        matcher: "from\\s+\\S+\\s+import\\s+\\*",
+        severity: "warning",
+        category: "maintainability",
+    },
+    {
+        name: "todo-fixme",
+        description: "TODO or FIXME comment indicating incomplete work",
+        type: "smell",
+        matcher: "(TODO|FIXME|HACK|XXX)\\s*:?",
+        severity: "info",
+        category: "maintainability",
+    },
+    {
+        name: "type-ignore",
+        description: "# type: ignore suppresses type checking",
+        type: "smell",
+        matcher: "#\\s*type:\\s*ignore",
+        severity: "warning",
+        category: "maintainability",
+    },
+    {
+        name: "noqa-comment",
+        description: "# noqa suppresses linting rules",
+        type: "smell",
+        matcher: "#\\s*noqa",
+        severity: "info",
+        category: "maintainability",
+    },
+    {
+        name: "long-function",
+        description: "Function body exceeds recommended length",
+        type: "smell",
+        matcher: "AST:long-function",
+        severity: "warning",
+        category: "maintainability",
+    },
+    {
+        name: "many-parameters",
+        description: "Function has too many parameters (consider using dataclass or kwargs)",
+        type: "smell",
+        matcher: "AST:many-parameters",
+        severity: "info",
+        category: "maintainability",
+    },
+    {
+        name: "assert-usage",
+        description: "assert can be disabled with -O flag, don't use for validation",
+        type: "smell",
+        matcher: "\\bassert\\s+",
+        severity: "info",
+        category: "maintainability",
+    },
+];
+/**
+ * findPatterns tool
+ */
+export const findPatternsTool = defineTool({
+    name: "find_patterns_python",
+    description: TOOL_DESCRIPTION,
+    inputSchema: TOOL_INPUT_SCHEMA,
+    execute: executeFindPatterns,
+});
+/**
+ * Execute the findPatterns tool
+ */
+async function executeFindPatterns(input) {
+    const { path: inputPath, patterns, categories = ["all"], 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("findPatterns requires a directory path");
+        }
+        // Determine which patterns to use
+        const patternsToUse = patterns ?? getBuiltinPatterns(categories);
+        // Collect files
+        const files = [];
+        await collectFiles(resolvedPath, files, maxFiles);
+        // Find matches
+        const allMatches = [];
+        const byPattern = {};
+        let errorCount = 0;
+        let warningCount = 0;
+        let infoCount = 0;
+        for (const file of files) {
+            const fileMatches = await analyzeFileForPatterns(file, patternsToUse);
+            allMatches.push(...fileMatches);
+        }
+        // Count by pattern and severity
+        for (const match of allMatches) {
+            byPattern[match.pattern] = (byPattern[match.pattern] ?? 0) + 1;
+            if (match.severity === "error")
+                errorCount++;
+            else if (match.severity === "warning")
+                warningCount++;
+            else
+                infoCount++;
+        }
+        // Sort by severity (errors first)
+        allMatches.sort((a, b) => {
+            const severityOrder = { error: 0, warning: 1, info: 2 };
+            return severityOrder[a.severity] - severityOrder[b.severity];
+        });
+        // Limit results
+        const limitedMatches = allMatches.slice(0, 100);
+        const result = {
+            path: resolvedPath,
+            matches: limitedMatches,
+            stats: {
+                filesAnalyzed: files.length,
+                totalMatches: allMatches.length,
+                byPattern,
+                bySeverity: {
+                    error: errorCount,
+                    warning: warningCount,
+                    info: infoCount,
+                },
+            },
+        };
+        return createSuccessResult(result);
+    }
+    catch (error) {
+        return createErrorResult(`Failed to find patterns: ${error instanceof Error ? error.message : String(error)}`);
+    }
+}
+/**
+ * Get built-in patterns filtered by category
+ */
+function getBuiltinPatterns(categories) {
+    if (categories.includes("all")) {
+        return BUILTIN_PATTERNS;
+    }
+    return BUILTIN_PATTERNS.filter((p) => categories.includes(p.category));
+}
+/**
+ * Collect files to analyze
+ */
+async function collectFiles(dirPath, files, 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);
+            if (entry.isDirectory()) {
+                if (DEFAULT_EXCLUDE.includes(entry.name))
+                    continue;
+                await collectFiles(fullPath, files, maxFiles, currentDepth + 1);
+            }
+            else if (entry.isFile()) {
+                // Only include Python files
+                if (fullPath.endsWith(".py") && !fullPath.endsWith(".pyi")) {
+                    files.push(fullPath);
+                }
+            }
+        }
+    }
+    catch {
+        // Ignore permission errors
+    }
+}
+/**
+ * Analyze a file for patterns
+ */
+async function analyzeFileForPatterns(filePath, patterns) {
+    try {
+        const content = await fs.readFile(filePath, "utf-8");
+        const lines = content.split("\n");
+        const matches = [];
+        // Separate regex patterns from AST patterns
+        const regexPatterns = patterns.filter((p) => !p.matcher.startsWith("AST:"));
+        const astPatterns = patterns.filter((p) => p.matcher.startsWith("AST:"));
+        // Check regex patterns line by line
+        for (let i = 0; i < lines.length; i++) {
+            const line = lines[i];
+            for (const pattern of regexPatterns) {
+                try {
+                    const regex = new RegExp(pattern.matcher, "gi");
+                    if (regex.test(line)) {
+                        matches.push({
+                            pattern: pattern.name,
+                            description: pattern.description,
+                            severity: pattern.severity,
+                            path: filePath,
+                            line: i + 1,
+                            snippet: line.trim().slice(0, 100),
+                            suggestion: getSuggestion(pattern.name),
+                        });
+                    }
+                }
+                catch {
+                    // Invalid regex, skip
+                }
+            }
+        }
+        // Check AST patterns
+        if (astPatterns.length > 0) {
+            const astMatches = await analyzeFileForAstPatterns(filePath, astPatterns);
+            matches.push(...astMatches);
+        }
+        return matches;
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Analyze file for AST-based patterns
+ */
+async function analyzeFileForAstPatterns(filePath, patterns) {
+    const matches = [];
+    try {
+        const parseResult = await parseFile(filePath);
+        const { tree, source } = parseResult;
+        const checkLongFunction = patterns.some((p) => p.matcher === "AST:long-function");
+        const checkManyParameters = patterns.some((p) => p.matcher === "AST:many-parameters");
+        // Walk the AST
+        function visit(node) {
+            if (checkLongFunction &&
+                (node.type === "function_definition" ||
+                    node.type === "async_function_definition")) {
+                const startLine = node.startPosition.row;
+                const endLine = node.endPosition.row;
+                const lines = endLine - startLine;
+                if (lines > 50) {
+                    const funcInfo = parseFunction(node, source);
+                    matches.push({
+                        pattern: "long-function",
+                        description: `Function "${funcInfo.name}" has ${String(lines)} lines (recommended: <50)`,
+                        severity: "warning",
+                        path: filePath,
+                        line: startLine + 1,
+                        snippet: `def ${funcInfo.name}(...): # ${String(lines)} lines`,
+                        suggestion: "Consider breaking this function into smaller functions",
+                    });
+                }
+            }
+            if (checkManyParameters &&
+                (node.type === "function_definition" ||
+                    node.type === "async_function_definition")) {
+                const funcInfo = parseFunction(node, source);
+                // Exclude 'self' and 'cls' from count
+                const realParamCount = funcInfo.parameters.filter((p) => p.name !== "self" && p.name !== "cls").length;
+                if (realParamCount > 5) {
+                    matches.push({
+                        pattern: "many-parameters",
+                        description: `Function "${funcInfo.name}" has ${String(realParamCount)} parameters (recommended: <5)`,
+                        severity: "info",
+                        path: filePath,
+                        line: funcInfo.line,
+                        snippet: `def ${funcInfo.name}(${String(realParamCount)} params...)`,
+                        suggestion: "Consider using a dataclass, TypedDict, or **kwargs for many parameters",
+                    });
+                }
+            }
+            for (const child of node.children) {
+                visit(child);
+            }
+        }
+        visit(tree.rootNode);
+    }
+    catch {
+        // Ignore parse errors
+    }
+    return matches;
+}
+/**
+ * Get suggestion for a pattern
+ */
+function getSuggestion(patternName) {
+    const suggestions = {
+        "eval-usage": "Use ast.literal_eval() for safe evaluation or refactor to avoid eval",
+        "exec-usage": "Refactor to avoid exec(), use importlib for dynamic imports",
+        "hardcoded-secret": "Use environment variables or a secrets manager",
+        "sql-injection-risk": "Use parameterized queries with ? or %s placeholders",
+        "pickle-usage": "Use JSON or a safer serialization format for untrusted data",
+        "shell-injection-risk": "Avoid shell=True or sanitize input carefully",
+        "print-statement": "Use logging module for production code",
+        "mutable-default-arg": "Use None as default and create the mutable object inside the function",
+        "global-variable": "Pass values as function parameters or use a class",
+        "bare-except": "Catch specific exceptions like 'except ValueError:' or at least 'except Exception:'",
+        "star-import": "Import specific names: 'from module import name1, name2'",
+        "type-ignore": "Fix the underlying type issue instead of suppressing",
+        "assert-usage": "Use explicit validation with if/raise for runtime checks",
+    };
+    return suggestions[patternName];
+}
+/**
+ * Factory function to create a customized findPatterns tool
+ */
+export function createFindPatternsTool(options) {
+    return defineTool({
+        name: "find_patterns_python",
+        description: TOOL_DESCRIPTION,
+        inputSchema: TOOL_INPUT_SCHEMA,
+        execute: async (input) => {
+            const modifiedInput = {
+                ...input,
+                maxFiles: input.maxFiles ?? options?.defaultMaxFiles,
+                patterns: input.patterns ?? [
+                    ...BUILTIN_PATTERNS,
+                    ...(options?.additionalPatterns ?? []),
+                ],
+            };
+            return executeFindPatterns(modifiedInput);
+        },
+    });
+}

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

@@ -0,0 +1,66 @@
+/**
+ * findReferences Tool
+ *
+ * Find all references to a symbol across Python codebases.
+ * Uses Tree-sitter for AST analysis.
+ */
+import type { Tool } from "@compilr-dev/agents";
+import type { SymbolReference } from "./types.js";
+/**
+ * Reference type
+ */
+export type ReferenceType = "read" | "write" | "call" | "import" | "definition" | "attribute";
+/**
+ * Input for findReferences tool
+ */
+export interface FindReferencesInput {
+    /** Symbol name to find */
+    symbol: string;
+    /** Scope the search to a specific file or directory */
+    scope?: string;
+    /** Maximum results to return (default: 50) */
+    limit?: number;
+    /** Include the definition itself (default: false) */
+    includeDefinition?: boolean;
+    /** Include virtual environments (default: false) */
+    includeVenv?: boolean;
+}
+/**
+ * References grouped by file
+ */
+export interface FileReferences {
+    /** File path */
+    path: string;
+    /** References in this file */
+    references: SymbolReference[];
+}
+/**
+ * Output from findReferences tool
+ */
+export interface FindReferencesResult {
+    /** Symbol that was searched */
+    symbol: string;
+    /** References grouped by file */
+    byFile: FileReferences[];
+    /** Total reference count */
+    totalCount: number;
+    /** Whether results were truncated */
+    truncated: boolean;
+    /** Statistics */
+    stats: {
+        filesSearched: number;
+        timeMs: number;
+    };
+}
+/**
+ * findReferences tool - Find all references to a symbol
+ */
+export declare const findReferencesTool: Tool<FindReferencesInput>;
+/**
+ * Factory function to create a customized findReferences tool
+ */
+export declare function createFindReferencesTool(options?: {
+    defaultLimit?: number;
+    defaultIncludeDefinition?: boolean;
+}): Tool<FindReferencesInput>;
+//# sourceMappingURL=find-references.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"find-references.d.ts","sourceRoot":"","sources":["../../src/tools/find-references.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AASH,OAAO,KAAK,EAAE,IAAI,EAAuB,MAAM,qBAAqB,CAAC;AAGrE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAKlD;;GAEG;AACH,MAAM,MAAM,aAAa,GACrB,MAAM,GACN,OAAO,GACP,MAAM,GACN,QAAQ,GACR,YAAY,GACZ,WAAW,CAAC;AAEhB;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,0BAA0B;IAC1B,MAAM,EAAE,MAAM,CAAC;IACf,uDAAuD;IACvD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,8CAA8C;IAC9C,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,qDAAqD;IACrD,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B,oDAAoD;IACpD,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,gBAAgB;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,8BAA8B;IAC9B,UAAU,EAAE,eAAe,EAAE,CAAC;CAC/B;AAED;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC,+BAA+B;IAC/B,MAAM,EAAE,MAAM,CAAC;IACf,iCAAiC;IACjC,MAAM,EAAE,cAAc,EAAE,CAAC;IACzB,4BAA4B;IAC5B,UAAU,EAAE,MAAM,CAAC;IACnB,qCAAqC;IACrC,SAAS,EAAE,OAAO,CAAC;IACnB,iBAAiB;IACjB,KAAK,EAAE;QACL,aAAa,EAAE,MAAM,CAAC;QACtB,MAAM,EAAE,MAAM,CAAC;KAChB,CAAC;CACH;AAsCD;;GAEG;AACH,eAAO,MAAM,kBAAkB,2BAK7B,CAAC;AA4UH;;GAEG;AACH,wBAAgB,wBAAwB,CAAC,OAAO,CAAC,EAAE;IACjD,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,wBAAwB,CAAC,EAAE,OAAO,CAAC;CACpC,GAAG,IAAI,CAAC,mBAAmB,CAAC,CAiB5B"}