@shalii/galaxy-a11y 0.0.0-stage → 0.1.4

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 shalii
+
+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

@@ -1,3 +1,283 @@
-# Temporary Holding Version
+# @shalii/galaxy-a11y
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Static **WCAG 2.2 / ADA accessibility scanner for Galaxy CMS themes** (html, scss, js).
+It understands Galaxy syntax (`#$variable|x$#`, `{if="…"}`, `[[id]]`, `__@@text@@__`), so every finding points to the real line in your real file and comes with the exact fix.
+
+> Static scanning finds roughly a third to a half of WCAG problems. See [Limits](#6-limits) and the manual checklist at the end of every report.
+
+---
+
+## 1. Install and run
+
+### In a project (recommended)
+```bash
+cd your-theme                      # folder that contains block/ list/ header/ sass/ src/ package.json
+npm i -D @shalii/galaxy-a11y
+npx galaxy-a11y .
+```
+
+Add a script to the theme's `package.json` so anyone can run it:
+```json
+"scripts": { "a11y": "galaxy-a11y . --html a11y-report.html" }
+```
+```bash
+npm run a11y
+```
+
+### Globally (once per computer)
+```bash
+npm i -g @shalii/galaxy-a11y
+cd any-theme-folder
+galaxy-a11y .
+```
+
+> `npm install` only installs the tool. It does **not** scan anything until you run the command.
+
+### Run from source (without installing from npm)
+```bash
+cd galaxy-a11y                     # this repository
+npm install
+node bin/galaxy-a11y.js "C:\path\to\your-theme" --fail-on none
+```
+Use quotes around paths that contain spaces.
+
+---
+
+## 2. Options
+
+| Option | What it does |
+|---|---|
+| `galaxy-a11y [folder]` | Folder or single file to scan (default: current folder) |
+| `--html <file>` | Filterable HTML report. Use a path that exists, e.g. `a11y-report.html` |
+| `--json [file]` | Machine-readable output (stdout if no file) |
+| `--all` | Also show low-priority notes |
+| `--disable A,B` | Turn rules off, e.g. `--disable SENSORY,ARIA-ROLE` |
+| `--fail-on <level>` | Exit code 1 on `error` (default), `warning`, or `none` |
+| `--limit <n>` | Max findings printed per file |
+| `--no-fix` | Hide fix text |
+| `-h`, `--help` | Help |
+
+Severity levels: **error** (definite failure), **warning** (likely, verify), **manual** (tool cannot decide), **note** (`--all`).
+
+### Silence one finding
+```html
+<!-- a11y-ignore: ALT -->
+<img src="logo.svg" alt="">
+```
+```js
+// a11y-ignore: TRAP
+```
+Put the comment on the line above or the same line. Without a rule name it silences everything on that line.
+
+### Project config
+Create `.galaxy-a11y.json` in the scanned folder:
+```json
+{ "ignoreDirs": ["legacy"], "ignore": ["/vendor/"], "disable": ["SENSORY"] }
+```
+Skipped by default: `node_modules`, `public`, `dist`, `build`, `logs`, `vendors`.
+
+### Use in CI or pre-commit
+```bash
+galaxy-a11y . --fail-on error
+```
+A non-zero exit code blocks the build or commit when errors exist.
+
+---
+
+## 3. What it checks
+
+**48 rules** (46 automatic + 2 manual-only), made up of about **100 individual checks**, each mapped to a WCAG 2.2 success criterion. Every finding shows the rule name, the WCAG number, the line and column, and the fix.
+
+| Area | Rule | What it catches | WCAG |
+|---|---|---|---|
+| **Images and media** | `ALT` | `<img>` with no `alt`, or an `alt` that is only whitespace (suggests the Galaxy variable when the editor controls the alt) | 1.1.1 |
+| | `MAP-AREA` | `<area>` in an image map with no alt text | 1.1.1 / 2.4.4 |
+| | `SVG` | Inline `<svg>` exposed to screen readers without a name (decorative ones should be `aria-hidden`) | 1.1.1 / 4.1.2 |
+| | `MEDIA` | Embedded or `<video>` that autoplays with sound, has no controls, or has no text alternative | 1.4.2 / 2.2.2 |
+| | `AUDIO` | `<audio>` that autoplays | 1.4.2 |
+| | `AUDIO-CAPTIONS` | Embedded video: reminds you to confirm captions / transcript exist | 1.2.2 / 1.2.3 / 1.2.5 |
+| **Motion and timing** | `ANIMATION` | Infinite animations with no `prefers-reduced-motion` override; autoplay video with no pause | 2.2.2 / 2.3.3 |
+| | `FLASH` | Animations repeating faster than 3 times per second | 2.3.1 |
+| | `REFRESH` | Meta refresh and timed redirects | 2.2.1 / 2.2.4 / 3.2.5 |
+| **Page structure** | `HTML_LANG` / `LANG` | Missing or invalid `lang` attribute | 3.1.1 / 3.1.2 |
+| | `TITLE` | Empty or missing `<title>` | 2.4.2 |
+| | `PARSING` | Duplicate `id`s (breaks labels, ARIA and skip links) | 4.1.2 |
+| | `HEADING` | Empty headings, skipped levels (h2 → h4), more than one `<h1>`, and elements styled as headings but not real heading tags | 1.3.1 / 2.4.6 |
+| | `NAV` | No `<main>`, several unlabelled `<nav>` landmarks, links opening a new window without warning | 1.3.1 / 2.4.1 / 3.2.5 |
+| | `SKIP-LINK` | No skip-to-content link in the header, or a skip button with no JS handler | 2.4.1 |
+| | `SEMANTIC` | Interactive elements nested inside each other (`<a>` in `<button>`) | 4.1.2 |
+| **Links and buttons** | `HREF` | `<a>` with no `href` (not keyboard-focusable) | 2.1.1 / 4.1.2 |
+| | `ERR-LINK` | Dead links (`#`, `javascript:`), unclear link text ("click here"), and empty hidden links that screen readers still announce | 2.1.1 / 2.4.4 / 4.1.2 |
+| | `LABEL` | Buttons and inputs with no accessible name, empty `<label>`, `<fieldset>` with no `<legend>`, placeholder-only fields | 1.3.1 / 3.3.2 / 4.1.2 |
+| | `LABEL-IN-NAME` | `aria-label` that does not contain the visible text | 2.5.3 |
+| **Forms** | `INPUT-PURPOSE` | Personal-data fields (name, email, phone…) with no `autocomplete` | 1.3.5 |
+| | `AUTOFILL` | `autocomplete="off"` on personal-data fields | 1.3.5 / 3.3.7 |
+| | `AUTH` | Password fields that block password managers; paste blocked | 3.3.8 |
+| | `REDUNDANT-ENTRY` | "Confirm / repeat" fields that make users re-type information | 3.3.7 |
+| | `ERROR-SUGGESTION` | Error text that only says "required" without telling how to fix it | 3.3.1 / 3.3.3 |
+| | `STATUS-LIVE` | Error / success message containers screen readers will not announce | 4.1.3 |
+| **Keyboard and focus** | `TABINDEX` | Positive `tabindex`; `tabindex="-1"` on visible controls; `tabindex` on non-interactive elements | 2.4.3 |
+| | `KEYBOARD` | Click handlers on `<div>` / `<span>` that a keyboard cannot use | 2.1.1 |
+| | `FOCUS` | Focus outline removed with no replacement | 2.4.7 / 2.4.13 |
+| | `FOCUS-ELEMENT` | Overlays / menus opened without moving focus (`.focus()` never called) | 2.4.3 |
+| | `FOCUS-STRATEGY` | Sticky or fixed headers that can cover the focused element, no `scroll-padding-top` | 2.4.11 |
+| | `TRAP` | Dialogs without `aria-modal`, overlays with no Escape-key handling | 2.1.2 / 2.4.3 |
+| | `SHORTCUT` / `CHAR-KEYS` | `accesskey` and single-character keyboard shortcuts | 2.1.4 |
+| | `MODALITY` | Content shown on hover only, `onmouseover` without a keyboard equivalent | 2.1.1 / 1.4.13 |
+| **Touch and pointer** | `GESTURE` | Swipe / drag actions with no single-tap alternative | 2.5.1 / 2.5.7 |
+| | `PTR-GESTURE` | Actions that fire on press (`mousedown` / `touchstart`) instead of release | 2.5.2 |
+| **ARIA** | `ARIA` | Dialogs with no name, misspelled `aria-*` attributes, `aria-hidden` containers that hold focusable items | 4.1.2 |
+| | `ARIA-ROLE` | Unknown or redundant ARIA roles, and roles missing the attributes they require | 4.1.2 |
+| **Visual design (SCSS)** | `CONTRAST` | Text / background pairs under 4.5:1 (3:1 for large text); suggests the closest passing colour | 1.4.3 / 1.4.11 |
+| | `COLOR` | Links told apart from text by colour only (underline removed) | 1.4.1 |
+| | `SIZE` | Text smaller than 12px | 1.4.4 / 1.4.12 |
+| | `SIZE-2.2` | Click / tap targets smaller than 24×24 px | 2.5.8 / 2.5.5 |
+| | `ZOOM` | Text sized only in `vw`; viewport tag that blocks pinch-zoom | 1.4.4 |
+| | `ORIENTATION` | Content hidden or rotated by orientation media queries | 1.3.4 |
+| **Manual only** | `SENSORY` | Reminder to read content for "click the green button / on the right" instructions | 1.3.3 |
+| | `CONSISTENT-HELP` | Reminder: help / contact link must be in the same place on every page | 3.2.6 |
+
+The last two rules cannot be decided from source code, so they appear as reminders in the manual checklist at the end of every report.
+
+Notes
+- `HREF` = missing or empty href. `ERR-LINK` = dead links and unnamed or generic links.
+- `CONTRAST` only checks colours that appear together in one SCSS rule (literal values or `$variables`). Colours chosen in the CMS cannot be checked statically.
+- Some rules (for example `TRAP` and `FOCUS-ELEMENT`) report as a low-priority **note** when the code appears to use a known library that handles the problem. Use `--all` to see notes.
+
+---
+
+## 4. What to expect
+
+### Output
+This is a real run on two small files (`block/hero.html` and `sass/hero.scss`):
+
+```text
+block/hero.html
+     2:3   error   ALT             <img> has no alt attribute.  WCAG 1.1.1
+                                  fix: Add alt="Describe the image" — or alt="" if purely decorative.
+     3:20  error   KEYBOARD       <div> has a click handler but is not keyboard-operable.  WCAG 2.1.1
+                                  fix: Use <button type="button"> (best). If impossible: role="button" tabindex="0" + Enter/Space key handler.
+     4:6   warning ERR-LINK        Link points to "#" (dead link / script action).  WCAG 2.1.1 / 4.1.2
+                                  fix: If it navigates, use the real URL. If it runs JS, use <button type="button"> ...
+
+sass/hero.scss
+     1:1   error   CONTRAST        Contrast 2.85:1 for ".hero" (#999 on #fff); needs 4.5:1.  WCAG 1.4.3
+                                  fix: Change the text colour to #747474 (closest passing shade), or change the background.
+
+(manual checklist)
+     1:1   manual  KEYBOARD        Tab through every page type once: order, visible focus, no traps ...
+
+Scanned 2 files — 5 errors, 5 warnings, 7 manual checks
+
+By rule:
+  ALT                  1 err     0 warn   0 manual
+  ...
+```
+
+How to read a line: `line:column  severity  RULE  message  WCAG number`, then `fix:` underneath.
+
+### Severity levels
+| Level | Meaning | What to do |
+|---|---|---|
+| **error** | Definite failure of a WCAG criterion | Fix these first |
+| **warning** | Likely a problem, but depends on context | Check each one, fix or silence with `a11y-ignore` |
+| **manual** | The tool cannot decide | Do the check by hand (list at end of report) |
+| **note** | Low priority hint (shown only with `--all`) | Optional |
+
+### Things to know
+- **The first scan on an existing theme often shows many findings.** Many repeat the same cause (for example one SCSS rule used everywhere). Work through the "By rule" table from the top; fixing a shared template or mixin clears many lines at once.
+- **Expect some warnings that do not apply.** The scanner reads source code, so it sometimes cannot tell that a library or the CMS already handles something. Silence those with `a11y-ignore` or `--disable`.
+- **Line numbers point into your real files**, even when the line uses Galaxy syntax (`#$variable|x$#`, `{if="…"}`, `[[id]]`).
+- **Exit code:** `1` if any **error** is found (so CI and pre-commit hooks can block), otherwise `0`. Change with `--fail-on warning` or `--fail-on none`.
+- **`--html a11y-report.html`** writes a report you can filter by errors, warnings and manual checks and share with the team.
+- **Zero findings does not mean "100% accessible".** See [Limits](#6-limits).
+
+---
+
+## 5. What a fix looks like
+
+Every finding comes with the exact change to make. Typical examples:
+
+**Missing alt text** (`ALT`, WCAG 1.1.1)
+```html
+<!-- before -->  <img src="team.jpg">
+<!-- after  -->  <img src="team.jpg" alt="The support team at the 2026 summit">
+<!-- decorative image --> <img src="divider.svg" alt="">
+```
+
+**Clickable `<div>`** (`KEYBOARD`, WCAG 2.1.1)
+```html
+<!-- before -->  <div class="btn" onclick="openMenu()">Menu</div>
+<!-- after  -->  <button type="button" class="btn" onclick="openMenu()">Menu</button>
+```
+
+**Field with placeholder only** (`LABEL`, WCAG 1.3.1 / 3.3.2 / 4.1.2)
+```html
+<!-- before -->  <input type="email" name="email" placeholder="Email">
+<!-- after  -->  <label for="email">Email</label>
+                 <input id="email" type="email" name="email" autocomplete="email">
+```
+(`autocomplete="email"` also fixes `INPUT-PURPOSE`.)
+
+**Dead link used as a button** (`ERR-LINK`, WCAG 2.1.1 / 4.1.2)
+```html
+<!-- before -->  <a href="#" class="toggle">Open</a>
+<!-- after  -->  <button type="button" class="toggle" aria-expanded="false" aria-controls="panel">Open</button>
+                 <div id="panel" hidden>…</div>
+```
+
+**Low contrast** (`CONTRAST`, WCAG 1.4.3). The scanner calculates the closest passing colour:
+```scss
+// before
+.hero { color: #999; background: #fff; }      // 2.85:1, needs 4.5:1
+// after
+.hero { color: #747474; background: #fff; }   // passes
+```
+
+**Removed focus outline** (`FOCUS`, WCAG 2.4.7)
+```scss
+// before
+a:focus { outline: none; }
+// after
+a:focus-visible { outline: 2px solid $focus-color; outline-offset: 2px; }
+```
+
+**Tiny click target** (`SIZE-2.2`, WCAG 2.5.8)
+```scss
+// before
+.btn { width: 18px; height: 18px; }
+// after
+.btn { min-width: 24px; min-height: 24px; }   // ideally 44×44
+```
+
+**Silence a finding that does not apply**
+```html
+<!-- a11y-ignore: ALT -->
+<img src="logo.svg" alt="">
+```
+
+---
+
+## 6. Limits
+
+The scanner reads source code only. It cannot see:
+- colours and content that editors choose in the CMS,
+- the `<html lang>` and `<title>` generated by the Galaxy platform,
+- real focus order, screen-reader output, or caption quality.
+
+For better coverage also:
+1. Scan the rendered pages: `npx @axe-core/cli https://your-site/page --tags wcag2a,wcag2aa,wcag22aa`
+2. Do the manual checklist printed at the end of each report (keyboard pass, screen-reader pass, captions, flashing).
+
+No tool can promise "100% ADA". A realistic goal is: zero automated errors, warnings reviewed, manual checklist signed off.
+
+---
+
+## 7. VS Code extension
+
+Prefer to see the problems while you edit? Install the **Galaxy A11y** extension from the VS Code Marketplace (publisher `shalii`). It runs this same scanner and shows the findings as squiggles, with the fix in the hover. It is a separate project: `galaxy-a11y-vscode`.
+
+---
+
+## License
+MIT

package/bin/galaxy-a11y.js

@@ -0,0 +1,36 @@
+#!/usr/bin/env node
+'use strict';
+const fs = require('fs');
+const { scan, ORDER } = require('../src');
+const report = require('../src/report');
+const a = process.argv.slice(2);
+const flag = (n) => a.includes(n);
+const val = (n) => { const i = a.indexOf(n); return i > -1 ? a[i + 1] : undefined; };
+if (flag('-h') || flag('--help')) {
+  console.log(`galaxy-a11y [folder] [options]
+  --all              also show low-priority notes
+  --json [file]      machine-readable output (stdout if no file)
+  --html <file>      write a filterable HTML report
+  --disable A,B      turn rules off (e.g. --disable SENSORY,ARIA-ROLE)
+  --fail-on <level>  exit 1 on error (default) | warning | none
+  --limit <n>        max findings printed per file
+  --no-fix           hide fix text
+Silence one finding in source:  <!-- a11y-ignore: ALT -->   or   // a11y-ignore   (line above / same line)
+Config: .galaxy-a11y.json  { "ignoreDirs": [], "ignore": ["regex"], "disable": ["RULE"] }`);
+  process.exit(0);
+}
+const target = a.find((x, i) => !x.startsWith('-') && !['--json', '--html', '--disable', '--fail-on', '--limit'].includes(a[i - 1])) || '.';
+const res = scan(target, { disable: (val('--disable') || '').split(',').filter(Boolean) });
+if (flag('--json')) { const j = JSON.stringify(res, null, 2); const f = val('--json'); if (f && !f.startsWith('-')) fs.writeFileSync(f, j); else console.log(j); }
+else console.log(report.text(res, { all: flag('--all'), color: process.stdout.isTTY, fixes: !flag('--no-fix'), limit: +val('--limit') || 0 }));
+if (val('--html')) {
+  const out = require('path').resolve(val('--html'));
+  try {
+    fs.mkdirSync(require('path').dirname(out), { recursive: true });
+    fs.writeFileSync(out, report.html(res));
+    console.error('HTML report: ' + out);
+  } catch (e) { console.error('Could not write the report to ' + out + ' (' + e.code + '). Try a path that exists, e.g. --html a11y-report.html'); }
+}
+const fail = val('--fail-on') || 'error';
+const bad = fail === 'none' ? 0 : res.findings.filter((f) => ORDER[f.severity] <= (fail === 'warning' ? 1 : 0)).length;
+process.exit(bad ? 1 : 0);

package/package.json

@@ -1,6 +1,38 @@
 {
   "name": "@shalii/galaxy-a11y",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.4",
+  "description": "Static WCAG 2.2 / ADA accessibility scanner for Galaxy CMS themes (html, scss, js)",
+  "keywords": [
+    "accessibility",
+    "a11y",
+    "wcag",
+    "ada",
+    "galaxy-cms",
+    "scss",
+    "html-lint"
+  ],
+  "license": "MIT",
+  "type": "commonjs",
+  "main": "src/index.js",
+  "bin": {
+    "galaxy-a11y": "bin/galaxy-a11y.js"
+  },
+  "files": [
+    "bin",
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "scan": "node bin/galaxy-a11y.js ."
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "parse5": "^7.1.2"
+  }
+}

package/src/color.js

@@ -0,0 +1,31 @@
+'use strict';
+const NAMED = { white: '#ffffff', black: '#000000', transparent: null };
+function parse(c) {
+  if (!c) return null;
+  c = String(c).trim().toLowerCase().replace(/\s*!important$/, '');
+  if (c in NAMED) return NAMED[c] ? parse(NAMED[c]) : null;
+  let m = c.match(/^#([0-9a-f]{3})$/);
+  if (m) return m[1].split('').map((h) => parseInt(h + h, 16));
+  m = c.match(/^#([0-9a-f]{6})$/);
+  if (m) return [0, 2, 4].map((i) => parseInt(m[1].substr(i, 2), 16));
+  m = c.match(/^rgba?\(\s*(\d+)[\s,]+(\d+)[\s,]+(\d+)\s*(?:[,/]\s*([\d.]+%?))?\s*\)$/);
+  if (m) {
+    const a = m[4] === undefined ? 1 : m[4].endsWith('%') ? parseFloat(m[4]) / 100 : parseFloat(m[4]);
+    return a < 1 ? null : [+m[1], +m[2], +m[3]]; // semi-transparent: can't judge statically
+  }
+  return null;
+}
+const lin = (v) => { v /= 255; return v <= 0.03928 ? v / 12.92 : Math.pow((v + 0.055) / 1.055, 2.4); };
+const lum = ([r, g, b]) => 0.2126 * lin(r) + 0.7152 * lin(g) + 0.0722 * lin(b);
+function ratio(a, b) { const l1 = lum(a), l2 = lum(b); return (Math.max(l1, l2) + 0.05) / (Math.min(l1, l2) + 0.05); }
+const hex = (rgb) => '#' + rgb.map((v) => Math.round(v).toString(16).padStart(2, '0')).join('');
+// Nudge fg toward black/white (whichever gives more contrast) until it reaches the target ratio.
+function suggest(fg, bg, target) {
+  const towards = lum(bg) > 0.5 ? [0, 0, 0] : [255, 255, 255];
+  for (let t = 0; t <= 1.0001; t += 0.02) {
+    const c = fg.map((v, i) => v + (towards[i] - v) * t);
+    if (ratio(c, bg) >= target) return hex(c);
+  }
+  return hex(towards);
+}
+module.exports = { parse, ratio, suggest, hex };

package/src/css-rules.js

@@ -0,0 +1,88 @@
+'use strict';
+const { parseScss, walk, collectVars, resolveVal } = require('./scss');
+const C = require('./color');
+
+const px = (v) => { const m = /^(-?[\d.]+)px$/.exec((v || '').trim()); return m ? parseFloat(m[1]) : null; };
+const baseOf = (sel) => sel.replace(/:(focus-visible|focus-within|focus)\b/g, '').replace(/\s+/g, ' ').trim();
+const get = (b, ...props) => { for (const p of props) { const d = b.decls.find((x) => x.prop === p); if (d) return d; } return null; };
+const TARGET_RE = /(btn|button|close|toggle|arrow|dot|bullet|pagination|prev|next|checkbox|radio|chevron|burger|hamburger)/i;
+
+function analyzeScss(raw, file, vars, shared) {
+  const out = [];
+  const root = parseScss(raw);
+  const add = (rule, severity, line, message, fix, wcag) => out.push({ file, line, col: 1, rule, severity, message, fix, wcag });
+  const blocks = [];
+  walk(root, (b) => blocks.push(b));
+  const hasReduced = /prefers-reduced-motion/.test(raw);
+  const focusStyled = new Set();
+  blocks.forEach((b) => {
+    if (/:focus(-visible|-within)?\b/.test(b.full) && b.decls.some((d) => /^(box-shadow|border|border-color|outline|outline-color|background|background-color|color|text-decoration|filter)$/.test(d.prop) && !/^(none|0)$/.test(d.value))) focusStyled.add(baseOf(b.full));
+  });
+  shared.focusStyled = shared.focusStyled || new Set(); focusStyled.forEach((x) => shared.focusStyled.add(x));
+  shared.scssBlocks.push({ file, blocks });
+
+  blocks.forEach((b) => {
+    if (!b.full) return;
+    const isFocus = /:focus(-visible)?\b/.test(b.full);
+    // FOCUS: outline removed
+    const ol = get(b, 'outline', 'outline-width');
+    if (ol && /^(none|0|0px)(\s|!|$)/.test(ol.value) && /:not\(\.(tab\w*|keyboard\w*|using-?keyboard\w*|user-is-tabbing|js-focus\w*)\)/i.test(b.full)) {
+      add('FOCUS', 'info', ol.line, `"${b.full}" hides the outline for mouse users and relies on a JS class for keyboard users.`, 'OK while the JS class is always added on Tab and the replacement outline has ≥3:1 contrast. Prefer plain :focus-visible so it works without JS.', 'WCAG 2.4.7');
+    } else if (ol && /^(none|0|0px)(\s|!|$)/.test(ol.value)) {
+      const indicator = (isFocus && b.decls.some((d) => /^(box-shadow|border|border-color|border-bottom|background|background-color|text-decoration|outline-color|outline-style)$/.test(d.prop) && !/^(none|0)$/.test(d.value))) || b.children.some((c) => /:focus/.test(c.full) && c.decls.length);
+      if (isFocus && !indicator) add('FOCUS', 'error', ol.line, `Focus outline removed on "${b.full}" with no replacement style.`, `Replace with a visible indicator, e.g.\n  &:focus-visible { outline: 2px solid $focus-color; outline-offset: 2px; }  // ≥3:1 contrast against neighbours`, 'WCAG 2.4.7 / 2.4.13');
+      else if (!isFocus && !indicator) add('FOCUS', 'warning', ol.line, `outline removed on "${b.full}" (affects :focus too).${shared.focusStyled.has(baseOf(b.full)) ? '' : ' No :focus/:focus-visible style found for it.'}`, `Delete "outline: none" or add:\n  &:focus-visible { outline: 2px solid currentColor; outline-offset: 2px; }`, 'WCAG 2.4.7');
+    }
+    // CONTRAST (same rule, literal or $variable colours)
+    const fgD = get(b, 'color'), bgD = get(b, 'background-color', 'background');
+    if (fgD && bgD) {
+      const fg = C.parse(resolveVal(fgD.value, vars)), bg = C.parse(resolveVal(bgD.value.split(/\s+/)[0] === 'none' ? '' : (bgD.prop === 'background' ? (bgD.value.match(/(#[0-9a-f]{3,6}\b|rgba?\([^)]*\)|\$[\w-]+|\b(?:white|black)\b)/i) || [])[0] || '' : bgD.value), vars));
+      if (fg && bg) {
+        const fs = get(b, 'font-size'), fw = get(b, 'font-weight');
+        const size = fs && px(resolveVal(fs.value, vars)), bold = fw && /^(bold|[6-9]00)/.test(fw.value);
+        const large = size && (size >= 24 || (size >= 18.66 && bold));
+        const need = large ? 3 : 4.5, r = C.ratio(fg, bg);
+        if (r < need) add('CONTRAST', 'error', fgD.line, `Contrast ${r.toFixed(2)}:1 for "${b.full}" (${fgD.value} on ${bgD.value}); needs ${need}:1.`, `Change the text colour to ${C.suggest(fg, bg, need)} (closest passing shade), or change the background.`, 'WCAG 1.4.3');
+      }
+    }
+    // ZOOM / SIZE (text)
+    const fs = get(b, 'font-size');
+    if (fs) {
+      const v = resolveVal(fs.value, vars);
+      if (/^[\d.]+vw$/.test(v.trim())) add('ZOOM', 'error', fs.line, `font-size ${v} scales only with viewport width, so browser zoom/text-size cannot enlarge it.`, 'Use clamp(1rem, 0.9rem + 1vw, 1.5rem) or rem/em.', 'WCAG 1.4.4');
+      const n = px(v);
+      if (n !== null && n < 12 && !/(::?before|::?after)/.test(b.full)) add('SIZE', 'warning', fs.line, `font-size ${v} on "${b.full}" is very small.`, 'Use ≥ 1rem for body copy (≥ 0.75rem only for short labels) and rem units so it scales.', 'WCAG 1.4.4 / 1.4.12');
+    }
+    // SIZE-2.2: target size
+    if (TARGET_RE.test(b.full.split(/[\s>+~]/).pop()) && !/(::?before|::?after|svg|path|img)$/.test(b.full)) {
+      const w = get(b, 'width', 'min-width'), h = get(b, 'height', 'min-height');
+      const wv = w && px(resolveVal(w.value, vars)), hv = h && px(resolveVal(h.value, vars));
+      if (wv !== null && hv !== null && (wv < 24 || hv < 24) && !/(progress|fill|track|scrollbar|divider|line)/i.test(b.full)) add('SIZE-2.2', 'warning', (w || h).line, `Click/tap target "${b.full}" is ${wv ?? '?'}×${hv ?? '?'} px (min 24×24).`, 'Make the hit-area ≥ 24×24 CSS px (ideally 44×44): min-width/min-height, or padding / an ::after hit-area, keep the icon small.', 'WCAG 2.5.8 / 2.5.5');
+    }
+    // ANIMATION / FLASH
+    const an = get(b, 'animation', 'animation-name');
+    if (an && !hasReduced && /infinite/.test(b.decls.map((d) => d.value).join(' ')) ) add('ANIMATION', 'warning', an.line, `Infinite animation on "${b.full}" with no prefers-reduced-motion override in this file.`, '@media (prefers-reduced-motion: reduce) { & { animation: none !important; transition: none !important; } }  — and give a pause control if it runs > 5 s.', 'WCAG 2.2.2 / 2.3.3');
+    const dur = get(b, 'animation-duration') || (an && an.prop === 'animation' ? an : null);
+    if (dur) { const m = dur.value.match(/([\d.]+)(m?s)/); if (m && /infinite/.test(b.decls.map((d) => d.value).join(' ')) && ((m[2] === 's' && parseFloat(m[1]) < 0.34) || (m[2] === 'ms' && parseFloat(m[1]) < 340))) add('FLASH', 'warning', dur.line, `Animation on "${b.full}" repeats faster than 3×/second.`, 'Slow it down (≥ 0.34 s per cycle) or remove it. Never flash large areas > 3×/s.', 'WCAG 2.3.1'); }
+    // MODALITY: hover-only reveal
+    if (/:hover\b/.test(b.full) && !/:(focus|focus-visible|focus-within)\b/.test(b.full)) {
+      const reveal = b.decls.some((d) => (/^(display|visibility)$/.test(d.prop) && /(block|flex|grid|visible)/.test(d.value)) || (d.prop === 'opacity' && !/^0/.test(d.value)) || (/^(max-)?height$/.test(d.prop) && d.value !== '0'));
+      if (reveal && !shared.focusStyled.has(baseOf(b.full)) && !/:focus-within/.test(raw)) add('MODALITY', 'warning', b.line, `Content revealed on :hover only ("${b.full}").`, 'Add the same rule for :focus-visible and :focus-within (e.g. ".menu-item:hover, .menu-item:focus-within { … }"); content must be dismissible (Esc) and hoverable.', 'WCAG 2.1.1 / 1.4.13');
+    }
+    // COLOR (link only distinguished by colour)
+    if (/(^|\s)a$|(^|\s)\.(link|link-text)$/.test(b.full) || /(content|text|body)[\w-]*\s+a$/.test(b.full)) {
+      const td = get(b, 'text-decoration');
+      if (td && /^none/.test(td.value) && !b.decls.some((d) => /^(border-bottom|box-shadow|background-image|text-decoration-line)$/.test(d.prop)) && !b.children.some((c) => /:hover|:focus|::after|::before/.test(c.full) && c.decls.some((d) => /underline|border|background|width/.test(d.prop + d.value)))) add('COLOR', 'warning', td.line, `Links in "${b.full}" lose their underline; if they sit inside body text, colour alone marks them.`, 'Keep text-decoration: underline for inline links (or add a border-bottom / ≥3:1 colour difference + non-colour cue).', 'WCAG 1.4.1');
+    }
+    // ORIENTATION
+    if (/^@media/.test(b.selector) && /orientation\s*:/.test(b.selector)) {
+      const bad = [];
+      walk(b, (c) => c.decls.forEach((d) => { if ((d.prop === 'display' && d.value === 'none') || (d.prop === 'visibility' && d.value === 'hidden') || /rotate\(\s*-?90/.test(d.value)) bad.push(d); }));
+      if (bad.length) add('ORIENTATION', 'warning', b.line, 'An orientation media query hides content or rotates the page.', 'Do not lock/hide content to one orientation. Adapt layout instead.', 'WCAG 1.3.4');
+    }
+  });
+  // fixed header without scroll-padding is reported once per project
+  blocks.forEach((b) => { if (/(header|nav|sticky|fixed)/i.test(b.full) && get(b, 'position') && /^(fixed|sticky)/.test(get(b, 'position').value)) shared.fixedHeaders.push({ file, line: get(b, 'position').line, sel: b.full }); if (get(b, 'scroll-padding-top', 'scroll-padding', 'scroll-margin-top')) shared.hasScrollPadding = true; });
+  return out;
+}
+module.exports = { analyzeScss, collectVars, parseScss };

package/src/galaxy.js

@@ -0,0 +1,27 @@
+'use strict';
+// Turns a Galaxy template into plain HTML WITHOUT changing length, line numbers or columns,
+// so every finding maps back to the exact place in the original file.
+const DYN = '\u2022'; // "•" = value is filled by the CMS at render time
+const blank = (s, ch) => s.replace(/[^\r\n]/g, ch);
+
+function preprocess(src) {
+  return src
+    .replace(/#\$[\s\S]*?\$#/g, (m) => blank(m, DYN))              // #$variable|x$#, #$include|..$#, #$loop..$#
+    .replace(/\{(?:else)?if=[\s\S]*?"\s*\}/g, (m) => blank(m, ' ')) // {if="..."} {elseif="..."}
+    .replace(/\{(?:else|\/if|\/loop|\/for)\}/g, (m) => blank(m, ' '))
+    .replace(/\{\$[^}=]*=[^}]*\}/g, (m) => blank(m, ' '))           // {$x="..."} assignment
+    .replace(/\{\$[^}]*\}/g, (m) => blank(m, DYN))                  // {$x} usage
+    .replace(/\{[a-z_]+\([^}]*\)\}/gi, (m) => blank(m, DYN))        // {format_date(..)}
+    .replace(/\{loop_index\}|\[\[[^\]]+\]\]/g, (m) => blank(m, DYN)) // [[id]] [[hide]]
+    .replace(/__@@|@@__/g, '    ');                                  // translation markers -> keep the text
+}
+
+// How many {if=...} blocks are open at a given offset (used to spot CMS-conditional labels etc.)
+function conditionalDepthAt(raw, offset) {
+  const head = raw.slice(0, offset);
+  const open = (head.match(/\{if=/g) || []).length;
+  const close = (head.match(/\{\/if\}/g) || []).length;
+  return open - close;
+}
+
+module.exports = { preprocess, conditionalDepthAt, DYN };

package/src/html-rules.js

@@ -0,0 +1,309 @@
+'use strict';
+const parse5 = require('parse5');
+const { preprocess, conditionalDepthAt, DYN } = require('./galaxy');
+
+const ROLES = new Set('alert alertdialog application article banner blockquote button caption cell checkbox code columnheader combobox complementary contentinfo definition deletion dialog directory document emphasis feed figure form generic grid gridcell group heading img insertion link list listbox listitem log main marquee math menu menubar menuitem menuitemcheckbox menuitemradio meter navigation none note option paragraph presentation progressbar radio radiogroup region row rowgroup rowheader scrollbar search searchbox separator slider spinbutton status strong subscript superscript switch tab table tablist tabpanel term textbox time timer toolbar tooltip tree treegrid treeitem'.split(' '));
+const ARIA_ATTRS = new Set('activedescendant atomic autocomplete braillelabel brailleroledescription busy checked colcount colindex colindextext colspan controls current describedby description details disabled dropeffect errormessage expanded flowto grabbed haspopup hidden invalid keyshortcuts label labelledby level live modal multiline multiselectable orientation owns placeholder posinset pressed readonly relevant required roledescription rowcount rowindex rowindextext rowspan selected setsize sort valuemax valuemin valuenow valuetext'.split(' '));
+const ROLE_REQUIRES = { checkbox: ['aria-checked'], switch: ['aria-checked'], radio: ['aria-checked'], menuitemcheckbox: ['aria-checked'], menuitemradio: ['aria-checked'], combobox: ['aria-expanded'], heading: ['aria-level'], slider: ['aria-valuenow'], scrollbar: ['aria-valuenow'] };
+const WIDGET_ROLES = new Set('button link tab menuitem menuitemcheckbox menuitemradio option checkbox radio switch slider textbox combobox treeitem searchbox spinbutton'.split(' '));
+const IMPLICIT = { nav: 'navigation', button: 'button', ul: 'list', ol: 'list', li: 'listitem', main: 'main', img: 'img', table: 'table', form: 'form', h1: 'heading', h2: 'heading', h3: 'heading', h4: 'heading', h5: 'heading', h6: 'heading' };
+const NON_INTERACTIVE = new Set('div span li p img i b svg td tr section article ul ol h1 h2 h3 h4 h5 h6 figure em strong label'.split(' '));
+const GENERIC_LINK = /^(click here|here|read more|more|learn more|link|discover|view|view more|details|find out more|see more)$/i;
+const AUTOCOMPLETE = [
+  [/(first|given|fname)/i, 'given-name'], [/(last|family|surname|lname)/i, 'family-name'], [/e-?mail/i, 'email'],
+  [/(phone|mobile|\btel)/i, 'tel'], [/(street|address1|address_1|addressline)/i, 'street-address'], [/(city|town)/i, 'address-level2'],
+  [/(zip|postal|postcode)/i, 'postal-code'], [/country/i, 'country-name'], [/(^|[^a-z])name($|[^a-z])/i, 'name'],
+  [/(organi[sz]ation|company)/i, 'organization'], [/(birth|dob)/i, 'bday'],
+];
+const norm = (s) => String(s || '').toLowerCase().replace(/[^\p{L}\p{N}]+/gu, ' ').trim();
+const isDyn = (s) => typeof s === 'string' && s.includes(DYN);
+
+function analyzeHtml(raw, file, shared) {
+  const out = [];
+  const src = preprocess(raw);
+  const doc = parse5.parseFragment(src, { sourceCodeLocationInfo: true });
+  const ids = new Map(), labelsFor = new Set(), refs = [], inlineScripts = [];
+  const headings = [], radios = new Map();
+
+  const attr = (el, n) => { const a = el.attrs && el.attrs.find((x) => x.name === n); return a ? a.value : undefined; };
+  const has = (el, n) => attr(el, n) !== undefined;
+  const loc = (el, n) => {
+    const l = el.sourceCodeLocation || {};
+    return n && l.attrs && l.attrs[n] ? l.attrs[n] : l;
+  };
+  const rawAttr = (el, n) => { const l = loc(el, n); return l.startOffset !== undefined && n ? raw.slice(l.startOffset, l.endOffset) : ''; };
+  const add = (rule, severity, el, message, fix, wcag, n) => {
+    const l = loc(el, n);
+    out.push({ file, line: l.startLine || 1, col: l.startCol || 1, rule, severity, message, fix: fix || '', wcag: wcag || '' });
+  };
+  const kids = (el) => (el.tagName === 'template' && el.content ? el.content.childNodes : el.childNodes) || [];
+  const hidden = (el) => attr(el, 'aria-hidden') === 'true';
+  const text = (el) => kids(el).map((c) => {
+    if (c.nodeName === '#text') return c.value;
+    if (c.tagName && !['script', 'style'].includes(c.tagName) && !hidden(c)) return text(c);
+    return '';
+  }).join('');
+  const descendants = (el, fn) => kids(el).forEach((c) => { if (c.tagName) { fn(c); descendants(c, fn); } });
+
+  const isFocusable = (el) => {
+    const t = el.tagName, ti = attr(el, 'tabindex');
+    if (has(el, 'disabled') || (ti !== undefined && parseInt(ti, 10) < 0)) return false;
+    if (ti !== undefined && !isNaN(parseInt(ti, 10))) return true;
+    if (t === 'a') return has(el, 'href');
+    if (t === 'input') return attr(el, 'type') !== 'hidden';
+    return ['button', 'select', 'textarea', 'summary'].includes(t) || ((t === 'audio' || t === 'video') && has(el, 'controls'));
+  };
+  // Does the element expose an accessible name? returns 'yes' | 'dynamic' | 'no'
+  const nameOf = (el) => {
+    const al = attr(el, 'aria-label');
+    if (has(el, 'aria-labelledby')) return 'yes';
+    if (al !== undefined && al.replace(new RegExp(DYN, 'g'), '').trim()) return 'yes';
+    if (al !== undefined && isDyn(al)) return 'dynamic';
+    const t = text(el);
+    if (t.replace(new RegExp(DYN, 'g'), '').trim()) return 'yes';
+    let found = 'no';
+    descendants(el, (d) => {
+      if (hidden(d)) return;
+      if (d.tagName === 'img') { const a = attr(d, 'alt'); if (a && a.replace(new RegExp(DYN, 'g'), '').trim()) found = 'yes'; else if (isDyn(a) && found === 'no') found = 'dynamic'; }
+      if (d.tagName === 'svg' && (attr(d, 'aria-label') || kids(d).some((k) => k.tagName === 'title'))) found = 'yes';
+      if (d.tagName === 'title' && d.parentNode && d.parentNode.tagName === 'svg') found = 'yes';
+    });
+    if (found !== 'no') return found;
+    if (isDyn(t)) return 'dynamic';
+    if (attr(el, 'title')) return 'yes';
+    return 'no';
+  };
+
+  const visit = (el, anc) => {
+    const t = el.tagName, role = (attr(el, 'role') || '').trim().toLowerCase();
+    const inAnchor = anc.some((a) => a.tagName === 'a'), inButton = anc.some((a) => a.tagName === 'button');
+    const inHeading = anc.some((a) => /^h[1-6]$/.test(a.tagName) || attr(a, 'role') === 'heading');
+    const id = attr(el, 'id');
+    if (id !== undefined && !isDyn(id) && id.trim()) {
+      if (ids.has(id)) add('PARSING', 'error', el, `Duplicate id "${id}" (first used on line ${ids.get(id)}). Breaks label/aria references and skip links.`, 'Make every id unique, e.g. id="' + id + '-[[id]]" (Galaxy [[id]] gives a unique value per item).', 'WCAG 4.1.2', 'id');
+      else ids.set(id, loc(el).startLine);
+    }
+    for (const r of ['aria-labelledby', 'aria-describedby', 'aria-controls']) {
+      const v = attr(el, r);
+      if (v && !isDyn(v)) v.split(/\s+/).forEach((x) => refs.push({ el, attr: r, id: x }));
+    }
+
+    // ---- lang / viewport / refresh / title -----------------------------------------------------
+    if (t === 'html') {
+      const lg = attr(el, 'lang');
+      if (!lg || !lg.trim()) add('HTML_LANG', 'error', el, '<html> has no lang attribute.', '<html lang="en"> (or the site language; use the Galaxy language variable if the theme is multilingual).', 'WCAG 3.1.1');
+    }
+    if (has(el, 'lang') && t !== 'html') {
+      const lg = attr(el, 'lang');
+      if (lg && !isDyn(lg) && !/^[a-z]{2,3}(-[a-z0-9]{2,8})*$/i.test(lg.trim())) add('LANG', 'error', el, `Invalid lang value "${lg}".`, 'Use a valid BCP-47 code such as "en", "fr", "es-MX".', 'WCAG 3.1.2', 'lang');
+    }
+    if (t === 'meta') {
+      const he = (attr(el, 'http-equiv') || '').toLowerCase(), nm = (attr(el, 'name') || '').toLowerCase(), c = attr(el, 'content') || '';
+      if (he === 'refresh' && /\d/.test(c) && !/^0\b/.test(c.trim())) add('REFRESH', 'error', el, 'Meta refresh auto-redirects/reloads the page.', 'Remove it. Use a server-side 301 redirect, or give users a link/button to continue.', 'WCAG 2.2.1 / 2.2.4 / 3.2.5', 'http-equiv');
+      if (nm === 'viewport' && (/user-scalable\s*=\s*(no|0)/i.test(c) || /maximum-scale\s*=\s*(0?\.\d+|1(\.\d+)?)\b/i.test(c))) add('ZOOM', 'error', el, 'Viewport blocks pinch-zoom (user-scalable=no or maximum-scale below 2).', '<meta name="viewport" content="width=device-width, initial-scale=1">', 'WCAG 1.4.4', 'content');
+    }
+    if (t === 'title' && !text(el).trim()) add('TITLE', 'error', el, '<title> is empty.', 'Give each page a unique, descriptive title: "Page name | Property name".', 'WCAG 2.4.2');
+    if (t === 'iframe') {
+      const ti = attr(el, 'title');
+      if (!(ti && ti.trim()) && !attr(el, 'aria-label') && !hidden(el)) add('TITLE', 'error', el, '<iframe> has no title.', 'Add title="Describe the embedded content", e.g. title="Video: hotel tour" or title="Map of the property".', 'WCAG 4.1.2 / 2.4.1');
+      const s = attr(el, 'src') || attr(el, 'data-src') || '';
+      if (/[?&]autoplay=1/.test(s) && !/[?&](muted=1|background=1|mute=1)/.test(s)) add('MEDIA', 'error', el, 'Embedded video autoplays with sound.', 'Remove autoplay=1, or add muted=1 and provide a visible pause/stop control.', 'WCAG 1.4.2 / 2.2.2', 'src');
+      if (/(youtube|vimeo)/.test(s)) add('AUDIO-CAPTIONS', 'manual', el, 'Embedded video: confirm captions (and a transcript / audio description) exist on the platform.', 'Upload .vtt/.srt captions to YouTube/Vimeo; link a transcript near the player.', 'WCAG 1.2.2 / 1.2.3 / 1.2.5', 'src');
+    }
+
+    // ---- images, svg, maps ---------------------------------------------------------------------
+    if (t === 'img') {
+      const alt = attr(el, 'alt');
+      if (alt === undefined && role !== 'presentation' && role !== 'none') {
+        const v = (rawAttr(el, 'src').match(/#\$variable\|([^|$]+)\$#/) || rawAttr(el, 'data-src').match(/#\$variable\|([^|$]+)\$#/) || [])[1];
+        add('ALT', 'error', el, '<img> has no alt attribute.', v ? `Add alt="#$variable|${v}.alt$#" (editor-controlled alt) — or alt="" if purely decorative.` : 'Add alt="Describe the image" — or alt="" if purely decorative.', 'WCAG 1.1.1');
+      } else if (alt !== undefined && !isDyn(alt)) {
+        if (alt.length && !alt.trim()) add('ALT', 'warning', el, 'alt contains only whitespace.', 'Use alt="" for decorative images or real text.', 'WCAG 1.1.1', 'alt');
+        else if (/\.(jpe?g|png|gif|svg|webp|avif)$/i.test(alt.trim()) || /^(image|photo|picture|img|banner|icon|graphic)$/i.test(alt.trim())) add('ALT', 'warning', el, `alt "${alt}" is a file name / generic word.`, 'Describe what the image conveys (or alt="" if decorative).', 'WCAG 1.1.1', 'alt');
+        else if (alt.length > 150) add('ALT', 'warning', el, 'alt is very long (>150 chars).', 'Keep alt short; put long descriptions in visible text or aria-describedby.', 'WCAG 1.1.1', 'alt');
+      }
+      if (isDyn(alt)) add('ALT', 'info', el, 'alt comes from a CMS field — make sure editors are told to fill it.', 'In the .var/.data field description: "Describe the image for screen-reader users; leave empty only if decorative."', 'WCAG 1.1.1', 'alt');
+    }
+    if (t === 'input' && attr(el, 'type') === 'image' && !attr(el, 'alt')) add('ALT', 'error', el, '<input type="image"> has no alt.', 'alt="Search" (describe the button action).', 'WCAG 1.1.1 / 4.1.2');
+    if (t === 'area') {
+      if (!attr(el, 'alt') && !attr(el, 'aria-label')) add('MAP-AREA', 'error', el, '<area> in an image map has no alt text.', '<area ... alt="Destination name">', 'WCAG 1.1.1 / 2.4.4');
+    }
+    if (t === 'svg' && !hidden(el) && role !== 'presentation' && role !== 'none') {
+      const named = attr(el, 'aria-label') || attr(el, 'aria-labelledby') || kids(el).some((k) => k.tagName === 'title');
+      if (!named) add('SVG', 'warning', el, 'Inline <svg> is exposed to assistive tech without a name.', 'Decorative: <svg aria-hidden="true" focusable="false" …>. Meaningful: <svg role="img" aria-label="…"> or add <title>. Best fix point is the shared partial/icons file.', 'WCAG 1.1.1 / 4.1.2');
+      else if (role !== 'img' && !attr(el, 'aria-label')) add('SVG', 'info', el, 'Named <svg> without role="img".', 'Add role="img" so the name is announced consistently.', 'WCAG 1.1.1');
+    }
+    if ((t === 'object' || t === 'embed') && !attr(el, 'title') && !attr(el, 'aria-label')) add('MEDIA', 'warning', el, `<${t}> has no text alternative.`, 'Add title="…" and provide a text alternative.', 'WCAG 1.1.1');
+
+    // ---- audio / video / animation -------------------------------------------------------------
+    if (t === 'video') {
+      const trackOk = kids(el).some((k) => k.tagName === 'track' && /captions|subtitles/.test(attr(k, 'kind') || ''));
+      if (has(el, 'autoplay') && !has(el, 'muted')) add('MEDIA', 'error', el, 'Video autoplays with sound.', 'Add muted (and playsinline) or remove autoplay.', 'WCAG 1.4.2', 'autoplay');
+      if (has(el, 'autoplay') && !has(el, 'controls')) add('ANIMATION', 'warning', el, 'Auto-playing video has no controls to pause/stop (it runs >5 s).', 'Add controls, or a visible Pause/Play button wired to video.pause()/play(). Honour prefers-reduced-motion.', 'WCAG 2.2.2', 'autoplay');
+      if (!trackOk && !has(el, 'autoplay')) add('AUDIO-CAPTIONS', 'warning', el, '<video> has no captions track.', '<track kind="captions" src="captions.vtt" srclang="en" label="English" default>', 'WCAG 1.2.2');
+      if (!has(el, 'autoplay') && !has(el, 'controls')) add('MEDIA', 'warning', el, '<video> has no controls.', 'Add the controls attribute.', 'WCAG 2.1.1 / 1.4.2');
+    }
+    if (t === 'audio') {
+      if (has(el, 'autoplay')) add('AUDIO', 'error', el, '<audio> autoplays.', 'Remove autoplay; give the user a play control.', 'WCAG 1.4.2', 'autoplay');
+      if (!has(el, 'controls')) add('AUDIO', 'error', el, '<audio> has no controls.', 'Add the controls attribute.', 'WCAG 1.4.2 / 2.1.1');
+      add('AUDIO', 'manual', el, 'Audio-only content needs a transcript.', 'Add a visible "Transcript" link/section next to the player.', 'WCAG 1.2.1');
+    }
+    if (t === 'marquee' || t === 'blink') add('ANIMATION', 'error', el, `<${t}> is obsolete and cannot be paused.`, 'Replace with static text, or a CSS animation that respects prefers-reduced-motion and can be paused.', 'WCAG 2.2.2');
+
+    // ---- links / buttons -----------------------------------------------------------------------
+    if (t === 'a') {
+      const href = attr(el, 'href');
+      if (href === undefined && !role) add('HREF', 'warning', el, '<a> has no href, so it is not keyboard-focusable and not a link.', 'Give it a real href, or use <button type="button"> if it triggers an action.', 'WCAG 2.1.1 / 4.1.2');
+      else if (href !== undefined && /^\s*(#|javascript:)/i.test(href) && href.trim().length <= 1 + 'avascript:void(0)'.length && !isDyn(href) && (href.trim() === '#' || /javascript:/i.test(href))) add('ERR-LINK', 'warning', el, `Link points to "${href.trim()}" (dead link / script action).`, 'If it navigates, use the real URL. If it runs JS (open/close/toggle), use <button type="button"> with aria-expanded/aria-controls where relevant.', 'WCAG 2.1.1 / 4.1.2', 'href');
+      else if (href !== undefined && !href.trim()) add('HREF', 'error', el, 'href is empty.', 'Provide a destination URL (or remove the link).', 'WCAG 2.4.4', 'href');
+      if (href !== undefined) {
+        const n = nameOf(el);
+        if (n === 'no' && !hidden(el) && attr(el, 'tabindex') === '-1' && /sr-only|visually-hidden/.test(attr(el, 'class') || '')) add('ERR-LINK', 'warning', el, 'Empty, visually-hidden link (used as a JS data carrier). Screen-reader users still meet an unnamed link.', 'Add aria-hidden="true", or better, move the data to a data-* attribute / <script type="application/json"> instead of an <a>.', 'WCAG 2.4.4 / 4.1.2');
+        else if (n === 'no' && !hidden(el)) add('ERR-LINK', 'error', el, 'Link has no accessible name (empty or icon-only).', 'Add visible text, or aria-label="Describe destination" on the <a>, or an <img alt>/<svg><title>.', 'WCAG 2.4.4 / 4.1.2');
+        const tx = text(el).trim();
+        if (GENERIC_LINK.test(tx) && !attr(el, 'aria-label') && !has(el, 'aria-labelledby')) add('ERR-LINK', 'warning', el, `Link text "${tx}" is not meaningful out of context.`, `Make it specific, or: aria-label="${tx} – <item title>" (keep the visible words at the start of the label).`, 'WCAG 2.4.4');
+      }
+      if (inButton) add('SEMANTIC', 'error', el, '<a> nested inside <button> (interactive in interactive).', 'Use one element only: either a link or a button.', 'WCAG 4.1.2');
+    }
+    if (t === 'button') {
+      if (nameOf(el) === 'no' && !hidden(el)) add('LABEL', 'error', el, '<button> has no accessible name.', 'Add visible text or aria-label="Close", "Open menu", etc. (wrap translatable text as __@@Close@@__).', 'WCAG 4.1.2');
+      if (inAnchor) add('SEMANTIC', 'error', el, '<button> nested inside <a> (interactive in interactive).', 'Use one element only.', 'WCAG 4.1.2');
+      if (/skip/i.test(attr(el, 'class') || '')) shared.skipButtons.push({ file, line: loc(el).startLine, cls: attr(el, 'class') });
+    }
+    if (t === 'a' && /skip/i.test(attr(el, 'class') || '') ) shared.skipLinks.push({ file, line: loc(el).startLine, href: attr(el, 'href') });
+    if (t === 'a' || t === 'button') {
+      const al = attr(el, 'aria-label');
+      if (al && !isDyn(al)) {
+        const vis = norm(text(el));
+        if (vis && !isDyn(text(el)) && !norm(al).includes(vis)) add('LABEL-IN-NAME', 'warning', el, `aria-label "${al}" does not contain the visible text "${text(el).trim().replace(/\s+/g, ' ')}".`, `Start the label with the visible words, e.g. aria-label="${text(el).trim().replace(/\s+/g, ' ')} – …", or remove aria-label.`, 'WCAG 2.5.3', 'aria-label');
+      }
+    }
+
+    // ---- forms ---------------------------------------------------------------------------------
+    if (t === 'label') { const f = attr(el, 'for'); if (f) labelsFor.add(f); if (!text(el).trim() && !isDyn(text(el)) ) add('LABEL', 'warning', el, '<label> is empty.', 'Put the field name inside the label.', 'WCAG 3.3.2 / 1.3.1'); }
+    if (['input', 'select', 'textarea'].includes(t)) {
+      const ty = (attr(el, 'type') || 'text').toLowerCase();
+      if (!['hidden', 'submit', 'button', 'reset', 'image'].includes(ty)) {
+        const idv = attr(el, 'id');
+        const wrapped = anc.some((a) => a.tagName === 'label');
+        const named = attr(el, 'aria-label') || has(el, 'aria-labelledby') || attr(el, 'title') || wrapped;
+        const lab = idv && (labelsFor.has(idv) || null);
+        shared._pending = shared._pending || [];
+        out.push({ __pendingLabel: true, el, idv, named: !!named, ty, file, line: loc(el).startLine || 1, col: loc(el).startCol || 1 });
+        const nm = (attr(el, 'name') || '') + ' ' + (idv && !isDyn(idv) ? idv : '');
+        const ac = attr(el, 'autocomplete');
+        if (['text', 'email', 'tel', 'url', 'search'].includes(ty) && ac === undefined && ty !== 'search') {
+          const hit = AUTOCOMPLETE.find(([re]) => re.test(nm));
+          const exp = ty === 'email' ? 'email' : ty === 'tel' ? 'tel' : hit && hit[1];
+          if (exp) add('INPUT-PURPOSE', 'error', el, `Field collects personal data (${exp}) but has no autocomplete.`, `Add autocomplete="${exp}".`, 'WCAG 1.3.5');
+        }
+        if (ac === 'off' && AUTOCOMPLETE.some(([re]) => re.test(nm))) add('AUTOFILL', 'warning', el, 'autocomplete="off" on a personal-data field blocks autofill.', 'Remove autocomplete="off" or use the correct token (given-name, email, tel…).', 'WCAG 1.3.5 / 3.3.7', 'autocomplete');
+        if (ty === 'password') {
+          if (ac === undefined || ac === 'off') add('AUTH', 'warning', el, 'Password field blocks/omits password-manager support.', 'autocomplete="current-password" (login) or "new-password" (registration). Allow paste.', 'WCAG 3.3.8');
+        }
+        if (has(el, 'onpaste') || has(el, 'ondrop')) add('AUTH', 'error', el, 'Paste is blocked on a field.', 'Remove the onpaste/ondrop handler so password managers and paste work.', 'WCAG 3.3.8', 'onpaste');
+        if (/(confirm|repeat|retype|re-?enter|verify)/i.test(nm)) add('REDUNDANT-ENTRY', 'manual', el, 'Looks like a "confirm/repeat" field — users must not re-type info already given in the same process.', 'Remove the duplicate field, or offer autofill / a "same as above" option.', 'WCAG 3.3.7');
+        if (ty === 'radio') { const n = attr(el, 'name') || ''; radios.set(n, (radios.get(n) || []).concat([{ el, group: anc.some((a) => a.tagName === 'fieldset' || ['group', 'radiogroup'].includes(attr(a, 'role'))) }])); }
+      }
+    }
+    if (t === 'fieldset' && !kids(el).some((k) => k.tagName === 'legend')) add('LABEL', 'warning', el, '<fieldset> has no <legend>.', 'Add <legend>Group question</legend> as the first child.', 'WCAG 1.3.1 / 3.3.2');
+    const cls = attr(el, 'class') || '';
+    if (/(^|[\s_-])(form-)?(error|success)[-_]?(message|msg)([\s_-]|$)|form-(error|success)\b|\balert\b/.test(cls) && !has(el, 'role') && !has(el, 'aria-live')) add('STATUS-LIVE', 'warning', el, 'Message container is not announced by screen readers when it appears.', 'Errors: role="alert". Success/info: role="status" (or aria-live="polite"). The container must exist in the DOM before text is injected.', 'WCAG 4.1.3');
+    const dem = attr(el, 'data-errormsg');
+    if (dem && !isDyn(dem) && /^(this field is )?required\.?$/i.test(dem.trim())) add('ERROR-SUGGESTION', 'warning', el, `Error text "${dem}" only says the field is required.`, 'Say what to do, per field: "Enter your email, e.g. name@example.com". (3.3.1 identify the field + 3.3.3 suggest a fix.)', 'WCAG 3.3.1 / 3.3.3', 'data-errormsg');
+
+    // ---- headings ------------------------------------------------------------------------------
+    if (/^h[1-6]$/.test(t)) {
+      headings.push({ el, lvl: +t[1] });
+      if (!text(el).replace(new RegExp(DYN, 'g'), '').trim() && !isDyn(text(el)) && nameOf(el) === 'no') add('HEADING', 'error', el, `<${t}> is empty.`, 'Remove the empty heading or give it text.', 'WCAG 1.3.1 / 2.4.6');
+    } else if (['span', 'div', 'p'].includes(t) && !role && !inHeading && /(^|\s)(h[1-6]-title|heading-title-[1-6]|h[1-6])(\s|$)/.test(cls) && text(el).trim()) {
+      const lv = (cls.match(/(?:h|heading-title-)([1-6])/) || [])[1] || '2';
+      add('HEADING', 'warning', el, `<${t}> styled as a heading (class "${cls.trim()}") is not a real heading.`, `Use <h${lv} class="${cls.trim()}"> (keep the classes — only the tag changes), or role="heading" aria-level="${lv}" if the tag cannot change.`, 'WCAG 1.3.1 / 2.4.6');
+    }
+
+    // ---- tabindex / keyboard / aria ------------------------------------------------------------
+    const ti = attr(el, 'tabindex');
+    if (ti !== undefined && !isDyn(ti)) {
+      const n = parseInt(ti, 10);
+      if (n > 0) add('TABINDEX', 'error', el, `tabindex="${ti}" forces a custom tab order.`, 'Use tabindex="0" or none; fix the DOM order instead.', 'WCAG 2.4.3', 'tabindex');
+      else if (n === -1 && ((t === 'a' && has(el, 'href')) || ['button', 'input', 'select', 'textarea'].includes(t)) && !hidden(el) && !anc.some(hidden)) add('TABINDEX', 'warning', el, `tabindex="-1" on a visible ${t}${['checkbox', 'radio'].includes(attr(el, 'type')) ? ' (native checkbox/radio replaced by a custom look)' : ''}: keyboard users cannot reach it.`, ['checkbox', 'radio'].includes(attr(el, 'type')) ? 'Keep the native input focusable: remove tabindex="-1" and hide it visually with the sr-only technique (position:absolute; opacity:0; width/height:1px — NOT display:none), then style the custom box with input:focus-visible + .box. Otherwise the JS replacement must be focusable, role="checkbox", aria-checked, Space-key operable.' : 'Remove tabindex="-1" unless the control is hidden/inactive (then also hide it with aria-hidden/hidden/inert). Toggle it from JS when a menu/slide opens.', 'WCAG 2.1.1 / 2.4.3', 'tabindex');
+      else if (n === 0 && NON_INTERACTIVE.has(t) && !role && !has(el, 'onclick')) add('TABINDEX', 'warning', el, `tabindex="0" on non-interactive <${t}> without a role.`, 'Remove it, or give a role + accessible name + key handling. Scrollable regions: role="region" aria-label="…".', 'WCAG 2.4.3 / 4.1.2', 'tabindex');
+    }
+    if (has(el, 'accesskey')) add('SHORTCUT', 'warning', el, 'accesskey creates a single-key shortcut that can clash with assistive tech.', 'Remove accesskey, or provide a way to turn off/remap it.', 'WCAG 2.1.4', 'accesskey');
+    if (has(el, 'onclick') || has(el, 'ng-click')) {
+      if (NON_INTERACTIVE.has(t) && !isFocusable(el) && !WIDGET_ROLES.has(role)) add('KEYBOARD', 'error', el, `<${t}> has a click handler but is not keyboard-operable.`, 'Use <button type="button"> (best). If impossible: role="button" tabindex="0" + Enter/Space key handler.', 'WCAG 2.1.1', 'onclick');
+    }
+    if (role && !['a', 'button', 'input', 'select', 'textarea', 'summary'].includes(t) && WIDGET_ROLES.has(role) && !has(el, 'tabindex') && !has(el, 'disabled') && !hidden(el) && !['option', 'menuitem', 'menuitemcheckbox', 'menuitemradio', 'treeitem', 'tab'].includes(role)) add('KEYBOARD', 'error', el, `role="${role}" on <${t}> is not focusable.`, `Prefer a native element. Otherwise add tabindex="0" and Enter/Space handling for role="${role}".`, 'WCAG 2.1.1');
+    if (role) {
+      const toks = role.split(/\s+/);
+      if (!toks.some((r) => ROLES.has(r) || /^(doc|graphics)-/.test(r))) add('ARIA-ROLE', 'error', el, `Unknown ARIA role "${role}".`, 'Use a valid WAI-ARIA role (or remove it).', 'WCAG 4.1.2', 'role');
+      else {
+        const r = toks.find((x) => ROLES.has(x));
+        if (IMPLICIT[t] === r && !(t === 'li' && false)) add('ARIA-ROLE', 'info', el, `role="${r}" is redundant on <${t}>.`, 'Remove the role (native semantics already apply).', 'WCAG 4.1.2', 'role');
+        (ROLE_REQUIRES[r] || []).forEach((q) => { if (!has(el, q) && !['input', 'select'].includes(t) && !(r === 'heading' && /^h[1-6]$/.test(t))) add('ARIA-ROLE', 'error', el, `role="${r}" requires ${q}.`, `Add ${q}="…" and keep it in sync from JS.`, 'WCAG 4.1.2', 'role'); });
+        if (r === 'dialog' || r === 'alertdialog') {
+          if (!attr(el, 'aria-label') && !has(el, 'aria-labelledby')) add('ARIA', 'warning', el, 'Dialog has no accessible name.', 'aria-labelledby="<id of the dialog heading>".', 'WCAG 4.1.2');
+          if (attr(el, 'aria-modal') !== 'true') add('TRAP', 'info', el, 'role="dialog" without aria-modal="true".', 'Add aria-modal="true", move focus inside on open, trap Tab, close on Esc, return focus to the opener.', 'WCAG 2.4.3 / 2.1.2');
+        }
+      }
+    }
+    for (const a of el.attrs || []) {
+      if (a.name.startsWith('aria-') && !ARIA_ATTRS.has(a.name.slice(5))) add('ARIA', 'error', el, `"${a.name}" is not a valid ARIA attribute.`, 'Check the spelling against WAI-ARIA 1.2 (e.g. aria-labelledby, aria-expanded).', 'WCAG 4.1.2', a.name);
+    }
+    if (hidden(el) && !has(el, 'hidden') && !has(el, 'inert') && !/display\s*:\s*none/i.test(attr(el, 'style') || '')) {
+      let bad = isFocusable(el);
+      if (!bad) descendants(el, (d) => { if (isFocusable(d)) bad = true; });
+      if (bad) add('ARIA', 'warning', el, 'aria-hidden="true" contains focusable elements. If the container is only hidden by CSS class (not display:none/visibility:hidden/inert) keyboard users can still tab into it.', 'Hide it for everyone while closed (display:none / visibility:hidden / the inert attribute) — or set tabindex="-1" on every focusable child. Toggle aria-hidden, inert and focusability together in JS when it opens.', 'WCAG 4.1.2 / 2.4.3', 'aria-hidden');
+    }
+    if (attr(el, 'aria-label') && !role && ['div', 'span', 'p', 'i', 'b', 'strong', 'em'].includes(t)) add('ARIA', 'warning', el, `aria-label on a generic <${t}> is ignored by many screen readers.`, 'Add a role (e.g. role="group"/"region") or move the text into the element.', 'WCAG 4.1.2', 'aria-label');
+    if (t === 'nav') shared.navs.push({ file, line: loc(el).startLine, col: loc(el).startCol, labeled: !!(attr(el, 'aria-label') || has(el, 'aria-labelledby')) });
+    if (t === 'main') shared.mains.push({ file, id: attr(el, 'id') });
+    if (t === 'table') {
+      let th = false; descendants(el, (d) => { if (d.tagName === 'th') th = true; });
+      if (!th && role !== 'presentation' && role !== 'none') add('SEMANTIC', 'warning', el, '<table> has no <th> header cells.', 'Use <th scope="col|row"> for headers; for layout tables use role="presentation" (better: CSS grid/flex).', 'WCAG 1.3.1');
+    }
+    for (const a of ['onmouseover', 'onmouseenter', 'onmouseout']) if (has(el, a)) add('MODALITY', 'warning', el, `${a} works with a mouse only.`, `Mirror it with onfocus/onblur (and keep content dismissible/hoverable).`, 'WCAG 2.1.1 / 1.4.13', a);
+    if (t === 'script') {
+      const s = kids(el).find((c) => c.nodeName === '#text');
+      if (s && !attr(el, 'src') && !/(json|template)/.test(attr(el, 'type') || '')) inlineScripts.push({ code: raw.slice(s.sourceCodeLocation.startOffset, s.sourceCodeLocation.endOffset), line: s.sourceCodeLocation.startLine });
+    }
+    // sensory text
+    if (!['script', 'style'].includes(t)) kids(el).forEach((c) => {
+      if (c.nodeName === '#text' && /\b(click|press|tap|use)\b[^.]{0,40}\b(red|green|blue|round|square|circular)\b|\b(on the|to the)\s+(left|right)\b|\b(above|below)\s+(button|link|image)\b/i.test(c.value)) {
+        const l = c.sourceCodeLocation || {}; out.push({ file, line: l.startLine || 1, col: l.startCol || 1, rule: 'SENSORY', severity: 'manual', message: 'Instruction relies on colour/shape/position.', fix: 'Also name the control (e.g. “Select the Book now button”).', wcag: 'WCAG 1.3.3 / 1.4.1' });
+      }
+    });
+    kids(el).forEach((c) => c.tagName && visit(c, anc.concat([el])));
+  };
+  kids(doc).forEach((c) => c.tagName && visit(c, []));
+
+  // ---- resolve file-level things -------------------------------------------------------------
+  for (let k = out.length - 1; k >= 0; k--) {
+    const p = out[k];
+    if (!p.__pendingLabel) continue;
+    out.splice(k, 1);
+    const hasLabel = p.named || (p.idv && labelsFor.has(p.idv));
+    if (!hasLabel) {
+      const ph = attr(p.el, 'placeholder');
+      out.push({ file, line: p.line, col: p.col, rule: 'LABEL', severity: ph ? 'warning' : 'error', message: ph ? 'Field relies on placeholder only (disappears while typing; weak accessible name).' : 'Form control has no label.', fix: 'Add <label for="ID">Field name</label> (id must match) or aria-label="Field name".', wcag: 'WCAG 1.3.1 / 3.3.2 / 4.1.2' });
+    } else if (p.idv && labelsFor.has(p.idv) && !p.named) {
+      // label exists – but is it only rendered when a CMS switch is on?
+      const lab = findLabel(doc, p.idv);
+      if (lab && conditionalDepthAt(raw, lab.sourceCodeLocation.startOffset) > 0 && !attr(p.el, 'aria-label')) {
+        out.push({ file, line: p.line, col: p.col, rule: 'LABEL', severity: 'warning', message: 'Visible <label> is wrapped in a CMS {if} (e.g. enable-label). When the editor turns it off the field has no name.', fix: 'Add a fallback: aria-label="{if=\\"…enable-label…\\"}{else}#$variable|label$#{/if}" — or always render the label and hide it visually (.sr-only).', wcag: 'WCAG 3.3.2 / 4.1.2' });
+      }
+    }
+  }
+  function findLabel(node, forId) {
+    let r = null;
+    const w = (n) => { (n.tagName === 'template' && n.content ? n.content.childNodes : n.childNodes || []).forEach((c) => { if (c.tagName === 'label' && attr(c, 'for') === forId) r = r || c; if (c.tagName) w(c); }); };
+    w(node); return r;
+  }
+  refs.forEach((r) => { if (!ids.has(r.id)) add('ARIA', 'warning', r.el, `${r.attr}="${r.id}" points to an id that is not in this file.`, 'Check the id exists in the rendered page (it may live in another block). If not, fix the id or remove the attribute.', 'WCAG 4.1.2', r.attr); });
+  let prev = 0;
+  headings.forEach((h) => { if (prev && h.lvl > prev + 1) add('HEADING', 'warning', h.el, `Heading level jumps from h${prev} to h${h.lvl}.`, `Use h${prev + 1} (style size with CSS classes, not heading level).`, 'WCAG 1.3.1 / 2.4.6'); prev = h.lvl; });
+  if (headings.filter((h) => h.lvl === 1).length > 1) add('HEADING', 'warning', headings.filter((h) => h.lvl === 1)[1].el, 'More than one <h1> in this file.', 'One <h1> per page; use h2 for other sections.', 'WCAG 1.3.1');
+  radios.forEach((arr, name) => { if (arr.length > 1 && !arr.some((r) => r.group)) add('LABEL', 'warning', arr[0].el, `Radio group "${name}" is not wrapped in <fieldset><legend> / role="radiogroup".`, '<fieldset><legend>Question</legend> …radios… </fieldset>', 'WCAG 1.3.1 / 3.3.2'); });
+  return { findings: out, inlineScripts };
+}
+module.exports = { analyzeHtml };

package/src/index.js

@@ -0,0 +1,92 @@
+'use strict';
+const fs = require('fs');
+const path = require('path');
+const { analyzeHtml } = require('./html-rules');
+const { analyzeScss, collectVars, parseScss } = require('./css-rules');
+const { analyzeJs } = require('./js-rules');
+
+const DEFAULT_IGNORE_DIRS = ['node_modules', '.git', 'public', 'dist', 'build', 'logs', 'vendors', 'vendor', 'coverage'];
+const ORDER = { error: 0, warning: 1, manual: 2, info: 3 };
+
+function walkDir(dir, cfg, out = []) {
+  for (const e of fs.readdirSync(dir, { withFileTypes: true })) {
+    const p = path.join(dir, e.name);
+    if (e.isDirectory()) { if (!cfg.ignoreDirs.includes(e.name)) walkDir(p, cfg, out); }
+    else if (/\.(html|scss|js)$/.test(e.name) && !/\.min\.js$/.test(e.name) && !cfg.ignore.some((re) => re.test(p.replace(/\\/g, '/')))) out.push(p);
+  }
+  return out;
+}
+
+function loadConfig(root, opts) {
+  let user = {};
+  const f = path.join(root, '.galaxy-a11y.json');
+  if (fs.existsSync(f)) user = JSON.parse(fs.readFileSync(f, 'utf8'));
+  return {
+    ignoreDirs: DEFAULT_IGNORE_DIRS.concat(user.ignoreDirs || []),
+    ignore: (user.ignore || []).map((s) => new RegExp(s)),
+    disable: new Set([...(user.disable || []), ...(opts.disable || [])].map((s) => s.toUpperCase())),
+  };
+}
+
+function scan(root, opts = {}) {
+  root = path.resolve(root);
+  const cfg = loadConfig(root, opts);
+  const files = fs.statSync(root).isDirectory() ? walkDir(root, cfg) : [root];
+  const base = fs.statSync(root).isDirectory() ? root : path.dirname(root);
+  const rel = (f) => path.relative(base, f).replace(/\\/g, '/');
+  const shared = { navs: [], mains: [], skipButtons: [], skipLinks: [], scssBlocks: [], fixedHeaders: [], focusStyled: new Set(), hasScrollPadding: false };
+  const vars = {};
+  const scssFiles = files.filter((f) => f.endsWith('.scss'));
+  const text = new Map(files.map((f) => [f, fs.readFileSync(f, 'utf8')]));
+  scssFiles.forEach((f) => collectVars(parseScss(text.get(f)), vars));
+  let findings = [], allJs = '';
+  for (const f of files) {
+    const raw = text.get(f), r = rel(f);
+    try {
+      if (f.endsWith('.html')) {
+        const { findings: fs_, inlineScripts } = analyzeHtml(raw, r, shared);
+        findings.push(...fs_);
+        inlineScripts.forEach((s) => { allJs += s.code; findings.push(...analyzeJs(s.code, r, s.line - 1)); });
+      } else if (f.endsWith('.scss')) findings.push(...analyzeScss(raw, r, vars, shared));
+      else { allJs += raw; findings.push(...analyzeJs(raw, r)); }
+    } catch (e) { findings.push({ file: r, line: 1, col: 1, rule: 'SCANNER', severity: 'info', message: 'Could not analyse file: ' + e.message, fix: '', wcag: '' }); }
+  }
+  // ---- project-wide rules ---------------------------------------------------------------------
+  const P = (rule, severity, file, line, message, fix, wcag) => findings.push({ file, line, col: 1, rule, severity, message, fix, wcag });
+  const hasSkipHandler = /(ada-skip|btn-ada-skip|skip-?link|skip-to)/i.test(allJs);
+  const isDir = fs.statSync(root).isDirectory();
+  const hasHeader = files.some((f) => /[\\/]header[\\/][^\\/]+\.html$/.test(f));
+  if (isDir && hasHeader && !shared.skipButtons.length && !shared.skipLinks.length) P('SKIP-LINK', 'error', '(project)', 1, 'No skip-to-content control found in any header template.', 'First focusable element in the header: <a class="skip-link" href="#main">Skip to main content</a>, visible on :focus, and <main id="main" tabindex="-1">.', 'WCAG 2.4.1');
+  shared.skipButtons.forEach((s) => { if (!hasSkipHandler) P('SKIP-LINK', 'error', s.file, s.line, `Skip control <button class="${s.cls}"> has no JS handler anywhere in the scanned code.`, 'Wire it: document.querySelector(".ada-skip").addEventListener("click", () => { const m = document.getElementById("main"); m.setAttribute("tabindex","-1"); m.focus(); });  — or replace it with <a href="#main">.', 'WCAG 2.4.1');
+    else P('SKIP-LINK', 'info', s.file, s.line, 'Skip control is a <button>, not a link. OK if the JS moves focus to <main>; an <a href="#main"> works without JS.', 'Prefer <a class="ada-skip" href="#main">.', 'WCAG 2.4.1'); });
+  shared.skipLinks.forEach((s) => { const id = (s.href || '').replace(/^#/, ''); if (id && !isNaN(1) && s.href.startsWith('#') && !shared.mains.some((m) => m.id === id) && !/\$|\u2022/.test(s.href)) P('SKIP-LINK', 'error', s.file, s.line, `Skip link target "${s.href}" does not exist (<main> has no id="${id}" in scanned templates).`, `Add id="${id}" to <main>.`, 'WCAG 2.4.1'); });
+  const unl = shared.navs.filter((n) => !n.labeled);
+  if (shared.navs.length > 1) unl.forEach((n) => P('NAV', 'warning', n.file, n.line, '<nav> without a label while the site has several <nav> landmarks.', 'aria-label="Main" / "Footer" / "Breadcrumb" (translatable: aria-label="__@@Main navigation@@__").', 'WCAG 1.3.1 / 2.4.1'));
+  if (shared.fixedHeaders.length && !shared.hasScrollPadding) { const h = shared.fixedHeaders[0]; P('FOCUS-STRATEGY', 'warning', h.file, h.line, `Fixed/sticky element "${h.sel}" can cover the focused element, and no scroll-padding-top exists anywhere.`, 'html { scroll-padding-top: <header height>; }  and test Tab through the page: the focused control must stay visible.', 'WCAG 2.4.11 (2.2)'); }
+  const mainFiles = files.filter((f) => /[\\/]page[\\/][^\\/]+\.html$/.test(f));
+  if (mainFiles.length && !shared.mains.length) P('NAV', 'error', '(project)', 1, 'No <main> landmark found in any page template.', '<main id="main" tabindex="-1">…</main>', 'WCAG 1.3.1 / 2.4.1');
+  if (isDir) [
+    ['CONSISTENT-HELP', 'Help/contact link (phone, chat, contact page) must be in the same relative place on every page.', 'WCAG 3.2.6'],
+    ['SENSORY', 'Read content for “click the green button / on the right” style instructions.', 'WCAG 1.3.3'],
+    ['FLASH', 'Review hero videos/animations: nothing may flash more than 3×/second.', 'WCAG 2.3.1'],
+    ['AUDIO-CAPTIONS', 'Check captions/transcripts for every video (incl. YouTube/Vimeo CMS fields).', 'WCAG 1.2.x'],
+    ['CONTRAST', 'CMS-chosen colours (custom-bg-color / custom-text-color fields) cannot be checked statically — test real pages.', 'WCAG 1.4.3 / 1.4.11'],
+    ['HTML_LANG', 'The <html lang> and <title> are generated by the Galaxy platform shell, not by this theme — check the rendered page source.', 'WCAG 3.1.1 / 2.4.2'],
+    ['KEYBOARD', 'Tab through every page type once: order, visible focus, no traps, menus/sliders/forms usable with keys only.', 'WCAG 2.1.1 / 2.4.3 / 2.4.7'],
+  ].forEach(([r, m, w]) => P(r, 'manual', '(manual checklist)', 1, m, '', w));
+  // ---- ignore comments, disabled rules, dedupe ------------------------------------------------
+  const byFile = new Map();
+  files.forEach((f) => byFile.set(rel(f), text.get(f).split('\n')));
+  const seen = new Set();
+  findings = findings.filter((f) => {
+    if (cfgDisabled(cfg, f)) return false;
+    const L = byFile.get(f.file);
+    if (L) for (const ln of [f.line - 2, f.line - 1]) { const m = L[ln] && L[ln].match(/a11y-ignore(?::?\s*([\w,\s_-]+))?/i); if (m && (!m[1] || !m[1].trim() || m[1].toUpperCase().split(/[\s,]+/).includes(f.rule))) return false; }
+    const k = [f.file, f.line, f.col, f.rule, f.message].join('|');
+    if (seen.has(k)) return false; seen.add(k); return true;
+  });
+  findings.sort((a, b) => ORDER[a.severity] - ORDER[b.severity] || a.file.localeCompare(b.file) || a.line - b.line);
+  return { root, filesScanned: files.length, findings };
+}
+const cfgDisabled = (cfg, f) => cfg.disable.has(f.rule);
+module.exports = { scan, ORDER };

package/src/js-rules.js

@@ -0,0 +1,32 @@
+'use strict';
+// Regex-level checks for behaviour that cannot be seen in markup. Comments are blanked first.
+const strip = (s) => s.replace(/\/\*[\s\S]*?\*\//g, (m) => m.replace(/[^\n]/g, ' ')).replace(/(^|[^:'"\\])\/\/[^\n]*/g, (m, p) => p + ' '.repeat(m.length - p.length));
+function analyzeJs(raw, file, lineOffset = 0) {
+  const out = [], code = strip(raw), lines = code.split('\n');
+  const add = (rule, severity, idx, message, fix, wcag) => out.push({ file, line: lineOffset + code.slice(0, idx).split('\n').length, col: 1, rule, severity, message, fix, wcag });
+  const each = (re, fn) => { let m; const r = new RegExp(re.source, re.flags.includes('g') ? re.flags : re.flags + 'g'); while ((m = r.exec(code))) fn(m); };
+  const mentions = (re) => re.test(code);
+  const overlay = /(modal|popup|lightbox|dialog|drawer|offcanvas|fancybox|burger|mobile-?menu)/i;
+  const libHandles = /fancybox/i.test(code); // Fancybox 3 ships Esc + focus handling
+
+  each(/\.(keyCode|which)\b|\bevent\.keyCode\b/, (m) => add('KEYBOARD', 'info', m.index, 'Deprecated keyCode/which used for key handling.', "Use event.key ('Enter', ' ', 'Escape', 'ArrowDown'…).", 'WCAG 2.1.1'));
+  each(/(mouseenter|mouseover|mouseleave|mouseout)\b/, (m) => { if (!/(focusin|focusout|\bfocus\b|\bblur\b)/.test(code)) add('MODALITY', 'warning', m.index, `Hover handler ("${m[1]}") with no matching focus handler in this file.`, "Listen to 'focusin'/'focusout' alongside mouseenter/mouseleave and toggle the same state; make popups dismissible with Esc.", 'WCAG 2.1.1 / 1.4.13'); });
+  each(/['"](touchstart|touchmove|touchend)['"]|\bswipe\b|\bDraggable\b|\bdraggable\s*:\s*true|\ballowTouchMove\s*:\s*true/i, (m) => add('GESTURE', 'warning', m.index, 'Touch/drag/swipe gesture. Make sure the same action works with a single tap/click (prev/next buttons, pagination).', 'Provide visible, focusable buttons (aria-label="Previous slide"/"Next slide") for every swipe/drag action.', 'WCAG 2.5.1 / 2.5.7'));
+  each(/['"](mousedown|touchstart|pointerdown)['"]/, (m) => add('PTR-GESTURE', 'warning', m.index, `Action fires on "${m[1]}" (down-event) — users cannot abort it.`, "Trigger on 'click' / 'pointerup', or allow cancel by moving away before release.", 'WCAG 2.5.2'));
+  each(/(?:key(?:\s*===?\s*|\.toLowerCase\(\)\s*===?\s*)['"][a-z0-9]['"]|keyCode\s*===?\s*(?:6[5-9]|[7-8]\d|90|4[89]|5[0-7]))/i, (m) => { const near = code.slice(Math.max(0, m.index - 200), m.index + 120); if (!/(ctrlKey|altKey|metaKey)/.test(near)) add('CHAR-KEYS', 'error', m.index, 'Single-character keyboard shortcut.', 'Require a modifier (Ctrl/Alt) or let users turn it off/remap it. Do NOT use plain letters/digits.', 'WCAG 2.1.4'); });
+  each(/\b(autoplay\s*:|\.autoplay\b|setInterval\s*\()/, (m) => { if (!/(pauseOnMouseEnter|\.autoplay\.stop|\.pause\(|pause-?button|btn-?pause|stopAutoplay|autoplay\s*:\s*false)/i.test(code)) add('ANIMATION', 'warning', m.index, 'Auto-advancing content with no pause/stop control found in this file.', 'Add a visible Pause/Play button (swiper.autoplay.stop()/start()), stop on focus/hover (pauseOnMouseEnter + focusin), and disable autoplay when matchMedia("(prefers-reduced-motion: reduce)").matches.', 'WCAG 2.2.2'); });
+  each(/\b(location(?:\.href|\.replace|\.assign)?\s*=|window\.location)/, (m) => { const near = code.slice(Math.max(0, m.index - 120), m.index); if (/setTimeout|setInterval/.test(near)) add('REFRESH', 'warning', m.index, 'Timed redirect.', 'Avoid auto-redirects; if required, warn the user and let them extend/stop it.', 'WCAG 2.2.1 / 3.2.5'); });
+  each(/(addEventListener\(\s*['"]paste['"]|\.on\(\s*['"]paste['"]|onpaste)/, (m) => { const near = code.slice(m.index, m.index + 200); if (/preventDefault|return false/.test(near)) add('AUTH', 'error', m.index, 'Paste is blocked.', 'Remove the paste blocker (password managers & assistive tech need paste).', 'WCAG 3.3.8'); });
+  if (overlay.test(file) || (overlay.test(code) && /(\.open|openModal|\.show\(|addClass\(['"][^'"]*(open|active|show|visible)|classList\.(add|toggle)\(['"][^'"]*(open|active|show|visible))/i.test(code))) {
+    const first = code.search(overlay);
+    if (!/\.focus\(/.test(code)) add('FOCUS-ELEMENT', libHandles ? 'info' : 'warning', Math.max(0, first), 'Opens an overlay/menu/dialog but this file never calls .focus().', 'On open: move focus into it (first focusable or the heading with tabindex="-1"). On close: return focus to the trigger element.', 'WCAG 2.4.3 / 3.2.1');
+    if (!/(Escape|['"]Esc['"]|keyCode\s*===?\s*27|which\s*===?\s*27)/.test(code)) add('TRAP', libHandles ? 'info' : 'warning', Math.max(0, first), 'Overlay/menu code has no Escape-key handling.', "document.addEventListener('keydown', e => { if (e.key === 'Escape') close(); }); and trap Tab inside modal dialogs (cycle first↔last focusable).", 'WCAG 2.1.2 / 2.4.3');
+    if (!/(aria-expanded|aria-hidden|aria-modal|inert|\.attr\(\s*['"]aria-|setAttribute\(\s*['"]aria-)/.test(code)) add('ARIA', 'warning', Math.max(0, first), 'Overlay/menu toggles visually but never updates ARIA state.', "Toggle aria-expanded on the trigger and aria-hidden (or inert) on the panel.", 'WCAG 4.1.2');
+  }
+  if (/\.validate\s*\(/.test(code) && !/(aria-live|role\s*[=:]\s*['"]alert|aria-invalid|aria-describedby|errorElement)/.test(code)) { const m = code.search(/\.validate\s*\(/); add('ERROR-SUGGESTION', 'warning', m, 'jQuery-validate form with no accessible error wiring.', "Configure: errorElement:'span', errorClass:'error', highlight/unhighlight to set aria-invalid, errorPlacement to set role=\"alert\" and aria-describedby, invalidHandler to focus the first invalid field.", 'WCAG 3.3.1 / 3.3.3 / 4.1.3'); }
+  each(/window\.open\s*\(/, (m) => add('NAV', 'info', m.index, 'window.open() opens a new window/tab without warning.', 'Warn users (visually and in the accessible name) or use a normal link.', 'WCAG 3.2.5'));
+  each(/\.scrollTo\(|scroll-behavior|behavior\s*:\s*['"]smooth/, (m) => { if (!/prefers-reduced-motion/.test(code)) add('ANIMATION', 'info', m.index, 'Smooth scrolling without a prefers-reduced-motion check.', "const reduce = matchMedia('(prefers-reduced-motion: reduce)').matches; behavior: reduce ? 'auto' : 'smooth'", 'WCAG 2.3.3'); });
+  each(/\.on\(\s*['"]click['"]\s*,\s*['"]?(?:div|span|li|img|\.[\w-]+)['"]?/, () => {});
+  return out;
+}
+module.exports = { analyzeJs };

package/src/report.js

@@ -0,0 +1,39 @@
+'use strict';
+const { ORDER } = require('./index');
+const esc = (s) => String(s).replace(/[&<>"]/g, (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;' }[c]));
+const col = (on) => (code, s) => (on ? `\x1b[${code}m${s}\x1b[0m` : s);
+
+function text(res, { all = false, color = false, fixes = true, limit = 0 } = {}) {
+  const c = col(color), lvl = all ? 3 : 2, list = res.findings.filter((f) => ORDER[f.severity] <= lvl);
+  const sev = { error: (s) => c(31, s), warning: (s) => c(33, s), manual: (s) => c(36, s), info: (s) => c(90, s) };
+  const out = [];
+  const byFile = new Map();
+  list.forEach((f) => { if (!byFile.has(f.file)) byFile.set(f.file, []); byFile.get(f.file).push(f); });
+  for (const [file, fl] of byFile) {
+    out.push('\n' + c(1, file));
+    (limit ? fl.slice(0, limit) : fl).forEach((f) => {
+      out.push(`  ${String(f.line).padStart(4)}:${String(f.col).padEnd(3)} ${sev[f.severity](f.severity.padEnd(7))} ${c(1, f.rule.padEnd(15))} ${f.message}  ${c(90, f.wcag)}`);
+      if (fixes && f.fix) out.push(...f.fix.split('\n').map((l, i) => `${' '.repeat(34)}${i ? '  ' : c(32, 'fix: ')}${l}`));
+    });
+  }
+  out.push('\n' + summary(res, list, c));
+  return out.join('\n');
+}
+function summary(res, list, c = (a, s) => s) {
+  const n = (s) => list.filter((f) => f.severity === s).length;
+  const rules = {};
+  list.forEach((f) => { rules[f.rule] = rules[f.rule] || { error: 0, warning: 0, manual: 0, info: 0 }; rules[f.rule][f.severity]++; });
+  const rows = Object.entries(rules).sort((a, b) => (b[1].error * 1000 + b[1].warning) - (a[1].error * 1000 + a[1].warning)).map(([r, v]) => `  ${r.padEnd(16)} ${String(v.error).padStart(5)} err ${String(v.warning).padStart(5)} warn ${String(v.manual).padStart(3)} manual`);
+  return [c(1, `Scanned ${res.filesScanned} files — ${n('error')} errors, ${n('warning')} warnings, ${n('manual')} manual checks${n('info') ? `, ${n('info')} notes` : ''}`), '', c(1, 'By rule:'), ...rows].join('\n');
+}
+function html(res) {
+  const rows = res.findings.map((f) => `<tr class="${f.severity}"><td>${esc(f.file)}:${f.line}</td><td>${f.severity}</td><td>${esc(f.rule)}</td><td>${esc(f.message)}<br><small>${esc(f.wcag)}</small></td><td><pre>${esc(f.fix)}</pre></td></tr>`).join('\n');
+  return `<!doctype html><html lang="en"><meta charset="utf-8"><title>Galaxy accessibility report</title><meta name="viewport" content="width=device-width,initial-scale=1">
+<style>body{font:14px/1.4 system-ui,sans-serif;margin:24px;color:#111}table{border-collapse:collapse;width:100%}td,th{border:1px solid #ccc;padding:6px;vertical-align:top;text-align:left}pre{margin:0;white-space:pre-wrap;font:12px ui-monospace,monospace}
+tr.error td:nth-child(2){color:#b00020;font-weight:700}tr.warning td:nth-child(2){color:#8a5a00;font-weight:700}tr.manual td:nth-child(2){color:#00606f}tr.info{color:#555}.f button{margin-right:6px;padding:4px 10px}</style>
+<h1>Galaxy accessibility report</h1><p>${res.filesScanned} files scanned · ${res.findings.length} findings</p>
+<p class="f"><button onclick="f('')">All</button><button onclick="f('error')">Errors</button><button onclick="f('warning')">Warnings</button><button onclick="f('manual')">Manual</button><button onclick="f('info')">Notes</button></p>
+<table><thead><tr><th>Where</th><th>Level</th><th>Rule</th><th>Problem</th><th>Exact fix</th></tr></thead><tbody>${rows}</tbody></table>
+<script>function f(s){document.querySelectorAll('tbody tr').forEach(function(r){r.hidden=s&&!r.classList.contains(s)})}</script></html>`;
+}
+module.exports = { text, html, summary };

package/src/scss.js

@@ -0,0 +1,49 @@
+'use strict';
+// Tiny SCSS reader: nested blocks with selector, declarations and line numbers. Not a full compiler.
+function parseScss(src) {
+  const root = { selector: '', full: '', decls: [], children: [], line: 1, parent: null };
+  let cur = root, buf = '', bufLine = 1, line = 1, i = 0, interp = 0;
+  const flushDecl = () => {
+    const t = buf.trim();
+    buf = '';
+    if (!t || t.startsWith('@include') && !t.includes(':') || t.startsWith('@import') || t.startsWith('@use')) return;
+    const m = t.match(/^(\$?[\w-]+)\s*:\s*([\s\S]+)$/);
+    if (m) cur.decls.push({ prop: m[1], value: m[2].trim(), line: bufLine });
+  };
+  const resolve = (parent, sel) => {
+    const first = sel.split(',')[0].trim();
+    if (!parent || sel.startsWith('@')) return sel.startsWith('@') ? sel : first;
+    return first.includes('&') ? first.replace(/&/g, parent) : (parent + ' ' + first).trim();
+  };
+  while (i < src.length) {
+    const ch = src[i], nx = src[i + 1];
+    if (ch === '\n') line++;
+    if (ch === '/' && nx === '/') { while (i < src.length && src[i] !== '\n') i++; continue; }
+    if (ch === '/' && nx === '*') { i += 2; while (i < src.length && !(src[i] === '*' && src[i + 1] === '/')) { if (src[i] === '\n') line++; i++; } i += 2; continue; }
+    if (ch === '"' || ch === "'") { const q = ch; buf += ch; i++; while (i < src.length && src[i] !== q) { buf += src[i]; if (src[i] === '\n') line++; i++; } buf += q; i++; continue; }
+    if (ch === '#' && nx === '{') { interp++; buf += '#{'; i += 2; continue; }
+    if (interp && ch === '}') { interp--; buf += '}'; i++; continue; }
+    if (!buf.trim()) bufLine = line;
+    if (ch === '{') {
+      const sel = buf.trim().replace(/\s+/g, ' ');
+      const full = resolve(cur.full, sel);
+      const blk = { selector: sel, full, decls: [], children: [], line: bufLine, parent: cur };
+      cur.children.push(blk); cur = blk; buf = ''; i++; continue;
+    }
+    if (ch === '}') { flushDecl(); cur = cur.parent || root; i++; continue; }
+    if (ch === ';') { flushDecl(); i++; continue; }
+    buf += ch; i++;
+  }
+  return root;
+}
+function walk(block, fn) { fn(block); block.children.forEach((c) => walk(c, fn)); }
+function collectVars(root, into) {
+  walk(root, (b) => b.decls.forEach((d) => { if (d.prop.startsWith('$')) into[d.prop] = d.value.replace(/\s*!default\s*$/, ''); }));
+}
+function resolveVal(v, vars, depth = 0) {
+  if (!v) return v;
+  v = v.trim();
+  if (v.startsWith('$') && vars[v] && depth < 6) return resolveVal(vars[v], vars, depth + 1);
+  return v;
+}
+module.exports = { parseScss, walk, collectVars, resolveVal };