@compilr-dev/agents-coding-python 0.1.0

package/dist/tools/get-exports.js

@@ -0,0 +1,437 @@
+/**
+ * getExports Tool
+ *
+ * Get all exports from a Python module.
+ * Analyzes __all__ declarations and identifies public API.
+ */
+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 = `Get all exports from a Python module.
+Analyzes __all__ declarations and identifies public API surface.
+Use this to understand what a module exposes to other modules.`;
+// Tool input schema
+const TOOL_INPUT_SCHEMA = {
+    type: "object",
+    properties: {
+        path: {
+            type: "string",
+            description: "File to analyze",
+        },
+        includeReExports: {
+            type: "boolean",
+            description: "Include re-exports from imports (default: true)",
+            default: true,
+        },
+        includePrivate: {
+            type: "boolean",
+            description: "Include private symbols with _ prefix (default: false)",
+            default: false,
+        },
+    },
+    required: ["path"],
+};
+/**
+ * getExports tool
+ */
+export const getExportsTool = defineTool({
+    name: "get_exports_python",
+    description: TOOL_DESCRIPTION,
+    inputSchema: TOOL_INPUT_SCHEMA,
+    execute: executeGetExports,
+});
+/**
+ * Execute the getExports tool
+ */
+async function executeGetExports(input) {
+    const { path: inputPath, includeReExports = true, includePrivate = false, } = input;
+    // Validate input
+    if (!inputPath || inputPath.trim().length === 0) {
+        return createErrorResult("Path is required");
+    }
+    try {
+        const resolvedPath = path.resolve(inputPath);
+        // Check if file exists
+        try {
+            await fs.access(resolvedPath);
+        }
+        catch {
+            return createErrorResult(`File 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 analyzeExports(resolvedPath, includeReExports, includePrivate);
+        return createSuccessResult({
+            ...result,
+            path: resolvedPath,
+        });
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return createErrorResult(`Failed to analyze exports: ${message}`);
+    }
+}
+/**
+ * Analyze exports in a Python file
+ */
+async function analyzeExports(filePath, includeReExports, includePrivate) {
+    const parseResult = await parseFile(filePath);
+    const { tree, source } = parseResult;
+    const allDeclaration = [];
+    const publicExports = [];
+    const privateSymbols = [];
+    const reExports = [];
+    // Track names in __all__
+    const allNames = new Set();
+    // First pass: find __all__ declaration
+    for (const child of tree.rootNode.children) {
+        if (child.type === "expression_statement") {
+            const expr = child.children[0];
+            if (expr?.type === "assignment") {
+                const left = expr.childForFieldName("left");
+                if (left?.text === "__all__") {
+                    const right = expr.childForFieldName("right");
+                    if (right) {
+                        const names = extractAllNames(right);
+                        names.forEach((n) => {
+                            allDeclaration.push(n);
+                            allNames.add(n);
+                        });
+                    }
+                }
+            }
+        }
+    }
+    // Second pass: extract all module-level definitions
+    for (const child of tree.rootNode.children) {
+        // Function definitions
+        if (child.type === "function_definition") {
+            const funcInfo = parseFunction(child, source);
+            const isPrivate = funcInfo.name.startsWith("_");
+            const inAll = allNames.has(funcInfo.name);
+            const symbol = {
+                name: funcInfo.name,
+                kind: "function",
+                line: funcInfo.line,
+                signature: buildFunctionSignature(child, source),
+                docstring: extractDocstring(child),
+                isPrivate,
+                inAll,
+            };
+            if (isPrivate && !inAll) {
+                if (includePrivate)
+                    privateSymbols.push(symbol);
+            }
+            else {
+                publicExports.push(symbol);
+            }
+        }
+        // Async function definitions
+        else if (child.type === "async_function_definition") {
+            const funcDef = child.children.find((c) => c.type === "function_definition");
+            if (funcDef) {
+                const funcInfo = parseFunction(funcDef, source);
+                const isPrivate = funcInfo.name.startsWith("_");
+                const inAll = allNames.has(funcInfo.name);
+                const symbol = {
+                    name: funcInfo.name,
+                    kind: "async_function",
+                    line: funcInfo.line,
+                    signature: `async ${buildFunctionSignature(funcDef, source)}`,
+                    docstring: extractDocstring(funcDef),
+                    isPrivate,
+                    inAll,
+                };
+                if (isPrivate && !inAll) {
+                    if (includePrivate)
+                        privateSymbols.push(symbol);
+                }
+                else {
+                    publicExports.push(symbol);
+                }
+            }
+        }
+        // Class definitions
+        else if (child.type === "class_definition") {
+            const classInfo = parseClass(child, source);
+            const isPrivate = classInfo.name.startsWith("_");
+            const inAll = allNames.has(classInfo.name);
+            const symbol = {
+                name: classInfo.name,
+                kind: "class",
+                line: classInfo.line,
+                signature: buildClassSignature(child, source),
+                docstring: extractDocstring(child),
+                isPrivate,
+                inAll,
+            };
+            if (isPrivate && !inAll) {
+                if (includePrivate)
+                    privateSymbols.push(symbol);
+            }
+            else {
+                publicExports.push(symbol);
+            }
+        }
+        // Decorated definitions
+        else if (child.type === "decorated_definition") {
+            const definition = child.children.find((c) => c.type === "function_definition" ||
+                c.type === "async_function_definition" ||
+                c.type === "class_definition");
+            if (definition) {
+                if (definition.type === "class_definition") {
+                    const classInfo = parseClass(definition, source);
+                    const isPrivate = classInfo.name.startsWith("_");
+                    const inAll = allNames.has(classInfo.name);
+                    const symbol = {
+                        name: classInfo.name,
+                        kind: "class",
+                        line: classInfo.line,
+                        signature: buildClassSignature(definition, source),
+                        docstring: extractDocstring(definition),
+                        isPrivate,
+                        inAll,
+                    };
+                    if (isPrivate && !inAll) {
+                        if (includePrivate)
+                            privateSymbols.push(symbol);
+                    }
+                    else {
+                        publicExports.push(symbol);
+                    }
+                }
+                else {
+                    const funcDef = definition.type === "async_function_definition"
+                        ? definition.children.find((c) => c.type === "function_definition")
+                        : definition;
+                    if (funcDef) {
+                        const funcInfo = parseFunction(funcDef, source);
+                        const isPrivate = funcInfo.name.startsWith("_");
+                        const inAll = allNames.has(funcInfo.name);
+                        const isAsync = definition.type === "async_function_definition";
+                        const symbol = {
+                            name: funcInfo.name,
+                            kind: isAsync ? "async_function" : "function",
+                            line: funcInfo.line,
+                            signature: isAsync
+                                ? `async ${buildFunctionSignature(funcDef, source)}`
+                                : buildFunctionSignature(funcDef, source),
+                            docstring: extractDocstring(funcDef),
+                            isPrivate,
+                            inAll,
+                        };
+                        if (isPrivate && !inAll) {
+                            if (includePrivate)
+                                privateSymbols.push(symbol);
+                        }
+                        else {
+                            publicExports.push(symbol);
+                        }
+                    }
+                }
+            }
+        }
+        // Variable assignments (module-level constants/variables)
+        else if (child.type === "expression_statement") {
+            const expr = child.children[0];
+            if (expr?.type === "assignment") {
+                const left = expr.childForFieldName("left");
+                if (left?.type === "identifier" && left.text !== "__all__") {
+                    const name = left.text;
+                    const isPrivate = name.startsWith("_");
+                    const inAll = allNames.has(name);
+                    const isConstant = name === name.toUpperCase();
+                    const symbol = {
+                        name,
+                        kind: isConstant ? "constant" : "variable",
+                        line: child.startPosition.row + 1,
+                        isPrivate,
+                        inAll,
+                    };
+                    if (isPrivate && !inAll) {
+                        if (includePrivate)
+                            privateSymbols.push(symbol);
+                    }
+                    else {
+                        publicExports.push(symbol);
+                    }
+                }
+            }
+        }
+        // Import statements (for re-exports)
+        else if (includeReExports && child.type === "import_from_statement") {
+            const reExport = extractReExport(child, source);
+            if (reExport) {
+                reExports.push(reExport);
+            }
+        }
+    }
+    // Calculate statistics
+    const exportStats = {
+        totalExports: publicExports.length,
+        functions: publicExports.filter((e) => e.kind === "function" || e.kind === "async_function").length,
+        classes: publicExports.filter((e) => e.kind === "class").length,
+        variables: publicExports.filter((e) => e.kind === "variable" || e.kind === "constant").length,
+        reExports: reExports.length,
+        hasAll: allDeclaration.length > 0,
+        allCount: allDeclaration.length > 0 ? allDeclaration.length : undefined,
+    };
+    return {
+        allDeclaration: allDeclaration.length > 0 ? allDeclaration : undefined,
+        publicExports,
+        privateSymbols: includePrivate && privateSymbols.length > 0 ? privateSymbols : undefined,
+        reExports: includeReExports && reExports.length > 0 ? reExports : undefined,
+        stats: exportStats,
+    };
+}
+/**
+ * Extract names from __all__ list
+ */
+function extractAllNames(node) {
+    const names = [];
+    if (node.type === "list") {
+        for (const child of node.children) {
+            if (child.type === "string") {
+                // Remove quotes
+                const text = child.text;
+                const name = text.slice(1, -1);
+                if (name)
+                    names.push(name);
+            }
+        }
+    }
+    else if (node.type === "tuple") {
+        for (const child of node.children) {
+            if (child.type === "string") {
+                const text = child.text;
+                const name = text.slice(1, -1);
+                if (name)
+                    names.push(name);
+            }
+        }
+    }
+    return names;
+}
+/**
+ * Build function signature string
+ */
+function buildFunctionSignature(funcNode, _source) {
+    const nameNode = funcNode.childForFieldName("name");
+    const paramsNode = funcNode.childForFieldName("parameters");
+    const returnNode = funcNode.childForFieldName("return_type");
+    const name = nameNode?.text ?? "unknown";
+    const params = paramsNode?.text ?? "()";
+    const returnType = returnNode ? ` -> ${returnNode.text}` : "";
+    return `def ${name}${params}${returnType}`;
+}
+/**
+ * Build class signature string
+ */
+function buildClassSignature(classNode, _source) {
+    const nameNode = classNode.childForFieldName("name");
+    const superclassNode = classNode.childForFieldName("superclasses");
+    const name = nameNode?.text ?? "unknown";
+    const bases = superclassNode?.text ?? "";
+    return bases ? `class ${name}${bases}` : `class ${name}`;
+}
+/**
+ * Extract docstring from a definition
+ */
+function extractDocstring(node) {
+    const body = node.childForFieldName("body");
+    if (!body)
+        return undefined;
+    for (const child of body.children) {
+        if (child.type === "expression_statement") {
+            const string = child.children.find((c) => c.type === "string" || c.type === "concatenated_string");
+            if (string) {
+                // Extract first line of docstring
+                let content = string.text;
+                if (content.startsWith('"""') || content.startsWith("'''")) {
+                    content = content.slice(3, -3);
+                }
+                else if (content.startsWith('"') || content.startsWith("'")) {
+                    content = content.slice(1, -1);
+                }
+                const firstLine = content.trim().split("\n")[0];
+                return firstLine.length > 100
+                    ? firstLine.slice(0, 100) + "..."
+                    : firstLine;
+            }
+        }
+        // Stop after first non-docstring statement
+        if (child.type !== "expression_statement" && child.type !== "comment") {
+            break;
+        }
+    }
+    return undefined;
+}
+/**
+ * Extract re-export info from import statement
+ */
+function extractReExport(node, _source) {
+    // from module import name, name2
+    // from module import *
+    const moduleNode = node.childForFieldName("module_name");
+    if (!moduleNode)
+        return null;
+    const moduleName = moduleNode.text;
+    const isRelative = moduleName.startsWith(".");
+    const line = node.startPosition.row + 1;
+    // Check for star import
+    const hasWildcard = node.children.some((c) => c.type === "wildcard_import" || c.text === "*");
+    if (hasWildcard) {
+        return {
+            symbols: "*",
+            from: moduleName,
+            line,
+            isRelative,
+        };
+    }
+    // Named imports
+    const symbols = [];
+    for (const child of node.children) {
+        if (child.type === "dotted_name" && child !== moduleNode) {
+            symbols.push(child.text);
+        }
+        else if (child.type === "aliased_import") {
+            const nameNode = child.childForFieldName("name");
+            if (nameNode) {
+                symbols.push(nameNode.text);
+            }
+        }
+    }
+    if (symbols.length === 0)
+        return null;
+    return {
+        symbols,
+        from: moduleName,
+        line,
+        isRelative,
+    };
+}
+/**
+ * Factory function to create a customized getExports tool
+ */
+export function createGetExportsTool(options) {
+    return defineTool({
+        name: "get_exports_python",
+        description: TOOL_DESCRIPTION,
+        inputSchema: TOOL_INPUT_SCHEMA,
+        execute: async (input) => {
+            return executeGetExports({
+                ...input,
+                includeReExports: input.includeReExports ?? options?.defaultIncludeReExports ?? true,
+                includePrivate: input.includePrivate ?? options?.defaultIncludePrivate ?? false,
+            });
+        },
+    });
+}

package/dist/tools/get-file-structure.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Get File Structure Tool
+ *
+ * Analyzes a Python file and returns its structural overview including
+ * classes, functions, variables, and imports.
+ */
+/**
+ * Input for getFileStructure tool
+ */
+export interface GetFileStructureInput {
+    /** Path to Python file */
+    path: string;
+    /** Include private members (starting with _) */
+    includePrivate?: boolean;
+    /** Maximum nesting depth */
+    maxDepth?: number;
+}
+/**
+ * Get file structure tool
+ */
+export declare const getFileStructureTool: import("@compilr-dev/agents").Tool<GetFileStructureInput>;
+/**
+ * Factory function to create getFileStructure tool with custom options
+ */
+export declare function createGetFileStructureTool(options?: {
+    baseDir?: string;
+}): import("@compilr-dev/agents").Tool<GetFileStructureInput>;
+//# sourceMappingURL=get-file-structure.d.ts.map

package/dist/tools/get-file-structure.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"get-file-structure.d.ts","sourceRoot":"","sources":["../../src/tools/get-file-structure.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAqBH;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC,0BAA0B;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,gDAAgD;IAChD,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,4BAA4B;IAC5B,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;GAEG;AACH,eAAO,MAAM,oBAAoB,2DAwB/B,CAAC;AAyJH;;GAEG;AACH,wBAAgB,0BAA0B,CAAC,OAAO,CAAC,EAAE;IAAE,OAAO,CAAC,EAAE,MAAM,CAAA;CAAE,6DAmCxE"}

package/dist/tools/get-file-structure.js

@@ -0,0 +1,186 @@
+/**
+ * Get File Structure Tool
+ *
+ * Analyzes a Python file and returns its structural overview including
+ * classes, functions, variables, and imports.
+ */
+import { defineTool, createSuccessResult, createErrorResult, } from "@compilr-dev/agents";
+import { stat } from "node:fs/promises";
+import { resolve } from "node:path";
+import { parseFile, parseClass, parseFunction, parseImport, parseVariable, parseDecorators, extractDocstring, } from "../parser/python-parser.js";
+/**
+ * Get file structure tool
+ */
+export const getFileStructureTool = defineTool({
+    name: "get_file_structure_python",
+    description: "Get structural overview of a Python file including classes, functions, variables, and imports. " +
+        "Useful for understanding file organization and API surface.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            path: {
+                type: "string",
+                description: "Path to Python file (.py)",
+            },
+            includePrivate: {
+                type: "boolean",
+                description: "Include private members (starting with _)",
+            },
+            maxDepth: {
+                type: "number",
+                description: "Maximum nesting depth to analyze",
+            },
+        },
+        required: ["path"],
+    },
+    execute: executeGetFileStructure,
+});
+async function executeGetFileStructure(input) {
+    const filePath = resolve(input.path);
+    const includePrivate = input.includePrivate ?? false;
+    // Validate file exists and is a Python file
+    try {
+        const stats = await stat(filePath);
+        if (!stats.isFile()) {
+            return createErrorResult(`Not a file: ${filePath}`);
+        }
+        if (!filePath.endsWith(".py") && !filePath.endsWith(".pyi")) {
+            return createErrorResult(`Not a Python file: ${filePath}`);
+        }
+    }
+    catch {
+        return createErrorResult(`File not found: ${filePath}`);
+    }
+    try {
+        const parseResult = await parseFile(filePath);
+        const { tree, source } = parseResult;
+        const rootNode = tree.rootNode;
+        const result = {
+            path: filePath,
+            classes: [],
+            functions: [],
+            variables: [],
+            imports: [],
+            stats: {
+                totalClasses: 0,
+                totalFunctions: 0,
+                totalVariables: 0,
+                totalImports: 0,
+                totalLines: source.split("\n").length,
+            },
+        };
+        // Extract module docstring
+        result.docstring = extractDocstring({ childForFieldName: () => rootNode }, source);
+        // Process top-level nodes
+        for (const child of rootNode.children) {
+            // Imports
+            if (child.type === "import_statement" ||
+                child.type === "import_from_statement") {
+                const importInfo = parseImport(child, source);
+                result.imports.push(importInfo);
+                result.stats.totalImports++;
+            }
+            // Class definitions
+            if (child.type === "class_definition") {
+                const classInfo = parseClass(child, source);
+                if (includePrivate || !classInfo.name.startsWith("_")) {
+                    // Filter private methods if needed
+                    if (!includePrivate) {
+                        classInfo.methods = classInfo.methods.filter((m) => !m.name.startsWith("_") || m.name.startsWith("__"));
+                        classInfo.attributes = classInfo.attributes.filter((a) => !a.name.startsWith("_"));
+                    }
+                    result.classes.push(classInfo);
+                    result.stats.totalClasses++;
+                }
+            }
+            // Decorated class definitions
+            if (child.type === "decorated_definition") {
+                const decorators = parseDecorators(child, source);
+                const classNode = child.children.find((c) => c.type === "class_definition");
+                if (classNode) {
+                    const classInfo = parseClass(classNode, source, decorators);
+                    if (includePrivate || !classInfo.name.startsWith("_")) {
+                        if (!includePrivate) {
+                            classInfo.methods = classInfo.methods.filter((m) => !m.name.startsWith("_") || m.name.startsWith("__"));
+                            classInfo.attributes = classInfo.attributes.filter((a) => !a.name.startsWith("_"));
+                        }
+                        result.classes.push(classInfo);
+                        result.stats.totalClasses++;
+                    }
+                }
+            }
+            // Function definitions
+            if (child.type === "function_definition" ||
+                child.type === "async_function_definition") {
+                const funcInfo = parseFunction(child, source);
+                if (includePrivate || !funcInfo.name.startsWith("_")) {
+                    result.functions.push(funcInfo);
+                    result.stats.totalFunctions++;
+                }
+            }
+            // Decorated function 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");
+                if (funcNode) {
+                    const funcInfo = parseFunction(funcNode, source, decorators);
+                    if (includePrivate || !funcInfo.name.startsWith("_")) {
+                        result.functions.push(funcInfo);
+                        result.stats.totalFunctions++;
+                    }
+                }
+            }
+            // 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 && (includePrivate || !varInfo.name.startsWith("_"))) {
+                        result.variables.push(varInfo);
+                        result.stats.totalVariables++;
+                    }
+                }
+            }
+        }
+        return createSuccessResult(result);
+    }
+    catch (error) {
+        return createErrorResult(error instanceof Error ? error.message : String(error));
+    }
+}
+/**
+ * Factory function to create getFileStructure tool with custom options
+ */
+export function createGetFileStructureTool(options) {
+    return defineTool({
+        name: "get_file_structure_python",
+        description: "Get structural overview of a Python file including classes, functions, variables, and imports.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                path: {
+                    type: "string",
+                    description: "Path to Python file (.py)",
+                },
+                includePrivate: {
+                    type: "boolean",
+                    description: "Include private members (starting with _)",
+                },
+                maxDepth: {
+                    type: "number",
+                    description: "Maximum nesting depth to analyze",
+                },
+            },
+            required: ["path"],
+        },
+        execute: async (input) => {
+            let targetPath = input.path;
+            if (options?.baseDir && !targetPath.startsWith("/")) {
+                targetPath = resolve(options.baseDir, targetPath);
+            }
+            return executeGetFileStructure({ ...input, path: targetPath });
+        },
+    });
+}

package/dist/tools/get-imports.d.ts

@@ -0,0 +1,34 @@
+/**
+ * getImports Tool
+ *
+ * Analyzes imports in Python files.
+ * Categorizes imports into stdlib, third-party, and local.
+ */
+import type { Tool } from "@compilr-dev/agents";
+/**
+ * Input for getImports tool
+ */
+export interface GetImportsInput {
+    /** File or directory to analyze */
+    path: string;
+    /** Recursively analyze directory (default: false) */
+    recursive?: boolean;
+    /** Filter to specific import sources */
+    filterModule?: string;
+    /** Maximum files to analyze (default: 50) */
+    maxFiles?: number;
+}
+/**
+ * getImports tool - Analyze Python imports
+ */
+export declare const getImportsTool: Tool<GetImportsInput>;
+/**
+ * Factory function to create a customized getImports tool
+ */
+export declare function createGetImportsTool(options?: {
+    /** Default recursive */
+    defaultRecursive?: boolean;
+    /** Default maxFiles */
+    defaultMaxFiles?: number;
+}): Tool<GetImportsInput>;
+//# sourceMappingURL=get-imports.d.ts.map

package/dist/tools/get-imports.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"get-imports.d.ts","sourceRoot":"","sources":["../../src/tools/get-imports.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AASH,OAAO,KAAK,EAAE,IAAI,EAAuB,MAAM,qBAAqB,CAAC;AAwNrE;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,mCAAmC;IACnC,IAAI,EAAE,MAAM,CAAC;IACb,qDAAqD;IACrD,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,wCAAwC;IACxC,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,6CAA6C;IAC7C,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAiCD;;GAEG;AACH,eAAO,MAAM,cAAc,uBAKzB,CAAC;AAyOH;;GAEG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,CAAC,EAAE;IAC7C,wBAAwB;IACxB,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B,uBAAuB;IACvB,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B,GAAG,IAAI,CAAC,eAAe,CAAC,CAexB"}