@mark1russell7/coeval 0.20.1 → 0.22.0

package/src/world.ts

@@ -1,4 +1,4 @@
-import { type Envelope, type Json, type Key, type TypeRef, field, isRecord, typePath } from "./doc.ts";
+import { type Envelope, type Json, type JsonRecord, type Key, type TypeRef, field, isRecord, typePath } from "./doc.ts";
 import type { Cap, Root } from "./deref.ts";
 import type { ValueType } from "./types.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,98 @@ 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.
+ * - `at`: the attributes with parameters of the node (TREE.AT, D124). Only the step `tree.at` reads them, and the
+ *   equation sees each parameter as a name.
  */
 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>>;
+  readonly at?: Readonly<Record<string, AtEquation>>;
+}
+
+/**
+ * An attribute with parameters (TREE.AT, D124), as `paramAttr` in Kiama. The step `tree.at` gives the arguments. The
+ * equation evaluates with the node as `self`, and it sees each parameter as a name, for example `names.width`.
+ */
+export interface AtEquation {
+  /** The names of the parameters. The step gives an argument for each of them, and no other argument. */
+  readonly params: readonly string[];
+  readonly equation: Json;
+}
+
+/** An entry of `tree.at` that the kit can use, or the reason of a bad entry (D124). */
+export type AtRule = { readonly ok: true; readonly params: readonly string[]; readonly equation: Json } | { readonly ok: false; readonly reason: string };
+
+/**
+ * This function reads an entry of the table `tree.at` (D124). The tree kit, the reference, `check` and the graph of
+ * attribute instances read it with this one function.
+ *
+ * @param declared - The entry.
+ * @returns The rule, or the reason when the entry has no correct form.
+ */
+export function atRuleOf(declared: unknown): AtRule {
+  const params = isRecord(declared) ? field(declared, "params") : undefined;
+  const good = Array.isArray(params) && params.every((name, index) => typeof name === "string" && params.indexOf(name) === index);
+  if (!good || !Object.hasOwn(declared as object, "equation")) {
+    return { ok: false, reason: "An entry of tree.at needs a list params of different texts and the field equation." };
+  }
+  return { ok: true, params: params as readonly string[], equation: field(declared as JsonRecord, "equation") as Json };
+}
+
+/** The arguments of a step `tree.at` (D124): the names of the equation and their key, or the reason of bad arguments. */
+export type AtArgs = { readonly ok: true; readonly names: Readonly<Record<string, Json>>; readonly key: string } | { readonly ok: false; readonly reason: string };
+
+/**
+ * This function examines the arguments of a step `tree.at` (D124). The step gives an argument for each parameter, and
+ * no other argument. Each argument is JSON data. The key is the text of `argsKey`, thus two equal arguments give one key.
+ *
+ * @param params - The parameters of the attribute.
+ * @param args - The field `args` of the step.
+ * @returns The names of the equation and the key, or the reason.
+ */
+export function atArgsOf(params: readonly string[], args: unknown): AtArgs {
+  if (!isRecord(args)) return { ok: false, reason: "The arguments are a record." };
+  const extra = Object.keys(args).find((name) => !params.includes(name));
+  if (extra !== undefined) return { ok: false, reason: `The attribute has no parameter ${extra}.` };
+  const names: Record<string, Json> = {};
+  for (const name of params) {
+    if (!Object.hasOwn(args, name)) return { ok: false, reason: `The step gives no argument ${name}.` };
+    const value = field(args, name);
+    if (argsKey(value) === undefined) return { ok: false, reason: `The argument ${name} is not JSON data.` };
+    Object.defineProperty(names, name, { value, enumerable: true, writable: true, configurable: true });
+  }
+  return { ok: true, names, key: argsKey(names) as string };
+}
+
+/**
+ * This function gives the key of a JSON value (D124). The fields of a record are in the order of their names. Two
+ * values have the same key only when they are equal by DOC.EQUALS, thus `-0` and `0` have different keys.
+ *
+ * @param value - The value.
+ * @returns The JSON text, or `undefined` for a value that is not JSON data: a number that is not finite, a host value or a cycle.
+ */
+export function argsKey(value: unknown): string | undefined {
+  return keyOf(value, new Set());
+}
+
+function keyOf(value: unknown, open: Set<object>): string | undefined {
+  if (value === null || typeof value === "boolean" || typeof value === "string") return JSON.stringify(value);
+  if (typeof value === "number") return !Number.isFinite(value) ? undefined : Object.is(value, -0) ? "-0" : JSON.stringify(value);
+  if (typeof value !== "object" || open.has(value) || (!Array.isArray(value) && !isRecord(value))) return undefined;
+  open.add(value);
+  try {
+    const list = Array.isArray(value);
+    const names = list ? [] : Object.keys(value).sort();
+    const items = list ? value.map((item) => keyOf(item, open)) : names.map((name) => keyOf(field(value as JsonRecord, name), open));
+    if (items.includes(undefined)) return undefined;
+    return list ? `[${items.join(",")}]` : `{${names.map((name, index) => `${JSON.stringify(name)}:${String(items[index])}`).join(",")}}`;
+  } finally {
+    open.delete(value);
+  }
 }
 
 /**