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,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
+ }