@mortice/mapwright 0.8.0

package/dist/comparison/compatibility.js

@@ -0,0 +1,316 @@
+import { changeIdentityId } from "./identity.js";
+import { orderCompatibilityFindings, aggregateCompatibility } from "./ordering.js";
+import { normalizeConsoleScripts } from "./projections.js";
+import { COMPATIBILITY_RULE_VERSION } from "./version.js";
+import { attachFindingIdentity } from "./artefactValidate.js";
+function findingId(comparisonId, ruleId, publicApiId, changeId) {
+    return changeIdentityId({
+        comparisonId,
+        domain: "publicApis",
+        baseRecordId: publicApiId,
+        headRecordId: changeId,
+        factualChangeKind: "modified",
+        discriminator: `compat:${ruleId}`
+    });
+}
+function pushFinding(findings, finding, identityBaseRecordId, identityHeadRecordId) {
+    findings.push(attachFindingIdentity(finding, identityBaseRecordId, identityHeadRecordId));
+}
+/**
+ * Versioned stability transition matrix (compatibilityRuleVersion 1 corrective).
+ */
+export function classifyStabilityTransition(from, to) {
+    if (from == null || to == null || from === to)
+        return null;
+    const key = `${from}->${to}`;
+    const matrix = {
+        "stable->deprecated": { classification: "potentially_breaking", ruleId: "stability-stable-to-deprecated" },
+        "stable->internal": { classification: "breaking", ruleId: "stability-stable-to-internal" },
+        "stable->experimental": { classification: "potentially_breaking", ruleId: "stability-stable-to-experimental" },
+        "experimental->stable": { classification: "non_breaking", ruleId: "stability-experimental-to-stable" },
+        "deprecated->stable": { classification: "non_breaking", ruleId: "stability-deprecated-to-stable" },
+        "deprecated->internal": { classification: "breaking", ruleId: "stability-deprecated-to-internal" },
+        "experimental->deprecated": { classification: "potentially_breaking", ruleId: "stability-experimental-to-deprecated" },
+        "experimental->internal": { classification: "breaking", ruleId: "stability-experimental-to-internal" },
+        "internal->stable": { classification: "non_breaking", ruleId: "stability-internal-to-stable" },
+        "internal->experimental": { classification: "non_breaking", ruleId: "stability-internal-to-experimental" }
+    };
+    return (matrix[key] ?? {
+        classification: "potentially_breaking",
+        ruleId: "stability-transition-unknown-policy"
+    });
+}
+function analyzeConsoleScripts(comparisonId, change, collisions) {
+    const oldScripts = normalizeConsoleScripts(change.facets.find((f) => f.facet === "console_scripts_changed")?.oldValue);
+    const newScripts = normalizeConsoleScripts(change.facets.find((f) => f.facet === "console_scripts_changed")?.newValue);
+    if (!change.facets.some((f) => f.facet === "console_scripts_changed"))
+        return [];
+    const oldMap = new Map(oldScripts.map((s) => [s.name, s.target]));
+    const newMap = new Map(newScripts.map((s) => [s.name, s.target]));
+    const findings = [];
+    for (const [name, target] of oldMap) {
+        if (!newMap.has(name)) {
+            const id = findingId(comparisonId, "python-console-script-removed", change.baseRecordId, change.id);
+            collisions.register(id, `${comparisonId}|console-removed|${name}`);
+            findings.push({
+                id,
+                classification: "breaking",
+                ruleId: "python-console-script-removed",
+                ruleVersion: COMPATIBILITY_RULE_VERSION,
+                language: "python",
+                publicApiId: null,
+                changeId: change.id,
+                changedFacets: ["console_scripts_changed"],
+                evidence: [`Console script "${name}" removed (was ${target}).`],
+                limitations: [],
+                confidence: "high"
+            });
+        }
+        else if (newMap.get(name) !== target) {
+            const id = findingId(comparisonId, "python-console-script-target-changed", change.baseRecordId, change.id);
+            collisions.register(id, `${comparisonId}|console-target|${name}`);
+            findings.push({
+                id,
+                classification: "potentially_breaking",
+                ruleId: "python-console-script-target-changed",
+                ruleVersion: COMPATIBILITY_RULE_VERSION,
+                language: "python",
+                publicApiId: null,
+                changeId: change.id,
+                changedFacets: ["console_scripts_changed"],
+                evidence: [`Console script "${name}" target changed from ${target} to ${newMap.get(name)}.`],
+                limitations: ["Cannot prove consumer command compatibility without runtime analysis."],
+                confidence: "medium"
+            });
+        }
+    }
+    for (const [name, target] of newMap) {
+        if (!oldMap.has(name)) {
+            // detect rename: same target, different name
+            const renamedFrom = [...oldMap.entries()].find(([oldName, oldTarget]) => oldTarget === target && !newMap.has(oldName));
+            if (renamedFrom) {
+                const id = findingId(comparisonId, "python-console-script-renamed", change.baseRecordId, change.id);
+                collisions.register(id, `${comparisonId}|console-renamed|${name}`);
+                findings.push({
+                    id,
+                    classification: "breaking",
+                    ruleId: "python-console-script-renamed",
+                    ruleVersion: COMPATIBILITY_RULE_VERSION,
+                    language: "python",
+                    publicApiId: null,
+                    changeId: change.id,
+                    changedFacets: ["console_scripts_changed"],
+                    evidence: [`Console script renamed from "${renamedFrom[0]}" to "${name}" (target ${target}).`],
+                    limitations: [],
+                    confidence: "high"
+                });
+            }
+            else {
+                const id = findingId(comparisonId, "python-console-script-added", change.baseRecordId, change.id);
+                collisions.register(id, `${comparisonId}|console-added|${name}`);
+                findings.push({
+                    id,
+                    classification: "non_breaking",
+                    ruleId: "python-console-script-added",
+                    ruleVersion: COMPATIBILITY_RULE_VERSION,
+                    language: "python",
+                    publicApiId: null,
+                    changeId: change.id,
+                    changedFacets: ["console_scripts_changed"],
+                    evidence: [`Console script "${name}" added (target ${target}).`],
+                    limitations: [],
+                    confidence: "high"
+                });
+            }
+        }
+    }
+    // order-only / identical maps should not reach here as a facet; if empty delta, documentation_only
+    if (findings.length === 0) {
+        const id = findingId(comparisonId, "python-console-script-metadata", change.baseRecordId, change.id);
+        collisions.register(id, `${comparisonId}|console-meta|${change.baseRecordId}`);
+        findings.push({
+            id,
+            classification: "documentation_only",
+            ruleId: "python-console-script-metadata",
+            ruleVersion: COMPATIBILITY_RULE_VERSION,
+            language: "python",
+            publicApiId: null,
+            changeId: change.id,
+            changedFacets: ["console_scripts_changed"],
+            evidence: ["Console script metadata ordering or representation changed without command/target delta."],
+            limitations: [],
+            confidence: "medium"
+        });
+    }
+    return findings;
+}
+/**
+ * Conservative public API compatibility analysis (rule version 1).
+ */
+export function analyzePublicApiCompatibility(input) {
+    const findings = [];
+    const publicChanges = input.changes.filter((c) => c.domain === "publicApis");
+    for (const change of publicChanges) {
+        if (change.status === "removed") {
+            const id = findingId(input.comparisonId, "public-export-removed", change.baseRecordId, change.id);
+            input.collisions.register(id, `${input.comparisonId}|public-export-removed|${change.baseRecordId}`);
+            findings.push({
+                id,
+                classification: "breaking",
+                ruleId: "public-export-removed",
+                ruleVersion: COMPATIBILITY_RULE_VERSION,
+                language: "any",
+                publicApiId: change.baseRecordId,
+                changeId: change.id,
+                changedFacets: [],
+                evidence: ["Public API record absent in head catalogue."],
+                limitations: [],
+                confidence: "high"
+            });
+            continue;
+        }
+        if (change.status === "added") {
+            const id = findingId(input.comparisonId, "public-export-added", change.headRecordId, change.id);
+            input.collisions.register(id, `${input.comparisonId}|public-export-added|${change.headRecordId}`);
+            findings.push({
+                id,
+                classification: "non_breaking",
+                ruleId: "public-export-added",
+                ruleVersion: COMPATIBILITY_RULE_VERSION,
+                language: "any",
+                publicApiId: change.headRecordId,
+                changeId: change.id,
+                changedFacets: [],
+                evidence: ["Public API record present only in head catalogue."],
+                limitations: [],
+                confidence: "high"
+            });
+            continue;
+        }
+        if (change.status === "modified") {
+            const facetNames = change.facets.map((f) => f.facet);
+            const stabilityFacet = change.facets.find((f) => f.facet === "stability_changed");
+            if (stabilityFacet) {
+                const transition = classifyStabilityTransition(stabilityFacet.oldValue, stabilityFacet.newValue);
+                if (transition) {
+                    const id = findingId(input.comparisonId, transition.ruleId, change.baseRecordId, change.id);
+                    input.collisions.register(id, `${input.comparisonId}|${transition.ruleId}|${change.baseRecordId}`);
+                    findings.push({
+                        id,
+                        classification: transition.classification,
+                        ruleId: transition.ruleId,
+                        ruleVersion: COMPATIBILITY_RULE_VERSION,
+                        language: "any",
+                        publicApiId: change.baseRecordId,
+                        changeId: change.id,
+                        changedFacets: ["stability_changed"],
+                        evidence: [`Stability changed from ${String(stabilityFacet.oldValue)} to ${String(stabilityFacet.newValue)}.`],
+                        limitations: [],
+                        confidence: "high"
+                    });
+                }
+            }
+            const docsOnly = facetNames.length > 0 &&
+                facetNames.every((f) => f === "documentation_changed") &&
+                !stabilityFacet;
+            const implOnly = facetNames.includes("implementation_target_changed") &&
+                !facetNames.includes("signature_changed") &&
+                !facetNames.some((f) => f.endsWith("path_changed") || f.includes("export"));
+            if (docsOnly) {
+                const id = findingId(input.comparisonId, "documentation-only", change.baseRecordId, change.id);
+                input.collisions.register(id, `${input.comparisonId}|documentation-only|${change.baseRecordId}`);
+                findings.push({
+                    id,
+                    classification: "documentation_only",
+                    ruleId: "documentation-only",
+                    ruleVersion: COMPATIBILITY_RULE_VERSION,
+                    language: "any",
+                    publicApiId: change.baseRecordId,
+                    changeId: change.id,
+                    changedFacets: facetNames,
+                    evidence: facetNames.map((f) => `Facet ${f} differed between base and head.`),
+                    limitations: [],
+                    confidence: "high"
+                });
+            }
+            else if (implOnly) {
+                const id = findingId(input.comparisonId, "implementation-target-stable-export", change.baseRecordId, change.id);
+                input.collisions.register(id, `${input.comparisonId}|impl-target|${change.baseRecordId}`);
+                findings.push({
+                    id,
+                    classification: "non_breaking",
+                    ruleId: "implementation-target-stable-export",
+                    ruleVersion: COMPATIBILITY_RULE_VERSION,
+                    language: "any",
+                    publicApiId: change.baseRecordId,
+                    changeId: change.id,
+                    changedFacets: facetNames,
+                    evidence: facetNames.map((f) => `Facet ${f} differed between base and head.`),
+                    limitations: ["Assumes consumer contract identity unchanged; signature structure not fully modelled."],
+                    confidence: "medium"
+                });
+            }
+            else if (facetNames.includes("signature_changed")) {
+                const id = findingId(input.comparisonId, "signature-fingerprint-or-display-changed", change.baseRecordId, change.id);
+                input.collisions.register(id, `${input.comparisonId}|sig|${change.baseRecordId}`);
+                findings.push({
+                    id,
+                    classification: "potentially_breaking",
+                    ruleId: "signature-fingerprint-or-display-changed",
+                    ruleVersion: COMPATIBILITY_RULE_VERSION,
+                    language: "any",
+                    publicApiId: change.baseRecordId,
+                    changeId: change.id,
+                    changedFacets: facetNames,
+                    evidence: facetNames.map((f) => `Facet ${f} differed between base and head.`),
+                    limitations: ["Schema 2 lacks structured parameter/type models; cannot prove assignability."],
+                    confidence: "low"
+                });
+            }
+            else if (!stabilityFacet && facetNames.length > 0) {
+                const id = findingId(input.comparisonId, "public-api-modified-unknown", change.baseRecordId, change.id);
+                input.collisions.register(id, `${input.comparisonId}|unknown-mod|${change.baseRecordId}`);
+                findings.push({
+                    id,
+                    classification: "unknown",
+                    ruleId: "public-api-modified-unknown",
+                    ruleVersion: COMPATIBILITY_RULE_VERSION,
+                    language: "any",
+                    publicApiId: change.baseRecordId,
+                    changeId: change.id,
+                    changedFacets: facetNames,
+                    evidence: facetNames.map((f) => `Facet ${f} differed between base and head.`),
+                    limitations: [],
+                    confidence: "medium"
+                });
+            }
+        }
+    }
+    for (const candidate of input.candidates) {
+        if (candidate.domain !== "publicApis")
+            continue;
+        const id = findingId(input.comparisonId, "public-surface-transition", candidate.baseRecordId, candidate.headRecordId);
+        input.collisions.register(id, `${input.comparisonId}|public-surface-transition|${candidate.id}`);
+        pushFinding(findings, {
+            id,
+            classification: candidate.ambiguity ? "potentially_breaking" : "breaking",
+            ruleId: "public-surface-transition",
+            ruleVersion: COMPATIBILITY_RULE_VERSION,
+            language: "any",
+            publicApiId: candidate.baseRecordId,
+            changeId: null,
+            changedFacets: candidate.transitionFacets,
+            evidence: candidate.evidenceReasons,
+            limitations: candidate.conflictingEvidence,
+            confidence: candidate.confidence
+        }, candidate.baseRecordId, candidate.headRecordId);
+    }
+    for (const change of input.changes.filter((c) => c.domain === "packages" && c.status === "modified")) {
+        findings.push(...analyzeConsoleScripts(input.comparisonId, change, input.collisions));
+    }
+    const withIdentity = findings.map((f) => f.identityDiscriminator
+        ? f
+        : attachFindingIdentity(f, f.publicApiId ?? null, f.changeId ?? null));
+    const ordered = orderCompatibilityFindings(withIdentity);
+    return { findings: ordered, aggregate: aggregateCompatibility(ordered) };
+}

package/dist/comparison/drift.d.ts

@@ -0,0 +1,34 @@
+import type { DriftStatus, RegenerationRecommendation } from "../comparison/schema.js";
+/**
+ * Explicit read-only drift detection: load committed catalogue, index workspace in memory, compare.
+ * Does not write catalogues or comparison artefacts.
+ * Does not execute Git or other VCS tools.
+ */
+export declare function checkCatalogueDrift(input: {
+    workspaceRoot: string;
+    catalogueDir?: string;
+    configPath?: string;
+}): {
+    ok: true;
+    data: {
+        driftStatus: DriftStatus;
+        driftClass: DriftStatus;
+        regenerationRecommendation: RegenerationRecommendation;
+        baseCatalogueId: string;
+        headCatalogueId: string;
+        counts: {
+            added: number;
+            removed: number;
+            modified: number;
+        };
+        aggregateCompatibility: string | null;
+        wroteFiles: false;
+        indexedInMemory: true;
+    };
+} | {
+    ok: false;
+    error: {
+        code: string;
+        message: string;
+    };
+};

package/dist/comparison/drift.js

@@ -0,0 +1,71 @@
+import path from "node:path";
+import { indexWorkspace } from "../catalogue/indexer.js";
+import { loadCommittedCatalogue } from "../catalogue/store.js";
+import { compareCatalogues } from "../comparison/compare.js";
+/**
+ * Explicit read-only drift detection: load committed catalogue, index workspace in memory, compare.
+ * Does not write catalogues or comparison artefacts.
+ * Does not execute Git or other VCS tools.
+ */
+export function checkCatalogueDrift(input) {
+    const workspaceRoot = path.resolve(input.workspaceRoot);
+    const catalogueDir = input.catalogueDir ?? ".mapwright";
+    const loaded = loadCommittedCatalogue(workspaceRoot, catalogueDir);
+    if (!loaded.ok) {
+        return { ok: false, error: loaded.error };
+    }
+    const { snapshot: head } = indexWorkspace({
+        workspaceRoot,
+        configPath: input.configPath,
+        mode: "memory",
+        write: false
+    });
+    const compared = compareCatalogues(loaded.snapshot, head);
+    if (!compared.ok) {
+        return { ok: false, error: compared.error };
+    }
+    const { counts, aggregateCompatibility } = compared.comparison.manifest;
+    const total = counts.added + counts.removed + counts.modified;
+    const hasPublic = compared.comparison.changes.some((c) => c.domain === "publicApis" && c.status !== "unchanged");
+    let driftClass = "no_drift";
+    if (total === 0) {
+        driftClass = "no_drift";
+    }
+    else if (aggregateCompatibility === "breaking" && hasPublic) {
+        driftClass = "breaking_public_drift";
+    }
+    else if (hasPublic) {
+        driftClass = "public_surface_drift";
+    }
+    else if (total > 0) {
+        driftClass = "non_public_drift";
+    }
+    else {
+        driftClass = "unknown";
+    }
+    let regenerationRecommendation = "none";
+    if (driftClass === "breaking_public_drift") {
+        regenerationRecommendation = "catalogue_regeneration_required";
+    }
+    else if (driftClass === "public_surface_drift" || driftClass === "non_public_drift") {
+        regenerationRecommendation = "catalogue_regeneration_recommended";
+    }
+    return {
+        ok: true,
+        data: {
+            driftStatus: driftClass,
+            driftClass,
+            regenerationRecommendation,
+            baseCatalogueId: loaded.snapshot.catalogueId,
+            headCatalogueId: head.catalogueId,
+            counts: {
+                added: counts.added,
+                removed: counts.removed,
+                modified: counts.modified
+            },
+            aggregateCompatibility,
+            wroteFiles: false,
+            indexedInMemory: true
+        }
+    };
+}

package/dist/comparison/identity.d.ts

@@ -0,0 +1,30 @@
+import type { ComparisonOptions, FactualChangeKind, RecordDomain } from "./schema.js";
+export type ComparisonIdentityField = string | number | boolean | null;
+export declare function normalizeComparisonString(value: string): string;
+export declare function encodeComparisonPreimage(fields: ComparisonIdentityField[]): string;
+export declare function hashComparisonPreimage(preimageJson: string): string;
+export declare function comparisonIdentityId(input: {
+    baseCatalogueId: string;
+    headCatalogueId: string;
+    options: ComparisonOptions;
+}): string;
+export declare function changeIdentityId(input: {
+    comparisonId: string;
+    domain: RecordDomain;
+    baseRecordId: string | null;
+    headRecordId: string | null;
+    factualChangeKind: FactualChangeKind;
+    discriminator?: string | null;
+}): string;
+/** Fail-closed collision tracker for comparison/change IDs. */
+export declare class ComparisonCollisionTracker {
+    private readonly seen;
+    register(id: string, preimage: string): void;
+}
+export declare class ComparisonIdentityCollisionError extends Error {
+    readonly id: string;
+    readonly existingPreimage: string;
+    readonly conflictingPreimage: string;
+    readonly code = "identity_hash_collision";
+    constructor(id: string, existingPreimage: string, conflictingPreimage: string);
+}

package/dist/comparison/identity.js

@@ -0,0 +1,73 @@
+/**
+ * Deterministic comparison and change identity encoder (`comparison-sha256-v1`).
+ */
+import { createHash } from "node:crypto";
+import { COMPARISON_NAMESPACE, CHANGE_NAMESPACE, COMPARISON_IDENTITY_SCHEME, COMPARISON_SCHEMA_VERSION, CHANGE_CONTRACT_VERSION, COMPATIBILITY_RULE_VERSION, COMPARISON_PROJECTION_VERSION, CANDIDATE_DETECTION_POLICY_VERSION } from "./version.js";
+export function normalizeComparisonString(value) {
+    return value.normalize("NFC");
+}
+export function encodeComparisonPreimage(fields) {
+    return JSON.stringify(fields);
+}
+export function hashComparisonPreimage(preimageJson) {
+    return createHash("sha256").update(preimageJson, "utf8").digest("hex");
+}
+export function comparisonIdentityId(input) {
+    const domains = [...input.options.enabledDomains].sort();
+    const fields = [
+        COMPARISON_NAMESPACE,
+        COMPARISON_IDENTITY_SCHEME,
+        COMPARISON_SCHEMA_VERSION,
+        CHANGE_CONTRACT_VERSION,
+        COMPATIBILITY_RULE_VERSION,
+        COMPARISON_PROJECTION_VERSION,
+        CANDIDATE_DETECTION_POLICY_VERSION,
+        normalizeComparisonString(input.baseCatalogueId),
+        normalizeComparisonString(input.headCatalogueId),
+        JSON.stringify(domains),
+        normalizeComparisonString(input.options.normalizationPolicyId),
+        input.options.includeUnchanged
+    ];
+    const digest = hashComparisonPreimage(encodeComparisonPreimage(fields));
+    return `comparison:${digest}`;
+}
+export function changeIdentityId(input) {
+    const fields = [
+        CHANGE_NAMESPACE,
+        COMPARISON_IDENTITY_SCHEME,
+        normalizeComparisonString(input.comparisonId),
+        normalizeComparisonString(input.domain),
+        input.baseRecordId === null ? null : normalizeComparisonString(input.baseRecordId),
+        input.headRecordId === null ? null : normalizeComparisonString(input.headRecordId),
+        normalizeComparisonString(input.factualChangeKind),
+        input.discriminator == null || input.discriminator === ""
+            ? null
+            : normalizeComparisonString(input.discriminator)
+    ];
+    const digest = hashComparisonPreimage(encodeComparisonPreimage(fields));
+    return `change:${digest}`;
+}
+/** Fail-closed collision tracker for comparison/change IDs. */
+export class ComparisonCollisionTracker {
+    seen = new Map();
+    register(id, preimage) {
+        const existing = this.seen.get(id);
+        if (existing !== undefined && existing !== preimage) {
+            throw new ComparisonIdentityCollisionError(id, existing, preimage);
+        }
+        this.seen.set(id, preimage);
+    }
+}
+export class ComparisonIdentityCollisionError extends Error {
+    id;
+    existingPreimage;
+    conflictingPreimage;
+    code = "identity_hash_collision";
+    constructor(id, existingPreimage, conflictingPreimage) {
+        super(`Comparison identity hash collision for ${id}`);
+        this.id = id;
+        this.existingPreimage = existingPreimage;
+        this.conflictingPreimage = conflictingPreimage;
+        this.name = "ComparisonIdentityCollisionError";
+    }
+}

package/dist/comparison/impact.d.ts

@@ -0,0 +1,14 @@
+import type { ChangeImpactResult, ComparisonSnapshot } from "./schema.js";
+export declare const IMPACT_DEFAULT_DEPTH = 3;
+export declare const IMPACT_MAX_DEPTH = 8;
+export declare const IMPACT_DEFAULT_LIMIT = 50;
+export declare const IMPACT_MAX_LIMIT = 200;
+export declare const IMPACT_MAX_VISITED_NODES = 10000;
+export declare const IMPACT_MAX_TRAVERSED_EDGES = 50000;
+export declare const IMPACT_MAX_PATHS_PER_ENDPOINT = 500;
+export type GraphEdge = ComparisonSnapshot["graphIndex"]["base"][number];
+export declare function getChangeImpact(comparison: ComparisonSnapshot, changeId: string, options?: {
+    maxDepth?: number;
+    limit?: number;
+    offset?: number;
+}): ChangeImpactResult | null;