diff --git a/scripts/check-doc-narrative.py b/scripts/check-doc-narrative.py index 3b98188ef..4cf7cdab9 100755 --- a/scripts/check-doc-narrative.py +++ b/scripts/check-doc-narrative.py @@ -38,7 +38,7 @@ import sys try: sys.stdout.reconfigure(errors="replace") # type: ignore[union-attr] sys.stderr.reconfigure(errors="replace") # type: ignore[union-attr] -except Exception: # noqa: BLE001, S110 — a stdout that cannot be reconfigured is not a reason to fail +except Exception: # noqa: S110 — a stdout that cannot be reconfigured is not a reason to fail pass # deliberate: this is the never-fails invariant's own setup, so it cannot itself raise # `docs/decisions/**` is exempt WHOLESALE — a decision record narrating how a rule was got wrong is @@ -254,6 +254,7 @@ def main(argv: list[str]) -> int: if __name__ == "__main__": try: sys.exit(main(sys.argv)) - except Exception as exc: # noqa: BLE001 — the never-fails constraint outranks a clean traceback + # The never-fails constraint outranks a clean traceback, so this catch is deliberately blind. + except Exception as exc: print(f"doc-narrative: internal error ({exc!r}) — SCANNED NOTHING. Advisory; not a failure.") sys.exit(0) diff --git a/scripts/tests/test_check_doc_narrative.py b/scripts/tests/test_check_doc_narrative.py index 0650e0b67..863b30a96 100644 --- a/scripts/tests/test_check_doc_narrative.py +++ b/scripts/tests/test_check_doc_narrative.py @@ -27,9 +27,7 @@ HIT = re.compile(r"^::warning file=(?P[^:]+)::(?P=path):(?P\d+) ", r def run(cwd: Path, *args: str) -> subprocess.CompletedProcess: - return subprocess.run( - [sys.executable, str(SCRIPT), *args], cwd=cwd, capture_output=True, text=True - ) + return subprocess.run([sys.executable, str(SCRIPT), *args], cwd=cwd, capture_output=True, text=True) def hits(out: str) -> set[tuple[str, int]]: @@ -76,9 +74,9 @@ def commit(r: Path, msg: str = "c") -> None: [ ((), "scanned "), (("--all",), "scanned "), - (("--diff",), "--diff needs a base ref"), # no base ref at all - (("--diff", ""), "--diff needs a base ref"), # `origin/` with base_ref unset - (("--diff", "no-such-ref-xyz"), "SCANNED NOTHING"), # an unresolvable ref + (("--diff",), "--diff needs a base ref"), # no base ref at all + (("--diff", ""), "--diff needs a base ref"), # `origin/` with base_ref unset + (("--diff", "no-such-ref-xyz"), "SCANNED NOTHING"), # an unresolvable ref (("--diff", "origin/"), "SCANNED NOTHING"), (("--nonsense",), "unknown mode"), ], @@ -133,14 +131,14 @@ def test_a_DELETED_doc_is_not_reported_as_added_content(repo: Path) -> None: # stopped pinning variants and removed the surface. The table is here so the next knob someone finds # gets a row instead of a round. FORMAT_KNOBS = [ - ("core.quotePath", "true"), # quotes non-ASCII paths out of the population - ("diff.dstPrefix", "dst/"), # rewrites the header the path is read from + ("core.quotePath", "true"), # quotes non-ASCII paths out of the population + ("diff.dstPrefix", "dst/"), # rewrites the header the path is read from ("diff.srcPrefix", "src/"), ("diff.noprefix", "true"), - ("color.diff", "always"), # injects ANSI escapes into every line + ("color.diff", "always"), # injects ANSI escapes into every line ("color.ui", "always"), - ("diff.renames", "false"), # turns a `git mv` into a whole-file add - ("diff.context", "9"), # a configured context must not beat the -U0 on the CLI + ("diff.renames", "false"), # turns a `git mv` into a whole-file add + ("diff.context", "9"), # a configured context must not beat the -U0 on the CLI ("diff.external", "/bin/echo"), # replaces the output wholesale ] @@ -167,9 +165,7 @@ def test_a_NON_UTF8_stdio_does_not_break_the_never_fails_invariant(repo: Path, e env = dict(os.environ, **{env_name: env_value}) env.pop("PYTHONUTF8", None) - p = subprocess.run( - [sys.executable, str(SCRIPT), "--all"], cwd=repo, capture_output=True, text=True, env=env - ) + p = subprocess.run([sys.executable, str(SCRIPT), "--all"], cwd=repo, capture_output=True, text=True, env=env) assert p.returncode == 0, f"{env_name}={env_value} exited {p.returncode}: {p.stderr}" @@ -224,9 +220,9 @@ def test_a_multi_hunk_file_numbers_every_hunk_from_its_own_header(repo: Path) -> body = [f"l{i}" for i in range(1, 31)] (repo / "docs" / "m.md").write_text("\n".join(body) + "\n", encoding="utf-8") commit(repo) - body[4] = NARRATIVE # replace, early hunk - body.insert(15, NARRATIVE) # pure insert, middle hunk - body[-1] = NARRATIVE # replace, last hunk + body[4] = NARRATIVE # replace, early hunk + body.insert(15, NARRATIVE) # pure insert, middle hunk + body[-1] = NARRATIVE # replace, last hunk (repo / "docs" / "m.md").write_text("\n".join(body) + "\n", encoding="utf-8") commit(repo) assert hits(run(repo, "--diff", "HEAD~1").stdout) == truth(repo, "docs/m.md") @@ -326,7 +322,10 @@ def test_a_NON_UTF8_LOCALE_does_not_silently_empty_the_scan(repo: Path) -> None: env = dict(os.environ, LC_ALL="C", PYTHONUTF8="0", PYTHONIOENCODING="utf-8") p = subprocess.run( [sys.executable, str(SCRIPT), "--diff", "HEAD~1"], - cwd=repo, capture_output=True, text=True, env=env, + cwd=repo, + capture_output=True, + text=True, + env=env, ) assert p.returncode == 0, p.stderr assert "internal error" not in p.stdout, p.stdout @@ -348,13 +347,11 @@ def test_MUTATION_neutering_the_pattern_makes_a_known_hit_go_quiet(repo: Path, t disarmed = tmp_path / "disarmed.py" src = SCRIPT.read_text(encoding="utf-8") - marker = 'PATTERNS = re.compile(' + marker = "PATTERNS = re.compile(" assert src.count(marker) == 1 disarmed.write_text( src.replace(marker, 'PATTERNS = re.compile(r"(?!x)x" # disarmed\n or ', 1), encoding="utf-8" ) - p = subprocess.run( - [sys.executable, str(disarmed), "--all"], cwd=repo, capture_output=True, text=True - ) + p = subprocess.run([sys.executable, str(disarmed), "--all"], cwd=repo, capture_output=True, text=True) assert p.returncode == 0, p.stderr assert hits(p.stdout) == set(), "the disarmed detector still flagged something — the mutation did not take"