release-state-reconcile 0.1.0__tar.gz

release_state_reconcile-0.1.0/LICENSE

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

release_state_reconcile-0.1.0/PKG-INFO

@@ -0,0 +1,177 @@
+Metadata-Version: 2.4
+Name: release-state-reconcile
+Version: 0.1.0
+Summary: Read-only CLI for reconciling release candidates across fixes, backports, checks, release notes, and published releases.
+Author: LaimaWu
+License: MIT License
+        
+        Copyright (c) 2026 LaimaWu
+        
+        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.
+        
+Project-URL: Repository, https://github.com/LaimaWu/release-state-reconcile
+Project-URL: Issues, https://github.com/LaimaWu/release-state-reconcile/issues
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Quality Assurance
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# Release State Reconcile
+
+Read-only CLI for reconciling release candidates across fixes, backports, checks, release notes, and published releases.
+
+Given one public GitHub repository, one selected release candidate, and one release line, Release State Reconcile reconstructs the public evidence chain across implementation, backports, checks, release-note evidence, and published releases, surfacing missing links, branch mismatches, contradictions, and `UNKNOWN` states without mutating GitHub.
+
+## Why this exists
+
+Release state is often spread across an issue, one or more pull requests, CI checks, changed files, maintenance branches, and release tags. This tool assembles those public facts into one deterministic report and keeps uncertainty explicit. It supports investigation and review; it does not make release decisions.
+
+## Installation
+
+Python 3.10 or newer is required.
+
+### Stable GitHub release
+
+Install the verified wheel attached to the `v0.1.0` GitHub Release:
+
+```bash
+python -m pip install https://github.com/LaimaWu/release-state-reconcile/releases/download/v0.1.0/release_state_reconcile-0.1.0-py3-none-any.whl
+```
+
+### Tagged Git source
+
+Alternatively, install from the exact `v0.1.0` tag:
+
+```bash
+python -m pip install "git+https://github.com/LaimaWu/release-state-reconcile.git@v0.1.0"
+```
+
+If you use `pipx`, the same tagged source can be installed as an isolated CLI application:
+
+```bash
+pipx install "git+https://github.com/LaimaWu/release-state-reconcile.git@v0.1.0"
+```
+
+### PyPI status
+
+PyPI distribution is planned but not yet available. Do not use `pip install release-state-reconcile` until the package is published on PyPI.
+
+### Contributor and development install
+
+From a source checkout, contributors can retain an editable installation:
+
+```bash
+python -m pip install -e .
+```
+
+## CLI
+
+```bash
+release-state-reconcile \
+  --candidate https://github.com/OWNER/REPOSITORY/issues/123 \
+  --release-branch release/1.2 \
+  --config repository.json \
+  --output report.md
+```
+
+Use `--format json` for structured output. If `--output` is omitted, the report is written to standard output.
+
+## Output shape
+
+The Markdown report includes an evidence-linked state table, related pull requests, explicit same- and cross-repository relationships, contradictions, and unknown or missing links.
+
+```text
+Fact                         State
+Original issue/PR            CLOSED
+Mainline merge               MERGED | OPEN | UNKNOWN
+Required backport PRs        MERGED | MISSING | TARGET_BRANCH_MISMATCH | UNKNOWN
+Backport/check state         PASS | FAIL | PENDING | UNKNOWN
+Release-note evidence        PRESENT | ABSENT | UNKNOWN
+Final tag/release containment CONTAINED | NOT_CONTAINED | UNKNOWN
+```
+
+Each observation carries a public source URL, object type, object ID, observed state, and confidence.
+
+## Configuration
+
+Repository conventions live in JSON rather than source code. A minimal configuration looks like this:
+
+```json
+{
+  "mainline_branch": "main",
+  "backport": {"required": true, "search": true},
+  "completion": {"closed_is_complete": true, "labels": []},
+  "verification_labels": ["verified"],
+  "release_note": {"path_globs": ["changes/**"]},
+  "release": {"tag_regex": "^v1\\.2\\.[0-9]+$", "max_releases": 10}
+}
+```
+
+The selected release branch is always supplied explicitly on the command line. Configuration may describe the default branch, whether a backport is expected, repository-specific verification labels, release-note paths, and the release-tag convention.
+
+## Scope and non-goals
+
+The tool observes and reconciles public GitHub state. It does not:
+
+- decide whether a candidate belongs in a release;
+- assess change risk or release-note quality;
+- approve, merge, label, comment on, or otherwise mutate GitHub objects;
+- orchestrate releases across multiple release lines;
+- provide end-to-end release automation; or
+- use an LLM or make AI-generated release decisions.
+
+## Read-only and security model
+
+The GitHub client exposes only HTTP `GET` operations. Authentication is optional: `GITHUB_TOKEN` or `GH_TOKEN` may be supplied to increase public REST API limits, but the tool has no GitHub write methods. Reports may be written to a local path selected by the caller.
+
+The runtime uses the Python standard library and the public GitHub REST API. Do not place tokens in configuration files or commit them to source control. See [SECURITY.md](SECURITY.md) for vulnerability reporting guidance.
+
+## Validation
+
+The repository contains 21 deterministic unit tests covering closure semantics, relationship discovery, cross-repository preservation, target-branch mismatch handling, external-provider uncertainty, check aggregation, release-note path evidence, and the GET-only client surface. CI runs the full suite on Python 3.10, 3.11, 3.12, and 3.13.
+
+Run locally with:
+
+```bash
+python -m unittest discover -s tests -v
+```
+
+## Known limitations
+
+- One repository and one selected release line are evaluated per run.
+- Repository conventions may require configuration.
+- Unsupported external change providers remain `UNKNOWN`.
+- Private CI and off-GitHub approvals are outside scope.
+- Candidate eligibility and release-note quality remain human judgment.
+- Some public issues do not expose enough relationships to reconstruct a useful chain.
+- A complete GitHub search establishes only that no qualifying result was returned for that query; it is not proof that an unreferenced change does not exist.
+
+## License
+
+[MIT](LICENSE)

release_state_reconcile-0.1.0/README.md

@@ -0,0 +1,133 @@
+# Release State Reconcile
+
+Read-only CLI for reconciling release candidates across fixes, backports, checks, release notes, and published releases.
+
+Given one public GitHub repository, one selected release candidate, and one release line, Release State Reconcile reconstructs the public evidence chain across implementation, backports, checks, release-note evidence, and published releases, surfacing missing links, branch mismatches, contradictions, and `UNKNOWN` states without mutating GitHub.
+
+## Why this exists
+
+Release state is often spread across an issue, one or more pull requests, CI checks, changed files, maintenance branches, and release tags. This tool assembles those public facts into one deterministic report and keeps uncertainty explicit. It supports investigation and review; it does not make release decisions.
+
+## Installation
+
+Python 3.10 or newer is required.
+
+### Stable GitHub release
+
+Install the verified wheel attached to the `v0.1.0` GitHub Release:
+
+```bash
+python -m pip install https://github.com/LaimaWu/release-state-reconcile/releases/download/v0.1.0/release_state_reconcile-0.1.0-py3-none-any.whl
+```
+
+### Tagged Git source
+
+Alternatively, install from the exact `v0.1.0` tag:
+
+```bash
+python -m pip install "git+https://github.com/LaimaWu/release-state-reconcile.git@v0.1.0"
+```
+
+If you use `pipx`, the same tagged source can be installed as an isolated CLI application:
+
+```bash
+pipx install "git+https://github.com/LaimaWu/release-state-reconcile.git@v0.1.0"
+```
+
+### PyPI status
+
+PyPI distribution is planned but not yet available. Do not use `pip install release-state-reconcile` until the package is published on PyPI.
+
+### Contributor and development install
+
+From a source checkout, contributors can retain an editable installation:
+
+```bash
+python -m pip install -e .
+```
+
+## CLI
+
+```bash
+release-state-reconcile \
+  --candidate https://github.com/OWNER/REPOSITORY/issues/123 \
+  --release-branch release/1.2 \
+  --config repository.json \
+  --output report.md
+```
+
+Use `--format json` for structured output. If `--output` is omitted, the report is written to standard output.
+
+## Output shape
+
+The Markdown report includes an evidence-linked state table, related pull requests, explicit same- and cross-repository relationships, contradictions, and unknown or missing links.
+
+```text
+Fact                         State
+Original issue/PR            CLOSED
+Mainline merge               MERGED | OPEN | UNKNOWN
+Required backport PRs        MERGED | MISSING | TARGET_BRANCH_MISMATCH | UNKNOWN
+Backport/check state         PASS | FAIL | PENDING | UNKNOWN
+Release-note evidence        PRESENT | ABSENT | UNKNOWN
+Final tag/release containment CONTAINED | NOT_CONTAINED | UNKNOWN
+```
+
+Each observation carries a public source URL, object type, object ID, observed state, and confidence.
+
+## Configuration
+
+Repository conventions live in JSON rather than source code. A minimal configuration looks like this:
+
+```json
+{
+  "mainline_branch": "main",
+  "backport": {"required": true, "search": true},
+  "completion": {"closed_is_complete": true, "labels": []},
+  "verification_labels": ["verified"],
+  "release_note": {"path_globs": ["changes/**"]},
+  "release": {"tag_regex": "^v1\\.2\\.[0-9]+$", "max_releases": 10}
+}
+```
+
+The selected release branch is always supplied explicitly on the command line. Configuration may describe the default branch, whether a backport is expected, repository-specific verification labels, release-note paths, and the release-tag convention.
+
+## Scope and non-goals
+
+The tool observes and reconciles public GitHub state. It does not:
+
+- decide whether a candidate belongs in a release;
+- assess change risk or release-note quality;
+- approve, merge, label, comment on, or otherwise mutate GitHub objects;
+- orchestrate releases across multiple release lines;
+- provide end-to-end release automation; or
+- use an LLM or make AI-generated release decisions.
+
+## Read-only and security model
+
+The GitHub client exposes only HTTP `GET` operations. Authentication is optional: `GITHUB_TOKEN` or `GH_TOKEN` may be supplied to increase public REST API limits, but the tool has no GitHub write methods. Reports may be written to a local path selected by the caller.
+
+The runtime uses the Python standard library and the public GitHub REST API. Do not place tokens in configuration files or commit them to source control. See [SECURITY.md](SECURITY.md) for vulnerability reporting guidance.
+
+## Validation
+
+The repository contains 21 deterministic unit tests covering closure semantics, relationship discovery, cross-repository preservation, target-branch mismatch handling, external-provider uncertainty, check aggregation, release-note path evidence, and the GET-only client surface. CI runs the full suite on Python 3.10, 3.11, 3.12, and 3.13.
+
+Run locally with:
+
+```bash
+python -m unittest discover -s tests -v
+```
+
+## Known limitations
+
+- One repository and one selected release line are evaluated per run.
+- Repository conventions may require configuration.
+- Unsupported external change providers remain `UNKNOWN`.
+- Private CI and off-GitHub approvals are outside scope.
+- Candidate eligibility and release-note quality remain human judgment.
+- Some public issues do not expose enough relationships to reconstruct a useful chain.
+- A complete GitHub search establishes only that no qualifying result was returned for that query; it is not proof that an unreferenced change does not exist.
+
+## License
+
+[MIT](LICENSE)

release_state_reconcile-0.1.0/pyproject.toml

@@ -0,0 +1,40 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "release-state-reconcile"
+version = "0.1.0"
+description = "Read-only CLI for reconciling release candidates across fixes, backports, checks, release notes, and published releases."
+readme = "README.md"
+requires-python = ">=3.10"
+license = {file = "LICENSE"}
+authors = [
+  {name = "LaimaWu"}
+]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Environment :: Console",
+  "License :: OSI Approved :: MIT License",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Topic :: Software Development :: Quality Assurance"
+]
+dependencies = []
+
+[project.urls]
+Repository = "https://github.com/LaimaWu/release-state-reconcile"
+Issues = "https://github.com/LaimaWu/release-state-reconcile/issues"
+
+[project.scripts]
+release-state-reconcile = "release_state_reconcile.cli:main"
+
+[tool.setuptools]
+package-dir = {"" = "src"}
+
+[tool.setuptools.packages.find]
+where = ["src"]

release_state_reconcile-0.1.0/setup.cfg

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

release_state_reconcile-0.1.0/src/release_state_reconcile/__init__.py

@@ -0,0 +1,5 @@
+"""Deterministic, read-only GitHub release-state reconciliation."""
+
+from .reconcile import reconcile_candidate
+
+__all__ = ["reconcile_candidate"]

release_state_reconcile-0.1.0/src/release_state_reconcile/__main__.py

@@ -0,0 +1,4 @@
+from .cli import main
+
+raise SystemExit(main())
+

release_state_reconcile-0.1.0/src/release_state_reconcile/cli.py

@@ -0,0 +1,42 @@
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+from .github import GitHubAPIError, GitHubClient
+from .reconcile import reconcile_candidate
+from .report import render_json, render_markdown
+
+
+def parser() -> argparse.ArgumentParser:
+    result = argparse.ArgumentParser(
+        description="Reconstruct release-candidate state from public GitHub data (GET-only)."
+    )
+    result.add_argument("--candidate", required=True, help="Public GitHub issue or PR URL")
+    result.add_argument("--release-branch", required=True, help="Target release branch")
+    result.add_argument("--config", required=True, type=Path, help="Repository configuration JSON")
+    result.add_argument("--format", choices=("markdown", "json"), default="markdown")
+    result.add_argument("--output", type=Path, help="Write report to this path instead of stdout")
+    return result
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = parser().parse_args(argv)
+    try:
+        config = json.loads(args.config.read_text(encoding="utf-8"))
+        report = reconcile_candidate(
+            GitHubClient(), args.candidate, args.release_branch, config
+        )
+        output = render_json(report) if args.format == "json" else render_markdown(report)
+        if args.output:
+            args.output.parent.mkdir(parents=True, exist_ok=True)
+            args.output.write_text(output + "\n", encoding="utf-8")
+        else:
+            sys.stdout.write(output + "\n")
+    except (ValueError, OSError, json.JSONDecodeError, GitHubAPIError) as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 2
+    return 0
+

release_state_reconcile-0.1.0/src/release_state_reconcile/github.py

@@ -0,0 +1,107 @@
+from __future__ import annotations
+
+import json
+import os
+import urllib.error
+import urllib.parse
+import urllib.request
+from typing import Any
+
+
+class GitHubAPIError(RuntimeError):
+    def __init__(self, status: int, url: str, message: str):
+        super().__init__(f"GitHub API {status} for {url}: {message}")
+        self.status = status
+        self.url = url
+
+
+class GitHubClient:
+    """Small GET-only GitHub REST client.
+
+    There are deliberately no mutation methods in this class. Authentication is
+    optional and only expands the public REST rate limit.
+    """
+
+    api_root = "https://api.github.com"
+
+    def __init__(self, token: str | None = None, timeout: int = 30):
+        self.token = token or os.environ.get("GITHUB_TOKEN") or os.environ.get("GH_TOKEN")
+        self.timeout = timeout
+        self.requests: list[str] = []
+        self._cache: dict[str, Any] = {}
+
+    def _get(self, path: str, params: dict[str, str | int] | None = None) -> Any:
+        url = path if path.startswith("https://") else f"{self.api_root}{path}"
+        if params:
+            url = f"{url}?{urllib.parse.urlencode(params)}"
+        if url in self._cache:
+            return self._cache[url]
+        headers = {
+            "Accept": "application/vnd.github+json",
+            "User-Agent": "release-state-reconcile/0.1",
+            "X-GitHub-Api-Version": "2022-11-28",
+        }
+        if self.token:
+            headers["Authorization"] = f"Bearer {self.token}"
+        request = urllib.request.Request(url, method="GET", headers=headers)
+        self.requests.append(url)
+        try:
+            with urllib.request.urlopen(request, timeout=self.timeout) as response:
+                payload = json.loads(response.read().decode("utf-8"))
+        except urllib.error.HTTPError as exc:
+            body = exc.read().decode("utf-8", errors="replace")
+            try:
+                message = json.loads(body).get("message", body)
+            except json.JSONDecodeError:
+                message = body
+            raise GitHubAPIError(exc.code, url, message) from exc
+        self._cache[url] = payload
+        return payload
+
+    def issue(self, owner: str, repo: str, number: int) -> dict[str, Any]:
+        return self._get(f"/repos/{owner}/{repo}/issues/{number}")
+
+    def timeline(self, owner: str, repo: str, number: int) -> list[dict[str, Any]]:
+        return self._get(
+            f"/repos/{owner}/{repo}/issues/{number}/timeline", {"per_page": 100}
+        )
+
+    def comments(self, owner: str, repo: str, number: int) -> list[dict[str, Any]]:
+        return self._get(
+            f"/repos/{owner}/{repo}/issues/{number}/comments", {"per_page": 100}
+        )
+
+    def pull(self, owner: str, repo: str, number: int) -> dict[str, Any]:
+        return self._get(f"/repos/{owner}/{repo}/pulls/{number}")
+
+    def check_runs(self, owner: str, repo: str, sha: str) -> dict[str, Any]:
+        return self._get(
+            f"/repos/{owner}/{repo}/commits/{sha}/check-runs", {"per_page": 100}
+        )
+
+    def pull_files(self, owner: str, repo: str, number: int) -> list[dict[str, Any]]:
+        return self._get(
+            f"/repos/{owner}/{repo}/pulls/{number}/files", {"per_page": 100}
+        )
+
+    def branch(self, owner: str, repo: str, branch: str) -> dict[str, Any]:
+        quoted = urllib.parse.quote(branch, safe="")
+        return self._get(f"/repos/{owner}/{repo}/branches/{quoted}")
+
+    def search_pulls(
+        self, owner: str, repo: str, base: str, reference: str
+    ) -> dict[str, Any]:
+        query = f'repo:{owner}/{repo} is:pr base:"{base}" "{reference}"'
+        return self._get("/search/issues", {"q": query, "per_page": 100})
+
+    def releases(self, owner: str, repo: str) -> list[dict[str, Any]]:
+        return self._get(f"/repos/{owner}/{repo}/releases", {"per_page": 100})
+
+    def release_by_tag(self, owner: str, repo: str, tag: str) -> dict[str, Any]:
+        quoted = urllib.parse.quote(tag, safe="")
+        return self._get(f"/repos/{owner}/{repo}/releases/tags/{quoted}")
+
+    def compare(self, owner: str, repo: str, base: str, head: str) -> dict[str, Any]:
+        quoted_base = urllib.parse.quote(base, safe="")
+        quoted_head = urllib.parse.quote(head, safe="")
+        return self._get(f"/repos/{owner}/{repo}/compare/{quoted_base}...{quoted_head}")

release_state_reconcile-0.1.0/src/release_state_reconcile/models.py

@@ -0,0 +1,70 @@
+from __future__ import annotations
+
+from dataclasses import asdict, dataclass, field
+from typing import Any
+
+
+@dataclass(frozen=True)
+class Evidence:
+    source_url: str
+    object_type: str
+    object_id: str
+    observed_state: str
+    confidence: str = "factual"
+
+
+@dataclass
+class Finding:
+    name: str
+    status: str
+    summary: str
+    evidence: list[Evidence] = field(default_factory=list)
+
+
+@dataclass
+class PullRecord:
+    number: int
+    url: str
+    title: str
+    state: str
+    merged: bool
+    merged_at: str | None
+    merge_sha: str | None
+    head_sha: str | None
+    base: str
+    labels: list[str]
+    relation: str
+    relation_evidence: list[Evidence] = field(default_factory=list)
+    changed_files: int = 0
+
+
+@dataclass
+class RelationshipRecord:
+    url: str
+    provider: str
+    repository: str | None
+    object_type: str
+    object_id: str
+    scope: str
+    relation: str
+    evidence: list[Evidence] = field(default_factory=list)
+
+
+@dataclass
+class CandidateReport:
+    candidate_url: str
+    repo: str
+    number: int
+    observed_at: str
+    target_release_branch: str
+    mainline_branch: str
+    findings: list[Finding]
+    related_pulls: list[PullRecord]
+    relationships: list[RelationshipRecord]
+    contradictions: list[Finding]
+    unknowns: list[Finding]
+    materially_useful: bool
+    api_requests: list[str] = field(default_factory=list)
+
+    def to_dict(self) -> dict[str, Any]:
+        return asdict(self)