NTFSSecurity/.memory-bank/systemPatterns.md

status	last-verified	owner	source
current	2026-10-04	active-agent	repository evidence

System patterns

Architecture

NTFSSecurity.psd1 ─┬─ ScriptsToProcess: NTFSSecurity.Init.ps1
                   │    Add-Type: Security2.dll, PrivilegeControl.dll,
                   │    ProcessPrivileges.dll, inline NTFS.DriveInfoExt;
                   │    Update-FormatData -PrependPath format.ps1xml
                   ├─ TypesToProcess: NTFSSecurity.types.ps1xml
                   │    (Owner, IsInheritanceBlocked, LengthOnDisk on
                   │    FileInfo/DirectoryInfo; AccountType on ACEs)
                   ├─ RootModule: NTFSSecurity.psm1 (aliases)
                   ├─ NestedModules: NTFSSecurity.dll (36 cmdlets)
                   └─ en-US\NTFSSecurity.dll-Help.xml (Get-Help; generated
                        from Docs/Cmdlets, Decision 8)
NTFSSecurity.dll ── cmdlets ──> Security2.dll (FileSystemAccessRule2,
                                FileSystemAuditRule2, IdentityReference2,
                                FileSystemInheritanceInfo, EffectiveAccess)
                 ── long paths ──> AlphaFS
                 ── privileges ──> PrivilegeControl / ProcessPrivileges

• BaseCmdlet resolves relative paths against $PWD.
• BaseCmdletWithPrivControl (access, audit, inheritance, owner, security descriptor, and privilege cmdlets) enables Backup, Restore, TakeOwnership, and Security in BeginProcessing when PrivateData.EnablePrivileges is $true, and disables the ones it enabled in EndProcessing.
• PrivateData switches: EnablePrivileges (base cmdlet), GetInheritedFrom (Get-NTFSAccess, Get-NTFSAudit), GetFileSystemModeProperty and IdentifyHardLinks (Get-ChildItem2), ShowAccountSid (format file).
• Cmdlets accept either -Path (alias FullName) or -SecurityDescriptor (from Get-NTFSSecurityDescriptor); SD sets change the in-memory object until Set-NTFSSecurityDescriptor writes it back.

Decisions

Each Decision record is a file in decisions/; read only the relevant ones.

#	Decision
1	Use the canonical Memory Bank base
2	Cmdlet reference stays platyPS markdown
3	Document the source at HEAD
4	Online help points to GitHub
5	Document defects, don't fix them in docs work
6	CI checks the docs against a build of the source
7	CHANGELOG lists user-visible changes only
8	Commit the generated help file and check it in CI
9	Keep the documentation on GitHub
10	One version for the manifest, assemblies, and changelog
11	CI and the wiki run on GitHub Actions

Patterns

Verifying documentation

• Run platyPS in Windows PowerShell 5.1 against a module build; a copy of Docs/Cmdlets must round-trip through Update-MarkdownHelp unchanged.
• GitHub renders the docs (Decision 9), and CI publishes them to the wiki (Decision 11). The MarkdownLinkCheck step covers only relative links in Docs and ignores anchors; Tests\Wiki.Tests.ps1 checks every link of the generated wiki, including anchors (GitHub's slug rules: lowercase, punctuation removed, spaces to hyphens). Check the links in README.md and CHANGELOG.md separately.
• The wiki is generated: edit Docs, never the wiki. Export-WikiContent.ps1 names a page after its file (Docs/README.md becomes Home), rewrites links, and builds the sidebar from the cmdlet groups of Docs/README.md; a cmdlet missing there fails Wiki.Tests.ps1.
• platyPS rewrites non-ASCII punctuation such as em dashes; keep cmdlet pages ASCII-only.
• In cmdlet pages, end a sentence with a link: platyPS renders a link as text (url) in the help file and drops the space after it.
• Verify examples in a $env:TEMP sandbox, never on real data; parse every example and check its parameters against Get-Command metadata.

Testing the module

• Pester 5 tests in Tests/*.Tests.ps1 import NTFSSecurity\bin\Release\NTFSSecurity.psd1; CI runs them in Windows PowerShell 5.1 and in PowerShell 7 (Decision 11).
• Get-Help -Online is tested with the internal test hook BypassOnlineHelpRetrieval, which returns the URI instead of opening a browser. In PowerShell 7 the hook also skips the help file, so that test runs only in Windows PowerShell (36 skipped tests in PowerShell 7); PowerShell 7 resolves the same URI.
• .github/scripts/Invoke-Tests.ps1 runs Pester for CI: the counts and the failed tests go to the job summary, the NUnit file to the test-results artifact, and it fails on failed test files too (Result -ne 'Passed').
• Tests\Manifest.Tests.ps1 checks the built manifest: Test-ModuleManifest without errors or warnings, exactly 36 cmdlets, and one version (Decision 10). Add a new cmdlet to CmdletsToExport and to the expected count in the same change.