@procedures/compiler 0.25.0 → 0.26.0

package/src/names.ts

@@ -0,0 +1,105 @@
+/**
+ * The names pass: the static kit of coeval checks the names of a program.
+ *
+ * The client changes the program into a run document of coeval (`desugarProgram()`, with the
+ * operands of the control-flow procedures as documents). The kinds of the document tell which
+ * names they bind for which parts: the steps of a chain, `last`, `item`, `index`, `acc` and
+ * `error`. Then `check()` of `@mark1russell7/coeval` finds each reference whose name no kind
+ * around it binds. This pass changes each issue into a diagnostic with the JSON pointer of the
+ * `$ref` in the program.
+ */
+
+import { check, walk, type DocVisit, type Key } from "@mark1russell7/coeval";
+import {
+  PROGRAM_WORLD,
+  desugarInput,
+  desugarProgram,
+  isAnyProcedureRef,
+  nameOfKey,
+  originOf,
+  programMachine,
+  type ProcedurePath,
+} from "@procedures/client/browser";
+import type { Diagnostic } from "./diagnostics.js";
+
+/** The options of the names pass. */
+export interface NameOptions {
+  /** `exec`: the program operates as `client.exec()` operates it. `body`: as the body of a defined procedure, with the name `input`. */
+  readonly mode: "exec" | "body";
+  /** The pointer of the program in a bigger document (the body of a definition). */
+  readonly base?: string | undefined;
+  /** The raw-input rule of the procedures. The default knows the control-flow procedures. */
+  readonly rawInput?: ((path: ProcedurePath) => boolean) | undefined;
+}
+
+/** The name of the result of the step before, in the kernel. The `$proc` form writes it as `$last`. */
+const LAST = "last";
+
+/** The `$proc` text of a name of the kernel. */
+function procName(key: string): string {
+  return key === LAST ? "$last" : nameOfKey(key);
+}
+
+function placeKey(place: readonly Key[]): string {
+  return place.map(String).join("\u0000");
+}
+
+/**
+ * This function gives the diagnostics of the names of a program. It uses `check()` of coeval on
+ * the run document of the program.
+ */
+export function nameDiagnostics(program: unknown, options: NameOptions): Diagnostic[] {
+  const body = options.mode === "body";
+  const settings = { rawInput: options.rawInput, scoped: body, expand: true };
+  const doc = isAnyProcedureRef(program) ? desugarProgram(program, settings) : body ? desugarInput(program, settings) : undefined;
+  if (!doc) return [];
+  const names = body ? ["input"] : [];
+  // The visit of each document, by its place. A part that is the whole value of its document has the
+  // place of its document: the deeper visit comes later, and it stays.
+  const visits = new Map<string, DocVisit>();
+  walk(PROGRAM_WORLD, doc, (visit) => void visits.set(placeKey(visit.place), visit), { names });
+  const issues = check(programMachine({ rawInput: options.rawInput ?? (() => false) }), doc, { names });
+  const diagnostics: Diagnostic[] = [];
+  for (const issue of issues) {
+    if (issue.code !== "#NAME?") continue;
+    const visit = visits.get(placeKey(issue.place));
+    const origin = visit ? originOf(visit.doc) : undefined;
+    const source = origin?.source as { readonly $ref?: unknown } | undefined;
+    if (!visit || !origin || typeof source?.$ref !== "string") continue;
+    const text = source.$ref;
+    const name = text.split(".")[0] ?? "";
+    const key = (visit.doc.value as readonly unknown[])[1];
+    const pointer = `${options.base ?? ""}${origin.pointer}`;
+    diagnostics.push(diagnosticOf(origin.deferred === true, visit, String(key), name, text, pointer));
+  }
+  return diagnostics;
+}
+
+/** This function makes the diagnostic of one name that no kind binds. */
+function diagnosticOf(deferred: boolean, visit: DocVisit, key: string, name: string, text: string, pointer: string): Diagnostic {
+  if (deferred) {
+    return {
+      severity: "info",
+      code: "unknown-name",
+      message: `No scope has the name "${name}" here. In the input of a deferred call, the $ref stays data for the runner.`,
+      pointer,
+    };
+  }
+  // The result of the step before is not the name of a step: the first step of a chain has no $last
+  if (key !== LAST && visit.later.has(key)) {
+    return {
+      severity: "error",
+      code: "use-before-definition",
+      message: `The $ref "${text}" reads "${name}" before the step that makes it: a step reads only the names of the steps before it.`,
+      pointer,
+    };
+  }
+  const known = [...new Set([...visit.names].map(procName))];
+  const here = known.length > 0 ? ` The names here: ${known.join(", ")}.` : " No name is in the scope here.";
+  return {
+    severity: "error",
+    code: "unknown-name",
+    message: `Unknown $ref name "${name}" in "${text}".${here}${name === "$last" ? " The first step of a chain has no $last." : ""}`,
+    pointer,
+  };
+}

package/src/normalize.ts

@@ -130,7 +130,7 @@ class Normalizer {
     if (mode === "body") {
       const input = this.binding("input", "input", base);
       const root = isAnyProcedureRef(program) ? this.rootCall(program, true, base) : this.hydrateRoot(program, true, base);
-      return { mode, root, input, bindingCount: this.bindingCount, program };
+      return { mode, root, input, bindingCount: this.bindingCount, program, base };
     }
     let root: IRNode;
     if (isAnyProcedureRef(program)) {
@@ -142,7 +142,7 @@ class Normalizer {
       this.report("error", "root-not-call", "The program must be a call ({ $proc, input }): client.exec() starts only a call.", base);
       root = { kind: "fail", pointer: base, message: ROOT_NOT_CALL_MESSAGE };
     }
-    return { mode, root, input: undefined, bindingCount: this.bindingCount, program };
+    return { mode, root, input: undefined, bindingCount: this.bindingCount, program, base };
   }
 
   // ===========================================================================

package/src/program.ts

@@ -10,7 +10,7 @@ import { pathToKey, type Capability, type Effects, type ProcedureManifest, type
 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 { bindScopes, 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";
@@ -112,7 +112,7 @@ function analyze(program: unknown, options: CheckOptions): Analysis {
     if (body === undefined) return undefined;
     bodies.set(key, "pending");
     const { ir } = normalize(body, facts, { mode: "body" });
-    resolveScopes(ir);
+    bindScopes(ir);
     const summary = inferEffects(ir.root, facts, bodyEffects).program;
     bodies.set(key, summary);
     return summary;
@@ -121,12 +121,12 @@ function analyze(program: unknown, options: CheckOptions): Analysis {
   // 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(...body.diagnostics, ...resolveScopes(body.ir, facts));
     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));
+  diagnostics.push(...result.diagnostics, ...resolveScopes(result.ir, facts));
   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 };

package/src/scopes.ts

@@ -1,37 +1,50 @@
 /**
- * The scopes pass: each `$ref` gets the binding that the interpreter reads.
+ * The scopes pass: each `$ref` gets the binding that the interpreter reads, for the generated code.
  *
- * The pass follows `lookupOutputRef()` of the client. The innermost frame with the name gives the
- * value. `$last` is the last result of the innermost frame that has one. A chain frame gets a
- * name after its step: a step reads only the names of the steps before it. A name that no frame
- * has is an error (`Unknown $ref name`). In the input of a deferred call, the runner can give the
- * name later, so there the name stays.
+ * The pass follows the names of the kernel. The innermost frame with the name gives the value.
+ * `$last` is the last result of the innermost frame that has one. A chain frame gets a name after
+ * its step: a step reads only the names of the steps before it.
+ *
+ * The rules of the names (an unknown name, a use before the definition) run through `check()` of
+ * coeval on the run document of the program (`names.ts`). This pass gives their diagnostics too.
  */
 
 import { isPlainObject } from "@procedures/client/browser";
 import { isOutputRef } from "./refs.js";
 import { childPointer, type Binding, type IRNode, type ItemsSpec, type Pointer, type ProgramIR, type ReferenceNode, type ScopeFrame, type ScopeSnapshot } from "./ir.js";
 import type { Diagnostic } from "./diagnostics.js";
+import type { ProcedureFacts } from "./facts.js";
+import { nameDiagnostics } from "./names.js";
 
 /** A frame while the pass walks: the names grow as the steps of a chain pass. */
 interface Frame {
   readonly names: Map<string, Binding>;
   last: Binding | undefined;
-  /** The names of this step and the later steps of a chain, to find a use before the definition. */
-  later: ReadonlySet<string>;
 }
 
 type Env = readonly Frame[] | undefined;
 
 /**
- * This function resolves the references of the IR and gives the diagnostics of the names.
+ * This function resolves the references of the IR, and gives the diagnostics of the names. The
+ * static kit of coeval finds the problems of the names (`nameDiagnostics()`). Give the facts of
+ * the procedures for their raw-input rule. The default knows the control-flow procedures.
  *
- * Deprecated behavior (D26): the diagnostics come in the order of the program tree. From the next
- * MINOR, the warnings for the raw input come first, and then the diagnostics of the names. The
- * function, the codes and the messages stay. Sort the diagnostics by `pointer` when the order
- * matters.
+ * The order of the diagnostics (D26): first the warnings for the raw input, then the diagnostics
+ * of the names. Before 0.26.0, the diagnostics came in the order of the program tree. Sort the
+ * diagnostics by `pointer` when the order matters.
  */
-export function resolveScopes(ir: ProgramIR): Diagnostic[] {
+export function resolveScopes(ir: ProgramIR, facts?: Pick<ProcedureFacts, "rawInput">): Diagnostic[] {
+  const diagnostics = bindScopes(ir);
+  const rawInput = facts ? (path: readonly string[]) => facts.rawInput(path as string[]) : undefined;
+  diagnostics.push(...nameDiagnostics(ir.program, { mode: ir.mode, base: ir.base, rawInput }));
+  return diagnostics;
+}
+
+/**
+ * This function resolves the references of the IR only. It gives the warnings for the raw input
+ * of a procedure that runs refs, and no diagnostics of the names.
+ */
+export function bindScopes(ir: ProgramIR): Diagnostic[] {
   const diagnostics: Diagnostic[] = [];
   const root: Env = ir.input ? [frameOf([["input", ir.input]])] : undefined;
   visit(ir.root, root, diagnostics);
@@ -39,7 +52,7 @@ export function resolveScopes(ir: ProgramIR): Diagnostic[] {
 }
 
 function frameOf(names: ReadonlyArray<readonly [string, Binding]>): Frame {
-  return { names: new Map(names), last: undefined, later: new Set() };
+  return { names: new Map(names), last: undefined };
 }
 
 /** The static scope at a point: a copy of the frames, as `withScope()` gives them to a raw input. */
@@ -63,37 +76,10 @@ function lookup(env: Env, name: string): Binding | undefined {
   return undefined;
 }
 
-function resolve(node: ReferenceNode, env: Env, diagnostics: Diagnostic[]): void {
+/** This function gives a reference the binding of its name. `names.ts` reports a name that no frame has. */
+function resolve(node: ReferenceNode, env: Env): void {
   if (node.synthetic) return;
   node.binding = lookup(env, node.name);
-  if (node.binding) return;
-  if (node.deferred) {
-    diagnostics.push({
-      severity: "info",
-      code: "unknown-name",
-      message: `No scope has the name "${node.name}" here. In the input of a deferred call, the $ref stays data for the runner.`,
-      pointer: node.pointer,
-    });
-    return;
-  }
-  const later = env?.some((frame) => frame.later.has(node.name)) ?? false;
-  const names = [...new Set((env ?? []).flatMap((frame) => [...frame.names.keys(), ...(frame.last ? ["$last"] : [])]))];
-  const known = names.length > 0 ? ` The names here: ${names.join(", ")}.` : " No name is in the scope here.";
-  diagnostics.push(
-    later
-      ? {
-          severity: "error",
-          code: "use-before-definition",
-          message: `The $ref "${node.text}" reads "${node.name}" before the step that makes it: a step reads only the names of the steps before it.`,
-          pointer: node.pointer,
-        }
-      : {
-          severity: "error",
-          code: "unknown-name",
-          message: `Unknown $ref name "${node.name}" in "${node.text}".${known}${node.name === "$last" ? " The first step of a chain has no $last." : ""}`,
-          pointer: node.pointer,
-        },
-  );
 }
 
 function visitItems(items: ItemsSpec, env: Env, diagnostics: Diagnostic[]): void {
@@ -107,7 +93,7 @@ function visit(node: IRNode, env: Env, diagnostics: Diagnostic[]): void {
     case "fail":
       return;
     case "reference":
-      resolve(node, env, diagnostics);
+      resolve(node, env);
       return;
     case "object":
       for (const entry of node.entries) visit(entry.value, env, diagnostics);
@@ -127,17 +113,14 @@ function visit(node: IRNode, env: Env, diagnostics: Diagnostic[]): void {
       else if (node.reason === "runs-refs" && node.key !== "procedure.define") scanRaw(node.input, env, diagnostics);
       return;
     case "chain": {
-      const names = node.steps.map((step) => step.result.name);
-      const frame: Frame = { names: new Map(), last: undefined, later: new Set() };
+      const frame: Frame = { names: new Map(), last: undefined };
       const inner: Env = [...(env ?? []), frame];
       if (node.initialInput) visit(node.initialInput, inner, diagnostics);
-      node.steps.forEach((step, index) => {
-        frame.later = new Set(names.slice(index).filter((name): name is string => name !== undefined));
+      for (const step of node.steps) {
         visit(step.node, inner, diagnostics);
         if (step.result.name !== undefined) frame.names.set(step.result.name, step.result);
         frame.last = step.result;
-      });
-      frame.later = new Set();
+      }
       return;
     }
     case "parallel":