@mortice/mapwright 0.8.0

package/dist/catalogue/canonicalisation.js

@@ -0,0 +1,262 @@
+import { normalizeIdentityPath } from "./identity.js";
+const GENERATED_ROOTS = ["dist", "build", "out"];
+function toPosix(filePath) {
+    return normalizeIdentityPath(filePath);
+}
+/** Path is under a build output tree (dist/build/out). */
+export function isBuildOutputPath(filePath) {
+    const normalized = toPosix(filePath);
+    return /(^|\/)(dist|build|out)(\/|$)/.test(normalized);
+}
+/**
+ * A symbol is treated as generated when its file is a build artefact, is a
+ * declaration file, or its provenance already marks it as generated.
+ */
+export function isGeneratedSymbol(symbol) {
+    if (symbol.symbolProvenance === "generated_declaration" || symbol.symbolProvenance === "generated_only") {
+        return true;
+    }
+    const normalized = toPosix(symbol.filePath);
+    if (isBuildOutputPath(normalized)) {
+        return true;
+    }
+    return normalized.endsWith(".d.ts");
+}
+/**
+ * Strip a single source or generated root segment and the file extension so
+ * relative module topology can be compared (e.g. src/a/b.ts ↔ dist/a/b.d.ts).
+ */
+export function moduleTopologyKey(filePath) {
+    let normalized = toPosix(filePath);
+    // Strip known source / emit roots (including nested package roots).
+    normalized = normalized.replace(/(^|\/)src\//, "$1");
+    for (const root of GENERATED_ROOTS) {
+        const pattern = new RegExp(`(^|/)${root}/`);
+        normalized = normalized.replace(pattern, "$1");
+    }
+    // .d.ts before .ts
+    if (normalized.endsWith(".d.ts")) {
+        normalized = normalized.slice(0, -".d.ts".length);
+    }
+    else {
+        normalized = normalized.replace(/\.[^.\/]+$/, "");
+    }
+    // Drop trailing /index for topology equivalence of package entry modules.
+    normalized = normalized.replace(/\/index$/, "");
+    return normalized;
+}
+/** Category B: authored and generated files share module topology after src↔emit transform. */
+export function hasSourceOutputMapping(authored, generated) {
+    if (!isGeneratedSymbol(generated) || isGeneratedSymbol(authored)) {
+        return false;
+    }
+    const authoredPath = toPosix(authored.filePath);
+    const generatedPath = toPosix(generated.filePath);
+    // Generated must sit under a known emit root or be a .d.ts sibling of source topology.
+    const generatedUnderEmit = isBuildOutputPath(generatedPath) || generatedPath.endsWith(".d.ts");
+    if (!generatedUnderEmit) {
+        return false;
+    }
+    // Authored should not itself be under emit roots (unless only .d.ts-without-source case).
+    if (isBuildOutputPath(authoredPath)) {
+        return false;
+    }
+    const authoredKey = moduleTopologyKey(authoredPath);
+    const generatedKey = moduleTopologyKey(generatedPath);
+    if (!authoredKey || !generatedKey) {
+        return false;
+    }
+    return authoredKey === generatedKey;
+}
+/**
+ * Category A: declaration equivalence stronger than package+name+kind alone.
+ * Requires matching qualified declaration identity (container + name) and kind,
+ * plus compatible signature fingerprint when both are present.
+ */
+export function categoryACompatible(a, b) {
+    if ((a.packageId ?? "package:unknown") !== (b.packageId ?? "package:unknown")) {
+        return false;
+    }
+    if (a.name !== b.name || a.kind !== b.kind) {
+        return false;
+    }
+    const aContainer = a.qualifiedContainerPath ?? "";
+    const bContainer = b.qualifiedContainerPath ?? "";
+    if (aContainer !== bContainer) {
+        return false;
+    }
+    // Prefer qualifiedName when both use the same logical module-qualified form after topology normalize.
+    // Do not require identical filePath-qualified strings (those differ across src/dist).
+    const aLogical = `${aContainer}\u0000${a.name}`;
+    const bLogical = `${bContainer}\u0000${b.name}`;
+    if (aLogical !== bLogical) {
+        return false;
+    }
+    if (a.signatureFingerprint && b.signatureFingerprint && a.signatureFingerprint !== b.signatureFingerprint) {
+        // Implementation vs declare-form fingerprints commonly differ; allow when exactly one side is generated.
+        const aGenerated = isGeneratedSymbol(a);
+        const bGenerated = isGeneratedSymbol(b);
+        if (aGenerated === bGenerated) {
+            return false;
+        }
+    }
+    return true;
+}
+/** Soft Category A grouping key used to find candidate pairs (not sufficient alone to collapse). */
+function softGroupKey(symbol) {
+    const packageId = symbol.packageId ?? "package:unknown";
+    const container = symbol.qualifiedContainerPath ?? "";
+    return `${packageId}\u0000${container}\u0000${symbol.name}\u0000${symbol.kind}`;
+}
+export function validateSymbolProvenance(symbol) {
+    const provenance = symbol.symbolProvenance ?? "authored_source";
+    const canonical = symbol.canonicalSymbolId ?? symbol.id;
+    const duplicateOf = symbol.duplicateOf ?? null;
+    if (provenance === "authored_source") {
+        if (canonical !== symbol.id || duplicateOf !== null) {
+            return `authored_source requires self-canonical id and null duplicateOf (got canonical=${canonical}, duplicateOf=${duplicateOf})`;
+        }
+    }
+    else if (provenance === "generated_declaration") {
+        if (!duplicateOf || canonical !== duplicateOf) {
+            return `generated_declaration requires duplicateOf === canonicalSymbolId pointing at authored source`;
+        }
+        if (duplicateOf === symbol.id) {
+            return `generated_declaration must not duplicate itself`;
+        }
+    }
+    else if (provenance === "generated_only") {
+        if (canonical !== symbol.id || duplicateOf !== null) {
+            return `generated_only requires self-canonical id and null duplicateOf`;
+        }
+    }
+    return undefined;
+}
+function applyAuthoredDefaults(symbol) {
+    symbol.canonicalSymbolId = symbol.id;
+    symbol.duplicateOf = null;
+    if (isGeneratedSymbol(symbol)) {
+        symbol.symbolProvenance = "generated_only";
+    }
+    else {
+        symbol.symbolProvenance = "authored_source";
+    }
+}
+/**
+ * Assign canonical identities to symbols in place.
+ *
+ * Returns a map from collapsed duplicate symbol id to its canonical symbol id.
+ */
+export function canonicaliseSymbols(symbols, diagnostics) {
+    const canonicalById = new Map();
+    for (const symbol of symbols) {
+        applyAuthoredDefaults(symbol);
+    }
+    const groups = new Map();
+    for (const symbol of symbols) {
+        const key = softGroupKey(symbol);
+        const bucket = groups.get(key);
+        if (bucket) {
+            bucket.push(symbol);
+        }
+        else {
+            groups.set(key, [symbol]);
+        }
+    }
+    for (const group of groups.values()) {
+        if (group.length < 2) {
+            continue;
+        }
+        const sources = group.filter((symbol) => !isGeneratedSymbol(symbol));
+        const generated = group.filter((symbol) => isGeneratedSymbol(symbol));
+        // Ambiguous: multiple authored sources in the soft group — never collapse.
+        if (sources.length !== 1) {
+            emitPossibleDuplicates(group, diagnostics, "ambiguous or missing authored source for Category B mapping");
+            continue;
+        }
+        const canonical = sources[0];
+        if (generated.length === 0) {
+            // Multiple soft-group members that are all authored — already handled by sources.length !== 1,
+            // but keep possible_generated_duplicate if somehow mixed without generated classification.
+            continue;
+        }
+        let collapsedAny = false;
+        for (const duplicate of generated) {
+            const aOk = categoryACompatible(canonical, duplicate);
+            const bOk = hasSourceOutputMapping(canonical, duplicate);
+            if (aOk && bOk) {
+                duplicate.canonicalSymbolId = canonical.id;
+                duplicate.duplicateOf = canonical.id;
+                duplicate.symbolProvenance = "generated_declaration";
+                canonicalById.set(duplicate.id, canonical.id);
+                collapsedAny = true;
+                continue;
+            }
+            // Category A alone or weak path proximity → diagnostic, leave self-canonical.
+            if (aOk && !bOk) {
+                diagnostics.push({
+                    id: `diag:${duplicate.id}:possible_generated_duplicate`,
+                    severity: "info",
+                    category: "indexing",
+                    code: "possible_generated_duplicate",
+                    message: `Symbol ${duplicate.name} (${duplicate.kind}) in ${duplicate.filePath} matches authored ${canonical.filePath} on declaration identity but lacks a proven source↔output module mapping; not collapsed.`,
+                    filePath: duplicate.filePath,
+                    target: { kind: "symbol", id: duplicate.id },
+                    provenance: { source: "canonicalisation" }
+                });
+            }
+        }
+        // Soft group shared package/name/kind with no successful Category B collapses.
+        if (!collapsedAny && generated.length > 0) {
+            // Diagnostics already emitted for A-without-B; if no A either, still warn once per generated.
+            for (const duplicate of generated) {
+                if (categoryACompatible(canonical, duplicate)) {
+                    continue;
+                }
+                diagnostics.push({
+                    id: `diag:${duplicate.id}:possible_generated_duplicate`,
+                    severity: "info",
+                    category: "indexing",
+                    code: "possible_generated_duplicate",
+                    message: `Symbol ${duplicate.name} (${duplicate.kind}) in ${duplicate.filePath} shares package/name/kind with other declarations but Category A+B mapping was not established; not collapsed.`,
+                    filePath: duplicate.filePath,
+                    target: { kind: "symbol", id: duplicate.id },
+                    provenance: { source: "canonicalisation" }
+                });
+            }
+        }
+    }
+    for (const symbol of symbols) {
+        const error = validateSymbolProvenance(symbol);
+        if (error) {
+            diagnostics.push({
+                id: `diag:${symbol.id}:invalid_symbol_provenance`,
+                severity: "error",
+                category: "indexing",
+                code: "invalid_symbol_provenance",
+                message: error,
+                filePath: symbol.filePath,
+                target: { kind: "symbol", id: symbol.id },
+                provenance: { source: "canonicalisation" }
+            });
+            // Repair to a safe self-canonical generated_only / authored_source state.
+            applyAuthoredDefaults(symbol);
+            canonicalById.delete(symbol.id);
+        }
+    }
+    return canonicalById;
+}
+function emitPossibleDuplicates(group, diagnostics, reason) {
+    for (const symbol of group) {
+        diagnostics.push({
+            id: `diag:${symbol.id}:possible_generated_duplicate`,
+            severity: "info",
+            category: "indexing",
+            code: "possible_generated_duplicate",
+            message: `Symbol ${symbol.name} (${symbol.kind}) in ${symbol.filePath}: ${reason}; not collapsed.`,
+            filePath: symbol.filePath,
+            target: { kind: "symbol", id: symbol.id },
+            provenance: { source: "canonicalisation" }
+        });
+    }
+}

package/dist/catalogue/config.d.ts

@@ -0,0 +1,13 @@
+import type { CatalogueConfig, CatalogueMode } from "./schema.js";
+export declare const DEFAULT_EXCLUDES: string[];
+export declare const DEFAULT_CONFIG: CatalogueConfig;
+export interface LoadConfigOptions {
+    workspaceRoot: string;
+    configPath?: string;
+    mode?: CatalogueMode;
+}
+export declare function loadConfig(options: LoadConfigOptions): {
+    config: CatalogueConfig;
+    mode: CatalogueMode;
+    configPath?: string;
+};

package/dist/catalogue/config.js

@@ -0,0 +1,77 @@
+import { existsSync, readFileSync } from "node:fs";
+import path from "node:path";
+export const DEFAULT_EXCLUDES = [
+    ".git/**",
+    "node_modules/**",
+    "**/dist/**",
+    "**/build/**",
+    "**/out/**",
+    "**/coverage/**",
+    "**/.next/**",
+    "**/.expo/**",
+    "**/.pytest_cache/**",
+    ".vscode-test/**",
+    "__pycache__/**",
+    "**/*.egg-info/**",
+    ".env",
+    ".env.*",
+    "*.pem",
+    "*.key",
+    "*.p12",
+    "*.pfx"
+];
+export const DEFAULT_CONFIG = {
+    schemaVersion: 2,
+    catalogueDir: ".mapwright",
+    committedCatalogue: true,
+    languages: ["typescript", "javascript", "python", "markdown", "json"],
+    include: ["src/**", "packages/**", "tests/**", "CATALOGUE.md", "README.md"],
+    exclude: DEFAULT_EXCLUDES,
+    documentation: {
+        requirePublicApiDocs: true,
+        requireCapabilityForPublicApi: true
+    },
+    validation: {
+        failOn: "warning"
+    },
+    limits: {
+        maxFileSizeBytes: 512000,
+        maxIndexedFiles: 10000,
+        maxSourcePreviewLines: 120
+    }
+};
+export function loadConfig(options) {
+    const resolvedConfigPath = options.configPath
+        ? path.resolve(options.workspaceRoot, options.configPath)
+        : path.resolve(options.workspaceRoot, "mapwright.config.json");
+    let userConfig = {};
+    let foundPath;
+    if (existsSync(resolvedConfigPath)) {
+        userConfig = JSON.parse(readFileSync(resolvedConfigPath, "utf8"));
+        foundPath = resolvedConfigPath;
+    }
+    const config = {
+        ...DEFAULT_CONFIG,
+        ...userConfig,
+        documentation: {
+            ...DEFAULT_CONFIG.documentation,
+            ...(userConfig.documentation ?? {})
+        },
+        validation: {
+            ...DEFAULT_CONFIG.validation,
+            ...(userConfig.validation ?? {})
+        },
+        limits: {
+            ...DEFAULT_CONFIG.limits,
+            ...(userConfig.limits ?? {})
+        },
+        include: userConfig.include ?? DEFAULT_CONFIG.include,
+        exclude: dedupe([...(DEFAULT_CONFIG.exclude ?? []), ...(userConfig.exclude ?? [])]),
+        languages: userConfig.languages ?? DEFAULT_CONFIG.languages
+    };
+    const mode = options.mode ?? (config.committedCatalogue ? "committed" : "local");
+    return { config, mode, configPath: foundPath };
+}
+function dedupe(values) {
+    return [...new Set(values)];
+}

package/dist/catalogue/deterministic.d.ts

@@ -0,0 +1,3 @@
+export declare function stableStringify(input: unknown, pretty?: boolean): string;
+export declare function hashContent(content: string): string;
+export declare function stableId(parts: string[]): string;

package/dist/catalogue/deterministic.js

@@ -0,0 +1,25 @@
+import { createHash } from "node:crypto";
+export function stableStringify(input, pretty = false) {
+    return JSON.stringify(sortValue(input), null, pretty ? 2 : 0) + "\n";
+}
+export function hashContent(content) {
+    return `sha256:${createHash("sha256").update(content).digest("hex")}`;
+}
+export function stableId(parts) {
+    return hashContent(parts.join("|"));
+}
+function sortValue(value) {
+    if (Array.isArray(value)) {
+        return value.map(sortValue);
+    }
+    if (value && typeof value === "object") {
+        const obj = value;
+        const sortedKeys = Object.keys(obj).sort();
+        const out = {};
+        for (const key of sortedKeys) {
+            out[key] = sortValue(obj[key]);
+        }
+        return out;
+    }
+    return value;
+}

package/dist/catalogue/diagnostics.d.ts

@@ -0,0 +1,2 @@
+import type { CatalogueConfig, DiagnosticRecord, SymbolRecord } from "./schema.js";
+export declare function buildDiagnostics(symbols: SymbolRecord[], config: CatalogueConfig): DiagnosticRecord[];

package/dist/catalogue/diagnostics.js

@@ -0,0 +1,34 @@
+import { isExamplesTreePath } from "./scanner.js";
+export function buildDiagnostics(symbols, config) {
+    const diagnostics = [];
+    for (const symbol of symbols) {
+        if (!symbol.exported || isExamplesTreePath(symbol.filePath)) {
+            continue;
+        }
+        if (config.documentation.requirePublicApiDocs && !symbol.doc?.present) {
+            diagnostics.push({
+                id: `diag:${symbol.id}:public_symbol_missing_catalogue_doc`,
+                severity: "warning",
+                category: "documentation",
+                code: "public_symbol_missing_catalogue_doc",
+                message: `Exported symbol ${symbol.name} is missing catalogue documentation.`,
+                filePath: symbol.filePath,
+                target: { kind: "symbol", id: symbol.id },
+                provenance: { source: "validation" }
+            });
+        }
+        if (config.documentation.requireCapabilityForPublicApi && symbol.capabilities.length === 0) {
+            diagnostics.push({
+                id: `diag:${symbol.id}:public_symbol_missing_capability`,
+                severity: "warning",
+                category: "documentation",
+                code: "public_symbol_missing_capability",
+                message: `Exported symbol ${symbol.name} is missing a @capability tag.`,
+                filePath: symbol.filePath,
+                target: { kind: "symbol", id: symbol.id },
+                provenance: { source: "validation" }
+            });
+        }
+    }
+    return diagnostics;
+}

package/dist/catalogue/evidence.d.ts

@@ -0,0 +1 @@
+export declare function truncateEvidenceText(text: string | undefined, maxLength?: number): string | undefined;

package/dist/catalogue/evidence.js

@@ -0,0 +1,10 @@
+export function truncateEvidenceText(text, maxLength = 300) {
+    if (!text) {
+        return undefined;
+    }
+    const normalized = text.replace(/\s+/g, " ").trim();
+    if (normalized.length <= maxLength) {
+        return normalized;
+    }
+    return `${normalized.slice(0, Math.max(0, maxLength - 3)).trimEnd()}...`;
+}

package/dist/catalogue/examples.d.ts

@@ -0,0 +1,3 @@
+export declare function normalizeExamplePath(value: string | undefined): string | undefined;
+export declare function buildExampleIdentity(filePath: string | undefined, anchor: string | undefined, fallbackReference: string): string;
+export declare function buildDeterministicExampleId(filePath: string | undefined, anchor: string | undefined, fallbackReference: string): string;

package/dist/catalogue/examples.js

@@ -0,0 +1,20 @@
+import { hashContent } from "./deterministic.js";
+export function normalizeExamplePath(value) {
+    if (!value) {
+        return undefined;
+    }
+    const normalized = value.trim().replaceAll("\\", "/");
+    return normalized || undefined;
+}
+export function buildExampleIdentity(filePath, anchor, fallbackReference) {
+    const normalizedPath = normalizeExamplePath(filePath)?.toLowerCase();
+    const normalizedAnchor = anchor?.trim().toLowerCase() || undefined;
+    if (normalizedPath || normalizedAnchor) {
+        return `${normalizedPath ?? ""}#${normalizedAnchor ?? ""}`;
+    }
+    return fallbackReference.trim().toLowerCase();
+}
+export function buildDeterministicExampleId(filePath, anchor, fallbackReference) {
+    const identity = buildExampleIdentity(filePath, anchor, fallbackReference);
+    return `example:${hashContent(identity).replace(/^sha256:/, "")}`;
+}

package/dist/catalogue/identity.d.ts

@@ -0,0 +1,61 @@
+export declare const IDENTITY_NAMESPACE = "code-atlas-identity";
+export declare const IDENTITY_SCHEME = "stable-sha256-v1";
+export type IdentityDomain = "package" | "symbol" | "public-api" | "test" | "relationship" | "capability" | "example" | "diagnostic";
+export type IdentityField = string | number | boolean | null;
+/** Unicode NFC normalization for identity string inputs. */
+export declare function normalizeIdentityString(value: string): string;
+/** Repo-relative POSIX path for identity inputs (no absolute paths). */
+export declare function normalizeIdentityPath(filePath: string): string;
+/**
+ * Deterministic JSON array encoding: fixed order, null vs "", no omitted middle fields.
+ * Uses JSON.stringify on a plain array (stable for primitives).
+ */
+export declare function encodeIdentityPreimage(domain: IdentityDomain, fields: IdentityField[]): string;
+export declare function hashIdentityPreimage(preimageJson: string): string;
+export declare function stableIdentityId(domain: IdentityDomain, fields: IdentityField[], prefix?: string): string;
+export declare function packageIdentityId(input: {
+    ecosystem: "npm" | "python" | "unknown";
+    name: string;
+    root: string;
+}): string;
+export declare function symbolIdentityId(input: {
+    language: string;
+    kind: string;
+    packageId: string;
+    modulePath: string;
+    qualifiedContainerPath: string;
+    declaredName: string;
+}): string;
+export declare function publicApiIdentityId(input: {
+    packageId: string;
+    importPath: string;
+    exportedName: string;
+    exportKind: string;
+}): string;
+export declare function testIdentityId(input: {
+    framework: string;
+    filePath: string;
+    suitePath: string;
+    title: string;
+    parameterisationKey: string | null;
+    functionName: string | null;
+    localDeclarationKey: string | null;
+}): string;
+export declare function relationshipIdentityId(input: {
+    type: string;
+    fromKind: string;
+    fromId: string;
+    toKind: string;
+    toId: string;
+    discriminant: string | null;
+}): string;
+export declare function signatureFingerprint(parts: IdentityField[]): string;
+export declare function implementationFingerprint(parts: IdentityField[]): string;
+/** Detect duplicate full IDs with different preimages during indexing. */
+export declare class IdentityCollisionTracker {
+    private readonly seen;
+    register(id: string, preimageJson: string): {
+        collision: boolean;
+        priorPreimage?: string;
+    };
+}

package/dist/catalogue/identity.js

@@ -0,0 +1,114 @@
+/**
+ * Canonical identity encoder for schema 2 (`stable-sha256-v1`).
+ * Preimage: JSON array ["code-atlas-identity", "stable-sha256-v1", domain, ...fields] as UTF-8 → SHA-256.
+ */
+import { createHash } from "node:crypto";
+// FROZEN: namespace string inherited from the pre-release Code Atlas era.
+// Do not rename — changing it would change every stable identity ID in existing catalogues.
+export const IDENTITY_NAMESPACE = "code-atlas-identity";
+export const IDENTITY_SCHEME = "stable-sha256-v1";
+/** Unicode NFC normalization for identity string inputs. */
+export function normalizeIdentityString(value) {
+    return value.normalize("NFC");
+}
+/** Repo-relative POSIX path for identity inputs (no absolute paths). */
+export function normalizeIdentityPath(filePath) {
+    const nfc = normalizeIdentityString(filePath);
+    let posix = nfc.replaceAll("\\", "/");
+    while (posix.startsWith("./")) {
+        posix = posix.slice(2);
+    }
+    if (posix.length > 1 && posix.endsWith("/")) {
+        posix = posix.slice(0, -1);
+    }
+    return posix === "" ? "." : posix;
+}
+/**
+ * Deterministic JSON array encoding: fixed order, null vs "", no omitted middle fields.
+ * Uses JSON.stringify on a plain array (stable for primitives).
+ */
+export function encodeIdentityPreimage(domain, fields) {
+    const preimage = [IDENTITY_NAMESPACE, IDENTITY_SCHEME, domain, ...fields];
+    return JSON.stringify(preimage);
+}
+export function hashIdentityPreimage(preimageJson) {
+    return createHash("sha256").update(preimageJson, "utf8").digest("hex");
+}
+export function stableIdentityId(domain, fields, prefix) {
+    const digest = hashIdentityPreimage(encodeIdentityPreimage(domain, fields));
+    if (prefix) {
+        return `${prefix}${digest}`;
+    }
+    return `${domain}:${digest}`;
+}
+export function packageIdentityId(input) {
+    return stableIdentityId("package", [
+        normalizeIdentityString(input.ecosystem),
+        normalizeIdentityString(input.name || "unnamed"),
+        normalizeIdentityPath(input.root)
+    ]);
+}
+export function symbolIdentityId(input) {
+    const digest = hashIdentityPreimage(encodeIdentityPreimage("symbol", [
+        normalizeIdentityString(input.language),
+        normalizeIdentityString(input.kind),
+        normalizeIdentityString(input.packageId),
+        normalizeIdentityPath(input.modulePath),
+        normalizeIdentityString(input.qualifiedContainerPath),
+        normalizeIdentityString(input.declaredName)
+    ]));
+    return `symbol:${input.language}:${input.kind}:${digest}`;
+}
+export function publicApiIdentityId(input) {
+    return stableIdentityId("public-api", [
+        normalizeIdentityString(input.packageId),
+        normalizeIdentityString(input.importPath),
+        normalizeIdentityString(input.exportedName),
+        normalizeIdentityString(input.exportKind)
+    ]);
+}
+export function testIdentityId(input) {
+    const digest = hashIdentityPreimage(encodeIdentityPreimage("test", [
+        normalizeIdentityString(input.framework),
+        normalizeIdentityPath(input.filePath),
+        normalizeIdentityString(input.suitePath),
+        normalizeIdentityString(input.title),
+        input.parameterisationKey === null ? null : normalizeIdentityString(input.parameterisationKey),
+        input.functionName === null ? null : normalizeIdentityString(input.functionName),
+        input.localDeclarationKey === null ? null : normalizeIdentityString(input.localDeclarationKey)
+    ]));
+    return `test:${input.framework}:${digest}`;
+}
+export function relationshipIdentityId(input) {
+    return stableIdentityId("relationship", [
+        normalizeIdentityString(input.type),
+        normalizeIdentityString(input.fromKind),
+        normalizeIdentityString(input.fromId),
+        normalizeIdentityString(input.toKind),
+        normalizeIdentityString(input.toId),
+        input.discriminant === null ? null : normalizeIdentityString(input.discriminant)
+    ]);
+}
+// FROZEN: "code-atlas-fingerprint" preimage strings inherited from the pre-release Code Atlas era.
+// Do not rename — changing them would change every fingerprint hash in existing catalogues.
+export function signatureFingerprint(parts) {
+    return hashIdentityPreimage(JSON.stringify(["code-atlas-fingerprint", "signature-v1", ...parts]));
+}
+export function implementationFingerprint(parts) {
+    return hashIdentityPreimage(JSON.stringify(["code-atlas-fingerprint", "implementation-v1", ...parts]));
+}
+/** Detect duplicate full IDs with different preimages during indexing. */
+export class IdentityCollisionTracker {
+    seen = new Map();
+    register(id, preimageJson) {
+        const prior = this.seen.get(id);
+        if (prior === undefined) {
+            this.seen.set(id, preimageJson);
+            return { collision: false };
+        }
+        if (prior === preimageJson) {
+            return { collision: false };
+        }
+        return { collision: true, priorPreimage: prior };
+    }
+}

package/dist/catalogue/ignore.d.ts

@@ -0,0 +1,4 @@
+import type { CatalogueConfig } from "./schema.js";
+export declare function createIgnoreMatcher(workspaceRoot: string, config: CatalogueConfig): (relativePath: string) => boolean;
+export declare function isIncludedByGlob(relativePath: string, include: string[]): boolean;
+export declare function normalize(filePath: string): string;

package/dist/catalogue/ignore.js

@@ -0,0 +1,29 @@
+import path from "node:path";
+import ignore from "ignore";
+import { minimatch } from "minimatch";
+export function createIgnoreMatcher(workspaceRoot, config) {
+    const ig = ignore();
+    ig.add(config.exclude);
+    return (relativePath) => {
+        const normalized = normalize(relativePath);
+        if (!normalized) {
+            return false;
+        }
+        if (ig.ignores(normalized)) {
+            return true;
+        }
+        // Path traversal and absolute path protection for scanner safety.
+        const absolute = path.resolve(workspaceRoot, normalized);
+        if (!absolute.startsWith(path.resolve(workspaceRoot))) {
+            return true;
+        }
+        return config.exclude.some((pattern) => minimatch(normalized, pattern, { dot: true }));
+    };
+}
+export function isIncludedByGlob(relativePath, include) {
+    const normalized = normalize(relativePath);
+    return include.some((pattern) => minimatch(normalized, pattern, { dot: true }));
+}
+export function normalize(filePath) {
+    return filePath.replaceAll(path.sep, "/").replace(/^\.\//, "");
+}