@compilr-dev/agents-coding-python 0.1.0

package/dist/tools/get-complexity.js

@@ -0,0 +1,384 @@
+/**
+ * getComplexity Tool
+ *
+ * Calculate cyclomatic and cognitive complexity for Python functions.
+ * Identifies complex code that may need refactoring.
+ */
+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, parseDecorators, } from "../parser/python-parser.js";
+// Tool description
+const TOOL_DESCRIPTION = `Calculate cyclomatic and cognitive complexity for Python functions.
+Identifies code that may be hard to understand or maintain.
+Returns complexity metrics and highlights hotspots that may need refactoring.`;
+// Tool input schema
+const TOOL_INPUT_SCHEMA = {
+    type: "object",
+    properties: {
+        path: {
+            type: "string",
+            description: "File or directory to analyze",
+        },
+        recursive: {
+            type: "boolean",
+            description: "Recursively analyze directory (default: false)",
+            default: false,
+        },
+        threshold: {
+            type: "number",
+            description: "Complexity threshold for warnings (default: 10)",
+            default: 10,
+        },
+        onlyAboveThreshold: {
+            type: "boolean",
+            description: "Only return items above threshold (default: false)",
+            default: false,
+        },
+        maxFiles: {
+            type: "number",
+            description: "Maximum files to analyze (default: 50)",
+            default: 50,
+        },
+    },
+    required: ["path"],
+};
+/**
+ * getComplexity tool - Calculate code complexity
+ */
+export const getComplexityTool = defineTool({
+    name: "get_complexity_python",
+    description: TOOL_DESCRIPTION,
+    inputSchema: TOOL_INPUT_SCHEMA,
+    execute: executeGetComplexity,
+});
+/**
+ * Execute the getComplexity tool
+ */
+async function executeGetComplexity(input) {
+    const { path: targetPath, recursive = false, threshold = 10, onlyAboveThreshold = false, maxFiles = 50, } = input;
+    const resolvedPath = path.resolve(targetPath);
+    try {
+        await fs.access(resolvedPath);
+    }
+    catch {
+        return createErrorResult(`Path not found: ${resolvedPath}`);
+    }
+    const stats = await fs.stat(resolvedPath);
+    try {
+        const files = [];
+        if (stats.isFile()) {
+            if (!resolvedPath.endsWith(".py") && !resolvedPath.endsWith(".pyi")) {
+                return createErrorResult(`Not a Python file: ${resolvedPath}`);
+            }
+            const fileResult = await analyzeFileComplexity(resolvedPath, threshold, onlyAboveThreshold);
+            files.push(fileResult);
+        }
+        else if (stats.isDirectory()) {
+            const pythonFiles = await collectPythonFiles(resolvedPath, recursive, maxFiles);
+            for (const filePath of pythonFiles) {
+                const fileResult = await analyzeFileComplexity(filePath, threshold, onlyAboveThreshold);
+                if (fileResult.functions.length > 0 || !onlyAboveThreshold) {
+                    files.push(fileResult);
+                }
+            }
+        }
+        // Calculate summary
+        let totalFunctions = 0;
+        let totalComplexity = 0;
+        let maxComplexity = 0;
+        let aboveThreshold = 0;
+        const hotspots = [];
+        for (const file of files) {
+            totalFunctions += file.functions.length;
+            for (const func of file.functions) {
+                totalComplexity += func.metrics.cyclomatic;
+                if (func.metrics.cyclomatic > maxComplexity) {
+                    maxComplexity = func.metrics.cyclomatic;
+                }
+                if (func.isComplex) {
+                    aboveThreshold++;
+                }
+                hotspots.push({
+                    name: func.name,
+                    path: file.path,
+                    line: func.line,
+                    cyclomatic: func.metrics.cyclomatic,
+                    cognitive: func.metrics.cognitive,
+                });
+            }
+        }
+        // Sort hotspots by complexity and take top 5
+        hotspots.sort((a, b) => b.cyclomatic - a.cyclomatic);
+        const topHotspots = hotspots.slice(0, 5);
+        const result = {
+            path: resolvedPath,
+            files,
+            summary: {
+                totalFiles: files.length,
+                totalFunctions,
+                averageComplexity: totalFunctions > 0 ? totalComplexity / totalFunctions : 0,
+                maxComplexity,
+                aboveThreshold,
+                threshold,
+            },
+            hotspots: topHotspots,
+        };
+        return createSuccessResult(result);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return createErrorResult(`Failed to analyze complexity: ${message}`);
+    }
+}
+/**
+ * Analyze complexity for a single file
+ */
+async function analyzeFileComplexity(filePath, threshold, onlyAboveThreshold) {
+    const parseResult = await parseFile(filePath);
+    const { tree, source } = parseResult;
+    const functions = [];
+    // Analyze top-level functions
+    for (const child of tree.rootNode.children) {
+        if (child.type === "function_definition" ||
+            child.type === "async_function_definition") {
+            const funcInfo = parseFunction(child, source);
+            const metrics = calculateComplexity(child, source);
+            const isComplex = metrics.cyclomatic >= threshold;
+            if (!onlyAboveThreshold || isComplex) {
+                functions.push({
+                    name: funcInfo.name,
+                    path: filePath,
+                    line: funcInfo.line,
+                    metrics,
+                    isComplex,
+                });
+            }
+        }
+        // Decorated functions
+        if (child.type === "decorated_definition") {
+            const funcNode = child.children.find((c) => c.type === "function_definition" ||
+                c.type === "async_function_definition");
+            if (funcNode) {
+                const decorators = parseDecorators(child, source);
+                const funcInfo = parseFunction(funcNode, source, decorators);
+                const metrics = calculateComplexity(funcNode, source);
+                const isComplex = metrics.cyclomatic >= threshold;
+                if (!onlyAboveThreshold || isComplex) {
+                    functions.push({
+                        name: funcInfo.name,
+                        path: filePath,
+                        line: funcInfo.line,
+                        metrics,
+                        isComplex,
+                    });
+                }
+            }
+        }
+        // Class methods
+        if (child.type === "class_definition") {
+            const classInfo = parseClass(child, source);
+            const body = child.childForFieldName("body");
+            if (body) {
+                for (const member of body.children) {
+                    if (member.type === "function_definition" ||
+                        member.type === "async_function_definition") {
+                        const funcInfo = parseFunction(member, source);
+                        const metrics = calculateComplexity(member, source);
+                        const isComplex = metrics.cyclomatic >= threshold;
+                        if (!onlyAboveThreshold || isComplex) {
+                            functions.push({
+                                name: `${classInfo.name}.${funcInfo.name}`,
+                                path: filePath,
+                                line: funcInfo.line,
+                                metrics,
+                                isComplex,
+                            });
+                        }
+                    }
+                    if (member.type === "decorated_definition") {
+                        const funcNode = member.children.find((c) => c.type === "function_definition" ||
+                            c.type === "async_function_definition");
+                        if (funcNode) {
+                            const decorators = parseDecorators(member, source);
+                            const funcInfo = parseFunction(funcNode, source, decorators);
+                            const metrics = calculateComplexity(funcNode, source);
+                            const isComplex = metrics.cyclomatic >= threshold;
+                            if (!onlyAboveThreshold || isComplex) {
+                                functions.push({
+                                    name: `${classInfo.name}.${funcInfo.name}`,
+                                    path: filePath,
+                                    line: funcInfo.line,
+                                    metrics,
+                                    isComplex,
+                                });
+                            }
+                        }
+                    }
+                }
+            }
+        }
+    }
+    // Calculate file-level averages
+    const totalCyclomatic = functions.reduce((sum, f) => sum + f.metrics.cyclomatic, 0);
+    const maxCyclomatic = Math.max(0, ...functions.map((f) => f.metrics.cyclomatic));
+    const complexCount = functions.filter((f) => f.isComplex).length;
+    return {
+        path: filePath,
+        functions,
+        averageComplexity: functions.length > 0 ? totalCyclomatic / functions.length : 0,
+        maxComplexity: maxCyclomatic,
+        stats: {
+            totalFunctions: functions.length,
+            complexFunctions: complexCount,
+            simpleAverage: functions.length > 0 ? totalCyclomatic / functions.length : 0,
+        },
+    };
+}
+/**
+ * Calculate complexity metrics for a function
+ */
+function calculateComplexity(node, _source) {
+    let cyclomatic = 1; // Base complexity
+    let cognitive = 0;
+    let maxNesting = 0;
+    let paramCount = 0;
+    // Count parameters
+    const paramsNode = node.childForFieldName("parameters");
+    if (paramsNode) {
+        for (const child of paramsNode.children) {
+            if (child.type === "identifier" ||
+                child.type === "typed_parameter" ||
+                child.type === "default_parameter" ||
+                child.type === "typed_default_parameter") {
+                paramCount++;
+            }
+        }
+    }
+    // Walk the AST and count complexity contributors
+    function walk(n, depth) {
+        // Track nesting
+        const isNestingConstruct = n.type === "if_statement" ||
+            n.type === "for_statement" ||
+            n.type === "while_statement" ||
+            n.type === "try_statement" ||
+            n.type === "with_statement" ||
+            n.type === "match_statement";
+        if (isNestingConstruct) {
+            if (depth > maxNesting) {
+                maxNesting = depth;
+            }
+        }
+        // Cyclomatic complexity contributors
+        switch (n.type) {
+            case "if_statement":
+            case "elif_clause":
+                cyclomatic++;
+                cognitive += 1 + depth; // Cognitive adds nesting penalty
+                break;
+            case "for_statement":
+            case "while_statement":
+                cyclomatic++;
+                cognitive += 1 + depth;
+                break;
+            case "except_clause":
+                cyclomatic++;
+                cognitive++;
+                break;
+            case "conditional_expression": // Ternary
+                cyclomatic++;
+                cognitive++;
+                break;
+            case "boolean_operator":
+                // and/or add to cyclomatic
+                cyclomatic++;
+                break;
+            case "match_statement":
+                cyclomatic++;
+                cognitive += 1 + depth;
+                break;
+            case "case_clause":
+                cyclomatic++;
+                break;
+            case "lambda":
+                cognitive++; // Lambdas add cognitive load
+                break;
+            case "list_comprehension":
+            case "dictionary_comprehension":
+            case "set_comprehension":
+            case "generator_expression":
+                cognitive++; // Comprehensions add cognitive load
+                break;
+        }
+        // Recurse into children
+        const newDepth = isNestingConstruct ? depth + 1 : depth;
+        for (const child of n.children) {
+            walk(child, newDepth);
+        }
+    }
+    const body = node.childForFieldName("body");
+    if (body) {
+        walk(body, 0);
+    }
+    // Calculate lines of code
+    const startLine = node.startPosition.row;
+    const endLine = node.endPosition.row;
+    const linesOfCode = endLine - startLine + 1;
+    return {
+        cyclomatic,
+        cognitive,
+        linesOfCode,
+        parameters: paramCount,
+        nestingDepth: maxNesting,
+    };
+}
+/**
+ * Collect Python files in a directory
+ */
+async function collectPythonFiles(dir, recursive, maxFiles) {
+    const files = [];
+    async function walk(currentDir) {
+        if (files.length >= maxFiles)
+            return;
+        const entries = await fs.readdir(currentDir, { withFileTypes: true });
+        for (const entry of entries) {
+            if (files.length >= maxFiles)
+                break;
+            const fullPath = path.join(currentDir, entry.name);
+            if (entry.isDirectory() && recursive) {
+                if (entry.name.startsWith(".") ||
+                    entry.name === "__pycache__" ||
+                    entry.name === "venv" ||
+                    entry.name === ".venv" ||
+                    entry.name === "node_modules") {
+                    continue;
+                }
+                await walk(fullPath);
+            }
+            else if (entry.isFile() &&
+                (fullPath.endsWith(".py") || fullPath.endsWith(".pyi"))) {
+                files.push(fullPath);
+            }
+        }
+    }
+    await walk(dir);
+    return files;
+}
+/**
+ * Factory function to create a customized getComplexity tool
+ */
+export function createGetComplexityTool(options) {
+    const { defaultThreshold = 10, defaultRecursive = false } = options ?? {};
+    return defineTool({
+        name: "get_complexity_python",
+        description: TOOL_DESCRIPTION,
+        inputSchema: TOOL_INPUT_SCHEMA,
+        execute: async (input) => {
+            return executeGetComplexity({
+                ...input,
+                threshold: input.threshold ?? defaultThreshold,
+                recursive: input.recursive ?? defaultRecursive,
+            });
+        },
+    });
+}

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

@@ -0,0 +1,85 @@
+/**
+ * getDependencyGraph Tool
+ *
+ * Analyze module-level dependencies in Python code.
+ * Builds a dependency graph and detects circular dependencies.
+ */
+import type { Tool } from "@compilr-dev/agents";
+/**
+ * Module node in the dependency graph
+ */
+export interface ModuleNode {
+    path: string;
+    absolutePath: string;
+    isExternal: boolean;
+    packageName?: string;
+}
+/**
+ * Dependency edge
+ */
+export interface DependencyEdge {
+    from: string;
+    to: string;
+    importType: "import" | "from_import";
+    symbols: string[];
+    isRelative: boolean;
+}
+/**
+ * Circular dependency
+ */
+export interface CircularDependency {
+    cycle: string[];
+    length: number;
+}
+/**
+ * Dependency graph stats
+ */
+export interface DependencyGraphStats {
+    totalModules: number;
+    internalModules: number;
+    externalPackages: number;
+    totalEdges: number;
+    circularDependencies: number;
+    externalPackageList: string[];
+    mostDependencies?: {
+        module: string;
+        count: number;
+    };
+    mostDependents?: {
+        module: string;
+        count: number;
+    };
+}
+/**
+ * Input for getDependencyGraph tool
+ */
+export interface GetDependencyGraphInput {
+    /** Directory or file to analyze */
+    path: string;
+    /** Include external package dependencies (default: true) */
+    includeExternal?: boolean;
+    /** Maximum depth for directory traversal (default: 10) */
+    maxDepth?: number;
+}
+/**
+ * Result of getDependencyGraph
+ */
+export interface GetDependencyGraphResult {
+    root: string;
+    modules: ModuleNode[];
+    edges: DependencyEdge[];
+    circularDependencies: CircularDependency[];
+    stats: DependencyGraphStats;
+}
+/**
+ * getDependencyGraph tool
+ */
+export declare const getDependencyGraphTool: Tool<GetDependencyGraphInput>;
+/**
+ * Factory function to create a customized getDependencyGraph tool
+ */
+export declare function createGetDependencyGraphTool(options?: {
+    defaultIncludeExternal?: boolean;
+    defaultMaxDepth?: number;
+}): Tool<GetDependencyGraphInput>;
+//# sourceMappingURL=get-dependency-graph.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"get-dependency-graph.d.ts","sourceRoot":"","sources":["../../src/tools/get-dependency-graph.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAUH,OAAO,KAAK,EAAE,IAAI,EAAuB,MAAM,qBAAqB,CAAC;AAGrE;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,YAAY,EAAE,MAAM,CAAC;IACrB,UAAU,EAAE,OAAO,CAAC;IACpB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,MAAM,CAAC;IACX,UAAU,EAAE,QAAQ,GAAG,aAAa,CAAC;IACrC,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,UAAU,EAAE,OAAO,CAAC;CACrB;AAED;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC,YAAY,EAAE,MAAM,CAAC;IACrB,eAAe,EAAE,MAAM,CAAC;IACxB,gBAAgB,EAAE,MAAM,CAAC;IACzB,UAAU,EAAE,MAAM,CAAC;IACnB,oBAAoB,EAAE,MAAM,CAAC;IAC7B,mBAAmB,EAAE,MAAM,EAAE,CAAC;IAC9B,gBAAgB,CAAC,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC;IACrD,cAAc,CAAC,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC;CACpD;AAED;;GAEG;AACH,MAAM,WAAW,uBAAuB;IACtC,mCAAmC;IACnC,IAAI,EAAE,MAAM,CAAC;IACb,4DAA4D;IAC5D,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,0DAA0D;IAC1D,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;GAEG;AACH,MAAM,WAAW,wBAAwB;IACvC,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,UAAU,EAAE,CAAC;IACtB,KAAK,EAAE,cAAc,EAAE,CAAC;IACxB,oBAAoB,EAAE,kBAAkB,EAAE,CAAC;IAC3C,KAAK,EAAE,oBAAoB,CAAC;CAC7B;AA2CD;;GAEG;AACH,eAAO,MAAM,sBAAsB,+BAKjC,CAAC;AA8YH;;GAEG;AACH,wBAAgB,4BAA4B,CAAC,OAAO,CAAC,EAAE;IACrD,sBAAsB,CAAC,EAAE,OAAO,CAAC;IACjC,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B,GAAG,IAAI,CAAC,uBAAuB,CAAC,CAiBhC"}