@procedures/compiler 0.0.0-stage → 0.3.0

package/src/openrpc.ts

@@ -0,0 +1,104 @@
+/**
+ * An OpenRPC document from a manifest (roadmap R23).
+ *
+ * The manifest of a host (`describeRegistry()`, `procedure.manifest`, roadmap R17) has the JSON
+ * Schemas of each procedure. This module writes them as an OpenRPC 1.3 document: one method for
+ * each procedure. A tool of the OpenRPC ecosystem can then show the procedures or make a client.
+ *
+ * The keys of each object have a fixed order, and the methods are in the order of their names.
+ * Thus one manifest always gives the same text, and a golden file can hold it.
+ */
+
+import type { Effects, ProcedureManifest, ProcedurePath } from "@procedures/client/browser";
+
+/** The version of the OpenRPC specification of the documents. */
+export const OPENRPC_VERSION = "1.3.2";
+
+/** A content descriptor of OpenRPC: a name and a JSON Schema. */
+export interface OpenRpcContentDescriptor {
+  readonly name: string;
+  readonly required?: boolean | undefined;
+  readonly schema: Record<string, unknown>;
+}
+
+/** One method of an OpenRPC document: one procedure. */
+export interface OpenRpcMethod {
+  /** The key of the procedure: its path with dots. */
+  readonly name: string;
+  readonly description?: string | undefined;
+  readonly tags?: ReadonlyArray<{ readonly name: string }> | undefined;
+  readonly params: readonly [OpenRpcContentDescriptor];
+  readonly result: OpenRpcContentDescriptor;
+  readonly deprecated?: boolean | undefined;
+  /** The path of the procedure. A segment can have a dot, so the name alone does not give the path. */
+  readonly "x-path": ProcedurePath;
+  /** The declared effects of the procedure. Absent: the procedure does not declare its effects. */
+  readonly "x-effects"?: Effects | undefined;
+  /** True: the procedure operates its input as a program (control flow, a defined procedure). */
+  readonly "x-data-driven"?: boolean | undefined;
+}
+
+/** An OpenRPC 1.3 document. */
+export interface OpenRpcDocument {
+  readonly openrpc: string;
+  readonly info: { readonly title: string; readonly version: string; readonly description?: string | undefined };
+  readonly methods: OpenRpcMethod[];
+}
+
+/** The options of `toOpenRpc()`. */
+export interface OpenRpcOptions {
+  /** The title of the document. The default is "Procedures". */
+  readonly title?: string | undefined;
+  /** The version of the document. The default is the hash of the manifest. */
+  readonly version?: string | undefined;
+  /** The description of the document. */
+  readonly description?: string | undefined;
+}
+
+/** A copy of a JSON value: only JSON values, and no `undefined`. */
+function jsonCopy(value: unknown): Record<string, unknown> {
+  if (value === undefined) return {};
+  const copy = JSON.parse(JSON.stringify(value)) as unknown;
+  return copy !== null && typeof copy === "object" && !Array.isArray(copy) ? (copy as Record<string, unknown>) : {};
+}
+
+/** The effects with their keys in a fixed order. */
+function effectsCopy(effects: Effects): Effects {
+  return {
+    ...(effects.reads ? { reads: [...effects.reads] } : {}),
+    ...(effects.writes ? { writes: [...effects.writes] } : {}),
+    ...(effects.destructive !== undefined ? { destructive: effects.destructive } : {}),
+    ...(effects.idempotent !== undefined ? { idempotent: effects.idempotent } : {}),
+  };
+}
+
+/**
+ * This function writes a manifest as an OpenRPC 1.3 document. Each procedure is a method with
+ * its key as the name. The input schema is the one parameter `input`. The output schema is the
+ * result `output`. The declared effects are the extension `x-effects`.
+ */
+export function toOpenRpc(manifest: ProcedureManifest, options: OpenRpcOptions = {}): OpenRpcDocument {
+  const entries = [...manifest.procedures].sort((a, b) => (a.key < b.key ? -1 : a.key > b.key ? 1 : 0));
+  const methods = entries.map(
+    (entry): OpenRpcMethod => ({
+      name: entry.key,
+      ...(entry.description !== undefined ? { description: entry.description } : {}),
+      ...(entry.tags && entry.tags.length > 0 ? { tags: entry.tags.map((name) => ({ name })) } : {}),
+      params: [{ name: "input", required: true, schema: jsonCopy(entry.input) }],
+      result: { name: "output", schema: jsonCopy(entry.output) },
+      ...(entry.deprecated ? { deprecated: true } : {}),
+      "x-path": [...entry.path],
+      ...(entry.effects ? { "x-effects": effectsCopy(entry.effects) } : {}),
+      ...(entry.dataDriven ? { "x-data-driven": true } : {}),
+    }),
+  );
+  return {
+    openrpc: OPENRPC_VERSION,
+    info: {
+      title: options.title ?? "Procedures",
+      version: options.version ?? manifest.hash,
+      ...(options.description !== undefined ? { description: options.description } : {}),
+    },
+    methods,
+  };
+}

package/src/print.ts

@@ -0,0 +1,143 @@
+/**
+ * A text form of the IR, with one node on each line. The golden tests and the persons who read
+ * the result of the compiler use it.
+ */
+
+import type { Binding, IRNode, ItemsSpec, ProgramIR, ScopeSnapshot } from "./ir.js";
+
+function json(value: unknown): string {
+  try {
+    const text = JSON.stringify(value);
+    return text === undefined ? String(value) : text.length > 80 ? `${text.slice(0, 77)}...` : text;
+  } catch {
+    return "<not JSON>";
+  }
+}
+
+function binding(value: Binding | undefined): string {
+  if (!value) return "-";
+  return value.name === undefined ? `b${value.id}` : `b${value.id}:${value.name}`;
+}
+
+function scope(snapshot: ScopeSnapshot): string {
+  if (!snapshot) return "none";
+  return snapshot
+    .map((frame) => `[${frame.names.map(([name, value]) => `${name}=${binding(value)}`).join(" ")}${frame.last ? ` $last=${binding(frame.last)}` : ""}]`)
+    .join(" ");
+}
+
+function extra(value: Readonly<Record<string, unknown>>): string {
+  return Object.keys(value).length > 0 ? ` extra=${json(value)}` : "";
+}
+
+/** This function gives the text of the IR of a program. */
+export function printIR(ir: ProgramIR): string {
+  const lines: string[] = [`program mode=${ir.mode}${ir.input ? ` input=${binding(ir.input)}` : ""}`];
+  const line = (depth: number, text: string): void => {
+    lines.push(`${"  ".repeat(depth)}${text}`);
+  };
+  const items = (spec: ItemsSpec, depth: number): void => {
+    if (spec.kind === "list") {
+      line(depth, `items list(${spec.items.length})`);
+      for (const item of spec.items) visit(item, depth + 1);
+    } else {
+      line(depth, "items value");
+      visit(spec.value, depth + 1);
+    }
+  };
+  const visit = (node: IRNode, depth: number): void => {
+    const at = ` @${json(node.pointer)}`;
+    switch (node.kind) {
+      case "literal":
+        line(depth, `literal ${node.origin} ${json(node.value)}${at}`);
+        return;
+      case "object":
+        line(depth, `object${at}`);
+        for (const entry of node.entries) {
+          line(depth + 1, `key ${json(entry.key)}`);
+          visit(entry.value, depth + 2);
+        }
+        return;
+      case "array":
+        line(depth, `array(${node.items.length})${at}`);
+        for (const item of node.items) visit(item, depth + 1);
+        return;
+      case "reference":
+        line(depth, `ref ${json(node.text)} -> ${node.binding ? binding(node.binding) : node.deferred ? "data (deferred)" : "unknown"}${at}`);
+        return;
+      case "call":
+        line(depth, `call ${node.key} ${node.position}${extra(node.extra)}${at}`);
+        visit(node.input, depth + 1);
+        return;
+      case "deferred":
+        line(depth, `deferred ${node.key} when=${json(node.when)}${at}`);
+        visit(node.input, depth + 1);
+        return;
+      case "dynamic":
+        line(depth, `dynamic ${node.key} ${node.position} reason=${node.reason}${extra(node.extra)} scope=${scope(node.scope)}${at}`);
+        visit(node.input, depth + 1);
+        if (node.model) {
+          line(depth + 1, "model");
+          visit(node.model, depth + 2);
+        }
+        return;
+      case "fail":
+        line(depth, `fail ${json(node.message)}${at}`);
+        return;
+      case "chain":
+        line(depth, `chain${node.implicit ? " implicit" : ""} ${node.position}${node.passThrough ? ` passThrough initial=${binding(node.initial)}` : ""}${at}`);
+        if (node.initialInput) {
+          line(depth + 1, "initialInput");
+          visit(node.initialInput, depth + 2);
+        }
+        for (const step of node.steps) {
+          line(depth + 1, `step -> ${binding(step.result)}`);
+          visit(step.node, depth + 2);
+        }
+        return;
+      case "parallel":
+        line(depth, `parallel ${node.position} concurrency=${node.concurrency ?? "all"} failFast=${node.failFast}${at}`);
+        for (const task of node.tasks) visit(task, depth + 1);
+        return;
+      case "conditional":
+        line(depth, `conditional ${node.position}${at}`);
+        visit(node.condition, depth + 1);
+        line(depth + 1, "then");
+        if (node.then) visit(node.then, depth + 2);
+        line(depth + 1, "else");
+        if (node.else) visit(node.else, depth + 2);
+        return;
+      case "try":
+        line(depth, `try ${node.position} error=${binding(node.error)}${at}`);
+        visit(node.try, depth + 1);
+        line(depth + 1, "catch");
+        visit(node.catch, depth + 2);
+        return;
+      case "and":
+      case "or":
+        line(depth, `${node.kind} ${node.position}${at}`);
+        for (const value of node.values) visit(value, depth + 1);
+        return;
+      case "map":
+        line(depth, `map ${node.position} item=${binding(node.item)} index=${binding(node.index)}${at}`);
+        items(node.items, depth + 1);
+        if (node.fn) {
+          line(depth + 1, "fn");
+          visit(node.fn, depth + 2);
+        }
+        return;
+      case "reduce":
+        line(depth, `reduce ${node.position} acc=${binding(node.acc)} item=${binding(node.item)} index=${binding(node.index)}${at}`);
+        if (node.items) items(node.items, depth + 1);
+        line(depth + 1, "initial");
+        visit(node.initial, depth + 2);
+        if (node.fn) {
+          line(depth + 1, "fn");
+          visit(node.fn, depth + 2);
+        }
+        return;
+    }
+  };
+  visit(ir.root, 1);
+  return `${lines.join("\n")}\n`;
+}

package/src/procedures/program/check.ts

@@ -0,0 +1,31 @@
+/**
+ * program.check procedure
+ *
+ * Check a program before it runs: the names, the procedures, the inputs, the capability and the
+ * effects. No call of the program starts.
+ */
+
+import { PROCEDURE_REGISTRY, type ProcedureContext } from "@procedures/client/browser";
+import { checkProgram } from "../../program.js";
+import { toCapability, type ProgramCheckInput, type ProgramCheckOutput } from "../../types.js";
+import { effectsOutput } from "./effects-output.js";
+
+/**
+ * This function checks a program against the registry and the expose rule of the host. The
+ * capability is the capability of the input, or the capability of the caller.
+ */
+export async function programCheck(input: ProgramCheckInput, ctx?: ProcedureContext): Promise<ProgramCheckOutput> {
+  const result = checkProgram(input.program, {
+    registry: ctx?.registry ?? PROCEDURE_REGISTRY,
+    expose: ctx?.expose,
+    capability: input.capability ? toCapability(input.capability) : ctx?.capability,
+    mode: input.mode,
+  });
+  return {
+    ok: result.ok,
+    effects: effectsOutput(result.effects),
+    mustEffects: result.mustEffects,
+    diagnostics: result.diagnostics,
+    registryHash: result.registryHash,
+  };
+}

package/src/procedures/program/compile.ts

@@ -0,0 +1,36 @@
+/**
+ * program.compile procedure
+ *
+ * This procedure compiles a program to a JavaScript function. It checks the program first. Then
+ * it writes the text of an ES module.
+ */
+
+import { PROCEDURE_REGISTRY, type ProcedureContext } from "@procedures/client/browser";
+import { compileProgram } from "../../program.js";
+import { toCapability, type ProgramCompileInput, type ProgramCompileOutput } from "../../types.js";
+import { effectsOutput } from "./effects-output.js";
+
+/**
+ * This function compiles a program against the registry and the expose rule of the host. The
+ * output has the source text, not the closure code: a closure does not go through JSON.
+ */
+export async function programCompile(input: ProgramCompileInput, ctx?: ProcedureContext): Promise<ProgramCompileOutput> {
+  const result = await compileProgram(input.program, {
+    registry: ctx?.registry ?? PROCEDURE_REGISTRY,
+    expose: ctx?.expose,
+    capability: input.capability ? toCapability(input.capability) : ctx?.capability,
+    mode: input.mode,
+    fold: input.fold,
+    language: input.language,
+  });
+  return {
+    ok: result.ok,
+    effects: effectsOutput(result.effects),
+    mustEffects: result.mustEffects,
+    diagnostics: result.diagnostics,
+    registryHash: result.registryHash,
+    code: result.code,
+    sourceMap: result.sourceMap,
+    folded: [...result.folded],
+  };
+}

package/src/procedures/program/diagram.ts

@@ -0,0 +1,25 @@
+/**
+ * program.diagram procedure
+ *
+ * This procedure draws a program as a Mermaid flowchart: the order of the calls, the control
+ * flow and the names. No call of the program starts.
+ */
+
+import { PROCEDURE_REGISTRY, type ProcedureContext } from "@procedures/client/browser";
+import { diagramProgram } from "../../mermaid.js";
+import type { ProgramDiagramInput, ProgramDiagramOutput } from "../../types.js";
+
+/**
+ * This function checks a program against the registry and the expose rule of the host. It gives
+ * the flowchart of the IR and the diagnostics of the check.
+ */
+export async function programDiagram(input: ProgramDiagramInput, ctx?: ProcedureContext): Promise<ProgramDiagramOutput> {
+  const result = diagramProgram(input.program, {
+    registry: ctx?.registry ?? PROCEDURE_REGISTRY,
+    expose: ctx?.expose,
+    capability: ctx?.capability,
+    mode: input.mode,
+    direction: input.direction,
+  });
+  return { mermaid: result.mermaid, diagnostics: result.diagnostics };
+}

package/src/procedures/program/effects-output.ts

@@ -0,0 +1,16 @@
+/**
+ * The effects of a program in the JSON output of the procedures.
+ */
+
+import type { Effects } from "@procedures/client/browser";
+import type { EffectsOutput } from "../../types.js";
+
+/** This function copies the effects into mutable lists for the output schema. */
+export function effectsOutput(effects: Effects): EffectsOutput {
+  return {
+    ...(effects.reads ? { reads: [...effects.reads] } : {}),
+    ...(effects.writes ? { writes: [...effects.writes] } : {}),
+    ...(effects.destructive !== undefined ? { destructive: effects.destructive } : {}),
+    ...(effects.idempotent !== undefined ? { idempotent: effects.idempotent } : {}),
+  };
+}

package/src/procedures/program/explain.ts

@@ -0,0 +1,46 @@
+/**
+ * program.explain procedure
+ *
+ * This procedure explains a program before it starts: the effects, each call with its declared
+ * effects and the answer of the capability, and the diagnostics. No call of the program starts.
+ */
+
+import { PROCEDURE_REGISTRY, type ProcedureContext } from "@procedures/client/browser";
+import { explainProgram } from "../../explain.js";
+import { toCapability, type CallExplanationOutput, type ProgramExplainInput, type ProgramExplainOutput } from "../../types.js";
+import { effectsOutput } from "./effects-output.js";
+
+/**
+ * This function explains a program against the registry and the expose rule of the host. The
+ * capability is the capability of the input, or the capability of the caller.
+ */
+export async function programExplain(input: ProgramExplainInput, ctx?: ProcedureContext): Promise<ProgramExplainOutput> {
+  const result = explainProgram(input.program, {
+    registry: ctx?.registry ?? PROCEDURE_REGISTRY,
+    expose: ctx?.expose,
+    capability: input.capability ? toCapability(input.capability) : ctx?.capability,
+    mode: input.mode,
+  });
+  return {
+    ok: result.ok,
+    effects: effectsOutput(result.effects),
+    mustEffects: result.mustEffects,
+    calls: result.calls.map(
+      (call): CallExplanationOutput => ({
+        key: call.key,
+        path: [...call.path],
+        pointer: call.pointer,
+        kind: call.kind,
+        ...(call.effects ? { effects: effectsOutput(call.effects) } : {}),
+        known: call.known,
+        exposed: call.exposed,
+        permitted: call.permitted,
+        ...(call.reason !== undefined ? { reason: call.reason } : {}),
+        message: call.message,
+      }),
+    ),
+    diagnostics: result.diagnostics,
+    registryHash: result.registryHash,
+    summary: result.summary,
+  };
+}

package/src/procedures/program/index.ts

@@ -0,0 +1,4 @@
+export { programCheck } from "./check.js";
+export { programCompile } from "./compile.js";
+export { programDiagram } from "./diagram.js";
+export { programExplain } from "./explain.js";

package/src/procedures/sdk/index.ts

@@ -0,0 +1,2 @@
+export { sdkOpenrpc } from "./openrpc.js";
+export { sdkTypescript } from "./typescript.js";

package/src/procedures/sdk/manifest.ts

@@ -0,0 +1,17 @@
+/**
+ * The manifest that the procedures `sdk.openrpc` and `sdk.typescript` read.
+ */
+
+import { describeRegistry, PROCEDURE_REGISTRY, type AnyProcedure, type ProcedureContext, type ProcedureManifest } from "@procedures/client/browser";
+import type { SdkInput } from "../../types.js";
+
+/**
+ * This function describes the registry of the caller, as `procedure.manifest` does. The manifest
+ * has only the procedures that the host exposes, and only one namespace when the input names it.
+ */
+export function manifestOf(input: SdkInput, ctx?: ProcedureContext): ProcedureManifest {
+  return describeRegistry(ctx?.registry ?? PROCEDURE_REGISTRY, {
+    ...(ctx?.expose ? { expose: ctx.expose } : {}),
+    ...(input.namespace ? { include: (procedure: AnyProcedure) => procedure.path[0] === input.namespace } : {}),
+  });
+}

package/src/procedures/sdk/openrpc.ts

@@ -0,0 +1,16 @@
+/**
+ * sdk.openrpc procedure
+ *
+ * This procedure describes the procedures of the registry as an OpenRPC 1.3 document. It reads
+ * the registry of the caller and obeys the expose rule of the host, as `procedure.manifest` does.
+ */
+
+import type { ProcedureContext } from "@procedures/client/browser";
+import { toOpenRpc } from "../../openrpc.js";
+import type { SdkOpenrpcInput, SdkOpenrpcOutput } from "../../types.js";
+import { manifestOf } from "./manifest.js";
+
+/** This function gives the OpenRPC document of the procedures that the host exposes. */
+export async function sdkOpenrpc(input: SdkOpenrpcInput, ctx?: ProcedureContext): Promise<SdkOpenrpcOutput> {
+  return toOpenRpc(manifestOf(input, ctx)) as unknown as SdkOpenrpcOutput;
+}

package/src/procedures/sdk/typescript.ts

@@ -0,0 +1,17 @@
+/**
+ * sdk.typescript procedure
+ *
+ * This procedure writes a typed TypeScript SDK for the procedures of the registry. It reads the
+ * registry of the caller and obeys the expose rule of the host, as `procedure.manifest` does.
+ */
+
+import type { ProcedureContext } from "@procedures/client/browser";
+import { toTypeScriptSdk } from "../../typescript-sdk.js";
+import type { SdkTypescriptInput, SdkTypescriptOutput } from "../../types.js";
+import { manifestOf } from "./manifest.js";
+
+/** This function gives the source of the SDK of the procedures that the host exposes. */
+export async function sdkTypescript(input: SdkTypescriptInput, ctx?: ProcedureContext): Promise<SdkTypescriptOutput> {
+  const manifest = manifestOf(input, ctx);
+  return { code: toTypeScriptSdk(manifest), procedures: manifest.procedures.length, registryHash: manifest.hash };
+}

package/src/program.ts

@@ -0,0 +1,181 @@
+/**
+ * The functions of the compiler: `checkProgram()` and `compileProgram()`.
+ *
+ * Both read the facts of the procedures from a manifest (a browser) or from a registry (a host).
+ * They run the passes in order: normalize, scopes, effects and checks. `compileProgram()` then
+ * folds the pure calls (optional) and writes the code: the closure code and the source text.
+ */
+
+import { pathToKey, type Capability, type Effects, type ProcedureManifest, type ProcedurePath } from "@procedures/client/browser";
+import type { ProgramIR } from "./ir.js";
+import { manifestFacts, registryFacts, withDefinitions, type ProcedureFacts, type RegistryLike } from "./facts.js";
+import { findDefinitions, normalize } from "./normalize.js";
+import { resolveScopes } from "./scopes.js";
+import { inferEffects, toEffects, type EffectSummary } from "./effects.js";
+import { checkCalls } from "./checks.js";
+import { hasErrors, sortDiagnostics, type Diagnostic } from "./diagnostics.js";
+import { foldProgram } from "./fold.js";
+import { compileClosure } from "./codegen-closure.js";
+import { emitText, type SourceMapLine } from "./codegen-text.js";
+import type { CompiledProgram } from "./runtime.js";
+
+/** The options of `checkProgram()`. Give a manifest, a registry or facts. */
+export interface CheckOptions {
+  /** The manifest of the host (`procedure.manifest`). A browser has only this. */
+  readonly manifest?: ProcedureManifest | undefined;
+  /** The registry of the host. It also gives the bodies of the defined procedures. */
+  readonly registry?: RegistryLike | undefined;
+  /** The facts of the procedures, when the caller made them already. */
+  readonly facts?: ProcedureFacts | undefined;
+  /** The expose rule of the host. The default exposes each procedure. */
+  readonly expose?: ((path: ProcedurePath) => boolean) | undefined;
+  /** The capability of the run. The check refuses each call that the capability refuses. */
+  readonly capability?: Capability<unknown> | undefined;
+  /** `exec` (the default): the program runs as `client.exec()` runs it. `body`: as the body of a defined procedure. */
+  readonly mode?: "exec" | "body" | undefined;
+}
+
+/** The effects of each run in which no call fails. */
+export interface MustEffects {
+  readonly reads: string[];
+  readonly writes: string[];
+}
+
+/** The result of `checkProgram()`. */
+export interface CheckResult {
+  /** True when no diagnostic is an error. A host starts the program only then. */
+  readonly ok: boolean;
+  /** The effects that a run can have (the upper bound). An absent `reads` or `writes`: not known. */
+  readonly effects: Effects;
+  /** The effects of each run in which no call fails (the lower bound). */
+  readonly mustEffects: MustEffects;
+  /** The problems, in the order of the program. */
+  readonly diagnostics: Diagnostic[];
+  /** The hash of the manifest that the check used. */
+  readonly registryHash: string;
+  /** The IR of the program. */
+  readonly ir: ProgramIR;
+}
+
+/** The options of `compileProgram()`. */
+export interface CompileOptions extends CheckOptions {
+  /** True: compute the pure core calls with literal inputs at compile time (the fold pass). The default is false. */
+  readonly fold?: boolean | undefined;
+  /** The language of the source text: `js` (the default) or `ts`. */
+  readonly language?: "js" | "ts" | undefined;
+  /** The import specifier of the runtime in the source text. The default is `@procedures/compiler/runtime`. */
+  readonly runtime?: string | undefined;
+}
+
+/** The result of `compileProgram()`. */
+export interface CompileResult extends CheckResult {
+  /** The closure code: a host runs it as `run(ctx, input)`. It uses no `eval`. */
+  readonly run: CompiledProgram;
+  /** The source text: an ES module whose default export is `async (ctx, input) => output`. */
+  readonly code: string;
+  /** The body of an async function with the parameters `rt`, `ctx` and `input` (JavaScript). */
+  readonly body: string;
+  /** The lines of `code` and the pointers of their parts of the program. */
+  readonly sourceMap: SourceMapLine[];
+  /** The pointers of the calls that the fold pass computed. */
+  readonly folded: readonly string[];
+}
+
+/** The facts of the options: the facts, else the facts of the registry, else the facts of the manifest. */
+export function baseFacts(options: CheckOptions): ProcedureFacts {
+  if (options.facts) return options.facts;
+  if (options.registry) return registryFacts(options.registry, { expose: options.expose });
+  if (options.manifest) return manifestFacts(options.manifest, { expose: options.expose });
+  throw new Error("checkProgram: give a manifest, a registry or facts");
+}
+
+interface Analysis {
+  readonly facts: ProcedureFacts;
+  readonly ir: ProgramIR;
+  readonly diagnostics: Diagnostic[];
+  readonly program: EffectSummary;
+}
+
+function analyze(program: unknown, options: CheckOptions): Analysis {
+  const definitions = findDefinitions(program);
+  const facts = withDefinitions(baseFacts(options), definitions);
+  const diagnostics: Diagnostic[] = [];
+
+  // The effects of a defined body: a recursive definition gives unknown effects
+  const bodies = new Map<string, EffectSummary | "pending">();
+  const bodyEffects = (path: ProcedurePath): EffectSummary | undefined => {
+    const key = pathToKey(path);
+    const cached = bodies.get(key);
+    if (cached === "pending") return undefined;
+    if (cached) return cached;
+    const body = facts.body(path);
+    if (body === undefined) return undefined;
+    bodies.set(key, "pending");
+    const { ir } = normalize(body, facts, { mode: "body" });
+    resolveScopes(ir);
+    const summary = inferEffects(ir.root, facts, bodyEffects).program;
+    bodies.set(key, summary);
+    return summary;
+  };
+
+  // The bodies that the program defines are a part of the program: their problems have pointers in it
+  for (const definition of definitions.values()) {
+    const body = normalize(definition.body, facts, { mode: "body", base: definition.pointer });
+    diagnostics.push(...body.diagnostics, ...resolveScopes(body.ir));
+    diagnostics.push(...checkCalls(body.ir.root, facts, inferEffects(body.ir.root, facts, bodyEffects)));
+  }
+
+  const result = normalize(program, facts, { mode: options.mode ?? "exec" });
+  diagnostics.push(...result.diagnostics, ...resolveScopes(result.ir));
+  const effects = inferEffects(result.ir.root, facts, bodyEffects);
+  diagnostics.push(...checkCalls(result.ir.root, facts, effects, { capability: options.capability }));
+  return { facts, ir: result.ir, diagnostics, program: effects.program };
+}
+
+function summarize(analysis: Analysis, diagnostics: Diagnostic[]): Omit<CheckResult, "ir"> {
+  const sorted = sortDiagnostics(diagnostics);
+  return {
+    ok: !hasErrors(sorted),
+    effects: toEffects(analysis.program.may),
+    mustEffects: { reads: [...analysis.program.must.reads].sort(), writes: [...analysis.program.must.writes].sort() },
+    diagnostics: sorted,
+    registryHash: analysis.facts.hash,
+  };
+}
+
+/**
+ * This function checks a program before it starts. It finds each unknown name and procedure, and
+ * each input that does not agree with its schema. It also finds each call that the capability
+ * refuses, and the effects of the whole program. No call starts.
+ */
+export function checkProgram(program: unknown, options: CheckOptions): CheckResult {
+  const analysis = analyze(program, options);
+  return { ...summarize(analysis, analysis.diagnostics), ir: analysis.ir };
+}
+
+/**
+ * This function checks a program and writes it as a function: the closure code for a host and
+ * the source text for an export. The code makes the calls of the interpreter in the same order.
+ */
+export async function compileProgram(program: unknown, options: CompileOptions): Promise<CompileResult> {
+  const analysis = analyze(program, options);
+  let ir = analysis.ir;
+  let folded: readonly string[] = [];
+  if (options.fold) {
+    const result = await foldProgram(ir.root, analysis.facts);
+    ir = { ...ir, root: result.root };
+    folded = result.folded;
+  }
+  const rawKeys = analysis.facts.rawKeys;
+  const run = compileClosure(ir, { rawKeys });
+  const text = emitText(ir, { language: options.language, runtime: options.runtime, registryHash: analysis.facts.hash, rawKeys });
+  return {
+    ...summarize(analysis, [...analysis.diagnostics, ...text.diagnostics]),
+    ir,
+    run,
+    code: text.module,
+    body: text.body,
+    sourceMap: text.sourceMap,
+    folded,
+  };
+}

package/src/refs.ts

@@ -0,0 +1,9 @@
+/**
+ * The test of a `$ref` object, as `isOutputRef()` of the client has it (the browser entry of the
+ * client does not export that function).
+ */
+
+/** True for an object with a `$ref` string (also an inherited one, as the `in` test of the client). */
+export function isOutputRef(value: unknown): value is { readonly $ref: string } {
+  return typeof value === "object" && value !== null && "$ref" in value && typeof (value as { $ref?: unknown }).$ref === "string";
+}

package/src/register.ts

@@ -0,0 +1,10 @@
+/**
+ * Importing this file registers the procedures of @procedures/compiler in the global registry:
+ * `import "@procedures/compiler/register"`. The package root registers nothing.
+ */
+
+import { registerCompilerProcedures } from "./module.js";
+
+export * from "./module.js";
+
+registerCompilerProcedures();