Gate performance tracing behind compile switch

AGENTS.md

@@ -188,3 +188,4 @@ When the user corrects an agent approach, add or tighten one concrete rule here
 - Keep package install/uninstall process launches simple unless explicitly requested; do not add a separate stdout/stderr process logging helper for winget or Chocolatey.
 - When the active log file is owned by `Start-Transcript`, do not call `Add-Content` against that file; write to host output so the transcript captures the line in the same log file without recording a terminating-error diagnostic.
 - Log install/uninstall package names and package-manager IDs before queuing background runspace work; do not rely on runspace host output for the package identity.
+- Keep performance tracing helpers under `tools/perf`; include them in generated output only through `Compile.ps1 -Trace`.

Compile.ps1

@@ -1,21 +1,46 @@
 param (
-    [switch]$Run
+    [switch]$Run,
+    [switch]$Trace
 )
 
 $OFS = "`r`n"
 
+function Remove-WinUtilPerformanceTraceCalls {
+    param(
+        [Parameter(Mandatory = $true)]
+        [string]$Content
+    )
+
+    if ($Trace) {
+        return $Content
+    }
+
+    $filteredLines = $Content -split "`r?`n" | Where-Object {
+        $_ -notmatch '^\s*(Start-WinUtilPerformanceTrace|Stop-WinUtilPerformanceTrace|Write-WinUtilPerformanceCheckpoint)\b'
+    }
+
+    $filteredLines -join "`r`n"
+}
+
 # Variable to sync between runspaces
 $sync = [Hashtable]::Synchronized(@{})
 $sync.configs = @{}
 
 $script = (Get-Content -Path scripts\start.ps1) -replace '#{replaceme}', (Get-Date -Format 'yy.MM.dd')
 
-$script += Get-ChildItem -Path functions -Recurse -File | Get-Content -Raw
+$script += Get-ChildItem -Path functions -Recurse -File | ForEach-Object {
+    Remove-WinUtilPerformanceTraceCalls -Content (Get-Content -Path $_.FullName -Raw)
+}
 
-$script += @'
+if ($Trace) {
+    $script += Get-ChildItem -Path tools\perf -Filter *.ps1 -File | Get-Content -Raw
+
+    $script += @'
+$sync.PerformanceTraceEnabled = $true
 Start-WinUtilPerformanceTrace
 Write-WinUtilPerformanceCheckpoint -Name "Config load start"
 '@
+}
 
 Get-ChildItem config | ForEach-Object {
     $obj = Get-Content -Path $_.FullName -Raw | ConvertFrom-Json
@@ -32,10 +57,14 @@ Get-ChildItem config | ForEach-Object {
 
     $sync.configs[$_.BaseName] = $obj
     $script += "`$sync.configs.$($_.BaseName) = @'`r`n$json`r`n'@ | ConvertFrom-Json"
-    $script += "`r`nWrite-WinUtilPerformanceCheckpoint -Name `"Config $($_.BaseName) loaded`""
+    if ($Trace) {
+        $script += "`r`nWrite-WinUtilPerformanceCheckpoint -Name `"Config $($_.BaseName) loaded`""
+    }
 }
 
-$script += "`r`nWrite-WinUtilPerformanceCheckpoint -Name `"Config load complete`""
+if ($Trace) {
+    $script += "`r`nWrite-WinUtilPerformanceCheckpoint -Name `"Config load complete`""
+}
 
 $xaml = Get-Content -Path xaml\inputXML.xaml -Raw
 $script += "`$inputXML = @'`r`n$xaml`r`n'@"
@@ -43,7 +72,7 @@ $script += "`$inputXML = @'`r`n$xaml`r`n'@"
 $autounattendXml = Get-Content -Path tools\autounattend.xml -Raw
 $script += "`$WinUtilAutounattendXml = @'`r`n$autounattendXml`r`n'@"
 
-$script += Get-Content -Path scripts\main.ps1 -Raw
+$script += Remove-WinUtilPerformanceTraceCalls -Content (Get-Content -Path scripts\main.ps1 -Raw)
 
 Set-Content -Path winutil.ps1 -Value $script
 

pester/performance.Tests.ps1

@@ -6,10 +6,14 @@ BeforeAll {
     $script:repoRoot = (Resolve-Path (Join-Path $PSScriptRoot "..")).Path
 
     . (Join-Path $script:repoRoot "functions\private\Write-WinUtilLog.ps1")
-    . (Join-Path $script:repoRoot "functions\private\Test-WinUtilPerformanceTrace.ps1")
-    . (Join-Path $script:repoRoot "functions\private\Write-WinUtilPerformanceCheckpoint.ps1")
-    . (Join-Path $script:repoRoot "functions\private\Start-WinUtilPerformanceTrace.ps1")
-    . (Join-Path $script:repoRoot "functions\private\Stop-WinUtilPerformanceTrace.ps1")
+    . (Join-Path $script:repoRoot "tools\perf\Test-WinUtilPerformanceTrace.ps1")
+    . (Join-Path $script:repoRoot "tools\perf\Write-WinUtilPerformanceCheckpoint.ps1")
+    . (Join-Path $script:repoRoot "tools\perf\Start-WinUtilPerformanceTrace.ps1")
+    . (Join-Path $script:repoRoot "tools\perf\Stop-WinUtilPerformanceTrace.ps1")
+}
+
+AfterAll {
+    & (Join-Path $script:repoRoot "Compile.ps1")
 }
 
 Describe "WinUtil performance tracing helpers" {
@@ -58,13 +62,34 @@ Describe "WinUtil performance tracing helpers" {
 }
 
 Describe "Startup performance checkpoints" {
-    It "adds config-load checkpoints to compiled output" {
+    It "keeps performance tracing out of normal compiled output" {
+        & (Join-Path $script:repoRoot "Compile.ps1")
+
+        $compiledScript = Get-Content -Path (Join-Path $script:repoRoot "winutil.ps1") -Raw
+
+        $compiledScript | Should -Not -Match "Test-WinUtilPerformanceTrace"
+        $compiledScript | Should -Not -Match "Start-WinUtilPerformanceTrace"
+        $compiledScript | Should -Not -Match "Write-WinUtilPerformanceCheckpoint"
+        $compiledScript | Should -Not -Match "Stop-WinUtilPerformanceTrace"
+        $compiledScript | Should -Not -Match "PerformanceTraceEnabled"
+    }
+
+    It "adds config-load checkpoints only to trace compiled output" {
         $compileScript = Get-Content -Path (Join-Path $script:repoRoot "Compile.ps1") -Raw
 
+        $compileScript | Should -Match '\[switch\]\$Trace'
         $compileScript | Should -Match "Start-WinUtilPerformanceTrace"
         $compileScript | Should -Match "Config load start"
         $compileScript | Should -Match "Config load complete"
         $compileScript | Should -Match "Config .* loaded"
+
+        & (Join-Path $script:repoRoot "Compile.ps1") -Trace
+        $compiledScript = Get-Content -Path (Join-Path $script:repoRoot "winutil.ps1") -Raw
+
+        $compiledScript | Should -Match "function Test-WinUtilPerformanceTrace"
+        $compiledScript | Should -Match '\$sync\.PerformanceTraceEnabled = \$true'
+        $compiledScript | Should -Match "Config load start"
+        $compiledScript | Should -Match "Config load complete"
     }
 
     It "adds runtime checkpoints for startup hotspots" {

pester/xaml.Tests.ps1

@@ -300,8 +300,6 @@ Describe "XAML and sync wiring" {
             "checkmarkrender",
             "warningrender",
             "InitializedTabs",
-            "PerformanceTrace",
-            "PerformanceTraceEnabled",
             "RenderedAssetCache",
             "ToggleStatusCache",
             "InstallAppAreaBorder",
@@ -309,7 +307,6 @@ Describe "XAML and sync wiring" {
             "InstallAppAreaOverlay",
             "InstallAppAreaOverlayText",
             "InstallAppRenderQueue",
-            "InstallAppRenderTimer",
             "InstallAppEntriesRendered",
             "ProgressBar",
             "progressBarTextBlock",