Copilot instructions

1---
2applyTo:
3  - "**/*.ps1"
4  - "**/*.psm1"
5---
6 
7# PowerShell Automatic Variables - Naming Guidelines
8 
9## Purpose
10 
11This instruction provides guidelines for avoiding conflicts with PowerShell's automatic variables when writing PowerShell scripts and modules.
12 
13## What Are Automatic Variables?
14 
15PowerShell has built-in automatic variables that are created and maintained by PowerShell itself. Assigning values to these variables can cause unexpected behavior and side effects.
16 
17## Common Automatic Variables to Avoid
18 
19### Critical Variables (Never Use)
20 
21- **`$matches`** - Contains the results of regular expression matches. Overwriting this can break regex operations.
22- **`$_`** - Represents the current object in the pipeline. Only use within pipeline blocks.
23- **`$PSItem`** - Alias for `$_`. Same rules apply.
24- **`$args`** - Contains an array of undeclared parameters. Don't use as a regular variable.
25- **`$input`** - Contains an enumerator of all input passed to a function. Don't reassign.
26- **`$LastExitCode`** - Exit code of the last native command. Don't overwrite unless intentional.
27- **`$?`** - Success status of the last command. Don't use as a variable name.
28- **`$$`** - Last token in the last line received by the session. Don't use.
29- **`$^`** - First token in the last line received by the session. Don't use.
30 
31### Context Variables (Use with Caution)
32 
33- **`$Error`** - Array of error objects. Don't replace, but can modify (e.g., `$Error.Clear()`).
34- **`$PSBoundParameters`** - Parameters passed to the current function. Read-only.
35- **`$MyInvocation`** - Information about the current command. Read-only.
36- **`$PSCmdlet`** - Cmdlet object for advanced functions. Read-only.
37 
38### Other Common Automatic Variables
39 
40- `$true`, `$false`, `$null` - Boolean and null constants
41- `$HOME`, `$PSHome`, `$PWD` - Path-related variables
42- `$PID` - Process ID of the current PowerShell session
43- `$Host` - Host application object
44- `$PSVersionTable` - PowerShell version information
45 
46For a complete list, see: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_automatic_variables
47 
48## Best Practices
49 
50### ❌ Bad - Using Automatic Variable Names
51 
52```powershell
53# Bad: $matches is an automatic variable used for regex capture groups
54$matches = Select-String -Path $file -Pattern $pattern
55 
56# Bad: $args is an automatic variable for undeclared parameters
57$args = Get-ChildItem
58 
59# Bad: $input is an automatic variable for pipeline input
60$input = Read-Host "Enter value"
61```
62 
63### ✅ Good - Using Descriptive Alternative Names
64 
65```powershell
66# Good: Use descriptive names that avoid conflicts
67$matchedLines = Select-String -Path $file -Pattern $pattern
68 
69# Good: Use specific names for arguments
70$arguments = Get-ChildItem
71 
72# Good: Use specific names for user input
73$userInput = Read-Host "Enter value"
74```
75 
76## Naming Alternatives
77 
78When you encounter a situation where you might use an automatic variable name, use these alternatives:
79 
80| Avoid | Use Instead |
81|-------|-------------|
82| `$matches` | `$matchedLines`, `$matchResults`, `$regexMatches` |
83| `$args` | `$arguments`, `$parameters`, `$commandArgs` |
84| `$input` | `$userInput`, `$inputValue`, `$inputData` |
85| `$_` (outside pipeline) | Use a named parameter or explicit variable |
86| `$Error` (reassignment) | Don't reassign; use `$Error.Clear()` if needed |
87 
88## How to Check
89 
90### PSScriptAnalyzer Rule
91 
92PSScriptAnalyzer has a built-in rule that detects assignments to automatic variables:
93 
94```powershell
95# This will trigger PSAvoidAssignmentToAutomaticVariable
96$matches = Get-Something
97```
98 
99**Rule ID**: PSAvoidAssignmentToAutomaticVariable
100 
101### Manual Review
102 
103When writing PowerShell code, always:
1041. Avoid variable names that match PowerShell keywords or automatic variables
1052. Use descriptive, specific names that clearly indicate the variable's purpose
1063. Run PSScriptAnalyzer on your code before committing
1074. Review code for variable naming during PR reviews
108 
109## Examples from the Codebase
110 
111### Example 1: Regex Matching
112 
113```powershell
114# ❌ Bad - Overwrites automatic $matches variable
115$matches = [regex]::Matches($content, $pattern)
116 
117# ✅ Good - Uses descriptive name
118$regexMatches = [regex]::Matches($content, $pattern)
119```
120 
121### Example 2: Select-String Results
122 
123```powershell
124# ❌ Bad - Conflicts with automatic $matches
125$matches = Select-String -Path $file -Pattern $pattern
126 
127# ✅ Good - Clear and specific
128$matchedLines = Select-String -Path $file -Pattern $pattern
129```
130 
131### Example 3: Collecting Arguments
132 
133```powershell
134# ❌ Bad - Conflicts with automatic $args
135function Process-Items {
136    $args = $MyItems
137    # ... process items
138}
139 
140# ✅ Good - Descriptive parameter name
141function Process-Items {
142    [CmdletBinding()]
143    param(
144        [Parameter(ValueFromRemainingArguments)]
145        [string[]]$Items
146    )
147    # ... process items
148}
149```
150 
151## References
152 
153- [PowerShell Automatic Variables Documentation](https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_automatic_variables)
154- [PSScriptAnalyzer Rules](https://github.com/PowerShell/PSScriptAnalyzer/blob/master/docs/Rules/README.md)
155- [PowerShell Best Practices](https://learn.microsoft.com/powershell/scripting/developer/cmdlet/strongly-encouraged-development-guidelines)
156 
157## Summary
158 
159**Key Takeaway**: Always use descriptive, specific variable names that clearly indicate their purpose and avoid conflicts with PowerShell's automatic variables. When in doubt, choose a longer, more descriptive name over a short one that might conflict.
160