Derive PSScriptAnalyzer settings from PowerShell standard; document GitHub Actions linters

Author: MariusStorhaug

.github/linters/.powershell-psscriptanalyzer.psd1

@@ -0,0 +1,55 @@
+# PSScriptAnalyzer settings — the enforcement mechanism for the PowerShell coding
+# standard (src/docs/Coding-Standards/PowerShell/index.md). The standard is the
+# source of truth; every rule configured here is derived from it. Change a rule by
+# changing the standard first, then reflect it here — never the other way around.
+#
+# super-linter discovers this file automatically as POWERSHELL_CONFIG_FILE
+# (.powershell-psscriptanalyzer.psd1) under .github/linters.
+@{
+    # Run the full default rule set — approved verbs, singular nouns, alias bans,
+    # $null-on-the-left comparisons, Invoke-Expression, unused variables, and the
+    # rest — then tighten the formatting rules below to match the standard.
+    IncludeDefaultRules = $true
+
+    # Gate on errors and warnings; both map to rules the standard requires.
+    Severity = @('Error', 'Warning')
+
+    Rules = @{
+        # One True Brace Style: opening brace on the statement line, closing brace
+        # on its own line with no blank line before it. NewLineAfter stays false on
+        # the close brace so else / elseif / catch / finally sit on the same line as
+        # the preceding brace ("} else {"), as the standard requires.
+        PSPlaceOpenBrace = @{
+            Enable = $true
+            OnSameLine = $true
+            NewLineAfter = $true
+            IgnoreOneLineBlock = $true
+        }
+        PSPlaceCloseBrace = @{
+            Enable = $true
+            NewLineAfter = $false
+            IgnoreOneLineBlock = $true
+            NoEmptyLineBefore = $true
+        }
+
+        # Indent with four spaces, never tabs.
+        PSUseConsistentIndentation = @{
+            Enable = $true
+            Kind = 'space'
+            IndentationSize = 4
+            PipelineIndentation = 'IncreaseIndentationForFirstPipeline'
+        }
+
+        # One space around operators and after commas, and consistent brace and
+        # parenthesis spacing.
+        PSUseConsistentWhitespace = @{
+            Enable = $true
+            CheckInnerBrace = $true
+            CheckOpenBrace = $true
+            CheckOpenParen = $true
+            CheckOperator = $true
+            CheckPipe = $true
+            CheckSeparator = $true
+        }
+    }
+}

.github/scripts/Test-DocumentationLink.ps1

@@ -1,4 +1,4 @@
-#!/usr/bin/env pwsh
+#!/usr/bin/env pwsh
 #Requires -Version 7.0
 
 <#

.github/scripts/Update-DocumentationIndex.ps1

@@ -112,8 +112,8 @@ function Get-IndexTable {
         $rows.Add([pscustomobject]@{
                 Order = if ($Order.ContainsKey($key)) { $Order[$key] } else { 10000 }
                 Title = if ($meta.ContainsKey('title')) { $meta['title'] } else { $child.Name }
-                Link  = "$($child.Name)/index.md"
-                Desc  = if ($meta.ContainsKey('description')) { $meta['description'] } else { '' }
+                Link = "$($child.Name)/index.md"
+                Desc = if ($meta.ContainsKey('description')) { $meta['description'] } else { '' }
             })
     }
     foreach ($child in $files) {
@@ -122,8 +122,8 @@ function Get-IndexTable {
         $rows.Add([pscustomobject]@{
                 Order = if ($Order.ContainsKey($key)) { $Order[$key] } else { 10000 }
                 Title = if ($meta.ContainsKey('title')) { $meta['title'] } else { [System.IO.Path]::GetFileNameWithoutExtension($child.Name) }
-                Link  = $child.Name
-                Desc  = if ($meta.ContainsKey('description')) { $meta['description'] } else { '' }
+                Link = $child.Name
+                Desc = if ($meta.ContainsKey('description')) { $meta['description'] } else { '' }
             })
     }
 

.github/scripts/Wait-CopilotReview.ps1

@@ -132,7 +132,7 @@ try {
             Select-Object -Last 1
 
         $processing = $lastRequestedAt -and
-            ((-not $lastReviewedAt) -or ([datetimeoffset] $lastRequestedAt -gt $lastReviewedAt))
+        ((-not $lastReviewedAt) -or ([datetimeoffset] $lastRequestedAt -gt $lastReviewedAt))
 
         if ($processing) {
             Write-Verbose "Copilot is already processing a review (requested $lastRequestedAt) - waiting for it."
@@ -219,13 +219,13 @@ try {
     }
 
     [pscustomobject]@{
-        Repository      = $Repository
-        PullRequest     = $PullRequest
-        ReviewState     = $review.state
-        SubmittedAt     = $review.submittedAt
+        Repository = $Repository
+        PullRequest = $PullRequest
+        ReviewState = $review.state
+        SubmittedAt = $review.submittedAt
         NewCommentCount = $newComments.Count
-        NewComments     = $newComments
-        Blessed         = $blessed
+        NewComments = $newComments
+        Blessed = $blessed
     }
 
     if ($blessed) {

src/docs/Coding-Standards/GitHub-Actions.md

@@ -258,6 +258,23 @@ appears.
   `main.<ext>` sits at the action root for a single-file action, or under `src/`
   as the entry point alongside the other modules.
 
+## Toolchain
+
+Two linters enforce this standard in CI, and their configuration is derived from
+it — the rules above are the source of truth:
+
+- **[actionlint](https://github.com/rhysd/actionlint)** checks workflow
+  correctness: expression syntax, job and step wiring, runner labels, and the
+  shell of every `run:` step through shellcheck.
+- **[zizmor](https://docs.zizmor.sh/)** audits workflow security, flagging the
+  failures this standard exists to prevent: unpinned actions, excessive
+  `permissions`, template injection from untrusted input, `secrets: inherit`,
+  and persisted credentials.
+
+Both run through [super-linter](https://github.com/super-linter/super-linter) on
+every push and pull request, so a workflow that breaks this standard fails the
+build.
+
 ```text
 # Single-file action — main.<ext> at the action root
 .github/actions/link-check/