@penpair/core 0.3.6 → 0.4.0

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

@@ -0,0 +1,161 @@
+import type { MapIcon, MapDrawingPlan } from "../maps/types.js";
+import type { ExecuteOptions } from "../client.js";
+import type { OperationOptions, OperationReport } from "../operation.js";
+import type { ExportResult } from "../export.js";
+export interface NativeDrawingNode {
+    id: string;
+    label: string;
+    summary?: string;
+    description?: string;
+    icon?: MapIcon;
+    cardTitle?: string;
+    cardSummary?: string;
+    annotationId?: string;
+    kind: string;
+    requirementIds?: string[];
+    detail?: {
+        mapId?: string;
+        contractHash?: string;
+        sourceId: string;
+        path: string;
+        sha256: string;
+        fileId: string;
+        pageId: string;
+        frameId: string;
+    };
+    origin?: "observed" | "proposed" | "owner-decision" | "unknown";
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+export interface NativeDrawingEdge {
+    labelBox?: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+    points?: {
+        x: number;
+        y: number;
+    }[];
+    id: string;
+    from: string;
+    to: string;
+    label: string;
+}
+export interface MapDrawing {
+    mapId: string;
+    contractHash: string;
+    title: string;
+    goal?: string;
+    summary?: string;
+    description?: string;
+    headerSummary?: string;
+    header?: MapDrawingPlan["header"];
+    annotations?: MapDrawingPlan["annotations"];
+    fontFamily?: string;
+    origin?: {
+        x: number;
+        y: number;
+    };
+    nodes: NativeDrawingNode[];
+    edges: NativeDrawingEdge[];
+}
+export interface MapTarget {
+    fileId: string;
+    pageId: string;
+    boardId?: string;
+}
+export interface ProjectionShape {
+    shapeId: string;
+    logicalId: string;
+    role: "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";
+    label: string | null;
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    content: string | null;
+    appearance?: unknown;
+    iconKey?: string | null;
+    interactions?: {
+        trigger: string;
+        type: string;
+        destinationId: string | null;
+        destinationPageId?: string | null;
+        destinationMapHash?: string | null;
+        destinationMapId?: string | null;
+    }[] | null;
+    from?: string;
+    to?: string;
+}
+export interface NativeMapProjection {
+    schemaVersion: 1;
+    kind: "native-map-projection";
+    fileId: string;
+    pageId: string;
+    boardId: string | null;
+    boardBounds: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    } | null;
+    mapId: string;
+    contractHash: string | null;
+    fingerprint: string;
+    shapes: ProjectionShape[];
+    conflicts: string[];
+}
+export interface PublishMapOptions extends OperationOptions {
+    /** Required for writes; the standard operation journal persists the pre-write snapshot. */
+    journal?: OperationOptions["journal"];
+    /** Last independently observed projection. Required before replacing an existing map. */
+    expected?: NativeMapProjection;
+    /** Export remains evidence awaiting human/agent visual inspection. */
+    export?: boolean;
+}
+export interface PublishMapResult {
+    report: OperationReport;
+    projection: NativeMapProjection;
+    image?: ExportResult;
+    visualReviewRequired: boolean;
+}
+export interface NativeMapProposal {
+    schemaVersion: 1;
+    kind: "native-map-proposal";
+    baseContractHash: string;
+    observedProjectionHash: string;
+    mapId: string;
+    title?: string;
+    metadataChanges?: {
+        title?: string;
+        goal?: string;
+        summary?: string | null;
+        description?: string | null;
+    };
+    changes: {
+        nodeId: string;
+        label?: string;
+        summary?: string | null;
+        description?: string | null;
+        icon?: MapIcon | null;
+    }[];
+    edgeChanges: {
+        edgeId: string;
+        from: string;
+        to: string;
+        label: string;
+    }[];
+    presentation: {
+        nodeId: string;
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    }[];
+    findings: string[];
+}
+export type ProjectionReadOptions = ExecuteOptions;

package/dist/map-penpot/types.js

@@ -0,0 +1 @@
+export {};

package/dist/maps/annotation-layout.d.ts

@@ -0,0 +1,24 @@
+import type { MapDrawingAnnotation } from "./types.js";
+type AnnotationContent = Pick<MapDrawingAnnotation, "nodeId" | "title" | "goal" | "summary" | "description" | "width">;
+export interface MapAnnotationLayout {
+    idBox: {
+        y: number;
+        height: number;
+    };
+    titleBox?: {
+        y: number;
+        height: number;
+    };
+    fields: Array<{
+        field: "goal" | "summary" | "description";
+        headingY: number;
+        headingHeight: number;
+        y: number;
+        height: number;
+    }>;
+    height: number;
+}
+/** Conservative word wrapping for Inter notes; native text uses the same reserved boxes. */
+export declare function mapNoteTextHeight(text: string, width: number, fontSize?: number, lineHeight?: number): number;
+export declare function mapAnnotationLayout(annotation: AnnotationContent): MapAnnotationLayout;
+export {};

package/dist/maps/annotation-layout.js

@@ -0,0 +1,85 @@
+function wordWidth(word, fontSize) {
+    return Array.from(word).reduce((width, character) => {
+        const factor = /\s/.test(character)
+            ? 0.35
+            : /[il.,'!:;]/.test(character)
+                ? 0.35
+                : /[MW@#]/.test(character)
+                    ? 1
+                    : /[A-Z]/.test(character)
+                        ? 0.78
+                        : /[a-z0-9]/.test(character)
+                            ? 0.62
+                            : 1;
+        return width + factor * fontSize;
+    }, 0);
+}
+/** Conservative word wrapping for Inter notes; native text uses the same reserved boxes. */
+export function mapNoteTextHeight(text, width, fontSize = 14, lineHeight = 20) {
+    let lines = 0;
+    for (const paragraph of text.split(/\r?\n/)) {
+        let lineWidth = 0;
+        let paragraphLines = 1;
+        for (const token of paragraph.split(/(\s+)/).filter(Boolean)) {
+            const tokenWidth = wordWidth(token, fontSize);
+            if (lineWidth && lineWidth + tokenWidth > width) {
+                paragraphLines++;
+                lineWidth = 0;
+            }
+            if (!lineWidth && /^\s+$/.test(token)) {
+                continue;
+            }
+            paragraphLines += Math.max(0, Math.ceil(tokenWidth / width) - 1);
+            lineWidth += tokenWidth > width ? tokenWidth % width : tokenWidth;
+        }
+        lines += paragraphLines;
+    }
+    return Math.max(1, lines) * lineHeight;
+}
+export function mapAnnotationLayout(annotation) {
+    const width = annotation.width - 40;
+    const idBox = {
+        y: 20,
+        height: 16,
+    };
+    let y = idBox.y + idBox.height + 8;
+    const titleBox = annotation.nodeId
+        ? {
+            y,
+            height: mapNoteTextHeight(annotation.title, width, 16, 24),
+        }
+        : undefined;
+    if (titleBox) {
+        y += titleBox.height + 12;
+    }
+    const fields = [];
+    for (const field of [
+        "goal",
+        "summary",
+        "description",
+    ]) {
+        const value = annotation[field];
+        if (value === undefined) {
+            continue;
+        }
+        const height = mapNoteTextHeight(value, width);
+        fields.push({
+            field,
+            headingY: y,
+            headingHeight: 16,
+            y: y + 20,
+            height,
+        });
+        y += 20 + height + 14;
+    }
+    return {
+        idBox,
+        ...(titleBox
+            ? {
+                titleBox,
+            }
+            : {}),
+        fields,
+        height: y + 6,
+    };
+}

package/dist/maps/context.d.ts

@@ -0,0 +1,13 @@
+import type { ArtifactReview, MapContext, MapContract } from "./types.js";
+export interface MapContextOptions {
+    reviews?: ArtifactReview[];
+    sourceHashes?: Record<string, string>;
+    journeyHash?: string;
+    journeyRequirementIds?: string[];
+    detailMaps?: Record<string, MapContract>;
+    detailReadiness?: Record<string, boolean>;
+    reviewEvidenceValid?: boolean;
+    maxItems?: number;
+    maxBytes?: number;
+}
+export declare function buildMapContext(raw: MapContract, options?: MapContextOptions): MapContext;

package/dist/maps/context.js

@@ -0,0 +1,207 @@
+import { findArtifactReview } from "./review.js";
+import { hashMapContract, validateMapContract, validateMapDetail } from "./validation.js";
+export function buildMapContext(raw, options = {}) {
+    const contract = validateMapContract(raw);
+    const mapHash = hashMapContract(contract);
+    const maxItems = options.maxItems ?? 100;
+    const maxBytes = options.maxBytes ?? 128 * 1024;
+    if (!Number.isInteger(maxItems) ||
+        maxItems < 1 ||
+        maxItems > 1000 ||
+        !Number.isInteger(maxBytes) ||
+        maxBytes < 4096 ||
+        maxBytes > 1024 * 1024) {
+        throw new Error("Map context requires 1–1000 items and a 4 KiB–1 MiB byte budget");
+    }
+    const reviewed = !!findArtifactReview(options.reviews ?? [], contract.kind, contract.id, mapHash) &&
+        options.reviewEvidenceValid !== false;
+    const staleSources = contract.sources.filter((source) => options.sourceHashes &&
+        Object.hasOwn(options.sourceHashes, source.id) &&
+        options.sourceHashes[source.id] !== source.sha256);
+    const unknownSources = contract.sources.filter((source) => !options.sourceHashes || !Object.hasOwn(options.sourceHashes, source.id));
+    const staleJourney = !!contract.journey &&
+        options.journeyHash !== undefined &&
+        options.journeyHash !== contract.journey.sha256;
+    const missingJourney = contract.kind === "integration-map" && !contract.journey;
+    const unknownJourney = !!contract.journey &&
+        (options.journeyHash === undefined || options.journeyRequirementIds === undefined);
+    const mappedRequirements = new Set([
+        ...contract.nodes,
+        ...contract.edges,
+    ].flatMap((entry) => entry.requirementIds ?? []));
+    const unmappedRequirements = contract.requirements.filter((requirement) => !mappedRequirements.has(requirement.id));
+    const requirementIds = new Set(contract.requirements.map((requirement) => requirement.id));
+    const missingJourneyRequirements = contract.kind === "integration-map"
+        ? (options.journeyRequirementIds ?? []).filter((id) => !requirementIds.has(id))
+        : [];
+    const details = contract.nodes
+        .filter((node) => node.kind === "detail-link")
+        .map((node) => {
+        const source = contract.sources.find((entry) => entry.id === node.sourceIds[0]);
+        const supplied = options.detailMaps?.[source.id];
+        const child = supplied ? validateMapDetail(contract, node, supplied) : undefined;
+        return {
+            nodeId: node.id,
+            sourceId: source.id,
+            path: source.path,
+            sha256: source.sha256,
+            fileId: source.fileId,
+            pageId: source.pageId,
+            frameId: source.frameId,
+            ...(child
+                ? {
+                    mapId: child.id,
+                    mapHash: hashMapContract(child),
+                }
+                : {}),
+            ready: !!child && options.detailReadiness?.[source.id] === true,
+            review: "separate-artifact",
+            contents: "not-inlined",
+        };
+    });
+    const unreadyDetails = details.filter((detail) => !detail.ready);
+    const blockers = contract.findings.filter((finding) => finding.severity === "blocking" && finding.status === "open");
+    const unknowns = [
+        ...contract.nodes,
+        ...contract.edges,
+        ...contract.requirements,
+    ].filter((entry) => entry.origin === "unknown");
+    const freshness = staleSources.length || staleJourney
+        ? "stale"
+        : unknownSources.length || unknownJourney
+            ? "unassessed"
+            : "matches-supplied-inputs";
+    const reasons = [];
+    if (!reviewed) {
+        reasons.push("Exact current contract owner review is missing or its evidence is invalid");
+    }
+    if (staleSources.length) {
+        reasons.push(`${staleSources.length} changed source(s): ${staleSources
+            .slice(0, 5)
+            .map((source) => source.id)
+            .join(", ")}`);
+    }
+    if (unknownSources.length || unknownJourney) {
+        reasons.push("Source freshness is unassessed for one or more declared references");
+    }
+    if (staleJourney || missingJourney) {
+        reasons.push(staleJourney
+            ? "Referenced journey contract changed"
+            : "Integration map requires an explicit journey contract reference");
+    }
+    if (blockers.length) {
+        reasons.push(`${blockers.length} unresolved blocking finding(s): ${blockers
+            .slice(0, 5)
+            .map((finding) => finding.id)
+            .join(", ")}`);
+    }
+    if (unknowns.length) {
+        reasons.push(`${unknowns.length} unresolved unknown semantic element(s)`);
+    }
+    if (unmappedRequirements.length) {
+        reasons.push(`${unmappedRequirements.length} unmapped local requirement(s): ${unmappedRequirements
+            .slice(0, 5)
+            .map((requirement) => requirement.id)
+            .join(", ")}`);
+    }
+    if (missingJourneyRequirements.length) {
+        reasons.push(`${missingJourneyRequirements.length} omitted journey requirement(s): ${missingJourneyRequirements.slice(0, 5).join(", ")}`);
+    }
+    if (unreadyDetails.length) {
+        reasons.push(`${unreadyDetails.length} linked detail contract(s) require separate source/readiness/review checks; contents are not inlined`);
+    }
+    const context = {
+        schemaVersion: 1,
+        kind: "map-context",
+        mapKind: contract.kind,
+        mapId: contract.id,
+        mapHash,
+        title: contract.title,
+        goal: contract.goal,
+        ...(contract.summary === undefined
+            ? {}
+            : {
+                summary: contract.summary,
+            }),
+        ...(contract.description === undefined
+            ? {}
+            : {
+                description: contract.description,
+            }),
+        reviewed,
+        ready: reviewed &&
+            freshness === "matches-supplied-inputs" &&
+            !missingJourney &&
+            !blockers.length &&
+            !unknowns.length &&
+            !unmappedRequirements.length &&
+            !missingJourneyRequirements.length &&
+            !unreadyDetails.length,
+        freshness,
+        reasons,
+        nodes: contract.nodes.slice(0, maxItems),
+        edges: contract.edges.slice(0, maxItems),
+        requirements: contract.requirements.slice(0, maxItems),
+        findings: [
+            ...blockers,
+            ...contract.findings.filter((finding) => !blockers.includes(finding)),
+        ].slice(0, maxItems),
+        sources: contract.sources.slice(0, maxItems),
+        details: details.slice(0, maxItems),
+        truncated: [
+            contract.nodes,
+            contract.edges,
+            contract.requirements,
+            contract.findings,
+            contract.sources,
+            details,
+        ].some((entries) => entries.length > maxItems),
+        implementation: "not-assessed",
+    };
+    const collections = [
+        "nodes",
+        "edges",
+        "requirements",
+        "findings",
+        "sources",
+        "details",
+    ];
+    const markTruncated = () => {
+        context.truncated = true;
+        context.ready = false;
+        const reason = "Context is truncated; inspect the complete contract before deciding readiness";
+        if (!context.reasons.includes(reason)) {
+            context.reasons.push(reason);
+        }
+    };
+    if (context.truncated) {
+        markTruncated();
+    }
+    while (true) {
+        const visibleNodes = new Set(context.nodes.map((node) => node.id));
+        const visibleEdges = context.edges.filter((edge) => visibleNodes.has(edge.from) && visibleNodes.has(edge.to));
+        if (visibleEdges.length !== context.edges.length) {
+            markTruncated();
+            context.edges = visibleEdges;
+        }
+        if (Buffer.byteLength(JSON.stringify(context)) <= maxBytes) {
+            break;
+        }
+        markTruncated();
+        const largest = collections.reduce((previous, key) => JSON.stringify(context[key]).length > JSON.stringify(context[previous]).length
+            ? key
+            : previous);
+        if (!context[largest].length) {
+            const textKey = [
+                "goal",
+                "summary",
+                "description",
+            ].reduce((previous, key) => (context[key]?.length ?? 0) > (context[previous]?.length ?? 0) ? key : previous);
+            context[textKey] = (context[textKey] ?? "").slice(0, Math.floor((context[textKey]?.length ?? 0) / 2));
+        }
+        else {
+            context[largest].splice(Math.floor(context[largest].length / 2));
+        }
+    }
+    return context;
+}

package/dist/maps/index.d.ts

@@ -0,0 +1,9 @@
+export * from "./types.js";
+export { validateMapContract, validateMapDetail, hashMapContract, maxMapBytes, } from "./validation.js";
+export { renderMapMarkdown, renderMapMermaid, buildMapDrawingPlan } from "./render.js";
+export { mapAnnotationLayout, mapNoteTextHeight, type MapAnnotationLayout, } from "./annotation-layout.js";
+export { routeMapEdges, mapLabelHeight, mapDrawingGeometryProblems, type MapRoutingNode, type MapRoutingEdge, type MapEdgeRoute, } from "./layout.js";
+export { createArtifactReview, validateArtifactReview, findArtifactReview, type ArtifactReviewInput, } from "./review.js";
+export { createMapProposal, validateMapProposal, acceptMapProposal } from "./proposal.js";
+export { buildMapContext, type MapContextOptions } from "./context.js";
+export { readMapContract, writeMapContract, readMapProposal, writeMapProposal, readArtifactReviews, writeArtifactReview, verifyArtifactReviewEvidence, observeMapSources, type MapWriteOptions, type MapSourceObservation, } from "./store.js";

package/dist/maps/index.js

@@ -0,0 +1,9 @@
+export * from "./types.js";
+export { validateMapContract, validateMapDetail, hashMapContract, maxMapBytes, } from "./validation.js";
+export { renderMapMarkdown, renderMapMermaid, buildMapDrawingPlan } from "./render.js";
+export { mapAnnotationLayout, mapNoteTextHeight, } from "./annotation-layout.js";
+export { routeMapEdges, mapLabelHeight, mapDrawingGeometryProblems, } from "./layout.js";
+export { createArtifactReview, validateArtifactReview, findArtifactReview, } from "./review.js";
+export { createMapProposal, validateMapProposal, acceptMapProposal } from "./proposal.js";
+export { buildMapContext } from "./context.js";
+export { readMapContract, writeMapContract, readMapProposal, writeMapProposal, readArtifactReviews, writeArtifactReview, verifyArtifactReviewEvidence, observeMapSources, } from "./store.js";

package/dist/maps/layout.d.ts

@@ -0,0 +1,35 @@
+import type { MapContract } from "./types.js";
+export interface MapRoutingNode {
+    id: string;
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+export interface MapRoutingEdge {
+    id: string;
+    from: string;
+    to: string;
+    label: string;
+}
+export interface MapEdgeRoute {
+    points: Array<{
+        x: number;
+        y: number;
+    }>;
+    labelBox: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+}
+export declare function mapDrawingGeometryProblems(nodes: MapRoutingNode[], edges: Array<MapEdgeRoute & {
+    id: string;
+}>): string[];
+export declare function mapLabelHeight(text: string, width: number): number;
+export declare function mapEdgeLabelWidth(label: string): number;
+/** Labels occupy dedicated gaps; routes stay outside those boxes and all card interiors. */
+export declare function routeMapEdges<T extends MapRoutingEdge>(nodes: MapRoutingNode[], edges: T[]): Array<T & MapEdgeRoute>;
+/** Ignore DFS return edges for placement only; every connector remains in the drawing. */
+export declare function mapNodeLayers(contract: MapContract): Map<string, number>;