@side-quest/kit 0.0.0 → 0.2.0

package/src/lib/types.ts

@@ -0,0 +1,228 @@
+/**
+ * Kit Plugin Type Definitions
+ *
+ * Shared types for the Kit MCP server and CLI wrapper.
+ */
+
+// ============================================================================
+// Response Format
+// ============================================================================
+
+/**
+ * Response format options for tool output.
+ */
+export enum ResponseFormat {
+	MARKDOWN = 'markdown',
+	JSON = 'json',
+}
+
+// ============================================================================
+// Grep Types
+// ============================================================================
+
+/**
+ * A single grep match result.
+ */
+export interface GrepMatch {
+	/** Relative file path from repository root */
+	file: string
+	/** Line number (1-indexed) */
+	line?: number
+	/** Matched line content */
+	content: string
+}
+
+/**
+ * Result of a grep search operation.
+ */
+export interface GrepResult {
+	/** Number of matches found */
+	count: number
+	/** Array of match objects */
+	matches: GrepMatch[]
+	/** Search pattern used */
+	pattern: string
+	/** Repository path searched */
+	path: string
+}
+
+/**
+ * Options for grep search.
+ */
+export interface GrepOptions {
+	/** Search pattern (text or regex) */
+	pattern: string
+	/** Repository path to search */
+	path?: string
+	/** Case-sensitive search (default: true) */
+	caseSensitive?: boolean
+	/** File pattern to include (e.g., "*.py") */
+	include?: string
+	/** File pattern to exclude */
+	exclude?: string
+	/** Maximum results to return (default: 100) */
+	maxResults?: number
+	/** Subdirectory to search within */
+	directory?: string
+}
+
+// ============================================================================
+// Semantic Search Types
+// ============================================================================
+
+/**
+ * A single semantic search match.
+ */
+export interface SemanticMatch {
+	/** Relative file path */
+	file: string
+	/** Code chunk that matched */
+	chunk: string
+	/** Relevance score (higher = more relevant) */
+	score: number
+	/** Start line of the chunk */
+	startLine?: number
+	/** End line of the chunk */
+	endLine?: number
+}
+
+/**
+ * Result of a semantic search operation.
+ */
+export interface SemanticResult {
+	/** Number of matches found */
+	count: number
+	/** Array of semantic matches */
+	matches: SemanticMatch[]
+	/** Natural language query used */
+	query: string
+	/** Repository path searched */
+	path: string
+	/** Whether results came from fallback grep */
+	fallback?: boolean
+	/** Install hint if semantic search unavailable */
+	installHint?: string
+}
+
+/**
+ * Options for semantic search.
+ */
+export interface SemanticOptions {
+	/** Natural language query */
+	query: string
+	/** Repository path to search */
+	path?: string
+	/** Number of results to return (default: 5) */
+	topK?: number
+	/** Chunking strategy: 'symbols' or 'lines' */
+	chunkBy?: 'symbols' | 'lines'
+	/** Force rebuild of vector index */
+	buildIndex?: boolean
+}
+
+// ============================================================================
+// Symbol Usages Types
+// ============================================================================
+
+/**
+ * A symbol usage/definition found by Kit.
+ */
+export interface SymbolUsage {
+	/** File containing the symbol */
+	file: string
+	/** Symbol type (function, class, variable, etc.) */
+	type: string
+	/** Symbol name */
+	name: string
+	/** Line number (may be null in current Kit version) */
+	line: number | null
+	/** Context around the usage */
+	context: string | null
+}
+
+/**
+ * Result of a symbol usages search.
+ */
+export interface UsagesResult {
+	/** Number of usages found */
+	count: number
+	/** Array of symbol usages */
+	usages: SymbolUsage[]
+	/** Symbol name searched for */
+	symbolName: string
+	/** Repository path searched */
+	path: string
+}
+
+/**
+ * Options for symbol usages search.
+ */
+export interface UsagesOptions {
+	/** Repository path */
+	path?: string
+	/** Symbol name to find usages for */
+	symbolName: string
+	/** Filter by symbol type (function, class, etc.) */
+	symbolType?: string
+}
+
+// ============================================================================
+// Generic Result Types
+// ============================================================================
+
+/**
+ * Error result type.
+ */
+export interface ErrorResult {
+	/** Error message */
+	error: string
+	/** Optional recovery hint */
+	hint?: string
+}
+
+/**
+ * Generic result type that can be success or error.
+ */
+export type KitResult<T> = T | ErrorResult
+
+/**
+ * Type guard for error results.
+ */
+export function isError<T extends object>(
+	result: KitResult<T>,
+): result is ErrorResult {
+	return typeof result === 'object' && result !== null && 'error' in result
+}
+
+// ============================================================================
+// Default Configuration
+// ============================================================================
+
+/** Environment variable name for configuring default path */
+export const KIT_DEFAULT_PATH_ENV = 'KIT_DEFAULT_PATH'
+
+/**
+ * Get the default path for Kit operations using cascading defaults:
+ * 1. KIT_DEFAULT_PATH environment variable (if set)
+ * 2. Current working directory (process.cwd())
+ *
+ * @returns Resolved default path for Kit operations
+ */
+export function getDefaultKitPath(): string {
+	return process.env[KIT_DEFAULT_PATH_ENV] || process.cwd()
+}
+
+/** Default timeout for grep operations (ms) */
+export const GREP_TIMEOUT = 30000
+
+/** Default timeout for semantic operations (ms) */
+export const SEMANTIC_TIMEOUT = 60000
+
+/** Default timeout for symbol usages operations (ms) */
+export const USAGES_TIMEOUT = 45000
+
+/** Default max results for grep */
+export const DEFAULT_MAX_RESULTS = 100
+
+/** Default top-k for semantic search */
+export const DEFAULT_TOP_K = 5

package/src/lib/utils/args.ts

@@ -0,0 +1,72 @@
+/**
+ * Command-line argument parsing utilities
+ *
+ * Adapted from cinema-bandit plugin's argument parsing pattern.
+ * Parses arguments in the format: <command> [positional] [--flag value]
+ */
+
+/**
+ * Parsed command-line arguments
+ */
+export interface ParsedArgs {
+	/** The subcommand (e.g., "prime", "find", "callers") */
+	command: string
+	/** Positional arguments after the command */
+	positional: string[]
+	/** Named flags (e.g., --format json, --force) */
+	flags: Record<string, string>
+}
+
+/**
+ * Parses command-line arguments into a structured object.
+ *
+ * @param args - Raw arguments from process.argv.slice(2)
+ * @returns Parsed arguments with command, positional args, and flags
+ *
+ * @example
+ * ```typescript
+ * parseArgs(["prime"]);
+ * // { command: "prime", positional: [], flags: {} }
+ *
+ * parseArgs(["find", "MyFunction"]);
+ * // { command: "find", positional: ["MyFunction"], flags: {} }
+ *
+ * parseArgs(["find", "MyFunction", "--format", "json"]);
+ * // { command: "find", positional: ["MyFunction"], flags: { "format": "json" } }
+ *
+ * parseArgs(["prime", "--force"]);
+ * // { command: "prime", positional: [], flags: { "force": "true" } }
+ * ```
+ */
+export function parseArgs(args: string[]): ParsedArgs {
+	const command = args[0] ?? ''
+	const positional: string[] = []
+	const flags: Record<string, string> = {}
+
+	let i = 1
+	while (i < args.length) {
+		const arg = args[i] as string
+
+		if (arg.startsWith('--')) {
+			// Handle --flag or --flag value
+			const key = arg.slice(2)
+			const nextArg = args[i + 1]
+
+			// Check if there's a value after the flag
+			if (nextArg && !nextArg.startsWith('--')) {
+				flags[key] = nextArg
+				i += 2
+			} else {
+				// Boolean flag (no value)
+				flags[key] = 'true'
+				i++
+			}
+		} else {
+			// Positional argument
+			positional.push(arg)
+			i++
+		}
+	}
+
+	return { command, positional, flags }
+}

package/src/lib/utils/git.ts

@@ -0,0 +1,65 @@
+import { resolve } from 'node:path'
+import {
+	ensureCommandAvailable,
+	spawnSyncCollect,
+	spawnWithTimeout,
+} from '@side-quest/core/spawn'
+
+/**
+ * Find the git repository root directory (async).
+ * @returns The git root path, or null if not in a git repo
+ */
+export async function findGitRoot(): Promise<string | null> {
+	const gitCmd = ensureCommandAvailable('git')
+	const result = await spawnWithTimeout(
+		[gitCmd, 'rev-parse', '--show-toplevel'],
+		10_000,
+	)
+
+	if (result.timedOut || result.exitCode !== 0) {
+		return null
+	}
+
+	if (result.stdout) {
+		return result.stdout.trim()
+	}
+
+	return null
+}
+
+/**
+ * Find the git repository root directory (synchronous).
+ * @returns The git root path, or undefined if not in a git repo
+ */
+export function findGitRootSync(): string | undefined {
+	const result = spawnSyncCollect(['git', 'rev-parse', '--show-toplevel'])
+	if (result.exitCode === 0 && result.stdout.trim()) {
+		return result.stdout.trim()
+	}
+	return undefined
+}
+
+/**
+ * Resolve the target directory for operations.
+ * Uses custom path if provided, falls back to git root, then cwd.
+ * @param customPath - Optional custom path to use
+ * @returns Resolved target directory path
+ */
+export async function getTargetDir(customPath?: string): Promise<string> {
+	if (customPath) {
+		return resolve(customPath)
+	}
+
+	const gitRoot = await findGitRoot()
+	if (gitRoot) {
+		return gitRoot
+	}
+
+	return process.cwd()
+}
+
+/**
+ * Constants for index file management
+ */
+export const INDEX_FILE = 'PROJECT_INDEX.json'
+export const MAX_AGE_HOURS = 24

package/src/lib/utils/index-parser.ts

@@ -0,0 +1,350 @@
+/**
+ * PROJECT_INDEX.json parser and query utilities
+ *
+ * Provides TypeScript-based queries to replace jq dependencies.
+ * Supports git-style directory search to find index from any subdirectory.
+ */
+
+import { dirname, join, resolve } from 'node:path'
+import { findUpSync, pathExistsSync } from '@side-quest/core/fs'
+
+/**
+ * Symbol definition from Kit CLI index
+ */
+export interface Symbol {
+	name: string
+	type: 'function' | 'class' | 'interface' | 'type' | 'constant' | 'variable'
+	start_line: number
+	end_line: number
+	code: string
+	file: string
+}
+
+/**
+ * File tree entry
+ */
+export interface FileTreeEntry {
+	path: string
+	is_dir: boolean
+	name: string
+	size: number
+}
+
+/**
+ * PROJECT_INDEX.json structure (from Kit CLI)
+ */
+export interface ProjectIndex {
+	file_tree: FileTreeEntry[]
+	files: FileTreeEntry[]
+	symbols: Record<string, Symbol[]>
+}
+
+/**
+ * Search up directory tree for PROJECT_INDEX.json (git-style)
+ *
+ * Note: Delegates to @sidequest/core/fs findUpSync for the file search.
+ *
+ * @param startDir - Directory to start searching from (default: process.cwd())
+ * @returns Absolute path to PROJECT_INDEX.json
+ * @throws Error if index not found
+ */
+export async function findProjectIndex(
+	startDir: string = process.cwd(),
+): Promise<string> {
+	const indexPath = findUpSync('PROJECT_INDEX.json', startDir)
+
+	if (indexPath) {
+		return indexPath
+	}
+
+	throw new Error(
+		'PROJECT_INDEX.json not found in current directory or any parent directory.\n' +
+			'Run: bun run src/cli.ts prime',
+	)
+}
+
+/**
+ * Resolve explicit path to PROJECT_INDEX.json
+ *
+ * Handles three cases:
+ * 1. Path to PROJECT_INDEX.json file directly
+ * 2. Path to directory containing PROJECT_INDEX.json
+ * 3. Relative path that needs resolution
+ *
+ * @param explicitPath - Explicit path provided by user
+ * @returns Absolute path to PROJECT_INDEX.json
+ * @throws Error if index not found at specified path
+ */
+export function resolveExplicitIndexPath(explicitPath: string): string {
+	const resolved = resolve(explicitPath)
+
+	// Case 1: Direct path to PROJECT_INDEX.json
+	if (resolved.endsWith('PROJECT_INDEX.json')) {
+		if (pathExistsSync(resolved)) {
+			return resolved
+		}
+		throw new Error(`PROJECT_INDEX.json not found at: ${resolved}`)
+	}
+
+	// Case 2: Directory containing PROJECT_INDEX.json
+	const indexInDir = join(resolved, 'PROJECT_INDEX.json')
+	if (pathExistsSync(indexInDir)) {
+		return indexInDir
+	}
+
+	throw new Error(
+		`PROJECT_INDEX.json not found at: ${indexInDir}\n` +
+			'Specify either:\n' +
+			'  - Path to PROJECT_INDEX.json file\n' +
+			'  - Directory containing PROJECT_INDEX.json',
+	)
+}
+
+/**
+ * Load and parse PROJECT_INDEX.json
+ *
+ * @param explicitPath - Optional explicit path to index file or directory
+ * @returns Parsed project index
+ * @throws Error if index not found or invalid JSON
+ */
+export async function loadProjectIndex(
+	explicitPath?: string,
+): Promise<ProjectIndex> {
+	const indexPath = explicitPath
+		? resolveExplicitIndexPath(explicitPath)
+		: await findProjectIndex()
+	const file = Bun.file(indexPath)
+	return (await file.json()) as ProjectIndex
+}
+
+/**
+ * Find symbols by name across all files
+ *
+ * @param index - Project index
+ * @param symbolName - Symbol name to search for (exact match)
+ * @returns Array of matching symbols with their file paths
+ */
+export function findSymbol(
+	index: ProjectIndex,
+	symbolName: string,
+): Array<{ file: string; symbol: Symbol }> {
+	const results: Array<{ file: string; symbol: Symbol }> = []
+
+	for (const [file, symbols] of Object.entries(index.symbols)) {
+		for (const symbol of symbols) {
+			if (symbol.name === symbolName) {
+				results.push({ file, symbol })
+			}
+		}
+	}
+
+	return results
+}
+
+/**
+ * Find symbols by fuzzy name matching (case-insensitive substring)
+ *
+ * @param index - Project index
+ * @param query - Search query (substring, case-insensitive)
+ * @returns Array of matching symbols with their file paths
+ */
+export function findSymbolFuzzy(
+	index: ProjectIndex,
+	query: string,
+): Array<{ file: string; symbol: Symbol; score: number }> {
+	const results: Array<{ file: string; symbol: Symbol; score: number }> = []
+	const lowerQuery = query.toLowerCase()
+
+	for (const [file, symbols] of Object.entries(index.symbols)) {
+		for (const symbol of symbols) {
+			const lowerName = symbol.name.toLowerCase()
+
+			// Exact match (highest score)
+			if (lowerName === lowerQuery) {
+				results.push({ file, symbol, score: 100 })
+			}
+			// Starts with (high score)
+			else if (lowerName.startsWith(lowerQuery)) {
+				results.push({ file, symbol, score: 75 })
+			}
+			// Contains (lower score)
+			else if (lowerName.includes(lowerQuery)) {
+				results.push({ file, symbol, score: 50 })
+			}
+		}
+	}
+
+	// Sort by score descending, then by name
+	return results.sort((a, b) => {
+		if (b.score !== a.score) return b.score - a.score
+		return a.symbol.name.localeCompare(b.symbol.name)
+	})
+}
+
+/**
+ * Get all symbols in a file
+ *
+ * @param index - Project index
+ * @param filePath - File path (can be relative or absolute)
+ * @returns Array of symbols in the file
+ */
+export function getFileSymbols(
+	index: ProjectIndex,
+	filePath: string,
+): Symbol[] {
+	// Try exact match first
+	if (index.symbols[filePath]) {
+		return index.symbols[filePath]
+	}
+
+	// Try finding by filename (if relative path provided)
+	for (const [path, symbols] of Object.entries(index.symbols)) {
+		if (path.endsWith(filePath)) {
+			return symbols
+		}
+	}
+
+	return []
+}
+
+/**
+ * Get all files with their symbol counts
+ *
+ * @param index - Project index
+ * @returns Array of files with symbol counts
+ */
+export function getFileStats(
+	index: ProjectIndex,
+): Array<{ file: string; symbolCount: number }> {
+	const stats: Array<{ file: string; symbolCount: number }> = []
+
+	for (const [file, symbols] of Object.entries(index.symbols)) {
+		stats.push({ file, symbolCount: symbols.length })
+	}
+
+	// Sort by symbol count descending
+	return stats.sort((a, b) => b.symbolCount - a.symbolCount)
+}
+
+/**
+ * Get symbol distribution by type
+ *
+ * @param index - Project index
+ * @returns Record of symbol types to counts
+ */
+export function getSymbolTypeDistribution(
+	index: ProjectIndex,
+): Record<string, number> {
+	const distribution: Record<string, number> = {
+		function: 0,
+		class: 0,
+		interface: 0,
+		type: 0,
+		constant: 0,
+		variable: 0,
+	}
+
+	for (const symbols of Object.values(index.symbols)) {
+		for (const symbol of symbols) {
+			distribution[symbol.type] = (distribution[symbol.type] || 0) + 1
+		}
+	}
+
+	return distribution
+}
+
+/**
+ * Get all exported symbols (heuristic: uppercase or common export patterns)
+ *
+ * Note: Kit index doesn't have explicit "exported" flag, so we use naming conventions
+ *
+ * @param index - Project index
+ * @returns Array of likely exported symbols
+ */
+export function getExportedSymbols(
+	index: ProjectIndex,
+): Array<{ file: string; symbol: Symbol }> {
+	const exported: Array<{ file: string; symbol: Symbol }> = []
+
+	for (const [file, symbols] of Object.entries(index.symbols)) {
+		// Skip test files
+		if (file.includes('.test.') || file.includes('.spec.')) {
+			continue
+		}
+
+		for (const symbol of symbols) {
+			// Heuristic: likely exported if:
+			// 1. Starts with uppercase (classes, types, interfaces)
+			// 2. Exported by naming convention
+			const firstChar = symbol.name[0]
+			if (firstChar && firstChar === firstChar.toUpperCase()) {
+				exported.push({ file, symbol })
+			}
+		}
+	}
+
+	return exported
+}
+
+/**
+ * Group symbols by directory
+ *
+ * @param index - Project index
+ * @returns Record of directory paths to symbol counts
+ */
+export function groupSymbolsByDirectory(
+	index: ProjectIndex,
+): Record<string, number> {
+	const dirCounts: Record<string, number> = {}
+
+	for (const [file, symbols] of Object.entries(index.symbols)) {
+		const dir = dirname(file)
+		dirCounts[dir] = (dirCounts[dir] || 0) + symbols.length
+	}
+
+	return dirCounts
+}
+
+/**
+ * Get directory with most symbols (complexity hotspot)
+ *
+ * @param index - Project index
+ * @param topN - Number of top directories to return
+ * @returns Array of directories sorted by symbol count
+ */
+export function getComplexityHotspots(
+	index: ProjectIndex,
+	topN = 10,
+): Array<{ directory: string; symbolCount: number }> {
+	const dirCounts = groupSymbolsByDirectory(index)
+
+	const sorted = Object.entries(dirCounts)
+		.map(([directory, symbolCount]) => ({ directory, symbolCount }))
+		.sort((a, b) => b.symbolCount - a.symbolCount)
+
+	return sorted.slice(0, topN)
+}
+
+/**
+ * Get all symbols of a specific type
+ *
+ * @param index - Project index
+ * @param type - Symbol type to filter by
+ * @returns Array of matching symbols with file paths
+ */
+export function getSymbolsByType(
+	index: ProjectIndex,
+	type: Symbol['type'],
+): Array<{ file: string; symbol: Symbol }> {
+	const results: Array<{ file: string; symbol: Symbol }> = []
+
+	for (const [file, symbols] of Object.entries(index.symbols)) {
+		for (const symbol of symbols) {
+			if (symbol.type === type) {
+				results.push({ file, symbol })
+			}
+		}
+	}
+
+	return results
+}