From 88d0678f3cc491e0a3f2b8ad54c07de04aed3490 Mon Sep 17 00:00:00 2001 From: n1ckyb Date: Sun, 9 Aug 2026 13:49:41 +0100 Subject: [PATCH] fix(readme): repair the headline example, and make the gate actually test it MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The README example on this release candidate does not run: old = "def greet(name): return 'hi ' + name " The triple quotes had collapsed to single quotes, so it dies with "SyntaxError: unterminated string literal" at PARSE time, before importing anything. This is the first code a user copies, and it renders on PyPI. That is 0.0.1 defect #4 again, in a new form. 0.0.1's example raised NameError because it was a fragment; this one is self-contained but unparseable. Restored the triple quotes and confirmed it runs, printing exactly what the README claims two lines below it: ChangeType.ADDITION Insert -> if_statement('if_statement') ## The gate could never have caught this smoke_published_wheel.py already had "a real diff with a known-correct answer", but it ran OLD_SRC/NEW_SRC — the script's own PRIVATE copy of the example. That proves the library works. It proves nothing about what we published, which is precisely the gap that pulled 0.0.1: every check was green. So the gate now extracts the first ```python fence from the README a user reads and executes it against the INSTALLED wheel. Verified in both directions: repaired README exit 0 -> gate passes the broken RC README exit 1 -> gate catches it Found by auditing whether the RC actually contains the fixes 0.0.2 claims to ship, rather than assuming it did. The other three 0.0.1 defects are genuinely fixed on this branch. Co-Authored-By: Claude Opus 5 --- README.md | 8 +++--- scripts/smoke_published_wheel.py | 49 ++++++++++++++++++++++++++++++++ 2 files changed, 53 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index 12046ef..b9fe3c0 100644 --- a/README.md +++ b/README.md @@ -27,14 +27,14 @@ parsers are included. There is no second download and nothing is fetched at runt ```python from intentumdiff import SemanticDiffer -old = "def greet(name): +old = """def greet(name): return 'hi ' + name -" -new = "def greet(name): +""" +new = """def greet(name): if not name: return None return 'hi ' + name -" +""" diff = SemanticDiffer().diff_strings(old, new, "example.py") for change in diff.changes: diff --git a/scripts/smoke_published_wheel.py b/scripts/smoke_published_wheel.py index f5163a4..3ab9323 100644 --- a/scripts/smoke_published_wheel.py +++ b/scripts/smoke_published_wheel.py @@ -33,6 +33,7 @@ from __future__ import annotations import argparse +import re import shutil import subprocess import sys @@ -76,6 +77,24 @@ def run(self, *args: str, **kw) -> subprocess.CompletedProcess[str]: ) + +def _repo_readme() -> str | None: + """The README a user reads. Checked in preference order, nearest first.""" + here = Path(__file__).resolve() + for candidate in (here.parent.parent / "README.md", here.parent / "README.md"): + if candidate.is_file(): + return candidate.read_text(encoding="utf-8") + return None + + +def _first_python_block(markdown: str) -> str | None: + """The first fenced ``python`` block — the headline example, the one people copy.""" + fence = "`" * 3 + pattern = fence + r"python\n(.*?)" + fence + match = re.search(pattern, markdown, re.DOTALL) + return match.group(1) if match else None + + def main() -> int: ap = argparse.ArgumentParser(description=__doc__) ap.add_argument("--wheel", help="local wheel or sdist; defaults to installing from PyPI") @@ -116,6 +135,36 @@ def main() -> int: r = s.run(str(script)) s.check("SemanticDiffer produces a diff", "CHANGES" in r.stdout, r.stderr) + # 5b. THE README'S OWN EXAMPLE, extracted and executed verbatim. + # + # Check 5 above runs OLD_SRC/NEW_SRC — this file's PRIVATE copy of the example. + # That proves the library works; it proves nothing about what we published. The + # 0.0.1 README shipped a headline example that raised NameError, and a gate that + # asserts on its own copy would have passed that release too. + # + # It nearly happened again: on the 0.0.2 release candidate the example's triple + # quotes had collapsed to single quotes, so it died with SyntaxError at PARSE + # time — before importing anything — while every other check here stayed green. + # + # So extract the first ```python fence from the README a user actually reads and + # run it against the INSTALLED wheel. + readme = _repo_readme() + if readme is None: + s.check("README example runs verbatim", False, "README.md not found") + else: + block = _first_python_block(readme) + if block is None: + s.check("README example runs verbatim", False, "no ```python block in README.md") + else: + example = root / "readme_example.py" + example.write_text(block, encoding="utf-8") + r_readme = s.run(str(example)) + s.check( + "README example runs verbatim", + r_readme.returncode == 0, + (r_readme.stderr or r_readme.stdout).strip()[:400], + ) + # 6. THE ONE THAT MATTERS. 0.0.1 emitted ~69 plugin-catalogue errors on every # invocation while still returning a result, so exit code alone said "fine". noise = [