🚀 [Feature]: Enhance settings file handling in Invoke-ScriptAnalyzer script

MariusStorhaug · MariusStorhaug · commit af6bef38763b · 2025-10-11T18:31:32.000+02:00
diff --git a/.github/workflows/Action-Test.yml b/.github/workflows/Action-Test.yml
@@ -89,6 +89,29 @@ jobs:
           Write-Host "Outcome: ${{ steps.action-test.outcome }}"
           Write-Host "Conclusion: ${{ steps.action-test.conclusion }}"
 
+  ActionTestSrcWithManifestDefault:
+    name: Action-Test - [Src-WithManifest-Default]
+    runs-on: ubuntu-latest
+    outputs:
+      Outcome: ${{ steps.action-test.outcome }}
+      Conclusion: ${{ steps.action-test.conclusion }}
+    steps:
+      - name: Checkout repo
+        uses: actions/checkout@v5
+
+      - name: Action-Test
+        uses: ./
+        id: action-test
+        with:
+          Path: src
+          WorkingDirectory: tests/srcWithManifestTestRepo
+
+      - name: Status
+        shell: pwsh
+        run: |
+          Write-Host "Outcome: ${{ steps.action-test.outcome }}"
+          Write-Host "Conclusion: ${{ steps.action-test.conclusion }}"
+
   ActionTestOutputs:
     name: Action-Test - [outputs]
     runs-on: ubuntu-latest
@@ -118,6 +141,7 @@ jobs:
       - ActionTestSrcSourceCode
       - ActionTestSrcCustom
       - ActionTestSrcWithManifest
+      - ActionTestSrcWithManifestDefault
       - ActionTestOutputs
     if: always()
     runs-on: ubuntu-latest
@@ -128,6 +152,8 @@ jobs:
       ActionTestSrcCustomConclusion: ${{ needs.ActionTestSrcCustom.outputs.Conclusion }}
       ActionTestSrcWithManifestOutcome: ${{ needs.ActionTestSrcWithManifest.outputs.Outcome }}
       ActionTestSrcWithManifestConclusion: ${{ needs.ActionTestSrcWithManifest.outputs.Conclusion }}
+      ActionTestSrcWithManifestDefaultOutcome: ${{ needs.ActionTestSrcWithManifestDefault.outputs.Outcome }}
+      ActionTestSrcWithManifestDefaultConclusion: ${{ needs.ActionTestSrcWithManifestDefault.outputs.Conclusion }}
       ActionTestOutputsOutcome: ${{ needs.ActionTestOutputs.outputs.Outcome }}
       ActionTestOutputsConclusion: ${{ needs.ActionTestOutputs.outputs.Conclusion }}
     steps:
diff --git a/README.md b/README.md
@@ -88,16 +88,41 @@ The action provides the following outputs:
    Choose a path for your code to test into the `Path` input. This can be a
    directory or a file.
 
-2. **Configure settings file**
+2. **Configure settings file (Optional)**
    Create a custom settings file to customize the analysis. The settings file is
    a hashtable that defines the rules to include, exclude, or customize. The
    settings file is in the format of a `.psd1` file.
 
-   By default, the action looks for a settings file at:
-   `.github/linters/.powershell-psscriptanalyzer.psd1`
+   **Settings File Precedence:**
 
-   You can override this by setting the `SettingsFilePath` input to point to your
-   custom settings file.
+   The action determines which settings to use in the following order:
+
+   1. **Custom Path**: If you provide a `SettingsFilePath` input, the action uses that file.
+   2. **Default Action Path**: If no `SettingsFilePath` is provided, the action looks for a settings file at:
+      `.github/linters/.powershell-psscriptanalyzer.psd1`
+   3. **PSScriptAnalyzer Defaults**: If no settings file is found in either location, the action uses
+      the default settings from the `Invoke-ScriptAnalyzer` cmdlet (all built-in rules with default severity).
+
+   **Example configurations:**
+
+   ```yaml
+   # Use a custom settings file
+   - uses: PSModule/Invoke-ScriptAnalyzer@v2
+     with:
+       Path: src
+       SettingsFilePath: config/custom-rules.psd1
+
+   # Use the default action path (.github/linters/.powershell-psscriptanalyzer.psd1)
+   - uses: PSModule/Invoke-ScriptAnalyzer@v2
+     with:
+       Path: src
+
+   # Use PSScriptAnalyzer defaults (no settings file)
+   - uses: PSModule/Invoke-ScriptAnalyzer@v2
+     with:
+       Path: src
+       SettingsFilePath: ''  # Explicitly skip settings file
+   ```
 
    For more info on how to create a settings file, see the [Settings Documentation](./Settings.md) file.
 
diff --git a/scripts/main.ps1 b/scripts/main.ps1
@@ -2,17 +2,31 @@
 $testPath = Resolve-Path -Path "$PSScriptRoot/tests/PSScriptAnalyzer" | Select-Object -ExpandProperty Path
 $path = [string]::IsNullOrEmpty($env:PSMODULE_INVOKE_SCRIPTANALYZER_INPUT_Path) ? '.' : $env:PSMODULE_INVOKE_SCRIPTANALYZER_INPUT_Path
 $codePath = Resolve-Path -Path $path | Select-Object -ExpandProperty Path
-$settingsFilePath = Resolve-Path -Path $env:PSMODULE_INVOKE_SCRIPTANALYZER_INPUT_SettingsFilePath | Select-Object -ExpandProperty Path
+
+# Try to resolve the settings file path, but allow it to be null if not found
+$settingsFilePath = $null
+if (-not [string]::IsNullOrEmpty($env:PSMODULE_INVOKE_SCRIPTANALYZER_INPUT_SettingsFilePath)) {
+    try {
+        $resolvedPath = Resolve-Path -Path $env:PSMODULE_INVOKE_SCRIPTANALYZER_INPUT_SettingsFilePath -ErrorAction Stop | Select-Object -ExpandProperty Path
+        if (Test-Path -Path $resolvedPath) {
+            $settingsFilePath = $resolvedPath
+            Write-Information "Using settings file: $settingsFilePath"
+        }
+    } catch {
+        Write-Warning "Settings file not found at path: $($env:PSMODULE_INVOKE_SCRIPTANALYZER_INPUT_SettingsFilePath). Using default settings."
+    }
+}
+
+if ($null -eq $settingsFilePath) {
+    Write-Information 'No settings file specified or found. Using default PSScriptAnalyzer settings.'
+}
 
 [pscustomobject]@{
     CodePath         = $codePath
     TestPath         = $testPath
     SettingsFilePath = $settingsFilePath
 } | Format-List | Out-String
 
-if (!(Test-Path -Path $settingsFilePath)) {
-    throw "Settings file not found at path: $settingsFilePath"
-}
 Set-GitHubOutput -Name CodePath -Value $codePath
 Set-GitHubOutput -Name TestPath -Value $testPath
 Set-GitHubOutput -Name SettingsFilePath -Value $settingsFilePath
diff --git a/scripts/tests/PSScriptAnalyzer/PSScriptAnalyzer.Tests.ps1 b/scripts/tests/PSScriptAnalyzer/PSScriptAnalyzer.Tests.ps1
@@ -11,17 +11,25 @@
     Justification = 'Write-Host is used for log output.'
 )]
 [CmdLetBinding()]
-Param(
+param(
     [Parameter(Mandatory)]
     [string] $Path,
 
-    [Parameter(Mandatory)]
+    [Parameter()]
     [string] $SettingsFilePath
 )
 
 BeforeDiscovery {
-    LogGroup "PSScriptAnalyzer tests using settings file [$SettingsFilePath]" {
-        $settings = Import-PowerShellDataFile -Path $SettingsFilePath
+    $hasSettingsFile = -not [string]::IsNullOrEmpty($SettingsFilePath)
+    $settingsDescription = $hasSettingsFile ? "settings file [$SettingsFilePath]" : 'default settings'
+
+    LogGroup "PSScriptAnalyzer tests using $settingsDescription" {
+        if ($hasSettingsFile) {
+            $settings = Import-PowerShellDataFile -Path $SettingsFilePath
+        } else {
+            $settings = @{}
+        }
+
         $rules = [Collections.Generic.List[System.Collections.Specialized.OrderedDictionary]]::new()
         $ruleObjects = Get-ScriptAnalyzerRule -Verbose:$false | Sort-Object -Property Severity, CommonName
         $Severeties = $ruleObjects | Select-Object -ExpandProperty Severity -Unique
@@ -65,13 +73,18 @@ BeforeDiscovery {
 
 Describe 'PSScriptAnalyzer' {
     BeforeAll {
-        $relativeSettingsFilePath = if ($SettingsFilePath.StartsWith($PSScriptRoot)) {
-            $SettingsFilePath.Replace($PSScriptRoot, 'Action:').Trim('\').Trim('/')
-        } elseif ($SettingsFilePath.StartsWith($env:GITHUB_WORKSPACE)) {
-            $SettingsFilePath.Replace($env:GITHUB_WORKSPACE, 'Workspace:').Trim('\').Trim('/')
-        } else {
-            $SettingsFilePath
+        $hasSettingsFile = -not [string]::IsNullOrEmpty($SettingsFilePath)
+
+        if ($hasSettingsFile) {
+            $relativeSettingsFilePath = if ($SettingsFilePath.StartsWith($PSScriptRoot)) {
+                $SettingsFilePath.Replace($PSScriptRoot, 'Action:').Trim('\').Trim('/')
+            } elseif ($SettingsFilePath.StartsWith($env:GITHUB_WORKSPACE)) {
+                $SettingsFilePath.Replace($env:GITHUB_WORKSPACE, 'Workspace:').Trim('\').Trim('/')
+            } else {
+                $SettingsFilePath
+            }
         }
+
         $Path = Resolve-Path -Path $Path | Select-Object -ExpandProperty Path
         $relativePath = if ($Path.StartsWith($PSScriptRoot)) {
             $Path.Replace($PSScriptRoot, 'Action:').Trim('\').Trim('/').Replace('\', '/')
@@ -88,9 +101,26 @@ Describe 'PSScriptAnalyzer' {
             GITHUB_WORKSPACE         = $env:GITHUB_WORKSPACE
         }
 
-        LogGroup "Invoke-ScriptAnalyzer -Path [$relativePath] -Settings [$relativeSettingsFilePath]" {
-            $testResults = Invoke-ScriptAnalyzer -Path $Path -Settings $SettingsFilePath -Recurse -Verbose
+        $invokeParams = @{
+            Path    = $Path
+            Recurse = $true
+            Verbose = $true
+        }
+
+        if ($hasSettingsFile) {
+            $invokeParams['Settings'] = $SettingsFilePath
         }
+
+        $logMessage = if ($hasSettingsFile) {
+            "Invoke-ScriptAnalyzer -Path [$relativePath] -Settings [$relativeSettingsFilePath]"
+        } else {
+            "Invoke-ScriptAnalyzer -Path [$relativePath] -Recurse (using default settings)"
+        }
+
+        LogGroup $logMessage {
+            $testResults = Invoke-ScriptAnalyzer @invokeParams
+        }
+
         LogGroup "TestResults [$($testResults.Count)]" {
             $testResults | Select-Object -Property * | Format-List | Out-String -Stream | ForEach-Object {
                 Write-Verbose $_ -Verbose
diff --git a/tests/Get-AggregatedStatus.ps1 b/tests/Get-AggregatedStatus.ps1
@@ -35,6 +35,11 @@ $ActionTestSrcWithManifestOutcomeResult = $env:ActionTestSrcWithManifestOutcome
 $ActionTestSrcWithManifestExpectedConclusion = 'success'
 $ActionTestSrcWithManifestConclusionResult = $env:ActionTestSrcWithManifestConclusion -eq $ActionTestSrcWithManifestExpectedConclusion
 
+$ActionTestSrcWithManifestDefaultExpectedOutcome = 'success'
+$ActionTestSrcWithManifestDefaultOutcomeResult = $env:ActionTestSrcWithManifestDefaultOutcome -eq $ActionTestSrcWithManifestDefaultExpectedOutcome
+$ActionTestSrcWithManifestDefaultExpectedConclusion = 'success'
+$ActionTestSrcWithManifestDefaultConclusionResult = $env:ActionTestSrcWithManifestDefaultConclusion -eq $ActionTestSrcWithManifestDefaultExpectedConclusion
+
 $ActionTestOutputsExpectedOutcome = 'success'
 $ActionTestOutputsOutcomeResult = $env:ActionTestOutputsOutcome -eq $ActionTestOutputsExpectedOutcome
 $ActionTestOutputsExpectedConclusion = 'success'
@@ -68,6 +73,15 @@ $jobs = @(
         ExpectedConclusion = $ActionTestSrcWithManifestExpectedConclusion
         PassedConclusion   = $ActionTestSrcWithManifestConclusionResult
     },
+    [PSCustomObject]@{
+        Name               = 'Action-Test - [Src-WithManifest-Default]'
+        Outcome            = $env:ActionTestSrcWithManifestDefaultOutcome
+        ExpectedOutcome    = $ActionTestSrcWithManifestDefaultExpectedOutcome
+        PassedOutcome      = $ActionTestSrcWithManifestDefaultOutcomeResult
+        Conclusion         = $env:ActionTestSrcWithManifestDefaultConclusion
+        ExpectedConclusion = $ActionTestSrcWithManifestDefaultExpectedConclusion
+        PassedConclusion   = $ActionTestSrcWithManifestDefaultConclusionResult
+    },
     [PSCustomObject]@{
         Name               = 'Action-Test - [outputs]'
         Outcome            = $env:ActionTestOutputsOutcome
