docs(build): clarify PowerShellBuild bug-workaround status

[tablackburn]

Summary

Three comment blocks in build.psake.ps1 referenced PowerShellBuild v0.7.3 bugs as "until bug is fixed" workarounds. As part of a wider multi-repo coverage-config alignment effort (upstream PR #19 on PowerShellModuleTemplate), I checked the upstream status against PowerShellBuild v0.8.0 (Feb 2026, latest):

PSB bug	Still present in v0.8.0?	Upstream fix PR?	Status of the workaround in this repo
Test-PSBuildPester.ps1:118 — [Math]::Truncate(int / int) truncates sub-100% coverage to 0 on console	✅ yes	❌ none	Comment was misleading. This bug is display-only — the JaCoCo XML on disk has the correct numbers and Codecov reads that XML, so coverage gating already works correctly. Threshold = 0 here is just preventing the local build from acting on the bogus 0% console display, which is the same "Codecov enforces threshold" pattern the upstream template uses.
Test-PSBuildScriptAnalysis.ps1:32-34 — $_Severity typo (missing dot) that silently misses findings	✅ yes	❌ none — only #106 is open, which adds tests for the function (doesn't fix the typo)	Workaround is genuinely necessary, just bumped version reference and noted the absent fix PR.

Why this is just a doc change

After checking upstream, the right move is Path A in the agreed scope: document the divergence rather than restructure. The custom UnitTest task (Integration test exclusion) and custom ScriptAnalysis task ($_Severity typo) are both load-bearing for separate reasons; aligning to the template's default Test wiring would require restructuring 17+ test files for marginal benefit.

The truncation comment was the only actually-misleading framing — it implied the workaround would be removable if the bug got fixed, but really Threshold = 0 is the right value for this repo regardless of bug status (Codecov does the gating).

Test plan

• CI green (no code change, comment-only)

🤖 Generated with Claude Code

Summary by CodeRabbit

• Chores
  • Clarified build documentation comments to explain code coverage display/truncation behavior and note that coverage thresholds are enforced by the external service using reported XML.
  • Updated comments describing a linter analyzer quirk and the project's workaround.
  • No executable logic, configuration values, or user-facing behavior changed.

[coderabbitai]

📝 Walkthrough

Walkthrough

Expanded and clarified inline comments in build.psake.ps1 describing PowerShellBuild’s local coverage display/truncation behavior, that JaCoCo XML written to disk is correct and Codecov enforces the threshold, and the continued workaround for the PSScriptAnalyzer $__Severity-style typo in v0.8.0. No executable logic changed.

Changes

Build script comment updates

Layer / File(s)	Summary
Comment Expansion build.psake.ps1	Lines ~24–41: Rewrote and expanded comments around code coverage display/truncation, noted that local display may show <100% as 0% while JaCoCo XML is correct and Codecov enforces gating; explained local threshold set to avoid acting on the display bug.
Comment Header Refresh build.psake.ps1	Lines ~116–118: Replaced header before the custom ScriptAnalysis task to describe the substituted workaround for PowerShellBuild’s Test-PSBuildScriptAnalysis behavior and referenced the "$__Severity"-style typo (documented as "$ _Severity" in comments).
Behavioral Note build.psake.ps1	Throughout edited comments: Clarified that the built-in PSScriptAnalyzer integration is intentionally substituted by a custom ScriptAnalysis task; no thresholds, task wiring, or config values were changed.

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~2 minutes

Poem

A rabbit nibbles notes in script,
Fixing phrasing where bugs are crypt,
Coverage shown and typos named,
Tasks remain — the code unchanged,
Hooray for clearer lines and wit! 🐇✨

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title 'docs(build): clarify PowerShellBuild bug-workaround status' directly corresponds to the main change: updating comments to clarify the status of PowerShellBuild bug workarounds, explaining which issues persist in v0.8.0 and why the workarounds remain necessary.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch docs/clarify-psb-workaround-status

---

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

• X
• Mastodon
• Reddit
• LinkedIn

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

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@build.psake.ps1`:
- Around line 37-41: In the comment block referencing the built-in
PSScriptAnalyzer integration, replace shorthand terms: change "PSB" to
"PowerShellBuild" and "PR" to "pull request" (e.g., the lines starting with "#
Disable PSB's built-in..." and "# that silently misses findings — bug still
present..." in build.psake.ps1); keep the rest of the wording intact but expand
any other abbreviations found in that block to their full forms to comply with
the repository's documentation style rule.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 10f66199-be75-4e56-91bb-c5524d052f6b

📥 Commits

Reviewing files that changed from the base of the PR and between ac2c994 and 27f84cc.

📒 Files selected for processing (1)

• build.psake.ps1

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[Copilot]

Copilot encountered an error and was unable to review this pull request. You can try again by re-requesting a review.