Skip to content

Enforce repository-wide code styling, GPL-3.0 SPDX headers, and PR governance - #23

Merged
LordHepipud merged 3 commits into
mainfrom
feature/update-code-styling
Nov 17, 2026
Merged

LordHepipud merged 3 commits into
mainfrom
feature/update-code-styling

Conversation

@LordHepipud

Copy link
Copy Markdown
Collaborator

Summary

This pull request establishes a holistic, zero-exemption code-styling, GPL-3.0-or-later SPDX licensing, documentation, and pull-request governance baseline across all PowerShell source, build, test, bootstrap, manifest, and documentation files in Icinga for Windows (290 files touched) without altering runtime check or daemon behavior.


Why & Architectural Rationale

  1. Zero-Exemption Code-Styling & Function-Scope Enforcement (build/Test-ModuleCodeStyling.ps1)

    • Previously, formatting rules (UTF-8 without BOM, 4-space indentation, Allman braces, single-line if/elseif conditions, vertical = alignment across assignment/hashtable/enum blocks, and aligned | pipes in .PARAMETER Markdown tables) were not gated across the full repository, allowing 500+ formatting deviations to accumulate across src/, build/, and Tests/.
    • Remediates 100% of PowerShell files (208 files in src/, 7 scripts in build/, 38 suites in Tests/, IcingaForWindows.psm1, IcingaForWindows.psd1, and PSScriptAnalyzerSettings.psd1) with zero path exemptions, while keeping executable AST token streams in src/ unchanged.
    • Enforces clear module architecture boundaries via AST inspection: files under src/ (outside src/Classes/) must define at most one top-level function and zero nested functions (src/Classes/ defines class and enum types only), whereas internal helper and nested functions remain permitted in build/, IcingaForWindows.psm1, and Tests/.
  2. Mandatory Icinga GmbH GPL-3.0-or-later SPDX Licensing

    • Aligns every PowerShell file and manifest in the repository with LICENSE (GPL-3.0-or-later) and Icinga GmbH SPDX requirements:
      • Inside <# ... #> comment-based help blocks, every .NOTES section across src/ (Public/, Private/, Classes/), IcingaForWindows.psm1, build/*.ps1, and Tests/*.Tests.ps1 concludes with:
        SPDX-FileCopyrightText: 2026 Icinga GmbH <https://icinga.com>
        SPDX-License-Identifier: GPL-3.0-or-later
        
      • Outside <# ... #> block comments, standalone PowerShell # SPDX-... license comments are emitted at lines 1-2 of compiled lib/IcingaForWindows.Classes.ps1 and lib/IcingaForWindows.Kernel.ps1 via build/Build-ModuleProject.ps1, at the top of PSScriptAnalyzerSettings.psd1, and beneath PrivateData.SPDX in IcingaForWindows.psd1 (updating Copyright from MIT to GPL-3.0-or-later and LicenseUri to blob/main/LICENSE).
    • Updates build/Build-ModuleDocs.ps1 to require .NOTES + SPDX completeness across all 198 Public and Private functions, strip machine-readable SPDX-... lines from rendered #### Notes Markdown sections, fix relative ../src/ source links, and regenerate all 20 docs/Icinga.*.md files and docs/index.md without touching hand-written docs/ subdirectories.
  3. Windows PowerShell 5.1 BOM-Less CP1252 Lexer & UNC Share Hardening

    • Concatenated lib/ modules are written as UTF-8 without BOM (UTF8Encoding($false)) so mid-file BOMs never break compilation. However, when Windows PowerShell 5.1 dot-sources a BOM-less .ps1 file (. $KernelPath), it decodes the bytes as Windows-1252 and treats bytes 0x91-0x94 (such as 0x92 inside the UTF-8 sequence 0xE2 0x86 0x92 of U+2192 ->, or 0x94 inside U+1F50D) as closing smart-quote string delimiters (' / "), breaking AST parsing of IcingaForWindows.Kernel.ps1.
    • Eliminates all literal non-ASCII bytes (> 0x7F) across all 258 PowerShell files, constructs intentional runtime console tree glyphs via [char]0x2514 / [char]0x2500 (rendering clean box-drawing characters without Mojibake on both PS 5.1 and PS 7+), and enforces strict 7-bit ASCII across source and compiled lib/ artifacts in build/Test-ModuleCodeStyling.ps1.
    • Hardens build/Build-ModuleProject.ps1 with SMB-safe [System.IO.File]::ReadAllText, deterministic alphabetical sorting for Classes, Private, and Public files, and explicit Pester 5.0+ New-PesterConfiguration loading so Windows PowerShell 5.1 never falls back to pre-installed Pester 3.4.0.
    • Combines [System.IO.Path]::GetFullPath((Resolve-Path ...).ProviderPath) across build/ and Tests/ to strip Microsoft.PowerShell.Core\FileSystem:: provider prefixes while collapsing \..\ segments on UNC network shares.
  4. Changelog, Roadmap & Single-Run CI Governance

    • Adds docs/General/Changelog.md, docs/General/Roadmap.md, and build/Test-ModuleChangelog.ps1, requiring every branch and Pull Request not on main to add at least one net-new * bullet entry relative to its merge-base.
    • Integrates Test-ModuleCodeStyling.ps1 and Test-ModuleChangelog.ps1 alongside Invoke-ScriptAnalysis.ps1 inside the analyze job of .github/workflows/ci.yml (fetch-depth: 0), while keeping Tests/CodeStyling.Tests.ps1 and Tests/Changelog.Tests.ps1 strictly to fast $TestDrive fixture unit tests so Invoke-ModuleTests.ps1 never scans the repository tree twice in CI.
  5. English README.md Overhaul & Unified AI Agent Ruleset

    • Rewrites README.md in English with subsystem architecture summaries, Mermaid runtime and CI governance diagrams, verified Quick Start and New-IcingaPlugin SDK examples, and developer validation commands.
    • Establishes docs/Agents/guidelines/01-Instruction.md as the binding single source of truth synchronized with AGENTS.md, CLAUDE.md, GEMINI.md, and .github/copilot-instructions.md, enforcing "Icinga for Windows" in prose and reserving IcingaForWindows strictly for technical module, path, file, and $Global:IcingaForWindows identifiers.

Verification

  • Windows PowerShell 5.1 & PowerShell 7+ Compilation & Import: .\build\Build-ModuleProject.ps1 compiles 42 public functions, 156 private functions, and 10 class files into BOM-less lib/IcingaForWindows.{Classes,Kernel}.ps1 with top # SPDX-... headers and imports cleanly on both Windows PowerShell 5.1 (including UNC shares) and PowerShell 7+.
  • Code-Styling & SPDX Validator: .\build\Test-ModuleCodeStyling.ps1 -> 0 violations across all 258 PowerShell & manifest files + compiled lib/ artifacts.
  • Changelog & Roadmap Gate: .\build\Test-ModuleChangelog.ps1 -> Passed (0 violations).
  • Strict API Documentation Generator: .\build\Build-ModuleDocs.ps1 -Strict $true -> 20 Markdown files (198 functions across 19 components), 0 violations, 0 broken relative links across all 47 Markdown files.
  • Daemon Memory-Leak & Static Analysis: .\build\Test-ModuleDaemonMemoryLeak.ps1 (0 leaks) and .\build\Invoke-ScriptAnalysis.ps1 -FailOn 'Warning' (0 build-breaking findings).
  • Pester Unit Test Suite: Full suite green across Windows PowerShell 5.1 and PowerShell 7+ (including 15 / 15 tests in CodeStyling.Tests.ps1, Changelog.Tests.ps1, and ClassLiteral.Tests.ps1).

…vernance

Establish a single, zero-exemption code-styling, SPDX licensing, documentation,
and pull-request governance baseline across all PowerShell source, build, test,
bootstrap, manifest, and documentation files in Icinga for Windows without
altering runtime check or daemon behavior.

Why & Architectural Rationale:
1. Unified Code-Styling & Function-Scope Enforcement (`Test-ModuleCodeStyling.ps1`):
   - Previously, formatting rules (4-space indentation, Allman braces, single-line
     `if`/`elseif` conditions, vertical `=` alignment across assignment/hashtable/enum
     blocks, and aligned `|` pipes in `.PARAMETER` Markdown tables) were not validated
     by an automated repository gate, allowing over 500 formatting deviations to
     accumulate across `src/`, `build/`, and `Tests/`.
   - Remediates 100% of PowerShell files (`208` files in `src/`, `7` scripts in
     `build/`, `38` suites in `Tests/`, `IcingaForWindows.psm1`, `IcingaForWindows.psd1`,
     and `PSScriptAnalyzerSettings.psd1`) with zero path exemptions while keeping
     executable AST token streams in `src/` unchanged.
   - Enforces strict module boundaries via AST inspection: files under `src/`
     (outside `src/Classes/`) must define exactly one top-level function and zero
     nested functions (`src/Classes/` defines classes and enums only), whereas
     internal helper and nested functions remain permitted in `build/`,
     `IcingaForWindows.psm1`, and `Tests/`.

2. Mandatory Icinga GmbH `GPL-3.0-or-later` SPDX Licensing:
   - Aligns every PowerShell artifact in the repository with the `LICENSE` file
     (`GPL-3.0-or-later`) and Icinga GmbH REUSE/SPDX requirements.
   - Requires every comment-based help block across `src/`, `build/`, `Tests/`, and
     `IcingaForWindows.psm1` to carry a `.NOTES` section concluding with:
       SPDX-FileCopyrightText: 2026 Icinga GmbH <https://icinga.com>
       SPDX-License-Identifier: GPL-3.0-or-later
   - Emits `# SPDX-FileCopyrightText` and `# SPDX-License-Identifier` PowerShell
     comments at the top of compiled `lib/IcingaForWindows.{Classes,Kernel}.ps1`
     artifacts, at the top of `PSScriptAnalyzerSettings.psd1`, and beneath
     `PrivateData.SPDX` in `IcingaForWindows.psd1` (updating `Copyright` from `MIT`
     to `GPL-3.0-or-later` and `LicenseUri` to `blob/main/LICENSE`).
   - Updates `build/Build-ModuleDocs.ps1` to validate `.NOTES` + SPDX completeness
     across all `198` `Public` and `Private` functions, strip machine-readable
     `SPDX-...` lines from rendered `#### Notes` Markdown sections, fix relative
     `../src/` source links, and regenerate all `20` `docs/Icinga.*.md` files and
     `docs/index.md` without touching hand-written `docs/` subdirectories.

3. Windows PowerShell 5.1 BOM-Less CP1252 Lexer & UNC Share Hardening:
   - Concatenated `lib/` modules must be written as UTF-8 without BOM (`UTF8Encoding($false)`)
     so embedded mid-file BOMs never corrupt compilation. However, when Windows
     PowerShell 5.1 dot-sources BOM-less `.ps1` files (`. $KernelPath`), it decodes
     them as Windows-1252 and treats bytes `0x91`-`0x94` (such as `0x92` inside the
     UTF-8 sequence `0xE2 0x86 0x92` of `U+2192` `->`, or `0x94` in `U+1F50D`) as
     closing smart-quote string delimiters, corrupting the AST of the compiled kernel.
   - Eliminates all literal non-ASCII bytes (`> 0x7F`) across all PowerShell files,
     constructs intentional runtime console tree glyphs via `[char]0x2514` /
     `[char]0x2500` so both PS 5.1 and PS 7 render clean box-drawing characters
     without Mojibake, and enforces strict 7-bit ASCII across source and compiled
     `lib/` files in `Test-ModuleCodeStyling.ps1`.
   - Hardens `build/Build-ModuleProject.ps1` with SMB-safe `[System.IO.File]::ReadAllText`,
     deterministic alphabetical sorting for `Classes`, `Private`, and `Public` files,
     and explicit Pester 5.0+ `New-PesterConfiguration` loading so Windows PowerShell
     5.1 never falls back to built-in Pester 3.4.0.
   - Combines `[System.IO.Path]::GetFullPath((Resolve-Path ...).ProviderPath)` across
     `build/` and `Tests/` to strip `Microsoft.PowerShell.Core\FileSystem::` provider
     prefixes while collapsing `\..\` segments on UNC network shares (`\\Mac\Home\...`).

4. Changelog, Roadmap & Single-Run CI Governance:
   - Introduces `docs/General/Changelog.md`, `docs/General/Roadmap.md`, and
     `build/Test-ModuleChangelog.ps1`, requiring every branch and GitHub Pull Request
     not on `main` to add at least one net-new `* ` bullet entry relative to its
     merge-base.
   - Integrates `Test-ModuleCodeStyling.ps1` and `Test-ModuleChangelog.ps1` alongside
     `Invoke-ScriptAnalysis.ps1` inside the `analyze` job of `.github/workflows/ci.yml`
     (`fetch-depth: 0`), while keeping `Tests/CodeStyling.Tests.ps1` and
     `Tests/Changelog.Tests.ps1` strictly to fast `$TestDrive` fixture unit tests so
     `Invoke-ModuleTests.ps1` never scans the repository tree twice in CI.

5. Documentation, Prose Naming & AI Agent Entrypoints:
   - Rewrites `README.md` in English with subsystem architecture overviews, Mermaid
     runtime and CI governance flowcharts, verified Quick Start and `New-IcingaPlugin`
     SDK examples, and build/test commands.
   - Establishes `docs/Agents/guidelines/01-Instruction.md` as the single source of
     truth synchronized with `AGENTS.md`, `CLAUDE.md`, `GEMINI.md`, and
     `.github/copilot-instructions.md`, enforcing `"Icinga for Windows"` in prose and
     reserving `IcingaForWindows` strictly for technical module, path, file, and
     `$Global:IcingaForWindows` identifiers.
@LordHepipud LordHepipud self-assigned this Nov 17, 2026
@cla-bot cla-bot Bot added the cla/signed CLA is signed by all contributors of a PR label Nov 17, 2026
In .NET multiline regular expressions (`(?m)`), `$` matches before `\n` (`0x0A`)
rather than `\r\n` (`0x0D 0x0A`). When `actions/checkout@v4` checks out files
with CRLF line endings on `windows-latest`, `[ \t]*$` fails to match the
trailing `\r` on `SPDX-FileCopyrightText` inside `.NOTES`.

Add `\r?$` to both SPDX validation patterns and tighten `CleanNotes` stripping
in `build/Build-ModuleDocs.ps1` so strict documentation builds succeed on both
LF and CRLF checkouts.
Place `SPDX-FileCopyrightText` and `SPDX-License-Identifier` inside the `.NOTES`
section of the top `<# ... #>` header block in compiled
`lib/IcingaForWindows.Classes.ps1` and `lib/IcingaForWindows.Kernel.ps1`
artifacts so compiled outputs share the exact same `.NOTES` SPDX layout and
validation logic as source, build, bootstrap, and test PowerShell files.
@LordHepipud
LordHepipud merged commit e6ffb1b into main Nov 17, 2026
6 checks passed
@LordHepipud
LordHepipud deleted the feature/update-code-styling branch November 17, 2026 20:07
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

cla/signed CLA is signed by all contributors of a PR

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant