html-validate 7.12.2 → 7.13.0

package/dist/cjs/core.js

@@ -543,6 +543,7 @@ class DOMNode {
         this.nodeName = nodeName !== null && nodeName !== void 0 ? nodeName : DOCUMENT_NODE_NAME;
         this.location = location;
         this.disabledRules = new Set();
+        this.blockedRules = new Map();
         this.childNodes = [];
         this.unique = counter++;
         this.cache = null;
@@ -618,14 +619,42 @@ class DOMNode {
     get lastChild() {
         return this.childNodes[this.childNodes.length - 1] || null;
     }
+    /**
+     * Block a rule for this node.
+     *
+     * @internal
+     */
+    blockRule(ruleId, blocker) {
+        const current = this.blockedRules.get(ruleId);
+        if (current) {
+            current.push(blocker);
+        }
+        else {
+            this.blockedRules.set(ruleId, [blocker]);
+        }
+    }
+    /**
+     * Blocks multiple rules.
+     *
+     * @internal
+     */
+    blockRules(rules, blocker) {
+        for (const rule of rules) {
+            this.blockRule(rule, blocker);
+        }
+    }
     /**
      * Disable a rule for this node.
+     *
+     * @internal
      */
     disableRule(ruleId) {
         this.disabledRules.add(ruleId);
     }
     /**
      * Disables multiple rules.
+     *
+     * @internal
      */
     disableRules(rules) {
         for (const rule of rules) {
@@ -648,10 +677,21 @@ class DOMNode {
     }
     /**
      * Test if a rule is enabled for this node.
+     *
+     * @internal
      */
     ruleEnabled(ruleId) {
         return !this.disabledRules.has(ruleId);
     }
+    /**
+     * Test if a rule is blocked for this node.
+     *
+     * @internal
+     */
+    ruleBlockers(ruleId) {
+        var _a;
+        return (_a = this.blockedRules.get(ruleId)) !== null && _a !== void 0 ? _a : [];
+    }
     generateSelector() {
         return null;
     }
@@ -2707,6 +2747,8 @@ function matchAttributeFacade(node, match) {
 const allowedKeys = ["exclude"];
 /**
  * Helper class to validate elements against metadata rules.
+ *
+ * @public
  */
 class Validator {
     /**
@@ -3462,6 +3504,7 @@ class Rule {
         this.event = null;
         this.options = options;
         this.enabled = true;
+        this.blockers = [];
         this.severity = 0;
         this.name = "";
     }
@@ -3471,6 +3514,26 @@ class Rule {
     setServerity(severity) {
         this.severity = severity;
     }
+    /**
+     * Block this rule from generating errors. Pass in an id generated by {@link
+     * createBlocker}. Can be unblocked by {@link unblock}.
+     *
+     * A blocked rule is similar to disabling it but it will still receive parser
+     * events. A list of all blockers is passed to the `rule:error` event.
+     *
+     * @internal
+     */
+    block(id) {
+        this.blockers.push(id);
+    }
+    /**
+     * Unblock a rule previously blocked by {@link block}.
+     *
+     * @internal
+     */
+    unblock(id) {
+        this.blockers = this.blockers.filter((it) => it !== id);
+    }
     setEnabled(enabled) {
         this.enabled = enabled;
     }
@@ -3487,9 +3550,36 @@ class Rule {
      *
      * To be considered enabled the enabled flag must be true and the severity at
      * least warning.
+     *
+     * @internal
      */
-    isEnabled() {
-        return this.enabled && this.severity >= exports.Severity.WARN;
+    isEnabled(node) {
+        return this.enabled && this.severity >= exports.Severity.WARN && (!node || node.ruleEnabled(this.name));
+    }
+    /**
+     * Test if rule is enabled.
+     *
+     * To be considered enabled the enabled flag must be true and the severity at
+     * least warning.
+     *
+     * @internal
+     */
+    isBlocked(node) {
+        if (this.blockers.length > 0) {
+            return true;
+        }
+        if (node && node.ruleBlockers(this.name).length > 0) {
+            return true;
+        }
+        return false;
+    }
+    /**
+     * Get a list of all blockers currently active this rule.
+     *
+     * @internal
+     */
+    getBlockers(node) {
+        return [...this.blockers, ...(node ? node.ruleBlockers(this.name) : [])];
     }
     /**
      * Check if keyword is being ignored by the current rule configuration.
@@ -3553,8 +3643,16 @@ class Rule {
     }
     report(...args) {
         const { node, message, location, context } = unpackErrorDescriptor(args);
-        if (this.isEnabled() && (!node || node.ruleEnabled(this.name))) {
-            const where = this.findLocation({ node, location, event: this.event });
+        const enabled = this.isEnabled(node);
+        const blocked = this.isBlocked(node);
+        const where = this.findLocation({ node, location, event: this.event });
+        this.parser.trigger("rule:error", {
+            location: where,
+            ruleId: this.name,
+            enabled,
+            blockers: this.getBlockers(node),
+        });
+        if (enabled && !blocked) {
             const interpolated = interpolate(message, context !== null && context !== void 0 ? context : {});
             this.reporter.add(this, interpolated, this.severity, node, where, context);
         }
@@ -4168,7 +4266,7 @@ const MATCH_SCRIPT_DATA = /^[^]*?(?=<\/script)/;
 const MATCH_SCRIPT_END = /^<(\/)(script)/;
 const MATCH_STYLE_DATA = /^[^]*?(?=<\/style)/;
 const MATCH_STYLE_END = /^<(\/)(style)/;
-const MATCH_DIRECTIVE = /^<!--\s*(\[)html-validate-([a-z0-9-]+)\s*(.*?)(]?)\s*-->/;
+const MATCH_DIRECTIVE = /^(<!--\s*\[html-validate-)([a-z0-9-]+)(\s*)(.*?)(]?\s*-->)/;
 const MATCH_COMMENT = /^<!--([^]*?)-->/;
 const MATCH_CONDITIONAL = /^<!\[([^\]]*?)\]>/;
 class InvalidTokenError extends Error {
@@ -7668,6 +7766,39 @@ class NoUnknownElements extends Rule {
     }
 }
 
+class NoUnusedDisable extends Rule {
+    documentation(context) {
+        return {
+            description: context
+                ? `\`${context.ruleId}\` rule is disabled but no error was reported.`
+                : "Rule is disabled but no error was reported.",
+            url: "https://html-validate.org/rules/no-unused-disable.html",
+        };
+    }
+    setup() {
+        /* this is a special rule, the `Engine` class directly emits errors on this
+         * rule, it exists only to be able to configure whenever the rule is enabled
+         * or not and to get the regular documentation and contextual help. */
+    }
+    reportUnused(unused, options, location) {
+        const tokens = new DOMTokenList(options.replace(",", " "), location);
+        for (const ruleId of unused) {
+            const index = tokens.indexOf(ruleId);
+            /* istanbul ignore next: the token should be present or it wouldn't be
+             * reported as unused, this is just a sanity check and fallback */
+            const tokenLocation = index >= 0 ? tokens.location(index) : location;
+            this.report({
+                node: null,
+                message: '"{{ ruleId }}" rule is disabled but no error was reported',
+                location: tokenLocation,
+                context: {
+                    ruleId: ruleId,
+                },
+            });
+        }
+    }
+}
+
 class NoUtf8Bom extends Rule {
     documentation() {
         return {
@@ -9291,6 +9422,7 @@ const bundledRules = {
     "no-style-tag": NoStyleTag,
     "no-trailing-whitespace": NoTrailingWhitespace,
     "no-unknown-elements": NoUnknownElements,
+    "no-unused-disable": NoUnusedDisable,
     "no-utf8-bom": NoUtf8Bom,
     "prefer-button": PreferButton,
     "prefer-native-element": PreferNativeElement,
@@ -9401,6 +9533,7 @@ const config$1 = {
         "no-self-closing": "error",
         "no-trailing-whitespace": "error",
         "no-utf8-bom": "error",
+        "no-unused-disable": "error",
         "prefer-button": "error",
         "prefer-native-element": "error",
         "prefer-tbody": "error",
@@ -9451,6 +9584,7 @@ const config = {
         "no-dup-id": "error",
         "no-multiple-main": "error",
         "no-raw-characters": ["error", { relaxed: true }],
+        "no-unused-disable": "error",
         "script-element": "error",
         "unrecognized-char-ref": "error",
         "valid-id": ["error", { relaxed: true }],
@@ -10250,6 +10384,10 @@ class Parser {
                 offset: 0,
             };
         }
+        /* trigger starting event */
+        this.trigger("parse:begin", {
+            location: null,
+        });
         /* reset DOM in case there are multiple calls in the same session */
         this.dom = new DOMTree({
             filename: (_a = source.filename) !== null && _a !== void 0 ? _a : "",
@@ -10284,6 +10422,10 @@ class Parser {
              * instead */
             location: null,
         });
+        /* trigger ending event */
+        this.trigger("parse:end", {
+            location: null,
+        });
         return this.dom.root;
     }
     /**
@@ -10594,11 +10736,11 @@ class Parser {
         };
     }
     consumeDirective(token) {
-        const [text, , action, directive, end] = token.data;
-        if (end === "") {
+        const [text, preamble, action, separator1, directive, postamble] = token.data;
+        if (!postamble.startsWith("]")) {
             throw new ParserError(token.location, `Missing end bracket "]" on directive "${text}"`);
         }
-        const match = directive.match(/^(.*?)(?:\s*(?:--|:)\s*(.*))?$/);
+        const match = directive.match(/^(.*?)(?:(\s*(?:--|:)\s*)(.*))?$/);
         /* istanbul ignore next: should not be possible, would be emitted as comment token */
         if (!match) {
             throw new Error(`Failed to parse directive "${text}"`);
@@ -10606,12 +10748,32 @@ class Parser {
         if (!isValidDirective(action)) {
             throw new ParserError(token.location, `Unknown directive "${action}"`);
         }
-        const [, data, comment] = match;
+        const [, data, separator2, comment] = match;
+        const prefix = "html-validate-";
+        /* <!-- [html-validate-action options -- comment] -->
+         *                     ^      ^          ^--------------- comment offset
+         *                     |      \-------------------------- options offset
+         *                     \--------------------------------- action offset
+         */
+        const actionOffset = preamble.length;
+        const optionsOffset = actionOffset + action.length + separator1.length;
+        const commentOffset = optionsOffset + data.length + (separator2 || "").length;
+        const location = sliceLocation(token.location, preamble.length - prefix.length - 1, -postamble.length + 1);
+        const actionLocation = sliceLocation(token.location, actionOffset, actionOffset + action.length);
+        const optionsLocation = data
+            ? sliceLocation(token.location, optionsOffset, optionsOffset + data.length)
+            : undefined;
+        const commentLocation = comment
+            ? sliceLocation(token.location, commentOffset, commentOffset + comment.length)
+            : undefined;
         this.trigger("directive", {
             action,
             data,
             comment: comment || "",
-            location: token.location,
+            location,
+            actionLocation,
+            optionsLocation,
+            commentLocation,
         });
     }
     /**
@@ -10897,6 +11059,18 @@ function messageSort(a, b) {
     return 0;
 }
 
+let blockerCounter = 1;
+/**
+ * Creates a new rule blocker for using when blocking rules from generating
+ * errors.
+ *
+ * @internal
+ */
+function createBlocker() {
+    const id = blockerCounter++;
+    return id;
+}
+
 /**
  * @internal
  */
@@ -10924,6 +11098,15 @@ class Engine {
             const parser = this.instantiateParser();
             /* setup plugins and rules */
             const { rules } = this.setupPlugins(source, this.config, parser);
+            const noUnusedDisable = rules["no-unused-disable"];
+            const directiveContext = {
+                rules,
+                reportUnused(unused, options, location) {
+                    if (noUnusedDisable) {
+                        noUnusedDisable.reportUnused(unused, options, location);
+                    }
+                },
+            };
             /* create a faux location at the start of the stream for the next events */
             const location = {
                 filename: source.filename,
@@ -10949,7 +11132,7 @@ class Engine {
             parser.trigger("source:ready", sourceEvent);
             /* setup directive handling */
             parser.on("directive", (_, event) => {
-                this.processDirective(event, parser, rules);
+                this.processDirective(event, parser, directiveContext);
             });
             /* parse token stream */
             try {
@@ -11056,12 +11239,15 @@ class Engine {
     instantiateParser() {
         return new this.ParserClass(this.config);
     }
-    processDirective(event, parser, allRules) {
+    processDirective(event, parser, context) {
+        var _a;
         const rules = event.data
             .split(",")
             .map((name) => name.trim())
-            .map((name) => allRules[name])
+            .map((name) => context.rules[name])
             .filter((rule) => rule); /* filter out missing rules */
+        /* istanbul ignore next: option must be present or there would be no rules to disable */
+        const location = (_a = event.optionsLocation) !== null && _a !== void 0 ? _a : event.location;
         switch (event.action) {
             case "enable":
                 this.processEnableDirective(rules, parser);
@@ -11070,10 +11256,10 @@ class Engine {
                 this.processDisableDirective(rules, parser);
                 break;
             case "disable-block":
-                this.processDisableBlockDirective(rules, parser);
+                this.processDisableBlockDirective(context, rules, parser, event.data, location);
                 break;
             case "disable-next":
-                this.processDisableNextDirective(rules, parser);
+                this.processDisableNextDirective(context, rules, parser, event.data, location);
                 break;
         }
     }
@@ -11098,10 +11284,13 @@ class Engine {
             data.target.disableRules(rules.map((rule) => rule.name));
         });
     }
-    processDisableBlockDirective(rules, parser) {
+    processDisableBlockDirective(context, rules, parser, options, location) {
+        const ruleIds = rules.map((it) => it.name);
+        const blocker = createBlocker();
+        const unused = new Set(ruleIds);
         let directiveBlock = null;
         for (const rule of rules) {
-            rule.setEnabled(false);
+            rule.block(blocker);
         }
         const unregisterOpen = parser.on("tag:start", (event, data) => {
             var _a, _b;
@@ -11113,7 +11302,7 @@ class Engine {
             }
             /* disable rules directly on the node so it will be recorded for later,
              * more specifically when using the domtree to trigger errors */
-            data.target.disableRules(rules.map((rule) => rule.name));
+            data.target.blockRules(ruleIds, blocker);
         });
         const unregisterClose = parser.on("tag:end", (event, data) => {
             /* if the directive is the last thing in a block no id would be set */
@@ -11126,26 +11315,45 @@ class Engine {
                 unregisterClose();
                 unregisterOpen();
                 for (const rule of rules) {
-                    rule.setEnabled(true);
+                    rule.unblock(blocker);
                 }
             }
         });
+        parser.on("rule:error", (event, data) => {
+            if (data.blockers.includes(blocker)) {
+                unused.delete(data.ruleId);
+            }
+        });
+        parser.on("parse:end", () => {
+            context.reportUnused(unused, options, location);
+        });
     }
-    processDisableNextDirective(rules, parser) {
+    processDisableNextDirective(context, rules, parser, options, location) {
+        const ruleIds = rules.map((it) => it.name);
+        const blocker = createBlocker();
+        const unused = new Set(ruleIds);
         for (const rule of rules) {
-            rule.setEnabled(false);
+            rule.block(blocker);
         }
-        /* disable rules directly on the node so it will be recorded for later,
+        /* block rules directly on the node so it will be recorded for later,
          * more specifically when using the domtree to trigger errors */
         const unregister = parser.on("tag:start", (event, data) => {
-            data.target.disableRules(rules.map((rule) => rule.name));
+            data.target.blockRules(ruleIds, blocker);
+        });
+        parser.on("rule:error", (event, data) => {
+            if (data.blockers.includes(blocker)) {
+                unused.delete(data.ruleId);
+            }
+        });
+        parser.on("parse:end", () => {
+            context.reportUnused(unused, options, location);
         });
         /* disable directive after next event occurs */
         parser.once("tag:ready, tag:end, attr", () => {
             unregister();
             parser.defer(() => {
                 for (const rule of rules) {
-                    rule.setEnabled(true);
+                    rule.unblock(blocker);
                 }
             });
         });
@@ -11537,7 +11745,7 @@ class HtmlValidate {
 /** @public */
 const name = "html-validate";
 /** @public */
-const version = "7.12.2";
+const version = "7.13.0";
 /** @public */
 const bugs = "https://gitlab.com/html-validate/html-validate/issues/new";
 
@@ -12000,6 +12208,7 @@ exports.StaticConfigLoader = StaticConfigLoader;
 exports.TemplateExtractor = TemplateExtractor;
 exports.TextNode = TextNode;
 exports.UserError = UserError;
+exports.Validator = Validator;
 exports.WrappedError = WrappedError;
 exports.bugs = bugs;
 exports.codeframe = codeframe;