@origints/markdown 0.1.0

package/dist/markdown-node.d.ts

@@ -0,0 +1,177 @@
+import { Root, Content } from 'mdast';
+import { MarkdownResult, MarkdownPath, SourcePosition } from './markdown-result';
+import { HeadingData, CodeBlockData, InlineCodeData, LinkData, ImageData, ListData, TableData, BlockquoteData, ParagraphData, DefinitionData } from './typed-extractors';
+type MdastNode = Root | Content;
+/**
+ * The type of Markdown node.
+ */
+export type MarkdownNodeType = 'root' | 'heading' | 'paragraph' | 'text' | 'emphasis' | 'strong' | 'inlineCode' | 'code' | 'link' | 'image' | 'list' | 'listItem' | 'table' | 'tableRow' | 'tableCell' | 'blockquote' | 'thematicBreak' | 'html' | 'definition' | 'footnoteDefinition' | 'footnoteReference' | 'break' | 'yaml' | 'toml' | 'unknown';
+/**
+ * A wrapper around mdast nodes with full metadata preservation.
+ *
+ * MarkdownNode enables typed navigation through Markdown structures while
+ * maintaining provenance information. Each traversal operation returns a new
+ * MarkdownNode with an extended path, allowing you to trace exactly how you
+ * arrived at any node.
+ */
+export declare class MarkdownNode {
+    private readonly node;
+    private readonly _path;
+    private readonly root;
+    private constructor();
+    /**
+     * Creates a MarkdownNode from a parsed mdast tree.
+     */
+    static fromRoot(root: Root): MarkdownNode;
+    /**
+     * Creates a MarkdownNode from an mdast node.
+     * @internal
+     */
+    static fromNode(node: MdastNode, path: MarkdownPath, root: Root): MarkdownNode;
+    /**
+     * Returns the current path through the Markdown structure.
+     */
+    get path(): MarkdownPath;
+    /**
+     * Returns the source position of this node, if available.
+     */
+    get position(): SourcePosition | undefined;
+    /**
+     * Returns the type of this Markdown node.
+     */
+    get nodeType(): MarkdownNodeType;
+    /**
+     * Returns the underlying mdast node.
+     */
+    unwrap(): MdastNode;
+    /**
+     * Select a single node matching the CSS-like selector.
+     *
+     * Supported selectors:
+     * - Type: `heading`, `paragraph`, `code`, etc.
+     * - Attribute: `[depth=2]`, `[lang="typescript"]`
+     * - Pseudo-classes: `:first-child`, `:last-child`, `:nth-child(n)`
+     * - Combinators: `heading text`, `list > listItem`
+     *
+     * @example
+     * ```typescript
+     * node.select('heading[depth=1]')
+     * node.select('code[lang="typescript"]')
+     * node.select('list > listItem:first-child')
+     * ```
+     */
+    select(selector: string): MarkdownResult<MarkdownNode>;
+    /**
+     * Select all nodes matching the CSS-like selector.
+     */
+    selectAll(selector: string): MarkdownResult<readonly MarkdownNode[]>;
+    /**
+     * Get all direct children of this node.
+     */
+    children(): MarkdownResult<readonly MarkdownNode[]>;
+    /**
+     * Get child at specific index.
+     */
+    child(index: number): MarkdownResult<MarkdownNode>;
+    /**
+     * Get the first child.
+     */
+    first(): MarkdownResult<MarkdownNode>;
+    /**
+     * Get the last child.
+     */
+    last(): MarkdownResult<MarkdownNode>;
+    /**
+     * Get all headings in the document.
+     */
+    headings(): MarkdownResult<readonly MarkdownNode[]>;
+    /**
+     * Get all code blocks in the document.
+     */
+    codeBlocks(): MarkdownResult<readonly MarkdownNode[]>;
+    /**
+     * Get all links in the document.
+     */
+    links(): MarkdownResult<readonly MarkdownNode[]>;
+    /**
+     * Get all images in the document.
+     */
+    images(): MarkdownResult<readonly MarkdownNode[]>;
+    /**
+     * Get all lists in the document.
+     */
+    lists(): MarkdownResult<readonly MarkdownNode[]>;
+    /**
+     * Get all tables in the document.
+     */
+    tables(): MarkdownResult<readonly MarkdownNode[]>;
+    /**
+     * Get all paragraphs in the document.
+     */
+    paragraphs(): MarkdownResult<readonly MarkdownNode[]>;
+    /**
+     * Get all blockquotes in the document.
+     */
+    blockquotes(): MarkdownResult<readonly MarkdownNode[]>;
+    /**
+     * Get the section under a specific heading (content until next heading of same or higher level).
+     */
+    section(headingText: string): MarkdownResult<readonly MarkdownNode[]>;
+    /**
+     * Extract heading data if this is a heading node.
+     */
+    asHeading(): MarkdownResult<HeadingData>;
+    /**
+     * Extract code block data if this is a code node.
+     */
+    asCodeBlock(): MarkdownResult<CodeBlockData>;
+    /**
+     * Extract inline code data if this is an inlineCode node.
+     */
+    asInlineCode(): MarkdownResult<InlineCodeData>;
+    /**
+     * Extract link data if this is a link node.
+     */
+    asLink(): MarkdownResult<LinkData>;
+    /**
+     * Extract image data if this is an image node.
+     */
+    asImage(): MarkdownResult<ImageData>;
+    /**
+     * Extract list data if this is a list node.
+     */
+    asList(): MarkdownResult<ListData>;
+    /**
+     * Extract table data if this is a table node.
+     */
+    asTable(): MarkdownResult<TableData>;
+    /**
+     * Extract blockquote data if this is a blockquote node.
+     */
+    asBlockquote(): MarkdownResult<BlockquoteData>;
+    /**
+     * Extract paragraph data if this is a paragraph node.
+     */
+    asParagraph(): MarkdownResult<ParagraphData>;
+    /**
+     * Extract definition data if this is a definition node.
+     */
+    asDefinition(): MarkdownResult<DefinitionData>;
+    /**
+     * Get the text content of this node (recursively extracts all text).
+     */
+    text(): string;
+    isHeading(): boolean;
+    isParagraph(): boolean;
+    isCode(): boolean;
+    isInlineCode(): boolean;
+    isLink(): boolean;
+    isImage(): boolean;
+    isList(): boolean;
+    isTable(): boolean;
+    isBlockquote(): boolean;
+    isText(): boolean;
+    private extractText;
+    private extractListItem;
+}
+export {};

package/dist/markdown-result.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Result types for Markdown operations.
+ *
+ * @module markdown/markdown-result
+ */
+/**
+ * Path through a Markdown structure.
+ * Uses indices for positional navigation and node types for semantic navigation.
+ */
+export type MarkdownPath = readonly (string | number)[];
+/**
+ * Source position information.
+ */
+export interface SourcePosition {
+    start: {
+        line: number;
+        column: number;
+        offset?: number;
+    };
+    end: {
+        line: number;
+        column: number;
+        offset?: number;
+    };
+}
+/**
+ * Types of Markdown failures.
+ */
+export type MarkdownFailureKind = 'parse' | 'type' | 'missing' | 'selector' | 'frontmatter';
+/**
+ * Failure information for Markdown operations.
+ */
+export interface MarkdownFailure {
+    readonly kind: MarkdownFailureKind;
+    readonly message: string;
+    readonly path: MarkdownPath;
+    readonly position?: SourcePosition;
+}
+/**
+ * Result type for Markdown operations.
+ * Either success with a value or failure with error details.
+ */
+export type MarkdownResult<T> = {
+    readonly ok: true;
+    readonly value: T;
+    readonly path: MarkdownPath;
+} | {
+    readonly ok: false;
+    readonly failure: MarkdownFailure;
+};
+/**
+ * Create a successful result.
+ */
+export declare function ok<T>(value: T, path: MarkdownPath): MarkdownResult<T>;
+/**
+ * Create a failure result.
+ */
+export declare function fail<T>(kind: MarkdownFailureKind, message: string, path: MarkdownPath, position?: SourcePosition): MarkdownResult<T>;
+/**
+ * Format a Markdown path for display.
+ */
+export declare function formatMarkdownPath(path: MarkdownPath): string;

package/dist/parse.d.ts

@@ -0,0 +1,41 @@
+import { TransformAst, TransformImpl } from '@origints/core';
+/**
+ * Options for parsing Markdown.
+ */
+export interface MarkdownParseOptions {
+    /**
+     * Enable GitHub Flavored Markdown (tables, strikethrough, autolinks, task lists).
+     * Default: true
+     */
+    gfm?: boolean;
+    /**
+     * Parse frontmatter (YAML or TOML at the start of the document).
+     * Default: true
+     */
+    frontmatter?: boolean;
+    /**
+     * Frontmatter formats to recognize.
+     * Default: ['yaml', 'toml']
+     */
+    frontmatterFormats?: ('yaml' | 'toml')[];
+}
+/**
+ * Create a parseMarkdown transform AST.
+ *
+ * @example
+ * ```typescript
+ * const plan = Planner.in(loadFile('README.md'))
+ *   .mapIn(parseMarkdown())
+ *   .inject((node) => node.select('heading[depth=1]').value.asHeading().value.text)
+ *   .compile()
+ * ```
+ */
+export declare function parseMarkdown(options?: MarkdownParseOptions): TransformAst;
+/**
+ * Transform implementation for parseMarkdown.
+ */
+export declare const parseMarkdownImpl: TransformImpl;
+/**
+ * Async transform implementation for parseMarkdown (handles streams).
+ */
+export declare const parseMarkdownAsyncImpl: TransformImpl;

package/dist/typed-extractors.d.ts

@@ -0,0 +1,120 @@
+import { SourcePosition } from './markdown-result';
+/**
+ * Extracted heading data.
+ */
+export interface HeadingData {
+    readonly depth: 1 | 2 | 3 | 4 | 5 | 6;
+    readonly text: string;
+    readonly id?: string;
+    readonly position?: SourcePosition;
+}
+/**
+ * Extracted code block data.
+ */
+export interface CodeBlockData {
+    readonly lang?: string;
+    readonly meta?: string;
+    readonly value: string;
+    readonly position?: SourcePosition;
+}
+/**
+ * Extracted inline code data.
+ */
+export interface InlineCodeData {
+    readonly value: string;
+    readonly position?: SourcePosition;
+}
+/**
+ * Extracted link data.
+ */
+export interface LinkData {
+    readonly url: string;
+    readonly title?: string;
+    readonly text: string;
+    readonly position?: SourcePosition;
+}
+/**
+ * Extracted image data.
+ */
+export interface ImageData {
+    readonly url: string;
+    readonly alt?: string;
+    readonly title?: string;
+    readonly position?: SourcePosition;
+}
+/**
+ * List item data.
+ */
+export interface ListItemData {
+    readonly checked?: boolean;
+    readonly text: string;
+    readonly children: readonly ListItemData[];
+    readonly position?: SourcePosition;
+}
+/**
+ * Extracted list data.
+ */
+export interface ListData {
+    readonly ordered: boolean;
+    readonly start?: number;
+    readonly items: readonly ListItemData[];
+    readonly position?: SourcePosition;
+}
+/**
+ * Table cell data.
+ */
+export interface TableCellData {
+    readonly text: string;
+    readonly align?: 'left' | 'center' | 'right';
+}
+/**
+ * Table row data.
+ */
+export interface TableRowData {
+    readonly cells: readonly TableCellData[];
+}
+/**
+ * Extracted table data.
+ */
+export interface TableData {
+    readonly headers: readonly TableCellData[];
+    readonly rows: readonly TableRowData[];
+    readonly position?: SourcePosition;
+}
+/**
+ * Extracted blockquote data.
+ */
+export interface BlockquoteData {
+    readonly text: string;
+    readonly position?: SourcePosition;
+}
+/**
+ * Extracted paragraph data.
+ */
+export interface ParagraphData {
+    readonly text: string;
+    readonly position?: SourcePosition;
+}
+/**
+ * Extracted thematic break (horizontal rule) data.
+ */
+export interface ThematicBreakData {
+    readonly position?: SourcePosition;
+}
+/**
+ * Extracted definition data (for reference-style links).
+ */
+export interface DefinitionData {
+    readonly identifier: string;
+    readonly url: string;
+    readonly title?: string;
+    readonly position?: SourcePosition;
+}
+/**
+ * Extracted footnote definition data.
+ */
+export interface FootnoteDefinitionData {
+    readonly identifier: string;
+    readonly text: string;
+    readonly position?: SourcePosition;
+}

package/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "@origints/markdown",
+  "version": "0.1.0",
+  "description": "Markdown parsing and manipulation for Origins with full lineage tracking",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.es.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.es.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "dependencies": {
+    "unified": "^11.0.0",
+    "remark-parse": "^11.0.0",
+    "remark-gfm": "^4.0.0",
+    "remark-frontmatter": "^5.0.0",
+    "remark-rehype": "^11.0.0",
+    "rehype-stringify": "^10.0.0",
+    "unist-util-select": "^5.0.0",
+    "unist-util-visit": "^5.0.0",
+    "vfile-matter": "^5.0.0",
+    "yaml": "^2.7.0"
+  },
+  "peerDependencies": {
+    "@origints/core": "^0.1.0"
+  },
+  "devDependencies": {
+    "@types/mdast": "^4.0.0",
+    "@types/node": "^25.0.0",
+    "@vitest/coverage-v8": "^4.0.0",
+    "eslint": "^9.0.0",
+    "typescript": "^5.9.0",
+    "vite": "^7.0.0",
+    "vite-plugin-dts": "^4.0.0",
+    "vitest": "^4.0.0",
+    "@origints/core": "0.1.0",
+    "@origints/yaml": "0.1.0"
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/anthropics/origins.git",
+    "directory": "packages/markdown"
+  },
+  "license": "MIT",
+  "scripts": {
+    "build": "vite build",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "lint": "eslint src"
+  }
+}