@fuzdev/mdz 0.1.0

package/dist/mdz_helpers.d.ts

@@ -0,0 +1,321 @@
+/**
+ * Shared constants and pure helper functions for mdz parsers.
+ *
+ * Used by both the synchronous parser (`mdz_lexer.ts` + `mdz_token_parser.ts`)
+ * and the streaming parser (`mdz_stream_parser.ts`).
+ *
+ * @module
+ */
+import type { MdzNode, MdzNodeComponent, MdzNodeElement } from './mdz.js';
+/** @nodocs */
+export declare const BACKTICK = 96;
+/** @nodocs */
+export declare const ASTERISK = 42;
+/** @nodocs */
+export declare const UNDERSCORE = 95;
+/** @nodocs */
+export declare const TILDE = 126;
+/** @nodocs */
+export declare const NEWLINE = 10;
+/** @nodocs */
+export declare const HYPHEN = 45;
+/** @nodocs */
+export declare const HASH = 35;
+/** @nodocs */
+export declare const SPACE = 32;
+/** @nodocs */
+export declare const TAB = 9;
+/** @nodocs */
+export declare const CARRIAGE_RETURN = 13;
+/** @nodocs */
+export declare const LEFT_ANGLE = 60;
+/** @nodocs */
+export declare const RIGHT_ANGLE = 62;
+/** @nodocs */
+export declare const SLASH = 47;
+/** @nodocs */
+export declare const LEFT_BRACKET = 91;
+/** @nodocs */
+export declare const RIGHT_BRACKET = 93;
+/** @nodocs */
+export declare const LEFT_PAREN = 40;
+/** @nodocs */
+export declare const RIGHT_PAREN = 41;
+/** @nodocs */
+export declare const COLON = 58;
+/** @nodocs */
+export declare const PERIOD = 46;
+/** @nodocs */
+export declare const COMMA = 44;
+/** @nodocs */
+export declare const SEMICOLON = 59;
+/** @nodocs */
+export declare const EXCLAMATION = 33;
+/** @nodocs */
+export declare const QUESTION = 63;
+/** @nodocs */
+export declare const DOLLAR = 36;
+/** @nodocs */
+export declare const PERCENT = 37;
+/** @nodocs */
+export declare const AMPERSAND = 38;
+/** @nodocs */
+export declare const APOSTROPHE = 39;
+/** @nodocs */
+export declare const PLUS = 43;
+/** @nodocs */
+export declare const EQUALS = 61;
+/** @nodocs */
+export declare const AT = 64;
+/** @nodocs */
+export declare const A_UPPER = 65;
+/** @nodocs */
+export declare const Z_UPPER = 90;
+/** @nodocs */
+export declare const A_LOWER = 97;
+/** @nodocs */
+export declare const Z_LOWER = 122;
+/** @nodocs */
+export declare const ZERO = 48;
+/** @nodocs */
+export declare const ONE = 49;
+/** @nodocs */
+export declare const NINE = 57;
+/** @nodocs */
+export declare const HR_HYPHEN_COUNT = 3;
+/** @nodocs */
+export declare const MIN_CODEBLOCK_BACKTICKS = 3;
+/** @nodocs */
+export declare const MAX_LIST_NUMBER_DIGITS = 9;
+/** @nodocs */
+export declare const MAX_HEADING_LEVEL = 6;
+/** @nodocs */
+export declare const HTTPS_PREFIX_LENGTH = 8;
+/** @nodocs */
+export declare const HTTP_PREFIX_LENGTH = 7;
+/** @nodocs */
+export declare const H_LOWER = 104;
+/** @nodocs */
+export declare const H_UPPER = 72;
+/**
+ * Whether a char code is whitespace within a line — space, tab, or `\r` —
+ * everything but the newline itself. A line consisting only of these counts
+ * as blank (paragraph breaks), and trailing runs of them are tolerated but
+ * never significant (HR and fence lines). `\r` is included so CRLF input
+ * gets blank-line and end-of-line behavior for free; mdz does no other CRLF
+ * handling.
+ *
+ * @nodocs
+ */
+export declare const is_line_whitespace: (char_code: number) => boolean;
+/**
+ * Whether `text` contains any non-whitespace character — the
+ * whitespace-only-paragraph drop shared by both parsers. Hot path in the
+ * streaming parser (called from `emit` on every text emission); the char
+ * loop avoids the regex allocation `/\S/.test()` incurs per call.
+ *
+ * Deliberately ASCII-only (space, tab, LF, CR, FF, VT), matching the
+ * grammar's blank-line definition: a line of Unicode-only whitespace
+ * (U+00A0 NBSP, U+3000, etc.) is content, not blank — CommonMark agrees.
+ * `/\S/` and `String.prototype.trim()` would recognize Unicode whitespace
+ * and silently drop such paragraphs.
+ *
+ * @nodocs
+ */
+export declare const has_non_whitespace: (text: string) => boolean;
+/**
+ * A matched blockquote prefix: a run of `>` markers — tight (`>>`) or
+ * separated by single spaces (`> >`), interchangeably — terminated by exactly
+ * one space or the end of the line. Depth is the count of `>`.
+ *
+ * @nodocs
+ */
+export interface MdzBlockquotePrefix {
+    /** Count of `>` markers. */
+    depth: number;
+    /**
+     * Index just past the prefix: after the terminating space, or at the
+     * line-end whitespace/newline for a bare (empty) prefix line.
+     */
+    content_start: number;
+}
+/**
+ * Match a blockquote prefix at `i` (the position of a `>`). Shared by both
+ * parsers — the sync lexer calls with `forced` true (its text is complete);
+ * the streaming parser gets `'pending'` when the buffer ends before the
+ * prefix can resolve.
+ *
+ * Returns null when the line has no valid prefix: a `>` followed directly by
+ * content (`>a`), a tab instead of the marker space (`>\ta`), or a tight run
+ * with trailing content (`>>x`). The backtrack pin: a `>` not followed by
+ * space, end-of-line, or a continuing run is content, and the separator space
+ * before it re-serves as the terminator — `> >x` is a depth-1 prefix with
+ * content `>x`. A `>` followed by only whitespace to the line end is a valid
+ * bare prefix (trailing whitespace tolerated, never significant).
+ *
+ * @nodocs
+ */
+export declare const mdz_match_blockquote_prefix: (text: string, i: number, forced: boolean) => MdzBlockquotePrefix | "pending" | null;
+/**
+ * Whether the line at a quote prefix's `content_start` has non-whitespace
+ * content before its end — the no-empty-start probe for quote opens
+ * (contentless prefix lines never start a quote). `'pending'` when the buffer
+ * ends inside the trailing whitespace run while streaming.
+ *
+ * @nodocs
+ */
+export declare const mdz_blockquote_line_has_content: (text: string, content_start: number, forced: boolean) => boolean | "pending";
+/**
+ * The one-level strip width for a quote line: the first `>` plus its single
+ * following space when present. Stripping one level leaves any deeper prefix
+ * in the content for the nested document to parse — `>> a` strips to `> a`.
+ *
+ * @nodocs
+ */
+export declare const mdz_blockquote_strip_width: (text: string, i: number) => number;
+/**
+ * Map a position in a blockquote's stripped inner document back to its
+ * source offset. Each segment covers one quote line's content plus its
+ * terminating newline — contiguous in both coordinate spaces, so the map is
+ * affine per segment. A binary search for the rightmost segment at or before
+ * `p` always lands correctly, including the end-exclusive position past the
+ * final line.
+ *
+ * @nodocs
+ */
+export declare const mdz_remap_segments: (segments: Array<{
+    inner_start: number;
+    source_start: number;
+}>, p: number) => number;
+/**
+ * Lowercase an ASCII letter code; passes other chars through.
+ * Mirrors the `[A-Z] → [a-z]` shift without touching non-ASCII.
+ *
+ * @nodocs
+ */
+export declare const ascii_to_lower: (char_code: number) => number;
+/**
+ * Case-insensitive URL scheme prefix check. Returns the prefix length
+ * (8 for `https://`, 7 for `http://`) or 0 if neither matches at `pos`.
+ *
+ * URI schemes are case-insensitive per RFC 3986 §3.1, and mobile keyboards
+ * routinely auto-capitalize the first letter of a sentence, producing
+ * `Https://` etc. The original case is preserved in the emitted reference —
+ * browsers normalize schemes themselves.
+ *
+ * @nodocs
+ */
+export declare const match_url_prefix_case_insensitive: (s: string, pos: number) => 0 | 7 | 8;
+/**
+ * Check if character code is a letter (A-Z, a-z).
+ *
+ * @nodocs
+ */
+export declare const is_letter: (char_code: number) => boolean;
+/**
+ * Check if character code is valid for tag name (letter, number, hyphen, underscore).
+ *
+ * @nodocs
+ */
+export declare const is_tag_name_char: (char_code: number) => boolean;
+/**
+ * Check if character is part of a word for word boundary detection.
+ * Used to prevent intraword emphasis with the `_` delimiter.
+ *
+ * Only alphanumeric characters (A-Z, a-z, 0-9) are word characters.
+ * Formatting delimiters (`*`, `_`, `~`) fall outside all three ranges,
+ * so they're naturally excluded without explicit checks.
+ *
+ * This prevents false positives with snake_case identifiers while allowing
+ * adjacent formatting like `**bold**_italic_`.
+ *
+ * @nodocs
+ */
+export declare const is_word_char: (char_code: number) => boolean;
+/** @nodocs */
+export declare const is_valid_path_char: (char_code: number) => boolean;
+/**
+ * Trim trailing punctuation from URL/path per RFC 3986 and GFM rules.
+ * - Trims simple trailing: .,;:!?]
+ * - Balanced logic for () only (valid in path components)
+ *
+ * Note on `]`: the mdz parsers (`mdz.ts`, `mdz_stream_parser_url.ts`,
+ * `mdz_lexer.ts`) scan URL/path chars through `is_valid_path_char`, which
+ * already rejects `]` — so it can never reach this function via parser flow.
+ * The `]` branch here is for external callers using this helper directly on
+ * arbitrary URL-ish input as part of the published `@fuzdev/mdz` surface.
+ *
+ * Optimized to avoid O(n²) string slicing - tracks end index and slices once at the end.
+ */
+export declare const mdz_trim_url_punctuation: (url: string) => string;
+/**
+ * Check if position in text is the start of an absolute path (starts with `/`).
+ * Must be preceded by whitespace or be at the start of the string.
+ * Rejects `//` (comments/protocol-relative) and slash followed by whitespace.
+ *
+ * @nodocs
+ */
+export declare const is_at_absolute_path: (text: string, index: number) => boolean;
+/**
+ * Check if position in text is the start of a relative path (`./` or `../`).
+ * Must be preceded by whitespace or be at the start of the string.
+ * Rejects prefix followed by whitespace, slash, or end of string.
+ *
+ * @nodocs
+ */
+export declare const is_at_relative_path: (text: string, index: number) => boolean;
+/**
+ * Extracts plain text content from an array of mdz nodes, recursing into children.
+ */
+export declare const mdz_text_content: (nodes: Array<MdzNode>) => string;
+/**
+ * Generates a lowercase slug id for a heading from its child nodes.
+ * Follows standard markdown conventions (GitHub, etc.) where heading IDs are lowercased.
+ */
+export declare const mdz_heading_id: (nodes: Array<MdzNode>) => string;
+/**
+ * Generates a lowercase slug id for a heading from plain text content.
+ * Used by the streaming parser which tracks text content directly
+ * rather than building `MdzNode[]` trees.
+ */
+export declare const mdz_heading_id_from_text: (text: string) => string;
+export declare const mdz_is_url: (s: string) => boolean;
+export declare const mdz_is_safe_reference: (reference: string) => boolean;
+/**
+ * Check if an element name is an HTML void element (`br`, `img`, `hr`, ...).
+ * Void elements render self-closing; any parsed children are dropped.
+ */
+export declare const mdz_is_void_element: (name: string) => boolean;
+/**
+ * Resolves a relative path (`./` or `../`) against a base path.
+ * The base is treated as a directory regardless of trailing slash
+ * (`'/docs/usage'` and `'/docs/usage/'` behave identically).
+ * Handles embedded `.` and `..` segments within the reference
+ * (e.g., `'./a/../b'` → navigates up then down).
+ * Clamps at root — excess `..` segments stop at `/` rather than escaping.
+ *
+ * @param reference - a relative path starting with `./` or `../`
+ * @param base - An absolute base path (e.g., `'/docs/usage/'`). Empty string is treated as root.
+ * @returns an absolute resolved path (e.g., `'/docs/usage/grammar'`)
+ */
+export declare const mdz_resolve_relative_path: (reference: string, base: string) => string;
+/**
+ * Push a node into a children array, coalescing with the previous Text node.
+ * Mutates `prev.content` and `prev.end` when both are Text, avoiding array growth
+ * and an extra allocation. Callers must own `dest` and not retain references to
+ * the prior last element across the call.
+ */
+export declare const mdz_push_merging_text: (dest: Array<MdzNode>, node: MdzNode) => void;
+/**
+ * Return a new array with adjacent Text nodes merged into single nodes.
+ * Fast path: returns the original array when no merging is needed.
+ */
+export declare const mdz_merge_adjacent_text: (nodes: Array<MdzNode>) => Array<MdzNode>;
+/**
+ * Extracts a single tag (component or element) if it's the only non-whitespace content.
+ *
+ * @returns the tag node if paragraph wrapping should be skipped (MDX convention),
+ *   or `null` if the content should be wrapped in a paragraph
+ */
+export declare const mdz_extract_single_tag: (nodes: Array<MdzNode>) => MdzNodeComponent | MdzNodeElement | null;
+//# sourceMappingURL=mdz_helpers.d.ts.map

package/dist/mdz_helpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mdz_helpers.d.ts","sourceRoot":"../src/lib/","sources":["../src/lib/mdz_helpers.ts"],"names":[],"mappings":"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"}