upgrade deps && docs [skip ci]

Author: mayank1513

MIGRATION.md

@@ -29,14 +29,15 @@ If you're using dynamic plugin loading, **no changes are needed**:
 #### 2. Direct Import Usage
 
 **Before (v0.0.2):**
+
 ```ts
 import plugin, { semverMax } from "git-json-resolver-semver";
 import { resolveConflicts } from "git-json-resolver";
 
 // Plugin configuration (old way)
 await plugin.init?.({
   strict: false,
-  fallback: "ours"
+  fallback: "ours",
 });
 
 await resolveConflicts({
@@ -50,14 +51,15 @@ await resolveConflicts({
 ```
 
 **After (v1.0.0):**
+
 ```ts
 import createSemverPlugin, { semverMax, init } from "git-json-resolver-semver";
 import { resolveConflicts } from "git-json-resolver";
 
 // Option 1: Use factory function with config
 const plugin = createSemverPlugin({
   strict: false,
-  fallback: "ours"
+  fallback: "ours",
 });
 
 await resolveConflicts({
@@ -70,7 +72,7 @@ await resolveConflicts({
 // Option 2: Use global init (for backward compatibility)
 init({
   strict: false,
-  fallback: "ours"
+  fallback: "ours",
 });
 
 await resolveConflicts({
@@ -91,8 +93,8 @@ The plugin now uses `validateStrict` from compare-versions and properly handles
 
 ```ts
 // Now properly handles these cases:
-"^1.2.3" // Strips ^ prefix before validation
-"1.2.3-beta.1" // Handled based on strict mode setting
+"^1.2.3"; // Strips ^ prefix before validation
+"1.2.3-beta.1"; // Handled based on strict mode setting
 ```
 
 #### Factory Pattern Benefits
@@ -116,10 +118,13 @@ All configuration options remain the same:
 ### Troubleshooting
 
 **Error: "Cannot read property 'strategies' of undefined"**
+
 - You're likely importing the old way. Use `createSemverPlugin()` or individual strategy exports.
 
 **Error: "plugin.init is not a function"**
+
 - Use the new `init` named export instead of `plugin.init`.
 
 **Semver validation behaving differently**
-- The new validation is more accurate. Check if your versions need the `strict: false` option.
+
+- The new validation is more accurate. Check if your versions need the `strict: false` option.

docs/index.md

@@ -64,9 +64,24 @@ pnpm install git-json-resolver
 ### 1. Direct Import
 
 ```ts
-import { semverMax } from "git-json-resolver-semver";
+import createSemverPlugin, { semverMax } from "git-json-resolver-semver";
 import { resolveConflicts } from "git-json-resolver";
 
+// Option 1: Use factory function with custom config
+const plugin = createSemverPlugin({
+  strict: false,
+  fallback: "ours",
+});
+
+await resolveConflicts({
+  customStrategies: plugin.strategies,
+  rules: {
+    "dependencies.react": ["semver-max"],
+    "devDependencies.vitest": ["semver-min"],
+  },
+});
+
+// Option 2: Use individual strategy exports - not scoped @see migration guide for more details
 await resolveConflicts({
   customStrategies: {
     "semver-max": semverMax,
@@ -109,11 +124,39 @@ export default config;
 
 ---
 
-## ⚙️ Behavior notes
+## ⚙️ Configuration
+
+### Factory Pattern (Recommended)
+
+```ts
+import createSemverPlugin from "git-json-resolver-semver";
+
+const plugin = createSemverPlugin({
+  strict: true, // Use validateStrict for exact semver only
+  preferValid: true, // Prefer valid semver when only one side is valid
+  fallback: "continue", // Behavior when both sides invalid
+  preferRange: false, // Future: merge into semver ranges
+  workspacePattern: "", // Pattern for workspace rules
+});
+```
+
+### Global Configuration
+
+```ts
+import { init } from "git-json-resolver-semver";
+
+init({
+  strict: false, // Allow prereleases and ranges
+  fallback: "ours",
+});
+```
+
+### Behavior Notes
 
-- **strict** mode (default) accepts only `x.y.z`. Set non-strict to allow prereleases/ranges.
-- **preferValid** (default) returns the valid side when the other is invalid.
-- **fallback** controls behavior when neither side is valid (`ours` | `theirs` | `continue` | `error`).
+- **strict** mode uses `validateStrict` - only accepts `x.y.z` format
+- **preferValid** returns the valid side when the other is invalid
+- **fallback** controls behavior when neither side is valid
+- Version prefixes like `^1.2.3` are automatically handled
 
 ## ⚙️ Strategies
 
@@ -142,5 +185,5 @@ This library is licensed under the MPL-2.0 open-source license.
 
 ## Modules
 
-- [index](index.md)
+- [index](index/README.md)
 - [index.test](index.test.md)

docs/index/-internal-.md

@@ -0,0 +1,46 @@
+---
+layout: default
+title: Internal
+parent: Index
+nav_order: 4
+---
+
+# \<internal\>
+
+## Interfaces
+
+### SemverPluginConfig
+
+Defined in: [index.ts:27](https://github.com/react18-tools/git-json-resolver-semver/blob/50e3ea62d91488fe5a6f02d1c59f11b20e40d81f/lib/src/index.ts#L27)
+
+#### Properties
+
+##### fallback?
+
+> `optional` **fallback**: `"ours"` \| `"theirs"` \| `"continue"` \| `"error"`
+
+Defined in: [index.ts:29](https://github.com/react18-tools/git-json-resolver-semver/blob/50e3ea62d91488fe5a6f02d1c59f11b20e40d81f/lib/src/index.ts#L29)
+
+##### preferRange?
+
+> `optional` **preferRange**: `boolean`
+
+Defined in: [index.ts:31](https://github.com/react18-tools/git-json-resolver-semver/blob/50e3ea62d91488fe5a6f02d1c59f11b20e40d81f/lib/src/index.ts#L31)
+
+##### preferValid?
+
+> `optional` **preferValid**: `boolean`
+
+Defined in: [index.ts:30](https://github.com/react18-tools/git-json-resolver-semver/blob/50e3ea62d91488fe5a6f02d1c59f11b20e40d81f/lib/src/index.ts#L30)
+
+##### strict?
+
+> `optional` **strict**: `boolean`
+
+Defined in: [index.ts:28](https://github.com/react18-tools/git-json-resolver-semver/blob/50e3ea62d91488fe5a6f02d1c59f11b20e40d81f/lib/src/index.ts#L28)
+
+##### workspacePattern?
+
+> `optional` **workspacePattern**: `string`
+
+Defined in: [index.ts:32](https://github.com/react18-tools/git-json-resolver-semver/blob/50e3ea62d91488fe5a6f02d1c59f11b20e40d81f/lib/src/index.ts#L32)

docs/index/README.md

@@ -0,0 +1,99 @@
+---
+layout: default
+title: README
+parent: Index
+nav_order: 5
+---
+
+# index
+
+## Modules
+
+- [\<internal\>](-internal-.md)
+
+## Variables
+
+### semverMax
+
+> `const` **semverMax**: `StrategyFn`\<`unknown`\>
+
+Defined in: [index.ts:153](https://github.com/react18-tools/git-json-resolver-semver/blob/50e3ea62d91488fe5a6f02d1c59f11b20e40d81f/lib/src/index.ts#L153)
+
+---
+
+### semverMin
+
+> `const` **semverMin**: `StrategyFn`\<`unknown`\>
+
+Defined in: [index.ts:154](https://github.com/react18-tools/git-json-resolver-semver/blob/50e3ea62d91488fe5a6f02d1c59f11b20e40d81f/lib/src/index.ts#L154)
+
+---
+
+### semverOurs
+
+> `const` **semverOurs**: `StrategyFn`\<`unknown`\>
+
+Defined in: [index.ts:155](https://github.com/react18-tools/git-json-resolver-semver/blob/50e3ea62d91488fe5a6f02d1c59f11b20e40d81f/lib/src/index.ts#L155)
+
+---
+
+### semverTheirs
+
+> `const` **semverTheirs**: `StrategyFn`\<`unknown`\>
+
+Defined in: [index.ts:156](https://github.com/react18-tools/git-json-resolver-semver/blob/50e3ea62d91488fe5a6f02d1c59f11b20e40d81f/lib/src/index.ts#L156)
+
+## Functions
+
+### createSemverPlugin()
+
+> **createSemverPlugin**(`pluginConfig`: [`SemverPluginConfig`](-internal-.md#semverpluginconfig)): `StrategyPlugin`
+
+Defined in: [index.ts:62](https://github.com/react18-tools/git-json-resolver-semver/blob/50e3ea62d91488fe5a6f02d1c59f11b20e40d81f/lib/src/index.ts#L62)
+
+Creates semver-aware strategies for `git-json-resolver`.
+
+## Strategies
+
+| Strategy        | Behavior                                                              | Example (`ours` vs `theirs`) | Result  |
+| --------------- | --------------------------------------------------------------------- | ---------------------------- | ------- |
+| `semver-max`    | Picks the higher valid semver                                         | `1.2.3` vs `1.3.0`           | `1.3.0` |
+| `semver-min`    | Picks the lower valid semver                                          | `2.0.0` vs `2.1.0`           | `2.0.0` |
+| `semver-ours`   | Picks `ours` if valid semver, else apply `preferValid` / `fallback`   | `1.2.3` vs `banana`          | `1.2.3` |
+| `semver-theirs` | Picks `theirs` if valid semver, else apply `preferValid` / `fallback` | `foo` vs `2.0.0`             | `2.0.0` |
+
+Configuration options (`pluginConfig`):
+
+- `strict` → use validateStrict - https://github.com/omichelsen/compare-versions?tab=readme-ov-file#validate-version-numbers-strict
+- `fallback` → behavior when both invalid (`ours` | `theirs` | `continue` | `error`)
+- `preferValid` → if only one side is valid semver, take it
+- `preferRange` → merge into semver range (future)
+- `workspacePattern` → pattern for workspace rules (e.g. `workspaces:*`)
+
+#### Parameters
+
+##### pluginConfig
+
+[`SemverPluginConfig`](-internal-.md#semverpluginconfig) = `defaultConfig`
+
+#### Returns
+
+`StrategyPlugin`
+
+---
+
+### init()
+
+> **init**(`config`: [`SemverPluginConfig`](-internal-.md#semverpluginconfig)): `void`
+
+Defined in: [index.ts:158](https://github.com/react18-tools/git-json-resolver-semver/blob/50e3ea62d91488fe5a6f02d1c59f11b20e40d81f/lib/src/index.ts#L158)
+
+#### Parameters
+
+##### config
+
+[`SemverPluginConfig`](-internal-.md#semverpluginconfig)
+
+#### Returns
+
+`void`

docs/index/index.md

@@ -0,0 +1,8 @@
+---
+layout: default
+title: Index
+nav_order: 3
+has_children: true
+---
+
+# Index

package.json

@@ -42,4 +42,4 @@
       "next@>=15.0.0 <15.2.3": ">=15.2.3"
     }
   }
-}
+}