wheeltruth 0.1.0__py3-none-any.whl

wheeltruth/__init__.py

@@ -0,0 +1,3 @@
+"""wheeltruth: check that your built wheel/sdist contains what it should."""
+
+__version__ = "0.1.0"

wheeltruth/check.py

@@ -0,0 +1,774 @@
+"""Core checks for wheeltruth: does the built artifact contain what it should?"""
+
+from __future__ import annotations
+
+import base64
+import csv
+import hashlib
+import io
+import os
+import re
+import subprocess
+import sys
+import tarfile
+import tempfile
+import zipfile
+
+SEVERITIES = ("info", "warning", "error")
+
+# Top-level sdist dirs that are never shipped inside a wheel.
+_NON_PACKAGE_TOPS = {
+    "tests", "test", "docs", "doc", "examples", "example",
+    ".github", ".git", "tools", "scripts",
+}
+
+
+class Finding:
+    def __init__(self, severity, code, message, artifact="", detail=""):
+        assert severity in SEVERITIES
+        self.severity = severity
+        self.code = code
+        self.message = message
+        self.artifact = artifact
+        self.detail = detail
+
+    def __repr__(self):  # pragma: no cover - debugging helper
+        return f"Finding({self.severity!r}, {self.code!r}, {self.message!r})"
+
+
+class ArtifactReport:
+    def __init__(self, path, kind):
+        self.path = path
+        self.kind = kind  # "wheel" | "sdist"
+        self.findings = []
+
+    def add(self, severity, code, message, detail=""):
+        self.findings.append(
+            Finding(severity, code, message, artifact=self.path, detail=detail)
+        )
+
+    @property
+    def has_issues(self):
+        return any(f.severity in ("warning", "error") for f in self.findings)
+
+    @property
+    def errors(self):
+        return [f for f in self.findings if f.severity == "error"]
+
+
+def _is_dist_info(path):
+    return bool(re.match(r"[^/]+\.dist-info/", path))
+
+
+def _is_signature_record(path):
+    return bool(re.match(r"[^/]+\.dist-info/RECORD(\.jws|\.p7s)?$", path))
+
+
+def parse_wheel_filename(filename):
+    """Return (name, version) from a wheel filename, or (None, None)."""
+    base = os.path.basename(filename)
+    if not base.endswith(".whl"):
+        return None, None
+    parts = base[:-4].split("-")
+    if len(parts) < 5:
+        return None, None
+    rest = parts[:-3]  # name, version, [build]
+    if len(rest) == 3:
+        name, version = rest[0], rest[1]
+    elif len(rest) == 2:
+        name, version = rest
+    else:
+        return None, None
+    return name, version
+
+
+def parse_sdist_filename(filename):
+    base = os.path.basename(filename)
+    for suffix in (".tar.gz", ".tgz", ".zip"):
+        if base.endswith(suffix):
+            stem = base[: -len(suffix)]
+            if "-" in stem:
+                name, version = stem.rsplit("-", 1)
+                return name, version
+    return None, None
+
+
+def _norm_name(name):
+    return re.sub(r"[-_.]+", "-", name or "").lower()
+
+
+def parse_rfc822_headers(text):
+    """Minimal RFC822 header parser -> {key: [values]}. Stops at first blank line."""
+    headers = {}
+    key = None
+    for line in text.splitlines():
+        if not line.strip():
+            break
+        if line[0] in " \t" and key:
+            headers[key][-1] += "\n" + line.strip()
+        elif ":" in line:
+            k, v = line.split(":", 1)
+            key = k.strip()
+            headers.setdefault(key, []).append(v.strip())
+        else:
+            key = None
+    return headers
+
+
+def parse_entry_points(text):
+    """Parse entry_points.txt -> {group: [(name, value), ...]}."""
+    groups = {}
+    current = None
+    for raw in text.splitlines():
+        line = raw.strip()
+        if not line or line.startswith(("#", ";")):
+            continue
+        if line.startswith("[") and line.endswith("]"):
+            current = line[1:-1].strip()
+            groups.setdefault(current, [])
+        elif current is not None and "=" in line:
+            name, value = line.split("=", 1)
+            groups[current].append((name.strip(), value.strip()))
+    return groups
+
+
+class WheelData:
+    def __init__(self, path):
+        self.path = path
+        self.files = []
+        self.record = {}  # path -> (hash, size)
+        self.metadata = {}
+        self.entry_points = {}
+        self.dist_info = ""
+        self.filename_name, self.filename_version = parse_wheel_filename(path)
+
+
+def read_wheel(path):
+    wheel = WheelData(path)
+    with zipfile.ZipFile(path) as zf:
+        wheel.files = [n for n in zf.namelist() if not n.endswith("/")]
+        dist_infos = {n.split("/")[0] for n in wheel.files if _is_dist_info(n)}
+        wheel.dist_info = sorted(dist_infos)[0] if dist_infos else ""
+        for name in wheel.files:
+            if name == f"{wheel.dist_info}/METADATA" and wheel.dist_info:
+                wheel.metadata = parse_rfc822_headers(
+                    zf.read(name).decode("utf-8", "replace")
+                )
+            elif name == f"{wheel.dist_info}/entry_points.txt" and wheel.dist_info:
+                wheel.entry_points = parse_entry_points(
+                    zf.read(name).decode("utf-8", "replace")
+                )
+            elif name.endswith(".dist-info/RECORD") and "/RECORD" in name:
+                text = zf.read(name).decode("utf-8", "replace")
+                for row in csv.reader(io.StringIO(text)):
+                    if len(row) >= 1 and row[0]:
+                        wheel.record[row[0]] = (
+                            row[1] if len(row) > 1 else "",
+                            row[2] if len(row) > 2 else "",
+                        )
+    return wheel
+
+
+class SdistData:
+    def __init__(self, path):
+        self.path = path
+        self.files = []
+        self.pkg_info = {}
+        self.filename_name, self.filename_version = parse_sdist_filename(path)
+
+
+def read_sdist(path):
+    sdist = SdistData(path)
+    base = os.path.basename(path)
+    if base.endswith(".zip"):
+        with zipfile.ZipFile(path) as zf:
+            sdist.files = [n for n in zf.namelist() if not n.endswith("/")]
+            for n in sdist.files:
+                if n.count("/") == 1 and n.endswith("PKG-INFO"):
+                    sdist.pkg_info = parse_rfc822_headers(
+                        zf.read(n).decode("utf-8", "replace")
+                    )
+    else:
+        with tarfile.open(path, "r:*") as tf:
+            for member in tf.getmembers():
+                if member.isfile():
+                    sdist.files.append(member.name)
+            for n in sdist.files:
+                if n.count("/") == 1 and n.endswith("PKG-INFO"):
+                    f = tf.extractfile(n)
+                    if f:
+                        sdist.pkg_info = parse_rfc822_headers(
+                            f.read().decode("utf-8", "replace")
+                        )
+    return sdist
+
+
+def _meta_name_version(headers):
+    name = (headers.get("Name") or [""])[0]
+    version = (headers.get("Version") or [""])[0]
+    return name, version
+
+
+# ---------------------------------------------------------------- checks
+
+
+def check_metadata_consistency(kind, headers, filename_name, filename_version, rep):
+    name, version = _meta_name_version(headers)
+    if not name:
+        rep.add("error", "metadata-no-name", "METADATA/PKG-INFO has no Name field")
+    if not version:
+        rep.add("error", "metadata-no-version", "METADATA/PKG-INFO has no Version field")
+    if filename_name and name and _norm_name(filename_name) != _norm_name(name):
+        rep.add(
+            "error",
+            "metadata-name-mismatch",
+            f"filename implies name {filename_name!r} but metadata says {name!r}",
+        )
+    if filename_version and version and filename_version != version:
+        rep.add(
+            "warning",
+            "metadata-version-mismatch",
+            f"filename implies version {filename_version!r} but metadata says {version!r}",
+        )
+
+
+def _b64_nopad(data):
+    return base64.urlsafe_b64encode(data).rstrip(b"=").decode("ascii")
+
+
+def check_record(wheel, rep):
+    """Every file in the zip must be listed in RECORD with a valid hash/size."""
+    try:
+        zf = zipfile.ZipFile(wheel.path)
+    except zipfile.BadZipFile:
+        rep.add("error", "bad-wheel", f"{wheel.path} is not a valid zip file")
+        return
+    with zf:
+        if not wheel.record:
+            rep.add("error", "record-missing", "wheel has no .dist-info/RECORD")
+            return
+        zfiles = set(wheel.files)
+        for f in sorted(zfiles):
+            if _is_signature_record(f):
+                continue
+            if f not in wheel.record:
+                rep.add(
+                    "error",
+                    "record-entry-missing",
+                    f"file {f} is in the wheel but not listed in RECORD",
+                )
+        for f in sorted(wheel.record):
+            digest, size = wheel.record[f]
+            if f not in zfiles:
+                rep.add(
+                    "error",
+                    "record-dangling",
+                    f"RECORD lists {f} but it is missing from the wheel",
+                )
+                continue
+            if digest:
+                algo, _, expected = digest.partition("=")
+                if algo.lower() == "sha256":
+                    try:
+                        actual = _b64_nopad(hashlib.sha256(zf.read(f)).digest())
+                    except KeyError:
+                        continue
+                    if actual != expected:
+                        rep.add(
+                            "error",
+                            "record-hash-mismatch",
+                            f"RECORD hash mismatch for {f} (file changed after RECORD was written)",
+                        )
+            if size and size.isdigit():
+                try:
+                    actual_size = zf.getinfo(f).file_size
+                except KeyError:
+                    continue
+                if int(size) != actual_size:
+                    rep.add(
+                        "error",
+                        "record-size-mismatch",
+                        f"RECORD size mismatch for {f}: listed {size}, actual {actual_size}",
+                    )
+
+
+def _entry_point_target_path(value, files):
+    """Resolve 'module:attr [extras]' to a path inside the wheel, or None."""
+    target = value.split()[0]  # strip "[extra]" markers
+    module = target.split(":")[0].strip()
+    if not module or not re.match(r"^[A-Za-z_][\w.]*$", module):
+        return None
+    rel = module.replace(".", "/")
+    for candidate in (rel + ".py", rel + "/__init__.py"):
+        if candidate in files:
+            return candidate
+    return None
+
+
+def check_entry_points(wheel, rep):
+    files = set(wheel.files)
+    for group in sorted(wheel.entry_points):
+        for name, value in wheel.entry_points[group]:
+            if _entry_point_target_path(value, files) is None:
+                rep.add(
+                    "error",
+                    "entry-point-dangling",
+                    f"[{group}] {name} = {value}: target module not found in wheel",
+                )
+
+
+def _top_package_dirs(files):
+    """Map top-level package dir -> {'py': set, 'pyi': set, 'py_typed': bool}."""
+    pkgs = {}
+    for f in files:
+        if _is_dist_info(f) or "/" not in f:
+            continue
+        top = f.split("/")[0]
+        if top in _NON_PACKAGE_TOPS or top.endswith(".data"):
+            continue
+        entry = pkgs.setdefault(top, {"py": set(), "pyi": set(), "py_typed": False})
+        base = f.rsplit("/", 1)[-1]
+        if f.endswith("/py.typed") or base == "py.typed":
+            entry["py_typed"] = True
+        elif f.endswith(".py"):
+            entry["py"].add(f[: -len(".py")])
+        elif f.endswith(".pyi"):
+            entry["pyi"].add(f[: -len(".pyi")])
+    return pkgs
+
+
+def check_typing(wheel, rep):
+    """Stub consistency: packages shipping some .pyi should ship them all."""
+    pkgs = _top_package_dirs(wheel.files)
+    for pkg in sorted(pkgs):
+        entry = pkgs[pkg]
+        if entry["py_typed"]:
+            rep.add(
+                "info",
+                "typing-py-typed",
+                f"package {pkg}/ ships py.typed (typed package marker)",
+            )
+        if entry["pyi"]:
+            missing = sorted(
+                s for s in entry["py"] - entry["pyi"]
+                if s.split("/")[-1] != "__init__"
+                # __init__.py rarely carries annotations worth stubbing;
+                # flagging it would drown the signal in noise.
+            )
+            for stem in missing:
+                rep.add(
+                    "warning",
+                    "typing-stub-missing",
+                    f"{pkg}/ ships .pyi stubs but {stem}.py has no sibling .pyi "
+                    f"(downstream type checkers may fail)",
+                    detail=f"{stem}.py",
+                )
+            for stem in sorted(entry["pyi"] - entry["py"]):
+                # A stub for a C extension (stem.so) or namespace edge is fine;
+                # only flag when neither .py nor a sibling module exists.
+                rep.add(
+                    "info",
+                    "typing-stub-orphan",
+                    f"{stem}.pyi has no sibling {stem}.py in the wheel",
+                    detail=f"{stem}.pyi",
+                )
+
+
+def check_wheel_contents(wheel, rep):
+    py_files = [
+        f
+        for f in wheel.files
+        if f.endswith(".py") and not _is_dist_info(f) and "__pycache__" not in f
+    ]
+    if not py_files:
+        rep.add(
+            "warning", "wheel-no-python", "wheel contains no .py files at all"
+        )
+    check_metadata_consistency(
+        "wheel", wheel.metadata, wheel.filename_name, wheel.filename_version, rep
+    )
+    check_record(wheel, rep)
+    check_entry_points(wheel, rep)
+    check_typing(wheel, rep)
+
+
+def check_sdist_contents(sdist, rep):
+    if not sdist.pkg_info:
+        rep.add("error", "sdist-no-pkg-info", "sdist has no PKG-INFO")
+    else:
+        check_metadata_consistency(
+            "sdist",
+            sdist.pkg_info,
+            sdist.filename_name,
+            sdist.filename_version,
+            rep,
+        )
+    py_files = [f for f in sdist.files if f.endswith(".py")]
+    if not py_files:
+        rep.add("warning", "sdist-no-python", "sdist contains no .py files at all")
+
+
+def _normalize_sdist_path(path):
+    """Strip '<name>-<version>/' and an optional 'src/' prefix."""
+    parts = path.split("/")
+    if len(parts) < 2:
+        return None
+    rest = parts[1:]
+    if rest and rest[0] == "src":
+        rest = rest[1:]
+    return "/".join(rest) if rest else None
+
+
+def check_wheel_vs_sdist(wheel, sdist, rep):
+    """Files tracked in the sdist's packages should survive into the wheel."""
+    wfiles = {
+        f
+        for f in wheel.files
+        if not _is_dist_info(f)
+        and not f.endswith("/")
+        and "__pycache__" not in f
+    }
+    # Group sdist files by top-level entry (after normalization).
+    s_groups = {}
+    for f in sdist.files:
+        n = _normalize_sdist_path(f)
+        if not n or n.endswith("/"):
+            continue
+        top = n.split("/")[0]
+        # Only compare things that look like shippable packages/modules.
+        s_groups.setdefault(top, []).append(n)
+
+    w_groups = {}
+    for f in wfiles:
+        top = f.split("/")[0]
+        w_groups.setdefault(top, []).append(f)
+
+    for top in sorted(s_groups):
+        if top in _NON_PACKAGE_TOPS:
+            continue
+        s_here = s_groups[top]
+        # Skip top-level non-package files (setup.py, README, ...) and dirs
+        # with no Python files at all.
+        if "/" not in s_here[0] and not s_here[0].endswith(".py"):
+            continue
+        if not any(p.endswith(".py") for p in s_here):
+            continue
+        s_rel = {p[len(top) + 1 :] for p in s_here}
+        w_rel = {p[len(top) + 1 :] for p in w_groups.get(top, []) if "/" in p}
+        # Also cover top-level modules (top.py in wheel vs top/<file> mismatch):
+        for missing in sorted(s_rel - w_rel):
+            # .pyi presence differences are covered by check_typing; still
+            # worth flagging here since sdist->wheel drops are the core story.
+            rep.add(
+                "warning",
+                "sdist-file-missing-in-wheel",
+                f"{top}/{missing} is in the sdist but missing from the wheel",
+                detail=f"{top}/{missing}",
+            )
+        for extra in sorted(w_rel - s_rel):
+            rep.add(
+                "info",
+                "wheel-file-not-in-sdist",
+                f"{top}/{extra} is in the wheel but not in the sdist",
+                detail=f"{top}/{extra}",
+            )
+    # Top-level modules (foo.py) that exist in sdist but not wheel.
+    s_toplevel_py = {
+        n for n in (_normalize_sdist_path(f) for f in sdist.files) if n and "/" not in n and n.endswith(".py")
+    }
+    w_toplevel_py = {f for f in wfiles if "/" not in f and f.endswith(".py")}
+    for missing in sorted(s_toplevel_py - w_toplevel_py):
+        rep.add(
+            "warning",
+            "sdist-file-missing-in-wheel",
+            f"{missing} is in the sdist but missing from the wheel",
+            detail=missing,
+        )
+
+# ------------------------------------------------- --project heuristics
+
+
+def _read_text(path):
+    try:
+        with open(path, "r", encoding="utf-8", errors="replace") as fh:
+            return fh.read()
+    except OSError:
+        return ""
+
+
+def expected_packages_from_project(projdir):
+    """Best-effort (name, [top-level packages]) from project config files.
+
+    Returns (name_or_None, packages_or_None). Parses pyproject.toml,
+    setup.cfg and setup.py with small targeted parsers (no external deps).
+    """
+    name = None
+    packages = None
+
+    pyproject = _read_text(os.path.join(projdir, "pyproject.toml"))
+    if pyproject:
+        # [project] name
+        m = re.search(
+            r"(?ms)^\[project\].*?^\s*name\s*=\s*[\"']([^\"']+)[\"']", pyproject
+        )
+        if m:
+            name = m.group(1)
+        # [tool.setuptools.packages.find] namespaces / include
+        m = re.search(
+            r"(?ms)^\[tool\.setuptools\.packages\.find\].*?^\s*namespaces\s*=\s*(true|false)",
+            pyproject,
+        )
+        # explicit [tool.setuptools] packages = [...]
+        m2 = re.search(
+            r"(?ms)^\[tool\.setuptools\].*?^\s*packages\s*=\s*\[([^\]]*)\]",
+            pyproject,
+        )
+        if m2:
+            packages = re.findall(r"[\"']([\w.]+)[\"']", m2.group(1))
+
+    setup_cfg = _read_text(os.path.join(projdir, "setup.cfg"))
+    if setup_cfg:
+        m = re.search(r"(?m)^\[metadata\].*?^name\s*=\s*(.+)$", setup_cfg)
+        if m and not name:
+            name = m.group(1).strip()
+        m = re.search(r"(?m)^\[options\].*?^packages\s*=\s*(.+)$", setup_cfg)
+        if m and packages is None:
+            first = m.group(1).strip()
+            if first == "find:":
+                packages = None  # auto-discovery; handled below
+            else:
+                # multi-line list under [options]
+                block = re.search(
+                    r"(?m)^\[options\].*?^packages\s*=\s*\n((?:[ \t]+\S.*\n?)+)",
+                    setup_cfg,
+                )
+                if block:
+                    packages = [
+                        ln.strip()
+                        for ln in block.group(1).splitlines()
+                        if ln.strip()
+                    ]
+                else:
+                    packages = [p.strip() for p in first.split(",") if p.strip()]
+
+    setup_py = _read_text(os.path.join(projdir, "setup.py"))
+    if setup_py:
+        if not name:
+            m = re.search(r"name\s*=\s*[\"']([^\"']+)[\"']", setup_py)
+            if m:
+                name = m.group(1)
+        if packages is None:
+            m = re.search(r"packages\s*=\s*\[([^\]]*)\]", setup_py)
+            if m:
+                packages = re.findall(r"[\"']([\w.]+)[\"']", m.group(1))
+
+    if packages is None:
+        # Auto-discovery fallback: top-level dirs with __init__.py (+ src/ layout).
+        found = []
+        for base in ("", "src"):
+            d = os.path.join(projdir, base) if base else projdir
+            try:
+                entries = os.listdir(d)
+            except OSError:
+                continue
+            for entry in entries:
+                full = os.path.join(d, entry)
+                if os.path.isdir(full) and os.path.isfile(
+                    os.path.join(full, "__init__.py")
+                ):
+                    found.append(entry)
+        packages = sorted(set(found)) or None
+
+    # Normalize dotted names to top-level dirs.
+    if packages:
+        tops = sorted({p.split(".")[0] for p in packages})
+    else:
+        tops = None
+    return name, tops
+
+
+def check_project_against_wheel(wheel, projdir, rep):
+    name, tops = expected_packages_from_project(projdir)
+    if name and wheel.filename_name and _norm_name(name) != _norm_name(
+        wheel.filename_name
+    ):
+        rep.add(
+            "warning",
+            "project-name-mismatch",
+            f"project config names the distribution {name!r} "
+            f"but the wheel file says {wheel.filename_name!r}",
+        )
+    if not tops:
+        rep.add(
+            "info",
+            "project-no-packages",
+            "could not determine expected packages from project config",
+        )
+        return
+    wheel_tops = {f.split("/")[0] for f in wheel.files if "/" in f}
+    wheel_toplevel_py = {
+        f[:-3] for f in wheel.files if "/" not in f and f.endswith(".py")
+    }
+    for top in tops:
+        if top not in wheel_tops and top not in wheel_toplevel_py:
+            rep.add(
+                "error",
+                "project-package-missing",
+                f"package {top!r} is configured in the project but missing from the wheel",
+            )
+
+
+# ------------------------------------------------------------------ smoke
+
+
+def _top_level_modules(wheel):
+    mods = set()
+    for f in wheel.files:
+        if _is_dist_info(f) or "__pycache__" in f:
+            continue
+        if "/" not in f and f.endswith(".py"):
+            mods.add(f[:-3])
+        elif f.endswith("/__init__.py"):
+            mods.add(f.split("/")[0])
+    return sorted(m for m in mods if m.isidentifier())[:25]
+
+
+def smoke_test_wheel(wheel, rep, timeout=180):
+    """Install the wheel into a throwaway venv and import top-level modules."""
+    mods = _top_level_modules(wheel)
+    if not mods:
+        rep.add("info", "smoke-no-modules", "smoke test skipped: no importable modules found")
+        return
+    tmp = tempfile.mkdtemp(prefix="wheeltruth-smoke-")
+    venv_dir = os.path.join(tmp, "venv")
+    try:
+        proc = subprocess.run(
+            [sys.executable, "-m", "venv", venv_dir],
+            capture_output=True, text=True, timeout=120,
+        )
+    except (OSError, subprocess.TimeoutExpired) as exc:
+        rep.add("info", "smoke-unavailable", f"smoke test unavailable: {exc}")
+        return
+    if proc.returncode != 0:
+        rep.add("info", "smoke-unavailable", "smoke test unavailable: venv creation failed")
+        return
+    bindir = os.path.join(venv_dir, "Scripts" if os.name == "nt" else "bin")
+    pip = os.path.join(bindir, "pip")
+    vpy = os.path.join(bindir, "python")
+    try:
+        proc = subprocess.run(
+            [pip, "install", "--no-deps", "--no-index", "--quiet", wheel.path],
+            capture_output=True, text=True, timeout=120,
+        )
+    except (OSError, subprocess.TimeoutExpired) as exc:
+        rep.add("warning", "smoke-install-failed", f"smoke test: pip install failed: {exc}")
+        return
+    if proc.returncode != 0:
+        rep.add(
+            "error", "smoke-install-failed",
+            "smoke test: pip install of the wheel failed",
+            detail=proc.stderr[-2000:],
+        )
+        return
+    failed = []
+    for mod in mods:
+        try:
+            proc = subprocess.run(
+                [vpy, "-c", f"import {mod}"],
+                capture_output=True, text=True, timeout=30,
+            )
+        except (OSError, subprocess.TimeoutExpired):
+            failed.append((mod, "timeout"))
+            continue
+        if proc.returncode != 0:
+            failed.append((mod, proc.stderr.strip().splitlines()[-1][:200] if proc.stderr.strip() else "import failed"))
+    for mod, err in failed:
+        rep.add("error", "smoke-import-failed", f"smoke test: import {mod} failed: {err}")
+    if not failed:
+        rep.add("info", "smoke-ok", f"smoke test: {len(mods)} top-level module(s) imported cleanly")
+
+
+# ----------------------------------------------------------------- reports
+
+
+def render_text(reports):
+    lines = []
+    for rep in reports:
+        lines.append(f"== {rep.path} ({rep.kind}) ==")
+        if not rep.findings:
+            lines.append("  OK: no issues found")
+        for f in rep.findings:
+            lines.append(f"  [{f.severity.upper():7}] {f.code}: {f.message}")
+        lines.append("")
+    return "\n".join(lines).rstrip() + "\n"
+
+
+def render_markdown(reports):
+    lines = ["# wheeltruth report", ""]
+    for rep in reports:
+        lines.append(f"## `{os.path.basename(rep.path)}` ({rep.kind})")
+        lines.append("")
+        if not rep.findings:
+            lines.append("OK: no issues found")
+        else:
+            lines.append("| severity | code | message |")
+            lines.append("|---|---|---|")
+            for f in rep.findings:
+                msg = f.message.replace("|", "\\|")
+                lines.append(f"| {f.severity} | `{f.code}` | {msg} |")
+        lines.append("")
+    return "\n".join(lines)
+
+
+def check_artifacts(paths, project=None, smoke=False):
+    """Run all checks over the given artifact paths. Returns [ArtifactReport]."""
+    reports = []
+    wheels = []
+    sdists = []
+    for path in paths:
+        base = os.path.basename(path)
+        rep = None
+        try:
+            if base.endswith(".whl"):
+                rep = ArtifactReport(path, "wheel")
+                wheel = read_wheel(path)
+                wheels.append((wheel, rep))
+                check_wheel_contents(wheel, rep)
+                if project:
+                    check_project_against_wheel(wheel, project, rep)
+                if smoke:
+                    smoke_test_wheel(wheel, rep)
+            elif base.endswith((".tar.gz", ".tgz", ".zip")):
+                rep = ArtifactReport(path, "sdist")
+                sdist = read_sdist(path)
+                sdists.append((sdist, rep))
+                check_sdist_contents(sdist, rep)
+            else:
+                rep = ArtifactReport(path, "unknown")
+                rep.add("error", "unknown-artifact",
+                        f"don't know how to check {base!r}: expected .whl or .tar.gz")
+        except (zipfile.BadZipFile, tarfile.TarError, OSError) as exc:
+            if rep is None:
+                rep = ArtifactReport(path, "unknown")
+            rep.add("error", "unreadable-artifact", f"could not read {base}: {exc}")
+        reports.append(rep)
+
+    # Cross-artifact comparison when we have both kinds.
+    if wheels and sdists:
+        # Pair each wheel with the sdist of the same distribution when possible.
+        for wheel, wrep in wheels:
+            wn = _norm_name(wheel.filename_name or (wheel.metadata.get("Name") or [""])[0])
+            partner = None
+            for sdist, _srep in sdists:
+                sn = _norm_name(sdist.filename_name or (sdist.pkg_info.get("Name") or [""])[0])
+                if wn and sn and wn == sn:
+                    partner = sdist
+                    break
+            if partner is None:
+                partner = sdists[0][0]
+            cross = ArtifactReport(f"{wheel.path} vs {partner.path}", "wheel-vs-sdist")
+            check_wheel_vs_sdist(wheel, partner, cross)
+            # Merge cross findings into the wheel's report for simpler output.
+            wrep.findings.extend(cross.findings)
+
+    return reports

wheeltruth/cli.py

@@ -0,0 +1,65 @@
+"""wheeltruth: does your built wheel/sdist actually contain what it should?"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+
+from . import check as _check
+
+__version__ = "0.1.0"
+
+
+def _exit_code(reports):
+    for rep in reports:
+        for f in rep.findings:
+            if f.severity in ("warning", "error"):
+                return 1
+    # Operational failures (unreadable artifacts) are errors too, but they
+    # already surface as error findings above. Exit 2 is reserved for CLI
+    # usage errors, which argparse handles itself.
+    return 0
+
+
+def cmd_check(args):
+    reports = _check.check_artifacts(args.artifacts, project=args.project, smoke=args.smoke)
+    if args.report == "md":
+        sys.stdout.write(_check.render_markdown(reports))
+    elif not args.quiet:
+        sys.stdout.write(_check.render_text(reports))
+    return _exit_code(reports)
+
+
+def build_parser():
+    parser = argparse.ArgumentParser(
+        prog="wheeltruth",
+        description="Check that your built wheel/sdist actually contains "
+                    "everything the package needs.",
+    )
+    parser.add_argument("--version", action="version", version=f"%(prog)s {__version__}")
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    p = sub.add_parser("check", help="check built artifacts for missing content")
+    p.add_argument("artifacts", nargs="+", help=".whl and/or .tar.gz files to check")
+    p.add_argument("--project", default=None,
+                   help="project directory with pyproject.toml/setup.cfg/setup.py "
+                        "to derive expected packages from")
+    p.add_argument("--smoke", action="store_true",
+                   help="install the wheel into a throwaway venv and import "
+                        "top-level modules")
+    p.add_argument("--report", choices=["text", "md"], default="text",
+                   help="output format (default: text)")
+    p.add_argument("--quiet", "-q", action="store_true",
+                   help="suppress output; only the exit code signals issues")
+    p.set_defaults(func=cmd_check)
+    return parser
+
+
+def main(argv=None):
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    return args.func(args)
+
+
+if __name__ == "__main__":
+    sys.exit(main())

wheeltruth-0.1.0.dist-info/METADATA

@@ -0,0 +1,108 @@
+Metadata-Version: 2.4
+Name: wheeltruth
+Version: 0.1.0
+Summary: Check that your built wheel/sdist actually contains everything the package needs
+Author: hao li
+License: MIT
+Project-URL: Homepage, https://github.com/hahahahahahahahah6/wheeltruth
+Keywords: pypi,wheel,packaging,ci,sdist
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# wheeltruth
+
+**Your tests passed. Your published wheel is missing files.**
+
+`wheeltruth` checks that your built wheel/sdist actually contains everything the
+package needs — before your users find out the hard way.
+
+## The problem
+
+`twine check` verifies your README renders. Nothing in the standard toolchain
+verifies that the *files* made it into the artifact. Two real cases from 2026:
+
+- **MLX v0.32.0** (2026-07-25): the macOS ARM64 wheel shipped `py.typed` but
+  silently dropped every `.pyi` stub the previous release had. Downstream type
+  checking broke, and the test suite never noticed — because tests run against
+  the source tree, not the wheel.
+- **OpenSpace** (2026-06-14): a tracked `host_skills/` directory vanished from
+  the built distribution, breaking integrations for everyone who installed it.
+
+Build backends, MANIFEST.in glitches, and `package-data` misconfigurations drop
+files quietly. `wheeltruth` inspects the artifact itself — the thing PyPI
+actually serves — not your repo.
+
+## Install
+
+```bash
+pip install wheeltruth
+```
+
+## Usage
+
+```bash
+# Check one or more built artifacts
+wheeltruth check dist/*
+
+# Compare a wheel against its sdist (catches files dropped between the two)
+wheeltruth check dist/mypkg-1.0-py3-none-any.whl dist/mypkg-1.0.tar.gz
+
+# Also verify expected packages from the project config
+wheeltruth check dist/* --project .
+
+# Install into a throwaway venv and import every top-level module
+wheeltruth check dist/*.whl --smoke
+
+# Machine-readable report for CI logs / PR comments
+wheeltruth check dist/* --report md
+```
+
+Exit code is `0` when clean, `1` when issues are found — drop it straight into CI:
+
+```yaml
+- name: Build
+  run: python -m build
+- name: Verify artifacts
+  run: |
+    pip install wheeltruth
+    wheeltruth check dist/*
+```
+
+## What it checks
+
+**Wheel only**
+- `RECORD` completeness: every file in the zip is listed, every listed file
+  exists, and sha256 hashes/sizes match (tampered or hand-edited wheels fail).
+- `entry_points.txt`: every `console_scripts`/`gui_scripts` target resolves to
+  a module actually inside the wheel (no more `ModuleNotFoundError` on first run).
+- Typing stub consistency: if a package ships *some* `.pyi` stubs, every
+  module should have one — a half-dropped stub set (the MLX case) is flagged.
+- `METADATA` name/version consistency with the wheel filename.
+
+**Wheel vs sdist**
+- Files tracked in the sdist's packages that never made it into the wheel
+  (the OpenSpace case), and vice versa. Handles `src/` layouts and ignores
+  `tests/`, `docs/`, etc.
+
+**With `--project .`**
+- Packages declared in `pyproject.toml` / `setup.cfg` / `setup.py` (or
+  auto-discovered) actually exist in the wheel.
+
+**With `--smoke`**
+- Installs the wheel into a throwaway venv (`--no-deps --no-index`) and
+  imports every top-level module.
+
+## Limitations (v0.1)
+
+- v0.1 is **check-only**: it reports problems, it doesn't fix your build config.
+- Heuristics, not proof: "expected files" are inferred from the sdist or
+  project config. Exotic layouts may produce false positives — file an issue.
+- `--smoke` needs a working `venv` + `pip` and takes a few seconds per wheel.
+- Stub checks are consistency checks; they can't know what the *previous*
+  release shipped.
+
+## License
+
+MIT

wheeltruth-0.1.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+wheeltruth/__init__.py,sha256=4JdoQJvr1CX5mFZFzvW-lfcKbUgMzcWvuEyIHqnugjk,100
+wheeltruth/check.py,sha256=E62FJrH5Z3bDOPrsAt99NYiBsFzPoHtsNBWShcEWH6s,27545
+wheeltruth/cli.py,sha256=7iTbm_eehZBjreoClGt2b1gQMY5w61LjWjdOx2uAsGM,2266
+wheeltruth-0.1.0.dist-info/licenses/LICENSE,sha256=OYhQDg7nxWoFtnF6J8NkFUA8NMw5TKv9a1WTXHY-fu4,1063
+wheeltruth-0.1.0.dist-info/METADATA,sha256=ZKGzGlLCKI_bgdvC_QWECetVyUYhMXk1NG19P4D__Rk,3672
+wheeltruth-0.1.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+wheeltruth-0.1.0.dist-info/entry_points.txt,sha256=t1dDTJuYwj-E_IGPWQp7Aaa62_nJHtMPxxue6rNJN3U,51
+wheeltruth-0.1.0.dist-info/top_level.txt,sha256=pCpdnnYQLdO5dbW7QiSuf_p6C8byCUquEw3LQJ3QDgs,11
+wheeltruth-0.1.0.dist-info/RECORD,,

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

wheeltruth-0.1.0.dist-info/entry_points.txt

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

wheeltruth-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.

wheeltruth-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+wheeltruth