- Fix -Json -WhatIf so PowerShell WhatIf host messages are suppressed and

  standard output remains a single JSON object
- Update JSON output documentation to match the current `Mode` values emitted
  by the script: `Execute`, `WhatIf (no changes)`, and `Check (no changes)`

Author: darianmiller

CHANGELOG.md

@@ -4,10 +4,17 @@ All notable changes to this project will be documented in this file.
 
 ---
 
+## [Unreleased]
+
+- Fix `-Json -WhatIf` so PowerShell WhatIf host messages are suppressed and
+  standard output remains a single JSON object
+- Update JSON output documentation to match the current `Mode` values emitted
+  by the script: `Execute`, `WhatIf (no changes)`, and `Check (no changes)`
+
 ## [0.12.0] 2026-04-23
 
 - Add `WinARM64EC` to list of directories in Standard cleanup level
-for Delphi 13.  [#12](https://github.com/continuous-delphi/delphi-clean/issues/23)
+for Delphi 13.  [#23](https://github.com/continuous-delphi/delphi-clean/issues/23)
 
 ## [0.11.0] 2026-04-23
 

docs/json-output.md

@@ -16,7 +16,7 @@ This object is returned after a scan, whether or not files are deleted.
   "Root": "C:/code/myproject",
   "ExcludeDirectoryPattern": [".git", ".vs", ".claude"],
   "IncludeFilePattern": [],
-  "Mode": "Clean",
+  "Mode": "Execute",
   "Disposition": "Permanent",
   "RecycleBin": false,
   "Check": false,
@@ -43,7 +43,7 @@ This object is returned after a scan, whether or not files are deleted.
 | `Root` | string | Absolute path of the scanned root directory |
 | `ExcludeDirectoryPattern` | string array | Combined list of built-in and user-supplied exclusion patterns |
 | `IncludeFilePattern` | string array | Additional file patterns supplied via config or `-IncludeFilePattern` |
-| `Mode` | string | `Clean`, `WhatIf`, or `Check` |
+| `Mode` | string | `Execute`, `WhatIf (no changes)`, or `Check (no changes)` |
 | `Disposition` | string | `Permanent` or `Recycle Bin` |
 | `RecycleBin` | boolean | Whether `-RecycleBin` was active |
 | `Check` | boolean | Whether `-Check` was active |
@@ -73,9 +73,9 @@ during the scan.
 
 | Value | When set |
 |-------|----------|
-| `Clean` | Normal run -- items are deleted (or recycled) |
-| `WhatIf` | `-WhatIf` was supplied -- scan only, no deletions |
-| `Check` | `-Check` was supplied -- scan only, no deletions |
+| `Execute` | Normal run -- items are deleted (or recycled) |
+| `WhatIf (no changes)` | `-WhatIf` was supplied -- scan only, no deletions |
+| `Check (no changes)` | `-Check` was supplied -- scan only, no deletions |
 
 ---
 
@@ -90,7 +90,7 @@ with zeroed counters and an empty `Items` array.
   "Root": "C:/code/myproject",
   "ExcludeDirectoryPattern": [".git", ".vs", ".claude"],
   "IncludeFilePattern": [],
-  "Mode": "Clean",
+  "Mode": "Execute",
   "Disposition": "Permanent",
   "RecycleBin": false,
   "Check": false,

source/delphi-clean.ps1

@@ -975,7 +975,8 @@ function Remove-FileList {
     param(
         [System.IO.FileInfo[]]$Files = @(),
         [switch]$ReturnRecords,
-        [switch]$RecycleBin
+        [switch]$RecycleBin,
+        [switch]$SuppressWhatIfOutput
     )
 
     $result = [PSCustomObject]@{
@@ -995,6 +996,14 @@ function Remove-FileList {
     foreach ($file in $Files) {
         Write-Verbose "Evaluating file: $($file.FullName)"
 
+        if ($WhatIfPreference -and $SuppressWhatIfOutput) {
+            Write-Detail "Would $($action.ToLower()): $($file.FullName)"
+            if ($ReturnRecords) {
+                $result.Records.Add((ConvertTo-DeletionRecord -Type File -Path $file.FullName -Deleted $false -Size $file.Length))
+            }
+            continue
+        }
+
         if ($PSCmdlet.ShouldProcess($file.FullName, $action)) {
             try {
                 if ($RecycleBin) {
@@ -1036,7 +1045,8 @@ function Remove-DirectoryList {
     param(
         [System.IO.DirectoryInfo[]]$Directories = @(),
         [switch]$ReturnRecords,
-        [switch]$RecycleBin
+        [switch]$RecycleBin,
+        [switch]$SuppressWhatIfOutput
     )
 
     $result = [PSCustomObject]@{
@@ -1063,6 +1073,14 @@ function Remove-DirectoryList {
         # Compute size before any deletion so it is available for the record regardless of outcome
         $dirSize = Get-TreeSize -Path $dir.FullName
 
+        if ($WhatIfPreference -and $SuppressWhatIfOutput) {
+            Write-Detail "Would $($action.ToLower()): $($dir.FullName)"
+            if ($ReturnRecords) {
+                $result.Records.Add((ConvertTo-DeletionRecord -Type Directory -Path $dir.FullName -Deleted $false -Size $dirSize))
+            }
+            continue
+        }
+
         if ($PSCmdlet.ShouldProcess($dir.FullName, $action)) {
             try {
                 if ($RecycleBin) {
@@ -1344,9 +1362,9 @@ try {
     # Normal clean path
     Write-Section 'Cleaning'
     if (-not $Json) { Write-Progress -Activity 'delphi-clean' -Status "Removing $($filesToDelete.Count) files..." }
-    $fileRemovalResult = Remove-FileList      -Files $filesToDelete       -ReturnRecords:$returnRecords -RecycleBin:$RecycleBin
+    $fileRemovalResult = Remove-FileList      -Files $filesToDelete       -ReturnRecords:$returnRecords -RecycleBin:$RecycleBin -SuppressWhatIfOutput:$Json
     if (-not $Json) { Write-Progress -Activity 'delphi-clean' -Status "Removing $($dirsToDelete.Count) directories..." }
-    $dirRemovalResult  = Remove-DirectoryList -Directories $dirsToDelete  -ReturnRecords:$returnRecords -RecycleBin:$RecycleBin
+    $dirRemovalResult  = Remove-DirectoryList -Directories $dirsToDelete  -ReturnRecords:$returnRecords -RecycleBin:$RecycleBin -SuppressWhatIfOutput:$Json
     if (-not $Json) { Write-Progress -Activity 'delphi-clean' -Completed }
 
     $allRecords = New-Object System.Collections.Generic.List[object]

tests/pwsh/delphi-clean.Integration.Tests.ps1

@@ -66,6 +66,14 @@ Describe 'delphi-clean.ps1 integration tests' {
     @($result.Items).Count | Should -BeGreaterThan 0
   }
 
+  It 'suppresses WhatIf host output in JSON mode' {
+    $output = @(& $script:ToolPath -RootPath $script:TempRoot -Level standard -Json -WhatIf *>&1)
+
+    $output.Count | Should -Be 1
+    [string]$output[0] | Should -Not -Match '^What if:'
+    { [string]$output[0] | ConvertFrom-Json } | Should -Not -Throw
+  }
+
   It 'JSON output includes DurationMs as a non-negative integer' {
     $jsonText = & $script:ToolPath -RootPath $script:TempRoot -Level standard -Json -WhatIf
     $result = $jsonText | ConvertFrom-Json