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.
- package/README.md +56 -2
- package/codemod +17 -30
- package/package.json +80 -10
- package/register.d.mts +2 -0
- package/register.mjs +67 -0
- package/runtime/addon.d.mts +114 -0
- package/runtime/addon.mjs +55 -0
- package/runtime/ast-grep.d.mts +20 -0
- package/runtime/ast-grep.mjs +82 -0
- package/runtime/context.d.mts +49 -0
- package/runtime/context.mjs +59 -0
- package/runtime/hooks.d.mts +2 -0
- package/runtime/hooks.mjs +7 -0
- package/runtime/host.d.mts +121 -0
- package/runtime/host.mjs +450 -0
- package/runtime/llm.d.mts +2 -0
- package/runtime/llm.mjs +5 -0
- package/runtime/metrics.d.mts +9 -0
- package/runtime/metrics.mjs +42 -0
- package/runtime/modules.d.mts +3 -0
- package/runtime/modules.mjs +17 -0
- 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 +879 -0
- package/runtime/runtime.d.mts +15 -0
- package/runtime/runtime.mjs +40 -0
- package/runtime/workflow.d.mts +19 -0
- package/runtime/workflow.mjs +126 -0
- package/testing/index.d.mts +157 -0
- package/testing/index.mjs +648 -0
- package/types/index.d.ts +8 -0
- package/types/langs/angular.d.ts +5 -0
- package/types/langs/c.d.ts +5 -0
- package/types/langs/c_sharp.d.ts +5 -0
- package/types/langs/cpp.d.ts +5 -0
- package/types/langs/css.d.ts +5 -0
- package/types/langs/elixir.d.ts +5 -0
- package/types/langs/go.d.ts +5 -0
- package/types/langs/html.d.ts +5 -0
- package/types/langs/java.d.ts +5 -0
- package/types/langs/javascript.d.ts +5 -0
- package/types/langs/json.d.ts +5 -0
- package/types/langs/kotlin.d.ts +5 -0
- package/types/langs/package.json +3 -0
- package/types/langs/php.d.ts +5 -0
- package/types/langs/python.d.ts +5 -0
- package/types/langs/ruby.d.ts +5 -0
- package/types/langs/rust.d.ts +5 -0
- package/types/langs/scala.d.ts +5 -0
- package/types/langs/toml.d.ts +5 -0
- package/types/langs/tsx.d.ts +5 -0
- package/types/langs/typescript.d.ts +5 -0
- package/types/langs/xml.d.ts +5 -0
- package/types/langs/yaml.d.ts +5 -0
- package/types/llm.d.ts +6 -0
- package/types/llrt/abort.d.ts +69 -0
- package/types/llrt/assert.d.ts +39 -0
- package/types/llrt/async_hooks.d.ts +210 -0
- package/types/llrt/buffer.d.ts +1186 -0
- package/types/llrt/child_process.d.ts +447 -0
- package/types/llrt/console.d.ts +210 -0
- package/types/llrt/crypto.d.ts +854 -0
- package/types/llrt/dgram.d.ts +381 -0
- package/types/llrt/dns.d.ts +124 -0
- package/types/llrt/dom-events.d.ts +51 -0
- package/types/llrt/events.d.ts +245 -0
- package/types/llrt/exceptions.d.ts +26 -0
- package/types/llrt/fetch.d.ts +332 -0
- package/types/llrt/fs/promises.d.ts +554 -0
- package/types/llrt/fs.d.ts +360 -0
- package/types/llrt/globals.d.ts +23 -0
- package/types/llrt/https.d.ts +27 -0
- package/types/llrt/index.d.ts +33 -0
- package/types/llrt/module.d.ts +285 -0
- package/types/llrt/navigator.d.ts +9 -0
- package/types/llrt/net.d.ts +488 -0
- package/types/llrt/os.d.ts +293 -0
- package/types/llrt/path.d.ts +150 -0
- package/types/llrt/perf_hooks.d.ts +23 -0
- package/types/llrt/process.d.ts +502 -0
- package/types/llrt/stream/web.d.ts +526 -0
- package/types/llrt/stream.d.ts +366 -0
- package/types/llrt/string_decoder.d.ts +63 -0
- package/types/llrt/timers.d.ts +72 -0
- package/types/llrt/timezone.d.ts +101 -0
- package/types/llrt/tty.d.ts +11 -0
- package/types/llrt/url.d.ts +774 -0
- package/types/llrt/util.d.ts +240 -0
- package/types/llrt/zlib.d.ts +177 -0
- package/types/main.d.ts +5 -0
- package/types/metrics.d.ts +5 -0
- package/types/modules/ast-grep.d.ts +634 -0
- package/types/modules/langs.d.ts +87 -0
- package/types/modules/llm.d.ts +23 -0
- package/types/modules/metrics.d.ts +107 -0
- package/types/modules/runtime.d.ts +66 -0
- package/types/modules/workflow.d.ts +915 -0
- package/types/runtime.d.ts +6 -0
- package/types/workflow.d.ts +5 -0
- package/vite.d.mts +7 -0
- 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
|
|
108
|
-
import type TSX from "codemod
|
|
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
|
-
|
|
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
|
-
|
|
94
|
-
moduleError = err;
|
|
95
|
-
} else {
|
|
96
|
-
moduleError = err;
|
|
97
|
-
}
|
|
94
|
+
moduleError = err;
|
|
98
95
|
}
|
|
99
96
|
}
|
|
100
97
|
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
"..",
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
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
|
-
|
|
115
|
-
|
|
116
|
-
"..",
|
|
117
|
-
"..",
|
|
118
|
-
"..",
|
|
119
|
-
"target",
|
|
120
|
-
"debug",
|
|
121
|
-
binaryName,
|
|
122
|
-
);
|
|
106
|
+
return { binaryPath: null, pkgName, error: moduleError };
|
|
107
|
+
}
|
|
123
108
|
|
|
124
|
-
|
|
125
|
-
|
|
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.
|
|
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
|
-
"
|
|
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.
|
|
30
|
-
"@codemod.com/cli-darwin-x64": "2.0.0-alpha.
|
|
31
|
-
"@codemod.com/cli-linux-arm64-gnu": "2.0.0-alpha.
|
|
32
|
-
"@codemod.com/cli-linux-arm64-musl": "2.0.0-alpha.
|
|
33
|
-
"@codemod.com/cli-linux-x64-gnu": "2.0.0-alpha.
|
|
34
|
-
"@codemod.com/cli-linux-x64-musl": "2.0.0-alpha.
|
|
35
|
-
"@codemod.com/cli-win32-x64-msvc": "2.0.0-alpha.
|
|
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
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[]>;
|