feat: support single-file path targets

Author: MaxLogic

CHANGELOG.md

@@ -1,6 +1,13 @@
 # Changelog
 
-## [v1.2] - 2026-06-16
+## [v1.3] - 2026-06-16
+
+### Added
+
+- Added `path=<file>` support so EncodingFixTool can process exactly one file while using the file's parent directory as the scan root.
+- Added regression coverage for single-file CLI processing to ensure sibling files are not touched.
+
+## [v1.2] - 2026-06-16
 
 ### Added
 

README.md

@@ -1,7 +1,7 @@
 # EncodingFixTool
 
 A fast, parallel, command-line fixer for Delphi source file encodings.
-It scans `.pas`, `.dpr`, …; detects UTF-8/ASCII vs. legacy single-byte encodings; repairs mixed lines (Windows-1250/1252/ANSI), and writes clean UTF-8 with an optional BOM. Line endings are preserved by default, or normalized to Windows CRLF when requested.
+It scans a directory tree or one explicit file; detects UTF-8/ASCII vs. legacy single-byte encodings; repairs mixed lines (Windows-1250/1252/ANSI), and writes clean UTF-8 with an optional BOM. Line endings are preserved by default, or normalized to Windows CRLF when requested.
 
 ---
 
@@ -31,6 +31,9 @@ EncodingFixTool path=C:\Projs\MyApp v bkp-dir=C:\backup\myapp
 :: Only scan .pas files in ./src (not recursive), remove BOM if present
 EncodingFixTool path=.\src recursive=n ext=pas utf8-bom=n
 
+:: Process exactly one file
+EncodingFixTool path=.\src\GeneratedUnit.pas preset=delphi-ai
+
 :: Normalize generated Delphi sources to Windows CRLF while fixing encodings
 EncodingFixTool path=.\src ext=pas,dpr eol=crlf
 
@@ -50,7 +53,7 @@ EncodingFixTool ext="*.pas,*.dpr, .dfm"
 | `dry`         | —       | —                          | off         | Dry run: analyze and report what **would** change; no writes.                                  |
 | `s`/`silent`  | —       | —                          | off         | No console output. (Overrides `verbose`.)                                                      |
 | `v`/`verbose` | —       | —                          | off         | More output: “OK” lines etc. (Ignored if `silent`.)                                            |
-| `path`        | —       | dir                        | current dir | Directory to scan.                                                                             |
+| `path`        | —       | dir/file                   | current dir | Directory to scan, or one file to process.                                                     |
 | `recursive`   | —       | `y`/`n`/`yes`/`no`/`1`/`0` | `y`         | Recurse into subfolders.                                                                       |
 | `ext`         | —       | CSV list                   | `pas,dpr`   | File extensions to include. Smart parsing: accepts `pas`, `.pas`, `*.pas`. Quoted lists OK.    |
 | `preset`      | —       | `delphi-ai`                | —           | Applies Delphi agent cleanup defaults: Delphi extensions, UTF-8 BOM, recursive scan, CRLF.     |
@@ -75,7 +78,7 @@ C:\bkp\src\foo\bar\Main.pas
 ## What it does (algorithm)
 
 1. **Gather files**
-   Walk the `path` (recursively by default), matching the configured extensions.
+   If `path` names a file, process only that file. Otherwise walk the directory `path` (recursively by default), matching the configured extensions.
 
 2. **Process in parallel**
    Uses `TParallel.For` to utilize multiple cores. Console output is synchronized, and the “files changed” and failure counters are atomic.
@@ -151,7 +154,7 @@ Done in 00:08.972. Files changed: 2. Failures: 0
   Binary Delphi forms are detected from raw bytes and skipped unchanged. Text DFM files remain eligible for the normal encoding and optional line-ending repair path.
 
 * **Relative reporting**
-  Paths in logs are shown **relative to** the scanned `path`, for readability.
+  Paths in logs are shown **relative to** the scanned directory, for readability. In single-file mode the scan root is the file's parent directory.
 
 ## AI/agent usage
 
@@ -173,6 +176,12 @@ Use dry-run mode first when the dirty worktree is not fully understood:
 EncodingFixTool path=. preset=delphi-ai scope=git-changed format=json dry
 ```
 
+For the narrowest safe repair, point `path` at one file:
+
+```powershell
+EncodingFixTool path=.\src\GeneratedUnit.pas preset=delphi-ai format=json
+```
+
 Do not run the non-dry command over broad third-party or vendored code unless that is the intended scope. Inspect the JSON summary and `git diff --stat` before committing.
 
 ## Agent skill
@@ -265,4 +274,4 @@ EncodingFixTool pairs well with [MaxLogic Delphi Companion](https://github.com/M
 
 * `0` – completed without parse errors or per-file failures.
 * `1` – invalid parameter or one or more files failed to process.
-* `2` – the `path` argument didn’t exist.
+* `2` – the `path` argument didn’t exist as either a directory or a file.

TASKS.md

@@ -1,10 +1,10 @@
 # Tasks
 
-Next task ID: T-007
+Next task ID: T-008
 
 ## Summary
 Open tasks: 0 (In Progress: 0, Next Today: 0, Next This Week: 0, Next Later: 0, Blocked: 0)
-Done tasks: 6
+Done tasks: 7
 
 ## In Progress
 
@@ -18,6 +18,35 @@ Done tasks: 6
 
 ## Done
 
+### T-007 [CLI] Support single-file path targets
+Completed: 2026-06-16
+Outcome:
+- `path=<file>` is accepted as a first-class narrow target.
+- Single-file mode uses the file's parent directory as the scan root and processes only that file when its extension matches the active options or preset.
+- README, agent skill, reference docs, and changelog document the single-file workflow.
+Proof:
+- PASS: `.\bin\EncodingFixTool.Tests.exe --include:SingleFile`
+  Result: exit=0, 1 passed, 0 failed
+- PASS: `.\bin\EncodingFixTool.Tests.exe`
+  Result: exit=0, 31 passed, 0 failed
+- PASS: `powershell -NoProfile -ExecutionPolicy Bypass -File tests\Invoke-EncodingFixTool.Tests.ps1`
+  Result: exit=0, output contains `EncodingFixTool CLI tests passed.`
+- PASS: `Invoke-ScriptAnalyzer -Path .\tests\Invoke-EncodingFixTool.Tests.ps1 -Severity Warning,Error`
+  Result: exit=0, no findings
+- PASS: `cmd /s /c '"C:\Program Files (x86)\Embarcadero\Studio\23.0\bin\rsvars.bat" && msbuild src\EncodingFixTool.dproj /t:Build /p:Config=Debug /p:Platform=Win32'`
+  Result: exit=0, zero warnings, zero errors
+- PASS: `cmd /s /c '"C:\Program Files (x86)\Embarcadero\Studio\23.0\bin\rsvars.bat" && msbuild tests\EncodingFixTool.Tests.dproj /t:Build /p:Config=Debug /p:Platform=Win32'`
+  Result: exit=0, zero warnings, zero errors
+- PASS: `& 'F:\projects\MaxLogic\DelphiAiKit\bin\DelphiAIKit.exe' build --project src\EncodingFixTool.dproj --delphi 23.0 --platform Win32 --config Debug --target Build --ai`
+  Result: success
+- PASS: `& 'F:\projects\MaxLogic\DelphiAiKit\bin\DelphiAIKit.exe' build --project tests\EncodingFixTool.Tests.dproj --delphi 23.0 --platform Win32 --config Debug --target Build --ai`
+  Result: success
+- PASS: `.\bin\EncodingFixTool.exe path=. preset=delphi-ai scope=git-changed format=json`
+  Result: exit=0, `failed=0`
+Touches: src/EncodingFixToolCore.pas, tests/EncodingFixTool.IntegrationTests.pas, tests/Invoke-EncodingFixTool.Tests.ps1, README.md, agent-skill/encodingfix-delphi-cleanup/SKILL.md, agent-skill/encodingfix-delphi-cleanup/references/encodingfix-tool.md, CHANGELOG.md
+Verify: integration-test, cli-proof, build
+Notes: Strict TDD followed for the DUnitX single-file regression. Initial RED was exit code 2 for `path=<file>`; GREEN passed after normalizing file paths into explicit single-file scan mode.
+
 ### T-006 [DOC] Refresh README for workflow and presets
 Completed: 2026-06-11
 Outcome:

agent-skill/encodingfix-delphi-cleanup/SKILL.md

@@ -52,6 +52,12 @@ If the executable is not on `PATH`, use a local Windows build such as:
 .\bin\EncodingFixTool.exe path=. preset=delphi-ai scope=git-changed format=json
 ```
 
+For one known file, use single-file mode instead of scanning the directory:
+
+```powershell
+.\bin\EncodingFixTool.exe path=.\src\GeneratedUnit.pas preset=delphi-ai format=json
+```
+
 3. Outside Git, use an explicit path and dry run first.
 
 From WSL:
@@ -77,7 +83,7 @@ Treat the run as successful only when the process exits with code `0` and JSON `
 - `changed > 0`: inspect the relevant diffs before reporting done.
 - `skipped > 0`: usually expected for binary `.dfm`; mention it only when relevant.
 - `failed > 0` or exit code `1`: stop and report the file-level failure.
-- Exit code `2`: fix the missing `path` and rerun.
+- Exit code `2`: fix the missing directory or file `path` and rerun.
 
 ## Verify
 

agent-skill/encodingfix-delphi-cleanup/references/encodingfix-tool.md

@@ -43,6 +43,12 @@ For a deliberately narrow repair, keep overrides visible:
 EncodingFixTool path=.\src preset=delphi-ai ext=pas,inc format=json dry
 ```
 
+For exactly one file, pass the file path directly. The tool treats the file's directory as the scan root and processes only that file:
+
+```powershell
+EncodingFixTool path=.\src\GeneratedUnit.pas preset=delphi-ai format=json
+```
+
 ## Configured Presets
 
 Repo presets may live in `.encodingfix.json`; user presets may live in:

src/EncodingFixTool.dproj

@@ -90,19 +90,19 @@
         <SanitizedProjectName>EncodingFixTool</SanitizedProjectName>
         <VerInfo_IncludeVerInfo>true</VerInfo_IncludeVerInfo>
         <VerInfo_MajorVer>1</VerInfo_MajorVer>
-        <VerInfo_MinorVer>2</VerInfo_MinorVer>
+        <VerInfo_MinorVer>3</VerInfo_MinorVer>
         <VerInfo_Release>0</VerInfo_Release>
         <VerInfo_Build>0</VerInfo_Build>
         <VerInfo_Locale>1045</VerInfo_Locale>
-        <VerInfo_Keys>CompanyName=;FileDescription=;FileVersion=1.2.0.0;InternalName=;LegalCopyright=;LegalTrademarks=;OriginalFilename=;ProductName=;ProductVersion=1.2.0.0;Comments=;CFBundleName=</VerInfo_Keys>
+        <VerInfo_Keys>CompanyName=;FileDescription=;FileVersion=1.3.0.0;InternalName=;LegalCopyright=;LegalTrademarks=;OriginalFilename=;ProductName=;ProductVersion=1.3.0.0;Comments=;CFBundleName=</VerInfo_Keys>
         <DCC_Namespace>System;Xml;Data;Datasnap;Web;Soap;$(DCC_Namespace)</DCC_Namespace>
         <Icon_MainIcon>$(BDS)\bin\delphi_PROJECTICON.ico</Icon_MainIcon>
         <Icns_MainIcns>$(BDS)\bin\delphi_PROJECTICNS.icns</Icns_MainIcns>
         <DCC_ExeOutput>..\bin</DCC_ExeOutput>
         <CfgDependentOn>..\..\MaxLogicFoundation\MaxLogicDefault.optset</CfgDependentOn>
     </PropertyGroup>
     <PropertyGroup Condition="'$(Base_Android)'!=''">
-        <VerInfo_Keys>package=com.embarcadero.$(MSBuildProjectName);label=$(MSBuildProjectName);versionCode=1;versionName=1.2.0;persistent=False;restoreAnyVersion=False;installLocation=auto;largeHeap=False;theme=TitleBar;hardwareAccelerated=true;apiKey=;minSdkVersion=23;targetSdkVersion=34</VerInfo_Keys>
+        <VerInfo_Keys>package=com.embarcadero.$(MSBuildProjectName);label=$(MSBuildProjectName);versionCode=1;versionName=1.3.0;persistent=False;restoreAnyVersion=False;installLocation=auto;largeHeap=False;theme=TitleBar;hardwareAccelerated=true;apiKey=;minSdkVersion=23;targetSdkVersion=34</VerInfo_Keys>
         <BT_BuildType>Debug</BT_BuildType>
         <Android_LauncherIcon36>$(BDS)\bin\Artwork\Android\FM_LauncherIcon_36x36.png</Android_LauncherIcon36>
         <Android_LauncherIcon48>$(BDS)\bin\Artwork\Android\FM_LauncherIcon_48x48.png</Android_LauncherIcon48>
@@ -141,13 +141,13 @@
     <PropertyGroup Condition="'$(Base_Win32)'!=''">
         <DCC_Namespace>Winapi;System.Win;Data.Win;Datasnap.Win;Web.Win;Soap.Win;Xml.Win;Bde;$(DCC_Namespace)</DCC_Namespace>
         <BT_BuildType>Debug</BT_BuildType>
-        <VerInfo_Keys>CompanyName=;FileDescription=$(MSBuildProjectName);FileVersion=1.2.0.0;InternalName=;LegalCopyright=;LegalTrademarks=;OriginalFilename=;ProductName=$(MSBuildProjectName);ProductVersion=1.2.0.0;Comments=;ProgramID=com.embarcadero.$(MSBuildProjectName)</VerInfo_Keys>
+        <VerInfo_Keys>CompanyName=;FileDescription=$(MSBuildProjectName);FileVersion=1.3.0.0;InternalName=;LegalCopyright=;LegalTrademarks=;OriginalFilename=;ProductName=$(MSBuildProjectName);ProductVersion=1.3.0.0;Comments=;ProgramID=com.embarcadero.$(MSBuildProjectName)</VerInfo_Keys>
         <VerInfo_Locale>1033</VerInfo_Locale>
     </PropertyGroup>
     <PropertyGroup Condition="'$(Base_Win64)'!=''">
         <DCC_Namespace>Winapi;System.Win;Data.Win;Datasnap.Win;Web.Win;Soap.Win;Xml.Win;Bde;$(DCC_Namespace)</DCC_Namespace>
         <BT_BuildType>Debug</BT_BuildType>
-        <VerInfo_Keys>CompanyName=;FileDescription=$(MSBuildProjectName);FileVersion=1.2.0.0;InternalName=;LegalCopyright=;LegalTrademarks=;OriginalFilename=;ProductName=$(MSBuildProjectName);ProductVersion=1.2.0.0;Comments=;ProgramID=com.embarcadero.$(MSBuildProjectName)</VerInfo_Keys>
+        <VerInfo_Keys>CompanyName=;FileDescription=$(MSBuildProjectName);FileVersion=1.3.0.0;InternalName=;LegalCopyright=;LegalTrademarks=;OriginalFilename=;ProductName=$(MSBuildProjectName);ProductVersion=1.3.0.0;Comments=;ProgramID=com.embarcadero.$(MSBuildProjectName)</VerInfo_Keys>
         <VerInfo_Locale>1033</VerInfo_Locale>
     </PropertyGroup>
     <PropertyGroup Condition="'$(Cfg_1)'!=''">
@@ -177,7 +177,7 @@
     </PropertyGroup>
     <PropertyGroup Condition="'$(Cfg_2_Win32)'!=''">
         <VerInfo_Locale>1033</VerInfo_Locale>
-        <VerInfo_Keys>CompanyName=;FileDescription=$(MSBuildProjectName);FileVersion=1.2.0.0;InternalName=;LegalCopyright=;LegalTrademarks=;OriginalFilename=;ProductName=$(MSBuildProjectName);ProductVersion=1.2.0.0;Comments=;ProgramID=com.embarcadero.$(MSBuildProjectName)</VerInfo_Keys>
+        <VerInfo_Keys>CompanyName=;FileDescription=$(MSBuildProjectName);FileVersion=1.3.0.0;InternalName=;LegalCopyright=;LegalTrademarks=;OriginalFilename=;ProductName=$(MSBuildProjectName);ProductVersion=1.3.0.0;Comments=;ProgramID=com.embarcadero.$(MSBuildProjectName)</VerInfo_Keys>
         <Manifest_File>(None)</Manifest_File>
         <AppDPIAwarenessMode>none</AppDPIAwarenessMode>
     </PropertyGroup>

src/EncodingFixTool.res

@@ -37,6 +37,7 @@       TOptions = record
         Silent: boolean;
         Verbose: boolean; // not compatible with Silent
         Path: string;
+        SingleFilePath: string;
         Recursive: boolean; // default y
         Exts: TArray<string>; // normalized: ".pas", ".dpr", etc.
         Utf8Bom: boolean; // default y
@@ -214,6 +215,17 @@ function TEncodingFixTool.CollectFiles(const aOptions: TOptions): TArray<string>
   lSearchOpt: TSearchOption;
   lExt, lPattern: string;
 begin
+  if aOptions.SingleFilePath <> '' then
+  begin
+    if IsWantedExt(aOptions.SingleFilePath) then
+    begin
+      Result := [aOptions.SingleFilePath];
+    end else begin
+      Result := [];
+    end;
+    Exit;
+  end;
+
   if aOptions.ScopeMode = TScopeMode.smGitChanged then
   begin
     Exit(CollectGitChangedFiles(aOptions));
@@ -601,7 +613,6 @@ function TEncodingFixTool.DecodeBestPerLine(const aLineBytes: TBytes; out aEncNa
   sc := ScoreDecoded(sANSI);
   if sc > bestScore then
   begin
-    bestScore := sc;
     bestS := sANSI;
     aEncName := 'ANSI';
   end;
@@ -1074,7 +1085,7 @@ function TEncodingFixTool.ShowHelp: integer;
     '  dry                   : Dry run (no files are changed).' + sLineBreak +
     '  s | silent            : No console output.' + sLineBreak +
     '  v | verbose           : More output (not compatible with silent).' + sLineBreak +
-    '  path=<dir>            : Directory to scan. Default: current working dir.' + sLineBreak +
+    '  path=<dir|file>       : Directory to scan or one file to process. Default: current working dir.' + sLineBreak +
     '  recursive=y|n         : Recurse into subfolders. Default: y.' + sLineBreak +
     '  ext=<csv>             : Extensions list. Default: pas,dpr. Accepts "pas", ".pas", "*.pas".' + sLineBreak +
     '  preset=delphi-ai      : AI cleanup preset for Delphi projects.' + sLineBreak +
@@ -1208,7 +1219,15 @@ function TEncodingFixTool.ParseCommandLine(out aOptions: TOptions): integer;
     begin
       if lValue <> '' then
       begin
-        aOptions.Path := ExpandFileName(lValue);
+        lValue := ExpandFileName(lValue);
+        aOptions.SingleFilePath := '';
+        if TFile.Exists(lValue) then
+        begin
+          aOptions.SingleFilePath := lValue;
+          aOptions.Path := ExtractFilePath(lValue);
+        end else begin
+          aOptions.Path := lValue;
+        end;
       end;
     end else if (aKey = 'recursive') then
     begin
@@ -1393,6 +1412,7 @@ function TEncodingFixTool.ParseCommandLine(out aOptions: TOptions): integer;
   aOptions.Silent := False;
   aOptions.Verbose := False;
   aOptions.Path := GetCurrentDir;
+  aOptions.SingleFilePath := '';
   aOptions.Recursive := True;
   aOptions.Exts := NormalizeExtList('pas,dpr');
   aOptions.Utf8Bom := True; // default y (Delphi-friendly)

src/EncodingFixToolCore.pas

@@ -73,6 +73,10 @@   TEncodingFixToolIntegrationTests = class
     [Category('AiWorkflow')]
     procedure GitChangedScopeProcessesOnlyChangedFiles;
 
+    [Test]
+    [Category('SingleFile')]
+    procedure FilePathProcessesOnlyThatFile;
+
     [Test]
     [Category('PresetConfig')]
     procedure ExplicitConfigPresetAppliesToIncludedExtensions;
@@ -573,6 +577,27 @@ procedure TEncodingFixToolIntegrationTests.GitChangedScopeProcessesOnlyChangedFi
   end;
 end;
 
+procedure TEncodingFixToolIntegrationTests.FilePathProcessesOnlyThatFile;
+var
+  lFileName: string;
+  lOtherFileName: string;
+  lRootPath: string;
+begin
+  lRootPath := TPath.Combine(TPath.GetTempPath, 'EncodingFix-DUnitX-' + TGuid.NewGuid.ToString);
+  TDirectory.CreateDirectory(lRootPath);
+  try
+    lFileName := WriteBytes(lRootPath, 'target.pas', TEncoding.ASCII.GetBytes('unit Target;'#10'end.'));
+    lOtherFileName := WriteBytes(lRootPath, 'other.pas', TEncoding.ASCII.GetBytes('unit Other;'#10'end.'));
+
+    Assert.AreEqual(0, Integer(RunTool(lFileName, ['recursive=n', 'ext=pas', 'eol=crlf', 's'])));
+
+    AssertBytesEqual(TEncoding.ASCII.GetBytes('unit Target;'#13#10'end.'), TFile.ReadAllBytes(lFileName));
+    AssertBytesEqual(TEncoding.ASCII.GetBytes('unit Other;'#10'end.'), TFile.ReadAllBytes(lOtherFileName));
+  finally
+    DeleteTree(lRootPath);
+  end;
+end;
+
 procedure TEncodingFixToolIntegrationTests.ExplicitConfigPresetAppliesToIncludedExtensions;
 var
   lFileName: string;