scorm-kit 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Parth Dhanani
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,109 @@
+# scorm-kit
+
+[![tests](https://github.com/parthdhanani/scorm-kit/actions/workflows/test.yml/badge.svg)](https://github.com/parthdhanani/scorm-kit/actions/workflows/test.yml)
+[![license](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+[![node](https://img.shields.io/badge/node-%E2%89%A518-brightgreen.svg)](https://nodejs.org)
+[![tests](https://img.shields.io/badge/tests-31%2F31-brightgreen.svg)](test/run.js)
+[![runtime deps](https://img.shields.io/badge/runtime%20deps-0-brightgreen.svg)](package.json)
+
+**An opinionated SCORM / cmi5 / xAPI build pipeline for teams that ship.** One CLI, nine subcommands, written because the existing ecosystem stops at "publish from Storyline and pray."
+
+```bash
+npm install -g github:parthdhanani/scorm-kit   # installs from source (not yet on npm)
+
+scorm-kit lint     course.zip    # static analysis: manifest, API, asset refs
+scorm-kit a11y     course.zip    # WCAG 2.2 AA static audit
+scorm-kit diff     before.zip after.zip   # structured diff for PR review
+scorm-kit i18n     course.zip --strings strings.json   # bundle a translation pack
+scorm-kit mock     course.zip    # local LMS for testing without Moodle
+scorm-kit rum      course.zip --endpoint https://rum.example.com/ingest   # inject RUM
+scorm-kit privacy  course.zip    # PII / data-leak static audit
+scorm-kit cmi5     validate|lint|convert ...   # cmi5 validator + SCORM→cmi5 wrapper
+scorm-kit report   course.zip    # one health-gate score: lint + a11y + privacy
+```
+
+Exit codes are conventional: `0` clean, `1` warnings only, `2` errors. Every command supports `--json` for CI pipelines.
+
+## Why this exists
+
+A production SCORM course in 2026 still ships as an opaque zip you upload to an LMS and hope for the best. The packaging tools don't lint. The LMSs don't surface runtime errors. There is no `diff` for PR review. There is no local runtime for testing. Multi-language ships as N separate packages bloating the gradebook. Captions are an afterthought.
+
+`scorm-kit` is the toolbelt I wanted while running the SCORM team at Kidvento (eight people, K-12, ~100 modules a year). Each subcommand was originally written to fix a real production incident or a real workflow gap; the unified CLI is the cleanup pass.
+
+## Commands
+
+### `scorm-kit lint <package>`
+
+Static analysis. Catches the classes of bug that Storyline's own publish step silently misses and that surface as "the LMS is being weird" three weeks later. Rules cover manifest correctness, SCORM API wrapper discovery, `cmi.interactions` collisions, broken asset references, and asset-size warnings.
+
+### `scorm-kit a11y <package>`
+
+WCAG 2.2 AA static audit of every HTML file in the package. Flags missing `lang`, missing `alt`, filename-as-alt, video without `<track>`, audio without transcript, heading-level skips, positive `tabindex`, missing form labels, ARIA misuse. Static-analysis level, not a replacement for a manual audit — but catches 80% of the cheap regressions.
+
+### `scorm-kit diff <before> <after>`
+
+Treats SCORM packages as reviewable artifacts, not binary blobs. Parses `imsmanifest.xml` semantically, hashes the asset list, and emits a unified line diff for text files (HTML/CSS/JS/JSON/XML/VTT). Drop it in CI to gate large unintended changes; use it in PR review to read what actually changed.
+
+### `scorm-kit i18n <package> --strings strings.json`
+
+Bundles a translation pack and a small runtime into a SCORM 1.2 package, turning it into **one package, N languages**, with the learner picking at launch. Authors annotate their HTML with `data-i18n` attributes; the runtime swaps text, media `<source>`s, and `<track>` captions on language change. Choice persists via `cmi.student_preference.language`. No re-publishing per language. No gradebook split.
+
+### `scorm-kit mock <package>`
+
+A local SCORM 1.2 runtime — tiny HTTP server, iframe shell, full `window.API` implementation, every method call recorded with timestamp and last-error code. Use it to develop and debug a SCORM package without uploading to Moodle every cycle. Inject failures (`--fail set`, `--fail init`) to test the course's error handling. Export the session log as JSON for regression tests.
+
+### `scorm-kit rum <package> --endpoint <url>`
+
+Injects a Real User Monitoring runtime. Captures navigation timing, resource-load failures, JS errors, long tasks, and slide transitions; batches and POSTs as JSON beacons. The signal an LMS has never offered. Pair with `cmi.core.student_id` as the actor (or pseudonymise upstream).
+
+> **Note:** The `--token` value is embedded in plaintext inside the output SCORM package (`rum-config.js`). Anyone who unzips the package can read it. Use a scoped, rotatable token — not a master API key.
+
+### `scorm-kit cmi5 <validate|lint|convert> <package>`
+
+cmi5 is the 2016 ADL spec that replaces SCORM 1.2 for new builds — SCORM-style "launch and handshake" with xAPI-based tracking. Most enterprise LMS RFPs in 2026 require cmi5 support.
+
+- `cmi5 validate <pkg>` — structural validation: `cmi5.xml` shape, root `courseStructure` + namespace, `<course>` and `<au>` required attributes, `launchMethod`/`moveOn` enums, `masteryScore` range, IRI shape on ids and `activityType`, AU launch URLs resolve inside the package.
+- `cmi5 lint <pkg>` — validate plus interop checks: unique ids, no duplicate launch URLs, `en` langstring present (LMSs default to en and show blank otherwise), ISO-8601 `duration`, namespaced extension keys, `waivedMoveOnConditions` consistent with `moveOn`.
+- `cmi5 convert <scorm.zip> --out <cmi5.zip>` — wraps a SCORM 1.2 package as cmi5 by generating `cmi5.xml` that references the SCORM SCO's launch HTML as the cmi5 AU. The SCORM API stays in place, so the package degrades gracefully if launched from a SCORM-only LMS. This is the **dual-stream** pattern most teams now use: SCORM for HR completion records, cmi5/xAPI for behavioural data.
+
+### `scorm-kit privacy <package>`
+
+Static PII / data-leak audit. Catches the leaks a procurement-grade compliance review would flag and your courseware vendors won't tell you about: hard-coded emails, phone numbers, SSN/DOB patterns, third-party trackers (GA/GTM/Hotjar/FullStory/Mixpanel/Segment/Amplitude/etc.), font CDNs that set cookies, off-package iframes and form actions, bearer tokens and API keys checked into the bundle, S3 signed URLs, plaintext xAPI `mbox`, learner-id keys used as `localStorage` keys, and the classic `cmi.core.student_name → innerHTML` XSS vector. Allowlist your own LMS/CDN with `--allow lms.example.com,cdn.example.com`. Pair with `lint` and `a11y` in CI for an opinionated three-pass build gate.
+
+### `scorm-kit report <package>`
+
+One pre-upload health gate. Runs `lint`, `a11y`, and `privacy` in one pass, aggregates their findings into a single **Build Health score (0–100)**, and reports how many issues were caught before the package ever reached an LMS — because every one of them is a learner ticket you'd otherwise get two weeks later. Pure composition: it shells out to the three subcommands and adds no analysis of its own. Score model is deliberately simple and explainable — each error costs 10, each warning costs 3, floored at 0. `--json` for CI. Exit `0`/`1`/`2` as usual.
+
+```
+$ scorm-kit report course.zip
+
+  lint    ✗  1 error  5 warnings
+  a11y    ✗  2 errors  0 warnings
+  privacy ✓  0 errors  0 warnings
+
+  Build health: 55/100  (needs work)
+  8 issues caught before upload — each one a learner ticket you won't get in two weeks.
+```
+
+## What scorm-kit is not
+
+- A SCORM authoring tool. For that, see **[Storycraft](../storycraft)** — the Markdown→SCORM compiler that this toolkit was built around.
+- A full WCAG audit. `a11y` is static analysis; manual testing is still required for compliance signoff.
+- A replacement for the LMS. `mock` is for development; production still ships to your real LMS.
+
+## Building from source
+
+```bash
+git clone https://github.com/parthdhanani/scorm-kit
+cd scorm-kit
+npm install        # zero runtime deps; install is just to populate node_modules cache
+npm test           # runs the test suite using fixture zips
+```
+
+## Tests
+
+Each subcommand has 3–5 tests in `test/` that exercise it against the sample SCORM zips in `fixtures/` (built by Storycraft). Run them with `npm test`.
+
+## License
+
+MIT. See `LICENSE`.

package/bin/scorm-kit.js

@@ -0,0 +1,62 @@
+#!/usr/bin/env node
+"use strict";
+
+var path = require("path");
+var { spawnSync } = require("child_process");
+
+var SUBCOMMANDS = {
+  lint:  "../src/lint/lint.js",
+  a11y:  "../src/a11y/a11y.js",
+  diff:  "../src/diff/diff.js",
+  i18n:  "../src/i18n/i18n-cli.js",
+  mock:  "../src/mock/mock.js",
+  rum:   "../src/rum/rum-cli.js",
+  privacy: "../src/privacy/privacy.js",
+  cmi5: "../src/cmi5/cmi5.js",
+  report: "../src/report/report.js",
+};
+
+var HELP = [
+  "scorm-kit — opinionated SCORM 1.2 build pipeline",
+  "",
+  "Usage: scorm-kit <command> [args]",
+  "",
+  "Commands:",
+  "  lint   <package>                static analysis (manifest, API, assets)",
+  "  a11y   <package>                WCAG 2.2 AA static audit",
+  "  diff   <before> <after>         structured diff of two packages",
+  "  i18n   <package> --strings ...  bundle a translation pack + runtime",
+  "  mock   <package> [--port N]     local LMS runtime for testing",
+  "  rum    <package> --endpoint ... inject real-user-monitoring runtime",
+  "  privacy <package>               PII / data-leak static audit",
+  "  cmi5 validate|lint|convert ...  cmi5 package validator + SCORM→cmi5 wrapper",
+  "  report <package>                one health-gate score (lint + a11y + privacy)",
+  "",
+  "Each command exits 0 on success, 1 on warnings, 2 on errors.",
+  "Run `scorm-kit <command> --help` for command-specific options.",
+].join("\n");
+
+function main(argv) {
+  var args = argv.slice(2);
+  if (args.length === 0 || args[0] === "-h" || args[0] === "--help") {
+    console.log(HELP);
+    process.exit(args.length === 0 ? 2 : 0);
+  }
+  if (args[0] === "--version" || args[0] === "-v") {
+    var pkg = require("../package.json");
+    console.log("scorm-kit " + pkg.version);
+    process.exit(0);
+  }
+  var sub = args.shift();
+  var script = SUBCOMMANDS[sub];
+  if (!script) {
+    console.error("scorm-kit: unknown command '" + sub + "'");
+    console.error("Run `scorm-kit --help` for the list of commands.");
+    process.exit(2);
+  }
+  var full = path.resolve(__dirname, script);
+  var res = spawnSync(process.execPath, [full].concat(args), { stdio: "inherit" });
+  process.exit(res.status == null ? 1 : res.status);
+}
+
+main(process.argv);

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "scorm-kit",
+  "version": "0.2.0",
+  "description": "Opinionated SCORM / cmi5 / xAPI build pipeline: lint, a11y, diff, i18n, mock, rum, privacy audit, cmi5 validator + SCORM→cmi5 wrapper.",
+  "bin": {
+    "scorm-kit": "bin/scorm-kit.js"
+  },
+  "scripts": {
+    "test": "node test/run.js",
+    "lint": "eslint ."
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.0.0",
+    "eslint": "^9.0.0",
+    "globals": "^15.0.0"
+  },
+  "keywords": ["scorm", "scorm-1.2", "cmi5", "xapi", "elearning", "lms", "cli", "lint", "wcag", "a11y", "privacy", "learning-engineering"],
+  "license": "MIT",
+  "engines": {
+    "node": ">=18"
+  },
+  "files": [
+    "bin",
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/parthdhanani/scorm-kit"
+  }
+}

package/src/a11y/a11y.js

@@ -0,0 +1,401 @@
+#!/usr/bin/env node
+/*
+ * scorm-a11y — WCAG 2.2 AA static auditor for SCORM 1.2 packages.
+ *
+ *   scorm-a11y path/to/package.zip
+ *   scorm-a11y path/to/unzipped-dir
+ *
+ * Checks every HTML file in the package against the accessibility failure
+ * modes that recur across the catalogues I've audited. Output is grouped
+ * by severity (error / warn / info) and can be emitted as JSON for CI.
+ *
+ * Rules:
+ *
+ *   doc-no-lang             <html> has no lang attribute
+ *   doc-no-title            <title> empty or missing
+ *   doc-empty-title         <title> contains only whitespace
+ *
+ *   img-no-alt              <img> has no alt attribute (decorative needs alt="")
+ *   img-alt-filename        alt looks like a filename ("logo.png", "img_42")
+ *   img-redundant-alt       alt repeats the surrounding link text
+ *
+ *   video-no-track          <video> has no <track kind="captions"> child
+ *   audio-no-transcript     <audio> with no nearby transcript link
+ *
+ *   heading-skip            heading level skipped (h1 → h3)
+ *   heading-no-h1           HTML has headings but no <h1>
+ *
+ *   link-no-text            <a> has no text content and no aria-label / title
+ *   link-generic-text       link text is "click here", "read more", etc.
+ *
+ *   button-no-name          <button> with no text content and no aria-label
+ *
+ *   form-input-no-label     <input>/<select>/<textarea> has no associated label
+ *
+ *   div-click-no-role       <div onclick=...> without role= and tabindex=
+ *   tabindex-positive       tabindex > 0 (breaks natural tab order)
+ *
+ *   iframe-no-title         <iframe> with no title attribute
+ *   table-no-headers        <table> with rows but no <th> or scope=
+ *
+ *   aria-bad-attr           common aria-* typos (aria-labelby, aria-labeled, etc.)
+ *   aria-hidden-focusable   focusable element inside aria-hidden="true"
+ *
+ *   lang-mixed-no-attr      page-level lang attr present but inline foreign
+ *                           text spans have no lang= override (heuristic)
+ *
+ * Exit codes: 0 = clean, 1 = warnings only, 2 = errors.
+ */
+"use strict";
+
+var fs = require("fs");
+var path = require("path");
+var os = require("os");
+var { spawnSync } = require("child_process");
+var verifyConfinement = require("../confine");
+
+// ---------- rules table ----------------------------------------------------
+
+var RULES = {
+  "doc-no-lang":          { sev: "error", msg: "<html> missing lang attribute" },
+  "doc-no-title":         { sev: "error", msg: "no <title> element" },
+  "doc-empty-title":      { sev: "error", msg: "<title> is empty" },
+  "img-no-alt":           { sev: "error", msg: "<img> missing alt attribute (use alt=\"\" for decorative)" },
+  "img-alt-filename":     { sev: "warn",  msg: "<img> alt looks like a filename" },
+  "img-redundant-alt":    { sev: "warn",  msg: "<img> alt repeats surrounding link text" },
+  "video-no-track":       { sev: "error", msg: "<video> has no <track kind=\"captions\">" },
+  "audio-no-transcript":  { sev: "warn",  msg: "<audio> with no nearby transcript link" },
+  "heading-skip":         { sev: "warn",  msg: "heading level skipped" },
+  "heading-no-h1":        { sev: "warn",  msg: "HTML has headings but no <h1>" },
+  "link-no-text":         { sev: "error", msg: "<a> has no accessible name" },
+  "link-generic-text":    { sev: "warn",  msg: "link text is generic (\"click here\" / \"read more\")" },
+  "button-no-name":       { sev: "error", msg: "<button> has no accessible name" },
+  "form-input-no-label":  { sev: "error", msg: "form control has no associated label" },
+  "div-click-no-role":    { sev: "error", msg: "<div onclick=...> without role/tabindex (not keyboard accessible)" },
+  "tabindex-positive":    { sev: "warn",  msg: "tabindex > 0 breaks natural tab order" },
+  "iframe-no-title":      { sev: "error", msg: "<iframe> missing title attribute" },
+  "table-no-headers":     { sev: "warn",  msg: "<table> has rows but no <th> or scope=" },
+  "aria-bad-attr":        { sev: "error", msg: "invalid aria-* attribute name (likely typo)" },
+  "aria-hidden-focusable":{ sev: "error", msg: "focusable element inside aria-hidden=\"true\"" },
+};
+
+// Common aria-* misspellings I've actually seen in audits.
+var VALID_ARIA = new Set([
+  "aria-label", "aria-labelledby", "aria-describedby", "aria-hidden",
+  "aria-live", "aria-atomic", "aria-relevant", "aria-busy",
+  "aria-controls", "aria-owns", "aria-flowto", "aria-activedescendant",
+  "aria-expanded", "aria-pressed", "aria-checked", "aria-selected",
+  "aria-disabled", "aria-readonly", "aria-required", "aria-invalid",
+  "aria-haspopup", "aria-current", "aria-modal", "aria-multiline",
+  "aria-multiselectable", "aria-orientation", "aria-sort", "aria-level",
+  "aria-posinset", "aria-setsize", "aria-valuemin", "aria-valuemax",
+  "aria-valuenow", "aria-valuetext", "aria-autocomplete", "aria-placeholder",
+  "aria-roledescription", "aria-keyshortcuts", "aria-details", "aria-errormessage",
+  "aria-colcount", "aria-colindex", "aria-colspan",
+  "aria-rowcount", "aria-rowindex", "aria-rowspan",
+  "aria-dropeffect", "aria-grabbed",
+]);
+
+var GENERIC_LINK_TEXT = new Set([
+  "click here", "click", "here", "read more", "more", "learn more",
+  "details", "link", "this", "this link", "more info", "info",
+]);
+
+// ---------- args -----------------------------------------------------------
+
+function parseArgs(argv) {
+  var a = { input: "", json: false, noColor: false, infoOff: false };
+  for (var i = 0; i < argv.length; i++) {
+    var k = argv[i];
+    if (k === "--json") a.json = true;
+    else if (k === "--no-color") a.noColor = true;
+    else if (k === "--no-info") a.infoOff = true;
+    else if (k === "-h" || k === "--help") { usage(); process.exit(0); }
+    else if (k[0] === "-") { console.error("Unknown flag: " + k); process.exit(2); }
+    else if (!a.input) a.input = k;
+    else { console.error("Unexpected arg: " + k); process.exit(2); }
+  }
+  if (!a.input) { usage(); process.exit(2); }
+  return a;
+}
+function usage() {
+  console.error("Usage: scorm-a11y <package.zip | dir> [--json] [--no-info] [--no-color]");
+}
+
+// ---------- zip ------------------------------------------------------------
+
+function unzipToTemp(zipPath) {
+  var tmp = fs.mkdtempSync(path.join(os.tmpdir(), "scorm-a11y-"));
+  var r = spawnSync("unzip", ["-q", "-o", zipPath, "-d", tmp]);
+  if (r.status !== 0) throw new Error("unzip: " + r.stderr.toString());
+  verifyConfinement(tmp);
+  return tmp;
+}
+
+// ---------- walk -----------------------------------------------------------
+
+function walk(dir, acc) {
+  acc = acc || [];
+  for (var name of fs.readdirSync(dir)) {
+    var p = path.join(dir, name);
+    var st = fs.statSync(p);
+    if (st.isDirectory()) walk(p, acc);
+    else acc.push(p);
+  }
+  return acc;
+}
+
+// ---------- finding type ---------------------------------------------------
+
+function find(rule, file, line, detail) {
+  return { rule: rule, sev: RULES[rule].sev, msg: RULES[rule].msg, file: file, line: line, detail: detail || "" };
+}
+
+function lineOf(html, idx) {
+  var n = 1;
+  for (var i = 0; i < idx && i < html.length; i++) if (html[i] === "\n") n++;
+  return n;
+}
+
+// ---------- attribute parsing ---------------------------------------------
+
+function getAttr(tagStr, name) {
+  var re = new RegExp("\\b" + name + '\\s*=\\s*(["\'])([^"\']*)\\1', "i");
+  var m = re.exec(tagStr);
+  return m ? m[2] : null;
+}
+function hasAttr(tagStr, name) {
+  return new RegExp("\\b" + name + "(\\s|=|>|/)", "i").test(tagStr);
+}
+// ---------- audit one HTML --------------------------------------------------
+
+function auditHtml(file, html) {
+  var findings = [];
+  var rel = file;
+
+  // doc-no-lang
+  var htmlTag = /<html\b[^>]*>/i.exec(html);
+  if (htmlTag && !getAttr(htmlTag[0], "lang")) {
+    findings.push(find("doc-no-lang", rel, lineOf(html, htmlTag.index)));
+  }
+
+  // title — search inside <head> so we don't pick up <svg><title> by accident
+  var headM = /<head\b[^>]*>([\s\S]*?)<\/head>/i.exec(html);
+  var headSlice = headM ? headM[1] : html;
+  var headStart = headM ? headM.index : 0;
+  var titleM = /<title\b[^>]*>([\s\S]*?)<\/title>/i.exec(headSlice);
+  if (!titleM) {
+    findings.push(find("doc-no-title", rel, 1));
+  } else if (!titleM[1].trim()) {
+    findings.push(find("doc-empty-title", rel, lineOf(html, headStart + titleM.index)));
+  }
+
+  // images
+  var imgRe = /<img\b([^>]*)>/gi, m;
+  while ((m = imgRe.exec(html)) !== null) {
+    var attrs = m[1];
+    if (!hasAttr(attrs, "alt")) {
+      findings.push(find("img-no-alt", rel, lineOf(html, m.index), m[0].slice(0, 80)));
+    } else {
+      var alt = getAttr(attrs, "alt") || "";
+      if (alt && /\.(png|jpg|jpeg|gif|svg|webp|bmp)$/i.test(alt.trim())) {
+        findings.push(find("img-alt-filename", rel, lineOf(html, m.index), "alt=\"" + alt + "\""));
+      }
+      if (alt && /^(img|image|picture|photo)[_\s-]?\d+$/i.test(alt.trim())) {
+        findings.push(find("img-alt-filename", rel, lineOf(html, m.index), "alt=\"" + alt + "\""));
+      }
+    }
+  }
+
+  // video without <track kind="captions">
+  var videoRe = /<video\b([^>]*)>([\s\S]*?)<\/video>/gi;
+  while ((m = videoRe.exec(html)) !== null) {
+    var inner = m[2];
+    if (!/<track\b[^>]*\bkind\s*=\s*["']captions["']/i.test(inner)) {
+      findings.push(find("video-no-track", rel, lineOf(html, m.index)));
+    }
+  }
+
+  // audio without transcript link nearby (heuristic: look for "transcript" in next 500 chars)
+  var audioRe = /<audio\b[^>]*>[\s\S]*?<\/audio>/gi;
+  while ((m = audioRe.exec(html)) !== null) {
+    var after = html.slice(m.index, m.index + 500 + m[0].length);
+    if (!/transcript/i.test(after)) {
+      findings.push(find("audio-no-transcript", rel, lineOf(html, m.index)));
+    }
+  }
+
+  // headings
+  var headRe = /<h([1-6])\b[^>]*>/gi;
+  var levels = [];
+  while ((m = headRe.exec(html)) !== null) levels.push({ lvl: +m[1], pos: m.index });
+  if (levels.length > 0) {
+    if (!levels.some(function (l) { return l.lvl === 1; })) {
+      findings.push(find("heading-no-h1", rel, lineOf(html, levels[0].pos)));
+    }
+    for (var i = 1; i < levels.length; i++) {
+      var d = levels[i].lvl - levels[i - 1].lvl;
+      if (d > 1) {
+        findings.push(find("heading-skip", rel, lineOf(html, levels[i].pos),
+          "h" + levels[i - 1].lvl + " → h" + levels[i].lvl));
+      }
+    }
+  }
+
+  // links
+  var linkRe = /<a\b([^>]*)>([\s\S]*?)<\/a>/gi;
+  while ((m = linkRe.exec(html)) !== null) {
+    var aAttrs = m[1], aText = m[2].replace(/<[^>]+>/g, "").trim();
+    var aria = getAttr(aAttrs, "aria-label");
+    var title = getAttr(aAttrs, "title");
+    var hasName = aText || aria || title;
+    if (!hasName) {
+      var imgInside = /<img\b[^>]*\balt\s*=\s*["']([^"']+)["']/i.exec(m[2]);
+      if (!imgInside || !imgInside[1].trim()) {
+        findings.push(find("link-no-text", rel, lineOf(html, m.index)));
+      }
+    } else {
+      if (aText && GENERIC_LINK_TEXT.has(aText.toLowerCase())) {
+        findings.push(find("link-generic-text", rel, lineOf(html, m.index), "\"" + aText + "\""));
+      }
+      // Redundant: img alt inside the link matches the link's surrounding text.
+      var imgInside2 = /<img\b[^>]*\balt\s*=\s*["']([^"']+)["']/i.exec(m[2]);
+      if (imgInside2 && aText && imgInside2[1].trim().toLowerCase() === aText.toLowerCase()) {
+        findings.push(find("img-redundant-alt", rel, lineOf(html, m.index),
+                           "alt=\"" + imgInside2[1] + "\" duplicates link text"));
+      }
+    }
+  }
+
+  // buttons
+  var btnRe = /<button\b([^>]*)>([\s\S]*?)<\/button>/gi;
+  while ((m = btnRe.exec(html)) !== null) {
+    var bAttrs = m[1], bText = m[2].replace(/<[^>]+>/g, "").trim();
+    if (!bText && !getAttr(bAttrs, "aria-label") && !getAttr(bAttrs, "title")) {
+      findings.push(find("button-no-name", rel, lineOf(html, m.index)));
+    }
+  }
+
+  // form inputs missing labels
+  var inputRe = /<(input|select|textarea)\b([^>]*)>/gi;
+  while ((m = inputRe.exec(html)) !== null) {
+    var iType = (getAttr(m[2], "type") || "").toLowerCase();
+    if (m[1].toLowerCase() === "input" && ["hidden", "submit", "button", "reset", "image"].indexOf(iType) >= 0) continue;
+    var id = getAttr(m[2], "id");
+    var aria2 = getAttr(m[2], "aria-label") || getAttr(m[2], "aria-labelledby");
+    var hasLabel = aria2;
+    if (!hasLabel && id) {
+      var labelRe = new RegExp('<label\\b[^>]*\\bfor\\s*=\\s*["\']' + id.replace(/[-/\\^$*+?.()|[\]{}]/g, "\\$&") + '["\']', "i");
+      if (labelRe.test(html)) hasLabel = true;
+    }
+    if (!hasLabel) {
+      findings.push(find("form-input-no-label", rel, lineOf(html, m.index), "<" + m[1] + ">"));
+    }
+  }
+
+  // div with onclick but no role/tabindex
+  var divClickRe = /<div\b([^>]*\bonclick\b[^>]*)>/gi;
+  while ((m = divClickRe.exec(html)) !== null) {
+    if (!getAttr(m[1], "role") || !hasAttr(m[1], "tabindex")) {
+      findings.push(find("div-click-no-role", rel, lineOf(html, m.index)));
+    }
+  }
+
+  // tabindex > 0
+  var tabRe = /\btabindex\s*=\s*["'](\d+)["']/gi;
+  while ((m = tabRe.exec(html)) !== null) {
+    if (+m[1] > 0) findings.push(find("tabindex-positive", rel, lineOf(html, m.index), "tabindex=\"" + m[1] + "\""));
+  }
+
+  // iframes
+  var iframeRe = /<iframe\b([^>]*)>/gi;
+  while ((m = iframeRe.exec(html)) !== null) {
+    if (!getAttr(m[1], "title")) findings.push(find("iframe-no-title", rel, lineOf(html, m.index)));
+  }
+
+  // tables with rows but no <th>/scope
+  var tableRe = /<table\b[^>]*>([\s\S]*?)<\/table>/gi;
+  while ((m = tableRe.exec(html)) !== null) {
+    var tBody = m[1];
+    if (/<tr\b/i.test(tBody) && !/<th\b/i.test(tBody) && !/scope\s*=/i.test(tBody)) {
+      findings.push(find("table-no-headers", rel, lineOf(html, m.index)));
+    }
+  }
+
+  // aria-* typos
+  var ariaRe = /\b(aria-[a-zA-Z]+)\s*=/g;
+  while ((m = ariaRe.exec(html)) !== null) {
+    var attr = m[1].toLowerCase();
+    if (!VALID_ARIA.has(attr)) {
+      findings.push(find("aria-bad-attr", rel, lineOf(html, m.index), attr));
+    }
+  }
+
+  // aria-hidden=true wrapping focusable elements
+  var hiddenRe = /<([a-z]+)\b[^>]*\baria-hidden\s*=\s*["']true["'][^>]*>([\s\S]*?)<\/\1>/gi;
+  while ((m = hiddenRe.exec(html)) !== null) {
+    if (/<(a|button|input|select|textarea|iframe)\b/i.test(m[2]) || /\btabindex\s*=\s*["']0["']/i.test(m[2])) {
+      findings.push(find("aria-hidden-focusable", rel, lineOf(html, m.index)));
+    }
+  }
+
+  return findings;
+}
+
+// ---------- main -----------------------------------------------------------
+
+function color(s, code, on) { return on ? "\x1b[" + code + "m" + s + "\x1b[0m" : s; }
+
+function main() {
+  var args = parseArgs(process.argv.slice(2));
+  if (!fs.existsSync(args.input)) { console.error("Not found: " + args.input); process.exit(2); }
+
+  var inputIsZip = fs.statSync(args.input).isFile();
+  var root, cleanup = function () {};
+  if (inputIsZip) {
+    root = unzipToTemp(args.input);
+    cleanup = function () { try { fs.rmSync(root, { recursive: true, force: true }); } catch (e) {} };
+  } else {
+    root = path.resolve(args.input);
+  }
+
+  try {
+    var htmls = walk(root).filter(function (p) { return /\.html?$/i.test(p); });
+    var all = [];
+    for (var f of htmls) {
+      var html = fs.readFileSync(f, "utf8");
+      var rel = path.relative(root, f);
+      var fs2 = auditHtml(rel, html);
+      all = all.concat(fs2);
+    }
+
+    if (args.infoOff) all = all.filter(function (x) { return x.sev !== "info"; });
+
+    if (args.json) {
+      console.log(JSON.stringify({ findings: all }, null, 2));
+    } else {
+      var byFile = {};
+      for (var f2 of all) { (byFile[f2.file] = byFile[f2.file] || []).push(f2); }
+      var useColor = !args.noColor && process.stdout.isTTY;
+      var sevColor = { error: 31, warn: 33, info: 36 };
+      for (var file of Object.keys(byFile).sort()) {
+        console.log("\n" + color(file, 1, useColor));
+        for (var item of byFile[file]) {
+          var sev = color(item.sev.toUpperCase().padEnd(5), sevColor[item.sev] || 0, useColor);
+          console.log("  " + sev + " L" + String(item.line).padEnd(4) + " " + item.rule.padEnd(22) + " " + item.msg + (item.detail ? "  — " + item.detail : ""));
+        }
+      }
+      var errs = all.filter(function (x) { return x.sev === "error"; }).length;
+      var warns = all.filter(function (x) { return x.sev === "warn"; }).length;
+      console.log("\n" + errs + " error(s), " + warns + " warning(s) across " + htmls.length + " HTML file(s).");
+    }
+
+    var anyErr = all.some(function (x) { return x.sev === "error"; });
+    var anyWarn = all.some(function (x) { return x.sev === "warn"; });
+    process.exit(anyErr ? 2 : anyWarn ? 1 : 0);
+  } finally {
+    cleanup();
+  }
+}
+
+main();