@wocha/upgrade

Automated codemods for upgrading @wocha/* SDK packages. Detects installed versions, applies AST-level transforms for breaking changes, and updates package.json dependency ranges.

Usage

npx @wocha/upgrade

From the monorepo during development:

pnpm --filter @wocha/upgrade build
node tools/upgrade/dist/index.js

Example output

  @wocha/upgrade v0.1.0

  Detected packages:
    @wocha/react    0.1.0 → 0.2.0
    @wocha/nextjs   0.1.0 → 0.2.0

  Codemods to apply:
    ✓ rename-provider (affects 3 files)
    ✓ update-hook-return (affects 5 files)
    ✓ middleware-config (affects 1 file)

  ? Apply changes? (Y/n)

  Applied 3 codemods across 9 files.
  Updated package.json versions.

  Run `pnpm install` to complete the upgrade.

Flags

| Flag | Description | |------|-------------| | --dry-run | Preview codemod changes without writing files or updating package.json | | --package <name> | Upgrade a single package, e.g. @wocha/react | | --from <version> | Override the detected current version | | --to <version> | Target version (default: latest from npm registry) | | --cwd <path> | Project directory to upgrade (default: current directory) | | --yes, -y | Apply changes without prompting | | --help, -h | Show help |

How it works

1. Detect — Reads package.json and finds all @wocha/* dependencies.
2. Compare — Queries the npm registry for the latest version of each package.
3. Plan — Selects codemods whose version falls between your current and target versions.
4. Preview — Runs each transform in dry mode to count affected files.
5. Apply — Runs jscodeshift transforms on matching TypeScript/JSX files and bumps dependency versions.

Writing custom codemods

Codemods live in src/codemods/<version>/ and export a default jscodeshift transform:

import type { API, FileInfo, Options } from "jscodeshift";

export default function myTransform(file: FileInfo, api: API, _options: Options) {
  const j = api.jscodeshift.withParser("tsx");
  const root = j(file.source);
  let changed = false;

  // ... AST mutations ...

  return changed ? root.toSource() : null;
}

Register the codemod in src/registry.ts:

{
  id: "my-codemod",
  version: "0.3.0",
  package: "@wocha/react",
  description: "Short description of the breaking change",
  transform: "codemods/v0.3/my-codemod.js",
}

The version field is the SDK release that introduces the breaking change. Codemods run when upgrading from a version below version to a version at or above it.

Add the file to tsup.config.ts entry array so it is compiled to dist/.

Contributing new codemods

1. Create a transform under src/codemods/v<release>/.

2. Add an entry to src/registry.ts with the target package and release version.

3. Add the file path to tsup.config.ts entries.

4. Test against a sample project:

   pnpm build
   node dist/index.js --dry-run --from 0.1.0 --to 0.2.0 --cwd ../../examples/react-quickstart

5. Document the breaking change in the SDK CHANGELOG.

Included example codemods (v0.1 → v0.2)

| ID | Package | Change | |----|---------|--------| | rename-provider | @wocha/react, @wocha/nextjs | WochaProvider → WochaAuthProvider | | update-hook-return | @wocha/react, @wocha/nextjs | useSession().session → useSession().data | | middleware-config | @wocha/nextjs | withWochaAuth({ publicPaths }) → { publicRoutes } |

These represent hypothetical breaking changes for demonstration purposes.

License

Apache-2.0