From b1c5315e7df0d2d23735bffe7bab466a2557e864 Mon Sep 17 00:00:00 2001 From: Quelin Zammit <193446206+PNX89@users.noreply.github.com> Date: Sun, 30 Aug 2026 18:48:24 +0200 Subject: [PATCH] Read the install step from the pipeline that runs it Generated files only, all written by pagesgen, which owns four files in every repository. Each change fixes something that could not be fixed in the repository, because a hand edit to a generated file is erased on the next run. A card could publish a dead link when no tag was visible at capture time. The contract test cited DOCDRIFT.md, which is present in one of the sixteen, and illustrated the resolution rule with another repository's path. A claim quoting a command rendered its backticks literally. The contributor guide hard-coded three Python facts that are false for the repository with no Python in it. And the command extractor dropped npm run typecheck, so the guide omitted a gate. --- CONTRIBUTING.md | 4 ++-- site/index.html | 18 ++++++++++++++++++ tests/test_doc_contract.py | 15 ++++++++++----- 3 files changed, 30 insertions(+), 7 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index b535da8..7dba39c 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -7,7 +7,7 @@ be useful is usually to disagree with something it claims. ```bash git clone https://github.com/PNX89/QUESTZ.git && cd QUESTZ -uv sync --all-extras --dev +uv sync --locked --dev questz canary check --contract examples/contracts/items.json --html questz/testsite/v2/items.html; echo "exit $?" ``` @@ -30,7 +30,7 @@ uv run pytest -m e2e --tracing=retain-on-failure ``` Run every one of them. Running only the test suite is the most common way to be surprised by a -red badge: formatting and typing are gates here, not suggestions. +red badge: formatting, linting and typing are gates here, not suggestions. ## And the jobs that gate the pull request diff --git a/site/index.html b/site/index.html index 5f96b69..e57b56e 100644 --- a/site/index.html +++ b/site/index.html @@ -45,6 +45,24 @@ font: 16px/1.65 ui-sans-serif, -apple-system, "Segoe UI", Roboto, Helvetica, Arial, sans-serif; } main { max-width: 46rem; margin: 0 auto; } + /* THE EVIDENCE BREAKS OUT WIDER THAN THE ARGUMENT, and that asymmetry is deliberate. + Prose wants a short measure, about 46rem, because a long line is hard to track back to the + start of the next one. Captured output wants whatever width it really is. + + MEASURED BEFORE CHANGING ANYTHING. Nine of the sixteen transcripts are wider than the + roughly 90 columns that fit here, and they are wide for two different reasons. QUARRYZ's + longest line is an ordinary English sentence that was simply never wrapped, and that is a + capture-side problem. QUIDZ at 169 columns is a real log record and QUOTEZ at 142 is one + JSON bar per line, and NEITHER may be narrowed: truncating removes evidence and wrapping + stops a record being a record, while the property this whole page rests on is that the + committed artefact and the rendered page are the same bytes. + + So the page gives the data the room instead. The block still scrolls when it must, and it + is keyboard reachable with a visible focus ring, so needing to scroll is not a dead end. */ + pre, .scroller { + width: min(64rem, calc(100vw - 3rem)); + margin-left: calc(50% - min(32rem, calc(50vw - 1.5rem))); + } h1 { font-size: 2.25rem; letter-spacing: -0.02em; margin: 0 0 .35rem; } .blurb { color: var(--muted); margin: 0 0 2rem; font-size: 1.05rem; } .claim { font-size: 1.2rem; line-height: 1.5; margin: 0 0 2rem; border-left: 3px solid var(--accent); padding-left: 1rem; } diff --git a/tests/test_doc_contract.py b/tests/test_doc_contract.py index 420ade8..191db11 100644 --- a/tests/test_doc_contract.py +++ b/tests/test_doc_contract.py @@ -1,4 +1,9 @@ -"""The doc-drift contract, generated. The contract itself is in DOCDRIFT.md. +"""The doc-drift contract, generated. + +THE CONTRACT ITSELF IS NOT IN THIS REPOSITORY. It lives beside the generator that wrote this +file, in the toolset these sixteen repositories share, and the copy here is the half that is +identical everywhere. This paragraph used to name a file that is not in the tree, which is the +exact defect this file exists to detect. Every repository in this toolset makes checkable claims in its README on purpose, and a claim that was true when written and is false now is worse than one never made: it reads as evidence @@ -37,8 +42,8 @@ def _resolves(claim: str) -> bool: """The resolution rule, in order: root, then src/, then a unique basename in the tree. The src/ step is the module-path convention rather than laziness. Prose says - `quidz/app.py` because that is the import path a reader types, and the file is at - `src/quidz/app.py`. Both are correct and a check that refused the first would be wrong. + `questz/thing.py` because that is the import path a reader types, and the file is at + `src/questz/thing.py`. Both are correct and a check that refused the first would be wrong. """ if (REPO / claim).exists(): return True @@ -88,8 +93,8 @@ def test_this_repository_still_implements_every_contract_kind() -> None: """The contract is only a contract because something checks it is kept. Each kind above names the test in this repository that implements it. Delete or rename one - and this fails, saying which kind lost its implementation. Without this, DOCDRIFT.md would be - a description of what used to be true. + and this fails, saying which kind lost its implementation. Without it, the shared contract + would be a description of what used to be true. """ suite = "\n".join( path.read_text(encoding="utf-8") for path in sorted((REPO / "tests").glob("test_*.py"))