@compilr-dev/agents-coding 0.0.1

package/dist/tools/search/references.js

@@ -0,0 +1,179 @@
+/**
+ * Find References Tool
+ * Find usages of a symbol using grep with word boundary matching
+ */
+import { defineTool, createSuccessResult, createErrorResult } from '@compilr-dev/agents';
+import { escapeRegex, isDirectory, runGrep, getGlobPattern } from './utils.js';
+/**
+ * Definition patterns to exclude when excludeDefinitions is true
+ */
+const DEFINITION_PATTERNS = [
+    // TypeScript/JavaScript
+    /^\s*(export\s+)?(async\s+)?function\s+/,
+    /^\s*(export\s+)?(abstract\s+)?class\s+/,
+    /^\s*(export\s+)?interface\s+/,
+    /^\s*(export\s+)?type\s+\w+\s*[=<]/,
+    /^\s*(export\s+)?(const|let|var)\s+\w+\s*[=:]/,
+    /^\s*(export\s+)?(const\s+)?enum\s+/,
+    // Python
+    /^\s*(async\s+)?def\s+/,
+    /^\s*class\s+\w+\s*[:(]/,
+    // Rust
+    /^\s*(pub\s+)?(async\s+)?fn\s+/,
+    /^\s*(pub\s+)?struct\s+/,
+    /^\s*(pub\s+)?enum\s+/,
+    /^\s*(pub\s+)?trait\s+/,
+    /^\s*(pub\s+)?type\s+/,
+    // Go
+    /^\s*func\s+(\([^)]+\)\s+)?\w+\s*\(/,
+    /^\s*type\s+\w+\s+(struct|interface)/,
+    // Java/Kotlin
+    /^\s*(public|private|protected)?\s*(abstract|final)?\s*class\s+/,
+    /^\s*(public|private)?\s*interface\s+/,
+];
+/**
+ * Check if a line is a definition
+ */
+function isDefinitionLine(line, symbol) {
+    // Must contain the symbol as a word
+    const symbolRegex = new RegExp(`\\b${escapeRegex(symbol)}\\b`);
+    if (!symbolRegex.test(line))
+        return false;
+    // Check against definition patterns
+    for (const pattern of DEFINITION_PATTERNS) {
+        if (pattern.test(line)) {
+            return true;
+        }
+    }
+    return false;
+}
+/**
+ * Execute find references
+ */
+async function executeFindReferences(input) {
+    const targetPath = input.path ?? process.cwd();
+    const limit = input.limit ?? 50;
+    const excludeDefinitions = input.excludeDefinitions ?? false;
+    if (!input.symbol || input.symbol.trim().length === 0) {
+        return createErrorResult('Symbol is required');
+    }
+    if (!(await isDirectory(targetPath))) {
+        return createErrorResult(`Directory not found: ${targetPath}`);
+    }
+    try {
+        const glob = getGlobPattern(input.fileType);
+        const symbol = input.symbol.trim();
+        // Use word boundary matching
+        const pattern = `\\b${escapeRegex(symbol)}\\b`;
+        // Get more results than needed if filtering definitions
+        const searchLimit = excludeDefinitions ? limit * 2 : limit;
+        const args = ['-n', '--column', '-w', '--glob', glob, '-e', pattern, '.'];
+        const rawResults = await runGrep(args, targetPath, searchLimit, true);
+        // Filter results
+        let references = rawResults.map((r) => ({
+            file: r.file,
+            line: r.line,
+            column: r.column ?? 1,
+            context: r.context.trim(),
+        }));
+        // Exclude definitions if requested
+        if (excludeDefinitions) {
+            references = references.filter((ref) => !isDefinitionLine(ref.context, symbol));
+        }
+        // Apply limit
+        const limitedReferences = references.slice(0, limit);
+        const result = {
+            references: limitedReferences,
+            totalFound: references.length,
+            symbol,
+        };
+        return createSuccessResult(result);
+    }
+    catch (error) {
+        return createErrorResult(error instanceof Error ? error.message : String(error));
+    }
+}
+/**
+ * Find References Tool
+ */
+export const findReferencesTool = defineTool({
+    name: 'find_references',
+    description: 'Find all usages/references of a symbol in the codebase. ' +
+        'Uses word boundary matching for accurate results. ' +
+        'Can exclude definition lines to show only usages.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            symbol: {
+                type: 'string',
+                description: 'Symbol name to find references for',
+            },
+            path: {
+                type: 'string',
+                description: 'Working directory (default: current directory)',
+            },
+            fileType: {
+                type: 'string',
+                description: 'File type filter (e.g., ts, py, rs, go)',
+            },
+            excludeDefinitions: {
+                type: 'boolean',
+                description: 'Exclude definition lines, show only usages (default: false)',
+            },
+            limit: {
+                type: 'number',
+                description: 'Max results (default: 50)',
+            },
+        },
+        required: ['symbol'],
+    },
+    execute: executeFindReferences,
+});
+/**
+ * Factory function to create find references tool with custom options
+ */
+export function createFindReferencesTool(options) {
+    return defineTool({
+        name: 'find_references',
+        description: 'Find all usages/references of a symbol in the codebase. ' +
+            'Uses word boundary matching for accurate results.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                symbol: {
+                    type: 'string',
+                    description: 'Symbol name to find',
+                },
+                path: {
+                    type: 'string',
+                    description: 'Working directory',
+                },
+                fileType: {
+                    type: 'string',
+                    description: 'File type filter',
+                },
+                excludeDefinitions: {
+                    type: 'boolean',
+                    description: 'Exclude definition lines',
+                },
+                limit: {
+                    type: 'number',
+                    description: 'Max results',
+                },
+            },
+            required: ['symbol'],
+        },
+        execute: async (input) => {
+            let targetPath = input.path ?? '.';
+            if (options?.baseDir && !targetPath.startsWith('/')) {
+                const nodePath = await import('node:path');
+                targetPath = nodePath.join(options.baseDir, targetPath);
+            }
+            return executeFindReferences({
+                ...input,
+                path: targetPath,
+                limit: input.limit ?? options?.defaultLimit,
+            });
+        },
+    });
+}

package/dist/tools/search/todos.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Find TODOs Tool
+ * Find TODO, FIXME, HACK, XXX, NOTE, BUG, WARN comments in code
+ */
+import type { Tool } from '@compilr-dev/agents';
+import type { FindTodosInput } from './types.js';
+/**
+ * Find TODOs Tool
+ */
+export declare const findTodosTool: Tool<FindTodosInput>;
+/**
+ * Factory function to create find todos tool with custom options
+ */
+export declare function createFindTodosTool(options?: {
+    /** Base directory for relative paths */
+    baseDir?: string;
+    /** Default limit */
+    defaultLimit?: number;
+}): Tool<FindTodosInput>;

package/dist/tools/search/todos.js

@@ -0,0 +1,269 @@
+/**
+ * Find TODOs Tool
+ * Find TODO, FIXME, HACK, XXX, NOTE, BUG, WARN comments in code
+ */
+import { defineTool, createSuccessResult, createErrorResult } from '@compilr-dev/agents';
+import { spawn } from 'node:child_process';
+import { isDirectory, getGlobPattern, SEARCH_TIMEOUT } from './utils.js';
+/**
+ * All supported TODO types
+ */
+const ALL_TODO_TYPES = ['TODO', 'FIXME', 'HACK', 'XXX', 'NOTE', 'BUG', 'WARN'];
+/**
+ * Build regex pattern for TODO types
+ */
+function buildTodoPattern(types) {
+    // Match: // TODO: text, # TODO text, /* TODO */, etc.
+    // Pattern: (TODO|FIXME|...)[:\s](.*)
+    const typePattern = types.join('|');
+    return `(${typePattern})[:\\s]`;
+}
+/**
+ * Parse TODO type from matched line
+ */
+function parseTodoType(line, types) {
+    const upperLine = line.toUpperCase();
+    for (const type of types) {
+        if (upperLine.includes(type)) {
+            return type;
+        }
+    }
+    return null;
+}
+/**
+ * Extract TODO text from line
+ */
+function extractTodoText(line, todoType) {
+    // Find the TODO keyword and extract everything after it
+    const upperLine = line.toUpperCase();
+    const idx = upperLine.indexOf(todoType);
+    if (idx === -1)
+        return line.trim();
+    let text = line.slice(idx + todoType.length);
+    // Remove common prefix characters: :, -, (, [
+    text = text.replace(/^[\s:*\-([]+/, '');
+    // Remove trailing comment closers
+    text = text.replace(/\s*\*\/\s*$/, '');
+    text = text.replace(/\s*-->\s*$/, '');
+    return text.trim();
+}
+/**
+ * Run grep to find TODOs (case-insensitive search)
+ */
+function runTodoGrep(pattern, cwd, glob, limit) {
+    return new Promise((resolve) => {
+        const results = [];
+        const args = [
+            '-n', // line numbers
+            '-i', // case insensitive for TODOs
+            '--glob',
+            glob,
+            '-e',
+            pattern,
+            '.',
+        ];
+        const proc = spawn('rg', args, { cwd });
+        let stdout = '';
+        let timedOut = false;
+        const timeout = setTimeout(() => {
+            timedOut = true;
+            proc.kill();
+        }, SEARCH_TIMEOUT);
+        proc.stdout.on('data', (data) => {
+            stdout += data.toString();
+        });
+        proc.on('close', () => {
+            clearTimeout(timeout);
+            if (timedOut) {
+                resolve(results);
+                return;
+            }
+            // Parse ripgrep output: file:line:content
+            const lines = stdout.split('\n').filter(Boolean);
+            for (const line of lines) {
+                if (results.length >= limit)
+                    break;
+                const match = line.match(/^([^:]+):(\d+):(.*)$/);
+                if (match) {
+                    results.push({
+                        file: match[1],
+                        line: parseInt(match[2], 10),
+                        context: match[3],
+                    });
+                }
+            }
+            resolve(results);
+        });
+        proc.on('error', () => {
+            clearTimeout(timeout);
+            resolve(results);
+        });
+    });
+}
+/**
+ * Get git blame author for a line (optional)
+ */
+async function getGitBlameAuthor(file, line, cwd) {
+    return new Promise((resolve) => {
+        const args = ['-L', `${String(line)},${String(line)}`, '--porcelain', file];
+        const proc = spawn('git', ['blame', ...args], {
+            cwd,
+            shell: true,
+        });
+        let stdout = '';
+        const timeout = setTimeout(() => {
+            proc.kill();
+            resolve(undefined);
+        }, 5000);
+        proc.stdout.on('data', (data) => {
+            stdout += data.toString();
+        });
+        proc.on('close', () => {
+            clearTimeout(timeout);
+            // Parse porcelain format for author
+            const authorMatch = stdout.match(/^author (.+)$/m);
+            resolve(authorMatch ? authorMatch[1] : undefined);
+        });
+        proc.on('error', () => {
+            clearTimeout(timeout);
+            resolve(undefined);
+        });
+    });
+}
+/**
+ * Execute find todos
+ */
+async function executeFindTodos(input) {
+    const targetPath = input.path ?? process.cwd();
+    const limit = input.limit ?? 100;
+    const types = input.types ?? ALL_TODO_TYPES;
+    const includeAuthor = input.includeAuthor ?? false;
+    if (!(await isDirectory(targetPath))) {
+        return createErrorResult(`Directory not found: ${targetPath}`);
+    }
+    try {
+        const glob = getGlobPattern(input.fileType);
+        const pattern = buildTodoPattern(types);
+        const rawResults = await runTodoGrep(pattern, targetPath, glob, limit);
+        // Process results
+        const todos = [];
+        const summary = {};
+        for (const raw of rawResults) {
+            const todoType = parseTodoType(raw.context, types);
+            if (!todoType)
+                continue;
+            const text = extractTodoText(raw.context, todoType);
+            const todo = {
+                type: todoType,
+                file: raw.file,
+                line: raw.line,
+                text,
+            };
+            // Get author if requested (slow, so only for small result sets)
+            if (includeAuthor && todos.length < 20) {
+                todo.author = await getGitBlameAuthor(raw.file, raw.line, targetPath);
+            }
+            todos.push(todo);
+            // Update summary
+            summary[todoType] = (summary[todoType] ?? 0) + 1;
+        }
+        const result = {
+            todos,
+            summary,
+            totalFound: todos.length,
+        };
+        return createSuccessResult(result);
+    }
+    catch (error) {
+        return createErrorResult(error instanceof Error ? error.message : String(error));
+    }
+}
+/**
+ * Find TODOs Tool
+ */
+export const findTodosTool = defineTool({
+    name: 'find_todos',
+    description: 'Find TODO, FIXME, HACK, XXX, NOTE, BUG, WARN comments in code. ' +
+        'Returns a summary count by type and individual locations. ' +
+        'Can optionally include git blame author info.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            path: {
+                type: 'string',
+                description: 'Working directory (default: current directory)',
+            },
+            types: {
+                type: 'array',
+                items: {
+                    type: 'string',
+                    enum: ['TODO', 'FIXME', 'HACK', 'XXX', 'NOTE', 'BUG', 'WARN'],
+                },
+                description: 'Comment types to find (default: all)',
+            },
+            fileType: {
+                type: 'string',
+                description: 'File type filter (e.g., ts, py, rs, go)',
+            },
+            includeAuthor: {
+                type: 'boolean',
+                description: 'Include git blame author info (slower)',
+            },
+            limit: {
+                type: 'number',
+                description: 'Max results (default: 100)',
+            },
+        },
+        required: [],
+    },
+    execute: executeFindTodos,
+});
+/**
+ * Factory function to create find todos tool with custom options
+ */
+export function createFindTodosTool(options) {
+    return defineTool({
+        name: 'find_todos',
+        description: 'Find TODO, FIXME, HACK, XXX, NOTE, BUG, WARN comments in code. ' +
+            'Returns a summary count by type and individual locations.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                path: {
+                    type: 'string',
+                    description: 'Working directory',
+                },
+                types: {
+                    type: 'array',
+                    items: { type: 'string' },
+                    description: 'Comment types to find',
+                },
+                fileType: {
+                    type: 'string',
+                    description: 'File type filter',
+                },
+                includeAuthor: {
+                    type: 'boolean',
+                    description: 'Include git blame author',
+                },
+                limit: {
+                    type: 'number',
+                    description: 'Max results',
+                },
+            },
+            required: [],
+        },
+        execute: async (input) => {
+            let targetPath = input.path ?? '.';
+            if (options?.baseDir && !targetPath.startsWith('/')) {
+                const nodePath = await import('node:path');
+                targetPath = nodePath.join(options.baseDir, targetPath);
+            }
+            return executeFindTodos({
+                ...input,
+                path: targetPath,
+                limit: input.limit ?? options?.defaultLimit,
+            });
+        },
+    });
+}

package/dist/tools/search/types.d.ts

@@ -0,0 +1,132 @@
+/**
+ * Types for Code Search Tools
+ */
+/**
+ * Definition type detected from code pattern
+ */
+export type DefinitionType = 'function' | 'class' | 'variable' | 'const' | 'let' | 'type' | 'interface' | 'enum' | 'method' | 'property' | 'unknown';
+/**
+ * A found definition location
+ */
+export interface Definition {
+    /** File path */
+    file: string;
+    /** Line number (1-indexed) */
+    line: number;
+    /** Column number (1-indexed) */
+    column: number;
+    /** Line content */
+    context: string;
+    /** Type of definition */
+    type: DefinitionType;
+    /** Export status */
+    isExported?: boolean;
+}
+/**
+ * Input for findDefinitionTool
+ */
+export interface FindDefinitionInput {
+    /** Symbol to find */
+    symbol: string;
+    /** Working directory (default: cwd) */
+    path?: string;
+    /** File type filter (e.g., 'ts', 'py', 'rs') */
+    fileType?: string;
+    /** Max results (default: 20) */
+    limit?: number;
+}
+/**
+ * Result from findDefinitionTool
+ */
+export interface FindDefinitionResult {
+    /** Found definitions */
+    definitions: Definition[];
+    /** Total matches found (may be more than returned) */
+    totalFound: number;
+    /** Symbol searched for */
+    symbol: string;
+}
+/**
+ * A found reference location
+ */
+export interface Reference {
+    /** File path */
+    file: string;
+    /** Line number (1-indexed) */
+    line: number;
+    /** Column number (1-indexed) */
+    column: number;
+    /** Line content */
+    context: string;
+}
+/**
+ * Input for findReferencesTool
+ */
+export interface FindReferencesInput {
+    /** Symbol to find */
+    symbol: string;
+    /** Working directory (default: cwd) */
+    path?: string;
+    /** File type filter (e.g., 'ts', 'py', 'rs') */
+    fileType?: string;
+    /** Exclude definition lines (default: false) */
+    excludeDefinitions?: boolean;
+    /** Max results (default: 50) */
+    limit?: number;
+}
+/**
+ * Result from findReferencesTool
+ */
+export interface FindReferencesResult {
+    /** Found references */
+    references: Reference[];
+    /** Total matches found (may be more than returned) */
+    totalFound: number;
+    /** Symbol searched for */
+    symbol: string;
+}
+/**
+ * TODO comment type
+ */
+export type TodoType = 'TODO' | 'FIXME' | 'HACK' | 'XXX' | 'NOTE' | 'BUG' | 'WARN';
+/**
+ * A found TODO comment
+ */
+export interface TodoComment {
+    /** TODO type */
+    type: TodoType;
+    /** File path */
+    file: string;
+    /** Line number (1-indexed) */
+    line: number;
+    /** TODO text content */
+    text: string;
+    /** Author (from git blame, if requested) */
+    author?: string;
+}
+/**
+ * Input for findTodosTool
+ */
+export interface FindTodosInput {
+    /** Working directory (default: cwd) */
+    path?: string;
+    /** Comment types to find (default: all) */
+    types?: TodoType[];
+    /** File type filter (e.g., 'ts', 'py', 'rs') */
+    fileType?: string;
+    /** Include author info via git blame (slower) */
+    includeAuthor?: boolean;
+    /** Max results (default: 100) */
+    limit?: number;
+}
+/**
+ * Result from findTodosTool
+ */
+export interface FindTodosResult {
+    /** Found TODO comments */
+    todos: TodoComment[];
+    /** Summary count by type */
+    summary: Partial<Record<TodoType, number>>;
+    /** Total found */
+    totalFound: number;
+}

package/dist/tools/search/types.js

@@ -0,0 +1,4 @@
+/**
+ * Types for Code Search Tools
+ */
+export {};

package/dist/tools/search/utils.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Shared utilities for Code Search tools
+ */
+/**
+ * File extensions by language type (canonical source)
+ */
+export declare const FILE_TYPE_EXTENSIONS: Record<string, string[]>;
+/**
+ * All source file extensions (for default glob patterns)
+ */
+export declare const ALL_SOURCE_EXTENSIONS: string[];
+/**
+ * Default timeout for search operations (30 seconds)
+ */
+export declare const SEARCH_TIMEOUT = 30000;
+/**
+ * Escape special regex characters
+ */
+export declare function escapeRegex(str: string): string;
+/**
+ * Get glob pattern for file type filtering
+ */
+export declare function getGlobPattern(fileType?: string, extensions?: string[]): string;
+/**
+ * Check if path is a directory
+ */
+export declare function isDirectory(path: string): Promise<boolean>;
+/**
+ * Ripgrep result with file, line, column, and context
+ */
+export interface GrepResult {
+    file: string;
+    line: number;
+    column?: number;
+    context: string;
+}
+/**
+ * Run ripgrep and parse results
+ *
+ * @param args - ripgrep arguments (without the command itself)
+ * @param cwd - working directory
+ * @param limit - maximum results to return
+ * @param includeColumn - whether to parse column from output
+ */
+export declare function runGrep(args: string[], cwd: string, limit: number, includeColumn?: boolean): Promise<GrepResult[]>;