@brianmsm/quarto-bento 0.0.0-stage → 0.1.1

package/distribution/runtime/src/core/graph-relations.ts

@@ -0,0 +1,354 @@
+/** Explicit source diagram relationships; saving never writes QMD or executes it. */
+import { projectPaths, readProject, saveProject } from "./project.ts";
+import { nativeGraphSlide } from "./graph-scope.ts";
+import { canonical, clone, set, targetKey } from "../state/json.ts";
+import { assertGraphDocument, graphReceipt } from "../state/graphs.ts";
+import {
+  type JsonObject,
+  type ProjectState,
+  StateError,
+} from "../state/types.ts";
+import { hashSource, scanSource } from "../source/mod.ts";
+import {
+  graphEdgeId,
+  graphNodeId,
+  sourceGraphs,
+  timelineLinkId,
+} from "../source/graphs.ts";
+
+export interface RelationGraph {
+  slideId: string;
+  slideLabel: string;
+  componentId: string;
+  kind: "diagram" | "timeline";
+  nodes: { id: string; label: string }[];
+  edges: {
+    id: string;
+    label: string;
+    fromNodeId: string;
+    toNodeId: string;
+    detached: boolean;
+  }[];
+}
+export interface GraphRelations {
+  docId: string;
+  revision: number;
+  sourceHash: string;
+  graphs: RelationGraph[];
+}
+export interface GraphRelationRequest {
+  expectedDocId: string;
+  expectedRevision: number;
+  expectedSourceHash: string;
+  slideId: string;
+  componentId: string;
+  edgeId: string;
+  fromNodeId: string;
+  toNodeId: string;
+}
+function fail(code: string, message: string): never {
+  throw new StateError(code, message);
+}
+function catalog(state: ProjectState, text: string): GraphRelations {
+  const source = scanSource(text);
+  for (const proof of Object.values(state.provenance)) {
+    if (graphReceipt(proof) && proof.source?.hash !== source.hash) {
+      fail(
+        "STALE_SOURCE",
+        "QMD cambió desde la última proyección. Recalcula o revisa sus diferencias; tus cambios pendientes siguen guardados.",
+      );
+    }
+  }
+  const graphs = sourceGraphs(source).map((graph): RelationGraph => {
+    const slideId = nativeGraphSlide(source, state, graph),
+      slide = state.emitted.slides.find((slide) => slide.id === slideId),
+      baseline = state.generatedBaseline.slides.find((slide) =>
+        slide.id === slideId
+      );
+    if (!slide || !baseline) {
+      fail(
+        "GRAPH_PENDING_DELETION",
+        "Restaura la diapositiva del gráfico antes de cambiar sus relaciones.",
+      );
+    }
+    const originalIds = graph.nodes.map((node) => node.block.id);
+    const member = (
+      nativeId: string,
+      sourceId: string,
+      role: string,
+      labelId?: string,
+    ) => {
+      const provenance =
+          state.provenance[targetKey({ slideId, elementId: nativeId })],
+        proof = graphReceipt(provenance),
+        native = slide.elements.find((element) => element.id === nativeId),
+        generated = baseline.elements.find((element) =>
+          element.id === nativeId
+        );
+      if (
+        !proof || provenance.origin !== "authored" ||
+        proof.componentId !== graph.wrapper.id ||
+        proof.sourceId !== sourceId || proof.role !== role ||
+        proof.kind !== graph.kind ||
+        proof.labelId !== labelId ||
+        canonical(proof.nodeIds) !== canonical(originalIds) ||
+        provenance.source?.hash !== source.hash || !generated
+      ) {
+        fail(
+          "UNMAPPED_GRAPH_SOURCE",
+          "Este gráfico necesita una proyección fuente verificada antes de editar relaciones.",
+        );
+      }
+      if (
+        !native ||
+        (labelId && !slide.elements.some((element) => element.id === labelId))
+      ) {
+        fail(
+          "GRAPH_PENDING_DELETION",
+          "Restaura los nodos, etiquetas y conectores pendientes de eliminación antes de editar relaciones.",
+        );
+      }
+      if (
+        native.type !== "shape" ||
+        (role === "node" || role === "milestone"
+          ? ["line", "path"].includes(String(native.shape))
+          : native.shape !== "line") ||
+        (labelId &&
+          slide.elements.find((element) => element.id === labelId)?.type !==
+            "text")
+      ) {
+        fail(
+          "GRAPH_PENDING_STRUCTURE",
+          "Restaura el tipo nativo de los nodos, textos y conectores antes de editar relaciones.",
+        );
+      }
+      return { native, generated, proof };
+    };
+    const nodes = graph.nodes.map((node) => {
+      member(
+        graphNodeId(node.block.id),
+        node.block.id,
+        graph.kind === "diagram" ? "node" : "milestone",
+        node.label!.id,
+      );
+      return { id: node.block.id, label: node.label!.content.trim() };
+    });
+    const links = graph.kind === "diagram"
+      ? graph.edges.map((edge) => ({
+        id: edge.block.id,
+        nativeId: graphEdgeId(edge.block.id),
+        sourceId: edge.block.id,
+        from: edge.from,
+        to: edge.to,
+        labelId: edge.label?.id,
+        label: edge.label?.content.trim() ?? "",
+      }))
+      : nodes.slice(0, -1).map((node, index) => ({
+        id: timelineLinkId(graph.wrapper.id, node.id, nodes[index + 1].id),
+        nativeId: timelineLinkId(
+          graph.wrapper.id,
+          node.id,
+          nodes[index + 1].id,
+        ),
+        sourceId: graph.wrapper.id,
+        from: node.id,
+        to: nodes[index + 1].id,
+        labelId: undefined,
+        label: "",
+      }));
+    const edges = links.map((link) => {
+      const { native, generated, proof } = member(
+        link.nativeId,
+        link.sourceId,
+        graph.kind === "diagram" ? "edge" : "timeline-link",
+        link.labelId,
+      );
+      const sourceNode = (endpoint: "from" | "to") => {
+        if (
+          proof[endpoint] !== link[endpoint] ||
+          (generated[endpoint] as JsonObject | undefined)?.el !==
+            graphNodeId(link[endpoint])
+        ) {
+          fail(
+            "UNMAPPED_GRAPH_SOURCE",
+            "La relación original no coincide con su proyección verificada.",
+          );
+        }
+        const id = (native[endpoint] as JsonObject | undefined)?.el;
+        if (id === undefined) return { id: link[endpoint], detached: true };
+        const node = nodes.find((node) => graphNodeId(node.id) === id);
+        if (!node) {
+          fail(
+            "GRAPH_ENDPOINT_SCOPE",
+            "La relación apunta fuera de los nodos originales del mismo gráfico.",
+          );
+        }
+        return { id: node.id, detached: false };
+      };
+      const from = sourceNode("from"), to = sourceNode("to");
+      return {
+        id: link.id,
+        label: link.label,
+        fromNodeId: from.id,
+        toNodeId: to.id,
+        detached: from.detached || to.detached,
+      };
+    });
+    return {
+      slideId,
+      slideLabel: source.blocks.find((block) =>
+        block.id === graph.wrapper.slideId && block.kind === "heading"
+      )?.content.trim() ?? slideId,
+      componentId: graph.wrapper.id,
+      kind: graph.kind,
+      nodes,
+      edges,
+    };
+  });
+  assertGraphDocument(state.emitted, state.provenance, {
+    capture: true,
+    baseline: state.generatedBaseline,
+  });
+  return {
+    docId: state.docId,
+    revision: state.revision,
+    sourceHash: source.hash,
+    graphs,
+  };
+}
+
+/** Read only; selectors come from exact source roles and verified saved native members. */
+export async function readGraphRelations(
+  source: string,
+): Promise<GraphRelations> {
+  return catalog(
+    await readProject(source),
+    await Deno.readTextFile(projectPaths(source).source),
+  );
+}
+/** One bounded atomic pair update, including explicit reconstruction after native detachment. */
+export async function saveGraphRelation(
+  source: string,
+  request: GraphRelationRequest,
+) {
+  if (
+    !request || typeof request !== "object" || Array.isArray(request) ||
+    Object.keys(request).sort().join(",") !==
+      "componentId,edgeId,expectedDocId,expectedRevision,expectedSourceHash,fromNodeId,slideId,toNodeId" ||
+    !Number.isSafeInteger(request.expectedRevision) ||
+    request.expectedRevision < 0 ||
+    ![
+      request.expectedDocId,
+      request.slideId,
+      request.componentId,
+      request.edgeId,
+      request.fromNodeId,
+      request.toNodeId,
+    ].every((value) => typeof value === "string" && value.length > 0) ||
+    typeof request.expectedSourceHash !== "string" ||
+    !/^[a-f0-9]{64}$/.test(request.expectedSourceHash)
+  ) {
+    fail(
+      "INVALID_GRAPH_RELATION",
+      "Selecciona una relación con identidad, revisión y fuente verificadas.",
+    );
+  }
+  const state = await readProject(source);
+  if (state.docId !== request.expectedDocId) {
+    fail(
+      "UNRELATED_DOCUMENT",
+      "La relación pertenece a otro documento; recarga el proyecto.",
+    );
+  }
+  if (state.revision !== request.expectedRevision) {
+    fail(
+      "STALE_REVISION",
+      "Otro guardado cambió el proyecto; recarga las relaciones antes de guardar.",
+    );
+  }
+  const text = await Deno.readTextFile(projectPaths(source).source);
+  if (hashSource(text) !== request.expectedSourceHash) {
+    fail(
+      "STALE_SOURCE",
+      "QMD cambió después de abrir las relaciones; recarga y revisa antes de guardar.",
+    );
+  }
+  const snapshot = catalog(state, text),
+    graph = snapshot.graphs.find((graph) =>
+      graph.slideId === request.slideId &&
+      graph.componentId === request.componentId
+    );
+  if (!graph) {
+    fail(
+      "GRAPH_ENDPOINT_SCOPE",
+      "Selecciona un diagrama QMD existente en su diapositiva original.",
+    );
+  }
+  if (graph.kind !== "diagram") {
+    fail(
+      "UNSUPPORTED_TIMELINE_RELATION",
+      "La secuencia deriva del orden de hitos en QMD; sus relaciones son de solo lectura.",
+    );
+  }
+  if (
+    !graph.edges.some((edge) => edge.id === request.edgeId) ||
+    !graph.nodes.some((node) => node.id === request.fromNodeId) ||
+    !graph.nodes.some((node) => node.id === request.toNodeId) ||
+    request.fromNodeId === request.toNodeId
+  ) {
+    fail(
+      "GRAPH_ENDPOINT_SCOPE",
+      "Selecciona una arista y dos nodos distintos del mismo diagrama.",
+    );
+  }
+  if (
+    state.pending.some((change) =>
+      change.kind === "field" && change.target.slideId === graph.slideId &&
+      change.target.elementId === graphEdgeId(request.edgeId) &&
+      ["from", "to"].includes(change.path[0]) &&
+      (change.path.length === 1 || change.path[1] === "el") &&
+      change.status === "conflict"
+    )
+  ) {
+    fail(
+      "GRAPH_RELATION_CONFLICT",
+      "Esta relación tiene un conflicto con QMD. Resuélvelo desde Comparar con QMD antes de elegir nuevos nodos; las demás ediciones siguen guardadas.",
+    );
+  }
+  const doc = clone(state.emitted),
+    edge = doc.slides.find((slide) => slide.id === graph.slideId)!.elements
+      .find((element) => element.id === graphEdgeId(request.edgeId))!,
+    baseline = state.generatedBaseline.slides.find((slide) =>
+      slide.id === graph.slideId
+    )!.elements.find((element) => element.id === edge.id)!;
+  for (const endpoint of ["from", "to"] as const) {
+    const current = edge[endpoint];
+    const present = current && typeof current === "object" &&
+      !Array.isArray(current);
+    const anchor = clone(present ? current : baseline[endpoint] as JsonObject);
+    if (!present) {
+      const overlay = state.overrides.find((overlay) =>
+        overlay.target.slideId === graph.slideId &&
+        overlay.target.elementId === edge.id
+      );
+      for (const field of overlay?.fields ?? []) {
+        if (
+          field.path.length === 2 && field.path[0] === endpoint &&
+          field.path[1] === "side"
+        ) set(anchor, ["side"], field.value);
+      }
+    }
+    edge[endpoint] = {
+      ...anchor,
+      el: graphNodeId(
+        endpoint === "from" ? request.fromNodeId : request.toNodeId,
+      ),
+    };
+  }
+  return await saveProject(
+    source,
+    doc,
+    request.expectedRevision,
+    request.expectedSourceHash,
+  );
+}

package/distribution/runtime/src/core/graph-scope.ts

@@ -0,0 +1,63 @@
+/** Weak source heading scope is an executed receipt, never a slug/position guess. */
+import type { SourceDocument } from "../source/mod.ts";
+import type { SourceGraph } from "../source/graphs.ts";
+import { graphReceipt } from "../state/graphs.ts";
+import { type ProjectState, StateError } from "../state/types.ts";
+import { verifiedSourceSlide } from "./source-scope.ts";
+
+function fail(): never {
+  throw new StateError(
+    "UNMAPPED_GRAPH_SOURCE",
+    "A graph under an unpinned heading needs its unique exact executed heading and native scope receipts. Recalculate and review the original source before editing relationships.",
+  );
+}
+export function nativeGraphSlide(
+  source: SourceDocument,
+  state: ProjectState,
+  graph: SourceGraph,
+): string {
+  const slides = source.slides.filter((slide) =>
+    slide.id === graph.wrapper.slideId
+  );
+  if (slides.length !== 1) fail();
+  const slide = slides[0];
+  const members = Object.entries(state.provenance).filter(([, provenance]) => {
+    const proof = graphReceipt(provenance);
+    return proof?.componentId === graph.wrapper.id;
+  });
+  if (!members.length) fail();
+  if (slide.stable) {
+    // Older explicit-ID receipts have no alias fields; any fields retained by
+    // current projections must still agree with their exact native scope.
+    for (const [key, provenance] of members) {
+      const [nativeSlideId] = JSON.parse(key) as [string],
+        proof = graphReceipt(provenance)!;
+      if (
+        nativeSlideId !== slide.id ||
+        proof.nativeSlideId !== undefined && proof.nativeSlideId !== slide.id ||
+        proof.sourceSlideId !== undefined && proof.sourceSlideId !== slide.id
+      ) fail();
+    }
+    return slide.id;
+  }
+  const scope = graphReceipt(members[0][1])!.nativeSlideId;
+  if (typeof scope !== "string" || !scope) fail();
+  for (const [key, provenance] of members) {
+    const [nativeSlideId] = JSON.parse(key) as [string],
+      proof = graphReceipt(provenance)!;
+    if (
+      nativeSlideId !== scope || proof.nativeSlideId !== scope ||
+      proof.sourceSlideId !== slide.id ||
+      proof.kind !== graph.kind || provenance.origin !== "authored" ||
+      provenance.source?.hash !== source.hash
+    ) fail();
+  }
+  try {
+    return verifiedSourceSlide(source, state, slide.id, scope);
+  } catch (error) {
+    if (error instanceof StateError && error.code === "UNMAPPED_SOURCE_SLIDE") {
+      fail();
+    }
+    throw error;
+  }
+}

package/distribution/runtime/src/core/graph-sync.ts

@@ -0,0 +1,228 @@
+/** Source-specific relationship synchronization and prospective measured graph gates. */
+import { canonical, entity, get, set, targetKey } from "../state/json.ts";
+import { graphReceipt, graphRelationshipPath } from "../state/graphs.ts";
+import {
+  type Change,
+  type JsonObject,
+  type ProjectState,
+  StateError,
+} from "../state/types.ts";
+import {
+  type GraphEndpointRequest,
+  graphFlowSignature,
+  graphNodeId,
+  sourceGraph,
+  sourceGraphs,
+} from "../source/graphs.ts";
+import { scanSource } from "../source/mod.ts";
+import { type Frame } from "../render/design.ts";
+import {
+  assertGraphTypography,
+  originalGraphNode,
+  projectGraph,
+} from "../render/graphs.ts";
+import type { BentoDoc as RenderDoc } from "../render/types.ts";
+import { nativeGraphSlide } from "./graph-scope.ts";
+
+function fail(code: string, message: string): never {
+  throw new StateError(code, message);
+}
+/** Neither native group IDs nor generic connector objects establish semantic membership. */
+export function graphSyncRequest(
+  text: string,
+  state: ProjectState,
+  change: Change,
+): GraphEndpointRequest | undefined {
+  const source = state.provenance[targetKey(change.target)];
+  if (!graphRelationshipPath(source, change.path)) return undefined;
+  const proof = graphReceipt(source)!;
+  if (proof.role === "timeline-link") {
+    fail(
+      "UNSUPPORTED_TIMELINE_RELATION",
+      "Timeline relationships derive from lexical QMD order. Restore native endpoints or reorder the original milestone blocks.",
+    );
+  }
+  if (
+    proof.role !== "edge" || proof.kind !== "diagram" ||
+    change.origin !== "authored" ||
+    change.target.elementId !== proof.sourceId + "/qb-edge" ||
+    !change.target.slideId
+  ) {
+    fail(
+      "UNMAPPED_GRAPH_SOURCE",
+      "Relationship edits require the original source diagram edge receipt.",
+    );
+  }
+  const endpoint = change.path[0] as "from" | "to";
+  let nativeId: unknown = change.after.value;
+  if (
+    change.path.length === 1 && nativeId && typeof nativeId === "object" &&
+    !Array.isArray(nativeId)
+  ) nativeId = (nativeId as JsonObject).el;
+  if (!change.after.present || typeof nativeId !== "string") {
+    fail(
+      "GRAPH_ENDPOINT_REQUIRED",
+      "A source edge endpoint needs an explicit node; removing/detaching endpoints cannot rewrite a faithful source edge.",
+    );
+  }
+  const saved = get(entity(state.emitted, change.target), [endpoint, "el"]);
+  if (!saved.present || saved.value !== nativeId) {
+    fail(
+      "GRAPH_RELATION_SNAPSHOT",
+      "The pending relationship no longer matches the saved native connector. Reopen Relations or compare with QMD before approving a source patch; all edits remain saved.",
+    );
+  }
+  const doc = scanSource(text), graph = sourceGraph(doc, proof.componentId);
+  if (
+    nativeGraphSlide(doc, state, graph) !== change.target.slideId ||
+    canonical(graph.nodes.map((node) => node.block.id).sort()) !==
+      canonical([...proof.nodeIds].sort())
+  ) {
+    fail(
+      "SOURCE_CONFLICT",
+      "The original graph membership or slide scope changed; render and review the graph before synchronizing relationships.",
+    );
+  }
+  const edge = graph.edges.find((edge) => edge.block.id === proof.sourceId);
+  const expected = proof[endpoint];
+  if (!edge || typeof expected !== "string" || edge[endpoint] !== expected) {
+    fail(
+      "SOURCE_CONFLICT",
+      "QMD independently changed this source edge endpoint; compare and resolve before synchronization.",
+    );
+  }
+  const node = graph.nodes.find((node) =>
+    graphNodeId(node.block.id) === nativeId
+  );
+  const nativeProof = node &&
+    graphReceipt(
+      state
+        .provenance[
+          targetKey({ slideId: change.target.slideId, elementId: nativeId })
+        ],
+    );
+  if (
+    !node || nativeProof?.role !== "node" ||
+    nativeProof.componentId !== proof.componentId ||
+    nativeProof.sourceId !== node.block.id ||
+    !state.emitted.slides.find((slide) => slide.id === change.target.slideId)
+      ?.elements.some((element) => element.id === nativeId)
+  ) {
+    fail(
+      "GRAPH_ENDPOINT_SCOPE",
+      "Choose an existing direct native source node shape from the same diagram.",
+    );
+  }
+  const baseline = get(entity(state.generatedBaseline, change.target), [
+    endpoint,
+    "el",
+  ]);
+  if (!baseline.present || baseline.value !== graphNodeId(expected)) {
+    fail(
+      "UNMAPPED_GRAPH_SOURCE",
+      "The saved source edge receipt no longer agrees with its generated endpoint baseline.",
+    );
+  }
+  return {
+    componentId: proof.componentId,
+    edgeId: proof.sourceId,
+    endpoint,
+    expected,
+    nodeId: node.block.id,
+  };
+}
+function checkedBase(proof: JsonObject): Frame {
+  const value = proof.base;
+  if (
+    !value || typeof value !== "object" || Array.isArray(value) ||
+    !["x", "y", "w", "h"].every((key) =>
+      typeof value[key] === "number" && Number.isFinite(value[key])
+    )
+  ) {
+    fail(
+      "UNMAPPED_GRAPH_SOURCE",
+      "A graph requires its fresh executed automatic-layout base.",
+    );
+  }
+  return value as unknown as Frame;
+}
+/** Combined proposed QMD plus retained native design, before a review can approve any writes. */
+export async function preflightGraphSync(
+  state: ProjectState,
+  current: string,
+  result: string,
+): Promise<void> {
+  const currentDoc = scanSource(current), prospective = scanSource(result);
+  const theme = state.generatedBaseline.theme as RenderDoc["theme"];
+  for (const graph of sourceGraphs(prospective)) {
+    const receipts = Object.values(state.provenance).map(graphReceipt).filter((
+      proof,
+    ) => proof?.componentId === graph.wrapper.id);
+    const proof = receipts[0];
+    if (!proof) {
+      fail(
+        "UNMAPPED_GRAPH_SOURCE",
+        "Prospective graphs require an existing fresh source graph receipt; author and render new components first.",
+      );
+    }
+    const original = sourceGraph(currentDoc, graph.wrapper.id);
+    const slideId = nativeGraphSlide(currentDoc, state, original);
+    if (
+      graph.wrapper.slideId !== original.wrapper.slideId &&
+      graph.wrapper.slideId !== slideId
+    ) {
+      fail(
+        "SOURCE_CONFLICT",
+        "The proposed graph moved outside its verified original heading scope.",
+      );
+    }
+    const explicitFrame = original.declaration.properties.y !== undefined &&
+      original.declaration.properties.h !== undefined &&
+      graph.declaration.properties.y !== undefined &&
+      graph.declaration.properties.h !== undefined;
+    if (
+      !explicitFrame &&
+      (proof.prefix !== graphFlowSignature(currentDoc, original) ||
+        proof.prefix !== graphFlowSignature(prospective, graph))
+    ) {
+      fail(
+        "GRAPH_FLOW_PREFLIGHT",
+        "A source change alters the unverified automatic flow before this graph. Declare source y and h for an independent frame, or restore/review the preceding structure before applying this combined sync.",
+      );
+    }
+    const projected = await projectGraph(
+      prospective,
+      await originalGraphNode(graph),
+      checkedBase(proof),
+      { theme },
+    );
+    // Validate actual retained geometry/typography too. Semantic pending fields
+    // are applied by the chosen prospective source, never frozen as overrides.
+    for (const element of projected.elements) {
+      const overlay = state.overrides.find((overlay) =>
+        overlay.target.slideId === slideId &&
+        overlay.target.elementId === element.id
+      );
+      for (const field of overlay?.fields ?? []) {
+        const target = element as unknown as JsonObject;
+        set(target, field.path, field.value);
+      }
+    }
+    const document = {
+      ...state.emitted,
+      slides: [{ id: slideId, elements: projected.elements }],
+    };
+    const provenance = Object.fromEntries(
+      Object.entries(projected.origins).map(([elementId, origin]) => [
+        targetKey({ slideId, elementId }),
+        {
+          origin: origin.origin,
+          source: {
+            ...(origin.graph ? { graph: origin.graph as JsonObject } : {}),
+          },
+        },
+      ]),
+    );
+    await assertGraphTypography(document as unknown as RenderDoc, provenance);
+  }
+}

package/distribution/runtime/src/core/io.ts

@@ -0,0 +1,27 @@
+/** File durability helpers for recoverable single-project transactions. */
+export async function syncDirectory(path: string) {
+  if (Deno.build.os === "windows") return;
+  const directory = await Deno.open(path, { read: true });
+  try {
+    await directory.sync();
+  } finally {
+    directory.close();
+  }
+}
+export async function writeDurable(path: string, text: string) {
+  const file = await Deno.open(path, {
+    createNew: true,
+    write: true,
+    mode: 0o600,
+  });
+  try {
+    const bytes = new TextEncoder().encode(text);
+    let offset = 0;
+    while (offset < bytes.length) {
+      offset += await file.write(bytes.subarray(offset));
+    }
+    await file.sync();
+  } finally {
+    file.close();
+  }
+}