@markuplint/pug-parser 4.6.22 → 4.18.0

package/docs/maintenance.ja.md

@@ -0,0 +1,188 @@
+# メンテナンスガイド
+
+## コマンド
+
+| コマンド                                    | 説明                   |
+| ------------------------------------------- | ---------------------- |
+| `yarn build --scope @markuplint/pug-parser` | このパッケージをビルド |
+| `yarn dev --scope @markuplint/pug-parser`   | ウォッチモードでビルド |
+| `yarn clean --scope @markuplint/pug-parser` | ビルド成果物を削除     |
+| `yarn test --scope @markuplint/pug-parser`  | テストを実行           |
+
+## テスト
+
+テストファイルは `*.spec.ts` の命名規則に従います:
+
+| テストファイル                                   | カバレッジ                                                       |
+| ------------------------------------------------ | ---------------------------------------------------------------- |
+| `src/index.spec.ts`                              | PugParser 統合テスト（Pug テンプレートのエンドツーエンドパース） |
+| `src/pug-parser/index.spec.ts`                   | AST 最適化テスト（pugParse、optimizeAST）                        |
+| `src/utils/get-offset-from-line-and-col.spec.ts` | オフセット計算ユーティリティのテスト                             |
+
+主なテストパターンでは `nodeListToDebugMaps` を使用したスナップショット形式のアサーションを行います:
+
+```ts
+import { nodeListToDebugMaps } from '@markuplint/parser-utils';
+import { parser } from '@markuplint/pug-parser';
+
+const doc = parser.parse('div.foo#bar text content');
+const debugMaps = nodeListToDebugMaps(doc.nodeList, true);
+expect(debugMaps).toStrictEqual([
+  // 期待されるデバッグ出力
+]);
+```
+
+## レシピ
+
+### 1. 新しい Pug AST ノードタイプの追加
+
+1. `src/types.ts` を読み、新しい最適化済み型を追加:
+   ```ts
+   export type ASTNewType = PugAST.NewType & AdditionalASTData;
+   ```
+2. 新しい型を `ASTNode` 共用体に追加
+3. `src/pug-parser/index.ts` を読み、`optimizeAST()` に新しい `case` を追加:
+   ```ts
+   case 'NewType': {
+     const block = optimizeAST(node.block, tokens, pug);
+     const newNode: ASTNewType = {
+       type: node.type,
+       raw,
+       offset,
+       endOffset,
+       line,
+       endLine,
+       column,
+       endColumn,
+       block,
+       filename: node.filename ?? null,
+     };
+     nodes.push(newNode);
+     continue;
+   }
+   ```
+4. `src/parser.ts` を読み、`nodeize()` に新しい `case` を追加:
+   - HTML 的な要素の場合: `getNamespace()` と属性で `visitElement()` を使用
+   - Pug 固有の構文の場合: 子ノードで `visitPsBlock()` を使用
+5. ビルド: `yarn build --scope @markuplint/pug-parser`
+6. テスト: `yarn test --scope @markuplint/pug-parser`
+
+### 2. 属性処理の変更
+
+1. `src/parser.ts` を読む — `visitAttr()` メソッドには3つのパスがある:
+   - **ショートハンド**（`#` / `.`）: `AttrState.BeforeValue` を使用し、`potentialName` を設定
+   - **通常**: `noQuoteValueType: 'script'` を使用
+   - **値パース**: `scriptParser()` で型検出（Numeric、Boolean、String、Template、dynamic）
+2. 変更を行う:
+   - 新しいショートハンド構文の場合: 既存の `#`/`.` チェックの前に条件を追加
+   - 属性名変換の場合: `attr.name.raw.endsWith('!')` チェックの後に追加
+   - 値型検出の場合: `scriptParser()` 結果の switch を変更
+3. `this.updateAttr()` でメタデータを設定: `potentialName`、`potentialValue`、`isDuplicatable`、`valueType`
+4. ビルドとテスト: `yarn build --scope @markuplint/pug-parser && yarn test --scope @markuplint/pug-parser`
+
+### 3. AST 最適化の更新
+
+1. `src/pug-parser/index.ts` を読む — 最適化パイプライン:
+   - `pugParse()` — エントリーポイント: lex → parse → optimize
+   - `optimizeAST()` — 再帰的なノード強化
+   - `getOffsetsFromLines()` — 累積オフセットルックアップテーブル
+   - `getLocationFromToken()` — 行/列によるトークンマッチング
+   - `getAttrs()` — レキサートークンからの属性強化
+   - `getEndAttributeLocation()` — 属性を含むタグの終了位置
+   - `mergeTextNode()` — 連続テキストノードのマージ
+   - `getPipelessText()` — パイプレステキストブロックの検出
+   - `getRawTextAndLocationEnd()` — 複数行テキストの処理
+   - `optimizeASTOfConditionalNode()` — else-if/else チェーンの処理
+2. 変更時の注意点:
+   - オフセットは `getOffsetsFromLines()` から `offsets[line - 2]` を使用して計算する必要がある
+   - 終了位置は `getLocationFromToken()` でマッチするレキサートークンから取得
+   - `raw` は元のソースからスライスする必要がある: `pug.slice(offset, endOffset)`
+   - `structuredClone()` によるトークンのクローンが必要 — パーサーはトークン配列を変更する
+3. ビルドとテスト: `yarn build --scope @markuplint/pug-parser && yarn test --scope @markuplint/pug-parser`
+
+### 4. インライン HTML 処理の変更
+
+1. `src/parser.ts` を読む — `nodeize()` の `Text` ケース:
+   - `<` や `#[` を含むテキストは `HtmlInPugParser` でパースされる
+   - `#ps:tag-interpolation` ノードは `PugParser` で再帰的にパースされる
+2. タグ補間構文を変更するには:
+   - `HtmlInPugParser` コンストラクタの `ignoreTags` を変更
+   - `Text` ケースの `#ps:tag-interpolation` 検出を更新
+   - `#[` プレフィックスと `]` サフィックスの除去のオフセット計算を更新
+3. インライン HTML の動作を変更するには:
+   - `HtmlInPugParser` クラスを変更（`HtmlParser` を拡張）
+   - `offsetOffset`、`offsetLine`、`offsetColumn` コンテキストが正しく渡される必要がある
+4. ビルドとテスト: `yarn build --scope @markuplint/pug-parser && yarn test --scope @markuplint/pug-parser`
+
+### 5. useOffset インデントフィルタリングの変更
+
+1. `src/pug-parser/index.ts` を読む — `pugParse()` 関数
+2. `useOffset` フラグは、ゼロ以外のオフセットでサブテンプレートをパースする際に `indent` と `outdent` トークンをフィルタリングする
+3. 変更するには:
+   - `if (useOffset)` ブロック内のフィルタ条件を変更
+   - サブテンプレートコンテキストで他のトークンタイプもフィルタリングが必要かを検討
+4. ビルドとテスト: `yarn build --scope @markuplint/pug-parser && yarn test --scope @markuplint/pug-parser`
+
+## トラブルシューティング
+
+### Pug AST ノードのオフセットがおかしい
+
+**症状:** Pug ノードの `offset`、`endOffset`、`endLine`、`endColumn` が markuplint AST 内で不正。
+
+**原因:** `optimizeAST()` 関数がオフセットを誤って計算しているか、マッチするレキサートークンが不正。
+
+**解決策:**
+
+1. `getOffsetsFromLines()` を確認 — 入力に対して累積オフセットテーブルが正しいことを検証
+2. `getLocationFromToken()` を確認 — 行/列で正しいトークンがマッチし、`tokenType` フィルタリングが正しいことを確認
+3. 属性付きタグの場合、`getEndAttributeLocation()` を確認 — 正しいトークンで停止していることを検証
+4. デバッグログを追加: 関連する `optimizeAST()` ケースで `console.log(JSON.stringify(node, null, 2))`
+
+### タグ補間がパースされない
+
+**症状:** `#[tag content]` が markuplint ノードに展開されず、生テキストとして表示される。
+
+**原因:** テキストノードが `HtmlInPugParser` パスに到達していないか、`#ps:tag-interpolation` の検出が失敗している。
+
+**解決策:**
+
+1. `nodeize()` の `Text` ケースを確認 — `originNode.raw.includes('#[')` が `true` と評価されることを確認
+2. `HtmlInPugParser` を確認 — `ignoreTags` が `#[...]` を正しくマスクしていることを検証
+3. `#ps:tag-interpolation` の検出を確認 — `node.nodeName === '#ps:tag-interpolation'` であることを確認
+4. 再帰的な `PugParser` 呼び出しを確認 — オフセットコンテキスト（`offsetOffset`、`offsetLine`、`offsetColumn`）が正しく計算されていることを検証
+
+### 複雑な式の属性パースが失敗する
+
+**症状:** 複雑な JavaScript 値を持つ Pug 属性（例: `data-value=obj.prop + 1`）がパースエラーまたは不正な AST を引き起こす。
+
+**原因:** 複数トークンの式に対して `scriptParser()` の結果が正しく処理されていない。
+
+**解決策:**
+
+1. `visitAttr()` メソッドを確認 — 最後の `return` ブロックが複数トークンの式を `isDynamicValue: true, valueType: 'code'` として処理している
+2. `@markuplint/parser-utils` の `scriptParser()` を確認 — 値の式が正しくトークン化されていることを検証
+3. 単一トークンの式の場合、`switch (token.type)` がトークンタイプを正しく処理しているか検証
+
+### ショートハンド属性の potentialName がおかしい
+
+**症状:** `#my-id` や `.my-class` が間違った `potentialName` を持つ属性を生成する。
+
+**原因:** ショートハンド検出または `endOffset` の再計算が誤っている。
+
+**解決策:**
+
+1. `visitAttr()` の `#`/`.` ブランチを確認 — `potentialName` が `#` の場合 `'id'`、`.` の場合 `'class'` に設定されていることを確認
+2. `nodeize()` の Tag ケースで `endOffset` の再計算を確認 — ショートハンド属性では `attr.offset === attr.endOffset` が true であり、`endOffset` は `attr.offset + attr.val.length - 1` であるべき
+3. Pug AST の `val` 値を検証 — `#my-id` の場合、`val` は `"'my-id'"`（前後にクォート付き）であるべき
+
+### パイプレステキストが検出されない
+
+**症状:** `.` 付きタグの後のインデントされたテキストがパイプレステキストとして扱われない。
+
+**原因:** `getPipelessText()` 関数が `start-pipeless-text` / `end-pipeless-text` トークンを見つけられないか、行範囲チェックが失敗している。
+
+**解決策:**
+
+1. レキサー出力を確認 — `start-pipeless-text` と `end-pipeless-text` トークンが存在することを検証
+2. 行範囲を確認: `startPipelessText.loc.start.line < node.line && node.line < endPipelessText.loc.start.line`
+3. トークンが存在するが範囲が誤っている場合、pug-lexer バージョンの問題の可能性がある

package/docs/maintenance.md

@@ -0,0 +1,188 @@
+# Maintenance Guide
+
+## Commands
+
+| Command                                     | Description            |
+| ------------------------------------------- | ---------------------- |
+| `yarn build --scope @markuplint/pug-parser` | Build this package     |
+| `yarn dev --scope @markuplint/pug-parser`   | Watch mode build       |
+| `yarn clean --scope @markuplint/pug-parser` | Remove build artifacts |
+| `yarn test --scope @markuplint/pug-parser`  | Run tests              |
+
+## Testing
+
+Test files follow the `*.spec.ts` naming convention:
+
+| Test File                                        | Coverage                                                       |
+| ------------------------------------------------ | -------------------------------------------------------------- |
+| `src/index.spec.ts`                              | PugParser integration tests (parsing Pug templates end-to-end) |
+| `src/pug-parser/index.spec.ts`                   | AST optimization tests (pugParse, optimizeAST)                 |
+| `src/utils/get-offset-from-line-and-col.spec.ts` | Offset calculation utility tests                               |
+
+The primary testing pattern uses `nodeListToDebugMaps` for snapshot-style assertions:
+
+```ts
+import { nodeListToDebugMaps } from '@markuplint/parser-utils';
+import { parser } from '@markuplint/pug-parser';
+
+const doc = parser.parse('div.foo#bar text content');
+const debugMaps = nodeListToDebugMaps(doc.nodeList, true);
+expect(debugMaps).toStrictEqual([
+  // expected debug output
+]);
+```
+
+## Recipes
+
+### 1. Adding a New Pug AST Node Type
+
+1. Read `src/types.ts` — add the new optimized type:
+   ```ts
+   export type ASTNewType = PugAST.NewType & AdditionalASTData;
+   ```
+2. Add the new type to the `ASTNode` union
+3. Read `src/pug-parser/index.ts` — add a new `case` in `optimizeAST()`:
+   ```ts
+   case 'NewType': {
+     const block = optimizeAST(node.block, tokens, pug);
+     const newNode: ASTNewType = {
+       type: node.type,
+       raw,
+       offset,
+       endOffset,
+       line,
+       endLine,
+       column,
+       endColumn,
+       block,
+       filename: node.filename ?? null,
+     };
+     nodes.push(newNode);
+     continue;
+   }
+   ```
+4. Read `src/parser.ts` — add a new `case` in `nodeize()`:
+   - For HTML-like elements: use `visitElement()` with `getNamespace()` and attributes
+   - For Pug-specific constructs: use `visitPsBlock()` with child nodes
+5. Build: `yarn build --scope @markuplint/pug-parser`
+6. Test: `yarn test --scope @markuplint/pug-parser`
+
+### 2. Modifying Attribute Processing
+
+1. Read `src/parser.ts` — the `visitAttr()` method has three paths:
+   - **Shorthand** (`#` / `.`): Uses `AttrState.BeforeValue`, sets `potentialName`
+   - **Regular**: Uses `noQuoteValueType: 'script'`
+   - **Value parsing**: Uses `scriptParser()` for type detection (Numeric, Boolean, String, Template, dynamic)
+2. Make the change:
+   - For new shorthand syntax: add a condition before the existing `#`/`.` check
+   - For attribute name transforms: add after the `attr.name.raw.endsWith('!')` check
+   - For value type detection: modify the `scriptParser()` result switch
+3. Use `this.updateAttr()` to set metadata: `potentialName`, `potentialValue`, `isDuplicatable`, `valueType`
+4. Build and test: `yarn build --scope @markuplint/pug-parser && yarn test --scope @markuplint/pug-parser`
+
+### 3. Updating AST Optimization
+
+1. Read `src/pug-parser/index.ts` — the optimization pipeline:
+   - `pugParse()` — entry point: lex → parse → optimize
+   - `optimizeAST()` — recursive node enrichment
+   - `getOffsetsFromLines()` — cumulative offset lookup table
+   - `getLocationFromToken()` — token matching by line/column
+   - `getAttrs()` — attribute enrichment from lexer tokens
+   - `getEndAttributeLocation()` — tag end position including attributes
+   - `mergeTextNode()` — consecutive text node merging
+   - `getPipelessText()` — pipeless text block detection
+   - `getRawTextAndLocationEnd()` — multi-line text handling
+   - `optimizeASTOfConditionalNode()` — else-if/else chain processing
+2. Make the change, paying attention to:
+   - Offsets must be computed from `getOffsetsFromLines()` using `offsets[line - 2]`
+   - End positions come from matching lexer tokens via `getLocationFromToken()`
+   - `raw` must be sliced from the original source: `pug.slice(offset, endOffset)`
+   - Token cloning via `structuredClone()` is required — the parser mutates the token array
+3. Build and test: `yarn build --scope @markuplint/pug-parser && yarn test --scope @markuplint/pug-parser`
+
+### 4. Modifying Inline HTML Handling
+
+1. Read `src/parser.ts` — the `Text` case in `nodeize()`:
+   - Text with `<` or `#[` is parsed through `HtmlInPugParser`
+   - `#ps:tag-interpolation` nodes are recursively parsed by `PugParser`
+2. To change tag interpolation syntax:
+   - Modify the `ignoreTags` in `HtmlInPugParser` constructor
+   - Update the `#ps:tag-interpolation` detection in the `Text` case
+   - Update the offset calculations for `#[` prefix and `]` suffix stripping
+3. To change inline HTML behavior:
+   - Modify the `HtmlInPugParser` class (extends `HtmlParser`)
+   - The `offsetOffset`, `offsetLine`, `offsetColumn` context must be passed correctly
+4. Build and test: `yarn build --scope @markuplint/pug-parser && yarn test --scope @markuplint/pug-parser`
+
+### 5. Modifying the useOffset Indent Filtering
+
+1. Read `src/pug-parser/index.ts` — the `pugParse()` function
+2. The `useOffset` flag filters `indent` and `outdent` tokens when parsing sub-templates at non-zero offsets
+3. To modify:
+   - Change the filter condition in the `if (useOffset)` block
+   - Consider whether other token types need filtering for the sub-template context
+4. Build and test: `yarn build --scope @markuplint/pug-parser && yarn test --scope @markuplint/pug-parser`
+
+## Troubleshooting
+
+### Pug AST node has wrong offsets
+
+**Symptom:** A Pug node's `offset`, `endOffset`, `endLine`, or `endColumn` is incorrect in the markuplint AST.
+
+**Cause:** The `optimizeAST()` function is computing wrong offsets, or the matching lexer token is incorrect.
+
+**Solution:**
+
+1. Check `getOffsetsFromLines()` — verify the cumulative offset table is correct for the input
+2. Check `getLocationFromToken()` — ensure the correct token is matched by line/column, and that `tokenType` filtering is correct
+3. For tags with attributes, check `getEndAttributeLocation()` — verify it stops at the right token
+4. Add debug logging: `console.log(JSON.stringify(node, null, 2))` in the relevant `optimizeAST()` case
+
+### Tag interpolation is not parsed
+
+**Symptom:** `#[tag content]` appears as raw text instead of being expanded into markuplint nodes.
+
+**Cause:** The text node is not reaching the `HtmlInPugParser` path, or the `#ps:tag-interpolation` detection is failing.
+
+**Solution:**
+
+1. Check the `Text` case in `nodeize()` — ensure `originNode.raw.includes('#[')` evaluates to `true`
+2. Check the `HtmlInPugParser` — verify `ignoreTags` correctly masks `#[...]`
+3. Check the `#ps:tag-interpolation` detection — ensure `node.nodeName === '#ps:tag-interpolation'`
+4. Check the recursive `PugParser` call — verify offset context (`offsetOffset`, `offsetLine`, `offsetColumn`) is computed correctly
+
+### Attribute parsing fails for complex expressions
+
+**Symptom:** A Pug attribute with a complex JavaScript value (e.g., `data-value=obj.prop + 1`) causes a parse error or incorrect AST.
+
+**Cause:** The `scriptParser()` result is not being handled correctly for multi-token expressions.
+
+**Solution:**
+
+1. Check the `visitAttr()` method — the final `return` block handles multi-token expressions as `isDynamicValue: true, valueType: 'code'`
+2. Check `scriptParser()` from `@markuplint/parser-utils` — verify it correctly tokenizes the value expression
+3. For single-token expressions, verify the `switch (token.type)` handles the token type correctly
+
+### Shorthand attribute has wrong potentialName
+
+**Symptom:** `#my-id` or `.my-class` produces an attribute with the wrong `potentialName`.
+
+**Cause:** The shorthand detection or `endOffset` recalculation is wrong.
+
+**Solution:**
+
+1. Check the `#`/`.` branch in `visitAttr()` — ensure `potentialName` is set to `'id'` for `#` and `'class'` for `.`
+2. Check the `endOffset` recalculation in `nodeize()` Tag case — for shorthand attributes, `attr.offset === attr.endOffset` must be true, and `endOffset` should be `attr.offset + attr.val.length - 1`
+3. Verify the `val` value from the Pug AST — for `#my-id`, `val` should be `"'my-id'"` (with surrounding quotes)
+
+### Pipeless text not detected
+
+**Symptom:** Indented text after a tag with `.` is not treated as pipeless text.
+
+**Cause:** The `getPipelessText()` function is not finding `start-pipeless-text` / `end-pipeless-text` tokens, or the line range check is failing.
+
+**Solution:**
+
+1. Check the lexer output — verify that `start-pipeless-text` and `end-pipeless-text` tokens exist
+2. Check the line range: `startPipelessText.loc.start.line < node.line && node.line < endPipelessText.loc.start.line`
+3. If the tokens exist but the range is wrong, the issue may be in the pug-lexer version

package/lib/index.d.ts

@@ -1 +1,7 @@
+/**
+ * @module
+ * Pug template parser for markuplint. Provides a parser that transforms Pug (formerly Jade)
+ * template syntax into markuplint's AST, handling indentation-based nesting, tag interpolation,
+ * inline HTML, Pug attributes, mixins, conditionals, and other Pug-specific constructs.
+ */
 export { parser } from './parser.js';

package/lib/index.js

@@ -1 +1,7 @@
+/**
+ * @module
+ * Pug template parser for markuplint. Provides a parser that transforms Pug (formerly Jade)
+ * template syntax into markuplint's AST, handling indentation-based nesting, tag interpolation,
+ * inline HTML, Pug attributes, mixins, conditionals, and other Pug-specific constructs.
+ */
 export { parser } from './parser.js';

package/lib/parser.d.ts

@@ -2,6 +2,14 @@ import type { ASTNode } from './types.js';
 import type { MLASTAttr, MLASTNodeTreeItem, MLASTParentNode } from '@markuplint/ml-ast';
 import type { ChildToken, ParseOptions, Token } from '@markuplint/parser-utils';
 import { ParserError, Parser } from '@markuplint/parser-utils';
+/**
+ * Parser implementation for Pug templates.
+ * Extends the base Parser to handle Pug's indentation-based syntax, including tags,
+ * inline HTML, tag interpolation (`#[...]`), Pug attributes (including shorthand
+ * `#id` and `.class`), `&attributes` spread syntax, mixins, conditionals,
+ * and other Pug-specific constructs. Uses pug-lexer and pug-parser for
+ * initial tokenization before mapping to markuplint's node tree.
+ */
 declare class PugParser extends Parser<ASTNode> {
     constructor();
     tokenize(options?: ParseOptions): {
@@ -9,8 +17,30 @@ declare class PugParser extends Parser<ASTNode> {
         isFragment: boolean;
     };
     parseError(error: any): ParserError;
+    /**
+     * Converts a Pug AST node into markuplint node tree items.
+     * Handles Doctype, Text (including inline HTML and tag interpolation),
+     * Comment, BlockComment, Tag (with attributes and child blocks),
+     * and other Pug-specific constructs (mixins, conditionals, etc.)
+     * which are mapped to preprocessor-specific blocks.
+     *
+     * @param originNode - The Pug AST node to convert
+     * @param parentNode - The parent node in the markuplint tree, or null for root nodes
+     * @param depth - The nesting depth of the node
+     * @returns An array of markuplint node tree items
+     */
     nodeize(originNode: ASTNode, parentNode: MLASTParentNode | null, depth: number): readonly MLASTNodeTreeItem[];
     afterFlattenNodes(nodeList: readonly MLASTNodeTreeItem[]): readonly MLASTNodeTreeItem[];
+    /**
+     * Visits an element token for Pug, constructing a start tag node with
+     * pre-parsed attributes (including `&attributes` spread syntax) and
+     * visiting child nodes within the Pug block.
+     *
+     * @param token - The child token with tag metadata and namespace
+     * @param childNodes - The child Pug AST nodes within the tag's block
+     * @param options - Options containing pre-parsed attribute overrides
+     * @returns An array of markuplint node tree items for the element and its children
+     */
     visitElement(token: ChildToken & {
         readonly nodeName: string;
         readonly namespace: string;
@@ -21,6 +51,14 @@ declare class PugParser extends Parser<ASTNode> {
         };
     }): MLASTNodeTreeItem[];
     visitSpreadAttr(): null;
+    /**
+     * Visits an attribute token, handling Pug-specific syntax including
+     * shorthand `#id` and `.class` notation, quoted attribute names,
+     * unescaped attribute names (trailing `!`), and JavaScript expression values.
+     *
+     * @param token - The token representing the attribute
+     * @returns The parsed attribute node with Pug-specific metadata
+     */
     visitAttr(token: Token): MLASTAttr;
 }
 export declare const parser: PugParser;

package/lib/parser.js

@@ -1,6 +1,11 @@
 import { HtmlParser, getNamespace } from '@markuplint/html-parser';
 import { ParserError, Parser, AttrState, scriptParser } from '@markuplint/parser-utils';
 import { pugParse } from './pug-parser/index.js';
+/**
+ * Internal HTML parser used for inline HTML content within Pug templates.
+ * Extends the standard HTML parser to handle Pug tag interpolation syntax (`#[...]`),
+ * treating interpolated tags as preprocessor-specific blocks.
+ */
 class HtmlInPugParser extends HtmlParser {
     constructor() {
         super({
@@ -19,6 +24,14 @@ class HtmlInPugParser extends HtmlParser {
         });
     }
 }
+/**
+ * Parser implementation for Pug templates.
+ * Extends the base Parser to handle Pug's indentation-based syntax, including tags,
+ * inline HTML, tag interpolation (`#[...]`), Pug attributes (including shorthand
+ * `#id` and `.class`), `&attributes` spread syntax, mixins, conditionals,
+ * and other Pug-specific constructs. Uses pug-lexer and pug-parser for
+ * initial tokenization before mapping to markuplint's node tree.
+ */
 class PugParser extends Parser {
     constructor() {
         super({
@@ -43,6 +56,18 @@ class PugParser extends Parser {
         }
         return super.parseError(error);
     }
+    /**
+     * Converts a Pug AST node into markuplint node tree items.
+     * Handles Doctype, Text (including inline HTML and tag interpolation),
+     * Comment, BlockComment, Tag (with attributes and child blocks),
+     * and other Pug-specific constructs (mixins, conditionals, etc.)
+     * which are mapped to preprocessor-specific blocks.
+     *
+     * @param originNode - The Pug AST node to convert
+     * @param parentNode - The parent node in the markuplint tree, or null for root nodes
+     * @param depth - The nesting depth of the node
+     * @returns An array of markuplint node tree items
+     */
     nodeize(
     // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
     originNode, parentNode, depth) {
@@ -189,6 +214,16 @@ class PugParser extends Parser {
             exposeWhiteSpace: false,
         });
     }
+    /**
+     * Visits an element token for Pug, constructing a start tag node with
+     * pre-parsed attributes (including `&attributes` spread syntax) and
+     * visiting child nodes within the Pug block.
+     *
+     * @param token - The child token with tag metadata and namespace
+     * @param childNodes - The child Pug AST nodes within the tag's block
+     * @param options - Options containing pre-parsed attribute overrides
+     * @returns An array of markuplint node tree items for the element and its children
+     */
     visitElement(token, 
     // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
     childNodes, options) {
@@ -210,6 +245,14 @@ class PugParser extends Parser {
     visitSpreadAttr() {
         return null;
     }
+    /**
+     * Visits an attribute token, handling Pug-specific syntax including
+     * shorthand `#id` and `.class` notation, quoted attribute names,
+     * unescaped attribute names (trailing `!`), and JavaScript expression values.
+     *
+     * @param token - The token representing the attribute
+     * @returns The parsed attribute node with Pug-specific metadata
+     */
     visitAttr(token) {
         if (token.raw[0] === '#' || token.raw[0] === '.') {
             const attr = super.visitAttr(token, {

package/lib/pug-parser/index.d.ts

@@ -1,2 +1,11 @@
 import type { ASTBlock } from '../types.js';
+/**
+ * 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 declare function pugParse(pug: string, useOffset?: boolean): ASTBlock;