@egentica/codemap 0.1.5

package/dist/types/assist.d.ts

@@ -0,0 +1,147 @@
+/**
+ * Assist system types for goal-driven file discovery.
+ *
+ * AssistMap uses multi-phase scoring to rank files:
+ * - Phase A: Static scoring (keyword/symbol matching)
+ * - Phase B: Stack pack bias (language-specific patterns)
+ * - Phase C: Experience weighting (query history, usage metadata, anti-results)
+ * - Phase D: Confidence + warnings
+ */
+/**
+ * Assist request parameters.
+ */
+export interface AssistRequest {
+    /** Goal description (natural language) */
+    goal: string;
+    /** Optional context for scoring */
+    context?: {
+        /** Current file path (for related file boost) */
+        currentFile?: string;
+        /** Recent files (for recency boost) */
+        recentFiles?: string[];
+    };
+}
+/**
+ * Single assist result (file candidate).
+ */
+export interface AssistCandidate {
+    /** File path */
+    file: string;
+    /** Overall confidence score (0-1) */
+    confidence: number;
+    /** Raw score (before normalization) */
+    rawScore: number;
+    /** Scoring breakdown */
+    scoring: {
+        /** Phase A: Static score */
+        static: number;
+        /** Phase B: Stack bias */
+        bias: number;
+        /** Phase C: Experience score */
+        experience: number;
+        /** Total before confidence */
+        total: number;
+    };
+    /** Reason phrases explaining the score */
+    reasons: string[];
+    /** Warnings (if any) */
+    warnings?: string[];
+}
+/**
+ * Assist response.
+ */
+export interface AssistResult {
+    /** Ranked file candidates */
+    targets: AssistCandidate[];
+    /** Overall confidence in top result */
+    topConfidence: number;
+    /** Suggestions for user */
+    suggestions?: string[];
+}
+/**
+ * Stack pack bias rules for language-specific patterns.
+ */
+export interface StackPackBias {
+    /** Stack identifier (e.g., "vue3-ts", "react-next") */
+    id: string;
+    /** Bias rules */
+    rules: BiasRule[];
+}
+/**
+ * Single bias rule.
+ */
+export interface BiasRule {
+    /** Condition: query pattern */
+    when: string | RegExp;
+    /** Boost: path pattern → score adjustment */
+    boost: Record<string, number>;
+    /** Description */
+    description?: string;
+}
+/**
+ * Usage metadata matching result.
+ */
+export interface UsageMatch {
+    /** File path */
+    file: string;
+    /** Matching usage phrases */
+    matchingUsages: string[];
+    /** Match score (0-1) */
+    score: number;
+}
+/**
+ * Query pattern match result.
+ */
+export interface QueryPatternMatch {
+    /** File path */
+    file: string;
+    /** Matching queries from history */
+    matchingQueries: Array<{
+        query: string;
+        timestamp: string;
+    }>;
+    /** Match score (0-1) */
+    score: number;
+}
+/**
+ * Anti-result penalty result.
+ */
+export interface AntiResultPenalty {
+    /** File path */
+    file: string;
+    /** Penalty score (negative) */
+    penalty: number;
+    /** Reason for penalty */
+    reason: string;
+}
+/**
+ * File experience metrics.
+ */
+export interface FileExperienceMetrics {
+    /** Success rate (0-1) */
+    successRate: number;
+    /** Total operations */
+    totalOps: number;
+    /** Successful operations */
+    successfulOps: number;
+    /** Last accessed timestamp */
+    lastAccessed?: string;
+    /** Days since last access */
+    daysSinceAccess?: number;
+    /** Heat score (0-1, based on recent activity) */
+    heatScore: number;
+}
+/**
+ * Symbol metadata for experience tracking.
+ */
+export interface SymbolExperienceMetrics {
+    /** Symbol reference (relativePath$symbolName) */
+    symbolRef: string;
+    /** Times successfully edited */
+    editCount: number;
+    /** Success rate */
+    successRate: number;
+    /** Domain path keywords */
+    domainKeywords: string[];
+}
+//# sourceMappingURL=assist.d.ts.map

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

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

package/dist/types/assist.js

@@ -0,0 +1,12 @@
+"use strict";
+/**
+ * Assist system types for goal-driven file discovery.
+ *
+ * AssistMap uses multi-phase scoring to rank files:
+ * - Phase A: Static scoring (keyword/symbol matching)
+ * - Phase B: Stack pack bias (language-specific patterns)
+ * - Phase C: Experience weighting (query history, usage metadata, anti-results)
+ * - Phase D: Confidence + warnings
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=assist.js.map

package/dist/types/assist.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"assist.js","sourceRoot":"","sources":["../../src/types/assist.ts"],"names":[],"mappings":";AAAA;;;;;;;;GAQG"}

package/dist/types/contracts/FileSystemProvider.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Minimal filesystem contract.
+ *
+ * Consumers provide an implementation of this interface.
+ * Enables storage-agnostic operation (node:fs, Electron, SQLite, memory, etc.).
+ */
+export interface FileSystemProvider {
+    read(path: string): Promise<string>;
+    write(path: string, content: string): Promise<void>;
+    exists(path: string): Promise<boolean>;
+    readdir(path: string): Promise<string[]>;
+    stat(path: string): Promise<{
+        isDirectory: boolean;
+        size: number;
+        mtime: number;
+    }>;
+    remove(path: string): Promise<void>;
+    rename(oldPath: string, newPath: string): Promise<void>;
+    mkdir(path: string): Promise<void>;
+    rmdir(path: string, options?: {
+        recursive?: boolean;
+    }): Promise<void>;
+}
+//# sourceMappingURL=FileSystemProvider.d.ts.map

package/dist/types/contracts/FileSystemProvider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"FileSystemProvider.d.ts","sourceRoot":"","sources":["../../../src/types/contracts/FileSystemProvider.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,MAAM,WAAW,kBAAkB;IACjC,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAA;IACnC,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IACnD,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAA;IACtC,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAAA;IACxC,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,WAAW,EAAE,OAAO,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC,CAAA;IAClF,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IACnC,MAAM,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IACvD,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAClC,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,SAAS,CAAC,EAAE,OAAO,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;CACtE"}

package/dist/types/contracts/FileSystemProvider.js

@@ -0,0 +1,9 @@
+"use strict";
+/**
+ * Minimal filesystem contract.
+ *
+ * Consumers provide an implementation of this interface.
+ * Enables storage-agnostic operation (node:fs, Electron, SQLite, memory, etc.).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=FileSystemProvider.js.map

package/dist/types/contracts/FileSystemProvider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"FileSystemProvider.js","sourceRoot":"","sources":["../../../src/types/contracts/FileSystemProvider.ts"],"names":[],"mappings":";AAAA;;;;;GAKG"}

package/dist/types/contracts/LanguageParser.d.ts

@@ -0,0 +1,146 @@
+/**
+ * Language parser plugin contract.
+ *
+ * Language parsers extract symbols and dependencies from source files.
+ * They hook into the scan:file event and enrich the graph with language-specific data.
+ *
+ * @example TypeScript Parser
+ * ```typescript
+ * export class TypeScriptParser implements LanguageParser {
+ *   name = 'typescript-parser';
+ *   version = '0.1.0';
+ *   fileExtensions = ['.ts', '.tsx', '.js', '.jsx'];
+ *
+ *   async parse(filePath: string, content: string): Promise<ParseResult> {
+ *     const ast = parse(content);
+ *     const symbols = extractSymbols(ast);
+ *     const dependencies = extractImports(ast);
+ *     return { symbols, dependencies };
+ *   }
+ *
+ *   register(codemap: CodeMapHost): void {
+ *     codemap.on('scan:file', async (file) => {
+ *       if (!this.canParse(file.relativePath)) return;
+ *       const content = await codemap.fs.read(file.absolutePath);
+ *       const result = await this.parse(file.relativePath, content);
+ *       result.symbols.forEach(s => codemap.addSymbol({ ...s, file }));
+ *       result.dependencies.forEach(dep => codemap.addDependency(file.relativePath, dep));
+ *     });
+ *   }
+ * }
+ * ```
+ */
+import type { SymbolEntry, ElementEntry } from '../core';
+import type { Plugin } from './Plugin';
+/**
+ * Result of parsing a source file.
+ */
+export interface ParseResult {
+    /**
+     * Symbols discovered in the file (functions, classes, etc.).
+     */
+    symbols: SymbolEntry[];
+    /**
+     * DOM elements discovered in template files (Vue, HTML, etc.).
+     * Separate from symbols - searchable via codemap_search_elements.
+     */
+    elements?: ElementEntry[];
+    /**
+     * Import dependencies (relative paths to other files).
+     */
+    dependencies: string[];
+    /**
+     * Optional: Exports from this file.
+     */
+    exports?: string[];
+    /**
+     * Optional: Simple annotations extracted from file.
+     */
+    annotations?: any[];
+    /**
+     * Optional: Categorized annotations (@codemap.domain.*, etc.)
+     */
+    categorizedAnnotations?: any[];
+}
+/**
+ * Language parser plugin interface.
+ * Extends base Plugin with parsing-specific methods.
+ */
+export interface LanguageParser extends Plugin {
+    /**
+     * File extensions this parser handles.
+     * e.g., ['.ts', '.tsx'] for TypeScript parser.
+     */
+    readonly fileExtensions: string[];
+    /**
+     * Check if this parser can handle a given file.
+     * Default implementation checks fileExtensions, but can be overridden.
+     */
+    canParse(filePath: string): boolean;
+    /**
+     * Parse a source file and extract symbols and dependencies.
+     *
+     * @param filePath - Relative path to the file
+     * @param content - File content to parse
+     * @returns Symbols and dependencies discovered
+     */
+    parse(filePath: string, content: string): Promise<ParseResult>;
+    /**
+     * Add a @codemap annotation to file content.
+     * Handles language-specific comment syntax (JSDoc, #, /*, etc.)
+     *
+     * @param content - Original file content
+     * @param key - Annotation key (e.g., "domain.name", "tags", "usage")
+     * @param value - Annotation value
+     * @returns Modified file content with annotation added
+     */
+    addAnnotation?(content: string, key: string, value: string): string;
+    /**
+     * Edit an existing @codemap annotation in file content.
+     *
+     * @param content - Original file content
+     * @param key - Annotation key to edit
+     * @param newValue - New annotation value
+     * @returns Modified file content with annotation updated
+     */
+    editAnnotation?(content: string, key: string, newValue: string): string;
+    /**
+     * Remove a @codemap annotation from file content.
+     *
+     * @param content - Original file content
+     * @param key - Annotation key to remove
+     * @returns Modified file content with annotation removed
+     */
+    removeAnnotation?(content: string, key: string): string;
+    /**
+     * Validate syntax before write (optional).
+     *
+     * Prevents corrupted files from being written by validating syntax
+     * in memory before any file operations occur.
+     *
+     * @param content - File content to validate
+     * @param filePath - File path (for context/error messages)
+     * @returns Validation result with specific errors if invalid
+     *
+     * @example
+     * const result = await parser.validateSyntax(content, 'app.ts');
+     * if (!result.valid) {
+     *   throw new Error('Syntax errors: ' + formatErrors(result.errors));
+     * }
+     */
+    validateSyntax?(content: string, filePath: string): Promise<{
+        valid: boolean;
+        errors?: Array<{
+            line: number;
+            column: number;
+            message: string;
+            suggestion?: string;
+        }>;
+    }>;
+}
+/**
+ * Default implementation of canParse.
+ * Checks if file extension matches parser's fileExtensions.
+ */
+export declare function defaultCanParse(parser: Pick<LanguageParser, 'fileExtensions'>, filePath: string): boolean;
+//# sourceMappingURL=LanguageParser.d.ts.map

package/dist/types/contracts/LanguageParser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"LanguageParser.d.ts","sourceRoot":"","sources":["../../../src/types/contracts/LanguageParser.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACzD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,UAAU,CAAC;AAEvC;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B;;OAEG;IACH,OAAO,EAAE,WAAW,EAAE,CAAC;IAEvB;;;OAGG;IACH,QAAQ,CAAC,EAAE,YAAY,EAAE,CAAC;IAE1B;;OAEG;IACH,YAAY,EAAE,MAAM,EAAE,CAAC;IAEvB;;OAEG;IACH,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IAEnB;;OAEG;IACH,WAAW,CAAC,EAAE,GAAG,EAAE,CAAC;IAEpB;;OAEG;IACH,sBAAsB,CAAC,EAAE,GAAG,EAAE,CAAC;CAChC;AAED;;;GAGG;AACH,MAAM,WAAW,cAAe,SAAQ,MAAM;IAC5C;;;OAGG;IACH,QAAQ,CAAC,cAAc,EAAE,MAAM,EAAE,CAAC;IAElC;;;OAGG;IACH,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC;IAEpC;;;;;;OAMG;IACH,KAAK,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC,CAAC;IAE/D;;;;;;;;OAQG;IACH,aAAa,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAAC;IAEpE;;;;;;;OAOG;IACH,cAAc,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAAC;IAExE;;;;;;OAMG;IACH,gBAAgB,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAAC;IAExD;;;;;;;;;;;;;;;OAeG;IACH,cAAc,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC;QAC1D,KAAK,EAAE,OAAO,CAAC;QACf,MAAM,CAAC,EAAE,KAAK,CAAC;YACb,IAAI,EAAE,MAAM,CAAC;YACb,MAAM,EAAE,MAAM,CAAC;YACf,OAAO,EAAE,MAAM,CAAC;YAChB,UAAU,CAAC,EAAE,MAAM,CAAC;SACrB,CAAC,CAAC;KACJ,CAAC,CAAC;CACJ;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAC7B,MAAM,EAAE,IAAI,CAAC,cAAc,EAAE,gBAAgB,CAAC,EAC9C,QAAQ,EAAE,MAAM,GACf,OAAO,CAET"}

package/dist/types/contracts/LanguageParser.js

@@ -0,0 +1,43 @@
+"use strict";
+/**
+ * Language parser plugin contract.
+ *
+ * Language parsers extract symbols and dependencies from source files.
+ * They hook into the scan:file event and enrich the graph with language-specific data.
+ *
+ * @example TypeScript Parser
+ * ```typescript
+ * export class TypeScriptParser implements LanguageParser {
+ *   name = 'typescript-parser';
+ *   version = '0.1.0';
+ *   fileExtensions = ['.ts', '.tsx', '.js', '.jsx'];
+ *
+ *   async parse(filePath: string, content: string): Promise<ParseResult> {
+ *     const ast = parse(content);
+ *     const symbols = extractSymbols(ast);
+ *     const dependencies = extractImports(ast);
+ *     return { symbols, dependencies };
+ *   }
+ *
+ *   register(codemap: CodeMapHost): void {
+ *     codemap.on('scan:file', async (file) => {
+ *       if (!this.canParse(file.relativePath)) return;
+ *       const content = await codemap.fs.read(file.absolutePath);
+ *       const result = await this.parse(file.relativePath, content);
+ *       result.symbols.forEach(s => codemap.addSymbol({ ...s, file }));
+ *       result.dependencies.forEach(dep => codemap.addDependency(file.relativePath, dep));
+ *     });
+ *   }
+ * }
+ * ```
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.defaultCanParse = defaultCanParse;
+/**
+ * Default implementation of canParse.
+ * Checks if file extension matches parser's fileExtensions.
+ */
+function defaultCanParse(parser, filePath) {
+    return parser.fileExtensions.some(ext => filePath.endsWith(ext));
+}
+//# sourceMappingURL=LanguageParser.js.map

package/dist/types/contracts/LanguageParser.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"LanguageParser.js","sourceRoot":"","sources":["../../../src/types/contracts/LanguageParser.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;;AAgIH,0CAKC;AATD;;;GAGG;AACH,SAAgB,eAAe,CAC7B,MAA8C,EAC9C,QAAgB;IAEhB,OAAO,MAAM,CAAC,cAAc,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,QAAQ,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC;AACnE,CAAC"}

package/dist/types/contracts/Plugin.d.ts

@@ -0,0 +1,226 @@
+/**
+ * Base plugin contract for CodeMap extensions.
+ *
+ * All plugins (parsers, enrichments, storage adapters) implement this interface.
+ * Plugins register lifecycle hooks with the CodeMap orchestrator.
+ *
+ * @example
+ * ```typescript
+ * export class HTMLParser implements Plugin {
+ *   register(codemap: CodeMap): void {
+ *     codemap.on('scan:file', async (file) => {
+ *       if (!file.relativePath.endsWith('.html')) return;
+ *       // Parse and add symbols to graph
+ *     });
+ *   }
+ * }
+ * ```
+ */
+import type { FileEntry } from '../core';
+import type { CodeMapEvent } from '../events';
+/**
+ * Event handler signature for lifecycle events.
+ */
+export type EventHandler<T = unknown> = (payload: T) => void | Promise<void>;
+/**
+ * Orient contribution from a plugin.
+ * Plugins return this from orient:contribute event handlers.
+ */
+export interface OrientContribution {
+    /** Section title (e.g., "TimeWarp Status", "Custom Plugin Data") */
+    title: string;
+    /** Markdown content for this section */
+    markdown: string;
+    /** Optional priority (higher = earlier in output, default: 0) */
+    priority?: number;
+}
+/**
+ * Minimal CodeMap interface for plugin registration.
+ * The full CodeMap class will implement this contract.
+ */
+export interface CodeMapHost {
+    /**
+     * Register a lifecycle event handler.
+     * Plugins hook into CodeMap events here.
+     *
+     * @param event - Event name (must be a valid CodeMapEvent)
+     * @param handler - Event handler function
+     */
+    on(event: CodeMapEvent, handler: EventHandler): void;
+    /**
+     * Access to the FileSystemIO gateway.
+     * Plugins use this for all file operations (no bypass).
+     */
+    fs: {
+        read(path: string): Promise<string>;
+        write(path: string, content: string): Promise<void>;
+        exists(path: string): Promise<boolean>;
+    };
+    /**
+     * Add a symbol to the unified graph.
+     * Used by parsers to enrich the graph with discovered symbols.
+     */
+    addSymbol(symbol: {
+        kind: string;
+        name: string;
+        line: number;
+        file: FileEntry;
+    }): void;
+    /**
+     * Add a dependency edge to the graph.
+     * Used by parsers to track import relationships.
+     */
+    addDependency(from: string, to: string): void;
+    /**
+     * Get plugin-specific configuration from .codemap/config.json.
+     * Returns undefined if plugin config not present.
+     *
+     * Config should be structured as:
+     * {
+     *   "plugins": {
+     *     "pluginName": { ...config... }
+     *   }
+     * }
+     *
+     * @param pluginName - Name of the plugin (should match Plugin.name)
+     * @returns Plugin configuration object or undefined
+     *
+     * @example
+     * ```typescript
+     * // In TimeWarp plugin
+     * const config = codemap.getPluginConfig('timewarp');
+     * this.maxSnapshots = config?.maxSnapshots ?? 50;
+     * this.compressionEnabled = config?.compressionEnabled ?? true;
+     * ```
+     */
+    getPluginConfig(pluginName: string): Record<string, unknown> | undefined;
+    /**
+     * Set plugin metadata on a file, symbol, or other entity.
+     * Namespace convention: key should be `pluginName.fieldName`
+     *
+     * Emits 'metadata:set' event for tracking.
+     *
+     * @param path - Entity path (file path, symbol reference, etc.)
+     * @param key - Metadata key (namespace: pluginName.fieldName)
+     * @param value - Metadata value (must be JSON-serializable)
+     *
+     * @example
+     * ```typescript
+     * // TimeWarp plugin sets snapshot count
+     * codemap.setMetadata('src/auth/login.ts', 'timewarp.snapshotCount', 5);
+     *
+     * // Analytics plugin sets view count
+     * codemap.setMetadata('src/components/Button.tsx', 'analytics.viewCount', 42);
+     * ```
+     */
+    setMetadata(path: string, key: string, value: unknown): void;
+    /**
+     * Get plugin metadata from a file, symbol, or other entity.
+     *
+     * Emits 'metadata:get' event for tracking.
+     *
+     * @param path - Entity path (file path, symbol reference, etc.)
+     * @param key - Metadata key (namespace: pluginName.fieldName)
+     * @returns Metadata value or undefined if not found
+     *
+     * @example
+     * ```typescript
+     * const count = codemap.getMetadata('src/auth/login.ts', 'timewarp.snapshotCount');
+     * // count = 5 or undefined
+     * ```
+     */
+    getMetadata(path: string, key: string): unknown;
+    /**
+     * Get a file entry from the graph (read-only).
+     * Useful for plugins that need direct graph access.
+     *
+     * @param path - File path (relative or absolute)
+     * @returns File entry or undefined if not found
+     *
+     * @example
+     * ```typescript
+     * const file = codemap.getFile('src/auth/login.ts');
+     * if (file) {
+     *   console.log(`File has ${file.symbols?.length || 0} symbols`);
+     * }
+     * ```
+     */
+    getFile(path: string): FileEntry | undefined;
+    /**
+     * Query the graph with advanced filters (read-only).
+     * Delegates to QueryEngine for consistent search behavior.
+     *
+     * @param options - Search options
+     * @returns Search results sorted by relevance
+     *
+     * @example
+     * ```typescript
+     * // Find all files in auth domain
+     * const results = codemap.queryGraph({
+     *   query: 'authentication',
+     *   mode: 'hybrid',
+     *   maxResults: 10
+     * });
+     * ```
+     */
+    queryGraph(options: {
+        query: string;
+        mode?: 'text' | 'symbol' | 'hybrid';
+        maxResults?: number;
+    }): Array<{
+        file: FileEntry;
+        relevance: number;
+        reasons: string[];
+    }>;
+    /**
+     * Get all files that import or are imported by a given file.
+     * Traverses the dependency graph.
+     *
+     * @param path - File path (relative or absolute)
+     * @param direction - 'imports' (what it imports) or 'importers' (what imports it)
+     * @param maxDepth - Maximum traversal depth (default: 3)
+     * @returns Array of file entries in dependency chain
+     *
+     * @example
+     * ```typescript
+     * // Find all files that import this file
+     * const importers = codemap.traverseDependencies('src/utils/logger.ts', 'importers');
+     *
+     * // Find all files this file imports (recursively)
+     * const imports = codemap.traverseDependencies('src/index.ts', 'imports', 5);
+     * ```
+     */
+    traverseDependencies(path: string, direction: 'imports' | 'importers', maxDepth?: number): FileEntry[];
+}
+/**
+ * Base plugin interface.
+ * All CodeMap plugins must implement this.
+ */
+export interface Plugin {
+    /**
+     * Plugin name (for debugging and registry).
+     */
+    readonly name: string;
+    /**
+     * Plugin version (semver).
+     */
+    readonly version: string;
+    /**
+     * Register plugin with CodeMap.
+     * Hook into lifecycle events, register handlers.
+     * Called once during CodeMap initialization.
+     */
+    register(codemap: CodeMapHost): void;
+    /**
+     * Optional async initialization for plugin data loading.
+     * Called after register() to allow plugins to load persisted data.
+     * Use this for operations that require async/await (database connections, file loading, etc.).
+     */
+    initialize?(codemap: CodeMapHost): Promise<void>;
+    /**
+     * Optional cleanup on plugin unload.
+     * Remove event handlers, close connections, etc.
+     */
+    unregister?(): void | Promise<void>;
+}
+//# sourceMappingURL=Plugin.d.ts.map

package/dist/types/contracts/Plugin.d.ts.map

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

package/dist/types/contracts/Plugin.js

@@ -0,0 +1,21 @@
+"use strict";
+/**
+ * Base plugin contract for CodeMap extensions.
+ *
+ * All plugins (parsers, enrichments, storage adapters) implement this interface.
+ * Plugins register lifecycle hooks with the CodeMap orchestrator.
+ *
+ * @example
+ * ```typescript
+ * export class HTMLParser implements Plugin {
+ *   register(codemap: CodeMap): void {
+ *     codemap.on('scan:file', async (file) => {
+ *       if (!file.relativePath.endsWith('.html')) return;
+ *       // Parse and add symbols to graph
+ *     });
+ *   }
+ * }
+ * ```
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=Plugin.js.map

package/dist/types/contracts/Plugin.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Plugin.js","sourceRoot":"","sources":["../../../src/types/contracts/Plugin.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;GAiBG"}

package/dist/types/contracts/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Contract interfaces for CodeMap plugins and extensions.
+ *
+ * These interfaces define the plugin system that enables CodeMap to be
+ * extended with language parsers, storage adapters, and enrichments.
+ */
+export * from './FileSystemProvider';
+export * from './Plugin';
+export * from './LanguageParser';
+//# sourceMappingURL=index.d.ts.map