@compilr-dev/agents-coding-python 0.1.0

package/dist/tools/find-symbol.js

@@ -0,0 +1,414 @@
+/**
+ * findSymbol Tool
+ *
+ * Find the definition location of 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, parseClass, parseFunction, parseVariable, parseDecorators, } from "../parser/python-parser.js";
+// Supported file extensions for searching
+const SUPPORTED_EXTENSIONS = new Set([".py", ".pyi"]);
+// Tool description
+const TOOL_DESCRIPTION = `Find the definition location of a symbol by name across Python codebases.
+Returns structured JSON with file path, line number, symbol kind, and other metadata.
+Use this to locate where functions, classes, variables, etc. are defined.`;
+// Tool input schema
+const TOOL_INPUT_SCHEMA = {
+    type: "object",
+    properties: {
+        symbol: {
+            type: "string",
+            description: "Symbol name to find",
+        },
+        scope: {
+            type: "string",
+            description: "Scope the search to a specific file or directory",
+        },
+        kind: {
+            type: "string",
+            enum: ["function", "class", "method", "variable", "constant", "any"],
+            description: "Filter by symbol kind (default: any)",
+            default: "any",
+        },
+        limit: {
+            type: "number",
+            description: "Maximum results to return (default: 10)",
+            default: 10,
+        },
+        includeVenv: {
+            type: "boolean",
+            description: "Include symbols from virtual environments/site-packages (default: false)",
+            default: false,
+        },
+    },
+    required: ["symbol"],
+};
+/**
+ * findSymbol tool - Find symbol definitions in Python
+ */
+export const findSymbolTool = defineTool({
+    name: "find_symbol_python",
+    description: TOOL_DESCRIPTION,
+    inputSchema: TOOL_INPUT_SCHEMA,
+    execute: executeFindSymbol,
+});
+/**
+ * Execute the findSymbol tool
+ */
+async function executeFindSymbol(input) {
+    const { symbol, scope, kind = "any", limit = 10, includeVenv = false, } = input;
+    // Validate input
+    if (!symbol || symbol.trim().length === 0) {
+        return createErrorResult("Symbol name is required");
+    }
+    const startTime = Date.now();
+    const definitions = [];
+    let filesSearched = 0;
+    try {
+        // Determine search path
+        const searchPath = scope || process.cwd();
+        // Check if path exists
+        try {
+            await fs.access(searchPath);
+        }
+        catch {
+            return createErrorResult(`Path not found: ${searchPath}`);
+        }
+        const stats = await fs.stat(searchPath);
+        if (stats.isFile()) {
+            // Search single file
+            if (isPythonFile(searchPath)) {
+                filesSearched = 1;
+                const fileDefinitions = await searchFileForSymbol(searchPath, symbol, kind);
+                definitions.push(...fileDefinitions);
+            }
+        }
+        else if (stats.isDirectory()) {
+            // Search directory recursively
+            const files = await collectFiles(searchPath, includeVenv);
+            filesSearched = files.length;
+            for (const filePath of files) {
+                if (definitions.length >= limit)
+                    break;
+                const fileDefinitions = await searchFileForSymbol(filePath, symbol, kind);
+                const remaining = limit - definitions.length;
+                definitions.push(...fileDefinitions.slice(0, remaining));
+            }
+        }
+        else {
+            return createErrorResult(`Path is neither a file nor directory: ${searchPath}`);
+        }
+        const endTime = Date.now();
+        const result = {
+            query: symbol,
+            definitions: definitions.slice(0, limit),
+            stats: {
+                filesSearched,
+                timeMs: endTime - startTime,
+            },
+        };
+        return createSuccessResult(result);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return createErrorResult(`Failed to search for symbol: ${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 recursively
+ */
+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()) {
+                // Skip virtual environments unless explicitly included
+                if (!includeVenv &&
+                    (entry.name === "venv" ||
+                        entry.name === ".venv" ||
+                        entry.name === "env" ||
+                        entry.name === ".env" ||
+                        entry.name === "site-packages" ||
+                        entry.name === "__pycache__")) {
+                    continue;
+                }
+                // Skip common non-source directories
+                if (entry.name.startsWith(".") ||
+                    entry.name === "dist" ||
+                    entry.name === "build" ||
+                    entry.name === "eggs" ||
+                    entry.name === "*.egg-info") {
+                    continue;
+                }
+                await walk(fullPath);
+            }
+            else if (entry.isFile()) {
+                if (isPythonFile(fullPath)) {
+                    files.push(fullPath);
+                }
+            }
+        }
+    }
+    await walk(dir);
+    return files;
+}
+/**
+ * Search a single file for symbol definitions
+ */
+async function searchFileForSymbol(filePath, symbolName, kindFilter) {
+    const definitions = [];
+    try {
+        const parseResult = await parseFile(filePath);
+        const { tree, source } = parseResult;
+        const rootNode = tree.rootNode;
+        // Search for symbols in the AST
+        for (const child of rootNode.children) {
+            // Function definitions
+            if (child.type === "function_definition" ||
+                child.type === "async_function_definition") {
+                const funcInfo = parseFunction(child, source);
+                if (funcInfo.name === symbolName) {
+                    if (kindFilter === "any" || kindFilter === "function") {
+                        definitions.push({
+                            name: funcInfo.name,
+                            path: filePath,
+                            line: funcInfo.line,
+                            column: funcInfo.column + 1,
+                            kind: "function",
+                            isPublic: !funcInfo.name.startsWith("_"),
+                            signature: buildFunctionSignature(funcInfo),
+                            docSummary: funcInfo.docstring?.split("\n")[0],
+                            confidence: 1.0,
+                        });
+                    }
+                }
+            }
+            // Decorated definitions
+            if (child.type === "decorated_definition") {
+                const decorators = parseDecorators(child, source);
+                const funcNode = child.children.find((c) => c.type === "function_definition" ||
+                    c.type === "async_function_definition");
+                const classNode = child.children.find((c) => c.type === "class_definition");
+                if (funcNode) {
+                    const funcInfo = parseFunction(funcNode, source, decorators);
+                    if (funcInfo.name === symbolName) {
+                        if (kindFilter === "any" || kindFilter === "function") {
+                            definitions.push({
+                                name: funcInfo.name,
+                                path: filePath,
+                                line: funcInfo.line,
+                                column: funcInfo.column + 1,
+                                kind: "function",
+                                isPublic: !funcInfo.name.startsWith("_"),
+                                signature: buildFunctionSignature(funcInfo),
+                                docSummary: funcInfo.docstring?.split("\n")[0],
+                                confidence: 1.0,
+                            });
+                        }
+                    }
+                }
+                if (classNode) {
+                    const classInfo = parseClass(classNode, source, decorators);
+                    if (classInfo.name === symbolName) {
+                        if (kindFilter === "any" || kindFilter === "class") {
+                            definitions.push({
+                                name: classInfo.name,
+                                path: filePath,
+                                line: classInfo.line,
+                                column: classInfo.column + 1,
+                                kind: "class",
+                                isPublic: !classInfo.name.startsWith("_"),
+                                signature: buildClassSignature(classInfo),
+                                docSummary: classInfo.docstring?.split("\n")[0],
+                                confidence: 1.0,
+                            });
+                        }
+                    }
+                    // Search methods inside the class
+                    if (kindFilter === "any" || kindFilter === "method") {
+                        for (const method of classInfo.methods) {
+                            if (method.name === symbolName) {
+                                definitions.push({
+                                    name: method.name,
+                                    path: filePath,
+                                    line: method.line,
+                                    column: method.column + 1,
+                                    kind: "method",
+                                    container: classInfo.name,
+                                    isPublic: !method.name.startsWith("_"),
+                                    signature: buildMethodSignature(method, classInfo.name),
+                                    docSummary: method.docstring?.split("\n")[0],
+                                    confidence: 1.0,
+                                });
+                            }
+                        }
+                    }
+                }
+            }
+            // Class definitions (non-decorated)
+            if (child.type === "class_definition") {
+                const classInfo = parseClass(child, source);
+                if (classInfo.name === symbolName) {
+                    if (kindFilter === "any" || kindFilter === "class") {
+                        definitions.push({
+                            name: classInfo.name,
+                            path: filePath,
+                            line: classInfo.line,
+                            column: classInfo.column + 1,
+                            kind: "class",
+                            isPublic: !classInfo.name.startsWith("_"),
+                            signature: buildClassSignature(classInfo),
+                            docSummary: classInfo.docstring?.split("\n")[0],
+                            confidence: 1.0,
+                        });
+                    }
+                }
+                // Search methods inside the class
+                if (kindFilter === "any" || kindFilter === "method") {
+                    for (const method of classInfo.methods) {
+                        if (method.name === symbolName) {
+                            definitions.push({
+                                name: method.name,
+                                path: filePath,
+                                line: method.line,
+                                column: method.column + 1,
+                                kind: "method",
+                                container: classInfo.name,
+                                isPublic: !method.name.startsWith("_"),
+                                signature: buildMethodSignature(method, classInfo.name),
+                                docSummary: method.docstring?.split("\n")[0],
+                                confidence: 1.0,
+                            });
+                        }
+                    }
+                }
+            }
+            // Variable assignments at module level
+            if (child.type === "expression_statement") {
+                const expr = child.firstChild;
+                if (expr &&
+                    (expr.type === "assignment" || expr.type === "annotated_assignment")) {
+                    const varInfo = parseVariable(expr, source);
+                    if (varInfo && varInfo.name === symbolName) {
+                        const varKind = varInfo.isConstant
+                            ? "constant"
+                            : "variable";
+                        if (kindFilter === "any" ||
+                            kindFilter === varKind ||
+                            (kindFilter === "variable" && varKind === "constant")) {
+                            definitions.push({
+                                name: varInfo.name,
+                                path: filePath,
+                                line: varInfo.line,
+                                column: varInfo.column + 1,
+                                kind: varKind,
+                                isPublic: !varInfo.name.startsWith("_"),
+                                signature: buildVariableSignature(varInfo),
+                                confidence: 1.0,
+                            });
+                        }
+                    }
+                }
+            }
+        }
+    }
+    catch {
+        // Silently skip files that can't be parsed
+    }
+    return definitions;
+}
+/**
+ * Build a function signature string
+ */
+function buildFunctionSignature(func) {
+    const asyncPrefix = func.isAsync ? "async " : "";
+    const params = func.parameters
+        .map((p) => {
+        let param = p.name;
+        if (p.type)
+            param += `: ${p.type}`;
+        if (p.default)
+            param += ` = ${p.default}`;
+        return param;
+    })
+        .join(", ");
+    const returnType = func.returnType ? ` -> ${func.returnType}` : "";
+    return `${asyncPrefix}def ${func.name}(${params})${returnType}`;
+}
+/**
+ * Build a method signature string
+ */
+function buildMethodSignature(method, className) {
+    const prefix = method.isStaticMethod
+        ? "@staticmethod "
+        : method.isClassMethod
+            ? "@classmethod "
+            : method.isProperty
+                ? "@property "
+                : "";
+    const asyncPrefix = method.isAsync ? "async " : "";
+    const params = method.parameters
+        .map((p) => {
+        let param = p.name;
+        if (p.type)
+            param += `: ${p.type}`;
+        if (p.default)
+            param += ` = ${p.default}`;
+        return param;
+    })
+        .join(", ");
+    const returnType = method.returnType ? ` -> ${method.returnType}` : "";
+    return `${prefix}${asyncPrefix}def ${className}.${method.name}(${params})${returnType}`;
+}
+/**
+ * Build a class signature string
+ */
+function buildClassSignature(classInfo) {
+    const dataclassPrefix = classInfo.isDataclass ? "@dataclass " : "";
+    const bases = classInfo.bases.length > 0 ? `(${classInfo.bases.join(", ")})` : "";
+    return `${dataclassPrefix}class ${classInfo.name}${bases}`;
+}
+/**
+ * Build a variable signature string
+ */
+function buildVariableSignature(varInfo) {
+    let sig = varInfo.name;
+    if (varInfo.type)
+        sig += `: ${varInfo.type}`;
+    if (varInfo.value) {
+        const valuePreview = varInfo.value.length > 50
+            ? varInfo.value.substring(0, 47) + "..."
+            : varInfo.value;
+        sig += ` = ${valuePreview}`;
+    }
+    return sig;
+}
+/**
+ * Factory function to create a customized findSymbol tool
+ */
+export function createFindSymbolTool(options) {
+    const { defaultLimit = 10, defaultIncludeVenv = false } = options ?? {};
+    return defineTool({
+        name: "find_symbol_python",
+        description: TOOL_DESCRIPTION,
+        inputSchema: TOOL_INPUT_SCHEMA,
+        execute: async (input) => {
+            return executeFindSymbol({
+                ...input,
+                limit: input.limit ?? defaultLimit,
+                includeVenv: input.includeVenv ?? defaultIncludeVenv,
+            });
+        },
+    });
+}

package/dist/tools/get-call-graph.d.ts

@@ -0,0 +1,89 @@
+/**
+ * getCallGraph Tool
+ *
+ * Analyze function call relationships in Python code.
+ * Returns a call graph showing what functions call what.
+ */
+import type { Tool } from "@compilr-dev/agents";
+/**
+ * Direction for call graph traversal
+ */
+export type CallGraphDirection = "callers" | "callees" | "both";
+/**
+ * Call type
+ */
+export type CallType = "direct" | "method" | "constructor" | "decorator";
+/**
+ * Function node in the call graph
+ */
+export interface FunctionNode {
+    name: string;
+    path: string;
+    line: number;
+    column?: number;
+    className?: string;
+    async?: boolean;
+}
+/**
+ * Call info
+ */
+export interface CallInfo {
+    function: FunctionNode;
+    callLine: number;
+    callColumn?: number;
+    type: CallType;
+    count: number;
+}
+/**
+ * Call graph node
+ */
+export interface CallGraphNode {
+    function: FunctionNode;
+    calls: CallInfo[];
+    calledBy: CallInfo[];
+}
+/**
+ * Call graph stats
+ */
+export interface CallGraphStats {
+    totalFunctions: number;
+    totalCalls: number;
+    maxDepthReached: number;
+    externalCalls?: number;
+}
+/**
+ * Input for getCallGraph tool
+ */
+export interface GetCallGraphInput {
+    /** File to analyze */
+    path: string;
+    /** Specific function to analyze (optional) */
+    functionName?: string;
+    /** Direction: 'callers' | 'callees' | 'both' (default: 'both') */
+    direction?: CallGraphDirection;
+    /** Maximum depth to traverse (default: 2) */
+    maxDepth?: number;
+    /** Include external package calls (default: false) */
+    includeExternal?: boolean;
+}
+/**
+ * Result of getCallGraph
+ */
+export interface GetCallGraphResult {
+    root?: FunctionNode;
+    graph: CallGraphNode[];
+    stats: CallGraphStats;
+}
+/**
+ * getCallGraph tool
+ */
+export declare const getCallGraphTool: Tool<GetCallGraphInput>;
+/**
+ * Factory function to create a customized getCallGraph tool
+ */
+export declare function createGetCallGraphTool(options?: {
+    defaultDirection?: CallGraphDirection;
+    defaultMaxDepth?: number;
+    defaultIncludeExternal?: boolean;
+}): Tool<GetCallGraphInput>;
+//# sourceMappingURL=get-call-graph.d.ts.map

package/dist/tools/get-call-graph.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"get-call-graph.d.ts","sourceRoot":"","sources":["../../src/tools/get-call-graph.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AASH,OAAO,KAAK,EAAE,IAAI,EAAuB,MAAM,qBAAqB,CAAC;AAQrE;;GAEG;AACH,MAAM,MAAM,kBAAkB,GAAG,SAAS,GAAG,SAAS,GAAG,MAAM,CAAC;AAEhE;;GAEG;AACH,MAAM,MAAM,QAAQ,GAAG,QAAQ,GAAG,QAAQ,GAAG,aAAa,GAAG,WAAW,CAAC;AAEzE;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED;;GAEG;AACH,MAAM,WAAW,QAAQ;IACvB,QAAQ,EAAE,YAAY,CAAC;IACvB,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,IAAI,EAAE,QAAQ,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;CACf;AAED;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,QAAQ,EAAE,YAAY,CAAC;IACvB,KAAK,EAAE,QAAQ,EAAE,CAAC;IAClB,QAAQ,EAAE,QAAQ,EAAE,CAAC;CACtB;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,cAAc,EAAE,MAAM,CAAC;IACvB,UAAU,EAAE,MAAM,CAAC;IACnB,eAAe,EAAE,MAAM,CAAC;IACxB,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,sBAAsB;IACtB,IAAI,EAAE,MAAM,CAAC;IACb,8CAA8C;IAC9C,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,kEAAkE;IAClE,SAAS,CAAC,EAAE,kBAAkB,CAAC;IAC/B,6CAA6C;IAC7C,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,sDAAsD;IACtD,eAAe,CAAC,EAAE,OAAO,CAAC;CAC3B;AAED;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,IAAI,CAAC,EAAE,YAAY,CAAC;IACpB,KAAK,EAAE,aAAa,EAAE,CAAC;IACvB,KAAK,EAAE,cAAc,CAAC;CACvB;AA+CD;;GAEG;AACH,eAAO,MAAM,gBAAgB,yBAK3B,CAAC;AA6dH;;GAEG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,CAAC,EAAE;IAC/C,gBAAgB,CAAC,EAAE,kBAAkB,CAAC;IACtC,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,sBAAsB,CAAC,EAAE,OAAO,CAAC;CAClC,GAAG,IAAI,CAAC,iBAAiB,CAAC,CAoB1B"}