@aroman22/codegraph-vba 1.3.3

package/dist/errors.d.ts

@@ -0,0 +1,136 @@
+/**
+ * CodeGraph Error Classes
+ *
+ * Custom error types for better error handling and debugging.
+ *
+ * @module errors
+ *
+ * @example
+ * ```typescript
+ * import { FileError, ParseError, setLogger, silentLogger } from 'codegraph';
+ *
+ * // Catch specific error types
+ * try {
+ *   await cg.indexAll();
+ * } catch (error) {
+ *   if (error instanceof FileError) {
+ *     console.log(`File error at ${error.filePath}: ${error.message}`);
+ *   } else if (error instanceof ParseError) {
+ *     console.log(`Parse error at ${error.filePath}:${error.line}`);
+ *   }
+ * }
+ *
+ * // Disable logging for tests
+ * setLogger(silentLogger);
+ * ```
+ */
+/**
+ * Base error class for all CodeGraph errors.
+ *
+ * All CodeGraph-specific errors extend this class, allowing you to catch
+ * all CodeGraph errors with a single catch block.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await cg.indexAll();
+ * } catch (error) {
+ *   if (error instanceof CodeGraphError) {
+ *     console.log(`CodeGraph error [${error.code}]: ${error.message}`);
+ *   }
+ * }
+ * ```
+ */
+export declare class CodeGraphError extends Error {
+    /** Error code for categorization (e.g., 'FILE_ERROR', 'PARSE_ERROR') */
+    readonly code: string;
+    /** Additional context about the error */
+    readonly context?: Record<string, unknown>;
+    constructor(message: string, code: string, context?: Record<string, unknown>);
+}
+/**
+ * Error reading or accessing files
+ */
+export declare class FileError extends CodeGraphError {
+    readonly filePath: string;
+    constructor(message: string, filePath: string, cause?: Error);
+}
+/**
+ * Error parsing source code
+ */
+export declare class ParseError extends CodeGraphError {
+    readonly filePath: string;
+    readonly line?: number;
+    readonly column?: number;
+    constructor(message: string, filePath: string, options?: {
+        line?: number;
+        column?: number;
+        cause?: Error;
+    });
+}
+/**
+ * Error with database operations
+ */
+export declare class DatabaseError extends CodeGraphError {
+    readonly operation: string;
+    constructor(message: string, operation: string, cause?: Error);
+}
+/**
+ * Error with search operations
+ */
+export declare class SearchError extends CodeGraphError {
+    readonly query: string;
+    constructor(message: string, query: string, cause?: Error);
+}
+/**
+ * Error with vector/embedding operations
+ */
+export declare class VectorError extends CodeGraphError {
+    constructor(message: string, operation: string, cause?: Error);
+}
+/**
+ * Error with configuration
+ */
+export declare class ConfigError extends CodeGraphError {
+    constructor(message: string, details?: Record<string, unknown>);
+}
+/**
+ * Simple logger for CodeGraph operations
+ *
+ * By default, logs to console.warn for warnings and console.error for errors.
+ * Can be configured to use custom logging.
+ */
+export interface Logger {
+    debug(message: string, context?: Record<string, unknown>): void;
+    warn(message: string, context?: Record<string, unknown>): void;
+    error(message: string, context?: Record<string, unknown>): void;
+}
+/**
+ * Default console-based logger
+ */
+export declare const defaultLogger: Logger;
+/**
+ * Silent logger (no output) - useful for tests
+ */
+export declare const silentLogger: Logger;
+/**
+ * Set the global logger
+ */
+export declare function setLogger(logger: Logger): void;
+/**
+ * Get the current logger
+ */
+export declare function getLogger(): Logger;
+/**
+ * Log a debug message
+ */
+export declare function logDebug(message: string, context?: Record<string, unknown>): void;
+/**
+ * Log a warning message
+ */
+export declare function logWarn(message: string, context?: Record<string, unknown>): void;
+/**
+ * Log an error message
+ */
+export declare function logError(message: string, context?: Record<string, unknown>): void;
+//# sourceMappingURL=errors.d.ts.map

package/dist/extraction/astro-extractor.d.ts

@@ -0,0 +1,79 @@
+import { ExtractionResult } from '../types';
+/**
+ * AstroExtractor - Extracts code relationships from Astro component files
+ *
+ * Astro files are multi-language: a TypeScript frontmatter block fenced by
+ * `---` lines, a JSX-like HTML template, and optional <script>/<style> blocks.
+ * Rather than parsing a full Astro grammar, we extract the frontmatter and
+ * <script> contents and delegate them to the TypeScript TreeSitterExtractor
+ * (Astro processes both as TypeScript by default — no `lang` attr needed).
+ *
+ * Also extracts function calls from template expressions (`{fn(...)}`) and
+ * component usages (`<PascalCase>`) so cross-file edges are captured even
+ * when the only reference lives in markup.
+ *
+ * Every .astro file produces a component node (Astro components are always
+ * importable).
+ */
+export declare class AstroExtractor {
+    private filePath;
+    private source;
+    private nodes;
+    private edges;
+    private unresolvedReferences;
+    private errors;
+    constructor(filePath: string, source: string);
+    /**
+     * Extract from Astro source
+     */
+    extract(): ExtractionResult;
+    /**
+     * Create a component node for the .astro file
+     */
+    private createComponentNode;
+    /**
+     * Extract the frontmatter block: the content between the opening `---`
+     * fence (first non-blank line of the file) and the closing `---` fence.
+     * An unclosed fence is treated as "no frontmatter" rather than swallowing
+     * the whole template as TypeScript.
+     *
+     * Returns the content plus its 0-indexed start line, or null.
+     */
+    private extractFrontmatter;
+    /**
+     * Extract <script> blocks from the template portion
+     */
+    private extractScriptBlocks;
+    /**
+     * Process frontmatter / script content by delegating to TreeSitterExtractor.
+     * Astro treats both as TypeScript by default.
+     */
+    private processScriptContent;
+    /**
+     * Line ranges (0-indexed, inclusive) the template scans must skip:
+     * the frontmatter block and <script>/<style> blocks.
+     */
+    private getCoveredRanges;
+    /**
+     * Extract function calls from Astro template expressions.
+     *
+     * Astro templates embed JSX-like expressions (`{formatDate(post.date)}`,
+     * `class:list={cn(...)}`), so calls frequently live in markup rather than
+     * the frontmatter. We scan template lines for `{expression}` groups and
+     * extract call patterns from them. A `{` group left open at end-of-line
+     * (the pervasive `{posts.map((post) => (` pattern) contributes the calls
+     * on its opening line.
+     */
+    private extractTemplateCalls;
+    /**
+     * Extract component usages from the Astro template.
+     *
+     * PascalCase tags like <Layout>, <PostCard /> represent component
+     * instantiations — analogous to function calls in imperative code.
+     * Lowercase tags are native HTML (Astro does not register kebab-case
+     * components the way Vue does, so those are real custom elements and
+     * are skipped).
+     */
+    private extractTemplateComponents;
+}
+//# sourceMappingURL=astro-extractor.d.ts.map

package/dist/extraction/dfm-extractor.d.ts

@@ -0,0 +1,31 @@
+import { ExtractionResult } from '../types';
+/**
+ * Custom extractor for Delphi DFM/FMX form files.
+ *
+ * DFM/FMX files describe the visual component hierarchy and event handler
+ * bindings. They use a simple text format (object/end blocks) that we parse
+ * with regex — no tree-sitter grammar exists for this format.
+ *
+ * Extracted information:
+ * - Components as NodeKind `component`
+ * - Nesting as EdgeKind `contains`
+ * - Event handlers (OnClick = MethodName) as UnresolvedReference → EdgeKind `references`
+ */
+export declare class DfmExtractor {
+    private filePath;
+    private source;
+    private nodes;
+    private edges;
+    private unresolvedReferences;
+    private errors;
+    constructor(filePath: string, source: string);
+    /**
+     * Extract components and event handler references from DFM/FMX source
+     */
+    extract(): ExtractionResult;
+    /** Create a file node for the DFM form file */
+    private createFileNode;
+    /** Parse object/end blocks and extract components + event handlers */
+    private parseComponents;
+}
+//# sourceMappingURL=dfm-extractor.d.ts.map

package/dist/extraction/extraction-version.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Extraction version
+ *
+ * A monotonically-increasing integer that identifies the *shape and depth* of
+ * what the extractor writes into the graph. Unlike `CURRENT_SCHEMA_VERSION`
+ * (which tracks the SQLite table layout and is migrated in place), this tracks
+ * the EXTRACTED CONTENT — node kinds, edges, synthesizers, resolver coverage.
+ *
+ * When an index was built by an older engine whose `EXTRACTION_VERSION` is
+ * below the running engine's, the data on disk is structurally fine but
+ * *stale*: it's missing whatever a newer extractor would now produce. A schema
+ * migration can't backfill that — only a re-index can. So this is the signal
+ * `codegraph status` uses to recommend a re-index, and the reason `codegraph
+ * upgrade` reminds users to refresh their projects.
+ *
+ * BUMP THIS when a release changes extraction output enough that existing
+ * indexes should be rebuilt to benefit — e.g. a new language/framework
+ * extractor, a new dynamic-dispatch synthesizer, a new node/edge kind, or a
+ * resolver fix that materially changes which edges exist. Do NOT bump for
+ * pure bug fixes, CLI/UX changes, or schema-only migrations. Over-bumping
+ * turns the re-index hint into noise — keep it honest (see CLAUDE.md, "Honesty
+ * in the product is load-bearing").
+ */
+export declare const EXTRACTION_VERSION = 24;
+//# sourceMappingURL=extraction-version.d.ts.map

package/dist/extraction/function-ref.d.ts

@@ -0,0 +1,118 @@
+/**
+ * Function-as-value capture (#756) — registration-linking for callbacks.
+ *
+ * A function name used as a VALUE — passed as a call argument
+ * (`register_handler(target_cb)`, `signal(SIGINT, handler)`), assigned to a
+ * field or function pointer (`o->cb = target_cb`, `OnFire := TargetCb`),
+ * placed in a struct/object initializer (`{ .recv_cb = my_cb }`,
+ * `{ recv: targetCb }`, `Ops{Cb: targetCb}`), or listed in a function table
+ * (`static cb_t table[] = { cb_a, cb_b }`) — is a real dependency that static
+ * call extraction misses entirely: `callers(target_cb)` showed nothing but
+ * direct calls, so every callback looked dead and its registration sites were
+ * invisible to impact analysis.
+ *
+ * This module captures those value positions during the AST walk as
+ * `function_ref` candidates. Capture is table-driven per language (the value
+ * positions and wrapper forms differ per grammar — `&fn` in C, `Main::fn` in
+ * Java, `::fn` in Kotlin, `#selector(fn)` in Swift, `@TargetCb` in Pascal,
+ * `method(:fn)` in Ruby). Candidates are GATED at end-of-file extraction
+ * (see `TreeSitterExtractor.flushFnRefCandidates`): only names matching a
+ * same-file function/method or an imported binding survive, which bounds
+ * volume and keeps precision high. Resolution then matches survivors against
+ * function/method nodes ONLY (`matchFunctionRef` in
+ * `src/resolution/name-matcher.ts`) and persists them as `references` edges,
+ * which `callers`/`impact` already traverse.
+ *
+ * Deliberately NOT covered (resolving the *dispatch* — `o->cb(x)` → the
+ * registered function — needs data-flow through struct fields; a wrong edge
+ * is worse than none): indirect-call resolution and `obj.method` member
+ * values where `obj` isn't `this`/`self` (the receiver's type is statically
+ * unknowable without local data-flow).
+ */
+import type { Node as SyntaxNode } from 'web-tree-sitter';
+export interface FnRefCandidate {
+    name: string;
+    line: number;
+    column: number;
+    /** Which capture position produced this candidate (gate policy keys on it). */
+    mode: CaptureMode;
+    /**
+     * True when the value was an explicit reference form (`&fn`, `&Cls::m`,
+     * `::fn`, `#selector`, `method(:sym)`) rather than a bare identifier —
+     * C++'s flush policy keys on it.
+     */
+    explicitRef: boolean;
+    /**
+     * Skip the same-file/import name gate for this candidate. Set for PHP
+     * string callables in known HOF positions: PHP global functions are
+     * referenced cross-file WITHOUT imports (global namespace), so the gate
+     * can't see them — the strong positional prior (a string argument to
+     * `usort`/`array_map`/…) plus resolution's unique-or-drop rule carry the
+     * precision instead.
+     */
+    skipGate?: boolean;
+}
+/** How to pull candidate value nodes out of a dispatched container node. */
+type CaptureMode = 'args' | 'rhs' | 'value' | 'list' | 'varinit';
+interface CaptureRule {
+    mode: CaptureMode;
+    /** Field holding the value for rhs/value/varinit (defaults per mode). */
+    field?: string;
+}
+export interface FnRefSpec {
+    /** Bare identifier node types that can act as a function value. */
+    idTypes: Set<string>;
+    /** Container node type → how to extract candidate values from it. */
+    dispatch: Map<string, CaptureRule>;
+    /**
+     * Transparent wrapper layers between a container and its values
+     * (`argument`, `value_argument`, `literal_element`, `expression_list`…).
+     * Value: the field to descend into, or null for "named children".
+     * `expression_list` fans out to ALL named children (Go multi-assign).
+     */
+    layers?: Map<string, string | null>;
+    /**
+     * Unary wrappers whose operand is the function value — C/C++ `&fn`
+     * (pointer_expression), Pascal `@Fn` (exprUnary), Scala eta `fn _`
+     * (postfix_expression). Value: operand field, or null for first named child.
+     */
+    unwrap?: Map<string, string | null>;
+    /**
+     * Whole-node reference forms needing bespoke name extraction —
+     * `method_reference` (Java), `callable_reference` / `navigation_expression`
+     * (Kotlin), `selector_expression` (Swift `#selector` / ObjC `@selector`),
+     * Ruby `method(:sym)` calls, and `this.method` member forms.
+     */
+    special?: Set<string>;
+    /**
+     * Capture modes whose candidates skip the same-file/import gate and rely on
+     * resolution's unique-or-drop rule instead. C-family only: an initializer
+     * value, function-pointer assignment RHS, or table element is a
+     * function-pointer position by construction, and C has no symbol imports —
+     * the dominant repo-scale pattern (`server.c`'s command table naming
+     * handlers defined across files) would otherwise be invisible. Call
+     * arguments stay gated everywhere (locals passed as args dwarf callbacks).
+     */
+    ungatedModes?: Set<CaptureMode>;
+    /**
+     * C++ only: in args/rhs/varinit positions, accept ONLY explicit reference
+     * forms (`&fn`, `&Cls::method`) — never bare identifiers. C++ codebases are
+     * dense with generic free-function/accessor names (`begin`, `end`, `out`,
+     * `size`, `data`) that collide with parameters and locals, and out-of-line
+     * member definitions extract as function-kind nodes — bare-id matching on
+     * fmt was mostly wrong edges. File-scope initializer tables (value/list)
+     * still accept bare identifiers, same as C.
+     */
+    addressOfOnly?: boolean;
+}
+/**
+ * Capture specs by language.
+ */
+export declare const FN_REF_SPECS: Record<string, FnRefSpec | undefined>;
+/**
+ * Extract candidate names from a dispatched container node. Returns the
+ * (name, position) pairs of every function-value-shaped expression found.
+ */
+export declare function captureFnRefCandidates(container: SyntaxNode, rule: CaptureRule, spec: FnRefSpec, source: string): FnRefCandidate[];
+export {};
+//# sourceMappingURL=function-ref.d.ts.map

package/dist/extraction/generated-detection.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Generated-file detection for symbol-disambiguation down-ranking.
+ *
+ * When a query like "Send" matches 17 symbols across protobuf scaffolding,
+ * test mocks, and the hand-written implementation, the FTS ranker often
+ * surfaces the generated stubs first because their names are identical
+ * to the implementation's name (validated empirically on cosmos-sdk —
+ * see project_go_multi_module_audit memory). Generated stubs frequently
+ * have no body to trace from, so the agent ends up reading source anyway.
+ *
+ * This helper is a pure path-based classifier consulted at disambiguation
+ * time (findSymbol / findAllSymbols / codegraph_search formatting), NOT
+ * a hard filter — generated nodes are still in the graph and remain
+ * reachable; they just rank LAST when there's a real implementation
+ * with the same name.
+ *
+ * Scope: suffix patterns only. Most generated files follow the
+ * `<basename>.<tool>.<ext>` convention (`.pb.go`, `_grpc.pb.go`,
+ * `.g.dart`, `_pb2.py`), and that covers ~all of what we saw in the
+ * Go audit. A future addition would be scanning for the canonical
+ * `// Code generated by` header during extraction, for the rare files
+ * that defy the suffix convention.
+ */
+/**
+ * Whether `filePath` looks like a tool-generated source file based on
+ * its filename. Path-only — does not read content. The result is a
+ * relevance hint for disambiguation, not a hard claim.
+ */
+export declare function isGeneratedFile(filePath: string): boolean;
+//# sourceMappingURL=generated-detection.d.ts.map

package/dist/extraction/grammars.d.ts

@@ -0,0 +1,128 @@
+/**
+ * Grammar Loading and Caching
+ *
+ * Uses web-tree-sitter (WASM) for universal cross-platform support.
+ * Grammars are loaded lazily — only languages actually present in the project
+ * are compiled, keeping V8 WASM memory pressure low on large codebases.
+ */
+import { Parser } from 'web-tree-sitter';
+import { Language } from '../types';
+export type GrammarLanguage = Exclude<Language, 'svelte' | 'vue' | 'astro' | 'liquid' | 'razor' | 'yaml' | 'twig' | 'xml' | 'properties' | 'vba' | 'sql' | 'unknown'>;
+/**
+ * File extension to Language mapping
+ */
+export declare const EXTENSION_MAP: Record<string, Language>;
+/**
+ * Whether a file is one CodeGraph can parse, based purely on its extension.
+ * This is the single source of truth for "should we index this file" — derived
+ * from EXTENSION_MAP so parser support and indexing selection never drift.
+ *
+ * `overrides` is the project's validated custom extension → language map (from
+ * `codegraph.json`); when present its extensions count as indexable in addition
+ * to the built-ins. Omitting it is byte-identical to the zero-config behavior.
+ */
+export declare function isSourceFile(filePath: string, overrides?: Record<string, Language>): boolean;
+/**
+ * Shopify OS 2.0 JSON template (`templates/*.json`) or section group
+ * (`sections/*.json`) — these reference sections by `"type"`, so the Liquid
+ * extractor links them. (config/ + locales/ JSON have no section refs.)
+ */
+export declare function isShopifyLiquidJson(filePath: string): boolean;
+/**
+ * Play Framework routes file: the extensionless `conf/routes` (and included
+ * `conf/*.routes`). No grammar — route extraction is done by the Play framework
+ * resolver, so it's processed through the no-grammar (`yaml`-style) path.
+ */
+export declare function isPlayRoutesFile(filePath: string): boolean;
+/**
+ * Dysflow exports Access/VBA form/report UI as `.form.txt` and `.report.txt`
+ * (two-segment extensions). `path.extname()` collapses them to `.txt`, which
+ * would falsely classify every text file as VBA. This helper recognizes the
+ * two-segment shape by checking the basename's last 9 or 11 characters.
+ *
+ * Used as a pre-check BEFORE `path.extname()` in both `detectLanguage()` and
+ * `isSourceFile()`. Returns true for `.form.txt` / `.report.txt` (any depth,
+ * forward or backslash separators); false for everything else.
+ *
+ * Trailing whitespace, case differences, and bare `.form`/`.report` (no .txt)
+ * are all treated as non-VBA — Dysflow always writes the `.txt` suffix.
+ */
+export declare function detectVbaFormFile(filePath: string): boolean;
+/**
+ * Initialize the tree-sitter WASM runtime. Must be called before loading grammars.
+ * Does NOT load any grammar WASM files — use loadGrammarsForLanguages() for that.
+ * Idempotent — safe to call multiple times.
+ */
+export declare function initGrammars(): Promise<void>;
+/**
+ * Load grammar WASM files for specific languages only.
+ * Skips languages that are already loaded or have no WASM grammar.
+ * Must be called after initGrammars().
+ */
+export declare function loadGrammarsForLanguages(languages: Language[]): Promise<void>;
+/**
+ * Load ALL grammar WASM files. Convenience function for tests and
+ * backward compatibility. Prefer loadGrammarsForLanguages() in production.
+ */
+export declare function loadAllGrammars(): Promise<void>;
+/**
+ * Check if grammars have been initialized
+ */
+export declare function isGrammarsInitialized(): boolean;
+/**
+ * Get a parser for the specified language.
+ * Returns synchronously from pre-loaded cache.
+ */
+export declare function getParser(language: Language): Parser | null;
+/**
+ * Detect language from file extension.
+ *
+ * `overrides` is the project's validated custom extension → language map (from
+ * `codegraph.json`); when present its mappings take precedence over the built-in
+ * `EXTENSION_MAP`. Omitting it is byte-identical to the zero-config behavior.
+ */
+export declare function detectLanguage(filePath: string, source?: string, overrides?: Record<string, Language>): Language;
+/**
+ * Check if a language is supported (has a grammar defined).
+ * Returns true if the grammar exists, even if not yet loaded.
+ */
+export declare function isLanguageSupported(language: Language): boolean;
+/**
+ * Check if a grammar has been loaded and is ready for parsing.
+ */
+export declare function isGrammarLoaded(language: Language): boolean;
+/**
+ * Languages tracked at the file-record level only: parsing emits zero symbol
+ * nodes, but the file is still stored (and framework resolvers may add per-file
+ * references later, e.g. Drupal routing yml, Spring `@Value` against
+ * application.properties). This is the canonical set behind the no-symbol
+ * branch in `tree-sitter.ts`; `xml` is intentionally excluded because its
+ * MyBatis extractor emits a file node. Callers use this to count such files as
+ * indexed rather than skipped, so it must stay in sync with that branch.
+ */
+export declare function isFileLevelOnlyLanguage(language: Language): boolean;
+/**
+ * Get all supported languages (those with grammar definitions).
+ */
+export declare function getSupportedLanguages(): Language[];
+/**
+ * Reset the cached parser for a language to reclaim WASM heap memory.
+ * The tree-sitter WASM runtime accumulates fragmented memory over thousands
+ * of parses. Deleting and recreating the Parser instance forces the WASM
+ * heap to reset, preventing "memory access out of bounds" crashes in
+ * large repos.
+ */
+export declare function resetParser(language: Language): void;
+/**
+ * Clear parser/grammar caches (useful for testing)
+ */
+export declare function clearParserCache(): void;
+/**
+ * Report grammars that failed to load.
+ */
+export declare function getUnavailableGrammarErrors(): Partial<Record<Language, string>>;
+/**
+ * Get language display name
+ */
+export declare function getLanguageDisplayName(language: Language): string;
+//# sourceMappingURL=grammars.d.ts.map