Skip to content

Commit cea6b54

Browse files
authored
fix: capture plugins using deferred SDK requires (#107)
* fix: capture SDK imports through named createRequire handles * test(sdk): bypass require cache when checking hook cleanup * fix(analysis): preserve require bindings during Bun type erasure
1 parent bfe563f commit cea6b54

4 files changed

Lines changed: 172 additions & 7 deletions

File tree

‎CHANGELOG.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,8 @@
22

33
## Unreleased
44

5+
- Discover literal SDK imports through stable handles from named Node.js `createRequire` imports so deferred registration and retained handlers receive their generated mock modules. Namespace/default factory handles are outside the supported static contract; shadowed `require` calls now need proven factory provenance.
6+
57
- Capture plugins that bind asynchronous state stores or inspect optional instance lifecycle capabilities during registration; preserve capture-local singleton factory state and runtime slots across SDK barrels. State operations and singleton lifecycle drains remain explicitly unsupported by capture mocks.
68

79
- Capture namespace SDK imports and published doctor-contract bundles without missing exports; mock doctor descriptors remain inspectable while actual migration execution fails explicitly.

‎src/runtime-imports.js‎

Lines changed: 38 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -2,10 +2,11 @@ import * as nodeModule from "node:module";
22
import { parse } from "acorn";
33
import { analyze } from "eslint-scope";
44

5-
const literalModuleImport = /(?<![$\w.])(?:(?:const|let|var)\s+(?:\{[^{}]*\}|[$A-Z_a-z][$\w]*)\s*=\s*)?(?<kind>require|import)\s*\(\s*(?<quote>["'`])(?<specifier>[^"'`\\\r\n]+)\k<quote>/dg;
5+
const literalModuleImport = /(?<![$\w.])(?<kind>[$A-Z_a-z][$\w]*)\s*\(\s*(?<quote>["'`])(?<specifier>[^"'`\\\r\n]+)\k<quote>/dg;
66

77
export function collectRuntimeModuleImports(text, { includeStaticNamespaces = false } = {}) {
8-
// Mark literal occurrences without interpreting quotes or regexes; the AST owns real calls.
8+
// Mark literal call arguments to preserve offsets through type erasure. Only
9+
// the AST and resolved Node createRequire bindings can classify real imports.
910
const entries = [...text.matchAll(literalModuleImport)].map(moduleImportEntry).filter(Boolean);
1011
if (entries.length === 0 && !includeStaticNamespaces) return entries;
1112
const { runtimeText, imports } = classifyRuntimeImports(text, entries);
@@ -25,7 +26,8 @@ export function collectRuntimeModuleImports(text, { includeStaticNamespaces = fa
2526
// Keep known imports if syntax is incomplete/unsupported; never guess namespace exports.
2627
// Type erasure has already classified each occurrence, even when AST analysis fails.
2728
const retained = new Set(imports.map(({ entry }) => entry.specifierStart));
28-
return [...scanLiteralModuleImports(text)].filter((entry) => retained.has(entry.specifierStart))
29+
return [...scanLiteralModuleImports(text)].filter((entry) =>
30+
["require", "import"].includes(entry.kind) && retained.has(entry.specifierStart))
2931
.map((entry) => ({ ...entry, names: new Set() }));
3032
}
3133

@@ -41,6 +43,31 @@ export function collectRuntimeModuleImports(text, { includeStaticNamespaces = fa
4143
else if (value && typeof value === "object") visit(value, node);
4244
}
4345
}
46+
const requireReferences = new Set();
47+
const lexicalReferences = new Set(scopes.scopes.flatMap((scope) =>
48+
scope.references.filter((reference) => reference.resolved).map((reference) => reference.identifier)));
49+
for (const declaration of nodes) {
50+
if (declaration.type !== "ImportDeclaration" || !["module", "node:module"].includes(declaration.source.value)) continue;
51+
for (const binding of declaration.specifiers) {
52+
const variable = scopes.getDeclaredVariables(declaration).find((value) => value.identifiers.includes(binding.local));
53+
if (!variable || variable.defs.length !== 1 || variable.references.some((reference) => reference.isWrite())) continue;
54+
// Named imports identify the factory without following mutable module objects.
55+
if (binding.type !== "ImportSpecifier" || binding.imported.name !== "createRequire") continue;
56+
for (const reference of variable.references) {
57+
const factory = reference.identifier;
58+
const call = parents.get(factory);
59+
if (!reference.isStatic() || call?.type !== "CallExpression" || call.callee !== factory || call.arguments.length !== 1) continue;
60+
const owner = parents.get(call);
61+
if (owner?.type !== "VariableDeclarator" || owner.init !== call || owner.id.type !== "Identifier") continue;
62+
const handle = scopes.getDeclaredVariables(owner).find((value) => value.identifiers.includes(owner.id));
63+
if (!handle || handle.defs.length !== 1 || handle.references.some((value) => value.isWrite() && !value.init)) continue;
64+
for (const use of handle.references) {
65+
if (use.isStatic() && use.isRead()) requireReferences.add(use.identifier);
66+
}
67+
}
68+
}
69+
}
70+
4471
const byMarker = new Map(imports.map(({ marker, entry }) => [marker, entry]));
4572
const result = [];
4673
for (const node of nodes) {
@@ -55,11 +82,13 @@ export function collectRuntimeModuleImports(text, { includeStaticNamespaces = fa
5582
}
5683
const source = node.type === "ImportExpression" ? node.source
5784
: node.type === "CallExpression" && node.callee.type === "Identifier"
58-
&& node.callee.name === "require" && node.arguments.length === 1 ? node.arguments[0] : null;
85+
&& ((node.callee.name === "require" && !lexicalReferences.has(node.callee)) || requireReferences.has(node.callee))
86+
&& node.arguments.length === 1 ? node.arguments[0] : null;
5987
const specifier = source?.type === "Literal" ? source.value
6088
: source?.type === "TemplateLiteral" && source.expressions.length === 0 ? source.quasis[0].value.cooked : null;
61-
const entry = byMarker.get(specifier);
62-
if (!entry) continue;
89+
const candidate = byMarker.get(specifier);
90+
if (!candidate) continue;
91+
const entry = node.type === "CallExpression" ? { ...candidate, kind: "require" } : candidate;
6392
const names = new Set();
6493
result.push({ ...entry, names });
6594
const access = parents.get(node);
@@ -193,7 +222,9 @@ function eraseTypeScript(text) {
193222
}
194223
}
195224
if (typeof globalThis.Bun?.Transpiler === "function") {
196-
const transpiler = new globalThis.Bun.Transpiler({ loader: "ts", target: "bun" });
225+
// Analyze source bindings: the Bun target injects a require binding that
226+
// would make native calls look shadowed after type erasure.
227+
const transpiler = new globalThis.Bun.Transpiler({ loader: "ts", target: "node" });
197228
return transpiler.transformSync(text);
198229
}
199230
return null;

‎test/runtime-imports.test.js‎

Lines changed: 78 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,84 @@ import { pathToFileURL } from "node:url";
77
import { collectRuntimeModuleImports } from "../src/runtime-imports.js";
88
import { createMockSdkPackage } from "../src/sdk-mock.js";
99

10+
test("Node createRequire handles retain literal SDK calls and original source positions", () => {
11+
for (const [declaration, factory] of [
12+
['import { createRequire as make } from "node:module";', "make"],
13+
['import { createRequire as make } from "module";', "make"],
14+
]) {
15+
const source = [declaration,
16+
`const load = ${factory}(import.meta.url);`,
17+
'const regex = /load("fake")/; const text = `load("openclaw/plugin-sdk/template-only")`; const quoted = \'load("openclaw/plugin-sdk/string-only")\';',
18+
'// load("openclaw/plugin-sdk/comment-only");',
19+
'const sdk = load("openclaw/plugin-sdk/alias-only");',
20+
'const read = () => sdk.readStringField({}, "value");',
21+
'const { isRecord: record } = load(`openclaw/plugin-sdk/destructured`);',
22+
'const direct = load("openclaw/plugin-sdk/direct").asOptionalRecord;',
23+
'function shadow(load) { return load("openclaw/plugin-sdk/ignored"); }',
24+
'{ const load = () => ({}); load("openclaw/plugin-sdk/block"); }',
25+
'try {} catch (load) { load("openclaw/plugin-sdk/catch"); }',
26+
'function factoryShadow(make, moduleApi) { const other = make(import.meta.url); other("openclaw/plugin-sdk/factory-shadow"); const next = moduleApi.createRequire(import.meta.url); next("openclaw/plugin-sdk/module-shadow"); }',
27+
].join("\n");
28+
const imports = collectRuntimeModuleImports(source);
29+
assert.deepEqual(imports.map(({ specifier, kind, names }) => [specifier, kind, [...names]]), [
30+
["openclaw/plugin-sdk/alias-only", "require", ["readStringField"]],
31+
["openclaw/plugin-sdk/destructured", "require", ["isRecord"]],
32+
["openclaw/plugin-sdk/direct", "require", ["asOptionalRecord"]],
33+
], declaration);
34+
for (const entry of imports) assert.equal(source.slice(entry.specifierStart, entry.specifierStart + entry.specifier.length), entry.specifier);
35+
}
36+
const typed = 'import { createRequire as make } from "node:module"; const load: NodeRequire = make(import.meta.url); type Only = ReturnType<typeof load>; const sdk: object = load("openclaw/plugin-sdk/typed-alias"); sdk.isRecord({});';
37+
assert.deepEqual(collectRuntimeModuleImports(typed).map(({ specifier, names }) => [specifier, [...names]]),
38+
[["openclaw/plugin-sdk/typed-alias", ["isRecord"]]]);
39+
const nested = 'import { createRequire as make } from "node:module"; function initialize() { const require = make(import.meta.url); const { isRecord } = require("openclaw/plugin-sdk/nested"); return () => require("openclaw/plugin-sdk/retained").readStringField({}, "value"); }';
40+
assert.deepEqual(collectRuntimeModuleImports(nested).map(({ specifier, names }) => [specifier, [...names]]), [
41+
["openclaw/plugin-sdk/nested", ["isRecord"]], ["openclaw/plugin-sdk/retained", ["readStringField"]],
42+
]);
43+
});
44+
45+
test("destructuring defaults retain nested SDK calls and their actual source offsets", () => {
46+
const source = [
47+
'import { createRequire as make } from "node:module";',
48+
'const load = make(import.meta.url);',
49+
'const { nativeSdk =',
50+
' require("openclaw/plugin-sdk/native-default").isRecord } = getOptions("plugin");',
51+
'const { dynamicSdk = await import("openclaw/plugin-sdk/dynamic-default") } = getOptions("plugin");',
52+
'const { aliasSdk = load("openclaw/plugin-sdk/alias-default").readStringField } = getOptions("plugin");',
53+
].join("\n");
54+
const imports = collectRuntimeModuleImports(source);
55+
assert.deepEqual(imports.map(({ specifier, names }) => [specifier, [...names]]), [
56+
["openclaw/plugin-sdk/native-default", ["isRecord"]],
57+
["openclaw/plugin-sdk/dynamic-default", []],
58+
["openclaw/plugin-sdk/alias-default", ["readStringField"]],
59+
]);
60+
for (const [index, callee] of ["require", "import", "load"].entries()) {
61+
const entry = imports[index];
62+
assert.equal(entry.index, source.indexOf(`${callee}("${entry.specifier}"`));
63+
assert.equal(source.slice(entry.specifierStart, entry.specifierStart + entry.specifier.length), entry.specifier);
64+
}
65+
});
66+
67+
test("createRequire discovery excludes unproven factories, writes and nonliteral calls", () => {
68+
for (const source of [
69+
'import { createRequire as make } from "other-module"; const load = make(import.meta.url); load("openclaw/plugin-sdk/no");',
70+
'function make(base) { return () => ({}); } const load = make(import.meta.url); load("openclaw/plugin-sdk/no");',
71+
'import { createRequire as make } from "node:module"; let load = make(import.meta.url); load = other; load("openclaw/plugin-sdk/no");',
72+
'import { createRequire as make } from "node:module"; var load = make(import.meta.url); var load = other; load("openclaw/plugin-sdk/no");',
73+
'import { createRequire as make } from "node:module"; let require = make(import.meta.url); require = other; require("openclaw/plugin-sdk/no");',
74+
'import { createRequire as make } from "node:module"; const require = make(import.meta.url); function shadow(require) { require("openclaw/plugin-sdk/no"); }',
75+
'function shadow(require) { require("openclaw/plugin-sdk/no"); }',
76+
'import { createRequire as make } from "node:module"; const alias = make; const load = alias(import.meta.url); load("openclaw/plugin-sdk/no");',
77+
'import { createRequire as make } from "node:module"; const load = make(import.meta.url); load("openclaw/plugin-sdk/" + name); load(`openclaw/plugin-sdk/${name}`); receiver.load("openclaw/plugin-sdk/no");',
78+
'import type { createRequire as make } from "node:module"; const load = make(import.meta.url); load("openclaw/plugin-sdk/no");',
79+
// Mutable module-object factories remain outside the supported static contract.
80+
'import * as moduleApi from "node:module"; const load = moduleApi.createRequire(import.meta.url); load("openclaw/plugin-sdk/no");',
81+
'import moduleApi from "module"; const load = moduleApi.createRequire(import.meta.url); load("openclaw/plugin-sdk/no");',
82+
]) assert.deepEqual(collectRuntimeModuleImports(source), [], source);
83+
const incomplete = 'import { createRequire as make } from "node:module"; const load = make(import.meta.url); load("openclaw/plugin-sdk/alias"); require("openclaw/plugin-sdk/retained"); const invalid =';
84+
assert.deepEqual(collectRuntimeModuleImports(incomplete).map(({ specifier, names }) => [specifier, [...names]]),
85+
[["openclaw/plugin-sdk/retained", []]]);
86+
});
87+
1088
test("runtime import names follow declarations through closures and exclude shadowed receivers", () => {
1189
const source = [
1290
'async function handler() { const sdk = await import("openclaw/plugin-sdk/outer");',

‎test/sdk-mock.test.js‎

Lines changed: 54 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -33,6 +33,60 @@ const cjsEntries = {
3333
],
3434
};
3535

36+
for (const rejected of [false, true]) {
37+
test(`createRequire aliases generate SDK modules and retained handlers ${rejected ? "preserve rejection" : "compute values"}`, {
38+
skip: !supportsCommonJsMocks,
39+
}, async (t) => {
40+
const root = await mkdtemp(path.join(os.tmpdir(), "plugin-inspector-require-alias-"));
41+
t.after(() => rm(root, { recursive: true, force: true }));
42+
const source = [
43+
'import { createRequire as nodeCreateRequire } from "node:module";',
44+
'function initializeSchema() {',
45+
'const require_ = nodeCreateRequire(import.meta.url);',
46+
'const { isRecord } = require_("openclaw/plugin-sdk/alias-registration-proof");',
47+
'if (!isRecord({}) || isRecord([])) throw new Error("registration SDK contract missing");',
48+
'}',
49+
'let registered = false;',
50+
'export default { register(api) {',
51+
' initializeSchema();',
52+
' const require_ = nodeCreateRequire(import.meta.url);',
53+
' api.registerGatewayMethod("fixture.alias", ({ respond }) => {',
54+
' if (!registered) throw new Error("handler ran during registration");',
55+
' const sdk = require_("openclaw/plugin-sdk/alias-retained-proof");',
56+
' const read = () => sdk.readStringField({ value: "alias value" }, "value");',
57+
' if (read() !== "alias value") throw new Error("retained SDK contract missing");',
58+
rejected
59+
? ' respond(false, undefined, { code: "UNAVAILABLE", message: read() });'
60+
: ' respond(true, { value: read() });',
61+
' });',
62+
' registered = true;',
63+
'} };',
64+
].join("\n");
65+
await writeFile(path.join(root, "index.mjs"), source);
66+
assert.deepEqual(inspectSourceText(source, "index.mjs").sdkImports.map(({ specifier, line }) => [specifier, line]), [
67+
["openclaw/plugin-sdk/alias-registration-proof", 4],
68+
["openclaw/plugin-sdk/alias-retained-proof", 13],
69+
]);
70+
const options = { cwd: root, pluginRoot: root, mockSdk: true };
71+
assert.equal((await captureEntrypoint("index.mjs", options)).status, "captured");
72+
const result = await runEntrypointSyntheticProbes("index.mjs", options);
73+
assert.deepEqual(result.summary, {
74+
probeCount: 1, passCount: rejected ? 0 : 1, failCount: rejected ? 1 : 0, blockedCount: 0,
75+
});
76+
if (rejected) assert.equal(result.results[0].error, "Gateway response error: alias value");
77+
await writeFile(path.join(root, "bad.mjs"), [
78+
'import { createRequire } from "node:module";',
79+
'const load = createRequire(import.meta.url);',
80+
'load("openclaw/plugin-sdk/alias-failure-proof");',
81+
'throw new Error("alias import failure");',
82+
].join("\n"));
83+
await assert.rejects(captureEntrypoint("bad.mjs", options), /alias import failure/);
84+
// A fresh parent directory bypasses Node's pre-hook require cache while staying in the loader's scope.
85+
assert.throws(() => nodeModule.createRequire(path.join(root, "uncached-parent", "after-capture.cjs"))("openclaw/plugin-sdk/alias-registration-proof"),
86+
{ code: "MODULE_NOT_FOUND" });
87+
});
88+
}
89+
3690
for (const [form, entryLines] of Object.entries(cjsEntries)) {
3791
for (const boundary of ["API", "CLI", "synthetic"]) {
3892
test(`CommonJS ${form} SDK calls execute through ${boundary}`, async (t) => {

0 commit comments

Comments
 (0)