chore(release): v2.6.0

.commitlintrc.json

@@ -11,6 +11,7 @@
       "version", "release", "changelog", "deps", "ci",
       "docs", "examples", "tests"
     ]],
+    "subject-exclamation-mark": [2, "never"],
     "subject-max-length": [1, "always", 100],
     "header-max-length": [0, "always"],
     "body-max-line-length": [0, "always"],

.github/dependabot.yml

@@ -1,4 +1,10 @@
 version: 2
+
+# Dependabot reads this file from the DEFAULT branch (main), not from target-branch, so
+# edits take effect only once they are released to main.
+#
+# Updates are grouped (one PR per group per week, not one per dependency), and the commit
+# prefix is pinned so Dependabot doesn't guess a type/scope from repo history.
 updates:
   - package-ecosystem: "github-actions"
     directory: "/"
@@ -8,6 +14,11 @@ updates:
     labels:
       - "dependencies"
       - "ci"
+    commit-message:
+      prefix: "chore(deps)"
+    groups:
+      github-actions:
+        patterns: ["*"]
 
   # "uv" (not "pip") so updates also refresh uv.lock
   - package-ecosystem: "uv"
@@ -18,3 +29,13 @@ updates:
     open-pull-requests-limit: 10
     labels:
       - "dependencies"
+    commit-message:
+      prefix: "chore(deps)"
+    groups:
+      # ruff and ty bumps routinely bring new lint/type diagnostics that need code fixes;
+      # keep them apart so they can't hold up the routine bumps. A dependency joins the
+      # FIRST group it matches, so this must stay above the catch-all.
+      astral-tools:
+        patterns: ["ruff", "ty"]
+      python:
+        patterns: ["*"]

.github/pull_request_template.md

@@ -30,7 +30,7 @@
 - [ ] I have updated the docs (`README.md`, `docs/`, `examples/`) if user-facing behavior changed
 - [ ] I have added unit tests that cover my changes (mocked, not requiring a live comlink service)
 - [ ] Tests pass (`uv run pytest tests/`)
-- [ ] Ruff linter and formatter pass (`uvx ruff check src/ tests/` and `uvx ruff format --check src/ tests/`)
+- [ ] Ruff linter and formatter pass (`uv run ruff check src/ tests/` and `uv run ruff format --check src/ tests/`)
 - [ ] Type check passes (`uv run ty check src/swgoh_comlink/`)
 - [ ] I have not bundled unrelated changes in this PR
 

.github/release-pr/v2.6.0.md

@@ -0,0 +1,31 @@
+Automated release prep for **v2.6.0**. CHANGELOG.md regenerated via git-changelog.
+
+Merging promotes `develop` -> `main` with the changelog already in place.
+Afterwards, run the **release** workflow on `main` to build, publish, and tag v2.6.0.
+
+_No open issues are referenced by the 22 pull requests merged since v2.5.0._
+
+---
+
+<a name="v2.6.0"></a>
+
+## [v2.6.0](https://github.com/swgoh-utils/comlink-python/compare/v2.5.0...v2.6.0) (2026-10-22)
+
+### Features
+
+- **helpers:** add get_era_units for an Era's unit roster ([38b44cd](https://github.com/swgoh-utils/comlink-python/commit/38b44cdb3d736338387bdc61fbde697c60dd4b60))
+
+### Bug Fixes
+
+- **statcalc:** build units that start above one star ([c19921b](https://github.com/swgoh-utils/comlink-python/commit/c19921bdffb9122a31c5ff0cacfad7fd3b64a04f))
+- **parity:** pass strict=True to zip in the list comparators ([0cdc467](https://github.com/swgoh-utils/comlink-python/commit/0cdc467162faa7d16ac816eee63db1334e16dda0))
+
+### Code Refactoring
+
+- **helpers:** narrow TB reward table ids to str in get_tb_mission_scores ([4edfb76](https://github.com/swgoh-utils/comlink-python/commit/4edfb76eb87167edb244f6b4a4ca1aec47fafb5b))
+
+### Docs
+
+- transport errors arrive as SwgohComlinkException ([ed3d204](https://github.com/swgoh-utils/comlink-python/commit/ed3d20418725cb3c8f5d4ce564eb3f9d3c297f8e))
+- **api:** order client pages for first-time readers ([df8dc90](https://github.com/swgoh-utils/comlink-python/commit/df8dc90ba027d81ae9fb7acb7de23aafc145dcee))
+- document the accidental major bump gotcha in commit messages ([93e05eb](https://github.com/swgoh-utils/comlink-python/commit/93e05eb57e1dbd13c562678350980184b0f94d72))

.github/tools/breaking_changes.py

@@ -0,0 +1,130 @@
+"""Explain, and police, a major version bump computed by git-changelog.
+
+The angular convention marks a commit as breaking when ANY line of its message matches
+``^break(s|ing changes?)?[ :].+$`` (case-insensitive), so a body line that merely wraps
+onto "Breaking ..." or "breaks ..." silently bumps the major version. This script reuses
+git-changelog's own parse (same commits, same regex) to list every line that triggered
+the bump, and writes them to the GitHub job summary.
+
+Usage (from the repo root)::
+
+    uv run python .github/tools/breaking_changes.py --bump auto --next-tag v3.0.0
+
+Exits 1 only when ``--bump auto`` produced a major and no commit carries the intentional
+``BREAKING CHANGE: <description>`` footer; an explicit ``--bump major`` is never blocked.
+"""
+
+from __future__ import annotations
+
+import argparse
+import os
+import re
+import sys
+from dataclasses import dataclass
+
+from git_changelog import Changelog, Commit, read_config
+
+# The Conventional Commits footer, exactly: upper-case, single space, colon, description.
+# Anything else BREAK_REGEX accepts ("Breaking changes ...", "breaks the ...") is prose.
+FOOTER_REGEX = re.compile(r"^BREAKING CHANGE: \S")
+
+
+@dataclass(frozen=True)
+class Trigger:
+    """One message line that made git-changelog treat its commit as breaking."""
+
+    commit: Commit
+    line: str
+
+    @property
+    def is_footer(self) -> bool:
+        return bool(FOOTER_REGEX.match(self.line))
+
+
+def major(tag: str) -> int:
+    return int(tag.lstrip("v").split(".", 1)[0])
+
+
+def code(text: str) -> str:
+    """Render ``text`` as an inline code span, even if it contains backticks."""
+    return f"`` {text} ``" if "`" in text else f"`{text}`"
+
+
+def find_triggers(changelog: Changelog) -> tuple[str | None, list[Trigger]]:
+    """Return the last released tag and every breaking line in the unreleased commits."""
+    unreleased = changelog.versions_list[0]
+    if unreleased.tag:  # HEAD is already tagged: nothing to bump.
+        return unreleased.tag, []
+    previous = unreleased.previous_version.tag if unreleased.previous_version else None
+    regex = changelog.convention.BREAK_REGEX
+    triggers = [
+        Trigger(commit, line)
+        for commit in unreleased.commits
+        if commit.convention["is_major"]
+        for line in [commit.subject, *commit.body]
+        if regex.match(line)
+    ]
+    return previous, triggers
+
+
+def render(previous: str, next_tag: str, bump: str, triggers: list[Trigger], blocked: bool) -> str:
+    out = [
+        f"## ⚠️ Major version bump: {previous} → {next_tag}",
+        "",
+        f"`bump={bump}`. git-changelog's angular convention treats a commit as breaking when"
+        " **any** line of its message matches `^break(s|ing changes?)?[ :].+$`"
+        " (case-insensitive). These lines triggered it:",
+        "",
+    ]
+    if not triggers:
+        out.append("_No commit since the last tag matches — the major came from the bump input._")
+    for t in triggers:
+        sha = t.commit.hash[:7]
+        ref = f"[`{sha}`]({t.commit.url})" if t.commit.url else f"`{sha}`"
+        merge = " (merge)" if len(t.commit.parent_hashes) > 1 else ""
+        kind = "✅ footer" if t.is_footer else "⚠️ prose"
+        out.append(f"- {ref}{merge} {t.commit.subject}  \n  {kind}: {code(t.line)}")
+    out.append("")
+    if blocked:
+        out += [
+            "### ❌ Blocked: no intentional `BREAKING CHANGE:` footer",
+            "",
+            "None of these lines is the exact `BREAKING CHANGE: <description>` footer, so this major"
+            " is almost certainly accidental. Re-run **prepare release** with `bump=minor` (or"
+            " `patch`); if the break is real, re-run with `bump=major`.",
+            "",
+        ]
+    return "\n".join(out)
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description="Explain and police a major bump from git-changelog.")
+    parser.add_argument("--bump", required=True, choices=["auto", "patch", "minor", "major"])
+    parser.add_argument("--next-tag", required=True, help="the tag git-changelog computed")
+    args = parser.parse_args()
+
+    config = read_config()
+    changelog = Changelog(".", convention=config["convention"], versioning=config["versioning"])
+    previous, triggers = find_triggers(changelog)
+
+    if previous is None or major(args.next_tag) <= major(previous):
+        print(f"{previous} → {args.next_tag}: not a major bump, nothing to check.")
+        return 0
+
+    blocked = args.bump == "auto" and not any(t.is_footer for t in triggers)
+    report = render(previous, args.next_tag, args.bump, triggers, blocked)
+    print(report)
+    if summary := os.environ.get("GITHUB_STEP_SUMMARY"):
+        with open(summary, "a", encoding="utf-8") as fh:
+            fh.write(report + "\n")
+    if blocked:
+        print(
+            "::error title=Accidental major bump?::bump=auto computed a major without a"
+            " 'BREAKING CHANGE:' footer; re-run with bump=minor/patch, or bump=major if intended."
+        )
+        return 1
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

.github/tools/closing_issues.py

@@ -0,0 +1,168 @@
+"""Find the issues that merged pull requests resolve, for the develop -> main release flow.
+
+GitHub only acts on closing keywords ("Closes #12") in a pull request that merges into the
+DEFAULT branch (main). Work here merges into develop, so the keywords are recorded but never
+fire, and the release PR that later carries the fix to main has no keywords of its own. This
+script reads the keywords back out of the merged pull requests (descriptions and commit
+messages) so they can be:
+
+* ``release``: re-stated in the release PR body, so GitHub closes the issues when the release
+  merges into main.
+* ``develop``: announced on each still-open issue as soon as its fix merges into develop.
+
+Matching follows GitHub's rules: a keyword (close/closes/closed, fix/fixes/fixed,
+resolve/resolves/resolved, optional colon) directly before ONE reference — ``#12``,
+``owner/repo#12`` or an issue URL in this repository. "Closes #1, #2" closes only #1, as on
+GitHub. HTML comments (the PR template's hints) and code are ignored.
+
+Usage (from the repo root, with ``gh`` authenticated)::
+
+    python3 .github/tools/closing_issues.py release --since v2.5.0
+    python3 .github/tools/closing_issues.py develop --sha <merge commit> [--dry-run]
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import re
+import subprocess
+import sys
+
+KEYWORD_REGEX = re.compile(
+    r"(?<![\w/#-])(?:close[sd]?|fix(?:e[sd])?|resolve[sd]?):?[ \t]+"
+    r"(?:(?P<repo>[\w.-]+/[\w.-]+)?#(?P<number>\d+)"
+    r"|https://github\.com/(?P<url_repo>[\w.-]+/[\w.-]+)/issues/(?P<url_number>\d+))\b",
+    re.IGNORECASE,
+)
+# Text GitHub does not scan for keywords: HTML comments, fenced code blocks (including ones
+# indented inside list items), and inline code.
+IGNORED_REGEX = re.compile(
+    r"<!--.*?-->|^[ \t]*(?P<fence>```|~~~).*?^[ \t]*(?P=fence)|`[^`\n]*`", re.DOTALL | re.MULTILINE
+)
+MERGE_SUBJECT_REGEX = re.compile(r"^Merge pull request #(\d+) from ")
+# Marks comments this script posted, so a re-run never posts the same note twice.
+MARKER = "<!-- closing-issues: pr={pr} -->"
+
+
+def gh(*args: str) -> str:
+    return subprocess.run(["gh", *args], check=True, capture_output=True, text=True).stdout
+
+
+def referenced_issues(text: str, repo: str) -> list[int]:
+    """Issue numbers in ``repo`` that ``text`` closes, in order of first mention."""
+    text = IGNORED_REGEX.sub(" ", text)
+    numbers: dict[int, None] = {}
+    for m in KEYWORD_REGEX.finditer(text):
+        ref_repo = m["repo"] or m["url_repo"] or repo
+        if ref_repo.lower() == repo.lower():
+            numbers[int(m["number"] or m["url_number"])] = None
+    return list(numbers)
+
+
+def pull_request_text(repo: str, pr: int) -> str:
+    """The PR description plus every commit message in it."""
+    body = gh("api", f"repos/{repo}/pulls/{pr}", "--jq", '.body // ""')
+    messages = gh("api", "--paginate", f"repos/{repo}/pulls/{pr}/commits", "--jq", ".[].commit.message")
+    return f"{body}\n\n{messages}"
+
+
+def is_open_issue(repo: str, number: int) -> bool:
+    """True for an open issue; False for a closed one, a pull request, or a missing number."""
+    try:
+        issue = json.loads(gh("api", f"repos/{repo}/issues/{number}"))
+    except subprocess.CalledProcessError:
+        return False
+    return issue["state"] == "open" and "pull_request" not in issue
+
+
+def issues_by_pr(repo: str, prs: list[int]) -> dict[int, list[int]]:
+    """Map each still-open issue to the merged PRs that resolve it."""
+    found: dict[int, list[int]] = {}
+    for pr in prs:
+        for number in referenced_issues(pull_request_text(repo, pr), repo):
+            found.setdefault(number, []).append(pr)
+    return {n: found[n] for n in sorted(found) if is_open_issue(repo, n)}
+
+
+def refs(prs: list[int]) -> str:
+    return ", ".join(f"#{pr}" for pr in prs)
+
+
+def release(repo: str, since: str) -> int:
+    """Print the release PR section that re-states the closing keywords merged since ``since``."""
+    subjects = subprocess.run(
+        ["git", "log", "--merges", "--format=%s", f"{since}..HEAD"], check=True, capture_output=True, text=True
+    ).stdout.splitlines()
+    prs = sorted({int(m[1]) for s in subjects if (m := MERGE_SUBJECT_REGEX.match(s))})
+    found = issues_by_pr(repo, prs)
+    if not found:
+        print(f"_No open issues are referenced by the {len(prs)} pull requests merged since {since}._")
+        return 0
+    # One keyword per line: GitHub closes only the first reference after each keyword.
+    print("### Issues resolved by this release\n")
+    print("Merging this PR into `main` closes:\n")
+    for number, by in found.items():
+        print(f"- Closes #{number} (via {refs(by)})")
+    return 0
+
+
+def develop(repo: str, sha: str, dry_run: bool) -> int:
+    """Comment on each open issue resolved by the PR(s) that ``sha`` merged into develop."""
+    prs = [
+        int(n)
+        for n in gh(
+            "api",
+            f"repos/{repo}/commits/{sha}/pulls",
+            "--jq",
+            '.[] | select(.merged_at != null and .base.ref == "develop") | .number',
+        ).split()
+    ]
+    if not prs:
+        print(f"{sha[:7]} is not a pull request merge into develop; nothing to do.")
+        return 0
+    summary = []
+    for number, by in issues_by_pr(repo, prs).items():
+        for pr in by:
+            marker = MARKER.format(pr=pr)
+            existing = gh("api", "--paginate", f"repos/{repo}/issues/{number}/comments", "--jq", ".[].body")
+            if marker in existing:
+                summary.append(f"- #{number}: already noted for #{pr}")
+                continue
+            body = (
+                f"{marker}\nAddressed by #{pr}, which is now merged into `develop`. This issue will close"
+                " automatically when that change is released to `main`."
+            )
+            if not dry_run:
+                gh("api", "-X", "POST", f"repos/{repo}/issues/{number}/comments", "-f", f"body={body}")
+            summary.append(f"- #{number}: {'would comment' if dry_run else 'commented'} (resolved by #{pr})")
+    report = "\n".join(summary) or f"No open issues are referenced by {refs(prs)}."
+    print(report)
+    if path := os.environ.get("GITHUB_STEP_SUMMARY"):
+        with open(path, "a", encoding="utf-8") as fh:
+            fh.write(f"## Issues addressed by {refs(prs)}\n\n{report}\n")
+    return 0
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description="Carry closing keywords from develop merges through to main.")
+    sub = parser.add_subparsers(dest="command", required=True)
+    rel = sub.add_parser("release", help="print the release PR's 'Closes #N' section")
+    rel.add_argument("--since", required=True, help="the last release tag")
+    dev = sub.add_parser("develop", help="comment on open issues resolved by a merge into develop")
+    dev.add_argument("--sha", required=True, help="the merge commit pushed to develop")
+    dev.add_argument("--dry-run", action="store_true", help="report without commenting")
+    args = parser.parse_args()
+
+    repo = os.environ.get("GITHUB_REPOSITORY") or gh(
+        "repo", "view", "--json", "nameWithOwner", "--jq", ".nameWithOwner"
+    )
+    repo = repo.strip()
+    if args.command == "release":
+        return release(repo, args.since)
+    return develop(repo, args.sha, args.dry_run)
+
+
+if __name__ == "__main__":
+    sys.exit(main())