compat-check 0.1.0__tar.gz

compat_check-0.1.0/LICENSE

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

compat_check-0.1.0/PKG-INFO

@@ -0,0 +1,144 @@
+Metadata-Version: 2.4
+Name: compat-check
+Version: 0.1.0
+Summary: Check whether a GitHub repo or PyPI package would install cleanly in this environment, without actually installing it.
+Author: jahyunlee00299
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/jahyunlee00299/compat-check
+Project-URL: Repository, https://github.com/jahyunlee00299/compat-check
+Project-URL: Issues, https://github.com/jahyunlee00299/compat-check/issues
+Keywords: dependencies,packaging,pip,uv,dry-run,resolver
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Build Tools
+Classifier: Topic :: System :: Software Distribution
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# compat-check
+
+[![test](https://github.com/jahyunlee00299/compat-check/actions/workflows/test.yml/badge.svg)](https://github.com/jahyunlee00299/compat-check/actions/workflows/test.yml)
+
+Check whether a GitHub repo or PyPI package would install cleanly **in this
+environment** — before you actually install it.
+
+```
+$ compat-check https://github.com/pallets/flask
+compat-check: https://github.com/pallets/flask
+backend: uv
+requirements checked: blinker>=1.9.0, click>=8.1.3, itsdangerous>=2.2.0, jinja2>=3.1.2, markupsafe>=2.1.1, werkzeug>=3.1.0
+
+OK — 6 package(s) would install cleanly:
+  + blinker==1.9.0
+  + click==8.5.0
+  ...
+```
+
+```
+$ compat-check some-package-with-a-real-conflict
+PROBLEMS FOUND — 1 package(s) cannot be resolved:
+
+  [numpy]
+      × No solution found when resolving dependencies:
+      ╰─▶ Because you require numpy>=2.0 and numpy<1.20, we can conclude that your
+          requirements are unsatisfiable.
+```
+
+## Why this instead of `uv`/`pip` themselves
+
+`uv` and `pip` already resolve dependencies — that's not the gap. Two things
+are:
+
+- **You still have to actually run the install (or a dry-run) yourself**,
+  reading whatever error comes back. `compat-check` does that in a throwaway
+  venv and hands you a plain-language pass/fail, without touching your real
+  environment.
+- **Both resolvers are fail-fast**: a single dry-run call reports only the
+  *first* unsatisfiable requirement. If two unrelated packages in the same
+  `requirements.txt` are both broken, one hides behind the other.
+  `compat-check` drops each failure and retries until every one surfaces.
+
+It does **not** try to out-resolve `uv`/`pip` — it wraps them (preferring
+`uv` when available, falling back to the standard-library `venv` + `pip`
+when it isn't) and reports what actually happened, not a static prediction
+from metadata.
+
+## What it checks
+
+- Whether every requirement resolves at all (missing versions, yanked
+  releases, platform/ABI mismatches — reported with the resolver's own
+  explanation)
+- Whether requirements in the same source conflict with each other
+
+## What it deliberately does not check (yet)
+
+- BLAS/LAPACK backend compatibility — this is a post-install diagnostic
+  (`numpy.show_config()`), not something knowable before installing
+- GPU/CUDA driver compatibility beyond what the resolver itself reports —
+  PyTorch-style packages that ship on a separate index aren't covered
+- `setup.py`-only packages with no `pyproject.toml`/`requirements.txt`/
+  `setup.cfg` (would require unsafe code execution to parse reliably)
+
+## Install
+
+Not yet published to PyPI — install directly from the repo:
+
+```
+uv tool install git+https://github.com/jahyunlee00299/compat-check
+```
+
+(or `pipx install git+https://github.com/jahyunlee00299/compat-check`, or clone and
+`pip install .` into a venv)
+
+## Usage
+
+```
+compat-check <github-url-or-pypi-package-name> [--python 3.11] [--no-cache] [--tree]
+```
+
+Exit codes: `0` clean, `1` conflicts found, `2` source could not be resolved
+at all (bad URL, nonexistent package).
+
+`--tree` shows the full dependency tree (requires `uv` — no pip-backend
+equivalent exists):
+
+```
+$ compat-check https://github.com/pallets/flask --tree
+...
+https://github.com/pallets/flask
+├── blinker v1.9.0
+├── click v8.5.0
+├── itsdangerous v2.2.0
+├── jinja2 v3.1.6
+│   └── markupsafe v3.0.3
+├── markupsafe v3.0.3
+└── werkzeug v3.1.8
+    └── markupsafe v3.0.3
+```
+
+Results are cached locally (`~/.cache/compat_check/`, 7-day TTL) since a
+dry-run against the same environment and requirements won't change
+minute-to-minute. Use `--no-cache` to force a fresh probe.
+
+## How it works
+
+1. Fetch the requirement list — from `pyproject.toml`, `requirements.txt`,
+   or `setup.cfg` on the GitHub repo, or from PyPI's JSON API for a bare
+   package name.
+2. Create a disposable virtual environment.
+3. Run `pip install --dry-run` (or `uv pip install --dry-run`) against it —
+   this resolves and would-download, but never actually installs anything
+   or runs arbitrary setup code from the target package.
+4. Report the result, retrying with failing packages dropped one at a time
+   so every conflict in a multi-package source gets surfaced, not just the
+   first one the resolver hits.
+
+## License
+
+MIT

compat_check-0.1.0/README.md

@@ -0,0 +1,121 @@
+# compat-check
+
+[![test](https://github.com/jahyunlee00299/compat-check/actions/workflows/test.yml/badge.svg)](https://github.com/jahyunlee00299/compat-check/actions/workflows/test.yml)
+
+Check whether a GitHub repo or PyPI package would install cleanly **in this
+environment** — before you actually install it.
+
+```
+$ compat-check https://github.com/pallets/flask
+compat-check: https://github.com/pallets/flask
+backend: uv
+requirements checked: blinker>=1.9.0, click>=8.1.3, itsdangerous>=2.2.0, jinja2>=3.1.2, markupsafe>=2.1.1, werkzeug>=3.1.0
+
+OK — 6 package(s) would install cleanly:
+  + blinker==1.9.0
+  + click==8.5.0
+  ...
+```
+
+```
+$ compat-check some-package-with-a-real-conflict
+PROBLEMS FOUND — 1 package(s) cannot be resolved:
+
+  [numpy]
+      × No solution found when resolving dependencies:
+      ╰─▶ Because you require numpy>=2.0 and numpy<1.20, we can conclude that your
+          requirements are unsatisfiable.
+```
+
+## Why this instead of `uv`/`pip` themselves
+
+`uv` and `pip` already resolve dependencies — that's not the gap. Two things
+are:
+
+- **You still have to actually run the install (or a dry-run) yourself**,
+  reading whatever error comes back. `compat-check` does that in a throwaway
+  venv and hands you a plain-language pass/fail, without touching your real
+  environment.
+- **Both resolvers are fail-fast**: a single dry-run call reports only the
+  *first* unsatisfiable requirement. If two unrelated packages in the same
+  `requirements.txt` are both broken, one hides behind the other.
+  `compat-check` drops each failure and retries until every one surfaces.
+
+It does **not** try to out-resolve `uv`/`pip` — it wraps them (preferring
+`uv` when available, falling back to the standard-library `venv` + `pip`
+when it isn't) and reports what actually happened, not a static prediction
+from metadata.
+
+## What it checks
+
+- Whether every requirement resolves at all (missing versions, yanked
+  releases, platform/ABI mismatches — reported with the resolver's own
+  explanation)
+- Whether requirements in the same source conflict with each other
+
+## What it deliberately does not check (yet)
+
+- BLAS/LAPACK backend compatibility — this is a post-install diagnostic
+  (`numpy.show_config()`), not something knowable before installing
+- GPU/CUDA driver compatibility beyond what the resolver itself reports —
+  PyTorch-style packages that ship on a separate index aren't covered
+- `setup.py`-only packages with no `pyproject.toml`/`requirements.txt`/
+  `setup.cfg` (would require unsafe code execution to parse reliably)
+
+## Install
+
+Not yet published to PyPI — install directly from the repo:
+
+```
+uv tool install git+https://github.com/jahyunlee00299/compat-check
+```
+
+(or `pipx install git+https://github.com/jahyunlee00299/compat-check`, or clone and
+`pip install .` into a venv)
+
+## Usage
+
+```
+compat-check <github-url-or-pypi-package-name> [--python 3.11] [--no-cache] [--tree]
+```
+
+Exit codes: `0` clean, `1` conflicts found, `2` source could not be resolved
+at all (bad URL, nonexistent package).
+
+`--tree` shows the full dependency tree (requires `uv` — no pip-backend
+equivalent exists):
+
+```
+$ compat-check https://github.com/pallets/flask --tree
+...
+https://github.com/pallets/flask
+├── blinker v1.9.0
+├── click v8.5.0
+├── itsdangerous v2.2.0
+├── jinja2 v3.1.6
+│   └── markupsafe v3.0.3
+├── markupsafe v3.0.3
+└── werkzeug v3.1.8
+    └── markupsafe v3.0.3
+```
+
+Results are cached locally (`~/.cache/compat_check/`, 7-day TTL) since a
+dry-run against the same environment and requirements won't change
+minute-to-minute. Use `--no-cache` to force a fresh probe.
+
+## How it works
+
+1. Fetch the requirement list — from `pyproject.toml`, `requirements.txt`,
+   or `setup.cfg` on the GitHub repo, or from PyPI's JSON API for a bare
+   package name.
+2. Create a disposable virtual environment.
+3. Run `pip install --dry-run` (or `uv pip install --dry-run`) against it —
+   this resolves and would-download, but never actually installs anything
+   or runs arbitrary setup code from the target package.
+4. Report the result, retrying with failing packages dropped one at a time
+   so every conflict in a multi-package source gets surfaced, not just the
+   first one the resolver hits.
+
+## License
+
+MIT

compat_check-0.1.0/compat_check/cache.py

@@ -0,0 +1,100 @@
+"""SQLite-backed cache in front of runner.probe_all().
+
+runner.py stays cache-unaware by design (separation of concerns) — this
+module wraps it. Keyed on the exact inputs that determine a dry-run's
+outcome: requirements, python_version, and backend name (uv vs pip give
+different resolvers and can disagree).
+"""
+from __future__ import annotations
+
+import hashlib
+import json
+import sqlite3
+import time
+from pathlib import Path
+
+from compat_check.runner import _select_backend, probe_all
+
+DEFAULT_TTL_SECONDS = 7 * 24 * 60 * 60  # 7 days — see docs/feature-connectivity-ledger.md
+DEFAULT_DB_PATH = Path.home() / ".cache" / "compat_check" / "history.db"
+
+_SCHEMA = """
+CREATE TABLE IF NOT EXISTS probe_cache (
+    cache_key TEXT PRIMARY KEY,
+    ok INTEGER NOT NULL,
+    failures_json TEXT NOT NULL,
+    resolved_json TEXT NOT NULL,
+    backend TEXT NOT NULL,
+    checked_at REAL NOT NULL
+)
+"""
+
+
+def _connect(db_path: Path) -> sqlite3.Connection:
+    db_path.parent.mkdir(parents=True, exist_ok=True)
+    conn = sqlite3.connect(str(db_path))
+    conn.execute(_SCHEMA)
+    return conn
+
+
+def make_cache_key(requirements: list[str], python_version: str, backend: str) -> str:
+    normalized = json.dumps(
+        {"requirements": sorted(requirements), "python_version": python_version, "backend": backend},
+        sort_keys=True,
+    )
+    return hashlib.sha256(normalized.encode("utf-8")).hexdigest()
+
+
+def cached_probe_all(
+    requirements: list[str],
+    python_version: str = "3.11",
+    max_rounds: int = 20,
+    db_path: Path | None = None,
+    ttl_seconds: int = DEFAULT_TTL_SECONDS,
+) -> dict:
+    """probe_all(), but returns a cached result when one exists and hasn't expired.
+
+    Result dict gains one extra key not present in raw probe_all() output:
+    "cache_hit": bool.
+    """
+    db_path = db_path or DEFAULT_DB_PATH
+    backend_name = _select_backend().name
+    cache_key = make_cache_key(requirements, python_version, backend_name)
+
+    conn = _connect(db_path)
+    try:
+        row = conn.execute(
+            "SELECT ok, failures_json, resolved_json, backend, checked_at "
+            "FROM probe_cache WHERE cache_key = ?",
+            (cache_key,),
+        ).fetchone()
+
+        if row is not None:
+            ok, failures_json, resolved_json, backend, checked_at = row
+            if time.time() - checked_at < ttl_seconds:
+                return {
+                    "ok": bool(ok),
+                    "backend": backend,
+                    "failures": json.loads(failures_json),
+                    "resolved": json.loads(resolved_json),
+                    "cache_hit": True,
+                }
+
+        result = probe_all(requirements, python_version=python_version, max_rounds=max_rounds)
+        conn.execute(
+            "INSERT OR REPLACE INTO probe_cache "
+            "(cache_key, ok, failures_json, resolved_json, backend, checked_at) "
+            "VALUES (?, ?, ?, ?, ?, ?)",
+            (
+                cache_key,
+                int(result["ok"]),
+                json.dumps(result["failures"]),
+                json.dumps(result["resolved"]),
+                result["backend"],
+                time.time(),
+            ),
+        )
+        conn.commit()
+        return {**result, "cache_hit": False}
+    finally:
+        conn.close()

compat_check-0.1.0/compat_check/cli.py

@@ -0,0 +1,80 @@
+"""compat-check CLI entry point — wires fetcher -> cache -> runner into a
+human-readable report.
+
+    compat-check <github-url-or-pypi-name> [--python 3.11] [--no-cache]
+"""
+from __future__ import annotations
+
+import argparse
+import sys
+
+from compat_check.cache import cached_probe_all
+from compat_check.fetcher import FetchError, fetch_requirements
+from compat_check.render import render_tree
+from compat_check.runner import probe_all
+from compat_check.tree import build_tree
+
+
+def _print_report(source: str, requirements: list[str], result: dict) -> None:
+    cache_note = " (cached)" if result.get("cache_hit") else ""
+    print(f"compat-check: {source}{cache_note}")
+    print(f"backend: {result['backend']}")
+    print(f"requirements checked: {', '.join(requirements)}")
+    print()
+
+    if result["ok"]:
+        print(f"OK — {len(result['resolved'])} package(s) would install cleanly:")
+        for pkg in result["resolved"]:
+            print(f"  + {pkg}")
+        return
+
+    print(f"PROBLEMS FOUND — {len(result['failures'])} package(s) cannot be resolved:")
+    for f in result["failures"]:
+        print(f"\n  [{f['package']}]")
+        # Indent the raw resolver output so it reads as evidence, not noise.
+        for line in f["stderr"].strip().splitlines():
+            print(f"    {line}")
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(
+        prog="compat-check",
+        description="Check whether a GitHub repo or PyPI package would install "
+                    "cleanly in this environment, without actually installing it.",
+    )
+    parser.add_argument("source", help="GitHub repo URL or PyPI package name")
+    parser.add_argument("--python", default="3.11", dest="python_version",
+                         help="target Python version (default: 3.11; ignored by the pip fallback)")
+    parser.add_argument("--no-cache", action="store_true",
+                         help="skip the local failure-history cache, always probe fresh")
+    parser.add_argument("--tree", action="store_true",
+                         help="show the full dependency tree (requires uv; no pip fallback)")
+    args = parser.parse_args(argv)
+
+    try:
+        requirements = fetch_requirements(args.source)
+    except FetchError as e:
+        print(f"compat-check: could not resolve requirements for '{args.source}': {e}", file=sys.stderr)
+        return 2
+
+    if args.no_cache:
+        result = probe_all(requirements, python_version=args.python_version)
+        result = {**result, "cache_hit": False}
+    else:
+        result = cached_probe_all(requirements, python_version=args.python_version)
+
+    _print_report(args.source, requirements, result)
+
+    if args.tree:
+        print()
+        tree_result = build_tree(requirements, python_version=args.python_version)
+        if tree_result["ok"]:
+            print(render_tree(tree_result["roots"], label=args.source))
+        else:
+            print(f"(tree unavailable: {tree_result['stderr'].strip()})", file=sys.stderr)
+
+    return 0 if result["ok"] else 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

compat_check-0.1.0/compat_check/fetcher.py

@@ -0,0 +1,152 @@
+"""Resolve a GitHub repo URL or a PyPI package name into requirement specs.
+
+GitHub path tries pyproject.toml, then requirements.txt, then setup.cfg, on
+raw.githubusercontent.com — unauthenticated, no rate limit (confirmed in
+prior research). setup.py is out of scope for this unit (would need AST
+parsing to be safe; deferred).
+
+PyPI path reads info.requires_dist from the package's JSON API.
+
+fetch_requirements() distinguishes "found nothing" from "found an empty
+list" by raising FetchError instead of ever returning []. Callers must not
+confuse an empty return with runner.probe_all([]), which is a "no
+requirements, trivially ok" result — this module never emits an empty list.
+"""
+from __future__ import annotations
+
+import configparser
+import json
+import re
+import tomllib
+import urllib.error
+import urllib.request
+from dataclasses import dataclass
+
+
+class FetchError(Exception):
+    """Raised when a source could not be resolved to any requirements."""
+
+
+@dataclass
+class GitHubRef:
+    owner: str
+    repo: str
+    branch: str | None  # None = try main, then master
+
+
+_GITHUB_URL_RE = re.compile(
+    r"^https?://github\.com/(?P<owner>[^/]+)/(?P<repo>[^/]+?)(?:\.git)?"
+    r"(?:/(?:tree|blob)/(?P<branch>[^/]+))?/?$"
+)
+
+_CANDIDATE_FILES = ("pyproject.toml", "requirements.txt", "setup.cfg")
+_BRANCH_FALLBACKS = ("main", "master")
+_USER_AGENT = "compat-check/0.1 (+https://github.com/)"
+_REQUEST_TIMEOUT = 15
+
+
+def _http_get(url: str) -> str | None:
+    req = urllib.request.Request(url, headers={"User-Agent": _USER_AGENT})
+    try:
+        with urllib.request.urlopen(req, timeout=_REQUEST_TIMEOUT) as resp:
+            return resp.read().decode("utf-8", errors="replace")
+    except urllib.error.HTTPError as e:
+        if e.code == 404:
+            return None
+        raise FetchError(f"HTTP {e.code} fetching {url}") from e
+    except urllib.error.URLError as e:
+        raise FetchError(f"network error fetching {url}: {e.reason}") from e
+
+
+def parse_github_url(source: str) -> GitHubRef | None:
+    m = _GITHUB_URL_RE.match(source.strip())
+    if not m:
+        return None
+    return GitHubRef(owner=m.group("owner"), repo=m.group("repo"), branch=m.group("branch"))
+
+
+def _parse_pyproject_toml(text: str) -> list[str]:
+    data = tomllib.loads(text)
+    project = data.get("project", {})
+    deps = list(project.get("dependencies", []))
+    # optional-dependencies groups are extras, not base requirements — skipped intentionally.
+    return deps
+
+
+def _parse_requirements_txt(text: str) -> list[str]:
+    reqs = []
+    for line in text.splitlines():
+        line = line.strip()
+        if not line or line.startswith("#"):
+            continue
+        if line.startswith(("-r ", "-e ", "--")):
+            continue  # nested includes / editable installs / pip flags out of scope
+        reqs.append(line)
+    return reqs
+
+
+def _parse_setup_cfg(text: str) -> list[str]:
+    parser = configparser.ConfigParser()
+    parser.read_string(text)
+    if not parser.has_option("options", "install_requires"):
+        return []
+    raw = parser.get("options", "install_requires")
+    return [line.strip() for line in raw.splitlines() if line.strip()]
+
+
+_PARSERS = {
+    "pyproject.toml": _parse_pyproject_toml,
+    "requirements.txt": _parse_requirements_txt,
+    "setup.cfg": _parse_setup_cfg,
+}
+
+
+def _fetch_from_github(ref: GitHubRef) -> list[str]:
+    branches = [ref.branch] if ref.branch else list(_BRANCH_FALLBACKS)
+    tried = []
+    for branch in branches:
+        for filename in _CANDIDATE_FILES:
+            url = f"https://raw.githubusercontent.com/{ref.owner}/{ref.repo}/{branch}/{filename}"
+            tried.append(url)
+            text = _http_get(url)
+            if text is None:
+                continue
+            try:
+                reqs = _PARSERS[filename](text)
+            except Exception as e:
+                raise FetchError(f"failed to parse {url}: {e}") from e
+            if reqs:
+                return reqs
+            # file exists but declares no dependencies — keep searching other files/branches
+    raise FetchError(
+        f"no pyproject.toml/requirements.txt/setup.cfg with dependencies found for "
+        f"{ref.owner}/{ref.repo} (tried: {', '.join(tried)})"
+    )
+
+
+def _fetch_from_pypi(package_name: str) -> list[str]:
+    url = f"https://pypi.org/pypi/{package_name}/json"
+    text = _http_get(url)
+    if text is None:
+        raise FetchError(f"PyPI package not found: {package_name}")
+    data = json.loads(text)
+    requires_dist = data.get("info", {}).get("requires_dist") or []
+    # drop extras-only markers (e.g. 'foo; extra == "dev"') — base install only.
+    base = [r for r in requires_dist if "extra ==" not in r]
+    if not base:
+        raise FetchError(f"PyPI package {package_name} declares no base requires_dist")
+    return base
+
+
+def fetch_requirements(source: str) -> list[str]:
+    """Resolve `source` (GitHub URL or PyPI package name) to requirement specs.
+
+    Raises FetchError if nothing could be resolved. Never returns [] —
+    that return value is reserved for callers of runner.probe_all() to mean
+    "no requirements, trivially ok", which this function must not be
+    confused with.
+    """
+    ref = parse_github_url(source)
+    if ref is not None:
+        return _fetch_from_github(ref)
+    return _fetch_from_pypi(source)

compat_check-0.1.0/compat_check/render.py

@@ -0,0 +1,62 @@
+"""Render a dependency tree (see tree.py) as a colored ASCII tree for the
+terminal. No external dependency — plain ANSI escape codes, disabled
+automatically when stdout isn't a TTY (e.g. piped to a file) so redirected
+output stays clean text.
+"""
+from __future__ import annotations
+
+import sys
+
+_GREEN = "\033[32m"
+_CYAN = "\033[36m"
+_DIM = "\033[2m"
+_RESET = "\033[0m"
+
+
+def _colors_enabled() -> bool:
+    return sys.stdout.isatty()
+
+
+def _colorize(text: str, code: str) -> str:
+    if not _colors_enabled():
+        return text
+    return f"{code}{text}{_RESET}"
+
+
+def render_tree(roots: list[dict], label: str | None = None) -> str:
+    """roots: list of {"name", "version", "children"} dicts, as returned by
+    tree.build_tree()["roots"]. Returns a multi-line string ready to print.
+
+    When `label` is given, roots are nested one level under a synthetic
+    label node instead of being printed as separate top-level trees — used
+    to show "what this source pulls in" as a single tree rather than a flat
+    list of its direct dependencies.
+    """
+    lines: list[str] = []
+    if label is not None:
+        lines.append(_colorize(label, _CYAN))
+        for i, root in enumerate(roots):
+            _render_node(root, prefix="", is_last=(i == len(roots) - 1), lines=lines, is_root=False)
+        return "\n".join(lines)
+
+    for i, root in enumerate(roots):
+        _render_node(root, prefix="", is_last=(i == len(roots) - 1), lines=lines, is_root=True)
+    return "\n".join(lines)
+
+
+def _render_node(node: dict, prefix: str, is_last: bool, lines: list[str], is_root: bool) -> None:
+    name = _colorize(node["name"], _GREEN)
+    version = _colorize(f"v{node['version']}", _DIM)
+
+    if is_root:
+        lines.append(f"{name} {version}")
+        child_prefix = ""
+    else:
+        connector = "└── " if is_last else "├── "
+        lines.append(f"{prefix}{connector}{name} {version}")
+        child_prefix = prefix + ("    " if is_last else "│   ")
+
+    children = node.get("children", [])
+    for i, child in enumerate(children):
+        _render_node(child, child_prefix, is_last=(i == len(children) - 1),
+                     lines=lines, is_root=False)