tagpoint 0.1.0__py3-none-any.whl

tagpoint/__init__.py

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

tagpoint/__main__.py

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

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/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.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,10 @@
+tagpoint/__init__.py,sha256=YbfTUvCFBDCwxYIIsEe1tNigQUaTyqNmvYpPr4OGEd0,116
+tagpoint/__main__.py,sha256=MHKZ_ae3fSLGTLUUMOx15fWdeOnJSHhq-zslRP5F5Lc,79
+tagpoint/checker.py,sha256=q3auiXS5kxNh955xoGi3CVOXg6eaxteNBeXdoaT_L1w,8547
+tagpoint/cli.py,sha256=bfPuUP6Q8nSlgAzOxW5g8b6KfbsdBV8ZlkC7wg93ifw,1596
+tagpoint-0.1.0.dist-info/licenses/LICENSE,sha256=OYhQDg7nxWoFtnF6J8NkFUA8NMw5TKv9a1WTXHY-fu4,1063
+tagpoint-0.1.0.dist-info/METADATA,sha256=U6XeDIAQuCo7UfyR5aSDjFLj4ZvXOFO0zNBpt6MU70c,3126
+tagpoint-0.1.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+tagpoint-0.1.0.dist-info/entry_points.txt,sha256=mS2lD2VWfursgDpObq_lfEcm2zyIA1coj-9pvUQUGZA,47
+tagpoint-0.1.0.dist-info/top_level.txt,sha256=Jfx1jtggOTB7aJXBuN-RkmXTfjOST9dJ1666SxNeDwM,9
+tagpoint-0.1.0.dist-info/RECORD,,

tagpoint-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
+

tagpoint-0.1.0.dist-info/entry_points.txt

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

tagpoint-0.1.0.dist-info/licenses/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.dist-info/top_level.txt

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