codemod 2.0.0-alpha.1 → 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.
Files changed (102) hide show
  1. package/README.md +56 -2
  2. package/codemod +17 -30
  3. package/package.json +80 -10
  4. package/register.d.mts +2 -0
  5. package/register.mjs +67 -0
  6. package/runtime/addon.d.mts +114 -0
  7. package/runtime/addon.mjs +55 -0
  8. package/runtime/ast-grep.d.mts +20 -0
  9. package/runtime/ast-grep.mjs +82 -0
  10. package/runtime/context.d.mts +49 -0
  11. package/runtime/context.mjs +59 -0
  12. package/runtime/hooks.d.mts +2 -0
  13. package/runtime/hooks.mjs +7 -0
  14. package/runtime/host.d.mts +121 -0
  15. package/runtime/host.mjs +450 -0
  16. package/runtime/llm.d.mts +2 -0
  17. package/runtime/llm.mjs +5 -0
  18. package/runtime/metrics.d.mts +9 -0
  19. package/runtime/metrics.mjs +42 -0
  20. package/runtime/modules.d.mts +3 -0
  21. package/runtime/modules.mjs +17 -0
  22. package/runtime/orchestrator-version.d.mts +2 -0
  23. package/runtime/orchestrator-version.mjs +3 -0
  24. package/runtime/orchestrator.d.mts +261 -0
  25. package/runtime/orchestrator.mjs +879 -0
  26. package/runtime/runtime.d.mts +15 -0
  27. package/runtime/runtime.mjs +40 -0
  28. package/runtime/workflow.d.mts +19 -0
  29. package/runtime/workflow.mjs +126 -0
  30. package/testing/index.d.mts +157 -0
  31. package/testing/index.mjs +648 -0
  32. package/types/index.d.ts +8 -0
  33. package/types/langs/angular.d.ts +5 -0
  34. package/types/langs/c.d.ts +5 -0
  35. package/types/langs/c_sharp.d.ts +5 -0
  36. package/types/langs/cpp.d.ts +5 -0
  37. package/types/langs/css.d.ts +5 -0
  38. package/types/langs/elixir.d.ts +5 -0
  39. package/types/langs/go.d.ts +5 -0
  40. package/types/langs/html.d.ts +5 -0
  41. package/types/langs/java.d.ts +5 -0
  42. package/types/langs/javascript.d.ts +5 -0
  43. package/types/langs/json.d.ts +5 -0
  44. package/types/langs/kotlin.d.ts +5 -0
  45. package/types/langs/package.json +3 -0
  46. package/types/langs/php.d.ts +5 -0
  47. package/types/langs/python.d.ts +5 -0
  48. package/types/langs/ruby.d.ts +5 -0
  49. package/types/langs/rust.d.ts +5 -0
  50. package/types/langs/scala.d.ts +5 -0
  51. package/types/langs/toml.d.ts +5 -0
  52. package/types/langs/tsx.d.ts +5 -0
  53. package/types/langs/typescript.d.ts +5 -0
  54. package/types/langs/xml.d.ts +5 -0
  55. package/types/langs/yaml.d.ts +5 -0
  56. package/types/llm.d.ts +6 -0
  57. package/types/llrt/abort.d.ts +69 -0
  58. package/types/llrt/assert.d.ts +39 -0
  59. package/types/llrt/async_hooks.d.ts +210 -0
  60. package/types/llrt/buffer.d.ts +1186 -0
  61. package/types/llrt/child_process.d.ts +447 -0
  62. package/types/llrt/console.d.ts +210 -0
  63. package/types/llrt/crypto.d.ts +854 -0
  64. package/types/llrt/dgram.d.ts +381 -0
  65. package/types/llrt/dns.d.ts +124 -0
  66. package/types/llrt/dom-events.d.ts +51 -0
  67. package/types/llrt/events.d.ts +245 -0
  68. package/types/llrt/exceptions.d.ts +26 -0
  69. package/types/llrt/fetch.d.ts +332 -0
  70. package/types/llrt/fs/promises.d.ts +554 -0
  71. package/types/llrt/fs.d.ts +360 -0
  72. package/types/llrt/globals.d.ts +23 -0
  73. package/types/llrt/https.d.ts +27 -0
  74. package/types/llrt/index.d.ts +33 -0
  75. package/types/llrt/module.d.ts +285 -0
  76. package/types/llrt/navigator.d.ts +9 -0
  77. package/types/llrt/net.d.ts +488 -0
  78. package/types/llrt/os.d.ts +293 -0
  79. package/types/llrt/path.d.ts +150 -0
  80. package/types/llrt/perf_hooks.d.ts +23 -0
  81. package/types/llrt/process.d.ts +502 -0
  82. package/types/llrt/stream/web.d.ts +526 -0
  83. package/types/llrt/stream.d.ts +366 -0
  84. package/types/llrt/string_decoder.d.ts +63 -0
  85. package/types/llrt/timers.d.ts +72 -0
  86. package/types/llrt/timezone.d.ts +101 -0
  87. package/types/llrt/tty.d.ts +11 -0
  88. package/types/llrt/url.d.ts +774 -0
  89. package/types/llrt/util.d.ts +240 -0
  90. package/types/llrt/zlib.d.ts +177 -0
  91. package/types/main.d.ts +5 -0
  92. package/types/metrics.d.ts +5 -0
  93. package/types/modules/ast-grep.d.ts +634 -0
  94. package/types/modules/langs.d.ts +87 -0
  95. package/types/modules/llm.d.ts +23 -0
  96. package/types/modules/metrics.d.ts +107 -0
  97. package/types/modules/runtime.d.ts +66 -0
  98. package/types/modules/workflow.d.ts +915 -0
  99. package/types/runtime.d.ts +6 -0
  100. package/types/workflow.d.ts +5 -0
  101. package/vite.d.mts +7 -0
  102. package/vite.mjs +32 -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();
@@ -206,6 +206,60 @@ nodes:
206
206
 
207
207
  **For detailed options and examples, see the [full CLI reference →](https://docs.codemod.com/community/cli)**
208
208
 
209
+ ## TypeScript types
210
+
211
+ A codemod package can depend on `codemod` directly: its scripts and `npx codemod` then run that
212
+ CLI, pinned to your `package.json`, and editors get the matching types for writing codemods and
213
+ workflows, the `codemod:*` modules (`codemod/workflow`, `codemod/ast-grep`, `codemod/metrics`, ...)
214
+ and the per-language node types:
215
+
216
+ ```bash
217
+ npm install codemod
218
+ ```
219
+
220
+ ```json
221
+ { "compilerOptions": { "types": ["codemod"] } }
222
+ ```
223
+
224
+ Type-only imports: `codemod/main` (`SgRoot`, `SgNode`, ...) and `codemod/langs/<language>`.
225
+ `@codemod.com/jssg-types` mirrors the same declarations for existing projects.
226
+
227
+ ## Testing workflows
228
+
229
+ `codemod/testing` runs workflows from your test runner (`node:test`, Vitest, Bun) on a copy of a
230
+ fixture or on inline files, and compares the files they leave. TypeScript workflows run in the test
231
+ process, so breakpoints, coverage and module mocks work in their code:
232
+
233
+ ```ts
234
+ import { test } from "node:test";
235
+ import { assertTree, fixtures, runWorkflow } from "codemod/testing";
236
+
237
+ for (const fixture of fixtures("tests")) {
238
+ test(fixture.name, async () => {
239
+ const run = await runWorkflow("workflow.ts", { target: fixture.input, params: fixture.params });
240
+ assertTree(run, fixture.expected);
241
+ });
242
+ }
243
+ ```
244
+
245
+ `until` stops after one step and `given` replaces a step's result, to test steps on their own. See
246
+ [Testing workflows](https://docs.codemod.com/community/workflows/testing).
247
+
248
+ ## Running workflows from Node.js
249
+
250
+ `codemod/host` runs a TypeScript workflow inside your Node.js or Bun process, for scripts and tools
251
+ built on codemods:
252
+
253
+ ```ts
254
+ import { runWorkflow } from "codemod/host";
255
+
256
+ const report = await runWorkflow("./my-codemod", { target: "./src" });
257
+ ```
258
+
259
+ Capabilities are not enforced on this host: run packages you did not write with the CLI, which runs
260
+ them sandboxed. See
261
+ [Run workflows from Node.js](https://docs.codemod.com/community/workflows/node).
262
+
209
263
  ## Ecosystem & Platform
210
264
 
211
265
  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": "2.0.0-alpha.1",
3
+ "version": "2.0.0-alpha.3",
4
4
  "description": "Codemod platform for semantic code transformations",
5
5
  "keywords": [
6
6
  "ast",
@@ -12,27 +12,97 @@
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
+ "build": "node scripts/build.mjs",
85
+ "prepack": "node scripts/build.mjs",
86
+ "test": "node scripts/build.mjs && node --test tests/*.test.js tests/*.test.mjs",
87
+ "typecheck": "node scripts/build.mjs && tsc -p ../../workflow/src/js && tsc -p types && tsc -p type-tests",
88
+ "pull-llrt-types": "bash scripts/pull-llrt-types.sh"
24
89
  },
25
90
  "dependencies": {
26
91
  "detect-libc": "^2.0.3"
27
92
  },
93
+ "devDependencies": {
94
+ "@codemod.com/tsconfig": "workspace:*",
95
+ "@types/node": "^22.16.0",
96
+ "typescript": "catalog:"
97
+ },
28
98
  "optionalDependencies": {
29
- "@codemod.com/cli-darwin-arm64": "2.0.0-alpha.1",
30
- "@codemod.com/cli-darwin-x64": "2.0.0-alpha.1",
31
- "@codemod.com/cli-linux-arm64-gnu": "2.0.0-alpha.1",
32
- "@codemod.com/cli-linux-arm64-musl": "2.0.0-alpha.1",
33
- "@codemod.com/cli-linux-x64-gnu": "2.0.0-alpha.1",
34
- "@codemod.com/cli-linux-x64-musl": "2.0.0-alpha.1",
35
- "@codemod.com/cli-win32-x64-msvc": "2.0.0-alpha.1"
99
+ "@codemod.com/cli-darwin-arm64": "2.0.0-alpha.3",
100
+ "@codemod.com/cli-darwin-x64": "2.0.0-alpha.3",
101
+ "@codemod.com/cli-linux-arm64-gnu": "2.0.0-alpha.3",
102
+ "@codemod.com/cli-linux-arm64-musl": "2.0.0-alpha.3",
103
+ "@codemod.com/cli-linux-x64-gnu": "2.0.0-alpha.3",
104
+ "@codemod.com/cli-linux-x64-musl": "2.0.0-alpha.3",
105
+ "@codemod.com/cli-win32-x64-msvc": "2.0.0-alpha.3"
36
106
  },
37
107
  "engines": {
38
108
  "node": ">= 16.0.0"
package/register.d.mts ADDED
@@ -0,0 +1,2 @@
1
+ import { resolveCodemodModule } from "./runtime/modules.mts";
2
+ export { resolveCodemodModule };
package/register.mjs ADDED
@@ -0,0 +1,67 @@
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
+ var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
8
+ if (typeof path === "string" && /^\.\.?\//.test(path)) {
9
+ return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
10
+ return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
11
+ });
12
+ }
13
+ return path;
14
+ };
15
+ /**
16
+ * `import "codemod/register"` lets Node.js and Bun import code written with
17
+ * the older `codemod:workflow`, `codemod:ast-grep`, `codemod:metrics`,
18
+ * `codemod:runtime` and `codemod:llm` spelling: those imports resolve to this
19
+ * package's `codemod/*` exports. Code that imports `codemod/*` needs none of this.
20
+ *
21
+ * @module
22
+ */
23
+ import module from "node:module";
24
+ import { CODEMOD_MODULES, resolveCodemodModule } from "./runtime/modules.mjs";
25
+ export { resolveCodemodModule };
26
+ const REGISTERED = Symbol.for("codemod.register");
27
+ const shared = globalThis;
28
+ const bunModules = shared.Bun !== undefined && !shared[REGISTERED]
29
+ ? await Promise.all(CODEMOD_MODULES.map(async (specifier) => [
30
+ specifier,
31
+ await import(__rewriteRelativeImportExtension(resolveCodemodModule(specifier) ?? specifier)),
32
+ ]))
33
+ : [];
34
+ function register() {
35
+ if (shared[REGISTERED])
36
+ return;
37
+ shared[REGISTERED] = true;
38
+ if (shared.Bun !== undefined) {
39
+ // Bun's runtime plugins do not resolve imports of loaded modules through
40
+ // onResolve, but serve virtual modules: back each with the real one.
41
+ shared.Bun.plugin({
42
+ name: "codemod",
43
+ setup(build) {
44
+ for (const [specifier, exports] of bunModules) {
45
+ build.module(specifier, () => ({ exports, loader: "object" }));
46
+ }
47
+ },
48
+ });
49
+ return;
50
+ }
51
+ if (typeof module.registerHooks === "function") {
52
+ module.registerHooks({
53
+ resolve(specifier, context, nextResolve) {
54
+ const url = resolveCodemodModule(specifier);
55
+ return url ? { url, shortCircuit: true } : nextResolve(specifier, context);
56
+ },
57
+ });
58
+ return;
59
+ }
60
+ if (typeof module.register === "function") {
61
+ // The built hooks file, next to the built form of this one.
62
+ module.register("./runtime/hooks.mjs", import.meta.url);
63
+ return;
64
+ }
65
+ throw new Error("this Node.js version cannot resolve codemod:* modules; use Node.js 20.6 or later");
66
+ }
67
+ register();
@@ -0,0 +1,114 @@
1
+ import type { Json, Outcome, StepRecord, TestPlan } from "./orchestrator.mts";
2
+ /** `OpenOptions` in crates/node/src/run.rs. */
3
+ export interface OpenOptions {
4
+ workflow: string;
5
+ target: string;
6
+ params?: Record<string, Json>;
7
+ name?: string;
8
+ dryRun?: boolean;
9
+ /** Stop after the step with this label (a test run). */
10
+ until?: string;
11
+ /** Results for steps that should not run, by label (a test run). */
12
+ given?: Record<string, Json>;
13
+ approve?: boolean;
14
+ capabilities?: string[];
15
+ store?: string;
16
+ resume?: string;
17
+ }
18
+ /** An event as the engine reports it (`Event` in crates/workflow/src/events.rs). */
19
+ export type EngineEvent = {
20
+ readonly event: string;
21
+ } & Record<string, unknown>;
22
+ /** What `Run.finish` returns: `RunReport::to_json`, with metrics and stats. */
23
+ export interface NativeReport {
24
+ runId: string;
25
+ status: "succeeded" | "failed" | "canceled" | "awaiting-approval" | "stopped";
26
+ output: Json;
27
+ error: string | null;
28
+ awaiting: string | null;
29
+ stoppedAt: string | null;
30
+ steps: {
31
+ position: number;
32
+ label: string;
33
+ status: "succeeded" | "partial" | "failed";
34
+ result: Json;
35
+ error: string | null;
36
+ given: boolean;
37
+ }[];
38
+ metrics: Record<string, unknown>;
39
+ stats: {
40
+ filesModified: number;
41
+ filesUnmodified: number;
42
+ filesWithErrors: number;
43
+ };
44
+ }
45
+ /** What a `forEachFile` callback did to one file, for `Run.commitFiles`. */
46
+ export interface FileEffects {
47
+ path: string;
48
+ /** The file's text when the step read it. */
49
+ original: string;
50
+ effects: import("./orchestrator.mts").FileEffect[];
51
+ }
52
+ /** One run in the engine: `Run` in crates/node/src/run.rs. */
53
+ export interface NativeRun {
54
+ readonly target: string;
55
+ readonly params: Record<string, Json>;
56
+ readonly dryRun: boolean;
57
+ /** Steps recorded by earlier executions of the run. */
58
+ history(): StepRecord[];
59
+ testPlan(): TestPlan | null;
60
+ /** Persist one step's outcome (a `StepRecord` as JSON). */
61
+ record(entry: string, durationMs: number): void;
62
+ /** Report a step started, replayed or retrying (a `StepEvent` as JSON). */
63
+ event(event: string): void;
64
+ /** A line the body (`null`) or the step at `position` wrote. */
65
+ log(position: number | null, line: string): void;
66
+ progress(position: number, processed: number, total: number): void;
67
+ canceled(): boolean;
68
+ /** Whether a step about to start must not, because the run was canceled. */
69
+ refusesSteps(): boolean;
70
+ cancel(): void;
71
+ /** The test plan's `until` step has started. */
72
+ stop(): void;
73
+ /** Evaluate a workflow.yaml `${{ }}` expression; `scope` is JSON. */
74
+ evaluate(kind: string, expression: string, scope: string): unknown;
75
+ /** Run a host task (a `StartRequest` as JSON). Rejects with `{ name, message }` as JSON in the message. */
76
+ runTask(request: string): Promise<Outcome>;
77
+ /** The files a `forEachFile` selector (as JSON) picks. */
78
+ selectFiles(selector: string): Promise<{
79
+ language: string | null;
80
+ files: [path: string, text: string][];
81
+ }>;
82
+ /** Commit what a step's callbacks did to its files (`FileEffects[]` as JSON). */
83
+ commitFiles(position: number, label: string, files: string): Promise<{
84
+ changes: Json;
85
+ failures: {
86
+ path: string;
87
+ error: string;
88
+ }[];
89
+ }>;
90
+ /** Add metrics a step recorded to the run summary, as JSON. */
91
+ addMetrics(metrics: string): void;
92
+ /** Events since the last call. */
93
+ takeEvents(): EngineEvent[];
94
+ /** Record how the run ended, given how its body ended (JSON, or `"null"`). */
95
+ finish(body: string): NativeReport;
96
+ }
97
+ /** The addon's exports. */
98
+ export interface Addon {
99
+ Run: {
100
+ open(options: OpenOptions): NativeRun;
101
+ };
102
+ /** Identifies the orchestrator source the addon's engine was built from. */
103
+ orchestratorVersion(): string;
104
+ /** The workflow file a path names: the file, or a package directory's workflow. */
105
+ resolveWorkflow(source: string, name: string | null): string;
106
+ /** Parse `source` as `language`; returns an `SgRoot`. */
107
+ parse(language: string, source: string, filename?: string, relativeFilename?: string): unknown;
108
+ languageFromPath(path: string): string | null;
109
+ kind(language: string, kindName: string): number;
110
+ }
111
+ /** The addon's exports. Throws with what to do when it cannot be found. */
112
+ export declare function addon(): Addon;
113
+ /** Where the addon is, or throws. */
114
+ export declare function addonPath(): string;
@@ -0,0 +1,55 @@
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
+ // The interfaces here describe what the addon exports (crates/node/src).
8
+ import { existsSync, statSync } from "node:fs";
9
+ import { createRequire } from "node:module";
10
+ import { dirname, join } from "node:path";
11
+ import { fileURLToPath } from "node:url";
12
+ const require = createRequire(import.meta.url);
13
+ const here = dirname(fileURLToPath(import.meta.url));
14
+ let loaded;
15
+ /** The addon's exports. Throws with what to do when it cannot be found. */
16
+ export function addon() {
17
+ if (loaded)
18
+ return loaded;
19
+ const path = addonPath();
20
+ const module = { exports: {} };
21
+ process.dlopen(module, path);
22
+ loaded = module.exports;
23
+ return loaded;
24
+ }
25
+ /** Where the addon is, or throws. */
26
+ export function addonPath() {
27
+ if (process.env.CODEMOD_NODE_ADDON)
28
+ return process.env.CODEMOD_NODE_ADDON;
29
+ const { detectPackageName } = require("../codemod");
30
+ const pkgName = detectPackageName();
31
+ if (pkgName) {
32
+ try {
33
+ const candidate = join(dirname(require.resolve(`${pkgName}/package.json`, { paths: [here] })), "codemod.node");
34
+ if (existsSync(candidate))
35
+ return candidate;
36
+ }
37
+ catch {
38
+ // not installed
39
+ }
40
+ }
41
+ const library = process.platform === "win32"
42
+ ? "codemod_node.dll"
43
+ : process.platform === "darwin"
44
+ ? "libcodemod_node.dylib"
45
+ : "libcodemod_node.so";
46
+ // In a checkout: whichever cargo build is newest, so a stale one is not
47
+ // picked over the build just made.
48
+ const [newest] = ["release", "debug"]
49
+ .map((profile) => join(here, "..", "..", "..", "..", "target", profile, library))
50
+ .filter((candidate) => existsSync(candidate))
51
+ .sort((a, b) => statSync(b).mtimeMs - statSync(a).mtimeMs);
52
+ if (newest)
53
+ return newest;
54
+ throw new Error(`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`);
55
+ }
@@ -0,0 +1,20 @@
1
+ /**
2
+ * `parse(lang, text)`, `parse(text, { language })`, or `parse(file, { language })`
3
+ * with a `forEachFile` file. Without a language, it comes from the file, then
4
+ * the `forEachFile` step's language, then the file's extension.
5
+ */
6
+ export declare function parse(source: unknown, second?: unknown): unknown;
7
+ /** The same as `parse`; parsers are ready at once here. */
8
+ export declare function parseAsync(source: unknown, second?: unknown): unknown;
9
+ export declare function parseFile(language: string, path: string): unknown;
10
+ /** The numeric id of a named node kind, for `{ kind: id }` matchers. */
11
+ export declare function kind(language: string, kindName: string): number;
12
+ export declare function jssgTransform(): never;
13
+ declare const _default: {
14
+ parse: typeof parse;
15
+ parseAsync: typeof parseAsync;
16
+ parseFile: typeof parseFile;
17
+ kind: typeof kind;
18
+ jssgTransform: typeof jssgTransform;
19
+ };
20
+ export default _default;
@@ -0,0 +1,82 @@
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
+ import { readFileSync, realpathSync } from "node:fs";
7
+ import { isAbsolute, join, relative } from "node:path";
8
+ import { addon } from "./addon.mjs";
9
+ import { context } from "./context.mjs";
10
+ function isRecord(value) {
11
+ return value !== null && typeof value === "object";
12
+ }
13
+ /** The `language` of `parse`'s options, when it is given. */
14
+ function languageOption(options) {
15
+ return isRecord(options) && typeof options.language === "string" ? options.language : undefined;
16
+ }
17
+ /**
18
+ * `parse(lang, text)`, `parse(text, { language })`, or `parse(file, { language })`
19
+ * with a `forEachFile` file. Without a language, it comes from the file, then
20
+ * the `forEachFile` step's language, then the file's extension.
21
+ */
22
+ export function parse(source, second) {
23
+ const native = addon();
24
+ const store = context.getStore();
25
+ const fallback = store?.step?.language;
26
+ if (typeof source === "string") {
27
+ if (typeof second === "string")
28
+ return native.parse(source, second);
29
+ const language = languageOption(second) ?? fallback;
30
+ if (!language) {
31
+ throw new Error('parse(text) needs a language: parse(text, { language: "tsx" })');
32
+ }
33
+ return native.parse(language, source);
34
+ }
35
+ if (!isRecord(source)) {
36
+ throw new TypeError("parse() expects source text or a file object, for example parse(file) or parse(text, { language })");
37
+ }
38
+ if (typeof source.text !== "string") {
39
+ throw new TypeError("parse(file) expects an object with a string `text`, such as the file a forEachFile callback receives");
40
+ }
41
+ const path = typeof source.path === "string" ? source.path : undefined;
42
+ const language = languageOption(second) ??
43
+ languageOption(source) ??
44
+ fallback ??
45
+ (path ? (native.languageFromPath(path) ?? undefined) : undefined);
46
+ if (!language) {
47
+ throw new Error(`parse(file): no language for '${path ?? "<file>"}'; pass one with parse(file, { language })`);
48
+ }
49
+ if (path === undefined)
50
+ return native.parse(language, source.text);
51
+ // The file's real path, and its path inside the target: what the CLI's
52
+ // runtime gives `filename()` and `relativeFilename()`.
53
+ const target = store?.run.target;
54
+ const filename = real(isAbsolute(path) || !target ? path : join(target, path));
55
+ const inTarget = target ? relative(real(target), filename) : path;
56
+ const outside = inTarget.startsWith("..") || isAbsolute(inTarget);
57
+ return native.parse(language, source.text, filename, outside ? undefined : inTarget);
58
+ }
59
+ /** A path with links resolved; as given when it does not exist. */
60
+ function real(path) {
61
+ try {
62
+ return realpathSync(path);
63
+ }
64
+ catch {
65
+ return path;
66
+ }
67
+ }
68
+ /** The same as `parse`; parsers are ready at once here. */
69
+ export function parseAsync(source, second) {
70
+ return parse(source, second);
71
+ }
72
+ export function parseFile(language, path) {
73
+ return addon().parse(language, readFileSync(path, "utf8"), path);
74
+ }
75
+ /** The numeric id of a named node kind, for `{ kind: id }` matchers. */
76
+ export function kind(language, kindName) {
77
+ return addon().kind(language, kindName);
78
+ }
79
+ export function jssgTransform() {
80
+ throw new Error("jssgTransform() is not supported in forEachFile callbacks yet; change each file from its own callback");
81
+ }
82
+ export default { parse, parseAsync, parseFile, kind, jssgTransform };
@@ -0,0 +1,49 @@
1
+ import { AsyncLocalStorage } from "node:async_hooks";
2
+ import type { NativeRun } from "./addon.mts";
3
+ import type { Json, Runtime } from "./orchestrator.mts";
4
+ /** One count of a metric, for one combination of labels. */
5
+ export type MetricEntry = {
6
+ cardinality: Record<string, string>;
7
+ count: number;
8
+ };
9
+ /** What a step or `forEachFile` callback sees and leaves behind. */
10
+ export interface StepScope {
11
+ position: number;
12
+ label: string;
13
+ /** State as the step sees it. */
14
+ state: Map<string, unknown>;
15
+ /** The state the step started with, as JSON, by key. */
16
+ initial: Map<string, string>;
17
+ /** Keys set with `persist: false`: the step's own. */
18
+ unpersisted: Set<string>;
19
+ /** Keys the step removed. */
20
+ removed: Set<string>;
21
+ /** Step outputs set here. */
22
+ outputs: Map<string, string>;
23
+ /** Metrics by name, then by their labels as JSON. */
24
+ metrics: Map<string, Map<string, MetricEntry>>;
25
+ /** A failure reported with `failFile` or `failStep`. */
26
+ failure: string | undefined;
27
+ /** `parse()`'s default language. */
28
+ language: string | undefined;
29
+ }
30
+ /** The run the code running now belongs to, and its step when it is in one. */
31
+ export interface RunScope {
32
+ run: NativeRun;
33
+ runtime: Runtime;
34
+ /** Whether `console` output of the run's code goes to its logs. */
35
+ captureConsole: boolean;
36
+ step?: StepScope;
37
+ }
38
+ export declare const context: AsyncLocalStorage<RunScope>;
39
+ /** The run the calling code belongs to; throws outside a run. */
40
+ export declare function current(what: string): RunScope;
41
+ /** A fresh step scope, starting from the workflow state the step began with. */
42
+ export declare function stepScope(position: number, label: string, state: Record<string, Json> | undefined, language?: string): StepScope;
43
+ /**
44
+ * The state a step set or removed (`null`), compared with the state it
45
+ * started with: what the engine's isolates report for the same code.
46
+ */
47
+ export declare function stateChanges(scope: StepScope): Record<string, Json>;
48
+ /** The metrics a step recorded, as the engine reports them. */
49
+ export declare function metricsOf(scope: StepScope): Record<string, MetricEntry[]>;