Update README.md

Author: isidore

custom-pmd-rule/README.md

@@ -1,56 +1,105 @@
 # Custom Linting Rule: Flip Comparison Operators
 
-A custom rule that detects `>` (greater than) and `>=` (greater than or equal) operators in Java code and suggests flipping them to `<` and `<=` respectively.
+A custom rule that detects `>` (greater than) and `>=` (greater than or equal) operators in Java code and refactors them by flipping both the operator AND operands to their `<` and `<=` equivalents.
 
 ## Quick Start
 
-### Find operators with bash script
+### Scan for operators (default)
 
 ```bash
-./find-comparisons.sh /path/to/java/source
+./find-comparisons.sh
 ```
 
-Example:
+Scans all `src/main/java` and `src/test/java` directories in the project.
+
+Or scan a specific directory:
 ```bash
-./find-comparisons.sh ../approvaltests/src/main/java
+./find-comparisons.sh custom-pmd-rule/example
 ```
 
-This will display all `>` and `>=` operators with line numbers and file paths.
-
-### Example Output
+### Refactor with `--fix`
 
+```bash
+./find-comparisons.sh --fix
 ```
-example/TestComparison.java:7:        if (x > y) {
-example/TestComparison.java:11:        if (x >= y) {
-example/TestComparison.java:25:        if (x > 0 && x < 100) {
-example/TestComparison.java:30:        while (x > 0) {
-```
+
+Automatically refactors all comparison operators with proper operand swapping.
 
 ## What the Rule Does
 
-- **Detects** `>` operators and suggests flipping to `<`
-- **Detects** `>=` operators and suggests flipping to `<=`
-- **Warnings only** — does not auto-fix (to prevent accidentally inverting logic)
-- Works as a standalone CLI tool
+### Refactoring Behavior
+
+This is a **pure refactoring** that preserves logic by swapping operands:
+
+| Original | Refactored | Logic |
+|----------|-----------|-------|
+| `x > y` | `y < x` | Equivalent ✓ |
+| `x >= y` | `y <= x` | Equivalent ✓ |
+| `this.getValue() > 5` | `5 < this.getValue()` | Equivalent ✓ |
+| `items.length >= 1` | `1 <= items.length` | Equivalent ✓ |
+| `getList().size() > 0` | `0 < getList().size()` | Equivalent ✓ |
+
+### Protected Cases
+
+The script intelligently handles:
+- ✅ **Simple comparisons** — `x > y`
+- ✅ **Method calls** — `obj.getValue() > 5`
+- ✅ **Chained calls** — `obj.getList().size() > 0`
+- ✅ **Property access** — `items.length >= 1`
+- ✅ **Complex expressions** — `getParameterTypes().length >= 1`
+- ✅ **Preserves generics** — `List<Integer>` unchanged
+- ✅ **Mixed code** — Generics and comparisons on same line
+
+## Test Cases
+
+Comprehensive test file included: `example/ComparisonTest.java`
+
+Tests verify:
+- Simple variable comparisons
+- Method calls and chained calls
+- Property access patterns (like `array.length`)
+- Complex expressions with multiple dots and parentheses
+- Generic type preservation
+- Mixed generics and comparisons on same line
+
+Run the test:
+```bash
+./find-comparisons.sh --fix custom-pmd-rule/example
+```
 
 ## Files
 
-- `find-comparisons.sh` — Main script to find comparison operators
-- `flip-comparison.xml` — PMD configuration file
-- `example/TestComparison.java` — Example Java file with violations
-- `SETUP.md` — Detailed setup and PMD integration instructions
+- `find-comparisons.sh` — Main script to scan and refactor comparison operators
+- `example/TestComparison.java` — Example with simple comparisons and generics
+- `example/ComparisonTest.java` — Comprehensive test cases
+- `flip-comparison.xml` — PMD configuration (reference)
+- `SETUP.md` — Additional setup and integration instructions
+
+## Logic Preservation
 
-## Why "Flip"?
+The refactoring swaps both the operator AND the operands, so the logical meaning is preserved:
 
-If you flip comparison operators, you reverse the logic:
-- `x > y` becomes `x < y` (opposite condition)
-- `x >= y` becomes `x <= y` (opposite condition)
+**Before:** `if (x > y) { ... }`  
+**After:** `if (y < x) { ... }`  
+**Result:** Same condition, just expressed differently
 
-The rule is useful for:
-- Finding all comparison operators in your codebase
-- Code analysis and style enforcement
-- Testing/educational purposes
+This makes it a safe refactoring—no behavior changes, only code rearrangement.
 
-## For PMD Integration
+## Usage
 
-See `SETUP.md` for instructions on using this with PMD directly.
+```bash
+# Scan all src directories
+./find-comparisons.sh
+
+# Scan specific directory
+./find-comparisons.sh /path/to/src
+
+# Refactor all operators
+./find-comparisons.sh --fix
+
+# Refactor specific directory
+./find-comparisons.sh --fix /path/to/src
+
+# Review changes before committing
+git diff
+```