@markuplint/ml-ast 5.0.0-rc.2 → 5.0.0-rc.5

package/docs/maintenance.md

@@ -1,214 +0,0 @@
-# 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
-
-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