codemod 1.18.7 → 2.0.0-alpha.2

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.
Files changed (89) hide show
  1. package/README.md +57 -2
  2. package/codemod +17 -30
  3. package/package.json +78 -10
  4. package/register.d.mts +11 -0
  5. package/register.mjs +60 -0
  6. package/runtime/addon.mjs +59 -0
  7. package/runtime/ast-grep.mjs +93 -0
  8. package/runtime/context.mjs +77 -0
  9. package/runtime/hooks.mjs +9 -0
  10. package/runtime/host.d.mts +120 -0
  11. package/runtime/host.mjs +390 -0
  12. package/runtime/llm.mjs +11 -0
  13. package/runtime/metrics.mjs +45 -0
  14. package/runtime/modules.mjs +19 -0
  15. package/runtime/orchestrator.mjs +657 -0
  16. package/runtime/runtime.mjs +48 -0
  17. package/runtime/workflow.mjs +135 -0
  18. package/testing/index.d.mts +203 -0
  19. package/testing/index.mjs +638 -0
  20. package/types/index.d.ts +8 -0
  21. package/types/langs/angular.d.ts +5 -0
  22. package/types/langs/c.d.ts +5 -0
  23. package/types/langs/c_sharp.d.ts +5 -0
  24. package/types/langs/cpp.d.ts +5 -0
  25. package/types/langs/css.d.ts +5 -0
  26. package/types/langs/elixir.d.ts +5 -0
  27. package/types/langs/go.d.ts +5 -0
  28. package/types/langs/html.d.ts +5 -0
  29. package/types/langs/java.d.ts +5 -0
  30. package/types/langs/javascript.d.ts +5 -0
  31. package/types/langs/json.d.ts +5 -0
  32. package/types/langs/kotlin.d.ts +5 -0
  33. package/types/langs/php.d.ts +5 -0
  34. package/types/langs/python.d.ts +5 -0
  35. package/types/langs/ruby.d.ts +5 -0
  36. package/types/langs/rust.d.ts +5 -0
  37. package/types/langs/scala.d.ts +5 -0
  38. package/types/langs/toml.d.ts +5 -0
  39. package/types/langs/tsx.d.ts +5 -0
  40. package/types/langs/typescript.d.ts +5 -0
  41. package/types/langs/xml.d.ts +5 -0
  42. package/types/langs/yaml.d.ts +5 -0
  43. package/types/llm.d.ts +6 -0
  44. package/types/llrt/abort.d.ts +69 -0
  45. package/types/llrt/assert.d.ts +39 -0
  46. package/types/llrt/async_hooks.d.ts +210 -0
  47. package/types/llrt/buffer.d.ts +1186 -0
  48. package/types/llrt/child_process.d.ts +447 -0
  49. package/types/llrt/console.d.ts +210 -0
  50. package/types/llrt/crypto.d.ts +854 -0
  51. package/types/llrt/dgram.d.ts +381 -0
  52. package/types/llrt/dns.d.ts +124 -0
  53. package/types/llrt/dom-events.d.ts +51 -0
  54. package/types/llrt/events.d.ts +245 -0
  55. package/types/llrt/exceptions.d.ts +26 -0
  56. package/types/llrt/fetch.d.ts +332 -0
  57. package/types/llrt/fs/promises.d.ts +554 -0
  58. package/types/llrt/fs.d.ts +360 -0
  59. package/types/llrt/globals.d.ts +23 -0
  60. package/types/llrt/https.d.ts +27 -0
  61. package/types/llrt/index.d.ts +33 -0
  62. package/types/llrt/module.d.ts +285 -0
  63. package/types/llrt/navigator.d.ts +9 -0
  64. package/types/llrt/net.d.ts +488 -0
  65. package/types/llrt/os.d.ts +293 -0
  66. package/types/llrt/path.d.ts +150 -0
  67. package/types/llrt/perf_hooks.d.ts +23 -0
  68. package/types/llrt/process.d.ts +502 -0
  69. package/types/llrt/stream/web.d.ts +526 -0
  70. package/types/llrt/stream.d.ts +366 -0
  71. package/types/llrt/string_decoder.d.ts +63 -0
  72. package/types/llrt/timers.d.ts +72 -0
  73. package/types/llrt/timezone.d.ts +101 -0
  74. package/types/llrt/tty.d.ts +11 -0
  75. package/types/llrt/url.d.ts +774 -0
  76. package/types/llrt/util.d.ts +240 -0
  77. package/types/llrt/zlib.d.ts +177 -0
  78. package/types/main.d.ts +5 -0
  79. package/types/metrics.d.ts +5 -0
  80. package/types/modules/ast-grep.d.ts +634 -0
  81. package/types/modules/langs.d.ts +87 -0
  82. package/types/modules/llm.d.ts +23 -0
  83. package/types/modules/metrics.d.ts +107 -0
  84. package/types/modules/runtime.d.ts +66 -0
  85. package/types/modules/workflow.d.ts +750 -0
  86. package/types/runtime.d.ts +6 -0
  87. package/types/workflow.d.ts +5 -0
  88. package/vite.d.mts +24 -0
  89. package/vite.mjs +26 -0
@@ -0,0 +1,135 @@
1
+ // `codemod:workflow` in Node.js and Bun: the shared orchestrator, with the
2
+ // run looked up per call (see context.mjs).
3
+ //
4
+ // In the workflow body, `step`, `getState` and `setState` go to the run's
5
+ // orchestrator. Inside a function step or a `forEachFile` callback, the state
6
+ // functions see the state the step started with, and what they set becomes
7
+ // the step's state changes, as in the engine's isolates.
8
+
9
+ import { createHash } from "node:crypto";
10
+
11
+ import { current } from "./context.mjs";
12
+ import { createTasks } from "./orchestrator.mjs";
13
+
14
+ export {
15
+ AwaitingApprovalError,
16
+ CanceledError,
17
+ NondeterminismError,
18
+ StepError,
19
+ } from "./orchestrator.mjs";
20
+
21
+ /** Identifies a callback given as a function, for replay checks. */
22
+ export function callbackId(fn) {
23
+ return `fn:${createHash("sha256").update(String(fn)).digest("hex").slice(0, 16)}`;
24
+ }
25
+
26
+ export const {
27
+ __callback,
28
+ forEachFile,
29
+ shell,
30
+ jssg,
31
+ astGrep,
32
+ shard,
33
+ codemod,
34
+ agent,
35
+ installSkill,
36
+ approval,
37
+ branch,
38
+ commit,
39
+ pullRequest,
40
+ } = createTasks({ callbackId });
41
+
42
+ export function step(labelOrTask, maybeTask) {
43
+ const scope = current("step()");
44
+ if (scope.step) {
45
+ throw new Error(
46
+ "step() cannot be called inside a step or forEachFile callback; start steps from the workflow body",
47
+ );
48
+ }
49
+ return scope.runtime.step(labelOrTask, maybeTask);
50
+ }
51
+
52
+ // In a step or callback the state functions behave as in the engine's
53
+ // isolates: values are copied in and out, and what the step leaves different
54
+ // from the state it started with becomes its state changes.
55
+
56
+ export function getState(key) {
57
+ const scope = current("getState()");
58
+ if (!scope.step) return scope.runtime.getState(key);
59
+ const state = scope.step.state;
60
+ if (key === undefined) return structuredClone(Object.fromEntries(state));
61
+ return state.has(key) ? structuredClone(state.get(key)) : undefined;
62
+ }
63
+
64
+ export function setState(key, value, persist = true) {
65
+ const scope = current("setState()");
66
+ if (!scope.step) return scope.runtime.setState(key, value);
67
+ const step = scope.step;
68
+ step.state.set(key, stateValue(value));
69
+ step.removed.delete(key);
70
+ if (persist) step.unpersisted.delete(key);
71
+ else step.unpersisted.add(key);
72
+ }
73
+
74
+ export function unsetState(key) {
75
+ const scope = current("unsetState()");
76
+ if (!scope.step) return scope.runtime.unsetState(key);
77
+ scope.step.state.delete(key);
78
+ scope.step.removed.add(key);
79
+ }
80
+
81
+ /**
82
+ * A value as state keeps it, the way the engine's isolates convert one:
83
+ * what is not JSON becomes `null`, and objects keep their own enumerable
84
+ * properties (so a `Date` or a `Map` becomes `{}`).
85
+ */
86
+ function stateValue(value) {
87
+ switch (typeof value) {
88
+ case "boolean":
89
+ case "string":
90
+ return value;
91
+ case "number":
92
+ return Number.isFinite(value) ? value : null;
93
+ case "bigint":
94
+ return Number(value);
95
+ case "object":
96
+ if (value === null) return null;
97
+ if (Array.isArray(value)) return value.map(stateValue);
98
+ return Object.fromEntries(Object.keys(value).map((key) => [key, stateValue(value[key])]));
99
+ default:
100
+ return null;
101
+ }
102
+ }
103
+
104
+ /** Callbacks run on one thread here, so a lock has nothing to wait for. */
105
+ export function acquireLock(name) {
106
+ const scope = current("acquireLock()");
107
+ if (!scope.step) return scope.runtime.acquireLock(name);
108
+ return () => {};
109
+ }
110
+
111
+ // Step outputs are kept for the transforms that still set them; nothing in a
112
+ // workflow reads them back but these functions.
113
+
114
+ export function setStepOutput(name, value) {
115
+ const scope = current("setStepOutput()");
116
+ if (!scope.step) return scope.runtime.setStepOutput(name, value);
117
+ scope.step.outputs.set(name, String(value));
118
+ }
119
+
120
+ export function getStepOutput(stepId, name) {
121
+ const scope = current("getStepOutput()");
122
+ if (!scope.step) return scope.runtime.getStepOutput(stepId, name);
123
+ return scope.step.outputs.get(name) ?? null;
124
+ }
125
+
126
+ export function getOrSetStepOutput(stepId, name, value) {
127
+ const scope = current("getOrSetStepOutput()");
128
+ if (!scope.step) return scope.runtime.getOrSetStepOutput(stepId, name, value);
129
+ if (!scope.step.outputs.has(name)) scope.step.outputs.set(name, String(value));
130
+ return scope.step.outputs.get(name);
131
+ }
132
+
133
+ export function __evaluate(kind, expression, scope) {
134
+ return current("__evaluate()").runtime.__evaluate(kind, expression, scope);
135
+ }
@@ -0,0 +1,203 @@
1
+ /**
2
+ * Run workflows from any test runner and compare the files they leave.
3
+ *
4
+ * ```ts
5
+ * import { test } from "node:test";
6
+ * import { runWorkflow, fixtures, assertTree } from "codemod/testing";
7
+ *
8
+ * for (const fixture of fixtures("tests")) {
9
+ * test(fixture.name, async () => {
10
+ * const run = await runWorkflow("workflow.ts", { target: fixture.input, params: fixture.params });
11
+ * assertTree(run, fixture.expected);
12
+ * });
13
+ * }
14
+ * ```
15
+ *
16
+ * Each run copies its target into a temporary directory first, so fixtures
17
+ * are never changed. Paths are resolved against the current directory;
18
+ * pass `new URL("./workflow.ts", import.meta.url)` to resolve against the
19
+ * test file instead.
20
+ *
21
+ * TypeScript workflows run in the test's own process, so breakpoints,
22
+ * coverage and mocks work in the workflow's code. `host: "quickjs"` runs them
23
+ * with the codemod CLI instead, in the sandboxed runtime `codemod run` uses.
24
+ *
25
+ * @module
26
+ */
27
+
28
+ export type JsonValue =
29
+ | string
30
+ | number
31
+ | boolean
32
+ | null
33
+ | JsonValue[]
34
+ | { [key: string]: JsonValue };
35
+
36
+ /** File contents by path, relative to the target (`"src/a.ts"`). */
37
+ export type FileTree = { readonly [path: string]: string };
38
+
39
+ /** A `URL` (`new URL("./tests", import.meta.url)`); only `file:` URLs are paths. */
40
+ export interface UrlLike {
41
+ readonly href: string;
42
+ }
43
+
44
+ /** A path, or a `file:` URL. */
45
+ export type PathLike = string | UrlLike;
46
+
47
+ /** An `AbortSignal`. */
48
+ export interface AbortSignalLike {
49
+ readonly aborted: boolean;
50
+ }
51
+
52
+ /** A workflow module: what `import("./workflow.ts")` gives. */
53
+ export interface WorkflowModule {
54
+ readonly default: (...args: never[]) => unknown;
55
+ }
56
+
57
+ /** A capability a transform may use beyond those codemod.yaml declares. */
58
+ export type Capability = "fs" | "fetch" | "child_process";
59
+
60
+ export interface RunWorkflowOptions {
61
+ /**
62
+ * The files the workflow runs on: a directory or a single file (copied
63
+ * first), or files by path.
64
+ */
65
+ target: PathLike | FileTree;
66
+ /** The workflow's parameters. */
67
+ params?: Record<string, JsonValue>;
68
+ /**
69
+ * Stop after the step with this label: steps the workflow starts after it
70
+ * do not run. The run's status is then `"stopped"`.
71
+ */
72
+ until?: string;
73
+ /**
74
+ * Results for steps that should not run, by label. The workflow gets the
75
+ * given value as the step's result.
76
+ */
77
+ given?: Record<string, JsonValue>;
78
+ /** Give every approval the workflow asks for. Default `true`. */
79
+ approve?: boolean;
80
+ /** Capabilities granted on top of those codemod.yaml declares. */
81
+ capabilities?: Capability[];
82
+ /** Which workflow to run when codemod.yaml defines several. */
83
+ workflowName?: string;
84
+ /** Keep the temporary directory the run changed (`run.dir`). */
85
+ keep?: boolean;
86
+ /** Stops the run. */
87
+ signal?: AbortSignalLike;
88
+ /**
89
+ * Where the workflow runs. `"node"` (the default for TypeScript workflows):
90
+ * in this process. `"quickjs"`: with the codemod CLI, in the sandboxed
91
+ * runtime `codemod run` uses, where capabilities are enforced. YAML
92
+ * workflows always run with the CLI.
93
+ */
94
+ host?: "node" | "quickjs";
95
+ /** The workflow file, when `workflow` is the module itself. */
96
+ path?: PathLike;
97
+ }
98
+
99
+ export type RunStatus = "succeeded" | "failed" | "canceled" | "awaiting-approval" | "stopped";
100
+
101
+ export interface StepRun {
102
+ readonly position: number;
103
+ readonly label: string;
104
+ readonly status: "succeeded" | "failed";
105
+ readonly result: JsonValue | null;
106
+ readonly error: string | null;
107
+ /** The step did not run: its result came from `given`. */
108
+ readonly given: boolean;
109
+ }
110
+
111
+ export interface LogLine {
112
+ /** Label of the step that logged it; `null` for the workflow body. */
113
+ readonly step: string | null;
114
+ readonly line: string;
115
+ }
116
+
117
+ export interface WorkflowRun {
118
+ readonly status: RunStatus;
119
+ /** Whether the run succeeded, or stopped at its `until` step. */
120
+ readonly ok: boolean;
121
+ /** What the workflow returned, when it succeeded. */
122
+ readonly output: JsonValue | null;
123
+ /** Why the run failed. */
124
+ readonly error: string | null;
125
+ /** The approval the run waits for (`approve: false`). */
126
+ readonly awaiting: string | null;
127
+ /** The `until` step the run stopped after. */
128
+ readonly stoppedAt: string | null;
129
+ /** The directory the run changed; removed afterwards unless `keep` is set. */
130
+ readonly dir: string;
131
+ /** Every file after the run. */
132
+ readonly files: FileTree;
133
+ /** Files the run wrote or created, with their new text; `null` for files it removed. */
134
+ readonly changes: { readonly [path: string]: string | null };
135
+ /** Every step, in the order the workflow started them. */
136
+ readonly steps: readonly StepRun[];
137
+ /** Console output, from steps, callbacks and the workflow body. */
138
+ readonly logs: readonly LogLine[];
139
+ /** Metrics the transforms recorded. */
140
+ readonly metrics: Record<string, unknown>;
141
+ /** The first step with this label. Throws when there is none. */
142
+ step(label: string): StepRun;
143
+ /** A unified diff of every file the run changed. */
144
+ diff(): string;
145
+ }
146
+
147
+ /**
148
+ * Run a workflow (a workflow file, a package directory, or the workflow
149
+ * module itself, with `options.path`) on a copy of `options.target`. Resolves for every outcome; check `run.status`, or use
150
+ * `assertTree`, which fails when the run did not succeed. Rejects when the
151
+ * workflow cannot run at all (for example it does not build), or when an
152
+ * `until` or `given` label matches no step.
153
+ */
154
+ export function runWorkflow(
155
+ workflow: PathLike | WorkflowModule,
156
+ options: RunWorkflowOptions,
157
+ ): Promise<WorkflowRun>;
158
+
159
+ export interface Fixture {
160
+ /** The fixture's directory, relative to the fixtures directory (`"renames/default-export"`). */
161
+ readonly name: string;
162
+ readonly dir: string;
163
+ /** `input/`, or the `input.<ext>` file: pass it as `target`. */
164
+ readonly input: string;
165
+ /** `expected/`, or the `expected.<ext>` file: pass it to `assertTree`. */
166
+ readonly expected: string;
167
+ /** From `params.json`, or empty. */
168
+ readonly params: Record<string, JsonValue>;
169
+ }
170
+
171
+ /**
172
+ * The fixtures in a directory: each subdirectory with `input/` and
173
+ * `expected/` directories, or `input.<ext>` and `expected.<ext>` files (the
174
+ * layouts `codemod jssg test` and `codemod workflow test` read). Groups of
175
+ * fixtures may be nested.
176
+ */
177
+ export function fixtures(dir: PathLike): Fixture[];
178
+
179
+ export interface AssertTreeOptions {
180
+ /** Ignore whitespace at the ends of lines and of files. */
181
+ ignoreWhitespace?: boolean;
182
+ /** Put in front of the failure message. */
183
+ message?: string;
184
+ }
185
+
186
+ /**
187
+ * Assert that `actual` holds exactly the expected files. Throws an
188
+ * `AssertionError` with `actual` and `expected` set and a diff in the
189
+ * message.
190
+ *
191
+ * - `actual`: a run (which must have succeeded or stopped), a directory, or
192
+ * files by path.
193
+ * - `expected`: a directory, files by path, or a single file, in which case
194
+ * the run must have left exactly one file.
195
+ *
196
+ * Line endings are compared as `\n`. With `CODEMOD_UPDATE_FIXTURES=1`, an
197
+ * expected directory or file is rewritten to match `actual` instead.
198
+ */
199
+ export function assertTree(
200
+ actual: WorkflowRun | PathLike | FileTree,
201
+ expected: PathLike | FileTree,
202
+ options?: AssertTreeOptions,
203
+ ): void;