Apply changesets and update CHANGELOG [skip ci]

Author: mayank1513

lib/README.md

@@ -19,12 +19,15 @@ A Git-aware conflict resolver for **JSON-first structured data**.
 ## Features
 
 - ⚡ **Primary focus on JSON** (first-class support)
-- 🔄 **YAML, XML, TOML** supported via conversion
-- 🧩 **Rule-based strategies** (per path/pattern)
-- 🗂️ Handles small configs to **huge repos** (optimizations built-in)
-- 🔌 **Pluggable matcher** abstraction (picomatch, micromatch supported out of the box with peerDependency)
-- 🛠️ Configurable trade-offs for **speed vs. memory**
-- 🗃️ **Planned**: extend configuration to use **different strategies per file** (ideas and edge cases welcome!)
+- 🔄 **YAML, XML, TOML, JSON5** supported via conversion
+- 🧩 **Rule-based strategies** with path/pattern matching
+- 📁 **Multiple file parallel processing** with include/exclude patterns
+- 🔌 **Pluggable matcher** abstraction (picomatch, micromatch, or custom)
+- 🛠️ **CLI and programmatic API** support
+- 📝 **Conflict sidecar files** for unresolved conflicts
+- 🔄 **Backup and restore** functionality
+- 📊 **Configurable logging** (memory or file-based)
+- 🔀 **Git merge driver** support for seamless Git integration
 
 ## Installation
 
@@ -46,6 +49,24 @@ yarn add git-json-resolver
 
 ## Quick Start
 
+### CLI Usage
+
+```bash
+# Initialize config file
+npx git-json-resolver --init
+
+# Run with default config
+npx git-json-resolver
+
+# Run with options
+npx git-json-resolver --include "**/*.json" --debug --sidecar
+
+# Restore from backups
+npx git-json-resolver --restore .merge-backups
+```
+
+### Git Integration
+
 Add a custom merge driver to your Git config:
 
 ```bash
@@ -57,73 +78,172 @@ Update `.gitattributes` to use it for JSON files:
 
 ```gitattributes
 *.json merge=json-resolver
+*.yaml merge=json-resolver
+*.yml merge=json-resolver
+*.toml merge=json-resolver
+*.xml merge=json-resolver
 ```
 
-## Example Config
+**How it works:**
+
+- Git automatically calls the merge driver during conflicts
+- Uses same configuration and strategies as CLI mode
+- Supports 3-way merge (ours, base, theirs)
+- Returns proper exit codes (0 = success, 1 = conflicts)
+
+## Configuration
+
+### Programmatic API
 
 ```ts
 import { resolveConflicts } from "git-json-resolver";
 
-const result = resolveConflicts({
-  filePath: "package.json",
-  rules: [
-    { pattern: "dependencies.*", strategy: "ours" },
-    { pattern: "version", strategy: "theirs", important: true },
-    { pattern: "scripts.build", strategy: "manual" },
-  ],
-  matcher: "picomatch", // default
-  optimize: {
-    cacheMatchers: true,
-    streamMode: false, // set true for very large repos
+await resolveConflicts({
+  defaultStrategy: ["merge", "ours"],
+  rules: {
+    "dependencies.*": ["ours"],
+    version: ["theirs!"], // ! marks as important
+    "scripts.build": ["skip"],
   },
+  include: ["**/*.json", "**/*.yaml"],
+  exclude: ["**/node_modules/**"],
+  matcher: "picomatch",
+  debug: true,
+  writeConflictSidecar: true,
+  backupDir: ".merge-backups",
 });
 ```
 
-### Upcoming: File-Specific Strategies
-
-We are exploring the ability to define **per-file strategy sets** in config, e.g.:
-
-```ts
-rulesByFile: {
-  "package.json": { version: ["theirs"], dependencies: ["ours"] },
-  "*.config.json": { "*": ["merge"] },
-},
+### Config File (`git-json-resolver.config.js`)
+
+```js
+module.exports = {
+  defaultStrategy: ["merge", "ours"],
+  rules: {
+    // Exact path matching
+    "package.json": {
+      version: ["theirs!"],
+      dependencies: ["ours"],
+    },
+    // Pattern matching
+    "*.config.json": {
+      "*": ["merge"],
+    },
+  },
+  // Alternative: byStrategy format
+  byStrategy: {
+    ours: ["dependencies.*", "devDependencies.*"],
+    "theirs!": ["version", "name"],
+  },
+  include: ["**/*.json", "**/*.yaml", "**/*.yml"],
+  exclude: ["**/node_modules/**", "**/dist/**"],
+  matcher: "picomatch",
+  debug: false,
+  writeConflictSidecar: false,
+  loggerConfig: {
+    mode: "memory", // or "stream"
+    logDir: "logs",
+    levels: {
+      stdout: ["warn", "error"],
+      file: ["info", "warn", "error"],
+    },
+  },
+};
 ```
 
-This raises interesting questions/edge cases:
-
-- How to merge file-level vs. global rules?
-- Should `include/exclude` still apply if a file is explicitly listed?
-- Should conflicting rules between file + global fall back to default strategy or error?
-
-We welcome ideas & edge cases here!
-
 ## Supported Strategies
 
+- **merge** → deep merge objects/arrays where possible
 - **ours** → take current branch value
 - **theirs** → take incoming branch value
-- **manual** → mark for human resolution
-- **drop** → remove the key entirely
-- **custom** → user-defined resolver function
+- **base** → revert to common ancestor
+- **skip** → leave unresolved (creates conflict entry)
+- **drop** → remove the field entirely
+- **non-empty** → prefer non-empty value (ours > theirs > base)
+- **update** → update with theirs if field exists in ours
+- **concat** → concatenate arrays from both sides
+- **unique** → merge arrays and remove duplicates
+- **custom** → user-defined resolver functions
+
+### Strategy Priority
+
+- Strategies marked with `!` (important) are applied first
+- Multiple strategies can be specified as fallbacks
+- Custom strategies can be defined via `customStrategies` config
 
 ## Supported Formats
 
 - **JSON** (native)
-- **YAML, XML, TOML** → converted to JSON → resolved → converted back
+- **JSON5** → via `json5` peer dependency
+- **YAML** → via `yaml` peer dependency
+- **TOML** → via `smol-toml` peer dependency
+- **XML** → via `fast-xml-parser` peer dependency
+
+All non-JSON formats are converted to JSON → resolved → converted back to original format.
+
+## CLI Options
+
+```bash
+# File patterns
+--include "**/*.json,**/*.yaml"  # Comma-separated patterns
+--exclude "**/node_modules/**"   # Exclusion patterns
+
+# Matcher selection
+--matcher picomatch              # picomatch, micromatch, or custom
+
+# Debug and logging
+--debug                          # Enable verbose logging
+--sidecar                        # Write conflict sidecar files
+
+# Utilities
+--init                           # Create starter config file
+--restore .merge-backups         # Restore from backup directory
+```
 
-## Performance & Optimization
+## Architecture
 
-- **Matcher caching** for repeated patterns
-- **Streaming mode** for very large repos (low memory footprint)
-- Trade-offs are configurable via `optimize` field
+- **Modular design**: Separate concerns (parsing, merging, serialization)
+- **Reusable utilities**: Common merge logic extracted for maintainability
+- **Optimized bundle**: Constants over enums for better minification
+- **Comprehensive testing**: Full test coverage with vitest
+- **Type-safe**: Full TypeScript support with proper type inference
+
+## Advanced Features
+
+### Pattern Matching
+
+- **Exact paths**: `"package.json"`, `"src.config.database.host"`
+- **Field matching**: `"[version]"` → matches any `version` field
+- **Glob patterns**: `"dependencies.*"`, `"**.config.**"`
+- **Wildcards**: `"*.json"`, `"src/**/*.config.js"`
+
+### Custom Strategies
+
+```ts
+import { StrategyStatus } from "git-json-resolver";
+
+const config = {
+  customStrategies: {
+    "semantic-version": ({ ours, theirs }) => {
+      // Custom logic for semantic version resolution
+      if (isNewerVersion(theirs, ours)) {
+        return { status: StrategyStatus.OK, value: theirs };
+      }
+      return { status: StrategyStatus.CONTINUE };
+    },
+  },
+  rules: {
+    version: ["semantic-version", "theirs"],
+  },
+};
+```
 
-## Roadmap
+### Logging & Debugging
 
-- [ ] Richer strategies via plugins (e.g., semantic version resolver)
-- [ ] CLI UX improvements
-- [ ] Pluggable format converters customizations
-- [ ] VSCode integration for previewing merge resolutions
-- [ ] **Per-file strategies support** (current RFC)
+- **Memory mode**: Fast, in-memory logging
+- **Stream mode**: File-based logging for large operations
+- **Per-file logs**: Separate log files for each processed file
+- **Debug mode**: Detailed conflict information and strategy traces
 
 ## Contributing