@mortice/mapwright 0.8.0

package/dist/catalogue/indexer.js

@@ -0,0 +1,1393 @@
+import { readFileSync } from "node:fs";
+import path from "node:path";
+import { loadConfig } from "./config.js";
+import { scanWorkspace } from "./scanner.js";
+import { buildDiagnostics } from "./diagnostics.js";
+import { computeCatalogueId, writeSnapshot } from "./store.js";
+import { extractTypeScriptSymbols } from "../extractors/typescript.js";
+import { extractJavaScriptSymbols } from "../extractors/javascript.js";
+import { extractPythonSymbols } from "../extractors/python.js";
+import { extractCatalogueMarkdown } from "../extractors/markdown.js";
+import { firstTag, manyTags, parseDocTags } from "../extractors/docTags.js";
+import { buildPackageModel, buildPublicImportPathBySymbolId, computePublicApiImportPath, findPackageForFile } from "./packages.js";
+import { MAPWRIGHT_GENERATOR_NAME, MAPWRIGHT_GENERATOR_VERSION } from "./version.js";
+import { buildDeterministicExampleId, normalizeExamplePath } from "./examples.js";
+import { buildPublicApiRefIndex, buildSymbolRefIndex, resolvePublicApiReference, resolveSymbolReference } from "./resolveRefs.js";
+import { IDENTITY_SCHEME, IdentityCollisionTracker, encodeIdentityPreimage, normalizeIdentityPath, normalizeIdentityString, publicApiIdentityId, relationshipIdentityId, testIdentityId } from "./identity.js";
+import { canonicaliseSymbols } from "./canonicalisation.js";
+import { buildLinkageRelationships } from "./linkage.js";
+import { buildPythonInitReExports } from "./pythonReExports.js";
+import { sortCapabilities, sortDiagnostics, sortExamples, sortFiles, sortPackages, sortPublicApis, sortRelationships, sortSymbols, sortTests } from "./ordering.js";
+export function indexWorkspace(input) {
+    const workspaceRoot = path.resolve(input.workspaceRoot);
+    const { config, mode, configPath } = loadConfig(input);
+    const { files, diagnostics: scannerDiagnostics } = scanWorkspace(workspaceRoot, config);
+    const symbols = [];
+    const relationships = [];
+    const capabilitiesById = new Map();
+    const publicApis = [];
+    const examples = [];
+    const tests = [];
+    const documentationDiagnostics = [];
+    const fileByPath = new Map();
+    // Pass 1: collect authored packages/capabilities/examples from CATALOGUE.md only,
+    // so package identity is established before symbols reference it.
+    const markdownPackages = [];
+    for (const file of files) {
+        fileByPath.set(file.path, file);
+        if (/CATALOGUE\.md$/i.test(file.path)) {
+            const md = extractCatalogueMarkdown(workspaceRoot, file.path);
+            for (const pkg of md.packages) {
+                if (!markdownPackages.find((p) => p.id === pkg.id)) {
+                    markdownPackages.push(pkg);
+                }
+            }
+            for (const capability of md.capabilities) {
+                upsertCapability(capabilitiesById, capability);
+            }
+            examples.push(...md.examples);
+        }
+    }
+    const packageModel = buildPackageModel(workspaceRoot, files, markdownPackages);
+    const packages = packageModel.packages;
+    // Pass 2: extract symbols/tests/examples with owning-package context.
+    for (const file of files) {
+        const packageRecord = findPackageForFile(packageModel, file.path);
+        if (file.language === "typescript") {
+            const result = extractTypeScriptSymbols(workspaceRoot, file, packageRecord);
+            symbols.push(...result.symbols);
+            relationships.push(...result.relationships);
+            documentationDiagnostics.push(...result.diagnostics);
+        }
+        else if (file.language === "javascript") {
+            const result = extractJavaScriptSymbols(workspaceRoot, file, packageRecord);
+            symbols.push(...result.symbols);
+            relationships.push(...result.relationships);
+            documentationDiagnostics.push(...result.diagnostics);
+        }
+        else if (file.language === "python") {
+            const result = extractPythonSymbols(workspaceRoot, file, packageRecord);
+            symbols.push(...result.symbols);
+            relationships.push(...result.relationships);
+            documentationDiagnostics.push(...result.diagnostics);
+        }
+        if (file.isTest) {
+            const extracted = extractTestRecords(workspaceRoot, file);
+            tests.push(...extracted.tests);
+            documentationDiagnostics.push(...extracted.diagnostics);
+        }
+        if (!file.isTest && (file.language === "typescript" || file.language === "javascript" || file.language === "python")) {
+            const extractedExamples = extractExampleRecords(workspaceRoot, file);
+            examples.push(...extractedExamples.examples);
+            documentationDiagnostics.push(...extractedExamples.diagnostics);
+        }
+    }
+    // Collapse generated declaration duplicates onto authored sources, then remap
+    // relationship endpoints to canonical symbol ids (keeping extracted ids as evidence).
+    const canonicalBySymbolId = canonicaliseSymbols(symbols, documentationDiagnostics);
+    remapRelationshipEndpoints(relationships, canonicalBySymbolId);
+    // Explicit Python __init__.py re-exports attribute the package-root import
+    // path to re-exported symbols, so they must exist before import-path resolution.
+    relationships.push(...buildPythonInitReExports({ workspaceRoot, files, symbols }));
+    const publicImportPathBySymbolId = buildPublicImportPathBySymbolId(packageModel, relationships);
+    const defaultExportSymbolIds = new Set(relationships
+        .filter((rel) => rel.type === "exports" && rel.to.kind === "symbol" && rel.localDiscriminant === "default")
+        .map((rel) => rel.to.id));
+    const publicApiBySymbolId = new Map();
+    for (const symbol of symbols) {
+        if (symbol.duplicateOf) {
+            continue;
+        }
+        for (const cap of symbol.capabilities) {
+            const capId = cap.startsWith("capability:") ? cap : `capability:${cap}`;
+            const record = ensureCapability(capabilitiesById, capId);
+            if (!record.symbols.includes(symbol.id))
+                record.symbols.push(symbol.id);
+            if (!record.files.includes(symbol.filePath))
+                record.files.push(symbol.filePath);
+        }
+        const docTags = symbol.doc?.tags ?? [];
+        const isPublicApiTag = Boolean(docTags.find((tag) => tag.tag === "publicApi")) || firstTag(docTags, "catalogue") === "public-api";
+        const symbolFile = fileByPath.get(symbol.filePath);
+        if ((symbol.exported || isPublicApiTag) && !symbolFile?.isTest && !symbolFile?.isExample) {
+            const packageRecord = findPackageForFile(packageModel, symbol.filePath);
+            const importPath = computePublicApiImportPath(workspaceRoot, symbol.filePath, packageRecord, symbol.language, publicImportPathBySymbolId.get(symbol.id));
+            const exportKind = defaultExportSymbolIds.has(symbol.id) ? "default" : "named";
+            const packageId = packageRecord?.id ?? "package:unknown";
+            // Public export identity is consumer-facing: package + import path + name + kind.
+            // The declaration is retained as a link (symbolId), not part of the identity.
+            const apiId = publicApiIdentityId({
+                packageId,
+                importPath: importPath ?? "",
+                exportedName: symbol.name,
+                exportKind
+            });
+            symbol.publicApi = apiId;
+            const capabilityIds = symbol.capabilities.map((c) => (c.startsWith("capability:") ? c : `capability:${c}`));
+            const api = {
+                id: apiId,
+                symbolId: symbol.id,
+                name: symbol.name,
+                importPath,
+                exportKind,
+                packageId,
+                signature: symbol.signature,
+                capabilityIds,
+                stability: firstTag(docTags, "stability") ?? "unknown",
+                intendedUse: firstTag(docTags, "intendedUse"),
+                inputs: firstTag(docTags, "inputs"),
+                returns: firstTag(docTags, "returns"),
+                contracts: manyTags(docTags, "contract"),
+                errors: manyTags(docTags, "errors"),
+                examples: [],
+                tests: manyTags(docTags, "tests"),
+                provenance: { source: symbol.language === "python" ? "python-docstring" : "jsdoc" }
+            };
+            const apiExamples = buildExamplesFromReferences(manyTags(docTags, "example"), {
+                sourceFilePath: symbol.filePath,
+                capabilityIds,
+                publicApiId: apiId,
+                symbolId: symbol.id,
+                provenanceSource: symbol.language === "python" ? "python-docstring" : "jsdoc"
+            });
+            api.examples = apiExamples.map((example) => example.id);
+            examples.push(...apiExamples);
+            publicApis.push(api);
+            publicApiBySymbolId.set(symbol.id, apiId);
+            const file = fileByPath.get(symbol.filePath);
+            if (file && !file.publicApis.includes(apiId)) {
+                file.publicApis.push(apiId);
+            }
+            for (const capId of capabilityIds) {
+                const capability = ensureCapability(capabilitiesById, capId);
+                if (!capability.publicApis.includes(api.id))
+                    capability.publicApis.push(api.id);
+            }
+        }
+    }
+    const capabilities = [...capabilitiesById.values()]
+        .map((cap) => ({
+        ...cap,
+        files: [...new Set(cap.files)].sort(),
+        symbols: [...new Set(cap.symbols)].sort(),
+        publicApis: [...new Set(cap.publicApis)].sort()
+    }))
+        .sort((a, b) => a.id.localeCompare(b.id));
+    const symbolResolutionDiagnostics = resolveTestSymbolReferences(tests, symbols, packageModel);
+    documentationDiagnostics.push(...symbolResolutionDiagnostics);
+    const publicApiResolutionDiagnostics = resolveTestPublicApiReferences(tests, publicApis, symbols, packageModel);
+    documentationDiagnostics.push(...publicApiResolutionDiagnostics);
+    const capabilityPublicApiDiagnostics = resolveCapabilityPublicApiReferences(capabilities, publicApis, symbols, packageModel);
+    documentationDiagnostics.push(...capabilityPublicApiDiagnostics);
+    const testRelationships = buildTestRelationships(tests, symbols, publicApiBySymbolId, new Set(publicApis.map((api) => api.id)));
+    relationships.push(...testRelationships);
+    // Gate 3: conservative, provenanced consumer→API linkage (resolved direct
+    // import/usage only). Never relabels inferred references as coverage.
+    const linkageRelationships = buildLinkageRelationships({
+        workspaceRoot,
+        files,
+        symbols,
+        publicApis,
+        relationships,
+        packageModel
+    });
+    relationships.push(...linkageRelationships);
+    dedupeRelationshipsById(relationships);
+    for (const file of files) {
+        const packageRecord = findPackageForFile(packageModel, file.path);
+        if (!packageRecord) {
+            continue;
+        }
+        if (file.publicApis.length > 0) {
+            packageRecord.publicPaths = [...new Set([...(packageRecord.publicPaths ?? []), file.path])].sort();
+        }
+        else if (file.kind === "source") {
+            packageRecord.internalPaths = [...new Set([...(packageRecord.internalPaths ?? []), file.path])].sort();
+        }
+    }
+    const symbolById = new Map(symbols.map((symbol) => [symbol.id, symbol]));
+    for (const capability of capabilities) {
+        const linkedPackages = new Set(capability.packages);
+        for (const filePath of capability.files) {
+            const packageRecord = packageModel.filePackageByPath.get(filePath);
+            if (packageRecord) {
+                linkedPackages.add(packageRecord.id);
+                packageRecord.capabilities = [...new Set([...(packageRecord.capabilities ?? []), capability.id])].sort();
+            }
+        }
+        capability.packages = [...linkedPackages].sort();
+    }
+    for (const api of publicApis) {
+        const symbol = symbolById.get(api.symbolId);
+        const packageRecord = symbol ? packageModel.filePackageByPath.get(symbol.filePath) : undefined;
+        if (packageRecord) {
+            packageRecord.publicApis = [...new Set([...(packageRecord.publicApis ?? []), api.id])].sort();
+        }
+    }
+    for (const test of tests) {
+        const packageRecord = packageModel.filePackageByPath.get(test.filePath);
+        if (packageRecord) {
+            packageRecord.tests = [...new Set([...(packageRecord.tests ?? []), test.id])].sort();
+        }
+    }
+    const { examples: normalizedExamples, diagnostics: exampleResolutionDiagnostics } = normalizeExamples(examples, capabilities, publicApis, symbols, packageModel);
+    documentationDiagnostics.push(...exampleResolutionDiagnostics);
+    const boundaryDiagnostics = [];
+    for (const relationship of relationships) {
+        if (relationship.type !== "imports" || relationship.from.kind !== "file" || relationship.to.kind !== "file") {
+            continue;
+        }
+        const sourcePackage = packageModel.filePackageByPath.get(relationship.from.id);
+        const targetPackage = packageModel.filePackageByPath.get(relationship.to.id);
+        if (!sourcePackage || !targetPackage) {
+            boundaryDiagnostics.push({
+                id: `diag:${relationship.id}:package_boundary_unknown`,
+                severity: "info",
+                category: "resolution",
+                code: "package_boundary_unknown",
+                message: `Package boundary could not be determined for import ${relationship.from.id} -> ${relationship.to.id}.`,
+                filePath: relationship.from.id,
+                target: { kind: "file", id: relationship.from.id },
+                provenance: { source: "validation" }
+            });
+            continue;
+        }
+        if (sourcePackage.id !== targetPackage.id) {
+            boundaryDiagnostics.push({
+                id: `diag:${relationship.id}:cross_boundary_import`,
+                severity: "warning",
+                category: "resolution",
+                code: "cross_boundary_import",
+                message: `Import crosses package boundary from ${sourcePackage.id} to ${targetPackage.id}.`,
+                filePath: relationship.from.id,
+                target: { kind: "package", id: sourcePackage.id },
+                provenance: { source: "validation" }
+            });
+        }
+    }
+    for (const packageRecord of packages) {
+        if ((packageRecord.entrypoints?.length ?? 0) > 0 || (packageRecord.modules?.length ?? 0) === 0) {
+            continue;
+        }
+        if (packageRecord.provenance.warnings?.some((warning) => warning.startsWith("private-workspace-root"))) {
+            continue;
+        }
+        boundaryDiagnostics.push({
+            id: `diag:${packageRecord.id}:package_missing_entrypoint`,
+            severity: "info",
+            category: "documentation",
+            code: "package_missing_entrypoint",
+            message: `Package ${packageRecord.id} has no detected entrypoints.`,
+            target: { kind: "package", id: packageRecord.id },
+            provenance: { source: "validation" }
+        });
+    }
+    const diagnostics = sortDiagnostics([
+        ...scannerDiagnostics,
+        ...documentationDiagnostics,
+        ...buildDiagnostics(symbols, config),
+        ...duplicateIdDiagnostics(symbols, capabilities, publicApis, tests),
+        ...packageDocDiagnostics(files, packages),
+        ...capabilityResolutionDiagnostics(capabilities, symbols),
+        ...publicApiCapabilityDiagnostics(publicApis, capabilities),
+        ...reuseDocumentationDiagnostics(capabilities, publicApis, normalizedExamples, tests, symbols),
+        ...testResolutionDiagnostics(tests, capabilities, symbols, publicApis),
+        ...boundaryDiagnostics
+    ]);
+    // Fail closed on any full-id hash collision before emitting a snapshot.
+    assertNoIdentityCollisions(packages, symbols, publicApis, tests, relationships, capabilities, normalizedExamples, diagnostics);
+    const sortedFiles = sortFiles(files);
+    const sortedSymbols = sortSymbols(symbols);
+    const sortedPublicApis = sortPublicApis(publicApis);
+    const sortedExamples = sortExamples(normalizedExamples);
+    const sortedPackages = sortPackages(packages);
+    const sortedRelationships = sortRelationships(relationships);
+    const sortedTests = sortTests(tests);
+    const sortedCapabilities = sortCapabilities(capabilities);
+    const snapshotNoId = {
+        schemaVersion: 2,
+        identityScheme: IDENTITY_SCHEME,
+        generator: {
+            name: MAPWRIGHT_GENERATOR_NAME,
+            version: MAPWRIGHT_GENERATOR_VERSION
+        },
+        mode,
+        stats: {
+            fileCount: sortedFiles.length,
+            symbolCount: sortedSymbols.length,
+            capabilityCount: sortedCapabilities.length,
+            publicApiCount: sortedPublicApis.length,
+            exampleCount: sortedExamples.length,
+            diagnosticCount: diagnostics.length,
+            languages: languageStats(sortedFiles)
+        },
+        files: sortedFiles,
+        packages: sortedPackages,
+        capabilities: sortedCapabilities,
+        publicApis: sortedPublicApis,
+        examples: sortedExamples,
+        symbols: sortedSymbols,
+        relationships: sortedRelationships,
+        tests: sortedTests,
+        diagnostics,
+        provenance: {
+            source: "indexer",
+            extractors: ["scanner", "typescript", "python", "markdown"],
+            documentationSources: [],
+            warnings: []
+        }
+    };
+    const snapshot = {
+        ...snapshotNoId,
+        catalogueId: computeCatalogueId(snapshotNoId)
+    };
+    if (input.write ?? mode !== "memory") {
+        writeSnapshot(workspaceRoot, config.catalogueDir, snapshot, input.pretty ?? true);
+    }
+    return { snapshot, configPath };
+}
+function ensureCapability(map, id) {
+    const existing = map.get(id);
+    if (existing) {
+        return existing;
+    }
+    const name = id.replace(/^capability:/, "");
+    const created = {
+        id,
+        name,
+        summary: undefined,
+        description: undefined,
+        keywords: name.split(/[.\-]/).filter(Boolean),
+        status: "available",
+        stability: "unknown",
+        publicApis: [],
+        symbols: [],
+        files: [],
+        packages: [],
+        examples: [],
+        tests: [],
+        contracts: [],
+        limitations: [],
+        provenance: { source: "docs+symbols" }
+    };
+    map.set(id, created);
+    return created;
+}
+function upsertCapability(map, record) {
+    const existing = map.get(record.id);
+    if (!existing) {
+        map.set(record.id, record);
+        return;
+    }
+    existing.summary = existing.summary ?? record.summary;
+    existing.description = existing.description ?? record.description;
+    existing.intendedUse = existing.intendedUse ?? record.intendedUse;
+    existing.stability = existing.stability === "unknown" ? record.stability : existing.stability;
+    existing.keywords = [...new Set([...existing.keywords, ...record.keywords])];
+    existing.publicApis = [...new Set([...existing.publicApis, ...record.publicApis])];
+    existing.symbols = [...new Set([...existing.symbols, ...record.symbols])];
+    existing.files = [...new Set([...existing.files, ...record.files])];
+    existing.packages = [...new Set([...(existing.packages ?? []), ...(record.packages ?? [])])];
+    existing.examples = [...new Set([...(existing.examples ?? []), ...(record.examples ?? [])])];
+    existing.tests = [...new Set([...(existing.tests ?? []), ...(record.tests ?? [])])];
+    existing.contracts = [...new Set([...(existing.contracts ?? []), ...(record.contracts ?? [])])];
+    existing.limitations = [...new Set([...(existing.limitations ?? []), ...(record.limitations ?? [])])];
+}
+function resolveCapabilityPublicApiReferences(capabilities, publicApis, symbols, packageModel) {
+    const index = buildPublicApiRefIndex(publicApis, symbols, packageModel.filePackageByPath);
+    const diagnostics = [];
+    for (const capability of capabilities) {
+        const resolved = new Set();
+        for (const ref of capability.publicApis) {
+            const result = resolvePublicApiReference(ref, index);
+            if (result.status === "resolved") {
+                resolved.add(result.value);
+                continue;
+            }
+            if (result.status === "ambiguous") {
+                diagnostics.push({
+                    id: `diag:${capability.id}:ambiguous_public_api_reference:${ref}`,
+                    severity: "warning",
+                    category: "resolution",
+                    code: "ambiguous_public_api_reference",
+                    message: `Capability ${capability.id} has ambiguous public API reference ${ref}.`,
+                    target: { kind: "capability", id: capability.id },
+                    provenance: { source: "validation" }
+                });
+                continue;
+            }
+            diagnostics.push({
+                id: `diag:${capability.id}:capability_references_unknown_public_api:${ref}`,
+                severity: "warning",
+                category: "resolution",
+                code: "capability_references_unknown_public_api",
+                message: `Capability ${capability.id} references unknown public API ${ref}.`,
+                target: { kind: "capability", id: capability.id },
+                provenance: { source: "validation" }
+            });
+        }
+        capability.publicApis = [...resolved].sort();
+    }
+    return diagnostics;
+}
+function exampleSourceRank(source) {
+    switch (source) {
+        case "example-docs":
+            return 1;
+        case "jsdoc":
+        case "python-docstring":
+            return 2;
+        case "catalogue-md":
+            return 3;
+        default:
+            return 99;
+    }
+}
+function normalizeExamples(examples, capabilities, publicApis, symbols, packageModel) {
+    const symbolIds = new Set(symbols.map((symbol) => symbol.id));
+    const index = buildPublicApiRefIndex(publicApis, symbols, packageModel.filePackageByPath);
+    const diagnostics = [];
+    // Prefer file-level annotations over symbol @example over CATALOGUE.md when merging
+    // the same identity (normalized filePath + optional anchor).
+    const ordered = [...examples].sort((left, right) => {
+        const rankDelta = exampleSourceRank(left.provenance.source) - exampleSourceRank(right.provenance.source);
+        if (rankDelta !== 0) {
+            return rankDelta;
+        }
+        return left.id.localeCompare(right.id);
+    });
+    const merged = new Map();
+    for (const example of ordered) {
+        const existing = merged.get(example.id);
+        if (!existing) {
+            const resolvedIds = resolveExamplePublicApiIds(example.id, example.publicApiIds, index, example.filePath, diagnostics);
+            merged.set(example.id, {
+                ...example,
+                filePath: normalizeExamplePath(example.filePath),
+                capabilityIds: [...new Set(example.capabilityIds.map(normalizeCap))].sort(),
+                publicApiIds: resolvedIds,
+                symbolIds: [...new Set(example.symbolIds)].filter((id) => symbolIds.has(id)).sort()
+            });
+            continue;
+        }
+        const preferIncoming = exampleSourceRank(example.provenance.source) < exampleSourceRank(existing.provenance.source);
+        existing.capabilityIds = [...new Set([...existing.capabilityIds, ...example.capabilityIds.map(normalizeCap)])]
+            .sort();
+        existing.publicApiIds = resolveExamplePublicApiIds(example.id, [...existing.publicApiIds, ...example.publicApiIds], index, example.filePath ?? existing.filePath, diagnostics);
+        existing.symbolIds = [...new Set([...existing.symbolIds, ...example.symbolIds])].filter((id) => symbolIds.has(id)).sort();
+        existing.filePath = existing.filePath ?? normalizeExamplePath(example.filePath);
+        if (preferIncoming) {
+            existing.anchor = example.anchor ?? existing.anchor;
+            existing.title = example.title ?? existing.title;
+            existing.summary = example.summary ?? existing.summary;
+            existing.provenance = {
+                ...example.provenance,
+                locations: [...new Set([...(example.provenance.locations ?? []), ...(existing.provenance.locations ?? [])])].sort(),
+                warnings: [...new Set([...(example.provenance.warnings ?? []), ...(existing.provenance.warnings ?? [])])].sort()
+            };
+        }
+        else {
+            existing.anchor = existing.anchor ?? example.anchor;
+            existing.title = existing.title ?? example.title;
+            existing.summary = existing.summary ?? example.summary;
+            existing.provenance = {
+                ...existing.provenance,
+                locations: [...new Set([...(existing.provenance.locations ?? []), ...(example.provenance.locations ?? [])])].sort(),
+                warnings: [...new Set([...(existing.provenance.warnings ?? []), ...(example.provenance.warnings ?? [])])].sort()
+            };
+        }
+    }
+    const normalizedExamples = [...merged.values()].sort((a, b) => a.id.localeCompare(b.id));
+    const exampleIdsByCapability = new Map();
+    for (const example of normalizedExamples) {
+        for (const capabilityId of example.capabilityIds) {
+            const current = exampleIdsByCapability.get(capabilityId) ?? [];
+            current.push(example.id);
+            exampleIdsByCapability.set(capabilityId, current.sort());
+        }
+    }
+    for (const capability of capabilities) {
+        const current = capability.examples ?? [];
+        const resolved = current.map((id) => id.trim()).filter(Boolean);
+        const mergedIds = [...new Set([...(exampleIdsByCapability.get(capability.id) ?? []), ...resolved])]
+            .filter((id) => normalizedExamples.some((example) => example.id === id))
+            .sort();
+        capability.examples = mergedIds;
+    }
+    for (const api of publicApis) {
+        const linked = normalizedExamples
+            .filter((example) => example.publicApiIds.includes(api.id))
+            .map((example) => example.id);
+        api.examples = [...new Set([...api.examples, ...linked])]
+            .filter((id) => normalizedExamples.some((example) => example.id === id))
+            .sort();
+    }
+    return { examples: normalizedExamples, diagnostics };
+}
+function resolveExamplePublicApiIds(exampleId, refs, index, filePath, diagnostics) {
+    const resolved = new Set();
+    for (const ref of refs) {
+        const result = resolvePublicApiReference(ref, index);
+        if (result.status === "resolved") {
+            resolved.add(result.value);
+            continue;
+        }
+        if (result.status === "ambiguous") {
+            diagnostics.push({
+                id: `diag:${exampleId}:example_references_ambiguous_public_api:${ref}`,
+                severity: "warning",
+                category: "resolution",
+                code: "example_references_ambiguous_public_api",
+                message: `Example ${exampleId} has ambiguous public API reference ${ref}.`,
+                filePath,
+                provenance: { source: "validation" }
+            });
+            continue;
+        }
+        resolved.add(ref);
+    }
+    return [...resolved].sort();
+}
+function buildExamplesFromReferences(references, options) {
+    return references
+        .map((reference) => reference.trim())
+        .filter(Boolean)
+        .map((reference) => {
+        const [filePathRaw, anchorRaw] = reference.split("#", 2);
+        const filePath = normalizeExamplePath(filePathRaw?.trim());
+        const anchor = anchorRaw?.trim();
+        return {
+            id: buildDeterministicExampleId(filePath, anchor, reference),
+            title: anchor ? anchor.replace(/[-_]/g, " ") : filePath ? path.basename(filePath) : undefined,
+            filePath,
+            anchor,
+            capabilityIds: [...new Set(options.capabilityIds.map(normalizeCap))].sort(),
+            publicApiIds: [options.publicApiId],
+            symbolIds: [options.symbolId],
+            summary: undefined,
+            provenance: { source: options.provenanceSource, locations: [options.sourceFilePath] }
+        };
+    })
+        .sort((a, b) => a.id.localeCompare(b.id));
+}
+function reuseDocumentationDiagnostics(capabilities, publicApis, examples, tests, symbols) {
+    const diagnostics = [];
+    const capabilityIds = new Set(capabilities.map((capability) => capability.id));
+    const publicApiIds = new Set(publicApis.map((api) => api.id));
+    const testsByCapability = new Map();
+    for (const test of tests) {
+        for (const capabilityId of test.coversCapabilities) {
+            const current = testsByCapability.get(capabilityId) ?? [];
+            current.push(test.id);
+            testsByCapability.set(capabilityId, current);
+        }
+    }
+    const examplesByCapability = new Map();
+    for (const example of examples) {
+        for (const capabilityId of example.capabilityIds) {
+            const current = examplesByCapability.get(capabilityId) ?? [];
+            current.push(example.id);
+            examplesByCapability.set(capabilityId, current);
+        }
+    }
+    const testsByPublicApi = new Map();
+    const publicApiBySymbolId = new Map(symbols
+        .filter((symbol) => Boolean(symbol.publicApi))
+        .map((symbol) => [symbol.id, symbol.publicApi]));
+    for (const test of tests) {
+        for (const symbolId of test.coversSymbols) {
+            const publicApiId = publicApiBySymbolId.get(symbolId);
+            if (!publicApiId) {
+                continue;
+            }
+            const current = testsByPublicApi.get(publicApiId) ?? [];
+            current.push(test.id);
+            testsByPublicApi.set(publicApiId, current);
+        }
+        for (const publicApiId of test.coversPublicApis) {
+            if (!publicApiIds.has(publicApiId)) {
+                continue;
+            }
+            const current = testsByPublicApi.get(publicApiId) ?? [];
+            current.push(test.id);
+            testsByPublicApi.set(publicApiId, current);
+        }
+    }
+    for (const capability of capabilities) {
+        const authoredCapability = capability.provenance.source === "catalogue-md";
+        if (!authoredCapability || capability.stability === "internal" || capability.stability === "test-only") {
+            continue;
+        }
+        if (!capability.summary?.trim()) {
+            diagnostics.push({
+                id: `diag:${capability.id}:capability_missing_summary`,
+                severity: "warning",
+                category: "documentation",
+                code: "capability_missing_summary",
+                message: `Capability ${capability.id} is missing a summary.`,
+                target: { kind: "capability", id: capability.id },
+                provenance: { source: "validation" }
+            });
+        }
+        if (capability.publicApis.length === 0) {
+            diagnostics.push({
+                id: `diag:${capability.id}:capability_missing_public_api`,
+                severity: "warning",
+                category: "documentation",
+                code: "capability_missing_public_api",
+                message: `Capability ${capability.id} has no linked public API.`,
+                target: { kind: "capability", id: capability.id },
+                provenance: { source: "validation" }
+            });
+        }
+        const hasTests = (capability.tests?.length ?? 0) > 0 || (testsByCapability.get(capability.id)?.length ?? 0) > 0;
+        if (!hasTests) {
+            diagnostics.push({
+                id: `diag:${capability.id}:capability_missing_tests`,
+                severity: "warning",
+                category: "documentation",
+                code: "capability_missing_tests",
+                message: `Capability ${capability.id} has no linked tests.`,
+                target: { kind: "capability", id: capability.id },
+                provenance: { source: "validation" }
+            });
+        }
+        const hasExamples = (capability.examples?.length ?? 0) > 0 || (examplesByCapability.get(capability.id)?.length ?? 0) > 0;
+        if (!hasExamples) {
+            diagnostics.push({
+                id: `diag:${capability.id}:capability_missing_examples`,
+                severity: "info",
+                category: "documentation",
+                code: "capability_missing_examples",
+                message: `Capability ${capability.id} has no linked examples.`,
+                target: { kind: "capability", id: capability.id },
+                provenance: { source: "validation" }
+            });
+        }
+    }
+    for (const api of publicApis) {
+        const symbol = symbols.find((item) => item.id === api.symbolId);
+        const internal = symbol?.visibility === "private"
+            || symbol?.visibility === "supported_internal"
+            || symbol?.visibility === "test_only"
+            || api.stability === "internal"
+            || api.stability === "test-only";
+        if (internal) {
+            continue;
+        }
+        // Avoid noisy diagnostics for APIs that are not connected to authored capabilities.
+        if (api.capabilityIds.length === 0) {
+            continue;
+        }
+        const hasExamples = api.examples.length > 0 || examples.some((example) => example.publicApiIds.includes(api.id));
+        if (!hasExamples) {
+            diagnostics.push({
+                id: `diag:${api.id}:public_api_missing_example`,
+                severity: "info",
+                category: "documentation",
+                code: "public_api_missing_example",
+                message: `Public API ${api.id} has no linked example.`,
+                target: { kind: "publicApi", id: api.id },
+                provenance: { source: "validation" }
+            });
+        }
+        const hasTests = api.tests.length > 0 || (testsByPublicApi.get(api.id)?.length ?? 0) > 0;
+        if (!hasTests) {
+            diagnostics.push({
+                id: `diag:${api.id}:public_api_missing_test_reference`,
+                severity: "warning",
+                category: "documentation",
+                code: "public_api_missing_test_reference",
+                message: `Public API ${api.id} has no linked test reference.`,
+                target: { kind: "publicApi", id: api.id },
+                provenance: { source: "validation" }
+            });
+        }
+    }
+    for (const example of examples) {
+        if (!example.filePath) {
+            diagnostics.push({
+                id: `diag:${example.id}:example_missing_file_path`,
+                severity: "warning",
+                category: "documentation",
+                code: "example_missing_file_path",
+                message: `Example ${example.id} is missing a file path reference.`,
+                provenance: { source: "validation" }
+            });
+        }
+        if ((example.provenance.warnings?.length ?? 0) > 0) {
+            diagnostics.push({
+                id: `diag:${example.id}:example_malformed_metadata`,
+                severity: "warning",
+                category: "documentation",
+                code: "example_malformed_metadata",
+                message: `Example ${example.id} contains malformed metadata tokens.`,
+                filePath: example.filePath,
+                provenance: { source: "validation" }
+            });
+        }
+        for (const capabilityId of example.capabilityIds) {
+            if (!capabilityIds.has(capabilityId)) {
+                diagnostics.push({
+                    id: `diag:${example.id}:example_references_unknown_capability:${capabilityId}`,
+                    severity: "warning",
+                    category: "resolution",
+                    code: "example_references_unknown_capability",
+                    message: `Example ${example.id} references unknown capability ${capabilityId}.`,
+                    filePath: example.filePath,
+                    provenance: { source: "validation" }
+                });
+            }
+        }
+        for (const publicApiId of example.publicApiIds) {
+            if (!publicApiIds.has(publicApiId)) {
+                diagnostics.push({
+                    id: `diag:${example.id}:example_references_unknown_public_api:${publicApiId}`,
+                    severity: "warning",
+                    category: "resolution",
+                    code: "example_references_unknown_public_api",
+                    message: `Example ${example.id} references unknown public API ${publicApiId}.`,
+                    filePath: example.filePath,
+                    provenance: { source: "validation" }
+                });
+            }
+        }
+    }
+    return diagnostics;
+}
+function languageStats(files) {
+    const out = {};
+    for (const file of files) {
+        out[file.language] = (out[file.language] ?? 0) + 1;
+    }
+    return out;
+}
+function capabilityResolutionDiagnostics(capabilities, symbols) {
+    const symbolIds = new Set(symbols.map((s) => s.id));
+    const diagnostics = [];
+    for (const capability of capabilities) {
+        for (const symbolId of capability.symbols) {
+            if (!symbolIds.has(symbolId)) {
+                diagnostics.push({
+                    id: `diag:${capability.id}:capability_references_unknown_symbol:${symbolId}`,
+                    severity: "error",
+                    category: "resolution",
+                    code: "capability_references_unknown_symbol",
+                    message: `Capability ${capability.id} references unknown symbol ${symbolId}.`,
+                    target: { kind: "capability", id: capability.id },
+                    provenance: { source: "validation" }
+                });
+            }
+        }
+    }
+    return diagnostics;
+}
+function publicApiCapabilityDiagnostics(publicApis, capabilities) {
+    const capabilityIds = new Set(capabilities.map((capability) => capability.id));
+    const diagnostics = [];
+    for (const api of publicApis) {
+        for (const capabilityId of api.capabilityIds) {
+            if (!capabilityIds.has(capabilityId)) {
+                diagnostics.push({
+                    id: `diag:${api.id}:public_api_references_unknown_capability:${capabilityId}`,
+                    severity: "error",
+                    category: "resolution",
+                    code: "public_api_references_unknown_capability",
+                    message: `Public API ${api.id} references unknown capability ${capabilityId}.`,
+                    target: { kind: "publicApi", id: api.id },
+                    provenance: { source: "validation" }
+                });
+            }
+        }
+    }
+    return diagnostics;
+}
+function testResolutionDiagnostics(tests, capabilities, symbols, publicApis) {
+    const capabilityIds = new Set(capabilities.map((c) => c.id));
+    const symbolIds = new Set(symbols.map((s) => s.id));
+    const publicApiIds = new Set(publicApis.map((api) => api.id));
+    const diagnostics = [];
+    for (const test of tests) {
+        for (const capId of test.coversCapabilities) {
+            if (!capabilityIds.has(capId)) {
+                diagnostics.push({
+                    id: `diag:${test.id}:test_references_unknown_capability:${capId}`,
+                    severity: "error",
+                    category: "resolution",
+                    code: "test_references_unknown_capability",
+                    message: `Test ${test.id} references unknown capability ${capId}.`,
+                    filePath: test.filePath,
+                    target: { kind: "test", id: test.id },
+                    provenance: { source: "validation" }
+                });
+            }
+        }
+        for (const symbolId of test.coversSymbols) {
+            if (!symbolIds.has(symbolId)) {
+                diagnostics.push({
+                    id: `diag:${test.id}:test_references_unknown_symbol:${symbolId}`,
+                    severity: "warning",
+                    category: "resolution",
+                    code: "test_references_unknown_symbol",
+                    message: `Test ${test.id} references unknown symbol ${symbolId}.`,
+                    filePath: test.filePath,
+                    target: { kind: "test", id: test.id },
+                    provenance: { source: "validation" }
+                });
+            }
+        }
+        for (const publicApiId of test.coversPublicApis) {
+            if (!publicApiIds.has(publicApiId)) {
+                diagnostics.push({
+                    id: `diag:${test.id}:test_references_unknown_public_api:${publicApiId}`,
+                    severity: "warning",
+                    category: "resolution",
+                    code: "test_references_unknown_public_api",
+                    message: `Test ${test.id} references unknown public API ${publicApiId}.`,
+                    filePath: test.filePath,
+                    target: { kind: "test", id: test.id },
+                    provenance: { source: "validation" }
+                });
+            }
+        }
+    }
+    return diagnostics;
+}
+function extractExampleRecords(workspaceRoot, file) {
+    const absolute = path.resolve(workspaceRoot, file.path);
+    const content = readFileSync(absolute, "utf8");
+    const examples = [];
+    const diagnostics = [];
+    for (const block of extractDocBlocks(content, file.language)) {
+        const parsed = parseExampleDocBlock(file.path, block.text);
+        if (!parsed) {
+            continue;
+        }
+        examples.push(parsed.example);
+        diagnostics.push(...parsed.diagnostics);
+    }
+    examples.sort((a, b) => a.id.localeCompare(b.id));
+    diagnostics.sort((a, b) => a.id.localeCompare(b.id));
+    return { examples, diagnostics };
+}
+function parseExampleDocBlock(filePath, blockText) {
+    const parsed = parseDocTags(blockText, filePath);
+    const tags = parsed.tags;
+    const isCatalogueExample = tags.some((tag) => tag.tag === "catalogue" && tag.value === "example");
+    if (!isCatalogueExample) {
+        return undefined;
+    }
+    const capabilityIds = tags.filter((tag) => tag.tag === "coversCapability").map((tag) => normalizeCap(tag.value));
+    const publicApiRefs = tags.filter((tag) => tag.tag === "coversPublicApi").map((tag) => tag.value);
+    const normalizedPath = normalizeExamplePath(filePath);
+    const title = normalizedPath ? path.basename(normalizedPath) : undefined;
+    return {
+        example: {
+            id: buildDeterministicExampleId(normalizedPath, undefined, filePath),
+            title,
+            filePath: normalizedPath,
+            anchor: undefined,
+            capabilityIds,
+            publicApiIds: publicApiRefs,
+            symbolIds: [],
+            summary: parsed.summary || undefined,
+            provenance: { source: "example-docs", locations: [filePath] }
+        },
+        diagnostics: parsed.diagnostics
+    };
+}
+function extractTestRecords(workspaceRoot, file) {
+    const absolute = path.resolve(workspaceRoot, file.path);
+    const content = readFileSync(absolute, "utf8");
+    const tests = [];
+    const diagnostics = [];
+    for (const block of extractDocBlocks(content, file.language)) {
+        const parsed = parseTestDocBlock(file.path, block.text, block.startLine);
+        if (!parsed) {
+            continue;
+        }
+        tests.push(parsed.test);
+        diagnostics.push(...parsed.diagnostics);
+    }
+    tests.sort((a, b) => a.id.localeCompare(b.id));
+    diagnostics.sort((a, b) => a.id.localeCompare(b.id));
+    return { tests, diagnostics };
+}
+function parseTestDocBlock(filePath, blockText, startLine) {
+    const parsed = parseDocTags(blockText, filePath);
+    const tags = parsed.tags;
+    const isCatalogueTest = tags.some((tag) => tag.tag === "catalogue" && tag.value === "test");
+    const hasCoverageTags = tags.some((tag) => tag.tag === "coversCapability" || tag.tag === "coversSymbol" || tag.tag === "coversPublicApi");
+    if (!isCatalogueTest && !hasCoverageTags) {
+        return undefined;
+    }
+    const capabilityIds = tags.filter((tag) => tag.tag === "coversCapability").map((tag) => normalizeCap(tag.value));
+    const symbolRefs = tags.filter((tag) => tag.tag === "coversSymbol").map((tag) => tag.value);
+    const publicApiRefs = tags.filter((tag) => tag.tag === "coversPublicApi").map((tag) => tag.value);
+    const contracts = tags.filter((tag) => tag.tag === "contract").map((tag) => tag.value);
+    const framework = detectTestFramework(filePath);
+    const name = `test-at-line-${startLine}`;
+    // Identity intentionally excludes testKind. The doc-block model carries no suite
+    // or title, so the derived local name acts as the stable within-file discriminator.
+    const id = testIdentityId({
+        framework,
+        filePath,
+        suitePath: "",
+        title: name,
+        parameterisationKey: null,
+        functionName: null,
+        localDeclarationKey: null
+    });
+    return {
+        test: {
+            id,
+            filePath,
+            name,
+            testKind: "unknown",
+            framework,
+            suitePath: "",
+            coversCapabilities: capabilityIds,
+            coversSymbols: symbolRefs,
+            coversPublicApis: publicApiRefs,
+            contracts,
+            provenance: { source: "test-docs" }
+        },
+        diagnostics: parsed.diagnostics
+    };
+}
+function detectTestFramework(filePath) {
+    const lower = filePath.toLowerCase();
+    if (lower.endsWith(".py")) {
+        return "pytest";
+    }
+    if (/\.(test|spec)\.[cm]?[jt]sx?$/.test(lower)) {
+        return "vitest";
+    }
+    return "unknown";
+}
+function resolveTestSymbolReferences(tests, symbols, packageModel) {
+    const index = buildSymbolRefIndex(symbols, packageModel.filePackageByPath);
+    const diagnostics = [];
+    for (const test of tests) {
+        const resolved = [];
+        for (const reference of test.coversSymbols) {
+            const result = resolveSymbolReference(reference, index);
+            if (result.status === "resolved") {
+                resolved.push(result.value);
+                continue;
+            }
+            if (result.status === "ambiguous") {
+                diagnostics.push({
+                    id: `diag:${test.id}:ambiguous_symbol_reference:${reference}`,
+                    severity: "warning",
+                    category: "resolution",
+                    code: "ambiguous_symbol_reference",
+                    message: `Test ${test.id} has ambiguous symbol reference ${reference}.`,
+                    filePath: test.filePath,
+                    target: { kind: "test", id: test.id },
+                    provenance: { source: "validation" }
+                });
+            }
+            resolved.push(reference);
+        }
+        test.coversSymbols = resolved;
+    }
+    return diagnostics;
+}
+function resolveTestPublicApiReferences(tests, publicApis, symbols, packageModel) {
+    const index = buildPublicApiRefIndex(publicApis, symbols, packageModel.filePackageByPath);
+    const diagnostics = [];
+    for (const test of tests) {
+        const resolved = [];
+        for (const reference of test.coversPublicApis) {
+            const result = resolvePublicApiReference(reference, index);
+            if (result.status === "resolved") {
+                resolved.push(result.value);
+                continue;
+            }
+            if (result.status === "ambiguous") {
+                diagnostics.push({
+                    id: `diag:${test.id}:ambiguous_public_api_reference:${reference}`,
+                    severity: "warning",
+                    category: "resolution",
+                    code: "ambiguous_public_api_reference",
+                    message: `Test ${test.id} has ambiguous public API reference ${reference}.`,
+                    filePath: test.filePath,
+                    target: { kind: "test", id: test.id },
+                    provenance: { source: "validation" }
+                });
+            }
+            resolved.push(reference);
+        }
+        test.coversPublicApis = [...new Set(resolved)].sort();
+    }
+    return diagnostics;
+}
+function duplicateIdDiagnostics(symbols, capabilities, publicApis, tests) {
+    const diagnostics = [];
+    const symbolSeen = new Set();
+    for (const symbol of symbols) {
+        if (symbolSeen.has(symbol.id)) {
+            diagnostics.push({
+                id: `diag:${symbol.id}:duplicate_symbol_id`,
+                severity: "error",
+                category: "indexing",
+                code: "duplicate_symbol_id",
+                message: `Duplicate symbol id found: ${symbol.id}.`,
+                filePath: symbol.filePath,
+                target: { kind: "symbol", id: symbol.id },
+                provenance: { source: "validation" }
+            });
+            continue;
+        }
+        symbolSeen.add(symbol.id);
+    }
+    const capabilitySeen = new Set();
+    for (const capability of capabilities) {
+        if (capabilitySeen.has(capability.id)) {
+            diagnostics.push({
+                id: `diag:${capability.id}:duplicate_capability_id`,
+                severity: "error",
+                category: "indexing",
+                code: "duplicate_capability_id",
+                message: `Duplicate capability id found: ${capability.id}.`,
+                target: { kind: "capability", id: capability.id },
+                provenance: { source: "validation" }
+            });
+            continue;
+        }
+        capabilitySeen.add(capability.id);
+    }
+    const publicApiSeen = new Set();
+    for (const publicApi of publicApis) {
+        if (publicApiSeen.has(publicApi.id)) {
+            diagnostics.push({
+                id: `diag:${publicApi.id}:duplicate_public_api_id`,
+                severity: "error",
+                category: "indexing",
+                code: "duplicate_public_api_id",
+                message: `Duplicate public API id found: ${publicApi.id}.`,
+                target: { kind: "publicApi", id: publicApi.id },
+                provenance: { source: "validation" }
+            });
+            continue;
+        }
+        publicApiSeen.add(publicApi.id);
+    }
+    const testSeen = new Set();
+    for (const test of tests) {
+        if (testSeen.has(test.id)) {
+            diagnostics.push({
+                id: `diag:${test.id}:duplicate_test_id`,
+                severity: "error",
+                category: "indexing",
+                code: "duplicate_test_id",
+                message: `Duplicate test id found: ${test.id}.`,
+                filePath: test.filePath,
+                target: { kind: "test", id: test.id },
+                provenance: { source: "validation" }
+            });
+            continue;
+        }
+        testSeen.add(test.id);
+    }
+    return diagnostics;
+}
+function buildTestRelationships(tests, symbols, publicApiBySymbolId, publicApiIds) {
+    const relationships = [];
+    const symbolIds = new Set(symbols.map((symbol) => symbol.id));
+    const pushEdge = (type, from, to, confidence) => {
+        relationships.push({
+            id: relationshipIdentityId({
+                type,
+                fromKind: from.kind,
+                fromId: from.id,
+                toKind: to.kind,
+                toId: to.id,
+                discriminant: null
+            }),
+            type,
+            from,
+            to,
+            confidence,
+            provenance: { source: "test-docs" }
+        });
+    };
+    for (const test of tests) {
+        for (const capabilityId of test.coversCapabilities) {
+            pushEdge("covers", { kind: "test", id: test.id }, { kind: "capability", id: capabilityId }, 0.9);
+            pushEdge("tests", { kind: "capability", id: capabilityId }, { kind: "test", id: test.id }, 0.9);
+        }
+        for (const symbolId of test.coversSymbols) {
+            if (!symbolIds.has(symbolId)) {
+                continue;
+            }
+            pushEdge("covers", { kind: "test", id: test.id }, { kind: "symbol", id: symbolId }, 0.9);
+            pushEdge("tests", { kind: "symbol", id: symbolId }, { kind: "test", id: test.id }, 0.9);
+            const publicApiId = publicApiBySymbolId.get(symbolId);
+            if (publicApiId) {
+                pushEdge("covers", { kind: "test", id: test.id }, { kind: "publicApi", id: publicApiId }, 0.85);
+                pushEdge("tests", { kind: "publicApi", id: publicApiId }, { kind: "test", id: test.id }, 0.85);
+            }
+        }
+        for (const publicApiId of test.coversPublicApis) {
+            if (!publicApiIds.has(publicApiId)) {
+                continue;
+            }
+            pushEdge("covers", { kind: "test", id: test.id }, { kind: "publicApi", id: publicApiId }, 0.9);
+            pushEdge("tests", { kind: "publicApi", id: publicApiId }, { kind: "test", id: test.id }, 0.9);
+        }
+    }
+    return sortRelationships(relationships);
+}
+/** Remap symbol endpoints of relationships onto canonical ids, preserving extracted ids as evidence. */
+function remapRelationshipEndpoints(relationships, canonicalBySymbolId) {
+    if (canonicalBySymbolId.size === 0) {
+        return;
+    }
+    for (const relationship of relationships) {
+        const fromMapped = relationship.from.kind === "symbol" ? canonicalBySymbolId.get(relationship.from.id) : undefined;
+        const toMapped = relationship.to.kind === "symbol" ? canonicalBySymbolId.get(relationship.to.id) : undefined;
+        if (!fromMapped && !toMapped) {
+            continue;
+        }
+        const extractedFromId = relationship.from.id;
+        const extractedToId = relationship.to.id;
+        if (fromMapped) {
+            relationship.from = { ...relationship.from, id: fromMapped };
+        }
+        if (toMapped) {
+            relationship.to = { ...relationship.to, id: toMapped };
+        }
+        const priorEvidence = relationship.evidence
+            ? [{ ...relationship.evidence, extractedFromId, extractedToId }]
+            : [{ extractedFromId, extractedToId }];
+        relationship.evidenceRanges = mergeEvidenceRanges([...(relationship.evidenceRanges ?? []), ...priorEvidence]);
+        relationship.id = relationshipIdentityId({
+            type: relationship.type,
+            fromKind: relationship.from.kind,
+            fromId: relationship.from.id,
+            toKind: relationship.to.kind,
+            toId: relationship.to.id,
+            discriminant: relationship.localDiscriminant ?? null
+        });
+    }
+    // Collapse semantically identical edges created from source + generated counterparts.
+    dedupeRelationshipsById(relationships);
+}
+function dedupeRelationshipsById(relationships) {
+    const byId = new Map();
+    const survivors = [];
+    for (const relationship of relationships) {
+        const existing = byId.get(relationship.id);
+        if (!existing) {
+            byId.set(relationship.id, relationship);
+            survivors.push(relationship);
+            continue;
+        }
+        existing.evidenceRanges = mergeEvidenceRanges([
+            ...(existing.evidenceRanges ?? []),
+            ...(relationship.evidenceRanges ?? []),
+            ...(relationship.evidence ? [relationship.evidence] : []),
+            ...(existing.evidence ? [existing.evidence] : [])
+        ]);
+        existing.confidence = Math.max(existing.confidence, relationship.confidence);
+    }
+    relationships.length = 0;
+    relationships.push(...survivors);
+}
+function mergeEvidenceRanges(ranges) {
+    const seen = new Set();
+    const merged = [];
+    for (const range of ranges) {
+        if (!range)
+            continue;
+        const key = JSON.stringify({
+            filePath: range.filePath ?? null,
+            startLine: range.startLine ?? range.line ?? null,
+            endLine: range.endLine ?? null,
+            extractedFromId: range.extractedFromId ?? null,
+            extractedToId: range.extractedToId ?? null,
+            text: range.text ?? null
+        });
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        merged.push(range);
+    }
+    return merged.sort((a, b) => {
+        const aPath = a.filePath ?? "";
+        const bPath = b.filePath ?? "";
+        if (aPath !== bPath)
+            return aPath.localeCompare(bPath);
+        const aLine = a.startLine ?? a.line ?? 0;
+        const bLine = b.startLine ?? b.line ?? 0;
+        if (aLine !== bLine)
+            return aLine - bLine;
+        return JSON.stringify(a).localeCompare(JSON.stringify(b));
+    });
+}
+/** Detect full-id hash collisions across all persisted entities and fail closed. */
+function assertNoIdentityCollisions(packages, symbols, publicApis, tests, relationships, capabilities, examples, diagnostics) {
+    const tracker = new IdentityCollisionTracker();
+    const check = (id, preimageJson) => {
+        const result = tracker.register(id, preimageJson);
+        if (result.collision) {
+            const message = `Identity hash collision on ${id}: ${result.priorPreimage} vs ${preimageJson}.`;
+            diagnostics.push({
+                id: `diag:${id}:identity_hash_collision`,
+                severity: "error",
+                category: "indexing",
+                code: "identity_hash_collision",
+                message,
+                provenance: { source: "identity" }
+            });
+            throw new IdentityCollisionError(message);
+        }
+    };
+    for (const packageRecord of packages) {
+        const identityName = packageRecord.name || "unnamed";
+        check(packageRecord.id, encodeIdentityPreimage("package", [
+            normalizeIdentityString(packageRecord.ecosystem ?? "unknown"),
+            normalizeIdentityString(identityName),
+            normalizeIdentityPath(packageRecord.path)
+        ]));
+    }
+    for (const symbol of symbols) {
+        check(symbol.id, encodeIdentityPreimage("symbol", [
+            normalizeIdentityString(symbol.language),
+            normalizeIdentityString(symbol.kind),
+            normalizeIdentityString(symbol.packageId ?? "package:unknown"),
+            normalizeIdentityPath(symbol.modulePath ?? symbol.filePath),
+            normalizeIdentityString(symbol.qualifiedContainerPath ?? ""),
+            normalizeIdentityString(symbol.name)
+        ]));
+    }
+    for (const api of publicApis) {
+        check(api.id, encodeIdentityPreimage("public-api", [
+            normalizeIdentityString(api.packageId ?? "package:unknown"),
+            normalizeIdentityString(api.importPath ?? ""),
+            normalizeIdentityString(api.name),
+            normalizeIdentityString(api.exportKind ?? "named")
+        ]));
+    }
+    for (const test of tests) {
+        check(test.id, encodeIdentityPreimage("test", [
+            normalizeIdentityString(test.framework ?? "unknown"),
+            normalizeIdentityPath(test.filePath),
+            normalizeIdentityString(test.suitePath ?? ""),
+            normalizeIdentityString(test.name),
+            null,
+            null,
+            null
+        ]));
+    }
+    for (const relationship of relationships) {
+        check(relationship.id, encodeIdentityPreimage("relationship", [
+            normalizeIdentityString(relationship.type),
+            normalizeIdentityString(relationship.from.kind),
+            normalizeIdentityString(relationship.from.id),
+            normalizeIdentityString(relationship.to.kind),
+            normalizeIdentityString(relationship.to.id),
+            relationship.localDiscriminant === null || relationship.localDiscriminant === undefined
+                ? null
+                : normalizeIdentityString(relationship.localDiscriminant)
+        ]));
+    }
+    for (const capability of capabilities) {
+        check(capability.id, encodeIdentityPreimage("capability", [normalizeIdentityString(capability.name)]));
+    }
+    for (const example of examples) {
+        check(example.id, encodeIdentityPreimage("example", [
+            normalizeIdentityString(example.filePath ?? ""),
+            normalizeIdentityString(example.anchor ?? ""),
+            normalizeIdentityString(example.title ?? "")
+        ]));
+    }
+    for (const diagnostic of diagnostics) {
+        check(diagnostic.id, encodeIdentityPreimage("diagnostic", [
+            normalizeIdentityString(diagnostic.code),
+            normalizeIdentityString(diagnostic.filePath ?? ""),
+            normalizeIdentityString(diagnostic.target?.kind ?? ""),
+            normalizeIdentityString(diagnostic.target?.id ?? ""),
+            normalizeIdentityString(diagnostic.message)
+        ]));
+    }
+}
+export class IdentityCollisionError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "IdentityCollisionError";
+    }
+}
+/** Exported for indexing-level collision tests. */
+export { assertNoIdentityCollisions };
+function extractDocBlocks(content, language) {
+    const blocks = [];
+    if (language === "typescript" || language === "javascript") {
+        const pattern = /\/\*\*([\s\S]*?)\*\//g;
+        let match;
+        while ((match = pattern.exec(content)) !== null) {
+            const before = content.slice(0, match.index);
+            const startLine = before.split(/\r?\n/).length;
+            blocks.push({ text: match[1] ?? "", startLine });
+        }
+        return blocks;
+    }
+    if (language === "python") {
+        const pattern = /(["']{3})([\s\S]*?)\1/g;
+        let match;
+        while ((match = pattern.exec(content)) !== null) {
+            const before = content.slice(0, match.index);
+            const startLine = before.split(/\r?\n/).length;
+            blocks.push({ text: match[2] ?? "", startLine });
+        }
+        return blocks;
+    }
+    return blocks;
+}
+function packageDocDiagnostics(files, packages) {
+    if (packages.length > 0) {
+        return [];
+    }
+    const hasCatalogueDoc = files.some((file) => /(^|\/)CATALOGUE\.md$/i.test(file.path));
+    if (hasCatalogueDoc) {
+        return [];
+    }
+    return [
+        {
+            id: "diag:package_missing_catalogue_doc",
+            severity: "warning",
+            category: "documentation",
+            code: "package_missing_catalogue_doc",
+            message: "No package-level CATALOGUE.md was found.",
+            provenance: { source: "validation" }
+        }
+    ];
+}
+function normalizeCap(value) {
+    return value.startsWith("capability:") ? value : `capability:${value}`;
+}
+export function shouldFailFromDiagnostics(mode, diagnostics) {
+    if (mode === "never") {
+        return false;
+    }
+    const threshold = mode === "error" ? 3 : mode === "warning" ? 2 : 1;
+    for (const diagnostic of diagnostics) {
+        const level = diagnostic.severity === "error" ? 3 : diagnostic.severity === "warning" ? 2 : 1;
+        if (level >= threshold) {
+            return true;
+        }
+    }
+    return false;
+}
+export function staleCommittedCatalogue(workspaceRoot, snapshot, catalogueDir) {
+    const currentPath = path.resolve(workspaceRoot, catalogueDir, "catalogue.json");
+    try {
+        const current = JSON.parse(readFileSync(currentPath, "utf8"));
+        return current.catalogueId !== snapshot.catalogueId;
+    }
+    catch {
+        return true;
+    }
+}