@side-quest/kit 0.1.0 → 0.2.0

package/dist/lib/types.d.ts

@@ -0,0 +1,179 @@
+/**
+ * Kit Plugin Type Definitions
+ *
+ * Shared types for the Kit MCP server and CLI wrapper.
+ */
+/**
+ * Response format options for tool output.
+ */
+export declare enum ResponseFormat {
+    MARKDOWN = "markdown",
+    JSON = "json"
+}
+/**
+ * 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;
+}
+/**
+ * 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;
+}
+/**
+ * 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;
+}
+/**
+ * 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 declare function isError<T extends object>(result: KitResult<T>): result is ErrorResult;
+/** Environment variable name for configuring default path */
+export declare 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 declare function getDefaultKitPath(): string;
+/** Default timeout for grep operations (ms) */
+export declare const GREP_TIMEOUT = 30000;
+/** Default timeout for semantic operations (ms) */
+export declare const SEMANTIC_TIMEOUT = 60000;
+/** Default timeout for symbol usages operations (ms) */
+export declare const USAGES_TIMEOUT = 45000;
+/** Default max results for grep */
+export declare const DEFAULT_MAX_RESULTS = 100;
+/** Default top-k for semantic search */
+export declare const DEFAULT_TOP_K = 5;
+//# sourceMappingURL=types.d.ts.map

package/dist/lib/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/lib/types.ts"],"names":[],"mappings":"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"}

package/dist/lib/types.js

@@ -0,0 +1,48 @@
+/**
+ * Kit Plugin Type Definitions
+ *
+ * Shared types for the Kit MCP server and CLI wrapper.
+ */
+// ============================================================================
+// Response Format
+// ============================================================================
+/**
+ * Response format options for tool output.
+ */
+export var ResponseFormat;
+(function (ResponseFormat) {
+    ResponseFormat["MARKDOWN"] = "markdown";
+    ResponseFormat["JSON"] = "json";
+})(ResponseFormat || (ResponseFormat = {}));
+/**
+ * Type guard for error results.
+ */
+export function isError(result) {
+    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() {
+    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;
+//# sourceMappingURL=types.js.map

package/dist/lib/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/lib/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,+EAA+E;AAC/E,kBAAkB;AAClB,+EAA+E;AAE/E;;GAEG;AACH,MAAM,CAAN,IAAY,cAGX;AAHD,WAAY,cAAc;IACzB,uCAAqB,CAAA;IACrB,+BAAa,CAAA;AACd,CAAC,EAHW,cAAc,KAAd,cAAc,QAGzB;AA2KD;;GAEG;AACH,MAAM,UAAU,OAAO,CACtB,MAAoB;IAEpB,OAAO,OAAO,MAAM,KAAK,QAAQ,IAAI,MAAM,KAAK,IAAI,IAAI,OAAO,IAAI,MAAM,CAAA;AAC1E,CAAC;AAED,+EAA+E;AAC/E,wBAAwB;AACxB,+EAA+E;AAE/E,6DAA6D;AAC7D,MAAM,CAAC,MAAM,oBAAoB,GAAG,kBAAkB,CAAA;AAEtD;;;;;;GAMG;AACH,MAAM,UAAU,iBAAiB;IAChC,OAAO,OAAO,CAAC,GAAG,CAAC,oBAAoB,CAAC,IAAI,OAAO,CAAC,GAAG,EAAE,CAAA;AAC1D,CAAC;AAED,+CAA+C;AAC/C,MAAM,CAAC,MAAM,YAAY,GAAG,KAAK,CAAA;AAEjC,mDAAmD;AACnD,MAAM,CAAC,MAAM,gBAAgB,GAAG,KAAK,CAAA;AAErC,wDAAwD;AACxD,MAAM,CAAC,MAAM,cAAc,GAAG,KAAK,CAAA;AAEnC,mCAAmC;AACnC,MAAM,CAAC,MAAM,mBAAmB,GAAG,GAAG,CAAA;AAEtC,wCAAwC;AACxC,MAAM,CAAC,MAAM,aAAa,GAAG,CAAC,CAAA"}

package/dist/lib/utils/args.d.ts

@@ -0,0 +1,40 @@
+/**
+ * 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 declare function parseArgs(args: string[]): ParsedArgs;
+//# sourceMappingURL=args.d.ts.map

package/dist/lib/utils/args.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"args.d.ts","sourceRoot":"","sources":["../../../src/lib/utils/args.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH;;GAEG;AACH,MAAM,WAAW,UAAU;IAC1B,wDAAwD;IACxD,OAAO,EAAE,MAAM,CAAA;IACf,6CAA6C;IAC7C,UAAU,EAAE,MAAM,EAAE,CAAA;IACpB,iDAAiD;IACjD,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CAC7B;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,UAAU,CA+BpD"}

package/dist/lib/utils/args.js

@@ -0,0 +1,58 @@
+/**
+ * Command-line argument parsing utilities
+ *
+ * Adapted from cinema-bandit plugin's argument parsing pattern.
+ * Parses arguments in the format: <command> [positional] [--flag value]
+ */
+/**
+ * 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) {
+    const command = args[0] ?? '';
+    const positional = [];
+    const flags = {};
+    let i = 1;
+    while (i < args.length) {
+        const arg = args[i];
+        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 };
+}
+//# sourceMappingURL=args.js.map

package/dist/lib/utils/args.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"args.js","sourceRoot":"","sources":["../../../src/lib/utils/args.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAcH;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,UAAU,SAAS,CAAC,IAAc;IACvC,MAAM,OAAO,GAAG,IAAI,CAAC,CAAC,CAAC,IAAI,EAAE,CAAA;IAC7B,MAAM,UAAU,GAAa,EAAE,CAAA;IAC/B,MAAM,KAAK,GAA2B,EAAE,CAAA;IAExC,IAAI,CAAC,GAAG,CAAC,CAAA;IACT,OAAO,CAAC,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC;QACxB,MAAM,GAAG,GAAG,IAAI,CAAC,CAAC,CAAW,CAAA;QAE7B,IAAI,GAAG,CAAC,UAAU,CAAC,IAAI,CAAC,EAAE,CAAC;YAC1B,gCAAgC;YAChC,MAAM,GAAG,GAAG,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,CAAA;YACxB,MAAM,OAAO,GAAG,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,CAAA;YAE3B,0CAA0C;YAC1C,IAAI,OAAO,IAAI,CAAC,OAAO,CAAC,UAAU,CAAC,IAAI,CAAC,EAAE,CAAC;gBAC1C,KAAK,CAAC,GAAG,CAAC,GAAG,OAAO,CAAA;gBACpB,CAAC,IAAI,CAAC,CAAA;YACP,CAAC;iBAAM,CAAC;gBACP,0BAA0B;gBAC1B,KAAK,CAAC,GAAG,CAAC,GAAG,MAAM,CAAA;gBACnB,CAAC,EAAE,CAAA;YACJ,CAAC;QACF,CAAC;aAAM,CAAC;YACP,sBAAsB;YACtB,UAAU,CAAC,IAAI,CAAC,GAAG,CAAC,CAAA;YACpB,CAAC,EAAE,CAAA;QACJ,CAAC;IACF,CAAC;IAED,OAAO,EAAE,OAAO,EAAE,UAAU,EAAE,KAAK,EAAE,CAAA;AACtC,CAAC"}

package/dist/lib/utils/git.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Find the git repository root directory (async).
+ * @returns The git root path, or null if not in a git repo
+ */
+export declare function findGitRoot(): Promise<string | null>;
+/**
+ * Find the git repository root directory (synchronous).
+ * @returns The git root path, or undefined if not in a git repo
+ */
+export declare function findGitRootSync(): string | 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 declare function getTargetDir(customPath?: string): Promise<string>;
+/**
+ * Constants for index file management
+ */
+export declare const INDEX_FILE = "PROJECT_INDEX.json";
+export declare const MAX_AGE_HOURS = 24;
+//# sourceMappingURL=git.d.ts.map

package/dist/lib/utils/git.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"git.d.ts","sourceRoot":"","sources":["../../../src/lib/utils/git.ts"],"names":[],"mappings":"AAOA;;;GAGG;AACH,wBAAsB,WAAW,IAAI,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAgB1D;AAED;;;GAGG;AACH,wBAAgB,eAAe,IAAI,MAAM,GAAG,SAAS,CAMpD;AAED;;;;;GAKG;AACH,wBAAsB,YAAY,CAAC,UAAU,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAWvE;AAED;;GAEG;AACH,eAAO,MAAM,UAAU,uBAAuB,CAAA;AAC9C,eAAO,MAAM,aAAa,KAAK,CAAA"}

package/dist/lib/utils/git.js

@@ -0,0 +1,50 @@
+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() {
+    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() {
+    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) {
+    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;
+//# sourceMappingURL=git.js.map

package/dist/lib/utils/git.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"git.js","sourceRoot":"","sources":["../../../src/lib/utils/git.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAA;AACnC,OAAO,EACN,sBAAsB,EACtB,gBAAgB,EAChB,gBAAgB,GAChB,MAAM,wBAAwB,CAAA;AAE/B;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,WAAW;IAChC,MAAM,MAAM,GAAG,sBAAsB,CAAC,KAAK,CAAC,CAAA;IAC5C,MAAM,MAAM,GAAG,MAAM,gBAAgB,CACpC,CAAC,MAAM,EAAE,WAAW,EAAE,iBAAiB,CAAC,EACxC,MAAM,CACN,CAAA;IAED,IAAI,MAAM,CAAC,QAAQ,IAAI,MAAM,CAAC,QAAQ,KAAK,CAAC,EAAE,CAAC;QAC9C,OAAO,IAAI,CAAA;IACZ,CAAC;IAED,IAAI,MAAM,CAAC,MAAM,EAAE,CAAC;QACnB,OAAO,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,CAAA;IAC5B,CAAC;IAED,OAAO,IAAI,CAAA;AACZ,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,eAAe;IAC9B,MAAM,MAAM,GAAG,gBAAgB,CAAC,CAAC,KAAK,EAAE,WAAW,EAAE,iBAAiB,CAAC,CAAC,CAAA;IACxE,IAAI,MAAM,CAAC,QAAQ,KAAK,CAAC,IAAI,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,EAAE,CAAC;QACnD,OAAO,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,CAAA;IAC5B,CAAC;IACD,OAAO,SAAS,CAAA;AACjB,CAAC;AAED;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,YAAY,CAAC,UAAmB;IACrD,IAAI,UAAU,EAAE,CAAC;QAChB,OAAO,OAAO,CAAC,UAAU,CAAC,CAAA;IAC3B,CAAC;IAED,MAAM,OAAO,GAAG,MAAM,WAAW,EAAE,CAAA;IACnC,IAAI,OAAO,EAAE,CAAC;QACb,OAAO,OAAO,CAAA;IACf,CAAC;IAED,OAAO,OAAO,CAAC,GAAG,EAAE,CAAA;AACrB,CAAC;AAED;;GAEG;AACH,MAAM,CAAC,MAAM,UAAU,GAAG,oBAAoB,CAAA;AAC9C,MAAM,CAAC,MAAM,aAAa,GAAG,EAAE,CAAA"}

package/dist/lib/utils/index-parser.d.ts

@@ -0,0 +1,155 @@
+/**
+ * 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.
+ */
+/**
+ * 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 declare function findProjectIndex(startDir?: string): Promise<string>;
+/**
+ * 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 declare function resolveExplicitIndexPath(explicitPath: string): string;
+/**
+ * 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 declare function loadProjectIndex(explicitPath?: string): Promise<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 declare function findSymbol(index: ProjectIndex, symbolName: string): Array<{
+    file: string;
+    symbol: Symbol;
+}>;
+/**
+ * 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 declare function findSymbolFuzzy(index: ProjectIndex, query: string): Array<{
+    file: string;
+    symbol: Symbol;
+    score: number;
+}>;
+/**
+ * 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 declare function getFileSymbols(index: ProjectIndex, filePath: string): Symbol[];
+/**
+ * Get all files with their symbol counts
+ *
+ * @param index - Project index
+ * @returns Array of files with symbol counts
+ */
+export declare function getFileStats(index: ProjectIndex): Array<{
+    file: string;
+    symbolCount: number;
+}>;
+/**
+ * Get symbol distribution by type
+ *
+ * @param index - Project index
+ * @returns Record of symbol types to counts
+ */
+export declare function getSymbolTypeDistribution(index: ProjectIndex): Record<string, number>;
+/**
+ * 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 declare function getExportedSymbols(index: ProjectIndex): Array<{
+    file: string;
+    symbol: Symbol;
+}>;
+/**
+ * Group symbols by directory
+ *
+ * @param index - Project index
+ * @returns Record of directory paths to symbol counts
+ */
+export declare function groupSymbolsByDirectory(index: ProjectIndex): Record<string, number>;
+/**
+ * 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 declare function getComplexityHotspots(index: ProjectIndex, topN?: number): Array<{
+    directory: string;
+    symbolCount: number;
+}>;
+/**
+ * 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 declare function getSymbolsByType(index: ProjectIndex, type: Symbol['type']): Array<{
+    file: string;
+    symbol: Symbol;
+}>;
+//# sourceMappingURL=index-parser.d.ts.map

package/dist/lib/utils/index-parser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index-parser.d.ts","sourceRoot":"","sources":["../../../src/lib/utils/index-parser.ts"],"names":[],"mappings":"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"}