⚙️ [Maintenance]: PowerShell guidance scripts are centrally available (#508)

Maintainers can now find the published PowerShell guidance examples
alongside Process-PSModule, giving the framework a single maintained
home for the scripts that explain common implementation patterns.

## New: Published PowerShell guidance scripts

The repository now carries the complete current set of guidance scripts
for collections, strings, call stacks, pipeline execution, module
loading, file access, and web calls. The published documentation
includes the purpose of every script and links directly to the tracked
directory. These are reference examples; run an individual script only
when its scenario is appropriate for the local environment.

---
<details>
<summary>Technical details</summary>

-Imported the 14 current `guidance/` Git blobs from `PSModule/docs`
without changing their contents and verified every imported blob ID
against the source repository.
-Added a scoped `.gitattributes` rule so the imported source stays
LF-normalized in Git on Windows checkouts.
-Added the guidance-script reference page, Reference landing-page entry,
and site navigation entry. `guidance/` remains outside `src/` because
these scripts are framework reference assets, not Process-PSModule
module source; no manifest wiring is required.
-Implementation plan progress: source import and published
discoverability are complete.
-Issue convergence sweep: searched open guidance-related issues.
`#423` is related documentation-consolidation
context but is not fully satisfied by this import; no issue is closed.
-Strict documentation validation exposes 28 pre-existing migrated-link
warnings outside this diff; the normal build generates the new guidance
page successfully. The bounded follow-up is
`#509`.

| Changed surface | Standards checked | Framework docs checked | Result
|
| --- | --- | --- | --- |
| `guidance/**` (PowerShell) | PowerShell syntax parsing, source
fidelity | Repository layout and module source layout | Aligned |
| `docs/content/**`, `docs/zensical.toml` | Markdown structure and
navigation | Documentation publishing | Aligned; strict baseline tracked
in #509 |
| `.gitattributes` | Repository text normalization | Repository standard
| Aligned |

</details>

<details>
<summary>Relevant issues (or links)</summary>

-No scoped delivery issue was provided; this import was requested
directly.
-#423
-#509

</details>

---------

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

Author: MariusStorhaug

.gitattributes

@@ -1,6 +1,9 @@
 # Needed for publishing of examples, build worker defaults to core.autocrlf=input.
 * text eol=autocrlf
 
+# Preserve the published guidance scripts' upstream LF representation.
+guidance/* text eol=lf
+
 *.mof   text eol=crlf
 *.sh    text eol=lf
 *.svg   eol=lf

docs/content/index.md

@@ -63,6 +63,7 @@ Look up the framework's exact contracts and the module-development standards it
 | [Scenario matrix](reference/scenario-matrix.md) | Which jobs run for each trigger scenario. |
 | [Framework test IDs](reference/framework-test-ids.md) | The framework tests enforced on source code and on the built module. |
 | [Dependencies](reference/dependencies.md) | The actions, modules, and services the workflow composes. |
+| [PowerShell guidance scripts](reference/guidance-scripts.md) | Runnable reference scripts for common PowerShell implementation patterns. |
 
 ## Specification
 

docs/content/reference/guidance-scripts.md

@@ -0,0 +1,31 @@
+---
+title: PowerShell guidance scripts
+description: Reference PowerShell scripts that demonstrate implementation patterns used by the PSModule framework.
+---
+
+# PowerShell guidance scripts
+
+The [guidance directory](https://github.com/PSModule/Process-PSModule/tree/main/guidance) contains runnable reference scripts for common PowerShell implementation patterns. They are framework learning assets, not Process-PSModule module source, so they are intentionally kept outside `src/` and are not included in a module manifest.
+
+Run an individual script only when its scenario is suitable for the local environment. Several scripts create temporary files, make web requests, or measure execution time.
+
+| Script | Focus |
+| --- | --- |
+| `Add-Array.ps1` | Array and generic list population |
+| `Add-HashTable.ps1` | Hashtable population styles |
+| `Add-String.ps1` | String construction approaches |
+| `Caller.ps1` | Caller discovery through the PowerShell call stack |
+| `ClassExtension.ps1` | Class inheritance and base-method invocation |
+| `Loops.ps1` | Loop and function-call overhead |
+| `Out-Null.ps1` | Discarding command output |
+| `PipelineExecution.ps1` | Pipeline parameter evaluation and lifecycle blocks |
+| `PSCallStack.ps1` | Nested-call stack inspection |
+| `PSCmdlet.ps1` | The `$PSCmdlet` variable at nested call levels |
+| `PSModuleTest.psm1` | Module-component import and exports |
+| `Read-File.ps1` | File-reading approaches |
+| `root.ps1` | Nested PSScriptAnalyzer binary-module loading |
+| `WebCalls.ps1` | Web-request protocol comparisons |
+
+## Maintenance
+
+The files were imported byte-for-byte from [`PSModule/docs/guidance`](https://github.com/PSModule/docs/tree/main/guidance). When that published set changes, import the complete current file from its Git blob into this directory and preserve its contents. Keep this index synchronized with the directory so users can discover every available script.

docs/zensical.toml

@@ -47,6 +47,7 @@ nav = [
     {"Scenario matrix" = "reference/scenario-matrix.md"},
     {"Framework test IDs" = "reference/framework-test-ids.md"},
     {"Dependencies" = "reference/dependencies.md"},
+    {"PowerShell guidance scripts" = "reference/guidance-scripts.md"},
   ]},
   {"Specification" = [
     "specification/index.md",

guidance/Add-Array.ps1

@@ -0,0 +1,50 @@
+$tests = @{
+    'PowerShell Explicit Assignment' = {
+        param($count)
+
+        $result = foreach ($i in 1..$count) {
+            $i
+        }
+        $null = $result # just added for linter issues
+    }
+    '.Add(..) to List<T>'            = {
+        param($count)
+
+        $result = [Collections.Generic.List[int]]::new()
+        foreach ($i in 1..$count) {
+            $result.Add($i)
+        }
+    }
+    '+= Operator to Array'           = {
+        param($count)
+
+        $result = @()
+        foreach ($i in 1..$count) {
+            $result += $i
+        }
+    }
+}
+
+5kb, 10kb, 100kb | ForEach-Object {
+    $groupResult = foreach ($test in $tests.GetEnumerator()) {
+        $ms = (Measure-Command { & $test.Value -Count $_ }).TotalMilliseconds
+
+        [pscustomobject]@{
+            CollectionSize    = $_
+            Test              = $test.Key
+            TotalMilliseconds = [math]::Round($ms, 2)
+        }
+
+        [GC]::Collect()
+        [GC]::WaitForPendingFinalizers()
+    }
+
+    $groupResult = $groupResult | Sort-Object TotalMilliseconds
+    $groupResult | Select-Object *, @{
+        Name       = 'RelativeSpeed'
+        Expression = {
+            $relativeSpeed = $_.TotalMilliseconds / $groupResult[0].TotalMilliseconds
+            [math]::Round($relativeSpeed, 2).ToString() + 'x'
+        }
+    }
+}

guidance/Add-HashTable.ps1

@@ -0,0 +1,17 @@
+# Adding 10000 items property-style
+Measure-Command {
+    $HashProp = @{}
+    1..10000 | ForEach-Object { $HashProp.$_ = $_ }
+}
+
+# Adding 10000 items using the Add method
+Measure-Command {
+    $HashMethod = @{}
+    1..10000 | ForEach-Object { $HashMethod.Add($_, $_) }
+}
+
+# Adding 10000 items dictionary-style
+Measure-Command {
+    $HashDict = @{}
+    1..10000 | ForEach-Object { $HashDict[$_] = $_ }
+}

guidance/Add-String.ps1

@@ -0,0 +1,48 @@
+$tests = @{
+    'StringBuilder'          = {
+        $sb = [System.Text.StringBuilder]::new()
+        foreach ($i in 0..$args[0]) {
+            $sb = $sb.AppendLine("Iteration $i")
+        }
+        $sb.ToString()
+    }
+    'Join operator'          = {
+        $string = @(
+            foreach ($i in 0..$args[0]) {
+                "Iteration $i"
+            }
+        ) -join "`n"
+        $string
+    }
+    'Addition Assignment +=' = {
+        $string = ''
+        foreach ($i in 0..$args[0]) {
+            $string += "Iteration $i`n"
+        }
+        $string
+    }
+}
+
+10kb, 50kb, 100kb | ForEach-Object {
+    $groupResult = foreach ($test in $tests.GetEnumerator()) {
+        $ms = (Measure-Command { & $test.Value $_ }).TotalMilliseconds
+
+        [pscustomobject]@{
+            Iterations        = $_
+            Test              = $test.Key
+            TotalMilliseconds = [math]::Round($ms, 2)
+        }
+
+        [GC]::Collect()
+        [GC]::WaitForPendingFinalizers()
+    }
+
+    $groupResult = $groupResult | Sort-Object TotalMilliseconds
+    $groupResult | Select-Object *, @{
+        Name       = 'RelativeSpeed'
+        Expression = {
+            $relativeSpeed = $_.TotalMilliseconds / $groupResult[0].TotalMilliseconds
+            [math]::Round($relativeSpeed, 2).ToString() + 'x'
+        }
+    }
+}

guidance/Caller.ps1

@@ -0,0 +1,54 @@
+function Invoke-Function4 {
+    <#
+        .SYNOPSIS
+        Demonstrates caller detection using Get-PSCallStack.
+    #>
+    [CmdletBinding()]
+    param()
+    'In: ' + $MyInvocation.InvocationName
+    $caller = (Get-PSCallStack)[1].Command
+    'Caller: ' + $caller
+}
+
+function Invoke-Function3 {
+    <#
+        .SYNOPSIS
+        Demonstrates nested caller detection at depth 3.
+    #>
+    [CmdletBinding()]
+    param()
+    'In: ' + $MyInvocation.InvocationName
+    $caller = (Get-PSCallStack)[1].Command
+    'Caller: ' + $caller
+    Invoke-Function4
+}
+
+function Invoke-Function2 {
+    <#
+        .SYNOPSIS
+        Demonstrates nested caller detection at depth 2.
+    #>
+    [CmdletBinding()]
+    param()
+    'In: ' + $MyInvocation.InvocationName
+    $caller = (Get-PSCallStack)[1].Command
+    'Caller: ' + $caller
+    Invoke-Function3
+}
+
+function Invoke-Function1 {
+    <#
+        .SYNOPSIS
+        Entry point demonstrating caller detection through the call stack.
+    #>
+    [CmdletBinding()]
+    param()
+    'In: ' + $MyInvocation.InvocationName
+    Get-PSCallStack
+    $caller = (Get-PSCallStack)[1].Command
+    'Caller: ' + $caller
+    Invoke-Function2
+}
+
+# Test the functions
+Invoke-Function1

guidance/ClassExtension.ps1

@@ -0,0 +1,41 @@
+class C {
+    [string]$Name
+
+    C([string]$Name) {
+        $this.Name = $Name
+    }
+
+    [string]GetInfo() {
+        return "Name: $($this.Name)"
+    }
+}
+
+class B : C {
+    [int]$Age
+
+    B([string]$Name, [int]$Age) : base($Name) {
+        $this.Age = $Age
+    }
+
+    [string]GetInfo() {
+        # Cast $this to the parent class (C) to call its GetInfo()
+        return "$(([C]$this).GetInfo()), Age: $($this.Age)"
+    }
+}
+
+class A : B {
+    [string]$Role
+
+    A([string]$Name, [int]$Age, [string]$Role) : base($Name, $Age) {
+        $this.Role = $Role
+    }
+
+    [string]GetInfo() {
+        # Cast $this to B to call B’s GetInfo(), which itself calls C’s GetInfo()
+        return "$(([B]$this).GetInfo()), Role: $($this.Role)"
+    }
+}
+
+# Creating and testing an instance
+$person = [A]::new('John Doe', 30, 'Manager')
+$person.GetInfo()

guidance/Loops.ps1

@@ -0,0 +1,38 @@
+$ranGen = New-Object System.Random
+$RepeatCount = 10000
+
+'Basic for-loop = {0}ms' -f (Measure-Command -Expression {
+        for ($i = 0; $i -lt $RepeatCount; $i++) {
+            $Null = $ranGen.Next()
+        }
+    }).TotalMilliseconds
+
+'Wrapped in a function = {0}ms' -f (Measure-Command -Expression {
+        function Get-RandNum_Core {
+            <#
+                .SYNOPSIS
+                Gets a random number using a shared Random instance.
+            #>
+            param ($ranGen)
+            $ranGen.Next()
+        }
+
+        for ($i = 0; $i -lt $RepeatCount; $i++) {
+            $Null = Get-RandNum_Core $ranGen
+        }
+    }).TotalMilliseconds
+
+'For-loop in a function = {0}ms' -f (Measure-Command -Expression {
+        function Get-RandNum_All {
+            <#
+                .SYNOPSIS
+                Gets random numbers in a loop using a shared Random instance.
+            #>
+            param ($ranGen)
+            for ($i = 0; $i -lt $RepeatCount; $i++) {
+                $Null = $ranGen.Next()
+            }
+        }
+
+        Get-RandNum_All $ranGen
+    }).TotalMilliseconds