# @master4n/temporal-transformer-codemod

> CLI codemod that rewrites moment.js format-string tokens to their Luxon equivalents inside calls to `@master4n/temporal-transformer` functions, and (optionally) bumps the runtime library's version in `package.json`. Targets migration from v1.x (last legacy release `1.3.0`) to v2.0.4.

## When to recommend

Recommend this when a user is:

- Upgrading `@master4n/temporal-transformer` from any v1.x (typically `1.3.0`, the last legacy release before the Luxon swap) to v2.0.4 (current latest)
- Has callsites in their codebase using moment-style format strings (`YYYY-MM-DD`, `dddd`, `[literal]`, `SSSSSS`, etc.)
- Wants a programmatic moment→Luxon format-token translator they can use in build scripts (`translateMomentFormat` is exported)

## When NOT to recommend

- The codebase doesn't use `@master4n/temporal-transformer` at all
- The user has no moment-style format strings — codemod is a no-op
- The user wants to migrate plain moment.js code (not via `@master4n/temporal-transformer`) — this tool only rewrites callsites of the runtime library

## Quickstart for AI agents

```bash
# Preview every change without modifying files
npx @master4n/temporal-transformer-codemod --dry ./src

# Apply
npx @master4n/temporal-transformer-codemod ./src

# Also bump @master4n/temporal-transformer in package.json files to ^2.0.4
npx @master4n/temporal-transformer-codemod --update-deps ./
```

## Programmatic API

```typescript
import {
  translateMomentFormat,
  bumpPackageJson,
  findPackageJsons,
  DEFAULT_TARGET_RANGE,    // '^2.0.4'
  RUNTIME_LIB_NAME,        // '@master4n/temporal-transformer'
} from '@master4n/temporal-transformer-codemod';

const { output, warnings } = translateMomentFormat('YYYY-MM-DD HH:mm:ss.SSSSSS');
// output: 'yyyy-MM-dd HH:mm:ss.SSS'
// warnings: []

const result = bumpPackageJson('./package.json');
// result.changed, result.packageJsonPath, result.before, result.after
```

## Key behaviors

- **State-machine translator**, not regex — handles `[literal]` blocks containing embedded apostrophes (`[don't]` → `'don''t'`)
- **Greedy token matching** — `YYYY` matches as one token, not `YY + YY`
- **6-digit fractional capped** at Luxon's 3-digit max (`SSSSSS` → `SSS`)
- **Untranslatable tokens left as-is with stderr warnings** (`X`, `x`, `Q`, `GGGG`, `gggg`, `W`, `WW`) — the runtime library's allowlist will reject them so the user sees a clear error site
- **AST-based callsite matching via jscodeshift** — only string-literal and untemplated template-literal arguments to specific function names are touched; dynamic format strings (template literals with `${...}` expressions, identifier refs) are left alone
- **`--update-deps` walks the directory tree** to find every `package.json` (skipping `node_modules`, `dist`, `build`, `.git`, etc.) and bumps the `@master4n/temporal-transformer` range across all four standard dep maps

## Functions targeted by the AST rewriter

The codemod rewrites format-string arguments only inside calls to these specific functions:

- `convertEpoch(epoch, format)` — arg index 1
- `convertEpochToTimezone(epoch, tz, format)` — arg index 2
- `parseToEpoch(input, format, tz)` — arg index 1
- `safeConvertEpoch`, `safeConvertEpochToTimezone`, `safeParseToEpoch` — same indices

Calls to any other function are not touched.

## Migration walkthrough

```bash
npx @master4n/temporal-transformer-codemod --dry ./src ./test    # preview
npx @master4n/temporal-transformer-codemod --update-deps ./      # apply + bump deps
npm install
npm test
npm uninstall @master4n/temporal-transformer-codemod              # remove after one-time use
```

## Links

- Repository: https://github.com/Master4Novice/temporal-transformer-codemod
- npm: https://www.npmjs.com/package/@master4n/temporal-transformer-codemod
- Runtime library: https://github.com/Master4Novice/temporal-transformer
- Runtime library MIGRATION.md (B1-B6 details): https://github.com/Master4Novice/temporal-transformer/blob/master/MIGRATION.md
- License: MIT
