@bendyline/squisq-formats 1.4.2 → 2.0.1

package/src/registry/types.ts

@@ -8,9 +8,25 @@
  * methods, so pulling in the registry never eagerly bundles heavy converters.
  */
 
-import type { Doc } from '@bendyline/squisq/schemas';
+import type { Doc, ThemeRegistry } from '@bendyline/squisq/schemas';
+import type { TransformStyleInput, TransformStyleRegistry } from '@bendyline/squisq/transform';
 import type { MarkdownDocument } from '@bendyline/squisq/markdown';
 import type { ContentContainer } from '@bendyline/squisq/storage';
+import type { ParseOptions, StringifyOptions } from '@bendyline/squisq/markdown';
+import type { DocxExportOptions } from '../docx/export.js';
+import type { DocxImportOptions } from '../docx/import.js';
+import type { PptxExportOptions } from '../pptx/export.js';
+import type { PptxImportOptions } from '../pptx/import.js';
+import type { XlsxExportOptions } from '../xlsx/export.js';
+import type { XlsxImportOptions } from '../xlsx/import.js';
+import type { CsvExportOptions, CsvImportOptions } from '../csv/index.js';
+import type { PdfExportOptions } from '../pdf/export.js';
+import type { PdfImportOptions } from '../pdf/import.js';
+import type { HtmlExportOptions } from '../html/htmlTemplate.js';
+import type { HtmlImportOptions } from '../html/import.js';
+import type { EpubExportOptions } from '../epub/export.js';
+import type { ContainerToZipOptions } from '../container/index.js';
+import type { ZipSafetyLimits } from '../shared/zipSafety.js';
 
 /** A format identifier (e.g. `'docx'`). Strings so hosts can register their own. */
 export type FormatId = string;
@@ -41,6 +57,33 @@ export interface ConversionResult {
   warnings: string[];
 }
 
+export interface MarkdownFormatOptions {
+  parse?: ParseOptions;
+  stringify?: StringifyOptions;
+}
+
+/** Resource limits applied when importing a DBK/ZIP container. */
+export type DbkFormatOptions = ZipSafetyLimits & ContainerToZipOptions;
+
+/**
+ * Strongly typed option bags for built-in formats. Import and export options
+ * share a bag because a single conversion may use the format on either side.
+ * Custom registries may add arbitrary keys through the intersection used by
+ * {@link ConvertOptions.formatOptions}.
+ */
+export interface BuiltinFormatOptions {
+  md: MarkdownFormatOptions;
+  docx: DocxImportOptions & DocxExportOptions;
+  pptx: PptxImportOptions & PptxExportOptions;
+  xlsx: XlsxImportOptions & XlsxExportOptions;
+  csv: CsvImportOptions & CsvExportOptions;
+  pdf: PdfImportOptions & PdfExportOptions;
+  html: HtmlImportOptions & Partial<Omit<HtmlExportOptions, 'playerScript'>>;
+  htmlzip: Partial<Omit<HtmlExportOptions, 'playerScript'>>;
+  epub: EpubExportOptions;
+  dbk: DbkFormatOptions;
+}
+
 /**
  * A source normalized into every shape an exporter might need. `doc` is always
  * present; `markdownDoc` is present when the source was markdown-shaped (an
@@ -55,22 +98,42 @@ export interface NormalizedInput {
 
 /** Options threaded through `convert()` and into every format method. */
 export interface ConvertOptions {
+  /** Cancel normalization, transformation, or export at the next bounded work boundary. */
+  signal?: AbortSignal;
   /** Registry to resolve formats against. Defaults to `defaultRegistry()`. */
   registry?: FormatRegistry;
   /** Explicit source format id (skips extension/byte sniffing). */
   from?: FormatId;
   /** Theme id to apply to the exported document. */
   themeId?: string;
-  /** Transform style id to apply before export. */
-  transformStyle?: string;
+  /** Explicit caller-owned registry for non-document custom themes. */
+  themeRegistry?: ThemeRegistry;
+  /** Built-in/registry id or call-scoped style to apply before export. */
+  transformStyle?: TransformStyleInput;
+  /** Explicit caller-owned registry used to resolve transform style ids. */
+  transformRegistry?: TransformStyleRegistry;
   /** Content-aware auto-templating when deriving a Doc from markdown. */
   autoTemplates?: boolean;
-  /** Title hint for exporters that support one (epub, html). */
+  /** Title hint for exporters that expose document metadata. */
   title?: string;
   /** Lazily resolve the standalone player IIFE bundle (required for HTML export). */
   resolvePlayerScript?: () => Promise<string>;
-  /** Per-format escape hatch for extra options. */
-  formatOptions?: Record<FormatId, Record<string, unknown>>;
+  /** Typed per-format options for built-ins; custom format ids remain extensible. */
+  formatOptions?: Partial<BuiltinFormatOptions> & Record<FormatId, unknown>;
+}
+
+/** Target-only options accepted after a source has already been normalized and transformed. */
+export type PreparedExportOptions = Pick<
+  ConvertOptions,
+  'signal' | 'title' | 'resolvePlayerScript' | 'formatOptions'
+>;
+
+/**
+ * An opaque normalized conversion snapshot. The source and transform pipeline
+ * has already completed; each call exports that same snapshot to one target.
+ */
+export interface PreparedConversion {
+  convert(to: FormatId, options?: PreparedExportOptions): Promise<ConversionResult>;
 }
 
 /** Describes how a single format imports to / exports from the squisq model. */

package/src/shared/boundedZipArchive.ts

@@ -0,0 +1,383 @@
+/** Incremental JSZip member reads governed by one shared archive budget. */
+
+import JSZip from 'jszip';
+import {
+  archiveTooLargeError,
+  assertNonNegativeFinite,
+  compressionRatio,
+  compressionRatioError,
+  entryTooLargeError,
+  resolveZipSafetyLimits,
+  throwIfZipAborted,
+  validateZipArchive,
+  tooManyEntriesError,
+  ZipSafetyError,
+  type ResolvedZipSafetyLimits,
+  type ValidatedZipEntry,
+  type ZipSafetyErrorCode,
+  type ZipSafetyLimits,
+} from './zipLimits.js';
+import { declaredZipEntryCount, prepareZipInput, type ZipInput } from './zipEntryCount.js';
+
+interface ActiveZipRead {
+  stop(error: unknown): void;
+}
+
+interface ZipChunkStream {
+  on(event: 'data', callback: (chunk: Uint8Array) => void): ZipChunkStream;
+  on(event: 'error', callback: (error: unknown) => void): ZipChunkStream;
+  on(event: 'end', callback: () => void): ZipChunkStream;
+  pause(): ZipChunkStream;
+  resume(): ZipChunkStream;
+}
+
+interface StreamableZipObject {
+  internalStream(type: 'uint8array'): ZipChunkStream;
+}
+
+/**
+ * A JSZip archive whose member reads share one actual-byte budget.
+ *
+ * JSZip's promise API accumulates a complete inflated member before returning.
+ * This wrapper instead consumes `internalStream('uint8array')`, checks every
+ * emitted chunk, and pauses every active stream as soon as any limit fails.
+ * Completed reads are cached so repeated OOXML part access is neither inflated
+ * nor charged twice.
+ */
+export interface BoundedZipArchive {
+  readonly zip: JSZip;
+  readonly entries: readonly ValidatedZipEntry[];
+  readonly emittedUncompressedBytes: number;
+  read(path: string, maxBytes?: number): Promise<Uint8Array | null>;
+  readText(path: string, maxBytes?: number): Promise<string | null>;
+  release(path: string): void;
+}
+
+class JsZipBoundedArchive implements BoundedZipArchive {
+  readonly zip: JSZip;
+  readonly entries: readonly ValidatedZipEntry[];
+
+  private readonly limits: ResolvedZipSafetyLimits;
+  private readonly entriesByPath: ReadonlyMap<string, ValidatedZipEntry>;
+  private readonly signal?: AbortSignal;
+  private readonly reads = new Map<string, Promise<Uint8Array>>();
+  private readonly activeReads = new Set<ActiveZipRead>();
+  private terminalError?: ZipSafetyError;
+  private emittedBytes = 0;
+
+  constructor(
+    zip: JSZip,
+    entries: readonly ValidatedZipEntry[],
+    limits: ResolvedZipSafetyLimits,
+    signal?: AbortSignal,
+  ) {
+    this.zip = zip;
+    this.entries = entries;
+    this.limits = limits;
+    this.signal = signal;
+    this.entriesByPath = new Map(entries.map((entry) => [entry.path, entry]));
+  }
+
+  /** Actual uncompressed bytes accepted from JSZip streams so far. */
+  get emittedUncompressedBytes(): number {
+    return this.emittedBytes;
+  }
+
+  /** Read and cache one member, returning null when it does not exist. */
+  async read(path: string, maxBytes?: number): Promise<Uint8Array | null> {
+    throwIfZipAborted(this.signal);
+    this.throwIfFailed();
+    if (maxBytes !== undefined) assertNonNegativeFinite('member read limit', maxBytes);
+    const entry = this.entriesByPath.get(path);
+    if (!entry) return null;
+
+    let pending = this.reads.get(path);
+    if (!pending) {
+      pending = this.streamEntry(entry, maxBytes);
+      this.reads.set(path, pending);
+    }
+    let bytes: Uint8Array;
+    try {
+      bytes = await pending;
+    } catch (error: unknown) {
+      // Cancellation is scoped to the current operation, not archive
+      // corruption. Do not leave a cancelled read cached for a later caller.
+      if (this.reads.get(path) === pending && !this.terminalError) this.reads.delete(path);
+      throw error;
+    }
+    throwIfZipAborted(this.signal);
+    if (maxBytes !== undefined && bytes.byteLength > maxBytes) {
+      const error = entryTooLargeError(path, bytes.byteLength, maxBytes);
+      this.failArchive(error);
+      throw error;
+    }
+    return bytes;
+  }
+
+  /** Read one UTF-8 text member, returning null when it does not exist. */
+  async readText(path: string, maxBytes?: number): Promise<string | null> {
+    const bytes = await this.read(path, maxBytes);
+    return bytes ? new TextDecoder().decode(bytes) : null;
+  }
+
+  /** Release a cached member when a sequential consumer has taken ownership. */
+  release(path: string): void {
+    this.reads.delete(path);
+  }
+
+  private streamEntry(metadata: ValidatedZipEntry, readLimit?: number): Promise<Uint8Array> {
+    throwIfZipAborted(this.signal);
+    const { path, entry, declaredSize, crc32: expectedCrc } = metadata;
+    const effectiveEntryLimit = Math.min(
+      this.limits.maxEntryUncompressedBytes,
+      readLimit ?? Number.POSITIVE_INFINITY,
+    );
+    // Never trust a declaration enough to allocate it up front. A forged
+    // 511 MiB size must not force 511 MiB of memory for a tiny member.
+    let output: Uint8Array = new Uint8Array(0);
+    let stream: ZipChunkStream;
+    try {
+      stream = (entry as unknown as StreamableZipObject).internalStream('uint8array');
+    } catch (error: unknown) {
+      const safeError = asZipSafetyError(error, path);
+      this.failArchive(safeError);
+      return Promise.reject(safeError);
+    }
+
+    return new Promise<Uint8Array>((resolve, reject) => {
+      let settled = false;
+      let written = 0;
+      let crc = 0xffffffff;
+      const removeAbortListener = (): void =>
+        this.signal?.removeEventListener('abort', handleAbort);
+      const handleAbort = (): void =>
+        controller.stop(this.signal?.reason ?? new Error('ZIP operation was cancelled'));
+
+      const controller: ActiveZipRead = {
+        stop: (error) => {
+          if (settled) return;
+          settled = true;
+          this.activeReads.delete(controller);
+          removeAbortListener();
+          // Public JSZip cancellation is cooperative. It prevents another
+          // compressed-input tick; data already emitted synchronously by the
+          // current tick is ignored because `settled` is now true.
+          try {
+            stream.pause();
+          } catch {
+            // Reject with the original safety failure even if a malformed
+            // third-party stream cannot be paused cleanly.
+          }
+          reject(error);
+        },
+      };
+      this.activeReads.add(controller);
+      if (this.signal) {
+        this.signal.addEventListener('abort', handleAbort, { once: true });
+        if (this.signal.aborted) {
+          handleAbort();
+          return;
+        }
+      }
+
+      stream
+        .on('data', (chunk: Uint8Array) => {
+          if (settled) return;
+          const nextWritten = written + chunk.byteLength;
+          try {
+            throwIfZipAborted(this.signal);
+            this.assertChunkAllowed(metadata, nextWritten, chunk.byteLength, effectiveEntryLimit);
+            output = growOutput(output, nextWritten, declaredSize, effectiveEntryLimit);
+            output.set(chunk, written);
+            written = nextWritten;
+            crc = updateCrc32(crc, chunk);
+          } catch (error: unknown) {
+            if (this.signal?.aborted) controller.stop(error);
+            else this.failArchive(asZipSafetyError(error, path));
+          }
+        })
+        .on('error', (error: unknown) => {
+          if (settled) return;
+          const message = error instanceof Error ? error.message : String(error);
+          const code: ZipSafetyErrorCode = message.includes('uncompressed data size mismatch')
+            ? 'size-mismatch'
+            : 'decompression-failed';
+          this.failArchive(
+            new ZipSafetyError(code, `ZIP import: could not decompress ${path}: ${message}`, {
+              path,
+              cause: error,
+            }),
+          );
+        })
+        .on('end', () => {
+          if (settled) return;
+          if (declaredSize !== undefined && written !== declaredSize) {
+            this.failArchive(
+              new ZipSafetyError(
+                'size-mismatch',
+                `ZIP import: archive member size does not match its metadata: ${path}.`,
+                { path, actual: written },
+              ),
+            );
+            return;
+          }
+          const actualCrc = (crc ^ 0xffffffff) >>> 0;
+          if (expectedCrc !== undefined && actualCrc !== expectedCrc >>> 0) {
+            this.failArchive(
+              new ZipSafetyError('crc-mismatch', `ZIP import: CRC32 mismatch for ${path}.`, {
+                path,
+              }),
+            );
+            return;
+          }
+
+          settled = true;
+          this.activeReads.delete(controller);
+          removeAbortListener();
+          resolve(output.byteLength === written ? output : output.slice(0, written));
+        })
+        .resume();
+    });
+  }
+
+  private assertChunkAllowed(
+    entry: ValidatedZipEntry,
+    nextEntryBytes: number,
+    chunkBytes: number,
+    effectiveEntryLimit: number,
+  ): void {
+    if (entry.declaredSize !== undefined && nextEntryBytes > entry.declaredSize) {
+      throw new ZipSafetyError(
+        'size-mismatch',
+        `ZIP import: archive member size does not match its metadata: ${entry.path}.`,
+        { path: entry.path, actual: nextEntryBytes },
+      );
+    }
+    if (
+      effectiveEntryLimit < this.limits.maxUncompressedBytes &&
+      nextEntryBytes > effectiveEntryLimit
+    ) {
+      throw entryTooLargeError(entry.path, nextEntryBytes, effectiveEntryLimit);
+    }
+
+    const nextTotal = this.emittedBytes + chunkBytes;
+    if (nextTotal > this.limits.maxUncompressedBytes) {
+      throw archiveTooLargeError(nextTotal, this.limits.maxUncompressedBytes);
+    }
+    if (nextEntryBytes > effectiveEntryLimit) {
+      throw entryTooLargeError(entry.path, nextEntryBytes, effectiveEntryLimit);
+    }
+
+    const ratio =
+      entry.compressedSize === undefined
+        ? undefined
+        : compressionRatio(nextEntryBytes, entry.compressedSize);
+    if (ratio !== undefined && ratio > this.limits.maxCompressionRatio) {
+      throw compressionRatioError(entry.path, ratio, this.limits.maxCompressionRatio);
+    }
+    this.emittedBytes = nextTotal;
+  }
+
+  private failArchive(error: ZipSafetyError): void {
+    if (this.terminalError) return;
+    this.terminalError = error;
+    for (const active of [...this.activeReads]) active.stop(error);
+  }
+
+  private throwIfFailed(): void {
+    if (this.terminalError) throw this.terminalError;
+  }
+}
+
+/** Load with JSZip, validate metadata, and create a shared bounded read session. */
+export async function openBoundedZipArchive(
+  data: ZipInput,
+  limits: ZipSafetyLimits = {},
+): Promise<BoundedZipArchive> {
+  throwIfZipAborted(limits.signal);
+  const resolved = resolveZipSafetyLimits(limits);
+  let prepared: { input: ZipInput; bytes?: Uint8Array };
+  try {
+    prepared = await prepareZipInput(data, limits.signal);
+  } catch (error: unknown) {
+    if (limits.signal?.aborted) throw limits.signal.reason ?? error;
+    throw invalidArchiveError(error);
+  }
+  throwIfZipAborted(limits.signal);
+  if (prepared.bytes) {
+    const declaredEntries = declaredZipEntryCount(prepared.bytes);
+    if (declaredEntries !== undefined && declaredEntries > resolved.maxEntries) {
+      throw tooManyEntriesError(declaredEntries, resolved.maxEntries);
+    }
+  }
+  let zip: JSZip;
+  try {
+    zip = await JSZip.loadAsync(prepared.input);
+  } catch (error: unknown) {
+    if (limits.signal?.aborted) throw limits.signal.reason ?? error;
+    throw invalidArchiveError(error);
+  }
+  throwIfZipAborted(limits.signal);
+  return createBoundedZipArchive(zip, limits);
+}
+
+function invalidArchiveError(cause: unknown): ZipSafetyError {
+  return new ZipSafetyError('invalid-archive', 'ZIP import: archive is not readable.', { cause });
+}
+
+/** Wrap an existing JSZip instance in the same validation and shared budget. */
+export function createBoundedZipArchive(
+  zip: JSZip,
+  limits: ZipSafetyLimits = {},
+): BoundedZipArchive {
+  throwIfZipAborted(limits.signal);
+  const resolved = resolveZipSafetyLimits(limits);
+  const entries = validateZipArchive(zip, limits);
+  throwIfZipAborted(limits.signal);
+  return new JsZipBoundedArchive(zip, entries, resolved, limits.signal);
+}
+
+function asZipSafetyError(error: unknown, path: string): ZipSafetyError {
+  if (error instanceof ZipSafetyError) return error;
+  return new ZipSafetyError(
+    'decompression-failed',
+    `ZIP import: could not decompress ${path}: ${error instanceof Error ? error.message : String(error)}`,
+    { path, cause: error },
+  );
+}
+
+function growOutput(
+  current: Uint8Array,
+  required: number,
+  declaredSize: number | undefined,
+  limit: number,
+): Uint8Array {
+  if (required <= current.byteLength) return current;
+  const maximum = Math.min(declaredSize ?? limit, limit);
+  const grownSize = current.byteLength === 0 ? required : current.byteLength * 2;
+  const nextSize = Math.min(maximum, Math.max(required, grownSize));
+  const next = new Uint8Array(nextSize);
+  next.set(current);
+  return next;
+}
+
+let crcTable: Uint32Array | undefined;
+
+function updateCrc32(crc: number, bytes: Uint8Array): number {
+  const table = crcTable ?? (crcTable = makeCrcTable());
+  let next = crc >>> 0;
+  for (const byte of bytes) next = table[(next ^ byte) & 0xff]! ^ (next >>> 8);
+  return next >>> 0;
+}
+
+function makeCrcTable(): Uint32Array {
+  const table = new Uint32Array(256);
+  for (let n = 0; n < table.length; n++) {
+    let value = n;
+    for (let bit = 0; bit < 8; bit++) {
+      value = (value & 1) !== 0 ? 0xedb88320 ^ (value >>> 1) : value >>> 1;
+    }
+    table[n] = value >>> 0;
+  }
+  return table;
+}

package/src/shared/fidelity.ts

@@ -0,0 +1,130 @@
+/**
+ * Shared Markdown fidelity reporting for exporters that intentionally support
+ * only a subset of the core Markdown AST. Keeping the capability profiles in
+ * one exhaustive table prevents each exporter from silently drifting as the
+ * core AST grows.
+ */
+
+import type {
+  MarkdownBlockNode,
+  MarkdownDocument,
+  MarkdownInlineNode,
+} from '@bendyline/squisq/markdown';
+
+type ContentNodeType = MarkdownBlockNode['type'] | MarkdownInlineNode['type'];
+export type MarkdownExportProfile = 'docx' | 'pdf' | 'pptx' | 'epub';
+
+/**
+ * Exhaustive by construction: adding a Markdown node type in core makes this
+ * package fail typechecking until its export fidelity is considered here.
+ */
+const CONTENT_NODE_TYPES: Record<ContentNodeType, true> = {
+  heading: true,
+  paragraph: true,
+  blockquote: true,
+  list: true,
+  code: true,
+  thematicBreak: true,
+  table: true,
+  htmlBlock: true,
+  math: true,
+  definition: true,
+  footnoteDefinition: true,
+  containerDirective: true,
+  leafDirective: true,
+  definitionList: true,
+  text: true,
+  emphasis: true,
+  strong: true,
+  delete: true,
+  inlineCode: true,
+  link: true,
+  image: true,
+  break: true,
+  htmlInline: true,
+  inlineMath: true,
+  footnoteReference: true,
+  linkReference: true,
+  imageReference: true,
+  textDirective: true,
+  mention: true,
+  inlineIcon: true,
+};
+
+const COMMON_SUPPORTED: readonly ContentNodeType[] = [
+  'heading',
+  'paragraph',
+  'blockquote',
+  'list',
+  'code',
+  'thematicBreak',
+  'table',
+  'htmlBlock',
+  'math',
+  'text',
+  'emphasis',
+  'strong',
+  'delete',
+  'inlineCode',
+  'link',
+  'image',
+  'break',
+  'htmlInline',
+  'inlineMath',
+];
+
+const PROFILE_SUPPORT: Record<MarkdownExportProfile, ReadonlySet<ContentNodeType>> = {
+  docx: new Set([...COMMON_SUPPORTED, 'footnoteDefinition', 'footnoteReference']),
+  pdf: new Set([...COMMON_SUPPORTED, 'footnoteDefinition', 'footnoteReference']),
+  pptx: new Set(COMMON_SUPPORTED),
+  epub: new Set(COMMON_SUPPORTED),
+};
+
+const PROFILE_LABELS: Record<MarkdownExportProfile, string> = {
+  docx: 'DOCX',
+  pdf: 'PDF',
+  pptx: 'PPTX',
+  epub: 'EPUB',
+};
+
+interface AstLikeNode {
+  type?: string;
+  children?: unknown;
+}
+
+/** Return a user-facing warning when an exporter will omit Markdown nodes. */
+export function markdownFidelityWarnings(
+  document: MarkdownDocument,
+  profile: MarkdownExportProfile,
+): string[] {
+  const supported = PROFILE_SUPPORT[profile];
+  const omitted = new Map<ContentNodeType, number>();
+
+  const visit = (candidate: unknown): void => {
+    if (!candidate || typeof candidate !== 'object') return;
+    const node = candidate as AstLikeNode;
+    const type = node.type as ContentNodeType | undefined;
+
+    if (type && Object.prototype.hasOwnProperty.call(CONTENT_NODE_TYPES, type)) {
+      if (!supported.has(type)) {
+        // The exporter drops this whole subtree, so report the highest-fidelity
+        // boundary once instead of inflating the count with its descendants.
+        omitted.set(type, (omitted.get(type) ?? 0) + 1);
+        return;
+      }
+    }
+
+    if (Array.isArray(node.children)) {
+      for (const child of node.children) visit(child);
+    }
+  };
+
+  for (const child of document.children) visit(child);
+  if (omitted.size === 0) return [];
+
+  const total = [...omitted.values()].reduce((sum, count) => sum + count, 0);
+  const details = [...omitted].map(([type, count]) => `${type} (${count})`).join(', ');
+  return [
+    `${PROFILE_LABELS[profile]} export omitted ${total} unsupported Markdown node(s): ${details}.`,
+  ];
+}