Proven Techniques to Tackle Tech Debt

<#
.SYNOPSIS
    Hunts for technical debt markers (TODO, FIXME, HACK, BUG, OPTIMIZE) across your codebase

.DESCRIPTION
    Scans all code files recursively and reports lines containing debt markers.
    Outputs results to console with line numbers and context for easy backlog creation.

.PARAMETER Path
    Root directory to scan (default: current directory)

.PARAMETER OutputCsv
    Optional: Export results to CSV file for import into Jira/Linear/etc.

.EXAMPLE
    Find-TechDebt -Path "C:\Projects\MyLegacyApp"

.EXAMPLE
    Find-TechDebt -Path "." -OutputCsv "debt-report.csv"
#>

function Find-TechDebt {
    param(
        [string]$Path = ".",
        [string]$OutputCsv = ""
    )

    Write-Host "🔍 Scanning for technical debt markers..." -ForegroundColor Cyan
    Write-Host "📂 Path: $Path`n" -ForegroundColor Gray

    # Debt keywords to search for
    $debtKeywords = @("TODO", "FIXME", "HACK", "BUG", "OPTIMIZE", "XXX", "REFACTOR")
    $pattern = $debtKeywords -join "|"

    # File extensions to scan (customize for your stack)
    $extensions = @("*.cs", "*.js", "*.ts", "*.tsx", "*.ps1", "*.sql", "*.py", "*.java", "*.rb", "*.go", "*.php")

    try {
        $results = Get-ChildItem -Path $Path -Recurse -Include $extensions -ErrorAction SilentlyContinue |
            Select-String -Pattern $pattern -CaseSensitive:$false |
            Select-Object @{
                Name='File'; Expression={$_.Filename}
            }, @{
                Name='Line'; Expression={$_.LineNumber}
            }, @{
                Name='Type'; Expression={
                    if ($_.Line -match "TODO") { "TODO" }
                    elseif ($_.Line -match "FIXME") { "FIXME" }
                    elseif ($_.Line -match "HACK") { "HACK" }
                    elseif ($_.Line -match "BUG") { "BUG" }
                    elseif ($_.Line -match "OPTIMIZE") { "OPTIMIZE" }
                    elseif ($_.Line -match "XXX") { "XXX" }
                    elseif ($_.Line -match "REFACTOR") { "REFACTOR" }
                }
            }, @{
                Name='Content'; Expression={$_.Line.Trim()}
            }, @{
                Name='Path'; Expression={$_.Path}
            }

        # Group by type for summary
        $summary = $results | Group-Object Type |
            Select-Object @{Name='Type'; Expression={$_.Name}}, @{Name='Count'; Expression={$_.Count}} |
            Sort-Object Count -Descending

        # Display results
        Write-Host "📊 SUMMARY" -ForegroundColor Yellow
        Write-Host "═══════════════════════════════════════" -ForegroundColor Gray
        $summary | Format-Table -AutoSize

        Write-Host "`n📝 DETAILED FINDINGS" -ForegroundColor Yellow
        Write-Host "═══════════════════════════════════════" -ForegroundColor Gray
        $results | Format-Table File, Line, Type, Content -AutoSize

        # Export to CSV if requested
        if ($OutputCsv) {
            $results | Export-Csv -Path $OutputCsv -NoTypeInformation
            Write-Host "`n✅ Results exported to: $OutputCsv" -ForegroundColor Green
        }

        # Final summary
        $totalDebt = ($results | Measure-Object).Count
        Write-Host "`n🎯 TOTAL DEBT MARKERS FOUND: $totalDebt" -ForegroundColor Cyan

        if ($totalDebt -gt 100) {
            Write-Host "⚠️  HIGH DEBT ALERT: You have over 100 debt markers. Consider scheduling a tech debt sprint." -ForegroundColor Red
        } elseif ($totalDebt -gt 50) {
            Write-Host "⚠️  MODERATE DEBT: Start chipping away with the Boy Scout Rule." -ForegroundColor Yellow
        } else {
            Write-Host "✅ MANAGEABLE DEBT: Keep up the good work!" -ForegroundColor Green
        }

    } catch {
        Write-Error "Error scanning for debt: $_"
    }
}

# Example usage:
# Find-TechDebt -Path "C:\Projects\MyApp"
# Find-TechDebt -Path "." -OutputCsv "tech-debt-report.csv"

<#
.SYNOPSIS
    Scans PowerShell scripts for high cyclomatic complexity (code that's too complex)

.DESCRIPTION
    Uses PSScriptAnalyzer to identify functions with complexity > threshold.
    High complexity (15+) indicates code that's hard to test, understand, and maintain.

.PARAMETER Path
    File or directory to scan

.PARAMETER ComplexityThreshold
    Minimum complexity to report (default: 15, industry standard for "too complex")

.EXAMPLE
    Find-ComplexCode -Path "C:\Scripts\MyScript.ps1"

.EXAMPLE
    Find-ComplexCode -Path "C:\Projects\Automation" -ComplexityThreshold 10

.NOTES
    Cyclomatic Complexity Scale:
    1-10:  Simple, easy to test
    11-20: Moderate complexity
    21-50: High complexity - refactor recommended
    51+:   Very high - urgent refactor needed
#>

function Find-ComplexCode {
    param(
        [Parameter(Mandatory=$true)]
        [string]$Path,

        [int]$ComplexityThreshold = 15
    )

    Write-Host "🔬 Analyzing code complexity..." -ForegroundColor Cyan
    Write-Host "📂 Path: $Path" -ForegroundColor Gray
    Write-Host "🎯 Threshold: $ComplexityThreshold`n" -ForegroundColor Gray

    try {
        # Check if PSScriptAnalyzer is installed
        if (-not (Get-Module -ListAvailable -Name PSScriptAnalyzer)) {
            Write-Host "❌ PSScriptAnalyzer not found. Installing..." -ForegroundColor Red
            Install-Module -Name PSScriptAnalyzer -Scope CurrentUser -Force
            Write-Host "✅ PSScriptAnalyzer installed`n" -ForegroundColor Green
        }

        Import-Module PSScriptAnalyzer

        # Get all PowerShell files
        $files = if (Test-Path -Path $Path -PathType Leaf) {
            @(Get-Item $Path)
        } else {
            Get-ChildItem -Path $Path -Recurse -Include *.ps1, *.psm1
        }

        $allResults = @()

        foreach ($file in $files) {
            Write-Host "  Scanning: $($file.Name)" -ForegroundColor Gray

            # Run PSScriptAnalyzer
            $results = Invoke-ScriptAnalyzer -Path $file.FullName -IncludeRule PSAvoidUsingCmdletAliases, PSAvoidUsingWMICmdlet, PSAvoidUsingPositionalParameters

            # Parse for complexity (note: PSScriptAnalyzer doesn't directly measure complexity,
            # but we can analyze function length and structure as a proxy)
            $content = Get-Content $file.FullName -Raw
            $functions = [regex]::Matches($content, 'function\s+[\w-]+\s*{[^}]*}', [System.Text.RegularExpressions.RegexOptions]::Singleline)

            foreach ($func in $functions) {
                $funcText = $func.Value
                $funcName = if ($funcText -match 'function\s+([\w-]+)') { $matches[1] } else { "Unknown" }

                # Count complexity indicators (if, elseif, switch, while, for, foreach, catch)
                $complexity = ([regex]::Matches($funcText, '\b(if|elseif|switch|while|for|foreach|catch)\b')).Count + 1

                if ($complexity -ge $ComplexityThreshold) {
                    $allResults += [PSCustomObject]@{
                        File = $file.Name
                        Function = $funcName
                        Complexity = $complexity
                        Lines = ($funcText -split "`n").Count
                        Severity = if ($complexity -gt 50) { "CRITICAL" }
                                   elseif ($complexity -gt 20) { "HIGH" }
                                   else { "MODERATE" }
                        Path = $file.FullName
                    }
                }
            }
        }

        if ($allResults.Count -eq 0) {
            Write-Host "`n✅ No high-complexity functions found! Your code is clean." -ForegroundColor Green
            return
        }

        # Display results sorted by complexity
        Write-Host "`n📊 HIGH COMPLEXITY FUNCTIONS" -ForegroundColor Yellow
        Write-Host "═══════════════════════════════════════════════════════════" -ForegroundColor Gray
        $allResults | Sort-Object Complexity -Descending | Format-Table File, Function, Complexity, Lines, Severity -AutoSize

        # Summary by severity
        $summary = $allResults | Group-Object Severity |
            Select-Object @{Name='Severity'; Expression={$_.Name}}, @{Name='Count'; Expression={$_.Count}}

        Write-Host "`n🎯 SUMMARY BY SEVERITY" -ForegroundColor Yellow
        Write-Host "═══════════════════════════════════════" -ForegroundColor Gray
        $summary | Format-Table -AutoSize

        # Recommendations
        Write-Host "`n💡 RECOMMENDATIONS" -ForegroundColor Cyan
        Write-Host "═══════════════════════════════════════" -ForegroundColor Gray

        $critical = ($allResults | Where-Object Severity -eq "CRITICAL").Count
        if ($critical -gt 0) {
            Write-Host "❗ CRITICAL: $critical functions with complexity > 50" -ForegroundColor Red
            Write-Host "   Action: Refactor immediately. These are bug factories." -ForegroundColor Red
        }

        $high = ($allResults | Where-Object Severity -eq "HIGH").Count
        if ($high -gt 0) {
            Write-Host "⚠️  HIGH: $high functions with complexity 21-50" -ForegroundColor Yellow
            Write-Host "   Action: Add to tech debt backlog. Break into smaller functions." -ForegroundColor Yellow
        }

        $moderate = ($allResults | Where-Object Severity -eq "MODERATE").Count
        if ($moderate -gt 0) {
            Write-Host "ℹ️  MODERATE: $moderate functions with complexity 15-20" -ForegroundColor Cyan
            Write-Host "   Action: Apply Boy Scout Rule when touching these files." -ForegroundColor Cyan
        }

    } catch {
        Write-Error "Error analyzing complexity: $_"
    }
}

# Example usage:
# Find-ComplexCode -Path "C:\Projects\MyApp"
# Find-ComplexCode -Path ".\MyScript.ps1" -ComplexityThreshold 10