html-validate 7.1.2 → 7.2.0

package/dist/es/core.js

@@ -3086,7 +3086,7 @@ var TRANSFORMER_API;
 /** @public */
 const name = "html-validate";
 /** @public */
-const version = "7.1.2";
+const version = "7.2.0";
 /** @public */
 const homepage = "https://html-validate.org";
 /** @public */
@@ -3187,6 +3187,18 @@ function getSchemaValidator(ruleId, properties) {
     };
     return ajv$1.compile(schema);
 }
+function isErrorDescriptor(value) {
+    return Boolean(value[0] && value[0].message);
+}
+function unpackErrorDescriptor(value) {
+    if (isErrorDescriptor(value)) {
+        return value[0];
+    }
+    else {
+        const [node, message, location, context] = value;
+        return { node, message, location, context };
+    }
+}
 /**
  * @public
  */
@@ -3287,13 +3299,8 @@ class Rule {
     static schema() {
         return null;
     }
-    /**
-     * Report a new error.
-     *
-     * Rule must be enabled both globally and on the specific node for this to
-     * have any effect.
-     */
-    report(node, message, location, context) {
+    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 interpolated = interpolate(message, context !== null && context !== void 0 ? context : {});
@@ -3806,9 +3813,14 @@ class AttrCase extends Rule {
                 return;
             }
             const letters = event.key.replace(/[^a-z]+/gi, "");
-            if (!this.style.match(letters)) {
-                this.report(event.target, `Attribute "${event.key}" should be ${this.style.name}`, event.keyLocation);
+            if (this.style.match(letters)) {
+                return;
             }
+            this.report({
+                node: event.target,
+                message: `Attribute "${event.key}" should be ${this.style.name}`,
+                location: event.keyLocation,
+            });
         });
     }
     isIgnored(node) {
@@ -5108,6 +5120,11 @@ class ElementName extends Rule {
     }
 }
 
+var ErrorKind;
+(function (ErrorKind) {
+    ErrorKind["CONTENT"] = "content";
+    ErrorKind["DESCENDANT"] = "descendant";
+})(ErrorKind || (ErrorKind = {}));
 function getTransparentChildren(node, transparent) {
     if (typeof transparent === "boolean") {
         return node.childElements;
@@ -5121,10 +5138,28 @@ function getTransparentChildren(node, transparent) {
         });
     }
 }
+function getRuleDescription$1(context) {
+    if (!context) {
+        return [
+            "Some elements has restrictions on what content is allowed.",
+            "This can include both direct children or descendant elements.",
+        ];
+    }
+    switch (context.kind) {
+        case ErrorKind.CONTENT:
+            return [
+                `The \`${context.child}\` element is not permitted as content under the parent \`${context.parent}\` element.`,
+            ];
+        case ErrorKind.DESCENDANT:
+            return [
+                `The \`${context.child}\` element is not permitted as a descendant of the \`${context.ancestor}\` element.`,
+            ];
+    }
+}
 class ElementPermittedContent extends Rule {
-    documentation() {
+    documentation(context) {
         return {
-            description: "Some elements has restrictions on what content is allowed. This can include both direct children or descendant elements.",
+            description: getRuleDescription$1(context).join("\n"),
             url: ruleDocumentationUrl("@/rules/element-permitted-content.ts"),
         };
     }
@@ -5133,8 +5168,9 @@ class ElementPermittedContent extends Rule {
             const doc = event.document;
             doc.visitDepthFirst((node) => {
                 const parent = node.parent;
-                /* dont verify root element, assume any element is allowed */
-                if (!parent || parent.isRootElement()) {
+                /* istanbul ignore next: satisfy typescript but will visitDepthFirst()
+                 * will not yield nodes without a parent */
+                if (!parent) {
                     return;
                 }
                 /* Run each validation step, stop as soon as any errors are
@@ -5144,7 +5180,6 @@ class ElementPermittedContent extends Rule {
                 [
                     () => this.validatePermittedContent(node, parent),
                     () => this.validatePermittedDescendant(node, parent),
-                    () => this.validatePermittedAncestors(node),
                 ].some((fn) => fn());
             });
         });
@@ -5161,7 +5196,14 @@ class ElementPermittedContent extends Rule {
     }
     validatePermittedContentImpl(cur, parent, rules) {
         if (!Validator.validatePermitted(cur, rules)) {
-            this.report(cur, `Element <${cur.tagName}> is not permitted as content in ${parent.annotatedName}`);
+            const child = `<${cur.tagName}>`;
+            const message = `${child} element is not permitted as content under ${parent.annotatedName}`;
+            const context = {
+                kind: ErrorKind.CONTENT,
+                parent: parent.annotatedName,
+                child,
+            };
+            this.report(cur, message, null, context);
             return true;
         }
         /* for transparent elements all/listed children must be validated against
@@ -5192,21 +5234,15 @@ class ElementPermittedContent extends Rule {
             if (Validator.validatePermitted(node, rules)) {
                 continue;
             }
-            this.report(node, `Element <${node.tagName}> is not permitted as descendant of ${cur.annotatedName}`);
-            return true;
-        }
-        return false;
-    }
-    validatePermittedAncestors(node) {
-        if (!node.meta) {
-            return false;
-        }
-        const rules = node.meta.requiredAncestors;
-        if (!rules) {
-            return false;
-        }
-        if (!Validator.validateAncestors(node, rules)) {
-            this.report(node, `Element <${node.tagName}> requires an "${rules[0]}" ancestor`);
+            const child = `<${node.tagName}>`;
+            const ancestor = cur.annotatedName;
+            const message = `${child} element is not permitted as a descendant of ${ancestor}`;
+            const context = {
+                kind: ErrorKind.DESCENDANT,
+                ancestor,
+                child,
+            };
+            this.report(node, message, null, context);
             return true;
         }
         return false;
@@ -5273,6 +5309,152 @@ class ElementPermittedOrder extends Rule {
     }
 }
 
+const CACHE_KEY = Symbol(classifyNodeText.name);
+var TextClassification;
+(function (TextClassification) {
+    TextClassification[TextClassification["EMPTY_TEXT"] = 0] = "EMPTY_TEXT";
+    TextClassification[TextClassification["DYNAMIC_TEXT"] = 1] = "DYNAMIC_TEXT";
+    TextClassification[TextClassification["STATIC_TEXT"] = 2] = "STATIC_TEXT";
+})(TextClassification || (TextClassification = {}));
+/**
+ * Checks text content of an element.
+ *
+ * Any text is considered including text from descendant elements. Whitespace is
+ * ignored.
+ *
+ * If any text is dynamic `TextClassification.DYNAMIC_TEXT` is returned.
+ */
+function classifyNodeText(node) {
+    if (node.cacheExists(CACHE_KEY)) {
+        return node.cacheGet(CACHE_KEY);
+    }
+    const text = findTextNodes(node);
+    /* if any text is dynamic classify as dynamic */
+    if (text.some((cur) => cur.isDynamic)) {
+        return node.cacheSet(CACHE_KEY, TextClassification.DYNAMIC_TEXT);
+    }
+    /* if any text has non-whitespace character classify as static */
+    if (text.some((cur) => cur.textContent.match(/\S/) !== null)) {
+        return node.cacheSet(CACHE_KEY, TextClassification.STATIC_TEXT);
+    }
+    /* default to empty */
+    return node.cacheSet(CACHE_KEY, TextClassification.EMPTY_TEXT);
+}
+function findTextNodes(node) {
+    let text = [];
+    for (const child of node.childNodes) {
+        switch (child.nodeType) {
+            case NodeType.TEXT_NODE:
+                text.push(child);
+                break;
+            case NodeType.ELEMENT_NODE:
+                text = text.concat(findTextNodes(child));
+                break;
+        }
+    }
+    return text;
+}
+
+function hasAltText(image) {
+    const alt = image.getAttribute("alt");
+    /* missing or boolean */
+    if (alt === null || alt.value === null) {
+        return false;
+    }
+    return alt.isDynamic || alt.value.toString() !== "";
+}
+
+function hasAriaLabel(node) {
+    const label = node.getAttribute("aria-label");
+    /* missing or boolean */
+    if (label === null || label.value === null) {
+        return false;
+    }
+    return label.isDynamic || label.value.toString() !== "";
+}
+
+/**
+ * Joins a list of words into natural language.
+ *
+ * - `["foo"]` becomes `"foo"`
+ * - `["foo", "bar"]` becomes `"foo or bar"`
+ * - `["foo", "bar", "baz"]` becomes `"foo, bar or baz"`
+ * - and so on...
+ *
+ * @internal
+ * @param values - List of words to join
+ * @param conjunction - Conjunction for the last element.
+ * @returns String with the words naturally joined with a conjunction.
+ */
+function naturalJoin(values, conjunction = "or") {
+    switch (values.length) {
+        case 0:
+            return "";
+        case 1:
+            return values[0];
+        case 2:
+            return `${values[0]} ${conjunction} ${values[1]}`;
+        default:
+            return `${values.slice(0, -1).join(", ")} ${conjunction} ${values.slice(-1)[0]}`;
+    }
+}
+
+function isTagnameOnly(value) {
+    return Boolean(value.match(/^[a-zA-Z0-9-]+$/));
+}
+function getRuleDescription(context) {
+    if (!context) {
+        return [
+            "Some elements has restrictions on what content is allowed.",
+            "This can include both direct children or descendant elements.",
+        ];
+    }
+    const escaped = context.ancestor.map((it) => `\`${it}\``);
+    return [`The \`${context.child}\` element requires a ${naturalJoin(escaped)} ancestor.`];
+}
+class ElementRequiredAncestor extends Rule {
+    documentation(context) {
+        return {
+            description: getRuleDescription(context).join("\n"),
+            url: ruleDocumentationUrl("@/rules/element-required-ancestor.ts"),
+        };
+    }
+    setup() {
+        this.on("dom:ready", (event) => {
+            const doc = event.document;
+            doc.visitDepthFirst((node) => {
+                const parent = node.parent;
+                /* istanbul ignore next: satisfy typescript but will visitDepthFirst()
+                 * will not yield nodes without a parent */
+                if (!parent) {
+                    return;
+                }
+                this.validateRequiredAncestors(node);
+            });
+        });
+    }
+    validateRequiredAncestors(node) {
+        if (!node.meta) {
+            return;
+        }
+        const rules = node.meta.requiredAncestors;
+        if (!rules) {
+            return;
+        }
+        if (Validator.validateAncestors(node, rules)) {
+            return;
+        }
+        const ancestor = rules.map((it) => (isTagnameOnly(it) ? `<${it}>` : `"${it}"`));
+        const child = `<${node.tagName}>`;
+        const message = `<${node.tagName}> element requires a ${naturalJoin(ancestor)} ancestor`;
+        const context = {
+            ancestor,
+            child,
+        };
+        this.report(node, message, null, context);
+    }
+}
+
 class ElementRequiredAttributes extends Rule {
     documentation(context) {
         const docs = {
@@ -5350,52 +5532,6 @@ class ElementRequiredContent extends Rule {
     }
 }
 
-const CACHE_KEY = Symbol(classifyNodeText.name);
-var TextClassification;
-(function (TextClassification) {
-    TextClassification[TextClassification["EMPTY_TEXT"] = 0] = "EMPTY_TEXT";
-    TextClassification[TextClassification["DYNAMIC_TEXT"] = 1] = "DYNAMIC_TEXT";
-    TextClassification[TextClassification["STATIC_TEXT"] = 2] = "STATIC_TEXT";
-})(TextClassification || (TextClassification = {}));
-/**
- * Checks text content of an element.
- *
- * Any text is considered including text from descendant elements. Whitespace is
- * ignored.
- *
- * If any text is dynamic `TextClassification.DYNAMIC_TEXT` is returned.
- */
-function classifyNodeText(node) {
-    if (node.cacheExists(CACHE_KEY)) {
-        return node.cacheGet(CACHE_KEY);
-    }
-    const text = findTextNodes(node);
-    /* if any text is dynamic classify as dynamic */
-    if (text.some((cur) => cur.isDynamic)) {
-        return node.cacheSet(CACHE_KEY, TextClassification.DYNAMIC_TEXT);
-    }
-    /* if any text has non-whitespace character classify as static */
-    if (text.some((cur) => cur.textContent.match(/\S/) !== null)) {
-        return node.cacheSet(CACHE_KEY, TextClassification.STATIC_TEXT);
-    }
-    /* default to empty */
-    return node.cacheSet(CACHE_KEY, TextClassification.EMPTY_TEXT);
-}
-function findTextNodes(node) {
-    let text = [];
-    for (const child of node.childNodes) {
-        switch (child.nodeType) {
-            case NodeType.TEXT_NODE:
-                text.push(child);
-                break;
-            case NodeType.ELEMENT_NODE:
-                text = text.concat(findTextNodes(child));
-                break;
-        }
-    }
-    return text;
-}
-
 const selector = ["h1", "h2", "h3", "h4", "h5", "h6"].join(",");
 class EmptyHeading extends Rule {
     documentation() {
@@ -7576,24 +7712,6 @@ class TelNonBreaking extends Rule {
     }
 }
 
-function hasAltText(image) {
-    const alt = image.getAttribute("alt");
-    /* missing or boolean */
-    if (alt === null || alt.value === null) {
-        return false;
-    }
-    return alt.isDynamic || alt.value.toString() !== "";
-}
-
-function hasAriaLabel(node) {
-    const label = node.getAttribute("aria-label");
-    /* missing or boolean */
-    if (label === null || label.value === null) {
-        return false;
-    }
-    return label.isDynamic || label.value.toString() !== "";
-}
-
 /**
  * Check if attribute is present and non-empty or dynamic.
  */
@@ -9771,13 +9889,13 @@ class VoidStyle extends Rule {
             return;
         }
         if (this.shouldBeOmitted(node)) {
-            this.report(node, `Expected omitted end tag <${node.tagName}> instead of self-closing element <${node.tagName}/>`);
+            this.reportError(node, `Expected omitted end tag <${node.tagName}> instead of self-closing element <${node.tagName}/>`);
         }
         if (this.shouldBeSelfClosed(node)) {
-            this.report(node, `Expected self-closing element <${node.tagName}/> instead of omitted end-tag <${node.tagName}>`);
+            this.reportError(node, `Expected self-closing element <${node.tagName}/> instead of omitted end-tag <${node.tagName}>`);
         }
     }
-    report(node, message) {
+    reportError(node, message) {
         const context = {
             style: this.style,
             tagName: node.tagName,
@@ -10089,6 +10207,7 @@ const bundledRules = {
     "element-permitted-content": ElementPermittedContent,
     "element-permitted-occurrences": ElementPermittedOccurrences,
     "element-permitted-order": ElementPermittedOrder,
+    "element-required-ancestor": ElementRequiredAncestor,
     "element-required-attributes": ElementRequiredAttributes,
     "element-required-content": ElementRequiredContent,
     "empty-heading": EmptyHeading,
@@ -10196,6 +10315,7 @@ const config$1 = {
         "element-permitted-content": "error",
         "element-permitted-occurrences": "error",
         "element-permitted-order": "error",
+        "element-required-ancestor": "error",
         "element-required-attributes": "error",
         "element-required-content": "error",
         "empty-heading": "error",
@@ -10254,6 +10374,7 @@ const config = {
         "element-permitted-content": "error",
         "element-permitted-occurrences": "error",
         "element-permitted-order": "error",
+        "element-required-ancestor": "error",
         "element-required-attributes": "error",
         "element-required-content": "error",
         "multiple-labeled-controls": "error",
@@ -10333,6 +10454,7 @@ class ResolvedConfig {
                 });
             }
             catch (err) {
+                /* istanbul ignore next: only used as a fallback */
                 const message = err instanceof Error ? err.message : String(err);
                 throw new NestedError(`When transforming "${source.filename}": ${message}`, ensureError(err));
             }
@@ -10345,7 +10467,7 @@ class ResolvedConfig {
      * Wrapper around [[transformSource]] which reads a file before passing it
      * as-is to transformSource.
      *
-     * @param source - Filename to transform (according to configured
+     * @param filename - Filename to transform (according to configured
      * transformations)
      * @returns A list of transformed sources ready for validation.
      */
@@ -10501,7 +10623,9 @@ class Config {
         var _a;
         const valid = validator(configData);
         if (!valid) {
-            throw new SchemaValidationError(filename, `Invalid configuration`, configData, configurationSchema, (_a = validator.errors) !== null && _a !== void 0 ? _a : []);
+            throw new SchemaValidationError(filename, `Invalid configuration`, configData, configurationSchema, 
+            /* istanbul ignore next: will be set when a validation error has occurred */
+            (_a = validator.errors) !== null && _a !== void 0 ? _a : []);
         }
         if (configData.rules) {
             const normalizedRules = Config.getRulesObject(configData.rules);
@@ -10610,6 +10734,7 @@ class Config {
                 metaTable.loadFromObject(legacyRequire(entry));
             }
             catch (err) {
+                /* istanbul ignore next: only used as a fallback */
                 const message = err instanceof Error ? err.message : String(err);
                 throw new ConfigError(`Failed to load elements from "${entry}": ${message}`, ensureError(err));
             }
@@ -10631,6 +10756,7 @@ class Config {
      *
      * @internal primary purpose is unittests
      */
+    /* istanbul ignore next: used for testing only */
     get() {
         const config = { ...this.config };
         if (config.elements) {
@@ -10653,6 +10779,7 @@ class Config {
      */
     getRules() {
         var _a;
+        /* istanbul ignore next: only used as a fallback */
         return Config.getRulesObject((_a = this.config.rules) !== null && _a !== void 0 ? _a : {});
     }
     static getRulesObject(src) {
@@ -10687,6 +10814,7 @@ class Config {
                 return plugin;
             }
             catch (err) {
+                /* istanbul ignore next: only used as a fallback */
                 const message = err instanceof Error ? err.message : String(err);
                 throw new ConfigError(`Failed to load plugin "${moduleName}": ${message}`, ensureError(err));
             }
@@ -11602,9 +11730,9 @@ class Reporter {
         if (!(location.filename in this.result)) {
             this.result[location.filename] = [];
         }
-        this.result[location.filename].push({
+        const ruleUrl = (_a = rule.documentation(context)) === null || _a === void 0 ? void 0 : _a.url;
+        const entry = {
             ruleId: rule.name,
-            ruleUrl: (_a = rule.documentation(context)) === null || _a === void 0 ? void 0 : _a.url,
             severity,
             message,
             offset: location.offset,
@@ -11614,8 +11742,14 @@ class Reporter {
             selector() {
                 return node ? node.generateSelector() : null;
             },
-            context,
-        });
+        };
+        if (ruleUrl) {
+            entry.ruleUrl = ruleUrl;
+        }
+        if (context) {
+            entry.context = context;
+        }
+        this.result[location.filename].push(entry);
     }
     addManual(filename, message) {
         if (!(filename in this.result)) {
@@ -12029,7 +12163,7 @@ class Engine {
             offset: location.offset,
             line: location.line,
             column: location.column,
-            size: location.size || 0,
+            size: location.size,
             selector: () => null,
         });
     }
@@ -12459,12 +12593,12 @@ class FileSystemConfigLoader extends ConfigLoader {
      * `null` if no configuration files are found.
      */
     fromFilename(filename) {
-        var _a;
         if (filename === "inline") {
             return null;
         }
-        if (this.cache.has(filename)) {
-            return (_a = this.cache.get(filename)) !== null && _a !== void 0 ? _a : null;
+        const cache = this.cache.get(filename);
+        if (cache) {
+            return cache;
         }
         let found = false;
         let current = path.resolve(path.dirname(filename));