@side-quest/kit 0.1.0 → 0.2.0

package/src/lib/ast/pattern.ts

@@ -0,0 +1,299 @@
+/**
+ * AST Pattern
+ *
+ * Compiles and matches AST search patterns against tree-sitter nodes.
+ * Ported from Kit's ASTPattern class in ast_search.py.
+ */
+
+import { getAstLogger } from '../logger.js'
+import type { SyntaxNode } from './languages.js'
+import { type PatternCriteria, SearchMode } from './types.js'
+
+/**
+ * Node types that represent function definitions across languages.
+ */
+const FUNCTION_NODE_TYPES = [
+	// TypeScript/JavaScript
+	'function_declaration',
+	'function_expression',
+	'arrow_function',
+	'method_definition',
+	'generator_function_declaration',
+	// Python
+	'function_definition',
+]
+
+/**
+ * Node types that represent class definitions across languages.
+ */
+const CLASS_NODE_TYPES = [
+	// TypeScript/JavaScript
+	'class_declaration',
+	'class_expression',
+	// Python
+	'class_definition',
+]
+
+/**
+ * Node types that represent try/catch statements.
+ */
+const TRY_NODE_TYPES = [
+	'try_statement', // TypeScript/JavaScript and Python
+]
+
+/**
+ * ASTPattern compiles search patterns and matches them against AST nodes.
+ *
+ * Supports two modes:
+ * - `simple`: Natural language patterns like "async function", "class"
+ * - `pattern`: JSON object criteria like {"type": "function_declaration"}
+ */
+export class ASTPattern {
+	readonly pattern: string
+	readonly mode: SearchMode
+
+	// Simple mode flags (parsed from natural language)
+	private isAsync = false
+	private isDef = false
+	private isClass = false
+	private isTry = false
+	private isImport = false
+	private isExport = false
+
+	// Pattern mode criteria (parsed from JSON)
+	private criteria: PatternCriteria = {}
+
+	/**
+	 * Create a new AST pattern.
+	 *
+	 * @param pattern - The search pattern string
+	 * @param mode - The search mode (simple or pattern)
+	 */
+	constructor(pattern: string, mode: SearchMode = SearchMode.SIMPLE) {
+		this.pattern = pattern
+		this.mode = mode
+		this.compile()
+	}
+
+	/**
+	 * Compile the pattern based on mode.
+	 */
+	private compile(): void {
+		if (this.mode === SearchMode.SIMPLE) {
+			this.compileSimple()
+		} else if (this.mode === SearchMode.PATTERN) {
+			this.compilePattern()
+		}
+	}
+
+	/**
+	 * Compile simple mode pattern from natural language.
+	 * Parses keywords like "async", "function", "class", etc.
+	 */
+	private compileSimple(): void {
+		const lower = this.pattern.toLowerCase()
+
+		// Check for keywords
+		this.isAsync = lower.includes('async')
+		this.isDef =
+			lower.includes('function') ||
+			lower.includes('def') ||
+			lower.includes('method')
+		this.isClass = lower.includes('class')
+		this.isTry = lower.includes('try') || lower.includes('catch')
+		this.isImport = lower.includes('import')
+		this.isExport = lower.includes('export')
+
+		// If no specific keywords matched, treat as text search
+		if (
+			!this.isAsync &&
+			!this.isDef &&
+			!this.isClass &&
+			!this.isTry &&
+			!this.isImport &&
+			!this.isExport
+		) {
+			// Fall back to text matching mode
+			this.criteria = { textMatch: this.pattern }
+		}
+	}
+
+	/**
+	 * Compile pattern mode from JSON criteria.
+	 */
+	private compilePattern(): void {
+		try {
+			this.criteria = JSON.parse(this.pattern)
+		} catch (error) {
+			// If JSON parsing fails, treat as text match
+			// Log at debug level since this is often intentional (user typed plain text)
+			const logger = getAstLogger()
+			logger.debug('Pattern JSON parse failed, using text match fallback', {
+				pattern: this.pattern,
+				error: error instanceof Error ? error.message : String(error),
+			})
+			this.criteria = { textMatch: this.pattern }
+		}
+	}
+
+	/**
+	 * Check if a node matches this pattern.
+	 *
+	 * @param node - The tree-sitter syntax node
+	 * @param source - The source code string
+	 * @returns True if the node matches
+	 */
+	matches(node: SyntaxNode, source: string): boolean {
+		if (this.mode === SearchMode.SIMPLE) {
+			return this.matchesSimple(node, source)
+		} else if (this.mode === SearchMode.PATTERN) {
+			return this.matchesPattern(node, source)
+		}
+		return false
+	}
+
+	/**
+	 * Match a node against simple mode pattern.
+	 */
+	private matchesSimple(node: SyntaxNode, source: string): boolean {
+		const nodeType = node.type
+
+		// If we're looking for specific constructs
+		if (
+			this.isDef ||
+			this.isClass ||
+			this.isTry ||
+			this.isImport ||
+			this.isExport
+		) {
+			// Check construct type
+			if (this.isDef && !this.isFunctionNode(nodeType)) return false
+			if (this.isClass && !this.isClassNode(nodeType)) return false
+			if (this.isTry && !TRY_NODE_TYPES.includes(nodeType)) return false
+			if (this.isImport && !nodeType.includes('import')) return false
+			if (this.isExport && !nodeType.includes('export')) return false
+
+			// Check async modifier (only for functions)
+			if (this.isAsync && this.isDef) {
+				if (!this.hasAsyncModifier(node)) return false
+			}
+
+			return true
+		}
+
+		// Text match fallback
+		if (this.criteria.textMatch) {
+			const text = this.getNodeText(node, source)
+			return text.includes(this.criteria.textMatch)
+		}
+
+		return false
+	}
+
+	/**
+	 * Match a node against pattern mode criteria.
+	 */
+	private matchesPattern(node: SyntaxNode, source: string): boolean {
+		// Match node type
+		if (this.criteria.type && node.type !== this.criteria.type) {
+			return false
+		}
+
+		// Match async modifier
+		if (this.criteria.async !== undefined) {
+			if (this.hasAsyncModifier(node) !== this.criteria.async) {
+				return false
+			}
+		}
+
+		// Match symbol name
+		if (this.criteria.name) {
+			const name = this.getNodeName(node, source)
+			if (name !== this.criteria.name) {
+				return false
+			}
+		}
+
+		// Match text content
+		if (this.criteria.textMatch) {
+			const text = this.getNodeText(node, source)
+			if (!text.includes(this.criteria.textMatch)) {
+				return false
+			}
+		}
+
+		// If no criteria specified, don't match anything
+		if (
+			!this.criteria.type &&
+			!this.criteria.async &&
+			!this.criteria.name &&
+			!this.criteria.textMatch
+		) {
+			return false
+		}
+
+		return true
+	}
+
+	/**
+	 * Check if a node type is a function node.
+	 */
+	private isFunctionNode(type: string): boolean {
+		return FUNCTION_NODE_TYPES.includes(type)
+	}
+
+	/**
+	 * Check if a node type is a class node.
+	 */
+	private isClassNode(type: string): boolean {
+		return CLASS_NODE_TYPES.includes(type)
+	}
+
+	/**
+	 * Check if a node has an async modifier.
+	 * Works for both direct 'async' child and keyword in text.
+	 */
+	private hasAsyncModifier(node: SyntaxNode): boolean {
+		// Check for 'async' child node (TypeScript/JavaScript)
+		for (const child of node.children) {
+			if (child && child.type === 'async') return true
+		}
+
+		// Check for async keyword in first few characters
+		// This handles cases where async is part of the node text
+		const firstPart = node.text?.slice(0, 10) ?? ''
+		return firstPart.includes('async')
+	}
+
+	/**
+	 * Get the name of a named node (function, class, etc.)
+	 */
+	private getNodeName(node: SyntaxNode, source: string): string | undefined {
+		// Look for identifier or name child
+		for (const child of node.children) {
+			if (!child) continue
+			if (
+				child.type === 'identifier' ||
+				child.type === 'type_identifier' ||
+				child.type === 'property_identifier'
+			) {
+				return source.substring(child.startIndex, child.endIndex)
+			}
+		}
+
+		// Check named children
+		const nameChild = node.childForFieldName('name')
+		if (nameChild) {
+			return source.substring(nameChild.startIndex, nameChild.endIndex)
+		}
+
+		return undefined
+	}
+
+	/**
+	 * Get the text content of a node.
+	 */
+	private getNodeText(node: SyntaxNode, source: string): string {
+		return source.substring(node.startIndex, node.endIndex)
+	}
+}

package/src/lib/ast/searcher.ts

@@ -0,0 +1,381 @@
+/**
+ * AST Searcher
+ *
+ * Searches files using tree-sitter AST patterns.
+ * Ported from Kit's ASTSearcher class in ast_search.py.
+ *
+ * Performance optimizations:
+ * - Uses fs/promises for non-blocking I/O
+ * - Parses files in parallel chunks to maximize throughput
+ */
+
+import { readdir, readFile, stat } from 'node:fs/promises'
+import { join, relative } from 'node:path'
+import { processInParallelChunks } from '@side-quest/core/concurrency'
+import { getAstLogger } from '../logger.js'
+import { getDefaultKitPath } from '../types.js'
+import type { SyntaxNode } from './languages.js'
+import { detectLanguage, getParser, isSupported } from './languages.js'
+import { ASTPattern } from './pattern.js'
+import {
+	type ASTMatch,
+	type ASTMatchContext,
+	type ASTSearchOptions,
+	type ASTSearchResult,
+	SearchMode,
+} from './types.js'
+
+/**
+ * Maximum file size to parse (5MB).
+ * Larger files are skipped to prevent memory issues.
+ */
+const MAX_FILE_SIZE = 5 * 1024 * 1024
+
+/**
+ * Maximum text length to include in match results.
+ */
+const MAX_TEXT_LENGTH = 500
+
+/**
+ * Number of files to parse in parallel.
+ * Balances throughput vs memory usage.
+ */
+const PARALLEL_CHUNK_SIZE = 10
+
+/**
+ * Directories to skip during traversal.
+ */
+const SKIP_DIRS = new Set([
+	'node_modules',
+	'.git',
+	'.svn',
+	'.hg',
+	'__pycache__',
+	'.pytest_cache',
+	'.mypy_cache',
+	'dist',
+	'build',
+	'.next',
+	'.nuxt',
+	'coverage',
+	'.coverage',
+	'venv',
+	'.venv',
+	'env',
+	'.env',
+])
+
+/**
+ * ASTSearcher performs AST-based code search using tree-sitter.
+ *
+ * It traverses the file system, parses supported files, and matches
+ * AST nodes against the given pattern.
+ */
+export class ASTSearcher {
+	private readonly repoPath: string
+
+	/**
+	 * Create a new AST searcher.
+	 *
+	 * @param repoPath - Repository path to search (defaults to KIT_DEFAULT_PATH or cwd)
+	 */
+	constructor(repoPath?: string) {
+		this.repoPath = repoPath ?? getDefaultKitPath()
+	}
+
+	/**
+	 * Search for AST patterns in the repository.
+	 *
+	 * Files are parsed in parallel chunks for better performance.
+	 *
+	 * @param options - Search options
+	 * @returns Search results with matching AST nodes
+	 */
+	async searchPattern(options: ASTSearchOptions): Promise<ASTSearchResult> {
+		const {
+			pattern,
+			mode = SearchMode.SIMPLE,
+			filePattern,
+			maxResults = 100,
+		} = options
+
+		const astPattern = new ASTPattern(pattern, mode)
+
+		// Get all files to search (async directory traversal)
+		const files = await this.getMatchingFiles(filePattern)
+
+		// Debug logging for MCP issues
+		const logger = getAstLogger()
+		logger.debug('File search results', {
+			fileCount: files.length,
+			repoPath: this.repoPath,
+			filePattern,
+			firstFiles: files.slice(0, 3),
+		})
+
+		// Process files in parallel chunks using core utility
+		const matches = await processInParallelChunks({
+			items: files,
+			chunkSize: PARALLEL_CHUNK_SIZE,
+			maxResults,
+			processor: (filePath) => this.searchFile(filePath, astPattern),
+			onError: (filePath, error) => {
+				logger.error('Error parsing file', {
+					filePath,
+					error: error.message,
+				})
+				return []
+			},
+		})
+
+		return {
+			count: matches.length,
+			matches,
+			pattern,
+			mode,
+			path: this.repoPath,
+		}
+	}
+
+	/**
+	 * Get all files matching the pattern.
+	 *
+	 * @param filePattern - Optional glob pattern to filter files
+	 * @returns Array of absolute file paths
+	 */
+	private async getMatchingFiles(filePattern?: string): Promise<string[]> {
+		const files: string[] = []
+		await this.walkDirectory(this.repoPath, files, filePattern)
+		return files
+	}
+
+	/**
+	 * Recursively walk directory and collect matching files.
+	 * Uses async fs methods to avoid blocking the event loop.
+	 */
+	private async walkDirectory(
+		dir: string,
+		files: string[],
+		filePattern?: string,
+	): Promise<void> {
+		const logger = getAstLogger()
+
+		let entries: string[]
+		try {
+			entries = await readdir(dir)
+		} catch (error) {
+			// Directory doesn't exist or can't be read
+			logger.warn('Failed to read directory', {
+				dir,
+				error: error instanceof Error ? error.message : String(error),
+			})
+			return
+		}
+
+		// Process entries in parallel for faster traversal
+		await Promise.all(
+			entries.map(async (entry) => {
+				// Skip hidden and ignored directories
+				if (SKIP_DIRS.has(entry) || entry.startsWith('.')) return
+
+				const fullPath = join(dir, entry)
+
+				let stats: Awaited<ReturnType<typeof stat>>
+				try {
+					stats = await stat(fullPath)
+				} catch (error) {
+					logger.debug('Failed to stat entry', {
+						path: fullPath,
+						error: error instanceof Error ? error.message : String(error),
+					})
+					return
+				}
+
+				if (stats.isDirectory()) {
+					await this.walkDirectory(fullPath, files, filePattern)
+				} else if (stats.isFile()) {
+					// Skip large files
+					if (stats.size > MAX_FILE_SIZE) {
+						logger.warn('Skipping large file', {
+							path: fullPath,
+							size: stats.size,
+							maxSize: MAX_FILE_SIZE,
+						})
+						return
+					}
+
+					// Check if file is supported for parsing
+					if (!isSupported(fullPath)) return
+
+					// Apply file pattern filter if provided
+					if (filePattern && !this.matchesFilePattern(fullPath, filePattern)) {
+						return
+					}
+
+					files.push(fullPath)
+				}
+			}),
+		)
+	}
+
+	/**
+	 * Check if a file matches the given pattern.
+	 * Uses Bun.Glob for proper glob pattern matching.
+	 */
+	private matchesFilePattern(filePath: string, pattern: string): boolean {
+		const relativePath = relative(this.repoPath, filePath)
+
+		// Use Bun.Glob for proper glob matching
+		const glob = new Bun.Glob(pattern)
+		return glob.match(relativePath)
+	}
+
+	/**
+	 * Search a single file for pattern matches.
+	 *
+	 * @param filePath - Absolute path to the file
+	 * @param pattern - AST pattern to match
+	 * @returns Array of matches found in the file
+	 */
+	private async searchFile(
+		filePath: string,
+		pattern: ASTPattern,
+	): Promise<ASTMatch[]> {
+		const language = detectLanguage(filePath)
+		if (!language) return []
+
+		const parser = await getParser(language)
+		const source = await readFile(filePath, 'utf8')
+		const tree = parser.parse(source)
+
+		// Handle parse failure
+		if (!tree) return []
+
+		const matches: ASTMatch[] = []
+		this.searchNode(tree.rootNode, source, pattern, filePath, matches)
+		return matches
+	}
+
+	/**
+	 * Recursively search AST nodes for pattern matches.
+	 */
+	private searchNode(
+		node: SyntaxNode,
+		source: string,
+		pattern: ASTPattern,
+		filePath: string,
+		matches: ASTMatch[],
+	): void {
+		// Check if this node matches the pattern
+		if (pattern.matches(node, source)) {
+			const match = this.createMatch(node, source, filePath)
+			matches.push(match)
+		}
+
+		// Recurse into children
+		for (let i = 0; i < node.childCount; i++) {
+			const child = node.child(i)
+			if (child) {
+				this.searchNode(child, source, pattern, filePath, matches)
+			}
+		}
+	}
+
+	/**
+	 * Create an ASTMatch from a matching node.
+	 */
+	private createMatch(
+		node: SyntaxNode,
+		source: string,
+		filePath: string,
+	): ASTMatch {
+		return {
+			file: relative(this.repoPath, filePath),
+			line: node.startPosition.row + 1,
+			column: node.startPosition.column,
+			nodeType: node.type,
+			text: this.truncateText(source.substring(node.startIndex, node.endIndex)),
+			context: this.getContext(node, source),
+		}
+	}
+
+	/**
+	 * Get context information about a matched node.
+	 */
+	private getContext(node: SyntaxNode, source: string): ASTMatchContext {
+		const context: ASTMatchContext = { nodeType: node.type }
+
+		// Walk up the tree to find parent function or class
+		let parent = node.parent
+		while (parent) {
+			if (this.isFunctionNode(parent.type)) {
+				context.parentFunction = this.getNodeName(parent, source)
+				break
+			}
+			if (this.isClassNode(parent.type)) {
+				context.parentClass = this.getNodeName(parent, source)
+				break
+			}
+			parent = parent.parent
+		}
+
+		return context
+	}
+
+	/**
+	 * Get the name of a named node (function, class, etc.).
+	 */
+	private getNodeName(node: SyntaxNode, source: string): string | undefined {
+		// Try named children first
+		const nameChild = node.childForFieldName('name')
+		if (nameChild) {
+			return source.substring(nameChild.startIndex, nameChild.endIndex)
+		}
+
+		// Look for identifier children
+		for (let i = 0; i < node.childCount; i++) {
+			const child = node.child(i)
+			if (
+				child &&
+				(child.type === 'identifier' || child.type === 'type_identifier')
+			) {
+				return source.substring(child.startIndex, child.endIndex)
+			}
+		}
+
+		return undefined
+	}
+
+	/**
+	 * Check if a node type is a function.
+	 */
+	private isFunctionNode(type: string): boolean {
+		return [
+			'function_declaration',
+			'function_definition',
+			'function_expression',
+			'arrow_function',
+			'method_definition',
+			'generator_function_declaration',
+		].includes(type)
+	}
+
+	/**
+	 * Check if a node type is a class.
+	 */
+	private isClassNode(type: string): boolean {
+		return [
+			'class_declaration',
+			'class_definition',
+			'class_expression',
+		].includes(type)
+	}
+
+	/**
+	 * Truncate text to maximum length.
+	 */
+	private truncateText(text: string): string {
+		if (text.length <= MAX_TEXT_LENGTH) return text
+		return `${text.slice(0, MAX_TEXT_LENGTH - 3)}...`
+	}
+}