@procedures/compiler 0.0.0-stage → 0.3.0

package/package.json

@@ -1,6 +1,86 @@
 {
+  "$schema": "https://json.schemastore.org/package",
   "name": "@procedures/compiler",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.3.0",
+  "description": "The compiler of procedure programs: it checks a JSON program before the first call (scopes, effects, schemas, capability) and writes it as a plain async function.",
+  "keywords": [
+    "compiler",
+    "procedures",
+    "static-analysis",
+    "effects",
+    "capabilities",
+    "codegen",
+    "workflow",
+    "dsl"
+  ],
+  "homepage": "https://mark1russell7.github.io/client/",
+  "bugs": {
+    "url": "https://github.com/mark1russell7/client/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mark1russell7/client.git",
+    "directory": "packages/compiler"
+  },
+  "license": "MIT",
+  "author": "Mark Russell (https://github.com/mark1russell7)",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./module": {
+      "types": "./dist/module.d.ts",
+      "import": "./dist/module.js"
+    },
+    "./register": {
+      "types": "./dist/register.d.ts",
+      "import": "./dist/register.js"
+    },
+    "./runtime": {
+      "types": "./dist/runtime.d.ts",
+      "import": "./dist/runtime.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "!src/**/*.test.ts",
+    "!src/**/*.test.tsx",
+    "!src/**/__tests__",
+    "CHANGELOG.md"
+  ],
+  "sideEffects": [
+    "./dist/register.js"
+  ],
+  "devDependencies": {
+    "@mark1russell7/cue": "^1.0.0",
+    "fast-check": "^4.10.2",
+    "typescript": "^7.0.2",
+    "vitest": "^5.0.3"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "client": {
+    "procedures": "./dist/register.js"
+  },
+  "dependencies": {
+    "@procedures/client": "0.3.0",
+    "zod": "^4.6.5"
+  },
+  "scripts": {
+    "build": "tsc -b",
+    "typecheck": "tsc --noEmit",
+    "clean": "rm -rf dist .tsbuildinfo",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  }
 }

package/src/checks.ts

@@ -0,0 +1,128 @@
+/**
+ * The checks pass: the problems of each call before the first call starts.
+ *
+ * - An unknown path, or a path that the host does not expose.
+ * - A call that the capability refuses (`capabilityRefusal()` of the client, with the declared
+ *   effects of the manifest), and a call whose program the compiler cannot see under a capability
+ *   that limits the effects (fail closed).
+ * - An input that does not agree with the JSON Schema of the procedure.
+ *
+ * In the interpreter each call of a program goes through the admission: a call of the host, or a
+ * nested call of a data-driven procedure. So the pass examines each call of the IR.
+ */
+
+import { capabilityRefusal, type AnyProcedure, type Capability, type Effects, type ProcedurePath } from "@procedures/client/browser";
+import { isCallLike, type IRNode, walk } from "./ir.js";
+import { isStringPath, type ProcedureFacts } from "./facts.js";
+import { isUnknown, toEffects, type EffectsAnalysis } from "./effects.js";
+import { checkShape, shapeOf, withExtra } from "./schema.js";
+import type { Diagnostic } from "./diagnostics.js";
+
+/** The options of the pass. */
+export interface CheckPassOptions {
+  readonly capability?: Capability<unknown> | undefined;
+}
+
+/** A capability without its deadline: the static check does not know the time of the run. */
+function withoutDeadline(capability: Capability<unknown> | undefined): Capability<unknown> | undefined {
+  if (!capability || capability.deadline === undefined) return capability;
+  const { deadline: _deadline, ...rest } = capability;
+  return rest;
+}
+
+/** True when the capability limits the reads or the writes, or refuses destructive procedures. */
+function limitsEffects(capability: Capability<unknown> | undefined): boolean {
+  const permitted = capability?.effects;
+  if (!permitted) return false;
+  const limited = (permit: readonly string[] | "any" | undefined): boolean => permit !== undefined && permit !== "any";
+  return limited(permitted.reads) || limited(permitted.writes) || permitted.destructive === false;
+}
+
+/** A procedure that has only a path and effects, for `capabilityRefusal()`. */
+function asProcedure(path: ProcedurePath, effects: Effects | undefined): AnyProcedure {
+  return { path, metadata: effects ? { effects } : {} } as unknown as AnyProcedure;
+}
+
+/** This function examines each call of the IR. */
+export function checkCalls(root: IRNode, facts: ProcedureFacts, effects: EffectsAnalysis, options: CheckPassOptions = {}): Diagnostic[] {
+  const diagnostics: Diagnostic[] = [];
+  const capability = withoutDeadline(options.capability);
+  const limited = limitsEffects(capability);
+
+  const visit = (node: IRNode): void => {
+    if (node.kind === "deferred") {
+      if (isStringPath(node.path) && node.path.length > 0 && !facts.entry(node.path)) {
+        diagnostics.push({
+          severity: "warning",
+          code: "unknown-procedure",
+          message: `No procedure has the path ${node.key}. This call waits for its runner, and the runner cannot start it.`,
+          pointer: node.pointer,
+        });
+      }
+      return;
+    }
+    if (!isCallLike(node)) return;
+    if (node.kind === "dynamic" && node.model) walk(node.model, visit);
+    const path = node.path;
+    if (!isStringPath(path) || path.length === 0 || path.some((segment) => segment.length === 0)) return;
+    const entry = facts.entry(path);
+    if (!entry) {
+      diagnostics.push({
+        severity: "error",
+        code: "unknown-procedure",
+        message: `No procedure has the path ${node.key}: the host does not have it, or it does not expose it.`,
+        pointer: node.pointer,
+      });
+      return;
+    }
+    if (!facts.exposed(path)) {
+      diagnostics.push({
+        severity: "error",
+        code: "not-exposed",
+        message: `The host does not expose ${node.key}. A program runs its calls through data-driven procedures, and they can call only exposed procedures.`,
+        pointer: node.pointer,
+      });
+    }
+    if (capability) {
+      const refusal = capabilityRefusal(asProcedure(path, entry.effects), capability);
+      if (refusal) {
+        diagnostics.push({ severity: "error", code: "capability-refused", message: `The capability refuses this call (${refusal.reason}): ${refusal.message}.`, pointer: node.pointer });
+      }
+    }
+    if (node.kind === "call" || node.kind === "dynamic") {
+      const runs = effects.nested.get(node);
+      if (runs && isUnknown(runs)) {
+        diagnostics.push({
+          severity: limited ? "error" : "info",
+          code: "effects-unknown",
+          message: limited
+            ? `${node.key} runs a program that the compiler cannot see, and the capability limits the effects. The check fails closed: run program.check on a host that can see the program.`
+            : `${node.key} runs a program that the compiler cannot see, so the effects of the program are not known.`,
+          pointer: node.pointer,
+        });
+      } else if (runs && capability) {
+        const refusal = capabilityRefusal(asProcedure(path, toEffects(runs.may)), capability);
+        if (refusal) {
+          diagnostics.push({
+            severity: "error",
+            code: "capability-refused",
+            message: `The capability refuses a call that ${node.key} runs (${refusal.reason}): ${refusal.message.replace(node.key, `the program of ${node.key}`)}.`,
+            pointer: node.pointer,
+          });
+        }
+      }
+      if (!(node.kind === "dynamic" && (node.reason === "invalid-control-flow" || node.reason === "cyclic"))) {
+        for (const issue of checkShape(withExtra(shapeOf(node.input), node.extra), entry.input)) {
+          diagnostics.push({
+            severity: "error",
+            code: "input-schema",
+            message: `The input of ${node.key} does not agree with its schema: ${issue.path ? `${issue.path}: ` : ""}${issue.message}.`,
+            pointer: issue.pointer,
+          });
+        }
+      }
+    }
+  };
+  walk(root, visit);
+  return diagnostics;
+}

package/src/codegen-closure.ts

@@ -0,0 +1,224 @@
+/**
+ * The closure code: the IR to a JavaScript function made of closures. A host runs it without
+ * `eval` and without `new Function`.
+ *
+ * The function does the steps of the interpreter in the same order. Each call goes through
+ * `ctx.client.call`, so it keeps its admission, validation, deadline and interceptors. The
+ * control-flow procedures do not start: the function does their work in line. A dynamic node
+ * calls its procedure with the raw input, and the interpreter of the client runs it.
+ */
+
+import type { IRNode, ItemsSpec, ProgramIR, ScopeSnapshot } from "./ir.js";
+import {
+  call,
+  callRaw,
+  deferred,
+  execWithInput,
+  fail,
+  get,
+  items as itemsOf,
+  merge,
+  message,
+  object,
+  parallel,
+  truthy,
+  unknownName,
+  type CompiledProgram,
+  type ProgramContext,
+  type RuntimeFrame,
+} from "./runtime.js";
+
+/** The state of one run: the context and the value of each binding. */
+interface State {
+  readonly ctx: ProgramContext;
+  readonly vars: unknown[];
+}
+
+type Run = (state: State) => Promise<unknown>;
+
+/** The options of the closure code. */
+export interface ClosureOptions {
+  /** The keys of the procedures that take raw input, for `client.exec(program, input)`. */
+  readonly rawKeys: readonly string[];
+}
+
+/** This function makes the closure code of a program. */
+export function compileClosure(ir: ProgramIR, options: ClosureOptions): CompiledProgram {
+  const root = compile(ir.root);
+  const { mode, program, input: inputBinding, bindingCount } = ir;
+  const rawKeys = [...options.rawKeys];
+  return async (ctx: ProgramContext, input?: unknown): Promise<unknown> => {
+    if (mode === "exec" && input !== undefined) return execWithInput(ctx, program, input, rawKeys);
+    const state: State = { ctx, vars: new Array<unknown>(bindingCount) };
+    if (inputBinding) state.vars[inputBinding.id] = input;
+    return root(state);
+  };
+}
+
+/** The frames of a scope with the values of a run, for `withScope()`. */
+function framesOf(snapshot: ScopeSnapshot, vars: readonly unknown[]): RuntimeFrame[] | undefined {
+  if (!snapshot) return undefined;
+  return snapshot.map((frame) => ({
+    names: frame.names.map(([name, binding]): readonly [string, unknown] => [name, vars[binding.id]]),
+    ...(frame.last ? { last: [vars[frame.last.id]] as const } : {}),
+  }));
+}
+
+function compileItems(spec: ItemsSpec): (state: State) => Promise<unknown[]> {
+  if (spec.kind === "list") {
+    const runs = spec.items.map(compile);
+    return async (state) => {
+      const values: unknown[] = [];
+      for (const run of runs) values.push(await run(state));
+      return values;
+    };
+  }
+  const run = compile(spec.value);
+  return async (state) => itemsOf(await run(state));
+}
+
+function compile(node: IRNode): Run {
+  switch (node.kind) {
+    case "literal": {
+      const value = node.value;
+      return async () => value;
+    }
+    case "object": {
+      const parts = node.entries.map((entry) => [entry.key, compile(entry.value)] as const);
+      return async (state) => {
+        const entries: Array<readonly [string, unknown]> = [];
+        for (const [key, run] of parts) entries.push([key, await run(state)]);
+        return object(entries);
+      };
+    }
+    case "array": {
+      const runs = node.items.map(compile);
+      return async (state) => {
+        const values: unknown[] = [];
+        for (const run of runs) values.push(await run(state));
+        return values;
+      };
+    }
+    case "reference": {
+      const { binding, fields, text, deferred: isDeferred, source } = node;
+      if (binding) {
+        const id = binding.id;
+        return fields.length === 0 ? async (state) => state.vars[id] : async (state) => get(state.vars[id], fields);
+      }
+      if (isDeferred) return async () => source;
+      return async () => unknownName(text);
+    }
+    case "call": {
+      const input = compile(node.input);
+      const { path, extra } = node;
+      return async (state) => call(state.ctx, path, merge(await input(state), extra));
+    }
+    case "deferred": {
+      const input = compile(node.input);
+      const source = node.source;
+      return async (state) => deferred(source, await input(state));
+    }
+    case "dynamic": {
+      const input = compile(node.input);
+      const { path, extra, scope } = node;
+      return async (state) => callRaw(state.ctx, path, merge(await input(state), extra), framesOf(scope, state.vars));
+    }
+    case "fail": {
+      const text = node.message;
+      return async () => fail(text);
+    }
+    case "chain": {
+      const initial = node.initialInput ? compile(node.initialInput) : undefined;
+      const initialId = node.initial?.id;
+      const steps = node.steps.map((step) => [step.result.id, compile(step.node)] as const);
+      return async (state) => {
+        if (initial && initialId !== undefined) state.vars[initialId] = await initial(state);
+        const results: unknown[] = [];
+        for (const [id, run] of steps) {
+          const result = await run(state);
+          state.vars[id] = result;
+          results.push(result);
+        }
+        return { results, final: results[results.length - 1] };
+      };
+    }
+    case "parallel": {
+      const tasks = node.tasks.map(compile);
+      const { concurrency, failFast } = node;
+      return async (state) => parallel(tasks.map((task) => () => task(state)), concurrency, failFast);
+    }
+    case "conditional": {
+      const condition = compile(node.condition);
+      const thenRun = node.then ? compile(node.then) : undefined;
+      const elseRun = node.else ? compile(node.else) : undefined;
+      return async (state) => {
+        const branch = truthy(await condition(state)) ? thenRun : elseRun;
+        return branch ? branch(state) : undefined;
+      };
+    }
+    case "try": {
+      const tried = compile(node.try);
+      const caught = compile(node.catch);
+      const errorId = node.error.id;
+      return async (state) => {
+        try {
+          const value = await tried(state);
+          return { success: true, value };
+        } catch (error) {
+          const text = message(error);
+          state.vars[errorId] = text;
+          const value = await caught(state);
+          return { success: false, value, error: text };
+        }
+      };
+    }
+    case "and":
+    case "or": {
+      const values = node.values.map(compile);
+      const stop = node.kind === "and" ? (value: unknown) => !value : (value: unknown) => Boolean(value);
+      return async (state) => {
+        let last: unknown = undefined;
+        for (const run of values) {
+          last = await run(state);
+          if (stop(last)) return last;
+        }
+        return last;
+      };
+    }
+    case "map": {
+      const list = compileItems(node.items);
+      const fn = node.fn ? compile(node.fn) : undefined;
+      const itemId = node.item.id;
+      const indexId = node.index.id;
+      return async (state) => {
+        const values = await list(state);
+        if (!fn) return { results: values };
+        const results: unknown[] = [];
+        for (const [index, item] of values.entries()) {
+          state.vars[itemId] = item;
+          state.vars[indexId] = index;
+          results.push(await fn(state));
+        }
+        return { results };
+      };
+    }
+    case "reduce": {
+      const initial = compile(node.initial);
+      if (!node.fn || !node.items) return initial;
+      const list = compileItems(node.items);
+      const fn = compile(node.fn);
+      const { acc: accBinding, item: itemBinding, index: indexBinding } = node;
+      return async (state) => {
+        const values = await list(state);
+        let acc = await initial(state);
+        for (const [index, item] of values.entries()) {
+          state.vars[accBinding.id] = acc;
+          state.vars[itemBinding.id] = item;
+          state.vars[indexBinding.id] = index;
+          acc = await fn(state);
+        }
+        return acc;
+      };
+    }
+  }
+}