codemod 2.0.0-alpha.2 → 2.0.0-alpha.3
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 +0 -1
- package/package.json +14 -12
- package/register.d.mts +2 -11
- package/register.mjs +53 -46
- package/runtime/addon.d.mts +114 -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 +49 -0
- package/runtime/context.mjs +35 -53
- package/runtime/hooks.d.mts +2 -0
- package/runtime/hooks.mjs +4 -6
- package/runtime/host.d.mts +82 -81
- package/runtime/host.mjs +383 -323
- package/runtime/llm.d.mts +2 -0
- package/runtime/llm.mjs +1 -7
- package/runtime/metrics.d.mts +9 -0
- package/runtime/metrics.mjs +31 -34
- package/runtime/modules.d.mts +3 -0
- package/runtime/modules.mjs +8 -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 +829 -607
- package/runtime/runtime.d.mts +15 -0
- package/runtime/runtime.mjs +18 -26
- package/runtime/workflow.d.mts +19 -0
- package/runtime/workflow.mjs +83 -92
- package/testing/index.d.mts +109 -155
- package/testing/index.mjs +555 -545
- package/types/langs/package.json +3 -0
- package/types/modules/workflow.d.ts +180 -15
- package/vite.d.mts +4 -21
- package/vite.mjs +23 -17
package/runtime/llm.mjs
CHANGED
|
@@ -1,11 +1,5 @@
|
|
|
1
1
|
// `codemod/llm` is not available when Node.js runs the workflow yet.
|
|
2
|
-
|
|
3
2
|
export function generate() {
|
|
4
|
-
|
|
5
|
-
new Error(
|
|
6
|
-
"codemod/llm is not available when Node.js runs the workflow; run it with the codemod CLI",
|
|
7
|
-
),
|
|
8
|
-
);
|
|
3
|
+
return Promise.reject(new Error("codemod/llm is not available when Node.js runs the workflow; run it with the codemod CLI"));
|
|
9
4
|
}
|
|
10
|
-
|
|
11
5
|
export default generate;
|
|
@@ -0,0 +1,9 @@
|
|
|
1
|
+
import type { MetricEntry } from "./context.mts";
|
|
2
|
+
declare class MetricAtom {
|
|
3
|
+
readonly name: string;
|
|
4
|
+
constructor(name: string);
|
|
5
|
+
increment(cardinality?: Record<string, unknown> | null, amount?: unknown): void;
|
|
6
|
+
getEntries(): MetricEntry[];
|
|
7
|
+
}
|
|
8
|
+
export declare function useMetricAtom(name: string): MetricAtom;
|
|
9
|
+
export { MetricAtom };
|
package/runtime/metrics.mjs
CHANGED
|
@@ -1,45 +1,42 @@
|
|
|
1
1
|
// `codemod/metrics` in Node.js and Bun. Metrics belong to the step that
|
|
2
2
|
// records them: they go into a `forEachFile` step's result and the run's
|
|
3
3
|
// report. The workflow body cannot record them, as in the engine.
|
|
4
|
-
|
|
5
4
|
import { context } from "./context.mjs";
|
|
6
|
-
|
|
7
5
|
class MetricAtom {
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
increment(cardinality = {}, amount = 1) {
|
|
13
|
-
const scope = context.getStore()?.step;
|
|
14
|
-
if (!scope) {
|
|
15
|
-
throw new Error(
|
|
16
|
-
`metric '${this.name}': metrics can only be recorded inside a step or forEachFile callback`,
|
|
17
|
-
);
|
|
6
|
+
name;
|
|
7
|
+
constructor(name) {
|
|
8
|
+
this.name = name;
|
|
18
9
|
}
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
10
|
+
increment(cardinality = {}, amount = 1) {
|
|
11
|
+
const scope = context.getStore()?.step;
|
|
12
|
+
if (!scope) {
|
|
13
|
+
throw new Error(`metric '${this.name}': metrics can only be recorded inside a step or forEachFile callback`);
|
|
14
|
+
}
|
|
15
|
+
const labels = cardinality ?? {};
|
|
16
|
+
const clean = {};
|
|
17
|
+
for (const key of Object.keys(labels).sort()) {
|
|
18
|
+
const value = labels[key];
|
|
19
|
+
if (value !== undefined && value !== null)
|
|
20
|
+
clean[key] = String(value);
|
|
21
|
+
}
|
|
22
|
+
// A whole amount of at least 0; anything that is not a number counts 1.
|
|
23
|
+
const count = typeof amount === "number" && Number.isFinite(amount) ? Math.max(0, Math.trunc(amount)) : 1;
|
|
24
|
+
const entryKey = JSON.stringify(clean);
|
|
25
|
+
let entries = scope.metrics.get(this.name);
|
|
26
|
+
if (!entries)
|
|
27
|
+
scope.metrics.set(this.name, (entries = new Map()));
|
|
28
|
+
const entry = entries.get(entryKey);
|
|
29
|
+
if (entry)
|
|
30
|
+
entry.count += count;
|
|
31
|
+
else
|
|
32
|
+
entries.set(entryKey, { cardinality: clean, count });
|
|
33
|
+
}
|
|
34
|
+
getEntries() {
|
|
35
|
+
const entries = context.getStore()?.step?.metrics.get(this.name);
|
|
36
|
+
return entries ? [...entries.values()].map((entry) => ({ ...entry })) : [];
|
|
23
37
|
}
|
|
24
|
-
// A whole amount of at least 0; anything that is not a number counts 1.
|
|
25
|
-
amount =
|
|
26
|
-
typeof amount === "number" && Number.isFinite(amount) ? Math.max(0, Math.trunc(amount)) : 1;
|
|
27
|
-
const entryKey = JSON.stringify(clean);
|
|
28
|
-
let entries = scope.metrics.get(this.name);
|
|
29
|
-
if (!entries) scope.metrics.set(this.name, (entries = new Map()));
|
|
30
|
-
const entry = entries.get(entryKey);
|
|
31
|
-
if (entry) entry.count += amount;
|
|
32
|
-
else entries.set(entryKey, { cardinality: clean, count: amount });
|
|
33
|
-
}
|
|
34
|
-
|
|
35
|
-
getEntries() {
|
|
36
|
-
const entries = context.getStore()?.step?.metrics.get(this.name);
|
|
37
|
-
return entries ? [...entries.values()].map((entry) => ({ ...entry })) : [];
|
|
38
|
-
}
|
|
39
38
|
}
|
|
40
|
-
|
|
41
39
|
export function useMetricAtom(name) {
|
|
42
|
-
|
|
40
|
+
return new MetricAtom(name);
|
|
43
41
|
}
|
|
44
|
-
|
|
45
42
|
export { MetricAtom };
|
package/runtime/modules.mjs
CHANGED
|
@@ -1,19 +1,17 @@
|
|
|
1
1
|
// The older `codemod:*` spelling of the codemod modules, and this package's
|
|
2
2
|
// Node.js implementations they resolve to. `codemod/workflow` and the rest
|
|
3
3
|
// need no mapping: they are this package's own exports.
|
|
4
|
-
|
|
4
|
+
// Paths of the built files, next to the built form of this one.
|
|
5
5
|
const MODULES = {
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
6
|
+
"codemod:workflow": "./workflow.mjs",
|
|
7
|
+
"codemod:ast-grep": "./ast-grep.mjs",
|
|
8
|
+
"codemod:metrics": "./metrics.mjs",
|
|
9
|
+
"codemod:runtime": "./runtime.mjs",
|
|
10
|
+
"codemod:llm": "./llm.mjs",
|
|
11
11
|
};
|
|
12
|
-
|
|
13
12
|
export const CODEMOD_MODULES = Object.keys(MODULES);
|
|
14
|
-
|
|
15
13
|
/** The URL an older `codemod:*` specifier resolves to, or undefined. */
|
|
16
14
|
export function resolveCodemodModule(specifier) {
|
|
17
|
-
|
|
18
|
-
|
|
15
|
+
const path = MODULES[specifier];
|
|
16
|
+
return path ? new URL(path, import.meta.url).href : undefined;
|
|
19
17
|
}
|
|
@@ -0,0 +1,261 @@
|
|
|
1
|
+
/** A JSON value: what steps record, tasks are described in, and state holds. */
|
|
2
|
+
export type Json = null | boolean | number | string | Json[] | {
|
|
3
|
+
[key: string]: Json;
|
|
4
|
+
};
|
|
5
|
+
/** `"partial"`: the step finished, but some of its files failed. */
|
|
6
|
+
export type StepStatus = "succeeded" | "partial" | "failed" | "canceled" | "awaiting-approval" | "waiting";
|
|
7
|
+
/**
|
|
8
|
+
* One step as the run store keeps it: `StepRecord` in
|
|
9
|
+
* `crates/state/src/run_store.rs`, which reads and writes this JSON.
|
|
10
|
+
*/
|
|
11
|
+
export interface StepRecord {
|
|
12
|
+
/** The step's place in the run's list of steps; it keeps it across resumes. */
|
|
13
|
+
position: number;
|
|
14
|
+
label: string;
|
|
15
|
+
/** Canonical form of the step's label and task: what makes it this step. */
|
|
16
|
+
key: string;
|
|
17
|
+
status: StepStatus;
|
|
18
|
+
result?: Json;
|
|
19
|
+
/** State the step set: keys to values, where `null` removes a key. */
|
|
20
|
+
state?: Record<string, Json> | null;
|
|
21
|
+
error?: string | null;
|
|
22
|
+
/** When a successful step finished, in milliseconds since the epoch. */
|
|
23
|
+
finishedAt?: number | null;
|
|
24
|
+
/** The order in which the run's steps finished. */
|
|
25
|
+
seq?: number | null;
|
|
26
|
+
/** The step did not run: a test gave its result. */
|
|
27
|
+
given?: boolean;
|
|
28
|
+
/** When a `sleep` or `waitForEvent` step began to wait. */
|
|
29
|
+
since?: number | null;
|
|
30
|
+
/** How many times the step ran, when retries made that more than once. */
|
|
31
|
+
attempts?: number | null;
|
|
32
|
+
}
|
|
33
|
+
/** What a step is asked to do, as the host receives it: JSON with a `kind`. */
|
|
34
|
+
export type TaskContent = {
|
|
35
|
+
kind: string;
|
|
36
|
+
} & Record<string, unknown>;
|
|
37
|
+
/** A function given to a host that runs callbacks in place. */
|
|
38
|
+
export type Callback = (...args: any[]) => unknown;
|
|
39
|
+
/** `host.start(request)`: `HostRequest` in `crates/workflow/src/run.rs`. */
|
|
40
|
+
export interface StartRequest {
|
|
41
|
+
position: number;
|
|
42
|
+
label: string;
|
|
43
|
+
task: TaskContent;
|
|
44
|
+
/** Workflow state when the step was called. */
|
|
45
|
+
state: Record<string, Json>;
|
|
46
|
+
/** The step's function, on hosts that run callbacks in place. */
|
|
47
|
+
fn?: Callback;
|
|
48
|
+
/** How long the task may run, from the step's `timeout`. */
|
|
49
|
+
timeoutMs?: number;
|
|
50
|
+
/** When the step began to wait (`sleep`, `waitForEvent`). */
|
|
51
|
+
since?: number;
|
|
52
|
+
}
|
|
53
|
+
/** What a task resolves to: `TaskOutcome` in `crates/workflow/src/tasks/mod.rs`. */
|
|
54
|
+
export interface Outcome {
|
|
55
|
+
result?: Json;
|
|
56
|
+
/** State the task set: keys to values, where `null` removes a key. */
|
|
57
|
+
state?: Record<string, Json> | null;
|
|
58
|
+
/** Set when some of the task's files failed: how many, as a message. */
|
|
59
|
+
partial?: string;
|
|
60
|
+
}
|
|
61
|
+
/** `host.event(event)`: `HostEvent` in `crates/workflow/src/run.rs`. */
|
|
62
|
+
export type StepEvent = {
|
|
63
|
+
type: "stepStarted" | "stepReplayed";
|
|
64
|
+
position: number;
|
|
65
|
+
label: string;
|
|
66
|
+
} | {
|
|
67
|
+
type: "stepRetrying";
|
|
68
|
+
position: number;
|
|
69
|
+
label: string;
|
|
70
|
+
/** The attempt that failed, counting from 1. */
|
|
71
|
+
attempt: number;
|
|
72
|
+
attempts: number;
|
|
73
|
+
error: string;
|
|
74
|
+
};
|
|
75
|
+
/** How a test runs a workflow; steps are matched by label. */
|
|
76
|
+
export interface TestPlan {
|
|
77
|
+
/** Stop after this step. */
|
|
78
|
+
until?: string;
|
|
79
|
+
/** Results for steps that should not run. */
|
|
80
|
+
given?: Record<string, Json>;
|
|
81
|
+
}
|
|
82
|
+
/** What runs the orchestrator: the engine's QuickJS context, or Node.js. */
|
|
83
|
+
export interface Host {
|
|
84
|
+
/** Steps recorded by earlier executions of the run. */
|
|
85
|
+
history(): StepRecord[];
|
|
86
|
+
/** Persist one step's outcome; `ms` is how long it took. */
|
|
87
|
+
record(entry: StepRecord, ms: number): void;
|
|
88
|
+
event(event: StepEvent): void;
|
|
89
|
+
/** Whether a step about to start must not, because the run was asked to stop. */
|
|
90
|
+
canceled(): boolean;
|
|
91
|
+
/** Run a task. Rejects with `{ name, message }`. */
|
|
92
|
+
start(request: StartRequest): Promise<Outcome>;
|
|
93
|
+
/** Evaluate a workflow.yaml `${{ }}` expression. */
|
|
94
|
+
evaluate(kind: string, expression: string, scope: unknown): unknown;
|
|
95
|
+
/** The real time, for step records. */
|
|
96
|
+
now(): number;
|
|
97
|
+
/** Move the body's clock forward. */
|
|
98
|
+
advanceClock(ms: number): void;
|
|
99
|
+
/** `{ until?, given? }` when the run is a test. */
|
|
100
|
+
testPlan(): TestPlan | null;
|
|
101
|
+
/** The test's `until` step has started. */
|
|
102
|
+
stop(): void;
|
|
103
|
+
/** A replayed step waits for `replayNext()`. */
|
|
104
|
+
wake?(): void;
|
|
105
|
+
/**
|
|
106
|
+
* Identifies a callback given as a function. Hosts without it need the
|
|
107
|
+
* build to extract callbacks.
|
|
108
|
+
*/
|
|
109
|
+
callbackId?(fn: Callback): string;
|
|
110
|
+
}
|
|
111
|
+
export declare class StepError extends Error {
|
|
112
|
+
readonly label: string;
|
|
113
|
+
constructor(label: string, cause: unknown);
|
|
114
|
+
}
|
|
115
|
+
export declare class CanceledError extends Error {
|
|
116
|
+
constructor(message?: string);
|
|
117
|
+
}
|
|
118
|
+
export declare class AwaitingApprovalError extends Error {
|
|
119
|
+
constructor(message?: string);
|
|
120
|
+
}
|
|
121
|
+
declare const TASK: unique symbol;
|
|
122
|
+
/** The files a `forEachFile` step visits, as the engine receives it. */
|
|
123
|
+
export interface Selector {
|
|
124
|
+
include: string[];
|
|
125
|
+
exclude: string[];
|
|
126
|
+
language?: string;
|
|
127
|
+
containing?: string;
|
|
128
|
+
concurrency?: number;
|
|
129
|
+
}
|
|
130
|
+
/** A callback the build extracted, or one given as a function. */
|
|
131
|
+
export interface Extracted {
|
|
132
|
+
id: string;
|
|
133
|
+
/** The outside values an extracted callback uses, read when its step is called. */
|
|
134
|
+
captures?: () => Json;
|
|
135
|
+
fn?: Callback;
|
|
136
|
+
}
|
|
137
|
+
/** What the build puts in place of an extracted callback. */
|
|
138
|
+
export interface CallbackReference {
|
|
139
|
+
__flowCallback: string;
|
|
140
|
+
captures: () => Json;
|
|
141
|
+
}
|
|
142
|
+
export interface ForEachFileTask {
|
|
143
|
+
readonly [TASK]: "forEachFile";
|
|
144
|
+
readonly selector: Selector;
|
|
145
|
+
readonly callback: Extracted;
|
|
146
|
+
}
|
|
147
|
+
export interface HostTask {
|
|
148
|
+
readonly [TASK]: "host";
|
|
149
|
+
readonly content: TaskContent;
|
|
150
|
+
}
|
|
151
|
+
export type Task = ForEachFileTask | HostTask;
|
|
152
|
+
/** A length of time: milliseconds, or a string such as "30s" or "10m". */
|
|
153
|
+
export type Duration = number | string;
|
|
154
|
+
/** `step(..., options)`: how to run a step. */
|
|
155
|
+
export interface StepOptions {
|
|
156
|
+
retries?: number;
|
|
157
|
+
retryDelay?: Duration;
|
|
158
|
+
timeout?: Duration;
|
|
159
|
+
}
|
|
160
|
+
/**
|
|
161
|
+
* The task builders (`forEachFile`, `shell`, `jssg`, ...). They only describe
|
|
162
|
+
* work, so they need no run. `options.callbackId(fn)` lets callbacks be given
|
|
163
|
+
* as functions, for hosts that run them in place.
|
|
164
|
+
*/
|
|
165
|
+
export declare function createTasks(options?: Pick<Host, "callbackId">): {
|
|
166
|
+
callbackOf: (value: unknown) => Extracted | null;
|
|
167
|
+
__callback: (id: string, captures: () => Json) => CallbackReference;
|
|
168
|
+
forEachFile: (selector: unknown, callback?: unknown) => ForEachFileTask | HostTask;
|
|
169
|
+
shell: (command: unknown, ...rest: unknown[]) => HostTask | ShellTag;
|
|
170
|
+
jssg: (path: string, options?: object) => HostTask;
|
|
171
|
+
astGrep: (path: string, options?: object) => HostTask;
|
|
172
|
+
shard: (options: object) => HostTask;
|
|
173
|
+
codemod: (source: string, options?: object) => HostTask;
|
|
174
|
+
agent: (prompt: string, options?: object) => HostTask;
|
|
175
|
+
installSkill: (options: object) => HostTask;
|
|
176
|
+
approval: (message: string) => HostTask;
|
|
177
|
+
sleep: (duration: Duration) => HostTask;
|
|
178
|
+
waitForEvent: (name: string, options?: {
|
|
179
|
+
timeout?: Duration;
|
|
180
|
+
}) => HostTask;
|
|
181
|
+
branch: (name: string) => HostTask;
|
|
182
|
+
commit: (message: string, options?: object) => HostTask;
|
|
183
|
+
pullRequest: (options: object) => HostTask;
|
|
184
|
+
};
|
|
185
|
+
/** A duration in milliseconds, from a number of them or a string such as "30s". */
|
|
186
|
+
export declare function milliseconds(value: unknown, what: string): number;
|
|
187
|
+
/** A duration in its largest whole unit, as the engine words it. */
|
|
188
|
+
export declare function describeDuration(ms: number): string;
|
|
189
|
+
/** What `createRuntime` returns: `codemod/workflow` for one run, and what its host drives. */
|
|
190
|
+
export type Runtime = ReturnType<typeof createRuntime>;
|
|
191
|
+
/** A tag made by `shell(options)`. */
|
|
192
|
+
type ShellTag = (strings: TemplateStringsArray, ...values: unknown[]) => HostTask;
|
|
193
|
+
export declare function createRuntime(host: Host): {
|
|
194
|
+
getState: (key?: string) => Json | undefined | Readonly<Record<string, Json>>;
|
|
195
|
+
setState: (key: string, value: unknown) => void;
|
|
196
|
+
unsetState: (key: string) => void;
|
|
197
|
+
acquireLock: (_name: string) => () => void;
|
|
198
|
+
setStepOutput: (name: string, value: unknown) => void;
|
|
199
|
+
getStepOutput: (stepId: string, name: string) => string | null;
|
|
200
|
+
getOrSetStepOutput: (stepId: string, name: string, value: unknown) => string;
|
|
201
|
+
__evaluate: (kind: string, expression: string, scope: unknown) => unknown;
|
|
202
|
+
step: (...args: unknown[]) => Promise<Json>;
|
|
203
|
+
sleep: (duration: Duration) => Promise<Json>;
|
|
204
|
+
waitForEvent: (name: string, options?: {
|
|
205
|
+
timeout?: Duration;
|
|
206
|
+
}) => Promise<Json>;
|
|
207
|
+
replayNext: () => boolean;
|
|
208
|
+
close: () => void;
|
|
209
|
+
isClosed: () => boolean;
|
|
210
|
+
__callback: (id: string, captures: () => Json) => CallbackReference;
|
|
211
|
+
forEachFile: (selector: unknown, callback?: unknown) => ForEachFileTask | HostTask;
|
|
212
|
+
shell: (command: unknown, ...rest: unknown[]) => HostTask | ShellTag;
|
|
213
|
+
jssg: (path: string, options?: object) => HostTask;
|
|
214
|
+
astGrep: (path: string, options?: object) => HostTask;
|
|
215
|
+
shard: (options: object) => HostTask;
|
|
216
|
+
codemod: (source: string, options?: object) => HostTask;
|
|
217
|
+
agent: (prompt: string, options?: object) => HostTask;
|
|
218
|
+
installSkill: (options: object) => HostTask;
|
|
219
|
+
approval: (message: string) => HostTask;
|
|
220
|
+
branch: (name: string) => HostTask;
|
|
221
|
+
commit: (message: string, options?: object) => HostTask;
|
|
222
|
+
pullRequest: (options: object) => HostTask;
|
|
223
|
+
};
|
|
224
|
+
/** Freeze a JSON value, all the way down. */
|
|
225
|
+
export declare function freeze<T>(value: T): T;
|
|
226
|
+
/**
|
|
227
|
+
* An error as a step's failure says it. Changing a captured value or a step
|
|
228
|
+
* result fails as a TypeError that does not say why; the hint does.
|
|
229
|
+
*/
|
|
230
|
+
export declare function describeError(error: unknown): string;
|
|
231
|
+
/** What a `forEachFile` callback did to its file. */
|
|
232
|
+
export type FileEffect = {
|
|
233
|
+
op: "write";
|
|
234
|
+
text: string;
|
|
235
|
+
} | {
|
|
236
|
+
op: "rename";
|
|
237
|
+
to: string;
|
|
238
|
+
} | {
|
|
239
|
+
op: "delete";
|
|
240
|
+
};
|
|
241
|
+
/** The `file` a `forEachFile` callback gets. */
|
|
242
|
+
export interface WorkflowFile {
|
|
243
|
+
readonly path: string;
|
|
244
|
+
readonly text: string;
|
|
245
|
+
readonly language: string | undefined;
|
|
246
|
+
write(text: string): void;
|
|
247
|
+
rename(to: string): void;
|
|
248
|
+
delete(): void;
|
|
249
|
+
}
|
|
250
|
+
/**
|
|
251
|
+
* The `file` a `forEachFile` callback gets, and the effects it records on it.
|
|
252
|
+
* After `close()`, when the callback has finished, the file takes no more.
|
|
253
|
+
*/
|
|
254
|
+
export declare function fileHandle(path: string, text: string, language?: string): {
|
|
255
|
+
file: WorkflowFile;
|
|
256
|
+
effects: FileEffect[];
|
|
257
|
+
close(): void;
|
|
258
|
+
};
|
|
259
|
+
/** Throw a TypeError naming the first part of `value` that is not JSON. */
|
|
260
|
+
export declare function checkJson(value: unknown, path: string, seen?: Set<object>): asserts value is Json;
|
|
261
|
+
export {};
|