@markuplint/ml-ast 4.4.10 → 5.0.0-alpha.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (11) hide show
  1. package/ARCHITECTURE.ja.md +310 -0
  2. package/ARCHITECTURE.md +310 -0
  3. package/CHANGELOG.md +45 -0
  4. package/README.md +6 -0
  5. package/SKILL.md +123 -0
  6. package/docs/maintenance.ja.md +213 -0
  7. package/docs/maintenance.md +214 -0
  8. package/docs/node-reference.ja.md +487 -0
  9. package/docs/node-reference.md +487 -0
  10. package/lib/types.d.ts +204 -41
  11. package/package.json +5 -2
package/lib/types.d.ts CHANGED
@@ -1,3 +1,17 @@
1
+ /**
2
+ * Discriminant union tag representing the kind of AST node.
3
+ *
4
+ * - `'doctype'` – A DOCTYPE declaration node
5
+ * - `'starttag'` – An opening element tag
6
+ * - `'endtag'` – A closing element tag
7
+ * - `'comment'` – An HTML comment
8
+ * - `'text'` – A text node
9
+ * - `'omittedtag'`– An omitted tag (e.g. implicit `<tbody>`)
10
+ * - `'psblock'` – A preprocessor-specific block (template engine constructs)
11
+ * - `'invalid'` – A node that could not be parsed correctly
12
+ * - `'attr'` – A regular HTML attribute
13
+ * - `'spread'` – A spread attribute (e.g. `{...props}` in JSX)
14
+ */
1
15
  export type MLASTNodeType = 'doctype' | 'starttag' | 'endtag' | 'comment' | 'text' | 'omittedtag' | 'psblock' | 'invalid' | 'attr' | 'spread';
2
16
  /**
3
17
  * Element type
@@ -7,145 +21,258 @@ export type MLASTNodeType = 'doctype' | 'starttag' | 'endtag' | 'comment' | 'tex
7
21
  * - `authored`: Authored element (JSX Element etc.) through the view framework or the template engine.
8
22
  */
9
23
  export type ElementType = 'html' | 'web-component' | 'authored';
24
+ /**
25
+ * Union of every possible AST node type produced by a markuplint parser.
26
+ */
10
27
  export type MLASTNode = MLASTDoctype | MLASTTag | MLASTComment | MLASTText | MLASTPreprocessorSpecificBlock | MLASTInvalid | MLASTAttr;
28
+ /**
29
+ * Nodes that can act as a parent in the AST tree (i.e. contain child nodes).
30
+ */
11
31
  export type MLASTParentNode = MLASTElement | MLASTPreprocessorSpecificBlock;
32
+ /**
33
+ * Top-level items in the AST node tree: either child nodes or a DOCTYPE declaration.
34
+ */
12
35
  export type MLASTNodeTreeItem = MLASTChildNode | MLASTDoctype;
36
+ /**
37
+ * Nodes that can appear as children within an element or preprocessor block.
38
+ */
13
39
  export type MLASTChildNode = MLASTTag | MLASTText | MLASTComment | MLASTPreprocessorSpecificBlock | MLASTInvalid;
40
+ /**
41
+ * A tag node: either an opening element or a closing element tag.
42
+ */
14
43
  export type MLASTTag = MLASTElement | MLASTElementCloseTag;
44
+ /**
45
+ * An attribute node: either a regular HTML attribute or a spread attribute.
46
+ */
15
47
  export type MLASTAttr = MLASTHTMLAttr | MLASTSpreadAttr;
48
+ /**
49
+ * Base token representing a span of source text with positional information.
50
+ * Every AST node ultimately extends this interface.
51
+ *
52
+ * End positions (`endOffset`, `endLine`, `endCol`) are not stored;
53
+ * they can be derived from `offset + raw.length`, or via helper utilities
54
+ * in `@markuplint/parser-utils`.
55
+ */
16
56
  export interface MLASTToken {
57
+ /** Unique identifier for this token instance */
17
58
  readonly uuid: string;
59
+ /** The original raw source text of this token */
18
60
  readonly raw: string;
19
- readonly startOffset: number;
20
- readonly endOffset: number;
21
- readonly startLine: number;
22
- readonly endLine: number;
23
- readonly startCol: number;
24
- readonly endCol: number;
61
+ /** Zero-based character offset of the token start in the source */
62
+ readonly offset: number;
63
+ /** One-based line number where the token starts */
64
+ readonly line: number;
65
+ /** One-based column number where the token starts */
66
+ readonly col: number;
25
67
  }
68
+ /**
69
+ * Abstract base for all AST nodes. Extends {@link MLASTToken} with
70
+ * a discriminant `type`, a `nodeName`, and a reference to the parent node.
71
+ */
26
72
  interface MLASTAbstractNode extends MLASTToken {
73
+ /** Discriminant tag identifying the concrete node kind */
27
74
  readonly type: MLASTNodeType;
75
+ /** The node name (tag name, `#text`, `#comment`, etc.) */
28
76
  readonly nodeName: string;
77
+ /** Reference to the parent node, or `null` for top-level nodes */
29
78
  readonly parentNode: MLASTParentNode | null;
30
79
  }
80
+ /**
81
+ * A DOCTYPE declaration node (e.g. `<!DOCTYPE html>`).
82
+ */
31
83
  export interface MLASTDoctype extends MLASTAbstractNode {
32
84
  readonly type: 'doctype';
85
+ /** Nesting depth in the document tree (always 0 for DOCTYPE) */
33
86
  readonly depth: number;
87
+ /** The declared document type name (e.g. `"html"`) */
34
88
  readonly name: string;
89
+ /** The public identifier of the DOCTYPE, if any */
35
90
  readonly publicId: string;
91
+ /** The system identifier of the DOCTYPE, if any */
36
92
  readonly systemId: string;
37
93
  }
94
+ /**
95
+ * An opening element tag (e.g. `<div class="foo">`).
96
+ * This is the primary element representation in the AST and owns
97
+ * child nodes, attributes, and a reference to its closing tag.
98
+ */
38
99
  export interface MLASTElement extends MLASTAbstractNode {
39
100
  readonly type: 'starttag';
101
+ /** Nesting depth in the document tree */
40
102
  readonly depth: number;
41
- readonly namespace: string;
103
+ /** Namespace URI of the element (e.g. `"http://www.w3.org/1999/xhtml"`) */
104
+ readonly namespace: NamespaceURI;
105
+ /** Whether the element is native HTML, a Web Component, or an authored component */
42
106
  readonly elementType: ElementType;
107
+ /** Whether this element acts as a fragment (no actual DOM node) */
43
108
  readonly isFragment: boolean;
109
+ /** Attributes on this element */
44
110
  readonly attributes: readonly MLASTAttr[];
111
+ /** Whether the element has one or more spread attributes */
45
112
  readonly hasSpreadAttr?: boolean;
113
+ /** Direct child nodes of this element */
46
114
  readonly childNodes: readonly MLASTChildNode[];
115
+ /** Block behavior associated with this element, if any */
116
+ readonly blockBehavior: MLASTBlockBehavior | null;
117
+ /** The matching closing tag, or `null` for void / self-closing elements */
47
118
  readonly pairNode: MLASTElementCloseTag | null;
48
- readonly selfClosingSolidus?: MLASTToken;
119
+ /** The characters that open this tag (usually `"<"`) */
49
120
  readonly tagOpenChar: string;
121
+ /** The characters that close this tag (usually `">"`) */
50
122
  readonly tagCloseChar: string;
123
+ /** Whether this element is a ghost node (omitted tag inferred by the parser) */
51
124
  readonly isGhost: boolean;
52
125
  }
126
+ /**
127
+ * A closing element tag (e.g. `</div>`).
128
+ * Always paired with an {@link MLASTElement} via `pairNode`.
129
+ */
53
130
  export interface MLASTElementCloseTag extends MLASTAbstractNode {
54
131
  readonly type: 'endtag';
132
+ /** Nesting depth in the document tree */
55
133
  readonly depth: number;
134
+ /** Closing tags do not have a parent node in the AST */
56
135
  readonly parentNode: null;
136
+ /** The matching opening element tag */
57
137
  readonly pairNode: MLASTElement;
138
+ /** The characters that open this tag (usually `"</"`) */
58
139
  readonly tagOpenChar: string;
140
+ /** The characters that close this tag (usually `">"`) */
59
141
  readonly tagCloseChar: string;
60
142
  }
143
+ /**
144
+ * A preprocessor-specific block node, representing control-flow constructs
145
+ * from template engines and frameworks (e.g. `{#if}`, `{#each}` in Svelte,
146
+ * `v-if` blocks in Vue, `<% if %>` in EJS/ERB).
147
+ */
61
148
  export interface MLASTPreprocessorSpecificBlock extends MLASTAbstractNode {
62
149
  readonly type: 'psblock';
63
- readonly conditionalType: MLASTPreprocessorSpecificBlockConditionalType;
150
+ /** Nesting depth in the document tree */
64
151
  readonly depth: number;
152
+ /** The block's name as determined by the parser */
65
153
  readonly nodeName: string;
154
+ /** Whether this block acts as a transparent fragment */
66
155
  readonly isFragment: boolean;
156
+ /** Direct child nodes within this block */
67
157
  readonly childNodes: readonly MLASTChildNode[];
158
+ /** Block behavior associated with this block, if any */
159
+ readonly blockBehavior: MLASTBlockBehavior | null;
160
+ /** Whether this block is bogus (unparsable or malformed) */
68
161
  readonly isBogus: boolean;
69
162
  }
70
- export type MLASTPreprocessorSpecificBlockConditionalType = 'if' | 'if:elseif' | 'if:else' | 'switch:case' | 'switch:default' | 'each' | 'each:empty' | 'await' | 'await:then' | 'await:catch' | 'end' | null;
163
+ /**
164
+ * Describes the behavior of a preprocessor block or element,
165
+ * capturing both the kind of control-flow construct and the
166
+ * source expression that drives it.
167
+ */
168
+ export interface MLASTBlockBehavior {
169
+ /** The kind of block behavior (e.g. `'if'`, `'each'`, `'await'`) */
170
+ readonly type: MLASTBlockBehaviorType;
171
+ /** The source expression associated with this block */
172
+ readonly expression: string;
173
+ }
174
+ /**
175
+ * The type of control-flow construct represented by a block behavior.
176
+ */
177
+ export type MLASTBlockBehaviorType = 'if' | 'if:elseif' | 'if:else' | 'switch:case' | 'switch:default' | 'each' | 'each:empty' | 'await' | 'await:then' | 'await:catch' | 'end';
178
+ /**
179
+ * An HTML comment node (e.g. `<!-- ... -->`).
180
+ */
71
181
  export interface MLASTComment extends MLASTAbstractNode {
72
182
  readonly type: 'comment';
73
183
  readonly nodeName: '#comment';
184
+ /** Nesting depth in the document tree */
74
185
  readonly depth: number;
186
+ /** Whether the comment is bogus (e.g. a malformed comment) */
75
187
  readonly isBogus: boolean;
76
188
  }
189
+ /**
190
+ * A text node containing character data between elements.
191
+ */
77
192
  export interface MLASTText extends MLASTAbstractNode {
78
193
  readonly type: 'text';
79
194
  readonly nodeName: '#text';
195
+ /** Nesting depth in the document tree */
80
196
  readonly depth: number;
81
197
  }
198
+ /**
199
+ * A node representing markup that could not be parsed correctly.
200
+ * Always marked as bogus.
201
+ */
82
202
  export interface MLASTInvalid extends MLASTAbstractNode {
83
203
  readonly type: 'invalid';
84
204
  readonly nodeName: '#invalid';
205
+ /** Nesting depth in the document tree */
85
206
  readonly depth: number;
207
+ /** The kind of node this was intended to be before parsing failed */
86
208
  readonly kind?: Exclude<MLASTChildNode['type'], 'invalid'>;
209
+ /** Invalid nodes are always bogus */
87
210
  readonly isBogus: true;
88
211
  }
212
+ /**
213
+ * A regular HTML attribute node, decomposed into its constituent tokens
214
+ * (name, equal sign, quotes, value, and surrounding whitespace).
215
+ */
89
216
  export interface MLASTHTMLAttr extends MLASTToken {
90
217
  readonly type: 'attr';
218
+ /** The attribute name as a string */
91
219
  readonly nodeName: string;
220
+ /** Whitespace token before the attribute name */
92
221
  readonly spacesBeforeName: MLASTToken;
222
+ /** The attribute name token */
93
223
  readonly name: MLASTToken;
224
+ /** Whitespace token between the name and the equal sign */
94
225
  readonly spacesBeforeEqual: MLASTToken;
226
+ /** The equal sign token */
95
227
  readonly equal: MLASTToken;
228
+ /** Whitespace token between the equal sign and the value */
96
229
  readonly spacesAfterEqual: MLASTToken;
230
+ /** The opening quote token */
97
231
  readonly startQuote: MLASTToken;
232
+ /** The attribute value token */
98
233
  readonly value: MLASTToken;
234
+ /** The closing quote token */
99
235
  readonly endQuote: MLASTToken;
236
+ /** Whether the value is a dynamic expression (e.g. a binding in a framework) */
100
237
  readonly isDynamicValue?: true;
238
+ /** Whether the attribute is a framework directive (e.g. `v-if`, `@click`) */
101
239
  readonly isDirective?: true;
240
+ /** The resolved attribute name when the actual name is a framework-specific directive */
102
241
  readonly potentialName?: string;
242
+ /** The resolved attribute value when the actual value is dynamic */
103
243
  readonly potentialValue?: string;
244
+ /** The semantic type of the attribute value */
104
245
  readonly valueType?: 'string' | 'number' | 'boolean' | 'code';
246
+ /** A candidate attribute name for auto-correction */
105
247
  readonly candidate?: string;
248
+ /** Whether this attribute is allowed to appear multiple times on the same element */
106
249
  readonly isDuplicatable: boolean;
107
250
  }
251
+ /**
252
+ * A spread attribute node (e.g. `{...props}` in JSX).
253
+ */
108
254
  export interface MLASTSpreadAttr extends MLASTToken {
109
255
  readonly type: 'spread';
110
256
  readonly nodeName: '#spread';
111
257
  }
258
+ /**
259
+ * The root document node returned by a parser.
260
+ * Contains the full node list and metadata about the parse result.
261
+ */
112
262
  export interface MLASTDocument {
263
+ /** The full original source code */
113
264
  readonly raw: string;
265
+ /** Flat list of top-level AST nodes in document order */
114
266
  readonly nodeList: readonly MLASTNodeTreeItem[];
267
+ /** Whether the document is a fragment (no root element required) */
115
268
  readonly isFragment: boolean;
269
+ /** A description of any unknown parse error that occurred, if any */
116
270
  readonly unknownParseError?: string;
117
271
  }
118
272
  /**
119
- * @deprecated Use `MLParser` instead. This will be dropped in v5.
273
+ * Interface for a markuplint-compatible parser.
274
+ * Implementations parse markup source code and produce an {@link MLASTDocument}.
120
275
  */
121
- export interface MLMarkupLanguageParser {
122
- /**
123
- * @deprecated
124
- */
125
- parse(sourceCode: string, options?: ParserOptions & {
126
- readonly offsetOffset?: number;
127
- readonly offsetLine?: number;
128
- readonly offsetColumn?: number;
129
- }): MLASTDocument;
130
- /**
131
- * @default "omittable"
132
- * @deprecated
133
- */
134
- endTag?: EndTagType;
135
- /**
136
- * Detect value as a true if its attribute is booleanish value and omitted.
137
- *
138
- * Ex:
139
- * ```jsx
140
- * <Component aria-hidden />
141
- * ```
142
- *
143
- * In the above, the `aria-hidden` is `true`.
144
- *
145
- * @deprecated
146
- */
147
- booleanish?: boolean;
148
- }
149
276
  export interface MLParser {
150
277
  parse(sourceCode: string, options?: ParserOptions & {
151
278
  readonly offsetOffset?: number;
@@ -167,9 +294,14 @@ export interface MLParser {
167
294
  * In the above, the `aria-hidden` is `true`.
168
295
  */
169
296
  booleanish?: boolean;
297
+ /** Whether tag names should be treated as case-sensitive (e.g. for XHTML or JSX) */
170
298
  tagNameCaseSensitive?: boolean;
171
299
  }
300
+ /**
301
+ * A module that exports a parser. Used for dynamic parser resolution.
302
+ */
172
303
  export interface MLParserModule {
304
+ /** The parser instance */
173
305
  readonly parser: MLParser;
174
306
  }
175
307
  /**
@@ -180,17 +312,48 @@ export interface MLParserModule {
180
312
  * - `"never"`: Never need
181
313
  */
182
314
  export type EndTagType = 'xml' | 'omittable' | 'never';
315
+ /**
316
+ * Options that can be passed to a parser to customize its behavior.
317
+ */
183
318
  export type ParserOptions = {
319
+ /** Whether to ignore front matter (e.g. YAML in Markdown or Astro files) */
184
320
  readonly ignoreFrontMatter?: boolean;
321
+ /** How to distinguish authored (component) element names from native HTML elements */
185
322
  readonly authoredElementName?: ParserAuthoredElementNameDistinguishing;
186
323
  };
324
+ /**
325
+ * Configuration for distinguishing authored (component) elements from native HTML elements.
326
+ * Can be a string pattern, a RegExp, a predicate function, or an array of these.
327
+ */
187
328
  export type ParserAuthoredElementNameDistinguishing = string | Readonly<RegExp> | Readonly<ParserAuthoredElementNameDistinguishingFunction> | readonly (string | Readonly<RegExp> | ParserAuthoredElementNameDistinguishingFunction)[];
329
+ /**
330
+ * A predicate function that returns `true` if the given element name
331
+ * should be treated as an authored (component) element.
332
+ *
333
+ * @param name - The element name to test
334
+ * @returns `true` if the name represents an authored element
335
+ */
188
336
  export type ParserAuthoredElementNameDistinguishingFunction = (name: string) => boolean;
189
337
  /**
190
- * @deprecated
338
+ * Callback function used for walking through AST nodes.
339
+ *
340
+ * @template Node - The specific AST node type being walked
341
+ * @param node - The current node being visited
342
+ * @param sequentailPrevNode - The previous node in sequential (document) order, or `null`
343
+ * @param depth - The nesting depth of the current node
191
344
  */
192
- export type Parse = MLMarkupLanguageParser['parse'];
193
345
  export type Walker<Node extends MLASTNodeTreeItem> = (node: Node, sequentailPrevNode: MLASTNodeTreeItem | null, depth: number) => void;
346
+ /**
347
+ * Standard namespace URIs for HTML, SVG, MathML, and XLink.
348
+ */
194
349
  export type NamespaceURI = 'http://www.w3.org/1999/xhtml' | 'http://www.w3.org/2000/svg' | 'http://www.w3.org/1998/Math/MathML' | 'http://www.w3.org/1999/xlink';
350
+ /**
351
+ * Short namespace identifiers used internally by markuplint.
352
+ *
353
+ * - `'html'` – XHTML namespace
354
+ * - `'svg'` – SVG namespace
355
+ * - `'mml'` – MathML namespace
356
+ * - `'xlink'` – XLink namespace
357
+ */
195
358
  export type Namespace = 'html' | 'svg' | 'mml' | 'xlink';
196
359
  export {};
package/package.json CHANGED
@@ -1,10 +1,13 @@
1
1
  {
2
2
  "name": "@markuplint/ml-ast",
3
- "version": "4.4.10",
3
+ "version": "5.0.0-alpha.0",
4
4
  "description": "The markuplint AST types.",
5
5
  "repository": "git@github.com:markuplint/markuplint.git",
6
6
  "author": "Yusuke Hirao <yusukehirao@me.com>",
7
7
  "license": "MIT",
8
+ "engines": {
9
+ "node": ">=22"
10
+ },
8
11
  "type": "module",
9
12
  "exports": {
10
13
  ".": {
@@ -23,5 +26,5 @@
23
26
  "dev": "tsc --watch --project tsconfig.build.json",
24
27
  "clean": "tsc --build --clean tsconfig.build.json"
25
28
  },
26
- "gitHead": "acbf53f7e30d7a59f850a0f279b617383266dab3"
29
+ "gitHead": "13dcfc84ec83d87360c720e253383b60767e1b56"
27
30
  }