@markuplint/ml-ast 4.4.10-dev.350 → 4.4.11

package/SKILL.md

@@ -0,0 +1,124 @@
+---
+description: Perform maintenance tasks for @markuplint/ml-ast
+---
+
+# ml-ast-maintenance
+
+Perform maintenance tasks for `@markuplint/ml-ast`: add AST node types,
+add fields to existing nodes, add conditional type values, and update the parser interface.
+
+## Input
+
+`$ARGUMENTS` specifies the task. Supported tasks:
+
+| Task                           | Description                                    |
+| ------------------------------ | ---------------------------------------------- |
+| `add-node-type <name>`         | Add a new AST node type                        |
+| `add-field <node> <field>`     | Add a field to an existing node type           |
+| `add-conditional-type <value>` | Add a conditional type value for psblock nodes |
+| `update-parser-interface`      | Modify the MLParser interface                  |
+
+If omitted, defaults to `add-node-type`.
+
+## Reference
+
+Before executing any task, read `docs/maintenance.md` (or `docs/maintenance.ja.md`)
+for the full guide. The recipes there are the source of truth for procedures.
+
+Also read:
+
+- `docs/node-reference.md` -- Detailed documentation of each AST node type
+- `ARCHITECTURE.md` -- Package overview, type hierarchy, and integration points
+
+## Task: add-node-type
+
+Add a new AST node type. Follow recipe #1 in `docs/maintenance.md`.
+
+### Step 1: Define the type
+
+1. Read `src/types.ts` to understand the existing type hierarchy
+2. Add the type value to `MLASTNodeType`
+3. Define the interface extending `MLASTAbstractNode`
+4. Add to relevant union types (`MLASTNode`, `MLASTChildNode`, etc.)
+
+### Step 2: Update downstream
+
+1. Update `ml-core`'s `createNode()` in `packages/@markuplint/ml-core/src/ml-dom/helper/create-node.ts`
+2. Add a `case` for the new type value in the `switch` statement
+3. Create or reuse an appropriate DOM node class
+
+### Step 3: Build and verify
+
+1. Build: `yarn build --scope @markuplint/ml-ast`
+2. Build: `yarn build --scope @markuplint/ml-core`
+3. Check the downstream impact checklist in `docs/maintenance.md`
+
+## Task: add-field
+
+Add a field to an existing node type. Follow recipe #2 in `docs/maintenance.md`.
+
+### Step 1: Add the field
+
+1. Read `src/types.ts` and find the target interface
+2. Add the field (prefer optional `?` for backward compatibility)
+3. Add JSDoc documentation for the new field
+
+### Step 2: Update consumers
+
+1. Update parsers that should populate the new field
+2. Update `ml-core` if the field affects DOM node creation
+
+### Step 3: Build and verify
+
+1. Build: `yarn build --scope @markuplint/ml-ast`
+2. Build affected packages
+3. Check the downstream impact checklist in `docs/maintenance.md`
+
+## Task: add-conditional-type
+
+Add a conditional type value for preprocessor-specific blocks. Follow recipe #4 in `docs/maintenance.md`.
+
+### Step 1: Add the value
+
+1. Read `src/types.ts` and find `MLASTPreprocessorSpecificBlockConditionalType`
+2. Add the new value to the union type
+3. Document the value's semantic meaning in the JSDoc comment
+
+### Step 2: Update parsers
+
+1. Update the parser that produces blocks with this conditional type
+2. Verify the value follows the naming convention (`category:variant`, e.g., `if:elseif`)
+
+### Step 3: Build and verify
+
+1. Build: `yarn build --scope @markuplint/ml-ast`
+2. Build the affected parser package
+
+## Task: update-parser-interface
+
+Modify the `MLParser` interface. Follow recipe #5 in `docs/maintenance.md`.
+
+### Step 1: Make changes
+
+1. Read `src/types.ts` and find `MLParser`
+2. Make changes (prefer adding optional fields for backward compatibility)
+3. Update `MLMarkupLanguageParser` (deprecated) if needed for consistency
+
+### Step 2: Update all parsers
+
+1. Update all parser implementations (see the list in `docs/maintenance.md` recipe #5)
+2. Update `@markuplint/parser-utils` if it provides shared implementation
+
+### Step 3: Build and verify
+
+1. Build all packages: `yarn build`
+2. Run all tests: `yarn test`
+
+## Rules
+
+1. **All node types extend `MLASTAbstractNode`** (except attributes which extend `MLASTToken`).
+2. **Use `readonly` for all interface fields.** The AST is immutable after parsing.
+3. **Prefer optional fields** when adding to existing interfaces for backward compatibility.
+4. **Always update `createNode()` in `ml-core`** when adding new node types.
+5. **Follow the discriminated union pattern.** Every node must have a unique `type` literal value.
+6. **Add JSDoc comments** to all new exported types and fields.

package/docs/maintenance.ja.md

@@ -0,0 +1,215 @@
+# メンテナンスガイド
+
+`@markuplint/ml-ast` の実践的な操作・メンテナンスガイドです。
+
+## コマンド
+
+| コマンド                                      | 説明                              |
+| --------------------------------------------- | --------------------------------- |
+| `yarn build --scope @markuplint/ml-ast`       | TypeScript を `lib/` にコンパイル |
+| `yarn workspace @markuplint/ml-ast run dev`   | ウォッチモードコンパイル          |
+| `yarn workspace @markuplint/ml-ast run clean` | コンパイル出力をクリーン          |
+
+## テスト
+
+このパッケージには**テストファイルがありません**。純粋な型定義パッケージのため、正当性はビルド時に TypeScript コンパイラで検証されます。統合テストはこれらの型を消費する下流パッケージで実施されます。
+
+型の正当性を検証するには：
+
+```bash
+yarn build --scope @markuplint/ml-ast
+```
+
+## 一般的なレシピ
+
+### 1. 新しいノード型の追加
+
+新しい AST ノード型（例：仮想的な `MLASTDirective`）を追加する場合：
+
+1. **`MLASTNodeType` に型の値を追加**（`src/types.ts`）：
+
+   ```typescript
+   export type MLASTNodeType =
+     | 'doctype'
+     | 'starttag'
+     // ... 既存の値
+     | 'directive'; // ここに追加
+   ```
+
+2. **`MLASTAbstractNode` を継承するインターフェースを定義**：
+
+   ```typescript
+   export interface MLASTDirective extends MLASTAbstractNode {
+     readonly type: 'directive';
+     readonly depth: number;
+     // 型固有のフィールドを追加
+   }
+   ```
+
+3. **関連する共用体型に追加**：
+   - `MLASTNode` -- 常にこの共用体に追加
+   - `MLASTChildNode` -- 要素の子になれる場合
+   - `MLASTNodeTreeItem` -- `nodeList` のトップレベルに出現できる場合
+   - `MLASTParentNode` -- 子ノードを含むことができる場合
+
+4. **`ml-core` の `createNode()` を更新**（`packages/@markuplint/ml-core/src/ml-dom/helper/create-node.ts`）：
+   - `switch` 文に新しい type 値の `case` を追加
+   - 適切な DOM ノードクラスを作成または再利用
+
+5. **このノード型を生成するパーサーを更新**
+
+6. **ビルドして検証**：
+   ```bash
+   yarn build --scope @markuplint/ml-ast
+   yarn build --scope @markuplint/ml-core
+   ```
+
+### 2. 既存ノード型へのフィールド追加
+
+既存のノードインターフェースに新しいフィールドを追加する場合：
+
+1. **`src/types.ts` のインターフェースにフィールドを追加**：
+
+   ```typescript
+   export interface MLASTElement extends MLASTAbstractNode {
+     // ... 既存のフィールド
+     readonly newField: string; // 必須フィールド
+     readonly optionalField?: boolean; // オプションフィールド（後方互換性のため推奨）
+   }
+   ```
+
+2. **後方互換性のためオプションフィールド**（`?`）を推奨 -- フィールドがなくても既存のパーサーが壊れません。
+
+3. **新しいフィールドを設定するパーサーを更新**
+
+4. **フィールドが DOM ノードの作成や動作に影響する場合は `ml-core` を更新**
+
+5. **全チェーンをビルド**：
+   ```bash
+   yarn build --scope @markuplint/ml-ast
+   yarn build --scope @markuplint/ml-core
+   ```
+
+### 3. 新しい属性バリアントの追加
+
+`MLASTHTMLAttr` と `MLASTSpreadAttr` に加えて新しい属性型を追加する場合：
+
+1. **`MLASTNodeType` に型の値を追加**（まだない場合）
+
+2. **`MLASTToken` を継承するインターフェースを定義**：
+
+   ```typescript
+   export interface MLASTNewAttr extends MLASTToken {
+     readonly type: 'newattr';
+     readonly nodeName: string;
+     // 属性固有のフィールドを追加
+   }
+   ```
+
+3. **`MLASTAttr` 共用体に追加**：
+
+   ```typescript
+   export type MLASTAttr = MLASTHTMLAttr | MLASTSpreadAttr | MLASTNewAttr;
+   ```
+
+4. **属性型で switch する下流の消費者を更新**
+
+5. **ビルドして検証**
+
+### 4. `PreprocessorSpecificBlockConditionalType` の値追加
+
+プリプロセッサブロックの新しい conditional type 値を追加する場合：
+
+1. **`src/types.ts` の `MLASTPreprocessorSpecificBlockConditionalType` に値を追加**：
+
+   ```typescript
+   export type MLASTPreprocessorSpecificBlockConditionalType =
+     | 'if'
+     | 'if:elseif'
+     // ... 既存の値
+     | 'newvalue' // ここに追加
+     | null;
+   ```
+
+2. **この conditional type でブロックを生成するパーサーを更新**
+
+3. **新しい値が DOM 作成時に特別な処理を必要とする場合は `ml-core` を更新**
+
+4. **ビルドして検証**：
+   ```bash
+   yarn build --scope @markuplint/ml-ast
+   ```
+
+### 5. `MLParser` インターフェースの変更
+
+パーサーインターフェースを変更する場合：
+
+1. **`src/types.ts` の `MLParser` を変更**
+
+2. **後方互換性を考慮**：
+   - オプションフィールドの追加は安全
+   - 必須フィールドの追加やシグネチャの変更は破壊的変更
+   - 一貫性のため必要に応じて `MLMarkupLanguageParser`（非推奨）も更新
+
+3. **すべてのパーサー実装を更新**：
+   - `@markuplint/html-parser`
+   - `@markuplint/jsx-parser`
+   - `@markuplint/vue-parser`
+   - `@markuplint/svelte-parser`
+   - `@markuplint/astro-parser`
+   - `@markuplint/pug-parser`
+   - `@markuplint/parser-utils`
+
+4. **影響を受けるすべてのパッケージをビルド**：
+   ```bash
+   yarn build
+   ```
+
+## 下流影響チェックリスト
+
+このパッケージの型を変更する際、以下の下流パッケージがビルド・テストに通ることを確認してください：
+
+- [ ] `@markuplint/html-parser` -- HTML パーサー
+- [ ] `@markuplint/parser-utils` -- パーサーユーティリティ関数
+- [ ] `@markuplint/jsx-parser` -- JSX パーサー
+- [ ] `@markuplint/astro-parser` -- Astro パーサー
+- [ ] `@markuplint/vue-parser` -- Vue SFC パーサー
+- [ ] `@markuplint/svelte-parser` -- Svelte パーサー
+- [ ] `@markuplint/pug-parser` -- Pug パーサー
+- [ ] `@markuplint/ml-core` -- コア DOM マッピング（最重要）
+- [ ] `@markuplint/ml-config` -- 設定型
+- [ ] `@markuplint/ml-spec` -- 仕様型
+- [ ] `@markuplint/file-resolver` -- ファイル解決
+
+最も重要な下流パッケージは `@markuplint/ml-core` で、`createNode()` -- `node.type` に対する `switch` 文で AST ノードを DOM ノードにマッピングする関数を含みます。
+
+## トラブルシューティング
+
+### 型変更後のビルドエラー
+
+**症状：** 型の変更後、下流パッケージのビルドが失敗する。
+
+**診断：**
+
+1. まずこのパッケージをビルド：`yarn build --scope @markuplint/ml-ast`
+2. 次に `ml-core` をビルド：`yarn build --scope @markuplint/ml-core`
+3. `switch` の網羅性エラーを確認 -- TypeScript は `node.type` の `switch` で新しい型値のケースが欠けている場合に報告します
+4. 共用体型の不一致を確認 -- 共用体に型を追加すると、既存の絞り込みコードの更新が必要になる場合があります
+
+### ml-core の `createNode()` のケース漏れ
+
+**症状：** 実行時に `TypeError: Invalid AST node types "newtype"` が発生する。
+
+**原因：** 新しいノード型が `MLASTNodeType` と関連する共用体型に追加されたが、`ml-core` の `createNode()` の switch 文が更新されていない。
+
+**修正：** `packages/@markuplint/ml-core/src/ml-dom/helper/create-node.ts` に新しい型の `case` を追加してください。
+
+### パーサーが期待されるノードを生成しない
+
+**症状：** パーサーが新しく追加されたフィールドや型のノードを生成しない。
+
+**診断：**
+
+1. パーサーの実装が新しいフィールドを設定するように更新されているか確認
+2. オプションフィールドの場合、フィールドが暗黙的に `undefined` になっていないか検証
+3. パーサーとこのパッケージの両方をビルドして型の整合性を確認

package/docs/maintenance.md

@@ -0,0 +1,215 @@
+# Maintenance Guide
+
+Practical operations and maintenance guide for `@markuplint/ml-ast`.
+
+## Commands
+
+| Command                                       | Description                  |
+| --------------------------------------------- | ---------------------------- |
+| `yarn build --scope @markuplint/ml-ast`       | Compile TypeScript to `lib/` |
+| `yarn workspace @markuplint/ml-ast run dev`   | Watch mode compilation       |
+| `yarn workspace @markuplint/ml-ast run clean` | Clean compiled output        |
+
+## Testing
+
+This package has **no test files**. It is a pure type-definition package, so correctness is verified by the TypeScript compiler during build. Integration testing is performed by downstream packages that consume these types.
+
+To verify type correctness:
+
+```bash
+yarn build --scope @markuplint/ml-ast
+```
+
+## Common Recipes
+
+### 1. Adding a New Node Type
+
+To add a new AST node type (e.g., a hypothetical `MLASTDirective`):
+
+1. **Add the type value to `MLASTNodeType`** in `src/types.ts`:
+
+   ```typescript
+   export type MLASTNodeType =
+     | 'doctype'
+     | 'starttag'
+     // ... existing values
+     | 'directive'; // Add here
+   ```
+
+2. **Define the interface** extending `MLASTAbstractNode`:
+
+   ```typescript
+   export interface MLASTDirective extends MLASTAbstractNode {
+     readonly type: 'directive';
+     readonly depth: number;
+     // Add type-specific fields
+   }
+   ```
+
+3. **Add to relevant union types**:
+   - `MLASTNode` -- Always add to this union
+   - `MLASTChildNode` -- If it can be a child of elements
+   - `MLASTNodeTreeItem` -- If it can appear at the top level of `nodeList`
+   - `MLASTParentNode` -- If it can contain child nodes
+
+4. **Update `ml-core`'s `createNode()`** in `packages/@markuplint/ml-core/src/ml-dom/helper/create-node.ts`:
+   - Add a `case` for the new type value in the `switch` statement
+   - Create or reuse an appropriate DOM node class
+
+5. **Update parsers** that should produce this node type
+
+6. **Build and verify**:
+   ```bash
+   yarn build --scope @markuplint/ml-ast
+   yarn build --scope @markuplint/ml-core
+   ```
+
+### 2. Adding a Field to an Existing Node Type
+
+To add a new field to an existing node interface:
+
+1. **Add the field** to the interface in `src/types.ts`:
+
+   ```typescript
+   export interface MLASTElement extends MLASTAbstractNode {
+     // ... existing fields
+     readonly newField: string; // Required field
+     readonly optionalField?: boolean; // Optional field (prefer for backward compat)
+   }
+   ```
+
+2. **Prefer optional fields** (`?`) for backward compatibility -- existing parsers will not break if the field is missing.
+
+3. **Update parsers** that should populate the new field.
+
+4. **Update `ml-core`** if the field affects DOM node creation or behavior.
+
+5. **Build the full chain**:
+   ```bash
+   yarn build --scope @markuplint/ml-ast
+   yarn build --scope @markuplint/ml-core
+   ```
+
+### 3. Adding a New Attribute Variant
+
+To add a new attribute type alongside `MLASTHTMLAttr` and `MLASTSpreadAttr`:
+
+1. **Add the type value to `MLASTNodeType`** (if not already present)
+
+2. **Define the interface** extending `MLASTToken`:
+
+   ```typescript
+   export interface MLASTNewAttr extends MLASTToken {
+     readonly type: 'newattr';
+     readonly nodeName: string;
+     // Add attribute-specific fields
+   }
+   ```
+
+3. **Add to `MLASTAttr` union**:
+
+   ```typescript
+   export type MLASTAttr = MLASTHTMLAttr | MLASTSpreadAttr | MLASTNewAttr;
+   ```
+
+4. **Update downstream consumers** that switch on attribute types
+
+5. **Build and verify**
+
+### 4. Adding a `PreprocessorSpecificBlockConditionalType` Value
+
+To add a new conditional type value for preprocessor blocks:
+
+1. **Add the value** to `MLASTPreprocessorSpecificBlockConditionalType` in `src/types.ts`:
+
+   ```typescript
+   export type MLASTPreprocessorSpecificBlockConditionalType =
+     | 'if'
+     | 'if:elseif'
+     // ... existing values
+     | 'newvalue' // Add here
+     | null;
+   ```
+
+2. **Update the parser** that produces blocks with this conditional type
+
+3. **Update `ml-core`** if the new value requires special handling during DOM creation
+
+4. **Build and verify**:
+   ```bash
+   yarn build --scope @markuplint/ml-ast
+   ```
+
+### 5. Modifying the `MLParser` Interface
+
+When changing the parser interface:
+
+1. **Make changes** to `MLParser` in `src/types.ts`
+
+2. **Consider backward compatibility**:
+   - Adding optional fields is safe
+   - Adding required fields or changing signatures is a breaking change
+   - Update `MLMarkupLanguageParser` (deprecated) if needed for consistency
+
+3. **Update all parser implementations**:
+   - `@markuplint/html-parser`
+   - `@markuplint/jsx-parser`
+   - `@markuplint/vue-parser`
+   - `@markuplint/svelte-parser`
+   - `@markuplint/astro-parser`
+   - `@markuplint/pug-parser`
+   - `@markuplint/parser-utils`
+
+4. **Build all affected packages**:
+   ```bash
+   yarn build
+   ```
+
+## Downstream Impact Checklist
+
+When modifying types in this package, verify that these downstream packages still build and pass tests:
+
+- [ ] `@markuplint/html-parser` -- HTML parser
+- [ ] `@markuplint/parser-utils` -- Parser utility functions
+- [ ] `@markuplint/jsx-parser` -- JSX parser
+- [ ] `@markuplint/astro-parser` -- Astro parser
+- [ ] `@markuplint/vue-parser` -- Vue SFC parser
+- [ ] `@markuplint/svelte-parser` -- Svelte parser
+- [ ] `@markuplint/pug-parser` -- Pug parser
+- [ ] `@markuplint/ml-core` -- Core DOM mapping (most critical)
+- [ ] `@markuplint/ml-config` -- Configuration types
+- [ ] `@markuplint/ml-spec` -- Specification types
+- [ ] `@markuplint/file-resolver` -- File resolution
+
+The most critical downstream package is `@markuplint/ml-core`, which contains `createNode()` -- the function that maps AST nodes to DOM nodes via a `switch` statement on `node.type`.
+
+## Troubleshooting
+
+### Build Errors After Type Changes
+
+**Symptom:** Downstream packages fail to build after modifying types.
+
+**Diagnosis:**
+
+1. Build this package first: `yarn build --scope @markuplint/ml-ast`
+2. Build `ml-core` next: `yarn build --scope @markuplint/ml-core`
+3. Check for `switch` exhaustiveness errors -- TypeScript will report if a `switch` on `node.type` is missing a case for a new type value
+4. Check for union type mismatches -- adding a type to a union may cause existing narrowing code to need updates
+
+### Missing Case in ml-core's `createNode()`
+
+**Symptom:** `TypeError: Invalid AST node types "newtype"` at runtime.
+
+**Cause:** A new node type was added to `MLASTNodeType` and the relevant union types, but `ml-core`'s `createNode()` switch statement was not updated.
+
+**Fix:** Add a `case` for the new type in `packages/@markuplint/ml-core/src/ml-dom/helper/create-node.ts`.
+
+### Parser Not Producing Expected Nodes
+
+**Symptom:** A parser does not produce nodes with newly added fields or types.
+
+**Diagnosis:**
+
+1. Check that the parser implementation has been updated to populate new fields
+2. For optional fields, verify that the field is not silently `undefined`
+3. Build both the parser and this package to ensure type alignment