Merge branch 'feat/improvements'

Author: chiahsien

AGENTS.md

@@ -4,8 +4,7 @@
 
 CLI tool that sorts sections of Xcode `project.pbxproj` files to reduce merge conflicts. Forked from WebKit's sort-Xcode-project-file with extended functionality.
 
-- **Script**: `sort-Xcode-project-file.py` (~428 lines, Python 3.9+, stdlib only)
-- **Legacy Perl version**: `sort-Xcode-project-file.pl` (maintained for reference; not actively developed)
+- **Script**: `sort-Xcode-project-file.py` (~503 lines, Python 3.9+, stdlib only)
 
 **License:** MIT
 
@@ -17,11 +16,13 @@ python3 sort-Xcode-project-file.py <path-to-project.pbxproj>
 python3 sort-Xcode-project-file.py <path-to-project.xcodeproj>
 python3 sort-Xcode-project-file.py --case-insensitive <path>
 python3 sort-Xcode-project-file.py --check <path>         # CI mode: exit 0 if sorted
+python3 sort-Xcode-project-file.py -r <directory>          # Recursive search
+cat project.pbxproj | python3 sort-Xcode-project-file.py - > sorted.pbxproj  # Stdin/stdout
 ```
 
 ### Tests
 ```bash
-python3 -m unittest discover tests -v    # Run all 54 tests
+python3 -m unittest discover tests -v    # Run all 70 tests
 ```
 
 ### Verify syntax
@@ -32,19 +33,20 @@ python3 -c "import py_compile; py_compile.compile('sort-Xcode-project-file.py',
 ## Architecture
 
 ```
-sort-Xcode-project-file.py    # Everything lives here (~428 lines)
+sort-Xcode-project-file.py    # Everything lives here (~503 lines)
 ├── Regex patterns             # re.compile with re.VERBOSE (lines 31-76)
-├── natural_sort_key()         # Natural (alphanumeric) sort key (line 98)
-├── extract_filename()         # Regex-based filename extraction (line 117)
-├── is_directory()             # Heuristic: no extension = directory (line 123)
-├── uniq()                     # Deduplicate preserving order (line 136)
-├── children_sort_key()        # Sort key: dirs first, then natural sort (line 147)
-├── files_sort_key()           # Sort key: natural sort only (line 153)
-├── read_array_entries()       # Extract array contents between ( and ); (line 159)
-├── write_file()               # Atomic write via tempfile + os.replace() (line 193)
-├── sort_project_file()        # Core: read → parse → sort → write (line 217)
-├── build_parser()             # argparse CLI definition (line 307)
-└── main()                     # Entry point: parse args, process files (line 366)
+├── natural_sort_key()         # Natural (alphanumeric) sort key (line 115)
+├── extract_filename()         # Regex-based filename extraction (line 134)
+├── is_directory()             # Heuristic: no extension = directory (line 140)
+├── uniq()                     # Deduplicate preserving order (line 153)
+├── children_sort_key()        # Sort key: dirs first, then natural sort (line 164)
+├── files_sort_key()           # Sort key: natural sort only (line 170)
+├── read_array_entries()       # Extract array contents between ( and ); (line 176)
+├── write_file()               # Atomic write via tempfile + os.replace() (line 210)
+├── sort_project_content()     # Core sorting logic (pure function) (line 234)
+├── sort_project_file()        # Read → sort_project_content → write (line 315)
+├── build_parser()             # argparse CLI definition (line 343)
+└── main()                     # Entry point: parse args, process files (line 409)
 ```
 
 ### Test suite (`tests/`)
@@ -54,12 +56,11 @@ tests/
 ├── __init__.py                    # Package marker
 ├── _helpers.py                    # importlib-based import of hyphenated script name
 ├── test_natural_sort.py           # 15 tests for natural_sort_key()
-├── test_is_directory.py           # 7 tests for is_directory()
+├── test_is_directory.py           # 9 tests for is_directory()
 ├── test_dedup.py                  # 7 tests for uniq()
 ├── test_extract_filename.py       # 5 tests for extract_filename()
-├── test_sort_project.py           # 9 integration tests (sort, idempotency, check mode)
-├── test_cli.py                    # 12 CLI tests via subprocess (exit codes, flags)
-├── cross_validate.py              # Standalone cross-validation script (Perl vs Python)
+├── test_sort_project.py           # 16 integration tests (sort, idempotency, check mode, edge cases)
+├── test_cli.py                    # 19 CLI tests via subprocess (exit codes, flags, stdin, recursive)
 └── fixtures/
     ├── basic_unsorted.pbxproj     # Unsorted input fixture
     ├── basic_sorted.pbxproj       # Expected output (case-sensitive)
@@ -69,7 +70,15 @@ tests/
     ├── with_duplicates.pbxproj    # Duplicate entries fixture
     ├── with_duplicates_sorted.pbxproj
     ├── empty_arrays.pbxproj       # Empty arrays fixture
-    └── empty_arrays_sorted.pbxproj
+    ├── empty_arrays_sorted.pbxproj
+    ├── with_spm_packages.pbxproj  # SPM packageProductDependencies/packageReferences
+    ├── with_spm_packages_sorted.pbxproj
+    ├── with_special_chars.pbxproj # Filenames with +, long names
+    ├── with_special_chars_sorted.pbxproj
+    ├── with_multi_fw_targets.pbxproj     # Multiple FW build phases
+    ├── with_multi_fw_targets_sorted.pbxproj
+    ├── with_nested_groups.pbxproj        # Nested children arrays, empty packageReferences
+    └── with_nested_groups_sorted.pbxproj
 ```
 
 ### Key Regex Patterns (compiled, module level)
@@ -155,17 +164,15 @@ def function_name(param: type) -> return_type:
 
 | Flag | Effect |
 |---|---|
+| `-` | Read from stdin, write to stdout |
 | `--case-insensitive` | Case-insensitive natural sort |
 | `--case-sensitive` | Force case-sensitive (default) |
 | `--check` | Exit 0 if sorted, exit 1 if not (no modification) |
+| `-r` / `--recursive` | Recursively find and sort all `project.pbxproj` under directories |
 | `--version` | Show version and exit |
 | `-w` / `--no-warnings` | Suppress warning messages |
 | `-h` / `--help` | Show usage and exit |
 
-## Known Limitations & Improvement Plan
-
-See [`docs/improvement-plan.md`](docs/improvement-plan.md) for a prioritized list of improvements.
-
 ## Commit Style
 
 Based on git history, use conventional commits:

README.md

@@ -6,17 +6,17 @@ Forked from [WebKit's sort-Xcode-project-file](https://github.com/WebKit/webkit/
 
 ## Features
 
-- Bypass `PBXFrameworksBuildPhase` section (preserve original order, important for some projects)
 - Sort `children` arrays throughout the project (directories before files)
 - Sort `files` arrays in build phases
-- Sort `targets` list in project
-- Sort `packageProductDependencies` and `packageReferences` lists in project
-- Sort `buildConfigurations` list in each target
-- Case-sensitive sorting by default (preserves original behavior)
-- Option to enable case-insensitive sorting: `--case-insensitive`
+- Sort `targets`, `buildConfigurations`, `packageProductDependencies`, and `packageReferences` arrays
+- Preserve `PBXFrameworksBuildPhase` order (link order matters)
 - Remove duplicate references automatically
 - Natural (human) sorting for names/filenames (e.g., `file2` < `file10`)
+- Case-sensitive sorting by default (original WebKit behavior)
+- Option for case-insensitive sorting: `--case-insensitive`
 - `--check` mode for CI pipelines (exit 0 if sorted, exit 1 if unsorted)
+- Stdin/stdout pipeline support (`-`)
+- Recursive directory search (`-r` / `--recursive`)
 - Atomic file writes — never leaves a `.pbxproj` in a corrupted state
 
 ## Requirements
@@ -26,89 +26,88 @@ Forked from [WebKit's sort-Xcode-project-file](https://github.com/WebKit/webkit/
 
 ## Usage
 
-**Please backup Xcode project file before using this script.** You can execute the following command to sort a project file:
-
 ```bash
-python3 sort-Xcode-project-file.py <path-to-xcodeproj-or-project.pbxproj>
+python3 sort-Xcode-project-file.py MyApp.xcodeproj
+python3 sort-Xcode-project-file.py path/to/project.pbxproj
 ```
 
+Both `.xcodeproj` directories and `project.pbxproj` files are accepted.
+
 ### Options
 
 | Flag | Description |
 |------|-------------|
+| `-` | Read from stdin, write to stdout |
 | `--case-insensitive` | Enable case-insensitive sorting (default is case-sensitive) |
 | `--case-sensitive` | Explicit alias to force case-sensitive sorting |
 | `--check` | Check if file is already sorted (exit 0 = sorted, exit 1 = unsorted) |
+| `-r`, `--recursive` | Recursively find and sort all `project.pbxproj` under directories |
 | `--version` | Show version and exit |
 | `-w`, `--no-warnings` | Suppress warning messages |
 | `-h`, `--help` | Show help |
 
-### CI Usage
-
-Use `--check` in CI pipelines to enforce sorted project files:
+### Examples
 
 ```bash
+# Sort a single project
+python3 sort-Xcode-project-file.py MyApp.xcodeproj
+
+# CI check — fails if unsorted
 python3 sort-Xcode-project-file.py --check MyApp.xcodeproj
-```
 
-Exit code 0 means the file is already sorted; exit code 1 means it needs sorting.
+# Sort all projects in a monorepo
+python3 sort-Xcode-project-file.py -r .
 
-## Pre-commit Hook Setup
+# Pipe through stdin/stdout
+cat project.pbxproj | python3 sort-Xcode-project-file.py - > sorted.pbxproj
 
-You can use this tool to sort Xcode project files before committing to git. Sorting project files decreases merge conflict probability.
+# Check stdin without modifying anything
+cat project.pbxproj | python3 sort-Xcode-project-file.py --check -
+```
 
-### 1.
+## Pre-commit Hook
 
-Create a `Scripts` directory in project root directory, and put `sort-Xcode-project-file.py` into `Scripts` directory.
+Sort Xcode project files automatically before each commit to reduce merge conflicts.
 
-### 2.
+**1.** Create a `Scripts` directory in your project root and copy `sort-Xcode-project-file.py` into it.
 
-Put the following code into `.git/hooks/pre-commit` file.
+**2.** Create `.git/hooks/pre-commit` with the following content:
 
 ```bash
 #!/bin/sh
-#
-# Following script is to sort Xcode project files, and add them back to version control.
-# The reason to sort project file is that it can decrease project.pbxproj file merging conflict possibility.
-#
+
 echo 'Sorting Xcode project files'
 
 GIT_ROOT=$(git rev-parse --show-toplevel)
 sorter="$GIT_ROOT/Scripts/sort-Xcode-project-file.py"
-modifiedProjectFiles=( $(git diff --name-only --cached | grep "project.pbxproj") )
 
-for filePath in ${modifiedProjectFiles[@]}; do
+git diff --name-only --cached | grep "project.pbxproj" | while IFS= read -r filePath; do
   fullFilePath="$GIT_ROOT/$filePath"
-  python3 $sorter $fullFilePath
-  git add $fullFilePath
+  python3 "$sorter" "$fullFilePath"
+  git add "$fullFilePath"
 done
 
 echo 'Done sorting Xcode project files'
-
-exit 0
 ```
 
-### 3.
-
-Put following line into `.gitattributes` file then commit it.
+**3.** Make it executable:
 
-```
-*.pbxproj merge=union
+```bash
+chmod +x .git/hooks/pre-commit
 ```
 
-## Running Tests
+**4.** *(Optional)* Add to `.gitattributes` to reduce merge conflicts further:
 
-```bash
-python3 -m unittest discover tests    # Run all tests (54 tests)
-python3 tests/cross_validate.py       # Cross-validate Python vs Perl output
+```
+*.pbxproj merge=union
 ```
 
-## Legacy Perl Version
+> **Note:** `merge=union` tells Git to keep both sides of a conflict automatically. This works well for sorted `.pbxproj` files but can produce invalid results on non-sorted ones. Use this tool consistently to avoid issues.
 
-The original Perl version (`sort-Xcode-project-file.pl`) is still available. The Python version produces byte-for-byte identical output.
+## Running Tests
 
 ```bash
-perl sort-Xcode-project-file.pl <path-to-xcodeproj-or-project.pbxproj>
+python3 -m unittest discover tests -v    # Run all 70 tests
 ```
 
 ## License