@bendyline/squisq 2.1.0 → 2.2.0

package/src/markdown/utils.ts

@@ -1,459 +0,0 @@
-/**
- * Markdown Tree Utilities
- *
- * Helper functions for traversing and querying the MarkdownDocument tree.
- * All functions are pure and operate on the JSON node interfaces.
- */
-
-import type { MarkdownNode, MarkdownDocument, HtmlNode } from './types.js';
-import { parseHtmlToNodes } from './htmlParse.js';
-
-/**
- * Get the children of any markdown node, if it has children.
- * Returns an empty array for leaf nodes (text, code, break, etc.).
- *
- * This is useful for generic tree walking where you don't want to
- * check the specific node type.
- */
-export function getChildren(node: MarkdownNode): MarkdownNode[] {
-  if ('children' in node && Array.isArray(node.children)) {
-    return node.children as MarkdownNode[];
-  }
-  return [];
-}
-
-/**
- * Walk the markdown tree depth-first, calling the visitor for each node.
- *
- * The visitor receives the current node and its parent. Return `true`
- * from the visitor to skip the node's children (prune).
- *
- * @param node - The root node to start walking from
- * @param visitor - Called for each node; return true to skip children
- * @param parent - (internal) Parent node
- */
-export function walkMarkdownTree(
-  node: MarkdownNode,
-  visitor: (node: MarkdownNode, parent?: MarkdownNode) => void | boolean,
-  parent?: MarkdownNode,
-): void {
-  const skip = visitor(node, parent);
-  if (skip === true) return;
-
-  const children = getChildren(node);
-  for (const child of children) {
-    walkMarkdownTree(child, visitor, node);
-  }
-}
-
-/**
- * Find all nodes of a specific type in the tree.
- *
- * @param root - The document or node to search within
- * @param type - The node type to find (e.g., 'heading', 'link', 'text')
- * @returns Array of matching nodes
- *
- * @example
- * ```ts
- * const headings = findNodesByType(doc, 'heading');
- * const links = findNodesByType(doc, 'link');
- * ```
- */
-export function findNodesByType<T extends MarkdownNode>(root: MarkdownNode, type: T['type']): T[] {
-  const results: T[] = [];
-  walkMarkdownTree(root, (node) => {
-    if (node.type === type) {
-      results.push(node as T);
-    }
-  });
-  return results;
-}
-
-/**
- * Extract all plain text content from a node and its descendants.
- * Concatenates text values, ignoring formatting, links, etc.
- *
- * @param node - The node to extract text from
- * @returns Plain text content
- *
- * @example
- * ```ts
- * const heading = doc.children[0]; // { type: 'heading', children: [{ type: 'text', value: 'Hello' }] }
- * extractPlainText(heading); // 'Hello'
- * ```
- */
-export function extractPlainText(node: MarkdownNode): string {
-  if ('value' in node && typeof node.value === 'string') {
-    return node.value;
-  }
-
-  const children = getChildren(node);
-  // Preserve boundaries between block-level elements (list items, paragraphs
-  // inside list items, blockquotes) so downstream consumers like caption
-  // splitting can treat each item as a separate phrase.
-  const separator = node.type === 'list' || node.type === 'listItem' ? '\n' : '';
-  return children.map(extractPlainText).join(separator);
-}
-
-/**
- * Count the total number of nodes in the tree.
- *
- * @param node - The root node
- * @returns Total node count (including the root)
- */
-export function countNodes(node: MarkdownNode): number {
-  let count = 1;
-  const children = getChildren(node);
-  for (const child of children) {
-    count += countNodes(child);
-  }
-  return count;
-}
-
-/**
- * Parse a YAML frontmatter string into a key-value record.
- *
- * Handles simple `key: value` pairs common in markdown frontmatter.
- * Values are trimmed; quoted strings have their quotes removed.
- * Returns `null` if parsing fails or the input is empty.
- *
- * @param yaml - The raw YAML string (without the `---` delimiters)
- * @returns A record of string keys to parsed values, or null
- */
-export function parseFrontmatter(yaml: string): Record<string, unknown> | null {
-  if (!yaml || !yaml.trim()) return null;
-
-  const result: Record<string, unknown> = {};
-  const lines = yaml.split('\n');
-
-  // Define keys as data properties so a frontmatter key named `__proto__`
-  // cannot invoke Object.prototype's legacy setter.
-  const assign = (key: string, value: unknown): void => {
-    Object.defineProperty(result, key, {
-      value,
-      enumerable: true,
-      configurable: true,
-      writable: true,
-    });
-  };
-
-  for (let i = 0; i < lines.length; i++) {
-    const line = lines[i];
-    const trimmed = line.trim();
-    if (!trimmed || trimmed.startsWith('#')) continue;
-
-    const colonIdx = trimmed.indexOf(':');
-    if (colonIdx < 1) continue;
-
-    const key = trimmed.slice(0, colonIdx).trim();
-    const value = trimmed.slice(colonIdx + 1).trim();
-
-    // YAML literal block scalar: `key: |` or `key: |-`. Subsequent lines
-    // that are more-indented than the key belong to the scalar; they are
-    // dedented by their common leading indent and joined with `\n`. A line
-    // at the key's indent (or less) ends the scalar. Both `|` and `|-`
-    // yield the joined string here (`|-` without a trailing newline); we do
-    // not model `|`'s trailing-newline / `+`/`-` chomping nuances beyond
-    // stripping trailing blank lines.
-    if (value === '|' || value === '|-') {
-      const keyIndent = line.length - line.trimStart().length;
-      const blockLines: string[] = [];
-      let j = i + 1;
-      for (; j < lines.length; j++) {
-        const bl = lines[j];
-        if (bl.trim() === '') {
-          blockLines.push('');
-          continue;
-        }
-        const indent = bl.length - bl.trimStart().length;
-        if (indent <= keyIndent) break; // dedent ends the scalar
-        blockLines.push(bl);
-      }
-      i = j - 1; // resume the outer walk at the terminating line
-
-      // Drop trailing blank lines captured inside the scalar.
-      while (blockLines.length > 0 && blockLines[blockLines.length - 1] === '') {
-        blockLines.pop();
-      }
-
-      // Dedent by the common leading whitespace of the non-blank lines.
-      let commonIndent = Infinity;
-      for (const bl of blockLines) {
-        if (bl === '') continue;
-        commonIndent = Math.min(commonIndent, bl.length - bl.trimStart().length);
-      }
-      if (!isFinite(commonIndent)) commonIndent = 0;
-      assign(key, blockLines.map((bl) => (bl === '' ? '' : bl.slice(commonIndent))).join('\n'));
-      continue;
-    }
-
-    // Quoted scalars are always strings, even when their contents look like a
-    // number or boolean. Double-quoted values emitted by
-    // formatFrontmatterValue use JSON-compatible escaping; single-quoted YAML
-    // represents a literal quote as two consecutive quotes.
-    if (value.startsWith('"') && value.endsWith('"')) {
-      try {
-        assign(key, JSON.parse(value));
-      } catch {
-        // Be permissive for hand-authored YAML outside our formatter's subset.
-        assign(key, value.slice(1, -1));
-      }
-      continue;
-    }
-    if (value.startsWith("'") && value.endsWith("'")) {
-      assign(key, value.slice(1, -1).replace(/''/g, "'"));
-      continue;
-    }
-
-    // Parse booleans and numbers
-    if (value === 'true') {
-      assign(key, true);
-    } else if (value === 'false') {
-      assign(key, false);
-    } else if (value !== '' && !isNaN(Number(value))) {
-      assign(key, Number(value));
-    } else {
-      assign(key, value);
-    }
-  }
-
-  return Object.keys(result).length > 0 ? result : null;
-}
-
-/**
- * Format a multi-line string as a YAML literal block scalar body, i.e.
- * `|-` followed by each source line indented two spaces. Paired with
- * {@link parseFrontmatter}'s block-scalar reader so multi-line frontmatter
- * values (e.g. pretty-printed JSON payloads) round-trip. Blank lines stay
- * blank (no trailing whitespace) so the output diffs cleanly.
- */
-export function formatBlockScalar(value: string): string {
-  const body = value
-    .split('\n')
-    .map((line) => (line === '' ? '' : `  ${line}`))
-    .join('\n');
-  return `|-\n${body}`;
-}
-
-const FRONTMATTER_BLOCK_RE = /^---\r?\n([\s\S]*?)\r?\n---(\r?\n)?/;
-
-/** Quote a frontmatter scalar so it round-trips cleanly through `parseFrontmatter`. */
-export function formatFrontmatterValue(value: string | number | boolean): string {
-  if (typeof value === 'boolean' || typeof value === 'number') return String(value);
-  // Multi-line strings can't live on one line — emit a YAML literal block
-  // scalar (`|-`) that `parseFrontmatter` reads back. This carries pretty-
-  // printed JSON payloads (opt-in custom templates/themes). Single-line
-  // values keep their exact historical output below.
-  if (/[\r\n]/.test(value)) return formatBlockScalar(value.replace(/\r\n?/g, '\n'));
-  // A single-line JSON object/array literal round-trips verbatim through
-  // the line-based `parseFrontmatter` (no leading quote to strip, no
-  // newline to split on), so write it unquoted to keep it human-readable
-  // — matching how `stringifyMarkdown` emits string values. Used by the
-  // compact custom-layouts payload.
-  if (/^[{[]/.test(value) && !/[\r\n]/.test(value)) return value;
-  // Quote when needed: leading/trailing whitespace, leading punctuation that
-  // could trigger YAML modes, or values that look like reserved literals.
-  const needsQuote =
-    /^\s|\s$/.test(value) ||
-    /^[!&*?|>%@`]/.test(value) ||
-    /[:#]/.test(value) ||
-    value === '' ||
-    value === 'true' ||
-    value === 'false' ||
-    (value !== '' && !Number.isNaN(Number(value))) ||
-    (/^["']/.test(value) && /["']$/.test(value));
-  if (!needsQuote) return value;
-  // Prefer double quotes; escape any embedded double-quote / backslash.
-  const escaped = value.replace(/\\/g, '\\\\').replace(/"/g, '\\"');
-  return `"${escaped}"`;
-}
-
-/**
- * Update a markdown source string's YAML frontmatter block, applying the
- * given key/value updates. A `null` or `undefined` value removes the key.
- * If no frontmatter block exists and any non-null update is supplied, a
- * new block is prepended; if every update is a removal and no block
- * exists, the source is returned unchanged.
- *
- * Existing key order is preserved; new keys are appended in the order
- * they appear in `updates`. The simple parser used here handles plain
- * `key: value` pairs only — comments, multi-line scalars, and nested
- * structures are left untouched (we only rewrite lines whose key matches
- * one in `updates`).
- *
- * @param source - The markdown source string.
- * @param updates - Map of key → new value (or null/undefined to remove).
- * @returns The updated markdown source string.
- */
-export function setFrontmatterValues(
-  source: string,
-  updates: Record<string, string | number | boolean | null | undefined>,
-): string {
-  const updateKeys = Object.keys(updates);
-  if (updateKeys.length === 0) return source;
-
-  const match = source.match(FRONTMATTER_BLOCK_RE);
-  const handled = new Set<string>();
-
-  // Existing frontmatter block — rewrite line-by-line, preserving order.
-  if (match) {
-    const inner = match[1];
-    const lines = inner.split(/\r?\n/);
-    const newLines: string[] = [];
-
-    for (const line of lines) {
-      const trimmed = line.trim();
-      if (!trimmed || trimmed.startsWith('#')) {
-        newLines.push(line);
-        continue;
-      }
-      const colonIdx = trimmed.indexOf(':');
-      if (colonIdx < 1) {
-        newLines.push(line);
-        continue;
-      }
-      const key = trimmed.slice(0, colonIdx).trim();
-      if (!Object.prototype.hasOwnProperty.call(updates, key)) {
-        newLines.push(line);
-        continue;
-      }
-      handled.add(key);
-      const next = updates[key];
-      if (next === null || next === undefined) continue; // remove
-      newLines.push(`${key}: ${formatFrontmatterValue(next)}`);
-    }
-
-    // Append any keys that weren't already present.
-    for (const key of updateKeys) {
-      if (handled.has(key)) continue;
-      const next = updates[key];
-      if (next === null || next === undefined) continue;
-      newLines.push(`${key}: ${formatFrontmatterValue(next)}`);
-    }
-
-    // If every line got removed, drop the block entirely.
-    const nonEmpty = newLines.filter((l) => l.trim().length > 0);
-    const rest = source.slice(match[0].length);
-    if (nonEmpty.length === 0) return rest;
-    return `---\n${newLines.join('\n')}\n---\n${rest}`;
-  }
-
-  // No existing block — only create one if there's at least one non-null
-  // value to write.
-  const fresh: string[] = [];
-  for (const key of updateKeys) {
-    const next = updates[key];
-    if (next === null || next === undefined) continue;
-    fresh.push(`${key}: ${formatFrontmatterValue(next)}`);
-  }
-  if (fresh.length === 0) return source;
-  return `---\n${fresh.join('\n')}\n---\n${source}`;
-}
-
-/**
- * Create a minimal MarkdownDocument from a list of block nodes.
- * Convenience function for programmatic document construction.
- */
-export function createDocument(...children: MarkdownDocument['children']): MarkdownDocument {
-  return {
-    type: 'document',
-    children,
-  };
-}
-
-/**
- * Infer a human-readable title for a markdown document.
- *
- * Resolution order:
- *   1. `title:` value in YAML frontmatter (when present and non-empty)
- *   2. Text of the first heading found, walking top-level depth (H1, then
- *      H2, etc.) — the shallowest heading wins regardless of source order
- *
- * Returns `undefined` when no usable title is found.
- */
-export function inferDocumentTitle(doc: MarkdownDocument): string | undefined {
-  const fmTitle = doc.frontmatter?.title;
-  if (typeof fmTitle === 'string') {
-    const trimmed = fmTitle.trim();
-    if (trimmed) return trimmed;
-  }
-
-  let best: { depth: number; text: string } | null = null;
-  for (const node of doc.children) {
-    if (node.type !== 'heading') continue;
-    const text = extractPlainText(node).trim();
-    if (!text) continue;
-    if (best === null || node.depth < best.depth) {
-      best = { depth: node.depth, text };
-      if (best.depth === 1) break;
-    }
-  }
-
-  return best?.text;
-}
-
-/**
- * Read a theme id from a markdown document's frontmatter.
- *
- * Checks the editor's canonical `squisq-theme` key first, then the
- * shorter legacy aliases (`themeId`, `theme`). Returns `undefined`
- * when none of them carry a non-empty string. Centralizing the lookup
- * keeps the export pipelines (DOCX, PPTX, HTML, plain-HTML bundle) in
- * sync with whatever the editor writes — adding a new frontmatter
- * spelling later is a one-file change.
- */
-export function readFrontmatterThemeId(
-  frontmatter: Record<string, unknown> | undefined,
-): string | undefined {
-  if (!frontmatter) return undefined;
-  const keys = ['squisq-theme', 'themeId', 'theme'] as const;
-  for (const key of keys) {
-    const raw = frontmatter[key];
-    if (typeof raw === 'string') {
-      const trimmed = raw.trim();
-      if (trimmed) return trimmed;
-    }
-  }
-  return undefined;
-}
-
-/**
- * Project an inline-HTML string (as stored on `TextLayer.content.html`) down
- * to plain text — the value mirrored into `content.text` for plain consumers
- * (PDF/markdown export, search, accessibility) and the SVG `<text>` fallback.
- *
- * `<br>` and block-level tags (`p`, `div`, `h1`–`h6`, `li`, `blockquote`,
- * `pre`) become line breaks so multi-line rich content reads sensibly. Entity
- * decoding is handled by {@link parseHtmlToNodes} (parse5-backed), so this is
- * more correct than a regex tag-stripper.
- */
-export function plainTextFromInlineHtml(html: string): string {
-  const BLOCK = new Set([
-    'p',
-    'div',
-    'h1',
-    'h2',
-    'h3',
-    'h4',
-    'h5',
-    'h6',
-    'li',
-    'blockquote',
-    'pre',
-  ]);
-  const walk = (nodes: HtmlNode[]): string =>
-    nodes
-      .map((n) => {
-        if (n.type === 'htmlText') return n.value;
-        if (n.type !== 'htmlElement') return '';
-        const tag = n.tagName.toLowerCase();
-        if (tag === 'br') return '\n';
-        const inner = walk(n.children);
-        return BLOCK.has(tag) ? `${inner}\n` : inner;
-      })
-      .join('');
-  return walk(parseHtmlToNodes(html))
-    .replace(/\u00A0/g, ' ')
-    .replace(/\n{3,}/g, '\n\n')
-    .trim();
-}