@mytechtoday/augment-extensions 0.2.0 → 0.5.0

package/augment-extensions/coding-standards/powershell/rules/naming-conventions.md

@@ -0,0 +1,266 @@
+# PowerShell Naming Conventions
+
+Comprehensive naming standards for PowerShell code following Microsoft best practices.
+
+## Function and Cmdlet Names
+
+### Verb-Noun Pattern
+
+**ALWAYS** use approved verbs with singular nouns:
+
+```powershell
+# ✅ Correct
+Get-User
+Set-Configuration
+New-LogEntry
+Remove-TempFile
+
+# ❌ Incorrect
+GetUser          # Missing hyphen
+Get-Users        # Plural noun
+Fetch-User       # Unapproved verb
+Get_User         # Underscore instead of hyphen
+```
+
+### Approved Verbs
+
+Use `Get-Verb` to see all approved verbs. Common categories:
+
+**Common Verbs:**
+- `Get`, `Set`, `New`, `Remove`
+- `Add`, `Clear`, `Copy`, `Move`
+- `Find`, `Search`, `Select`, `Show`
+- `Start`, `Stop`, `Restart`, `Suspend`
+- `Read`, `Write`, `Update`, `Invoke`
+
+**Data Verbs:**
+- `Backup`, `Restore`, `Save`, `Sync`
+- `Compare`, `Convert`, `Export`, `Import`
+- `Merge`, `Split`, `Compress`, `Expand`
+
+**Lifecycle Verbs:**
+- `Initialize`, `Register`, `Unregister`
+- `Enable`, `Disable`, `Install`, `Uninstall`
+
+**Diagnostic Verbs:**
+- `Test`, `Trace`, `Measure`, `Debug`
+- `Confirm`, `Assert`, `Validate`
+
+### Verb Selection Guidelines
+
+```powershell
+# ✅ Use Get for retrieval
+Get-UserProfile
+
+# ✅ Use Set for modification
+Set-UserProfile
+
+# ✅ Use New for creation
+New-UserProfile
+
+# ✅ Use Remove for deletion
+Remove-UserProfile
+
+# ✅ Use Test for validation (returns boolean)
+Test-UserExists
+
+# ✅ Use Invoke for execution
+Invoke-UserScript
+```
+
+## Variable Names
+
+### PascalCase for Variables
+
+```powershell
+# ✅ Correct
+$UserName = "john.doe"
+$FilePath = "C:\Logs\app.log"
+$MaxRetryCount = 3
+$IsEnabled = $true
+
+# ❌ Incorrect
+$username        # camelCase
+$file_path       # snake_case
+$MAXRETRYCOUNT   # ALL CAPS (reserved for constants)
+$is-enabled      # kebab-case
+```
+
+### Descriptive Names
+
+```powershell
+# ✅ Descriptive
+$DatabaseConnectionString
+$UserEmailAddress
+$MaximumRetryAttempts
+
+# ❌ Too short/cryptic
+$dcs
+$email
+$max
+```
+
+### Boolean Variables
+
+Prefix with `Is`, `Has`, `Should`, `Can`:
+
+```powershell
+$IsValid = $true
+$HasPermission = $false
+$ShouldContinue = $true
+$CanWrite = Test-Path $path -PathType Leaf
+```
+
+### Collections
+
+Use plural nouns:
+
+```powershell
+$Users = @()
+$Files = Get-ChildItem
+$ErrorMessages = @()
+```
+
+## Parameter Names
+
+### PascalCase and Descriptive
+
+```powershell
+function Get-UserData
+{
+    [CmdletBinding()]
+    param(
+        [Parameter(Mandatory)]
+        [string]$UserName,
+        
+        [Parameter()]
+        [string]$DomainName = 'contoso.com',
+        
+        [Parameter()]
+        [switch]$IncludeGroups
+    )
+}
+```
+
+### Common Parameter Names
+
+Follow PowerShell conventions:
+
+```powershell
+# ✅ Standard names
+-Path           # File/folder paths
+-Name           # Object names
+-ComputerName   # Remote computer
+-Credential     # PSCredential object
+-Force          # Override confirmations
+-WhatIf         # Simulation mode
+-Confirm        # Confirmation prompts
+-Verbose        # Verbose output
+-Debug          # Debug output
+```
+
+## Constants and Enums
+
+### ALL_CAPS with Underscores
+
+```powershell
+# Constants
+$MAX_RETRY_COUNT = 5
+$DEFAULT_TIMEOUT_SECONDS = 30
+$API_BASE_URL = 'https://api.example.com'
+
+# Enums
+enum LogLevel
+{
+    DEBUG
+    INFO
+    WARNING
+    ERROR
+    CRITICAL
+}
+```
+
+## File Names
+
+### Script Files (.ps1)
+
+```powershell
+# ✅ Correct
+Get-UserReport.ps1
+Deploy-Application.ps1
+Backup-Database.ps1
+
+# ❌ Incorrect
+getUserReport.ps1      # camelCase
+get_user_report.ps1    # snake_case
+script1.ps1            # Non-descriptive
+```
+
+### Module Files
+
+```powershell
+# Module manifest (.psd1)
+MyModule.psd1
+
+# Module script (.psm1)
+MyModule.psm1
+
+# Module folder
+MyModule/
+```
+
+## Class Names
+
+### PascalCase
+
+```powershell
+class UserAccount
+{
+    [string]$UserName
+    [string]$Email
+    [datetime]$CreatedDate
+    
+    UserAccount([string]$userName, [string]$email)
+    {
+        $this.UserName = $userName
+        $this.Email = $email
+        $this.CreatedDate = Get-Date
+    }
+}
+```
+
+## Anti-Patterns
+
+### Avoid These
+
+```powershell
+# ❌ Hungarian notation
+$strUserName
+$intCount
+$arrUsers
+
+# ❌ Abbreviations (unless widely known)
+$usr
+$cnt
+$msg
+
+# ❌ Single letters (except loop counters)
+$x
+$y
+$z
+
+# ✅ Loop counters are OK
+for ($i = 0; $i -lt 10; $i++)
+{
+    # Process
+}
+```
+
+## Best Practices
+
+1. **Be consistent** - Follow the same pattern throughout your codebase
+2. **Be descriptive** - Names should explain purpose without comments
+3. **Use approved verbs** - Check with `Get-Verb`
+4. **Avoid abbreviations** - Unless universally understood (URL, API, SQL)
+5. **Follow PowerShell conventions** - Match built-in cmdlet patterns
+

package/augment-extensions/coding-standards/powershell/rules/performance-optimization.md

@@ -0,0 +1,209 @@
+# PowerShell Performance Optimization
+
+Comprehensive performance optimization techniques for efficient PowerShell code.
+
+## Pipeline Efficiency
+
+### Use Pipeline Correctly
+
+**PREFER** pipeline over loops when possible:
+
+```powershell
+# ✅ GOOD: Pipeline (faster)
+Get-ChildItem -Path C:\Logs -Filter *.log | Where-Object { $_.Length -gt 1MB } | Remove-Item
+
+# ❌ BAD: ForEach loop (slower)
+$files = Get-ChildItem -Path C:\Logs -Filter *.log
+foreach ($file in $files) {
+    if ($file.Length -gt 1MB) {
+        Remove-Item $file
+    }
+}
+```
+
+### Filter Left, Format Right
+
+**ALWAYS** filter as early as possible:
+
+```powershell
+# ✅ GOOD: Filter at source
+Get-ChildItem -Path C:\Logs -Filter *.log | Where-Object { $_.Length -gt 1MB }
+
+# ❌ BAD: Get everything then filter
+Get-ChildItem -Path C:\Logs | Where-Object { $_.Name -like '*.log' -and $_.Length -gt 1MB }
+```
+
+### Avoid Unnecessary Pipeline Operations
+
+```powershell
+# ✅ GOOD: Direct assignment
+$processes = Get-Process
+
+# ❌ BAD: Unnecessary ForEach-Object
+$processes = Get-Process | ForEach-Object { $_ }
+```
+
+## Loop Performance
+
+### foreach vs ForEach-Object
+
+**USE** `foreach` statement for better performance:
+
+```powershell
+# ✅ GOOD: foreach statement (fastest)
+$items = 1..10000
+foreach ($item in $items) {
+    $result = $item * 2
+}
+
+# ❌ SLOWER: ForEach-Object cmdlet
+$items = 1..10000
+$items | ForEach-Object {
+    $result = $_ * 2
+}
+```
+
+**WHEN** to use ForEach-Object:
+- Processing pipeline input
+- Need to stream large datasets
+- Want lazy evaluation
+
+### Avoid Nested Loops
+
+```powershell
+# ✅ GOOD: Use hashtable for lookups
+$userLookup = @{}
+foreach ($user in $users) {
+    $userLookup[$user.Id] = $user
+}
+
+foreach ($order in $orders) {
+    $user = $userLookup[$order.UserId]  # O(1) lookup
+}
+
+# ❌ BAD: Nested loops
+foreach ($order in $orders) {
+    foreach ($user in $users) {  # O(n²) complexity
+        if ($user.Id -eq $order.UserId) {
+            # Process
+        }
+    }
+}
+```
+
+## Memory Management
+
+### Use [System.Collections.Generic.List] for Dynamic Arrays
+
+```powershell
+# ✅ GOOD: Generic List (efficient)
+$list = [System.Collections.Generic.List[string]]::new()
+foreach ($item in 1..10000) {
+    $list.Add("Item $item")
+}
+
+# ❌ BAD: Array concatenation (slow)
+$array = @()
+foreach ($item in 1..10000) {
+    $array += "Item $item"  # Creates new array each time
+}
+```
+
+### Dispose of Large Objects
+
+```powershell
+# ✅ GOOD: Explicit disposal
+$stream = [System.IO.StreamReader]::new('large-file.txt')
+try {
+    $content = $stream.ReadToEnd()
+}
+finally {
+    $stream.Dispose()
+}
+
+# ✅ BETTER: Using statement (PowerShell 7+)
+using ($stream = [System.IO.StreamReader]::new('large-file.txt')) {
+    $content = $stream.ReadToEnd()
+}
+```
+
+### Clear Variables When Done
+
+```powershell
+# Clear large variables
+$largeData = Get-LargeDataset
+# Process data
+$largeData = $null
+[System.GC]::Collect()  # Force garbage collection (use sparingly)
+```
+
+## String Operations
+
+### Use StringBuilder for Concatenation
+
+```powershell
+# ✅ GOOD: StringBuilder
+$sb = [System.Text.StringBuilder]::new()
+foreach ($item in 1..1000) {
+    [void]$sb.AppendLine("Line $item")
+}
+$result = $sb.ToString()
+
+# ❌ BAD: String concatenation
+$result = ''
+foreach ($item in 1..1000) {
+    $result += "Line $item`n"  # Creates new string each time
+}
+```
+
+### Use -join for Arrays
+
+```powershell
+# ✅ GOOD: -join operator
+$items = 1..1000
+$result = $items -join ', '
+
+# ❌ BAD: String concatenation in loop
+$result = ''
+foreach ($item in $items) {
+    $result += "$item, "
+}
+```
+
+## Cmdlet-Specific Optimizations
+
+### Use -Filter Instead of Where-Object
+
+```powershell
+# ✅ GOOD: Server-side filtering
+Get-ChildItem -Path C:\Logs -Filter *.log
+
+# ❌ BAD: Client-side filtering
+Get-ChildItem -Path C:\Logs | Where-Object { $_.Extension -eq '.log' }
+```
+
+### Use -ReadCount for Large Files
+
+```powershell
+# ✅ GOOD: Process in batches
+Get-Content -Path large-file.txt -ReadCount 1000 | ForEach-Object {
+    # Process batch of 1000 lines
+}
+
+# ❌ BAD: Load entire file
+$content = Get-Content -Path large-file.txt
+```
+
+## Best Practices Summary
+
+1. **Filter early** - Use -Filter parameter when available
+2. **Use foreach statement** - Faster than ForEach-Object for arrays
+3. **Avoid array concatenation** - Use Generic.List for dynamic arrays
+4. **Use StringBuilder** - For string concatenation in loops
+5. **Dispose resources** - Clean up streams, connections, large objects
+6. **Measure performance** - Use Measure-Command to profile
+7. **Avoid nested loops** - Use hashtables for lookups
+8. **Stream large files** - Use -ReadCount or StreamReader
+9. **Cache results** - Don't repeat expensive operations
+10. **Use .NET types** - When PowerShell cmdlets are too slow
+