@octanejs/codemod 0.0.0-stage → 0.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Dominic Gannaway
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,89 @@
1
- # Temporary Holding Version
1
+ # @octanejs/codemod
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ Migrate a React codebase to Octane. `octane-codemod` rewrites React + TSX/JSX
4
+ modules as Octane + TSRX, and can take each module on to Strong mode where the
5
+ compiler accepts it.
6
+
7
+ ```bash
8
+ npx @octanejs/codemod src # migrate in place
9
+ npx @octanejs/codemod src --dry-run # report only
10
+ npx @octanejs/codemod src --strong # also make modules Strong where possible
11
+ ```
12
+
13
+ Then run `npx @octanejs/cli init` to swap the bundler plugin, `tsconfig`, and
14
+ dependencies over to Octane.
15
+
16
+ > **Prototype.** The rewrites below are tested, and every migrated module is
17
+ > compiled by the Octane compiler before it is written, but the rule set is
18
+ > still growing. Review the diff, and read the **Needs attention** list.
19
+
20
+ ## What it rewrites
21
+
22
+ | Rule | React | Octane |
23
+ | --- | --- | --- |
24
+ | `imports` | `react`, `react-dom`, `react-dom/client` | `octane`, merged into one import |
25
+ | `imports` | `React.useState`, `React.FC` | named imports |
26
+ | `imports` | React libraries with a binding (`@tanstack/react-query`, ...) | `@octanejs/*` |
27
+ | `template-component` | `function C() { …; return <div /> }` | `function C() @{ …; <div /> }` |
28
+ | `template-if` | `{a ? <A /> : <B />}`, `{a > 0 && <A />}` (also through a `const`) | `@if (a) { <A /> } @else { <B /> }` |
29
+ | `template-if` | `if (a) return <A />; …; return <B />` in a component | `@if (a) { <A /> } @else { …; <B /> }` |
30
+ | `template-for` | `{xs.map((x, i) => <li key={x.id} />)}` | `@for (const x of xs; index i; key x.id) { <li /> }` |
31
+ | `template-try` | `<Suspense fallback={f}>…</Suspense>` | `@try { … } @pending { f }` |
32
+ | `template-text` | `{title}` with `title: string`, `{count}` with `count: number` | `{title as string}`, `{String(count)}`: text bindings, not renderable holes |
33
+ | `hook-dependencies` | `useEffect(fn)` (runs every render) | `useEffect(fn, null)`: an omitted list is inferred in Octane |
34
+ | `forward-ref` | `forwardRef((props, ref) => …)` | `({ ref, ...props }) => …` |
35
+ | `context-provider` | `<Ctx.Provider value>` | `<Ctx value>` |
36
+ | `context-consumer` | `<Ctx.Consumer>{(v) => …}</Ctx.Consumer>` | `@{ const v = useContext(Ctx); … }` |
37
+ | `native-text-change` | `onChange` on a text `<input>` / `<textarea>` | `onInput` (native `change` fires on blur) |
38
+ | `event-object` | `e.nativeEvent`, `e.persist()`, `e.target` on a control | `e`, removed, `e.currentTarget` |
39
+ | `class-attribute` | `className` on an HTML element | `class` |
40
+ | `legacy-root` | `ReactDOM.render(el, c)` | `createRoot(c).render(el)` |
41
+ | `root-render` | `root.render(<App a={1} />)`, `hydrateRoot(c, createElement(App, p))` | `root.render(App, { a: 1 })`, `hydrateRoot(c, App, p)`: no generic element renderer |
42
+ | `server-render` | `renderToString(<App />)` | `renderToString(App).html`: Octane returns `{ html, css }` |
43
+ | `strict-mode` | `<StrictMode>…</StrictMode>` | its children (Octane's is a pass-through) |
44
+
45
+ Every rewrite keeps React's behavior. Where it cannot be proven equal, the code
46
+ is left alone: `{count && <X />}` stays a hole, because React renders `0` there
47
+ and `@if` would not. `template-text` reads types through the project's
48
+ `tsconfig.json` and runs only on TypeScript modules when that config enables
49
+ `strictNullChecks`; otherwise a `string` may hold null, which React renders as
50
+ nothing.
51
+
52
+ Some differences are reported rather than rewritten. Each `flushSync` call
53
+ keeps its React shape, but Octane's leaves the commit's `useEffect`s queued
54
+ where React runs them before returning. React Three Fiber scenes need moving
55
+ into `.three.tsrx` modules by hand.
56
+
57
+ Every module with JSX becomes `.tsrx`, entries and helpers without a component
58
+ included, so Strong mode can reach all of them; one that was JavaScript gains
59
+ `// @ts-nocheck`, so it stays as unchecked as it was. Every import of a renamed
60
+ module, dynamic imports and `index.html` entry scripts included, is updated.
61
+
62
+ ## Strong mode
63
+
64
+ With `--strong`, each template module starts with `"use strong"` and is
65
+ compiled in Strong mode. The codemod applies the compiler's own suggested fixes
66
+ (`useLazyRef` for lazily initialized refs) and the rewrites that keep React's
67
+ meaning exactly: a dependency list the compiler infers identically is dropped,
68
+ and `useState(prop)` becomes `useState(() => prop)`. A module with Strong
69
+ errors left falls back to compatibility mode, so the app still builds, and the
70
+ errors are listed as the work remaining. `--force-strong` keeps the directive
71
+ anyway.
72
+
73
+ ## What it reports
74
+
75
+ Class components, `createRef`, `defaultProps`, unported React libraries, and
76
+ anything else without an automatic rewrite are listed under **Needs attention**
77
+ with a file and line. The process exits with status 1 when any error remains.
78
+
79
+ ## Options
80
+
81
+ | Flag | |
82
+ | --- | --- |
83
+ | `--strong` | Make modules Strong where the compiler accepts it |
84
+ | `--force-strong` | Keep `"use strong"` even with Strong errors left |
85
+ | `--target tsx` | Keep JSX and `.tsx`; port only the React APIs |
86
+ | `--dry-run` | Report without writing |
87
+ | `--print` | Print each migrated module (implies `--dry-run`) |
88
+ | `--no-verify` | Skip compiling the result |
89
+ | `--json` | Machine-readable result |
package/package.json CHANGED
@@ -1,6 +1,53 @@
1
1
  {
2
2
  "name": "@octanejs/codemod",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
3
+ "version": "0.0.0",
4
+ "type": "module",
5
+ "engines": {
6
+ "node": ">=22.22.2"
7
+ },
8
+ "description": "Migrate a React codebase to Octane: rewrite React + TSX/JSX modules as Octane + TSRX, optionally in Strong mode.",
9
+ "license": "MIT",
10
+ "author": {
11
+ "name": "Dominic Gannaway",
12
+ "email": "dg@domgan.com"
13
+ },
14
+ "repository": {
15
+ "type": "git",
16
+ "url": "git+https://github.com/octanejs/octane.git",
17
+ "directory": "packages/codemod"
18
+ },
19
+ "publishConfig": {
20
+ "access": "public"
21
+ },
22
+ "keywords": [
23
+ "octane",
24
+ "codemod",
25
+ "migration",
26
+ "react",
27
+ "tsrx"
28
+ ],
29
+ "files": [
30
+ "src",
31
+ "README.md",
32
+ "LICENSE"
33
+ ],
34
+ "bin": {
35
+ "octane-codemod": "src/bin.js"
36
+ },
37
+ "exports": {
38
+ ".": "./src/index.js",
39
+ "./package.json": "./package.json"
40
+ },
41
+ "dependencies": {
42
+ "@octanejs/cli": "0.2.4",
43
+ "octane": "0.16.3",
44
+ "picocolors": "^1.1.1",
45
+ "typescript": "^5.9.3"
46
+ },
47
+ "devDependencies": {
48
+ "vitest": "^4.1.10"
49
+ },
50
+ "scripts": {
51
+ "test": "cd ../.. && vitest run --project codemod"
52
+ }
6
53
  }
package/src/bin.js ADDED
@@ -0,0 +1,122 @@
1
+ #!/usr/bin/env node
2
+ import path from 'node:path';
3
+ import { parseArgs } from 'node:util';
4
+ import colors from 'picocolors';
5
+ import { runCodemod } from './project.js';
6
+
7
+ const HELP = `octane-codemod — migrate React + TSX/JSX to Octane + TSRX
8
+
9
+ Usage: octane-codemod [paths...] [options]
10
+
11
+ paths files or directories to migrate (default: .)
12
+
13
+ Options:
14
+ --strong make each migrated module Strong where the compiler
15
+ accepts it; the rest stay in compatibility mode
16
+ --force-strong keep "use strong" even where Strong errors remain
17
+ --target <tsrx|tsx> tsrx (default) rewrites components as templates;
18
+ tsx keeps JSX and only ports the React APIs
19
+ --dry-run report without writing
20
+ --print print each migrated module (implies --dry-run)
21
+ --no-verify skip compiling the result
22
+ --json print the result as JSON
23
+ -h, --help show this help
24
+ `;
25
+
26
+ const { values, positionals } = parseArgs({
27
+ allowPositionals: true,
28
+ allowNegative: true,
29
+ options: {
30
+ strong: { type: 'boolean', default: false },
31
+ 'force-strong': { type: 'boolean', default: false },
32
+ target: { type: 'string', default: 'tsrx' },
33
+ 'dry-run': { type: 'boolean', default: false },
34
+ print: { type: 'boolean', default: false },
35
+ verify: { type: 'boolean', default: true },
36
+ json: { type: 'boolean', default: false },
37
+ help: { type: 'boolean', short: 'h', default: false },
38
+ },
39
+ });
40
+
41
+ if (values.help) {
42
+ process.stdout.write(HELP);
43
+ process.exit(0);
44
+ }
45
+ if (values.target !== 'tsrx' && values.target !== 'tsx') {
46
+ process.stderr.write(`--target must be tsrx or tsx, got "${values.target}".\n`);
47
+ process.exit(2);
48
+ }
49
+
50
+ const dryRun = values['dry-run'] || values.print;
51
+ const result = await runCodemod(positionals.length > 0 ? positionals : ['.'], {
52
+ target: /** @type {'tsrx' | 'tsx'} */ (values.target),
53
+ strong: values.strong || values['force-strong'],
54
+ forceStrong: values['force-strong'],
55
+ verify: values.verify,
56
+ write: !dryRun,
57
+ });
58
+
59
+ // The codemod's own notes, at the original file's lines, and the compiler's
60
+ // diagnostics, at the written file's, as one list.
61
+ const findings = result.files.flatMap((file) => [
62
+ ...file.notes
63
+ .filter((note) => note.severity !== 'info')
64
+ .map((note) => ({ file: file.file, ...note, code: note.rule })),
65
+ ...file.diagnostics.map((diagnostic) => ({ file: file.output, ...diagnostic })),
66
+ ]);
67
+ const errors = findings.filter((finding) => finding.severity === 'error');
68
+
69
+ if (values.json) {
70
+ const files = result.files.map(({ code, ...file }) => (values.print ? { ...file, code } : file));
71
+ process.stdout.write(JSON.stringify({ ...result, files }, null, 2) + '\n');
72
+ process.exit(errors.length > 0 ? 1 : 0);
73
+ }
74
+
75
+ const changed = result.files.filter((file) => file.changed);
76
+ for (const file of changed) {
77
+ const arrow = file.output === file.file ? '' : ` → ${file.output}`;
78
+ const rules = Object.entries(file.rules)
79
+ .map(([rule, count]) => (count > 1 ? `${rule}×${count}` : rule))
80
+ .join(', ');
81
+ const mode =
82
+ file.strong === null ? '' : file.strong ? colors.green(' strong') : colors.yellow(' compat');
83
+ const mark = errors.some((error) => error.file === file.output)
84
+ ? colors.red('✗')
85
+ : colors.green('✓');
86
+ process.stdout.write(`${mark} ${file.file}${arrow}${mode} ${colors.dim(rules)}\n`);
87
+ if (values.print) process.stdout.write(colors.dim('─'.repeat(60)) + '\n' + file.code + '\n');
88
+ }
89
+
90
+ if (findings.length > 0) {
91
+ process.stdout.write(`\n${colors.bold('Needs attention')}\n`);
92
+ for (const finding of findings) {
93
+ const tag = finding.severity === 'error' ? colors.red : colors.yellow;
94
+ const message = finding.message.split('\n')[0];
95
+ process.stdout.write(
96
+ ` ${finding.file}:${finding.line} ${tag(finding.severity)} ${colors.dim(finding.code)} ${message}\n`,
97
+ );
98
+ }
99
+ }
100
+ if (result.packages.length > 0) {
101
+ process.stdout.write(`\n${colors.bold('Dependencies')}\n`);
102
+ for (const { from, to } of result.packages) process.stdout.write(` ${from} → ${to}\n`);
103
+ }
104
+ for (const page of result.html) process.stdout.write(`\nUpdated the entry script in ${page}\n`);
105
+
106
+ const strong = changed.filter((file) => file.strong !== null);
107
+ const summary = [
108
+ `${changed.length} module(s) migrated`,
109
+ `${changed.filter((file) => file.output !== file.file).length} renamed to .tsrx`,
110
+ strong.length > 0
111
+ ? `${strong.filter((file) => file.strong).length}/${strong.length} Strong`
112
+ : null,
113
+ `${errors.length} error(s)`,
114
+ ].filter(Boolean);
115
+ process.stdout.write(`\n${summary.join(', ')}${dryRun ? colors.dim(' (dry run)') : ''}\n`);
116
+ if (changed.length > 0 && !dryRun) {
117
+ const root = path.relative(process.cwd(), result.root) || '.';
118
+ process.stdout.write(
119
+ colors.dim(`Next: run \`npx @octanejs/cli init\` in ${root} to wire Octane into the build.\n`),
120
+ );
121
+ }
122
+ process.exit(errors.length > 0 ? 1 : 0);
@@ -0,0 +1,61 @@
1
+ import { createRequire } from 'node:module';
2
+ import path from 'node:path';
3
+ import { pathToFileURL } from 'node:url';
4
+
5
+ /**
6
+ * @typedef {{ code: string, severity: string, message: string, line: number }} Finding
7
+ *
8
+ * @typedef {Object} Compiler
9
+ * @property {(source: string, filename: string, options?: object) => { diagnostics: any[], error: unknown }} collectDiagnostics
10
+ * @property {string} from where the compiler was loaded
11
+ */
12
+
13
+ /**
14
+ * The Octane compiler that judges the migrated code: the project's own when it
15
+ * has one, so the result matches what its build will do, else the copy this
16
+ * package ships with, since a React project has no Octane installed yet.
17
+ *
18
+ * @param {string} root
19
+ * @returns {Promise<Compiler>}
20
+ */
21
+ export async function loadCompiler(root) {
22
+ for (const base of [path.join(root, 'noop.js'), import.meta.url]) {
23
+ let entry;
24
+ try {
25
+ entry = createRequire(base).resolve('octane/compiler');
26
+ } catch {
27
+ continue;
28
+ }
29
+ const module = await import(pathToFileURL(entry).href);
30
+ if (typeof module.collectDiagnostics === 'function') {
31
+ return { collectDiagnostics: module.collectDiagnostics, from: entry };
32
+ }
33
+ }
34
+ throw new Error('Could not load `octane/compiler`.');
35
+ }
36
+
37
+ /**
38
+ * @param {any} diagnostic a compiler diagnostic
39
+ * @returns {Finding}
40
+ */
41
+ export function finding(diagnostic) {
42
+ return {
43
+ code: diagnostic.code,
44
+ severity: diagnostic.severity,
45
+ message: String(diagnostic.message).replace(`[${diagnostic.code}] `, ''),
46
+ line: diagnostic.start?.line ?? 1,
47
+ };
48
+ }
49
+
50
+ /**
51
+ * @param {any} error what the compiler threw for a module it could not parse
52
+ * @returns {Finding}
53
+ */
54
+ export function thrown(error) {
55
+ return {
56
+ code: 'COMPILE_ERROR',
57
+ severity: 'error',
58
+ message: String(error?.message ?? error),
59
+ line: error?.loc?.line ?? 1,
60
+ };
61
+ }
package/src/index.d.ts ADDED
@@ -0,0 +1,80 @@
1
+ import type ts from 'typescript';
2
+
3
+ interface Note {
4
+ rule: string;
5
+ severity: 'info' | 'warning' | 'error';
6
+ line: number;
7
+ message: string;
8
+ }
9
+ interface TransformOptions {
10
+ target?: 'tsx' | 'tsrx';
11
+ strong?: boolean;
12
+ strictNullChecks?: boolean;
13
+ types?: { sourceFile: ts.SourceFile; checker: ts.TypeChecker };
14
+ resolveSpecifier?(specifier: string): string | null;
15
+ isContext?(specifier: string, name: string): boolean | null;
16
+ }
17
+ interface TransformResult {
18
+ code: string;
19
+ changed: boolean;
20
+ template: boolean;
21
+ notes: Note[];
22
+ rules: Record<string, number>;
23
+ exports: {
24
+ contexts: string[];
25
+ reexports: { specifier: string; names: [string, string][] | null }[];
26
+ };
27
+ }
28
+ interface CodemodOptions {
29
+ target?: 'tsrx' | 'tsx';
30
+ strong?: boolean;
31
+ forceStrong?: boolean;
32
+ verify?: boolean;
33
+ write?: boolean;
34
+ root?: string;
35
+ }
36
+ interface Finding {
37
+ code: string;
38
+ severity: string;
39
+ message: string;
40
+ line: number;
41
+ }
42
+ interface Compiler {
43
+ from: string;
44
+ collectDiagnostics: typeof import('octane/compiler').collectDiagnostics;
45
+ }
46
+ interface FileResult {
47
+ file: string;
48
+ output: string;
49
+ changed: boolean;
50
+ rules: Record<string, number>;
51
+ notes: Note[];
52
+ strong: boolean | null;
53
+ strongFixes: string[];
54
+ diagnostics: Finding[];
55
+ code: string;
56
+ }
57
+ interface CodemodResult {
58
+ root: string;
59
+ files: FileResult[];
60
+ packages: { from: string; to: string }[];
61
+ missing: string[];
62
+ html: string[];
63
+ compiler: string | null;
64
+ }
65
+ export declare function runCodemod(
66
+ paths: string[],
67
+ options?: CodemodOptions,
68
+ ): Promise<CodemodResult>;
69
+ export declare function transformModule(
70
+ source: string,
71
+ filename: string,
72
+ options?: TransformOptions,
73
+ ): TransformResult;
74
+ export declare function strengthen(
75
+ compiler: Compiler,
76
+ code: string,
77
+ filename: string,
78
+ options?: { force?: boolean },
79
+ ): { code: string; strong: boolean; fixed: string[]; blockers: Finding[] };
80
+ export declare function loadCompiler(root: string): Promise<Compiler>;
package/src/index.js ADDED
@@ -0,0 +1,4 @@
1
+ export { transformModule } from './transform.js';
2
+ export { runCodemod } from './project.js';
3
+ export { strengthen } from './strong.js';
4
+ export { loadCompiler } from './compiler.js';
@@ -0,0 +1,235 @@
1
+ /**
2
+ * What each React module name means in Octane.
3
+ *
4
+ * Values and types are listed separately because Octane exports React's type
5
+ * names as migration aliases (`ReactNode`, `ChangeEvent`, `FC`, ...), while
6
+ * several React values have no Octane counterpart at all and need a rewrite or a
7
+ * person (`forwardRef`, class components, `createRef`).
8
+ */
9
+
10
+ /** React value exports that exist in `octane` under the same name. */
11
+ const OCTANE_VALUES = new Set([
12
+ 'Activity',
13
+ 'Children',
14
+ 'Fragment',
15
+ 'StrictMode',
16
+ 'Suspense',
17
+ 'ViewTransition',
18
+ 'act',
19
+ 'addTransitionType',
20
+ 'cloneElement',
21
+ 'createContext',
22
+ 'createElement',
23
+ 'createPortal',
24
+ 'createRoot',
25
+ 'flushSync',
26
+ 'hydrateRoot',
27
+ 'isValidElement',
28
+ 'lazy',
29
+ 'memo',
30
+ 'preconnect',
31
+ 'prefetchDNS',
32
+ 'preinit',
33
+ 'preinitModule',
34
+ 'preload',
35
+ 'preloadModule',
36
+ 'requestFormReset',
37
+ 'startTransition',
38
+ 'unstable_Activity',
39
+ 'unstable_ViewTransition',
40
+ 'unstable_addTransitionType',
41
+ 'unstable_batchedUpdates',
42
+ 'use',
43
+ 'useActionState',
44
+ 'useCallback',
45
+ 'useContext',
46
+ 'useDebugValue',
47
+ 'useDeferredValue',
48
+ 'useEffect',
49
+ 'useEffectEvent',
50
+ 'useFormState',
51
+ 'useFormStatus',
52
+ 'useId',
53
+ 'useImperativeHandle',
54
+ 'useInsertionEffect',
55
+ 'useLayoutEffect',
56
+ 'useMemo',
57
+ 'useOptimistic',
58
+ 'useReducer',
59
+ 'useRef',
60
+ 'useState',
61
+ 'useSyncExternalStore',
62
+ 'useTransition',
63
+ 'version',
64
+ ]);
65
+
66
+ /** `react-dom/server` names served by `octane/server`. */
67
+ const OCTANE_SERVER_VALUES = new Set([
68
+ 'renderToPipeableStream',
69
+ 'renderToReadableStream',
70
+ 'renderToStaticMarkup',
71
+ 'renderToString',
72
+ ]);
73
+
74
+ /** React type names `octane` exports as-is. */
75
+ const OCTANE_TYPES = new Set(
76
+ (
77
+ 'AllHTMLAttributes AnchorHTMLAttributes AnimationEvent AnimationEventHandler AreaHTMLAttributes ' +
78
+ 'AriaAttributes AriaRole Attributes AudioHTMLAttributes BaseHTMLAttributes BlockquoteHTMLAttributes ' +
79
+ 'Booleanish ButtonHTMLAttributes CSSProperties CanvasHTMLAttributes ChangeEvent ChangeEventHandler ' +
80
+ 'ClipboardEvent ClipboardEventHandler ColHTMLAttributes ColgroupHTMLAttributes ComponentProps ' +
81
+ 'ComponentPropsWithRef ComponentPropsWithoutRef ComponentRef ComponentType CompositionEvent ' +
82
+ 'CompositionEventHandler Context ContextType CrossOrigin CustomComponentPropsWithRef DOMAttributes ' +
83
+ 'DOMElement DataHTMLAttributes DelHTMLAttributes DependencyList Destructor DetailedHTMLProps ' +
84
+ 'DetailedReactHTMLElement DetailsHTMLAttributes DialogHTMLAttributes Dispatch DispatchWithoutAction ' +
85
+ 'DragEvent DragEventHandler EffectCallback ElementRef ElementType EmbedHTMLAttributes EventHandler ' +
86
+ 'ExoticComponent FC FieldsetHTMLAttributes FocusEvent FocusEventHandler FormEvent FormEventHandler ' +
87
+ 'FormHTMLAttributes FunctionComponent FunctionComponentElement HTMLAttributeAnchorTarget ' +
88
+ 'HTMLAttributeReferrerPolicy HTMLAttributes HTMLInputTypeAttribute HTMLProps HtmlHTMLAttributes ' +
89
+ 'IframeHTMLAttributes ImgHTMLAttributes InputEvent InputEventHandler InputHTMLAttributes ' +
90
+ 'InsHTMLAttributes InvalidEvent InvalidEventHandler JSX JSXElementConstructor Key KeyboardEvent ' +
91
+ 'KeyboardEventHandler KeygenHTMLAttributes LabelHTMLAttributes LazyExoticComponent LiHTMLAttributes ' +
92
+ 'LinkHTMLAttributes MapHTMLAttributes MemoExoticComponent MenuHTMLAttributes MetaHTMLAttributes ' +
93
+ 'MeterHTMLAttributes MouseEvent MouseEventHandler MutableRefObject NamedExoticComponent ' +
94
+ 'ObjectHTMLAttributes OlHTMLAttributes OptgroupHTMLAttributes OptionHTMLAttributes ' +
95
+ 'OutputHTMLAttributes ParamHTMLAttributes PointerEvent PointerEventHandler ProgressHTMLAttributes ' +
96
+ 'PropsWithChildren PropsWithRef PropsWithoutRef Provider ProviderProps QuoteHTMLAttributes ' +
97
+ 'ReactElement ReactHTMLElement ReactNode ReactPortal ReactSVGElement Reducer ReducerAction ' +
98
+ 'ReducerState ReducerStateWithoutAction ReducerWithoutAction Ref RefAttributes RefCallback RefObject ' +
99
+ 'SVGAttributes SVGLineElementAttributes SVGProps SVGTextElementAttributes ScriptHTMLAttributes ' +
100
+ 'SelectHTMLAttributes SetStateAction SlotHTMLAttributes SourceHTMLAttributes StrictModeProps ' +
101
+ 'StyleHTMLAttributes SuspenseProps TableHTMLAttributes TdHTMLAttributes TextareaHTMLAttributes ' +
102
+ 'ThHTMLAttributes TimeHTMLAttributes ToggleEvent ToggleEventHandler TouchEvent TouchEventHandler ' +
103
+ 'TrackHTMLAttributes TransitionEvent TransitionEventHandler UIEvent UIEventHandler ' +
104
+ 'VideoHTMLAttributes WebViewHTMLAttributes WheelEvent WheelEventHandler'
105
+ ).split(' '),
106
+ );
107
+
108
+ /**
109
+ * React type names with an Octane spelling of their own. `ReactNode` keeps its
110
+ * alias when imported by name, so only namespace-qualified uses change; the
111
+ * rest have no alias in Octane.
112
+ *
113
+ * @type {Record<string, string>}
114
+ */
115
+ const RENAMED_TYPES = {
116
+ BaseSyntheticEvent: 'NativeEvent',
117
+ ForwardRefExoticComponent: 'FC',
118
+ ForwardedRef: 'Ref',
119
+ LegacyRef: 'Ref',
120
+ ReactChild: 'OctaneNode',
121
+ ReactFragment: 'OctaneNode',
122
+ ReactText: 'OctaneNode',
123
+ SyntheticEvent: 'NativeEvent',
124
+ };
125
+
126
+ /** Namespace-qualified spellings that read better as Octane's own name. *
127
+ * @type {Record<string, string>}
128
+ */
129
+ const QUALIFIED_TYPE_PREFERENCES = {
130
+ ReactElement: 'OctaneElement',
131
+ ReactNode: 'OctaneNode',
132
+ };
133
+
134
+ /** Modules whose imports this codemod owns, and the Octane module each becomes. *
135
+ * @type {Record<string, string>}
136
+ */
137
+ export const REACT_MODULES = {
138
+ react: 'octane',
139
+ 'react-dom': 'octane',
140
+ 'react-dom/client': 'octane',
141
+ 'react-dom/server': 'octane/server',
142
+ 'react-dom/server.browser': 'octane/server',
143
+ 'react-dom/server.bun': 'octane/server',
144
+ 'react-dom/server.edge': 'octane/server',
145
+ 'react-dom/server.node': 'octane/server',
146
+ 'react-dom/test-utils': 'octane',
147
+ 'react/jsx-runtime': 'octane/jsx-runtime',
148
+ 'react/jsx-dev-runtime': 'octane/jsx-dev-runtime',
149
+ };
150
+
151
+ /**
152
+ * React framework packages an Octane framework integration serves. They are
153
+ * not bindings, so the shared binding catalog leaves them out.
154
+ */
155
+ export const FRAMEWORK_PACKAGES = /** @type {Record<string, string>} */ ({
156
+ '@tanstack/react-start': '@octanejs/tanstack-start',
157
+ });
158
+
159
+ /**
160
+ * React values with no Octane export, each with what to do instead. A value
161
+ * listed here is never imported from Octane; the codemod either rewrites its
162
+ * uses or reports them.
163
+ *
164
+ * @type {Record<string, string>}
165
+ */
166
+ export const UNSUPPORTED_VALUES = {
167
+ Component: 'Class components are not supported. Convert it to a function component.',
168
+ PureComponent:
169
+ 'Class components are not supported. Convert it to a function component with `memo`.',
170
+ Profiler: 'Octane has no `Profiler`; use the Octane devtools profiler.',
171
+ SuspenseList: 'Octane has no `SuspenseList`.',
172
+ cache: 'Server Components are not supported, so `cache` has no Octane equivalent.',
173
+ cacheSignal: 'Server Components are not supported, so `cacheSignal` has no Octane equivalent.',
174
+ captureOwnerStack: 'Octane does not collect owner stacks.',
175
+ createRef:
176
+ 'Octane has no `createRef`; use `useRef` in a function component or a `{ current: null }` object.',
177
+ findDOMNode: 'Octane has no `findDOMNode`; pass a ref to the host element.',
178
+ forwardRef: 'Refs are props in Octane; the codemod unwraps `forwardRef` where it can.',
179
+ hydrate: 'Legacy roots are not supported; the codemod rewrites calls to `hydrateRoot`.',
180
+ render: 'Legacy roots are not supported; the codemod rewrites calls to `createRoot(...).render`.',
181
+ unmountComponentAtNode:
182
+ 'Legacy roots are not supported; keep the `createRoot` result and call `root.unmount()`.',
183
+ };
184
+
185
+ /**
186
+ * @param {string} module a key of {@link REACT_MODULES}
187
+ * @param {string} name the imported name
188
+ * @param {boolean} typeOnly
189
+ * @returns {{ module: string, name: string } | null} null when Octane has no
190
+ * such export
191
+ */
192
+ export function mapReactImport(module, name, typeOnly) {
193
+ if (module === 'react-dom/server' || module.startsWith('react-dom/server.')) {
194
+ return OCTANE_SERVER_VALUES.has(name) ? { module: 'octane/server', name } : null;
195
+ }
196
+ if (!typeOnly && OCTANE_VALUES.has(name)) return { module: 'octane', name };
197
+ if (OCTANE_TYPES.has(name)) return { module: 'octane', name };
198
+ if (name in RENAMED_TYPES) return { module: 'octane', name: RENAMED_TYPES[name] };
199
+ return null;
200
+ }
201
+
202
+ /**
203
+ * The Octane name for `React.<name>` in a type position.
204
+ *
205
+ * @param {string} name
206
+ * @returns {string | null}
207
+ */
208
+ export function mapQualifiedType(name) {
209
+ if (name in QUALIFIED_TYPE_PREFERENCES) return QUALIFIED_TYPE_PREFERENCES[name];
210
+ if (OCTANE_TYPES.has(name)) return name;
211
+ return RENAMED_TYPES[name] ?? null;
212
+ }
213
+
214
+ /** Built-in hooks whose omitted dependency list Octane infers. *
215
+ * @type {Record<string, number>}
216
+ */
217
+ export const DEPENDENCY_HOOKS = {
218
+ useCallback: 1,
219
+ useEffect: 1,
220
+ useImperativeHandle: 2,
221
+ useInsertionEffect: 1,
222
+ useLayoutEffect: 1,
223
+ useMemo: 1,
224
+ };
225
+
226
+ /** `<input type>` values whose native `change` fires on commit, not per edit. */
227
+ export const TEXT_INPUT_TYPES = new Set([
228
+ 'text',
229
+ 'search',
230
+ 'url',
231
+ 'tel',
232
+ 'password',
233
+ 'email',
234
+ 'number',
235
+ ]);