@compilr-dev/agents-coding-ts 0.1.0

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

@@ -0,0 +1,482 @@
+/**
+ * getDependencyGraph Tool
+ *
+ * Analyze module-level dependencies across a directory.
+ * Builds a dependency graph and detects circular dependencies.
+ */
+import * as fs from 'node:fs/promises';
+import * as fsSync from 'node:fs';
+import * as path from 'node:path';
+import * as ts from 'typescript';
+import { defineTool, createSuccessResult, createErrorResult } from '@compilr-dev/agents';
+import { detectLanguage, isLanguageSupported } from '../parser/typescript-parser.js';
+// Tool description
+const TOOL_DESCRIPTION = `Analyze module-level dependencies across a directory.
+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,
+        },
+        includeTypeOnly: {
+            type: 'boolean',
+            description: 'Include type-only imports (default: true)',
+            default: true,
+        },
+        maxDepth: {
+            type: 'number',
+            description: 'Maximum depth for directory traversal (default: 10)',
+            default: 10,
+        },
+    },
+    required: ['path'],
+};
+// Default file patterns
+const DEFAULT_INCLUDE = ['**/*.ts', '**/*.tsx', '**/*.js', '**/*.jsx', '**/*.mts', '**/*.mjs'];
+const DEFAULT_EXCLUDE = ['**/node_modules/**', '**/dist/**', '**/build/**', '**/.git/**'];
+/**
+ * getDependencyGraph tool - Analyze module dependencies
+ */
+export const getDependencyGraphTool = defineTool({
+    name: 'get_dependency_graph',
+    description: TOOL_DESCRIPTION,
+    inputSchema: TOOL_INPUT_SCHEMA,
+    execute: executeGetDependencyGraph,
+});
+/**
+ * Execute the getDependencyGraph tool
+ */
+async function executeGetDependencyGraph(input) {
+    const { path: inputPath, includeExternal = true, includeTypeOnly = true, maxDepth = 10, include = DEFAULT_INCLUDE, exclude = DEFAULT_EXCLUDE, } = input;
+    // Validate input
+    if (!inputPath || inputPath.trim().length === 0) {
+        return createErrorResult('Path is required');
+    }
+    try {
+        // Check if path exists
+        try {
+            await fs.access(inputPath);
+        }
+        catch {
+            return createErrorResult(`Path not found: ${inputPath}`);
+        }
+        const stats = await fs.stat(inputPath);
+        const rootPath = stats.isDirectory() ? inputPath : path.dirname(inputPath);
+        // Collect files to analyze
+        const files = stats.isDirectory()
+            ? await collectFiles(inputPath, include, exclude, maxDepth)
+            : [inputPath];
+        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, includeTypeOnly);
+        return createSuccessResult(result);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return createErrorResult(`Failed to analyze dependencies: ${message}`);
+    }
+}
+/**
+ * Collect files matching patterns
+ */
+async function collectFiles(dir, include, exclude, 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);
+            const relativePath = fullPath;
+            // Check exclusions
+            if (matchesPattern(relativePath, exclude)) {
+                continue;
+            }
+            if (entry.isDirectory()) {
+                const subFiles = await collectFiles(fullPath, include, exclude, maxDepth, currentDepth + 1);
+                files.push(...subFiles);
+            }
+            else if (entry.isFile()) {
+                // Check if file matches include patterns
+                if (matchesPattern(relativePath, include) && isSupportedFile(fullPath)) {
+                    files.push(fullPath);
+                }
+            }
+        }
+    }
+    catch {
+        // Silently skip directories we can't read
+    }
+    return files;
+}
+/**
+ * Check if a path matches any of the patterns
+ */
+function matchesPattern(filePath, patterns) {
+    const fileName = path.basename(filePath);
+    for (const pattern of patterns) {
+        // Handle simple glob patterns
+        if (pattern.includes('**')) {
+            // Check if any directory in path matches
+            const patternDir = pattern.replace('**/', '').replace('/**', '');
+            if (filePath.includes(patternDir.replace('*', ''))) {
+                return true;
+            }
+        }
+        else if (pattern.startsWith('*.')) {
+            // Extension pattern
+            const ext = pattern.substring(1);
+            if (fileName.endsWith(ext)) {
+                return true;
+            }
+        }
+        else if (filePath.includes(pattern) || fileName === pattern) {
+            return true;
+        }
+    }
+    return false;
+}
+/**
+ * Check if file is supported
+ */
+function isSupportedFile(filePath) {
+    const detection = detectLanguage(filePath);
+    if (!detection.language) {
+        return false;
+    }
+    return isLanguageSupported(detection.language);
+}
+/**
+ * Analyze dependencies across files
+ */
+async function analyzeDependencies(files, rootPath, includeExternal, includeTypeOnly) {
+    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) {
+            // Skip type-only if not requested
+            if (imp.typeOnly && !includeTypeOnly) {
+                continue;
+            }
+            // Determine if external
+            const isExternal = !imp.source.startsWith('.') && !imp.source.startsWith('/');
+            if (isExternal) {
+                if (!includeExternal) {
+                    continue;
+                }
+                // Extract package name (handle scoped packages)
+                const packageName = imp.source.startsWith('@')
+                    ? imp.source.split('/').slice(0, 2).join('/')
+                    : imp.source.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.importType,
+                    typeOnly: imp.typeOnly,
+                    symbolCount: imp.symbols.length,
+                    symbols: imp.symbols.slice(0, 10),
+                });
+                moduleDeps.push(packageName);
+            }
+            else {
+                // Internal import - resolve path
+                const resolvedPath = resolveImportPath(file, imp.source, 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.importType,
+                        typeOnly: imp.typeOnly,
+                        symbolCount: imp.symbols.length,
+                        symbols: imp.symbols.slice(0, 10),
+                    });
+                    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 file
+ */
+async function extractImports(filePath) {
+    const imports = [];
+    try {
+        const sourceCode = await fs.readFile(filePath, 'utf-8');
+        const scriptKind = getScriptKind(filePath);
+        const sourceFile = ts.createSourceFile(filePath, sourceCode, ts.ScriptTarget.Latest, true, scriptKind);
+        ts.forEachChild(sourceFile, (node) => {
+            // Import declarations
+            if (ts.isImportDeclaration(node)) {
+                if (ts.isStringLiteral(node.moduleSpecifier)) {
+                    const source = node.moduleSpecifier.text;
+                    // Check for type-only import by looking at the import text
+                    const importText = node.getText(sourceFile);
+                    const typeOnly = importText.includes('import type');
+                    const symbols = [];
+                    let importType = 'side-effect';
+                    if (node.importClause) {
+                        // Default import
+                        if (node.importClause.name) {
+                            importType = 'default';
+                            symbols.push(node.importClause.name.text);
+                        }
+                        // Named or namespace imports
+                        if (node.importClause.namedBindings) {
+                            if (ts.isNamespaceImport(node.importClause.namedBindings)) {
+                                importType = 'namespace';
+                                symbols.push(node.importClause.namedBindings.name.text);
+                            }
+                            else if (ts.isNamedImports(node.importClause.namedBindings)) {
+                                importType = importType === 'default' ? 'default' : 'named';
+                                for (const element of node.importClause.namedBindings.elements) {
+                                    symbols.push(element.name.text);
+                                }
+                            }
+                        }
+                    }
+                    imports.push({ source, importType, typeOnly, symbols });
+                }
+            }
+            // Export declarations with 'from' (re-exports count as dependencies)
+            if (ts.isExportDeclaration(node)) {
+                if (node.moduleSpecifier && ts.isStringLiteral(node.moduleSpecifier)) {
+                    const source = node.moduleSpecifier.text;
+                    const typeOnly = node.isTypeOnly;
+                    const symbols = [];
+                    let importType = 'namespace';
+                    if (node.exportClause && ts.isNamedExports(node.exportClause)) {
+                        importType = 'named';
+                        for (const element of node.exportClause.elements) {
+                            symbols.push(element.name.text);
+                        }
+                    }
+                    imports.push({ source, importType, typeOnly, symbols });
+                }
+            }
+        });
+    }
+    catch {
+        // Silently skip files that can't be parsed
+    }
+    return imports;
+}
+/**
+ * Resolve import path to absolute file path
+ */
+function resolveImportPath(fromFile, importSource, _rootPath) {
+    const fromDir = path.dirname(fromFile);
+    const basePath = path.resolve(fromDir, importSource);
+    // Try various extensions
+    const extensions = ['.ts', '.tsx', '.js', '.jsx', '.mts', '.mjs', ''];
+    for (const ext of extensions) {
+        const candidate = basePath + ext;
+        try {
+            // Check if file exists synchronously for simplicity
+            // (we're already in an async context and this is a quick check)
+            fsSync.accessSync(candidate);
+            return candidate;
+        }
+        catch {
+            // Try index file
+            const indexCandidate = path.join(basePath, `index${ext || '.ts'}`);
+            try {
+                fsSync.accessSync(indexCandidate);
+                return indexCandidate;
+            }
+            catch {
+                // Continue to next extension
+            }
+        }
+    }
+    return undefined;
+}
+/**
+ * Detect circular dependencies using DFS
+ */
+function detectCircularDependencies(adjacency) {
+    const cycles = [];
+    const visited = new Set();
+    const recursionStack = new Set();
+    const path = [];
+    function dfs(node) {
+        if (recursionStack.has(node)) {
+            // Found a cycle
+            const cycleStart = path.indexOf(node);
+            if (cycleStart !== -1) {
+                const cycle = [...path.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);
+        path.push(node);
+        const deps = adjacency.get(node) ?? [];
+        for (const dep of deps) {
+            // Only check internal dependencies
+            if (adjacency.has(dep)) {
+                dfs(dep);
+            }
+        }
+        path.pop();
+        recursionStack.delete(node);
+    }
+    for (const node of adjacency.keys()) {
+        if (!visited.has(node)) {
+            dfs(node);
+        }
+    }
+    return cycles;
+}
+/**
+ * Get TypeScript script kind from file extension
+ */
+function getScriptKind(filePath) {
+    const ext = filePath.toLowerCase().split('.').pop();
+    switch (ext) {
+        case 'ts':
+            return ts.ScriptKind.TS;
+        case 'tsx':
+            return ts.ScriptKind.TSX;
+        case 'js':
+            return ts.ScriptKind.JS;
+        case 'jsx':
+            return ts.ScriptKind.JSX;
+        case 'mts':
+        case 'cts':
+            return ts.ScriptKind.TS;
+        case 'mjs':
+        case 'cjs':
+            return ts.ScriptKind.JS;
+        default:
+            return ts.ScriptKind.TS;
+    }
+}
+/**
+ * Factory function to create a customized getDependencyGraph tool
+ */
+export function createGetDependencyGraphTool(options) {
+    const { defaultIncludeExternal = true, defaultIncludeTypeOnly = true, defaultMaxDepth = 10, } = options ?? {};
+    return defineTool({
+        name: 'get_dependency_graph',
+        description: TOOL_DESCRIPTION,
+        inputSchema: TOOL_INPUT_SCHEMA,
+        execute: async (input) => {
+            return executeGetDependencyGraph({
+                ...input,
+                includeExternal: input.includeExternal ?? defaultIncludeExternal,
+                includeTypeOnly: input.includeTypeOnly ?? defaultIncludeTypeOnly,
+                maxDepth: input.maxDepth ?? defaultMaxDepth,
+            });
+        },
+    });
+}

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

@@ -0,0 +1,21 @@
+/**
+ * getDocumentation Tool
+ *
+ * Extract JSDoc/TSDoc documentation from source files.
+ * Provides documentation coverage metrics and identifies undocumented exports.
+ */
+import type { Tool } from '@compilr-dev/agents';
+import type { GetDocumentationInput } from './types.js';
+/**
+ * getDocumentation tool
+ */
+export declare const getDocumentationTool: Tool<GetDocumentationInput>;
+/**
+ * Create customizable getDocumentation tool
+ */
+export declare function createGetDocumentationTool(options?: {
+    name?: string;
+    description?: string;
+    defaultMaxFiles?: number;
+    defaultDocumentedOnly?: boolean;
+}): Tool<GetDocumentationInput>;