@markuplint/parser-utils 4.8.10 → 5.0.0-alpha.0

package/lib/debug.js

@@ -1,15 +1,3 @@
-var __classPrivateFieldGet = (this && this.__classPrivateFieldGet) || function (receiver, state, kind, f) {
-    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a getter");
-    if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot read private member from an object whose class did not declare it");
-    return kind === "m" ? f : kind === "a" ? f.call(receiver) : f ? f.value : state.get(receiver);
-};
-var __classPrivateFieldSet = (this && this.__classPrivateFieldSet) || function (receiver, state, value, kind, f) {
-    if (kind === "m") throw new TypeError("Private method is not writable");
-    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a setter");
-    if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot write private member to an object whose class did not declare it");
-    return (kind === "a" ? f.call(receiver, value) : f ? f.value = value : state.set(receiver, value)), value;
-};
-var _PerformanceTimer_logs, _PerformanceTimer_counter;
 import debug from 'debug';
 import { nodeListToDebugMaps } from './debugger.js';
 export const log = debug('ml-parser');
@@ -17,32 +5,29 @@ export function domLog(nodeList) {
     log('Parse result: %O', nodeListToDebugMaps(nodeList, true));
 }
 export class PerformanceTimer {
-    constructor() {
-        _PerformanceTimer_logs.set(this, []);
-        _PerformanceTimer_counter.set(this, -1);
-    }
+    #logs = [];
+    #counter = -1;
     push(name) {
-        var _a;
         if (!log.enabled) {
             return '';
         }
-        __classPrivateFieldSet(this, _PerformanceTimer_counter, (_a = __classPrivateFieldGet(this, _PerformanceTimer_counter, "f"), _a++, _a), "f");
+        this.#counter++;
         const now = performance.now();
-        const last = __classPrivateFieldGet(this, _PerformanceTimer_logs, "f").at(-1);
+        const last = this.#logs.at(-1);
         if (last && Number.isNaN(last[2])) {
             last[2] = now;
         }
-        name = name || `#${__classPrivateFieldGet(this, _PerformanceTimer_counter, "f")}`;
-        __classPrivateFieldGet(this, _PerformanceTimer_logs, "f").push([name, now, Number.NaN]);
+        name = name || `#${this.#counter}`;
+        this.#logs.push([name, now, Number.NaN]);
     }
     log() {
         if (!log.enabled) {
             return;
         }
         this.push('end');
-        __classPrivateFieldGet(this, _PerformanceTimer_logs, "f").pop();
+        this.#logs.pop();
         const map = new Map();
-        for (const content of __classPrivateFieldGet(this, _PerformanceTimer_logs, "f")) {
+        for (const content of this.#logs) {
             const diff = content[2] - content[1];
             const name = content[0];
             if (map.has(name)) {
@@ -59,4 +44,3 @@ export class PerformanceTimer {
         }
     }
 }
-_PerformanceTimer_logs = new WeakMap(), _PerformanceTimer_counter = new WeakMap();

package/lib/debugger.d.ts

@@ -1,4 +1,29 @@
 import type { MLASTAttr, MLASTNode } from '@markuplint/ml-ast';
+/**
+ * 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 declare function nodeListToDebugMaps(nodeList: readonly (MLASTNode | null)[], withAttr?: boolean): string[];
+/**
+ * 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 declare function attributesToDebugMaps(attributes: readonly MLASTAttr[]): string[][];
+/**
+ * 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 declare function nodeTreeDebugView(nodeTree: readonly MLASTNode[], idFilter?: boolean): (string | undefined)[];

package/lib/debugger.js

@@ -1,13 +1,29 @@
+import { getEndCol, getEndLine } from './get-location.js';
+/**
+ * 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 = [];
-        r.push(tokenDebug(n));
+        const r = [tokenDebug(n)];
         if (withAttr && n && n.type === 'starttag') {
             r.push(...attributesToDebugMaps(n.attributes).flat());
         }
         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
@@ -61,9 +86,14 @@ function tokenDebug(n, type = '') {
     if (!n) {
         return 'NULL';
     }
-    return `[${n.startLine}:${n.startCol}]>[${n.endLine}:${n.endCol}](${n.startOffset},${n.endOffset})${
+    const endOffset = n.offset + n.raw.length;
+    const endLine = getEndLine(n.raw, n.line);
+    const endCol = getEndCol(n.raw, n.col);
+    return `[${n.line}:${n.col}]>[${endLine}:${endCol}](${n.offset},${endOffset})${
     // @ts-ignore
-    n.potentialName ?? n.nodeName ?? n.name ?? n.type ?? type}${'isGhost' in n && n.isGhost ? '(👻)' : ''}${'isBogus' in n && n.isBogus ? '(👿)' : ''}${'conditionalType' in n && n.conditionalType ? ` (${n.conditionalType})` : ''}: ${visibleWhiteSpace(n.raw)}`;
+    n.potentialName ?? n.nodeName ?? n.name ?? n.type ?? type}${'isGhost' in n && n.isGhost ? '(👻)' : ''}${'isBogus' in n && n.isBogus ? '(👿)' : ''}${
+    // @ts-ignore
+    n.blockBehavior?.type ? ` (${n.blockBehavior.type})` : ''}: ${visibleWhiteSpace(n.raw)}`;
 }
 function visibleWhiteSpace(chars) {
     return chars.replaceAll('\n', '⏎').replaceAll('\t', '→').replaceAll(/\s/g, '␣');

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-location.d.ts

@@ -6,12 +6,43 @@ export declare function getLine(rawCodeFragment: string, startOffset: number): n
  * @deprecated Use {@link getPosition} instead. Will be removed in v5.0.0.
  */
 export declare function getCol(rawCodeFragment: string, startOffset: number): number;
+/**
+ * Computes the line and column of a position within a code fragment.
+ *
+ * @param rawCodeFragment - The full raw source text
+ * @param startOffset - The zero-based byte offset to compute the position of
+ * @returns An object containing one-based `line` and `column`
+ */
 export declare function getPosition(rawCodeFragment: string, startOffset: number): {
     readonly line: number;
     readonly column: number;
 };
 export declare function getEndLine(rawCodeFragment: string, startLine: number): number;
 export declare function getEndCol(rawCodeFragment: string, startCol: number): number;
+/**
+ * Computes the end position of a code fragment given its start position.
+ *
+ * @param rawCodeFragment - The raw source text of the fragment
+ * @param startOffset - The zero-based byte offset where the fragment starts
+ * @param startLine - The one-based line number where the fragment starts
+ * @param startCol - The one-based column number where the fragment starts
+ * @returns An object containing `endOffset`, `endLine`, and `endCol`
+ */
+export declare function getEndPosition(rawCodeFragment: string, startOffset: number, startLine: number, startCol: number): {
+    endOffset: number;
+    endLine: number;
+    endCol: number;
+};
+/**
+ * Converts line/column ranges to byte offsets within a code string.
+ *
+ * @param rawCode - The full raw source text
+ * @param startLine - The one-based start line number
+ * @param startCol - The one-based start column number
+ * @param endLine - The one-based end line number
+ * @param endCol - The one-based end column number
+ * @returns An object containing zero-based `offset` and `endOffset`
+ */
 export declare function getOffsetsFromCode(rawCode: string, startLine: number, startCol: number, endLine: number, endCol: number): {
     offset: number;
     endOffset: number;

package/lib/get-location.js

@@ -12,6 +12,13 @@ export function getCol(rawCodeFragment, startOffset) {
     const lines = rawCodeFragment.slice(0, startOffset).split(LINE_BREAK);
     return (lines.at(-1) ?? '').length + 1;
 }
+/**
+ * Computes the line and column of a position within a code fragment.
+ *
+ * @param rawCodeFragment - The full raw source text
+ * @param startOffset - The zero-based byte offset to compute the position of
+ * @returns An object containing one-based `line` and `column`
+ */
 export function getPosition(rawCodeFragment, startOffset) {
     const lines = rawCodeFragment.slice(0, startOffset).split(LINE_BREAK);
     const line = lines.length;
@@ -27,6 +34,32 @@ export function getEndCol(rawCodeFragment, startCol) {
     const lastLine = lines.pop();
     return lineCount > 1 ? lastLine.length + 1 : startCol + rawCodeFragment.length;
 }
+/**
+ * Computes the end position of a code fragment given its start position.
+ *
+ * @param rawCodeFragment - The raw source text of the fragment
+ * @param startOffset - The zero-based byte offset where the fragment starts
+ * @param startLine - The one-based line number where the fragment starts
+ * @param startCol - The one-based column number where the fragment starts
+ * @returns An object containing `endOffset`, `endLine`, and `endCol`
+ */
+export function getEndPosition(rawCodeFragment, startOffset, startLine, startCol) {
+    return {
+        endOffset: startOffset + rawCodeFragment.length,
+        endLine: getEndLine(rawCodeFragment, startLine),
+        endCol: getEndCol(rawCodeFragment, startCol),
+    };
+}
+/**
+ * Converts line/column ranges to byte offsets within a code string.
+ *
+ * @param rawCode - The full raw source text
+ * @param startLine - The one-based start line number
+ * @param startCol - The one-based start column number
+ * @param endLine - The one-based end line number
+ * @param endCol - The one-based end column number
+ * @returns An object containing zero-based `offset` and `endOffset`
+ */
 export function getOffsetsFromCode(rawCode, startLine, startCol, endLine, endCol) {
     const lines = rawCode.split('\n');
     let offset = 0;

package/lib/get-namespace.d.ts

@@ -0,0 +1,11 @@
+import type { MLASTParentNode, NamespaceURI } from '@markuplint/ml-ast';
+/**
+ * Determines the namespace URI for a node based on its tag name and parent node context.
+ * Handles namespace transitions between HTML, SVG, and MathML
+ * (e.g., entering `<svg>` switches to SVG namespace, `<foreignObject>` switches back to HTML).
+ *
+ * @param currentNodeName - The tag name of the current node, or null for anonymous nodes
+ * @param parentNode - The parent node in the AST, or null for root-level nodes
+ * @returns The resolved namespace URI for the node
+ */
+export declare function getNamespace(currentNodeName: string | null, parentNode: MLASTParentNode | null): NamespaceURI;

package/lib/get-namespace.js

@@ -0,0 +1,38 @@
+/**
+ * Determines the namespace URI for a node based on its tag name and parent node context.
+ * Handles namespace transitions between HTML, SVG, and MathML
+ * (e.g., entering `<svg>` switches to SVG namespace, `<foreignObject>` switches back to HTML).
+ *
+ * @param currentNodeName - The tag name of the current node, or null for anonymous nodes
+ * @param parentNode - The parent node in the AST, or null for root-level nodes
+ * @returns The resolved namespace URI for the node
+ */
+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/ignore-block.js

@@ -15,11 +15,10 @@ export function ignoreBlock(source, tags, maskChar = MASK_CHAR) {
         replaced = text.replaced;
         stack.push(...text.stack.map(res => ({ ...res, type: tag.type })));
     }
-    stack.sort((a, b) => a.index - b.index);
     return {
         source,
         replaced,
-        stack,
+        stack: stack.toSorted((a, b) => a.index - b.index),
         maskChar,
     };
 }
@@ -63,33 +62,34 @@ ignoreBlock, throwErrorWhenTagHasUnresolved = true) {
     for (const tag of stack) {
         const raw = `${tag.startTag}${tag.taggedCode}${tag.endTag ?? ''}`;
         const tagIndexEnd = tag.index + raw.length;
-        const node = newNodeList.find(node => node.startOffset <= tag.index && node.endOffset >= tagIndexEnd);
+        const nodeEndOffset = (n) => n.offset + n.raw.length;
+        const node = newNodeList.find(node => node.offset <= tag.index && nodeEndOffset(node) >= tagIndexEnd);
         if (!node) {
             continue;
         }
         const replacementChildNodes = [];
-        if (node.startOffset === tag.index && node.endOffset === tagIndexEnd) {
-            const token = parser.createToken(raw, node.startOffset, node.startLine, node.startCol);
+        if (node.offset === tag.index && nodeEndOffset(node) === tagIndexEnd) {
+            const token = parser.createToken(raw, node.offset, node.line, node.col);
             const psNode = {
                 ...token,
                 type: 'psblock',
-                conditionalType: null,
                 depth: node.depth,
                 nodeName: `#ps:${tag.type}`,
                 parentNode: node.parentNode,
                 childNodes: [],
+                blockBehavior: null,
                 isBogus: false,
                 isFragment: false, // TODO: Case by case
             };
             replacementChildNodes.push(psNode);
         }
         else if (node.type === 'text') {
-            const offset = tag.index - node.startOffset;
+            const offset = tag.index - node.offset;
             const above = node.raw.slice(0, offset);
             const below = node.raw.slice(offset + raw.length);
             if (above) {
                 const { line, column } = getPosition(node.raw, 0);
-                const token = parser.createToken(above, node.startOffset, node.startLine + line - 1, node.startCol + column - 1);
+                const token = parser.createToken(above, node.offset, node.line + line - 1, node.col + column - 1);
                 const aboveNode = {
                     ...token,
                     nodeName: '#text',
@@ -100,22 +100,22 @@ ignoreBlock, throwErrorWhenTagHasUnresolved = true) {
                 replacementChildNodes.push(aboveNode);
             }
             const { line, column } = getPosition(raw, offset);
-            const token = parser.createToken(raw, node.startOffset + offset, node.startLine + line - 1, node.startCol + column - 1);
+            const token = parser.createToken(raw, node.offset + offset, node.line + line - 1, node.col + column - 1);
             const psNode = {
                 ...token,
                 type: 'psblock',
-                conditionalType: null,
                 depth: node.depth,
                 nodeName: `#ps:${tag.type}`,
                 parentNode: node.parentNode,
                 childNodes: [],
+                blockBehavior: null,
                 isBogus: false,
                 isFragment: false, // TODO: Case by case
             };
             replacementChildNodes.push(psNode);
             if (below) {
                 const { line, column } = getPosition(node.raw, offset + raw.length);
-                const token = parser.createToken(below, node.startOffset + offset + raw.length, node.startLine + line - 1, node.startCol + column - 1);
+                const token = parser.createToken(below, node.offset + offset + raw.length, node.line + line - 1, node.col + column - 1);
                 const aboveNode = {
                     ...token,
                     nodeName: '#text',
@@ -144,8 +144,9 @@ ignoreBlock, throwErrorWhenTagHasUnresolved = true) {
                 for (const tag of stack) {
                     const raw = tag.startTag + tag.taggedCode + tag.endTag;
                     const length = raw.length;
-                    if (attr.value.startOffset <= tag.index && tag.index + length <= attr.value.endOffset) {
-                        const offset = tag.index - attr.value.startOffset;
+                    if (attr.value.offset <= tag.index &&
+                        tag.index + length <= attr.value.offset + attr.value.raw.length) {
+                        const offset = tag.index - attr.value.offset;
                         const above = attr.value.raw.slice(0, offset);
                         const below = attr.value.raw.slice(offset + length);
                         parser.updateRaw(attr.value, above + raw + below);
@@ -162,7 +163,7 @@ ignoreBlock, throwErrorWhenTagHasUnresolved = true) {
                 }
                 // Update node raw
                 const length = attr.raw.length;
-                const offset = attr.startOffset - node.startOffset;
+                const offset = attr.offset - node.offset;
                 const above = node.raw.slice(0, offset);
                 const below = node.raw.slice(offset + length);
                 parser.updateRaw(node, above + attr.raw + below);

package/lib/index.d.ts

@@ -1,7 +1,8 @@
 export * from './debugger.js';
 export * from './enums.js';
+export * from './get-namespace.js';
 export * from './idl-attributes.js';
 export * from './parser-error.js';
 export * from './parser.js';
 export * from './script-parser.js';
-export * from './types.js';
+export type * from './types.js';

package/lib/index.js

@@ -1,7 +1,7 @@
 export * from './debugger.js';
 export * from './enums.js';
+export * from './get-namespace.js';
 export * from './idl-attributes.js';
 export * from './parser-error.js';
 export * from './parser.js';
 export * from './script-parser.js';
-export * from './types.js';

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,30 +1,47 @@
+/**
+ * An error that occurs during parsing, carrying the source line, column,
+ * and raw text where the error was encountered.
+ */
 export class ParserError extends Error {
+    col;
+    line;
+    name = 'ParserError';
+    raw;
     constructor(message, info) {
         super(message);
-        this.name = 'ParserError';
         this.line = info.line ?? 1;
         this.col = info.col ?? 0;
         this.raw = info.raw ?? '';
         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 {
+    name = 'TargetParserError';
+    nodeName;
     constructor(message, info) {
         const errMsg = info.nodeName
             ? `The ${info.nodeName} is invalid element (${info.line}:${info.col}): ${message}`
             : message;
         super(errMsg, info);
-        this.name = 'TargetParserError';
         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 {
+    filePath;
+    name = 'ConfigParserError';
     constructor(message, info) {
         const pos = info.line != null && info.line != null ? `(${info.line}:${info.col})` : '';
         const file = ` in ${info.filePath}${pos}`;
         const errMsg = `${message}${file}`;
         super(errMsg, info);
-        this.name = 'ConfigParserError';
         this.filePath = info.filePath;
     }
 }