@blamejs/core 0.7.104 → 0.7.106

package/lib/guard-html-wcag-aria.js

@@ -0,0 +1,164 @@
+"use strict";
+
+var validateOpts = require("./validate-opts");
+var tagwalk = require("./guard-html-wcag-tagwalk");
+
+var KNOWN_ROLES = Object.freeze([
+  "banner","complementary","contentinfo","form","main","navigation","region","search",
+  "alert","alertdialog","log","marquee","status","timer",
+  "article","definition","directory","document","feed","figure","group","heading","img",
+  "list","listitem","math","note","presentation","none","row","rowgroup","rowheader",
+  "separator","table","term","toolbar","tooltip",
+  "button","checkbox","combobox","dialog","grid","gridcell","link","listbox","menu",
+  "menubar","menuitem","menuitemcheckbox","menuitemradio","option","progressbar","radio",
+  "radiogroup","scrollbar","searchbox","slider","spinbutton","switch","tab","tablist",
+  "tabpanel","textbox","tree","treegrid","treeitem","application",
+]);
+
+var ROLE_REQUIRED_PROPS = Object.freeze({
+  "checkbox":         ["aria-checked"],
+  "switch":           ["aria-checked"],
+  "radio":            ["aria-checked"],
+  "menuitemradio":    ["aria-checked"],
+  "menuitemcheckbox": ["aria-checked"],
+  "combobox":         ["aria-expanded"],
+  "scrollbar":        ["aria-valuenow"],
+  "slider":           ["aria-valuenow"],
+  "spinbutton":       ["aria-valuenow"],
+  "heading":          ["aria-level"],
+  "option":           ["aria-selected"],
+});
+
+var ARIA_VALUE_SETS = Object.freeze({
+  "aria-checked":     ["true","false","mixed"],
+  "aria-expanded":    ["true","false"],
+  "aria-pressed":     ["true","false","mixed"],
+  "aria-selected":    ["true","false"],
+  "aria-disabled":    ["true","false"],
+  "aria-hidden":      ["true","false"],
+  "aria-haspopup":    ["false","true","menu","listbox","tree","grid","dialog"],
+  "aria-orientation": ["horizontal","vertical"],
+  "aria-current":     ["page","step","location","date","time","true","false"],
+  "aria-live":        ["off","polite","assertive"],
+  "aria-sort":        ["ascending","descending","none","other"],
+  "aria-autocomplete":["inline","list","both","none"],
+});
+
+var _TAG_RE = tagwalk.TAG_RE;
+var _parseAttrs = tagwalk.parseAttrs;
+var _lineColAt = tagwalk.lineColAt;
+
+function audit(html, opts) {
+  opts = opts || {};
+  validateOpts(opts, ["allowedRoles", "scopeUrl"], "guardHtml.wcag.aria.audit");
+  if (typeof html !== "string") {
+    throw new TypeError("aria.audit: html must be a string");
+  }
+  var allowedRoles = Array.isArray(opts.allowedRoles)
+    ? KNOWN_ROLES.concat(opts.allowedRoles)
+    : KNOWN_ROLES;
+
+  var findings = [];
+  function _add(f) { findings.push(f); }
+
+  var declaredIds = Object.create(null);
+  var idRe = /\bid\s*=\s*["']([^"']+)["']/gi;
+  var im;
+  while ((im = idRe.exec(html))) {                                                 // RegExp.prototype.exec
+    declaredIds[im[1]] = true;
+  }
+
+  _TAG_RE.lastIndex = 0;
+  var m;
+  while ((m = _TAG_RE.exec(html))) {                                               // RegExp.prototype.exec
+    if (m[0].charAt(1) === "/") continue;
+    var tagName = m[1].toLowerCase();
+    var attrs = _parseAttrs(m[2]);
+    var offset = m.index;
+    var pos = _lineColAt(html, offset);
+
+    if ("role" in attrs) {
+      var roles = attrs.role.split(/\s+/).filter(Boolean);
+      for (var ri = 0; ri < roles.length; ri++) {
+        if (allowedRoles.indexOf(roles[ri]) === -1) {
+          _add({
+            sc: "4.1.2", level: "A", severity: "warning",
+            element: tagName, line: pos.line, column: pos.column,
+            message: "Unknown ARIA role \"" + roles[ri] + "\" (typo? unsupported by AT?)",
+            remediation: "Use a known WAI-ARIA 1.2 role or remove the role attribute",
+          });
+        }
+      }
+      for (var rj = 0; rj < roles.length; rj++) {
+        var required = ROLE_REQUIRED_PROPS[roles[rj]];
+        if (!Array.isArray(required) || required.length === 0) continue;
+        for (var ai = 0; ai < required.length; ai++) {
+          if (!(required[ai] in attrs)) {
+            _add({
+              sc: "4.1.2", level: "A", severity: "error",
+              element: tagName, line: pos.line, column: pos.column,
+              message: "ARIA role=\"" + roles[rj] + "\" requires attribute \"" + required[ai] + "\"",
+              remediation: "Add " + required[ai] + "=\"<valid-value>\" to the element",
+            });
+          }
+        }
+      }
+    }
+
+    var attrNames = Object.keys(attrs);
+    for (var ki = 0; ki < attrNames.length; ki++) {
+      var key = attrNames[ki];
+      if (key.indexOf("aria-") !== 0) continue;
+      var allowedValues = ARIA_VALUE_SETS[key];
+      if (!Array.isArray(allowedValues)) continue;
+      var v = String(attrs[key]).trim();
+      if (allowedValues.indexOf(v) === -1) {
+        _add({
+          sc: "4.1.2", level: "A", severity: "error",
+          element: tagName, line: pos.line, column: pos.column,
+          message: key + "=\"" + v + "\" is not in the allowed value set [" + allowedValues.join(", ") + "]",
+          remediation: "Set " + key + " to one of the allowed values",
+        });
+      }
+    }
+
+    var refAttrs = ["aria-labelledby", "aria-controls", "aria-describedby"];
+    for (var rai = 0; rai < refAttrs.length; rai++) {
+      var refKey = refAttrs[rai];
+      if (!(refKey in attrs)) continue;
+      var idsRefd = attrs[refKey].split(/\s+/).filter(Boolean);
+      for (var idi = 0; idi < idsRefd.length; idi++) {
+        if (!declaredIds[idsRefd[idi]]) {
+          _add({
+            sc: "4.1.2", level: "A", severity: "error",
+            element: tagName, line: pos.line, column: pos.column,
+            message: refKey + "=\"" + idsRefd[idi] + "\" references id that is not declared in the document",
+            remediation: "Either declare an element with id=\"" + idsRefd[idi] + "\" or remove the reference",
+          });
+        }
+      }
+    }
+
+    if (attrs["aria-hidden"] === "true") {
+      var interactive = ["a", "button", "input", "select", "textarea"].indexOf(tagName) !== -1;
+      var hasTabindex = "tabindex" in attrs && attrs.tabindex !== "-1";
+      if (interactive || hasTabindex) {
+        _add({
+          sc: "4.1.2", level: "A", severity: "error",
+          element: tagName, line: pos.line, column: pos.column,
+          message: "aria-hidden=\"true\" on interactive element",
+          remediation: "Remove aria-hidden, or remove from focus order via tabindex=\"-1\" (and disable interactivity)",
+        });
+      }
+    }
+  }
+
+  return findings;
+}
+
+module.exports = {
+  audit:               audit,
+  KNOWN_ROLES:         KNOWN_ROLES,
+  ROLE_REQUIRED_PROPS: ROLE_REQUIRED_PROPS,
+  ARIA_VALUE_SETS:     ARIA_VALUE_SETS,
+};

package/lib/guard-html-wcag-forms.js

@@ -0,0 +1,144 @@
+"use strict";
+/**
+ * Form-specific accessibility validation for the WCAG 2.2 audit-only
+ * scanner.
+ *
+ * Checks:
+ *   - <fieldset> without <legend> (WCAG 1.3.1)
+ *   - <input autocomplete=""> against the HTML 5.3 token registry
+ *     (WCAG 1.3.5 — Identify Input Purpose)
+ *   - Required field without aria-required / required (WCAG 3.3.7)
+ *   - Form submit without explicit submit button or commit-on-enter
+ *     marker (WCAG 3.3.4 — Error Prevention)
+ *   - <input type="password"> within an autocomplete-disabled form
+ *     (WCAG 3.3.8 — Accessible Authentication)
+ *   - <textarea> without label / aria-label (WCAG 3.3.2)
+ *
+ * Exposed under b.guardHtml.wcag.forms.audit(html, opts).
+ */
+
+var validateOpts = require("./validate-opts");
+var tagwalk = require("./guard-html-wcag-tagwalk");
+
+// HTML 5.3 §4.10.18.7.1 — autocomplete token registry. Operators
+// override / extend via opts.allowedAutocomplete. The framework
+// allowlists the most common values; rare ones are flagged as
+// warnings (operator might be using a custom token in error).
+var AUTOCOMPLETE_TOKENS = Object.freeze([
+  "off", "on",
+  "name", "honorific-prefix", "given-name", "additional-name", "family-name",
+  "honorific-suffix", "nickname", "username", "new-password", "current-password",
+  "one-time-code",
+  "organization-title", "organization",
+  "street-address", "address-line1", "address-line2", "address-line3",
+  "address-level4", "address-level3", "address-level2", "address-level1",
+  "country", "country-name", "postal-code",
+  "cc-name", "cc-given-name", "cc-additional-name", "cc-family-name",
+  "cc-number", "cc-exp", "cc-exp-month", "cc-exp-year", "cc-csc", "cc-type",
+  "transaction-currency", "transaction-amount",
+  "language",
+  "bday", "bday-day", "bday-month", "bday-year", "sex",
+  "tel", "tel-country-code", "tel-national", "tel-area-code", "tel-local",
+  "tel-extension", "email",
+  "impp", "url", "photo",
+]);
+
+function audit(html, opts) {
+  opts = opts || {};
+  validateOpts(opts, [
+    "allowedAutocomplete", "scopeUrl",
+  ], "guardHtml.wcag.forms.audit");
+  if (typeof html !== "string") {
+    throw new TypeError("forms.audit: html must be a string");
+  }
+  var allowed = Array.isArray(opts.allowedAutocomplete)
+    ? AUTOCOMPLETE_TOKENS.concat(opts.allowedAutocomplete)
+    : AUTOCOMPLETE_TOKENS;
+
+  var findings = [];
+  function _add(f) { findings.push(f); }
+
+  // Pre-scan: is there a <legend> inside any <fieldset>?
+  // We track fieldset → has-legend by forward-scanning each fieldset.
+  tagwalk.TAG_RE.lastIndex = 0;
+  var m;
+  while ((m = tagwalk.TAG_RE.exec(html))) {
+    if (m[0].charAt(1) === "/") continue;
+    var tagName = m[1].toLowerCase();
+    var attrs = tagwalk.parseAttrs(m[2]);
+    var pos = tagwalk.lineColAt(html, m.index);
+
+    if (tagName === "fieldset") {
+      // Forward-look for </fieldset>
+      var closeIdx = html.indexOf("</fieldset>", m.index);
+      var inside = closeIdx === -1 ? html.slice(m.index) : html.slice(m.index, closeIdx);
+      if (!/<legend\b/i.test(inside)) {
+        _add({
+          sc: "1.3.1", level: "A", severity: "warning",
+          element: "fieldset", line: pos.line, column: pos.column,
+          message: "<fieldset> has no <legend> (assistive tech can't announce the field-group purpose)",
+          remediation: "Add <legend>Group title</legend> as the first child of <fieldset>",
+        });
+      }
+    }
+
+    if (tagName === "input" && "autocomplete" in attrs) {
+      var v = String(attrs.autocomplete).trim().toLowerCase();
+      // autocomplete supports compound tokens like "section-foo billing tel";
+      // we check the LAST token (the canonical purpose token).
+      var tokens = v.split(/\s+/);
+      var canonical = tokens[tokens.length - 1];
+      if (allowed.indexOf(canonical) === -1) {
+        _add({
+          sc: "1.3.5", level: "AA", severity: "warning",
+          element: "input", line: pos.line, column: pos.column,
+          message: "input autocomplete=\"" + v + "\" canonical token \"" + canonical +
+                   "\" is not in the HTML 5.3 registry",
+          remediation: "Use a registered autocomplete token (https://www.w3.org/TR/html53/sec-forms.html#autofill)",
+        });
+      }
+    }
+
+    if (tagName === "input" && attrs.type === "password" &&
+        "autocomplete" in attrs &&
+        attrs.autocomplete === "off") {
+      _add({
+        sc: "3.3.8", level: "AA", severity: "warning",
+        element: "input", line: pos.line, column: pos.column,
+        message: "password input has autocomplete=\"off\" (blocks password manager — WCAG 3.3.8 requires accessible authentication; password managers count as a recognised authentication aid)",
+        remediation: "Use autocomplete=\"current-password\" or autocomplete=\"new-password\" instead of \"off\"",
+      });
+    }
+
+    // 3.3.7 redundant entry — input type=email/tel/etc. without
+    // autocomplete attribute prevents browsers from offering
+    // saved values, forcing users to re-enter every time.
+    if (tagName === "input" && !("autocomplete" in attrs) &&
+        ["email", "tel", "name"].indexOf(attrs.type) !== -1) {
+      _add({
+        sc: "3.3.7", level: "A", severity: "info",
+        element: "input", line: pos.line, column: pos.column,
+        message: "input type=\"" + attrs.type + "\" has no autocomplete attribute (browsers can't offer saved values; users re-enter)",
+        remediation: "Add autocomplete=\"email\" / \"tel\" / \"name\" / etc.",
+      });
+    }
+
+    if (tagName === "textarea" &&
+        !("aria-label" in attrs) && !("aria-labelledby" in attrs) &&
+        !("title" in attrs) && !("id" in attrs)) {
+      _add({
+        sc: "3.3.2", level: "A", severity: "error",
+        element: "textarea", line: pos.line, column: pos.column,
+        message: "textarea has no associated label (no id, no aria-label, no title)",
+        remediation: "Add id+matching <label for=...> or aria-label=\"<text>\"",
+      });
+    }
+  }
+
+  return findings;
+}
+
+module.exports = {
+  audit:                  audit,
+  AUTOCOMPLETE_TOKENS:    AUTOCOMPLETE_TOKENS,
+};

package/lib/guard-html-wcag-tables.js

@@ -0,0 +1,154 @@
+"use strict";
+/**
+ * Table semantics validation for the WCAG 2.2 audit-only scanner.
+ *
+ * Checks per WCAG 2.2 / WAI-ARIA / HTML 5.3 best practices:
+ *   - <table> without <caption> (data-tables only; layout-tables
+ *     should use role="presentation" instead)
+ *   - <th> without scope attribute (or invalid scope value)
+ *   - layout tables that should be replaced with semantic markup
+ *   - missing or empty <thead> for data tables with multiple body rows
+ *   - <tr> outside <table> / <thead> / <tbody> / <tfoot>
+ *
+ * Exposed under b.guardHtml.wcag.tables.audit(html, opts).
+ */
+
+var validateOpts = require("./validate-opts");
+var tagwalk = require("./guard-html-wcag-tagwalk");
+
+var VALID_SCOPE_VALUES = Object.freeze(["row", "col", "rowgroup", "colgroup"]);
+
+var _TAG_RE = tagwalk.TAG_RE;
+var _parseAttrs = tagwalk.parseAttrs;
+var _lineColAt = tagwalk.lineColAt;
+
+function audit(html, opts) {
+  opts = opts || {};
+  validateOpts(opts, ["scopeUrl"], "guardHtml.wcag.tables.audit");
+  if (typeof html !== "string") {
+    throw new TypeError("tables.audit: html must be a string");
+  }
+
+  var findings = [];
+  function _add(f) { findings.push(f); }
+
+  // Walk the tag stream, tracking nesting state for tables + their
+  // children. We don't build a full DOM; we track the open-tag stack
+  // to determine whether we're inside <table> / <thead> / <tbody>.
+  var stack = [];
+  _TAG_RE.lastIndex = 0;
+  var m;
+  while ((m = _TAG_RE.exec(html))) {
+    var isClose = m[0].charAt(1) === "/";
+    var tagName = m[1].toLowerCase();
+    var attrs = isClose ? null : _parseAttrs(m[2]);
+    var pos = _lineColAt(html, m.index);
+
+    if (isClose) {
+      // Pop the matching open tag (lazily — broken HTML may produce
+      // mismatches; we just pop any matching same-name from the top).
+      for (var s = stack.length - 1; s >= 0; s--) {
+        if (stack[s].name === tagName) {
+          stack.splice(s, 1);
+          break;
+        }
+      }
+      continue;
+    }
+
+    if (tagName === "table") {
+      // Data table check: presence of <caption> as a direct/early
+      // child within the same table. We can't know the close-tag
+      // position without scanning forward; do a forward look.
+      var role = attrs.role || "";
+      var isPresentation = role === "presentation" || role === "none";
+      if (!isPresentation) {
+        // Find the matching </table>
+        var closeIdx = _findClose(html, m.index, "table");
+        var inside = closeIdx === -1 ? html.slice(m.index) : html.slice(m.index, closeIdx);
+        if (!/<caption\b/i.test(inside)) {
+          _add({
+            sc: "1.3.1", level: "A", severity: "warning",
+            element: "table", line: pos.line, column: pos.column,
+            message: "Data <table> has no <caption> (assistive tech can't summarize the table for screen-reader users)",
+            remediation: "Add <caption>Descriptive title</caption> as the first child of <table>, or set role=\"presentation\" if this is a layout table",
+          });
+        }
+      }
+      stack.push({ name: "table", attrs: attrs });
+    }
+
+    if (tagName === "th") {
+      if (!("scope" in attrs)) {
+        _add({
+          sc: "1.3.1", level: "A", severity: "warning",
+          element: "th", line: pos.line, column: pos.column,
+          message: "<th> element has no scope attribute (screen readers can't announce the right header for each cell)",
+          remediation: "Add scope=\"col\" / scope=\"row\" / scope=\"colgroup\" / scope=\"rowgroup\"",
+        });
+      } else if (VALID_SCOPE_VALUES.indexOf(attrs.scope) === -1) {
+        _add({
+          sc: "1.3.1", level: "A", severity: "error",
+          element: "th", line: pos.line, column: pos.column,
+          message: "<th> scope=\"" + attrs.scope + "\" is not in the allowed value set [" +
+                   VALID_SCOPE_VALUES.join(", ") + "]",
+          remediation: "Use a valid scope value",
+        });
+      }
+    }
+
+    if (tagName === "tr") {
+      // Detect <tr> outside any table-context wrapper
+      var inTable = stack.some(function (e) {
+        return e.name === "table" || e.name === "thead" ||
+               e.name === "tbody" || e.name === "tfoot";
+      });
+      if (!inTable) {
+        _add({
+          sc: "1.3.1", level: "A", severity: "warning",
+          element: "tr", line: pos.line, column: pos.column,
+          message: "<tr> appears outside <table> / <thead> / <tbody> / <tfoot>",
+          remediation: "Wrap the <tr> in a table-row context",
+        });
+      }
+    }
+
+    // Track other table descendants so we can identify nested
+    // structure if needed for layout-table heuristics.
+    if (tagName === "thead" || tagName === "tbody" ||
+        tagName === "tfoot" || tagName === "caption") {
+      stack.push({ name: tagName, attrs: attrs });
+    }
+  }
+
+  return findings;
+}
+
+function _findClose(html, startIdx, tagName) {
+  // Forward-scan for the matching close tag, tracking nesting depth
+  // so nested tables of the same name resolve correctly.
+  var openRe = new RegExp("<" + tagName + "\\b", "ig");                            // allow:dynamic-regex — `tagName` is a static string from the framework's WCAG audit (only "table" is passed); `\\b` is a RegExp word boundary
+  var closeRe = new RegExp("</" + tagName + "\\s*>", "ig");                        // allow:dynamic-regex — same as above; static input
+  openRe.lastIndex = startIdx + 1;
+  closeRe.lastIndex = startIdx + 1;
+  var depth = 1;
+  while (depth > 0) {
+    var nextOpen = openRe.exec(html);
+    var nextClose = closeRe.exec(html);
+    if (!nextClose) return -1;
+    if (!nextOpen || nextOpen.index > nextClose.index) {
+      depth -= 1;
+      if (depth === 0) return nextClose.index + nextClose[0].length;
+      openRe.lastIndex = nextClose.index + nextClose[0].length;
+    } else {
+      depth += 1;
+      closeRe.lastIndex = nextOpen.index + nextOpen[0].length;
+    }
+  }
+  return -1;
+}
+
+module.exports = {
+  audit:               audit,
+  VALID_SCOPE_VALUES:  VALID_SCOPE_VALUES,
+};

package/lib/guard-html-wcag-tagwalk.js

@@ -0,0 +1,44 @@
+"use strict";
+/**
+ * Shared tag-walker helpers for the WCAG 2.2 audit-only scanner
+ * modules. Extracted from guard-html-wcag.js / -aria.js / -tables.js
+ * so the regex constants live in one place.
+ */
+
+// HTML5 open + close tag regex. Captures: 1=tag-name, 2=attribute body.
+var TAG_RE = /<\/?([a-zA-Z][a-zA-Z0-9-]*)\b([^>]*)>/g;
+
+// Per-attribute parser: name then (optional) value in double-quoted /
+// single-quoted / unquoted form.
+var ATTR_RE = /([a-zA-Z_:][-a-zA-Z0-9_:.]*)\s*(?:=\s*("([^"]*)"|'([^']*)'|([^\s"'=<>`]+)))?/g;
+
+function parseAttrs(attrString) {
+  var out = Object.create(null);
+  if (!attrString) return out;
+  ATTR_RE.lastIndex = 0;
+  var m;
+  while ((m = ATTR_RE.exec(attrString))) {
+    var name = m[1].toLowerCase();
+    var value = m[3] !== undefined ? m[3] :
+                m[4] !== undefined ? m[4] :
+                m[5] !== undefined ? m[5] : "";
+    out[name] = value;
+  }
+  return out;
+}
+
+function lineColAt(html, offset) {
+  var line = 1;
+  var lastNl = -1;
+  for (var i = 0; i < offset; i++) {
+    if (html.charCodeAt(i) === 10) { line += 1; lastNl = i; }                      // allow:raw-byte-literal — ASCII LF
+  }
+  return { line: line, column: offset - lastNl };
+}
+
+module.exports = {
+  TAG_RE:       TAG_RE,
+  ATTR_RE:      ATTR_RE,
+  parseAttrs:   parseAttrs,
+  lineColAt:    lineColAt,
+};