[CmdletBinding(SupportsShouldProcess, DefaultParameterSetName = 'Clean')]

param(

[Parameter(ParameterSetName = 'Version', Mandatory)]

[switch]$Version,

[Parameter(ParameterSetName = 'Version')]

[ValidateSet('text', 'json')]

[string]$Format = 'text',

[Parameter(ParameterSetName = 'Clean')]

[ValidateSet('basic', 'standard', 'deep')]

[string]$Level = 'basic',

[Parameter(ParameterSetName = 'Clean')]

[string]$RootPath,

[Parameter(ParameterSetName = 'Clean')]

[string[]]$ExcludeDirectoryPattern = @(),

[Parameter(ParameterSetName = 'Clean')]

[string[]]$IncludeFilePattern = @(),

[Parameter(ParameterSetName = 'Clean')]

[switch]$PassThru,

[Parameter(ParameterSetName = 'Clean')]

[switch]$Json,

[Parameter(ParameterSetName = 'Clean')]

[switch]$RecycleBin,

# Audit mode: scan only, never deletes. Exit 0 = nothing found, 1 = artifacts found.

# Cannot be combined with -WhatIf.

[Parameter(ParameterSetName = 'Clean')]

[switch]$Check,

# Show the effective merged configuration and exit. No scan or cleanup is performed.

[Parameter(ParameterSetName = 'Clean')]

[switch]$ShowConfig,

# Path to an explicit JSON config file. Loaded at highest config priority (above

# project and local files, below command-line parameters).

[Parameter(ParameterSetName = 'Clean')]

[string]$ConfigFile,

# Controls how much output is produced during a clean or check run.

# detailed - header, per-item lines, and summary (default)

# summary - header and summary only; per-item lines are suppressed

# quiet - no output at all; use the exit code as the signal

[Parameter(ParameterSetName = 'Clean')]

[ValidateSet('detailed', 'summary', 'quiet')]

[string]$OutputLevel = 'detailed'

)

Set-StrictMode -Version Latest

$ErrorActionPreference = 'Stop'

$script:ToolVersion = '1.3.0'

$script:OutputLevel = $OutputLevel

$script:BuiltInExcludeDirs = @('.git', '.vs', '.claude')

if ($Version) {

if ($Format -eq 'json') {

[PSCustomObject]@{

ok = $true

command = 'version'

tool = [PSCustomObject]@{

name = 'delphi-clean'

version = $script:ToolVersion

}

} | ConvertTo-Json -Depth 3 -Compress

}

else {

Write-Output "delphi-clean $script:ToolVersion"

}

exit 0

}

function Write-Detail {

param([AllowEmptyString()][Parameter(Mandatory)][string]$Message)

if ($script:OutputLevel -eq 'detailed' -and -not $Json) {

Write-Information $Message -InformationAction Continue

}

}

function Write-Summary {

param([AllowEmptyString()][Parameter(Mandatory)][string]$Message)

if ($script:OutputLevel -ne 'quiet' -and -not $Json) {

Write-Information $Message -InformationAction Continue

}

}

function Write-Section {

param([AllowEmptyString()][Parameter(Mandatory)][string]$Message)

if ($script:OutputLevel -eq 'detailed' -and -not $Json) {

Write-Information '' -InformationAction Continue

Write-Information ('=' * 70) -InformationAction Continue

Write-Information $Message -InformationAction Continue

Write-Information ('=' * 70) -InformationAction Continue

}

}

function Write-SummarySection {

param([AllowEmptyString()][Parameter(Mandatory)][string]$Message)

if ($script:OutputLevel -ne 'quiet' -and -not $Json) {

Write-Information '' -InformationAction Continue

Write-Information ('=' * 70) -InformationAction Continue

Write-Information $Message -InformationAction Continue

Write-Information ('=' * 70) -InformationAction Continue

}

}

function Format-Duration {

param([long]$Milliseconds)

if ($Milliseconds -lt 1000) { return "$Milliseconds ms" }

return ('{0:N3} s' -f ($Milliseconds / 1000))

}

function Format-ByteSize {

param([long]$Bytes)

if ($Bytes -ge 1GB) { return ('{0:N1} GB' -f ($Bytes / 1GB)) }

if ($Bytes -ge 1MB) { return ('{0:N1} MB' -f ($Bytes / 1MB)) }

if ($Bytes -ge 1KB) { return ('{0:N1} KB' -f ($Bytes / 1KB)) }

return "$Bytes B"

}

function Get-TreeSize {

param(

[Parameter(Mandatory)]

[string]$Path

)

if (-not (Test-Path -LiteralPath $Path)) { return [long]0 }

$total = [long]0

foreach ($f in (Get-ChildItem -Path $Path -Recurse -File -Force -ErrorAction SilentlyContinue)) {

$total += $f.Length

}

return $total

}

function Get-TrashDestination {

param(

[Parameter(Mandatory)]

[string]$TrashFilesDir,

[Parameter(Mandatory)]

[string]$Name

)

$dest = Join-Path $TrashFilesDir $Name

if (-not (Test-Path -LiteralPath $dest)) {

return $dest

}

$base = [System.IO.Path]::GetFileNameWithoutExtension($Name)

$ext = [System.IO.Path]::GetExtension($Name)

$counter = 2

do {

$uniqueName = if ($ext) { "$base $counter$ext" } else { "$Name $counter" }

$dest = Join-Path $TrashFilesDir $uniqueName

$counter++

} while (Test-Path -LiteralPath $dest)

return $dest

}

function Send-ToMacTrash {

param(

[Parameter(Mandatory)]

[string]$Path

)

$trashDir = Join-Path $HOME '.Trash'

if (-not (Test-Path -LiteralPath $trashDir)) {

New-Item -ItemType Directory -Path $trashDir | Out-Null

}

$name = Split-Path -Path $Path -Leaf

$dest = Get-TrashDestination -TrashFilesDir $trashDir -Name $name

Move-Item -LiteralPath $Path -Destination $dest

}

function Send-ToLinuxTrash {

param(

[Parameter(Mandatory)]

[string]$Path

)

$trashRoot = Join-Path $HOME '.local/share/Trash'

$filesDir = Join-Path $trashRoot 'files'

$infoDir = Join-Path $trashRoot 'info'

foreach ($dir in @($filesDir, $infoDir)) {

if (-not (Test-Path -LiteralPath $dir)) {

New-Item -ItemType Directory -Path $dir | Out-Null

}

}

$name = Split-Path -Path $Path -Leaf

$destPath = Get-TrashDestination -TrashFilesDir $filesDir -Name $name

$destName = Split-Path -Path $destPath -Leaf

$infoFile = Join-Path $infoDir "$destName.trashinfo"

$absPath = [System.IO.Path]::GetFullPath($Path)

$timestamp = [datetime]::Now.ToString('yyyy-MM-ddTHH:mm:ss')

$trashInfoContent = "[Trash Info]`nPath=$absPath`nDeletionDate=$timestamp`n"

[System.IO.File]::WriteAllText($infoFile, $trashInfoContent)

try {

Move-Item -LiteralPath $Path -Destination $destPath

}

catch {

Remove-Item -LiteralPath $infoFile -Force -ErrorAction SilentlyContinue

throw

}

}

function Get-PlatformKind {

if (Get-Variable -Name IsWindows -ErrorAction SilentlyContinue) {

if ($IsWindows) { return 'Windows' }

if ($IsMacOS) { return 'macOS' }

if ($IsLinux) { return 'Linux' }

}

switch ([System.Environment]::OSVersion.Platform) {

'Win32NT' { return 'Windows' }

'Unix' {

try {

if ([System.IO.Directory]::Exists('/System/Library/CoreServices')) {

return 'macOS'

}

}

catch {

Write-Verbose "Platform probe for macOS fallback failed: $($_.Exception.Message)"

}

return 'Linux'

}

'MacOSX' { return 'macOS' }

default { return 'Unknown' }

}

}

function Send-ToRecycleBin {

param(

[Parameter(Mandatory)]

[string]$Path,

[Parameter(Mandatory)]

[ValidateSet('File', 'Directory')]

[string]$Type

)

$platformKind = Get-PlatformKind

if ($platformKind -eq 'Windows') {

Add-Type -AssemblyName Microsoft.VisualBasic -ErrorAction Stop

if ($Type -eq 'File') {

[Microsoft.VisualBasic.FileIO.FileSystem]::DeleteFile(

$Path,

[Microsoft.VisualBasic.FileIO.UIOption]::OnlyErrorDialogs,

[Microsoft.VisualBasic.FileIO.RecycleOption]::SendToRecycleBin

)

}

else {

[Microsoft.VisualBasic.FileIO.FileSystem]::DeleteDirectory(

$Path,

[Microsoft.VisualBasic.FileIO.UIOption]::OnlyErrorDialogs,

[Microsoft.VisualBasic.FileIO.RecycleOption]::SendToRecycleBin

)

}

}

elseif ($platformKind -eq 'macOS') {

Send-ToMacTrash -Path $Path

}

elseif ($platformKind -eq 'Linux') {

Send-ToLinuxTrash -Path $Path

}

else {

throw 'Unsupported platform for -RecycleBin.'

}

}

function Get-RelativePathCompat {

param(

[Parameter(Mandatory)]

[string]$BasePath,

[Parameter(Mandatory)]

[string]$TargetPath

)

$baseFull = [System.IO.Path]::GetFullPath($BasePath)

$targetFull = [System.IO.Path]::GetFullPath($TargetPath)

if (-not $baseFull.EndsWith([string][System.IO.Path]::DirectorySeparatorChar)) {

$baseFull += [string][System.IO.Path]::DirectorySeparatorChar

}

$baseUri = New-Object System.Uri($baseFull)

$targetUri = New-Object System.Uri($targetFull)

$relativeUri = $baseUri.MakeRelativeUri($targetUri)

$relativePath = [System.Uri]::UnescapeDataString($relativeUri.ToString()) -replace '/', [System.IO.Path]::DirectorySeparatorChar

if ([string]::IsNullOrWhiteSpace($relativePath)) {

return '.'

}

return $relativePath

}

function Resolve-CleanRoot {

param(

[string]$InputRoot

)

if ([string]::IsNullOrWhiteSpace($InputRoot)) {

return (Get-Location).Path

}

$resolvedInput = Resolve-Path $InputRoot

return $resolvedInput.Path

}

function Test-SafeCleanRoot {

param(

[Parameter(Mandatory)]

[string]$Root

)

$fullRoot = [System.IO.Path]::GetFullPath($Root)

$rootOfRoot = [System.IO.Path]::GetPathRoot($fullRoot)

if ($fullRoot -eq $rootOfRoot) {

throw "Refusing to clean an unsafe root path: $fullRoot"

}

$resolved = Resolve-Path -LiteralPath $fullRoot

if (-not $resolved) {

throw "Invalid root path: $fullRoot"

}

}

function Test-PathUnderExcludedDirectory {

param(

[Parameter(Mandatory)]

[string]$FullName,

[Parameter(Mandatory)]

[string]$Root,

[Parameter(Mandatory)]

[string[]]$ExcludedDirPatterns

)

$relative = Get-RelativePathCompat -BasePath $Root -TargetPath $FullName

if ($relative -eq '.') {

return $false

}

$parts = $relative -split '[\\\/]'

foreach ($part in $parts) {

foreach ($pattern in $ExcludedDirPatterns) {

if ($part -ilike $pattern) {

return $true

}

}

}

return $false

}

function Get-ConfigValue {

param(

[object]$Config,

[Parameter(Mandatory)]

[string]$Key,

$Default = $null

)

if ($null -eq $Config) { return $Default }

$prop = $Config.PSObject.Properties[$Key]

if ($null -eq $prop) { return $Default }

return $prop.Value

}

function Read-ConfigFile {

param(

[Parameter(Mandatory)]

[string]$Path

)

if (-not (Test-Path -LiteralPath $Path)) {

return $null

}

try {

$content = Get-Content -LiteralPath $Path -Raw -Encoding UTF8

return $content | ConvertFrom-Json

}

catch {

Write-Warning "[config] Failed to parse '$Path': $($_.Exception.Message)"

return $null

}

}

function Merge-CleanConfig {

param(

[object[]]$Configs = @()

)

$resultLevel = $null

$resultOutputLevel = $null

$resultRecycleBin = $null

$resultSearchParent = $null

$seenInclude = New-Object 'System.Collections.Generic.HashSet[string]' -ArgumentList ([System.StringComparer]::OrdinalIgnoreCase)

$seenExclude = New-Object 'System.Collections.Generic.HashSet[string]' -ArgumentList ([System.StringComparer]::OrdinalIgnoreCase)

$resultInclude = New-Object 'System.Collections.Generic.List[string]'

$resultExclude = New-Object 'System.Collections.Generic.List[string]'

foreach ($config in $Configs) {

if ($null -eq $config) { continue }

$val = Get-ConfigValue -Config $config -Key 'level'

if ($null -ne $val) { $resultLevel = $val }

$val = Get-ConfigValue -Config $config -Key 'outputLevel'

if ($null -ne $val) { $resultOutputLevel = $val }

$val = Get-ConfigValue -Config $config -Key 'recycleBin'

if ($null -ne $val) { $resultRecycleBin = $val }

$val = Get-ConfigValue -Config $config -Key 'searchParentFolders'

if ($null -ne $val) { $resultSearchParent = $val }

foreach ($item in @(Get-ConfigValue -Config $config -Key 'includeFilePattern' -Default @())) {

if (-not [string]::IsNullOrEmpty($item) -and $seenInclude.Add($item)) {

$resultInclude.Add($item)

}

}

foreach ($item in @(Get-ConfigValue -Config $config -Key 'excludeDirectoryPattern' -Default @())) {

if (-not [string]::IsNullOrEmpty($item) -and $seenExclude.Add($item)) {

$resultExclude.Add($item)

}

}

}

return [PSCustomObject]@{

level = $resultLevel

outputLevel = $resultOutputLevel

recycleBin = $resultRecycleBin

searchParentFolders = $resultSearchParent

includeFilePattern = @($resultInclude)

excludeDirectoryPattern = @($resultExclude)

}

}

function Resolve-EffectiveConfig {

param(

[Parameter(Mandatory)]

[string]$RootPath,

[string]$ConfigFile = ''

)

$log = New-Object 'System.Collections.Generic.List[string]'

$anyConfigFound = $false

# Allow test suites to redirect the home directory lookup.

# Guard against $HOME being null/empty (e.g. minimal CI environments).

$homeDir = if (-not [string]::IsNullOrEmpty($env:DELPHI_CLEAN_HOME_OVERRIDE)) {

$env:DELPHI_CLEAN_HOME_OVERRIDE

} elseif (-not [string]::IsNullOrEmpty($HOME)) {

[string]$HOME

} else {

''

}

$projectConfigPath = Join-Path $RootPath 'delphi-clean.json'

$localConfigPath = Join-Path $RootPath 'delphi-clean.local.json'

$homeConfig = $null

if (-not [string]::IsNullOrEmpty($homeDir)) {

$homeConfigPath = Join-Path $homeDir 'delphi-clean.json'

$homeConfig = Read-ConfigFile -Path $homeConfigPath

Write-Verbose ("[config] user-level: {0}" -f $(if ($null -ne $homeConfig) { $homeConfigPath } else { "$homeConfigPath (not found)" }))

if ($null -ne $homeConfig) { $anyConfigFound = $true; $log.Add("[config] user-level: $homeConfigPath") }

} else {

Write-Verbose '[config] user-level: skipped ($HOME not set)'

}

$projectConfig = Read-ConfigFile -Path $projectConfigPath

$localConfig = Read-ConfigFile -Path $localConfigPath

# Write-Verbose always shows all paths; log only tracks found files

Write-Verbose ("[config] project-level: {0}" -f $(if ($null -ne $projectConfig) { $projectConfigPath } else { "$projectConfigPath (not found)" }))

Write-Verbose ("[config] local override: {0}" -f $(if ($null -ne $localConfig) { $localConfigPath } else { "$localConfigPath (not found)" }))

if ($null -ne $projectConfig) { $anyConfigFound = $true; $log.Add("[config] project-level: $projectConfigPath") }

if ($null -ne $localConfig) { $anyConfigFound = $true; $log.Add("[config] local override: $localConfigPath") }

# Traversal is triggered only by the project-level or local config.

# searchParentFolders in the $HOME config is intentionally ignored.

$traversalRequested = ((Get-ConfigValue -Config $projectConfig -Key 'searchParentFolders') -eq $true) -or

((Get-ConfigValue -Config $localConfig -Key 'searchParentFolders') -eq $true)

$traversedConfigs = @()

if ($traversalRequested) {

$current = Split-Path -Parent $RootPath

while (-not [string]::IsNullOrEmpty($current)) {

$parentConfigPath = Join-Path $current 'delphi-clean.json'

$parentConfig = Read-ConfigFile -Path $parentConfigPath

if ($null -ne $parentConfig) {

# Prepend so farthest ancestor ends up first (lowest priority among traversed)

$traversedConfigs = @($parentConfig) + $traversedConfigs

$anyConfigFound = $true

Write-Verbose "[config] traversed: $parentConfigPath"

$log.Add("[config] traversed: $parentConfigPath")

if ((Get-ConfigValue -Config $parentConfig -Key 'searchParentFolders') -eq $false) {

Write-Verbose '[config] (stop marker -- traversal ends here)'

$log.Add('[config] (stop marker -- traversal ends here)')

break

}

}

$parent = Split-Path -Parent $current

if ($parent -eq $current) { break } # filesystem root reached

$current = $parent

}

}

# Explicit config file (highest config priority, below CLI)

$explicitConfig = $null

if (-not [string]::IsNullOrEmpty($ConfigFile)) {

if (-not (Test-Path -LiteralPath $ConfigFile)) {

Write-Warning "[config] Explicit config file not found: $ConfigFile"

}

else {

$explicitConfig = Read-ConfigFile -Path $ConfigFile

if ($null -ne $explicitConfig) {

$anyConfigFound = $true

Write-Verbose "[config] explicit file: $ConfigFile"

$log.Add("[config] explicit file: $ConfigFile")

}

}

}

# Merge: lowest priority first

$allConfigs = @($homeConfig) + $traversedConfigs + @($projectConfig) + @($localConfig) + @($explicitConfig)

$merged = Merge-CleanConfig -Configs $allConfigs

$finalLogLines = @(

'[config] final merged values:'

("[config] level = {0}" -f $(if ($null -ne $merged.level) { $merged.level } else { '(not set)' }))

("[config] outputLevel = {0}" -f $(if ($null -ne $merged.outputLevel) { $merged.outputLevel } else { '(not set)' }))

("[config] recycleBin = {0}" -f $(if ($null -ne $merged.recycleBin) { "$($merged.recycleBin)" } else { '(not set)' }))

("[config] searchParentFolders = {0}" -f $(if ($null -ne $merged.searchParentFolders) { "$($merged.searchParentFolders)" } else { '(not set)' }))

("[config] includeFilePattern = [{0}]" -f ($merged.includeFilePattern -join ', '))

("[config] excludeDirectoryPattern = [{0}]" -f ($merged.excludeDirectoryPattern -join ', '))

)

foreach ($line in $finalLogLines) { Write-Verbose $line }

return [PSCustomObject]@{

Merged = $merged

Log = $log.ToArray()

ConfigsFound = $anyConfigFound

}

}

function Get-LevelDefinition {

param(

[Parameter(Mandatory)]

[ValidateSet('basic', 'standard', 'deep')]

[string]$Name

)

# --- base (basic) ---

$basicFiles = @(

'*.dcu',

'*.identcache',

'*.bak',

'*.tmp',

'*.tvsconfig',

'*.stat'

)

$basicDirs = @(

'__history'

)

# --- standard additions ---

$standardFilesExtra = @(

'*.drc',

'*.map',

'*.rsm',

'*.tds',

'*.bpl',

'*.dcp',

'*.bpi',

'*.so',

'*.o',

'*.a',

'*.dylib',

'*.exe',

'*.hpp',

'*.dres',

'*.ilc',

'*.ild',

'*.ilf',

'*.ipu',

'*.ddp',

'*.prjmgc',

'*.vlb',

'dunitx-results.xml'

)

$standardDirsExtra = @(

'Win32',

'Win64',

'WinARM64EC',

'Debug',

'Release',

'OSX64',

'OSXARM64',

'Android',

'Android64',

'iOSDevice64',

'iOSSimulatorArm64',

'Linux64',

'LinuxARM64',

'TMSWeb'

)

# --- deep additions ---

$deepFilesExtra = @(

'*.local',

'*.dproj.local',

'*.groupproj.local',

'*.projdata',

'*.dsk',

'*.~*',

'*.lib',

'*.fbpInf',

'*.fbl8',

'*.fbpbrk',

'*.fb8lck',

'*.mab',

'TestInsightSettings.ini'

)

$deepDirsExtra = @(

'__recovery'

)

# --- compose ---

switch ($Name) {

'basic' {

$files = $basicFiles

$dirs = $basicDirs

}

'standard' {

$files = $basicFiles + $standardFilesExtra

$dirs = $basicDirs + $standardDirsExtra

}

'deep' {

$files = $basicFiles + $standardFilesExtra + $deepFilesExtra

$dirs = $basicDirs + $standardDirsExtra + $deepDirsExtra

}

}

# --- dedupe ---

$files = $files | Sort-Object -Unique

$dirs = $dirs | Sort-Object -Unique

return @{

FilePatterns = $files

DirectoryNames = $dirs

}

}

function Get-FilesToDelete {

param(

[Parameter(Mandatory)]

[string]$Root,

[Parameter(Mandatory)]

[string[]]$Patterns,

[Parameter(Mandatory)]

[string[]]$ExcludedDirPatterns

)

Write-Verbose 'Scanning for matching files.'

$examined = 0

$allFiles = Get-ChildItem -Path $Root -Recurse -File -Force -ErrorAction SilentlyContinue |

ForEach-Object {

$examined++

if (-not $Json -and $examined % 500 -eq 0) {

Write-Progress -Activity 'delphi-clean' -Status "Scanning: $examined files examined..."

}

$_

} |

Where-Object {

-not (Test-PathUnderExcludedDirectory -FullName $_.FullName -Root $Root -ExcludedDirPatterns $ExcludedDirPatterns)

}

$allFiles |

Where-Object {

$file = $_

foreach ($pattern in $Patterns) {

if ($file.Name -like $pattern) {

return $true

}

}

return $false

} |

Sort-Object -Property FullName -Unique

}

function Get-DirectoriesToDelete {

param(

[Parameter(Mandatory)]

[string]$Root,

[Parameter(Mandatory)]

[string[]]$DirectoryNames,

[Parameter(Mandatory)]

[string[]]$ExcludedDirPatterns

)

Write-Verbose 'Scanning for matching directories.'

$nameSet = @{}

foreach ($dirName in $DirectoryNames) {

$nameSet[$dirName.ToUpperInvariant()] = $true

}

Get-ChildItem -Path $Root -Recurse -Directory -Force -ErrorAction SilentlyContinue |

Where-Object {

$nameSet.ContainsKey($_.Name.ToUpperInvariant()) -and

-not (Test-PathUnderExcludedDirectory -FullName $_.FullName -Root $Root -ExcludedDirPatterns $ExcludedDirPatterns)

} |

Sort-Object -Property FullName -Unique |

Sort-Object -Property { $_.FullName.Length } -Descending

}

function ConvertTo-DeletionRecord {

param(

[Parameter(Mandatory)]

[ValidateSet('File', 'Directory')]

[string]$Type,

[Parameter(Mandatory)]

[string]$Path,

[Parameter(Mandatory)]

[bool]$Deleted,

[long]$Size = 0

)

[PSCustomObject]@{

Type = $Type

Path = $Path

Deleted = $Deleted

Size = $Size

}

}

function Remove-FileList {

[CmdletBinding(SupportsShouldProcess = $true)]

param(

[System.IO.FileInfo[]]$Files = @(),

[switch]$ReturnRecords,

[switch]$RecycleBin,

[switch]$SuppressWhatIfOutput

)

$result = [PSCustomObject]@{

DeletedCount = 0

FailedCount = 0

BytesFreed = [long]0

Records = New-Object System.Collections.Generic.List[object]

}

if (@($Files).Count -eq 0) {

return $result

}

$action = if ($RecycleBin) { 'Recycle file' } else { 'Delete file' }

$verb = if ($RecycleBin) { 'Recycled' } else { 'Deleted' }

foreach ($file in $Files) {

Write-Verbose "Evaluating file: $($file.FullName)"

if ($WhatIfPreference -and $SuppressWhatIfOutput) {

Write-Detail "Would $($action.ToLower()): $($file.FullName)"