Repository navigation
Enforce repository-wide code styling, GPL-3.0 SPDX headers, and PR governance - #23
Merged
Merged
Conversation
…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.
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.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
This pull request establishes a holistic, zero-exemption code-styling,
GPL-3.0-or-laterSPDX licensing, documentation, and pull-request governance baseline across all PowerShell source, build, test, bootstrap, manifest, and documentation files in Icinga for Windows (290files touched) without altering runtime check or daemon behavior.Why & Architectural Rationale
Zero-Exemption Code-Styling & Function-Scope Enforcement (
build/Test-ModuleCodeStyling.ps1)if/elseifconditions, vertical=alignment across assignment/hashtable/enum blocks, and aligned|pipes in.PARAMETERMarkdown tables) were not gated across the full repository, allowing 500+ formatting deviations to accumulate acrosssrc/,build/, andTests/.208files insrc/,7scripts inbuild/,38suites inTests/,IcingaForWindows.psm1,IcingaForWindows.psd1, andPSScriptAnalyzerSettings.psd1) with zero path exemptions, while keeping executable AST token streams insrc/unchanged.src/(outsidesrc/Classes/) must define at most one top-levelfunctionand zero nested functions (src/Classes/definesclassandenumtypes only), whereas internal helper and nested functions remain permitted inbuild/,IcingaForWindows.psm1, andTests/.Mandatory Icinga GmbH
GPL-3.0-or-laterSPDX LicensingLICENSE(GPL-3.0-or-later) and Icinga GmbH SPDX requirements:<# ... #>comment-based help blocks, every.NOTESsection acrosssrc/(Public/,Private/,Classes/),IcingaForWindows.psm1,build/*.ps1, andTests/*.Tests.ps1concludes with:<# ... #>block comments, standalone PowerShell# SPDX-...license comments are emitted at lines 1-2 of compiledlib/IcingaForWindows.Classes.ps1andlib/IcingaForWindows.Kernel.ps1viabuild/Build-ModuleProject.ps1, at the top ofPSScriptAnalyzerSettings.psd1, and beneathPrivateData.SPDXinIcingaForWindows.psd1(updatingCopyrightfromMITtoGPL-3.0-or-laterandLicenseUritoblob/main/LICENSE).build/Build-ModuleDocs.ps1to require.NOTES+ SPDX completeness across all198PublicandPrivatefunctions, strip machine-readableSPDX-...lines from rendered#### NotesMarkdown sections, fix relative../src/source links, and regenerate all20docs/Icinga.*.mdfiles anddocs/index.mdwithout touching hand-writtendocs/subdirectories.Windows PowerShell 5.1 BOM-Less CP1252 Lexer & UNC Share Hardening
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.ps1file (. $KernelPath), it decodes the bytes as Windows-1252 and treats bytes0x91-0x94(such as0x92inside the UTF-8 sequence0xE2 0x86 0x92ofU+2192->, or0x94insideU+1F50D) as closing smart-quote string delimiters ('/"), breaking AST parsing ofIcingaForWindows.Kernel.ps1.> 0x7F) across all258PowerShell 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 compiledlib/artifacts inbuild/Test-ModuleCodeStyling.ps1.build/Build-ModuleProject.ps1with SMB-safe[System.IO.File]::ReadAllText, deterministic alphabetical sorting forClasses,Private, andPublicfiles, and explicit Pester 5.0+New-PesterConfigurationloading so Windows PowerShell 5.1 never falls back to pre-installed Pester 3.4.0.[System.IO.Path]::GetFullPath((Resolve-Path ...).ProviderPath)acrossbuild/andTests/to stripMicrosoft.PowerShell.Core\FileSystem::provider prefixes while collapsing\..\segments on UNC network shares.Changelog, Roadmap & Single-Run CI Governance
docs/General/Changelog.md,docs/General/Roadmap.md, andbuild/Test-ModuleChangelog.ps1, requiring every branch and Pull Request not onmainto add at least one net-new*bullet entry relative to its merge-base.Test-ModuleCodeStyling.ps1andTest-ModuleChangelog.ps1alongsideInvoke-ScriptAnalysis.ps1inside theanalyzejob of.github/workflows/ci.yml(fetch-depth: 0), while keepingTests/CodeStyling.Tests.ps1andTests/Changelog.Tests.ps1strictly to fast$TestDrivefixture unit tests soInvoke-ModuleTests.ps1never scans the repository tree twice in CI.English
README.mdOverhaul & Unified AI Agent RulesetREADME.mdin English with subsystem architecture summaries, Mermaid runtime and CI governance diagrams, verified Quick Start andNew-IcingaPluginSDK examples, and developer validation commands.docs/Agents/guidelines/01-Instruction.mdas the binding single source of truth synchronized withAGENTS.md,CLAUDE.md,GEMINI.md, and.github/copilot-instructions.md, enforcing"Icinga for Windows"in prose and reservingIcingaForWindowsstrictly for technical module, path, file, and$Global:IcingaForWindowsidentifiers.Verification
.\build\Build-ModuleProject.ps1compiles42public functions,156private functions, and10class files into BOM-lesslib/IcingaForWindows.{Classes,Kernel}.ps1with top# SPDX-...headers and imports cleanly on both Windows PowerShell 5.1 (including UNC shares) and PowerShell 7+..\build\Test-ModuleCodeStyling.ps1->0violations across all258PowerShell & manifest files + compiledlib/artifacts..\build\Test-ModuleChangelog.ps1-> Passed (0violations)..\build\Build-ModuleDocs.ps1 -Strict $true->20Markdown files (198functions across19components),0violations,0broken relative links across all47Markdown files..\build\Test-ModuleDaemonMemoryLeak.ps1(0leaks) and.\build\Invoke-ScriptAnalysis.ps1 -FailOn 'Warning'(0build-breaking findings).15 / 15tests inCodeStyling.Tests.ps1,Changelog.Tests.ps1, andClassLiteral.Tests.ps1).