codemod 2.0.0-alpha.3 → 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.
@@ -98,7 +98,27 @@ export function createTasks(options = {}) {
98
98
  // Without a language, the package's (codemod.yaml), as for callbacks.
99
99
  if (kind === "jssg" && content.language === undefined)
100
100
  content.packageLanguage = true;
101
- return Object.freeze({ [TASK]: "host", content });
101
+ return Object.freeze({ [TASK]: "host", content, reducer: transform.reducer });
102
+ }
103
+ /**
104
+ * Read the target's lockfiles into one dependency graph and run `callback`
105
+ * with a live handle on it, in its own isolate. Only what the callback
106
+ * returns is recorded.
107
+ */
108
+ function dependencyGraph(options, callback) {
109
+ const extracted = callbackOf(callback);
110
+ if (!extracted || extracted.fn) {
111
+ throw new TypeError("dependencyGraph: the callback was not extracted by the build; run the workflow through the codemod-workflow build");
112
+ }
113
+ const { lockfiles, ...rest } = isRecord(options) ? options : {};
114
+ const unknown = Object.keys(rest);
115
+ if (unknown.length)
116
+ throw new TypeError(`dependencyGraph: unknown option '${unknown[0]}'`);
117
+ return Object.freeze({
118
+ [TASK]: "dependencyGraph",
119
+ lockfiles: lockfiles === undefined ? undefined : globs(lockfiles, "lockfiles", "dependencyGraph: "),
120
+ callback: extracted,
121
+ });
102
122
  }
103
123
  function hostTask(kind, options) {
104
124
  const content = withoutUndefined(options);
@@ -140,7 +160,25 @@ export function createTasks(options = {}) {
140
160
  }
141
161
  /** Run a JSSG transform file over the target. */
142
162
  function jssg(path, options = {}) {
143
- return hostTask("jssg", { ...options, path });
163
+ if (!isRecord(options) || !("reduce" in options)) {
164
+ if (isRecord(options) && "initial" in options) {
165
+ throw new TypeError("jssg: initial is the starting value of reduce; give reduce too");
166
+ }
167
+ return hostTask("jssg", { ...options, path });
168
+ }
169
+ const { reduce, initial, ...rest } = options;
170
+ const callback = callbackOf(reduce);
171
+ if (!callback) {
172
+ throw new TypeError(typeof reduce === "function"
173
+ ? "jssg: reduce was not extracted by the build; run the workflow through the codemod-workflow build"
174
+ : "jssg: reduce must be a function, written inline as reduce: (result, file) => ...");
175
+ }
176
+ if (initial === undefined) {
177
+ throw new TypeError("jssg: reduce needs an initial value, as { reduce, initial }");
178
+ }
179
+ checkJson(initial, "jssg: initial");
180
+ const task = hostTask("jssg", { ...rest, path });
181
+ return Object.freeze({ ...task, reducer: { callback, initial: initial } });
144
182
  }
145
183
  /** Apply an ast-grep YAML rule file. */
146
184
  function astGrep(path, options = {}) {
@@ -199,6 +237,7 @@ export function createTasks(options = {}) {
199
237
  callbackOf,
200
238
  __callback,
201
239
  forEachFile,
240
+ dependencyGraph,
202
241
  shell,
203
242
  jssg,
204
243
  astGrep,
@@ -252,6 +291,9 @@ export function describeDuration(ms) {
252
291
  function policyOf(options, what) {
253
292
  if (options === undefined)
254
293
  return { attempts: 1, retryDelay: 0, timeout: undefined };
294
+ if (isRecord(options) && "state" in options) {
295
+ throw new TypeError(`${what}: steps take no \`state\`: give values to the task itself (a function step's variables, jssg \`params\`, shell \`env\`) and read what it found from its result`);
296
+ }
255
297
  onlyKeys(options, ["retries", "retryDelay", "timeout"], what);
256
298
  const { retries = 0, retryDelay = "1s", timeout } = options;
257
299
  if (!Number.isInteger(retries) || retries < 0) {
@@ -331,7 +373,6 @@ export function createRuntime(host) {
331
373
  }
332
374
  return { position: nextPosition++ };
333
375
  }
334
- const state = new Map();
335
376
  // A test run can stop after one step (`until`) and skip steps with a given
336
377
  // result (`given`), both matched by label.
337
378
  const plan = host.testPlan() ?? {};
@@ -342,7 +383,7 @@ export function createRuntime(host) {
342
383
  let closed = false;
343
384
  // Recorded steps the body has issued again, waiting to settle. They settle
344
385
  // one at a time in the order they finished when they ran, so the body sees
345
- // state, the clock and promise races as it did then.
386
+ // results, the clock and promise races as it did then.
346
387
  const replaying = [];
347
388
  /**
348
389
  * Settle the next replayed step. The host calls it whenever the workflow
@@ -376,62 +417,6 @@ export function createRuntime(host) {
376
417
  if (typeof entry.finishedAt === "number")
377
418
  host.advanceClock(entry.finishedAt);
378
419
  }
379
- // ---------------------------------------------------------------- state ---
380
- /** Read one state key, or the whole state as an object when called without one. Values are frozen. */
381
- function getState(key) {
382
- if (key === undefined)
383
- return Object.freeze(Object.fromEntries(state));
384
- return state.get(key);
385
- }
386
- /** Set workflow state. `undefined` removes the key. */
387
- function setState(key, value) {
388
- if (value === undefined) {
389
- state.delete(key);
390
- return;
391
- }
392
- checkJson(value, `state.${key}`);
393
- state.set(key, freeze(JSON.parse(JSON.stringify(value))));
394
- }
395
- function unsetState(key) {
396
- state.delete(key);
397
- }
398
- function applyState(changes) {
399
- if (!changes)
400
- return;
401
- for (const [key, value] of Object.entries(changes)) {
402
- if (value === null)
403
- state.delete(key);
404
- else
405
- state.set(key, freeze(value));
406
- }
407
- }
408
- function stateSnapshot() {
409
- return Object.fromEntries(state);
410
- }
411
- // The body runs alone, so a lock there has nothing to wait for; steps and
412
- // callbacks get the real one from their own runtime.
413
- function acquireLock(_name) {
414
- return () => { };
415
- }
416
- // Step outputs are kept for the transforms that still set them; nothing in
417
- // a workflow reads them back but these functions.
418
- const stepOutputs = new Map();
419
- const outputKey = (stepId, name) => JSON.stringify([stepId, name]);
420
- function setStepOutput(name, value) {
421
- stepOutputs.set(outputKey("", name), String(value));
422
- }
423
- function getStepOutput(stepId, name) {
424
- return stepOutputs.get(outputKey(stepId, name)) ?? null;
425
- }
426
- function getOrSetStepOutput(stepId, name, value) {
427
- const key = outputKey(stepId, name);
428
- const existing = stepOutputs.get(key);
429
- if (existing !== undefined)
430
- return existing;
431
- const text = String(value);
432
- stepOutputs.set(key, text);
433
- return text;
434
- }
435
420
  /** Evaluate a workflow.yaml `${{ }}` expression; used by translated workflows. */
436
421
  function __evaluate(kind, expression, scope) {
437
422
  return host.evaluate(kind, expression, scope);
@@ -460,7 +445,7 @@ export function createRuntime(host) {
460
445
  const described = label === undefined ? "step" : `step '${label}'`;
461
446
  const policy = policyOf(options, described);
462
447
  // Everything up to the first await runs synchronously inside step(), so
463
- // captures and state are a snapshot taken when the step is called.
448
+ // captures are a snapshot taken when the step is called.
464
449
  let content;
465
450
  let fn;
466
451
  const callback = callbackOf(task);
@@ -480,8 +465,24 @@ export function createRuntime(host) {
480
465
  };
481
466
  fn = task.callback.fn;
482
467
  }
468
+ else if (isTask(task) && task[TASK] === "dependencyGraph") {
469
+ content = withoutUndefined({
470
+ kind: "dependencyGraph",
471
+ lockfiles: task.lockfiles,
472
+ callback: task.callback.id,
473
+ captures: capturesOf(task.callback),
474
+ });
475
+ }
483
476
  else if (isTask(task) && task[TASK] === "host") {
484
477
  content = task.content;
478
+ if (task.reducer) {
479
+ const { callback, initial } = task.reducer;
480
+ content = {
481
+ ...content,
482
+ reduce: { callback: callback.id, captures: capturesOf(callback), initial },
483
+ };
484
+ fn = callback.fn;
485
+ }
485
486
  }
486
487
  else {
487
488
  throw new TypeError(`${described}: expected a task such as forEachFile(...) or a function`);
@@ -508,7 +509,6 @@ export function createRuntime(host) {
508
509
  // order they were issued.
509
510
  order: prior.seq ?? prior.position,
510
511
  settle() {
511
- applyState(prior.state);
512
512
  settleClock(prior);
513
513
  host.event({ type: "stepReplayed", position, label: name });
514
514
  resolve(prior.result ?? null);
@@ -548,7 +548,6 @@ export function createRuntime(host) {
548
548
  position,
549
549
  label: name,
550
550
  task: content,
551
- state: stateSnapshot(),
552
551
  fn,
553
552
  ...(policy.timeout !== undefined && { timeoutMs: policy.timeout }),
554
553
  ...(since !== undefined && { since }),
@@ -580,7 +579,6 @@ export function createRuntime(host) {
580
579
  position,
581
580
  label: name,
582
581
  task: { kind: "sleep", duration: policy.retryDelay },
583
- state: {},
584
582
  });
585
583
  }
586
584
  attempt++;
@@ -603,15 +601,13 @@ export function createRuntime(host) {
603
601
  throw new StepError(name, error);
604
602
  }
605
603
  const result = outcome.result ?? null;
606
- const changes = outcome.state ?? null;
607
- applyState(changes);
608
604
  const finishedAt = host.now();
609
605
  // Some files failed: the step finished, and the rest of the run goes on.
610
606
  if (outcome.partial !== undefined) {
611
- record({ status: "partial", result, state: changes, finishedAt, error: outcome.partial });
607
+ record({ status: "partial", result, finishedAt, error: outcome.partial });
612
608
  }
613
609
  else {
614
- record({ status: "succeeded", result, state: changes, finishedAt });
610
+ record({ status: "succeeded", result, finishedAt });
615
611
  }
616
612
  settleClock({ finishedAt });
617
613
  return result;
@@ -658,13 +654,6 @@ export function createRuntime(host) {
658
654
  const { callbackOf: _, ...builders } = tasks;
659
655
  return {
660
656
  ...builders,
661
- getState,
662
- setState,
663
- unsetState,
664
- acquireLock,
665
- setStepOutput,
666
- getStepOutput,
667
- getOrSetStepOutput,
668
657
  __evaluate,
669
658
  step,
670
659
  sleep,
@@ -726,14 +715,14 @@ function normalizeSelector(selector) {
726
715
  // Neither include nor language: the package's languages from codemod.yaml.
727
716
  return normalized;
728
717
  }
729
- function globs(value, field) {
718
+ function globs(value, field, owner = "forEachFile: selector.") {
730
719
  if (value === undefined)
731
720
  return [];
732
721
  if (typeof value === "string")
733
722
  return [value];
734
723
  if (Array.isArray(value) && value.every((item) => typeof item === "string"))
735
724
  return [...value];
736
- throw new TypeError(`forEachFile: selector.${field} must be a glob or an array of globs`);
725
+ throw new TypeError(`${owner}${field} must be a glob or an array of globs`);
737
726
  }
738
727
  function defaultLabel(position, content) {
739
728
  switch (content.kind) {
@@ -756,6 +745,10 @@ function defaultLabel(position, content) {
756
745
  return `wait for ${String(content.name)}`;
757
746
  case "codemod":
758
747
  return `codemod ${String(content.source)}`;
748
+ case "dependencyGraph": {
749
+ const lockfiles = content.lockfiles;
750
+ return lockfiles ? `dependencyGraph ${lockfiles.join(", ")}` : "dependencyGraph";
751
+ }
759
752
  case "agent":
760
753
  return `agent: ${truncate(content.prompt)}`;
761
754
  default:
@@ -8,12 +8,17 @@ export declare function sleep(duration: Duration): Promise<Json>;
8
8
  export declare function waitForEvent(name: string, options?: {
9
9
  timeout?: Duration;
10
10
  }): Promise<Json>;
11
- export declare function getState(key?: string): unknown;
12
- export declare function setState(key: string, value: unknown, persist?: boolean): void;
13
- export declare function unsetState(key: string): void;
14
- /** Callbacks run on one thread here, so a lock has nothing to wait for. */
15
- export declare function acquireLock(name: string): () => void;
16
- export declare function setStepOutput(name: string, value: unknown): void;
17
- export declare function getStepOutput(stepId: string, name: string): string | null;
18
- export declare function getOrSetStepOutput(stepId: string, name: string, value: unknown): string;
19
11
  export declare function __evaluate(kind: string, expression: string, scope: unknown): unknown;
12
+ export declare function dependencyGraph(_options: unknown, _callback: unknown): never;
13
+ export declare const registry: Readonly<{
14
+ npm: (_name: string) => Promise<never>;
15
+ cargo: (_name: string) => Promise<never>;
16
+ }>;
17
+ export declare const semver: Readonly<{
18
+ satisfies: () => never;
19
+ compare: () => never;
20
+ gt: () => never;
21
+ lt: () => never;
22
+ isBreaking: () => never;
23
+ isPrerelease: () => never;
24
+ }>;
@@ -1,10 +1,8 @@
1
1
  // `codemod:workflow` in Node.js and Bun: the shared orchestrator, with the
2
2
  // run looked up per call (see context.mjs).
3
3
  //
4
- // In the workflow body, `step`, `getState` and `setState` go to the run's
5
- // orchestrator. Inside a function step or a `forEachFile` callback, the state
6
- // functions see the state the step started with, and what they set becomes
7
- // the step's state changes, as in the engine's isolates.
4
+ // In the workflow body, `step` goes to the run's orchestrator. Workflows have
5
+ // no state: a step gets values from the body and returns what it found.
8
6
  import { createHash } from "node:crypto";
9
7
  import { current } from "./context.mjs";
10
8
  import { createTasks } from "./orchestrator.mjs";
@@ -31,96 +29,28 @@ export function sleep(duration) {
31
29
  export function waitForEvent(name, options) {
32
30
  return body("waitForEvent()").waitForEvent(name, options);
33
31
  }
34
- // In a step or callback the state functions behave as in the engine's
35
- // isolates: values are copied in and out, and what the step leaves different
36
- // from the state it started with becomes its state changes.
37
- export function getState(key) {
38
- const scope = current("getState()");
39
- if (!scope.step)
40
- return scope.runtime.getState(key);
41
- const state = scope.step.state;
42
- if (key === undefined)
43
- return structuredClone(Object.fromEntries(state));
44
- return state.has(key) ? structuredClone(state.get(key)) : undefined;
45
- }
46
- export function setState(key, value, persist = true) {
47
- const scope = current("setState()");
48
- if (!scope.step)
49
- return scope.runtime.setState(key, value);
50
- const step = scope.step;
51
- step.state.set(key, stateValue(value));
52
- step.removed.delete(key);
53
- if (persist)
54
- step.unpersisted.delete(key);
55
- else
56
- step.unpersisted.add(key);
57
- }
58
- export function unsetState(key) {
59
- const scope = current("unsetState()");
60
- if (!scope.step)
61
- return scope.runtime.unsetState(key);
62
- scope.step.state.delete(key);
63
- scope.step.removed.add(key);
64
- }
65
- /**
66
- * A value as state keeps it, the way the engine's isolates convert one:
67
- * what is not JSON becomes `null`, and objects keep their own enumerable
68
- * properties (so a `Date` or a `Map` becomes `{}`).
69
- */
70
- function stateValue(value) {
71
- switch (typeof value) {
72
- case "boolean":
73
- case "string":
74
- return value;
75
- case "number":
76
- return Number.isFinite(value) ? value : null;
77
- case "bigint":
78
- return Number(value);
79
- case "object":
80
- if (value === null)
81
- return null;
82
- if (Array.isArray(value))
83
- return value.map(stateValue);
84
- return Object.fromEntries(Object.entries(value).map(([key, item]) => [
85
- key,
86
- stateValue(item),
87
- ]));
88
- default:
89
- return null;
90
- }
91
- }
92
- /** Callbacks run on one thread here, so a lock has nothing to wait for. */
93
- export function acquireLock(name) {
94
- const scope = current("acquireLock()");
95
- if (!scope.step)
96
- return scope.runtime.acquireLock(name);
97
- return () => { };
98
- }
99
- // Step outputs are kept for the transforms that still set them; nothing in a
100
- // workflow reads them back but these functions.
101
- export function setStepOutput(name, value) {
102
- const scope = current("setStepOutput()");
103
- if (!scope.step)
104
- return scope.runtime.setStepOutput(name, value);
105
- scope.step.outputs.set(name, String(value));
106
- }
107
- export function getStepOutput(stepId, name) {
108
- const scope = current("getStepOutput()");
109
- if (!scope.step)
110
- return scope.runtime.getStepOutput(stepId, name);
111
- return scope.step.outputs.get(name) ?? null;
112
- }
113
- export function getOrSetStepOutput(stepId, name, value) {
114
- const scope = current("getOrSetStepOutput()");
115
- if (!scope.step)
116
- return scope.runtime.getOrSetStepOutput(stepId, name, value);
117
- const existing = scope.step.outputs.get(name);
118
- if (existing !== undefined)
119
- return existing;
120
- const text = String(value);
121
- scope.step.outputs.set(name, text);
122
- return text;
123
- }
124
32
  export function __evaluate(kind, expression, scope) {
125
33
  return current("__evaluate()").runtime.__evaluate(kind, expression, scope);
126
34
  }
35
+ // The dependency APIs need the engine's lockfile reader and registry client,
36
+ // which only the codemod CLI has. They are exported here so a workflow that
37
+ // imports them still loads, and fail with a clear message when used.
38
+ const QUICKJS_ONLY = 'is not available on the Node.js host yet: run the workflow with the codemod CLI, or test it with { host: "quickjs" }';
39
+ function unavailable(what) {
40
+ throw new Error(`${what} ${QUICKJS_ONLY}`);
41
+ }
42
+ export function dependencyGraph(_options, _callback) {
43
+ return unavailable("dependencyGraph()");
44
+ }
45
+ export const registry = Object.freeze({
46
+ npm: (_name) => Promise.reject(new Error(`registry.npm() ${QUICKJS_ONLY}`)),
47
+ cargo: (_name) => Promise.reject(new Error(`registry.cargo() ${QUICKJS_ONLY}`)),
48
+ });
49
+ export const semver = Object.freeze({
50
+ satisfies: () => unavailable("semver.satisfies()"),
51
+ compare: () => unavailable("semver.compare()"),
52
+ gt: () => unavailable("semver.gt()"),
53
+ lt: () => unavailable("semver.lt()"),
54
+ isBreaking: () => unavailable("semver.isBreaking()"),
55
+ isPrerelease: () => unavailable("semver.isPrerelease()"),
56
+ });
@@ -102,8 +102,6 @@ export interface WorkflowRun {
102
102
  readonly steps: readonly StepRun[];
103
103
  /** Console output, from steps, callbacks and the workflow body. */
104
104
  readonly logs: readonly LogLine[];
105
- /** Metrics the transforms recorded. */
106
- readonly metrics: Record<string, unknown>;
107
105
  /** The first step with this label. Throws when there is none. */
108
106
  step(label: string): StepRun;
109
107
  /** A unified diff of every file the run changed. */
package/testing/index.mjs CHANGED
@@ -161,7 +161,6 @@ class Run {
161
161
  changes;
162
162
  steps;
163
163
  logs;
164
- metrics;
165
164
  constructor(result, dir, before, files) {
166
165
  this.status = result.status;
167
166
  this.output = result.output;
@@ -173,7 +172,6 @@ class Run {
173
172
  this.changes = Object.freeze(changes(before, files));
174
173
  this.steps = Object.freeze(result.steps.map((step) => Object.freeze(step)));
175
174
  this.logs = Object.freeze(result.logs.map((log) => Object.freeze(log)));
176
- this.metrics = result.metrics;
177
175
  Object.defineProperty(this, "before", { value: before, enumerable: false });
178
176
  }
179
177
  /** Whether the run finished, or stopped at its `until` step. */
@@ -236,7 +234,6 @@ function harness(spec, signal) {
236
234
  stoppedAt: null,
237
235
  steps: [],
238
236
  logs: [],
239
- metrics: {},
240
237
  });
241
238
  }
242
239
  else {
package/types/index.d.ts CHANGED
@@ -2,7 +2,6 @@
2
2
  /// <reference path="llrt/index.d.ts" />
3
3
  /// <reference path="modules/ast-grep.d.ts" />
4
4
  /// <reference path="modules/llm.d.ts" />
5
- /// <reference path="modules/metrics.d.ts" />
6
5
  /// <reference path="modules/runtime.d.ts" />
7
6
  /// <reference path="modules/workflow.d.ts" />
8
7
  /// <reference path="modules/langs.d.ts" />
@@ -589,10 +589,31 @@ declare module "codemod:ast-grep" {
589
589
  */
590
590
  export type Transform<T extends TypesMap> = Codemod<T>;
591
591
 
592
+ /**
593
+ * Any JSON a transform reports about its file. A `jssg` step's `data`
594
+ * lists it per file, or folds it with the step's reducer. Explicit `null`
595
+ * is reported; missing or `undefined` data is omitted.
596
+ *
597
+ * @example
598
+ * ```ts
599
+ * return { edit: null, data: { props: props.map((p) => p.text()) } };
600
+ * ```
601
+ */
602
+ export type TransformData =
603
+ | string
604
+ | number
605
+ | boolean
606
+ | null
607
+ | readonly TransformData[]
608
+ | { readonly [key: string]: TransformData };
609
+
610
+ /** The new text (`edit`, or `null` for no change), and data to report. */
611
+ export type TransformResult = { edit?: string | null; data?: TransformData };
612
+
592
613
  export type Codemod<T extends TypesMap> = (
593
614
  root: SgRoot<T>,
594
615
  options: TransformOptions<T>,
595
- ) => Promise<string | null>;
616
+ ) => Promise<string | null | TransformResult>;
596
617
 
597
618
  export type GetSelectorOptions<_T extends TypesMap> = {
598
619
  params: Record<string, string>;