@fraziym/axoniz 0.1.0

package/dist/core/intelligence/ast_index.d.ts

@@ -0,0 +1,255 @@
+/**
+ * axoniz.core.intelligence.ast_index
+ * =====================================
+ * Phase 3 — Living Codebase Understanding
+ *
+ * Cursor and Copilot do text search. They're glorified grep.
+ * axoniz builds a real AST index of your entire workspace:
+ *   - Every class, function, method, variable
+ *   - Every import and what imports what
+ *   - Every call site (who calls what)
+ *   - Symbol cross-references
+ *   - "What will break if I change X?"
+ *
+ * Before editing anything, axoniz knows what will break.
+ * After editing, it compares semantic meaning, not just text.
+ *
+ * Storage: SQLite at ~/.axoniz/ast_indexes/ast_<hash>.db (per workspace)
+ * Incremental: only re-indexes changed files (mtime-based)
+ *
+ * ────────────────────────────────────────────────────────────────────────────
+ * PORT DESIGN DECISION — how Python's `ast` module was replaced
+ * ────────────────────────────────────────────────────────────────────────────
+ * Python parsed source with `ast.parse()` and an `ast.NodeVisitor`. Node has no
+ * built-in parser and the brief forbids adding a parser dependency
+ * (`typescript` is a devDependency and must not be imported from `src/`), so
+ * this module ships a **heuristic symbol/relationship extractor** that produces
+ * the *same output shape*: the same `symbols` / `imports` / `calls` tables, the
+ * same `Symbol` / `CallSite` / `ImpactAnalysis` objects and the same query
+ * results.
+ *
+ *   • Python files use an indentation-driven scanner (`class` / `def` / `async
+ *     def` / `import` / `from ... import` / module- and class-level
+ *     assignments / dotted call chains).
+ *   • TypeScript/JavaScript files use a brace-driven scanner (classes,
+ *     interfaces/type/enum, function declarations, arrow & function
+ *     expressions, class methods, ESM/CJS imports, call chains). Python's
+ *     indexer only globbed `.py`; the port indexes TS/JS as well because the
+ *     ported codebase *is* TypeScript — without it the index would be empty and
+ *     `impact_analysis` useless. `_find_python_files()` is kept for callers that
+ *     want the original `.py`-only behaviour.
+ *
+ * Fidelity that is LOST versus `ast`:
+ *   1. No true parse tree. Anything that needs real syntax resolution is
+ *      approximate: multi-line call argument lists are under-counted
+ *      (`args_count`), calls hidden inside f-strings/comprehensions may be
+ *      missed, and decorators are attributed to the decorated definition's line
+ *      (Python reported the `def` line too, so this matches).
+ *   2. `def`/`class` body extents (`line_end`) come from indentation (Python) or
+ *      brace matching (TS) rather than `node.end_lineno`.
+ *   3. Docstrings are detected only when the first statement of a body is a
+ *      string literal; `inspect.cleandoc` de-denting is approximated.
+ *   4. `parent` attribution uses the innermost enclosing class found by
+ *      indentation/braces; Python used the visitor's `_current_class`.
+ *   5. TypeScript `interface` / `type` / `enum` declarations are recorded with
+ *      kind `"class"` so the `by_kind` histogram keeps exactly Python's kind set
+ *      (class/function/method/variable).
+ *   6. The `symbol_refs` table is created, per-file cleared and indexed but left
+ *      unpopulated — exactly as in `ast_index.py` (its `_ASTVisitor` never
+ *      appended to `symbol_refs`).
+ *
+ * `index_workspace()` stays synchronous so its callers (the `ast_reindex` tool,
+ * `_t_reindex`) keep returning a value rather than a Promise. Background use
+ * goes through `index_workspace_async()`, which drives the same work in bounded
+ * batches and yields to the event loop between them.
+ */
+export declare const AST_INDEX_DIR: string;
+/** Extension → language label written into `files.language`. */
+export declare const INDEX_EXTENSIONS: Record<string, string>;
+export interface SymbolInit {
+    name: string;
+    kind: string;
+    file_path: string;
+    line: number;
+    signature?: string;
+    docstring?: string;
+    parent?: string;
+}
+export declare class Symbol {
+    name: string;
+    kind: string;
+    file_path: string;
+    line: number;
+    signature: string;
+    docstring: string;
+    parent: string;
+    constructor(init: SymbolInit | string, kind?: string, file_path?: string, line?: number, signature?: string, docstring?: string, parent?: string);
+    get filePath(): string;
+}
+export interface CallSiteInit {
+    file_path: string;
+    caller: string;
+    callee: string;
+    line: number;
+}
+export declare class CallSite {
+    file_path: string;
+    caller: string;
+    callee: string;
+    line: number;
+    constructor(init: CallSiteInit | string, caller?: string, callee?: string, line?: number);
+    get filePath(): string;
+}
+export interface ImpactAnalysisInit {
+    symbol: string;
+    direct_calls: CallSite[];
+    affected_files: string[];
+    risk_level: string;
+    summary: string;
+}
+export declare class ImpactAnalysis {
+    symbol: string;
+    direct_calls: CallSite[];
+    affected_files: string[];
+    risk_level: string;
+    summary: string;
+    constructor(init: ImpactAnalysisInit);
+    get directCalls(): CallSite[];
+    get affectedFiles(): string[];
+    get riskLevel(): string;
+}
+export interface IndexStats {
+    files_indexed: number;
+    files_new: number;
+    files_changed: number;
+    files_skipped: number;
+    total: number;
+}
+export interface AstStats {
+    files_indexed: number;
+    symbols: number;
+    calls: number;
+    imports: number;
+    by_kind: Record<string, number>;
+}
+export interface ExtractedSymbol {
+    name: string;
+    kind: string;
+    line: number;
+    line_end: number;
+    parent: string;
+    signature: string;
+    docstring: string;
+}
+export interface ExtractedImport {
+    module: string;
+    names: string[];
+    alias: string;
+    line: number;
+    is_from: boolean;
+}
+export interface ExtractedCall {
+    caller: string;
+    callee: string;
+    line: number;
+    args_count: number;
+}
+export interface Extraction {
+    symbols: ExtractedSymbol[];
+    imports: ExtractedImport[];
+    calls: ExtractedCall[];
+}
+/**
+ * Builds and queries a real AST index of a workspace.
+ *
+ * The key capability:
+ *     "Before you edit function X, here's everything that calls it,
+ *      everything it imports, and what will break."
+ */
+export declare class ASTIndexer {
+    workspace: string;
+    private readonly _conn;
+    /** Python kept a `_index_thread`; Node keeps the in-flight background promise. */
+    _index_task: Promise<void> | null;
+    constructor(workspace: string);
+    _init_schema(): void;
+    /**
+     * Index all source files in the workspace. Only re-indexes changed files.
+     * Returns stats dict.
+     *
+     * Synchronous on purpose: it is driven by the `ast_reindex` tool, which
+     * returns a string. Use `index_workspace_async()` for background indexing.
+     */
+    index_workspace(max_files?: number, force?: boolean): IndexStats;
+    /** camelCase alias. */
+    indexWorkspace(max_files?: number, force?: boolean): IndexStats;
+    /**
+     * Background indexing — doesn't block the agent.
+     * Bounded-concurrency batches with an event-loop yield between them, which is
+     * the async analogue of Python's `threading.Thread(target=..., daemon=True)`.
+     */
+    index_workspace_async(): void;
+    /** camelCase alias. */
+    indexWorkspaceAsyncStart(): void;
+    /** Awaitable form of the background indexer. */
+    indexWorkspaceAsync(max_files?: number, force?: boolean): Promise<IndexStats>;
+    private _index_workspace_pooled;
+    /** Python's `.py`-only discovery, kept for API compatibility. */
+    _find_python_files(max_files: number): string[];
+    /** All indexable source files (Python behaviour → .py; port adds TS/JS). */
+    _find_source_files(max_files: number): string[];
+    private _find_files;
+    /** Parse one source file and update all tables. */
+    _index_file(fpath: string, mtime: number): void;
+    /** Find where a class/function/variable is defined. */
+    find_symbol(name: string, kind?: string | null): Symbol[];
+    /** Find all places that call a function — "who calls X?" */
+    find_callers(function_name: string): CallSite[];
+    /** Where is a symbol used? Combines calls + imports. */
+    find_usages(symbol_name: string): Array<Record<string, unknown>>;
+    /** Which files import a given module? */
+    what_imports(module_name: string): string[];
+    /**
+     * Before editing symbol_name, what will break?
+     * Returns an ImpactAnalysis with call sites, affected files, risk level.
+     */
+    impact_analysis(symbol_name: string): ImpactAnalysis;
+    /** camelCase alias. */
+    impactAnalysis(symbol_name: string): ImpactAnalysis;
+    /**
+     * Before editing a file, get full context:
+     * what's defined, what's imported, what calls what.
+     */
+    get_file_context(file_path: string): string;
+    /** camelCase alias. */
+    getFileContext(file_path: string): string;
+    /** Index statistics. */
+    stats(): AstStats;
+    /** Format impact analysis as a readable string for the agent. */
+    format_impact(ia: ImpactAnalysis, max_callers?: number): string;
+    /** camelCase alias. */
+    formatImpact(ia: ImpactAnalysis, max_callers?: number): string;
+    /**
+     * One-line summary for swarm orchestrator context injection.
+     *
+     * Byte-identical to Python on a Python-only workspace. When the index also
+     * covers TypeScript/JavaScript (the port indexes those extensions) the
+     * language word becomes "code" rather than claiming everything is Python.
+     */
+    summary(): string;
+    /** Inject AST tools into agent._tool_map. */
+    as_tool_map(): Record<string, (...args: unknown[]) => string>;
+    /** camelCase alias. */
+    asToolMap(): Record<string, (...args: unknown[]) => string>;
+    _t_find_symbol(name: string, kind?: string | null): string;
+    _t_find_callers(function_name: string): string;
+    _t_impact(symbol_name: string): string;
+    _t_file_context(p: string): string;
+    _t_stats(): string;
+    _t_reindex(force?: boolean): string;
+    /** Close the underlying handle. */
+    close(): void;
+}
+/** Exported for tests/debugging: the raw heuristic extractor. */
+export declare function _extract_symbols(source: string, language?: string): Extraction;
+//# sourceMappingURL=ast_index.d.ts.map

package/dist/core/intelligence/ast_index.d.ts.map

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