@mark1russell7/coeval 0.18.0 → 0.19.0

package/src/stdlib.ts

@@ -236,7 +236,7 @@ export const STD_EVALUATORS: Readonly<Record<string, Evaluator>> = {
     const found = resolve(data as readonly Json[]);
     return found.ok ? ok(valueOfThing(found.thing)) : fail(found.code, found.reason);
   },
-  "tree.node": (input) => treeNode(input),
+  "tree.node": (input) => treeNode(input, undefined),
 };
 
 /*
@@ -316,6 +316,57 @@ interface NodeState {
   json(path: Set<object>): Result;
 }
 
+/** The answer of the ladder for one attribute of one node (TREE.CELL, D108). */
+export interface AttributeAnswer {
+  /** The result of the attribute. It is `undefined` when no rung answered. */
+  readonly result: Result | undefined;
+  /** The rung that answered. It is `undefined` when no rung answered. */
+  readonly by: AttributeRung | undefined;
+}
+
+/**
+ * This function gives the memo cell of one attribute of one node, for a host that keeps its cells between evaluations
+ * (TREE.CELL, D108). The kit uses it at each demand of an attribute in an evaluation.
+ *
+ * The array `place` is one object for each document of a plan, and it stays the same across the evaluations of that
+ * plan. A new plan gives new arrays. Thus a host keeps its cells by the identity of `place` and by `attribute`.
+ * A host that keeps its cells by the keys of `place` can give a stale answer after a change of the document.
+ *
+ * The function gives the answer of `compute`, or a kept answer. A host with signals gives a computed signal: a change
+ * of its store then makes only the attributes that read the store compute again. Each demand gives a new `compute`, and
+ * a cell that computes again uses the last one.
+ *
+ * The kit marks an attribute in evaluation before it uses the cell. Thus a cycle gives `#CYCLE!` before it reaches the
+ * cell again. An exception of the function that `compute` did not throw gives `#CYCLE!` with the chain of the demands.
+ *
+ * @param place - The keys from the root document to the document of the node.
+ * @param attribute - The name of the attribute.
+ * @param compute - The function that visits the rungs of the ladder.
+ * @returns The answer.
+ */
+export type AttributeCell = (place: readonly Key[], attribute: string, compute: () => AttributeAnswer) => AttributeAnswer;
+
+/** The options of the tree kit (D108). */
+export interface TreeOptions {
+  /**
+   * The memo cells of the host (TREE.CELL). The default is a plain memo for each node and attribute, for one
+   * evaluation (TREE.MEMO).
+   */
+  readonly cell?: AttributeCell;
+}
+
+/**
+ * This function gives the code of the kind of a node of the decorated tree, with the options of the host. A host puts
+ * the code at the name `tree.node` of its machine. Without a cell, the code is the standard code.
+ *
+ * @param options - The options, for example the memo cells of the host.
+ * @returns The code.
+ */
+export function treeNodeEvaluator(options: TreeOptions = {}): Evaluator {
+  const host = options.cell;
+  return host === undefined ? (STD_EVALUATORS["tree.node"] as Evaluator) : (input: EvalInput) => treeNode(input, host);
+}
+
 /**
  * The memo cell of one attribute: in evaluation, or done with its result and the rung that answered. A done cell
  * without a result tells that no rung answered.
@@ -373,6 +424,31 @@ function contractOf(machine: Machine | undefined, typePath: readonly Key[]): Nod
 
 const BUSY: Cell = /* @__PURE__ */ Object.freeze({ busy: true });
 
+/** The answer of the ladder when no rung answers. */
+const NO_ANSWER: AttributeAnswer = /* @__PURE__ */ Object.freeze({ result: undefined, by: undefined });
+
+/**
+ * The marks of the attributes in evaluation, for each place of a plan, with the cells of a host (TREE.CELL). Nodes of
+ * two evaluations share their place and their kept cells, thus they share their marks.
+ */
+const marksByPlace = /* @__PURE__ */ new WeakMap<readonly Key[], Map<string, Cell>>();
+
+/** The trees of the cells of a host, for each place of a root in a plan. Nodes of two evaluations stay in one tree. */
+const buildsByPlace = /* @__PURE__ */ new WeakMap<readonly Key[], TreeBuild>();
+
+/** This function gives the value of a weak map, or puts a new value in it. */
+function keptAt<T>(map: WeakMap<readonly Key[], T>, place: readonly Key[], make: () => T): T {
+  let value = map.get(place);
+  if (value === undefined) {
+    value = make();
+    map.set(place, value);
+  }
+  return value;
+}
+
+/** A value that no exception has. */
+const NOT_THROWN: unique symbol = /* @__PURE__ */ Symbol("coeval.tree.not-thrown") as never;
+
 /** One attribute in evaluation. The text names it in the reason of a cycle. */
 interface Demand {
   readonly cells: Map<string, Cell>;
@@ -451,8 +527,10 @@ function plainOf(value: unknown, path: Set<object>): Result {
  * the node, an equation of its kind and an equation `down` of the kind of its parent. A copy from the parent, then a
  * fold or a default, come last. A failed attribute throws `Failure` with its own error, thus a reference to it gives that error.
  * The argument `outer` is the self of the context, that `treeNode` resolved. The node reads no root of the context directly (C4).
+ *
+ * The argument `host` gives the memo cells of the host (TREE.CELL), or `undefined` for the plain memo of the node.
  */
-function treeThing(input: EvalInput, build: TreeBuild, outer: Thing | undefined): HostThing {
+function treeThing(input: EvalInput, build: TreeBuild, outer: Thing | undefined, host: AttributeCell | undefined): HostThing {
   const { parts, context, kind: type, place, machine } = input;
   // The equations evaluate in the evaluation that made the node, thus their reads go in its list (READS.EQUATION).
   const runtime = (input as InputWithRuntime)[RUNTIME];
@@ -461,6 +539,8 @@ function treeThing(input: EvalInput, build: TreeBuild, outer: Thing | undefined)
   // Only a node of the same tree is a parent for the rungs `parent` and `copy`.
   const up = above !== undefined && above.build === build ? above : undefined;
   const cells = new Map<string, Cell>();
+  // With the cells of a host, the marks of a place serve each node of the place (TREE.CELL).
+  const marks = host === undefined ? cells : keptAt(marksByPlace, place, () => new Map<string, Cell>());
   /** The positions of the items of the list `children`, for the names of the children. */
   let positions: { readonly list: readonly unknown[]; readonly at: Map<unknown, number> } | undefined;
 
@@ -505,7 +585,45 @@ function treeThing(input: EvalInput, build: TreeBuild, outer: Thing | undefined)
     return undefined;
   };
 
+  /**
+   * This function gives an attribute through the cell of the host (TREE.CELL). The cell is the memo. The node keeps
+   * the last answer only for `has` and `trace`.
+   */
+  const through =
+    host === undefined
+      ? undefined
+      : (key: string): Result | undefined => {
+          const text = attributeText(key, type, place);
+          if (marks.has(key)) return cycleAt(marks, key, text);
+          if (tree === undefined && up?.tree === undefined && !parts.some((item) => item.key === key)) return undefined;
+          marks.set(key, BUSY);
+          demands.push({ cells: marks, key, text });
+          let thrown: unknown = NOT_THROWN;
+          let answer: AttributeAnswer;
+          try {
+            answer = host(place, key, () => {
+              try {
+                return climb(key) ?? NO_ANSWER;
+              } catch (error) {
+                thrown = error;
+                throw error;
+              }
+            });
+          } catch (error) {
+            // An exception of the kit or of the stack goes on, as without a host. Another exception is a cycle of the host.
+            if (error === thrown) throw error;
+            const chain = demands.map((demand) => demand.text).join(" -> ");
+            answer = { result: fail("#CYCLE!", `The cells of the host found a cycle in the demands: ${chain}.`, { cause: error }), by: undefined };
+          } finally {
+            demands.pop();
+            marks.delete(key);
+          }
+          cells.set(key, { busy: false, result: answer.result, by: answer.by });
+          return answer.result;
+        };
+
   const read = (key: string): Result | undefined => {
+    if (through !== undefined) return through(key);
     const cell = cells.get(key);
     if (cell !== undefined) return cell.busy ? cycleAt(cells, key, attributeText(key, type, place)) : cell.result;
     // A node without a contract has only its parts, as before D42. Thus a missing part needs no cell.
@@ -635,14 +753,17 @@ const NO_HOPS = /* @__PURE__ */ Object.freeze({ hops: false });
  * This function evaluates a node of the decorated tree. Inside an attribute of an open tree, the node gives its host
  * thing, and no attribute evaluates. Else the node is the root of a new tree, and it gives the JSON of the tree. The
  * node reads `self` through `resolve` (C4, D44). A machine that closes the root `self` thus gives no nested trees.
+ * The argument `host` gives the memo cells of the host (TREE.CELL), or `undefined` for the plain memo of each node.
  */
-function treeNode(input: EvalInput): Result {
+function treeNode(input: EvalInput, host: AttributeCell | undefined): Result {
   const found = input.resolve(SELF_PATH, NO_HOPS);
   const outer = found.ok ? found.thing : undefined;
   const above = stateOf(outer);
-  if (above !== undefined && above.build.open) return ok(treeThing(input, above.build, outer));
-  const build: TreeBuild = { open: true };
-  const root = treeThing(input, build, outer);
+  if (above !== undefined && above.build.open) return ok(treeThing(input, above.build, outer, host));
+  // With the cells of a host, a kept value can hold a node of an earlier evaluation. Thus that node stays in the tree.
+  const build: TreeBuild = host === undefined ? { open: true } : keptAt(buildsByPlace, input.place, () => ({ open: true }));
+  build.open = true;
+  const root = treeThing(input, build, outer, host);
   try {
     return (stateOf(root) as NodeState).json(new Set());
   } finally {

package/src/types.ts

@@ -205,8 +205,12 @@ function formOf(type: unknown, domains: Readonly<Record<string, Domain>> | undef
   return { t: "record", fields: fields as Readonly<Record<string, ValueType>>, optional: new Set(names), closed };
 }
 
-/** This function gives each base type that holds the members of a base type: the type itself and each parent, through each level. */
-function lineOf(name: string, domains: Readonly<Record<string, Domain>> | undefined): ReadonlySet<string> {
+/**
+ * This function gives each base type that holds the members of a base type: the type itself and each parent, through
+ * each level. A cycle of parents ends at a name that the line has, and a parent that is not a domain ends its branch.
+ * The function is internal: `encodeValue` uses it too (D109).
+ */
+export function lineOf(name: string, domains: Readonly<Record<string, Domain>> | undefined): ReadonlySet<string> {
   const seen = new Set<string>([name]);
   const queue = [name];
   while (queue.length > 0) {

package/src/typing.ts

@@ -1,7 +1,8 @@
 import { type Envelope, type Key, isRecord, typeName } from "./doc.ts";
 import type { Machine } from "./evaluate.ts";
-import type { DocVisit, Issue } from "./static.ts";
-import { type ValueType, fits, isUnknown, typeIssues, typeText } from "./types.ts";
+import type { DocVisit, Issue, WorldIssue } from "./static.ts";
+import { type ValueType, domainOf, fits, isUnknown, typeIssues, typeText } from "./types.ts";
+import { type Kind, type Shape, eachKind, kindAt } from "./world.ts";
 
 /*
  * The check of value types (R5 P3, D25). The pass reads the documents that the walk of `check` visited. It goes down
@@ -133,8 +134,36 @@ export interface TypeRule {
    * @returns The type of the document.
    */
   readonly synth: (input: TypeInput, report: (problem: TypeProblem) => void) => ValueType;
+  /**
+   * This function lists the declarations that the rule reads, for example the signatures of a formula profile
+   * (TYPE.WORLD, D110). `checkWorld` with the option `types` examines each one before a document exists. A rule
+   * without this function declares nothing.
+   *
+   * @returns The value types that the rule reads, and the problems that the rule finds in its declarations.
+   */
+  readonly declared?: () => readonly Declared[];
 }
 
+/**
+ * One declaration of a type rule (TYPE.WORLD, D110). It is a value type that the rule reads, with what it is. Or it is
+ * a problem that the rule finds in a declaration, for example an overload that the check does not select at any time.
+ */
+export type Declared =
+  | {
+      /** The keys of the declaration in the declarations of the rule, for example `["sigs", "add", "to"]`. */
+      readonly at: readonly Key[];
+      /** The value type. `checkWorld` examines it with `typeIssues`. */
+      readonly type: unknown;
+      /** What the type is, for the reason of an issue, for example "result of a signature of ops.add". */
+      readonly what: string;
+    }
+  | {
+      /** The keys of the declaration in the declarations of the rule. */
+      readonly at: readonly Key[];
+      /** The reason of the problem. */
+      readonly problem: string;
+    };
+
 /** The type of one document of a check of types. */
 export interface Typed {
   /** The keys from the root document to the document. */
@@ -206,7 +235,7 @@ function pathKey(path: readonly Key[]): string {
 }
 
 /** This function gives the type rule of an evaluator name. A runner hides the evaluator of its name, and a runner has no rule yet (K29). */
-function ruleOf(machine: Machine, name: string | undefined): TypeRule | undefined {
+export function ruleOf(machine: Machine, name: string | undefined): TypeRule | undefined {
   if (name === undefined || (machine.runners !== undefined && Object.hasOwn(machine.runners, name))) return undefined;
   const evaluator = Object.hasOwn(machine.evaluators, name) ? machine.evaluators[name] : undefined;
   const rule = typeof evaluator === "object" && evaluator !== null ? (evaluator as { readonly type?: unknown }).type : undefined;
@@ -388,3 +417,114 @@ export function typePass(machine: Machine, nodes: readonly TypeNode[], verb: str
   const issues = found.sort((a, b) => a.index - b.index).map((item) => item.issue);
   return { type: types[0] ?? "unknown", issues, places };
 }
+
+/** The owner of a value type of a machine: a kind, a domain or a type rule. */
+type Owner = Pick<WorldIssue, "kind" | "fallback" | "domain" | "evaluator">;
+
+/**
+ * This function examines each value type of a machine before a document exists (TYPE.WORLD, D110). It reads the
+ * `result` and each `expect` of each kind, the parents and the steps of each domain, and the declarations of each type
+ * rule. Each problem of `typeIssues` gives one issue with the keys of the bad term.
+ *
+ * A term shape with `kinds` and `expect` also gets an issue for each kind of its list whose `result` does not fit
+ * `expect`. A check of types gives `#TYPE!` at each document of that kind there.
+ *
+ * @param machine - The machine.
+ * @returns The issues: the kinds in the order of the world, then the domains, then the type rules.
+ */
+export function machineTypeIssues(machine: Machine): readonly WorldIssue[] {
+  const domains = machine.domains;
+  const world = machine.world;
+  const out: WorldIssue[] = [];
+  const add = (owner: Owner, at: readonly Key[], reason: string): void => {
+    out.push({ code: "#TYPE!", ...owner, verb: "eval", at, reason });
+  };
+  /** This function examines one value type. It gives `true` when the type has no problem. */
+  const examine = (owner: Owner, at: readonly Key[], type: unknown, what: string): boolean => {
+    const problems = typeIssues(type, domains);
+    for (const problem of problems) add(owner, [...at, ...problem.at], `The ${what} is not a correct value type. ${problem.reason}`);
+    return problems.length === 0;
+  };
+  /**
+   * This function finds each kind of the list `kinds` of a term whose result does not fit the `expect` of the term.
+   * Only a kind at the path itself counts. A path through an alias or to a fallback kind gives no issue.
+   */
+  const results = (owner: Owner, kinds: readonly (readonly Key[])[], at: readonly Key[], expect: ValueType): void => {
+    if (isUnknown(expect, domains)) return;
+    kinds.forEach((path, index) => {
+      const found: Kind | undefined = Array.isArray(path) ? kindAt(world, path) : undefined;
+      const result = found?.result;
+      if (result === undefined || typeIssues(result, domains).length > 0 || fits(result, expect, domains)) return;
+      const text = path.join(".");
+      add(owner, [...at, "kinds", index], `The kind ${text} has the result ${typeText(result)}, and the part needs the type ${typeText(expect)}. Each document of ${text} here gets #TYPE!.`);
+    });
+  };
+
+  eachKind(world, (kind, path, fallback) => {
+    const owner: Owner = fallback ? { kind: path, fallback: true } : { kind: path };
+    const name = fallback ? (path.length === 0 ? "fallback kind of the world" : `fallback kind of ${path.join(".")}`) : `kind ${path.join(".")}`;
+    if (kind.result !== undefined) examine(owner, ["result"], kind.result, `result of the ${name}`);
+    // The set holds the shapes on the way, thus a shape that holds itself does not loop.
+    const way = new Set<Shape>();
+    const shape = (spec: Shape | undefined, at: readonly Key[]): void => {
+      if (typeof spec !== "object" || spec === null || way.has(spec)) return;
+      way.add(spec);
+      const expect = (spec as { readonly expect?: unknown }).expect;
+      const where = [...at, "expect"];
+      if (expect !== undefined && examine(owner, where, expect, `expected type at ${where.join(".")} of the ${name}`) && spec.shape === "term" && Array.isArray(spec.kinds)) {
+        results(owner, spec.kinds, at, expect as ValueType);
+      }
+      if (spec.shape === "list" || spec.shape === "map") shape(spec.item, [...at, "item"]);
+      if (spec.shape === "record") {
+        const fields: unknown = spec.fields;
+        if (typeof fields === "object" && fields !== null && !Array.isArray(fields)) {
+          for (const key of Object.keys(fields)) shape((fields as Readonly<Record<string, Shape>>)[key], [...at, "fields", key]);
+        }
+        shape(spec.rest, [...at, "rest"]);
+      }
+      way.delete(spec);
+    };
+    shape(kind.parts, ["parts"]);
+  });
+
+  const table = domains ?? {};
+  for (const name of Object.keys(table)) {
+    // A table entry with the name of the top or the bottom has no effect (TYPE.OPEN).
+    if (name === "unknown" || name === "never") continue;
+    const owner: Owner = { kind: [], domain: name };
+    const domain = domainOf(name, domains);
+    if (domain === undefined) {
+      add(owner, ["is"], `The domain ${name} has no test is. Each use of the name ${name} reads as unknown.`);
+      continue;
+    }
+    const under: unknown = domain.under;
+    if (Array.isArray(under)) {
+      under.forEach((parent: unknown, index) => {
+        if (parent === "unknown" || parent === "never") return;
+        if (typeof parent !== "string" || domainOf(parent, domains) === undefined) add(owner, ["under", index], `The parent ${String(parent)} of the domain ${name} is not a domain of the machine.`);
+      });
+    }
+    const steps: unknown = domain.steps;
+    if (typeof steps === "object" && steps !== null) {
+      for (const key of Object.keys(steps)) examine(owner, ["steps", key], (steps as Readonly<Record<string, unknown>>)[key], `type of the step ${key} of the domain ${name}`);
+    }
+  }
+
+  for (const name of Object.keys(machine.evaluators)) {
+    const declared = ruleOf(machine, name)?.declared;
+    if (typeof declared !== "function") continue;
+    const owner: Owner = { kind: [], evaluator: name };
+    let list: readonly Declared[];
+    try {
+      list = declared();
+    } catch (error) {
+      add(owner, [], `The type rule of ${name} fails: ${message(error)}`);
+      continue;
+    }
+    for (const item of list) {
+      if ("problem" in item) add(owner, item.at, item.problem);
+      else examine(owner, item.at, item.type, item.what);
+    }
+  }
+  return out;
+}

package/src/world.ts

@@ -323,6 +323,55 @@ export function isNamespace(entry: WorldEntry | undefined): entry is Namespace {
   return entry !== undefined && !isKind(entry) && !isAlias(entry) && Object.hasOwn(entry, "kinds");
 }
 
+/**
+ * This function visits each kind of a world. These are the kinds of each namespace, at each depth, and the fallback
+ * kind of each namespace and of the world. It does not follow an alias, because the kind of an alias has its own place. A
+ * fallback kind has the keys of its namespace. It comes after the entries of that namespace. `checkWorld` reads the
+ * kinds with this one function.
+ *
+ * @param world - The world.
+ * @param visit - The function that gets each kind, its keys from the root of the world, and `true` for a fallback kind.
+ */
+export function eachKind(world: World, visit: (kind: Kind, path: readonly Key[], fallback: boolean) => void): void {
+  // The set holds the namespaces on the way, thus a namespace that holds itself does not loop.
+  const way = new Set<Namespace>();
+  const entries = (kinds: Readonly<Record<string, WorldEntry>>, path: readonly Key[]): void => {
+    for (const key of Object.keys(kinds)) {
+      const entry = kinds[key];
+      const here = [...path, key];
+      if (isKind(entry)) visit(entry, here, false);
+      else if (isNamespace(entry) && !way.has(entry)) {
+        way.add(entry);
+        entries(entry.kinds, here);
+        if (entry.fallback !== undefined) visit(entry.fallback, here, true);
+        way.delete(entry);
+      }
+    }
+  };
+  entries(world.kinds, []);
+  if (world.fallback !== undefined) visit(world.fallback, [], true);
+}
+
+/**
+ * This function gives the kind at a path of a world, without an alias and without a fallback kind. A namespace on the
+ * way gives its entries.
+ *
+ * @param world - The world.
+ * @param path - The keys from the root of the world.
+ * @returns The kind, or `undefined` when no kind is at the path.
+ */
+export function kindAt(world: World, path: readonly Key[]): Kind | undefined {
+  let entries = world.kinds;
+  let entry: WorldEntry | undefined;
+  for (let index = 0; index < path.length; index += 1) {
+    entry = entryAt(entries, path[index] as Key);
+    if (index === path.length - 1) break;
+    if (!isNamespace(entry)) return undefined;
+    entries = entry.kinds;
+  }
+  return isKind(entry) ? entry : undefined;
+}
+
 function entryAt(entries: Readonly<Record<string, WorldEntry>>, key: Key): WorldEntry | undefined {
   const name = String(key);
   return Object.hasOwn(entries, name) ? entries[name] : undefined;