feat: add diff command for tracking compatibility progress over time

- Add ftready diff subcommand to compare two JSON reports
- Refactor CLI from single command to click group with default 'check' subcommand
- Show improved/regressed/added/removed packages with delta counts
- Support text and JSON output for diffs (--format text|json)
- Export DiffSummary, PackageDiff, diff_reports, format_diff from public API
- Update README: PEP 703 link, pure-Python explanation, --cache-ttl/--cache-file docs,
  tracking progress section, Python API examples, limitations section, uv install option
- Add 23 new tests for diff module and CLI subcommand (129 total, 93% coverage)

Author: dxvidparham

README.md

@@ -10,21 +10,23 @@
   <a href="https://github.com/dxvidparham/ftready/actions/workflows/ci.yml"><img src="https://github.com/dxvidparham/ftready/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
   <a href="https://pypi.org/project/ftready/"><img src="https://img.shields.io/pypi/v/ftready" alt="PyPI version"></a>
   <a href="https://pypi.org/project/ftready/"><img src="https://img.shields.io/pypi/pyversions/ftready" alt="Python versions"></a>
-  <a href="https://github.com/dxvidparham/ftready"><img src="https://img.shields.io/badge/coverage-92%25-brightgreen" alt="Coverage"></a>
+  <a href="https://github.com/dxvidparham/ftready"><img src="https://img.shields.io/badge/coverage-93%25-brightgreen" alt="Coverage"></a>
   <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="License: MIT"></a>
 </p>
 
 <p align="center">
   <a href="#-quickstart">Quickstart</a> ·
   <a href="#-features">Features</a> ·
   <a href="#-usage">Usage</a> ·
+  <a href="#-tracking-progress">Tracking Progress</a> ·
   <a href="#-ci-integration">CI Integration</a> ·
+  <a href="#-python-api">Python API</a> ·
   <a href="https://pypi.org/project/ftready/">PyPI</a>
 </p>
 
 ---
 
-Python 3.13 shipped a **free-threaded build** (`-t` suffix) that disables the GIL — unlocking true multi-core parallelism. But your project is only as ready as its **least-compatible dependency**.
+[PEP 703](https://peps.python.org/pep-0703/) introduced a **free-threaded build** of CPython (3.13t / 3.14t) that disables the GIL — unlocking true multi-core parallelism. But your project is only as ready as its **least-compatible dependency**. See the [CPython free-threading docs](https://docs.python.org/3.14/whatsnew/3.13.html#free-threaded-cpython) for background.
 
 `ftready` scans your dependency tree, queries PyPI for `cp313t`/`cp314t` wheels, cross-references [ft-checker.com](https://ft-checker.com) test results, and tells you exactly where you stand:
 
@@ -47,7 +49,7 @@ Python 3.13 shipped a **free-threaded build** (`-t` suffix) that disables the GI
 ## ⚡ Quickstart
 
 ```bash
-pip install ftready
+pip install ftready   # or: uv tool install ftready
 ftready
 ```
 
@@ -60,6 +62,7 @@ That's it. Reads your `pyproject.toml` and prints a compatibility report.
 - **Pure-Python detection** — flags packages with no C extensions as likely compatible
 - **Every input format** — `pyproject.toml` (PEP 621 + Poetry), `requirements.txt`, `uv.lock`, `poetry.lock`, `pdm.lock`
 - **Full dependency tree** — `--all-deps` scans transitive deps via lock files with pinned-version accuracy
+- **Progress tracking** — `ftready diff` compares two JSON reports to show what changed over time
 - **Multiple outputs** — rich tables, plain text, JSON, or CSV
 - **CI-ready** — configurable exit codes (`--fail-on`) to gate or report without blocking
 - **Offline-safe** — `--no-ftchecker` and `--no-pypi` flags for controlled environments
@@ -85,30 +88,62 @@ ftready --plain               # plain-text table
 ftready --format json         # JSON (for scripting)
 ftready --format csv          # CSV
 ftready --output report.txt   # write to file
+ftready -v                    # verbose progress to stderr
 ```
 
 ### Data source control
 
 ```bash
-ftready --no-ftchecker   # PyPI only (skip ft-checker.com)
-ftready --no-pypi        # ft-checker only (skip PyPI)
-ftready --no-cache       # force fresh ft-checker scrape
+ftready --no-ftchecker                  # PyPI only (skip ft-checker.com)
+ftready --no-pypi                       # ft-checker only (skip PyPI)
+ftready --no-cache                      # force fresh ft-checker scrape
+ftready --cache-ttl 48                  # cache ft-checker data for 48 hours
+ftready --cache-file /tmp/ft_cache.json # custom cache location
 ```
 
 ### Exit codes
 
-| Code | Meaning |
-| ---- | ------- |
+| Code | Meaning                                           |
+| ---- | ------------------------------------------------- |
 | `0`  | No blocking issues (configurable via `--fail-on`) |
-| `1`  | At least one dependency has a **Failed** status |
-| `2`  | Configuration error (missing input file, etc.) |
+| `1`  | At least one dependency has a **Failed** status   |
+| `2`  | Configuration error (missing input file, etc.)    |
 
 ```bash
 ftready --fail-on=never    # always exit 0 (report only)
 ftready --fail-on=unknown  # exit 1 on Failed OR Unknown
 ftready --fail-on=failed   # exit 1 on Failed only (default)
 ```
 
+## 📈 Tracking Progress
+
+Save JSON reports over time and use `ftready diff` to see what changed:
+
+```bash
+# Save a baseline
+ftready --format json --output baseline.json
+
+# ... weeks later, check again
+ftready --format json --output current.json
+
+# Compare the two
+ftready diff baseline.json current.json
+```
+
+```
+ftready diff: 2025-01-15T12:00:00+00:00 → 2025-03-01T12:00:00+00:00
+
+3.13t ready: 5 → 8 (+3)
+3.14t ready: 2 → 5 (+3)
+
+✅ Improved (3):
+  scipy: 3.13t: Not tested → Success
+  pillow: 3.13t: Not tested → Success, 3.14t: Not tested → Success
+  matplotlib: 3.14t: Not tested → Success
+```
+
+The diff also supports `--format json` for machine-readable output.
+
 ## 🔄 How It Works
 
 ```
@@ -126,6 +161,8 @@ uv.lock ────────┘      │        (parallel)     (optional)
 4. **Enrich** — optionally fetches [ft-checker.com](https://ft-checker.com) test results (cached 24h)
 5. **Report** — renders results as a styled table, JSON, or CSV with configurable exit codes
 
+> **About "Pure Python":** A package is flagged as 🐍 when *all* its published wheels use the `py3-none-any` tag — meaning no compiled C extensions. These packages typically work on free-threaded Python without changes. However, packages using `ctypes`, `cffi`, or calling native code at runtime may still have issues despite being "pure." Treat this as a strong signal, not a guarantee.
+
 ## 🏗 CI Integration
 
 **Report without blocking:**
@@ -160,16 +197,63 @@ uv.lock ────────┘      │        (parallel)     (optional)
     path: ft-report.json
 ```
 
+**Track progress across CI runs** by downloading a previous artifact and diffing:
+
+```yaml
+- name: Compare with baseline
+  run: |
+    pip install ftready
+    ftready --format json --output current.json --fail-on=never
+    ftready diff baseline.json current.json || true
+```
+
+## 🐍 Python API
+
+`ftready` exports a public API for programmatic use:
+
+```python
+from ftready import (
+    load_dependencies,
+    fetch_ftchecker_db,
+    build_results,
+    generate_report,
+    diff_reports,
+    format_diff,
+)
+from pathlib import Path
+
+# Load deps from pyproject.toml
+deps = load_dependencies(Path("pyproject.toml"))
+
+# Query data sources
+ft_db = fetch_ftchecker_db(Path(".ft_cache.json"))
+results = build_results(deps, ft_db)
+
+# Render as JSON
+report = generate_report(results, include_dev=False, output_format="json")
+
+# Compare two JSON reports
+summary = diff_reports("old_report.json", "new_report.json")
+print(format_diff(summary))
+```
+
 ## 📊 Data Sources
 
-| Source | Role | Coverage |
-| ------ | ---- | -------- |
-| PyPI JSON API | **Primary** — `cp313t`/`cp314t` wheel tag detection | Every package on PyPI |
-| PyPI version endpoint | **Primary** — pinned-version checking from lock files | Every package on PyPI |
-| [ft-checker.com](https://ft-checker.com) | **Enrichment** — actual test results | ~1000 top packages |
+| Source                                   | Role                                                  | Coverage              |
+| ---------------------------------------- | ----------------------------------------------------- | --------------------- |
+| PyPI JSON API                            | **Primary** — `cp313t`/`cp314t` wheel tag detection   | Every package on PyPI |
+| PyPI version endpoint                    | **Primary** — pinned-version checking from lock files | Every package on PyPI |
+| [ft-checker.com](https://ft-checker.com) | **Enrichment** — actual test results                  | ~1000 top packages    |
 
 When both sources report on a package, ft-checker.com takes priority — a package may ship free-threaded wheels but still fail tests.
 
+## ⚠️ Limitations
+
+- **Latest release only** (without lock files): When no lock file is used, ftready checks the *latest* PyPI release. If you're pinned to an older version, use `--all-deps` with a lock file for exact version checks.
+- **Wheel tags ≠ runtime compatibility**: A package shipping `cp313t` wheels doesn't guarantee it works correctly under free-threaded Python — it only means the maintainer built wheels for that target. ft-checker.com test results provide stronger evidence.
+- **ft-checker.com coverage**: The enrichment source covers ~1000 popular packages. Niche packages may only have PyPI wheel tag data.
+- **No transitive blocker tracing**: The tool reports status per-package but doesn't show dependency chains (e.g., "X depends on Y which depends on Z, and Z is the blocker").
+
 ## 📄 License
 
 [MIT](LICENSE)

src/ftready/__init__.py

@@ -2,17 +2,23 @@
 
 from ftready.checker import build_results
 from ftready.constants import Status
+from ftready.diff import DiffSummary, PackageDiff, diff_reports, format_diff, format_diff_json
 from ftready.models import PackageResult
 from ftready.parser import load_dependencies, load_lockfile_dependencies, load_requirements, load_uv_lock_dependencies
 from ftready.report import generate_report
 from ftready.scraper import check_pypi_batch, fetch_ftchecker_db
 
 __all__ = [
+    "DiffSummary",
+    "PackageDiff",
     "PackageResult",
     "Status",
     "build_results",
     "check_pypi_batch",
+    "diff_reports",
     "fetch_ftchecker_db",
+    "format_diff",
+    "format_diff_json",
     "generate_report",
     "load_dependencies",
     "load_lockfile_dependencies",

src/ftready/cli.py

@@ -11,6 +11,7 @@
 
 from ftready.checker import build_results
 from ftready.constants import _DEFAULT_CACHE_TTL_HOURS, STATUS_FAILED, STATUS_UNKNOWN
+from ftready.diff import diff_reports, format_diff, format_diff_json
 from ftready.parser import load_dependencies, load_lockfile_dependencies, load_requirements, load_uv_lock_dependencies
 from ftready.report import generate_report
 from ftready.scraper import fetch_ftchecker_db
@@ -102,7 +103,24 @@ def _resolve_deps(
     return deps, direct_names
 
 
-@click.command(help="Check project dependencies for free-threaded Python (3.13t/3.14t) compatibility.")
+class _DefaultGroup(click.RichGroup):
+    """A click Group that falls through to a default subcommand when none is given."""
+
+    default_cmd_name: str = "check"
+
+    def parse_args(self, ctx: click.Context, args: list[str]) -> list[str]:
+        """Prepend the default subcommand when args don't start with a known command."""
+        if not args or args[0] not in self.commands:
+            args = [self.default_cmd_name, *args]
+        return super().parse_args(ctx, args)
+
+
+@click.group(cls=_DefaultGroup, help="Check project dependencies for free-threaded Python (3.13t/3.14t) compatibility.")
+def main() -> None:
+    """Entry point group — delegates to ``check`` by default."""
+
+
+@main.command(help="Check project dependencies for free-threaded Python compatibility.")
 @click.option(
     "--pyproject",
     type=click.Path(path_type=Path),
@@ -166,7 +184,7 @@ def _resolve_deps(
     show_default=True,
     help="When to exit with code 1.",
 )
-def main(
+def check(
     pyproject: Path,
     output: Path | None,
     cache_file: Path,
@@ -183,7 +201,7 @@ def main(
     requirements: Path | None,
     fail_on: str,
 ) -> None:
-    """Entry point for the free-threaded compatibility checker."""
+    """Run the free-threaded compatibility check."""
     if verbose:
         logging.basicConfig(level=logging.INFO, format="%(message)s", stream=sys.stderr, force=True)
 
@@ -237,3 +255,32 @@ def main(
     )
     if any_direct_bad:
         sys.exit(1)
+
+
+@main.command(name="diff", help="Compare two JSON reports to track compatibility changes over time.")
+@click.argument("old_report", type=click.Path(exists=True, path_type=Path))
+@click.argument("new_report", type=click.Path(exists=True, path_type=Path))
+@click.option(
+    "--format",
+    "output_format",
+    type=click.Choice(["text", "json"]),
+    default="text",
+    show_default=True,
+    help="Output format for the diff.",
+)
+@click.option("--output", type=click.Path(path_type=Path), default=None, help="Write the diff to this file.")
+def diff_cmd(
+    old_report: Path,
+    new_report: Path,
+    output_format: str,
+    output: Path | None,
+) -> None:
+    """Compare two ftready JSON reports and show what changed."""
+    summary = diff_reports(str(old_report), str(new_report))
+    result = format_diff_json(summary) if output_format == "json" else format_diff(summary)
+
+    if output:
+        output.write_text(result, encoding="utf-8")
+        click.echo(f"Diff written to {output}", err=True)
+    else:
+        click.echo(result)