@mark1russell7/coeval 0.7.1 → 0.8.0

package/src/reference.ts

@@ -1,9 +1,9 @@
 import { type Envelope, type Json, type Key, isEnvelope, isRecord, typeName } from "./doc.ts";
 import { ask } from "./ladder.ts";
-import type { CapsRule, Kind } from "./world.ts";
+import { type AttributeDeclaration, type CapsRule, type Kind, type TreeContract, equationType, lookupKind } from "./world.ts";
 import { type PartSlot, type Split, partsOf, pathMatches } from "./parts.ts";
 import { type Cap, type Context, type HostThing, type Resolution, type ResolveOptions, type Thing, THING, isHostThing, resolve, valueOfThing, worldThing } from "./deref.ts";
-import { STD_EVALUATORS } from "./stdlib.ts";
+import { type AttributeRung, STD_EVALUATORS } from "./stdlib.ts";
 import { type EvalError, type Failed, type Result, Failure, describe, fail, ok, placed, thrown } from "./errors.ts";
 import {
   type AllOptions,
@@ -17,7 +17,6 @@ import {
   type RunInput,
   type RunPart,
   type Steps,
-  intersectCaps,
   makeContext,
   permits,
   placeText,
@@ -150,13 +149,23 @@ function examine(env: Env, at: At): Seen | Failed {
   return { doc, kindText, typePath: read.typePath ?? [], kind, name, chosen, split };
 }
 
+/**
+ * This function gives the effects that two lists of capabilities both permit (CAP.ONLY). The reference reads the rule
+ * from SPEC directly, and not from the intersection of the plan. Thus `agree` finds a bug in either one (D15).
+ */
+function bothPermit(a: readonly Cap[], b: readonly Cap[]): readonly Cap[] {
+  const out: Cap[] = [];
+  for (const cap of [...a, ...b]) if (permits(a, cap) && permits(b, cap) && !permits(out, cap)) out.push(cap);
+  return out;
+}
+
 /** This function gives the capabilities that the rules of a kind give one part (D14, CAP.CONTRACT, CAP.ONLY). */
 function capsOfPart(rules: readonly CapsRule[] | undefined, path: readonly Key[], caps: readonly Cap[]): readonly Cap[] {
   let out = caps;
   for (const rule of rules ?? []) {
     if (rule.in !== undefined && !rule.in.some((pattern) => pathMatches(path, pattern))) continue;
     if (rule.rule === "mask") return [];
-    if (rule.rule === "only") out = intersectCaps(out, rule.caps);
+    if (rule.rule === "only") out = bothPermit(out, rule.caps);
   }
   return out;
 }
@@ -420,13 +429,20 @@ export function reference(machine: Machine, doc: unknown, context: Context = mak
     scope: { prefix: "", counts: new Map(), alls: 0 },
   };
   const ctx = context.world === null ? { ...context, world: worldThing(machine.world) } : context;
+  // A node of a tree reads the definitions of this evaluation for its equations (TREE.LADDER).
+  activeEnvs.push(env);
   try {
     return evaluateAt(env, { value: doc, place: [], declared: options.declaredType, depth: 0, address: false, ctx });
   } catch (error) {
     return placed(thrown(error, "the reference"), []);
+  } finally {
+    activeEnvs.pop();
   }
 }
 
+/** The evaluations of the reference that run at this time, the innermost last. */
+const activeEnvs: Env[] = [];
+
 /*
  * The definition of the decorated tree (TREE.*), written from docs/SPEC.md. It shares no code with `tree.node` of
  * stdlib.ts: its nodes, its memo, its marks for attributes in evaluation and its JSON are its own.
@@ -444,6 +460,16 @@ interface RefNode {
   readonly place: readonly Key[];
   readonly parts: readonly Part[];
   readonly ctx: Context;
+  /** The tree contract of the kind of the node (D42). */
+  readonly contract: TreeContract | undefined;
+  /** The type of a bare equation: the type `of` of the parts of the kind. */
+  readonly of: string | undefined;
+  /** The parent node in the same tree, for the rungs `parent` and `copy`. */
+  readonly up: RefNode | undefined;
+  /** The evaluation of the reference that made the node. Its equations evaluate with its definitions. */
+  readonly env: Env | undefined;
+  /** The host thing of the node. */
+  thing: HostThing;
   /** The results of the attributes that ended. */
   readonly values: Map<string, Result>;
   /** The attributes in evaluation. */
@@ -463,8 +489,86 @@ function refNodeOf(thing: unknown): RefNode | undefined {
   return typeof thing === "object" && thing !== null ? refNodes.get(thing) : undefined;
 }
 
-/** TREE.ONCE, TREE.MEMO and TREE.CYCLE: the result of one attribute, or `undefined` when the node has no such part. */
-function attributeOf(node: RefNode, self: HostThing, name: string): Result | undefined {
+/**
+ * TREE.LADDER: an equation of the kind of a node evaluates in the reference. It gets the node as `self`, the names of
+ * its rung and no capabilities. A bare equation gets the type `of` of the parts of the kind.
+ */
+function equationOf(node: RefNode, term: Json, names: Readonly<Record<string, unknown>>): Result {
+  const env = node.env;
+  if (env === undefined) return fail("#NOEVAL", "The evaluation of an equation needs the machine.");
+  const ctx: Context = { ...node.ctx, names, caps: [], self: node.thing };
+  return reference(env.machine, term, ctx, { definitions: env.definitions, ...(node.of === undefined ? {} : { declaredType: node.of }) });
+}
+
+function termIn<T>(table: Readonly<Record<string, T>> | undefined, name: string): T | undefined {
+  return table === undefined || !Object.hasOwn(table, name) ? undefined : table[name];
+}
+
+/** TREE.DOWN: the names of a child for an equation of `down` of its parent: `child`, `index` and `prev`. */
+function namesOfChild(up: RefNode, child: RefNode): Result {
+  const children = attributeOf(up, "children");
+  if (children !== undefined && !children.ok) return children;
+  const list: readonly unknown[] = children !== undefined && Array.isArray(children.value) ? children.value : [];
+  const index = list.indexOf(child.thing);
+  return ok({ child: child.thing, index: index < 0 ? null : index, prev: index > 0 ? list[index - 1] : null });
+}
+
+/** TREE.FOLD: the unit, then `combine` with the attribute of each node of this tree in the list `children`. */
+function foldOf(node: RefNode, name: string, fold: NonNullable<AttributeDeclaration["fold"]>): Result {
+  let acc = equationOf(node, fold.unit, {});
+  if (!acc.ok) return acc;
+  const children = attributeOf(node, "children");
+  if (children === undefined) return acc;
+  if (!children.ok) return children;
+  if (!Array.isArray(children.value)) return fail("#VALUE!", `The fold of ${name} needs a list in children.`);
+  for (const item of children.value) {
+    const child = refNodeOf(item);
+    if (child === undefined || child.tree !== node.tree) continue;
+    const value = attributeOf(child, name);
+    if (value === undefined) return fail("#N/A", `No rung gives ${nameOfAttribute(child, name)}.`);
+    if (!value.ok) return value;
+    acc = equationOf(node, fold.combine, { acc: acc.value, item: value.value });
+    if (!acc.ok) return acc;
+  }
+  return acc;
+}
+
+/**
+ * TREE.LADDER: the rungs of the ladder of an attribute, in their order. A rung gives `undefined` when it does not
+ * answer, and the next rung then tries.
+ */
+const REF_RUNGS: readonly (readonly [AttributeRung, (node: RefNode, name: string) => Result | undefined])[] = [
+  ["own", (node, name) => node.parts.find((item) => item.key === name)?.evaluate({ ...node.ctx, self: node.thing })],
+  [
+    "kind",
+    (node, name) => {
+      const term = termIn(node.contract?.equations, name);
+      return term === undefined ? undefined : equationOf(node, term, {});
+    },
+  ],
+  [
+    "parent",
+    (node, name) => {
+      const up = node.up;
+      const term = up === undefined ? undefined : termIn(up.contract?.down, name);
+      if (up === undefined || term === undefined) return undefined;
+      const names = namesOfChild(up, node);
+      return names.ok ? equationOf(up, term, names.value as Readonly<Record<string, unknown>>) : names;
+    },
+  ],
+  ["copy", (node, name) => (node.up !== undefined && termIn(node.contract?.attributes, name)?.copy === true ? attributeOf(node.up, name) : undefined)],
+  [
+    "default",
+    (node, name) => {
+      const declared = termIn(node.contract?.attributes, name);
+      if (declared?.fold !== undefined) return foldOf(node, name, declared.fold);
+      return declared?.default === undefined ? undefined : equationOf(node, declared.default, {});
+    },
+  ],
+];
+
+/** TREE.ONCE, TREE.MEMO and TREE.CYCLE: the result of one attribute, or `undefined` when no rung of its ladder answers. */
+function attributeOf(node: RefNode, name: string): Result | undefined {
   const done = node.values.get(name);
   if (done !== undefined) return done;
   if (node.pending.has(name)) {
@@ -472,14 +576,16 @@ function attributeOf(node: RefNode, self: HostThing, name: string): Result | und
     const steps = from < 0 ? [nameOfAttribute(node, name)] : inEvaluation.slice(from).map((entry) => nameOfAttribute(entry.node, entry.name));
     return fail("#CYCLE!", `The attributes form a cycle: ${[...steps, nameOfAttribute(node, name)].join(" -> ")}.`);
   }
-  const part = node.parts.find((item) => item.key === name);
-  if (part === undefined) return undefined;
   node.pending.add(name);
   inEvaluation.push({ node, name });
   try {
-    const result = part.evaluate({ ...node.ctx, self });
-    node.values.set(name, result);
-    return result;
+    for (const [, rung] of REF_RUNGS) {
+      const result = rung(node, name);
+      if (result === undefined) continue;
+      node.values.set(name, result);
+      return result;
+    }
+    return undefined;
   } finally {
     node.pending.delete(name);
     inEvaluation.pop();
@@ -490,7 +596,7 @@ function attributeOf(node: RefNode, self: HostThing, name: string): Result | und
 function jsonOfNode(node: RefNode, self: HostThing, open: readonly object[]): Result {
   const record: Record<string, unknown> = {};
   for (const part of node.parts) {
-    const result = attributeOf(node, self, part.key) as Result;
+    const result = attributeOf(node, part.key) as Result;
     if (!result.ok) return result;
     const value = plainValue(result.value, [...open, self]);
     if (!value.ok) return value;
@@ -530,10 +636,26 @@ function plainValue(value: unknown, open: readonly object[]): Result {
  * TREE.LAZY, TREE.PARENT, TREE.SIBLING and TREE.ERROR: a node of an open tree gives its thing, and the root of a new
  * tree gives its JSON. A step on the thing reads an attribute, and a failed attribute throws its own error.
  */
-const treeDefinition: EvalFn = ({ parts, context, kind, place }) => {
+const treeDefinition: EvalFn = ({ parts, context, kind, place, machine, typePath }) => {
   const outer = refNodeOf(context.self);
   const nested = outer !== undefined && outer.tree.open;
-  const node: RefNode = { tree: nested ? outer.tree : { open: true }, kind, place, parts, ctx: context, values: new Map(), pending: new Set() };
+  const found = machine === undefined || typePath.length === 0 ? undefined : lookupKind(machine.world, typePath);
+  const contract = found?.ok === true ? found.kind.tree : undefined;
+  const of = contract === undefined || found?.ok !== true ? undefined : equationType(found.kind);
+  const node: RefNode = {
+    tree: nested ? outer.tree : { open: true },
+    kind,
+    place,
+    parts,
+    ctx: context,
+    contract,
+    of,
+    up: nested ? outer : undefined,
+    env: activeEnvs[activeEnvs.length - 1],
+    thing: null as unknown as HostThing,
+    values: new Map(),
+    pending: new Set(),
+  };
   const self: HostThing & { readonly type: string } = {
     [THING]: true,
     type: kind,
@@ -541,17 +663,18 @@ const treeDefinition: EvalFn = ({ parts, context, kind, place }) => {
     deref: (key): Thing | undefined => {
       if (key === "parent") return context.self;
       if (key === "type") return kind;
-      const result = attributeOf(node, self, String(key));
+      const result = attributeOf(node, String(key));
       if (result === undefined || result.ok) return result?.ok === true ? result.value : undefined;
       throw new Failure(result.error);
     },
-    has: (key) => key === "parent" || key === "type" || parts.some((part) => part.key === String(key)),
+    has: (key) => key === "parent" || key === "type" || parts.some((part) => part.key === String(key)) || node.values.has(String(key)),
     toJson: () => {
       const result = jsonOfNode(node, self, []);
       if (result.ok) return result.value;
       throw new Failure(result.error);
     },
   };
+  node.thing = self;
   refNodes.set(self, node);
   if (nested) return ok(self);
   try {

package/src/static.ts

@@ -1,7 +1,7 @@
-import { type Envelope, type Json, type Key, isEnvelope, isKey, isRecord, typeName } from "./doc.ts";
-import type { Kind, NamesSource, ScopeRule, World } from "./world.ts";
+import { type Envelope, type Json, type Key, isKey, isRecord, typeName } from "./doc.ts";
+import { type Kind, type World, equationType } from "./world.ts";
 import { ask } from "./ladder.ts";
-import { type PartSlot, partsOf, pathMatches } from "./parts.ts";
+import { type PartSlot, partsOf, scopesOf } from "./parts.ts";
 import { type Cap, type Context, type Root, ROOTS, context, isRef, walkerOf, worldThing } from "./deref.ts";
 import type { ErrorCode } from "./errors.ts";
 import { type Machine, partCaps, permits, waitedReason } from "./evaluate.ts";
@@ -67,75 +67,6 @@ export interface WalkOptions {
   readonly problem?: (problem: WalkProblem) => void;
 }
 
-function valueAt(value: unknown, path: readonly Key[]): unknown {
-  let here: unknown = value;
-  for (const key of path) {
-    if (Array.isArray(here)) here = here[Number(key)];
-    else if (isRecord(here) && Object.hasOwn(here, String(key))) here = here[String(key)];
-    else return undefined;
-  }
-  return here;
-}
-
-function headerName(item: Json): string | undefined {
-  return isEnvelope(item) && typeof (item as { readonly name?: unknown }).name === "string" ? (item as { readonly name: string }).name : undefined;
-}
-
-function namesOf(source: NamesSource, value: unknown, covered: readonly PartSlot[]): readonly string[] {
-  if ("fixed" in source) return source.fixed;
-  if ("keysAt" in source) {
-    const at = valueAt(value, source.keysAt);
-    return isRecord(at) ? Object.keys(at) : [];
-  }
-  if ("listAt" in source) {
-    const at = valueAt(value, source.listAt);
-    return Array.isArray(at) ? (at as readonly unknown[]).filter((item): item is string => typeof item === "string") : [];
-  }
-  if ("textAt" in source) {
-    const at = valueAt(value, source.textAt);
-    if (typeof at === "string") return [at];
-    return source.otherwise === undefined ? [] : [source.otherwise];
-  }
-  return covered.map((slot) => headerName(slot.item)).filter((name): name is string => name !== undefined);
-}
-
-/**
- * This function gives the names that the scope rules of a kind give each part, and the names that only later parts
- * see. `check` and `conforms` read the scope rules with it.
- *
- * @param rules - The scope rules of the kind.
- * @param value - The value of the document.
- * @param slots - The parts of the value, in order.
- * @returns The names that each part sees, and the names that only the later parts see, by the index of the part.
- */
-export function scopesOf(rules: readonly ScopeRule[] | undefined, value: unknown, slots: readonly PartSlot[]): { readonly sees: readonly (readonly string[])[]; readonly later: readonly (readonly string[])[] } {
-  const sees: string[][] = slots.map(() => []);
-  const later: string[][] = slots.map(() => []);
-  for (const rule of rules ?? []) {
-    const covered = slots.map((slot, index) => ({ slot, index })).filter(({ slot }) => rule.in.some((pattern) => pathMatches(slot.path, pattern)));
-    if (rule.sequential !== true) {
-      const names = namesOf(rule.names, value, covered.map(({ slot }) => slot));
-      for (const { index } of covered) sees[index]?.push(...names);
-      continue;
-    }
-    if ("headers" in rule.names) {
-      covered.forEach(({ index }, position) => {
-        const before = covered.slice(0, position).map(({ slot }) => headerName(slot.item)).filter((name): name is string => name !== undefined);
-        const after = covered.slice(position).map(({ slot }) => headerName(slot.item)).filter((name): name is string => name !== undefined);
-        sees[index]?.push(...before);
-        later[index]?.push(...after);
-      });
-      continue;
-    }
-    const names = namesOf(rule.names, value, covered.map(({ slot }) => slot));
-    covered.forEach(({ index }, position) => {
-      if (position > 0) sees[index]?.push(...names);
-      else later[index]?.push(...names);
-    });
-  }
-  return { sees, later };
-}
-
 /** The names of a walk without names. A walk does not change a set at any time: it makes a new set to add names. */
 const NO_NAMES: ReadonlySet<string> = /* @__PURE__ */ new Set();
 
@@ -595,11 +526,55 @@ interface Drive {
 /** What the code of a document does with a wait: an evaluator stops it, and a runner passes it on. */
 type Waits = boolean | Drive;
 
+/** The names that an equation of `down` sees (TREE.DOWN). */
+const DOWN_NAMES: readonly string[] = /* @__PURE__ */ Object.freeze(["child", "index", "prev"]);
+
+/** The names that the term `combine` of a fold sees (TREE.FOLD). */
+const FOLD_NAMES: readonly string[] = /* @__PURE__ */ Object.freeze(["acc", "item"]);
+
+/**
+ * This function gives each equation of the tree contract of a kind, with the names that it sees (D42). An equation of
+ * `equations`, a `unit` and a `default` see no names.
+ */
+function equationsOf(kind: Kind): readonly { readonly label: string; readonly term: Json; readonly names: readonly string[] }[] {
+  const tree = kind.tree;
+  if (tree === undefined) return [];
+  const out: { readonly label: string; readonly term: Json; readonly names: readonly string[] }[] = [];
+  for (const [name, term] of Object.entries(tree.equations ?? {})) out.push({ label: `tree.equations.${name}`, term, names: [] });
+  for (const [name, term] of Object.entries(tree.down ?? {})) out.push({ label: `tree.down.${name}`, term, names: DOWN_NAMES });
+  for (const [name, declared] of Object.entries(tree.attributes ?? {})) {
+    if (declared.fold !== undefined) {
+      out.push({ label: `tree.attributes.${name}.fold.unit`, term: declared.fold.unit, names: [] });
+      out.push({ label: `tree.attributes.${name}.fold.combine`, term: declared.fold.combine, names: FOLD_NAMES });
+    }
+    if (declared.default !== undefined) out.push({ label: `tree.attributes.${name}.default`, term: declared.default, names: [] });
+  }
+  return out;
+}
+
+/**
+ * This function checks the equations of the tree contract of a kind, each with the names of its rung (TREE.DOWN-NAMES).
+ * An equation evaluates without capabilities, thus a check with capabilities gives it none. Each issue gets the place
+ * of the document of the kind, and its reason names the equation.
+ */
+function equationIssues(machine: Machine, kind: Kind, kindText: string, options: CheckOptions, seen: Set<Kind>): readonly Issue[] {
+  const of = equationType(kind);
+  const out: Issue[] = [];
+  for (const { label, term, names } of equationsOf(kind)) {
+    const inner: CheckOptions = { names, ...(of === undefined ? {} : { declaredType: of }), ...(options.caps === undefined ? {} : { caps: [] }) };
+    for (const issue of checkAll(machine, term, inner, undefined, seen)) {
+      out.push({ code: issue.code, place: [], reason: `In the equation ${label} of the kind ${kindText}: ${issue.reason}` });
+    }
+  }
+  return out;
+}
+
 /**
  * This function finds the issues of `check`. With a list of nodes, it also records each document that it visits for
- * the pass of types. It marks each document with an issue.
+ * the pass of types. It marks each document with an issue. The set `seen` holds the kinds whose equations the check
+ * walked, thus it walks the equations of each kind one time.
  */
-function checkAll(machine: Machine, doc: unknown, options: CheckOptions, nodes: TypeNode[] | undefined): readonly Issue[] {
+function checkAll(machine: Machine, doc: unknown, options: CheckOptions, nodes: TypeNode[] | undefined, seen: Set<Kind> = new Set()): readonly Issue[] {
   const issues: Issue[] = [];
   const verb = options.verb ?? "eval";
   const indices = nodes === undefined ? undefined : new Map<DocVisit, number>();
@@ -643,6 +618,11 @@ function checkAll(machine: Machine, doc: unknown, options: CheckOptions, nodes:
         push({ code: "#KIND?", place: v.place, reason: `The world has no kind ${typeName(v.doc.type)}.`, at: v.at });
         return "skip";
       }
+      // The equations of a kind are code of the kind. The check walks them at the first document of the kind (D42).
+      if (v.kind?.tree !== undefined && !seen.has(v.kind)) {
+        seen.add(v.kind);
+        for (const issue of equationIssues(machine, v.kind, typeName(v.doc.type), options, seen)) push({ ...issue, place: v.place, at: v.at });
+      }
       const name = answer.evaluator;
       if (current !== undefined) current.evaluator = name;
       // A runner hides the evaluator of its name (MACHINE.RUNNER), as in the compilation of a plan.