@mark1russell7/layout-contract 0.2.16 → 0.2.17

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package",
   "name": "@mark1russell7/layout-contract",
-  "version": "0.2.16",
+  "version": "0.2.17",
   "description": "The shared contract of the packing and highways layout engines: the input and record formats, the turn rule, margins, tolerances and hard rules.",
   "keywords": [
     "layout",

package/src/measures.ts

@@ -1,4 +1,4 @@
-import { SHAPE_KIND_IDS, type ShapeKind } from "./shapes.ts";
+import { SHAPE_KIND_IDS, type ShapeBound, type ShapeKind } from "./shapes.ts";
 import { RECORD_EPS, RECORD_SCALE } from "./tolerance.ts";
 
 /** The direction of a measure: the side of the better values. */
@@ -32,6 +32,11 @@ export interface MeasureSpec<Id extends string = string> {
   readonly role?: "guard" | "change-guard" | "diagnostic" | "time";
   /** The shape kinds of the boxes that the measure supports. Without it, the measure supports only `rect`. `checkShapes` refuses the other kinds. */
   readonly shapes?: readonly ShapeKind[];
+  /**
+   * The kinds where the value is a bound of the true value, and its side. A kind is in `shapes` or in `bound.shapes`, not in the two lists.
+   * `checkShapes` refuses a bound kind by default and with `{ level: "safe" }`. With `{ level: "bound" }`, it accepts it. `docs/SHAPES.md` tells what a bound value proves for each `direction`.
+   */
+  readonly bound?: ShapeBound;
 }
 
 /** The id of a joint measure. `docs/JOINT-MEASURES.md` gives the definitions. */

package/src/shapes.ts

@@ -58,28 +58,60 @@ export interface ShapeSupport<Id extends string = string> {
    * Thus a safe count of 0 tells that the rule has no break. A kind is in `shapes` or in `safe`, not in the two lists.
    */
   readonly safe?: readonly ShapeKind[];
+  /**
+   * The kinds where the value of a measure is a bound of the true value, not the exact value. `ShapeBound` tells the side.
+   * A kind is in one list only: `shapes`, `safe` or `bound.shapes`. `docs/SHAPES.md` tells what a bound value proves.
+   */
+  readonly bound?: ShapeBound;
+}
+
+/**
+ * The kinds where a measure gives a bound of the true value, and the side of the bound.
+ * With `upper`, the value is the true value or more. With `lower`, the value is the true value or less.
+ */
+export interface ShapeBound {
+  readonly shapes: readonly ShapeKind[];
+  readonly side: "upper" | "lower";
 }
 
 /** The level of a rule on a shape kind: an exact count, a safe count (an upper bound), or no support. */
 export type RuleLevel = "exact" | "safe" | "none";
 
-/** This function gives the level of a rule on a shape kind. A kind of `shapesOf` is `exact`, a kind of `safe` is `safe`, and another kind is `none`. */
+/** This function gives the level of a rule on a shape kind. A kind of `shapesOf` is `exact`, a kind of `safe` is `safe`, and another kind is `none`. It does not read `bound`. */
 export function ruleLevel(rule: Pick<ShapeSupport, "shapes" | "safe">, kind: ShapeKind): RuleLevel {
   if (shapesOf(rule).includes(kind)) return "exact";
   return rule.safe?.includes(kind) === true ? "safe" : "none";
 }
 
+/** The level of a measure or a rule on a shape kind. The level `bound` is a value on one side of the true value (`ShapeBound`). */
+export type ShapeLevel = RuleLevel | "bound";
+
+/**
+ * This function gives the level of a measure or a rule on a shape kind. It joins the lists `shapes`, `safe` and `bound.shapes`.
+ * A kind of `shapesOf` is `exact`, a kind of `safe` is `safe`, a kind of `bound.shapes` is `bound`, and another kind is `none`.
+ */
+export function shapeLevel(use: Pick<ShapeSupport, "shapes" | "safe" | "bound">, kind: ShapeKind): ShapeLevel {
+  const level = ruleLevel(use, kind);
+  if (level !== "none") return level;
+  return use.bound?.shapes.includes(kind) === true ? "bound" : "none";
+}
+
 /**
  * This function gives the problems of a list of measures and rules. An empty list tells that the list is good.
- * It refuses an unknown kind, a kind two times in one list, and a kind in `safe` that is also in `shapesOf`.
+ * It refuses an unknown kind, a kind two times in one list, and a kind in more than one of `shapesOf`, `safe` and `bound.shapes`.
+ * It also refuses a `bound` without a list of kinds, and a `side` that is not `upper` or `lower`.
  */
 export function shapeSupportProblems(uses: readonly ShapeSupport[]): string[] {
   const out: string[] = [];
   for (const use of uses) {
-    for (const [name, list] of [["shapes", use.shapes], ["safe", use.safe]] as const) {
-      if (list === undefined) continue;
+    const bound: unknown = use.bound;
+    const isBound = typeof bound === "object" && bound !== null && !Array.isArray(bound);
+    if (bound !== undefined && !isBound) out.push(`${use.id}: the bound value is not an object with shapes and a side`);
+    const boundShapes = isBound ? (bound as { readonly shapes?: unknown }).shapes : undefined;
+    for (const [name, list] of [["shapes", use.shapes], ["safe", use.safe], ["bound", boundShapes]] as const) {
+      if (list === undefined && (name !== "bound" || !isBound)) continue;
       if (!Array.isArray(list)) {
-        out.push(`${use.id}: the ${name} value is not a list of shape kinds`);
+        out.push(`${use.id}: the ${name === "bound" ? "bound shapes" : name} value is not a list of shape kinds`);
         continue;
       }
       list.forEach((k: unknown, i) => {
@@ -87,9 +119,17 @@ export function shapeSupportProblems(uses: readonly ShapeSupport[]): string[] {
         else if (list.indexOf(k) !== i) out.push(`${use.id}: the ${name} list has the kind ${k} two times`);
       });
     }
-    if (!Array.isArray(use.safe)) continue;
     const exact: readonly unknown[] = use.shapes === undefined ? DEFAULT_SHAPES : Array.isArray(use.shapes) ? use.shapes : [];
-    for (const k of new Set<unknown>(use.safe)) if (exact.includes(k)) out.push(`${use.id}: the kind ${String(k)} is in shapes and in safe`);
+    if (Array.isArray(use.safe)) for (const k of new Set<unknown>(use.safe)) if (exact.includes(k)) out.push(`${use.id}: the kind ${String(k)} is in shapes and in safe`);
+    if (!isBound) continue;
+    const side: unknown = (bound as { readonly side?: unknown }).side;
+    if (side !== "upper" && side !== "lower") out.push(`${use.id}: the bound side ${String(side)} is not upper or lower`);
+    if (!Array.isArray(boundShapes)) continue;
+    const safe: readonly unknown[] = Array.isArray(use.safe) ? use.safe : [];
+    for (const k of new Set<unknown>(boundShapes)) {
+      if (exact.includes(k)) out.push(`${use.id}: the kind ${String(k)} is in shapes and in bound`);
+      if (safe.includes(k)) out.push(`${use.id}: the kind ${String(k)} is in safe and in bound`);
+    }
   }
   return out;
 }
@@ -154,16 +194,18 @@ export function shapesOf(use: Pick<ShapeSupport, "shapes">): readonly ShapeKind[
 /** The options of `checkShapes`. */
 export interface ShapeCheck {
   /**
-   * The lowest level of a rule that `checkShapes` accepts. The default `exact` refuses a kind with only a safe count.
-   * The value `safe` also accepts a kind of `safe`. Use it only when the run claims that a rule has no break.
+   * The lowest level that `checkShapes` accepts. The default `exact` refuses a kind with only a safe count or a bound value.
+   * The value `safe` also accepts a kind of `safe`, as in 0.2.16. Use it only when the run claims that a rule has no break.
+   * The value `bound` also accepts a kind of `safe` and a kind of `bound.shapes`. Use it only when the run reads each bound value for the proofs of its side (`docs/SHAPES.md`).
    */
-  readonly level?: "exact" | "safe";
+  readonly level?: "exact" | "safe" | "bound";
 }
 
 /**
  * This function checks that each measure and each rule of a run supports each shape kind of the input. An empty list tells that the run is good.
  * Each break has the claim `shape`, the id of the input, and the first 5 ids of the boxes of the kind.
- * By default, a kind of `safe` is a break, because the count of the rule is not exact. With the level `safe`, it is not a break.
+ * By default, a kind of `safe` or of `bound.shapes` is a break, because the result is not exact.
+ * With the level `safe`, a kind of `safe` is not a break. With the level `bound`, a kind of `safe` and a kind of `bound.shapes` are not a break.
  */
 export function checkShapes(input: Pick<LayoutInput, "id" | "boxes">, uses: readonly ShapeSupport[], options: ShapeCheck = {}): ClaimBreak[] {
   const kinds = shapeKindsOf(input);
@@ -171,11 +213,13 @@ export function checkShapes(input: Pick<LayoutInput, "id" | "boxes">, uses: read
   for (const use of uses) {
     const shapes = shapesOf(use);
     for (const kind of kinds) {
-      const level = ruleLevel(use, kind);
-      if (level === "exact" || (level === "safe" && options.level === "safe")) continue;
+      const level = shapeLevel(use, kind);
+      const accepts = level === "exact" || (level === "safe" && (options.level === "safe" || options.level === "bound")) || (level === "bound" && options.level === "bound");
+      if (accepts) continue;
       const ids = input.boxes.filter((b) => shapeKindOf(b) === kind).map((b) => b.id);
       const shown = ids.slice(0, 5).join(", ") + (ids.length > 5 ? `, and ${ids.length - 5} more` : "");
-      const safe = level === "safe" ? `. The count of ${use.id} on ${kind} is only safe` : "";
+      const safe =
+        level === "safe" ? `. The count of ${use.id} on ${kind} is only safe` : level === "bound" ? `. The value of ${use.id} is only ${use.bound!.side === "upper" ? "an upper" : "a lower"} bound for ${kind}` : "";
       out.push({
         claim: "shape",
         detail: `${use.id} supports only the shape kinds ${shapes.join(", ") || "(none)"}, but the input ${input.id} has ${kind} boxes: ${shown}${safe}`,

package/src/strategy-space.ts

@@ -813,6 +813,40 @@ function restrict(space: StrategySpace, shapes: readonly ShapeKind[] | undefined
 /** The space of the members of a meta option of a restricted space, when it is not the part of the option. Only `view: "bounds"` makes such a space. */
 const memberSpaces = new WeakMap<StageOption, StrategySpace>();
 
+/**
+ * This function tells if an option of a restricted space has a member list. A base option and a meta option with a `pool` have one.
+ * A different meta option has one when its members have a base config. `restrict` keeps only the pool entries that fit.
+ */
+const hasMembers = (space: StrategySpace, stage: string, o: StageOption): boolean =>
+  o.members === undefined || o.members.pool !== undefined || combos(memberSpaces.get(o) ?? partOf(space, stage).space, 1, false, 0n).length > 0;
+
+/** This function tells if a restricted space has a config. A base config counts. With `meta`, a meta config counts when each of its meta options has a member list. */
+const hasConfig = (space: StrategySpace, meta: boolean): boolean =>
+  combos(space, 1, meta, 0n).some((c) => c.base || [...c.choices].every(([stage, o]) => o === null || hasMembers(space, stage, o)));
+
+/** This function gives the error of a sample of a space that has no config for the shape kinds `shapes`. `kept` is the restricted space. */
+function noSample(space: StrategySpace, kept: StrategySpace, shapes: readonly ShapeKind[], meta: boolean): RangeError {
+  const list = (names: readonly string[], one: string, more: string): string => (names.length === 1 ? `${one} ${names[0]}` : `${more} ${names.join(", ")}`);
+  const empty = kept.stages.filter((s) => !s.optional && !s.options.some((o) => meta || o.members === undefined)).map((s) => s.name);
+  const removed = !meta
+    ? []
+    : space.stages.flatMap((s) =>
+        s.options
+          .filter((o) => o.members !== undefined && o.members.view !== "bounds" && supportsShapes(o, shapes))
+          .filter((o) => {
+            const own = kept.stages.find((x) => x.name === s.name)?.options.find((x) => x.id === o.id);
+            return own === undefined || !hasMembers(kept, s.name, own);
+          })
+          .map((o) => `${s.name}.${o.id}`),
+      );
+  let text = `The space ${space.engine} has no config for a sample with the shape kinds ${shapes.join(", ")}.`;
+  if (empty.length > 0) text += ` ${list(empty, "The stage", "The stages")} ${empty.length === 1 ? "has" : "have"} no option for these kinds.`;
+  if (removed.length > 0)
+    text += ` ${list(removed, "The meta option", "The meta options")} ${removed.length === 1 ? "has" : "have"} no member config for these kinds. Set members.view to "bounds" when the members see only the bounding boxes.`;
+  if (empty.length === 0 && removed.length === 0) text += " The constraints remove each config.";
+  return new RangeError(text);
+}
+
 /** This function gives the count of the base configs of a space that is known to be good. */
 const baseCount = (space: StrategySpace, levels: number, limit: bigint): bigint => combos(space, levels, false, limit).reduce((sum, c) => sum + c.weight!, 0n);
 
@@ -908,6 +942,13 @@ function sampleConfigs(space: StrategySpace, n: number, seed: number, meta: bool
     if (list.length === 0) throw new Error(`The stage ${s.name} of the space ${space.engine} has no option for a sample. A shape filter can remove all of its options.`);
     return list;
   });
+  // A meta option without a member list stays in its list, so the strata of 0.2.16 do not change. A point that chooses it draws again.
+  const usable = new Map<StageOption, boolean>();
+  const withMembers = (s: SpaceStage, o: StageOption | null | undefined): boolean => {
+    if (o === null || o === undefined || o.members === undefined) return true;
+    if (!usable.has(o)) usable.set(o, hasMembers(space, s.name, o));
+    return usable.get(o)!;
+  };
   const points: Map<string, StageOption | null>[] = [];
   let tries = 0;
   for (let round = 0; points.length < n; round++) {
@@ -927,7 +968,7 @@ function sampleConfigs(space: StrategySpace, n: number, seed: number, meta: bool
         if (m !== undefined && m !== s.name) choices.set(s.name, null);
       }
       const filled = stages.every((s) => s.optional === true || choices.get(s.name) !== null || metaPart.has(prefix.get(s.name)!));
-      if (filled && keeps(space, choices)) points.push(choices);
+      if (filled && keeps(space, choices) && stages.every((s) => withMembers(s, choices.get(s.name)))) points.push(choices);
     }
   }
   const values: Values[][] = points.map(() => stages.map(() => ({})));
@@ -987,6 +1028,8 @@ function sampleConfigs(space: StrategySpace, n: number, seed: number, meta: bool
  * - A sample draws again when a point breaks a constraint. After `maxTries` draws, it throws an `Error`. Two sampled configs can be equal.
  * - With `shapes`, only the options that support each kind of the list count. Without `shapes`, the result does not change.
  * - A meta option with a `pool` gives only the entries of its pool. With `shapes`, only the entries whose members support each kind count.
+ * - A sample draws again when a point chooses a meta option without a member list. `spaceSize` gives such an option 0.
+ * - With `shapes`, a sample throws a `RangeError` when the space has no config for the kinds. The error names the stages without an option and the meta options without members.
  */
 export function enumerateSpace(space: StrategySpace, options: EnumerateOptions): StrategyConfig[] {
   assertSpace(space);
@@ -1001,7 +1044,14 @@ export function enumerateSpace(space: StrategySpace, options: EnumerateOptions):
   const meta = options.meta ?? "skip";
   if (meta !== "skip" && meta !== "sample") throw new RangeError(`The option meta is ${String(meta)}, not skip or sample.`);
   if (options.n === 0) return [];
-  return sampleConfigs(restrict(space, options.shapes), options.n, options.seed, meta === "sample", options.maxTries ?? Math.max(1000, 100 * options.n), space);
+  const kept = restrict(space, options.shapes);
+  try {
+    return sampleConfigs(kept, options.n, options.seed, meta === "sample", options.maxTries ?? Math.max(1000, 100 * options.n), space);
+  } catch (error) {
+    // Only a space without a config for the shape kinds gives the RangeError. A different failure keeps its own error.
+    if (options.shapes !== undefined && !hasConfig(kept, meta === "sample")) throw noSample(space, kept, options.shapes, meta === "sample");
+    throw error;
+  }
 }
 
 /**