@compilr-dev/agents-coding-python 0.1.0

package/dist/tools/get-imports.js

@@ -0,0 +1,455 @@
+/**
+ * getImports Tool
+ *
+ * Analyzes imports in Python files.
+ * Categorizes imports into stdlib, third-party, and local.
+ */
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import { defineTool, createSuccessResult, createErrorResult, } from "@compilr-dev/agents";
+import { parseFile, parseImport } from "../parser/python-parser.js";
+// Python standard library modules (Python 3.10+)
+const STDLIB_MODULES = new Set([
+    // Built-in modules
+    "abc",
+    "aifc",
+    "argparse",
+    "array",
+    "ast",
+    "asynchat",
+    "asyncio",
+    "asyncore",
+    "atexit",
+    "audioop",
+    "base64",
+    "bdb",
+    "binascii",
+    "binhex",
+    "bisect",
+    "builtins",
+    "bz2",
+    "calendar",
+    "cgi",
+    "cgitb",
+    "chunk",
+    "cmath",
+    "cmd",
+    "code",
+    "codecs",
+    "codeop",
+    "collections",
+    "colorsys",
+    "compileall",
+    "concurrent",
+    "configparser",
+    "contextlib",
+    "contextvars",
+    "copy",
+    "copyreg",
+    "cProfile",
+    "crypt",
+    "csv",
+    "ctypes",
+    "curses",
+    "dataclasses",
+    "datetime",
+    "dbm",
+    "decimal",
+    "difflib",
+    "dis",
+    "distutils",
+    "doctest",
+    "email",
+    "encodings",
+    "enum",
+    "errno",
+    "faulthandler",
+    "fcntl",
+    "filecmp",
+    "fileinput",
+    "fnmatch",
+    "fractions",
+    "ftplib",
+    "functools",
+    "gc",
+    "getopt",
+    "getpass",
+    "gettext",
+    "glob",
+    "graphlib",
+    "grp",
+    "gzip",
+    "hashlib",
+    "heapq",
+    "hmac",
+    "html",
+    "http",
+    "idlelib",
+    "imaplib",
+    "imghdr",
+    "imp",
+    "importlib",
+    "inspect",
+    "io",
+    "ipaddress",
+    "itertools",
+    "json",
+    "keyword",
+    "lib2to3",
+    "linecache",
+    "locale",
+    "logging",
+    "lzma",
+    "mailbox",
+    "mailcap",
+    "marshal",
+    "math",
+    "mimetypes",
+    "mmap",
+    "modulefinder",
+    "multiprocessing",
+    "netrc",
+    "nis",
+    "nntplib",
+    "numbers",
+    "operator",
+    "optparse",
+    "os",
+    "ossaudiodev",
+    "pathlib",
+    "pdb",
+    "pickle",
+    "pickletools",
+    "pipes",
+    "pkgutil",
+    "platform",
+    "plistlib",
+    "poplib",
+    "posix",
+    "posixpath",
+    "pprint",
+    "profile",
+    "pstats",
+    "pty",
+    "pwd",
+    "py_compile",
+    "pyclbr",
+    "pydoc",
+    "queue",
+    "quopri",
+    "random",
+    "re",
+    "readline",
+    "reprlib",
+    "resource",
+    "rlcompleter",
+    "runpy",
+    "sched",
+    "secrets",
+    "select",
+    "selectors",
+    "shelve",
+    "shlex",
+    "shutil",
+    "signal",
+    "site",
+    "smtpd",
+    "smtplib",
+    "sndhdr",
+    "socket",
+    "socketserver",
+    "spwd",
+    "sqlite3",
+    "ssl",
+    "stat",
+    "statistics",
+    "string",
+    "stringprep",
+    "struct",
+    "subprocess",
+    "sunau",
+    "symtable",
+    "sys",
+    "sysconfig",
+    "syslog",
+    "tabnanny",
+    "tarfile",
+    "telnetlib",
+    "tempfile",
+    "termios",
+    "test",
+    "textwrap",
+    "threading",
+    "time",
+    "timeit",
+    "tkinter",
+    "token",
+    "tokenize",
+    "trace",
+    "traceback",
+    "tracemalloc",
+    "tty",
+    "turtle",
+    "turtledemo",
+    "types",
+    "typing",
+    "unicodedata",
+    "unittest",
+    "urllib",
+    "uu",
+    "uuid",
+    "venv",
+    "warnings",
+    "wave",
+    "weakref",
+    "webbrowser",
+    "winreg",
+    "winsound",
+    "wsgiref",
+    "xdrlib",
+    "xml",
+    "xmlrpc",
+    "zipapp",
+    "zipfile",
+    "zipimport",
+    "zlib",
+    "zoneinfo",
+]);
+// Tool description
+const TOOL_DESCRIPTION = `Analyze imports in a Python file or directory.
+Returns categorized imports (stdlib, third-party, local) with details about each import.
+Useful for understanding dependencies and finding import issues.`;
+// 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,
+        },
+        filterModule: {
+            type: "string",
+            description: "Filter to imports from a specific module",
+        },
+        maxFiles: {
+            type: "number",
+            description: "Maximum files to analyze (default: 50)",
+            default: 50,
+        },
+    },
+    required: ["path"],
+};
+/**
+ * getImports tool - Analyze Python imports
+ */
+export const getImportsTool = defineTool({
+    name: "get_imports_python",
+    description: TOOL_DESCRIPTION,
+    inputSchema: TOOL_INPUT_SCHEMA,
+    execute: executeGetImports,
+});
+/**
+ * Execute the getImports tool
+ */
+async function executeGetImports(input) {
+    const { path: targetPath, recursive = false, filterModule, maxFiles = 50, } = input;
+    const resolvedPath = path.resolve(targetPath);
+    // Check if path exists
+    try {
+        await fs.access(resolvedPath);
+    }
+    catch {
+        return createErrorResult(`Path not found: ${resolvedPath}`);
+    }
+    const stats = await fs.stat(resolvedPath);
+    try {
+        if (stats.isFile()) {
+            // Analyze single file
+            if (!resolvedPath.endsWith(".py") && !resolvedPath.endsWith(".pyi")) {
+                return createErrorResult(`Not a Python file: ${resolvedPath}`);
+            }
+            const result = await analyzeFileImports(resolvedPath, filterModule);
+            return createSuccessResult(result);
+        }
+        else if (stats.isDirectory()) {
+            // Analyze directory
+            const files = await collectPythonFiles(resolvedPath, recursive, maxFiles);
+            const allImports = [];
+            let stdlibCount = 0;
+            let thirdPartyCount = 0;
+            let localCount = 0;
+            for (const filePath of files) {
+                const fileResult = await analyzeFileImports(filePath, filterModule);
+                allImports.push(...fileResult.imports);
+                stdlibCount += fileResult.stats.stdlib;
+                thirdPartyCount += fileResult.stats.thirdParty;
+                localCount += fileResult.stats.local;
+            }
+            // Deduplicate imports
+            const uniqueImports = deduplicateImports(allImports);
+            const result = {
+                path: resolvedPath,
+                imports: uniqueImports,
+                stats: {
+                    total: uniqueImports.length,
+                    stdlib: stdlibCount,
+                    thirdParty: thirdPartyCount,
+                    local: localCount,
+                },
+            };
+            return createSuccessResult(result);
+        }
+        else {
+            return createErrorResult(`Path is neither a file nor directory: ${resolvedPath}`);
+        }
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return createErrorResult(`Failed to analyze imports: ${message}`);
+    }
+}
+/**
+ * Analyze imports in a single file
+ */
+async function analyzeFileImports(filePath, filterModule) {
+    const parseResult = await parseFile(filePath);
+    const { tree, source } = parseResult;
+    const rootNode = tree.rootNode;
+    const imports = [];
+    let stdlibCount = 0;
+    let thirdPartyCount = 0;
+    let localCount = 0;
+    for (const child of rootNode.children) {
+        if (child.type === "import_statement" ||
+            child.type === "import_from_statement") {
+            const importInfo = parseImport(child, source);
+            const category = categorizeImport(importInfo.module, importInfo.isRelative);
+            // Apply filter if specified
+            if (filterModule && !importInfo.module.startsWith(filterModule)) {
+                continue;
+            }
+            const categorizedImport = {
+                ...importInfo,
+                category,
+            };
+            imports.push(categorizedImport);
+            switch (category) {
+                case "stdlib":
+                    stdlibCount++;
+                    break;
+                case "third_party":
+                    thirdPartyCount++;
+                    break;
+                case "local":
+                    localCount++;
+                    break;
+            }
+        }
+    }
+    return {
+        path: filePath,
+        imports,
+        stats: {
+            total: imports.length,
+            stdlib: stdlibCount,
+            thirdParty: thirdPartyCount,
+            local: localCount,
+        },
+    };
+}
+/**
+ * Categorize an import as stdlib, third-party, or local
+ */
+function categorizeImport(module, isRelative) {
+    // Relative imports are always local
+    if (isRelative) {
+        return "local";
+    }
+    // Empty module (from . import) is local
+    if (!module) {
+        return "local";
+    }
+    // Get the top-level module name
+    const topLevelModule = module.split(".")[0];
+    // Check if it's a stdlib module
+    if (STDLIB_MODULES.has(topLevelModule)) {
+        return "stdlib";
+    }
+    // Everything else is third-party
+    // Note: In a real implementation, we could check against installed packages
+    // or look for local modules in the project directory
+    return "third_party";
+}
+/**
+ * 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) {
+                // Skip common non-source directories
+                if (entry.name.startsWith(".") ||
+                    entry.name === "__pycache__" ||
+                    entry.name === "venv" ||
+                    entry.name === ".venv" ||
+                    entry.name === "env" ||
+                    entry.name === "node_modules" ||
+                    entry.name === "dist" ||
+                    entry.name === "build") {
+                    continue;
+                }
+                await walk(fullPath);
+            }
+            else if (entry.isFile()) {
+                if (fullPath.endsWith(".py") || fullPath.endsWith(".pyi")) {
+                    files.push(fullPath);
+                }
+            }
+        }
+    }
+    await walk(dir);
+    return files;
+}
+/**
+ * Deduplicate imports by module name
+ */
+function deduplicateImports(imports) {
+    const seen = new Map();
+    for (const imp of imports) {
+        const key = `${imp.module}:${imp.isFromImport}:${JSON.stringify(imp.names)}`;
+        if (!seen.has(key)) {
+            seen.set(key, imp);
+        }
+    }
+    return Array.from(seen.values());
+}
+/**
+ * Factory function to create a customized getImports tool
+ */
+export function createGetImportsTool(options) {
+    const { defaultRecursive = false, defaultMaxFiles = 50 } = options ?? {};
+    return defineTool({
+        name: "get_imports_python",
+        description: TOOL_DESCRIPTION,
+        inputSchema: TOOL_INPUT_SCHEMA,
+        execute: async (input) => {
+            return executeGetImports({
+                ...input,
+                recursive: input.recursive ?? defaultRecursive,
+                maxFiles: input.maxFiles ?? defaultMaxFiles,
+            });
+        },
+    });
+}

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

@@ -0,0 +1,100 @@
+/**
+ * getSignature Tool
+ *
+ * Get detailed signature information for a function, method, or class in Python code.
+ * Includes parameters, type hints, decorators, and docstrings.
+ */
+import type { Tool } from "@compilr-dev/agents";
+/**
+ * Python symbol kinds
+ */
+export type PythonSymbolKind = "function" | "async_function" | "method" | "class" | "variable";
+/**
+ * Parameter detail
+ */
+export interface ParameterDetail {
+    name: string;
+    type?: string;
+    optional: boolean;
+    defaultValue?: string;
+    description?: string;
+    isKwOnly?: boolean;
+    isPosOnly?: boolean;
+    isVarArgs?: boolean;
+    isKwArgs?: boolean;
+}
+/**
+ * Return type detail
+ */
+export interface ReturnTypeDetail {
+    type: string;
+    isCoroutine?: boolean;
+    nullable?: boolean;
+}
+/**
+ * Member signature (for class members)
+ */
+export interface MemberSignature {
+    name: string;
+    kind: "method" | "property" | "class_variable";
+    signature: string;
+    async?: boolean;
+    static?: boolean;
+    classmethod?: boolean;
+    decorators?: string[];
+}
+/**
+ * Documentation extracted from docstrings
+ */
+export interface Documentation {
+    summary: string;
+    description?: string;
+    params?: Record<string, string>;
+    returns?: string;
+    raises?: string[];
+    examples?: string[];
+    notes?: string;
+    deprecated?: string;
+}
+/**
+ * Input for getSignature tool
+ */
+export interface GetSignatureInput {
+    /** File containing the symbol */
+    path: string;
+    /** Symbol name to get signature for */
+    name: string;
+    /** Line number for disambiguation (optional) */
+    line?: number;
+    /** Include full documentation (default: true) */
+    includeDoc?: boolean;
+}
+/**
+ * Result of getSignature
+ */
+export interface GetSignatureResult {
+    name: string;
+    path: string;
+    kind: PythonSymbolKind;
+    line: number;
+    signature: string;
+    formattedSignature: string;
+    parameters?: ParameterDetail[];
+    returnType?: ReturnTypeDetail;
+    decorators?: string[];
+    documentation?: Documentation;
+    bases?: string[];
+    members?: MemberSignature[];
+    async?: boolean;
+}
+/**
+ * getSignature tool
+ */
+export declare const getSignatureTool: Tool<GetSignatureInput>;
+/**
+ * Factory function to create a customized getSignature tool
+ */
+export declare function createGetSignatureTool(options?: {
+    defaultIncludeDoc?: boolean;
+}): Tool<GetSignatureInput>;
+//# sourceMappingURL=get-signature.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"get-signature.d.ts","sourceRoot":"","sources":["../../src/tools/get-signature.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AASH,OAAO,KAAK,EAAE,IAAI,EAAuB,MAAM,qBAAqB,CAAC;AAQrE;;GAEG;AACH,MAAM,MAAM,gBAAgB,GACxB,UAAU,GACV,gBAAgB,GAChB,QAAQ,GACR,OAAO,GACP,UAAU,CAAC;AAEf;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,OAAO,CAAC;IAClB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,QAAQ,GAAG,UAAU,GAAG,gBAAgB,CAAC;IAC/C,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;CACvB;AAED;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAChC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IACpB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,iCAAiC;IACjC,IAAI,EAAE,MAAM,CAAC;IACb,uCAAuC;IACvC,IAAI,EAAE,MAAM,CAAC;IACb,gDAAgD;IAChD,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,iDAAiD;IACjD,UAAU,CAAC,EAAE,OAAO,CAAC;CACtB;AAED;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,gBAAgB,CAAC;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;IAClB,kBAAkB,EAAE,MAAM,CAAC;IAC3B,UAAU,CAAC,EAAE,eAAe,EAAE,CAAC;IAC/B,UAAU,CAAC,EAAE,gBAAgB,CAAC;IAC9B,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;IACtB,aAAa,CAAC,EAAE,aAAa,CAAC;IAC9B,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IACjB,OAAO,CAAC,EAAE,eAAe,EAAE,CAAC;IAC5B,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAgCD;;GAEG;AACH,eAAO,MAAM,gBAAgB,yBAK3B,CAAC;AAu3BH;;GAEG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,CAAC,EAAE;IAC/C,iBAAiB,CAAC,EAAE,OAAO,CAAC;CAC7B,GAAG,IAAI,CAAC,iBAAiB,CAAC,CAY1B"}