diff --git a/.github/workflows/build_release.yml b/.github/workflows/build_release.yml index 3b2bdf7..6463a97 100644 --- a/.github/workflows/build_release.yml +++ b/.github/workflows/build_release.yml @@ -10,7 +10,7 @@ concurrency: jobs: test-lint-scan: - if: github.ref == 'refs/heads/main' + if: startsWith(github.ref, 'refs/heads/release/') permissions: contents: read # Needed to check out repository security-events: write # Needed by CodeQL to upload SARIF results @@ -20,7 +20,7 @@ jobs: build: name: Build Release needs: test-lint-scan - if: github.ref == 'refs/heads/main' + if: startsWith(github.ref, 'refs/heads/release/') runs-on: ubuntu-latest timeout-minutes: 15 permissions: @@ -29,11 +29,14 @@ jobs: attestations: write # Needed to persist SLSA build provenance attestations on GitHub outputs: version: ${{ steps.version.outputs.version }} + commit: ${{ steps.version.outputs.commit }} + latest: ${{ steps.version.outputs.latest }} steps: - name: Checkout repository uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 with: persist-credentials: false + fetch-depth: 0 - name: Set up uv uses: astral-sh/setup-uv@1c37ad07a6a961277cf70c0d37d6f313000f5884 # v10.3.0 with: @@ -42,14 +45,41 @@ jobs: enable-cache: false - name: Install dependencies run: uv sync --locked --no-default-groups --group test --no-install-project - - name: Extract version and release notes from CHANGELOG.md + - name: Extract version, release commit, and release notes from CHANGELOG.md id: version run: | uv run --no-sync python -m local.verify_release changelog \ + --resolve-commit \ --notes-out "$RUNNER_TEMP/release-notes.md" \ --github-output "$GITHUB_OUTPUT" + - name: Verify release branch and release commit + env: + VERSION: ${{ steps.version.outputs.version }} + COMMIT: ${{ steps.version.outputs.commit }} + REF_NAME: ${{ github.ref_name }} + EVENT_SHA: ${{ github.sha }} + run: | + if [[ ! "$VERSION" =~ ^(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)$ ]]; then + echo "Invalid version from verify_release: $VERSION" >&2 + exit 1 + fi + if [[ ! "$COMMIT" =~ ^[0-9a-f]{40}$ ]]; then + echo "Invalid release commit from verify_release: $COMMIT" >&2 + exit 1 + fi + if [[ "$REF_NAME" != "release/$VERSION" ]]; then + echo "Workflow must be dispatched on release/$VERSION, got: $REF_NAME" >&2 + exit 1 + fi + HEAD_SHA="$(git rev-parse HEAD)" + if [[ "$HEAD_SHA" != "$COMMIT" || "$EVENT_SHA" != "$COMMIT" ]]; then + echo "Release commit $COMMIT, checked-out HEAD $HEAD_SHA, and GITHUB_SHA $EVENT_SHA must all match" >&2 + exit 1 + fi - name: Build sdist and wheel run: uv build --no-preview --no-sources --clear + - name: Verify built distributions + run: uv run --no-sync python -m local.verify_release dist - name: Attest distribution build provenance id: attest uses: actions/attest@1e69f48acb82d1966a394da916b4c1698aa569d6 # v4.2.2 @@ -82,7 +112,7 @@ jobs: publish: name: Publish to PyPI needs: build - if: github.ref == 'refs/heads/main' + if: startsWith(github.ref, 'refs/heads/release/') runs-on: ubuntu-latest timeout-minutes: 15 environment: pypi @@ -102,7 +132,7 @@ jobs: github-release: name: Create GitHub Release needs: [build, publish] - if: github.ref == 'refs/heads/main' + if: startsWith(github.ref, 'refs/heads/release/') runs-on: ubuntu-latest timeout-minutes: 10 permissions: @@ -128,11 +158,21 @@ jobs: GH_TOKEN: ${{ github.token }} GH_REPO: ${{ github.repository }} VERSION: ${{ needs.build.outputs.version }} + COMMIT: ${{ needs.build.outputs.commit }} + LATEST: ${{ needs.build.outputs.latest }} run: | - if [[ ! "$VERSION" =~ ^[0-9]+\.[0-9]+\.[0-9]+$ ]]; then + if [[ ! "$VERSION" =~ ^(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)$ ]]; then echo "Invalid version from build job: $VERSION" >&2 exit 1 fi + if [[ ! "$COMMIT" =~ ^[0-9a-f]{40}$ ]]; then + echo "Invalid commit from build job: $COMMIT" >&2 + exit 1 + fi + if [[ ! "$LATEST" =~ ^(true|false)$ ]]; then + echo "Invalid latest flag from build job: $LATEST" >&2 + exit 1 + fi BUNDLE_FILE="$(find provenance -type f | head -n 1)" if [[ -z "$BUNDLE_FILE" ]]; then echo "Missing provenance bundle in provenance/" >&2 @@ -140,12 +180,24 @@ jobs: fi cp "$BUNDLE_FILE" "provenance/cuid2-${VERSION}.sigstore.json" jq -ce '.dsseEnvelope' "$BUNDLE_FILE" > "provenance/cuid2-${VERSION}.intoto.jsonl" + if TAG_REF="$(gh api "repos/$GH_REPO/git/ref/tags/v$VERSION" 2>&1)"; then + echo "Tag v$VERSION already exists; refusing to attach the release to it: $TAG_REF" >&2 + exit 1 + elif [[ "$TAG_REF" != *"HTTP 404"* ]]; then + echo "Could not verify that tag v$VERSION is absent: $TAG_REF" >&2 + exit 1 + fi gh release create "v$VERSION" \ --repo "$GH_REPO" \ - --target "$GITHUB_SHA" \ + --target "$COMMIT" \ --title "v$VERSION" \ --notes-file release-notes/release-notes.md \ - --latest \ + --latest="$LATEST" \ dist/*.whl dist/*.tar.gz \ "provenance/cuid2-${VERSION}.sigstore.json" \ "provenance/cuid2-${VERSION}.intoto.jsonl" + TAG_COMMIT="$(gh api "repos/$GH_REPO/commits/v$VERSION" --jq .sha)" + if [[ "$TAG_COMMIT" != "$COMMIT" ]]; then + echo "Tag v$VERSION targets $TAG_COMMIT, expected $COMMIT" >&2 + exit 1 + fi diff --git a/CHANGELOG.md b/CHANGELOG.md index 4257962..fa5c8a5 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -8,6 +8,19 @@ This repository continues the `overflowdigital` `cuid2` package (`b02c8ca`); ver ## [Unreleased] +### Changed + +- `Cuid`, `Cuid.generate`, `create_id`, and `cuid_wrapper` now normalize integer-like `length` arguments via `operator.index` on validation, so objects implementing only `__index__` (without `__gt__` or `__add__`) are supported and `cuid_wrapper` binds a plain `int` in its `functools.partial` keywords. + +### Removed + +- Unreferenced internal helpers `create_letter` and `create_hash` from `cuid2.utils`. + +### Fixed + +- `cuid2 --check -` now decodes `stdin` as UTF-8 (it used the locale encoding before, which only differs on Windows before Python 3.15 and in non-UTF-8 locales) and treats lines containing invalid UTF-8 bytes as invalid identifiers (escaped via `ascii()`), exiting with code 1 instead of crashing with a `UnicodeDecodeError` traceback. +- The `cuid2` CLI no longer crashes with an unhandled traceback when `stdin` or `stdout` is closed (`<&-`, `>&-`): generation, `-h`/`--help`, and `-V`/`--version` exit with code 0 and `cuid2 --check -q` preserves its validation exit status (0 or 1) when `stdout` is closed, while non-quiet `--check` with closed `stdout` and `--check -` with closed `stdin` exit with code 1. + ## [3.0.0] - 2026-11-08 ### Changed diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index dceda66..abc8b22 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -82,7 +82,8 @@ Pull requests that change behavior, packaging, or documentation that consumers r To cut a release: 1. Open a release PR that renames `## [Unreleased]` to `## [X.Y.Z] - YYYY-MM-DD`, adds a fresh empty `## [Unreleased]` section above it, bumps `version` in `pyproject.toml` and `uv.lock`, and updates the compare-link footer in `CHANGELOG.md` (adds `[X.Y.Z]` comparing `v...vX.Y.Z` and updates `[Unreleased]` to `compare/vX.Y.Z...HEAD`). -2. After the release PR merges to `main`, dispatch `.github/workflows/build_release.yml` from `main` and approve the `pypi` environment deployment when prompted (the workflow reads the version from `pyproject.toml`, validates and extracts the matching `## [X.Y.Z]` section from `CHANGELOG.md` via `local.verify_release`, verifies and attests SLSA build provenance for the built sdist and wheel via `actions/attest`, publishes distributions with PEP 740 attestations via `pypa/gh-action-pypi-publish`, and creates the GitHub release tagged at the built commit). Verify the published attestations via `gh attestation verify --owner gordon-code` and at `https://pypi.org/integrity/cuid2///provenance`. +2. After the release PR squash-merges to `main`, a `core`-team member resolves the release commit and creates the release branch: run `git fetch origin main --tags && git switch main && git pull --ff-only`, then `uv run python -m local.verify_release changelog --resolve-commit` (prints the SHA of the commit that bumped `version` to X.Y.Z; fails if tag `vX.Y.Z` exists or X.Y.Z is not greater than every existing `v*` tag of the same major version), then `git push origin :refs/heads/release/X.Y.Z`. Release branches can be created only by the core team and are immutable (they cannot be updated, rewritten, or deleted), so double-check the SHA and version before pushing. +3. Dispatch `gh workflow run build_release.yml --ref release/X.Y.Z` and approve the `pypi` environment deployment when prompted (the workflow skips every job on a ref that is not `release/*`, and its `build` job fails unless the ref is `release/` at the commit that bumped the version, so later commits on `main` are ignored; it reads the version from `pyproject.toml`, validates and extracts the matching `## [X.Y.Z]` section from `CHANGELOG.md` via `local.verify_release`, builds and verifies the sdist and wheel, verifies and attests SLSA build provenance via `actions/attest`, publishes distributions with PEP 740 attestations via `pypa/gh-action-pypi-publish`, and creates the GitHub release with tag `vX.Y.Z` at that commit). Verify the published attestations via `gh attestation verify --owner gordon-code` and at `https://pypi.org/integrity/cuid2///provenance`. ## Submitting Pull Requests diff --git a/local/tests/test_cli.py b/local/tests/test_cli.py index ec8f9e4..2036f1f 100644 --- a/local/tests/test_cli.py +++ b/local/tests/test_cli.py @@ -1,10 +1,14 @@ from __future__ import annotations +import errno import importlib import importlib.metadata import io import os import runpy +import subprocess +import sys +import tempfile from typing import TYPE_CHECKING import pytest @@ -16,9 +20,16 @@ from cuid2.cli import main as cli_main if TYPE_CHECKING: + from collections.abc import Iterator from unittest.mock import Mock +def _assert_cli_exits(args: list[str], expected_code: int) -> None: + with pytest.raises(SystemExit) as exc_info: + cli_main(args) + assert exc_info.value.code == expected_code + + class TestCli: def test_cli_default_length( self: TestCli, @@ -382,7 +393,7 @@ def test_cli_broken_pipe( monkeypatch: pytest.MonkeyPatch, mocker: Mock, ) -> None: - """Tests that BrokenPipeError on stdout redirects stdout fd to devnull when available.""" + """Tests that BrokenPipeError on stdout redirects stdout fd to devnull and flushes before closing.""" fake_stdout = io.StringIO() monkeypatch.setattr("sys.stdout", fake_stdout) write_mock = mocker.patch.object(fake_stdout, "write", side_effect=BrokenPipeError) @@ -390,14 +401,18 @@ def test_cli_broken_pipe( write_mock.assert_called_once() assert fake_stdout.getvalue() == "" + calls: list[str] = [] mocker.patch.object(fake_stdout, "fileno", return_value=1) open_mock = mocker.patch("os.open", return_value=99) - dup2_mock = mocker.patch("os.dup2") - close_mock = mocker.patch("os.close") + dup2_mock = mocker.patch("os.dup2", side_effect=lambda *_args: calls.append("dup2")) + flush_mock = mocker.patch.object(fake_stdout, "flush", side_effect=lambda: calls.append("flush")) + close_mock = mocker.patch("os.close", side_effect=lambda *_args: calls.append("close")) cli_main(["-n", "5"]) open_mock.assert_called_once_with(os.devnull, os.O_WRONLY) dup2_mock.assert_called_once_with(99, 1) + flush_mock.assert_called_once_with() close_mock.assert_called_once_with(99) + assert calls == ["dup2", "flush", "close"] def test_cli_check_broken_pipe_is_not_success( self: TestCli, @@ -413,6 +428,355 @@ def test_cli_check_broken_pipe_is_not_success( cli_main(["--check", "-"]) assert exc_info.value.code == 1 + def test_cli_check_invalid_utf8_stdin( + self: TestCli, + monkeypatch: pytest.MonkeyPatch, + capsys: pytest.CaptureFixture[str], + ) -> None: + """Tests that --check - reconfigures TextIOWrapper stdin with surrogateescape instead of crashing.""" + valid_id = create_id() + + with monkeypatch.context() as mp: + mp.setattr("sys.stdin", io.TextIOWrapper(io.BytesIO(b"\xff\xfe\n"), encoding="utf-8", errors="strict")) + _assert_cli_exits(["--check", "-"], 1) + captured = capsys.readouterr() + assert captured.out == "\\udcff\\udcfe: invalid\n" + assert captured.err == "" + + with monkeypatch.context() as mp: + mp.setattr( + "sys.stdin", + io.TextIOWrapper(io.BytesIO(f"{valid_id}\n".encode() + b"a\x80\n"), encoding="utf-8", errors="strict"), + ) + _assert_cli_exits(["--check", "-"], 1) + captured = capsys.readouterr() + assert captured.out == f"{valid_id}: valid\na\\udc80: invalid\n" + assert captured.err == "" + + with monkeypatch.context() as mp: + preread_stdin = io.TextIOWrapper(io.BytesIO(f"header\n{valid_id}\n".encode()), encoding="utf-8") + assert preread_stdin.readline() == "header\n" + mp.setattr("sys.stdin", preread_stdin) + _assert_cli_exits(["--check", "-"], 0) + captured = capsys.readouterr() + assert captured.out == f"{valid_id}: valid\n" + assert captured.err == "" + + def test_cli_closed_stdio( + self: TestCli, + monkeypatch: pytest.MonkeyPatch, + mocker: Mock, + capsys: pytest.CaptureFixture[str], + ) -> None: + """Tests generation, --version, and --check behavior when stdin or stdout is closed.""" + valid_id = create_id() + + with monkeypatch.context() as mp: + mp.setattr("sys.stdout", None) + cli_main([]) + _assert_cli_exits(["-V"], 0) + _assert_cli_exits(["-h"], 0) + assert capsys.readouterr().err == "" + _assert_cli_exits(["--check", valid_id, "-q"], 0) + _assert_cli_exits(["--check", "BAD_ID", "-q"], 1) + _assert_cli_exits(["--check", valid_id], 1) + + with monkeypatch.context() as mp: + closed_out = io.StringIO() + closed_out.close() + mp.setattr("sys.stdout", closed_out) + cli_main(["-n", "2"]) + _assert_cli_exits(["-V"], 0) + _assert_cli_exits(["-h"], 0) + assert sys.stdout is closed_out + _assert_cli_exits(["--check", valid_id, "-q"], 0) + + with monkeypatch.context() as mp: + fake_stdout = io.StringIO() + mp.setattr("sys.stdout", fake_stdout) + mocker.patch.object(fake_stdout, "flush", side_effect=OSError(errno.EBADF, "Bad file descriptor")) + _assert_cli_exits(["--check", valid_id], 1) + + with monkeypatch.context() as mp: + mp.setattr("sys.stdin", None) + _assert_cli_exits(["--check", "-"], 1) + captured_stdin_none = capsys.readouterr() + assert captured_stdin_none.out == "" + assert captured_stdin_none.err == "" + _assert_cli_exits(["--check", "-", "-q"], 1) + captured_stdin_none_quiet = capsys.readouterr() + assert captured_stdin_none_quiet.out == "" + assert captured_stdin_none_quiet.err == "" + + with monkeypatch.context() as mp: + closed_in = io.StringIO() + closed_in.close() + mp.setattr("sys.stdin", closed_in) + _assert_cli_exits(["--check", "-"], 1) + captured_closed_in = capsys.readouterr() + assert captured_closed_in.out == "" + assert captured_closed_in.err == "" + + def test_cli_duck_typed_stdout( + self: TestCli, + monkeypatch: pytest.MonkeyPatch, + capsys: pytest.CaptureFixture[str], + ) -> None: + """Tests minimal duck-typed stdout writers without .closed or .fileno attributes.""" + chunks: list[str] = [] + broken = False + + class _MinimalWriter: + def write(self: _MinimalWriter, s: str) -> int: + if broken: + raise BrokenPipeError + chunks.append(s) + return len(s) + + def flush(self: _MinimalWriter) -> None: + return None + + writer = _MinimalWriter() + assert not hasattr(writer, "closed") + assert not hasattr(writer, "fileno") + monkeypatch.setattr("sys.stdout", writer) + + cli_main([]) + assert is_cuid("".join(chunks).strip(), min_length=DEFAULT_LENGTH, max_length=DEFAULT_LENGTH) is True + chunks.clear() + + _assert_cli_exits(["-h"], 0) + assert "usage: cuid2" in "".join(chunks) + chunks.clear() + + broken = True + cli_main([]) + _assert_cli_exits(["-h"], 0) + assert chunks == [] + assert capsys.readouterr().err == "" + + def test_cli_closed_non_iobase_stdout_and_midstream_stdin( + self: TestCli, + monkeypatch: pytest.MonkeyPatch, + capsys: pytest.CaptureFixture[str], + ) -> None: + """Tests closed non-IOBase stdout wrappers and mid-stream stdin failures after a valid candidate.""" + valid_id = create_id() + + with monkeypatch.context() as mp: + with tempfile.NamedTemporaryFile(mode="w+", encoding="utf-8") as tmp_out: + pass + assert not isinstance(tmp_out, io.IOBase) + assert tmp_out.closed is True + mp.setattr("sys.stdout", tmp_out) + cli_main([]) + _assert_cli_exits(["-h"], 0) + _assert_cli_exits(["-V"], 0) + _assert_cli_exits(["--check", valid_id, "-q"], 0) + _assert_cli_exits(["--check", valid_id], 1) + assert sys.stdout is tmp_out + + for midstream_exc in ( + UnicodeDecodeError("utf-8", b"\xff", 0, 1, "invalid start byte"), + OSError(errno.EBADF, "Bad file descriptor"), + ): + for extra_args, expected_out in (([], f"{valid_id}: valid\n"), (["-q"], "")): + + class _MidstreamFailStdin: + def __init__(self: _MidstreamFailStdin, err: Exception) -> None: + self._err = err + + def __iter__(self: _MidstreamFailStdin) -> Iterator[str]: + yield f"{valid_id}\n" + raise self._err + + with monkeypatch.context() as mp: + mp.setattr("sys.stdin", _MidstreamFailStdin(midstream_exc)) + _assert_cli_exits(["--check", "-", *extra_args], 1) + captured = capsys.readouterr() + assert captured.out == expected_out + assert captured.err == "" + + def test_cli_closed_stdout_proxy_and_parser_color_guard( + self: TestCli, + monkeypatch: pytest.MonkeyPatch, + mocker: Mock, + ) -> None: + """Tests closed stdout proxies, Mock stdout, open real-fd stdout, and _disable_parser_color.""" + valid_id = create_id() + closed_backing = io.TextIOWrapper(io.BytesIO(), encoding="utf-8") + closed_backing.close() + + class _ClosedProxy: + write = closed_backing.write + flush = closed_backing.flush + fileno = closed_backing.fileno + + @staticmethod + def isatty() -> bool: + return False + + proxy = _ClosedProxy() + assert not hasattr(proxy, "closed") + with monkeypatch.context() as mp: + mp.setattr("sys.stdout", proxy) + cli_main([]) + _assert_cli_exits(["-h"], 0) + _assert_cli_exits(["--check", valid_id], 1) + assert sys.stdout is proxy + + with monkeypatch.context() as mp: + mock_out = mocker.Mock() + mp.setattr("sys.stdout", mock_out) + _assert_cli_exits(["-V"], 0) + mock_out.write.assert_called_once() + + with tempfile.NamedTemporaryFile(mode="w+", encoding="utf-8") as open_tmp, monkeypatch.context() as mp: + mp.setattr("sys.stdout", open_tmp) + cli_main([]) + open_tmp.seek(0) + assert is_cuid(open_tmp.read().strip(), min_length=DEFAULT_LENGTH, max_length=DEFAULT_LENGTH) is True + + class _BuiltinInitFormatter: + pass + + class _PyNoColorFormatter: + def __init__(self: _PyNoColorFormatter, prog: str) -> None: + self.prog = prog + + class _ColorFormatter: + def __init__(self: _ColorFormatter, prog: str, *, color: bool = True) -> None: + self.prog = prog + self.color = color + + parser_no_color_attr = cuid2.cli._build_parser() + vars(parser_no_color_attr).pop("color", None) + orig_cls = parser_no_color_attr.formatter_class + cuid2.cli._disable_parser_color(parser_no_color_attr, _BuiltinInitFormatter) + assert "color" not in vars(parser_no_color_attr) + assert parser_no_color_attr.formatter_class is orig_cls + + cuid2.cli._disable_parser_color(parser_no_color_attr, _PyNoColorFormatter) + assert parser_no_color_attr.formatter_class is orig_cls + + parser_with_color = cuid2.cli._build_parser() + vars(parser_with_color)["color"] = True + cuid2.cli._disable_parser_color(parser_with_color, _ColorFormatter) + assert parser_with_color.formatter_class is not orig_cls + assert vars(parser_with_color)["color"] is False + + def test_cli_real_io_errors_propagate( + self: TestCli, + monkeypatch: pytest.MonkeyPatch, + mocker: Mock, + ) -> None: + """Tests that non-closed OSErrors on stdout, CSPRNG generation, and stdin propagate.""" + with monkeypatch.context() as mp: + fake_stdout = io.StringIO() + mp.setattr("sys.stdout", fake_stdout) + mocker.patch.object(fake_stdout, "write", side_effect=OSError(errno.ENOSPC, "No space left on device")) + with pytest.raises(OSError, match="No space left on device") as exc_info: + cli_main(["-n", "2"]) + assert exc_info.value.errno == errno.ENOSPC + + with monkeypatch.context() as mp: + fake_stdout = io.StringIO() + mp.setattr("sys.stdout", fake_stdout) + mocker.patch.object(fake_stdout, "flush", side_effect=OSError(errno.ENOSPC, "No space left on device")) + with pytest.raises(OSError, match="No space left on device") as exc_info: + cli_main(["-n", "2"]) + assert exc_info.value.errno == errno.ENOSPC + + with monkeypatch.context() as mp: + + class _BrokenStdin: + def __iter__(self: _BrokenStdin) -> Iterator[str]: + err_msg = "Input/output error" + raise OSError(errno.EIO, err_msg) + + mp.setattr("sys.stdin", _BrokenStdin()) + with pytest.raises(OSError, match="Input/output error") as exc_info: + cli_main(["--check", "-"]) + assert exc_info.value.errno == errno.EIO + + mocker.patch("cuid2.generator.Cuid.generate", side_effect=OSError(errno.EIO, "Input/output error")) + with pytest.raises(OSError, match="Input/output error") as exc_info: + cli_main(["-n", "2"]) + assert exc_info.value.errno == errno.EIO + + @pytest.mark.parametrize( + ("cmd", "stdin_bytes", "expected_rc", "expected_stdout"), + [ + pytest.param( + ["-m", "cuid2", "--check", "-"], + b"\xff\xfe\n", + 1, + b"\\udcff\\udcfe: invalid\n", + id="invalid_utf8_stdin", + ), + pytest.param( + ["-c", "import os, cuid2.cli; os.close(1); cuid2.cli.main(['--check', 'ab'])"], + None, + 1, + b"", + id="close_fd1_check", + ), + pytest.param( + ["-c", "import os, cuid2.cli; os.close(1); cuid2.cli.main(['--check', 'ab', '-q'])"], + None, + 0, + b"", + id="close_fd1_check_quiet", + ), + pytest.param( + ["-c", "import os, cuid2.cli; os.close(0); cuid2.cli.main(['--check', '-'])"], + None, + 1, + b"", + id="close_fd0_check_stdin", + ), + pytest.param( + ["-c", "import os, cuid2.cli; os.close(1); cuid2.cli.main([])"], + None, + 0, + b"", + id="close_fd1_generate", + ), + pytest.param( + ["-c", "import os, cuid2.cli; os.close(1); cuid2.cli.main(['-V'])"], + None, + 0, + b"", + id="close_fd1_version", + ), + pytest.param( + ["-c", "import os, cuid2.cli; os.close(1); cuid2.cli.main(['-h'])"], + None, + 0, + b"", + id="close_fd1_help", + ), + ], + ) + def test_cli_closed_stdio_subprocess( + self: TestCli, + cmd: list[str], + stdin_bytes: bytes | None, + expected_rc: int, + expected_stdout: bytes, + ) -> None: + """Tests real OS descriptor closure and invalid UTF-8 stdin in isolated child interpreters.""" + res = subprocess.run( # noqa: S603 + [sys.executable, "-I", *cmd], + input=stdin_bytes, + stdin=None if stdin_bytes is not None else subprocess.DEVNULL, + capture_output=True, + check=False, + ) + assert res.returncode == expected_rc + assert res.stdout.replace(b"\r\n", b"\n") == expected_stdout + assert res.stderr == b"" + def test_cli_does_not_initialize_generator_on_import( self: TestCli, mocker: Mock, diff --git a/local/tests/test_cuid.py b/local/tests/test_cuid.py index 856b935..3dc255f 100644 --- a/local/tests/test_cuid.py +++ b/local/tests/test_cuid.py @@ -126,15 +126,61 @@ def test_generate_non_integer_length(self: TestCuid, invalid_length: Any) -> Non with pytest.raises(TypeError): cuid_wrapper(length=invalid_length) - # Tests that integer-like lengths (int subclasses) are accepted and produce IDs of exactly that length. + # Tests that integer-like lengths (IntEnum and pure __index__ objects) are accepted and normalized to int. def test_generate_integer_like_length(self: TestCuid) -> None: class Size(IntEnum): SHORT = 10 - assert len(Cuid(length=Size.SHORT).generate()) == Size.SHORT + class _IndexOnly: + def __init__(self: _IndexOnly, value: int) -> None: + self._value = value + + def __index__(self: _IndexOnly) -> int: + return self._value + + index_ten: Any = _IndexOnly(10) + cuid_enum = Cuid(length=Size.SHORT) + cuid_index = Cuid(length=index_ten) + assert type(cuid_enum._length) is int + assert type(cuid_index._length) is int + assert len(cuid_enum.generate()) == Size.SHORT + assert len(cuid_index.generate()) == 10 assert len(Cuid().generate(length=Size.SHORT)) == Size.SHORT + assert len(Cuid().generate(length=index_ten)) == 10 assert len(create_id(length=Size.SHORT)) == Size.SHORT - assert len(cuid_wrapper(length=Size.SHORT)()) == Size.SHORT + assert len(create_id(length=index_ten)) == 10 + + wrapped_enum = cuid_wrapper(length=Size.SHORT) + assert isinstance(wrapped_enum, partial) + assert type(wrapped_enum.keywords["length"]) is int + assert len(wrapped_enum()) == Size.SHORT + + wrapped_index = cuid_wrapper(length=index_ten) + assert isinstance(wrapped_index, partial) + assert type(wrapped_index.keywords["length"]) is int + assert len(wrapped_index()) == 10 + + cuid = Cuid() + for raw in (1, 0, -1): + bad_low: Any = _IndexOnly(raw) + with pytest.raises(ValueError, match=r"Length must be at least 2 characters\."): + Cuid(length=bad_low) + with pytest.raises(ValueError, match=r"Length must be at least 2 characters\."): + cuid.generate(length=bad_low) + with pytest.raises(ValueError, match=r"Length must be at least 2 characters\."): + create_id(length=bad_low) + with pytest.raises(ValueError, match=r"Length must be at least 2 characters\."): + cuid_wrapper(length=bad_low) + + bad_high: Any = _IndexOnly(BIG_LENGTH + 1) + with pytest.raises(ValueError, match=r"Length must never exceed 32 characters\."): + Cuid(length=bad_high) + with pytest.raises(ValueError, match=r"Length must never exceed 32 characters\."): + cuid.generate(length=bad_high) + with pytest.raises(ValueError, match=r"Length must never exceed 32 characters\."): + create_id(length=bad_high) + with pytest.raises(ValueError, match=r"Length must never exceed 32 characters\."): + cuid_wrapper(length=bad_high) # Tests that specification boundary lengths MIN_LENGTH (2) and BIG_LENGTH (32) generate valid IDs of that length. @pytest.mark.parametrize("valid_length", [MIN_LENGTH, BIG_LENGTH]) diff --git a/local/tests/test_fuzz.py b/local/tests/test_fuzz.py index e9a4303..171ac4f 100644 --- a/local/tests/test_fuzz.py +++ b/local/tests/test_fuzz.py @@ -2,6 +2,7 @@ import math import random +from hashlib import sha3_512 from typing import TYPE_CHECKING, Protocol, cast from unittest.mock import Mock, patch @@ -80,9 +81,11 @@ def test_fuzz_utils_primitives( initial_count: int, ) -> None: rng = random.Random(seed) # noqa: S311 - letter: str = utils.create_letter(rng) + letter, salt = utils._letter_and_entropy_via_getrandbits(rng.getrandbits, entropy_len) assert len(letter) == 1 assert letter in ASCII_LOWERCASE + assert len(salt) == entropy_len + assert all(ch in BASE36_ALPHABET for ch in salt) entropy: str = utils.create_entropy(rng, entropy_len) assert len(entropy) == entropy_len @@ -91,11 +94,6 @@ def test_fuzz_utils_primitives( with pytest.raises(ValueError, match=r"Cannot create entropy without a length >= 1\."): utils.create_entropy(rng, invalid_entropy_len) - digest: str = utils.create_hash(data) - # A 512-bit SHA3-512 digest has at most 100 base36 digits and create_hash drops the leading digit. - assert 1 <= len(digest) <= 99 - assert all(ch in BASE36_ALPHABET for ch in digest) - fingerprint: str = utils.create_fingerprint(rng, data) assert len(fingerprint) == BIG_LENGTH assert all(ch in BASE36_ALPHABET for ch in fingerprint) @@ -167,7 +165,7 @@ def test_fuzz_create_hash_slice_arbitrary_digest(digest_int: int, length: int) - mock_hash = Mock() mock_hash.digest.return_value = digest_int.to_bytes(64, byteorder="big") with patch.object(utils, "sha3_512", return_value=mock_hash): - full_hash = utils.create_hash("fuzz") + full_hash = utils.base36_encode(digest_int)[1:] assert utils._create_hash_slice("fuzz", 1, length) == full_hash[1:length] assert utils._create_hash_slice("fuzz", 0, length) == full_hash[:length] assert utils._create_hash_slice("fuzz", 0, BIG_LENGTH) == full_hash[:BIG_LENGTH] @@ -185,7 +183,10 @@ def test_fuzz_create_hash_slice_and_scale_randbits( u53: int, dyadic_j: int, ) -> None: - assert utils._create_hash_slice(data, 1, length) == utils.create_hash(data)[1:length] + assert ( + utils._create_hash_slice(data, 1, length) + == utils.base36_encode(int.from_bytes(sha3_512(data.encode()).digest(), "big"))[2 : length + 1] + ) modulus = BASE36_RADIX**length draw_bits = modulus.bit_length() + utils._OVERSAMPLE_BITS diff --git a/local/tests/test_utils.py b/local/tests/test_utils.py index b61857b..497f922 100644 --- a/local/tests/test_utils.py +++ b/local/tests/test_utils.py @@ -6,6 +6,7 @@ import string import threading import time +from hashlib import sha3_512 from types import SimpleNamespace from typing import TYPE_CHECKING @@ -93,87 +94,6 @@ def test_performance_for_very_large_numbers(self: TestBase36Encode) -> None: ) -class TestCreateLetter: - # Tests that create_letter function returns a lowercase letter - def test_happy_path_create_letter(self: TestCreateLetter, mocker: Mock) -> None: - mock_random = mocker.Mock() - mock_random.getrandbits.return_value = 1 << (utils._LETTER_DRAW_BITS - 1) - result = utils.create_letter(random_generator=mock_random) - assert result == "n" - assert result in string.ascii_lowercase - mock_random.getrandbits.assert_called_once_with(utils._LETTER_DRAW_BITS) - - # Tests that create_letter function returns a lowercase letter when random_generator returns 0 - def test_edge_case_create_letter_zero(self: TestCreateLetter, mocker: Mock) -> None: - mock_random = mocker.Mock() - mock_random.getrandbits.return_value = 0 - result = utils.create_letter(random_generator=mock_random) - assert result == "a" - assert result in string.ascii_lowercase - mock_random.getrandbits.assert_called_once_with(utils._LETTER_DRAW_BITS) - - # Tests that create_letter function returns a lowercase letter when random_generator returns max bits - def test_edge_case_create_letter_one(self: TestCreateLetter, mocker: Mock) -> None: - mock_random = mocker.Mock() - mock_random.getrandbits.return_value = (1 << utils._LETTER_DRAW_BITS) - 1 - result = utils.create_letter(random_generator=mock_random) - assert result == "z" - assert result in string.ascii_lowercase - mock_random.getrandbits.assert_called_once_with(utils._LETTER_DRAW_BITS) - - -class TestCreateHash: - # Tests that the output of create_hash() is always a string of length 98 - def test_hash_output_length(self: TestCreateHash) -> None: - assert len(utils.create_hash()) == 98 - - # Tests that create_hash() returns the same output for the same input - def test_same_output_for_same_input(self: TestCreateHash) -> None: - input_str = "test string" - assert utils.create_hash(input_str) == utils.create_hash(input_str) - - # Tests that create_hash() returns a hash for an empty string input - def test_empty_string_input(self: TestCreateHash) -> None: - assert utils.create_hash("") - - # Tests that create_hash() returns a hash for a string input containing special characters - def test_special_characters_input(self: TestCreateHash) -> None: - input_str = "test!@#$%^&*()_+-=[]{}|;':\",./<>? string" - assert utils.create_hash(input_str) - - # Tests that create_hash() returns a hash for a very long string input - def test_very_long_string_input(self: TestCreateHash) -> None: - input_str = "a" * 1000000 - assert utils.create_hash(input_str) - assert len(utils.create_hash(str(input_str))) == 98 - - # Tests that create_hash() can handle large input strings - def test_large_input_strings(self: TestCreateHash) -> None: - input_str = "a" * 10000 - assert utils.create_hash(input_str) - assert len(utils.create_hash(str(input_str))) == 98 - - # Tests that create_hash() can handle very large integers for base36 encoding - def test_base36_encoding(self: TestCreateHash) -> None: - input_int = 99999999999999999999999999999999999999999999999999999999999999999999999999 - assert utils.create_hash(str(input_int)) - assert len(utils.create_hash(str(input_int))) == 98 - - # Tests that create_hash() raises a TypeError if the input is not a string - def test_non_string_input_types(self: TestCreateHash) -> None: - with pytest.raises(AttributeError): - utils.create_hash(12345) # type: ignore[arg-type] - - # Tests that create_hash() uses sha3_512 directly without a sha512 fallback attribute - def test_create_hash_uses_sha3_512_directly(self: TestCreateHash, mocker: Mock) -> None: - assert not hasattr(utils, "sha512") - mock_hash = mocker.Mock() - mock_hash.digest.return_value = b"\x08" + b"\x00" * 63 - mock_sha3 = mocker.patch("cuid2.utils.sha3_512", return_value=mock_hash) - assert len(utils.create_hash("test")) == 98 - mock_sha3.assert_called_once_with(b"test") - - class TestCreateEntropy: # Tests that create_entropy returns a string of expected length and only contains characters # from base36 alphabet when given a valid instance of Random and a positive length @@ -527,9 +447,12 @@ def decode_draw(bits: int) -> tuple[str, str]: def test_low_bit_stuck_random_immunity(self: TestFixedPointScalingAndHashSlice) -> None: rng = _LowBitStuckRandom(42) - assert rng.getrandbits(utils._LETTER_DRAW_BITS) % 4 == 0 + k_fused = (len(utils.ASCII_LOWERCASE) * 36**24).bit_length() + utils._OVERSAMPLE_BITS + assert rng.getrandbits(k_fused) % 4 == 0 - assert {utils.create_letter(rng) for _ in range(500)} == set(utils.ASCII_LOWERCASE) + assert {utils._letter_and_entropy_via_getrandbits(rng.getrandbits, 24)[0] for _ in range(500)} == set( + utils.ASCII_LOWERCASE, + ) rng_entropy = _LowBitStuckRandom(42) entropy_draws = [utils.create_entropy(rng_entropy, 24) for _ in range(500)] @@ -550,13 +473,20 @@ def test_create_hash_slice_branches( boundary_int: int, length: int, ) -> None: + assert not hasattr(utils, "sha512") mock_hash = mocker.Mock() mock_hash.digest.return_value = boundary_int.to_bytes(64, byteorder="big") - mocker.patch("cuid2.utils.sha3_512", return_value=mock_hash) + mock_sha3 = mocker.patch("cuid2.utils.sha3_512", return_value=mock_hash) - full_hash = utils.create_hash("boundary") + full_hash = utils.base36_encode(boundary_int)[1:] assert utils._create_hash_slice("boundary", 0, length) == full_hash[:length] assert utils._create_hash_slice("boundary", 1, length) == full_hash[1:length] + assert mock_sha3.call_count == 2 + + def test_create_letter_and_create_hash_not_exported(self: TestFixedPointScalingAndHashSlice) -> None: + assert not hasattr(utils, "create_letter") + assert not hasattr(utils, "_LETTER_DRAW_BITS") + assert not hasattr(utils, "create_hash") class _LowResolutionRandom(random.Random): @@ -614,7 +544,7 @@ def test_random_only_draws_match_per_character_reference( expected = (_per_character_letter(reference), _per_character_salt(reference, length)) assert utils._letter_and_entropy_via_random(rng_type(seed), length) == expected - assert utils.create_letter(rng_type(seed)) == _per_character_letter(rng_type(seed).random) + assert utils._letter_via_random(rng_type(seed)) == _per_character_letter(rng_type(seed).random) assert utils.create_entropy(rng_type(seed), length) == _per_character_salt(rng_type(seed).random, length) expected_count = math.floor(rng_type(seed).random() * utils.INITIAL_COUNT_MAX) assert utils._create_initial_count(rng_type(seed)) == expected_count @@ -650,7 +580,8 @@ def test_cuid_with_random_only_generator_matches_per_character_reference( letter = _per_character_letter(reference) salt = _per_character_salt(reference, 24) hash_input = utils.base36_encode(time_ns) + salt + utils.base36_encode(start_count + 1) + "fp" - assert cuid.generate() == letter + utils.create_hash(hash_input)[1:24] + expected_tail = utils.base36_encode(int.from_bytes(sha3_512(hash_input.encode()).digest(), "big"))[2:25] + assert cuid.generate() == letter + expected_tail varied = Cuid(random_generator=_RandomOnlyRandom) assert {varied.generate()[0] for _ in range(500)} == set(utils.ASCII_LOWERCASE) diff --git a/local/tests/test_verify_release.py b/local/tests/test_verify_release.py index d2ddda5..f24db91 100644 --- a/local/tests/test_verify_release.py +++ b/local/tests/test_verify_release.py @@ -1,6 +1,9 @@ from __future__ import annotations import io +import os +import shutil +import subprocess import tarfile import zipfile from typing import TYPE_CHECKING @@ -10,10 +13,13 @@ from local.verify_release import ( DEFAULT_CHANGELOG_PATH, DEFAULT_PYPROJECT_PATH, + _check_version_vs_tags, + _is_latest_version, expected_sdist_members, expected_wheel_members, main, read_project_version, + resolve_release_commit, verify_and_extract_release_notes, verify_dist_archives, ) @@ -23,8 +29,13 @@ from pathlib import Path +def _write_lf(path: Path, content: str) -> None: + path.parent.mkdir(parents=True, exist_ok=True) + path.write_text(content, encoding="utf-8", newline="\n") + + def _write_changelog(path: Path, content: str) -> Path: - path.write_text(content, encoding="utf-8") + _write_lf(path, content) return path @@ -50,10 +61,13 @@ def test_live_repository_changelog_matches_pyproject(self) -> None: assert notes.startswith("### ") assert notes.endswith("\n") - @pytest.mark.parametrize("bad_version", ["", "2.1", "v2.1.0", "2.1.0rc1", "abc"]) + @pytest.mark.parametrize( + "bad_version", + ["", "2.1", "v2.1.0", "2.1.0rc1", "abc", "01.0.0", "1.01.0", "1.0.01"], + ) def test_read_project_version_rejects_invalid_semver(self, tmp_path: Path, bad_version: str) -> None: pyproject = tmp_path / "pyproject.toml" - pyproject.write_text(f'[project]\nversion = "{bad_version}"\n', encoding="utf-8") + _write_lf(pyproject, f'[project]\nversion = "{bad_version}"\n') with pytest.raises(ValueError, match="Invalid version"): read_project_version(pyproject) @@ -143,6 +157,86 @@ def test_verify_and_extract_preserves_paragraphs_and_upgrade_notes(self, tmp_pat ), r"Missing or empty CHANGELOG\.md section for version 2\.1\.0", ), + ( + ( + "## [Unreleased]\n\n" + "## [2.1.0] - 2026-10-25\n\n### Added\n\n- A\n\n" + "## [2.1.0] - 2026-10-24\n\n### Added\n\n- B\n\n" + "[Unreleased]: https://github.com/gordon-code/cuid2/compare/v2.1.0...HEAD\n" + "[2.1.0]: https://github.com/gordon-code/cuid2/releases/tag/v2.1.0\n" + ), + "duplicate release headings", + ), + ( + ( + "## [Unreleased]\n\n" + "## [2.1.0] - 2026-10-25\n\n### Added\n\n- A\n\n" + "## [2.0.4] - 2026-10-24\n\n### Changed\n\n- B\n\n" + "## [2.0.4] - 2026-10-23\n\n### Fixed\n\n- C\n\n" + "[Unreleased]: https://github.com/gordon-code/cuid2/compare/v2.1.0...HEAD\n" + "[2.1.0]: https://github.com/gordon-code/cuid2/compare/v2.0.4...v2.1.0\n" + "[2.0.4]: https://github.com/gordon-code/cuid2/releases/tag/v2.0.4\n" + ), + "duplicate release headings", + ), + ( + ( + "## [Unreleased]\n\n" + "## [2.1.0] - 2026-10-25\n\n### Added\n\n- A\n\n" + "## [2.0.3] - 2026-10-23\n\n### Changed\n\n- B\n\n" + "## [2.0.4] - 2026-10-24\n\n### Changed\n\n- C\n\n" + "[Unreleased]: https://github.com/gordon-code/cuid2/compare/v2.1.0...HEAD\n" + "[2.1.0]: https://github.com/gordon-code/cuid2/compare/v2.0.3...v2.1.0\n" + "[2.0.3]: https://github.com/gordon-code/cuid2/compare/v2.0.2...v2.0.3\n" + "[2.0.4]: https://github.com/gordon-code/cuid2/releases/tag/v2.0.4\n" + ), + r"Release versions must be strictly decreasing: 2\.0\.3 is listed above 2\.0\.4", + ), + ( + ( + "## [Unreleased]\n\n" + "## [2.1.0] - 2026-10-25\n\n### Added\n\n- A\n\n" + "## [2.0.4] - 2026-10-24\n\n### Changed\n\n- B\n\n" + "[Unreleased]: https://github.com/gordon-code/cuid2/compare/v2.1.0...HEAD\n" + "[2.1.0]: https://github.com/gordon-code/cuid2/compare/v2.0.3...v2.1.0\n" + "[2.0.4]: https://github.com/gordon-code/cuid2/releases/tag/v2.0.4\n" + ), + "Missing or stale compare links for 2.1.0", + ), + ( + ( + "## [Unreleased]\n\n" + "## [2.1.0] - 2026-10-25\n\n### Added\n\n- A\n\n" + "## [2.1.0] - 2026-10-25\n\n### Fixed\n\n- B\n\n" + "[Unreleased]: https://github.com/gordon-code/cuid2/compare/v2.1.0...HEAD\n" + "[2.1.0]: https://github.com/gordon-code/cuid2/compare/v2.0.4...v2.1.0\n" + "[2.0.4]: https://github.com/gordon-code/cuid2/releases/tag/v2.0.4\n" + ), + "duplicate release headings", + ), + ( + ( + "## [Unreleased]\n\n" + "## [2.1.0] - 2026-10-25\n\n### Added\n\n- A\n\n" + "## [2.0.4] - 2026-10-24\n\n### Changed\n\n- B\n\n" + "[Unreleased]: https://github.com/gordon-code/cuid2/compare/v2.1.0...HEAD\n" + "[2.1.0]: https://github.com/gordon-code/cuid2/compare/v2.0.4...v2.1.0\n" + "[2.0.4]: https://github.com/gordon-code/cuid2/compare/v2.0.3...v2.0.4\n" + "[2.0.3]: https://github.com/gordon-code/cuid2/releases/tag/v2.0.3\n" + ), + "footer links do not match release headings", + ), + ( + ( + "## [Unreleased]\n\n" + "## [2.1.0] - 2026-10-25\n\n### Added\n\n- A\n\n" + "## [2.0.4]\n\n### Changed\n\n- B\n\n" + "[Unreleased]: https://github.com/gordon-code/cuid2/compare/v2.1.0...HEAD\n" + "[2.1.0]: https://github.com/gordon-code/cuid2/compare/v2.0.4...v2.1.0\n" + "[2.0.4]: https://github.com/gordon-code/cuid2/releases/tag/v2.0.4\n" + ), + "Invalid release heading", + ), ], ) def test_verify_and_extract_rejects_invalid_changelog( @@ -212,6 +306,390 @@ def test_cli_main_changelog_and_dist(self, tmp_path: Path, capsys: pytest.Captur assert main(["dist", "--pyproject", str(DEFAULT_PYPROJECT_PATH), "--dist-dir", str(tmp_path)]) == 0 bad_pyproject = tmp_path / "bad.toml" - bad_pyproject.write_text('[project]\nversion = "invalid"\n', encoding="utf-8") + _write_lf(bad_pyproject, '[project]\nversion = "invalid"\n') assert main(["changelog", "--pyproject", str(bad_pyproject)]) == 1 assert "Invalid version" in capsys.readouterr().err + + @pytest.mark.parametrize( + ("version", "tag_names", "expected_match"), + [ + ("3.1.0", ["v3.0.0"], None), + ("2.3.1", ["v3.0.0", "v2.3.0"], None), + ("0.4.0", ["v0.3.0", "v1.0.0"], None), + ("2.3.1", ["v2.4.0-rc.1", "v2.x", "v02.9.0", "vNext"], None), + ("2.3.1", ["v3.0.0", "v2.4.0"], r"not greater than existing tag v2\.4\.0 on major 2"), + ("2.3.0", ["v2.3.0"], r"not greater than existing tag v2\.3\.0 on major 2"), + ("0.2.1", ["v0.3.0"], "on major 0"), + ], + ) + def test_check_version_vs_tags( + self, + version: str, + tag_names: list[str], + expected_match: str | None, + ) -> None: + if expected_match is None: + _check_version_vs_tags(version, tag_names) + else: + with pytest.raises(ValueError, match=expected_match): + _check_version_vs_tags(version, tag_names) + + @pytest.mark.parametrize( + ("version", "tag_names", "expected"), + [ + ("3.1.0", ["v3.0.0", "v2.3.0"], True), + ("2.3.1", ["v3.0.0", "v2.3.0"], False), + ("3.0.0", [], True), + ("3.0.0", ["v3.0.0"], False), + ("2.3.1", ["v2.4.0-rc.1", "vNext"], True), + ], + ) + def test_is_latest_version(self, version: str, tag_names: list[str], expected: bool) -> None: + assert _is_latest_version(version, tag_names) is expected + + +@pytest.fixture +def isolated_git_env(monkeypatch: pytest.MonkeyPatch, tmp_path_factory: pytest.TempPathFactory) -> None: + git_keys = [k for k in os.environ if k.upper().startswith("GIT_")] + for key in git_keys: + monkeypatch.delenv(key) + cfg = tmp_path_factory.mktemp("gitcfg") / "gitconfig" + cfg.write_text( + "[user]\n\tname = Test\n\temail = test@example.invalid\n" + "[init]\n\tdefaultBranch = main\n" + "[commit]\n\tgpgsign = false\n" + "[tag]\n\tgpgsign = false\n" + "[core]\n\tautocrlf = false\n", + encoding="utf-8", + newline="\n", + ) + monkeypatch.setenv("GIT_CONFIG_GLOBAL", str(cfg)) + monkeypatch.setenv("GIT_CONFIG_NOSYSTEM", "1") + monkeypatch.setenv("GIT_TERMINAL_PROMPT", "0") + + +def _git(repo: Path, *args: str) -> str: + git = shutil.which("git") + if git is None: + pytest.skip("git not available") + return subprocess.run( # noqa: S603 + [git, *args], + cwd=repo, + check=True, + capture_output=True, + text=True, + encoding="utf-8", + ).stdout.strip() + + +def _make_release_repo(repo: Path) -> str: + _git(repo, "init", "-b", "main") + _write_lf(repo / "pyproject.toml", '[project]\nname = "cuid2"\nversion = "2.0.4"\n') + _write_lf( + repo / "CHANGELOG.md", + "# Changelog\n\n" + "## [Unreleased]\n\n" + "## [2.0.4] - 2026-10-24\n\n" + "### Changed\n\n" + "- Initial tracked release.\n\n" + "[Unreleased]: https://github.com/gordon-code/cuid2/compare/v2.0.4...HEAD\n" + "[2.0.4]: https://github.com/gordon-code/cuid2/releases/tag/v2.0.4\n", + ) + _write_lf(repo / "src" / "cuid2" / "__init__.py", '"""Stub package."""\n') + _write_lf(repo / "uv.lock", "version = 1\n") + _write_lf(repo / "README.md", "# cuid2\n") + _write_lf(repo / "LICENSE", "MIT\n") + _git(repo, "add", ".") + _git(repo, "commit", "-q", "-m", "chore: release 2.0.4") + _git(repo, "tag", "v2.0.4") + + _write_lf(repo / "pyproject.toml", '[project]\nname = "cuid2"\nversion = "2.1.0"\n') + _write_lf( + repo / "CHANGELOG.md", + "# Changelog\n\n" + "## [Unreleased]\n\n" + "## [2.1.0] - 2026-10-25\n\n" + "### Added\n\n" + "- New feature in 2.1.0.\n\n" + "## [2.0.4] - 2026-10-24\n\n" + "### Changed\n\n" + "- Initial tracked release.\n\n" + "[Unreleased]: https://github.com/gordon-code/cuid2/compare/v2.1.0...HEAD\n" + "[2.1.0]: https://github.com/gordon-code/cuid2/compare/v2.0.4...v2.1.0\n" + "[2.0.4]: https://github.com/gordon-code/cuid2/releases/tag/v2.0.4\n", + ) + _git(repo, "add", "pyproject.toml", "CHANGELOG.md") + _git(repo, "commit", "-q", "-m", "chore: release 2.1.0") + return _git(repo, "rev-parse", "HEAD") + + +@pytest.mark.usefixtures("isolated_git_env") +class TestResolveReleaseCommit: + def test_resolve_release_commit_selects_bump_commit( + self, + tmp_path: Path, + capsys: pytest.CaptureFixture[str], + ) -> None: + release_sha = _make_release_repo(tmp_path) + pyproject = tmp_path / "pyproject.toml" + changelog = tmp_path / "CHANGELOG.md" + assert ( + resolve_release_commit(tmp_path, pyproject_path=pyproject, version="2.1.0", prev_version="2.0.4") + == release_sha + ) + + _write_lf(pyproject, '[project]\nname = "cuid2"\nversion = "2.1.0"\n\n[tool.ruff]\nline-length = 120\n') + _git(tmp_path, "add", "pyproject.toml") + _git(tmp_path, "commit", "-q", "-m", "chore: update ruff config") + + _write_lf(tmp_path / "uv.lock", "version = 1\nrevision = 2\n") + _git(tmp_path, "add", "uv.lock") + _git(tmp_path, "commit", "-q", "-m", "chore: update lockfile") + + _write_lf(tmp_path / "prek.toml", "fail_fast = false\n") + _git(tmp_path, "add", "prek.toml") + _git(tmp_path, "commit", "-q", "-m", "chore: add prek config") + + assert ( + resolve_release_commit(tmp_path, pyproject_path=pyproject, version="2.1.0", prev_version="2.0.4") + == release_sha + ) + + gh_out = tmp_path / "github-output.txt" + rc = main( + [ + "changelog", + "--pyproject", + str(pyproject), + "--changelog", + str(changelog), + "--resolve-commit", + "--github-output", + str(gh_out), + ], + ) + assert rc == 0 + captured = capsys.readouterr() + assert captured.out == f"{release_sha}\n" + assert captured.err == "" + assert gh_out.read_text(encoding="utf-8") == f"version=2.1.0\ncommit={release_sha}\nlatest=true\n" + + def test_resolve_release_commit_tag_checks( + self, + tmp_path: Path, + capsys: pytest.CaptureFixture[str], + ) -> None: + release_sha = _make_release_repo(tmp_path) + pyproject = tmp_path / "pyproject.toml" + changelog = tmp_path / "CHANGELOG.md" + + _git(tmp_path, "tag", "v2.1.0") + with pytest.raises(ValueError, match=r"Release tag v2\.1\.0 already exists"): + resolve_release_commit(tmp_path, pyproject_path=pyproject, version="2.1.0", prev_version="2.0.4") + + failed_notes = tmp_path / "failed-notes.md" + failed_gh_out = tmp_path / "failed-github-output.txt" + assert ( + main( + [ + "changelog", + "--pyproject", + str(pyproject), + "--changelog", + str(changelog), + "--resolve-commit", + "--notes-out", + str(failed_notes), + "--github-output", + str(failed_gh_out), + ], + ) + == 1 + ) + failed_captured = capsys.readouterr() + assert failed_captured.out == "" + assert "Release tag v2.1.0 already exists" in failed_captured.err + assert not failed_notes.exists() + assert not failed_gh_out.exists() + + _git(tmp_path, "tag", "-d", "v2.1.0") + _git(tmp_path, "tag", "v2.2.0") + with pytest.raises(ValueError, match=r"not greater than existing tag v2\.2\.0 on major 2"): + resolve_release_commit(tmp_path, pyproject_path=pyproject, version="2.1.0", prev_version="2.0.4") + + _git(tmp_path, "tag", "-d", "v2.2.0") + for extra_tag in ("v3.0.0", "v1.9.0", "v2.1.0-rc.1", "v2.x", "v02.5.0"): + _git(tmp_path, "tag", extra_tag) + + assert ( + resolve_release_commit(tmp_path, pyproject_path=pyproject, version="2.1.0", prev_version="2.0.4") + == release_sha + ) + + gh_out = tmp_path / "github-output.txt" + rc = main( + [ + "changelog", + "--pyproject", + str(pyproject), + "--changelog", + str(changelog), + "--resolve-commit", + "--github-output", + str(gh_out), + ], + ) + assert rc == 0 + assert capsys.readouterr().out == f"{release_sha}\n" + assert gh_out.read_text(encoding="utf-8") == f"version=2.1.0\ncommit={release_sha}\nlatest=false\n" + + def test_resolve_release_commit_parent_and_head_version(self, tmp_path: Path) -> None: + release_sha = _make_release_repo(tmp_path) + pyproject = tmp_path / "pyproject.toml" + + with pytest.raises( + ValueError, + match=r"Version before release commit .* is 2\.0\.4, but CHANGELOG\.md lists previous release 2\.0\.3", + ): + resolve_release_commit(tmp_path, pyproject_path=pyproject, version="2.1.0", prev_version="2.0.3") + + assert ( + resolve_release_commit(tmp_path, pyproject_path=pyproject, version="2.1.0", prev_version=None) + == release_sha + ) + + with pytest.raises( + ValueError, + match=r"Committed pyproject\.toml at HEAD declares version '2\.1\.0', expected 2\.9\.9", + ): + resolve_release_commit(tmp_path, pyproject_path=pyproject, version="2.9.9", prev_version="2.0.4") + + def test_resolve_release_commit_first_release_and_recovery_history(self, tmp_path: Path) -> None: + first_repo = tmp_path / "first" + first_repo.mkdir() + _git(first_repo, "init", "-b", "main") + _write_lf(first_repo / "pyproject.toml", '[project]\nname = "cuid2"\nversion = "2.1.0"\n') + _git(first_repo, "add", "pyproject.toml") + _git(first_repo, "commit", "-q", "-m", "chore: initial release 2.1.0") + first_sha = _git(first_repo, "rev-parse", "HEAD") + assert ( + resolve_release_commit( + first_repo, + pyproject_path=first_repo / "pyproject.toml", + version="2.1.0", + prev_version=None, + ) + == first_sha + ) + + recovery_repo = tmp_path / "recovery" + recovery_repo.mkdir() + _make_release_repo(recovery_repo) + _write_lf(recovery_repo / "pyproject.toml", '[project]\nname = "cuid2"\nversion = "2.0.4"\n') + _git(recovery_repo, "add", "pyproject.toml") + _git(recovery_repo, "commit", "-q", "-m", "revert: restore 2.0.4") + _write_lf(recovery_repo / "pyproject.toml", '[project]\nname = "cuid2"\nversion = "2.1.1"\n') + _git(recovery_repo, "add", "pyproject.toml") + _git(recovery_repo, "commit", "-q", "-m", "chore: release 2.1.1") + final_sha = _git(recovery_repo, "rev-parse", "HEAD") + assert ( + resolve_release_commit( + recovery_repo, + pyproject_path=recovery_repo / "pyproject.toml", + version="2.1.1", + prev_version="2.0.4", + ) + == final_sha + ) + + def test_resolve_release_commit_shallow_clone(self, tmp_path: Path) -> None: + repo = tmp_path / "origin" + repo.mkdir() + _make_release_repo(repo) + clone = tmp_path / "shallow" + _git(tmp_path, "clone", "--depth", "1", repo.as_uri(), str(clone)) + with pytest.raises(ValueError, match="Repository is shallow"): + resolve_release_commit( + clone, + pyproject_path=clone / "pyproject.toml", + version="2.1.0", + prev_version="2.0.4", + ) + + def test_resolve_release_commit_requires_git( + self, + tmp_path: Path, + monkeypatch: pytest.MonkeyPatch, + ) -> None: + _make_release_repo(tmp_path) + monkeypatch.setattr(shutil, "which", lambda _name: None) + with pytest.raises(ValueError, match="git executable not found"): + resolve_release_commit( + tmp_path, + pyproject_path=tmp_path / "pyproject.toml", + version="2.1.0", + prev_version="2.0.4", + ) + + def test_resolve_release_commit_historical_pyproject_edge_cases(self, tmp_path: Path) -> None: + dyn_repo = tmp_path / "dynamic" + dyn_repo.mkdir() + _git(dyn_repo, "init", "-b", "main") + _write_lf(dyn_repo / "pyproject.toml", '[project]\nname = "cuid2"\ndynamic = ["version"]\n') + _git(dyn_repo, "add", "pyproject.toml") + _git(dyn_repo, "commit", "-q", "-m", "chore: dynamic version") + _write_lf(dyn_repo / "pyproject.toml", '[project]\nname = "cuid2"\nversion = "2.1.0"\n') + _git(dyn_repo, "add", "pyproject.toml") + _git(dyn_repo, "commit", "-q", "-m", "chore: static 2.1.0") + dyn_bump_sha = _git(dyn_repo, "rev-parse", "HEAD") + assert ( + resolve_release_commit( + dyn_repo, + pyproject_path=dyn_repo / "pyproject.toml", + version="2.1.0", + prev_version=None, + ) + == dyn_bump_sha + ) + with pytest.raises( + ValueError, + match=r"Version before release commit .* is absent, but CHANGELOG\.md lists previous release 2\.0\.4", + ): + resolve_release_commit( + dyn_repo, + pyproject_path=dyn_repo / "pyproject.toml", + version="2.1.0", + prev_version="2.0.4", + ) + + bad_toml_repo = tmp_path / "bad_toml" + bad_toml_repo.mkdir() + _git(bad_toml_repo, "init", "-b", "main") + _write_lf(bad_toml_repo / "pyproject.toml", "[project\nbroken = true\n") + _git(bad_toml_repo, "add", "pyproject.toml") + _git(bad_toml_repo, "commit", "-q", "-m", "chore: broken toml") + _write_lf(bad_toml_repo / "pyproject.toml", '[project]\nname = "cuid2"\nversion = "2.1.0"\n') + _git(bad_toml_repo, "add", "pyproject.toml") + _git(bad_toml_repo, "commit", "-q", "-m", "chore: fix toml and set 2.1.0") + with pytest.raises(ValueError, match=r"Cannot parse pyproject\.toml at"): + resolve_release_commit( + bad_toml_repo, + pyproject_path=bad_toml_repo / "pyproject.toml", + version="2.1.0", + prev_version=None, + ) + + untracked_repo = tmp_path / "untracked" + untracked_repo.mkdir() + _git(untracked_repo, "init", "-b", "main") + _write_lf(untracked_repo / "README.md", "# cuid2\n") + _git(untracked_repo, "add", "README.md") + _git(untracked_repo, "commit", "-q", "-m", "docs: add readme") + _write_lf(untracked_repo / "pyproject.toml", '[project]\nname = "cuid2"\nversion = "2.1.0"\n') + with pytest.raises(ValueError, match=r"No first-parent commit reachable from HEAD touches pyproject\.toml"): + resolve_release_commit( + untracked_repo, + pyproject_path=untracked_repo / "pyproject.toml", + version="2.1.0", + prev_version=None, + ) diff --git a/local/verify_release.py b/local/verify_release.py index 0ead648..9b9183b 100644 --- a/local/verify_release.py +++ b/local/verify_release.py @@ -3,7 +3,10 @@ from __future__ import annotations import argparse +import itertools import re +import shutil +import subprocess import sys import tarfile import tomllib @@ -14,7 +17,7 @@ import keepachangelog if TYPE_CHECKING: - from collections.abc import Sequence + from collections.abc import Iterable, Sequence _REPO_ROOT = Path(__file__).resolve().parent.parent DEFAULT_PYPROJECT_PATH = _REPO_ROOT / "pyproject.toml" @@ -23,12 +26,30 @@ DEFAULT_REPO_URL = "https://github.com/gordon-code/cuid2" _MIN_RELEASES = 2 -_SEMVER_RE = re.compile(r"^[0-9]+\.[0-9]+\.[0-9]+$") +_MIN_RELEASES_WITH_PREV = 3 +_SEMVER_CORE = r"(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)" +_SEMVER_RE = re.compile(rf"^{_SEMVER_CORE}$") +_TAG_VER_RE = re.compile(rf"^v{_SEMVER_CORE}$") +_COMMIT_SHA_RE = re.compile(r"^[0-9a-f]{40}$") _DATE_RE = re.compile(r"^\d{4}-\d{2}-\d{2}$") _H2_RE = re.compile(r"^## ") +_RELEASE_H2_RE = re.compile(rf"^## \[(?P{_SEMVER_CORE})\] - \d{{4}}-\d{{2}}-\d{{2}}$") _FOOTER_LINK_RE = re.compile(r"^\[[^\]]+\]:\s*https?://") +def _parse_semver(version: str) -> tuple[int, int, int]: + match = _SEMVER_RE.fullmatch(version) + if match is None: + msg = f"Invalid semantic version: {version}" + raise ValueError(msg) + major, minor, patch = match.groups() + return (int(major), int(minor), int(patch)) + + +def _previous_release_version(release_keys: Sequence[str]) -> str | None: + return release_keys[2] if len(release_keys) >= _MIN_RELEASES_WITH_PREV else None + + def read_project_version(pyproject_path: Path = DEFAULT_PYPROJECT_PATH) -> str: """Read and validate the semantic version from ``pyproject.toml``. @@ -55,6 +76,29 @@ def read_project_version(pyproject_path: Path = DEFAULT_PYPROJECT_PATH) -> str: return version +def _parse_release_h2(header: str) -> str: + match = _RELEASE_H2_RE.fullmatch(header) + if match is None: + msg = f"Invalid release heading in CHANGELOG.md: {header}" + raise ValueError(msg) + return match.group("version") + + +def _validate_release_headings(release_keys: Sequence[str], lines: Sequence[str]) -> None: + h2_headers = [line for line in lines if _H2_RE.match(line)] + heading_versions = [_parse_release_h2(header) for header in h2_headers[1:]] + if len(set(heading_versions)) != len(heading_versions): + msg = "CHANGELOG.md has duplicate release headings" + raise ValueError(msg) + if list(release_keys) != ["unreleased", *heading_versions]: + msg = "CHANGELOG.md footer links do not match release headings" + raise ValueError(msg) + for newer, older in itertools.pairwise(heading_versions): + if _parse_semver(newer) <= _parse_semver(older): + msg = f"Release versions must be strictly decreasing: {newer} is listed above {older}" + raise ValueError(msg) + + def _validate_keepachangelog_metadata( changelog_path: Path, lines: list[str], @@ -67,6 +111,7 @@ def _validate_keepachangelog_metadata( if len(release_keys) < _MIN_RELEASES or release_keys[0] != "unreleased" or release_keys[1] != version: msg = f"Expected keepachangelog release order ['unreleased', '{version}', ...] in {changelog_path}" raise ValueError(msg) + _validate_release_headings(release_keys, lines) unreleased_meta = releases["unreleased"].get("metadata", {}) version_entry = releases[version] @@ -80,12 +125,19 @@ def _validate_keepachangelog_metadata( expected_unreleased_url = f"{repo_url}/compare/v{version}...HEAD" version_url = str(version_meta.get("url") or "") unreleased_link_line = f"[Unreleased]: {expected_unreleased_url}" - version_link_prefix = f"[{version}]: {repo_url}/" + prev_version = _previous_release_version(release_keys) + if prev_version is None: + version_link_prefix = f"[{version}]: {repo_url}/" + valid_version_link = version_url.startswith(f"{repo_url}/") and any( + line.startswith(version_link_prefix) for line in lines + ) + else: + expected_version_url = f"{repo_url}/compare/v{prev_version}...v{version}" + valid_version_link = version_url == expected_version_url and f"[{version}]: {expected_version_url}" in lines if ( unreleased_meta.get("url") != expected_unreleased_url - or not version_url.startswith(f"{repo_url}/") or unreleased_link_line not in lines - or not any(line.startswith(version_link_prefix) for line in lines) + or not valid_version_link ): msg = f"Missing or stale compare links for {version} in {changelog_path} footer" raise ValueError(msg) @@ -249,6 +301,169 @@ def verify_dist_archives(dist_dir: Path = DEFAULT_DIST_DIR, *, version: str) -> raise ValueError(msg) +def _run_git(repo_root: Path, *args: str) -> subprocess.CompletedProcess[str]: + git = shutil.which("git") + if git is None: + msg = "git executable not found" + raise ValueError(msg) + return subprocess.run( # noqa: S603 + [git, *args], + cwd=repo_root, + check=False, + capture_output=True, + text=True, + encoding="utf-8", + ) + + +def _assert_full_history(repo_root: Path) -> None: + res = _run_git(repo_root, "rev-parse", "--is-shallow-repository") + if res.returncode != 0: + msg = f"Failed to query git repository history depth: {res.stderr.strip()}" + raise ValueError(msg) + if res.stdout.strip() == "true": + msg = "Repository is shallow; fetch full history (fetch-depth: 0)" + raise ValueError(msg) + + +def _assert_tag_available(repo_root: Path, version: str) -> None: + if _run_git(repo_root, "rev-parse", "--verify", "--quiet", f"refs/tags/v{version}").returncode == 0: + msg = f"Release tag v{version} already exists" + raise ValueError(msg) + + +def _list_version_tags(repo_root: Path) -> list[str]: + res = _run_git(repo_root, "tag", "--list", "v*") + if res.returncode != 0: + msg = f"Failed to list git tags: {res.stderr.strip()}" + raise ValueError(msg) + return res.stdout.splitlines() + + +def _check_version_vs_tags(version: str, tag_names: Iterable[str]) -> None: + target = _parse_semver(version) + major = target[0] + for tag_name in tag_names: + if not _TAG_VER_RE.fullmatch(tag_name): + continue + tag_ver = tag_name[1:] + parsed_tag = _parse_semver(tag_ver) + if parsed_tag[0] == major and target <= parsed_tag: + msg = f"Version {version} is not greater than existing tag v{tag_ver} on major {major}" + raise ValueError(msg) + + +def _assert_version_above_same_major_tags(repo_root: Path, version: str) -> None: + _check_version_vs_tags(version, _list_version_tags(repo_root)) + + +def _is_latest_version(version: str, tag_names: Iterable[str]) -> bool: + target = _parse_semver(version) + return all(target > _parse_semver(tag_name[1:]) for tag_name in tag_names if _TAG_VER_RE.fullmatch(tag_name)) + + +def _project_version_at(repo_root: Path, rev: str, rel_pyproject: str) -> str | None: + res = _run_git(repo_root, "show", f"{rev}:{rel_pyproject}") + if res.returncode != 0: + return None + try: + data = tomllib.loads(res.stdout) + except tomllib.TOMLDecodeError as exc: + msg = f"Cannot parse {rel_pyproject} at {rev}: {exc}" + raise ValueError(msg) from exc + project = data.get("project") + if not isinstance(project, dict): + return None + raw_version = project.get("version") + return raw_version if isinstance(raw_version, str) else None + + +def _find_bump_commit( + repo_root: Path, + rel_pyproject: str, + *, + version: str, + prev_version: str | None, +) -> str: + res = _run_git(repo_root, "log", "--first-parent", "--format=%H", "HEAD", "--", rel_pyproject) + if res.returncode != 0: + msg = f"Failed to inspect git history for {rel_pyproject}: {res.stderr.strip()}" + raise ValueError(msg) + shas = res.stdout.split() + if not shas: + msg = f"No first-parent commit reachable from HEAD touches {rel_pyproject}" + raise ValueError(msg) + for sha in shas: + if _COMMIT_SHA_RE.fullmatch(sha) is None: + msg = f"Invalid commit SHA from git log: {sha}" + raise ValueError(msg) + tip = _project_version_at(repo_root, shas[0], rel_pyproject) + if tip != version: + msg = f"Committed {rel_pyproject} at HEAD declares version {tip!r}, expected {version}" + raise ValueError(msg) + bump = shas[0] + prev: str | None = None + for sha in shas[1:]: + candidate = _project_version_at(repo_root, sha, rel_pyproject) + if candidate != version: + prev = candidate + break + bump = sha + if prev_version is not None and prev != prev_version: + msg = ( + f"Version before release commit {bump} is {prev or 'absent'}, " + f"but CHANGELOG.md lists previous release {prev_version}" + ) + raise ValueError(msg) + return bump + + +def resolve_release_commit( + repo_root: Path, + *, + pyproject_path: Path, + version: str, + prev_version: str | None, +) -> str: + """Resolve the first-parent commit SHA that bumped ``pyproject.toml`` to ``version``. + + Parameters + ---------- + repo_root : Path + Root directory of the git repository. + pyproject_path : Path + Path to ``pyproject.toml`` inside ``repo_root``. + version : str + Target strict SemVer release version expected at ``HEAD``. + prev_version : str | None + Immediately preceding release version from ``CHANGELOG.md``, or ``None`` for an initial release. + + Returns + ------- + str + 40-character lowercase hexadecimal SHA-1 of the commit that introduced ``version``. + + Raises + ------ + ValueError + If ``git`` is unavailable, the repository is shallow, tag ``v{version}`` already exists, + ``version`` is not greater than every existing strict-SemVer tag of the same major version, + ``pyproject_path`` is outside ``repo_root``, ``HEAD`` does not declare ``version``, or the + version immediately preceding the bump commit does not match ``prev_version``. + """ + _parse_semver(version) + _assert_full_history(repo_root) + _assert_tag_available(repo_root, version) + _assert_version_above_same_major_tags(repo_root, version) + rel_pyproject = pyproject_path.resolve().relative_to(repo_root.resolve()).as_posix() + return _find_bump_commit( + repo_root, + rel_pyproject, + version=version, + prev_version=prev_version, + ) + + def _build_parser() -> argparse.ArgumentParser: parser = argparse.ArgumentParser( prog="python -m local.verify_release", @@ -282,7 +497,15 @@ def _build_parser() -> argparse.ArgumentParser: "--github-output", type=Path, default=None, - help="Optional path to GITHUB_OUTPUT file to append version=.", + help=( + "Optional path to GITHUB_OUTPUT file to append version= " + "(plus commit= and latest= with --resolve-commit)." + ), + ) + changelog_parser.add_argument( + "--resolve-commit", + action="store_true", + help="Resolve and verify the release commit SHA and tag invariants, printing the SHA to stdout.", ) dist_parser = subparsers.add_parser( @@ -305,6 +528,35 @@ def _build_parser() -> argparse.ArgumentParser: return parser +def _run_changelog_command(args: argparse.Namespace, *, version: str) -> None: + notes = verify_and_extract_release_notes(args.changelog, version=version) + commit_sha: str | None = None + latest: bool | None = None + if args.resolve_commit: + release_keys = list(keepachangelog.to_dict(str(args.changelog), show_unreleased=True)) + prev_version = _previous_release_version(release_keys) + repo_root = args.pyproject.resolve().parent + commit_sha = resolve_release_commit( + repo_root, + pyproject_path=args.pyproject, + version=version, + prev_version=prev_version, + ) + latest = _is_latest_version(version, _list_version_tags(repo_root)) + + if args.notes_out is not None: + args.notes_out.write_text(notes, encoding="utf-8") + if commit_sha is not None: + sys.stdout.write(f"{commit_sha}\n") + if args.github_output is not None: + output_lines = [f"version={version}\n"] + if commit_sha is not None and latest is not None: + output_lines.append(f"commit={commit_sha}\n") + output_lines.append(f"latest={'true' if latest else 'false'}\n") + with args.github_output.open("a", encoding="utf-8") as fh: + fh.writelines(output_lines) + + def main(argv: Sequence[str] | None = None) -> int: """CLI entry point for release and distribution verification. @@ -323,12 +575,7 @@ def main(argv: Sequence[str] | None = None) -> int: try: version = read_project_version(args.pyproject) if args.command == "changelog": - notes = verify_and_extract_release_notes(args.changelog, version=version) - if args.notes_out is not None: - args.notes_out.write_text(notes, encoding="utf-8") - if args.github_output is not None: - with args.github_output.open("a", encoding="utf-8") as fh: - fh.write(f"version={version}\n") + _run_changelog_command(args, version=version) elif args.command == "dist": verify_dist_archives(args.dist_dir, version=version) except ValueError as exc: diff --git a/src/cuid2/cli.py b/src/cuid2/cli.py index 6666017..3c75654 100644 --- a/src/cuid2/cli.py +++ b/src/cuid2/cli.py @@ -2,6 +2,8 @@ from __future__ import annotations +import errno +import io import os import sys from argparse import SUPPRESS, Action, ArgumentParser, ArgumentTypeError, RawDescriptionHelpFormatter @@ -16,25 +18,87 @@ if TYPE_CHECKING: from argparse import Namespace - from collections.abc import Iterable, Iterator, Sequence + from collections.abc import Callable, Iterable, Iterator, Sequence from random import Random + from typing import TextIO _SLUG_LENGTH: int = 5 -def _write_lines(lines: Iterable[str]) -> None: +def _is_closed_stream_error(exc: OSError | ValueError) -> bool: + # A closed Python file raises ValueError; a closed or broken descriptor raises EBADF or BrokenPipeError + # (matched by type: a bare BrokenPipeError() carries no errno). + return isinstance(exc, ValueError | BrokenPipeError) or exc.errno == errno.EBADF + + +def _stdout_cannot_probe_color(stdout: TextIO | None) -> bool: + if stdout is None or getattr(stdout, "closed", False) is True: + return True + try: + os.isatty(stdout.fileno()) + except (AttributeError, OSError, TypeError, ValueError): + return True + return False + + +def _disable_parser_color( + parser: ArgumentParser, + formatter_cls: Callable[..., object] = RawDescriptionHelpFormatter, +) -> None: + # Python 3.14+ ArgumentParser(color=...) and Python 3.14 HelpFormatter(color=...) probe sys.stdout via _colorize. + parser_vars = vars(parser) + if "color" in parser_vars: + parser_vars["color"] = False + init_code = getattr(getattr(formatter_cls, "__init__", None), "__code__", None) + if init_code is not None and "color" in init_code.co_varnames: + parser_vars["formatter_class"] = partial(formatter_cls, color=False) + + +def _redirect_stdout_to_devnull(stdout: TextIO) -> None: + with suppress(AttributeError, OSError, ValueError): + stdout_fd = stdout.fileno() + devnull = os.open(os.devnull, os.O_WRONLY) + try: + os.dup2(devnull, stdout_fd) + stdout.flush() + finally: + os.close(devnull) + + +def _write_lines(lines: Iterable[str]) -> bool: + stdout = sys.stdout + if stdout is None: + return False + for line in lines: + try: + stdout.write(line) + except (OSError, ValueError) as exc: + if not _is_closed_stream_error(exc): + raise + _redirect_stdout_to_devnull(stdout) + return False try: - for line in lines: - sys.stdout.write(line) - sys.stdout.flush() - except BrokenPipeError: - with suppress(OSError): - stdout_fd = sys.stdout.fileno() - devnull = os.open(os.devnull, os.O_WRONLY) - try: - os.dup2(devnull, stdout_fd) - finally: - os.close(devnull) + stdout.flush() + except (OSError, ValueError) as exc: + if not _is_closed_stream_error(exc): + raise + _redirect_stdout_to_devnull(stdout) + return False + return True + + +class _HelpAction(Action): + def __call__( + self: _HelpAction, + parser: ArgumentParser, + namespace: Namespace, + values: object, + option_string: str | None = None, + ) -> None: + """Print help message to stdout and exit.""" + del namespace, values, option_string + _write_lines((parser.format_help(),)) + parser.exit(0) class _VersionAction(Action): @@ -117,7 +181,10 @@ def _build_parser() -> ArgumentParser: " cuid2 -n 5 | cuid2 --check -" ), formatter_class=RawDescriptionHelpFormatter, + add_help=False, ) + if _stdout_cannot_probe_color(sys.stdout): + _disable_parser_color(parser) parser.add_argument( "length", nargs="?", @@ -125,6 +192,14 @@ def _build_parser() -> ArgumentParser: default=None, help=_LENGTH_HELP, ) + parser.add_argument( + "-h", + "--help", + action=_HelpAction, + nargs=0, + default=SUPPRESS, + help="Show this help message and exit.", + ) parser.add_argument( "-V", "--version", @@ -205,8 +280,15 @@ def _iter_candidates(check_arg: str) -> Iterator[str]: if check_arg != "-": yield check_arg return + stdin = sys.stdin + if stdin is None: + msg = "stdin is closed" + raise ValueError(msg) + if isinstance(stdin, io.TextIOWrapper): + with suppress(io.UnsupportedOperation): + stdin.reconfigure(encoding="utf-8", errors="surrogateescape") empty = True - for line in sys.stdin: + for line in stdin: candidate = line.rstrip("\r\n") if candidate: empty = False @@ -223,18 +305,28 @@ def _run_check(check_arg: str, target_length: int | None, *, quiet: bool) -> int def _evaluate() -> Iterator[str]: nonlocal all_valid, exhausted - for candidate in _iter_candidates(check_arg): - valid = is_cuid(candidate, min_length=min_len, max_length=max_len) - all_valid = all_valid and valid - if not quiet: - # ascii() escapes control and non-ASCII characters from untrusted input. - label = ascii(candidate)[1:-1] if candidate else "" - yield f"{label}: {'valid' if valid else 'invalid'}\n" - exhausted = True - - _write_lines(_evaluate()) - # A closed stdout stops evaluation early; unchecked candidates must not count as valid. - return 0 if all_valid and exhausted else 1 + try: + for candidate in _iter_candidates(check_arg): + valid = is_cuid(candidate, min_length=min_len, max_length=max_len) + all_valid = all_valid and valid + if not quiet: + # ascii() escapes control, non-ASCII, and surrogate-escaped bytes from untrusted input. + label = ascii(candidate)[1:-1] if candidate else "" + yield f"{label}: {'valid' if valid else 'invalid'}\n" + exhausted = True + except (OSError, ValueError) as exc: + # Only a closed or unreadable stdin (None, closed file, EBADF; UnicodeDecodeError is a ValueError) + # ends evaluation early; real I/O errors such as EIO propagate. + if not _is_closed_stream_error(exc): + raise + + if quiet: + any(_evaluate()) + return 0 if all_valid and exhausted else 1 + + wrote = _write_lines(_evaluate()) + # A closed stdin or stdout stops evaluation early; unchecked or unwritten candidates must not count as valid. + return 0 if all_valid and exhausted and wrote else 1 def main(args: Sequence[str] | None = None) -> None: diff --git a/src/cuid2/generator.py b/src/cuid2/generator.py index 3167a98..7099d65 100644 --- a/src/cuid2/generator.py +++ b/src/cuid2/generator.py @@ -55,14 +55,19 @@ def __call__( _CUID_REGEX: Final[re.Pattern[str]] = re.compile(r"^[a-z][0-9a-z]+\Z") -def _validate_length(length: int) -> None: - """Validate that the requested CUID length is within supported bounds. +def _validate_length(length: int) -> int: + """Validate and normalize the requested CUID length to a built-in integer. Parameters ---------- length : int The requested CUID length to validate. + Returns + ------- + int + The validated CUID length as a built-in ``int`` in ``MIN_LENGTH``..``BIG_LENGTH``. + Raises ------ ValueError @@ -70,12 +75,14 @@ def _validate_length(length: int) -> None: TypeError If `length` is not an integer (a float, `Decimal`, `Fraction`, or string, for example). """ - if isinstance(length, bool) or operator.index(length) < MIN_LENGTH: + resolved: int = operator.index(length) + if resolved < MIN_LENGTH: msg = f"Length must be at least {MIN_LENGTH} characters." raise ValueError(msg) - if length > BIG_LENGTH: + if resolved > BIG_LENGTH: msg = f"Length must never exceed {BIG_LENGTH} characters." raise ValueError(msg) + return resolved def is_cuid(cuid_str: str, min_length: int = MIN_LENGTH, max_length: int = BIG_LENGTH) -> bool: @@ -198,12 +205,10 @@ def __init__( attributes are deep-copied, and the random generator, counter, fingerprint, and (when one is used) lock are built anew. """ - _validate_length(length) - + self._length: int = _validate_length(length) self._random_generator: Callable[[], Random] = random_generator self._counter_factory: Callable[[int], Callable[[], int]] = counter self._fingerprint_factory: FingerprintCallable = fingerprint - self._length: int = length self._state: _GeneratorState = self._create_state(previous_random=None) def __deepcopy__(self: Cuid, memo: dict[int, object]) -> Cuid: @@ -276,9 +281,7 @@ def generate(self: Cuid, length: int | None = None) -> str: TypeError If the length parameter is not an integer. """ - if length is not None: - _validate_length(length) - return self._generate(self._length if length is None else length) + return self._generate(self._length if length is None else _validate_length(length)) def _generate(self: Cuid, resolved_length: int) -> str: state: _GeneratorState = self._current_state() @@ -329,8 +332,7 @@ def create_id(length: int | None = None) -> str: If the length parameter is not an integer. """ global _default_generator # noqa: PLW0603 - if length is not None: - _validate_length(length) + resolved_length: int = DEFAULT_LENGTH if length is None else _validate_length(length) generator = _default_generator if generator is None: with _process_lock(os.getpid()): @@ -338,7 +340,7 @@ def create_id(length: int | None = None) -> str: if generator is None: generator = Cuid() _default_generator = generator - return generator._generate(DEFAULT_LENGTH if length is None else length) # noqa: SLF001 # pyright: ignore[reportPrivateUsage] + return generator._generate(resolved_length) # noqa: SLF001 # pyright: ignore[reportPrivateUsage] def cuid_wrapper(length: int = DEFAULT_LENGTH) -> Callable[[], str]: @@ -363,5 +365,4 @@ def cuid_wrapper(length: int = DEFAULT_LENGTH) -> Callable[[], str]: TypeError If the length parameter is not an integer. """ - _validate_length(length) - return partial(create_id, length=length) + return partial(create_id, length=_validate_length(length)) diff --git a/src/cuid2/utils.py b/src/cuid2/utils.py index a257218..4f78164 100644 --- a/src/cuid2/utils.py +++ b/src/cuid2/utils.py @@ -28,7 +28,6 @@ _OVERSAMPLE_BITS: Final[int] = 64 _COUNTER_DRAW_BITS: Final[int] = INITIAL_COUNT_MAX.bit_length() + _OVERSAMPLE_BITS -_LETTER_DRAW_BITS: Final[int] = ASCII_LOWERCASE_LEN.bit_length() + _OVERSAMPLE_BITS _POWERS_OF_36: Final[tuple[int, ...]] = tuple(BASE36_RADIX**i for i in range(101)) _HASH_MIN_99_DIGITS: Final[int] = _POWERS_OF_36[98] _HASH_MIN_100_DIGITS: Final[int] = _POWERS_OF_36[99] @@ -210,54 +209,6 @@ def create_entropy(random_generator: Random, length: int = 4) -> str: return _entropy_from_scaled(scaled, length) -def create_hash(data: str = "") -> str: - """Create a base36-encoded SHA3-512 hash of `data` with the leading character dropped. - - Parameters - ---------- - data : str, default="" - Data to be hashed. It is an optional parameter with a default value of an empty string. - If no value is provided for `data`, an empty string will be hashed. - - Returns - ------- - str - Base36 encoding of the SHA3-512 hash of the input string `data`, with the first character dropped. - - """ - hashed_value = sha3_512(data.encode()) - hashed_int: int = int.from_bytes(hashed_value.digest(), byteorder="big") - - # Drop the first character because it will bias the histogram to the left. - return base36_encode(hashed_int)[1:] - - -def create_letter(random_generator: Random) -> str: - """Generate a random lowercase ASCII letter using the given random number generator. - - Parameters - ---------- - random_generator : random.Random - Random number generator used to generate a random letter. Its `.getrandbits(k)` is used; a generator - without `.getrandbits(k)`, or whose class defines `.random()` but not `.getrandbits(k)` (such as a - `random.Random` subclass overriding only `.random()`), is drawn from with one `.random()` call. - - Returns - ------- - str - a randomly generated lowercase letter from the English alphabet. - """ - if _uses_random_only(random_generator): - return _letter_via_random(random_generator) - return ASCII_LOWERCASE[ - _scale_randbits( - random_generator.getrandbits(_LETTER_DRAW_BITS), - ASCII_LOWERCASE_LEN, - _LETTER_DRAW_BITS, - ) - ] - - def base36_encode(number: int) -> str: """Encode a non-negative integer into a base36 string.