@compilr-dev/agents-coding-python 0.1.0

package/dist/tools/find-references.js

@@ -0,0 +1,306 @@
+/**
+ * findReferences Tool
+ *
+ * Find all references to a symbol across Python codebases.
+ * Uses Tree-sitter for AST analysis.
+ */
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import { defineTool, createSuccessResult, createErrorResult, } from "@compilr-dev/agents";
+import { parseFile, getNodeText } from "../parser/python-parser.js";
+// Supported file extensions
+const SUPPORTED_EXTENSIONS = new Set([".py", ".pyi"]);
+// Tool description
+const TOOL_DESCRIPTION = `Find all references to a symbol across Python files.
+Returns locations grouped by file with context about each reference.
+Useful for refactoring, understanding usage patterns, and impact analysis.`;
+// Tool input schema
+const TOOL_INPUT_SCHEMA = {
+    type: "object",
+    properties: {
+        symbol: {
+            type: "string",
+            description: "Symbol name to find references for",
+        },
+        scope: {
+            type: "string",
+            description: "Scope the search to a specific file or directory",
+        },
+        limit: {
+            type: "number",
+            description: "Maximum results to return (default: 50)",
+            default: 50,
+        },
+        includeDefinition: {
+            type: "boolean",
+            description: "Include the definition itself (default: false)",
+            default: false,
+        },
+        includeVenv: {
+            type: "boolean",
+            description: "Include virtual environments (default: false)",
+            default: false,
+        },
+    },
+    required: ["symbol"],
+};
+/**
+ * findReferences tool - Find all references to a symbol
+ */
+export const findReferencesTool = defineTool({
+    name: "find_references_python",
+    description: TOOL_DESCRIPTION,
+    inputSchema: TOOL_INPUT_SCHEMA,
+    execute: executeFindReferences,
+});
+/**
+ * Execute the findReferences tool
+ */
+async function executeFindReferences(input) {
+    const { symbol, scope, limit = 50, includeDefinition = false, includeVenv = false, } = input;
+    if (!symbol || symbol.trim().length === 0) {
+        return createErrorResult("Symbol name is required");
+    }
+    const startTime = Date.now();
+    const byFile = [];
+    let totalCount = 0;
+    let filesSearched = 0;
+    try {
+        const searchPath = scope || process.cwd();
+        try {
+            await fs.access(searchPath);
+        }
+        catch {
+            return createErrorResult(`Path not found: ${searchPath}`);
+        }
+        const stats = await fs.stat(searchPath);
+        if (stats.isFile()) {
+            if (isPythonFile(searchPath)) {
+                filesSearched = 1;
+                const refs = await searchFileForReferences(searchPath, symbol, includeDefinition);
+                if (refs.length > 0) {
+                    byFile.push({ path: searchPath, references: refs.slice(0, limit) });
+                    totalCount = refs.length;
+                }
+            }
+        }
+        else if (stats.isDirectory()) {
+            const files = await collectFiles(searchPath, includeVenv);
+            filesSearched = files.length;
+            for (const filePath of files) {
+                if (totalCount >= limit)
+                    break;
+                const refs = await searchFileForReferences(filePath, symbol, includeDefinition);
+                if (refs.length > 0) {
+                    const remaining = limit - totalCount;
+                    byFile.push({
+                        path: filePath,
+                        references: refs.slice(0, remaining),
+                    });
+                    totalCount += Math.min(refs.length, remaining);
+                }
+            }
+        }
+        const endTime = Date.now();
+        const result = {
+            symbol,
+            byFile,
+            totalCount,
+            truncated: totalCount >= limit,
+            stats: {
+                filesSearched,
+                timeMs: endTime - startTime,
+            },
+        };
+        return createSuccessResult(result);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return createErrorResult(`Failed to find references: ${message}`);
+    }
+}
+/**
+ * Check if a file is a Python file
+ */
+function isPythonFile(filePath) {
+    const ext = path.extname(filePath).toLowerCase();
+    return SUPPORTED_EXTENSIONS.has(ext);
+}
+/**
+ * Collect all Python files in a directory
+ */
+async function collectFiles(dir, includeVenv) {
+    const files = [];
+    async function walk(currentDir) {
+        const entries = await fs.readdir(currentDir, { withFileTypes: true });
+        for (const entry of entries) {
+            const fullPath = path.join(currentDir, entry.name);
+            if (entry.isDirectory()) {
+                if (!includeVenv &&
+                    (entry.name === "venv" ||
+                        entry.name === ".venv" ||
+                        entry.name === "env" ||
+                        entry.name === ".env" ||
+                        entry.name === "site-packages" ||
+                        entry.name === "__pycache__")) {
+                    continue;
+                }
+                if (entry.name.startsWith(".") ||
+                    entry.name === "dist" ||
+                    entry.name === "build") {
+                    continue;
+                }
+                await walk(fullPath);
+            }
+            else if (entry.isFile() && isPythonFile(fullPath)) {
+                files.push(fullPath);
+            }
+        }
+    }
+    await walk(dir);
+    return files;
+}
+/**
+ * Search a file for references to a symbol
+ */
+async function searchFileForReferences(filePath, symbolName, includeDefinition) {
+    const references = [];
+    try {
+        const parseResult = await parseFile(filePath);
+        const { tree, source } = parseResult;
+        const lines = source.split("\n");
+        // Walk the AST to find all references
+        findReferencesInNode(tree.rootNode, source, symbolName, includeDefinition, filePath, lines, references);
+    }
+    catch {
+        // Skip files that can't be parsed
+    }
+    return references;
+}
+/**
+ * Recursively find references in AST nodes
+ */
+function findReferencesInNode(node, source, symbolName, includeDefinition, filePath, lines, references) {
+    // Check identifier nodes
+    if (node.type === "identifier" && getNodeText(node, source) === symbolName) {
+        const refType = determineReferenceType(node, includeDefinition);
+        if (refType) {
+            const lineIndex = node.startPosition.row;
+            references.push({
+                path: filePath,
+                line: lineIndex + 1,
+                column: node.startPosition.column + 1,
+                context: lines[lineIndex]?.trim() || "",
+                type: refType,
+            });
+        }
+    }
+    // Check attribute access (e.g., obj.symbolName)
+    if (node.type === "attribute") {
+        const attrNode = node.childForFieldName("attribute");
+        if (attrNode && getNodeText(attrNode, source) === symbolName) {
+            const lineIndex = attrNode.startPosition.row;
+            references.push({
+                path: filePath,
+                line: lineIndex + 1,
+                column: attrNode.startPosition.column + 1,
+                context: lines[lineIndex]?.trim() || "",
+                type: "attribute",
+            });
+        }
+    }
+    // Check import names
+    if (node.type === "import_from_statement" ||
+        node.type === "import_statement") {
+        for (const child of node.children) {
+            if (child.type === "dotted_name" &&
+                getNodeText(child, source).includes(symbolName)) {
+                const lineIndex = child.startPosition.row;
+                references.push({
+                    path: filePath,
+                    line: lineIndex + 1,
+                    column: child.startPosition.column + 1,
+                    context: lines[lineIndex]?.trim() || "",
+                    type: "import",
+                });
+            }
+        }
+    }
+    // Recurse into children
+    for (const child of node.children) {
+        findReferencesInNode(child, source, symbolName, includeDefinition, filePath, lines, references);
+    }
+}
+/**
+ * Determine the type of reference based on context
+ */
+function determineReferenceType(node, includeDefinition) {
+    const parent = node.parent;
+    if (!parent)
+        return "read";
+    // Definition sites
+    if (parent.type === "function_definition" ||
+        parent.type === "async_function_definition" ||
+        parent.type === "class_definition") {
+        return includeDefinition ? "definition" : null;
+    }
+    // Parameter definition
+    if (parent.type === "parameters" ||
+        parent.type === "typed_parameter" ||
+        parent.type === "default_parameter") {
+        return includeDefinition ? "definition" : null;
+    }
+    // Assignment left side
+    if (parent.type === "assignment" || parent.type === "annotated_assignment") {
+        const leftNode = parent.childForFieldName("left");
+        if (leftNode &&
+            node.startIndex >= leftNode.startIndex &&
+            node.endIndex <= leftNode.endIndex) {
+            return "write";
+        }
+    }
+    // Augmented assignment
+    if (parent.type === "augmented_assignment") {
+        const leftNode = parent.children[0];
+        if (leftNode &&
+            node.startIndex >= leftNode.startIndex &&
+            node.endIndex <= leftNode.endIndex) {
+            return "write";
+        }
+    }
+    // Function call
+    if (parent.type === "call") {
+        const funcNode = parent.childForFieldName("function");
+        if (funcNode &&
+            node.startIndex >= funcNode.startIndex &&
+            node.endIndex <= funcNode.endIndex) {
+            return "call";
+        }
+    }
+    // Import
+    if (parent.type === "import_statement" ||
+        parent.type === "import_from_statement" ||
+        parent.type === "aliased_import") {
+        return "import";
+    }
+    // Default to read
+    return "read";
+}
+/**
+ * Factory function to create a customized findReferences tool
+ */
+export function createFindReferencesTool(options) {
+    const { defaultLimit = 50, defaultIncludeDefinition = false } = options ?? {};
+    return defineTool({
+        name: "find_references_python",
+        description: TOOL_DESCRIPTION,
+        inputSchema: TOOL_INPUT_SCHEMA,
+        execute: async (input) => {
+            return executeFindReferences({
+                ...input,
+                limit: input.limit ?? defaultLimit,
+                includeDefinition: input.includeDefinition ?? defaultIncludeDefinition,
+            });
+        },
+    });
+}

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

@@ -0,0 +1,86 @@
+/**
+ * findSymbol Tool
+ *
+ * Find the definition location of a symbol across Python codebases.
+ * Uses Tree-sitter for AST analysis.
+ */
+import type { Tool } from "@compilr-dev/agents";
+/**
+ * Python symbol kinds
+ */
+export type PythonSymbolKind = "function" | "class" | "method" | "variable" | "constant" | "parameter";
+export type PythonSymbolKindFilter = PythonSymbolKind | "any";
+/**
+ * Input for findSymbol tool
+ */
+export interface FindSymbolInput {
+    /** Symbol name to find */
+    symbol: string;
+    /** Scope the search to a specific file or directory */
+    scope?: string;
+    /** Filter by symbol kind */
+    kind?: PythonSymbolKindFilter;
+    /** Maximum results to return (default: 10) */
+    limit?: number;
+    /** Include symbols from virtual environments (default: false) */
+    includeVenv?: boolean;
+}
+/**
+ * A found symbol definition
+ */
+export interface PythonSymbolDefinition {
+    /** Symbol name */
+    name: string;
+    /** File path */
+    path: string;
+    /** Line number (1-based) */
+    line: number;
+    /** Column number (1-based) */
+    column: number;
+    /** Symbol kind */
+    kind: PythonSymbolKind;
+    /** Containing class/module (if applicable) */
+    container?: string;
+    /** Is public (doesn't start with _) */
+    isPublic: boolean;
+    /** Signature (for functions/methods) */
+    signature?: string;
+    /** Docstring summary */
+    docSummary?: string;
+    /** Confidence score (0-1) for fuzzy matches */
+    confidence: number;
+}
+/**
+ * Search statistics
+ */
+export interface SearchStats {
+    /** Number of files searched */
+    filesSearched: number;
+    /** Time taken in milliseconds */
+    timeMs: number;
+}
+/**
+ * Output from findSymbol tool
+ */
+export interface FindSymbolResult {
+    /** Symbol that was searched */
+    query: string;
+    /** Found definitions */
+    definitions: PythonSymbolDefinition[];
+    /** Search statistics */
+    stats: SearchStats;
+}
+/**
+ * findSymbol tool - Find symbol definitions in Python
+ */
+export declare const findSymbolTool: Tool<FindSymbolInput>;
+/**
+ * Factory function to create a customized findSymbol tool
+ */
+export declare function createFindSymbolTool(options?: {
+    /** Default limit */
+    defaultLimit?: number;
+    /** Default includeVenv */
+    defaultIncludeVenv?: boolean;
+}): Tool<FindSymbolInput>;
+//# sourceMappingURL=find-symbol.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"find-symbol.d.ts","sourceRoot":"","sources":["../../src/tools/find-symbol.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AASH,OAAO,KAAK,EAAE,IAAI,EAAuB,MAAM,qBAAqB,CAAC;AAYrE;;GAEG;AACH,MAAM,MAAM,gBAAgB,GACxB,UAAU,GACV,OAAO,GACP,QAAQ,GACR,UAAU,GACV,UAAU,GACV,WAAW,CAAC;AAEhB,MAAM,MAAM,sBAAsB,GAAG,gBAAgB,GAAG,KAAK,CAAC;AAE9D;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,0BAA0B;IAC1B,MAAM,EAAE,MAAM,CAAC;IACf,uDAAuD;IACvD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,4BAA4B;IAC5B,IAAI,CAAC,EAAE,sBAAsB,CAAC;IAC9B,8CAA8C;IAC9C,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,iEAAiE;IACjE,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB;AAED;;GAEG;AACH,MAAM,WAAW,sBAAsB;IACrC,kBAAkB;IAClB,IAAI,EAAE,MAAM,CAAC;IACb,gBAAgB;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,4BAA4B;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,8BAA8B;IAC9B,MAAM,EAAE,MAAM,CAAC;IACf,kBAAkB;IAClB,IAAI,EAAE,gBAAgB,CAAC;IACvB,8CAA8C;IAC9C,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,uCAAuC;IACvC,QAAQ,EAAE,OAAO,CAAC;IAClB,wCAAwC;IACxC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,wBAAwB;IACxB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,+CAA+C;IAC/C,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,+BAA+B;IAC/B,aAAa,EAAE,MAAM,CAAC;IACtB,iCAAiC;IACjC,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,+BAA+B;IAC/B,KAAK,EAAE,MAAM,CAAC;IACd,wBAAwB;IACxB,WAAW,EAAE,sBAAsB,EAAE,CAAC;IACtC,wBAAwB;IACxB,KAAK,EAAE,WAAW,CAAC;CACpB;AAwCD;;GAEG;AACH,eAAO,MAAM,cAAc,uBAKzB,CAAC;AA4aH;;GAEG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,CAAC,EAAE;IAC7C,oBAAoB;IACpB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,0BAA0B;IAC1B,kBAAkB,CAAC,EAAE,OAAO,CAAC;CAC9B,GAAG,IAAI,CAAC,eAAe,CAAC,CAexB"}