@markuplint/parser-utils 4.8.9 → 4.8.11

package/lib/debugger.js

@@ -1,3 +1,11 @@
+/**
+ * Converts a list of AST nodes into human-readable debug strings showing
+ * each node's position, type, and raw content. Useful for snapshot testing.
+ *
+ * @param nodeList - The flat list of AST nodes to convert
+ * @param withAttr - Whether to include detailed attribute debug info for start tags
+ * @returns An array of formatted debug strings, one per node (plus attribute lines when enabled)
+ */
 export function nodeListToDebugMaps(nodeList, withAttr = false) {
     return nodeList.flatMap(n => {
         const r = [];
@@ -8,6 +16,14 @@ export function nodeListToDebugMaps(nodeList, withAttr = false) {
         return r;
     });
 }
+/**
+ * Converts a list of AST attributes into detailed debug strings showing
+ * each attribute's components (name, equal sign, value, quotes) with
+ * their positions and additional metadata like directives and dynamic values.
+ *
+ * @param attributes - The list of attributes to convert into debug representations
+ * @returns An array of string arrays, one inner array per attribute containing its debug lines
+ */
 export function attributesToDebugMaps(attributes) {
     return attributes.map(n => {
         const r = [
@@ -36,6 +52,15 @@ export function attributesToDebugMaps(attributes) {
         return r;
     });
 }
+/**
+ * Produces a tree-style debug view of AST nodes, showing indentation
+ * based on depth, parent-child relationships, pair node links,
+ * and ghost/bogus markers. Useful for visualizing the parsed DOM structure.
+ *
+ * @param nodeTree - The flat list of AST nodes to visualize as a tree
+ * @param idFilter - Whether to replace UUIDs with short sequential hex IDs for readability
+ * @returns An array of formatted strings representing the tree view
+ */
 export function nodeTreeDebugView(nodeTree, idFilter = false) {
     const filter = idFilter ? uuidFilter : (id) => id;
     return nodeTree

package/lib/enums.d.ts

@@ -1,3 +1,8 @@
+/**
+ * States of the tag-level state machine used during tokenization.
+ * Transitions drive the parser through detecting the opening bracket,
+ * tag name, attributes, and closing bracket of an HTML/XML tag.
+ */
 export declare enum TagState {
     BeforeOpenTag = 0,
     FirstCharOfTagName = 1,
@@ -6,6 +11,11 @@ export declare enum TagState {
     AfterAttrs = 4,
     AfterOpenTag = 5
 }
+/**
+ * States of the attribute-level state machine used during attribute tokenization.
+ * Transitions drive the parser through the attribute name, equals sign,
+ * and value portions of an HTML/XML attribute.
+ */
 export declare enum AttrState {
     BeforeName = 0,
     Name = 1,

package/lib/enums.js

@@ -1,3 +1,8 @@
+/**
+ * States of the tag-level state machine used during tokenization.
+ * Transitions drive the parser through detecting the opening bracket,
+ * tag name, attributes, and closing bracket of an HTML/XML tag.
+ */
 export var TagState;
 (function (TagState) {
     TagState[TagState["BeforeOpenTag"] = 0] = "BeforeOpenTag";
@@ -7,6 +12,11 @@ export var TagState;
     TagState[TagState["AfterAttrs"] = 4] = "AfterAttrs";
     TagState[TagState["AfterOpenTag"] = 5] = "AfterOpenTag";
 })(TagState || (TagState = {}));
+/**
+ * States of the attribute-level state machine used during attribute tokenization.
+ * Transitions drive the parser through the attribute name, equals sign,
+ * and value portions of an HTML/XML attribute.
+ */
 export var AttrState;
 (function (AttrState) {
     AttrState[AttrState["BeforeName"] = 0] = "BeforeName";

package/lib/get-namespace.d.ts

@@ -0,0 +1,2 @@
+import type { MLASTParentNode, NamespaceURI } from '@markuplint/ml-ast';
+export declare function getNamespace(currentNodeName: string | null, parentNode: MLASTParentNode | null): NamespaceURI;

package/lib/get-namespace.js

@@ -0,0 +1,29 @@
+export function getNamespace(currentNodeName, parentNode) {
+    const parentNS = getParentNamespace(parentNode);
+    if (parentNS === 'http://www.w3.org/1999/xhtml' && currentNodeName?.toLowerCase() === 'svg') {
+        return 'http://www.w3.org/2000/svg';
+    }
+    else if (parentNS === 'http://www.w3.org/2000/svg' && parentNode?.nodeName === 'foreignObject') {
+        return 'http://www.w3.org/1999/xhtml';
+    }
+    else if (parentNS === 'http://www.w3.org/1999/xhtml' && currentNodeName?.toLowerCase() === 'math') {
+        return 'http://www.w3.org/1998/Math/MathML';
+    }
+    return parentNS;
+}
+function getParentNamespace(parentNode) {
+    if (!parentNode) {
+        return 'http://www.w3.org/1999/xhtml';
+    }
+    if ('namespace' in parentNode && parentNode.namespace) {
+        const ns = parentNode.namespace.toLowerCase().trim();
+        return ns === 'http://www.w3.org/1999/xhtml'
+            ? 'http://www.w3.org/1999/xhtml'
+            : ns === 'http://www.w3.org/2000/svg'
+                ? 'http://www.w3.org/2000/svg'
+                : ns === 'http://www.w3.org/1998/Math/MathML'
+                    ? 'http://www.w3.org/1998/Math/MathML'
+                    : 'http://www.w3.org/1999/xhtml';
+    }
+    return getParentNamespace(parentNode.parentNode);
+}

package/lib/idl-attributes.d.ts

@@ -1,3 +1,12 @@
+/**
+ * Searches the IDL-to-content-attribute mapping to find the corresponding
+ * IDL property name and content attribute name for a given attribute name.
+ * Handles camelCase IDL names, lowercase content attribute names, hyphenated names,
+ * and event handler attributes (e.g., `onclick`).
+ *
+ * @param name - The attribute name to look up (can be IDL, content, or hyphenated form)
+ * @returns An object with the matching `idlPropName` and `contentAttrName`, both undefined if no match is found
+ */
 export declare function searchIDLAttribute(name: string): {
     idlPropName: string | undefined;
     contentAttrName: string | undefined;

package/lib/idl-attributes.js

@@ -416,6 +416,15 @@ const idlContentMap = {
     credentialless: 'credentialless',
 };
 const list = Object.entries(idlContentMap);
+/**
+ * Searches the IDL-to-content-attribute mapping to find the corresponding
+ * IDL property name and content attribute name for a given attribute name.
+ * Handles camelCase IDL names, lowercase content attribute names, hyphenated names,
+ * and event handler attributes (e.g., `onclick`).
+ *
+ * @param name - The attribute name to look up (can be IDL, content, or hyphenated form)
+ * @returns An object with the matching `idlPropName` and `contentAttrName`, both undefined if no match is found
+ */
 export function searchIDLAttribute(name) {
     const camelizedName = camelize(name);
     const [idlPropName, contentAttrName] = /^on[a-z]/.test(name)

package/lib/parser-error.d.ts

@@ -1,9 +1,17 @@
+/**
+ * Positional and contextual information associated with a parser error,
+ * used to construct meaningful error messages with source locations.
+ */
 export type ParserErrorInfo = {
     readonly line?: number;
     readonly col?: number;
     readonly raw?: string;
     readonly stack?: string;
 };
+/**
+ * An error that occurs during parsing, carrying the source line, column,
+ * and raw text where the error was encountered.
+ */
 export declare class ParserError extends Error {
     readonly col: number;
     readonly line: number;
@@ -11,6 +19,10 @@ export declare class ParserError extends Error {
     readonly raw: string;
     constructor(message: string, info: ParserErrorInfo);
 }
+/**
+ * A parser error specific to a particular HTML element, including
+ * the node name of the element that caused the error in the message.
+ */
 export declare class TargetParserError extends ParserError {
     name: string;
     readonly nodeName: string | null;
@@ -18,6 +30,10 @@ export declare class TargetParserError extends ParserError {
         readonly nodeName?: string | null;
     });
 }
+/**
+ * A parser error that occurs while reading a configuration file,
+ * including the file path in the error message for easier debugging.
+ */
 export declare class ConfigParserError extends ParserError {
     readonly filePath: string;
     name: string;

package/lib/parser-error.js

@@ -1,3 +1,7 @@
+/**
+ * An error that occurs during parsing, carrying the source line, column,
+ * and raw text where the error was encountered.
+ */
 export class ParserError extends Error {
     constructor(message, info) {
         super(message);
@@ -8,6 +12,10 @@ export class ParserError extends Error {
         this.stack = info.stack ?? this.stack;
     }
 }
+/**
+ * A parser error specific to a particular HTML element, including
+ * the node name of the element that caused the error in the message.
+ */
 export class TargetParserError extends ParserError {
     constructor(message, info) {
         const errMsg = info.nodeName
@@ -18,6 +26,10 @@ export class TargetParserError extends ParserError {
         this.nodeName = info.nodeName ?? null;
     }
 }
+/**
+ * A parser error that occurs while reading a configuration file,
+ * including the file path in the error message for easier debugging.
+ */
 export class ConfigParserError extends ParserError {
     constructor(message, info) {
         const pos = info.line != null && info.line != null ? `(${info.line}:${info.col})` : '';

package/lib/parser.d.ts

@@ -2,10 +2,29 @@ import type { Token, ChildToken, QuoteSet, ParseOptions, ParserOptions, Tokenize
 import type { EndTagType, MLASTDocument, MLASTParentNode, MLParser, ParserAuthoredElementNameDistinguishing, MLASTElement, MLASTElementCloseTag, MLASTToken, MLASTNodeTreeItem, MLASTTag, MLASTText, MLASTAttr, MLASTChildNode, MLASTSpreadAttr, ElementType, Walker, MLASTHTMLAttr, MLASTPreprocessorSpecificBlockConditionalType } from '@markuplint/ml-ast';
 import { AttrState } from './enums.js';
 import { ParserError } from './parser-error.js';
+/**
+ * Abstract base class for all markuplint parsers. Provides the core parsing pipeline
+ * including tokenization, tree traversal, node flattening, and error handling.
+ * Subclasses must implement `nodeize` to convert language-specific AST nodes
+ * into the markuplint AST format.
+ *
+ * @template Node - The language-specific AST node type produced by the tokenizer
+ * @template State - An optional parser state type that persists across tokenization
+ */
 export declare abstract class Parser<Node extends {} = {}, State extends unknown = null> implements MLParser {
     #private;
     state: State;
+    /**
+     * Creates a new Parser instance with the given options and initial state.
+     *
+     * @param options - Configuration options controlling tag handling, whitespace, and quoting behavior
+     * @param defaultState - The initial parser state, cloned and restored after each parse call
+     */
     constructor(options?: ParserOptions, defaultState?: State);
+    /**
+     * The pattern used to distinguish authored (component) element names
+     * from native HTML elements, as specified by the parse options.
+     */
     get authoredElementName(): ParserAuthoredElementNameDistinguishing | undefined;
     /**
      * Detect value as a true if its attribute is booleanish value and omitted.
@@ -26,41 +45,175 @@ export declare abstract class Parser<Node extends {} = {}, State extends unknown
      * - `"never"`: Never need
      */
     get endTag(): EndTagType;
+    /**
+     * The current raw source code being parsed, which may have been
+     * preprocessed (e.g., ignore blocks masked, front matter removed).
+     */
     get rawCode(): string;
+    /**
+     * Whether tag names should be compared in a case-sensitive manner.
+     * When false (the default), tag name comparisons are case-insensitive (HTML behavior).
+     */
     get tagNameCaseSensitive(): boolean;
+    /**
+     * Tokenizes the raw source code into language-specific AST nodes.
+     * Subclasses should override this method to provide actual tokenization logic.
+     *
+     * @param options - Parse options controlling offset, depth, and other parse-time settings
+     * @returns The tokenized result containing the AST node array and fragment flag
+     */
     tokenize(options?: ParseOptions): Tokenized<Node, State>;
+    /**
+     * Hook called before parsing begins, allowing subclasses to preprocess
+     * the raw source code. The default implementation prepends offset spaces
+     * based on the parse options.
+     *
+     * @param rawCode - The raw source code about to be parsed
+     * @param options - Parse options that may specify offset positioning
+     * @returns The preprocessed source code to be used for tokenization
+     */
     beforeParse(rawCode: string, options?: ParseOptions): string;
+    /**
+     * Parses raw source code through the full pipeline: preprocessing, tokenization,
+     * traversal, flattening, ignore-block restoration, and post-processing.
+     * Returns the complete markuplint AST document.
+     *
+     * @param rawCode - The raw source code to parse
+     * @param options - Parse options controlling offsets, depth, front matter, and authored element names
+     * @returns The parsed AST document containing the node list and fragment flag
+     */
     parse(rawCode: string, options?: ParseOptions): MLASTDocument;
+    /**
+     * Hook called after the main parse pipeline completes, allowing subclasses
+     * to perform final transformations on the node list. The default implementation
+     * removes any offset spaces that were prepended during preprocessing.
+     *
+     * @param nodeList - The fully parsed and flattened node list
+     * @param options - The parse options used for this parse invocation
+     * @returns The post-processed node list
+     */
     afterParse(nodeList: readonly MLASTNodeTreeItem[], options?: ParseOptions): readonly MLASTNodeTreeItem[];
+    /**
+     * Wraps an arbitrary error into a ParserError with source location information.
+     * Extracts line and column numbers from common error formats.
+     *
+     * @param error - The original error to wrap
+     * @returns A ParserError containing the original error's message and location data
+     */
     parseError(error: any): ParserError;
+    /**
+     * Recursively traverses language-specific AST nodes by calling `nodeize` on each,
+     * filtering duplicates, and separating child nodes from ancestor-level siblings.
+     *
+     * @param originNodes - The language-specific AST nodes to traverse
+     * @param parentNode - The parent markuplint AST node, or null for top-level nodes
+     * @param depth - The current nesting depth in the tree
+     * @returns An object containing `childNodes` at the current depth and `siblings` that belong to ancestor levels
+     */
     traverse(originNodes: readonly Node[], parentNode: (MLASTParentNode | null) | undefined, depth: number): {
         childNodes: readonly MLASTChildNode[];
         siblings: readonly MLASTNodeTreeItem[];
     };
+    /**
+     * Hook called after traversal completes, used to sort the resulting node tree
+     * by source position. Subclasses may override for custom post-traversal logic.
+     *
+     * @param nodeTree - The unsorted node tree produced by traversal
+     * @returns The node tree sorted by source position
+     */
     afterTraverse(nodeTree: readonly MLASTNodeTreeItem[]): readonly MLASTNodeTreeItem[];
+    /**
+     * Converts a single language-specific AST node into one or more markuplint AST nodes.
+     * Subclasses must override this method to provide actual node conversion logic
+     * using visitor methods like `visitElement`, `visitText`, `visitComment`, etc.
+     *
+     * @param originNode - The language-specific AST node to convert
+     * @param parentNode - The parent markuplint AST node, or null for top-level nodes
+     * @param depth - The current nesting depth in the tree
+     * @returns An array of markuplint AST nodes produced from the origin node
+     */
     nodeize(originNode: Node, parentNode: MLASTParentNode | null, depth: number): readonly MLASTNodeTreeItem[];
+    /**
+     * Post-processes the nodes produced by `nodeize`, separating them into siblings
+     * at the current depth and ancestors that belong to a shallower depth level.
+     * Doctype nodes at depth 0 are promoted to ancestors.
+     *
+     * @param siblings - The nodes produced by `nodeize` for a single origin node
+     * @param parentNode - The parent markuplint AST node, or null for top-level nodes
+     * @param depth - The current nesting depth
+     * @returns An object with `siblings` at the current depth and `ancestors` at shallower depths
+     */
     afterNodeize(siblings: readonly MLASTNodeTreeItem[], parentNode: MLASTParentNode | null, depth: number): {
         siblings: MLASTChildNode[];
         ancestors: MLASTNodeTreeItem[];
     };
+    /**
+     * Flattens a hierarchical node tree into a flat, sorted list by walking
+     * the tree depth-first and removing duplicated nodes.
+     *
+     * @param nodeTree - The hierarchical node tree to flatten
+     * @returns A flat array of all nodes in source order
+     */
     flattenNodes(nodeTree: readonly MLASTNodeTreeItem[]): readonly MLASTNodeTreeItem[];
+    /**
+     * Post-processes the flattened node list by exposing remnant whitespace and
+     * invalid nodes between known nodes, converting orphan end tags to bogus markers,
+     * concatenating adjacent text nodes, and trimming overlapping text.
+     *
+     * @param nodeList - The flat node list to post-process
+     * @param options - Controls which post-processing steps are applied
+     * @returns The cleaned-up flat node list
+     */
     afterFlattenNodes(nodeList: readonly MLASTNodeTreeItem[], options?: {
         readonly exposeInvalidNode?: boolean;
         readonly exposeWhiteSpace?: boolean;
         readonly concatText?: boolean;
     }): readonly MLASTNodeTreeItem[];
+    /**
+     * Creates an AST doctype node from a token containing the doctype
+     * name, public ID, and system ID.
+     *
+     * @param token - The child token with doctype-specific properties
+     * @returns An array containing the single doctype AST node
+     */
     visitDoctype(token: ChildToken & {
         readonly name: string;
         readonly publicId: string;
         readonly systemId: string;
     }): readonly MLASTNodeTreeItem[];
+    /**
+     * Creates an AST comment node from a token. Automatically detects whether
+     * the comment is a bogus comment (not starting with `<!--`).
+     *
+     * @param token - The child token containing the comment's raw text and position
+     * @param options - Optional settings to override the bogus detection
+     * @returns An array containing the single comment AST node
+     */
     visitComment(token: ChildToken, options?: {
         readonly isBogus?: boolean;
     }): readonly MLASTNodeTreeItem[];
+    /**
+     * Creates AST text node(s) from a token. Optionally re-parses the text content
+     * to discover embedded HTML tags within it.
+     *
+     * @param token - The child token containing the text content and position
+     * @param options - Controls whether to search for embedded tags and how to handle invalid ones
+     * @returns An array of AST nodes; a single text node or multiple tag/text nodes if tags were found
+     */
     visitText(token: ChildToken, options?: {
         readonly researchTags?: boolean;
         readonly invalidTagAsText?: boolean;
     }): readonly MLASTNodeTreeItem[];
+    /**
+     * Creates AST element node(s) from a token, including the start tag, optional end tag,
+     * and recursively traversed child nodes. Handles ghost elements (empty raw),
+     * self-closing tags, and nameless fragments (e.g., JSX `<>`).
+     *
+     * @param token - The child token with the element's node name and namespace
+     * @param childNodes - The language-specific child AST nodes to traverse
+     * @param options - Controls end tag creation, fragment handling, and property overrides
+     * @returns An array of AST nodes including the start tag, optional end tag, and any sibling nodes
+     */
     visitElement(token: ChildToken & {
         readonly nodeName: string;
         readonly namespace: string;
@@ -69,12 +222,48 @@ export declare abstract class Parser<Node extends {} = {}, State extends unknown
         readonly namelessFragment?: boolean;
         readonly overwriteProps?: Partial<MLASTElement>;
     }): readonly MLASTNodeTreeItem[];
+    /**
+     * Creates an AST preprocessor-specific block node (e.g., for template directives
+     * like `{#if}`, `{#each}`, or front matter). Recursively traverses child nodes.
+     *
+     * @param token - The child token with the block's node name and fragment flag
+     * @param childNodes - The language-specific child AST nodes to traverse
+     * @param conditionalType - The conditional type if this is a conditional block (e.g., "if", "else")
+     * @param originBlockNode - The original language-specific block node for reference
+     * @returns An array of AST nodes including the block node and any sibling nodes
+     */
     visitPsBlock(token: ChildToken & {
         readonly nodeName: string;
         readonly isFragment: boolean;
     }, childNodes?: readonly Node[], conditionalType?: MLASTPreprocessorSpecificBlockConditionalType, originBlockNode?: Node): readonly MLASTNodeTreeItem[];
+    /**
+     * Traverses a list of child nodes under the given parent, appending the resulting
+     * child AST nodes to the parent and returning any sibling nodes that belong
+     * to ancestor levels. Skips traversal for raw text elements (e.g., `<script>`, `<style>`).
+     *
+     * @param children - The language-specific child AST nodes to traverse
+     * @param parentNode - The parent markuplint AST node to which children will be appended
+     * @returns An array of sibling nodes that belong to ancestor depth levels
+     */
     visitChildren(children: readonly Node[], parentNode: MLASTParentNode | null): readonly MLASTNodeTreeItem[];
+    /**
+     * Attempts to parse a token as a JSX spread attribute (e.g., `{...props}`).
+     * Returns null if the token does not match the spread attribute pattern.
+     *
+     * @param token - The token to inspect for spread attribute syntax
+     * @returns A spread attribute AST node, or null if the token is not a spread attribute
+     */
     visitSpreadAttr(token: Token): MLASTSpreadAttr | null;
+    /**
+     * Parses a token into a fully structured attribute AST node, breaking it down
+     * into its constituent parts: spaces, name, equal sign, quotes, and value.
+     * Also detects spread attributes. If there is leftover text after the attribute,
+     * it is returned in the `__rightText` property for further processing.
+     *
+     * @param token - The token containing the raw attribute text and position
+     * @param options - Controls quoting behavior, value types, and the initial parser state
+     * @returns The parsed attribute AST node with an optional `__rightText` for remaining unparsed content
+     */
     visitAttr(token: Token, options?: {
         readonly quoteSet?: readonly QuoteSet[];
         readonly noQuoteValueType?: ValueType;
@@ -83,9 +272,25 @@ export declare abstract class Parser<Node extends {} = {}, State extends unknown
     }): MLASTAttr & {
         __rightText?: string;
     };
+    /**
+     * Re-parses a text token to discover embedded HTML/XML tags within it,
+     * splitting the content into a sequence of tag and text AST nodes.
+     * Handles self-closing detection, depth tracking, and void element recognition.
+     *
+     * @param token - The child token containing the code fragment to re-parse
+     * @param options - Controls whether nameless fragments (JSX `<>`) are recognized
+     * @returns An array of tag and text AST nodes discovered in the code fragment
+     */
     parseCodeFragment(token: ChildToken, options?: {
         readonly namelessFragment?: boolean;
     }): (MLASTTag | MLASTText)[];
+    /**
+     * Updates the position and depth properties of an AST node, recalculating
+     * end offsets, lines, and columns based on the new start values.
+     *
+     * @param node - The AST node whose location should be updated
+     * @param props - The new position and depth values to apply (only provided values are changed)
+     */
     updateLocation(node: MLASTNodeTreeItem, props: Partial<Pick<MLASTNodeTreeItem, 'startOffset' | 'startLine' | 'startCol' | 'depth'>>): void;
     /**
      * Set new raw code to target node.
@@ -96,18 +301,95 @@ export declare abstract class Parser<Node extends {} = {}, State extends unknown
      * @param raw new raw code
      */
     updateRaw(node: MLASTToken, raw: string): void;
+    /**
+     * Updates the node name and/or element type of an element or close tag AST node.
+     * Useful for renaming elements or changing their classification after initial parsing.
+     *
+     * @param el - The element or close tag AST node to update
+     * @param props - The properties to overwrite on the element
+     */
     updateElement(el: MLASTElement, props: Partial<Pick<MLASTElement, 'nodeName' | 'elementType'>>): void;
     updateElement(el: MLASTElementCloseTag, props: Partial<Pick<MLASTElementCloseTag, 'nodeName'>>): void;
+    /**
+     * Updates metadata properties on an HTML attribute AST node, such as marking
+     * it as a directive, dynamic value, or setting its potential name/value
+     * for preprocessor-specific attribute transformations.
+     *
+     * @param attr - The HTML attribute AST node to update
+     * @param props - The metadata properties to overwrite on the attribute
+     */
     updateAttr(attr: MLASTHTMLAttr, props: Partial<Pick<MLASTHTMLAttr, 'isDynamicValue' | 'isDirective' | 'potentialName' | 'potentialValue' | 'valueType' | 'candidate' | 'isDuplicatable'>>): void;
+    /**
+     * Determines the element type (e.g., "html", "web-component", "authored") for a
+     * given tag name, using the parser's authored element name distinguishing pattern.
+     *
+     * @param nodeName - The tag name to classify
+     * @param defaultPattern - A fallback pattern if no authored element name pattern is set
+     * @returns The element type classification
+     */
     detectElementType(nodeName: string, defaultPattern?: ParserAuthoredElementNameDistinguishing): ElementType;
+    /**
+     * Creates a new MLASTToken with a generated UUID and computed end position.
+     * Accepts either a Token object or a raw string with explicit start coordinates.
+     *
+     * @param token - A Token object or raw string to create the AST token from
+     * @param startOffset - The byte offset where the token starts (required when token is a string)
+     * @param startLine - The line number where the token starts (required when token is a string)
+     * @param startCol - The column number where the token starts (required when token is a string)
+     * @returns A fully populated AST token with UUID, start/end positions, and raw content
+     */
     createToken(token: Token): MLASTToken;
     createToken(token: string, startOffset: number, startLine: number, startCol: number): MLASTToken;
+    /**
+     * Extracts a Token from the current raw code at the given byte offset range,
+     * computing the line and column from the source position.
+     *
+     * @param start - The starting byte offset (inclusive) in the raw code
+     * @param end - The ending byte offset (exclusive) in the raw code; if omitted, slices to the end
+     * @returns A Token containing the sliced raw content and its start position
+     */
     sliceFragment(start: number, end?: number): Token;
+    /**
+     * Calculates start and end byte offsets from line/column positions
+     * within the current raw source code.
+     *
+     * @param startLine - The starting line number (1-based)
+     * @param startCol - The starting column number (1-based)
+     * @param endLine - The ending line number (1-based)
+     * @param endCol - The ending column number (1-based)
+     * @returns The computed start and end byte offsets
+     */
     getOffsetsFromCode(startLine: number, startCol: number, endLine: number, endCol: number): {
         offset: number;
         endOffset: number;
     };
+    /**
+     * Walks through a node list depth-first, invoking the walker callback for each node.
+     * The walker receives the current node, the sequentially previous node, and the depth.
+     * Automatically recurses into child nodes of parent elements and preprocessor blocks.
+     *
+     * @template Node - The specific AST node type being walked
+     * @param nodeList - The list of nodes to walk
+     * @param walker - The callback invoked for each node during the walk
+     * @param depth - The current depth (starts at 0 for top-level calls)
+     */
     walk<Node extends MLASTNodeTreeItem>(nodeList: readonly Node[], walker: Walker<Node>, depth?: number): void;
+    /**
+     * Appends child nodes to a parent node, updating parent references and
+     * maintaining sorted order by source position. If a child already exists
+     * in the parent (by UUID), it is replaced in place rather than duplicated.
+     *
+     * @param parentNode - The parent node to append children to, or null (no-op)
+     * @param childNodes - The child nodes to append
+     */
     appendChild(parentNode: MLASTParentNode | null, ...childNodes: readonly MLASTChildNode[]): void;
+    /**
+     * Replaces a child node within a parent's child list with one or more replacement nodes.
+     * If the old child is not found in the parent, the operation is a no-op.
+     *
+     * @param parentNode - The parent node containing the child to replace
+     * @param oldChildNode - The existing child node to be replaced
+     * @param replacementChildNodes - The replacement nodes to insert at the old child's position
+     */
     replaceChild(parentNode: MLASTParentNode, oldChildNode: MLASTChildNode, ...replacementChildNodes: readonly MLASTChildNode[]): void;
 }