@yuaone/core 0.1.0

package/dist/codebase-context.d.ts

@@ -0,0 +1,396 @@
+/**
+ * @module codebase-context
+ * @description Codebase Context Engine — indexes TypeScript/JavaScript projects,
+ * extracts symbols, builds call graphs, and provides semantic search + blast radius analysis.
+ *
+ * Uses regex-based AST analysis (no ts-morph dependency). Designed for the YUAN coding agent
+ * to understand project structure before making changes.
+ */
+import type { ImportRef } from "./dependency-analyzer.js";
+import { LanguageSupport } from "./language-support.js";
+import type { SupportedLanguage } from "./language-support.js";
+/** Information about a function/method parameter. */
+export interface ParamInfo {
+    /** Parameter name */
+    name: string;
+    /** TypeScript type annotation */
+    type: string;
+    /** Whether the parameter is optional (has `?`) */
+    optional: boolean;
+    /** Default value expression, if any */
+    defaultValue?: string;
+}
+/** A symbol extracted from source code. */
+export interface SymbolInfo {
+    /** Symbol name */
+    name: string;
+    /** Symbol kind */
+    kind: "function" | "class" | "interface" | "type" | "enum" | "variable" | "method";
+    /** Absolute file path where the symbol is defined */
+    file: string;
+    /** Start line number (1-based) */
+    line: number;
+    /** End line number (1-based, estimated) */
+    endLine: number;
+    /** Parameters (for functions/methods) */
+    params?: ParamInfo[];
+    /** Return type annotation (for functions/methods) */
+    returnType?: string;
+    /** Superclass name (for classes) */
+    extends?: string;
+    /** Implemented interfaces (for classes) */
+    implements?: string[];
+    /** Members (for classes/interfaces) */
+    members?: SymbolInfo[];
+    /** Whether the symbol is exported */
+    exported: boolean;
+    /** Whether this is a default export */
+    isDefault: boolean;
+    /** Whether the function/method is async */
+    isAsync: boolean;
+    /** JSDoc comment, if present */
+    jsdoc?: string;
+}
+/** A directed edge in the call graph. */
+export interface CallEdge {
+    /** Caller identifier: "file:functionName" */
+    caller: string;
+    /** Callee identifier: "file:functionName" or "external:moduleName" */
+    callee: string;
+    /** Line number of the call site */
+    line: number;
+    /** Absolute file path containing the call */
+    file: string;
+}
+/** Complete analysis of a single source file. */
+export interface FileAnalysis {
+    /** Absolute file path */
+    file: string;
+    /** Detected language */
+    language: "typescript" | "javascript" | SupportedLanguage;
+    /** Symbols defined in this file */
+    symbols: SymbolInfo[];
+    /** Import references */
+    imports: ImportRef[];
+    /** Exported symbol names */
+    exports: string[];
+    /** Call edges originating from this file */
+    callEdges: CallEdge[];
+    /** Complexity metrics */
+    complexity: {
+        /** Cyclomatic complexity estimate */
+        cyclomatic: number;
+        /** Cognitive complexity (nesting-aware) */
+        cognitive: number;
+        /** Lines of code (non-blank, non-comment) */
+        loc: number;
+        /** Blank line count */
+        blankLines: number;
+        /** Comment line count */
+        commentLines: number;
+        /** Number of import dependencies */
+        dependencies: number;
+    };
+}
+/** Full codebase index — the primary data structure. */
+export interface CodebaseIndex {
+    /** Per-file analysis results */
+    files: Map<string, FileAnalysis>;
+    /** Symbol name → all matching SymbolInfo across the codebase */
+    symbolTable: Map<string, SymbolInfo[]>;
+    /** All call edges across the codebase */
+    callGraph: CallEdge[];
+    /** Epoch ms when the index was last built */
+    lastIndexedAt: number;
+    /** Total number of indexed files */
+    totalFiles: number;
+    /** Total number of extracted symbols */
+    totalSymbols: number;
+}
+/** A search result from semantic symbol search. */
+export interface SemanticSearchResult {
+    /** Matched symbol */
+    symbol: SymbolInfo;
+    /** File containing the symbol */
+    file: string;
+    /** Relevance score (0–1) */
+    relevance: number;
+    /** Code snippet around the symbol */
+    snippet: string;
+}
+/** Blast radius analysis for a file change. */
+export interface BlastRadiusResult {
+    /** Files that directly import the changed file */
+    directDependents: string[];
+    /** Files transitively affected */
+    transitiveDependents: string[];
+    /** Test files that may be affected */
+    affectedTests: string[];
+    /** Exported symbols from the changed file */
+    affectedExports: string[];
+    /** Overall risk assessment */
+    riskLevel: "low" | "medium" | "high";
+}
+/**
+ * Codebase Context Engine — indexes TypeScript/JavaScript projects and provides
+ * symbol lookup, call graph analysis, blast radius estimation, and semantic search.
+ *
+ * @example
+ * ```typescript
+ * const ctx = new CodebaseContext("/path/to/project");
+ * await ctx.buildIndex();
+ *
+ * const symbols = ctx.findSymbol("handleRequest");
+ * const blast = ctx.getBlastRadius("/path/to/project/src/router.ts");
+ * const results = ctx.searchSymbols("auth middleware", 5);
+ * ```
+ */
+export declare class CodebaseContext {
+    private index;
+    private projectPath;
+    /** Cached file contents for snippet extraction */
+    private fileContents;
+    /** Reverse dependency map (file → files that import it) */
+    private reverseDepMap;
+    /** Optional multi-language support for non-TS/JS files */
+    private languageSupport;
+    constructor(projectPath: string, languageSupport?: LanguageSupport);
+    /**
+     * Build a full index of the project. Scans all source files,
+     * extracts symbols, builds call graph, and creates the symbol table.
+     *
+     * @returns The complete codebase index
+     */
+    buildIndex(): Promise<CodebaseIndex>;
+    /**
+     * Incrementally update the index for a single changed file.
+     * Re-analyzes only that file and updates the symbol table.
+     *
+     * @param filePath - Absolute path of the changed file
+     */
+    updateFile(filePath: string): Promise<void>;
+    /**
+     * Remove a file from the index (e.g., after deletion).
+     *
+     * @param filePath - Absolute path of the removed file
+     */
+    removeFile(filePath: string): void;
+    /**
+     * Find all symbols matching the given name across the codebase.
+     *
+     * @param name - Symbol name to search for (exact match)
+     * @returns Array of matching SymbolInfo
+     */
+    findSymbol(name: string): SymbolInfo[];
+    /**
+     * Find the symbol defined at a specific file and line.
+     *
+     * @param file - Absolute file path
+     * @param line - Line number (1-based)
+     * @returns The symbol at that location, or undefined
+     */
+    findSymbolAt(file: string, line: number): SymbolInfo | undefined;
+    /**
+     * Find all symbols of a given kind across the codebase.
+     *
+     * @param kind - Symbol kind to filter by
+     * @returns Array of matching SymbolInfo
+     */
+    findSymbolsByKind(kind: SymbolInfo["kind"]): SymbolInfo[];
+    /**
+     * Find all exported symbols in a specific file.
+     *
+     * @param file - Absolute file path
+     * @returns Array of exported SymbolInfo
+     */
+    findExportedSymbols(file: string): SymbolInfo[];
+    /**
+     * Get all call edges where the given symbol is the callee.
+     *
+     * @param symbolName - Name of the called function/method
+     * @param file - Optional file path to narrow the search
+     * @returns Call edges targeting this symbol
+     */
+    getCallersOf(symbolName: string, file?: string): CallEdge[];
+    /**
+     * Get all call edges originating from the given symbol.
+     *
+     * @param symbolName - Name of the calling function/method
+     * @param file - Optional file path to narrow the search
+     * @returns Call edges originating from this symbol
+     */
+    getCalleesOf(symbolName: string, file?: string): CallEdge[];
+    /**
+     * Calculate the blast radius of changing a file — which files are affected,
+     * which tests may break, and what's the risk level.
+     *
+     * @param file - Absolute file path being changed
+     * @returns Blast radius analysis
+     */
+    getBlastRadius(file: string): BlastRadiusResult;
+    /**
+     * Search symbols by a query string using token-based fuzzy matching.
+     * Splits the query into tokens and scores symbols by match count against
+     * name, kind, file path, and JSDoc.
+     *
+     * @param query - Search query (space-separated tokens)
+     * @param limit - Maximum results to return (default 10)
+     * @returns Ranked search results with relevance scores
+     */
+    searchSymbols(query: string, limit?: number): SemanticSearchResult[];
+    /**
+     * Search for symbols whose return type or type annotation matches a pattern.
+     *
+     * @param typePattern - Regex pattern to match against types
+     * @returns Matching symbols
+     */
+    searchByType(typePattern: string): SymbolInfo[];
+    /**
+     * Get the analysis for a specific file.
+     *
+     * @param file - Absolute file path
+     * @returns FileAnalysis or undefined if not indexed
+     */
+    getFileAnalysis(file: string): FileAnalysis | undefined;
+    /**
+     * Get files exceeding a cyclomatic complexity threshold.
+     *
+     * @param threshold - Minimum cyclomatic complexity (default 20)
+     * @returns Files exceeding the threshold, sorted by complexity descending
+     */
+    getComplexFiles(threshold?: number): FileAnalysis[];
+    /**
+     * Identify hotspots — files with high complexity AND many dependents.
+     *
+     * @returns Hotspot entries sorted by combined score descending
+     */
+    getHotspots(): {
+        file: string;
+        complexity: number;
+        dependencies: number;
+    }[];
+    /**
+     * Get summary statistics for the indexed codebase.
+     *
+     * @returns Aggregate stats
+     */
+    getStats(): {
+        totalFiles: number;
+        totalSymbols: number;
+        avgComplexity: number;
+    };
+    /**
+     * Recursively collect all source files under a directory,
+     * skipping excluded directories.
+     */
+    private collectSourceFiles;
+    /**
+     * Check if a file is a supported source file.
+     * Uses LanguageSupport for multi-language detection when available,
+     * otherwise falls back to built-in TS/JS extensions.
+     */
+    private isSupportedSourceFile;
+    /**
+     * Analyze a single source file — extract symbols, imports, exports,
+     * and compute complexity metrics.
+     *
+     * When LanguageSupport is available and the file is not TS/JS,
+     * uses language-specific patterns for symbol extraction.
+     */
+    private analyzeFile;
+    /**
+     * Extract all symbol definitions from file content using regex patterns.
+     */
+    private extractSymbols;
+    /**
+     * Extract symbols from non-TS/JS files using LanguageSupport patterns.
+     * Provides basic function and class extraction for any language
+     * that LanguageSupport has patterns for.
+     *
+     * Falls back to an empty array if patterns produce no matches — this is
+     * safe because the caller only reaches here for non-TS/JS files.
+     */
+    private extractSymbolsWithLanguageSupport;
+    /**
+     * Extract class method members from a class body.
+     */
+    private extractClassMembers;
+    /**
+     * Extract import references from file content.
+     */
+    private extractImports;
+    /**
+     * Extract exported symbol names from file content.
+     */
+    private extractExports;
+    /**
+     * Extract call edges from function bodies.
+     * Maps each function's body to the functions it calls.
+     */
+    private extractCallEdges;
+    /**
+     * Compute complexity metrics for file content.
+     */
+    private computeComplexity;
+    /**
+     * Compute cognitive complexity — increments with nesting depth.
+     */
+    private computeCognitiveComplexity;
+    /**
+     * Build the symbol table from all file analyses.
+     * Maps symbol name → all SymbolInfo across the codebase.
+     */
+    private buildSymbolTable;
+    /**
+     * Build the global call graph from per-file call edges.
+     */
+    private buildCallGraph;
+    /**
+     * Build the reverse dependency map (file → files that import it).
+     * Resolves relative import paths to absolute file paths.
+     */
+    private buildReverseDependencyMap;
+    /**
+     * Resolve a relative import specifier to an absolute file path.
+     */
+    private resolveImportPath;
+    /**
+     * Get 1-based line number for a character offset within content.
+     */
+    private getLineNumber;
+    /**
+     * Estimate the end line of a function/arrow function by scanning for matching braces.
+     */
+    private estimateEndLine;
+    /**
+     * Estimate the end line of a brace-delimited block (class, function, enum, interface).
+     * Tracks `{` and `}` to find the matching close brace.
+     */
+    private estimateBlockEnd;
+    /**
+     * Estimate the end line of a type alias (ends with `;` at depth 0).
+     */
+    private estimateTypeEnd;
+    /**
+     * Parse a raw parameter string into ParamInfo array.
+     * Handles `name: Type`, `name?: Type`, `name = defaultVal`.
+     */
+    private parseParams;
+    /**
+     * Split parameter string by commas, respecting nested angle brackets and parentheses.
+     */
+    private splitParams;
+    /**
+     * Clean a JSDoc comment — strip leading `*` and `/** ... * /`.
+     */
+    private cleanJsdoc;
+    /**
+     * Score a symbol against search tokens for relevance ranking.
+     */
+    private scoreSymbol;
+    /**
+     * Get a code snippet around a symbol for search result display.
+     */
+    private getSnippet;
+}
+//# sourceMappingURL=codebase-context.d.ts.map

package/dist/codebase-context.d.ts.map

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