httpx2-audit 0.1.0__py3-none-any.whl

httpx2_audit-0.1.0.dist-info/METADATA

@@ -0,0 +1,108 @@
+Metadata-Version: 2.4
+Name: httpx2-audit
+Version: 0.1.0
+Summary: Find what breaks when your Python stack moves from httpx to httpx2: static audit, import/dependency codemod and a mixed-stack/TLS environment report.
+Author-email: agent-one <rafal.baranowski.iot@gmail.com>
+License: MIT
+Project-URL: Homepage, https://github.com/rafal-one/httpx2-audit
+Keywords: httpx,httpx2,migration,codemod,audit,openai,anthropic,respx,pytest-httpx
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Quality Assurance
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# httpx2-audit
+
+Find what breaks when your Python stack moves from **httpx** to **httpx2** (the pydantic fork; openai 3.x,
+anthropic 1.x, Starlette, the MCP SDK and huggingface_hub already switched). Pure stdlib, Python 3.9+
+(it analyses code, it does not import httpx), no network except the optional TLS probe.
+
+Unofficial community tool, not affiliated with httpx, httpx2 or pydantic. State as of 2026-10-18.
+
+## Why
+
+The move breaks things *silently*: `import httpx` fails once an SDK stops pulling it in; `respx` and
+`pytest-httpx` mocks stop intercepting, so tests hit the live API; `except httpx.ConnectError` no longer
+catches errors raised by httpx2 code; httpx clients passed as `http_client=` are the wrong type; TLS switches
+from the certifi bundle to the OS trust store.
+
+```
+pip install httpx2-audit     # or: pip install git+https://github.com/rafal-one/httpx2-audit
+```
+
+## `check`: static audit
+
+```
+$ httpx2-audit check src/
+src/app.py:1:1: HX001 imports httpx; httpx2 is a separate package with its own module name [info]
+src/app.py:4:36: HX004 httpx object or http_client passed on; an httpx2-based SDK needs httpx2 objects (http_client) [warning]
+src/app.py:7:8: HX003 except clause names an httpx exception; errors raised by httpx2-based code are not caught (httpx.ConnectError) [warning]
+```
+
+| Rule | Severity | Meaning |
+|---|---|---|
+| HX001 | info | `import httpx` / `from httpx import ...` |
+| HX002 | error | httpx imported but not declared in pyproject/requirements (transitive install is gone) |
+| HX003 | warning | `except httpx.X` (also aliases and tuples) |
+| HX004 | warning | `http_client=` or any httpx object (`httpx.Timeout`, `httpx.Limits`, ...) passed to a non-httpx call |
+| HX005 | warning | `isinstance`/`issubclass` against httpx classes |
+| HX006 | warning | `import httpcore` (httpx2 uses httpcore2) |
+| HX007 | warning | `respx` / `pytest_httpx` imports: they do not mock httpx2 |
+| HX008 | info | `certifi.where()` passed explicitly while httpx is in use |
+| HX010 | warning | file imports both httpx and httpx2 |
+
+Options: `--format text|json|sarif` (SARIF for GitHub code scanning), `--min-severity`, `--fail-on
+info|warning|error|never` (default `warning`), `-q` (no footer). Exit codes: `0` nothing at or above
+`--fail-on`, `1` findings, `2` bad usage or missing path. Directories like `.venv`, `node_modules`, `build`
+are skipped; files that do not parse are reported on stderr and skipped. Imports already wrapped in
+`try: import httpx2 ... except ImportError: import httpx` are treated as handled.
+
+CI: `httpx2-audit check . --format sarif > audit.sarif`, or just `httpx2-audit check . --fail-on error`.
+
+## `fix`: import and dependency codemod
+
+Dry run by default (prints a unified diff); `--write` applies it.
+
+```
+httpx2-audit fix .                # diff
+httpx2-audit fix . --write        # apply
+httpx2-audit fix . --dual --write # libraries: try httpx2, fall back to httpx
+```
+
+* `import httpx` -> `import httpx2 as httpx` (so the rest of the file keeps working), `from httpx import X`
+  -> `from httpx2 import X`; same for `httpcore` -> `httpcore2` and `pytest_httpx` -> `pytest_httpx2`.
+* `requirements*.txt` and `pyproject.toml` requirement strings: `httpx` -> `httpx2>=2.0`, `httpcore`,
+  `pytest-httpx` (extras and markers are kept).
+* `--dual` wraps each import in a `try/except ImportError` and leaves dependencies alone.
+* Private modules (`httpx._models`) and dotted imports are reported as `manual:` and left untouched.
+* It does not touch `except` clauses, `respx` mocks or TLS settings; run `check` afterwards. httpx2 needs Python 3.10+.
+
+## `env`: mixed stacks and TLS
+
+```
+$ httpx2-audit env --probe api.openai.com --probe intranet.corp:8443
+installed:
+  httpx              0.28.1
+  httpx2             2.14.0
+depend on httpx:  respx
+depend on httpx2: pytest-httpx2
+tls intranet.corp:8443: openssl-default=ok, certifi=FAIL: CERTIFICATE_VERIFY_FAILED, truststore=ok
+WARNING: TLS trust differs for intranet.corp:8443: ...
+```
+
+Lists the relevant installed distributions, which installed packages require httpx or httpx2 (a mixed
+environment cannot pass clients between them), and compares what the system store, certifi and truststore
+(if installed) accept for the hosts you probe. Exit code `1` when warnings are printed.
+
+## Development
+
+`pytest` (37 tests). Tested on Python 3.9 and 3.14; clean installs of wheel and sdist checked.
+
+## Donate
+
+If this saved your migration a day: https://paypal.me/RafalBaranowski
+
+MIT licensed.

httpx2_audit-0.1.0.dist-info/RECORD

@@ -0,0 +1,7 @@
+httpx2_audit.py,sha256=a9uJCWNlIA9gG6fK4qa6pmQeWgtYCBsTR891bgg96o0,24474
+httpx2_audit-0.1.0.dist-info/licenses/LICENSE,sha256=-hZriFiksFsGGM2WbhdnQzoXUOFuMGve5P3y4pvA0Ws,1066
+httpx2_audit-0.1.0.dist-info/METADATA,sha256=Qcgu6nUbcb7cY0zc3At8OoPHzLRNg29MlOvCR08EPl0,5207
+httpx2_audit-0.1.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+httpx2_audit-0.1.0.dist-info/entry_points.txt,sha256=6ehiU6UNvfmy90hhE6TLmVgcbDYz9zKxXj41kNbGfec,51
+httpx2_audit-0.1.0.dist-info/top_level.txt,sha256=BfRObduluR_FQQDRTFdEq4SuTKxawIVsYSiTprWPl2U,13
+httpx2_audit-0.1.0.dist-info/RECORD,,

httpx2_audit-0.1.0.dist-info/WHEEL

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

httpx2_audit-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+httpx2-audit = httpx2_audit:main

httpx2_audit-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,9 @@
+MIT License
+
+Copyright (c) 2026 agent-one
+
+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.

httpx2_audit-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+httpx2_audit

httpx2_audit.py

@@ -0,0 +1,598 @@
+"""httpx2-audit: find what breaks when a Python stack moves from httpx to httpx2."""
+import argparse
+import ast
+import json
+import os
+import re
+import socket
+import ssl
+import sys
+from importlib import metadata
+
+__version__ = "0.1.0"
+
+DONATE = "https://paypal.me/RafalBaranowski"
+SKIP_DIRS = {".git", ".hg", ".venv", "venv", "env", "node_modules", "build", "dist",
+             "site-packages", "__pycache__", ".tox", ".nox", ".mypy_cache", ".eggs"}
+SEV_ORDER = {"info": 0, "warning": 1, "error": 2}
+
+RULES = {
+    "HX001": ("info", "imports httpx; httpx2 is a separate package with its own module name"),
+    "HX002": ("error", "httpx is imported but not declared as a dependency; SDKs that moved to httpx2 no longer install it"),
+    "HX003": ("warning", "except clause names an httpx exception; errors raised by httpx2-based code are not caught"),
+    "HX004": ("warning", "httpx object or http_client passed on; an httpx2-based SDK needs httpx2 objects"),
+    "HX005": ("warning", "isinstance/issubclass against an httpx class fails for httpx2 objects"),
+    "HX006": ("warning", "imports httpcore; httpx2 is built on httpcore2"),
+    "HX007": ("warning", "test mock library for httpx; it does not intercept httpx2 requests, so tests may reach the live API"),
+    "HX008": ("info", "certifi bundle passed explicitly; httpx2 defaults to the OS trust store (truststore)"),
+    "HX010": ("warning", "file imports both httpx and httpx2"),
+}
+
+# import name -> (distribution, replacement import name, replacement distribution spec)
+SWAP_MODULES = {
+    "httpx": "httpx2",
+    "httpcore": "httpcore2",
+    "pytest_httpx": "pytest_httpx2",
+}
+SWAP_DISTS = {
+    "httpx": ("httpx2", ">=2.0"),
+    "httpcore": ("httpcore2", ">=2.0"),
+    "pytest-httpx": ("pytest-httpx2", ">=1.0"),
+}
+MOCK_MODULES = {"respx", "pytest_httpx"}
+WATCH_DISTS = {"httpx", "httpx2", "httpcore", "httpcore2", "respx", "pytest-httpx", "pytest-httpx2"}
+
+
+def norm(name):
+    return re.sub(r"[-_.]+", "-", name).lower()
+
+
+class Finding(dict):
+    pass
+
+
+def finding(rule, path, line, col, detail=""):
+    sev, msg = RULES[rule]
+    return Finding(rule=rule, severity=sev, path=path, line=line, col=col,
+                   message=msg + (" (%s)" % detail if detail else ""))
+
+
+# ----------------------------------------------------------------- manifests
+
+REQ_RE = re.compile(r"^\s*([A-Za-z0-9][A-Za-z0-9._-]*)\s*(\[[^\]]*\])?\s*([<>=!~].*?)?\s*(;.*)?$")
+
+
+def iter_files(roots, pred):
+    for root in roots:
+        if os.path.isfile(root):
+            if pred(os.path.basename(root)):
+                yield root
+            continue
+        for dp, dns, fns in os.walk(root):
+            dns[:] = sorted(d for d in dns if d not in SKIP_DIRS and not d.endswith(".egg-info"))
+            for fn in sorted(fns):
+                if pred(fn):
+                    yield os.path.join(dp, fn)
+
+
+def is_manifest(fn):
+    return fn == "pyproject.toml" or (fn.startswith("requirements") and fn.endswith((".txt", ".in")))
+
+
+def manifest_requirements(path):
+    """Yield (lineno, requirement-name) for requirement-looking lines/strings."""
+    try:
+        with open(path, encoding="utf-8") as f:
+            lines = f.read().splitlines()
+    except (OSError, UnicodeDecodeError):
+        return
+    for i, line in enumerate(lines, 1):
+        if path.endswith("pyproject.toml"):
+            for m in re.finditer(r"""["']([^"'\n]+)["']""", line):
+                r = REQ_RE.match(m.group(1))
+                if r and norm(r.group(1)) in WATCH_DISTS:
+                    yield i, norm(r.group(1))
+        else:
+            s = line.split("#", 1)[0].strip()
+            if s and not s.startswith("-"):
+                r = REQ_RE.match(s)
+                if r:
+                    yield i, norm(r.group(1))
+
+
+def declared_deps(roots):
+    found = set()
+    manifests = list(iter_files(roots, is_manifest))
+    for m in manifests:
+        for _, name in manifest_requirements(m):
+            found.add(name)
+    return found, manifests
+
+
+# ------------------------------------------------------------------- scanner
+
+class Scanner(ast.NodeVisitor):
+    def __init__(self, path, tree):
+        self.path = path
+        self.out = []
+        self.mod_alias = {}   # local name -> module ("httpx"/"httpcore"/...)
+        self.name_alias = {}  # local name -> "httpx.Client"
+        self.dual = set()     # ids of import nodes inside try/except ImportError
+        self.imports = []     # (node, module) for httpx imports (for HX002/HX010)
+        self.uses_httpx = False
+        self.uses_httpx2 = False
+        self._mark_dual(tree)
+        self.tree = tree
+
+    def add(self, rule, node, detail=""):
+        self.out.append(finding(rule, self.path, node.lineno, node.col_offset + 1, detail))
+
+    def _mark_dual(self, tree):
+        for node in ast.walk(tree):
+            if isinstance(node, ast.Try):
+                catches = False
+                for h in node.handlers:
+                    names = []
+                    if h.type is not None:
+                        names = [n for n in ast.walk(h.type) if isinstance(n, ast.Name)]
+                    if h.type is None or any(n.id in ("ImportError", "ModuleNotFoundError") for n in names):
+                        catches = True
+                if not catches:
+                    continue
+                for part in (node.body, *[h.body for h in node.handlers]):
+                    for st in part:
+                        if isinstance(st, (ast.Import, ast.ImportFrom)):
+                            self.dual.add(id(st))
+
+    def resolve(self, node):
+        """Dotted name for Name/Attribute chains, with import aliases resolved."""
+        parts = []
+        while isinstance(node, ast.Attribute):
+            parts.append(node.attr)
+            node = node.value
+        if not isinstance(node, ast.Name):
+            return None
+        head = node.id
+        if head in self.name_alias:
+            base = self.name_alias[head]
+        elif head in self.mod_alias:
+            base = self.mod_alias[head]
+        else:
+            return None
+        return ".".join([base] + parts[::-1])
+
+    def mentions(self, node, prefix="httpx"):
+        for n in ast.walk(node):
+            if isinstance(n, (ast.Name, ast.Attribute)):
+                r = self.resolve(n)
+                if r and (r == prefix or r.startswith(prefix + ".")):
+                    return True
+        return False
+
+    def visit_Import(self, node):
+        for a in node.names:
+            top = a.name.split(".")[0]
+            local = a.asname or top
+            if top in ("httpx", "httpx2", "httpcore", "httpcore2", "respx", "pytest_httpx", "certifi"):
+                self.mod_alias[local] = top if a.asname is None or "." not in a.name else a.name
+            self._module_seen(node, a.name)
+        self.generic_visit(node)
+
+    def visit_ImportFrom(self, node):
+        if node.level == 0 and node.module:
+            top = node.module.split(".")[0]
+            for a in node.names:
+                if top in ("httpx", "httpx2", "httpcore", "httpcore2", "respx", "pytest_httpx"):
+                    self.name_alias[a.asname or a.name] = node.module + "." + a.name
+            self._module_seen(node, node.module)
+        self.generic_visit(node)
+
+    def _module_seen(self, node, module):
+        top = module.split(".")[0]
+        is_dual = id(node) in self.dual
+        if top == "httpx2":
+            self.uses_httpx2 = True
+        if top == "httpx":
+            self.uses_httpx = not is_dual or self.uses_httpx
+            if not is_dual:
+                self.imports.append((node, top))
+                self.add("HX001", node)
+        elif top == "httpcore" and not is_dual:
+            self.add("HX006", node)
+        elif top in MOCK_MODULES:
+            self.add("HX007", node, top)
+
+    def visit_ExceptHandler(self, node):
+        if node.type is not None:
+            elts = node.type.elts if isinstance(node.type, ast.Tuple) else [node.type]
+            for e in elts:
+                r = self.resolve(e)
+                if r and r.startswith("httpx."):
+                    self.add("HX003", e, r)
+        self.generic_visit(node)
+
+    def visit_Call(self, node):
+        fn = self.resolve(node.func)
+        if isinstance(node.func, ast.Name) and node.func.id in ("isinstance", "issubclass") and len(node.args) >= 2:
+            if self.mentions(node.args[1]):
+                self.add("HX005", node, self.resolve(node.args[1]) or "")
+        callee_httpx = bool(fn and (fn == "httpx" or fn.startswith("httpx.")))
+        for kw in node.keywords:
+            if kw.arg is None or callee_httpx:
+                continue
+            if kw.arg in ("http_client", "http_async_client") or self.mentions(kw.value):
+                self.add("HX004", kw.value, kw.arg)
+        if fn == "certifi.where" and (self.uses_httpx or self.uses_httpx2):
+            self.add("HX008", node)
+        self.generic_visit(node)
+
+
+def scan_file(path):
+    try:
+        with open(path, "rb") as f:
+            src = f.read()
+        tree = ast.parse(src, filename=path)
+    except (OSError, SyntaxError, ValueError) as e:
+        return None, str(e)
+    sc = Scanner(path, tree)
+    # first pass records imports/aliases so later uses resolve; imports come first in practice
+    sc.visit(tree)
+    if sc.uses_httpx and sc.uses_httpx2:
+        sc.add("HX010", sc.imports[0][0] if sc.imports else tree.body[0])
+    return sc, None
+
+
+def run_check(paths, declared=None):
+    findings, skipped, nfiles = [], [], 0
+    if declared is None:
+        declared, manifests = declared_deps(paths)
+    else:
+        manifests = []
+    for p in iter_files(paths, lambda fn: fn.endswith(".py")):
+        nfiles += 1
+        sc, err = scan_file(p)
+        if sc is None:
+            skipped.append({"path": p, "error": err})
+            continue
+        findings.extend(sc.out)
+        if sc.imports and manifests and not ({"httpx", "httpx2"} & declared):
+            node = sc.imports[0][0]
+            findings.append(finding("HX002", p, node.lineno, node.col_offset + 1))
+    findings.sort(key=lambda f: (f["path"], f["line"], f["col"], f["rule"]))
+    return {"findings": findings, "skipped": skipped, "files": nfiles,
+            "manifests": manifests, "declared": sorted(declared)}
+
+
+# ---------------------------------------------------------------------- fix
+
+def _swap_import(node, lines, dual):
+    """Return (start_line, end_line, new_text) or (None, reason)."""
+    start, end = node.lineno - 1, node.end_lineno - 1
+    seg = lines[start:end + 1]
+    first = seg[0]
+    indent = first[:node.col_offset]
+    if first[:node.col_offset].strip():
+        return None, "statement does not start its line"
+    text = "\n".join(seg)
+    text = text[node.col_offset:]
+    if ";" in text.split("#", 1)[0]:
+        return None, "multiple statements on one line"
+    if isinstance(node, ast.Import):
+        if any("." in a.name for a in node.names):
+            return None, "dotted import of a private/submodule"
+        if dual:
+            if len(node.names) != 1:
+                return None, "multi-name import in dual mode"
+            a = node.names[0]
+            local = a.asname or a.name
+            new = SWAP_MODULES[a.name]
+            body = "%stry:\n%s    import %s as %s\n%sexcept ImportError:  # pragma: no cover\n%s    %s" % (
+                indent, indent, new, local, indent, indent, text)
+            return (start, end, body), None
+        parts = []
+        for a in node.names:
+            if a.name in SWAP_MODULES:
+                parts.append("%s as %s" % (SWAP_MODULES[a.name], a.asname or a.name))
+            else:
+                parts.append(a.name + (" as " + a.asname if a.asname else ""))
+        return (start, end, indent + "import " + ", ".join(parts)), None
+    # ImportFrom
+    if node.module != node.module.split(".")[0] and node.module.split(".")[0] in SWAP_MODULES:
+        return None, "import from a private/submodule (%s)" % node.module
+    new_mod = SWAP_MODULES[node.module]
+    new_text = re.sub(r"\bfrom(\s+)%s\b" % re.escape(node.module), r"from\g<1>%s" % new_mod, text, count=1)
+    if dual:
+        body = "%stry:\n%s    %s\n%sexcept ImportError:  # pragma: no cover\n%s    %s" % (
+            indent, indent, new_text.replace("\n", "\n    "), indent, indent, text.replace("\n", "\n    "))
+        return (start, end, body), None
+    return (start, end, indent + new_text), None
+
+
+def fix_source(src, dual=False):
+    """Return (new_source, changes, unfixable) for one Python file's source text."""
+    try:
+        tree = ast.parse(src)
+    except SyntaxError:
+        return src, [], []
+    sc = Scanner("<s>", tree)
+    sc.visit(tree)
+    lines = src.split("\n")
+    edits, unfixable = [], []
+    for node in ast.walk(tree):
+        if id(node) in sc.dual:
+            continue
+        mod = None
+        if isinstance(node, ast.Import):
+            mods = [a.name.split(".")[0] for a in node.names]
+            if any(m in SWAP_MODULES for m in mods):
+                mod = True
+        elif isinstance(node, ast.ImportFrom) and node.level == 0 and node.module:
+            if node.module.split(".")[0] in SWAP_MODULES:
+                mod = True
+        if not mod:
+            continue
+        res, reason = _swap_import(node, lines, dual)
+        if res is None:
+            unfixable.append((node.lineno, reason))
+        else:
+            edits.append((res, node.lineno))
+    changes = []
+    for (s, e, text), ln in sorted(edits, key=lambda x: -x[0][0]):
+        lines[s:e + 1] = text.split("\n")
+        changes.append(ln)
+    return "\n".join(lines), sorted(changes), unfixable
+
+
+def fix_manifest_text(text, is_pyproject):
+    """Swap httpx/httpcore/pytest-httpx requirements for their *2 counterparts."""
+    changes = []
+
+    def repl_req(s):
+        m = REQ_RE.match(s)
+        if not m:
+            return s
+        n = norm(m.group(1))
+        if n not in SWAP_DISTS:
+            return s
+        new, spec = SWAP_DISTS[n]
+        return "%s%s%s%s" % (new, m.group(2) or "", spec, (" " + m.group(4).strip()) if m.group(4) else "")
+
+    out = []
+    for i, line in enumerate(text.split("\n"), 1):
+        new = line
+        if is_pyproject:
+            new = re.sub(r"""(["'])([^"'\n]+)\1""", lambda m: m.group(1) + repl_req(m.group(2)) + m.group(1), line)
+        else:
+            body, sep, comment = line.partition("#")
+            if body.strip() and not body.strip().startswith("-"):
+                lead = body[:len(body) - len(body.lstrip())]
+                trail = " " if sep and body.endswith(" ") else ""
+                new = lead + repl_req(body.strip()) + trail + sep + comment
+        if new != line:
+            changes.append(i)
+        out.append(new)
+    return "\n".join(out), changes
+
+
+def run_fix(paths, write=False, dual=False):
+    import difflib
+    report = {"files": [], "unfixable": [], "diff": ""}
+    diffs = []
+    for p in iter_files(paths, lambda fn: fn.endswith(".py")):
+        try:
+            with open(p, encoding="utf-8") as f:
+                src = f.read()
+        except (OSError, UnicodeDecodeError):
+            continue
+        new, changes, unfix = fix_source(src, dual)
+        for ln, why in unfix:
+            report["unfixable"].append({"path": p, "line": ln, "reason": why})
+        if new != src:
+            report["files"].append(p)
+            diffs.append("".join(difflib.unified_diff(src.splitlines(True), new.splitlines(True), p, p)))
+            if write:
+                with open(p, "w", encoding="utf-8") as f:
+                    f.write(new)
+    if not dual:
+        for m in iter_files(paths, is_manifest):
+            try:
+                with open(m, encoding="utf-8") as f:
+                    src = f.read()
+            except (OSError, UnicodeDecodeError):
+                continue
+            new, changes = fix_manifest_text(src, m.endswith("pyproject.toml"))
+            if new != src:
+                report["files"].append(m)
+                diffs.append("".join(difflib.unified_diff(src.splitlines(True), new.splitlines(True), m, m)))
+                if write:
+                    with open(m, "w", encoding="utf-8") as f:
+                        f.write(new)
+    report["diff"] = "".join(diffs)
+    return report
+
+
+# ----------------------------------------------------------------------- env
+
+def installed_report():
+    dists = {}
+    for d in metadata.distributions():
+        name = norm(d.metadata["Name"] or "")
+        if name:
+            dists[name] = d
+    rows = {n: dists[n].version for n in sorted(WATCH_DISTS | {"certifi", "truststore", "openai", "anthropic",
+                                                              "mcp", "starlette", "huggingface-hub"}) if n in dists}
+    uses = {"httpx": [], "httpx2": []}
+    for n, d in sorted(dists.items()):
+        for r in d.requires or []:
+            m = REQ_RE.match(r.split(";")[0].strip())
+            if not m or "extra ==" in r.replace('"', "'").replace("extra==", "extra =="):
+                continue
+            rn = norm(m.group(1))
+            if rn in uses and n not in ("httpx", "httpx2"):
+                uses[rn].append(n)
+    return rows, uses
+
+
+def tls_probe(host, port=443, timeout=5.0):
+    result = {}
+    ctxs = {"openssl-default": ssl.create_default_context()}
+    try:
+        import certifi
+        ctxs["certifi"] = ssl.create_default_context(cafile=certifi.where())
+    except ImportError:
+        pass
+    try:
+        import truststore
+        ctxs["truststore"] = truststore.SSLContext(ssl.PROTOCOL_TLS_CLIENT)
+    except ImportError:
+        pass
+    for name, ctx in ctxs.items():
+        try:
+            with socket.create_connection((host, port), timeout=timeout) as s:
+                with ctx.wrap_socket(s, server_hostname=host):
+                    result[name] = "ok"
+        except (ssl.SSLError, OSError) as e:
+            result[name] = "FAIL: %s" % (getattr(e, "reason", None) or e)
+    return result
+
+
+def run_env(probes):
+    rows, uses = installed_report()
+    warnings = []
+    if uses["httpx"] and uses["httpx2"]:
+        warnings.append("mixed stack: %s need httpx, %s need httpx2; objects cannot cross over" %
+                        (", ".join(uses["httpx"]), ", ".join(uses["httpx2"])))
+    if "respx" in rows or "pytest-httpx" in rows:
+        if "httpx2" in rows and "pytest-httpx2" not in rows:
+            warnings.append("httpx2 installed but only the httpx mock libraries are: tests will not be intercepted")
+    if "httpx2" in rows and sys.version_info < (3, 10):
+        warnings.append("httpx2 requires Python 3.10+")
+    tls = {}
+    for p in probes:
+        host, _, port = p.partition(":")
+        tls[p] = tls_probe(host, int(port) if port else 443)
+        vals = list(tls[p].values())
+        if len(set(v == "ok" for v in vals)) > 1:
+            warnings.append("TLS trust differs for %s: %s" % (p, ", ".join("%s=%s" % kv for kv in tls[p].items())))
+    return {"installed": rows, "httpx_dependents": uses["httpx"], "httpx2_dependents": uses["httpx2"],
+            "tls": tls, "warnings": warnings}
+
+
+# -------------------------------------------------------------------- output
+
+def to_sarif(findings):
+    rules = [{"id": k, "shortDescription": {"text": v[1]}} for k, v in RULES.items()]
+    lvl = {"info": "note", "warning": "warning", "error": "error"}
+    return {"version": "2.1.0", "$schema": "https://json.schemastore.org/sarif-2.1.0.json",
+            "runs": [{"tool": {"driver": {"name": "httpx2-audit", "version": __version__,
+                                          "informationUri": "https://github.com/rafal-one/httpx2-audit",
+                                          "rules": rules}},
+                      "results": [{"ruleId": f["rule"], "level": lvl[f["severity"]],
+                                   "message": {"text": f["message"]},
+                                   "locations": [{"physicalLocation": {
+                                       "artifactLocation": {"uri": f["path"].replace(os.sep, "/")},
+                                       "region": {"startLine": f["line"], "startColumn": f["col"]}}}]}
+                                  for f in findings]}]}
+
+
+def footer():
+    return "httpx2-audit is free (MIT). If it saved you time: %s" % DONATE
+
+
+def cmd_check(a):
+    for p in a.paths:
+        if not os.path.exists(p):
+            print("httpx2-audit: no such path: %s" % p, file=sys.stderr)
+            return 2
+    res = run_check(a.paths)
+    floor = SEV_ORDER[a.min_severity]
+    shown = [f for f in res["findings"] if SEV_ORDER[f["severity"]] >= floor]
+    if a.format == "json":
+        print(json.dumps({"findings": shown, "skipped": res["skipped"], "files": res["files"],
+                          "declared": res["declared"]}, indent=2))
+    elif a.format == "sarif":
+        print(json.dumps(to_sarif(shown), indent=2))
+    else:
+        for f in shown:
+            print("%s:%d:%d: %s %s [%s]" % (f["path"], f["line"], f["col"], f["rule"], f["message"], f["severity"]))
+        for s in res["skipped"]:
+            print("%s: skipped (%s)" % (s["path"], s["error"]), file=sys.stderr)
+        print("\n%d finding(s) in %d file(s) scanned." % (len(shown), res["files"]))
+        if not a.quiet:
+            print(footer())
+    if a.fail_on == "never":
+        return 0
+    bad = [f for f in res["findings"] if SEV_ORDER[f["severity"]] >= SEV_ORDER[a.fail_on]]
+    return 1 if bad else 0
+
+
+def cmd_fix(a):
+    for p in a.paths:
+        if not os.path.exists(p):
+            print("httpx2-audit: no such path: %s" % p, file=sys.stderr)
+            return 2
+    rep = run_fix(a.paths, write=a.write, dual=a.dual)
+    if rep["diff"]:
+        print(rep["diff"], end="")
+    for u in rep["unfixable"]:
+        print("manual: %s:%d: %s" % (u["path"], u["line"], u["reason"]), file=sys.stderr)
+    verb = "rewrote" if a.write else "would rewrite (use --write)"
+    print("%s %d file(s)." % (verb, len(rep["files"])))
+    if a.dual:
+        print("dual mode: imports prefer httpx2 and fall back to httpx; dependencies unchanged.")
+    elif rep["files"]:
+        print("note: httpx2 needs Python 3.10+. Then run `httpx2-audit check` for what imports cannot fix "
+              "(except clauses, mocks, TLS).")
+    return 0
+
+
+def cmd_env(a):
+    rep = run_env(a.probe)
+    if a.format == "json":
+        print(json.dumps(rep, indent=2))
+    else:
+        print("installed:")
+        for n, v in rep["installed"].items():
+            print("  %-18s %s" % (n, v))
+        print("depend on httpx:  %s" % (", ".join(rep["httpx_dependents"]) or "-"))
+        print("depend on httpx2: %s" % (", ".join(rep["httpx2_dependents"]) or "-"))
+        for h, r in rep["tls"].items():
+            print("tls %s: %s" % (h, ", ".join("%s=%s" % kv for kv in r.items())))
+        for w in rep["warnings"]:
+            print("WARNING: " + w)
+        print(footer())
+    return 1 if rep["warnings"] else 0
+
+
+def build_parser():
+    p = argparse.ArgumentParser(prog="httpx2-audit", description=__doc__)
+    p.add_argument("--version", action="version", version="httpx2-audit " + __version__)
+    sub = p.add_subparsers(dest="cmd", required=True)
+    c = sub.add_parser("check", help="scan Python files for httpx -> httpx2 problems")
+    c.add_argument("paths", nargs="*", default=["."])
+    c.add_argument("--format", choices=["text", "json", "sarif"], default="text")
+    c.add_argument("--min-severity", choices=list(SEV_ORDER), default="info")
+    c.add_argument("--fail-on", choices=["info", "warning", "error", "never"], default="warning")
+    c.add_argument("-q", "--quiet", action="store_true", help="omit the footer")
+    c.set_defaults(func=cmd_check)
+    f = sub.add_parser("fix", help="rewrite imports and dependencies (dry run unless --write)")
+    f.add_argument("paths", nargs="*", default=["."])
+    f.add_argument("--write", action="store_true")
+    f.add_argument("--dual", action="store_true", help="try httpx2, fall back to httpx (for libraries)")
+    f.set_defaults(func=cmd_fix)
+    e = sub.add_parser("env", help="report installed httpx/httpx2 stack and optionally probe TLS")
+    e.add_argument("--probe", action="append", default=[], metavar="HOST[:PORT]")
+    e.add_argument("--format", choices=["text", "json"], default="text")
+    e.set_defaults(func=cmd_env)
+    return p
+
+
+def main(argv=None):
+    a = build_parser().parse_args(argv)
+    if a.cmd in ("check", "fix") and not a.paths:
+        a.paths = ["."]
+    return a.func(a)
+
+
+if __name__ == "__main__":
+    sys.exit(main())