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.
- package/README.md +1 -2
- package/package.json +14 -16
- package/register.d.mts +2 -11
- package/register.mjs +53 -46
- package/runtime/addon.d.mts +119 -0
- package/runtime/addon.mjs +36 -40
- package/runtime/ast-grep.d.mts +20 -0
- package/runtime/ast-grep.mjs +50 -61
- package/runtime/context.d.mts +25 -0
- package/runtime/context.mjs +10 -64
- package/runtime/hooks.d.mts +2 -0
- package/runtime/hooks.mjs +4 -6
- package/runtime/host.d.mts +81 -81
- package/runtime/host.mjs +428 -326
- package/runtime/llm.d.mts +2 -0
- package/runtime/llm.mjs +1 -7
- package/runtime/modules.d.mts +3 -0
- package/runtime/modules.mjs +7 -10
- package/runtime/orchestrator-version.d.mts +2 -0
- package/runtime/orchestrator-version.mjs +3 -0
- package/runtime/orchestrator.d.mts +261 -0
- package/runtime/orchestrator.mjs +823 -608
- package/runtime/runtime.d.mts +15 -0
- package/runtime/runtime.mjs +18 -26
- package/runtime/workflow.d.mts +24 -0
- package/runtime/workflow.mjs +42 -121
- package/testing/index.d.mts +107 -155
- package/testing/index.mjs +552 -545
- package/types/index.d.ts +0 -1
- package/types/langs/package.json +3 -0
- package/types/modules/ast-grep.d.ts +22 -1
- package/types/modules/workflow.d.ts +386 -231
- package/vite.d.mts +4 -21
- package/vite.mjs +23 -17
- package/runtime/metrics.mjs +0 -45
- package/types/metrics.d.ts +0 -5
- package/types/modules/metrics.d.ts +0 -107
|
@@ -1,204 +1,17 @@
|
|
|
1
|
-
|
|
2
|
-
|
|
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.
|
|
242
|
-
//
|
|
243
|
-
//
|
|
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
|
-
|
|
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 `
|
|
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
|
|
333
|
-
export function step<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
|
-
/**
|
|
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`,
|
|
455
|
-
*
|
|
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
|
-
*
|
|
486
|
-
*
|
|
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
|
|
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
|
|
507
|
-
*
|
|
508
|
-
*
|
|
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
|
-
|
|
512
|
-
|
|
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
|
-
|
|
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
|
-
/**
|
|
553
|
-
|
|
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
|
-
/**
|
|
569
|
-
|
|
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;
|