@mark1russell7/coeval 0.20.0 → 0.21.0

package/src/stdlib.ts

@@ -18,7 +18,7 @@ import {
 import { Failure } from "./errors.ts";
 import { type Cap, type HostThing, type Thing, type Walker, THING, isHostThing, valueOfThing } from "./deref.ts";
 import type { World } from "./ladder.ts";
-import { type AttributeDeclaration, type CircularRule, type TreeContract, circularOf, equationType, lookupKind } from "./world.ts";
+import { type AttributeDeclaration, type CircularRule, type TreeContract, circularOf, collectOf, equationType, lookupKind } from "./world.ts";
 import { STD_DOMAINS } from "./types.ts";
 import type { SyntaxProfile } from "./syntax.ts";
 
@@ -67,6 +67,15 @@ export const STD_WORLD: World = {
       pure: true,
       summary: "A step of a path: it follows a key again and again, until it reaches a node of a type.",
     },
+    tree: {
+      kinds: {
+        named: {
+          verbs: { step: "walk.named", view: "view.card" },
+          pure: true,
+          summary: "A step of a path: it goes up to the nearest registry of names, and it gives the node with the name (TREE.NAMED).",
+        },
+      },
+    },
     panel: {
       verbs: { eval: "tree.node", view: "view.op" },
       parts: { shape: "record", fields: ["width", "height", "children"], of: "number" },
@@ -167,6 +176,7 @@ export const WORLD_SYNTAX: SyntaxProfile = /* @__PURE__ */ Object.freeze({
       { name: "panel", kind: "panel", args: "named", fields: ["width", "height", "children"] },
       { name: "box", kind: "box", args: "named", fields: ["width", "height", "children"] },
       { name: "nearest", kind: "nearest", args: "named", fields: ["type", "follow", "self"] },
+      { name: "tree.named", kind: "tree.named", args: "named", fields: ["name", "in"] },
       // An operator document with fewer terms than its operator takes, for example add(5) (K163, D65).
       { name: "add", kind: "add" },
       { name: "multiply", kind: "multiply" },
@@ -272,6 +282,8 @@ export interface AttributeTrace {
 /** The state of a node behind its brand. */
 interface NodeState extends LoopNode {
   readonly build: TreeBuild;
+  /** The binding name from the header of the document of the node, for the registry of names (TREE.NAMED). */
+  readonly name: string | undefined;
   /**
    * This function gives an attribute through its ladder (TREE.LADDER).
    *
@@ -853,6 +865,57 @@ function plainOf(value: unknown, path: Set<object>): Result {
   }
 }
 
+/**
+ * This function gives the collection of an attribute of a node (TREE.COLLECT, D122). It visits the node, then each node
+ * of the same tree in each list `children`, in the order of the lists. Each node is visited one time.
+ * The registry of names (TREE.NAMED) gives a record from each binding name to its node.
+ */
+function collected(root: HostThing, key: string, declared: unknown): Result {
+  const top = stateOf(root) as NodeState;
+  const rule = collectOf(declared);
+  if (!rule.ok) return fail("#VALUE!", `The attribute ${attributeText(key, top.type, top.place)} has a bad declaration collect. ${rule.reason}`);
+  const registry: Record<string, unknown> = {};
+  const owners = new Map<string, NodeState>();
+  let acc = rule.names ? ok(registry) : top.equation(rule.unit, NO_NAMES);
+  if (!acc.ok) return acc;
+  const seen = new Set<NodeState>();
+  const stack: unknown[] = [root];
+  while (stack.length > 0) {
+    const thing = stack.pop();
+    const at = stateOf(thing);
+    // An item that is not a node of this tree does not count, and a node counts one time.
+    if (at === undefined || at.build !== top.build || seen.has(at)) continue;
+    seen.add(at);
+    if (rule.names) {
+      const name = at.name;
+      const earlier = name === undefined ? undefined : owners.get(name);
+      if (earlier !== undefined) {
+        const both = `${earlier.type} at [${earlier.place.join(", ")}] and ${at.type} at [${at.place.join(", ")}]`;
+        return fail("#VALUE!", `Two nodes have the name ${name} in the registry ${attributeText(key, top.type, top.place)}: ${both}.`);
+      }
+      if (name !== undefined) {
+        owners.set(name, at);
+        putField(registry, name, thing);
+      }
+    } else {
+      const term = entryOf(at.tree?.contributes, key);
+      if (term !== undefined) {
+        const item = at.equation(term, NO_NAMES);
+        if (!item.ok) return item;
+        acc = top.equation(rule.combine, { acc: acc.value, item: item.value });
+        if (!acc.ok) return acc;
+      }
+    }
+    const children = at.read("children");
+    if (children === undefined) continue;
+    if (!children.ok) return children;
+    if (!Array.isArray(children.value)) return fail("#VALUE!", `The collection of ${key} needs a list in children of ${at.type} at [${at.place.join(", ")}].`);
+    const list = children.value as readonly unknown[];
+    for (let index = list.length - 1; index >= 0; index -= 1) stack.push(list[index]);
+  }
+  return acc;
+}
+
 /**
  * This function makes a node of the decorated tree. A step `parent` gives the self of the context of the node, and a
  * step `type` gives its type. Another step reads an attribute through its ladder (TREE.LADDER). The rungs are a part of
@@ -916,6 +979,7 @@ function treeThing(input: EvalInput, place: readonly Key[], build: TreeBuild, ou
       if (copied !== undefined) return { result: copied, by: "copy" };
     }
     if (declared?.fold !== undefined) return { result: fold(key, declared.fold), by: "default" };
+    if (declared?.collect !== undefined) return { result: collected(node, key, declared.collect), by: "default" };
     if (declared?.default !== undefined) return { result: state.equation(declared.default, NO_NAMES), by: "default" };
     return undefined;
   };
@@ -984,6 +1048,7 @@ function treeThing(input: EvalInput, place: readonly Key[], build: TreeBuild, ou
 
   const state: NodeState = {
     build,
+    name: input.doc.name,
     type,
     place,
     tree,
@@ -1170,8 +1235,29 @@ export function nearestWalker(options: NearestOptions = {}): Walker {
 
 const nearest: Walker = /* @__PURE__ */ nearestWalker();
 
+/**
+ * The walker of the step `tree.named` (TREE.NAMED, D122). It goes up from the thing before the step through the key
+ * `parent`, to the first thing that answers the registry. The field `in` names the registry, and the default is
+ * `names`. The walker gives the node with the field `name` in that registry.
+ */
+const named: Walker = ({ data, here, deref }) => {
+  const name = isRecord(data) ? field(data, "name") : undefined;
+  if (typeof name !== "string") return { ok: false, code: "#VALUE!", reason: "The step tree.named needs a text name." };
+  const registry = isRecord(data) && typeof field(data, "in") === "string" ? String(field(data, "in")) : "names";
+  let at: Thing | undefined = here;
+  for (let hops = 0; hops < 256 && at !== undefined && at !== null; hops += 1) {
+    const found = deref(at, registry);
+    if (found !== undefined) {
+      if (!isRecord(found) || !Object.hasOwn(found, name)) return { ok: false, reason: `The registry ${registry} has no node with the name ${name}.` };
+      return { ok: true, thing: field(found, name) as Thing };
+    }
+    at = deref(at, "parent");
+  }
+  return { ok: false, reason: `No registry ${registry} is on the way.` };
+};
+
 /** The walkers of the standard world, by name. */
-export const STD_WALKERS: Readonly<Record<string, Walker>> = { "walk.nearest": nearest };
+export const STD_WALKERS: Readonly<Record<string, Walker>> = { "walk.nearest": nearest, "walk.named": named };
 
 /** This function evaluates parts one after the other, and stops at the first error. */
 function* inOrder(parts: readonly RunPart[]): Generator<Promise<unknown>, { readonly values: readonly unknown[] } | { readonly error: Result }, unknown> {

package/src/steps.ts

@@ -0,0 +1,181 @@
+/**
+ * The steps of a language (STEPS.*). A step is a level of the power of a language. A low step accepts only programs
+ * that end for a known reason, for example loops with a fixed count. A high step accepts more programs. The language
+ * declares the step of each construct as data. `stepOf` gives the lowest step that a document needs, with the reason,
+ * and `checkStep` compares that step with the highest step that the host accepts. A document cannot raise its own
+ * step, because the declaration and the limit come from the language and the host. The ladder of `ask` (`ladder.ts`)
+ * is a different thing: it finds the evaluator of a verb.
+ */
+
+/** A key of a path from the root to a node: a field name or a position. */
+export type StepKey = string | number;
+
+/** The steps of a language, from the lowest to the highest, and the step that each construct needs. It is data. */
+export interface StepLadder<S extends string = string> {
+  /** The names of the steps, from the lowest to the highest. */
+  readonly steps: readonly S[];
+  /** The step that each construct needs. A construct without an entry needs the lowest step. */
+  readonly constructs: Readonly<Record<string, S>>;
+}
+
+/** The walk of the documents of a language. The language gives these two functions. */
+export interface StepWalk<N> {
+  /** This function gives the name of the construct of a node, or `undefined` for a node without a construct. */
+  readonly construct: (node: N) => string | undefined;
+  /** This function gives the child nodes of a node in document order, each with the key of its path. */
+  readonly children: (node: N) => Iterable<readonly [StepKey, N]>;
+}
+
+/** The reason for a step: the first node in document order whose construct needs that step. */
+export interface StepReason<N, S extends string = string> {
+  /** The name of the construct. */
+  readonly construct: string;
+  /** The step that the construct needs. */
+  readonly step: S;
+  /** The keys from the root to the node. The root has the empty path. */
+  readonly path: readonly StepKey[];
+  readonly node: N;
+}
+
+/** The lowest step that a document needs. */
+export interface StepNeed<N, S extends string = string> {
+  readonly step: S;
+  /** The reason. It is `undefined` when no construct needs more than the lowest step. */
+  readonly reason?: StepReason<N, S>;
+}
+
+/** The refusal of a document whose step is higher than the limit of the host. */
+export interface StepRefusal<N, S extends string = string> {
+  /** The step that the document needs. */
+  readonly needed: S;
+  /** The highest step that the host accepts. */
+  readonly maxStep: S;
+  /** The reason of the step. A need that a host makes without `stepOf` can have no reason. */
+  readonly reason?: StepReason<N, S>;
+  /** The text of the refusal. It names the needed step and the limit, and the construct and its path of the reason. */
+  readonly message: string;
+}
+
+/**
+ * This function makes a ladder of steps, and it checks the declaration (STEPS.LADDER). The list of steps must have one
+ * step or more, with no name two times. The step of each construct must be a step of the list.
+ *
+ * @param steps - The names of the steps, from the lowest to the highest.
+ * @param constructs - The step that each construct needs.
+ * @returns The ladder, frozen.
+ * @throws TypeError for a declaration that is not valid, because it is a defect of the language.
+ */
+export function stepLadder<const S extends string>(steps: readonly S[], constructs: Readonly<Record<string, NoInfer<S>>>): StepLadder<S> {
+  if (steps.length === 0) throw new TypeError("a ladder of steps needs one step or more");
+  const seen = new Set<string>();
+  for (const step of steps) {
+    if (typeof step !== "string") throw new TypeError(`the step ${String(step)} is not a name`);
+    if (seen.has(step)) throw new TypeError(`the step "${step}" is in the ladder two times`);
+    seen.add(step);
+  }
+  for (const [construct, step] of Object.entries(constructs)) {
+    if (!seen.has(step)) throw new TypeError(`the construct "${construct}" needs the step "${String(step)}", which is not a step of the ladder`);
+  }
+  return Object.freeze({ steps: Object.freeze([...steps]), constructs: Object.freeze({ ...constructs }) });
+}
+
+/**
+ * This function tells if a value is a step of a ladder. A host uses it to check its option for the highest step.
+ *
+ * @param ladder - The ladder.
+ * @param value - The value.
+ * @returns `true` when the value is the name of a step of the ladder.
+ */
+export function isStep<S extends string>(ladder: StepLadder<S>, value: unknown): value is S {
+  return typeof value === "string" && ladder.steps.includes(value as S);
+}
+
+/**
+ * This function gives the position of a step in its ladder. The lowest step has the position 0.
+ *
+ * @param ladder - The ladder.
+ * @param step - The step.
+ * @returns The position.
+ * @throws TypeError for a name that is not a step of the ladder.
+ */
+export function stepRank<S extends string>(ladder: StepLadder<S>, step: S): number {
+  const rank = ladder.steps.indexOf(step);
+  if (rank < 0) throw new TypeError(`"${String(step)}" is not a step of the ladder. The steps are ${ladder.steps.join(", ")}`);
+  return rank;
+}
+
+/** An item of the walk: a node, the key of its path and the item of its parent. Thus a path costs nothing until a reason needs it. */
+interface Visit<N> {
+  readonly node: N;
+  readonly key: StepKey | undefined;
+  readonly parent: Visit<N> | undefined;
+}
+
+function pathOf<N>(visit: Visit<N>): StepKey[] {
+  const path: StepKey[] = [];
+  for (let v: Visit<N> | undefined = visit; v?.key !== undefined; v = v.parent) path.push(v.key);
+  return path.reverse();
+}
+
+/**
+ * This function gives the lowest step that a document needs, with the reason (STEPS.LOWEST, STEPS.REASON). The step is
+ * the highest step of the constructs of its nodes. The reason is the first node in document order with that step. The
+ * walk uses its own stack, thus a deep document does not overflow (STEPS.LINEAR). It visits a shared node one time,
+ * and it stops at the first node with the highest step of the ladder.
+ *
+ * @param ladder - The ladder of the language.
+ * @param walk - The construct and the child nodes of a node.
+ * @param root - The root node of the document.
+ * @returns The step, and the reason when the step is not the lowest step.
+ */
+export function stepOf<N, S extends string>(ladder: StepLadder<S>, walk: StepWalk<N>, root: N): StepNeed<N, S> {
+  const top = ladder.steps.length - 1;
+  let best = 0;
+  let reason: StepReason<N, S> | undefined;
+  const seen = new Set<unknown>();
+  const todo: Visit<N>[] = [{ node: root, key: undefined, parent: undefined }];
+  for (let visit = todo.pop(); visit !== undefined; visit = todo.pop()) {
+    const { node } = visit;
+    if (typeof node === "object" && node !== null) {
+      if (seen.has(node)) continue;
+      seen.add(node);
+    }
+    const construct = walk.construct(node);
+    const step = construct === undefined || !Object.hasOwn(ladder.constructs, construct) ? undefined : ladder.constructs[construct];
+    const rank = step === undefined ? 0 : ladder.steps.indexOf(step);
+    if (rank > best) {
+      best = rank;
+      reason = { construct: construct as string, step: step as S, path: pathOf(visit), node };
+      if (best === top) break;
+    }
+    const kids = [...walk.children(node)];
+    for (let i = kids.length - 1; i >= 0; i--) {
+      const [key, child] = kids[i] as readonly [StepKey, N];
+      todo.push({ node: child, key, parent: visit });
+    }
+  }
+  const step = ladder.steps[best] as S;
+  return reason === undefined ? { step } : { step, reason };
+}
+
+/**
+ * This function compares the step of a document with the highest step that the host accepts (STEPS.MAX). The limit
+ * changes only which documents the host accepts. The language evaluates an accepted document as before, thus a limit
+ * does not change a value.
+ *
+ * @param ladder - The ladder of the language.
+ * @param need - The step of the document, from `stepOf`.
+ * @param maxStep - The highest step that the host accepts.
+ * @returns `undefined` when the host accepts the document, or the refusal that names the needed step.
+ * @throws TypeError when `maxStep` or the step of `need` is not a step of the ladder.
+ */
+export function checkStep<N, S extends string>(ladder: StepLadder<S>, need: StepNeed<N, S>, maxStep: S): StepRefusal<N, S> | undefined {
+  const limit = stepRank(ladder, maxStep);
+  const needed = stepRank(ladder, need.step);
+  if (needed <= limit) return undefined;
+  const head = `the document needs the step ${need.step}, and the host accepts the steps up to ${maxStep}`;
+  const reason = need.reason;
+  if (reason === undefined) return { needed: need.step, maxStep, message: head };
+  const where = reason.path.length === 0 ? "at the root" : `at the path ${JSON.stringify(reason.path)}`;
+  return { needed: need.step, maxStep, reason, message: `${head}. The construct "${reason.construct}" ${where} needs the step ${reason.step}` };
+}

package/src/types.ts

@@ -1144,8 +1144,10 @@ function valueStep(value: unknown, key: Key): { readonly found: unknown } | { re
  *
  * - A record gives the type of its field. A closed record without the field has no such step. An open record gives
  *   `unknown`.
- * - A list gives the type of its items for an index, and `number` for `length`.
- * - A base type reads the steps of its domain, then of each parent (`Domain.steps`).
+ * - A list gives the type of its items for an index, and `number` for `length`. Another key has no such step.
+ * - A base type reads the steps of its domain, then of each parent (`Domain.steps`). A base type of the kernel
+ *   without such a step has no step, because its values are not objects (TYPE.NO-STEP, D120).
+ * - A function type has no step, because a step into a function reaches nothing.
  * - A union joins the steps of its types. `one` gives the values that the step reaches.
  * - Each other step gives `unknown`, and `never` gives `never`.
  *
@@ -1171,10 +1173,13 @@ export function stepType(
         const found = steps[name] as ValueType;
         return { type: examine === undefined ? found : examine(found, `type of the step ${name} of the domain ${each}`) };
       }
-      return { type: "unknown" };
+      // A value of a base type of the kernel is not an object, thus a step into it reaches nothing (TYPE.NO-STEP).
+      return Object.hasOwn(STD_DOMAINS, form.name) ? NO_STEP : { type: "unknown" };
+    case "fn":
+      return NO_STEP;
     case "list":
       if (key === "length") return { type: "number" };
-      return { type: indexOf(key) >= 0 ? form.item : "unknown" };
+      return indexOf(key) >= 0 ? { type: form.item } : NO_STEP;
     case "record":
       if (Object.hasOwn(form.fields, name)) return { type: form.fields[name] as ValueType };
       return form.closed ? { missing: Object.keys(form.fields) } : { type: "unknown" };
@@ -1204,6 +1209,9 @@ export function stepType(
   }
 }
 
+/** The answer of `stepType` for a type whose members have no step with the key, and no fields to name. */
+const NO_STEP: StepType = { missing: [] };
+
 /** A term that `typeIssues` reads later: the term, its keys from the root and its depth. */
 interface Pending {
   readonly type: unknown;

package/src/world.ts

@@ -116,12 +116,20 @@ export interface LazyRule {
  * - `lazy`: the parts that an evaluation can skip and still give a value.
  * - `reads`: the roots that the code of the kind resolves as a whole, with the path of one root. The static facts
  *   give a read of each root at each document of the kind (D44). The tree node reads `self` this way.
+ * - `effects`: the effects that the code of `eval` can cause, in the form of the field `effects` of a kind (D27). In
+ *   the answer of the hook `facts`, it gives the effects of the code of a name. The contract of a kind does not
+ *   describe an own entry for another evaluator, thus only the hook can give its effects (CAP.OWN-EFFECTS, D118).
+ * - `drives`: the parts that the code of a runner evaluates itself, without a wait, in the form of the lazy rules. A
+ *   step under such a part cannot wait for the host. The check of a run then refuses a part that can wait there
+ *   (RUN.DRIVES, D119). Without `drives`, the check assumes that the runner passes each wait of its parts through.
  */
 export interface KindFacts {
   readonly pure?: boolean;
   readonly volatile?: boolean;
   readonly lazy?: readonly LazyRule[];
   readonly reads?: readonly Root[];
+  readonly effects?: "type" | readonly string[];
+  readonly drives?: readonly LazyRule[];
 }
 
 /**
@@ -136,14 +144,38 @@ export interface KindFacts {
  * - `default`: the term that gives the value when no rung before it answers and the declaration has no fold.
  * - `circular`: a cycle of this attribute gives its fixed point, not `#CYCLE!` (TREE.CIRCULAR, D113). Only a cycle
  *   whose attributes each declare `circular` gives a fixed point.
+ * - `collect`: the value of a node without an answer of the first four rungs and without a fold. The node combines
+ *   the contributions of each node of its subtree (TREE.COLLECT, D122).
  */
 export interface AttributeDeclaration {
   readonly copy?: boolean;
   readonly fold?: { readonly unit: Json; readonly combine: Json };
   readonly default?: Json;
   readonly circular?: CircularDeclaration;
+  readonly collect?: CollectDeclaration;
 }
 
+/**
+ * The declaration `collect` of an attribute (TREE.COLLECT, D122). The node of the attribute visits each node of its
+ * subtree. It visits the node itself first. Then it visits the nodes in its list `children`, in the order of the list.
+ *
+ * - `{ unit, combine }`: the collection starts with the term `unit`. The term `combine` then adds the contribution
+ *   of each node, with the names `acc` and `item`. A node contributes when its kind has an equation for the
+ *   attribute in `tree.contributes`.
+ * - `"names"`: the registry of binding names. Its value is a record from the header name of each node to its node
+ *   (TREE.NAMED). Two nodes with one name give `#VALUE!` at the read of the registry.
+ */
+export type CollectDeclaration = { readonly unit: Json; readonly combine: Json } | "names";
+
+/** A declaration `collect` that the kit can use, or the reason of a bad declaration (D122). */
+export type CollectRule =
+  | { readonly ok: true; readonly names: true }
+  | { readonly ok: true; readonly names: false; readonly unit: Json; readonly combine: Json }
+  | { readonly ok: false; readonly reason: string };
+
+/** The rule of the registry of binding names. */
+const NAMES_RULE: CollectRule = /* @__PURE__ */ Object.freeze({ ok: true, names: true });
+
 /**
  * The declaration `circular` of an attribute (TREE.CIRCULAR, D113). The attribute that a cycle reaches first leads it.
  * The leader evaluates again until no value of the cycle changes.
@@ -200,6 +232,21 @@ export function circularOf(declared: unknown): CircularRule {
   return { ok: true, start: start as Json, limit };
 }
 
+/**
+ * This function reads the declaration `collect` of an attribute (D122). The tree kit, the reference, `check` and the
+ * graph of attribute instances read it with this one function.
+ *
+ * @param declared - The value of the field `collect`.
+ * @returns The rule of the collection, or the reason when the declaration has no correct form.
+ */
+export function collectOf(declared: unknown): CollectRule {
+  if (declared === "names") return NAMES_RULE;
+  if (!isRecord(declared) || !Object.hasOwn(declared, "unit") || !Object.hasOwn(declared, "combine")) {
+    return { ok: false, reason: 'The declaration collect needs the text "names" or a record with the fields unit and combine.' };
+  }
+  return { ok: true, names: false, unit: field(declared, "unit") as Json, combine: field(declared, "combine") as Json };
+}
+
 /**
  * The tree contract of a kind (D42): the equations of the attributes of its nodes. Each equation is a document that
  * evaluates with the node as `self` and without capabilities. A bare equation gets the type `of` of the parts of the
@@ -209,11 +256,14 @@ export function circularOf(declared: unknown): CircularRule {
  * - `down`: the attributes of each child of the node. `self` is this node. An equation sees the names `child`,
  *   `index` and `prev` (TREE.DOWN).
  * - `attributes`: the declarations of the attributes of the node, for the rungs `copy` and `default`.
+ * - `contributes`: the contribution of the node to each collection of an attribute (TREE.COLLECT, D122). An
+ *   equation sees no names.
  */
 export interface TreeContract {
   readonly equations?: Readonly<Record<string, Json>>;
   readonly down?: Readonly<Record<string, Json>>;
   readonly attributes?: Readonly<Record<string, AttributeDeclaration>>;
+  readonly contributes?: Readonly<Record<string, Json>>;
 }
 
 /**