@orkestrel/markdown 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Orkestrel
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,103 @@
+# @orkestrel/markdown
+
+A zero-surprise, types-first markdown parser — a hand-written scanner turns
+GitHub-Flavored Markdown into a typed AST (a discriminated union keyed by
+`element`), and a separate renderer projects that AST to sanitized, XSS-safe
+HTML. Total and depth-capped throughout: malformed or pathologically deep
+input degrades to literal text instead of throwing. Part of the `@orkestrel`
+line.
+
+## Install
+
+```sh
+npm install @orkestrel/markdown
+```
+
+## Requirements
+
+- Node.js >= 24
+- ESM-only (no CommonJS build)
+
+## Usage
+
+```ts
+import { createMarkdown, renderHTML } from '@orkestrel/markdown'
+
+const markdown = createMarkdown('# Hi\n\nRead the [guide](./guide.md) for more, *thanks*.')
+markdown.document
+// { element: 'document', children: [...] } — the typed, render-agnostic AST
+
+renderHTML(markdown.document)
+// '<h1>Hi</h1>\n<p>Read the <a href="./guide.md">guide</a> for more, <em>thanks</em>.</p>'
+```
+
+`createMarkdown(markdown)` (or `new Markdown(markdown)`) runs a two-phase
+parse (block phase, then inline phase) and stores the result as a stateful
+workspace's `document` — a render-agnostic `MarkdownDocument`. The workspace
+also exposes `find` / `filter` / `map` / `reduce` / `fold` / `stream` /
+iteration over the AST. `renderHTML(node)` HTML-escapes all text and
+attributes and sanitizes link `href`s (an unsafe scheme like `javascript:` or
+`data:` is dropped), so even hostile content cannot inject markup or script.
+`renderMarkdown(node)` writes canonical markdown source back out — a
+`parseDocument(renderMarkdown(doc))` round-trip always deep-equals `doc`. A
+fold projects the AST to any shape (a plain string, a DOM tree, a count)
+through one total, per-element handler table, with no writer coupling built
+in.
+
+## Validating untrusted ASTs
+
+A parsed or deserialized AST crossing a trust boundary (an RPC payload, a
+cached document) can be checked without throwing:
+
+```ts
+import { isMarkdownNode } from '@orkestrel/markdown'
+
+isMarkdownNode({ element: 'text', value: 'hi' }) // true
+isMarkdownNode({ element: 'bogus' }) // false
+```
+
+`isMarkdownNode`, `isMarkdownDocument`, `isBlockNode`, and `isInlineNode` are
+total guards — safe to call on cyclic or adversarial input, even deeply
+nested structures.
+
+## Contract-backed leaf shapes
+
+The non-recursive leaf nodes (`TextNode`, `CodeSpanNode`, `CodeBlockNode`,
+`ThematicBreakNode`) each have a compiled contract — a guard, parser, JSON
+Schema, and seeded generator from one shape declaration, built on
+`@orkestrel/contract`:
+
+```ts
+import { createTextContract } from '@orkestrel/markdown'
+
+const text = createTextContract()
+text.schema // the compiled JSON Schema
+text.generate() // a seeded, schema-valid TextNode
+```
+
+## Safety notes
+
+- `renderHTML`'s `href`s are restricted to a safe scheme allowlist (`http`,
+  `https`, `mailto`, `tel`, or scheme-less/relative/anchor links) — anything
+  else is dropped.
+- All of `renderHTML`'s rendered text and attributes are HTML-escaped.
+  `renderMarkdown` is not an HTML boundary — it writes markdown source, not
+  markup — so no HTML-escaping applies there.
+- Parsing and rendering are depth-capped (`MAX_DEPTH`); past that depth the
+  parser/writer degrades to literal text instead of recursing further or
+  throwing.
+
+## Guide
+
+For the full surface — the AST shape, the two-phase parse, GFM tables, and
+the contract-backed leaf shapes — see
+[`guides/src/markdown.md`](guides/src/markdown.md).
+
+## Package
+
+Published as a single typed entry point per the `exports` field in
+`package.json`.
+
+## License
+
+MIT © [Orkestrel](https://github.com/orkestrel) — see [LICENSE](./LICENSE).

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

@@ -0,0 +1,86 @@
+import type { BlockNode, MarkdownDocument, MarkdownHandlers, MarkdownInterface, MarkdownNode, MarkdownRewriteHandler } from './types.js';
+/**
+ * A stateful, parsed markdown document - wraps a typed {@link MarkdownDocument} AST
+ * with the query (`find` / `filter` / `reduce` / iteration), rewrite (`map`), fold, and
+ * streaming operations {@link MarkdownInterface} declares.
+ *
+ * @remarks
+ * - **Construction.** Given a `string`, the constructor runs {@link parseDocument} (the
+ *   block phase then the inline phase) to build the AST. Given a {@link MarkdownDocument},
+ *   the document is adopted AS-IS and is NOT re-validated - a caller adopting an
+ *   untrusted value should gate it with `isMarkdownDocument` first.
+ * - **Immutable.** {@link map} never mutates the stored AST - it returns a NEW `Markdown`
+ *   instance; the document root invariant (`element: 'document'`) always holds.
+ * - **Traversal order.** {@link walk} and the `find` / `filter` / `reduce` queries built
+ *   on it walk the AST depth-first, pre-order, root-inclusive (via {@link walkNodes});
+ *   `stream` is shallow - only the document's direct block children.
+ *
+ * @example
+ * ```ts
+ * import { Markdown, isHeadingNode, renderMarkdown } from '@src/core'
+ *
+ * const markdown = new Markdown('# Title\n\nA **bold** [link](https://x.dev).')
+ * const heading = markdown.find(isHeadingNode) // the HeadingNode, or undefined
+ * const shouted = markdown.map((node) =>
+ *   node.element === 'text' ? { element: 'text', value: node.value.toUpperCase() } : node,
+ * )
+ * renderMarkdown(shouted.document) // '# TITLE\n\nA **BOLD** [LINK](https://x.dev).'
+ * ```
+ */
+export declare class Markdown implements MarkdownInterface {
+    #private;
+    constructor(input: string | MarkdownDocument);
+    /** The stored {@link MarkdownDocument} AST root. */
+    get document(): MarkdownDocument;
+    /**
+     * THE deep traversal - a lazy, depth-first, pre-order, root-inclusive generator
+     * over every {@link MarkdownNode} in the document. `find` / `filter` / `reduce`
+     * all iterate this single traversal.
+     *
+     * @example
+     * ```ts
+     * for (const node of markdown.walk()) {
+     *   // every node, depth-first, pre-order, root-inclusive
+     * }
+     *
+     * // also consumable by for-await - JS accepts a sync iterable in for-await
+     * for await (const node of markdown.walk()) {
+     *   // same sequence, no separate async iterator needed
+     * }
+     * ```
+     */
+    walk(): Generator<MarkdownNode>;
+    find<T extends MarkdownNode>(guard: (node: MarkdownNode) => node is T): T | undefined;
+    find(predicate: (node: MarkdownNode) => boolean): MarkdownNode | undefined;
+    filter<T extends MarkdownNode>(guard: (node: MarkdownNode) => node is T): readonly T[];
+    filter(predicate: (node: MarkdownNode) => boolean): readonly MarkdownNode[];
+    /** Rewrites the AST bottom-up (copy-on-write) and returns a new {@link Markdown}. */
+    map(rewrite: MarkdownRewriteHandler): MarkdownInterface;
+    /** Folds the AST depth-first, pre-order into an accumulator. */
+    reduce<T>(callback: (accumulator: T, node: MarkdownNode) => T, initial: T): T;
+    /** Runs a total catamorphism over the document using a {@link MarkdownHandlers} table. */
+    fold<T>(handlers: MarkdownHandlers<T>): T;
+    /**
+     * A web-standard {@link ReadableStream} over the document's top-level block nodes
+     * (shallow, source order) - a fresh, pull-based source per call: one block is
+     * enqueued per `pull`, so a slow reader's backpressure is respected. Cancellable,
+     * async-iterable wherever the platform supports it (Node, Deno), and pipeable
+     * through any {@link TransformStream} / {@link WritableStream}.
+     *
+     * @example
+     * ```ts
+     * // universal - works in every ReadableStream-supporting environment
+     * const reader = markdown.stream().getReader()
+     * for (let result = await reader.read(); !result.done; result = await reader.read()) {
+     *   console.log(result.value) // one BlockNode
+     * }
+     *
+     * // Node / Deno / Firefox support async iteration of ReadableStream natively;
+     * // other environments should use the reader loop above instead.
+     * for await (const block of markdown.stream()) {
+     *   console.log(block)
+     * }
+     * ```
+     */
+    stream(): ReadableStream<BlockNode>;
+}

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

@@ -0,0 +1,17 @@
+/**
+ * The URL schemes `renderHTML` permits on a link `href` - anything else (notably
+ * `javascript:`, `data:`, `vbscript:`, `file:`) is dropped to an empty `href` so a
+ * hostile link can never execute. Frozen, lower-case; a relative / anchor /
+ * scheme-less `href` (no `scheme:` prefix) is always allowed.
+ */
+export declare const SAFE_URL_SCHEMES: ReadonlySet<string>;
+/**
+ * The maximum recursion depth the parse pipeline (`parseDocument` and its
+ * `parsers.ts` helpers) and the `helpers.ts` traversal / render functions
+ * (`renderHTML`, `renderMarkdown`, `walkNodes`, `foldNode`) honor before degrading to
+ * literal text - bounds blockquote nesting, inline nesting (emphasis / links), and
+ * traversal/render recursion so pathological or hostile input (deeply nested
+ * blockquotes, runaway emphasis) cannot exhaust the call stack. Past this depth the
+ * parser treats the remaining content as literal text instead of recursing further.
+ */
+export declare const MAX_DEPTH = 64;

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

@@ -0,0 +1,92 @@
+import type { ContractInterface } from '@orkestrel/contract';
+import type { CodeBlockNode, CodeSpanNode, MarkdownDocument, MarkdownInterface, TextNode, ThematicBreakNode } from './types.js';
+/**
+ * Create a stateful markdown handle from a markdown string or an already-parsed
+ * {@link MarkdownDocument} - a typed AST plus the query, rewrite, and fold operations
+ * {@link MarkdownInterface} exposes.
+ *
+ * @remarks
+ * Given a `string`, runs a block phase (headings / paragraphs / lists / GFM tables /
+ * fenced code / blockquotes / thematic breaks) then an inline phase (emphasis /
+ * inline code / links) to build a render-agnostic {@link MarkdownDocument}. Given a
+ * {@link MarkdownDocument}, adopts it AS-IS without re-validation - gate an untrusted
+ * value with `isMarkdownDocument` first. Pure + total parse (malformed markdown
+ * degrades to text, never throws) and zero-dependency - a hand-written scanner, no
+ * regex-only structural parse, linear-time (no ReDoS).
+ *
+ * @param input - A markdown string to parse, or an already-parsed {@link MarkdownDocument}
+ * @returns A working {@link MarkdownInterface}
+ *
+ * @example
+ * ```ts
+ * import { createMarkdown } from '@src/core'
+ *
+ * const markdown = createMarkdown('# Hi\n\nRead the [guide](./guide.md).')
+ * markdown.document.children[0] // { element: 'heading', ... }
+ * ```
+ */
+export declare function createMarkdown(input: string | MarkdownDocument): MarkdownInterface;
+/**
+ * Compile the {@link textShape} into a {@link ContractInterface} for
+ * {@link TextNode} - a guard, coercing parser, JSON Schema, and seeded
+ * generator from one shape declaration (AGENTS §14).
+ *
+ * @returns A `TextNode` contract bundling `schema` / `is` / `parse` / `generate`
+ *
+ * @example
+ * ```ts
+ * import { createTextContract } from '@src/core'
+ *
+ * const text = createTextContract()
+ * text.is({ element: 'text', value: 'hi' }) // true
+ * ```
+ */
+export declare function createTextContract(): ContractInterface<TextNode>;
+/**
+ * Compile the {@link codeSpanShape} into a {@link ContractInterface} for
+ * {@link CodeSpanNode} - a guard, coercing parser, JSON Schema, and seeded
+ * generator from one shape declaration (AGENTS §14).
+ *
+ * @returns A `CodeSpanNode` contract bundling `schema` / `is` / `parse` / `generate`
+ *
+ * @example
+ * ```ts
+ * import { createCodeSpanContract } from '@src/core'
+ *
+ * const codeSpan = createCodeSpanContract()
+ * codeSpan.is({ element: 'codeSpan', value: 'const x = 1' }) // true
+ * ```
+ */
+export declare function createCodeSpanContract(): ContractInterface<CodeSpanNode>;
+/**
+ * Compile the {@link codeBlockShape} into a {@link ContractInterface} for
+ * {@link CodeBlockNode} - a guard, coercing parser, JSON Schema, and seeded
+ * generator from one shape declaration (AGENTS §14).
+ *
+ * @returns A `CodeBlockNode` contract bundling `schema` / `is` / `parse` / `generate`
+ *
+ * @example
+ * ```ts
+ * import { createCodeBlockContract } from '@src/core'
+ *
+ * const codeBlock = createCodeBlockContract()
+ * codeBlock.is({ element: 'codeBlock', code: 'x' }) // true
+ * ```
+ */
+export declare function createCodeBlockContract(): ContractInterface<CodeBlockNode>;
+/**
+ * Compile the {@link thematicBreakShape} into a {@link ContractInterface} for
+ * {@link ThematicBreakNode} - a guard, coercing parser, JSON Schema, and
+ * seeded generator from one shape declaration (AGENTS §14).
+ *
+ * @returns A `ThematicBreakNode` contract bundling `schema` / `is` / `parse` / `generate`
+ *
+ * @example
+ * ```ts
+ * import { createThematicBreakContract } from '@src/core'
+ *
+ * const thematicBreak = createThematicBreakContract()
+ * thematicBreak.is({ element: 'thematicBreak' }) // true
+ * ```
+ */
+export declare function createThematicBreakContract(): ContractInterface<ThematicBreakNode>;