From bbc29b40ace8ca17be06904de0eb3b7ec2260687 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Marcos=20M=C3=A9ndez?= Date: Sat, 26 Sep 2026 21:44:32 +0000 Subject: [PATCH 1/2] ci: check the site before it is served The site had no gate at all. Nothing builds it, so a link that resolves to nothing, an asset that was removed or an external link over plain HTTP went straight to the public page with nobody in the way. Every other repository in the organization has a required check; this one is the most visible and had none. tools/sitecheck.py is what a build step would have done: * every internal link resolves to a file in the repository; * every fragment names an id that is on the page it names, including a fragment of another page, which is what rots silently when a heading is renamed; * every referenced asset exists, and every asset in the tree is referenced, including the social card of the og:image and twitter:image meta tags, which a crawler fetches and a reader never sees fail; * an external link is https or mailto; * a page carries a language, a title and exactly one h1. It is a pure function of a mapping of path to text, so each rule is tested as the smallest page that breaks it, and the suite ends by running the checker over this repository: the rules are only worth having if the site satisfies them. Two findings came out of the first run, both real. The dark and the one colour marks were served and referenced by nothing, so guidelines.html now has a section for the mark that offers all four variants with the rules for using them, which is what a brand page is for. Measured: 37 tests, tools/sitecheck.py 99 percent lines and branches, against the 95 the project asks of its own code. --- .github/workflows/tests.yml | 20 +++ README.md | 27 ++++ guidelines.html | 10 ++ pyproject.toml | 12 ++ tests/test_sitecheck.py | 257 +++++++++++++++++++++++++++++++++++ tools/sitecheck.py | 263 ++++++++++++++++++++++++++++++++++++ 6 files changed, 589 insertions(+) create mode 100644 .github/workflows/tests.yml create mode 100644 README.md create mode 100644 pyproject.toml create mode 100644 tests/test_sitecheck.py create mode 100644 tools/sitecheck.py 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/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..538712f --- /dev/null +++ b/tests/test_sitecheck.py @@ -0,0 +1,257 @@ +# 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_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..f259618 --- /dev/null +++ b/tools/sitecheck.py @@ -0,0 +1,263 @@ +# 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", +) +# 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 name.startswith(".")] + 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 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)) From 8a8e60e552c37b225bddbc9d0d1af9f15586d06b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Marcos=20M=C3=A9ndez?= Date: Sat, 26 Sep 2026 21:46:59 +0000 Subject: [PATCH 2/2] ci: keep packaging leftovers out of what counts as the site The gate failed on its first run, correctly, and on something the local run could not see: in CI the editable install writes *.egg-info/SOURCES.txt and its siblings into the tree, and a .txt is something a site can legitimately serve, so three packaging files were counted as assets no page references. A suffix rule alone cannot tell them apart, so the tree now says which directories are the site: this checker, its tests, and the directories a tool leaves behind are not, including anything ending in .egg-info or .dist-info. Tested against a fixture tree carrying all four. .gitignore keeps the same leftovers out of the repository. --- .gitignore | 5 +++++ tests/test_sitecheck.py | 15 +++++++++++++++ tools/sitecheck.py | 18 +++++++++++++++++- 3 files changed, 37 insertions(+), 1 deletion(-) create mode 100644 .gitignore 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/tests/test_sitecheck.py b/tests/test_sitecheck.py index 538712f..d0346ca 100644 --- a/tests/test_sitecheck.py +++ b/tests/test_sitecheck.py @@ -213,6 +213,21 @@ def test_it_reads_pages_and_assets_and_skips_the_rest(self): 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]) diff --git a/tools/sitecheck.py b/tools/sitecheck.py index f259618..900a9a5 100644 --- a/tools/sitecheck.py +++ b/tools/sitecheck.py @@ -44,6 +44,13 @@ "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 = ( @@ -229,7 +236,7 @@ def read_site(root: str) -> tuple[dict[str, str], set[str]]: pages: dict[str, str] = {} assets: set[str] = set() for base, dirs, names in os.walk(root): - dirs[:] = [name for name in dirs if not name.startswith(".")] + dirs[:] = [name for name in dirs if not _is_excluded_dir(name)] for name in names: if name.startswith("."): continue @@ -243,6 +250,15 @@ def read_site(root: str) -> tuple[dict[str, str], set[str]]: 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)