tagpoint 0.1.0__tar.gz

tagpoint-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 hao li
+
+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.

tagpoint-0.1.0/PKG-INFO

@@ -0,0 +1,88 @@
+Metadata-Version: 2.4
+Name: tagpoint
+Version: 0.1.0
+Summary: Verify a PyPI release actually matches its GitHub tag — name AND content
+Author-email: hao li <haoli5933@gmail.com>
+License: MIT
+Project-URL: Homepage, https://github.com/hahahahahahahahah6/tagpoint
+Project-URL: Repository, https://github.com/hahahahahahahahah6/tagpoint
+Keywords: pypi,github,supply-chain,release,tag,integrity
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Build Tools
+Classifier: Topic :: Security
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# tagpoint
+
+Verify that a PyPI release **actually matches** its GitHub tag — the name *and* the content.
+
+```bash
+pip install tagpoint
+tagpoint check requests --repo psf/requests
+```
+
+Output:
+
+```
+tagpoint report: requests==2.32.3  repo=psf/requests
+tag: v2.32.3   commit: abc123def456
+
+[PASS] tag-exists: tag v2.32.3 -> abc123def456
+[PASS] sdist-version: PKG-INFO version 2.32.3 matches PyPI
+[PASS] file-list: 128 files match the tag tree
+[PASS] tag-before-build: tag commit 2024-05-29T... <= upload 2024-05-29T...
+
+verdict: CONSISTENT
+```
+
+Exit code `0` = consistent, `1` = inconsistent, `2` = check error (network, missing data).
+
+## Install
+
+```bash
+pip install tagpoint
+```
+
+tagpoint is stdlib-only — no third-party dependencies.
+
+## Usage
+
+```
+tagpoint check <pypi-package> --repo owner/name [--shallow] [--token TOKEN]
+```
+
+- `tagpoint check flask --repo pallets/flask` — full check (default)
+- `--shallow` — only verify the tag exists and the sdist version matches
+- `--token` — GitHub token (or `GITHUB_TOKEN` env var) to raise API rate limits
+
+Four checks run by default:
+
+1. **tag-exists** — a tag named `v{version}` or `{version}` exists and resolves (annotated tags are peeled to the commit).
+2. **sdist-version** — the sdist's `PKG-INFO` version equals the PyPI version.
+3. **file-list** — the sdist file list matches the tag's git tree (catches files added/removed after the build).
+4. **tag-before-build** — the tag commit date is not newer than the release upload time (a tag moved *after* the build is drift).
+
+## Differentiation
+
+There are tools that check whether a release tag **exists** (e.g. my
+[tagtruth](https://github.com/hahahahahahahahah6/tagtruth) project checks tag
+presence as part of release hygiene). tagpoint goes one step further: it checks
+whether the tag **points at the code the release was actually built from**.
+
+The failure mode it catches is real: a tag named `v1.2.3` exists, CI is green,
+everything looks fine — but the tag was force-moved after the sdist was built,
+or the release was cut from a dirty working tree. The name matches; the
+content doesn't. tagpoint compares the sdist contents against the tag's git
+tree and flags the drift. Think of it as a "name matches reality" check for
+your supply chain.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

tagpoint-0.1.0/README.md

@@ -0,0 +1,67 @@
+# tagpoint
+
+Verify that a PyPI release **actually matches** its GitHub tag — the name *and* the content.
+
+```bash
+pip install tagpoint
+tagpoint check requests --repo psf/requests
+```
+
+Output:
+
+```
+tagpoint report: requests==2.32.3  repo=psf/requests
+tag: v2.32.3   commit: abc123def456
+
+[PASS] tag-exists: tag v2.32.3 -> abc123def456
+[PASS] sdist-version: PKG-INFO version 2.32.3 matches PyPI
+[PASS] file-list: 128 files match the tag tree
+[PASS] tag-before-build: tag commit 2024-05-29T... <= upload 2024-05-29T...
+
+verdict: CONSISTENT
+```
+
+Exit code `0` = consistent, `1` = inconsistent, `2` = check error (network, missing data).
+
+## Install
+
+```bash
+pip install tagpoint
+```
+
+tagpoint is stdlib-only — no third-party dependencies.
+
+## Usage
+
+```
+tagpoint check <pypi-package> --repo owner/name [--shallow] [--token TOKEN]
+```
+
+- `tagpoint check flask --repo pallets/flask` — full check (default)
+- `--shallow` — only verify the tag exists and the sdist version matches
+- `--token` — GitHub token (or `GITHUB_TOKEN` env var) to raise API rate limits
+
+Four checks run by default:
+
+1. **tag-exists** — a tag named `v{version}` or `{version}` exists and resolves (annotated tags are peeled to the commit).
+2. **sdist-version** — the sdist's `PKG-INFO` version equals the PyPI version.
+3. **file-list** — the sdist file list matches the tag's git tree (catches files added/removed after the build).
+4. **tag-before-build** — the tag commit date is not newer than the release upload time (a tag moved *after* the build is drift).
+
+## Differentiation
+
+There are tools that check whether a release tag **exists** (e.g. my
+[tagtruth](https://github.com/hahahahahahahahah6/tagtruth) project checks tag
+presence as part of release hygiene). tagpoint goes one step further: it checks
+whether the tag **points at the code the release was actually built from**.
+
+The failure mode it catches is real: a tag named `v1.2.3` exists, CI is green,
+everything looks fine — but the tag was force-moved after the sdist was built,
+or the release was cut from a dirty working tree. The name matches; the
+content doesn't. tagpoint compares the sdist contents against the tag's git
+tree and flags the drift. Think of it as a "name matches reality" check for
+your supply chain.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

tagpoint-0.1.0/pyproject.toml

@@ -0,0 +1,32 @@
+[build-system]
+requires = ["setuptools>=61"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "tagpoint"
+version = "0.1.0"
+description = "Verify a PyPI release actually matches its GitHub tag — name AND content"
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.9"
+authors = [{ name = "hao li", email = "haoli5933@gmail.com" }]
+keywords = ["pypi", "github", "supply-chain", "release", "tag", "integrity"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Topic :: Software Development :: Build Tools",
+    "Topic :: Security",
+]
+
+[project.scripts]
+tagpoint = "tagpoint.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/hahahahahahahahah6/tagpoint"
+Repository = "https://github.com/hahahahahahahahah6/tagpoint"
+
+[tool.setuptools.packages.find]
+where = ["src"]

tagpoint-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

tagpoint-0.1.0/src/tagpoint/__init__.py

@@ -0,0 +1,4 @@
+"""tagpoint: verify that a PyPI release matches its GitHub tag."""
+
+__version__ = "0.1.0"
+__all__ = ["__version__"]

tagpoint-0.1.0/src/tagpoint/__main__.py

@@ -0,0 +1,4 @@
+from .cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

tagpoint-0.1.0/src/tagpoint/checker.py

@@ -0,0 +1,221 @@
+"""Core consistency checks between a PyPI release and its GitHub tag.
+
+tagpoint answers one question: does the tag named after the PyPI version
+actually point at the code the release was built from?  It fetches the PyPI
+metadata, resolves the matching GitHub tag, downloads the sdist, and compares
+what can be compared without a full git checkout:
+
+1. the tag exists (v{version} or {version})
+2. the sdist PKG-INFO version matches the PyPI version
+3. (deep) the sdist file list matches the tag's git tree file list,
+   flagging files the tag gained/lost after the release was built
+4. (deep) the tag commit date is not newer than the release upload time
+   (a tag moved *after* the build is suspicious drift)
+"""
+
+from __future__ import annotations
+
+import hashlib
+import io
+import json
+import tarfile
+import urllib.error
+import urllib.request
+import zipfile
+from dataclasses import dataclass, field
+
+PYPI_JSON_URL = "https://pypi.org/pypi/{name}/json"
+GITHUB_API = "https://api.github.com"
+
+_USER_AGENT = "tagpoint/0.1.0 (+https://github.com/hahahahahahahahah6/tagpoint)"
+
+
+class CheckError(Exception):
+    """Raised when a check cannot be completed (network, missing data, ...)."""
+
+
+@dataclass
+class Finding:
+    ok: bool
+    name: str
+    detail: str
+
+
+@dataclass
+class Report:
+    package: str
+    version: str
+    repo: str
+    tag: str | None
+    commit: str | None
+    findings: list[Finding] = field(default_factory=list)
+
+    @property
+    def consistent(self) -> bool:
+        return bool(self.findings) and all(f.ok for f in self.findings)
+
+    def render(self) -> str:
+        lines = [
+            f"tagpoint report: {self.package}=={self.version}  repo={self.repo}",
+            f"tag: {self.tag or '(none)'}   commit: {(self.commit or '(none)')[:12]}",
+            "",
+        ]
+        for f in self.findings:
+            mark = "PASS" if f.ok else "FAIL"
+            lines.append(f"[{mark}] {f.name}: {f.detail}")
+        lines.append("")
+        verdict = "CONSISTENT" if self.consistent else "INCONSISTENT"
+        lines.append(f"verdict: {verdict}")
+        return "\n".join(lines)
+
+
+def _fetch_json(url: str, token: str | None = None) -> dict:
+    req = urllib.request.Request(url, headers={"User-Agent": _USER_AGENT})
+    if token:
+        req.add_header("Authorization", f"Bearer {token}")
+    try:
+        with urllib.request.urlopen(req, timeout=30) as resp:
+            return json.loads(resp.read().decode("utf-8"))
+    except urllib.error.HTTPError as e:
+        raise CheckError(f"HTTP {e.code} fetching {url}") from e
+    except urllib.error.URLError as e:
+        raise CheckError(f"network error fetching {url}: {e.reason}") from e
+
+
+def _fetch_bytes(url: str) -> bytes:
+    req = urllib.request.Request(url, headers={"User-Agent": _USER_AGENT})
+    try:
+        with urllib.request.urlopen(req, timeout=60) as resp:
+            return resp.read()
+    except urllib.error.HTTPError as e:
+        raise CheckError(f"HTTP {e.code} downloading {url}") from e
+    except urllib.error.URLError as e:
+        raise CheckError(f"network error downloading {url}: {e.reason}") from e
+
+
+def _sdist_files(blob: bytes, filename: str) -> tuple[str, list[str]]:
+    """Return (PKG-INFO version, sorted file list) from an sdist blob."""
+    version = ""
+    names: list[str] = []
+    if filename.endswith(".zip"):
+        with zipfile.ZipFile(io.BytesIO(blob)) as zf:
+            for info in zf.infolist():
+                names.append(info.filename)
+                if info.filename.endswith("PKG-INFO"):
+                    version = _pkg_info_version(zf.read(info.filename).decode("utf-8", "replace"))
+    else:  # .tar.gz
+        with tarfile.open(fileobj=io.BytesIO(blob), mode="r:gz") as tf:
+            for member in tf.getmembers():
+                names.append(member.name)
+                if member.name.endswith("PKG-INFO") and member.isfile():
+                    f = tf.extractfile(member)
+                    if f:
+                        version = _pkg_info_version(f.read().decode("utf-8", "replace"))
+    return version, sorted(names)
+
+
+def _pkg_info_version(text: str) -> str:
+    for line in text.splitlines():
+        if line.lower().startswith("version:"):
+            return line.split(":", 1)[1].strip()
+    return ""
+
+
+def _sha256_file(path: str) -> str:
+    h = hashlib.sha256()
+    with open(path, "rb") as f:
+        for chunk in iter(lambda: f.read(65536), b""):
+            h.update(chunk)
+    return h.hexdigest()
+
+
+def _strip_top_dir(names: list[str]) -> set[str]:
+    """Drop the sdist's single top-level directory so paths compare to a git tree."""
+    out = set()
+    for n in names:
+        parts = n.strip("/").split("/")
+        if len(parts) > 1:
+            out.add("/".join(parts[1:]))
+    return out
+
+
+def check(package: str, repo: str, *, deep: bool = True, token: str | None = None) -> Report:
+    """Run the full consistency check and return a Report."""
+    meta = _fetch_json(PYPI_JSON_URL.format(name=package), token)
+    version = meta["info"]["version"]
+    report = Report(package=package, version=version, repo=repo, tag=None, commit=None)
+
+    # 1. resolve the tag
+    tag_name = None
+    commit = None
+    for candidate in (f"v{version}", version):
+        try:
+            ref = _fetch_json(f"{GITHUB_API}/repos/{repo}/git/refs/tags/{candidate}", token)
+        except CheckError:
+            continue
+        tag_name = candidate
+        obj = ref["object"]
+        if obj["type"] == "tag":  # annotated tag -> peel to commit
+            peeled = _fetch_json(obj["url"], token)
+            commit = peeled["object"]["sha"]
+        else:
+            commit = obj["sha"]
+        break
+    report.tag, report.commit = tag_name, commit
+    if tag_name is None:
+        report.findings.append(Finding(False, "tag-exists",
+                                       f"no tag v{version} or {version} on {repo}"))
+        return report
+    report.findings.append(Finding(True, "tag-exists",
+                                   f"tag {tag_name} -> {commit[:12]}"))
+
+    # 2. sdist sanity: PKG-INFO version must match PyPI version
+    files = meta["releases"].get(version, [])
+    sdists = [f for f in files if f["packagetype"] == "sdist"]
+    if not sdists:
+        report.findings.append(Finding(False, "sdist-present",
+                                       "no sdist file in this release"))
+        return report
+    sdist = sdists[0]
+    blob = _fetch_bytes(sdist["url"])
+    pkg_version, sdist_names = _sdist_files(blob, sdist["filename"])
+    if pkg_version == version:
+        report.findings.append(Finding(True, "sdist-version",
+                                       f"PKG-INFO version {pkg_version} matches PyPI"))
+    else:
+        report.findings.append(Finding(False, "sdist-version",
+                                       f"PKG-INFO says {pkg_version!r}, PyPI says {version!r}"))
+
+    if not deep:
+        return report
+
+    # 3. file-list comparison: sdist contents vs tag tree
+    tree = _fetch_json(f"{GITHUB_API}/repos/{repo}/git/trees/{commit}?recursive=1", token)
+    tag_paths = {t["path"] for t in tree.get("tree", []) if t["type"] == "blob"}
+    # PKG-INFO is generated at build time; it never lives in the git tree.
+    sdist_paths = _strip_top_dir(sdist_names) - {"PKG-INFO"}
+    only_tag = sorted(tag_paths - sdist_paths)
+    only_sdist = sorted(sdist_paths - tag_paths)
+    if not only_tag and not only_sdist:
+        report.findings.append(Finding(True, "file-list",
+                                       f"{len(tag_paths)} files match the tag tree"))
+    else:
+        detail = []
+        if only_tag:
+            detail.append(f"{len(only_tag)} only in tag (e.g. {', '.join(only_tag[:3])})")
+        if only_sdist:
+            detail.append(f"{len(only_sdist)} only in sdist (e.g. {', '.join(only_sdist[:3])})")
+        report.findings.append(Finding(False, "file-list", "; ".join(detail)))
+
+    # 4. tag commit must not be newer than the release upload
+    commit_meta = _fetch_json(f"{GITHUB_API}/repos/{repo}/commits/{commit}", token)
+    commit_date = commit_meta["commit"]["committer"]["date"]
+    upload_time = sdist["upload_time_iso_8601"]
+    if commit_date <= upload_time:
+        report.findings.append(Finding(True, "tag-before-build",
+                                       f"tag commit {commit_date} <= upload {upload_time}"))
+    else:
+        report.findings.append(Finding(False, "tag-before-build",
+                                       f"tag commit {commit_date} is NEWER than upload {upload_time} — tag drifted"))
+
+    return report

tagpoint-0.1.0/src/tagpoint/cli.py

@@ -0,0 +1,45 @@
+"""Command-line interface for tagpoint."""
+
+from __future__ import annotations
+
+import argparse
+import os
+import sys
+
+from . import __version__
+from .checker import CheckError, check
+
+
+def build_parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(
+        prog="tagpoint",
+        description="Verify a PyPI release matches its GitHub tag (name AND content).",
+    )
+    p.add_argument("--version", action="version", version=f"%(prog)s {__version__}")
+    sub = p.add_subparsers(dest="command", required=True)
+
+    c = sub.add_parser("check", help="check one package release against its repo tag")
+    c.add_argument("package", help="PyPI package name, e.g. requests")
+    c.add_argument("--repo", required=True, help="GitHub repo as owner/name, e.g. psf/requests")
+    c.add_argument("--shallow", action="store_true",
+                   help="skip file-list and tag-date checks (tag existence + sdist version only)")
+    c.add_argument("--token", default=os.environ.get("GITHUB_TOKEN"),
+                   help="GitHub token (or set GITHUB_TOKEN) to raise API rate limits")
+    return p
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = build_parser().parse_args(argv)
+    if args.command == "check":
+        try:
+            report = check(args.package, args.repo, deep=not args.shallow, token=args.token)
+        except CheckError as e:
+            print(f"tagpoint: error: {e}", file=sys.stderr)
+            return 2
+        print(report.render())
+        return 0 if report.consistent else 1
+    return 2
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

tagpoint-0.1.0/src/tagpoint.egg-info/PKG-INFO

@@ -0,0 +1,88 @@
+Metadata-Version: 2.4
+Name: tagpoint
+Version: 0.1.0
+Summary: Verify a PyPI release actually matches its GitHub tag — name AND content
+Author-email: hao li <haoli5933@gmail.com>
+License: MIT
+Project-URL: Homepage, https://github.com/hahahahahahahahah6/tagpoint
+Project-URL: Repository, https://github.com/hahahahahahahahah6/tagpoint
+Keywords: pypi,github,supply-chain,release,tag,integrity
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Build Tools
+Classifier: Topic :: Security
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# tagpoint
+
+Verify that a PyPI release **actually matches** its GitHub tag — the name *and* the content.
+
+```bash
+pip install tagpoint
+tagpoint check requests --repo psf/requests
+```
+
+Output:
+
+```
+tagpoint report: requests==2.32.3  repo=psf/requests
+tag: v2.32.3   commit: abc123def456
+
+[PASS] tag-exists: tag v2.32.3 -> abc123def456
+[PASS] sdist-version: PKG-INFO version 2.32.3 matches PyPI
+[PASS] file-list: 128 files match the tag tree
+[PASS] tag-before-build: tag commit 2024-05-29T... <= upload 2024-05-29T...
+
+verdict: CONSISTENT
+```
+
+Exit code `0` = consistent, `1` = inconsistent, `2` = check error (network, missing data).
+
+## Install
+
+```bash
+pip install tagpoint
+```
+
+tagpoint is stdlib-only — no third-party dependencies.
+
+## Usage
+
+```
+tagpoint check <pypi-package> --repo owner/name [--shallow] [--token TOKEN]
+```
+
+- `tagpoint check flask --repo pallets/flask` — full check (default)
+- `--shallow` — only verify the tag exists and the sdist version matches
+- `--token` — GitHub token (or `GITHUB_TOKEN` env var) to raise API rate limits
+
+Four checks run by default:
+
+1. **tag-exists** — a tag named `v{version}` or `{version}` exists and resolves (annotated tags are peeled to the commit).
+2. **sdist-version** — the sdist's `PKG-INFO` version equals the PyPI version.
+3. **file-list** — the sdist file list matches the tag's git tree (catches files added/removed after the build).
+4. **tag-before-build** — the tag commit date is not newer than the release upload time (a tag moved *after* the build is drift).
+
+## Differentiation
+
+There are tools that check whether a release tag **exists** (e.g. my
+[tagtruth](https://github.com/hahahahahahahahah6/tagtruth) project checks tag
+presence as part of release hygiene). tagpoint goes one step further: it checks
+whether the tag **points at the code the release was actually built from**.
+
+The failure mode it catches is real: a tag named `v1.2.3` exists, CI is green,
+everything looks fine — but the tag was force-moved after the sdist was built,
+or the release was cut from a dirty working tree. The name matches; the
+content doesn't. tagpoint compares the sdist contents against the tag's git
+tree and flags the drift. Think of it as a "name matches reality" check for
+your supply chain.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

tagpoint-0.1.0/src/tagpoint.egg-info/SOURCES.txt

@@ -0,0 +1,13 @@
+LICENSE
+README.md
+pyproject.toml
+src/tagpoint/__init__.py
+src/tagpoint/__main__.py
+src/tagpoint/checker.py
+src/tagpoint/cli.py
+src/tagpoint.egg-info/PKG-INFO
+src/tagpoint.egg-info/SOURCES.txt
+src/tagpoint.egg-info/dependency_links.txt
+src/tagpoint.egg-info/entry_points.txt
+src/tagpoint.egg-info/top_level.txt
+tests/test_checker.py

tagpoint-0.1.0/src/tagpoint.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

tagpoint-0.1.0/src/tagpoint.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+tagpoint = tagpoint.cli:main

tagpoint-0.1.0/src/tagpoint.egg-info/top_level.txt

@@ -0,0 +1 @@
+tagpoint

tagpoint-0.1.0/tests/test_checker.py

@@ -0,0 +1,192 @@
+"""Smoke tests for tagpoint. All network access is mocked — no real HTTP."""
+
+from __future__ import annotations
+
+import io
+import json
+import tarfile
+import urllib.error
+
+import pytest
+
+from tagpoint import checker
+from tagpoint.checker import CheckError, check
+
+PKG = "fakepkg"
+REPO = "owner/fakepkg"
+VERSION = "1.2.3"
+
+
+def make_sdist(version: str, files: tuple[str, ...] = ("fakepkg/__init__.py",)) -> bytes:
+    buf = io.BytesIO()
+    top = f"fakepkg-{version}"
+    with tarfile.open(fileobj=buf, mode="w:gz") as tf:
+        pkg_info = f"Metadata-Version: 2.1\nName: fakepkg\nVersion: {version}\n".encode()
+        for name in (f"{top}/PKG-INFO",) + tuple(f"{top}/{f}" for f in files):
+            data = pkg_info if name.endswith("PKG-INFO") else b"x = 1\n"
+            ti = tarfile.TarInfo(name=name)
+            ti.size = len(data)
+            tf.addfile(ti, io.BytesIO(data))
+    return buf.getvalue()
+
+
+def pypi_meta(version=VERSION, with_sdist=True):
+    files = []
+    if with_sdist:
+        files.append({
+            "packagetype": "sdist",
+            "filename": f"fakepkg-{version}.tar.gz",
+            "url": f"https://files.pythonhosted.org/fakepkg-{version}.tar.gz",
+            "upload_time_iso_8601": "2026-10-01T12:00:00Z",
+        })
+    return {"info": {"version": version}, "releases": {version: files}}
+
+
+class FakeResp:
+    def __init__(self, payload: bytes):
+        self._payload = payload
+
+    def read(self):
+        return self._payload
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, *a):
+        return False
+
+
+class Router:
+    """Maps URL substrings to payloads for urlopen."""
+
+    def __init__(self):
+        self.routes: list[tuple[str, bytes]] = []
+
+    def add(self, needle: str, payload):
+        if isinstance(payload, (dict, list)):
+            payload = json.dumps(payload).encode()
+        self.routes.append((needle, payload))
+
+    def __call__(self, req, timeout=None):
+        url = req.full_url if hasattr(req, "full_url") else req
+        for needle, payload in self.routes:
+            if needle in url:
+                return FakeResp(payload)
+        raise urllib.error.HTTPError(url, 404, "not found", {}, None)
+
+
+@pytest.fixture
+def net(monkeypatch):
+    router = Router()
+    monkeypatch.setattr(checker.urllib.request, "urlopen", router)
+    return router
+
+
+def wire_happy(router: Router, version=VERSION, tag_commit_date="2026-09-30T12:00:00Z",
+               tree_files=("fakepkg/__init__.py",), sdist_files=("fakepkg/__init__.py",),
+               sdist_version=None):
+    sdist_version = sdist_version or version
+    router.add("pypi.org", pypi_meta(version))
+    router.add("git/refs/tags/v", {"object": {"type": "commit",
+                                              "sha": "abc123" + "0" * 34,
+                                              "url": "x"}})
+    router.add("git/trees", {"tree": [{"path": p, "type": "blob"} for p in tree_files]})
+    router.add("repos/owner/fakepkg/commits",
+               {"commit": {"committer": {"date": tag_commit_date}}})
+    router.add("files.pythonhosted.org", make_sdist(sdist_version, sdist_files))
+
+
+def test_happy_path_consistent(net):
+    wire_happy(net)
+    r = check(PKG, REPO)
+    assert r.consistent
+    assert r.version == VERSION
+    assert r.tag == f"v{VERSION}"
+    assert len(r.findings) == 4
+    out = r.render()
+    assert "CONSISTENT" in out
+    assert "[PASS]" in out and "[FAIL]" not in out
+
+
+def test_missing_tag_is_inconsistent(net):
+    net.add("pypi.org", pypi_meta())
+    # no tag routes -> 404 on both v{version} and {version}
+    r = check(PKG, REPO)
+    assert not r.consistent
+    assert r.tag is None
+    assert "INCONSISTENT" in r.render()
+
+
+def test_sdist_version_mismatch(net):
+    wire_happy(net, sdist_version="9.9.9")
+    r = check(PKG, REPO)
+    assert not r.consistent
+    assert any(f.name == "sdist-version" and not f.ok for f in r.findings)
+
+
+def test_no_sdist_in_release(net):
+    net.add("pypi.org", pypi_meta(with_sdist=False))
+    net.add("git/refs/tags/v", {"object": {"type": "commit", "sha": "a" * 40, "url": "x"}})
+    r = check(PKG, REPO)
+    assert not r.consistent
+    assert any(f.name == "sdist-present" and not f.ok for f in r.findings)
+
+
+def test_file_list_drift_detected(net):
+    # tag gained a file after the release was built
+    wire_happy(net, tree_files=("fakepkg/__init__.py", "fakepkg/backdoor.py"))
+    r = check(PKG, REPO)
+    assert not r.consistent
+    bad = [f for f in r.findings if f.name == "file-list"]
+    assert bad and not bad[0].ok
+    assert "backdoor.py" in bad[0].detail
+
+
+def test_tag_newer_than_upload_detected(net):
+    wire_happy(net, tag_commit_date="2026-10-05T12:00:00Z")  # after upload 10-01
+    r = check(PKG, REPO)
+    assert not r.consistent
+    bad = [f for f in r.findings if f.name == "tag-before-build"]
+    assert bad and not bad[0].ok
+
+
+def test_annotated_tag_is_peeled(net):
+    net.add("pypi.org", pypi_meta())
+    net.add("git/refs/tags/v",
+            {"object": {"type": "tag", "sha": "t" * 40, "url": "https://api.github.com/peeled"}})
+    net.add("peeled", {"object": {"type": "commit", "sha": "c" * 40}})
+    net.add("git/trees", {"tree": [{"path": "fakepkg/__init__.py", "type": "blob"}]})
+    net.add("repos/owner/fakepkg/commits",
+            {"commit": {"committer": {"date": "2026-09-30T12:00:00Z"}}})
+    net.add("files.pythonhosted.org", make_sdist(VERSION))
+    r = check(PKG, REPO)
+    assert r.consistent
+    assert r.commit == "c" * 40
+
+
+def test_pypi_404_raises_check_error(net):
+    # Router raises HTTPError 404 -> CheckError
+    with pytest.raises(CheckError):
+        check("no-such-pkg", REPO)
+
+
+def test_shallow_skips_deep_checks(net):
+    wire_happy(net)
+    r = check(PKG, REPO, deep=False)
+    assert r.consistent
+    assert [f.name for f in r.findings] == ["tag-exists", "sdist-version"]
+
+
+def test_cli_exit_codes(net, capsys, monkeypatch):
+    from tagpoint import cli
+    wire_happy(net)
+    monkeypatch.setattr(checker.urllib.request, "urlopen", net)
+    assert cli.main(["check", PKG, "--repo", REPO]) == 0
+    out, _ = capsys.readouterr()
+    assert "CONSISTENT" in out
+
+    # drift case -> exit 1
+    net2 = Router()
+    wire_happy(net2, tree_files=("fakepkg/__init__.py", "fakepkg/evil.py"))
+    monkeypatch.setattr(checker.urllib.request, "urlopen", net2)
+    assert cli.main(["check", PKG, "--repo", REPO]) == 1