STYLE_GUIDE_FULL.md

<!-- markdownlint-disable MD013 -->

# PowerShell Writing Style

**Version:** 2.21.20260623.0

## Metadata

- **Status:** Active
- **Owner:** Repository Maintainers
- **Last Updated:** 2026-06-23
- **Scope:** PowerShell coding standards for all `.ps1` files in this repository — style, formatting, naming, error handling, documentation, and compatibility patterns for both legacy (v1.0) and modern (v2.0+) codebases.

## Keywords

Per [RFC 2119](https://www.rfc-editor.org/rfc/rfc2119): **MUST** / **SHALL** / **REQUIRED** = absolute requirement; **MUST NOT** / **SHALL NOT** = absolute prohibition; **SHOULD** / **RECOMMENDED** = strong recommendation (deviations require justification); **SHOULD NOT** / **NOT RECOMMENDED** = strong discouragement; **MAY** / **OPTIONAL** = truly optional.

### Keywords — Extended Explanation

The main guide previously included the full RFC 2119 keyword definitions with all synonyms:

- **MUST** / **REQUIRED** / **SHALL** — Absolute requirement. Non-negotiable.
- **MUST NOT** / **SHALL NOT** — Absolute prohibition.
- **SHOULD** / **RECOMMENDED** — Strong recommendation. Valid reasons may exist to deviate, but implications must be understood.
- **SHOULD NOT** / **NOT RECOMMENDED** — Strong discouragement. Valid reasons may exist to do otherwise, but implications must be understood.
- **MAY** / **OPTIONAL** — Truly optional. Implementations can choose to include or omit.

## Quick Reference Checklist

Scope tags: **[All]** = all PowerShell versions, **[Modern]** = PowerShell v2.0+ (requires features not available in v1.0), **[v1.0]** = backward compatible with Windows PowerShell v1.0. Each item links to its detailed section.

### Code Layout and Formatting (Quick Reference)

- **[All]** Code **MUST** use 4 spaces for indentation, never tabs → [Indentation Rules](#indentation-rules)
- **[All]** Opening braces **MUST** be placed on same line (OTBS) → [Brace Placement (OTBS)](#brace-placement-otbs)
- **[All]** `catch`, `finally`, `else` **MUST** be on same line as closing brace → [Exception: catch, finally, and else Keywords](#exception-catch-finally-and-else-keywords)
- **[All]** Code **MUST** use single space around operators, no extra alignment → [Operator Spacing and Alignment](#operator-spacing-and-alignment)
- **[All]** Operators **MUST NOT** be vertically aligned across multiple lines → [Operator Spacing and Alignment](#operator-spacing-and-alignment)
- **[All]** Multi-line method parameters **MUST** have extra indentation → [Multi-line Method Indentation](#multi-line-method-indentation)
- **[All]** Blank lines **SHOULD** be used sparingly: two around functions, one within → [Blank Line Usage](#blank-line-usage)
- **[All]** Blank lines **MUST NOT** contain any whitespace (spaces or tabs) → [Blank Line Usage](#blank-line-usage)
- **[All]** Lines **MUST NOT** end with trailing whitespace → [Trailing Whitespace](#trailing-whitespace)
- **[All]** Variables in strings **SHOULD** be delimited with `${}` or `-f` operator → [Variable Delimiting in Strings](#variable-delimiting-in-strings)
- **[All]** Source `.ps1` files **MUST** be UTF-8 without BOM by default; see [File Encoding](#file-encoding) for the Windows PowerShell/non-ASCII exception
- **[All]** When writing text files programmatically, encoding **MUST** be specified explicitly; prefer `.NET` for cross-version UTF-8 without BOM → [Programmatic File Writing Encoding](#programmatic-file-writing-encoding)
- **[All]** When producing byte-exact text artifacts, serializer output **MUST** be normalized to LF in memory before writing or comparing → [Line Endings for Byte-Exact Text Artifacts](#line-endings-for-byte-exact-text-artifacts)
- **[All]** Text-level file comparison **MUST** read files with `Get-Content -Raw` or `[System.IO.File]::ReadAllText()` under a fixed encoding/BOM convention; `Get-Content` without `-Raw` **MUST NOT** be used → [Line Endings for Byte-Exact Text Artifacts](#line-endings-for-byte-exact-text-artifacts)
- **[All]** True byte-for-byte comparison **MUST** read files with `[System.IO.File]::ReadAllBytes()`; this is required for hash/signature inputs and any other byte-exact identity check → [Line Endings for Byte-Exact Text Artifacts](#line-endings-for-byte-exact-text-artifacts)

### Capitalization and Naming Conventions (Quick Reference)

- **[All]** Public identifiers (functions, parameters, properties) **MUST** use PascalCase → [Capitalization and Naming Conventions](#capitalization-and-naming-conventions)
- **[All]** PowerShell keywords (function, param, if, else, return, trap) **MUST** be lowercase → [Capitalization and Naming Conventions](#capitalization-and-naming-conventions)
- **[All]** Local variables **MUST** use camelCase with type-hinting prefixes, fully descriptive (e.g., $strMessage, $intCount, no abbreviations) → [Local Variable Naming: Type-Prefixed camelCase](#local-variable-naming-type-prefixed-camelcase)
- **[All]** Functions **MUST** follow Verb-Noun pattern with approved verbs → [Script and Function Naming: Full Explicit Form](#script-and-function-naming-full-explicit-form)
- **[All]** Functions **MUST** use singular nouns in function names → [Script and Function Naming: Nouns](#script-and-function-naming-nouns)
- **[All]** Modules **MUST** use PascalCase nouns (containers, not actions) → [Module Naming: Noun-Based Containers](#module-naming-noun-based-containers)
- **[Modern]** Module manifest `Tags` key **MUST** be populated aggressively with relevant keywords for discoverability → [Module Naming: Noun-Based Containers](#module-naming-noun-based-containers)
- **[All]** Aliases **MUST NOT** be used in code → [Do Not Use Aliases](#do-not-use-aliases)
- **[Modern]** Modules **MUST NOT** export compatibility aliases (exception: genuine interactive shortcuts) → [Do Not Use Aliases](#do-not-use-aliases)
- **[All]** Parameters **MUST** use PascalCase, fully descriptive names → [Parameter Naming](#parameter-naming)
- **[v1.0]** Reference parameters **MUST** use "ReferenceTo" prefix → [Parameter Naming](#parameter-naming)
- **[All]** Code **SHOULD** avoid relative paths and tilde (~) shortcut → [Path and Scope Handling](#path-and-scope-handling)
- **[All]** Code **SHOULD** use explicit scoping ($global:, $script:) → [Path and Scope Handling](#path-and-scope-handling)
- **[All]** `-LiteralPath` **SHOULD** be used instead of `-Path` when operating on concrete (non-wildcard) paths derived from variables or `Join-Path` → [Prefer `-LiteralPath` Over `-Path` for Concrete Paths](#prefer--literalpath-over--path-for-concrete-paths)
- **[All]** For destructive cmdlets (`Remove-Item`, `Move-Item`), `-LiteralPath` **MUST** be used for variable-derived paths → [Prefer `-LiteralPath` Over `-Path` for Concrete Paths](#prefer--literalpath-over--path-for-concrete-paths)
- **[All]** `New-Item` does **not** support `-LiteralPath`; use `-Path` with `New-Item` → [Prefer `-LiteralPath` Over `-Path` for Concrete Paths](#prefer--literalpath-over--path-for-concrete-paths)
- **[All]** For directory creation from variable-derived paths that may contain wildcard characters, prefer `[System.IO.Directory]::CreateDirectory()` → [Prefer `-LiteralPath` Over `-Path` for Concrete Paths](#prefer--literalpath-over--path-for-concrete-paths)
- **[All]** Paths passed to .NET file APIs (`System.IO.*`) **MUST** be resolved to absolute via `GetUnresolvedProviderPathFromPSPath()` first; non-FileSystem provider paths **MUST NOT** be used → [Resolving Paths for .NET Static Methods](#resolving-paths-for-net-static-methods)

### Documentation and Comments (Quick Reference)

- **[All]** All functions **MUST** have full comment-based help → [Comment-Based Help: Structure and Format](#comment-based-help-structure-and-format)
- **[All]** Comment-based help **MUST** be placed inside function body, above param block → [Comment-Based Help: Structure and Format](#comment-based-help-structure-and-format)
- **[All]** Comment-based help **MUST** use single-line comments (#) with dotted keywords (.SYNOPSIS, .DESCRIPTION, etc.) → [Comment-Based Help: Structure and Format](#comment-based-help-structure-and-format)
- **[v1.0]** Block comments (`<# ... #>`) **MUST NOT** be used — they cause parser errors in PowerShell v1.0; use single-line comments (`#`) instead → [Help Format Options: Comparison](#help-format-options-comparison)
- **[All]** Comment-based help **MUST** include sections: .SYNOPSIS, .DESCRIPTION, .PARAMETER (one per parameter, if any), .EXAMPLE, .INPUTS, .OUTPUTS, .NOTES → [Comment-Based Help: Structure and Format](#comment-based-help-structure-and-format)
- **[All]** Comment-based help **MUST** use exactly one comment blank line between top-level help sections → [Comment-Based Help Spacing](#comment-based-help-spacing)
- **[All]** Explanatory or output-description lines within `.EXAMPLE` blocks **MUST** use double `#` (`# # <text>`) so that `Get-Help` renders them as valid PowerShell comments (`# <text>`) → [Inline Comments Within `.EXAMPLE` Blocks](#inline-comments-within-example-blocks)
- **[All]** Functions **SHOULD** provide multiple examples with input, output, and explanation → [Help Content Quality: High Standards](#help-content-quality-high-standards)
- **[All]** Every possible output/return value **MUST** be documented in .OUTPUTS with exact type and meaning; integer status codes **MUST** include full code-to-meaning mapping; output examples **MUST** be placed in .EXAMPLE blocks → [Help Content Quality: High Standards](#help-content-quality-high-standards)
- **[All]** Positional parameter support **MUST** be documented in .NOTES → [Help Content Quality: High Standards](#help-content-quality-high-standards)
- **[All]** Private/internal helper functions' `.NOTES` **MUST** begin with a private-helper banner → [Private/Internal Helper Function Documentation](#privateinternal-helper-function-documentation)
- **[Modern]** Functions omitted from module manifest `FunctionsToExport` are treated as private/internal helpers → [Private/Internal Helper Function Documentation](#privateinternal-helper-function-documentation)
- **[All]** Positional parameter documentation for private/internal helpers **SHOULD** state it is an internal-caller contract only → [Positional Parameter Support](#positional-parameter-support)
- **[All]** Version number **MUST** be included in .NOTES (format: Major.Minor.YYYYMMDD.Revision) → [Function and Script Versioning](#function-and-script-versioning)
- **[All]** Version build component **MUST** be current date in YYYYMMDD format → [Function and Script Versioning](#function-and-script-versioning)
- **[All]** `.NOTES` `Revision` **MUST** reset to `0` when `Major`, `Minor`, or `Build` changes; otherwise increment (`N + 1`) for same-day updates → [Function and Script Versioning](#function-and-script-versioning)
- **[All]** Inline comments **SHOULD** focus on "why" not "what" → [Inline Comments: Purpose and Placement](#inline-comments-purpose-and-placement)
- **[All]** Code **SHOULD** use #region / #endregion for logical code folding → [Structural Documentation: Regions and Licensing](#structural-documentation-regions-and-licensing)
- **[All]** The param() block **MUST** be placed before license region (if applicable) → [Structural Documentation: Regions and Licensing](#structural-documentation-regions-and-licensing)
- **[All]** Distributable helpers **SHOULD** use per-function licensing (#region License after param block) → [Structural Documentation: Regions and Licensing](#structural-documentation-regions-and-licensing)
- **[All]** Parameter documentation **SHOULD** be centralized in help block, not above individual parameters → [Parameter Documentation Placement: Strategic Choice](#parameter-documentation-placement-strategic-choice)

### Functions and Parameter Blocks (Quick Reference)

- **[v1.0]** v1.0-targeted functions **MUST NOT** use [CmdletBinding()] attribute → [Function Declaration and Structure](#function-declaration-and-structure)
- **[v1.0]** v1.0-targeted functions **MUST NOT** use [OutputType()] attribute → [Function Declaration and Structure](#function-declaration-and-structure)
- **[v1.0]** v1.0-targeted functions **MUST NOT** use begin/process/end blocks → [Function Declaration and Structure](#function-declaration-and-structure)
- **[v1.0]** v1.0-targeted functions **MUST NOT** support pipeline input → [Pipeline Behavior: Deliberately Disabled](#pipeline-behavior-deliberately-disabled)
- **[v1.0]** v1.0-targeted functions **MUST** use simple function keyword with param() block → [Function Declaration and Structure](#function-declaration-and-structure)
- **[v1.0]** Parameters **MUST** use strong typing → [Parameter Block Design: Detailed Analysis](#parameter-block-design-detailed-analysis)
- **[v1.0]** v1.0-targeted functions **MUST** use explicit return statements → [Return Semantics: Explicit Status Codes](#return-semantics-explicit-status-codes)
- **[v1.0]** Reference parameters ([ref]) **MUST** be used for outputs requiring caller modification → [Input/Output Contract: Reference Parameters](#inputoutput-contract-reference-parameters)
- **[v1.0]** Functions **MUST** return single integer status code (0=success, 1-5=partial, -1=failure) → [Return Semantics: Explicit Status Codes](#return-semantics-explicit-status-codes)
- **[v1.0]** Exception: Test-* functions **MAY** return Boolean when no practical error handling needed → [Return Semantics: Explicit Status Codes](#return-semantics-explicit-status-codes)
- **[v1.0]** Positional parameters **SHOULD** be supported for v1.0 usability → [Positional Parameter Support](#positional-parameter-support)
- **[v1.0]** v1.0-targeted functions **MUST** use trap-based error handling (not try/catch) → [Core Error Suppression Mechanism](#core-error-suppression-mechanism)
- **[Modern]** Modern functions and scripts **MUST** use [CmdletBinding()] attribute → [Rule: "Modern Advanced" Function/Script Requirements (v2.0+)](#rule-modern-advanced-functionscript-requirements-v20)
- **[Modern]** Modern functions and scripts **MUST** use [OutputType()] declaring singular primary type → [Rule: "Modern Advanced" Function/Script Requirements (v2.0+)](#rule-modern-advanced-functionscript-requirements-v20)
- **[Modern]** Modern functions and scripts **MUST** use streaming output (write objects directly to pipeline in loop) → [Rule: "Modern Advanced" Function/Script Requirements (v2.0+)](#rule-modern-advanced-functionscript-requirements-v20)
- **[Modern]** Modern functions and scripts **MUST** use try/catch for error handling → [Rule: "Modern Advanced" Function/Script Requirements (v2.0+)](#rule-modern-advanced-functionscript-requirements-v20)
- **[Modern]** Modern functions and scripts **MUST** use Write-Verbose and Write-Debug (not manual preference toggling) → [Rule: "Modern Advanced" Function/Script Requirements (v2.0+)](#rule-modern-advanced-functionscript-requirements-v20)
- **[Modern]** Exception: Modern functions and scripts **MAY** temporarily suppress $VerbosePreference for noisy nested commands using try/finally → ["Modern Advanced" Functions/Scripts: Exception for Suppressing Nested Verbose Streams](#modern-advanced-functionsscripts-exception-for-suppressing-nested-verbose-streams)
- **[Modern]** [Parameter(Mandatory=$true)] **SHOULD** be used only when function cannot work without value → ["Modern Advanced" Functions/Scripts: Parameter Validation and Attributes (`[Parameter()]`)](#modern-advanced-functionsscripts-parameter-validation-and-attributes-parameter)
- **[Modern]** [ValidateNotNullOrEmpty()] **SHOULD** be used for optional-but-not-empty parameters and for mandatory [string] parameters whose logic depends on a non-empty value → ["Modern Advanced" Functions/Scripts: Parameter Validation and Attributes (`[Parameter()]`)](#modern-advanced-functionsscripts-parameter-validation-and-attributes-parameter)
- **[Modern]** [ValidateRange(min, max)] **SHOULD** be used on numeric parameters with a constrained valid domain (counts, delays/timeouts, thresholds, percentages) so invalid input fails at parameter binding rather than producing a confusing downstream error → ["Modern Advanced" Functions/Scripts: Parameter Validation and Attributes (`[Parameter()]`)](#modern-advanced-functionsscripts-parameter-validation-and-attributes-parameter)
- **[Modern]** Multiple [OutputType()] **SHOULD** only be used for intentionally polymorphic returns → ["Modern Advanced" Functions/Scripts: Handling Multiple or Dynamic Output Types](#modern-advanced-functionsscripts-handling-multiple-or-dynamic-output-types)
- **[Modern]** Subset-only positional contracts **MUST** use `PositionalBinding = $false` with explicit `[Parameter(Position = N)]` → [Positional Parameter Support](#positional-parameter-support)
- **[All]** Functions **MUST** be atomic, reusable tools with single purpose → [Function Declaration and Structure](#function-declaration-and-structure)
- **[All]** Polymorphic parameters (multiple incompatible types) **SHOULD** be left un-typed or [object] → [Parameter Block Design: Detailed Analysis](#parameter-block-design-detailed-analysis)
- **[All]** [ref] **MUST** be used exclusively for output requiring write-back to caller scope → [Input/Output Contract: Reference Parameters](#inputoutput-contract-reference-parameters)
- **[All]** [ref] **MUST NOT** be used for complex objects that don't need modification → [Input/Output Contract: Reference Parameters](#inputoutput-contract-reference-parameters)

### Error Handling (Quick Reference)

- **[v1.0]** v1.0-targeted functions **MUST** use trap {} for error suppression → [Core Error Suppression Mechanism](#core-error-suppression-mechanism)
- **[Modern]** catch blocks **MUST NOT** be empty; default pattern is `Write-Debug` + `throw` → [Modern catch Block Requirements](#modern-catch-block-requirements)
- **[Modern]** Non-throwing catch (no `throw`) **MUST** have a documented non-throwing contract → [Modern catch Block Requirements](#modern-catch-block-requirements)
- **[Modern]** `throw "message"` and `throw ("fmt" -f $args)` **MUST NOT** be used in catch blocks intended to rethrow → [Rethrow Anti-Pattern](#rethrow-anti-pattern)
- **[Modern]** Exception wrapping **SHOULD** use `$PSCmdlet.ThrowTerminatingError()` with the original as `InnerException` → [Wrapping Exceptions with `$PSCmdlet.ThrowTerminatingError()`](#wrapping-exceptions-with-pscmdletthrowterminatingerror)
- **[Modern]** Variables referenced in `finally` that are assigned in `try` **MUST** be initialized before the `try` block → [Set-StrictMode Considerations for finally Blocks](#set-strictmode-considerations-for-finally-blocks)
- **[Modern]** In files bundled into a module or other aggregate script artifact, `Set-StrictMode -Version Latest` **MUST** be placed at script scope as the first executable statement in the file, after any `#requires` comments, `using` statements, and any script-level `[CmdletBinding()]`/`param` block → [Set-StrictMode Placement for Dot-Sourced Files](#set-strictmode-placement-for-dot-sourced-files)
- **[Modern]** In files intended to be dot-sourced directly into the caller's scope (test fixtures, ad-hoc scripts, build tooling), `Set-StrictMode -Version Latest` **MUST NOT** be placed at script scope; it **MUST** be placed inside the function body (as the first statement in `begin {}` when using a `begin/process/end` layout, or otherwise as the first statement in the function body) → [Set-StrictMode Placement for Dot-Sourced Files](#set-strictmode-placement-for-dot-sourced-files)

### File Writeability Testing (Quick Reference)

- **[All]** Scripts **MUST** verify file writeability before significant processing when writing output to files → [File Writeability Testing](#file-writeability-testing)
- **[v1.0]** v1.0-targeted scripts **MUST** use `.NET` approach (`Test-FileWriteability` function) → [Approaches](#approaches)
- **[Modern]** Scripts **MAY** use `.NET` or `try/catch` approach based on requirements → [Approaches](#approaches)

### Operating System Compatibility Checks (Quick Reference)

- **[All]** Scripts/functions supporting only specific operating systems **MUST** include OS compatibility checks → [Operating System Compatibility Checks](#operating-system-compatibility-checks)
- **[Modern]** PowerShell Core 6.0+ only scripts **SHOULD** use built-in `$IsWindows`, `$IsMacOS`, `$IsLinux` variables → [PowerShell Core 6.0+ OS Detection](#powershell-core-60-os-detection)
- **[v1.0]** Scripts supporting older versions **MUST** use `Test-Windows`, `Test-macOS`, `Test-Linux` functions from PowerShell_Resources → [Cross-Version OS Detection](#cross-version-os-detection)
- **[All]** Wrong OS errors **MUST** be reported consistently with existing error handling patterns → [Error Handling for Wrong OS](#error-handling-for-wrong-os)

### Output Formatting and Streams (Quick Reference)

- **[Modern]** Modern functions **MUST NOT** collect results in `List<T>` and return; **MUST** stream objects to pipeline → [Processing Collections in Modern Functions (Streaming Output)](#processing-collections-in-modern-functions-streaming-output)
- **[Modern]** Streaming function calls **SHOULD** be wrapped in @(...) to handle 0-1-Many problem → [Consuming Streaming Functions (The `0-1-Many` Problem)](#consuming-streaming-functions-the-0-1-many-problem)
- **[All]** Code **MUST** use Write-Warning for user-facing anomalies; Write-Debug for internal details → [Choosing Between Warning and Debug Streams](#choosing-between-warning-and-debug-streams)
- **[All]** .NET method output **MUST** be suppressed with [void](...), not | Out-Null → [Suppression of Method Output](#suppression-of-method-output)
- **[All]** `Write-Verbose` / `Write-Debug` **MUST NOT** emit raw PII, credentials, tokens, or other sensitive identifiers → [Sensitive Data in Verbose and Debug Streams](#sensitive-data-in-verbose-and-debug-streams)
- **[Modern]** Hot-path `Write-Verbose` / `Write-Debug` with string formatting **SHOULD** be guarded behind a preference check → [Performance-Sensitive `Write-Verbose` / `Write-Debug` in Hot Paths](#performance-sensitive-write-verbose--write-debug-in-hot-paths)
- **[All]** `-f` format operator **MUST** be applied inside the argument-expression parentheses of cmdlet calls → [String Formatting in Cmdlet Arguments (`-f` Scoping)](#string-formatting-in-cmdlet-arguments--f-scoping)

### Language Interop and .NET (Quick Reference)

- **[All]** `System.Collections.ArrayList` is deprecated and **MUST NOT** be used in new code; use `System.Collections.Generic.List[T]` instead → [.NET Interop Patterns: Safe and Documented](#net-interop-patterns-safe-and-documented)
- **[All]** Generic collections **MUST** provide specific type T (List[PSCustomObject], not List[object]) → [.NET Interop Patterns: Safe and Documented](#net-interop-patterns-safe-and-documented)
- **[All]** Code **MUST NOT** grow PowerShell arrays with `+=` inside accumulation loops; use `System.Collections.Generic.List[T]` when an in-memory collection is required → [.NET Interop Patterns: Safe and Documented](#net-interop-patterns-safe-and-documented)

### Testing (Quick Reference)

- **[All]** New functions **SHOULD** have corresponding Pester tests when testability is a project requirement → [Testing with Pester](#testing-with-pester)
- **[All]** Test files **MUST** use `*.Tests.ps1` naming convention → [Test File Naming and Location](#test-file-naming-and-location)
- **[All]** Tests **MUST** use Pester 5.x syntax (BeforeAll, Describe, Context, It) → [Pester 5.x Syntax Requirements](#pester-5x-syntax-requirements)
- **[All]** Tests **SHOULD** use Arrange-Act-Assert pattern in test cases → [Test Structure: Arrange-Act-Assert](#test-structure-arrange-act-assert)
- **[All]** Tests **MUST** verify all documented return codes for functions → [Testing Return Code Conventions](#testing-return-code-conventions)
- **[All]** Test-* functions **MUST** have tests for both `$true` and `$false` cases → [Testing Return Code Conventions](#testing-return-code-conventions)
- **[All]** Tests asserting property names on `[pscustomobject]` **MUST** use order-insensitive comparisons → [Testing Property Names on PSCustomObject](#testing-property-names-on-pscustomobject)
- **[All]** Tests asserting strongly-typed array properties **MUST** check non-emptiness first, then assert the exact array type with `-is`; **MUST NOT** permit `[object[]]` fallback → [Testing Strongly-Typed Array Properties](#testing-strongly-typed-array-properties)
- **[All]** Test `BeforeAll` dot-sourcing **MUST** use the `Split-Path` + `Join-Path` two-step pattern; multi-segment `Join-Path` forms **MUST NOT** be used → [Test File Dot-Sourcing Pattern](#test-file-dot-sourcing-pattern)
- **[All]** Tests iterating a returned collection with `foreach` **MUST** assert non-emptiness before the loop → [Defensive Assertions Before Iteration and Indexing](#defensive-assertions-before-iteration-and-indexing)
- **[All]** Tests accessing specific indices of a returned collection **MUST** assert count before any indexed access → [Defensive Assertions Before Iteration and Indexing](#defensive-assertions-before-iteration-and-indexing)
- **[All]** Tests asserting that a call does not throw **MUST** use `{ ... } | Should -Not -Throw` and **MUST NOT** rely on `try/catch` plus negated assertions on exception text → [Asserting Successful Execution With Should -Not -Throw](#asserting-successful-execution-with-should--not--throw)
- **[All]** PSScriptAnalyzer CI integrations that emit host-native diagnostics **MUST** use the active CI host's command format → [PSScriptAnalyzer CI Diagnostic Output](#psscriptanalyzer-ci-diagnostic-output)
- **[All]** Host-neutral, local, and interactive PSScriptAnalyzer runs **SHOULD** use plain output; ambiguous, missing, or contradictory host detection **MUST** fall back to plain output → [PSScriptAnalyzer CI Diagnostic Output](#psscriptanalyzer-ci-diagnostic-output)
- **[All]** CI Pester discovery and execution **MUST** be scoped to the project-owned `tests/` tree or documented test root, not the repository root → [Running Pester Tests](#running-pester-tests)
- **[All]** CI Pester discovery and the Pester configuration `Run.Path` **MUST** share one test-root source of truth and **SHOULD** guard missing test roots cleanly → [Running Pester Tests](#running-pester-tests)

## Executive Summary: Author Profile

The author's code writing style can be characterized as a highly disciplined "PowerShell v1.0 Classicist" approach when applicable. This is a deliberate engineering choice to ensure maximum backward compatibility with PowerShell version 1.0 in scenarios where the script could feasibly run on that platform, such as standalone string manipulation functions, data parsing utilities, or scripts that interact with basic Windows operating system information without external dependencies. It prioritizes portability, robustness, and deterministic behavior in legacy or mixed environments where newer PowerShell versions cannot be assumed. However, this v1.0 compatibility is not rigidly enforced; when external constraints require newer PowerShell versions (e.g., dependencies on modules like Az, which mandate Windows PowerShell 5.1 or PowerShell 7.x), the author readily adopts modern language constructs such as try/catch for error handling, advanced functions with [CmdletBinding()], and other features to align with the required runtime.

This explains the systematic avoidance of features introduced in v2.0 or later in v1.0-targeted scripts, such as advanced functions with the [CmdletBinding()] attribute, structured try/catch error handling, common parameters like -Verbose or -Debug, begin/process/end blocks, and modern output streams. Instead, the style relies on PowerShell's foundational mechanics, such as simple function declarations, strongly typed param blocks, explicit return statements for single values, and a custom error detection pattern using trap statements and global preference toggling.

Within these constraints, the author adheres closely to community best practices for readability, naming, documentation, and maintainability. Functions are designed as reusable tools with a single purpose—e.g., performing targeted data transformations or validations. Outputs are explicit and controlled: a status code (e.g., an integer indicating full success, partial success, or failure) is typically returned, while complex results are passed via reference parameters only when necessary to modify data in the caller's scope, avoiding unnecessary use of [ref] for read-only objects since it provides no performance benefits in PowerShell. Error handling is "fail-controlled," suppressing issues to allow graceful recovery without halting execution. The code is robust, thoroughly documented, and predictable across versions, making it ideal for tools in legacy or mixed environments. Performance is balanced with readability, favoring script constructs over pipelines. If the v1.0 constraint were lifted (e.g., due to modern dependencies), the style would evolve to incorporate features like pipeline-friendly objects and structured errors while retaining strong typing and documentation for clarity.

## Code Layout and Formatting

### Indentation Rules

Indentation **MUST** use four spaces for all logical blocks, including param declarations, conditional statements (if/else), loops, and function bodies—tabs **MUST NOT** be used.

### Brace Placement (OTBS)

Bracing **MUST** strictly adhere to the "One True Brace Style" (OTBS): opening braces **MUST** be placed at the end of the statement line, and closing braces **MUST** start on a new line, aligned with the opening statement. This applies universally to functions, conditionals, and most script blocks.

### Exception: catch, finally, and else Keywords

> **Exception for `catch`, `finally`, and `else`:** These keywords are the major exception to this rule. To be syntactically valid, the `catch`, `finally`, and `else` (or `elseif`) keywords **MUST** follow the closing brace (`}`) of the preceding block on the **same line**.
>
> **Compliant `if/else`:**
>
> ```powershell
> if ($condition) {
>     # ...
> } else {
>     # ...
> }
> ```
>
> **Compliant `try/catch`:**
>
> ```powershell
> try {
>     # ...
> } catch {
>     # ...
> } finally {
>     # ...
> }
> ```

### Operator Spacing and Alignment

Whitespace **MUST** be used precisely to enhance clarity: a single space **MUST** surround operators (e.g., -gt, =, -and, -eq) and **MUST** follow commas in parameter lists or arrays, with no unnecessary spaces inside parentheses, brackets, or subexpressions. Line terminators **SHOULD** avoid semicolons entirely, as they are unnecessary and can complicate edits. Line continuation **SHOULD** eschew backticks, preferring natural breaks at operators, pipes, or commas where possible—though in v1.0-focused code, long lines (e.g., in comments or regex patterns) **MAY** be tolerated for completeness. Line lengths **SHOULD** aim for under 115 characters where practical, but verbose comments **MAY** exceed this; this is acceptable per flexible guidelines, as it prioritizes detailed explanations without sacrificing core code readability.

Code **MUST** use **exactly one space** on either side of an operator (e.g., `=`, `-eq`). Code **MUST NOT** add extra whitespace to vertically align operators across multiple lines. This ensures compliance with standard PSScriptAnalyzer rules.

### Multi-line Method Indentation

When a method call (like `.Add()`) is wrapped (e.g., in a `[void]` cast) and its parameter is a multi-line script block (like a hashtable or `[pscustomobject]`), an **additional** level of indentation **MUST** be used for the contents of that script block.

```powershell
[void]($list.Add(
        [pscustomobject]@{
            # This line is indented three times:
            # 1. For the opening parenthesis
            # 2. For the .Add() method
            # 3. For the [pscustomobject]@{...} block
            Key = $Value
        }
    ))
```

### Blank Line Usage

Example snippet illustrating bracing, indentation, spacing, and blank lines:

```powershell
function ExampleFunction {
    param (
        [string]$ParamOne
    )

    if ($ParamOne -gt 0) {
        # Spaced operator example
    } else {
        # Alternative path
    }

    return 0
}
```

Blank lines **SHOULD** be used sparingly but effectively: two **SHOULD** surround function definitions for visual separation, and single blanks **SHOULD** group related logic within functions (e.g., before a block comment or between setup and main logic). Files **MUST** end with a single blank line. Regions (#region ... #endregion) **SHOULD** logically group elements like licenses or helper sections, improving navigability in larger scripts.

**Important:** Blank lines **MUST** be completely empty—they **MUST NOT** contain any whitespace characters (spaces or tabs). This ensures consistency and prevents issues with some editors and linters.

**Compliant (blank line is truly empty):**

```powershell
{
    Invoke-SomeCmdlet

    Invoke-AnotherCmdlet
}
```

**Non-Compliant (blank line contains spaces):**

```powershell
{
    Invoke-SomeCmdlet

    Invoke-AnotherCmdlet
}
```

In the non-compliant example, the blank line (line 3) contains spaces, which is not allowed.

### Trailing Whitespace

The prohibition on trailing whitespace is motivated by practical concerns: trailing whitespace can cause issues with version control systems, some editors, and linters. It also serves no functional purpose and reduces code consistency.

**Compliant (no trailing whitespace):**

```powershell
function ExampleFunction {
    param (
        [string]$ParamOne
    )
}
```

**Non-Compliant (trailing spaces on line 3):**

```powershell
function ExampleFunction {
    param (
        [string]$ParamOne   # ← trailing spaces here (not shown)
    )
}
```

In the non-compliant example, line 3 would end with trailing spaces after `$ParamOne` (before the comment), which is not allowed. The actual trailing spaces are not shown in this documentation to avoid violating the rule within this file itself.

**Lines MUST NOT end with trailing whitespace** (spaces or tabs). Most modern editors can be configured to automatically remove trailing whitespace on save, which is **RECOMMENDED**.

### Variable Delimiting in Strings

In addition to curly braces and the format operator, string concatenation is also an acceptable approach:

- **Compliant (Acceptable):** Use string concatenation.

  ```powershell
  $strMessage = ($SSORegion + ': Error occurred')
  ```

When a variable in an expandable string (`"..."`) is immediately followed by punctuation (especially a colon `:`) or other text that is not part of the variable name, it can cause parsing errors.

- **Non-Compliant (Ambiguous):**

  ```powershell
  $strMessage = "$SSORegion: Error occurred"
  ```

- **Compliant (Preferred):** Use curly braces to explicitly delimit the variable name:

  ```powershell
  $strMessage = "${SSORegion}: Error occurred"
  ```

- **Compliant (Also Preferred):** Use the `-f` format operator, which avoids all parsing ambiguity.

  ```powershell
  $strMessage = ("{0}: Error occurred" -f $SSORegion)
  ```

### String Formatting in Cmdlet Arguments (`-f` Scoping)

When a string expression is composed inline and passed to a cmdlet using parentheses as the argument, a common mistake is to place the `-f` format operator *after* the closing parenthesis of the argument expression. For example:

```powershell
Write-Warning ("foo {0}" + "bar") -f $x
```

In this case, PowerShell's parser treats the parenthesized expression `("foo {0}" + "bar")` as the complete argument to `Write-Warning`. The `-f` that follows is then parsed as a *parameter token* on `Write-Warning`, not as the format operator. Depending on the cmdlet, this produces either a parameter-binding error (e.g., *"A parameter cannot be found that matches parameter name 'f'"*) or, on commands that happen to have a parameter starting with `f`, an unexpected and silent misbinding.

This mistake is easy to make when composing strings inline because the developer mentally groups the entire expression including `-f` as a single unit, but PowerShell's parser does not. The parentheses close the argument expression before `-f` is reached.

The preferred fix is to nest the entire format expression inside the argument-expression parentheses:

```powershell
Write-Warning (("foo {0}" + "bar") -f $x)
```

Here the outer parentheses define the argument expression, and within them the inner parentheses plus `-f` form a complete format operation. PowerShell evaluates the whole expression before passing the result to `Write-Warning`.

Alternatively, assigning the formatted string to a variable before the cmdlet call avoids the nesting entirely and may improve readability for complex expressions:

```powershell
$strMessage = ("foo {0}" + "bar") -f $x
Write-Warning $strMessage
```

In the variable-assignment case, there are no cmdlet-parameter semantics in play, so `-f` is unambiguously the format operator. This pattern is particularly useful when the format expression is long or involves multiple placeholders.

When a composed string expression is passed to a cmdlet or language construct using parentheses as the argument expression (for example `Write-Warning`, `Write-Host`, `Write-Error`, `Write-Verbose`, `Write-Debug`, `Write-Output`, or `throw (...)`), any `-f` format operator **MUST** be applied inside the same parentheses that form the argument expression. Once the argument-expression parentheses close, PowerShell may parse `-f` as a parameter token rather than as the format operator.

See also [Variable Delimiting in Strings](#variable-delimiting-in-strings) for broader guidance on composing strings safely.

- **Non-Compliant:**

  ```powershell
  Write-Warning ("foo {0}" + "bar") -f $x
  ```

- **Compliant (Preferred):** Place the `-f` operator inside the argument-expression parentheses:

  ```powershell
  Write-Warning (("foo {0}" + "bar") -f $x)
  ```

- **Compliant (Alternative):** Assign the formatted string to a variable first:

  ```powershell
  $strMessage = ("foo {0}" + "bar") -f $x
  Write-Warning $strMessage
  ```

### File Encoding

UTF-8 does not require a BOM. A leading BOM is an invisible character that can cause practical problems, including interfering with regex-based text processing, breaking shebang (`#!`) handling on Linux/macOS, and creating unnecessary cross-tool inconsistencies or diff noise. Saving `.ps1` files as BOM-less UTF-8 avoids these issues and aligns with modern editor and automation behavior.

However, there is an important compatibility caveat: Windows PowerShell (v5.1 and earlier) does not assume UTF-8 for BOM-less files. Instead, it falls back to the system's ANSI code page. This means non-ASCII characters in a BOM-less UTF-8 script can be silently misinterpreted on legacy hosts. The actionable rule in the main guide addresses this with an explicit exception: scripts that contain non-ASCII characters and must target Windows PowerShell either need a BOM or must stay ASCII-only. For the vast majority of scripts (which are ASCII-only), BOM-less UTF-8 is safe across all PowerShell versions.

#### VS Code Configuration Example

VS Code defaults to UTF-8 without BOM (`files.encoding: utf8`), so no change is typically needed. To verify, check the encoding shown in the status bar at the bottom-right of the window. To make the intent explicit in a workspace, add `"files.encoding": "utf8"` to `.vscode/settings.json`. The value `"utf8"` means no BOM; `"utf8bom"` would add one. For the rare case where a script must contain non-ASCII characters and target Windows PowerShell, use `"utf8bom"` instead, per the exception in the actionable rule. To scope the setting to PowerShell files only, use a `"[powershell]"` language-specific override:

```json
{
    "[powershell]": {
        "files.encoding": "utf8"
    }
}
```

PowerShell `.ps1` source files **MUST** be saved as UTF-8 **without** a Byte Order Mark (BOM, `U+FEFF`), **unless** the script contains non-ASCII characters (e.g., accented characters, CJK text, or special symbols in string literals or comments) **and** must run on Windows PowerShell v5.1 or earlier. In that case, the file **MUST** either (a) be saved as UTF-8 **with** BOM so that Windows PowerShell can detect the encoding, or (b) remain ASCII-only so that BOM-less UTF-8 and the system ANSI code page produce identical byte sequences. This exception does not apply to PowerShell 7+, which defaults to UTF-8. Editors used for PowerShell development **SHOULD** be configured to save `.ps1` files as UTF-8 without BOM by default. If tool-specific examples are included, they **SHOULD** be presented as examples rather than assumptions that all environments behave identically.

### Programmatic File Writing Encoding

The default encoding used by `Set-Content`, `Out-File`, and the `>` redirection operator varies significantly across PowerShell versions. In Windows PowerShell 5.1, `Set-Content` defaults to the system ANSI code page, while `Out-File` and `>` default to UTF-16 LE (with BOM). In PowerShell 7+, all three default to UTF-8 without BOM. This divergence means that a script relying on default encoding can produce different output depending on the host, making build artifacts non-deterministic.

The `.NET` `System.Text.UTF8Encoding` approach is preferred for cross-version determinism because it is available in every PowerShell version (including v1.0) and produces identical output regardless of host. The constructor argument `$false` suppresses the BOM, matching the project's source file encoding convention.

The `-Encoding utf8NoBOM` parameter value was introduced in PowerShell 6.0 (Core). It does not exist in Windows PowerShell 5.1, so requiring it as the standard pattern would break backward compatibility. For projects that explicitly target only PowerShell 7+, using `-Encoding utf8NoBOM` with cmdlets is an acceptable alternative.

When writing or generating text files programmatically (for example, build scripts producing `.psm1` files or code generators producing repository artifacts), the output encoding **MUST** be specified explicitly so results are deterministic across PowerShell versions.

The preferred cross-version pattern for UTF-8 without BOM **SHOULD** use a `.NET` encoding object:

```powershell
$objUtf8NoBomEncoding = New-Object System.Text.UTF8Encoding($false)
[System.IO.File]::WriteAllText($strOutputFilePath, $strFileContent, $objUtf8NoBomEncoding)
```

`Set-Content` and similar cmdlets **MUST** include an explicit `-Encoding` parameter when writing generated artifacts, because default encoding behavior varies across PowerShell versions and can make output non-deterministic.

`-Encoding utf8NoBOM` **MUST NOT** be the required cross-version pattern, because it is unavailable in Windows PowerShell 5.1. For code that explicitly targets only PowerShell 7+, it **MAY** be used.

### Line Endings for Byte-Exact Text Artifacts

Some PowerShell workloads produce text whose identity is its exact byte sequence: golden/snapshot test baselines, files fed into cryptographic hash functions, signed payloads, and other artifacts that are later compared byte-for-byte. For these artifacts, a single stray CRLF where an LF was expected — or vice versa — is enough to cause a hash mismatch, a signature verification failure, or a confusing snapshot diff.

The built-in serializers in PowerShell do not guarantee a stable line-ending convention across hosts. In particular, `ConvertTo-Json` has historically emitted different line endings across PowerShell versions and platforms: some versions produce CRLF inside the serialized output even on Linux and macOS, while others produce LF. Code that trusts the serializer to produce a canonical byte sequence will therefore pass on one host and fail on another. The only reliable remedy at the PowerShell layer is to normalize line endings in memory after serialization and before writing or comparing, for example by replacing `` `r`n `` with `` `n `` on the serialized string. This makes the output deterministic regardless of the serializer's per-host behavior.

On the read side, `Get-Content` without `-Raw` is also unsuitable for byte-exact comparison. It returns an array of lines rather than the original on-disk text, and the line terminators themselves are stripped during that split. The reconstructed string is therefore not guaranteed to equal the bytes that were written — it loses both the specific terminator used (CRLF vs LF) and any trailing newline. `Get-Content -Raw` reads the entire file into a single string and preserves the decoded text verbatim, including embedded and trailing newlines, which is what text-level identity comparison requires. It does still decode the file contents, however, so it is not a byte-for-byte read and can hide differences such as a UTF-8 BOM or other encoding-level distinctions. When true byte-exact comparison is required — most notably for cryptographic hash inputs and signed payloads — use `[System.IO.File]::ReadAllBytes()`, which returns the raw byte array with no decoding. `[System.IO.File]::ReadAllText()` is the corresponding .NET option for text-centric codepaths and shares the same decoding caveat as `Get-Content -Raw`. Both .NET APIs are subject to the path-resolution discipline described in [Resolving Paths for .NET Static Methods](#resolving-paths-for-net-static-methods).

Repository-level controls such as `.gitattributes` entries that pin committed text files to LF can also matter for artifacts stored in version control, because Git's own line-ending handling can otherwise rewrite bytes between commit and checkout. That concern sits above the PowerShell language layer and is intentionally out of scope for `STYLE_GUIDE.md`, which only covers how `.ps1` code serializes and reads byte-exact text.

When a PowerShell script or test produces text output whose identity is its exact byte sequence (for example, golden baselines, snapshot fixtures, hash inputs, or signed payloads), the producer **MUST** normalize line endings to LF at serialization time. Consumers reading the entire file as text **MUST NOT** use `Get-Content` without `-Raw`; they **MUST** use `Get-Content -Raw` or the equivalent .NET `[System.IO.File]::ReadAllText()` API. Those text-returning APIs are acceptable only for text-level comparison when the encoding convention, including BOM presence or absence, is already fixed. For true byte-for-byte identity (for example, hash inputs and signed payloads), consumers **MUST** use `[System.IO.File]::ReadAllBytes()`, because `Get-Content -Raw` and `[System.IO.File]::ReadAllText()` decode bytes into a `System.String` and can mask byte-level differences such as a UTF-8 BOM or other encoding distinctions.

Cross-version differences in `ConvertTo-Json` and other serializers can emit CRLF on some hosts and LF on others, causing byte-exact comparisons to fail unless line endings are normalized in memory before writing or comparing. The recommended pattern is to normalize CRLF to LF immediately after serialization:

```powershell
$strJson = $objInput | ConvertTo-Json -Depth 5
$strJson = $strJson -replace "`r`n", "`n"
# If the artifact convention requires a trailing LF, also append one:
# $strJson = $strJson + "`n"
```

`Get-Content` without `-Raw` strips line terminators and returns an array of lines rather than the original on-disk text, so it **MUST NOT** be used for byte-exact comparison. Use `Get-Content -Raw` or `[System.IO.File]::ReadAllText()` to read the decoded text as a single string when the comparison is text-level, or use `[System.IO.File]::ReadAllBytes()` when true byte-for-byte identity is required. When using the .NET APIs, paths **MUST** first be resolved to an absolute filesystem path per [Resolving Paths for .NET Static Methods](#resolving-paths-for-net-static-methods).

## Capitalization and Naming Conventions

Public identifiers (functions, parameters, properties) **MUST** use PascalCase. Keywords (`function`, `param`, `if`, `else`, `return`, `trap`) **MUST** be lowercase. Operators (`-gt`, `-eq`) **MUST** be lowercase with surrounding spaces. Local variables **MUST** use camelCase with a type-hinting prefix (e.g., `$strMessage`, `$intReturnValue`, `$boolResult`, `$arrElements`).

### Overview of Observed Naming Discipline

The author exhibits an uncompromising commitment to **explicit, self-documenting identifiers** across all code elements. This manifests as a complete rejection of aliases, abbreviations, or any form of shorthand in function names, parameter names, or command invocations. Every identifier is fully spelled out using clear, descriptive language that communicates intent without requiring external context or documentation lookup. This practice eliminates ambiguity and future-proofs the code against changes in command behavior or parameter sets—common sources of subtle bugs in PowerShell scripting.

The naming strategy is rooted in **.NET Framework capitalization conventions**, treating PowerShell as a .NET scripting language. This results in:

- **PascalCase** for all public-facing identifiers (function names, parameters, properties).
- **lowercase** for PowerShell language keywords (`function`, `param`, `if`, `else`, `return`, `trap`).
- **camelCase with type-hinting prefixes** for local variables. **These MUST be fully descriptive and non-abbreviated** (e.g., `$strMessage`, `$intReturnValue`, `$objMemoryStream`).
- **Noun-based naming for Modules**, treating them as containers/namespaces (e.g., `ObjectFlattener`) distinct from the executable actions they contain.

This consistent application creates a visual hierarchy that allows rapid comprehension of code structure and data flow, even in large or complex functions.

### Script and Function Naming: Full Explicit Form

**Function names** **MUST** strictly adhere to the **Verb-Noun** pattern using **approved verbs** and **singular nouns**, rendered in **PascalCase**. Examples include:

- `Convert-StringToObject`
- `Get-ReferenceToLastError`
- `Test-ErrorOccurred`
- `Split-StringOnLiteralString`

### Script and Function Naming: Approved Verbs

Using approved verbs is a core PowerShell convention that ensures discoverability and consistency. You **MAY** always retrieve the complete list of approved verbs by running the following command:

```powershell
Get-Verb
```

If a verb (like `Review` or `Check`) is not on this list, you **MUST** choose the closest approved alternative, such as `Get-` (to retrieve information) or `Test-` (to return a boolean).

The list of approved PowerShell verbs can be viewed [on Microsoft's Docs page](https://learn.microsoft.com/en-us/powershell/scripting/developer/cmdlet/approved-verbs-for-windows-powershell-commands?view=powershell-7.5). For offline scenarios, a copy of this page is included below, retrieved on November 3, 2025:

PowerShell uses a verb-noun pair for the names of cmdlets and for their derived .NET classes. The verb part of the name identifies the action that the cmdlet performs. The noun part of the name identifies the entity on which the action is performed. For example, the `Get-Command` cmdlet retrieves all the commands that are registered in PowerShell.

> **Note:** PowerShell uses the term *verb* to describe a word that implies an action even if that word isn't a standard verb in the English language. For example, the term `New` is a valid PowerShell verb name because it implies an action even though it isn't a verb in the English language.

Each approved verb has a corresponding *alias prefix* defined. We use this alias prefix in aliases for commands using that verb. For example, the alias prefix for `Import` is `ip` and, accordingly, the alias for `Import-Module` is `ipmo`. This is a recommendation but not a rule; in particular, it need not be respected for command aliases mimicking well known commands from other environments.

#### Verb Naming Recommendations

The following recommendations help you choose an appropriate verb for your cmdlet, to ensure consistency between the cmdlets that you create, the cmdlets that are provided by PowerShell, and the cmdlets that are designed by others.

- Use one of the predefined verb names provided by PowerShell
- Use the verb to describe the general scope of the action, and use parameters to further refine the action of the cmdlet.
- Don't use a synonym of an approved verb. For example, always use `Remove`, never use `Delete` or `Eliminate`.
- Use only the form of each verb that's listed in this topic. For example, use `Get`, but don't use `Getting` or `Gets`.
- Don't use the following reserved verbs or aliases. The PowerShell language and a rare few cmdlets use these verbs under exceptional circumstances.
  - `ForEach` (`foreach`)
  - `Ping` (`pi`)
  - `Sort` (`sr`)
  - `Tee` (`te`)
  - `Where` (`wh`)

You **MAY** get a complete list of verbs using the `Get-Verb` cmdlet.

#### Approved Verb Tables — Action Descriptions

The full verb tables previously included an "Action" column describing what each verb does. These descriptions are from [Microsoft's Approved Verbs documentation](https://learn.microsoft.com/en-us/powershell/scripting/developer/cmdlet/approved-verbs-for-windows-powershell-commands?view=powershell-7.5). The condensed tables in the main guide retain verb names, aliases, and synonyms to avoid.

Functions **MUST** use approved PowerShell verbs. Run `Get-Verb` for the complete list. If a verb (like `Review` or `Check`) is not approved, choose the closest alternative (e.g., `Get-` or `Test-`). For the full reference, see [Microsoft's Approved Verbs](https://learn.microsoft.com/en-us/powershell/scripting/developer/cmdlet/approved-verbs-for-windows-powershell-commands?view=powershell-7.5).

> **Note:** The term *verb* in PowerShell describes any word implying an action, even if it isn't a standard English verb (e.g., `New`).

**Reserved verbs** (do not use): `ForEach` (`foreach`), `Ping` (`pi`), `Sort` (`sr`), `Tee` (`te`), `Where` (`wh`).

#### Similar Verbs for Different Actions

The following similar verbs represent different actions.

##### `New` vs. `Add`

Use the `New` verb to create a new resource. Use the `Add` to add something to an existing container or resource. For example, `Add-Content` adds output to an existing file.

##### `New` vs. `Set`

Use the `New` verb to create a new resource. Use the `Set` verb to modify an existing resource, optionally creating it if it doesn't exist, such as the `Set-Variable` cmdlet.

##### `Find` vs. `Search`

Use the `Find` verb to look for an object. Use the `Search` verb to create a reference to a resource in a container.

##### `Get` vs. `Read`

Use the `Get` verb to obtain information about a resource (such as a file) or to obtain an object with which you can access the resource in future. Use the `Read` verb to open a resource and extract information contained within.

##### `Invoke` vs. `Start`

Use the `Invoke` verb to perform synchronous operations, such as running a command and waiting for it to end. Use the `Start` verb to begin asynchronous operations, such as starting an autonomous process.

##### `Ping` vs. `Test`

Use the `Test` verb.

#### Common Verbs

| Verb (alias) | Synonyms to avoid |
| --- | --- |
| `Add` (`a`) | Append, Attach, Concatenate, Insert |
| `Clear` (`cl`) | Flush, Erase, Release, Unmark, Unset, Nullify |
| `Close` (`cs`) | |
| `Copy` (`cp`) | Duplicate, Clone, Replicate, Sync |
| `Enter` (`et`) | Push, Into |
| `Exit` (`ex`) | Pop, Out |
| `Find` (`fd`) | Search |
| `Format` (`f`) | |
| `Get` (`g`) | Read, Open, Cat, Type, Dir, Obtain, Dump, Acquire, Examine, Find, Search |
| `Hide` (`h`) | Block |
| `Join` (`j`) | Combine, Unite, Connect, Associate |
| `Lock` (`lk`) | Restrict, Secure |
| `Move` (`m`) | Transfer, Name, Migrate |
| `New` (`n`) | Create, Generate, Build, Make, Allocate |
| `Open` (`op`) | |
| `Optimize` (`om`) | |
| `Pop` (`pop`) | |
| `Push` (`pu`) | |
| `Redo` (`re`) | |
| `Remove` (`r`) | Clear, Cut, Dispose, Discard, Erase |
| `Rename` (`rn`) | Change |
| `Reset` (`rs`) | |
| `Resize` (`rz`) | |
| `Search` (`sr`) | Find, Locate |
| `Select` (`sc`) | Find, Locate |
| `Set` (`s`) | Write, Reset, Assign, Configure, Update |
| `Show` (`sh`) | Display, Produce |
| `Skip` (`sk`) | Bypass, Jump |
| `Split` (`sl`) | Separate |
| `Step` (`st`) | |
| `Switch` (`sw`) | |
| `Undo` (`un`) | |
| `Unlock` (`uk`) | Release, Unrestrict, Unsecure |
| `Watch` (`wc`) | |

#### Communications Verbs

| Verb (alias) | Synonyms to avoid |
| --- | --- |
| `Connect` (`cc`) | Join, Telnet, Login |
| `Disconnect` (`dc`) | Break, Logoff |
| `Read` (`rd`) | Acquire, Prompt, Get |
| `Receive` (`rc`) | Read, Accept, Peek |
| `Send` (`sd`) | Put, Broadcast, Mail, Fax |
| `Write` (`wr`) | Put, Print |

#### Data Verbs

| Verb (alias) | Synonyms to avoid |
| --- | --- |
| `Backup` (`ba`) | Save, Burn, Replicate, Sync |
| `Checkpoint` (`ch`) | Diff |
| `Compare` (`cr`) | Diff |
| `Compress` (`cm`) | Compact |
| `Convert` (`cv`) | Change, Resize, Resample |
| `ConvertFrom` (`cf`) | Export, Output, Out |
| `ConvertTo` (`ct`) | Import, Input, In |
| `Dismount` (`dm`) | Unmount, Unlink |
| `Edit` (`ed`) | Change, Update, Modify |
| `Expand` (`en`) | Explode, Uncompress |
| `Export` (`ep`) | Extract, Backup |
| `Group` (`gp`) | |
| `Import` (`ip`) | BulkLoad, Load |
| `Initialize` (`in`) | Erase, Init, Renew, Rebuild, Reinitialize, Setup |
| `Limit` (`l`) | Quota |
| `Merge` (`mg`) | Combine, Join |
| `Mount` (`mt`) | Connect |
| `Out` (`o`) | |
| `Publish` (`pb`) | Deploy, Release, Install |
| `Restore` (`rr`) | Repair, Return, Undo, Fix |
| `Save` (`sv`) | |
| `Sync` (`sy`) | Replicate, Coerce, Match |
| `Unpublish` (`ub`) | Uninstall, Revert, Hide |
| `Update` (`ud`) | Refresh, Renew, Recalculate, Re-index |

#### Diagnostic Verbs

| Verb (alias) | Synonyms to avoid |
| --- | --- |
| `Debug` (`db`) | Diagnose |
| `Measure` (`ms`) | Calculate, Determine, Analyze |
| `Ping` (`pi`) — *deprecated; use `Test`* | |
| `Repair` (`rp`) | Fix, Restore |
| `Resolve` (`rv`) | Expand, Determine |
| `Test` (`t`) | Diagnose, Analyze, Salvage, Verify |
| `Trace` (`tr`) | Track, Follow, Inspect, Dig |

#### Lifecycle Verbs

| Verb (alias) | Synonyms to avoid |
| --- | --- |
| `Approve` (`ap`) | |
| `Assert` (`as`) | Certify |
| `Build` (`bd`) — *PS 6+* | |
| `Complete` (`cp`) | |
| `Confirm` (`cn`) | Acknowledge, Agree, Certify, Validate, Verify |
| `Deny` (`dn`) | Block, Object, Refuse, Reject |
| `Deploy` (`dp`) — *PS 6+* | |
| `Disable` (`d`) | Halt, Hide |
| `Enable` (`e`) | Start, Begin |
| `Install` (`is`) | Setup |
| `Invoke` (`i`) | Run, Start |
| `Register` (`rg`) | |
| `Request` (`rq`) | |
| `Restart` (`rt`) | Recycle |
| `Resume` (`ru`) | |
| `Start` (`sa`) | Launch, Initiate, Boot |
| `Stop` (`sp`) | End, Kill, Terminate, Cancel |
| `Submit` (`sb`) | Post |
| `Suspend` (`ss`) | Pause |
| `Uninstall` (`us`) | |
| `Unregister` (`ur`) | Remove |
| `Wait` (`w`) | Sleep, Pause |

#### Security Verbs

| Verb (alias) | Synonyms to avoid |
| --- | --- |
| `Block` (`bl`) | Prevent, Limit, Deny |
| `Grant` (`gr`) | Allow, Enable |
| `Protect` (`pt`) | Encrypt, Safeguard, Seal |
| `Revoke` (`rk`) | Remove, Disable |
| `Unblock` (`ul`) | Clear, Allow |
| `Unprotect` (`up`) | Decrypt, Unseal |

#### Other Verbs

| Verb (alias) | Synonyms to avoid |
| --- | --- |
| `Use` (`u`) | |

### Script and Function Naming: Nouns

**Noun Singularity:** The noun **MUST** be singular, even if the function returns multiple objects. This is a core PowerShell convention (e.g., `Get-Process`, `Get-ChildItem`) and corresponds to the **PSScriptAnalyzer `PSUseSingularNouns`** rule. The noun describes the *type* of object the function works with, not the *quantity* of its output.

- **Correct:** `Get-Process` (returns *many* process objects)
- **Incorrect:** `Get-Processes`
- **Correct:** `Expand-TrustPrincipal` (operates on *one* principal node, even if it results in many values)
- **Incorrect:** `Expand-TrustPrincipals`

### Module Naming: Noun-Based Containers

In the .NET Framework design philosophy, a **Verb-Noun** phrase represents an executable *method* or *command* (an action). A **Noun** represents the *class*, *library*, or *tool* that contains those capabilities (the container). Naming a module using a Verb-Noun pattern (e.g., `FlattenObject`) blurs this distinction and creates cognitive dissonance, leading users to falsely expect a command named `Flatten-Object` to exist.

By naming the module `ObjectFlattener` (the tool) and the function `ConvertTo-FlatObject` (the action), the architecture remains semantically pure and aligned with Microsoft’s own structural standards (e.g., the module `Microsoft.Graph` contains the command `Get-MgUser`).

The discoverability strategy relies on the **Module Manifest (`.psd1`)** rather than compromising the architectural name. The `Tags` key in the manifest handles keyword searching, keeping the module name pure while ensuring findability during searches.

Module manifests (`.psd1`) are a PowerShell v2.0+ feature — they do not exist in PowerShell v1.0. Manifest-specific guidance therefore cannot carry the `[All]` scope tag, which by convention means "all PowerShell versions, including v1.0." The general module naming rule remains `[All]` because PascalCase noun naming is applicable regardless of PowerShell version, while the manifest-specific `Tags` discoverability guidance is explicitly `[Modern]`.

**Modules are treated as .NET Namespaces or Class Libraries (Containers), not Actions.** Therefore, Module names **MUST** be **PascalCase Nouns** or **Noun Phrases**.

- **Correct:** `ObjectFlattener`, `NetworkManager`, `DataParser`
- **Incorrect:** `FlattenObject`, `ManageNetwork`, `ParseData`

Module names **MUST NOT** be compromised for the sake of keyword searching.

**[Modern]** In module-based code, the **Module Manifest (`.psd1`)** handles discoverability. The `Tags` key in the manifest **MUST** be populated aggressively with relevant keywords (including verbs) to ensure the module is found during searches, while keeping the architectural name pure.

### Do Not Use Aliases

Using full command names ensures:

1. **Discoverability**: The code is immediately understandable to any PowerShell user.
2. **Future-proofing**: Changes to parameter sets in underlying cmdlets cannot break the script due to positional or partial-name matching.
3. **Syntax highlighting**: Full names trigger proper IDE and GitHub syntax coloring.

Aliases (e.g., `gci`, `gps`) or abbreviated forms **MUST NOT** appear in the code. Even common operations **MUST** use full command names.

Furthermore, **Modules MUST NOT export "Compatibility Aliases"** solely to bridge a gap between a module name and a command name (e.g., do **not** export `Flatten-Object` when the correct command is `ConvertTo-FlatObject`).

**Exceptions:**

Aliases **MAY** only be exported in a Module Manifest if they provide genuine short-hand convenience for *interactive* users (e.g., `cfo` for `ConvertTo-FlatObject`) and are strictly documented as optional. They **MUST NOT** be used to mask non-approved verbs.

### Parameter Naming

Examples of descriptive parameter names:

- `$ReferenceToResultObject` — clearly indicates a `[ref]` parameter for result storage
- `$ReferenceArrayOfExtraStrings` — describes both the reference mechanism and content type
- `$StringToProcess` — specifies both the type and purpose
- `$PSVersion` — follows the established PowerShell naming convention

These names leave no ambiguity about the parameter's purpose, expected type, or direction of data flow. The use of `ReferenceTo` prefix for `[ref]` parameters is a deliberate pattern that instantly signals pass-by-reference semantics — a critical distinction in PowerShell v1.0 where such mechanics are not visually obvious.

**Parameter names** **MUST** use PascalCase and be highly descriptive (e.g., `$ReferenceToResultObject`, `$StringToProcess`, `$PSVersion`). The `ReferenceTo` prefix for `[ref]` parameters signals **pass-by-reference** semantics. [ref] **MUST** be used only when data needs to be written back to the caller’s scope; for passing complex objects that do not need modification, pass by value.

### Local Variable Naming: Type-Prefixed camelCase

This prefixing is **not** a legacy artifact but a **deliberate design decision** to compensate for PowerShell's dynamic typing and the frequent absence of modern IDE tooling. The prefix:

- **Eliminates type inference errors** during debugging
- **Reduces cognitive load** when reading code without IntelliSense
- **Prevents accidental type mismatches** in complex logic flows

#### Why Ad Hoc Abbreviated Type Prefixes Are Called Out

The prefix list in [Local Variable Naming: Type-Prefixed camelCase](#local-variable-naming-type-prefixed-camelcase) is intentionally **open-ended** for additional descriptive prefixes — the main guide explicitly permits prefixes like `$ref` and `$version` when they provide immediate type clarity — but **canonical** for the common built-in types it already names: `$obj` is established as the default prefix for any .NET type without a dedicated approved prefix (including enum values), and `$hashtable` is established as the canonical prefix for hashtable variables. Authors remain free to introduce *new* descriptive prefixes for types the list does not cover; what they **SHOULD NOT** do is invent *parallel abbreviated* prefixes for types the list already handles (such as `$enum…` for enums or `$hash…` for hashtables). Doing so fragments the convention: reviewers scanning code can no longer rely on a single, predictable token to identify a variable's type, and searches for `$hashtable` (or for `$obj` on enums) miss the ad hoc variants.

Two specific substitutions are called out because they are the most tempting mistakes:

- **`$enum…` → `$obj…`.** An enum is a .NET type without a dedicated approved prefix, so it falls under the default `$obj` bucket exactly like any other such type. Introducing a separate `$enum` prefix would imply that enums are a first-class category in the prefix list, when in fact the guide's design is for `$obj` to absorb all such types uniformly.
- **`$hash…` → `$hashtable…`.** `$hash` is a natural-looking shortening, but the approved prefix is the fully spelled `$hashtable`. The descriptive-portion rule already forbids abbreviations in the body of a variable name; applying the same discipline to the prefix keeps the type-hinting convention internally consistent and avoids ambiguity with unrelated uses of the word "hash" (e.g., cryptographic hashes, hash codes).

Consistency with the documented prefix list is what keeps the type-hinting convention useful and predictable. Every deviation that is individually "obvious" erodes the guarantee that a reader can identify a variable's type from its prefix alone.

Local variables follow a **Hungarian-style notation** combining a **type-hinting prefix** with **descriptive `camelCase`**. **The descriptive portion of each name—everything after the type prefix—MUST be fully spelled out; abbreviations and shorthand are not permitted.**

- **Prefixes:** `$str` (string), `$int` (integer), `$dbl` (double), `$bool` (boolean), `$arr` (array), `$obj` (object/default), `$hashtable` (hashtable), `$list` (generic list), etc.
- **Default prefix — `obj`:** Use `$obj` for any .NET type that does not have a dedicated approved prefix above. This includes enum values (e.g., `$objActionPreference`), complex .NET reference types (e.g., `$objMemoryStream`), and `[pscustomobject]` instances (e.g., `$objResult`).
- **Open-ended list:** The "etc." above means additional descriptive prefixes such as `$ref` and `$version` are permitted when they provide immediate type clarity (e.g., `$refLastKnownError`, `$versionPowerShell`). However, authors **SHOULD NOT** invent ad hoc abbreviated type-name prefixes when a canonical documented prefix already exists. Specifically:
  - Do **not** use `$enumActionPreference`; use `$objActionPreference` instead (enum values fall under the default `$obj` prefix).
  - Do **not** use `$hashSeen`, `$hashResult`, etc.; use `$hashtableSeen`, `$hashtableResult`, etc. instead (the canonical prefix for hashtables is `$hashtable`, not the abbreviated `$hash`).
- **Descriptive Name:** The name **MUST** be **fully spelled out**.

**Examples:**

- `$strPolicyString` (not `$strS` or `$strPolicy`)
- `$objMemoryStream` (not `$objMs` or `$stream`)
- `$arrStatements` (not `$arrStmt` or `$stmts`)
- `$strMessage`
- `$intReturnValue`
- `$boolResult`
- `$arrElements`
- `$hashtableSettings`
- `$objActionPreference`
- `$objResult`
- `$refLastKnownError`
- `$versionPowerShell`

### Local Variable Naming: Defensive Design Philosophy

While some modern styles discourage type prefixes on local variables, in this context they represent **defensive programming**—a hallmark of the robustness philosophy that applies to all scripts regardless of target PowerShell version.

### Path and Scope Handling

Code **SHOULD** avoid relative paths (`.`, `..`) and the **home directory shortcut `~`** entirely. This is due to:

- `~` behavior varies by provider (FileSystem vs. Registry vs. others).
- Relative paths depend on `[Environment]::CurrentDirectory`, which **MAY** diverge from `$PWD` when calling .NET methods or external tools.

Instead, **explicit scoping** **SHOULD** be used:

```powershell
$global:ErrorActionPreference
```

For shared state, use:

- `$Script:varName` for module/script-level variables
- `$Global:varName` for session-wide state

This eliminates environment-dependent behavior and ensures deterministic execution.

> **Note:** The guidance to avoid relative paths targets bare `.` / `..` paths
> that depend on `[Environment]::CurrentDirectory` or `$PWD`. Paths anchored to
> `$PSScriptRoot` — such as `"$PSScriptRoot/../config.json"` or
> `Join-Path -Path $PSScriptRoot -ChildPath '../src/Helper.ps1'` — are
> **deterministic** because they resolve relative to the executing script's
> directory, not the process working directory.

**Non-compliant** (CWD-dependent):

```powershell
# Bad — result changes depending on where the caller invoked the script:
Get-Content -Path '../config.json'
```

**Compliant** (`$PSScriptRoot`-anchored):

```powershell
# Good — always resolves relative to the script's own directory:
Get-Content -LiteralPath (Join-Path -Path $PSScriptRoot -ChildPath '../config.json')
```

#### Resolving Paths for .NET Static Methods

**[All]** When a script or function passes a user-provided or otherwise unresolved PowerShell path to a .NET file API (for example, `[System.IO.File]::WriteAllText()`, `[System.IO.File]::WriteAllLines()`, or other `System.IO.*` methods that expect a file-system path), the path **MUST** first be converted to an absolute file-system path via `$ExecutionContext.SessionState.Path.GetUnresolvedProviderPathFromPSPath()`. This method assumes the path resolves through the FileSystem provider; non-FileSystem provider paths (such as `HKLM:\…` or `Cert:\…`) **MUST NOT** be passed to `System.IO.*` methods.

**Compliant:**

```powershell
# Resolve the PowerShell path before passing it to .NET
$strOutputPath = '.\output.txt'
$strOutputPath = $ExecutionContext.SessionState.Path.GetUnresolvedProviderPathFromPSPath($strOutputPath)
[System.IO.File]::WriteAllText($strOutputPath, $strContent, $objEncoding)
```

**Non-Compliant:**

```powershell
# Non-Compliant: passing an unresolved PowerShell path directly to a .NET method
$strOutputPath = '.\output.txt'
[System.IO.File]::WriteAllText($strOutputPath, $strContent, $objEncoding)
```

### Options for Local Variable Prefixes: Analysis

The broader PowerShell community considers the use of type prefixes on local variables a **"matter of taste"** for private variables. Some style guides recommend plain camelCase (e.g., `$message`, `$count`) as a cleaner, more modern approach that aligns with .NET naming conventions. Below is a comparison of the two approaches for context:

| Option | Description | Pros | Cons |
| --- | --- | --- | --- |
| **1. Type Prefixes** (e.g., `$strMessage`, `$intCount`) | Hungarian-style notation **(required by this style guide)** | • Immediate type visibility in plain text • Critical in v1.0 without IDE support • Reduces runtime type errors • Self-documenting in large functions | • Increases visual noise • Feels dated in modern editors • **Intentionally longer variable names** (as abbreviations are forbidden) |
| **2. Plain camelCase** (e.g., `$message`, `$count`) | Community alternative **(not permitted in this codebase)** | • Cleaner, more modern aesthetic • Aligns with .NET naming simplicity • Shorter, easier to type | • Requires IDE/IntelliSense for type clarity • Risk of confusion in complex logic • Less resilient in plain-text review |

**This style guide requires type prefixes (Option 1) in all code.** Plain camelCase is a valid community alternative, but it is **not permitted** in this codebase. The clarity benefit of type prefixes outweighs verbosity regardless of target PowerShell version, as IDE support cannot always be assumed and the prefixes provide immediate type context in any environment.

### Summary: Naming as Defensive Architecture

The author's naming conventions are not merely stylistic—they form a **defensive architecture** that:

1. **Eliminates ambiguity** through full explicit names.
2. **Future-proofs** against command evolution.
3. **Provides immediate type context** via type prefixes.
4. **Ensures deterministic behavior** through explicit scoping.

This results in code that is **self-documenting**, **resilient to change**, and **immediately comprehensible** to any PowerShell practitioner—regardless of their familiarity with the specific script.

## Documentation and Comments

### Overview of Documentation Philosophy

The author treats **documentation as a first-class citizen** of the codebase, embedding comprehensive, structured, and immediately actionable information directly within every function—regardless of scope, complexity, or visibility. This is not an afterthought but a **core engineering principle**: code **MUST** be **self-explanatory** to any consumer, even in the absence of external manuals, IDE tooltips, or prior knowledge. The documentation strategy is **v1.0-native** in compatible scripts, relying exclusively on PowerShell's original comment-based help system (introduced in v1.0) without dependence on newer features like `[CmdletBinding()]`, `Get-Help` enhancements in v2.0+, or external XML help files. In scripts requiring modern PowerShell due to dependencies, the author incorporates these newer help features as appropriate.

Every function—**including nested private helpers**—receives **identical treatment** in documentation rigor. This creates a **uniform information density** across the entire script, enabling rapid onboarding, debugging, and maintenance. The documentation serves three distinct audiences:

1. **End users** (via `Get-Help`)
2. **Script maintainers** (via inline context)
3. **Code reviewers** (via complete behavioral contracts)

### Comment-Based Help: Structure and Format

The help block **MUST** be **placed inside the function**, **immediately above the `param` block**, ensuring:

- **Proximity to implementation** → reduces drift during refactoring
- **Visibility in plain text** → no IDE required
- **Discoverability via `Get-Help`** → works in PowerShell v1.0+

**Detailed section reference:**

| Section | Purpose | Observed Implementation |
| --- | --- | --- |
| `.SYNOPSIS` | One-sentence purpose | Concise, imperative-voice summary |
| `.DESCRIPTION` | Detailed behavior | Explains logic, edge cases, and failure modes |
| `.PARAMETER` (if the function declares parameters in its `param()` block) | Per-parameter documentation | One block per parameter, even for `[ref]` types |
| `.EXAMPLE` | Usage demonstration | **Multiple examples** with input, output, and explanation |
| `.INPUTS` | Pipeline input | Explicitly "None" (correct for non-pipeline design) |
| `.OUTPUTS` | Return value semantics | Document all outputs; include full mapping for integer status codes when used |
| `.NOTES` | Additional context | Positional parameters, versioning, design rationale |

> **Note:** If a function declares no parameters in its `param()` block (excluding implicit common parameters), the `.PARAMETER` section is omitted entirely. Do not include an empty or placeholder `.PARAMETER` block.

#### Why Three or More `#` Characters Are Non-Compliant in `.EXAMPLE` Blocks

In comment-based help, the first `#` on each line serves as the comment-based help prefix — PowerShell strips it when rendering the help content. For explanatory lines that should appear as PowerShell comments in `Get-Help` output, the second `#` becomes the visible comment marker, producing the intended `# <text>` rendering.

When an author mistakenly uses three `#` characters (`# # # <text>`), the first `#` is consumed as the help prefix, leaving `# # <text>` as the rendered content. `Get-Help` then displays `## <text>`, which does not preserve the intended `# <text>` rendered form and introduces an extra visible comment marker that is visually inconsistent with the surrounding example content. This is a subtle authoring error that the single-`#` non-compliant example does not explicitly cover, because the failure mode is different: single `#` produces bare prose (no comment marker at all), whereas triple `#` produces a *double* comment marker that looks like a Markdown heading rather than a PowerShell comment.

All functions **MUST** include **full comment-based help** using **single-line comments** (`#`) with **dotted keywords** placed **inside the function**, **immediately above the `param` block**.

**Required sections**: `.SYNOPSIS`, `.DESCRIPTION`, `.PARAMETER` (one per declared parameter, if any), `.EXAMPLE` (multiple with input, output, and explanation), `.INPUTS`, `.OUTPUTS` (document all outputs; when integer status codes are used, include full mapping of codes to meanings), `.NOTES` (positional parameters, versioning).

> **Note:** If a function declares no parameters in its `param()` block (excluding implicit common parameters), the `.PARAMETER` section is omitted entirely.

**Example of complete help block** (from a generic parsing function):

```powershell
# .SYNOPSIS
# Processes a string input with flexible handling of non-standard formats.
#
# .DESCRIPTION
# Attempts direct processing. On failure, iteratively handles problematic segments...
#
# .PARAMETER ReferenceToResultObject
# Reference to store the resulting object.
#
# .EXAMPLE
# $result = $null; $extras = @('','','','',''); $status = Process-String ([ref]$result) ([ref]$extras) 'input-string'
#
# # $status = 4, $result = processed value, $extras[3] = 'leftover'
#
# .INPUTS
# None. You can't pipe objects to this function.
#
# .OUTPUTS
# [int] Status code: 0=success, 1-5=partial success with extras, -1=failure
#
# .NOTES
# This function/script supports positional parameters:
#
#   Position 0: ReferenceToResultObject
#   Position 1: ReferenceArrayOfExtraStrings
#   Position 2: InputString
#
# Version: 1.0.20250218.0
```

> **Note:** The terse form is acceptable where brevity is preferred, for
> example: `# Supports positional parameters.` followed by
> `# Version: 1.0.20250218.0`. The multi-line format shown above is
> **RECOMMENDED** because it explicitly identifies which parameters are
> positional and at which positions. See
> [Positional Parameter Support](#positional-parameter-support) for full
> guidance.

### Comment-Based Help Spacing

Dense comment-based help blocks are technically valid, but they make section
boundaries harder to scan. A single comment blank line between top-level help
sections preserves the complete inline help contract while giving readers a
reliable visual rhythm for `.SYNOPSIS`, `.DESCRIPTION`, `.PARAMETER`,
`.EXAMPLE`, `.INPUTS`, `.OUTPUTS`, and `.NOTES`.

The rule uses a line containing only `#` instead of a true empty physical line
because the separator remains part of the comment-based help block. This keeps
the source visually separated without implying a break in the help content, and
it preserves predictable `Get-Help` rendering across Windows PowerShell and
PowerShell 7+.

A **comment blank line** is a line inside comment-based help that contains only
the comment marker (`#`), with the same indentation as the surrounding help
block. For function-level help, the comment blank line is indented with the help
block:

```powershell
function Get-Example {
    # .SYNOPSIS
    # Does something.
    #
    # .DESCRIPTION
    # Does something in more detail.
    param ()
}
```

Comment-based help **MUST** use exactly one comment blank line between
top-level help sections. Top-level help sections include `.SYNOPSIS`,
`.DESCRIPTION`, `.PARAMETER`, `.EXAMPLE`, `.INPUTS`, `.OUTPUTS`, and `.NOTES`.
A comment blank line **MUST NOT** appear before the first help keyword.
Consecutive `.PARAMETER` sections **MUST** be separated by exactly one comment
blank line. Consecutive `.EXAMPLE` sections **MUST** be separated by exactly one
comment blank line.

A comment blank line **SHOULD NOT** appear immediately after a dotted help
keyword when the section content begins on the next line. Wrapped lines
belonging to the same paragraph **MUST NOT** be separated by comment blank
lines.

Inside `.EXAMPLE` sections, executable sample code **SHOULD** be separated from
explanatory rendered-comment lines by exactly one comment blank line. The
existing requirement that explanatory or output-description lines use exactly
`# # <text>` remains unchanged:

```powershell
# .EXAMPLE
# $arrResult = @(Get-Example)
#
# # Returns zero or more example objects.
```

Within `.NOTES`, distinct note groups **SHOULD** be separated by exactly one
comment blank line, especially positional parameter documentation, additional
note text, private/internal helper banners, and version metadata:

```powershell
# .NOTES
# This script supports positional parameters:
#
#   Position 0: RootDirectoryPath
#
# Parameters without a listed position must be named.
#
# Version: 1.0.20260517.0
```

### Inline Comments Within `.EXAMPLE` Blocks

When writing explanatory or output-description lines within a `.EXAMPLE` section of comment-based help, use **double `#`** — that is, `# # <text>`. The first `#` is the standard comment-based help line prefix (required for all help content). The second `#` creates a PowerShell comment within the rendered example output so that:

1. `Get-Help -Examples` renders the line as `# <text>`, which is valid PowerShell syntax and can be safely copy-pasted.
2. The explanatory text is visually distinct from executable code lines in the example.

**Compliant** — explanatory lines use `# #`:

```powershell
# .EXAMPLE
# $arrRows = @(ConvertTo-VectorRow -Counts $arrCounts -FeatureIndexObject $objIndex)
#
# # $arrRows[0].PrincipalKey = 'user-abc'
# # $arrRows[0].Vector = [double[]] (fixed-length array)
```

Rendered by `Get-Help`:

```text
$arrRows = @(ConvertTo-VectorRow -Counts $arrCounts -FeatureIndexObject $objIndex)
# $arrRows[0].PrincipalKey = 'user-abc'
# $arrRows[0].Vector = [double[]] (fixed-length array)
```

**Non-compliant** — single `#` for explanation text:

```powershell
# .EXAMPLE
# $arrRows = @(ConvertTo-VectorRow -Counts $arrCounts -FeatureIndexObject $objIndex)
#
# Returns vector row objects with PrincipalKey, Vector, and TotalActions.
```

Rendered by `Get-Help`:

```text
$arrRows = @(ConvertTo-VectorRow -Counts $arrCounts -FeatureIndexObject $objIndex)
Returns vector row objects with PrincipalKey, Vector, and TotalActions.
```

The non-compliant form renders bare prose that (a) is not valid PowerShell, (b) can be confused with actual command output, and (c) is not safely copy-pasteable.

**Non-compliant** — triple `#` for explanation text:

```powershell
# .EXAMPLE
# $arrRows = @(ConvertTo-VectorRow -Counts $arrCounts -FeatureIndexObject $objIndex)
#
# # # Returns vector row objects with PrincipalKey and Vector.
```

Rendered by `Get-Help`:

```text
$arrRows = @(ConvertTo-VectorRow -Counts $arrCounts -FeatureIndexObject $objIndex)
## Returns vector row objects with PrincipalKey and Vector.
```

Lines within `.EXAMPLE` blocks that are intended to render as PowerShell comments in `Get-Help` output **MUST** use exactly two `#` characters (`# # <text>`). Using three or more `#` characters (for example, `# # # <text>`) is non-compliant because it does not preserve the intended rendered form of `# <text>` in `Get-Help` output.

---

### Help Content Quality: High Standards

Comprehensive help also demonstrates **State Transparency**: showing **exact contents** of output variables after execution, so callers know precisely what to expect.

1. **Behavioral Contracts**: Every possible output/return value documented with **exact type and meaning** (in .OUTPUTS) and **example** (in .EXAMPLE blocks); when integer status codes are used, include full mapping of codes to meanings.
2. **Edge Case Coverage**: Examples include valid input, invalid segments, overflow conditions, excess parts.
3. **Positional Parameter Support**: `.NOTES` explicitly documents positional ordering.
4. **Versioning**: Includes internal version in `.NOTES` for change tracking.

---

### Private/Internal Helper Function Documentation

Private/internal helper functions receive the same full comment-based help treatment as public/exported functions. However, without an explicit banner distinguishing them, a reader examining a function file in isolation cannot tell whether it is part of the stable public API or an internal implementation detail. This matters because:

1. **Drift between file presentation and actual API surface.** When a helper's comment-based help looks identical to a public function's help, consumers may treat it as a supported entry point. If the function is later renamed, restructured, or removed during internal refactoring, those consumers encounter unexpected breakage.
2. **Positional contracts differ in stability.** A public function's positional parameter ordering is a stable contract; an internal helper's ordering may be changed freely as the implementation evolves. Explicitly labeling the positional documentation as an internal-caller contract prevents external callers from relying on ordering that was never guaranteed.
3. **Module manifests are not the only scoping mechanism.** While `FunctionsToExport` in a module manifest (`.psd1`) is the primary mechanism in module-based code, the concept of private/internal helpers is broader: standalone scripts, multi-function `.ps1` files, and v1.0-targeted code all have internal helpers that are not governed by a manifest. The banner rule therefore applies at the `[All]` scope.

The banner is deliberately placed at the top of `.NOTES` so it is the first thing a reader encounters after the behavioral documentation sections. It does not reduce documentation quality; it adds a single, high-signal annotation that protects both the author's refactoring freedom and consumers' expectations.

**[All]** If a function is intended only for internal use and is not part of the script, module, or tool's public API surface, its `.NOTES` section **MUST** begin with a clear private-helper banner. That banner **MUST** state that the function is not part of the public API surface, and **MUST** warn that parameters, return shape, and positional contract may change without notice.

**[Modern]** In module-based code, a function intentionally omitted from the module manifest's `FunctionsToExport` is treated as a private/internal helper for purposes of the documentation requirements above.

All other comment-based help requirements (`.SYNOPSIS`, `.DESCRIPTION`, `.PARAMETER`, `.EXAMPLE`, `.INPUTS`, `.OUTPUTS`, `.NOTES`) still apply to private/internal helpers — the banner is an addition, not a replacement.

**Compliant — private/internal helper with required `.NOTES` banner:**

```powershell
function Convert-RawRecord {
    # .SYNOPSIS
    # Transforms a raw input record into a normalized internal format.
    #
    # .DESCRIPTION
    # Parses the raw record hashtable, validates required keys, and
    # returns a normalized [pscustomobject]. This function is used
    # only by Import-DataSet and is not part of the public API.
    #
    # .PARAMETER ReferenceToResultObject
    # Reference to store the resulting normalized object.
    #
    # .PARAMETER RawRecord
    # The raw hashtable to normalize.
    #
    # .EXAMPLE
    # $objResult = $null
    # $intReturnCode = Convert-RawRecord ([ref]$objResult) $hashtableInput
    #
    # # $intReturnCode = 0, $objResult contains the normalized record
    #
    # .INPUTS
    # None. You can't pipe objects to this function.
    #
    # .OUTPUTS
    # [int] Status code: 0 = success, -1 = failure (missing keys)
    #
    # .NOTES
    # PRIVATE/INTERNAL HELPER — This function is not part of the
    # public API surface. Parameters, return shape, and positional
    # contract may change without notice.
    #
    # This function supports positional parameters
    # (internal-caller contract only; subject to change):
    #
    #   Position 0: ReferenceToResultObject
    #   Position 1: RawRecord
    #
    # Version: 1.0.20260415.0
    param (
        [ref]$ReferenceToResultObject,
        [hashtable]$RawRecord
    )

    # Implementation omitted for brevity
}
```

---

### Inline Comments: Purpose and Placement

**Examples**:

```powershell
# Retrieve the newest error on the stack prior to doing work
$refLastKnownError = Get-ReferenceToLastError

# Set ErrorActionPreference to SilentlyContinue; this will suppress error output...
$global:ErrorActionPreference = [System.Management.Automation.ActionPreference]::SilentlyContinue
```

No redundant comments (e.g., `# Increment i by 1`) appear—code is considered self-documenting when possible.

Inline comments **SHOULD** focus on **"why"** rather than **"what"**, be used only when behavior is non-obvious, and be aligned with at least two spaces from code.

---

### Structural Documentation: Regions and Licensing

The structural documentation using `#region` enables:

- **Rapid navigation** in any editor
- **Isolation of concerns** (license, helpers, core logic)
- **Clear understanding** of design intent

The script uses **`#region` / `#endregion`** blocks to create **logical code folding**:

```powershell
#region License ########################################################
# Full MIT-style license
#endregion License ########################################################

#region FunctionsToSupportErrorHandling ############################
# Get-ReferenceToLastError
# Test-ErrorOccurred
#endregion FunctionsToSupportErrorHandling ############################
```

For distributable helper functions, the structure **MUST** be: function declaration, comment-based help, `param()` block, then `#region License` block.

**Example:**

```powershell
function Get-Example {
    # .SYNOPSIS
    # Example function with license
    #
    # .DESCRIPTION
    # This demonstrates the correct placement of param() before license.
    #
    # .NOTES
    # Version: 1.0.20260109.0

    param(
        [string]$Parameter
    )

    #region License ########################################################
    # MIT License or other license text
    #endregion License ########################################################

    # Function implementation
    return 0
}
```

---

### Function and Script Versioning

All distributable functions and scripts **MUST** include a version number in the `.NOTES` section of their comment-based help. This version number provides critical change tracking and **MUST** follow a strict, `[System.Version]`-compatible format: `Major.Minor.Build.Revision`.

For this section, the **previously published version** means the most recent `.NOTES` version published for the same distributable function or script before this change. In repository work, this is the version already on the branch the change lands on, not an in-progress value produced earlier in the same change. For a brand-new function or script, there is no previously published version.

- **`Major`**: Increment the **Major** version (e.g., `1.0.20251103.0` to `2.0.20251230.0`) **any time a breaking change is introduced**. Breaking changes include:
  - Removing or renaming a function, parameter, or public interface
  - Changing parameter types in incompatible ways
  - Altering return types or output formats that break existing consumers
  - Any modification that requires users to update their code
- **`Minor`**: Increment the **Minor** version (e.g., `1.0.20251103.0` to `1.1.20251230.0`) **any time a feature or function change is introduced that is non-breaking**. This includes:
  - Adding new functions or capabilities
  - Adding new optional parameters
  - Enhancing existing functionality without changing interfaces
  - Performance improvements that don't affect behavior
- **`Build`**: This component **MUST** be an integer in the format **`YYYYMMDD`**, representing the date the code was last modified. This date **MUST** be updated to the **current date** for *any* modification, however minor.
- **`Revision`**: This component is typically `0` for the first published version of a given distributable function or script at a given `Major.Minor.Build`. It counts same-day published updates of the same function or script relative to the previously published version, not work-in-progress iterations or commits. When a `.NOTES` version is assigned or updated, after applying the required `Major`, `Minor`, and `Build` values above, `Revision` **MUST** be `0` if the resulting `Major.Minor.Build` differs from the previously published version's `Major.Minor.Build` or if there is no previously published version. If the previously published version already records the same `Major.Minor.Build` at revision `N`, `Revision` **MUST** be `N + 1`. Same-day updates at the same `Major.Minor.Build` that increment `Revision` can include, but are not limited to:
  - Trivial edits, such as typos, formatting, or comment fixes
  - Bug fixes that do not require a `Major` or `Minor` version bump
  - Documentation-only updates

| Case | Previously published version | This change | Reason |
| --- | --- | --- | --- |
| Same-day update | `1.2.20260619.0` | `1.2.20260619.1` | Same `Major.Minor.Build`, so `N + 1`. |
| Same-day breaking change | `1.2.20260619.1` | `2.0.20260619.0` | `Major` changed, so reset to `0`. |
| Next-day update | `1.2.20260619.1` | `1.2.20260620.0` | `Build` date changed, so reset to `0`. |

**Compliant Example:**

```powershell
# .NOTES
# Version: 1.2.20251230.0
```

This example assumes that the current date is December 30, 2025. In any code you write, use the current date in place of December 30, 2025.

### Function and Script Versioning: Revision Counting

The `.NOTES` version is consumed by `[System.Version]` comparison and used as provenance for a distributable function or script. A nondeterministic `Revision` value can make otherwise ordered versions ambiguous or incorrectly ordered, so the reset and increment calculation is a **MUST** rather than a **SHOULD**. RFC 2119 reserves imperatives for interoperation requirements and behavior whose inconsistency can cause harm; ambiguous version ordering is that kind of harm. The requirement is scoped to the calculation performed when a version is assigned or updated. It does not dictate how often a project publishes or versions a function or script.

`Revision` is the lowest-precedence component in the repository's `[System.Version]`-compatible `Major.Minor.Build.Revision` policy. It resets to `0` whenever any higher-order component changes: `Major`, `Minor`, or `Build`. If the previously published version already carries the same `Major.Minor.Build` at revision `N`, the next published same-day update for that same function or script uses `N + 1`. This is repository policy, informed by Semantic Versioning's reset-by-higher-precedence pattern by analogy and applied to the lowest-precedence `System.Version` component.

The **previously published version** is the most recent `.NOTES` version published for that same distributable function or script before the current change. In pull-request workflows, that means the version recorded on the base branch the change merges into. Because the base branch can receive other changes before a pull request merges, evaluate the value when finalizing the change rather than when starting branch work. If automated merge machinery, such as a merge queue, changes the target branch after finalization, treat any resulting provenance drift as follow-up work instead of complicating the author-facing rule. For a brand-new function or script, there is no previously published version, so `Revision` starts at `0`.

---

### Parameter Documentation Placement: Strategic Choice

The rationale for centralizing parameter help in the comment-based help block:

- **Single source of truth** → reduces maintenance drift
- **v1.0 compatibility** → avoids v2.0+ parameter attributes
- **Clarity in examples** → full context in one place

**Alternative considered (but not used)**: Inline comments above each parameter:

```powershell
param (
    # Reference to store the result object
    [ref]$ReferenceToResultObject,
    # Array to store extra strings
    [ref]$ReferenceArrayOfExtraStrings
)
```

- **Pros**: Immediate proximity
- **Cons**: Risk of desync, visual noise

The choice prioritizes **consistency and maintainability**.

Parameter help **SHOULD** be centralized in the comment-based help block, not duplicated above individual parameters in the `param` block.

---

### Help Format Options: Comparison

The author uses **single-line comments** (`# .SECTION`) rather than **block comments** (`<# ... #>`).

| Format | Pros | Cons |
| --- | --- | --- |
| **Single-line (`#`)** | • Granular editing • Clear in diff tools • No escaping issues • Works in **all** PowerShell versions including v1.0 | • More vertical space • Slightly more typing |
| **Block (`<# ... #>`)** | • Compact • Modern aesthetic | • **Not supported in PowerShell v1.0** (causes parser error) • Harder to edit individual lines • Risk of malformed blocks |

**Finding**: Only **single-line comments** (`#`) are compatible with PowerShell v1.0. Block comments (`<# ... #>`) are valid in PowerShell v2.0+ and are discoverable by `Get-Help` in those versions, but they **MUST NOT** be used when v1.0 compatibility is required. The single-line format is **required** for the v1.0 compatibility goal.

Comment-based help **MUST** use single-line comments (`#`) for v1.0-compatible code. Block comments (`<# ... #>`) **MUST NOT** be used when v1.0 compatibility is required.

> **⚠ PowerShell v1.0 Compatibility Warning:** Block comments (`<# ... #>`) were introduced in PowerShell v2.0. In PowerShell v1.0, attempting to use block comments results in a **parser error** that prevents the script from running. Scripts targeting v1.0 compatibility **MUST** use only single-line comments (`#`). This applies to both comment-based help and general-purpose comments.

**Example — what fails in PowerShell v1.0:**

```powershell
# This will cause a parser error in PowerShell v1.0:
function Get-Example {
    <#
    .SYNOPSIS
        Example function.
    #>
    param ()
}
```

**Correct approach for v1.0 compatibility:**

```powershell
# This works in all PowerShell versions, including v1.0:
function Get-Example {
    # .SYNOPSIS
    #     Example function.
    param ()
}
```

---

### Summary: Documentation as Complete Specification

The documentation system is **comprehensive and complete**:

- **Zero ambiguity** in function contracts
- **Full behavioral coverage** including failure modes
- **Immediate usability** via `Get-Help` in any PowerShell v1.0+ host
- **Self-contained** — no external help files required
- **Future-proof** — versioned, example-rich, and example-driven

This is not merely "good documentation"—it is **executable specification**. A developer could **delete the implementation** and **reconstruct correct behavior solely from the help blocks and examples**.

The author has elevated documentation from a **maintenance task** to a **core reliability mechanism**, ensuring the code remains understandable, debuggable, and maintainable across decades and environments.

## Functions and Parameter Blocks

### Overview of Function Architecture

Functions **MUST** be designed as **atomic, reusable tools** with a single, well-defined purpose. Every function **MUST** be a **self-contained unit of execution** that accepts input, performs a transformation or validation, and produces a **predictable, deterministic output**. This design philosophy is rooted in **PowerShell v1.0 constraints** for compatible scripts and deliberately avoids any feature introduced in v2.0 or later in those cases. The result is a **robust, portable, and highly maintainable** codebase that operates identically across all PowerShell versions from 1.0 onward when feasible. However, in scripts with external dependencies requiring newer versions (e.g., modern modules), the author incorporates appropriate features like pipeline processing or structured error handling.

The characteristic pattern of this architecture in v1.0-targeted scripts is the **complete absence** of:

- `[CmdletBinding()]` and `[OutputType()]` attributes
- `begin`, `process`, or `end` blocks
- Common parameters (`-Verbose`, `-Debug`, `-WhatIf`, etc.)
- Pipeline-aware processing
- Structured error handling (`try/catch`)

Instead, the author relies on **v1.0-native constructs**:

- Simple `function` keyword
- Formal `param()` blocks
- Strong typing
- Explicit `return` statements
- Reference parameters (`[ref]`) for outputs that need to modify caller variables

This creates a **C-style procedural model** within PowerShell, prioritizing **control flow predictability** over pipeline composability.

### Function Declaration and Structure

All functions **MUST** follow a **strict, uniform template**:

```powershell
function Verb-Noun {
    # Full comment-based help block
    param (
        [type]$ParameterName1,
        [type]$ParameterName2 = default
    )
    # Implementation
    return $statusCode
}
```

**Key characteristics**:

1. **No `[CmdletBinding()]`** → intentional omission for v1.0 compatibility; v1.0-targeted functions **MUST NOT** use this
2. **No pipeline blocks** → `process` block would imply pipeline input, which **MUST NOT** be supported in v1.0-targeted functions
3. **Explicit `return`** → **MUST** be used to guarantee single-value output and prevent accidental pipeline leakage
4. **Strongly typed `param` block** → **MUST** validate input at parse time
5. `[CmdletBinding()]` and `[OutputType()]` Present → **MUST** be included for modern, non-v1.0 functions where either the function or script it sits in relies on external dependencies (e.g., a module that only supports Windows PowerShell v5.1 or PowerShell 7.x), making the function explicitly non-v1.0-compatible.

---

### Parameter Block Design: Detailed Analysis

The `param` block is the **primary contract** between caller and function. Every parameter **MUST** be:

- **Strongly typed** using .NET types
- **Fully documented** in comment-based help
- **Defaulted where appropriate** to ensure predictable behavior

**Exception for Polymorphic Parameters:**

In rare cases, a function **MAY** be intentionally designed to accept a parameter that can be one of several different, incompatible types (e.g., a string *or* an object). This is common in "safe wrapper" functions that process dynamic input, such as the `Principal` element from an IAM policy.

In this scenario, the parameter **SHOULD** be left **un-typed** (or explicitly typed as `[object]`). The function's internal logic is then responsible for inspecting the received object's type (e.g., using `if ($MyParameter -is [string])`) and handling it appropriately. This pattern **SHOULD** be used sparingly and only when required by the function's core purpose.

**Parameter typing examples**:

| Parameter | Type | Purpose |
| --- | --- | --- |
| `$ReferenceToResultObject` | `[ref]` | Output: stores processed result (used only when modification in caller scope is needed) |
| `$ReferenceArrayOfExtraStrings` | `[ref]` | Output: array for additional data (used only for write-back) |
| `$StringToProcess` | `[string]` | Input: string to handle |
| `$PSVersion` | `[version]` | Optional: runtime version for optimization |

**Reference parameters (`[ref]`)** are used **exclusively for output** where data **MUST** be written back to the caller's scope—a deliberate pattern to:

- Return multiple complex values
- Avoid pipeline interference
- Maintain v1.0 compatibility
- Ensure caller controls variable lifetime

[ref] **SHOULD NOT** be used for passing complex objects that do not require modification, as PowerShell passes object references by default without performance gains from [ref] in such cases.

**Default values** are used judiciously:

```powershell
[string]$StringToProcess = '',
[version]$PSVersion = ([version]'0.0')
```

This ensures the function can be called with minimal arguments while maintaining type safety.

---

### Return Semantics: Explicit Status Codes

**Rationale for explicit `return`**:

1. **Determinism** — only the status code is returned
2. **No pipeline pollution** — prevents accidental object emission
3. **v1.0 compatibility** — `return` works identically in all versions
4. **Caller control** — status code can be stored, tested, or ignored

```powershell
$status = Process-String ([ref]$result) ([ref]$extras) $input
if ($status -eq 0) { ... }  # Full success
```

This pattern creates a **C-style error code contract** that is immediately familiar to systems programmers.

Every v1.0-targeted function **MUST** return a **single integer status code** via explicit `return` statement:

| Code | Meaning |
| --- | --- |
| `0` | Full success |
| `1–5` | Partial success with additional data |
| `-1` | Complete failure |

**Exception for `Test-*` Functions:**

For PowerShell v1.0 scripts/functions that use the `Test-` verb (in a Verb-Noun naming convention) and are **not reasonably anticipated to encounter errors that the caller needs to detect and react to programmatically**, a **Boolean return** **MAY** be used instead of an integer status code.

This exception applies when:

1. The function's verb is `Test-`
2. The function is designed to return a simple true/false result (e.g., testing for the existence of a condition)
3. There is no practical need for the caller to distinguish between different error conditions or partial success states

**Example of Compliant Test Function with Boolean Return:**

```powershell
function Test-PathExists {
    # .SYNOPSIS
    # Tests whether a path exists.
    #
    # .DESCRIPTION
    # Returns $true if the path exists, $false otherwise.
    #
    # .PARAMETER Path
    # The path to test.
    #
    # .EXAMPLE
    # $boolPathExists = Test-PathExists -Path 'C:\Temp'
    #
    # # $boolPathExists is $true when the path exists.
    #
    # .INPUTS
    # None. You can't pipe objects to this function.
    #
    # .OUTPUTS
    # [bool] $true if the path exists, $false otherwise.
    #
    # .NOTES
    # This function supports positional parameters:
    #
    #   Position 0: Path
    #
    # Version: 1.0.20260517.0
    param (
        [string]$Path
    )

    return (Test-Path -LiteralPath $Path)
}
```

For `Test-*` functions that might encounter meaningful errors (e.g., access denied, network issues) that the caller **SHOULD** be able to detect, the standard integer status code pattern **SHOULD** still be used.

---

### Input/Output Contract: Reference Parameters

**Advantages**:

- **No pipeline interference** — data never accidentally flows downstream
- **Caller-controlled lifetime** — variables persist after function exit
- **Multiple return values** — result + additional data in one call
- **v1.0 compatible** — `[ref]` works in all versions

**Post-call state example**:

```powershell
$result = processed value
$extras = @('','', '', 'extra', '')
$status   = 4
```

Functions **MUST** use **`[ref]` parameters** to return complex data only when write-back is required:

```powershell
[ref]$ReferenceToResultObject     → [object]
[ref]$ReferenceArrayOfExtraStrings → [string[]]
```

[ref] **SHOULD NOT** be used for passing complex objects that do not require modification, as PowerShell passes object references by default.

---

### Pipeline Behavior: Deliberately Disabled

In v1.0-targeted functions, pipeline input is deliberately disabled. This is **not a limitation** but a **design requirement** for:

- **Deterministic ordering** — processes one input at a time
- **Stateful operations** — requires full control over input sequence
- **v1.0 compatibility** — pipeline binding attributes require v2.0+

In v1.0-targeted functions, pipeline input **MUST** be **explicitly rejected**:

- No `ValueFromPipeline` attributes
- `.INPUTS` section states "None"
- No `process` block

In scripts requiring modern PowerShell, pipeline support is added as needed.

---

### Positional Parameter Support

Functions **SHOULD** support **positional parameter binding** for v1.0 usability:

```powershell
# Named parameters
Process-String ([ref]$r) ([ref]$e) $str

# Positional parameters (documented in .NOTES)
Process-String ([ref]$r) ([ref]$e) $str $psver
```

**Important distinction:** While functions **SHOULD** support positional parameters in their declarations (for flexibility and v1.0 usability), function **calls** throughout the codebase **SHOULD** use named parameters for clarity and maintainability. The PSScriptAnalyzer configuration enforces this via the `PSAvoidUsingPositionalParameters` rule.

This enables:

- **Interactive use** without naming
- **Script compatibility** with older calling patterns
- **Flexibility** without sacrificing type safety

#### Documenting Positional Parameters in `.NOTES`

When a function or script supports positional parameters, the `.NOTES` section **SHOULD** use the following multi-line format to document which parameters are positional and at which positions:

```powershell
# .NOTES
# This function/script supports positional parameters:
#
#   Position 0: VectorRows
#   Position 1: KMeansResult
#
# Version: 1.0.20250218.0
```

Guidance for this format:

1. The header line **SHOULD** be `# This function/script supports positional parameters:` followed by each position listed on its own indented line as `#   Position N: ParameterName`.
2. Only list parameters that are expected to be used positionally. For functions or scripts with many optional parameters, listing only the mandatory or commonly-used positional parameters is acceptable.
3. The parameter name **SHOULD** match the declared parameter name without the `-` prefix (e.g., `VectorRows`, not `-VectorRows`), since the `.NOTES` section documents the parameter's identity, not its call syntax.
4. **[All]** If positional parameter behavior is documented for a private/internal helper, that documentation **SHOULD** clearly state that it is an internal-caller contract only and is subject to change. For example, the header line **SHOULD** read `# This function supports positional parameters` / `# (internal-caller contract only; subject to change):` instead of the standard header.

#### [Modern] Enforcing a Subset-Only Positional Contract

**[Modern]** When a `[CmdletBinding()]` function or script documents only a **subset** of its parameters as positional, it **MUST** use `[CmdletBinding(PositionalBinding = $false)]` and **MUST** apply explicit `[Parameter(Position = N)]` attributes only to the parameters intended to be positional. This rule does not apply to v1.0-targeted functions, which cannot use `[CmdletBinding()]`.

**Compliant — subset-only positional contract enforced:**

```powershell
function Import-DataSet {
    [CmdletBinding(PositionalBinding = $false)]
    [OutputType([pscustomobject])]
    param (
        [Parameter(Mandatory = $true, Position = 0)]
        [string]$InputMode,

        [Parameter(Mandatory = $true, Position = 1)]
        [string]$OutputPath,

        [Parameter()]
        [switch]$Force,

        [Parameter()]
        [int]$RetryCount
    )

    # Only InputMode and OutputPath are positional;
    # Force and RetryCount must always be named.
    # ...
}
```

**Non-compliant — default PositionalBinding contradicts documented subset contract:**

```powershell
# BAD: Documentation claims only InputMode and OutputPath are positional,
# but CmdletBinding() defaults to PositionalBinding = $true, which silently
# makes Force and RetryCount positional as well.
function Import-DataSet {
    [CmdletBinding()]
    [OutputType([pscustomobject])]
    param (
        [Parameter(Mandatory = $true)]
        [string]$InputMode,

        [Parameter(Mandatory = $true)]
        [string]$OutputPath,

        [Parameter()]
        [switch]$Force,

        [Parameter()]
        [int]$RetryCount
    )

    # .NOTES claims "Position 0: InputMode, Position 1: OutputPath"
    # but all parameters accept positional input — mismatch.
    # ...
}
```

---

### Advanced Feature Emulation (v1.0-Native)

In v1.0 scripts, the author **emulates modern features** using v1.0 constructs:

| Modern Feature | v1.0 Emulation |
| --- | --- |
| `[CmdletBinding()]` | Comment-based help + strong typing |
| `-WhatIf` support | Not applicable (no state change) |
| `SupportsShouldProcess` | N/A |
| `[OutputType()]` | Documented in `.OUTPUTS` |
| Parameter validation | Strong typing + manual checks |

### Options for Return Mechanism: Comparison

The use of explicit `return` vs. implicit output represents a **philosophical choice**:

| Approach | Pros | Cons |
| --- | --- | --- |
| **Explicit `return` (current)** | • Full control • No accidental output • v1.0 compatible • Clear contract | • Not pipeline-friendly • Verbose |
| **Implicit output (modern)** | • Pipeline composable • Concise | • Risk of extra objects • Requires v2.0+ for safety |

**Conclusion**: The explicit `return` pattern is **correct and optimal** for v1.0-targeted, non-pipeline tools.

### Rule: "Modern Advanced" Function/Script Requirements (v2.0+)

The "v1.0 Classicist" style is the default for standalone, portable utilities that **MUST** maintain backward compatibility.

However, if a script or function **cannot** target v1.0, it **MUST** be written in the "Modern Advanced" style. This condition is met if the code:

1. Has external module dependencies that require a modern PowerShell version (e.g., `AWS.Tools`, `Az`, `Microsoft.Graph`).
2. Intentionally uses features from PowerShell v2.0 or later (e.g., `try/catch`, `[pscustomobject]` literals, `Add-Type -AssemblyName`), and there are no reasonable alternative approaches that can be used to ensure support for PowerShell v1.0.

Functions and scripts written in this "Modern Advanced" style **MUST** adhere to the following rules:

1. **Must Use `[CmdletBinding()]`:** All modern functions and scripts **MUST** use the `[CmdletBinding()]` attribute. This is the non-negotiable identifier of an advanced function or script and enables support for common parameters (`-Verbose`, `-Debug`, `-ErrorAction`, etc.). For modern scripts (`.ps1` files that are not functions), `[CmdletBinding()]` and the `param` block **MUST** appear as the first statement in the script, other than permitted `using` statements, comments, and blank lines. Placing other statements before `[CmdletBinding()]` / `param` causes a `ParseException` when the script is invoked via the call operator (`& $path`).
2. **Must Use `[OutputType()]`:** All modern functions and scripts **MUST** declare their primary output object type using `[OutputType()]`. This is critical for discoverability, integration, and validating the function's or script's contract.
3. **Must Use Streaming Output:** Functions and scripts that return collections **MUST** write objects directly to the pipeline (stream) from within a loop. They **MUST NOT** collect results in a `List<T>` or array to be returned at the end. (See *Processing Collections in Modern Functions*).
4. **Must Use `try/catch`:** Error handling **MUST** use `try/catch` blocks. The v1.0 `trap` / preference-toggling pattern is **prohibited** in this style.
5. **Must Use Proper Streams:** Verbose and debug messages **MUST** be written to their respective streams (`Write-Verbose`, `Write-Debug`). Manual toggling of `$VerbosePreference` is **prohibited**.

**Example of a Compliant Modern Function:**

```powershell
function Get-ModernData {
    [CmdletBinding()]
    [OutputType([pscustomobject])]
    param (
        [Parameter(Mandatory = $true)]
        [string]$InputPath
    )

    process {
        Write-Verbose "Processing file: $InputPath"

        try {
            $data = Get-Content -LiteralPath $InputPath -ErrorAction Stop
            foreach ($line in $data) {
                # This is streaming output.
                [pscustomobject]@{
                    Length = $line.Length
                    Line = $line
                }
            }
        } catch {
            Write-Error -Message "Failed to process $InputPath: $($_.Exception.Message)"
        }
    }
}
```

**Benefits**: Pipeline-friendly, discoverable

**Trade-off**: Breaks v1.0 compatibility

#### "Modern Advanced" Functions/Scripts: Exception for Suppressing Nested Verbose Streams

Rule 5 states that manual toggling of `$VerbosePreference` is prohibited. This rule's primary intent is to ensure your function or script *respects* the user's desire for verbose output from *your* script (via `Write-Verbose`).

An exception to this rule **MAY** be made when you **MUST** *surgically suppress* the verbose stream from a "chatty" or "noisy" nested command (a command you call within your function or script). This pattern allows your function or script to remain verbose while silencing the underlying tool.

In this specific scenario, you **MUST** use the following pattern to temporarily set `$VerbosePreference` and guarantee it is restored, even if the command fails:

```powershell
# Save the user's current preference
$VerbosePreferenceAtStartOfBlock = $VerbosePreference

try {
    # Temporarily silence the verbose stream for the nested command
    $VerbosePreference = [System.Management.Automation.ActionPreference]::SilentlyContinue

    # Call the noisy command.
    $result = Get-NoisyCommand -Parameter $foo -ErrorAction Stop

    # Restore the preference *immediately* after the call
    $VerbosePreference = $VerbosePreferenceAtStartOfBlock

    # All logic that depends on $result's success MUST
    # also be inside the 'try' block.
    Write-Verbose "Successfully processed result from noisy command."
    # ... (other code that uses $result) ...
} catch {
    # If Get-NoisyCommand fails, this block will run and
    # the dependent logic above will be skipped.
    # Re-throw the error so the caller knows what happened.
    throw
} finally {
    # This 'finally' block ensures the preference is restored,
    # even if the 'catch' block runs and throws an error.
    $VerbosePreference = $VerbosePreferenceAtStartOfBlock
}
```

This `try/finally` pattern is robust, safe, and compliantly achieves your goal of controlling output from third-party cmdlets.

#### "Modern Advanced" Functions/Scripts: Singular `[OutputType()]`

When a function returns one or more objects via the pipeline (streaming), the `[OutputType()]` attribute **MUST** declare the *singular* type of object in the stream (e.g., `[OutputType([pscustomobject])]`). Code **MUST NOT** use the plural array type (e.g., `[OutputType([pscustomobject[]])]`). The pipeline *always* creates an array for the caller automatically if multiple objects are returned.

#### "Modern Advanced" Functions/Scripts: Handling Multiple or Dynamic Output Types

When a function is *intentionally* designed to return different, non-related object types (e.g., a wrapper for `ConvertFrom-Json` which can return a single object, an array, or a scalar type), it is preferred to **list all primary output types** using multiple `[OutputType()]` attributes. This is far more descriptive and helpful to the caller than using a single, generic `[OutputType([System.Object])]`.

If a function's output type is truly dynamic and unpredictable, `[OutputType([System.Object])]` **SHOULD** be used only as a last resort, as it provides minimal value for discoverability.

#### "Modern Advanced" Functions/Scripts: Prioritizing Primary Output Types

When using multiple `[OutputType()]` attributes, the goal is to list the **primary, high-level** object types a user can expect. It is **not** necessary to create an exhaustive list of every possible scalar or primitive type (e.g., `[int]`, `[bool]`, `[double]`) if they are not the main, intended output of the function.

This practice avoids cluttering the function's definition and keeps the developer's focus on the most common and important return values. For example, a JSON parsing function **SHOULD** list `[pscustomobject]` and `[object[]]`, but does not need to list `[int]`.

#### "Modern Advanced" Functions/Scripts: Parameter Validation and Attributes (`[Parameter()]`)

Using `[CmdletBinding()]` unlocks powerful parameter validation attributes like `[Parameter(Mandatory = $true)]`, `[ValidateNotNullOrEmpty()]`, and `[ValidateSet()]`.

These are **not stylistic requirements**; they are **design tools** that **MUST** be used deliberately to enforce a function's operational contract.

- **Use `[Parameter(Mandatory = $true)]` when:**
  - The function **cannot possibly perform its core purpose** without this value (e.g., `$Identity` for a `Get-User` function).
  - You want the PowerShell engine to **fail fast** and prompt the user if it's missing.

- **DO NOT Use `[Parameter(Mandatory = $true)]` when:**
  - The function is a "safe" wrapper or helper designed to handle any input, including `$null`.
  - The function has a clear, graceful default behavior when the parameter is omitted (e.g., returning `$null`, an empty array, or `$false`).
  - **Example:** The `Convert-JsonFromPossiblyUrlEncodedString` function is a "safe" wrapper. Its contract is to *try* to convert a string. A `$null` string is a valid input that **SHOULD** gracefully return `$null`, not throw a script-terminating error. Making `$InputString` mandatory would violate this "safe" contract.

- **Prefer `[ValidateNotNullOrEmpty()]` over `[Parameter(Mandatory = $true)]` when:**
  - The parameter is *technically* optional, but if it *is* provided, it **MUST NOT** be an empty string.
  - This is common for optional parameters like `$LogPath` or `$Description`.

- **Also use `[ValidateNotNullOrEmpty()]` on mandatory `[string]` parameters when:**
  - The function's logic depends on the parameter having a non-empty value (e.g., computing a hash, constructing a path, or performing a lookup).
  - PowerShell coerces `$null` to `[string]::Empty` for `[string]`-typed parameters. Because `[string]::Empty` is not `$null`, a mandatory `[string]` parameter satisfied by this coercion will pass the mandatory check but silently bind an empty string. This can cause incorrect behavior—for example, hashing an empty string instead of rejecting invalid input.
  - Adding `[ValidateNotNullOrEmpty()]` alongside `[Parameter(Mandatory = $true)]` catches this edge case at parameter-binding time and produces a clear error message.
  - This guidance applies to functions and scripts targeting Windows PowerShell 2.0 or newer, because `[ValidateNotNullOrEmpty()]` is not available in Windows PowerShell v1.0.

- **Use `[ValidateRange(min, max)]` on numeric parameters when:**
  - The parameter has a constrained valid domain, such as counts, delays or timeouts, thresholds, or percentages.
  - Fail-fast parameter binding provides a clearer error than allowing an invalid value to surface later in downstream logic.
  - When the domain is naturally bounded on both sides, prefer explicit bounds (for example `0, 100` for percentages). When only a lower bound is principled, a type maximum such as `[int]::MaxValue` or `[double]::MaxValue` **SHOULD** be used as the upper bound to preserve the fail-fast benefit for the lower bound without imposing an artificial ceiling.
  - This attribute is available in Windows PowerShell 2.0 and newer.

### Consuming Streaming Functions (The `0-1-Many` Problem)

When a function or script streams its output (whether it's a "modern advanced" function/script as mandated by the "Processing Collections" rule, or whether it's a standard, v1.0-compatible function and just happens to be streaming its output), the caller's variable will be `$null` if zero objects are returned, a *scalar object* if one object is returned, or an `[object[]]` array if multiple objects are returned.

This can cause errors in subsequent code that *always* expects an array (e.g., `foreach ($item in $result)` or `$result.Count`).

To ensure the result is **always** an array (even if empty or with a single item), the caller **SHOULD** wrap the function call in the **array subexpression operator `@(...)`**. This is the standard, robust way to consume a streaming function and **SHOULD** be the default way to demonstrate usage in `.EXAMPLE` blocks.

**Compliant `.EXAMPLE`:**

```powershell
# .EXAMPLE
# $arrPrincipals = @(Expand-TrustPrincipal -PrincipalNode $statement.Principal)
#
# # This example shows how to safely call the function and guarantee the
# # result is an array, even if only one principal is returned.
```

---

### Summary: Function Design as Reliability Engineering

The function and parameter block design represents **reliability engineering at the architectural level**:

- **Atomic operations** with clear contracts
- **Strong typing** for fail-early validation
- **Explicit returns** for deterministic output
- **Reference parameters** for complex state only when write-back is needed
- **Positional support** for usability
- **Pipeline avoidance** for control in v1.0 cases

This creates **industrial-grade script components** that can be:

- Dropped into any PowerShell v1.0+ environment when compatible
- Understood without documentation (though documentation is provided)
- Maintained decades later
- Integrated into larger systems with confidence

The absence of modern features in v1.0 scripts is not a limitation—it is **evidence of mastery** over the v1.0 platform and a deliberate choice for **maximum reliability**.

## Error Handling

### Executive Summary: Error Handling Philosophy

The author implements a **complete, v1.0-native error handling system** in compatible scripts that is **fail-controlled, deterministic, and self-diagnosing**. This is not a workaround for missing `try/catch` (introduced in v2.0) but a **deliberately engineered reliability layer** that:

1. **Suppresses terminating and non-terminating errors** to prevent script abortion
2. **Detects error occurrence** with 100% accuracy using reference-based comparison
3. **Preserves error context** for downstream analysis
4. **Restores original state** after error-prone operations
5. **Communicates anomalies** via the Warning stream when logic reaches "impossible" states

The system is **atomic**—each error-prone operation is isolated, measured, and reported independently. This creates a **diagnostic breadcrumb trail** that enables root cause analysis even in production environments where verbose output is disabled. In scripts requiring modern PowerShell (e.g., due to module dependencies), the author switches to try/catch and other structured mechanisms for improved readability and functionality.

### Core Error Suppression Mechanism

v1.0-targeted functions **MUST** use **two complementary v1.0-native suppression techniques**:

| Technique | Implementation | Purpose |
| --- | --- | --- |
| **`trap { }`** | Empty trap block at function scope | Catches **terminating errors** (e.g., type cast failures) and prevents script termination |
| **`$global:ErrorActionPreference = 'SilentlyContinue'`** | Temporarily set before risky operation, restored immediately after | Suppresses **non-terminating error output** to host |

```powershell
trap { }  # Intentional error suppression
$originalPref = $global:ErrorActionPreference
$global:ErrorActionPreference = [System.Management.Automation.ActionPreference]::SilentlyContinue
# Risky operation here
$global:ErrorActionPreference = $originalPref  # State restoration
```

**Key characteristics**:

- **No error leakage** to host → script continues
- **State preservation** → original preference restored
- **v1.0 compatibility** → works in all PowerShell versions

---

### Error Detection: Reference-Based Comparison

The author **rejects unreliable heuristics** (`$?`, `$Error[0].Exception`, null checks) and implements a **reference-equality detection system** using two custom helper functions:

1. **`Get-ReferenceToLastError`:** Returns `[ref]$Error[0]` if errors exist, `[ref]$null` otherwise
2. **`Test-ErrorOccurred`:** Compares two `[ref]` objects to determine if a **new error** appeared

**Detection workflow**:

```powershell
$refBefore = Get-ReferenceToLastError    # Snapshot pre-operation
# ... perform risky operation ...
$refAfter = Get-ReferenceToLastError     # Snapshot post-operation
$errorOccurred = Test-ErrorOccurred $refBefore $refAfter
```

**Reference comparison logic**:

| Before \ After | `$null` | Not `$null` (same) | Not `$null` (different) |
| --- | --- | --- | --- |
| `$null` | No | **YES** | N/A |
| Not `$null` | No | No | **YES** |

This eliminates false positives from `$error` array clearing and ensures **100% accurate error detection**.

---

### Atomic Error Handling Pattern

Every type conversion or risky operation **MUST** follow this **exact atomic pattern**:

```powershell
function Convert-Safely {
    param([ref]$refOutput, [string]$input)

    trap { }  # Suppress termination
    $refBefore = Get-ReferenceToLastError
    $originalPref = $global:ErrorActionPreference
    $global:ErrorActionPreference = 'SilentlyContinue'

    $refOutput.Value = [type]$input  # Risky cast

    $global:ErrorActionPreference = $originalPref
    $refAfter = Get-ReferenceToLastError

    return (-not (Test-ErrorOccurred $refBefore $refAfter))
}
```

**Key guarantees**:

- Operation is **isolated** — error cannot affect caller
- **State is restored** — preference reset
- **Result is boolean** — `$true` = success, `$false` = failure
- **No side effects** — even on failure

---

### Anomaly Reporting: Write-Warning for Logical Impossibilities

**Purpose** of `Write-Warning` for anomaly reporting:

- **Diagnostic beacon** for developers
- **Production-safe** — does not terminate execution
- **Actionable** — includes exact context (variable values, expected vs. actual)

These warnings represent **contract violations** in the parsing logic and serve as diagnostic information for root cause analysis.

`Write-Warning` **MUST** be used **sparingly** to flag **logically impossible states** (contract violations). Code **MUST NOT** suppress these warnings.

```powershell
Write-Warning -Message 'Conversion failed even though individual parts succeeded. This should not be possible!'
```

---

### Error Context Preservation

Despite suppression, **full error context is preserved** in the global `$Error` array:

- Original `ErrorRecord` objects remain intact
- Stack trace, exception details, and target object are available
- Can be inspected after execution for detailed analysis

```powershell
if ($errorOccurred) {
    # Full error details available in $Error[0]
    $lastError = $Error[0]
}
```

Despite suppression, **full error context is preserved** in the global `$Error` array (original `ErrorRecord` objects remain intact with stack trace and exception details).

---

### Comparison with Modern Alternatives

| Feature | v1.0 Implementation | v2.0+ Equivalent |
| --- | --- | --- |
| Error suppression | `trap { }` + preference toggle | `try/catch` with `-ErrorAction Stop` |
| Error detection | Reference comparison | `catch` block execution |
| State management | Manual preference restore | Automatic scope exit |
| Anomaly reporting | `Write-Warning` | `Write-Warning` (same) |

The v1.0 pattern is **functionally equivalent** but **more verbose** and **duplicate-prone**.

### Modern `catch` Block Requirements

In modern functions using `try/catch` (i.e., those not targeting v1.0), `catch` blocks **MUST NOT** be empty. An empty `catch` block is flagged by PSScriptAnalyzer and provides no diagnostic value.

#### Architectural Context: Library/Helper Functions vs. Higher-Level Code

The return-code and error-swallowing patterns described in the preceding v1.0 sections are primarily associated with **library/helper functions** — highly reusable building blocks that handle operational errors internally and communicate failure through an explicitly documented contract (e.g., integer return codes, reference outputs). These functions are designed to **never throw**, and their non-throwing behavior **MUST** be documented in `.DESCRIPTION` and `.OUTPUTS`. While v1.0 compatibility is a common consequence of this design goal, the non-throwing contract itself is the primary architectural motivation; a modern function can adopt the same pattern when the design requires it.

For **modern higher-level functions and scripts** — code that orchestrates these building blocks or performs tasks for end users — the default expectation is that unexpected failures **propagate** to the caller.

#### Default Pattern: `Write-Debug` + `throw`

The standard `catch` pattern for modern advanced functions and scripts **SHOULD** log the error to the **Debug** stream and then **re-throw** it so that unexpected failures propagate to the caller. This **SHOULD** be the default unless the function is explicitly designed as a non-throwing wrapper with a documented contract.

```powershell
# Default: log and re-throw
try {
    ...
} catch {
    Write-Debug ("Failed to do X: {0}" -f $_)
    throw
}
```

#### Rethrow Anti-Pattern

When a `catch` block is intended to rethrow, `throw "message"` and `throw ("format string" -f $args)` **MUST NOT** be used. These forms throw a string that PowerShell wraps into a **new** `RuntimeException`/`ErrorRecord`, discarding the original exception type, stack trace, and `ErrorRecord`. This makes root-cause analysis significantly harder and breaks any caller logic that catches specific exception types. This prohibition applies only to catch blocks whose intent is to preserve and propagate the original failure; catch blocks that intentionally translate an error into a new, independently documented message (such as the [file writeability tests](#file-writeability-testing)) are not subject to this rule.

```powershell
# WRONG — destroys the original exception:
try {
    Get-Item -LiteralPath $strPath -ErrorAction Stop
} catch {
    throw "Failed to get item: $($_.Exception.Message)"
}

# WRONG — same problem with -f operator:
try {
    Get-Item -LiteralPath $strPath -ErrorAction Stop
} catch {
    throw ("Failed to get item: {0}" -f $_.Exception.Message)
}
```

#### Adding Context Before Rethrowing

If contextual information is needed before rethrowing, it **SHOULD** be logged via `Write-Debug` before the bare `throw`. This preserves the original exception while still providing diagnostic context on the Debug stream, reinforcing the [Default Pattern](#default-pattern-write-debug--throw).

```powershell
# Correct — context logged, original exception preserved:
try {
    Get-Item -LiteralPath $strPath -ErrorAction Stop
} catch {
    Write-Debug ("Failed to get item at path '{0}': {1}" -f $strPath, $_)
    throw
}
```

#### Wrapping Exceptions with `$PSCmdlet.ThrowTerminatingError()`

If an exception **must** be wrapped with additional context while still propagating, the preferred pattern for advanced functions **SHOULD** use `$PSCmdlet.ThrowTerminatingError()` and preserve the original exception as the `InnerException`. This approach maintains the full exception chain for callers while adding meaningful context.

```powershell
# Correct — wraps with context, preserves original as InnerException:
function Get-ResolvedItem {
    [CmdletBinding()]
    param (
        [string]$Path
    )

    try {
        Get-Item -LiteralPath $Path -ErrorAction Stop
    } catch {
        $objException = [System.InvalidOperationException]::new(
            ("Failed to resolve item at path '{0}'" -f $Path),
            $_.Exception
        )
        $objErrorRecord = [System.Management.Automation.ErrorRecord]::new(
            $objException,
            'ResolvedItemFailure',
            [System.Management.Automation.ErrorCategory]::ObjectNotFound,
            $Path
        )
        $PSCmdlet.ThrowTerminatingError($objErrorRecord)
    }
}
```

> **Note:** The above wrapping pattern is appropriate only when additional context is genuinely needed beyond what `Write-Debug` + bare `throw` provides. In most cases, the [Default Pattern](#default-pattern-write-debug--throw) is sufficient.

#### Documented Non-Throwing Exception

A modern function **MAY** intentionally handle an exception without re-throwing **only** when its contract explicitly specifies non-throwing behavior. In that case, the function's comment-based help (`.DESCRIPTION` and `.OUTPUTS`) **MUST** clearly document that failures are communicated through return values, output state, warnings, or another defined mechanism rather than by throwing.

```powershell
# Non-throwing wrapper with documented contract
function Convert-SafelyFromJson {
    # .SYNOPSIS
    # Converts a JSON string to an object without throwing on invalid input.
    #
    # .DESCRIPTION
    # Attempts to convert a JSON string to an object. This function does
    # NOT throw on invalid input; instead it returns $null and logs the
    # error to the Debug stream. Callers MUST check the return value.
    #
    # .PARAMETER JsonString
    # JSON string to convert.
    #
    # .EXAMPLE
    # $objResult = Convert-SafelyFromJson -JsonString '{"name":"example"}'
    #
    # # $objResult is a converted object on success, or $null on failure.
    #
    # .INPUTS
    # None. You can't pipe objects to this function.
    #
    # .OUTPUTS
    # [object] on success; $null on failure.
    #
    # .NOTES
    # This function supports positional parameters:
    #
    #   Position 0: JsonString
    #
    # Version: 1.0.20260517.0
    [CmdletBinding()]
    [OutputType([object])]
    param (
        [string]$JsonString
    )

    if ([string]::IsNullOrEmpty($JsonString)) {
        return $null
    }

    try {
        $JsonString | ConvertFrom-Json -ErrorAction Stop
    } catch {
        Write-Debug ("JSON conversion failed: {0}" -f $_)
        $null
    }
}
```

---

### Set-StrictMode Considerations for `finally` Blocks

When `Set-StrictMode -Version Latest` is in effect, referencing a variable that has never been assigned raises a terminating error. This creates a subtle but important pitfall when a `finally` block references a variable that is assigned inside the corresponding `try` block (for example, a disposable resource). If an exception occurs before the assignment executes, `Set-StrictMode` will raise a terminating error for the uninitialized variable inside `finally`, which can mask the original exception and interfere with proper cleanup.

**Rule:** When a `finally` block references a variable that is assigned inside the corresponding `try` block, that variable **MUST** be initialized before the `try` block, typically to `$null`.

**Compliant Example:**

```powershell
$objResource = $null
try {
    $objResource = [SomeDisposable]::Create()
    # ... use $objResource ...
} finally {
    if ($null -ne $objResource) {
        $objResource.Dispose()
    }
}
```

In this example, `$objResource` is initialized to `$null` before the `try` block. If `[SomeDisposable]::Create()` throws before the assignment completes, the `finally` block can safely check `$null -ne $objResource` without triggering a `Set-StrictMode` violation.

---

### Set-StrictMode Placement for Dot-Sourced Files

The placement rule for `Set-StrictMode -Version Latest` (see [Set-StrictMode Placement for Dot-Sourced Files](#set-strictmode-placement-for-dot-sourced-files) in `STYLE_GUIDE.md`) is driven by how PowerShell handles scope when a `.ps1` file is dot-sourced versus when it is executed or bundled into a module.

#### Dot-Sourcing Scope Semantics

When a `.ps1` file is **dot-sourced** with the `.` operator (for example, `. .\Helpers.ps1`), PowerShell does **not** create a new script scope for the file. Instead, every script-scope statement in the file executes in the **caller's scope**. This includes not only function and variable definitions — which is typically the intended effect — but also settings that modify the execution environment, such as:

- `Set-StrictMode -Version Latest`
- `$ErrorActionPreference = 'Stop'`
- `$InformationPreference = 'Continue'`
- `$VerbosePreference`, `$DebugPreference`, `$WarningPreference`
- Any other preference variable assignment or environment-mutating cmdlet invoked at script scope

If a dot-sourced file sets any of these at script scope, the setting silently persists in the caller's scope after the dot-source completes. The caller has no way to know the setting was changed, and the change is indistinguishable from one the caller made deliberately. This is a classic source of "spooky action at a distance" bugs: a test fixture that enables strict mode for its own helpers can flip strict mode on in the caller's script, causing unrelated code downstream to start failing on previously tolerated constructs (uninitialized variables, missing properties, and so on).

By contrast, when a `.ps1` file is **executed** (for example, via `.\Helpers.ps1` or `& .\Helpers.ps1`), PowerShell creates a fresh script scope for the file. Script-scope statements affect only that scope and are discarded when the file exits. When a file is **bundled** into a module or an aggregate script artifact (for example, concatenated into a single `.psm1` or a monolithic script), the bundled artifact has its own isolated scope when it is imported (`Import-Module`) or executed (not dot-sourced), so script-scope `Set-StrictMode` calls inside the bundled source file are contained in those cases. Dot-sourcing any `.ps1` — including an individual bundled source file or a monolithic bundled artifact — still runs its script-scope statements in the caller's scope and therefore still leaks.

#### Why Require `Set-StrictMode` at All in Bundled Source Files

Requiring `Set-StrictMode -Version Latest` near the top of bundled source files — immediately after any PowerShell-required leading constructs such as `#requires` comments, `using` statements, and any allowed script-level `[CmdletBinding()]`/`param` block — is deliberately redundant at runtime: the bundled artifact itself typically establishes strict mode for the whole module, so the per-file call is a no-op in normal module use. The redundancy exists to preserve **file-level correctness** as a standalone property of the source file. Developers frequently run individual source files directly — to reproduce a bug, to execute a quick unit test, to diff two versions of a helper, or to iterate during authoring — and in those workflows the bundled artifact's strict-mode setting is not in effect. Keeping the directive at the start of each source file's executable body ensures that the file behaves identically whether it is loaded through the bundled artifact or executed on its own, which in turn means local reproduction of a bug cannot be obscured by a strict-mode mismatch.

#### Why Forbid Script-Scope `Set-StrictMode` in Dot-Sourced Files

Dot-sourced files — test fixtures, ad-hoc scripts, build tooling — are by contract supposed to *add* names (functions, variables) to the caller's scope and nothing else. Injecting strict-mode or preference-variable changes into the caller violates that contract and turns a helper file into a source of non-local behavior changes. Moving `Set-StrictMode -Version Latest` into the function body (as the first statement in `begin {}` for advanced functions that use a `begin/process/end` layout, or as the first statement in the function body otherwise) confines the setting to the function's own scope chain, so strict mode is active exactly while the function runs and is cleanly restored when the function returns. Using `begin {}` in advanced functions with named pipeline blocks ensures strict mode applies uniformly to `begin`, `process`, and `end`, and avoids re-running `Set-StrictMode` for every pipeline input. The same logic applies to any other preference variable the function needs to set: set it inside the function body, not at script scope, so the caller's environment is not silently mutated.

Where `Set-StrictMode -Version Latest` belongs depends on how the `.ps1` file is consumed at runtime. A `.ps1` file that is dot-sourced executes its script-scope statements in the **caller's scope**, which means a script-scope `Set-StrictMode` call leaks into the caller and silently changes the caller's strict-mode setting. By contrast, when code is consumed through an imported module or by executing a script or aggregate artifact normally (for example, `.\Helpers.ps1`, `& .\Helpers.ps1`, or `Import-Module`), script-scope statements run in that artifact's own script scope, so a script-scope `Set-StrictMode` call is contained to that scope.

**Rule (bundled files):** For files bundled into a module or other aggregate script artifact, `Set-StrictMode -Version Latest` **MUST** be placed at script scope as the first executable statement in the file, after any required file-header constructs such as `#requires` comments, `using` statements, and any script-level `[CmdletBinding()]`/`param` block. The bundled artifact may also establish strict mode, making this redundant at runtime, but it preserves file-level correctness if the source file is ever executed directly. This rule does **not** make dot-sourcing the source file safe: dot-sourcing any `.ps1` file — including an individual bundled source file or a monolithic bundled artifact — still runs its script-scope statements in the caller's scope and will leak strict mode.

**Rule (dot-sourced files):** For files that are not bundled and are instead intended to be dot-sourced directly into the caller's scope (for example, test fixtures, ad-hoc scripts, or build tooling), `Set-StrictMode -Version Latest` **MUST NOT** be placed at script scope. Instead, it **MUST** be placed inside the function body — as the first statement in `begin {}` when the function uses a `begin/process/end` layout (so strict mode covers `begin`, `process`, and `end`, and is not re-invoked for every pipeline input), or otherwise as the first statement in the function body.

#### Bundled File — Compliant Example

```powershell
#requires -Version 5.1
using namespace System.Text

Set-StrictMode -Version Latest

function Get-Thing {
    [CmdletBinding()]
    [OutputType([string])]
    param (
        [string]$Name
    )

    process {
        # ... implementation ...
    }
}
```

#### Bundled File — Non-Compliant Example

```powershell
# Set-StrictMode is missing at file scope. If the bundled artifact fails to
# establish strict mode, or if this file is executed independently,
# strict-mode guarantees are lost.
function Get-Thing {
    [CmdletBinding()]
    [OutputType([string])]
    param (
        [string]$Name
    )

    process {
        # ... implementation ...
    }
}
```

#### Dot-Sourced File — Compliant Example

```powershell
function Invoke-TestFixture {
    [CmdletBinding()]
    [OutputType([void])]
    param (
        [string]$Path
    )

    begin {
        Set-StrictMode -Version Latest
    }

    process {
        # ... implementation ...
    }
}
```

#### Dot-Sourced File — Non-Compliant Example

```powershell
# WRONG — when this file is dot-sourced, Set-StrictMode executes in the
# caller's scope and silently changes the caller's strict-mode setting.
Set-StrictMode -Version Latest

function Invoke-TestFixture {
    [CmdletBinding()]
    [OutputType([void])]
    param (
        [string]$Path
    )

    process {
        # ... implementation ...
    }
}
```

---

### Summary: Error Handling as Diagnostic Instrumentation

The error handling system is a **masterclass in v1.0 reliability engineering**:

- **Fail-controlled** — never crashes
- **Self-diagnosing** — detects errors with certainty
- **State-preserving** — restores environment
- **Comprehensive** — preserves full error context
- **Production-safe** — warnings for impossible states

This is not "working around" v1.0 limitations — it is **exploiting v1.0 mechanics to achieve enterprise-grade reliability**. The system transforms potentially fatal failures into **predictable, analyzable status codes** while maintaining **zero host output** in normal operation.

The only identified weakness is **helper function duplication**, which **SHOULD** be consolidated into shared nested definitions to eliminate maintenance risk. With this single improvement, the error handling system would achieve **perfect reliability scoring** across all PowerShell versions.

## File Writeability Testing

Scripts that write output to files **MUST** verify the destination path is writable **before performing any significant processing** (preflight check for invalid paths, missing directories, insufficient permissions, read-only locations, locked files).

### Approaches

#### v1.0 Parser Error Rationale

Since `try/catch` was introduced in PowerShell v2.0, any script containing this syntax will fail to parse on v1.0, even if the code path is never executed. This is why v1.0-targeted scripts **MUST** use the `.NET` approach.

Use the `Test-FileWriteability` function bundled from the reference implementation (see [Reference Implementation](#reference-implementation)).

#### Scripts Requiring PowerShell v2.0+ Support

For scripts targeting PowerShell v2.0 or later, **either approach is acceptable**.

##### Prefer the `.NET` Approach (`Test-FileWriteability`) When

- Script performs **mission-critical operations** or where strict error control/avoidance (i.e., avoiding users seeing an error) is paramount
- Script runs **unattended** (scheduled tasks, automation pipelines)
- Script is part of a **larger module or library** where consistency matters, or where the script/library has to be runnable on PowerShell v1.0 without throwing a parser error
- **Detailed error capture** is needed (e.g., populating a reference to an ErrorRecord for logging)
- Script size is **not a concern**

##### Prefer the `try/catch` Approach When

- Script is a **simple, single-purpose utility**
- Script runs **interactively** where users can see and respond to errors
- The typical user is **PowerShell-savvy** and would be expected to interpret any issues without trouble
- Script is **distributed to others** who may need to read/modify it (simpler code is easier to understand)
- **Minimizing script size** is important

1. **`.NET` approach** (`Test-FileWriteability`): Comprehensive, uses .NET file operations. **MUST** be used for v1.0-targeted scripts (since `try/catch` causes parser errors in v1.0).
2. **`try/catch` approach**: Shorter (~10 lines), requires PowerShell v2.0+.

Both use a **create-then-delete pattern**. The delete step catches additional failure modes (e.g., file locks on Windows) that file creation alone may miss.

**[v1.0]** scripts **MUST** use the `.NET` approach. **[Modern]** scripts **MAY** use either approach.

Prefer `.NET` for mission-critical/unattended scripts, or where v1.0 parseability is needed. Prefer `try/catch` for simple utilities or when minimizing size.

---

### Code Examples

#### try/catch Approach Rationale

The `try/catch` code example uses `.NET` static methods for both path construction (`[System.IO.Path]::Combine()`) and file operations (`[System.IO.File]::Open()` and `[System.IO.File]::Delete()`) instead of cmdlets. `New-Item` does not support `-LiteralPath`, and `Join-Path`'s `-Path` parameter accepts wildcard characters. Since the guide requires `-LiteralPath` for variable-derived concrete paths, the cmdlet-based approach cannot be made consistent with that rule. `.NET` path and file APIs operate on literal path strings and do not interpret PowerShell wildcard characters, avoiding the inconsistency.

The probe writes to a GUID-based temporary filename (`.write_test_{GUID}.tmp`) in the target file's parent directory instead of probing at the actual output path. This avoids two problems:

- **Data destruction**: APIs with create-or-overwrite semantics (e.g., `[System.IO.File]::Create()`, `New-Item -Force`) truncate or overwrite an existing file at the probe path, destroying pre-existing user data.
- **False failures in overwrite workflows**: If the output file already exists and the script intends to overwrite it, probing at the exact output path with `[System.IO.FileMode]::CreateNew` would throw an `IOException` — a false negative that incorrectly reports the directory as non-writable.

The probe uses `[System.IO.FileMode]::CreateNew` rather than `[System.IO.FileMode]::Create` or `[System.IO.File]::Create()`. `CreateNew` throws an `IOException` if the target file already exists, providing a safety net even in the vanishingly unlikely event of a GUID collision. `Create` (and `[System.IO.File]::Create()`) silently truncate an existing file, which would mask the collision and destroy the other file's contents.

The `[System.IO.FileAccess]::Write` parameter is specified explicitly because the two-argument `File.Open(path, FileMode)` overload defaults to `FileAccess.ReadWrite`. Since the probe only needs to verify write permission, requesting read access is unnecessary and could cause a false negative in environments where inherited ACLs deny read on newly created files while permitting write.

The path is resolved to absolute form via `$ExecutionContext.SessionState.Path.GetUnresolvedProviderPathFromPSPath()` before being passed to the `.NET` static methods. See [Resolving Paths for .NET Static Methods](#resolving-paths-for-net-static-methods) for the general rule and rationale.

#### .NET Approach

Bundle `Test-FileWriteability` from the [reference implementation](#reference-implementation):

```powershell
$errRecord = $null
$boolIsWritable = Test-FileWriteability -Path 'Z:\InvalidPath\file.log' -ReferenceToErrorRecord ([ref]$errRecord)
if (-not $boolIsWritable) {
    Write-Warning ('Failed to write to path. Error: ' + $errRecord.Exception.Message)
    return # replace with an appropriate exiting action
}
```

#### try/catch Approach

```powershell
try {
    $strOutputPath = $ExecutionContext.SessionState.Path.GetUnresolvedProviderPathFromPSPath($OutputPath)
    $strWriteTestPath = [System.IO.Path]::Combine([System.IO.Path]::GetDirectoryName($strOutputPath), ('.write_test_{0}.tmp' -f [Guid]::NewGuid().ToString('N')))
    [System.IO.File]::Open($strWriteTestPath, [System.IO.FileMode]::CreateNew, [System.IO.FileAccess]::Write).Dispose()
    [System.IO.File]::Delete($strWriteTestPath)
} catch {
    throw ("Cannot write to '{0}': {1}" -f $OutputPath, $_.Exception.Message)
}
```

> **Warning:** File APIs with create-or-overwrite semantics (e.g., `[System.IO.File]::Create()`, `New-Item -Force`) **SHOULD NOT** be used for writeability probes unless the probe filename is guaranteed unique. Using the actual output path as the probe can destroy pre-existing data or cause false failures when the file already exists.

---

### Reference Implementation

For scripts requiring the comprehensive `.NET` approach, a full implementation of the `Test-FileWriteability` function is available at:

<https://github.com/franklesniak/PowerShell_Resources/blob/master/Test-FileWriteability.ps1>

This implementation includes:

- Explicit file handle control and resource cleanup
- Detailed error capture via reference parameters
- Full documentation and examples
- Support for PowerShell v1.0+

Full `Test-FileWriteability` implementation: <https://github.com/franklesniak/PowerShell_Resources/blob/master/Test-FileWriteability.ps1>

## Operating System Compatibility Checks

Platform-specific scripts/functions **MUST** include OS checks before platform-specific operations. **Fail early** — perform checks at the beginning of the function or script.

### PowerShell Core 6.0+ OS Detection

If the script or function **only** needs to support PowerShell Core 6.0 or newer (and does not need to run on Windows PowerShell 1.0-5.1), the built-in automatic variables can be used for OS detection:

- **`$IsWindows`** — `$true` on Windows, `$false` on other platforms
- **`$IsMacOS`** — `$true` on macOS, `$false` on other platforms
- **`$IsLinux`** — `$true` on Linux, `$false` on other platforms

**Example: Windows-only script for PowerShell Core 6.0+:**

```powershell
function Get-WindowsSystemInfo {
    # .SYNOPSIS
    # Retrieves Windows-specific system information.
    # .DESCRIPTION
    # This function only runs on Windows and uses Windows-specific cmdlets.
    # .NOTES
    # Requires PowerShell Core 6.0+
    # Version: 1.0.20260109.0

    param()

    # Check if running on Windows
    if (-not $IsWindows) {
        Write-Error -Message "This function only runs on Windows."
        return -1
    }

    # Proceed with Windows-specific operations
    $objSystemInfo = Get-CimInstance -ClassName Win32_OperatingSystem
    return 0
}
```

**Example: Linux or macOS script:**

```powershell
function Get-UnixSystemInfo {
    # .SYNOPSIS
    # Retrieves Unix-based system information.
    # .DESCRIPTION
    # This function runs on Linux or macOS only.
    # .NOTES
    # Requires PowerShell Core 6.0+
    # Version: 1.0.20260109.0

    param()

    # Check if running on a Unix-based system
    if (-not ($IsLinux -or $IsMacOS)) {
        Write-Error -Message "This function only runs on Linux or macOS."
        return -1
    }

    # Proceed with Unix-specific operations
    $strOutput = uname -a
    return 0
}
```

Use built-in variables: `$IsWindows`, `$IsMacOS`, `$IsLinux`.

```powershell
if (-not $IsWindows) {
    Write-Error -Message "This function only runs on Windows."
    return -1
}
```

---

### Cross-Version OS Detection

**Example: Windows-only script for PowerShell 1.0+:**

```powershell
# Bundle the Test-Windows function from PowerShell_Resources repository
# (Include full function definition here or dot-source it)

function Get-WindowsSystemInfo {
    # .SYNOPSIS
    # Retrieves Windows-specific system information.
    # .DESCRIPTION
    # This function only runs on Windows and uses Windows-specific cmdlets.
    # Compatible with PowerShell 1.0+.
    # .NOTES
    # Version: 1.0.20260109.0

    param()

    # Check if running on Windows using safe cross-version detection
    $boolIsWindows = Test-Windows
    if (-not $boolIsWindows) {
        Write-Warning -Message "This function only runs on Windows."
        return -1
    }

    # Proceed with Windows-specific operations
    # Use appropriate cmdlets based on PowerShell version
    return 0
}
```

**Example: Linux or macOS script for PowerShell 1.0+:**

```powershell
# Bundle Test-Linux and Test-macOS functions from PowerShell_Resources
# (Include full function definitions here or dot-source them)

function Get-UnixSystemInfo {
    # .SYNOPSIS
    # Retrieves Unix-based system information.
    # .DESCRIPTION
    # This function runs on Linux or macOS only.
    # Compatible with PowerShell 1.0+.
    # .NOTES
    # Version: 1.0.20260109.0

    param()

    # Check if running on a Unix-based system
    $boolIsLinux = Test-Linux
    $boolIsMacOS = Test-macOS

    if (-not ($boolIsLinux -or $boolIsMacOS)) {
        Write-Warning -Message "This function only runs on Linux or macOS."
        return -1
    }

    # Proceed with Unix-specific operations
    return 0
}
```

**Rationale for using dedicated functions:**

The `$IsWindows`, `$IsMacOS`, and `$IsLinux` variables were introduced in PowerShell Core 6.0. Attempting to reference these variables in PowerShell 1.0-5.1 results in a `$null` value, which can lead to incorrect behavior (e.g., `-not $IsWindows` evaluates to `$true` on Windows PowerShell 5.1, incorrectly suggesting the script is not on Windows).

The `Test-Windows`, `Test-macOS`, and `Test-Linux` functions from the PowerShell_Resources repository provide safe, reliable OS detection that works identically across all PowerShell versions from 1.0 onward.

For scripts supporting PowerShell older than 6.0 (including Windows PowerShell 1.0–5.1), `$IsWindows`/`$IsMacOS`/`$IsLinux` do not exist; referencing them yields `$null` or throws under strict mode, causing incorrect behavior. Use safe detection functions from [`PowerShell_Resources`](https://github.com/franklesniak/PowerShell_Resources):

| OS | Function | Link |
| --- | --- | --- |
| Windows | `Test-Windows` | [`Test-Windows.ps1`](https://github.com/franklesniak/PowerShell_Resources/blob/master/Test-Windows.ps1) |
| macOS | `Test-macOS` | [`Test-macOS.ps1`](https://github.com/franklesniak/PowerShell_Resources/blob/master/Test-macOS.ps1) |
| Linux | `Test-Linux` | [`Test-Linux.ps1`](https://github.com/franklesniak/PowerShell_Resources/blob/master/Test-Linux.ps1) |

```powershell
$boolIsWindows = Test-Windows
if (-not $boolIsWindows) {
    Write-Warning -Message "This function only runs on Windows."
    return -1
}
```

### Error Handling for Wrong OS

If the script or function detects that it is running on an unsupported operating system, it **SHOULD** report the error in a way that is **consistent with the script's or function's existing error handling patterns**.

**Guidelines:**

1. **Match the error reporting style:** If the function returns integer status codes (e.g., `0` for success, `-1` for failure), return the appropriate error code. If it uses exceptions, throw an exception. If it uses `Write-Error`, use that.

2. **Provide clear error messages:** The error message **SHOULD** clearly state which operating system(s) are required and which OS was detected.

3. **Fail early:** Perform the OS check at the beginning of the function or script, before any significant processing occurs.

**Example: Function returning status code:**

```powershell
function Get-WindowsRegistryValue {
    # .SYNOPSIS
    # Retrieves a value from the Windows Registry.
    # .OUTPUTS
    # [int] Status code: 0=success, -1=failure (including wrong OS)

    param(
        [string]$Path
    )

    # OS check at the beginning
    if (-not $IsWindows) {
        Write-Error -Message "This function requires Windows. Current OS is not supported."
        return -1
    }

    # Proceed with Windows-specific operations
    return 0
}
```

**Example: Function using Write-Warning for non-critical failure:**

```powershell
function Get-OptionalWindowsInfo {
    # .SYNOPSIS
    # Retrieves optional Windows information.

    param()

    # Check OS and warn if not Windows
    if (-not $IsWindows) {
        Write-Warning -Message "This function is optimized for Windows. Some features may not be available on other platforms."
        return $null
    }

    # Proceed with Windows-specific operations
    return $objInfo
}
```

**Example: Script exiting with clear error:**

```powershell
# At the top of a Windows-only script
if (-not $IsWindows) {
    Write-Error -Message "This script requires Windows. Current OS: $(if ($IsLinux) { 'Linux' } elseif ($IsMacOS) { 'macOS' } else { 'Unknown' })"
    exit 1
}

# Continue with Windows-specific script logic
```

#### Summary: OS Compatibility Checks

Operating system compatibility checks are a **critical reliability requirement** for platform-specific scripts and functions:

- **Required** when scripts/functions support only specific operating systems
- **Use built-in variables** (`$IsWindows`, `$IsMacOS`, `$IsLinux`) for PowerShell Core 6.0+ only scripts
- **Use safe functions** (`Test-Windows`, `Test-macOS`, `Test-Linux`) for scripts supporting older PowerShell versions
- **Report errors consistently** with the script's existing error handling patterns
- **Fail early** to prevent unexpected behavior on unsupported platforms

Report errors **consistently** with the script's existing error handling pattern (status codes, exceptions, or `Write-Error`). Error messages **SHOULD** clearly state which OS(es) are required.

## Language Interop, Versioning, and .NET

### Executive Summary: Interop and Versioning Strategy

The author employs a **sophisticated, version-aware interoperability layer** that seamlessly bridges **PowerShell v1.0 scripting** with **.NET Framework capabilities** while maintaining **strict backward compatibility** and **deterministic behavior** across all PowerShell versions from 1.0 to modern releases in compatible scripts. This is achieved through:

1. **Runtime version detection** via a dedicated helper function
2. **Conditional execution paths** based on detected PowerShell version
3. **Progressive enhancement** — using advanced .NET types only when available
4. **Graceful degradation** — falling back to simpler types when modern features are absent
5. **Explicit .NET interop** with full documentation of rationale

The strategy transforms potentially version-breaking operations (e.g., handling large numbers) into **resilient, self-adapting code** that works identically whether running on PowerShell 1.0, 3.0, or 7.x. In scripts with dependencies requiring newer PowerShell, version detection is minimized or omitted in favor of assuming the required features.

### Runtime Version Detection: `Get-PSVersion`

**Analysis of detection logic**:

| Condition | PowerShell Version | Result |
| --- | --- | --- |
| `$PSVersionTable` exists | v2.0+ | Actual version (e.g., 5.1.22621.2506) |
| `$PSVersionTable` missing | v1.0 | Hard-coded `[version]'1.0'` |

**Critical findings**:

- **No reliance** on `$PSVersionTable.PSVersion.Major` ≥ 2 → avoids false positives
- **Explicit fallback** to `'1.0'` → prevents `$null` or exceptions
- **Returns `[version]` type** → enables direct comparison (`$version.Major -ge 3`)
- **v1.0 compatible** → uses only v1.0 features (`Test-Path`, variable access)

A **dedicated version probe** returns a `[System.Version]` object:

```powershell
function Get-PSVersion {
    if (Test-Path variable:\PSVersionTable) {
        return $PSVersionTable.PSVersion
    } else {
        return [version]'1.0'
    }
}
```

Returns actual version on v2.0+; falls back to `[version]'1.0'` when `$PSVersionTable` is absent.

---

### Conditional .NET Feature Usage: Progressive Enhancement

The **progressive enhancement stack** for numeric overflow handling:

| PowerShell Version | .NET Type Used | Numeric Range |
| --- | --- | --- |
| v3.0+ | `[System.Numerics.BigInteger]` | Unlimited (subject to memory) |
| v1.0–v2.0 | `[double]` | ±1.7 × 10³⁰⁸ (IEEE 754) |
| All versions | `[int]`, `[int64]` | Built-in safe conversions |

**Rationale**:

- **BigInteger** → handles numbers larger than `[int32]::MaxValue` (2,147,483,647)
- **Double** → v1.0-compatible approximation for large numbers
- **No runtime exceptions** → conversion functions return `$false` on failure

Use PowerShell version as a feature flag for .NET types:

```powershell
if ($versionPowerShell.Major -ge 3) {
    $boolResult = Convert-StringToBigIntegerSafely ...
} else {
    $boolResult = Convert-StringToDoubleSafely ...
}
```

| PowerShell Version | .NET Type Used | Numeric Range |
| --- | --- | --- |
| v3.0+ | `[System.Numerics.BigInteger]` | Unlimited (subject to memory) |
| v1.0–v2.0 | `[double]` | ±1.7 × 10³⁰⁸ (IEEE 754) |
| All versions | `[int]`, `[int64]` | Built-in safe conversions |

---

### .NET Interop Patterns: Safe and Documented

The author uses **direct .NET interop** in controlled scenarios:

| .NET Usage | Implementation | Technical Justification |
| --- | --- | --- |
| **`[regex]::Escape()`** | `Split-StringOnLiteralString` | Ensures literal string splitting (not regex) in v1.0 |
| **`[regex]::Split()`** | Same function | v1.0-compatible alternative to `-split` operator (v2.0+) |
| **`[System.Numerics.BigInteger]`** | Overflow handling | Only when PS v3+ detected |

**Example: Literal string splitting**:

```powershell
$strSplitterInRegEx = [regex]::Escape($Splitter)
$result = [regex]::Split($StringToSplit, $strSplitterInRegEx)
```

**Deprecation of `System.Collections.ArrayList`:** `System.Collections.ArrayList` is **deprecated** (consistent with [Microsoft's .NET guidance](https://learn.microsoft.com/en-us/dotnet/api/system.collections.arraylist)) and **MUST NOT** be used in new code. All new and newly-modified code **MUST** use `System.Collections.Generic.List[T]` instead. `System.Collections.Generic.List[T]` has been available since .NET Framework 2.0 (PowerShell v1.0).

`ArrayList` is only permitted as a fallback in rare, well-justified cases where an attempt to instantiate `System.Collections.Generic.List[T]` throws an exception that is caught and handled. Such fallback **MUST** be reported via the debug stream, and the debug message **MUST** include the caught exception type and message (for example: `Write-Debug "Failed to create generic list; falling back to ArrayList. Exception: $($_.Exception.GetType().FullName): $($_.Exception.Message)"`).

```powershell
# Compliant (Required for all new code)
$list = New-Object System.Collections.Generic.List[PSCustomObject]

# Non-Compliant (Deprecated — do not use in new code)
$list = New-Object System.Collections.ArrayList
```

> **Migration Note:** Legacy code that uses `System.Collections.ArrayList` **SHOULD** be refactored to use `System.Collections.Generic.List[T]` with the appropriate type parameter when the code is next modified. Replace `New-Object System.Collections.ArrayList` with `New-Object System.Collections.Generic.List[PSCustomObject]` (or the appropriate type), and verify that all `.Add()` calls and downstream consumers are compatible with the typed list.

**Typed Generic Collections:** When instantiating generic .NET collections, such as `System.Collections.Generic.List[T]`, the specific type `T` **MUST** be provided if known (e.g., `[PSCustomObject]`, `[string]`). This is more precise, safer, and more descriptive than using the generic `[object]`.

```powershell
# Compliant (Preferred)
$listAttached = New-Object System.Collections.Generic.List[PSCustomObject]

# Non-Compliant (Vague)
$listAttached = New-Object System.Collections.Generic.List[object]
```

**Avoiding PowerShell Array `+=` in Accumulation Loops:** PowerShell arrays are fixed-size. When code uses `$arrOutput += $objItem` inside a loop, PowerShell must allocate a new array and copy all existing elements on every append. Those repeated copies add up as the collection grows: 1 + 2 + ... + n copies, which makes the loop O(n^2) instead of linear.

`System.Collections.Generic.List[T]` is the correct in-memory accumulation structure because appends are amortized O(1). The list can grow without reallocating and copying every element for every single `.Add()` call. A final `.ToArray()` conversion is justified only at a boundary where an array is actually part of the required contract, such as a strongly typed array property, a legacy API call, or a documented return/reference-output shape.

Wrapping `List[T].Add()` in `[void](...)` is defensive consistency with the guide's broader method-output suppression style, not a technical requirement for `List[T]`: `List[T].Add()` and `.AddRange()` return `void`. This differs from the deprecated `System.Collections.ArrayList.Add()` method, which returns the new element index as an `[int]` and can pollute the success stream if not suppressed.

**Advantages**:

- **v1.0 compatible** → `[regex]` class exists in .NET 2.0
- **Deterministic behavior** → no regex metacharacter interpretation
- **No external dependencies** → pure .NET Framework

| .NET Usage | Technical Justification |
| --- | --- |
| `[regex]::Escape()` + `[regex]::Split()` | Literal string splitting in v1.0 (alternative to v2.0+ `-split`) |
| `[System.Numerics.BigInteger]` | Overflow handling — only when PS v3+ detected |

**Deprecation of `System.Collections.ArrayList`:** `ArrayList` is **deprecated** and **MUST NOT** be used in new code. Use `System.Collections.Generic.List[T]` instead (available since .NET 2.0 / PS v1.0). `ArrayList` is only permitted as a caught-exception fallback, reported via debug stream.

```powershell
# Compliant
$list = New-Object System.Collections.Generic.List[PSCustomObject]

# Non-Compliant (Deprecated)
$list = New-Object System.Collections.ArrayList
```

**Typed Generic Collections:** The specific type `T` **MUST** be provided if known (e.g., `[PSCustomObject]`, `[string]`), not `[object]`.

**PowerShell Array Accumulation:** Code **MUST NOT** grow a PowerShell array with `+=` inside an accumulation loop. PowerShell arrays are fixed-size, so each `+=` creates a new array and copies the existing elements. When a collection must be accumulated in memory, code **MUST** use `System.Collections.Generic.List[T]` with `.Add()` or `.AddRange()`, and convert to an array with `.ToArray()` only at a boundary where an array is actually required. This rule complements, and does not weaken, the requirement that modern functions stream output when streaming is the correct contract.

```powershell
# Compliant
$listOutput = New-Object System.Collections.Generic.List[PSCustomObject]
foreach ($objItem in $InputObject) {
    [void]($listOutput.Add($objItem))
}
$arrOutput = $listOutput.ToArray()

# Non-Compliant
$arrOutput = @()
foreach ($objItem in $InputObject) {
    $arrOutput += $objItem
}
```

---

### Type Conversion Safety Chain

The author implements a **defense-in-depth conversion chain** for numeric strings:

```powershell
# 1. Try int32 (safe, fast)
# 2. If overflow → try int64
# 3. If still overflow and PS v3+ → try BigInteger
# 4. If still overflow or PS v1.0 → try double
# 5. If all fail → treat as non-numeric
```

Each step uses the **atomic error handling pattern** (trap + preference toggle + reference comparison) to:

- Attempt conversion
- Detect failure
- Preserve original error
- Return `$false` without throwing

### Version-Aware Fallback Logic

Functions use version detection to **bypass expensive checks** when possible:

```powershell
if ($PSVersion -eq ([version]'0.0')) {
    $versionPowerShell = Get-PSVersion  # Detect if not provided
} else {
    $versionPowerShell = $PSVersion     # Use caller-provided value
}
```

**Benefits**:

- **Performance optimization** → skip version detection if caller knows runtime
- **Flexibility** → supports both interactive and scripted use
- **Defensive programming** → default case handles unexpected input

### .NET Type Usage Summary

| .NET Type | First Available | Technical Purpose |
| --- | --- | --- |
| `[regex]` | .NET 2.0 (PS v1.0) | Literal string parsing |
| `[System.Numerics.BigInteger]` | .NET 4.0 (PS v3.0+) | Unlimited integer precision |
| `[version]` | .NET 2.0 | Standard version semantics |
| `[ref]` | .NET 2.0 | Multiple return values (only for write-back) |

All types are **v1.0-safe** except `BigInteger`, which is **guarded by version check**.

---

### Modernization Path (v2.0+)

If v1.0 compatibility were not required, the author would likely:

1. **Replace manual version detection** with `#requires -Version 3.0`
2. **Use `[bigint]` PSCustomObject** instead of `BigInteger` (PS v7+)
3. **Leverage `-split` operator** with `[regex]::Escape()` for literal splits
4. **Add `[ValidateScript()]` attributes** for input validation

### Summary: Interop as Adaptive Resilience

The language interop and versioning strategy represents **adaptive resilience engineering**:

- **Version detection** → knows its environment
- **Progressive enhancement** → uses best available tools
- **Graceful degradation** → never fails due to missing features
- **Explicit .NET usage** → documented, safe, and v1.0-compatible
- **Provider-agnostic paths** → deterministic across environments

This creates code that:

- Works on **PowerShell 1.0** with basic functionality
- **Automatically upgrades** performance/precision on newer runtimes
- **Never crashes** due to version differences
- **Self-documents** its capabilities and limitations

The system transforms version fragmentation from a liability into a **non-issue** — the script simply **does the right thing** regardless of where it runs.

## Output Formatting and Streams

### Executive Summary: Output Discipline

The author enforces a **zero-tolerance policy for uncontrolled output** and implements a **strict, single-typed, stream-isolated communication model**. This is not merely stylistic preference but a **core reliability requirement** driven by the function's role as a **reusable tool** in **v1.0 PowerShell environments** when applicable.

All output follows **three key principles**:

1. **Single output type** — only one kind of object ever leaves the function
2. **Explicit stream routing** — each message type uses exactly one stream
3. **No host pollution** — no output appears unless explicitly requested

This creates a **predictable, composable, and debuggable** interface that works identically whether the function is called interactively, from a script, or within a larger pipeline. In modern-dependent scripts, additional streams like Verbose or Debug are used as needed.

### Primary Output: Integer Status Code via `return`

**Key characteristics** of the primary output status code:

| Property | Implementation |
| --- | --- |
| **Type** | `[int]` (32-bit signed integer) |
| **Source** | Explicit `return` statement |
| **Stream** | Success (pipeline) |
| **Cardinality** | Exactly one value |

**Documented in `.OUTPUTS`**:

```powershell
# .OUTPUTS
# [int] Status code: 0=success, 1-5=partial with additional data, -1=failure
```

This status code serves as the **function's contract** — a machine-readable indicator of outcome.

v1.0-targeted functions return a **single `[int]` status code** via explicit `return`:

```powershell
return 0    # Full success
return 4    # Partial success
return -1   # Complete failure
```

Document in `.OUTPUTS`: `# [int] Status code: 0=success, 1-5=partial with additional data, -1=failure`

---

### Processing Collections in Modern Functions (Streaming Output)

A modern (non-v1.0) function **SHOULD NOT** build a large collection (like a `List<T>`) and return it at the end. This is memory-inefficient, as it requires holding all results in memory, and often creates an unnecessary O(n) performance hit when the list is copied.

The preferred, idiomatic PowerShell pattern is to **"stream" the output**: write each result object *directly to the pipeline from within the processing loop*. This is highly memory-efficient and aligns with the pipeline's "one object at a time" philosophy.

- **Compliant (Streaming):** Write objects to the pipeline *inside* your loop.
- **Non-Compliant (Collecting):** Adding all objects to a `$list` and returning `$list` at the end.

**Compliant (Streaming) Example:**

```powershell
[CmdletBinding()]
[OutputType([pscustomobject])]
param(...)

foreach ($objItem in $SourceData) {
    # ... logic to create $objResult ...
    $objResult # This writes the object to the pipeline
}
# Note: There is no 'return' statement for the collection
```

**Non-Compliant (Collecting) Example:**

```powershell
[CmdletBinding()]
[OutputType([pscustomobject[]])] # Unnecessary plural
param(...)

$listOutput = New-Object System.Collections.Generic.List[PSCustomObject]
foreach ($objItem in $SourceData) {
    # ... logic ...
    [void]($listOutput.Add($objResult))
}
return $listOutput.ToArray() # Unnecessary copy and non-idiomatic
```

This rule is distinct from the v1.0-native pattern, which uses explicit integer `return` codes and passes data via `[ref]` parameters. The v1.0-native pattern **MAY** be desireable in situations where the function **SHOULD** return no output in the event of any error occurring during processing, or where error/warning status needs to be passed back to the caller.

---

### Complex Output: Reference Parameters (`[ref]`)

When structured data must be written back to the caller, `[ref]` parameters provide several practical **advantages**:

- **No pipeline interference** — data never accidentally flows downstream
- **Caller-controlled lifetime** — variables persist after function exit
- **Multiple return values** — result + additional data in one call
- **v1.0 compatible** — `[ref]` works in all versions

**Post-call state example**:

```powershell
$result = processed value
$extras = @('','', '', 'extra', '')
$status   = 4
```

All **structured data** is returned via **`[ref]` parameters** only when write-back to the caller is required.

---

### Stream Usage: Clear Mapping

#### Warning Stream Details

`Write-Warning` **MUST** be used **sparingly and surgically** for **logically impossible states**:

```powershell
Write-Warning -Message 'Conversion of string failed even though valid. This should not be possible!'
```

**Purpose**:

- **Developer alert** — indicates internal contract violation
- **Non-terminating** — does not halt execution
- **Actionable** — includes exact values and context
- **Production-safe** — visible only with `-WarningAction` or `$WarningPreference`

#### Host Stream Rationale

**No output ever goes to the host console** via:

- `Write-Host`
- `Write-Output` (except via `return`)
- Echo/print statements

**Rationale**:

- **Pipeline safety** — prevents data leakage
- **Script compatibility** — silent operation in automation
- **v1.0 compliance** — avoids v2.0+ stream features

#### Output Type Consistency

The function **never emits mixed object types**. The only object that can leave via the success stream is the **integer status code**.

**Guarantee**:

```powershell
$result = Process-String ...
$result.GetType().FullName  # Always "System.Int32"
```

This enables:

- **Pipeline chaining** with confidence
- **Type-based filtering** in larger scripts
- **Static analysis** of data flow

#### Stream Interaction Matrix

| Caller Context | Success Stream | Warning Stream | Host Stream |
| --- | --- | --- | --- |
| Interactive | Status code visible | Warnings shown | **Never** |
| Script | `$status` captured | Warnings logged | **Never** |
| Pipeline | Status flows downstream | Warnings preserved | **Never** |

| Stream | Command | Purpose |
| --- | --- | --- |
| **Success** | `return` | Primary result (status code) |
| **Warning** | `Write-Warning` | Logical anomalies (contract violations) |
| **Host** | *Never used* | **Prohibited** — `Write-Host` **MUST NOT** be used |

v1.0-targeted functions **MUST NOT** emit mixed object types on the success stream.

---

---

### Format Files: Future-Proof Design Pattern

While not implemented in this v1.0 script, the author's design **anticipates** the use of **`.format.ps1xml` files** for custom object display:

```xml
<!-- Hypothetical modulename.format.ps1xml -->
<Type>
  <Name>ProcessingResult</Name>
  <Members>
    <NoteProperty Name="Status"    Type="int" />
    <NoteProperty Name="Result"   Type="object" />
    <NoteProperty Name="Extras" Type="string[]" />
  </Members>
</Type>
```

**Design considerations**:

- **Raw data preserved** — objects contain full fidelity
- **Display decoupled** — formatting is external
- **Pipeline-safe** — formatting applied only at display time

### Modern Stream Capabilities (v2.0+ Context)

In PowerShell v2.0+, the author would likely add:

```powershell
[CmdletBinding()]
param(...)
process {
    Write-Verbose "Attempting operation on $StringToProcess"
    Write-Debug   "Pre-operation error count: $($Error.Count)"
}
```

> **Note:** This example uses `$StringToProcess` for brevity. When the logged variable could contain PII, credentials, or other sensitive data, follow the guidance in [Sensitive Data in Verbose and Debug Streams](#sensitive-data-in-verbose-and-debug-streams).

**Streams enabled**:

- **Verbose** → operational details
- **Debug** → internal state
- **Progress** → long-running operations (not applicable here)

But in **v1.0**, these are **deliberately omitted** — not due to ignorance, but **design constraint**.

### Summary: Output as Controlled Interface

The output formatting and stream usage represent **military-grade interface discipline**:

- **Single return type** (`[int]`) → predictable
- **Reference parameters** → complex data without pipeline risk (only for write-back)
- **Warning stream** → diagnostic beacon for impossible states
- **Host stream** → completely sealed
- **Format files** → anticipated for future display needs

This creates a **fortified boundary** between the function and its environment:

- **No data leakage**
- **No side effects**
- **Full diagnostic visibility** when needed
- **Perfect compatibility** with automation, scripting, and interactive use

The absence of `Write-Host` and mixed output types is not a limitation — it is **evidence of mastery** over PowerShell's output model and a deliberate choice for **maximum reliability** in v1.0 environments.

### Choosing Between Warning and Debug Streams

The choice of output stream is critical for communicating intent:

- **Warning Stream (`Write-Warning`):** Reserved for logical anomalies or conditions that the **end-user** **SHOULD** be aware of, but which do not halt execution (e.g., "Could not determine root user email for account X").
- **Debug Stream (`Write-Debug`):** Used for logging **internal function details** that are not relevant to the end-user but are critical for diagnostics. This includes handled `catch` block errors, or fallback logic (e.g., "Failed to create generic lists; falling back to ArrayLists.").

### Suppression of Method Output

When calling .NET methods that return a value (like `System.Collections.ArrayList.Add()`), that output **MUST** be suppressed to avoid polluting the pipeline. The preferred method is to cast the entire statement to `[void]` for performance, as it is measurably faster than piping to `| Out-Null`.

```powershell
# Compliant (Preferred for performance)
[void]($list.Add($item))

# Non-Compliant (Typically slower than casting to void)
$list.Add($item) | Out-Null
```

### Sensitive Data in Verbose and Debug Streams

Additional compliant examples for logging sensitive data safely:

```powershell
# Compliant - logs the value's type name with a null-safe fallback
$strPrincipalKeyTypeName = if ($null -ne $PrincipalKey) { $PrincipalKey.GetType().Name } else { '<null>' }
Write-Debug -Message ('PrincipalKey type: {0}' -f $strPrincipalKeyTypeName)

# Compliant - logs non-sensitive metadata (string length) with a type-safe fallback
$strPrincipalKeyLength = if ($PrincipalKey -is [string]) { [string]$PrincipalKey.Length } else { '<n/a>' }
Write-Verbose -Message ('PrincipalKey length: {0}' -f $strPrincipalKeyLength)
```

Functions **MUST NOT** emit raw PII, credentials, secrets, tokens, or sensitive identifiers via `Write-Verbose` or `Write-Debug`. Use safe alternatives: boolean presence flags, non-sensitive metadata (length, count, type name), or redacted values.

```powershell
# Non-Compliant
Write-Verbose -Message ('PrincipalKey: ' + $PrincipalKey)

# Compliant - logs whether the value is present (boolean)
Write-Verbose -Message ('PrincipalKey present: {0}' -f ($null -ne $PrincipalKey))
```

### Performance-Sensitive `Write-Verbose` / `Write-Debug` in Hot Paths

**[Modern]** functions that are called per-record or inside tight loops (that is, hot paths) **SHOULD** guard `Write-Verbose` and `Write-Debug` calls that perform string formatting — such as with the `-f` operator or string concatenation — behind an appropriate preference check to avoid unconditional string allocation overhead when the stream is not enabled.

**Recommended pattern for `Write-Verbose`:**

```powershell
if ($VerbosePreference -ne 'SilentlyContinue') {
    Write-Verbose ("Processing item: {0}" -f $strCurrentItem)
}
```

**Recommended pattern for `Write-Debug`:**

```powershell
if ($DebugPreference -ne 'SilentlyContinue') {
    Write-Debug ("Processing item: {0}" -f $strCurrentItem)
}
```

> **Note:** This guard is recommended only for performance-sensitive code paths and is **NOT** required for functions that run once, or only a small number of times, per pipeline or script execution.

## Testing with Pester

**Pester 5.x** is required. Legacy 3.x/4.x patterns **MUST NOT** be used. Pester requires PowerShell 3.0+ to run, but scripts under test can target any version. See [pester.dev](https://pester.dev/).

---

### Test File Naming and Location

**Example directory structure:**

```text
repository/
├── src/
│   └── Get-UserInfo.ps1
└── tests/
    └── Get-UserInfo.Tests.ps1
```

#### Pester Intro

**Pester** is the standard testing framework for PowerShell, providing a domain-specific language for writing and executing tests. This section documents testing conventions that integrate with the coding standards in this guide. For comprehensive Pester documentation, see [pester.dev](https://pester.dev/).

> **Note:** Pester 5.x requires PowerShell 3.0+ to execute tests. However, v1.0-compatible scripts can still be tested with Pester—simply run the tests on a modern PowerShell version (e.g., pwsh 7.x on a CI platform like `ubuntu-latest`). The test files themselves will use modern Pester syntax, but the scripts under test can target any PowerShell version.

- Test files **MUST** use `*.Tests.ps1` suffix
- Test files **SHOULD** be in a `tests/` directory at the repository root
- One test file per function/script **SHOULD** be created

---

### Pester 5.x Syntax Requirements

Tests **MUST** use Pester 5.x syntax. Legacy Pester 3.x/4.x patterns **MUST NOT** be used.

| Block | Purpose |
| --- | --- |
| `BeforeAll` | One-time setup at the beginning of a `Describe` or `Context` block (e.g., dot-sourcing the function under test) |
| `BeforeEach` | Setup before each `It` block (use sparingly) |
| `AfterAll` / `AfterEach` | Teardown (cleanup resources, restore state) |
| `Describe` | Groups tests for a single function or script |
| `Context` | Groups tests for a specific scenario or condition |
| `It` | Defines an individual test case |
| `Should` | Assertion cmdlet for validating expected outcomes |

**Key Pester 5.x Changes:**

- Use `BeforeAll` for dot-sourcing scripts (not at the file level outside blocks)
- Discovery and Run phases are separate—code at the top level runs during discovery
- Code **MUST** use `Should -Be`, `Should -BeExactly`, `Should -BeNullOrEmpty`, etc. (not legacy `Assert-*` patterns)

---

### Test File Dot-Sourcing Pattern

Pester test files that dot-source scripts under test in `BeforeAll` **MUST** use the `Split-Path` + `Join-Path` two-step pattern. This pattern resolves the parent directory of the test file's directory and then builds the path to the source file:

```powershell
BeforeAll {
    $strSrcPath = Join-Path -Path (Split-Path -Path $PSScriptRoot -Parent) -ChildPath 'src'
    . (Join-Path -Path $strSrcPath -ChildPath 'FunctionName.ps1')
}
```

**Why this pattern is required:**

- Multi-segment `Join-Path` forms such as `Join-Path $PSScriptRoot '..' 'src' 'FunctionName.ps1'` rely on the `-AdditionalChildPath` parameter, which was introduced in PowerShell 6.0 and is **not available** in Windows PowerShell 5.1. Test files **MUST NOT** use this form.
- For consistency and canonical style in test files, `$PSScriptRoot`-anchored `..` path forms such as `$PSScriptRoot/../src/...` or `Join-Path -Path $PSScriptRoot -ChildPath '../src/...'` **MUST NOT** be used; use the explicit parent-resolution pattern instead.

---

### Test Structure: Arrange-Act-Assert

Tests **SHOULD** follow the **Arrange-Act-Assert (AAA)** pattern for clarity and maintainability:

1. **Arrange:** Set up test data, preconditions, and inputs
2. **Act:** Execute the function or script under test
3. **Assert:** Verify the output matches expectations

Each `It` block **SHOULD** test **one specific behavior**. Use comments to delineate the AAA sections for readability.

**Example:**

```powershell
It "Returns success code 0 when given valid input" {
    # Arrange
    $refResult = $null
    $strInput = "valid-input"

    # Act
    $intReturnCode = Get-ProcessedData -ReferenceToResult ([ref]$refResult) -InputString $strInput

    # Assert
    $intReturnCode | Should -Be 0
}
```

---

### Defensive Assertions Before Iteration and Indexing

#### Why `foreach` over `$null` or an empty collection is a silent-pass risk

In PowerShell, `foreach ($x in $null) { ... }` and `foreach ($x in @()) { ... }` both execute zero loop iterations. When a Pester `It` block places all of its `Should` assertions inside such a `foreach`, a bug that causes the function under test to return `$null` or an empty array will not trigger any assertion failure—the test silently passes with zero evaluated assertions. This is one of the most dangerous patterns in Pester tests because it gives a green test result for fundamentally broken code. A single `Should -Not -BeNullOrEmpty` assertion before the loop converts that silent pass into an immediate, descriptive failure.

#### Why a direct Pester assertion is more actionable than a runtime indexing error

When a test accesses `$arrResult[0]` without first asserting the collection count, a `$null` or empty result produces a runtime error such as *"Cannot index into a null array"* rather than a structured Pester failure. This runtime error obscures the root cause—the function returned unexpected output—behind an implementation detail of the test itself. A pre-index `$arrResult.Count | Should -Be <N>` assertion produces a clear Pester message like *"Expected 1, but got 0"*, immediately signaling that the function's output contract was violated, not the test code.

#### Why outer-collection and nested-property assertions protect different failure modes

An outer assertion like `$arrResult.Count | Should -Be 1` confirms that the top-level collection has the expected number of elements, but it says nothing about the structure of each element. A nested assertion like `$arrResult[0].Principals | Should -Not -BeNullOrEmpty` confirms that a specific property within that element is populated. These guard against different regression scenarios: one where the function returns too few (or too many) top-level results, and another where the function returns the right number of results but with missing or empty nested data. Both assertions are needed to fully protect subsequent indexed access into the nested property.

#### How pre-assertions strengthen Arrange-Act-Assert

The Arrange-Act-Assert pattern structures a test into setup, execution, and verification phases. Defensive pre-assertions fit naturally at the beginning of the Assert phase as *structural guards* that validate the shape and size of the result before the test proceeds to verify specific values. This layered approach ensures that each assertion failure maps to a single, unambiguous cause: a structural guard failure means the output contract was violated at a structural level, while a value assertion failure means the structure was correct but a specific value was wrong. Without these guards, a single failure can be ambiguous—did the function return the wrong value, or did it return nothing at all?

When a test iterates or indexes into a collection returned by the function or script under test, the test **MUST** include defensive pre-assertions so that an empty or `$null` result produces a clear, immediate Pester failure instead of silently passing or generating a confusing runtime error.

1. **Pre-iteration non-emptiness.** Tests that iterate a collection with `foreach ($x in $collection) { ... }` **MUST** assert `$collection | Should -Not -BeNullOrEmpty` before the `foreach`. A `foreach` over `$null` or an empty collection executes zero iterations, causing all inner assertions to be silently skipped.

2. **Pre-index count assertion.** Tests that access specific indices of a returned collection (e.g., `$arrResult[0]`) **MUST** assert `$arrResult.Count | Should -Be <N>` before any indexed access when the exact count is part of the contract being tested. If exact count is not part of the contract, the test **MUST** assert a minimum-count condition that covers the highest index accessed—for example, `Should -BeGreaterThan <highest-index-accessed>` (since collections are zero-based, `$arr.Count | Should -BeGreaterThan 2` guarantees that `$arr[0]`, `$arr[1]`, and `$arr[2]` are safe to access).

3. **Pre-index non-empty on nested properties.** When a test indexes into a property of a returned element (e.g., `$arrResult[0].Principals[0]`), the test **MUST** also assert `$arrResult[0].Principals | Should -Not -BeNullOrEmpty` before the inner index.

4. **Ordering.** For a test that accesses `$arr[i].Prop[j]`, assertions **SHOULD** follow this order:
   1. `$arr | Should -Not -BeNullOrEmpty` or `$arr.Count | Should -Be <N>`
   2. `$arr[i].Prop | Should -Not -BeNullOrEmpty`
   3. Strong-type check on `$arr[i].Prop`, if applicable
   4. Assertions that verify the actual behavior under test

**Compliant** (`foreach` — assert non-emptiness before iterating):

```powershell
It "Each ClusterActions entry includes a Principals array" {
    # Assert
    $script:objResult.ClusterActions | Should -Not -BeNullOrEmpty
    foreach ($objCluster in $script:objResult.ClusterActions) {
        $objCluster.PSObject.Properties.Name | Should -Contain 'Principals'
        $objCluster.Principals | Should -Not -BeNullOrEmpty
        ($objCluster.Principals -is [string[]]) | Should -BeTrue
    }
}
```

**Non-Compliant** (`foreach` — missing non-emptiness assertion):

```powershell
# Non-Compliant: foreach over $null or an empty collection can execute zero
# iterations and leave the test without any evaluated inner assertions.
It "Each ClusterActions entry includes a Principals array" {
    # Assert
    foreach ($objCluster in $script:objResult.ClusterActions) {
        $objCluster.PSObject.Properties.Name | Should -Contain 'Principals'
    }
}
```

**Compliant** (indexed access — count and nested non-emptiness before indexing):

```powershell
# Assert
$arrResult.Count | Should -Be 1
$arrResult[0].Principals | Should -Not -BeNullOrEmpty
$arrResult[0].Principals.Count | Should -Be 2
$arrResult[0].Principals[0] | Should -Be 'userA'
$arrResult[0].Principals[1] | Should -Be 'userB'
```

**Non-Compliant** (indexed access — no count assertion before `[0]`):

```powershell
# Non-Compliant: no count assertion before [0].
# Assert
$arrResult[0].Principals.Count | Should -Be 1
$arrResult[0].Principals[0] | Should -Be 'userA'
```

---

### Asserting Successful Execution With Should -Not -Throw

#### Why `try/catch` plus negated assertions on exception text is a silent-pass risk

A success-case test that wraps the call in `try { ... } catch { $e = $_ }` and then asserts only `$e.Exception.Message | Should -Not -Match '<pattern>'` is structurally fragile. The test passes under two very different conditions: (1) the call did not throw at all (the intended success path), and (2) the call threw for some unrelated reason and the exception message simply did not contain the negated pattern. Case (2) is a false positive: the function under test failed, but the test reports green. Worse, as the implementation evolves, the exception text can change for reasons wholly unrelated to the behavior being tested—error messages are rephrased, wrapping exceptions are added or removed, localization is introduced—and none of those changes would cause the negated assertion to fail. The test becomes a permanent green light that cannot distinguish success from a broad class of unrelated failures.

#### Why `{ ... } | Should -Not -Throw` is the correct pattern for asserting success

`Should -Not -Throw` evaluates the script block and fails the test on **any** exception, regardless of type, message, or origin. This is exactly the semantics required of a success-case assertion: "the call completed without throwing." There is no pattern to maintain, no message text that can drift, and no silent-pass path. A regression that introduces any new exception—expected or not, related or not—immediately produces a descriptive Pester failure that names the thrown exception, making the root cause easy to diagnose. The idiom is also self-documenting: a reader sees the script block and `Should -Not -Throw` and immediately understands that the assertion under test is "this does not throw."

#### Why expected-failure tests are different and must use positive assertions

Tests that verify a *specific expected failure* are the inverse problem: their purpose is to confirm that a particular exception condition is reached. These tests legitimately need to inspect exception details, but their follow-up assertions on the captured exception **MUST** fail when the expected exception is absent or different. `Should -Throw -ExpectedMessage '<pattern>'` fails both when no exception is thrown and when an exception is thrown whose message does not match the pattern—both are defects. Capturing the exception in a `catch` block and then asserting `$e.Exception.Message | Should -Match '<pattern>'` is similarly safe, because `$e` is `$null` when no exception was thrown and the `-Match` assertion fails on `$null`. The failure mode that must be avoided is a negated assertion against exception **text** (`Should -Not -Match`, `Should -Not -Be` against `$e.Exception.Message`) used as the *only* check, because any input that makes the negated predicate true—including the absence of any exception at all, or an exception with a totally unrelated message—counts as a pass. A presence-guard assertion such as `$e | Should -Not -BeNullOrEmpty` against the captured `ErrorRecord` itself is not subject to this failure mode: it fails precisely when `$e` is `$null`, which is the "expected exception absent" case, and is therefore explicitly permitted — and recommended — as a structural guard before dereferencing `$e.Exception`.

#### How to capture the thrown exception for follow-up assertions

`Should -Throw` on its own does not implicitly expose the thrown exception to subsequent statements, so any follow-up assertion against the exception needs an explicit capture mechanism. Pester 5 supports two idioms. The first is `Should -Throw -PassThru`, which evaluates the script block, asserts that it throws, and returns the thrown `ErrorRecord` as its output so it can be assigned to a variable and inspected—for example, `$errorRecord = { ... } | Should -Throw -PassThru; $errorRecord.Exception.Message | Should -Match '<pattern>'`. The second is the classic `try { ... } catch { $e = $_ }` pattern, in which the caught `$_` is an `ErrorRecord` whose `Exception` property exposes the same detail; a presence-guard assertion such as `$e | Should -Not -BeNullOrEmpty` followed by `$e.Exception.Message | Should -Match '<pattern>'` is safe because both assertions fail when `$e` is `$null`. Both idioms are acceptable; the critical constraint is that the follow-up assertions on the captured exception fail when the expected exception is absent or different. Assertions that satisfy this constraint include both positive predicates on exception detail (`Should -Match`, `Should -Be`, `Should -BeOfType`, etc.) and the presence guard `Should -Not -BeNullOrEmpty` against the captured `ErrorRecord` itself — despite using `-Not`, the presence guard fails precisely in the absent-exception case and is therefore consistent with (and complementary to) the rule. What **MUST NOT** be used as the sole follow-up check is a negated predicate against exception **text** (e.g., `$e.Exception.Message | Should -Not -Match '<pattern>'`), because that assertion is silently satisfied by any exception whose message does not match — including unrelated exceptions and the absence of an exception altogether.

#### Motivating case

This rule was added in response to a review thread on [franklesniak/PSStyleGuide#37](https://github.com/franklesniak/PSStyleGuide/pull/37) (review comment `r3121685195`), which surfaced Pester success-case tests written as `try/catch` with `Should -Not -Match` assertions on `$e.Exception.Message`. In that context, a regression that caused the function under test to throw an unrelated exception would still have produced a green test result, because the negated message assertion was satisfied by any message that did not happen to contain the forbidden substring. Codifying the `{ ... } | Should -Not -Throw` requirement prevents that silent-pass class of test from recurring.

When a Pester test's purpose is to assert that a call **succeeds** — that is, completes without throwing — the test **MUST** wrap the invocation in a script block and assert it with `Should -Not -Throw`. Such tests **MUST NOT** use `try { ... } catch { $e = $_ }` followed only by negated assertions against exception text (for example, `Should -Not -Match`) as the mechanism for proving success. Negated assertions on exception text silently pass when an unrelated exception is thrown whose message does not happen to match the negated pattern, producing a green result for fundamentally broken code.

Tests whose purpose is to assert a **specific expected failure** **MAY** inspect exception details, but follow-up assertions on the captured exception **MUST** fail when the expected exception is absent or different — for example, `Should -Throw -ExpectedMessage '<pattern>'`, or `Should -Throw -PassThru` (which returns the thrown `ErrorRecord`) or an explicit `try { ... } catch { $e = $_ }` to capture the exception, followed by assertions such as `Should -Match` or `Should -Be` against the captured object. A presence guard that fails when no exception was captured — specifically `$e | Should -Not -BeNullOrEmpty` immediately after a `try/catch` capture — **IS** permitted (and **SHOULD** be used before dereferencing `$e.Exception`) because it fails when `$e` is `$null`, which is the "expected exception absent" case. `Should -Throw` without `-PassThru` does **not** implicitly expose the thrown exception; a capture mechanism is required before any follow-up assertion. Negated assertions against exception **text** (for example, `$e.Exception.Message | Should -Not -Match '<pattern>'`) **MUST NOT** be used as the sole mechanism for validating either success or expected failure, because any exception whose message does not match the negated pattern — including an unrelated exception — will silently satisfy the assertion.

**Compliant** (success assertion — `Should -Not -Throw` fails on any exception):

```powershell
It "Completes without throwing for valid input" {
    # Arrange
    $strInput = 'valid-data'

    # Act / Assert
    { Convert-StringToObject -StringToConvert $strInput } | Should -Not -Throw
}
```

**Non-Compliant** (success assertion — `try/catch` plus negated message assertion can pass on an unrelated failure):

```powershell
# Non-Compliant: if the function throws for an unrelated reason whose message
# does not contain 'invalid', the negated -Not -Match assertion still passes
# and the test reports success even though the call failed.
It "Completes without throwing for valid input" {
    # Arrange
    $strInput = 'valid-data'
    $e = $null

    # Act
    try {
        Convert-StringToObject -StringToConvert $strInput
    } catch {
        $e = $_
    }

    # Assert
    $e.Exception.Message | Should -Not -Match 'invalid'
}
```

**Compliant** (expected-failure assertion — capture with `-PassThru` and assert positively):

```powershell
It "Throws a specific error for invalid input" {
    # Arrange
    $strInput = 'bad-data'

    # Act
    $errorRecord = { Convert-StringToObject -StringToConvert $strInput } |
        Should -Throw -PassThru

    # Assert
    $errorRecord.Exception.Message | Should -Match 'invalid'
}
```

**Compliant** (expected-failure assertion — capture with `try/catch` and assert positively):

```powershell
It "Throws a specific error for invalid input" {
    # Arrange
    $strInput = 'bad-data'
    $e = $null

    # Act
    try {
        Convert-StringToObject -StringToConvert $strInput
    } catch {
        $e = $_
    }

    # Assert — positive assertion fails when $e is $null (no exception thrown)
    $e | Should -Not -BeNullOrEmpty
    $e.Exception.Message | Should -Match 'invalid'
}
```

---

### Testing Return Code Conventions

For functions and scripts that use explicit integer status codes, tests **MUST** verify the return code conventions documented in [Return Semantics: Explicit Status Codes](#return-semantics-explicit-status-codes).

> **Note for functions and scripts that return objects:** If a function or script returns `[pscustomobject]` or other structured data instead of integer status codes, this section does not apply. For such cases, output contract verification — including edge cases such as `$null` returns — SHOULD be covered by Pester tests in accordance with [Testing with Pester](#testing-with-pester), where applicable.

#### Functions Returning Integer Status Codes

For functions that return integer status codes (`0` = success, `1-5` = partial success, `-1` = failure), tests **MUST** cover:

| Return Code | Test Requirement |
| --- | --- |
| `0` | At least one test verifying success case |
| `1-5` | At least one test for partial success cases (if applicable to the function) |
| `-1` | At least one test verifying failure case |

Additionally, if the function uses `[ref]` parameters for output:

- Tests **MUST** verify the reference parameter is populated correctly on success
- Tests **MUST** verify the reference parameter state on failure (typically `$null` or unchanged)

**Example for Integer Status Code Function:**

```powershell
Describe "Convert-StringToObject" {
    BeforeAll {
        $strSrcPath = Join-Path -Path (Split-Path -Path $PSScriptRoot -Parent) -ChildPath 'src'
        . (Join-Path -Path $strSrcPath -ChildPath 'Convert-StringToObject.ps1')
    }

    Context "When given valid input" {
        It "Returns 0 for success" {
            # Arrange
            $refResult = $null
            $strInput = "valid-data"

            # Act
            $intReturnCode = Convert-StringToObject -ReferenceToResult ([ref]$refResult) -StringToConvert $strInput

            # Assert
            $intReturnCode | Should -Be 0
        }

        It "Populates the reference parameter with the converted object" {
            # Arrange
            $refResult = $null
            $strInput = "valid-data"

            # Act
            [void](Convert-StringToObject -ReferenceToResult ([ref]$refResult) -StringToConvert $strInput)

            # Assert
            $refResult | Should -Not -BeNullOrEmpty
        }
    }

    Context "When given invalid input" {
        It "Returns -1 for failure" {
            # Arrange
            $refResult = $null
            $strInput = ""

            # Act
            $intReturnCode = Convert-StringToObject -ReferenceToResult ([ref]$refResult) -StringToConvert $strInput

            # Assert
            $intReturnCode | Should -Be -1
        }
    }
}
```

#### Test-* Functions Returning Boolean

For `Test-*` functions that return Boolean values (as documented in the exception for Test-* functions), tests **MUST** verify:

- A case that returns `$true`
- A case that returns `$false`

**Example for Boolean Test Function:**

```powershell
Describe "Test-PathExists" {
    BeforeAll {
        $strSrcPath = Join-Path -Path (Split-Path -Path $PSScriptRoot -Parent) -ChildPath 'src'
        . (Join-Path -Path $strSrcPath -ChildPath 'Test-PathExists.ps1')
    }

    Context "When the path exists" {
        It "Returns true" {
            # Arrange
            $strPath = $env:TEMP  # Known to exist

            # Act
            $boolResult = Test-PathExists -Path $strPath

            # Assert
            $boolResult | Should -BeTrue
        }
    }

    Context "When the path does not exist" {
        It "Returns false" {
            # Arrange
            $strPath = "C:\NonExistent\Path\That\Does\Not\Exist"

            # Act
            $boolResult = Test-PathExists -Path $strPath

            # Assert
            $boolResult | Should -BeFalse
        }
    }
}
```

---

### Testing Property Names on PSCustomObject

When testing that a `[pscustomobject]` contains the expected property names, assertions **MUST** use an **order-insensitive** comparison. Although `PSObject.Properties.Name` preserves declaration order in practice for objects created via the `[pscustomobject]` type accelerator with a hashtable literal, this ordering is not a documented guarantee. Tests **SHOULD NOT** rely on property ordering because:

1. Future refactors might change the property declaration order.
2. Objects constructed via `Add-Member` or other mechanisms may not preserve insertion order.
3. Order-insensitive tests are more resilient and communicate intent more clearly.

**Per-property containment** (preferred when property count is small):

```powershell
$objResult.PSObject.Properties.Name | Should -Contain 'Key'
$objResult.PSObject.Properties.Name | Should -Contain 'Type'
$objResult.PSObject.Properties.Name | Should -HaveCount 2
```

**Sorted array comparison** (acceptable alternative — the expected array must be in sorted order to match the `Sort-Object` output):

```powershell
($objResult.PSObject.Properties.Name | Sort-Object) |
    Should -Be @('Key', 'Type')
```

**Non-Compliant** (order-sensitive — fragile):

```powershell
# Non-Compliant
$objResult.PSObject.Properties.Name | Should -Be @('Key', 'Type')
```

---

### Testing Strongly-Typed Array Properties

#### Why `Should -Not -BeNullOrEmpty` before `.Count`

When a property is `$null` or an empty array, `$obj.Prop.Count | Should -BeGreaterThan 0` can produce the same generic failure message—such as *"Expected the actual value to be greater than 0, but got 0"*—because in PowerShell `$null.Count` also evaluates to `0`. In contrast, `$obj.Prop | Should -Not -BeNullOrEmpty` immediately communicates that the value was null or empty, giving the developer a much clearer signal about what went wrong. Testing non-emptiness first also guards subsequent assertions—such as type checks—from operating on a `$null` value that would produce misleading results.

#### Why permitting `[object[]]` weakens the test

When production code intentionally casts a property to a strongly-typed array like `[string[]]`, the test exists to ensure that cast is preserved. If a future refactor accidentally removes the cast, the property silently degrades to `[object[]]`—PowerShell's default array type. A disjunction such as `($x -is [string[]]) -or ($x -is [object[]])` will still pass in that scenario, defeating the purpose of the assertion. By requiring the exact type match (`-is [string[]]` alone), the test catches the regression immediately.

#### Why `Should -BeOfType [string[]]` is discouraged for array-type assertions

Pester's `-BeOfType` assertion receives its input through the PowerShell pipeline. When an array is piped (`$x | Should -BeOfType [string[]]`), PowerShell unrolls the array and sends each element individually to `Should`. Pester then evaluates `-BeOfType` against each *element*, not against the *array itself*. This means the assertion tests whether each string is of type `[string[]]`—which it is not—and the test fails even when the property is correctly typed.

A workaround exists: the unary comma operator (`, $x | Should -BeOfType [string[]]`) wraps the array in a single-element wrapper array so that the original array survives pipeline unrolling as a single object. However, this idiom is obscure and error-prone; contributors unfamiliar with the trick may remove the comma or misunderstand the intent. The `-is` operator pattern (`($x -is [string[]]) | Should -BeTrue`) avoids pipeline unrolling entirely, is self-documenting, and is consistent across all array-type assertions.

When asserting that a property on a returned object is a non-empty, strongly-typed array, tests **MUST** follow these rules:

1. **Non-emptiness first.** Tests **MUST** use `Should -Not -BeNullOrEmpty` before any `.Count`-based assertion. This produces a clear failure message when the property is `$null` or empty, rather than a confusing "expected greater than 0" when the property is `$null`.

2. **Strongly-typed assertion.** When production code explicitly casts an output property to a strongly-typed array (e.g., `[string[]]`), tests **MUST** assert that exact array type using the `-is` operator wrapped in `Should -BeTrue`:

   ```powershell
   ($obj.Prop -is [string[]]) | Should -BeTrue
   ```

   Tests **MUST NOT** use a disjunction that also permits `[object[]]`, because that masks regressions when the intended production cast is accidentally removed.

3. **Avoid `Should -BeOfType [string[]]` for array types.** Tests **SHOULD NOT** use `$x | Should -BeOfType [string[]]` to assert array type, because the pipeline unrolls the array before Pester evaluates the type. Prefer the `-is [string[]]` pattern.

4. **Ordering.** When combined with a property-name check, the recommended assertion order **SHOULD** be: property name first, then non-empty assertion, then strongly-typed assertion.

**Compliant** (preferred pattern):

```powershell
$script:objResult.ClusterActions | Should -Not -BeNullOrEmpty
foreach ($objCluster in $script:objResult.ClusterActions) {
    $objCluster.PSObject.Properties.Name | Should -Contain 'Principals'
    $objCluster.Principals | Should -Not -BeNullOrEmpty
    ($objCluster.Principals -is [string[]]) | Should -BeTrue
}
```

**Non-Compliant** (too permissive):

```powershell
# Non-Compliant: [object[]] disjunction masks regressions in the
# production strongly-typed cast.
(($objCluster.Principals -is [string[]]) -or ($objCluster.Principals -is [object[]])) |
    Should -BeTrue

# Non-Compliant: .Count on a potentially-null value is asserted before
# proving the property is non-empty.
$objCluster.Principals.Count | Should -BeGreaterThan 0
```

**Non-Compliant** (pipeline unrolling):

```powershell
# Non-Compliant: the array is unrolled before Pester evaluates the type assertion.
$objCluster.Principals | Should -BeOfType [string[]]
```

---

### Mocking External Dependencies

Use Pester's `Mock` command to isolate the function under test from external dependencies:

```powershell
Context "When external service is unavailable" {
    BeforeAll {
        Mock Get-ExternalData { throw "Connection failed" }
    }

    It "Returns failure code -1 and does not throw" {
        # Arrange
        $refResult = $null

        # Act
        $intReturnCode = Process-ExternalData -ReferenceToResult ([ref]$refResult)

        # Assert
        $intReturnCode | Should -Be -1
    }
}
```

**Mocking Guidelines:**

- Mock cmdlets and external commands that introduce dependencies (network, file system, cloud services)
- Mock at the narrowest scope possible (prefer `Context`-level mocks over `Describe`-level)
- Use `Assert-MockCalled` to verify expected interactions when appropriate

---

### PSScriptAnalyzer CI Diagnostic Output

`Invoke-ScriptAnalyzer` returns `DiagnosticRecord` objects by default; it does not provide a built-in switch that emits GitHub Actions workflow annotations or Azure Pipelines logged issues. `-EnableExit` controls exit behavior, but translation from analyzer records to CI diagnostics belongs to the integration that writes the log commands. Those records include fields such as `ScriptPath` and severity values such as `Information`, `Warning`, `Error`, and `ParseError`, so the integration has enough structured data to format host-specific output deliberately.

GitHub Actions and Azure Pipelines consume different log command syntaxes. GitHub Actions workflow commands use forms such as `::notice`, `::warning`, and `::error` with comma-delimited properties and message data after `::`. Azure Pipelines logging commands use `##vso[task.logissue ...]` with semicolon-delimited properties. A command string that is valid for one host is ordinary log text to the other, so the selected syntax must follow the active host rather than a generic "CI" assumption.

Host detection should be explicit and conservative. GitHub Actions can be identified with `GITHUB_ACTIONS=true`, and path translation often also needs `GITHUB_WORKSPACE`. Azure Pipelines can be identified with `TF_BUILD=True` and/or Azure Pipelines `SYSTEM_*` variables. If these signals are missing, ambiguous, or contradictory, plain PSScriptAnalyzer output is the safest result because it preserves the finding without pretending to create host-native annotations.

Dynamic command fields must be escaped according to the selected host syntax before the command is written. GitHub Actions workflow-command properties and message data use percent-encoding rules such as `%25`, `%0D`, `%0A`, `%3A`, and `%2C` in the relevant command fields. Azure Pipelines logging commands use a different escaping contract, including `%AZP25`, `%0A`, `%0D`, `%3B`, and `%5D` for percent signs, newlines, carriage returns, semicolons, and closing brackets. Escaping must cover paths, line numbers, rule names, titles, and diagnostic messages because any one of those values can contain characters that corrupt the command.

File paths also need host-aware formatting. GitHub Actions workflow commands support a `file` property on `notice`, `warning`, and `error` commands, and GitHub examples use repository paths such as `app.js`. For GitHub Actions workflow commands, repository-relative paths are the safest portable form. Absolute paths under `GITHUB_WORKSPACE` may be normalized by the runner to workspace-relative paths, but paths outside the workspace should not be relied on for repository annotations. GitHub Checks API annotations use a required `path` value such as `assets/css/main.css`; this path should be repository-relative. Azure Pipelines logging-command guidance says file paths should be absolute, so `sourcepath` should be normalized to an absolute path before emitting `task.logissue`. PSScriptAnalyzer `DiagnosticRecord.ScriptPath` is the path of the analyzed file and may need translation before being emitted as a host-native diagnostic.

Severity mapping should be explicit. GitHub Actions can represent warnings and errors; informational findings can be notices if the integration intentionally supports that mapping. Azure Pipelines `task.logissue` supports `type=error` and `type=warning`, so informational findings should remain plain output or be included in summaries or artifacts. PSScriptAnalyzer `ParseError` should map to an error or failure diagnostic.

GitHub documents multiple annotation surfaces with different limits. Problem matchers document GitHub Actions display limits of 10 warning, 10 error, and 10 notice annotations per step, 50 annotations per job, and 50 annotations per run. The Checks API accepts a maximum of 50 annotations per API request and separately notes GitHub Actions warning/error per-step limits. Because analyzer output can exceed these display surfaces, annotations should complement plain output, summaries, or artifacts rather than replace them.

When a PSScriptAnalyzer CI integration emits host-native diagnostics in addition to or instead of plain analyzer output, it **MUST** use the command format for the active CI host. GitHub Actions annotations **MUST** use GitHub Actions workflow commands such as `::warning file=...,line=...::...` or `::error file=...,line=...::...`. Azure Pipelines issues **MUST** use Azure Pipelines logging commands such as `##vso[task.logissue type=warning;sourcepath=...;linenumber=...]...` or `##vso[task.logissue type=error;sourcepath=...;linenumber=...]...`. These command syntaxes **MUST NOT** be interchanged.

When a command string includes dynamic values such as file paths, line numbers, rule names, messages, or titles, those values **MUST** be formatted, escaped, or encoded according to the active host's command syntax before they are written to the log. File paths **SHOULD** be emitted in the form the active host expects so that diagnostics resolve to the correct file.

Host-neutral, local, and interactive runs **SHOULD** use plain PSScriptAnalyzer output unless the active CI host is explicitly known. If host detection is ambiguous, missing, or contradictory, the integration **MUST** use plain PSScriptAnalyzer output and **MUST NOT** emit host-native diagnostic commands.

---

### Running Pester Tests

**Basic invocation:**

```powershell
Invoke-Pester -Path tests/
```

**Detailed output:**

```powershell
Invoke-Pester -Path tests/ -Output Detailed
```

**Single test file:**

```powershell
Invoke-Pester -Path tests/Get-UserInfo.Tests.ps1
```

**With configuration object (for CI/CD scenarios):**

```powershell
$objPesterConfig = New-PesterConfiguration
$objPesterConfig.Run.Path = 'tests/'
$objPesterConfig.Output.Verbosity = 'Detailed'
$objPesterConfig.TestResult.Enabled = $true
$objPesterConfig.TestResult.OutputPath = 'test-results.xml'
Invoke-Pester -Configuration $objPesterConfig
```

#### Why CI Pester discovery must be scoped to the project test root

A CI workflow that discovers tests from the repository root can produce a misleading green result by finding tests the project does not actually own. For example, a repository can contain `samples/template/Example.Tests.ps1` from a starter project while the real `tests/` directory is missing. A root scan such as `Get-ChildItem -Path . -Filter '*.Tests.ps1' -Recurse` will find and execute the sample test, so CI reports that Pester passed even though the project's real test suite is absent.

Scoping discovery to `tests/` or to the project's documented test root converts that situation into the intended signal: either the owned tests run, or the workflow reports that no owned Pester tests were found. It also prevents vendored modules, dependencies, scaffolding, and examples from changing the test surface area behind the project's back.

#### Why discovery and execution need a single test-root source of truth

Pester discovery and Pester execution are two halves of one contract. If discovery scans `tests/` but the Pester configuration `Run.Path` later points at `.`, the workflow's preflight output no longer describes what Pester actually runs. The inverse is also risky: discovery can say test files exist in one directory while execution runs a narrower or entirely different directory and silently skips the files that justified the step.

A single source of truth, such as `PESTER_TEST_ROOT`, keeps the workflow honest. The same value defines what "this project's tests" means for both the preflight check and the Pester configuration, so a later path change is made once instead of being duplicated across separate script fragments.

#### Why missing test roots should skip cleanly

Downstream consumers often adopt a style guide or reusable workflow before they have created PowerShell tests. Some projects intentionally remove a `tests/` directory during early scaffolding, documentation-only work, or staged migrations. In those cases, a hard workflow failure from `Get-ChildItem` is mostly noise: it says the directory is absent, not that the code failed a test.

A `Test-Path -LiteralPath ... -PathType Container` guard lets the workflow produce a clear "no test files" skip when the directory is absent. Restricting the guard to `Container` keeps the skip scoped to "the test root is a missing directory" — a bare `Test-Path` would also succeed when the configured path happens to resolve to a file (for example a mis-set `PESTER_TEST_ROOT` env var), silently converting a real misconfiguration into a clean skip. That keeps CI output actionable while still making the absence of owned Pester tests visible to maintainers. `Get-ChildItem` with `-ErrorAction SilentlyContinue` is an alternative shape, but it is not equivalent: `SilentlyContinue` will also suppress non-existence-related errors such as permission or IO failures, converting genuine CI problems into a silent "no tests" skip. Preferring `Test-Path` followed by `Get-ChildItem` without `-ErrorAction SilentlyContinue` keeps the skip narrowly scoped to "directory is missing," while still surfacing real enumeration failures as workflow errors.

For local developer runs, use the documented project test root directly:

```powershell
Invoke-Pester -Path tests/ -Output Detailed
```

CI workflow runs often need a PowerShell `run:` step that performs both test discovery and Pester execution. In those steps, CI Pester discovery (`Get-ChildItem ... -Filter '*.Tests.ps1' -Recurse`) and execution (the Pester configuration `Run.Path`) **MUST** be scoped to the project-owned `tests/` tree or to the project's documented test root. They **MUST NOT** scan from the repository root, because root-level scanning can sweep up unrelated tests, including starter, sample, template, vendored, or dependency `*.Tests.ps1` files, and produce a misleading green test signal.

The Pester configuration `Run.Path` value and the discovery step's path **MUST** be derived from a single source of truth, such as a workflow-level `env:` value like `PESTER_TEST_ROOT`, so the discovery scope and execution scope cannot drift apart.

The discovery step **SHOULD** guard against a missing test root using `Test-Path -LiteralPath ... -PathType Container` so projects that have not yet created or have intentionally removed the `tests/` directory still see a clean "no test files" skip rather than a workflow error. Using `-PathType Container` keeps the skip scoped to "the test root is a missing directory"; a bare `Test-Path` would also succeed when the path resolves to a file (for example a mis-set `PESTER_TEST_ROOT`), masking a real misconfiguration as a clean skip. `Get-ChildItem ... -ErrorAction SilentlyContinue` **MAY** be used as an alternative, but it is **NOT** equivalent: `SilentlyContinue` also suppresses non-existence-related errors such as permission or IO failures, which can mask genuine CI problems as a clean skip. A `Test-Path` guard followed by `Get-ChildItem` without `-ErrorAction SilentlyContinue` is preferred.

**Compliant** (single env-var-driven test root for discovery and execution):

```yaml
- name: Run Pester tests
  shell: pwsh
  env:
    PESTER_TEST_ROOT: tests
  run: |
    $strPesterTestRoot = Join-Path -Path $env:GITHUB_WORKSPACE -ChildPath $env:PESTER_TEST_ROOT
    $arrPesterTestFiles = @()

    if (Test-Path -LiteralPath $strPesterTestRoot -PathType Container) {
        $arrPesterTestFiles = @(
            Get-ChildItem -LiteralPath $strPesterTestRoot -Filter '*.Tests.ps1' -Recurse -File
        )
    }

    if ($arrPesterTestFiles.Count -eq 0) {
        Write-Output ("No Pester test files found under '{0}'." -f $strPesterTestRoot)
        exit 0
    }

    $objPesterConfiguration = New-PesterConfiguration
    $objPesterConfiguration.Run.Path = $strPesterTestRoot
    $objPesterConfiguration.Output.Verbosity = 'Detailed'
    Invoke-Pester -Configuration $objPesterConfiguration
```

**Non-compliant** (repository-root discovery and execution):

```yaml
- name: Run Pester tests
  shell: pwsh
  run: |
    $arrPesterTestFiles = @(
        Get-ChildItem -Path . -Filter '*.Tests.ps1' -Recurse -File
    )

    if ($arrPesterTestFiles.Count -eq 0) {
        Write-Output "No Pester test files found."
        exit 0
    }

    $objPesterConfiguration = New-PesterConfiguration
    $objPesterConfiguration.Run.Path = '.'
    $objPesterConfiguration.Output.Verbosity = 'Detailed'
    Invoke-Pester -Configuration $objPesterConfiguration
```

## Performance, Security, and Other

### Executive Summary: Holistic Design Constraints

The author operates under **three immutable design pillars** that govern every decision in performance, security, and auxiliary behavior:

1. **v1.0 Compatibility** — the code **MUST** run on PowerShell 1.0 without modification when the script's nature allows (e.g., no modern dependencies)
2. **Deterministic Execution** — every path **MUST** produce identical, predictable results
3. **Zero Side Effects** — the function **MUST NOT** alter global state or emit uncontrolled output

These constraints create a **highly constrained optimization space** where performance, security, and maintainability are balanced against **absolute portability**. The result is a **lean, defensive, and self-documenting** implementation that sacrifices micro-optimizations for **macro-reliability**. In dependency-constrained scripts, these pillars adapt to include modern optimizations.

### Performance: Measured Pragmatism

The author adopts a **"measure, then optimize"** philosophy, but within v1.0 constraints, **measurement is limited**. No `Measure-Command` or profiling cmdlets exist in v1.0, so performance decisions are based on **algorithmic complexity analysis** and **known PowerShell behavioral characteristics**.

#### Key Performance Characteristics

| Operation | Complexity | Technical Rationale |
| --- | --- | --- |
| **String splitting** | O(n) | `[regex]::Split` with escaped delimiter — linear pass |
| **Type casting loop** | O(1) per attempt, bounded | Bounded by input segments |
| **Error detection** | O(1) | Reference comparison — no array scanning |
| **Version detection** | O(1) | Single `Test-Path variable:\PSVersionTable` |

**Total worst-case complexity**: **O(n)** where *n* is input string length.

#### Performance-Critical Paths

1. **Literal string splitting**

    Uses `[regex]::Escape()` + `[regex]::Split()` instead of `-split` operator
    **Reason**: `-split` is v2.0+; regex method is v1.0-compatible and **faster** for literal splits (no regex engine overhead for metacharacters)

2. **Conditional BigInteger usage**
    Only invoked when:

    - Numeric segment > `[int32]::MaxValue`
    - PowerShell version ≥ 3.0

    **Avoids** costly `BigInteger` allocation in v1.0/v2.0 environments

3. **Short-circuit processing**

   On first successful parse, **excess segments are stored** and processing halts

   Prevents unnecessary type conversion attempts

#### Performance Trade-offs

| Trade-off | Decision | Technical Justification |
| --- | --- | --- |
| **Script vs. Pipeline** | Script constructs (`foreach`) | Avoids pipeline overhead; v1.0 has no optimized pipeline |
| **Regex vs. String methods** | Regex for splitting | `[regex]::Escape()` ensures literal behavior; `String.Split()` has different empty-string semantics |
| **Early version detection** | Optional `$PSVersion` parameter | Caller can skip `Get-PSVersion` if known → saves one `Test-Path` |

**Conclusion**: Performance is **bounded, predictable, and appropriate** for typical use cases. No premature optimization occurs.

### Security: Defense-in-Depth by Design

The function processes **untrusted inputs** (e.g., from external sources). The security model is **input-agnostic and side-effect-free**.

#### Security Posture

| Threat Vector | Mitigation | Evidence |
| --- | --- | --- |
| **Injection via string** | Strong typing + safe casting | Type casts fail fast if malformed |
| **Path traversal** | No file system access | Function is pure computation |
| **Memory exhaustion** | Bounded input handling | Max fixed segments + excess string |
| **Information disclosure** | No `Write-Host` | Only Warning stream for anomalies |
| **Privilege escalation** | No external calls | Pure .NET type usage |

#### Secure-by-Default Patterns

1. **No file/registry access** → eliminates path-based attacks
2. **No `Invoke-Expression`** → prevents code injection
3. **No external processes** → no command execution
4. **All .NET interop is read-only** → `[regex]`, `[version]`, `[Numerics.BigInteger]`

#### Credential Handling (Inferred)

While not present, the author's pattern suggests future security handling would use:

```powershell
[Parameter()]
[PSCredential]$Credential
```

With **SecureString** and **never** clear-text storage.

**Design consideration**: The function is **security-neutral** — it neither introduces nor mitigates external risks, but **cannot be exploited** due to its isolated, pure-function design.

### Other: Maintainability, Extensibility, and Modernization

#### Maintainability: High Cohesion, Controlled Coupling

| Aspect | Implementation | Benefit |
| --- | --- | --- |
| **Single responsibility** | Targeted operations | Clear contract |
| **No global state mutation** | Only `$global:ErrorActionPreference` (restored) | Predictable |
| **Helper consolidation needed** | Duplicate error functions | **Action item**: nest in parent scope |
| **Versioned internally** | `.NOTES: Version: 1.0.20250218.0` | Change tracking |

#### Extensibility Points

| Extension | Method | v1.0 Compatibility |
| --- | --- | --- |
| **Custom number bases** | Add parameter `[int]$Base = 10` | Yes |
| **Strict mode** | Add switch `[switch]$Strict` | Yes |
| **Output object** | Return `[pscustomobject]` | No (requires v2.0+) |

#### Modernization Path (v2.0+)

If v1.0 compatibility were not required, the author would likely:

```powershell
[CmdletBinding()]
[OutputType([PSCustomObject])]
param(
    [string]$StringToProcess
)
process {
    [pscustomobject]@{
        Status = 0
        Result = $res
        Extras = $extras
    }
}
```

**Benefits**:

- Pipeline-friendly
- `Get-Help` integration
- `-Verbose`/`-Debug` support

**Trade-off**: Breaks v1.0 compatibility

### Summary: Performance, Security, and Holistic Design

The **Performance, Security, and Other** aspects reveal a **mature, constrained optimization**:

- **Performance**: Bounded, predictable, and **optimized within v1.0 limits** — no premature micro-optimizations, but **algorithmic efficiency** is excellent.
- **Security**: **Inherently safe** — pure function, no external interfaces, no data leakage. **Cannot be weaponized**.
- **Maintainability**: High, with **one actionable improvement** (consolidate duplicate helpers).
- **Extensibility**: Clear points for future enhancement.
- **Modernization**: Well-defined path to v2.0+ features **without breaking core contract**.

The function is a **minimal, maximalist** design: it does **exactly one thing**, does it **perfectly**, and **refuses to do anything else**. This is the hallmark of **industrial-grade PowerShell tooling** — code that can be deployed in 2006 or 2026 with identical behavior when compatible.

**Final Assessment**: **"Fit for purpose across 18 years of PowerShell evolution."**

### Prefer `-LiteralPath` Over `-Path` for Concrete Paths

#### Why `-Path` Is Dangerous for Concrete Paths

PowerShell's `-Path` parameter interprets wildcard characters (`*`, `?`, `[`, `]`) before resolving to the file system. This is by design—`-Path` supports glob patterns—but it creates a class of subtle, silent bugs when the path is a concrete value that happens to contain these characters:

| Character | Wildcard Meaning | Real-World Source |
| --- | --- | --- |
| `[` `]` | Character-range match | Valid in Windows file names: version tags (`[1.0]`), user-generated names, bracketed metadata |
| `*` | Zero-or-more-character match | Reserved in Windows file names; may appear via user-supplied input or on non-Windows filesystems |
| `?` | Single-character match | Reserved in Windows file names; may appear via user-supplied input or on non-Windows filesystems |

When `-Path` encounters these characters, it attempts wildcard resolution. If no file matches the pattern, the cmdlet may silently return nothing or fail with a misleading error. If multiple files match, the cmdlet operates on all of them—potentially deleting, moving, or overwriting files the code never intended to touch.

#### Variable-Derived Paths Are Especially Risky

Paths built from variables, `Join-Path` output, user input, environment variables, or API results are particularly dangerous with `-Path` because their content is not visible at authoring time. A path like `$strDownloadPath` might resolve to `C:\Users\name\Downloads\report[final].docx`—and `Remove-Item -Path $strDownloadPath` would interpret `[final]` as a character class, potentially matching (and deleting) the wrong files or failing silently.

#### Why `-LiteralPath` Is the Safe Default

`-LiteralPath` treats the entire string as a literal file-system path with no wildcard interpretation. It is semantically equivalent to "this exact path" and eliminates the entire class of wildcard-injection bugs. There is no performance cost to using `-LiteralPath`; it simply bypasses the wildcard-resolution step.

#### Destructive Operations Require Stronger Protection

For `Remove-Item` and `Move-Item`, the consequences of accidental wildcard expansion are **irreversible**—deleted files cannot be recovered (without backups), and moved files may overwrite existing targets. This is why the main guide elevates the rule from **SHOULD** to **MUST** for destructive cmdlets with variable-derived paths.

#### `New-Item` Exception

`New-Item` does not expose a `-LiteralPath` parameter in any released version of PowerShell (Windows PowerShell 5.1, PowerShell 7.x). Attempting `New-Item -LiteralPath` produces a `ParameterBindingException`. Because `New-Item` creates a new item rather than deleting, moving, or modifying existing file-system entries, the wildcard-injection risk is lower than for read or destructive cmdlets, but it is not eliminated: wildcard characters supplied to `-Path` can still match existing parent directories or items and cause creation in unintended or multiple locations. Use `New-Item -Path` when the path value is trusted or validated; for untrusted input that may contain wildcard characters (`[`, `]`, `*`, `?`) as literal characters, validate or reject the input, or use an appropriate .NET API (e.g., `[System.IO.File]::Create()`, `[System.IO.Directory]::CreateDirectory()`) when literal path semantics are required.

#### Wildcard-Safe Directory Creation With `[System.IO.Directory]::CreateDirectory()`

For directory creation specifically, `[System.IO.Directory]::CreateDirectory()` is the preferred .NET alternative when the path is variable-derived and may contain wildcard characters. Unlike `New-Item -Path ... -ItemType Directory`, `CreateDirectory()` does not interpret PowerShell wildcard characters (`[`, `]`, `*`, `?`) and therefore provides deterministic behavior regardless of what characters appear in the path.

The path must be resolved to an absolute filesystem path via `$ExecutionContext.SessionState.Path.GetUnresolvedProviderPathFromPSPath()` before being passed to `CreateDirectory()`, as documented in the "Resolving Paths for .NET Static Methods" rule. `GetUnresolvedProviderPathFromPSPath()` is particularly appropriate here because the target directory may not yet exist.

`CreateDirectory()` is also safe to call when the directory already exists—it returns the existing `DirectoryInfo` object without error—making a preceding `Test-Path -LiteralPath` check optional but useful for clarity. The compliant example in the main guide includes the `Test-Path` guard for readability.

For *file* creation with wildcard-safe semantics, the corresponding .NET API is `[System.IO.File]::Create()` or `[System.IO.StreamWriter]`, but that case is not covered by this rule. The directory-creation guidance is separated because it is the most common scenario where `New-Item -ItemType Directory` would otherwise be the idiomatic choice.

When a cmdlet supports both `-Path` and `-LiteralPath`, and the code is operating on a **single concrete path value**—not an intentionally wildcarded pattern—`-LiteralPath` **SHOULD** be used instead of `-Path`. This especially applies when the path is derived from variables, `Join-Path`, or string construction, because `-Path` interprets wildcard characters (`[`, `]`, `*`, `?`) and can silently match the wrong files or match nothing at all.

For **destructive** operations—`Remove-Item`, `Move-Item`—`-LiteralPath` **MUST** be used when the path value comes from a variable or expression. Wildcard interpretation of a variable-derived path in a destructive cmdlet can silently delete or move unintended files.

Reserve `-Path` for cases where wildcard expansion is **explicitly intended**.

**Exception — `New-Item`:** `New-Item` does **not** have a `-LiteralPath` parameter (across Windows PowerShell 5.1 and PowerShell 7.x). Use `New-Item -Path` for item creation. Because `-Path` still interprets wildcard characters, code **SHOULD** validate or reject untrusted input containing `[`, `]`, `*`, or `?` as literal characters, or use a .NET file API (e.g., `[System.IO.File]::Create()`) when literal path semantics are required.

**Directory creation:** When creating a directory from a variable-derived path that may contain wildcard characters (`[`, `]`, `*`, or `?`), code **SHOULD** prefer `[System.IO.Directory]::CreateDirectory()` over `New-Item -Path ... -ItemType Directory`. The path **MUST** first be resolved to an absolute filesystem path per [Resolving Paths for .NET Static Methods](#resolving-paths-for-net-static-methods).

**Compliant** (wildcard-safe directory creation):

```powershell
$strOutputPath = $ExecutionContext.SessionState.Path.GetUnresolvedProviderPathFromPSPath($OutputPath)
if (-not (Test-Path -LiteralPath $strOutputPath)) {
    [void]([System.IO.Directory]::CreateDirectory($strOutputPath))
}
```

**Common cmdlets where this rule applies:** `Copy-Item`, `Get-ChildItem`, `Get-Content`, `Get-Item`, `Move-Item`, `Remove-Item`, `Set-Content`, `Test-Path`.

**Compliant:**

```powershell
Test-Path -LiteralPath $strFilePath
Get-Content -LiteralPath $strConfigFile -ErrorAction Stop
Remove-Item -LiteralPath $strTempFile -Force
```

**Non-compliant** (variable-derived path with `-Path`):

```powershell
# Risk: $strFilePath may contain [] or wildcard characters
Test-Path -Path $strFilePath
Get-Content -Path $strConfigFile -ErrorAction Stop
Remove-Item -Path $strTempFile -Force   # Dangerous: destructive + wildcard
```

**Acceptable** (intentional wildcard):

```powershell
# Intentional wildcard — -Path is correct here:
Get-ChildItem -Path 'C:\Logs\*.log'
Remove-Item -Path 'C:\Temp\*.tmp' -Force
```