@compilr-dev/agents-coding-python 0.1.0

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

@@ -0,0 +1,387 @@
+/**
+ * getDependencyGraph Tool
+ *
+ * Analyze module-level dependencies in Python code.
+ * Builds a dependency graph and detects circular dependencies.
+ */
+import * as fs from "node:fs/promises";
+import { accessSync } from "node:fs";
+import * as path from "node:path";
+import { defineTool, createSuccessResult, createErrorResult, } from "@compilr-dev/agents";
+import { parseFile, parseImport } from "../parser/python-parser.js";
+// Tool description
+const TOOL_DESCRIPTION = `Analyze module-level dependencies in Python code.
+Returns a dependency graph showing which modules import which other modules.
+Detects circular dependencies and provides dependency statistics.`;
+// Tool input schema
+const TOOL_INPUT_SCHEMA = {
+    type: "object",
+    properties: {
+        path: {
+            type: "string",
+            description: "Directory or file to analyze",
+        },
+        includeExternal: {
+            type: "boolean",
+            description: "Include external package dependencies (default: true)",
+            default: true,
+        },
+        maxDepth: {
+            type: "number",
+            description: "Maximum depth for directory traversal (default: 10)",
+            default: 10,
+        },
+    },
+    required: ["path"],
+};
+// Default exclusions
+const DEFAULT_EXCLUDE = [
+    "node_modules",
+    "__pycache__",
+    ".git",
+    "venv",
+    ".venv",
+    "env",
+    "dist",
+    "build",
+    ".tox",
+    ".eggs",
+];
+/**
+ * getDependencyGraph tool
+ */
+export const getDependencyGraphTool = defineTool({
+    name: "get_dependency_graph_python",
+    description: TOOL_DESCRIPTION,
+    inputSchema: TOOL_INPUT_SCHEMA,
+    execute: executeGetDependencyGraph,
+});
+/**
+ * Execute the getDependencyGraph tool
+ */
+async function executeGetDependencyGraph(input) {
+    const { path: inputPath, includeExternal = true, maxDepth = 10 } = 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);
+        const rootPath = stats.isDirectory()
+            ? resolvedPath
+            : path.dirname(resolvedPath);
+        // Collect files to analyze
+        const files = stats.isDirectory()
+            ? await collectFiles(resolvedPath, maxDepth)
+            : [resolvedPath];
+        if (files.length === 0) {
+            return createSuccessResult({
+                root: rootPath,
+                modules: [],
+                edges: [],
+                circularDependencies: [],
+                stats: {
+                    totalModules: 0,
+                    internalModules: 0,
+                    externalPackages: 0,
+                    totalEdges: 0,
+                    circularDependencies: 0,
+                    externalPackageList: [],
+                },
+            });
+        }
+        // Analyze dependencies
+        const result = await analyzeDependencies(files, rootPath, includeExternal);
+        return createSuccessResult(result);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return createErrorResult(`Failed to analyze dependencies: ${message}`);
+    }
+}
+/**
+ * Collect Python files
+ */
+async function collectFiles(dir, maxDepth, currentDepth = 0) {
+    if (currentDepth >= maxDepth)
+        return [];
+    const files = [];
+    try {
+        const entries = await fs.readdir(dir, { withFileTypes: true });
+        for (const entry of entries) {
+            const fullPath = path.join(dir, entry.name);
+            if (entry.isDirectory()) {
+                if (DEFAULT_EXCLUDE.includes(entry.name))
+                    continue;
+                const subFiles = await collectFiles(fullPath, maxDepth, currentDepth + 1);
+                files.push(...subFiles);
+            }
+            else if (entry.isFile()) {
+                if (fullPath.endsWith(".py") && !fullPath.endsWith(".pyi")) {
+                    files.push(fullPath);
+                }
+            }
+        }
+    }
+    catch {
+        // Silently skip directories we can't read
+    }
+    return files;
+}
+/**
+ * Analyze dependencies across files
+ */
+async function analyzeDependencies(files, rootPath, includeExternal) {
+    const modules = new Map();
+    const edges = [];
+    const externalPackages = new Set();
+    // Track adjacency for cycle detection
+    const adjacency = new Map();
+    for (const file of files) {
+        const relativePath = path.relative(rootPath, file);
+        const imports = await extractImports(file);
+        // Add this module
+        if (!modules.has(relativePath)) {
+            modules.set(relativePath, {
+                path: relativePath,
+                absolutePath: file,
+                isExternal: false,
+            });
+        }
+        const moduleDeps = [];
+        for (const imp of imports) {
+            // Determine if external
+            const isExternal = !imp.isRelative;
+            if (isExternal) {
+                if (!includeExternal)
+                    continue;
+                // Extract package name
+                const packageName = imp.module.split(".")[0];
+                externalPackages.add(packageName);
+                // Add external module node
+                if (!modules.has(packageName)) {
+                    modules.set(packageName, {
+                        path: packageName,
+                        absolutePath: packageName,
+                        isExternal: true,
+                        packageName,
+                    });
+                }
+                edges.push({
+                    from: relativePath,
+                    to: packageName,
+                    importType: imp.isFromImport ? "from_import" : "import",
+                    symbols: imp.names.map((n) => n.name),
+                    isRelative: false,
+                });
+                moduleDeps.push(packageName);
+            }
+            else {
+                // Internal import - resolve path
+                const resolvedPath = resolveImportPath(file, imp.module, rootPath);
+                if (resolvedPath) {
+                    const relativeResolved = path.relative(rootPath, resolvedPath);
+                    // Add target module if not exists
+                    if (!modules.has(relativeResolved)) {
+                        modules.set(relativeResolved, {
+                            path: relativeResolved,
+                            absolutePath: resolvedPath,
+                            isExternal: false,
+                        });
+                    }
+                    edges.push({
+                        from: relativePath,
+                        to: relativeResolved,
+                        importType: imp.isFromImport ? "from_import" : "import",
+                        symbols: imp.names.map((n) => n.name),
+                        isRelative: imp.isRelative,
+                    });
+                    moduleDeps.push(relativeResolved);
+                }
+            }
+        }
+        adjacency.set(relativePath, moduleDeps);
+    }
+    // Detect circular dependencies
+    const circularDependencies = detectCircularDependencies(adjacency);
+    // Calculate statistics
+    const internalModules = Array.from(modules.values()).filter((m) => !m.isExternal);
+    const dependencyCounts = new Map();
+    const dependentCounts = new Map();
+    for (const edge of edges) {
+        dependencyCounts.set(edge.from, (dependencyCounts.get(edge.from) ?? 0) + 1);
+        dependentCounts.set(edge.to, (dependentCounts.get(edge.to) ?? 0) + 1);
+    }
+    let mostDependencies;
+    let mostDependents;
+    for (const [module, count] of dependencyCounts) {
+        if (!mostDependencies || count > mostDependencies.count) {
+            mostDependencies = { module, count };
+        }
+    }
+    for (const [module, count] of dependentCounts) {
+        if (!mostDependents || count > mostDependents.count) {
+            mostDependents = { module, count };
+        }
+    }
+    const stats = {
+        totalModules: modules.size,
+        internalModules: internalModules.length,
+        externalPackages: externalPackages.size,
+        totalEdges: edges.length,
+        circularDependencies: circularDependencies.length,
+        externalPackageList: Array.from(externalPackages).sort(),
+        mostDependencies,
+        mostDependents,
+    };
+    return {
+        root: rootPath,
+        modules: Array.from(modules.values()),
+        edges,
+        circularDependencies,
+        stats,
+    };
+}
+/**
+ * Extract imports from a Python file
+ */
+async function extractImports(filePath) {
+    const imports = [];
+    try {
+        const parseResult = await parseFile(filePath);
+        const { tree, source } = parseResult;
+        for (const child of tree.rootNode.children) {
+            if (child.type === "import_statement" ||
+                child.type === "import_from_statement") {
+                const importInfo = parseImport(child, source);
+                imports.push({
+                    module: importInfo.module,
+                    isFromImport: importInfo.isFromImport,
+                    isRelative: importInfo.isRelative,
+                    names: importInfo.names,
+                });
+            }
+        }
+    }
+    catch {
+        // Silently skip files that can't be parsed
+    }
+    return imports;
+}
+/**
+ * Resolve import path to absolute file path
+ */
+function resolveImportPath(fromFile, importModule, _rootPath) {
+    const fromDir = path.dirname(fromFile);
+    // Handle relative imports (start with .)
+    if (importModule.startsWith(".")) {
+        // Count leading dots
+        let dots = 0;
+        while (importModule[dots] === ".") {
+            dots++;
+        }
+        // Go up (dots - 1) directories
+        let baseDir = fromDir;
+        for (let i = 1; i < dots; i++) {
+            baseDir = path.dirname(baseDir);
+        }
+        // Get remaining module path
+        const modulePath = importModule.slice(dots).replace(/\./g, path.sep);
+        const basePath = path.join(baseDir, modulePath);
+        return tryResolvePath(basePath);
+    }
+    // Absolute import within project
+    const modulePath = importModule.replace(/\./g, path.sep);
+    const basePath = path.join(fromDir, modulePath);
+    return tryResolvePath(basePath);
+}
+/**
+ * Try to resolve a path with various extensions
+ */
+function tryResolvePath(basePath) {
+    const candidates = [`${basePath}.py`, path.join(basePath, "__init__.py")];
+    for (const candidate of candidates) {
+        try {
+            accessSync(candidate);
+            return candidate;
+        }
+        catch {
+            // Continue to next candidate
+        }
+    }
+    return undefined;
+}
+/**
+ * Detect circular dependencies using DFS
+ */
+function detectCircularDependencies(adjacency) {
+    const cycles = [];
+    const visited = new Set();
+    const recursionStack = new Set();
+    const currentPath = [];
+    function dfs(node) {
+        if (recursionStack.has(node)) {
+            // Found a cycle
+            const cycleStart = currentPath.indexOf(node);
+            if (cycleStart !== -1) {
+                const cycle = [...currentPath.slice(cycleStart), node];
+                // Avoid duplicate cycles
+                const cycleKey = [...cycle].sort().join("->");
+                if (!cycles.some((c) => [...c.cycle].sort().join("->") === cycleKey)) {
+                    cycles.push({
+                        cycle,
+                        length: cycle.length - 1,
+                    });
+                }
+            }
+            return;
+        }
+        if (visited.has(node)) {
+            return;
+        }
+        visited.add(node);
+        recursionStack.add(node);
+        currentPath.push(node);
+        const deps = adjacency.get(node) ?? [];
+        for (const dep of deps) {
+            // Only check internal dependencies
+            if (adjacency.has(dep)) {
+                dfs(dep);
+            }
+        }
+        currentPath.pop();
+        recursionStack.delete(node);
+    }
+    for (const node of adjacency.keys()) {
+        if (!visited.has(node)) {
+            dfs(node);
+        }
+    }
+    return cycles;
+}
+/**
+ * Factory function to create a customized getDependencyGraph tool
+ */
+export function createGetDependencyGraphTool(options) {
+    const { defaultIncludeExternal = true, defaultMaxDepth = 10 } = options ?? {};
+    return defineTool({
+        name: "get_dependency_graph_python",
+        description: TOOL_DESCRIPTION,
+        inputSchema: TOOL_INPUT_SCHEMA,
+        execute: async (input) => {
+            return executeGetDependencyGraph({
+                ...input,
+                includeExternal: input.includeExternal ?? defaultIncludeExternal,
+                maxDepth: input.maxDepth ?? defaultMaxDepth,
+            });
+        },
+    });
+}

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

@@ -0,0 +1,78 @@
+/**
+ * getExports Tool
+ *
+ * Get all exports from a Python module.
+ * Analyzes __all__ declarations and identifies public API.
+ */
+import type { Tool } from "@compilr-dev/agents";
+/**
+ * Export kind
+ */
+export type ExportKind = "function" | "async_function" | "class" | "variable" | "constant" | "module" | "unknown";
+/**
+ * Exported symbol
+ */
+export interface ExportedSymbol {
+    name: string;
+    kind: ExportKind;
+    line: number;
+    signature?: string;
+    docstring?: string;
+    isPrivate?: boolean;
+    inAll?: boolean;
+}
+/**
+ * Re-export info
+ */
+export interface ReExport {
+    symbols: string[] | "*";
+    from: string;
+    line: number;
+    isRelative?: boolean;
+}
+/**
+ * Export statistics
+ */
+export interface ExportStats {
+    totalExports: number;
+    functions: number;
+    classes: number;
+    variables: number;
+    reExports: number;
+    hasAll: boolean;
+    allCount?: number;
+}
+/**
+ * Input for getExports tool
+ */
+export interface GetExportsInput {
+    /** File to analyze */
+    path: string;
+    /** Include re-exports from imports (default: true) */
+    includeReExports?: boolean;
+    /** Include private symbols with _ prefix (default: false) */
+    includePrivate?: boolean;
+}
+/**
+ * Result of getExports
+ */
+export interface GetExportsResult {
+    path: string;
+    allDeclaration?: string[];
+    publicExports: ExportedSymbol[];
+    privateSymbols?: ExportedSymbol[];
+    reExports?: ReExport[];
+    stats: ExportStats;
+}
+/**
+ * getExports tool
+ */
+export declare const getExportsTool: Tool<GetExportsInput>;
+/**
+ * Factory function to create a customized getExports tool
+ */
+export declare function createGetExportsTool(options?: {
+    defaultIncludeReExports?: boolean;
+    defaultIncludePrivate?: boolean;
+}): Tool<GetExportsInput>;
+//# sourceMappingURL=get-exports.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"get-exports.d.ts","sourceRoot":"","sources":["../../src/tools/get-exports.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AASH,OAAO,KAAK,EAAE,IAAI,EAAuB,MAAM,qBAAqB,CAAC;AAQrE;;GAEG;AACH,MAAM,MAAM,UAAU,GAClB,UAAU,GACV,gBAAgB,GAChB,OAAO,GACP,UAAU,GACV,UAAU,GACV,QAAQ,GACR,SAAS,CAAC;AAEd;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,UAAU,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED;;GAEG;AACH,MAAM,WAAW,QAAQ;IACvB,OAAO,EAAE,MAAM,EAAE,GAAG,GAAG,CAAC;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,CAAC,EAAE,OAAO,CAAC;CACtB;AAED;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,YAAY,EAAE,MAAM,CAAC;IACrB,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,OAAO,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,sBAAsB;IACtB,IAAI,EAAE,MAAM,CAAC;IACb,sDAAsD;IACtD,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B,6DAA6D;IAC7D,cAAc,CAAC,EAAE,OAAO,CAAC;CAC1B;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;IAC1B,aAAa,EAAE,cAAc,EAAE,CAAC;IAChC,cAAc,CAAC,EAAE,cAAc,EAAE,CAAC;IAClC,SAAS,CAAC,EAAE,QAAQ,EAAE,CAAC;IACvB,KAAK,EAAE,WAAW,CAAC;CACpB;AA6BD;;GAEG;AACH,eAAO,MAAM,cAAc,uBAKzB,CAAC;AA2bH;;GAEG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,CAAC,EAAE;IAC7C,uBAAuB,CAAC,EAAE,OAAO,CAAC;IAClC,qBAAqB,CAAC,EAAE,OAAO,CAAC;CACjC,GAAG,IAAI,CAAC,eAAe,CAAC,CAexB"}