powershell-strict-mode

Files (1)

• SKILL.md

SKILL.md (first lines)

# powershell-strict-mode

Goal: eliminate classes of errors caused by `Set-StrictMode -Version Latest` and PowerShell typing nuances.

## Mandatory rules

### 1. Always wrap filters with `@()`

`Where-Object`, `Select-Object`, `Group-Object` can return:

- `$null` - when 0 matches
- single object - when 1 match
- array - when 2+ matches

In StrictMode, calling `.Count` or `.Length` on `$null` or PSCustomObject throws `PropertyNotFoundStrict`.

```powershell
# WRONG - error if 0 or 1 result
$items = $nodes | Where-Object { $_.type -eq 'feature' }
$items.Count   # <- PropertyNotFoundStrict in strict mode

# CORRECT - always array
$items = @($nodes | Where-Object { $_.type -eq 'feature' })
$items.Count   # safe
```

### 2. Do not execute pipeline twice for Count + data

```powershell
# WRONG - two passes, second can be PSObject without Count
$extAll = ($nodes | Where-Object { $_.type -eq 'external_dependency' }).Count
$extNoDomain = ($nodes | Where-Object { $_.type -eq 'external_dependency' -and ... }).Count

# CORRECT - one @() per required collection
$extAll      = @($nodes | Where-Object { $_.type -eq 'external_dependency' })
$extNoDomain = @($extAll | Where-Object { [string]::IsNullOrWhiteSpace($_.domain) })
$pct = if ($extAll.Count -gt 0) { $extNoDomain.Count / $extAll.Count * 100 } else { 0 }
```

### 3. Regex in single-quoted strings - special characters without escape hell

Use `'...'` (single-quoted) for regex instead of `"..."` (double-quoted).
In double-quoted strings, `['\"]` is interpreted incorrectly by PS parser as a char array.

```powershell
# WRONG - Unexpected token ']' (double-quoted + bracket)
if ($line -match "import\s+.*from\s+['\"]([^'\"]+)['\"]") { ... }

# CORRECT - single-quoted, '' is escaped apostrophe
if ($line -match 'import\s+.*from\s+[''"]([^''"]+)[''"]') { ... }
```

### 4. Null checks before property access

```powershell
# WRONG - error if $node is null
if ($node.metadata.PSObject.Properties['hash']) { ... }

# CORRECT
if ($null -ne $node -and $null -ne $node.metadata -and $node.metadata.PSObject.Properties['hash']) { ... }
```

### 5. Type conversion with Measure-Object

`Measure-Object -Average` returns an object, not a number:

```powershell
# WRONG
$avg = ($lengths | Measure-Object -Average).Average   # can be double
[int]$avg  # OK only if not $null

# CORRECT - guard for empty collection
$avg = if ($lengths.Count -gt 0) { [int](($lengths | Measure-Object -Average).Average) } else { 0 }
```

### 6. Collection interpolation in strings

```powershell
# WRONG - prints "System.Object[]" or nothing
"deps=$namespaces"

# CORRECT
"deps=$($namespaces -join ',')"
```

### 7. Safe access to PSObject.Properties in strict mode

```powershell
# Always verify Properties exists before indexing
if ($obj.PSObject.Properties['myProp']) {
    $val = $obj.myProp
}
```

### 8. Value-returning functions - avoid mixing Write-Host with return

```powershell
# WRONG - Write-Host can leak into output stream in some contexts
function Get-Count { Write-Host "debug"; return 5 }

# CORRECT - debug to stream 2 (stderr)
function Get-Count { Write-Verbose "debug"; return 5 }
```

## Generate scripts adapted to machine

When generating or editing any PS1 script, **do not hardcode**:

- module versions (Pester, PSReadLine, Az, ...)
- machine-specific absolute paths
- CLI flags that exist only in specific module version
- noisy success stdout when script supports `quiet|normal|diagnostic` or `EmitJson`

If script returns parseable JSON, keep success output in `quiet` by default, and print diagnostics only in `diagnostic` or save into bundle after failure.

### Rule: detect first, then use

Instead:

From ArkadiuszSieracki/mastermind-agentic-sdlc-vscode-copilot, Apache-2.0.

More from ArkadiuszSieracki/mastermind-agentic-sdlc-vscode-copilot