deepline 0.3.422 → 0.3.424

package/dist/bundling-sources/shared_libs/plays/script-entry.ts

@@ -0,0 +1,992 @@
+/**
+ * Script plays: a play file the runtime runs as written.
+ *
+ *   import deepline from 'deepline';
+ *   export default async function ({ domain }: { domain: string }) {
+ *     return { company: await deepline.tools.execute({ ... }) };
+ *   }
+ *
+ * The whole module body runs inside the run, with `deepline` bound to it (the
+ * SDK's `runScriptPlay`). The play's result is, in order: what a top-level
+ * call to the default-exported function returned; else what calling that
+ * function with the input returns; else a top-level `return`, else
+ * `deepline.output(...)`, else `{}`. So a file that is top-level code, a
+ * default-exported function of the input, or both runs as one play, and
+ * nothing the author wrote is rewritten beyond turning its default export
+ * into a local binding on the same line.
+ */
+import { basename } from 'node:path';
+import { isAstNode, TypeScriptParser, type AstNode } from './ts-ast';
+
+export const SCRIPT_SDK = 'deepline';
+/** A play file: `lookup.play.ts`, `.play.js`, `.play.mts`, ... */
+export const PLAY_FILE_PATTERN = /\.play\.[cm]?[jt]sx?$/i;
+const DEFINE_CALLEES = new Set(['definePlay', 'defineWorkflow']);
+const FUNCTION_TYPES = new Set([
+  'FunctionDeclaration',
+  'FunctionExpression',
+  'ArrowFunctionExpression',
+]);
+/** Statements that stay at module scope: imports, and the types an input type may name. */
+const MODULE_SCOPE = new Set([
+  'ImportDeclaration',
+  'TSTypeAliasDeclaration',
+  'TSInterfaceDeclaration',
+]);
+const DECLARATION_TYPES = new Set([
+  'FunctionDeclaration',
+  'TSDeclareFunction',
+  'ClassDeclaration',
+  'TSTypeAliasDeclaration',
+  'TSInterfaceDeclaration',
+  'TSEnumDeclaration',
+]);
+const UNWRAPPED_TYPES = new Set([
+  'TSAsExpression',
+  'TSSatisfiesExpression',
+  'TSTypeAssertion',
+  'ParenthesizedExpression',
+  'AwaitExpression',
+]);
+/**
+ * Code a top-level call to the entry may sit under and still not run on
+ * every pass: `if (import.meta.main) main()` is left to the dispatch.
+ */
+const CONDITIONAL_TYPES = new Set([
+  ...FUNCTION_TYPES,
+  'ClassDeclaration',
+  'ClassExpression',
+  'IfStatement',
+  'ConditionalExpression',
+  'LogicalExpression',
+  'SwitchStatement',
+  'ForStatement',
+  'ForInStatement',
+  'ForOfStatement',
+  'WhileStatement',
+  'DoWhileStatement',
+  'CatchClause',
+]);
+
+/** Where a script's optional calls are, for analyzers that read scripts. */
+type ScriptPlayParts = {
+  /**
+   * The play's config object literal: `export const config = {...}`, or the
+   * one passed to `deepline.config(...)`.
+   */
+  config: AstNode | null;
+  /** The entry's input parameter type, else the `T` of `deepline.input<T>()`. */
+  inputType: AstNode | null;
+  /**
+   * The play's result values, in source order: the entry's own returns, or
+   * without an entry each top-level `return value`; and each
+   * `deepline.output(value)`.
+   */
+  outputs: AstNode[];
+};
+
+/** The module's default-exported function of the input, which the runtime calls. */
+export type PlayEntry = {
+  /** The function itself. */
+  node: AstNode;
+  /** What module code calls it by; null when it is anonymous. */
+  name: string | null;
+  /**
+   * `declaration`: `export default [async] function [name](input) {}`.
+   * `expression`: `export default <function or arrow>`.
+   * `binding`: `export default name`, `name` a top-level function.
+   * `specifier`: `export { name as default }`.
+   */
+  exportedAs: 'declaration' | 'expression' | 'binding' | 'specifier';
+  /** The export statement. */
+  exportStatement: AstNode;
+  /** The top-level statement declaring a `binding`/`specifier` entry. */
+  declaration: AstNode | null;
+};
+
+/** A script play; its nodes carry `start`/`end` spans over the source. */
+export type ScriptPlay = ScriptPlayParts & {
+  /** The default-exported play function, or null for top-level code alone. */
+  entry: PlayEntry | null;
+  /**
+   * The module's own unconditional top-level call to the entry, such as
+   * `await main()`: its value is the result and the entry is not called again.
+   */
+  entryCall: AstNode | null;
+  /**
+   * The play's own code: top-level statements after the header, without
+   * types, config, the entry's declaration and the statement calling it,
+   * followed by the entry's body.
+   */
+  code: AstNode[];
+  /** What the script calls the runtime: `deepline`, or its own default-import name. */
+  contextName: string;
+  /** Where the leading imports and types end: 0 when there are none. */
+  headerEnd: number;
+  /**
+   * Set when the play's code, besides its `config`/`input` calls and
+   * declarations, is only `return [await] handler(deepline, input)`: the play
+   * delegates to `handler`, which takes the runtime as `ctx` would.
+   */
+  delegate: { handlerName: string } | null;
+};
+
+/**
+ * The file `deepline plays run -e '<code>'` writes and runs. A one-off inline
+ * play is the only play whose tool calls may omit `description`.
+ */
+export const INLINE_PLAY_FILE = '.inline.play.ts';
+
+/** Leading import statements, as `plays run -e` code may begin. */
+const LEADING_IMPORT =
+  /^\s*import\s+(?:[\w$*{}\s,]+?\s+from\s+)?['"][^'"]+['"]\s*;?/;
+
+/**
+ * The `.inline.play.ts` text for `plays run -e '<code>'`. The code is the body
+ * of the play function, with `input` holding `--input`; its leading imports
+ * stay at module scope and `deepline` is imported when it is not. Code that
+ * already default-exports its play is written as-is. Every line keeps its
+ * number, so errors point at what was typed.
+ */
+export function inlinePlaySource(code: string): string {
+  let header = '';
+  let body = code;
+  for (let match = LEADING_IMPORT.exec(body); match; ) {
+    header += match[0];
+    body = body.slice(match[0].length);
+    match = LEADING_IMPORT.exec(body);
+  }
+  const runtimeImport =
+    /\bimport\s+\w+\s*(,\s*\{[^}]*\}\s*)?from\s+['"]deepline['"]/.test(header)
+      ? ''
+      : `import ${SCRIPT_SDK} from '${SCRIPT_SDK}'; `;
+  if (/\bexport\s+default\b/.test(code)) return runtimeImport + code;
+  return `${runtimeImport}${header}export default async function (input: any) {${body}\n}\n`;
+}
+
+export function isInlinePlayFile(filePath: string): boolean {
+  return basename(filePath) === INLINE_PLAY_FILE;
+}
+
+/** `lookup.play.ts` → `lookup`; `.inline.play.ts` → `inline`. */
+export function playNameFromPath(filePath: string): string {
+  return basename(filePath)
+    .replace(/^\.+/, '')
+    .replace(/(\.play)?\.[cm]?[jt]sx?$/, '');
+}
+
+/**
+ * The script play in `source`, or null when it is not one: it calls
+ * definePlay, exports something besides a default, or default-exports a
+ * context-first `(ctx, input)` handler. Unparseable source is left to the
+ * normal pipeline unless it is evidently a script; then the syntax error, with
+ * its line, is the author's real problem.
+ */
+export function parseScriptPlay(source: string): ScriptPlay | null {
+  const program = programOf(source);
+  const form = program ? playForm(program) : null;
+  if (!program || !form) return null;
+  const { entry } = form;
+  const header = headerOf(program);
+  const contextName = defaultImportName(header.find(isSdkImport)) ?? SCRIPT_SDK;
+  const parts = scriptPlayParts(program, contextName, entry?.node ?? null);
+  const configExport = configExportOf(program);
+  const headerEnd = (header.at(-1)?.end as number | undefined) ?? 0;
+  const [entryCall = null] = entry ? entryCallsOf(program, entry) : [];
+  const callStatement = entryCall
+    ? (program.body as AstNode[]).find(
+        (node) =>
+          (node.start as number) <= (entryCall.start as number) &&
+          (node.end as number) >= (entryCall.end as number),
+      )
+    : undefined;
+  const excluded = new Set(
+    [
+      entry?.exportStatement,
+      entry?.declaration,
+      callStatement,
+      configExport,
+    ].filter(Boolean),
+  );
+  const moduleCode = (program.body as AstNode[]).slice(header.length).filter(
+    (node) =>
+      !excluded.has(node) &&
+      !MODULE_SCOPE.has(node.type) &&
+      !(
+        node.type === 'ExpressionStatement' &&
+        scriptCallName(unwrapped(node.expression), contextName) === 'config'
+      ) &&
+      // Beside a play function, module code that neither awaits nor uses
+      // the runtime only names values and helpers, as a definePlay file's
+      // module scope does.
+      (!entry || usesRuntime(node, contextName)),
+  );
+  const body = entry?.node.body as AstNode | undefined;
+  const code = [
+    ...moduleCode,
+    ...(body?.type === 'BlockStatement' ? (body.body as AstNode[]) : []),
+  ];
+  const [parameter] = (entry?.node.params as AstNode[] | undefined) ?? [];
+  return {
+    entry,
+    entryCall,
+    code,
+    contextName,
+    headerEnd,
+    delegate: delegateOf(code, contextName),
+    config: (configExport && configObjectOf(configExport)) ?? parts.config,
+    // The entry's parameter is its input; `(input) => ({ ... })` returns its
+    // expression.
+    inputType: parameterType(parameter) ?? parts.inputType,
+    outputs: body && body.type !== 'BlockStatement' ? [body] : parts.outputs,
+  };
+}
+
+/**
+ * What a play file calls its runtime: `ctx`, `deepline`, and the file's
+ * default import from `deepline`. A seed: analyzers add the handler and
+ * resolver parameters they discover.
+ */
+export function playRuntimeNames(source: string): ReadonlySet<string> {
+  const program = programOf(source);
+  const imported = program
+    ? (program.body as AstNode[]).filter(isSdkImport).map(defaultImportName)
+    : [];
+  return new Set([
+    'ctx',
+    SCRIPT_SDK,
+    ...imported.filter((name): name is string => name !== null),
+  ]);
+}
+
+/** A runtime name, or by convention any name ending in `Ctx`. */
+export function isRuntimeReceiver(
+  name: string,
+  runtimeNames: ReadonlySet<string>,
+): boolean {
+  return runtimeNames.has(name) || name.endsWith('Ctx');
+}
+
+/**
+ * `{ handlerName }` when `code`, without its `config`/`input` signature
+ * statements and declarations, is only `return [await] handler(ctx, ...)`.
+ */
+function delegateOf(
+  code: AstNode[],
+  contextName: string,
+): ScriptPlay['delegate'] {
+  const [statement, extra] = code.filter(
+    (node) =>
+      !isSignatureStatement(node, contextName) && !isDeclarationOnly(node),
+  );
+  if (extra || statement?.type !== 'ReturnStatement') return null;
+  const returned = statement.argument;
+  const call =
+    isAstNode(returned) && returned.type === 'AwaitExpression'
+      ? returned.argument
+      : returned;
+  if (!isAstNode(call) || call.type !== 'CallExpression') return null;
+  const [runtime] = call.arguments as AstNode[];
+  return isAstNode(call.callee) &&
+    call.callee.type === 'Identifier' &&
+    runtime?.type === 'Identifier' &&
+    (runtime.name === 'ctx' || runtime.name === contextName)
+    ? { handlerName: call.callee.name as string }
+    : null;
+}
+
+/** `deepline.config({...});` or `const x = deepline.input();`. */
+function isSignatureStatement(node: AstNode, contextName: string): boolean {
+  if (node.type === 'ExpressionStatement') {
+    return scriptCallName(unwrapped(node.expression), contextName) === 'config';
+  }
+  if (node.type !== 'VariableDeclaration') return false;
+  const declarations = node.declarations as AstNode[];
+  return (
+    declarations.length === 1 &&
+    scriptCallName(unwrapped(declarations[0]!.init), contextName) === 'input'
+  );
+}
+
+/** Functions, classes, types, and `const LIMIT = 100`: names, not work. */
+function isDeclarationOnly(node: AstNode): boolean {
+  if (DECLARATION_TYPES.has(node.type)) return true;
+  return (
+    node.type === 'VariableDeclaration' &&
+    node.kind === 'const' &&
+    (node.declarations as AstNode[]).every(
+      (declarator) =>
+        isAstNode(declarator.init) && isLiteralValue(declarator.init),
+    )
+  );
+}
+
+/** A string, number, bigint or regex literal, or a template without `${}`. */
+function isLiteralValue(node: AstNode): boolean {
+  return node.type === 'TemplateLiteral'
+    ? (node.expressions as AstNode[]).length === 0
+    : node.type === 'Literal' &&
+        (node.regex !== undefined ||
+          ['string', 'number', 'bigint'].includes(typeof node.value));
+}
+
+/** `x` without `as`/`satisfies`/`<T>` assertions, parentheses and `await`. */
+function unwrapped(node: unknown): AstNode | null {
+  let current = isAstNode(node) ? node : null;
+  while (current && UNWRAPPED_TYPES.has(current.type)) {
+    const inner = current.expression ?? current.argument;
+    current = isAstNode(inner) ? inner : null;
+  }
+  return current;
+}
+
+function parameterType(parameter: AstNode | undefined): AstNode | null {
+  // `(input: T = {})` annotates the pattern on the left of the default.
+  const target =
+    parameter?.type === 'AssignmentPattern' ? parameter.left : parameter;
+  const annotation = isAstNode(target) ? target.typeAnnotation : null;
+  return isAstNode(annotation) && isAstNode(annotation.typeAnnotation)
+    ? annotation.typeAnnotation
+    : null;
+}
+
+function scriptPlayParts(
+  program: AstNode,
+  contextName: string,
+  playFunction: AstNode | null,
+): ScriptPlayParts {
+  const parts: ScriptPlayParts = { config: null, inputType: null, outputs: [] };
+  const visit = (node: AstNode, insideFunction: boolean): void => {
+    if (
+      node.type === 'ReturnStatement' &&
+      !insideFunction &&
+      isAstNode(node.argument)
+    ) {
+      parts.outputs.push(node.argument);
+    }
+    const call = scriptCallName(node, contextName);
+    const [argument] = Array.isArray(node.arguments)
+      ? node.arguments.filter(isAstNode)
+      : [];
+    if (call === 'config' && argument?.type === 'ObjectExpression') {
+      parts.config ??= argument;
+    } else if (call === 'input') {
+      parts.inputType ??= typeArgument(node);
+    } else if (call === 'output' && argument) {
+      parts.outputs.push(argument);
+    }
+    // The play's own returns: top-level ones in a script, the play function's
+    // own in function form; any other function's returns are its own.
+    const nested =
+      node === playFunction
+        ? false
+        : insideFunction || FUNCTION_TYPES.has(node.type);
+    childNodes(node).forEach((child) => visit(child, nested));
+  };
+  visit(program, playFunction !== null);
+  return parts;
+}
+
+/** Whether `node` awaits or reaches the runtime, outside nested functions. */
+function usesRuntime(node: AstNode, contextName: string): boolean {
+  if (
+    node.type === 'AwaitExpression' ||
+    (node.type === 'Identifier' && node.name === contextName)
+  ) {
+    return true;
+  }
+  if (FUNCTION_TYPES.has(node.type)) return false;
+  return childNodes(node).some((child) => usesRuntime(child, contextName));
+}
+
+/** `config`, `input` or `output` when `node` is `<contextName>.<that>(...)`. */
+function scriptCallName(
+  node: AstNode | null,
+  contextName: string,
+): 'config' | 'input' | 'output' | null {
+  if (node?.type !== 'CallExpression' || !isAstNode(node.callee)) return null;
+  const callee = node.callee;
+  if (
+    callee.type !== 'MemberExpression' ||
+    callee.computed ||
+    !isAstNode(callee.object) ||
+    callee.object.type !== 'Identifier' ||
+    callee.object.name !== contextName ||
+    !isAstNode(callee.property)
+  ) {
+    return null;
+  }
+  const name = callee.property.name;
+  return name === 'config' || name === 'input' || name === 'output'
+    ? name
+    : null;
+}
+
+function typeArgument(call: AstNode): AstNode | null {
+  const instantiation = call.typeArguments ?? call.typeParameters;
+  return isAstNode(instantiation) && Array.isArray(instantiation.params)
+    ? (instantiation.params.find(isAstNode) ?? null)
+    : null;
+}
+
+/**
+ * The play module as the function the runner calls: imports stay at module
+ * scope and the rest of the module runs inside `runScriptPlay`, its default
+ * export a local binding, then the entry is dispatched. Every edit stays on
+ * its line, so every author line keeps its number.
+ */
+export function wrapScriptPlay(
+  source: string,
+  script: ScriptPlay,
+  { typed }: { typed: boolean },
+): string {
+  const { entry, entryCall } = script;
+  // TypeScript sources annotate what they declare, so the wrapped form also
+  // type-checks under noImplicitAny.
+  const unknownType = typed ? ': unknown' : '';
+  const anyType = typed ? ': any' : '';
+  const runtimeImport = defaultImportName(
+    headerOf(programOf(source)!).find(isSdkImport),
+  )
+    ? `import { runScriptPlay as __deeplineRunScriptPlay } from '${SCRIPT_SDK}';`
+    : `import ${SCRIPT_SDK}, { runScriptPlay as __deeplineRunScriptPlay } from '${SCRIPT_SDK}';`;
+  const entryBindings = entry
+    ? ` let __deeplineEntry${anyType}; let __deeplineEntryResult${anyType};`
+    : '';
+  const prefix =
+    `${runtimeImport} export default async function (__deeplineContext${unknownType}, __deeplineInput${anyType}) {` +
+    ` return __deeplineRunScriptPlay(__deeplineContext, __deeplineInput, async () => {${entryBindings}`;
+  const edits: Array<{ at: number; end?: number; text: string }> = [
+    {
+      at: script.headerEnd,
+      text: script.headerEnd === 0 ? `${prefix} ` : ` ${prefix}`,
+    },
+  ];
+  // `export const config = {...}` runs inside the run as `const config`.
+  const configExport = configExportOf(programOf(source)!);
+  if (configExport) {
+    const declared = configExport.declaration as AstNode;
+    edits.push({
+      at: configExport.start as number,
+      end: declared.start as number,
+      text: blank(
+        source.slice(configExport.start as number, declared.start as number),
+      ),
+    });
+  }
+  let entryName = '__deeplineEntry';
+  if (entry) {
+    const statement = entry.exportStatement;
+    const declared = statement.declaration as AstNode | undefined;
+    if (entry.exportedAs === 'specifier') {
+      // `export { main as default }` names a binding that may follow it.
+      entryName = entry.name!;
+      edits.push({
+        at: statement.start as number,
+        end: statement.end as number,
+        text: blank(
+          source.slice(statement.start as number, statement.end as number),
+        ),
+      });
+    } else if (entry.exportedAs === 'declaration' && entry.name) {
+      // A named function declaration stays one, hoisted as it was.
+      entryName = entry.name;
+      edits.push({
+        at: statement.start as number,
+        end: declared!.start as number,
+        text: blank(
+          source.slice(statement.start as number, declared!.start as number),
+        ),
+      });
+    } else {
+      edits.push({
+        at: statement.start as number,
+        end: declared!.start as number,
+        text: '__deeplineEntry = ',
+      });
+      if (entry.exportedAs === 'declaration') {
+        edits.push({ at: statement.end as number, text: ';' });
+      }
+    }
+    if (entryCall) {
+      edits.push(
+        { at: entryCall.start as number, text: '(__deeplineEntryResult = ' },
+        { at: entryCall.end as number, text: ')' },
+      );
+    }
+  }
+  const dispatch = !entry
+    ? ''
+    : entryCall
+      ? ' return await __deeplineEntryResult;'
+      : // A play function that takes no input is called without one.
+        ` return await ${entryName}(${(entry.node.params as AstNode[]).length ? '__deeplineInput' : ''});`;
+  return (
+    edits
+      // Last first, and a replacement before an insertion at its start.
+      .sort(
+        (left, right) =>
+          right.at - left.at || (right.end ?? right.at) - (left.end ?? left.at),
+      )
+      .reduce(
+        (text, edit) =>
+          text.slice(0, edit.at) + edit.text + text.slice(edit.end ?? edit.at),
+        source,
+      ) + `\n;${dispatch} }); }\n`
+  );
+}
+
+/** `text` as spaces, keeping its line breaks. */
+function blank(text: string): string {
+  return text.replace(/[^\n]/g, ' ');
+}
+
+/**
+ * The rules a script must follow so its config and input contract can be
+ * read without running it, and so what it returns is unambiguous. Throws the
+ * first violation with its line.
+ */
+export function validateScriptPlay(source: string, script: ScriptPlay): void {
+  const { contextName, entry } = script;
+  const program = programOf(source)!;
+  const statements = program.body as AstNode[];
+  const defaultExport = statements.find(isDefaultExport);
+  if (defaultExport && !entry) {
+    fail(
+      source,
+      defaultExport,
+      'The default export must be the play function: export default async function (input) { ... return { ... }; }.',
+    );
+  }
+  if (entry) {
+    const calls = entryCallsOf(program, entry);
+    if (calls.length > 1) {
+      fail(
+        source,
+        calls[1]!,
+        `The play function is called ${calls.length} times at the top of the file; the runtime runs it once per run. Call it once, or not at all.`,
+      );
+    }
+    // A top-level result beside the play function: which one is the result?
+    const moduleResult = (node: AstNode, insideFunction: boolean): void => {
+      const call = scriptCallName(node, contextName);
+      if (
+        !insideFunction &&
+        (node.type === 'ReturnStatement' || call === 'output')
+      ) {
+        fail(
+          source,
+          node,
+          "The play function's return is the play's result; this top-level result would compete with it. Return the result from the play function.",
+        );
+      }
+      const nested = insideFunction || FUNCTION_TYPES.has(node.type);
+      childNodes(node).forEach((child) => moduleResult(child, nested));
+    };
+    moduleResult(program, false);
+  }
+  const lateImport = statements
+    .slice(headerOf(program).length)
+    .find((node) => node.type === 'ImportDeclaration');
+  if (lateImport) {
+    fail(
+      source,
+      lateImport,
+      'Move this import above the play code; imports come first in a script play.',
+    );
+  }
+  const topLevelConfig = new Set(
+    statements
+      .map((node) =>
+        node.type === 'ExpressionStatement' ? node.expression : null,
+      )
+      .filter((node): node is AstNode => isAstNode(node)),
+  );
+  const configExport = configExportOf(program);
+  if (configExport) {
+    const config = configObjectOf(configExport);
+    if (!config) {
+      fail(
+        source,
+        configExport,
+        "export const config must be one object literal, e.g. export const config = { description: '...' };",
+      );
+    }
+    validateConfigName(source, config);
+  }
+  const configCalls: AstNode[] = [];
+  const inputTypes = new Set<string>();
+  const visit = (node: AstNode): void => {
+    const call = scriptCallName(node, contextName);
+    const args = Array.isArray(node.arguments) ? node.arguments : [];
+    if (call === 'config') {
+      configCalls.push(node);
+      if (!topLevelConfig.has(node)) {
+        fail(
+          source,
+          node,
+          `${contextName}.config(...) must be its own top-level statement.`,
+        );
+      }
+      if (
+        args.length !== 1 ||
+        !isAstNode(args[0]) ||
+        args[0].type !== 'ObjectExpression'
+      ) {
+        fail(
+          source,
+          node,
+          `${contextName}.config(...) takes one object literal, e.g. ${contextName}.config({ description: '...' }).`,
+        );
+      }
+      validateConfigName(source, args[0] as AstNode);
+      if (configCalls.length > 1) {
+        fail(source, node, `${contextName}.config(...) may appear only once.`);
+      }
+      if (configExport) {
+        fail(
+          source,
+          node,
+          `The play config is declared twice: export const config (line ${lineOf(source, configExport)}) and ${contextName}.config(...) (line ${lineOf(source, node)}). Keep only export const config.`,
+        );
+      }
+    } else if (call === 'input') {
+      if (args.length > 0) {
+        fail(
+          source,
+          node,
+          `${contextName}.input() takes no arguments; declare the shape as a type: ${contextName}.input<{ domain: string }>().`,
+        );
+      }
+      const type = typeArgument(node);
+      if (type)
+        inputTypes.add(source.slice(type.start as number, type.end as number));
+      if (inputTypes.size > 1) {
+        fail(
+          source,
+          node,
+          `${contextName}.input<T>() is called with different types (${[...inputTypes].join(', ')}). Use one input type.`,
+        );
+      }
+    }
+    childNodes(node).forEach(visit);
+  };
+  visit(program);
+}
+
+/**
+ * What another play's type check sees for an imported script play: a play
+ * reference, which is all `deepline.runPlay(key, child, ...)` needs.
+ */
+export const SCRIPT_PLAY_MODULE_DECLARATION = `import type { DefinedPlay } from '${SCRIPT_SDK}';
+declare const play: DefinedPlay<Record<string, unknown>, Record<string, unknown>>;
+export default play;
+`;
+
+/** A config `name`, when present, is a non-empty string literal. */
+function validateConfigName(source: string, config: AstNode): void {
+  const name = ((config.properties as AstNode[] | undefined) ?? []).find(
+    (property) =>
+      property.type === 'Property' &&
+      !property.computed &&
+      isAstNode(property.key) &&
+      (property.key.name === 'name' || property.key.value === 'name'),
+  );
+  if (
+    name &&
+    !(
+      isAstNode(name.value) &&
+      name.value.type === 'Literal' &&
+      typeof name.value.value === 'string' &&
+      name.value.value.trim()
+    )
+  ) {
+    fail(source, name, 'config name must be a non-empty string literal.');
+  }
+}
+
+function lineOf(source: string, node: AstNode): number {
+  return source.slice(0, node.start as number).split('\n').length;
+}
+
+function fail(source: string, node: AstNode, message: string): never {
+  throw new Error(`line ${lineOf(source, node)}: ${message}`);
+}
+
+/** The direct children of an AST node. */
+function childNodes(node: AstNode): AstNode[] {
+  return Object.entries(node).flatMap(([key, value]) =>
+    key === 'loc'
+      ? []
+      : Array.isArray(value)
+        ? value.filter(isAstNode)
+        : isAstNode(value)
+          ? [value]
+          : [],
+  );
+}
+
+/**
+ * Parsed programs by source text, least recently used first. Analyzers read
+ * the same files many times in one admission; a parse that throws is not kept.
+ */
+const programs = new Map<string, AstNode | null>();
+const MAX_PROGRAMS = 16;
+
+function programOf(source: string): AstNode | null {
+  const program = programs.has(source) ? programs.get(source)! : parse(source);
+  programs.delete(source);
+  programs.set(source, program);
+  if (programs.size > MAX_PROGRAMS) {
+    programs.delete(programs.keys().next().value!);
+  }
+  return program;
+}
+
+/** Leading imports and types; the play's code is everything after them. */
+function headerOf(program: AstNode): AstNode[] {
+  const statements = program.body as AstNode[];
+  const firstCode = statements.findIndex(
+    (node) => !MODULE_SCOPE.has(node.type),
+  );
+  return firstCode === -1 ? statements : statements.slice(0, firstCode);
+}
+
+function isSdkImport(node: AstNode): boolean {
+  return (
+    node.type === 'ImportDeclaration' &&
+    isAstNode(node.source) &&
+    node.source.value === SCRIPT_SDK
+  );
+}
+
+function parse(source: string): AstNode | null {
+  try {
+    return TypeScriptParser.parse(source, {
+      ecmaVersion: 'latest',
+      sourceType: 'module',
+      allowHashBang: true,
+      // Script plays may end early with a top-level `return`.
+      allowReturnOutsideFunction: true,
+    }) as unknown as AstNode;
+  } catch (error) {
+    const looksLikeScript =
+      /\bdeepline\s*\./.test(source) &&
+      !/\bexport\b|\bdefinePlay\b/.test(source);
+    if (!looksLikeScript) return null;
+    const line = (error as { loc?: { line?: number } }).loc?.line;
+    throw new Error(
+      `line ${line ?? '?'}: ${(error as Error).message.replace(/ \(\d+:\d+\)$/, '')}`,
+    );
+  }
+}
+
+/**
+ * A script play exports nothing besides its `config` and a default; it never defines a play
+ * itself. `entry` is the default-exported function of the input, or null for
+ * top-level code alone or a default export that is not such a function
+ * (which `validateScriptPlay` rejects).
+ */
+function playForm(program: AstNode): { entry: PlayEntry | null } | null {
+  if (containsDefinePlayCall(program)) return null;
+  const configExport = configExportOf(program);
+  const exports = (program.body as AstNode[]).filter(
+    (node) =>
+      node !== configExport && /^Export|^TSExportAssignment$/.test(node.type),
+  );
+  if (exports.length === 0) return { entry: null };
+  const [statement] = exports;
+  if (exports.length !== 1 || !isDefaultExport(statement!)) return null;
+  const entry = entryOf(program, statement!);
+  // A legacy handler takes the context itself, `(ctx, input) => ...`, and the
+  // runner keeps calling it that way. A play function takes only its input.
+  if (entry && (entry.node.params as AstNode[]).length > 1) return null;
+  // Without `import deepline from 'deepline'`, a default-exported play
+  // function is still a play: `wrapScriptPlay` adds the import. Any other
+  // default export, or a file that imports something else as `deepline`, is
+  // a legacy module the runner calls as it always has.
+  if (!importsRuntime(program) && (!entry || importsRuntimeName(program))) {
+    return null;
+  }
+  return { entry };
+}
+
+/** The top-level `export const config = ...` statement, if any. */
+function configExportOf(program: AstNode): AstNode | null {
+  return (
+    (program.body as AstNode[]).find(
+      (node) =>
+        node.type === 'ExportNamedDeclaration' &&
+        !node.source &&
+        isAstNode(node.declaration) &&
+        node.declaration.type === 'VariableDeclaration' &&
+        (node.declaration.declarations as AstNode[]).some(
+          (declarator) => (declarator.id as AstNode).name === 'config',
+        ),
+    ) ?? null
+  );
+}
+
+/**
+ * The object literal `export const config = {...}` declares, through
+ * `as const`/`satisfies T`; null when it declares anything else.
+ */
+function configObjectOf(configExport: AstNode): AstNode | null {
+  const declaration = configExport.declaration as AstNode;
+  const declarators = declaration.declarations as AstNode[];
+  if (declaration.kind !== 'const' || declarators.length !== 1) return null;
+  const init = unwrapped(declarators[0]!.init);
+  return init?.type === 'ObjectExpression' ? init : null;
+}
+
+/** `export default ...` or `export { name as default }`. */
+function isDefaultExport(node: AstNode): boolean {
+  if (node.type === 'ExportDefaultDeclaration') return true;
+  const specifiers = (node.specifiers as AstNode[] | undefined) ?? [];
+  return (
+    node.type === 'ExportNamedDeclaration' &&
+    !node.declaration &&
+    !node.source &&
+    specifiers.length === 1 &&
+    exportedName(specifiers[0]!) === 'default'
+  );
+}
+
+function exportedName(specifier: AstNode): unknown {
+  const exported = specifier.exported as AstNode | undefined;
+  return exported?.name ?? exported?.value;
+}
+
+/** The function a default export statement names, when it is one. */
+function entryOf(program: AstNode, statement: AstNode): PlayEntry | null {
+  if (statement.type === 'ExportDefaultDeclaration') {
+    const declared = unwrapped(statement.declaration);
+    if (declared && FUNCTION_TYPES.has(declared.type)) {
+      const id = declared.id as AstNode | null | undefined;
+      return {
+        node: declared,
+        name:
+          declared.type === 'FunctionDeclaration' && id
+            ? (id.name as string)
+            : null,
+        exportedAs:
+          declared.type === 'FunctionDeclaration'
+            ? 'declaration'
+            : 'expression',
+        exportStatement: statement,
+        declaration: null,
+      };
+    }
+    return declared?.type === 'Identifier'
+      ? boundEntry(program, statement, declared.name as string, 'binding')
+      : null;
+  }
+  const [specifier] = statement.specifiers as AstNode[];
+  const local = specifier!.local as AstNode;
+  return boundEntry(program, statement, local.name as string, 'specifier');
+}
+
+/** `name`'s top-level function declaration or `const name = <function>`. */
+function boundEntry(
+  program: AstNode,
+  exportStatement: AstNode,
+  name: string,
+  exportedAs: 'binding' | 'specifier',
+): PlayEntry | null {
+  for (const node of program.body as AstNode[]) {
+    if (
+      node.type === 'FunctionDeclaration' &&
+      (node.id as AstNode | null)?.name === name
+    ) {
+      return { node, name, exportedAs, exportStatement, declaration: node };
+    }
+    if (node.type !== 'VariableDeclaration') continue;
+    for (const declarator of node.declarations as AstNode[]) {
+      const init = unwrapped(declarator.init);
+      if (
+        (declarator.id as AstNode).name === name &&
+        init &&
+        FUNCTION_TYPES.has(init.type)
+      ) {
+        return {
+          node: init,
+          name,
+          exportedAs,
+          exportStatement,
+          declaration: node,
+        };
+      }
+    }
+  }
+  return null;
+}
+
+/**
+ * The module's own calls to the entry that run whenever the module does:
+ * outside functions, branches and loops. `if (import.meta.main) main()` is
+ * not one; the runtime calls the entry itself.
+ */
+function entryCallsOf(program: AstNode, entry: PlayEntry): AstNode[] {
+  if (!entry.name) return [];
+  const calls: AstNode[] = [];
+  const visit = (node: AstNode): void => {
+    if (CONDITIONAL_TYPES.has(node.type)) return;
+    if (
+      node.type === 'CallExpression' &&
+      isAstNode(node.callee) &&
+      node.callee.type === 'Identifier' &&
+      node.callee.name === entry.name
+    ) {
+      calls.push(node);
+    }
+    childNodes(node).forEach(visit);
+  };
+  (program.body as AstNode[])
+    .filter(
+      (node) => node !== entry.declaration && node !== entry.exportStatement,
+    )
+    .forEach(visit);
+  return calls;
+}
+
+function importsRuntime(program: AstNode): boolean {
+  return (program.body as AstNode[]).some(
+    (node) => isSdkImport(node) && defaultImportName(node) !== null,
+  );
+}
+
+/** Whether an import binds the name `deepline`, so adding the runtime's would clash. */
+function importsRuntimeName(program: AstNode): boolean {
+  return (program.body as AstNode[]).some(
+    (node) =>
+      node.type === 'ImportDeclaration' &&
+      (node.specifiers as AstNode[]).some(
+        (specifier) => (specifier.local as AstNode).name === SCRIPT_SDK,
+      ),
+  );
+}
+
+function containsDefinePlayCall(node: AstNode): boolean {
+  if (node.type === 'CallExpression' && isAstNode(node.callee)) {
+    const callee = node.callee;
+    const name =
+      callee.type === 'Identifier'
+        ? callee.name
+        : callee.type === 'MemberExpression' && isAstNode(callee.property)
+          ? callee.property.name
+          : null;
+    if (DEFINE_CALLEES.has(name as string)) return true;
+  }
+  return childNodes(node).some(containsDefinePlayCall);
+}
+
+function defaultImportName(
+  importDeclaration: AstNode | undefined,
+): string | null {
+  const specifier = (
+    importDeclaration?.specifiers as AstNode[] | undefined
+  )?.find((node) => node.type === 'ImportDefaultSpecifier');
+  return specifier && isAstNode(specifier.local)
+    ? (specifier.local.name as string)
+    : null;
+}