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