@markuplint/alpine-parser 4.6.23 → 5.0.0-alpha.0

package/CHANGELOG.md

@@ -3,6 +3,13 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+# [5.0.0-alpha.0](https://github.com/markuplint/markuplint/compare/v4.14.1...v5.0.0-alpha.0) (2026-02-20)
+
+### Features
+
+- **alpine-parser:** support loop blocks ([d92c53c](https://github.com/markuplint/markuplint/commit/d92c53ce7337a2b39f78cbc43edbe1aba2232bae))
+- delete htmx-parser, simplify alpine-parser, add migration guide and tests ([f8dbb09](https://github.com/markuplint/markuplint/commit/f8dbb090707d8cfbf3d859a9b868b2087064f89b))
+
 ## [4.6.23](https://github.com/markuplint/markuplint/compare/@markuplint/alpine-parser@4.6.22...@markuplint/alpine-parser@4.6.23) (2026-02-10)
 
 **Note:** Version bump only for package @markuplint/alpine-parser

package/README.md

@@ -14,7 +14,7 @@ $ yarn add -D @markuplint/alpine-parser
 
 ## Usage
 
-Add `parser` and `spec` option to your [configuration](https://markuplint.dev/configuration/#properties/parser).
+Add `parser` and `specs` option to your [configuration](https://markuplint.dev/configuration/#properties/parser).
 
 ```json
 {
@@ -22,7 +22,7 @@ Add `parser` and `spec` option to your [configuration](https://markuplint.dev/co
     "\\.html$": "@markuplint/alpine-parser"
   },
   "specs": {
-    "\\.html$": "@markuplint/alpine-parser/spec"
+    "\\.html$": "@markuplint/alpine-spec"
   }
 }
 ```

package/lib/parser.d.ts

@@ -1,31 +1,27 @@
-import type { Token } from '@markuplint/parser-utils';
+import type { MLASTNodeTreeItem } from '@markuplint/ml-ast';
 import { HtmlParser } from '@markuplint/html-parser';
 /**
  * Parser for Alpine.js templates that extends the standard HTML parser.
  *
- * Recognizes Alpine.js directives such as `x-data`, `x-bind`, `x-on`, and
- * `x-transition`, and classifies them as either directives (opaque to linting)
- * or attribute bindings (with potential standard attribute names for validation).
+ * Converts `<template x-for="...">` elements into preprocessor-specific
+ * blocks so that markuplint understands the iteration semantics.
+ *
+ * Attribute-level directive resolution (x-bind, x-on, @, :, etc.) is
+ * handled declaratively via `directivePatterns` in `@markuplint/alpine-spec`.
  */
 declare class AlpineParser extends HtmlParser {
     /**
-     * Visits an attribute token and applies Alpine.js-specific classification.
-     *
-     * Determines whether the attribute is an Alpine.js directive, a dynamic
-     * binding (e.g., `:class`, `x-bind:href`), or an event listener shorthand
-     * (e.g., `@click`, `x-on:submit`), and returns the attribute with
-     * appropriate metadata such as `potentialName`, `isDirective`, and
-     * `isDynamicValue`.
+     * Overrides the base element visitor to convert `<template x-for="...">` elements
+     * into preprocessor-specific blocks with `blockBehavior: { type: 'each' }`.
+     * The matching closing tag receives `{ type: 'end' }`. Non-template elements
+     * and templates without `x-for` are passed through unchanged.
      *
-     * @param token - The raw attribute token containing text and position information
-     * @param options - Controls quoting behavior, value types, and the initial parser state
-     * @returns The attribute AST node enriched with Alpine.js directive metadata
+     * @param token - The element token with tag metadata
+     * @param childNodes - The child AST nodes within the element
+     * @param options - Options forwarded to the base `visitElement`
+     * @returns An array of markuplint node tree items, with `x-for` templates replaced by psblock nodes
      */
-    visitAttr(token: Token, options: Parameters<HtmlParser['visitAttr']>[1]): (import("packages/@markuplint/ml-ast/lib/types.js").MLASTHTMLAttr & {
-        __rightText?: string;
-    }) | (import("packages/@markuplint/ml-ast/lib/types.js").MLASTSpreadAttr & {
-        __rightText?: string;
-    });
+    visitElement(token: Parameters<HtmlParser['visitElement']>[0], childNodes: Parameters<HtmlParser['visitElement']>[1], options: Parameters<HtmlParser['visitElement']>[2]): readonly MLASTNodeTreeItem[];
 }
 /**
  * Singleton Alpine.js parser instance for use by the markuplint engine.

package/lib/parser.js

@@ -2,207 +2,49 @@ import { HtmlParser } from '@markuplint/html-parser';
 /**
  * Parser for Alpine.js templates that extends the standard HTML parser.
  *
- * Recognizes Alpine.js directives such as `x-data`, `x-bind`, `x-on`, and
- * `x-transition`, and classifies them as either directives (opaque to linting)
- * or attribute bindings (with potential standard attribute names for validation).
+ * Converts `<template x-for="...">` elements into preprocessor-specific
+ * blocks so that markuplint understands the iteration semantics.
+ *
+ * Attribute-level directive resolution (x-bind, x-on, @, :, etc.) is
+ * handled declaratively via `directivePatterns` in `@markuplint/alpine-spec`.
  */
 class AlpineParser extends HtmlParser {
     /**
-     * Visits an attribute token and applies Alpine.js-specific classification.
-     *
-     * Determines whether the attribute is an Alpine.js directive, a dynamic
-     * binding (e.g., `:class`, `x-bind:href`), or an event listener shorthand
-     * (e.g., `@click`, `x-on:submit`), and returns the attribute with
-     * appropriate metadata such as `potentialName`, `isDirective`, and
-     * `isDynamicValue`.
+     * Overrides the base element visitor to convert `<template x-for="...">` elements
+     * into preprocessor-specific blocks with `blockBehavior: { type: 'each' }`.
+     * The matching closing tag receives `{ type: 'end' }`. Non-template elements
+     * and templates without `x-for` are passed through unchanged.
      *
-     * @param token - The raw attribute token containing text and position information
-     * @param options - Controls quoting behavior, value types, and the initial parser state
-     * @returns The attribute AST node enriched with Alpine.js directive metadata
+     * @param token - The element token with tag metadata
+     * @param childNodes - The child AST nodes within the element
+     * @param options - Options forwarded to the base `visitElement`
+     * @returns An array of markuplint node tree items, with `x-for` templates replaced by psblock nodes
      */
-    visitAttr(token, options) {
-        const attr = super.visitAttr(token, options);
-        if (attr.type === 'spread') {
-            return attr;
-        }
-        const name = attr.name.raw;
-        switch (name) {
-            /**
-             * @see https://alpinejs.dev/directives/data
-             */
-            case 'x-data': {
-                return {
-                    ...attr,
-                    isDirective: true,
-                };
-            }
-            /**
-             * @see https://alpinejs.dev/directives/init
-             */
-            case 'x-init': {
-                return {
-                    ...attr,
-                    isDirective: true,
-                };
-            }
-            /**
-             * @see https://alpinejs.dev/directives/show
-             */
-            case 'x-show': {
-                return {
-                    ...attr,
-                    isDirective: true,
-                };
-            }
-            /**
-             * @see https://alpinejs.dev/directives/text
-             */
-            case 'x-text': {
-                return {
-                    ...attr,
-                    isDirective: true,
-                };
-            }
-            /**
-             * @see https://alpinejs.dev/directives/html
-             */
-            case 'x-html': {
-                return {
-                    ...attr,
-                    isDirective: true,
-                };
-            }
-            /**
-             * {@link ./spec.ts} Treat as a normal attribute and allow only in template elements as defined in `spec`.
-             *
-             * @see https://alpinejs.dev/directives/model
-             */
-            case 'x-model': {
-                return attr;
-            }
-            /**
-             * @see https://alpinejs.dev/directives/modelable
-             */
-            case 'x-modelable': {
-                return {
-                    ...attr,
-                    isDirective: true,
-                };
-            }
-            /**
-             * {@link ./spec.ts} Treat as a normal attribute and allow only in template elements as defined in `spec`.
-             *
-             * @see https://alpinejs.dev/directives/for
-             */
-            case 'x-for': {
-                return attr;
-            }
-            /**
-             * @see https://alpinejs.dev/directives/effect
-             */
-            case 'x-effect': {
-                return {
-                    ...attr,
-                    isDirective: true,
-                };
-            }
-            /**
-             * @see https://alpinejs.dev/directives/ignore
-             */
-            case 'x-ignore': {
-                return {
-                    ...attr,
-                    valueType: 'boolean',
-                    isDirective: true,
-                };
-            }
-            /**
-             * @see https://alpinejs.dev/directives/ref
-             */
-            case 'x-ref': {
-                return {
-                    ...attr,
-                    isDirective: true,
-                };
-            }
-            /**
-             * @see https://alpinejs.dev/directives/cloak
-             */
-            case 'x-cloak': {
-                return {
-                    ...attr,
-                    valueType: 'boolean',
-                    isDirective: true,
-                };
-            }
-            /**
-             * {@link ./spec.ts} Treat as a normal attribute and allow only in template elements as defined in `spec`.
-             *
-             * @see https://alpinejs.dev/directives/teleport
-             */
-            case 'x-teleport': {
-                return attr;
-            }
-            /**
-             * {@link ./spec.ts} Treat as a normal attribute and allow only in template elements as defined in `spec`.
-             *
-             * @see https://alpinejs.dev/directives/if
-             */
-            case 'x-if': {
-                return attr;
-            }
-            /**
-             * @see https://alpinejs.dev/directives/id
-             */
-            case 'x-id': {
-                return {
-                    ...attr,
-                    isDirective: true,
-                };
-            }
-        }
-        /**
-         * @see https://alpinejs.dev/directives/bind
-         */
-        if (name.startsWith('x-bind:') || name.startsWith(':')) {
-            const potentialName = (attr.name.raw.match(/^(x-bind:|:)([^.]+)(?:\.([^.]+))?$/i) ?? [])[2];
-            if (!potentialName) {
-                return attr;
-            }
-            return {
-                ...attr,
-                potentialName,
-                valueType: 'code',
-                isDuplicatable: ['class', 'style'].includes(potentialName),
-                isDynamicValue: true,
-            };
-        }
-        /**
-         * @see https://alpinejs.dev/directives/on
-         */
-        if (name.startsWith('x-on:') || name.startsWith('@')) {
-            const potentialName = (attr.name.raw.match(/^(x-on:|@)([^.]+)(\..+)?$/i) ?? [])[2];
-            if (!potentialName) {
-                return attr;
-            }
-            return {
-                ...attr,
-                potentialName: `on${potentialName.toLowerCase()}`,
-                // TODO: Postpone due to inability to distinguish between custom and native events
-                isDirective: true,
-                isDynamicValue: true,
-            };
-        }
-        /**
-         * @see https://alpinejs.dev/directives/transition
-         */
-        if (/^x-transition(?:$|:|\.)/.test(name)) {
-            return {
-                ...attr,
-                isDirective: true,
+    visitElement(token, childNodes = [], options) {
+        return super.visitElement(token, childNodes, options).map(node => {
+            if (node.type !== 'starttag' && node.type !== 'endtag') {
+                return node;
+            }
+            if (node.nodeName.toLowerCase() !== 'template') {
+                return node;
+            }
+            const attrs = node.type === 'starttag' ? node.attributes : node.pairNode.attributes;
+            if (!attrs.some(attr => attr.nodeName.toLowerCase() === 'x-for')) {
+                return node;
+            }
+            const forBlock = {
+                isFragment: false,
+                childNodes: [],
+                ...node,
+                type: 'psblock',
+                blockBehavior: {
+                    type: node.type === 'starttag' ? 'each' : 'end',
+                    expression: node.raw,
+                },
+                isBogus: false,
             };
-        }
-        return attr;
+            return forBlock;
+        });
     }
 }
 /**

package/package.json

@@ -1,19 +1,18 @@
 {
 	"name": "@markuplint/alpine-parser",
-	"version": "4.6.23",
+	"version": "5.0.0-alpha.0",
 	"description": "Alpine.js parser for markuplint",
 	"repository": "git@github.com:markuplint/markuplint.git",
 	"author": "Yusuke Hirao <yusukehirao@me.com>",
 	"license": "MIT",
+	"engines": {
+		"node": ">=22"
+	},
 	"type": "module",
 	"exports": {
 		".": {
 			"import": "./lib/index.js",
 			"types": "./lib/index.d.ts"
-		},
-		"./spec": {
-			"import": "./lib/spec.js",
-			"types": "./lib/spec.d.ts"
 		}
 	},
 	"publishConfig": {
@@ -25,11 +24,10 @@
 		"clean": "tsc --build --clean tsconfig.build.json"
 	},
 	"dependencies": {
-		"@markuplint/html-parser": "4.6.23"
+		"@markuplint/html-parser": "5.0.0-alpha.0"
 	},
 	"devDependencies": {
-		"@markuplint/ml-spec": "4.10.2",
-		"@markuplint/parser-utils": "4.8.11"
+		"@markuplint/parser-utils": "5.0.0-alpha.0"
 	},
-	"gitHead": "193ee7c1262bbed95424e38efdf1a8e56ff049f4"
+	"gitHead": "13dcfc84ec83d87360c720e253383b60767e1b56"
 }