@mark1russell7/coeval 0.3.3 → 0.4.1

package/src/static.ts

@@ -4,7 +4,7 @@ import { ask } from "./ladder.ts";
 import { type PartSlot, pathMatches, splitParts } from "./parts.ts";
 import { type Cap, type Root, ROOTS, isRef } from "./deref.ts";
 import type { ErrorCode } from "./errors.ts";
-import { type Machine, permits } from "./evaluate.ts";
+import { type Machine, partCaps, permits } from "./evaluate.ts";
 
 /** One document that a walk visits. */
 export interface DocVisit {
@@ -12,25 +12,38 @@ export interface DocVisit {
   readonly place: readonly Key[];
   /** The keys from the root JSON value to this document. A change at this path changes this document. */
   readonly at: readonly Key[];
+  /** The visit of the document that holds this document as a part. The root has none. */
+  readonly parent?: DocVisit | undefined;
+  /** The keys from the value of the parent to this document: the path of the part. The root has none. */
+  readonly slot: readonly Key[];
   /** The document. A bare value has the type that its position declares. */
   readonly doc: Envelope;
   /** `true` when the type came from the position and not from an envelope. */
   readonly declared: boolean;
   /** The kind of the document, when the world has it. */
-  readonly kind?: Kind;
+  readonly kind?: Kind | undefined;
   /** The keys of the kind after each alias. */
-  readonly typePath?: readonly Key[];
+  readonly typePath?: readonly Key[] | undefined;
   /** The number of documents around this document. The root has 0. */
   readonly depth: number;
   /** The names that the kinds around this document bind for it. */
   readonly names: ReadonlySet<string>;
   /** The names that a sequence around this document binds only for the parts after it. */
   readonly later: ReadonlySet<string>;
+  /** `true` when the position of the document declares an address: a reference there is not a read of a value. */
+  readonly address?: true | undefined;
+  /**
+   * The capabilities of the document: the capabilities of the walk, narrowed by the capability rules of the kinds
+   * around it (`Kind.caps`). A walk without capabilities gives none here.
+   */
+  readonly caps?: readonly Cap[] | undefined;
 }
 
 /** A position that a walk cannot read as a document. */
 export interface WalkProblem {
+  /** The keys from the root document to the document with the problem. */
   readonly place: readonly Key[];
+  /** The keys from the root JSON value to the value with the problem. */
   readonly at: readonly Key[];
   readonly code: "#PART?" | "#VALUE!";
   readonly reason: string;
@@ -42,6 +55,8 @@ export interface WalkOptions {
   readonly declaredType?: string;
   /** The names that the host binds at the root. */
   readonly names?: readonly string[];
+  /** The capabilities at the root. With them, each visit gets the capabilities of its document. */
+  readonly caps?: readonly Cap[];
   /**
    * This function gets each position that is not a document.
    *
@@ -120,74 +135,155 @@ function withoutNames(options: WalkOptions): WalkOptions {
   return rest;
 }
 
+/** A path that shares its start with other paths: the keys of one step, and the path before them. */
+interface Trail {
+  readonly up: Trail | undefined;
+  readonly keys: readonly Key[];
+  full?: readonly Key[];
+}
+
+/** This function gives the keys of a trail, from its start. It keeps the result in the trail. */
+function keysOf(trail: Trail | undefined): readonly Key[] {
+  if (trail === undefined) return [];
+  if (trail.full !== undefined) return trail.full;
+  const steps: Trail[] = [];
+  let here: Trail | undefined = trail;
+  while (here !== undefined && here.full === undefined) {
+    steps.push(here);
+    here = here.up;
+  }
+  const keys: Key[] = here?.full === undefined ? [] : [...here.full];
+  for (let index = steps.length - 1; index >= 0; index -= 1) for (const key of (steps[index] as Trail).keys) keys.push(key);
+  trail.full = keys;
+  return keys;
+}
+
+/** A visit with its paths as trails. It makes the keys of a path only when a reader asks for them. */
+class Visit implements DocVisit {
+  readonly #place: Trail | undefined;
+  readonly #at: Trail | undefined;
+
+  constructor(
+    place: Trail | undefined,
+    at: Trail | undefined,
+    readonly doc: Envelope,
+    readonly declared: boolean,
+    readonly depth: number,
+    readonly names: ReadonlySet<string>,
+    readonly later: ReadonlySet<string>,
+    readonly slot: readonly Key[],
+    readonly parent: DocVisit | undefined,
+    readonly kind: Kind | undefined,
+    readonly typePath: readonly Key[] | undefined,
+    readonly address: true | undefined,
+    readonly caps: readonly Cap[] | undefined,
+  ) {
+    this.#place = place;
+    this.#at = at;
+  }
+
+  get place(): readonly Key[] {
+    return keysOf(this.#place);
+  }
+
+  get at(): readonly Key[] {
+    return keysOf(this.#at);
+  }
+}
+
 /**
  * This function visits each document of a document: the root and each part at each depth, by the contracts of the
- * kinds. A part of a kind that the world does not have is not visited. The walk uses no stack of the host for the
- * depth, thus a deep document cannot overflow it.
+ * kinds. A part of a kind that the world does not have is not visited. With capabilities in the options, the walk
+ * narrows them for each part by the rules of its kind, as a run does. The walk uses no stack of the host for the
+ * depth, thus a deep document cannot overflow it. The time and the memory of a walk are linear in the size of the
+ * document. A visit makes the keys of its place and of its path only when a reader asks for them.
  *
  * @param world - The world of the kinds.
  * @param doc - The document, as JSON.
  * @param visit - The function that gets each document. It gives `"skip"` to not visit the parts of a document.
- * @param options - The type of a bare root value, the names of the host, and a function for the problems.
+ * @param options - The type of a bare root value, the names, the capabilities and a function for the problems.
  */
 export function walk(world: World, doc: unknown, visit: (visit: DocVisit) => void | "skip", options: WalkOptions = {}): void {
   interface Item {
     readonly value: unknown;
-    readonly place: readonly Key[];
-    readonly at: readonly Key[];
+    readonly place: Trail | undefined;
+    readonly at: Trail | undefined;
     readonly declared: string | undefined;
     readonly depth: number;
     readonly names: ReadonlySet<string>;
     readonly later: ReadonlySet<string>;
+    readonly address: boolean;
+    readonly slot: readonly Key[];
+    readonly parent: DocVisit | undefined;
+    readonly caps: readonly Cap[] | undefined;
   }
-  const names: ReadonlySet<string> = options.names === undefined || options.names.length === 0 ? NO_NAMES : new Set(options.names);
-  const stack: Item[] = [{ value: doc, place: [], at: [], declared: options.declaredType, depth: 0, names, later: NO_NAMES }];
+  const stack: Item[] = [
+    {
+      value: doc,
+      place: undefined,
+      at: undefined,
+      declared: options.declaredType,
+      depth: 0,
+      names: options.names === undefined || options.names.length === 0 ? NO_NAMES : new Set(options.names),
+      later: NO_NAMES,
+      address: false,
+      slot: [],
+      parent: undefined,
+      caps: options.caps,
+    },
+  ];
   while (stack.length > 0) {
     const item = stack.pop() as Item;
     const envelope = isEnvelope(item.value) ? (item.value as Envelope) : undefined;
     if (envelope === undefined && item.declared === undefined) {
-      options.problem?.({ place: item.place, at: item.at, code: "#PART?", reason: "The value has no envelope, and its position declares no type." });
+      options.problem?.({ place: keysOf(item.place), at: keysOf(item.at), code: "#PART?", reason: "The value has no envelope, and its position declares no type." });
       continue;
     }
     const doc: Envelope = envelope ?? { type: item.declared ?? "?", value: item.value as Json };
     const found = lookupKind(world, doc.type);
     const kind = found.ok ? found.kind : undefined;
-    const seen: DocVisit =
-      kind === undefined
-        ? { place: item.place, at: item.at, doc, declared: envelope === undefined, depth: item.depth, names: item.names, later: item.later }
-        : {
-            place: item.place,
-            at: item.at,
-            doc,
-            declared: envelope === undefined,
-            kind,
-            typePath: found.ok ? found.path : [],
-            depth: item.depth,
-            names: item.names,
-            later: item.later,
-          };
-    const answer = visit(seen);
+    const here = new Visit(
+      item.place,
+      item.at,
+      doc,
+      envelope === undefined,
+      item.depth,
+      item.names,
+      item.later,
+      item.slot,
+      item.parent,
+      kind,
+      found.ok ? found.path : undefined,
+      item.address ? true : undefined,
+      item.caps,
+    );
+    const answer = visit(here);
     if (answer === "skip" || kind === undefined) continue;
     const split = splitParts(kind.parts, doc.value);
+    const base: Trail | undefined = envelope === undefined ? item.at : { up: item.at, keys: ["value"] };
     if (!split.ok) {
       const at = split.at.length === 0 ? "" : ` (at ${split.at.join(".")})`;
-      options.problem?.({ place: item.place, at: item.at, code: "#VALUE!", reason: `${split.reason}${at} The kind is ${typeName(doc.type)}.` });
+      const where = keysOf({ up: base, keys: split.at });
+      options.problem?.({ place: keysOf(item.place), at: where, code: "#VALUE!", reason: `${split.reason}${at} The kind is ${typeName(doc.type)}.` });
       continue;
     }
     const { sees, later } = scopesOf(kind.scope, doc.value, split.parts);
-    const base = envelope === undefined ? item.at : [...item.at, "value"];
     for (let index = split.parts.length - 1; index >= 0; index -= 1) {
       const slot = split.parts[index] as PartSlot;
       const extra = sees[index] ?? [];
       const hidden = later[index] ?? [];
       stack.push({
         value: slot.item,
-        place: [...item.place, ...slot.path],
-        at: [...base, ...slot.path],
+        place: slot.path.length === 0 ? item.place : { up: item.place, keys: slot.path },
+        at: slot.path.length === 0 ? base : { up: base, keys: slot.path },
         declared: slot.of,
         depth: item.depth + 1,
         names: extra.length === 0 ? item.names : new Set([...item.names, ...extra]),
         later: hidden.length === 0 ? item.later : new Set([...item.later, ...hidden]),
+        address: slot.address === true,
+        slot: slot.path,
+        parent: here,
+        caps: item.caps === undefined || kind.caps === undefined ? item.caps : partCaps(kind.caps, slot.path, item.caps),
       });
     }
   }
@@ -195,6 +291,8 @@ export function walk(world: World, doc: unknown, visit: (visit: DocVisit) => voi
 
 /** One reference of a document. */
 export interface RefUse {
+  /** The visit of the reference document: its parent, its depth and the names that it sees. */
+  readonly visit: DocVisit;
   /** The place of the reference document, through the parts. */
   readonly place: readonly Key[];
   /** The keys from the root JSON value to the reference document. */
@@ -204,12 +302,14 @@ export interface RefUse {
   readonly root: string;
   /** `false` when a kind around the reference binds its first name. A reference to another root is free. */
   readonly free: boolean;
+  /** `true` when the reference is an address: its position declares it. An address does not read a value. */
+  readonly address: boolean;
 }
 
 /**
  * This function finds each reference of a document: each document of the type `ref` that a walk reaches. A
  * reference to a name that a kind around it binds is not free. The others are what the document reads from
- * outside: its dependencies.
+ * outside: its dependencies. When the kind `ref` has parts, the walk also finds the references in its step documents.
  *
  * @param world - The world of the kinds.
  * @param doc - The document, as JSON.
@@ -229,8 +329,13 @@ export function refsOf(world: World, doc: unknown, options: WalkOptions = {}): r
       const root = typeof path[0] === "string" ? path[0] : "";
       const first = path[1];
       const bound = root === "names" && isKey(first) && v.names.has(String(first));
-      out.push({ place: v.place, at: v.at, path, root, free: !bound });
-      return "skip";
+      // The place and the path of a reference are made only when a reader asks for them.
+      const use = { path, root, free: !bound, address: v.address === true } as RefUse;
+      Object.defineProperty(use, "place", { enumerable: true, get: () => v.place });
+      Object.defineProperty(use, "at", { enumerable: true, get: () => v.at });
+      Object.defineProperty(use, "visit", { enumerable: false, value: v });
+      out.push(use);
+      return undefined;
     },
     rest,
   );
@@ -278,6 +383,8 @@ export interface Issue {
   /** The keys from the root document to the document with the problem. */
   readonly place: readonly Key[];
   readonly reason: string;
+  /** The keys from the root JSON value to the value with the problem. */
+  readonly at?: readonly Key[];
 }
 
 /** The options of a check. */
@@ -286,10 +393,27 @@ export interface CheckOptions {
   readonly declaredType?: string;
   /** The names that the host binds at the root. `"any"` does not check the names. The default is no names. */
   readonly names?: readonly string[] | "any";
-  /** The capabilities at the root. Without them, the check does not check the effects. */
+  /**
+   * The capabilities at the root. Without them, the check does not check the effects. The check narrows them for
+   * each part by the capability rules of the kinds, as a run does.
+   */
   readonly caps?: readonly Cap[];
 }
 
+/**
+ * This function gives the reason of a `#CAP!`. When a kind around the document narrowed the capabilities, the
+ * reason names the nearest such kind.
+ */
+function capReason(v: DocVisit, kind: readonly Key[]): string {
+  const text = kind.join(".");
+  for (let up = v.parent; up !== undefined; up = up.parent) {
+    if (up.caps !== undefined && permits(up.caps, kind)) {
+      return `The capabilities do not permit the effect ${text} here. The kind ${typeName(up.doc.type)} around it narrows them for its parts.`;
+    }
+  }
+  return `The capabilities do not permit the effect ${text}.`;
+}
+
 /**
  * This function checks a document before an evaluation, by the contracts of its kinds. It finds the problems
  * that an evaluation finds when it reaches them:
@@ -301,7 +425,7 @@ export interface CheckOptions {
  * - `#DEPTH!`: too much nesting.
  * - `#REF!` and `#STEP?`: a bad path.
  * - `#NAME?`: a name that nothing binds.
- * - `#CAP!`: an effect that the capabilities do not permit.
+ * - `#CAP!`: an effect that the capabilities of its document do not permit. A kind around the document can narrow them.
  *
  * @param machine - The world and the code of the evaluators.
  * @param doc - The document, as JSON.
@@ -319,34 +443,41 @@ export function check(machine: Machine, doc: unknown, options: CheckOptions = {}
     doc,
     (v) => {
       if (v.depth > maxDepth) {
-        issues.push({ code: "#DEPTH!", place: v.place, reason: `The nesting is deeper than ${maxDepth} documents.` });
+        issues.push({ code: "#DEPTH!", place: v.place, reason: `The nesting is deeper than ${maxDepth} documents.`, at: v.at });
         return "skip";
       }
       const header = v.declared ? {} : v.doc;
       const answer = ask(machine.world, header, "eval", v.declared ? { declaredType: typeName(v.doc.type) } : {});
       if (answer.error === "unknown-kind") {
-        issues.push({ code: "#KIND?", place: v.place, reason: `The world has no kind ${typeName(v.doc.type)}.` });
+        issues.push({ code: "#KIND?", place: v.place, reason: `The world has no kind ${typeName(v.doc.type)}.`, at: v.at });
         return "skip";
       }
       const name = answer.evaluator;
       if (name === undefined || (!has(machine.evaluators, name) && !has(machine.runners, name))) {
-        issues.push({ code: "#NOEVAL", place: v.place, reason: `No rung gives an evaluator for ${typeName(v.doc.type)}.` });
+        issues.push({ code: "#NOEVAL", place: v.place, reason: `No rung gives an evaluator for ${typeName(v.doc.type)}.`, at: v.at });
       }
-      if (options.caps !== undefined && v.kind?.effects !== undefined) {
+      const caps = v.caps;
+      if (caps !== undefined && v.kind?.effects !== undefined) {
         const kinds: readonly (readonly Key[])[] = v.kind.effects === "type" ? [v.typePath ?? []] : v.kind.effects.map((kind) => kind.split("."));
         for (const kind of kinds) {
-          if (!permits(options.caps, kind)) issues.push({ code: "#CAP!", place: v.place, reason: `The capabilities do not permit the effect ${kind.join(".")}.` });
+          if (!permits(caps, kind)) issues.push({ code: "#CAP!", place: v.place, reason: capReason(v, kind), at: v.at });
         }
       }
-      if (!isRef(v.doc)) return undefined;
+      const isPath = isRef(v.doc);
+      if (!isPath && v.typePath?.length === 1 && v.typePath[0] === "ref") {
+        issues.push({ code: "#VALUE!", place: v.place, reason: "The value of ref is a path: a list that starts with a root.", at: [...v.at, ...(v.declared ? [] : ["value"])] });
+      }
+      if (!isPath) return undefined;
       const path = v.doc.value as readonly Json[];
       const root = path[0];
+      // The JSON path of a problem of a path goes to its step.
+      const stepAt = (index: number): readonly Key[] => [...v.at, "value", ...(index < path.length ? [index] : [])];
       if (typeof root !== "string" || !(ROOTS as readonly string[]).includes(root)) {
-        issues.push({ code: "#REF!", place: v.place, reason: `A path starts with a root: ${ROOTS.join(", ")}.` });
+        issues.push({ code: "#REF!", place: v.place, reason: `A path starts with a root: ${ROOTS.join(", ")}.`, at: stepAt(0) });
         return "skip";
       }
       if (!roots.includes(root)) {
-        issues.push({ code: "#REF!", place: v.place, reason: `The root ${root} is not open here. The open roots are ${roots.join(", ")}.` });
+        issues.push({ code: "#REF!", place: v.place, reason: `The root ${root} is not open here. The open roots are ${roots.join(", ")}.`, at: stepAt(0) });
       }
       const first = path[1];
       if (root === ("names" as Root) && !anyName && isKey(first) && !v.names.has(String(first))) {
@@ -355,22 +486,25 @@ export function check(machine: Machine, doc: unknown, options: CheckOptions = {}
           code: "#NAME?",
           place: v.place,
           reason: later ? `The name ${String(first)} is bound by a later step.` : `Nothing binds the name ${String(first)}.`,
+          at: stepAt(1),
         });
       }
-      path.slice(1).forEach((step) => {
-        if (isKey(step)) return;
+      path.forEach((step, index) => {
+        if (index === 0 || isKey(step)) return;
         const found = isEnvelope(step) ? lookupKind(machine.world, step.type) : undefined;
         const walker = found?.ok === true && Object.hasOwn(found.kind.verbs, "step") ? found.kind.verbs["step"] : undefined;
         if (walker === undefined || !has(machine.walkers, walker)) {
-          issues.push({ code: "#STEP?", place: v.place, reason: "A step is a key, or a document of a kind with the verb step." });
+          issues.push({ code: "#STEP?", place: v.place, reason: "A step is a key, or a document of a kind with the verb step.", at: stepAt(index) });
         }
       });
-      return "skip";
+      // The step documents of the path are parts when the kind ref has a deep shape. The walk checks them too.
+      return undefined;
     },
     {
       ...(options.declaredType === undefined ? {} : { declaredType: options.declaredType }),
       ...(Array.isArray(options.names) ? { names: options.names } : {}),
-      problem: (problem) => issues.push({ code: problem.code, place: problem.place, reason: problem.reason }),
+      ...(options.caps === undefined ? {} : { caps: options.caps }),
+      problem: (problem) => issues.push({ code: problem.code, place: problem.place, reason: problem.reason, at: problem.at }),
     },
   );
   return issues;

package/src/stdlib.ts

@@ -69,18 +69,21 @@ export const STD_WORLD: World = {
     pure: {
       verbs: { eval: "control.pure", view: "view.op" },
       parts: { shape: "list" },
+      caps: [{ rule: "mask" }],
       summary: "It evaluates its part without capabilities, thus an effect in it fails.",
     },
     log: {
       verbs: { eval: "effect.log", view: "view.op" },
       parts: { shape: "list", of: "text" },
       side: "run",
+      effects: ["log"],
       summary: "It writes the result of its part to the log. This is an effect.",
     },
     write: {
       verbs: { eval: "effect.write", view: "view.op" },
       parts: { shape: "record", fields: ["value"] },
       side: "run",
+      effects: ["write"],
       summary: "It writes the result of its part to the store, at its key. This is an effect.",
     },
   },
@@ -269,10 +272,11 @@ export const STD_RUNNERS: Readonly<Record<string, Runner>> = {
     }
     return ok(last);
   },
-  "control.pure": function* ({ parts, context }) {
+  // The contract of pure masks the capabilities of its part, and the kernel applies it. Thus the runner does not.
+  "control.pure": function* ({ parts }) {
     const only = parts[0];
     if (only === undefined) return fail("#VALUE!", "pure needs one part.");
-    return yield* only.evaluate({ ...context, caps: [] });
+    return yield* only.evaluate();
   },
   "control.if": function* ({ parts }) {
     const test = parts.find((part) => part.key === "test");

package/src/world.ts

@@ -1,4 +1,5 @@
 import { type Envelope, type Json, type Key, type TypeRef, field, isRecord, typePath } from "./doc.ts";
+import type { Cap } from "./deref.ts";
 
 /** The two sides of evaluation. `derive` is pure. `run` causes effects in order. */
 export type Side = "derive" | "run";
@@ -14,11 +15,16 @@ export type Side = "derive" | "run";
  * - `record`: the value is a record. Each named field has its shape. A list of names makes each named field a
  *   part. The other fields have the shape `rest` (the default is data). `required` names the fields that must be.
  * - `deep`: each envelope at any depth of the value is a part, and the rest is data.
+ * - `text`, `number` and `one`: the value is data of that type. `one` names the values that it permits.
+ *
+ * A `term` with `address: true` is an address: a reference there gives what its path reaches, not the value. A
+ * `term` with `kinds` permits only a part whose type starts with one of the paths. A `record` with `closed: true`
+ * permits only its named fields. A `list` with `distinct: true` permits no two equal items.
  */
 export type Shape =
   | { readonly shape: "none" }
-  | { readonly shape: "term"; readonly of?: string }
-  | { readonly shape: "list"; readonly of?: string; readonly item?: Shape }
+  | { readonly shape: "term"; readonly of?: string; readonly address?: boolean; readonly kinds?: readonly (readonly Key[])[] }
+  | { readonly shape: "list"; readonly of?: string; readonly item?: Shape; readonly distinct?: boolean }
   | { readonly shape: "map"; readonly of?: string; readonly item?: Shape }
   | {
       readonly shape: "record";
@@ -26,8 +32,12 @@ export type Shape =
       readonly of?: string;
       readonly required?: readonly string[];
       readonly rest?: Shape;
+      readonly closed?: boolean;
     }
-  | { readonly shape: "deep"; readonly of?: string };
+  | { readonly shape: "deep"; readonly of?: string }
+  | { readonly shape: "text" }
+  | { readonly shape: "number"; readonly whole?: boolean; readonly min?: number; readonly max?: number }
+  | { readonly shape: "one"; readonly values: readonly Json[] };
 
 /** The former name of `Shape`. */
 export type PartsSpec = Shape;
@@ -60,6 +70,22 @@ export interface ScopeRule {
   readonly sequential?: boolean;
 }
 
+/**
+ * A capability rule of a kind: what the kind gives some of its parts from the capabilities of its document. A rule
+ * only narrows. A part does not get a capability that its document does not have (CAP.NARROW).
+ *
+ * - `same`: the parts get the capabilities of the document. This is the default.
+ * - `mask`: the parts get no capabilities, as the part of `pure`.
+ * - `only`: the parts get only the effects that the capabilities of the document and the list `caps` both permit.
+ *
+ * `in` names the parts that the rule covers, as patterns of their paths in the value. The key `"*"` matches each
+ * key. A rule without `in` covers each part.
+ */
+export type CapsRule =
+  | { readonly rule: "same"; readonly in?: readonly (readonly Key[])[] }
+  | { readonly rule: "mask"; readonly in?: readonly (readonly Key[])[] }
+  | { readonly rule: "only"; readonly caps: readonly Cap[]; readonly in?: readonly (readonly Key[])[] };
+
 /** A kind gives the name of an evaluator for each verb, and the contract of its value. */
 export interface Kind {
   readonly verbs: Readonly<Record<string, string>>;
@@ -67,6 +93,13 @@ export interface Kind {
   readonly parts?: Shape;
   /** The names that the kind binds for its parts. */
   readonly scope?: readonly ScopeRule[];
+  /**
+   * The capabilities that the kind gives its parts, as rules. A part that no rule covers gets the capabilities of
+   * the document. A part that several rules cover gets only what each rule permits. The static kit reads the rules,
+   * and the kernel narrows the context of each part by them. Thus an evaluator does not narrow the capabilities
+   * itself.
+   */
+  readonly caps?: readonly CapsRule[];
   /** The side of the kind. A kind of the run side causes effects. The default is `derive`. */
   readonly side?: Side;
   /**
@@ -209,6 +242,9 @@ export function entriesAsJson(entries: Readonly<Record<string, WorldEntry>>): Js
 
 function describeShape(shape: Shape | undefined): Json {
   if (shape === undefined || shape.shape === "none") return "none";
+  if (shape.shape === "text") return "a text";
+  if (shape.shape === "number") return "a number";
+  if (shape.shape === "one") return `one of ${JSON.stringify(shape.values)}`;
   if (shape.shape === "term") return `a part${shape.of === undefined ? "" : ` of ${shape.of}`}`;
   if (shape.shape === "deep") return "each document in the value";
   if (shape.shape === "list") return `a list${shape.of === undefined ? "" : ` of ${shape.of}`}`;