Add JSON configuration file support with merge hierarchy for Issue #21

CHANGELOG.md

@@ -4,6 +4,43 @@ All notable changes to this project will be documented in this file.
 
 ---
 
+## [0.10.0] 2026-04-04
+
+- Add JSON configuration file hierarchy
+  (`$HOME`, project-level, local override, `-ConfigFile`)
+  with scalar-override and array-append merge rules and optional
+  upward traversal via `searchParentFolders`
+  See `docs/configuration.md` for details.
+
+- Add `-ConfigFile <path>` to inject an explicit config file (e.g. for CI
+  pipelines) at highest config priority below command-line parameters.
+
+- Add `-ShowConfig` to display the effective merged configuration and exit
+  without scanning or cleaning. Supports `-Json` for machine-readable output.
+
+- Add freed-space reporting to the clean summary:
+  `Space freed : 142.3 MB` (text) or `BytesFreed` (JSON).
+  Also reported in `-Check` mode as `Space to free` and in `-WhatIf` mode
+  as `Space would free`.
+
+- Add elapsed time to all summaries (`Duration` in text, `DurationMs` in JSON).
+
+- Add `Size` (bytes) to every item in the JSON `Items` array, covering both
+  files (direct length) and directories (recursive sum computed before deletion).
+
+- Add `Write-Progress` feedback during file scan (updates every 500 files) and
+  during the deletion phase; suppressed when `-Json` is active.
+
+- Add cross-platform build artifact patterns to the `standard` level:
+  `*.o`, `*.a` (Linux/macOS object/static-lib), `*.dylib` (macOS dynamic lib).
+
+- Add `iOSSimulatorArm64` and `LinuxARM64` output directories to the
+  `standard` level for Delphi 12+ platform targets.
+
+- Add `*.mab` (MadExcept/JEDI debug map) to the `deep` level.
+
+---
+
 ## [0.9.0] 2026-03-30
 
 - Add `-Check` for simple 0:clean, 1:dirty check

README.md

@@ -49,8 +49,11 @@ and the newer PowerShell 7+ (`pwsh`).
 - Add extra file patterns with `-IncludeFilePattern`
 - Exclude directories by wildcard pattern with `-ExcludeDirectoryPattern`
 - Send items to the recycle bin / trash instead of permanent deletion with `-RecycleBin`
-- Use `-OutputLevel` to adjust how much detail is shown.
-- Check for cleanup artifacts without modifying files using `-Check`.
+- Use `-OutputLevel` to adjust how much detail is shown
+- Check for cleanup artifacts without modifying files using `-Check`
+- JSON configuration file hierarchy (`$HOME`, project-level, local override, `-ConfigFile`)
+- Inspect the effective merged configuration with `-ShowConfig`
+- Inject a CI-specific config file via `-ConfigFile`
 
 ---
 
@@ -113,19 +116,23 @@ delphi-clean -PassThru
 
 ## -Json
 
-Outputs a JSON summary including:
+Outputs a single JSON object to standard output. All other output (text, progress)
+is suppressed. Key fields include:
 
-- Files found
-- Directories found
-- Files deleted
-- Directories deleted
-- Item-level details
+- `Level`, `Root`, `Mode` -- invocation metadata
+- `FilesFound`, `DirectoriesFound` -- items discovered during scan
+- `FilesDeleted`, `DirectoriesDeleted` -- items actually removed
+- `BytesFreed` -- total bytes freed (or would-be freed in `-WhatIf`/`-Check`)
+- `DurationMs` -- elapsed time in milliseconds
 - `Disposition` (`Permanent` or `Recycle Bin`) and `RecycleBin` flag
+- `Items[]` -- per-item records with `Type`, `Path`, `Deleted`, and `Size` (bytes)
 
 ```powershell
 delphi-clean -Json
 ```
 
+See [docs/json-output.md](docs/json-output.md) for the full field reference.
+
 ---
 
 ## -IncludeFilePattern
@@ -324,6 +331,73 @@ Check vs WhatIf:
 
 ---
 
+## -ShowConfig
+
+Displays the effective merged configuration that would be used for the current
+invocation, then exits without scanning or cleaning. No files are modified.
+
+```powershell
+delphi-clean -ShowConfig
+delphi-clean -ShowConfig -Json
+```
+
+The output lists every config file that was found and loaded, plus the final
+resolved value for each property (including built-in excluded directories and
+any CLI overrides already applied).
+
+---
+
+## -ConfigFile
+
+Injects an explicit JSON configuration file at the highest config priority
+(above project-level and local files, below command-line parameters). Useful
+in CI pipelines where the config lives outside the repository tree, or when
+testing a config before committing it.
+
+```powershell
+delphi-clean -ConfigFile C:/ci/delphi-clean-ci.json -Level standard
+```
+
+The file uses the same JSON format as `delphi-clean.json`. See
+[docs/configuration.md](docs/configuration.md) for the full key reference.
+
+---
+
+## Configuration Files
+
+`delphi-clean` supports optional JSON configuration files so you can encode
+per-project and per-user preferences without repeating them on the command line.
+
+Config sources, from lowest to highest priority:
+
+```
+$HOME/delphi-clean.json          user-level defaults
+  <RootPath>/delphi-clean.json   project-level (commit with the repo)
+    <RootPath>/delphi-clean.local.json  local user overrides (add to .gitignore)
+      -ConfigFile <path>                explicit file (e.g. for CI)
+        command-line parameters         highest priority
+```
+
+**Scalars override** -- the highest-priority source wins.
+**Arrays append** -- items from all sources are combined; duplicates are removed.
+
+Example `delphi-clean.json` (project-level):
+
+```json
+{
+  "level": "standard",
+  "outputLevel": "summary",
+  "includeFilePattern": ["*.res"],
+  "excludeDirectoryPattern": ["assets"],
+  "searchParentFolders": false
+}
+```
+
+See [docs/configuration.md](docs/configuration.md) for the full reference,
+including upward traversal (`searchParentFolders`) and monorepo patterns.
+
+---
+
 ## Exit Codes
 
 ```text

docs/cleanup-levels.md

@@ -44,6 +44,9 @@ Includes everything in `basic, plus the following additional items.
 - `*.dcp`
 - `*.bpi`
 - `*.so`
+- `*.o`
+- `*.a`
+- `*.dylib`
 - `*.exe`
 - `*.hpp`
 - `*.dres`
@@ -67,7 +70,9 @@ Includes everything in `basic, plus the following additional items.
 - `Android`
 - `Android64`
 - `iOSDevice64`
+- `iOSSimulatorArm64`
 - `Linux64`
+- `LinuxARM64`
 - `TMSWeb`
 
 ---
@@ -88,6 +93,7 @@ Includes everything in `standard`, plus the following additional items.
 - `*.fbl8`
 - `*.fbpbrk`
 - `*.fb8lck`
+- `*.mab`
 - `TestInsightSettings.ini`