@brianmsm/quarto-bento 0.0.0-stage → 0.1.0

package/distribution/runtime/src/render/quarto.ts

@@ -0,0 +1,127 @@
+import {
+  basename,
+  dirname,
+  isAbsolute,
+  relative,
+  resolve,
+  sep,
+} from "node:path";
+import { fileURLToPath } from "node:url";
+import type { Ast } from "./types.ts";
+import {
+  assertCompatibleProducerFilters,
+  attachProducerCapture,
+  prepareProducerCapture,
+} from "./producer-capture.ts";
+async function assertPrivateBuild(buildRoot: string): Promise<void> {
+  const pending = [buildRoot];
+  let entries = 0;
+  while (pending.length) {
+    const current = pending.pop()!;
+    if (++entries > 50_000) {
+      throw new Error(
+        "UNSAFE_BUILD_PATH: generated tree is too large to verify",
+      );
+    }
+    const info = await Deno.lstat(current);
+    if (info.isSymlink && current !== buildRoot) {
+      // Fontconfig can create aliases between cache files. They are safe only
+      // when the fully resolved target remains inside this generated tree.
+      let target: string;
+      try {
+        target = await Deno.realPath(current);
+      } catch {
+        throw new Error(`UNSAFE_BUILD_PATH: unresolved alias ${current}`);
+      }
+      const location = relative(buildRoot, target);
+      if (
+        isAbsolute(location) || location === ".." ||
+        location.startsWith(`..${sep}`)
+      ) {
+        throw new Error(`UNSAFE_BUILD_PATH: external alias ${current}`);
+      }
+      continue;
+    }
+    if (
+      info.isSymlink || !(info.isDirectory || info.isFile) ||
+      (info.isFile && (info.nlink === null || info.nlink > 1))
+    ) {
+      throw new Error(
+        `UNSAFE_BUILD_PATH: Quarto output must contain only private files and real directories (${current})`,
+      );
+    }
+    if (info.isDirectory) {
+      for await (const entry of Deno.readDir(current)) {
+        pending.push(resolve(current, entry.name));
+      }
+    }
+  }
+}
+export async function executeQuarto(
+  source: string,
+  buildDir: string,
+): Promise<Ast> {
+  source = resolve(source);
+  buildDir = resolve(buildDir);
+  await Deno.mkdir(buildDir, { recursive: true });
+  await assertPrivateBuild(buildDir);
+  if (!(await Deno.lstat(buildDir)).isDirectory) {
+    throw new Error(
+      "UNSAFE_BUILD_PATH: Quarto output must be a real directory",
+    );
+  }
+  const astPath = resolve(buildDir, "executed.json");
+  try {
+    await Deno.remove(astPath);
+  } catch (e) {
+    if (!(e instanceof Deno.errors.NotFound)) throw e;
+  }
+  await assertCompatibleProducerFilters(source);
+  const capture = await prepareProducerCapture(source);
+  try {
+    const filter = fileURLToPath(new URL("./capture.lua", import.meta.url));
+    const result = await new Deno.Command("quarto", {
+      cwd: dirname(source),
+      args: [
+        "render",
+        basename(source),
+        "--to",
+        "html",
+        "--lua-filter",
+        filter,
+        "-M",
+        "theme:none",
+        "--output",
+        "quarto-intermediate.html",
+        "--output-dir",
+        buildDir,
+      ],
+      env: {
+        ...capture.env,
+        QBENTO_AST: astPath,
+        QBENTO_INTERNAL_RENDER: "1",
+        XDG_CACHE_HOME: resolve(buildDir, "cache"),
+      },
+      stdout: "piped",
+      stderr: "piped",
+    }).output();
+    await Deno.writeFile(resolve(buildDir, "quarto.stdout.log"), result.stdout);
+    await Deno.writeFile(resolve(buildDir, "quarto.stderr.log"), result.stderr);
+    if (!result.success) {
+      throw new Error(
+        `QUARTO_FAILED: ${new TextDecoder().decode(result.stderr)}`,
+      );
+    }
+    const ast = JSON.parse(await Deno.readTextFile(astPath));
+    if (!Array.isArray(ast.blocks)) {
+      throw new Error("INVALID_AST: Quarto did not emit blocks");
+    }
+    return attachProducerCapture(
+      ast,
+      capture.manifest,
+      await capture.emitted(),
+    );
+  } finally {
+    await capture.cleanup();
+  }
+}

package/distribution/runtime/src/render/registry.ts

@@ -0,0 +1,233 @@
+import { resolve } from "node:path";
+import { sha256 } from "../state/store.ts";
+import {
+  type DesignDefaults,
+  DesignError,
+  type DesignTheme,
+  type LayoutDefinition,
+  validateDesignDefaults,
+} from "./design.ts";
+
+export interface DesignRegistry {
+  schemaVersion: 1;
+  layouts?: Record<string, LayoutDefinition>;
+  themes?: Record<string, DesignTheme>;
+  activeTheme?: string;
+}
+const names = /^[a-z][a-z0-9-]{0,63}$/;
+export const MAX_DESIGN_REGISTRY_BYTES = 262144;
+const maximumBytes = MAX_DESIGN_REGISTRY_BYTES;
+function object(value: unknown): asserts value is Record<string, unknown> {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new DesignError("INVALID_DESIGN_REGISTRY", "Expected a JSON object.");
+  }
+}
+/** Versioned JSON data, never code, remote dependencies or Quarto configuration. */
+export function validateDesignRegistry(value: unknown): DesignRegistry {
+  object(value);
+  if (
+    value.schemaVersion !== 1 ||
+    Object.keys(value).some((key) =>
+      !["schemaVersion", "layouts", "themes", "activeTheme"].includes(key)
+    )
+  ) {
+    throw new DesignError(
+      "INVALID_DESIGN_REGISTRY",
+      "Expected schemaVersion 1 and only layouts/themes/activeTheme.",
+    );
+  }
+  const result: DesignRegistry = { schemaVersion: 1 };
+  if (value.layouts !== undefined) {
+    object(value.layouts);
+    if ("two-column" in value.layouts) {
+      throw new DesignError(
+        "RESERVED_LAYOUT",
+        "two-column is built in; choose a distinct custom name.",
+      );
+    }
+    result.layouts = validateDesignDefaults({
+      layouts: value.layouts as Record<string, LayoutDefinition>,
+    }).layouts;
+  }
+  if (value.themes !== undefined) {
+    object(value.themes);
+    if (Object.keys(value.themes).length > 32) {
+      throw new DesignError(
+        "INVALID_DESIGN_REGISTRY",
+        "At most 32 named themes.",
+      );
+    }
+    result.themes = Object.create(null);
+    for (const [name, theme] of Object.entries(value.themes)) {
+      object(theme);
+      if (!names.test(name)) {
+        throw new DesignError(
+          "INVALID_DESIGN_REGISTRY",
+          `Unsafe theme name: ${name}`,
+        );
+      }
+      result.themes![name] = validateDesignDefaults({
+        theme: theme as unknown as DesignTheme,
+      }).theme!;
+    }
+  }
+  if (value.activeTheme !== undefined) {
+    if (
+      typeof value.activeTheme !== "string" || !names.test(value.activeTheme) ||
+      !Object.hasOwn(result.themes ?? {}, value.activeTheme)
+    ) {
+      throw new DesignError(
+        "UNKNOWN_THEME",
+        "activeTheme must name a declared theme.",
+      );
+    }
+    result.activeTheme = value.activeTheme;
+  } else if (Object.keys(result.themes ?? {}).length) {
+    throw new DesignError(
+      "THEME_SELECTION_REQUIRED",
+      "Select activeTheme explicitly; JSON key order never selects a theme.",
+    );
+  }
+  return result;
+}
+export function registryDefaults(registry: DesignRegistry): DesignDefaults {
+  const checked = validateDesignRegistry(registry);
+  return {
+    ...(checked.layouts ? { layouts: checked.layouts } : {}),
+    ...(checked.activeTheme
+      ? { theme: checked.themes![checked.activeTheme] }
+      : {}),
+  };
+}
+async function designRegistryReady(
+  directory: string,
+  transactionToken?: string,
+): Promise<void> {
+  const stateDir = resolve(directory, ".qbento");
+  try {
+    const info = await Deno.lstat(stateDir);
+    if (info.isSymlink || !info.isDirectory) {
+      throw new DesignError(
+        "UNSAFE_DESIGN_REGISTRY",
+        ".qbento must be a real directory.",
+      );
+    }
+  } catch (error) {
+    if (error instanceof Deno.errors.NotFound) return;
+    throw error;
+  }
+  const journal = resolve(stateDir, "design-save.json");
+  try {
+    const marker = await Deno.lstat(journal);
+    if (
+      !transactionToken || marker.isSymlink || !marker.isFile ||
+      marker.size > 8192 || marker.nlink !== null && marker.nlink > 1
+    ) {
+      throw new DesignError(
+        "DESIGN_REGISTRY_RECOVERY_REQUIRED",
+        "An interrupted registry save is retained at .qbento/design-save.json. Inspect its history receipt and restore or finish the saved registry before loading or recalculating.",
+      );
+    }
+    const receipt = JSON.parse(await Deno.readTextFile(journal));
+    if (receipt.token !== transactionToken) {
+      throw new DesignError(
+        "DESIGN_REGISTRY_RECOVERY_REQUIRED",
+        "Another registry save requires recovery before loading the registry.",
+      );
+    }
+  } catch (error) {
+    if (!(error instanceof Deno.errors.NotFound)) throw error;
+  }
+}
+/** Refuse an unresolved save before other raw registry readers infer absence. */
+export async function assertDesignRegistryReady(
+  directory: string,
+): Promise<void> {
+  await designRegistryReady(directory);
+}
+async function registryBytes(
+  directory: string,
+  transactionToken?: string,
+): Promise<Uint8Array | null> {
+  await designRegistryReady(directory, transactionToken);
+  const stateDir = resolve(directory, ".qbento");
+  const path = resolve(stateDir, "design.json");
+  try {
+    const info = await Deno.lstat(path);
+    if (
+      info.isSymlink || !info.isFile || info.nlink !== null && info.nlink > 1
+    ) {
+      throw new DesignError(
+        "UNSAFE_DESIGN_REGISTRY",
+        "design.json must be a regular unlinked file.",
+      );
+    }
+    if (info.size > maximumBytes) {
+      throw new DesignError(
+        "DESIGN_REGISTRY_TOO_LARGE",
+        "design.json exceeds 256 KiB.",
+      );
+    }
+    // Fixed filename and verified directory/file prevent path or URL selection.
+    const file = await Deno.open(path, { read: true });
+    try {
+      const bytes = new Uint8Array(maximumBytes + 1);
+      let size = 0;
+      for (;;) {
+        const read = await file.read(bytes.subarray(size));
+        if (read === null) break;
+        size += read;
+        if (size > maximumBytes) {
+          throw new DesignError(
+            "DESIGN_REGISTRY_TOO_LARGE",
+            "design.json exceeds 256 KiB.",
+          );
+        }
+      }
+      return bytes.slice(0, size);
+    } finally {
+      file.close();
+    }
+  } catch (error) {
+    if (error instanceof Deno.errors.NotFound) return null;
+    throw error;
+  }
+}
+/** Preserve the complete validated registry and its exact-byte freshness token. */
+export async function readDesignRegistry(
+  directory: string,
+): Promise<{ registry: DesignRegistry; hash: string | null }> {
+  const bytes = await registryBytes(directory);
+  if (!bytes) return { registry: { schemaVersion: 1 }, hash: null };
+  let value: unknown;
+  try {
+    value = JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(bytes));
+  } catch {
+    throw new DesignError(
+      "INVALID_DESIGN_REGISTRY",
+      "design.json must contain valid UTF-8 JSON.",
+    );
+  }
+  return { registry: validateDesignRegistry(value), hash: await sha256(bytes) };
+}
+export async function loadDesignRegistry(
+  directory: string,
+): Promise<{ defaults: DesignDefaults; hash: string | null }> {
+  const snapshot = await readDesignRegistry(directory);
+  return { defaults: registryDefaults(snapshot.registry), hash: snapshot.hash };
+}
+/** CAS includes both absence and exact bytes; native sparse overrides are independent. */
+export async function assertDesignRegistryUnchanged(
+  directory: string,
+  expected: string | null,
+  transactionToken?: string,
+): Promise<void> {
+  const bytes = await registryBytes(directory, transactionToken);
+  const actual = bytes === null ? null : await sha256(bytes);
+  if (actual !== expected) {
+    throw new DesignError(
+      "DESIGN_REGISTRY_CHANGED",
+      "design.json changed during the checked operation; retry from the current registry.",
+    );
+  }
+}

package/distribution/runtime/src/render/resources.ts

@@ -0,0 +1,292 @@
+/** Bounded resource dependency inspection. No DOM, fetch, mutation or SVG repair. */
+export class ResourceDependencyError extends Error {}
+const maximum = 8 * 1024 * 1024;
+// Browser schemes ignore ASCII whitespace/control characters.
+// deno-lint-ignore no-control-regex
+const controls = /[\u0000-\u0020\u007f]/g;
+function fail(reason: string): never {
+  throw new ResourceDependencyError(
+    `${reason}; embed the resource in the SVG or import a self-contained local snapshot before saving`,
+  );
+}
+function entities(value: string, literalUnknown = false): string {
+  const named: Record<string, string> = {
+    amp: "&",
+    lt: "<",
+    gt: ">",
+    quot: '"',
+    apos: "'",
+    colon: ":",
+    sol: "/",
+    bsol: "\\",
+    Tab: "\t",
+    NewLine: "\n",
+    num: "#",
+    lpar: "(",
+    rpar: ")",
+    period: ".",
+    comma: ",",
+    semi: ";",
+    equals: "=",
+    percnt: "%",
+    plus: "+",
+    quest: "?",
+    commat: "@",
+  };
+  return value.replace(
+    /&(#x[0-9a-f]+|#\d+|[a-z][a-z0-9]*);?/gi,
+    (whole, name: string) => {
+      if (name.startsWith("#")) {
+        const n = name[1].toLowerCase() === "x"
+          ? parseInt(name.slice(2), 16)
+          : Number(name.slice(1));
+        if (!Number.isSafeInteger(n) || n <= 0 || n > 0x10ffff) {
+          fail(
+            "Unsupported reference entity",
+          );
+        }
+        return String.fromCodePoint(n);
+      }
+      if (!Object.hasOwn(named, name)) {
+        if (literalUnknown) return whole;
+        fail(
+          `Unsupported reference entity ${whole}`,
+        );
+      }
+      return named[name];
+    },
+  );
+}
+function cssEscapes(value: string): string {
+  return value.replace(
+    /\\(?:([0-9a-f]{1,6})(?:\r\n|[\t\n\r\f ])?|([\s\S]))/gi,
+    (_m, hex: string, char: string) => {
+      if (hex) {
+        const n = parseInt(hex, 16);
+        return n > 0 && n <= 0x10ffff ? String.fromCodePoint(n) : "\ufffd";
+      }
+      return /[\n\r\f]/.test(char) ? "" : char;
+    },
+  );
+}
+function dataSvg(value: string): string | null {
+  if (!/^data:image\/svg\+xml(?:[;,])/i.test(value)) return null;
+  const comma = value.indexOf(",");
+  if (comma < 0) fail("Malformed embedded SVG data");
+  try {
+    const header = value.slice(0, comma), payload = value.slice(comma + 1);
+    return /;base64$/i.test(header)
+      ? new TextDecoder("utf-8", { fatal: true }).decode(
+        Uint8Array.from(atob(payload), (c) => c.charCodeAt(0)),
+      )
+      : decodeURIComponent(payload);
+  } catch {
+    fail("Malformed embedded SVG data");
+  }
+}
+function reference(value: string, depth: number, navigation = false): void {
+  const target = value.trim();
+  if (!target || target.startsWith("#")) return;
+  const normalized = target.replace(controls, "");
+  if (navigation && /^https?:\/\/[^\s<>"']+$/i.test(normalized)) return;
+  const svg = dataSvg(normalized);
+  if (svg !== null) {
+    assertOfflineSvg(svg, depth + 1);
+    return;
+  }
+  if (
+    /^data:(?:image\/(?:png|jpe?g|gif|webp|avif|bmp|x-icon)|font\/(?:woff2?|ttf|otf)|application\/(?:font-woff|x-font-ttf|x-font-opentype))(?:;[^,]*)?,/i
+      .test(normalized)
+  ) return;
+  fail("External, transient or unresolved SVG resource reference");
+}
+/** Inspect CSS resources before the pinned renderer would strip declarations. */
+export function assertOfflineSvgCss(css: string, depth = 0): void {
+  if (css.length > maximum) fail("SVG CSS exceeds the inspection bound");
+  function stringEnd(start: number): number {
+    const quote = css[start];
+    let i = start + 1;
+    for (; i < css.length; i++) {
+      if (css[i] === "\\") {
+        i++;
+        continue;
+      }
+      if (css[i] === quote) return i;
+    }
+    fail("Unclosed SVG CSS string");
+  }
+  function skipTrivia(start: number): number {
+    let i = start;
+    while (i < css.length) {
+      if (/\s/.test(css[i])) {
+        i++;
+        continue;
+      }
+      if (css.startsWith("/*", i)) {
+        const end = css.indexOf("*/", i + 2);
+        if (end < 0) return css.length;
+        i = end + 2;
+        continue;
+      }
+      break;
+    }
+    return i;
+  }
+  const identifier =
+    /^(?:[-\w]|\\(?:[0-9a-f]{1,6}(?:\r\n|[\t\n\r\f ])?|[\s\S]))+/i;
+  let i = 0;
+  while (i < css.length) {
+    i = skipTrivia(i);
+    if (i >= css.length) break;
+    if (css[i] === '"' || css[i] === "'") {
+      i = stringEnd(i) + 1;
+      continue;
+    }
+    const at = css[i] === "@";
+    if (at) i++;
+    const match = identifier.exec(css.slice(i));
+    if (!match) {
+      i++;
+      continue;
+    }
+    const name = cssEscapes(match[0]).toLowerCase();
+    i += match[0].length;
+    if (at && name === "import") fail("SVG CSS imports another stylesheet");
+    const open = skipTrivia(i);
+    if (css[open] !== "(") continue;
+    if (
+      [
+        "image-set",
+        "-webkit-image-set",
+        "image",
+        "cross-fade",
+        "-webkit-cross-fade",
+        "paint",
+      ].includes(name)
+    ) {
+      fail(
+        "SVG CSS image/resource functions require a self-contained snapshot",
+      );
+    }
+    if (name !== "url") continue;
+    const start = skipTrivia(open + 1);
+    let end: number;
+    if (css[start] === '"' || css[start] === "'") {
+      end = stringEnd(start);
+      const target = cssEscapes(css.slice(start + 1, end));
+      i = skipTrivia(end + 1);
+      if (css[i] !== ")") fail("Malformed SVG CSS resource reference");
+      reference(target, depth);
+    } else {
+      end = start;
+      while (end < css.length) {
+        if (css[end] === "\\") {
+          end += 2;
+          continue;
+        }
+        if (css[end] === ")") break;
+        end++;
+      }
+      if (end === css.length) fail("Unclosed SVG CSS resource reference");
+      reference(cssEscapes(css.slice(start, end)), depth);
+      i = end;
+    }
+    i++;
+  }
+}
+/** Both inline SVG and asset-backed SVG use the pinned HTML SVG renderer. */
+export function assertOfflineSvg(markup: string, depth = 0): void {
+  if (markup.length > maximum || depth > 4) {
+    fail("SVG exceeds the inspection size/depth bound");
+  }
+  if (!markup.trim()) return; // Native empty SVG/embed placeholders are retained.
+  if (/^\s*data:/i.test(markup)) {
+    const decoded = dataSvg(markup.trim());
+    if (decoded === null) {
+      fail("SVG view requires inline SVG markup, not a resource URL");
+    }
+    // svg.markup/embed.view are markup, not data URI inputs in pinned render.ts.
+    fail("SVG view requires decoded inline SVG markup, not a data URI");
+  }
+  if (!/<\s*svg(?:\s|\/?>)/i.test(markup)) {
+    fail("SVG view requires inline SVG markup");
+  }
+  // Entity declarations and stylesheet instructions cannot be inspected as data.
+  const declarations = markup.replace(
+    /<!--[\s\S]*?-->|<!\[CDATA\[[\s\S]*?\]\]>/g,
+    "",
+  );
+  if (
+    /<!\s*ENTITY\b|<!\s*DOCTYPE[^>]*\[|<\?xml-stylesheet\b/i.test(declarations)
+  ) {
+    fail("SVG external declarations are unsupported");
+  }
+  const tag =
+    /<!--[\s\S]*?-->|<!\[CDATA\[[\s\S]*?\]\]>|<\?[^>]*\?>|<\/?([a-z][\w:.-]*)/gi;
+  let match: RegExpExecArray | null;
+  while ((match = tag.exec(markup))) {
+    if (!match[1] || match[0].startsWith("</")) continue;
+    const name = match[1].toLowerCase();
+    let i = tag.lastIndex;
+    for (;;) {
+      while (i < markup.length && /\s/.test(markup[i])) i++;
+      if (markup[i] === "/" && markup[i + 1] === ">") {
+        i += 2;
+        break;
+      }
+      if (markup[i] === ">") {
+        i++;
+        break;
+      }
+      const attr = /^[^\s/>=]+/.exec(markup.slice(i));
+      if (!attr) fail("Malformed SVG attribute boundary");
+      const key = attr[0].toLowerCase();
+      i += attr[0].length;
+      while (i < markup.length && /\s/.test(markup[i])) i++;
+      if (markup[i] !== "=") continue;
+      i++;
+      while (i < markup.length && /\s/.test(markup[i])) i++;
+      const quote = markup[i] === '"' || markup[i] === "'" ? markup[i++] : "";
+      const start = i;
+      while (
+        i < markup.length &&
+        (quote ? markup[i] !== quote : !/[\s>]/.test(markup[i]))
+      ) i++;
+      if (i === markup.length) fail("Unclosed SVG resource attribute");
+      const raw = markup.slice(start, i);
+      if (quote) i++;
+      if (
+        ["href", "xlink:href", "src", "poster", "data", "srcset"].includes(key)
+      ) {
+        reference(
+          entities(raw, true),
+          depth,
+          name === "a" && /href$/.test(key),
+        );
+      } else if (key === "xml:base" && raw.trim()) {
+        fail("SVG base changes resource resolution");
+      } else if (
+        key === "style" || /(?:url\s*\(|\\|@)/i.test(entities(raw, true))
+      ) {
+        assertOfflineSvgCss(entities(raw, true), depth);
+      }
+    }
+    if (name === "style") {
+      const close = /<\/style\s*>/gi;
+      close.lastIndex = i;
+      const end = close.exec(markup);
+      if (!end) fail("Unclosed SVG stylesheet");
+      const css = markup.slice(i, end.index).replace(
+        /<!\[CDATA\[([\s\S]*?)\]\]>/g,
+        "$1",
+      );
+      assertOfflineSvgCss(entities(css), depth);
+    }
+    tag.lastIndex = i;
+  }
+}
+/** Raster image fields can also contain SVG data; inspect those nested bytes. */
+export function assertOfflineSvgData(uri: string): void {
+  const svg = dataSvg(uri);
+  if (svg !== null) assertOfflineSvg(svg, 1);
+}