Skip to content

fix(python-sonarcloud): detect repo state - #166

Merged
williaby merged 5 commits into
mainfrom
chore/python-sonarcloud-detect-state
May 26, 2026
Merged

williaby merged 5 commits into
mainfrom
chore/python-sonarcloud-detect-state

Conversation

@williaby

Copy link
Copy Markdown
Collaborator

Summary

  • Apply the split-install detect-state pattern to python-sonarcloud.yml (matches merged PRs fix(python-compatibility): detect repo state instead of hardcoding uv sync --frozen #156-fix(python-release): detect repo state instead of hardcoding uv sync/run --frozen #160).
  • Add Detect repo state step (skip / poetry-not-supported / uv-locked / uv-no-lock outcomes).
  • Split Install dependencies into two if:-guarded steps so SonarCloud sees literal --frozen on the uv-locked path (S8544 cannot fire). The uv-no-lock variant inlines # NOSONAR(S8541,S8544) with rationale.
  • Keep the shell branching on extra-dependencies input inside each install step (flattening 3 modes x 2 states into 6 steps would obscure intent).
  • The pytest run step uses literal --frozen with preceding-line # NOSONAR(S8541) for --no-build only, per python-mutation.yml:159-169 precedent.
  • Downstream analysis steps (Verify coverage, SonarCloud Scan, Wait, Check Quality Gate, Quality Gate Summary, Upload coverage artifacts, Fail on Quality Gate) gain detect-state guards so the skip path exits cleanly.

NOSONAR rationale

  • S8541 (--no-build omission) is suppressed because $NO_BUILD_FLAG is dynamic by design: consumers with PEP 517 build backends (e.g., hatchling) pass no-build: false. Step-level branching just shuffles the finding.
  • S8544 (--frozen omission) is suppressed only on the uv-no-lock path, where no uv.lock exists by design (uv sync creates one on that step).
  • Precedent: python-mutation.yml:159-169.

Affected downstream repos

Per /tmp/ci-failure-inventory.tsv: 3 direct callers plus .github itself.

Sample downstream caller

ByronWilliamsCPA/family-office-portal

Test plan

  • actionlint -shellcheck= passes (embedded shellcheck reports pre-existing SC2086 warnings on $GITHUB_OUTPUT/$GITHUB_STEP_SUMMARY, unrelated to this change; per feedback_actionlint_shellcheck_embed)
  • CI on .github passes
  • SonarCloud quality gate: OK, 0 open vulnerabilities
  • After merge, sample downstream caller (family-office-portal) SonarCloud workflow re-runs successfully

Copilot AI review requested due to automatic review settings May 25, 2026 23:48
@coderabbitai

coderabbitai Bot commented May 25, 2026 •

Copy link
Copy Markdown

Warning

Review limit reached

@williaby, we couldn't start this review because you've reached your PR review rate limit.

More reviews will be available in 14 minutes and 10 seconds. Learn how PR review limits work.

Your organization has run out of usage credits. Purchase more in the billing tab.

⌛ How to resolve this issue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans include higher PR review limits than trial, open-source, and free plans. In all cases, reviews become available again over time. During sustained high-volume PR review activity, CodeRabbit may temporarily slow when the next review becomes available.

Please see our Fair Usage Limits Policy for further information.

ℹ️ Review info
⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: efc64b72-1420-4da8-ba2b-b2d05414ca73

📥 Commits

Reviewing files that changed from the base of the PR and between 51a0025 and 4e56dba.

📒 Files selected for processing (1)
  • .github/workflows/python-sonarcloud.yml
✨ Finishing Touches
🧪 Generate unit tests (beta)
  • Create PR with unit tests
  • Commit unit tests in branch chore/python-sonarcloud-detect-state

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

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

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

This PR updates the reusable SonarCloud workflow to detect the caller repository’s packaging state before running uv commands, matching the “detect repo state + split install steps” pattern already adopted in other reusable workflows in this repo. This prevents hard failures for docs-only/template repos (no pyproject.toml) and for uv repos that have not committed a uv.lock yet, while still failing fast for Poetry repos per org policy.

Changes:

  • Add a Detect repo state step that categorizes callers as skip, poetry-not-supported, uv-locked, or uv-no-lock.
  • Split dependency installation into two guarded steps so --frozen is a literal on the uv-locked path and omitted (with inline NOSONAR rationale) on the uv-no-lock path.
  • Gate downstream SonarCloud, coverage, and quality gate steps on detected uv states so the skip path exits cleanly.

williaby added a commit that referenced this pull request May 25, 2026
… install step

Preceding-line NOSONAR(S8541,S8544) inside the uv-no-lock install step's
multi-line run block is not honored by SonarCloud's githubactions rule set
(documented anti-pattern in docs/sonarcloud-nosonar-patterns.md). Moving
suppression to inline trailing comments on each of the three uv sync lines
within the block. The step-level rationale moves into the header comment.

Verified: SonarCloud PR #166 flagged S8541 L293 + S8544 L293, L299, L301 (the
three uv sync lines). Lines 280 and 282 (uv-locked path, literal --frozen)
were NOT flagged, confirming preceding-line NOSONAR(S8541) is honored when
the underlying line is otherwise clean of S8544.
williaby added a commit that referenced this pull request May 25, 2026
…arCloud

SonarCloud's githubactions rule set ignores NOSONAR (both preceding-line
and inline) inside multi-line run: | blocks for S8541/S8544. Even with
inline trailing NOSONAR per uv sync line, PR #166 commit bb31ec1 still
flagged 5 vulnerabilities (L296, L302, L304).

Restructure: extract the EXTRA_DEPENDENCIES branching into a separate
Resolve extras flag step that outputs steps.extras.outputs.flag, then
collapse each install step to a single-line run: shape. This is the only
reliable Pattern A position for SonarCloud (per docs/sonarcloud-nosonar-patterns.md).

Two install steps remain (uv-locked, uv-no-lock); the resolve step
unconditionally handles all three extras-modes and outputs a literal
flag string consumed by both.
@williaby

Copy link
Copy Markdown
Collaborator Author

PR Review (Claude Code + agents)

Status: All 24 CI checks green. SonarCloud Quality Gate passed (0 new issues). Copilot reviewed (no inline findings). CodeRabbit hit the org review rate limit and was skipped. GHAS/CodeQL surfaced 2 Critical findings; agents added 4 Important + 4 Suggested. Branch is BEHIND main — rebase before merge.


🛑 Critical (must fix before merge)

1. Code injection via ${{ steps.extras.outputs.flag }} interpolation — .github/workflows/python-sonarcloud.yml:291 and :296 (CodeQL alerts #182, #183)

The pattern uv sync ${{ steps.extras.outputs.flag }} --frozen \$NO_BUILD_FLAG performs GitHub-side template expansion before bash sees the script, so any shell metacharacters surviving the Resolve extras flag construction become script text. The pre-PR code accessed EXTRA_DEPENDENCIES only via env var inside a single run: block and did not have this exposure. The NOSONAR comments on these lines suppress SonarCloud S8541/S8544 but cannot address the CodeQL injection alert.

Fix: map the step output to an env var on each install step:

```yaml

  • name: Install dependencies (uv with lockfile)
    if: steps.detect.outputs.state == 'uv-locked'
    env:
    UV_EXTRAS: ${{ steps.extras.outputs.flag }}
    run: uv sync $UV_EXTRAS --frozen $NO_BUILD_FLAG # NOSONAR(S8541): ...
    shell: bash
    ```

⚠️ Important


💡 Suggested

  • Visually ambiguous poetry regex — :243. `'^[tool.poetry(.|])'` is correct ERE (the `]` inside a group is a literal), but escaping it explicitly (`(.|])`) removes ambiguity at zero functional cost.
  • Anti-simplification comment on repeated if: disjunctions — :340. The positive disjunction is repeated six times; the negative form (`state != 'skip' && state != 'poetry-not-supported'`) would incorrectly allow downstream steps to run when `state` is empty (detect skipped on prior failure). A one-line comment would prevent future cleanup regressions.
  • Consider defaults: run: shell: bash at job level to remove inconsistency between steps that set `shell: bash` and steps that don't.

✅ Pattern fidelity (positive)

Aside from the items above, structure is byte-identical to #156-#160: state names, ordering, skip-state notice (notice vs error), `if: always() && (...)` gating on Summary/Upload/Fail steps, exit code on poetry-not-supported. The `Resolve extras flag` indirection is a legitimate extension because `extra-dependencies` input is unique to this workflow.


🤖 Generated with Claude Code

williaby and others added 4 commits May 25, 2026 17:23
…nc --frozen

Apply the split-install detect-state pattern established by merged PRs #156-#160.
Branches on pyproject.toml + lockfile presence: skip when no pyproject, fail
fast on poetry repos with actionable error, use --frozen on uv-locked repos
and bare uv sync on uv-no-lock repos.

Install step is split into two if-guarded variants so SonarCloud sees literal
--frozen on the uv-locked path (S8544 cannot fire). The uv-no-lock variant
inlines NOSONAR(S8541,S8544) with rationale; uv.lock does not exist by design
on that path. The shell branching on extra-dependencies input is preserved
inside each install step (flattening to step variants would obscure intent).

The pytest run step uses literal --frozen with a preceding-line NOSONAR(S8541)
for --no-build only; this placement is honored when the underlying line is
otherwise clean per python-mutation.yml:159-169 precedent. Downstream analysis
steps (Verify coverage, SonarCloud Scan, Wait, Check Quality Gate, Quality Gate
Summary, Upload coverage artifacts, Fail on Quality Gate) gain detect-state
guards so the skip path exits the job cleanly.
… install step

Preceding-line NOSONAR(S8541,S8544) inside the uv-no-lock install step's
multi-line run block is not honored by SonarCloud's githubactions rule set
(documented anti-pattern in docs/sonarcloud-nosonar-patterns.md). Moving
suppression to inline trailing comments on each of the three uv sync lines
within the block. The step-level rationale moves into the header comment.

Verified: SonarCloud PR #166 flagged S8541 L293 + S8544 L293, L299, L301 (the
three uv sync lines). Lines 280 and 282 (uv-locked path, literal --frozen)
were NOT flagged, confirming preceding-line NOSONAR(S8541) is honored when
the underlying line is otherwise clean of S8544.
…arCloud

SonarCloud's githubactions rule set ignores NOSONAR (both preceding-line
and inline) inside multi-line run: | blocks for S8541/S8544. Even with
inline trailing NOSONAR per uv sync line, PR #166 commit bb31ec1 still
flagged 5 vulnerabilities (L296, L302, L304).

Restructure: extract the EXTRA_DEPENDENCIES branching into a separate
Resolve extras flag step that outputs steps.extras.outputs.flag, then
collapse each install step to a single-line run: shape. This is the only
reliable Pattern A position for SonarCloud (per docs/sonarcloud-nosonar-patterns.md).

Two install steps remain (uv-locked, uv-no-lock); the resolve step
unconditionally handles all three extras-modes and outputs a literal
flag string consumed by both.
…njection

Addresses CodeQL alerts #182 and #183 (py/code-injection) and Important findings
from /pr-review on PR #166.

Critical:
- Map steps.extras.outputs.flag to env UV_EXTRAS on both install steps so it
  reaches bash as a variable value rather than being interpolated into the run:
  script via GitHub-side template expansion. Template expansion runs before bash
  sees the line; without env mapping, any shell metacharacters in flag would
  become script text. The flag derives from inputs.extra-dependencies, a
  caller-controlled reusable workflow input.
- Add #CRITICAL / #VERIFY RAD annotations near the install steps documenting
  the env-mapping invariant per project CLAUDE.md.

Pattern alignment with PRs #156/#158/#160:
- Remove NOSONAR(S8541) on the uv-locked install step. The canonical precedent
  keeps the locked install line bare on the rationale that literal --frozen
  makes the line scanner-clean; only the uv-no-lock branch carries NOSONAR.

Polish:
- Strip leading space in FLAG accumulator so the for-loop branch produces the
  same shape as --all-extras and empty branches.
- Escape ] explicitly in poetry detection regex for reader clarity (functional
  no-op; the original was correct ERE).
- Document why the downstream if: conditions use the positive disjunction
  (state == 'uv-locked' || state == 'uv-no-lock') rather than the shorter
  negative form; the negative form would incorrectly run downstream steps when
  steps.detect.outputs.state is empty after an upstream failure.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
@williaby
williaby force-pushed the chore/python-sonarcloud-detect-state branch from 251ba35 to 6fa51ff Compare May 26, 2026 00:27
@williaby

Copy link
Copy Markdown
Collaborator Author

PR Fix Summary

Addressed all Critical and Important findings from the /pr-review pass plus the two CodeQL alerts. Branch rebased onto origin/main and force-pushed.

Fixed in 6fa51ff:

Tier Finding Fix
🛑 Critical CodeQL #182 / #183 — template injection via \${{ steps.extras.outputs.flag }} (lines 291, 296) Added env: UV_EXTRAS: \${{ steps.extras.outputs.flag }} on both install steps; references \$UV_EXTRAS in run: so bash sees the value as a variable, not as part of the script text
⚠️ Important Missing RAD #CRITICAL / #VERIFY tags on security-relevant pattern Added RAD annotation block above the install steps documenting the env-mapping invariant
⚠️ Important NOSONAR-on-uv-locked-path diverges from #156/#158/#160 precedent Removed # NOSONAR(S8541) from the uv-locked install step to match canonical precedent (literal --frozen keeps the line scanner-clean)
⚠️ Important Leading-space asymmetry in flag output Added FLAG=\"\${FLAG# }\" so the for-loop branch produces the same shape as --all-extras and empty branches
💡 Suggested Visually ambiguous ] in poetry regex Escaped to (\.|\]) for reader clarity (functional no-op)
💡 Suggested Anti-simplification comment on repeated if: disjunctions Added a comment above the first disjunction documenting why the positive form is intentional (empty state after upstream failure would satisfy the shorter negative form)

Verification:

  • actionlint -shellcheck= exit 0
  • pre-commit run --files .github/workflows/python-sonarcloud.yml all hooks passed (including no-em-dash, yamllint, commitizen)
  • Shellcheck SC2086 on \$UV_EXTRAS is intentional word-splitting (multi-extras case requires unquoted expansion); matches the pre-existing accepted pattern on \$GITHUB_OUTPUT / \$NO_BUILD_FLAG

Not addressed (out of scope):

  • Argument-hygiene regression vs original (Important, bash-array vs flat-string): partially mitigated by the env-mapping fix; full mitigation would require returning to the bash-array pattern, but that conflicts with the single-line run: shape required for SonarCloud pattern-matching. Documented as a known limitation in the new RAD annotation.
  • Suggested: defaults: run: shell: bash at job level — broader scope than this PR.

CI will re-run on the force-pushed branch. CodeQL alerts #182 and #183 should auto-dismiss on the next analysis run since the alerted template-expansion pattern has been removed.

🤖 Generated with Claude Code

The previous commit (6fa51ff) removed NOSONAR(S8541) on the uv-locked install
line on the assumption that it would match the #156/#158/#160 precedent of
keeping the locked-install line bare. SonarCloud's Quality Gate on PR #166
empirically rejected this assumption: S8541 (security rating C) fires on this
line regardless of the literal --frozen, because $NO_BUILD_FLAG remains a
dynamic env var.

Why this workflow differs from #156/#158/#160: the install steps in those PRs
likely resolve to a literal --no-build, no flag, or no install at all on the
locked path. python-sonarcloud.yml's locked install step uses dynamic
$NO_BUILD_FLAG (the no-build: workflow input is opt-out by design for PEP 517
consumers like hatchling), so S8541 matches.

Restored the inline NOSONAR(S8541) and updated the header comment to document
the empirical divergence so a future reader does not re-attempt the same
"match precedent" cleanup.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
@sonarqubecloud

Copy link
Copy Markdown

@williaby

Copy link
Copy Markdown
Collaborator Author

Fix-up: re-add NOSONAR(S8541) on uv-locked install line

SonarCloud Quality Gate empirically rejected the "match #156/#158/#160 precedent" approach from 6fa51ff: S8541 fires on uv sync $UV_EXTRAS --frozen $NO_BUILD_FLAG even with the literal --frozen present, because $NO_BUILD_FLAG is a dynamic env var rather than a literal --no-build. That distinguishes this workflow from #156/#158/#160 (where the locked install path likely resolves to a literal --no-build or omits the flag).

Restored the inline # NOSONAR(S8541) on line 307 in 4e56dba. The header comment now documents the empirical divergence so a future cleanup does not re-attempt the same removal.

CodeQL fix from 6fa51ff is unchanged: UV_EXTRAS env mapping remains on both install steps; injection vector is closed.

🤖 Generated with Claude Code

@williaby
williaby merged commit c7d2dce into main May 26, 2026
24 checks passed
@williaby
williaby deleted the chore/python-sonarcloud-detect-state branch May 26, 2026 00:50
williaby added a commit that referenced this pull request May 26, 2026
Wave 1C of the CI Repair Sprint (PR #166, python-sonarcloud.yml) discovered
that inline-trailing NOSONAR inside a run: | block scalar is ALSO not
honored by SonarCloud's githubactions ruleset, not just preceding-line.
Three commits were required to converge: split-install with preceding-line
NOSONAR (ERROR 5 vulns), inline-trailing inside run: | (still ERROR 5
vulns), and finally structural rewrite to single-line run: (OK 0 vulns).

This commit updates the canonical patterns doc to:

- Add a fourth row to the TL;DR table documenting inline-trailing-inside-
  block failure mode (PR #166 commit bb31ec1).
- Strengthen the Rule of thumb: only single-line run: shape reliably
  honors NOSONAR. Any placement inside run: | is unreliable.
- Update the Hypothesis section with three candidate explanations.
- Demote Pattern B from "acceptable for multi-line" to "fragile; use only
  when single-line shape is impossible."
- Add a second empirical anti-pattern: inline-trailing inside run: |.
- Add Option 3 (helper-step output emission) as the pattern PR #166 used.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
williaby added a commit that referenced this pull request May 26, 2026
Critical: Option 3 example interpolated ${{ inputs.extras }} and
${{ steps.extras.outputs.flag }} directly into shell, which conflicts
with the workflow-injection hardening pattern documented in
python-sonarcloud.yml:302-307 (#CRITICAL RAD annotation). Route both
through env: blocks (EXTRA_DEPENDENCIES, UV_EXTRAS) so the example
matches the implementation it cites.

Also align identifier names with the real workflow: inputs.extras ->
inputs.extra-dependencies. Add an explanatory paragraph naming the
injection vector and pointing at the source file's #CRITICAL annotation.

Important: reword the Option 3 "benefit" sentence; the helper step still
uses run: |. Only the install step (where NOSONAR matters) is now
single-line.

Suggested: tighten hypothesis section by collapsing the comma-syntax
candidate into a parenthetical (Wave 1C's own evidence tested both
forms and disproves it as the variable). Dedupe the duplicate PR #166
references entry.

Informational: replace "lucky non-failure" (both occurrences) with
"incidental pass" for a more deliberate technical tone.

Addresses Copilot inline comments at lines 171 and 181 of the original
diff. Quality gate impact: none (docs excluded from SonarCloud scan).

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
williaby added a commit that referenced this pull request May 26, 2026
…ing (#170)

* docs(sonarcloud): strengthen NOSONAR rule with Wave 1C empirical finding

Wave 1C of the CI Repair Sprint (PR #166, python-sonarcloud.yml) discovered
that inline-trailing NOSONAR inside a run: | block scalar is ALSO not
honored by SonarCloud's githubactions ruleset, not just preceding-line.
Three commits were required to converge: split-install with preceding-line
NOSONAR (ERROR 5 vulns), inline-trailing inside run: | (still ERROR 5
vulns), and finally structural rewrite to single-line run: (OK 0 vulns).

This commit updates the canonical patterns doc to:

- Add a fourth row to the TL;DR table documenting inline-trailing-inside-
  block failure mode (PR #166 commit bb31ec1).
- Strengthen the Rule of thumb: only single-line run: shape reliably
  honors NOSONAR. Any placement inside run: | is unreliable.
- Update the Hypothesis section with three candidate explanations.
- Demote Pattern B from "acceptable for multi-line" to "fragile; use only
  when single-line shape is impossible."
- Add a second empirical anti-pattern: inline-trailing inside run: |.
- Add Option 3 (helper-step output emission) as the pattern PR #166 used.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* docs(sonarcloud): harden Option 3 example, address PR #170 review

Critical: Option 3 example interpolated ${{ inputs.extras }} and
${{ steps.extras.outputs.flag }} directly into shell, which conflicts
with the workflow-injection hardening pattern documented in
python-sonarcloud.yml:302-307 (#CRITICAL RAD annotation). Route both
through env: blocks (EXTRA_DEPENDENCIES, UV_EXTRAS) so the example
matches the implementation it cites.

Also align identifier names with the real workflow: inputs.extras ->
inputs.extra-dependencies. Add an explanatory paragraph naming the
injection vector and pointing at the source file's #CRITICAL annotation.

Important: reword the Option 3 "benefit" sentence; the helper step still
uses run: |. Only the install step (where NOSONAR matters) is now
single-line.

Suggested: tighten hypothesis section by collapsing the comma-syntax
candidate into a parenthetical (Wave 1C's own evidence tested both
forms and disproves it as the variable). Dedupe the duplicate PR #166
references entry.

Informational: replace "lucky non-failure" (both occurrences) with
"incidental pass" for a more deliberate technical tone.

Addresses Copilot inline comments at lines 171 and 181 of the original
diff. Quality gate impact: none (docs excluded from SonarCloud scan).

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

---------

Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
williaby added a commit that referenced this pull request May 26, 2026
…tall

Apply the Wave 1C strengthened detect-state pattern (see PR #166): split the
install step into two if-guarded single-line `run:` steps (uv-locked vs
uv-no-lock), each carrying Pattern A inline NOSONAR. Gate downstream steps
on detect.outputs.state so skip and poetry-not-supported paths exit cleanly.

The pre-existing single-line install (line 169) used a bare `# NOSONAR`
without a rule list; replace with explicit S8541 (and S8541,S8544 on the
no-lock path) rule lists per the strengthened patterns doc.

Trigger unchanged: workflow_call only (CI-053 enforced; mutation testing
must remain schedule + workflow_dispatch in downstream callers).

The `Run mutation testing` step retains its `run: |` block because the
shell logic uses multi-line uv run calls with literal `--frozen`. Per the
strengthened guidance, preceding-line NOSONAR inside `run: |` is fragile
but the literal `--frozen` keeps S8544 from firing structurally. Verify
the SonarCloud gate per PR; if S8541 fires here, restructure to single-
line shape per Option 3.
williaby added a commit that referenced this pull request May 26, 2026
…tall (#172)

* fix(python-mutation): apply detect-state pattern with single-line install

Apply the Wave 1C strengthened detect-state pattern (see PR #166): split the
install step into two if-guarded single-line `run:` steps (uv-locked vs
uv-no-lock), each carrying Pattern A inline NOSONAR. Gate downstream steps
on detect.outputs.state so skip and poetry-not-supported paths exit cleanly.

The pre-existing single-line install (line 169) used a bare `# NOSONAR`
without a rule list; replace with explicit S8541 (and S8541,S8544 on the
no-lock path) rule lists per the strengthened patterns doc.

Trigger unchanged: workflow_call only (CI-053 enforced; mutation testing
must remain schedule + workflow_dispatch in downstream callers).

The `Run mutation testing` step retains its `run: |` block because the
shell logic uses multi-line uv run calls with literal `--frozen`. Per the
strengthened guidance, preceding-line NOSONAR inside `run: |` is fragile
but the literal `--frozen` keeps S8544 from firing structurally. Verify
the SonarCloud gate per PR; if S8541 fires here, restructure to single-
line shape per Option 3.

* fix(python-mutation): emit deterministic skip outputs and tighten nested uv run

Address two findings from PR #172 review (Copilot, local pr-review):

1. Skip path leaves workflow_call outputs empty.
   The job's score/passed outputs sourced from steps.analyze.outputs.*,
   which evaluate to empty strings when analyze is gated off on the skip
   path. Downstream callers using `if: needs.mutation.outputs.passed ==
   'true'` silently fell through to false. Add a `set-skip-outputs`
   step that writes deterministic score=0, passed=true, and skipped=true,
   and coalesce the job-output expressions across analyze and the new
   step. Expose `skipped` as a new workflow_call output so sophisticated
   callers can distinguish "skipped" from "tested and passed".

2. Nested `uv run mutmut results --json` subprocess inside the analyze
   step's Python heredoc omitted --frozen and \$NO_BUILD_FLAG, breaking
   the PR body's stated invariant that literal --frozen is on every
   `uv run` line. Build the command in Python so both flags propagate,
   restoring the lockfile/no-build guarantee on this invocation.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* docs(changelog): note python-mutation skip outputs and uv run fix

Document the python-mutation.yml changes from PR #172 in the
[Unreleased] Fixed section, covering the detect-state pattern
application, deterministic skip-path outputs (with new `skipped`
output), and the nested subprocess --frozen/\$NO_BUILD_FLAG fix.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

---------

Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
williaby added a commit that referenced this pull request May 26, 2026
… --frozen

Apply established NOSONAR detect-state pattern (see python-mutation.yml:159-169
and merged PRs #155-#160, #164-#166). Branches on pyproject.toml + lockfile
presence: skip when no pyproject, fail fast on poetry repos with actionable
error, use --frozen on uv-locked repos, drop --frozen on uv-no-lock repos.

Apply Wave 1C strengthened pattern (docs/sonarcloud-nosonar-patterns.md
strengthened 2026-05-26): only single-line run: shape reliably honors NOSONAR.
Split install into two if:-guarded steps with literal flags and inline Pattern
A NOSONAR. Collapse Check docstring coverage and Build MkDocs site multi-line
run: | blocks to single-line run: so SonarCloud can pattern-match Pattern A.

S8541 suppression is acceptable here: the \$NO_BUILD_FLAG env var is dynamic
by design (consumers with PEP 517 build backends like hatchling can pass
no-build: false). Step-level branching would just shuffle the finding.
williaby added a commit that referenced this pull request May 26, 2026
… --frozen (#171)

* fix(python-docs): detect repo state instead of hardcoding uv sync/run --frozen

Apply established NOSONAR detect-state pattern (see python-mutation.yml:159-169
and merged PRs #155-#160, #164-#166). Branches on pyproject.toml + lockfile
presence: skip when no pyproject, fail fast on poetry repos with actionable
error, use --frozen on uv-locked repos, drop --frozen on uv-no-lock repos.

Apply Wave 1C strengthened pattern (docs/sonarcloud-nosonar-patterns.md
strengthened 2026-05-26): only single-line run: shape reliably honors NOSONAR.
Split install into two if:-guarded steps with literal flags and inline Pattern
A NOSONAR. Collapse Check docstring coverage and Build MkDocs site multi-line
run: | blocks to single-line run: so SonarCloud can pattern-match Pattern A.

S8541 suppression is acceptable here: the \$NO_BUILD_FLAG env var is dynamic
by design (consumers with PEP 517 build backends like hatchling can pass
no-build: false). Step-level branching would just shuffle the finding.

* fix(python-docs): gate deploy on build state to avoid download-artifact failure

Expose steps.detect.outputs.state as a build job-level output and require
needs.build.outputs.state != 'skip' in the deploy job if: clause. Without
this, the build job succeeded in skip mode (only the skip-notice step ran;
the upload-artifact step was already conditionally skipped) and needs: build
falsely cleared deploy to run, where actions/download-artifact then failed
with "artifact not found" against the never-uploaded documentation-site.

Add CHANGELOG entry under [Unreleased] / Fixed.

Addresses Copilot inline review on PR #171.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.7 <noreply@anthropic.com>
williaby added a commit that referenced this pull request May 26, 2026
PR #170 strengthened the NOSONAR rule based on Wave 1C (PR #166), which
found that comma-separated NOSONAR and inline-trailing NOSONAR inside
run: | blocks are not honored. The strengthened rule was framed as "any
NOSONAR inside run: | is unreliable; treat Pattern B as a lucky
non-failure."

Subsequent Waves 2B (PR #172, python-mutation) and 2C (PR #173, python-
performance-regression) re-validated Pattern B with passing SonarCloud
gates. Both PRs kept multi-line run: | blocks with literal --frozen on
every uv line and preceding-line single-rule # NOSONAR(S8541). Both
achieved gate=OK with 0 vulns on first push.

The evidence supports a more nuanced rule: Pattern B is reliable when
three conditions hold simultaneously.

1. Every uv invocation in the run: | block uses literal --frozen
   (not dynamic $FROZEN_FLAG).
2. NOSONAR is single-rule S8541 only, not comma-separated.
3. NOSONAR is on the preceding line, not inline-trailing.

Updates to docs/sonarcloud-nosonar-patterns.md:

- TL;DR table: split the prior "Preceding-line with literal --frozen"
  row into two rows that distinguish the working condition (single-rule
  S8541) from the failure modes (comma-separated or inline-trailing).
- TL;DR Rule of thumb: replace "single-line run: only" framing with
  "two predictable shapes" framing, listing both Pattern A and the
  conditioned Pattern B.
- Recommended Patterns: replace "Pattern B (fragile)" framing with
  "Pattern B (acceptable under specific conditions)" plus an explicit
  three-condition reliability list. Note 3-for-3 empirical track record
  when conditions hold.
- Date line: add "nuanced 2026-05-26" with PR pointer.

The earlier strengthened rule was over-pessimistic. This nuance does not
contradict it; both PRs #166 and #170 documented failure modes correctly,
and PRs #172 and #173 demonstrated the working conditions. Future Phase 2
or 3 implementers should default to Pattern A but may use Pattern B when
the three conditions hold.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
williaby added a commit that referenced this pull request May 26, 2026
…ce (#174)

* docs(sonarcloud): nuance Pattern B reliability with Wave 2B/2C evidence

PR #170 strengthened the NOSONAR rule based on Wave 1C (PR #166), which
found that comma-separated NOSONAR and inline-trailing NOSONAR inside
run: | blocks are not honored. The strengthened rule was framed as "any
NOSONAR inside run: | is unreliable; treat Pattern B as a lucky
non-failure."

Subsequent Waves 2B (PR #172, python-mutation) and 2C (PR #173, python-
performance-regression) re-validated Pattern B with passing SonarCloud
gates. Both PRs kept multi-line run: | blocks with literal --frozen on
every uv line and preceding-line single-rule # NOSONAR(S8541). Both
achieved gate=OK with 0 vulns on first push.

The evidence supports a more nuanced rule: Pattern B is reliable when
three conditions hold simultaneously.

1. Every uv invocation in the run: | block uses literal --frozen
   (not dynamic $FROZEN_FLAG).
2. NOSONAR is single-rule S8541 only, not comma-separated.
3. NOSONAR is on the preceding line, not inline-trailing.

Updates to docs/sonarcloud-nosonar-patterns.md:

- TL;DR table: split the prior "Preceding-line with literal --frozen"
  row into two rows that distinguish the working condition (single-rule
  S8541) from the failure modes (comma-separated or inline-trailing).
- TL;DR Rule of thumb: replace "single-line run: only" framing with
  "two predictable shapes" framing, listing both Pattern A and the
  conditioned Pattern B.
- Recommended Patterns: replace "Pattern B (fragile)" framing with
  "Pattern B (acceptable under specific conditions)" plus an explicit
  three-condition reliability list. Note 3-for-3 empirical track record
  when conditions hold.
- Date line: add "nuanced 2026-05-26" with PR pointer.

The earlier strengthened rule was over-pessimistic. This nuance does not
contradict it; both PRs #166 and #170 documented failure modes correctly,
and PRs #172 and #173 demonstrated the working conditions. Future Phase 2
or 3 implementers should default to Pattern A but may use Pattern B when
the three conditions hold.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* docs(sonarcloud): resolve internal contradictions in Pattern B framing

Addresses PR #174 review findings:

Critical
- Anti-patterns heading at line 145 narrowed from "any NOSONAR inside
  run: | blocks" to "unreliable NOSONAR forms inside run: | blocks",
  since the body of the same PR now endorses Pattern B (preceding-line
  single-rule NOSONAR with literal --frozen) inside run: | blocks.
- Hypothesis section (lines 88-107) rewritten: the absolute Wave 1C
  claim that "no NOSONAR placement inside a run: | block scalar is
  reliable" was the surviving prior framing that contradicted the new
  Pattern B framing. Reframed as historical Wave 1C conclusion now
  superseded by Wave 2B/2C re-validation.

Important
- "3-for-3" reliability claim qualified: PR #173 is open at time of
  writing with a passing pre-merge gate; reframed as "2 merged
  applications plus 1 pre-merge gate pass" so readers do not treat all
  three legs as production-validated.

Suggested
- Pattern B uv-line count corrected from "11 uv lines across 4 blocks"
  to "11 uv lines across 5 blocks" (actual count of run: | blocks
  added in PR #173).
- TL;DR rule-of-thumb sentence deduplicated against the identical
  sentence in the Pattern B detail section, now references the
  Verification protocol section instead.

Informational
- "Lucky non-failure" jargon at line 141 rewritten to be
  self-contained for first-time readers.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

---------

Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
williaby added a commit that referenced this pull request May 26, 2026
…coding uv sync/run --frozen

Apply established NOSONAR detect-state pattern (see python-mutation.yml:159-169)
to the largest reusable workflow in the org (642 lines, 17 unguarded uv
invocations across 8 install/run steps).

Changes:
- Add `Detect repo state` step that branches on pyproject.toml + lockfile
  presence: skip when no pyproject, fail fast on poetry repos with actionable
  error, install with --frozen on uv-locked repos, install without --frozen
  on uv-no-lock repos (uv sync creates the lockfile on that path).
- Add `Resolve extra dependency flags` helper step (Option 3 from PR #166)
  that builds a flat "--extra dev --extra ml" string output, so the per-state
  install steps can be single-line Pattern A NOSONAR placement.
- Split the two install steps (PR-branch and main-branch) into uv-locked /
  uv-no-lock variants each, four total. Pattern A inline NOSONAR(S8541) on
  uv-locked (literal --frozen visible); NOSONAR(S8541,S8544) on uv-no-lock
  where --frozen is structurally absent by design.
- Apply Pattern B (preceding-line NOSONAR(S8541) inside `run: |`) to the
  three multi-line shell blocks (Run PR Benchmarks, Run Baseline Benchmarks,
  Compare Performance). Every uv invocation in these blocks carries literal
  --frozen, so only S8541 needs suppression. Per docs/sonarcloud-nosonar-
  patterns.md strengthened 2026-05-26, Pattern B is acceptable when literal
  --frozen is structurally present and only S8541 fires. The blocks are
  genuinely multi-line (capability detection branching with three argv
  variants, Python heredoc) so collapsing to single-line is not feasible
  without significant readability loss.
- Add `Skip notice` step for the no-pyproject path so downstream callers
  see a clear summary entry instead of a silent green.
- Guard all downstream benchmark / summary / PR-comment / fail steps with
  `if: steps.detect.outputs.state == 'uv-locked' || == 'uv-no-lock'` so
  the workflow exits cleanly when no pyproject is present.

S8541 suppression rationale: `$NO_BUILD_FLAG` (from inputs.no-build, default
'true' -> '--no-build') is dynamic by design so consumers with PEP 517 build
backends like hatchling can pass `no-build: false`. SonarCloud cannot resolve
the env var. The lockfile-based `uv sync --frozen` (uv-locked path) constrains
installable versions to the consumer's audited uv.lock, bounding residual
setup-script risk.

Wave 2C of CI Repair Sprint Phase 2. Largest single-file change in the sprint.
williaby added a commit that referenced this pull request May 26, 2026
…coding uv sync --frozen (#173)

* fix(python-performance-regression): detect repo state instead of hardcoding uv sync/run --frozen

Apply established NOSONAR detect-state pattern (see python-mutation.yml:159-169)
to the largest reusable workflow in the org (642 lines, 17 unguarded uv
invocations across 8 install/run steps).

Changes:
- Add `Detect repo state` step that branches on pyproject.toml + lockfile
  presence: skip when no pyproject, fail fast on poetry repos with actionable
  error, install with --frozen on uv-locked repos, install without --frozen
  on uv-no-lock repos (uv sync creates the lockfile on that path).
- Add `Resolve extra dependency flags` helper step (Option 3 from PR #166)
  that builds a flat "--extra dev --extra ml" string output, so the per-state
  install steps can be single-line Pattern A NOSONAR placement.
- Split the two install steps (PR-branch and main-branch) into uv-locked /
  uv-no-lock variants each, four total. Pattern A inline NOSONAR(S8541) on
  uv-locked (literal --frozen visible); NOSONAR(S8541,S8544) on uv-no-lock
  where --frozen is structurally absent by design.
- Apply Pattern B (preceding-line NOSONAR(S8541) inside `run: |`) to the
  three multi-line shell blocks (Run PR Benchmarks, Run Baseline Benchmarks,
  Compare Performance). Every uv invocation in these blocks carries literal
  --frozen, so only S8541 needs suppression. Per docs/sonarcloud-nosonar-
  patterns.md strengthened 2026-05-26, Pattern B is acceptable when literal
  --frozen is structurally present and only S8541 fires. The blocks are
  genuinely multi-line (capability detection branching with three argv
  variants, Python heredoc) so collapsing to single-line is not feasible
  without significant readability loss.
- Add `Skip notice` step for the no-pyproject path so downstream callers
  see a clear summary entry instead of a silent green.
- Guard all downstream benchmark / summary / PR-comment / fail steps with
  `if: steps.detect.outputs.state == 'uv-locked' || == 'uv-no-lock'` so
  the workflow exits cleanly when no pyproject is present.

S8541 suppression rationale: `$NO_BUILD_FLAG` (from inputs.no-build, default
'true' -> '--no-build') is dynamic by design so consumers with PEP 517 build
backends like hatchling can pass `no-build: false`. SonarCloud cannot resolve
the env var. The lockfile-based `uv sync --frozen` (uv-locked path) constrains
installable versions to the consumer's audited uv.lock, bounding residual
setup-script risk.

Wave 2C of CI Repair Sprint Phase 2. Largest single-file change in the sprint.

* fix(python-performance-regression): address Copilot review findings on PR #173

Resolves four issues raised in Copilot's review and one related design
smell surfaced by the /pr-review pass.

Critical:
- Install-on-main now re-detects uv.lock presence inline via [ -f uv.lock ]
  rather than trusting steps.detect.outputs.state. The original gating
  used the PR-branch detection after `git checkout origin/main`, which
  misclassifies main when the PR adds or removes uv.lock. Collapses the
  two install-on-main steps into one with a shell-level branch.
- Validate Benchmark Script now carries the same detect-state guard as
  adjacent steps, so the skip path (no pyproject.toml) actually skips
  instead of failing on a missing benchmark script.

Important:
- Compare Performance no longer calls sys.exit(1) on regression. The
  dedicated `Fail on Regression` step at the end of the job is now the
  single source of failure-on-regression behavior. Post PR Comment and
  Performance Summary now run on regression, which is the case where
  they matter most. Removes the unused `import sys` and the redundant
  FAIL_ON_REGRESSION env var on the Compare step.
- Resolve extra dependency flags validates each extra against the PEP
  508 allowlist (^[A-Za-z0-9._-]+\$) before emitting it; caller-controlled
  bytes can no longer reach the downstream `uv sync \$EXTRA_FLAGS`
  expansion. Whitespace separators (space, tab, or newlines from YAML
  block scalars) are normalized via `tr -s`.

Verification:
- actionlint -shellcheck= passes
- yamllint passes (existing line-length warnings unchanged)
- pre-commit run --files passes (no-em-dash hook included)

* fix(python-performance-regression): use same-line NOSONAR (Pattern A) for SonarCloud

SonarCloud quality gate failed on the previous push with 11 new S8541
(and one S8544) issues because the workflow's prior Pattern B (preceding-
line `# NOSONAR(...)` inside `run: |`) is not recognized by SonarCloud's
standard NOSONAR mechanism, which is documented as same-line only.

Conversion:
- Single-line invocations get NOSONAR appended at end of line (Generate
  Synthetic Test Data, Install dependencies on main x2, Compare
  Performance heredoc opener).
- Multi-line capability checks (`uv run ... --help | grep ...`) get
  NOSONAR appended at end of the existing single line.
- Multi-line benchmark execution branches in Run PR Benchmarks and Run
  Baseline Benchmarks have their `uv run` argv collapsed onto one line
  (no more `\`-continuations) so a same-line NOSONAR can sit on the same
  line as the `uv run --frozen $NO_BUILD_FLAG` invocation. The `|| {
  ... }` fallback brace groups stay multi-line for readability.

Stale comments about "Pattern B (preceding-line NOSONAR inside run: |)
is acceptable here because..." removed; replaced with brief notes
explaining the same-line NOSONAR rationale.

Verification:
- actionlint -shellcheck= passes
- yamllint passes (8 new line-length warnings from collapsed `uv run`
  lines; warnings only, not errors)
- pre-commit run --files passes

* fix(python-performance-regression): use hashFiles() to gate install-on-main, revert Pattern A churn

Revert commit 46e462b. Per docs/sonarcloud-nosonar-patterns.md (nuanced
in PR #174, merged 2026-05-25), inline-trailing NOSONAR inside `run: |`
block scalars is NOT honored by SonarCloud's githubactions rule set, and
the preceding-line Pattern B form IS reliable when three conditions hold:
literal --frozen on every uv line, single-rule S8541 only, no dynamic
$FROZEN_FLAG. The collapse-to-single-line approach in 46e462b violated
condition #3 (inline-trailing) and triggered 21 new MAJOR vulnerabilities
on the SonarCloud gate, up from 11. This revert restores Pattern B at
all original locations.

Restructure the `Install dependencies on main` step (still incorrect
even at the fda25ca state) to satisfy SonarCloud:

- Replace the `run: |` block + `[ -f uv.lock ]` shell check (which used
  comma-separated NOSONAR(S8541,S8544) for the uv-no-lock branch,
  violating Pattern B condition #2) with two single-line `run:` steps.
- Gate each step with `hashFiles('uv.lock')` instead of the stale
  `steps.detect.outputs.state`. hashFiles() re-evaluates per step
  against the current worktree, so after `Checkout Main Branch` it
  correctly reflects main's tree (the original Copilot finding).
- Each single-line step uses Pattern A (inline NOSONAR), which IS the
  most reliable form per the docs and accepts comma-separated rule
  lists (the uv-no-lock branch carries NOSONAR(S8541,S8544)).

This combines the correctness fix for the Copilot install-on-main
finding with the SonarCloud-compatible suppression shape, replacing
the previous flawed attempt.
williaby pushed a commit that referenced this pull request Jul 12, 2026
The org's own docs/sonarcloud-nosonar-patterns.md (surfaced via review)
documents this exact failure precisely: SonarCloud's githubactions
ruleset only reliably honors NOSONAR as a trailing comment on a genuine
single-line YAML `run:` scalar (Pattern A), not a preceding-line comment
inside a `run: |` block (Pattern B is reliable only for multi-line
backslash-continued commands with a literal --frozen, e.g. the pytest
steps, which is why those were never flagged across any of this
feature's prior commits). The previous commit used a preceding-line
comment for the single-line install/coverage commands, an anti-pattern
the doc traces back to PR #166 commit bb31ec1.

Rebuild every affected `uv sync`/`uv run` line as a bash array
(NO_BUILD_ARGS=(); [ -n "$NO_BUILD_FLAG" ] && NO_BUILD_ARGS+=(...); ...
"${NO_BUILD_ARGS[@]}") on a single physical `run:` line with a trailing
NOSONAR comment. This satisfies Pattern A for SonarCloud while staying
shellcheck-clean without needing a `# shellcheck disable=SC2086` comment
(which itself requires its own preceding line and so cannot coexist with
a single-line run:). Verified against a real shellcheck binary, and that
the array construction survives `set -e` when the flag is empty (GitHub
Actions bash steps run with -e by default).

Also addresses the review's other findings:
- Fix the literal em-dash in docs/workflows/python-ci.md (hard project
  rule).
- Add a CHANGELOG.md entry under [Unreleased] for the new input.
- Add `fetch-depth: 0` and a "Validate source layout" step to the three
  new test-* jobs, matching quality-checks (previously only
  coverage-combine and quality-checks had these).
- coverage-combine's coverage-combine step now uses --keep and || true,
  matching quality-checks' own combine step.
- coverage-combine now runs its own "Verify relative_files is configured"
  preflight (parses pyproject.toml with tomllib) and fails fast with an
  actionable error instead of silently under-counting coverage when a
  caller opts in without relative_files = true.
- Drop coverage-combine's final upload step's `if: always()` to match
  quality-checks' upload step (no always(); only runs on success).

Not addressed here (raised as a design question, not a bug): the
review's premise question about collapsing test-unit/test-integration/
test-security into one `strategy.matrix` job. That's a real
simplification but changes the job/check-name surface this feature
exposes to callers; deferring to a follow-up discussion rather than
folding into this already-large diff.

Signed-off-by: Claude <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants