@orkestrel/markdown 0.0.1

package/dist/src/core/helpers.d.ts

@@ -0,0 +1,362 @@
+import type { EmphasisNode, InlineNode, LinkNode, ListItemParts, MarkdownDocument, MarkdownHandlers, MarkdownNode, MarkdownRewriteHandler, TableAlign } from './types.js';
+/**
+ * Normalize line endings to `\n` and split a markdown document into its lines - CRLF
+ * (`\r\n`) and bare CR (`\r`) both collapse to `\n` first, so a Windows-origin
+ * document parses identically. A single trailing newline does not yield a final
+ * empty line.
+ *
+ * @param markdown - The raw markdown source
+ * @returns The document's lines, line-terminators stripped
+ */
+export declare function splitLines(markdown: string): readonly string[];
+/**
+ * The count of leading space / tab characters on `line` (a tab counts as one) - the
+ * indent that decides whether a list item's continuation belongs to the item.
+ *
+ * @param line - The line to measure
+ * @returns The number of leading space / tab characters
+ */
+export declare function leadingIndent(line: string): number;
+/**
+ * Extract an ATX heading line (`#` … `######` followed by text) into its
+ * `{ level, text }`, or `undefined` when `line` is not a heading. A run of more than 6
+ * `#`s, or `#`s not followed by whitespace + text, is not a
+ * heading; an optional closing `###` run is stripped.
+ *
+ * @param line - The candidate line
+ * @returns The heading level (1–6) and its raw inline text, or `undefined`
+ */
+export declare function extractHeading(line: string): {
+    readonly level: number;
+    readonly text: string;
+} | undefined;
+/**
+ * Extract a fenced-code opening line (```` ``` ```` or `~~~`, optionally with an info
+ * string) into its `{ marker, lang }`, or `undefined` when `line` is not a fence
+ * opener. `marker` is the exact fence run (the closer must match the same character +
+ * at least the same length); `lang` is the first word of the info string.
+ *
+ * @param line - The candidate line
+ * @returns The fence marker run and its language tag, or `undefined`
+ */
+export declare function extractFence(line: string): {
+    readonly marker: string;
+    readonly lang: string | undefined;
+} | undefined;
+/**
+ * Extract a list-item line (`-` / `*` / `+` bullet, or `1.` / `1)` ordinal, followed by
+ * a space) into its {@link ListItemParts}, or `undefined` when `line` is not a list
+ * item. `content` is the text after the marker; `marker` is the full marker-plus-space
+ * width (for measuring a continuation's indent).
+ *
+ * @param line - The candidate line
+ * @returns The list-item parts, or `undefined` when not a list item
+ */
+export declare function extractListItem(line: string): ListItemParts | undefined;
+/**
+ * Strip one level of blockquote marker (`>` plus one optional following space) from a
+ * blockquote line, so the de-quoted lines re-parse as nested blocks.
+ *
+ * @param line - A blockquote line (per {@link isQuote})
+ * @returns The line with its leading `>` (and one space) removed
+ */
+export declare function stripQuote(line: string): string;
+/**
+ * Split one GFM table row into its cell strings - outer pipes are optional, an escaped
+ * pipe (`\|`) inside a cell is NOT a separator (it becomes a literal `|`), and the
+ * empty leading / trailing cell produced by an outer `|` is dropped.
+ *
+ * @param row - The raw table row line
+ * @returns The row's cells, in column order
+ */
+export declare function splitTableRow(row: string): readonly string[];
+/**
+ * Derive the per-column {@link TableAlign} list from a GFM delimiter row - `:---`
+ * left, `---:` right, `:---:` center, `---` none.
+ *
+ * @param delimiter - The table's delimiter row
+ * @returns One alignment per column, in column order
+ */
+export declare function tableAlignments(delimiter: string): readonly TableAlign[];
+/**
+ * Whether the line at `index` starts a NEW block kind (heading / fence / thematic
+ * break / blockquote / list / table) - the paragraph collector stops at such a line
+ * so a block following a paragraph without a blank line still parses (a trusted-input
+ * caller writing a `##` heading directly under a paragraph, with no intervening blank
+ * line).
+ *
+ * @param lines - The document's lines
+ * @param index - The line index to test
+ * @returns `true` when the line begins a different block
+ */
+export declare function startsBlock(lines: readonly string[], index: number): boolean;
+/**
+ * Resolve backslash escapes in a raw string to their literal characters - used for a
+ * link `href` (which is not otherwise inline-parsed) and any plain text run.
+ *
+ * @param text - The raw text possibly carrying `\x` escapes
+ * @returns The text with escapable `\x` reduced to `x`
+ */
+export declare function unescapeText(text: string): string;
+/**
+ * Merge adjacent text nodes into one - the inline scanner emits a text node per
+ * unrecognized character, so coalescing keeps the AST clean and assertion-friendly.
+ *
+ * @param nodes - The inline nodes (possibly with adjacent text runs)
+ * @returns The nodes with consecutive text nodes concatenated
+ */
+export declare function coalesceText(nodes: readonly InlineNode[]): readonly InlineNode[];
+/**
+ * Scan an inline code span at `start` (a `` ` ``-run … a matching `` ` ``-run of the
+ * SAME length, the CommonMark rule that lets a span contain backticks). Returns the
+ * span's literal text + end index, or `undefined` when no matching closer exists (it
+ * then degrades to literal backticks).
+ *
+ * @param source - The inline source text
+ * @param start - The index of the opening backtick
+ * @param to - The exclusive end of the scan window
+ * @returns The span text + end index, or `undefined`
+ */
+export declare function scanCode(source: string, start: number, to: number): {
+    readonly value: string;
+    readonly end: number;
+} | undefined;
+/**
+ * Scan a link `[text](href)` at `start` - the text runs to a BALANCED `]`, then `(`
+ * must immediately follow and the destination runs to the matching `)` (both respect
+ * nested delimiters + escapes). Returns the link node, or `undefined` when the shape
+ * does not hold (it then degrades to a literal `[`).
+ *
+ * @param source - The inline source text
+ * @param start - The index of the opening `[`
+ * @param to - The exclusive end of the scan window
+ * @param depth - The current inline-recursion depth (defaults to 0 at the entry point);
+ *   at {@link MAX_DEPTH} the link's text children degrade to literal text instead of
+ *   recursing further
+ * @returns The parsed {@link LinkNode} + end index, or `undefined`
+ */
+export declare function scanLink(source: string, start: number, to: number, depth?: number): {
+    readonly node: LinkNode;
+    readonly end: number;
+} | undefined;
+/**
+ * Scan an emphasis run at `start` (`*` / `_`, doubled for strong) - finds the nearest
+ * matching closing run of the same marker + width, requiring non-space immediately
+ * inside both delimiters (the CommonMark flanking simplification that blocks `* x *`).
+ * Returns the emphasis node, or `undefined` when no valid closer exists (it then
+ * degrades to a literal marker).
+ *
+ * @param source - The inline source text
+ * @param start - The index of the opening marker
+ * @param to - The exclusive end of the scan window
+ * @param depth - The current inline-recursion depth (defaults to 0 at the entry point);
+ *   at {@link MAX_DEPTH} the emphasis's children degrade to literal text instead of
+ *   recursing further
+ * @returns The parsed {@link EmphasisNode} + end index, or `undefined`
+ */
+export declare function scanEmphasis(source: string, start: number, to: number, depth?: number): {
+    readonly node: EmphasisNode;
+    readonly end: number;
+} | undefined;
+/**
+ * Scan the window `[from, to)` of `source` into inline nodes - the single recursive
+ * engine the inline phase runs on (emphasis / link text recurse through it). Linear:
+ * each character is consumed once; a failed construct emits its opening character as
+ * text and advances by one, so there is no re-scan (no ReDoS).
+ *
+ * @param source - The inline source text
+ * @param from - The inclusive start of the scan window
+ * @param to - The exclusive end of the scan window
+ * @param depth - The current inline-recursion depth (defaults to 0 at the entry point);
+ *   incremented by one on every recursive descent through {@link scanLink} /
+ *   {@link scanEmphasis}. At {@link MAX_DEPTH} the window is never scanned for markup -
+ *   it emits as a single literal text node - so pathological nesting (`[[[[…`,
+ *   `****…`) cannot exhaust the call stack.
+ * @returns The parsed inline nodes (NOT yet coalesced)
+ */
+export declare function scanInline(source: string, from: number, to: number, depth?: number): readonly InlineNode[];
+/**
+ * HTML-escape text content - `&` / `<` / `>` / `"` / `'` to their entities - so text
+ * from a markdown document can never inject markup. The renderer applies this to every
+ * text run, code body, and (escaped further) attribute value.
+ *
+ * @param text - The raw text
+ * @returns The HTML-escaped text
+ */
+export declare function escapeHtml(text: string): string;
+/**
+ * Sanitize + HTML-attribute-escape a link `href` - a destination whose scheme is not
+ * in {@link SAFE_URL_SCHEMES} (notably `javascript:` / `data:` / `vbscript:`), or that
+ * is protocol-relative (`//host/path`, or a backslash variant a browser normalizes to
+ * the same effect - `\\host`, `/\host`, `\/host` - inherits whatever scheme the
+ * embedding page is served over, including an unsafe one), is dropped to an empty
+ * string; a relative / anchor / scheme-less (and non-protocol-relative) destination
+ * (including a SINGLE leading `/` or `\`) is kept;
+ * the surviving value is then HTML-escaped. Defence-in-depth against an XSS `href`,
+ * even though the input is trusted.
+ *
+ * @param href - The raw link destination
+ * @returns A safe, escaped `href` (empty when the scheme is unsafe or protocol-relative)
+ */
+export declare function sanitizeUrl(href: string): string;
+/**
+ * Render a {@link MarkdownNode} (typically a {@link MarkdownDocument}) to a safe HTML
+ * string - the recursive AST → HTML engine (headings, paragraphs, lists, GFM tables,
+ * fenced code, blockquotes, links, emphasis, inline code), escaping every text run and
+ * sanitizing every link `href`.
+ *
+ * @remarks
+ * Total: never throws. At {@link MAX_DEPTH} a value-bearing node (`text` / `codeSpan`)
+ * degrades to its escaped `value`; any other node degrades to `''` instead of
+ * recursing further, so pathologically deep input cannot exhaust the call stack. The
+ * recursive engine and its per-shape sub-steps (inline concatenation, table cell,
+ * tight list-item) are nested inner functions - the only exported surface is
+ * `renderHTML` itself.
+ *
+ * @param node - The AST node to render (a full document, or any sub-node)
+ * @returns The rendered, XSS-safe HTML string
+ *
+ * @example
+ * ```ts
+ * renderHTML({ element: 'document', children: [
+ *   { element: 'heading', level: 1, children: [{ element: 'text', value: 'Hi' }] },
+ * ] })
+ * // '<h1>Hi</h1>'
+ * ```
+ */
+export declare function renderHTML(node: MarkdownNode): string;
+/**
+ * Render a {@link MarkdownNode} to its CANONICAL markdown source - the inverse
+ * projection of `renderHTML`, and the serializer a `parse(renderMarkdown(doc))`
+ * round-trip is built on. Canonical forms: `*em*` / `**strong**` (underscore emphasis
+ * normalizes to asterisks), `- ` bullets, `N. ` sequential ordinals (from the list's
+ * `start`), `---` thematic breaks, fenced code blocks (backtick run widened past any
+ * 3+ backtick run inside the body), ATX headings, `> `-prefixed blockquote lines, GFM
+ * tables (1-space-padded cells, `\|`-escaped pipes, an alignment delimiter row), and
+ * `[text](href)` links. A `text` node's literal content is backslash-escaped wherever
+ * it would otherwise re-parse as markup (AGENTS §14 parse↔render soundness).
+ *
+ * @remarks
+ * Total: never throws. At {@link MAX_DEPTH} a value-bearing node degrades to its
+ * escaped `value`; any other node degrades to `''`. Blocks are joined by exactly one
+ * blank line; a document with zero blocks renders `''`.
+ *
+ * @param node - The AST node to render (a full document, or any sub-node)
+ * @returns The canonical markdown source
+ *
+ * @example
+ * ```ts
+ * renderMarkdown({ element: 'document', children: [
+ *   { element: 'heading', level: 2, children: [{ element: 'text', value: 'Hi' }] },
+ * ] })
+ * // '## Hi'
+ * ```
+ */
+export declare function renderMarkdown(node: MarkdownNode): string;
+/**
+ * Depth-first, pre-order, root-inclusive traversal of a {@link MarkdownNode} - yields
+ * the node itself, then recurses into its children (block children, list items, table
+ * header/row cells' inline nodes) in walk order.
+ *
+ * @remarks
+ * Total: never throws. Descent stops at {@link MAX_DEPTH} (the node at the cap is
+ * still yielded; its children are not) so pathologically deep input cannot exhaust
+ * the call stack.
+ *
+ * @param node - The AST node to walk (a full document, or any sub-node)
+ * @returns A generator yielding every visited node, pre-order
+ *
+ * @example
+ * ```ts
+ * const doc = { element: 'document', children: [{ element: 'thematicBreak' }] } as const
+ * [...walkNodes(doc)].map((node) => node.element) // ['document', 'thematicBreak']
+ * ```
+ */
+export declare function walkNodes(node: MarkdownNode): Generator<MarkdownNode>;
+/**
+ * Fold a {@link MarkdownNode} into a `T` via a total catamorphism - children are
+ * folded first (post-order), then the node's own {@link MarkdownHandler} is invoked
+ * with the already-folded children.
+ *
+ * @remarks
+ * **Table contract.** A {@link TableNode} has no single `children` array - its cells
+ * live in `header` (one inline-node list per column) and `rows` (a list of such
+ * rows). The `table` handler receives ONE folded `T` per inline node, flattened in
+ * walk order across ALL cells - every header cell's inline nodes (column order), then
+ * every body row's cells' inline nodes (row order, then column order) - and reads
+ * `node.header[c].length` / `node.rows[r][c].length` off the table node itself to
+ * recover cell boundaries within the flat list.
+ *
+ * Total: never throws. At `depth >= {@link MAX_DEPTH}` the node's handler is invoked
+ * with an empty children list instead of recursing further.
+ *
+ * @param node - The AST node to fold
+ * @param handlers - The total {@link MarkdownHandlers} table, one handler per element
+ * @param depth - The starting recursion depth (pass `0` at the entry point)
+ * @returns The folded `T`
+ *
+ * @example
+ * ```ts
+ * const countHandlers: MarkdownHandlers<number> = {
+ *   document: (_, children) => children.reduce((a, b) => a + b, 1),
+ *   // ...one handler per element, each summing its folded children
+ * }
+ * foldNode(document, countHandlers, 0) // total node count
+ * ```
+ */
+export declare function foldNode<T>(node: MarkdownNode, handlers: MarkdownHandlers<T>, depth: number): T;
+/**
+ * Rewrite a {@link MarkdownDocument} bottom-up (copy-on-write) - each node's children
+ * are rewritten first (post-order), then `rewrite` is applied to the node itself; the
+ * document ROOT is never passed to `rewrite` (the `element: 'document'` invariant
+ * always holds). A table's inline cells and a list's items ARE rewritten.
+ *
+ * @remarks
+ * Never mutates `document` - every level is rebuilt into a fresh object/array, even
+ * when `rewrite` returns its input unchanged. When `rewrite` returns a node whose
+ * `element` does not fit the slot it was called for (a block slot handed a
+ * non-{@link BlockNode}, an inline slot handed a non-{@link InlineNode}, a list-item
+ * slot handed a non-`listItem`), the ill-fitting result is discarded and the
+ * freshly-rebuilt (unrewritten-at-this-level) node is kept instead - `rewriteDocument`
+ * stays total and never produces a structurally invalid document.
+ *
+ * Descent is capped at {@link MAX_DEPTH}, the same cap {@link walkNodes} and
+ * {@link foldNode} observe: at `depth >= MAX_DEPTH` the subtree is passed through
+ * UNCHANGED (by reference, not rebuilt, and `rewrite` is not invoked on it) instead of
+ * recursing further, so a pathologically deep adopted document cannot exhaust the
+ * call stack. {@link MarkdownInterface.map} inherits this cap since it delegates here.
+ *
+ * @param document - The document AST to rewrite
+ * @param rewrite - The bottom-up {@link MarkdownRewriteHandler}
+ * @returns A new, rewritten {@link MarkdownDocument}
+ *
+ * @example
+ * ```ts
+ * rewriteDocument(document, (node) =>
+ *   node.element === 'text' ? { element: 'text', value: node.value.toUpperCase() } : node,
+ * )
+ * ```
+ */
+export declare function rewriteDocument(document: MarkdownDocument, rewrite: MarkdownRewriteHandler): MarkdownDocument;
+/**
+ * Concatenate the `value` / `code` content of every descendant text / code-span /
+ * code-block node under `node`, in walk order - the plain-text projection of an AST
+ * (search indexing, word counts, a text-only preview).
+ *
+ * @remarks
+ * Total: never throws. Descent stops at {@link MAX_DEPTH} (contributes `''` past the
+ * cap instead of recursing further).
+ *
+ * @param node - The AST node to flatten (a full document, or any sub-node)
+ * @returns The concatenated text content
+ *
+ * @example
+ * ```ts
+ * flattenText({ element: 'paragraph', children: [
+ *   { element: 'text', value: 'a ' },
+ *   { element: 'codeSpan', value: 'b' },
+ * ] })
+ * // 'a b'
+ * ```
+ */
+export declare function flattenText(node: MarkdownNode): string;

package/dist/src/core/index.d.ts

@@ -0,0 +1,8 @@
+export type * from './types.js';
+export * from './constants.js';
+export * from './helpers.js';
+export * from './parsers.js';
+export * from './shapers.js';
+export * from './validators.js';
+export * from './Markdown.js';
+export * from './factories.js';