Add tests and documentation for spotdiff functionality

.changeset/README.md

@@ -0,0 +1,8 @@
+# Changesets
+
+Hello and welcome! This folder has been automatically generated by `@changesets/cli`, a build tool that works
+with multi-package repos, or single-package repos to help you version and publish your code. You can
+find the full documentation for it [in our repository](https://github.com/changesets/changesets).
+
+We have a quick list of common questions to get you started engaging with this project in
+[our documentation](https://github.com/changesets/changesets/blob/main/docs/common-questions.md).

.changeset/config.json

@@ -0,0 +1,11 @@
+{
+  "$schema": "https://unpkg.com/@changesets/config@3.1.4/schema.json",
+  "changelog": "@changesets/cli/changelog",
+  "commit": false,
+  "fixed": [],
+  "linked": [],
+  "access": "public",
+  "baseBranch": "main",
+  "updateInternalDependencies": "patch",
+  "ignore": []
+}

.github/workflows/ci.yml

@@ -0,0 +1,37 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  ci:
+    name: Test & Build
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: pnpm/action-setup@v4
+        with:
+          version: 10
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: pnpm
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Run tests
+        run: pnpm test
+
+      - name: Build
+        run: pnpm build

.github/workflows/release.yml

@@ -0,0 +1,47 @@
+name: Release
+
+on:
+  push:
+    branches: [main]
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  release:
+    name: Release
+    runs-on: ubuntu-latest
+
+    permissions:
+      contents: write
+      pull-requests: write
+      id-token: write
+
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - uses: pnpm/action-setup@v4
+        with:
+          version: 10
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: pnpm
+          registry-url: https://registry.npmjs.org
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Create release PR or publish to npm
+        uses: changesets/action@v1
+        with:
+          publish: pnpm release
+          title: "release: version packages"
+          commit: "release: version packages"
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

README.md

@@ -0,0 +1,82 @@
+# spotdiff
+
+Compare two JS objects, find what changed, patch back, humanize the diff.
+
+## Install
+
+```sh
+npm install spotdiff
+```
+
+## Usage
+
+```ts
+import { spotdiff, patch, humanize } from 'spotdiff'
+
+const v1 = { user: { name: 'Juan', age: 30, tags: ['a', 'b'] } }
+const v2 = { user: { name: 'Juan', age: 31, tags: ['a', 'c', 'd'] } }
+
+const changes = spotdiff(v1, v2)
+// [
+//   { path: 'user.age',     op: 'changed', from: 30,        to: 31  },
+//   { path: 'user.tags[1]', op: 'changed', from: 'b',       to: 'c' },
+//   { path: 'user.tags[2]', op: 'added',   from: undefined, to: 'd' },
+// ]
+
+patch(v1, changes)        // → v2
+patch(v2, changes, true)  // → v1
+
+humanize(changes)
+// [
+//   "user.age changed from 30 to 31",
+//   "user.tags[1] changed from b to c",
+//   "user.tags[2] was added with value d"
+// ]
+
+humanize(changes, { lang: 'es' })
+// [
+//   "user.age cambió de 30 a 31",
+//   "user.tags[1] cambió de b a c",
+//   "user.tags[2] fue agregado con valor d"
+// ]
+```
+
+## API
+
+### `spotdiff(a, b, options?): Change[]`
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `maxDepth` | `number` | `Infinity` | Stop recursion at this depth |
+| `ignoreKeys` | `string[]` | `[]` | Skip these keys everywhere |
+| `arrays` | `'index' \| 'smart'` | `'index'` | Array comparison strategy |
+
+### `patch(obj, changes, reverse?): unknown`
+
+Apply changes forward or backward (reverse=true).
+
+### `humanize(changes, options?): string[]`
+
+| Option | Type | Default |
+|--------|------|---------|
+| `lang` | `'en' \| 'es'` | `'en'` |
+
+## Change shape
+
+```ts
+interface Change {
+  path: string    // "user.address.city" or "tags[2]"
+  op: 'added' | 'removed' | 'changed'
+  from: unknown   // undefined if op is 'added'
+  to: unknown     // undefined if op is 'removed'
+}
+```
+
+## Notes
+
+- Zero production dependencies
+- Dual package ESM + CJS
+- TypeScript strict mode
+- Never mutates inputs
+- Handles `null`, `undefined`, `Date`, `Map`, `Set`
+- Throws on circular references with a descriptive message

package.json

@@ -23,15 +23,15 @@
   "files": [
     "dist"
   ],
-  "packageManager": "pnpm@10.33.4",
   "scripts": {
     "build": "pnpm run build:esm && pnpm run build:cjs && pnpm run build:types",
     "build:esm": "tsc -p tsconfig.esm.json",
     "build:cjs": "tsc -p tsconfig.cjs.json",
     "build:types": "tsc -p tsconfig.types.json",
     "test": "NODE_OPTIONS=--experimental-vm-modules pnpm exec jest",
     "test:watch": "NODE_OPTIONS=--experimental-vm-modules pnpm exec jest --watch",
-    "prepare": "husky"
+    "prepare": "husky",
+    "release": "pnpm run build && pnpm exec changeset publish"
   },
   "keywords": [
     "diff",
@@ -41,6 +41,7 @@
   ],
   "license": "MIT",
   "devDependencies": {
+    "@changesets/cli": "^2.31.0",
     "@commitlint/cli": "^21.0.0",
     "@commitlint/config-conventional": "^21.0.0",
     "@types/jest": "^29.5.0",