docs: Correct the script analysis setting name in the README examples - #192
Merged
Merged
Conversation
Both getting-started examples assigned $PSBPreference.Test.ScriptAnalysisEnabled. That setting does not exist -- the name appears nowhere in the module source. The real one is nested, $PSBPreference.Test.ScriptAnalysis.Enabled, which the README's own settings table has documented correctly all along. $PSBPreference is a plain hashtable, so assigning an unrecognized path adds a key nothing reads. No error, no warning. Anyone who copied the psake example to turn script analysis off has been running it on every build since; anyone who copied the Invoke-Build example to turn it on may never have run it at all. These are not incidental mentions. They are the two flagship "here is how you use PowerShellBuild" blocks, which is the first thing a new consumer copies. Same failure class as #178, where IB.tasks.ps1 read Test.CodeCoverage.OutputFormat while the setting is OutputFileFormat: a name that binds nothing and fails quietly. The drift test added in #186 does not catch this. It parses $PSBPreference references out of the README settings table rows only, so names inside fenced code examples go unchecked. Extending it to code fences is worth doing once #186 and the stacked signing documentation land, and is noted on the issue rather than done here, where it would conflict with both. A third occurrence in instructions/repository-specific.instructions.md is already fixed in #188. Closes #191 Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01U1Jhu7fgTRJq7LK5MuKteE
The entry claimed a consumer who copied either example was affected. Only the psake one was. It assigns $false to the dead name, so script analysis kept running when the consumer asked for it off -- real impact. The Invoke-Build example assigns $true, and Test.ScriptAnalysis.Enabled already defaults to $true (build.properties.ps1:66), so that assignment landed on a key nothing reads while the real setting stayed at the value the consumer wanted. Nothing was lost there. Telling Invoke-Build users to check their build file for analysis that never ran would create exactly the false belief this entry exists to dispel, and the changelog is the copy that ships. Caught in review of #192. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01U1Jhu7fgTRJq7LK5MuKteE
tablackburn
changed the title
…iptanalysis-setting-name # Conflicts: # CHANGELOG.md
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Closes #191
The defect
Both of the README's getting-started examples assign a setting that does not exist.
ScriptAnalysisEnabledappears nowhere in the module source — I grepped the whole repository. The real setting is nested:The README has been contradicting its own settings table sixty lines above it.
Why this is worse than a typo
$PSBPreferenceis a plain hashtable. Assigning an unrecognized path adds a key nothing reads — no error, no warning, no hint that the line did nothing.So a consumer who copied the psake example to turn script analysis off has been running it on every build since. One who copied the Invoke-Build example to turn it on may never have run it at all. Neither has any way to notice.
And these are not incidental mentions. They are the two flagship "here is how you use PowerShellBuild" blocks — the first thing a new consumer copies.
Same failure class as #178, where
IB.tasks.ps1readTest.CodeCoverage.OutputFormatwhile the setting isOutputFileFormat: a name that binds nothing and fails quietly.The change
Two lines, plus realigning the
=on the assignment under each so the blocks still read cleanly. No module code touched — the setting was always correct, only the documentation of it was wrong.A CHANGELOG entry under Fixed because this is user-facing in effect: anyone who copied either example has a dead line in their build file right now and needs to be told to look.
Not fixed here: the test gap
The drift test added in #186 does not catch this. It parses
$PSBPreference.*references out of the README settings table rows only, so setting names inside fenced code examples are unchecked.Extending that regex to code fences would close the gap and catch this class permanently. I deliberately left it out of this PR:
tests/IBTasks.tests.ps1is modified by #186 and again by the signing-documentation PR stacked on top of it, and a third concurrent edit to the same file would conflict with both. It is recorded on #191 as the follow-up, to be done once that stack lands.Verification
grep -rn "ScriptAnalysisEnabled"across the repository now returns nothing outsideOutput/.instructions/repository-specific.instructions.md:303is already fixed in docs: Correct dead paths and stale claims in repository instructions #188, so the two PRs together clear it everywhere.🤖 Generated with Claude Code
https://claude.ai/code/session_01U1Jhu7fgTRJq7LK5MuKteE