@specific.dev/spectest 0.112.0 → 0.113.0

package/dist/daemon.js

@@ -43,6 +43,7 @@ import { isDesktopApp } from "./desktop.js";
 // each easy to restate subtly differently.
 import { buildArgFlags, buildContentKey as computeBuildContentKey, buildTargetFlags, imageTag, isGeneratedDockerignore, pickProjectIgnore, serviceDockerignore as composeServiceDockerignore, unionDockerignore, } from "./harness/build-context.js";
 import { startServices } from "./harness/service-graph.js";
+import { fakeFunctions, fakeFunctionParameters, callFakeFunction } from "./harness/fake-functions.js";
 import { dispatchFake } from "./harness/fake-websocket.js";
 import { casesMetadata as catalogueCases, groupsMetadata as catalogueGroups, } from "./harness/catalogue.js";
 import { summarizeBuildKit } from "./harness/buildkit-progress.js";
@@ -5286,6 +5287,21 @@ export function harnessMethods(state) {
         }),
         projectSetup: async () => exclusive(state, "inFlightProjectSetup", "project-setup already in progress", () => runProjectSetup()),
         interactiveSetup: async () => exclusive(state, "inFlightProjectSetup", "project-setup already in progress", () => runProjectSetup("setupInteractive")),
+        fakeFunctions: async (params) => exclusive(state, "inFlightTest", "a test or eval is already running", async () => {
+            const name = requireString(params, "fake");
+            const fake = FAKES.get(name);
+            if (!fake)
+                throw notFound(`Unknown fake: ${name}`);
+            await ensureFakeHelpers(name);
+            if (params.member === undefined)
+                return { functions: fakeFunctions(fake.helpers), parameters: fakeFunctionParameters(fake.helpers) };
+            const member = requireString(params, "member");
+            if (params.expressions !== undefined)
+                return callFakeFunction(fake.helpers, member, [], [], params.expressions);
+            if (!Array.isArray(params.args))
+                throw badRequest("args must be a JSON array");
+            return callFakeFunction(fake.helpers, member, params.args, params.omitted_args);
+        }),
         eval: async (params) => {
             const code = requireString(params, "code");
             return exclusive(state, "inFlightTest", "a test or eval is already running", () => {

package/dist/harness/fake-functions.d.ts

@@ -0,0 +1,18 @@
+/** Only own data properties are callable. Discovery never invokes getters. */
+export declare function fakeFunctions(helpers: Record<string, unknown>): string[];
+export declare function fakeFunctionParameters(helpers: Record<string, unknown>): {
+    [k: string]: import("./function-parameters.js").FunctionParameter[] | null;
+};
+/** Use the raw helpers: the test wrappers intentionally discard annotations
+ * when there is no recorder. Preserve both the value and its presentation. */
+export declare function callFakeFunction(helpers: Record<string, unknown>, member: string, args: unknown[], omittedArgs?: number[], expressions?: string[]): Promise<{
+    result: {} | null;
+    annotation: import("../annotate.js").RenderAnnotation | null;
+    error: null;
+    duration_ms: number;
+} | {
+    result: null;
+    annotation: null;
+    error: string;
+    duration_ms: number;
+}>;

package/dist/harness/fake-functions.js

@@ -0,0 +1,82 @@
+import { parse } from "acorn";
+import { functionParameters } from "./function-parameters.js";
+import { readAnnotation } from "../annotate.js";
+import { deepUnwrap } from "../inspect.js";
+import { safeSerialize } from "../recorder.js";
+import { runUninstrumented } from "./instrumentation-scope.js";
+/** Only own data properties are callable. Discovery never invokes getters. */
+export function fakeFunctions(helpers) {
+    return Object.getOwnPropertyNames(helpers).filter((name) => typeof Object.getOwnPropertyDescriptor(helpers, name)?.value === "function").sort();
+}
+export function fakeFunctionParameters(helpers) {
+    return Object.fromEntries(fakeFunctions(helpers).map(name => [name,
+        functionParameters(Object.getOwnPropertyDescriptor(helpers, name).value),
+    ]));
+}
+/** Use the raw helpers: the test wrappers intentionally discard annotations
+ * when there is no recorder. Preserve both the value and its presentation. */
+export async function callFakeFunction(helpers, member, args, omittedArgs = [], expressions) {
+    const fn = Object.getOwnPropertyDescriptor(helpers, member)?.value;
+    if (typeof fn !== "function")
+        throw new Error(`Unknown fake function: ${member}`);
+    if (!Array.isArray(omittedArgs) || omittedArgs.some(i => !Number.isInteger(i) || i < 0 || i >= args.length || args[i] !== null))
+        throw new Error("omitted_args must contain indices of null argument placeholders");
+    const omitted = new Set(omittedArgs);
+    const actualArgs = args.map((value, i) => omitted.has(i) ? undefined : value);
+    const start = Date.now();
+    try {
+        const value = await runUninstrumented(() => Reflect.apply(fn, helpers, expressions === undefined ? actualArgs : evaluateArguments(fn, expressions)));
+        const annotated = readAnnotation(value);
+        return {
+            result: safeSerialize(deepUnwrap(annotated ? annotated.value : value)) ?? null,
+            annotation: annotated?.annotation ?? null,
+            error: null,
+            duration_ms: Date.now() - start,
+        };
+    }
+    catch (error) {
+        return { result: null, annotation: null,
+            error: error instanceof Error ? error.message : String(error), duration_ms: Date.now() - start };
+    }
+}
+/** Expressions execute only in the environment, never in either dashboard.
+ * Compile every field before evaluating any, so a syntax error cannot partially
+ * execute the call. Keep actual JS values (undefined, Date, functions, etc.). */
+function evaluateArguments(fn, expressions) {
+    if (!Array.isArray(expressions) || expressions.some(source => typeof source !== "string"))
+        throw new Error("expressions must be an array of JavaScript expressions");
+    const parameters = functionParameters(fn);
+    const label = (index) => parameters?.[index]?.name ?? `Argument ${index + 1}`;
+    const withLabel = (index, action) => {
+        try {
+            return action();
+        }
+        catch (error) {
+            throw new Error(`${label(index)}: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    };
+    const compiled = expressions.map((source, index) => withLabel(index, () => {
+        if (!source.trim())
+            return null;
+        const expression = `(${source}\n)`;
+        const program = parse(expression, { ecmaVersion: "latest" });
+        if (program.body.length !== 1 || program.body[0].type !== "ExpressionStatement")
+            throw new Error("Enter a single JavaScript expression.");
+        return new Function(`"use strict"; return ${expression};`);
+    }));
+    // Preserve interior omissions but avoid inventing trailing arguments.
+    while (compiled.length && compiled.at(-1) === null)
+        compiled.pop();
+    const args = [];
+    compiled.forEach((evaluate, index) => withLabel(index, () => {
+        const value = evaluate ? evaluate() : undefined;
+        if (parameters?.[index]?.rest) {
+            if (!Array.isArray(value))
+                throw new Error("Enter an array expression for the remaining arguments.");
+            args.push(...value);
+        }
+        else
+            args.push(value);
+    }));
+    return args;
+}

package/dist/harness/function-parameters.d.ts

@@ -0,0 +1,9 @@
+export interface FunctionParameter {
+    name: string;
+    has_default: boolean;
+    rest: boolean;
+    destructured: boolean;
+}
+/** Parse runtime JavaScript, never execute it (including default expressions).
+ * Null means opaque/unparseable, while [] means a known zero-argument helper. */
+export declare function functionParameters(fn: Function): FunctionParameter[] | null;

package/dist/harness/function-parameters.js

@@ -0,0 +1,42 @@
+import { parse } from "acorn";
+/** Parse runtime JavaScript, never execute it (including default expressions).
+ * Null means opaque/unparseable, while [] means a known zero-argument helper. */
+export function functionParameters(fn) {
+    const source = Function.prototype.toString.call(fn);
+    if (source.length > 256_000)
+        return null;
+    // Function/arrow expressions and object methods have different grammar.
+    for (const method of [false, true]) {
+        const text = method ? `({${source}})` : `(${source})`;
+        try {
+            const program = parse(text, { ecmaVersion: "latest", sourceType: "module" });
+            const statement = program.body[0];
+            if (statement?.type !== "ExpressionStatement")
+                continue;
+            let expression = statement.expression;
+            if (method) {
+                if (expression.type !== "ObjectExpression")
+                    continue;
+                const properties = expression.properties;
+                if (properties.length !== 1 || properties[0]?.type !== "Property")
+                    continue;
+                expression = properties[0].value;
+            }
+            if (expression.type !== "FunctionExpression" && expression.type !== "ArrowFunctionExpression")
+                continue;
+            return expression.params.map((parameter) => {
+                const rest = parameter.type === "RestElement";
+                let binding = rest ? parameter.argument : parameter;
+                const has_default = binding.type === "AssignmentPattern";
+                if (binding.type === "AssignmentPattern")
+                    binding = binding.left;
+                return {
+                    name: binding.type === "Identifier" ? binding.name : text.slice(binding.start, binding.end),
+                    has_default, rest, destructured: binding.type !== "Identifier",
+                };
+            });
+        }
+        catch { /* Native/bound functions and unsupported syntax stay opaque. */ }
+    }
+    return null;
+}

package/dist/harness/protocol.d.ts

@@ -23,7 +23,7 @@
 /** Protocol version this build speaks. Must match `PROTOCOL_VERSION` in protocol.rs. */
 export declare const PROTOCOL_VERSION = 1;
 /** Methods either side can send. */
-export type Method = "hello" | "load" | "loadTests" | "fingerprint" | "bootstrap" | "interactiveSetup" | "run" | "eval" | "setRecordSecrets" | "teardown" | "shutdown" | "createArtifact" | "completeArtifact" | "progress" | "step";
+export type Method = "hello" | "load" | "loadTests" | "fingerprint" | "bootstrap" | "interactiveSetup" | "run" | "fakeFunctions" | "eval" | "setRecordSecrets" | "teardown" | "shutdown" | "createArtifact" | "completeArtifact" | "progress" | "step";
 /** Methods this build knows how to dispatch. A method outside this set still
  *  *parses* — it is answered with an error, never dropped. */
 export declare const KNOWN_METHODS: ReadonlySet<string>;

package/dist/harness/protocol.js

@@ -32,6 +32,7 @@ export const KNOWN_METHODS = new Set([
     "bootstrap",
     "interactiveSetup",
     "run",
+    "fakeFunctions",
     "eval",
     "setRecordSecrets",
     "teardown",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@specific.dev/spectest",
-  "version": "0.112.0",
+  "version": "0.113.0",
   "description": "Spectest SDK for defining test environments in TypeScript.",
   "type": "module",
   "main": "./dist/index.js",
@@ -55,6 +55,7 @@
   "dependencies": {
     "@kubernetes/client-node": "^1.0.0",
     "@xterm/headless": "^5.5.0",
+    "acorn": "8.18.0",
     "dns-packet": "^5.6.1",
     "playwright-core": "^1.61.1",
     "ws": "^8.20.1"

package/src/daemon.ts

@@ -93,6 +93,7 @@ import {
   unionDockerignore,
 } from "./harness/build-context.js";
 import { startServices } from "./harness/service-graph.js";
+import { fakeFunctions, fakeFunctionParameters, callFakeFunction } from "./harness/fake-functions.js";
 import { dispatchFake } from "./harness/fake-websocket.js";
 import {
   casesMetadata as catalogueCases,
@@ -6332,6 +6333,19 @@ export function harnessMethods(state: RouteState): MethodTable {
         () => runProjectSetup("setupInteractive"),
       ),
 
+    fakeFunctions: async (params) => exclusive(state, "inFlightTest", "a test or eval is already running", async () => {
+      const name = requireString(params, "fake");
+      const fake = FAKES.get(name);
+      if (!fake) throw notFound(`Unknown fake: ${name}`);
+      await ensureFakeHelpers(name);
+      if (params.member === undefined) return { functions: fakeFunctions(fake.helpers!), parameters: fakeFunctionParameters(fake.helpers!) };
+      const member = requireString(params, "member");
+      if (params.expressions !== undefined)
+        return callFakeFunction(fake.helpers!, member, [], [], params.expressions as string[]);
+      if (!Array.isArray(params.args)) throw badRequest("args must be a JSON array");
+      return callFakeFunction(fake.helpers!, member, params.args, params.omitted_args as number[] | undefined);
+    }),
+
     eval: async (params) => {
       const code = requireString(params, "code");
       return exclusive(state, "inFlightTest", "a test or eval is already running", () => {

package/src/fake-functions.test.ts

@@ -0,0 +1,62 @@
+import { expect, test } from "bun:test";
+import { mkdtemp, mkdir, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+test("daemon dispatch discovers cached helpers, preserves annotations and excludes concurrent evals", async () => {
+  const root = await mkdtemp(join(tmpdir(), "spectest-fake-functions-"));
+  try {
+    await mkdir(join(root, "spectest"));
+    await writeFile(join(root, "spectest/index.ts"), `
+      import { defineEnvironment, defineFake, annotate } from ${JSON.stringify(new URL("./index.ts", import.meta.url).href)};
+      const env = defineEnvironment({ name: "helpers", services: {}, fakes: {
+        mail: defineFake({ name: "mail", hostnames: ["mail.test"], handler: () => new Response("ok"), helpers: () => {
+          let count = 0;
+          return {
+            receipt(amount) { count += amount; return annotate({ subject: "Receipt " + count }, "email"); },
+            async wait() { await globalThis.gate; return count; },
+          };
+        } }),
+      }});
+      export default env.project({});
+    `);
+    const script = `
+      import { strict as assert } from "node:assert";
+      import { METHODS } from ${JSON.stringify(new URL("./daemon.ts", import.meta.url).href)};
+      await METHODS.load({});
+      {
+        const discovery = await METHODS.fakeFunctions({fake:"mail"});
+        assert.deepEqual(discovery.functions, ["receipt", "wait"]);
+        assert.deepEqual(discovery.parameters.receipt, [{ name: "amount", has_default: false, rest: false, destructured: false }]);
+        assert.deepEqual(discovery.parameters.wait, []);
+      }
+      await assert.rejects(METHODS.fakeFunctions({fake:"missing"}), /Unknown fake/);
+      await assert.rejects(METHODS.fakeFunctions({fake:"mail", member:"receipt", args:{}}), /JSON array/);
+      for (const count of [1, 2]) {
+        const result = await METHODS.fakeFunctions({fake:"mail", member:"receipt", expressions:["2 - 1"]});
+        assert.equal(result.result.subject, "Receipt " + count);
+        assert.equal(result.annotation.kind, "email");
+        assert.equal(result.annotation.message.subject, result.result.subject);
+      }
+      let release;
+      globalThis.gate = new Promise(r => release = r);
+      const pending = METHODS.fakeFunctions({fake:"mail", member:"wait", expressions:[]});
+      await assert.rejects(METHODS.eval({code:"export default 1"}), /already running/);
+      await assert.rejects(METHODS.fakeFunctions({fake:"mail"}), /already running/);
+      release();
+      assert.equal((await pending).result, 2);
+      {
+        const discovery = await METHODS.fakeFunctions({fake:"mail"});
+        assert.deepEqual(discovery.functions, ["receipt", "wait"]);
+        assert.deepEqual(discovery.parameters.receipt, [{ name: "amount", has_default: false, rest: false, destructured: false }]);
+        assert.deepEqual(discovery.parameters.wait, []);
+      }
+      process.exit(0);
+    `;
+    const child = Bun.spawn([process.execPath, "--eval", script], {
+      env: { ...process.env, SPECTEST_APP_DIR: root }, stdout: "pipe", stderr: "pipe",
+    });
+    const [code, stdout, stderr] = await Promise.all([child.exited, new Response(child.stdout).text(), new Response(child.stderr).text()]);
+    expect(code, stdout + stderr).toBe(0);
+  } finally { await rm(root, { recursive: true, force: true }); }
+}, 20000);

package/src/harness/fake-functions.test.ts

@@ -0,0 +1,77 @@
+import { expect, test } from "bun:test";
+import { annotate } from "../annotate.js";
+import { fakeFunctions, callFakeFunction } from "./fake-functions.js";
+
+test("discovery includes only own data functions and never runs getters", async () => {
+  const helpers = Object.create({ inherited() { throw new Error("no"); } });
+  Object.defineProperties(helpers, {
+    getter: { get() { throw new Error("no"); } },
+    value: { value: 42 },
+    own: { value() {} },
+  });
+  expect(fakeFunctions(helpers)).toEqual(["own"]);
+  for (const name of ["getter", "inherited", "constructor", "toString", "missing", "value"])
+    await expect(callFakeFunction(helpers, name, [])).rejects.toThrow("Unknown fake function");
+});
+
+test("calls preserve receiver, arguments, live state, and async return values", async () => {
+  const helpers = { count: 0, async add(value: { amount: number }) { this.count += value.amount; return this.count; } };
+  expect((await callFakeFunction(helpers, "add", [{ amount: 3 }])).result).toBe(3);
+  expect((await callFakeFunction(helpers, "add", [{ amount: 2 }])).result).toBe(5);
+});
+
+test("email and chat annotations survive separately from the raw value", async () => {
+  const value = { subject: "Receipt", html: "<p>Paid</p>" };
+  const helpers = {
+    email: () => annotate(value, "email"),
+    chat: async () => annotate({ original: 1 }, "chat", [{ side: "other", text: "Hello" }]),
+    empty() {},
+    fail() { throw new Error("declined"); },
+    async reject() { throw new Error("offline"); },
+  };
+  const email = await callFakeFunction(helpers, "email", []);
+  expect(email.result).toEqual(value);
+  expect(email.annotation).toEqual({ kind: "email", message: value });
+  const chat = await callFakeFunction(helpers, "chat", []);
+  expect(chat.result).toEqual({ original: 1 });
+  expect(chat.annotation?.kind).toBe("chat");
+  expect((await callFakeFunction(helpers, "empty", [])).result).toBeNull();
+  expect((await callFakeFunction(helpers, "fail", [])).error).toBe("declined");
+  expect((await callFakeFunction(helpers, "reject", [])).error).toBe("offline");
+});
+
+test("evaluates JavaScript expressions with defaults, rest and non-JSON values", async () => {
+  const helpers = {
+    values(label = "default", ...items: unknown[]) { return [label, ...items]; },
+    inspect(date: Date, callback: (n: number) => number) { return [date.getUTCFullYear(), callback(4)]; },
+    count(...items: unknown[]) { return items.length; },
+  };
+  const call = (member: string, expressions: string[]) => callFakeFunction(helpers, member, [], [], expressions);
+  expect((await call("values", ["'123'", "[1 + 2, { ok: true }, null]"])).result).toEqual(["123", 3, { ok: true }, null]);
+  expect((await call("values", ["", "[false]"])).result).toEqual(["default", false]);
+  expect((await call("values", ["undefined", ""])).result).toEqual(["default"]);
+  expect((await call("inspect", ["new Date('2026-01-01')", "n => n * 2"])).result).toEqual([2026, 8]);
+  expect((await call("count", [""])).result).toBe(0);
+  expect((await call("values", ["'x'", "42"])).error).toContain("items: Enter an array expression");
+});
+
+test("rejects invalid expressions before evaluating fields or invoking a helper", async () => {
+  let calls = 0;
+  const helpers = { send(to: unknown, body: unknown) { calls++; return [to, body]; } };
+  const globals = globalThis as typeof globalThis & { expressionCalls?: number };
+  globals.expressionCalls = 0;
+  try {
+    const call = (expressions: string[]) => callFakeFunction(helpers, "send", [], [], expressions);
+    expect((await call(["++globalThis.expressionCalls", "{broken"])).error).toContain("body:");
+    expect(globals.expressionCalls).toBe(0);
+    expect((await call(["1); globalThis.expressionCalls++; (2", "''"])).error).toContain("to:");
+    expect((await call(["unquotedMissingName", "''"])).error).toContain("to:");
+    expect(calls).toBe(0);
+    await expect(callFakeFunction(helpers, "missing", [], [], ["++globalThis.expressionCalls"])).rejects.toThrow("Unknown fake function");
+    expect(globals.expressionCalls).toBe(0);
+    expect((await call(["++globalThis.expressionCalls", "'hello' // trailing comment"])).result).toEqual([1, "hello"]);
+    expect(globals.expressionCalls).toBe(1);
+    expect(calls).toBe(1);
+    expect((await callFakeFunction({ max: Math.max }, "max", [], [], ["1 + 2", "10"])).result).toBe(10);
+  } finally { delete globals.expressionCalls; }
+});

package/src/harness/fake-functions.ts

@@ -0,0 +1,78 @@
+import { parse } from "acorn";
+import { functionParameters } from "./function-parameters.js";
+import { readAnnotation } from "../annotate.js";
+import { deepUnwrap } from "../inspect.js";
+import { safeSerialize } from "../recorder.js";
+import { runUninstrumented } from "./instrumentation-scope.js";
+
+/** Only own data properties are callable. Discovery never invokes getters. */
+export function fakeFunctions(helpers: Record<string, unknown>): string[] {
+  return Object.getOwnPropertyNames(helpers).filter((name) =>
+    typeof Object.getOwnPropertyDescriptor(helpers, name)?.value === "function",
+  ).sort();
+}
+
+export function fakeFunctionParameters(helpers: Record<string, unknown>) {
+  return Object.fromEntries(fakeFunctions(helpers).map(name => [name,
+    functionParameters(Object.getOwnPropertyDescriptor(helpers, name)!.value),
+  ]));
+}
+
+/** Use the raw helpers: the test wrappers intentionally discard annotations
+ * when there is no recorder. Preserve both the value and its presentation. */
+export async function callFakeFunction(helpers: Record<string, unknown>, member: string, args: unknown[], omittedArgs: number[] = [], expressions?: string[]) {
+  const fn = Object.getOwnPropertyDescriptor(helpers, member)?.value;
+  if (typeof fn !== "function") throw new Error(`Unknown fake function: ${member}`);
+  if (!Array.isArray(omittedArgs) || omittedArgs.some(i => !Number.isInteger(i) || i < 0 || i >= args.length || args[i] !== null))
+    throw new Error("omitted_args must contain indices of null argument placeholders");
+  const omitted = new Set(omittedArgs);
+  const actualArgs = args.map((value, i) => omitted.has(i) ? undefined : value);
+  const start = Date.now();
+  try {
+    const value = await runUninstrumented(() => Reflect.apply(fn, helpers,
+      expressions === undefined ? actualArgs : evaluateArguments(fn, expressions)));
+    const annotated = readAnnotation(value);
+    return {
+      result: safeSerialize(deepUnwrap(annotated ? annotated.value : value)) ?? null,
+      annotation: annotated?.annotation ?? null,
+      error: null,
+      duration_ms: Date.now() - start,
+    };
+  } catch (error) {
+    return { result: null, annotation: null,
+      error: error instanceof Error ? error.message : String(error), duration_ms: Date.now() - start };
+  }
+}
+
+/** Expressions execute only in the environment, never in either dashboard.
+ * Compile every field before evaluating any, so a syntax error cannot partially
+ * execute the call. Keep actual JS values (undefined, Date, functions, etc.). */
+function evaluateArguments(fn: Function, expressions: string[]): unknown[] {
+  if (!Array.isArray(expressions) || expressions.some(source => typeof source !== "string"))
+    throw new Error("expressions must be an array of JavaScript expressions");
+  const parameters = functionParameters(fn);
+  const label = (index: number) => parameters?.[index]?.name ?? `Argument ${index + 1}`;
+  const withLabel = <T>(index: number, action: () => T): T => {
+    try { return action(); }
+    catch (error) { throw new Error(`${label(index)}: ${error instanceof Error ? error.message : String(error)}`); }
+  };
+  const compiled = expressions.map((source, index) => withLabel(index, () => {
+    if (!source.trim()) return null;
+    const expression = `(${source}\n)`;
+    const program = parse(expression, { ecmaVersion: "latest" });
+    if (program.body.length !== 1 || program.body[0].type !== "ExpressionStatement")
+      throw new Error("Enter a single JavaScript expression.");
+    return new Function(`"use strict"; return ${expression};`);
+  }));
+  // Preserve interior omissions but avoid inventing trailing arguments.
+  while (compiled.length && compiled.at(-1) === null) compiled.pop();
+  const args: unknown[] = [];
+  compiled.forEach((evaluate, index) => withLabel(index, () => {
+    const value = evaluate ? evaluate() : undefined;
+    if (parameters?.[index]?.rest) {
+      if (!Array.isArray(value)) throw new Error("Enter an array expression for the remaining arguments.");
+      args.push(...value);
+    } else args.push(value);
+  }));
+  return args;
+}

package/src/harness/function-parameters.test.ts

@@ -0,0 +1,45 @@
+import { expect, test } from "bun:test";
+import { functionParameters } from "./function-parameters.js";
+import { callFakeFunction, fakeFunctionParameters } from "./fake-functions.js";
+
+const p = (name: string, has_default = false, rest = false, destructured = false) => ({ name, has_default, rest, destructured });
+
+test("reads runtime names from methods, arrows, async and generator functions", () => {
+  const methods = { send(to: string, subject: string, text: string) {}, async load(id: number) {}, *items(limit = 3) {} };
+  expect(fakeFunctionParameters(methods)).toEqual({ send: [p("to"), p("subject"), p("text")], load: [p("id")], items: [p("limit", true)] });
+  expect(functionParameters(value => value)).toEqual([p("value")]);
+  expect(functionParameters(async value => value)).toEqual([p("value")]);
+  expect(functionParameters(function named(ångström: string) {})).toEqual([p("ångström")]);
+  expect(functionParameters(() => 42)).toEqual([]);
+});
+
+test("handles nested defaults, commas, comments and patterns without evaluating anything", () => {
+  let calls = 0;
+  const fn = (first = (++calls, /[,)]/), /* not,a,param */ second = (x = [1, 2]) => x,
+    third = `a,${[1, 2].join(",")}`, { to, subject: title } = { to: "a", subject: "b" }, [a, b] = [1, 2], ...rest: unknown[]) => {};
+  const result = functionParameters(fn)!;
+  expect(result.map(v => [v.has_default, v.rest, v.destructured])).toEqual([
+    [true, false, false], [true, false, false], [true, false, false], [true, false, true], [true, false, true], [false, true, false],
+  ]);
+  expect(result.slice(0, 3).map(v => v.name)).toEqual(["first", "second", "third"]);
+  expect(result[3].name).toContain("to");
+  expect(result[3].name).toContain("subject");
+  expect(result[4].name).toMatch(/^\[/);
+  expect(result[5].name).toBe("rest");
+  expect(calls).toBe(0);
+});
+
+test("opaque functions stay unknown and user-supplied toString is never called", () => {
+  const fn = (name: string) => name;
+  Object.defineProperty(fn, "toString", { get() { throw new Error("do not inspect"); } });
+  expect(functionParameters(fn)).toEqual([p("name")]);
+  expect(functionParameters(fn.bind(null))).toBeNull();
+  expect(functionParameters(Math.max)).toBeNull();
+});
+
+test("omitted slots trigger defaults while explicit null and later arguments are preserved", async () => {
+  const helpers = { send(to = "default", text: unknown, ...extra: unknown[]) { return [to, text, ...extra]; } };
+  expect((await callFakeFunction(helpers, "send", [null, "123", false, { ok: true }], [0])).result).toEqual(["default", "123", false, { ok: true }]);
+  expect((await callFakeFunction(helpers, "send", [null, "text"])).result).toEqual([null, "text"]);
+  for (const omitted of [[-1], [2], [0.5], [1]]) await expect(callFakeFunction(helpers, "send", [null, "text"], omitted)).rejects.toThrow("omitted_args");
+});

package/src/harness/function-parameters.ts

@@ -0,0 +1,43 @@
+import { parse, type Node, type Expression, type Pattern, type FunctionExpression, type ArrowFunctionExpression } from "acorn";
+
+export interface FunctionParameter {
+  name: string;
+  has_default: boolean;
+  rest: boolean;
+  destructured: boolean;
+}
+
+/** Parse runtime JavaScript, never execute it (including default expressions).
+ * Null means opaque/unparseable, while [] means a known zero-argument helper. */
+export function functionParameters(fn: Function): FunctionParameter[] | null {
+  const source = Function.prototype.toString.call(fn);
+  if (source.length > 256_000) return null;
+  // Function/arrow expressions and object methods have different grammar.
+  for (const method of [false, true]) {
+    const text = method ? `({${source}})` : `(${source})`;
+    try {
+      const program = parse(text, { ecmaVersion: "latest", sourceType: "module" });
+      const statement = program.body[0];
+      if (statement?.type !== "ExpressionStatement") continue;
+      let expression: Node = statement.expression;
+      if (method) {
+        if (expression.type !== "ObjectExpression") continue;
+        const properties = (expression as Extract<Expression, { type: "ObjectExpression" }>).properties;
+        if (properties.length !== 1 || properties[0]?.type !== "Property") continue;
+        expression = properties[0].value;
+      }
+      if (expression.type !== "FunctionExpression" && expression.type !== "ArrowFunctionExpression") continue;
+      return (expression as FunctionExpression | ArrowFunctionExpression).params.map((parameter) => {
+        const rest = parameter.type === "RestElement";
+        let binding: Pattern = rest ? parameter.argument : parameter;
+        const has_default = binding.type === "AssignmentPattern";
+        if (binding.type === "AssignmentPattern") binding = binding.left;
+        return {
+          name: binding.type === "Identifier" ? binding.name : text.slice(binding.start, binding.end),
+          has_default, rest, destructured: binding.type !== "Identifier",
+        };
+      });
+    } catch { /* Native/bound functions and unsupported syntax stay opaque. */ }
+  }
+  return null;
+}

package/src/harness/protocol.ts

@@ -34,6 +34,7 @@ export type Method =
   | "bootstrap"
   | "interactiveSetup"
   | "run"
+  | "fakeFunctions"
   | "eval"
   | "setRecordSecrets"
   | "teardown"
@@ -54,6 +55,7 @@ export const KNOWN_METHODS: ReadonlySet<string> = new Set<Method>([
   "bootstrap",
   "interactiveSetup",
   "run",
+  "fakeFunctions",
   "eval",
   "setRecordSecrets",
   "teardown",