@jarenjs/md 0.34.0

package/src/ast.js

@@ -0,0 +1,346 @@
+//@ts-check
+/**
+ * @file The Markdown AST vocabulary: node constructors, shape guards
+ * and compiled walkers.
+ *
+ * Every node is a plain JSON object with a `type` discriminator;
+ * container nodes hold ordered content in `children`, literal nodes in
+ * `value` (normative vocabulary in docs/MD-FORMAT.md §4). The
+ * constructors exist so every node of a type is born with the same
+ * hidden class — the walkers and render tables then stay monomorphic.
+ */
+
+/** The document format version this package produces. */
+export const MD_VERSION = '0.1';
+
+/** Node types whose content lives in `children`. */
+const CONTAINER_TYPES = new Set([
+  'paragraph', 'heading', 'blockquote', 'list', 'listItem',
+  'table', 'tableRow', 'tableCell', 'footnoteDefinition',
+  'emphasis', 'strong', 'strikethrough', 'link',
+]);
+
+/**
+ * @typedef {{ type: string, [member: string]: any }} MdNode
+ */
+/**
+ * @typedef {{ $md: string, frontmatter: any, ast: MdNode[],
+ *   meta: { sourceUrl: string|null, hash: string,
+ *           frontmatterLang: 'yaml'|'json'|'toml'|null } }} MdDocument
+ */
+
+/**
+ * Does this node hold its content in `children`? Plugin/custom nodes
+ * count when they actually carry a children array.
+ * @param {MdNode} node
+ * @returns {boolean}
+ */
+export function isContainerNode(node) {
+  return CONTAINER_TYPES.has(node.type) || Array.isArray(node.children);
+}
+
+/** @param {MdNode[]} children @returns {MdNode} */
+export function paragraph(children) {
+  return { type: 'paragraph', children };
+}
+
+/** @param {number} depth @param {MdNode[]} children @returns {MdNode} */
+export function heading(depth, children) {
+  return { type: 'heading', depth, children };
+}
+
+/** @returns {MdNode} */
+export function thematicBreak() {
+  return { type: 'thematicBreak' };
+}
+
+/** @param {MdNode[]} children @returns {MdNode} */
+export function blockquote(children) {
+  return { type: 'blockquote', children };
+}
+
+/**
+ * @param {boolean} ordered
+ * @param {number|null} start
+ * @param {boolean} tight
+ * @param {MdNode[]} children
+ * @returns {MdNode}
+ */
+export function list(ordered, start, tight, children) {
+  return { type: 'list', ordered, start, tight, children };
+}
+
+/** @param {boolean|null} checked @param {MdNode[]} children @returns {MdNode} */
+export function listItem(checked, children) {
+  return { type: 'listItem', checked, children };
+}
+
+/**
+ * @param {string|null} lang
+ * @param {string|null} meta
+ * @param {string} value
+ * @returns {MdNode}
+ */
+export function code(lang, meta, value) {
+  return { type: 'code', lang, meta, value };
+}
+
+/** @param {string} value @returns {MdNode} */
+export function htmlBlock(value) {
+  return { type: 'html', value };
+}
+
+/**
+ * @param {(string|null)[]} align
+ * @param {MdNode[]} children
+ * @returns {MdNode}
+ */
+export function table(align, children) {
+  return { type: 'table', align, children };
+}
+
+/** @param {MdNode[]} children @returns {MdNode} */
+export function tableRow(children) {
+  return { type: 'tableRow', children };
+}
+
+/** @param {MdNode[]} children @returns {MdNode} */
+export function tableCell(children) {
+  return { type: 'tableCell', children };
+}
+
+/** @param {string} value @returns {MdNode} */
+export function text(value) {
+  return { type: 'text', value };
+}
+
+/** @param {MdNode[]} children @returns {MdNode} */
+export function emphasis(children) {
+  return { type: 'emphasis', children };
+}
+
+/** @param {MdNode[]} children @returns {MdNode} */
+export function strong(children) {
+  return { type: 'strong', children };
+}
+
+/** @param {MdNode[]} children @returns {MdNode} */
+export function strikethrough(children) {
+  return { type: 'strikethrough', children };
+}
+
+/**
+ * @param {string} url
+ * @param {string|null} title
+ * @param {MdNode[]} children
+ * @returns {MdNode}
+ */
+export function link(url, title, children) {
+  return { type: 'link', url, title, children };
+}
+
+/**
+ * A GFM literal autolink (`www.example.com`, `a@b.test`): a `link`, not
+ * a type of its own — every consumer, plugin and schema would otherwise
+ * have to learn a second spelling of the same thing. The `auto` flag is
+ * carried for the ONE consumer that has to tell them apart, the
+ * canonical printer, which prints it back bare (MD-FORMAT.md §4.7).
+ * @param {string} url the resolved destination (scheme inserted)
+ * @param {string} literal the text as the author wrote it
+ * @returns {MdNode}
+ */
+export function autolink(url, literal) {
+  return { type: 'link', url, title: null, children: [{ type: 'text', value: literal }], auto: true };
+}
+
+/**
+ * A GFM footnote definition: block content collected out of the flow
+ * and rendered once, at the end, if something cites it.
+ * @param {string} identifier the normalized label (matching key)
+ * @param {string} label the label as written
+ * @param {MdNode[]} children
+ * @returns {MdNode}
+ */
+export function footnoteDefinition(identifier, label, children) {
+  return { type: 'footnoteDefinition', identifier, label, children };
+}
+
+/**
+ * A GFM footnote reference: the citation mark in the text.
+ * @param {string} identifier the normalized label (matching key)
+ * @param {string} label the label as written
+ * @returns {MdNode}
+ */
+export function footnoteReference(identifier, label) {
+  return { type: 'footnoteReference', identifier, label };
+}
+
+/**
+ * @param {string} url
+ * @param {string|null} title
+ * @param {string} alt
+ * @returns {MdNode}
+ */
+export function image(url, title, alt) {
+  return { type: 'image', url, title, alt };
+}
+
+/** @param {string} value @returns {MdNode} */
+export function inlineCode(value) {
+  return { type: 'inlineCode', value };
+}
+
+/** @returns {MdNode} */
+export function hardBreak() {
+  return { type: 'break' };
+}
+
+/** @returns {MdNode} */
+export function softBreak() {
+  return { type: 'softBreak' };
+}
+
+/**
+ * The generic escape hatch for constructs without a compiled-in plugin
+ * vocabulary (MD-FORMAT §4.4).
+ * @param {string} name
+ * @param {any} data
+ * @param {MdNode[]} [children]
+ * @returns {MdNode}
+ */
+export function custom(name, data, children = undefined) {
+  return children === undefined
+    ? { type: 'custom', name, data }
+    : { type: 'custom', name, data, children };
+}
+
+/**
+ * Walk an AST (a node or an array of nodes) in document order, calling
+ * `visitor(node, parent, index)` pre-order. Returning `false` from the
+ * visitor skips the node's children.
+ *
+ * @param {MdNode | MdNode[]} root
+ * @param {(node: MdNode, parent: MdNode|null, index: number) => (boolean|void)} visitor
+ */
+export function walkAst(root, visitor) {
+  if (Array.isArray(root)) {
+    for (let i = 0; i < root.length; i++) walkNode(root[i], null, i, visitor);
+  }
+  else {
+    walkNode(root, null, 0, visitor);
+  }
+}
+
+/**
+ * @param {MdNode} node
+ * @param {MdNode|null} parent
+ * @param {number} index
+ * @param {(node: MdNode, parent: MdNode|null, index: number) => (boolean|void)} visitor
+ */
+function walkNode(node, parent, index, visitor) {
+  if (visitor(node, parent, index) === false) return;
+  const children = node.children;
+  if (Array.isArray(children)) {
+    for (let i = 0; i < children.length; i++) {
+      walkNode(children[i], node, i, visitor);
+    }
+  }
+}
+
+/**
+ * @typedef {(node: MdNode, parent: MdNode|null, index: number) => (boolean|void)} MdVisitFn
+ * @typedef {MdVisitFn | { enter?: MdVisitFn, exit?: MdVisitFn }} MdVisitSpec
+ */
+
+/**
+ * Compile a per-type visitor spec into a dispatch table and walk with
+ * it. Handlers are keyed by node type, `'*'` matches every type; a
+ * handler is a function (pre-order) or `{ enter, exit }`. An `enter`
+ * returning `false` skips the children (exit still runs).
+ *
+ * The table is built once per call — pass the same spec object to reuse
+ * the compiled form across documents (a `WeakMap` memo keeps this
+ * allocation-free on repeat visits).
+ *
+ * @param {MdNode | MdNode[]} root
+ * @param {Record<string, MdVisitSpec>} visitors
+ */
+export function visitAst(root, visitors) {
+  const table = compileVisitorTable(visitors);
+  if (Array.isArray(root)) {
+    for (let i = 0; i < root.length; i++) visitNode(root[i], null, i, table);
+  }
+  else {
+    visitNode(root, null, 0, table);
+  }
+}
+
+/** @type {WeakMap<object, { enter: Record<string, MdVisitFn>, exit: Record<string, MdVisitFn>, any: { enter: MdVisitFn|null, exit: MdVisitFn|null } }>} */
+const visitorMemo = new WeakMap();
+
+/**
+ * @param {Record<string, MdVisitSpec>} visitors
+ */
+function compileVisitorTable(visitors) {
+  let table = visitorMemo.get(visitors);
+  if (table !== undefined) return table;
+  /** @type {Record<string, MdVisitFn>} */
+  const enter = Object.create(null);
+  /** @type {Record<string, MdVisitFn>} */
+  const exit = Object.create(null);
+  const any = { enter: /** @type {MdVisitFn|null} */ (null), exit: /** @type {MdVisitFn|null} */ (null) };
+  for (const type of Object.keys(visitors)) {
+    const spec = visitors[type];
+    const enterFn = typeof spec === 'function' ? spec : spec.enter ?? null;
+    const exitFn = typeof spec === 'function' ? null : spec.exit ?? null;
+    if (type === '*') {
+      any.enter = enterFn;
+      any.exit = exitFn;
+    }
+    else {
+      if (enterFn !== null) enter[type] = enterFn;
+      if (exitFn !== null) exit[type] = exitFn;
+    }
+  }
+  table = { enter, exit, any };
+  visitorMemo.set(visitors, table);
+  return table;
+}
+
+/**
+ * @param {MdNode} node
+ * @param {MdNode|null} parent
+ * @param {number} index
+ * @param {{ enter: Record<string, MdVisitFn>, exit: Record<string, MdVisitFn>, any: { enter: MdVisitFn|null, exit: MdVisitFn|null } }} table
+ */
+function visitNode(node, parent, index, table) {
+  const enterFn = table.enter[node.type] ?? table.any.enter;
+  let descend = true;
+  if (enterFn !== null && enterFn !== undefined) {
+    descend = enterFn(node, parent, index) !== false;
+  }
+  if (descend && Array.isArray(node.children)) {
+    const children = node.children;
+    for (let i = 0; i < children.length; i++) {
+      visitNode(children[i], node, i, table);
+    }
+  }
+  const exitFn = table.exit[node.type] ?? table.any.exit;
+  if (exitFn !== null && exitFn !== undefined) exitFn(node, parent, index);
+}
+
+/**
+ * The plain-text content of a node subtree (alt-text derivation,
+ * heading slugs, search indexing).
+ * @param {MdNode | MdNode[]} root
+ * @returns {string}
+ */
+export function textOf(root) {
+  let out = '';
+  walkAst(root, (node) => {
+    if (node.type === 'text' || node.type === 'inlineCode') out += node.value;
+    else if (node.type === 'image') out += node.alt;
+    else if (node.type === 'break' || node.type === 'softBreak') out += ' ';
+  });
+  return out;
+}

package/src/bake.js

@@ -0,0 +1,104 @@
+//@ts-check
+/**
+ * @file `bake` — write a derived value back into the source text.
+ *
+ * A directive carries a value a machine derives and a human reads
+ * (directives.js). Baking materializes the current value INTO the
+ * committed file, which is the whole point: the document needs no
+ * runtime, GitHub renders it correctly, and the next re-derivation shows
+ * up as a diff a reviewer can look at instead of a number that quietly
+ * stopped being true.
+ *
+ * Two properties make it usable on documents people wrote by hand:
+ *
+ *  - **byte-local.** Only the spans between markers change. `toMarkdown`
+ *    is a canonicalizing printer, so re-printing a README would reflow
+ *    every list and re-wrap every table — correct markdown, and a diff
+ *    nobody can review. So `bake` splices the SOURCE, and a document
+ *    with no directives comes back the same bytes it went in as.
+ *  - **idempotent.** Baking an already-baked document changes nothing,
+ *    which is what lets a `--check` mode be "bake and compare".
+ *
+ * The trust level is different from mdx's, and the difference is the
+ * point: an mdx interpolation lands in a TEXT node and is never re-read
+ * as markdown, because it may carry untrusted data. A baked body is
+ * spliced into the source and WILL be re-parsed as markdown — a fact
+ * that is a whole table is exactly the use case. `bake` is therefore a
+ * build-time tool for input you control, and it says so here rather than
+ * leaving the two to be confused.
+ */
+
+import { parseMarkdown } from './parser.js';
+import { scanDirectives, scanSourceDirectives } from './directives.js';
+
+/**
+ * @typedef {{ text: string, changed: boolean, diagnostics: string[],
+ *   applied: { key: string, from: string, to: string }[] }} BakeResult
+ */
+
+/**
+ * Replace every directive body in `source` with a freshly resolved
+ * value.
+ *
+ * `resolve(key, directive)` returns the text to place between the
+ * markers, or `undefined` to leave that directive untouched. Throwing is
+ * allowed and is reported as a diagnostic — one bad derivation must not
+ * cost the rest of the document.
+ *
+ * @param {string} source the document text
+ * @param {{ ns: string, resolve: (key: string, directive: any) => (string|undefined),
+ *   parseOptions?: any }} options
+ * @returns {BakeResult}
+ */
+export function bake(source, options) {
+  const ns = options.ns;
+  const resolve = options.resolve;
+  /** @type {string[]} */
+  const diagnostics = [];
+  /** @type {{ key: string, from: string, to: string }[]} */
+  const applied = [];
+
+  const found = scanSourceDirectives(source, { ns });
+  diagnostics.push(...found.diagnostics);
+
+  // The source says where a directive lives; the PARSED DOCUMENT says
+  // whether the renderer will see one there. They disagree in exactly
+  // one situation that matters, and it is a trap worth naming loudly:
+  // a marker that BEGINS A LINE inside a paragraph opens a CommonMark
+  // HTML block, which swallows the rest of that line. The bytes still
+  // bake correctly and the file still looks right — and every renderer
+  // then drops or escapes the whole line, so the sentence the marker
+  // was carrying a number for disappears. Bake it, and say so.
+  const parsed = scanDirectives(
+    parseMarkdown(source, { ...options.parseOptions, frontmatter: false }), { ns });
+  diagnostics.push(...parsed.diagnostics.filter((d) => !found.diagnostics.includes(d)));
+  let seen = 0;
+  for (const directive of found.directives) {
+    if (seen < parsed.directives.length && parsed.directives[seen].key === directive.key) {
+      seen++;
+      continue;
+    }
+    diagnostics.push(`${directive.key}: the marker is not an inline directive in the parsed`
+      + ' document — a marker that starts a line opens an HTML block and swallows the rest'
+      + ' of that line. Put text before it, or give it a paragraph of its own.');
+  }
+
+  // right to left, so each splice leaves earlier offsets valid
+  let text = source;
+  for (let i = found.directives.length - 1; i >= 0; i--) {
+    const directive = found.directives[i];
+    let value;
+    try {
+      value = resolve(directive.key, directive);
+    }
+    catch (err) {
+      diagnostics.push(`${directive.key}: resolver threw — ${String(/** @type {any} */ (err)?.message ?? err)}`);
+      continue;
+    }
+    if (value === undefined) continue;
+    if (value === directive.body) continue;
+    applied.unshift({ key: directive.key, from: directive.body, to: value });
+    text = text.slice(0, directive.bodyStart) + value + text.slice(directive.bodyEnd);
+  }
+  return { text, changed: text !== source, diagnostics, applied };
+}

package/src/compiler.js

@@ -0,0 +1,167 @@
+//@ts-check
+/**
+ * @file compileMarkdown: parse once, then hand out specialized
+ * closures.
+ *
+ * A CompiledMd is the package's unit of work: the parsed document plus
+ * lazily-built, cached projections (vnode tree, canonical Markdown,
+ * frontmatter externals). Every projection is computed at most once
+ * per compiled document — calling `toVnode()` twice returns the same
+ * reference, which is what the view patcher's `===` fast path wants.
+ */
+
+import { parseMarkdown, buildPluginTables } from './parser.js';
+import { walkAst, visitAst } from './ast.js';
+import { toMarkdown } from './to-md.js';
+import { mdToVnode } from './to-vnode.js';
+
+/**
+ * @typedef {import('./ast.js').MdNode} MdNode
+ * @typedef {import('./ast.js').MdDocument} MdDocument
+ * @typedef {import('./parser.js').MdParseOptions} MdParseOptions
+ */
+/**
+ * @typedef {MdParseOptions & { retainSource?: boolean,
+ *   html?: 'skip'|'text', headingIds?: boolean, slugPrefix?: string,
+ *   headingAnchors?: boolean, footnotesLabel?: string,
+ *   keyed?: boolean }} MdCompileOptions
+ */
+/**
+ * The compiled closure bundle.
+ * @typedef {object} CompiledMd
+ * @property {MdDocument} doc the parsed document
+ * @property {MdNode[]} ast `doc.ast`
+ * @property {any} frontmatter `doc.frontmatter`
+ * @property {string} hash `doc.meta.hash`
+ * @property {string|null} source the source text (null when `retainSource: false`)
+ * @property {any} tables the compiled plugin tables (internal contract)
+ * @property {() => any} toVnode cached vnode projection
+ * @property {() => string} toMarkdown cached canonical Markdown
+ * @property {(visitor: any) => void} walk pre-order walker over the AST
+ * @property {(visitors: any) => void} visit compiled per-type visitor
+ * @property {() => Record<string, any>} externals frontmatter as JSLT/query externals
+ */
+
+/**
+ * Compile Markdown source (or an already-parsed MdDocument) into a
+ * closure bundle.
+ *
+ * @example
+ * const md = compileMarkdown('# Hi\n\nSome *text*.');
+ * md.toVnode();          // ['article', { class: 'md' }, ...]
+ * md.toMarkdown();       // '# Hi\n\nSome *text*.\n'
+ * md.externals();        // {} — no frontmatter
+ *
+ * @param {string | MdDocument} sourceOrDoc
+ * @param {MdCompileOptions} [options]
+ * @returns {CompiledMd}
+ */
+export function compileMarkdown(sourceOrDoc, options = {}) {
+  const fromSource = typeof sourceOrDoc === 'string';
+  const doc = fromSource
+    ? parseMarkdown(sourceOrDoc, options)
+    : sourceOrDoc;
+  const source = fromSource && options.retainSource !== false
+    ? /** @type {string} */ (sourceOrDoc)
+    : null;
+  const tables = buildPluginTables(options.plugins);
+
+  /** @type {any} */
+  let vnode;
+  /** @type {string | undefined} */
+  let markdown;
+  /** @type {Record<string, any> | undefined} */
+  let externals;
+
+  /** @type {CompiledMd} */
+  const compiled = {
+    doc,
+    ast: doc.ast,
+    frontmatter: doc.frontmatter,
+    hash: doc.meta.hash,
+    source,
+    tables,
+
+    toVnode() {
+      if (vnode === undefined) {
+        vnode = mdToVnode(compiled, {
+          plugins: options.plugins,
+          html: options.html,
+          sanitizeUrl: options.sanitizeUrl,
+          headingIds: options.headingIds,
+          slugPrefix: options.slugPrefix,
+          headingAnchors: options.headingAnchors,
+          footnotesLabel: options.footnotesLabel,
+          keyed: options.keyed,
+        });
+      }
+      return vnode;
+    },
+
+    toMarkdown() {
+      if (markdown === undefined) markdown = toMarkdown(doc);
+      return markdown;
+    },
+
+    walk(visitor) {
+      walkAst(doc.ast, visitor);
+    },
+
+    visit(visitors) {
+      visitAst(doc.ast, visitors);
+    },
+
+    externals() {
+      if (externals === undefined) externals = frontmatterExternals(doc.frontmatter);
+      return externals;
+    },
+  };
+  return compiled;
+}
+
+/**
+ * Flatten frontmatter into an externals object for the query/JSLT
+ * engines (MD-FORMAT.md §3.4). Only a frontmatter *object* contributes
+ * members; the engine-reserved names `root` and `path` are dropped.
+ * @param {any} frontmatter
+ * @returns {Record<string, any>}
+ */
+export function frontmatterExternals(frontmatter) {
+  /** @type {Record<string, any>} */
+  const out = {};
+  if (frontmatter === null || typeof frontmatter !== 'object' || Array.isArray(frontmatter)) {
+    return out;
+  }
+  for (const key of Object.keys(frontmatter)) {
+    if (key === 'root' || key === 'path') continue;
+    out[key] = frontmatter[key];
+  }
+  return out;
+}
+
+/**
+ * Emit a `@jarenjs/forms`-consumable structure from a document whose
+ * frontmatter declares a schema (`$schema` object member or `form:`
+ * key). The caller injects the forms module (or the two functions it
+ * needs) — `@jarenjs/md` stays dependency-free:
+ *
+ * @example
+ * import * as forms from '@jarenjs/forms';
+ * const form = mdToForm(md.doc, forms);
+ * // { schema, fields, data } or null when no schema is declared
+ *
+ * @param {MdDocument} doc
+ * @param {{ buildFormModel: (schema: any) => any,
+ *           createInitialData: (schema: any) => any }} forms
+ * @returns {{ schema: any, fields: any, data: any } | null}
+ */
+export function mdToForm(doc, forms) {
+  const fm = doc.frontmatter;
+  if (fm === null || typeof fm !== 'object' || Array.isArray(fm)) return null;
+  const schema = typeof fm.form === 'object' && fm.form !== null
+    ? fm.form
+    : typeof fm.$schema === 'object' && fm.$schema !== null ? fm.$schema : null;
+  if (schema === null) return null;
+  const data = fm.data !== undefined ? fm.data : forms.createInitialData(schema);
+  return { schema, fields: forms.buildFormModel(schema), data };
+}