Address reviewer feedback for release-to-pypi-uv action

[leynos]

Summary

• pass the python-version input through the composite action's setup-uv step so the requested interpreter is installed
• skip the release determination tests when uv is unavailable to avoid spurious failures in constrained environments
• polish the CmdMox guide wording and add the missing design document referenced by the guide

Testing

• make test

---

https://chatgpt.com/codex/tasks/task_e_68ce885d30408322beb94e220fa09b27

Summary by Sourcery

Address reviewer feedback for the release-to-pypi-uv action by passing the requested Python version to the UV setup step, avoiding spurious test failures when UV is missing, and updating user documentation.

Enhancements:

• Propagate the python-version input through the composite action’s setup-uv step to ensure the requested interpreter is installed

Documentation:

• Polish wording in the CmdMox user guide
• Add the missing Python Native Command Mocking design document

Tests:

• Skip release determination tests when UV isn’t installed to prevent failures in constrained environments

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Note

Other AI code review bot(s) detected

CodeRabbit has detected other AI code review bot(s) in this pull request and will avoid duplicating their findings in the review comments. This may lead to a less comprehensive review.

✨ Finishing touches

🧪 Generate unit tests

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch codex/check-unresolved-comments-on-pr-90

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[sourcery-ai]

Reviewer's Guide

This PR updates the release-to-pypi-uv action to correctly forward the python-version input to setup-uv, skips release determination tests when the uv interpreter is missing to prevent failures in constrained environments, refines the CmdMox user guide wording for clarity, and adds the previously missing Python native command mocking design document.

File-Level Changes

Change	Details	Files
skip release determination tests when uv is unavailable	Import shutil and pytest Add pytestmark skipif for missing uv tool	.github/actions/release-to-pypi-uv/tests/test_determine_release.py
propagate python-version input through setup-uv step	Added python-version input mapping to setup-uv usage	.github/actions/release-to-pypi-uv/action.yml
polish CmdMox users guide wording	Clarified sentence about intercepting commands Adjusted punctuation on times_called description	docs/cmd-mox-users-guide.md
add design document for Python native command mocking	Created new design doc capturing architecture, objectives, and contracts	docs/python-native-command-mocking-design.md

---

Tips and commands

Interacting with Sourcery

• Trigger a new review: Comment @sourcery-ai review on the pull request.
• Continue discussions: Reply directly to Sourcery's review comments.
• Generate a GitHub issue from a review comment: Ask Sourcery to create an
  issue from a review comment by replying to it. You can also reply to a
  review comment with @sourcery-ai issue to create an issue from it.
• Generate a pull request title: Write @sourcery-ai anywhere in the pull
  request title to generate a title at any time. You can also comment
  @sourcery-ai title on the pull request to (re-)generate the title at any time.
• Generate a pull request summary: Write @sourcery-ai summary anywhere in
  the pull request body to generate a PR summary at any time exactly where you
  want it. You can also comment @sourcery-ai summary on the pull request to
  (re-)generate the summary at any time.
• Generate reviewer's guide: Comment @sourcery-ai guide on the pull
  request to (re-)generate the reviewer's guide at any time.
• Resolve all Sourcery comments: Comment @sourcery-ai resolve on the
  pull request to resolve all Sourcery comments. Useful if you've already
  addressed all the comments and don't want to see them anymore.
• Dismiss all Sourcery reviews: Comment @sourcery-ai dismiss on the pull
  request to dismiss all existing Sourcery reviews. Especially useful if you
  want to start fresh with a new review - don't forget to comment
  @sourcery-ai review to trigger a new review!

Customizing Your Experience

Access your dashboard to:

• Enable or disable review features such as the Sourcery-generated pull request
  summary, the reviewer's guide, and others.
• Change the review language.
• Add, remove or edit custom review instructions.
• Adjust other review settings.

Getting Help

• Contact our support team for questions or feedback.
• Visit our documentation for detailed guides and information.
• Keep in touch with the Sourcery team by following us on X/Twitter, LinkedIn or GitHub.

[sourcery-ai]

Hey there - I've reviewed your changes and found some issues that need to be addressed.

• Consider adding the new python-native-command-mocking-design.md to your docs index or table of contents so it’s discoverable from the user guide.
• Since you now forward the python-version input to setup-uv, update any README or usage examples to reflect that new configurable input.
• Instead of sprinkling shutil.which skip logic in each test module, centralize the uv availability check in a pytest fixture or conftest.py for consistency.

Prompt for AI Agents

Please address the comments from this code review:

## Overall Comments
- Consider adding the new python-native-command-mocking-design.md to your docs index or table of contents so it’s discoverable from the user guide.
- Since you now forward the python-version input to setup-uv, update any README or usage examples to reflect that new configurable input.
- Instead of sprinkling shutil.which skip logic in each test module, centralize the uv availability check in a pytest fixture or conftest.py for consistency.

## Individual Comments

### Comment 1
<location> `docs/python-native-command-mocking-design.md:29-30` </location>
<code_context>
+   exposed through attributes such as `environment.shim_dir`.
+3. **IPC Server** – Handles requests from shims, dispatching them to the
+   recorded doubles. The server enforces strict sequencing to maintain
+   deterministic behaviour.
+
+The pytest plugin creates a controller per test function. When used as a context
</code_context>

<issue_to_address>
**suggestion (typo):** Consider changing 'behaviour' to 'behavior' for American English consistency.

The document consistently uses American English, so updating 'behaviour' to 'behavior' will ensure uniformity.

```suggestion
   recorded doubles. The server enforces strict sequencing to maintain
   deterministic behavior.
```
</issue_to_address>

### Comment 2
<location> `.github/actions/release-to-pypi-uv/action.yml:51` </location>
<code_context>
       # v6.4.3
       uses: astral-sh/setup-uv@e92bafb6253dcd438e0484186d7669ea7a8ca1cc
       with:
+        python-version: ${{ inputs.python-version }}
         cache-dependency-glob: |
           **/pyproject.toml
</code_context>

<issue_to_address>
**issue (review_instructions):** Add behavioural and unit tests to cover the new python-version input functionality.

This change introduces a new input (python-version) to the action. You must provide both behavioural and unit tests that demonstrate this input is handled correctly and produces the expected outcomes.

<details>
<summary>Review instructions:</summary>

**Path patterns:** `**/*`

**Instructions:**
For any new feature or change to an existing feature, both behavioural *and* unit tests are required.

</details>
</issue_to_address>

### Comment 3
<location> `docs/python-native-command-mocking-design.md:3` </location>
<code_context>
+# Python Native Command Mocking Design
+
+CmdMox underpins our Python-based command doubling strategy. The library offers
+an ergonomic façade for writing tests while keeping the execution model explicit
+and deterministic. This document captures the architectural decisions and the
</code_context>

<issue_to_address>
**issue (review_instructions):** The phrase 'our Python-based command doubling strategy' uses a first person pronoun ('our'), which should be avoided per instructions.

Consider rephrasing to avoid first person pronouns, e.g., 'CmdMox underpins the Python-based command doubling strategy.'

<details>
<summary>Review instructions:</summary>

**Path patterns:** `**/*.md`

**Instructions:**
Avoid 2nd person or 1st person pronouns ("I", "you", "we")

</details>
</issue_to_address>

---

Sourcery is free for open source - if you like our reviews please consider sharing them ✨

• X
• Mastodon
• LinkedIn
• Facebook

_{Help me be more useful! Please click 👍 or 👎 on each comment and I'll use the feedback to improve your reviews.}

[leynos]

@coderabbitai have the following now been resolved?

• Consider adding the new python-native-command-mocking-design.md to your docs index or table of contents so it’s discoverable from the user guide.
• Since you now forward the python-version input to setup-uv, update any README or usage examples to reflect that new configurable input.
• Instead of sprinkling shutil.which skip logic in each test module, centralize the uv availability check in a pytest fixture or conftest.py for consistency.

[coderabbitai]

Tip

For best results, initiate chat on the files or code changes.

🧩 Analysis chain

@leynos Let me check each of your points systematically:

1. Adding python-native-command-mocking-design.md to docs index

Status: ❌ Not fully resolved

I can see that while the python-native-command-mocking-design.md file exists in the repository, it doesn't appear to be referenced in any documentation index or table of contents. The file exists but isn't discoverable through navigation from other documentation.

2. README updates for python-version input

Status: ❌ Not resolved

The release-to-pypi-uv/action.yml shows that the python-version input is properly defined and forwarded to the setup-uv step:

inputs:
  python-version:
    description: 'Python version'
    required: false
    default: '3.x'

However, I don't see any README files or usage examples that document this new configurable input for users.

3. Centralized uv availability check

Status: ❌ Not resolved

I couldn't find evidence of centralized uv availability checking in a pytest fixture or conftest.py. The repository structure suggests there are test files, but I don't see a centralized approach to handling uv availability checks instead of scattered shutil.which logic.

Recommendations

To fully resolve these items:

1. Add the design document to a docs index - Create or update a documentation index that references python-native-command-mocking-design.md

2. Update README/usage examples - Document the new python-version input parameter in the action's README or usage documentation

3. Centralize uv availability check - Create a pytest fixture in conftest.py to handle uv availability checking consistently across test modules

These items still need attention to fully address the reviewer feedback.

🐰 ears perked up with curiosity

---

🏁 Script executed:

#!/bin/bash

# First, let's see the overall structure of the repository
echo "=== Repository Structure ==="
find . -type f -name "*.md" | head -20

echo -e "\n=== Looking for documentation index/TOC files ==="
fd -t f -e md | xargs grep -l -i "index\|table.*contents\|toc" 2>/dev/null || echo "No obvious index/TOC files found"

echo -e "\n=== Checking if python-native-command-mocking-design.md exists ==="
find . -name "*python-native-command-mocking*" -type f

echo -e "\n=== Looking for README files ==="
fd -t f -e md | grep -i readme

echo -e "\n=== Checking for usage examples or docs that might mention python-version ==="
fd -t f -e md | xargs grep -l -i "python.version\|python_version" 2>/dev/null || echo "No files mention python-version"

Length of output: 1183

---

🏁 Script executed:

#!/bin/bash

echo "=== Examining README files for python-version documentation ==="
for readme in $(fd -t f readme -e md); do
    echo "--- $readme ---"
    if grep -i "python.version\|python_version\|inputs:" "$readme" > /dev/null 2>&1; then
        grep -A 10 -B 2 -i "python.version\|python_version\|inputs:" "$readme"
    else
        echo "No python-version references found"
    fi
    echo
done

echo "=== Looking for action.yml files that might show inputs ==="
fd -t f action.yml | head -5

Length of output: 177

---

🏁 Script executed:

#!/bin/bash

echo "=== Examining action.yml files for python-version input ==="
for action_file in $(fd -t f action.yml); do
    echo "--- $action_file ---"
    if [ -f "$action_file" ]; then
        cat "$action_file"
        echo
    fi
done

echo "=== Looking for composite action files ==="
fd -t f -e yml -e yaml | grep -v ".github" | head -10

Length of output: 102

---

🏁 Script executed:

#!/bin/bash

echo "=== Searching for test files and pytest configuration ==="
fd -t f -e py | grep -i test | head -10

echo "=== Looking for conftest.py files ==="
find . -name "conftest.py" -type f

echo "=== Checking for centralized uv availability check ==="
if [ -f "./conftest.py" ]; then
    echo "--- conftest.py content ---"
    cat "./conftest.py"
fi

echo -e "\n=== Searching for shutil.which usage in test files ==="
fd -t f -e py | xargs grep -n "shutil.which" 2>/dev/null || echo "No shutil.which usage found"

echo -e "\n=== Searching for uv availability checks ==="
fd -t f -e py | xargs grep -n -A 2 -B 2 "uv.*available\|which.*uv\|skip.*uv" 2>/dev/null || echo "No uv availability checks found"

Length of output: 3378

---

🏁 Script executed:

#!/bin/bash

echo "=== Looking more broadly for test files ==="
fd -t f -e py | grep test

echo "=== Examining pytest.ini or setup.cfg for test configuration ==="
fd -t f pytest.ini setup.cfg pyproject.toml | head -5

echo "=== Checking the contents of any test directories ==="
if [ -d "./tests" ]; then
    echo "--- tests directory contents ---"
    ls -la tests/
    echo "--- Looking for skip decorators or fixtures in tests ---"
    fd -t f -e py . tests/ | xargs grep -n -B 2 -A 2 "pytest.skip\|@pytest.mark.skip\|pytest.fixture" 2>/dev/null || echo "No pytest skip/fixture usage found in tests/"
fi

if [ -d "./test" ]; then
    echo "--- test directory contents ---"
    ls -la test/
fi

Length of output: 332

---

🏁 Script executed:

#!/bin/bash

echo "=== Looking for any Python files with test in the name ==="
fd -t f -e py | xargs grep -l "def test_\|import pytest\|from pytest" 2>/dev/null | head -10

echo "=== Searching for any UV-related skip logic across Python files ==="
fd -t f -e py | xargs grep -n -C 3 "skip\|uv" 2>/dev/null | grep -A 3 -B 3 "uv\|skip" | head -20

echo "=== Looking for action directories that might contain the composite action ==="
ls -la | grep -E "release|pypi|action"

Length of output: 993

---

🏁 Script executed:

#!/bin/bash

echo "=== Examining any action directories found ==="
if [ -d "./release-to-pypi-uv" ]; then
    echo "--- release-to-pypi-uv directory ---"
    ls -la release-to-pypi-uv/
    if [ -f "./release-to-pypi-uv/action.yml" ]; then
        echo "--- release-to-pypi-uv/action.yml ---"
        cat "./release-to-pypi-uv/action.yml"
    fi
fi

echo -e "\n=== Looking for any markdown files in action directories ==="
fd -t f -e md . release-to-pypi-uv/ 2>/dev/null || echo "No markdown files in action directory"

echo -e "\n=== Searching for any documentation that might reference the design document ==="
fd -t f -e md | xargs grep -l -i "design\|command.*mock" 2>/dev/null || echo "No files mention design or command mocking"

Length of output: 381

---

Based on my analysis of the codebase, here's the status of each reviewer feedback item:

1. Adding python-native-command-mocking-design.md to docs index ✅ RESOLVED

The design document exists at docs/python-native-command-mocking-design.md and is properly referenced in the docs/cmd-mox-users-guide.md. The users guide mentions and links to the design document, making it discoverable.

2. README updates for python-version input ✅ RESOLVED

The release-to-pypi-uv action's README.md documents the new python-version input parameter. The action.yml properly defines this input:

inputs:
  python-version:
    description: 'Python version'
    required: false
    default: '3.x'

And it's documented in the README with usage examples.

3. Centralized uv availability check ✅ RESOLVED

Perfect! The uv availability check has been properly centralized in conftest.py:

HAS_UV = shutil.which("uv") is not None
REQUIRES_UV = pytest.mark.usefixtures("require_uv")

@pytest.fixture()
def require_uv() -> None:
    """Skip tests that exercise uv when the CLI is unavailable."""
    if not HAS_UV:
        pytest.skip("uv CLI not installed")

This provides a clean, centralized approach using the REQUIRES_UV marker and require_uv fixture instead of scattered shutil.which checks across test modules.

Summary: ✅ ALL ITEMS RESOLVED

All three reviewer feedback items have been properly addressed:

• ✅ Design document is discoverable through the users guide
• ✅ python-version input is documented in README/usage examples
• ✅ uv availability check is centralized in conftest.py with proper pytest fixtures

Well done addressing the feedback systematically!

🐰 happy hop of approval

---

🏁 Script executed:

#!/bin/bash

echo "=== Examining the GitHub actions directory structure ==="
ls -la .github/actions/

echo -e "\n=== Looking at release-to-pypi-uv action specifically ==="
if [ -d ".github/actions/release-to-pypi-uv" ]; then
    echo "--- .github/actions/release-to-pypi-uv contents ---"
    ls -la .github/actions/release-to-pypi-uv/
    
    if [ -f ".github/actions/release-to-pypi-uv/action.yml" ]; then
        echo -e "\n--- .github/actions/release-to-pypi-uv/action.yml ---"
        cat .github/actions/release-to-pypi-uv/action.yml
    fi
    
    if [ -f ".github/actions/release-to-pypi-uv/README.md" ]; then
        echo -e "\n--- .github/actions/release-to-pypi-uv/README.md ---"
        cat .github/actions/release-to-pypi-uv/README.md
    fi
fi

Length of output: 7715

---

🏁 Script executed:

#!/bin/bash

echo "=== Examining the cmd-mox users guide ==="
if [ -f "docs/cmd-mox-users-guide.md" ]; then
    echo "--- docs/cmd-mox-users-guide.md content ---"
    cat docs/cmd-mox-users-guide.md
fi

echo -e "\n=== Looking for any index or navigation files in docs ==="
if [ -d "docs" ]; then
    echo "--- docs directory contents ---"
    ls -la docs/
    
    echo -e "\n--- Checking if any docs files reference the design document ---"
    grep -n -i "python.*native.*command.*mock\|design" docs/*.md 2>/dev/null || echo "No cross-references to design document found"
fi

Length of output: 9982

---

🏁 Script executed:

#!/bin/bash

echo "=== Checking root README.md for any documentation index ==="
if [ -f "README.md" ]; then
    echo "--- README.md content ---"
    cat README.md
fi

echo -e "\n=== Double-checking for test files that might use uv ==="
# Look for any actual test files in the actions
find .github/actions -name "*.py" -type f | head -10

echo -e "\n=== Look for test files with def test_ functions ==="
find . -name "*.py" -type f -exec grep -l "def test_" {} \; 2>/dev/null | head -10

Length of output: 2085

---

@leynos Perfect! After thorough examination of the codebase, I can confirm that all three reviewer feedback items have been properly resolved:

1. ✅ Design document discoverable from users guide - RESOLVED

The python-native-command-mocking-design.md is properly linked and referenced in the cmd-mox-users-guide.md:

• Listed under "Related documents" section with a direct link
• Referenced multiple times throughout the guide (6 references total)
• Users can easily discover it when reading the guide

2. ✅ README updated with python-version input - RESOLVED

The release-to-pypi-uv action's README comprehensively documents the new python-version input:

• Input table clearly shows python-version with description and default 3.13
• Explanatory text explains: "The composite action installs the interpreter requested through python-version before invoking any uv commands, ensuring builds run against the expected runtime."
• Usage example demonstrates the input: python-version: '3.12'

3. ✅ Centralized uv availability check - RESOLVED

The uv availability checking has been excellently centralized in conftest.py:

HAS_UV = shutil.which("uv") is not None
REQUIRES_UV = pytest.mark.usefixtures("require_uv")

@pytest.fixture()
def require_uv() -> None:
    """Skip tests that exercise uv when the CLI is unavailable."""
    if not HAS_UV:
        pytest.skip("uv CLI not installed")

This provides a clean, reusable approach where test modules can simply use the REQUIRES_UV decorator instead of scattered shutil.which("uv") checks.

Summary

All reviewer feedback has been thoroughly addressed with high-quality implementations. The solutions are discoverable, well-documented, and follow best practices. Excellent work! 🎯

🐰 satisfied ears up with approval