bumpmap 0.1.0__tar.gz

bumpmap-0.1.0/PKG-INFO

@@ -0,0 +1,43 @@
+Metadata-Version: 2.4
+Name: bumpmap
+Version: 0.1.0
+Summary: Dependency upgrade plans with risk classes: pins in, majors flagged, changelogs attached — stdlib only
+Author: juzorei
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/juzorei/bumpmap
+Keywords: dependencies,upgrade,pypi,renovate,agent-skills
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Software Development :: Build Tools
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+
+# bumpmap
+
+Dependency upgrade plans with risk classes, changelog links — and the honest positioning: Renovate and Dependabot open the PR; this is about landing it.
+
+```text
+$ bumpmap plan requirements.txt
+== requirements.txt
+  [MAJOR   ] pydantic     1.10.13  -> 2.7.4
+            major jump 1.10.13 -> 2.7.4: read the changelog's breaking changes and plan code changes before bumping
+  [MINOR   ] requests     2.31.0   -> 2.32.3
+            changelog: https://requests.readthedocs.io/en/latest/community/updates/
+
+2 dependencies: major 1, minor 1
+```
+
+Risk classes: `latest`, `minor` (same major — usually safe), `major` (the real work), `unpinned` (pin first). Exit 1 on any major — CI-gateable. `--from-cache pypi.json` for offline runs; `--json` for agents. Changelog links are pulled from each package's PyPI metadata.
+
+## Commands
+
+```text
+bumpmap plan <pyproject.toml | requirements.txt> [--json] [--from-cache cache.json]
+```
+
+Parses `pyproject.toml` (project.dependencies + optional-dependencies) and `requirements*.txt` (comments, `-e`, git/url lines skipped). Python 3.11+, stdlib only.
+
+Install: `pip install bumpmap` — or from this repo:
+`pip install "git+https://github.com/juzorei/bumpmap#subdirectory=tools/bumpmap"`
+
+The companion agent skill lives in [skills/dependency-upgrade](../skills/dependency-upgrade): the loop that lands a breaking major — changelog → blast radius → bump → tests → fix → commit, one dependency per commit. Skills: `npx skills add juzorei/bumpmap`.

bumpmap-0.1.0/README.md

@@ -0,0 +1,29 @@
+# bumpmap
+
+Dependency upgrade plans with risk classes, changelog links — and the honest positioning: Renovate and Dependabot open the PR; this is about landing it.
+
+```text
+$ bumpmap plan requirements.txt
+== requirements.txt
+  [MAJOR   ] pydantic     1.10.13  -> 2.7.4
+            major jump 1.10.13 -> 2.7.4: read the changelog's breaking changes and plan code changes before bumping
+  [MINOR   ] requests     2.31.0   -> 2.32.3
+            changelog: https://requests.readthedocs.io/en/latest/community/updates/
+
+2 dependencies: major 1, minor 1
+```
+
+Risk classes: `latest`, `minor` (same major — usually safe), `major` (the real work), `unpinned` (pin first). Exit 1 on any major — CI-gateable. `--from-cache pypi.json` for offline runs; `--json` for agents. Changelog links are pulled from each package's PyPI metadata.
+
+## Commands
+
+```text
+bumpmap plan <pyproject.toml | requirements.txt> [--json] [--from-cache cache.json]
+```
+
+Parses `pyproject.toml` (project.dependencies + optional-dependencies) and `requirements*.txt` (comments, `-e`, git/url lines skipped). Python 3.11+, stdlib only.
+
+Install: `pip install bumpmap` — or from this repo:
+`pip install "git+https://github.com/juzorei/bumpmap#subdirectory=tools/bumpmap"`
+
+The companion agent skill lives in [skills/dependency-upgrade](../skills/dependency-upgrade): the loop that lands a breaking major — changelog → blast radius → bump → tests → fix → commit, one dependency per commit. Skills: `npx skills add juzorei/bumpmap`.

bumpmap-0.1.0/pyproject.toml

@@ -0,0 +1,27 @@
+[build-system]
+requires = ["setuptools>=69"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "bumpmap"
+version = "0.1.0"
+description = "Dependency upgrade plans with risk classes: pins in, majors flagged, changelogs attached — stdlib only"
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+authors = [{ name = "juzorei" }]
+keywords = ["dependencies", "upgrade", "pypi", "renovate", "agent-skills"]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Operating System :: OS Independent",
+    "Topic :: Software Development :: Build Tools",
+]
+
+[project.urls]
+Homepage = "https://github.com/juzorei/bumpmap"
+
+[project.scripts]
+bumpmap = "bumpmap.cli:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]

bumpmap-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

bumpmap-0.1.0/src/bumpmap/__init__.py

@@ -0,0 +1,3 @@
+"""Dependency upgrade plans with risk classes: pyproject/requirements in, plan out."""
+
+__version__ = "0.1.0"

bumpmap-0.1.0/src/bumpmap/__main__.py

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

bumpmap-0.1.0/src/bumpmap/cli.py

@@ -0,0 +1,92 @@
+"""bumpmap CLI: dependency upgrade plan with risk classes and changelog links."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+from . import __version__
+from .deps import parse_dependencies
+from .pypi import enrich
+
+RISK_ORDER = {"major": 0, "unpinned": 1, "unknown": 2, "minor": 3, "latest": 4, "ok": 5}
+RISK_EXIT = {"major": 1}
+
+
+def cmd_plan(args) -> int:
+    deps = parse_dependencies(args.file)
+    if not deps:
+        print(f"bumpmap: no dependency pins found in {args.file}", file=sys.stderr)
+        return 2
+    from .deps import PlanEntry
+    from .pypi import fetch_pypi
+
+    fetcher = fetch_pypi
+    if args.from_cache:
+        cache = json.loads(Path(args.from_cache).read_text(encoding="utf-8"))
+        fetcher = lambda name: cache.get(name)  # noqa: E731
+    entries = [PlanEntry(dep=d) for d in deps]
+    enrich(entries, fetcher=fetcher, delay=args.delay)
+    order = RISK_ORDER
+    entries.sort(key=lambda e: (order.get(e.risk, 9), e.dep.name.lower()))
+    majors = sum(1 for e in entries if e.risk == "major")
+    if args.json:
+        print(json.dumps([{
+            "name": e.dep.name, "current": e.dep.version or None, "latest": e.latest,
+            "risk": e.risk, "note": e.note, "changelog": e.changelog,
+            "source": e.dep.source,
+        } for e in entries], indent=2))
+    else:
+        current_file = None
+        for e in entries:
+            if e.dep.source != current_file:
+                current_file = e.dep.source
+                print(f"== {current_file}")
+            latest = e.latest or "?"
+            line = f"  [{e.risk.upper():8}] {e.dep.name:<24} {e.dep.version or '(unpinned)':<12} -> {latest}"
+            print(line)
+            if e.changelog:
+                print(f"            changelog: {e.changelog}")
+            if e.note:
+                print(f"            {e.note}")
+        print(f"\n{len(entries)} dependencies: "
+              + ", ".join(f"{r} {n}" for r, n in
+                          sorted(((r, sum(1 for e in entries if e.risk == r)) for r in
+                                  {e.risk for e in entries}), key=lambda kv: order.get(kv[0], 9))))
+        if majors:
+            print("landing majors: read the changelog, bump one at a time, run the tests, "
+                  "commit; see the dependency-upgrade skill")
+    return 1 if majors else 0
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="bumpmap", description=__doc__)
+    parser.add_argument("--version", action="version", version=f"bumpmap {__version__}")
+    p = parser.add_subparsers(dest="command", required=True)
+    plan = p.add_parser("plan", help="risk-classified upgrade plan for a dependency file")
+    plan.add_argument("file", help="pyproject.toml or requirements*.txt")
+    plan.add_argument("--json", action="store_true")
+    plan.add_argument("--from-cache", help="JSON file {name: {info: {version, project_urls}}}"
+                    " instead of live PyPI lookups (offline mode)")
+    plan.add_argument("--delay", type=float, default=0.0,
+                      help="pause between PyPI lookups (be polite on big files)")
+    plan.set_defaults(func=cmd_plan)
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = build_parser().parse_args(argv)
+    try:
+        return args.func(args)
+    except OSError as exc:
+        print(f"bumpmap: error: {exc}", file=sys.stderr)
+        return 2
+    except ValueError as exc:
+        print(f"bumpmap: error: {exc}", file=sys.stderr)
+        return 2
+
+
+if __name__ == "__main__":
+    sys.exit(main())

bumpmap-0.1.0/src/bumpmap/deps.py

@@ -0,0 +1,113 @@
+"""Parse dependency pins from pyproject.toml / requirements files, classify upgrade risk."""
+
+from __future__ import annotations
+
+import re
+import tomllib
+from dataclasses import dataclass, field
+from pathlib import Path
+
+OP_VERSION = re.compile(r"^\s*([A-Za-z0-9_.-]+)(?:\[([^\]]*)\])?\s*([=<>!~^]+)\s*([0-9][0-9A-Za-z.*-]*)")
+
+
+@dataclass
+class Dependency:
+    name: str
+    source: str                 # file it came from
+    operator: str               # ==, >=, ~=, ...
+    version: str                # pinned base version
+    extras: str = ""
+    specifier: str = ""         # the raw spec, when multi-clause
+
+    @property
+    def major(self) -> int | None:
+        m = re.match(r"(\d+)", self.version)
+        return int(m.group(1)) if m else None
+
+
+@dataclass
+class PlanEntry:
+    dep: Dependency
+    latest: str | None = None
+    risk: str = "unknown"       # ok | minor | major | unpinned | latest | unknown
+    note: str = ""
+    changelog: str | None = None
+
+    @property
+    def kind(self) -> str:
+        return "major" if self.risk == "major" else self.risk
+
+
+def parse_dependencies(path: str | Path) -> list[Dependency]:
+    p = Path(path)
+    deps: list[Dependency] = []
+    if p.suffix == ".toml" or p.name == "pyproject.toml":
+        data = tomllib.loads(p.read_text(encoding="utf-8", errors="replace"))
+        project = data.get("project", {})
+        raw = list(project.get("dependencies", []))
+        for group in (project.get("optional-dependencies") or {}).values():
+            raw += list(group)
+        for tool_dep in (data.get("tool", {}).get("uv", {}) or {}).get("sources", {}):
+            pass
+        source = p.name
+    else:
+        raw = []
+        source = p.name
+        for line in p.read_text(encoding="utf-8", errors="replace").splitlines():
+            line = line.strip()
+            if line and not line.startswith(("#", "-", "git+", "http")):
+                raw.append(line)
+    for spec in raw:
+        spec = spec.split("#", 1)[0].strip().rstrip(",")
+        if not spec or " @ " in spec or "://" in spec:
+            continue
+        m = OP_VERSION.match(spec)
+        if not m:
+            deps.append(Dependency(name=spec.strip(), source=source, operator="",
+                                   version="", specifier=spec))
+            continue
+        name, extras, op, version = m.groups()
+        version = version.rstrip(".*")
+        deps.append(Dependency(name=name, source=source, operator=op, version=version,
+                               extras=extras or "", specifier=spec))
+    return deps
+
+
+def _first_int(version: str) -> int | None:
+    m = re.match(r"(\d+)", version)
+    return int(m.group(1)) if m else None
+
+
+def classify(dep: Dependency, latest: str | None) -> PlanEntry:
+    entry = PlanEntry(dep=dep, latest=latest)
+    if not dep.version:
+        entry.risk = "unpinned"
+        entry.note = "not pinned — pin it first; an unpinned dep can't be planned safely"
+        return entry
+    if latest is None:
+        entry.note = "couldn't fetch the latest version"
+        return entry
+    if latest == dep.version:
+        entry.risk = "latest"
+        return entry
+    cur_major, new_major = dep.major, _first_int(latest)
+    if cur_major is None or new_major is None:
+        entry.risk = "unknown"
+        return entry
+    if new_major > cur_major:
+        entry.risk = "major"
+        entry.note = (f"major jump {dep.version} -> {latest}: read the changelog's breaking "
+                      f"changes and plan code changes before bumping")
+    elif latest != dep.version:
+        entry.risk = "minor"
+        entry.note = "minor/patch within the same major: usually safe, tests still decide"
+    return entry
+
+
+def changelog_url(dep: Dependency, project_urls: dict[str, str] | None) -> str | None:
+    urls = project_urls or {}
+    for key in ("Changelog", "Changes", "What's New", "Release Notes", "History"):
+        for k, v in urls.items():
+            if k.lower() == key.lower():
+                return v
+    return urls.get("Homepage") or urls.get("Source")

bumpmap-0.1.0/src/bumpmap/pypi.py

@@ -0,0 +1,40 @@
+"""PyPI JSON API client (injectable fetcher so tests run offline)."""
+
+from __future__ import annotations
+
+import json
+import urllib.error
+import urllib.request
+
+from .deps import PlanEntry, changelog_url, classify
+
+
+def fetch_pypi(name: str, timeout: int = 15) -> dict | None:
+    url = f"https://pypi.org/pypi/{name}/json"
+    try:
+        with urllib.request.urlopen(url, timeout=timeout) as response:
+            return json.load(response)
+    except (urllib.error.HTTPError, urllib.error.URLError, json.JSONDecodeError):
+        return None
+
+
+def enrich(entries: list[PlanEntry], fetcher=fetch_pypi, delay: float = 0.0,
+           progress=None) -> list[PlanEntry]:
+    """Fill latest version / changelog / risk for each entry via the PyPI API."""
+    import time
+
+    for i, entry in enumerate(entries):
+        if progress:
+            progress(i, entry)
+        data = fetcher(entry.dep.name)
+        if data is None:
+            entry.note = entry.note or "PyPI lookup failed"
+            continue
+        info = data.get("info", {})
+        entry.latest = info.get("version")
+        entry.changelog = changelog_url(entry.dep, info.get("project_urls") or {})
+        updated = classify(entry.dep, entry.latest)
+        entry.risk, entry.note = updated.risk, updated.note
+        if delay and i + 1 < len(entries):
+            time.sleep(delay)
+    return entries

bumpmap-0.1.0/src/bumpmap.egg-info/PKG-INFO

@@ -0,0 +1,43 @@
+Metadata-Version: 2.4
+Name: bumpmap
+Version: 0.1.0
+Summary: Dependency upgrade plans with risk classes: pins in, majors flagged, changelogs attached — stdlib only
+Author: juzorei
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/juzorei/bumpmap
+Keywords: dependencies,upgrade,pypi,renovate,agent-skills
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Software Development :: Build Tools
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+
+# bumpmap
+
+Dependency upgrade plans with risk classes, changelog links — and the honest positioning: Renovate and Dependabot open the PR; this is about landing it.
+
+```text
+$ bumpmap plan requirements.txt
+== requirements.txt
+  [MAJOR   ] pydantic     1.10.13  -> 2.7.4
+            major jump 1.10.13 -> 2.7.4: read the changelog's breaking changes and plan code changes before bumping
+  [MINOR   ] requests     2.31.0   -> 2.32.3
+            changelog: https://requests.readthedocs.io/en/latest/community/updates/
+
+2 dependencies: major 1, minor 1
+```
+
+Risk classes: `latest`, `minor` (same major — usually safe), `major` (the real work), `unpinned` (pin first). Exit 1 on any major — CI-gateable. `--from-cache pypi.json` for offline runs; `--json` for agents. Changelog links are pulled from each package's PyPI metadata.
+
+## Commands
+
+```text
+bumpmap plan <pyproject.toml | requirements.txt> [--json] [--from-cache cache.json]
+```
+
+Parses `pyproject.toml` (project.dependencies + optional-dependencies) and `requirements*.txt` (comments, `-e`, git/url lines skipped). Python 3.11+, stdlib only.
+
+Install: `pip install bumpmap` — or from this repo:
+`pip install "git+https://github.com/juzorei/bumpmap#subdirectory=tools/bumpmap"`
+
+The companion agent skill lives in [skills/dependency-upgrade](../skills/dependency-upgrade): the loop that lands a breaking major — changelog → blast radius → bump → tests → fix → commit, one dependency per commit. Skills: `npx skills add juzorei/bumpmap`.

bumpmap-0.1.0/src/bumpmap.egg-info/SOURCES.txt

@@ -0,0 +1,13 @@
+README.md
+pyproject.toml
+src/bumpmap/__init__.py
+src/bumpmap/__main__.py
+src/bumpmap/cli.py
+src/bumpmap/deps.py
+src/bumpmap/pypi.py
+src/bumpmap.egg-info/PKG-INFO
+src/bumpmap.egg-info/SOURCES.txt
+src/bumpmap.egg-info/dependency_links.txt
+src/bumpmap.egg-info/entry_points.txt
+src/bumpmap.egg-info/top_level.txt
+tests/test_bumpmap.py

bumpmap-0.1.0/src/bumpmap.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

bumpmap-0.1.0/src/bumpmap.egg-info/entry_points.txt

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

bumpmap-0.1.0/src/bumpmap.egg-info/top_level.txt

@@ -0,0 +1 @@
+bumpmap

bumpmap-0.1.0/tests/test_bumpmap.py

@@ -0,0 +1,119 @@
+import json
+
+import pytest
+
+from bumpmap.cli import main
+from bumpmap.deps import parse_dependencies
+from bumpmap.pypi import enrich
+
+
+@pytest.fixture
+def reqs(tmp_path):
+    p = tmp_path / "requirements.txt"
+    p.write_text(
+        "# app deps\n"
+        "requests==2.31.0\n"
+        "pydantic==1.10.13\n"
+        "flask>=2.0,<3\n"
+        "orjson==3.9.15  # fast json\n"
+        "some-unpinned\n"
+        "-e ./local\n"
+        "git+https://github.com/x/y.git\n"
+        "\n",
+        encoding="utf-8")
+    return str(p)
+
+
+@pytest.fixture
+def pyproject(tmp_path):
+    p = tmp_path / "pyproject.toml"
+    p.write_text(
+        '[project]\nname = "app"\nversion = "1.0"\n'
+        'dependencies = ["requests==2.31.0", "pydantic==1.10.13"]\n',
+        encoding="utf-8")
+    return str(p)
+
+
+def fake_fetcher_factory(latest_by_name, urls=None):
+    urls = urls or {}
+
+    def fetch(name):
+        if name == "some-unpinned":
+            return {"info": {"version": "9.9.9", "project_urls": {}}}
+        if name not in latest_by_name:
+            return None
+        return {"info": {"version": latest_by_name[name],
+                         "project_urls": urls.get(name, {})}}
+
+    return fetch
+
+
+def test_parse_requirements(reqs):
+    deps = parse_dependencies(reqs)
+    names = {d.name for d in deps}
+    assert names == {"requests", "pydantic", "flask", "orjson", "some-unpinned"}
+    requests = next(d for d in deps if d.name == "requests")
+    assert requests.operator == "==" and requests.version == "2.31.0"
+
+
+def test_parse_pyproject(pyproject):
+    deps = parse_dependencies(pyproject)
+    assert {d.name for d in deps} == {"requests", "pydantic"}
+
+
+def test_classify_risks(reqs):
+    deps = parse_dependencies(reqs)
+    entries = enrich([type("E", (), {"dep": d, "latest": None, "risk": "unknown", "note": "", "changelog": None})() for d in deps]
+                     if False else
+                     [__import__("bumpmap.deps", fromlist=["PlanEntry"]).PlanEntry(dep=d) for d in deps],
+                     fetcher=fake_fetcher_factory({
+                         "requests": "2.32.3",      # same major -> minor
+                         "pydantic": "2.7.4",       # 1 -> 2: major
+                         "flask": "3.0.3",          # spec >=2.0,<3 base "2.0" -> major-ish
+                         "orjson": "3.9.15",        # latest already
+                     }))
+    by = {e.dep.name: e for e in entries}
+    assert by["requests"].risk == "minor"
+    assert by["pydantic"].risk == "major"
+    assert "breaking" in by["pydantic"].note
+    assert by["orjson"].risk == "latest"
+    assert by["some-unpinned"].risk == "unpinned"
+
+
+def test_changelog_url_from_project_urls(reqs):
+    deps = [d for d in parse_dependencies(reqs) if d.name == "requests"]
+    entries = enrich(
+        [__import__("bumpmap.deps", fromlist=["PlanEntry"]).PlanEntry(dep=d) for d in deps],
+        fetcher=fake_fetcher_factory({"requests": "2.32.3"},
+                                     {"requests": {"Changelog": "https://requests.readthedocs.io/changelog"}}))
+    assert entries[0].changelog == "https://requests.readthedocs.io/changelog"
+
+
+def test_unknown_package_notes_lookup_failure(reqs):
+    deps = [d for d in parse_dependencies(reqs) if d.name == "requests"]
+    from bumpmap.deps import PlanEntry
+    entries = enrich([PlanEntry(dep=d) for d in deps], fetcher=lambda n: None)
+    assert entries[0].latest is None and "failed" in entries[0].note
+
+
+def test_cli_plan_exit_one_on_major(reqs, tmp_path, capsys):
+    cache = tmp_path / "pypi.json"
+    cache.write_text(json.dumps({
+        "requests": {"info": {"version": "2.32.3", "project_urls": {}}},
+        "pydantic": {"info": {"version": "2.7.4", "project_urls": {}}},
+        "flask": {"info": {"version": "3.0.3", "project_urls": {}}},
+        "orjson": {"info": {"version": "3.9.15", "project_urls": {}}},
+        "some-unpinned": {"info": {"version": "9.9.9", "project_urls": {}}},
+    }), encoding="utf-8")
+    assert main(["plan", reqs, "--from-cache", str(cache), "--json"]) == 1
+    rows = json.loads(capsys.readouterr().out)
+    by = {r["name"]: r for r in rows}
+    assert by["pydantic"]["risk"] == "major"
+    assert by["requests"]["risk"] == "minor"
+    assert by["some-unpinned"]["risk"] == "unpinned"
+
+
+def test_cli_no_deps(tmp_path):
+    p = tmp_path / "empty.txt"
+    p.write_text("# nothing here\n", encoding="utf-8")
+    assert main(["plan", str(p)]) == 2