pytest-wirecheck 0.1.0__py3-none-any.whl

pytest_wirecheck-0.1.0.dist-info/METADATA

@@ -0,0 +1,175 @@
+Metadata-Version: 2.4
+Name: pytest-wirecheck
+Version: 0.1.0
+Summary: Record what your code really sends to the Claude API in tests, and fail the build if a request would break under API version 2026-10-21.
+Author: Ishan Yash
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/ishanyash/wirecheck
+Project-URL: Source, https://github.com/ishanyash/wirecheck
+Project-URL: Issues, https://github.com/ishanyash/wirecheck/issues
+Keywords: pytest,anthropic,claude,claude-api,migration,ci,lint
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: Pytest
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Quality Assurance
+Classifier: Topic :: Software Development :: Testing
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pytest>=8.0
+Provides-Extra: test
+Requires-Dist: anthropic>=2.0.0; extra == "test"
+Dynamic: license-file
+
+# WireCheck
+
+**Your tests pass. Your Claude API calls return 400. WireCheck checks what your code really sends to the Claude API in tests, and fails the build if a request would break under API version 2026-10-21.**
+
+![pytest --wirecheck failing on three hidden temperature bugs](https://raw.githubusercontent.com/ishanyash/wirecheck/main/docs/screenshot.png)
+
+[PyPI: pytest-wirecheck](https://pypi.org/project/pytest-wirecheck/) · [GitHub Marketplace: WireCheck for Claude API](https://github.com/marketplace/actions/wirecheck-for-claude-api) · [Demo](demo/)
+
+## Why
+
+On 21 Oct 2026 Anthropic released Claude API version `2026-10-21`. The new SDK majors (Python `anthropic` 2.0.0 and later) send it by default. Under it, a Messages request that sends `temperature`, `top_p` or `top_k` returns **400, even at the default value** ([migration guide](https://platform.claude.com/docs/en/api/migration-2026-10-21)).
+
+Most test suites mock the API, so they never see that 400. And these parameters are hard to grep for. Since `anthropic` 1.0.0, `temperature=` is no longer a keyword of `messages.create` (passing it is a `TypeError`, so tests catch it), and the SDK 1.0 migration guide said to pass it through `extra_body` instead. `extra_body` is merged into the JSON at runtime, so no type checker sees it, and it often sits in a shared wrapper or a defaults dict, far from the call. That is exactly how [Nojoin broke](https://github.com/Valtora/Nojoin/issues/554): a loose version floor pulled in `anthropic` 2.x, a wrapper still sent `temperature: 0.2` through `extra_body`, and the tests mocked the client, so they all passed.
+
+WireCheck looks at the final request as it leaves the HTTP client, after the SDK has merged every wrapper, default and `extra_body`.
+
+## Quick start
+
+```bash
+pip install pytest-wirecheck
+pytest --wirecheck
+```
+
+A test that sends a breaking request now fails, and the run ends with a short report. This is the [demo](demo/) on `anthropic` 2.3.0:
+
+```
+3 requests to the Claude API checked: 3 errors, 0 warnings
+anthropic SDK: 2.3.0; API versions seen: 2026-10-21 x3
+
+RULE   LEVEL  COUNT  TEST                                         CALL SITE                    WHAT
+WC001  error  1      broken/test_broken.py::test_direct_call      broken/app_direct.py:12      temperature
+WC001  error  1      broken/test_broken.py::test_extra_body       broken/app_extra_body.py:18  temperature
+WC001  error  1      broken/test_broken.py::test_wrapper_factory  broken/app_factory.py:21     top_p
+```
+
+Each row shows the rule, the test that sent the request, and the file and line in your code that made the call. Works with `pytest-xdist` too.
+
+### GitHub Action
+
+```yaml
+name: WireCheck
+on: pull_request
+permissions:
+  contents: read
+  pull-requests: write   # to post the findings comment
+jobs:
+  wirecheck:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/setup-python@v7
+        with:
+          python-version: "3.12"
+      - run: pip install -e ".[test]"        # your project and its test deps
+      - uses: ishanyash/wirecheck@v0.1.0
+        with:
+          pytest-args: tests/
+```
+
+The Action runs the static scan and your tests with `--wirecheck`, writes the findings to the job summary, and posts **one** pull request comment with a findings table (it updates the same comment on later pushes).
+
+| Input | Default | Meaning |
+|---|---|---|
+| `path` | `.` | Folders for the static scan |
+| `run-pytest` | `true` | Run `pytest --wirecheck` |
+| `pytest-args` | | Extra pytest arguments |
+| `working-directory` | `.` | Where to run |
+| `fail-on` | `error` | `error`, `warn` or `never` |
+| `comment` | `true` | Post the PR comment |
+| `install` | `action` | `action` installs WireCheck from the tagged Action source; `skip` if you install it yourself |
+
+## What it checks
+
+Rules come from the [migration guide](https://platform.claude.com/docs/en/api/migration-2026-10-21) and the [release notes](https://platform.claude.com/docs/en/release-notes/overview).
+
+**In the real requests your tests send (`pytest --wirecheck`):**
+
+| Rule | What | Level |
+|---|---|---|
+| WC001 | `temperature`, `top_p` or `top_k` in a Messages, token count or batch request | error on 2026-10-21 |
+| WC002 | `document` block directly in an `assistant` message | error on 2026-10-21 |
+| WC003 | `text` block with non-empty `citations` in a `user` message, including inside `search_result` | error on 2026-10-21 |
+| WC004 | `X-Api-Key` header set by your code. SDK 2.x sends `Authorization: Bearer`, so your key no longer replaces the client key (both are sent) | warning |
+| WC005 | `claude-opus-4-8` with `speed: "fast"` | warning now, error from 2026-11-30 |
+
+**In source (`wirecheck scan`):**
+
+| Rule | What | Level |
+|---|---|---|
+| WCS001 | `MessageParam(...)` / `BetaMessageParam(...)` called or subclassed (TypeError in SDK 2.x) | error |
+| WCS002 | `X-Api-Key` in `extra_headers` / `default_headers` | warning |
+| WCS003 | `ant --api-key` / `ant --auth-token` (removed in the `ant` CLI 2.0.0) | error |
+| WCS004 | Text Completions calls (`client.completions.create`, `/v1/complete`) | error |
+| WCS005 | `temperature` / `top_p` / `top_k` visible in a Messages call (a hint; the runtime check is the real one) | warning |
+
+```bash
+wirecheck scan .                 # text
+wirecheck scan src --format json # or markdown
+```
+
+## Which API version applies
+
+For each request WireCheck reads the `anthropic-version` header. If there is none, it uses the installed SDK (`anthropic` 2.0.0 and later means `2026-10-21`).
+
+- On `2026-10-21`, WC001 to WC003 are **errors** and fail the test that sent the request.
+- On `2023-06-01` (SDK 1.x and older), the same findings are **warnings**. Your code works today and breaks when you upgrade. Use `--wirecheck-fail-on=warn` to fail on them now.
+
+## How it works
+
+When enabled, the plugin wraps `Client.send` and `AsyncClient.send` of `httpx2` (used by `anthropic` 1.x and 2.x) and `httpx` (older SDKs). Every request to `api.anthropic.com`, `$ANTHROPIC_BASE_URL` or a `--wirecheck-base-url` is recorded before it reaches the transport, so it is seen even when the test mocks the response with a mock transport, `respx`, or the `wirecheck_stub` fixture, and even when there is no network. API keys are redacted before anything is stored. The hook is removed when the run ends.
+
+## Options
+
+| Option | Meaning |
+|---|---|
+| `--wirecheck` | Turn it on (or `wirecheck = true` in your pytest ini, or `WIRECHECK=1`) |
+| `--wirecheck-fail-on` | `error` (default), `warn`, or `never` |
+| `--wirecheck-base-url URL` | Also capture a gateway or proxy URL (repeatable) |
+| `--wirecheck-report PATH` | Write findings as JSON |
+| `--wirecheck-markdown PATH` | Write findings as Markdown |
+| `WIRECHECK_TODAY=YYYY-MM-DD` | Pin the date used by date-based rules |
+
+Fixtures and markers:
+
+- `wirecheck_stub` answers every Claude API request in a test with a canned reply, with no network. It mocks the response, not the client, so WireCheck still sees what you send. Set `wirecheck_stub["text"]` to change the reply.
+- `wirecheck_requests` lists the requests the current test sent.
+- `@pytest.mark.wirecheck_skip` ignores requests from one test.
+
+## Known limits
+
+- **It only sees requests that are really built.** If a test replaces `client.messages.create` (or the whole client) with a `MagicMock`, no request exists and WireCheck sees nothing. It prints a hint when a run captured no requests. Mock the HTTP response instead.
+- Python only, and only the `httpx` / `httpx2` HTTP clients (the SDK default). The optional `aiohttp` backend is not hooked.
+- Bedrock and Vertex requests go to other hosts and carry the version differently. Add their URL with `--wirecheck-base-url` if you want them recorded; version detection there falls back to the SDK version.
+- `wirecheck_stub` answers non-streaming calls only.
+- WC003 checks the places the guide names (user `text` blocks and `search_result` blocks). It does not flag bare `text` blocks inside `tool_result`, because the guide does not say.
+- The static scanner is a set of simple patterns. It misses anything assembled at runtime, which is why the pytest plugin exists.
+- No auto-fix and no TypeScript or other SDKs in v0.1.
+
+## Licence
+
+MIT. See [LICENSE](LICENSE).
+
+---
+
+Built by [Ishan Yash](https://ishanyash.com)

pytest_wirecheck-0.1.0.dist-info/RECORD

@@ -0,0 +1,16 @@
+pytest_wirecheck-0.1.0.dist-info/licenses/LICENSE,sha256=MuK8B3MG-z13clfuY50YCK1V2vcVKfjb5Jn1-IpM5XA,1067
+wirecheck/__init__.py,sha256=VO7vlDU6YC0km-9pW1oMQdEE0wK3wb-HUQ4xrI23N0c,93
+wirecheck/__main__.py,sha256=k1ocEWawweo1qCJWNFAAvyxz3tcY13dzvCenHszij30,48
+wirecheck/capture.py,sha256=ps1xUgsp2gD3rBDN8fHje6fNvNK1RMxcEGs5Vy8PyAY,8408
+wirecheck/cli.py,sha256=ocDEU6G1hUrhNPGiWlmC9j9abSAriDTVeYJ5sLG15Tc,3537
+wirecheck/clock.py,sha256=Lkx13akupxZE9IHjZsXHzNR2mi8YIZI4c6h3g85ll40,449
+wirecheck/plugin.py,sha256=3K5gwrSx_g-mRk_68HY5eEE0QUCUjPu952L248wHXr4,12292
+wirecheck/report.py,sha256=sP0oRWcsVLGWhBOw8KnQsT5Mg06-H1VZNMWi6D5p6jk,7588
+wirecheck/rules.py,sha256=H95XEuBlJsczdq8cQmYqVNs0kVDHifry-Bb87h1LFyE,8809
+wirecheck/scan.py,sha256=QeGyrtgQhGqPuyX6OS1-pR9595SUs7dAQjotUhJ2Nxs,12096
+wirecheck/versions.py,sha256=1436fYEgvr78aTZeol7MuSTjQsT3A2DxS7uez9mT1q4,1787
+pytest_wirecheck-0.1.0.dist-info/METADATA,sha256=o4wVKGC7T0dc86X9dCIiI7-maKE5zGiQ7ag6OgUh6ps,9642
+pytest_wirecheck-0.1.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+pytest_wirecheck-0.1.0.dist-info/entry_points.txt,sha256=R9WSrpOsfRyRPWBfLVtuWn4UGpLyww2kWZeAAFWCOQU,90
+pytest_wirecheck-0.1.0.dist-info/top_level.txt,sha256=ch9iUWiBVYpV5H6owQAPrfDLrX05pqZEx1b_U_A06wY,10
+pytest_wirecheck-0.1.0.dist-info/RECORD,,

pytest_wirecheck-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.2.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

pytest_wirecheck-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,5 @@
+[console_scripts]
+wirecheck = wirecheck.cli:main
+
+[pytest11]
+wirecheck = wirecheck.plugin

pytest_wirecheck-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ishan Yash
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

pytest_wirecheck-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+wirecheck

wirecheck/__init__.py

@@ -0,0 +1,3 @@
+"""WireCheck: check what your code really sends to the Claude API."""
+
+__version__ = "0.1.0"

wirecheck/__main__.py

@@ -0,0 +1,3 @@
+from .cli import main
+
+raise SystemExit(main())

wirecheck/capture.py

@@ -0,0 +1,231 @@
+"""Capture every request that leaves httpx / httpx2 for the Claude API.
+
+The hook wraps ``Client.send`` and ``AsyncClient.send`` at class level, so it sees
+the final request after the SDK has merged ``extra_body``, ``extra_headers`` and
+client defaults, and it sees it even when the test swaps in a mock transport.
+
+anthropic>=1.x uses httpx2; older SDKs use httpx. Both are hooked when importable.
+"""
+
+from __future__ import annotations
+
+import functools
+import importlib
+import json
+import os
+import sys
+import sysconfig
+from typing import Any, Callable
+
+from .rules import Captured
+
+DEFAULT_HOSTS = ("api.anthropic.com",)
+LIBRARIES = ("httpx2", "httpx")
+REDACT = {"x-api-key", "authorization", "proxy-authorization", "cookie"}
+
+def _norm(path: str) -> str:
+    """Pure string normalising, no file system calls.
+
+    The hook runs inside the user's event loop. Tools such as blockbuster raise on
+    blocking calls there (os.path.abspath, os.getcwd, ...), so nothing on the hot
+    path may touch the file system.
+    """
+    if os.name == "nt":
+        return path.replace("/", "\\").lower()
+    return path
+
+
+# Computed once at import time, outside any event loop.
+_THIS_DIR = _norm(os.path.dirname(os.path.abspath(__file__)))
+_LIB_DIRS = tuple(
+    _norm(os.path.abspath(p))
+    for p in {
+        sysconfig.get_paths().get("stdlib"),
+        sysconfig.get_paths().get("platstdlib"),
+        sysconfig.get_paths().get("purelib"),
+        sysconfig.get_paths().get("platlib"),
+    }
+    if p
+)
+_SEP = "\\" if os.name == "nt" else "/"
+
+
+def _is_library_file(filename: str) -> bool:
+    if not filename or filename.startswith("<"):
+        return True
+    path = _norm(filename)
+    if path.startswith(_THIS_DIR + _SEP):
+        return True
+    if f"{_SEP}site-packages{_SEP}" in path or f"{_SEP}dist-packages{_SEP}" in path:
+        return True
+    return path.startswith(_LIB_DIRS)
+
+
+def find_call_site(root: str | None = None, skip: int = 2) -> str | None:
+    """File and line of the innermost frame that belongs to the user's code."""
+    try:
+        frame = sys._getframe(skip)
+    except ValueError:
+        return None
+    prefix = _norm(root).rstrip(_SEP) + _SEP if root else None
+    while frame is not None:
+        filename = frame.f_code.co_filename
+        if not _is_library_file(filename):
+            shown = filename
+            if prefix and _norm(filename).startswith(prefix):
+                shown = filename[len(prefix):]
+            return f"{shown.replace(_SEP, '/')}:{frame.f_lineno}"
+        frame = frame.f_back
+    return None
+
+
+def _normalise_base(url: str) -> str:
+    url = url.strip().rstrip("/")
+    if "://" not in url:
+        url = "https://" + url
+    return url
+
+
+class Recorder:
+    """Holds the hook state. One active recorder at a time."""
+
+    def __init__(
+        self,
+        on_capture: Callable[[Captured], None],
+        base_urls: list[str] | None = None,
+        root: str | None = None,
+    ) -> None:
+        self.on_capture = on_capture
+        self.base_urls = [_normalise_base(u) for u in (base_urls or []) if u and u.strip()]
+        self.hosts = set(DEFAULT_HOSTS)
+        self.root = root
+        self.current_test: str | None = None
+        self.stub: dict[str, Any] | None = None  # set by the wirecheck_stub fixture
+        self._originals: list[tuple[type, str, Any]] = []
+        self.libraries: list[str] = []
+        self.errors: list[str] = []  # internal failures, shown in the report instead of hidden
+
+    # -- matching -----------------------------------------------------------
+    def matches(self, url: Any) -> bool:
+        host = getattr(url, "host", None)
+        if host in self.hosts:
+            return True
+        text = str(url)
+        return any(text == base or text.startswith(base + "/") for base in self.base_urls)
+
+    # -- observing ----------------------------------------------------------
+    def observe(self, request: Any, library: str) -> None:
+        if not self.matches(request.url):
+            return
+        headers: dict[str, str] = {}
+        for name, value in request.headers.items():
+            key = name.lower()
+            headers[key] = "<redacted>" if key in REDACT else value
+        body: Any = None
+        try:
+            raw = request.content  # raises if the body is an unread stream
+        except Exception:
+            raw = None
+        if raw:
+            try:
+                body = json.loads(raw)
+            except (ValueError, UnicodeDecodeError):
+                body = None
+        try:
+            call_site = find_call_site(self.root, skip=3)
+        except Exception as exc:  # a missing call site must not lose the request
+            self.errors.append(f"call site: {exc!r}")
+            call_site = None
+        captured = Captured(
+            method=request.method,
+            url=str(request.url),
+            path=request.url.path,
+            headers=headers,
+            body=body,
+            test=self.current_test,
+            call_site=call_site,
+            library=library,
+        )
+        # No lock: list.append is atomic, and lock waits count as blocking calls in async checkers.
+        self.on_capture(captured)
+
+    def stub_response(self, request: Any, module: Any) -> Any | None:
+        if self.stub is None or not self.matches(request.url):
+            return None
+        path = request.url.path.rstrip("/")
+        if path.endswith("/v1/messages/count_tokens"):
+            payload: Any = {"input_tokens": 1}
+        elif path.endswith("/v1/messages"):
+            model = "stub"
+            try:
+                model = json.loads(request.content).get("model", model)
+            except Exception:
+                pass
+            payload = {
+                "id": "msg_wirecheck_stub",
+                "type": "message",
+                "role": "assistant",
+                "model": model,
+                "content": [{"type": "text", "text": self.stub.get("text", "stub reply")}],
+                "stop_reason": "end_turn",
+                "stop_sequence": None,
+                "usage": {"input_tokens": 1, "output_tokens": 1},
+            }
+        else:
+            payload = {}
+        return module.Response(200, json=payload, request=request)
+
+    # -- install / uninstall -------------------------------------------------
+    def install(self) -> None:
+        for name in LIBRARIES:
+            try:
+                module = importlib.import_module(name)
+            except Exception:
+                continue
+            self._patch(module, name)
+            self.libraries.append(name)
+
+    def _patch(self, module: Any, name: str) -> None:
+        recorder = self
+        sync_orig = module.Client.send
+        async_orig = module.AsyncClient.send
+
+        def hook(request: Any) -> Any:
+            # Never break the user's test because of us, but never hide a failure either:
+            # it is counted and shown in the report.
+            try:
+                recorder.observe(request, name)
+            except Exception as exc:
+                recorder.errors.append(f"{request.method} {request.url}: {exc!r}")
+            try:
+                return recorder.stub_response(request, module)
+            except Exception as exc:
+                recorder.errors.append(f"stub: {exc!r}")
+                return None
+
+        @functools.wraps(sync_orig)
+        def send(client: Any, request: Any, *args: Any, **kwargs: Any) -> Any:
+            stubbed = hook(request)
+            if stubbed is not None:
+                return stubbed
+            return sync_orig(client, request, *args, **kwargs)
+
+        @functools.wraps(async_orig)
+        async def asend(client: Any, request: Any, *args: Any, **kwargs: Any) -> Any:
+            stubbed = hook(request)
+            if stubbed is not None:
+                return stubbed
+            return await async_orig(client, request, *args, **kwargs)
+
+        send.__wirecheck__ = True  # type: ignore[attr-defined]
+        asend.__wirecheck__ = True  # type: ignore[attr-defined]
+        self._originals.append((module.Client, "send", sync_orig))
+        self._originals.append((module.AsyncClient, "send", async_orig))
+        module.Client.send = send
+        module.AsyncClient.send = asend
+
+    def uninstall(self) -> None:
+        while self._originals:
+            cls, attr, orig = self._originals.pop()
+            setattr(cls, attr, orig)
+        self.libraries.clear()

wirecheck/cli.py

@@ -0,0 +1,93 @@
+"""Command line: ``wirecheck scan`` and ``wirecheck comment``."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+from typing import Any, Sequence
+
+from . import __version__, report, scan
+
+
+def _load(path: str | None) -> dict[str, Any] | None:
+    if not path or not os.path.exists(path):
+        return None
+    with open(path, encoding="utf-8") as fh:
+        return json.load(fh)
+
+
+def _exit_code(findings: list[dict[str, Any]], fail_on: str) -> int:
+    if fail_on == "never":
+        return 0
+    if fail_on == "warn":
+        return 1 if findings else 0
+    return 1 if any(f["severity"] == "error" for f in findings) else 0
+
+
+def cmd_scan(args: argparse.Namespace) -> int:
+    data = scan.scan(args.paths or ["."])
+    if args.format == "json":
+        text = json.dumps(data, indent=2) + "\n"
+    elif args.format == "markdown":
+        text = report.render_markdown(None, data)
+    else:
+        text = scan.render_text(data) + "\n"
+    if args.output:
+        with open(args.output, "w", encoding="utf-8") as fh:
+            fh.write(text)
+    else:
+        sys.stdout.write(text)
+    return _exit_code(data["findings"], args.fail_on)
+
+
+def cmd_comment(args: argparse.Namespace) -> int:
+    pytest_data, scan_data = _load(args.pytest), _load(args.scan)
+    text = report.render_markdown(pytest_data, scan_data, pytest_exit=args.pytest_exit)
+    if args.output:
+        with open(args.output, "w", encoding="utf-8") as fh:
+            fh.write(text)
+    elif not args.counts:
+        sys.stdout.write(text)
+    if args.counts:
+        findings = (pytest_data or {}).get("findings", []) + (scan_data or {}).get("findings", [])
+        errors = sum(1 for f in findings if f["severity"] == "error")
+        sys.stdout.write(f"errors={errors}\nwarnings={len(findings) - errors}\n")
+    return 0
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="wirecheck",
+        description="Check code for Claude API version 2026-10-21 problems. "
+        "For the runtime check, run: pytest --wirecheck",
+    )
+    parser.add_argument("--version", action="version", version=f"wirecheck {__version__}")
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    p = sub.add_parser("scan", help="Scan source files for things that break under 2026-10-21.")
+    p.add_argument("paths", nargs="*", help="Files or folders (default: .)")
+    p.add_argument("--format", choices=("text", "json", "markdown"), default="text")
+    p.add_argument("--output", "-o", help="Write to this file instead of stdout.")
+    p.add_argument("--fail-on", choices=("error", "warn", "never"), default="error",
+                   help="Exit 1 on errors (default), on any finding, or never.")
+    p.set_defaults(func=cmd_scan)
+
+    c = sub.add_parser("comment", help="Build the Markdown PR comment from JSON reports.")
+    c.add_argument("--pytest", help="JSON from pytest --wirecheck-report")
+    c.add_argument("--scan", help="JSON from wirecheck scan --format json")
+    c.add_argument("--pytest-exit", type=int, default=None, help="pytest exit code, noted in the comment if unusual")
+    c.add_argument("--output", "-o")
+    c.add_argument("--counts", action="store_true", help="Print errors=N and warnings=N (for GitHub outputs).")
+    c.set_defaults(func=cmd_comment)
+    return parser
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    args = build_parser().parse_args(argv)
+    return args.func(args)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

wirecheck/clock.py

@@ -0,0 +1,17 @@
+"""One place to read "today", so tests can freeze it.
+
+Set WIRECHECK_TODAY=YYYY-MM-DD to pin the date (handy in CI), or monkeypatch
+``wirecheck.clock.today`` in a test.
+"""
+
+from __future__ import annotations
+
+import datetime as _dt
+import os
+
+
+def today() -> _dt.date:
+    override = os.environ.get("WIRECHECK_TODAY", "").strip()
+    if override:
+        return _dt.date.fromisoformat(override)
+    return _dt.datetime.now(_dt.timezone.utc).date()