From dbd8d1696a4fb75ebf160e171042a95929e3268a Mon Sep 17 00:00:00 2001 From: Raimund Andree Date: Fri, 2 Oct 2026 11:57:43 +0200 Subject: [PATCH] ci: build the module and check the docs against the build The documentation check ran Update-MarkdownHelp against the NTFSSecurity release from the PowerShell Gallery (4.2.6), so it failed for every unreleased parameter change. PR #91 failed because 4.2.6 still has Remove-Item2 -PassThur while the source and the docs have -PassThru. - Build NTFSSecurity.csproj in Release on the Visual Studio 2022 image, using the .NET Framework 4.5.2 reference assemblies package instead of an installed targeting pack - Check Docs/Cmdlets against the module built from source - Pin platyPS 0.14.2 and MarkdownLinkCheck 0.2.0, and enable TLS 1.2 so the NuGet provider bootstrap works Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Co-authored-by: AI Assistant --- .memory-bank/activeContext.md | 26 ++++++------- .memory-bank/progress.md | 8 ++-- .memory-bank/systemPatterns.md | 9 +++++ .memory-bank/techContext.md | 29 ++++++++++----- Docs/Contributing/02-Writing.md | 3 +- appveyor.yml | 65 +++++++++++++++++++++------------ 6 files changed, 89 insertions(+), 51 deletions(-) diff --git a/.memory-bank/activeContext.md b/.memory-bank/activeContext.md index 67a592e..0a260ff 100644 --- a/.memory-bank/activeContext.md +++ b/.memory-bank/activeContext.md @@ -9,22 +9,22 @@ source: current task evidence ## Current focus -Documentation aligned with the cmdlets at HEAD (branch `ai/docs-alignment`). -Next candidates: ship generated MAML help, re-point the docs build, and fix -the code defects the documentation work surfaced. +PR #91 (`ai/docs-alignment`): CI fixed by building the module from source +in `appveyor.yml` and checking the docs against that build. ## Evidence -- All 36 cmdlet pages filled from the C# source; 142 examples; no `{{` - placeholders; examples checked against live parameter metadata. -- `Update-MarkdownHelp` against release 4.2.6 leaves 35 of 36 pages - byte-identical; `Remove-Item2` differs only by `-PassThru` (HEAD) versus - `-PassThur` (4.2.6). -- `New-ExternalHelp` builds `NTFSSecurity.dll-Help.xml` (36 commands); - `Get-Help` renders it when placed in `en-US` of a module copy. -- Read the Docs project `ntfssecurity` and the AppVeyor project build the - fork `Sup3rlativ3/NTFSSecurity`; the last RTD build is about 5.75 years old. +- AppVeyor build 54825990 failed in step 01: `Update-MarkdownHelp` against + the Gallery module 4.2.6 rewrote `Remove-Item2 -PassThru` to `-PassThur`. +- Against a Release build of the source, `Update-MarkdownHelp` changes none + of the 36 pages; a simulation of all `appveyor.yml` steps in a fresh clone + passed, and a page with stale syntax made it fail as intended. +- The link check (`Get-MarkdownLink -BrokenOnly`) finds 308 links, none + broken. +- Read the Docs project `ntfssecurity` still builds the fork + `Sup3rlativ3/NTFSSecurity`. ## Next step -Await the next task. Open follow-ups are listed in `progress.md`. +Push `ai/docs-alignment` (only on request) and confirm the AppVeyor build of +PR #91 passes on the Visual Studio 2022 image. diff --git a/.memory-bank/progress.md b/.memory-bank/progress.md index 5bbb0c4..449bbfa 100644 --- a/.memory-bank/progress.md +++ b/.memory-bank/progress.md @@ -21,6 +21,9 @@ since the 4.2.6 release except the `Remove-Item2 -PassThru` rename and home page, contributor guide, README rewritten; `mkdocs.yml` nav, `edit_uri`, and `.readthedocs.yml` (`build.os`) fixed; `CHANGELOG.md` created. +- 2026-10-02: PR #91 build fixed: `appveyor.yml` builds the module from + source and checks the docs against that build instead of the Gallery + release (root cause of the `Remove-Item2 -PassThru` drift failure). ## Stable capabilities @@ -34,9 +37,8 @@ since the 4.2.6 release except the `Remove-Item2 -PassThru` rename and - Ship help: add the generated `en-US\NTFSSecurity.dll-Help.xml` to the build and drop the stale `NTFSSecurity-Help.xml`. -- Publishing: re-point Read the Docs and AppVeyor from the fork - `Sup3rlativ3/NTFSSecurity`; `appveyor.yml` checks docs against the Gallery - module instead of the source. +- Publishing: re-point Read the Docs from the fork `Sup3rlativ3/NTFSSecurity` + to this repository (or create a new Read the Docs project). - Manifest: remove `Show-NTFSSimpleAccess` and duplicates from `CmdletsToExport`; bump `ModuleVersion` (4.2.5 in source, 4.2.6 released). - Code defects found while documenting (each documented on its page): diff --git a/.memory-bank/systemPatterns.md b/.memory-bank/systemPatterns.md index 1fa620b..19319cc 100644 --- a/.memory-bank/systemPatterns.md +++ b/.memory-bank/systemPatterns.md @@ -76,6 +76,15 @@ NTFSSecurity.dll ── cmdlets ──> Security2.dll (FileSystemAccessRule2, - Rationale: No build toolchain was available to verify code changes, and the docs must describe current behavior. +### Decision 6: CI checks the docs against a build of the source + +- Choice: `appveyor.yml` builds `NTFSSecurity.csproj` and runs + `Update-MarkdownHelp` against `NTFSSecurity\bin\Release`, not against the + module from the PowerShell Gallery. +- Rationale: Checking against the last release fails for every unreleased + parameter change (PR #91 failed on `Remove-Item2 -PassThru`) and never + compiled the code. + ### Pattern: verifying documentation - Run platyPS in Windows PowerShell 5.1 against a module build; a copy of diff --git a/.memory-bank/techContext.md b/.memory-bank/techContext.md index 001235d..290a78f 100644 --- a/.memory-bank/techContext.md +++ b/.memory-bank/techContext.md @@ -28,8 +28,12 @@ source: repository evidence - Windows only (NTFS, Win32 security APIs). - The Debug build writes straight into `C:\Program Files\WindowsPowerShell\Modules\NTFSSecurity\`. -- No MSBuild or .NET Framework targeting pack on the 2026-10-02 workstation; - the released module 4.2.6 and platyPS 0.14.2 were installed. +- No Visual Studio MSBuild or .NET Framework targeting pack on the + workstation. A local build works with the .NET Framework MSBuild + (`%WINDIR%\Microsoft.NET\Framework64\v4.0.30319\MSBuild.exe`) plus + `/p:CscToolPath` to the Roslyn `csc.exe` of the `Microsoft.Net.Compilers` + package; the legacy C# 5 compiler fails with CS0136. `dotnet msbuild` + fails on the binary resources in `Resources.resx` (MSB3822, MSB3823). ## Constraints @@ -41,22 +45,27 @@ source: repository evidence (WinForms code removed in `d3063de`), and repeats the inheritance cmdlets. - `NTFSSecurity/NTFSSecurity-Help.xml` is a stale pre-4.x MAML file for old command names; binary-module help must be named `NTFSSecurity.dll-Help.xml`. -- Read the Docs (`ntfssecurity`) and AppVeyor are attached to the fork - `Sup3rlativ3/NTFSSecurity`, not to this repository. +- CI: AppVeyor project `raandree/ntfssecurity` builds branches and pull + requests. Read the Docs (`ntfssecurity`) and a second AppVeyor project are + attached to the fork `Sup3rlativ3/NTFSSecurity`. - `Get-FileHash2` fails in PowerShell 7; all other cmdlets passed a smoke test in PowerShell 7.6. ## Validation -- Docs drift check (mirrors `appveyor.yml`), run in Windows PowerShell 5.1 - to avoid PowerShell 7.4+ `-ProgressAction` noise: copy `Docs/Cmdlets`, run - `Update-MarkdownHelp` on the copy against the module, and diff. +- CI (`appveyor.yml`, image Visual Studio 2022): restore `packages.config` + per project plus `Microsoft.NETFramework.ReferenceAssemblies.net452` + 1.0.3, build `NTFSSecurity.csproj` in Release with + `TargetFrameworkRootPath`/`FrameworkPathOverride`, import + `NTFSSecurity\bin\Release\NTFSSecurity.psd1`, run `Update-MarkdownHelp`, + and fail on `git diff -- Docs/Cmdlets`; then `Get-MarkdownLink -BrokenOnly`. +- Run platyPS in Windows PowerShell 5.1 to avoid PowerShell 7.4+ + `-ProgressAction` noise. - Placeholder check: no `{{` left in `Docs/Cmdlets/*.md`. - Help build check: `New-ExternalHelp -Path ./Docs/Cmdlets` to a temp folder. - Markdown lint: `npx markdownlint-cli2` with `MD013` limited to prose (tables, code, and headings excluded) on the conceptual pages. -- YAML: `ConvertFrom-Yaml` (powershell-yaml) on `mkdocs.yml` and - `.readthedocs.yml`; every `nav` target must exist. -- Link check in CI: `Get-MarkdownLink -Path .\Docs\ -BrokenOnly`. +- YAML: `ConvertFrom-Yaml` (powershell-yaml) on `mkdocs.yml`, + `.readthedocs.yml`, and `appveyor.yml`; every `nav` target must exist. - MkDocs needs Python, which this workstation does not have; `mkdocs build --strict` was not run. diff --git a/Docs/Contributing/02-Writing.md b/Docs/Contributing/02-Writing.md index e58d02e..8c850d0 100644 --- a/Docs/Contributing/02-Writing.md +++ b/Docs/Contributing/02-Writing.md @@ -42,7 +42,8 @@ parameter descriptions, the examples, and the notes. When a cmdlet changes, build the module, import the build output, and update the pages in Windows PowerShell 5.1. A Release build writes the module to -`NTFSSecurity\bin\Release`: +`NTFSSecurity\bin\Release`; the `before_build` and `build_script` steps in +`appveyor.yml` show the commands that the CI build uses: ```powershell Install-Module -Name platyPS -RequiredVersion 0.14.2 diff --git a/appveyor.yml b/appveyor.yml index a0573d6..effe479 100644 --- a/appveyor.yml +++ b/appveyor.yml @@ -1,31 +1,48 @@ -install: - - ps: | - Install-PackageProvider -Name NuGet -MinimumVersion 2.8.5.201 -Force - Install-Module platyPS -Force - Install-Module MarkdownLinkCheck -Force - Install-Module NTFSSecurity -Force - Import-Module platyPS - Import-Module MarkdownLinkCheck +# Builds the NTFSSecurity module from source and checks that the cmdlet +# documentation in Docs/Cmdlets matches the cmdlets of that build. +image: Visual Studio 2022 init: - - ps: git config --global core.autocrlf true + - ps: git config --global core.autocrlf true + +install: + - ps: | + [Net.ServicePointManager]::SecurityProtocol = [Net.ServicePointManager]::SecurityProtocol -bor [Net.SecurityProtocolType]::Tls12 + Install-PackageProvider -Name NuGet -MinimumVersion 2.8.5.201 -Force | Out-Null + Install-Module -Name platyPS -RequiredVersion 0.14.2 -Force + Install-Module -Name MarkdownLinkCheck -RequiredVersion 0.2.0 -Force + +before_build: + - nuget restore NTFSSecurity\packages.config -PackagesDirectory packages -NonInteractive + - nuget restore Security2\packages.config -PackagesDirectory packages -NonInteractive + # Provides the .NET Framework 4.5.2 reference assemblies, so the build does + # not depend on a targeting pack installed on the build image. + - nuget install Microsoft.NETFramework.ReferenceAssemblies.net452 -Version 1.0.3 -OutputDirectory packages -NonInteractive build_script: - - ps: Import-Module -Force NTFSSecurity + - ps: | + $referenceAssemblies = "$env:APPVEYOR_BUILD_FOLDER\packages\Microsoft.NETFramework.ReferenceAssemblies.net452.1.0.3\build" + msbuild NTFSSecurity\NTFSSecurity.csproj /nologo /verbosity:minimal /p:Configuration=Release "/p:TargetFrameworkRootPath=$referenceAssemblies" "/p:FrameworkPathOverride=$referenceAssemblies\.NETFramework\v4.5.2" + if ($LASTEXITCODE -ne 0) { + throw "MSBuild failed with exit code $LASTEXITCODE." + } test_script: - - ps: | - $ErrorActionPreference = 'Stop' - - # 01. Test that documentation is up-to-date - Update-MarkdownHelp -Path ./Docs/Cmdlets - $Diff = git diff - if ($Diff) { - throw "Help is not up-to-date, run Update-MarkdownHelp: $diff" - } + - ps: | + $ErrorActionPreference = 'Stop' + Import-Module -Name platyPS + Import-Module -Name MarkdownLinkCheck + Import-Module -Name .\NTFSSecurity\bin\Release\NTFSSecurity.psd1 -Force + + # 01. Test that the documentation matches the cmdlets built from source + Update-MarkdownHelp -Path ./Docs/Cmdlets | Out-Null + $diff = git diff -- Docs/Cmdlets + if ($diff) { + throw "Help is not up-to-date, run Update-MarkdownHelp: $diff" + } - # 02. Verify hyperlinks - $BrokenLinks = Get-MarkdownLink -Path .\Docs\ -BrokenOnly - if ($brokenLinks) { - throw "Found broken hyperlinks $brokenLinks" - } \ No newline at end of file + # 02. Verify hyperlinks + $brokenLinks = Get-MarkdownLink -Path .\Docs\ -BrokenOnly + if ($brokenLinks) { + throw "Found broken hyperlinks $brokenLinks" + }