@saluzi/codegraph 0.1.0

package/dist/errors.d.ts

@@ -0,0 +1,149 @@
+/**
+ * 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/errors.js

@@ -0,0 +1,219 @@
+"use strict";
+/**
+ * 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);
+ * ```
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.silentLogger = exports.defaultLogger = exports.ConfigError = exports.VectorError = exports.SearchError = exports.DatabaseError = exports.ParseError = exports.FileError = exports.CodeGraphError = void 0;
+exports.setLogger = setLogger;
+exports.getLogger = getLogger;
+exports.logDebug = logDebug;
+exports.logWarn = logWarn;
+exports.logError = logError;
+/**
+ * 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}`);
+ *   }
+ * }
+ * ```
+ */
+class CodeGraphError extends Error {
+    /** Error code for categorization (e.g., 'FILE_ERROR', 'PARSE_ERROR') */
+    code;
+    /** Additional context about the error */
+    context;
+    constructor(message, code, context) {
+        super(message);
+        this.name = 'CodeGraphError';
+        this.code = code;
+        this.context = context;
+        // Maintain proper stack trace for V8
+        if (Error.captureStackTrace) {
+            Error.captureStackTrace(this, this.constructor);
+        }
+    }
+}
+exports.CodeGraphError = CodeGraphError;
+/**
+ * Error reading or accessing files
+ */
+class FileError extends CodeGraphError {
+    filePath;
+    constructor(message, filePath, cause) {
+        super(message, 'FILE_ERROR', { filePath, cause: cause?.message });
+        this.name = 'FileError';
+        this.filePath = filePath;
+        if (cause) {
+            this.cause = cause;
+        }
+    }
+}
+exports.FileError = FileError;
+/**
+ * Error parsing source code
+ */
+class ParseError extends CodeGraphError {
+    filePath;
+    line;
+    column;
+    constructor(message, filePath, options) {
+        super(message, 'PARSE_ERROR', {
+            filePath,
+            line: options?.line,
+            column: options?.column,
+            cause: options?.cause?.message,
+        });
+        this.name = 'ParseError';
+        this.filePath = filePath;
+        this.line = options?.line;
+        this.column = options?.column;
+        if (options?.cause) {
+            this.cause = options.cause;
+        }
+    }
+}
+exports.ParseError = ParseError;
+/**
+ * Error with database operations
+ */
+class DatabaseError extends CodeGraphError {
+    operation;
+    constructor(message, operation, cause) {
+        super(message, 'DATABASE_ERROR', { operation, cause: cause?.message });
+        this.name = 'DatabaseError';
+        this.operation = operation;
+        if (cause) {
+            this.cause = cause;
+        }
+    }
+}
+exports.DatabaseError = DatabaseError;
+/**
+ * Error with search operations
+ */
+class SearchError extends CodeGraphError {
+    query;
+    constructor(message, query, cause) {
+        super(message, 'SEARCH_ERROR', { query, cause: cause?.message });
+        this.name = 'SearchError';
+        this.query = query;
+        if (cause) {
+            this.cause = cause;
+        }
+    }
+}
+exports.SearchError = SearchError;
+/**
+ * Error with vector/embedding operations
+ */
+class VectorError extends CodeGraphError {
+    constructor(message, operation, cause) {
+        super(message, 'VECTOR_ERROR', { operation, cause: cause?.message });
+        this.name = 'VectorError';
+        if (cause) {
+            this.cause = cause;
+        }
+    }
+}
+exports.VectorError = VectorError;
+/**
+ * Error with configuration
+ */
+class ConfigError extends CodeGraphError {
+    constructor(message, details) {
+        super(message, 'CONFIG_ERROR', details);
+        this.name = 'ConfigError';
+    }
+}
+exports.ConfigError = ConfigError;
+/**
+ * Default console-based logger
+ */
+exports.defaultLogger = {
+    debug(message, context) {
+        if (process.env.CODEGRAPH_DEBUG) {
+            console.debug(`[CodeGraph] ${message}`, context ?? '');
+        }
+    },
+    warn(message, context) {
+        console.warn(`[CodeGraph] ${message}`, context ?? '');
+    },
+    error(message, context) {
+        console.error(`[CodeGraph] ${message}`, context ?? '');
+    },
+};
+/**
+ * Silent logger (no output) - useful for tests
+ */
+exports.silentLogger = {
+    debug() { },
+    warn() { },
+    error() { },
+};
+/**
+ * Current logger instance (can be replaced)
+ */
+let currentLogger = exports.defaultLogger;
+/**
+ * Set the global logger
+ */
+function setLogger(logger) {
+    currentLogger = logger;
+}
+/**
+ * Get the current logger
+ */
+function getLogger() {
+    return currentLogger;
+}
+/**
+ * Log a debug message
+ */
+function logDebug(message, context) {
+    currentLogger.debug(message, context);
+}
+/**
+ * Log a warning message
+ */
+function logWarn(message, context) {
+    currentLogger.warn(message, context);
+}
+/**
+ * Log an error message
+ */
+function logError(message, context) {
+    currentLogger.error(message, context);
+}
+//# sourceMappingURL=errors.js.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/dfm-extractor.js

@@ -0,0 +1,151 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DfmExtractor = void 0;
+const tree_sitter_helpers_1 = require("./tree-sitter-helpers");
+/**
+ * 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`
+ */
+class DfmExtractor {
+    filePath;
+    source;
+    nodes = [];
+    edges = [];
+    unresolvedReferences = [];
+    errors = [];
+    constructor(filePath, source) {
+        this.filePath = filePath;
+        this.source = source;
+    }
+    /**
+     * Extract components and event handler references from DFM/FMX source
+     */
+    extract() {
+        const startTime = Date.now();
+        try {
+            const fileNode = this.createFileNode();
+            this.parseComponents(fileNode.id);
+        }
+        catch (error) {
+            this.errors.push({
+                message: `DFM extraction error: ${error instanceof Error ? error.message : String(error)}`,
+                severity: 'error',
+                code: 'parse_error',
+            });
+        }
+        return {
+            nodes: this.nodes,
+            edges: this.edges,
+            unresolvedReferences: this.unresolvedReferences,
+            errors: this.errors,
+            durationMs: Date.now() - startTime,
+        };
+    }
+    /** Create a file node for the DFM form file */
+    createFileNode() {
+        const lines = this.source.split('\n');
+        const id = (0, tree_sitter_helpers_1.generateNodeId)(this.filePath, 'file', this.filePath, 1);
+        const fileNode = {
+            id,
+            kind: 'file',
+            name: this.filePath.split('/').pop() || this.filePath,
+            qualifiedName: this.filePath,
+            filePath: this.filePath,
+            language: 'pascal',
+            startLine: 1,
+            endLine: lines.length,
+            startColumn: 0,
+            endColumn: lines[lines.length - 1]?.length || 0,
+            updatedAt: Date.now(),
+        };
+        this.nodes.push(fileNode);
+        return fileNode;
+    }
+    /** Parse object/end blocks and extract components + event handlers */
+    parseComponents(fileNodeId) {
+        const lines = this.source.split('\n');
+        const stack = [fileNodeId];
+        const objectPattern = /^\s*(object|inherited|inline)\s+(\w+)\s*:\s*(\w+)/;
+        const eventPattern = /^\s*(On\w+)\s*=\s*(\w+)\s*$/;
+        const endPattern = /^\s*end\s*$/;
+        const multiLineStart = /=\s*\(\s*$/;
+        const multiLineItemStart = /=\s*<\s*$/;
+        let inMultiLine = false;
+        let multiLineEndChar = ')';
+        for (let i = 0; i < lines.length; i++) {
+            const line = lines[i];
+            const lineNum = i + 1;
+            // Skip multi-line properties
+            if (inMultiLine) {
+                if (line.trimEnd().endsWith(multiLineEndChar))
+                    inMultiLine = false;
+                continue;
+            }
+            if (multiLineStart.test(line)) {
+                inMultiLine = true;
+                multiLineEndChar = ')';
+                continue;
+            }
+            if (multiLineItemStart.test(line)) {
+                inMultiLine = true;
+                multiLineEndChar = '>';
+                continue;
+            }
+            // Component declaration
+            const objMatch = line.match(objectPattern);
+            if (objMatch) {
+                const [, , name, typeName] = objMatch;
+                const nodeId = (0, tree_sitter_helpers_1.generateNodeId)(this.filePath, 'component', name, lineNum);
+                this.nodes.push({
+                    id: nodeId,
+                    kind: 'component',
+                    name: name,
+                    qualifiedName: `${this.filePath}#${name}`,
+                    filePath: this.filePath,
+                    language: 'pascal',
+                    startLine: lineNum,
+                    endLine: lineNum,
+                    startColumn: 0,
+                    endColumn: line.length,
+                    signature: typeName,
+                    updatedAt: Date.now(),
+                });
+                this.edges.push({
+                    source: stack[stack.length - 1],
+                    target: nodeId,
+                    kind: 'contains',
+                });
+                stack.push(nodeId);
+                continue;
+            }
+            // Event handler
+            const eventMatch = line.match(eventPattern);
+            if (eventMatch) {
+                const [, , methodName] = eventMatch;
+                this.unresolvedReferences.push({
+                    fromNodeId: stack[stack.length - 1],
+                    referenceName: methodName,
+                    referenceKind: 'references',
+                    line: lineNum,
+                    column: 0,
+                });
+                continue;
+            }
+            // Block end
+            if (endPattern.test(line)) {
+                if (stack.length > 1)
+                    stack.pop();
+            }
+        }
+    }
+}
+exports.DfmExtractor = DfmExtractor;
+//# sourceMappingURL=dfm-extractor.js.map

package/dist/extraction/grammars.d.ts

@@ -0,0 +1,94 @@
+/**
+ * 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' | 'liquid' | 'yaml' | 'twig' | '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.
+ */
+export declare function isSourceFile(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
+ */
+export declare function detectLanguage(
+  filePath: string,
+  source?: string,
+): 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
+/**
+ * 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