feat(ipuaro): add search tools (v0.7.0)

packages/ipuaro/src/infrastructure/tools/index.ts

@@ -15,3 +15,15 @@ export {
 export { EditLinesTool, type EditLinesResult } from "./edit/EditLinesTool.js"
 export { CreateFileTool, type CreateFileResult } from "./edit/CreateFileTool.js"
 export { DeleteFileTool, type DeleteFileResult } from "./edit/DeleteFileTool.js"
+
+// Search tools
+export {
+    FindReferencesTool,
+    type FindReferencesResult,
+    type SymbolReference,
+} from "./search/FindReferencesTool.js"
+export {
+    FindDefinitionTool,
+    type FindDefinitionResult,
+    type DefinitionLocation,
+} from "./search/FindDefinitionTool.js"

packages/ipuaro/src/infrastructure/tools/search/FindDefinitionTool.ts

@@ -0,0 +1,221 @@
+import { promises as fs } from "node:fs"
+import * as path from "node:path"
+import type { ITool, ToolContext, ToolParameterSchema } from "../../../domain/services/ITool.js"
+import type { SymbolLocation } from "../../../domain/services/IStorage.js"
+import {
+    createErrorResult,
+    createSuccessResult,
+    type ToolResult,
+} from "../../../domain/value-objects/ToolResult.js"
+
+/**
+ * A single definition location with context.
+ */
+export interface DefinitionLocation {
+    path: string
+    line: number
+    type: SymbolLocation["type"]
+    context: string
+}
+
+/**
+ * Result data from find_definition tool.
+ */
+export interface FindDefinitionResult {
+    symbol: string
+    found: boolean
+    definitions: DefinitionLocation[]
+    suggestions?: string[]
+}
+
+/**
+ * Tool for finding where a symbol is defined.
+ * Uses the SymbolIndex to locate definitions.
+ */
+export class FindDefinitionTool implements ITool {
+    readonly name = "find_definition"
+    readonly description =
+        "Find where a symbol is defined. " + "Returns file path, line number, and symbol type."
+    readonly parameters: ToolParameterSchema[] = [
+        {
+            name: "symbol",
+            type: "string",
+            description: "Symbol name to find definition for",
+            required: true,
+        },
+    ]
+    readonly requiresConfirmation = false
+    readonly category = "search" as const
+
+    private readonly contextLines = 2
+
+    validateParams(params: Record<string, unknown>): string | null {
+        if (typeof params.symbol !== "string" || params.symbol.trim() === "") {
+            return "Parameter 'symbol' is required and must be a non-empty string"
+        }
+
+        return null
+    }
+
+    async execute(params: Record<string, unknown>, ctx: ToolContext): Promise<ToolResult> {
+        const startTime = Date.now()
+        const callId = `${this.name}-${String(startTime)}`
+
+        const symbol = (params.symbol as string).trim()
+
+        try {
+            const symbolIndex = await ctx.storage.getSymbolIndex()
+            const locations = symbolIndex.get(symbol)
+
+            if (!locations || locations.length === 0) {
+                const suggestions = this.findSimilarSymbols(symbol, symbolIndex)
+                return createSuccessResult(
+                    callId,
+                    {
+                        symbol,
+                        found: false,
+                        definitions: [],
+                        suggestions: suggestions.length > 0 ? suggestions : undefined,
+                    } satisfies FindDefinitionResult,
+                    Date.now() - startTime,
+                )
+            }
+
+            const definitions: DefinitionLocation[] = []
+            for (const loc of locations) {
+                const context = await this.getContext(loc, ctx)
+                definitions.push({
+                    path: loc.path,
+                    line: loc.line,
+                    type: loc.type,
+                    context,
+                })
+            }
+
+            definitions.sort((a, b) => {
+                const pathCompare = a.path.localeCompare(b.path)
+                if (pathCompare !== 0) {
+                    return pathCompare
+                }
+                return a.line - b.line
+            })
+
+            const result: FindDefinitionResult = {
+                symbol,
+                found: true,
+                definitions,
+            }
+
+            return createSuccessResult(callId, result, Date.now() - startTime)
+        } catch (error) {
+            const message = error instanceof Error ? error.message : String(error)
+            return createErrorResult(callId, message, Date.now() - startTime)
+        }
+    }
+
+    /**
+     * Get context lines around the definition.
+     */
+    private async getContext(loc: SymbolLocation, ctx: ToolContext): Promise<string> {
+        try {
+            const lines = await this.getFileLines(loc.path, ctx)
+            if (lines.length === 0) {
+                return ""
+            }
+
+            const lineIndex = loc.line - 1
+            const startIndex = Math.max(0, lineIndex - this.contextLines)
+            const endIndex = Math.min(lines.length - 1, lineIndex + this.contextLines)
+
+            const contextLines: string[] = []
+            for (let i = startIndex; i <= endIndex; i++) {
+                const lineNum = i + 1
+                const prefix = i === lineIndex ? ">" : " "
+                contextLines.push(`${prefix}${String(lineNum).padStart(4)}│${lines[i]}`)
+            }
+
+            return contextLines.join("\n")
+        } catch {
+            return ""
+        }
+    }
+
+    /**
+     * Get file lines from storage or filesystem.
+     */
+    private async getFileLines(relativePath: string, ctx: ToolContext): Promise<string[]> {
+        const fileData = await ctx.storage.getFile(relativePath)
+        if (fileData) {
+            return fileData.lines
+        }
+
+        const absolutePath = path.resolve(ctx.projectRoot, relativePath)
+        try {
+            const content = await fs.readFile(absolutePath, "utf-8")
+            return content.split("\n")
+        } catch {
+            return []
+        }
+    }
+
+    /**
+     * Find similar symbol names for suggestions.
+     */
+    private findSimilarSymbols(symbol: string, symbolIndex: Map<string, unknown>): string[] {
+        const suggestions: string[] = []
+        const lowerSymbol = symbol.toLowerCase()
+        const maxSuggestions = 5
+
+        for (const name of symbolIndex.keys()) {
+            if (suggestions.length >= maxSuggestions) {
+                break
+            }
+
+            const lowerName = name.toLowerCase()
+            if (lowerName.includes(lowerSymbol) || lowerSymbol.includes(lowerName)) {
+                suggestions.push(name)
+            } else if (this.levenshteinDistance(lowerSymbol, lowerName) <= 2) {
+                suggestions.push(name)
+            }
+        }
+
+        return suggestions.sort()
+    }
+
+    /**
+     * Calculate Levenshtein distance between two strings.
+     */
+    private levenshteinDistance(a: string, b: string): number {
+        if (a.length === 0) {
+            return b.length
+        }
+        if (b.length === 0) {
+            return a.length
+        }
+
+        const matrix: number[][] = []
+
+        for (let i = 0; i <= b.length; i++) {
+            matrix[i] = [i]
+        }
+        for (let j = 0; j <= a.length; j++) {
+            matrix[0][j] = j
+        }
+
+        for (let i = 1; i <= b.length; i++) {
+            for (let j = 1; j <= a.length; j++) {
+                if (b.charAt(i - 1) === a.charAt(j - 1)) {
+                    matrix[i][j] = matrix[i - 1][j - 1]
+                } else {
+                    matrix[i][j] = Math.min(
+                        matrix[i - 1][j - 1] + 1,
+                        matrix[i][j - 1] + 1,
+                        matrix[i - 1][j] + 1,
+                    )
+                }
+            }
+        }
+
+        return matrix[b.length][a.length]
+    }
+}

packages/ipuaro/src/infrastructure/tools/search/FindReferencesTool.ts

@@ -0,0 +1,260 @@
+import * as path from "node:path"
+import type { ITool, ToolContext, ToolParameterSchema } from "../../../domain/services/ITool.js"
+import {
+    createErrorResult,
+    createSuccessResult,
+    type ToolResult,
+} from "../../../domain/value-objects/ToolResult.js"
+
+/**
+ * A single reference to a symbol.
+ */
+export interface SymbolReference {
+    path: string
+    line: number
+    column: number
+    context: string
+    isDefinition: boolean
+}
+
+/**
+ * Result data from find_references tool.
+ */
+export interface FindReferencesResult {
+    symbol: string
+    totalReferences: number
+    files: number
+    references: SymbolReference[]
+    definitionLocations: {
+        path: string
+        line: number
+        type: string
+    }[]
+}
+
+/**
+ * Tool for finding all usages of a symbol across the codebase.
+ * Searches through indexed files for symbol references.
+ */
+export class FindReferencesTool implements ITool {
+    readonly name = "find_references"
+    readonly description =
+        "Find all usages of a symbol across the codebase. " +
+        "Returns list of file paths, line numbers, and context."
+    readonly parameters: ToolParameterSchema[] = [
+        {
+            name: "symbol",
+            type: "string",
+            description: "Symbol name to search for (function, class, variable, etc.)",
+            required: true,
+        },
+        {
+            name: "path",
+            type: "string",
+            description: "Limit search to specific file or directory",
+            required: false,
+        },
+    ]
+    readonly requiresConfirmation = false
+    readonly category = "search" as const
+
+    private readonly contextLines = 1
+
+    validateParams(params: Record<string, unknown>): string | null {
+        if (typeof params.symbol !== "string" || params.symbol.trim() === "") {
+            return "Parameter 'symbol' is required and must be a non-empty string"
+        }
+
+        if (params.path !== undefined && typeof params.path !== "string") {
+            return "Parameter 'path' must be a string"
+        }
+
+        return null
+    }
+
+    async execute(params: Record<string, unknown>, ctx: ToolContext): Promise<ToolResult> {
+        const startTime = Date.now()
+        const callId = `${this.name}-${String(startTime)}`
+
+        const symbol = (params.symbol as string).trim()
+        const filterPath = params.path as string | undefined
+
+        try {
+            const symbolIndex = await ctx.storage.getSymbolIndex()
+            const definitionLocations = symbolIndex.get(symbol) ?? []
+
+            const allFiles = await ctx.storage.getAllFiles()
+            const filesToSearch = this.filterFiles(allFiles, filterPath, ctx.projectRoot)
+
+            if (filesToSearch.size === 0) {
+                return createSuccessResult(
+                    callId,
+                    {
+                        symbol,
+                        totalReferences: 0,
+                        files: 0,
+                        references: [],
+                        definitionLocations: definitionLocations.map((loc) => ({
+                            path: loc.path,
+                            line: loc.line,
+                            type: loc.type,
+                        })),
+                    } satisfies FindReferencesResult,
+                    Date.now() - startTime,
+                )
+            }
+
+            const references: SymbolReference[] = []
+            const filesWithReferences = new Set<string>()
+
+            for (const [filePath, fileData] of filesToSearch) {
+                const fileRefs = this.findReferencesInFile(
+                    filePath,
+                    fileData.lines,
+                    symbol,
+                    definitionLocations,
+                )
+
+                if (fileRefs.length > 0) {
+                    filesWithReferences.add(filePath)
+                    references.push(...fileRefs)
+                }
+            }
+
+            references.sort((a, b) => {
+                const pathCompare = a.path.localeCompare(b.path)
+                if (pathCompare !== 0) {
+                    return pathCompare
+                }
+                return a.line - b.line
+            })
+
+            const result: FindReferencesResult = {
+                symbol,
+                totalReferences: references.length,
+                files: filesWithReferences.size,
+                references,
+                definitionLocations: definitionLocations.map((loc) => ({
+                    path: loc.path,
+                    line: loc.line,
+                    type: loc.type,
+                })),
+            }
+
+            return createSuccessResult(callId, result, Date.now() - startTime)
+        } catch (error) {
+            const message = error instanceof Error ? error.message : String(error)
+            return createErrorResult(callId, message, Date.now() - startTime)
+        }
+    }
+
+    /**
+     * Filter files by path prefix if specified.
+     */
+    private filterFiles(
+        allFiles: Map<string, { lines: string[] }>,
+        filterPath: string | undefined,
+        projectRoot: string,
+    ): Map<string, { lines: string[] }> {
+        if (!filterPath) {
+            return allFiles
+        }
+
+        const normalizedFilter = filterPath.startsWith("/")
+            ? path.relative(projectRoot, filterPath)
+            : filterPath
+
+        const filtered = new Map<string, { lines: string[] }>()
+        for (const [filePath, fileData] of allFiles) {
+            if (filePath === normalizedFilter || filePath.startsWith(`${normalizedFilter}/`)) {
+                filtered.set(filePath, fileData)
+            }
+        }
+
+        return filtered
+    }
+
+    /**
+     * Find all references to the symbol in a file.
+     */
+    private findReferencesInFile(
+        filePath: string,
+        lines: string[],
+        symbol: string,
+        definitionLocations: { path: string; line: number }[],
+    ): SymbolReference[] {
+        const references: SymbolReference[] = []
+        const symbolRegex = this.createSymbolRegex(symbol)
+
+        for (let lineIndex = 0; lineIndex < lines.length; lineIndex++) {
+            const line = lines[lineIndex]
+            const lineNumber = lineIndex + 1
+            let match: RegExpExecArray | null
+
+            symbolRegex.lastIndex = 0
+            while ((match = symbolRegex.exec(line)) !== null) {
+                const column = match.index + 1
+                const context = this.buildContext(lines, lineIndex)
+                const isDefinition = this.isDefinitionLine(
+                    filePath,
+                    lineNumber,
+                    definitionLocations,
+                )
+
+                references.push({
+                    path: filePath,
+                    line: lineNumber,
+                    column,
+                    context,
+                    isDefinition,
+                })
+            }
+        }
+
+        return references
+    }
+
+    /**
+     * Create a regex for matching the symbol with appropriate boundaries.
+     * Handles symbols that start or end with non-word characters (like $value).
+     */
+    private createSymbolRegex(symbol: string): RegExp {
+        const escaped = symbol.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")
+
+        const startsWithWordChar = /^\w/.test(symbol)
+        const endsWithWordChar = /\w$/.test(symbol)
+
+        const prefix = startsWithWordChar ? "\\b" : "(?<![\\w$])"
+        const suffix = endsWithWordChar ? "\\b" : "(?![\\w$])"
+
+        return new RegExp(`${prefix}${escaped}${suffix}`, "g")
+    }
+
+    /**
+     * Build context string with surrounding lines.
+     */
+    private buildContext(lines: string[], currentIndex: number): string {
+        const startIndex = Math.max(0, currentIndex - this.contextLines)
+        const endIndex = Math.min(lines.length - 1, currentIndex + this.contextLines)
+
+        const contextLines: string[] = []
+        for (let i = startIndex; i <= endIndex; i++) {
+            const lineNum = i + 1
+            const prefix = i === currentIndex ? ">" : " "
+            contextLines.push(`${prefix}${String(lineNum).padStart(4)}│${lines[i]}`)
+        }
+
+        return contextLines.join("\n")
+    }
+
+    /**
+     * Check if this line is a definition location.
+     */
+    private isDefinitionLine(
+        filePath: string,
+        lineNumber: number,
+        definitionLocations: { path: string; line: number }[],
+    ): boolean {
+        return definitionLocations.some((loc) => loc.path === filePath && loc.line === lineNumber)
+    }
+}

packages/ipuaro/src/infrastructure/tools/search/index.ts

@@ -0,0 +1,12 @@
+// Search tools exports
+export {
+    FindReferencesTool,
+    type FindReferencesResult,
+    type SymbolReference,
+} from "./FindReferencesTool.js"
+
+export {
+    FindDefinitionTool,
+    type FindDefinitionResult,
+    type DefinitionLocation,
+} from "./FindDefinitionTool.js"