Sync docs changes from docs repo

[Sean Wheeler (sdwheeler)]

Sync docs changes from docs repo

• Fixes Invoke-ScriptAnalyzer does not report a parse failure in a param() block caused by a missing parameter separator comma. #2192
• Closes Add missing Severity entry for Invoke-ScriptAnalyzer docs #2193 - Duplicate PR
  • This PR includes the change from Liam and other edits to that article.
• Fixes AB#591525
• This PR also fixes the documentation Pester test for the rules docs

[Copilot]

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.

[Sean Wheeler (sdwheeler)]

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

[Sean Wheeler (sdwheeler)]

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.

[Sean Wheeler (sdwheeler)]

Close/reopen

[Sean Wheeler (sdwheeler)]

Patrick Meinecke (@SeeminglyScience) I reran the build. Now it's failing in a different place in the Windows tests. The docs test pass.

[Copilot]

🟡 Changes recommended

Documentation validation contains no-op checks, and several examples and defaults contradict the implemented rules.

Get a fresh assessment by requesting another Copilot review.

Review details

Suppressed comments (1)

docs/Rules/DSCReturnCorrectTypesForDSCFunctions.md:125

• This “noncompliant” class shows the correct return declarations for Set and Test, and merely omits Get, which belongs to PSDSCStandardDSCFunctionsInResource. It therefore does not illustrate incorrect return types for this rule; include all three methods with intentionally wrong return declarations.

• Files reviewed: 86/86 changed files
• Comments generated: 19
• Review effort level: Balanced

[Christoph Bergmeister (bergmeister)]

Sean Wheeler (@sdwheeler) please have a look at more detailed Copilot review that I kicked off whether there is anything to add onto backlog as it would obviously need to be fixed in docs first. Otherwise happy because sync is sync

[Sean Wheeler (sdwheeler)]

Christoph Bergmeister (@bergmeister) Mikey Lombardi (He/Him) (@michaeltlombardi) Ready to merge

[Sean Wheeler (sdwheeler)]

Christoph Bergmeister (@bergmeister) This is ready to merge

[Copilot]

Copilot review overview

🟡 Changes recommended

Documentation tests have validation defects, and the cmdlet help version conflicts with the module version.

Get a fresh assessment by requesting another Copilot review.

Review effort: Balanced
Findings: 2 · 8

Open (10)

• The implementation checks RootModule, NestedModules, and ScriptsToProcess; it does not check…
• The rule checks wildcard exports only for FunctionsToExport and CmdletsToExport; its…
• Correct the documented desktop PowerShell fallback profile · New
• Use the required flat Configure parameter layout · New
• Document all password parameter matching behavior · New
• Document static Console Write calls as detected · New
• Fix the case-sensitive Further reading link · New
• Limit the suppression description to supported expressions · New
• Remove unsupported type-name casing coverage · New
• Clarify UseOutputTypeCorrectly applies to advanced functions · New

Resolved since last review (17)

• This validation is currently a no-op because $targetFile is undefined. In addition, $ruleTable…
• $targetFile is never assigned, so it is $null and $isRuleFile is always false. Consequently,…
• Get-CimInstance is absent from the selected Ubuntu 18.04 / PowerShell 6.2.4 profile while present…
• Removing this comma makes the Test-TargetResource parameter block syntactically invalid, so the…
• The visitor also reports top-level Write-Host calls; it only skips calls nested in functions…
• The rule intentionally reports only when there are more than two positional arguments, but this…
• These are not the defaults implemented by the rule, and neither named profile is shipped.…
• core-7.0.0-windows is not a shipped settings profile, so this example causes…
• This purported noncompliant line is only 115 characters long, so it does not exceed the documented…
• This test only validates rows that already exist. If a rule's table row and link definition are…
• The exception is reversed. The implementation skips the spacing check when the opening brace is…
• The rule's optional empty-line check is for an empty line before a closing brace…
• Correct the spelling of “without.”
• The code line has no whitespace after the backtick, so it is actually compliant and does not…
• The requirement applies to properties marked Key or Required; a property does not need both…
• The code line has no trailing space after the backtick, so this “noncompliant” sample is identical…
• Untyped parameters are valid and are not reported by this rule; it only rejects more than one type…