@nodetool-ai/node-sdk 0.7.0-rc.23 → 0.8.2

package/dist/code-analysis.js

@@ -0,0 +1,919 @@
+/**
+ * AST primitives for the body of a Code node (`nodetool.code.Code`).
+ *
+ * A Code node's `code` property is the body of one async function: declared
+ * dynamic inputs arrive on an `inputs` object, and outputs leave through
+ * `emit(name, value)` / `output(name, value)` — or, for a body that calls
+ * neither, through the legacy returned object's keys. Everything a checker
+ * needs to say about such a body —
+ * does it parse, what does it return, which names does it invent — is derived
+ * here, so the graph validator, the code-generation planner and the editor all
+ * read the same AST rather than three approximations of it.
+ *
+ * Pure functions, no I/O: the parser is the only dependency.
+ */
+import * as acorn from "acorn";
+import { isNumber, isObjectLike, isString } from "./type-predicates.js";
+/**
+ * The body is parsed as a module so an `import` reads as an import rather than
+ * as an unexplained syntax error — but the runtime splices the same text into
+ * an async function, where a module declaration is invalid syntax. Callers
+ * reject them explicitly via {@link moduleDeclarationKinds}.
+ */
+const PARSE_OPTIONS = {
+    ecmaVersion: "latest",
+    sourceType: "module",
+    allowReturnOutsideFunction: true,
+    allowAwaitOutsideFunction: true,
+    locations: true
+};
+const MODULE_DECLARATION_TYPES = new Set([
+    "ImportDeclaration",
+    "ExportNamedDeclaration",
+    "ExportDefaultDeclaration",
+    "ExportAllDeclaration"
+]);
+/**
+ * Parse a Code node body into its top-level statement list.
+ *
+ * The body is a bare statement list with `return` at the top level, which most
+ * of the time parses directly. Anything the direct parse rejects gets a second
+ * pass wrapped in an async function, so `await` in odd positions doesn't read
+ * as a syntax error.
+ */
+export function parseCodeBody(code) {
+    try {
+        return { statements: acorn.parse(code, PARSE_OPTIONS).body };
+    }
+    catch (directError) {
+        try {
+            const wrapped = acorn.parse(`(async function(){\n${code}\n})()`, {
+                ...PARSE_OPTIONS,
+                allowReturnOutsideFunction: false
+            });
+            const statement = wrapped.body[0];
+            if (statement?.type === "ExpressionStatement") {
+                const call = statement.expression;
+                if (call.type === "CallExpression" &&
+                    call.callee.type === "FunctionExpression") {
+                    return { statements: call.callee.body.body };
+                }
+            }
+            return { error: "Could not read the code as a function body." };
+        }
+        catch {
+            const message = directError instanceof Error ? directError.message : String(directError);
+            const line = directError.loc?.line;
+            return isNumber(line) ? { error: message, line } : { error: message };
+        }
+    }
+}
+/** `"import"` / `"export"` for every module declaration at the top level. */
+export function moduleDeclarationKinds(statements) {
+    const kinds = new Set();
+    for (const statement of statements) {
+        if (MODULE_DECLARATION_TYPES.has(statement.type)) {
+            kinds.add(statement.type.startsWith("Import") ? "import" : "export");
+        }
+    }
+    return [...kinds];
+}
+/**
+ * Specifiers of the top-level static `import` declarations, in source order.
+ *
+ * These are the only imports the guest loader can serve: it resolves a
+ * specifier the run declared, and nothing else.
+ */
+export function staticImportSpecifiers(statements) {
+    const specifiers = [];
+    for (const statement of statements) {
+        if (statement.type !== "ImportDeclaration")
+            continue;
+        const source = statement.source;
+        if (isString(source.value))
+            specifiers.push(source.value);
+    }
+    return specifiers;
+}
+/**
+ * Specifier plus imported names for every top-level static `import`, in source
+ * order.
+ *
+ * {@link staticImportSpecifiers} answers which modules a body wants;
+ * this answers which of their exports it wants, so a loader can refuse a
+ * misspelled name with the module's own export list instead of leaving the
+ * guest to report "Could not find export".
+ */
+export function staticImportBindings(statements) {
+    const bindings = [];
+    for (const statement of statements) {
+        if (statement.type !== "ImportDeclaration")
+            continue;
+        const source = statement.source;
+        if (!isString(source.value))
+            continue;
+        const named = [];
+        for (const specifier of statement.specifiers) {
+            if (specifier.type !== "ImportSpecifier")
+                continue;
+            const imported = specifier.imported;
+            if (imported.type === "Identifier") {
+                named.push(imported.name);
+            }
+            else if (isString(imported.value)) {
+                named.push(imported.value);
+            }
+        }
+        bindings.push({ specifier: source.value, named });
+    }
+    return bindings;
+}
+/**
+ * The names a module's source exports, or `null` when they cannot be decided.
+ *
+ * `null` means "do not check": the source did not parse, or it carries an
+ * `export * from …` whose names live in another file. A caller that refuses an
+ * import on this list must treat `null` as permission, never as an empty
+ * module.
+ *
+ * Used to turn QuickJS's "Could not find export 'websearch'" — which names
+ * neither the module's exports nor the near miss — into a refusal made before
+ * the guest starts, with both.
+ */
+export function exportedNames(source) {
+    let program;
+    try {
+        program = acorn.parse(source, PARSE_OPTIONS);
+    }
+    catch {
+        return null;
+    }
+    const names = new Set();
+    for (const statement of program.body) {
+        if (statement.type === "ExportAllDeclaration") {
+            // `export * as ns from …` names one export; a bare `export * from …`
+            // forwards an unknowable set.
+            if (statement.exported === null || statement.exported === undefined) {
+                return null;
+            }
+            const exported = statement.exported;
+            if (exported.type === "Identifier")
+                names.add(exported.name);
+            else if (isString(exported.value))
+                names.add(exported.value);
+            continue;
+        }
+        if (statement.type === "ExportDefaultDeclaration") {
+            names.add("default");
+            continue;
+        }
+        if (statement.type !== "ExportNamedDeclaration")
+            continue;
+        for (const specifier of statement.specifiers) {
+            const exported = specifier.exported;
+            if (exported.type === "Identifier")
+                names.add(exported.name);
+            else if (isString(exported.value))
+                names.add(exported.value);
+        }
+        const declaration = statement.declaration;
+        if (declaration === null || declaration === undefined)
+            continue;
+        if (declaration.type === "FunctionDeclaration" ||
+            declaration.type === "ClassDeclaration") {
+            if (declaration.id)
+                names.add(declaration.id.name);
+            continue;
+        }
+        if (declaration.type === "VariableDeclaration") {
+            for (const declarator of declaration.declarations) {
+                patternNames(declarator.id, names);
+            }
+        }
+    }
+    return [...names];
+}
+export function dynamicModuleAccess(statements) {
+    let dynamicImport = false;
+    let require = false;
+    walk(statements, (node) => {
+        if (node.type === "ImportExpression") {
+            dynamicImport = true;
+            return;
+        }
+        if (node.type === "CallExpression" &&
+            node.callee.type === "Identifier" &&
+            node.callee.name === "require") {
+            require = true;
+        }
+    });
+    return { dynamicImport, require };
+}
+function objectKeys(expression) {
+    const keys = new Set();
+    let opaque = false;
+    for (const property of expression.properties) {
+        if (property.type === "SpreadElement") {
+            opaque = true;
+            continue;
+        }
+        if (property.key.type === "Identifier" && !property.computed) {
+            keys.add(property.key.name);
+        }
+        else if (property.key.type === "Literal" &&
+            isString(property.key.value)) {
+            keys.add(property.key.value);
+        }
+        else {
+            // A computed key can be anything at runtime.
+            opaque = true;
+        }
+    }
+    return { keys, opaque, notAnObject: false };
+}
+/**
+ * Shapes a return argument can take. A ternary splits into one shape per
+ * branch, so `return cond ? {a, b} : {a}` is caught on the branch that drops
+ * `b` instead of passing on the union.
+ */
+export function returnShapes(argument) {
+    if (!argument) {
+        return [{ keys: new Set(), opaque: false, notAnObject: true }];
+    }
+    switch (argument.type) {
+        case "ObjectExpression":
+            return [objectKeys(argument)];
+        case "ConditionalExpression":
+            return [
+                ...returnShapes(argument.consequent),
+                ...returnShapes(argument.alternate)
+            ];
+        case "ArrayExpression":
+        case "TemplateLiteral":
+        case "FunctionExpression":
+        case "ArrowFunctionExpression":
+            return [{ keys: new Set(), opaque: false, notAnObject: true }];
+        case "Literal":
+            // `return null` is as wrong as `return 5`; both drop every output.
+            return [{ keys: new Set(), opaque: false, notAnObject: true }];
+        default:
+            // A variable, a call, `await …` — the shape is only known at runtime.
+            return [{ keys: new Set(), opaque: true, notAnObject: false }];
+    }
+}
+/** Node types that own a `return` — the body's own returns stop here. */
+function isFunctionLike(node) {
+    return (node.type === "FunctionDeclaration" ||
+        node.type === "FunctionExpression" ||
+        node.type === "ArrowFunctionExpression");
+}
+function collectReturns(node, out) {
+    if (!isObjectLike(node))
+        return;
+    if (Array.isArray(node)) {
+        for (const item of node)
+            collectReturns(item, out);
+        return;
+    }
+    if (!isString(node.type))
+        return;
+    const astNode = node;
+    // A `return` inside a helper function belongs to that helper, not the body.
+    if (isFunctionLike(astNode))
+        return;
+    if (astNode.type === "ReturnStatement")
+        out.push(astNode);
+    for (const [key, value] of Object.entries(astNode)) {
+        if (key === "type" || key === "start" || key === "end" || key === "loc") {
+            continue;
+        }
+        collectReturns(value, out);
+    }
+}
+/**
+ * Whether a statement can complete normally — i.e. control flows past it.
+ * `return`/`throw` cannot; an `if` without an `else` always can.
+ */
+function completesNormally(statement) {
+    switch (statement.type) {
+        case "ReturnStatement":
+        case "ThrowStatement":
+            return false;
+        case "BlockStatement":
+            return statementsComplete(statement.body);
+        case "IfStatement":
+            if (!statement.alternate)
+                return true;
+            return (completesNormally(statement.consequent) ||
+                completesNormally(statement.alternate));
+        case "TryStatement": {
+            if (statement.finalizer && !statementsComplete(statement.finalizer.body)) {
+                return false;
+            }
+            const blockCompletes = statementsComplete(statement.block.body);
+            if (!statement.handler)
+                return blockCompletes;
+            return blockCompletes || statementsComplete(statement.handler.body.body);
+        }
+        case "SwitchStatement": {
+            // Without a default, an unmatched value skips the whole switch.
+            if (!statement.cases.some((c) => c.test === null))
+                return true;
+            // A `break` lands after the switch, so control continues there.
+            if (statement.cases.some((c) => c.consequent.some((s) => s.type === "BreakStatement"))) {
+                return true;
+            }
+            // Every other case falls through to the next, so only the last one
+            // decides whether control leaves the switch normally.
+            const last = statement.cases[statement.cases.length - 1];
+            return !last || statementsComplete(last.consequent);
+        }
+        case "LabeledStatement":
+            return completesNormally(statement.body);
+        default:
+            // Loops are assumed to terminate: `while (true) { return … }` is rare
+            // enough that treating it as exhaustive would hide real fall-throughs.
+            return true;
+    }
+}
+function statementsComplete(statements) {
+    for (const statement of statements) {
+        if (!completesNormally(statement))
+            return false;
+    }
+    return true;
+}
+/** The body's own `return` statements, and whether control can fall past them. */
+export function analyzeCodeBody(statements) {
+    const returns = [];
+    collectReturns(statements, returns);
+    return { returns, fallsThrough: statementsComplete(statements) };
+}
+/** The two host bridges a body delivers outputs through. */
+export const CODE_OUTPUT_CALLEES = ["emit", "output"];
+/**
+ * Handles the body delivers to via `emit(name, …)` / `output(name, …)`.
+ *
+ * Presence in the AST is the whole rule: a call inside a branch, a loop or a
+ * helper function counts, because the contract is per-handle existence rather
+ * than per-path coverage. `x.output(…)` is a method on something else and is
+ * not counted.
+ */
+export function outputCallNames(statements) {
+    const names = new Set();
+    let nonLiteral = false;
+    walk(statements, (node) => {
+        if (node.type !== "CallExpression")
+            return;
+        if (node.callee.type !== "Identifier")
+            return;
+        if (!CODE_OUTPUT_CALLEES.includes(node.callee.name))
+            return;
+        const first = node.arguments[0];
+        if (first?.type === "Literal" && isString(first.value)) {
+            names.add(first.value);
+            return;
+        }
+        nonLiteral = true;
+    });
+    return { names: [...names], nonLiteral };
+}
+/** The global a body reads its input streams through. */
+export const CODE_STREAM_GLOBAL = "stream";
+/** Members of `stream` that take an input handle name as first argument. */
+const STREAM_NAMED_MEMBERS = ["first", "open"];
+/**
+ * Handles the body takes from via `stream(name)`, `stream.first(name)` and
+ * `stream.open(name)`, plus whether it also uses `stream.any()`.
+ *
+ * Presence in the AST is the whole rule, as for {@link outputCallNames}: a call
+ * inside a branch or a loop counts. `x.stream(…)` is a method on something else,
+ * and a body that binds `stream` itself reports nothing — the calls are that
+ * binding's, not the sandbox's.
+ */
+export function streamCallNames(statements) {
+    if (collectBoundNamesFrom(statements).has(CODE_STREAM_GLOBAL)) {
+        return { names: [], nonLiteral: false, usesAny: false };
+    }
+    const names = new Set();
+    let nonLiteral = false;
+    let usesAny = false;
+    walk(statements, (node) => {
+        if (node.type !== "CallExpression")
+            return;
+        const callee = node.callee;
+        if (callee.type === "Identifier" && callee.name === CODE_STREAM_GLOBAL) {
+            addStreamName(node.arguments[0]);
+            return;
+        }
+        if (callee.type !== "MemberExpression" ||
+            callee.computed ||
+            callee.object.type !== "Identifier" ||
+            callee.object.name !== CODE_STREAM_GLOBAL ||
+            callee.property.type !== "Identifier") {
+            return;
+        }
+        if (callee.property.name === "any") {
+            usesAny = true;
+            return;
+        }
+        if (STREAM_NAMED_MEMBERS.includes(callee.property.name)) {
+            addStreamName(node.arguments[0]);
+        }
+    });
+    function addStreamName(first) {
+        if (first?.type === "Literal" && isString(first.value)) {
+            names.add(first.value);
+            return;
+        }
+        nonLiteral = true;
+    }
+    return { names: [...names], nonLiteral, usesAny };
+}
+/** Names a binding pattern introduces (`const { a, b: [c] } = x`). */
+function patternNames(pattern, out) {
+    if (pattern == null)
+        return;
+    const node = pattern;
+    switch (node.type) {
+        case "Identifier":
+            out.add(node.name);
+            return;
+        case "ObjectPattern":
+            for (const property of node.properties) {
+                patternNames(property.type === "RestElement" ? property.argument : property.value, out);
+            }
+            return;
+        case "ArrayPattern":
+            for (const element of node.elements)
+                patternNames(element, out);
+            return;
+        case "AssignmentPattern":
+            patternNames(node.left, out);
+            return;
+        case "RestElement":
+            patternNames(node.argument, out);
+            return;
+        default:
+            return;
+    }
+}
+const isAstNode = (value) => typeof value === "object" &&
+    value !== null &&
+    typeof value.type === "string";
+/** Depth-first walk, passing each node with its ancestor chain (root first). */
+function walk(root, visit, ancestors = []) {
+    if (Array.isArray(root)) {
+        for (const item of root)
+            walk(item, visit, ancestors);
+        return;
+    }
+    if (!isAstNode(root))
+        return;
+    visit(root, [...ancestors, root]);
+    ancestors.push(root);
+    for (const [key, value] of Object.entries(root)) {
+        if (key === "type" || key === "start" || key === "end" || key === "loc") {
+            continue;
+        }
+        walk(value, visit, ancestors);
+    }
+    ancestors.pop();
+}
+function collectBoundNamesFrom(statements) {
+    const names = new Set();
+    walk(statements, (node) => {
+        switch (node.type) {
+            case "VariableDeclarator":
+                patternNames(node.id, names);
+                break;
+            case "FunctionDeclaration":
+            case "FunctionExpression":
+            case "ArrowFunctionExpression":
+                if ("id" in node && node.id)
+                    names.add(node.id.name);
+                for (const param of node.params)
+                    patternNames(param, names);
+                break;
+            case "ClassDeclaration":
+            case "ClassExpression":
+                if (node.id)
+                    names.add(node.id.name);
+                break;
+            case "CatchClause":
+                if (node.param)
+                    patternNames(node.param, names);
+                break;
+            case "ImportDeclaration":
+                for (const specifier of node.specifiers) {
+                    names.add(specifier.local.name);
+                }
+                break;
+            case "AssignmentExpression":
+                // The body runs non-strict, so `x = 1` on an undeclared name creates a
+                // global instead of throwing. Reading it afterwards is legal.
+                patternNames(node.left, names);
+                break;
+            default:
+                break;
+        }
+    });
+    return names;
+}
+/**
+ * Every name the code itself binds — variables, functions, classes, parameters,
+ * catch clauses, and undeclared assignment targets. A reference to anything
+ * else has to come from the sandbox or from a dynamic input, so this is the
+ * allowlist a caller subtracts before deciding a name was invented.
+ */
+export function collectBoundNames(code) {
+    const parsed = parseCodeBody(code);
+    if ("error" in parsed)
+        return [];
+    return [...collectBoundNamesFrom(parsed.statements)];
+}
+/**
+ * Names the code tests with `typeof`. `typeof x` is the one read that never
+ * throws on a missing binding, so a name guarded anywhere in the body is one
+ * the author already treats as optional — a caller deciding whether a name is
+ * undefined has to subtract these.
+ */
+export function typeofGuardedNames(statements) {
+    const guarded = new Set();
+    walk(statements, (node) => {
+        if (node.type === "UnaryExpression" &&
+            node.operator === "typeof" &&
+            node.argument.type === "Identifier") {
+            guarded.add(node.argument.name);
+        }
+    });
+    return guarded;
+}
+/** The global every declared input of a Code node arrives on. */
+export const CODE_INPUTS_GLOBAL = "inputs";
+/**
+ * Input names the body reads off the `inputs` global, and whether it also
+ * reaches for the object in a way this analysis cannot resolve to names.
+ *
+ * `inputs.text` and `inputs["text"]` both count. A dynamic read
+ * (`inputs[key]`), a spread, or passing `inputs` somewhere sets `opaque`:
+ * the body uses inputs the reader cannot enumerate, so a caller must not
+ * conclude an undeclared slot is unused. A body that shadows `inputs` with
+ * its own binding reports nothing — the reads are that binding's, not the
+ * node's.
+ */
+export function inputsMemberReads(statements) {
+    if (collectBoundNamesFrom(statements).has(CODE_INPUTS_GLOBAL)) {
+        return { names: [], opaque: false };
+    }
+    const names = new Set();
+    let opaque = false;
+    walk(statements, (node, ancestors) => {
+        if (node.type !== "Identifier" || node.name !== CODE_INPUTS_GLOBAL)
+            return;
+        const parent = ancestors[ancestors.length - 2];
+        // A property *named* `inputs` (`opts.inputs`, `{inputs: 1}`) is not the
+        // global. `inputs.x` is, and there `inputs` is the object, not the
+        // property.
+        if (parent?.type === "MemberExpression") {
+            if (parent.property === node && !parent.computed)
+                return;
+            if (parent.object === node) {
+                if (!parent.computed && parent.property.type === "Identifier") {
+                    names.add(parent.property.name);
+                    return;
+                }
+                if (parent.computed &&
+                    parent.property.type === "Literal" &&
+                    isString(parent.property.value)) {
+                    names.add(parent.property.value);
+                    return;
+                }
+                // `inputs[key]` — a real read of a name only the runtime knows.
+                opaque = true;
+                return;
+            }
+        }
+        if (parent?.type === "Property" && parent.key === node && !parent.computed) {
+            return;
+        }
+        // `{...inputs}`, `f(inputs)`, `Object.keys(inputs)` — the whole bag leaves.
+        opaque = true;
+    });
+    return { names: [...names], opaque };
+}
+/**
+ * Identifier *reads* — occurrences that resolve against the scope chain.
+ * Property names, object keys and labels are excluded: none of them resolve,
+ * so none of them can throw a ReferenceError.
+ *
+ * Positions come along because the migration rewrites these occurrences in
+ * place; sharing one collector keeps "what counts as a read" from drifting
+ * between the check and the rewrite.
+ */
+function identifierReads(statements) {
+    const reads = [];
+    walk(statements, (node, ancestors) => {
+        if (node.type !== "Identifier")
+            return;
+        const parent = ancestors[ancestors.length - 2];
+        if (!parent)
+            return;
+        switch (parent.type) {
+            case "MemberExpression":
+                if (parent.property === node && !parent.computed)
+                    return;
+                break;
+            case "Property":
+                if (parent.key === node && !parent.computed && !parent.shorthand) {
+                    return;
+                }
+                break;
+            case "MethodDefinition":
+            case "PropertyDefinition":
+                if (parent.key === node && !parent.computed)
+                    return;
+                break;
+            case "LabeledStatement":
+                if (parent.label === node)
+                    return;
+                break;
+            case "BreakStatement":
+            case "ContinueStatement":
+                if (parent.label === node)
+                    return;
+                break;
+            case "MetaProperty":
+                return;
+            case "ImportSpecifier":
+            case "ImportDefaultSpecifier":
+            case "ImportNamespaceSpecifier":
+            case "ExportSpecifier":
+                return;
+            case "VariableDeclarator":
+                if (parent.id === node)
+                    return;
+                break;
+            case "UnaryExpression":
+                // `typeof maybeMissing` is a read, but never a ReferenceError — see
+                // {@link typeofGuardedNames}.
+                break;
+            case "FunctionDeclaration":
+            case "FunctionExpression":
+            case "ClassDeclaration":
+            case "ClassExpression":
+                if (parent.id === node)
+                    return;
+                break;
+            default:
+                break;
+        }
+        reads.push({
+            name: node.name,
+            start: node.start,
+            end: node.end,
+            shorthand: parent.type === "Property" && parent.shorthand === true
+        });
+    });
+    // A shorthand property's `key` and `value` are the same node, so the walk
+    // reaches the occurrence twice. One position is one read.
+    const seen = new Set();
+    return reads.filter((read) => {
+        if (seen.has(read.start))
+            return false;
+        seen.add(read.start);
+        return true;
+    });
+}
+/**
+ * Identifiers the code reads without binding them. Property names, object
+ * keys and labels are excluded: none of them resolve against the scope chain,
+ * so none of them can throw a ReferenceError.
+ */
+export function freeIdentifiers(statements) {
+    const bound = collectBoundNamesFrom(statements);
+    const names = new Set(identifierReads(statements).map((read) => read.name));
+    return [...names].filter((name) => !bound.has(name));
+}
+/**
+ * Rewrite a pre-`inputs` Code node body: every free read of a declared input
+ * becomes `inputs.<name>`.
+ *
+ * Inputs used to arrive as globals of their own name. Bodies written that way
+ * throw a ReferenceError now, so this is the mechanical half of that move —
+ * offsets come from the AST, so a name inside a string or a comment, an object
+ * key, or a locally shadowed binding is left alone.
+ *
+ * Returns the rewritten source and the names it touched. `changed` is false
+ * when there was nothing to do, when the body does not parse, or when it binds
+ * `inputs` itself — rewriting into a shadowed name would silently change which
+ * object is read.
+ */
+export function migrateCodeBodyToInputs(code, inputNames) {
+    const unchanged = { code, changed: false, rewritten: [] };
+    const targets = new Set(inputNames);
+    if (targets.size === 0)
+        return unchanged;
+    const parsed = parseCodeBody(code);
+    if ("error" in parsed)
+        return unchanged;
+    const bound = collectBoundNamesFrom(parsed.statements);
+    if (bound.has(CODE_INPUTS_GLOBAL))
+        return unchanged;
+    const edits = identifierReads(parsed.statements).filter((read) => targets.has(read.name) && !bound.has(read.name));
+    if (edits.length === 0)
+        return unchanged;
+    // Apply back to front so earlier offsets stay valid.
+    let out = code;
+    for (const edit of [...edits].sort((a, b) => b.start - a.start)) {
+        const replacement = edit.shorthand
+            ? `${edit.name}: ${CODE_INPUTS_GLOBAL}.${edit.name}`
+            : `${CODE_INPUTS_GLOBAL}.${edit.name}`;
+        out = out.slice(0, edit.start) + replacement + out.slice(edit.end);
+    }
+    return {
+        code: out,
+        changed: true,
+        rewritten: [...new Set(edits.map((e) => e.name))].sort()
+    };
+}
+/**
+ * Property names the Code node itself owns. A body that reads `inputs.code`
+ * is not naming a user handle — it is colliding with the editor field.
+ */
+export const CODE_NODE_OWN_PROPERTIES = new Set([
+    "code",
+    "script",
+    "packages",
+    "secrets",
+    "timeout",
+    "max_response_mb",
+    "allow_local_network",
+    "allow_host_filesystem"
+]);
+function isUserHandleName(name) {
+    return name !== "" && !CODE_NODE_OWN_PROPERTIES.has(name);
+}
+/**
+ * Input handle names the body itself names: `inputs.foo` / `inputs["foo"]`
+ * and `stream("foo")` / `stream.first("foo")` / `stream.open("foo")`.
+ *
+ * A named read is a handle. The editor shows it and an agent can connect to
+ * it without a separate "add dynamic input" step.
+ */
+export function inferredCodeInputNames(code) {
+    const parsed = parseCodeBody(code);
+    if ("error" in parsed)
+        return [];
+    const names = new Set();
+    for (const name of inputsMemberReads(parsed.statements).names) {
+        if (isUserHandleName(name))
+            names.add(name);
+    }
+    for (const name of streamCallNames(parsed.statements).names) {
+        if (isUserHandleName(name))
+            names.add(name);
+    }
+    return [...names];
+}
+/**
+ * Output handle names the body itself names: `emit("foo")` / `output("foo")`,
+ * or — when the body uses neither — the keys of the last `return { … }`.
+ */
+export function inferredCodeOutputNames(code) {
+    const parsed = parseCodeBody(code);
+    if ("error" in parsed)
+        return [];
+    const emitted = outputCallNames(parsed.statements);
+    if (emitted.names.length > 0) {
+        return emitted.names.filter(isUserHandleName);
+    }
+    const { returns } = analyzeCodeBody(parsed.statements);
+    for (let i = returns.length - 1; i >= 0; i--) {
+        const shapes = returnShapes(returns[i].argument);
+        if (shapes.length !== 1)
+            continue;
+        const shape = shapes[0];
+        if (shape.opaque || shape.notAnObject || shape.keys.size === 0)
+            continue;
+        return [...shape.keys].filter(isUserHandleName);
+    }
+    return [];
+}
+/** Hosts of model APIs a planned Code step must not call itself. */
+const MODEL_API_HOSTS = [
+    "api.openai.com",
+    "api.anthropic.com",
+    "generativelanguage.googleapis.com",
+    "openrouter.ai",
+    "api.mistral.ai",
+    "api.groq.com",
+    "api.together.xyz",
+    "api.deepseek.com"
+];
+/** Host calls that return a promise; a body that does not await one holds a Promise. */
+const ASYNC_HOST_GLOBALS = new Set(["getSecret", "fetch", "sleep"]);
+const ASYNC_HOST_OBJECTS = new Set(["workspace", "media"]);
+/** The host call a `const x = <call>` initializer makes without `await`, if any. */
+function unawaitedHostCall(init) {
+    if (init?.type !== "CallExpression")
+        return null;
+    const callee = init.callee;
+    if (callee.type === "Identifier" && ASYNC_HOST_GLOBALS.has(callee.name)) {
+        return callee.name;
+    }
+    if (callee.type === "MemberExpression" &&
+        callee.object.type === "Identifier" &&
+        ASYNC_HOST_OBJECTS.has(callee.object.name) &&
+        callee.property.type === "Identifier") {
+        return `${callee.object.name}.${callee.property.name}`;
+    }
+    return null;
+}
+const LOOP_TYPES = new Set([
+    "ForStatement",
+    "ForInStatement",
+    "ForOfStatement",
+    "WhileStatement",
+    "DoWhileStatement"
+]);
+/** A function handed to a call — `rows.forEach(row => …)` runs per item. */
+function isCallbackArgument(node, parent) {
+    return ((node.type === "ArrowFunctionExpression" ||
+        node.type === "FunctionExpression") &&
+        parent?.type === "CallExpression" &&
+        parent.arguments.includes(node));
+}
+/**
+ * What would make a Code step the workflow planner wrote fail or pass nothing
+ * on, checked before anything runs.
+ *
+ * `inputs` are the handles the build connects, `output` the handle the next
+ * step reads. Each problem is a sentence the planner can act on: the repair
+ * round sends them back verbatim.
+ */
+export function plannedCodeStepProblems(code, handles) {
+    const parsed = parseCodeBody(code);
+    if ("error" in parsed) {
+        return [`its code does not parse: ${parsed.error}`];
+    }
+    const problems = [];
+    let outputInLoop = false;
+    walk(parsed.statements, (node, ancestors) => {
+        if (outputInLoop || node.type !== "CallExpression")
+            return;
+        if (node.callee.type !== "Identifier" || node.callee.name !== "output") {
+            return;
+        }
+        outputInLoop = ancestors.some((ancestor, index) => LOOP_TYPES.has(ancestor.type) ||
+            isCallbackArgument(ancestor, ancestors[index - 1]));
+    });
+    if (outputInLoop) {
+        problems.push("it calls output() once per item, but output() can be set only once per run — " +
+            "call await emit(name, item) per item, or collect the items and call output() once after the loop");
+    }
+    const wired = new Set(handles.inputs);
+    const memberReads = inputsMemberReads(parsed.statements);
+    const streamReads = streamCallNames(parsed.statements);
+    const unwired = memberReads.names
+        .filter(isUserHandleName)
+        .filter((name) => !wired.has(name));
+    if (unwired.length > 0) {
+        problems.push(`it reads ${unwired.map((name) => `inputs.${name}`).join(", ")}, but the only connected ` +
+            `input${handles.inputs.length === 1 ? " is" : "s are"} ${handles.inputs.length > 0
+                ? handles.inputs.map((name) => `inputs.${name}`).join(", ")
+                : "none"}`);
+    }
+    // A connected input the body never names carries a value nowhere. Skipped
+    // when the body reads `inputs` as a whole or by a computed key.
+    if (!memberReads.opaque && !streamReads.nonLiteral && !streamReads.usesAny) {
+        const read = new Set([...memberReads.names, ...streamReads.names]);
+        const unread = handles.inputs.filter((name) => !read.has(name));
+        if (unread.length > 0) {
+            problems.push(`${unread.map((name) => `inputs.${name}`).join(", ")} ${unread.length === 1 ? "is" : "are"} connected, but the body never reads ${unread.length === 1 ? "it" : "them"}`);
+        }
+    }
+    const unawaited = new Set();
+    walk(parsed.statements, (node) => {
+        if (node.type !== "VariableDeclarator")
+            return;
+        const call = unawaitedHostCall(node.init);
+        if (call !== null)
+            unawaited.add(call);
+    });
+    if (unawaited.size > 0) {
+        problems.push(`it assigns ${[...unawaited].map((name) => `${name}()`).join(", ")} without await, so the variable holds a Promise`);
+    }
+    const modelHost = MODEL_API_HOSTS.find((host) => code.includes(host));
+    if (modelHost !== undefined) {
+        problems.push(`it calls the model API at ${modelHost} itself; put the model call in its own step with a model_role`);
+    }
+    const outputs = inferredCodeOutputNames(code);
+    if (!outputs.includes(handles.output)) {
+        problems.push(outputs.length === 0
+            ? `it never sets "${handles.output}", so the next step receives nothing`
+            : `it sets ${outputs.map((name) => `"${name}"`).join(", ")}, but the next step reads "${handles.output}"`);
+    }
+    return problems;
+}
+//# sourceMappingURL=code-analysis.js.map