ironmark 1.13.0 → 2.0.0

package/wasm/cli.js

@@ -1,6 +1,13 @@
 #!/usr/bin/env node
 import { readFileSync } from "node:fs";
-import { parse, parseToAst, 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"),
@@ -15,18 +22,23 @@ USAGE:
     Default format is html.
 
 OPTIONS (all formats):
-    --format <html|ansi|ast>  Output format; ast also accepts 'json' (default: html)
-    --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
+    --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)
@@ -41,6 +53,9 @@ EXAMPLES:
     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);
@@ -61,6 +76,18 @@ for (let i = 0; i < args.length; i++) {
       console.log(`ironmark ${VERSION}`);
       process.exit(0);
       break;
+    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) {
@@ -70,6 +97,18 @@ for (let i = 0; i < args.length; i++) {
       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":
       ansiOptions.color = false;
@@ -188,9 +227,9 @@ if (files.length === 0) {
 }
 
 if (fmt === "html") {
-  process.stdout.write(parse(input, parseOptions));
+  process.stdout.write(renderHtml(input, parseOptions));
 } else if (fmt === "ansi") {
-  process.stdout.write(renderAnsi(input, parseOptions, ansiOptions));
+  process.stdout.write(renderAnsiTerminal(input, parseOptions, ansiOptions));
 } else {
-  process.stdout.write(JSON.stringify(parseToAst(input, parseOptions), null, 2) + "\n");
+  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;