@octanejs/codemod 0.0.0-stage → 0.1.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,105 @@
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`, `use-sync-external-store/shim` | `octane`, merged into one import |
25
+ | `imports` | `React.useState`, `React.FC`, and `React.ReactNode` with no import (the global namespace React's types declare) | named imports |
26
+ | `imports` | `declare module 'react' { namespace JSX { … } }` (custom elements) | `declare module 'octane/jsx-runtime'` |
27
+ | `imports` | React libraries with a binding (`@tanstack/react-query`, ...) | `@octanejs/*` |
28
+ | `imports` | `@radix-ui/react-<primitive>` (`import * as DialogPrimitive from '@radix-ui/react-dialog'`) | that primitive's namespace of `@octanejs/radix` (`import { Dialog as DialogPrimitive } from '@octanejs/radix'`) |
29
+ | `imports` | `@tanstack/react-table`, `@tanstack/react-hotkeys`, `@tanstack/react-pacer` | TanStack's own `@tanstack/octane-*` adapters, with `Octane` for `React` in type names |
30
+ | `template-component` | `function C() { …; return <div /> }` | `function C() @{ …; <div /> }` |
31
+ | `template-if` | `{a ? <A /> : <B />}`, `{a > 0 && <A />}` (also through a `const`) | `@if (a) { <A /> } @else { <B /> }` |
32
+ | `template-if` | `if (a) return <A />; …; return <B />` in a component | `@if (a) { <A /> } @else { …; <B /> }` |
33
+ | `template-for` | `{xs.map((x, i) => <li key={x.id} />)}` | `@for (const x of xs; index i; key x.id) { <li /> }` |
34
+ | `template-try` | `<Suspense fallback={f}>…</Suspense>` | `@try { … } @pending { f }` |
35
+ | `template-text` | `{title}` with `title: string`, `{count}` with `count: number` | `{title as string}`, `{String(count)}`: text bindings, not renderable holes |
36
+ | `hook-dependencies` | `useEffect(fn)` (runs every render) | `useEffect(fn, null)`: an omitted list is inferred in Octane |
37
+ | `forward-ref` | `forwardRef((props, ref) => …)` | `({ ref, ...props }) => …` |
38
+ | `descriptor-children` | a component that clones or inspects `children` (`render={children}`, `cloneElement`, `Children.only`) | `descriptorChildren(…)`, so callers pass elements as React does |
39
+ | `context-provider` | `<Ctx.Provider value>` | `<Ctx value>` |
40
+ | `context-consumer` | `<Ctx.Consumer>{(v) => …}</Ctx.Consumer>` | `@{ const v = useContext(Ctx); … }` |
41
+ | `native-text-change` | `onChange` on a text `<input>` / `<textarea>` | `onInput` (native `change` fires on blur) |
42
+ | `native-text-change` | `function Input({ ...props }) { return <input {...props} /> }` | `function Input({ onChange, ...props }) @{ <input onInput={onChange} {...props} /> }` |
43
+ | `event-object` | `e.nativeEvent`, `e.persist()`, `e.target` on a control, also through a component typed for one | `e`, removed, `e.currentTarget` |
44
+ | `class-attribute` | `className` on an HTML element | `class` |
45
+ | `legacy-root` | `ReactDOM.render(el, c)` | `createRoot(c).render(el)` |
46
+ | `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 |
47
+ | `server-render` | `renderToString(<App />)` | `renderToString(App).html`: Octane returns `{ html, css }` |
48
+ | `strict-mode` | `<StrictMode>…</StrictMode>` | its children (Octane's is a pass-through) |
49
+ | `react-compat` | `<Toaster position="top-right" />` from a React package with no Octane port | `<ReactCompat><Toaster position="top-right" /></ReactCompat>`, rendered by React |
50
+
51
+ Every rewrite keeps React's behavior. Where it cannot be proven equal, the code
52
+ is left alone: `{count && <X />}` stays a hole, because React renders `0` there
53
+ and `@if` would not. `template-text` reads types through the project's
54
+ `tsconfig.json` and runs only on TypeScript modules when that config enables
55
+ `strictNullChecks`; otherwise a `string` may hold null, which React renders as
56
+ nothing.
57
+
58
+ Some differences are reported rather than rewritten. Each `flushSync` call
59
+ keeps its React shape, but Octane's leaves the commit's `useEffect`s queued
60
+ where React runs them before returning. React Three Fiber scenes need moving
61
+ into `.three.tsrx` modules by hand.
62
+
63
+ Every module with JSX becomes `.tsrx`, entries and helpers without a component
64
+ included, so Strong mode can reach all of them; one that was JavaScript gains
65
+ `// @ts-nocheck`, so it stays as unchecked as it was. Every import of a renamed
66
+ module, dynamic imports and `index.html` entry scripts included, is updated.
67
+
68
+ ## Strong mode
69
+
70
+ With `--strong`, each template module starts with `"use strong"` and is
71
+ compiled in Strong mode. The codemod applies the compiler's own suggested fixes
72
+ (`useLazyRef` for lazily initialized refs) and the rewrites that keep React's
73
+ meaning exactly: a dependency list the compiler infers identically is dropped,
74
+ and `useState(prop)` becomes `useState(() => prop)`. A module with Strong
75
+ errors left falls back to compatibility mode, so the app still builds, and the
76
+ errors are listed as the work remaining. `--force-strong` keeps the directive
77
+ anyway.
78
+
79
+ ## What it reports
80
+
81
+ Class components, `createRef`, `defaultProps`, and anything else without an
82
+ automatic rewrite are listed under **Needs attention** with a file and line.
83
+ The process exits with status 1 when any error remains.
84
+
85
+ A React package with no Octane binding still runs on React, so React stays a
86
+ dependency, and a comment above each import of it says so. When the project
87
+ has React and React DOM 19.2 or newer in the React 19 series, a component of that package renders in
88
+ its own React root through `ReactCompat` if its element gives React nothing
89
+ Octane renders: text children and props without elements. The package's hooks
90
+ and contexts, and its components that take Octane children or render
91
+ callbacks, are reported where they are used. **No Octane port** lists each such
92
+ package with the modules that import it, the elements hosted in islands, and
93
+ the uses that need a port.
94
+
95
+ ## Options
96
+
97
+ | Flag | |
98
+ | --- | --- |
99
+ | `--strong` | Make modules Strong where the compiler accepts it |
100
+ | `--force-strong` | Keep `"use strong"` even with Strong errors left |
101
+ | `--target tsx` | Keep JSX and `.tsx`; port only the React APIs |
102
+ | `--dry-run` | Report without writing |
103
+ | `--print` | Print each migrated module (implies `--dry-run`) |
104
+ | `--no-verify` | Skip compiling the result |
105
+ | `--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.1.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.3.0",
43
+ "octane": "0.16.4",
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,135 @@
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
+ if (result.missing.length > 0) {
105
+ process.stdout.write(
106
+ `\n${colors.bold('No Octane port')} ${colors.dim('(still runs on React)')}\n`,
107
+ );
108
+ for (const { name, modules, islands, blocked } of result.missing) {
109
+ const uses = [
110
+ `${modules} module(s)`,
111
+ islands > 0 ? `${islands} element(s) in ReactCompat islands` : null,
112
+ blocked > 0 ? colors.red(`${blocked} use(s) need a port`) : null,
113
+ ].filter(Boolean);
114
+ process.stdout.write(` ${name} ${colors.dim(uses.join(', '))}\n`);
115
+ }
116
+ }
117
+ for (const page of result.html) process.stdout.write(`\nUpdated the entry script in ${page}\n`);
118
+
119
+ const strong = changed.filter((file) => file.strong !== null);
120
+ const summary = [
121
+ `${changed.length} module(s) migrated`,
122
+ `${changed.filter((file) => file.output !== file.file).length} renamed to .tsrx`,
123
+ strong.length > 0
124
+ ? `${strong.filter((file) => file.strong).length}/${strong.length} Strong`
125
+ : null,
126
+ `${errors.length} error(s)`,
127
+ ].filter(Boolean);
128
+ process.stdout.write(`\n${summary.join(', ')}${dryRun ? colors.dim(' (dry run)') : ''}\n`);
129
+ if (changed.length > 0 && !dryRun) {
130
+ const root = path.relative(process.cwd(), result.root) || '.';
131
+ process.stdout.write(
132
+ colors.dim(`Next: run \`npx @octanejs/cli init\` in ${root} to wire Octane into the build.\n`),
133
+ );
134
+ }
135
+ 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,91 @@
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
+ unported?(specifier: string): string | null;
17
+ reactCompat?: boolean;
18
+ }
19
+ /** A React package with no Octane port, and how migrated code uses it. */
20
+ interface Unported {
21
+ name: string;
22
+ /** Elements now rendered in a `ReactCompat` island. */
23
+ islands: number;
24
+ /** Uses that only a port can support. */
25
+ blocked: number;
26
+ }
27
+ interface TransformResult {
28
+ code: string;
29
+ changed: boolean;
30
+ template: boolean;
31
+ notes: Note[];
32
+ rules: Record<string, number>;
33
+ exports: {
34
+ contexts: string[];
35
+ reexports: { specifier: string; names: [string, string][] | null }[];
36
+ };
37
+ unported: Unported[];
38
+ }
39
+ interface CodemodOptions {
40
+ target?: 'tsrx' | 'tsx';
41
+ strong?: boolean;
42
+ forceStrong?: boolean;
43
+ verify?: boolean;
44
+ write?: boolean;
45
+ root?: string;
46
+ }
47
+ interface Finding {
48
+ code: string;
49
+ severity: string;
50
+ message: string;
51
+ line: number;
52
+ }
53
+ interface Compiler {
54
+ from: string;
55
+ collectDiagnostics: typeof import('octane/compiler').collectDiagnostics;
56
+ }
57
+ interface FileResult {
58
+ file: string;
59
+ output: string;
60
+ changed: boolean;
61
+ rules: Record<string, number>;
62
+ notes: Note[];
63
+ strong: boolean | null;
64
+ strongFixes: string[];
65
+ diagnostics: Finding[];
66
+ code: string;
67
+ }
68
+ interface CodemodResult {
69
+ root: string;
70
+ files: FileResult[];
71
+ packages: { from: string; to: string }[];
72
+ missing: (Unported & { modules: number })[];
73
+ html: string[];
74
+ compiler: string | null;
75
+ }
76
+ export declare function runCodemod(
77
+ paths: string[],
78
+ options?: CodemodOptions,
79
+ ): Promise<CodemodResult>;
80
+ export declare function transformModule(
81
+ source: string,
82
+ filename: string,
83
+ options?: TransformOptions,
84
+ ): TransformResult;
85
+ export declare function strengthen(
86
+ compiler: Compiler,
87
+ code: string,
88
+ filename: string,
89
+ options?: { force?: boolean },
90
+ ): { code: string; strong: boolean; fixed: string[]; blockers: Finding[] };
91
+ 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';