ironmark 1.12.3 → 2.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ironmark",
-  "version": "1.12.3",
+  "version": "2.0.0",
   "description": "Very fast markdown parser in Rust, consumable from JavaScript/TypeScript via WebAssembly",
   "keywords": [
     "markdown",

package/wasm/cli.js

@@ -1,49 +1,68 @@
 #!/usr/bin/env node
 import { readFileSync } from "node:fs";
-import { renderAnsi } from "./node.js";
+import {
+  renderHtml,
+  parseMarkdown,
+  renderAnsiTerminal,
+  getCapabilities,
+  getDefaultOptions,
+  getPresets,
+} from "./node.js";
 
 const VERSION = JSON.parse(
   readFileSync(new URL("../package.json", import.meta.url), "utf8"),
 ).version;
 
-const HELP = `ironmark — render Markdown as coloured terminal output
+const HELP = `ironmark — render Markdown in various output formats
 
 USAGE:
-    ironmark --ansi [OPTIONS] [FILE...]
+    ironmark [--format <html|ansi|ast>] [OPTIONS] [FILE...]
 
     When no FILE is given, reads from stdin. Use '-' for stdin explicitly.
+    Default format is html.
 
-OPTIONS:
-    --ansi               Render as ANSI-coloured terminal output (required)
+OPTIONS (all formats):
+    --format <html|ansi|ast>    Output format; ast also accepts 'json' (default: html)
+    --preset <name>             Apply a named option preset: default, safe, strict, llm
+    --safe                      Alias for --preset safe (disable raw HTML, enable tag filter)
+    --no-hard-breaks            Don't turn soft newlines into hard line breaks
+    --no-tables                 Disable pipe table syntax
+    --no-highlight              Disable ==highlight== syntax
+    --no-strikethrough          Disable ~~strikethrough~~ syntax
+    --no-underline              Disable ++underline++ syntax
+    --no-autolink               Disable bare URL auto-linking
+    --no-task-lists             Disable - [x] task list syntax
+    --math                      Enable $inline$ and $$display$$ math
+    --wiki-links                Enable [[wiki link]] syntax
+    --capabilities              Print machine-readable capabilities JSON and exit
+    --default-options           Print resolved default options JSON and exit
+    --list-presets              Print all preset names and their options and exit
+    -h, --help                  Print this help and exit
+    -V, --version               Print version and exit
+
+OPTIONS (ansi format only):
     --width N            Terminal column width (default: auto-detect, fallback 80)
     --no-color           Disable ANSI escape codes (plain text)
     -n, --line-numbers   Show line numbers in fenced code blocks
     --padding N          Horizontal padding on both sides of output (default: 0)
-    --no-hard-breaks     Don't turn soft newlines into hard line breaks
-    --no-tables          Disable pipe table syntax
-    --no-highlight       Disable ==highlight== syntax
-    --no-strikethrough   Disable ~~strikethrough~~ syntax
-    --no-underline       Disable ++underline++ syntax
-    --no-autolink        Disable bare URL auto-linking
-    --no-task-lists      Disable - [x] task list syntax
-    --math               Enable $inline$ and $$display$$ math
-    --wiki-links         Enable [[wiki link]] syntax
-    -h, --help           Print this help and exit
-    -V, --version        Print version and exit
 
 EXAMPLES:
-    npx ironmark --ansi README.md
-    npx ironmark --ansi --width 120 README.md
-    npx ironmark --ansi --no-color README.md | less
-    echo '# Hello' | npx ironmark --ansi
-    cat doc.md | npx ironmark --ansi --math --wiki-links
+    echo '# Hello' | npx ironmark
+    echo '# Hello' | npx ironmark --format html
+    npx ironmark --format ansi README.md
+    npx ironmark --format ast README.md
+    npx ironmark --format ansi --width 120 --no-color README.md | less
+    cat doc.md | npx ironmark --format ansi --math --wiki-links
+    npx ironmark --safe README.md
+    npx ironmark --preset llm README.md
+    npx ironmark --capabilities
 `;
 
 const args = process.argv.slice(2);
 const files = [];
 const parseOptions = {};
 const ansiOptions = {};
-let ansiMode = false;
+let format = null;
 
 for (let i = 0; i < args.length; i++) {
   switch (args[i]) {
@@ -57,8 +76,38 @@ for (let i = 0; i < args.length; i++) {
       console.log(`ironmark ${VERSION}`);
       process.exit(0);
       break;
-    case "--ansi":
-      ansiMode = true;
+    case "--capabilities":
+      process.stdout.write(JSON.stringify(getCapabilities(), null, 2) + "\n");
+      process.exit(0);
+      break;
+    case "--default-options":
+      process.stdout.write(JSON.stringify(getDefaultOptions(), null, 2) + "\n");
+      process.exit(0);
+      break;
+    case "--list-presets":
+      process.stdout.write(JSON.stringify(getPresets(), null, 2) + "\n");
+      process.exit(0);
+      break;
+    case "--format": {
+      const val = args[++i];
+      if (val === undefined) {
+        console.error("error: --format requires a value");
+        process.exit(2);
+      }
+      format = val;
+      break;
+    }
+    case "--preset": {
+      const val = args[++i];
+      if (val === undefined) {
+        console.error("error: --preset requires a value (default, safe, strict, llm)");
+        process.exit(2);
+      }
+      parseOptions.preset = val;
+      break;
+    }
+    case "--safe":
+      parseOptions.safe = true;
       break;
     case "--no-color":
     case "--no-colour":
@@ -114,7 +163,9 @@ for (let i = 0; i < args.length; i++) {
       parseOptions.enableWikiLinks = true;
       break;
     default:
-      if (args[i].startsWith("--width=")) {
+      if (args[i].startsWith("--format=")) {
+        format = args[i].slice("--format=".length);
+      } else if (args[i].startsWith("--width=")) {
         const val = Number(args[i].slice("--width=".length));
         if (Number.isNaN(val)) {
           console.error("error: --width requires a numeric value");
@@ -138,13 +189,20 @@ for (let i = 0; i < args.length; i++) {
   }
 }
 
-if (!ansiMode) {
-  console.error("error: --ansi flag is required");
+const fmt = format ?? "html";
+
+if (fmt !== "html" && fmt !== "ansi" && fmt !== "ast" && fmt !== "json") {
+  console.error(`error: unknown format '${fmt}' — use html, ansi, or ast`);
+  process.exit(2);
+}
+
+if (files.length === 0 && process.stdin.isTTY) {
+  console.error("error: no input provided");
   console.error("Run 'ironmark --help' for usage.");
   process.exit(2);
 }
 
-// Auto-detect terminal width
+// Auto-detect terminal width for ansi format
 if (ansiOptions.width === undefined) {
   ansiOptions.width = process.stdout.columns || 80;
 }
@@ -168,4 +226,10 @@ if (files.length === 0) {
   }
 }
 
-process.stdout.write(renderAnsi(input, parseOptions, ansiOptions));
+if (fmt === "html") {
+  process.stdout.write(renderHtml(input, parseOptions));
+} else if (fmt === "ansi") {
+  process.stdout.write(renderAnsiTerminal(input, parseOptions, ansiOptions));
+} else {
+  process.stdout.write(JSON.stringify(parseMarkdown(input, parseOptions), null, 2) + "\n");
+}

package/wasm/index.d.ts

@@ -1,6 +1,48 @@
+// ─── Input types ─────────────────────────────────────────────────────────────
+
 export type MarkdownInput = string | Uint8Array | ArrayBuffer | ArrayBufferView;
 
+// ─── Preset names ─────────────────────────────────────────────────────────────
+
+/**
+ * Named option presets for common use cases.
+ *
+ * - `"default"` — Default ironmark behavior; all extensions enabled.
+ * - `"safe"` — Disables raw HTML and enables the GFM tag filter. Use for untrusted input.
+ * - `"strict"` — CommonMark-only; disables extensions and restricts permissive behaviors.
+ * - `"llm"` — Deterministic, structure-first output optimized for AI pipelines and agents.
+ *   Disables autolink, wiki links, math, hard breaks, and raw HTML; enables heading IDs
+ *   and whitespace normalization.
+ */
+export type PresetName = "default" | "safe" | "strict" | "llm";
+
+// ─── Parse options ────────────────────────────────────────────────────────────
+
 export interface ParseOptions {
+  /**
+   * Apply a named preset before applying any explicit options.
+   * Explicit options always override the preset.
+   */
+  preset?: PresetName;
+
+  /**
+   * Enable safe rendering. Equivalent to `{ disableRawHtml: true, tagFilter: true }`.
+   * Explicit `disableRawHtml` / `tagFilter` values override this.
+   */
+  safe?: boolean;
+
+  /**
+   * When true, output is normalized for deterministic comparison:
+   * whitespace is collapsed and output is stable across runs.
+   */
+  deterministic?: boolean;
+
+  /**
+   * Reserved for future use. When true, the AST will include source position
+   * metadata. Has no effect in the current version.
+   */
+  stableAst?: boolean;
+
   /** When true, every newline in a paragraph becomes a hard line break (`<br />`). Default: true. */
   hardBreaks?: boolean;
   /** Enable ==highlight== syntax for `<mark>`. Default: true. */
@@ -39,37 +81,13 @@ export interface ParseOptions {
   enableLatexMath?: boolean;
 }
 
-/**
- * Initialize the WASM module.
- *
- * - **Node.js**: This is a no-op — WASM is embedded and loaded synchronously at import time.
- * - **Browser/Bundler**: Must be called (and awaited) before using `parse()`.
- *   Optionally pass a URL or `WebAssembly.Module` to override the default WASM location.
- *   Calling `init()` multiple times is safe (subsequent calls are no-ops).
- */
-export declare function init(input?: string | URL | WebAssembly.Module): Promise<void>;
+// ─── Render-specific option aliases ──────────────────────────────────────────
 
-/**
- * Parse Markdown to HTML.
- *
- * @param markdown - Markdown source (string or binary).
- * @param options - Optional parsing options.
- * @returns HTML string.
- */
-export declare function parse(markdown: MarkdownInput, options?: ParseOptions): string;
+/** Options for `renderHtml()`. Same as `ParseOptions`. */
+export type RenderHtmlOptions = ParseOptions;
 
-/**
- * Parse Markdown and return the block-level AST as a JSON string.
- *
- * @param markdown - Markdown source (string or binary).
- * @param options - Optional parsing options.
- * @returns JSON string representing the AST.
- */
-export declare function parseToAst(markdown: MarkdownInput, options?: ParseOptions): string;
+// ─── ANSI options ─────────────────────────────────────────────────────────────
 
-/**
- * Options for the ANSI terminal renderer.
- */
 export interface AnsiOptions {
   /**
    * Terminal column width for word-wrap, heading underlines, and thematic breaks.
@@ -88,99 +106,267 @@ export interface AnsiOptions {
   lineNumbers?: boolean;
   /**
    * Horizontal padding to add on both sides of every output line.
-   * The output width remains `width`; padding reduces the available text area.
    * Also adds `ceil(padding / 2)` blank lines at the top. Default: `0`.
    */
   padding?: number;
 }
 
+// ─── HTML parse options ───────────────────────────────────────────────────────
+
+export interface HtmlParseOptions {
+  /**
+   * If true, unknown HTML tags (like `<sup>`, `<sub>`, `<abbr>`) are preserved
+   * as raw HTML in the Markdown output. If false (default), unknown tags are
+   * stripped but their text content is kept.
+   */
+  preserveUnknownAsHtml?: boolean;
+}
+
+// ─── AST node types ───────────────────────────────────────────────────────────
+
+/**
+ * A single AST node. The `t` field is the type discriminant.
+ * Child nodes are in `c`; leaf text content is in `text`.
+ */
+export interface AstNode {
+  t: string;
+  c?: AstNode[];
+  text?: string;
+  [key: string]: unknown;
+}
+
+/** Parsed AST: an array of top-level block nodes returned by `parseMarkdown()`. */
+export type MarkdownAst = AstNode[];
+
+// ─── Introspection return types ───────────────────────────────────────────────
+
+export interface Capabilities {
+  astSchemaVersion: string;
+  formats: string[];
+  presets: PresetName[];
+  extensions: string[];
+  security: string[];
+}
+
+export interface HeadingInfo {
+  level: number;
+  text: string;
+  id: string;
+}
+
+export interface AstSummary {
+  blockCount: number;
+  nodeCounts: Record<string, number>;
+}
+
+// ─── Initialization ───────────────────────────────────────────────────────────
+
+/**
+ * Initialize the WASM module.
+ *
+ * - **Node.js**: no-op — WASM is embedded and loaded synchronously at import time.
+ * - **Browser/Bundler**: must be awaited before calling any other function.
+ *   Accepts a URL or `WebAssembly.Module` to override the default WASM location.
+ *   Safe to call multiple times.
+ *
+ * @example
+ * ```ts
+ * import { init, renderHtml } from "ironmark";
+ * await init();
+ * const html = renderHtml("# Hello");
+ * ```
+ */
+export declare function init(input?: string | URL | WebAssembly.Module): Promise<void>;
+
+// ─── Core API ─────────────────────────────────────────────────────────────────
+
+/**
+ * Parse Markdown and return the structured AST as a JavaScript object.
+ *
+ * The recommended entry point for AI pipelines, agents, and any workflow
+ * that needs to inspect or transform document structure.
+ *
+ * @param input - Markdown source.
+ * @param options - Optional parse options or preset.
+ * @returns Parsed AST — a JavaScript array, no `JSON.parse()` needed.
+ *
+ * @example
+ * ```ts
+ * import { parseMarkdown } from "ironmark";
+ *
+ * const ast = parseMarkdown("# Hello\n\n**World**");
+ * ```
+ *
+ * @example With a preset
+ * ```ts
+ * const ast = parseMarkdown(userInput, { preset: "llm" });
+ * ```
+ */
+export declare function parseMarkdown(input: MarkdownInput, options?: ParseOptions): MarkdownAst;
+
+/**
+ * Render Markdown to an HTML string.
+ *
+ * Use `safe: true` or `preset: "safe"` for any untrusted input.
+ *
+ * @param input - Markdown source.
+ * @param options - Optional render options.
+ * @returns HTML string.
+ *
+ * @example
+ * ```ts
+ * import { renderHtml } from "ironmark";
+ *
+ * const html = renderHtml("# Hello");
+ * const safeHtml = renderHtml(userInput, { safe: true });
+ * ```
+ */
+export declare function renderHtml(input: MarkdownInput, options?: RenderHtmlOptions): string;
+
+/**
+ * Render an AST back to a Markdown string.
+ *
+ * Pass the result of `parseMarkdown()` directly — accepts an AST object or
+ * a JSON string. Useful for normalizing Markdown or round-trip conversion.
+ *
+ * @param ast - AST from `parseMarkdown()`, or a JSON string.
+ * @returns Markdown string.
+ *
+ * @example
+ * ```ts
+ * import { parseMarkdown, renderMarkdown } from "ironmark";
+ *
+ * const ast = parseMarkdown("**Hello**");
+ * const md = renderMarkdown(ast);
+ * ```
+ */
+export declare function renderMarkdown(ast: MarkdownAst | string): string;
+
 /**
  * Render Markdown as ANSI-coloured terminal output.
  *
- * Produces a string containing ANSI 256-colour escape codes suitable for
- * display in a terminal emulator. Headings, code blocks, inline code,
- * blockquotes, tables, and inline formatting are all styled distinctly.
+ * Produces a string with ANSI 256-colour escape codes suitable for TTY display.
  *
- * @param markdown - Markdown source (string or binary).
- * @param options - Optional parse options (same flags as `parse()`).
- * @param ansiOptions - Optional ANSI rendering options (width, color, lineNumbers).
- * @returns String with ANSI escape codes (or plain text when `color: false`).
+ * @param input - Markdown source.
+ * @param options - Optional parse options.
+ * @param ansiOptions - Optional ANSI rendering options.
+ * @returns String with ANSI escape codes.
  *
  * @example
  * ```ts
- * import { renderAnsi } from "ironmark";
- * const out = renderAnsi("# Hello\n\n**bold** and `code`");
- * process.stdout.write(out);
+ * import { renderAnsiTerminal } from "ironmark";
+ *
+ * process.stdout.write(renderAnsiTerminal("# Hello\n\n**bold**"));
  * ```
  */
-export declare function renderAnsi(
-  markdown: MarkdownInput,
+export declare function renderAnsiTerminal(
+  input: MarkdownInput,
   options?: ParseOptions,
   ansiOptions?: AnsiOptions,
 ): string;
 
 /**
- * Options for HTML-to-Markdown parsing.
- */
-export interface HtmlParseOptions {
-  /**
-   * If true, unknown HTML tags (like `<sup>`, `<sub>`, `<abbr>`) are preserved
-   * as raw HTML in the Markdown output. If false (default), unknown tags are
-   * stripped but their text content is kept.
-   */
-  preserveUnknownAsHtml?: boolean;
-}
-
-/**
- * Parse an HTML string and return the AST as a JSON string.
+ * Parse an HTML string and return the AST as a JavaScript object.
  *
- * This converts HTML back into the same AST structure used by the Markdown parser,
- * enabling HTML-to-Markdown conversion.
+ * Converts HTML into the same AST structure used by the Markdown parser,
+ * enabling HTML → Markdown conversion via `renderMarkdown()`.
  *
  * @param html - HTML source string.
  * @param preserveUnknownAsHtml - If true, unknown HTML tags are preserved as raw HTML.
- * @returns JSON string representing the AST.
+ * @returns Parsed AST object.
  *
  * @example
  * ```ts
- * import { parseHtmlToAst } from "ironmark";
+ * import { parseHtmlToAst, renderMarkdown } from "ironmark";
+ *
  * const ast = parseHtmlToAst("<h1>Hello</h1><p>World</p>");
- * console.log(JSON.parse(ast));
+ * const md = renderMarkdown(ast);
  * ```
  */
-export declare function parseHtmlToAst(html: string, preserveUnknownAsHtml?: boolean): string;
+export declare function parseHtmlToAst(html: string, preserveUnknownAsHtml?: boolean): MarkdownAst;
 
 /**
  * Convert HTML to Markdown.
  *
- * This parses HTML and renders it as Markdown syntax.
- *
  * @param html - HTML source string.
- * @param preserveUnknownAsHtml - If true, unknown HTML tags are preserved as raw HTML in output.
+ * @param preserveUnknownAsHtml - If true, unknown HTML tags are preserved as raw HTML.
  * @returns Markdown string.
  *
  * @example
  * ```ts
  * import { htmlToMarkdown } from "ironmark";
+ *
  * const md = htmlToMarkdown("<p><strong>Bold</strong> text</p>");
  * // Returns: "**Bold** text"
  * ```
  */
 export declare function htmlToMarkdown(html: string, preserveUnknownAsHtml?: boolean): string;
 
+// ─── Introspection helpers ────────────────────────────────────────────────────
+
+/**
+ * Return machine-readable metadata about this ironmark build.
+ *
+ * @example
+ * ```ts
+ * import { getCapabilities } from "ironmark";
+ * const caps = getCapabilities();
+ * // { astSchemaVersion: "2", formats: [...], presets: [...], ... }
+ * ```
+ */
+export declare function getCapabilities(): Capabilities;
+
+/**
+ * Return the current AST schema version string.
+ * An increment signals a breaking change to the AST node shape.
+ */
+export declare function getAstSchemaVersion(): string;
+
+/**
+ * Return the resolved default `ParseOptions` — the effective value of every
+ * option when none are specified.
+ */
+export declare function getDefaultOptions(): Required<
+  Omit<ParseOptions, "preset" | "safe" | "deterministic" | "stableAst">
+>;
+
 /**
- * Render an AST (as JSON) to Markdown.
+ * Return all named presets and their resolved option objects.
  *
- * This takes a JSON string representing an ironmark AST and renders it as Markdown.
+ * @example
+ * ```ts
+ * import { getPresets } from "ironmark";
+ * const { llm } = getPresets();
+ * ```
+ */
+export declare function getPresets(): Record<PresetName, Partial<ParseOptions>>;
+
+// ─── Utility functions ────────────────────────────────────────────────────────
+
+/**
+ * Extract all headings from a parsed AST.
  *
- * @param astJson - JSON string representing the AST (as returned by `parseToAst` or `parseHtmlToAst`).
- * @returns Markdown string.
+ * Returns level, plain-text content, and a slugified `id` for each heading.
  *
  * @example
  * ```ts
- * import { parseToAst, renderMarkdown } from "ironmark";
- * const ast = parseToAst("# Hello\n\n**World**");
- * const md = renderMarkdown(ast);
+ * import { parseMarkdown, extractHeadings } from "ironmark";
+ *
+ * const headings = extractHeadings(parseMarkdown("# Hello\n\n## World"));
+ * // [{ level: 1, text: "Hello", id: "hello" }, { level: 2, text: "World", id: "world" }]
+ * ```
+ */
+export declare function extractHeadings(ast: MarkdownAst): HeadingInfo[];
+
+/**
+ * Summarize an AST: count top-level blocks and all node types.
+ *
+ * @example
+ * ```ts
+ * import { parseMarkdown, summarizeAst } from "ironmark";
+ *
+ * const summary = summarizeAst(parseMarkdown("# Hello\n\nA paragraph.\n\n- item"));
+ * // { blockCount: 3, nodeCounts: { Heading: 1, Paragraph: 1, List: 1, ... } }
  * ```
  */
-export declare function renderMarkdown(astJson: string): string;
+export declare function summarizeAst(ast: MarkdownAst): AstSummary;