codemod 1.18.7 → 2.0.0-alpha.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (89) hide show
  1. package/README.md +57 -2
  2. package/codemod +17 -30
  3. package/package.json +78 -10
  4. package/register.d.mts +11 -0
  5. package/register.mjs +60 -0
  6. package/runtime/addon.mjs +59 -0
  7. package/runtime/ast-grep.mjs +93 -0
  8. package/runtime/context.mjs +77 -0
  9. package/runtime/hooks.mjs +9 -0
  10. package/runtime/host.d.mts +120 -0
  11. package/runtime/host.mjs +390 -0
  12. package/runtime/llm.mjs +11 -0
  13. package/runtime/metrics.mjs +45 -0
  14. package/runtime/modules.mjs +19 -0
  15. package/runtime/orchestrator.mjs +657 -0
  16. package/runtime/runtime.mjs +48 -0
  17. package/runtime/workflow.mjs +135 -0
  18. package/testing/index.d.mts +203 -0
  19. package/testing/index.mjs +638 -0
  20. package/types/index.d.ts +8 -0
  21. package/types/langs/angular.d.ts +5 -0
  22. package/types/langs/c.d.ts +5 -0
  23. package/types/langs/c_sharp.d.ts +5 -0
  24. package/types/langs/cpp.d.ts +5 -0
  25. package/types/langs/css.d.ts +5 -0
  26. package/types/langs/elixir.d.ts +5 -0
  27. package/types/langs/go.d.ts +5 -0
  28. package/types/langs/html.d.ts +5 -0
  29. package/types/langs/java.d.ts +5 -0
  30. package/types/langs/javascript.d.ts +5 -0
  31. package/types/langs/json.d.ts +5 -0
  32. package/types/langs/kotlin.d.ts +5 -0
  33. package/types/langs/php.d.ts +5 -0
  34. package/types/langs/python.d.ts +5 -0
  35. package/types/langs/ruby.d.ts +5 -0
  36. package/types/langs/rust.d.ts +5 -0
  37. package/types/langs/scala.d.ts +5 -0
  38. package/types/langs/toml.d.ts +5 -0
  39. package/types/langs/tsx.d.ts +5 -0
  40. package/types/langs/typescript.d.ts +5 -0
  41. package/types/langs/xml.d.ts +5 -0
  42. package/types/langs/yaml.d.ts +5 -0
  43. package/types/llm.d.ts +6 -0
  44. package/types/llrt/abort.d.ts +69 -0
  45. package/types/llrt/assert.d.ts +39 -0
  46. package/types/llrt/async_hooks.d.ts +210 -0
  47. package/types/llrt/buffer.d.ts +1186 -0
  48. package/types/llrt/child_process.d.ts +447 -0
  49. package/types/llrt/console.d.ts +210 -0
  50. package/types/llrt/crypto.d.ts +854 -0
  51. package/types/llrt/dgram.d.ts +381 -0
  52. package/types/llrt/dns.d.ts +124 -0
  53. package/types/llrt/dom-events.d.ts +51 -0
  54. package/types/llrt/events.d.ts +245 -0
  55. package/types/llrt/exceptions.d.ts +26 -0
  56. package/types/llrt/fetch.d.ts +332 -0
  57. package/types/llrt/fs/promises.d.ts +554 -0
  58. package/types/llrt/fs.d.ts +360 -0
  59. package/types/llrt/globals.d.ts +23 -0
  60. package/types/llrt/https.d.ts +27 -0
  61. package/types/llrt/index.d.ts +33 -0
  62. package/types/llrt/module.d.ts +285 -0
  63. package/types/llrt/navigator.d.ts +9 -0
  64. package/types/llrt/net.d.ts +488 -0
  65. package/types/llrt/os.d.ts +293 -0
  66. package/types/llrt/path.d.ts +150 -0
  67. package/types/llrt/perf_hooks.d.ts +23 -0
  68. package/types/llrt/process.d.ts +502 -0
  69. package/types/llrt/stream/web.d.ts +526 -0
  70. package/types/llrt/stream.d.ts +366 -0
  71. package/types/llrt/string_decoder.d.ts +63 -0
  72. package/types/llrt/timers.d.ts +72 -0
  73. package/types/llrt/timezone.d.ts +101 -0
  74. package/types/llrt/tty.d.ts +11 -0
  75. package/types/llrt/url.d.ts +774 -0
  76. package/types/llrt/util.d.ts +240 -0
  77. package/types/llrt/zlib.d.ts +177 -0
  78. package/types/main.d.ts +5 -0
  79. package/types/metrics.d.ts +5 -0
  80. package/types/modules/ast-grep.d.ts +634 -0
  81. package/types/modules/langs.d.ts +87 -0
  82. package/types/modules/llm.d.ts +23 -0
  83. package/types/modules/metrics.d.ts +107 -0
  84. package/types/modules/runtime.d.ts +66 -0
  85. package/types/modules/workflow.d.ts +750 -0
  86. package/types/runtime.d.ts +6 -0
  87. package/types/workflow.d.ts +5 -0
  88. package/vite.d.mts +24 -0
  89. package/vite.mjs +26 -0
package/README.md CHANGED
@@ -104,8 +104,8 @@ Packages can be as simple as a single transformation or as complex as multi-step
104
104
 
105
105
  ```typescript
106
106
  // Example: Replace console.log with logger.info
107
- import type { Codemod } from "codemod:ast-grep";
108
- import type TSX from "codemod:ast-grep/langs/tsx";
107
+ import type { Codemod } from "codemod/ast-grep";
108
+ import type TSX from "codemod/ast-grep/langs/tsx";
109
109
 
110
110
  const codemod: Codemod<TSX> = (root) => {
111
111
  const rootNode = root.root();
@@ -183,6 +183,7 @@ nodes:
183
183
  |---------|-------------|
184
184
  | `npx codemod workflow run -w <path>` | Run a codemod workflow on your codebase |
185
185
  | `npx codemod workflow validate -w <path>` | Validate workflow syntax and structure |
186
+ | `npx codemod workflow test [tests]` | Run the whole workflow on test fixtures and compare the results |
186
187
  | `npx codemod workflow resume -i <id>` | Resume a paused workflow |
187
188
  | `npx codemod workflow status -i <id>` | Show workflow execution status |
188
189
  | `npx codemod workflow list` | List recent workflow runs |
@@ -206,6 +207,60 @@ nodes:
206
207
 
207
208
  **For detailed options and examples, see the [full CLI reference →](https://docs.codemod.com/community/cli)**
208
209
 
210
+ ## TypeScript types
211
+
212
+ A codemod package can depend on `codemod` directly: its scripts and `npx codemod` then run that
213
+ CLI, pinned to your `package.json`, and editors get the matching types for writing codemods and
214
+ workflows, the `codemod:*` modules (`codemod/workflow`, `codemod/ast-grep`, `codemod/metrics`, ...)
215
+ and the per-language node types:
216
+
217
+ ```bash
218
+ npm install codemod
219
+ ```
220
+
221
+ ```json
222
+ { "compilerOptions": { "types": ["codemod"] } }
223
+ ```
224
+
225
+ Type-only imports: `codemod/main` (`SgRoot`, `SgNode`, ...) and `codemod/langs/<language>`.
226
+ `@codemod.com/jssg-types` mirrors the same declarations for existing projects.
227
+
228
+ ## Testing workflows
229
+
230
+ `codemod/testing` runs workflows from your test runner (`node:test`, Vitest, Bun) on a copy of a
231
+ fixture or on inline files, and compares the files they leave. TypeScript workflows run in the test
232
+ process, so breakpoints, coverage and module mocks work in their code:
233
+
234
+ ```ts
235
+ import { test } from "node:test";
236
+ import { assertTree, fixtures, runWorkflow } from "codemod/testing";
237
+
238
+ for (const fixture of fixtures("tests")) {
239
+ test(fixture.name, async () => {
240
+ const run = await runWorkflow("workflow.ts", { target: fixture.input, params: fixture.params });
241
+ assertTree(run, fixture.expected);
242
+ });
243
+ }
244
+ ```
245
+
246
+ `until` stops after one step and `given` replaces a step's result, to test steps on their own. See
247
+ [Testing workflows](https://docs.codemod.com/community/workflows/testing).
248
+
249
+ ## Running workflows from Node.js
250
+
251
+ `codemod/host` runs a TypeScript workflow inside your Node.js or Bun process, for scripts and tools
252
+ built on codemods:
253
+
254
+ ```ts
255
+ import { runWorkflow } from "codemod/host";
256
+
257
+ const report = await runWorkflow("./my-codemod", { target: "./src" });
258
+ ```
259
+
260
+ Capabilities are not enforced on this host: run packages you did not write with the CLI, which runs
261
+ them sandboxed. See
262
+ [Run workflows from Node.js](https://docs.codemod.com/community/workflows/node).
263
+
209
264
  ## Ecosystem & Platform
210
265
 
211
266
  The Codemod CLI is part of a larger ecosystem designed to help teams modernize code at scale:
package/codemod CHANGED
@@ -76,7 +76,8 @@ function failToLocateBinary(pkgName, originalError) {
76
76
  process.exit(1);
77
77
  }
78
78
 
79
- function resolveBinaryPath() {
79
+ /** Where the native binary is; `binaryPath` is null when it cannot be found. */
80
+ function findBinaryPath() {
80
81
  const pkgName = detectPackageName();
81
82
  let moduleError = null;
82
83
 
@@ -90,42 +91,27 @@ function resolveBinaryPath() {
90
91
  return { binaryPath: candidate, pkgName };
91
92
  }
92
93
  } catch (err) {
93
- if (err.code !== "MODULE_NOT_FOUND") {
94
- moduleError = err;
95
- } else {
96
- moduleError = err;
97
- }
94
+ moduleError = err;
98
95
  }
99
96
  }
100
97
 
101
- const releaseCandidate = path.join(
102
- __dirname,
103
- "..",
104
- "..",
105
- "..",
106
- "target",
107
- "release",
108
- binaryName,
109
- );
110
- if (fs.existsSync(releaseCandidate)) {
111
- return { binaryPath: releaseCandidate, pkgName: null };
98
+ // A checkout of the codemod repository: a local cargo build.
99
+ for (const profile of ["release", "debug"]) {
100
+ const candidate = path.join(__dirname, "..", "..", "..", "target", profile, binaryName);
101
+ if (fs.existsSync(candidate)) {
102
+ return { binaryPath: candidate, pkgName: null };
103
+ }
112
104
  }
113
105
 
114
- const debugCandidate = path.join(
115
- __dirname,
116
- "..",
117
- "..",
118
- "..",
119
- "target",
120
- "debug",
121
- binaryName,
122
- );
106
+ return { binaryPath: null, pkgName, error: moduleError };
107
+ }
123
108
 
124
- if (fs.existsSync(debugCandidate)) {
125
- return { binaryPath: debugCandidate, pkgName: null };
109
+ function resolveBinaryPath() {
110
+ const found = findBinaryPath();
111
+ if (found.binaryPath) {
112
+ return found;
126
113
  }
127
-
128
- failToLocateBinary(pkgName, moduleError);
114
+ failToLocateBinary(found.pkgName, found.error);
129
115
  }
130
116
 
131
117
  function npmExecutable(platform = process.platform) {
@@ -239,6 +225,7 @@ if (require.main === module) {
239
225
  module.exports = {
240
226
  CODEMOD_BOOTSTRAPPED_ENV,
241
227
  detectPackageName,
228
+ findBinaryPath,
242
229
  latestBootstrapArgs,
243
230
  npmExecutable,
244
231
  shouldBootstrapLatestNoCommand,
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "codemod",
3
- "version": "1.18.7",
3
+ "version": "2.0.0-alpha.2",
4
4
  "description": "Codemod platform for semantic code transformations",
5
5
  "keywords": [
6
6
  "ast",
@@ -12,27 +12,95 @@
12
12
  "homepage": "https://codemod.com",
13
13
  "repository": "https://github.com/codemod/codemod",
14
14
  "license": "Apache-2.0",
15
+ "exports": {
16
+ ".": {
17
+ "types": "./types/index.d.ts"
18
+ },
19
+ "./ast-grep": {
20
+ "types": "./types/main.d.ts",
21
+ "default": "./runtime/ast-grep.mjs"
22
+ },
23
+ "./ast-grep/langs/*": {
24
+ "types": "./types/langs/*.d.ts"
25
+ },
26
+ "./host": {
27
+ "types": "./runtime/host.d.mts",
28
+ "default": "./runtime/host.mjs"
29
+ },
30
+ "./langs/*": {
31
+ "types": "./types/langs/*.d.ts"
32
+ },
33
+ "./llm": {
34
+ "types": "./types/llm.d.ts",
35
+ "default": "./runtime/llm.mjs"
36
+ },
37
+ "./main": {
38
+ "types": "./types/main.d.ts",
39
+ "default": "./runtime/ast-grep.mjs"
40
+ },
41
+ "./metrics": {
42
+ "types": "./types/metrics.d.ts",
43
+ "default": "./runtime/metrics.mjs"
44
+ },
45
+ "./package.json": "./package.json",
46
+ "./register": {
47
+ "types": "./register.d.mts",
48
+ "default": "./register.mjs"
49
+ },
50
+ "./runtime": {
51
+ "types": "./types/runtime.d.ts",
52
+ "default": "./runtime/runtime.mjs"
53
+ },
54
+ "./testing": {
55
+ "types": "./testing/index.d.mts",
56
+ "default": "./testing/index.mjs"
57
+ },
58
+ "./vite": {
59
+ "types": "./vite.d.mts",
60
+ "default": "./vite.mjs"
61
+ },
62
+ "./workflow": {
63
+ "types": "./types/workflow.d.ts",
64
+ "default": "./runtime/workflow.mjs"
65
+ }
66
+ },
67
+ "types": "./types/index.d.ts",
15
68
  "bin": {
16
69
  "codemod": "codemod"
17
70
  },
18
71
  "files": [
72
+ "!types/tsconfig.json",
19
73
  "README.md",
20
- "codemod"
74
+ "codemod",
75
+ "register.d.mts",
76
+ "register.mjs",
77
+ "runtime",
78
+ "testing",
79
+ "types",
80
+ "vite.d.mts",
81
+ "vite.mjs"
21
82
  ],
22
83
  "scripts": {
23
- "test": "node --test tests/*.test.js"
84
+ "test": "node --test tests/*.test.js tests/*.test.mjs",
85
+ "typecheck": "tsc -p types && tsc -p type-tests",
86
+ "pull-llrt-types": "bash scripts/pull-llrt-types.sh",
87
+ "sync-orchestrator": "node scripts/sync-orchestrator.mjs"
24
88
  },
25
89
  "dependencies": {
26
90
  "detect-libc": "^2.0.3"
27
91
  },
92
+ "devDependencies": {
93
+ "@codemod.com/tsconfig": "workspace:*",
94
+ "typescript": "catalog:"
95
+ },
28
96
  "optionalDependencies": {
29
- "@codemod.com/cli-darwin-arm64": "1.18.7",
30
- "@codemod.com/cli-darwin-x64": "1.18.7",
31
- "@codemod.com/cli-linux-arm64-gnu": "1.18.7",
32
- "@codemod.com/cli-linux-arm64-musl": "1.18.7",
33
- "@codemod.com/cli-linux-x64-gnu": "1.18.7",
34
- "@codemod.com/cli-linux-x64-musl": "1.18.7",
35
- "@codemod.com/cli-win32-x64-msvc": "1.18.7"
97
+ "@codemod.com/cli-darwin-arm64": "2.0.0-alpha.2",
98
+ "@codemod.com/cli-darwin-x64": "2.0.0-alpha.2",
99
+ "@codemod.com/cli-linux-arm64-gnu": "2.0.0-alpha.2",
100
+ "@codemod.com/cli-linux-arm64-musl": "2.0.0-alpha.2",
101
+ "@codemod.com/cli-linux-x64-gnu": "2.0.0-alpha.2",
102
+ "@codemod.com/cli-linux-x64-musl": "2.0.0-alpha.2",
103
+ "@codemod.com/cli-win32-x64-msvc": "2.0.0-alpha.2"
36
104
  },
37
105
  "engines": {
38
106
  "node": ">= 16.0.0"
package/register.d.mts ADDED
@@ -0,0 +1,11 @@
1
+ /**
2
+ * `import "codemod/register"` lets Node.js and Bun import code written with
3
+ * the older `codemod:workflow`, `codemod:ast-grep`, `codemod:metrics`,
4
+ * `codemod:runtime` and `codemod:llm` spelling: those imports resolve to this
5
+ * package's `codemod/*` exports. Code that imports `codemod/*` needs none of this.
6
+ *
7
+ * @module
8
+ */
9
+
10
+ /** The URL a `codemod:*` specifier resolves to, or `undefined`. */
11
+ export function resolveCodemodModule(specifier: string): string | undefined;
package/register.mjs ADDED
@@ -0,0 +1,60 @@
1
+ // `import "codemod/register"`: lets Node.js and Bun import code written with
2
+ // the older `codemod:workflow`, `codemod:ast-grep`, ... spelling, mapping it
3
+ // to this package's `codemod/workflow`, `codemod/ast-grep`, ... exports.
4
+ // Code that imports `codemod/*` needs none of this.
5
+ //
6
+ // `codemod/host` and `codemod/testing` register these hooks themselves.
7
+
8
+ import module from "node:module";
9
+
10
+ import { CODEMOD_MODULES, resolveCodemodModule } from "./runtime/modules.mjs";
11
+
12
+ export { resolveCodemodModule };
13
+
14
+ const REGISTERED = Symbol.for("codemod.register");
15
+
16
+ const bunModules =
17
+ typeof globalThis.Bun !== "undefined" && !globalThis[REGISTERED]
18
+ ? await Promise.all(
19
+ CODEMOD_MODULES.map(async (specifier) => [
20
+ specifier,
21
+ await import(resolveCodemodModule(specifier)),
22
+ ]),
23
+ )
24
+ : [];
25
+
26
+ function register() {
27
+ if (globalThis[REGISTERED]) return;
28
+ globalThis[REGISTERED] = true;
29
+ if (typeof globalThis.Bun !== "undefined") {
30
+ // Bun's runtime plugins do not resolve imports of loaded modules through
31
+ // onResolve, but serve virtual modules: back each with the real one.
32
+ globalThis.Bun.plugin({
33
+ name: "codemod",
34
+ setup(build) {
35
+ for (const [specifier, exports] of bunModules) {
36
+ build.module(specifier, () => ({ exports, loader: "object" }));
37
+ }
38
+ },
39
+ });
40
+ return;
41
+ }
42
+ if (typeof module.registerHooks === "function") {
43
+ module.registerHooks({
44
+ resolve(specifier, context, nextResolve) {
45
+ const url = resolveCodemodModule(specifier);
46
+ return url ? { url, shortCircuit: true } : nextResolve(specifier, context);
47
+ },
48
+ });
49
+ return;
50
+ }
51
+ if (typeof module.register === "function") {
52
+ module.register("./runtime/hooks.mjs", import.meta.url);
53
+ return;
54
+ }
55
+ throw new Error(
56
+ "this Node.js version cannot resolve codemod:* modules; use Node.js 20.6 or later",
57
+ );
58
+ }
59
+
60
+ register();
@@ -0,0 +1,59 @@
1
+ // Loads the native addon (`codemod.node`): the workflow engine and the
2
+ // ast-grep API for code that runs in Node.js or Bun.
3
+ //
4
+ // Looked up in order: `CODEMOD_NODE_ADDON`, the platform package next to the
5
+ // CLI binary, then a cargo build in a checkout of the codemod repository.
6
+
7
+ import { existsSync, statSync } from "node:fs";
8
+ import { createRequire } from "node:module";
9
+ import { dirname, join } from "node:path";
10
+ import { fileURLToPath } from "node:url";
11
+
12
+ const require = createRequire(import.meta.url);
13
+ const here = dirname(fileURLToPath(import.meta.url));
14
+
15
+ let loaded;
16
+
17
+ /** The addon's exports. Throws with what to do when it cannot be found. */
18
+ export function addon() {
19
+ if (loaded) return loaded;
20
+ const path = addonPath();
21
+ const module = { exports: {} };
22
+ process.dlopen(module, path);
23
+ loaded = module.exports;
24
+ return loaded;
25
+ }
26
+
27
+ /** Where the addon is, or throws. */
28
+ export function addonPath() {
29
+ if (process.env.CODEMOD_NODE_ADDON) return process.env.CODEMOD_NODE_ADDON;
30
+ const { detectPackageName } = require("../codemod");
31
+ const pkgName = detectPackageName();
32
+ if (pkgName) {
33
+ try {
34
+ const candidate = join(
35
+ dirname(require.resolve(`${pkgName}/package.json`, { paths: [here] })),
36
+ "codemod.node",
37
+ );
38
+ if (existsSync(candidate)) return candidate;
39
+ } catch {
40
+ // not installed
41
+ }
42
+ }
43
+ const library =
44
+ process.platform === "win32"
45
+ ? "codemod_node.dll"
46
+ : process.platform === "darwin"
47
+ ? "libcodemod_node.dylib"
48
+ : "libcodemod_node.so";
49
+ // In a checkout: whichever cargo build is newest, so a stale one is not
50
+ // picked over the build just made.
51
+ const builds = ["release", "debug"]
52
+ .map((profile) => join(here, "..", "..", "..", "..", "target", profile, library))
53
+ .filter((candidate) => existsSync(candidate))
54
+ .sort((a, b) => statSync(b).mtimeMs - statSync(a).mtimeMs);
55
+ if (builds.length) return builds[0];
56
+ throw new Error(
57
+ `cannot find the codemod native addon${pkgName ? ` (expected codemod.node in the ${pkgName} package)` : " for this platform"}; reinstall codemod with optional dependencies, or set CODEMOD_NODE_ADDON`,
58
+ );
59
+ }
@@ -0,0 +1,93 @@
1
+ // `codemod/ast-grep` in Node.js and Bun, backed by the native addon: the same
2
+ // SgRoot and SgNode methods, matchers and languages as in the engine.
3
+ //
4
+ // Roots parsed here have no semantic provider, as with `parse()` in an engine
5
+ // `forEachFile` callback: `definition()` returns null.
6
+
7
+ import { readFileSync, realpathSync } from "node:fs";
8
+ import { isAbsolute, join, relative } from "node:path";
9
+
10
+ import { addon } from "./addon.mjs";
11
+ import { context } from "./context.mjs";
12
+
13
+ /**
14
+ * `parse(lang, text)`, `parse(text, { language })`, or `parse(file, { language })`
15
+ * with a `forEachFile` file. Without a language, it comes from the file, then
16
+ * the `forEachFile` step's language, then the file's extension.
17
+ */
18
+ export function parse(source, second) {
19
+ const native = addon();
20
+ const store = context.getStore();
21
+ const fallback = store?.step?.language;
22
+ const languageOption = (value) =>
23
+ value && typeof value === "object" ? (value.language ?? undefined) : undefined;
24
+
25
+ if (typeof source === "string") {
26
+ if (typeof second === "string") return native.parse(source, second);
27
+ const language = languageOption(second) ?? fallback;
28
+ if (!language) {
29
+ throw new Error('parse(text) needs a language: parse(text, { language: "tsx" })');
30
+ }
31
+ return native.parse(language, source);
32
+ }
33
+ if (!source || typeof source !== "object") {
34
+ throw new TypeError(
35
+ "parse() expects source text or a file object, for example parse(file) or parse(text, { language })",
36
+ );
37
+ }
38
+ if (typeof source.text !== "string") {
39
+ throw new TypeError(
40
+ "parse(file) expects an object with a string `text`, such as the file a forEachFile callback receives",
41
+ );
42
+ }
43
+ const path = typeof source.path === "string" ? source.path : undefined;
44
+ const language =
45
+ languageOption(second) ??
46
+ source.language ??
47
+ fallback ??
48
+ (path ? native.languageFromPath(path) : undefined);
49
+ if (!language) {
50
+ throw new Error(
51
+ `parse(file): no language for '${path ?? "<file>"}'; pass one with parse(file, { language })`,
52
+ );
53
+ }
54
+ if (path === undefined) return native.parse(language, source.text);
55
+ // The file's real path, and its path inside the target: what the CLI's
56
+ // runtime gives `filename()` and `relativeFilename()`.
57
+ const target = store?.run?.target;
58
+ const filename = real(isAbsolute(path) || !target ? path : join(target, path));
59
+ const inTarget = target ? relative(real(target), filename) : path;
60
+ const outside = inTarget.startsWith("..") || isAbsolute(inTarget);
61
+ return native.parse(language, source.text, filename, outside ? undefined : inTarget);
62
+ }
63
+
64
+ /** A path with links resolved; as given when it does not exist. */
65
+ function real(path) {
66
+ try {
67
+ return realpathSync(path);
68
+ } catch {
69
+ return path;
70
+ }
71
+ }
72
+
73
+ /** The same as `parse`; parsers are ready at once here. */
74
+ export function parseAsync(source, second) {
75
+ return parse(source, second);
76
+ }
77
+
78
+ export function parseFile(language, path) {
79
+ return addon().parse(language, readFileSync(path, "utf8"), path);
80
+ }
81
+
82
+ /** The numeric id of a named node kind, for `{ kind: id }` matchers. */
83
+ export function kind(language, kindName) {
84
+ return addon().kind(language, kindName);
85
+ }
86
+
87
+ export function jssgTransform() {
88
+ throw new Error(
89
+ "jssgTransform() is not supported in forEachFile callbacks yet; change each file from its own callback",
90
+ );
91
+ }
92
+
93
+ export default { parse, parseAsync, parseFile, kind, jssgTransform };
@@ -0,0 +1,77 @@
1
+ // Which run, and which step of it, the code running now belongs to. The
2
+ // `codemod/*` modules are singletons, and runs may overlap (tests in
3
+ // parallel), so they look the run up here.
4
+ //
5
+ // The store is shared through a global symbol, so it stays one store when a
6
+ // test runner loads this package twice (once natively, once through its own
7
+ // module graph).
8
+
9
+ import { AsyncLocalStorage } from "node:async_hooks";
10
+
11
+ const KEY = Symbol.for("codemod.workflow.context");
12
+
13
+ /** @type {AsyncLocalStorage<{ run: any, runtime: any, step?: StepScope }>} */
14
+ export const context = (globalThis[KEY] ??= new AsyncLocalStorage());
15
+
16
+ /**
17
+ * @typedef {object} StepScope
18
+ * @property {number} position
19
+ * @property {string} label
20
+ * @property {Map<string, unknown>} state state as the step sees it
21
+ * @property {Map<string, string>} initial the state the step started with, as JSON, by key
22
+ * @property {Set<string>} unpersisted keys set with `persist: false`: the step's own
23
+ * @property {Set<string>} removed keys the step removed
24
+ * @property {Map<string, string>} outputs step outputs set here
25
+ * @property {Map<string, Map<string, { cardinality: Record<string, string>, count: number }>>} metrics
26
+ * @property {string | undefined} failure a failure reported with `failFile` or `failStep`
27
+ * @property {string | undefined} language `parse()`'s default language
28
+ */
29
+
30
+ /** The run the calling code belongs to; throws outside a run. */
31
+ export function current(what) {
32
+ const store = context.getStore();
33
+ if (!store) {
34
+ throw new Error(
35
+ `${what} only works while a workflow runs; run the workflow with codemod (the CLI, or runWorkflow from codemod/testing)`,
36
+ );
37
+ }
38
+ return store;
39
+ }
40
+
41
+ /** A fresh step scope, starting from the workflow state the step began with. */
42
+ export function stepScope(position, label, state, language) {
43
+ const entries = Object.entries(state ?? {});
44
+ return {
45
+ position,
46
+ label,
47
+ state: new Map(entries.map(([key, value]) => [key, structuredClone(value)])),
48
+ initial: new Map(entries.map(([key, value]) => [key, JSON.stringify(value)])),
49
+ unpersisted: new Set(),
50
+ removed: new Set(),
51
+ outputs: new Map(),
52
+ metrics: new Map(),
53
+ failure: undefined,
54
+ language,
55
+ };
56
+ }
57
+
58
+ /**
59
+ * The state a step set or removed (`null`), compared with the state it
60
+ * started with: what the engine's isolates report for the same code.
61
+ */
62
+ export function stateChanges(scope) {
63
+ const changes = {};
64
+ for (const [key, value] of scope.state) {
65
+ if (scope.unpersisted.has(key)) continue;
66
+ if (scope.initial.get(key) !== JSON.stringify(value)) changes[key] = value;
67
+ }
68
+ for (const key of scope.removed) changes[key] = null;
69
+ return changes;
70
+ }
71
+
72
+ /** The metrics a step recorded, as the engine reports them. */
73
+ export function metricsOf(scope) {
74
+ const data = {};
75
+ for (const [name, entries] of scope.metrics) data[name] = [...entries.values()];
76
+ return data;
77
+ }
@@ -0,0 +1,9 @@
1
+ // Resolve hooks for Node.js versions without `module.registerHooks`
2
+ // (loaded through `module.register`, on the loader thread).
3
+
4
+ import { resolveCodemodModule } from "./modules.mjs";
5
+
6
+ export async function resolve(specifier, context, nextResolve) {
7
+ const url = resolveCodemodModule(specifier);
8
+ return url ? { url, shortCircuit: true } : nextResolve(specifier, context);
9
+ }