From deeb0bd82cd55be286993262803b180f93b1a258 Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 5 Aug 2026 18:26:24 +0000 Subject: [PATCH 1/3] docs: say what was actually checked about the adopters MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The claim was "Used by developers and organizations worldwide in their production workflows", under a heading reading "Trusted by developers worldwide". The organizations were verified by hand, at organization level — these orgs have repositories that run Commit Check. Which repositories was not pinned down, so "in their production workflows" claimed more than that: a repository can be a demo, a template or an experiment. It was also the least load-bearing part of the sentence, since eighteen logos carry the point on their own. What was verified is the stronger claim anyway, because a reader can check it — the dependents graph is right there, and "production" is not falsifiable. So the section says that instead, and the dependents link moves into the sentence rather than dangling after the logo grid. Dropping "worldwide" from the heading also stops it and the sentence below repeating the same two words back to back. Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_01U9zFxq8V4qxG4aMzJhGBFn --- docs/index.md | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/docs/index.md b/docs/index.md index 7e3699b..8dcc204 100644 --- a/docs/index.md +++ b/docs/index.md @@ -240,11 +240,12 @@ graph LR -## Trusted by developers worldwide +## Used by
-**Used by developers and organizations worldwide in their production workflows.** +**Commit Check runs in repositories across these organizations, and in +[many more](https://github.com/commit-check/commit-check-action/network/dependents).**
@@ -323,8 +324,6 @@ graph LR
-And [many more](https://github.com/commit-check/commit-check-action/network/dependents). - ---
From 2d2cd174975f1685ef0208f8be9747ea76d5c6d4 Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 5 Aug 2026 19:06:40 +0000 Subject: [PATCH 2/3] test: check the compact samples, which nothing was checking MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The two text formats spell a check name differently — the default output prints the kebab-case name, --compact prints the config key — so a sample of one cannot be validated against the other. The existing guard only matches the default format, which meant every --compact sample on the site was checked by nothing at all. That is the same blind spot that let a pre-2.13 sample sit unnoticed in the troubleshooting page: the sample was stale in a format the guard could not see, and every test still passed. Fixing that one sample did not close the hole it came through. Two samples were uncovered, in example.md and rules.md — one indented inside a content tab, one not, so the pattern allows leading whitespace. Verified by breaking one deliberately: the guard names the file and both spellings, rather than only going red. This also decides what happens if commit-check#528 reconciles the two formats upstream. Today that would quietly leave both samples wrong; now docs-sync fails and says which lines to rewrite. Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_01U9zFxq8V4qxG4aMzJhGBFn --- tests/docs_sync_test.py | 31 +++++++++++++++++++++++++++++++ 1 file changed, 31 insertions(+) diff --git a/tests/docs_sync_test.py b/tests/docs_sync_test.py index 4eac633..7d39e76 100644 --- a/tests/docs_sync_test.py +++ b/tests/docs_sync_test.py @@ -32,6 +32,10 @@ def _read_doc(name: str) -> str: #: A pasted failure line, e.g. ``CC003 subject-imperative check failed ==> ...`` _SAMPLE_FAILURE = re.compile(r"(CC\d{3}) (\S+) check failed ==>") +#: A pasted ``--compact`` line, e.g. ``[FAIL] CC003 subject_imperative: ...``. +#: Indented, because these samples sit inside content tabs. +_COMPACT_FAILURE = re.compile(r"^\s*\[FAIL\] (CC\d{3}) ([^:\s]+):", re.M) + def _rule_section(content: str, rule_id: str) -> str: """Return just the part of the rules page belonging to one rule.""" @@ -83,6 +87,33 @@ def test_sample_output_matches_what_the_tool_prints(self): ) assert not stale, "sample output is out of date:\n " + "\n ".join(stale) + def test_compact_sample_output_matches_what_the_tool_prints(self): + """Pasted ``--compact`` output names rules the way that format does. + + The two text formats spell a check differently: the default output + prints the kebab-case name, and ``--compact`` prints the config key. + A sample of one therefore cannot be validated against the other, and + the guard above only matches the default format — so the compact + samples were checked by nothing at all. That is the blind spot that + let a pre-2.13 sample sit unnoticed in the troubleshooting page. + + If the two formats are ever reconciled (see commit-check#528), this + is what will point at the samples that need rewriting. + """ + by_id = {entry.rule_id: entry for entry in ALL_RULES} + stale = [] + for page in DOCS.rglob("*.md"): + for rule_id, printed in _COMPACT_FAILURE.findall(page.read_text("utf-8")): + entry = by_id.get(rule_id) + if entry and printed != entry.check: + stale.append( + f"{page.relative_to(DOCS)}: {rule_id} shown as " + f"'{printed}', --compact prints '{entry.check}'" + ) + assert not stale, ( + "compact sample output is out of date:\n " + "\n ".join(stale) + ) + def test_every_rule_explains_itself(self): """Each rule section must answer what it does and why it matters.""" content = _read_doc("rules.md") From 936d8cb1839054f4ceae7872d1016c1bde538b4d Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 5 Aug 2026 19:11:31 +0000 Subject: [PATCH 3/3] test: report unknown rule IDs instead of skipping them MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Both sample guards looked up the rule ID and then wrote `if entry and ...`, so an ID the package does not define fell through the condition and the sample passed. A typo, or an ID retired upstream, could sit in the docs with every test green — which is the exact failure these guards exist to catch, so it is the one they must not wave through. Review raised this against the compact guard, because that is what was in the diff. The older guard had the same line, so fixing only the new one would have left the hole in the more established of the two and made the pair inconsistent. Both now share one helper rather than the fix being written twice. Verified by breaking each case in turn: a stale name in the default format, a stale name in --compact, and CC999 in place of a real ID. All three now name the file and the problem; the third previously passed. Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_01U9zFxq8V4qxG4aMzJhGBFn --- tests/docs_sync_test.py | 49 ++++++++++++++++++++++++----------------- 1 file changed, 29 insertions(+), 20 deletions(-) diff --git a/tests/docs_sync_test.py b/tests/docs_sync_test.py index 7d39e76..de9abf0 100644 --- a/tests/docs_sync_test.py +++ b/tests/docs_sync_test.py @@ -43,6 +43,33 @@ def _rule_section(content: str, rule_id: str) -> str: return re.split(r"\{ #cc\d{3} \}", after)[0] +def _stale_samples(pattern: re.Pattern, attribute: str, printer: str) -> list[str]: + """Find pasted samples that name a rule differently from the tool. + + ``attribute`` is the field of the catalog entry the format prints, and + ``printer`` names that format in the failure message. + + An unrecognised rule ID is reported rather than skipped. Skipping it would + mean a typo, or an ID retired upstream, could sit in a sample with every + test still passing — which is the exact failure these guards exist to + catch, so it must not be the one they wave through. + """ + by_id = {entry.rule_id: entry for entry in ALL_RULES} + stale = [] + for page in DOCS.rglob("*.md"): + for rule_id, printed in pattern.findall(page.read_text("utf-8")): + where = page.relative_to(DOCS) + entry = by_id.get(rule_id) + if entry is None: + stale.append(f"{where}: {rule_id} is not a rule the package defines") + elif printed != getattr(entry, attribute): + stale.append( + f"{where}: {rule_id} shown as '{printed}', " + f"{printer} prints '{getattr(entry, attribute)}'" + ) + return stale + + class TestRulesDocumentation: """Every rule the package defines stays documented here.""" @@ -75,16 +102,7 @@ def test_sample_output_matches_what_the_tool_prints(self): to its kebab-case form, six samples across four pages kept showing the old one and every test still passed. """ - by_id = {entry.rule_id: entry for entry in ALL_RULES} - stale = [] - for page in DOCS.rglob("*.md"): - for rule_id, printed in _SAMPLE_FAILURE.findall(page.read_text("utf-8")): - entry = by_id.get(rule_id) - if entry and printed != entry.name: - stale.append( - f"{page.relative_to(DOCS)}: {rule_id} shown as " - f"'{printed}', the tool prints '{entry.name}'" - ) + stale = _stale_samples(_SAMPLE_FAILURE, "name", "the tool") assert not stale, "sample output is out of date:\n " + "\n ".join(stale) def test_compact_sample_output_matches_what_the_tool_prints(self): @@ -100,16 +118,7 @@ def test_compact_sample_output_matches_what_the_tool_prints(self): If the two formats are ever reconciled (see commit-check#528), this is what will point at the samples that need rewriting. """ - by_id = {entry.rule_id: entry for entry in ALL_RULES} - stale = [] - for page in DOCS.rglob("*.md"): - for rule_id, printed in _COMPACT_FAILURE.findall(page.read_text("utf-8")): - entry = by_id.get(rule_id) - if entry and printed != entry.check: - stale.append( - f"{page.relative_to(DOCS)}: {rule_id} shown as " - f"'{printed}', --compact prints '{entry.check}'" - ) + stale = _stale_samples(_COMPACT_FAILURE, "check", "--compact") assert not stale, ( "compact sample output is out of date:\n " + "\n ".join(stale) )