@orkestrel/markdown 0.0.5 → 0.0.7

package/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "@orkestrel/markdown",
-	"version": "0.0.5",
-	"description": "Markdown parser toolkit — a fast, zero-surprise CommonMark-style parser with GFM tables, a typed AST, contract-backed node guards, and safe HTML rendering. Part of the @orkestrel line.",
+	"version": "0.0.7",
+	"description": "A types-first markdown layer over @orkestrel/html — typed AST, both conversion directions, and sanitized HTML by default.",
 	"keywords": [
 		"ast",
 		"commonmark",
@@ -20,7 +20,7 @@
 		"url": "git+https://github.com/orkestrel/markdown.git"
 	},
 	"files": [
-		"dist",
+		"dist/src",
 		"README.md"
 	],
 	"type": "module",
@@ -45,19 +45,20 @@
 		"access": "public"
 	},
 	"scripts": {
-		"clean": "node -e \"try{require('node:fs').rmSync('dist',{recursive:true,force:true})}catch{}\"",
+		"clean": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\"",
 		"copy": "node -e \"const fs=require('node:fs'),p=require('node:path'),a=process.argv[1],b=process.argv[2];fs.mkdirSync(p.dirname(b),{recursive:true});fs.cpSync(a,b,{force:true});console.log('Copied: '+a+' to '+b)\"",
-		"tmp:txt": "node -e \"const fs=require('node:fs'),p=require('node:path');function walk(d){for(const e of fs.readdirSync(d,{withFileTypes:true})){const f=p.join(d,e.name);if(e.isDirectory()){walk(f)}else if(!e.name.endsWith('.md')&&!e.name.endsWith('.txt')){const t=f+'.txt';if(!fs.existsSync(t)){fs.renameSync(f,t)}else{console.warn('Skipping '+f+' — target exists: '+t)}}}}try{walk('tmp')}catch(e){if(e.code!=='ENOENT')throw e}\"",
-		"lint": "oxlint --config .oxlintrc.json --fix .",
+		"scaffold": "scaffold",
+		"lint": "oxlint --config .oxlintrc.json --fix --deny-warnings .",
 		"check": "tsc --noEmit --project tsconfig.json && npm run check:src",
 		"check:src": "npm run check:src:core",
 		"check:src:core": "tsc --noEmit -p configs/src/tsconfig.core.json",
 		"format": "oxfmt --config .oxfmtrc.json --write .",
 		"format:check": "oxfmt --config .oxfmtrc.json --check .",
-		"lint:check": "oxlint --config .oxlintrc.json .",
-		"test": "npm run test:src && npm run test:guides",
+		"lint:check": "oxlint --config .oxlintrc.json --deny-warnings .",
+		"test": "npm run test:src && npm run test:policy && npm run test:guides",
 		"test:src": "vitest run --config vite.config.ts --no-cache --reporter=dot --project src:core",
 		"test:src:core": "vitest run --config vite.config.ts --no-cache --reporter=dot --project src:core",
+		"test:policy": "vitest run --config vite.config.ts --no-cache --reporter=dot --project policy",
 		"test:guides": "vitest run --config vite.config.ts --reporter=dot --project guides",
 		"build": "npm run clean && npm run build:src",
 		"build:src": "npm run build:src:core",
@@ -65,19 +66,23 @@
 		"prepublishOnly": "npm run format:check && npm run lint:check && npm run check && npm run build && npm test"
 	},
 	"dependencies": {
-		"@orkestrel/contract": "^0.0.5"
+		"@orkestrel/contract": "^0.0.9",
+		"@orkestrel/html": "^0.0.1"
 	},
 	"devDependencies": {
-		"@orkestrel/guide": "^0.0.4",
-		"@types/node": "^26.1.1",
-		"oxfmt": "^0.59.0",
-		"oxlint": "^1.74.0",
+		"@microsoft/api-extractor": "^7.58.12",
+		"@orkestrel/guide": "^0.0.7",
+		"@orkestrel/scaffold": "^0.0.11",
+		"@types/node": "^26.1.2",
+		"@vitest/browser-playwright": "^4.1.10",
+		"oxfmt": "^0.61.0",
+		"oxlint": "^1.76.0",
 		"typescript": "^6.0.3",
-		"vite": "^8.1.5",
+		"vite": "^8.2.0",
 		"vite-plugin-dts": "^5.0.3",
 		"vitest": "^4.1.10"
 	},
 	"engines": {
-		"node": ">=22"
+		"node": ">=22.12.0"
 	}
 }

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

@@ -1,86 +0,0 @@
-import { 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

@@ -1,17 +0,0 @@
-/**
- * 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

@@ -1,92 +0,0 @@
-import { ContractInterface } from '@orkestrel/contract';
-import { 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>;