@compilr-dev/agents-coding-ts 0.1.0

package/dist/tools/find-symbol.js

@@ -0,0 +1,458 @@
+/**
+ * findSymbol Tool
+ *
+ * Find the definition location of a symbol across the codebase.
+ * Uses TypeScript Compiler API for accurate AST analysis.
+ */
+import * as fs from 'node:fs/promises';
+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';
+// Supported file extensions for searching
+const SUPPORTED_EXTENSIONS = new Set([
+    '.ts',
+    '.tsx',
+    '.js',
+    '.jsx',
+    '.mts',
+    '.mjs',
+    '.cts',
+    '.cjs',
+]);
+// Helper to check for a specific modifier kind
+function hasModifierKind(modifiers, kind) {
+    return modifiers?.some((m) => m.kind === kind) ?? false;
+}
+// Tool description
+const TOOL_DESCRIPTION = `Find the definition location of a symbol by name across the codebase.
+Returns structured JSON with file path, line number, symbol kind, and other metadata.
+Use this to locate where functions, classes, variables, types, etc. are defined.`;
+// Tool input schema
+const TOOL_INPUT_SCHEMA = {
+    type: 'object',
+    properties: {
+        symbol: {
+            type: 'string',
+            description: 'Symbol name to find',
+        },
+        scope: {
+            type: 'string',
+            description: 'Scope the search to a specific file or directory',
+        },
+        kind: {
+            type: 'string',
+            enum: [
+                'function',
+                'class',
+                'variable',
+                'type',
+                'interface',
+                'enum',
+                'method',
+                'property',
+                'any',
+            ],
+            description: 'Filter by symbol kind (default: any)',
+            default: 'any',
+        },
+        limit: {
+            type: 'number',
+            description: 'Maximum results to return (default: 10)',
+            default: 10,
+        },
+        includeNodeModules: {
+            type: 'boolean',
+            description: 'Include symbols from node_modules (default: false)',
+            default: false,
+        },
+    },
+    required: ['symbol'],
+};
+/**
+ * findSymbol tool - Find symbol definitions
+ */
+export const findSymbolTool = defineTool({
+    name: 'find_symbol',
+    description: TOOL_DESCRIPTION,
+    inputSchema: TOOL_INPUT_SCHEMA,
+    execute: executeFindSymbol,
+});
+/**
+ * Execute the findSymbol tool
+ */
+async function executeFindSymbol(input) {
+    const { symbol, scope, kind = 'any', limit = 10, includeNodeModules = false } = input;
+    // Validate input
+    if (!symbol || symbol.trim().length === 0) {
+        return createErrorResult('Symbol name is required');
+    }
+    const startTime = Date.now();
+    const definitions = [];
+    let filesSearched = 0;
+    try {
+        // Determine search path
+        const searchPath = scope || process.cwd();
+        // Check if path exists
+        try {
+            await fs.access(searchPath);
+        }
+        catch {
+            return createErrorResult(`Path not found: ${searchPath}`);
+        }
+        const stats = await fs.stat(searchPath);
+        if (stats.isFile()) {
+            // Search single file
+            const detection = detectLanguage(searchPath);
+            if (detection.language && isLanguageSupported(detection.language)) {
+                filesSearched = 1;
+                const fileDefinitions = await searchFileForSymbol(searchPath, symbol, kind);
+                definitions.push(...fileDefinitions);
+            }
+        }
+        else if (stats.isDirectory()) {
+            // Search directory recursively
+            const files = await collectFiles(searchPath, includeNodeModules);
+            filesSearched = files.length;
+            for (const filePath of files) {
+                if (definitions.length >= limit)
+                    break;
+                const fileDefinitions = await searchFileForSymbol(filePath, symbol, kind);
+                const remaining = limit - definitions.length;
+                definitions.push(...fileDefinitions.slice(0, remaining));
+            }
+        }
+        else {
+            return createErrorResult(`Path is neither a file nor directory: ${searchPath}`);
+        }
+        const endTime = Date.now();
+        const result = {
+            query: symbol,
+            definitions: definitions.slice(0, limit),
+            stats: {
+                filesSearched,
+                timeMs: endTime - startTime,
+            },
+        };
+        return createSuccessResult(result);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return createErrorResult(`Failed to search for symbol: ${message}`);
+    }
+}
+/**
+ * Collect all supported files in a directory recursively
+ */
+async function collectFiles(dir, includeNodeModules) {
+    const files = [];
+    async function walk(currentDir) {
+        const entries = await fs.readdir(currentDir, { withFileTypes: true });
+        for (const entry of entries) {
+            const fullPath = path.join(currentDir, entry.name);
+            if (entry.isDirectory()) {
+                // Skip node_modules unless explicitly included
+                if (entry.name === 'node_modules' && !includeNodeModules) {
+                    continue;
+                }
+                // Skip common non-source directories
+                if (entry.name.startsWith('.') ||
+                    entry.name === 'dist' ||
+                    entry.name === 'build' ||
+                    entry.name === 'coverage') {
+                    continue;
+                }
+                await walk(fullPath);
+            }
+            else if (entry.isFile()) {
+                const ext = path.extname(entry.name).toLowerCase();
+                if (SUPPORTED_EXTENSIONS.has(ext)) {
+                    files.push(fullPath);
+                }
+            }
+        }
+    }
+    await walk(dir);
+    return files;
+}
+/**
+ * Search a single file for symbol definitions
+ */
+async function searchFileForSymbol(filePath, symbolName, kindFilter) {
+    const definitions = [];
+    try {
+        const sourceCode = await fs.readFile(filePath, 'utf-8');
+        const scriptKind = getScriptKind(filePath);
+        const sourceFile = ts.createSourceFile(filePath, sourceCode, ts.ScriptTarget.Latest, true, scriptKind);
+        // Search for symbols
+        findSymbolsInNode(sourceFile, sourceFile, symbolName, kindFilter, filePath, definitions);
+    }
+    catch {
+        // Silently skip files that can't be parsed
+    }
+    return definitions;
+}
+/**
+ * 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;
+    }
+}
+/**
+ * Recursively find symbols in AST nodes
+ */
+function findSymbolsInNode(node, sourceFile, symbolName, kindFilter, filePath, definitions, container) {
+    // Check current node for symbol definition
+    const def = extractSymbolDefinition(node, sourceFile, symbolName, kindFilter, filePath, container);
+    if (def) {
+        definitions.push(def);
+    }
+    // Recurse into children
+    ts.forEachChild(node, (child) => {
+        // Track container context for methods/properties
+        let newContainer = container;
+        if (ts.isClassDeclaration(node) && node.name) {
+            newContainer = node.name.text;
+        }
+        findSymbolsInNode(child, sourceFile, symbolName, kindFilter, filePath, definitions, newContainer);
+    });
+}
+/**
+ * Extract symbol definition from a node if it matches
+ */
+function extractSymbolDefinition(node, sourceFile, symbolName, kindFilter, filePath, container) {
+    let name;
+    let kind;
+    let exported = false;
+    let signature;
+    let docSummary;
+    const modifiers = ts.canHaveModifiers(node) ? ts.getModifiers(node) : undefined;
+    exported = hasModifierKind(modifiers, ts.SyntaxKind.ExportKeyword);
+    // Function declarations
+    if (ts.isFunctionDeclaration(node) && node.name) {
+        name = node.name.text;
+        kind = 'function';
+        signature = buildFunctionSignature(node);
+        docSummary = getJsDocSummary(node, sourceFile);
+    }
+    // Class declarations
+    else if (ts.isClassDeclaration(node) && node.name) {
+        name = node.name.text;
+        kind = 'class';
+        signature = `class ${name}`;
+        docSummary = getJsDocSummary(node, sourceFile);
+    }
+    // Interface declarations
+    else if (ts.isInterfaceDeclaration(node)) {
+        name = node.name.text;
+        kind = 'interface';
+        signature = `interface ${name}`;
+        docSummary = getJsDocSummary(node, sourceFile);
+    }
+    // Type alias declarations
+    else if (ts.isTypeAliasDeclaration(node)) {
+        name = node.name.text;
+        kind = 'type';
+        signature = `type ${name}`;
+        docSummary = getJsDocSummary(node, sourceFile);
+    }
+    // Enum declarations
+    else if (ts.isEnumDeclaration(node)) {
+        name = node.name.text;
+        kind = 'enum';
+        signature = `enum ${name}`;
+        docSummary = getJsDocSummary(node, sourceFile);
+    }
+    // Variable declarations
+    else if (ts.isVariableDeclaration(node) && ts.isIdentifier(node.name)) {
+        // Skip if this is a function (arrow function or function expression)
+        if (node.initializer &&
+            (ts.isArrowFunction(node.initializer) || ts.isFunctionExpression(node.initializer))) {
+            name = node.name.text;
+            kind = 'function';
+            signature = buildArrowFunctionSignature(node);
+        }
+        else {
+            name = node.name.text;
+            kind = 'variable';
+            signature = `${getVariableKind(node)} ${name}`;
+        }
+        // Check parent for export status
+        const parent = node.parent.parent;
+        if (ts.isVariableStatement(parent)) {
+            const parentMods = ts.canHaveModifiers(parent) ? ts.getModifiers(parent) : undefined;
+            exported = hasModifierKind(parentMods, ts.SyntaxKind.ExportKeyword);
+            docSummary = getJsDocSummary(parent, sourceFile);
+        }
+    }
+    // Method declarations (inside classes)
+    // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition -- node.name can be undefined for computed properties
+    else if (ts.isMethodDeclaration(node) && node.name && ts.isIdentifier(node.name)) {
+        name = node.name.text;
+        kind = 'method';
+        signature = buildMethodSignature(node);
+        docSummary = getJsDocSummary(node, sourceFile);
+        // Methods are exported if their containing class is exported
+    }
+    // Property declarations (inside classes)
+    // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition -- node.name can be undefined for computed properties
+    else if (ts.isPropertyDeclaration(node) && node.name && ts.isIdentifier(node.name)) {
+        name = node.name.text;
+        kind = 'property';
+        const typeAnnotation = node.type ? `: ${node.type.getText(sourceFile)}` : '';
+        signature = `${name}${typeAnnotation}`;
+        docSummary = getJsDocSummary(node, sourceFile);
+    }
+    // Check if this matches our search
+    if (!name || name !== symbolName) {
+        return null;
+    }
+    if (!kind) {
+        return null;
+    }
+    // Apply kind filter
+    if (kindFilter !== 'any' && kind !== kindFilter) {
+        // Handle type filter matching both 'type' and 'interface'
+        if (kindFilter === 'type' && kind === 'interface') {
+            // Allow interface to match type filter
+        }
+        else {
+            return null;
+        }
+    }
+    // Get position information
+    const { line, character } = sourceFile.getLineAndCharacterOfPosition(node.getStart(sourceFile));
+    return {
+        name,
+        path: filePath,
+        line: line + 1, // Convert to 1-based
+        column: character + 1, // Convert to 1-based
+        kind,
+        container,
+        exported,
+        signature,
+        docSummary,
+        confidence: 1.0, // Exact match
+    };
+}
+/**
+ * Get variable declaration kind (const, let, var)
+ */
+function getVariableKind(node) {
+    const parent = node.parent;
+    if (ts.isVariableDeclarationList(parent)) {
+        if (parent.flags & ts.NodeFlags.Const)
+            return 'const';
+        if (parent.flags & ts.NodeFlags.Let)
+            return 'let';
+    }
+    return 'var';
+}
+/**
+ * Build a function signature string
+ */
+function buildFunctionSignature(node) {
+    const name = node.name?.text ?? 'anonymous';
+    const params = node.parameters
+        .map((p) => {
+        const paramName = ts.isIdentifier(p.name) ? p.name.text : 'param';
+        const paramType = p.type ? p.type.getText() : '';
+        return paramType ? `${paramName}: ${paramType}` : paramName;
+    })
+        .join(', ');
+    const returnType = node.type ? `: ${node.type.getText()}` : '';
+    const asyncPrefix = hasModifierKind(ts.getModifiers(node), ts.SyntaxKind.AsyncKeyword)
+        ? 'async '
+        : '';
+    return `${asyncPrefix}function ${name}(${params})${returnType}`;
+}
+/**
+ * Build a method signature string
+ */
+function buildMethodSignature(node) {
+    const name = ts.isIdentifier(node.name) ? node.name.text : 'method';
+    const params = node.parameters
+        .map((p) => {
+        const paramName = ts.isIdentifier(p.name) ? p.name.text : 'param';
+        const paramType = p.type ? p.type.getText() : '';
+        return paramType ? `${paramName}: ${paramType}` : paramName;
+    })
+        .join(', ');
+    const returnType = node.type ? `: ${node.type.getText()}` : '';
+    const modifiers = ts.getModifiers(node);
+    const asyncPrefix = hasModifierKind(modifiers, ts.SyntaxKind.AsyncKeyword) ? 'async ' : '';
+    const staticPrefix = hasModifierKind(modifiers, ts.SyntaxKind.StaticKeyword) ? 'static ' : '';
+    return `${staticPrefix}${asyncPrefix}${name}(${params})${returnType}`;
+}
+/**
+ * Build an arrow function signature string from variable declaration
+ */
+function buildArrowFunctionSignature(node) {
+    const name = ts.isIdentifier(node.name) ? node.name.text : 'anonymous';
+    if (node.initializer &&
+        (ts.isArrowFunction(node.initializer) || ts.isFunctionExpression(node.initializer))) {
+        const func = node.initializer;
+        const params = func.parameters
+            .map((p) => {
+            const paramName = ts.isIdentifier(p.name) ? p.name.text : 'param';
+            const paramType = p.type ? p.type.getText() : '';
+            return paramType ? `${paramName}: ${paramType}` : paramName;
+        })
+            .join(', ');
+        const returnType = func.type ? `: ${func.type.getText()}` : '';
+        return `const ${name} = (${params})${returnType}`;
+    }
+    return `const ${name}`;
+}
+/**
+ * Extract JSDoc summary (first line) from a node
+ */
+function getJsDocSummary(node, sourceFile) {
+    // Get leading trivia (comments before the node)
+    const fullText = sourceFile.getFullText();
+    const nodeStart = node.getFullStart();
+    const nodeTextStart = node.getStart(sourceFile);
+    const trivia = fullText.substring(nodeStart, nodeTextStart);
+    // Look for JSDoc comment
+    const jsDocMatch = trivia.match(/\/\*\*\s*\n?\s*\*?\s*([^\n*]+)/);
+    if (jsDocMatch) {
+        return jsDocMatch[1].trim();
+    }
+    return undefined;
+}
+/**
+ * Factory function to create a customized findSymbol tool
+ */
+export function createFindSymbolTool(options) {
+    const { defaultLimit = 10, defaultIncludeNodeModules = false } = options ?? {};
+    return defineTool({
+        name: 'find_symbol',
+        description: TOOL_DESCRIPTION,
+        inputSchema: TOOL_INPUT_SCHEMA,
+        execute: async (input) => {
+            return executeFindSymbol({
+                ...input,
+                limit: input.limit ?? defaultLimit,
+                includeNodeModules: input.includeNodeModules ?? defaultIncludeNodeModules,
+            });
+        },
+    });
+}

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

@@ -0,0 +1,23 @@
+/**
+ * getCallGraph Tool
+ *
+ * Analyze function call relationships using TypeScript Compiler API.
+ * Returns a call graph showing what functions call what.
+ */
+import type { Tool } from '@compilr-dev/agents';
+import type { GetCallGraphInput, CallGraphDirection } from './types.js';
+/**
+ * getCallGraph tool - Analyze function call relationships
+ */
+export declare const getCallGraphTool: Tool<GetCallGraphInput>;
+/**
+ * Factory function to create a customized getCallGraph tool
+ */
+export declare function createGetCallGraphTool(options?: {
+    /** Default direction */
+    defaultDirection?: CallGraphDirection;
+    /** Default max depth */
+    defaultMaxDepth?: number;
+    /** Default includeExternal */
+    defaultIncludeExternal?: boolean;
+}): Tool<GetCallGraphInput>;