@mark1russell7/layout-contract 0.2.14 → 0.2.16

package/src/shapes.ts

@@ -1,6 +1,6 @@
 // The shape kinds of the items (`docs/SHAPES.md`): the declared set, the kind of a box and the check of the measures and rules on a run.
 import type { ClaimBreak } from "./corpus.ts";
-import type { Region } from "./geometry.ts";
+import { regionArea, type Region } from "./geometry.ts";
 import type { LayoutBox, LayoutInput } from "./input.ts";
 
 /**
@@ -13,7 +13,7 @@ export type ShapeKind = "rect" | "polygon" | "circle" | "free";
 export interface ShapeGeometry {
   /** The bounding box: `boundsOf` and `placedRect`. */
   readonly bounds: boolean;
-  /** The area of the shape. */
+  /** The area of the shape: `regionArea` and `boxArea`. */
   readonly area: boolean;
   /** The test that the shape is inside a region: `rectInRegion` for a `rect`. */
   readonly contains: boolean;
@@ -31,11 +31,14 @@ export interface ShapeKindSpec {
   readonly geometry: ShapeGeometry;
 }
 
-/** The declared shape kinds, in their order. Only `rect` has all of its geometry. The other kinds have their bounding box only. */
+/**
+ * The declared shape kinds, in their order. Only `rect` has all of its geometry.
+ * `polygon` and `circle` have their bounding box and their exact area. `free` has its bounding box only.
+ */
 export const SHAPE_KINDS: readonly ShapeKindSpec[] = Object.freeze([
   { id: "rect", fields: ["w", "h"], regions: ["rect"], geometry: { bounds: true, area: true, contains: true, overlap: true } },
-  { id: "polygon", fields: ["points", "holes?"], regions: ["polygon"], geometry: { bounds: true, area: false, contains: false, overlap: false } },
-  { id: "circle", fields: ["cx", "cy", "r"], regions: ["circle"], geometry: { bounds: true, area: false, contains: false, overlap: false } },
+  { id: "polygon", fields: ["points", "holes?"], regions: ["polygon"], geometry: { bounds: true, area: true, contains: false, overlap: false } },
+  { id: "circle", fields: ["cx", "cy", "r"], regions: ["circle"], geometry: { bounds: true, area: true, contains: false, overlap: false } },
   { id: "free", fields: ["w", "h", "shape?"], regions: ["rect", "polygon", "circle", "ellipse"], geometry: { bounds: true, area: false, contains: false, overlap: false } },
 ] as const);
 
@@ -48,7 +51,47 @@ export const DEFAULT_SHAPES: readonly ShapeKind[] = Object.freeze(["rect"] as co
 /** A measure or a rule, with the shape kinds that it supports. Without `shapes`, it supports `DEFAULT_SHAPES`. */
 export interface ShapeSupport<Id extends string = string> {
   readonly id: Id;
+  /** The kinds with an exact count or value. */
   readonly shapes?: readonly ShapeKind[];
+  /**
+   * The kinds with a safe count: the rule can count a break that is not real, but it does not miss a real break.
+   * 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 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`. */
+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";
+}
+
+/**
+ * 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`.
+ */
+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;
+      if (!Array.isArray(list)) {
+        out.push(`${use.id}: the ${name} value is not a list of shape kinds`);
+        continue;
+      }
+      list.forEach((k: unknown, i) => {
+        if (!isShapeKind(k)) out.push(`${use.id}: the ${name} kind ${String(k)} is not a declared kind`);
+        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`);
+  }
+  return out;
 }
 
 const REGION_KIND: Readonly<Record<Region["kind"], ShapeKind>> = { rect: "rect", polygon: "polygon", circle: "circle", ellipse: "free" };
@@ -67,6 +110,19 @@ export function shapeKindOf(box: LayoutBox): ShapeKind {
   return box.shape === undefined ? "rect" : REGION_KIND[box.shape.kind];
 }
 
+/**
+ * This function gives the exact area of a box, or `undefined` when the contract knows only its bounding box.
+ * A box with `shape` gives `regionArea` of the shape. A `rect` box without `shape` gives `w` by `h`.
+ * A box of the kind `free` gives `undefined`, also with a shape. Thus a box with an ellipse shape gives `undefined`, because `shapeKindOf` makes an ellipse `free`.
+ * A box of another kind without `shape` is a bad input, and gives `undefined`.
+ */
+export function boxArea(box: LayoutBox): number | undefined {
+  const kind = shapeKindOf(box);
+  if (kind === "free") return undefined;
+  if (box.shape !== undefined) return regionArea(box.shape);
+  return kind === "rect" ? box.w * box.h : undefined;
+}
+
 /** This function gives the shape kinds of the boxes of an input, in the order of `SHAPE_KINDS`. An input without boxes gives an empty list. */
 export function shapeKindsOf(input: Pick<LayoutInput, "boxes">): ShapeKind[] {
   const seen = new Set(input.boxes.map(shapeKindOf));
@@ -95,22 +151,34 @@ export function shapesOf(use: Pick<ShapeSupport, "shapes">): readonly ShapeKind[
   return use.shapes ?? DEFAULT_SHAPES;
 }
 
+/** 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.
+   */
+  readonly level?: "exact" | "safe";
+}
+
 /**
  * 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.
  */
-export function checkShapes(input: Pick<LayoutInput, "id" | "boxes">, uses: readonly ShapeSupport[]): ClaimBreak[] {
+export function checkShapes(input: Pick<LayoutInput, "id" | "boxes">, uses: readonly ShapeSupport[], options: ShapeCheck = {}): ClaimBreak[] {
   const kinds = shapeKindsOf(input);
   const out: ClaimBreak[] = [];
   for (const use of uses) {
     const shapes = shapesOf(use);
     for (const kind of kinds) {
-      if (shapes.includes(kind)) continue;
+      const level = ruleLevel(use, kind);
+      if (level === "exact" || (level === "safe" && options.level === "safe")) 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` : "";
       out.push({
         claim: "shape",
-        detail: `${use.id} supports only the shape kinds ${shapes.join(", ") || "(none)"}, but the input ${input.id} has ${kind} boxes: ${shown}`,
+        detail: `${use.id} supports only the shape kinds ${shapes.join(", ") || "(none)"}, but the input ${input.id} has ${kind} boxes: ${shown}${safe}`,
         inputs: [input.id],
       });
     }

package/src/strategy-space.ts

@@ -52,6 +52,11 @@ export interface MemberRule {
    * With `pool`, a config of the option has the members of one entry, and `spaceSize` counts each entry one time.
    */
   readonly pool?: readonly (readonly StrategyConfig[])[];
+  /**
+   * The view of the items that the members get. With `bounds`, the option gives its members the bounding box of each item.
+   * Then a shape filter checks the members with the kind `rect`, and the option itself with the kinds of the input. Without `view`, the members get the kinds of the input.
+   */
+  readonly view?: "bounds";
 }
 
 /** The inputs that an option supports. A missing field supports each value. */
@@ -315,6 +320,8 @@ function optionProblems(stage: SpaceStage, o: StageOption): Problem[] {
     const pool: unknown = o.members.pool;
     if (pool !== undefined && (!Array.isArray(pool) || pool.length === 0 || !pool.every((entry: unknown) => Array.isArray(entry))))
       out.push(["pool", `${at} has a pool that is not a list of one or more member lists`]);
+    const view: unknown = o.members.view;
+    if (view !== undefined && view !== "bounds") out.push(["view", `${at} has the member view ${show(view)}, not "bounds"`]);
   }
   return out;
 }
@@ -337,6 +344,19 @@ function supportsProblems(supports: unknown, at: string): Problem[] {
 const supportsShapes = (o: StageOption, shapes: readonly ShapeKind[] | undefined): boolean =>
   shapes === undefined || o.supports?.shape === undefined || shapes.every((k) => o.supports!.shape!.includes(k));
 
+/** The shape kinds that the members of an option with `view: "bounds"` see: a bounding box is a `rect`. */
+const BOUNDS_VIEW: readonly ShapeKind[] = Object.freeze(["rect"] as const);
+
+/**
+ * This function gives the shape kinds of the members of a meta option. With `view: "bounds"`, a list with a kind becomes `BOUNDS_VIEW`.
+ * Without a list, or with an empty list, the value does not change.
+ */
+const memberShapes = (rule: MemberRule, shapes: readonly ShapeKind[] | undefined): readonly ShapeKind[] | undefined =>
+  rule.view === "bounds" && shapes !== undefined && shapes.length > 0 ? BOUNDS_VIEW : shapes;
+
+/** This function tells if two lists have the same shape kinds. */
+const sameKinds = (a: readonly ShapeKind[], b: readonly ShapeKind[]): boolean => a.every((k) => b.includes(k)) && b.every((k) => a.includes(k));
+
 /** This function gives the problems of the params of one stage choice. */
 function choiceParamProblems(o: StageOption, params: unknown, at: string): Problem[] {
   if (params !== undefined && !isObject(params)) return [["config", `the params of ${at} are not an object`]];
@@ -411,7 +431,7 @@ function configProblems(space: StrategySpace, config: unknown, member: boolean,
       out.push(["depth", `a member has the meta option ${s.name}.${o.id}. The depth of a meta config is 1`]);
       continue;
     }
-    out.push(...memberProblems(partOf(space, s.name).space, o.members, c["members"], at, shapes));
+    out.push(...memberProblems(partOf(space, s.name).space, o.members, c["members"], at, memberShapes(o.members, shapes)));
   }
   for (const c of space.constraints ?? []) if (!holds(c, chosen)) out.push(["constraint", `the config breaks the constraint ${describe(c)}`]);
   return out;
@@ -473,6 +493,7 @@ const toBreaks = (problems: readonly Problem[], inputs: readonly string[] = []):
  *
  * A member list that is not an entry of the `pool` of its option gives the claim `pool`.
  * With `shapes`, an option that does not support a kind of the list gives the claim `shape`. A member of a meta option gets the same check.
+ * A member of an option with `view: "bounds"` gets the check with the kind `rect`.
  */
 export function checkConfig(space: StrategySpace, config: StrategyConfig, options: ShapeFilter = {}): ClaimBreak[] {
   return toBreaks(configProblems(space, config, false, options.shapes));
@@ -738,7 +759,9 @@ function combos(space: StrategySpace, levels: number, meta: boolean, limit: bigi
     for (const o of s.options) {
       if (o.members === undefined) continue;
       const choices = new Map<string, StageOption | null>(stages.map((x) => [x.name, x === s ? o : null]));
-      const lists = o.members.pool === undefined ? memberLists(base, o.members, limit) : BigInt(o.members.pool.length);
+      const own = memberSpaces.get(o);
+      const from = own === undefined ? base : baseCount(own, levels, limit);
+      const lists = o.members.pool === undefined ? memberLists(from, o.members, limit) : BigInt(o.members.pool.length);
       if (keeps(space, choices)) out.push({ choices, base: false, weight: times(countOf(o), lists, limit) });
     }
   return out;
@@ -761,6 +784,8 @@ export function spaceSize(space: StrategySpace, options: SpaceSizeOptions): Spac
  * This function gives the space with only the options that support each shape kind of `shapes`. Without `shapes`, it gives the same space.
  * A stage can lose all of its options. Then the space has no config with that stage.
  * A pool keeps only the entries whose members fit the smaller space. A meta option without such an entry goes out.
+ *
+ * The members of an option with `view: "bounds"` come from the space for the kinds of `memberShapes`. `memberSpaces` keeps that space.
  */
 function restrict(space: StrategySpace, shapes: readonly ShapeKind[] | undefined): StrategySpace {
   if (shapes === undefined) return space;
@@ -770,14 +795,27 @@ function restrict(space: StrategySpace, shapes: readonly ShapeKind[] | undefined
     ...(space.parts === undefined ? {} : { parts: space.parts.map((p) => restrict(p, shapes)) }),
   };
   const withPool = (s: SpaceStage, o: StageOption): StageOption[] => {
-    if (o.members?.pool === undefined) return [o];
-    const part = partOf(kept, s.name).space;
+    if (o.members === undefined) return [o];
+    const inner = memberShapes(o.members, shapes)!;
+    const own = sameKinds(inner, shapes) ? undefined : restrict(partOf(space, s.name).space, inner);
+    const mark = (option: StageOption): StageOption[] => {
+      if (own !== undefined) memberSpaces.set(option, own);
+      return [option];
+    };
+    if (o.members.pool === undefined) return own === undefined ? [o] : mark({ ...o });
+    const part = own ?? partOf(kept, s.name).space;
     const pool = o.members.pool.filter((entry) => fits(part, entry));
-    return pool.length === 0 ? [] : [{ ...o, members: { ...o.members, pool } }];
+    return pool.length === 0 ? [] : mark({ ...o, members: { ...o.members, pool } });
   };
   return { ...kept, stages: kept.stages.map((s) => ({ ...s, options: s.options.flatMap((o) => withPool(s, o)) })) };
 }
 
+/** 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 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);
+
 /** This function throws a `RangeError` for a list of shape kinds with a kind that is not declared. */
 function assertShapes(shapes: readonly ShapeKind[] | undefined): void {
   if (shapes === undefined) return;
@@ -854,13 +892,19 @@ function sampleValue(p: SpaceParam, u: number): ParamValue {
 /** This function gives a seed of 32 bits from a seed and a step name. */
 const subSeed = (seed: number, step: string): number => Math.floor(stepRandom(seed, step)() * 4294967296);
 
-/** This function gives a sample of a space: Latin hypercube strata over the options, the params and the member counts. */
-function sampleConfigs(space: StrategySpace, n: number, seed: number, meta: boolean, maxTries: number): StrategyConfig[] {
+/**
+ * This function gives a sample of a space: Latin hypercube strata over the options, the params and the member counts.
+ * `canon` is the space of `canonicalConfig`: the space before a shape filter. A member of an option with `view: "bounds"` can have an option that the filter removed.
+ */
+function sampleConfigs(space: StrategySpace, n: number, seed: number, meta: boolean, maxTries: number, canon: StrategySpace = space): StrategyConfig[] {
   const stages = space.stages;
   const prefix = prefixes(space);
+  // A stage without options can stay empty in a part with a meta option of `view: "bounds"`, because that option replaces the stage.
+  const bounded = new Set(stages.filter((s) => meta && s.options.some((o) => memberSpaces.has(o))).map((s) => prefix.get(s.name)!));
   const lists = stages.map((s) => {
     const list: (StageOption | null)[] = s.options.filter((o) => meta || o.members === undefined);
     if (s.optional) list.push(null);
+    if (list.length === 0 && bounded.has(prefix.get(s.name)!)) list.push(null);
     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;
   });
@@ -882,7 +926,8 @@ function sampleConfigs(space: StrategySpace, n: number, seed: number, meta: bool
         const m = metaPart.get(prefix.get(s.name)!);
         if (m !== undefined && m !== s.name) choices.set(s.name, null);
       }
-      if (keeps(space, choices)) points.push(choices);
+      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);
     }
   }
   const values: Values[][] = points.map(() => stages.map(() => ({})));
@@ -907,7 +952,7 @@ function sampleConfigs(space: StrategySpace, n: number, seed: number, meta: bool
         });
         continue;
       }
-      const part = partOf(space, s.name).space;
+      const part = memberSpaces.get(o) ?? partOf(space, s.name).space;
       const poolSize = Math.max(n, 4 * o.members.max, 8);
       const seen = new Set<string>();
       const pool = sampleConfigs(part, poolSize, subSeed(seed, `pool:${s.name}:${o.id}`), false, Math.max(1000, 100 * poolSize)).filter((c) => {
@@ -930,7 +975,7 @@ function sampleConfigs(space: StrategySpace, n: number, seed: number, meta: bool
       const o = choices.get(s.name)!;
       out[s.name] = o === null ? null : o.members === undefined ? { option: o.id, params: values[i]![k]! } : { option: o.id, params: values[i]![k]!, members: members[i]![k]! };
     });
-    return canonicalConfig(space, { space: space.engine, stages: out });
+    return canonicalConfig(canon, { space: space.engine, stages: out });
   });
 }
 
@@ -956,7 +1001,7 @@ 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));
+  return sampleConfigs(restrict(space, options.shapes), options.n, options.seed, meta === "sample", options.maxTries ?? Math.max(1000, 100 * options.n), space);
 }
 
 /**

package/src/turn.ts

@@ -18,14 +18,20 @@ export function turnPoint(x: number, y: number, h: number): [number, number] {
   return [h - y, x];
 }
 
-/** This function gives a port of a box of height `h` after the turn. Each value of the port turns, also a port with only `x` or only `y`. */
+/**
+ * This function gives a port of a box of height `h` after the turn. Each value of the port turns, also a port with only `x` or only `y`.
+ * The start of a side is its top end or its left end. Thus `left` goes to `top` and `right` goes to `bottom` with `along` changed to `1 - along`.
+ * `top` goes to `right` and `bottom` goes to `left` with the same `along`.
+ */
 export function turnPort(port: Port, h: number): Port {
-  const { side, x, y, ...rest } = port;
+  const { side, x, y, along, ...rest } = port;
+  const flips = side === "left" || side === "right";
   return {
     ...rest,
     ...(side === undefined ? {} : { side: turnSide(side) }),
     ...(y === undefined ? {} : { x: h - y }),
     ...(x === undefined ? {} : { y: x }),
+    ...(along === undefined ? {} : { along: flips ? 1 - along : along }),
   };
 }