legible 0.1.0__tar.gz

legible-0.1.0/PKG-INFO

@@ -0,0 +1,135 @@
+Metadata-Version: 2.4
+Name: legible
+Version: 0.1.0
+Summary: Three build gates for things a linter will not catch: type below a readable floor, colour that cannot be read on the surface it sits on, and a retired name reaching anything a human reads.
+Author-email: Vincent Gonzalez <hello@f-keys.com>
+License: MIT
+Project-URL: Homepage, https://f-keys.com/legible/
+Project-URL: Source, https://github.com/vince-gonzalez/f-keys/tree/main/gatekit
+Project-URL: Issues, https://github.com/vince-gonzalez/f-keys/issues
+Keywords: accessibility,a11y,wcag,contrast,font-size,ci,build-gate,linter,deadname,rename
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Quality Assurance
+Classifier: Topic :: Software Development :: Testing
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+
+```
+╔════════════════════════════════════════════════════════════════════════════════════════════╗
+║                                                                                            ║
+║                    ██████╗  █████╗ ████████╗███████╗██╗  ██╗██╗████████╗                   ║
+║                   ██╔════╝ ██╔══██╗╚══██╔══╝██╔════╝██║ ██╔╝██║╚══██╔══╝                   ║
+║                   ██║  ███╗███████║   ██║   █████╗  █████╔╝ ██║   ██║                      ║
+║                   ██║   ██║██╔══██║   ██║   ██╔══╝  ██╔═██╗ ██║   ██║                      ║
+║                   ╚██████╔╝██║  ██║   ██║   ███████╗██║  ██╗██║   ██║                      ║
+║                    ╚═════╝ ╚═╝  ╚═╝   ╚═╝   ╚══════╝╚═╝  ╚═╝╚═╝   ╚═╝                      ║
+║                                                                                            ║
+║                           three gates a linter will not give you                           ║
+║                                                                                            ║
+╚════════════════════════════════════════════════════════════════════════════════════════════╝
+```
+Three gates for defects a linter does not have an opinion about, because
+none of them is a syntax error. Each one exists because a real person read
+something and could not.
+
+| Gate | Fails the build when |
+|---|---|
+| `typefloor` | Type is declared below a readable floor (13px by default) |
+| `contrast-gate` | A declared colour cannot reach 4.5:1 on any surface the file also declares |
+| `deadname-gate` | A retired name reaches anything a human reads |
+
+## Install
+
+```
+pip install legible
+```
+
+## Use
+
+```
+typefloor ./src                  # every CSS and inline declaration
+contrast-gate ./src              # WCAG 4.5:1 against declared surfaces
+deadname-gate ./src              # a name that should be gone
+```
+
+Each exits non-zero on a finding and prints the file and line. `--list`
+shows every offender rather than the summary.
+
+## Why these three
+
+**typefloor.** Six-point type is not a style choice. This was written after
+the same reader reported the same thing more than once, and the first time it
+was pointed at a folder it found every violation immediately — what was
+missing was never the tool, it was anything that pulled it.
+
+**contrast-gate.** It reads CSS custom properties — `--ink: #hex` against
+`--bg: #hex` — and reports the best surface each ink can reach. Dark grey on
+navy measured 2.64:1 where body text needs 4.5, and a person found that, not
+a build.
+
+It does **not** read literal `color:` declarations. A stylesheet using
+neither has nothing to compare, and it says so and exits 0 — which in CI
+reads as a pass on a site nobody checked. Pass `--require-pairs` to fail
+instead when nothing was found. The Action sets it.
+
+**deadname-gate.** Fails a build when a name that should be gone reaches a
+title, a footer, a byline, alt text or a comment — while leaving machine
+identifiers alone, because renaming a repository path or a published
+artifact breaks working links or contradicts a deposited record. Both halves
+matter: a gate that cannot tell those apart gets switched off.
+
+Written for a company rename. It is the same shape as the problem of a person
+changing their name and finding it in three hundred places, which is the
+harder version and the one worth getting right.
+
+## Exit codes
+
+| Code | Means |
+|---|---|
+| `0` | Clean |
+| `1` | It found something. The file and line are printed. |
+| `2` | Misconfigured — it could not check, and will not report clean |
+
+The third one matters. `deadname-gate` forbids nothing out of the box, so a
+fresh install exits **2** with an explanation rather than **0**. A gate that
+reports a pass while checking nothing is worse than no gate, and every one of
+these three shipped a version that did exactly that before it was caught.
+
+## Configuration
+
+Each gate reads a JSON file of exceptions, so a deliberate choice is
+recorded with a reason rather than silently re-flagged.
+
+```
+typefloor ./src --config typefloor.json
+contrast-gate ./src --config contrast.json
+deadname-gate ./src --config deadname_gate.json
+```
+
+`TYPEFLOOR_CONFIG`, `CONTRAST_CONFIG` and `DEADNAME_CONFIG` do the same.
+
+## In CI
+
+```yaml
+- run: pip install legible
+- run: typefloor ./src
+- run: contrast-gate ./src --require-pairs
+- run: deadname-gate ./src
+```
+
+There are Actions too, in `.github/actions/` of the source repository.
+
+## A note on the argument
+
+An earlier version ignored a bare path and scanned its own directory
+instead, then printed `OK`. A gate that reports a pass on a tree it never
+opened is worse than no gate, so a positional path is now the root. If you
+pinned an earlier build, check what it is actually reading.
+
+## Licence
+
+MIT.

legible-0.1.0/README.md

@@ -0,0 +1,115 @@
+```
+╔════════════════════════════════════════════════════════════════════════════════════════════╗
+║                                                                                            ║
+║                    ██████╗  █████╗ ████████╗███████╗██╗  ██╗██╗████████╗                   ║
+║                   ██╔════╝ ██╔══██╗╚══██╔══╝██╔════╝██║ ██╔╝██║╚══██╔══╝                   ║
+║                   ██║  ███╗███████║   ██║   █████╗  █████╔╝ ██║   ██║                      ║
+║                   ██║   ██║██╔══██║   ██║   ██╔══╝  ██╔═██╗ ██║   ██║                      ║
+║                   ╚██████╔╝██║  ██║   ██║   ███████╗██║  ██╗██║   ██║                      ║
+║                    ╚═════╝ ╚═╝  ╚═╝   ╚═╝   ╚══════╝╚═╝  ╚═╝╚═╝   ╚═╝                      ║
+║                                                                                            ║
+║                           three gates a linter will not give you                           ║
+║                                                                                            ║
+╚════════════════════════════════════════════════════════════════════════════════════════════╝
+```
+Three gates for defects a linter does not have an opinion about, because
+none of them is a syntax error. Each one exists because a real person read
+something and could not.
+
+| Gate | Fails the build when |
+|---|---|
+| `typefloor` | Type is declared below a readable floor (13px by default) |
+| `contrast-gate` | A declared colour cannot reach 4.5:1 on any surface the file also declares |
+| `deadname-gate` | A retired name reaches anything a human reads |
+
+## Install
+
+```
+pip install legible
+```
+
+## Use
+
+```
+typefloor ./src                  # every CSS and inline declaration
+contrast-gate ./src              # WCAG 4.5:1 against declared surfaces
+deadname-gate ./src              # a name that should be gone
+```
+
+Each exits non-zero on a finding and prints the file and line. `--list`
+shows every offender rather than the summary.
+
+## Why these three
+
+**typefloor.** Six-point type is not a style choice. This was written after
+the same reader reported the same thing more than once, and the first time it
+was pointed at a folder it found every violation immediately — what was
+missing was never the tool, it was anything that pulled it.
+
+**contrast-gate.** It reads CSS custom properties — `--ink: #hex` against
+`--bg: #hex` — and reports the best surface each ink can reach. Dark grey on
+navy measured 2.64:1 where body text needs 4.5, and a person found that, not
+a build.
+
+It does **not** read literal `color:` declarations. A stylesheet using
+neither has nothing to compare, and it says so and exits 0 — which in CI
+reads as a pass on a site nobody checked. Pass `--require-pairs` to fail
+instead when nothing was found. The Action sets it.
+
+**deadname-gate.** Fails a build when a name that should be gone reaches a
+title, a footer, a byline, alt text or a comment — while leaving machine
+identifiers alone, because renaming a repository path or a published
+artifact breaks working links or contradicts a deposited record. Both halves
+matter: a gate that cannot tell those apart gets switched off.
+
+Written for a company rename. It is the same shape as the problem of a person
+changing their name and finding it in three hundred places, which is the
+harder version and the one worth getting right.
+
+## Exit codes
+
+| Code | Means |
+|---|---|
+| `0` | Clean |
+| `1` | It found something. The file and line are printed. |
+| `2` | Misconfigured — it could not check, and will not report clean |
+
+The third one matters. `deadname-gate` forbids nothing out of the box, so a
+fresh install exits **2** with an explanation rather than **0**. A gate that
+reports a pass while checking nothing is worse than no gate, and every one of
+these three shipped a version that did exactly that before it was caught.
+
+## Configuration
+
+Each gate reads a JSON file of exceptions, so a deliberate choice is
+recorded with a reason rather than silently re-flagged.
+
+```
+typefloor ./src --config typefloor.json
+contrast-gate ./src --config contrast.json
+deadname-gate ./src --config deadname_gate.json
+```
+
+`TYPEFLOOR_CONFIG`, `CONTRAST_CONFIG` and `DEADNAME_CONFIG` do the same.
+
+## In CI
+
+```yaml
+- run: pip install legible
+- run: typefloor ./src
+- run: contrast-gate ./src --require-pairs
+- run: deadname-gate ./src
+```
+
+There are Actions too, in `.github/actions/` of the source repository.
+
+## A note on the argument
+
+An earlier version ignored a bare path and scanned its own directory
+instead, then printed `OK`. A gate that reports a pass on a tree it never
+opened is worse than no gate, so a positional path is now the root. If you
+pinned an earlier build, check what it is actually reading.
+
+## Licence
+
+MIT.

legible-0.1.0/pyproject.toml

@@ -0,0 +1,42 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "legible"
+version = "0.1.0"
+description = "Three build gates for things a linter will not catch: type below a readable floor, colour that cannot be read on the surface it sits on, and a retired name reaching anything a human reads."
+readme = "README.md"
+requires-python = ">=3.8"
+license = { text = "MIT" }
+authors = [{ name = "Vincent Gonzalez", email = "hello@f-keys.com" }]
+keywords = [
+    "accessibility", "a11y", "wcag", "contrast", "font-size",
+    "ci", "build-gate", "linter", "deadname", "rename",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Topic :: Software Development :: Quality Assurance",
+    "Topic :: Software Development :: Testing",
+]
+dependencies = []
+
+[project.urls]
+Homepage = "https://f-keys.com/legible/"
+Source = "https://github.com/vince-gonzalez/f-keys/tree/main/gatekit"
+Issues = "https://github.com/vince-gonzalez/f-keys/issues"
+
+[project.scripts]
+typefloor = "gatekit.typefloor:main"
+contrast-gate = "gatekit.contrast:main"
+deadname-gate = "gatekit.deadname_gate:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+gatekit = ["*.json"]

legible-0.1.0/setup.cfg

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

legible-0.1.0/src/gatekit/contrast.json

@@ -0,0 +1,5 @@
+{
+  "floor": 4.5,
+  "exceptions": [],
+  "_comment": "Exceptions are yours to record, with a reason. The default list is empty on purpose."
+}

legible-0.1.0/src/gatekit/contrast.py

@@ -0,0 +1,264 @@
+#!/usr/bin/env python3
+"""
+============================================================
+contrast - nothing on a page may be unreadable
+F-Keys | www.f-keys.com
+------------------------------------------------------------
+WHY THIS EXISTS
+
+"Dark grey on navy" has been reported by the person who has to
+read it more than once, which makes it a class of defect
+rather than a mistake. typefloor.py already stops type being
+too small; this stops it being the wrong colour, by the same
+method: measure it, fail the build, and stop relying on
+anybody noticing.
+
+WHAT IT MEASURES
+
+The WCAG 2.1 contrast ratio between every colour a stylesheet
+declares and the surface it is drawn on. A ratio is a number
+between 1 (invisible) and 21 (black on white).
+
+  4.5   the floor for body text
+  3.0   large text, 24px or 19px bold
+
+THE RULE, AND WHY IT IS THIS ONE
+
+Comparing every ink against every surface flags pairs that
+never occur together - a green meant for a black readout is
+not a defect because it would be illegible on chrome. So each
+ink has to reach the floor on at least ONE declared surface.
+An ink that fails against all of them has nowhere it can
+legitimately be used, which is exactly the "dark grey on
+navy" case this exists for.
+
+WHAT IT CANNOT SEE
+
+A colour applied by script at runtime, and a colour whose
+surface is decided by a parent this cannot resolve. Pairings
+are read from the custom properties a file declares, which is
+how these stylesheets are written; anything set inline in JS
+is out of reach and stays that way rather than being guessed
+at.
+
+  python tools/contrast.py                 report; exit 1 if any pair fails
+  python tools/contrast.py --list          every pair, passing or not
+  python tools/contrast.py --root remapwrap
+
+Pairs that must stay below the floor go in tools/contrast.json
+with a reason, the same as typefloor.
+============================================================
+"""
+
+import json
+import os
+import re
+import sys
+
+try:
+    sys.stdout.reconfigure(encoding="utf-8", errors="replace")
+except (AttributeError, ValueError):
+    pass
+
+HERE = os.path.dirname(os.path.abspath(__file__))
+def _config():
+    if "--config" in sys.argv:
+        i = sys.argv.index("--config")
+        if i + 1 < len(sys.argv):
+            return os.path.abspath(sys.argv[i + 1])
+    return os.environ.get("CONTRAST_CONFIG") or os.path.join(HERE, "contrast.json")
+
+
+CONFIG = _config()
+
+#: Which variables name a surface something is drawn on. Everything else
+#: that looks like a colour is treated as ink.
+SURFACES = ("bg", "background", "panel", "surface", "paper", "card",
+            "field", "sel", "face", "desktop", "title-b")
+
+SKIP_DIRS = {"node_modules", ".git", "dist", "build", "__pycache__",
+             "vendor", ".venv", "fonts", "assets"}
+
+
+def load_config():
+    if not os.path.exists(CONFIG):
+        return {"floor": 4.5, "exceptions": []}
+    with open(CONFIG, encoding="utf-8") as fh:
+        cfg = json.load(fh)
+    cfg.setdefault("floor", 4.5)
+    cfg.setdefault("exceptions", [])
+    return cfg
+
+
+def to_rgb(value):
+    v = value.strip().lower()
+    m = re.match(r"^#([0-9a-f]{3,8})$", v)
+    if m:
+        h = m.group(1)
+        if len(h) == 3:
+            h = "".join(c * 2 for c in h)
+        if len(h) < 6:
+            return None
+        return tuple(int(h[i:i + 2], 16) for i in (0, 2, 4))
+    m = re.match(r"^rgba?\(([^)]+)\)$", v)
+    if m:
+        parts = [p.strip() for p in m.group(1).replace("/", ",").split(",")]
+        try:
+            return tuple(int(float(p)) for p in parts[:3])
+        except ValueError:
+            return None
+    return None
+
+
+def luminance(rgb):
+    out = []
+    for c in rgb:
+        c = c / 255.0
+        out.append(c / 12.92 if c <= 0.03928 else ((c + 0.055) / 1.055) ** 2.4)
+    return 0.2126 * out[0] + 0.7152 * out[1] + 0.0722 * out[2]
+
+
+def ratio(a, b):
+    la, lb = luminance(a), luminance(b)
+    hi, lo = max(la, lb), min(la, lb)
+    return (hi + 0.05) / (lo + 0.05)
+
+
+def variables(text):
+    """Every --name: value the file declares."""
+    out = {}
+    for name, value in re.findall(r"--([\w-]+)\s*:\s*([^;}]+)[;}]", text):
+        rgb = to_rgb(value)
+        if rgb:
+            out[name] = rgb
+    return out
+
+
+def walk(root):
+    for base, dirs, files in os.walk(root):
+        dirs[:] = [d for d in dirs if d not in SKIP_DIRS and not d.startswith(".")]
+        for name in files:
+            if name.lower().endswith((".html", ".css")):
+                yield os.path.join(base, name)
+
+
+def check(root, cfg):
+    floor = cfg["floor"]
+    allowed = {(e.get("ink"), e.get("on")) for e in cfg["exceptions"]}
+    rows = []
+
+    for path in walk(root):
+        try:
+            text = open(path, encoding="utf-8", errors="replace").read()
+        except OSError:
+            continue
+        vars_ = variables(text)
+        if not vars_:
+            continue
+
+        surfaces = {n: c for n, c in vars_.items()
+                    if any(s in n for s in SURFACES)}
+        inks = {n: c for n, c in vars_.items()
+                if n not in surfaces and not n.startswith("glow")}
+        if not surfaces or not inks:
+            continue
+
+        rel = os.path.relpath(path, root).replace("\\", "/")
+        for ink_name, ink in sorted(inks.items()):
+            # The best surface this ink has. An ink that reaches the floor
+            # somewhere has a place it belongs; one that reaches it nowhere
+            # cannot be read against anything the file declares.
+            best_name, best = None, 0.0
+            for surf_name, surf in sorted(surfaces.items()):
+                r = ratio(ink, surf)
+                if r > best:
+                    best_name, best = surf_name, r
+            declared = any((ink_name, s) in allowed for s in surfaces)
+            rows.append({"file": rel, "ink": ink_name, "on": best_name,
+                         "ratio": best,
+                         "ok": best >= floor or declared,
+                         "declared": declared})
+    return rows
+
+
+def _help():
+    print("""contrast-gate - Fail a build when a declared colour cannot be read on any surface the file declares.
+
+usage:
+  contrast-gate [PATH] [--config FILE] [--list] [--require-pairs]
+
+  PATH             directory to check (default: the working directory)
+  --config         JSON file of recorded exceptions
+  --list           every pair rather than the summary
+  --require-pairs  fail if no colour pair was found at all, instead of
+                   passing vacuously on a stylesheet with no variables
+  --root DIR       same as PATH, kept for existing callers
+
+This reads CSS custom properties (--name: #hex), not literal
+color/background declarations.
+
+Exits 0 when clean, 1 on a finding. Part of readable-gates.
+https://f-keys.com/gatekit/""")
+    return 0
+
+
+def main():
+    if "--help" in sys.argv or "-h" in sys.argv:
+        return _help()
+    args = sys.argv[1:]
+    # Packaged, the directory above this file is site-packages,
+    # not the project being checked. The working directory is
+    # what someone running this in their repo means.
+    root = os.environ.get("CONTRAST_ROOT") or os.getcwd()
+    if "--root" in args:
+        root = os.path.abspath(args[args.index("--root") + 1])
+    else:
+        # a bare path was silently ignored, which meant this scanned its
+        # own repository and reported OK on a tree nobody asked about
+        positional = [a for a in args if not a.startswith("-")]
+        if positional:
+            root = os.path.abspath(positional[0])
+
+    cfg = load_config()
+    rows = check(root, cfg)
+    if not rows:
+        # This reads CSS custom properties - `--ink: #hex` against
+        # `--bg: #hex` - not literal `color:` declarations. A stylesheet
+        # that uses neither has nothing here to compare, which is a true
+        # statement and a dangerous one: in CI it exits 0 and reads as a
+        # pass on a site nobody checked. --require-pairs is how you say
+        # "I expect this to find something", and the Action sets it.
+        print("  contrast: nothing with declared colours to check.")
+        print("            This audits CSS custom properties (--name: #hex),")
+        print("            not literal color/background declarations.")
+        if "--require-pairs" in args:
+            print("  contrast: FAILED - --require-pairs was set and no pair "
+                  "was found.")
+            return 1
+        return 0
+
+    if "--list" in args:
+        for r in sorted(rows, key=lambda x: x["ratio"]):
+            mark = "ok  " if r["ok"] else "FAIL"
+            print("  {} {:>5.2f}  --{} at best on --{}   {}".format(
+                mark, r["ratio"], r["ink"], r["on"], r["file"]))
+        return 0
+
+    bad = [r for r in rows if not r["ok"]]
+    if not bad:
+        print("  contrast: OK - every declared pair reaches {}:1"
+              .format(cfg["floor"]))
+        return 0
+
+    print("  contrast: {} pair(s) below {}:1 and not declared\n"
+          .format(len(bad), cfg["floor"]))
+    for r in sorted(bad, key=lambda x: x["ratio"])[:40]:
+        print("    {:>5.2f}  --{} has no surface it reads on (best is --{})   {}".format(
+            r["ratio"], r["ink"], r["on"], r["file"]))
+    print("\n  Either change the colours, or add the pair to tools/"
+          "contrast.json with a reason.")
+    return 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

legible-0.1.0/src/gatekit/deadname_gate.json

@@ -0,0 +1,13 @@
+{
+  "_comment": [
+    "Names that must not reach anything a human reads.",
+    "'forbidden' is a list of case-insensitive words.",
+    "'allowed' exempts machine identifiers - repo paths, package names,",
+    "live URLs - because renaming those breaks working links or",
+    "contradicts a published record. Each needs a reason.",
+    "Nothing is forbidden by default: say what yours is."
+  ],
+  "forbidden": [],
+  "allowed": [],
+  "skip_paths": []
+}