@side-quest/kit 0.0.0 → 0.2.0

package/src/lib/ast/types.ts

@@ -0,0 +1,99 @@
+/**
+ * AST Search Types
+ *
+ * Type definitions for AST-based code search using tree-sitter.
+ */
+
+/**
+ * Search mode for AST patterns.
+ *
+ * - `simple`: Natural language patterns like "async function", "class"
+ * - `pattern`: JSON object criteria like {"type": "function_declaration"}
+ */
+export enum SearchMode {
+	/** Natural language patterns: "async function", "class", "try" */
+	SIMPLE = 'simple',
+	/** JSON criteria: {"type": "function_declaration", "async": true} */
+	PATTERN = 'pattern',
+}
+
+/**
+ * A single AST match found during search.
+ */
+export interface ASTMatch {
+	/** File path relative to repository root */
+	file: string
+	/** Line number (1-indexed) */
+	line: number
+	/** Column number (0-indexed) */
+	column: number
+	/** Tree-sitter node type (e.g., "function_declaration") */
+	nodeType: string
+	/** Matched source text (truncated to 500 chars) */
+	text: string
+	/** Context about where the match was found */
+	context: ASTMatchContext
+}
+
+/**
+ * Context information for an AST match.
+ */
+export interface ASTMatchContext {
+	/** The tree-sitter node type */
+	nodeType: string
+	/** Parent function name, if match is inside a function */
+	parentFunction?: string
+	/** Parent class name, if match is inside a class */
+	parentClass?: string
+}
+
+/**
+ * Options for AST search.
+ */
+export interface ASTSearchOptions {
+	/** Search pattern (natural language or JSON depending on mode) */
+	pattern: string
+	/** Search mode: 'simple' or 'pattern' */
+	mode?: SearchMode
+	/** File glob pattern (default: all supported files) */
+	filePattern?: string
+	/** Repository path to search */
+	path?: string
+	/** Maximum results to return (default: 100) */
+	maxResults?: number
+}
+
+/**
+ * Result of an AST search operation.
+ */
+export interface ASTSearchResult {
+	/** Number of matches found */
+	count: number
+	/** Array of AST matches */
+	matches: ASTMatch[]
+	/** The search pattern used */
+	pattern: string
+	/** The search mode used */
+	mode: SearchMode
+	/** Repository path searched */
+	path: string
+}
+
+/**
+ * Criteria for pattern mode matching.
+ */
+export interface PatternCriteria {
+	/** Tree-sitter node type to match */
+	type?: string
+	/** Whether node should be async */
+	async?: boolean
+	/** Text that must appear in the node */
+	textMatch?: string
+	/** Name of the symbol to match */
+	name?: string
+}
+
+/**
+ * Timeout for AST search operations (ms).
+ */
+export const AST_SEARCH_TIMEOUT = 60000

package/src/lib/commands/callers.ts

@@ -0,0 +1,226 @@
+/**
+ * Callers command - Find who calls a function
+ *
+ * Uses kit grep to find all call sites of a function, filtering out the
+ * definition itself to show only actual usage locations.
+ */
+
+import { color, OutputFormat } from '../formatters/output'
+import { executeKitGrep } from '../kit-wrapper'
+import { findSymbol, loadProjectIndex } from '../utils/index-parser'
+
+/**
+ * Call site result - a location where the function is called
+ */
+interface CallSite {
+	file: string
+	line: number
+	context: string
+}
+
+/**
+ * Result of callers search
+ */
+interface CallersResult {
+	functionName: string
+	definitionFile?: string
+	definitionLine?: number
+	callSites: CallSite[]
+	count: number
+}
+
+/**
+ * Format callers result as markdown
+ *
+ * @param result - Callers result to format
+ * @returns Formatted markdown string
+ */
+function formatMarkdown(result: CallersResult): string {
+	const { functionName, definitionFile, definitionLine, callSites, count } =
+		result
+
+	if (count === 0) {
+		return color(
+			'yellow',
+			`\n⚠️  No call sites found for function: ${functionName}\n`,
+		)
+	}
+
+	let output = color('cyan', `\n📞 Found ${count} call site(s) for: `)
+	output += color('blue', functionName)
+	output += '\n\n'
+
+	// Show definition location if available
+	if (definitionFile && definitionLine) {
+		output += color(
+			'dim',
+			`Definition: ${definitionFile}:${definitionLine}\n\n`,
+		)
+	}
+
+	// Group by file
+	const byFile = new Map<string, CallSite[]>()
+	for (const callSite of callSites) {
+		if (!byFile.has(callSite.file)) {
+			byFile.set(callSite.file, [])
+		}
+		byFile.get(callSite.file)?.push(callSite)
+	}
+
+	// Output each file
+	for (const [file, sites] of byFile.entries()) {
+		output += color('dim', `${file}:\n`)
+		for (const site of sites) {
+			output += `  ${color('dim', `L${site.line}:`)} ${site.context.trim()}\n`
+		}
+		output += '\n'
+	}
+
+	return output
+}
+
+/**
+ * Format callers result as JSON
+ *
+ * @param result - Callers result to format
+ * @returns JSON string
+ */
+function formatJSON(result: CallersResult): string {
+	return JSON.stringify(result, null, 2)
+}
+
+/**
+ * Execute callers command
+ *
+ * Finds all locations where a function is called by:
+ * 1. Looking up the function definition in PROJECT_INDEX.json
+ * 2. Using kit grep to find all occurrences
+ * 3. Filtering out the definition line to show only call sites
+ *
+ * @param functionName - Name of the function to find callers for
+ * @param format - Output format (markdown or JSON)
+ */
+export async function executeCallers(
+	functionName: string,
+	format: OutputFormat,
+): Promise<void> {
+	try {
+		// Find the function definition in the index
+		let definitionFile: string | undefined
+		let definitionLine: number | undefined
+
+		try {
+			const index = await loadProjectIndex()
+			const definitions = findSymbol(index, functionName)
+
+			// Use the first definition found (functions should be unique)
+			const firstDef = definitions[0]
+			if (firstDef) {
+				definitionFile = firstDef.file
+				definitionLine = firstDef.symbol.start_line
+			}
+		} catch {
+			// Index not available - we'll proceed without filtering the definition
+		}
+
+		// Use kit grep to find all occurrences
+		const grepResult = executeKitGrep({
+			pattern: functionName,
+			caseSensitive: true,
+			maxResults: 500,
+		})
+
+		// Handle errors
+		if ('error' in grepResult) {
+			if (format === OutputFormat.JSON) {
+				console.error(
+					JSON.stringify(
+						{
+							error: grepResult.error,
+							functionName,
+							isError: true,
+						},
+						null,
+						2,
+					),
+				)
+			} else {
+				console.error(color('red', '\n❌ Error:'), grepResult.error, '\n')
+			}
+			process.exit(1)
+		}
+
+		// Filter matches to exclude the definition line
+		let matches = grepResult.matches
+
+		if (definitionFile && definitionLine) {
+			matches = matches.filter(
+				(match) =>
+					!(match.file === definitionFile && match.line === definitionLine),
+			)
+		}
+
+		// Filter out matches that look like definitions rather than calls
+		// Heuristics:
+		// - Lines starting with "function ", "const ", "let ", "var ", "export function"
+		// - Lines with "= function" or "= (" (function assignments)
+		// - Lines with "export async function" (exported async functions)
+		matches = matches.filter((match) => {
+			const trimmed = match.content.trim()
+			const definitionPatterns = [
+				/^function\s+/, // function declarations
+				/^export\s+(async\s+)?function\s+/, // exported functions (sync or async)
+				/^(const|let|var)\s+\w+\s*=\s*function/, // function expressions
+				/^(const|let|var)\s+\w+\s*=\s*\(/, // arrow functions
+				/^(const|let|var)\s+\w+\s*=\s*async\s*\(/, // async arrow functions
+				/^async\s+function\s+/, // async function declarations
+			]
+
+			return !definitionPatterns.some((pattern) => pattern.test(trimmed))
+		})
+
+		// Convert to call sites
+		const callSites: CallSite[] = matches.map((match) => ({
+			file: match.file,
+			line: match.line || 0,
+			context: match.content,
+		}))
+
+		// Build result
+		const result: CallersResult = {
+			functionName,
+			definitionFile,
+			definitionLine,
+			callSites,
+			count: callSites.length,
+		}
+
+		// Output results
+		if (format === OutputFormat.JSON) {
+			console.log(formatJSON(result))
+		} else {
+			console.log(formatMarkdown(result))
+		}
+	} catch (error) {
+		if (format === OutputFormat.JSON) {
+			console.error(
+				JSON.stringify(
+					{
+						error: error instanceof Error ? error.message : 'Unknown error',
+						functionName,
+						isError: true,
+					},
+					null,
+					2,
+				),
+			)
+		} else {
+			console.error(
+				color('red', '\n❌ Error:'),
+				error instanceof Error ? error.message : error,
+				'\n',
+			)
+		}
+		process.exit(1)
+	}
+}

package/src/lib/commands/find.ts

@@ -0,0 +1,159 @@
+/**
+ * Find command - Locate symbol definitions by name
+ *
+ * Searches PROJECT_INDEX.json for symbol definitions with exact or fuzzy matching.
+ * Supports dual output formats (markdown table or JSON).
+ */
+
+import { color, OutputFormat } from '../formatters/output'
+import {
+	findSymbol,
+	findSymbolFuzzy,
+	type Symbol as IndexSymbol,
+	loadProjectIndex,
+} from '../utils/index-parser'
+
+/**
+ * Format symbol results as markdown table
+ */
+function formatMarkdown(
+	results: Array<{ file: string; symbol: IndexSymbol }>,
+	query: string,
+): string {
+	if (results.length === 0) {
+		return color('yellow', `\n⚠️  No symbols found matching: ${query}\n`)
+	}
+
+	let output = color('cyan', `\n📍 Found ${results.length} symbol(s)\n\n`)
+
+	// Group by file
+	const byFile = new Map<string, IndexSymbol[]>()
+	for (const { file, symbol } of results) {
+		if (!byFile.has(file)) {
+			byFile.set(file, [])
+		}
+		byFile.get(file)?.push(symbol)
+	}
+
+	// Output each file
+	for (const [file, symbols] of byFile.entries()) {
+		output += color('dim', `${file}:\n`)
+		for (const symbol of symbols) {
+			const typeColor = getTypeColor(symbol.type)
+			output += `  ${color('dim', '•')} ${color(typeColor, symbol.type.padEnd(10))} ${color('blue', symbol.name)} ${color('dim', `(line ${symbol.start_line}`)}\n`
+		}
+		output += '\n'
+	}
+
+	return output
+}
+
+/**
+ * Get color for symbol type
+ */
+function getTypeColor(
+	type: string,
+): 'blue' | 'green' | 'magenta' | 'cyan' | 'yellow' {
+	switch (type) {
+		case 'function':
+			return 'blue'
+		case 'class':
+			return 'green'
+		case 'interface':
+		case 'type':
+			return 'magenta'
+		case 'constant':
+			return 'cyan'
+		default:
+			return 'yellow'
+	}
+}
+
+/**
+ * Format symbol results as JSON
+ */
+function formatJSON(
+	results: Array<{ file: string; symbol: IndexSymbol }>,
+	query: string,
+): string {
+	return JSON.stringify(
+		{
+			query,
+			count: results.length,
+			results: results.map(({ file, symbol }) => ({
+				file,
+				name: symbol.name,
+				type: symbol.type,
+				line: symbol.start_line,
+				code: symbol.code,
+			})),
+		},
+		null,
+		2,
+	)
+}
+
+/**
+ * Execute find command
+ *
+ * @param symbol - Symbol name to search for
+ * @param format - Output format (markdown or JSON)
+ */
+export async function executeFind(
+	symbol: string,
+	format: OutputFormat,
+): Promise<void> {
+	try {
+		const index = await loadProjectIndex()
+
+		// Try exact match first
+		let results: Array<{ file: string; symbol: IndexSymbol }> = findSymbol(
+			index,
+			symbol,
+		)
+
+		// If no exact match, try fuzzy search
+		if (results.length === 0) {
+			const fuzzyResults = findSymbolFuzzy(index, symbol)
+			if (fuzzyResults.length > 0 && format === OutputFormat.MARKDOWN) {
+				console.log(
+					color(
+						'yellow',
+						`\n⚠️  No exact match for "${symbol}". Showing fuzzy matches:\n`,
+					),
+				)
+			}
+			results = fuzzyResults.map(({ file, symbol: sym }) => ({
+				file,
+				symbol: sym,
+			}))
+		}
+
+		// Output results
+		if (format === OutputFormat.JSON) {
+			console.log(formatJSON(results, symbol))
+		} else {
+			console.log(formatMarkdown(results, symbol))
+		}
+	} catch (error) {
+		if (format === OutputFormat.JSON) {
+			console.error(
+				JSON.stringify(
+					{
+						error: error instanceof Error ? error.message : 'Unknown error',
+						isError: true,
+					},
+					null,
+					2,
+				),
+			)
+		} else {
+			console.error(
+				color('red', '\n❌ Error:'),
+				error instanceof Error ? error.message : error,
+			)
+		}
+
+		process.exit(1)
+	}
+}

package/src/lib/commands/overview.ts

@@ -0,0 +1,73 @@
+/**
+ * Overview command - List all symbols in a file
+ */
+
+import { color, OutputFormat } from '../formatters/output'
+import {
+	getFileSymbols,
+	type Symbol as IndexSymbol,
+	loadProjectIndex,
+} from '../utils/index-parser'
+
+export async function executeOverview(
+	file: string,
+	format: OutputFormat,
+): Promise<void> {
+	try {
+		const index = await loadProjectIndex()
+		const symbols = getFileSymbols(index, file)
+
+		if (symbols.length === 0) {
+			if (format === OutputFormat.JSON) {
+				console.log(JSON.stringify({ file, symbols: [] }, null, 2))
+			} else {
+				console.log(color('yellow', `\n⚠️  No symbols found in: ${file}\n`))
+			}
+			return
+		}
+
+		if (format === OutputFormat.JSON) {
+			console.log(
+				JSON.stringify({ file, count: symbols.length, symbols }, null, 2),
+			)
+		} else {
+			// Group by type
+			const grouped = symbols.reduce(
+				(acc, sym) => {
+					if (!acc[sym.type]) acc[sym.type] = []
+					acc[sym.type]?.push(sym)
+					return acc
+				},
+				{} as Record<string, IndexSymbol[]>,
+			)
+
+			console.log(color('cyan', `\n📄 ${file}\n`))
+			console.log(color('dim', `Total symbols: ${symbols.length}\n`))
+
+			for (const [type, syms] of Object.entries(grouped)) {
+				console.log(color('magenta', `${type}s:`))
+				for (const sym of syms) {
+					console.log(
+						`  ${color('dim', '•')} ${color('blue', sym.name)} ${color('dim', `(line ${sym.start_line})`)}`,
+					)
+				}
+				console.log('')
+			}
+		}
+	} catch (error) {
+		console.error(
+			format === OutputFormat.JSON
+				? JSON.stringify(
+						{
+							error: error instanceof Error ? error.message : 'Unknown error',
+							isError: true,
+						},
+						null,
+						2,
+					)
+				: color('red', '\n❌ Error:') +
+						` ${error instanceof Error ? error.message : error}`,
+		)
+		process.exit(1)
+	}
+}