@thinksharpe/react-compiler-unmemo 0.5.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Thinksharpe
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,158 @@
+# react-compiler-unmemo
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=flat-square)](https://opensource.org/licenses/MIT)
+[![Node.js](https://img.shields.io/badge/node-%3E%3D18-brightgreen?style=flat-square)](https://nodejs.org)
+
+A codemod that removes `useMemo` and `useCallback` from your React codebase so you can adopt [React Compiler](https://react.dev/learn/react-compiler) without the manual cleanup.
+
+> **Note:** React Compiler works fine with existing manual memoization — it preserves and layers on top of it. Removing hooks is optional for cleanliness and readability, but **not required for performance**. Use this tool to declutter legacy code. Always preview with `--dry-run` and type-check afterward.
+
+## Quick Start
+
+```bash
+npx react-compiler-unmemo ./my-react-app
+```
+
+This previews all changes without modifying any files (dry-run is the safe default). When you're ready to apply:
+
+```bash
+npx react-compiler-unmemo ./my-react-app --write
+```
+
+Or clone and run locally:
+
+```bash
+git clone https://github.com/thinksharpe/react-compiler-unmemo.git
+cd react-compiler-unmemo
+npm install
+node react-compiler-unmemo.mjs ./path/to/your/project
+```
+
+## Origin
+
+I tried using Claude Opus 4.5 to write a script that would remove `useMemo` and `useCallback` from my codebase, but it kept failing. Claude noticed that `sed` couldn't handle this kind of complex pattern matching — the nested parentheses, arrow functions, and dependency arrays made it impossible with simple text replacement. So it wrote this script instead.
+
+I like to keep my code as readable as possible, and all those `useMemo` and `useCallback` hooks were adding extra complexity. I'm glad they're gone from my codebase now. Hope it helps someone else too.
+
+## Before / After
+
+```diff
+- const value = useMemo(() => computeExpensiveValue(a, b), [a, b]);
++ const value = computeExpensiveValue(a, b);
+
+- const handler = useCallback((e) => doSomething(e), [doSomething]);
++ const handler = (e) => doSomething(e);
+
+- import { useMemo, useCallback, useState } from "react";
++ import { useState } from "react";
+```
+
+## Why
+
+- **Cleaner code** — less boilerplate, easier to read and maintain
+- **Aligns with modern React** — React Compiler handles memoization automatically
+- **Smaller bundles** — unused hook imports are removed
+- **Safe to re-run** — idempotent, won't touch already-processed files
+
+## Usage
+
+```bash
+# 1. Preview changes (safe default — no files modified)
+node react-compiler-unmemo.mjs ./my-app
+
+# 2. Apply changes
+node react-compiler-unmemo.mjs ./my-app --write
+
+# 3. Type-check your project
+cd ./my-app && npx tsc --noEmit
+```
+
+## Options
+
+| Flag | Description | Default |
+|------|-------------|--------|
+| *(no flag)* | Preview changes without writing files | **dry-run** |
+| `--write` | Apply changes to files | off |
+| `--verbose` | Log every transformation | off |
+| `--files <glob>` | Limit to specific file patterns | `helpers/**/*.{tsx,ts}` |
+| `--skip-fix` | Skip type annotation repair step | off |
+
+```bash
+# Only process specific directory
+node react-compiler-unmemo.mjs ./my-app --files "hooks/**/*.ts" --write
+
+# app directory
+node react-compiler-unmemo.mjs ./my-app --files "app/**/*.{tsx,ts}"
+
+# See every change in detail
+node react-compiler-unmemo.mjs ./my-app --verbose
+```
+
+## What It Handles
+
+- `useMemo(() => expr, [deps])` → `expr`
+- `useMemo(() => { return expr; }, [deps])` → `expr`
+- `useMemo<Type>(...)` → strips the generic, restores the type annotation
+- `useCallback((params) => body, [deps])` → `(params) => body`
+- `React.useMemo` / `React.useCallback` variants
+- Multi-line hooks spanning dozens of lines
+- Nested generics like `useMemo<ColumnsType<MyType>>()`
+- Import cleanup (removes unused `useMemo`/`useCallback` from imports)
+
+## When NOT to Use
+
+- **You haven't enabled React Compiler yet** — without the compiler, removing `useMemo`/`useCallback` may cause performance regressions
+- **Intentional escape hatches** — some hooks are used deliberately to control referential identity for third-party libraries
+- **Class component interop** — if memoized values are passed to class components that rely on shallow comparison
+
+When in doubt, use `--dry-run` and review the output.
+
+## Post-Migration
+
+**Always run your type checker after the migration:**
+
+```bash
+npx tsc --noEmit
+# or your project's build command
+```
+
+The tool handles the most common cases automatically, but some things need manual attention:
+
+- **Hooks with `//` comments inside** — the parser may skip or partially transform these. Check the "remaining refs" count in the output.
+- **Missing imports** — the type fixer adds `ColumnsType<T>` annotations but may not add the import statement.
+- **Dangling `as Type` casts** — if a `useCallback` had an `as React.FC` cast, it may need cleanup.
+- **Broken IIFEs** — complex `useMemo` bodies with comments may leave a trailing `, [deps])` instead of `})()`.
+
+See [docs/edge-cases.md](./docs/edge-cases.md) for the full list with code examples.
+
+## Project Structure
+
+```
+react-compiler-unmemo/
+├── react-compiler-unmemo.mjs  # Entry point
+├── helpers/
+│   ├── remove-hooks.mjs # Core hook removal
+│   └── fix-type-annotations.mjs
+├── docs/
+│   ├── architecture.md  # How it works under the hood
+│   └── edge-cases.md    # Known edge cases & fixes
+├── package.json
+└── README.md
+```
+
+For technical details on the parser and pipeline, see [docs/architecture.md](./docs/architecture.md).
+
+## Contributing
+
+Issues, PRs, and edge-case examples welcome. Please open an issue first for large changes.
+
+If you've run this on a real codebase and hit an edge case, sharing the pattern (even without proprietary code) helps improve the tool for everyone.
+
+## Links
+
+- [React Compiler — Official Guide](https://react.dev/learn/react-compiler)
+- [React 19 — What's New](https://react.dev/blog/2024/12/05/react-19)
+
+## License
+
+MIT — see [LICENSE](./LICENSE)

package/docs/architecture.md

@@ -0,0 +1,157 @@
+# Architecture
+
+Deep dive into how `react-compiler-unmemo` works under the hood.
+
+## Overview
+
+The tool is a two-step pipeline:
+
+```
+react-compiler-unmemo.mjs
+  ├── Step 1: src/remove-hooks.mjs   → strip useMemo/useCallback
+  └── Step 2: src/fix-type-annotations.mjs → restore lost type annotations
+```
+
+Each script exports a `run(targetDir, options)` function and can also run standalone via CLI.
+
+---
+
+## Step 1: Hook Removal (`src/remove-hooks.mjs`)
+
+### Phase 1: Strip Generic Type Parameters
+
+Before removing the hook call itself, we strip any TypeScript generic type parameters:
+
+```
+useMemo<ColumnsType<TaxArea>>(  →  useMemo(
+```
+
+This is done with a character scanner that counts nested `<>` brackets, since a simple regex like `<[^>]*>` fails on nested generics like `ColumnsType<TaxArea>`.
+
+### Phase 2: Remove Hook Calls
+
+For each occurrence of `useMemo(` or `useCallback(` (including `React.` prefixed variants):
+
+1. **Find the matching closing paren** using a depth-counting parser that tracks `()`, `[]`, `{}` while respecting strings, template literals, and escape sequences.
+
+2. **Strip the dependency array** by scanning for the last `, [` at depth 0 inside the call.
+
+3. **Unwrap the arrow function** by finding `=>` at depth 0.
+
+4. **Generate the replacement:**
+
+   | Pattern | Replacement |
+   |---------|-------------|
+   | `useMemo(() => expr, [deps])` | `expr` |
+   | `useMemo(() => { return expr; }, [deps])` | `expr` |
+   | `useMemo(() => { complex; body; }, [deps])` | `(() => { complex; body; })()` |
+   | `useCallback((a, b) => body, [deps])` | `(a, b) => body` |
+
+5. **Loop** — since indices shift after each replacement, we restart the search after every successful replacement. A safety counter (200 max) prevents infinite loops.
+
+### Phase 3: Clean Imports
+
+After all hooks are removed, we clean up the import statements:
+
+```typescript
+// Before
+import { useMemo, useCallback, useState } from "react";
+
+// After
+import { useState } from "react";
+```
+
+Handles both `import { ... }` and `import React, { ... }` styles. Empty imports are removed entirely.
+
+---
+
+## Step 2: Fix Type Annotations (`src/fix-type-annotations.mjs`)
+
+When `useMemo<ColumnsType<Foo>>(...)` is stripped, the generic type annotation is lost. This step scans for known patterns and restores the annotation on the variable:
+
+```typescript
+// Lost annotation
+const columns = [...]
+
+// Restored
+const columns: ColumnsType<Foo> = [...]
+```
+
+### Type Inference
+
+The script infers the correct type parameter `T` from surrounding code context:
+
+- **`ColumnsType<T>`** — looks for `SorterResult<T>`, `Table<T>`, or `ColumnType<T>` in the same file
+- **`FormFieldProps[]`** — applied to any `formFields` array
+
+Each pattern has an `alreadyTyped` regex to skip files that already have the annotation (idempotent).
+
+---
+
+## Parser Design
+
+The core parser is character-by-character rather than regex-based. This is critical because:
+
+1. **Nested brackets** — `useMemo<ColumnsType<TaxArea>>()` has nested `<>` that regex can't match
+2. **Multi-line constructs** — hooks often span 20+ lines with complex nested objects
+3. **Strings containing brackets** — `"some (text)"` inside a hook body would confuse regex
+4. **Template literals** — `` `${expr}` `` with nested expressions
+
+### String/Template Tracking
+
+The parser tracks three states:
+- **Normal** — counting brackets
+- **In string** — `'...'` or `"..."`, respecting `\\` escapes
+- **In template** — `` `...` ``, tracking `${...}` expression depth
+
+### Comment Awareness
+
+Before processing any match, `isInsideComment()` checks if the position is inside a `//` line comment or `/* */` block comment.
+
+---
+
+## File Structure
+
+```
+react-compiler-unmemo/
+├── react-compiler-unmemo.mjs      # Entry point / runner
+├── src/
+│   ├── remove-hooks.mjs           # Core hook removal
+│   └── fix-type-annotations.mjs   # Type annotation fixer
+├── docs/
+│   ├── architecture.md            # This file
+│   └── edge-cases.md              # Known edge cases
+├── package.json
+├── .gitignore
+└── README.md
+```
+
+## Exported API
+
+Both scripts export their `run()` function for programmatic use:
+
+```javascript
+import { run as removeHooks } from "./src/remove-hooks.mjs";
+import { run as fixTypes } from "./src/fix-type-annotations.mjs";  // in react-compiler-unmemo.mjs
+
+// Remove hooks from a directory
+const result = removeHooks("/path/to/project", {
+  fileGlob: "src/**/*.{tsx,ts}",
+  dryRun: false,
+  verbose: true,
+});
+// result: { changedCount, totalTransformations, errors, remaining }
+
+// Fix type annotations
+const fixResult = fixTypes("/path/to/project", {
+  fileGlob: "src/**/*.{tsx,ts}",
+  dryRun: false,
+});
+// fixResult: { fixCount, errors }
+```
+
+## Limitations
+
+- **Does not use an AST parser** — the character-by-character approach is simpler and has no dependencies beyond `glob`, but it could theoretically be confused by extremely unusual code patterns
+- **Type inference is heuristic** — the fix-type-annotations step only handles known patterns (`ColumnsType`, `FormFieldProps`). Other lost generics need manual annotation
+- **IIFE fallback** — complex `useMemo` bodies with multiple statements become `(() => { ... })()` which works but isn't the prettiest

package/docs/edge-cases.md

@@ -0,0 +1,247 @@
+# Edge Cases & Post-Migration Fixes
+
+After running `remove-hooks.mjs`, the following edge cases required manual fixes.
+These are pre-existing type issues that were **hidden** by `useMemo`/`useCallback`'s
+looser type inference and only surfaced once the wrappers were removed.
+
+---
+
+## 1. Lost Generic Type Annotations on `columns` Arrays
+
+**Problem:** When `useMemo<ColumnsType<T>>(...)` is removed, the generic type
+annotation `ColumnsType<T>` is stripped along with it. Without the annotation,
+TypeScript infers a loose object literal type instead of `ColumnsType<T>`, causing
+type mismatches with table `onChange` handlers.
+
+**Error example:**
+```
+Type '(sorter: SorterResult<TaxArea>[] | SorterResult<TaxArea>) => void'
+is not assignable to type '(sorter: SorterResult<{ id: any; ... }>) => void'.
+```
+
+**Fix:** Add the type annotation directly to the variable:
+```typescript
+// Before (script output)
+const columns = [
+  { title: "Name", dataIndex: "name", ... },
+];
+
+// After (manual fix)
+const columns: ColumnsType<TaxArea> = [
+  { title: "Name", dataIndex: "name", ... },
+];
+```
+
+---
+
+## 2. Lost Type Annotations on `formFields` Arrays
+
+**Problem:** `FormFieldProps` has a union type for the `type` field
+(`"text" | "select" | "switch" | ...`). When `useMemo` wraps the array,
+TypeScript doesn't strictly check the object literal. Once removed,
+`type: "text"` is inferred as `string`, which doesn't satisfy the union.
+
+**Error example:**
+```
+Type 'string' is not assignable to type '"number" | "text" | "switch" | "select" | ...'
+```
+
+**Fix:** Add `FormFieldProps[]` type annotation to the `formFields` variable:
+```typescript
+// Before
+const formFields = [
+  { label: "Name", name: "name", type: "text", span: 12 },
+];
+
+// After
+const formFields: FormFieldProps[] = [
+  { label: "Name", name: "name", type: "text", span: 12 },
+];
+```
+
+---
+
+## 3. Invalid Properties on Typed Objects (Pre-existing Bugs)
+
+**Problem:** Some object literals contained properties that don't exist on
+their target type. `useMemo`'s loose inference hid these errors.
+
+### 3a. `scrollable` property on column definitions
+```typescript
+// Invalid — 'scrollable' doesn't exist on ColumnType<Manifest>
+{ title: "PO", scrollable: true, ... }
+
+// Fix: remove the invalid property
+{ title: "PO", ... }
+```
+### 3b. `sorterIndex` typo (should be `sortIndex`)
+```typescript
+// Invalid
+{ sorterIndex: "name" }
+
+// Fix
+{ sortIndex: "name" }
+```
+### 3c. `required` and `addonAfter` on `FormFieldProps`
+```typescript
+// Invalid — these properties don't exist on FormFieldProps
+{ required: false, addonAfter: <UserOutlined /> }
+
+// Fix: remove the invalid properties
+```
+
+### 3d. Method name typos exposed by stricter inference
+```typescript
+// Invalid
+form.setFieldsValues({ finalAim: newFinalAimType });
+
+// Fix
+form.setFieldsValue({ finalAim: newFinalAimType });
+```
+---
+
+## 4. Implicit `any` Parameters
+
+**Problem:** When `useCallback` wraps a function, TypeScript can sometimes
+infer parameter types from context. Once the wrapper is removed, parameters
+may lose their inferred types and become implicit `any`.
+
+**Error example:**
+```
+Parameter '_' implicitly has an 'any' type.
+```
+
+**Fix:** Add explicit type annotations to the parameters:
+```typescript
+// Before
+render: (_, record) => record.customer?.comment || "",
+
+// After
+render: (_: unknown, record: CustomerRouteFrequency) => record.customer?.comment || "",
+```
+
+---
+
+## 5. `useMemo` Returning a Value vs. Function
+
+**Problem:** The script converts `useMemo(() => expr, [deps])` to just `expr`.
+But if `expr` is an object or complex expression, the result may need parens
+to avoid parsing ambiguity.
+
+**Example:**
+```typescript
+// useMemo(() => ({ key: value }), [deps])
+// Correctly becomes:
+const obj = ({ key: value });
+
+// useMemo(() => { return entity || DEFAULT; }, [entity])
+// Correctly becomes (IIFE for complex bodies):
+const item = (() => { ... })();
+// Or for simple return:
+const item = (entity || DEFAULT);
+```
+
+The script handles both cases automatically.
+
+---
+
+## 6. Hooks with Embedded Comments (Script Limitation)
+
+**Problem:** The script's comment detection can cause it to skip hooks that contain
+`//` comments inside their body. The script sees the `//` and thinks the entire
+hook call is inside a comment.
+
+**Symptom:** The hook is left untouched after running the script, or is partially
+transformed (e.g. the wrapper is removed but the dependency array is left behind).
+
+**Example — skipped entirely:**
+```typescript
+// Script cannot process this because of the // comments inside
+const findOption = useCallback(
+  (value: number) => {
+    // No dependencies since we're using a ref
+    return optionsRef.current.find((opt) => opt.value === value);
+  },
+  [],
+);
+
+// Fix: manually remove the wrapper
+const findOption = (value: number) => {
+    // No dependencies since we're using a ref
+    return optionsRef.current.find((opt) => opt.value === value);
+  };
+```
+
+**Example — broken IIFE with leftover dependency array:**
+```typescript
+// Script partially transforms, leaving ", [deps])" behind
+const orderBy = (() => {
+    // Default ordering
+    return { name: "AscNullsLast" };
+  }, [order]);   // <-- broken: should be "})();"
+
+// Fix:
+const orderBy = (() => {
+    // Default ordering
+    return { name: "AscNullsLast" };
+  })();
+```
+
+---
+
+## 7. `as Type` Casts on Function Expressions
+
+**Problem:** When `useCallback` wraps a function that has an `as Type` cast at
+the end, removing the wrapper leaves a bare function expression with a dangling
+cast that may not parse correctly.
+
+**Example:**
+```typescript
+// Before
+const Toggle = useCallback(() => {
+  return React.createElement(Button, { onClick: handleToggle });
+}, [handleToggle]) as React.FC;
+
+// Script output (broken)
+const Toggle: React.FC = () => {
+  return React.createElement(Button, { onClick: handleToggle });
+} as React.FC;
+
+// Fix: remove the dangling cast (the variable already has the type)
+const Toggle: React.FC = () => {
+  return React.createElement(Button, { onClick: handleToggle });
+};
+```
+
+---
+
+## 8. Missing `ColumnsType` Import
+
+**Problem:** The fix-type-annotations step adds `ColumnsType<T>` annotations to
+`columns` arrays, but does not add the corresponding import. If the file didn't
+already import `ColumnsType`, you'll get a "Cannot find name" error.
+
+**Error example:**
+```
+Cannot find name 'ColumnsType'.
+```
+
+**Fix:** Add the import:
+```typescript
+import type { ColumnsType } from "antd/es/table";
+```
+
+---
+
+## Summary Checklist
+
+After running the script, run `npx tsc --noEmit` (or your build command) and check for:
+
+1. **`ColumnsType<T>` annotations** — any file that had `useMemo<ColumnsType<T>>`
+2. **Missing `ColumnsType` import** — add `import type { ColumnsType } from "antd/es/table"`
+3. **`FormFieldProps[]` annotations** — any file with `formFields` arrays
+4. **Implicit `any` errors** — render functions in column definitions
+5. **Invalid properties** — properties that were silently ignored before
+6. **Hooks with embedded comments** — may be skipped or partially transformed
+7. **Dangling `as Type` casts** — remove if the variable already has the type
+8. **Broken IIFEs** — leftover `, [deps])` instead of `)()`