# UPGRADING — `@yaoc1996/js-tools`

Procedures for AI coding agents (and humans) upgrading this package in a **consumer app**. If you're working *inside* this package's repo, see [`AGENTS.md`](./AGENTS.md) instead.

When a consumer app needs to move to a newer version, pick **one** workflow:

```
node_modules/@yaoc1996/js-tools/CHANGELOG.md exists?
├── No  →  Workflow B
└── Yes →  Contains entries for every version from <current> up to <target>?
           ├── No  →  Workflow B
           └── Yes →  Workflow A
```

In practice: any upgrade *from* a version ≤ 2.0.5 uses Workflow B (the changelog starts at 2.0.5 with no retroactive breaking-change entries).

## Workflow A — Guided upgrade

1. Read `node_modules/@yaoc1996/js-tools/CHANGELOG.md` for every release between current and target. Collect all bullets under `### Breaking changes`.
2. For each breaking-change entry that links to `docs/migrations/v<X>-to-v<Y>.md`, read that file in full.
3. For each entry: in the consumer app, grep for the affected `{ subpath, symbol }` and apply the migration. Use ripgrep when available:
   ```
   rg -n "from ['\"]@yaoc1996/js-tools(/[a-z-]+)?['\"]" --type ts --type tsx
   ```
4. Bump the version in the consumer's `package.json`, run `pnpm install` (or npm/yarn equivalent), then run the consumer's typecheck and tests. Resolve all errors.

## Workflow B — Audit upgrade (no migration info)

Use when `CHANGELOG.md` is missing entries for the version range. The agent reconstructs the migration from the published type declarations.

1. **Enumerate every imported symbol** from this package in the consumer app:
   ```
   rg -n "from ['\"]@yaoc1996/js-tools(/[a-z-]+)?['\"]" --type ts --type tsx
   ```
   For each match, parse the import clause and produce a set of `{ subpath, symbol }` pairs. Include type-only imports and namespace imports. Don't skip workers (`@yaoc1996/js-tools/workers/*`).

2. **Install the target version** in the consumer (`pnpm add @yaoc1996/js-tools@<target>`). The next steps read from `node_modules/@yaoc1996/js-tools/dist/*.d.ts`, so confirm those files exist after install (`ls node_modules/@yaoc1996/js-tools/dist/*.d.ts`). Caveats:
   - **Workspace protocol / monorepo:** if the consumer uses `workspace:*` or links via pnpm/yarn workspaces, `pnpm add` may not refresh `node_modules` — run `pnpm install --force` or rebuild the linked package (`pnpm --filter @yaoc1996/js-tools build`).
   - **Stale dist:** if `dist/*.d.ts` is missing or older than `src/`, the package was published without a build step. Fall back to reading the source in `node_modules/@yaoc1996/js-tools/src/` if shipped, or fetch the version's tarball from npm.

3. **For each `{ subpath, symbol }` pair**, check against the new version's declaration file:
   - **Path:** `node_modules/@yaoc1996/js-tools/dist/<subpath>.d.ts`. For the root export, use `dist/index.d.ts`. For workers, the subpath maps to `dist/workers/<name>.d.ts`.
   - **If the symbol is missing from the expected file:**
     - Grep all sibling `.d.ts` files under `dist/` for the symbol name. If found elsewhere, the export moved — update the consumer's import path.
     - If not found anywhere, the symbol was removed or renamed. Look for a likely replacement by:
       (a) reading `node_modules/@yaoc1996/js-tools/docs/public/<module>/` for an entry with a similar name or purpose, then
       (b) grepping `dist/*.d.ts` for related identifiers (e.g., if `useThreeObject` is gone, search for `useThree*`).
     - If still no replacement, this is a true removal — flag it in `UPGRADE-NOTES.md` (see step 5) and leave a TODO in the consumer code, or implement the dropped functionality locally.
   - **If the symbol exists but the signature changed:** diff against the call site. Update arguments, return-type usage, generics, and any destructured fields on the return value.
   - **If the symbol exists and the signature is unchanged:** check `docs/public/<module>/<symbol>.md` (if shipped) for behavioral changes — runtime semantics can change without a type change. Also check for `@deprecated` JSDoc tags on the imported symbols — Tier 3 commodity modules are marked for removal (see CHANGELOG.md § Deprecated for replacement npm packages).

4. **Verify.** Run the consumer's typecheck first, then tests, then (for UI code) exercise the affected screen in a browser. Resolve all type errors before runtime testing.

5. **Record findings.** For every change that *should have been* a `CHANGELOG.md` entry, append a one-line note to `UPGRADE-NOTES.md` at the consumer-app root. Format: `- <subpath> :: <symbol> :: <one-line description>`. This is local-only and helps the next agent (or human) doing a similar upgrade.
