a11y-ad 0.1.0__tar.gz

a11y_ad-0.1.0/CHANGELOG.md

@@ -0,0 +1,8 @@
+# Changelog
+
+## 0.1.0 (2026-10-04)
+
+- Initial release: WCAG 4.1.2 accessible-name resolver (aria-labelledby,
+  aria-label, visible text, label[for], wrapping label, title, alt),
+  file/directory/URL scanning, JSON output, CI exit codes, stdlib-only.
+- Regression tests ported from the proven original implementation.

a11y_ad-0.1.0/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

a11y_ad-0.1.0/MANIFEST.in

@@ -0,0 +1,3 @@
+recursive-include tests *.py
+recursive-include tests/fixtures *.html
+include LICENSE README.md CHANGELOG.md

a11y_ad-0.1.0/PKG-INFO

@@ -0,0 +1,144 @@
+Metadata-Version: 2.4
+Name: a11y-ad
+Version: 0.1.0
+Summary: Browserless WCAG 4.1.2 accessible-name auditor for HTML — resolves aria labels, visible text, <label> bindings and titles, and reports every interactive element with no accessible name.
+Author: goun7
+License: Apache-2.0
+Project-URL: Homepage, https://github.com/goun7/a11y-ad
+Project-URL: Issues, https://github.com/goun7/a11y-ad/issues
+Project-URL: Changelog, https://github.com/goun7/a11y-ad/blob/main/CHANGELOG.md
+Keywords: accessibility,a11y,wcag,wcag22,aria,accessible-name,audit,cli,html,eaa
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Quality Assurance
+Classifier: Topic :: Text Processing :: Markup :: HTML
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# a11y-ad — browserless WCAG 4.1.2 accessible-name auditor
+
+`a11y-ad` audits HTML for **missing accessible names** (WCAG 4.1.2 / "Name,
+Role, Value") on every interactive element — no browser, no headless Chrome,
+stdlib only. Built for CI.
+
+## Why another accessibility tool?
+
+Most lightweight linters check *only* `aria-label`/`<label>` and flag every
+button with visible text as a critical failure. In one audit run against a
+fully-labelled application, a popular scanner reported **68 "critical" HTML
+accessible-name issues — 0 of them real**, because visible button text,
+`aria-labelledby`, and wrapping `<label>` elements are all valid accessible
+names.
+
+`a11y-ad` resolves the name the way assistive technology does, following the
+WCAG 4.1.2 resolution order:
+
+```
+aria-labelledby -> aria-label -> visible text -> <label for=id>
+-> wrapping <label> -> title -> alt (input[type=image])
+```
+
+and reports only the elements that end up with **no name at all**.
+
+## Scope (be honest about automated a11y coverage)
+
+Automated tools in general catch roughly 30–50% of WCAG issues; manual
+keyboard/screen-reader testing remains necessary. `a11y-ad` covers exactly
+one failure class — missing accessible names — and does it with zero false
+positives in the resolution cases above. Browser-measured checks (target
+size, focus visibility, contrast, reduced motion) are out of scope for the
+core; see Roadmap.
+
+## Install
+
+```bash
+pip install a11y-ad
+```
+
+## Usage
+
+```bash
+a11y-ad index.html            # single file
+a11y-ad src/                  # directory (recursive, *.html)
+a11y-ad https://example.com   # URL
+a11y-ad src/ --json           # machine-readable
+```
+
+Exit code is `1` when any interactive element lacks a name — use it as a CI
+gate:
+
+```yaml
+# GitHub Actions example
+- run: pip install a11y-ad && a11y-ad dist/
+```
+
+### JSON payload
+
+```json
+[
+  {
+    "target": "bad.html",
+    "total": 3,
+    "missing": ["line 3 <button >", "line 4 <input >"],
+    "sources": {"MISSING": 2, "text": 1},
+    "ok": false
+  }
+]
+```
+
+### Library
+
+```python
+from a11y_ad import audit, audit_file, audit_tree, fetch
+
+r = audit('<button aria-labelledby="h1">Edit</button>')
+r.ok            # True
+r.elements[0]   # Element(tag='button', name='...', source='aria-labelledby')
+r.missing       # elements with no accessible name
+```
+
+## Exclusions & semantics
+
+- `<a>` without `href` and `<input type="hidden">` are not interactive → skipped.
+- `aria-hidden="true"` counts as *named* (it is intentionally hidden from AT).
+- Elements whose visible text lives in a translation dictionary (filled at
+  runtime) will read as *statically* missing; audit the rendered DOM for the
+  final word (see Roadmap).
+
+## Security
+
+`fetch()` refuses non-http(s) schemes and any host resolving to a loopback,
+private, link-local, reserved or multicast address, so the library can be
+wired into "enter your URL" scan forms without handing callers a probe into
+the host network. The guard is best-effort (no DNS-rebinding defense) — for
+untrusted input at scale, front it with a proxy allowlist.
+
+## Roadmap
+
+- `--i18n` runtime layer: apply a key/value dictionary before auditing
+  (ported from the battle-tested original).
+- GitHub Action wrapper.
+- Browser-measured WCAG 2.2 checks (2.5.8 target size, 2.4.7 focus,
+  1.4.3 contrast) as an optional `[browser]` extra (Playwright).
+
+## Provenance
+
+The resolver is a hardened port of an auditor written for a production
+PWA, where four measurement bugs (void-tag stack shifting, early
+`</span>` closure bypassing a wrapping `<label>`, missing `label[for]`
+map, wrapping labels not recognized) were found via live measurement and
+fixed; their regression scenarios ship as tests in this repository.
+
+## License
+
+Apache-2.0

a11y_ad-0.1.0/README.md

@@ -0,0 +1,117 @@
+# a11y-ad — browserless WCAG 4.1.2 accessible-name auditor
+
+`a11y-ad` audits HTML for **missing accessible names** (WCAG 4.1.2 / "Name,
+Role, Value") on every interactive element — no browser, no headless Chrome,
+stdlib only. Built for CI.
+
+## Why another accessibility tool?
+
+Most lightweight linters check *only* `aria-label`/`<label>` and flag every
+button with visible text as a critical failure. In one audit run against a
+fully-labelled application, a popular scanner reported **68 "critical" HTML
+accessible-name issues — 0 of them real**, because visible button text,
+`aria-labelledby`, and wrapping `<label>` elements are all valid accessible
+names.
+
+`a11y-ad` resolves the name the way assistive technology does, following the
+WCAG 4.1.2 resolution order:
+
+```
+aria-labelledby -> aria-label -> visible text -> <label for=id>
+-> wrapping <label> -> title -> alt (input[type=image])
+```
+
+and reports only the elements that end up with **no name at all**.
+
+## Scope (be honest about automated a11y coverage)
+
+Automated tools in general catch roughly 30–50% of WCAG issues; manual
+keyboard/screen-reader testing remains necessary. `a11y-ad` covers exactly
+one failure class — missing accessible names — and does it with zero false
+positives in the resolution cases above. Browser-measured checks (target
+size, focus visibility, contrast, reduced motion) are out of scope for the
+core; see Roadmap.
+
+## Install
+
+```bash
+pip install a11y-ad
+```
+
+## Usage
+
+```bash
+a11y-ad index.html            # single file
+a11y-ad src/                  # directory (recursive, *.html)
+a11y-ad https://example.com   # URL
+a11y-ad src/ --json           # machine-readable
+```
+
+Exit code is `1` when any interactive element lacks a name — use it as a CI
+gate:
+
+```yaml
+# GitHub Actions example
+- run: pip install a11y-ad && a11y-ad dist/
+```
+
+### JSON payload
+
+```json
+[
+  {
+    "target": "bad.html",
+    "total": 3,
+    "missing": ["line 3 <button >", "line 4 <input >"],
+    "sources": {"MISSING": 2, "text": 1},
+    "ok": false
+  }
+]
+```
+
+### Library
+
+```python
+from a11y_ad import audit, audit_file, audit_tree, fetch
+
+r = audit('<button aria-labelledby="h1">Edit</button>')
+r.ok            # True
+r.elements[0]   # Element(tag='button', name='...', source='aria-labelledby')
+r.missing       # elements with no accessible name
+```
+
+## Exclusions & semantics
+
+- `<a>` without `href` and `<input type="hidden">` are not interactive → skipped.
+- `aria-hidden="true"` counts as *named* (it is intentionally hidden from AT).
+- Elements whose visible text lives in a translation dictionary (filled at
+  runtime) will read as *statically* missing; audit the rendered DOM for the
+  final word (see Roadmap).
+
+## Security
+
+`fetch()` refuses non-http(s) schemes and any host resolving to a loopback,
+private, link-local, reserved or multicast address, so the library can be
+wired into "enter your URL" scan forms without handing callers a probe into
+the host network. The guard is best-effort (no DNS-rebinding defense) — for
+untrusted input at scale, front it with a proxy allowlist.
+
+## Roadmap
+
+- `--i18n` runtime layer: apply a key/value dictionary before auditing
+  (ported from the battle-tested original).
+- GitHub Action wrapper.
+- Browser-measured WCAG 2.2 checks (2.5.8 target size, 2.4.7 focus,
+  1.4.3 contrast) as an optional `[browser]` extra (Playwright).
+
+## Provenance
+
+The resolver is a hardened port of an auditor written for a production
+PWA, where four measurement bugs (void-tag stack shifting, early
+`</span>` closure bypassing a wrapping `<label>`, missing `label[for]`
+map, wrapping labels not recognized) were found via live measurement and
+fixed; their regression scenarios ship as tests in this repository.
+
+## License
+
+Apache-2.0

a11y_ad-0.1.0/pyproject.toml

@@ -0,0 +1,45 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "a11y-ad"
+version = "0.1.0"
+description = "Browserless WCAG 4.1.2 accessible-name auditor for HTML — resolves aria labels, visible text, <label> bindings and titles, and reports every interactive element with no accessible name."
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "Apache-2.0" }
+authors = [{ name = "goun7" }]
+keywords = [
+  "accessibility", "a11y", "wcag", "wcag22", "aria",
+  "accessible-name", "audit", "cli", "html", "eaa",
+]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Environment :: Console",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: Apache Software License",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.9",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Topic :: Software Development :: Quality Assurance",
+  "Topic :: Text Processing :: Markup :: HTML",
+]
+dependencies = []
+
+[project.urls]
+Homepage = "https://github.com/goun7/a11y-ad"
+Issues = "https://github.com/goun7/a11y-ad/issues"
+Changelog = "https://github.com/goun7/a11y-ad/blob/main/CHANGELOG.md"
+
+[project.scripts]
+a11y-ad = "a11y_ad.cli:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

a11y_ad-0.1.0/setup.cfg

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

a11y_ad-0.1.0/src/a11y_ad/__init__.py

@@ -0,0 +1,11 @@
+"""a11y-ad — browserless WCAG 4.1.2 accessible-name auditor."""
+
+from .core import (AuditResult, Element, FetchError, audit, audit_file,
+                   audit_tree, fetch)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "AuditResult", "Element", "FetchError", "audit", "audit_file",
+    "audit_tree", "fetch", "__version__",
+]

a11y_ad-0.1.0/src/a11y_ad/cli.py

@@ -0,0 +1,77 @@
+"""CLI: `a11y-ad <file.html | directory | URL> ... [--json]`
+
+Exit codes (CI-friendly):
+    0 — every interactive element has an accessible name
+    1 — at least one missing name (or audit error)
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+from typing import List, Tuple
+
+from .core import AuditResult, audit_file, audit_tree, fetch
+
+
+def _collect(targets: List[str]) -> List[Tuple[str, AuditResult]]:
+    out: List[Tuple[str, AuditResult]] = []
+    for t in targets:
+        if t.startswith(("http://", "https://")):
+            out.append((t, fetch(t)))
+            continue
+        p = Path(t)
+        if p.is_dir():
+            for path, res in audit_tree(p).items():
+                out.append((str(path), res))
+        else:
+            out.append((str(p), audit_file(p)))
+    return out
+
+
+def _summary(label: str, res: AuditResult) -> str:
+    srcs = ", ".join("%s=%d" % kv for kv in sorted(res.sources.items()))
+    lines = ["%s: %d interactive element(s), %d without accessible name [%s]"
+             % (label, res.total, len(res.missing), srcs)]
+    lines += ["  MISSING " + e.describe() for e in res.missing[:10]]
+    if len(res.missing) > 10:
+        lines.append("  ... and %d more" % (len(res.missing) - 10))
+    return "\n".join(lines)
+
+
+def main(argv=None) -> int:
+    ap = argparse.ArgumentParser(
+        prog="a11y-ad",
+        description="Browserless WCAG 4.1.2 accessible-name auditor.")
+    ap.add_argument("targets", nargs="+",
+                    help="HTML file, directory (recursive *.html) or URL")
+    ap.add_argument("--json", action="store_true",
+                    help="machine-readable JSON output")
+    args = ap.parse_args(argv)
+
+    try:
+        results = _collect(args.targets)
+    except Exception as exc:  # noqa: BLE001 — CLI boundary
+        print("error: %s" % exc, file=sys.stderr)
+        return 1
+
+    if args.json:
+        payload = [{
+            "target": label,
+            "total": r.total,
+            "missing": [e.describe() for e in r.missing],
+            "sources": r.sources,
+            "ok": r.ok,
+        } for label, r in results]
+        print(json.dumps(payload, ensure_ascii=False, indent=2))
+    else:
+        for label, r in results:
+            print(_summary(label, r))
+
+    return 0 if all(r.ok for _, r in results) else 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

a11y_ad-0.1.0/src/a11y_ad/core.py

@@ -0,0 +1,309 @@
+"""a11y-ad — browserless WCAG 4.1.2 accessible-name auditor.
+
+Core resolver ported from an auditor built for a production PWA, where it
+was hardened against four measurement bugs recorded during development.
+Constraint notes from that port are kept inline.
+"""
+
+from __future__ import annotations
+
+import ipaddress
+import pathlib
+import socket
+import urllib.request
+import urllib.parse
+from dataclasses import dataclass, field
+from html.parser import HTMLParser
+from typing import Dict, List, Optional, Tuple
+
+__all__ = ["Element", "AuditResult", "audit", "audit_file", "audit_tree", "fetch"]
+
+INTERACTIVE = ("button", "a", "input", "select", "textarea")
+VOID = ("input", "img", "br", "hr", "meta", "link", "source", "area",
+        "base", "col", "embed", "param", "track", "wbr")
+SKIP = {"script", "style", "template"}
+
+# Source of an accessible name, in WCAG 4.1.2 resolution order.
+SRC_LABELLEDBY = "aria-labelledby"
+SRC_ARIA_LABEL = "aria-label"
+SRC_TEXT = "text"
+SRC_LABEL_FOR = "label[for]"
+SRC_WRAPPING_LABEL = "wrapping-label"
+SRC_TITLE = "title"
+SRC_ALT_IMAGE = "alt"
+SRC_HIDDEN = "aria-hidden"
+SRC_MISSING = "MISSING"
+
+
+@dataclass
+class Element:
+    """One interactive element and its resolved accessible name."""
+
+    tag: str
+    line: int
+    attrs: Dict[str, str]
+    name: str
+    source: str
+    # Stable key so two audit passes (e.g. pre/post runtime i18n) can be
+    # diffed: element order never changes when only text is injected.
+    @property
+    def key(self) -> Tuple[int, str, str]:
+        return (self.line, self.tag,
+                self.attrs.get("id") or self.attrs.get("aria-label") or "")
+
+    def describe(self) -> str:
+        hint = self.attrs.get("id") or self.attrs.get("aria-label") or ""
+        return "line %d <%s %s>" % (self.line, self.tag, hint)
+
+
+@dataclass
+class AuditResult:
+    total: int
+    elements: List[Element]
+    sources: Dict[str, int]
+    missing: List[Element] = field(default_factory=list)
+
+    @property
+    def ok(self) -> bool:
+        return not self.missing
+
+
+class _LabelFor(HTMLParser):
+    """Collects <label for="id">text</label> bindings."""
+
+    def __init__(self) -> None:
+        super().__init__(convert_charrefs=True)
+        self.target: Optional[str] = None
+        self.acc: List[str] = []
+        self.map: Dict[str, str] = {}
+
+    def handle_starttag(self, tag, attrs):
+        d = {k: (v or "") for k, v in attrs}
+        if tag == "label" and d.get("for"):
+            self.target = d["for"]
+            self.acc = []
+
+    def handle_endtag(self, tag):
+        if tag == "label" and self.target:
+            v = " ".join(x for x in self.acc if x).strip()
+            if v:
+                self.map[self.target] = v
+            self.target = None
+            self.acc = []
+
+    def handle_data(self, data):
+        if self.target:
+            self.acc.append(" ".join(data.split()))
+
+
+class _Parser(HTMLParser):
+    """Walks the HTML and captures every interactive element with context.
+
+    Measurement-bug notes (from the ported implementation):
+      #1 wrapping <label> must be recognised at all
+      #2 void tags (<input>) must NOT be pushed on the stack — they have
+         no close tag and would shift the <label> frame
+      #4 an `</span>` close tag must not close an open <label> early:
+         end-tag matching has to check BOTH the `tag` and `kind` fields
+    """
+
+    def __init__(self) -> None:
+        super().__init__(convert_charrefs=True)
+        self.elements: List[dict] = []
+        self.stack: List[dict] = []
+        self.wrapping: List[dict] = []
+        # generic (non-interactive) elements carrying an id, kept by
+        # reference: their text accumulates during parsing, so the
+        # id->text map must be resolved AFTER feed() completes.
+        self.id_nodes: Dict[str, dict] = {}
+
+    def handle_starttag(self, tag, attrs):
+        d = {k: (v or "") for k, v in attrs}
+        if tag in SKIP:
+            return
+        if tag == "label":
+            c = {"kind": "label", "texts": []}
+            self.wrapping.append(c)
+            self.stack.append(c)
+            return
+        if tag in INTERACTIVE:
+            n = {"tag": tag, "attrs": d, "texts": [],
+                 "line": self.getpos()[0],
+                 "wrapping": self.wrapping[-1] if self.wrapping else None}
+            self.elements.append(n)
+            if self.wrapping:
+                self.wrapping[-1].setdefault(
+                    "children", self.wrapping[-1].get("children", []) + [n])
+            if tag in VOID:  # bug #2
+                return
+            self.stack.append(n)
+            return
+        if tag in VOID:
+            alt = d.get("alt", "")
+            if alt:
+                for c in self.stack[-3:]:
+                    c.setdefault("alts", []).append(alt)
+            return
+        node = {"kind": tag, "texts": [], "attrs": d}
+        aid = d.get("id")
+        if aid:
+            self.id_nodes[aid] = node
+        self.stack.append(node)
+
+    def handle_data(self, data):
+        v = " ".join(data.split())
+        if not v:
+            return
+        # [-3:] lookback: text may live one or two inline elements deep
+        # (e.g. <button><span><b>Go</b></span></button>).
+        for c in self.stack[-3:]:
+            c["texts"].append(v)
+
+    def handle_endtag(self, tag):
+        # bug #4: match on tag AND kind, never pop past an open <label>.
+        while self.stack:
+            c = self.stack.pop()
+            if c.get("kind") == "label" and tag == "label":
+                if self.wrapping and self.wrapping[-1] is c:
+                    self.wrapping.pop()
+                break
+            if c.get("tag") == tag or c.get("kind") == tag:
+                break
+
+
+def _text_of(node: dict) -> str:
+    a = " ".join(x for x in node.get("texts", []) if x)
+    if node.get("alts"):
+        b = " ".join(x for x in node["alts"] if x)
+        a = (a + " " + b).strip()
+    return a
+
+
+def audit(html: str) -> AuditResult:
+    """Audit an HTML document for missing WCAG 4.1.2 accessible names.
+
+    Resolution order: aria-labelledby -> aria-label -> visible text ->
+    <label for=id> -> wrapping <label> -> title -> alt (input[type=image]).
+    Excluded from the audit: <a> without href, <input type=hidden>.
+    """
+    p = _Parser()
+    p.feed(html)
+    p.close()
+    lf = _LabelFor()
+    lf.feed(html)
+    lf.close()
+
+    # id -> accessible text, collected for EVERY element (not only
+    # interactive ones): aria-labelledby may point at a heading or span.
+    id_text: Dict[str, str] = {}
+    for e in p.elements:
+        if e["attrs"].get("id"):
+            id_text[e["attrs"]["id"]] = _text_of(e)
+    for aid, node in p.id_nodes.items():
+        if aid not in id_text:
+            id_text[aid] = _text_of(node)
+
+    total = 0
+    missing: List[Element] = []
+    sources: Dict[str, int] = {}
+    elements: List[Element] = []
+    for e in p.elements:
+        d = e["attrs"]
+        if e["tag"] == "a" and not d.get("href"):
+            continue
+        if e["tag"] == "input" and d.get("type") == "hidden":
+            continue
+        total += 1
+        source = SRC_MISSING
+        name = ""
+        if d.get("aria-hidden") == "true":
+            source = SRC_HIDDEN
+        elif d.get("aria-labelledby"):
+            parts = [id_text.get(x.strip(), "")
+                     for x in d["aria-labelledby"].split()]
+            joined = " ".join(x for x in parts if x).strip()
+            if joined:
+                source, name = SRC_LABELLEDBY, joined
+        elif d.get("aria-label"):
+            source, name = SRC_ARIA_LABEL, d["aria-label"]
+        elif _text_of(e):
+            source, name = SRC_TEXT, _text_of(e)
+        elif d.get("id") and d["id"] in lf.map:
+            source, name = SRC_LABEL_FOR, lf.map[d["id"]]
+        elif e.get("wrapping") is not None and _text_of(e["wrapping"]):
+            source, name = SRC_WRAPPING_LABEL, _text_of(e["wrapping"])
+        elif d.get("title"):
+            source, name = SRC_TITLE, d["title"]
+        elif (e["tag"] == "input" and d.get("type") == "image"
+              and d.get("alt")):
+            source, name = SRC_ALT_IMAGE, d["alt"]
+        sources[source] = sources.get(source, 0) + 1
+        el = Element(tag=e["tag"], line=e["line"], attrs=d,
+                     name=name, source=source)
+        elements.append(el)
+        if source == SRC_MISSING:
+            missing.append(el)
+    return AuditResult(total=total, elements=elements,
+                       sources=sources, missing=missing)
+
+
+def audit_file(path) -> AuditResult:
+    return audit(pathlib.Path(path).read_text(encoding="utf-8"))
+
+
+def audit_tree(root) -> Dict[pathlib.Path, AuditResult]:
+    """Audit every *.html file under a directory (recursive)."""
+    root = pathlib.Path(root)
+    return {p: audit_file(p) for p in sorted(root.rglob("*.html"))}
+
+
+class FetchError(ValueError):
+    """Raised when a URL is refused by the SSRF guard."""
+
+
+def _guard_url(url: str) -> str:
+    """Refuse URLs that could reach internal/private infrastructure.
+
+    fetch() is safe on a developer CLI, but this library is also used by
+    web frontends ("enter your URL" scan forms). There, an unguarded
+    fetch would let a caller probe localhost, link-local metadata
+    endpoints, or the private network behind the server.
+    """
+    parsed = urllib.parse.urlparse(url)
+    if parsed.scheme not in ("http", "https"):
+        raise FetchError("only http(s) URLs are allowed, got %r" % parsed.scheme)
+    host = parsed.hostname
+    if not host:
+        raise FetchError("URL without host")
+    if host in ("localhost",) or host.endswith((".local", ".internal", ".home")):
+        raise FetchError("refusing internal hostname %r" % host)
+    try:
+        infos = socket.getaddrinfo(host, None)
+    except socket.gaierror as exc:
+        raise FetchError("cannot resolve host %r: %s" % (host, exc))
+    seen: set = set()
+    for info in infos:
+        ip = ipaddress.ip_address(info[4][0])
+        if ip in seen:
+            continue
+        seen.add(ip)
+        if (ip.is_private or ip.is_loopback or ip.is_link_local
+                or ip.is_reserved or ip.is_multicast or ip.is_unspecified):
+            raise FetchError(
+                "refusing to fetch private/reserved address %s (host %r)"
+                % (ip, host))
+    return url
+
+
+def fetch(url: str) -> AuditResult:
+    """Fetch a URL over HTTP(S) and audit the response body.
+
+    Refuses non-http(s) schemes and any host resolving to a loopback,
+    private, link-local, reserved or multicast address (SSRF guard).
+    Best-effort: DNS-rebinding TOCTOU is not defended against — never
+    expose fetch() to untrusted input without a proxy allowlist.
+    """
+    _guard_url(url)
+    req = urllib.request.Request(url, headers={"User-Agent": "a11y-ad/0.1"})
+    with urllib.request.urlopen(req, timeout=30) as r:
+        return audit(r.read().decode("utf-8", errors="replace"))

a11y_ad-0.1.0/src/a11y_ad.egg-info/PKG-INFO

@@ -0,0 +1,144 @@
+Metadata-Version: 2.4
+Name: a11y-ad
+Version: 0.1.0
+Summary: Browserless WCAG 4.1.2 accessible-name auditor for HTML — resolves aria labels, visible text, <label> bindings and titles, and reports every interactive element with no accessible name.
+Author: goun7
+License: Apache-2.0
+Project-URL: Homepage, https://github.com/goun7/a11y-ad
+Project-URL: Issues, https://github.com/goun7/a11y-ad/issues
+Project-URL: Changelog, https://github.com/goun7/a11y-ad/blob/main/CHANGELOG.md
+Keywords: accessibility,a11y,wcag,wcag22,aria,accessible-name,audit,cli,html,eaa
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Quality Assurance
+Classifier: Topic :: Text Processing :: Markup :: HTML
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# a11y-ad — browserless WCAG 4.1.2 accessible-name auditor
+
+`a11y-ad` audits HTML for **missing accessible names** (WCAG 4.1.2 / "Name,
+Role, Value") on every interactive element — no browser, no headless Chrome,
+stdlib only. Built for CI.
+
+## Why another accessibility tool?
+
+Most lightweight linters check *only* `aria-label`/`<label>` and flag every
+button with visible text as a critical failure. In one audit run against a
+fully-labelled application, a popular scanner reported **68 "critical" HTML
+accessible-name issues — 0 of them real**, because visible button text,
+`aria-labelledby`, and wrapping `<label>` elements are all valid accessible
+names.
+
+`a11y-ad` resolves the name the way assistive technology does, following the
+WCAG 4.1.2 resolution order:
+
+```
+aria-labelledby -> aria-label -> visible text -> <label for=id>
+-> wrapping <label> -> title -> alt (input[type=image])
+```
+
+and reports only the elements that end up with **no name at all**.
+
+## Scope (be honest about automated a11y coverage)
+
+Automated tools in general catch roughly 30–50% of WCAG issues; manual
+keyboard/screen-reader testing remains necessary. `a11y-ad` covers exactly
+one failure class — missing accessible names — and does it with zero false
+positives in the resolution cases above. Browser-measured checks (target
+size, focus visibility, contrast, reduced motion) are out of scope for the
+core; see Roadmap.
+
+## Install
+
+```bash
+pip install a11y-ad
+```
+
+## Usage
+
+```bash
+a11y-ad index.html            # single file
+a11y-ad src/                  # directory (recursive, *.html)
+a11y-ad https://example.com   # URL
+a11y-ad src/ --json           # machine-readable
+```
+
+Exit code is `1` when any interactive element lacks a name — use it as a CI
+gate:
+
+```yaml
+# GitHub Actions example
+- run: pip install a11y-ad && a11y-ad dist/
+```
+
+### JSON payload
+
+```json
+[
+  {
+    "target": "bad.html",
+    "total": 3,
+    "missing": ["line 3 <button >", "line 4 <input >"],
+    "sources": {"MISSING": 2, "text": 1},
+    "ok": false
+  }
+]
+```
+
+### Library
+
+```python
+from a11y_ad import audit, audit_file, audit_tree, fetch
+
+r = audit('<button aria-labelledby="h1">Edit</button>')
+r.ok            # True
+r.elements[0]   # Element(tag='button', name='...', source='aria-labelledby')
+r.missing       # elements with no accessible name
+```
+
+## Exclusions & semantics
+
+- `<a>` without `href` and `<input type="hidden">` are not interactive → skipped.
+- `aria-hidden="true"` counts as *named* (it is intentionally hidden from AT).
+- Elements whose visible text lives in a translation dictionary (filled at
+  runtime) will read as *statically* missing; audit the rendered DOM for the
+  final word (see Roadmap).
+
+## Security
+
+`fetch()` refuses non-http(s) schemes and any host resolving to a loopback,
+private, link-local, reserved or multicast address, so the library can be
+wired into "enter your URL" scan forms without handing callers a probe into
+the host network. The guard is best-effort (no DNS-rebinding defense) — for
+untrusted input at scale, front it with a proxy allowlist.
+
+## Roadmap
+
+- `--i18n` runtime layer: apply a key/value dictionary before auditing
+  (ported from the battle-tested original).
+- GitHub Action wrapper.
+- Browser-measured WCAG 2.2 checks (2.5.8 target size, 2.4.7 focus,
+  1.4.3 contrast) as an optional `[browser]` extra (Playwright).
+
+## Provenance
+
+The resolver is a hardened port of an auditor written for a production
+PWA, where four measurement bugs (void-tag stack shifting, early
+`</span>` closure bypassing a wrapping `<label>`, missing `label[for]`
+map, wrapping labels not recognized) were found via live measurement and
+fixed; their regression scenarios ship as tests in this repository.
+
+## License
+
+Apache-2.0

a11y_ad-0.1.0/src/a11y_ad.egg-info/SOURCES.txt

@@ -0,0 +1,18 @@
+CHANGELOG.md
+LICENSE
+MANIFEST.in
+README.md
+pyproject.toml
+src/a11y_ad/__init__.py
+src/a11y_ad/cli.py
+src/a11y_ad/core.py
+src/a11y_ad.egg-info/PKG-INFO
+src/a11y_ad.egg-info/SOURCES.txt
+src/a11y_ad.egg-info/dependency_links.txt
+src/a11y_ad.egg-info/entry_points.txt
+src/a11y_ad.egg-info/top_level.txt
+tests/test_cli.py
+tests/test_core.py
+tests/test_guard.py
+tests/fixtures/bad.html
+tests/fixtures/good.html

a11y_ad-0.1.0/src/a11y_ad.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

a11y_ad-0.1.0/src/a11y_ad.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+a11y-ad = a11y_ad.cli:main

a11y_ad-0.1.0/src/a11y_ad.egg-info/top_level.txt

@@ -0,0 +1 @@
+a11y_ad

a11y_ad-0.1.0/tests/fixtures/bad.html

@@ -0,0 +1,6 @@
+<!doctype html>
+<html><body>
+<button><svg viewBox="0 0 8 8"></svg></button>
+<input type="text">
+<a href="/ok">All good link</a>
+</body></html>

a11y_ad-0.1.0/tests/fixtures/good.html

@@ -0,0 +1,8 @@
+<!doctype html>
+<html><body>
+<button>Save changes</button>
+<input id="mail" type="email">
+<label for="mail">E-mail address</label>
+<label>Accept<input type="checkbox"></label>
+<button aria-label="Close">X</button>
+</body></html>

a11y_ad-0.1.0/tests/test_cli.py

@@ -0,0 +1,44 @@
+"""CLI tests: exit codes, JSON payload, directory scanning."""
+
+import json
+from pathlib import Path
+
+import pytest
+
+from a11y_ad.cli import main
+
+FIXTURES = Path(__file__).parent / "fixtures"
+
+
+def test_clean_file_exits_zero(capsys):
+    assert main([str(FIXTURES / "good.html")]) == 0
+    out = capsys.readouterr().out
+    assert "0 without accessible name" in out
+
+
+def test_dirty_file_exits_one(capsys):
+    assert main([str(FIXTURES / "bad.html")]) == 1
+    out = capsys.readouterr().out
+    assert "MISSING" in out
+
+
+def test_directory_scan_and_json(capsys):
+    rc = main([str(FIXTURES), "--json"])
+    payload = json.loads(capsys.readouterr().out)
+    names = {Path(p["target"]).name for p in payload}
+    assert names == {"good.html", "bad.html"}
+    bad = next(p for p in payload if p["target"].endswith("bad.html"))
+    assert bad["ok"] is False and bad["total"] == 3 and len(bad["missing"]) == 2
+    good = next(p for p in payload if p["target"].endswith("good.html"))
+    assert good["ok"] is True
+    assert rc == 1  # one of the files is dirty
+
+
+def test_missing_file_is_error(capsys):
+    assert main(["/nonexistent/x.html"]) == 1
+    assert "error" in capsys.readouterr().err
+
+
+@pytest.mark.parametrize("fixture", ["good.html", "bad.html"])
+def test_fixture_files_exist(fixture):
+    assert (FIXTURES / fixture).is_file()

a11y_ad-0.1.0/tests/test_core.py

@@ -0,0 +1,131 @@
+"""a11y-ad core tests — includes regression scenarios ported from the
+original production-PWA implementation, where four measurement bugs were
+found and fixed during development (see PLAN.md in that project).
+"""
+
+from a11y_ad import audit
+
+# ---------------------------------------------------------------- named
+
+
+def test_visible_text():
+    r = audit("<button>Save</button>")
+    assert r.total == 1 and r.ok
+    assert r.elements[0].source == "text"
+    assert r.elements[0].name == "Save"
+
+
+def test_nested_inline_text():
+    # text may sit two inline elements deep ([-3:] lookback)
+    r = audit("<button><span><b>Go</b></span></button>")
+    assert r.ok and r.elements[0].source == "text"
+
+
+def test_aria_label():
+    r = audit('<button aria-label="Close dialog">X</button>')
+    assert r.ok
+    assert r.elements[0].source == "aria-label"
+    assert r.elements[0].name == "Close dialog"
+
+
+def test_aria_labelledby_points_at_heading():
+    # aria-labelledby may reference a NON-interactive element (a heading):
+    # the id->text map must cover every element, not only interactive ones.
+    html = ('<h3 id="sec1">Account settings</h3>'
+            '<button aria-labelledby="sec1">Edit</button>')
+    r = audit(html)
+    assert r.ok
+    assert r.elements[0].source == "aria-labelledby"
+    assert r.elements[0].name == "Account settings"
+
+
+def test_label_for():
+    html = ('<input id="email" type="text">'
+            '<label for="email">Your e-mail</label>')
+    r = audit(html)
+    assert r.ok
+    assert r.elements[0].source == "label[for]"
+    assert r.elements[0].name == "Your e-mail"
+
+
+def test_wrapping_label():
+    html = "<label>Newsletter<input type=\"checkbox\"></label>"
+    r = audit(html)
+    assert r.ok
+    assert r.elements[0].source == "wrapping-label"
+
+
+def test_title_fallback():
+    r = audit('<button title="Print page"><svg></svg></button>')
+    assert r.ok
+    assert r.elements[0].source == "title"
+
+
+def test_input_image_alt():
+    r = audit('<input type="image" alt="Search" src="s.png">')
+    assert r.ok
+    assert r.elements[0].source == "alt"
+
+
+def test_aria_hidden_counted_as_named():
+    r = audit('<button aria-hidden="true">::</button>')
+    assert r.ok
+    assert r.elements[0].source == "aria-hidden"
+
+
+# ---------------------------------------------------------------- missing
+
+
+def test_missing_button():
+    r = audit("<button><svg></svg></button>")
+    assert not r.ok
+    assert r.missing[0].tag == "button"
+    assert r.missing[0].describe().startswith("line 1 <button")
+
+
+def test_exclusions():
+    html = ('<input type="hidden" value="x">'
+            '<a id="nohref">plain anchor</a>')
+    r = audit(html)
+    assert r.total == 0  # both excluded
+
+
+# ------------------------------------------------- ported regressions
+
+
+def test_void_tag_does_not_shift_label_frame():
+    # original bug #2/#3: <input> is void; if it were pushed on the
+    # stack the later <label> frame would be lost and the input would
+    # falsely read as missing.
+    html = ('<form><input id="q" type="text"></form>'
+            '<label for="q">Search term</label>')
+    r = audit(html)
+    assert r.ok and r.elements[0].source == "label[for]"
+
+
+def test_span_close_does_not_close_label_early():
+    # original bug #4: </span> inside a label must not pop the label
+    # off the stack; the input after it still resolves to the wrapping
+    # label text.
+    html = ("<label>Accept terms<span> (required)</span>"
+            "<input type=\"checkbox\"></label>")
+    r = audit(html)
+    assert r.ok
+    assert r.elements[0].source == "wrapping-label"
+
+
+def test_negative_control_text_really_counts():
+    # if the auditor counted nothing, stripping the visible text would
+    # not change the result — guard against vacuous green.
+    good = audit("<button>Save</button>")
+    bad = audit("<button></button>")
+    assert good.ok and not bad.ok
+    assert len(bad.missing) - len(good.missing) >= 1
+
+
+def test_sources_breakdown():
+    html = ('<button>A</button><button aria-label="B">x</button>'
+            "<button></button>")
+    r = audit(html)
+    assert r.total == 3
+    assert r.sources == {"text": 1, "aria-label": 1, "MISSING": 1}

a11y_ad-0.1.0/tests/test_guard.py

@@ -0,0 +1,36 @@
+"""SSRF guard tests — fetch() must refuse internal/private targets."""
+
+import pytest
+
+from a11y_ad import FetchError
+from a11y_ad.core import _guard_url
+
+
+@pytest.mark.parametrize("url", [
+    "file:///etc/passwd",
+    "ftp://example.com/x.html",
+    "javascript:alert(1)",
+    "http://localhost/x",
+    "http://localhost:8080/admin",
+    "http://127.0.0.1/x",
+    "http://0.0.0.0/x",
+    "http://169.254.169.254/latest/meta-data/",
+    "http://10.0.0.1/x",
+    "http://192.168.1.10/x",
+    "http://172.16.0.5/x",
+    "http://[::1]/x",
+    "http://metadata.internal/x",
+    "http://printer.local/x",
+])
+def test_guard_refuses_internal_targets(url):
+    with pytest.raises(FetchError):
+        _guard_url(url)
+
+
+def test_guard_accepts_public_url():
+    assert _guard_url("https://example.com/") == "https://example.com/"
+
+
+def test_guard_rejects_unresolvable_host():
+    with pytest.raises(FetchError):
+        _guard_url("https://this-host-does-not-exist-a11y-ad.invalid/")