@mortice/mapwright 0.8.0

package/dist/comparison/projections.js

@@ -0,0 +1,185 @@
+function sortedUnique(values) {
+    return [...new Set(values ?? [])].sort();
+}
+function equalJson(a, b) {
+    return JSON.stringify(a) === JSON.stringify(b);
+}
+function pushFacet(facets, facet, oldValue, newValue) {
+    if (!equalJson(oldValue, newValue)) {
+        facets.push({ facet, oldValue, newValue });
+    }
+}
+function pushUnavailable(facets, facet, oldValue, newValue) {
+    if (oldValue == null && newValue == null) {
+        return;
+    }
+    if (oldValue == null || newValue == null) {
+        facets.push({ facet, oldValue, newValue, evidenceUnavailable: true });
+        return;
+    }
+    pushFacet(facets, facet, oldValue, newValue);
+}
+/** Strip line/column ranges from relationship evidence for semantic comparison. */
+export function semanticRelationshipEvidence(evidence) {
+    if (evidence == null)
+        return null;
+    if (Array.isArray(evidence)) {
+        return evidence.map((item) => semanticRelationshipEvidence(item));
+    }
+    if (typeof evidence !== "object")
+        return evidence;
+    const rec = evidence;
+    const out = {};
+    for (const [key, value] of Object.entries(rec)) {
+        if (key === "line" ||
+            key === "startLine" ||
+            key === "endLine" ||
+            key === "startColumn" ||
+            key === "endColumn" ||
+            key === "column") {
+            continue;
+        }
+        out[key] = value;
+    }
+    return out;
+}
+export function recordKey(domain, record) {
+    if (domain === "files") {
+        return String(record.path ?? "");
+    }
+    return String(record.id ?? "");
+}
+export function indexDomain(domain, snapshot) {
+    const map = new Map();
+    const collection = collectionFor(domain, snapshot);
+    for (const item of collection) {
+        const rec = item;
+        const key = recordKey(domain, rec);
+        if (key) {
+            map.set(key, rec);
+        }
+    }
+    return map;
+}
+function collectionFor(domain, snapshot) {
+    switch (domain) {
+        case "packages":
+            return snapshot.packages;
+        case "files":
+            return snapshot.files;
+        case "symbols":
+            return snapshot.symbols;
+        case "publicApis":
+            return snapshot.publicApis;
+        case "tests":
+            return snapshot.tests;
+        case "examples":
+            return snapshot.examples;
+        case "capabilities":
+            return snapshot.capabilities;
+        case "relationships":
+            return snapshot.relationships;
+        case "diagnostics":
+            return snapshot.diagnostics;
+    }
+}
+/** Same-ID facet projection for a modified pair. Identity fields are not compared here. */
+export function projectFacets(domain, base, head) {
+    const facets = [];
+    switch (domain) {
+        case "symbols":
+            pushUnavailable(facets, "signature_changed", base.signatureFingerprint, head.signatureFingerprint);
+            if (base.signatureFingerprint != null &&
+                head.signatureFingerprint != null &&
+                base.signatureFingerprint === head.signatureFingerprint) {
+                pushUnavailable(facets, "implementation_changed", base.implementationFingerprint, head.implementationFingerprint);
+            }
+            else if (base.signatureFingerprint != null &&
+                head.signatureFingerprint != null &&
+                base.signatureFingerprint !== head.signatureFingerprint) {
+                pushUnavailable(facets, "implementation_changed", base.implementationFingerprint, head.implementationFingerprint);
+            }
+            pushFacet(facets, "documentation_changed", base.doc ?? null, head.doc ?? null);
+            // module/file path may change without identity change only when identity excludes path;
+            // for same-ID symbols, path is typically identity — still allow modulePath facet when present as non-identity display
+            pushFacet(facets, "module_path_changed", base.modulePath ?? null, head.modulePath ?? null);
+            pushFacet(facets, "file_path_changed", base.filePath ?? null, head.filePath ?? null);
+            // Raw source ranges are display/evidence only — never semantic location_changed
+            pushFacet(facets, "visibility_changed", base.visibility ?? null, head.visibility ?? null);
+            pushFacet(facets, "export_status_changed", base.exported ?? null, head.exported ?? null);
+            pushFacet(facets, "canonical_target_changed", base.canonicalSymbolId ?? null, head.canonicalSymbolId ?? null);
+            pushFacet(facets, "capability_links_changed", sortedUnique(base.capabilities), sortedUnique(head.capabilities));
+            break;
+        case "publicApis":
+            pushFacet(facets, "implementation_target_changed", base.symbolId ?? null, head.symbolId ?? null);
+            pushFacet(facets, "documentation_changed", base.intendedUse ?? null, head.intendedUse ?? null);
+            pushFacet(facets, "stability_changed", base.stability ?? null, head.stability ?? null);
+            pushFacet(facets, "contracts_changed", sortedUnique(base.contracts), sortedUnique(head.contracts));
+            pushFacet(facets, "errors_changed", sortedUnique(base.errors), sortedUnique(head.errors));
+            pushFacet(facets, "capability_links_changed", sortedUnique(base.capabilityIds), sortedUnique(head.capabilityIds));
+            pushFacet(facets, "example_links_changed", sortedUnique(base.examples), sortedUnique(head.examples));
+            pushFacet(facets, "test_links_changed", sortedUnique(base.tests), sortedUnique(head.tests));
+            pushUnavailable(facets, "signature_changed", base.signature ?? null, head.signature ?? null);
+            break;
+        case "packages":
+            pushFacet(facets, "public_apis_changed", sortedUnique(base.publicApis), sortedUnique(head.publicApis));
+            pushFacet(facets, "tests_changed", sortedUnique(base.tests), sortedUnique(head.tests));
+            pushFacet(facets, "capabilities_changed", sortedUnique(base.capabilities), sortedUnique(head.capabilities));
+            pushFacet(facets, "entrypoints_changed", base.entrypoints ?? null, head.entrypoints ?? null);
+            pushFacet(facets, "console_scripts_changed", normalizeConsoleScripts(base.consoleScripts), normalizeConsoleScripts(head.consoleScripts));
+            pushFacet(facets, "import_packages_changed", sortedUnique(base.importPackages), sortedUnique(head.importPackages));
+            break;
+        case "files":
+            pushFacet(facets, "content_fingerprint_changed", base.hash ?? null, head.hash ?? null);
+            pushFacet(facets, "public_surface_changed", sortedUnique(base.publicApis), sortedUnique(head.publicApis));
+            break;
+        case "relationships":
+            pushFacet(facets, "evidence_changed", semanticRelationshipEvidence(base.evidence ?? base.evidenceRanges ?? null), semanticRelationshipEvidence(head.evidence ?? head.evidenceRanges ?? null));
+            pushFacet(facets, "confidence_changed", base.confidence ?? null, head.confidence ?? null);
+            pushFacet(facets, "local_discriminant_changed", base.localDiscriminant ?? null, head.localDiscriminant ?? null);
+            break;
+        case "diagnostics":
+            pushFacet(facets, "severity_changed", base.severity ?? null, head.severity ?? null);
+            pushFacet(facets, "documentation_changed", base.message ?? null, head.message ?? null);
+            break;
+        case "tests":
+            pushFacet(facets, "test_links_changed", sortedUnique(base.coversPublicApis), sortedUnique(head.coversPublicApis));
+            pushFacet(facets, "capability_links_changed", sortedUnique(base.coversCapabilities), sortedUnique(head.coversCapabilities));
+            break;
+        case "examples":
+            pushFacet(facets, "example_links_changed", sortedUnique(base.publicApiIds), sortedUnique(head.publicApiIds));
+            pushFacet(facets, "documentation_changed", base.summary ?? null, head.summary ?? null);
+            break;
+        case "capabilities":
+            pushFacet(facets, "public_apis_changed", sortedUnique(base.publicApis), sortedUnique(head.publicApis));
+            pushFacet(facets, "documentation_changed", base.summary ?? null, head.summary ?? null);
+            break;
+    }
+    return facets;
+}
+export function normalizeConsoleScripts(value) {
+    if (!Array.isArray(value))
+        return [];
+    return value
+        .map((item) => {
+        if (!item || typeof item !== "object")
+            return null;
+        const rec = item;
+        const name = String(rec.name ?? "");
+        const target = String(rec.target ?? "");
+        if (!name)
+            return null;
+        return { name, target };
+    })
+        .filter((x) => x != null)
+        .sort((a, b) => a.name.localeCompare(b.name) || a.target.localeCompare(b.target));
+}
+export function displayFields(domain, record) {
+    return {
+        packageId: record.packageId ?? null,
+        importPath: record.importPath ?? null,
+        modulePath: record.modulePath ?? record.path ?? null,
+        qualifiedName: record.qualifiedName ?? null,
+        name: record.name ?? null
+    };
+}

package/dist/comparison/relationshipPolicy.d.ts

@@ -0,0 +1,19 @@
+import type { RelationshipType } from "../catalogue/schema.js";
+/**
+ * Relationship direction policy for impact analysis.
+ * Dependant-impact follows the reverse of the dependency direction:
+ * changed dependency/API → find consumers (dependants).
+ */
+export interface RelationshipImpactPolicy {
+    type: RelationshipType | string;
+    /** Endpoint that owns/provides the dependency (semantic target of consumption). */
+    dependencyEndpoint: "from" | "to";
+    /** Endpoint that depends on / consumes the other. */
+    dependantEndpoint: "from" | "to";
+    participatesInImpact: boolean;
+    /** When true, impact BFS walks from changed node toward dependants. */
+    reverseTraversalForImpact: boolean;
+}
+export declare function getRelationshipImpactPolicy(type: string): RelationshipImpactPolicy;
+/** Normalize catalogue relationship endpoint kinds to graph-index kinds. */
+export declare function normalizeEndpointKind(kind: string): string;

package/dist/comparison/relationshipPolicy.js

@@ -0,0 +1,98 @@
+const POLICY = {
+    imports: {
+        type: "imports",
+        dependencyEndpoint: "to",
+        dependantEndpoint: "from",
+        participatesInImpact: true,
+        reverseTraversalForImpact: true
+    },
+    exports: {
+        type: "exports",
+        dependencyEndpoint: "to",
+        dependantEndpoint: "from",
+        participatesInImpact: true,
+        reverseTraversalForImpact: true
+    },
+    tests: {
+        type: "tests",
+        dependencyEndpoint: "to",
+        dependantEndpoint: "from",
+        participatesInImpact: true,
+        reverseTraversalForImpact: true
+    },
+    covers: {
+        type: "covers",
+        dependencyEndpoint: "to",
+        dependantEndpoint: "from",
+        participatesInImpact: true,
+        reverseTraversalForImpact: true
+    },
+    explicit_coverage: {
+        type: "explicit_coverage",
+        dependencyEndpoint: "to",
+        dependantEndpoint: "from",
+        participatesInImpact: true,
+        reverseTraversalForImpact: true
+    },
+    explicit_example: {
+        type: "explicit_example",
+        dependencyEndpoint: "to",
+        dependantEndpoint: "from",
+        participatesInImpact: true,
+        reverseTraversalForImpact: true
+    },
+    resolved_direct_import: {
+        type: "resolved_direct_import",
+        dependencyEndpoint: "to",
+        dependantEndpoint: "from",
+        participatesInImpact: true,
+        reverseTraversalForImpact: true
+    },
+    resolved_direct_usage: {
+        type: "resolved_direct_usage",
+        dependencyEndpoint: "to",
+        dependantEndpoint: "from",
+        participatesInImpact: true,
+        reverseTraversalForImpact: true
+    },
+    defines: {
+        type: "defines",
+        dependencyEndpoint: "to",
+        dependantEndpoint: "from",
+        participatesInImpact: false,
+        reverseTraversalForImpact: false
+    },
+    contains: {
+        type: "contains",
+        dependencyEndpoint: "to",
+        dependantEndpoint: "from",
+        participatesInImpact: false,
+        reverseTraversalForImpact: false
+    },
+    documents: {
+        type: "documents",
+        dependencyEndpoint: "to",
+        dependantEndpoint: "from",
+        participatesInImpact: true,
+        reverseTraversalForImpact: true
+    }
+};
+export function getRelationshipImpactPolicy(type) {
+    return (POLICY[type] ?? {
+        type,
+        dependencyEndpoint: "to",
+        dependantEndpoint: "from",
+        participatesInImpact: false,
+        reverseTraversalForImpact: false
+    });
+}
+/** Normalize catalogue relationship endpoint kinds to graph-index kinds. */
+export function normalizeEndpointKind(kind) {
+    const map = {
+        publicApi: "public-api",
+        "public-api": "public-api",
+        externalPackage: "external-package",
+        "external-package": "external-package"
+    };
+    return map[kind] ?? kind;
+}

package/dist/comparison/schema.d.ts

@@ -0,0 +1,178 @@
+/** Comparison contract types (comparisonSchemaVersion 1). */
+export type RecordDomain = "packages" | "files" | "symbols" | "publicApis" | "tests" | "examples" | "capabilities" | "relationships" | "diagnostics";
+export type FactualChangeKind = "added" | "removed" | "unchanged" | "modified";
+export type CompatibilityClassification = "breaking" | "potentially_breaking" | "non_breaking" | "documentation_only" | "unknown" | "not_applicable";
+export type ConfidenceCategory = "high" | "medium" | "low" | "ambiguous";
+export type ImpactEvidenceLevel = "direct_evidence" | "transitive_inference" | "possible_impact";
+export type DriftStatus = "no_drift" | "non_public_drift" | "public_surface_drift" | "breaking_public_drift" | "unknown";
+export type RegenerationRecommendation = "none" | "catalogue_regeneration_recommended" | "catalogue_regeneration_required";
+export type ComparisonErrorCode = "comparison_base_not_found" | "comparison_head_not_found" | "comparison_catalogue_invalid" | "comparison_schema_unsupported" | "comparison_identity_scheme_unsupported" | "comparison_identity_scheme_mismatch" | "comparison_identity_mismatch" | "comparison_referential_integrity_failed" | "comparison_artifact_invalid" | "comparison_lock_mismatch" | "comparison_path_rejected" | "comparison_artifact_too_large";
+export interface ComparisonError {
+    code: ComparisonErrorCode;
+    message: string;
+    details?: unknown;
+}
+export interface ComparisonOptions {
+    enabledDomains: RecordDomain[];
+    normalizationPolicyId: string;
+    includeUnchanged: boolean;
+}
+export declare const DEFAULT_COMPARISON_OPTIONS: ComparisonOptions;
+export interface FacetDiff {
+    facet: string;
+    oldValue: unknown;
+    newValue: unknown;
+    evidenceUnavailable?: boolean;
+}
+export interface ChangeRecord {
+    id: string;
+    domain: RecordDomain;
+    status: FactualChangeKind;
+    baseRecordId: string | null;
+    headRecordId: string | null;
+    /** Discriminator used when encoding change identity; null for plain factual changes. */
+    identityDiscriminator?: string | null;
+    packageId?: string | null;
+    importPath?: string | null;
+    modulePath?: string | null;
+    qualifiedName?: string | null;
+    name?: string | null;
+    facets: FacetDiff[];
+}
+export interface CompatibilityFinding {
+    id: string;
+    classification: CompatibilityClassification;
+    ruleId: string;
+    ruleVersion: string;
+    language: string;
+    publicApiId?: string | null;
+    changeId?: string | null;
+    /** Exact identity inputs used when encoding the finding ID. */
+    identityBaseRecordId?: string | null;
+    identityHeadRecordId?: string | null;
+    identityDiscriminator?: string | null;
+    changedFacets: string[];
+    evidence: string[];
+    limitations: string[];
+    confidence: ConfidenceCategory;
+}
+export interface TransitionCandidate {
+    id: string;
+    candidateKind: "probable_move" | "probable_rename" | "probable_move_and_rename" | "possible_replacement" | "ambiguous_candidate" | "public_surface_transition";
+    domain: RecordDomain;
+    baseRecordId: string;
+    headRecordId: string;
+    /** Discriminator used when encoding candidate identity. */
+    identityDiscriminator?: string | null;
+    confidence: ConfidenceCategory;
+    evidenceReasons: string[];
+    conflictingEvidence: string[];
+    alternativeCandidateIds: string[];
+    ambiguity: boolean;
+    transitionFacets: string[];
+}
+export interface ImpactPathEdge {
+    snapshot: "base" | "head";
+    relationshipType: string;
+    fromKind: string;
+    fromId: string;
+    toKind: string;
+    toId: string;
+    provenance?: string;
+    evidenceLevel: ImpactEvidenceLevel;
+}
+export interface ImpactSection {
+    total: number;
+    returned: number;
+    offset: number;
+    limit: number;
+    truncated: boolean;
+    /** Present when work budget prevented a complete enumeration. */
+    totalIsLowerBound?: boolean;
+    traversalIncomplete?: boolean;
+    records: Array<{
+        id: string;
+        kind: string;
+        packageId?: string | null;
+        qualifiedName?: string | null;
+        pathLength: number;
+        evidenceLevel: ImpactEvidenceLevel;
+        path: ImpactPathEdge[];
+    }>;
+}
+export interface ChangeImpactResult {
+    changeId: string;
+    baseImpact: ImpactSection;
+    headImpact: ImpactSection;
+    retainedImpact: ImpactSection;
+    removedImpact: ImpactSection;
+    addedImpact: ImpactSection;
+    possibleImpact: ImpactSection;
+}
+export interface DomainUnchangedCounts {
+    packages: number;
+    files: number;
+    symbols: number;
+    publicApis: number;
+    tests: number;
+    examples: number;
+    capabilities: number;
+    relationships: number;
+    diagnostics: number;
+}
+export interface ComparisonManifest {
+    comparisonSchemaVersion: number;
+    changeContractVersion: string;
+    compatibilityRuleVersion: string;
+    comparisonIdentityScheme: string;
+    comparisonProjectionVersion: string;
+    candidateDetectionPolicyVersion: string;
+    comparisonId: string;
+    baseCatalogueId: string;
+    headCatalogueId: string;
+    baseGeneratorVersion: string | null;
+    headGeneratorVersion: string | null;
+    comparisonGeneratorVersion: string;
+    options: ComparisonOptions;
+    counts: {
+        added: number;
+        removed: number;
+        modified: number;
+        unchanged: DomainUnchangedCounts;
+        compatibilityFindings: number;
+        candidates: number;
+    };
+    aggregateCompatibility: CompatibilityClassification | null;
+}
+export interface ComparisonSnapshot {
+    manifest: ComparisonManifest;
+    changes: ChangeRecord[];
+    compatibilityFindings: CompatibilityFinding[];
+    candidates: TransitionCandidate[];
+    /** Minimal relationship indexes for Model A source-free impact. */
+    graphIndex: {
+        base: Array<{
+            id?: string;
+            type: string;
+            fromKind: string;
+            fromId: string;
+            toKind: string;
+            toId: string;
+            provenance?: string;
+            localDiscriminant?: string | null;
+            confidence?: number;
+        }>;
+        head: Array<{
+            id?: string;
+            type: string;
+            fromKind: string;
+            fromId: string;
+            toKind: string;
+            toId: string;
+            provenance?: string;
+            localDiscriminant?: string | null;
+            confidence?: number;
+        }>;
+    };
+    warnings?: string[];
+}

package/dist/comparison/schema.js

@@ -0,0 +1,16 @@
+/** Comparison contract types (comparisonSchemaVersion 1). */
+export const DEFAULT_COMPARISON_OPTIONS = {
+    enabledDomains: [
+        "packages",
+        "files",
+        "symbols",
+        "publicApis",
+        "tests",
+        "examples",
+        "capabilities",
+        "relationships",
+        "diagnostics"
+    ],
+    normalizationPolicyId: "default-v1",
+    includeUnchanged: false
+};

package/dist/comparison/store.d.ts

@@ -0,0 +1,58 @@
+import type { ComparisonError, ComparisonSnapshot } from "./schema.js";
+export declare const COMPARISON_OUTPUT_FILES: {
+    readonly comparison: "comparison.json";
+    readonly changes: "changes.json";
+    readonly compatibility: "compatibility.json";
+    readonly impactSummary: "impact-summary.json";
+    readonly graphIndex: "graph-index.json";
+    readonly lock: "comparison.lock.json";
+};
+export declare const ALLOWED_ARTEFACT_FILENAMES: Set<string>;
+export declare const MAX_ARTEFACT_FILE_BYTES: number;
+export declare const MAX_ARTEFACT_TOTAL_BYTES: number;
+export declare const MAX_CHANGE_RECORDS = 500000;
+export declare const MAX_COMPAT_FINDINGS = 200000;
+export declare const MAX_CANDIDATES = 100000;
+export declare const MAX_GRAPH_EDGES = 1000000;
+export interface ArtefactFs {
+    mkdirSync(dir: string, opts?: {
+        recursive?: boolean;
+    }): void;
+    writeFileSync(filePath: string, content: string): void;
+    existsSync(target: string): boolean;
+    renameSync(from: string, to: string): void;
+    rmSync(target: string, opts?: {
+        recursive?: boolean;
+        force?: boolean;
+    }): void;
+}
+export declare const defaultArtefactFs: ArtefactFs;
+export declare function assertComparisonPathContained(workspaceRoot: string, relativeOrAbsolute: string): ComparisonError | null;
+/**
+ * Transactional / rollback-safe directory replacement.
+ * Not claimed as single-syscall filesystem-atomic across platforms.
+ */
+export declare function replaceDirectoryTransactionally(outputRoot: string, tmpRoot: string, fsImpl?: ArtefactFs): {
+    ok: true;
+    cleanupWarning?: string;
+} | {
+    ok: false;
+    error: ComparisonError;
+};
+export declare function writeComparisonArtefact(outputRoot: string, comparison: ComparisonSnapshot, pretty?: boolean, fsImpl?: ArtefactFs): {
+    ok: true;
+    cleanupWarning?: string;
+} | {
+    ok: false;
+    error: ComparisonError;
+};
+export type LoadComparisonResult = {
+    ok: true;
+    comparison: ComparisonSnapshot;
+} | {
+    ok: false;
+    error: ComparisonError;
+};
+export declare function loadComparisonArtefact(outputRoot: string): LoadComparisonResult;
+export declare function removeComparisonArtefact(outputRoot: string): void;
+export declare function listArtefactFiles(outputRoot: string): string[];