npmpy docstring validation against changed files in pr

.github/workflows/test.yml

@@ -80,6 +80,87 @@ jobs:
               "summary": "This check is informational and does not block merging. See the job summary and the 'Validate NumPy docstrings' step log for the full list of issues."
             }
 
+  docstring-changed-files:
+    name: NumPy docstring validation (changed files)
+    runs-on: ubuntu-latest
+    # Only meaningful for pull requests, where a base branch exists to diff
+    # against. This check is REQUIRED/blocking: it fails the PR when any of the
+    # src/microbots/*.py files it touches have docstring issues.
+    if: github.event_name == 'pull_request'
+    permissions:
+      contents: read
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+        with:
+          # Full history so we can diff the PR head against its base commit to
+          # determine exactly which files this pull request changed.
+          fetch-depth: 0
+
+      - name: Set up Python 3.12
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install pre-commit
+        run: |
+          python -m pip install --upgrade pip
+          pip install pre-commit numpydoc
+
+      - name: Determine changed Python files
+        id: changed
+        # Restricts validation to the src/microbots/*.py files changed in this
+        # PR, matching the pre-commit hook's `files:` scope (^src/microbots/.*\.py$).
+        run: |
+          base="${{ github.event.pull_request.base.sha }}"
+          head="${{ github.event.pull_request.head.sha }}"
+
+          files=$(git diff --name-only --diff-filter=ACMR "$base" "$head" \
+            | grep -E '^src/microbots/.*\.py$' || true)
+
+          # Collapse to a single space-separated line for use in later steps.
+          files=$(echo "$files" | tr '\n' ' ' | xargs || true)
+          echo "files=$files" >> "$GITHUB_OUTPUT"
+          if [ -n "$files" ]; then
+            echo "has_files=true" >> "$GITHUB_OUTPUT"
+          else
+            echo "has_files=false" >> "$GITHUB_OUTPUT"
+          fi
+          echo "Changed files: ${files:-<none>}"
+
+      - name: Validate NumPy docstrings on changed files (blocking)
+        # Runs the numpydoc-validation hook against only the files this PR
+        # changes. A non-zero exit here fails the job and blocks the merge.
+        run: |
+          if [ "${{ steps.changed.outputs.has_files }}" != "true" ]; then
+            echo "No changed src/microbots/*.py files to validate."
+            exit 0
+          fi
+
+          set +e
+          output=$(pre-commit run numpydoc-validation --files ${{ steps.changed.outputs.files }} 2>&1)
+          status=$?
+          echo "$output"
+
+          {
+            echo "## NumPy docstring validation (changed files)"
+            if [ "$status" -eq 0 ]; then
+              echo "All changed files follow the NumPy docstring guide. :white_check_mark:"
+            else
+              echo "**This check is required and blocks merging.**"
+              echo ""
+              echo "Some docstrings in the files you changed don't follow the "
+              echo "NumPy guide (see \`docs/api-reference-guide.md\`). Fix the "
+              echo "issues below, then push again."
+              echo ""
+              echo '```'
+              echo "$output" | tail -n 200
+              echo '```'
+            fi
+          } >> "$GITHUB_STEP_SUMMARY"
+
+          exit "$status"
+
   test:
     runs-on: ubuntu-latest
     permissions:
@@ -332,4 +413,4 @@ jobs:
 
               echo "| ${name} | ${status} |" >> $GITHUB_STEP_SUMMARY
             fi
-          done
+          done