a11yhat 0.1.0__tar.gz

a11yhat-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Vincent Gonzalez / F-Keys Creative LLC
+
+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.

a11yhat-0.1.0/PKG-INFO

@@ -0,0 +1,68 @@
+Metadata-Version: 2.4
+Name: a11yhat
+Version: 0.1.0
+Summary: a11yhat: a WCAG 2.2 accessibility machine, structured by POUR — four crew leads, every success criterion a recorded check. A hardHats crew.
+Author: Vincent Gonzalez
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/vince-gonzalez/a11yhat
+Project-URL: Repository, https://github.com/vince-gonzalez/a11yhat
+Keywords: accessibility,wcag,a11y,section508,audit,pour
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Quality Assurance
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# a11yhat
+
+An open-source **WCAG 2.2 accessibility machine**, structured the way the work is
+organized — by the four principles, **Perceivable · Operable · Understandable ·
+Robust (POUR)**. One crew in the **hardHats** family (hardHats is the framework;
+a11yhat is a crew built with it).
+
+## How it works
+Each principle is a **crew lead** — a module that owns its success criteria. Every
+applicable criterion gets a recorded result; nothing is silently skipped:
+
+- **PASS** — checked and met.
+- **FAIL** — checked and failed, with the specific elements.
+- **CHECK** — a representative measurement ran; a human must confirm the rest
+  (keyboard operation, caption quality, reading order — anything a parser can't
+  judge alone). Each CHECK names the exact thing to look at.
+- **NA** — not present on this page.
+
+| Crew lead | Principle | Measured deterministically | Representative check + human confirm |
+|---|---|---|---|
+| `perceivable.py` | 1 | **contrast (1.4.3, luminance math)**, alt text (1.1.1), headings/labels/tables (1.3.1), autoplay (1.4.2), resize/zoom (1.4.4) | media captions (1.2.x), sensory wording (1.3.3), use of color (1.4.1), images of text (1.4.5) |
+| `operable.py` | 2 | bypass (2.4.1), title (2.4.2), positive tabindex (2.4.3), link purpose (2.4.4), focus-visible suppression (2.4.7), mouse-only onclick (2.1.1) | keyboard operation, traps, timing, flashing, multiple ways |
+| `understandable.py` | 3 | page language (3.1.1), auto-context-change on input (3.2.2), control labels (3.3.2) | language of parts, predictability, error identification/prevention |
+| `robust.py` | 4 | duplicate ids (4.1.1), accessible name of every interactive element (4.1.2) | status-message live regions (4.1.3) |
+
+Shared foundation: `dom.py` (a dependency-free DOM), `color.py` (WCAG luminance),
+`base.py` (the uniform `Finding` record and the `Crew` base).
+
+## Install & run
+```
+pip install a11yhat            # once on PyPI
+python -m a11yhat page.html    # full POUR report, exit 1 on any FAIL
+python -m a11yhat page.html --json
+cat page.html | python -m a11yhat -
+```
+
+## Grounding
+Criteria, topics, and pass/fail conditions follow the **DHS Trusted Tester for Web
+(5.1.3)** process. Standard library only — nothing is installed into your
+environment. Automated checks catch the machine-decidable failures; the CHECK
+items are the ones a tester must confirm, each with the exact thing to review. It
+is an honest tool: it does the fast 80% and tells you precisely what the human 20%
+is — it does not pretend a scanner can certify a page.
+
+## License
+MIT. Copyright Vincent Gonzalez / F-Keys Creative LLC.
+
+## Tests
+`python -m unittest discover -s tests` — every deterministic check is proven to
+catch its defect and to clear on good input, and a clean page produces zero
+failures.

a11yhat-0.1.0/README.md

@@ -0,0 +1,51 @@
+# a11yhat
+
+An open-source **WCAG 2.2 accessibility machine**, structured the way the work is
+organized — by the four principles, **Perceivable · Operable · Understandable ·
+Robust (POUR)**. One crew in the **hardHats** family (hardHats is the framework;
+a11yhat is a crew built with it).
+
+## How it works
+Each principle is a **crew lead** — a module that owns its success criteria. Every
+applicable criterion gets a recorded result; nothing is silently skipped:
+
+- **PASS** — checked and met.
+- **FAIL** — checked and failed, with the specific elements.
+- **CHECK** — a representative measurement ran; a human must confirm the rest
+  (keyboard operation, caption quality, reading order — anything a parser can't
+  judge alone). Each CHECK names the exact thing to look at.
+- **NA** — not present on this page.
+
+| Crew lead | Principle | Measured deterministically | Representative check + human confirm |
+|---|---|---|---|
+| `perceivable.py` | 1 | **contrast (1.4.3, luminance math)**, alt text (1.1.1), headings/labels/tables (1.3.1), autoplay (1.4.2), resize/zoom (1.4.4) | media captions (1.2.x), sensory wording (1.3.3), use of color (1.4.1), images of text (1.4.5) |
+| `operable.py` | 2 | bypass (2.4.1), title (2.4.2), positive tabindex (2.4.3), link purpose (2.4.4), focus-visible suppression (2.4.7), mouse-only onclick (2.1.1) | keyboard operation, traps, timing, flashing, multiple ways |
+| `understandable.py` | 3 | page language (3.1.1), auto-context-change on input (3.2.2), control labels (3.3.2) | language of parts, predictability, error identification/prevention |
+| `robust.py` | 4 | duplicate ids (4.1.1), accessible name of every interactive element (4.1.2) | status-message live regions (4.1.3) |
+
+Shared foundation: `dom.py` (a dependency-free DOM), `color.py` (WCAG luminance),
+`base.py` (the uniform `Finding` record and the `Crew` base).
+
+## Install & run
+```
+pip install a11yhat            # once on PyPI
+python -m a11yhat page.html    # full POUR report, exit 1 on any FAIL
+python -m a11yhat page.html --json
+cat page.html | python -m a11yhat -
+```
+
+## Grounding
+Criteria, topics, and pass/fail conditions follow the **DHS Trusted Tester for Web
+(5.1.3)** process. Standard library only — nothing is installed into your
+environment. Automated checks catch the machine-decidable failures; the CHECK
+items are the ones a tester must confirm, each with the exact thing to review. It
+is an honest tool: it does the fast 80% and tells you precisely what the human 20%
+is — it does not pretend a scanner can certify a page.
+
+## License
+MIT. Copyright Vincent Gonzalez / F-Keys Creative LLC.
+
+## Tests
+`python -m unittest discover -s tests` — every deterministic check is proven to
+catch its defect and to clear on good input, and a clean page produces zero
+failures.

a11yhat-0.1.0/a11yhat/__main__.py

@@ -0,0 +1,6 @@
+"""Enable `python -m a11yhat page.html`."""
+import sys
+
+from .run import main
+
+sys.exit(main())

a11yhat-0.1.0/a11yhat/base.py

@@ -0,0 +1,53 @@
+"""
+Shared result model for hardHats. Every success criterion a crew checks returns a
+Finding, so the four crew leads (Perceivable, Operable, Understandable, Robust)
+produce one uniform record and the runner can roll them up by principle.
+
+A criterion is never silently skipped: it is PASS, FAIL, REVIEW (a representative
+measurement ran but a human must confirm), or NA (not present on this page). That
+is the Trusted Tester stance - every applicable criterion gets a recorded result.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+PASS, FAIL, REVIEW, NA = "PASS", "FAIL", "REVIEW", "NA"
+
+PRINCIPLE = {"1": "Perceivable", "2": "Operable", "3": "Understandable", "4": "Robust"}
+
+
+@dataclass
+class Finding:
+    sc: str                 # "1.1.1"
+    level: str              # "A" / "AA"
+    name: str               # short criterion name
+    topic: str              # Trusted Tester topic reference
+    status: str = REVIEW
+    detail: list = field(default_factory=list)   # specific problems or notes
+    measurement: str = ""   # the number/evidence the check produced
+
+    @property
+    def principle(self) -> str:
+        return PRINCIPLE[self.sc[0]]
+
+
+class Crew:
+    """A principle's crew lead. Each check() appends one Finding per criterion."""
+
+    principle_num = ""
+
+    def __init__(self, doc, css: str = "", html: str = ""):
+        self.doc = doc
+        self.css = css or ""
+        self.html = html or ""
+        self.findings: list[Finding] = []
+
+    def record(self, sc, level, name, topic, status, detail=None, measurement=""):
+        self.findings.append(Finding(sc, level, name, topic, status,
+                                     list(detail or []), measurement))
+
+    def run(self) -> list[Finding]:
+        for name in dir(self):
+            if name.startswith("sc_"):
+                getattr(self, name)()
+        return self.findings

a11yhat-0.1.0/a11yhat/color.py

@@ -0,0 +1,42 @@
+"""WCAG contrast math. Relative luminance and ratio, per WCAG 2.x definitions."""
+from __future__ import annotations
+
+import re
+
+_NAMED = {"black": (0, 0, 0), "white": (255, 255, 255), "red": (255, 0, 0),
+          "green": (0, 128, 0), "blue": (0, 0, 255), "gray": (128, 128, 128),
+          "grey": (128, 128, 128), "silver": (192, 192, 192), "navy": (0, 0, 128)}
+
+
+def parse_color(value: str):
+    """#rgb, #rrggbb, rgb()/rgba(), or a few named colors -> (r,g,b) or None."""
+    v = value.strip().lower()
+    if v in _NAMED:
+        return _NAMED[v]
+    m = re.fullmatch(r"#([0-9a-f]{3})", v)
+    if m:
+        return tuple(int(c * 2, 16) for c in m.group(1))
+    m = re.fullmatch(r"#([0-9a-f]{6})", v)
+    if m:
+        h = m.group(1)
+        return tuple(int(h[i:i + 2], 16) for i in (0, 2, 4))
+    m = re.match(r"rgba?\(\s*([\d.]+)[,\s]+([\d.]+)[,\s]+([\d.]+)", v)
+    if m:
+        return tuple(min(255, int(float(x))) for x in m.groups())
+    return None
+
+
+def _lin(c: float) -> float:
+    c /= 255.0
+    return c / 12.92 if c <= 0.03928 else ((c + 0.055) / 1.055) ** 2.4
+
+
+def luminance(rgb) -> float:
+    r, g, b = (_lin(x) for x in rgb)
+    return 0.2126 * r + 0.7152 * g + 0.0722 * b
+
+
+def ratio(fg, bg) -> float:
+    l1, l2 = luminance(fg), luminance(bg)
+    hi, lo = max(l1, l2), min(l1, l2)
+    return (hi + 0.05) / (lo + 0.05)

a11yhat-0.1.0/a11yhat/dom.py

@@ -0,0 +1,93 @@
+"""
+A small, dependency-free DOM for the hardHats accessibility checks.
+
+Standard-library html.parser only (nothing is pip-installed into his env). The
+checks need to ask real structural questions - every img, heading levels in
+order, form controls and their labels, interactive elements, duplicate ids - so
+they query this tree instead of guessing with regex.
+"""
+from __future__ import annotations
+
+from html.parser import HTMLParser
+
+VOID = {"area", "base", "br", "col", "embed", "hr", "img", "input", "link",
+        "meta", "param", "source", "track", "wbr"}
+INTERACTIVE = {"a", "button", "input", "select", "textarea", "details", "summary"}
+
+
+class Node:
+    __slots__ = ("tag", "attrs", "parent", "children", "text", "line")
+
+    def __init__(self, tag, attrs=None, line=0):
+        self.tag = tag
+        self.attrs = attrs or {}
+        self.parent = None
+        self.children: list[Node] = []
+        self.text = ""
+        self.line = line
+
+    def get(self, name, default=None):
+        return self.attrs.get(name, default)
+
+    def has(self, name):
+        return name in self.attrs
+
+    def walk(self):
+        yield self
+        for c in self.children:
+            yield from c.walk()
+
+    def find(self, *tags):
+        tset = set(tags)
+        return [n for n in self.walk() if n.tag in tset]
+
+    def inner_text(self):
+        out = [self.text]
+        for c in self.children:
+            out.append(c.inner_text())
+        return " ".join(t for t in out if t).strip()
+
+    def role(self):
+        return (self.get("role") or "").strip().lower()
+
+    def is_interactive(self):
+        if self.tag in INTERACTIVE and not (self.tag == "a" and not self.has("href")):
+            return True
+        if self.role() in {"button", "link", "checkbox", "menuitem", "tab", "switch"}:
+            return True
+        return self.has("onclick") or self.has("tabindex")
+
+
+class _Builder(HTMLParser):
+    def __init__(self):
+        super().__init__(convert_charrefs=True)
+        self.root = Node("#document")
+        self.stack = [self.root]
+
+    def handle_starttag(self, tag, attrs):
+        node = Node(tag, {k: (v or "") for k, v in attrs}, self.getpos()[0])
+        node.parent = self.stack[-1]
+        self.stack[-1].children.append(node)
+        if tag not in VOID:
+            self.stack.append(node)
+
+    def handle_startendtag(self, tag, attrs):
+        node = Node(tag, {k: (v or "") for k, v in attrs}, self.getpos()[0])
+        node.parent = self.stack[-1]
+        self.stack[-1].children.append(node)
+
+    def handle_endtag(self, tag):
+        for i in range(len(self.stack) - 1, 0, -1):
+            if self.stack[i].tag == tag:
+                del self.stack[i:]
+                break
+
+    def handle_data(self, data):
+        if data.strip():
+            self.stack[-1].text = (self.stack[-1].text + " " + data.strip()).strip()
+
+
+def parse(html: str) -> Node:
+    b = _Builder()
+    b.feed(html)
+    return b.root

a11yhat-0.1.0/a11yhat/operable.py

@@ -0,0 +1,164 @@
+"""
+Operable - WCAG Principle 2 crew lead. UI components and navigation must be
+operable. Keyboard and focus-order "sense" can only be confirmed by a human, so
+those criteria run a representative measurement (enumerate the controls, catch the
+static giveaways) and flag the rest for the keyboard pass.
+"""
+from __future__ import annotations
+
+import re
+
+from .base import FAIL, NA, PASS, REVIEW, Crew
+
+VAGUE_LINK = {"click here", "here", "read more", "more", "link", "this", "learn more",
+              "details", "continue", "go", "click", "download"}
+
+
+class Operable(Crew):
+    principle_num = "2"
+
+    # ---- 2.1.1 Keyboard (Topic 4) ----
+    def sc_211_keyboard(self):
+        mouse_only = []
+        for el in self.doc.walk():
+            if el.has("onclick") and el.tag not in ("a", "button", "input", "select", "textarea") \
+                    and not el.role() and not el.has("tabindex"):
+                mouse_only.append(el.tag)
+        interactive = [e for e in self.doc.walk() if e.is_interactive()]
+        status = FAIL if mouse_only else REVIEW
+        detail = []
+        if mouse_only:
+            detail.append(f"{len(mouse_only)} element(s) with onclick but no role/tabindex "
+                          f"(keyboard cannot reach): {', '.join(sorted(set(mouse_only))[:4])}")
+        detail.append(f"confirm all {len(interactive)} interactive elements work with Tab/Enter/Space")
+        self.record("2.1.1", "A", "Keyboard", "Topic 4 Keyboard access & focus", status, detail,
+                    f"{len(interactive)} interactive, {len(mouse_only)} mouse-only")
+
+    # ---- 2.1.2 No keyboard trap (Topic 4) ----
+    def sc_212_trap(self):
+        self.record("2.1.2", "A", "No keyboard trap", "Topic 4 Keyboard access & focus", REVIEW,
+                    ["tab through the page; focus must never get stuck in a widget or dialog"],
+                    "manual")
+
+    # ---- 2.2.1 / 2.2.2 Timing & moving content (Topics 8, 2) ----
+    def sc_221_timing(self):
+        refresh = re.search(r'<meta[^>]+http-equiv=["\']refresh["\'][^>]*content=["\'](\d+)', self.html, re.I)
+        if refresh and int(refresh.group(1)) > 0:
+            self.record("2.2.1", "A", "Timing adjustable", "Topic 8 Adjustable time limits", FAIL,
+                        [f"meta refresh after {refresh.group(1)}s with no user control"],
+                        f"refresh={refresh.group(1)}s")
+        else:
+            self.record("2.2.1", "A", "Timing adjustable", "Topic 8 Adjustable time limits", REVIEW,
+                        ["no auto-refresh found; confirm any session/interaction time limits are "
+                         "adjustable"], "no meta-refresh")
+
+    def sc_222_moving(self):
+        moving = len(self.doc.find("marquee", "blink"))
+        anim = len(re.findall(r"@keyframes|animation\s*:", self.css, re.I))
+        autop = len([m for m in self.doc.find("audio", "video") if m.has("autoplay")])
+        n = moving + anim + autop
+        self.record("2.2.2", "A", "Pause, stop, hide", "Topic 2 Auto-updating content",
+                    FAIL if moving else (REVIEW if n else PASS),
+                    ([f"moving/auto-updating content: {moving} marquee, {anim} CSS animation, "
+                      f"{autop} autoplay - must be pausable if it runs over 5s"] if n else []),
+                    f"{n} moving source(s)")
+
+    # ---- 2.3.1 Three flashes (Topic 3) ----
+    def sc_231_flash(self):
+        risk = len(self.doc.find("video", "canvas")) + len(re.findall(r"@keyframes", self.css, re.I))
+        self.record("2.3.1", "A", "Three flashes or below", "Topic 3 Flashing",
+                    REVIEW if risk else PASS,
+                    (["nothing may flash more than 3 times per second; review video/animation"]
+                     if risk else []), f"{risk} animation/video source(s)")
+
+    # ---- 2.4.1 Bypass blocks (Topic 9) ----
+    def sc_241_bypass(self):
+        skip = any("skip" in (a.inner_text() or "").lower() for a in self.doc.find("a") if a.has("href"))
+        landmark = bool(self.doc.find("main") or any(e.role() == "main" for e in self.doc.walk()))
+        ok = skip or landmark
+        self.record("2.4.1", "A", "Bypass blocks", "Topic 9 Repetitive content",
+                    PASS if ok else FAIL,
+                    ([] if ok else ["no skip link and no <main>/role=main landmark to bypass "
+                                    "repeated navigation"]),
+                    f"skip-link={skip}, main={landmark}")
+
+    # ---- 2.4.2 Page titled (Topic 12) ----
+    def sc_242_title(self):
+        t = self.doc.find("title")
+        text = t[0].inner_text() if t else ""
+        self.record("2.4.2", "A", "Page titled", "Topic 12 Page titles & frames",
+                    PASS if text.strip() else FAIL,
+                    ([] if text.strip() else ["missing or empty <title>"]),
+                    f'title="{text[:40]}"')
+
+    # ---- 2.4.3 Focus order (Topic 4) ----
+    def sc_243_focusorder(self):
+        pos = [int(e.get("tabindex")) for e in self.doc.walk()
+               if e.get("tabindex", "").lstrip("-").isdigit() and int(e.get("tabindex")) > 0]
+        self.record("2.4.3", "A", "Focus order", "Topic 4 Keyboard access & focus",
+                    FAIL if pos else REVIEW,
+                    ([f"{len(pos)} positive tabindex value(s) override natural order"] if pos
+                     else ["confirm the tab order follows the visual/reading order"]),
+                    f"{len(pos)} positive tabindex")
+
+    # ---- 2.4.4 Link purpose (Topic 6) ----
+    def sc_244_linkpurpose(self):
+        empty, vague = [], []
+        for a in self.doc.find("a"):
+            if not a.has("href"):
+                continue
+            txt = (a.inner_text() or a.get("aria-label") or a.get("title") or "").strip().lower()
+            if not txt:
+                empty.append(a.get("href", "")[:30])
+            elif txt in VAGUE_LINK:
+                vague.append(txt)
+        detail = []
+        if empty:
+            detail.append(f"{len(empty)} link(s) with no text/label")
+        if vague:
+            detail.append(f"non-descriptive link text: {', '.join(sorted(set(vague))[:5])}")
+        self.record("2.4.4", "A", "Link purpose (in context)", "Topic 6 Links",
+                    FAIL if empty else (REVIEW if vague else PASS), detail,
+                    f"{len(self.doc.find('a'))} links, {len(empty)} empty, {len(vague)} vague")
+
+    # ---- 2.4.5 Multiple ways (Topic 19) ----
+    def sc_245_multiple(self):
+        nav = len(self.doc.find("nav")) or sum(1 for e in self.doc.walk() if e.role() == "navigation")
+        search = bool([i for i in self.doc.find("input") if i.get("type") == "search"]) \
+            or "search" in self.html.lower()
+        ways = (1 if nav else 0) + (1 if search else 0)
+        self.record("2.4.5", "AA", "Multiple ways", "Topic 19 Multiple ways", REVIEW,
+                    [f"confirm at least two ways to find pages (nav={bool(nav)}, search={search}); "
+                     "a sitemap or site search counts"], f"{ways} way(s) detected")
+
+    # ---- 2.4.6 Headings and labels (AA) ----
+    def sc_246_headings(self):
+        empty_h = [h.tag for h in self.doc.find("h1", "h2", "h3", "h4", "h5", "h6")
+                   if not h.inner_text().strip()]
+        self.record("2.4.6", "AA", "Headings and labels", "Topic 10 Content structure",
+                    FAIL if empty_h else REVIEW,
+                    ([f"{len(empty_h)} empty heading(s)"] if empty_h
+                     else ["confirm headings and labels describe their topic or purpose"]),
+                    f"{len(empty_h)} empty headings")
+
+    # ---- 2.4.7 Focus visible (Topic 4, AA) ----
+    def sc_247_focusvisible(self):
+        blocks = re.findall(r"(:focus(?:-visible)?[^{]*)\{([^}]*)\}", self.css, re.I)
+        if not blocks:
+            self.record("2.4.7", "AA", "Focus visible", "Topic 4 Keyboard access & focus", REVIEW,
+                        ["no :focus style found; confirm the browser default focus ring is visible "
+                         "and not suppressed elsewhere"], "no :focus rule")
+            return
+        bad = []
+        for sel, body in blocks:
+            b = body.lower()
+            removes = re.search(r"outline\s*:\s*(none|0)\b", b)
+            replaces = (re.search(r"box-shadow\s*:\s*(?!none)", b)
+                        or re.search(r"border(-[a-z]+)?\s*:\s*(?!none|0\b)\S", b)
+                        or re.search(r"outline\s*:\s*(?!none|0\b)\S", b))
+            if removes and not replaces:
+                bad.append(sel.strip())
+        self.record("2.4.7", "AA", "Focus visible", "Topic 4 Keyboard access & focus",
+                    FAIL if bad else PASS,
+                    ([f"focus outline removed with no visible replacement: {bad[0]}"] if bad else []),
+                    f"{len(blocks)} focus rule(s), {len(bad)} suppressed")

a11yhat-0.1.0/a11yhat/perceivable.py

@@ -0,0 +1,206 @@
+"""
+Perceivable - WCAG Principle 1 crew lead. Information and UI components must be
+presentable in ways users can perceive. Every applicable criterion gets a result;
+contrast (1.4.3) is measured, the rest are checked structurally or flagged for
+confirmation with the specific thing to look at.
+"""
+from __future__ import annotations
+
+import re
+
+from .base import FAIL, NA, PASS, REVIEW, Crew
+from .color import parse_color, ratio
+
+SENSORY = re.compile(r"\b(round|square|circular|the (left|right|top|bottom)|"
+                     r"on the (left|right)|above|below|the (green|red|blue) (button|box|link))\b", re.I)
+
+
+def css_rules(css: str):
+    """Yield (selector, {prop: value}) for each rule block in a stylesheet."""
+    for block in re.findall(r"([^{}]+)\{([^{}]*)\}", css):
+        sel, body = block[0].strip(), block[1]
+        decls = {}
+        for part in body.split(";"):
+            if ":" in part:
+                k, v = part.split(":", 1)
+                decls[k.strip().lower()] = v.strip()
+        if decls:
+            yield sel, decls
+
+
+class Perceivable(Crew):
+    principle_num = "1"
+
+    # ---- 1.1.1 Non-text content (Topic 7) ----
+    def sc_111_images(self):
+        imgs = self.doc.find("img")
+        no_alt = [i for i in imgs if not i.has("alt")]
+        bad_alt = []
+        for i in imgs:
+            alt = i.get("alt", "").strip()
+            if alt and (re.search(r"\.(png|jpe?g|gif|svg|webp)$", alt, re.I)
+                        or re.fullmatch(r"(image|img|photo|picture|icon|logo)\d*", alt, re.I)):
+                bad_alt.append(alt[:40])
+        svg_unnamed = [s for s in self.doc.find("svg")
+                       if s.role() == "img" and not (s.has("aria-label") or s.find("title"))]
+        canvas_bare = [c for c in self.doc.find("canvas") if not c.inner_text()]
+        detail = []
+        if no_alt:
+            detail.append(f"{len(no_alt)} <img> without an alt attribute")
+        if bad_alt:
+            detail.append(f"alt looks like a filename/label: {', '.join(bad_alt[:3])}")
+        if svg_unnamed:
+            detail.append(f"{len(svg_unnamed)} role=img <svg> with no title/aria-label")
+        if canvas_bare:
+            detail.append(f"{len(canvas_bare)} <canvas> with no text alternative")
+        if not imgs and not self.doc.find("svg", "canvas"):
+            self.record("1.1.1", "A", "Non-text content", "Topic 7 Images", NA,
+                        measurement="no images on the page")
+            return
+        status = FAIL if (no_alt or svg_unnamed or canvas_bare) else (REVIEW if bad_alt else PASS)
+        self.record("1.1.1", "A", "Non-text content", "Topic 7 Images", status, detail,
+                    f"{len(imgs)} img, {len(no_alt)} missing alt")
+
+    # ---- 1.2.x Time-based media (Topics 16, 17) ----
+    def sc_12_media(self):
+        av = self.doc.find("audio", "video")
+        if not av:
+            self.record("1.2.1", "A", "Audio/video alternatives", "Topic 16/17 Media", NA,
+                        measurement="no audio or video elements")
+            return
+        tracks = sum(1 for v in av for t in v.find("track") if t.get("kind") == "captions")
+        self.record("1.2.2", "A", "Captions & transcripts", "Topic 17 Synchronized media", REVIEW,
+                    [f"{len(av)} media element(s); confirm captions, transcript, and audio "
+                     f"description (found {tracks} caption track(s))"],
+                    f"{len(av)} media, {tracks} caption tracks")
+
+    # ---- 1.3.1 Info and relationships (Topics 10, 14, 5) ----
+    def sc_131_structure(self):
+        detail = []
+        # headings do not skip levels
+        levels = [int(h.tag[1]) for h in self.doc.find("h1", "h2", "h3", "h4", "h5", "h6")]
+        prev = 0
+        for lv in levels:
+            if prev and lv > prev + 1:
+                detail.append(f"heading jumps from h{prev} to h{lv}")
+            prev = lv
+        # form controls have a programmatic label
+        unlabeled = []
+        labels_for = {l.get("for") for l in self.doc.find("label") if l.has("for")}
+        for ctl in self.doc.find("input", "select", "textarea"):
+            if ctl.get("type", "").lower() in ("hidden", "submit", "button", "reset", "image"):
+                continue
+            named = (ctl.has("aria-label") or ctl.has("aria-labelledby")
+                     or ctl.has("title") or ctl.get("id") in labels_for
+                     or (ctl.parent and ctl.parent.tag == "label"))
+            if not named:
+                unlabeled.append(ctl.get("name") or ctl.get("id") or ctl.tag)
+        # data tables have header cells
+        headerless = [t for t in self.doc.find("table")
+                      if t.find("td") and not (t.find("th") or any(
+                          c.get("scope") for c in t.find("td")))]
+        if unlabeled:
+            detail.append(f"{len(unlabeled)} form control(s) without a label")
+        if headerless:
+            detail.append(f"{len(headerless)} data table(s) without <th> header cells")
+        status = FAIL if detail else PASS
+        self.record("1.3.1", "A", "Info and relationships", "Topic 10/14/5 Structure", status,
+                    detail, f"{len(levels)} headings, "
+                    f"{len(self.doc.find('input','select','textarea'))} controls, "
+                    f"{len(self.doc.find('table'))} tables")
+
+    # ---- 1.3.2 Meaningful sequence (Topic 15) ----
+    def sc_132_sequence(self):
+        reorder = len(re.findall(r"\b(order\s*:\s*-?\d|float\s*:\s*(left|right)|"
+                                 r"position\s*:\s*absolute|direction\s*:\s*rtl)\b", self.css, re.I))
+        self.record("1.3.2", "A", "Meaningful sequence", "Topic 15 CSS content & positioning",
+                    REVIEW if reorder else PASS,
+                    ([f"{reorder} CSS rule(s) reorder/position content - confirm the DOM order "
+                      f"still reads correctly with CSS off"] if reorder else []),
+                    f"{reorder} reordering rules")
+
+    # ---- 1.3.3 Sensory characteristics (Topic 13) ----
+    def sc_133_sensory(self):
+        hits = set(m.group(0) for m in SENSORY.finditer(self.doc.inner_text()))
+        self.record("1.3.3", "A", "Sensory characteristics", "Topic 13 Sensory & contrast",
+                    REVIEW if hits else PASS,
+                    ([f"instructions may rely on shape/position/color alone: "
+                      f"{', '.join(list(hits)[:4])}"] if hits else []),
+                    f"{len(hits)} sensory phrase(s)")
+
+    # ---- 1.4.1 Use of color (Topic 13) ----
+    def sc_141_color(self):
+        links = self.doc.find("a")
+        plain = [a for a in links if a.has("href") and "text-decoration" in self.css.lower()
+                 and re.search(r"text-decoration\s*:\s*none", self.css, re.I)]
+        self.record("1.4.1", "A", "Use of color", "Topic 13 Sensory & contrast", REVIEW,
+                    ["confirm no information is conveyed by color alone (links, required fields, "
+                     f"states); {('underlines removed via CSS' if plain else 'check in-text links')}"],
+                    f"{len(links)} links")
+
+    # ---- 1.4.2 Audio control (Topic 2) ----
+    def sc_142_audio(self):
+        autop = [m for m in self.doc.find("audio", "video")
+                 if m.has("autoplay") and not m.has("muted")]
+        self.record("1.4.2", "A", "Audio control", "Topic 2 Auto-playing content",
+                    FAIL if autop else PASS,
+                    ([f"{len(autop)} media element(s) autoplay sound with no control"] if autop else []),
+                    f"{len(autop)} autoplaying")
+
+    # ---- 1.4.3 Contrast (minimum) - MEASURED (Topic 13) ----
+    def sc_143_contrast(self):
+        pairs = []  # (ratio, where, fg, bg)
+        # inline styles that set both color and a background
+        for el in self.doc.walk():
+            st = el.get("style", "").lower()
+            fg = re.search(r"(?<!-)color\s*:\s*([^;]+)", st)
+            bg = re.search(r"background(?:-color)?\s*:\s*([^;]+)", st)
+            if fg and bg:
+                c, b = parse_color(fg.group(1)), parse_color(bg.group(1))
+                if c and b:
+                    pairs.append((ratio(c, b), f"<{el.tag} style>", fg.group(1).strip(), bg.group(1).strip()))
+        # stylesheet rules that set both
+        for sel, decls in css_rules(self.css):
+            if "color" in decls and ("background" in decls or "background-color" in decls):
+                c = parse_color(decls["color"])
+                b = parse_color(decls.get("background-color") or decls.get("background", ""))
+                if c and b:
+                    pairs.append((ratio(c, b), sel.strip()[:40], decls["color"],
+                                  decls.get("background-color") or decls["background"]))
+        if not pairs:
+            self.record("1.4.3", "AA", "Contrast (minimum)", "Topic 13 Sensory & contrast", REVIEW,
+                        ["no element declares both text and background color; measure rendered "
+                         "contrast with a tool (needs 4.5:1 normal, 3:1 large text)"], "0 pairs measured")
+            return
+        fails = [p for p in pairs if p[0] < 4.5]
+        worst = min(pairs, key=lambda p: p[0])
+        detail = [f"{w}: {r:.2f}:1 ({fg} on {bg}) - below 4.5:1"
+                  for r, w, fg, bg in sorted(fails)[:5]]
+        self.record("1.4.3", "AA", "Contrast (minimum)", "Topic 13 Sensory & contrast",
+                    FAIL if fails else PASS, detail,
+                    f"{len(pairs)} pairs measured, lowest {worst[0]:.2f}:1, {len(fails)} below 4.5:1")
+
+    # ---- 1.4.4 Resize text (Topic 18) ----
+    def sc_144_resize(self):
+        detail = []
+        vp = re.search(r'<meta[^>]+name=["\']viewport["\'][^>]*>', self.html, re.I)
+        if vp and re.search(r"user-scalable\s*=\s*no|maximum-scale\s*=\s*(1(\.0)?|0)", vp.group(0), re.I):
+            detail.append("viewport blocks zoom (user-scalable=no / maximum-scale<=1)")
+        tiny = sorted(set(int(m.group(1)) for m in re.finditer(r"font-size\s*:\s*(\d+)px", self.css)
+                          if int(m.group(1)) < 13))
+        if tiny:
+            detail.append(f"font-size below 13px floor: {', '.join(f'{p}px' for p in tiny)}")
+        self.record("1.4.4", "AA", "Resize text", "Topic 18 Resize text",
+                    FAIL if any("blocks zoom" in d for d in detail) else (REVIEW if tiny else PASS),
+                    detail, f"zoom blocked: {bool(vp and 'detail' and any('blocks' in d for d in detail))}")
+
+    # ---- 1.4.5 Images of text (Topic 7/13) ----
+    def sc_145_imgtext(self):
+        imgs = self.doc.find("img")
+        if not imgs:
+            self.record("1.4.5", "AA", "Images of text", "Topic 7 Images", NA,
+                        measurement="no images")
+            return
+        self.record("1.4.5", "AA", "Images of text", "Topic 7 Images", REVIEW,
+                    [f"confirm none of the {len(imgs)} images are pictures of text that could be "
+                     "real text (logos are exempt)"], f"{len(imgs)} images to review")

a11yhat-0.1.0/a11yhat/robust.py

@@ -0,0 +1,70 @@
+"""
+Robust - WCAG Principle 4 crew lead. Content must be robust enough for assistive
+technology. Name/role/value is the heart of it, so the accessible name of every
+interactive element is checked directly; parsing (duplicate ids) is deterministic;
+status messages are flagged for the dynamic-content pass.
+"""
+from __future__ import annotations
+
+from collections import Counter
+
+from .base import FAIL, NA, PASS, REVIEW, Crew
+
+NAMED_ROLE_NEEDS = {
+    "checkbox": "aria-checked", "switch": "aria-checked", "radio": "aria-checked",
+    "slider": "aria-valuenow", "combobox": "aria-expanded", "tab": "aria-selected",
+}
+
+
+class Robust(Crew):
+    principle_num = "4"
+
+    # ---- 4.1.1 Parsing / duplicate ids (Topic 20) ----
+    def sc_411_parsing(self):
+        ids = [e.get("id") for e in self.doc.walk() if e.has("id") and e.get("id")]
+        dups = [i for i, n in Counter(ids).items() if n > 1]
+        self.record("4.1.1", "A", "Parsing (unique ids)", "Topic 20 Parsing",
+                    FAIL if dups else PASS,
+                    ([f"duplicate id(s): {', '.join(dups[:6])}"] if dups else []),
+                    f"{len(ids)} ids, {len(dups)} duplicated")
+
+    # ---- 4.1.2 Name, role, value (Topics 4/5/6) ----
+    def sc_412_namerolevalue(self):
+        labels_for = {l.get("for") for l in self.doc.find("label") if l.has("for")}
+        nameless, roleless_widget = [], []
+        for el in self.doc.walk():
+            if not el.is_interactive():
+                continue
+            name = (el.inner_text() or el.get("aria-label") or el.get("aria-labelledby")
+                    or el.get("title") or el.get("alt") or el.get("value")
+                    or el.get("placeholder") or "").strip()
+            associated = el.get("id") in labels_for or (el.parent and el.parent.tag == "label")
+            if not name and not associated:
+                nameless.append(el.tag + (f"[{el.role()}]" if el.role() else ""))
+            role = el.role()
+            if role in NAMED_ROLE_NEEDS and not el.has(NAMED_ROLE_NEEDS[role]):
+                roleless_widget.append(f"{role} missing {NAMED_ROLE_NEEDS[role]}")
+        detail = []
+        if nameless:
+            detail.append(f"{len(nameless)} interactive element(s) with no accessible name: "
+                          f"{', '.join(sorted(set(nameless))[:4])}")
+        if roleless_widget:
+            detail.append(f"custom widget(s) missing a required state: "
+                          f"{', '.join(sorted(set(roleless_widget))[:4])}")
+        total = sum(1 for e in self.doc.walk() if e.is_interactive())
+        if not total:
+            self.record("4.1.2", "A", "Name, role, value", "Topic 5 Forms / 4 Controls", NA,
+                        measurement="no interactive elements")
+            return
+        self.record("4.1.2", "A", "Name, role, value", "Topic 5 Forms / 4 Controls",
+                    FAIL if detail else PASS, detail,
+                    f"{total} interactive, {len(nameless)} unnamed")
+
+    # ---- 4.1.3 Status messages (AA) ----
+    def sc_413_status(self):
+        live = [e for e in self.doc.walk()
+                if e.has("aria-live") or e.role() in ("status", "alert", "log")]
+        self.record("4.1.3", "AA", "Status messages", "Topic (dynamic content)", REVIEW,
+                    [f"confirm dynamic updates (errors, cart counts, results) are announced via a "
+                     f"live region ({len(live)} aria-live/status region(s) present)"],
+                    f"{len(live)} live region(s)")

a11yhat-0.1.0/a11yhat/run.py

@@ -0,0 +1,91 @@
+"""
+a11yhat - runner. Parses an HTML page, deploys the four crew leads (Perceivable,
+Operable, Understandable, Robust), and reports every applicable success criterion
+with its result and the measurement behind it. A crew in the hardHats family.
+
+  python -m a11yhat page.html
+  python -m a11yhat page.html --json
+  cat page.html | python -m a11yhat -
+"""
+from __future__ import annotations
+
+import json
+import re
+import sys
+
+try:
+    sys.stdout.reconfigure(encoding="utf-8", errors="replace")
+except (AttributeError, ValueError):
+    pass
+
+from .base import FAIL, NA, PASS, REVIEW
+from .dom import parse
+from .operable import Operable
+from .perceivable import Perceivable
+from .robust import Robust
+from .understandable import Understandable
+
+CREWS = [Perceivable, Operable, Understandable, Robust]
+MARK = {PASS: "PASS", FAIL: "FAIL", REVIEW: "CHECK", NA: " -- "}
+ORDER = {PASS: 1, FAIL: 0, REVIEW: 2, NA: 3}
+
+
+def audit(html: str):
+    css = "\n".join(re.findall(r"<style[^>]*>(.*?)</style>", html, re.I | re.S))
+    doc = parse(html)
+    findings = []
+    for crew in CREWS:
+        findings += crew(doc, css, html).run()
+    return findings
+
+
+def text_report(findings) -> int:
+    print("=" * 72)
+    print(" a11yhat - WCAG 2.2 A/AA machine (POUR)")
+    print("=" * 72)
+    fails = reviews = 0
+    for crew in CREWS:
+        pnum = crew.principle_num
+        rows = sorted([f for f in findings if f.sc[0] == pnum],
+                      key=lambda f: (ORDER[f.status], f.sc))
+        head = {"1": "PERCEIVABLE", "2": "OPERABLE", "3": "UNDERSTANDABLE", "4": "ROBUST"}[pnum]
+        nf = sum(1 for f in rows if f.status == FAIL)
+        nc = sum(1 for f in rows if f.status == REVIEW)
+        print(f"\n[{pnum}] {head}  —  crew lead: {crew.__name__}  "
+              f"({nf} fail, {nc} to check, {len(rows)} criteria)")
+        print("-" * 72)
+        for f in rows:
+            print(f"  {MARK[f.status]}  {f.sc:<6} {f.level:<2} {f.name}")
+            if f.measurement:
+                print(f"         └ {f.measurement}")
+            for d in f.detail:
+                print(f"           • {d}")
+        fails += nf
+        reviews += nc
+    total = len(findings)
+    print("\n" + "=" * 72)
+    verdict = "FAIL" if fails else ("NEEDS HUMAN REVIEW" if reviews else "PASS (automated)")
+    print(f" VERDICT: {verdict}  —  {fails} failing, {reviews} to confirm, "
+          f"{total} criteria across all four principles")
+    print("=" * 72)
+    return 1 if fails else 0
+
+
+def main():
+    args = sys.argv[1:]
+    as_json = "--json" in args
+    args = [a for a in args if a != "--json"]
+    src = args[0] if args else "-"
+    html = sys.stdin.read() if src == "-" else open(src, encoding="utf-8", errors="replace").read()
+    findings = audit(html)
+    if as_json:
+        print(json.dumps([{"sc": f.sc, "level": f.level, "principle": f.principle,
+                           "name": f.name, "topic": f.topic, "status": f.status,
+                           "measurement": f.measurement, "detail": f.detail}
+                          for f in findings], indent=1))
+        return 1 if any(f.status == FAIL for f in findings) else 0
+    return text_report(findings)
+
+
+if __name__ == "__main__":
+    sys.exit(main())

a11yhat-0.1.0/a11yhat/understandable.py

@@ -0,0 +1,98 @@
+"""
+Understandable - WCAG Principle 3 crew lead. Content and operation must be
+understandable. Language is checked deterministically; predictability and input
+assistance are confirmed by a representative measurement (what forms/controls
+exist, what is required) plus the human check each one needs.
+"""
+from __future__ import annotations
+
+import re
+
+from .base import FAIL, NA, PASS, REVIEW, Crew
+
+
+class Understandable(Crew):
+    principle_num = "3"
+
+    # ---- 3.1.1 Language of page (Topic 11) ----
+    def sc_311_lang(self):
+        m = re.search(r'<html\b[^>]*\blang\s*=\s*["\']?([a-zA-Z][a-zA-Z-]*)', self.html, re.I)
+        self.record("3.1.1", "A", "Language of page", "Topic 11 Language",
+                    PASS if m else FAIL,
+                    ([] if m else ["<html> has no lang attribute; set e.g. lang=\"en\""]),
+                    f'lang="{m.group(1) if m else "(none)"}"')
+
+    # ---- 3.1.2 Language of parts (Topic 11, AA) ----
+    def sc_312_langparts(self):
+        tagged = len(re.findall(r'<[a-z0-9]+[^>]*\blang\s*=', self.html, re.I)) - 1  # minus <html>
+        self.record("3.1.2", "AA", "Language of parts", "Topic 11 Language", REVIEW,
+                    [f"confirm any passage in another language carries its own lang attribute "
+                     f"({max(0, tagged)} non-root element(s) already tagged)"],
+                    f"{max(0, tagged)} tagged parts")
+
+    # ---- 3.2.1 / 3.2.2 Predictable (on focus / on input) ----
+    def sc_321_onfocus(self):
+        risk = len(re.findall(r"onfocus\s*=|onchange\s*=\s*[\"'][^\"']*(submit|location|open)", self.html, re.I))
+        self.record("3.2.1", "A", "On focus", "Topic (predictable)",
+                    REVIEW if risk else PASS,
+                    (["focusing a control must not change context (submit, navigate, open a "
+                      f"window); {risk} onfocus/onchange handler(s) to check"] if risk else []),
+                    f"{risk} focus/change handler(s)")
+
+    def sc_322_oninput(self):
+        selects_submit = len(re.findall(r"onchange\s*=\s*[\"'][^\"']*(submit|location)", self.html, re.I))
+        self.record("3.2.2", "A", "On input", "Topic (predictable)",
+                    FAIL if selects_submit else REVIEW,
+                    ([f"{selects_submit} control(s) change context on input (auto-submit/navigate) "
+                      "without warning"] if selects_submit
+                     else ["confirm changing a setting does not auto-submit or navigate unexpectedly"]),
+                    f"{selects_submit} auto-context-change")
+
+    # ---- 3.2.3 / 3.2.4 Consistent navigation & identification (AA) ----
+    def sc_323_consistency(self):
+        self.record("3.2.3", "AA", "Consistent navigation & identification",
+                    "Topic (predictable)", REVIEW,
+                    ["across the site, repeated navigation must keep the same order and repeated "
+                     "components the same name (a multi-page check)"], "cross-page")
+
+    # ---- 3.3.1 Error identification (Topic 5) ----
+    def sc_331_errorid(self):
+        forms = self.doc.find("form")
+        required = [c for c in self.doc.find("input", "select", "textarea")
+                    if c.has("required") or c.get("aria-required") == "true"]
+        if not forms and not required:
+            self.record("3.3.1", "A", "Error identification", "Topic 5 Forms", NA,
+                        measurement="no forms")
+            return
+        self.record("3.3.1", "A", "Error identification", "Topic 5 Forms", REVIEW,
+                    [f"{len(forms)} form(s), {len(required)} required field(s): submit with bad "
+                     "input and confirm each error is named in text (not color alone)"],
+                    f"{len(forms)} forms, {len(required)} required")
+
+    # ---- 3.3.2 Labels or instructions (Topic 5) ----
+    def sc_332_labels(self):
+        controls = [c for c in self.doc.find("input", "select", "textarea")
+                    if c.get("type", "").lower() not in ("hidden", "submit", "button", "reset")]
+        labels_for = {l.get("for") for l in self.doc.find("label") if l.has("for")}
+        missing = [c for c in controls if not (
+            c.has("aria-label") or c.has("aria-labelledby") or c.has("title")
+            or c.has("placeholder") or c.get("id") in labels_for
+            or (c.parent and c.parent.tag == "label"))]
+        if not controls:
+            self.record("3.3.2", "A", "Labels or instructions", "Topic 5 Forms", NA,
+                        measurement="no input controls")
+            return
+        self.record("3.3.2", "A", "Labels or instructions", "Topic 5 Forms",
+                    FAIL if missing else PASS,
+                    ([f"{len(missing)} control(s) with no visible label or instruction"] if missing
+                     else []), f"{len(controls)} controls, {len(missing)} without label")
+
+    # ---- 3.3.3 / 3.3.4 Error suggestion & prevention (AA) ----
+    def sc_334_prevention(self):
+        legal = re.search(r"(password|credit\s*card|payment|purchase|checkout|delete|confirm)",
+                          self.html, re.I)
+        self.record("3.3.4", "AA", "Error prevention (legal/financial)", "Topic 5 Forms", REVIEW,
+                    ["for legal, financial, or data-deletion submissions, confirm the user can "
+                     "review/reverse/confirm before committing"
+                     + (" - this page mentions one" if legal else "")],
+                    f"legal/financial context={bool(legal)}")

a11yhat-0.1.0/a11yhat.egg-info/PKG-INFO

@@ -0,0 +1,68 @@
+Metadata-Version: 2.4
+Name: a11yhat
+Version: 0.1.0
+Summary: a11yhat: a WCAG 2.2 accessibility machine, structured by POUR — four crew leads, every success criterion a recorded check. A hardHats crew.
+Author: Vincent Gonzalez
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/vince-gonzalez/a11yhat
+Project-URL: Repository, https://github.com/vince-gonzalez/a11yhat
+Keywords: accessibility,wcag,a11y,section508,audit,pour
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Quality Assurance
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# a11yhat
+
+An open-source **WCAG 2.2 accessibility machine**, structured the way the work is
+organized — by the four principles, **Perceivable · Operable · Understandable ·
+Robust (POUR)**. One crew in the **hardHats** family (hardHats is the framework;
+a11yhat is a crew built with it).
+
+## How it works
+Each principle is a **crew lead** — a module that owns its success criteria. Every
+applicable criterion gets a recorded result; nothing is silently skipped:
+
+- **PASS** — checked and met.
+- **FAIL** — checked and failed, with the specific elements.
+- **CHECK** — a representative measurement ran; a human must confirm the rest
+  (keyboard operation, caption quality, reading order — anything a parser can't
+  judge alone). Each CHECK names the exact thing to look at.
+- **NA** — not present on this page.
+
+| Crew lead | Principle | Measured deterministically | Representative check + human confirm |
+|---|---|---|---|
+| `perceivable.py` | 1 | **contrast (1.4.3, luminance math)**, alt text (1.1.1), headings/labels/tables (1.3.1), autoplay (1.4.2), resize/zoom (1.4.4) | media captions (1.2.x), sensory wording (1.3.3), use of color (1.4.1), images of text (1.4.5) |
+| `operable.py` | 2 | bypass (2.4.1), title (2.4.2), positive tabindex (2.4.3), link purpose (2.4.4), focus-visible suppression (2.4.7), mouse-only onclick (2.1.1) | keyboard operation, traps, timing, flashing, multiple ways |
+| `understandable.py` | 3 | page language (3.1.1), auto-context-change on input (3.2.2), control labels (3.3.2) | language of parts, predictability, error identification/prevention |
+| `robust.py` | 4 | duplicate ids (4.1.1), accessible name of every interactive element (4.1.2) | status-message live regions (4.1.3) |
+
+Shared foundation: `dom.py` (a dependency-free DOM), `color.py` (WCAG luminance),
+`base.py` (the uniform `Finding` record and the `Crew` base).
+
+## Install & run
+```
+pip install a11yhat            # once on PyPI
+python -m a11yhat page.html    # full POUR report, exit 1 on any FAIL
+python -m a11yhat page.html --json
+cat page.html | python -m a11yhat -
+```
+
+## Grounding
+Criteria, topics, and pass/fail conditions follow the **DHS Trusted Tester for Web
+(5.1.3)** process. Standard library only — nothing is installed into your
+environment. Automated checks catch the machine-decidable failures; the CHECK
+items are the ones a tester must confirm, each with the exact thing to review. It
+is an honest tool: it does the fast 80% and tells you precisely what the human 20%
+is — it does not pretend a scanner can certify a page.
+
+## License
+MIT. Copyright Vincent Gonzalez / F-Keys Creative LLC.
+
+## Tests
+`python -m unittest discover -s tests` — every deterministic check is proven to
+catch its defect and to clear on good input, and a clean page produces zero
+failures.

a11yhat-0.1.0/a11yhat.egg-info/SOURCES.txt

@@ -0,0 +1,19 @@
+LICENSE
+README.md
+pyproject.toml
+a11yhat/__init__.py
+a11yhat/__main__.py
+a11yhat/base.py
+a11yhat/color.py
+a11yhat/dom.py
+a11yhat/operable.py
+a11yhat/perceivable.py
+a11yhat/robust.py
+a11yhat/run.py
+a11yhat/understandable.py
+a11yhat.egg-info/PKG-INFO
+a11yhat.egg-info/SOURCES.txt
+a11yhat.egg-info/dependency_links.txt
+a11yhat.egg-info/entry_points.txt
+a11yhat.egg-info/top_level.txt
+tests/test_wcag.py

a11yhat-0.1.0/a11yhat.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

a11yhat-0.1.0/a11yhat.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+a11yhat = a11yhat.run:main

a11yhat-0.1.0/a11yhat.egg-info/top_level.txt

@@ -0,0 +1 @@
+a11yhat

a11yhat-0.1.0/pyproject.toml

@@ -0,0 +1,30 @@
+[build-system]
+requires = ["setuptools>=61"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "a11yhat"
+version = "0.1.0"
+description = "a11yhat: a WCAG 2.2 accessibility machine, structured by POUR — four crew leads, every success criterion a recorded check. A hardHats crew."
+readme = "README.md"
+requires-python = ">=3.9"
+authors = [{ name = "Vincent Gonzalez" }]
+keywords = ["accessibility", "wcag", "a11y", "section508", "audit", "pour"]
+license = "MIT"
+license-files = ["LICENSE"]
+classifiers = [
+  "Programming Language :: Python :: 3",
+  "Topic :: Software Development :: Quality Assurance",
+  "Operating System :: OS Independent",
+]
+dependencies = []
+
+[project.urls]
+Homepage = "https://github.com/vince-gonzalez/a11yhat"
+Repository = "https://github.com/vince-gonzalez/a11yhat"
+
+[project.scripts]
+a11yhat = "a11yhat.run:main"
+
+[tool.setuptools]
+packages = ["a11yhat"]

a11yhat-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

a11yhat-0.1.0/tests/test_wcag.py

@@ -0,0 +1,105 @@
+"""
+Self-test for the hardHats WCAG machine. Every deterministic check must catch its
+defect (FAIL on bad input) AND clear on good input (PASS). A compliance tool that
+cannot be shown to fail is not trustworthy.
+
+  python -m unittest discover -s tests
+"""
+import unittest
+
+from a11yhat.run import audit
+
+
+def status(html, sc):
+    for f in audit(html):
+        if f.sc == sc:
+            return f.status
+    return None
+
+
+WRAP = "<!doctype html><html lang='en'><head><title>T</title></head><body>{}</body></html>"
+
+
+class DeterministicChecks(unittest.TestCase):
+
+    def one(self, sc, bad_body, good_body, bad="FAIL", good="PASS"):
+        self.assertEqual(status(WRAP.format(bad_body), sc), bad, f"{sc} should {bad} on bad input")
+        self.assertEqual(status(WRAP.format(good_body), sc), good, f"{sc} should {good} on good input")
+
+    def test_111_img_alt(self):
+        self.one("1.1.1", "<img src=a.png>", "<img src=a.png alt='A red barn at dusk'>")
+
+    def test_131_heading_skip(self):
+        self.one("1.3.1", "<h1>a</h1><h3>b</h3>", "<h1>a</h1><h2>b</h2>")
+
+    def test_143_contrast(self):
+        self.one("1.4.3",
+                 "<p style='color:#777;background:#fff'>x</p>",
+                 "<p style='color:#000;background:#fff'>x</p>")
+
+    def test_142_autoplay(self):
+        self.one("1.4.2", "<video autoplay src=v.mp4></video>", "<video src=v.mp4></video>")
+
+    def test_241_bypass(self):
+        self.one("2.4.1", "<nav>n</nav><p>x</p>", "<main><p>x</p></main>")
+
+    def test_242_title(self):
+        # title lives in <head>; test full documents here
+        self.assertEqual(status("<html lang=en><head></head><body>x</body></html>", "2.4.2"), "FAIL")
+        self.assertEqual(status("<html lang=en><head><title>Hi</title></head><body>x</body></html>",
+                                "2.4.2"), "PASS")
+
+    def test_244_link_purpose(self):
+        self.one("2.4.4", "<a href=/x></a>", "<a href=/x>Annual accessibility report</a>")
+
+    def test_247_focus_visible(self):
+        self.one("2.4.7",
+                 "<style>:focus{outline:none}</style><a href=/x>x</a>",
+                 "<style>:focus{outline:2px solid blue}</style><a href=/x>x</a>")
+
+    def test_311_lang(self):
+        self.assertEqual(status("<html><head><title>t</title></head><body>x</body></html>",
+                                "3.1.1"), "FAIL")
+        self.assertEqual(status("<html lang=en><head><title>t</title></head><body>x</body></html>",
+                                "3.1.1"), "PASS")
+
+    def test_332_labels(self):
+        self.one("3.3.2",
+                 "<form><input type=text name=q></form>",
+                 "<form><label for=q>Search</label><input type=text id=q name=q></form>")
+
+    def test_411_dup_id(self):
+        self.one("4.1.1", "<span id=x></span><span id=x></span>", "<span id=x></span><span id=y></span>")
+
+    def test_412_name_role_value(self):
+        self.one("4.1.2", "<button></button>", "<button>Save</button>")
+
+
+class CleanPagePasses(unittest.TestCase):
+    """A well-built page must produce zero FAIL findings."""
+
+    CLEAN = """<!doctype html><html lang="en"><head><title>Accessible page</title>
+    <style>body{color:#111;background:#fff} :focus{outline:2px solid #005fcc}</style></head>
+    <body>
+      <a href="#main">Skip to content</a>
+      <nav>Navigation</nav>
+      <main id="main">
+        <h1>Welcome</h1>
+        <h2>About</h2>
+        <img src="barn.jpg" alt="A red barn at dusk">
+        <form>
+          <label for="email">Email address</label>
+          <input type="text" id="email" name="email" required>
+          <button type="submit">Subscribe</button>
+        </form>
+        <a href="/report">Read the annual accessibility report</a>
+      </main>
+    </body></html>"""
+
+    def test_no_failures(self):
+        fails = [f.sc for f in audit(self.CLEAN) if f.status == "FAIL"]
+        self.assertEqual(fails, [], f"clean page should have no failures, got: {fails}")
+
+
+if __name__ == "__main__":
+    unittest.main()