@orkestrel/markdown 0.0.1 → 0.0.3

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

@@ -1,4 +1,4 @@
-import type { BlockNode, InlineNode, ListNode, MarkdownDocument, TableNode } from './types.js';
+import { BlockNode, InlineNode, ListNode, MarkdownDocument, TableNode } from './types.js';
 /**
  * Parses a run of markdown lines into a block AST, recursing into nested
  * blockquotes, list items, and depth-capped degrade paragraphs.
@@ -6,6 +6,11 @@ import type { BlockNode, InlineNode, ListNode, MarkdownDocument, TableNode } fro
  * @param lines - The markdown lines to parse.
  * @param depth - The current recursion depth (blockquotes/lists increment it).
  * @returns The parsed block nodes.
+ *
+ * @example
+ * ```ts
+ * parseBlocks(['# Hi'], 0) // [{ element: 'heading', level: 1, children: [...] }]
+ * ```
  */
 export declare function parseBlocks(lines: readonly string[], depth: number): readonly BlockNode[];
 /**
@@ -15,6 +20,11 @@ export declare function parseBlocks(lines: readonly string[], depth: number): re
  * @param lines - The markdown lines to scan.
  * @param start - The index of the header row.
  * @returns The parsed table node and the index of the first line after it.
+ *
+ * @example
+ * ```ts
+ * collectTable(['| a |', '| - |'], 0) // { node: { element: 'table', ... }, next: 2 }
+ * ```
  */
 export declare function collectTable(lines: readonly string[], start: number): {
     readonly node: TableNode;
@@ -28,6 +38,11 @@ export declare function collectTable(lines: readonly string[], start: number): {
  * @param start - The index of the first list item.
  * @param depth - The current recursion depth (each item recurses at `depth + 1`).
  * @returns The parsed list node and the index of the first line after it.
+ *
+ * @example
+ * ```ts
+ * collectList(['- item'], 0, 0) // { node: { element: 'list', ... }, next: 1 }
+ * ```
  */
 export declare function collectList(lines: readonly string[], start: number, depth: number): {
     readonly node: ListNode;

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

@@ -1,3 +1,4 @@
+import { ObjectShape, LiteralShape, StringShape, OptionalShape, BooleanShape, NumberShape } from '@orkestrel/contract';
 /**
  * The shape of a {@link TextNode} - a plain-text leaf inline run.
  *
@@ -10,10 +11,10 @@
  * text.is({ element: 'text', value: 'hi' }) // true
  * ```
  */
-export declare const textShape: import("@orkestrel/contract").ObjectShape<{
-    element: import("@orkestrel/contract").LiteralShape<readonly ["text"]>;
-    value: import("@orkestrel/contract").StringShape;
-}>;
+export declare const textShape: ObjectShape<{
+    element: LiteralShape<readonly ["text"]>;
+    value: StringShape;
+}, false>;
 /**
  * The shape of a {@link CodeSpanNode} - an inline code span (`` `code` ``).
  *
@@ -26,10 +27,10 @@ export declare const textShape: import("@orkestrel/contract").ObjectShape<{
  * codeSpan.is({ element: 'codeSpan', value: 'const x = 1' }) // true
  * ```
  */
-export declare const codeSpanShape: import("@orkestrel/contract").ObjectShape<{
-    element: import("@orkestrel/contract").LiteralShape<readonly ["codeSpan"]>;
-    value: import("@orkestrel/contract").StringShape;
-}>;
+export declare const codeSpanShape: ObjectShape<{
+    element: LiteralShape<readonly ["codeSpan"]>;
+    value: StringShape;
+}, false>;
 /**
  * The shape of a {@link CodeBlockNode} - a fenced code block. `lang` is
  * optional (absent when the opening fence carries no info-string).
@@ -44,11 +45,11 @@ export declare const codeSpanShape: import("@orkestrel/contract").ObjectShape<{
  * codeBlock.is({ element: 'codeBlock', code: 'x', lang: 'ts' })        // true
  * ```
  */
-export declare const codeBlockShape: import("@orkestrel/contract").ObjectShape<{
-    element: import("@orkestrel/contract").LiteralShape<readonly ["codeBlock"]>;
-    lang: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").StringShape>;
-    code: import("@orkestrel/contract").StringShape;
-}>;
+export declare const codeBlockShape: ObjectShape<{
+    element: LiteralShape<readonly ["codeBlock"]>;
+    lang: OptionalShape<StringShape>;
+    code: StringShape;
+}, false>;
 /**
  * The shape of a {@link ThematicBreakNode} - a horizontal rule. Carries no
  * fields beyond its `element` discriminant.
@@ -62,9 +63,9 @@ export declare const codeBlockShape: import("@orkestrel/contract").ObjectShape<{
  * thematicBreak.is({ element: 'thematicBreak' }) // true
  * ```
  */
-export declare const thematicBreakShape: import("@orkestrel/contract").ObjectShape<{
-    element: import("@orkestrel/contract").LiteralShape<readonly ["thematicBreak"]>;
-}>;
+export declare const thematicBreakShape: ObjectShape<{
+    element: LiteralShape<readonly ["thematicBreak"]>;
+}, false>;
 /**
  * The shape of a {@link TableAlign} - the per-column GFM table alignment
  * literal.
@@ -80,7 +81,7 @@ export declare const thematicBreakShape: import("@orkestrel/contract").ObjectSha
  * tableAlign.is('top')    // false
  * ```
  */
-export declare const tableAlignShape: import("@orkestrel/contract").LiteralShape<readonly ["none", "left", "right", "center"]>;
+export declare const tableAlignShape: LiteralShape<readonly ["none", "left", "right", "center"]>;
 /**
  * The shape of {@link ListItemParts} - the parsed parts of a single list-item
  * line the block phase's list detector returns. Fully non-recursive (no
@@ -95,10 +96,10 @@ export declare const tableAlignShape: import("@orkestrel/contract").LiteralShape
  * listItemParts.is({ ordered: false, start: 1, content: 'hi', indent: 0, marker: 2 }) // true
  * ```
  */
-export declare const listItemPartsShape: import("@orkestrel/contract").ObjectShape<{
-    ordered: import("@orkestrel/contract").BooleanShape;
-    start: import("@orkestrel/contract").NumberShape;
-    content: import("@orkestrel/contract").StringShape;
-    indent: import("@orkestrel/contract").NumberShape;
-    marker: import("@orkestrel/contract").NumberShape;
-}>;
+export declare const listItemPartsShape: ObjectShape<{
+    ordered: BooleanShape;
+    start: NumberShape;
+    content: StringShape;
+    indent: NumberShape;
+    marker: NumberShape;
+}, false>;

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

@@ -1,11 +1,17 @@
-import type { Guard } from '@orkestrel/contract';
-import type { BlockNode, BlockquoteNode, CodeBlockNode, CodeSpanNode, EmphasisNode, HeadingNode, InlineNode, LinkNode, ListNode, MarkdownDocument, MarkdownNode, ParagraphNode, TableNode, TextNode, ThematicBreakNode } from './types.js';
+import { Guard } from '@orkestrel/contract';
+import { BlockNode, BlockquoteNode, CodeBlockNode, CodeSpanNode, EmphasisNode, HeadingNode, InlineNode, LinkNode, ListNode, MarkdownDocument, MarkdownNode, ParagraphNode, TableNode, TextNode, ThematicBreakNode } from './types.js';
 /**
  * Whether `character` is an inline whitespace character (space / tab / newline) - the
  * emphasis flanking rule's space test.
  *
  * @param character - The character to test
  * @returns `true` when it is inline whitespace
+ *
+ * @example
+ * ```ts
+ * isWhitespace(' ') // true
+ * isWhitespace('a') // false
+ * ```
  */
 export declare function isWhitespace(character: string): boolean;
 /**
@@ -14,6 +20,12 @@ export declare function isWhitespace(character: string): boolean;
  *
  * @param character - The single character after a backslash
  * @returns `true` when a backslash before it is an escape
+ *
+ * @example
+ * ```ts
+ * isEscapable('*') // true
+ * isEscapable('a') // false
+ * ```
  */
 export declare function isEscapable(character: string): boolean;
 /**
@@ -23,6 +35,11 @@ export declare function isEscapable(character: string): boolean;
  *
  * @param line - The candidate line
  * @returns `true` when the line is blank
+ *
+ * @example
+ * ```ts
+ * isBlankLine('   ') // true
+ * ```
  */
 export declare function isBlankLine(line: string): boolean;
 /**
@@ -31,6 +48,11 @@ export declare function isBlankLine(line: string): boolean;
  *
  * @param line - The candidate line
  * @returns `true` when the line begins a blockquote
+ *
+ * @example
+ * ```ts
+ * isQuote('> quoted') // true
+ * ```
  */
 export declare function isQuote(line: string): boolean;
 /**
@@ -40,6 +62,11 @@ export declare function isQuote(line: string): boolean;
  * @param line - The candidate closing line
  * @param marker - The opening fence's marker run (from {@link extractFence})
  * @returns `true` when `line` closes the fence
+ *
+ * @example
+ * ```ts
+ * isFenceClose('```', '```') // true
+ * ```
  */
 export declare function isFenceClose(line: string, marker: string): boolean;
 /**
@@ -48,6 +75,12 @@ export declare function isFenceClose(line: string, marker: string): boolean;
  *
  * @param character - The single character to test, or `undefined` past the end of a line
  * @returns `true` when it is whitespace
+ *
+ * @example
+ * ```ts
+ * isFenceWhitespace(' ')         // true
+ * isFenceWhitespace(undefined)   // false
+ * ```
  */
 export declare function isFenceWhitespace(character: string | undefined): boolean;
 /**
@@ -57,6 +90,11 @@ export declare function isFenceWhitespace(character: string | undefined): boolea
  *
  * @param line - The candidate line
  * @returns `true` when the line is a thematic break
+ *
+ * @example
+ * ```ts
+ * isThematicBreak('---') // true
+ * ```
  */
 export declare function isThematicBreak(line: string): boolean;
 /**
@@ -67,25 +105,79 @@ export declare function isThematicBreak(line: string): boolean;
  * @param header - The candidate header line
  * @param delimiter - The line after it (the candidate delimiter)
  * @returns `true` when the two lines open a table
+ *
+ * @example
+ * ```ts
+ * isTableStart('| a |', '| - |') // true
+ * ```
  */
 export declare function isTableStart(header: string, delimiter: string | undefined): boolean;
 /** Determine whether a node is a heading block. */
 export declare function isHeadingNode(node: MarkdownNode): node is HeadingNode;
-/** Determine whether a node is a paragraph block. */
+/**
+ * Determine whether a node is a paragraph block.
+ *
+ * @example
+ * ```ts
+ * isParagraphNode({ element: 'paragraph', children: [] }) // true
+ * ```
+ */
 export declare function isParagraphNode(node: MarkdownNode): node is ParagraphNode;
-/** Determine whether a node is a list block. */
+/**
+ * Determine whether a node is a list block.
+ *
+ * @example
+ * ```ts
+ * isListNode({ element: 'list', ordered: false, start: 1, items: [] }) // true
+ * ```
+ */
 export declare function isListNode(node: MarkdownNode): node is ListNode;
 /** Determine whether a node is a GFM table block. */
 export declare function isTableNode(node: MarkdownNode): node is TableNode;
-/** Determine whether a node is a fenced code block. */
+/**
+ * Determine whether a node is a fenced code block.
+ *
+ * @example
+ * ```ts
+ * isCodeBlockNode({ element: 'codeBlock', code: 'x' }) // true
+ * ```
+ */
 export declare function isCodeBlockNode(node: MarkdownNode): node is CodeBlockNode;
-/** Determine whether a node is a blockquote block. */
+/**
+ * Determine whether a node is a blockquote block.
+ *
+ * @example
+ * ```ts
+ * isBlockquoteNode({ element: 'blockquote', children: [] }) // true
+ * ```
+ */
 export declare function isBlockquoteNode(node: MarkdownNode): node is BlockquoteNode;
-/** Determine whether a node is a thematic break (horizontal rule) block. */
+/**
+ * Determine whether a node is a thematic break (horizontal rule) block.
+ *
+ * @example
+ * ```ts
+ * isThematicBreakNode({ element: 'thematicBreak' }) // true
+ * ```
+ */
 export declare function isThematicBreakNode(node: MarkdownNode): node is ThematicBreakNode;
-/** Determine whether a node is a plain text run. */
+/**
+ * Determine whether a node is a plain text run.
+ *
+ * @example
+ * ```ts
+ * isTextNode({ element: 'text', value: 'hi' }) // true
+ * ```
+ */
 export declare function isTextNode(node: MarkdownNode): node is TextNode;
-/** Determine whether a node is an emphasis run (`*em*` / `**strong**`). */
+/**
+ * Determine whether a node is an emphasis run (`*em*` / `**strong**`).
+ *
+ * @example
+ * ```ts
+ * isEmphasisNode({ element: 'emphasis', strong: false, children: [] }) // true
+ * ```
+ */
 export declare function isEmphasisNode(node: MarkdownNode): node is EmphasisNode;
 /**
  * Determine whether a node is an inline code span.
@@ -93,6 +185,11 @@ export declare function isEmphasisNode(node: MarkdownNode): node is EmphasisNode
  * @remarks
  * Narrows to {@link CodeSpanNode} - the node whose `element` discriminant is
  * `'codeSpan'`.
+ *
+ * @example
+ * ```ts
+ * isCodeSpanNode({ element: 'codeSpan', value: 'x' }) // true
+ * ```
  */
 export declare function isCodeSpanNode(node: MarkdownNode): node is CodeSpanNode;
 /** Determine whether a node is a link. */

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@orkestrel/markdown",
-	"version": "0.0.1",
+	"version": "0.0.3",
 	"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.",
 	"keywords": [
 		"ast",
@@ -25,13 +25,19 @@
 	],
 	"type": "module",
 	"sideEffects": false,
-	"main": "./dist/src/core/index.js",
+	"main": "./dist/src/core/index.cjs",
+	"module": "./dist/src/core/index.js",
 	"types": "./dist/src/core/index.d.ts",
 	"exports": {
 		".": {
-			"types": "./dist/src/core/index.d.ts",
-			"import": "./dist/src/core/index.js",
-			"default": "./dist/src/core/index.js"
+			"import": {
+				"types": "./dist/src/core/index.d.ts",
+				"default": "./dist/src/core/index.js"
+			},
+			"require": {
+				"types": "./dist/src/core/index.d.cts",
+				"default": "./dist/src/core/index.cjs"
+			}
 		},
 		"./package.json": "./package.json"
 	},
@@ -43,31 +49,35 @@
 		"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 .",
-		"check": "tsc --noEmit --project tsconfig.json",
+		"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",
-		"test:src": "vitest run --config vite.config.ts --reporter=dot --project src:core",
+		"test": "npm run test:src && 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: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",
-		"build:src:core": "vite build --config configs/src/vite.core.config.ts && tsc -p configs/src/tsconfig.core.json",
-		"prepublishOnly": "npm run format:check && npm run lint:check && npm run check && npm run check:src && npm run build && npm test"
+		"build:src:core": "vite build --config configs/src/vite.core.config.ts && npm run copy dist/src/core/index.d.ts dist/src/core/index.d.cts",
+		"prepublishOnly": "npm run format:check && npm run lint:check && npm run check && npm run build && npm test"
 	},
 	"dependencies": {
-		"@orkestrel/contract": "^0.0.1"
+		"@orkestrel/contract": "^0.0.3"
 	},
 	"devDependencies": {
+		"@orkestrel/guide": "^0.0.2",
 		"@types/node": "^26.1.1",
-		"oxfmt": "^0.58.0",
-		"oxlint": "^1.73.0",
+		"oxfmt": "^0.59.0",
+		"oxlint": "^1.74.0",
 		"typescript": "^6.0.3",
-		"vite": "^8.1.4",
+		"vite": "^8.1.5",
+		"vite-plugin-dts": "^5.0.3",
 		"vitest": "^4.1.10"
 	},
 	"engines": {
-		"node": ">=24"
+		"node": ">=22"
 	}
 }