CI quality gates (Pester runner + PSScriptAnalyzer + artifacts + SARIF)

.github/workflows/ci.yml

@@ -17,7 +17,6 @@ jobs:
     name: Pester (${{ matrix.os }})
     runs-on: ${{ matrix.os }}
 
-    # add job-scoped permissions needed for artifact upload
     permissions:
       contents: read
       actions: write
@@ -32,15 +31,78 @@ jobs:
 
       - name: Run Pester
         shell: pwsh
-        run: pwsh -NoProfile -File ./tools/run-tests.ps1 -CI
+        run: pwsh -NoProfile -File ./tools/Invoke-IdlePesterTests.ps1 -CI
 
-      - name: Upload test results
+      - name: Upload Pester artifacts
         if: always()
-        continue-on-error: true
         uses: actions/upload-artifact@v6
         with:
-          name: test-results-${{ matrix.os }}
-          path: artifacts/test-results.xml
+          name: pester-artifacts-${{ matrix.os }}
+          if-no-files-found: warn
+          path: |
+            artifacts/test-results.xml
+            artifacts/coverage.xml
+
+  lint:
+    name: PSScriptAnalyzer
+    runs-on: ubuntu-latest
+
+    permissions:
+      contents: read
+      actions: read
+      security-events: write
+
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Run PSScriptAnalyzer
+        shell: pwsh
+        run: pwsh -NoProfile -File ./tools/Invoke-IdleScriptAnalyzer.ps1 -CI
+
+      - name: Upload PSScriptAnalyzer artifacts
+        if: always()
+        uses: actions/upload-artifact@v6
+        with:
+          name: psscriptanalyzer-artifacts
+          if-no-files-found: warn
+          path: |
+            artifacts/pssa-results.json
+            artifacts/pssa-results.sarif
+
+      - name: Decide whether to upload SARIF
+        id: sarif_check
+        shell: pwsh
+        run: |
+          Set-StrictMode -Version Latest
+          $ErrorActionPreference = 'Stop'
+
+          $jsonPath = Join-Path -Path $env:GITHUB_WORKSPACE -ChildPath 'artifacts/pssa-results.json'
+          $sarifPath = Join-Path -Path $env:GITHUB_WORKSPACE -ChildPath 'artifacts/pssa-results.sarif'
+
+          $shouldUpload = $false
+
+          if ((Test-Path -LiteralPath $jsonPath) -and (Test-Path -LiteralPath $sarifPath)) {
+            $content = Get-Content -LiteralPath $jsonPath -Raw
+            if ($content) {
+              $items = $content | ConvertFrom-Json
+              if ($null -ne $items) {
+                # ConvertFrom-Json returns PSCustomObject for single element, array for multiple.
+                if ($items -is [System.Array]) {
+                  $shouldUpload = ($items.Count -gt 0)
+                } else {
+                  $shouldUpload = $true
+                }
+              }
+            }
+          }
+
+          "should_upload_sarif=$($shouldUpload.ToString().ToLowerInvariant())" | Out-File -FilePath $env:GITHUB_OUTPUT -Append -Encoding utf8
+
+      - name: Upload SARIF to GitHub Code Scanning
+        if: github.event_name == 'push' && github.ref == 'refs/heads/main' && steps.sarif_check.outputs.should_upload_sarif == 'true'
+        uses: github/codeql-action/upload-sarif@v4
+        with:
+          sarif_file: artifacts/pssa-results.sarif
 
   docs-cmdlet-reference:
     name: Verify cmdlet reference is up to date
@@ -63,12 +125,11 @@ jobs:
               # Ignore if not supported in this environment
             }
           }
-          
+
           # platyPS is pinned for deterministic Markdown output.
           # See CONTRIBUTING.md for upgrade procedure.
-
           Install-Module -Name platyPS -RequiredVersion 0.14.2 -Scope CurrentUser -Force -AllowClobber -ErrorAction Stop
-      
+
       - name: Debug platyPS version
         shell: pwsh
         run: |

CONTRIBUTING.md

@@ -123,14 +123,54 @@ Pull Requests must:
 
 A contribution is complete when:
 
-- all tests pass (`Invoke-Pester -Path ./tests`)
-- no architecture rules are violated (see `docs/01-architecture.md`)
+- all tests pass (`pwsh -NoProfile -File ./tools/Invoke-IdlePesterTests.ps1`)
+- static analysis passes (`pwsh -NoProfile -File ./tools/Invoke-IdleScriptAnalyzer.ps1`)
+- no architecture rules are violated (see `docs/advanced/architecture.md`)
 - public APIs are documented (comment-based help for exported functions)
 - documentation is updated where required:
   - README.md (only high-level overview + pointers)
   - docs/ (usage/concepts/examples)
   - provider/step module READMEs if behavior/auth changes
 
+## Local quality checks
+
+IdLE provides canonical scripts under `tools/` so you can reproduce the same checks locally that CI runs.
+
+### Run tests (Pester)
+
+Run the test suite:
+
+- `pwsh -NoProfile -File ./tools/Invoke-IdlePesterTests.ps1`
+
+To generate CI-like artifacts (test results + coverage) under `artifacts/`:
+
+- `pwsh -NoProfile -File ./tools/Invoke-IdlePesterTests.ps1 -CI`
+
+Outputs:
+
+- `artifacts/test-results.xml` (NUnitXml)
+- `artifacts/coverage.xml` (coverage report)
+
+### Run static analysis (PSScriptAnalyzer)
+
+Run PSScriptAnalyzer using the repository settings:
+
+- `pwsh -NoProfile -File ./tools/Invoke-IdleScriptAnalyzer.ps1`
+
+To generate CI-like artifacts under `artifacts/` (including SARIF for GitHub Code Scanning):
+
+- `pwsh -NoProfile -File ./tools/Invoke-IdleScriptAnalyzer.ps1 -CI`
+
+Outputs:
+
+- `artifacts/pssa-results.json` (summary)
+- `artifacts/pssa-results.sarif` (SARIF)
+
+The rule set is defined in `PSScriptAnalyzerSettings.psd1` at the repository root.
+The runner pins tool versions for deterministic CI results; update pins intentionally and document the change in the PR.
+
+> Note: `artifacts/` is a build output folder and should not be committed.
+
 ---
 
 ## Generated cmdlet reference (platyPS)
@@ -253,11 +293,6 @@ To fix a failing PR:
 
 Repository maintainers should configure branch protection so that required status checks include this workflow.
 
-
-
-
-
-
 ## Documentation
 
 Keep docs short and linkable:
@@ -269,7 +304,7 @@ Keep docs short and linkable:
 Key links:
 
 - Docs map: `docs/00-index.md`
-- Architecture: `docs/01-architecture.md`
+- Architecture: `docs/advanced/architecture.md`
 - Examples: `docs/02-examples.md`
 - Coding & in-code documentation rules: `STYLEGUIDE.md`
 

PSScriptAnalyzerSettings.psd1

@@ -0,0 +1,58 @@
+# PSScriptAnalyzer settings for IdentityLifecycleEngine (IdLE)
+#
+# This file is intentionally data-only (no script blocks, no expressions).
+# It is used by CI and can also be referenced from VS Code workspace settings.
+#
+# Notes:
+# - We explicitly list IncludeRules to keep the first rollout focused and low-noise.
+# - Formatting rules are enabled to align with STYLEGUIDE.md (4 spaces, consistent whitespace).
+
+@{
+    Severity     = @('Error', 'Warning')
+
+    IncludeRules = @(
+        # Naming / API hygiene
+        'PSUseApprovedVerbs',
+        'PSAvoidGlobalVars',
+        'PSAvoidUsingCmdletAliases',
+        'PSAvoidUsingPositionalParameters',
+        'PSUseCorrectCasing',
+
+        # Common correctness issues
+        'PSAvoidUsingEmptyCatchBlock',
+        'PSReviewUnusedParameter',
+        'PSUseDeclaredVarsMoreThanAssignments',
+        'PSAvoidTrailingWhitespace',
+
+        # Security / risky constructs
+        'PSAvoidUsingInvokeExpression',
+        'PSAvoidUsingPlainTextForPassword',
+        'PSAvoidUsingConvertToSecureStringWithPlainText',
+
+        # Style / formatting (enabled explicitly)
+        'PSUseConsistentIndentation',
+        'PSUseConsistentWhitespace'
+    )
+
+    Rules        = @{
+        PSUseConsistentIndentation = @{
+            Enable             = $true
+            IndentationSize    = 4
+            PipelineIndentation = 'IncreaseIndentationForFirstPipeline'
+            Kind               = 'space'
+        }
+
+        PSUseConsistentWhitespace  = @{
+            Enable                          = $true
+            CheckInnerBrace                 = $true
+            CheckOpenBrace                  = $true
+            CheckOpenParen                  = $true
+            CheckOperator                   = $true
+            CheckPipe                       = $true
+            CheckPipeForRedundantWhitespace = $false
+            CheckSeparator                  = $true
+            CheckParameter                  = $false
+            IgnoreAssignmentOperatorInsideHashTable = $false
+        }
+    }
+}

STYLEGUIDE.md

@@ -99,6 +99,20 @@ Providers:
 - No live system calls in unit tests
 - Providers require contract tests
 
+## Quality Gates
+
+IdLE uses static analysis and automated tests to keep the codebase consistent and maintainable.
+
+- **PSScriptAnalyzer** is the required linter for PowerShell code.
+  - Repository policy is defined in `PSScriptAnalyzerSettings.psd1` (repo root).
+  - Run locally via `pwsh -NoProfile -File ./tools/Invoke-IdleScriptAnalyzer.ps1`.
+  - CI publishes analyzer outputs under `artifacts/`.
+  - On default-branch runs, CI also uploads SARIF to GitHub Code Scanning.
+
+- **Pester** is the required test framework.
+  - Run locally via `pwsh -NoProfile -File ./tools/Invoke-IdlePesterTests.ps1`.
+  - CI publishes test results and coverage under `artifacts/`.
+
 ---
 
 ## Documentation Responsibilities

docs/advanced/releases.md

@@ -63,11 +63,19 @@ Pre-release tags do **not** publish to PowerShell Gallery.
    pwsh -NoProfile -File ./tools/Set-IdleModuleVersion.ps1 -TargetVersion 1.2.0
    ```
 
-3. Run tests:
+3. Run quality checks locally:
 
-   ```powershell
-   pwsh -NoProfile -File ./tools/run-tests.ps1
-   ```
+   - Pester tests:
+
+     ```powershell
+     pwsh -NoProfile -File ./tools/Invoke-IdlePesterTests.ps1
+     ```
+
+   - Static analysis (PSScriptAnalyzer):
+
+     ```powershell
+     pwsh -NoProfile -File ./tools/Invoke-IdleScriptAnalyzer.ps1
+     ```
 
 4. Commit and push the changes.
 5. Open a Pull Request to `main` and wait for CI to pass.