codemod 2.0.0-alpha.1 → 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.
- package/README.md +57 -2
- package/codemod +17 -30
- package/package.json +78 -10
- package/register.d.mts +11 -0
- package/register.mjs +60 -0
- package/runtime/addon.mjs +59 -0
- package/runtime/ast-grep.mjs +93 -0
- package/runtime/context.mjs +77 -0
- package/runtime/hooks.mjs +9 -0
- package/runtime/host.d.mts +120 -0
- package/runtime/host.mjs +390 -0
- package/runtime/llm.mjs +11 -0
- package/runtime/metrics.mjs +45 -0
- package/runtime/modules.mjs +19 -0
- package/runtime/orchestrator.mjs +657 -0
- package/runtime/runtime.mjs +48 -0
- package/runtime/workflow.mjs +135 -0
- package/testing/index.d.mts +203 -0
- package/testing/index.mjs +638 -0
- package/types/index.d.ts +8 -0
- package/types/langs/angular.d.ts +5 -0
- package/types/langs/c.d.ts +5 -0
- package/types/langs/c_sharp.d.ts +5 -0
- package/types/langs/cpp.d.ts +5 -0
- package/types/langs/css.d.ts +5 -0
- package/types/langs/elixir.d.ts +5 -0
- package/types/langs/go.d.ts +5 -0
- package/types/langs/html.d.ts +5 -0
- package/types/langs/java.d.ts +5 -0
- package/types/langs/javascript.d.ts +5 -0
- package/types/langs/json.d.ts +5 -0
- package/types/langs/kotlin.d.ts +5 -0
- package/types/langs/php.d.ts +5 -0
- package/types/langs/python.d.ts +5 -0
- package/types/langs/ruby.d.ts +5 -0
- package/types/langs/rust.d.ts +5 -0
- package/types/langs/scala.d.ts +5 -0
- package/types/langs/toml.d.ts +5 -0
- package/types/langs/tsx.d.ts +5 -0
- package/types/langs/typescript.d.ts +5 -0
- package/types/langs/xml.d.ts +5 -0
- package/types/langs/yaml.d.ts +5 -0
- package/types/llm.d.ts +6 -0
- package/types/llrt/abort.d.ts +69 -0
- package/types/llrt/assert.d.ts +39 -0
- package/types/llrt/async_hooks.d.ts +210 -0
- package/types/llrt/buffer.d.ts +1186 -0
- package/types/llrt/child_process.d.ts +447 -0
- package/types/llrt/console.d.ts +210 -0
- package/types/llrt/crypto.d.ts +854 -0
- package/types/llrt/dgram.d.ts +381 -0
- package/types/llrt/dns.d.ts +124 -0
- package/types/llrt/dom-events.d.ts +51 -0
- package/types/llrt/events.d.ts +245 -0
- package/types/llrt/exceptions.d.ts +26 -0
- package/types/llrt/fetch.d.ts +332 -0
- package/types/llrt/fs/promises.d.ts +554 -0
- package/types/llrt/fs.d.ts +360 -0
- package/types/llrt/globals.d.ts +23 -0
- package/types/llrt/https.d.ts +27 -0
- package/types/llrt/index.d.ts +33 -0
- package/types/llrt/module.d.ts +285 -0
- package/types/llrt/navigator.d.ts +9 -0
- package/types/llrt/net.d.ts +488 -0
- package/types/llrt/os.d.ts +293 -0
- package/types/llrt/path.d.ts +150 -0
- package/types/llrt/perf_hooks.d.ts +23 -0
- package/types/llrt/process.d.ts +502 -0
- package/types/llrt/stream/web.d.ts +526 -0
- package/types/llrt/stream.d.ts +366 -0
- package/types/llrt/string_decoder.d.ts +63 -0
- package/types/llrt/timers.d.ts +72 -0
- package/types/llrt/timezone.d.ts +101 -0
- package/types/llrt/tty.d.ts +11 -0
- package/types/llrt/url.d.ts +774 -0
- package/types/llrt/util.d.ts +240 -0
- package/types/llrt/zlib.d.ts +177 -0
- package/types/main.d.ts +5 -0
- package/types/metrics.d.ts +5 -0
- package/types/modules/ast-grep.d.ts +634 -0
- package/types/modules/langs.d.ts +87 -0
- package/types/modules/llm.d.ts +23 -0
- package/types/modules/metrics.d.ts +107 -0
- package/types/modules/runtime.d.ts +66 -0
- package/types/modules/workflow.d.ts +750 -0
- package/types/runtime.d.ts +6 -0
- package/types/workflow.d.ts +5 -0
- package/vite.d.mts +24 -0
- package/vite.mjs +26 -0
|
@@ -0,0 +1,750 @@
|
|
|
1
|
+
// oxlint-disable triple-slash-reference
|
|
2
|
+
/// <reference path="./metrics.d.ts" />
|
|
3
|
+
|
|
4
|
+
declare module "codemod:workflow" {
|
|
5
|
+
/**
|
|
6
|
+
* Workflow Step Outputs Module
|
|
7
|
+
*
|
|
8
|
+
* This module provides functions to store and retrieve step outputs
|
|
9
|
+
* across workflow executions, similar to GitHub Actions.
|
|
10
|
+
*/
|
|
11
|
+
|
|
12
|
+
/**
|
|
13
|
+
* Sets a step output value.
|
|
14
|
+
*
|
|
15
|
+
* Step outputs allow you to share data between steps in a workflow.
|
|
16
|
+
* Similar to GitHub Actions, you can reference outputs like:
|
|
17
|
+
* ${{ steps.my_step.outputs.my_output }}
|
|
18
|
+
*
|
|
19
|
+
* In native mode, outputs are appended to the file specified by
|
|
20
|
+
* the STEP_OUTPUTS environment variable.
|
|
21
|
+
*
|
|
22
|
+
* In WASM mode, outputs are stored in memory.
|
|
23
|
+
*
|
|
24
|
+
* @param stepId - The unique identifier of the step
|
|
25
|
+
* @param outputName - The name of the output variable
|
|
26
|
+
* @param value - The value to store (as a string)
|
|
27
|
+
*
|
|
28
|
+
* @deprecated Use `setState` instead for structured state that doesn't require manual JSON serialization.
|
|
29
|
+
*
|
|
30
|
+
* @example
|
|
31
|
+
* ```typescript
|
|
32
|
+
* import { setStepOutput } from 'codemod/workflow';
|
|
33
|
+
*
|
|
34
|
+
* // In a step with id="build"
|
|
35
|
+
* setStepOutput('build', 'version', '1.2.3');
|
|
36
|
+
* setStepOutput('build', 'artifact_path', '/tmp/build/app.zip');
|
|
37
|
+
*
|
|
38
|
+
* // Later steps can access these via:
|
|
39
|
+
* // ${{ steps.build.outputs.version }}
|
|
40
|
+
* // ${{ steps.build.outputs.artifact_path }}
|
|
41
|
+
* ```
|
|
42
|
+
*/
|
|
43
|
+
export function setStepOutput(outputName: string, value: string): void;
|
|
44
|
+
|
|
45
|
+
/**
|
|
46
|
+
* Gets a step output value.
|
|
47
|
+
*
|
|
48
|
+
* Returns the value as a string if found, or null if the output doesn't exist.
|
|
49
|
+
*
|
|
50
|
+
* @param stepId - The unique identifier of the step
|
|
51
|
+
* @param outputName - The name of the output variable
|
|
52
|
+
* @returns The value as a string, or null if not found
|
|
53
|
+
*
|
|
54
|
+
* @deprecated Use `getState` instead for structured state that doesn't require manual JSON parsing.
|
|
55
|
+
*
|
|
56
|
+
* @example
|
|
57
|
+
* ```typescript
|
|
58
|
+
* import { getStepOutput } from 'codemod/workflow';
|
|
59
|
+
*
|
|
60
|
+
* // Get output from a previous step
|
|
61
|
+
* const version = getStepOutput('build', 'version');
|
|
62
|
+
* console.log(version); // '1.2.3'
|
|
63
|
+
*
|
|
64
|
+
* // Check if output exists
|
|
65
|
+
* const artifactPath = getStepOutput('build', 'artifact_path');
|
|
66
|
+
* if (artifactPath) {
|
|
67
|
+
* console.log(`Artifact ready at: ${artifactPath}`);
|
|
68
|
+
* }
|
|
69
|
+
* ```
|
|
70
|
+
*/
|
|
71
|
+
export function getStepOutput(stepId: string, outputName: string): string | null;
|
|
72
|
+
|
|
73
|
+
/**
|
|
74
|
+
* Gets a step output value, or sets it if it doesn't exist (atomically).
|
|
75
|
+
*
|
|
76
|
+
* This function is useful in concurrent scenarios where multiple files are processed
|
|
77
|
+
* in parallel. The first thread to call this function will set the value if it doesn't
|
|
78
|
+
* exist, and subsequent calls will return the existing value.
|
|
79
|
+
*
|
|
80
|
+
* This operation is atomic, preventing race conditions when multiple threads try to
|
|
81
|
+
* access/set the same output simultaneously.
|
|
82
|
+
*
|
|
83
|
+
* @param stepId - The unique identifier of the step
|
|
84
|
+
* @param outputName - The name of the output variable
|
|
85
|
+
* @param defaultValue - The value to set if the output doesn't exist
|
|
86
|
+
* @returns The existing value (if found) or the newly set default value
|
|
87
|
+
*
|
|
88
|
+
* @deprecated Use `setState`/`getState` with `acquireLock` instead for structured state.
|
|
89
|
+
*
|
|
90
|
+
* @example
|
|
91
|
+
* ```typescript
|
|
92
|
+
* import { getOrSetStepOutput, setStepOutput } from 'codemod/workflow';
|
|
93
|
+
*
|
|
94
|
+
* // Multiple files being processed in parallel
|
|
95
|
+
* async function transform(root: SgRoot<JS>): Promise<string | null> {
|
|
96
|
+
* const source = root.root().text();
|
|
97
|
+
* const newFiles = source.split("\n").filter(line => line.trim() !== "");
|
|
98
|
+
*
|
|
99
|
+
* // Get existing files or initialize with empty array
|
|
100
|
+
* const existingFilesStr = getOrSetStepOutput("scan-files", "allFiles", "[]");
|
|
101
|
+
* const existingFiles = JSON.parse(existingFilesStr);
|
|
102
|
+
*
|
|
103
|
+
* // Merge with existing files
|
|
104
|
+
* const allFiles = [...existingFiles, ...newFiles];
|
|
105
|
+
*
|
|
106
|
+
* // Update the output
|
|
107
|
+
* setStepOutput("allFiles", JSON.stringify(allFiles));
|
|
108
|
+
*
|
|
109
|
+
* return null;
|
|
110
|
+
* }
|
|
111
|
+
* ```
|
|
112
|
+
*/
|
|
113
|
+
export function getOrSetStepOutput(
|
|
114
|
+
stepId: string,
|
|
115
|
+
outputName: string,
|
|
116
|
+
defaultValue: string,
|
|
117
|
+
): string;
|
|
118
|
+
|
|
119
|
+
/**
|
|
120
|
+
* Sets a named state value that is shared across all parallel file executions.
|
|
121
|
+
*
|
|
122
|
+
* Values are stored as native JavaScript objects internally (no JSON serialization needed).
|
|
123
|
+
* When `persist` is true (the default), the value will be persisted at the end of the
|
|
124
|
+
* execution batch and available to subsequent workflow steps.
|
|
125
|
+
*
|
|
126
|
+
* @param name - The state key
|
|
127
|
+
* @param value - Any JSON-serializable value
|
|
128
|
+
* @param persist - Whether to persist across workflow steps (default: true)
|
|
129
|
+
*
|
|
130
|
+
* @example
|
|
131
|
+
* ```typescript
|
|
132
|
+
* import { setState } from 'codemod/workflow';
|
|
133
|
+
*
|
|
134
|
+
* setState("migratedFiles", ["src/App.tsx", "src/utils.ts"]);
|
|
135
|
+
* setState("stats", { totalFiles: 42, modified: 5 });
|
|
136
|
+
* setState("tempCounter", 0, false); // transient, not persisted
|
|
137
|
+
* ```
|
|
138
|
+
*/
|
|
139
|
+
export function setState<T>(name: string, value: T, persist?: boolean): void;
|
|
140
|
+
|
|
141
|
+
/**
|
|
142
|
+
* Gets a named state value, or `undefined` if it doesn't exist.
|
|
143
|
+
*
|
|
144
|
+
* @param name - The state key
|
|
145
|
+
* @returns The stored value, or `undefined` if not found
|
|
146
|
+
*
|
|
147
|
+
* @example
|
|
148
|
+
* ```typescript
|
|
149
|
+
* import { getState } from 'codemod/workflow';
|
|
150
|
+
*
|
|
151
|
+
* const files = getState<string[]>("migratedFiles");
|
|
152
|
+
* if (files) {
|
|
153
|
+
* console.log(`Already migrated ${files.length} files`);
|
|
154
|
+
* }
|
|
155
|
+
* ```
|
|
156
|
+
*/
|
|
157
|
+
export function getState<T>(name: string): T | undefined;
|
|
158
|
+
|
|
159
|
+
/**
|
|
160
|
+
* Removes a named state value.
|
|
161
|
+
*
|
|
162
|
+
* If the key was previously persisted, a removal diff will be generated
|
|
163
|
+
* so the value is also removed from persistent storage.
|
|
164
|
+
*
|
|
165
|
+
* @param name - The state key to remove
|
|
166
|
+
*
|
|
167
|
+
* @example
|
|
168
|
+
* ```typescript
|
|
169
|
+
* import { unsetState } from 'codemod/workflow';
|
|
170
|
+
*
|
|
171
|
+
* unsetState("tempData");
|
|
172
|
+
* ```
|
|
173
|
+
*/
|
|
174
|
+
export function unsetState(name: string): void;
|
|
175
|
+
|
|
176
|
+
/**
|
|
177
|
+
* Acquires a named mutex lock for coordinating concurrent access to shared state.
|
|
178
|
+
*
|
|
179
|
+
* Returns a `release` function that must be called when done. The lock blocks other
|
|
180
|
+
* threads trying to acquire the same named lock until it is released.
|
|
181
|
+
*
|
|
182
|
+
* @param name - The lock name
|
|
183
|
+
* @returns A function that releases the lock (must be called exactly once)
|
|
184
|
+
*
|
|
185
|
+
* @example
|
|
186
|
+
* ```typescript
|
|
187
|
+
* import { acquireLock, getState, setState } from 'codemod/workflow';
|
|
188
|
+
*
|
|
189
|
+
* // Safely accumulate results from parallel file processing
|
|
190
|
+
* const release = acquireLock("results");
|
|
191
|
+
* try {
|
|
192
|
+
* const results = getState<string[]>("allResults") ?? [];
|
|
193
|
+
* results.push(currentFile);
|
|
194
|
+
* setState("allResults", results);
|
|
195
|
+
* } finally {
|
|
196
|
+
* release();
|
|
197
|
+
* }
|
|
198
|
+
* ```
|
|
199
|
+
*/
|
|
200
|
+
export function acquireLock(name: string): () => void;
|
|
201
|
+
|
|
202
|
+
// ── Shard function types ────────────────────────────────────────────────
|
|
203
|
+
|
|
204
|
+
/**
|
|
205
|
+
* Input passed to a custom shard function by the engine.
|
|
206
|
+
*
|
|
207
|
+
* The engine handles all file discovery (globbing + optional codemod dry-run)
|
|
208
|
+
* before calling the shard function. The function only needs to handle grouping.
|
|
209
|
+
*/
|
|
210
|
+
export interface ShardInput {
|
|
211
|
+
/** Relative paths of eligible files (pre-filtered by the engine) */
|
|
212
|
+
files: string[];
|
|
213
|
+
/** Absolute path to the target directory */
|
|
214
|
+
targetDir: string;
|
|
215
|
+
/** Previous shard assignments for incremental re-evaluation */
|
|
216
|
+
previousShards: ShardResult[];
|
|
217
|
+
}
|
|
218
|
+
|
|
219
|
+
/**
|
|
220
|
+
* A single shard result returned by a custom shard function.
|
|
221
|
+
*
|
|
222
|
+
* The `name` and `_meta_files` fields are required. Any additional
|
|
223
|
+
* properties are exposed as `matrix.*` variables in downstream steps.
|
|
224
|
+
*
|
|
225
|
+
* Fields prefixed with `_meta_` are excluded from the matrix hash,
|
|
226
|
+
* so re-indexing shards won't invalidate existing task identity.
|
|
227
|
+
*/
|
|
228
|
+
export interface ShardResult {
|
|
229
|
+
/** Shard identifier (used in PR titles, branch names) */
|
|
230
|
+
name: string;
|
|
231
|
+
/** Shard index — excluded from matrix hash for stability */
|
|
232
|
+
_meta_shard: number;
|
|
233
|
+
/** Files in this shard */
|
|
234
|
+
_meta_files: string[];
|
|
235
|
+
/** Arbitrary metadata exposed as matrix variables */
|
|
236
|
+
[key: string]: unknown;
|
|
237
|
+
}
|
|
238
|
+
|
|
239
|
+
// ── Workflow authoring (workflow.ts) ───────────────────────────────────
|
|
240
|
+
//
|
|
241
|
+
// Everything below is used from a workflow file. `getState`, `setState`,
|
|
242
|
+
// `unsetState` and `acquireLock` above also work inside function steps and
|
|
243
|
+
// forEachFile callbacks; the step output functions only in JSSG transforms.
|
|
244
|
+
//
|
|
245
|
+
// Code inside `step(() => ...)` and `forEachFile(...)` callbacks runs in
|
|
246
|
+
// its own isolate, with every module the run allows (`fs`, `fetch` and
|
|
247
|
+
// `child_process` behind --allow-*). The rest of the workflow, the body,
|
|
248
|
+
// runs again on every resume: there, `Date`, `Math.random` and
|
|
249
|
+
// `crypto.randomUUID` are replay-safe, and modules that read files, the
|
|
250
|
+
// network, the environment or the clock are build errors.
|
|
251
|
+
|
|
252
|
+
import type { MetricEntry } from "codemod:metrics";
|
|
253
|
+
|
|
254
|
+
/** A JSON value: what step results, captured variables and state may hold. */
|
|
255
|
+
export type JsonValue =
|
|
256
|
+
| string
|
|
257
|
+
| number
|
|
258
|
+
| boolean
|
|
259
|
+
| null
|
|
260
|
+
| readonly JsonValue[]
|
|
261
|
+
| { readonly [key: string]: JsonValue };
|
|
262
|
+
|
|
263
|
+
/** Stands in for a value that is not JSON, so the type error names the problem. */
|
|
264
|
+
export interface NotJson<Reason extends string> {
|
|
265
|
+
readonly __notJson: Reason;
|
|
266
|
+
}
|
|
267
|
+
|
|
268
|
+
/**
|
|
269
|
+
* `T` with every part that is not JSON replaced by a `NotJson` marker,
|
|
270
|
+
* so a value of type `T` is JSON when it is assignable to `JsonCompatible<T>`.
|
|
271
|
+
*/
|
|
272
|
+
export type JsonCompatible<T> = unknown extends T
|
|
273
|
+
? T
|
|
274
|
+
: T extends string | number | boolean | null | undefined | void
|
|
275
|
+
? T
|
|
276
|
+
: T extends PromiseLike<unknown>
|
|
277
|
+
? NotJson<"a Promise: await it first">
|
|
278
|
+
: T extends (...args: never[]) => unknown
|
|
279
|
+
? NotJson<"a function">
|
|
280
|
+
: T extends ReadonlySet<unknown>
|
|
281
|
+
? NotJson<"a Set: use an array">
|
|
282
|
+
: T extends ReadonlyMap<unknown, unknown>
|
|
283
|
+
? NotJson<"a Map: use a plain object">
|
|
284
|
+
: T extends Date
|
|
285
|
+
? NotJson<"a Date: use date.toISOString()">
|
|
286
|
+
: T extends RegExp
|
|
287
|
+
? NotJson<"a RegExp: use its source string">
|
|
288
|
+
: T extends object
|
|
289
|
+
? { [K in keyof T]: JsonCompatible<T[K]> }
|
|
290
|
+
: NotJson<"not JSON">;
|
|
291
|
+
|
|
292
|
+
/** Step results are deeply frozen. */
|
|
293
|
+
export type Frozen<T> = T extends (...args: never[]) => unknown
|
|
294
|
+
? T
|
|
295
|
+
: T extends readonly (infer U)[]
|
|
296
|
+
? readonly Frozen<U>[]
|
|
297
|
+
: T extends object
|
|
298
|
+
? { readonly [K in keyof T]: Frozen<T[K]> }
|
|
299
|
+
: T;
|
|
300
|
+
|
|
301
|
+
const taskResult: unique symbol;
|
|
302
|
+
|
|
303
|
+
/** Work for `step()` to run, made by `forEachFile` or a task such as `jssg`. */
|
|
304
|
+
export interface Task<Result> {
|
|
305
|
+
readonly [taskResult]: Result;
|
|
306
|
+
}
|
|
307
|
+
|
|
308
|
+
/** What the workflow's default export receives. */
|
|
309
|
+
export interface WorkflowContext<Params = Record<string, unknown>> {
|
|
310
|
+
/** `--param key=value` values (JSON when they parse as JSON, otherwise strings). */
|
|
311
|
+
params: Params;
|
|
312
|
+
/** Absolute path of the directory the workflow runs on. */
|
|
313
|
+
target: string;
|
|
314
|
+
/** Whether this is a dry run: file changes are computed but not written. */
|
|
315
|
+
dryRun: boolean;
|
|
316
|
+
}
|
|
317
|
+
|
|
318
|
+
/**
|
|
319
|
+
* Runs a task as a durable step and resolves to its frozen result.
|
|
320
|
+
*
|
|
321
|
+
* The step starts when `step()` is called, so `Promise.all` runs steps in
|
|
322
|
+
* parallel. Its result is recorded; on `codemod workflow resume`, finished
|
|
323
|
+
* steps are replayed from the record instead of running again.
|
|
324
|
+
*
|
|
325
|
+
* @example
|
|
326
|
+
* ```ts
|
|
327
|
+
* const renamed = await step("Rename stylesheets", forEachFile("src/**\/*.less", (file) => {
|
|
328
|
+
* file.rename(file.path.replace(/\.less$/, ".css"));
|
|
329
|
+
* }));
|
|
330
|
+
* ```
|
|
331
|
+
*/
|
|
332
|
+
export function step<Result>(task: Task<Result>): Promise<Frozen<Result>>;
|
|
333
|
+
export function step<Result>(label: string, task: Task<Result>): Promise<Frozen<Result>>;
|
|
334
|
+
/**
|
|
335
|
+
* Runs a function once, in its own isolate, and records its result, which
|
|
336
|
+
* must be JSON. Write it inline: outside variables arrive as frozen copies,
|
|
337
|
+
* and assigning to them is a build error. Inside, `Date`, `fetch`, `fs` and
|
|
338
|
+
* so on are real (as the run's capabilities allow).
|
|
339
|
+
*/
|
|
340
|
+
export function step<Result>(
|
|
341
|
+
run: () => PromiseLike<Checked<Result>>,
|
|
342
|
+
): Promise<Frozen<StepValue<Result>>>;
|
|
343
|
+
export function step<Result>(
|
|
344
|
+
label: string,
|
|
345
|
+
run: () => PromiseLike<Checked<Result>>,
|
|
346
|
+
): Promise<Frozen<StepValue<Result>>>;
|
|
347
|
+
export function step<Result>(run: () => Checked<Result>): Promise<Frozen<StepValue<Result>>>;
|
|
348
|
+
export function step<Result>(
|
|
349
|
+
label: string,
|
|
350
|
+
run: () => Checked<Result>,
|
|
351
|
+
): Promise<Frozen<StepValue<Result>>>;
|
|
352
|
+
|
|
353
|
+
/**
|
|
354
|
+
* `T`, checked to be JSON: `Result` is inferred from the value, which must
|
|
355
|
+
* then also be assignable to its JSON-compatible form.
|
|
356
|
+
*/
|
|
357
|
+
export type Checked<T> = T & NoInfer<JsonCompatible<T>>;
|
|
358
|
+
|
|
359
|
+
/** A function step that returns nothing records `null`. */
|
|
360
|
+
export type StepValue<T> = [T] extends [void | undefined] ? null : Exclude<T, void | undefined>;
|
|
361
|
+
|
|
362
|
+
/** One glob or several. */
|
|
363
|
+
export type Globs = string | readonly string[];
|
|
364
|
+
|
|
365
|
+
/** Languages `forEachFile` can select files by, through their extensions. */
|
|
366
|
+
export type SelectorLanguage =
|
|
367
|
+
| "typescript"
|
|
368
|
+
| "tsx"
|
|
369
|
+
| "javascript"
|
|
370
|
+
| "css"
|
|
371
|
+
| "json"
|
|
372
|
+
| "html"
|
|
373
|
+
| "python"
|
|
374
|
+
| "rust"
|
|
375
|
+
| "go"
|
|
376
|
+
| "java"
|
|
377
|
+
| "yaml";
|
|
378
|
+
|
|
379
|
+
/** How a `forEachFile` step runs its callback. */
|
|
380
|
+
export interface ForEachFileOptions {
|
|
381
|
+
/** Files only these globs match are skipped. */
|
|
382
|
+
exclude?: Globs;
|
|
383
|
+
/** Only files whose text contains this string. */
|
|
384
|
+
containing?: string;
|
|
385
|
+
/**
|
|
386
|
+
* Files each worker keeps in flight (default 1). Raise it for async
|
|
387
|
+
* callbacks that wait on the network or `codemod/llm`.
|
|
388
|
+
*/
|
|
389
|
+
concurrency?: number;
|
|
390
|
+
}
|
|
391
|
+
|
|
392
|
+
/**
|
|
393
|
+
* Which files `forEachFile` visits, and how: a glob, a list of globs, or an
|
|
394
|
+
* object. Without `include` or `language`, the files of the package's
|
|
395
|
+
* `targets.languages` (codemod.yaml) are visited. `.gitignore` is respected.
|
|
396
|
+
*/
|
|
397
|
+
export type FileSelector =
|
|
398
|
+
| Globs
|
|
399
|
+
| (ForEachFileOptions & {
|
|
400
|
+
include: Globs;
|
|
401
|
+
/** The default language for `parse(file)` and `parse(text)`. */
|
|
402
|
+
language?: string;
|
|
403
|
+
})
|
|
404
|
+
| (ForEachFileOptions & {
|
|
405
|
+
include?: undefined;
|
|
406
|
+
/** Selects the language's file extensions, and is the default for `parse`. */
|
|
407
|
+
language?: SelectorLanguage;
|
|
408
|
+
});
|
|
409
|
+
|
|
410
|
+
/** The file a `forEachFile` callback receives. Changes are applied when the step ends. */
|
|
411
|
+
export interface WorkflowFile {
|
|
412
|
+
/** Path relative to the target. */
|
|
413
|
+
readonly path: string;
|
|
414
|
+
/** Contents when the step started. */
|
|
415
|
+
readonly text: string;
|
|
416
|
+
/** The selector's `language`, which `parse(file)` uses; otherwise undefined. */
|
|
417
|
+
readonly language?: string;
|
|
418
|
+
/** Replace the contents. */
|
|
419
|
+
write(text: string): void;
|
|
420
|
+
/** Move the file to `path`, relative to the target. */
|
|
421
|
+
rename(path: string): void;
|
|
422
|
+
/** Remove the file. */
|
|
423
|
+
delete(): void;
|
|
424
|
+
}
|
|
425
|
+
|
|
426
|
+
/** Files a step changed. */
|
|
427
|
+
export interface FileChanges {
|
|
428
|
+
written: string[];
|
|
429
|
+
renamed: { from: string; to: string }[];
|
|
430
|
+
deleted: string[];
|
|
431
|
+
}
|
|
432
|
+
|
|
433
|
+
export interface FileFailure {
|
|
434
|
+
path: string;
|
|
435
|
+
error: string;
|
|
436
|
+
}
|
|
437
|
+
|
|
438
|
+
export interface ForEachFileResult<Output> {
|
|
439
|
+
/** What the callback returned, in path order. Files that returned nothing are left out. */
|
|
440
|
+
outputs: Output[];
|
|
441
|
+
changes: FileChanges;
|
|
442
|
+
/** Files whose callback threw. */
|
|
443
|
+
failures: FileFailure[];
|
|
444
|
+
/** What callbacks recorded with `codemod/metrics`, by metric name. */
|
|
445
|
+
metrics: Record<string, MetricEntry[]>;
|
|
446
|
+
}
|
|
447
|
+
|
|
448
|
+
/**
|
|
449
|
+
* Runs `callback` once for every selected file, in parallel, in isolates.
|
|
450
|
+
* The callback may be async. Returned values are collected into `outputs`.
|
|
451
|
+
*
|
|
452
|
+
* Write the callback inline. Variables from outside it arrive as frozen
|
|
453
|
+
* copies and must be JSON; assigning to them is a build error. Imports
|
|
454
|
+
* (`codemod/ast-grep`, `codemod/metrics`, packages, files next to the
|
|
455
|
+
* workflow) are available inside.
|
|
456
|
+
*
|
|
457
|
+
* @example
|
|
458
|
+
* ```ts
|
|
459
|
+
* import { parse } from "codemod/ast-grep";
|
|
460
|
+
*
|
|
461
|
+
* const usages = await step(forEachFile({ language: "typescript", containing: "moment" }, (file) => {
|
|
462
|
+
* const found = parse(file).root().findAll({ rule: { pattern: 'import $X from "moment"' } });
|
|
463
|
+
* return found.length ? file.path : undefined;
|
|
464
|
+
* }));
|
|
465
|
+
* usages.outputs; // readonly string[]
|
|
466
|
+
* ```
|
|
467
|
+
*/
|
|
468
|
+
export function forEachFile<Output = undefined>(
|
|
469
|
+
selector: FileSelector,
|
|
470
|
+
callback: (file: WorkflowFile) => PromiseLike<Checked<Output>>,
|
|
471
|
+
): Task<ForEachFileResult<Exclude<Output, void | undefined>>>;
|
|
472
|
+
export function forEachFile<Output = undefined>(
|
|
473
|
+
selector: FileSelector,
|
|
474
|
+
callback: (file: WorkflowFile) => Checked<Output>,
|
|
475
|
+
): Task<ForEachFileResult<Exclude<Output, void | undefined>>>;
|
|
476
|
+
/** Visits the files of the package's `targets.languages` (codemod.yaml). */
|
|
477
|
+
export function forEachFile<Output = undefined>(
|
|
478
|
+
callback: (file: WorkflowFile) => PromiseLike<Checked<Output>>,
|
|
479
|
+
): Task<ForEachFileResult<Exclude<Output, void | undefined>>>;
|
|
480
|
+
export function forEachFile<Output = undefined>(
|
|
481
|
+
callback: (file: WorkflowFile) => Checked<Output>,
|
|
482
|
+
): Task<ForEachFileResult<Exclude<Output, void | undefined>>>;
|
|
483
|
+
|
|
484
|
+
/**
|
|
485
|
+
* Returns the whole workflow state as a frozen object.
|
|
486
|
+
* (With a key, see the `getState(name)` overload above.)
|
|
487
|
+
*/
|
|
488
|
+
export function getState(): Readonly<Record<string, JsonValue>>;
|
|
489
|
+
|
|
490
|
+
/**
|
|
491
|
+
* A result for tasks that do nothing in some runs: shell commands, agents
|
|
492
|
+
* and skill installs in a dry run, git tasks without `--managed-git`.
|
|
493
|
+
*/
|
|
494
|
+
export type Skippable<T> =
|
|
495
|
+
| (T & { skipped?: false })
|
|
496
|
+
| ({ skipped: true } & { [K in keyof T]?: undefined });
|
|
497
|
+
|
|
498
|
+
export interface ShellOptions {
|
|
499
|
+
/** Extra environment variables. */
|
|
500
|
+
env?: Readonly<Record<string, string>>;
|
|
501
|
+
/** Directory to run in, relative to the target (or absolute). Defaults to the current directory. */
|
|
502
|
+
cwd?: string;
|
|
503
|
+
}
|
|
504
|
+
|
|
505
|
+
/**
|
|
506
|
+
* Runs a shell command. It can read the workflow state from `$CODEMOD_STATE`
|
|
507
|
+
* (a JSON file) or `$CODEMOD_STATE_<KEY>`, and set state by writing
|
|
508
|
+
* `key=value` (or `key@=value` to append) lines to `$STATE_OUTPUTS`.
|
|
509
|
+
*/
|
|
510
|
+
export function shell(
|
|
511
|
+
command: string,
|
|
512
|
+
options?: ShellOptions,
|
|
513
|
+
): Task<Skippable<{ output: string }>>;
|
|
514
|
+
|
|
515
|
+
export type Capability = "fs" | "fetch" | "child_process";
|
|
516
|
+
|
|
517
|
+
export interface JssgOptions {
|
|
518
|
+
include?: Globs;
|
|
519
|
+
exclude?: Globs;
|
|
520
|
+
/** Directory under the target to restrict the run to. */
|
|
521
|
+
basePath?: string;
|
|
522
|
+
/** Process exactly these files, relative to the target. */
|
|
523
|
+
files?: readonly string[];
|
|
524
|
+
/** Defaults to `typescript`. */
|
|
525
|
+
language?: string;
|
|
526
|
+
/** Merged over the run's params; the transform reads them as `options.params`. */
|
|
527
|
+
params?: Readonly<Record<string, unknown>>;
|
|
528
|
+
/** The transform reads these as `options.matrixValues`. */
|
|
529
|
+
matrix?: Readonly<Record<string, unknown>>;
|
|
530
|
+
capabilities?: readonly Capability[];
|
|
531
|
+
/**
|
|
532
|
+
* Semantic analysis for `definition()` and `references()`: `"file"` (the default)
|
|
533
|
+
* analyses each file on its own, `"workspace"` the whole target (or `root`), and
|
|
534
|
+
* `"none"` turns it off.
|
|
535
|
+
*/
|
|
536
|
+
semanticAnalysis?:
|
|
537
|
+
| "file"
|
|
538
|
+
| "workspace"
|
|
539
|
+
| "none"
|
|
540
|
+
| { mode: "file" | "workspace"; root?: string };
|
|
541
|
+
threads?: number;
|
|
542
|
+
/** Run the transform without applying its changes. */
|
|
543
|
+
dryRun?: boolean;
|
|
544
|
+
}
|
|
545
|
+
|
|
546
|
+
export interface JssgResult {
|
|
547
|
+
changes: FileChanges;
|
|
548
|
+
unmodified: number;
|
|
549
|
+
failures: FileFailure[];
|
|
550
|
+
}
|
|
551
|
+
|
|
552
|
+
/** Runs a JSSG transform file. `path` is relative to the workflow file. */
|
|
553
|
+
export function jssg(path: string, options?: JssgOptions): Task<JssgResult>;
|
|
554
|
+
|
|
555
|
+
export interface AstGrepOptions {
|
|
556
|
+
include?: Globs;
|
|
557
|
+
exclude?: Globs;
|
|
558
|
+
basePath?: string;
|
|
559
|
+
threads?: number;
|
|
560
|
+
}
|
|
561
|
+
|
|
562
|
+
export interface AstGrepResult {
|
|
563
|
+
changes: FileChanges;
|
|
564
|
+
matches: number;
|
|
565
|
+
failures: FileFailure[];
|
|
566
|
+
}
|
|
567
|
+
|
|
568
|
+
/** Applies an ast-grep YAML rule file. `path` is relative to the workflow file. */
|
|
569
|
+
export function astGrep(path: string, options?: AstGrepOptions): Task<AstGrepResult>;
|
|
570
|
+
|
|
571
|
+
export type ShardMethod =
|
|
572
|
+
| {
|
|
573
|
+
type: "directory" | "codeowner";
|
|
574
|
+
/** Target number of files per shard. */
|
|
575
|
+
maxFilesPerShard: number;
|
|
576
|
+
/** Trailing shards smaller than this are merged into the previous one. */
|
|
577
|
+
minShardSize?: number;
|
|
578
|
+
}
|
|
579
|
+
| {
|
|
580
|
+
/** A JS/TS file whose default export receives a `ShardInput` and returns `ShardResult[]`. */
|
|
581
|
+
function: string;
|
|
582
|
+
};
|
|
583
|
+
|
|
584
|
+
export interface ShardOptions {
|
|
585
|
+
method: ShardMethod;
|
|
586
|
+
/** Directory to scan, relative to the target. */
|
|
587
|
+
target?: string;
|
|
588
|
+
/** Glob for eligible files when `jssg` is not set. */
|
|
589
|
+
filePattern?: string;
|
|
590
|
+
/** Keep only the files this transform would change. */
|
|
591
|
+
jssg?: JssgOptions & { path: string };
|
|
592
|
+
/** An earlier result of this step, so existing assignments are kept. */
|
|
593
|
+
previous?: readonly ShardResult[];
|
|
594
|
+
}
|
|
595
|
+
|
|
596
|
+
/** Splits files into groups ("shards"), for example one per directory or code owner. */
|
|
597
|
+
export function shard(options: ShardOptions): Task<ShardResult[]>;
|
|
598
|
+
|
|
599
|
+
/** Runs another codemod package (registry name or local path) as part of this step. */
|
|
600
|
+
export function codemod(
|
|
601
|
+
source: string,
|
|
602
|
+
options?: { params?: Readonly<Record<string, unknown>> },
|
|
603
|
+
): Task<{ output: JsonValue }>;
|
|
604
|
+
|
|
605
|
+
/** Coding agents `agent(...)` can run, by id. Aliases such as `"claude"` work too. */
|
|
606
|
+
export type CodingAgent =
|
|
607
|
+
| "claude-code"
|
|
608
|
+
| "codex"
|
|
609
|
+
| "cursor"
|
|
610
|
+
| "gemini"
|
|
611
|
+
| "antigravity"
|
|
612
|
+
| "opencode"
|
|
613
|
+
| "copilot"
|
|
614
|
+
| "amp"
|
|
615
|
+
| "qwen-code"
|
|
616
|
+
| "goose"
|
|
617
|
+
| "droid"
|
|
618
|
+
| "kimi"
|
|
619
|
+
| "crush"
|
|
620
|
+
| "openclaw"
|
|
621
|
+
| "aider"
|
|
622
|
+
| "kiro"
|
|
623
|
+
| "auggie"
|
|
624
|
+
| "cline";
|
|
625
|
+
|
|
626
|
+
export interface AgentOptions {
|
|
627
|
+
/**
|
|
628
|
+
* The coding agent to run, which must be installed. Without one: the run's
|
|
629
|
+
* agent (`--agent`, `LLM_AGENT`); the agent the workflow itself runs
|
|
630
|
+
* inside, which gets the prompt back; one the person picks; or the
|
|
631
|
+
* built-in agent when `LLM_API_KEY` is set.
|
|
632
|
+
*/
|
|
633
|
+
agent?: CodingAgent | (string & {});
|
|
634
|
+
/** Extra instructions for the agent. */
|
|
635
|
+
systemPrompt?: string;
|
|
636
|
+
/** A model name the agent understands. */
|
|
637
|
+
model?: string;
|
|
638
|
+
/**
|
|
639
|
+
* `"full"` (default): edit files and run commands without asking.
|
|
640
|
+
* `"read-only"`: the agent may look but not change anything. Agents that
|
|
641
|
+
* cannot be held to that (see the agent table in the docs) fail the step
|
|
642
|
+
* instead of running.
|
|
643
|
+
*/
|
|
644
|
+
autonomy?: "full" | "read-only";
|
|
645
|
+
/** Stop the agent after this many seconds. */
|
|
646
|
+
timeoutSeconds?: number;
|
|
647
|
+
/** Built-in agent only: the most tool-using steps it may take. */
|
|
648
|
+
maxSteps?: number;
|
|
649
|
+
/** Built-in agent only. */
|
|
650
|
+
tools?: readonly string[];
|
|
651
|
+
/** Built-in agent only. */
|
|
652
|
+
endpoint?: string;
|
|
653
|
+
/** Built-in agent only. */
|
|
654
|
+
apiKey?: string;
|
|
655
|
+
/** Built-in agent only. */
|
|
656
|
+
llmProtocol?: string;
|
|
657
|
+
}
|
|
658
|
+
|
|
659
|
+
export interface AgentUsage {
|
|
660
|
+
inputTokens?: number;
|
|
661
|
+
outputTokens?: number;
|
|
662
|
+
costUsd?: number;
|
|
663
|
+
}
|
|
664
|
+
|
|
665
|
+
export interface AgentResult {
|
|
666
|
+
skipped?: true;
|
|
667
|
+
/** The prompt went back to the coding agent this workflow runs inside (`true`), or nowhere (`false`). */
|
|
668
|
+
handedOff?: boolean;
|
|
669
|
+
/** The agent that ran the prompt (`"built-in"` for the built-in agent). */
|
|
670
|
+
agent?: string;
|
|
671
|
+
/** The agent's final answer. */
|
|
672
|
+
result?: string | null;
|
|
673
|
+
/** The agent's session, to continue it there. */
|
|
674
|
+
sessionId?: string | null;
|
|
675
|
+
model?: string | null;
|
|
676
|
+
/** Tokens and cost, as far as the agent reports them. */
|
|
677
|
+
usage?: AgentUsage | null;
|
|
678
|
+
/** Structured output from the built-in agent. */
|
|
679
|
+
data?: JsonValue;
|
|
680
|
+
}
|
|
681
|
+
|
|
682
|
+
/** Hands a prompt to a coding agent. */
|
|
683
|
+
export function agent(prompt: string, options?: AgentOptions): Task<AgentResult>;
|
|
684
|
+
|
|
685
|
+
export interface InstallSkillOptions {
|
|
686
|
+
/** Package to install, for example `@codemod/jest-to-vitest`. */
|
|
687
|
+
package: string;
|
|
688
|
+
/** Skill source path inside the package. */
|
|
689
|
+
path?: string;
|
|
690
|
+
harness?: "auto" | "claude" | "goose" | "opencode" | "cursor" | "codex" | "antigravity";
|
|
691
|
+
scope?: "project" | "user";
|
|
692
|
+
force?: boolean;
|
|
693
|
+
}
|
|
694
|
+
|
|
695
|
+
/** Installs a package's agent skill into a coding-agent harness. */
|
|
696
|
+
export function installSkill(options: InstallSkillOptions): Task<Skippable<{ output: string }>>;
|
|
697
|
+
|
|
698
|
+
/**
|
|
699
|
+
* Waits for a person to approve. Interactive runs ask; with `--no-interactive`
|
|
700
|
+
* the run pauses here until `codemod workflow resume --id <id> --approve`.
|
|
701
|
+
*/
|
|
702
|
+
export function approval(message: string): Task<{ approved: true }>;
|
|
703
|
+
|
|
704
|
+
/** Checks out a branch for the following changes. Only with `--managed-git`. */
|
|
705
|
+
export function branch(name: string): Task<Skippable<{ branch: string }>>;
|
|
706
|
+
|
|
707
|
+
/** Commits changes. Only with `--managed-git`. */
|
|
708
|
+
export function commit(
|
|
709
|
+
message: string,
|
|
710
|
+
options?: { add?: readonly string[]; allowEmpty?: boolean },
|
|
711
|
+
): Task<Skippable<{ committed: boolean }>>;
|
|
712
|
+
|
|
713
|
+
export interface PullRequestOptions {
|
|
714
|
+
title: string;
|
|
715
|
+
body?: string;
|
|
716
|
+
draft?: boolean;
|
|
717
|
+
base?: string;
|
|
718
|
+
/** Defaults to the current branch. */
|
|
719
|
+
branch?: string;
|
|
720
|
+
}
|
|
721
|
+
|
|
722
|
+
/** Pushes the branch and opens a pull request. Only with `--managed-git`. */
|
|
723
|
+
export function pullRequest(
|
|
724
|
+
options: PullRequestOptions,
|
|
725
|
+
): Task<Skippable<{ branch: string; url: string | null }>>;
|
|
726
|
+
|
|
727
|
+
/** A finished step changed since the run was recorded, so resume cannot reuse its result. */
|
|
728
|
+
export class NondeterminismError extends Error {}
|
|
729
|
+
|
|
730
|
+
/** A step failed. */
|
|
731
|
+
export class StepError extends Error {
|
|
732
|
+
readonly label: string;
|
|
733
|
+
}
|
|
734
|
+
|
|
735
|
+
/** The run was canceled. */
|
|
736
|
+
export class CanceledError extends Error {}
|
|
737
|
+
|
|
738
|
+
/** The run is paused at an approval. */
|
|
739
|
+
export class AwaitingApprovalError extends Error {}
|
|
740
|
+
|
|
741
|
+
/**
|
|
742
|
+
* Evaluates a workflow.yaml `${{ }}` expression.
|
|
743
|
+
* @internal Emitted by `codemod workflow upgrade`; not for hand-written workflows.
|
|
744
|
+
*/
|
|
745
|
+
export function __evaluate(
|
|
746
|
+
kind: "condition" | "string" | "list",
|
|
747
|
+
expression: string,
|
|
748
|
+
scope: Readonly<Record<string, unknown>>,
|
|
749
|
+
): any;
|
|
750
|
+
}
|