@mark1russell7/coeval 0.21.0 → 0.23.0

package/src/types.ts

@@ -87,7 +87,8 @@ export interface Domain {
 /**
  * The codec of a domain: it writes a member of the domain as JSON, and it reads the JSON again (D40). Both functions
  * must be pure. `decode(encode(v))` must equal `v` by `sameValue` (EXT.ROUNDTRIP). The codec must give one JSON
- * value for each member, thus the same value has the same document in each language (D12).
+ * value for each member, thus the same value has the same document in each language (D12). `codecLaws` examines
+ * these laws for the members of the domain (D130).
  */
 export interface DomainCodec {
   /**

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";
 
@@ -146,6 +146,8 @@ export interface KindFacts {
  *   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).
+ * - `higher`: the value of a node without an answer of the rungs before it. The term gives a document as data. The kit
+ *   evaluates that document with the node as `self`, thus its root is a new node under the node (TREE.HIGHER, D126).
  */
 export interface AttributeDeclaration {
   readonly copy?: boolean;
@@ -153,6 +155,7 @@ export interface AttributeDeclaration {
   readonly default?: Json;
   readonly circular?: CircularDeclaration;
   readonly collect?: CollectDeclaration;
+  readonly higher?: Json;
 }
 
 /**
@@ -189,6 +192,9 @@ export interface CircularDeclaration {
   readonly limit?: number;
 }
 
+/** The most generated documents on the way from a node to the root of its tree (TREE.HIGHER-DEPTH, D126). */
+export const GENERATION_LIMIT = 64;
+
 /** The most rounds of a circular attribute without its own `limit` (TREE.CIRCULAR-LIMIT, D113). */
 export const CIRCULAR_LIMIT = 100;
 
@@ -258,12 +264,111 @@ export function collectOf(declared: unknown): CollectRule {
  * - `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.
+ * - `forwards`: the name of an attribute that gives a node. An attribute that no other rung answers comes from that
+ *   node (TREE.FORWARD, D126).
  */
 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>>;
+  readonly forwards?: string;
+}
+
+/**
+ * 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());
+}
+
+/**
+ * This function gives the structural key of a document (TREE.HIGHER-PLAN, D126). The fields of a record keep their
+ * order, because the order of the parts decides the order of the JSON and the first error. Thus one key means one
+ * document, and the two documents are equal by DOC.EQUALS.
+ *
+ * @param doc - The document.
+ * @returns The JSON text, or `undefined` for a value that is not JSON data.
+ */
+export function documentKey(doc: unknown): string | undefined {
+  return keyOf(doc, new Set(), false);
+}
+
+function keyOf(value: unknown, open: Set<object>, sorted = true): 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 ? [] : sorted ? Object.keys(value).sort() : Object.keys(value);
+    const items = list ? value.map((item) => keyOf(item, open, sorted)) : names.map((name) => keyOf(field(value as JsonRecord, name), open, sorted));
+    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);
+  }
 }
 
 /**