@egentica/codemap 0.1.5

package/dist/core/PluginRegistry.js

@@ -0,0 +1,230 @@
+"use strict";
+/**
+ * PluginRegistry - Central plugin management for CodeMap.
+ *
+ * Discovers, registers, and manages plugin lifecycle.
+ * Plugins register hooks via the CodeMapHost interface.
+ *
+ * Architecture:
+ * - Plugins register via registry.register(plugin)
+ * - Each plugin receives CodeMapHost interface to hook into events
+ * - Registry tracks all registered plugins for lifecycle management
+ * - Supports plugin unregistration for cleanup
+ *
+ * @example
+ * ```typescript
+ * const registry = new PluginRegistry(codemap);
+ *
+ * // Register a language parser
+ * registry.register(new TypeScriptParser());
+ *
+ * // Register TimeWarp plugin
+ * registry.register(new TimeWarpPlugin());
+ *
+ * // Cleanup on shutdown
+ * await registry.unregisterAll();
+ * ```
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PluginRegistry = void 0;
+const packageDiscovery_1 = require("./utils/packageDiscovery");
+class PluginRegistry {
+    plugins;
+    codemap;
+    constructor(codemap) {
+        this.plugins = new Map();
+        this.codemap = codemap;
+    }
+    /**
+     * Auto-discover and register all available plugin packages.
+     *
+     * Loads plugins in two phases:
+     * 1. First-party plugins: Auto-discover @egentica/codemap-plugin-* packages
+     * 2. Third-party plugins: Load from config.plugins array
+     *
+     * Silently skips packages that are not installed.
+     *
+     * @param config - Configuration object (may contain plugins array)
+     */
+    async autoloadPlugins(config = {}) {
+        // 1. Auto-discover first-party plugins
+        const firstPartyPlugins = await (0, packageDiscovery_1.discoverFirstPartyPackages)('codemap-plugin');
+        // 2. Load third-party plugins from config
+        const thirdPartyPlugins = config.plugins?.paths || [];
+        // 3. Merge and load all plugins
+        const allPlugins = [...firstPartyPlugins, ...thirdPartyPlugins];
+        for (const pkg of allPlugins) {
+            try {
+                const module = await Promise.resolve(`${pkg}`).then(s => __importStar(require(s)));
+                const PluginClass = module.default;
+                const plugin = new PluginClass();
+                await this.register(plugin);
+            }
+            catch {
+                // Plugin not installed - skip silently
+            }
+        }
+    }
+    /**
+     * Register a plugin with CodeMap.
+     *
+     * Calls plugin.register(codemap) to let the plugin hook into events.
+     * If plugin has initialize() method, calls it for async setup.
+     * Plugin name must be unique.
+     *
+     * @param plugin - Plugin to register
+     * @throws Error if plugin with same name already registered
+     */
+    async register(plugin) {
+        if (this.plugins.has(plugin.name)) {
+            throw new Error(`Plugin '${plugin.name}' is already registered. ` +
+                `Each plugin name must be unique.`);
+        }
+        // Let plugin register its hooks (sync)
+        plugin.register(this.codemap);
+        // Initialize plugin data if supported (async)
+        if (plugin.initialize && typeof plugin.initialize === 'function') {
+            await plugin.initialize(this.codemap);
+        }
+        // Track registration
+        this.plugins.set(plugin.name, {
+            plugin,
+            registeredAt: Date.now()
+        });
+    }
+    /**
+     * Unregister a plugin by name.
+     *
+     * Calls plugin.unregister() if defined.
+     * Removes plugin from registry.
+     *
+     * Note: Does NOT automatically remove event handlers.
+     * Plugins are responsible for cleanup in their unregister() method.
+     *
+     * @param name - Plugin name to unregister
+     * @returns True if plugin was found and unregistered
+     */
+    async unregister(name) {
+        const metadata = this.plugins.get(name);
+        if (!metadata)
+            return false;
+        // Call plugin cleanup if defined
+        if (metadata.plugin.unregister) {
+            await metadata.plugin.unregister();
+        }
+        // Remove from registry
+        this.plugins.delete(name);
+        return true;
+    }
+    /**
+     * Unregister all plugins.
+     *
+     * Calls unregister() on each plugin sequentially.
+     * Useful for shutdown/cleanup.
+     */
+    async unregisterAll() {
+        const names = Array.from(this.plugins.keys());
+        for (const name of names) {
+            await this.unregister(name);
+        }
+    }
+    /**
+     * Check if a plugin is registered.
+     *
+     * @param name - Plugin name to check
+     * @returns True if plugin is registered
+     */
+    has(name) {
+        return this.plugins.has(name);
+    }
+    /**
+     * Get a registered plugin by name.
+     *
+     * @param name - Plugin name
+     * @returns Plugin instance or undefined
+     */
+    get(name) {
+        return this.plugins.get(name)?.plugin;
+    }
+    /**
+     * Get all registered plugin names.
+     *
+     * @returns Array of plugin names
+     */
+    getRegisteredPlugins() {
+        return Array.from(this.plugins.keys());
+    }
+    /**
+     * Get plugin count.
+     *
+     * @returns Number of registered plugins
+     */
+    get count() {
+        return this.plugins.size;
+    }
+    /**
+     * Get plugin metadata (name, version, registration time).
+     *
+     * @returns Array of plugin metadata
+     */
+    getPluginInfo() {
+        return Array.from(this.plugins.values()).map(metadata => ({
+            name: metadata.plugin.name,
+            version: metadata.plugin.version,
+            registeredAt: metadata.registeredAt
+        }));
+    }
+    /**
+     * Get a language parser that can handle the given file.
+     *
+     * @param filePath - File path to find parser for
+     * @returns LanguageParser instance or undefined
+     */
+    getParserForFile(filePath) {
+        for (const metadata of this.plugins.values()) {
+            const plugin = metadata.plugin;
+            // Check if this is a LanguageParser plugin with canParse method
+            if (plugin.canParse && typeof plugin.canParse === 'function') {
+                if (plugin.canParse(filePath)) {
+                    return plugin;
+                }
+            }
+        }
+        return undefined;
+    }
+}
+exports.PluginRegistry = PluginRegistry;
+//# sourceMappingURL=PluginRegistry.js.map

package/dist/core/PluginRegistry.js.map

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

package/dist/core/QueryEngine.d.ts

@@ -0,0 +1,134 @@
+/**
+ * QueryEngine - Orchestrator for search and graph traversal.
+ *
+ * Thin orchestrator that delegates to strategy classes:
+ * - TextSearchEngine: File path matching
+ * - SymbolSearchEngine: Symbol name matching
+ * - ResultProcessor: Post-processing and enrichment
+ * - DependencyTraversal: Graph traversal operations
+ *
+ * Architecture:
+ * - Pure query layer — no I/O, no side effects
+ * - Delegates all search logic to strategies
+ * - Coordinates multiple search modes
+ * - Manages result pagination and formatting
+ *
+ * @codemap.policy No file operations — graph queries only.
+ * @codemap.policy All search methods return sorted results (highest relevance first).
+ *
+ * @example
+ * ```typescript
+ * const query = new QueryEngine(config);
+ *
+ * // Text search
+ * const results = query.search({ query: 'auth login', mode: 'text' });
+ *
+ * // Symbol search
+ * const symbols = query.search({ query: 'handleLogin', mode: 'symbol' });
+ *
+ * // Find dependencies
+ * const importers = query.findImporters('src/auth/login.ts');
+ * ```
+ */
+import type { FileSystemGraph } from './FileSystemGraph';
+import type { FileEntry } from '../types/core';
+import type { SearchRequest, SearchResponse, SearchResult } from '../types/query';
+import type { EventBus } from './EventBus';
+import { HintRegistry } from './HintRegistry';
+/**
+ * Configuration for QueryEngine.
+ */
+export interface QueryEngineConfig {
+    /**
+     * The graph to query against.
+     */
+    graph: FileSystemGraph;
+    /**
+     * Default max results.
+     * Defaults to 5.
+     */
+    defaultMaxResults?: number;
+    /**
+     * Optional: GroupStore for including group membership in search results.
+     */
+    groupStore?: any;
+    /**
+     * Optional: HintRegistry for contextual hints.
+     */
+    hintRegistry?: HintRegistry;
+    /**
+     * Optional: EventBus for emitting search events (plugin hooks).
+     */
+    eventBus?: EventBus;
+}
+export declare class QueryEngine {
+    private graph;
+    private defaultMaxResults;
+    private defaultMaxSymbolsPerFile;
+    private groupStore?;
+    private hintRegistry;
+    private eventBus?;
+    private textSearch;
+    private symbolSearch;
+    private resultProcessor;
+    private dependencyTraversal;
+    constructor(config: QueryEngineConfig);
+    /**
+     * Execute a search query.
+     *
+     * Supports multiple search modes:
+     * - text: Keyword matching in file paths
+     * - symbol: Symbol name matching
+     * - hybrid: Combined text + symbol search
+     *
+     * @param request - Search request
+     * @returns Search results sorted by relevance
+     */
+    search(request: SearchRequest): SearchResponse;
+    /**
+     * Find files by name pattern (supports * wildcard).
+     */
+    findByName(pattern: string): FileEntry[];
+    /**
+     * Find files relevant to a task description.
+     * Uses keyword extraction + relevance scoring.
+     */
+    findRelevant(task: string, maxResults?: number): SearchResult[];
+    /**
+     * Find all files that import a given file.
+     */
+    findImporters(relativePath: string): FileEntry[];
+    /**
+     * Find all files imported by a given file.
+     */
+    findImports(relativePath: string): FileEntry[];
+    /**
+     * Get related files (imports + importers).
+     */
+    getRelated(relativePath: string): {
+        imports: FileEntry[];
+        importers: FileEntry[];
+    };
+    /**
+     * Traverse dependency graph with BFS.
+     */
+    traverse(startPath: string, direction: 'imports' | 'importers', maxDepth?: number): FileEntry[];
+    /**
+     * Search for DOM elements in template files.
+     *
+     * @param query - Element name or tag to search for
+     * @param tag - Optional tag filter
+     * @param hasId - Optional ID filter (true = explicit IDs, false = auto-numbered)
+     * @param maxResults - Max results to return
+     * @returns Element matches with file context
+     */
+    searchElements(query: string, options?: {
+        tag?: string;
+        hasId?: boolean;
+        maxResults?: number;
+    }): Array<{
+        element: any;
+        file: FileEntry;
+    }>;
+}
+//# sourceMappingURL=QueryEngine.d.ts.map

package/dist/core/QueryEngine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"QueryEngine.d.ts","sourceRoot":"","sources":["../../src/core/QueryEngine.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AACzD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AAC/C,OAAO,KAAK,EACV,aAAa,EACb,cAAc,EACd,YAAY,EACb,MAAM,gBAAgB,CAAC;AACxB,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAC3C,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAM9C;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC;;OAEG;IACH,KAAK,EAAE,eAAe,CAAC;IAEvB;;;OAGG;IACH,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAE3B;;OAEG;IACH,UAAU,CAAC,EAAE,GAAG,CAAC;IAEjB;;OAEG;IACH,YAAY,CAAC,EAAE,YAAY,CAAC;IAE5B;;OAEG;IACH,QAAQ,CAAC,EAAE,QAAQ,CAAC;CACrB;AAED,qBAAa,WAAW;IACtB,OAAO,CAAC,KAAK,CAAkB;IAC/B,OAAO,CAAC,iBAAiB,CAAS;IAClC,OAAO,CAAC,wBAAwB,CAAS;IACzC,OAAO,CAAC,UAAU,CAAC,CAAM;IACzB,OAAO,CAAC,YAAY,CAAe;IACnC,OAAO,CAAC,QAAQ,CAAC,CAAW;IAG5B,OAAO,CAAC,UAAU,CAAmB;IACrC,OAAO,CAAC,YAAY,CAAqB;IACzC,OAAO,CAAC,eAAe,CAAkB;IACzC,OAAO,CAAC,mBAAmB,CAAsB;gBAErC,MAAM,EAAE,iBAAiB;IAoBrC;;;;;;;;;;OAUG;IACH,MAAM,CAAC,OAAO,EAAE,aAAa,GAAG,cAAc;IA2G9C;;OAEG;IACH,UAAU,CAAC,OAAO,EAAE,MAAM,GAAG,SAAS,EAAE;IAIxC;;;OAGG;IACH,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,YAAY,EAAE;IAS/D;;OAEG;IACH,aAAa,CAAC,YAAY,EAAE,MAAM,GAAG,SAAS,EAAE;IAIhD;;OAEG;IACH,WAAW,CAAC,YAAY,EAAE,MAAM,GAAG,SAAS,EAAE;IAI9C;;OAEG;IACH,UAAU,CAAC,YAAY,EAAE,MAAM,GAAG;QAAE,OAAO,EAAE,SAAS,EAAE,CAAC;QAAC,SAAS,EAAE,SAAS,EAAE,CAAA;KAAE;IAIlF;;OAEG;IACH,QAAQ,CACN,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,SAAS,GAAG,WAAW,EAClC,QAAQ,GAAE,MAAU,GACnB,SAAS,EAAE;IAId;;;;;;;;OAQG;IACH,cAAc,CACZ,KAAK,EAAE,MAAM,EACb,OAAO,CAAC,EAAE;QACR,GAAG,CAAC,EAAE,MAAM,CAAC;QACb,KAAK,CAAC,EAAE,OAAO,CAAC;QAChB,UAAU,CAAC,EAAE,MAAM,CAAC;KACrB,GACA,KAAK,CAAC;QAAE,OAAO,EAAE,GAAG,CAAC;QAAC,IAAI,EAAE,SAAS,CAAA;KAAE,CAAC;CA4B5C"}

package/dist/core/QueryEngine.js

@@ -0,0 +1,211 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.QueryEngine = void 0;
+const HintRegistry_1 = require("./HintRegistry");
+const TextSearchEngine_1 = require("./query/TextSearchEngine");
+const SymbolSearchEngine_1 = require("./query/SymbolSearchEngine");
+const ResultProcessor_1 = require("./query/ResultProcessor");
+const DependencyTraversal_1 = require("./query/DependencyTraversal");
+class QueryEngine {
+    graph;
+    defaultMaxResults;
+    defaultMaxSymbolsPerFile;
+    groupStore;
+    hintRegistry;
+    eventBus;
+    // Strategy instances
+    textSearch;
+    symbolSearch;
+    resultProcessor;
+    dependencyTraversal;
+    constructor(config) {
+        this.graph = config.graph;
+        this.defaultMaxResults = config.defaultMaxResults || 5; // Default to 5 files
+        this.defaultMaxSymbolsPerFile = 5; // Default to 5 symbols per file
+        this.groupStore = config.groupStore;
+        this.hintRegistry = config.hintRegistry || new HintRegistry_1.HintRegistry();
+        this.eventBus = config.eventBus;
+        // Initialize strategy instances
+        this.textSearch = new TextSearchEngine_1.TextSearchEngine(this.graph);
+        this.symbolSearch = new SymbolSearchEngine_1.SymbolSearchEngine(this.graph);
+        this.resultProcessor = new ResultProcessor_1.ResultProcessor(this.groupStore);
+        this.dependencyTraversal = new DependencyTraversal_1.DependencyTraversal(this.graph);
+        // Register default hints if no custom registry provided
+        if (!config.hintRegistry) {
+            this.hintRegistry.registerDefaults();
+        }
+    }
+    /**
+     * Execute a search query.
+     *
+     * Supports multiple search modes:
+     * - text: Keyword matching in file paths
+     * - symbol: Symbol name matching
+     * - hybrid: Combined text + symbol search
+     *
+     * @param request - Search request
+     * @returns Search results sorted by relevance
+     */
+    search(request) {
+        const startTime = Date.now();
+        const mode = request.mode || 'hybrid';
+        const includeFull = request.includeFull || false;
+        const maxResults = includeFull ? 9999 : (request.maxResults || this.defaultMaxResults);
+        const maxSymbolsPerFile = includeFull ? 9999 : (request.maxSymbolsPerFile || this.defaultMaxSymbolsPerFile);
+        const symbolFormat = request.symbolFormat || 'full';
+        const useRegex = request.useRegex || false;
+        // Execute search based on mode - delegate to strategy classes
+        let results = [];
+        if (mode === 'text' || mode === 'hybrid') {
+            results = this.textSearch.search(request, useRegex);
+        }
+        if (mode === 'symbol' || mode === 'hybrid') {
+            const symbolResults = this.symbolSearch.search(request, useRegex);
+            results = this.resultProcessor.mergeResults(results, symbolResults);
+        }
+        // Apply filters
+        if (request.extensions) {
+            results = results.filter(r => request.extensions.some(ext => r.file.relativePath.endsWith(ext)));
+        }
+        if (request.pathPrefix) {
+            results = results.filter(r => r.file.relativePath.startsWith(request.pathPrefix));
+        }
+        // Sort by relevance (descending)
+        results.sort((a, b) => b.relevance - a.relevance);
+        // Limit results (unless includeFull is true)
+        const totalMatches = results.length;
+        if (!includeFull) {
+            results = results.slice(0, maxResults);
+        }
+        // Limit symbols per file (unless includeFull is true)
+        if (!includeFull) {
+            results = this.resultProcessor.limitSymbolsPerFile(results, maxSymbolsPerFile);
+        }
+        // Enrich with group membership BEFORE compacting symbols
+        // (enrichWithGroups needs matchedSymbols to find symbol-level groups)
+        if (this.groupStore) {
+            results = this.resultProcessor.enrichWithGroups(results);
+        }
+        // Convert symbols to compact format if requested
+        if (symbolFormat === 'compact') {
+            results = this.resultProcessor.compactSymbols(results, maxSymbolsPerFile);
+        }
+        // Strip full symbols array from file metadata for token efficiency (unless includeFull is true)
+        if (!includeFull) {
+            results = this.resultProcessor.stripFileSymbols(results);
+        }
+        // Generate contextual hints
+        const hints = this.hintRegistry.getHints({
+            results,
+            totalMatches,
+            query: request.query,
+            mode,
+            useRegex
+        });
+        const durationMs = Date.now() - startTime;
+        // Build response envelope
+        const envelope = {
+            success: true,
+            data: {
+                results,
+                totalMatches,
+                hints: hints.length > 0 ? hints : undefined
+            },
+            meta: {
+                durationMs,
+                timestamp: Date.now(),
+                operation: 'search',
+                query: request.query,
+                mode
+            }
+        };
+        // Plugin hook: before returning results (plugins can enrich metadata)
+        if (this.eventBus) {
+            this.eventBus.emit('search:result:before', envelope);
+        }
+        // Plugin hook: after enrichment (plugins can post-process)
+        if (this.eventBus) {
+            this.eventBus.emit('search:result:after', envelope);
+        }
+        return envelope;
+    }
+    // ── Public API Methods ─────────────────────────────────────────────────────
+    /**
+     * Find files by name pattern (supports * wildcard).
+     */
+    findByName(pattern) {
+        return this.textSearch.findByName(pattern);
+    }
+    /**
+     * Find files relevant to a task description.
+     * Uses keyword extraction + relevance scoring.
+     */
+    findRelevant(task, maxResults) {
+        const response = this.search({
+            query: task,
+            mode: 'hybrid',
+            maxResults: maxResults || this.defaultMaxResults
+        });
+        return response.data?.results || [];
+    }
+    /**
+     * Find all files that import a given file.
+     */
+    findImporters(relativePath) {
+        return this.dependencyTraversal.findImporters(relativePath);
+    }
+    /**
+     * Find all files imported by a given file.
+     */
+    findImports(relativePath) {
+        return this.dependencyTraversal.findImports(relativePath);
+    }
+    /**
+     * Get related files (imports + importers).
+     */
+    getRelated(relativePath) {
+        return this.dependencyTraversal.getRelated(relativePath);
+    }
+    /**
+     * Traverse dependency graph with BFS.
+     */
+    traverse(startPath, direction, maxDepth = 3) {
+        return this.dependencyTraversal.traverse(startPath, direction, maxDepth);
+    }
+    /**
+     * Search for DOM elements in template files.
+     *
+     * @param query - Element name or tag to search for
+     * @param tag - Optional tag filter
+     * @param hasId - Optional ID filter (true = explicit IDs, false = auto-numbered)
+     * @param maxResults - Max results to return
+     * @returns Element matches with file context
+     */
+    searchElements(query, options) {
+        const queryLower = query.toLowerCase();
+        const results = [];
+        const maxResults = options?.maxResults || this.defaultMaxResults;
+        for (const file of this.graph.getAllFiles()) {
+            if (!file.elements || file.elements.length === 0)
+                continue;
+            for (const element of file.elements) {
+                // Apply filters
+                if (options?.tag && element.tag !== options.tag)
+                    continue;
+                if (options?.hasId !== undefined && element.hasId !== options.hasId)
+                    continue;
+                // Check if element name or tag matches query
+                const matchesQuery = element.name.toLowerCase().includes(queryLower) ||
+                    element.tag.toLowerCase().includes(queryLower);
+                if (matchesQuery) {
+                    results.push({ element, file });
+                    if (results.length >= maxResults)
+                        return results;
+                }
+            }
+        }
+        return results;
+    }
+}
+exports.QueryEngine = QueryEngine;
+//# sourceMappingURL=QueryEngine.js.map

package/dist/core/QueryEngine.js.map

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

package/dist/core/Scanner.d.ts

@@ -0,0 +1,84 @@
+/**
+ * Scanner - Orchestrator using strategy pattern.
+ *
+ * Delegates to strategy classes for clean separation of concerns:
+ * - IgnorePatternMatcher: Pattern matching and .gitignore handling
+ * - DirectoryWalker: Safe directory tree traversal
+ * - DependencyResolver: Import resolution and dependency graph
+ */
+import type { FileSystemProvider } from '../types/contracts/FileSystemProvider';
+import type { FileEntry } from '../types/core';
+import type { EventBus } from './EventBus';
+import type { FileSystemGraph } from './FileSystemGraph';
+/**
+ * Scanner configuration.
+ */
+export interface ScannerConfig {
+    rootPath: string;
+    provider: FileSystemProvider;
+    eventBus: EventBus;
+    graph: FileSystemGraph;
+    ignorePatterns?: string[];
+    bypassHardcodedIgnoreList?: boolean;
+}
+/**
+ * Scan lifecycle event payloads.
+ */
+export interface ScanStartPayload {
+    rootPath: string;
+    startTime: number;
+}
+export interface ScanFilePayload {
+    file: FileEntry;
+    content: string;
+}
+export interface ScanCompletePayload {
+    rootPath: string;
+    filesScanned: number;
+    directoriesScanned: number;
+    durationMs: number;
+}
+/**
+ * Scanner - Thin orchestrator delegating to strategies.
+ */
+export declare class Scanner {
+    private rootPath;
+    private provider;
+    private eventBus;
+    private graph;
+    private debugLogPath;
+    private patternMatcher;
+    private directoryWalker;
+    private dependencyResolver;
+    constructor(config: ScannerConfig);
+    private debugLog;
+    /**
+     * Load .gitignore patterns before scan.
+     */
+    loadGitignore(): Promise<void>;
+    /**
+     * Execute full project scan.
+     */
+    scan(): Promise<{
+        filesScanned: number;
+        directoriesScanned: number;
+        durationMs: number;
+    }>;
+    /**
+     * Process a single file: add to graph, emit event.
+     */
+    private processFile;
+    /**
+     * Add ignore pattern.
+     */
+    addIgnorePattern(pattern: string): void;
+    /**
+     * Remove ignore pattern.
+     */
+    removeIgnorePattern(pattern: string): void;
+    /**
+     * Get current patterns.
+     */
+    getIgnorePatterns(): string[];
+}
+//# sourceMappingURL=Scanner.d.ts.map