shellscripts 0.23.1__tar.gz → 0.24.0__tar.gz

{shellscripts-0.23.1 → shellscripts-0.24.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: shellscripts
-Version: 0.23.1
+Version: 0.24.0
 Summary: Execute useful shell scripts via an uvx-compatible CLI interface.
 Author: Francesco Rolando
 License-Expression: GPL-3.0-only
@@ -31,7 +31,7 @@ Dynamic: license-file
 > * **No Support or Feature Requests:** Please **do not** open issues, bug reports, or feature requests. They will not be addressed or accepted at this stage of development.
 > * **No Warranty:** This software is provided **"AS IS"**, without warranty of any kind, express or implied. You may use it strictly for **testing and evaluation purposes** at your own sole risk.
 
-# s/shellScripts (0.23.1)
+# s/shellScripts (0.24.0)
 
 <p align="center">
   <img src="https://img.shields.io/badge/python-3.11%2B-3776AB?style=flat-square&logo=python&logoColor=white" alt="Python 3.11+">

{shellscripts-0.23.1 → shellscripts-0.24.0}/README.md

@@ -10,7 +10,7 @@
 > * **No Support or Feature Requests:** Please **do not** open issues, bug reports, or feature requests. They will not be addressed or accepted at this stage of development.
 > * **No Warranty:** This software is provided **"AS IS"**, without warranty of any kind, express or implied. You may use it strictly for **testing and evaluation purposes** at your own sole risk.
 
-# s/shellScripts (0.23.1)
+# s/shellScripts (0.24.0)
 
 <p align="center">
   <img src="https://img.shields.io/badge/python-3.11%2B-3776AB?style=flat-square&logo=python&logoColor=white" alt="Python 3.11+">

{shellscripts-0.23.1 → shellscripts-0.24.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "shellscripts"
-version = "0.23.1"
+version = "0.24.0"
 description = "Execute useful shell scripts via an uvx-compatible CLI interface."
 readme = "README.md"
 requires-python = ">=3.11"

{shellscripts-0.23.1 → shellscripts-0.24.0}/src/shell_scripts/__init__.py

@@ -1,4 +1,4 @@
-__version__ = "0.23.1"
+__version__ = "0.24.0"
 
 from .core import main  # noqa: F401
 

{shellscripts-0.23.1 → shellscripts-0.24.0}/src/shell_scripts/commands/pdf_split_by_format.py

@@ -1,6 +1,8 @@
 #!/usr/bin/env python3
+import errno
 import os
 import re
+import shutil
 import subprocess
 import tempfile
 
@@ -102,7 +104,48 @@ def _extract_toc_for_range(data_file, start, end):
     return "\n".join(result)
 
 
+def _promote_temp_output(temp_output, output_file):
+    """
+    @brief Promote one pdftk-produced temporary artifact onto the final output path.
+    @details Attempts same-device atomic replacement via `os.replace`. On
+      `OSError` with `errno.EXDEV` (temporary directory and output directory
+      located on different filesystems), falls back to `shutil.move`, which
+      copies the artifact content and removes the temporary source. All other
+      `OSError` values propagate unchanged to preserve pre-existing failure
+      semantics. Time complexity O(1) for same-device renames, O(n) over file
+      size for the cross-device copy fallback.
+    @param temp_output {str} Temporary artifact path produced by the external tool chain.
+    @param output_file {str} Final chunk path that must receive the artifact content.
+    @return {None} Applies destination filesystem mutation.
+    @throws {OSError} Propagated for non-EXDEV replacement failures.
+    @satisfies REQ-031, REQ-032
+    """
+    try:
+        os.replace(temp_output, output_file)
+    except OSError as error:
+        if error.errno != errno.EXDEV:
+            raise
+        shutil.move(temp_output, output_file)
+
+
 def _apply_toc(output_file, toc_content):
+    """
+    @brief Reapply in-range TOC data to one generated chunk file.
+    @details Writes `toc_content` into a temporary `.info` payload, prepares
+      temporary PDF artifacts, strips object streams from `output_file` via
+      `qpdf`, rebuilds the chunk with TOC metadata via `pdftk update_info`,
+      and promotes the artifact onto `output_file` through
+      `_promote_temp_output` so a temporary directory on a different
+      filesystem cannot silently drop the chunk TOC. Tool-chain failures are
+      contained without aborting the split loop. Time complexity O(m) over
+      TOC content size plus external process latency.
+    @param output_file {str} Generated chunk path receiving the TOC metadata.
+    @param toc_content {str} Range-filtered pdftk dump-data bookmark payload.
+    @return {None} Mutates `output_file` content on success.
+    @throws {OSError} Propagated when temporary payload creation, unlink, or
+      non-EXDEV promotion fails.
+    @satisfies REQ-032
+    """
     if not toc_content.strip():
         return
     with tempfile.NamedTemporaryFile(mode="w", suffix=".info", delete=False) as f:
@@ -124,7 +167,7 @@ def _apply_toc(output_file, toc_content):
                 capture_output=True,
             )
             if r2.returncode == 0:
-                os.replace(with_toc, output_file)
+                _promote_temp_output(with_toc, output_file)
             else:
                 os.unlink(with_toc)
                 print(f"   [!] Warning: unable to update TOC for '{output_file}'.")

{shellscripts-0.23.1 → shellscripts-0.24.0}/src/shell_scripts/commands/pdf_split_by_toc.py

@@ -1,6 +1,8 @@
 #!/usr/bin/env python3
+import errno
 import os
 import re
+import shutil
 import subprocess
 import tempfile
 
@@ -76,7 +78,48 @@ def _sanitize_title(title):
     return safe.strip("-")
 
 
+def _promote_temp_output(temp_output, output_file):
+    """
+    @brief Promote one pdftk-produced temporary artifact onto the final output path.
+    @details Attempts same-device atomic replacement via `os.replace`. On
+      `OSError` with `errno.EXDEV` (temporary directory and output directory
+      located on different filesystems), falls back to `shutil.move`, which
+      copies the artifact content and removes the temporary source. All other
+      `OSError` values propagate unchanged to preserve pre-existing failure
+      semantics. Time complexity O(1) for same-device renames, O(n) over file
+      size for the cross-device copy fallback.
+    @param temp_output {str} Temporary artifact path produced by the external tool chain.
+    @param output_file {str} Final chunk path that must receive the artifact content.
+    @return {None} Applies destination filesystem mutation.
+    @throws {OSError} Propagated for non-EXDEV replacement failures.
+    @satisfies REQ-031, REQ-032
+    """
+    try:
+        os.replace(temp_output, output_file)
+    except OSError as error:
+        if error.errno != errno.EXDEV:
+            raise
+        shutil.move(temp_output, output_file)
+
+
 def _apply_toc_to_file(output_file, toc_content):
+    """
+    @brief Reapply rebased TOC data to one generated chunk file.
+    @details Writes `toc_content` into a temporary `.info` payload, strips
+      object streams from `output_file` via `qpdf`, rebuilds the chunk with
+      TOC metadata via `pdftk update_info`, and promotes the artifact onto
+      `output_file` through `_promote_temp_output` so a temporary directory
+      on a different filesystem cannot crash chunk generation. Emits a
+      warning and keeps the original chunk when the tool chain fails.
+      Time complexity O(m) over TOC content size plus external process
+      latency.
+    @param output_file {str} Generated chunk path receiving the TOC metadata.
+    @param toc_content {str} Rebased pdftk dump-data bookmark payload.
+    @return {None} Mutates `output_file` content on success.
+    @throws {OSError} Propagated when temporary payload creation, unlink, or
+      non-EXDEV promotion fails.
+    @satisfies REQ-031
+    """
     if not toc_content.strip():
         return
     with tempfile.NamedTemporaryFile(mode="w", suffix=".info", delete=False) as f:
@@ -95,7 +138,7 @@ def _apply_toc_to_file(output_file, toc_content):
                 capture_output=True,
             )
             if r2.returncode == 0:
-                os.replace(with_toc, output_file)
+                _promote_temp_output(with_toc, output_file)
             else:
                 if os.path.exists(with_toc):
                     os.unlink(with_toc)

{shellscripts-0.23.1 → shellscripts-0.24.0}/src/shellscripts.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: shellscripts
-Version: 0.23.1
+Version: 0.24.0
 Summary: Execute useful shell scripts via an uvx-compatible CLI interface.
 Author: Francesco Rolando
 License-Expression: GPL-3.0-only
@@ -31,7 +31,7 @@ Dynamic: license-file
 > * **No Support or Feature Requests:** Please **do not** open issues, bug reports, or feature requests. They will not be addressed or accepted at this stage of development.
 > * **No Warranty:** This software is provided **"AS IS"**, without warranty of any kind, express or implied. You may use it strictly for **testing and evaluation purposes** at your own sole risk.
 
-# s/shellScripts (0.23.1)
+# s/shellScripts (0.24.0)
 
 <p align="center">
   <img src="https://img.shields.io/badge/python-3.11%2B-3776AB?style=flat-square&logo=python&logoColor=white" alt="Python 3.11+">

{shellscripts-0.23.1 → shellscripts-0.24.0}/src/shellscripts.egg-info/SOURCES.txt

@@ -56,4 +56,6 @@ tests/test_tst_010_req_cmd.py
 tests/test_tst_011_video_commands.py
 tests/test_tst_012_workflow_runtime.py
 tests/test_tst_013_release_pypi_gating.py
-tests/test_tst_014_pypi_version_source.py
+tests/test_tst_014_pypi_version_source.py
+tests/test_tst_015_pre_release_check.py
+tests/test_tst_016_release_precheck_gating.py

{shellscripts-0.23.1 → shellscripts-0.24.0}/tests/test_tst_007_pdf_commands.py

@@ -7,6 +7,7 @@
 @return {None} Pytest module scope.
 """
 
+import errno
 import pathlib
 import subprocess
 
@@ -206,6 +207,7 @@ def test_pdf_split_by_toc_runs_required_tools(monkeypatch, tmp_path):
     monkeypatch.setattr(pdf_split_by_toc, "require_commands", lambda *_cmds: None)
     monkeypatch.setattr(pdf_split_by_toc.subprocess, "run", _fake_run)
 
+    monkeypatch.chdir(tmp_path)
     result = pdf_split_by_toc.run([str(input_pdf)])
 
     assert result == 0
@@ -213,6 +215,79 @@ def test_pdf_split_by_toc_runs_required_tools(monkeypatch, tmp_path):
     assert any(cmd[0] == "pdftk" for cmd in calls)
 
 
+def test_pdf_split_by_toc_promotes_output_across_devices(monkeypatch, tmp_path):
+    """
+    @brief Validate cross-device temp-output promotion in pdf-split-by-toc.
+    @details Simulates `os.replace` failing with `errno.EXDEV` (system temp
+      directory located on a different filesystem than the working directory)
+      and asserts the generated chunk still receives the pdftk-produced
+      artifact through the copy-based fallback instead of crashing.
+    @param monkeypatch {pytest.MonkeyPatch} Runtime patch helper.
+    @param tmp_path {pathlib.Path} Isolated filesystem fixture.
+    @return {None} Assertions only.
+    @satisfies TST-007, REQ-031
+    """
+
+    input_pdf = tmp_path / "book.pdf"
+    input_pdf.write_text("dummy")
+    toc_artifact = (
+        "NumberOfPages: 3\n"
+        "BookmarkBegin\n"
+        "BookmarkTitle: Intro\n"
+        "BookmarkLevel: 1\n"
+        "BookmarkPageNumber: 1\n"
+        "BookmarkBegin\n"
+        "BookmarkTitle: End\n"
+        "BookmarkLevel: 1\n"
+        "BookmarkPageNumber: 3\n"
+    )
+
+    def _fake_run(command, **kwargs):
+        """
+        @brief Mock subprocess.run for pdf-split-by-toc.
+        @details Captures invocation list and writes the deterministic TOC
+          artifact to every pdftk output target so the promotion result stays
+          observable.
+        @param command {list[str]} Command token vector.
+        @param kwargs {dict[str, object]} Execution options.
+        @return {subprocess.CompletedProcess[str]} Successful completion object.
+        """
+
+        del kwargs
+        if command[0] == "pdftk" and "output" in command:
+            output_path = command[command.index("output") + 1]
+            with open(output_path, "w", encoding="utf-8") as handle:
+                handle.write(toc_artifact)
+        return subprocess.CompletedProcess(command, 0, stdout="", stderr="")
+
+    def _raise_exdev(source, destination):
+        """
+        @brief Simulate cross-device rename rejection.
+        @details Replaces `os.replace` with the exact `OSError` raised by the
+          operating system when source and destination live on different
+          filesystems, keeping the reproducer independent from the host
+          mount layout.
+        @param source {str} Source path token.
+        @param destination {str} Destination path token.
+        @return {None} Never returns normally.
+        @throws {OSError} Always raises with `errno.EXDEV`.
+        """
+
+        del source, destination
+        raise OSError(errno.EXDEV, "Invalid cross-device link")
+
+    monkeypatch.setattr(pdf_split_by_toc, "require_commands", lambda *_cmds: None)
+    monkeypatch.setattr(pdf_split_by_toc.subprocess, "run", _fake_run)
+    monkeypatch.setattr(pdf_split_by_toc.os, "replace", _raise_exdev)
+
+    monkeypatch.chdir(tmp_path)
+    result = pdf_split_by_toc.run([str(input_pdf)])
+
+    chunk = input_pdf.parent / "book_01_Intro.pdf"
+    assert result == 0
+    assert chunk.read_text(encoding="utf-8") == toc_artifact
+
+
 def test_pdf_split_by_format_runs_required_tools(monkeypatch, tmp_path):
     """
     @brief Validate pdf-split-by-format command sequence.
@@ -251,12 +326,93 @@ def test_pdf_split_by_format_runs_required_tools(monkeypatch, tmp_path):
     monkeypatch.setattr(pdf_split_by_format, "_has_toc", lambda _pdf: False)
     monkeypatch.setattr(pdf_split_by_format.subprocess, "run", _fake_run)
 
+    monkeypatch.chdir(tmp_path)
     result = pdf_split_by_format.run([str(input_pdf)])
 
     assert result == 0
     assert any(cmd[0] == "qpdf" for cmd in calls)
 
 
+def test_pdf_split_by_format_promotes_output_across_devices(monkeypatch, tmp_path):
+    """
+    @brief Validate cross-device temp-output promotion in pdf-split-by-format.
+    @details Simulates `os.replace` failing with `errno.EXDEV` while TOC data
+      is available and asserts the generated chunk still receives the
+      pdftk-produced artifact through the copy-based fallback instead of
+      silently losing its table of contents.
+    @param monkeypatch {pytest.MonkeyPatch} Runtime patch helper.
+    @param tmp_path {pathlib.Path} Isolated filesystem fixture.
+    @return {None} Assertions only.
+    @satisfies TST-007, REQ-032
+    """
+
+    input_pdf = tmp_path / "formats.pdf"
+    input_pdf.write_text("dummy")
+    toc_artifact = (
+        "NumberOfPages: 3\n"
+        "BookmarkBegin\n"
+        "BookmarkTitle: Intro\n"
+        "BookmarkLevel: 1\n"
+        "BookmarkPageNumber: 1\n"
+        "BookmarkBegin\n"
+        "BookmarkTitle: End\n"
+        "BookmarkLevel: 1\n"
+        "BookmarkPageNumber: 3\n"
+    )
+
+    def _fake_run(command, **kwargs):
+        """
+        @brief Mock subprocess.run for pdf-split-by-format.
+        @details Captures invocation list and writes the deterministic TOC
+          artifact to every pdftk output target (dump-data file and
+          update-info output) so the promotion result stays observable.
+        @param command {list[str]} Command token vector.
+        @param kwargs {dict[str, object]} Execution options.
+        @return {subprocess.CompletedProcess[str]} Successful completion object.
+        """
+
+        del kwargs
+        if command[0] == "pdftk" and "output" in command:
+            output_path = command[command.index("output") + 1]
+            with open(output_path, "w", encoding="utf-8") as handle:
+                handle.write(toc_artifact)
+        return subprocess.CompletedProcess(command, 0, stdout="", stderr="")
+
+    def _raise_exdev(source, destination):
+        """
+        @brief Simulate cross-device rename rejection.
+        @details Replaces `os.replace` with the exact `OSError` raised by the
+          operating system when source and destination live on different
+          filesystems, keeping the reproducer independent from the host
+          mount layout.
+        @param source {str} Source path token.
+        @param destination {str} Destination path token.
+        @return {None} Never returns normally.
+        @throws {OSError} Always raises with `errno.EXDEV`.
+        """
+
+        del source, destination
+        raise OSError(errno.EXDEV, "Invalid cross-device link")
+
+    monkeypatch.setattr(pdf_split_by_format, "require_commands", lambda *_cmds: None)
+    monkeypatch.setattr(pdf_split_by_format, "_get_total_pages", lambda _pdf: 3)
+    monkeypatch.setattr(
+        pdf_split_by_format,
+        "_get_page_formats",
+        lambda _pdf, _pages: ["A4", "A4", "A3"],
+    )
+    monkeypatch.setattr(pdf_split_by_format, "_has_toc", lambda _pdf: True)
+    monkeypatch.setattr(pdf_split_by_format.subprocess, "run", _fake_run)
+    monkeypatch.setattr(pdf_split_by_format.os, "replace", _raise_exdev)
+
+    monkeypatch.chdir(tmp_path)
+    result = pdf_split_by_format.run([str(input_pdf)])
+
+    chunk = input_pdf.parent / "formats_01.pdf"
+    assert result == 0
+    assert chunk.read_text(encoding="utf-8") == toc_artifact
+
+
 def test_pdf_toc_clean_generates_toc_clean_filename(monkeypatch, tmp_path):
     """
     @brief Validate pdf-toc-clean output naming and tool sequence.

shellscripts-0.24.0/tests/test_tst_015_pre_release_check.py

@@ -0,0 +1,149 @@
+"""
+@brief Validate pre-release check script mandatory structure and syntax.
+@details Parses `scripts/pre-release-check.sh` and asserts repository-root
+  resolution, pytest invocation with `PYTHONPATH=src` and `.venv` fallback,
+  `dist` cleanup, `uv build`/`python3 -m build` fallback, sdist and wheel
+  artifact gates, fail-fast exit semantics, and `PASS`/`FAIL` evidence-line
+  format. Validates Bash syntax via `bash -n` without executing the release
+  pipeline.
+@satisfies TST-015, DES-021, DES-022, DES-023, DES-024, DES-025, DES-026,
+  DES-027, REQ-079, REQ-080, REQ-081, REQ-082
+@return {None} Pytest module scope.
+"""
+
+import pathlib
+import subprocess
+
+SCRIPT_PATH = pathlib.Path(__file__).resolve().parents[1] / "scripts" / "pre-release-check.sh"
+
+
+def _read_script() -> str:
+    """
+    @brief Load the pre-release check script content.
+    @details Reads the script file as UTF-8 text for token-level structural
+      assertions. Time complexity O(n) over script size.
+    @return {str} Full script content.
+    @throws {OSError} When the script file cannot be read.
+    """
+
+    return SCRIPT_PATH.read_text(encoding="utf-8")
+
+
+def test_pre_release_script_exists_and_is_non_empty():
+    """
+    @brief Validate pre-release script presence at the required path.
+    @details Asserts the script file exists at `scripts/pre-release-check.sh`
+      and contains non-empty content, proving the mandatory pipeline
+      entrypoint is implemented.
+    @return {None} Assertions only.
+    @satisfies TST-015, DES-021
+    """
+
+    assert SCRIPT_PATH.is_file()
+    assert _read_script().strip()
+
+
+def test_pre_release_script_passes_bash_syntax_check():
+    """
+    @brief Validate Bash syntax of the pre-release script.
+    @details Executes `bash -n` against the script and passes only when the
+      parser reports no syntax errors and a zero exit status.
+    @return {None} Assertions only.
+    @satisfies TST-015, DES-021
+    """
+
+    result = subprocess.run(
+        ["bash", "-n", str(SCRIPT_PATH)],
+        capture_output=True,
+        text=True,
+    )
+    assert result.returncode == 0, result.stderr
+
+
+def test_pre_release_script_resolves_repository_root():
+    """
+    @brief Validate repository-root resolution and execution directory.
+    @details Asserts the script resolves the Git repository root via
+      `git rev-parse --show-toplevel` and executes all checks from that root
+      via an explicit working-directory change.
+    @return {None} Assertions only.
+    @satisfies TST-015, DES-022
+    """
+
+    content = _read_script()
+    assert "rev-parse --show-toplevel" in content
+    assert 'cd -- "${PROJECT_ROOT}"' in content
+
+
+def test_pre_release_script_runs_pytest_with_src_pythonpath():
+    """
+    @brief Validate mandatory unit-test check invocation.
+    @details Asserts the script runs pytest against `tests/`, prepends the
+      project `src` directory to `PYTHONPATH`, and selects the interpreter
+      via the `.venv/bin/python3`-when-present fallback to `python3`.
+    @return {None} Assertions only.
+    @satisfies TST-015, DES-023
+    """
+
+    content = _read_script()
+    assert "PYTHONPATH=" in content
+    assert "${PWD}/src" in content
+    assert "-m pytest tests/" in content
+    assert ".venv/bin/python3" in content
+
+
+def test_pre_release_script_builds_and_verifies_artifacts():
+    """
+    @brief Validate mandatory build and artifact verification checks.
+    @details Asserts the script removes the preexisting `dist` directory,
+      builds via `uv build` with `python3 -m build` fallback, and gates the
+      pipeline on at least one sdist and one wheel artifact in `dist`.
+    @return {None} Assertions only.
+    @satisfies TST-015, DES-024, DES-025
+    """
+
+    content = _read_script()
+    assert "rm -rf -- dist" in content
+    assert "uv build" in content
+    assert "python3 -m build" in content
+    assert 'compgen -G "dist/*.tar.gz"' in content
+    assert 'compgen -G "dist/*.whl"' in content
+
+
+def test_pre_release_script_enforces_fail_fast_and_evidence_lines():
+    """
+    @brief Validate fail-fast semantics and evidence-line format.
+    @details Asserts the script prints `PASS:` and `FAIL:` evidence lines,
+      aborts with exit code `1` naming the first failed check, and exits `0`
+      only through the all-checks-passed summary path.
+    @return {None} Assertions only.
+    @satisfies TST-015, REQ-079, REQ-080
+    """
+
+    content = _read_script()
+    assert "PASS: " in content
+    assert "FAIL: " in content
+    assert "exit 1" in content
+    assert "exit 0" in content
+    assert "Pre-release check FAILED at check: " in content
+    assert "Pre-release check PASSED" in content
+
+
+def test_pre_release_script_cleans_generated_artifacts():
+    """
+    @brief Validate generated-artifact cleanup registration.
+    @details Asserts the script defines `cleanup_artifacts`, registers it as
+      an EXIT trap so success and failure paths both clean up, removes
+      `dist`, `build`, `.pytest_cache`, `src/shellscripts.egg-info`, and
+      `__pycache__` directories under `src` and `tests`, and prints a
+      `clean` evidence line listing the removed artifact groups.
+    @return {None} Assertions only.
+    @satisfies TST-015, DES-026, DES-027, REQ-081, REQ-082
+    """
+
+    content = _read_script()
+    assert "cleanup_artifacts" in content
+    assert "trap cleanup_artifacts EXIT" in content
+    assert "rm -rf -- dist build .pytest_cache src/shellscripts.egg-info" in content
+    assert "find src tests -type d -name __pycache__" in content
+    assert "clean: dist build .pytest_cache src/shellscripts.egg-info __pycache__" in content

shellscripts-0.24.0/tests/test_tst_016_release_precheck_gating.py

@@ -0,0 +1,151 @@
+"""
+@brief Validate release workflow pre-release verification gating contract.
+@details Parses the repository workflow artifact
+  `.github/workflows/release-pypi.yml` as static text and verifies that a
+  dedicated `pre-release-check` job executes `scripts/pre-release-check.sh`
+  before release artifact creation and that the `build-release` job declares
+  `needs` on it, so any verification failure prevents artifact creation,
+  attestation, changelog, GitHub release, and PyPI publication (DES-028,
+  DES-029, REQ-083).
+  Level classification: all helpers are Level 0 (pure text parsing over a
+  tracked static artifact); test functions are Level 1 consumers with no
+  cross-test dependencies and no network, filesystem side effects, clock,
+  or randomness exposure.
+@satisfies TST-016, DES-028, DES-029, REQ-083
+@return {None} Pytest module scope.
+"""
+
+from pathlib import Path
+
+# @var WORKFLOW_PATH {Path} Absolute path of the release workflow artifact under verification; resolved from this test file location to remain working-directory independent.
+WORKFLOW_PATH = (
+    Path(__file__).resolve().parents[1] / ".github" / "workflows" / "release-pypi.yml"
+)
+
+# @var PRECHECK_JOB_HEADER {str} Exact two-space-indented job header declaring the dedicated pre-release verification job (DES-028).
+PRECHECK_JOB_HEADER = "  pre-release-check:"
+
+# @var PRECHECK_SCRIPT_COMMAND {str} Runner line that must execute the mandatory pre-release pipeline inside the dedicated job (DES-028).
+PRECHECK_SCRIPT_COMMAND = "run: bash scripts/pre-release-check.sh"
+
+# @var PRECHECK_SYNC_COMMAND {str} Runner line that provisions the project virtual environment with dev dependencies before script execution (DES-028).
+PRECHECK_SYNC_COMMAND = "run: uv sync --frozen"
+
+# @var BUILD_RELEASE_NEEDS_LINE {str} Exact `needs` declaration that gates the release build job on the pre-release verification job (DES-029, REQ-083).
+BUILD_RELEASE_NEEDS_LINE = "needs: [check-branch, pre-release-check]"
+
+# @var FORBIDDEN_PUBLISH_ACTIONS {tuple[str, ...]} Release/publication action slugs that MUST NOT appear inside the pre-release verification job.
+FORBIDDEN_PUBLISH_ACTIONS = (
+    "pypa/gh-action-pypi-publish",
+    "softprops/action-gh-release",
+    "actions/attest-build-provenance",
+)
+
+
+def _read_workflow_text() -> str:
+    """
+    @brief Read the release workflow artifact as decoded UTF-8 text.
+    @details Performs a single read of the tracked workflow file referenced by
+      `WORKFLOW_PATH`; no writes, network, or environment access. Time
+      complexity O(n) where n is the file byte size.
+    @pre Workflow artifact exists at `WORKFLOW_PATH`.
+    @return {str} Full workflow file content.
+    @throws {OSError} When the workflow artifact is missing or unreadable.
+    @satisfies TST-016
+    """
+    return WORKFLOW_PATH.read_text(encoding="utf-8")
+
+
+def _extract_job_block(workflow_text: str, job_name: str) -> str:
+    """
+    @brief Extract one job definition block from workflow text.
+    @details Slices from the two-space-indented `job_name:` header until the
+      next two-space-indented job header or document end. Time complexity
+      O(n) over payload length.
+    @param workflow_text {str} Full workflow file content.
+    @param job_name {str} Job key to extract.
+    @return {str} Job block text.
+    @throws {AssertionError} When the job key is absent.
+    @satisfies TST-016
+    """
+    lines = workflow_text.splitlines()
+    start_index = None
+    for index, line in enumerate(lines):
+        if line == f"  {job_name}:":
+            start_index = index
+            break
+    assert start_index is not None, f"missing job definition: {job_name}"
+
+    end_index = len(lines)
+    for index in range(start_index + 1, len(lines)):
+        line = lines[index]
+        if line.startswith("  ") and not line.startswith("   ") and line.endswith(":"):
+            end_index = index
+            break
+    return "\n".join(lines[start_index:end_index])
+
+
+def test_release_workflow_declares_pre_release_check_job():
+    """
+    @brief Verify the dedicated pre-release verification job exists and runs
+      the mandatory pipeline before artifact creation.
+    @details Asserts the `pre-release-check` job is declared before the
+      `build-release` job, provisions dependencies with `uv sync --frozen`,
+      and executes `scripts/pre-release-check.sh` as a runner step.
+    @return {None} Assertions only.
+    @satisfies TST-016, DES-028
+    """
+    workflow_text = _read_workflow_text()
+
+    assert PRECHECK_JOB_HEADER in workflow_text, (
+        "dedicated pre-release-check job missing from release workflow"
+    )
+    assert workflow_text.index(PRECHECK_JOB_HEADER) < workflow_text.index(
+        "  build-release:"
+    ), "pre-release-check job must be declared before build-release"
+
+    precheck_block = _extract_job_block(workflow_text, "pre-release-check")
+    assert PRECHECK_SYNC_COMMAND in precheck_block, (
+        "pre-release-check job must provision the virtual environment with uv sync"
+    )
+    assert PRECHECK_SCRIPT_COMMAND in precheck_block, (
+        "pre-release-check job must execute scripts/pre-release-check.sh"
+    )
+
+
+def test_release_workflow_build_release_needs_pre_release_check():
+    """
+    @brief Verify the build-release job declares needs on the pre-release job.
+    @details Asserts the exact `needs` list on `build-release` contains both
+      `check-branch` and `pre-release-check`, which is the GitHub Actions
+      mechanism that skips every artifact-creation and publication step when
+      verification fails.
+    @return {None} Assertions only.
+    @satisfies TST-016, DES-029, REQ-083
+    """
+    workflow_text = _read_workflow_text()
+    build_release_block = _extract_job_block(workflow_text, "build-release")
+
+    assert BUILD_RELEASE_NEEDS_LINE in build_release_block, (
+        "build-release job must gate on [check-branch, pre-release-check]"
+    )
+
+
+def test_pre_release_job_does_not_publish_or_create_release_assets():
+    """
+    @brief Verify the pre-release job stays verification-only.
+    @details Negative/regression guard: the dedicated verification job must
+      not contain PyPI publication, GitHub release, or provenance attestation
+      actions, keeping all release-side effects exclusively inside the gated
+      `build-release` job.
+    @return {None} Assertions only.
+    @satisfies TST-016, REQ-083
+    """
+    workflow_text = _read_workflow_text()
+    precheck_block = _extract_job_block(workflow_text, "pre-release-check")
+
+    for forbidden_action in FORBIDDEN_PUBLISH_ACTIONS:
+        assert forbidden_action not in precheck_block, (
+            f"verification job must not perform release-side effects: "
+            f"{forbidden_action}"
+        )