@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 +21 -0
- package/README.md +88 -2
- package/package.json +50 -3
- package/src/bin.js +122 -0
- package/src/compiler.js +61 -0
- package/src/index.d.ts +80 -0
- package/src/index.js +4 -0
- package/src/mappings.js +235 -0
- package/src/project.js +515 -0
- package/src/strong.js +149 -0
- package/src/transform.js +2568 -0
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
|
-
#
|
|
1
|
+
# @octanejs/codemod
|
|
2
2
|
|
|
3
|
-
|
|
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
|
|
4
|
-
"
|
|
5
|
-
"
|
|
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);
|
package/src/compiler.js
ADDED
|
@@ -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
package/src/mappings.js
ADDED
|
@@ -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
|
+
]);
|