mutate.ps1

# usbspeed mutation harness
#
# A test suite that passes proves nothing on its own -- it only proves the tests
# tolerate the current code. This harness deliberately breaks usbspeed.ps1, one
# edit at a time, and requires the suites to NOTICE. A mutation the suites do not
# notice is a SURVIVOR: a line of the tool that nothing is actually testing.
#
# Three things make the score honest:
#   1. ANCHOR VALIDATION. A mutation whose anchor text does not exist in the
#      source patches nothing, runs the unmodified tool, and is reported as
#      "killed" by a suite that never saw a mutant. Every anchor here must match
#      EXACTLY ONCE or the mutation is reported as an INVALID CONTROL and is
#      excluded from the score.
#   2. PAIRED EDITS. Redundantly defensive code produces equivalent mutants:
#      removing either half alone changes nothing observable. The fix is to
#      remove both halves in one mutation, not to delete the assertion.
#   3. NO-OP EXCLUSION. A mutation with no semantic effect (a comment reword)
#      cannot be killed by anything. Counting it as a pass would inflate the
#      score, so it is run, reported, and excluded.
#
# Read-only with respect to the user's machine: it copies the tool into a temp
# directory, mutates the copy, and deletes the directory afterwards.
#
# Run:  powershell.exe -NoProfile -ExecutionPolicy Bypass -File mutate.ps1

[CmdletBinding()]
param([switch]$Fast)

Set-StrictMode -Version Latest
$ErrorActionPreference = 'Stop'

$m_here = Split-Path -Parent $MyInvocation.MyCommand.Path
$m_tool = Join-Path $m_here 'usbspeed.ps1'
$m_self = Join-Path $m_here 'selftest.ps1'
$m_real = Join-Path $m_here 'realcheck.ps1'

foreach ($m_f in @($m_tool, $m_self, $m_real)) {
    if (-not (Test-Path -LiteralPath $m_f)) {
        Write-Host ('missing: ' + $m_f) -ForegroundColor Red
        exit 2
    }
}

$m_src = [IO.File]::ReadAllText($m_tool)

Write-Host ''
Write-Host 'usbspeed mutation harness' -ForegroundColor Cyan
Write-Host ('source: ' + [string]$m_src.Length + ' chars')
if ($Fast) { Write-Host 'fast mode: hermetic suite only (C#-layer mutations will be reported as NOT RUN)' -ForegroundColor Yellow }
Write-Host ''

# ---------------------------------------------------------------------------
# The mutations.
#
# Layer 'ps'  -> expected to die in the hermetic suite (selftest.ps1).
# Layer 'c#'  -> touches the native ioctl layer, so only real hardware can tell;
#                expected to die in realcheck.ps1.
# ---------------------------------------------------------------------------

$m_muts = @(
    # --- speed resolution -------------------------------------------------
    @{ id = 'speed-table-high'; layer = 'ps'
       desc = 'High-Speed listed as 4800 Mbps instead of 480'
       edits = @(@{ from = '; 2 = 480.0;'; to = '; 2 = 4800.0;' }) }

    @{ id = 'ssp-mbps'; layer = 'ps'
       desc = 'SuperSpeedPlus reported as 1 Gbps instead of 10'
       edits = @(@{ from = '$mbps = 10000.0'; to = '$mbps = 1000.0' }) }

    @{ id = 'opss-bit'; layer = 'ps'
       desc = 'operating-at-SuperSpeed read from the capability bit'
       edits = @(@{ from = '$opSS   = (($Flags -band [long]1) -ne 0)'
                    to   = '$opSS   = (($Flags -band [long]2) -ne 0)' }) }

    @{ id = 'capss-bit'; layer = 'ps'
       desc = 'SuperSpeed-capable read from the wrong flag bit'
       edits = @(@{ from = '$capSS  = (($Flags -band [long]2) -ne 0)'
                    to   = '$capSS  = (($Flags -band [long]4) -ne 0)' }) }

    @{ id = 'opssp-bit'; layer = 'ps'
       desc = 'operating-at-SuperSpeedPlus read from the SSP capability bit'
       edits = @(@{ from = '$opSSP  = (($Flags -band [long]4) -ne 0)'
                    to   = '$opSSP  = (($Flags -band [long]8) -ne 0)' }) }

    @{ id = 'ssp-before-ss'; layer = 'ps'
       desc = 'SuperSpeed tested before SuperSpeedPlus, so 10 Gbps reads as 5'
       edits = @(@{ from = '    if ($opSSP) {'; to = '    if ($opSS) {' }) }

    # --- connector properties --------------------------------------------
    @{ id = 'userconn-bit'; layer = 'ps'
       desc = 'user-connectable read from the debug-capable bit'
       edits = @(@{ from = '$userConn = (($cflags -band [long]1) -ne 0)'
                    to   = '$userConn = (($cflags -band [long]2) -ne 0)' }) }

    @{ id = 'typec-bit'; layer = 'ps'
       desc = 'USB-C connector read from the multiple-companions bit'
       edits = @(@{ from = '$typeC    = (($cflags -band [long]8) -ne 0)'
                    to   = '$typeC    = (($cflags -band [long]4) -ne 0)' }) }

    # --- the cry-wolf discriminator (the tool's central design decision) ---
    @{ id = 'cry-wolf-guard'; layer = 'ps'
       desc = 'drops the user-connectable test, so every internal 2.0 hub half is a fault'
       edits = @(@{ from = 'if ($ConnOk -eq 1 -and $UserConnectable) {'
                    to   = 'if ($ConnOk -eq 1) {' }) }

    @{ id = 'capss-and-to-or'; layer = 'ps'
       desc = 'below-capability test uses -or, flagging healthy SuperSpeed links'
       edits = @(@{ from = 'if ($CapSS -and (-not $OpSS)) {'
                    to   = 'if ($CapSS -or (-not $OpSS)) {' }) }

    @{ id = 'lowpower-code'; layer = 'ps'
       desc = 'power fault emits the wrong verdict code'
       edits = @(@{ from = "Code = 'LOW-POWER';"; to = "Code = 'NO-POWER';" }) }

    # --- descriptor sanity ------------------------------------------------
    @{ id = 'dlen-check'; layer = 'ps'
       desc = 'accepts a 17-byte device descriptor as sane'
       edits = @(@{ from = 'if ($DLen -ne 18) { return $false }'
                    to   = 'if ($DLen -ne 17) { return $false }' }) }

    @{ id = 'dtype-check'; layer = 'ps'
       desc = 'accepts descriptor type 0 instead of 1'
       edits = @(@{ from = 'if ($DType -ne 1) { return $false }'
                    to   = 'if ($DType -ne 0) { return $false }' }) }

    @{ id = 'status-bound'; layer = 'ps'
       desc = 'connection-status upper bound widened to 1000, so garbage passes'
       edits = @(@{ from = '$Status -gt 10'; to = '$Status -gt 1000' }) }

    # --- derived values ---------------------------------------------------
    @{ id = 'bcd-shift'; layer = 'ps'
       desc = 'bcdUSB major nibble shifted 4 instead of 8'
       edits = @(@{ from = '(($Bcd -band 0xFF00) -shr 8)'
                    to   = '(($Bcd -band 0xFF00) -shr 4)' }) }

    @{ id = 'understate-inverted'; layer = 'ps'
       desc = 'understatement factor computed upside down'
       edits = @(@{ from = '[math]::Round($spd.Mbps / $legacyMbps, 2)'
                    to   = '[math]::Round($legacyMbps / $spd.Mbps, 2)' }) }

    @{ id = 'empty-port-guard'; layer = 'ps'
       desc = 'vacant ports fall through the guard and report a 1.5 Mbps link'
       edits = @(@{ from = '    if ($status -ne 1) {'; to = '    if ($status -ne 0) {' }) }

    # --- PAIRED: hub path matching is case-insensitive THREE times over. -----
    # Both sides are lowercased AND PowerShell's -eq is itself case-insensitive.
    # Removing either .ToLowerInvariant() alone -- or even both -- changes
    # nothing observable, because -eq still ignores case. That is an equivalent
    # mutant, and the answer is to remove ALL the redundancy in one mutation
    # rather than to delete the assertion that "failed" to catch it.
    @{ id = 'hub-match-case (paired)'; layer = 'ps'
       desc = 'all three layers of case-insensitive hub matching removed together'
       edits = @(
            @{ from = '$target = $HubPath.ToLowerInvariant()'; to = '$target = $HubPath' }
            @{ from = 'if ($p.Hub.ToLowerInvariant() -eq $target)'; to = 'if ($p.Hub -ceq $target)' }) }

    # --- glyph fallback ---------------------------------------------------
    @{ id = 'glyph-survives'; layer = 'ps'
       desc = 'glyph round-trip always claims success, so box drawing is never downgraded'
       edits = @(@{ from = 'return ($back -eq $S)'; to = 'return $true' }) }

    # --- native ioctl layer (only real hardware can judge these) ----------
    @{ id = 'u16-signed'; layer = 'c#'
       desc = 'Marshal.ReadInt16 left signed, so vendor id 0x8087 reads negative'
       edits = @(@{ from = 'return Marshal.ReadInt16(p, off) & 0xFFFF;'
                    to   = 'return Marshal.ReadInt16(p, off);' }) }

    @{ id = 'v2-input-bit'; layer = 'c#'
       desc = 'Usb300 input bit cleared, so the V2 ioctl returns error 87 everywhere'
       edits = @(@{ from = 'Marshal.WriteInt32(vb, 8, 4);'
                    to   = 'Marshal.WriteInt32(vb, 8, 0);' }) }

    @{ id = 'legacy-offset'; layer = 'c#'
       desc = 'Speed read one byte early, landing on CurrentConfigurationValue'
       edits = @(@{ from = 'legacy = U8(eb, 23);'; to = 'legacy = U8(eb, 22);' }) }

    @{ id = 'addr-offset'; layer = 'c#'
       desc = 'DeviceAddress read at the natural-alignment offset instead of the pack(1) one'
       edits = @(@{ from = 'addr   = U16(eb, 25);'; to = 'addr   = U16(eb, 26);' }) }

    @{ id = 'pipes-offset'; layer = 'c#'
       desc = 'NumberOfOpenPipes read one byte late'
       edits = @(@{ from = 'pipes  = Marshal.ReadInt32(eb, 27);'
                    to   = 'pipes  = Marshal.ReadInt32(eb, 28);' }) }

    @{ id = 'status-offset'; layer = 'c#'
       desc = 'ConnectionStatus read one byte late'
       edits = @(@{ from = 'status = Marshal.ReadInt32(eb, 31);'
                    to   = 'status = Marshal.ReadInt32(eb, 32);' }) }

    @{ id = 'hub-ports-offset'; layer = 'c#'
       desc = 'HighestPortNumber read at offset 6 instead of 4'
       edits = @(@{ from = 'portsEx = U16(hb, 4);'; to = 'portsEx = U16(hb, 6);' }) }

    @{ id = 'port-clamp-too-low'; layer = 'c#'
       desc = 'spec port ceiling lowered to 4, silently truncating every real hub'
       edits = @(@{ from = 'const int MAX_HUB_PORTS           = 255;'
                    to   = 'const int MAX_HUB_PORTS           = 4;' }) }

    @{ id = 'clamp-flag-never-set'; layer = 'ps'
       desc = 'clamp flag hardcoded off, hiding a truncated enumeration'
       edits = @(@{ from = "PortsClamped  = ([int](Get-IntField -Map `$Fields -Name 'portsclamped' -Default 0) -eq 1)"
                    to   = 'PortsClamped  = $false' }) }

    # --- declared no-op: excluded from the score, not counted as a pass ---
    @{ id = 'noop-comment'; layer = 'ps'; noop = $true
       desc = 'reword a comment; no suite can or should detect this'
       edits = @(@{ from = 'which maps to Low-Speed / 1.5 Mbps.'
                    to   = 'which maps to Low-Speed / 1.5 Mbit.' }) }
)

# ---------------------------------------------------------------------------

function m_CountOccurrences {
    param([string]$Text, [string]$Needle)
    $n = 0
    $i = $Text.IndexOf($Needle, [StringComparison]::Ordinal)
    while ($i -ge 0) {
        $n++
        $i = $Text.IndexOf($Needle, $i + 1, [StringComparison]::Ordinal)
    }
    return $n
}

function m_RunSuite {
    param([string]$Script, [string]$WorkDir, [int]$TimeoutSec = 240)
    $out = Join-Path $WorkDir ('out-' + [IO.Path]::GetFileNameWithoutExtension($Script) + '.txt')
    $pr = Start-Process -FilePath 'powershell.exe' `
            -ArgumentList @('-NoProfile', '-ExecutionPolicy', 'Bypass', '-File', $Script) `
            -WorkingDirectory $WorkDir -PassThru -WindowStyle Hidden `
            -RedirectStandardOutput $out -RedirectStandardError (Join-Path $WorkDir 'err.txt')

    # Start-Process -PassThru WITHOUT -Wait returns a Process whose ExitCode is
    # $null even after WaitForExit() returns $true and HasExited is $true.
    # Touching .Handle first makes PowerShell retain the process handle so the
    # exit code survives. Without this line every mutant reads ExitCode $null,
    # `$null -ne 0` is TRUE, and the harness reports a 100% kill rate no matter
    # what it did to the source -- including for mutations that change nothing.
    $null = $pr.Handle

    # A mutant can HANG rather than fail: capping a hub's port count by spec was
    # added precisely because a bad HighestPortNumber made the tool issue three
    # ioctls per phantom port. Without a timeout the harness stalls forever on
    # exactly the bug it is meant to surface.
    if (-not $pr.WaitForExit($TimeoutSec * 1000)) {
        try { $pr.Kill() } catch { }
        return -999
    }
    $code = $pr.ExitCode
    if ($null -eq $code) { throw ('could not read an exit code for ' + $Script) }
    return [int]$code
}

$m_root = Join-Path $env:TEMP ('usbspeed-mutate-' + [string]$PID)
if (Test-Path -LiteralPath $m_root) { Remove-Item -LiteralPath $m_root -Recurse -Force }
[void](New-Item -ItemType Directory -Path $m_root -Force)

# ---------------------------------------------------------------------------
# BASELINE CONTROL. A mutation harness that cannot recognise a HEALTHY tool
# reports a perfect score against everything, including edits that change
# nothing. Before judging a single mutant, run the UNMODIFIED source through the
# exact same runner and require both suites to pass. If this fails, every number
# below would be meaningless, so the harness refuses to produce one.
# ---------------------------------------------------------------------------
Write-Host 'baseline control: unmutated source must PASS both suites through this runner' -ForegroundColor Cyan
$m_base = Join-Path $m_root '_baseline'
[void](New-Item -ItemType Directory -Path $m_base -Force)
Copy-Item -LiteralPath $m_tool -Destination (Join-Path $m_base 'usbspeed.ps1')
Copy-Item -LiteralPath $m_self -Destination (Join-Path $m_base 'selftest.ps1')
Copy-Item -LiteralPath $m_real -Destination (Join-Path $m_base 'realcheck.ps1')

$m_b1 = m_RunSuite -Script (Join-Path $m_base 'selftest.ps1') -WorkDir $m_base
Write-Host ('  selftest  on clean source -> exit ' + [string]$m_b1)
$m_b2 = 0
if (-not $Fast) {
    $m_b2 = m_RunSuite -Script (Join-Path $m_base 'realcheck.ps1') -WorkDir $m_base
    Write-Host ('  realcheck on clean source -> exit ' + [string]$m_b2)
}
if ($m_b1 -ne 0 -or $m_b2 -ne 0) {
    Write-Host 'BASELINE FAILED: the suites do not pass on unmodified source, so no kill can be trusted.' -ForegroundColor Red
    Remove-Item -LiteralPath $m_root -Recurse -Force -ErrorAction SilentlyContinue
    exit 2
}
Write-Host '  baseline OK -- a pass is distinguishable from a failure' -ForegroundColor Green
Write-Host ''

$m_killed   = 0
$m_survived = New-Object Collections.ArrayList
$m_invalid  = New-Object Collections.ArrayList
$m_excluded = New-Object Collections.ArrayList
$m_notrun   = New-Object Collections.ArrayList
$m_total    = 0

foreach ($m_mut in $m_muts) {
    $m_id = [string]$m_mut.id
    $m_isNoop = $false
    if ($m_mut.ContainsKey('noop')) { $m_isNoop = [bool]$m_mut.noop }

    # --- anchor validation: every anchor must match EXACTLY once ----------
    $m_bad = ''
    foreach ($m_e in $m_mut.edits) {
        $m_n = m_CountOccurrences -Text $m_src -Needle ([string]$m_e.from)
        if ($m_n -ne 1) {
            $m_bad = 'anchor matched ' + [string]$m_n + ' times: ' + [string]$m_e.from
            break
        }
    }
    if ($m_bad -ne '') {
        [void]$m_invalid.Add($m_id + ' -- ' + $m_bad)
        Write-Host ('[INVALID] ' + $m_id + ' -- ' + $m_bad) -ForegroundColor Magenta
        continue
    }

    # --- apply ------------------------------------------------------------
    $m_new = $m_src
    foreach ($m_e in $m_mut.edits) {
        $m_new = $m_new.Replace([string]$m_e.from, [string]$m_e.to)
    }
    if ($m_new -eq $m_src) {
        [void]$m_invalid.Add($m_id + ' -- replacement is byte-identical to the original')
        Write-Host ('[INVALID] ' + $m_id + ' -- produced no change') -ForegroundColor Magenta
        continue
    }

    $m_dir = Join-Path $m_root $m_id.Replace(' ', '_').Replace('(', '').Replace(')', '')
    [void](New-Item -ItemType Directory -Path $m_dir -Force)
    [IO.File]::WriteAllText((Join-Path $m_dir 'usbspeed.ps1'), $m_new, (New-Object Text.UTF8Encoding($false)))
    Copy-Item -LiteralPath $m_self -Destination (Join-Path $m_dir 'selftest.ps1')
    Copy-Item -LiteralPath $m_real -Destination (Join-Path $m_dir 'realcheck.ps1')

    # --- judge ------------------------------------------------------------
    $m_by = ''
    $m_rc = m_RunSuite -Script (Join-Path $m_dir 'selftest.ps1') -WorkDir $m_dir
    if ($m_rc -eq -999) { $m_by = 'selftest(timeout)' }
    elseif ($m_rc -ne 0) { $m_by = 'selftest' }

    if ($m_by -eq '' -and (-not $Fast)) {
        $m_rc2 = m_RunSuite -Script (Join-Path $m_dir 'realcheck.ps1') -WorkDir $m_dir
        if ($m_rc2 -eq -999) { $m_by = 'realcheck(timeout)' }
        elseif ($m_rc2 -ne 0) { $m_by = 'realcheck' }
    }

    if ($m_isNoop) {
        if ($m_by -eq '') {
            [void]$m_excluded.Add($m_id + ' -- ' + [string]$m_mut.desc)
            Write-Host ('[EXCLUDED] ' + $m_id + ' (declared no-op, survived as expected)') -ForegroundColor DarkGray
        } else {
            [void]$m_survived.Add($m_id + ' -- declared a no-op but ' + $m_by + ' failed; the declaration is wrong')
            Write-Host ('[BOGUS] ' + $m_id + ' -- declared no-op was killed by ' + $m_by) -ForegroundColor Red
        }
        continue
    }

    $m_total++
    if ($m_by -ne '') {
        $m_killed++
        Write-Host ('[KILLED]  ' + $m_id.PadRight(26) + ' by ' + $m_by.PadRight(10) + ' -- ' + [string]$m_mut.desc) -ForegroundColor Green
    } else {
        if ($Fast -and [string]$m_mut.layer -eq 'c#') {
            $m_total--
            [void]$m_notrun.Add($m_id)
            Write-Host ('[NOT RUN] ' + $m_id + ' (needs real hardware; -Fast skipped realcheck)') -ForegroundColor Yellow
        } else {
            [void]$m_survived.Add($m_id + ' -- ' + [string]$m_mut.desc)
            Write-Host ('[SURVIVED] ' + $m_id + ' -- ' + [string]$m_mut.desc) -ForegroundColor Red
        }
    }
}

Remove-Item -LiteralPath $m_root -Recurse -Force -ErrorAction SilentlyContinue

Write-Host ''
Write-Host ('mutation score: ' + [string]$m_killed + '/' + [string]$m_total) -ForegroundColor Cyan
Write-Host ('invalid controls (anchor did not match exactly once): ' + [string]$m_invalid.Count)
Write-Host ('excluded as declared no-ops: ' + [string]$m_excluded.Count)
foreach ($m_x in $m_excluded) { Write-Host ('  ' + $m_x) -ForegroundColor DarkGray }
if ($m_notrun.Count -gt 0) {
    Write-Host ('not run (-Fast): ' + [string]$m_notrun.Count)
    foreach ($m_x in $m_notrun) { Write-Host ('  ' + $m_x) -ForegroundColor Yellow }
}
foreach ($m_x in $m_invalid) { Write-Host ('  INVALID: ' + $m_x) -ForegroundColor Magenta }
foreach ($m_x in $m_survived) { Write-Host ('  SURVIVOR: ' + $m_x) -ForegroundColor Red }

if ($m_survived.Count -eq 0 -and $m_invalid.Count -eq 0 -and $m_killed -eq $m_total) {
    Write-Host 'mutate OK' -ForegroundColor Green
    exit 0
}
exit 1