wheelgap 0.1.0__tar.gz

wheelgap-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,50 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    name: test (${{ matrix.os }}, py${{ matrix.python }})
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest]
+        python: ["3.11", "3.12", "3.13", "3.14"]
+        include:
+          - { os: macos-latest, python: "3.14" }
+          - { os: windows-latest, python: "3.14" }
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          persist-credentials: false
+      - uses: astral-sh/setup-uv@v10.3.3
+      - run: uv run --python ${{ matrix.python }} --group dev pytest -v
+
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          persist-credentials: false
+      - uses: astral-sh/setup-uv@v10.3.3
+      - run: uv run --group dev ruff check .
+      - run: uv run --group dev ruff format --check .
+
+  dogfood:
+    name: wheelgap checks its own uv.lock (via the action)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          persist-credentials: false
+      - uses: ./
+        with:
+          args: uv.lock -p 3.11,3.14,3.14t -t all

wheelgap-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,43 @@
+name: Publish to PyPI
+
+# Uses PyPI trusted publishing (no API token). One-time setup:
+#   1. https://pypi.org/manage/account/publishing/ -> add a pending publisher:
+#      project "wheelgap", owner "patrickballard", repo "wheelgap", workflow "publish.yml", environment "pypi"
+#   2. Repo Settings -> Variables -> add PYPI_PUBLISH = true
+#   3. Run this workflow (Actions tab -> Publish to PyPI -> Run workflow), or publish a release.
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    if: vars.PYPI_PUBLISH == 'true'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          persist-credentials: false
+      - uses: astral-sh/setup-uv@v10.3.3
+      - run: uv build
+      - uses: actions/upload-artifact@v7
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v8
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1

wheelgap-0.1.0/.gitignore

@@ -0,0 +1,8 @@
+__pycache__/
+*.py[cod]
+.venv/
+dist/
+build/
+*.egg-info/
+.pytest_cache/
+.ruff_cache/

wheelgap-0.1.0/CHANGELOG.md

@@ -0,0 +1,11 @@
+# Changelog
+
+## 0.1.0 (2026-11-08)
+
+First release.
+
+- Reads `uv.lock`, `pylock.toml` (PEP 751), `poetry.lock`, `requirements.txt` (with `-r` includes), or package names on the command line.
+- Targets: `linux-x86_64`, `linux-aarch64`, `musl-x86_64`, `musl-aarch64`, `macos-arm64`, `macos-x86_64`, `win-amd64`, `win-arm64`, for any CPython version including free-threaded builds (`3.14t`).
+- Evaluates environment markers and walks the `uv.lock` dependency graph per target, so Windows-only or old-Python-only packages don't show up as false gaps.
+- Works offline from lockfiles that record their files; `--online` re-checks against PyPI.
+- `--json` output and CI-friendly exit codes (0 clean, 1 gaps, 2 error). Also usable as a GitHub Action.

wheelgap-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,14 @@
+# Contributing
+
+Thanks for helping! wheelgap is deliberately small: one job, one dependency (`packaging`).
+
+```bash
+git clone https://github.com/patrickballard/wheelgap && cd wheelgap
+uv run --group dev pytest        # tests
+uv run --group dev ruff check .  # lint
+uv run wheelgap numpy -t all     # try it
+```
+
+- Issues labelled [`good first issue`](https://github.com/patrickballard/wheelgap/labels/good%20first%20issue) are scoped to be doable in an evening.
+- Please add a test with any behaviour change. Tests never hit the network (see the `fake_pypi` fixture in `tests/conftest.py`).
+- Found a wheel that wheelgap misjudges? Open an issue with the wheel filename and the target; those make great test cases.

wheelgap-0.1.0/LICENSE

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

wheelgap-0.1.0/PKG-INFO

@@ -0,0 +1,143 @@
+Metadata-Version: 2.5
+Name: wheelgap
+Version: 0.1.0
+Summary: Find the Python dependencies that have no prebuilt wheel for your target platform, before your Docker build does.
+Project-URL: Homepage, https://github.com/patrickballard/wheelgap
+Project-URL: Issues, https://github.com/patrickballard/wheelgap/issues
+Project-URL: Changelog, https://github.com/patrickballard/wheelgap/blob/main/CHANGELOG.md
+Author: Patrick Ballard
+License-Expression: MIT
+License-File: LICENSE
+Keywords: alpine,arm64,docker,free-threading,lockfile,musllinux,packaging,pypi,uv,wheels
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Build Tools
+Classifier: Topic :: System :: Software Distribution
+Requires-Python: >=3.11
+Requires-Dist: packaging>=24.2
+Description-Content-Type: text/markdown
+
+# wheelgap
+
+[![CI](https://github.com/patrickballard/wheelgap/actions/workflows/ci.yml/badge.svg)](https://github.com/patrickballard/wheelgap/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-blue)
+
+**Find the Python dependencies that have no prebuilt wheel for your target platform, before your Docker build does.**
+
+Point it at your lockfile and the platforms you ship to (ARM servers, Alpine images, Windows on ARM, free-threaded Python 3.14t). It tells you which packages pip or uv will have to compile from source, and which can't be installed at all.
+
+![wheelgap demo](docs/demo.gif)
+
+## Install and run (under 30 seconds)
+
+With [uv](https://docs.astral.sh/uv/):
+
+```bash
+uvx --from git+https://github.com/patrickballard/wheelgap wheelgap
+```
+
+Or with pipx:
+
+```bash
+pipx run --spec git+https://github.com/patrickballard/wheelgap wheelgap
+```
+
+Run either one in a project directory. It finds `uv.lock`, `pylock.toml`, `poetry.lock` or `requirements.txt` on its own.
+
+## Usage
+
+```bash
+# Will my Alpine ARM image compile anything?
+wheelgap -p 3.13 -t alpine-arm64
+
+# Is my stack ready for free-threaded Python 3.14?
+wheelgap -p 3.14t -t all
+
+# Several Pythons at once, Linux on both architectures
+wheelgap uv.lock -p 3.12,3.13,3.14 -t linux-x86_64,linux-aarch64
+
+# No lockfile? Check packages directly (latest version, or pin one)
+wheelgap psycopg2 uvloop numpy==2.3.4 -t windows,win-arm64
+
+# Machine-readable, for scripts and CI
+wheelgap --json > wheelgap.json
+```
+
+Each cell in the table is one of:
+
+| cell | meaning |
+| --- | --- |
+| `✓` | a compatible wheel exists, so the install is fast |
+| `● source` | no wheel, only an sdist, so it compiles at install time (needs a compiler, headers, time) |
+| `✗ missing` | no wheel and no sdist, so the install fails |
+| `–` | not installed on this target (environment markers exclude it) |
+
+Packages that are fine everywhere are hidden; `--all` shows them.
+
+**Exit codes:** `0` no gaps, `1` gaps found, `2` bad input. `--exit-zero` always exits `0`.
+
+### Targets
+
+| name | aliases | wheel tags it accepts |
+| --- | --- | --- |
+| `linux-x86_64` | `linux`, `linux-amd64` | `manylinux_2_*_x86_64` up to `--glibc` (default 2.36), legacy `manylinux2014`/`2010`/`1` |
+| `linux-aarch64` | `linux-arm64` | `manylinux_2_*_aarch64` |
+| `musl-x86_64` | `alpine`, `musl` | `musllinux_1_*_x86_64` up to `--musl` (default 1.2) |
+| `musl-aarch64` | `alpine-arm64` | `musllinux_1_*_aarch64` |
+| `macos-arm64` | `macos`, `mac` | `macosx_*_arm64` and `universal2` up to `--macos` (default 14.0) |
+| `macos-x86_64` | `macos-intel` | `macosx_*_x86_64` and `universal2` |
+| `win-amd64` | `windows`, `win` | `win_amd64` |
+| `win-arm64` | `windows-arm64` | `win_arm64` |
+
+`-t all` checks all eight. Python versions take a trailing `t` for free-threaded builds (`3.14t`), which correctly rejects `abi3` wheels. Without `-p`, wheelgap uses the Python it is running on.
+
+### In CI (GitHub Action)
+
+```yaml
+- uses: actions/checkout@v7
+- uses: patrickballard/wheelgap@v0.1.0
+  with:
+    args: uv.lock -p 3.13 -t linux-x86_64,linux-aarch64
+```
+
+The job fails when a dependency would build from source on a target you ship, for example when a dependency bump drops ARM wheels.
+
+## How it works
+
+- **Lockfiles are read offline.** `uv.lock`, `pylock.toml` and `poetry.lock` already record every file published for each pinned version. wheelgap parses the wheel filenames' tags with [`packaging`](https://packaging.pypa.io/) and checks them against the exact tag set each target accepts. That is the same logic pip and uv use to pick a wheel.
+- **`requirements.txt` and bare package names** are looked up on the PyPI JSON API. Feed it a fully pinned file (from `uv pip compile`, `pip-compile` or `uv export`): wheelgap checks the lines you give it and doesn't resolve dependencies.
+- **Environment markers are respected.** A `pywin32 ; sys_platform == 'win32'` dependency won't show up as a Linux gap. For `uv.lock` the dependency graph is walked per target, so transitive platform-specific packages are handled too.
+- `--online` re-checks lockfile packages against PyPI. Use it when a project has uploaded new wheels for an existing version since you locked, or if your `uv.lock` was generated with `environments` restrictions.
+
+## Why this exists
+
+Missing wheels show up late, in the most expensive place:
+
+- Your `python:3.13-alpine` image on an ARM runner takes 25 minutes because two transitive dependencies don't publish `musllinux_aarch64` wheels, and QEMU is compiling them.
+- A build fails with `error: Microsoft Visual C++ 14.0 or greater is required` on a teammate's Snapdragon laptop.
+- You try free-threaded Python 3.14t and half your stack quietly falls back to source builds, because `abi3` wheels don't apply there.
+
+Sites like [pyreadiness.org](https://pyreadiness.org) and [free-threaded wheels](https://hugovk.github.io/free-threaded-wheels/) track the top few hundred packages. wheelgap checks your packages, at your pinned versions, for your targets, in about a second, and it can run in CI.
+
+## Roadmap
+
+- [ ] Pyodide/WebAssembly, iOS and Android targets
+- [ ] Read targets from `[tool.wheelgap]` in `pyproject.toml`
+- [ ] Private indexes (`--index-url`, the simple API)
+- [ ] Infer the target from a `Dockerfile` (`FROM python:3.13-alpine`, `--platform=linux/arm64`)
+- [ ] "Closest version with a wheel" hints (e.g. upgrade `foo` 1.2 → 1.4 to get `musllinux` wheels)
+- [ ] Publish to PyPI so it's just `uvx wheelgap`
+
+Contributions welcome. Issues labelled [good first issue](https://github.com/patrickballard/wheelgap/labels/good%20first%20issue) are a good start, and [CONTRIBUTING.md](CONTRIBUTING.md) has the 3-command dev setup.
+
+## License
+
+[MIT](LICENSE)

wheelgap-0.1.0/README.md

@@ -0,0 +1,117 @@
+# wheelgap
+
+[![CI](https://github.com/patrickballard/wheelgap/actions/workflows/ci.yml/badge.svg)](https://github.com/patrickballard/wheelgap/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-blue)
+
+**Find the Python dependencies that have no prebuilt wheel for your target platform, before your Docker build does.**
+
+Point it at your lockfile and the platforms you ship to (ARM servers, Alpine images, Windows on ARM, free-threaded Python 3.14t). It tells you which packages pip or uv will have to compile from source, and which can't be installed at all.
+
+![wheelgap demo](docs/demo.gif)
+
+## Install and run (under 30 seconds)
+
+With [uv](https://docs.astral.sh/uv/):
+
+```bash
+uvx --from git+https://github.com/patrickballard/wheelgap wheelgap
+```
+
+Or with pipx:
+
+```bash
+pipx run --spec git+https://github.com/patrickballard/wheelgap wheelgap
+```
+
+Run either one in a project directory. It finds `uv.lock`, `pylock.toml`, `poetry.lock` or `requirements.txt` on its own.
+
+## Usage
+
+```bash
+# Will my Alpine ARM image compile anything?
+wheelgap -p 3.13 -t alpine-arm64
+
+# Is my stack ready for free-threaded Python 3.14?
+wheelgap -p 3.14t -t all
+
+# Several Pythons at once, Linux on both architectures
+wheelgap uv.lock -p 3.12,3.13,3.14 -t linux-x86_64,linux-aarch64
+
+# No lockfile? Check packages directly (latest version, or pin one)
+wheelgap psycopg2 uvloop numpy==2.3.4 -t windows,win-arm64
+
+# Machine-readable, for scripts and CI
+wheelgap --json > wheelgap.json
+```
+
+Each cell in the table is one of:
+
+| cell | meaning |
+| --- | --- |
+| `✓` | a compatible wheel exists, so the install is fast |
+| `● source` | no wheel, only an sdist, so it compiles at install time (needs a compiler, headers, time) |
+| `✗ missing` | no wheel and no sdist, so the install fails |
+| `–` | not installed on this target (environment markers exclude it) |
+
+Packages that are fine everywhere are hidden; `--all` shows them.
+
+**Exit codes:** `0` no gaps, `1` gaps found, `2` bad input. `--exit-zero` always exits `0`.
+
+### Targets
+
+| name | aliases | wheel tags it accepts |
+| --- | --- | --- |
+| `linux-x86_64` | `linux`, `linux-amd64` | `manylinux_2_*_x86_64` up to `--glibc` (default 2.36), legacy `manylinux2014`/`2010`/`1` |
+| `linux-aarch64` | `linux-arm64` | `manylinux_2_*_aarch64` |
+| `musl-x86_64` | `alpine`, `musl` | `musllinux_1_*_x86_64` up to `--musl` (default 1.2) |
+| `musl-aarch64` | `alpine-arm64` | `musllinux_1_*_aarch64` |
+| `macos-arm64` | `macos`, `mac` | `macosx_*_arm64` and `universal2` up to `--macos` (default 14.0) |
+| `macos-x86_64` | `macos-intel` | `macosx_*_x86_64` and `universal2` |
+| `win-amd64` | `windows`, `win` | `win_amd64` |
+| `win-arm64` | `windows-arm64` | `win_arm64` |
+
+`-t all` checks all eight. Python versions take a trailing `t` for free-threaded builds (`3.14t`), which correctly rejects `abi3` wheels. Without `-p`, wheelgap uses the Python it is running on.
+
+### In CI (GitHub Action)
+
+```yaml
+- uses: actions/checkout@v7
+- uses: patrickballard/wheelgap@v0.1.0
+  with:
+    args: uv.lock -p 3.13 -t linux-x86_64,linux-aarch64
+```
+
+The job fails when a dependency would build from source on a target you ship, for example when a dependency bump drops ARM wheels.
+
+## How it works
+
+- **Lockfiles are read offline.** `uv.lock`, `pylock.toml` and `poetry.lock` already record every file published for each pinned version. wheelgap parses the wheel filenames' tags with [`packaging`](https://packaging.pypa.io/) and checks them against the exact tag set each target accepts. That is the same logic pip and uv use to pick a wheel.
+- **`requirements.txt` and bare package names** are looked up on the PyPI JSON API. Feed it a fully pinned file (from `uv pip compile`, `pip-compile` or `uv export`): wheelgap checks the lines you give it and doesn't resolve dependencies.
+- **Environment markers are respected.** A `pywin32 ; sys_platform == 'win32'` dependency won't show up as a Linux gap. For `uv.lock` the dependency graph is walked per target, so transitive platform-specific packages are handled too.
+- `--online` re-checks lockfile packages against PyPI. Use it when a project has uploaded new wheels for an existing version since you locked, or if your `uv.lock` was generated with `environments` restrictions.
+
+## Why this exists
+
+Missing wheels show up late, in the most expensive place:
+
+- Your `python:3.13-alpine` image on an ARM runner takes 25 minutes because two transitive dependencies don't publish `musllinux_aarch64` wheels, and QEMU is compiling them.
+- A build fails with `error: Microsoft Visual C++ 14.0 or greater is required` on a teammate's Snapdragon laptop.
+- You try free-threaded Python 3.14t and half your stack quietly falls back to source builds, because `abi3` wheels don't apply there.
+
+Sites like [pyreadiness.org](https://pyreadiness.org) and [free-threaded wheels](https://hugovk.github.io/free-threaded-wheels/) track the top few hundred packages. wheelgap checks your packages, at your pinned versions, for your targets, in about a second, and it can run in CI.
+
+## Roadmap
+
+- [ ] Pyodide/WebAssembly, iOS and Android targets
+- [ ] Read targets from `[tool.wheelgap]` in `pyproject.toml`
+- [ ] Private indexes (`--index-url`, the simple API)
+- [ ] Infer the target from a `Dockerfile` (`FROM python:3.13-alpine`, `--platform=linux/arm64`)
+- [ ] "Closest version with a wheel" hints (e.g. upgrade `foo` 1.2 → 1.4 to get `musllinux` wheels)
+- [ ] Publish to PyPI so it's just `uvx wheelgap`
+
+Contributions welcome. Issues labelled [good first issue](https://github.com/patrickballard/wheelgap/labels/good%20first%20issue) are a good start, and [CONTRIBUTING.md](CONTRIBUTING.md) has the 3-command dev setup.
+
+## License
+
+[MIT](LICENSE)

wheelgap-0.1.0/action.yml

@@ -0,0 +1,25 @@
+name: wheelgap
+description: Fail CI when a Python dependency has no prebuilt wheel for the platforms you ship to.
+author: patrickballard
+branding:
+  icon: package
+  color: orange
+
+inputs:
+  args:
+    description: >
+      Arguments passed to wheelgap, e.g. "uv.lock -p 3.13 -t linux-aarch64,musl-x86_64".
+      Pass -p explicitly: otherwise the runner's own Python version is assumed.
+    required: false
+    default: ""
+
+runs:
+  using: composite
+  steps:
+    - name: Run wheelgap
+      shell: bash
+      env:
+        WHEELGAP_ARGS: ${{ inputs.args }}
+        FORCE_COLOR: "1"
+      # WHEELGAP_ARGS is deliberately unquoted so it splits into separate arguments.
+      run: pipx run --spec "$GITHUB_ACTION_PATH" wheelgap $WHEELGAP_ARGS

wheelgap-0.1.0/docs/demo/requirements.txt

@@ -0,0 +1,15 @@
+fastapi
+uvicorn[standard]
+uvloop
+httptools
+psycopg2
+psycopg-binary
+pydantic-core
+numpy
+pandas
+orjson
+lxml
+grpcio
+cryptography
+pyyaml
+regex

wheelgap-0.1.0/pyproject.toml

@@ -0,0 +1,49 @@
+[project]
+name = "wheelgap"
+version = "0.1.0"
+description = "Find the Python dependencies that have no prebuilt wheel for your target platform, before your Docker build does."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Patrick Ballard" }]
+requires-python = ">=3.11"
+dependencies = ["packaging>=24.2"]
+keywords = ["wheels", "packaging", "pypi", "uv", "lockfile", "docker", "alpine", "musllinux", "free-threading", "arm64"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Software Development :: Build Tools",
+    "Topic :: System :: Software Distribution",
+]
+
+[project.urls]
+Homepage = "https://github.com/patrickballard/wheelgap"
+Issues = "https://github.com/patrickballard/wheelgap/issues"
+Changelog = "https://github.com/patrickballard/wheelgap/blob/main/CHANGELOG.md"
+
+[project.scripts]
+wheelgap = "wheelgap.cli:main"
+
+[dependency-groups]
+dev = ["pytest>=8", "ruff>=0.8"]
+
+[build-system]
+requires = ["hatchling>=1.27"]
+build-backend = "hatchling.build"
+
+[tool.ruff]
+line-length = 120
+target-version = "py311"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

wheelgap-0.1.0/src/wheelgap/__init__.py

@@ -0,0 +1,3 @@
+"""wheelgap: find the dependencies that have no prebuilt wheel for your target platform."""
+
+__version__ = "0.1.0"

wheelgap-0.1.0/src/wheelgap/__main__.py

@@ -0,0 +1,5 @@
+import sys
+
+from .cli import main
+
+sys.exit(main())

wheelgap-0.1.0/src/wheelgap/check.py

@@ -0,0 +1,134 @@
+"""Decide, per package and target, whether a prebuilt wheel exists."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from enum import StrEnum
+
+from packaging.markers import InvalidMarker, Marker, UndefinedComparison, UndefinedEnvironmentName
+from packaging.tags import Tag
+from packaging.utils import InvalidWheelFilename, canonicalize_name, parse_wheel_filename
+
+from .sources import Edge, Package, Source
+from .targets import Target
+
+
+class Status(StrEnum):
+    WHEEL = "wheel"  # a compatible wheel exists
+    SOURCE = "source"  # no compatible wheel, but an sdist: installers will build it
+    MISSING = "missing"  # no compatible wheel and no sdist: install fails
+    UNKNOWN = "unknown"  # couldn't look the package up
+    NOT_NEEDED = "n/a"  # markers say this package isn't installed on the target
+
+
+SDIST_SUFFIXES = (".tar.gz", ".zip", ".tar.bz2", ".tgz", ".tar.xz")
+
+
+@dataclass
+class Row:
+    package: Package
+    results: dict[Target, Status] = field(default_factory=dict)
+
+    @property
+    def ok(self) -> bool:
+        return all(s in (Status.WHEEL, Status.NOT_NEEDED) for s in self.results.values())
+
+    @property
+    def needed(self) -> bool:
+        return any(s is not Status.NOT_NEEDED for s in self.results.values())
+
+
+def wheel_tags(files: list[str]) -> list[frozenset[Tag]]:
+    out = []
+    for f in files:
+        if not f.endswith(".whl"):
+            continue
+        try:
+            out.append(parse_wheel_filename(f)[3])
+        except InvalidWheelFilename:
+            continue
+    return out
+
+
+def has_sdist(files: list[str]) -> bool:
+    return any(f.endswith(SDIST_SUFFIXES) for f in files)
+
+
+def status_for(files: list[str] | None, target: Target, _wheels: list[frozenset[Tag]] | None = None) -> Status:
+    if files is None:
+        return Status.UNKNOWN
+    wheels = _wheels if _wheels is not None else wheel_tags(files)
+    if any(target.accepts(t) for t in wheels):
+        return Status.WHEEL
+    return Status.SOURCE if has_sdist(files) else Status.MISSING
+
+
+_marker_cache: dict[str, Marker | None] = {}
+
+
+def marker_holds(marker: str | None, target: Target) -> bool:
+    if not marker:
+        return True
+    if marker not in _marker_cache:
+        try:
+            _marker_cache[marker] = Marker(marker)
+        except InvalidMarker:
+            _marker_cache[marker] = None
+    m = _marker_cache[marker]
+    if m is None:
+        return True  # can't parse it: assume the package is needed rather than hide a gap
+    try:
+        return m.evaluate(target.marker_env)
+    except (UndefinedComparison, UndefinedEnvironmentName):
+        return True
+
+
+def reachable(source: Source, target: Target) -> set[int]:
+    """Indexes of packages installed on `target`, walking the lockfile graph from its roots."""
+    by_name: dict[str, list[int]] = {}
+    for i, p in enumerate(source.packages):
+        by_name.setdefault(p.key, []).append(i)
+
+    def follow(edge: Edge) -> list[int]:
+        name, version, marker = edge
+        if not marker_holds(marker, target):
+            return []
+        candidates = by_name.get(canonicalize_name(name), [])
+        if version is not None:
+            candidates = [i for i in candidates if source.packages[i].version == version] or candidates
+        return candidates
+
+    seen = set(source.roots)
+    stack = list(source.roots)
+    for edge in source.root_edges:
+        stack.extend(follow(edge))
+    while stack:
+        i = stack.pop()
+        seen.add(i)
+        for edge in (source.edges or {}).get(i, []):
+            for j in follow(edge):
+                if j not in seen:
+                    seen.add(j)
+                    stack.append(j)
+    return seen
+
+
+def applies(pkg: Package, target: Target) -> bool:
+    return pkg.markers is None or any(marker_holds(m, target) for m in pkg.markers)
+
+
+def check(sources: list[Source], targets: list[Target]) -> list[Row]:
+    rows = []
+    for source in sources:
+        installed = {t: reachable(source, t) for t in targets} if source.edges is not None else None
+        for i, pkg in enumerate(source.packages):
+            if pkg.skip:
+                continue
+            files = None if pkg.error else pkg.files
+            wheels = wheel_tags(files) if files is not None else []
+            row = Row(pkg)
+            for t in targets:
+                needed = i in installed[t] if installed is not None else applies(pkg, t)
+                row.results[t] = status_for(files, t, wheels) if needed else Status.NOT_NEEDED
+            rows.append(row)
+    return rows