@mark1russell7/coeval 0.8.0 → 0.10.0

package/src/static.ts

@@ -1,5 +1,5 @@
 import { type Envelope, type Json, type Key, isKey, isRecord, typeName } from "./doc.ts";
-import { type Kind, type World, equationType } from "./world.ts";
+import { type Kind, type Namespace, type World, type WorldEntry, effectsOfVerb, equationType, isKind, isNamespace } from "./world.ts";
 import { ask } from "./ladder.ts";
 import { type PartSlot, partsOf, scopesOf } from "./parts.ts";
 import { type Cap, type Context, type Root, ROOTS, context, isRef, walkerOf, worldThing } from "./deref.ts";
@@ -364,8 +364,11 @@ export interface CheckOptions {
   readonly caps?: readonly Cap[];
   /**
    * The verb that goes up the ladder at each document, as in `prepare`. The default is `eval`. `#NOEVAL` and the hook
-   * `known` follow this verb. The contract declares the effects and the value types of `eval` only, thus only `eval`
-   * checks them (VERB.CHECK). The type rule of an evaluator serves each verb.
+   * `known` follow this verb. The type rule of an evaluator serves each verb.
+   *
+   * The check tests the effects that the contract declares for this verb (VERB.EFFECTS). A kind without a declaration
+   * for the verb gives no effect issue. The contract declares the value types of `eval` only, thus only `eval` checks
+   * them (VERB.CHECK).
    */
   readonly verb?: string;
   /**
@@ -408,16 +411,28 @@ const EACH: readonly Cap[] = /* @__PURE__ */ Object.freeze([[]]);
 const NO_EFFECTS: readonly (readonly Key[])[] = /* @__PURE__ */ Object.freeze([]);
 
 /**
- * This function gives the effects that the contract of the kind of a visit declares, as keys (FACTS.EFFECTS). The
- * text `"type"` gives the type of the document after each alias. A visit without a kind declares no effect. `check`,
- * `factsOf` and `effectsOf` read the declarations with this one function (D27).
+ * This function gives the effects that the contract of the kind of a visit declares for a verb, as keys
+ * (FACTS.EFFECTS, VERB.EFFECTS). The text `"type"` gives the type of the document after each alias. A visit without a
+ * kind declares no effect. `check`, `factsOf` and `effectsOf` read the declarations with this one function (D27).
  *
  * @param v - The visit.
+ * @param verb - The verb. The default is `eval`. A kind without a declaration for the verb gives no effect.
  * @returns The keys of each declared effect, in the order of the contract.
  */
-export function declaredEffects(v: DocVisit): readonly (readonly Key[])[] {
-  const effects = v.kind?.effects;
-  if (effects === undefined || effects.length === 0) return NO_EFFECTS;
+export function declaredEffects(v: DocVisit, verb = "eval"): readonly (readonly Key[])[] {
+  return verbDeclared(v, verb) ?? NO_EFFECTS;
+}
+
+/**
+ * This function gives the effects that the contract of the kind of a visit declares for a verb, as keys. The result
+ * is `undefined` when the contract has no declaration for the verb (D49). A visit without a kind declares no effect
+ * for `eval` and no declaration for another verb.
+ */
+function verbDeclared(v: DocVisit, verb: string): readonly (readonly Key[])[] | undefined {
+  if (v.kind === undefined) return verb === "eval" ? NO_EFFECTS : undefined;
+  const effects = effectsOfVerb(v.kind, verb);
+  if (effects === undefined) return undefined;
+  if (effects.length === 0) return NO_EFFECTS;
   return effects === "type" ? [v.typePath ?? []] : effects.map((kind) => kind.split("."));
 }
 
@@ -472,7 +487,9 @@ function capReason(v: DocVisit, kind: readonly Key[], allowed: (caps: readonly C
  *   A run does not always fail there, thus a type issue is a static finding, not an error of a run.
  *
  * The check asks the ladder for the verb of the options, `eval` by default (VERB.CHECK). The shapes, the paths and the
- * names follow the contracts, thus they are the same for each verb. Only `eval` checks the declared effects.
+ * names follow the contracts, thus they are the same for each verb. The check tests the effects that each contract
+ * declares for the verb: `effects` for `eval`, and the entry of `verbEffects` for another verb (VERB.EFFECTS). A kind
+ * without a declaration for the verb gives no `#CAP!` and no `#CALC!` for an effect.
  *
  * @param machine - The world and the code of the evaluators.
  * @param doc - The document, as JSON.
@@ -508,6 +525,74 @@ export function typeCheck(machine: Machine, doc: unknown, options: CheckOptions
   return { type: pass.type, issues: pass.issues.length === 0 ? issues : [...issues, ...pass.issues], places: pass.places };
 }
 
+/**
+ * A problem of a world that `checkWorld` finds before a document exists (STATIC.COVERAGE). Each document of the
+ * kind gives this problem for the verb, thus `check` with the verb finds it too.
+ */
+export interface WorldIssue {
+  /** The code of the problem. `#NOEVAL`: no rung of the ladder gives an evaluator for the verb. */
+  readonly code: "#NOEVAL";
+  /** The keys of the kind from the root of the world. For a fallback kind, the keys of its namespace. */
+  readonly kind: readonly Key[];
+  /** `true` for the fallback kind of a namespace or of the world. */
+  readonly fallback?: true;
+  /** The verb without an evaluator. */
+  readonly verb: string;
+  readonly reason: string;
+}
+
+/** This function tells if a table of verbs has an entry for a verb. */
+function hasVerb(table: Readonly<Record<string, string>> | undefined, verb: string): boolean {
+  return table !== undefined && Object.hasOwn(table, verb);
+}
+
+/**
+ * This function checks the world of a machine before a document exists. It finds each kind that has no entry for a
+ * verb of the list, when the world has no default for that verb (STATIC.COVERAGE). A document of such a kind gets no
+ * evaluator for the verb, thus the check gives the same proof of coverage as a type system.
+ *
+ * The check visits each kind 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. The check reads only the world.
+ *
+ * @param machine - The machine, for its world.
+ * @param verbs - The verbs that each kind of the language must answer, for example `eval`, `view` and `type`.
+ * @returns One issue for each kind and verb without an evaluator. The order is the order of the world, then the
+ *   order of the verbs. The fallback kind of a namespace comes after the entries of that namespace.
+ */
+export function checkWorld(machine: Machine, verbs: readonly string[]): readonly WorldIssue[] {
+  const world = machine.world;
+  const open = verbs.filter((verb) => !hasVerb(world.defaults, verb));
+  const out: WorldIssue[] = [];
+  if (open.length === 0) return out;
+  const visit = (kind: Kind, path: readonly Key[], fallback: boolean): void => {
+    const text = path.join(".");
+    const name = fallback ? (path.length === 0 ? "the fallback kind of the world" : `the fallback kind of ${text}`) : `the kind ${text}`;
+    for (const verb of open) {
+      if (hasVerb(kind.verbs, verb)) continue;
+      const reason = `${name.charAt(0).toUpperCase()}${name.slice(1)} has no entry for the verb ${verb}, and the world has no default for it.`;
+      out.push(fallback ? { code: "#NOEVAL", kind: path, fallback: true, verb, reason } : { code: "#NOEVAL", kind: path, verb, reason });
+    }
+  };
+  // 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);
+  return out;
+}
+
 /**
  * A runner under an evaluator in a check of a run. The run drives its steps without a wait, thus only a wait for an
  * effect of its runners fails (RUN.DRIVE-NESTED).
@@ -583,9 +668,8 @@ function checkAll(machine: Machine, doc: unknown, options: CheckOptions, nodes:
     issues.push(issue);
     if (current !== undefined) current.marked = true;
   };
-  // The effects of a contract are the effects of eval (VERB.CONTRACT). An effect of another verb meets its test when
-  // it happens (RUN.CAP).
-  const effects = verb === "eval";
+  // The field effects declares eval, and verbEffects declares the other verbs (VERB.EFFECTS). An effect of a verb
+  // without a declaration meets its test when it happens (RUN.CAP).
   const allowed = options.caps === undefined ? undefined : permitsOf(machine);
   // In a run, a part that can wait needs a parent that can wait (RUN.CAN-WAIT). The map tells for each document with
   // code if its code passes a wait on: false for an evaluator, true for a runner whose waits reach the driver of the
@@ -636,7 +720,8 @@ function checkAll(machine: Machine, doc: unknown, options: CheckOptions, nodes:
         if (known !== true) push({ code: "#NAME?", place: v.place, reason: known, at: v.at });
       }
       const caps = v.caps;
-      const declared = effects ? declaredEffects(v) : NO_EFFECTS;
+      const stated = verbDeclared(v, verb);
+      const declared = stated ?? NO_EFFECTS;
       if (allowed !== undefined && caps !== undefined) {
         for (const kind of declared) {
           if (!allowed(caps, kind)) push({ code: "#CAP!", place: v.place, reason: capReason(v, kind, allowed), at: v.at });
@@ -650,16 +735,17 @@ function checkAll(machine: Machine, doc: unknown, options: CheckOptions, nodes:
           // The run drives a runner under an evaluator, and only a real wait fails (RUN.DRIVE-NESTED). Its issue goes in
           // here, in the order of the document, when an effect of its runners can wait.
           const issue: Issue = { code: "#CALC!", place: v.place, reason: waitedReason(typeName(v.doc.type)), at: v.at };
-          chain = { issue, index: issues.length, node: current, wait: !effects };
+          chain = { issue, index: issues.length, node: current, wait: false };
           drives.push(chain);
         } else if (runner) {
           chain = up ?? true;
         }
         waits.set(v, chain);
-        // A runner waits only for an effect that reaches the host (C6). A refused effect gives #CAP! without a wait.
+        // A runner waits only for an effect that reaches the host (C6). A refused effect gives #CAP! without a wait. A
+        // runner without a declaration for the verb can cause each effect, thus it can wait.
         if (typeof chain === "object" && !chain.wait) {
           const rule = allowed ?? permits;
-          chain.wait = declared.some((kind) => caps === undefined || rule(caps, kind));
+          chain.wait = stated === undefined || declared.some((kind) => caps === undefined || rule(caps, kind));
         }
         // In a run, the host does each effect, thus an evaluator cannot cause one.
         const first = declared[0];

package/src/stdlib.ts

@@ -71,6 +71,8 @@ export const STD_WORLD: World = {
       // A node that nothing reads keeps its attributes without an evaluation (TREE.LAZY).
       pure: true,
       lazy: [{}],
+      // The code resolves self to find an open tree and the parent (C4, D44).
+      reads: ["self"],
       summary: "A node of a tree. Each part is an attribute that evaluates on demand, one time, with the node as self.",
     },
     box: {
@@ -79,6 +81,7 @@ export const STD_WORLD: World = {
       caps: [{ rule: "mask" }],
       pure: true,
       lazy: [{}],
+      reads: ["self"],
       summary: "A node of a tree, as panel. A formula in a box can read its parent and its siblings.",
     },
     math: {
@@ -396,11 +399,12 @@ function plainOf(value: unknown, path: Set<object>): Result {
  * step `type` gives its type. Another step reads an attribute through its ladder (TREE.LADDER). The rungs are a part of
  * 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).
  */
-function treeThing(input: EvalInput, build: TreeBuild): HostThing {
+function treeThing(input: EvalInput, build: TreeBuild, outer: Thing | undefined): HostThing {
   const { parts, context, kind: type, place, machine } = input;
   const { tree, of } = contractOf(machine, input.typePath);
-  const above = stateOf(context.self);
+  const above = stateOf(outer);
   // 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>();
@@ -522,7 +526,7 @@ function treeThing(input: EvalInput, build: TreeBuild): HostThing {
     type,
     label: `node ${type}`,
     deref(key: Key): Thing | undefined {
-      if (key === "parent") return context.self;
+      if (key === "parent") return outer;
       if (key === "type") return type;
       const result = read(String(key));
       if (result === undefined) return undefined;
@@ -556,15 +560,24 @@ export function attributeTrace(node: Thing, attribute: string): AttributeTrace |
   return stateOf(node)?.trace(attribute);
 }
 
+/** The path of the root `self`. A node of the tree resolves it, thus the list of reads holds the read (C4). */
+const SELF_PATH: readonly Json[] = /* @__PURE__ */ Object.freeze(["self"]);
+
+/** The options of the resolution of `self`: the node needs no hops. */
+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.
+ * 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.
  */
 function treeNode(input: EvalInput): Result {
-  const above = stateOf(input.context.self);
-  if (above !== undefined && above.build.open) return ok(treeThing(input, above.build));
+  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);
+  const root = treeThing(input, build, outer);
   try {
     return (stateOf(root) as NodeState).json(new Set());
   } finally {

package/src/types.ts

@@ -9,8 +9,8 @@ import { type Json, type Key, docEquals, isEnvelope, isRecord } from "./doc.ts";
 /**
  * A value type: a set of values that a result can have, as a JSON term.
  *
- * - A text names a base type: `unknown`, `never`, a domain of the kernel (`null`, `bool`, `number`, `text`), or a
- *   domain of a language.
+ * - A text names a base type: `unknown`, `never`, a domain of the kernel (`null`, `undefined`, `bool`, `number`,
+ *   `text`), or a domain of a language.
  * - `list`: a list whose items have the type.
  * - `record`: a plain record with the named fields. `optional` names the fields that can be absent. A `closed`
  *   record has no other fields. The other fields of an open record can hold each value.
@@ -95,6 +95,8 @@ export interface TypeIssue {
  */
 export const STD_DOMAINS: Readonly<Record<string, Domain>> = {
   null: { is: (value) => value === null, summary: "The value null." },
+  // JSON has no undefined, thus a document holds it as ext.undefined (D48). The domain has no codec: the codec of values writes undefined first.
+  undefined: { is: (value) => value === undefined, summary: "The value undefined. A document holds it as the extension ext.undefined." },
   bool: { is: (value) => typeof value === "boolean", summary: "A truth value: true or false." },
   number: { is: (value) => typeof value === "number", summary: "A number of the host, also NaN, an infinity and -0." },
   text: { is: (value) => typeof value === "string", summary: "A text." },

package/src/world.ts

@@ -1,5 +1,5 @@
 import { type Envelope, type Json, type Key, type TypeRef, field, isRecord, typePath } from "./doc.ts";
-import type { Cap } from "./deref.ts";
+import type { Cap, Root } from "./deref.ts";
 import type { ValueType } from "./types.ts";
 
 /** The two sides of evaluation. `derive` is pure. `run` causes effects in order. */
@@ -114,11 +114,14 @@ export interface LazyRule {
  *   because the static facts do not see that read.
  * - `volatile`: `true` when its result can change while each read gives the same thing, for example a clock.
  * - `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.
  */
 export interface KindFacts {
   readonly pure?: boolean;
   readonly volatile?: boolean;
   readonly lazy?: readonly LazyRule[];
+  readonly reads?: readonly Root[];
 }
 
 /**
@@ -169,7 +172,8 @@ export function equationType(kind: Kind): string | undefined {
 /**
  * A kind gives the name of an evaluator for each verb, and the contract of its value. The contract serves each verb.
  * For each verb, the kernel splits the parts and narrows their capabilities by it, and `check` reads its scope rules.
- * `side` and `effects` tell what the verb `eval` does (VERB.CONTRACT).
+ * `side` and `effects` tell what the verb `eval` does (VERB.CONTRACT). `verbEffects` tells the effects of the other
+ * verbs (VERB.EFFECTS).
  */
 export interface Kind extends KindFacts {
   /**
@@ -197,6 +201,13 @@ export interface Kind extends KindFacts {
    * (CAP.LATENT).
    */
   readonly effects?: "type" | readonly string[];
+  /**
+   * The effects that the other verbs of a document of this kind can cause, by verb, in the form of `effects`
+   * (VERB.EFFECTS, D49). An entry `view: []` declares no effect for `view`. A verb without an entry has no
+   * declaration, thus `check` does not test its effects. The field `effects` declares `eval`, thus this field has no
+   * entry `eval`.
+   */
+  readonly verbEffects?: VerbEffects;
   /**
    * The value type of the result of the verb `eval`, when it is fixed (TYPE.SYNTH). A check of types gives it to each
    * document of the kind, in the place of the type that the rule of the evaluator synthesizes.
@@ -211,6 +222,28 @@ export interface Kind extends KindFacts {
   readonly summary?: string;
 }
 
+/**
+ * The effects that a contract declares for the verbs other than `eval`, by verb (D49). Each entry has the form of the
+ * field `effects` of a kind. The type has no entry `eval`, because the field `effects` declares `eval`.
+ */
+export type VerbEffects = Readonly<Record<string, "type" | readonly string[]>> & { readonly eval?: never };
+
+/**
+ * This function gives the effects that the contract of a kind declares for a verb (VERB.EFFECTS, D49). For `eval`,
+ * the field `effects` declares them, and a kind without the field declares no effect. For another verb, the entry of
+ * `verbEffects` declares them. `check` and `conforms` read the declarations with this one function.
+ *
+ * @param kind - The kind.
+ * @param verb - The verb.
+ * @returns The declaration in the form of `effects`, or `undefined` when the contract does not declare the effects of
+ *   the verb.
+ */
+export function effectsOfVerb(kind: Kind, verb: string): "type" | readonly string[] | undefined {
+  if (verb === "eval") return kind.effects ?? [];
+  const table = kind.verbEffects as Readonly<Record<string, "type" | readonly string[]>> | undefined;
+  return table !== undefined && Object.hasOwn(table, verb) ? table[verb] : undefined;
+}
+
 /** A namespace: a group of entries under one key of the world. `fallback` is the kind of each other key in it. */
 export interface Namespace {
   readonly kinds: Readonly<Record<string, WorldEntry>>;