diff --git a/.github/workflows/tests.yml b/.github/workflows/tests.yml new file mode 100644 index 0000000..0e3467f --- /dev/null +++ b/.github/workflows/tests.yml @@ -0,0 +1,20 @@ +# The gate of the site (docs/ci-cd.md): +# python / coverage tools/sitecheck.py under coverage.py, 95 percent, the +# bar for project-authored code. The suite ends by +# running the checker over this repository, so a broken +# link, a missing asset, a plain HTTP link or an asset +# no page references fails the check before the page is +# served. +# Required on main. Thresholds are only ever raised. +name: tests +on: + pull_request: + push: + branches: [main] +jobs: + python: + uses: keel-linux/.github/.github/workflows/test-python.yml@main + with: + threshold: 95 + package: tools + tests: tests diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..b1e26b2 --- /dev/null +++ b/.gitignore @@ -0,0 +1,5 @@ +__pycache__/ +.pytest_cache/ +.coverage +coverage.txt +*.egg-info/ diff --git a/README.md b/README.md new file mode 100644 index 0000000..712a086 --- /dev/null +++ b/README.md @@ -0,0 +1,27 @@ +# keellinux.org + +The project site, served by GitHub Pages from `main`: two static pages, one +stylesheet and the brand assets. Nothing builds it, so what is in the +repository is what the browser gets. + +| Path | What it is | +|------|------------| +| `index.html` | the home page, also served at `www` | +| `guidelines.html` | how the organization works, and the mark | +| `style.css` | the whole stylesheet, light and dark | +| `assets/` | the mark in its variants and the social card | +| `tools/sitecheck.py` | the checks a build step would have done | +| `tests/` | one test per rule, ending with the site itself | + +## The check + +``` +python3 tools/sitecheck.py . +``` + +It exits 0 when the site is sound and 1 with one line per finding: an +internal link that resolves to nothing, a fragment naming an id that is not +there, a referenced asset that is missing, an asset no page references, an +external link that is not https, or a page without a language, a title or +exactly one h1. The gate `python / coverage` runs the same checks on every +pull request and is required on `main`. diff --git a/guidelines.html b/guidelines.html index 9f80b2f..589423b 100644 --- a/guidelines.html +++ b/guidelines.html @@ -93,6 +93,16 @@

Upstream

  • Forks keep TurnKey Linux as an upstream remote.
  • Changes are offered back upstream where they apply.
  • + +

    The mark

    +

    The mark is a keel seen from astern, with the waterline across it and a drop below. It is drawn as a vector and every other size is an export of it; a change to the mark is a re-export, never an edit of an export.

    + +

    Keep the clear space around it equal to the height of the drop, do not recolour it, and do not set it on a background that leaves the waterline invisible.

    diff --git a/pyproject.toml b/pyproject.toml new file mode 100644 index 0000000..0372f76 --- /dev/null +++ b/pyproject.toml @@ -0,0 +1,12 @@ +# The site has no build step: the files in the repository are the files the +# browser gets. tools/sitecheck.py is the check that a build step would have +# done, and this file is only here to measure it. + +[tool.coverage.run] +branch = true +source = ["tools"] + +[tool.coverage.report] +show_missing = true +# The bar for project-authored code (decision 0003). Only ever raised. +fail_under = 95 diff --git a/tests/test_sitecheck.py b/tests/test_sitecheck.py new file mode 100644 index 0000000..d0346ca --- /dev/null +++ b/tests/test_sitecheck.py @@ -0,0 +1,272 @@ +# Copyright (c) 2026 KeelLinux maintainers +"""Every rule the site checker enforces, and the site itself + +The checker is a pure function of a mapping of path to text, so each rule is +stated here as the smallest page that breaks it. The last test runs the +checker over the repository it lives in, which is what the gate does: the +rules are only worth having if the site actually satisfies them. +""" + +import os +import sys +import unittest +from os.path import abspath, dirname, join + +ROOT = dirname(dirname(abspath(__file__))) +sys.path.insert(0, join(ROOT, "tools")) + +import sitecheck # noqa: E402 + +HEAD = 'Keel' +BODY = "

    Keel

    " + + +def page(body: str = "", head: str = HEAD, heading: str = BODY) -> str: + return f"{head}{heading}{body}" + + +class TestShape(unittest.TestCase): + def test_a_well_formed_page_has_no_findings(self): + self.assertEqual(sitecheck.check({"index.html": page()}), []) + + def test_a_page_without_a_language_is_reported(self): + text = page(head="K") + self.assertIn( + "index.html: the html element has no lang", + sitecheck.check({"index.html": text}), + ) + + def test_a_page_without_a_title_is_reported(self): + text = page(head='') + self.assertIn("index.html: no title", sitecheck.check({"index.html": text})) + + def test_an_empty_title_counts_as_none(self): + text = page(head=' ') + self.assertIn("index.html: no title", sitecheck.check({"index.html": text})) + + def test_a_page_without_an_h1_is_reported(self): + findings = sitecheck.check({"index.html": page(heading="

    no heading

    ")}) + self.assertIn("index.html: 0 h1 elements, expected 1", findings) + + def test_two_h1_elements_are_reported(self): + text = page(heading="

    one

    two

    ") + self.assertIn( + "index.html: 2 h1 elements, expected 1", + sitecheck.check({"index.html": text}), + ) + + +class TestInternalLinks(unittest.TestCase): + def test_a_link_to_a_missing_page_is_reported(self): + findings = sitecheck.check({"index.html": page('x')}) + self.assertEqual( + findings, ["index.html: gone.html does not resolve to a file"] + ) + + def test_a_link_to_a_page_that_is_there_passes(self): + pages = {"index.html": page('x'), "two.html": page()} + self.assertEqual(sitecheck.check(pages), []) + + def test_a_link_out_of_the_site_root_is_reported(self): + findings = sitecheck.check( + {"index.html": page('x')} + ) + self.assertEqual( + findings, ["index.html: ../secret.html does not resolve to a file"] + ) + + def test_an_absolute_path_is_read_from_the_site_root(self): + pages = {"index.html": page('x'), "two.html": page()} + self.assertEqual(sitecheck.check(pages), []) + + def test_a_link_from_a_page_in_a_directory_resolves_beside_it(self): + pages = { + "docs/one.html": page('x'), + "docs/two.html": page(), + } + self.assertEqual(sitecheck.check(pages), []) + + +class TestFragments(unittest.TestCase): + def test_a_fragment_on_the_same_page_must_exist(self): + text = page('x') + self.assertEqual( + sitecheck.check({"index.html": text}), + ["index.html: #nowhere names an id that is not there"], + ) + + def test_a_fragment_that_exists_passes(self): + text = page('x
    ') + self.assertEqual(sitecheck.check({"index.html": text}), []) + + def test_a_fragment_of_another_page_must_exist_there(self): + pages = { + "index.html": page('x'), + "two.html": page('
    '), + } + self.assertEqual( + sitecheck.check(pages), + ["index.html: two.html#gone names an id that is not there"], + ) + + def test_a_fragment_of_another_page_that_exists_passes(self): + pages = { + "index.html": page('x'), + "two.html": page('
    '), + } + self.assertEqual(sitecheck.check(pages), []) + + def test_a_fragment_of_an_asset_is_reported(self): + text = page('x') + findings = sitecheck.check({"index.html": text}, {"assets/a.svg"}) + self.assertEqual( + findings, + [ + "index.html: assets/a.svg#part names a fragment of a file" + " that is not a page" + ], + ) + + def test_an_empty_id_attribute_is_not_a_target(self): + text = page('x
    ') + self.assertEqual(len(sitecheck.check({"index.html": text})), 1) + + +class TestAssets(unittest.TestCase): + def test_a_referenced_asset_that_is_missing_is_reported(self): + text = page('') + self.assertEqual( + sitecheck.check({"index.html": text}, set()), + ["index.html: assets/gone.png does not resolve to a file"], + ) + + def test_a_referenced_asset_that_is_there_passes(self): + text = page('') + self.assertEqual(sitecheck.check({"index.html": text}, {"assets/here.png"}), []) + + def test_an_asset_no_page_references_is_reported(self): + findings = sitecheck.check({"index.html": page()}, {"assets/orphan.png"}) + self.assertEqual(findings, ["assets/orphan.png: no page references it"]) + + def test_assets_are_not_checked_when_none_are_given(self): + text = page('') + self.assertEqual(sitecheck.check({"index.html": text}), []) + + def test_the_social_card_of_a_meta_tag_counts_as_a_reference(self): + text = page( + '' + ) + self.assertEqual(sitecheck.check({"index.html": text}, {"assets/card.png"}), []) + + def test_a_twitter_image_counts_as_a_reference(self): + text = page('') + self.assertEqual(sitecheck.check({"index.html": text}, {"assets/card.png"}), []) + + def test_a_meta_tag_that_is_not_a_reference_is_ignored(self): + text = page('') + self.assertEqual(sitecheck.check({"index.html": text}), []) + + def test_a_poster_and_a_stylesheet_count_as_references(self): + text = page( + '' + '' + ) + self.assertEqual( + sitecheck.check({"index.html": text}, {"style.css", "assets/still.png"}), + [], + ) + + +class TestExternalLinks(unittest.TestCase): + def test_an_https_link_passes(self): + text = page('x') + self.assertEqual(sitecheck.check({"index.html": text}), []) + + def test_a_plain_http_link_is_reported(self): + text = page('x') + self.assertEqual( + sitecheck.check({"index.html": text}), + ["index.html: http://example.org/x is not https"], + ) + + def test_a_protocol_relative_link_is_reported(self): + text = page('x') + self.assertEqual( + sitecheck.check({"index.html": text}), + ["index.html: //example.org/x is not https"], + ) + + def test_a_mailto_link_passes(self): + text = page('x') + self.assertEqual(sitecheck.check({"index.html": text}), []) + + def test_a_data_uri_is_not_a_reference(self): + text = page('') + self.assertEqual(sitecheck.check({"index.html": text}, set()), []) + + +class TestReadSite(unittest.TestCase): + def test_it_reads_pages_and_assets_and_skips_the_rest(self): + pages, assets = sitecheck.read_site(ROOT) + self.assertIn("index.html", pages) + self.assertIn("assets/keel-mark.svg", assets) + self.assertNotIn("tools/sitecheck.py", assets) + self.assertFalse([path for path in assets if path.startswith(".git")]) + + def test_packaging_metadata_is_not_part_of_the_site(self): + import tempfile + + with tempfile.TemporaryDirectory() as tmp: + for directory in ("site.egg-info", "tools", "tests", "build"): + os.makedirs(join(tmp, directory)) + with open(join(tmp, directory, "leftover.txt"), "w") as fob: + fob.write("x") + with open(join(tmp, "index.html"), "w") as fob: + fob.write(page()) + pages, assets = sitecheck.read_site(tmp) + + self.assertEqual(sorted(pages), ["index.html"]) + self.assertEqual(assets, set()) + + def test_a_dotted_directory_is_skipped(self): + pages, assets = sitecheck.read_site(ROOT) + self.assertFalse([path for path in pages if "/." in path]) + + +class TestCommandLine(unittest.TestCase): + def test_the_site_of_this_repository_has_no_findings(self): + self.assertEqual(sitecheck.main(["sitecheck", ROOT]), 0) + + def test_a_tree_with_no_page_is_a_usage_failure(self): + self.assertEqual(sitecheck.main(["sitecheck", join(ROOT, "assets")]), 2) + + def test_it_exits_1_on_a_finding(self): + import tempfile + + with tempfile.TemporaryDirectory() as tmp: + with open(join(tmp, "index.html"), "w") as fob: + fob.write(page('x')) + self.assertEqual(sitecheck.main(["sitecheck", tmp]), 1) + + def test_the_script_runs_as_a_program(self): + import subprocess + + out = subprocess.run( + [sys.executable, join(ROOT, "tools", "sitecheck.py"), ROOT], + capture_output=True, + text=True, + ) + self.assertEqual(out.returncode, 0, out.stderr) + self.assertIn("findings", out.stderr) + + def test_the_default_root_is_the_working_directory(self): + here = os.getcwd() + os.chdir(ROOT) + try: + self.assertEqual(sitecheck.main(["sitecheck"]), 0) + finally: + os.chdir(here) + + +if __name__ == "__main__": + unittest.main() diff --git a/tools/sitecheck.py b/tools/sitecheck.py new file mode 100644 index 0000000..900a9a5 --- /dev/null +++ b/tools/sitecheck.py @@ -0,0 +1,279 @@ +# Copyright (c) 2026 KeelLinux maintainers +"""What a static site must satisfy before it is served + +The site is the public face of the project and nothing builds it: the files +in the repository are the files the browser gets. So the checks that a build +step would have done are here instead, and the gate runs them over the +repository's own pages. + +What is checked, and why each one is worth a failed build: + + - every internal link resolves to a file in the repository, so a page + never answers 404 from its own navigation; + - every fragment resolves to an id on the page it names, including the + fragments of another page, which is what silently rots when a heading + is renamed; + - every asset a page references exists, and every asset in the tree is + referenced by some page, so a removed image is caught and an orphan is + not served forever; + - an external link is https, because a page served over TLS that links + over plain HTTP teaches the reader the wrong habit; + - a page carries a title, a language and one h1, which is the least a + reader and a search engine can expect. + +Pure but for `read_site`: `check` is given a mapping of path to text and +returns the findings, so every rule is tested without a filesystem. +""" + +from __future__ import annotations + +import os +import sys +from html.parser import HTMLParser + +# Attributes that carry a reference to something else +REFERENCE_ATTRS = ("href", "src", "srcset", "poster") +# Extensions that are pages rather than assets +PAGE_SUFFIX = ".html" +# meta tags whose content is a reference, not text: the social card is +# fetched by a crawler, so a wrong path there breaks a link nobody sees +# until it is shared +META_REFERENCE_KEYS = ( + "og:image", + "og:image:url", + "og:url", + "twitter:image", +) +# Directories that are in the repository but are not the site: this checker, +# its tests, and whatever a tool leaves behind. Packaging metadata is the +# reason this list exists rather than a suffix rule alone: an editable install +# writes *.egg-info/*.txt into the tree, and a .txt is something a site can +# serve, so the tree has to say which directories are the site at all. +EXCLUDE_DIRS = ("tools", "tests", "node_modules", "build", "dist") +EXCLUDE_DIR_SUFFIXES = (".egg-info", ".dist-info") +# What the site serves. A file of any other kind in the tree is repository +# furniture (this checker, its tests, the packaging) and is not an asset. +ASSET_SUFFIXES = ( + ".css", ".js", ".png", ".svg", ".jpg", ".jpeg", ".webp", ".avif", + ".ico", ".gif", ".woff", ".woff2", ".txt", ".json", ".xml", ".pdf", + ".webmanifest", +) + + +class Page(HTMLParser): + """The parts of one page the checks look at""" + + def __init__(self) -> None: + super().__init__(convert_charrefs=True) + self.references: list[str] = [] + self.ids: set[str] = set() + self.titles: list[str] = [] + self.headings: list[str] = [] + self.language = "" + self._in_title = False + self._in_h1 = False + + def handle_starttag(self, tag: str, attrs: list[tuple[str, str | None]]) -> None: + values = {name: (value or "") for name, value in attrs} + if tag == "html": + self.language = values.get("lang", "") + if tag == "title": + self._in_title = True + self.titles.append("") + if tag == "h1": + self._in_h1 = True + self.headings.append("") + if "id" in values and values["id"]: + self.ids.add(values["id"]) + if tag == "meta": + key = values.get("property") or values.get("name") or "" + content = values.get("content", "").strip() + if key.lower() in META_REFERENCE_KEYS and content: + self.references.append(content) + for attr in REFERENCE_ATTRS: + value = values.get(attr, "").strip() + if value: + self.references.append(value) + + def handle_endtag(self, tag: str) -> None: + if tag == "title": + self._in_title = False + if tag == "h1": + self._in_h1 = False + + def handle_data(self, data: str) -> None: + if self._in_title and self.titles: + self.titles[-1] += data + if self._in_h1 and self.headings: + self.headings[-1] += data + + +def parse(text: str) -> Page: + page = Page() + page.feed(text) + page.close() + return page + + +def is_external(reference: str) -> bool: + return "//" in reference.split("?")[0] or reference.startswith("mailto:") + + +def split_fragment(reference: str) -> tuple[str, str]: + """A reference as (path, fragment); either part may be empty""" + path, _, fragment = reference.partition("#") + return path, fragment + + +def check(pages: dict[str, str], assets: set[str] | None = None) -> list[str]: + """Findings for a site given as {path: text}, one line each + + `assets` is every non page file in the tree, used to find the ones no + page references. Leave it out to skip that rule. + """ + findings: list[str] = [] + parsed = {path: parse(text) for path, text in sorted(pages.items())} + referenced: set[str] = set() + + for path, page in parsed.items(): + findings.extend(_check_shape(path, page)) + for reference in page.references: + if reference.startswith("data:"): + continue + if is_external(reference): + findings.extend(_check_external(path, reference)) + continue + target, fragment = split_fragment(reference) + if target: + referenced.add(_resolve(path, target)) + findings.extend( + _check_internal( + path, reference, target, fragment, parsed, assets + ) + ) + + if assets is not None: + for asset in sorted(assets - referenced): + findings.append(f"{asset}: no page references it") + return findings + + +def _check_shape(path: str, page: Page) -> list[str]: + findings = [] + if not page.language.strip(): + findings.append(f"{path}: the html element has no lang") + titles = [title.strip() for title in page.titles if title.strip()] + if not titles: + findings.append(f"{path}: no title") + headings = [text.strip() for text in page.headings if text.strip()] + if len(headings) != 1: + findings.append(f"{path}: {len(headings)} h1 elements, expected 1") + return findings + + +def _check_external(path: str, reference: str) -> list[str]: + if reference.startswith(("https://", "mailto:")): + return [] + return [f"{path}: {reference} is not https"] + + +def _resolve(path: str, target: str) -> str: + """A reference on `path` as a site path, without normalising away .. + + A target that climbs above the site root is returned as it was, so the + internal check reports it as missing rather than reaching outside. + """ + if target.startswith("/"): + return target.lstrip("/") + base = os.path.dirname(path) + joined = os.path.normpath(os.path.join(base, target)) if base else target + return os.path.normpath(joined) + + +def _check_internal( + path: str, + reference: str, + target: str, + fragment: str, + parsed: dict[str, Page], + assets: set[str] | None, +) -> list[str]: + """Findings for one internal reference made on `path` + + A reference to a page is resolved against the pages, which are all + known. A reference to an asset is resolved against `assets` when the + caller gave them, and left alone when it did not, so a caller that only + has the pages is not told that every image is missing. + """ + findings = [] + resolved = _resolve(path, target) if target else path + if target and not _resolves(resolved, parsed, assets): + return [f"{path}: {reference} does not resolve to a file"] + if not fragment: + return findings + if resolved not in parsed: + return [ + f"{path}: {reference} names a fragment of a file" + " that is not a page" + ] + if fragment not in parsed[resolved].ids: + findings.append(f"{path}: {reference} names an id that is not there") + return findings + + +def _resolves( + resolved: str, parsed: dict[str, Page], assets: set[str] | None +) -> bool: + if resolved.endswith(PAGE_SUFFIX): + return resolved in parsed + if assets is None: + return True + return resolved in assets + + +def read_site(root: str) -> tuple[dict[str, str], set[str]]: + """The pages and the assets of the tree at `root`""" + pages: dict[str, str] = {} + assets: set[str] = set() + for base, dirs, names in os.walk(root): + dirs[:] = [name for name in dirs if not _is_excluded_dir(name)] + for name in names: + if name.startswith("."): + continue + full = os.path.join(base, name) + path = os.path.relpath(full, root) + if name.endswith(PAGE_SUFFIX): + with open(full, encoding="utf-8") as fob: + pages[path] = fob.read() + elif name.lower().endswith(ASSET_SUFFIXES): + assets.add(path) + return pages, assets + + +def _is_excluded_dir(name: str) -> bool: + """Whether a directory is repository furniture rather than the site""" + return ( + name.startswith(".") + or name in EXCLUDE_DIRS + or name.endswith(EXCLUDE_DIR_SUFFIXES) + ) + + +def main(argv: list[str]) -> int: + root = argv[1] if len(argv) > 1 else "." + pages, assets = read_site(root) + if not pages: + print(f"{root}: no pages found", file=sys.stderr) + return 2 + findings = check(pages, assets) + for finding in findings: + print(finding) + print( + f"{len(pages)} pages, {len(assets)} assets, {len(findings)} findings", + file=sys.stderr, + ) + return 1 if findings else 0 + + +if __name__ == "__main__": + sys.exit(main(sys.argv))