@mark1russell7/layout-contract 0.2.12 → 0.2.14

package/src/strategy-space.ts

@@ -2,6 +2,7 @@
 import type { ClaimBreak } from "./corpus.ts";
 import { canonicalJson, sha256Hex } from "./hash.ts";
 import { stepRandom } from "./random.ts";
+import { isShapeKind, SHAPE_KIND_IDS, type ShapeKind } from "./shapes.ts";
 
 /** The schema of a strategy space. */
 export const STRATEGY_SPACE_SCHEMA = "strategy-space/1";
@@ -45,6 +46,18 @@ export interface MemberRule {
   readonly min: number;
   readonly max: number;
   readonly ordered: boolean;
+  /**
+   * The member lists that the option permits. Each entry is a list of whole configs of the space of the members.
+   * Without `pool`, each list of base configs with a good count is a member list.
+   * 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 inputs that an option supports. A missing field supports each value. */
+export interface OptionSupports {
+  /** The shape kinds of the boxes (`docs/SHAPES.md`). Without it, the option supports each kind. */
+  readonly shape?: readonly ShapeKind[];
 }
 
 /** One implementation of a stage. An option with `members` is a meta option: it chooses between whole configs, or wraps them. */
@@ -52,6 +65,14 @@ export interface StageOption {
   readonly id: string;
   readonly params: readonly SpaceParam[];
   readonly members?: MemberRule;
+  /** The inputs that the option supports. It describes the option, so it is not part of a config or of its id. */
+  readonly supports?: OptionSupports;
+}
+
+/** The shape kinds of the inputs of a check, a count or an enumeration. Without `shapes`, each option counts. */
+export interface ShapeFilter {
+  /** The shape kinds of the input. Only the options that support each of these kinds count. */
+  readonly shapes?: readonly ShapeKind[];
 }
 
 /** One stage of the pipeline of an engine. A config of an `optional` stage can have no option. */
@@ -113,7 +134,7 @@ export interface SpaceSize {
 }
 
 /** The options of `spaceSize`. */
-export interface SpaceSizeOptions {
+export interface SpaceSizeOptions extends ShapeFilter {
   /** The count of the levels of each numeric param, a whole number of 1 or more. */
   readonly levels: number;
   /** The largest meta count that `spaceSize` gives. The default is `10n ** 18n`. */
@@ -121,7 +142,7 @@ export interface SpaceSizeOptions {
 }
 
 /** The options of a grid. The grid gives only the configs without a meta option. */
-export interface GridOptions {
+export interface GridOptions extends ShapeFilter {
   readonly mode: "grid";
   readonly levels: number;
   /** The largest count of configs. A larger grid causes a `RangeError`. The default is 100000. */
@@ -129,12 +150,12 @@ export interface GridOptions {
 }
 
 /** The options of a sample. */
-export interface SampleOptions {
+export interface SampleOptions extends ShapeFilter {
   readonly mode: "sample";
   /** The count of the configs, a whole number of 0 or more. */
   readonly n: number;
   readonly seed: number;
-  /** With `skip` (the default), the sample has no meta option. With `sample`, a meta option draws its members from base samples. */
+  /** With `skip` (the default), the sample has no meta option. With `sample`, a meta option draws its members from base samples, or one entry of its `pool`. */
   readonly meta?: "skip" | "sample";
   /** The largest count of option draws. The default is the larger value of 1000 and `100 * n`. */
   readonly maxTries?: number;
@@ -189,6 +210,21 @@ function isActive(p: SpaceParam, values: Values): boolean {
   return p.when.in.some((x) => x === v);
 }
 
+/** This function gives the problem of a value of a param, or `undefined` for a value in its range. The corpus dimensions of `families.ts` use it. */
+export function paramProblem(param: SpaceParam, value: unknown): string | undefined {
+  return valueProblem(param, value);
+}
+
+/** This function tells if a param is active for the values of the earlier params. A param without `when` is always active. */
+export function paramActive(param: SpaceParam, values: Readonly<Record<string, ParamValue>>): boolean {
+  return isActive(param, values);
+}
+
+/** This function gives the stable form of a value of a param: a real number gets 12 significant digits, and `-0` becomes `0`. */
+export function paramValue(param: SpaceParam, value: ParamValue): ParamValue {
+  return normalize(param, value);
+}
+
 /** This function gives the part of a space that has a stage, and the prefix of the names of its stages. */
 function partOf(space: StrategySpace, stage: string): { readonly space: StrategySpace; readonly prefix: string } {
   for (const part of space.parts ?? []) {
@@ -271,14 +307,36 @@ function optionProblems(stage: SpaceStage, o: StageOption): Problem[] {
       if (problem !== undefined) out.push(["when", `${pat} has a when value that is not a value of ${p.when.param}: ${problem}`]);
     }
   });
+  if (o.supports !== undefined) out.push(...supportsProblems(o.supports, at));
   if (o.members !== undefined) {
     const { min, max, ordered } = o.members;
     if (!Number.isInteger(min) || !Number.isInteger(max) || min < 1 || min > max || typeof ordered !== "boolean")
       out.push(["members", `${at} has a member rule without whole counts 1 <= min <= max and a boolean ordered`]);
+    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`]);
   }
   return out;
 }
 
+/** This function gives the problems of the `supports` of an option. */
+function supportsProblems(supports: unknown, at: string): Problem[] {
+  if (!isObject(supports)) return [["shape", `the supports of ${at} are not an object`]];
+  const shape = supports["shape"];
+  if (shape === undefined) return [];
+  if (!Array.isArray(shape) || shape.length === 0) return [["shape", `${at} supports no shape kind. Remove shape to support each kind`]];
+  const out: Problem[] = [];
+  shape.forEach((k: unknown, i) => {
+    if (!isShapeKind(k)) out.push(["shape", `${at} supports the shape kind ${show(k)}, which is not one of ${SHAPE_KIND_IDS.join(", ")}`]);
+    else if (shape.indexOf(k) !== i) out.push(["duplicate", `${at} has the shape kind ${k} two times`]);
+  });
+  return out;
+}
+
+/** This function tells if an option supports each shape kind of the list. */
+const supportsShapes = (o: StageOption, shapes: readonly ShapeKind[] | undefined): boolean =>
+  shapes === undefined || o.supports?.shape === undefined || shapes.every((k) => o.supports!.shape!.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`]];
@@ -301,7 +359,7 @@ function choiceParamProblems(o: StageOption, params: unknown, at: string): Probl
 }
 
 /** This function gives the problems of a config of a space. A member of a meta option has `member: true`. */
-function configProblems(space: StrategySpace, config: unknown, member: boolean): Problem[] {
+function configProblems(space: StrategySpace, config: unknown, member: boolean, shapes?: readonly ShapeKind[]): Problem[] {
   if (!isObject(config) || !isObject(config["stages"])) return [["config", "the config is not an object with stages"]];
   const out: Problem[] = [];
   const stages = config["stages"];
@@ -339,6 +397,10 @@ function configProblems(space: StrategySpace, config: unknown, member: boolean):
     }
     chosen.set(s.name, o.id);
     const at = `the option ${s.name}.${o.id}`;
+    if (!supportsShapes(o, shapes)) {
+      const missing = shapes!.filter((k) => !o.supports!.shape!.includes(k));
+      out.push(["shape", `${at} supports the shape kinds ${o.supports!.shape!.join(", ")}, not ${missing.join(", ")}`]);
+    }
     if (meta !== undefined && meta !== s.name) out.push(["meta", `the stage ${s.name} is set, but the meta option of ${meta} replaces the other stages of its part`]);
     out.push(...choiceParamProblems(o, c["params"], at));
     if (o.members === undefined) {
@@ -349,42 +411,77 @@ 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));
+    out.push(...memberProblems(partOf(space, s.name).space, o.members, c["members"], at, shapes));
   }
   for (const c of space.constraints ?? []) if (!holds(c, chosen)) out.push(["constraint", `the config breaks the constraint ${describe(c)}`]);
   return out;
 }
 
 /** This function gives the problems of the members of a meta option. `part` is the space of the members. */
-function memberProblems(part: StrategySpace, rule: MemberRule, members: unknown, at: string): Problem[] {
+function memberProblems(part: StrategySpace, rule: MemberRule, members: unknown, at: string, shapes?: readonly ShapeKind[]): Problem[] {
   if (!Array.isArray(members)) return [["members", `${at} is a meta option without a list of members`]];
   const out: Problem[] = [];
   if (members.length < rule.min || members.length > rule.max) out.push(["members", `${at} has ${members.length} members, not ${rule.min} to ${rule.max}`]);
   const ids = new Map<string, number>();
   members.forEach((m: unknown, k) => {
-    const inner = configProblems(part, m, true);
+    const inner = configProblems(part, m, true, shapes);
     for (const [claim, detail] of inner) out.push([claim, `the member ${k} of ${at}: ${detail}`]);
     if (inner.length > 0) return;
     const id = idOf(canonicalOf(part, m as StrategyConfig, true));
     if (ids.has(id)) out.push(["duplicate", `the members ${ids.get(id)} and ${k} of ${at} are the same config ${id}`]);
     else ids.set(id, k);
   });
+  if (rule.pool !== undefined && out.length === 0) {
+    const key = memberKey(part, rule, members as readonly StrategyConfig[]);
+    if (!rule.pool.some((entry) => memberKey(part, rule, entry) === key))
+      out.push(["pool", `${at} has a member list that is not in its pool of ${rule.pool.length} ${rule.pool.length === 1 ? "list" : "lists"}`]);
+  }
+  return out;
+}
+
+/** This function gives the key of a good member list: the `configId` of each member, sorted when the rule is not ordered. */
+function memberKey(part: StrategySpace, rule: MemberRule, members: readonly StrategyConfig[]): string {
+  const ids = members.map((m) => idOf(canonicalOf(part, m, true)));
+  if (!rule.ordered) ids.sort();
+  return ids.join(",");
+}
+
+/** This function gives the problems of the pool of a meta option of a good space. `part` is the space of the members. */
+function poolProblems(part: StrategySpace, rule: MemberRule, at: string): Problem[] {
+  const out: Problem[] = [];
+  const keys = new Map<string, number>();
+  const plain: MemberRule = { min: rule.min, max: rule.max, ordered: rule.ordered };
+  (rule.pool ?? []).forEach((entry, j) => {
+    const inner = memberProblems(part, plain, entry, `the pool entry ${j} of ${at}`);
+    out.push(...inner);
+    if (inner.length > 0) return;
+    const key = memberKey(part, rule, entry);
+    if (keys.has(key)) out.push(["duplicate", `the pool entries ${keys.get(key)} and ${j} of ${at} have the same members`]);
+    else keys.set(key, j);
+  });
   return out;
 }
 
+/** This function tells if a member list fits a space: each member is a good config of the space. A shape filter removes options from the space. */
+const fits = (part: StrategySpace, entry: readonly StrategyConfig[]): boolean => entry.every((m) => configProblems(part, m, true).length === 0);
+
 const toBreaks = (problems: readonly Problem[], inputs: readonly string[] = []): ClaimBreak[] => problems.map(([claim, detail]) => ({ claim, detail, inputs }));
 
 /**
  * This function checks one config of a space. It gives one break for each problem. An empty list tells that the config is good.
  * The `claim` of a break is the kind of the problem, for example `missing`, `unknown`, `inactive`, `param`, `constraint`, `members` or `depth`.
+ *
+ * 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.
  */
-export function checkConfig(space: StrategySpace, config: StrategyConfig): ClaimBreak[] {
-  return toBreaks(configProblems(space, config, false));
+export function checkConfig(space: StrategySpace, config: StrategyConfig, options: ShapeFilter = {}): ClaimBreak[] {
+  return toBreaks(configProblems(space, config, false, options.shapes));
 }
 
 /**
  * This function checks a space. It gives one break for each problem. An empty list tells that the space is good.
  * It finds duplicate names, empty ranges, defaults out of range, enums without values, bad log scales, unknown names and bad named configs.
+ * It also checks each entry of a `pool`: the count of its members, each member and a repeated entry.
  * The `inputs` of a break of a named config have the name of the config.
  */
 export function checkSpace(space: StrategySpace): ClaimBreak[] {
@@ -423,6 +520,9 @@ export function checkSpace(space: StrategySpace): ClaimBreak[] {
     for (const s of space.stages) if (partOf(space, s.name).prefix === "") out.push(["parts", `the stage ${s.name} is not a stage of a part`]);
   const breaks = toBreaks(out);
   if (breaks.length > 0) return breaks;
+  for (const s of space.stages)
+    for (const o of s.options) if (o.members?.pool !== undefined) breaks.push(...toBreaks(poolProblems(partOf(space, s.name).space, o.members, `the option ${s.name}.${o.id}`)));
+  if (breaks.length > 0) return breaks;
   for (const [name, config] of Object.entries(space.named ?? {}))
     breaks.push(...toBreaks(configProblems(space, config, false).map(([c, d]) => [c, `the named config ${name}: ${d}`] as const), [name]));
   return breaks;
@@ -569,7 +669,7 @@ interface Combo {
 const optionIds = (choices: Choices): Map<string, string | null> => new Map([...choices].map(([k, o]) => [k, o?.id ?? null]));
 const keeps = (space: StrategySpace, choices: Choices): boolean => (space.constraints ?? []).every((c) => holds(c, optionIds(choices)));
 
-/** This function gives the count of the member lists of a meta option from `base` base configs, or `null` above `limit`. */
+/** This function gives the count of the member lists of a meta option without a pool from `base` base configs, or `null` above `limit`. */
 function memberLists(base: bigint, rule: MemberRule, limit: bigint): bigint | null {
   let sum = 0n;
   for (let m = rule.min; m <= rule.max; m++) {
@@ -638,7 +738,8 @@ 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]));
-      if (keeps(space, choices)) out.push({ choices, base: false, weight: times(countOf(o), memberLists(base, o.members, limit), limit) });
+      const lists = o.members.pool === undefined ? memberLists(base, 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;
 }
@@ -646,14 +747,49 @@ function combos(space: StrategySpace, levels: number, meta: boolean, limit: bigi
 /**
  * This function gives the count of the grid points of a space, with `levels` levels for each numeric param.
  * It counts only the active params and the combinations that keep the constraints. It gives the meta configs apart.
+ * A meta option with a `pool` counts each entry of the pool one time.
+ * With `shapes`, it counts only the options that support each kind of the list.
  */
 export function spaceSize(space: StrategySpace, options: SpaceSizeOptions): SpaceSize {
   assertSpace(space);
   assertWhole(options.levels, "levels", 1);
-  const limit = options.maxMeta ?? 10n ** 18n;
+  assertShapes(options.shapes);
+  return sizeOf(restrict(space, options.shapes), options.levels, options.maxMeta ?? 10n ** 18n);
+}
+
+/**
+ * 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.
+ */
+function restrict(space: StrategySpace, shapes: readonly ShapeKind[] | undefined): StrategySpace {
+  if (shapes === undefined) return space;
+  const kept: StrategySpace = {
+    ...space,
+    stages: space.stages.map((s) => ({ ...s, options: s.options.filter((o) => supportsShapes(o, shapes)) })),
+    ...(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;
+    const pool = o.members.pool.filter((entry) => fits(part, entry));
+    return pool.length === 0 ? [] : [{ ...o, members: { ...o.members, pool } }];
+  };
+  return { ...kept, stages: kept.stages.map((s) => ({ ...s, options: s.options.flatMap((o) => withPool(s, o)) })) };
+}
+
+/** 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;
+  if (!Array.isArray(shapes)) throw new RangeError("The option shapes is not a list of shape kinds.");
+  for (const k of shapes) if (!isShapeKind(k)) throw new RangeError(`The shape kind ${show(k)} is not one of ${SHAPE_KIND_IDS.join(", ")}.`);
+}
+
+/** This function gives the count of the grid points of a space that is known to be good. */
+function sizeOf(space: StrategySpace, levels: number, limit: bigint): SpaceSize {
   let base = 0n;
   let meta: bigint | null = 0n;
-  for (const c of combos(space, options.levels, true, limit)) {
+  for (const c of combos(space, levels, true, limit)) {
     if (c.base) base += c.weight!;
     else meta = meta === null || c.weight === null || meta + c.weight > limit ? null : meta + c.weight;
   }
@@ -674,11 +810,12 @@ function* product<T>(lists: readonly (readonly T[])[], i = 0, acc: T[] = []): Ge
 }
 
 /** This function gives the configs of the grid of a space, without meta options. */
-function gridConfigs(space: StrategySpace, levels: number, limit: number): StrategyConfig[] {
-  const size = spaceSize(space, { levels, maxMeta: 0n }).base;
+function gridConfigs(space: StrategySpace, levels: number, limit: number, shapes: readonly ShapeKind[] | undefined): StrategyConfig[] {
+  const kept = restrict(space, shapes);
+  const size = sizeOf(kept, levels, 0n).base;
   if (size > BigInt(limit)) throw new RangeError(`The grid of the space ${space.engine} has ${size} configs, more than the limit ${limit}.`);
   const out: StrategyConfig[] = [];
-  for (const c of combos(space, levels, false, 0n)) {
+  for (const c of combos(kept, levels, false, 0n)) {
     const names = [...c.choices.keys()];
     const lists = names.map((k) => {
       const o = c.choices.get(k)!;
@@ -724,6 +861,7 @@ function sampleConfigs(space: StrategySpace, n: number, seed: number, meta: bool
   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) 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;
   });
   const points: Map<string, StageOption | null>[] = [];
@@ -761,6 +899,14 @@ function sampleConfigs(space: StrategySpace, n: number, seed: number, meta: bool
         });
       }
       if (o.members === undefined) continue;
+      const fixed = o.members.pool;
+      if (fixed !== undefined) {
+        const r = stepRandom(seed, `pool-entry:${s.name}:${o.id}`);
+        permutation(users.length, r).forEach((stratum, j) => {
+          members[users[j]!]![k] = [...fixed[Math.min(fixed.length - 1, Math.floor(((stratum + r()) / users.length) * fixed.length))]!];
+        });
+        continue;
+      }
       const part = partOf(space, s.name).space;
       const poolSize = Math.max(n, 4 * o.members.max, 8);
       const seen = new Set<string>();
@@ -794,12 +940,15 @@ function sampleConfigs(space: StrategySpace, n: number, seed: number, meta: bool
  * - The mode `grid` gives each grid point without a meta option, in a stable order. Stages, options and values go in the order of the space.
  * - The mode `sample` gives `n` configs of a seeded Latin hypercube. The options of a stage get equal strata, and each active param gets its own strata.
  * - 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.
  */
 export function enumerateSpace(space: StrategySpace, options: EnumerateOptions): StrategyConfig[] {
   assertSpace(space);
+  assertShapes(options.shapes);
   if (options.mode === "grid") {
     assertWhole(options.levels, "levels", 1);
-    return gridConfigs(space, options.levels, options.limit ?? 100_000);
+    return gridConfigs(space, options.levels, options.limit ?? 100_000, options.shapes);
   }
   if (options.mode !== "sample") throw new RangeError(`The mode ${String((options as { mode?: unknown }).mode)} is not grid or sample.`);
   assertWhole(options.n, "n", 0);
@@ -807,7 +956,16 @@ 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(space, 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));
+}
+
+/**
+ * This function gives the shape kinds that a space accepts, in the order of `SHAPE_KINDS`. The value comes from the `supports` of the options.
+ * A space accepts a kind when it has at least one config without a meta option on that kind.
+ */
+export function spaceShapeKinds(space: StrategySpace): ShapeKind[] {
+  assertSpace(space);
+  return SHAPE_KIND_IDS.filter((k) => sizeOf(restrict(space, [k]), 1, 0n).base > 0n);
 }
 
 /**