@brianmsm/quarto-bento 0.0.0-stage → 0.1.1

package/distribution/runtime/src/source/identities.ts

@@ -0,0 +1,256 @@
+/** Inspectable identity acquisition; source writes belong only to approved sync. */
+import { literalTableBlock } from "./table.ts";
+import {
+  hashSource,
+  scanSource,
+  sliceBytes,
+  type SourceDocument,
+  SourceError,
+  type SourcePatch,
+} from "./mod.ts";
+import { isNativeIdentity, isSourceIdentity } from "./identity-id.ts";
+import {
+  originalAttributeTokens,
+  originalPandocAttributes,
+} from "./attributes.ts";
+
+export interface IdentityRequest {
+  blockId: string;
+  sourceId: string;
+  nativeId: string;
+  imageNativeId?: string;
+  title: boolean;
+}
+export interface IdentityPreview {
+  version: 1;
+  kind: "source-identities";
+  sourceHash: string;
+  requests: IdentityRequest[];
+  /** Preserve offset-derived computed identities without editing executable bytes. */
+  producerRequests?: string[];
+  patches: SourcePatch[];
+  bindings: { blockId: string; newBlockId: string }[];
+  result: string;
+  resultHash: string;
+}
+const encoder = new TextEncoder(),
+  decoder = new TextDecoder("utf-8", { fatal: true });
+function fail(message: string): never {
+  throw new SourceError("ambiguous-identity", message);
+}
+function splice(text: string, patches: SourcePatch[]) {
+  let bytes = encoder.encode(text);
+  for (
+    const patch of [...patches].sort((a, b) => b.span.start - a.span.start)
+  ) {
+    if (sliceBytes(text, patch.span) !== patch.expected) {
+      fail(
+        "Identity fragment changed.",
+      );
+    }
+    const replacement = encoder.encode(patch.replacement),
+      next = new Uint8Array(
+        bytes.length - (patch.span.end - patch.span.start) + replacement.length,
+      );
+    next.set(bytes.subarray(0, patch.span.start));
+    next.set(replacement, patch.span.start);
+    next.set(
+      bytes.subarray(patch.span.end),
+      patch.span.start + replacement.length,
+    );
+    bytes = next;
+  }
+  return decoder.decode(bytes);
+}
+export function previewIdentities(
+  document: SourceDocument,
+  requests: IdentityRequest[],
+  producerRequests: string[] = [],
+): IdentityPreview {
+  if (
+    hashSource(document.text) !== document.hash || document.diagnostics.length
+  ) fail("Resolve source diagnostics before acquiring identities.");
+  const patches: SourcePatch[] = [],
+    bindings: IdentityPreview["bindings"] = [],
+    reserved = new Set(
+      document.blocks.filter((b) => b.stable).map((b) => b.id),
+    );
+  const seen = new Set<string>();
+  for (const request of requests) {
+    if (
+      !isSourceIdentity(request.sourceId) ||
+      !isNativeIdentity(request.nativeId) ||
+      (request.imageNativeId !== undefined &&
+        (!isNativeIdentity(request.imageNativeId) ||
+          request.imageNativeId === request.nativeId)) ||
+      seen.has(request.blockId) ||
+      reserved.has(request.sourceId)
+    ) fail("Source/native identities are unsafe or collide.");
+    seen.add(request.blockId);
+    reserved.add(request.sourceId);
+    const blocks = document.blocks.filter((block) =>
+      block.id === request.blockId
+    );
+    if (blocks.length !== 1) {
+      fail("Identity does not select exactly one original block.");
+    }
+    const block = blocks[0];
+    const table = block.kind === "unsupported" &&
+      literalTableBlock(document, block.id);
+    if (
+      block.stable || block.origin !== "authored" ||
+      !block.editable && !table ||
+      !table &&
+        !["heading", "paragraph", "list", "math", "code", "image"].includes(
+          block.kind,
+        )
+    ) {
+      fail(
+        "Only weak authored headings, paragraphs, lists, display equations and displayed code can acquire a verified identity.",
+      );
+    }
+    if (block.parentId) {
+      const parent = document.blocks.find((candidate) =>
+        candidate.id === block.parentId
+      );
+      if (!parent || /\.bento-[\w-]+/.test(parent.raw.split(/\r?\n/)[0])) {
+        fail(
+          "Pin component child identities explicitly; wrapping must not change component structure.",
+        );
+      }
+    }
+    let replacement: string, newBlockId: string;
+    if (block.kind === "heading") {
+      const newline = block.raw.endsWith("\r\n")
+        ? "\r\n"
+        : block.raw.endsWith("\n")
+        ? "\n"
+        : "";
+      const line = block.raw.slice(0, block.raw.length - newline.length),
+        attrs = /\{([^{}]*)\}[ \t]*$/.exec(line);
+      const native = request.title
+        ? ` bento-title-id="${request.nativeId}"`
+        : "";
+      if (attrs) {
+        const attr = originalPandocAttributes(
+          attrs[1],
+          originalAttributeTokens(attrs[1]),
+        );
+        if (attr[0] || attr[2].some(([name]) => name === "bento-title-id")) {
+          fail("Heading already has an ambiguous source/native declaration.");
+        }
+        replacement = line.slice(0, attrs.index) +
+          `{#${request.sourceId} ${attrs[1]}${native}}` +
+          line.slice(attrs.index + attrs[0].length) + newline;
+      } else replacement = line + ` {#${request.sourceId}${native}}` + newline;
+      newBlockId = request.sourceId;
+    } else {
+      if (request.title) fail("A body text block is not a slide title.");
+      if (
+        block.kind === "image" && !request.imageNativeId ||
+        block.kind !== "image" && request.imageNativeId !== undefined
+      ) fail("Image identity needs its original checked native pair.");
+      const newline = document.newline;
+      const body = block.raw + (block.raw.endsWith("\n") ? "" : newline);
+      replacement =
+        `::: {#${request.sourceId} bento-element-id="${request.nativeId}"${
+          request.imageNativeId
+            ? ` bento-image-id="${request.imageNativeId}"`
+            : ""
+        }}${newline}${newline}${body}${newline}:::${newline}`;
+      newBlockId = `${request.sourceId}/${block.kind}:1`;
+    }
+    patches.push({
+      blockId: block.id,
+      span: block.span,
+      expected: block.raw,
+      replacement,
+    });
+    bindings.push({ blockId: block.id, newBlockId });
+  }
+  for (const producerId of producerRequests) {
+    const blocks = document.blocks.filter((block) => block.id === producerId);
+    const block = blocks[0];
+    if (
+      !/^chunk@(?:0|[1-9][0-9]*)$/.test(producerId) || seen.has(producerId) ||
+      blocks.length !== 1 || !block || block.kind !== "chunk" ||
+      block.origin !== "computed" || block.stable || block.parentId ||
+      block.id !== `chunk@${block.span.start}`
+    ) {
+      fail(
+        "Producer identity needs one exact unlabelled top-level executable chunk.",
+      );
+    }
+    seen.add(producerId);
+    patches.push({
+      blockId: producerId,
+      span: { start: block.span.start, end: block.span.start },
+      expected: "",
+      replacement: `<!-- qb-producer:${producerId} -->${document.newline}`,
+    });
+  }
+  const ordered = [...patches].sort((a, b) => a.span.start - b.span.start);
+  for (let i = 1; i < ordered.length; i++) {
+    if (ordered[i].span.start < ordered[i - 1].span.end) {
+      fail("Identity patches overlap.");
+    }
+  }
+  const result = splice(document.text, patches), fresh = scanSource(result);
+  if (fresh.diagnostics.length) {
+    fail("Acquired identities make source structure ambiguous.");
+  }
+  for (const binding of bindings) {
+    const before = document.blocks.find((block) =>
+        block.id === binding.blockId
+      )!,
+      after = fresh.blocks.filter((block) => block.id === binding.newBlockId);
+    if (
+      after.length !== 1 || after[0].kind !== before.kind ||
+      after[0].content !== before.content || after[0].origin !== "authored"
+    ) fail("Identity acquisition changed authored content.");
+  }
+  for (const producerId of producerRequests) {
+    const before = document.blocks.find((block) => block.id === producerId)!;
+    const matches = fresh.blocks.filter((block) => block.id === producerId);
+    const after = matches[0];
+    if (
+      matches.length !== 1 || after.kind !== "chunk" ||
+      after.origin !== "computed" || !after.stable ||
+      after.raw !== before.raw || after.content !== before.content ||
+      after.editable
+    ) fail("Producer identity changed executable content or ownership.");
+  }
+  return {
+    version: 1,
+    kind: "source-identities",
+    sourceHash: document.hash,
+    requests: structuredClone(requests),
+    ...(producerRequests.length
+      ? { producerRequests: [...producerRequests] }
+      : {}),
+    patches,
+    bindings,
+    result,
+    resultHash: hashSource(result),
+  };
+}
+export function applyIdentities(text: string, plan: IdentityPreview): string {
+  if (hashSource(text) !== plan.sourceHash) {
+    throw new SourceError(
+      "stale-source",
+      "Source changed after identity preview.",
+    );
+  }
+  const fresh = previewIdentities(
+    scanSource(text),
+    plan.requests,
+    plan.producerRequests,
+  );
+  if (JSON.stringify(fresh) !== JSON.stringify(plan)) {
+    throw new SourceError(
+      "invalid-identity-plan",
+      "Identity preview was modified.",
+    );
+  }
+  return fresh.result;
+}

package/distribution/runtime/src/source/identity-id.ts

@@ -0,0 +1,6 @@
+/** Source identifiers are global; native identifiers are scoped to a slide. */
+export const isSourceIdentity = (value: string): boolean =>
+  /^[\p{L}_][\p{L}\p{N}\p{M}_.:-]*$/u.test(value);
+/** Existing mapped children can contain '/', and Unicode automatic heading IDs. */
+export const isNativeIdentity = (value: string): boolean =>
+  /^[\p{L}_][\p{L}\p{N}\p{M}_.:/-]*$/u.test(value);

package/distribution/runtime/src/source/image.ts

@@ -0,0 +1,50 @@
+/** Exact Markdown caption span for one standalone inline image. The Pandoc
+ * proof remains responsible for confirming that the entire block is an image.
+ */
+export const IMAGE_CODEC_VERSION = 1;
+export interface ImageCaptionSyntax {
+  start: number;
+  end: number;
+  caption: string;
+}
+export function imageCaptionSyntax(
+  raw: string,
+): ImageCaptionSyntax | undefined {
+  const opening = /^ {0,3}!\[/.exec(raw);
+  if (!opening) return undefined;
+  const start = opening[0].length;
+  let depth = 1;
+  for (let index = start; index < raw.length; index++) {
+    const character = raw[index];
+    if (character === "\\") {
+      index++;
+      continue;
+    }
+    if (character === "`") {
+      const run = /^`+/.exec(raw.slice(index))![0];
+      let close = index + run.length;
+      while (close < raw.length) {
+        const next = raw.indexOf("`", close);
+        if (next < 0) return undefined;
+        const candidate = /^`+/.exec(raw.slice(next))![0];
+        if (candidate.length === run.length) {
+          index = next + run.length - 1;
+          break;
+        }
+        close = next + candidate.length;
+      }
+      if (close >= raw.length) return undefined;
+      continue;
+    }
+    if (character === "[") depth++;
+    if (character === "]" && --depth === 0) {
+      if (raw[index + 1] !== "(") return undefined;
+      return {
+        start: new TextEncoder().encode(raw.slice(0, start)).length,
+        end: new TextEncoder().encode(raw.slice(0, index)).length,
+        caption: raw.slice(start, index),
+      };
+    }
+  }
+  return undefined;
+}

package/distribution/runtime/src/source/kpi.ts

@@ -0,0 +1,196 @@
+/** Original-source contract for the deliberately bounded KPI composition. */
+import {
+  hashSource,
+  scanSource,
+  type SourceBlock,
+  type SourceDocument,
+} from "./mod.ts";
+import {
+  originalAttributeTokens,
+  originalPandocAttributes,
+} from "./attributes.ts";
+import {
+  type DesignDeclaration,
+  DesignError,
+  nativeDesignField,
+  type PandocAttr,
+  parseDesignAttributes,
+} from "../render/design.ts";
+
+export type KpiRole = "label" | "value" | "detail";
+export interface KpiSlot {
+  role: KpiRole;
+  wrapper: SourceBlock;
+  paragraph: SourceBlock;
+  attr: PandocAttr;
+  design: DesignDeclaration;
+}
+export interface KpiSource {
+  wrapper: SourceBlock;
+  attr: PandocAttr;
+  design: DesignDeclaration;
+  slots: KpiSlot[];
+  /** Verified outermost source component; native Bento grouping is flat. */
+  groupId: string;
+  ancestors: string[];
+}
+function fail(code: string, message: string): never {
+  throw new DesignError(code, message);
+}
+export function kpiSourceAttributes(block: SourceBlock): PandocAttr {
+  const content = /^ {0,3}:{3,}\s*\{([^{}]*)\}\s*$/.exec(
+    block.raw.split(/\r?\n/)[0],
+  )?.[1];
+  if (content === undefined) {
+    fail(
+      "KPI_SOURCE_ATTRIBUTES",
+      "Use literal fenced-div attributes for KPI identities and roles.",
+    );
+  }
+  return originalPandocAttributes(content, originalAttributeTokens(content));
+}
+/** A computed paragraph is its own inline source proof; no chunk is invented. */
+function assertInlineValue(block: SourceBlock): void {
+  if (block.origin !== "computed") return;
+  // Quarto's ordinary inline forms only. Shortcodes, multiline/delimiter tricks,
+  // and unproved dynamic constructs have no faithful KPI mapping in this slice.
+  if (/\{\{[<%]|\r|\n/.test(block.content)) {
+    fail(
+      "KPI_INLINE_SOURCE_UNSUPPORTED",
+      "Use a single-line Quarto inline expression in the value slot.",
+    );
+  }
+  const codes = [...block.content.matchAll(/(?<!`)(`+)([^`]*?)\1(?!`)/g)];
+  const expressions = codes.filter((match) =>
+    /^(?:r\s+|\{(?:r|python|julia)\}\s*)\S/.test(match[2])
+  );
+  if (!expressions.length || expressions.some((match) => match[1] !== "`")) {
+    fail(
+      "KPI_INLINE_SOURCE_UNSUPPORTED",
+      "The computed value needs an explicit supported Quarto inline expression, not a synthetic producer.",
+    );
+  }
+}
+export function kpiSource(document: SourceDocument, id: string): KpiSource {
+  if (document.hash !== hashSource(document.text)) {
+    fail(
+      "KPI_SOURCE_CHANGED",
+      "The original KPI source snapshot hash is stale.",
+    );
+  }
+  const source = scanSource(document.text);
+  if (source.diagnostics.length) {
+    fail(
+      "KPI_SOURCE_IDENTITY",
+      "Resolve duplicate IDs or malformed source structure before rendering a KPI.",
+    );
+  }
+  const wrappers = source.blocks.filter((block) => block.id === id);
+  if (
+    wrappers.length !== 1 || wrappers[0].kind !== "div" ||
+    !wrappers[0].explicitId
+  ) {
+    fail(
+      "KPI_SOURCE_IDENTITY",
+      "A KPI needs one globally identified original fenced div.",
+    );
+  }
+  const wrapper = wrappers[0], attr = kpiSourceAttributes(wrapper);
+  const design = parseDesignAttributes(attr);
+  if (attr[0] !== id || design.component !== "kpi" || id.length + 18 > 160) {
+    fail(
+      "KPI_SOURCE_IDENTITY",
+      "The original .bento-kpi identity must fit the pinned native object IDs.",
+    );
+  }
+  const ancestors: string[] = [];
+  let parentId = wrapper.parentId;
+  while (parentId) {
+    const parent = source.blocks.find((block) => block.id === parentId);
+    if (
+      !parent || ancestors.includes(parentId) || parent.kind !== "div" ||
+      !parent.explicitId || parent.origin !== "authored" ||
+      parent.slideId !== wrapper.slideId ||
+      !["card", "layout"].includes(
+        parseDesignAttributes(kpiSourceAttributes(parent)).component ?? "",
+      )
+    ) {
+      fail(
+        "KPI_SOURCE_CONTEXT",
+        "KPI ancestors must be identified original cards/layouts on the same slide, outside execution output.",
+      );
+    }
+    ancestors.push(parentId);
+    parentId = parent.parentId;
+  }
+  const children = source.blocks.filter((block) => block.parentId === id);
+  if (
+    children.length < 2 || children.length > 3 ||
+    children.some((block) => block.kind !== "div" || !block.explicitId)
+  ) {
+    fail(
+      "KPI_SLOT_STRUCTURE",
+      "A KPI needs exactly two or three identified direct div children: label, value, optional detail.",
+    );
+  }
+  const roles: KpiRole[] = ["label", "value", "detail"];
+  const slots = children.map((child, index): KpiSlot => {
+    const childAttr = kpiSourceAttributes(child);
+    const declared = childAttr[2].filter(([key]) => key === "bento-role");
+    if (
+      childAttr[0] !== child.id || child.id.length + 12 > 160 ||
+      declared.length !== 1 || declared[0][1] !== roles[index] ||
+      childAttr[1].length
+    ) {
+      fail(
+        "KPI_SLOT_ROLE",
+        "Declare the unique roles label, value, optional detail in that order, on plain identified div children.",
+      );
+    }
+    const descendants = source.blocks.filter((block) =>
+      block.parentId === child.id
+    );
+    if (
+      descendants.length !== 1 || descendants[0].kind !== "paragraph" ||
+      descendants[0].id !== `${child.id}/paragraph:1`
+    ) {
+      fail(
+        "KPI_SLOT_PARAGRAPH",
+        "Each KPI role needs exactly one ordinary paragraph; nested blocks and separately marked paragraphs refuse.",
+      );
+    }
+    if (
+      childAttr[2].some(([key]) =>
+        key !== "bento-role" && !nativeDesignField(key)
+      )
+    ) {
+      fail(
+        "KPI_SLOT_ATTRIBUTE",
+        "KPI children accept bento-role and supported native text design fields only.",
+      );
+    }
+    const paragraph = descendants[0];
+    if (paragraph.origin === "computed" && roles[index] !== "value") {
+      fail(
+        "KPI_LITERAL_ROLE_REQUIRED",
+        "Label and detail are authored literal paragraphs; inline computation belongs to value.",
+      );
+    }
+    assertInlineValue(paragraph);
+    return {
+      role: roles[index],
+      wrapper: child,
+      paragraph,
+      attr: childAttr,
+      design: parseDesignAttributes(childAttr),
+    };
+  });
+  return {
+    wrapper,
+    attr,
+    design,
+    slots,
+    ancestors,
+    groupId: ancestors.at(-1) ?? id,
+  };
+}