@penpair/core 0.3.7 → 0.4.1

package/dist/map-penpot/content.js

@@ -0,0 +1,173 @@
+import { mapAnnotationLayout } from "../maps/annotation-layout.js";
+import { mapLabelHeight } from "../maps/layout.js";
+import { mapOriginLabels, mapOriginLegend } from "./status-labels.js";
+export const nativeMapRoles = [
+    "node",
+    "label",
+    "edge",
+    "edge-label",
+    "title",
+    "badge",
+    "legend",
+    "map-summary",
+    "map-full-summary",
+    "map-goal",
+    "map-description",
+    "summary",
+    "full-label",
+    "full-summary",
+    "description",
+    "annotation-panel",
+    "annotation-id",
+    "annotation-heading",
+    "icon-well",
+    "icon",
+    "port-in",
+    "port-out",
+];
+export function nativeMapTextEntries(drawing) {
+    const result = [];
+    const add = (role, logicalId, text, x, y, width, height, fontSize = 14, color = "#101828", semantic, strong = false) => {
+        result.push({
+            role,
+            logicalId,
+            text,
+            x,
+            y,
+            width,
+            height,
+            fontSize,
+            color,
+            ...(semantic
+                ? {
+                    semantic,
+                }
+                : {}),
+            ...(strong
+                ? {
+                    strong,
+                }
+                : {}),
+        });
+    };
+    const titleBox = drawing.header?.titleBox ?? {
+        x: 32,
+        y: 24,
+        width: 900,
+        height: 40,
+    };
+    add("title", drawing.mapId, drawing.title, titleBox.x, titleBox.y, titleBox.width, titleBox.height, 24, "#101828", {
+        scope: "map",
+        field: "title",
+    }, true);
+    const headerText = drawing.headerSummary ??
+        drawing.summary ??
+        (drawing.goal && drawing.goal.length <= 240 ? drawing.goal : undefined);
+    if (headerText) {
+        const box = drawing.header?.summaryBox ?? {
+            x: 32,
+            y: 72,
+            width: 900,
+            height: mapLabelHeight(headerText, 900),
+        };
+        add("map-summary", drawing.mapId, headerText, box.x, box.y, box.width, box.height, 14, "#667085", {
+            scope: "map",
+            field: drawing.summary !== undefined ? "summary" : "goal",
+        });
+    }
+    if (drawing.nodes.some((node) => node.origin)) {
+        add("legend", drawing.mapId, mapOriginLegend, 32, drawing.header?.legendY ?? (headerText ? 132 : 72), 1000, 20, 10, "#667085");
+    }
+    for (const node of drawing.nodes) {
+        const modern = node.cardTitle !== undefined;
+        const title = modern
+            ? node.cardTitle
+            : (node.kind === "decision" ? "Decision: " : node.kind === "detail-link" ? "Details: " : "") +
+                node.label;
+        add("label", node.id, title, node.x + 64, node.y + 18, node.width - 80, 32, 14, "#101828", {
+            scope: "node",
+            field: "label",
+            nodeId: node.id,
+            compact: modern && title !== node.label,
+        }, true);
+        const summary = node.cardSummary ?? node.summary;
+        if (summary) {
+            add("summary", node.id, summary, node.x + 64, node.y + 50, node.width - 80, 48, 12, "#667085", {
+                scope: "node",
+                field: "summary",
+                nodeId: node.id,
+                compact: summary !== node.summary,
+            });
+        }
+        if (node.origin) {
+            add("badge", node.id, mapOriginLabels[node.origin], node.x + 16, node.y + node.height - 24, node.width - 32, 16, 10, "#667085");
+        }
+    }
+    for (const edge of drawing.edges) {
+        if (edge.label && edge.labelBox) {
+            add("edge-label", edge.id, edge.label, edge.labelBox.x, edge.labelBox.y, edge.labelBox.width, edge.labelBox.height, 12, "#667085");
+        }
+    }
+    for (const annotation of drawing.annotations ?? []) {
+        const node = annotation.nodeId
+            ? drawing.nodes.find((candidate) => candidate.id === annotation.nodeId)
+            : undefined;
+        const id = node?.id ?? drawing.mapId;
+        const layout = mapAnnotationLayout(annotation);
+        const x = annotation.x + 20;
+        const width = annotation.width - 40;
+        add("annotation-id", annotation.id, node ? `Node · ${node.id}` : "Map context", x, annotation.y + layout.idBox.y, width, layout.idBox.height, 10, "#667085");
+        if (node && layout.titleBox) {
+            add("full-label", node.id, node.label, x, annotation.y + layout.titleBox.y, width, layout.titleBox.height, 16, "#101828", {
+                scope: "node",
+                field: "label",
+                nodeId: node.id,
+            }, true);
+        }
+        for (const fieldLayout of layout.fields) {
+            const field = fieldLayout.field;
+            const value = annotation[field];
+            add("annotation-heading", `${annotation.id}:${field}`, field[0].toUpperCase() + field.slice(1), x, annotation.y + fieldLayout.headingY, width, fieldLayout.headingHeight, 11, "#667085", undefined, true);
+            const role = node
+                ? field === "summary"
+                    ? "full-summary"
+                    : "description"
+                : field === "goal"
+                    ? "map-goal"
+                    : field === "summary"
+                        ? "map-full-summary"
+                        : "map-description";
+            add(role, id, value, x, annotation.y + fieldLayout.y, width, fieldLayout.height, 14, "#344054", {
+                scope: node ? "node" : "map",
+                field,
+                ...(node
+                    ? {
+                        nodeId: node.id,
+                    }
+                    : {}),
+            });
+        }
+    }
+    return result;
+}
+export function nativeMapShapeKeys(drawing) {
+    return new Set([
+        ...nativeMapTextEntries(drawing).map((entry) => `${entry.role}:${entry.logicalId}`),
+        ...drawing.nodes.flatMap((node) => [
+            "node",
+            "icon-well",
+            "icon",
+            "port-in",
+            "port-out",
+        ].map((role) => `${role}:${node.id}`)),
+        ...drawing.edges.flatMap((edge) => [
+            `edge:${edge.id}`,
+            ...(edge.label
+                ? [
+                    `edge-label:${edge.id}`,
+                ]
+                : []),
+        ]),
+        ...(drawing.annotations ?? []).map((annotation) => `annotation-panel:${annotation.id}`),
+    ]);
+}

package/dist/map-penpot/details.d.ts

@@ -0,0 +1,4 @@
+import type { MapDrawing } from "./types.js";
+/** Resolve only explicitly pinned direct contracts; never recurse into another map's sources. */
+export declare function resolveMapDetails(root: string, drawing: MapDrawing): Promise<MapDrawing>;
+export declare function requireResolvedMapDetails(drawing: MapDrawing): void;

package/dist/map-penpot/details.js

@@ -0,0 +1,84 @@
+import { createHash } from "node:crypto";
+import { readProjectBytes } from "../bounded-file.js";
+import { hashMapContract, maxMapBytes, validateMapContract, validateMapDetail, } from "../maps/validation.js";
+/** Resolve only explicitly pinned direct contracts; never recurse into another map's sources. */
+export async function resolveMapDetails(root, drawing) {
+    const references = drawing.nodes.filter((node) => node.detail);
+    if (references.length > 64) {
+        throw new Error("Native map supports at most 64 direct detail references");
+    }
+    const identity = drawing.mapId.match(/^(journey-map|integration-map):(.+)$/);
+    if (references.length && !identity) {
+        throw new Error("Native detail maps require a namespaced canonical parent identity");
+    }
+    const parent = {
+        kind: identity?.[1],
+        id: identity?.[2] ?? "",
+        sources: references.map((node) => ({
+            ...node.detail,
+            id: node.detail.sourceId,
+            kind: "contract",
+        })),
+    };
+    let totalBytes = 0;
+    const cache = new Map();
+    const resolved = new Map();
+    for (const node of references) {
+        const detail = node.detail;
+        const key = `${detail.path}:${detail.sha256}`;
+        let contract = cache.get(key);
+        if (!contract) {
+            const bytes = await readProjectBytes(root, detail.path, maxMapBytes);
+            totalBytes += bytes.length;
+            if (totalBytes > 128 * 1024 * 1024) {
+                throw new Error("Direct detail contracts exceed the 128 MiB aggregate budget");
+            }
+            if (createHash("sha256").update(bytes).digest("hex") !== detail.sha256) {
+                throw new Error(`Pinned detail contract changed: ${detail.sourceId}`);
+            }
+            let raw;
+            try {
+                raw = JSON.parse(bytes.toString("utf8"));
+            }
+            catch {
+                throw new Error(`Invalid detail contract JSON: ${detail.sourceId}`);
+            }
+            contract = validateMapContract(raw);
+            cache.set(key, contract);
+        }
+        validateMapDetail(parent, {
+            id: node.id,
+            sourceIds: [
+                detail.sourceId,
+            ],
+            requirementIds: node.requirementIds,
+        }, contract);
+        const identity = {
+            mapId: `${contract.kind}:${contract.id}`,
+            contractHash: hashMapContract(contract),
+        };
+        if ((detail.mapId !== undefined && detail.mapId !== identity.mapId) ||
+            (detail.contractHash !== undefined && detail.contractHash !== identity.contractHash)) {
+            throw new Error(`Resolved detail contract identity differs: ${detail.sourceId}`);
+        }
+        resolved.set(key, identity);
+    }
+    return {
+        ...drawing,
+        nodes: drawing.nodes.map((node) => node.detail
+            ? {
+                ...node,
+                detail: {
+                    ...node.detail,
+                    ...resolved.get(`${node.detail.path}:${node.detail.sha256}`),
+                },
+            }
+            : node),
+    };
+}
+export function requireResolvedMapDetails(drawing) {
+    if (drawing.nodes.some((node) => node.detail &&
+        (!node.detail.mapId || !/^[a-f0-9]{64}$/.test(node.detail.contractHash ?? "")))) {
+        throw new Error("Resolve pinned detail contract identities before using native map evidence");
+    }
+}

package/dist/map-penpot/evidence-error.d.ts

@@ -0,0 +1,5 @@
+import { PenpairError } from "../errors.js";
+export declare class MapExportEvidenceError extends PenpairError {
+    readonly runId: string;
+    constructor(runId: string, detail: string);
+}

package/dist/map-penpot/evidence-error.js

@@ -0,0 +1,9 @@
+import { PenpairError } from "../errors.js";
+export class MapExportEvidenceError extends PenpairError {
+    runId;
+    constructor(runId, detail) {
+        super("incomplete-output", `Native map write is verified, but export evidence failed for run ${runId}: ${detail}. Inspect the run and rerun the original publish command with --apply --resume ${runId}.`);
+        this.runId = runId;
+        this.name = "MapExportEvidenceError";
+    }
+}

package/dist/map-penpot/icons.d.ts

@@ -0,0 +1,5 @@
+import type { MapIcon } from "../maps/types.js";
+import type { ProjectionShape } from "./types.js";
+export declare const nativeMapIcons: Record<MapIcon, string>;
+export declare function defaultMapIcon(kind: string): MapIcon;
+export declare function identifyMapIcon(shape: Pick<ProjectionShape, "content">): MapIcon | undefined;

package/dist/map-penpot/icons.js

@@ -0,0 +1,79 @@
+export const nativeMapIcons = {
+    screen: "M0 0 L24 0 L24 18 L0 18 L0 0 M6 24 L18 24 M12 18 L12 24",
+    action: "M14 0 L2 14 L11 14 L10 24 L22 9 L13 9 L14 0",
+    decision: "M12 0 L24 12 L12 24 L0 12 L12 0",
+    data: "M0 0 L24 0 L24 24 L0 24 L0 0 M0 8 L24 8 M0 16 L24 16",
+    service: "M0 0 L24 0 L24 10 L0 10 L0 0 M0 14 L24 14 L24 24 L0 24 L0 14 M5 5 L8 5 M5 19 L8 19",
+    code: "M8 0 L0 12 L8 24 M16 0 L24 12 L16 24",
+    check: "M0 12 L8 22 L24 0",
+    link: "M0 8 L0 0 L16 0 L16 16 L8 16 M8 8 L24 8 L24 24 L8 24 L8 8",
+};
+export function defaultMapIcon(kind) {
+    if (kind === "decision") {
+        return "decision";
+    }
+    if (kind === "detail-link") {
+        return "link";
+    }
+    if (/screen|view|page|route/.test(kind)) {
+        return "screen";
+    }
+    if (/data|store|state/.test(kind)) {
+        return "data";
+    }
+    if (/service|api|request/.test(kind)) {
+        return "service";
+    }
+    if (/component|hook|code/.test(kind)) {
+        return "code";
+    }
+    if (/success|outcome|complete/.test(kind)) {
+        return "check";
+    }
+    return "action";
+}
+function normalizedIcon(content) {
+    if (typeof content !== "string" || content.length > 8192) {
+        return undefined;
+    }
+    const tokens = content.match(/[ML]|[-+]?(?:\d+\.?\d*|\.\d+)(?:[eE][-+]?\d+)?/g);
+    if (!tokens || tokens.join("") !== content.replace(/[\s,]/g, "")) {
+        return undefined;
+    }
+    const points = [];
+    for (let index = 0; index < tokens.length; index += 3) {
+        const command = tokens[index];
+        const x = Number(tokens[index + 1]);
+        const y = Number(tokens[index + 2]);
+        if (![
+            "M",
+            "L",
+        ].includes(command ?? "") ||
+            !Number.isFinite(x) ||
+            !Number.isFinite(y)) {
+            return undefined;
+        }
+        points.push({
+            command: command,
+            x,
+            y,
+        });
+    }
+    const minX = Math.min(...points.map((point) => point.x));
+    const minY = Math.min(...points.map((point) => point.y));
+    const width = Math.max(...points.map((point) => point.x)) - minX;
+    const height = Math.max(...points.map((point) => point.y)) - minY;
+    if (width <= 0 || height <= 0) {
+        return undefined;
+    }
+    return points
+        .map((point) => `${point.command}${Math.round(((point.x - minX) / width) * 10000)},${Math.round(((point.y - minY) / height) * 10000)}`)
+        .join(" ");
+}
+export function identifyMapIcon(shape) {
+    const actual = normalizedIcon(shape.content);
+    if (!actual) {
+        return undefined;
+    }
+    return Object.keys(nativeMapIcons).find((icon) => normalizedIcon(nativeMapIcons[icon]) === actual);
+}

package/dist/map-penpot/import-content.d.ts

@@ -0,0 +1,2 @@
+import type { MapDrawing, NativeMapProjection, NativeMapProposal } from "./types.js";
+export declare function importNativeContent(drawing: MapDrawing, observed: NativeMapProjection, findings: string[]): Pick<NativeMapProposal, "changes" | "metadataChanges">;

package/dist/map-penpot/import-content.js

@@ -0,0 +1,150 @@
+import { nativeMapTextEntries } from "./content.js";
+import { defaultMapIcon, identifyMapIcon } from "./icons.js";
+export function importNativeContent(drawing, observed, findings) {
+    const entries = nativeMapTextEntries(drawing);
+    const changes = [];
+    const metadataChanges = {};
+    const read = (scope, field, nodeId) => {
+        const relevant = entries.filter((entry) => entry.semantic?.scope === scope &&
+            entry.semantic.field === field &&
+            entry.semantic.nodeId === nodeId);
+        const changed = relevant.flatMap((entry) => {
+            const actual = observed.shapes.find((shape) => shape.role === entry.role && shape.logicalId === entry.logicalId);
+            const text = actual?.label?.trim() ?? "";
+            return text !== entry.text
+                ? [
+                    {
+                        text,
+                        compact: entry.semantic?.compact === true,
+                    },
+                ]
+                : [];
+        });
+        if (!relevant.length) {
+            const roles = scope === "map"
+                ? field === "goal"
+                    ? [
+                        "map-goal",
+                    ]
+                    : field === "summary"
+                        ? [
+                            "map-summary",
+                        ]
+                        : [
+                            "map-description",
+                        ]
+                : field === "label"
+                    ? [
+                        "label",
+                        "full-label",
+                    ]
+                    : field === "summary"
+                        ? [
+                            "summary",
+                            "full-summary",
+                        ]
+                        : [
+                            "description",
+                        ];
+            const actual = observed.shapes.find((shape) => roles.includes(shape.role) &&
+                shape.logicalId === (nodeId ?? drawing.mapId) &&
+                !entries.some((entry) => entry.role === shape.role &&
+                    entry.logicalId === shape.logicalId &&
+                    entry.semantic &&
+                    entry.semantic.field !== field));
+            return actual?.label?.trim() || undefined;
+        }
+        if (!changed.length) {
+            return undefined;
+        }
+        const full = changed.find((change) => !change.compact);
+        const selected = full ?? changed[0];
+        if (selected.compact && selected.text.endsWith("…")) {
+            findings.push(`Edit the full ${field} annotation for ${nodeId ?? drawing.mapId}; compact text is incomplete`);
+            return undefined;
+        }
+        if (changed.some((change) => change.text !== selected.text && !selected.text.startsWith(change.text.replace(/…$/, "")))) {
+            findings.push(`Conflicting compact/full ${field} edits: ${nodeId ?? drawing.mapId}`);
+        }
+        return selected.text || null;
+    };
+    for (const field of [
+        "title",
+        "goal",
+        "summary",
+        "description",
+    ]) {
+        const value = read("map", field);
+        if (value === undefined) {
+            continue;
+        }
+        if (field === "goal" || field === "title") {
+            if (!value) {
+                findings.push("Map goal cannot be empty");
+            }
+            else {
+                metadataChanges[field] = value;
+            }
+        }
+        else {
+            metadataChanges[field] = value;
+        }
+    }
+    for (const node of drawing.nodes) {
+        const change = {
+            nodeId: node.id,
+        };
+        for (const field of [
+            "label",
+            "summary",
+            "description",
+        ]) {
+            let value = read("node", field, node.id);
+            if (value === undefined) {
+                continue;
+            }
+            if (field === "label") {
+                if (!value) {
+                    findings.push(`Node title cannot be empty: ${node.id}`);
+                    continue;
+                }
+                if (node.cardTitle === undefined) {
+                    value =
+                        node.kind === "decision"
+                            ? value.replace(/^Decision: /, "")
+                            : node.kind === "detail-link"
+                                ? value.replace(/^Details: /, "")
+                                : value;
+                }
+                change.label = value;
+            }
+            else {
+                change[field] = value;
+            }
+        }
+        const icon = observed.shapes.find((shape) => shape.role === "icon" && shape.logicalId === node.id);
+        const key = icon ? identifyMapIcon(icon) : undefined;
+        if (!key) {
+            findings.push(`Unrecognized or missing native icon: ${node.id}`);
+        }
+        else if (icon?.iconKey &&
+            icon.iconKey !== key &&
+            icon.iconKey !== (node.icon ?? defaultMapIcon(node.kind))) {
+            findings.push(`Icon metadata and glyph disagree: ${node.id}`);
+        }
+        else if (key !== (node.icon ?? defaultMapIcon(node.kind))) {
+            change.icon = key;
+        }
+        if (Object.keys(change).length > 1) {
+            changes.push(change);
+        }
+    }
+    return {
+        changes,
+        ...(Object.keys(metadataChanges).length
+            ? {
+                metadataChanges,
+            }
+            : {}),
+    };
+}

package/dist/map-penpot/import.d.ts

@@ -0,0 +1,5 @@
+import type { MapContract, MapProposal } from "../maps/types.js";
+import type { MapDrawing, NativeMapProjection, NativeMapProposal } from "./types.js";
+export declare function importMapProposal(drawing: MapDrawing, observed: NativeMapProjection, baseline?: NativeMapProjection): NativeMapProposal;
+/** Convert a native observation into the canonical reviewed proposal format. */
+export declare function nativeProposalToMapProposal(map: MapContract, drawing: MapDrawing, observed: NativeMapProjection, baseline?: NativeMapProjection): MapProposal;