Skip to content

Commit 49a9622

Browse files
mayank1513mayank1513
committed
feat: add CLI interface and update documentation
- Add new CLI module (lib/src/cli.ts) with 128 lines - Update README.md with improved structure and examples - Refactor normalizer.ts implementation - Update package.json dependencies - Export CLI functionality in index.ts
1 parent 490d49b commit 49a9622

File tree

6 files changed

+240
-192
lines changed

6 files changed

+240
-192
lines changed

‎.tkb‎

Lines changed: 2 additions & 98 deletions
Original file line numberDiff line numberDiff line change
@@ -1,71 +1,11 @@
11
{
22
"scope": "Workspace",
33
"tasks": {
4-
"G-1H47JpSI69kav1qZ-kp": {
5-
"id": "G-1H47JpSI69kav1qZ-kp",
6-
"description": "Star [this repository](https://github.com/react18-tools/turborepo-template/) for easy access and to show your support",
7-
"columnId": "column-todo"
8-
},
9-
"gbzyhx0FwFfzRoE-iqVeu": {
10-
"id": "gbzyhx0FwFfzRoE-iqVeu",
11-
"description": "run `yarn rebrand` to rebrand and clean up the repo; the `rebrand` script will automatically rebrand the repo, adjust workflows, and create a commit",
12-
"columnId": "column-todo"
13-
},
14-
"Y5__aEZl3Pbxp7r90HKpV": {
15-
"id": "Y5__aEZl3Pbxp7r90HKpV",
16-
"description": "Install `pnpm` using `npm i -g pnpm`",
17-
"columnId": "column-todo"
18-
},
19-
"jcpymbi71e702p7n6fwvZ": {
20-
"id": "jcpymbi71e702p7n6fwvZ",
21-
"description": "Install dependencies using `pnpm`: run `pnpm i`.",
22-
"columnId": "column-todo"
23-
},
24-
"jdZxwLymOo7w2eZeNpvsN": {
25-
"id": "jdZxwLymOo7w2eZeNpvsN",
26-
"description": "Run `yarn plop`, and follow prompts to generate server or client components for your library",
27-
"columnId": "column-todo"
28-
},
29-
"RX4J5v4y5IOe_ucf8pMRT": {
30-
"id": "RX4J5v4y5IOe_ucf8pMRT",
31-
"description": "🌟 Enable [private vulnerability reporting](https://github.com/react18-tools/git-json-resolver/security) (For public repo - do this after updating visibility to public)",
32-
"columnId": "column-todo"
33-
},
34-
"EdPbrbJLllUHfZmCS80f7": {
35-
"id": "EdPbrbJLllUHfZmCS80f7",
36-
"description": "Set up `CodeCov`\n - Visit Codecov and set up your repo\n - Create [repository secret]((https://github.com/react18-tools/git-json-resolver/settings/secrets/actions)) for `CODECOV_TOKEN`",
37-
"columnId": "column-todo"
38-
},
394
"MLLUsAhCKaKxvEXFY0HSq": {
405
"id": "MLLUsAhCKaKxvEXFY0HSq",
416
"description": "Set up `CodeClimate`\n - Visit CodeClimate and set up your repo\n - Create [repository secret] for `CC_TEST_REPORTER_ID`\n - Add `*.test.*` to ignore patterns on the website\n - Update Code Climate badge",
427
"columnId": "column-todo"
438
},
44-
"gMYfaAh2RABMP8uZRQgNx": {
45-
"id": "gMYfaAh2RABMP8uZRQgNx",
46-
"description": "Add `NPM_AUTH_TOKEN` to repository secrets to automate package publishing\n - Log in to your [`npm` account](https://www.npmjs.com/login) and create an automation token\n - Create a new repository secret `NPM_AUTH_TOKEN`",
47-
"columnId": "column-todo"
48-
},
49-
"_BfuX7quWBANpDK1bI7YM": {
50-
"id": "_BfuX7quWBANpDK1bI7YM",
51-
"description": "Update description in `lib/package.json`",
52-
"columnId": "column-todo"
53-
},
54-
"dC7QDBLH8BmHUfaYmIt81": {
55-
"id": "dC7QDBLH8BmHUfaYmIt81",
56-
"description": "(Optional) Add Repo Stats by visiting and setting up [repobeats](https://repobeats.axiom.co/)",
57-
"columnId": "column-todo"
58-
},
59-
"P_NrSJQ8m91Odgz8E1fS6": {
60-
"id": "P_NrSJQ8m91Odgz8E1fS6",
61-
"description": "Create your library and update examples",
62-
"columnId": "column-todo"
63-
},
64-
"1dRWJhy45E1Rq5wZAmPHt": {
65-
"id": "1dRWJhy45E1Rq5wZAmPHt",
66-
"description": "Update README as required",
67-
"columnId": "column-todo"
68-
},
699
"5vS1JNXoMhDl5IBljwh2v": {
7010
"id": "5vS1JNXoMhDl5IBljwh2v",
7111
"description": "Set up GitHub pages to deploy docs\n - Go to [repo settings](https://github.com/react18-tools/git-json-resolver/settings/pages) -> pages (On the left panel); Select deploy from a branch; Then Select `main` and `/docs`",
@@ -76,26 +16,6 @@
7616
"description": "(Optional) Set up [Deepsource](https://app.deepsource.com/login) for static code analysis",
7717
"columnId": "column-todo"
7818
},
79-
"FDFqCQvLm2mUlnTJ3Gna5": {
80-
"id": "FDFqCQvLm2mUlnTJ3Gna5",
81-
"description": "Push your changes/Create PR and see your library being automatically tested and published",
82-
"columnId": "column-todo"
83-
},
84-
"O1qAByMoxhHOR-a_guL91": {
85-
"id": "O1qAByMoxhHOR-a_guL91",
86-
"description": "Optionally deploy your examples to Vercel.",
87-
"columnId": "column-todo"
88-
},
89-
"0499BqWDwJ5cxqtC9Nr82": {
90-
"id": "0499BqWDwJ5cxqtC9Nr82",
91-
"description": "Feel free to star this template, contribute, and/or sponsor the [`terborepo-template`](https://github.com/react18-tools/turborepo-template) project or my [other open-source work](https://github.com/sponsors/mayank1513)",
92-
"columnId": "column-todo"
93-
},
94-
"IjuAtNquJ4-Ut874rHKIW": {
95-
"id": "IjuAtNquJ4-Ut874rHKIW",
96-
"description": "You can also fork the [`terborepo-template`](https://github.com/react18-tools/turborepo-template/fork) and add your package to `scripts/featured.json`\n - If approved, your package will be automatically added to FEATURED.md and also published on the home page of this repo.",
97-
"columnId": "column-todo"
98-
},
9919
"_JiH9RZLmUF5nxD7lBC5B": {
10020
"id": "_JiH9RZLmUF5nxD7lBC5B",
10121
"description": "Create a new GitHub repository using this template.\n - Click the `Use this template` button at the top right -> `Create a new repository`\n - Click `Create repository` and wait for the setup workflow to finish rebranding your repo.",
@@ -117,25 +37,9 @@
11737
"id": "column-todo",
11838
"title": "To do",
11939
"tasksIds": [
120-
"G-1H47JpSI69kav1qZ-kp",
121-
"Y5__aEZl3Pbxp7r90HKpV",
122-
"jcpymbi71e702p7n6fwvZ",
123-
"gbzyhx0FwFfzRoE-iqVeu",
124-
"jdZxwLymOo7w2eZeNpvsN",
125-
"RX4J5v4y5IOe_ucf8pMRT",
126-
"EdPbrbJLllUHfZmCS80f7",
12740
"MLLUsAhCKaKxvEXFY0HSq",
128-
"gMYfaAh2RABMP8uZRQgNx",
129-
"_BfuX7quWBANpDK1bI7YM",
130-
"dC7QDBLH8BmHUfaYmIt81",
131-
"P_NrSJQ8m91Odgz8E1fS6",
132-
"1dRWJhy45E1Rq5wZAmPHt",
13341
"5vS1JNXoMhDl5IBljwh2v",
134-
"55DAZwduwTvlaxaJC8hlX",
135-
"FDFqCQvLm2mUlnTJ3Gna5",
136-
"O1qAByMoxhHOR-a_guL91",
137-
"0499BqWDwJ5cxqtC9Nr82",
138-
"IjuAtNquJ4-Ut874rHKIW"
42+
"55DAZwduwTvlaxaJC8hlX"
13943
]
14044
},
14145
{
@@ -153,4 +57,4 @@
15357
]
15458
}
15559
]
156-
}
60+
}

‎README.md‎

Lines changed: 79 additions & 72 deletions
Original file line numberDiff line numberDiff line change
@@ -7,25 +7,26 @@
77
[![Downloads](https://img.jsdelivr.com/img.shields.io/npm/d18m/git-json-resolver.svg)](https://www.npmjs.com/package/git-json-resolver)
88
![npm bundle size](https://img.shields.io/bundlephobia/minzip/git-json-resolver)
99

10-
Git Json Resolver is a comprehensive library designed to unlock the full potential of React 18 server components. It provides customizable loading animation components and a fullscreen loader container, seamlessly integrating with React and Next.js.
10+
A Git-aware conflict resolver for **JSON-first structured data**.
1111

12-
✅ Fully Treeshakable (import from `git-json-resolver/client/loader-container`)
12+
## Why?
1313

14-
✅ Fully TypeScript Supported
14+
- Git merge conflicts in structured files (JSON, YAML, XML, TOML) are painful.
15+
- Manual resolution is error-prone, time-consuming, and breaks CI/CD pipelines.
16+
- `git-json-resolver` automates conflict handling with **configurable strategies**.
17+
- Non-JSON formats are internally normalized to JSON → resolved → converted back.
1518

16-
✅ Leverages the power of React 18 Server components
19+
## Features
1720

18-
✅ Compatible with all React 18 build systems/tools/frameworks
21+
- ⚡ **Primary focus on JSON** (first-class support)
22+
- 🔄 **YAML, XML, TOML** supported via conversion
23+
- 🧩 **Rule-based strategies** (per path/pattern)
24+
- 🗂️ Handles small configs to **huge repos** (optimizations built-in)
25+
- 🔌 **Pluggable matcher** abstraction (picomatch, micromatch supported out of the box with peerDependency)
26+
- 🛠️ Configurable trade-offs for **speed vs. memory**
27+
- 🗃️ **Planned**: extend configuration to use **different strategies per file** (ideas and edge cases welcome!)
1928

20-
✅ Documented with [Typedoc](https://react18-tools.github.io/git-json-resolver) ([Docs](https://react18-tools.github.io/git-json-resolver))
21-
22-
✅ Examples for Next.js, and Vite
23-
24-
> <img src="https://raw.githubusercontent.com/mayank1513/mayank1513/main/popper.png" style="height: 20px"/> Star [this repository](https://github.com/react18-tools/git-json-resolver) and share it with your friends.
25-
26-
## Getting Started
27-
28-
### Installation
29+
## Installation
2930

3031
```bash
3132
pnpm add git-json-resolver
@@ -43,92 +44,98 @@ npm install git-json-resolver
4344
yarn add git-json-resolver
4445
```
4546

46-
## Want Lite Version? [![npm bundle size](https://img.shields.io/bundlephobia/minzip/git-json-resolver-lite)](https://www.npmjs.com/package/git-json-resolver-lite) [![Version](https://img.shields.io/npm/v/git-json-resolver-lite.svg?colorB=green)](https://www.npmjs.com/package/git-json-resolver-lite) [![Downloads](https://img.jsdelivr.com/img.shields.io/npm/d18m/git-json-resolver-lite.svg)](https://www.npmjs.com/package/git-json-resolver-lite)
47+
## Quick Start
4748

48-
```bash
49-
pnpm add git-json-resolver-lite
50-
```
51-
52-
**or**
49+
Add a custom merge driver to your Git config:
5350

5451
```bash
55-
npm install git-json-resolver-lite
52+
git config merge.json-resolver.name "Custom JSON merge driver"
53+
git config merge.json-resolver.driver "npx git-json-resolver %A %O %B"
5654
```
5755

58-
**or**
56+
Update `.gitattributes` to use it for JSON files:
5957

60-
```bash
61-
yarn add git-json-resolver-lite
58+
```gitattributes
59+
*.json merge=json-resolver
6260
```
6361

64-
> You need `r18gs` as a peer-dependency
62+
## Example Config
63+
64+
```ts
65+
import { resolveConflicts } from "git-json-resolver";
66+
67+
const result = resolveConflicts({
68+
filePath: "package.json",
69+
rules: [
70+
{ pattern: "dependencies.*", strategy: "ours" },
71+
{ pattern: "version", strategy: "theirs", important: true },
72+
{ pattern: "scripts.build", strategy: "manual" },
73+
],
74+
matcher: "picomatch", // default
75+
optimize: {
76+
cacheMatchers: true,
77+
streamMode: false, // set true for very large repos
78+
},
79+
});
80+
```
6581

66-
### Import Styles
82+
### Upcoming: File-Specific Strategies
6783

68-
You can import styles globally or within specific components.
84+
We are exploring the ability to define **per-file strategy sets** in config, e.g.:
6985

70-
```css
71-
/* globals.css */
72-
@import "git-json-resolver/dist";
86+
```ts
87+
rulesByFile: {
88+
"package.json": { version: ["theirs"], dependencies: ["ours"] },
89+
"*.config.json": { "*": ["merge"] },
90+
},
7391
```
7492

75-
```tsx
76-
// layout.tsx
77-
import "git-json-resolver/dist/index.css";
78-
```
93+
This raises interesting questions/edge cases:
7994

80-
For selective imports:
95+
- How to merge file-level vs. global rules?
96+
- Should `include/exclude` still apply if a file is explicitly listed?
97+
- Should conflicting rules between file + global fall back to default strategy or error?
8198

82-
```css
83-
/* globals.css */
84-
@import "git-json-resolver/dist/client"; /** required if you are using LoaderContainer */
85-
@import "git-json-resolver/dist/server/bars/bars1";
86-
```
99+
We welcome ideas & edge cases here!
87100

88-
### Usage
101+
## Supported Strategies
89102

90-
Using loaders is straightforward.
103+
- **ours** → take current branch value
104+
- **theirs** → take incoming branch value
105+
- **manual** → mark for human resolution
106+
- **drop** → remove the key entirely
107+
- **custom** → user-defined resolver function
91108

92-
```tsx
93-
import { Bars1 } from "git-json-resolver/dist/server/bars/bars1";
109+
## Supported Formats
94110

95-
export default function MyComponent() {
96-
return someCondition ? <Bars1 /> : <>Something else...</>;
97-
}
98-
```
111+
- **JSON** (native)
112+
- **YAML, XML, TOML** → converted to JSON → resolved → converted back
99113

100-
For detailed API and options, refer to [the API documentation](https://react18-tools.github.io/git-json-resolver).
114+
## Performance & Optimization
101115

102-
**Using LoaderContainer**
116+
- **Matcher caching** for repeated patterns
117+
- **Streaming mode** for very large repos (low memory footprint)
118+
- Trade-offs are configurable via `optimize` field
103119

104-
`LoaderContainer` is a fullscreen component. You can add this component directly in your layout and then use `useLoader` hook to toggle its visibility.
120+
## Roadmap
105121

106-
```tsx
107-
// layout.tsx
108-
<LoaderContainer />
109-
...
110-
```
122+
- [ ] Richer strategies via plugins (e.g., semantic version resolver)
123+
- [ ] CLI UX improvements
124+
- [ ] Pluggable format converters customizations
125+
- [ ] VSCode integration for previewing merge resolutions
126+
- [ ] **Per-file strategies support** (current RFC)
111127

112-
```tsx
113-
// some other page or component
114-
import { useLoader } from "git-json-resolver/dist/hooks";
115-
116-
export default MyComponent() {
117-
const { setLoading } = useLoader();
118-
useCallback(()=>{
119-
setLoading(true);
120-
...do some work
121-
setLoading(false);
122-
}, [])
123-
...
124-
}
125-
```
128+
## Contributing
126129

127-
## License
130+
Contributions welcome 🙌
128131

129-
This library is licensed under the MPL-2.0 open-source license.
132+
- Fork, branch, PR — with tests (`vitest` required)
133+
- Docs live in `libDocs/` (tutorials, guides, deep dives)
134+
- API reference generated into `docs/` via TypeDoc
130135

136+
## License
131137

138+
This library is licensed under the MPL-2.0 open-source license.
132139

133140
> <img src="https://raw.githubusercontent.com/mayank1513/mayank1513/main/popper.png" style="height: 20px"/> Please enroll in [our courses](https://mayank-chaudhari.vercel.app/courses) or [sponsor](https://github.com/sponsors/mayank1513) our work.
134141

‎lib/package.json‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -22,6 +22,9 @@
2222
"require": "./dist/index.js"
2323
}
2424
},
25+
"bin": {
26+
"git-json-resolver": "./dist/cli.mjs"
27+
},
2528
"scripts": {
2629
"build": "tsup && tsc -p tsconfig-build.json && gzip -c dist/index.js | wc -c",
2730
"clean": "rm -rf dist",

0 commit comments

Comments
 (0)