hadara 0.3.2 → 0.3.3-rc.0

package/dist/context/code-index.js

@@ -0,0 +1,1154 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CODE_FILE_LANGUAGES = exports.CODE_FILE_KINDS = exports.CODE_INDEX_EDGE_TYPES = exports.CODE_INDEX_IGNORED_PATHS = exports.CODE_INDEX_DEFAULT_BUDGETS = exports.CODE_INDEX_FILE_SUMMARY_CACHE_VERSION = exports.CODE_INDEX_FILE_SUMMARY_CACHE_SCHEMA_ID = exports.CODE_INDEX_FILE_SUMMARY_CACHE_ROOT = exports.CODE_INDEX_CACHE_ROOT = exports.CODE_INDEX_EXTRACTOR_VERSION = exports.CODE_INDEX_COMMAND = exports.CODE_INDEX_SCHEMA_ID = void 0;
+exports.buildCodeIndexReport = buildCodeIndexReport;
+exports.codeIndexFileSummaryCachePath = codeIndexFileSummaryCachePath;
+exports.discoverCodeIndexFiles = discoverCodeIndexFiles;
+exports.createCodeFileNode = createCodeFileNode;
+exports.extractCodeFileReferences = extractCodeFileReferences;
+exports.classifyCodeFile = classifyCodeFile;
+exports.detectCodeFileLanguage = detectCodeFileLanguage;
+exports.shouldIgnoreCodeIndexPath = shouldIgnoreCodeIndexPath;
+exports.createCodeFileNodeId = createCodeFileNodeId;
+exports.createCodeSymbolNodeId = createCodeSymbolNodeId;
+exports.toCodeIndexRelativePath = toCodeIndexRelativePath;
+exports.summarizeCodeIndex = summarizeCodeIndex;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const fs_1 = require("../core/fs");
+const extractor_contract_1 = require("./extractor-contract");
+const capability_registry_1 = require("../services/capability-registry");
+exports.CODE_INDEX_SCHEMA_ID = 'hadara.codeIndex.v1';
+exports.CODE_INDEX_COMMAND = 'code.index';
+exports.CODE_INDEX_EXTRACTOR_VERSION = 'c2-code-index-v1';
+exports.CODE_INDEX_CACHE_ROOT = '.hadara/local/cache/context';
+exports.CODE_INDEX_FILE_SUMMARY_CACHE_ROOT = `${exports.CODE_INDEX_CACHE_ROOT}/code-index-files`;
+exports.CODE_INDEX_FILE_SUMMARY_CACHE_SCHEMA_ID = 'hadara.codeIndex.fileSummaryCacheRecord.v1';
+exports.CODE_INDEX_FILE_SUMMARY_CACHE_VERSION = 'c6.6-code-index-file-summary-v1';
+exports.CODE_INDEX_DEFAULT_BUDGETS = {
+    maxIndexedFiles: 2000,
+    maxIndexedBytes: 20 * 1024 * 1024,
+    maxSingleFileBytes: 1024 * 1024
+};
+exports.CODE_INDEX_IGNORED_PATHS = [
+    'node_modules',
+    'dist',
+    'coverage',
+    '.git',
+    '.hadara/local',
+    '.hadara/tmp',
+    '.pytest_cache',
+    '.mypy_cache',
+    '.ruff_cache',
+    '.venv',
+    'venv'
+];
+exports.CODE_INDEX_EDGE_TYPES = [
+    'IMPORTS',
+    'EXPORTS',
+    'DEFINES_SYMBOL',
+    'TESTS_FILE',
+    'IMPLEMENTS_COMMAND',
+    'REFERENCED_BY_DOC',
+    'VALIDATED_BY_EVIDENCE'
+];
+exports.CODE_FILE_KINDS = ['source', 'test', 'fixture', 'script', 'config', 'unknown'];
+exports.CODE_FILE_LANGUAGES = ['typescript', 'javascript', 'json', 'markdown', 'unknown'];
+const COMMAND_REGISTRY_SOURCE_PATH = 'src/services/capability-registry.ts';
+function buildCodeIndexReport(options) {
+    const generatedAt = options.generatedAt ?? new Date().toISOString();
+    const budgets = normalizeCodeIndexBudgets(options.budgets);
+    const discovered = discoverCodeIndexInputs(options.projectRoot, {
+        budgets,
+        sourceEntries: options.sourceEntries
+    });
+    const rawSummaries = [];
+    const issues = [...discovered.issues];
+    let indexedBytes = 0;
+    let skippedFiles = discovered.skippedFiles;
+    const cacheStats = createCodeIndexFileSummaryCacheStats();
+    const cacheOptions = options.fileSummaryCache;
+    const extractorVersion = cacheOptions?.extractorVersion ?? exports.CODE_INDEX_EXTRACTOR_VERSION;
+    for (const relativePath of discovered.paths) {
+        const absolutePath = node_path_1.default.join(options.projectRoot, relativePath);
+        try {
+            const sourceEntry = discovered.sourceEntriesByPath.get(relativePath) ?? createCodeIndexSourceEntry(options.projectRoot, relativePath);
+            if (sourceEntry.sizeBytes > budgets.maxSingleFileBytes) {
+                skippedFiles += 1;
+                issues.push(createBudgetIssue({
+                    message: `Skipped ${relativePath} because it exceeds the single-file code index budget (${sourceEntry.sizeBytes} bytes > ${budgets.maxSingleFileBytes} bytes).`,
+                    path: relativePath,
+                    fixHint: 'Reduce the file size or wait for a future configurable code index budget.'
+                }));
+                continue;
+            }
+            if (indexedBytes + sourceEntry.sizeBytes > budgets.maxIndexedBytes) {
+                skippedFiles += 1;
+                issues.push(createBudgetIssue({
+                    message: `Skipped ${relativePath} because the code index byte budget would be exceeded (${indexedBytes + sourceEntry.sizeBytes} bytes > ${budgets.maxIndexedBytes} bytes).`,
+                    path: relativePath,
+                    fixHint: 'Reduce indexed source size or wait for a future configurable code index budget.'
+                }));
+                continue;
+            }
+            const cached = readCodeIndexFileSummaryCache({
+                projectRoot: options.projectRoot,
+                sourceEntry,
+                cacheOptions,
+                extractorVersion
+            });
+            updateCodeIndexFileSummaryCacheStats(cacheStats, cached.status);
+            if (cached.issue)
+                issues.push(cached.issue);
+            if (cached.summary) {
+                rawSummaries.push(cached.summary);
+                indexedBytes += sourceEntry.sizeBytes;
+                continue;
+            }
+            const content = node_fs_1.default.readFileSync(absolutePath, 'utf8');
+            indexedBytes += sourceEntry.sizeBytes;
+            const summary = extractCodeFileSummary({
+                projectRoot: options.projectRoot,
+                path: relativePath,
+                content,
+                sizeBytes: sourceEntry.sizeBytes
+            });
+            issues.push(...summary.issues);
+            rawSummaries.push(summary);
+            if (cacheOptions?.mode === 'read-write') {
+                writeCodeIndexFileSummaryCache({
+                    projectRoot: options.projectRoot,
+                    sourceEntry,
+                    summary,
+                    createdAt: cacheOptions.createdAt ?? generatedAt,
+                    extractorVersion
+                });
+            }
+        }
+        catch (error) {
+            issues.push({
+                severity: 'warning',
+                code: 'CODE_INDEX_FILE_READ_FAILED',
+                message: `Failed to read code index file ${relativePath}: ${error instanceof Error ? error.message : String(error)}.`,
+                path: relativePath,
+                fixHint: 'Check file permissions or remove the unreadable file from indexed source paths.'
+            });
+        }
+    }
+    const sanitized = sanitizeCodeFileSummaries(rawSummaries);
+    const fileSummaries = sanitized.summaries;
+    issues.push(...sanitized.issues);
+    const commandHints = createCommandHints(fileSummaries);
+    const commandFamiliesByPath = createCommandFamiliesByPath(commandHints);
+    const files = fileSummaries.map((summary) => createCodeFileNodeFromSummary(summary, {
+        imports: summary.imports.map((importReference) => importReference.resolvedPath ?? importReference.specifier),
+        exports: summary.exports.map((exportReference) => exportReference.name),
+        commandFamilies: commandFamiliesByPath.get(summary.filePath) ?? []
+    }));
+    const symbols = createCodeSymbolNodes(fileSummaries);
+    const edges = [
+        ...createImportEdges(fileSummaries),
+        ...createSymbolEdges(fileSummaries),
+        ...createCommandHintEdges(fileSummaries, commandHints),
+        ...createTestRelationEdges(options.projectRoot, fileSummaries)
+    ].sort((a, b) => a.id.localeCompare(b.id));
+    return {
+        schemaVersion: exports.CODE_INDEX_SCHEMA_ID,
+        command: exports.CODE_INDEX_COMMAND,
+        ok: !issues.some((issue) => issue.severity === 'error'),
+        generatedAt,
+        projectRoot: options.projectRoot,
+        sourceHash: (0, extractor_contract_1.hashContextGraphSources)(files.map((file) => ({ path: file.path, hash: file.hash }))),
+        files,
+        symbols,
+        edges,
+        summary: summarizeCodeIndex(files, symbols, edges, issues),
+        budget: {
+            ...budgets,
+            indexedFiles: files.length,
+            indexedBytes,
+            skippedFiles
+        },
+        cache: createCodeIndexCacheMetadata(cacheOptions, cacheStats),
+        issues
+    };
+}
+function codeIndexFileSummaryCachePath(relativePath) {
+    const normalizedPath = (0, extractor_contract_1.normalizeContextGraphPath)(relativePath);
+    const fingerprint = (0, extractor_contract_1.hashContextGraphText)(normalizedPath).replace(/^sha256:/, '');
+    return `${exports.CODE_INDEX_FILE_SUMMARY_CACHE_ROOT}/${fingerprint}.json`;
+}
+function discoverCodeIndexFiles(projectRoot, options = {}) {
+    const budgets = normalizeCodeIndexBudgets(options.budgets);
+    const paths = [];
+    const issues = [];
+    let skippedFiles = 0;
+    let fileBudgetIssueRecorded = false;
+    const root = node_path_1.default.resolve(projectRoot);
+    function visit(relativeDir) {
+        if (relativeDir && shouldIgnoreCodeIndexPath(relativeDir))
+            return;
+        const absoluteDir = node_path_1.default.join(root, relativeDir);
+        let entries;
+        try {
+            entries = node_fs_1.default.readdirSync(absoluteDir, { withFileTypes: true });
+        }
+        catch (error) {
+            issues.push({
+                severity: 'warning',
+                code: 'CODE_INDEX_FILE_READ_FAILED',
+                message: `Failed to read code index directory ${(0, extractor_contract_1.normalizeContextGraphPath)(relativeDir || '.')}: ${error instanceof Error ? error.message : String(error)}.`,
+                path: (0, extractor_contract_1.normalizeContextGraphPath)(relativeDir || '.'),
+                fixHint: 'Check directory permissions or remove the unreadable directory from indexed source paths.'
+            });
+            return;
+        }
+        for (const entry of entries.sort((a, b) => a.name.localeCompare(b.name))) {
+            const relativePath = (0, extractor_contract_1.normalizeContextGraphPath)(node_path_1.default.join(relativeDir, entry.name));
+            if (shouldIgnoreCodeIndexPath(relativePath))
+                continue;
+            if (entry.isDirectory()) {
+                visit(relativePath);
+                continue;
+            }
+            if (entry.isFile() && classifyCodeFile(relativePath) !== 'unknown') {
+                if (paths.length >= budgets.maxIndexedFiles) {
+                    skippedFiles += 1;
+                    if (!fileBudgetIssueRecorded) {
+                        fileBudgetIssueRecorded = true;
+                        issues.push(createBudgetIssue({
+                            message: `Code index exceeded max indexed files budget (${budgets.maxIndexedFiles}); partial results returned.`,
+                            path: relativePath,
+                            fixHint: 'Reduce indexed files or wait for a future configurable code index budget.'
+                        }));
+                    }
+                    continue;
+                }
+                paths.push(relativePath);
+            }
+        }
+    }
+    visit('');
+    return { paths: Array.from(new Set(paths)).sort(), issues, skippedFiles };
+}
+function discoverCodeIndexInputs(projectRoot, options) {
+    if (!options.sourceEntries) {
+        const discovered = discoverCodeIndexFiles(projectRoot, { budgets: options.budgets });
+        return {
+            ...discovered,
+            sourceEntriesByPath: new Map()
+        };
+    }
+    const sourceEntriesByPath = new Map();
+    const paths = [];
+    const issues = [];
+    let skippedFiles = 0;
+    let fileBudgetIssueRecorded = false;
+    for (const sourceEntry of options.sourceEntries) {
+        if (!sourceEntry.extractorKeys?.includes('codeIndex'))
+            continue;
+        const relativePath = (0, extractor_contract_1.normalizeContextGraphPath)(sourceEntry.path);
+        if (shouldIgnoreCodeIndexPath(relativePath) || classifyCodeFile(relativePath) === 'unknown')
+            continue;
+        if (paths.length >= options.budgets.maxIndexedFiles) {
+            skippedFiles += 1;
+            if (!fileBudgetIssueRecorded) {
+                fileBudgetIssueRecorded = true;
+                issues.push(createBudgetIssue({
+                    message: `Code index exceeded max indexed files budget (${options.budgets.maxIndexedFiles}); partial results returned.`,
+                    path: relativePath,
+                    fixHint: 'Reduce indexed files or wait for a future configurable code index budget.'
+                }));
+            }
+            continue;
+        }
+        const normalizedEntry = {
+            ...sourceEntry,
+            path: relativePath
+        };
+        paths.push(relativePath);
+        sourceEntriesByPath.set(relativePath, normalizedEntry);
+    }
+    return {
+        paths: Array.from(new Set(paths)).sort(),
+        sourceEntriesByPath,
+        issues,
+        skippedFiles
+    };
+}
+function createCodeIndexSourceEntry(projectRoot, relativePath) {
+    const normalizedPath = (0, extractor_contract_1.normalizeContextGraphPath)(relativePath);
+    const stats = node_fs_1.default.statSync(node_path_1.default.join(projectRoot, normalizedPath));
+    return {
+        path: normalizedPath,
+        sizeBytes: stats.size,
+        mtimeMs: stats.mtimeMs,
+        metadataHash: (0, extractor_contract_1.hashContextGraphJson)({
+            path: normalizedPath,
+            sizeBytes: stats.size,
+            mtimeMs: stats.mtimeMs
+        }),
+        extractorKeys: ['codeIndex']
+    };
+}
+function normalizeCodeIndexBudgets(input = {}) {
+    return {
+        maxIndexedFiles: normalizeBudgetValue(input.maxIndexedFiles, exports.CODE_INDEX_DEFAULT_BUDGETS.maxIndexedFiles),
+        maxIndexedBytes: normalizeBudgetValue(input.maxIndexedBytes, exports.CODE_INDEX_DEFAULT_BUDGETS.maxIndexedBytes),
+        maxSingleFileBytes: normalizeBudgetValue(input.maxSingleFileBytes, exports.CODE_INDEX_DEFAULT_BUDGETS.maxSingleFileBytes)
+    };
+}
+function normalizeBudgetValue(value, fallback) {
+    if (value === undefined || !Number.isFinite(value))
+        return fallback;
+    return Math.max(0, Math.floor(value));
+}
+function createBudgetIssue(input) {
+    return {
+        severity: 'warning',
+        code: 'CODE_INDEX_TOO_LARGE',
+        message: input.message,
+        ...(input.path ? { path: input.path } : {}),
+        fixHint: input.fixHint
+    };
+}
+function createCodeFileNode(relativePath, content, metadata = {}) {
+    const normalizedPath = (0, extractor_contract_1.normalizeContextGraphPath)(relativePath);
+    return {
+        id: createCodeFileNodeId(normalizedPath),
+        path: normalizedPath,
+        kind: classifyCodeFile(normalizedPath),
+        language: detectCodeFileLanguage(normalizedPath),
+        hash: (0, extractor_contract_1.hashContextGraphText)(content),
+        lineCount: countLines(content),
+        exports: uniqueSorted(metadata.exports ?? []),
+        imports: uniqueSorted(metadata.imports ?? []),
+        commandFamilies: uniqueSorted(metadata.commandFamilies ?? [])
+    };
+}
+function createCodeFileNodeFromSummary(summary, metadata = {}) {
+    return {
+        id: createCodeFileNodeId(summary.filePath),
+        path: (0, extractor_contract_1.normalizeContextGraphPath)(summary.filePath),
+        kind: summary.kind,
+        language: summary.language,
+        hash: summary.hash,
+        lineCount: summary.lineCount,
+        exports: uniqueSorted(metadata.exports ?? []),
+        imports: uniqueSorted(metadata.imports ?? []),
+        commandFamilies: uniqueSorted(metadata.commandFamilies ?? [])
+    };
+}
+function extractCodeFileReferences(input) {
+    const imports = [];
+    const exports = [];
+    const issues = [];
+    const normalizedPath = (0, extractor_contract_1.normalizeContextGraphPath)(input.path);
+    const language = detectCodeFileLanguage(normalizedPath);
+    if (language !== 'typescript' && language !== 'javascript') {
+        return { imports, exports, issues };
+    }
+    const lines = input.content.split(/\r?\n/);
+    lines.forEach((line, index) => {
+        const lineNumber = index + 1;
+        for (const specifier of extractImportSpecifiersFromLine(line)) {
+            const resolvedPath = resolveRelativeCodeImport({
+                projectRoot: input.projectRoot,
+                fromPath: normalizedPath,
+                specifier
+            });
+            imports.push({
+                specifier,
+                ...(resolvedPath ? { resolvedPath } : {}),
+                line: lineNumber
+            });
+            if (isRelativeImportSpecifier(specifier) && !resolvedPath) {
+                issues.push({
+                    severity: 'warning',
+                    code: 'CODE_INDEX_IMPORT_UNRESOLVED',
+                    message: `Could not resolve relative import ${specifier} from ${normalizedPath}.`,
+                    path: normalizedPath,
+                    fixHint: 'Check that the import target exists, uses a supported extension, and is not ignored by code index rules.'
+                });
+            }
+        }
+        for (const exportReference of extractExportReferencesFromLine(line)) {
+            exports.push({ ...exportReference, line: lineNumber });
+        }
+    });
+    return {
+        imports: dedupeImports(imports),
+        exports: dedupeExports(exports),
+        issues
+    };
+}
+function extractCodeFileSummary(input) {
+    const normalizedPath = (0, extractor_contract_1.normalizeContextGraphPath)(input.path);
+    const references = extractCodeFileReferences({
+        projectRoot: input.projectRoot,
+        path: normalizedPath,
+        content: input.content
+    });
+    return {
+        filePath: normalizedPath,
+        kind: classifyCodeFile(normalizedPath),
+        language: detectCodeFileLanguage(normalizedPath),
+        hash: (0, extractor_contract_1.hashContextGraphText)(input.content),
+        lineCount: countLines(input.content),
+        sizeBytes: input.sizeBytes,
+        imports: references.imports,
+        exports: references.exports,
+        commandMentions: extractCommandMentions(input.content),
+        ...(normalizedPath === COMMAND_REGISTRY_SOURCE_PATH
+            ? { commandIdLines: Object.fromEntries(createRegistryLineMap(input.content).entries()) }
+            : {}),
+        issues: references.issues
+    };
+}
+function extractCommandMentions(content) {
+    const mentions = [];
+    for (const entry of (0, capability_registry_1.listCommandRegistryEntries)()) {
+        const line = findCommandMentionLine(content, entry.id);
+        if (line !== undefined)
+            mentions.push({ commandId: entry.id, line });
+    }
+    return mentions.sort((a, b) => `${a.commandId}:${a.line}`.localeCompare(`${b.commandId}:${b.line}`));
+}
+function classifyCodeFile(inputPath) {
+    const filePath = (0, extractor_contract_1.normalizeContextGraphPath)(inputPath);
+    if (filePath === 'package.json' || filePath === 'tsconfig.json')
+        return 'config';
+    if (filePath.startsWith('tests/fixtures/'))
+        return 'fixture';
+    if (filePath.startsWith('tests/') && (filePath.endsWith('.test.ts') || filePath.endsWith('.spec.ts')))
+        return 'test';
+    if (filePath.startsWith('src/') && (filePath.endsWith('.ts') || filePath.endsWith('.js')))
+        return 'source';
+    if (filePath.startsWith('scripts/'))
+        return 'script';
+    return 'unknown';
+}
+function detectCodeFileLanguage(inputPath) {
+    const filePath = (0, extractor_contract_1.normalizeContextGraphPath)(inputPath);
+    if (filePath.endsWith('.ts'))
+        return 'typescript';
+    if (filePath.endsWith('.js'))
+        return 'javascript';
+    if (filePath.endsWith('.json'))
+        return 'json';
+    if (filePath.endsWith('.md'))
+        return 'markdown';
+    return 'unknown';
+}
+function shouldIgnoreCodeIndexPath(inputPath) {
+    const normalizedPath = (0, extractor_contract_1.normalizeContextGraphPath)(inputPath);
+    if (!normalizedPath || normalizedPath === '.')
+        return false;
+    return exports.CODE_INDEX_IGNORED_PATHS.some((ignoredPath) => normalizedPath === ignoredPath || normalizedPath.startsWith(`${ignoredPath}/`));
+}
+function createCodeFileNodeId(inputPath) {
+    return `file:${(0, extractor_contract_1.normalizeContextGraphPath)(inputPath)}`;
+}
+function createCodeSymbolNodeId(inputPath, name) {
+    return `symbol:${(0, extractor_contract_1.normalizeContextGraphPath)(inputPath)}#${name}`;
+}
+function toCodeIndexRelativePath(projectRoot, absoluteOrRelativePath) {
+    return (0, extractor_contract_1.toProjectRelativeContextPath)(projectRoot, absoluteOrRelativePath);
+}
+function summarizeCodeIndex(files, symbols, edges, issues) {
+    return {
+        sourceFiles: files.filter((file) => file.kind === 'source').length,
+        testFiles: files.filter((file) => file.kind === 'test').length,
+        fixtureFiles: files.filter((file) => file.kind === 'fixture').length,
+        configFiles: files.filter((file) => file.kind === 'config').length,
+        symbols: symbols.length,
+        edges: edges.length,
+        degraded: issues.some((issue) => issue.severity === 'warning' || issue.severity === 'error')
+    };
+}
+function sanitizeCodeFileSummaries(summaries) {
+    const availablePaths = new Set(summaries.map((summary) => summary.filePath));
+    const issues = [];
+    return {
+        summaries: summaries.map((summary) => {
+            const imports = summary.imports.map((importReference) => {
+                if (!importReference.resolvedPath || availablePaths.has(importReference.resolvedPath))
+                    return importReference;
+                if (isRelativeImportSpecifier(importReference.specifier)) {
+                    issues.push({
+                        severity: 'warning',
+                        code: 'CODE_INDEX_IMPORT_UNRESOLVED',
+                        message: `Could not resolve relative import ${importReference.specifier} from ${summary.filePath}.`,
+                        path: summary.filePath,
+                        fixHint: 'Check that the import target exists, uses a supported extension, and is not ignored by code index rules.'
+                    });
+                }
+                return {
+                    specifier: importReference.specifier,
+                    line: importReference.line
+                };
+            });
+            return { ...summary, imports: dedupeImports(imports) };
+        }),
+        issues
+    };
+}
+function createCodeIndexFileSummaryCacheStats() {
+    return {
+        readCount: 0,
+        reusedFileCount: 0,
+        recomputedFileCount: 0,
+        missingFileCount: 0,
+        staleFileCount: 0,
+        corruptFileCount: 0,
+        schemaMismatchFileCount: 0
+    };
+}
+function updateCodeIndexFileSummaryCacheStats(stats, status) {
+    if (status === 'disabled')
+        return;
+    stats.readCount += 1;
+    if (status === 'fresh')
+        stats.reusedFileCount += 1;
+    else {
+        stats.recomputedFileCount += 1;
+        if (status === 'missing')
+            stats.missingFileCount += 1;
+        if (status === 'stale')
+            stats.staleFileCount += 1;
+        if (status === 'corrupt')
+            stats.corruptFileCount += 1;
+        if (status === 'schema-mismatch')
+            stats.schemaMismatchFileCount += 1;
+    }
+}
+function createCodeIndexCacheMetadata(cacheOptions, stats) {
+    if (!cacheOptions)
+        return { used: false, hit: false };
+    return {
+        used: stats.reusedFileCount > 0,
+        hit: stats.readCount > 0 && stats.recomputedFileCount === 0,
+        mode: 'code-index-file-summaries',
+        cachePath: exports.CODE_INDEX_FILE_SUMMARY_CACHE_ROOT,
+        readFileSummaryCount: stats.readCount,
+        reusedFileSummaryCount: stats.reusedFileCount,
+        recomputedFileSummaryCount: stats.recomputedFileCount,
+        missingFileSummaryCount: stats.missingFileCount,
+        staleFileSummaryCount: stats.staleFileCount,
+        corruptFileSummaryCount: stats.corruptFileCount,
+        schemaMismatchFileSummaryCount: stats.schemaMismatchFileCount
+    };
+}
+function readCodeIndexFileSummaryCache(input) {
+    if (!input.cacheOptions)
+        return { status: 'disabled' };
+    const cachePath = codeIndexFileSummaryCachePath(input.sourceEntry.path);
+    const absolutePath = node_path_1.default.join(input.projectRoot, cachePath);
+    if (!node_fs_1.default.existsSync(absolutePath))
+        return { status: 'missing', path: cachePath };
+    let parsed;
+    try {
+        parsed = JSON.parse(node_fs_1.default.readFileSync(absolutePath, 'utf8'));
+    }
+    catch (error) {
+        return {
+            status: 'corrupt',
+            path: cachePath,
+            issue: {
+                severity: 'warning',
+                code: 'CODE_INDEX_FILE_CACHE_CORRUPT',
+                message: `Code index file summary cache at ${cachePath} could not be parsed: ${error instanceof Error ? error.message : String(error)}.`,
+                path: input.sourceEntry.path,
+                fixHint: 'Refresh the context cache with context cache warm --execute.'
+            }
+        };
+    }
+    if (!isCodeIndexFileSummaryCacheRecord(parsed)) {
+        return {
+            status: 'schema-mismatch',
+            path: cachePath,
+            issue: {
+                severity: 'warning',
+                code: 'CODE_INDEX_FILE_CACHE_SCHEMA_MISMATCH',
+                message: `Code index file summary cache at ${cachePath} does not match ${exports.CODE_INDEX_FILE_SUMMARY_CACHE_SCHEMA_ID}.`,
+                path: input.sourceEntry.path,
+                fixHint: 'Refresh the context cache with context cache warm --execute.'
+            }
+        };
+    }
+    if (!isFreshCodeIndexFileSummaryCacheRecord(parsed, input.sourceEntry, input.extractorVersion)) {
+        return { status: 'stale', path: cachePath, record: parsed };
+    }
+    return { status: 'fresh', path: cachePath, record: parsed, summary: parsed.summary };
+}
+function writeCodeIndexFileSummaryCache(input) {
+    const normalizedPath = (0, extractor_contract_1.normalizeContextGraphPath)(input.sourceEntry.path);
+    const record = {
+        schemaVersion: exports.CODE_INDEX_FILE_SUMMARY_CACHE_SCHEMA_ID,
+        cacheRecordVersion: exports.CODE_INDEX_FILE_SUMMARY_CACHE_VERSION,
+        createdAt: input.createdAt,
+        path: normalizedPath,
+        extractorVersion: input.extractorVersion,
+        source: {
+            path: normalizedPath,
+            sizeBytes: input.sourceEntry.sizeBytes,
+            ...(input.sourceEntry.mtimeMs === undefined ? {} : { mtimeMs: input.sourceEntry.mtimeMs }),
+            ...(input.sourceEntry.contentHash ? { contentHash: input.sourceEntry.contentHash } : {}),
+            ...(input.sourceEntry.metadataHash ? { metadataHash: input.sourceEntry.metadataHash } : {})
+        },
+        summary: input.summary
+    };
+    (0, fs_1.atomicWriteTextFile)(input.projectRoot, codeIndexFileSummaryCachePath(normalizedPath), `${JSON.stringify(record, null, 2)}\n`);
+    return record;
+}
+function isFreshCodeIndexFileSummaryCacheRecord(record, sourceEntry, extractorVersion) {
+    const normalizedPath = (0, extractor_contract_1.normalizeContextGraphPath)(sourceEntry.path);
+    return record.path === normalizedPath
+        && record.source.path === normalizedPath
+        && record.summary.filePath === normalizedPath
+        && record.extractorVersion === extractorVersion
+        && record.source.sizeBytes === sourceEntry.sizeBytes
+        && record.source.mtimeMs === sourceEntry.mtimeMs
+        && record.source.contentHash === sourceEntry.contentHash
+        && record.source.metadataHash === sourceEntry.metadataHash;
+}
+function isCodeIndexFileSummaryCacheRecord(value) {
+    if (!value || typeof value !== 'object')
+        return false;
+    const record = value;
+    return record.schemaVersion === exports.CODE_INDEX_FILE_SUMMARY_CACHE_SCHEMA_ID
+        && record.cacheRecordVersion === exports.CODE_INDEX_FILE_SUMMARY_CACHE_VERSION
+        && typeof record.createdAt === 'string'
+        && typeof record.path === 'string'
+        && typeof record.extractorVersion === 'string'
+        && Boolean(record.source)
+        && typeof record.source === 'object'
+        && typeof record.source.path === 'string'
+        && typeof record.source.sizeBytes === 'number'
+        && isCodeFileExtractionSummary(record.summary);
+}
+function isCodeFileExtractionSummary(value) {
+    if (!value || typeof value !== 'object')
+        return false;
+    const summary = value;
+    return typeof summary.filePath === 'string'
+        && exports.CODE_FILE_KINDS.includes(summary.kind)
+        && exports.CODE_FILE_LANGUAGES.includes(summary.language)
+        && typeof summary.hash === 'string'
+        && typeof summary.lineCount === 'number'
+        && typeof summary.sizeBytes === 'number'
+        && Array.isArray(summary.imports)
+        && Array.isArray(summary.exports)
+        && Array.isArray(summary.commandMentions)
+        && Array.isArray(summary.issues);
+}
+function countLines(content) {
+    if (content.length === 0)
+        return 0;
+    return content.endsWith('\n') ? content.split('\n').length - 1 : content.split('\n').length;
+}
+function extractImportSpecifiersFromLine(line) {
+    const specifiers = [];
+    const importMatch = line.match(/^\s*import\s+(?:type\s+)?(?:.+?\s+from\s+)?['"]([^'"]+)['"]/);
+    if (importMatch?.[1])
+        specifiers.push(importMatch[1]);
+    const exportFromMatch = line.match(/^\s*export\s+(?:type\s+)?\{[^}]*\}\s+from\s+['"]([^'"]+)['"]/);
+    if (exportFromMatch?.[1])
+        specifiers.push(exportFromMatch[1]);
+    const requirePattern = /require\(\s*['"]([^'"]+)['"]\s*\)/g;
+    for (const requireMatch of line.matchAll(requirePattern)) {
+        if (requireMatch[1])
+            specifiers.push(requireMatch[1]);
+    }
+    return specifiers;
+}
+function extractExportReferencesFromLine(line) {
+    const trimmed = line.trim();
+    const exports = [];
+    const declarationMatch = trimmed.match(/^export\s+(?:async\s+)?(function|class|interface|type|const)\s+([A-Za-z_$][\w$]*)/);
+    if (declarationMatch?.[1] && declarationMatch[2]) {
+        exports.push({
+            name: declarationMatch[2],
+            kind: declarationMatch[1]
+        });
+    }
+    const listMatch = trimmed.match(/^export\s+(?:type\s+)?\{([^}]+)\}/);
+    if (listMatch?.[1]) {
+        for (const part of listMatch[1].split(',')) {
+            const candidate = part.trim();
+            if (!candidate)
+                continue;
+            const aliasParts = candidate.split(/\s+as\s+/);
+            const exportedName = (aliasParts[aliasParts.length - 1] ?? '').trim();
+            if (/^[A-Za-z_$][\w$]*$/.test(exportedName))
+                exports.push({
+                    name: exportedName,
+                    kind: 'unknown'
+                });
+        }
+    }
+    return exports;
+}
+function resolveRelativeCodeImport(input) {
+    if (!isRelativeImportSpecifier(input.specifier))
+        return undefined;
+    const fromDir = node_path_1.default.posix.dirname((0, extractor_contract_1.normalizeContextGraphPath)(input.fromPath));
+    const basePath = (0, extractor_contract_1.normalizeContextGraphPath)(node_path_1.default.posix.join(fromDir, input.specifier));
+    const candidates = [
+        basePath,
+        `${basePath}.ts`,
+        `${basePath}.js`,
+        `${basePath}.json`,
+        `${basePath}/index.ts`,
+        `${basePath}/index.js`,
+        `${basePath}/index.json`
+    ];
+    for (const candidate of candidates) {
+        if (shouldIgnoreCodeIndexPath(candidate) || classifyCodeFile(candidate) === 'unknown')
+            continue;
+        if (node_fs_1.default.existsSync(node_path_1.default.join(input.projectRoot, candidate)))
+            return candidate;
+    }
+    return undefined;
+}
+function createImportEdges(importReferences) {
+    const edges = [];
+    const seen = new Set();
+    for (const sourceFile of importReferences) {
+        const from = createCodeFileNodeId(sourceFile.filePath);
+        for (const importReference of sourceFile.imports) {
+            if (!importReference.resolvedPath)
+                continue;
+            const source = (0, extractor_contract_1.createContextGraphSourceRef)({
+                path: sourceFile.filePath,
+                line: importReference.line,
+                hash: sourceFile.hash,
+                extractor: 'extractCodeImports'
+            });
+            const edge = {
+                id: createCodeEdgeId({
+                    type: 'IMPORTS',
+                    from,
+                    to: createCodeFileNodeId(importReference.resolvedPath),
+                    source,
+                    reason: `File ${sourceFile.filePath} imports ${importReference.resolvedPath}.`
+                }),
+                from,
+                to: createCodeFileNodeId(importReference.resolvedPath),
+                type: 'IMPORTS',
+                confidence: 'explicit',
+                reason: `File ${sourceFile.filePath} imports ${importReference.resolvedPath}.`,
+                source
+            };
+            if (seen.has(edge.id))
+                continue;
+            seen.add(edge.id);
+            edges.push(edge);
+        }
+    }
+    return edges.sort((a, b) => a.id.localeCompare(b.id));
+}
+function createCodeSymbolNodes(fileReferences) {
+    const symbols = [];
+    const seen = new Set();
+    for (const sourceFile of fileReferences) {
+        for (const exportReference of sourceFile.exports) {
+            const id = createCodeSymbolNodeId(sourceFile.filePath, exportReference.name);
+            if (seen.has(id))
+                continue;
+            seen.add(id);
+            symbols.push({
+                id,
+                name: exportReference.name,
+                kind: exportReference.kind,
+                path: (0, extractor_contract_1.normalizeContextGraphPath)(sourceFile.filePath),
+                exported: true,
+                line: exportReference.line
+            });
+        }
+    }
+    return symbols.sort((a, b) => a.id.localeCompare(b.id));
+}
+function createSymbolEdges(fileReferences) {
+    const edges = [];
+    const seen = new Set();
+    for (const sourceFile of fileReferences) {
+        const from = createCodeFileNodeId(sourceFile.filePath);
+        for (const exportReference of sourceFile.exports) {
+            const to = createCodeSymbolNodeId(sourceFile.filePath, exportReference.name);
+            const source = (0, extractor_contract_1.createContextGraphSourceRef)({
+                path: sourceFile.filePath,
+                line: exportReference.line,
+                hash: sourceFile.hash,
+                extractor: 'extractCodeSymbols'
+            });
+            for (const type of ['DEFINES_SYMBOL', 'EXPORTS']) {
+                const reason = type === 'DEFINES_SYMBOL'
+                    ? `File ${sourceFile.filePath} defines exported symbol ${exportReference.name}.`
+                    : `File ${sourceFile.filePath} exports symbol ${exportReference.name}.`;
+                const edge = {
+                    id: createCodeEdgeId({ type, from, to, source, reason }),
+                    from,
+                    to,
+                    type,
+                    confidence: 'explicit',
+                    reason,
+                    source
+                };
+                if (seen.has(edge.id))
+                    continue;
+                seen.add(edge.id);
+                edges.push(edge);
+            }
+        }
+    }
+    return edges.sort((a, b) => a.id.localeCompare(b.id));
+}
+function createCommandHints(fileReferences) {
+    const availablePaths = new Set(fileReferences.map((reference) => reference.filePath));
+    const registryLineByCommand = new Map(Object.entries(fileReferences.find((reference) => reference.filePath === COMMAND_REGISTRY_SOURCE_PATH)?.commandIdLines ?? {}));
+    const hints = [];
+    for (const entry of (0, capability_registry_1.listCommandRegistryEntries)()) {
+        const explicitImplementationFiles = normalizeExistingHintPaths(entry.implementationFiles ?? [], availablePaths);
+        const heuristicImplementationFiles = explicitImplementationFiles.length > 0
+            ? []
+            : normalizeExistingHintPaths(inferCommandImplementationFiles(entry), availablePaths);
+        const testFiles = normalizeExistingHintPaths(entry.testFiles ?? [], availablePaths);
+        if (explicitImplementationFiles.length === 0 && heuristicImplementationFiles.length === 0 && testFiles.length === 0) {
+            continue;
+        }
+        hints.push({
+            commandId: entry.id,
+            commandFamily: entry.family,
+            implementationFiles: explicitImplementationFiles.length > 0 ? explicitImplementationFiles : heuristicImplementationFiles,
+            implementationConfidence: explicitImplementationFiles.length > 0 ? 'explicit' : 'heuristic',
+            testFiles,
+            sourceLine: registryLineByCommand.get(entry.id)
+        });
+    }
+    return hints.sort((a, b) => a.commandId.localeCompare(b.commandId));
+}
+function createCommandFamiliesByPath(hints) {
+    const familiesByPath = new Map();
+    for (const hint of hints) {
+        for (const filePath of [...hint.implementationFiles, ...hint.testFiles]) {
+            const families = familiesByPath.get(filePath) ?? new Set();
+            families.add(hint.commandFamily);
+            familiesByPath.set(filePath, families);
+        }
+    }
+    return new Map([...familiesByPath.entries()].map(([filePath, families]) => [filePath, [...families].sort()]));
+}
+function createCommandHintEdges(fileReferences, hints) {
+    const summaryByPath = new Map(fileReferences.map((reference) => [reference.filePath, reference]));
+    const edges = [];
+    const seen = new Set();
+    for (const hint of hints) {
+        const commandNodeId = (0, extractor_contract_1.createCommandNodeId)(hint.commandId);
+        const registrySummary = summaryByPath.get(COMMAND_REGISTRY_SOURCE_PATH);
+        const source = (0, extractor_contract_1.createContextGraphSourceRef)({
+            path: COMMAND_REGISTRY_SOURCE_PATH,
+            ...(hint.sourceLine === undefined ? {} : { line: hint.sourceLine }),
+            ...(registrySummary ? { hash: registrySummary.hash } : {}),
+            extractor: 'extractCommandHints'
+        });
+        for (const filePath of hint.implementationFiles) {
+            const from = createCodeFileNodeId(filePath);
+            const reason = hint.implementationConfidence === 'explicit'
+                ? `Command registry explicitly maps command ${hint.commandId} to implementation file ${filePath}.`
+                : `Command ${hint.commandId} maps heuristically to CLI handler file ${filePath}.`;
+            const edge = {
+                id: createCodeEdgeId({ type: 'IMPLEMENTS_COMMAND', from, to: commandNodeId, source, reason }),
+                from,
+                to: commandNodeId,
+                type: 'IMPLEMENTS_COMMAND',
+                confidence: hint.implementationConfidence,
+                reason,
+                source
+            };
+            if (!seen.has(edge.id)) {
+                seen.add(edge.id);
+                edges.push(edge);
+            }
+        }
+        for (const filePath of hint.testFiles) {
+            const from = createCodeFileNodeId(filePath);
+            const reason = `Command registry explicitly maps command ${hint.commandId} to test file ${filePath}.`;
+            const edge = {
+                id: createCodeEdgeId({ type: 'TESTS_FILE', from, to: commandNodeId, source, reason }),
+                from,
+                to: commandNodeId,
+                type: 'TESTS_FILE',
+                confidence: 'explicit',
+                reason,
+                source
+            };
+            if (!seen.has(edge.id)) {
+                seen.add(edge.id);
+                edges.push(edge);
+            }
+        }
+    }
+    return edges.sort((a, b) => a.id.localeCompare(b.id));
+}
+function createTestRelationEdges(projectRoot, fileReferences) {
+    const edges = [];
+    const seen = new Set();
+    const sourceFiles = fileReferences.filter((reference) => classifyCodeFile(reference.filePath) === 'source');
+    const testFiles = fileReferences.filter((reference) => classifyCodeFile(reference.filePath) === 'test');
+    const sourceFilesByStem = createSourceFilesByStem(sourceFiles);
+    const testPaths = new Set(testFiles.map((reference) => reference.filePath));
+    for (const testFile of testFiles) {
+        const testNodeId = createCodeFileNodeId(testFile.filePath);
+        for (const importReference of testFile.imports) {
+            if (!importReference.resolvedPath || classifyCodeFile(importReference.resolvedPath) !== 'source')
+                continue;
+            const source = (0, extractor_contract_1.createContextGraphSourceRef)({
+                path: testFile.filePath,
+                line: importReference.line,
+                hash: testFile.hash,
+                extractor: 'extractTestRelations'
+            });
+            pushUniqueCodeEdge(edges, seen, {
+                type: 'TESTS_FILE',
+                from: testNodeId,
+                to: createCodeFileNodeId(importReference.resolvedPath),
+                confidence: 'explicit',
+                reason: `Test file ${testFile.filePath} imports source file ${importReference.resolvedPath}.`,
+                source
+            });
+        }
+        for (const sourceFile of sourceFilesByStem.get(testFileStem(testFile.filePath)) ?? []) {
+            const source = (0, extractor_contract_1.createContextGraphSourceRef)({
+                path: testFile.filePath,
+                line: 1,
+                hash: testFile.hash,
+                extractor: 'extractTestRelations'
+            });
+            pushUniqueCodeEdge(edges, seen, {
+                type: 'TESTS_FILE',
+                from: testNodeId,
+                to: createCodeFileNodeId(sourceFile.filePath),
+                confidence: 'derived',
+                reason: `Test file ${testFile.filePath} matches source file ${sourceFile.filePath} by filename stem.`,
+                source
+            });
+        }
+        for (const mention of testFile.commandMentions) {
+            const source = (0, extractor_contract_1.createContextGraphSourceRef)({
+                path: testFile.filePath,
+                line: mention.line,
+                hash: testFile.hash,
+                extractor: 'extractTestRelations'
+            });
+            pushUniqueCodeEdge(edges, seen, {
+                type: 'TESTS_FILE',
+                from: testNodeId,
+                to: (0, extractor_contract_1.createCommandNodeId)(mention.commandId),
+                confidence: 'heuristic',
+                reason: `Test file ${testFile.filePath} mentions command id ${mention.commandId}.`,
+                source
+            });
+        }
+    }
+    for (const evidenceReference of readEvidenceTestReferences(projectRoot, testPaths)) {
+        const source = (0, extractor_contract_1.createContextGraphSourceRef)({
+            path: evidenceReference.evidencePath,
+            line: evidenceReference.line,
+            content: evidenceReference.content,
+            extractor: 'extractEvidenceTestReferences'
+        });
+        pushUniqueCodeEdge(edges, seen, {
+            type: 'VALIDATED_BY_EVIDENCE',
+            from: createCodeFileNodeId(evidenceReference.testPath),
+            to: evidenceReference.evidenceId,
+            confidence: 'explicit',
+            reason: `Evidence record ${evidenceReference.evidenceId} references indexed test file ${evidenceReference.testPath}.`,
+            source
+        });
+    }
+    return edges.sort((a, b) => a.id.localeCompare(b.id));
+}
+function pushUniqueCodeEdge(edges, seen, input) {
+    const edge = {
+        id: createCodeEdgeId(input),
+        from: input.from,
+        to: input.to,
+        type: input.type,
+        confidence: input.confidence,
+        reason: input.reason,
+        source: input.source
+    };
+    if (seen.has(edge.id))
+        return;
+    seen.add(edge.id);
+    edges.push(edge);
+}
+function createSourceFilesByStem(sourceFiles) {
+    const filesByStem = new Map();
+    for (const sourceFile of sourceFiles) {
+        const stem = sourceFileStem(sourceFile.filePath);
+        const files = filesByStem.get(stem) ?? [];
+        files.push(sourceFile);
+        filesByStem.set(stem, files.sort((a, b) => a.filePath.localeCompare(b.filePath)));
+    }
+    return filesByStem;
+}
+function sourceFileStem(filePath) {
+    return node_path_1.default.posix.basename((0, extractor_contract_1.normalizeContextGraphPath)(filePath)).replace(/\.(?:ts|js|json)$/, '');
+}
+function testFileStem(filePath) {
+    return node_path_1.default.posix.basename((0, extractor_contract_1.normalizeContextGraphPath)(filePath)).replace(/\.(?:test|spec)\.(?:ts|js)$/, '');
+}
+function findCommandMentionLine(content, commandId) {
+    const pattern = new RegExp(`(^|[^A-Za-z0-9_.-])${escapeRegex(commandId)}([^A-Za-z0-9_.-]|$)`);
+    const lines = content.split(/\r?\n/);
+    const index = lines.findIndex((line) => pattern.test(line));
+    return index >= 0 ? index + 1 : undefined;
+}
+function readEvidenceTestReferences(projectRoot, testPaths) {
+    const tasksDir = node_path_1.default.join(projectRoot, 'tasks');
+    if (!node_fs_1.default.existsSync(tasksDir))
+        return [];
+    const references = [];
+    const taskDirs = node_fs_1.default.readdirSync(tasksDir, { withFileTypes: true })
+        .filter((entry) => entry.isDirectory())
+        .map((entry) => entry.name)
+        .sort();
+    for (const taskDir of taskDirs) {
+        const evidencePath = (0, extractor_contract_1.normalizeContextGraphPath)(node_path_1.default.posix.join('tasks', taskDir, 'evidence.jsonl'));
+        const absolutePath = node_path_1.default.join(projectRoot, evidencePath);
+        if (!node_fs_1.default.existsSync(absolutePath))
+            continue;
+        let content;
+        try {
+            content = node_fs_1.default.readFileSync(absolutePath, 'utf8');
+        }
+        catch {
+            continue;
+        }
+        content.split(/\r?\n/).forEach((line, index) => {
+            if (!line.trim())
+                return;
+            const evidenceId = readEvidenceIdFromLine(line) ?? `evidence:${evidencePath}#L${index + 1}`;
+            for (const testPath of testPaths) {
+                if (!line.includes(testPath))
+                    continue;
+                references.push({
+                    evidencePath,
+                    line: index + 1,
+                    content,
+                    evidenceId,
+                    testPath
+                });
+            }
+        });
+    }
+    return references.sort((a, b) => `${a.evidencePath}:${a.line}:${a.testPath}`.localeCompare(`${b.evidencePath}:${b.line}:${b.testPath}`));
+}
+function readEvidenceIdFromLine(line) {
+    try {
+        const parsed = JSON.parse(line);
+        return typeof parsed.id === 'string' && parsed.id.length > 0 ? parsed.id : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function normalizeExistingHintPaths(paths, availablePaths) {
+    return uniqueSorted(paths.map(extractor_contract_1.normalizeContextGraphPath).filter((filePath) => availablePaths.has(filePath)));
+}
+function createRegistryLineMap(content) {
+    const lineByCommand = new Map();
+    const lines = content.split(/\r?\n/);
+    lines.forEach((line, index) => {
+        const match = line.match(/\bid:\s*['"]([^'"]+)['"]/);
+        if (match?.[1] && !lineByCommand.has(match[1]))
+            lineByCommand.set(match[1], index + 1);
+    });
+    return lineByCommand;
+}
+function inferCommandImplementationFiles(entry) {
+    const exact = {
+        'ci.gate': ['src/cli/ci.ts'],
+        'context.graph': ['src/cli/context.ts'],
+        'dev.docker-check': ['src/cli/dev.ts'],
+        'docs.managed.list': ['src/cli/docs.ts'],
+        'docs.managed.explain': ['src/cli/docs.ts'],
+        'docs.required-reading': ['src/cli/docs.ts'],
+        'evidence.add-command': ['src/cli/evidence.ts'],
+        'evidence.collect': ['src/cli/evidence.ts'],
+        'install.plan': ['src/cli/install.ts'],
+        'mcp.serve': ['src/cli/mcp.ts'],
+        'ops.status': ['src/cli/status.ts'],
+        'package.smoke': ['src/cli/package-smoke.ts'],
+        'policy.check-shell': ['src/cli/policy.ts'],
+        'policy.preflight-shell': ['src/cli/policy.ts'],
+        'release.artifact': ['src/cli/release-artifact.ts'],
+        'release.dry-run': ['src/cli/release-dry-run.ts'],
+        'release.gate': ['src/cli/release-gate.ts'],
+        'release.publish': ['src/cli/release-publish.ts'],
+        'run.scaffold': ['src/cli/run-scaffold.ts'],
+        'run-state.resume': ['src/cli/run-state.ts'],
+        'run-state.show': ['src/cli/run-state.ts'],
+        'smoke.clean-checkout': ['src/cli/smoke.ts'],
+        'smoke.run': ['src/cli/smoke.ts'],
+        'task.audit-close': ['src/cli/task.ts'],
+        'task.upgrade-scaffold': ['src/cli/task.ts'],
+        'write.preflight': ['src/cli/write-preflight.ts']
+    };
+    if (exact[entry.id])
+        return exact[entry.id];
+    const familyPrefix = entry.id.split('.')[0] ?? entry.id;
+    const familyPath = `src/cli/${familyPrefix}.ts`;
+    return [familyPath];
+}
+function createCodeEdgeId(input) {
+    const fingerprint = (0, extractor_contract_1.hashContextGraphText)(JSON.stringify({
+        type: input.type,
+        from: input.from,
+        to: input.to,
+        source: {
+            path: input.source.path,
+            line: input.source.line ?? null,
+            extractor: input.source.extractor
+        },
+        reason: input.reason
+    })).replace(/^sha256:/, '');
+    return `code-edge:${input.type}:${fingerprint}`;
+}
+function escapeRegex(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+function isRelativeImportSpecifier(specifier) {
+    return specifier.startsWith('./') || specifier.startsWith('../');
+}
+function dedupeImports(imports) {
+    const seen = new Set();
+    const deduped = [];
+    for (const importReference of imports) {
+        const key = `${importReference.specifier}\0${importReference.resolvedPath ?? ''}\0${importReference.line}`;
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        deduped.push(importReference);
+    }
+    return deduped;
+}
+function dedupeExports(exports) {
+    const seen = new Set();
+    const deduped = [];
+    for (const exportReference of exports) {
+        if (seen.has(exportReference.name))
+            continue;
+        seen.add(exportReference.name);
+        deduped.push(exportReference);
+    }
+    return deduped;
+}
+function uniqueSorted(values) {
+    return Array.from(new Set(values)).sort();
+}