@bendyline/squisq-formats 2.0.1 → 2.2.0

package/src/shared/zipLimits.ts

@@ -1,296 +0,0 @@
-/** ZIP safety policy, structured errors, path checks, and metadata validation. */
-
-import type JSZip from 'jszip';
-
-export interface ZipSafetyLimits {
-  /** Cooperatively cancel archive opening, validation, and member traversal. */
-  signal?: AbortSignal;
-  /** Maximum number of archive records, including directories. Default: 10,000. */
-  maxEntries?: number;
-  /** Maximum uncompressed bytes for one member. Defaults to maxUncompressedBytes. */
-  maxEntryUncompressedBytes?: number;
-  /** Maximum total uncompressed bytes across the archive. Default: 512 MiB. */
-  maxUncompressedBytes?: number;
-  /** Maximum uncompressed/compressed ratio for a member. Default: 1,000. */
-  maxCompressionRatio?: number;
-}
-
-export type ZipSafetyErrorCode =
-  | 'invalid-limit'
-  | 'invalid-archive'
-  | 'unsafe-path'
-  | 'invalid-entry-metadata'
-  | 'too-many-entries'
-  | 'entry-too-large'
-  | 'archive-too-large'
-  | 'compression-ratio-exceeded'
-  | 'size-mismatch'
-  | 'crc-mismatch'
-  | 'decompression-failed';
-
-export interface ZipSafetyErrorOptions {
-  path?: string;
-  limit?: number;
-  actual?: number;
-  cause?: unknown;
-}
-
-/** A stable, machine-readable error raised while validating or reading a ZIP. */
-export class ZipSafetyError extends Error {
-  readonly code: ZipSafetyErrorCode;
-  readonly path?: string;
-  readonly limit?: number;
-  readonly actual?: number;
-
-  constructor(code: ZipSafetyErrorCode, message: string, options: ZipSafetyErrorOptions = {}) {
-    super(message);
-    this.name = 'ZipSafetyError';
-    this.code = code;
-    this.path = options.path;
-    this.limit = options.limit;
-    this.actual = options.actual;
-    if (options.cause !== undefined) {
-      (this as Error & { cause?: unknown }).cause = options.cause;
-    }
-  }
-}
-
-export interface ValidatedZipEntry {
-  path: string;
-  entry: JSZip.JSZipObject;
-  declaredSize?: number;
-  compressedSize?: number;
-  crc32?: number;
-}
-
-export interface ResolvedZipSafetyLimits {
-  maxEntries: number;
-  maxEntryUncompressedBytes: number;
-  maxUncompressedBytes: number;
-  maxCompressionRatio: number;
-}
-
-export const DEFAULT_MAX_ZIP_ENTRIES = 10_000;
-export const DEFAULT_MAX_ZIP_UNCOMPRESSED_BYTES = 512 * 1024 * 1024;
-export const DEFAULT_MAX_ZIP_COMPRESSION_RATIO = 1_000;
-
-/**
- * Validate central-directory metadata before any member is decompressed.
- * JSZip normalizes traversal names, so inspect `unsafeOriginalName` too.
- */
-export function validateZipArchive(zip: JSZip, limits: ZipSafetyLimits = {}): ValidatedZipEntry[] {
-  throwIfZipAborted(limits.signal);
-  const resolved = resolveZipSafetyLimits(limits);
-  const files: ValidatedZipEntry[] = [];
-  let memberCount = 0;
-  let declaredTotal = 0;
-  let oversizedEntry: { path: string; actual: number; limit: number } | undefined;
-
-  zip.forEach((relativePath, entry) => {
-    throwIfZipAborted(limits.signal);
-    memberCount++;
-    if (entry.dir) return;
-    const originalPath = originalEntryPath(entry, relativePath);
-    if (!isSafeArchivePath(originalPath)) {
-      throw new ZipSafetyError(
-        'unsafe-path',
-        `ZIP import: archive contains an unsafe path: ${originalPath}.`,
-        { path: originalPath },
-      );
-    }
-
-    const metadata = compressedMetadata(entry, originalPath);
-    if (
-      metadata.uncompressedSize !== undefined &&
-      metadata.uncompressedSize > resolved.maxEntryUncompressedBytes
-    ) {
-      oversizedEntry ??= {
-        path: originalPath,
-        actual: metadata.uncompressedSize,
-        limit: resolved.maxEntryUncompressedBytes,
-      };
-    }
-
-    const ratio =
-      metadata.uncompressedSize === undefined || metadata.compressedSize === undefined
-        ? undefined
-        : compressionRatio(metadata.uncompressedSize, metadata.compressedSize);
-    if (ratio !== undefined && ratio > resolved.maxCompressionRatio) {
-      throw compressionRatioError(originalPath, ratio, resolved.maxCompressionRatio);
-    }
-
-    declaredTotal += metadata.uncompressedSize ?? 0;
-    if (!Number.isSafeInteger(declaredTotal)) throw invalidMetadataError(originalPath);
-    files.push({
-      path: relativePath,
-      entry,
-      ...(metadata.uncompressedSize !== undefined
-        ? { declaredSize: metadata.uncompressedSize }
-        : {}),
-      ...(metadata.compressedSize !== undefined ? { compressedSize: metadata.compressedSize } : {}),
-      ...(metadata.crc32 !== undefined ? { crc32: metadata.crc32 } : {}),
-    });
-  });
-
-  if (memberCount > resolved.maxEntries) {
-    throw tooManyEntriesError(memberCount, resolved.maxEntries);
-  }
-  if (declaredTotal > resolved.maxUncompressedBytes) {
-    throw archiveTooLargeError(declaredTotal, resolved.maxUncompressedBytes);
-  }
-  if (oversizedEntry) {
-    throw entryTooLargeError(oversizedEntry.path, oversizedEntry.actual, oversizedEntry.limit);
-  }
-  return files;
-}
-
-/** Preserve the caller's exact cancellation reason across ZIP/OOXML layers. */
-export function throwIfZipAborted(signal?: AbortSignal): void {
-  if (!signal?.aborted) return;
-  throw signal.reason ?? new Error('ZIP operation was cancelled');
-}
-
-/** Reject a path that could be interpreted outside an archive's logical root. */
-export function assertSafeZipPath(path: string): void {
-  if (!isSafeArchivePath(path)) {
-    throw new ZipSafetyError('unsafe-path', `ZIP archive path is unsafe: ${path}.`, { path });
-  }
-}
-
-export function resolveZipSafetyLimits(limits: ZipSafetyLimits): ResolvedZipSafetyLimits {
-  const maxEntries = limits.maxEntries ?? DEFAULT_MAX_ZIP_ENTRIES;
-  const maxUncompressedBytes = limits.maxUncompressedBytes ?? DEFAULT_MAX_ZIP_UNCOMPRESSED_BYTES;
-  const maxEntryUncompressedBytes = limits.maxEntryUncompressedBytes ?? maxUncompressedBytes;
-  const maxCompressionRatio = limits.maxCompressionRatio ?? DEFAULT_MAX_ZIP_COMPRESSION_RATIO;
-
-  assertNonNegativeInteger('maxEntries', maxEntries);
-  assertNonNegativeFinite('maxUncompressedBytes', maxUncompressedBytes);
-  assertNonNegativeFinite('maxEntryUncompressedBytes', maxEntryUncompressedBytes);
-  if (!Number.isFinite(maxCompressionRatio) || maxCompressionRatio < 1) {
-    throw invalidLimitError(
-      'maxCompressionRatio must be a finite number greater than or equal to 1',
-    );
-  }
-  return {
-    maxEntries,
-    maxEntryUncompressedBytes,
-    maxUncompressedBytes,
-    maxCompressionRatio,
-  };
-}
-
-export function assertNonNegativeFinite(name: string, value: number): void {
-  if (!Number.isFinite(value) || value < 0) {
-    throw invalidLimitError(`${name} must be a non-negative finite number`);
-  }
-}
-
-export function entryTooLargeError(path: string, actual: number, limit: number): ZipSafetyError {
-  return new ZipSafetyError(
-    'entry-too-large',
-    `ZIP import: archive member ${path} exceeds ${limit} byte per-entry limit.`,
-    { path, limit, actual },
-  );
-}
-
-export function tooManyEntriesError(actual: number, limit: number): ZipSafetyError {
-  return new ZipSafetyError(
-    'too-many-entries',
-    `ZIP import: archive has ${actual} files; limit is ${limit}.`,
-    { limit, actual },
-  );
-}
-
-export function archiveTooLargeError(actual: number, limit: number): ZipSafetyError {
-  return new ZipSafetyError(
-    'archive-too-large',
-    `ZIP import: uncompressed content exceeds ${limit} byte limit.`,
-    { limit, actual },
-  );
-}
-
-export function compressionRatioError(path: string, actual: number, limit: number): ZipSafetyError {
-  return new ZipSafetyError(
-    'compression-ratio-exceeded',
-    `ZIP import: archive member ${path} exceeds ${limit}:1 compression-ratio limit.`,
-    { path, limit, actual },
-  );
-}
-
-export function compressionRatio(uncompressedBytes: number, compressedBytes: number): number {
-  if (uncompressedBytes === 0) return 0;
-  if (compressedBytes === 0) return Number.POSITIVE_INFINITY;
-  return uncompressedBytes / compressedBytes;
-}
-
-function assertNonNegativeInteger(name: string, value: number): void {
-  if (!Number.isInteger(value) || value < 0) {
-    throw invalidLimitError(`${name} must be a non-negative integer`);
-  }
-}
-
-function invalidLimitError(detail: string): ZipSafetyError {
-  return new ZipSafetyError('invalid-limit', `ZIP import: ${detail}.`);
-}
-
-function originalEntryPath(entry: JSZip.JSZipObject, relativePath: string): string {
-  return (
-    (
-      entry as JSZip.JSZipObject & {
-        unsafeOriginalName?: string;
-      }
-    ).unsafeOriginalName ?? relativePath
-  );
-}
-
-function compressedMetadata(
-  entry: JSZip.JSZipObject,
-  path: string,
-): { uncompressedSize?: number; compressedSize?: number; crc32?: number } {
-  const data = (
-    entry as unknown as {
-      _data?: { uncompressedSize?: number; compressedSize?: number; crc32?: number };
-    }
-  )._data;
-  const uncompressedSize = data?.uncompressedSize;
-  const compressedSize = data?.compressedSize;
-  const crc32 = data?.crc32;
-  if (
-    (uncompressedSize !== undefined && !isValidMetadataInteger(uncompressedSize)) ||
-    (compressedSize !== undefined && !isValidMetadataInteger(compressedSize)) ||
-    (crc32 !== undefined && !Number.isInteger(crc32))
-  ) {
-    throw invalidMetadataError(path);
-  }
-  return {
-    ...(uncompressedSize !== undefined ? { uncompressedSize } : {}),
-    ...(compressedSize !== undefined ? { compressedSize } : {}),
-    ...(crc32 !== undefined ? { crc32 } : {}),
-  };
-}
-
-function isValidMetadataInteger(value: number): boolean {
-  return Number.isSafeInteger(value) && value >= 0;
-}
-
-function invalidMetadataError(path: string): ZipSafetyError {
-  return new ZipSafetyError(
-    'invalid-entry-metadata',
-    `ZIP import: archive member has invalid size or checksum metadata: ${path}.`,
-    { path },
-  );
-}
-
-function isSafeArchivePath(path: string): boolean {
-  const segments = path.split('/');
-  return !(
-    path.startsWith('/') ||
-    /^[a-zA-Z]:[\\/]/.test(path) ||
-    path.includes('\\') ||
-    Array.from(path).some((character) => {
-      const codePoint = character.codePointAt(0) ?? 0;
-      return codePoint < 0x20 || codePoint === 0x7f;
-    }) ||
-    segments.some((segment) => segment === '' || segment === '.' || segment === '..')
-  );
-}

package/src/shared/zipSafety.ts

@@ -1,19 +0,0 @@
-/** Stable facade for ZIP validation and bounded JSZip member reads. */
-
-export {
-  ZipSafetyError,
-  DEFAULT_MAX_ZIP_ENTRIES,
-  DEFAULT_MAX_ZIP_UNCOMPRESSED_BYTES,
-  DEFAULT_MAX_ZIP_COMPRESSION_RATIO,
-  assertSafeZipPath,
-  validateZipArchive,
-} from './zipLimits.js';
-export type {
-  ZipSafetyLimits,
-  ZipSafetyErrorCode,
-  ZipSafetyErrorOptions,
-  ValidatedZipEntry,
-} from './zipLimits.js';
-
-export { createBoundedZipArchive, openBoundedZipArchive } from './boundedZipArchive.js';
-export type { BoundedZipArchive } from './boundedZipArchive.js';

package/src/xlsx/export.ts

@@ -1,253 +0,0 @@
-/**
- * XLSX export — MarkdownDocument → SpreadsheetML (.xlsx).
- *
- * Tables-only fidelity (honestly documented): every `table` node in the
- * markdown AST becomes one worksheet; all other content (headings, prose,
- * lists, images, …) is dropped except that the nearest preceding heading is
- * used to name the sheet. This mirrors the import side (`xlsxToMarkdownDoc`),
- * which turns each worksheet grid back into a markdown table.
- *
- * Cells are emitted as inline strings (`t="inlineStr"`) so no sharedStrings
- * part is needed, except values matching a plain-number pattern, which are
- * emitted as numeric cells. The package is assembled with the shared ooxml/
- * writer (auto-generates `[Content_Types].xml` + `_rels`), so only the
- * SpreadsheetML-specific parts (workbook, worksheets, styles) are written here.
- *
- * @example
- * ```ts
- * import { parseMarkdown } from '@bendyline/squisq/markdown';
- * import { markdownDocToXlsx } from '@bendyline/squisq-formats/xlsx';
- *
- * const md = parseMarkdown('# Metrics\n\n| A | B |\n| - | - |\n| 1 | 2 |');
- * const buffer = await markdownDocToXlsx(md);
- * ```
- */
-
-import type { Doc } from '@bendyline/squisq/schemas';
-import { docToMarkdown } from '@bendyline/squisq/doc';
-import type {
-  MarkdownDocument,
-  MarkdownBlockNode,
-  MarkdownTable,
-  MarkdownTableRow,
-} from '@bendyline/squisq/markdown';
-
-import { createPackage } from '../ooxml/writer.js';
-import { xmlDeclaration, escapeXml } from '../ooxml/xmlUtils.js';
-import { extractPlainText } from '../shared/text.js';
-import {
-  NS_SML,
-  NS_R,
-  REL_OFFICE_DOCUMENT,
-  REL_STYLES,
-  REL_WORKSHEET,
-  CONTENT_TYPE_XLSX_WORKBOOK,
-  CONTENT_TYPE_XLSX_WORKSHEET,
-  CONTENT_TYPE_XLSX_STYLES,
-} from '../ooxml/namespaces.js';
-
-/**
- * Options for XLSX export.
- */
-export interface XlsxExportOptions {
-  /** Workbook title (written to core properties). */
-  title?: string;
-  /** Workbook author (written to core properties). */
-  author?: string;
-  /** Prefix used for auto-named sheets when no heading precedes a table. Default: "Sheet". */
-  sheetNamePrefix?: string;
-}
-
-interface SheetData {
-  name: string;
-  /** Grid of cell text: first row is the header. */
-  grid: string[][];
-}
-
-/** A plain integer or decimal (optionally negative) — emitted as a numeric cell. */
-const NUMERIC_RE = /^-?\d+(\.\d+)?$/;
-
-/**
- * Sanitize a candidate name into a valid, unique Excel sheet name.
- * Strips characters Excel forbids (`[]:*?/\`), caps at 31 chars, and
- * de-duplicates against already-used names by appending 2, 3, …
- */
-function sanitizeSheetName(raw: string, used: Set<string>, fallback: string): string {
-  let name = raw.replace(/[[\]:*?/\\]/g, '').trim();
-  if (name.length === 0) name = fallback;
-  name = name.slice(0, 31);
-
-  if (!used.has(name)) {
-    used.add(name);
-    return name;
-  }
-  // Dedupe: "Name", "Name2", "Name3", … keeping within the 31-char cap.
-  for (let n = 2; ; n++) {
-    const suffix = String(n);
-    const base = name.slice(0, 31 - suffix.length);
-    const candidate = `${base}${suffix}`;
-    if (!used.has(candidate)) {
-      used.add(candidate);
-      return candidate;
-    }
-  }
-}
-
-/** Convert a table node into a grid of plain-text cells. */
-function tableToGrid(table: MarkdownTable): string[][] {
-  return table.children.map((row: MarkdownTableRow) =>
-    row.children.map((cell) => extractPlainText(cell.children)),
-  );
-}
-
-/** Walk the document, pairing each table with the nearest preceding heading. */
-function collectSheets(doc: MarkdownDocument, prefix: string): SheetData[] {
-  const used = new Set<string>();
-  const sheets: SheetData[] = [];
-  let pendingHeading: string | null = null;
-
-  const visit = (nodes: MarkdownBlockNode[]): void => {
-    for (const node of nodes) {
-      if (node.type === 'heading') {
-        pendingHeading = extractPlainText(node.children);
-      } else if (node.type === 'table') {
-        const fallback = `${prefix}${sheets.length + 1}`;
-        const name = sanitizeSheetName(pendingHeading ?? fallback, used, fallback);
-        sheets.push({ name, grid: tableToGrid(node) });
-        pendingHeading = null;
-      }
-    }
-  };
-
-  visit(doc.children);
-  return sheets;
-}
-
-/** Column letters for a zero-based index (0 → "A", 26 → "AA"). */
-function columnLetter(index: number): string {
-  let n = index + 1;
-  let letters = '';
-  while (n > 0) {
-    const rem = (n - 1) % 26;
-    letters = String.fromCharCode(65 + rem) + letters;
-    n = Math.floor((n - 1) / 26);
-  }
-  return letters;
-}
-
-function cellXml(value: string, ref: string): string {
-  if (NUMERIC_RE.test(value)) {
-    return `<c r="${ref}"><v>${escapeXml(value)}</v></c>`;
-  }
-  return `<c r="${ref}" t="inlineStr"><is><t xml:space="preserve">${escapeXml(value)}</t></is></c>`;
-}
-
-function worksheetXml(grid: string[][]): string {
-  const rows: string[] = [];
-  for (let r = 0; r < grid.length; r++) {
-    const cells = grid[r]!;
-    const cellsXml = cells.map((value, c) => cellXml(value, `${columnLetter(c)}${r + 1}`)).join('');
-    rows.push(`<row r="${r + 1}">${cellsXml}</row>`);
-  }
-  return (
-    `${xmlDeclaration()}\n` +
-    `<worksheet xmlns="${NS_SML}" xmlns:r="${NS_R}">` +
-    `<sheetData>${rows.join('')}</sheetData>` +
-    `</worksheet>`
-  );
-}
-
-function workbookXml(sheets: SheetData[]): string {
-  const sheetEls = sheets
-    .map(
-      (sheet, i) =>
-        `<sheet name="${escapeXml(sheet.name)}" sheetId="${i + 1}" r:id="rId${i + 1}"/>`,
-    )
-    .join('');
-  return (
-    `${xmlDeclaration()}\n` +
-    `<workbook xmlns="${NS_SML}" xmlns:r="${NS_R}">` +
-    `<sheets>${sheetEls}</sheets>` +
-    `</workbook>`
-  );
-}
-
-/** Minimal but valid styles part (Excel expects the referenced collections to exist). */
-function stylesXml(): string {
-  return (
-    `${xmlDeclaration()}\n` +
-    `<styleSheet xmlns="${NS_SML}">` +
-    `<fonts count="1"><font><sz val="11"/><name val="Calibri"/></font></fonts>` +
-    `<fills count="1"><fill><patternFill patternType="none"/></fill></fills>` +
-    `<borders count="1"><border/></borders>` +
-    `<cellStyleXfs count="1"><xf numFmtId="0" fontId="0" fillId="0" borderId="0"/></cellStyleXfs>` +
-    `<cellXfs count="1"><xf numFmtId="0" fontId="0" fillId="0" borderId="0" xfId="0"/></cellXfs>` +
-    `</styleSheet>`
-  );
-}
-
-/**
- * Convert a MarkdownDocument to a .xlsx file (tables-only fidelity).
- *
- * Each markdown `table` becomes one worksheet; a document with no tables
- * yields a single empty sheet (a valid, openable file — never throws).
- */
-export async function markdownDocToXlsx(
-  doc: MarkdownDocument,
-  options: XlsxExportOptions = {},
-): Promise<ArrayBuffer> {
-  const prefix = options.sheetNamePrefix ?? 'Sheet';
-  let sheets = collectSheets(doc, prefix);
-
-  // Zero tables → one empty sheet so the file is still valid.
-  if (sheets.length === 0) {
-    sheets = [{ name: `${prefix}1`, grid: [] }];
-  }
-
-  const pkg = createPackage();
-
-  // Worksheets + workbook→worksheet relationships.
-  sheets.forEach((sheet, i) => {
-    const sheetPath = `xl/worksheets/sheet${i + 1}.xml`;
-    pkg.addPart(sheetPath, worksheetXml(sheet.grid), CONTENT_TYPE_XLSX_WORKSHEET);
-    pkg.addRelationship('xl/workbook.xml', {
-      id: `rId${i + 1}`,
-      type: REL_WORKSHEET,
-      target: `worksheets/sheet${i + 1}.xml`,
-    });
-  });
-
-  // Styles part (referenced after the sheet relationships).
-  pkg.addPart('xl/styles.xml', stylesXml(), CONTENT_TYPE_XLSX_STYLES);
-  pkg.addRelationship('xl/workbook.xml', {
-    id: `rId${sheets.length + 1}`,
-    type: REL_STYLES,
-    target: 'styles.xml',
-  });
-
-  // Workbook + root relationship.
-  pkg.addPart('xl/workbook.xml', workbookXml(sheets), CONTENT_TYPE_XLSX_WORKBOOK);
-  pkg.addRelationship('', {
-    id: 'rId1',
-    type: REL_OFFICE_DOCUMENT,
-    target: 'xl/workbook.xml',
-  });
-
-  if (options.title || options.author) {
-    pkg.setCoreProperties({
-      title: options.title,
-      creator: options.author,
-      created: new Date().toISOString(),
-      modified: new Date().toISOString(),
-    });
-  }
-
-  return pkg.toArrayBuffer();
-}
-
-/**
- * Convert a squisq Doc to a .xlsx file (via the markdown table model).
- */
-export async function docToXlsx(doc: Doc, options?: XlsxExportOptions): Promise<ArrayBuffer> {
-  return markdownDocToXlsx(docToMarkdown(doc), options);
-}