@mortice/mapwright 0.8.0

package/dist/cli/commands/compatibility.js

@@ -0,0 +1,43 @@
+import path from "node:path";
+import { loadComparisonArtefact } from "../../comparison/store.js";
+import { getCompatibilityReport } from "../../queries/changes.js";
+const SEVERITY = {
+    breaking: 0,
+    potentially_breaking: 1,
+    unknown: 2,
+    non_breaking: 3,
+    documentation_only: 4,
+    not_applicable: 5
+};
+export function runCompatibilityCommand(options) {
+    if (!options.comparisonDir) {
+        return {
+            output: { ok: false, error: { code: "usage_error", message: "--comparison-dir is required" } },
+            exitCode: 2
+        };
+    }
+    const loaded = loadComparisonArtefact(path.resolve(options.comparisonDir));
+    if (!loaded.ok) {
+        return { output: { ok: false, error: loaded.error }, exitCode: 3 };
+    }
+    const report = getCompatibilityReport(loaded.comparison, {
+        offset: options.offset,
+        limit: options.limit
+    });
+    const failOn = options.failOn ?? "never";
+    const aggregate = report.aggregate;
+    let exitCode = 0;
+    if (failOn === "breaking" && aggregate === "breaking")
+        exitCode = 1;
+    if (failOn === "potentially-breaking" && aggregate && SEVERITY[aggregate] <= SEVERITY.potentially_breaking) {
+        exitCode = 1;
+    }
+    if (failOn === "unknown" && aggregate && SEVERITY[aggregate] <= SEVERITY.unknown)
+        exitCode = 1;
+    if (failOn === "any-change" || failOn === "any-public-change") {
+        if ((loaded.comparison.manifest.counts.added + loaded.comparison.manifest.counts.removed + loaded.comparison.manifest.counts.modified) > 0) {
+            exitCode = 1;
+        }
+    }
+    return { output: { ok: true, data: report }, exitCode };
+}

package/dist/cli/commands/diff.d.ts

@@ -0,0 +1,31 @@
+export type FailOn = "never" | "unknown" | "potentially-breaking" | "breaking" | "any-public-change" | "any-change";
+export declare function hasPublicFacingChange(input: {
+    changes: Array<{
+        domain: string;
+        status: string;
+    }>;
+    candidates: Array<{
+        domain: string;
+    }>;
+    compatibilityFindings: Array<{
+        ruleId: string;
+        classification: string;
+    }>;
+}): boolean;
+export declare function runDiffCommand(options: {
+    baseWorkspace: string;
+    baseCatalogueDir: string;
+    headWorkspace: string;
+    headCatalogueDir: string;
+    writeDir?: string;
+    failOn?: FailOn;
+}): {
+    output: Record<string, unknown>;
+    exitCode: number;
+};
+export declare function runLoadComparisonCommand(options: {
+    comparisonDir: string;
+}): {
+    output: Record<string, unknown>;
+    exitCode: number;
+};

package/dist/cli/commands/diff.js

@@ -0,0 +1,118 @@
+import path from "node:path";
+import { loadCataloguePair } from "../../comparison/validate.js";
+import { compareCatalogues } from "../../comparison/compare.js";
+import { writeComparisonArtefact, loadComparisonArtefact } from "../../comparison/store.js";
+import { DEFAULT_COMPARISON_OPTIONS } from "../../comparison/schema.js";
+const SEVERITY = {
+    breaking: 0,
+    potentially_breaking: 1,
+    unknown: 2,
+    non_breaking: 3,
+    documentation_only: 4,
+    not_applicable: 5
+};
+export function hasPublicFacingChange(input) {
+    if (input.changes.some((c) => c.domain === "publicApis" && c.status !== "unchanged")) {
+        return true;
+    }
+    if (input.candidates.some((c) => c.domain === "publicApis")) {
+        return true;
+    }
+    if (input.compatibilityFindings.some((f) => f.ruleId.startsWith("public-") ||
+        f.ruleId.startsWith("python-console-script") ||
+        f.ruleId.startsWith("stability-"))) {
+        return true;
+    }
+    if (input.changes.some((c) => c.domain === "packages" &&
+        c.status === "modified" &&
+        input.compatibilityFindings.some((f) => f.ruleId.startsWith("python-console-script")))) {
+        return true;
+    }
+    return false;
+}
+function thresholdReached(failOn, aggregate, counts, publicFacing) {
+    if (failOn === "never")
+        return false;
+    if (failOn === "any-change") {
+        return counts.added + counts.removed + counts.modified > 0;
+    }
+    if (failOn === "any-public-change") {
+        return publicFacing;
+    }
+    if (!aggregate)
+        return false;
+    if (failOn === "breaking")
+        return aggregate === "breaking";
+    if (failOn === "potentially-breaking") {
+        return SEVERITY[aggregate] <= SEVERITY.potentially_breaking;
+    }
+    if (failOn === "unknown") {
+        return SEVERITY[aggregate] <= SEVERITY.unknown;
+    }
+    return false;
+}
+export function runDiffCommand(options) {
+    const pair = loadCataloguePair({
+        baseWorkspaceRoot: path.resolve(options.baseWorkspace),
+        baseCatalogueDir: options.baseCatalogueDir,
+        headWorkspaceRoot: path.resolve(options.headWorkspace),
+        headCatalogueDir: options.headCatalogueDir
+    });
+    if (!pair.ok) {
+        const code = pair.error.code === "comparison_path_rejected" ? 4 : 3;
+        return { output: { ok: false, error: pair.error }, exitCode: code };
+    }
+    const compared = compareCatalogues(pair.base, pair.head, DEFAULT_COMPARISON_OPTIONS);
+    if (!compared.ok) {
+        const code = compared.error.code === "comparison_path_rejected" ? 4 : 3;
+        return { output: { ok: false, error: compared.error }, exitCode: code };
+    }
+    if (options.writeDir) {
+        const written = writeComparisonArtefact(path.resolve(options.writeDir), compared.comparison);
+        if (!written.ok) {
+            return {
+                output: { ok: false, error: written.error },
+                exitCode: written.error.code === "comparison_path_rejected" ? 4 : 3
+            };
+        }
+    }
+    const failOn = options.failOn ?? "never";
+    const publicFacing = hasPublicFacingChange(compared.comparison);
+    const hit = thresholdReached(failOn, compared.comparison.manifest.aggregateCompatibility, compared.comparison.manifest.counts, publicFacing);
+    return {
+        output: {
+            ok: true,
+            data: {
+                comparisonId: compared.comparison.manifest.comparisonId,
+                counts: compared.comparison.manifest.counts,
+                aggregateCompatibility: compared.comparison.manifest.aggregateCompatibility,
+                baseCatalogueId: compared.comparison.manifest.baseCatalogueId,
+                headCatalogueId: compared.comparison.manifest.headCatalogueId,
+                baseGeneratorVersion: compared.comparison.manifest.baseGeneratorVersion,
+                headGeneratorVersion: compared.comparison.manifest.headGeneratorVersion,
+                warnings: compared.comparison.warnings ?? []
+            }
+        },
+        exitCode: hit ? 1 : 0
+    };
+}
+export function runLoadComparisonCommand(options) {
+    const loaded = loadComparisonArtefact(path.resolve(options.comparisonDir));
+    if (!loaded.ok) {
+        return {
+            output: { ok: false, error: loaded.error },
+            exitCode: loaded.error.code === "comparison_path_rejected" ? 4 : 3
+        };
+    }
+    return {
+        output: {
+            ok: true,
+            data: {
+                comparisonId: loaded.comparison.manifest.comparisonId,
+                counts: loaded.comparison.manifest.counts,
+                aggregateCompatibility: loaded.comparison.manifest.aggregateCompatibility
+            }
+        },
+        exitCode: 0
+    };
+}

package/dist/cli/commands/dogfood.d.ts

@@ -0,0 +1,8 @@
+export interface DogfoodCommandOptions {
+    workspace: string;
+    config?: string;
+    mode?: "committed" | "local" | "memory";
+    maxDiagnostics?: number;
+    maxGaps?: number;
+}
+export declare function runDogfoodCommand(options: DogfoodCommandOptions): Record<string, unknown>;

package/dist/cli/commands/dogfood.js

@@ -0,0 +1,24 @@
+import path from "node:path";
+import { indexWorkspace } from "../../catalogue/indexer.js";
+import { getDogfoodReport } from "../../queries/dogfood.js";
+export function runDogfoodCommand(options) {
+    const workspaceRoot = path.resolve(options.workspace);
+    const { snapshot } = indexWorkspace({
+        workspaceRoot,
+        configPath: options.config,
+        mode: options.mode ?? "local",
+        write: false
+    });
+    return {
+        ok: true,
+        data: getDogfoodReport(snapshot, {
+            workspace: workspaceRoot,
+            maxDiagnostics: options.maxDiagnostics,
+            maxGaps: options.maxGaps
+        }),
+        warnings: [],
+        provenance: {
+            source: "mapwright"
+        }
+    };
+}

package/dist/cli/commands/drift.d.ts

@@ -0,0 +1,8 @@
+export declare function runDriftCommand(options: {
+    workspace: string;
+    catalogueDir?: string;
+    config?: string;
+}): {
+    output: Record<string, unknown>;
+    exitCode: number;
+};

package/dist/cli/commands/drift.js

@@ -0,0 +1,13 @@
+import path from "node:path";
+import { checkCatalogueDrift } from "../../comparison/drift.js";
+export function runDriftCommand(options) {
+    const result = checkCatalogueDrift({
+        workspaceRoot: path.resolve(options.workspace),
+        catalogueDir: options.catalogueDir,
+        configPath: options.config
+    });
+    if (!result.ok) {
+        return { output: { ok: false, error: result.error }, exitCode: 3 };
+    }
+    return { output: { ok: true, data: result.data }, exitCode: 0 };
+}

package/dist/cli/commands/index.d.ts

@@ -0,0 +1,9 @@
+export * from "./indexWorkspace.js";
+export * from "./validate.js";
+export * from "./check.js";
+export * from "./schema.js";
+export * from "./auditDocs.js";
+export * from "./adoptionPlan.js";
+export * from "./template.js";
+export * from "./dogfood.js";
+export * from "./recommendConfig.js";

package/dist/cli/commands/index.js

@@ -0,0 +1,9 @@
+export * from "./indexWorkspace.js";
+export * from "./validate.js";
+export * from "./check.js";
+export * from "./schema.js";
+export * from "./auditDocs.js";
+export * from "./adoptionPlan.js";
+export * from "./template.js";
+export * from "./dogfood.js";
+export * from "./recommendConfig.js";

package/dist/cli/commands/indexWorkspace.d.ts

@@ -0,0 +1,8 @@
+export interface IndexCommandOptions {
+    workspace: string;
+    config?: string;
+    mode?: "committed" | "local" | "memory";
+    write?: boolean;
+    pretty?: boolean;
+}
+export declare function runIndexCommand(options: IndexCommandOptions): Record<string, unknown>;

package/dist/cli/commands/indexWorkspace.js

@@ -0,0 +1,23 @@
+import path from "node:path";
+import { indexWorkspace } from "../../catalogue/indexer.js";
+export function runIndexCommand(options) {
+    const workspaceRoot = path.resolve(options.workspace);
+    const { snapshot } = indexWorkspace({
+        workspaceRoot,
+        configPath: options.config,
+        mode: options.mode,
+        write: options.write,
+        pretty: options.pretty
+    });
+    return {
+        ok: true,
+        data: {
+            catalogueId: snapshot.catalogueId,
+            stats: snapshot.stats
+        },
+        warnings: [],
+        provenance: {
+            source: "cli:index"
+        }
+    };
+}

package/dist/cli/commands/recommendConfig.d.ts

@@ -0,0 +1,7 @@
+export interface RecommendConfigCommandOptions {
+    workspace: string;
+    config?: string;
+    mode?: "committed" | "local" | "memory";
+    limit?: number;
+}
+export declare function runRecommendConfigCommand(options: RecommendConfigCommandOptions): Record<string, unknown>;

package/dist/cli/commands/recommendConfig.js

@@ -0,0 +1,20 @@
+import path from "node:path";
+import { indexWorkspace } from "../../catalogue/indexer.js";
+import { recommendConfig } from "../../queries/recommendConfig.js";
+export function runRecommendConfigCommand(options) {
+    const workspaceRoot = path.resolve(options.workspace);
+    const { snapshot } = indexWorkspace({
+        workspaceRoot,
+        configPath: options.config,
+        mode: options.mode ?? "memory",
+        write: false
+    });
+    return {
+        ok: true,
+        data: recommendConfig(snapshot, { limit: options.limit }),
+        warnings: [],
+        provenance: {
+            source: "mapwright"
+        }
+    };
+}

package/dist/cli/commands/schema.d.ts

@@ -0,0 +1 @@
+export declare function runSchemaCommand(): Record<string, unknown>;

package/dist/cli/commands/schema.js

@@ -0,0 +1,37 @@
+import { CURRENT_SCHEMA_VERSION, SUPPORTED_SCHEMA_VERSIONS, SUPPORTED_IDENTITY_SCHEMES } from "../../catalogue/store.js";
+import { IDENTITY_SCHEME } from "../../catalogue/identity.js";
+export function runSchemaCommand() {
+    return {
+        ok: true,
+        data: {
+            schemaVersion: CURRENT_SCHEMA_VERSION,
+            supportedSchemaVersions: [...SUPPORTED_SCHEMA_VERSIONS],
+            identityScheme: IDENTITY_SCHEME,
+            supportedIdentitySchemes: [...SUPPORTED_IDENTITY_SCHEMES],
+            snapshot: {
+                required: [
+                    "schemaVersion",
+                    "identityScheme",
+                    "catalogueId",
+                    "generator",
+                    "mode",
+                    "stats",
+                    "files",
+                    "packages",
+                    "capabilities",
+                    "publicApis",
+                    "examples",
+                    "symbols",
+                    "relationships",
+                    "tests",
+                    "diagnostics",
+                    "provenance"
+                ]
+            }
+        },
+        warnings: [],
+        provenance: {
+            source: "cli:schema"
+        }
+    };
+}

package/dist/cli/commands/template.d.ts

@@ -0,0 +1,5 @@
+export interface TemplateCommandOptions {
+    templateId?: string;
+    list?: boolean;
+}
+export declare function runTemplateCommand(options: TemplateCommandOptions): Record<string, unknown>;

package/dist/cli/commands/template.js

@@ -0,0 +1,44 @@
+import { getDocumentationTemplate, listDocumentationTemplateIds, listDocumentationTemplates } from "../../catalogue/templates.js";
+export function runTemplateCommand(options) {
+    if (options.list) {
+        return {
+            ok: true,
+            data: {
+                templates: listDocumentationTemplates()
+            },
+            warnings: [],
+            provenance: {
+                source: "mapwright"
+            }
+        };
+    }
+    const templateId = options.templateId ?? "";
+    if (!isDocumentationTemplateId(templateId)) {
+        return {
+            ok: false,
+            error: {
+                code: "template_not_found",
+                message: `Unknown template ${templateId}.`
+            },
+            warnings: [],
+            data: {
+                availableTemplateIds: listDocumentationTemplateIds(),
+                templates: listDocumentationTemplates()
+            },
+            provenance: {
+                source: "mapwright"
+            }
+        };
+    }
+    return {
+        ok: true,
+        data: getDocumentationTemplate(templateId),
+        warnings: [],
+        provenance: {
+            source: "mapwright"
+        }
+    };
+}
+function isDocumentationTemplateId(value) {
+    return listDocumentationTemplateIds().includes(value);
+}

package/dist/cli/commands/validate.d.ts

@@ -0,0 +1,9 @@
+export interface ValidateCommandOptions {
+    workspace: string;
+    config?: string;
+    failOn?: "info" | "warning" | "error" | "never";
+}
+export declare function runValidateCommand(options: ValidateCommandOptions): {
+    output: Record<string, unknown>;
+    exitCode: number;
+};

package/dist/cli/commands/validate.js

@@ -0,0 +1,85 @@
+import path from "node:path";
+import { existsSync, readFileSync } from "node:fs";
+import { indexWorkspace, shouldFailFromDiagnostics, staleCommittedCatalogue } from "../../catalogue/indexer.js";
+import { loadConfig } from "../../catalogue/config.js";
+import { OUTPUT_FILES } from "../../catalogue/store.js";
+export function runValidateCommand(options) {
+    const workspaceRoot = path.resolve(options.workspace);
+    const { config } = loadConfig({ workspaceRoot, configPath: options.config });
+    const { snapshot } = indexWorkspace({ workspaceRoot, configPath: options.config, mode: "committed", write: false });
+    let state = "catalogue_current";
+    const diagnostics = [...snapshot.diagnostics];
+    const committedPath = path.resolve(workspaceRoot, config.catalogueDir, OUTPUT_FILES.catalogue);
+    if (config.committedCatalogue) {
+        if (!existsSync(committedPath)) {
+            state = "catalogue_missing";
+            diagnostics.push({
+                id: "diag:catalogue_missing",
+                severity: "error",
+                category: "determinism",
+                code: "catalogue_missing",
+                message: "Committed catalogue file is missing.",
+                provenance: { source: "validate" }
+            });
+        }
+        else {
+            try {
+                JSON.parse(readFileSync(committedPath, "utf8"));
+                const stale = staleCommittedCatalogue(workspaceRoot, snapshot, config.catalogueDir);
+                if (stale) {
+                    state = "catalogue_stale";
+                    diagnostics.push({
+                        id: "diag:catalogue_stale",
+                        severity: "error",
+                        category: "determinism",
+                        code: "catalogue_stale",
+                        message: "Committed catalogue is stale compared with indexed snapshot.",
+                        provenance: { source: "validate" }
+                    });
+                }
+            }
+            catch {
+                state = "catalogue_unreadable";
+                diagnostics.push({
+                    id: "diag:catalogue_unreadable",
+                    severity: "error",
+                    category: "determinism",
+                    code: "catalogue_unreadable",
+                    message: "Committed catalogue exists but cannot be parsed.",
+                    provenance: { source: "validate" }
+                });
+            }
+        }
+    }
+    const failOn = options.failOn ?? config.validation.failOn;
+    const diagnosticsFailedThreshold = shouldFailFromDiagnostics(failOn, diagnostics);
+    const structuralFailure = config.committedCatalogue && state !== "catalogue_current";
+    const failed = structuralFailure || diagnosticsFailedThreshold;
+    if (diagnosticsFailedThreshold) {
+        diagnostics.push({
+            id: "diag:diagnostics_failed_threshold",
+            severity: "error",
+            category: "determinism",
+            code: "diagnostics_failed_threshold",
+            message: `Diagnostics met or exceeded configured fail threshold ${failOn}.`,
+            provenance: { source: "validate" }
+        });
+    }
+    diagnostics.sort((a, b) => a.id.localeCompare(b.id));
+    return {
+        output: {
+            ok: !failed,
+            data: {
+                state,
+                diagnostics,
+                failOn,
+                diagnosticsFailedThreshold
+            },
+            warnings: [],
+            provenance: {
+                source: "cli:validate"
+            }
+        },
+        exitCode: failed ? 1 : 0
+    };
+}

package/dist/cli/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};