PowerShell · adityapatwardhan · Dec 6, 2025 · Oct 31, 2025 · Nov 25, 2025 · Nov 25, 2025
diff --git a/.github/actions/infrastructure/merge-conflict-checker/README.md b/.github/actions/infrastructure/merge-conflict-checker/README.md
@@ -0,0 +1,84 @@
+# Merge Conflict Checker
+
+This composite GitHub Action checks for Git merge conflict markers in files changed in pull requests.
+
+## Purpose
+
+Automatically detects leftover merge conflict markers (`<<<<<<<`, `=======`, `>>>>>>>`) in pull request files to prevent them from being merged into the codebase.
+
+## Usage
+
+### In a Workflow
+
+```yaml
+- name: Check for merge conflict markers
+  uses: "./.github/actions/infrastructure/merge-conflict-checker"
+```
+
+### Complete Example
+
+```yaml
+jobs:
+  merge_conflict_check:
+    name: Check for Merge Conflict Markers
+    runs-on: ubuntu-latest
+    if: github.event_name == 'pull_request'
+    permissions:
+      pull-requests: read
+      contents: read
+    steps:
+      - name: checkout
+        uses: actions/checkout@v5
+
+      - name: Check for merge conflict markers
+        uses: "./.github/actions/infrastructure/merge-conflict-checker"
+```
+
+## How It Works
+
+1. **File Detection**: Uses GitHub's API to get the list of files changed in the pull request
+2. **Marker Scanning**: Reads each changed file and searches for the following markers:
+   - `<<<<<<<` (conflict start marker)
+   - `=======` (conflict separator)
+   - `>>>>>>>` (conflict end marker)
+3. **Result Reporting**: 
+   - If markers are found, the action fails and lists all affected files
+   - If no markers are found, the action succeeds
+
+## Outputs
+
+- `files-checked`: Number of files that were checked
+- `conflicts-found`: Number of files containing merge conflict markers
+
+## Behavior
+
+- **Event Support**: Only works with `pull_request` events
+- **File Handling**:
+  - Checks only files that were added, modified, or renamed
+  - Skips deleted files
+  - Skips binary/unreadable files
+  - Skips directories
+
+## Example Output
+
+When conflict markers are detected:
+
+```
+❌ Merge conflict markers detected in the following files:
+  - src/example.cs
+    Markers found: <<<<<<<, =======, >>>>>>>
+  - README.md
+    Markers found: <<<<<<<, =======, >>>>>>>
+
+Please resolve these conflicts before merging.
+```
+
+When no markers are found:
+
+```
+✅ No merge conflict markers found
+```
+
+## Integration
+
+This action is integrated into the `linux-ci.yml` workflow and runs automatically on all pull requests to ensure code quality before merging.
diff --git a/.github/actions/infrastructure/merge-conflict-checker/action.yml b/.github/actions/infrastructure/merge-conflict-checker/action.yml
@@ -0,0 +1,36 @@
+name: 'Check for Merge Conflict Markers'
+description: 'Checks for Git merge conflict markers in changed files for pull requests'
+author: 'PowerShell Team'
+
+outputs:
+  files-checked:
+    description: 'Number of files checked for merge conflict markers'
+    value: ${{ steps.check.outputs.files-checked }}
+  conflicts-found:
+    description: 'Number of files with merge conflict markers'
+    value: ${{ steps.check.outputs.conflicts-found }}
+
+runs:
+  using: 'composite'
+  steps:
+    - name: Get changed files
+      id: changed-files
+      uses: "./.github/actions/infrastructure/get-changed-files"
+
+    - name: Check for merge conflict markers
+      id: check
+      shell: pwsh
+      env:
+        CHANGED_FILES_JSON: ${{ steps.changed-files.outputs.files }}
+      run: |
+        # Get changed files from environment variable (secure against injection)
+        $changedFilesJson = $env:CHANGED_FILES_JSON
+        $changedFiles = $changedFilesJson | ConvertFrom-Json
+
+        # Import ci.psm1 and run the check
+        Import-Module "$env:GITHUB_WORKSPACE/tools/ci.psm1" -Force
+        Test-MergeConflictMarker -File $changedFiles -WorkspacePath $env:GITHUB_WORKSPACE
+
+branding:
+  icon: 'alert-triangle'
+  color: 'red'
@@ -80,6 +80,12 @@ runs:
       Invoke-CIFinish
     shell: pwsh
 
+  - name: Install Pester
+    run: |-
+      Import-Module ./tools/ci.psm1
+      Install-CIPester
+    shell: pwsh
+
   - name: Validate Package Names
     run: |-
       # Run Pester tests to validate package names

diff --git a/.github/instructions/powershell-automatic-variables.instructions.md b/.github/instructions/powershell-automatic-variables.instructions.md
@@ -0,0 +1,159 @@
+---
+applyTo:
+  - "**/*.ps1"
+  - "**/*.psm1"
+---
+
+# PowerShell Automatic Variables - Naming Guidelines
+
+## Purpose
+
+This instruction provides guidelines for avoiding conflicts with PowerShell's automatic variables when writing PowerShell scripts and modules.
+
+## What Are Automatic Variables?
+
+PowerShell 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.
+
+## Common Automatic Variables to Avoid
+
+### Critical Variables (Never Use)
+
+- **`$matches`** - Contains the results of regular expression matches. Overwriting this can break regex operations.
+- **`$_`** - Represents the current object in the pipeline. Only use within pipeline blocks.
+- **`$PSItem`** - Alias for `$_`. Same rules apply.
+- **`$args`** - Contains an array of undeclared parameters. Don't use as a regular variable.
+- **`$input`** - Contains an enumerator of all input passed to a function. Don't reassign.
+- **`$LastExitCode`** - Exit code of the last native command. Don't overwrite unless intentional.
+- **`$?`** - Success status of the last command. Don't use as a variable name.
+- **`$$`** - Last token in the last line received by the session. Don't use.
+- **`$^`** - First token in the last line received by the session. Don't use.
+
+### Context Variables (Use with Caution)
+
+- **`$Error`** - Array of error objects. Don't replace, but can modify (e.g., `$Error.Clear()`).
+- **`$PSBoundParameters`** - Parameters passed to the current function. Read-only.
+- **`$MyInvocation`** - Information about the current command. Read-only.
+- **`$PSCmdlet`** - Cmdlet object for advanced functions. Read-only.
+
+### Other Common Automatic Variables
+
+- `$true`, `$false`, `$null` - Boolean and null constants
+- `$HOME`, `$PSHome`, `$PWD` - Path-related variables
+- `$PID` - Process ID of the current PowerShell session
+- `$Host` - Host application object
+- `$PSVersionTable` - PowerShell version information
+
+For a complete list, see: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_automatic_variables
+
+## Best Practices
+
+### ❌ Bad - Using Automatic Variable Names
+
+```powershell
+# Bad: $matches is an automatic variable used for regex capture groups
+$matches = Select-String -Path $file -Pattern $pattern
+
+# Bad: $args is an automatic variable for undeclared parameters
+$args = Get-ChildItem
+
+# Bad: $input is an automatic variable for pipeline input
+$input = Read-Host "Enter value"
+```
+
+### ✅ Good - Using Descriptive Alternative Names
+
+```powershell
+# Good: Use descriptive names that avoid conflicts
+$matchedLines = Select-String -Path $file -Pattern $pattern
+
+# Good: Use specific names for arguments
+$arguments = Get-ChildItem
+
+# Good: Use specific names for user input
+$userInput = Read-Host "Enter value"
+```
+
+## Naming Alternatives
+
+When you encounter a situation where you might use an automatic variable name, use these alternatives:
+
+| Avoid | Use Instead |
+|-------|-------------|
+| `$matches` | `$matchedLines`, `$matchResults`, `$regexMatches` |
+| `$args` | `$arguments`, `$parameters`, `$commandArgs` |
+| `$input` | `$userInput`, `$inputValue`, `$inputData` |
+| `$_` (outside pipeline) | Use a named parameter or explicit variable |
+| `$Error` (reassignment) | Don't reassign; use `$Error.Clear()` if needed |
+
+## How to Check
+
+### PSScriptAnalyzer Rule
+
+PSScriptAnalyzer has a built-in rule that detects assignments to automatic variables:
+
+```powershell
+# This will trigger PSAvoidAssignmentToAutomaticVariable
+$matches = Get-Something
+```
+
+**Rule ID**: PSAvoidAssignmentToAutomaticVariable
+
+### Manual Review
+
+When writing PowerShell code, always:
+1. Avoid variable names that match PowerShell keywords or automatic variables
+2. Use descriptive, specific names that clearly indicate the variable's purpose
+3. Run PSScriptAnalyzer on your code before committing
+4. Review code for variable naming during PR reviews
+
+## Examples from the Codebase
+
+### Example 1: Regex Matching
+
+```powershell
+# ❌ Bad - Overwrites automatic $matches variable
+$matches = [regex]::Matches($content, $pattern)
+
+# ✅ Good - Uses descriptive name
+$regexMatches = [regex]::Matches($content, $pattern)
+```
+
+### Example 2: Select-String Results
+
+```powershell
+# ❌ Bad - Conflicts with automatic $matches
+$matches = Select-String -Path $file -Pattern $pattern
+
+# ✅ Good - Clear and specific
+$matchedLines = Select-String -Path $file -Pattern $pattern
+```
+
+### Example 3: Collecting Arguments
+
+```powershell
+# ❌ Bad - Conflicts with automatic $args
+function Process-Items {
+    $args = $MyItems
+    # ... process items
+}
+
+# ✅ Good - Descriptive parameter name
+function Process-Items {
+    [CmdletBinding()]
+    param(
+        [Parameter(ValueFromRemainingArguments)]
+        [string[]]$Items
+    )
+    # ... process items
+}
+```
+
+## References
+
+- [PowerShell Automatic Variables Documentation](https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_automatic_variables)
+- [PSScriptAnalyzer Rules](https://github.com/PowerShell/PSScriptAnalyzer/blob/master/docs/Rules/README.md)
+- [PowerShell Best Practices](https://learn.microsoft.com/powershell/scripting/developer/cmdlet/strongly-encouraged-development-guidelines)
+
+## Summary
+
+**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.