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

package/lib/script-parser.d.ts

@@ -1,9 +1,30 @@
 import type { CustomParser } from './types.js';
+/**
+ * Tokenizes a JavaScript code string into an array of typed tokens using espree.
+ * Each token contains its type (e.g., Identifier, Punctuator) and raw value.
+ *
+ * @param script - The JavaScript source code to tokenize
+ * @returns An array of tokens with their type and string value
+ */
 export declare function scriptParser(script: string): ScriptTokenType[];
+/**
+ * Attempts to extract the longest valid JavaScript prefix from a script string
+ * that may contain trailing non-JS content (e.g., HTML after an inline expression).
+ * Falls back to wrapping the script as an object literal or spread operator
+ * if the initial parse fails.
+ *
+ * @param script - The potentially mixed script/markup string to parse
+ * @param parse - A custom parse function to validate the script; defaults to espree with JSX support
+ * @returns An object containing the `validScript` prefix and the remaining `leftover` string
+ */
 export declare function safeScriptParser(script: string, parse?: CustomParser): {
     validScript: string;
     leftover: string;
 };
+/**
+ * A token produced by the script tokenizer, representing a single
+ * lexical unit of JavaScript source code.
+ */
 export type ScriptTokenType = {
     type: 'Identifier' | 'Boolean' | 'Numeric' | 'String' | 'Template' | 'Punctuator';
     value: string;

package/lib/script-parser.js

@@ -1,5 +1,12 @@
 // @ts-ignore
 import { tokenize, parse } from 'espree';
+/**
+ * Tokenizes a JavaScript code string into an array of typed tokens using espree.
+ * Each token contains its type (e.g., Identifier, Punctuator) and raw value.
+ *
+ * @param script - The JavaScript source code to tokenize
+ * @returns An array of tokens with their type and string value
+ */
 export function scriptParser(script) {
     const tokens = tokenize(script, {
         ecmaVersion: 'latest',
@@ -10,6 +17,16 @@ export function scriptParser(script) {
         value: token.value,
     }));
 }
+/**
+ * Attempts to extract the longest valid JavaScript prefix from a script string
+ * that may contain trailing non-JS content (e.g., HTML after an inline expression).
+ * Falls back to wrapping the script as an object literal or spread operator
+ * if the initial parse fails.
+ *
+ * @param script - The potentially mixed script/markup string to parse
+ * @param parse - A custom parse function to validate the script; defaults to espree with JSX support
+ * @returns An object containing the `validScript` prefix and the remaining `leftover` string
+ */
 export function safeScriptParser(script, parse = defaultParse) {
     let { validScript, leftover } = safeParse(script, parse);
     // Support for object literal

package/lib/sort-nodes.d.ts

@@ -1,2 +1,10 @@
 import type { MLASTNodeTreeItem } from '@markuplint/ml-ast';
+/**
+ * Comparator function for sorting AST nodes by their source position.
+ * Sorts primarily by offset, then by end offset for nodes at the same position.
+ *
+ * @param a - The first node to compare
+ * @param b - The second node to compare
+ * @returns A negative, zero, or positive number for sort ordering
+ */
 export declare function sortNodes(a: MLASTNodeTreeItem, b: MLASTNodeTreeItem): number;

package/lib/sort-nodes.js

@@ -1,8 +1,16 @@
+/**
+ * Comparator function for sorting AST nodes by their source position.
+ * Sorts primarily by offset, then by end offset for nodes at the same position.
+ *
+ * @param a - The first node to compare
+ * @param b - The second node to compare
+ * @returns A negative, zero, or positive number for sort ordering
+ */
 export function sortNodes(a, b) {
-    if (a.startOffset === b.startOffset) {
-        return sort(a.endOffset, b.endOffset);
+    if (a.offset === b.offset) {
+        return sort(a.offset + a.raw.length, b.offset + b.raw.length);
     }
-    return sort(a.startOffset, b.startOffset);
+    return sort(a.offset, b.offset);
 }
 function sort(a, b) {
     const diff = a - b;

package/lib/types.d.ts

@@ -1,4 +1,8 @@
 import type { EndTagType, MLASTParentNode, ParserOptions as ConfigParserOptions } from '@markuplint/ml-ast';
+/**
+ * Configuration options for initializing a Parser instance,
+ * controlling how the parser handles tags, attributes, and whitespace.
+ */
 export type ParserOptions = {
     readonly booleanish?: boolean;
     readonly endTagType?: EndTagType;
@@ -9,28 +13,58 @@ export type ParserOptions = {
     readonly spaceChars?: readonly string[];
     readonly rawTextElements?: readonly string[];
 };
+/**
+ * Options passed to a single parse invocation, extending the base config parser options
+ * with offset positioning and depth control for embedded code fragments.
+ */
 export type ParseOptions = ConfigParserOptions & {
     readonly offsetOffset?: number;
     readonly offsetLine?: number;
     readonly offsetColumn?: number;
     readonly depth?: number;
 };
+/**
+ * The result of tokenizing raw source code, containing the AST nodes
+ * and metadata about whether the parsed content is a document fragment.
+ *
+ * @template N - The AST node type produced by the tokenizer
+ * @template State - The parser state type carried through tokenization
+ */
 export type Tokenized<N extends {} = {}, State extends unknown = null> = {
     readonly ast: N[];
     readonly isFragment: boolean;
     readonly state?: State;
 };
+/**
+ * A minimal source token representing a raw string fragment
+ * along with its starting position in the source code.
+ */
 export type Token = {
     readonly raw: string;
-    readonly startOffset: number;
-    readonly startLine: number;
-    readonly startCol: number;
+    readonly offset: number;
+    readonly line: number;
+    readonly col: number;
 };
+/**
+ * A token that belongs to a parent node in the AST, extending the base Token
+ * with nesting depth and a reference to the enclosing parent node.
+ */
 export type ChildToken = Token & {
     readonly depth: number;
     readonly parentNode: MLASTParentNode | null;
 };
+/**
+ * Determines how self-closing tags (e.g., `<br />`) are interpreted.
+ *
+ * - `"html"`: Only void elements are treated as self-closing (HTML spec behavior)
+ * - `"xml"`: The self-closing solidus (`/`) determines self-closing behavior
+ * - `"html+xml"`: Either void elements or the self-closing solidus cause self-closing
+ */
 export type SelfCloseType = 'html' | 'xml' | 'html+xml';
+/**
+ * Represents a tagged code block (e.g., template expressions or preprocessor directives)
+ * that was extracted from the source during the ignore-block phase.
+ */
 export type Code = {
     readonly type: string;
     readonly index: number;
@@ -39,22 +73,45 @@ export type Code = {
     readonly endTag: string | null;
     resolved: boolean;
 };
+/**
+ * Defines a pattern for identifying blocks of code that should be masked
+ * (replaced with placeholder characters) before parsing, such as template
+ * language expressions or preprocessor directives.
+ */
 export type IgnoreTag = {
     readonly type: string;
     readonly start: Readonly<RegExp> | string;
     readonly end: Readonly<RegExp> | string;
 };
+/**
+ * The result of masking ignore-tagged code blocks in the source, preserving
+ * the original source alongside the replaced version and a stack of extracted codes.
+ */
 export type IgnoreBlock = {
     readonly source: string;
     readonly replaced: string;
     readonly stack: readonly Code[];
     readonly maskChar: string;
 };
+/**
+ * Defines a pair of quote delimiters and the value type they enclose,
+ * used when parsing attribute values with non-standard quoting
+ * (e.g., JSX expression braces or template literals).
+ */
 export type QuoteSet = {
     readonly start: string;
     readonly end: string;
     readonly type: ValueType;
     readonly parser?: CustomParser;
 };
+/**
+ * A function that attempts to parse a code string, throwing a SyntaxError
+ * if the code is invalid. Used by the safe script parser to determine
+ * the boundary of valid script content.
+ */
 export type CustomParser = (code: string) => void;
+/**
+ * The semantic type of an attribute value, distinguishing between
+ * plain string values and script/expression values.
+ */
 export type ValueType = 'string' | 'script';

package/package.json

@@ -1,10 +1,13 @@
 {
 	"name": "@markuplint/parser-utils",
-	"version": "4.8.10",
+	"version": "5.0.0-alpha.0",
 	"description": "Utility module for markuplint parser plugin",
 	"repository": "git@github.com:markuplint/markuplint.git",
 	"author": "Yusuke Hirao <yusukehirao@me.com>",
 	"license": "MIT",
+	"engines": {
+		"node": ">=22"
+	},
 	"type": "module",
 	"exports": {
 		".": {
@@ -28,17 +31,15 @@
 		"clean": "tsc --build --clean tsconfig.build.json"
 	},
 	"dependencies": {
-		"@markuplint/ml-ast": "4.4.10",
-		"@markuplint/ml-spec": "4.10.1",
-		"@markuplint/types": "4.8.1",
-		"@types/uuid": "10.0.0",
+		"@markuplint/ml-ast": "5.0.0-alpha.0",
+		"@markuplint/ml-spec": "5.0.0-alpha.0",
+		"@markuplint/types": "5.0.0-alpha.0",
 		"debug": "4.4.3",
-		"espree": "10.4.0",
-		"type-fest": "4.41.0",
-		"uuid": "13.0.0"
+		"espree": "11.1.0",
+		"type-fest": "5.4.4"
 	},
 	"devDependencies": {
-		"@typescript-eslint/typescript-estree": "8.44.0"
+		"@typescript-eslint/typescript-estree": "8.56.0"
 	},
-	"gitHead": "6213ea30269ef404f030e67bbcc7fc7443ec1060"
+	"gitHead": "13dcfc84ec83d87360c720e253383b60767e1b56"
 }