@compilr-dev/agents-coding-python 0.1.0

package/dist/tools/get-call-graph.js

@@ -0,0 +1,431 @@
+/**
+ * getCallGraph Tool
+ *
+ * Analyze function call relationships in Python code.
+ * Returns a call graph showing what functions call what.
+ */
+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 = `Analyze function call relationships in Python code.
+Returns a call graph showing which functions call which other functions.
+Use this to understand code flow, dependencies, and refactoring impact.`;
+// Tool input schema
+const TOOL_INPUT_SCHEMA = {
+    type: "object",
+    properties: {
+        path: {
+            type: "string",
+            description: "File to analyze",
+        },
+        functionName: {
+            type: "string",
+            description: "Specific function to analyze (optional)",
+        },
+        direction: {
+            type: "string",
+            enum: ["callers", "callees", "both"],
+            description: "Direction: 'callers' | 'callees' | 'both' (default: 'both')",
+        },
+        maxDepth: {
+            type: "number",
+            description: "Maximum depth to traverse (default: 2)",
+            default: 2,
+        },
+        includeExternal: {
+            type: "boolean",
+            description: "Include external package calls (default: false)",
+            default: false,
+        },
+    },
+    required: ["path"],
+};
+/**
+ * getCallGraph tool
+ */
+export const getCallGraphTool = defineTool({
+    name: "get_call_graph_python",
+    description: TOOL_DESCRIPTION,
+    inputSchema: TOOL_INPUT_SCHEMA,
+    execute: executeGetCallGraph,
+});
+/**
+ * Execute the getCallGraph tool
+ */
+async function executeGetCallGraph(input) {
+    const { path: inputPath, functionName, direction = "both", maxDepth = 2, includeExternal = false, } = input;
+    // Validate input
+    if (!inputPath || inputPath.trim().length === 0) {
+        return createErrorResult("Path is required");
+    }
+    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.isFile()) {
+            return createErrorResult(`Path must be a file: ${resolvedPath}`);
+        }
+        if (!resolvedPath.endsWith(".py")) {
+            return createErrorResult("File must be a Python file (.py)");
+        }
+        // Analyze the file
+        const result = await analyzeCallGraph(resolvedPath, functionName, direction, maxDepth, includeExternal);
+        return createSuccessResult(result);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return createErrorResult(`Failed to analyze call graph: ${message}`);
+    }
+}
+/**
+ * Analyze call graph for a file
+ */
+async function analyzeCallGraph(filePath, functionName, direction, maxDepth, includeExternal) {
+    const parseResult = await parseFile(filePath);
+    const { tree, source } = parseResult;
+    // Find all functions in the file
+    const functions = extractFunctions(tree.rootNode, source, filePath);
+    // Build the call graph
+    const graphNodes = new Map();
+    let rootNode;
+    let externalCallCount = 0;
+    // If functionName is specified, find it
+    if (functionName) {
+        const targetFunc = functions.find((f) => f.node.name === functionName);
+        if (!targetFunc) {
+            return {
+                graph: [],
+                stats: {
+                    totalFunctions: 0,
+                    totalCalls: 0,
+                    maxDepthReached: 0,
+                },
+            };
+        }
+        rootNode = targetFunc.node;
+    }
+    // Analyze callees (what each function calls)
+    if (direction === "callees" || direction === "both") {
+        const functionsToAnalyze = functionName
+            ? functions.filter((f) => f.node.name === functionName)
+            : functions;
+        for (const func of functionsToAnalyze) {
+            const callees = extractCallees(func, functions, source, includeExternal);
+            let graphNode = graphNodes.get(func.node.name);
+            if (!graphNode) {
+                graphNode = {
+                    function: func.node,
+                    calls: [],
+                    calledBy: [],
+                };
+                graphNodes.set(func.node.name, graphNode);
+            }
+            graphNode.calls = callees;
+            if (includeExternal) {
+                externalCallCount += callees.filter((c) => c.function.path === "external").length;
+            }
+        }
+    }
+    // Analyze callers (what calls each function)
+    if (direction === "callers" || direction === "both") {
+        const functionsToAnalyze = functionName
+            ? functions.filter((f) => f.node.name === functionName)
+            : functions;
+        for (const func of functionsToAnalyze) {
+            const callers = findCallersInFile(func.node.name, functions, source, filePath);
+            let graphNode = graphNodes.get(func.node.name);
+            if (!graphNode) {
+                graphNode = {
+                    function: func.node,
+                    calls: [],
+                    calledBy: [],
+                };
+                graphNodes.set(func.node.name, graphNode);
+            }
+            graphNode.calledBy = callers;
+        }
+    }
+    // Calculate statistics
+    const graph = Array.from(graphNodes.values());
+    const totalCalls = graph.reduce((sum, node) => sum + node.calls.length, 0);
+    const callGraphStats = {
+        totalFunctions: graph.length,
+        totalCalls,
+        maxDepthReached: Math.min(maxDepth, 1),
+        externalCalls: includeExternal ? externalCallCount : undefined,
+    };
+    return {
+        root: rootNode,
+        graph,
+        stats: callGraphStats,
+    };
+}
+/**
+ * Extract all functions from an AST
+ */
+function extractFunctions(rootNode, source, filePath) {
+    const functions = [];
+    function visit(node, className) {
+        // Function definitions
+        if (node.type === "function_definition" ||
+            node.type === "async_function_definition") {
+            const funcInfo = parseFunction(node, source);
+            const isAsync = node.type === "async_function_definition";
+            functions.push({
+                node: {
+                    name: funcInfo.name,
+                    path: filePath,
+                    line: funcInfo.line,
+                    column: node.startPosition.column + 1,
+                    className,
+                    async: isAsync,
+                },
+                astNode: node,
+            });
+        }
+        // Class definitions - extract methods
+        if (node.type === "class_definition") {
+            const classInfo = parseClass(node, source);
+            const body = node.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 isAsync = member.type === "async_function_definition";
+                        functions.push({
+                            node: {
+                                name: methodInfo.name,
+                                path: filePath,
+                                line: methodInfo.line,
+                                column: member.startPosition.column + 1,
+                                className: classInfo.name,
+                                async: isAsync,
+                            },
+                            astNode: member,
+                        });
+                    }
+                    // Decorated methods
+                    if (member.type === "decorated_definition") {
+                        const funcNode = member.children.find((c) => c.type === "function_definition" ||
+                            c.type === "async_function_definition");
+                        if (funcNode) {
+                            const methodInfo = parseFunction(funcNode, source);
+                            const isAsync = funcNode.type === "async_function_definition";
+                            functions.push({
+                                node: {
+                                    name: methodInfo.name,
+                                    path: filePath,
+                                    line: methodInfo.line,
+                                    column: funcNode.startPosition.column + 1,
+                                    className: classInfo.name,
+                                    async: isAsync,
+                                },
+                                astNode: funcNode,
+                            });
+                        }
+                    }
+                }
+            }
+        }
+        // Decorated function definitions
+        if (node.type === "decorated_definition") {
+            const funcNode = node.children.find((c) => c.type === "function_definition" ||
+                c.type === "async_function_definition");
+            if (funcNode) {
+                const funcInfo = parseFunction(funcNode, source);
+                const isAsync = funcNode.type === "async_function_definition";
+                functions.push({
+                    node: {
+                        name: funcInfo.name,
+                        path: filePath,
+                        line: funcInfo.line,
+                        column: funcNode.startPosition.column + 1,
+                        className,
+                        async: isAsync,
+                    },
+                    astNode: funcNode,
+                });
+            }
+        }
+        // Recurse for nested functions (but not into class methods which are handled separately)
+        if (node.type !== "class_definition") {
+            for (const child of node.children) {
+                visit(child, className);
+            }
+        }
+    }
+    visit(rootNode);
+    return functions;
+}
+/**
+ * Extract callees (functions called by a function)
+ */
+function extractCallees(func, allFunctions, source, includeExternal) {
+    const callCounts = new Map();
+    const bodyNode = func.astNode.childForFieldName("body");
+    if (!bodyNode)
+        return [];
+    function visit(node) {
+        if (node.type === "call") {
+            const callInfo = extractCallInfo(node, allFunctions, source, includeExternal);
+            if (callInfo) {
+                const key = `${callInfo.function.name}:${callInfo.function.path}`;
+                const existing = callCounts.get(key);
+                if (existing) {
+                    existing.count++;
+                }
+                else {
+                    callCounts.set(key, callInfo);
+                }
+            }
+        }
+        for (const child of node.children) {
+            visit(child);
+        }
+    }
+    visit(bodyNode);
+    return Array.from(callCounts.values());
+}
+/**
+ * Extract call info from a call expression
+ */
+function extractCallInfo(node, allFunctions, _source, includeExternal) {
+    const functionNode = node.childForFieldName("function");
+    if (!functionNode)
+        return null;
+    let funcName;
+    let callType = "direct";
+    let className;
+    // Simple function call: func_name()
+    if (functionNode.type === "identifier") {
+        funcName = functionNode.text;
+    }
+    // Method call: obj.method() or self.method()
+    else if (functionNode.type === "attribute") {
+        const attr = functionNode.childForFieldName("attribute");
+        const obj = functionNode.childForFieldName("object");
+        if (attr) {
+            funcName = attr.text;
+            callType = "method";
+            if (obj?.type === "identifier") {
+                const objName = obj.text;
+                if (objName !== "self" && objName !== "cls") {
+                    className = objName;
+                }
+            }
+        }
+    }
+    if (!funcName)
+        return null;
+    // Check if it's a known function in the file
+    const knownFunc = allFunctions.find((f) => f.node.name === funcName);
+    if (knownFunc) {
+        return {
+            function: knownFunc.node,
+            callLine: node.startPosition.row + 1,
+            callColumn: node.startPosition.column + 1,
+            type: callType,
+            count: 1,
+        };
+    }
+    // External call (not in this file)
+    if (includeExternal) {
+        return {
+            function: {
+                name: funcName,
+                path: "external",
+                line: 0,
+                className,
+            },
+            callLine: node.startPosition.row + 1,
+            callColumn: node.startPosition.column + 1,
+            type: callType,
+            count: 1,
+        };
+    }
+    return null;
+}
+/**
+ * Find callers of a function within the same file
+ */
+function findCallersInFile(targetFuncName, allFunctions, _source, _filePath) {
+    const callerCounts = new Map();
+    for (const func of allFunctions) {
+        // Skip the function itself
+        if (func.node.name === targetFuncName)
+            continue;
+        const bodyNode = func.astNode.childForFieldName("body");
+        if (!bodyNode)
+            continue;
+        let callsTarget = false;
+        let callLine = 0;
+        let callColumn = 0;
+        let callCount = 0;
+        function visit(node) {
+            if (node.type === "call") {
+                const functionNode = node.childForFieldName("function");
+                let calledName;
+                if (functionNode?.type === "identifier") {
+                    calledName = functionNode.text;
+                }
+                else if (functionNode?.type === "attribute") {
+                    const attr = functionNode.childForFieldName("attribute");
+                    if (attr) {
+                        calledName = attr.text;
+                    }
+                }
+                if (calledName === targetFuncName) {
+                    callsTarget = true;
+                    callCount++;
+                    if (callLine === 0) {
+                        callLine = node.startPosition.row + 1;
+                        callColumn = node.startPosition.column + 1;
+                    }
+                }
+            }
+            for (const child of node.children) {
+                visit(child);
+            }
+        }
+        visit(bodyNode);
+        if (callsTarget) {
+            const key = func.node.name;
+            callerCounts.set(key, {
+                function: func.node,
+                callLine,
+                callColumn,
+                type: "direct",
+                count: callCount,
+            });
+        }
+    }
+    return Array.from(callerCounts.values());
+}
+/**
+ * Factory function to create a customized getCallGraph tool
+ */
+export function createGetCallGraphTool(options) {
+    const { defaultDirection = "both", defaultMaxDepth = 2, defaultIncludeExternal = false, } = options ?? {};
+    return defineTool({
+        name: "get_call_graph_python",
+        description: TOOL_DESCRIPTION,
+        inputSchema: TOOL_INPUT_SCHEMA,
+        execute: async (input) => {
+            return executeGetCallGraph({
+                ...input,
+                direction: input.direction ?? defaultDirection,
+                maxDepth: input.maxDepth ?? defaultMaxDepth,
+                includeExternal: input.includeExternal ?? defaultIncludeExternal,
+            });
+        },
+    });
+}

package/dist/tools/get-class-hierarchy.d.ts

@@ -0,0 +1,38 @@
+/**
+ * getClassHierarchy Tool
+ *
+ * Analyze class inheritance hierarchy in Python codebases.
+ * Finds parent classes (ancestors) and child classes (descendants).
+ */
+import type { Tool } from "@compilr-dev/agents";
+/**
+ * Direction for hierarchy traversal
+ */
+export type HierarchyDirection = "ancestors" | "descendants" | "both";
+/**
+ * Input for getClassHierarchy tool
+ */
+export interface GetClassHierarchyInput {
+    /** Class name to analyze */
+    name: string;
+    /** File where the class is defined (improves accuracy) */
+    file?: string;
+    /** Direction: 'ancestors' | 'descendants' | 'both' (default: 'both') */
+    direction?: HierarchyDirection;
+    /** Maximum depth to traverse (default: 5) */
+    maxDepth?: number;
+    /** Scope for searching descendants */
+    scope?: string;
+}
+/**
+ * getClassHierarchy tool - Analyze class inheritance
+ */
+export declare const getClassHierarchyTool: Tool<GetClassHierarchyInput>;
+/**
+ * Factory function to create a customized getClassHierarchy tool
+ */
+export declare function createGetClassHierarchyTool(options?: {
+    defaultDirection?: HierarchyDirection;
+    defaultMaxDepth?: number;
+}): Tool<GetClassHierarchyInput>;
+//# sourceMappingURL=get-class-hierarchy.d.ts.map

package/dist/tools/get-class-hierarchy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"get-class-hierarchy.d.ts","sourceRoot":"","sources":["../../src/tools/get-class-hierarchy.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AASH,OAAO,KAAK,EAAE,IAAI,EAAuB,MAAM,qBAAqB,CAAC;AAQrE;;GAEG;AACH,MAAM,MAAM,kBAAkB,GAAG,WAAW,GAAG,aAAa,GAAG,MAAM,CAAC;AAEtE;;GAEG;AACH,MAAM,WAAW,sBAAsB;IACrC,4BAA4B;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,0DAA0D;IAC1D,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,wEAAwE;IACxE,SAAS,CAAC,EAAE,kBAAkB,CAAC;IAC/B,6CAA6C;IAC7C,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,sCAAsC;IACtC,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAsCD;;GAEG;AACH,eAAO,MAAM,qBAAqB,8BAKhC,CAAC;AA+QH;;GAEG;AACH,wBAAgB,2BAA2B,CAAC,OAAO,CAAC,EAAE;IACpD,gBAAgB,CAAC,EAAE,kBAAkB,CAAC;IACtC,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B,GAAG,IAAI,CAAC,sBAAsB,CAAC,CAiB/B"}