@markuplint/astro-parser 5.2.0 → 5.3.0

package/CHANGELOG.md

@@ -3,6 +3,20 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+# [5.3.0](https://github.com/markuplint/markuplint/compare/v5.2.0...v5.3.0) (2026-10-21)
+
+### Bug Fixes
+
+* **astro-parser:** detect a frontmatter fence with trailing spaces and pin the guard boundaries ([23e6e0c](https://github.com/markuplint/markuplint/commit/23e6e0c3628ed3c9b3bad20d9381a505919146b1))
+* **astro-parser:** do not report a root that is neither a component nor an element ([fdf141b](https://github.com/markuplint/markuplint/commit/fdf141b02eb0c9bb26812c4be748feac1c1584d6))
+* **astro-parser:** migrate to astro-eslint-parser v3 ([f76792a](https://github.com/markuplint/markuplint/commit/f76792a01f823bb4e29103d1b4ce7ef6e33c8bda))
+* make published packages loadable from require() and put types first ([723106f](https://github.com/markuplint/markuplint/commit/723106f51aac4e60dc02db2c1a894617368b0253)), closes [#4198](https://github.com/markuplint/markuplint/issues/4198)
+
+### Features
+
+* **astro-parser:** answer what a component name is by the rule of Astro ([5399070](https://github.com/markuplint/markuplint/commit/5399070fa1797cbd502379e9c469aba51693b92b))
+
+
 # [5.2.0](https://github.com/markuplint/markuplint/compare/v5.1.1...v5.2.0) (2026-10-13)
 
 ### Bug Fixes

package/lib/astro-parser.d.ts

@@ -1,12 +1,4 @@
-import type { RootNode } from '@astrojs/compiler/types';
-/**
- * `@astrojs/compiler` is a dev dependency used only for these type
- * definitions; the runtime AST actually comes from `astro-eslint-parser`.
- * When upgrading `astro-eslint-parser`, also update `@astrojs/compiler` to
- * the version it uses internally, otherwise the types drift from the
- * runtime AST shape.
- */
-export type { RootNode, ElementNode, CustomElementNode, ComponentNode, FragmentNode, AttributeNode, Node, } from '@astrojs/compiler/types';
+import type { AstroRoot } from './to-nodes.js';
 /**
  * ## Diagnostic handling policy
  *
@@ -25,8 +17,8 @@ export type { RootNode, ElementNode, CustomElementNode, ComponentNode, FragmentN
  *
  * `parseTemplate()` itself raises an `astro-eslint-parser` `ParseError`
  * (extending `SyntaxError`) on severity=Error diagnostics and on raw
- * template syntax errors (unterminated comments, unclosed expressions,
- * etc.). Those — and only those — are normalized to `ParserError`, so the
+ * template syntax errors (unclosed expressions, mismatched end tags, etc.).
+ * Those — and only those — are normalized to `ParserError`, so the
  * caller sees a single Tier-3 (per-file violation) error type for every
  * parse failure. Any other throw, including a genuine `SyntaxError` from a
  * markuplint invariant break, is allowed to propagate so the standard
@@ -36,10 +28,15 @@ export type { RootNode, ElementNode, CustomElementNode, ComponentNode, FragmentN
  * code today (upstream gates internally) but is retained as a safety net
  * if a future `astro-eslint-parser` ever stops gating severity=Error.
  *
+ * Two malformed inputs that v3 accepts without any signal — an unterminated
+ * frontmatter and an unclosed HTML comment — are detected here and raised as
+ * `ParserError` too (see `assertFrontmatterTerminated` and
+ * `assertParsedToTheEnd`), so no template is silently skipped.
+ *
  * @see https://github.com/markuplint/markuplint/issues/3823
  * @see https://docs.astro.build/en/reference/directives-reference/#isinline
  * @see https://docs.astro.build/en/guides/client-side-scripts/#script-processing
  *
  * @throws {ParserError} on severity=Error Astro diagnostics or on raw upstream syntax errors
  */
-export declare function astroParse(code: string): RootNode;
+export declare function astroParse(code: string): AstroRoot;

package/lib/astro-parser.js

@@ -1,14 +1,11 @@
 import { ParserError } from '@markuplint/parser-utils';
 import { parseTemplate } from 'astro-eslint-parser';
 /**
- * Astro tags each diagnostic with a VS Code-style severity
- * (1=Error, 2=Warning, 3=Information, 4=Hint). The compiler exposes the
- * enum as types-only via `@astrojs/compiler/types` — there is no runtime
- * value to import — so the fatal level is mirrored as a literal here.
- *
- * @see https://github.com/withastro/compiler/blob/main/packages/compiler/shared/types.ts
+ * Astro tags each diagnostic with a severity of `'error'`, `'warning'`,
+ * `'information'` or `'hint'` (`DiagnosticSeverity` of `@astrojs/compiler-binding`,
+ * a `const enum`, i.e. types-only), so the fatal level is mirrored as a literal here.
  */
-const ASTRO_DIAGNOSTIC_SEVERITY_ERROR = 1;
+const ASTRO_DIAGNOSTIC_SEVERITY_ERROR = 'error';
 /**
  * Type guard for `astro-eslint-parser`'s `ParseError` class. The class
  * extends `SyntaxError` and carries a unique `originalAST` instance
@@ -44,8 +41,8 @@ function isAstroEslintParseError(error) {
  *
  * `parseTemplate()` itself raises an `astro-eslint-parser` `ParseError`
  * (extending `SyntaxError`) on severity=Error diagnostics and on raw
- * template syntax errors (unterminated comments, unclosed expressions,
- * etc.). Those — and only those — are normalized to `ParserError`, so the
+ * template syntax errors (unclosed expressions, mismatched end tags, etc.).
+ * Those — and only those — are normalized to `ParserError`, so the
  * caller sees a single Tier-3 (per-file violation) error type for every
  * parse failure. Any other throw, including a genuine `SyntaxError` from a
  * markuplint invariant break, is allowed to propagate so the standard
@@ -55,6 +52,11 @@ function isAstroEslintParseError(error) {
  * code today (upstream gates internally) but is retained as a safety net
  * if a future `astro-eslint-parser` ever stops gating severity=Error.
  *
+ * Two malformed inputs that v3 accepts without any signal — an unterminated
+ * frontmatter and an unclosed HTML comment — are detected here and raised as
+ * `ParserError` too (see `assertFrontmatterTerminated` and
+ * `assertParsedToTheEnd`), so no template is silently skipped.
+ *
  * @see https://github.com/markuplint/markuplint/issues/3823
  * @see https://docs.astro.build/en/reference/directives-reference/#isinline
  * @see https://docs.astro.build/en/guides/client-side-scripts/#script-processing
@@ -80,10 +82,57 @@ export function astroParse(code) {
     // past the wrapper as a non-fatal pass-through.
     const fatal = result.diagnostics.find(d => d.severity === ASTRO_DIAGNOSTIC_SEVERITY_ERROR);
     if (fatal) {
+        // A label's column is 0-based; `ParserError` takes a 1-based one.
+        const label = fatal.labels[0];
         throw new ParserError(fatal.text, {
-            line: fatal.location.line,
-            col: fatal.location.column,
+            line: label?.line ?? 1,
+            col: label ? label.column + 1 : 1,
         });
     }
+    assertFrontmatterTerminated(code, result.ast);
+    assertParsedToTheEnd(code, result.ast);
     return result.ast;
 }
+/**
+ * A leading `---` line, which opens a frontmatter block. Spaces may follow the fence
+ * (`astro-eslint-parser` accepts `--- ` as one), and the source may end right after it.
+ */
+const RE_FRONTMATTER_FENCE = /^(?:\s*\n)?---[ \t]*(?:\r?\n|$)/;
+/**
+ * `astro-eslint-parser` v3 reports an unterminated frontmatter (for example,
+ * a closing `---` hidden inside an unterminated block comment) neither
+ * as an error nor as a diagnostic: the fence and everything after it silently
+ * becomes template text. Every earlier version, and Astro itself, rejects it.
+ *
+ * @throws {ParserError} when the source starts with a frontmatter fence that no frontmatter was parsed from
+ */
+function assertFrontmatterTerminated(code, ast) {
+    const { frontmatter } = ast;
+    if (frontmatter && frontmatter.end === frontmatter.start && RE_FRONTMATTER_FENCE.test(code)) {
+        throw new ParserError('Unterminated frontmatter', locate(code, 0));
+    }
+}
+/**
+ * `astro-eslint-parser` v3 reports an unclosed HTML comment (`<!-- ...`)
+ * neither as an error nor as a diagnostic: it drops the comment and
+ * everything after it, so a template that is not checked at all would pass.
+ * A node list that stops before the end of the source is that situation.
+ *
+ * Whitespace after the last node is not content: the newline that follows a
+ * closing frontmatter fence belongs to no node.
+ *
+ * @throws {ParserError} when the AST does not reach the end of the source
+ */
+function assertParsedToTheEnd(code, ast) {
+    const parsedEnd = ast.body.at(-1)?.end ?? ast.frontmatter?.end ?? 0;
+    if (parsedEnd < code.length && code.slice(parsedEnd).trim() !== '') {
+        throw new ParserError('Unterminated syntax: the template is not parsed to its end', locate(code, parsedEnd));
+    }
+}
+/**
+ * The 1-based line and column of an offset.
+ */
+function locate(code, offset) {
+    const lines = code.slice(0, offset).split('\n');
+    return { line: lines.length, col: (lines.at(-1)?.length ?? 0) + 1 };
+}

package/lib/component-scanner.js

@@ -5,6 +5,14 @@ function extractComponentInfo(doc) {
     if (!root) {
         return null;
     }
+    // The parser says the root is authored, yet its name is not the one of a component
+    // (`component`, `slot` of Vue): it renders what it is given, so there is no element
+    // to pretend to be. `pretenders` would otherwise emit that name as the target, and
+    // nothing tells it from the name of an element. What a component's name is, is the
+    // parser's rule (`Parser#isComponentName`).
+    if (root.elementType === 'authored' && !parser.isComponentName(root.nodeName)) {
+        return null;
+    }
     const spreads = extractSpreads(root);
     return {
         rootElement: root.nodeName,

package/lib/parser.d.ts

@@ -1,4 +1,4 @@
-import type { Node } from './astro-parser.js';
+import type { Node } from './to-nodes.js';
 import type { MLASTNodeTreeItem, MLASTParentNode } from '@markuplint/ml-ast';
 import type { ChildToken, Token } from '@markuplint/parser-utils';
 import { Parser } from '@markuplint/parser-utils';
@@ -106,6 +106,15 @@ declare class AstroParser extends Parser<Node> {
      * @param defaultPattern
      */
     detectElementType(nodeName: string): import("@markuplint/ml-ast").ElementType;
+    /**
+     * A variable used as a tag must be capitalized in Astro, as `detectElementType` takes it. Unlike the
+     * default of the base class, a `.` alone does not make a name a component: `<ui.Item>` is an
+     * HTML element there.
+     *
+     * @param name - A tag name as written, case kept
+     * @returns Whether the name is a component's
+     */
+    isComponentName(name: string): boolean;
 }
 export declare const parser: AstroParser;
 export {};

package/lib/parser.js

@@ -1,7 +1,8 @@
-import { AttrState, Parser, ParserError } from '@markuplint/parser-utils';
+import { AttrState, Parser, ParserError, isPotentialCustomElementName } from '@markuplint/parser-utils';
 import { astroParse } from './astro-parser.js';
 import { detectBlockBehavior } from './detect-block-behavior.js';
 import { extractSpreadAttribute } from './spread-attr.js';
+import { toNodes } from './to-nodes.js';
 /**
  * Parser implementation for Astro component templates.
  * Extends the base Parser to handle Astro-specific syntax including frontmatter blocks,
@@ -26,7 +27,7 @@ class AstroParser extends Parser {
     }
     tokenize() {
         return {
-            ast: astroParse(this.rawCode).children,
+            ast: toNodes(astroParse(this.rawCode)),
             isFragment: true,
         };
     }
@@ -43,11 +44,8 @@ class AstroParser extends Parser {
     nodeize(
     // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
     originNode, parentNode, depth) {
-        if (!originNode.position) {
-            throw new TypeError("Node doesn't have position");
-        }
-        const offset = originNode.position.start.offset;
-        const endOffset = originNode.position.end?.offset;
+        const offset = originNode.start;
+        const endOffset = originNode.end;
         const token = this.sliceFragment(offset, endOffset);
         switch (originNode.type) {
             case 'frontmatter': {
@@ -86,13 +84,9 @@ class AstroParser extends Parser {
                     parentNode,
                 });
             }
-            case 'component':
-            case 'custom-element':
-            case 'fragment':
             case 'element': {
-                const tagToken = token.raw ? token : this.sliceFragment(0);
                 return this.visitElement({
-                    ...tagToken,
+                    ...token,
                     depth,
                     parentNode,
                 }, originNode.children);
@@ -106,12 +100,12 @@ class AstroParser extends Parser {
                 const nodes = [];
                 let closeExpressionLocation = null;
                 if (firstChild && lastChild && firstChild !== lastChild) {
-                    const startExpressionEndOffset = firstChild.position?.end?.offset ?? endOffset ?? offset;
+                    const startExpressionEndOffset = firstChild.end;
                     const startExpressionLocation = this.sliceFragment(offset, startExpressionEndOffset);
                     startExpressionRaw = startExpressionLocation.raw;
                     startExpressionStartLine = startExpressionLocation.line;
                     startExpressionStartCol = startExpressionLocation.col;
-                    closeExpressionLocation = this.sliceFragment(lastChild.position?.start.offset ?? offset, endOffset);
+                    closeExpressionLocation = this.sliceFragment(lastChild.start, endOffset);
                 }
                 const blockBehavior = detectBlockBehavior(startExpressionRaw);
                 nodes.push(...this.visitPsBlock({
@@ -316,5 +310,16 @@ class AstroParser extends Parser {
     detectElementType(nodeName) {
         return super.detectElementType(nodeName, /^[A-Z]/);
     }
+    /**
+     * A variable used as a tag must be capitalized in Astro, as `detectElementType` takes it. Unlike the
+     * default of the base class, a `.` alone does not make a name a component: `<ui.Item>` is an
+     * HTML element there.
+     *
+     * @param name - A tag name as written, case kept
+     * @returns Whether the name is a component's
+     */
+    isComponentName(name) {
+        return /^[A-Z]/.test(name) && !isPotentialCustomElementName(name);
+    }
 }
 export const parser = new AstroParser();

package/lib/to-nodes.d.ts

@@ -0,0 +1,52 @@
+import type { ParseTemplateResult } from 'astro-eslint-parser';
+/**
+ * The root `astro-eslint-parser` produces for a template.
+ */
+export type AstroRoot = ParseTemplateResult['result']['ast'];
+/**
+ * A node of the Astro template reduced to what {@link import('./parser.js')} needs:
+ * its kind, its source range (UTF-16 offsets, `end` exclusive) and the nodes it contains.
+ *
+ * Attributes are deliberately absent: the parser re-tokenizes the start tag from the
+ * source text, so no attribute information is read from the Astro AST.
+ */
+export type Node = (Range & {
+    readonly type: 'frontmatter';
+}) | (Range & {
+    readonly type: 'doctype';
+    readonly value: string;
+}) | (Range & {
+    readonly type: 'text';
+}) | (Range & {
+    readonly type: 'comment';
+}) | (Range & {
+    readonly type: 'element';
+    readonly children: readonly Node[];
+}) | (Range & {
+    readonly type: 'expression';
+    readonly children: readonly Node[];
+});
+interface Range {
+    readonly start: number;
+    readonly end: number;
+}
+/**
+ * The nodes of the Astro AST as a flat list of top-level {@link Node}s: the frontmatter
+ * (when there is one) followed by the body.
+ *
+ * ## Why a normalization step exists
+ *
+ * `astro-eslint-parser` v3 reports a JSX-style AST (`JSXElement`, `JSXText`, ...) where the
+ * former compiler reported `element` / `component` / `text` nodes. Three of its shapes
+ * differ in a way the parser must not see:
+ *
+ * - The range of an `AstroScript` child is that of the whole `<script>` element, not of its
+ *   body, so the body range is taken from the surrounding start and end tags.
+ * - A JSX node inside an expression (`{items.map(i => <li>{i}</li>)}`) is not a child of the
+ *   expression container but a descendant of its ESTree expression. The outermost ones are
+ *   collected, and the code between them is reported as `text` nodes, which is the layout the
+ *   parser relies on to split an expression into its opening and closing parts.
+ * - An absent frontmatter is reported as an empty one.
+ */
+export declare function toNodes(root: AstroRoot): Node[];
+export {};

package/lib/to-nodes.js

@@ -0,0 +1,120 @@
+/**
+ * The nodes of the Astro AST as a flat list of top-level {@link Node}s: the frontmatter
+ * (when there is one) followed by the body.
+ *
+ * ## Why a normalization step exists
+ *
+ * `astro-eslint-parser` v3 reports a JSX-style AST (`JSXElement`, `JSXText`, ...) where the
+ * former compiler reported `element` / `component` / `text` nodes. Three of its shapes
+ * differ in a way the parser must not see:
+ *
+ * - The range of an `AstroScript` child is that of the whole `<script>` element, not of its
+ *   body, so the body range is taken from the surrounding start and end tags.
+ * - A JSX node inside an expression (`{items.map(i => <li>{i}</li>)}`) is not a child of the
+ *   expression container but a descendant of its ESTree expression. The outermost ones are
+ *   collected, and the code between them is reported as `text` nodes, which is the layout the
+ *   parser relies on to split an expression into its opening and closing parts.
+ * - An absent frontmatter is reported as an empty one.
+ */
+export function toNodes(root) {
+    const nodes = [];
+    const { frontmatter } = root;
+    if (frontmatter && frontmatter.end > frontmatter.start) {
+        nodes.push({ type: 'frontmatter', start: frontmatter.start, end: frontmatter.end });
+    }
+    for (const node of root.body) {
+        nodes.push(...convert(node));
+    }
+    return nodes;
+}
+function convert(node) {
+    const { start, end } = node;
+    switch (node.type) {
+        case 'AstroDoctype': {
+            return [{ type: 'doctype', start, end, value: node.value }];
+        }
+        case 'AstroComment': {
+            return [{ type: 'comment', start, end }];
+        }
+        case 'JSXText': {
+            return [{ type: 'text', start, end }];
+        }
+        case 'JSXElement': {
+            return [
+                {
+                    type: 'element',
+                    start,
+                    end,
+                    children: node.children.flatMap(child => {
+                        if (child.type !== 'AstroScript') {
+                            return convert(child);
+                        }
+                        // An empty body (`<script />`) is still reported as a script: it has no text.
+                        const bodyStart = node.openingElement.end;
+                        const bodyEnd = node.closingElement?.start ?? end;
+                        return bodyEnd > bodyStart ? [{ type: 'text', start: bodyStart, end: bodyEnd }] : [];
+                    }),
+                },
+            ];
+        }
+        case 'JSXFragment': {
+            return [{ type: 'element', start, end, children: node.children.flatMap(child => convert(child)) }];
+        }
+        case 'JSXExpressionContainer': {
+            return [{ type: 'expression', start, end, children: expressionChildren(node) }];
+        }
+        default: {
+            // Exhaustive: a node type that `astro-eslint-parser` adds fails the build here
+            // instead of silently vanishing from the document.
+            node;
+            return [];
+        }
+    }
+}
+/**
+ * The children of an expression container: the outermost JSX nodes of its expression, with
+ * the (non-empty) code between them as `text`. The braces are not part of any child.
+ *
+ * Empty gaps produce no `text`, as the former compiler did. The parser cuts the opening part of
+ * the expression at the end of the first child and the closing part at the start of the last
+ * one, so an expression that ends with an element has that element's markup in its closing
+ * part (`<input type={type} />}`). That layout is pinned by the `#739` spec in `parser.spec.ts`.
+ */
+function expressionChildren(container) {
+    const jsxNodes = collectJsx(container.expression).toSorted((a, b) => a.start - b.start);
+    if (jsxNodes.length === 0) {
+        return [];
+    }
+    const children = [];
+    // Skip the opening `{`
+    let cursor = container.start + 1;
+    for (const jsx of jsxNodes) {
+        if (jsx.start > cursor) {
+            children.push({ type: 'text', start: cursor, end: jsx.start });
+        }
+        children.push(...convert(jsx));
+        cursor = jsx.end;
+    }
+    // Stop before the closing `}`
+    const innerEnd = container.end - 1;
+    if (innerEnd > cursor) {
+        children.push({ type: 'text', start: cursor, end: innerEnd });
+    }
+    return children;
+}
+/**
+ * Finds the outermost `JSXElement` / `JSXFragment` nodes in an ESTree subtree. A node found
+ * is not descended into: its own descendants are converted when the node itself is.
+ */
+function collectJsx(value) {
+    if (typeof value !== 'object' || value === null) {
+        return [];
+    }
+    if (Array.isArray(value)) {
+        return value.flatMap(item => collectJsx(item));
+    }
+    if ('type' in value && (value.type === 'JSXElement' || value.type === 'JSXFragment')) {
+        return [value];
+    }
+    return Object.entries(value).flatMap(([key, child]) => (key === 'parent' ? [] : collectJsx(child)));
+}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@markuplint/astro-parser",
-	"version": "5.2.0",
+	"version": "5.3.0",
 	"description": "astro parser for markuplint",
 	"repository": {
 		"type": "git",
@@ -15,12 +15,12 @@
 	"type": "module",
 	"exports": {
 		".": {
-			"import": "./lib/index.js",
-			"types": "./lib/index.d.ts"
+			"types": "./lib/index.d.ts",
+			"default": "./lib/index.js"
 		},
 		"./component-scanner": {
-			"import": "./lib/component-scanner.js",
-			"types": "./lib/component-scanner.d.ts"
+			"types": "./lib/component-scanner.d.ts",
+			"default": "./lib/component-scanner.js"
 		}
 	},
 	"publishConfig": {
@@ -32,12 +32,9 @@
 		"clean": "tsc --build --clean tsconfig.build.json"
 	},
 	"dependencies": {
-		"@markuplint/ml-ast": "5.1.1",
-		"@markuplint/parser-utils": "5.2.0",
-		"astro-eslint-parser": "^1.4.0"
+		"@markuplint/ml-ast": "5.3.0",
+		"@markuplint/parser-utils": "5.3.0",
+		"astro-eslint-parser": "^3.2.0"
 	},
-	"devDependencies": {
-		"@astrojs/compiler": "3.0.1"
-	},
-	"gitHead": "d8b2feab77c9c862513615bea6b80d2817431878"
+	"gitHead": "f587cf0206c8426e57369a48d6d5fb22306eafde"
 }