Sync docs changes from docs repo by sdwheeler · Pull Request #2196 · PowerShell/PSScriptAnalyzer · GitHub
Skip to content

Sync docs changes from docs repo - #2196

Open
Sean Wheeler (sdwheeler) wants to merge 8 commits into
PowerShell:mainfrom
sdwheeler:sdw-w591525-rule-sync-docs-src
Open

Sync docs changes from docs repo#2196
Sean Wheeler (sdwheeler) wants to merge 8 commits into
PowerShell:mainfrom
sdwheeler:sdw-w591525-rule-sync-docs-src

Conversation

@sdwheeler

@sdwheeler Sean Wheeler (sdwheeler) commented Jul 23, 2026 •
edited
Loading

Copy link
Copy Markdown
Collaborator

Sync docs changes from docs repo

Copilot AI review requested due to automatic review settings July 23, 2026 17:57
Copilot AI reviewed Jul 23, 2026
View reviewed changes

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

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 syncs updated PSScriptAnalyzer documentation from the upstream docs repo, primarily refreshing built-in rule reference pages and cmdlet help pages. It also incorporates the docs change needed to address #2192/#2193 by documenting ParseError as an allowed -Severity value for Invoke-ScriptAnalyzer.

Changes:

  • Refresh rule docs to a more consistent structure (default state, clearer descriptions, examples, and “Configure rule” sections).
  • Update rules index (docs/Rules/README.md) to a new “Default state” model and add link references for maintainability.
  • Update cmdlet docs (including adding New-ScriptAnalyzerSettingsFile and Test-ScriptAnalyzerSettingsFile to the module landing page and documenting ParseError severity).

Reviewed changes

Copilot reviewed 85 out of 85 changed files in this pull request and generated 4 comments.

Show a summary per file
File Description
docs/Rules/UseUTF8EncodingForHelpFile.md Expands rule doc with default state, examples, configuration guidance, and link refs.
docs/Rules/UseUsingScopeModifierInNewRunspaces.md Refreshes rule description/examples and adds configuration guidance section.
docs/Rules/UseToExportFieldsInManifest.md Clarifies guidance and adds config/suppression section.
docs/Rules/UseSupportsShouldProcess.md Rewrites description and adds “Default state” and config guidance.
docs/Rules/UseSingularNouns.md Reworks description/examples and adds structured parameters section.
docs/Rules/UseSingleValueFromPipelineParameter.md Adds default state + configuration and clarifies suppression guidance.
docs/Rules/UseShouldProcessForStateChangingFunctions.md Updates description, adds configure/suppression guidance, and normalizes link refs.
docs/Rules/UsePSCredentialType.md Expands description and adds configuration guidance section.
docs/Rules/UseProcessBlockForPipelineCommand.md Improves explanation and adds configure/suppression guidance.
docs/Rules/UseOutputTypeCorrectly.md Adds default state and config guidance + improves description and link refs.
docs/Rules/UseLiteralInitializerForHashtable.md Adds default state + configure/suppression guidance and improves examples.
docs/Rules/UseDeclaredVarsMoreThanAssignments.md Adds default state + configure/suppression guidance and improves explanations.
docs/Rules/UseCorrectCasing.md Adds example section and rewrites parameters documentation.
docs/Rules/UseConstrainedLanguageMode.md Major rewrite: adds consolidated restriction/remediation table, config + parameter docs, and link ref normalization.
docs/Rules/UseConsistentWhitespace.md Adds default state and expands/clarifies parameter descriptions and examples.
docs/Rules/UseConsistentParametersKind.md Rewrites overview and trims config section (now needs ParametersKind documented).
docs/Rules/UseConsistentParameterSetName.md Adds default state + guidance/notes and reorganizes configuration section.
docs/Rules/UseConsistentIndentation.md Adds default state, examples, and expands parameter documentation.
docs/Rules/UseCompatibleTypes.md Adds default state, new examples, and expands parameter descriptions.
docs/Rules/UseCompatibleSyntax.md Adds default state, examples, and expands parameter documentation.
docs/Rules/UseCompatibleCommands.md Adds default state, examples, and expands parameter documentation.
docs/Rules/UseCompatibleCmdlets.md Rewrites description/config guidance and adds suppression guidance and link ref.
docs/Rules/UseCmdletCorrectly.md Adds default state + config/suppression guidance and improves description.
docs/Rules/UseBOMForUnicodeEncodedFile.md Adds default state + examples and config/suppression guidance; switches to link refs.
docs/Rules/UseApprovedVerbs.md Adds default state + config/suppression guidance; improves description and examples.
docs/Rules/ShouldProcess.md Rewrites description, adds default state, and adds config/suppression guidance + link refs.
docs/Rules/ReviewUnusedParameter.md Adds default state + config/suppression guidance and reorganizes configuration docs.
docs/Rules/ReservedParams.md Adds default state + config/suppression guidance and improves description.
docs/Rules/ReservedCmdletChar.md Adds default state, expands reserved character explanation, and adds config/suppression guidance.
docs/Rules/README.md Replaces rules list table with “Default state” model and link-reference style.
docs/Rules/ProvideCommentHelp.md Rewrites description and adds structured config + parameter documentation.
docs/Rules/PossibleIncorrectUsageOfRedirectionOperator.md Adds default state + config/suppression guidance and improves description.
docs/Rules/PossibleIncorrectUsageOfAssignmentOperator.md Adds detailed explanation + implicit suppression section and adds config/suppression guidance + link refs.
docs/Rules/PossibleIncorrectComparisonWithNull.md Adds richer explanation/examples and adds config/suppression guidance + link refs.
docs/Rules/PlaceOpenBrace.md Adds default state, examples, and expands parameter documentation.
docs/Rules/PlaceCloseBrace.md Adds default state, examples, and expands parameter documentation.
docs/Rules/MissingTryBlock.md Adds default state, clarifies false-positive note, and normalizes link refs.
docs/Rules/MissingModuleManifestField.md Adds default state + config/suppression guidance; improves description and adds link refs.
docs/Rules/MisleadingBacktick.md Adds default state, adds examples, and adds config/suppression guidance.
docs/Rules/InvalidMultiDotValue.md Adds default state, improves description, and renames configuration section to “Configure rule”.
docs/Rules/DSCUseVerboseMessageInDSCResource.md Adds default state + config/suppression guidance and improves description.
docs/Rules/DSCUseIdenticalParametersForDSC.md Adds default state + config/suppression guidance and improves description.
docs/Rules/DSCUseIdenticalMandatoryParametersForDSC.md Adds default state + config/suppression guidance and improves description (including MOF fencing).
docs/Rules/DSCStandardDSCFunctionsInResource.md Adds default state, improves examples, and adds config/suppression guidance.
docs/Rules/DSCReturnCorrectTypesForDSCFunctions.md Adds default state, improves examples, and adds config/suppression guidance.
docs/Rules/DSCDscTestsPresent.md Adds default state + config/suppression guidance and improves description.
docs/Rules/DSCDscExamplesPresent.md Adds default state + config/suppression guidance and improves description.
docs/Rules/AvoidUsingWriteHost.md Adds default state + config/suppression guidance; rewrites description and normalizes links.
docs/Rules/AvoidUsingWMICmdlet.md Adds default state + config/suppression guidance and improves description and examples.
docs/Rules/AvoidUsingUsernameAndPasswordParams.md Adds default state + config/suppression guidance and improves description.
docs/Rules/AvoidUsingPositionalParameters.md Adds default state, examples, and restructures config + parameter docs.
docs/Rules/AvoidUsingPlainTextForPassword.md Adds default state + config/suppression guidance and adds SecureString link ref.
docs/Rules/AvoidUsingInvokeExpression.md Adds default state + config/suppression guidance and improves description.
docs/Rules/AvoidUsingEmptyCatchBlock.md Adds default state + config/suppression guidance and improves description.
docs/Rules/AvoidUsingDoubleQuotesForConstantString.md Adds default state + config/parameter docs and expands description.
docs/Rules/AvoidUsingDeprecatedManifestFields.md Adds default state + config/suppression guidance and improves description.
docs/Rules/AvoidUsingConvertToSecureStringWithPlainText.md Adds default state + config/suppression guidance and adds SecretStore recommendation link ref.
docs/Rules/AvoidUsingComputerNameHardcoded.md Adds default state + config/suppression guidance and improves description/examples.
docs/Rules/AvoidUsingCmdletAliases.md Adds default state + config/suppression guidance and adds examples.
docs/Rules/AvoidUsingBrokenHashAlgorithms.md Adds default state + config/suppression guidance and improves description.
docs/Rules/AvoidUsingArrayList.md Adds default state + config/parameter docs and updates references.
docs/Rules/AvoidUsingAllowUnencryptedAuthentication.md Adds default state + config/suppression guidance and improves description.
docs/Rules/AvoidTrailingWhitespace.md Adds default state + examples and config/suppression guidance.
docs/Rules/AvoidShouldContinueWithoutForce.md Adds default state + config/suppression guidance and adds link refs.
docs/Rules/AvoidSemicolonsAsLineTerminators.md Adds default state + config/parameter docs and improves description/examples.
docs/Rules/AvoidReservedWordsAsFunctionNames.md Adds default state + config/suppression guidance and normalizes links.
docs/Rules/AvoidOverwritingBuiltInCmdlets.md Adds default state, expands description/examples, and updates configuration guidance.
docs/Rules/AvoidNullOrEmptyHelpMessageAttribute.md Adds default state + config/suppression guidance and improves description.
docs/Rules/AvoidMultipleTypeAttributes.md Adds default state + config/suppression guidance and improves description.
docs/Rules/AvoidLongLines.md Adds default state, examples, and expands config + parameter docs.
docs/Rules/AvoidInvokingEmptyMembers.md Adds default state + config/suppression guidance and improves description and references.
docs/Rules/AvoidGlobalVars.md Adds default state + config/suppression guidance and expands description/examples.
docs/Rules/AvoidGlobalFunctions.md Adds default state + config/suppression guidance and improves description.
docs/Rules/AvoidGlobalAliases.md Adds default state + config/suppression guidance and improves description.
docs/Rules/AvoidExclaimOperator.md Adds default state, improves description, and expands config/parameter docs.
docs/Rules/AvoidDynamicallyCreatingVariableNames.md Adds default state, improves description, and restructures config/refs (contains one broken Learn link path).
docs/Rules/AvoidDefaultValueSwitchParameter.md Adds default state + config/suppression guidance and normalizes links.
docs/Rules/AvoidDefaultValueForMandatoryParameter.md Adds default state + config/suppression guidance and improves description.
docs/Rules/AvoidAssignmentToAutomaticVariable.md Adds default state + config/suppression guidance and improves description/examples.
docs/Rules/AlignAssignmentStatement.md Adds default state, improves examples, and expands config/parameter documentation.
docs/Cmdlets/Test-ScriptAnalyzerSettingsFile.md Adds/refreshes cmdlet help content (contains a small grammar error in Quiet description).
docs/Cmdlets/PSScriptAnalyzer.md Bumps help version and adds the new settings-file cmdlets to the landing page list.
docs/Cmdlets/New-ScriptAnalyzerSettingsFile.md Adds/refreshes cmdlet help content and improves structure/formatting.
docs/Cmdlets/Invoke-ScriptAnalyzer.md Refreshes examples/output formatting and documents ParseError as a valid -Severity value.
docs/Cmdlets/Invoke-Formatter.md Minor formatting tweak (blank line after synopsis heading).
Comments suppressed due to low confidence (1)

docs/Rules/UseConsistentParametersKind.md:56

  • The Parameters section documents only Enable, but the rule also supports a ParametersKind option. Without documenting it, users can't discover the setting or its valid values.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Comment thread docs/Cmdlets/Test-ScriptAnalyzerSettingsFile.md Outdated
Comment thread docs/Rules/AvoidDynamicallyCreatingVariableNames.md Outdated
Comment thread docs/Rules/UseSingularNouns.md Outdated
Comment thread docs/Rules/UseConsistentParametersKind.md
@sdwheeler
Apply suggestions from code review
273992b 
Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
@sdwheeler

Sean Wheeler (sdwheeler) commented Jul 23, 2026

Copy link
Copy Markdown
Collaborator Author

Patrick Meinecke (@SeeminglyScience) We can skip the failed docs test for now. Please merge.

@sdwheeler
Sean Wheeler (sdwheeler) force-pushed the sdw-w591525-rule-sync-docs-src branch from 14d0c4f to 6806e84 Compare July 23, 2026 18:57
@sdwheeler
Sean Wheeler (sdwheeler) force-pushed the sdw-w591525-rule-sync-docs-src branch from 6806e84 to d04cdc6 Compare July 23, 2026 23:05
@sdwheeler

Sean Wheeler (sdwheeler) commented Jul 25, 2026

Copy link
Copy Markdown
Collaborator Author

Patrick Meinecke (@SeeminglyScience) The docs tests pass now. This latest failure was in an existing test that has passed on previous runs. I think this is a transient problem.

@sdwheeler

Sean Wheeler (sdwheeler) commented Jul 25, 2026

Copy link
Copy Markdown
Collaborator Author

Close/reopen

@sdwheeler

Sean Wheeler (sdwheeler) commented Jul 25, 2026

Copy link
Copy Markdown
Collaborator Author

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

Copilot code review Copilot
Copilot review effort, defaults to Lite
Applies to this pull request for everyone.Learn more about Copilot code review.
Copilot left review comments
@michaeltlombardi Mikey Lombardi (He/Him) (michaeltlombardi) Awaiting requested review from michaeltlombardi michaeltlombardi is a code owner
@bergmeister Christoph Bergmeister (bergmeister) Awaiting requested review from bergmeister bergmeister is a code owner

At least 1 approving review is required to merge this pull request.

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

Invoke-ScriptAnalyzer does not report a parse failure in a param() block caused by a missing parameter separator comma.

2 participants

@sdwheeler