acture-codemods 1.1.0

package/dist/index.d.ts

@@ -0,0 +1,309 @@
+/**
+ * Common types shared across codemods and the CLI runner.
+ *
+ * Per research-4 §B.6, the contract every codemod must honour is:
+ *   - It can run in `--dry-run` mode and produce a diff WITHOUT writing.
+ *   - It can produce machine-readable output (`--json`).
+ *   - It is conservative: when in doubt, skip the file rather than emit
+ *     a partial / dangerous transform. The agent that drives the codemod
+ *     will re-attempt the file manually.
+ */
+interface CodemodOptions {
+    /** Files to operate on. Each entry is an absolute path to a .ts/.tsx
+     *  file. The CLI is responsible for expanding globs into this list. */
+    readonly files: readonly string[];
+    /** Don't write files; return what the diff WOULD be. */
+    readonly dryRun?: boolean;
+    /** Per-codemod options (free-form bag of strings). Each codemod
+     *  documents which keys it reads. */
+    readonly options?: Record<string, string | undefined>;
+}
+interface FileChange {
+    readonly path: string;
+    /** `none` if the file was unchanged; otherwise the new content. */
+    readonly before: string;
+    readonly after: string;
+    /** `true` if the codemod made any change to the file's text. */
+    readonly changed: boolean;
+    /** Non-fatal observations (e.g. "skipped: nested JSX expression
+     *  too complex"). Hosts surface these to the user. */
+    readonly notes?: readonly string[];
+}
+interface CodemodResult {
+    readonly codemod: string;
+    readonly version: string;
+    readonly files: readonly FileChange[];
+    /** Summary counts. The CLI uses these to print the recap. */
+    readonly summary: {
+        readonly total: number;
+        readonly changed: number;
+        readonly skipped: number;
+    };
+}
+interface Codemod {
+    /** Stable id used in the manifest, e.g. `wrap-handler-with-mutation`. */
+    readonly name: string;
+    /** Free-text. Surfaced in `--help` and `--list`. */
+    readonly description: string;
+    /** Runs the codemod against `options.files`. Pure function from
+     *  options to result — does NOT write files unless `dryRun` is false. */
+    run(options: CodemodOptions): Promise<CodemodResult> | CodemodResult;
+}
+
+/**
+ * Codemod registry, Nx-style.
+ *
+ * Each entry pairs a codemod name with the version of acture at which
+ * it was first published. The CLI uses this to:
+ *   - `--list` the catalog,
+ *   - look up a codemod by name,
+ *   - emit a JSON manifest for tooling (`acture-codemods --manifest`).
+ *
+ * Per research-4 §B.5: the v1.2 scope is two of the five planned
+ * codemods. The other three (`redux-action-to-command`,
+ * `usestate-mutation-to-command`, `rtk-thunk-to-command`) are tracked in
+ * the manifest as `status: 'planned'` so users see what's coming.
+ */
+
+interface ManifestEntry {
+    readonly name: string;
+    readonly description: string;
+    readonly status: 'shipped' | 'planned';
+    readonly since?: string;
+    readonly codemod?: Codemod;
+}
+declare const MANIFEST: readonly ManifestEntry[];
+declare function findCodemod(name: string): Codemod | undefined;
+declare function listShipped(): readonly ManifestEntry[];
+
+/**
+ * Programmatic runner used by both the CLI and library consumers.
+ *
+ * Looks up a codemod in the manifest, validates the options, and invokes
+ * the codemod's `run`. Returns the same `CodemodResult` shape the CLI
+ * emits as JSON.
+ */
+
+declare function runCodemod(name: string, options: CodemodOptions): Promise<CodemodResult>;
+
+/**
+ * `wrap-handler-with-mutation`
+ *
+ * Find every `onClick`, `onChange`, `onSubmit` JSX attribute whose value
+ * is an expression and wrap it with `wrapMutation(...)`. Adds the import
+ * if missing.
+ *
+ * Examples:
+ *   <button onClick={save}>Save</button>
+ *   →
+ *   <button onClick={wrapMutation(save)}>Save</button>
+ *
+ *   <form onSubmit={(e) => handler(e)}>
+ *   →
+ *   <form onSubmit={wrapMutation((e) => handler(e))}>
+ *
+ * Idempotent: if the expression is already a call to `wrapMutation`, we
+ * leave it alone.
+ *
+ * Conservative: we skip the attribute (and surface a note) if the
+ * expression contains anything we don't know how to wrap cleanly. The
+ * agent will re-attempt by hand. Specifically, we skip:
+ *   - Attributes that aren't `onClick` / `onChange` / `onSubmit` by
+ *     default (configurable via `--events`).
+ *   - Attribute values that aren't JsxExpression containers (literal
+ *     strings, etc.).
+ *
+ * This is the simplest of the v1.2 codemods — pure structural rewrite,
+ * no type info needed (research-4 §B.5 row 4).
+ */
+
+declare const wrapHandlerWithMutation: Codemod;
+
+/**
+ * `extract-onclick-to-command`
+ *
+ * Lift an inline `onClick={() => …}` (or `onSubmit`/`onChange`) into a
+ * named module-level command registered with `defineCommand`, and
+ * replace the JSX expression with a reference to the command's id
+ * dispatched via the registry.
+ *
+ * Example transform (input):
+ *   <button onClick={() => store.save()}>Save</button>
+ *
+ * Example transform (output):
+ *   const __cmd_handleSave = defineCommand({
+ *     id: 'app.wrapped.handleSave',
+ *     title: 'Handle Save',
+ *     execute: () => { store.save(); return ok(undefined); },
+ *   });
+ *
+ *   <button onClick={() => registry.dispatch(__cmd_handleSave.id)}>Save</button>
+ *
+ * **Scope (research-4 §B.5):** This codemod is intentionally narrow.
+ * It handles arrow-function-with-block / arrow-function-expression
+ * inline handlers that take no parameters and return nothing useful
+ * (the common case for buttons). Handlers that:
+ *   - take parameters (e.g. event objects),
+ *   - return data the caller uses,
+ *   - close over local component state that needs to flow into params,
+ * are SKIPPED with a note. The agent re-attempts those by hand —
+ * conservatism over coverage is the rule (research-4 §B.6).
+ *
+ * Options (read from `--option key=value` on the CLI):
+ *   - `id-prefix`         default `app.wrapped` — the prefix for
+ *                         generated command ids.
+ *   - `registry-import`   default `./acture/registry` — module to import
+ *                         the `registry` symbol from.
+ *   - `acture-import`     default `acture` — module to import
+ *                         `defineCommand` and `ok` from.
+ */
+
+declare const extractOnClickToCommand: Codemod;
+
+/**
+ * `redux-action-to-command`
+ *
+ * Convert Redux-style `dispatch({ type: 'X', payload: ... })` call sites
+ * into `registry.dispatch('X', <payload>)`. Adds the `registry` import
+ * if missing.
+ *
+ * Example transform:
+ *
+ *   dispatch({ type: 'cart/addItem', payload: { id, qty } });
+ *   →
+ *   registry.dispatch('cart/addItem', { id, qty });
+ *
+ *   dispatch({ type: 'cart/clear' });
+ *   →
+ *   registry.dispatch('cart/clear');
+ *
+ * Structurally identical to the `azizhk/dispatch-your-reducer` gist
+ * (research-4 §B.3 ref [29]). Conservative:
+ *   - Skip when the action argument isn't an object literal.
+ *   - Skip when the `type` field isn't a string literal (e.g.
+ *     `dispatch({ type: actionType, ... })` would need type inference).
+ *   - Skip when there are keys other than `type` and `payload` — those
+ *     usually carry Redux-internal metadata that doesn't translate.
+ *   - Skip when the callee identifier isn't in the configured list
+ *     (default: `dispatch`, configurable via `--option callees`).
+ *
+ * Options (from `--option key=value`):
+ *   - `callees`           comma-separated list of dispatch-like callees.
+ *                         Default `dispatch`. Extend with `dispatch,storeDispatch`
+ *                         if your codebase uses multiple names.
+ *   - `registry-import`   default `./acture/registry`. Imported as
+ *                         `{ registry }`.
+ *   - `id-rewrite`        one of `keep` (default), `dot` (rewrite slash to
+ *                         dot — `cart/addItem` → `app.cart.addItem`).
+ */
+
+declare const reduxActionToCommand: Codemod;
+
+/**
+ * `usestate-mutation-to-command`
+ *
+ * Wrap inline `onClick`/`onChange`/`onSubmit` arrow handlers whose body
+ * is composed of useState-setter calls (`setX(...)`) with `wrapMutation`,
+ * deriving a command id from the setter name. Per research-4 §B.5
+ * row 3 — a targeted variant of `wrap-handler-with-mutation` that
+ * specifically lifts useState mutations.
+ *
+ * Example:
+ *
+ *   <button onClick={() => setCount(count + 1)}>+</button>
+ *   →
+ *   <button onClick={wrapMutation(
+ *     () => setCount(count + 1),
+ *     { id: 'app.state.setCount' },
+ *   )}>+</button>
+ *
+ *   <button onClick={() => { setOpen(true); setActive('a'); }}>...</button>
+ *   →
+ *   <button onClick={wrapMutation(
+ *     () => { setOpen(true); setActive('a'); },
+ *     { id: 'app.state.setOpen' },
+ *   )}>...</button>
+ *
+ * The id is derived from the FIRST setter call in the body (if multiple
+ * setters are present), with `app.state` as the default prefix.
+ *
+ * Why this is its own codemod (vs. the general
+ * `wrap-handler-with-mutation`): the general codemod doesn't know the
+ * handler's *intent*. By gating on `setX` calls we get higher-quality
+ * generated ids and avoid wrapping handlers that have side effects
+ * other than state mutation.
+ *
+ * Conservative gates (the agent re-attempts skipped handlers by hand):
+ *   - Body must contain at least one identifier-form CallExpression
+ *     whose callee matches `^set[A-Z]`.
+ *   - All top-level statements / expressions in the body must be one of:
+ *     a CallExpression of a `set*` function, or an existing
+ *     `wrapMutation(...)` call (idempotency). Anything else → skip.
+ *
+ * Options (from `--option key=value`):
+ *   - `id-prefix`         default `app.state` — prefix for generated ids.
+ *   - `setter-pattern`    default `^set[A-Z]` — regex for identifying
+ *                         setter identifiers. Override if the codebase
+ *                         uses a different convention.
+ *   - `events`            default `onClick,onChange,onSubmit`.
+ *   - `import-from`       default `acture-migration`.
+ */
+
+declare const useStateMutationToCommand: Codemod;
+
+/**
+ * `rtk-thunk-to-command`
+ *
+ * Convert RTK's `createAsyncThunk(id, payloadCreator)` into an acture
+ * async command: `defineCommand({ id, title, execute })`. The original
+ * payload creator becomes `execute`, with `return X` rewritten to
+ * `return ok(X)` so the result type matches acture's `Result<R>`
+ * contract.
+ *
+ * Example transform (input):
+ *
+ *   export const fetchUser = createAsyncThunk(
+ *     'users/fetchUser',
+ *     async (id: string) => {
+ *       const res = await fetch(`/users/${id}`);
+ *       return await res.json();
+ *     },
+ *   );
+ *
+ * Example transform (output):
+ *
+ *   export const fetchUser = defineCommand({
+ *     id: 'users/fetchUser',
+ *     title: 'Fetch User',
+ *     execute: async (id: string) => {
+ *       const res = await fetch(`/users/${id}`);
+ *       return ok(await res.json());
+ *     },
+ *   });
+ *
+ * Research-4 §B.5 row 5. This is the type-aware codemod in the v1
+ * planned set — but in practice the "type awareness" is minimal: we
+ * just need to recognise the payload creator's signature (single arg of
+ * any type), not derive its zod schema. Inferring `params` is left to
+ * the user — we emit a note in `FileChange.notes` reminding them to add
+ * a `params:` field if they want palette / MCP / AI surfaces to see a
+ * typed parameter.
+ *
+ * Conservative gates (skipped with a note rather than half-transformed):
+ *   - Skip if `createAsyncThunk` has fewer or more than 2 arguments
+ *     (3rd arg is options — `extraReducers`, `condition`, `idGenerator`
+ *     etc. — none of which map cleanly to a defineCommand spec).
+ *   - Skip if the 1st arg isn't a string literal id.
+ *   - Skip if the 2nd arg isn't an arrow function or function expression.
+ *
+ * Options (from `--option key=value`):
+ *   - `acture-import`     default `acture` — module from which to import
+ *                         `defineCommand` and `ok`.
+ *   - `title-from`        default `id-last-segment` — strategy for
+ *                         deriving the title. Other value: `id` (use the
+ *                         whole id verbatim).
+ */
+
+declare const rtkThunkToCommand: Codemod;
+
+export { type Codemod, type CodemodOptions, type CodemodResult, type FileChange, MANIFEST, type ManifestEntry, extractOnClickToCommand, findCodemod, listShipped, reduxActionToCommand, rtkThunkToCommand, runCodemod, useStateMutationToCommand, wrapHandlerWithMutation };