@pellux/goodvibes-sdk 0.18.3 → 0.18.11

package/dist/platform/intelligence/facade.js

@@ -0,0 +1,336 @@
+/**
+ * CodeIntelligence — unified facade over tree-sitter and LSP services.
+ *
+ * Design principles:
+ *   - Graceful degradation: never throw, always return safe defaults.
+ *   - LSP is optional; falls back to tree-sitter where possible.
+ *   - Tree-sitter is optional; falls back to empty arrays/null.
+ *   - On initialization, language configs are read and registered with LspService
+ *     so user/project overrides in .goodvibes/sdk/languages/*.json take effect.
+ */
+import { resolve } from 'path';
+import { pathToFileURL, fileURLToPath } from 'url';
+import { loadLanguageConfigs } from './config.js';
+import { TreeSitterService } from './tree-sitter/service.js';
+import { LspService } from './lsp/service.js';
+import { detectLanguage } from './tree-sitter/languages.js';
+import { extractSymbols, extractOutline, findEnclosingScope } from './tree-sitter/queries.js';
+import { logger } from '../utils/logger.js';
+import { summarizeError } from '../utils/error-display.js';
+// ---------------------------------------------------------------------------
+// URI helpers
+// ---------------------------------------------------------------------------
+/**
+ * Convert a filesystem path to a file:// URI.
+ * Correctly handles paths with spaces and special characters.
+ */
+export function pathToUri(filePath) {
+    return pathToFileURL(resolve(filePath)).href;
+}
+/**
+ * Convert a file:// URI back to a filesystem path.
+ * Correctly handles percent-encoded URIs.
+ */
+export function uriToPath(uri) {
+    return fileURLToPath(uri);
+}
+// ---------------------------------------------------------------------------
+// CodeIntelligence
+// ---------------------------------------------------------------------------
+export class CodeIntelligence {
+    treeSitter;
+    lsp;
+    shellPaths;
+    constructor(options = {}) {
+        this.shellPaths = options.shellPaths ?? null;
+        this.treeSitter = options.treeSitter ?? new TreeSitterService();
+        this.lsp = options.lsp ?? (this.shellPaths ? new LspService(this.shellPaths) : null);
+    }
+    // -------------------------------------------------------------------------
+    // Lifecycle
+    // -------------------------------------------------------------------------
+    /**
+     * Initialize all services. Call once at startup.
+     * Loads language configs and registers LSP server commands with LspService
+     * so that user/project overrides in .goodvibes/sdk/languages/ are respected.
+     */
+    async initialize() {
+        if (!this.shellPaths) {
+            try {
+                await this.treeSitter.initialize();
+            }
+            catch (err) {
+                logger.debug('CodeIntelligence: TreeSitterService init error', { error: summarizeError(err) });
+            }
+            return;
+        }
+        // Wire language configs into LspService (resolves config/facade disconnection).
+        // Only register languages that have an LSP command defined — don't overwrite
+        // configs that were already registered via registerServer().
+        try {
+            const lsp = this.lsp;
+            if (!lsp) {
+                await this.treeSitter.initialize();
+                return;
+            }
+            const configs = loadLanguageConfigs(this.shellPaths);
+            for (const [langId, cfg] of configs) {
+                if (cfg.lsp) {
+                    lsp.registerServer(langId, {
+                        command: cfg.lsp.command,
+                        args: cfg.lsp.args,
+                        initializationOptions: cfg.lsp.initializationOptions,
+                    });
+                }
+            }
+        }
+        catch (err) {
+            logger.debug('CodeIntelligence: failed to load language configs', { error: summarizeError(err) });
+        }
+        // Initialize tree-sitter WASM loader.
+        try {
+            await this.treeSitter.initialize();
+        }
+        catch (err) {
+            logger.debug('CodeIntelligence: TreeSitterService init error', { error: summarizeError(err) });
+        }
+        // LspService has no async init; LSP servers are started on demand.
+    }
+    /** Shutdown all owned services for this facade instance. */
+    async dispose() {
+        try {
+            await this.lsp?.shutdown();
+        }
+        catch (err) {
+            logger.debug('LSP shutdown error', { error: summarizeError(err) });
+        }
+        try {
+            this.treeSitter.dispose();
+        }
+        catch (err) {
+            logger.debug('TreeSitter dispose error', { error: summarizeError(err) });
+        }
+    }
+    // -------------------------------------------------------------------------
+    // Private helpers
+    // -------------------------------------------------------------------------
+    /**
+     * Parse a file and load its tree-sitter language in one step.
+     * Returns null if the language is unknown or grammar unavailable.
+     */
+    async _parseFile(filePath, content) {
+        const lang = detectLanguage(filePath);
+        if (!lang)
+            return null;
+        const tree = await this.treeSitter.parse(filePath, content, lang);
+        if (!tree)
+            return null;
+        const language = await this.treeSitter.loadLanguage(lang);
+        if (!language)
+            return null;
+        return { tree, language, lang };
+    }
+    // -------------------------------------------------------------------------
+    // Tree-sitter operations
+    // -------------------------------------------------------------------------
+    /** Detect the language of a file by its extension. */
+    detectLanguage(filePath) {
+        return detectLanguage(filePath);
+    }
+    /** Check if a tree-sitter grammar is loaded for a file's language. */
+    hasTreeSitter(filePath) {
+        const lang = detectLanguage(filePath);
+        if (!lang)
+            return false;
+        return this.treeSitter.loadedLanguages.includes(lang);
+    }
+    /**
+     * Parse a file and extract symbols.
+     * Returns empty array if no grammar is loaded for the language.
+     */
+    async getSymbols(filePath, content) {
+        try {
+            const parsed = await this._parseFile(filePath, content);
+            if (!parsed)
+                return [];
+            return extractSymbols(parsed.tree, parsed.language, parsed.lang);
+        }
+        catch (err) {
+            logger.debug('CodeIntelligence.getSymbols error', { filePath, error: summarizeError(err) });
+            return [];
+        }
+    }
+    /**
+     * Parse a file and extract an outline (signatures only).
+     * Returns empty array if no grammar is loaded for the language.
+     */
+    async getOutline(filePath, content) {
+        try {
+            const parsed = await this._parseFile(filePath, content);
+            if (!parsed)
+                return [];
+            return extractOutline(parsed.tree, parsed.language, parsed.lang);
+        }
+        catch (err) {
+            logger.debug('CodeIntelligence.getOutline error', { filePath, error: summarizeError(err) });
+            return [];
+        }
+    }
+    /**
+     * Find the scope (function/class) enclosing a line.
+     * Returns null if unavailable.
+     */
+    async getEnclosingScope(filePath, content, line) {
+        try {
+            const parsed = await this._parseFile(filePath, content);
+            if (!parsed)
+                return null;
+            return findEnclosingScope(parsed.tree, parsed.language, parsed.lang, line);
+        }
+        catch (err) {
+            logger.debug('CodeIntelligence.getEnclosingScope error', { filePath, error: summarizeError(err) });
+            return null;
+        }
+    }
+    // -------------------------------------------------------------------------
+    // LSP operations
+    // -------------------------------------------------------------------------
+    /** Check if an LSP server is available for a file's language. */
+    async hasLsp(filePath) {
+        if (!this.lsp)
+            return false;
+        const lang = detectLanguage(filePath);
+        if (!lang)
+            return false;
+        try {
+            return await this.lsp.isAvailable(lang);
+        }
+        catch (err) {
+            logger.debug('hasLsp error', { error: summarizeError(err) });
+            return false;
+        }
+    }
+    /**
+     * Get definition location.
+     * Returns null if LSP not available for the file's language.
+     */
+    async getDefinition(filePath, line, column) {
+        const lang = detectLanguage(filePath);
+        if (!lang)
+            return null;
+        try {
+            const client = await this.lsp?.getClient(lang);
+            if (!client)
+                return null;
+            const uri = pathToUri(filePath);
+            const result = await client.request('textDocument/definition', {
+                textDocument: { uri },
+                position: { line, character: column },
+            });
+            if (!result)
+                return null;
+            if (Array.isArray(result))
+                return result[0] ?? null;
+            return result;
+        }
+        catch (err) {
+            logger.debug('CodeIntelligence.getDefinition error', { filePath, error: summarizeError(err) });
+            return null;
+        }
+    }
+    /**
+     * Get all references to a symbol.
+     * Returns empty array if LSP not available.
+     */
+    async getReferences(filePath, line, column) {
+        const lang = detectLanguage(filePath);
+        if (!lang)
+            return [];
+        try {
+            const client = await this.lsp?.getClient(lang);
+            if (!client)
+                return [];
+            const uri = pathToUri(filePath);
+            const result = await client.request('textDocument/references', {
+                textDocument: { uri },
+                position: { line, character: column },
+                context: { includeDeclaration: true },
+            });
+            return result ?? [];
+        }
+        catch (err) {
+            logger.debug('CodeIntelligence.getReferences error', { filePath, error: summarizeError(err) });
+            return [];
+        }
+    }
+    /**
+     * Get document symbols.
+     * Tries LSP first; falls back to tree-sitter if LSP is unavailable.
+     */
+    async getDocumentSymbols(filePath, content) {
+        const lang = detectLanguage(filePath);
+        // Try LSP first
+        if (lang) {
+            try {
+                const client = await this.lsp?.getClient(lang);
+                if (client) {
+                    const uri = pathToUri(filePath);
+                    const lspSymbols = await client.request('textDocument/documentSymbol', { textDocument: { uri } });
+                    if (lspSymbols && lspSymbols.length > 0)
+                        return lspSymbols;
+                }
+            }
+            catch (err) {
+                logger.debug('CodeIntelligence.getDocumentSymbols LSP error', { filePath, error: summarizeError(err) });
+            }
+        }
+        // Fall back to tree-sitter
+        return this.getSymbols(filePath, content);
+    }
+    /**
+     * Get hover information.
+     * Returns null if LSP not available.
+     */
+    async getHover(filePath, line, column) {
+        const lang = detectLanguage(filePath);
+        if (!lang)
+            return null;
+        try {
+            const client = await this.lsp?.getClient(lang);
+            if (!client)
+                return null;
+            const uri = pathToUri(filePath);
+            return await client.request('textDocument/hover', {
+                textDocument: { uri },
+                position: { line, character: column },
+            }) ?? null;
+        }
+        catch (err) {
+            logger.debug('CodeIntelligence.getHover error', { filePath, error: summarizeError(err) });
+            return null;
+        }
+    }
+    /**
+     * Get diagnostics for a file.
+     * Returns empty array if LSP not available.
+     * Note: LSP pushes diagnostics via textDocument/publishDiagnostics notifications;
+     * this method is a best-effort pull (not all servers support textDocument/diagnostic).
+     */
+    async getDiagnostics(filePath) {
+        const lang = detectLanguage(filePath);
+        if (!lang)
+            return [];
+        try {
+            const client = await this.lsp?.getClient(lang);
+            if (!client)
+                return [];
+            const uri = pathToUri(filePath);
+            const result = await client.request('textDocument/diagnostic', { textDocument: { uri } });
+            return result?.items ?? [];
+        }
+        catch (err) {
+            logger.debug('CodeIntelligence.getDiagnostics error', { filePath, error: summarizeError(err) });
+            return [];
+        }
+    }
+}

package/dist/platform/intelligence/import-graph.d.ts

@@ -0,0 +1,83 @@
+/**
+ * Import graph for TypeScript/JavaScript files.
+ *
+ * Builds a reverse dependency index (dependents map) by scanning the project
+ * tree for import/export/require statements. Caches the result and rebuilds
+ * when a file is marked as modified.
+ *
+ * Usage:
+ *   const graph = new ImportGraph();
+ *   await graph.build(projectRoot);
+ *   const affected = graph.findDependents('/abs/path/to/file.ts');
+ */
+/** Absolute path → set of absolute paths that import it */
+export type DependentsMap = Map<string, Set<string>>;
+/** Absolute path → set of absolute paths it imports */
+export type ImportsMap = Map<string, Set<string>>;
+/**
+ * Extract all module specifiers (import/export/require) from a file's text.
+ * Returns only relative specifiers (starting with '.').
+ */
+declare function extractRelativeSpecifiers(content: string): string[];
+export declare const extractRelativeSpecifiersForTest: typeof extractRelativeSpecifiers;
+export declare function resolveSpecifierForTest(fromFile: string, spec: string, knownFiles: Iterable<string>): string | null;
+export declare class ImportGraph {
+    /** Forward map: file → files it imports */
+    private imports;
+    /** Reverse map: file → files that import it */
+    private dependents;
+    /** Root that was last scanned */
+    private scannedRoot;
+    /** Whether graph is stale and needs a rebuild */
+    private dirty;
+    constructor();
+    /**
+     * Mark the graph as stale. Call this whenever a file has been modified
+     * so the next findDependents() call triggers a rebuild.
+     */
+    markDirty(): void;
+    /**
+     * Build (or rebuild) the import graph by scanning all source files under
+     * `projectRoot`. Idempotent when not dirty and root hasn't changed.
+     */
+    build(projectRoot: string): Promise<void>;
+    /**
+     * Build the graph from an in-memory file map for deterministic tests.
+     * Keys must be absolute file paths.
+     * @internal
+     */
+    buildFromFilesForTest(files: Record<string, string>): void;
+    /**
+     * Return all files that directly import `filePath`.
+     * Returns an empty array if the graph hasn't been built or the file isn't known.
+     */
+    findDependents(filePath: string): string[];
+    /**
+     * Return all files that transitively depend on `filePath`.
+     * BFS from the direct dependents.
+     */
+    findTransitiveDependents(filePath: string): string[];
+    /**
+     * Return the set of files `filePath` directly imports.
+     * @internal
+     */
+    findImports(filePath: string): string[];
+    /**
+     * Return graph statistics.
+     * @internal
+     */
+    stats(): {
+        files: number;
+        edges: number;
+        scannedRoot: string | null;
+        dirty: boolean;
+    };
+    /**
+     * Export as a plain object keyed by relative paths (relative to `projectRoot`).
+     * Useful for serialization and the analyze tool's `dependencies` mode.
+     * @internal
+     */
+    toRelativeGraph(projectRoot: string): Record<string, string[]>;
+}
+export {};
+//# sourceMappingURL=import-graph.d.ts.map

package/dist/platform/intelligence/import-graph.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"import-graph.d.ts","sourceRoot":"","sources":["../../../src/platform/intelligence/import-graph.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAWH,2DAA2D;AAC3D,MAAM,MAAM,aAAa,GAAG,GAAG,CAAC,MAAM,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC;AAErD,uDAAuD;AACvD,MAAM,MAAM,UAAU,GAAG,GAAG,CAAC,MAAM,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC;AAalD;;;GAGG;AACH,iBAAS,yBAAyB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,EAAE,CAS5D;AAED,eAAO,MAAM,gCAAgC,kCAA4B,CAAC;AAuC1E,wBAAgB,uBAAuB,CACrC,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,MAAM,EACZ,UAAU,EAAE,QAAQ,CAAC,MAAM,CAAC,GAC3B,MAAM,GAAG,IAAI,CAGf;AAoCD,qBAAa,WAAW;IACtB,2CAA2C;IAC3C,OAAO,CAAC,OAAO,CAAyB;IAExC,+CAA+C;IAC/C,OAAO,CAAC,UAAU,CAA4B;IAE9C,iCAAiC;IACjC,OAAO,CAAC,WAAW,CAAuB;IAE1C,iDAAiD;IACjD,OAAO,CAAC,KAAK,CAAQ;;IAIrB;;;OAGG;IACH,SAAS,IAAI,IAAI;IAIjB;;;OAGG;IACG,KAAK,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAmD/C;;;;OAIG;IACH,qBAAqB,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,IAAI;IA2B1D;;;OAGG;IACH,cAAc,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,EAAE;IAI1C;;;OAGG;IACH,wBAAwB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,EAAE;IAiBpD;;;OAGG;IACH,WAAW,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,EAAE;IAIvC;;;OAGG;IACH,KAAK,IAAI;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;QAAC,KAAK,EAAE,OAAO,CAAA;KAAE;IAQrF;;;;OAIG;IACH,eAAe,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC;CAQ/D"}

package/dist/platform/intelligence/import-graph.js

@@ -0,0 +1,257 @@
+/**
+ * Import graph for TypeScript/JavaScript files.
+ *
+ * Builds a reverse dependency index (dependents map) by scanning the project
+ * tree for import/export/require statements. Caches the result and rebuilds
+ * when a file is marked as modified.
+ *
+ * Usage:
+ *   const graph = new ImportGraph();
+ *   await graph.build(projectRoot);
+ *   const affected = graph.findDependents('/abs/path/to/file.ts');
+ */
+import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
+import { dirname, extname, join, relative, resolve } from 'node:path';
+import { logger } from '../utils/logger.js';
+import { summarizeError } from '../utils/error-display.js';
+const SUPPORTED_EXTENSIONS = new Set(['.ts', '.tsx', '.js', '.jsx', '.mjs', '.cjs']);
+const SKIP_DIRS = new Set(['.git', 'node_modules', 'dist', '.next', '.nuxt', '.cache', '__pycache__']);
+const MAX_FILES = 5_000;
+// ---------------------------------------------------------------------------
+// Import extraction (line-by-line, no catastrophic backtracking)
+// ---------------------------------------------------------------------------
+const IMPORT_RE = /(?:import|export)\s.*?from\s+['"]([^'"]+)['"]/;
+const REQUIRE_RE = /require\(['"]([^'"]+)['"]\)/;
+/**
+ * Extract all module specifiers (import/export/require) from a file's text.
+ * Returns only relative specifiers (starting with '.').
+ */
+function extractRelativeSpecifiers(content) {
+    const specs = [];
+    for (const line of content.split('\n')) {
+        const im = IMPORT_RE.exec(line);
+        if (im?.[1]?.startsWith('.'))
+            specs.push(im[1]);
+        const rq = REQUIRE_RE.exec(line);
+        if (rq?.[1]?.startsWith('.'))
+            specs.push(rq[1]);
+    }
+    return specs;
+}
+export const extractRelativeSpecifiersForTest = extractRelativeSpecifiers;
+/**
+ * Resolve a relative specifier from a source file to an absolute path.
+ * Tries common extensions/index files if an exact match doesn't exist.
+ */
+function resolveSpecifierFromKnownFiles(fromFile, spec, fileExists) {
+    const base = resolve(dirname(fromFile), spec);
+    // Already an exact file?
+    if (fileExists(base))
+        return base;
+    // Try extensions
+    for (const ext of ['.ts', '.tsx', '.js', '.jsx', '.mjs', '.cjs']) {
+        const candidate = base + ext;
+        if (fileExists(candidate))
+            return candidate;
+    }
+    // Try index files
+    for (const index of ['index.ts', 'index.tsx', 'index.js', 'index.jsx']) {
+        const candidate = join(base, index);
+        if (fileExists(candidate))
+            return candidate;
+    }
+    return null;
+}
+function resolveSpecifier(fromFile, spec) {
+    return resolveSpecifierFromKnownFiles(fromFile, spec, (candidate) => existsSync(candidate) && statSync(candidate).isFile());
+}
+export function resolveSpecifierForTest(fromFile, spec, knownFiles) {
+    const fileSet = knownFiles instanceof Set ? knownFiles : new Set(knownFiles);
+    return resolveSpecifierFromKnownFiles(fromFile, spec, (candidate) => fileSet.has(candidate));
+}
+// ---------------------------------------------------------------------------
+// File collection
+// ---------------------------------------------------------------------------
+function collectSourceFiles(dir, results = []) {
+    if (results.length >= MAX_FILES)
+        return results;
+    let entries;
+    try {
+        entries = readdirSync(dir, { withFileTypes: true });
+    }
+    catch (err) {
+        logger.debug('[import-graph] Skipping unreadable directory', { dir, error: summarizeError(err) });
+        return results;
+    }
+    for (const entry of entries) {
+        if (results.length >= MAX_FILES)
+            break;
+        if (SKIP_DIRS.has(entry.name))
+            continue;
+        const full = join(dir, entry.name);
+        if (entry.isDirectory()) {
+            collectSourceFiles(full, results);
+        }
+        else if (entry.isFile() && SUPPORTED_EXTENSIONS.has(extname(entry.name))) {
+            results.push(full);
+        }
+    }
+    return results;
+}
+// ---------------------------------------------------------------------------
+// ImportGraph class
+// ---------------------------------------------------------------------------
+export class ImportGraph {
+    /** Forward map: file → files it imports */
+    imports = new Map();
+    /** Reverse map: file → files that import it */
+    dependents = new Map();
+    /** Root that was last scanned */
+    scannedRoot = null;
+    /** Whether graph is stale and needs a rebuild */
+    dirty = true;
+    constructor() { }
+    /**
+     * Mark the graph as stale. Call this whenever a file has been modified
+     * so the next findDependents() call triggers a rebuild.
+     */
+    markDirty() {
+        this.dirty = true;
+    }
+    /**
+     * Build (or rebuild) the import graph by scanning all source files under
+     * `projectRoot`. Idempotent when not dirty and root hasn't changed.
+     */
+    async build(projectRoot) {
+        if (!this.dirty && this.scannedRoot === projectRoot)
+            return;
+        const files = collectSourceFiles(projectRoot);
+        const imports = new Map();
+        const dependents = new Map();
+        // Ensure every file has an entry, even with no imports
+        for (const f of files) {
+            if (!imports.has(f))
+                imports.set(f, new Set());
+            if (!dependents.has(f))
+                dependents.set(f, new Set());
+        }
+        for (const filePath of files) {
+            let content;
+            try {
+                content = readFileSync(filePath, 'utf-8');
+            }
+            catch (err) {
+                logger.debug('[import-graph] Skipping unreadable file', { file: filePath, error: summarizeError(err) });
+                continue;
+            }
+            const specs = extractRelativeSpecifiers(content);
+            for (const spec of specs) {
+                const resolved = resolveSpecifier(filePath, spec);
+                if (!resolved)
+                    continue;
+                // Forward
+                let fwd = imports.get(filePath);
+                if (!fwd) {
+                    fwd = new Set();
+                    imports.set(filePath, fwd);
+                }
+                fwd.add(resolved);
+                // Reverse
+                let rev = dependents.get(resolved);
+                if (!rev) {
+                    rev = new Set();
+                    dependents.set(resolved, rev);
+                }
+                rev.add(filePath);
+            }
+        }
+        this.imports = imports;
+        this.dependents = dependents;
+        this.scannedRoot = projectRoot;
+        this.dirty = false;
+    }
+    /**
+     * Build the graph from an in-memory file map for deterministic tests.
+     * Keys must be absolute file paths.
+     * @internal
+     */
+    buildFromFilesForTest(files) {
+        const knownFiles = new Set(Object.keys(files));
+        const imports = new Map();
+        const dependents = new Map();
+        for (const filePath of knownFiles) {
+            imports.set(filePath, new Set());
+            dependents.set(filePath, new Set());
+        }
+        for (const [filePath, content] of Object.entries(files)) {
+            const specs = extractRelativeSpecifiers(content);
+            for (const spec of specs) {
+                const resolved = resolveSpecifierFromKnownFiles(filePath, spec, (candidate) => knownFiles.has(candidate));
+                if (!resolved)
+                    continue;
+                imports.get(filePath).add(resolved);
+                dependents.get(resolved).add(filePath);
+            }
+        }
+        this.imports = imports;
+        this.dependents = dependents;
+        this.scannedRoot = null;
+        this.dirty = false;
+    }
+    /**
+     * Return all files that directly import `filePath`.
+     * Returns an empty array if the graph hasn't been built or the file isn't known.
+     */
+    findDependents(filePath) {
+        return Array.from(this.dependents.get(filePath) ?? []);
+    }
+    /**
+     * Return all files that transitively depend on `filePath`.
+     * BFS from the direct dependents.
+     */
+    findTransitiveDependents(filePath) {
+        const visited = new Set();
+        const queue = [filePath];
+        while (queue.length > 0) {
+            const current = queue.shift();
+            for (const dep of this.dependents.get(current) ?? []) {
+                if (!visited.has(dep)) {
+                    visited.add(dep);
+                    queue.push(dep);
+                }
+            }
+        }
+        return Array.from(visited);
+    }
+    /**
+     * Return the set of files `filePath` directly imports.
+     * @internal
+     */
+    findImports(filePath) {
+        return Array.from(this.imports.get(filePath) ?? []);
+    }
+    /**
+     * Return graph statistics.
+     * @internal
+     */
+    stats() {
+        let edges = 0;
+        for (const deps of this.imports.values()) {
+            edges += deps.size;
+        }
+        return { files: this.imports.size, edges, scannedRoot: this.scannedRoot, dirty: this.dirty };
+    }
+    /**
+     * Export as a plain object keyed by relative paths (relative to `projectRoot`).
+     * Useful for serialization and the analyze tool's `dependencies` mode.
+     * @internal
+     */
+    toRelativeGraph(projectRoot) {
+        const result = {};
+        for (const [file, deps] of this.imports) {
+            const key = relative(projectRoot, file);
+            result[key] = Array.from(deps).map((d) => relative(projectRoot, d));
+        }
+        return result;
+    }
+}