ci: add PSScriptAnalyzer linting with repo settings

[blindzero]

Problem Statement

We have Pester tests and CI actions running but no linting or code analysis.

Proposed Solution

Add static analysis (PSScriptAnalyzer) to CI to enforce IdLE’s coding standards and provide early feedback during PR reviews. IdLE already defines coding/test/documentation standards in STYLEGUIDE.md and CONTRIBUTING.md; CI should help enforce them consistently.

Scope / Tasks

• Add PSScriptAnalyzerSettings.psd1 at repository root:
  • curated rule set aligned with IdLE style guide (approved verbs, readability, consistent formatting, etc.)
  • documented exclusions (if any), with rationale
• Add tool script tools/Run-IdleScriptAnalyzer.ps1:
  • installs/imports pinned PSScriptAnalyzer version (deterministic CI)
  • runs analysis on src/ (optionally tools/), excludes generated artifacts
  • outputs readable summary + returns non-zero exit code (gating)
• Update .github/workflows/ci.yml:
  • new job lint on ubuntu-latest
  • uploads analyzer results as artifact and/or SARIF (optional)
• Update docs:
  • CONTRIBUTING: how to run lint locally, how to fix common findings
  • STYLEGUIDE: mention that CI enforces selected rules (brief)
  • other docs for remarks as gate influences eg releases.md
• GitHub-native Code Scanning (SARIF) for PSScriptAnalyzer
  • Generate a SARIF report from PSScriptAnalyzer results (best-effort; do not block local runs).
  • Upload SARIF to GitHub Code Scanning using github/codeql-action/upload-sarif (or Microsoft’s PSScriptAnalyzer action that emits SARIF).
  • Ensure workflow has the required permission security-events: write.
  • Recommended trigger strategy:
    • Run PSScriptAnalyzer as a PR quality gate (fail on Errors).
    • Upload SARIF only on pushes to main (and optionally scheduled) to avoid permission issues on PRs from forks.
• Enable CodeQL for GitHub Actions workflows
  • Add a CodeQL workflow that scans GitHub Actions workflow YAML / action metadata (language: actions).
  • Run on:
    • push to main
    • pull_request targeting main (optional; depending on repo policy)
    • schedule (weekly) for continuous coverage

Acceptance Criteria

• CI contains a dedicated “Lint” (PSScriptAnalyzer) job.
• pwsh ./tools/Run-IdleScriptAnalyzer.ps1 runs locally and in CI.
• Findings policy is explicit (e.g., fail on Error only, warnings informational).
• Repo has an explicit settings file (PSScriptAnalyzerSettings.psd1) tracked in git.
• Documentation explains local usage and CI behavior.
• Code Scanning shows uploaded alerts from PSScriptAnalyzer SARIF (for default branch runs).
• Repository has CodeQL enabled for GitHub Actions scanning (language: actions) and produces code scanning alerts when applicable.
• PRs still have a deterministic lint gate (PSScriptAnalyzer) independent of SARIF upload.
• Documentation briefly mentions:
  • “Lint runs in CI”
  • “Code Scanning is available for SARIF + CodeQL (actions)”

Alternatives Considered

• Implement PSScriptAnalyzer call in test-run suite?
• CodeQL does not analyze PowerShell itself, but it does support GitHub Actions YAML scanning.
• SARIF upload integrates third-party/other analyzers into GitHub’s native code scanning UI.

Impact

• Impacts build / CI / release process