@compilr-dev/agents-coding-ts 0.1.0

package/dist/tools/find-references.js

@@ -0,0 +1,488 @@
+/**
+ * findReferences Tool
+ *
+ * Find all usages 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 all usages of a symbol across the codebase.
+Returns structured JSON with file paths, line numbers, and reference types.
+Use this to understand how a function, class, or variable is used throughout the project.`;
+// Tool input schema
+const TOOL_INPUT_SCHEMA = {
+    type: 'object',
+    properties: {
+        symbol: {
+            type: 'string',
+            description: 'Symbol name to find references for',
+        },
+        definitionFile: {
+            type: 'string',
+            description: 'File where the symbol is defined (improves accuracy)',
+        },
+        definitionLine: {
+            type: 'number',
+            description: 'Line where symbol is defined (improves accuracy)',
+        },
+        scope: {
+            type: 'string',
+            description: 'Scope the search to a specific file or directory',
+        },
+        limit: {
+            type: 'number',
+            description: 'Maximum results to return (default: 50)',
+            default: 50,
+        },
+        includeDefinition: {
+            type: 'boolean',
+            description: 'Include the definition itself (default: false)',
+            default: false,
+        },
+        groupByFile: {
+            type: 'boolean',
+            description: 'Group results by file (default: true)',
+            default: true,
+        },
+    },
+    required: ['symbol'],
+};
+/**
+ * findReferences tool - Find all usages of a symbol
+ */
+export const findReferencesTool = defineTool({
+    name: 'find_references',
+    description: TOOL_DESCRIPTION,
+    inputSchema: TOOL_INPUT_SCHEMA,
+    execute: executeFindReferences,
+});
+/**
+ * Execute the findReferences tool
+ */
+async function executeFindReferences(input) {
+    const { symbol, definitionFile, definitionLine, scope, limit = 50, includeDefinition = false, groupByFile = true, } = input;
+    // Validate input
+    if (!symbol || symbol.trim().length === 0) {
+        return createErrorResult('Symbol name is required');
+    }
+    const startTime = Date.now();
+    const allReferences = [];
+    let filesSearched = 0;
+    let definition;
+    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);
+        // First, try to find the definition if definitionFile is provided
+        if (definitionFile) {
+            try {
+                await fs.access(definitionFile);
+                const detection = detectLanguage(definitionFile);
+                if (detection.language && isLanguageSupported(detection.language)) {
+                    definition = await findDefinitionInFile(definitionFile, symbol, definitionLine);
+                }
+            }
+            catch {
+                // Definition file not found, continue without it
+            }
+        }
+        // Collect files to search
+        let filesToSearch = [];
+        if (stats.isFile()) {
+            const detection = detectLanguage(searchPath);
+            if (detection.language && isLanguageSupported(detection.language)) {
+                filesToSearch = [searchPath];
+            }
+        }
+        else if (stats.isDirectory()) {
+            filesToSearch = await collectFiles(searchPath);
+        }
+        else {
+            return createErrorResult(`Path is neither a file nor directory: ${searchPath}`);
+        }
+        filesSearched = filesToSearch.length;
+        // Search each file for references
+        for (const filePath of filesToSearch) {
+            if (allReferences.length >= limit)
+                break;
+            const fileRefs = await searchFileForReferences(filePath, symbol, definition, includeDefinition);
+            const remaining = limit - allReferences.length;
+            allReferences.push(...fileRefs.slice(0, remaining));
+        }
+        const endTime = Date.now();
+        const truncated = allReferences.length >= limit;
+        // Build result
+        const result = {
+            symbol,
+            definition,
+            totalCount: allReferences.length,
+            truncated,
+            stats: {
+                filesSearched,
+                timeMs: endTime - startTime,
+            },
+        };
+        if (groupByFile) {
+            result.byFile = groupReferencesByFile(allReferences);
+        }
+        else {
+            result.references = allReferences;
+        }
+        return createSuccessResult(result);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return createErrorResult(`Failed to search for references: ${message}`);
+    }
+}
+/**
+ * Collect all supported files in a directory recursively
+ */
+async function collectFiles(dir) {
+    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 and common non-source directories
+                if (entry.name === 'node_modules' ||
+                    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;
+}
+/**
+ * Find the definition of a symbol in a file
+ */
+async function findDefinitionInFile(filePath, symbolName, targetLine) {
+    try {
+        const sourceCode = await fs.readFile(filePath, 'utf-8');
+        const scriptKind = getScriptKind(filePath);
+        const sourceFile = ts.createSourceFile(filePath, sourceCode, ts.ScriptTarget.Latest, true, scriptKind);
+        let foundDef;
+        function visit(node) {
+            if (foundDef)
+                return;
+            const def = tryExtractDefinition(node, sourceFile, symbolName, filePath);
+            if (def) {
+                // If targetLine is specified, only match if on that line
+                if (targetLine === undefined || def.line === targetLine) {
+                    foundDef = def;
+                    return;
+                }
+            }
+            ts.forEachChild(node, visit);
+        }
+        visit(sourceFile);
+        return foundDef;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Try to extract a definition from a node
+ */
+function tryExtractDefinition(node, sourceFile, symbolName, filePath) {
+    let name;
+    let kind;
+    const modifiers = ts.canHaveModifiers(node) ? ts.getModifiers(node) : undefined;
+    const exported = hasModifierKind(modifiers, ts.SyntaxKind.ExportKeyword);
+    if (ts.isFunctionDeclaration(node) && node.name?.text === symbolName) {
+        name = node.name.text;
+        kind = 'function';
+    }
+    else if (ts.isClassDeclaration(node) && node.name?.text === symbolName) {
+        name = node.name.text;
+        kind = 'class';
+    }
+    else if (ts.isInterfaceDeclaration(node) && node.name.text === symbolName) {
+        name = node.name.text;
+        kind = 'interface';
+    }
+    else if (ts.isTypeAliasDeclaration(node) && node.name.text === symbolName) {
+        name = node.name.text;
+        kind = 'type';
+    }
+    else if (ts.isEnumDeclaration(node) && node.name.text === symbolName) {
+        name = node.name.text;
+        kind = 'enum';
+    }
+    else if (ts.isVariableDeclaration(node) &&
+        ts.isIdentifier(node.name) &&
+        node.name.text === symbolName) {
+        name = node.name.text;
+        kind = 'variable';
+    }
+    if (name && kind) {
+        const { line, character } = sourceFile.getLineAndCharacterOfPosition(node.getStart(sourceFile));
+        return {
+            name,
+            path: filePath,
+            line: line + 1,
+            column: character + 1,
+            kind,
+            exported,
+            confidence: 1.0,
+        };
+    }
+    return undefined;
+}
+/**
+ * Search a single file for references to a symbol
+ */
+async function searchFileForReferences(filePath, symbolName, definition, includeDefinition) {
+    const references = [];
+    try {
+        const sourceCode = await fs.readFile(filePath, 'utf-8');
+        const lines = sourceCode.split('\n');
+        const scriptKind = getScriptKind(filePath);
+        const sourceFile = ts.createSourceFile(filePath, sourceCode, ts.ScriptTarget.Latest, true, scriptKind);
+        // Track current containing function for context
+        let containingFunction;
+        function visit(node) {
+            // Track containing function
+            if (ts.isFunctionDeclaration(node) && node.name) {
+                containingFunction = node.name.text;
+            }
+            else if (ts.isMethodDeclaration(node) && ts.isIdentifier(node.name)) {
+                containingFunction = node.name.text;
+            }
+            else if (ts.isArrowFunction(node)) {
+                const parent = node.parent;
+                if (ts.isVariableDeclaration(parent) && ts.isIdentifier(parent.name)) {
+                    containingFunction = parent.name.text;
+                }
+            }
+            // Check for references
+            const ref = tryExtractReference(node, sourceFile, symbolName, filePath, lines, containingFunction);
+            if (ref) {
+                // Skip if this is the definition and we don't want to include it
+                if (!includeDefinition &&
+                    definition &&
+                    ref.path === definition.path &&
+                    ref.line === definition.line) {
+                    // Skip definition
+                }
+                else {
+                    references.push(ref);
+                }
+            }
+            ts.forEachChild(node, visit);
+            // Reset containing function when leaving
+            if (ts.isFunctionDeclaration(node) ||
+                ts.isMethodDeclaration(node) ||
+                ts.isArrowFunction(node)) {
+                containingFunction = undefined;
+            }
+        }
+        visit(sourceFile);
+    }
+    catch {
+        // Silently skip files that can't be parsed
+    }
+    return references;
+}
+/**
+ * Try to extract a reference from a node
+ */
+function tryExtractReference(node, sourceFile, symbolName, filePath, lines, containingFunction) {
+    // Check if this is an identifier matching our symbol
+    if (!ts.isIdentifier(node) || node.text !== symbolName) {
+        return undefined;
+    }
+    // Determine reference type based on context
+    const refType = determineReferenceType(node);
+    if (!refType) {
+        return undefined;
+    }
+    const { line, character } = sourceFile.getLineAndCharacterOfPosition(node.getStart(sourceFile));
+    const lineIndex = line;
+    const context = lineIndex < lines.length ? lines[lineIndex].trim() : '';
+    return {
+        path: filePath,
+        line: line + 1,
+        column: character + 1,
+        context,
+        type: refType,
+        containingFunction,
+    };
+}
+/**
+ * Determine the type of reference based on AST context
+ */
+function determineReferenceType(node) {
+    const parent = node.parent;
+    // Import statement
+    if (ts.isImportSpecifier(parent) || ts.isImportClause(parent) || ts.isNamespaceImport(parent)) {
+        return 'import';
+    }
+    // Export statement
+    if (ts.isExportSpecifier(parent) || ts.isExportAssignment(parent)) {
+        return 'export';
+    }
+    // Type reference (in type annotations)
+    if (ts.isTypeReferenceNode(parent)) {
+        return 'type';
+    }
+    // Extends clause
+    if (ts.isExpressionWithTypeArguments(parent)) {
+        const grandparent = parent.parent;
+        if (ts.isHeritageClause(grandparent)) {
+            if (grandparent.token === ts.SyntaxKind.ExtendsKeyword) {
+                return 'extend';
+            }
+            // Use else for implements to avoid the "always true" comparison error
+            return 'implement';
+        }
+    }
+    // Call expression
+    if (ts.isCallExpression(parent) && parent.expression === node) {
+        return 'call';
+    }
+    // New expression
+    if (ts.isNewExpression(parent) && parent.expression === node) {
+        return 'call';
+    }
+    // Property access (reading)
+    if (ts.isPropertyAccessExpression(parent) && parent.name === node) {
+        // Check if this is a write (assignment target)
+        const grandparent = parent.parent;
+        if (ts.isBinaryExpression(grandparent) &&
+            grandparent.operatorToken.kind === ts.SyntaxKind.EqualsToken &&
+            grandparent.left === parent) {
+            return 'write';
+        }
+        return 'read';
+    }
+    // Variable declaration (definition, but also a "write")
+    if (ts.isVariableDeclaration(parent) && parent.name === node) {
+        return 'write';
+    }
+    // Assignment expression
+    if (ts.isBinaryExpression(parent) &&
+        parent.operatorToken.kind === ts.SyntaxKind.EqualsToken &&
+        parent.left === node) {
+        return 'write';
+    }
+    // Parameter declaration
+    if (ts.isParameter(parent)) {
+        return 'write';
+    }
+    // Function/class/interface declaration (this is a definition)
+    if (ts.isFunctionDeclaration(parent) ||
+        ts.isClassDeclaration(parent) ||
+        ts.isInterfaceDeclaration(parent) ||
+        ts.isTypeAliasDeclaration(parent) ||
+        ts.isEnumDeclaration(parent) ||
+        ts.isMethodDeclaration(parent) ||
+        ts.isPropertyDeclaration(parent)) {
+        // This is a definition, we'll include it based on includeDefinition flag
+        return 'write';
+    }
+    // Default to read for other usages
+    return 'read';
+}
+/**
+ * Group references by file
+ */
+function groupReferencesByFile(references) {
+    const byFile = new Map();
+    for (const ref of references) {
+        const existing = byFile.get(ref.path);
+        if (existing) {
+            existing.push(ref);
+        }
+        else {
+            byFile.set(ref.path, [ref]);
+        }
+    }
+    return Array.from(byFile.entries()).map(([path, refs]) => ({
+        path,
+        references: refs,
+    }));
+}
+/**
+ * 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 findReferences tool
+ */
+export function createFindReferencesTool(options) {
+    const { defaultLimit = 50, defaultGroupByFile = true, defaultIncludeDefinition = false, } = options ?? {};
+    return defineTool({
+        name: 'find_references',
+        description: TOOL_DESCRIPTION,
+        inputSchema: TOOL_INPUT_SCHEMA,
+        execute: async (input) => {
+            return executeFindReferences({
+                ...input,
+                limit: input.limit ?? defaultLimit,
+                groupByFile: input.groupByFile ?? defaultGroupByFile,
+                includeDefinition: input.includeDefinition ?? defaultIncludeDefinition,
+            });
+        },
+    });
+}

package/dist/tools/find-symbol.d.ts

@@ -0,0 +1,21 @@
+/**
+ * findSymbol Tool
+ *
+ * Find the definition location of a symbol across the codebase.
+ * Uses TypeScript Compiler API for accurate AST analysis.
+ */
+import type { Tool } from '@compilr-dev/agents';
+import type { FindSymbolInput } from './types.js';
+/**
+ * findSymbol tool - Find symbol definitions
+ */
+export declare const findSymbolTool: Tool<FindSymbolInput>;
+/**
+ * Factory function to create a customized findSymbol tool
+ */
+export declare function createFindSymbolTool(options?: {
+    /** Default limit */
+    defaultLimit?: number;
+    /** Default includeNodeModules */
+    defaultIncludeNodeModules?: boolean;
+}): Tool<FindSymbolInput>;