@markuplint/pug-parser 4.6.22 → 4.18.0

package/lib/pug-parser/index.js

@@ -3,6 +3,15 @@ import lexer from 'pug-lexer';
 import parser from 'pug-parser';
 import { getOffsetFromLineAndCol } from '../utils/get-offset-from-line-and-col.js';
 import { getOffsetsFromCode } from '@markuplint/parser-utils/location';
+/**
+ * Parses a Pug template string into an optimized AST with computed offsets
+ * and location data by lexing with pug-lexer, parsing with pug-parser,
+ * and then enriching each node with raw source, offsets, and end positions.
+ *
+ * @param pug - The raw Pug template source code
+ * @param useOffset - Whether to strip indent/outdent tokens (used when parsing at a non-zero offset)
+ * @returns The optimized Pug AST block containing enriched nodes
+ */
 export function pugParse(pug, useOffset = false) {
     let lexOrigin = lexer(pug);
     /**
@@ -23,6 +32,13 @@ export function pugParse(pug, useOffset = false) {
     const ast = optimizeAST(originAst, lex, pug);
     return ast;
 }
+/**
+ * Computes the cumulative character offset at the end of each line
+ * in the given source string.
+ *
+ * @param pug - The raw Pug template source code
+ * @returns An array where each index corresponds to a line and the value is the cumulative offset
+ */
 function getOffsetsFromLines(pug) {
     const lines = pug.split(/\n/);
     let chars = 0;
@@ -32,6 +48,14 @@ function getOffsetsFromLines(pug) {
     });
     return result;
 }
+/**
+ * Merges consecutive Text nodes into a single Text node, combining
+ * their raw source and extending the end location of the first node.
+ *
+ * @param nodes - The array of AST nodes to process
+ * @param pug - The raw Pug template source code
+ * @returns A new array with adjacent Text nodes merged together
+ */
 function mergeTextNode(
 // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
 nodes, pug) {
@@ -50,10 +74,14 @@ nodes, pug) {
     return baseNodes;
 }
 /**
+ * Transforms the raw pug-parser AST into an optimized AST by computing
+ * accurate source offsets, raw text slices, and end positions for each node.
+ * Recursively processes child blocks and merges adjacent text nodes.
  *
- * @param originalAST
- * @param tokens Lexed token list
- * @param pug Raw code
+ * @param originalAST - The raw AST block from pug-parser, or null
+ * @param tokens - The lexed token list from pug-lexer
+ * @param pug - The raw Pug template source code
+ * @returns The optimized AST block with enriched location data
  */
 function optimizeAST(
 // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
@@ -471,6 +499,17 @@ tokens, pug) {
         line: originalAST.line,
     };
 }
+/**
+ * Recursively processes conditional node chains (`else if` / `else`) in the Pug AST,
+ * computing location data for each alternate branch.
+ *
+ * @param node - The Pug conditional AST node with potential alternate branches
+ * @param tokens - The lexed token list from pug-lexer
+ * @param pug - The raw Pug template source code
+ * @param offsets - Precomputed line offset array
+ * @param depth - The current recursion depth for tracking nested conditionals
+ * @returns An array of optimized conditional nodes for the alternate branches
+ */
 function optimizeASTOfConditionalNode(
 // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
 node, 
@@ -548,6 +587,17 @@ tokens, pug, offsets, depth) {
     }
     return altNodes;
 }
+/**
+ * Finds the matching lexer token for a node at the given position and returns
+ * its end location and length.
+ *
+ * @param offset - The character offset of the node's start
+ * @param line - The 1-based line number of the node
+ * @param column - The 1-based column number of the node
+ * @param tokens - The lexed token list from pug-lexer
+ * @param tokenType - Optional token type(s) to filter by
+ * @returns An object with endLine, endColumn, endOffset, and length
+ */
 function getLocationFromToken(offset, line, column, 
 // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
 tokens, tokenType) {
@@ -572,6 +622,17 @@ tokens, tokenType) {
         length,
     };
 }
+/**
+ * Extracts and enriches attribute data from the original Pug AST attributes
+ * by correlating each attribute with its corresponding lexer token to compute
+ * accurate offsets and raw source slices.
+ *
+ * @param originalAttrs - The original attribute list from the Pug AST
+ * @param tokens - The lexed token list from pug-lexer
+ * @param offsets - Precomputed line offset array
+ * @param pug - The raw Pug template source code
+ * @returns An array of enriched attribute objects with computed location data
+ */
 function getAttrs(
 // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
 originalAttrs, 
@@ -609,6 +670,19 @@ tokens, offsets, pug) {
     }
     return attrs;
 }
+/**
+ * Determines the end position of a tag node including its attributes
+ * by scanning lexer tokens that follow the tag's position and precede
+ * non-attribute tokens.
+ *
+ * @param nodeName - The tag name of the element
+ * @param offset - The character offset of the tag's start
+ * @param line - The 1-based line number of the tag
+ * @param column - The 1-based column number of the tag
+ * @param tokens - The lexed token list from pug-lexer
+ * @param offsets - Precomputed line offset array
+ * @returns An object with endOffset, endLine, and endColumn
+ */
 function getEndAttributeLocation(nodeName, offset, line, column, 
 // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
 tokens, offsets) {
@@ -638,6 +712,15 @@ tokens, offsets) {
         endColumn: column + nodeName.length,
     };
 }
+/**
+ * Detects whether a Text node is part of a pipeless text block (indented
+ * text content below a tag) and returns its full span if so.
+ *
+ * @param node - The Pug Text AST node to check
+ * @param pug - The raw Pug template source code
+ * @param tokens - The lexed token list from pug-lexer
+ * @returns Location data for the pipeless text span, or null if not pipeless text
+ */
 function getPipelessText(
 // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
 node, pug, 
@@ -674,6 +757,19 @@ tokens) {
     }
     return null;
 }
+/**
+ * Extracts raw text content and computes accurate end locations for a Text node
+ * by walking through lexer tokens from the node's start position. Handles
+ * multi-line text, piped text detection, and indentation tracking.
+ *
+ * @param val - The text value from the Pug AST node
+ * @param offset - The character offset where the text starts
+ * @param line - The 1-based start line number
+ * @param column - The 1-based start column number
+ * @param tokens - The lexed token list from pug-lexer
+ * @param pug - The raw Pug template source code
+ * @returns An array of ASTText nodes with computed location data
+ */
 function getRawTextAndLocationEnd(val, offset, line, column, 
 // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
 tokens, pug) {

package/lib/types.d.ts

@@ -1,3 +1,7 @@
+/**
+ * Additional location and raw source data that is computed during AST optimization
+ * and appended to the original Pug AST node types.
+ */
 export type AdditionalASTData = {
     raw: string;
     offset: number;
@@ -5,59 +9,84 @@ export type AdditionalASTData = {
     endLine: number;
     endColumn: number;
 };
+/** Union of all optimized Pug AST node types that the parser can produce. */
 export type ASTNode = ASTDoctype | ASTComment | ASTBlockComment | ASTText | ASTTag | ASTInterpolatedTag | ASTCode | ASTConditional | ASTCase | ASTWhen | ASTWhile | ASTEach | ASTMixin | ASTMixinBlock | ASTYieldBlock | ASTFileReference | ASTInclude | ASTRawInclude | ASTIncludeFilter | ASTExtends | ASTNamedBlock | ASTFilter;
+/** Represents a Pug block containing an ordered list of child nodes. */
 export type ASTBlock = {
     type: 'Block';
     nodes: readonly ASTNode[];
     line: number;
 };
+/** An optimized Pug doctype node with computed location data. */
 export type ASTDoctype = PugAST.Doctype & AdditionalASTData;
+/** An optimized Pug single-line comment node with computed location data. */
 export type ASTComment = PugAST.Comments.Comment & AdditionalASTData;
+/** An optimized Pug block comment node with computed location data and an optimized child block. */
 export type ASTBlockComment = Omit<PugAST.Comments.BlockComment, 'block'> & {
     block: ASTBlock | null;
 } & AdditionalASTData;
+/** An optimized Pug text node with computed location data. */
 export type ASTText = PugAST.Text & AdditionalASTData;
+/** An optimized Pug tag node with computed attributes and child block. */
 export type ASTTag = Omit<PugAST.Tag, 'attrs' | 'block'> & {
     attrs: readonly ASTAttr[];
     block: ASTBlock | null;
 } & AdditionalASTData;
+/** An optimized Pug interpolated tag node with computed child block. */
 export type ASTInterpolatedTag = Omit<PugAST.InterpolatedTag, 'block'> & {
     block: ASTBlock | null;
 } & AdditionalASTData;
+/** An optimized Pug code node (unbuffered/buffered JavaScript) with computed child block. */
 export type ASTCode = Omit<PugAST.Code, 'block'> & {
     block: ASTBlock | null;
 } & AdditionalASTData;
+/** An optimized Pug conditional (`if`/`else if`/`else`) node with computed child block. */
 export type ASTConditional = Omit<PugAST.CodeHelpers.Conditional, 'consequent' | 'alternate'> & {
     block: ASTBlock | null;
 } & AdditionalASTData;
+/** An optimized Pug `case` node with computed child block. */
 export type ASTCase = Omit<PugAST.CodeHelpers.CaseWhen.Case, 'block'> & {
     block: ASTBlock | null;
 } & AdditionalASTData;
+/** An optimized Pug `when` node with computed child block. */
 export type ASTWhen = Omit<PugAST.CodeHelpers.CaseWhen.When, 'block'> & {
     block: ASTBlock | null;
 } & AdditionalASTData;
+/** An optimized Pug `while` loop node with computed location data. */
 export type ASTWhile = PugAST.While & AdditionalASTData;
+/** An optimized Pug `each` iteration node with computed child block. */
 export type ASTEach = Omit<PugAST.Each, 'block' | 'alternate'> & {
     block: ASTBlock | null;
 } & AdditionalASTData;
+/** An optimized Pug mixin (definition or call) node with computed child block. */
 export type ASTMixin = Omit<PugAST.Mixin, 'block'> & {
     block: ASTBlock | null;
 } & AdditionalASTData;
+/** An optimized Pug `block` placeholder inside a mixin definition. */
 export type ASTMixinBlock = PugAST.MixinBlock & AdditionalASTData;
+/** An optimized Pug `yield` block placeholder. */
 export type ASTYieldBlock = PugAST.YieldBlock & AdditionalASTData;
+/** An optimized Pug file reference node with computed location data. */
 export type ASTFileReference = PugAST.FileOperations.FileReference & AdditionalASTData;
+/** An optimized Pug `include` node with computed child block. */
 export type ASTInclude = Omit<PugAST.FileOperations.Include, 'block'> & {
     block: ASTBlock | null;
 } & AdditionalASTData;
+/** An optimized Pug raw `include` node with computed location data. */
 export type ASTRawInclude = PugAST.FileOperations.RawInclude & AdditionalASTData;
+/** An optimized Pug include filter node with computed location data. */
 export type ASTIncludeFilter = PugAST.FileOperations.IncludeFilter & AdditionalASTData;
+/** An optimized Pug `extends` node with computed location data. */
 export type ASTExtends = PugAST.FileOperations.Extends & AdditionalASTData;
+/** An optimized Pug named block node with computed child nodes. */
 export type ASTNamedBlock = Omit<PugAST.FileOperations.NamedBlock, 'nodes'> & {
     nodes: readonly ASTNode[];
 } & AdditionalASTData;
+/** An optimized Pug filter node with computed child block. */
 export type ASTFilter = Omit<PugAST.Filter, 'block'> & {
     block: ASTBlock | null;
 } & AdditionalASTData;
+/** An optimized Pug attribute with computed location and raw source data. */
 export type ASTAttr = PugAST.AbstractNodeTypes.Attribute & AdditionalASTData;
 export declare namespace PugAST {
     /**

package/lib/utils/get-offset-from-line-and-col.d.ts

@@ -1 +1,11 @@
+/**
+ * Calculates the character offset in a string from a 1-based line number
+ * and 1-based column number. Handles multi-byte characters correctly
+ * by splitting lines into individual characters.
+ *
+ * @param str - The source string to compute the offset within
+ * @param line - The 1-based line number
+ * @param col - The 1-based column number
+ * @returns The 0-based character offset corresponding to the given line and column
+ */
 export declare function getOffsetFromLineAndCol(str: string, line: number, col: number): number;

package/lib/utils/get-offset-from-line-and-col.js

@@ -1,3 +1,13 @@
+/**
+ * Calculates the character offset in a string from a 1-based line number
+ * and 1-based column number. Handles multi-byte characters correctly
+ * by splitting lines into individual characters.
+ *
+ * @param str - The source string to compute the offset within
+ * @param line - The 1-based line number
+ * @param col - The 1-based column number
+ * @returns The 0-based character offset corresponding to the given line and column
+ */
 export function getOffsetFromLineAndCol(str, line, col) {
     const lines = str.split('\n').slice(0, line);
     const lastLine = lines.pop();

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@markuplint/pug-parser",
-	"version": "4.6.22",
+	"version": "4.18.0",
 	"description": "Pug parser for markuplint",
 	"repository": "git@github.com:markuplint/markuplint.git",
 	"author": "Yusuke Hirao <yusukehirao@me.com>",
@@ -21,11 +21,11 @@
 		"clean": "tsc --build --clean tsconfig.build.json"
 	},
 	"dependencies": {
-		"@markuplint/html-parser": "4.6.22",
-		"@markuplint/ml-ast": "4.4.10",
-		"@markuplint/parser-utils": "4.8.10",
+		"@markuplint/html-parser": "4.18.0",
+		"@markuplint/ml-ast": "4.18.0",
+		"@markuplint/parser-utils": "4.18.0",
 		"pug-lexer": "5.0.1",
 		"pug-parser": "6.0.0"
 	},
-	"gitHead": "6213ea30269ef404f030e67bbcc7fc7443ec1060"
+	"gitHead": "1885af6349def3f19df975b9e9c399dd47361de1"
 }