utils: surface failures from -Clean

`Remove-Item -ErrorAction Ignore` silently swallows failures, which
on Windows happens whenever any file in the target tree is held by
another process (an in-flight build, an editor, virus scanning, etc.).
The result is a partially-deleted build directory: subsequent `ninja`
runs then treat the stale survivors as up-to-date, so a header API
change produces objects that link against a signature no longer present
in their dependent libraries.

Wrap each removal in a small helper that:

- skips paths that do not exist (so a first-time clean is not an
  error),
- runs `Remove-Item` with `-ErrorAction Stop`, and
- on failure throws a clear message naming the path and the likely
  cause.

Also correct the parameter docstring; the previous text described a
behavior that has not matched the implementation in some time.

Author: compnerd

utils/build.ps1

@@ -95,8 +95,10 @@ An array of architectures for which the Windows Swift SDK should be built.
 Default: @("X64","X86","ARM64")
 
 .PARAMETER Clean
-Clean non-compiler builds while building. Use this for a fresh build when
-experiencing issues.
+Wipe the per-triple build directories under `$BinaryCache` (host and target
+SDK builds, including all compiler stages) and the host install directory
+before building.  Downloaded dependencies are preserved.  Builds for
+platforms not selected by the current invocation are not removed.
 
 .PARAMETER SkipBuild
 Skip the build phase entirely. Useful for testing packaging or other post-build
@@ -4828,21 +4830,35 @@ try {
 Get-Dependencies
 
 if ($Clean) {
-  Remove-Item -Force -Recurse -Path "$BinaryCache\$($BuildPlatform.Triple)\" -ErrorAction Ignore
-  Remove-Item -Force -Recurse -Path "$BinaryCache\$($HostPlatform.Triple)\" -ErrorAction Ignore
+  # Recursively delete a build directory, failing loudly if the tree cannot
+  # be fully removed.  `Remove-Item -ErrorAction Ignore` silently leaves
+  # locked-file siblings behind, producing a partially-cleaned tree where
+  # ninja then treats stale objects as up-to-date.  Surface the failure
+  # so the caller can close the offending process and retry.
+  function Clean-Path([string] $Path) {
+    if (-not (Test-Path -LiteralPath $Path)) { return }
+    try {
+      Remove-Item -Force -Recurse -LiteralPath $Path -ErrorAction Stop
+    } catch {
+      throw "Failed to clean '$Path'; a file is likely locked by a running process (build, editor, or virus scanner).  Close it and retry.  Inner error: $_"
+    }
+  }
+
+  Clean-Path "$BinaryCache\$($BuildPlatform.Triple)"
+  Clean-Path "$BinaryCache\$($HostPlatform.Triple)"
   foreach ($Build in $WindowsSDKBuilds) {
-    Remove-Item -Force -Recurse -Path "$BinaryCache\$($Build.Triple)\" -ErrorAction Ignore
+    Clean-Path "$BinaryCache\$($Build.Triple)"
   }
   foreach ($Build in $AndroidSDKBuilds) {
-    Remove-Item -Force -Recurse -Path "$BinaryCache\$($Build.Triple)\" -ErrorAction Ignore
+    Clean-Path "$BinaryCache\$($Build.Triple)"
   }
-  Remove-Item -Force -Recurse -Path "$BinaryCache\1" -ErrorAction Ignore
-  Remove-Item -Force -Recurse -Path "$BinaryCache\5" -ErrorAction Ignore
-  Remove-Item -Force -Recurse -Path (Get-InstallDir $HostPlatform) -ErrorAction Ignore
+  Clean-Path "$BinaryCache\1"
+  Clean-Path "$BinaryCache\5"
+  Clean-Path (Get-InstallDir $HostPlatform)
 
   Get-SelectedSDKBuilds | ForEach-Object {
-    Remove-Item -Force -Recurse -Path (Get-ProjectBinaryCache $_ ClangBuiltins) -ErrorAction Ignore
-    Remove-Item -Force -Recurse -Path (Get-ProjectBinaryCache $_ ClangRuntime) -ErrorAction Ignore
+    Clean-Path (Get-ProjectBinaryCache $_ ClangBuiltins)
+    Clean-Path (Get-ProjectBinaryCache $_ ClangRuntime)
   }
 }