releaseprobe 0.1.0__tar.gz

releaseprobe-0.1.0/.devcontainer/devcontainer-lock.json

@@ -0,0 +1,9 @@
+{
+  "features": {
+    "ghcr.io/devcontainers/features/docker-outside-of-docker:1": {
+      "version": "1.10.0",
+      "resolved": "ghcr.io/devcontainers/features/docker-outside-of-docker@sha256:c2c2cf829505ead8e4892c88c31b6594ae94a2bbb209e16e1fac456c1a3a624e",
+      "integrity": "sha256:c2c2cf829505ead8e4892c88c31b6594ae94a2bbb209e16e1fac456c1a3a624e"
+    }
+  }
+}

releaseprobe-0.1.0/.devcontainer/devcontainer.json

@@ -0,0 +1,24 @@
+{
+  "name": "releaseprobe",
+  "image": "mcr.microsoft.com/devcontainers/python:1-3.12-bookworm",
+  "postCreateCommand": "pip install -e '.[dev]'",
+  "customizations": {
+    "vscode": {
+      "extensions": [
+        "ms-python.python",
+        "ms-python.vscode-pylance",
+        "charliermarsh.ruff",
+        "ms-python.mypy-type-checker"
+      ],
+      "settings": {
+        "python.testing.pytestEnabled": true,
+        "python.testing.pytestArgs": ["tests"],
+        "[python]": {
+          "editor.defaultFormatter": "charliermarsh.ruff",
+          "editor.formatOnSave": true
+        }
+      }
+    }
+  },
+  "remoteUser": "vscode"
+}

releaseprobe-0.1.0/.github/dependabot.yml

@@ -0,0 +1,10 @@
+version: 2
+updates:
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+  - package-ecosystem: "pip"
+    directory: "/"
+    schedule:
+      interval: "weekly"

releaseprobe-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,80 @@
+name: Release
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - "src/releaseprobe/__init__.py"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    outputs:
+      released: ${{ steps.check.outputs.released }}
+      tag: ${{ steps.check.outputs.tag }}
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Determine whether the version was bumped
+        id: check
+        run: |
+          version=$(python -c "import re, pathlib; print(re.search(r'__version__\s*=\s*\"([^\"]+)\"', pathlib.Path('src/releaseprobe/__init__.py').read_text())[1])")
+          tag="v${version}"
+          echo "version=${version}" >> "$GITHUB_OUTPUT"
+          echo "tag=${tag}" >> "$GITHUB_OUTPUT"
+
+          if git rev-parse "${tag}" >/dev/null 2>&1; then
+            echo "released=false" >> "$GITHUB_OUTPUT"
+            echo "Tag ${tag} already exists, skipping release."
+          else
+            echo "released=true" >> "$GITHUB_OUTPUT"
+            echo "Version bump detected, releasing ${tag}."
+          fi
+
+      - name: Create tag and GitHub release
+        if: steps.check.outputs.released == 'true'
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          TAG: ${{ steps.check.outputs.tag }}
+        run: |
+          git tag "${TAG}"
+          git push origin "${TAG}"
+          gh release create "${TAG}" \
+            --title "${TAG}" \
+            --generate-notes
+
+  publish:
+    needs: release
+    if: needs.release.outputs.released == 'true'
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          ref: ${{ needs.release.outputs.tag }}
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Build distribution
+        run: |
+          pip install build
+          python -m build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

releaseprobe-0.1.0/.github/workflows/test.yml

@@ -0,0 +1,39 @@
+name: Test
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: pip
+
+      - name: Install dependencies
+        run: pip install -e ".[dev]"
+
+      - name: Lint
+        run: ruff check .
+
+      - name: Type check
+        run: mypy
+
+      - name: Test
+        run: pytest

releaseprobe-0.1.0/.gitignore

@@ -0,0 +1,22 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+.venv/
+venv/
+.env
+
+# Testing / coverage
+.coverage
+.coverage.*
+htmlcov/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+
+# Editors
+.vscode/
+.idea/
+*.swp

releaseprobe-0.1.0/LICENSE

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

releaseprobe-0.1.0/PKG-INFO

@@ -0,0 +1,124 @@
+Metadata-Version: 2.5
+Name: releaseprobe
+Version: 0.1.0
+Summary: Find release notes, URLs and metadata from container labels and tags.
+Project-URL: Homepage, https://github.com/dkarv/releaseprobe
+Project-URL: Repository, https://github.com/dkarv/releaseprobe
+Project-URL: Issues, https://github.com/dkarv/releaseprobe/issues
+Author-email: David Punzet <d.punzet@testbirds.de>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: container,docker,labels,oci,release-notes
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+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 :: Build Tools
+Classifier: Topic :: Utilities
+Requires-Python: >=3.10
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == 'dev'
+Requires-Dist: mypy>=1.11; extra == 'dev'
+Requires-Dist: pytest-cov>=5.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# releaseprobe
+
+Find release notes, URLs and other release metadata for container images by
+reading their labels. Inspired by [Renovate's docker datasource](https://docs.renovatebot.com/modules/datasource/docker/):
+
+- [OCI image labels](https://github.com/opencontainers/image-spec/blob/main/annotations.md)
+  (`org.opencontainers.image.*`), preferred.
+- [label-schema.org](http://label-schema.org/rc1/) labels (`org.label-schema.*`),
+  as a fallback for older images.
+
+releaseprobe does not talk to a registry or the Docker daemon itself - it
+takes the labels you already have (from `docker inspect`, `skopeo inspect`,
+`crane config`, the registry HTTP API, a Kubernetes pod spec, ...) as input
+and tells you what release metadata they contain.
+
+## Installation
+
+```bash
+pip install releaseprobe
+```
+
+## Usage
+
+Pass labels as a JSON object, e.g. straight from `docker inspect`:
+
+```bash
+docker inspect --format '{{json .Config.Labels}}' ghcr.io/org/app:1.2.3 \
+  | releaseprobe
+```
+
+```
+version:       1.2.3
+source:        https://github.com/org/app
+url:           -
+documentation: -
+revision:      abc123
+release notes: https://github.com/org/app
+```
+
+A path to a JSON file works too (`releaseprobe labels.json`); omit the path or
+pass `-` to read from stdin. Add `--json` for machine-readable output.
+
+## Library usage
+
+```python
+from releaseprobe import probe_labels
+
+info = probe_labels({"org.opencontainers.image.source": "https://github.com/org/app"})
+info.release_notes_url()  # "https://github.com/org/app"
+```
+
+## Development
+
+```bash
+python -m venv .venv
+source .venv/bin/activate
+pip install -e ".[dev]"
+
+pytest
+ruff check .
+mypy
+```
+
+### Dev container
+
+A [dev container](.devcontainer/devcontainer.json) is included so you can try
+releaseprobe in VS Code: open the repo and choose "Reopen in Container"
+(needs the Dev Containers extension). It gives you a Python 3.12 environment
+with the project installed in editable mode.
+
+The container itself has no Docker CLI, so to try releaseprobe against a
+real image, inspect it from your host and drop the labels into the workspace
+(they land in the container too, since the workspace folder is mounted in):
+
+```bash
+# on your host
+docker inspect --format '{{json .Config.Labels}}' ghcr.io/grafana/grafana:11.2.0 > labels.json
+```
+
+```bash
+# inside the dev container
+releaseprobe labels.json
+```
+
+## Releasing
+
+Bump the `__version__` string in `src/releaseprobe/__init__.py` and merge to
+`main`. The CI pipeline detects the version bump, tags the commit, creates a
+GitHub release with auto-generated notes, and publishes the package to PyPI.
+
+## License
+
+MIT, see [LICENSE](LICENSE).

releaseprobe-0.1.0/README.md

@@ -0,0 +1,93 @@
+# releaseprobe
+
+Find release notes, URLs and other release metadata for container images by
+reading their labels. Inspired by [Renovate's docker datasource](https://docs.renovatebot.com/modules/datasource/docker/):
+
+- [OCI image labels](https://github.com/opencontainers/image-spec/blob/main/annotations.md)
+  (`org.opencontainers.image.*`), preferred.
+- [label-schema.org](http://label-schema.org/rc1/) labels (`org.label-schema.*`),
+  as a fallback for older images.
+
+releaseprobe does not talk to a registry or the Docker daemon itself - it
+takes the labels you already have (from `docker inspect`, `skopeo inspect`,
+`crane config`, the registry HTTP API, a Kubernetes pod spec, ...) as input
+and tells you what release metadata they contain.
+
+## Installation
+
+```bash
+pip install releaseprobe
+```
+
+## Usage
+
+Pass labels as a JSON object, e.g. straight from `docker inspect`:
+
+```bash
+docker inspect --format '{{json .Config.Labels}}' ghcr.io/org/app:1.2.3 \
+  | releaseprobe
+```
+
+```
+version:       1.2.3
+source:        https://github.com/org/app
+url:           -
+documentation: -
+revision:      abc123
+release notes: https://github.com/org/app
+```
+
+A path to a JSON file works too (`releaseprobe labels.json`); omit the path or
+pass `-` to read from stdin. Add `--json` for machine-readable output.
+
+## Library usage
+
+```python
+from releaseprobe import probe_labels
+
+info = probe_labels({"org.opencontainers.image.source": "https://github.com/org/app"})
+info.release_notes_url()  # "https://github.com/org/app"
+```
+
+## Development
+
+```bash
+python -m venv .venv
+source .venv/bin/activate
+pip install -e ".[dev]"
+
+pytest
+ruff check .
+mypy
+```
+
+### Dev container
+
+A [dev container](.devcontainer/devcontainer.json) is included so you can try
+releaseprobe in VS Code: open the repo and choose "Reopen in Container"
+(needs the Dev Containers extension). It gives you a Python 3.12 environment
+with the project installed in editable mode.
+
+The container itself has no Docker CLI, so to try releaseprobe against a
+real image, inspect it from your host and drop the labels into the workspace
+(they land in the container too, since the workspace folder is mounted in):
+
+```bash
+# on your host
+docker inspect --format '{{json .Config.Labels}}' ghcr.io/grafana/grafana:11.2.0 > labels.json
+```
+
+```bash
+# inside the dev container
+releaseprobe labels.json
+```
+
+## Releasing
+
+Bump the `__version__` string in `src/releaseprobe/__init__.py` and merge to
+`main`. The CI pipeline detects the version bump, tags the commit, creates a
+GitHub release with auto-generated notes, and publishes the package to PyPI.
+
+## License
+
+MIT, see [LICENSE](LICENSE).

releaseprobe-0.1.0/pyproject.toml

@@ -0,0 +1,69 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "releaseprobe"
+dynamic = ["version"]
+description = "Find release notes, URLs and metadata from container labels and tags."
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.10"
+authors = [{ name = "David Punzet", email = "d.punzet@testbirds.de" }]
+keywords = ["docker", "oci", "container", "release-notes", "labels"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "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 :: Build Tools",
+    "Topic :: Utilities",
+]
+dependencies = []
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0",
+    "pytest-cov>=5.0",
+    "ruff>=0.6",
+    "mypy>=1.11",
+    "build>=1.2",
+]
+
+[project.urls]
+Homepage = "https://github.com/dkarv/releaseprobe"
+Repository = "https://github.com/dkarv/releaseprobe"
+Issues = "https://github.com/dkarv/releaseprobe/issues"
+
+[project.scripts]
+releaseprobe = "releaseprobe.cli:main"
+
+[tool.hatch.version]
+path = "src/releaseprobe/__init__.py"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/releaseprobe"]
+
+[tool.pytest.ini_options]
+addopts = "--cov=releaseprobe --cov-report=term-missing"
+testpaths = ["tests"]
+
+[tool.coverage.run]
+source = ["releaseprobe"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B"]
+
+[tool.mypy]
+python_version = "3.10"
+strict = true
+files = ["src"]

releaseprobe-0.1.0/src/releaseprobe/__init__.py

@@ -0,0 +1,7 @@
+"""releaseprobe - find release notes, URLs and metadata from container labels and tags."""
+
+from releaseprobe.probe import ReleaseInfo, probe_labels
+
+__version__ = "0.1.0"
+
+__all__ = ["ReleaseInfo", "probe_labels", "__version__"]

releaseprobe-0.1.0/src/releaseprobe/cli.py

@@ -0,0 +1,77 @@
+"""Command line interface for releaseprobe."""
+
+from __future__ import annotations
+
+import argparse
+import dataclasses
+import json
+import sys
+from typing import TextIO
+
+from releaseprobe import __version__
+from releaseprobe.probe import probe_labels
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="releaseprobe",
+        description=(
+            "Find release notes, URLs and metadata from container image labels. "
+            "Labels are read as a JSON object, e.g. the output of "
+            "`docker inspect --format '{{json .Config.Labels}}' <image>`."
+        ),
+    )
+    parser.add_argument("--version", action="version", version=f"%(prog)s {__version__}")
+    parser.add_argument(
+        "labels_file",
+        nargs="?",
+        default="-",
+        help="Path to a JSON file with the image labels, or '-' to read from stdin (default).",
+    )
+    parser.add_argument(
+        "--json",
+        action="store_true",
+        help="Print the full result as JSON instead of a human-readable summary.",
+    )
+    return parser
+
+
+def _read_labels(path: str, stdin: TextIO) -> dict[str, str]:
+    if path == "-":
+        raw = stdin.read()
+    else:
+        with open(path, encoding="utf-8") as f:
+            raw = f.read()
+    data = json.loads(raw) if raw.strip() else {}
+    if not isinstance(data, dict):
+        raise ValueError("labels JSON must be an object of label key/value pairs")
+    return data
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+
+    try:
+        labels = _read_labels(args.labels_file, sys.stdin)
+    except (OSError, ValueError, json.JSONDecodeError) as exc:
+        print(f"error: could not read labels: {exc}", file=sys.stderr)
+        return 1
+
+    info = probe_labels(labels)
+
+    if args.json:
+        print(json.dumps(dataclasses.asdict(info), indent=2))
+        return 0
+
+    print(f"version:       {info.version or '-'}")
+    print(f"source:        {info.source or '-'}")
+    print(f"url:           {info.url or '-'}")
+    print(f"documentation: {info.documentation or '-'}")
+    print(f"revision:      {info.revision or '-'}")
+    print(f"release notes: {info.release_notes_url() or '-'}")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

releaseprobe-0.1.0/src/releaseprobe/labels.py

@@ -0,0 +1,35 @@
+"""Well-known container image label keys relevant to release metadata.
+
+Two competing conventions are in use in the wild, mirroring how Renovate's
+docker datasource reads them (see
+https://docs.renovatebot.com/modules/datasource/docker/):
+
+- OCI Image Format Specification (current):
+  https://github.com/opencontainers/image-spec/blob/main/annotations.md
+- label-schema.org (deprecated, still common on older images):
+  http://label-schema.org/rc1/
+"""
+
+from __future__ import annotations
+
+# OCI Image Format Specification annotations.
+OCI_SOURCE = "org.opencontainers.image.source"
+OCI_URL = "org.opencontainers.image.url"
+OCI_DOCUMENTATION = "org.opencontainers.image.documentation"
+OCI_VERSION = "org.opencontainers.image.version"
+OCI_REVISION = "org.opencontainers.image.revision"
+OCI_VENDOR = "org.opencontainers.image.vendor"
+OCI_TITLE = "org.opencontainers.image.title"
+OCI_DESCRIPTION = "org.opencontainers.image.description"
+OCI_CREATED = "org.opencontainers.image.created"
+
+# label-schema.org annotations (deprecated), used as a fallback when the OCI
+# label is absent.
+LABEL_SCHEMA_VCS_URL = "org.label-schema.vcs-url"
+LABEL_SCHEMA_VCS_REF = "org.label-schema.vcs-ref"
+LABEL_SCHEMA_VERSION = "org.label-schema.version"
+
+# Field -> ordered list of label keys to check, OCI first, label-schema as fallback.
+SOURCE_KEYS = (OCI_SOURCE, LABEL_SCHEMA_VCS_URL)
+REVISION_KEYS = (OCI_REVISION, LABEL_SCHEMA_VCS_REF)
+VERSION_KEYS = (OCI_VERSION, LABEL_SCHEMA_VERSION)

releaseprobe-0.1.0/src/releaseprobe/probe.py

@@ -0,0 +1,54 @@
+"""Derive release metadata from a container image's labels.
+
+The labels themselves are expected to already have been collected by the
+caller (e.g. via `docker inspect`, `skopeo inspect`, `crane config`, the
+registry HTTP API, or a Kubernetes pod spec) - this module only interprets
+them, following the same label conventions as Renovate's docker datasource:
+https://docs.renovatebot.com/modules/datasource/docker/
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import dataclass, field
+
+from releaseprobe import labels as label_keys
+
+
+def _first(labels: Mapping[str, str], keys: tuple[str, ...]) -> str | None:
+    for key in keys:
+        value = labels.get(key)
+        if value:
+            return value
+    return None
+
+
+@dataclass
+class ReleaseInfo:
+    version: str | None = None
+    source: str | None = None
+    url: str | None = None
+    documentation: str | None = None
+    revision: str | None = None
+    raw_labels: dict[str, str] = field(default_factory=dict)
+
+    def release_notes_url(self) -> str | None:
+        """Best-effort guess at a release notes / changelog URL.
+
+        Prefers the VCS source repository (as Renovate does when deriving a
+        changelog), then falls back to the generic project URL and finally
+        the documentation URL.
+        """
+        return self.source or self.url or self.documentation
+
+
+def probe_labels(labels: Mapping[str, str]) -> ReleaseInfo:
+    """Extract release metadata from a mapping of container image labels."""
+    return ReleaseInfo(
+        version=_first(labels, label_keys.VERSION_KEYS),
+        source=_first(labels, label_keys.SOURCE_KEYS),
+        url=labels.get(label_keys.OCI_URL),
+        documentation=labels.get(label_keys.OCI_DOCUMENTATION),
+        revision=_first(labels, label_keys.REVISION_KEYS),
+        raw_labels=dict(labels),
+    )

releaseprobe-0.1.0/tests/data/homeassistant.json

@@ -0,0 +1,26 @@
+{
+    "io.hass.base.image": "ghcr.io/home-assistant/base:3.24",
+    "io.hass.arch": "amd64",
+    "org.opencontainers.image.url": "https://www.home-assistant.io/",
+    "io.hass.type": "core",
+    "io.hass.base.name": "python",
+    "io.hass.version": "2026.9.2",
+    "org.opencontainers.image.version": "2026.9.2",
+    "org.opencontainers.image.authors": "The Home Assistant Authors",
+    "org.opencontainers.image.source": "https://github.com/home-assistant/core",
+    "com.docker.compose.container-number": "1",
+    "com.docker.compose.replace": "homeassistant",
+    "com.docker.compose.service": "homeassistant",
+    "org.opencontainers.image.documentation": "https://www.home-assistant.io/docs/",
+    "org.opencontainers.image.licenses": "Apache-2.0",
+    "com.docker.compose.project.working_dir": "/var/misc/temp/periphery/repos/komodo/homeassistant",
+    "org.opencontainers.image.description": "Open-source home automation platform running on Python 3",
+    "com.docker.compose.version": "5.3.1",
+    "com.docker.compose.oneoff": "False",
+    "com.docker.compose.depends_on": "",
+    "io.hass.base.version": "2026.06.1",
+    "org.opencontainers.image.created": "2026-09-11 19:45:15+00:00",
+    "org.opencontainers.image.title": "Home Assistant",
+    "com.docker.compose.project": "homeassistant",
+    "io.hass.base.arch": "amd64"
+}

releaseprobe-0.1.0/tests/test_cli.py

@@ -0,0 +1,76 @@
+from __future__ import annotations
+
+import json
+
+from releaseprobe import __version__
+from releaseprobe.cli import main
+
+
+def test_version_flag(capsys) -> None:
+    exit_code = None
+    try:
+        main(["--version"])
+    except SystemExit as exc:
+        exit_code = exc.code
+
+    assert exit_code == 0
+    assert __version__ in capsys.readouterr().out
+
+
+def test_main_prints_human_summary(tmp_path, capsys) -> None:
+    labels_file = tmp_path / "labels.json"
+    labels_file.write_text(
+        json.dumps(
+            {
+                "org.opencontainers.image.version": "1.2.3",
+                "org.opencontainers.image.source": "https://github.com/org/app",
+            }
+        )
+    )
+
+    exit_code = main([str(labels_file)])
+
+    out = capsys.readouterr().out
+    assert exit_code == 0
+    assert "version:       1.2.3" in out
+    assert "release notes: https://github.com/org/app" in out
+
+
+def test_main_prints_json(tmp_path, capsys) -> None:
+    labels_file = tmp_path / "labels.json"
+    labels_file.write_text(json.dumps({"org.opencontainers.image.version": "1.2.3"}))
+
+    exit_code = main([str(labels_file), "--json"])
+
+    out = capsys.readouterr().out
+    assert exit_code == 0
+    assert json.loads(out)["version"] == "1.2.3"
+
+
+def test_main_reads_labels_from_stdin(monkeypatch, capsys) -> None:
+    import io
+
+    monkeypatch.setattr("sys.stdin", io.StringIO('{"org.opencontainers.image.version": "9.9.9"}'))
+
+    exit_code = main(["-"])
+
+    out = capsys.readouterr().out
+    assert exit_code == 0
+    assert "version:       9.9.9" in out
+
+
+def test_main_reports_invalid_json(tmp_path, capsys) -> None:
+    labels_file = tmp_path / "labels.json"
+    labels_file.write_text("not json")
+
+    exit_code = main([str(labels_file)])
+
+    assert exit_code == 1
+    assert "error" in capsys.readouterr().err
+
+
+def test_main_reports_missing_file(capsys) -> None:
+    exit_code = main(["/nonexistent/labels.json"])
+
+    assert exit_code == 1
+    assert "error" in capsys.readouterr().err

releaseprobe-0.1.0/tests/test_probe.py

@@ -0,0 +1,86 @@
+from __future__ import annotations
+
+from releaseprobe import labels
+from releaseprobe.probe import probe_labels
+
+
+def test_probe_labels_reads_oci_annotations() -> None:
+    info = probe_labels(
+        {
+            labels.OCI_VERSION: "1.2.3",
+            labels.OCI_SOURCE: "https://github.com/org/app",
+            labels.OCI_URL: "https://app.example.com",
+            labels.OCI_DOCUMENTATION: "https://docs.example.com",
+            labels.OCI_REVISION: "abc123",
+        }
+    )
+
+    assert info.version == "1.2.3"
+    assert info.source == "https://github.com/org/app"
+    assert info.url == "https://app.example.com"
+    assert info.documentation == "https://docs.example.com"
+    assert info.revision == "abc123"
+
+
+def test_probe_labels_falls_back_to_label_schema() -> None:
+    info = probe_labels(
+        {
+            labels.LABEL_SCHEMA_VERSION: "1.0.0",
+            labels.LABEL_SCHEMA_VCS_URL: "https://github.com/org/legacy",
+            labels.LABEL_SCHEMA_VCS_REF: "def456",
+        }
+    )
+
+    assert info.version == "1.0.0"
+    assert info.source == "https://github.com/org/legacy"
+    assert info.revision == "def456"
+
+
+def test_probe_labels_prefers_oci_over_label_schema() -> None:
+    info = probe_labels(
+        {
+            labels.OCI_SOURCE: "https://github.com/org/app",
+            labels.LABEL_SCHEMA_VCS_URL: "https://github.com/org/legacy",
+        }
+    )
+
+    assert info.source == "https://github.com/org/app"
+
+
+def test_probe_labels_keeps_raw_labels() -> None:
+    raw = {labels.OCI_VERSION: "1.2.3"}
+    info = probe_labels(raw)
+
+    assert info.raw_labels == raw
+
+
+def test_release_notes_url_prefers_source_then_url_then_documentation() -> None:
+    assert (
+        probe_labels(
+            {
+                labels.OCI_SOURCE: "https://github.com/org/app",
+                labels.OCI_URL: "https://app.example.com",
+                labels.OCI_DOCUMENTATION: "https://docs.example.com",
+            }
+        ).release_notes_url()
+        == "https://github.com/org/app"
+    )
+
+    assert (
+        probe_labels(
+            {
+                labels.OCI_URL: "https://app.example.com",
+                labels.OCI_DOCUMENTATION: "https://docs.example.com",
+            }
+        ).release_notes_url()
+        == "https://app.example.com"
+    )
+
+    assert (
+        probe_labels({labels.OCI_DOCUMENTATION: "https://docs.example.com"}).release_notes_url()
+        == "https://docs.example.com"
+    )
+
+
+def test_release_notes_url_returns_none_when_absent() -> None:
+    assert probe_labels({}).release_notes_url() is None