codemod 2.0.0-alpha.2 → 2.0.0-alpha.4

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.
@@ -1,204 +1,17 @@
1
- // oxlint-disable triple-slash-reference
2
- /// <reference path="./metrics.d.ts" />
1
+ /**
2
+ * In a workflow, as in Node.js: where the workflow file is, also inside its
3
+ * steps and `forEachFile` callbacks.
4
+ */
5
+ interface ImportMeta {
6
+ /** The directory the workflow file is in. */
7
+ dirname: string;
8
+ /** The workflow file. */
9
+ filename: string;
10
+ /** The workflow file, as a `file:` URL. */
11
+ url: string;
12
+ }
3
13
 
4
14
  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
15
  // ── Shard function types ────────────────────────────────────────────────
203
16
 
204
17
  /**
@@ -238,9 +51,9 @@ declare module "codemod:workflow" {
238
51
 
239
52
  // ── Workflow authoring (workflow.ts) ───────────────────────────────────
240
53
  //
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.
54
+ // Everything below is used from a workflow file. Workflows have no state:
55
+ // a step gets values from the body (a function step's captured variables,
56
+ // jssg `params`, shell `env`) and returns what it found on its result.
244
57
  //
245
58
  // Code inside `step(() => ...)` and `forEachFile(...)` callbacks runs in
246
59
  // its own isolate, with every module the run allows (`fs`, `fetch` and
@@ -249,9 +62,7 @@ declare module "codemod:workflow" {
249
62
  // `crypto.randomUUID` are replay-safe, and modules that read files, the
250
63
  // network, the environment or the clock are build errors.
251
64
 
252
- import type { MetricEntry } from "codemod:metrics";
253
-
254
- /** A JSON value: what step results, captured variables and state may hold. */
65
+ /** A JSON value: what step results and captured variables may hold. */
255
66
  export type JsonValue =
256
67
  | string
257
68
  | number
@@ -300,11 +111,21 @@ declare module "codemod:workflow" {
300
111
 
301
112
  const taskResult: unique symbol;
302
113
 
303
- /** Work for `step()` to run, made by `forEachFile` or a task such as `jssg`. */
114
+ /** Work for `step()` to run, made by `forEachFile` or a task such as `shell`. */
304
115
  export interface Task<Result> {
305
116
  readonly [taskResult]: Result;
306
117
  }
307
118
 
119
+ const transformResult: unique symbol;
120
+
121
+ /**
122
+ * A transform for single files, made by `jssg` or `astGrep`. Give it to
123
+ * `forEachFile` to say which files it runs on.
124
+ */
125
+ export interface Transform<Result> extends Task<Result> {
126
+ readonly [transformResult]: Result;
127
+ }
128
+
308
129
  /** What the workflow's default export receives. */
309
130
  export interface WorkflowContext<Params = Record<string, unknown>> {
310
131
  /** `--param key=value` values (JSON when they parse as JSON, otherwise strings). */
@@ -315,6 +136,32 @@ declare module "codemod:workflow" {
315
136
  dryRun: boolean;
316
137
  }
317
138
 
139
+ /**
140
+ * A length of time: a number of milliseconds, or a number with a unit,
141
+ * such as `"500ms"`, `"30s"`, `"10m"`, `"1h"` or `"2d"`.
142
+ */
143
+ export type Duration = number | `${number}${"ms" | "s" | "m" | "h" | "d"}`;
144
+
145
+ /**
146
+ * How a step is run. These do not identify the step: changing them does
147
+ * not make a finished step run again on resume.
148
+ */
149
+ export interface StepOptions {
150
+ /**
151
+ * Runs the step again when it fails, up to this many more times. The
152
+ * run sees only the last failure. Default: 0.
153
+ */
154
+ retries?: number;
155
+ /** How long to wait before each retry. Default: `"1s"`. */
156
+ retryDelay?: Duration;
157
+ /**
158
+ * Stops the step, and fails it, when one attempt takes longer than
159
+ * this: commands are terminated and file changes not yet written are
160
+ * dropped.
161
+ */
162
+ timeout?: Duration;
163
+ }
164
+
318
165
  /**
319
166
  * Runs a task as a durable step and resolves to its frozen result.
320
167
  *
@@ -327,10 +174,15 @@ declare module "codemod:workflow" {
327
174
  * const renamed = await step("Rename stylesheets", forEachFile("src/**\/*.less", (file) => {
328
175
  * file.rename(file.path.replace(/\.less$/, ".css"));
329
176
  * }));
177
+ * await step("Install", shell("pnpm install"), { retries: 2, timeout: "10m" });
330
178
  * ```
331
179
  */
332
- export function step<Result>(task: Task<Result>): Promise<Frozen<Result>>;
333
- export function step<Result>(label: string, task: Task<Result>): Promise<Frozen<Result>>;
180
+ export function step<Result>(task: Task<Result>, options?: StepOptions): Promise<Frozen<Result>>;
181
+ export function step<Result>(
182
+ label: string,
183
+ task: Task<Result>,
184
+ options?: StepOptions,
185
+ ): Promise<Frozen<Result>>;
334
186
  /**
335
187
  * Runs a function once, in its own isolate, and records its result, which
336
188
  * must be JSON. Write it inline: outside variables arrive as frozen copies,
@@ -339,17 +191,54 @@ declare module "codemod:workflow" {
339
191
  */
340
192
  export function step<Result>(
341
193
  run: () => PromiseLike<Checked<Result>>,
194
+ options?: StepOptions,
342
195
  ): Promise<Frozen<StepValue<Result>>>;
343
196
  export function step<Result>(
344
197
  label: string,
345
198
  run: () => PromiseLike<Checked<Result>>,
199
+ options?: StepOptions,
200
+ ): Promise<Frozen<StepValue<Result>>>;
201
+ export function step<Result>(
202
+ run: () => Checked<Result>,
203
+ options?: StepOptions,
346
204
  ): Promise<Frozen<StepValue<Result>>>;
347
- export function step<Result>(run: () => Checked<Result>): Promise<Frozen<StepValue<Result>>>;
348
205
  export function step<Result>(
349
206
  label: string,
350
207
  run: () => Checked<Result>,
208
+ options?: StepOptions,
351
209
  ): Promise<Frozen<StepValue<Result>>>;
352
210
 
211
+ /**
212
+ * Waits, as a step. The wait counts from when it began: a run that is
213
+ * interrupted and resumed waits only for what is left. A dry run does not
214
+ * wait.
215
+ *
216
+ * @example
217
+ * ```ts
218
+ * await sleep("30s");
219
+ * ```
220
+ */
221
+ export function sleep(duration: Duration): Promise<null>;
222
+
223
+ /**
224
+ * Waits, as a step, for an event sent to the run with
225
+ * `codemod workflow send <name> --id <run-id> [--data <json>]`, and
226
+ * resolves to its data (`null` when none was given). An event sent before
227
+ * the workflow gets here is kept for it. With `timeout`, the step fails if
228
+ * no event comes in that time, counted from when the wait began.
229
+ *
230
+ * A dry run is not saved and cannot be sent events, so the step fails there.
231
+ *
232
+ * @example
233
+ * ```ts
234
+ * const ci = await waitForEvent<{ passed: boolean }>("ci-finished", { timeout: "1h" });
235
+ * ```
236
+ */
237
+ export function waitForEvent<Data = JsonValue>(
238
+ name: string,
239
+ options?: { timeout?: Duration },
240
+ ): Promise<Frozen<Data>>;
241
+
353
242
  /**
354
243
  * `T`, checked to be JSON: `Result` is inferred from the value, which must
355
244
  * then also be assignable to its JSON-compatible form.
@@ -439,10 +328,11 @@ declare module "codemod:workflow" {
439
328
  /** What the callback returned, in path order. Files that returned nothing are left out. */
440
329
  outputs: Output[];
441
330
  changes: FileChanges;
442
- /** Files whose callback threw. */
331
+ /**
332
+ * Files whose callback threw. With some, the step is partial; when the
333
+ * callback throws on every file, the step fails instead.
334
+ */
443
335
  failures: FileFailure[];
444
- /** What callbacks recorded with `codemod/metrics`, by metric name. */
445
- metrics: Record<string, MetricEntry[]>;
446
336
  }
447
337
 
448
338
  /**
@@ -451,8 +341,8 @@ declare module "codemod:workflow" {
451
341
  *
452
342
  * Write the callback inline. Variables from outside it arrive as frozen
453
343
  * 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.
344
+ * (`codemod/ast-grep`, packages, files next to the workflow) are
345
+ * available inside.
456
346
  *
457
347
  * @example
458
348
  * ```ts
@@ -482,10 +372,207 @@ declare module "codemod:workflow" {
482
372
  ): Task<ForEachFileResult<Exclude<Output, void | undefined>>>;
483
373
 
484
374
  /**
485
- * Returns the whole workflow state as a frozen object.
486
- * (With a key, see the `getState(name)` overload above.)
375
+ * Which files `forEachFile` runs a `jssg` transform on: a glob, a list of
376
+ * globs, or an object. `language` is the language the files are parsed as
377
+ * and, without `include`, selects that language's file extensions. Without
378
+ * a `language`, the package's is used (`targets.languages` in codemod.yaml,
379
+ * when it lists one), and otherwise `typescript`.
380
+ */
381
+ export type JssgSelector = Globs | { include?: Globs; exclude?: Globs; language?: string };
382
+
383
+ /**
384
+ * Which files `forEachFile` applies `astGrep` rules to: a glob, a list of
385
+ * globs, or an object. Without `include`, the files of the rules' languages.
487
386
  */
488
- export function getState(): Readonly<Record<string, JsonValue>>;
387
+ export type AstGrepSelector = Globs | { include?: Globs; exclude?: Globs };
388
+
389
+ /**
390
+ * Runs a JSSG transform, or applies an ast-grep rule file, on every
391
+ * selected file. The selector's fields stand for the same options of
392
+ * `jssg` and `astGrep`, so give each in one place.
393
+ *
394
+ * @example
395
+ * ```ts
396
+ * await step("Migrate imports", forEachFile(jssg("scripts/codemod.ts")));
397
+ * await step("Apply rules", forEachFile("src/**\/*.ts", astGrep("rules/config.yml")));
398
+ * await step("Migrate components", forEachFile(
399
+ * { include: "src/**\/*.tsx", exclude: "**\/*.test.tsx", language: "tsx" },
400
+ * jssg("scripts/components.ts", { params: { strict: true } }),
401
+ * ));
402
+ * ```
403
+ */
404
+ export function forEachFile<Data>(transform: Transform<JssgResult<Data>>): Task<JssgResult<Data>>;
405
+ export function forEachFile<Data>(
406
+ selector: JssgSelector,
407
+ transform: Transform<JssgResult<Data>>,
408
+ ): Task<JssgResult<Data>>;
409
+ export function forEachFile(transform: Transform<AstGrepResult>): Task<AstGrepResult>;
410
+ export function forEachFile(
411
+ selector: AstGrepSelector,
412
+ transform: Transform<AstGrepResult>,
413
+ ): Task<AstGrepResult>;
414
+
415
+ // ---------------------------------------------------------- dependencies ---
416
+
417
+ export type Ecosystem = "npm" | "cargo";
418
+ export type DependencyKind = "prod" | "dev" | "peer" | "optional" | "build";
419
+ export type KindsOption = { kinds?: DependencyKind | readonly DependencyKind[] };
420
+
421
+ /** A `name@version` the lockfiles install, or one of the repository's own packages. */
422
+ export interface PackageNode {
423
+ readonly ecosystem: Ecosystem;
424
+ readonly name: string;
425
+ readonly version: string;
426
+ /** Directory of one of the repository's own packages; null for third-party packages. */
427
+ readonly workspace: string | null;
428
+ readonly isWorkspace: boolean;
429
+ /** Edges this node declares. */
430
+ dependencies(options?: KindsOption): DependencyEdge[];
431
+ /** Edges installed onto this exact node. */
432
+ dependents(options?: KindsOption): DependencyEdge[];
433
+ /** Each workspace that reaches this node, with its shortest chain (workspace first, this node last). */
434
+ workspacesReaching(options?: KindsOption): { workspace: PackageNode; chain: PackageNode[] }[];
435
+ /**
436
+ * This package's releases from the registry, oldest first, each with
437
+ * `breaking` relative to this node's version. Yanked releases are dropped.
438
+ */
439
+ releases(options?: {
440
+ /** `{ react: "19.0.0" }` keeps releases whose ranges on react accept 19.0.0. */
441
+ accepting?: Record<string, string>;
442
+ newerThanMine?: boolean;
443
+ prereleases?: boolean;
444
+ }): Promise<(Release & { breaking: boolean })[]>;
445
+ /** `name@version`, which is also what the node becomes in a step's result. */
446
+ toString(): string;
447
+ }
448
+
449
+ /** One declared dependency. */
450
+ export interface DependencyEdge {
451
+ readonly from: PackageNode;
452
+ /** The installed node; null for peer edges and ranges the lockfile does not resolve. */
453
+ readonly to: PackageNode | null;
454
+ readonly name: string;
455
+ /** Declared range; null when the lockfile keeps none (third-party crates in Cargo.lock). */
456
+ readonly range: string | null;
457
+ readonly kind: DependencyKind;
458
+ /** Whether the declared range accepts `version`; null when it cannot tell. */
459
+ accepts(version: string): boolean | null;
460
+ }
461
+
462
+ /** What an edge becomes in a step's result. */
463
+ export interface RecordedEdge {
464
+ from: string;
465
+ /** `name@version`, or the bare name when the edge does not resolve. */
466
+ to: string;
467
+ kind: DependencyKind;
468
+ range: string | null;
469
+ }
470
+
471
+ /** A `dependencyGraph` result as recorded: nodes become `name@version`, edges `RecordedEdge`. */
472
+ export type Recorded<T> = T extends PackageNode
473
+ ? string
474
+ : T extends DependencyEdge
475
+ ? RecordedEdge
476
+ : T extends (...args: never[]) => unknown
477
+ ? T
478
+ : T extends readonly (infer U)[]
479
+ ? Recorded<U>[]
480
+ : T extends object
481
+ ? { [K in keyof T]: Recorded<T[K]> }
482
+ : T;
483
+
484
+ /**
485
+ * The repository's lockfiles as a live graph. It is only valid inside the
486
+ * `dependencyGraph` callback; only what the callback returns is recorded.
487
+ */
488
+ export interface DependencyGraph {
489
+ /** Lockfiles read, relative to the target. */
490
+ readonly lockfiles: readonly string[];
491
+ /**
492
+ * Lockfiles found but not read, with why. Without a `lockfiles` option,
493
+ * one that cannot be read (a Yarn v1 lockfile in an example, say) is
494
+ * left out instead of failing the step.
495
+ */
496
+ readonly skipped: readonly { readonly lockfile: string; readonly error: string }[];
497
+ /** The repository's own packages. */
498
+ workspaces(): PackageNode[];
499
+ /** Every node, or every installed version of `name`. */
500
+ nodes(name?: string): PackageNode[];
501
+ /** One node by name, and by version when several are installed. */
502
+ node(name: string, version?: string): PackageNode | undefined;
503
+ /** Edges that declare a dependency on `name`, resolved or not (peer edges never resolve). */
504
+ dependents(name: string, options?: KindsOption): DependencyEdge[];
505
+ /** Shortest chains from each `from` node (default: every workspace) to any `to` node. */
506
+ chains(options: {
507
+ from?: PackageNode | readonly PackageNode[];
508
+ to: PackageNode | readonly PackageNode[];
509
+ kinds?: DependencyKind | readonly DependencyKind[];
510
+ }): PackageNode[][];
511
+ }
512
+
513
+ /**
514
+ * Reads the target's lockfiles (yarn.lock, pnpm-lock.yaml, package-lock.json,
515
+ * Cargo.lock; default: any of them) into a graph and runs `callback` on it in
516
+ * its own isolate, where it may await `registry` lookups. Nodes and edges in
517
+ * the result are recorded as `name@version` text and `RecordedEdge`.
518
+ *
519
+ * @example
520
+ * ```ts
521
+ * const muiUsers = await step(dependencyGraph({ lockfiles: "yarn.lock" }, (g) =>
522
+ * g.dependents("@material-ui/core", { kinds: "prod" })
523
+ * .filter((edge) => edge.from.isWorkspace)
524
+ * .map((edge) => edge.from.workspace),
525
+ * ));
526
+ * ```
527
+ */
528
+ export function dependencyGraph<Output>(
529
+ options: { lockfiles?: Globs },
530
+ callback: (graph: DependencyGraph) => Output | PromiseLike<Output>,
531
+ ): Task<Recorded<Awaited<Output>>>;
532
+
533
+ export interface Release {
534
+ version: string;
535
+ yanked: boolean;
536
+ prerelease: boolean;
537
+ dependencies: Record<string, string>;
538
+ peerDependencies: Record<string, string>;
539
+ optionalDependencies: Record<string, string>;
540
+ /** cargo only. */
541
+ buildDependencies?: Record<string, string>;
542
+ /** cargo only. */
543
+ devDependencies?: Record<string, string>;
544
+ }
545
+
546
+ export interface PackageReleases {
547
+ ecosystem: Ecosystem;
548
+ name: string;
549
+ /** Oldest first. Empty when the registry does not know the package. */
550
+ versions: Release[];
551
+ }
552
+
553
+ /**
554
+ * Release metadata from npm and crates.io. Usable inside a function step or
555
+ * a `forEachFile` / `dependencyGraph` callback, so the answer is recorded
556
+ * with the step; in the workflow body it rejects. Lookups are cached for the
557
+ * run and asked once per package.
558
+ */
559
+ export const registry: {
560
+ npm(name: string): Promise<PackageReleases>;
561
+ cargo(name: string): Promise<PackageReleases>;
562
+ };
563
+
564
+ type EcosystemOption = { ecosystem?: Ecosystem };
565
+ /** Version comparison with npm rules, or Cargo's with `{ ecosystem: "cargo" }`. */
566
+ export const semver: {
567
+ /** true, false, or null when the range cannot be read (`workspace:`, `git:` ...). */
568
+ satisfies(version: string, range: string, options?: EcosystemOption): boolean | null;
569
+ compare(a: string, b: string, options?: EcosystemOption): -1 | 0 | 1;
570
+ gt(a: string, b: string, options?: EcosystemOption): boolean;
571
+ lt(a: string, b: string, options?: EcosystemOption): boolean;
572
+ /** Whether `from` to `to` changes the left-most non-zero component (0.29 to 0.30 is breaking). */
573
+ isBreaking(from: string, to: string, options?: EcosystemOption): boolean;
574
+ isPrerelease(version: string, options?: EcosystemOption): boolean;
575
+ };
489
576
 
490
577
  /**
491
578
  * A result for tasks that do nothing in some runs: shell commands, agents
@@ -500,17 +587,52 @@ declare module "codemod:workflow" {
500
587
  env?: Readonly<Record<string, string>>;
501
588
  /** Directory to run in, relative to the target (or absolute). Defaults to the current directory. */
502
589
  cwd?: string;
590
+ /** Return the result of a command that exits with an error, instead of failing the step. */
591
+ allowFailure?: boolean;
503
592
  }
504
593
 
594
+ /** What a command printed, as text (the last 1 MiB of each), and how it exited. */
595
+ export interface ShellResult {
596
+ stdout: string;
597
+ stderr: string;
598
+ /** 0, unless `allowFailure` is set; -1 when a signal ended the command. */
599
+ exitCode: number;
600
+ }
601
+
602
+ /** A value in a `shell` template: quoted as one word, or one word per item. */
603
+ export type ShellValue = string | number | boolean | readonly (string | number | boolean)[];
604
+
605
+ export type ShellTask = Task<Skippable<ShellResult>>;
606
+
505
607
  /**
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`.
608
+ * Runs a shell command. It gets values through `env`; the workflow parses
609
+ * what it needs from what the command prints. A command that exits with
610
+ * an error fails the step, unless `allowFailure` is set.
611
+ *
612
+ * @example
613
+ * await step("Install", shell("npm install"));
614
+ * const { stdout } = await step("Detect", shell(`echo '{"major":19}'`));
615
+ * JSON.parse(stdout); // { major: 19 }
616
+ */
617
+ export function shell(command: string, options?: ShellOptions): ShellTask;
618
+ /**
619
+ * Runs a shell command written as a template. Each value is quoted for the
620
+ * shell, so a path with spaces stays one argument; the text around them is
621
+ * taken as written, backslashes included.
622
+ *
623
+ * @example
624
+ * await step("Find uses", shell`grep -rn ${name} src`);
625
+ */
626
+ export function shell(strings: TemplateStringsArray, ...values: ShellValue[]): ShellTask;
627
+ /**
628
+ * Options for a command written as a template.
629
+ *
630
+ * @example
631
+ * await step("Build", shell({ cwd: "packages/app" })`npm run build`);
509
632
  */
510
633
  export function shell(
511
- command: string,
512
- options?: ShellOptions,
513
- ): Task<Skippable<{ output: string }>>;
634
+ options: ShellOptions,
635
+ ): (strings: TemplateStringsArray, ...values: ShellValue[]) => ShellTask;
514
636
 
515
637
  export type Capability = "fs" | "fetch" | "child_process";
516
638
 
@@ -543,14 +665,45 @@ declare module "codemod:workflow" {
543
665
  dryRun?: boolean;
544
666
  }
545
667
 
546
- export interface JssgResult {
668
+ /** One file's `data`, as the transform returned it. */
669
+ export interface JssgData {
670
+ file: string;
671
+ data: JsonValue;
672
+ }
673
+
674
+ export interface JssgResult<Data = readonly JssgData[]> {
547
675
  changes: FileChanges;
548
676
  unmodified: number;
549
677
  failures: FileFailure[];
678
+ /**
679
+ * Each file's `data`, sorted by path, leaving out files that returned
680
+ * none; or, with a reducer, what it folded them into.
681
+ */
682
+ data: Data;
550
683
  }
551
684
 
552
- /** Runs a JSSG transform file. `path` is relative to the workflow file. */
553
- export function jssg(path: string, options?: JssgOptions): Task<JssgResult>;
685
+ /**
686
+ * Folds each file's `data` into one value as the file finishes, so the
687
+ * step never holds every file's data at once. Files arrive in no
688
+ * particular order. Write `reduce` inline so the build can extract it.
689
+ */
690
+ export interface JssgReducer<T> {
691
+ reduce: (result: T, entry: JssgData) => T | Promise<T>;
692
+ initial: T;
693
+ }
694
+
695
+ /**
696
+ * A JSSG transform file; `path` is relative to the workflow file. Run it
697
+ * with `forEachFile(selector, jssg(path))`, which says which files it is
698
+ * for. As a step on its own it runs on the files its options select.
699
+ */
700
+ // `T` is unconstrained so `initial: 0` gives `number`, not `0`; the
701
+ // result is checked to be JSON when the step runs.
702
+ export function jssg<T>(
703
+ path: string,
704
+ options: JssgOptions & JssgReducer<T>,
705
+ ): Transform<JssgResult<T>>;
706
+ export function jssg(path: string, options?: JssgOptions): Transform<JssgResult>;
554
707
 
555
708
  export interface AstGrepOptions {
556
709
  include?: Globs;
@@ -565,8 +718,13 @@ declare module "codemod:workflow" {
565
718
  failures: FileFailure[];
566
719
  }
567
720
 
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>;
721
+ /**
722
+ * An ast-grep YAML rule file; `path` is relative to the workflow file.
723
+ * Apply it with `forEachFile(selector, astGrep(path))`, which says which
724
+ * files it is for. As a step on its own it runs on the files its options
725
+ * select.
726
+ */
727
+ export function astGrep(path: string, options?: AstGrepOptions): Transform<AstGrepResult>;
570
728
 
571
729
  export type ShardMethod =
572
730
  | {
@@ -724,9 +882,6 @@ declare module "codemod:workflow" {
724
882
  options: PullRequestOptions,
725
883
  ): Task<Skippable<{ branch: string; url: string | null }>>;
726
884
 
727
- /** A finished step changed since the run was recorded, so resume cannot reuse its result. */
728
- export class NondeterminismError extends Error {}
729
-
730
885
  /** A step failed. */
731
886
  export class StepError extends Error {
732
887
  readonly label: string;