@markuplint/ml-core 4.13.2 → 5.0.0-alpha.0

package/lib/virtual-rule.d.ts

@@ -0,0 +1,72 @@
+import type { AnyMLRule } from './ml-rule/index.js';
+import type { Rules, SpecConformance } from '@markuplint/ml-config';
+/**
+ * Common shape of a nodeRule/childNodeRule entry that supports naming.
+ */
+type NameableNodeRule = {
+    readonly name?: string;
+    readonly specConformance?: SpecConformance;
+    readonly rules?: {
+        readonly [ruleName: string]: unknown;
+    };
+};
+/**
+ * Result of expanding named nodeRules into virtual rules.
+ */
+export type ExpandResult<T> = {
+    /** Virtual MLRule instances created from named nodeRules */
+    readonly virtualRules: readonly AnyMLRule[];
+    /** NodeRules array with named entries transformed (rules key changed to alias name) */
+    readonly transformedNodeRules: readonly T[];
+    /** Validation errors encountered during expansion */
+    readonly errors: readonly Error[];
+};
+/**
+ * Expands named nodeRules (or childNodeRules) into virtual MLRule instances.
+ *
+ * Named entries (those with a `name` property containing `/`) are converted into
+ * independent virtual rules that reuse the base rule's verify/fix logic but run
+ * under their own alias name. This enables per-check control:
+ * - Each virtual rule can be independently enabled/disabled via `rules["alias/name"]: false`
+ * - Violations report both the base `ruleId` and the alias `name`
+ *
+ * **false entry separation**: When a named nodeRule has `rules` entries set to `false`,
+ * those entries are separated into unnamed nodeRules. This preserves their semantics
+ * as base-rule specificity overrides (disabling the base rule on matching nodes)
+ * rather than creating virtual rules that would only disable themselves.
+ *
+ * **Multi-entry support**: When a named nodeRule has 2+ non-false entries, each
+ * entry gets its own virtual rule with a derived name (`name/baseRuleName`).
+ * A `groupName` is set so the entire group can be disabled via `rules["groupName"]: false`.
+ *
+ * Unnamed nodeRules pass through unchanged.
+ *
+ * @param nodeRules - The nodeRules (or childNodeRules) array from the config
+ * @param existingRules - All registered MLRule instances (for base rule lookup)
+ * @returns Virtual rules, transformed nodeRules, and any validation errors
+ */
+export declare function expandNamedNodeRules<T extends NameableNodeRule>(nodeRules: readonly T[], existingRules: readonly Readonly<AnyMLRule>[]): ExpandResult<T>;
+/**
+ * Result of expanding named rule groups in the `rules` section.
+ */
+export type ExpandNamedRulesResult = {
+    /** Virtual MLRule instances created from named rule groups */
+    readonly virtualRules: readonly AnyMLRule[];
+    /** Rules dict with named groups expanded into their virtual rule entries */
+    readonly resolvedRules: Rules;
+    /** Validation errors encountered during expansion */
+    readonly errors: readonly Error[];
+};
+/**
+ * Expands named rule groups in the `rules` section into virtual MLRule instances.
+ *
+ * Named rule groups (keys containing `/` whose values are {@link NamedRuleGroup} objects)
+ * are converted into independent virtual rules, similar to how `expandNamedNodeRules`
+ * handles named nodeRules. This enables per-check control at the global rules level.
+ *
+ * @param rules - The rules dict from the config
+ * @param existingRules - All registered MLRule instances (for base rule lookup)
+ * @returns Virtual rules, resolved rules dict, and any validation errors
+ */
+export declare function expandNamedRules(rules: Rules, existingRules: readonly Readonly<AnyMLRule>[]): ExpandNamedRulesResult;
+export {};

package/lib/virtual-rule.js

@@ -0,0 +1,233 @@
+import { isNamedRuleGroup } from '@markuplint/ml-config';
+const NAMED_NODE_RULE_PATTERN = /^[^/]+\/.+$/;
+/**
+ * Expands named nodeRules (or childNodeRules) into virtual MLRule instances.
+ *
+ * Named entries (those with a `name` property containing `/`) are converted into
+ * independent virtual rules that reuse the base rule's verify/fix logic but run
+ * under their own alias name. This enables per-check control:
+ * - Each virtual rule can be independently enabled/disabled via `rules["alias/name"]: false`
+ * - Violations report both the base `ruleId` and the alias `name`
+ *
+ * **false entry separation**: When a named nodeRule has `rules` entries set to `false`,
+ * those entries are separated into unnamed nodeRules. This preserves their semantics
+ * as base-rule specificity overrides (disabling the base rule on matching nodes)
+ * rather than creating virtual rules that would only disable themselves.
+ *
+ * **Multi-entry support**: When a named nodeRule has 2+ non-false entries, each
+ * entry gets its own virtual rule with a derived name (`name/baseRuleName`).
+ * A `groupName` is set so the entire group can be disabled via `rules["groupName"]: false`.
+ *
+ * Unnamed nodeRules pass through unchanged.
+ *
+ * @param nodeRules - The nodeRules (or childNodeRules) array from the config
+ * @param existingRules - All registered MLRule instances (for base rule lookup)
+ * @returns Virtual rules, transformed nodeRules, and any validation errors
+ */
+export function expandNamedNodeRules(nodeRules, existingRules) {
+    const virtualRules = [];
+    const transformedNodeRules = [];
+    const errors = [];
+    const existingRuleMap = new Map(existingRules.map(r => [r.name, r]));
+    const usedAliasNames = new Set();
+    for (const nodeRule of nodeRules) {
+        if (!nodeRule.name) {
+            // Unnamed nodeRule: pass through unchanged
+            transformedNodeRules.push(nodeRule);
+            continue;
+        }
+        const namedRuleName = nodeRule.name;
+        // Validate name format (must contain /)
+        if (!NAMED_NODE_RULE_PATTERN.test(namedRuleName)) {
+            errors.push(new Error(`Named nodeRule name must contain "/" (e.g., "scope/rule-name"): "${namedRuleName}"`));
+            continue;
+        }
+        // Separate false entries from non-false entries
+        const allEntries = Object.entries(nodeRule.rules ?? {});
+        const nonFalseEntries = allEntries.filter(([, config]) => config !== false);
+        const falseEntries = allEntries.filter(([, config]) => config === false);
+        if (nonFalseEntries.length === 0) {
+            errors.push(new Error(`Named nodeRule "${namedRuleName}" must have at least one non-false rule entry`));
+            continue;
+        }
+        // Check for duplicate alias names
+        if (usedAliasNames.has(namedRuleName)) {
+            errors.push(new Error(`Duplicate named nodeRule: "${namedRuleName}"`));
+            continue;
+        }
+        usedAliasNames.add(namedRuleName);
+        // Check for name collision with existing rules
+        if (existingRuleMap.has(namedRuleName)) {
+            errors.push(new Error(`Named nodeRule "${namedRuleName}" conflicts with an existing rule of the same name`));
+            continue;
+        }
+        // Emit false entries as unnamed nodeRules (base-rule specificity overrides)
+        if (falseEntries.length > 0) {
+            const falseRules = {};
+            for (const [key] of falseEntries) {
+                falseRules[key] = false;
+            }
+            // Safety: stripNamedProperties copies all properties except name/specConformance/rules,
+            // then adds replacement rules. T's extra properties (e.g., ChildNodeRule.inheritance) are preserved.
+            transformedNodeRules.push(stripNamedProperties(nodeRule, falseRules));
+        }
+        // Determine whether we need derived names (multi-entry)
+        const useGroupName = nonFalseEntries.length > 1;
+        const groupName = useGroupName ? namedRuleName : undefined;
+        for (const [baseRuleName, ruleConfig] of nonFalseEntries) {
+            const baseRule = existingRuleMap.get(baseRuleName);
+            if (!baseRule) {
+                errors.push(new Error(`Base rule "${baseRuleName}" not found for named nodeRule "${namedRuleName}"`));
+                continue;
+            }
+            // For multi-entry: derived name = "groupName/baseRuleName"
+            // For single-entry: use the name directly
+            const aliasName = useGroupName ? `${namedRuleName}/${baseRuleName}` : namedRuleName;
+            // Check derived name collision
+            if (existingRuleMap.has(aliasName)) {
+                errors.push(new Error(`Named nodeRule "${aliasName}" conflicts with an existing rule of the same name`));
+                continue;
+            }
+            if (usedAliasNames.has(aliasName) && aliasName !== namedRuleName) {
+                errors.push(new Error(`Duplicate named nodeRule: "${aliasName}"`));
+                continue;
+            }
+            if (aliasName !== namedRuleName) {
+                usedAliasNames.add(aliasName);
+            }
+            // Create virtual rule by aliasing the base rule
+            const virtualRule = baseRule.createAlias(aliasName, {
+                specConformance: nodeRule.specConformance,
+                groupName,
+            });
+            virtualRules.push(virtualRule);
+            // Transform the nodeRule: change the rules key from base rule name to alias name,
+            // and strip the name/specConformance properties (consumed by the virtual rule)
+            // Safety: same as above — T's structural properties are preserved by stripNamedProperties.
+            transformedNodeRules.push(stripNamedProperties(nodeRule, { [aliasName]: ruleConfig }));
+        }
+    }
+    return { virtualRules, transformedNodeRules, errors };
+}
+/**
+ * Creates a copy of the nodeRule with `name`, `specConformance`, and `rules` removed,
+ * then adds the given replacement rules. Used to transform named nodeRules into
+ * their expanded form.
+ */
+function stripNamedProperties(nodeRule, replacementRules) {
+    const result = {};
+    for (const [key, value] of Object.entries(nodeRule)) {
+        if (key !== 'name' && key !== 'specConformance' && key !== 'rules') {
+            result[key] = value;
+        }
+    }
+    result['rules'] = replacementRules;
+    return result;
+}
+/**
+ * Expands named rule groups in the `rules` section into virtual MLRule instances.
+ *
+ * Named rule groups (keys containing `/` whose values are {@link NamedRuleGroup} objects)
+ * are converted into independent virtual rules, similar to how `expandNamedNodeRules`
+ * handles named nodeRules. This enables per-check control at the global rules level.
+ *
+ * @param rules - The rules dict from the config
+ * @param existingRules - All registered MLRule instances (for base rule lookup)
+ * @returns Virtual rules, resolved rules dict, and any validation errors
+ */
+export function expandNamedRules(rules, existingRules) {
+    const virtualRules = [];
+    const resolvedRules = {};
+    const errors = [];
+    const existingRuleMap = new Map(existingRules.map(r => [r.name, r]));
+    const usedAliasNames = new Set();
+    for (const [key, value] of Object.entries(rules)) {
+        // Non-namespaced keys: pass through as regular rules
+        if (!key.includes('/')) {
+            resolvedRules[key] = value;
+            continue;
+        }
+        // Wildcard patterns (e.g., "a11y/*"): pass through
+        if (key.endsWith('/*')) {
+            resolvedRules[key] = value;
+            continue;
+        }
+        // `false`: disable signal — pass through
+        if (value === false) {
+            resolvedRules[key] = false;
+            continue;
+        }
+        // NamedRuleGroup: expand into virtual rules
+        if (isNamedRuleGroup(value)) {
+            const groupKey = key;
+            const { specConformance, severity: groupSeverity } = value;
+            const groupRules = value.rules;
+            const entries = Object.entries(groupRules);
+            const nonFalseEntries = entries.filter(([, v]) => v !== false);
+            if (nonFalseEntries.length === 0) {
+                errors.push(new Error(`Named rule group "${groupKey}" must have at least one non-false rule entry`));
+                continue;
+            }
+            // Check for duplicate
+            if (usedAliasNames.has(groupKey)) {
+                errors.push(new Error(`Duplicate named rule group: "${groupKey}"`));
+                continue;
+            }
+            usedAliasNames.add(groupKey);
+            // Check for name collision with existing rules
+            if (existingRuleMap.has(groupKey)) {
+                errors.push(new Error(`Named rule group "${groupKey}" conflicts with an existing rule of the same name`));
+                continue;
+            }
+            const useGroupName = nonFalseEntries.length > 1;
+            const gName = useGroupName ? groupKey : undefined;
+            // Determine the defaultSeverity for virtual rules:
+            // 1. Group-level severity override (from user config merge)
+            // 2. undefined (use base rule's default)
+            const effectiveDefaultSeverity = groupSeverity;
+            for (const [baseRuleName, ruleConfig] of nonFalseEntries) {
+                const baseRule = existingRuleMap.get(baseRuleName);
+                if (!baseRule) {
+                    errors.push(new Error(`Base rule "${baseRuleName}" not found for named rule group "${groupKey}"`));
+                    continue;
+                }
+                const aliasName = useGroupName ? `${groupKey}/${baseRuleName}` : groupKey;
+                // Check collisions
+                if (existingRuleMap.has(aliasName)) {
+                    errors.push(new Error(`Named rule group "${aliasName}" conflicts with an existing rule of the same name`));
+                    continue;
+                }
+                if (usedAliasNames.has(aliasName) && aliasName !== groupKey) {
+                    errors.push(new Error(`Duplicate named rule: "${aliasName}"`));
+                    continue;
+                }
+                if (aliasName !== groupKey) {
+                    usedAliasNames.add(aliasName);
+                }
+                // Create virtual rule
+                const virtualRule = baseRule.createAlias(aliasName, {
+                    specConformance,
+                    groupName: gName,
+                    defaultSeverity: effectiveDefaultSeverity,
+                });
+                virtualRules.push(virtualRule);
+                // Add the rule config under the alias name
+                resolvedRules[aliasName] = ruleConfig;
+            }
+        }
+        else {
+            // Not a NamedRuleGroup — treat as regular rule (e.g., user config for a virtual rule)
+            resolvedRules[key] = value;
+        }
+    }
+    // Backwards compatibility: if a base rule is set to false in the rules dict,
+    // also disable any virtual rules from named rule groups that wrap it.
+    // This ensures `"id-duplication": false` still works when the preset wraps
+    // the rule in a named rule group like `"a11y/id-duplication"`.
+    for (const vRule of virtualRules) {
+        if (vRule.baseRuleId && resolvedRules[vRule.baseRuleId] === false) {
+            resolvedRules[vRule.name] = false;
+        }
+    }
+    return { virtualRules, resolvedRules: resolvedRules, errors };
+}

package/package.json

@@ -1,10 +1,13 @@
 {
 	"name": "@markuplint/ml-core",
-	"version": "4.13.2",
+	"version": "5.0.0-alpha.0",
 	"description": "The core module of markuplint",
 	"repository": "git@github.com:markuplint/markuplint.git",
 	"author": "Yusuke Hirao <yusukehirao@me.com>",
 	"license": "MIT",
+	"engines": {
+		"node": ">=22"
+	},
 	"type": "module",
 	"exports": {
 		".": {
@@ -27,20 +30,20 @@
 		"./lib/configs.js": "./lib/configs.browser.js"
 	},
 	"dependencies": {
-		"@markuplint/config-presets": "4.5.13",
-		"@markuplint/html-parser": "4.6.22",
-		"@markuplint/html-spec": "4.16.1",
-		"@markuplint/i18n": "4.7.0",
-		"@markuplint/ml-ast": "4.4.10",
-		"@markuplint/ml-config": "4.8.14",
-		"@markuplint/ml-spec": "4.10.1",
-		"@markuplint/parser-utils": "4.8.10",
-		"@markuplint/selector": "4.7.7",
-		"@markuplint/shared": "4.4.12",
+		"@markuplint/config-presets": "5.0.0-alpha.0",
+		"@markuplint/html-parser": "5.0.0-alpha.0",
+		"@markuplint/html-spec": "5.0.0-alpha.0",
+		"@markuplint/i18n": "5.0.0-alpha.0",
+		"@markuplint/ml-ast": "5.0.0-alpha.0",
+		"@markuplint/ml-config": "5.0.0-alpha.0",
+		"@markuplint/ml-spec": "5.0.0-alpha.0",
+		"@markuplint/parser-utils": "5.0.0-alpha.0",
+		"@markuplint/selector": "5.0.0-alpha.0",
+		"@markuplint/shared": "5.0.0-alpha.0",
 		"@types/debug": "4.1.12",
 		"debug": "4.4.3",
 		"is-plain-object": "5.0.0",
-		"type-fest": "4.41.0"
+		"type-fest": "5.4.4"
 	},
-	"gitHead": "6213ea30269ef404f030e67bbcc7fc7443ec1060"
+	"gitHead": "13dcfc84ec83d87360c720e253383b60767e1b56"
 }