@mark1russell7/strategy-space 0.0.0-bootstrap.0 → 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mark Russell
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,50 @@
 # @mark1russell7/strategy-space
 
-This version is a placeholder. The release workflow of https://github.com/mark1russell7/strategy-space publishes the real versions. Use a later version.
+Layout strategies as data. A strategy space gives the stages of an engine, the options of each stage and the ranges of their params. The functions of this package check a space and its configs, and give the id of a config. They also count the space and make grids and seeded samples.
+
+```ts
+import { checkSpace, configId, enumerateSpace, spaceSize, type StrategySpace } from "@mark1russell7/strategy-space";
+
+const space: StrategySpace = {
+  schema: "strategy-space/1",
+  engine: "pack",
+  version: "0.0.1",
+  stages: [
+    { name: "order", options: [{ id: "area", params: [] }, { id: "height", params: [] }] },
+    { name: "placement", options: [{ id: "shelf", params: [{ name: "gap", kind: "int", min: 0, max: 8, default: 2 }] }] },
+  ],
+};
+
+checkSpace(space); // [] : the space is good
+spaceSize(space, { levels: 3 }).base; // 6n : 2 orders, 3 levels of gap
+const configs = enumerateSpace(space, { mode: "sample", n: 4, seed: 7 });
+configId(space, configs[0]!); // the first 16 hex characters of a SHA-256
+```
+
+## What the package has
+
+| Area | Functions |
+| --- | --- |
+| The checks | `checkSpace`, `checkConfig`, `paramProblem` |
+| The id of a config | `canonicalConfig`, `configId` |
+| The count | `spaceSize`, `paramLevels`, `spaceShapeKinds` |
+| The configs | `enumerateSpace` (the modes `grid` and `sample`, the draws `uniform` and `walk`, fixed options) |
+| Two spaces as one | `productSpace`, `joinConfigs`, `splitConfig` |
+| The option schema of a strategy | `listOptions`, `optionDefaults`, `checkOptions`, `clampOptions`, `checkSchema` |
+| The sweeps of the options | `sweepValues`, `sweepOf`, `sweepGrid` |
+| The distinctness gate | `distinctness`, `distinctCount` |
+
+[`docs/STRATEGY-SPACE.md`](../../docs/STRATEGY-SPACE.md) tells the schema `strategy-space/1` and the rules of each function. [`docs/DISTINCT.md`](../../docs/DISTINCT.md) tells the gate.
+
+## Shape kinds
+
+An option can give the shape kinds that it supports, as tags. The option `kinds` gives the list of the known tags. Without `kinds`, each string with text is a kind.
+
+```ts
+checkSpace(space, { kinds: ["rect", "circle"] });
+spaceSize(space, { levels: 3, shapes: ["circle"], kinds: ["rect", "circle"] });
+```
+
+## The same ids as `layout-contract`
+
+The schema, the ids and the samples come from `layout-contract` 0.6.1 with no change. A config has the same `configId`, and a seed gives the same sample. The hash and the random numbers come from `@mark1russell7/rigor-generators`.

package/build/claim.d.ts

@@ -0,0 +1,10 @@
+/** One broken claim, with the ids of the inputs that break it. `layout-contract` uses the same form for the checks of a corpus. */
+export interface ClaimBreak {
+  /** The name of the claim, for example `schema`, `unknown`, `shape` or `members`. */
+  readonly claim: string;
+  /** The text of the break. */
+  readonly detail: string;
+  /** The ids of the inputs that break the claim. The list is empty when the break has no input. */
+  readonly inputs: readonly string[];
+}
+//# sourceMappingURL=claim.d.ts.map

package/build/claim.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"claim.d.ts","names":[],"sources":["../src/claim.ts"],"mappings":";iBAGiB;;WAEN;;WAEA;;WAEA"}

package/build/distinct.d.ts

@@ -0,0 +1,49 @@
+/** The hashes of the outputs of one strategy: one hash for each input, by the id of the input. `probeHash` of `layout-contract` gives one hash. */
+export interface OutputHashes {
+  readonly id: string;
+  readonly stage: string;
+  readonly outputs: Readonly<Record<string, string>>;
+}
+/** The options of the gate. */
+export interface DistinctOptions {
+  /** The ids of the inputs of the set. Each variant needs a hash on each of them. */
+  readonly inputs: readonly string[];
+  /** The hash that a strategy gives for an input that it refuses, for example `REFUSED_PROBE` of `layout-contract`. A refused input is not a difference. */
+  readonly refused?: string;
+}
+/**
+ * The verdict of the gate on one variant.
+ * `distinct`: on at least one input, its output differs from the output of each operator of its stage.
+ * `same`: an operator of its stage has the same hash on each input of the set.
+ * `no-read`: the gate cannot decide. An input has no hash, or no input shows a difference from an operator that is not the same.
+ */
+export type DistinctVerdict = "distinct" | "same" | "no-read";
+/** The row of the gate for one variant. */
+export interface DistinctRow {
+  readonly id: string;
+  readonly stage: string;
+  readonly verdict: DistinctVerdict;
+  /** The first id of the variants with the same hash on each input. A variant with a different id is a duplicate of it. */
+  readonly canonical: string;
+  /** The operators with the same hash on each input. */
+  readonly sameAs: readonly string[];
+  /** The operators with no difference on a compared input, and no equal hash on each input. */
+  readonly undecided: readonly string[];
+  /** The inputs of the set with no hash for this variant. */
+  readonly missing: readonly string[];
+  /** The first input where the outputs differ from each operator, by the id of the operator. */
+  readonly differsOn: Readonly<Record<string, string>>;
+}
+/**
+ * This function gives the verdict of the gate on each variant, sorted by id.
+ * It compares a variant only with the operators of its stage. A stage with no operator gives `distinct` to each complete variant.
+ *
+ * @param operators - The hashes of the existing operators.
+ * @param variants - The hashes of the variants that the gate examines.
+ * @param options - The inputs of the set and the refused hash.
+ * @throws Error when an id is in the operators or in the variants more than once, or when the set has no input.
+ */
+export declare function distinctness(operators: readonly OutputHashes[], variants: readonly OutputHashes[], options: DistinctOptions): DistinctRow[];
+/** This function gives the count of the distinct variants: the canonical variants with the verdict `distinct`. A duplicate does not count. */
+export declare function distinctCount(rows: readonly DistinctRow[]): number;
+//# sourceMappingURL=distinct.d.ts.map

package/build/distinct.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"distinct.d.ts","names":[],"sources":["../src/distinct.ts"],"mappings":";iBAIiB;WACN;WACA;WACA,SAAS,SAAS;;;iBAIZ;;WAEN;;WAEA;;;;;;;;YASC;;iBAGK;WACN;WACA;WACA,SAAS;;WAET;;WAEA;;WAEA;;WAEA;;WAEA,WAAW,SAAS;;;;;;;;;;;wBAuBf,aAAa,oBAAoB,gBAAgB,mBAAmB,gBAAgB,SAAS,kBAAkB;;wBAiC/G,cAAc,eAAe"}

package/build/distinct.js

@@ -0,0 +1,61 @@
+// src/distinct.ts
+/** This function gives the key of the hashes of a strategy on the inputs, in the order of the inputs. */
+function vectorKey(s, inputs) {
+	return JSON.stringify(inputs.map((b) => s.outputs[b] ?? null));
+}
+/** This function gives the ids that are in the list more than once. */
+function repeated(ids) {
+	const seen = /* @__PURE__ */ new Set();
+	return [...new Set(ids.filter((id) => seen.has(id) || !seen.add(id)))];
+}
+/**
+* This function gives the verdict of the gate on each variant, sorted by id.
+* It compares a variant only with the operators of its stage. A stage with no operator gives `distinct` to each complete variant.
+*
+* @param operators - The hashes of the existing operators.
+* @param variants - The hashes of the variants that the gate examines.
+* @param options - The inputs of the set and the refused hash.
+* @throws Error when an id is in the operators or in the variants more than once, or when the set has no input.
+*/
+function distinctness(operators, variants, options) {
+	const { inputs, refused } = options;
+	if (inputs.length === 0) throw new Error("The gate has no input.");
+	const twice = repeated([...operators.map((o) => o.id), ...variants.map((v) => v.id)]);
+	if (twice.length > 0) throw new Error(`These ids are not unique: ${twice.join(", ")}.`);
+	const canonical = /* @__PURE__ */ new Map();
+	for (const v of [...variants].sort((a, b) => a.id < b.id ? -1 : 1)) {
+		const key = `${v.stage}\u0000${vectorKey(v, inputs)}`;
+		if (!canonical.has(key)) canonical.set(key, v.id);
+	}
+	const compared = (a, b) => a !== void 0 && b !== void 0 && a !== refused && b !== refused;
+	return [...variants].sort((a, b) => a.id < b.id ? -1 : 1).map((v) => {
+		const missing = inputs.filter((b) => v.outputs[b] === void 0);
+		const sameAs = [];
+		const undecided = [];
+		const differsOn = {};
+		for (const op of operators.filter((o) => o.stage === v.stage).sort((a, b) => a.id < b.id ? -1 : 1)) {
+			const input = inputs.find((b) => compared(v.outputs[b], op.outputs[b]) && v.outputs[b] !== op.outputs[b]);
+			if (input !== void 0) differsOn[op.id] = input;
+			else if (missing.length === 0 && inputs.every((b) => op.outputs[b] === v.outputs[b])) sameAs.push(op.id);
+			else undecided.push(op.id);
+		}
+		const verdict = missing.length > 0 ? "no-read" : sameAs.length > 0 ? "same" : undecided.length > 0 ? "no-read" : "distinct";
+		return {
+			id: v.id,
+			stage: v.stage,
+			verdict,
+			canonical: canonical.get(`${v.stage}\u0000${vectorKey(v, inputs)}`),
+			sameAs,
+			undecided,
+			missing,
+			differsOn
+		};
+	});
+}
+/** This function gives the count of the distinct variants: the canonical variants with the verdict `distinct`. A duplicate does not count. */
+function distinctCount(rows) {
+	return rows.filter((r) => r.verdict === "distinct" && r.canonical === r.id).length;
+}
+export { distinctCount, distinctness };
+
+//# sourceMappingURL=distinct.js.map

package/build/distinct.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"distinct.js","names":[],"sources":["../src/distinct.ts"],"sourcesContent":["// The distinctness gate (`docs/DISTINCT.md`). A variant counts only when its output differs from each operator of its stage on at least one input.\n// The caller gives the hash of the output of each strategy on each input of a fixed set. The gate came from `highways` 27b40c8.\n\n/** The hashes of the outputs of one strategy: one hash for each input, by the id of the input. `probeHash` of `layout-contract` gives one hash. */\nexport interface OutputHashes {\n  readonly id: string;\n  readonly stage: string;\n  readonly outputs: Readonly<Record<string, string>>;\n}\n\n/** The options of the gate. */\nexport interface DistinctOptions {\n  /** The ids of the inputs of the set. Each variant needs a hash on each of them. */\n  readonly inputs: readonly string[];\n  /** The hash that a strategy gives for an input that it refuses, for example `REFUSED_PROBE` of `layout-contract`. A refused input is not a difference. */\n  readonly refused?: string;\n}\n\n/**\n * The verdict of the gate on one variant.\n * `distinct`: on at least one input, its output differs from the output of each operator of its stage.\n * `same`: an operator of its stage has the same hash on each input of the set.\n * `no-read`: the gate cannot decide. An input has no hash, or no input shows a difference from an operator that is not the same.\n */\nexport type DistinctVerdict = \"distinct\" | \"same\" | \"no-read\";\n\n/** The row of the gate for one variant. */\nexport interface DistinctRow {\n  readonly id: string;\n  readonly stage: string;\n  readonly verdict: DistinctVerdict;\n  /** The first id of the variants with the same hash on each input. A variant with a different id is a duplicate of it. */\n  readonly canonical: string;\n  /** The operators with the same hash on each input. */\n  readonly sameAs: readonly string[];\n  /** The operators with no difference on a compared input, and no equal hash on each input. */\n  readonly undecided: readonly string[];\n  /** The inputs of the set with no hash for this variant. */\n  readonly missing: readonly string[];\n  /** The first input where the outputs differ from each operator, by the id of the operator. */\n  readonly differsOn: Readonly<Record<string, string>>;\n}\n\n/** This function gives the key of the hashes of a strategy on the inputs, in the order of the inputs. */\nfunction vectorKey(s: OutputHashes, inputs: readonly string[]): string {\n  return JSON.stringify(inputs.map((b) => s.outputs[b] ?? null));\n}\n\n/** This function gives the ids that are in the list more than once. */\nfunction repeated(ids: readonly string[]): string[] {\n  const seen = new Set<string>();\n  return [...new Set(ids.filter((id) => seen.has(id) || !seen.add(id)))];\n}\n\n/**\n * This function gives the verdict of the gate on each variant, sorted by id.\n * It compares a variant only with the operators of its stage. A stage with no operator gives `distinct` to each complete variant.\n *\n * @param operators - The hashes of the existing operators.\n * @param variants - The hashes of the variants that the gate examines.\n * @param options - The inputs of the set and the refused hash.\n * @throws Error when an id is in the operators or in the variants more than once, or when the set has no input.\n */\nexport function distinctness(operators: readonly OutputHashes[], variants: readonly OutputHashes[], options: DistinctOptions): DistinctRow[] {\n  const { inputs, refused } = options;\n  if (inputs.length === 0) throw new Error(\"The gate has no input.\");\n  const twice = repeated([...operators.map((o) => o.id), ...variants.map((v) => v.id)]);\n  if (twice.length > 0) throw new Error(`These ids are not unique: ${twice.join(\", \")}.`);\n\n  // The first id of each class of variants with the same hashes.\n  const canonical = new Map<string, string>();\n  for (const v of [...variants].sort((a, b) => (a.id < b.id ? -1 : 1))) {\n    const key = `${v.stage}\\u0000${vectorKey(v, inputs)}`;\n    if (!canonical.has(key)) canonical.set(key, v.id);\n  }\n\n  const compared = (a: string | undefined, b: string | undefined): boolean => a !== undefined && b !== undefined && a !== refused && b !== refused;\n  return [...variants]\n    .sort((a, b) => (a.id < b.id ? -1 : 1))\n    .map((v) => {\n      const missing = inputs.filter((b) => v.outputs[b] === undefined);\n      const sameAs: string[] = [];\n      const undecided: string[] = [];\n      const differsOn: Record<string, string> = {};\n      for (const op of operators.filter((o) => o.stage === v.stage).sort((a, b) => (a.id < b.id ? -1 : 1))) {\n        const input = inputs.find((b) => compared(v.outputs[b], op.outputs[b]) && v.outputs[b] !== op.outputs[b]);\n        if (input !== undefined) differsOn[op.id] = input;\n        else if (missing.length === 0 && inputs.every((b) => op.outputs[b] === v.outputs[b])) sameAs.push(op.id);\n        else undecided.push(op.id);\n      }\n      const verdict: DistinctVerdict = missing.length > 0 ? \"no-read\" : sameAs.length > 0 ? \"same\" : undecided.length > 0 ? \"no-read\" : \"distinct\";\n      return { id: v.id, stage: v.stage, verdict, canonical: canonical.get(`${v.stage}\\u0000${vectorKey(v, inputs)}`)!, sameAs, undecided, missing, differsOn };\n    });\n}\n\n/** This function gives the count of the distinct variants: the canonical variants with the verdict `distinct`. A duplicate does not count. */\nexport function distinctCount(rows: readonly DistinctRow[]): number {\n  return rows.filter((r) => r.verdict === \"distinct\" && r.canonical === r.id).length;\n}\n"],"mappings":";;AA4CA,SAAS,UAAU,GAAiB,QAAmC;CACrE,OAAO,KAAK,UAAU,OAAO,KAAK,MAAM,EAAE,QAAQ,MAAM,IAAI,CAAC;AAC/D;;AAGA,SAAS,SAAS,KAAkC;CAClD,MAAM,uBAAO,IAAI,IAAY;CAC7B,OAAO,CAAC,GAAG,IAAI,IAAI,IAAI,QAAQ,OAAO,KAAK,IAAI,EAAE,KAAK,CAAC,KAAK,IAAI,EAAE,CAAC,CAAC,CAAC;AACvE;;;;;;;;;;AAWA,SAAgB,aAAa,WAAoC,UAAmC,SAAyC;CAC3I,MAAM,EAAE,QAAQ,YAAY;CAC5B,IAAI,OAAO,WAAW,GAAG,MAAM,IAAI,MAAM,wBAAwB;CACjE,MAAM,QAAQ,SAAS,CAAC,GAAG,UAAU,KAAK,MAAM,EAAE,EAAE,GAAG,GAAG,SAAS,KAAK,MAAM,EAAE,EAAE,CAAC,CAAC;CACpF,IAAI,MAAM,SAAS,GAAG,MAAM,IAAI,MAAM,6BAA6B,MAAM,KAAK,IAAI,EAAE,EAAE;CAGtF,MAAM,4BAAY,IAAI,IAAoB;CAC1C,KAAK,MAAM,KAAK,CAAC,GAAG,QAAQ,CAAC,CAAC,MAAM,GAAG,MAAO,EAAE,KAAK,EAAE,KAAK,KAAK,CAAE,GAAG;EACpE,MAAM,MAAM,GAAG,EAAE,MAAM,QAAQ,UAAU,GAAG,MAAM;EAClD,IAAI,CAAC,UAAU,IAAI,GAAG,GAAG,UAAU,IAAI,KAAK,EAAE,EAAE;CAClD;CAEA,MAAM,YAAY,GAAuB,MAAmC,MAAM,KAAA,KAAa,MAAM,KAAA,KAAa,MAAM,WAAW,MAAM;CACzI,OAAO,CAAC,GAAG,QAAQ,CAAC,CACjB,MAAM,GAAG,MAAO,EAAE,KAAK,EAAE,KAAK,KAAK,CAAE,CAAC,CACtC,KAAK,MAAM;EACV,MAAM,UAAU,OAAO,QAAQ,MAAM,EAAE,QAAQ,OAAO,KAAA,CAAS;EAC/D,MAAM,SAAmB,CAAC;EAC1B,MAAM,YAAsB,CAAC;EAC7B,MAAM,YAAoC,CAAC;EAC3C,KAAK,MAAM,MAAM,UAAU,QAAQ,MAAM,EAAE,UAAU,EAAE,KAAK,CAAC,CAAC,MAAM,GAAG,MAAO,EAAE,KAAK,EAAE,KAAK,KAAK,CAAE,GAAG;GACpG,MAAM,QAAQ,OAAO,MAAM,MAAM,SAAS,EAAE,QAAQ,IAAI,GAAG,QAAQ,EAAE,KAAK,EAAE,QAAQ,OAAO,GAAG,QAAQ,EAAE;GACxG,IAAI,UAAU,KAAA,GAAW,UAAU,GAAG,MAAM;QACvC,IAAI,QAAQ,WAAW,KAAK,OAAO,OAAO,MAAM,GAAG,QAAQ,OAAO,EAAE,QAAQ,EAAE,GAAG,OAAO,KAAK,GAAG,EAAE;QAClG,UAAU,KAAK,GAAG,EAAE;EAC3B;EACA,MAAM,UAA2B,QAAQ,SAAS,IAAI,YAAY,OAAO,SAAS,IAAI,SAAS,UAAU,SAAS,IAAI,YAAY;EAClI,OAAO;GAAE,IAAI,EAAE;GAAI,OAAO,EAAE;GAAO;GAAS,WAAW,UAAU,IAAI,GAAG,EAAE,MAAM,QAAQ,UAAU,GAAG,MAAM,GAAG;GAAI;GAAQ;GAAW;GAAS;EAAU;CAC1J,CAAC;AACL;;AAGA,SAAgB,cAAc,MAAsC;CAClE,OAAO,KAAK,QAAQ,MAAM,EAAE,YAAY,cAAc,EAAE,cAAc,EAAE,EAAE,CAAC,CAAC;AAC9E"}

package/build/index.d.ts

@@ -0,0 +1,5 @@
+import { ClaimBreak } from "./claim.js";
+import { DistinctOptions, DistinctRow, DistinctVerdict, OutputHashes, distinctCount, distinctness } from "./distinct.js";
+import { AnyOption, BooleanOption, DeclaredStrategy, EnumOption, ListItem, NoDefault, NoDefaultReason, NumberOption, OptionDeclaration, OptionIssue, OptionScale, OptionSchema, OptionSetting, SweepOptions, ValueOption, checkOptions, checkSchema, clampOptions, declarationIssues, listOptions, optionDefaults, optionIssue, sweepGrid, sweepOf, sweepValues } from "./strategy-options.js";
+import { EnumerateOptions, GridOptions, KindOptions, MemberRule, OptionRef, OptionSupports, ParamKind, ParamValue, ParamWhen, STRATEGY_SPACE_SCHEMA, SampleOptions, ShapeFilter, SpaceConstraint, SpaceParam, SpaceSize, SpaceSizeOptions, SpaceStage, StageChoice, StageOption, StrategyConfig, StrategySpace, canonicalConfig, checkConfig, checkSpace, configId, enumerateSpace, joinConfigs, paramActive, paramLevels, paramProblem, paramValue, productSpace, spaceShapeKinds, spaceSize, splitConfig } from "./strategy-space.js";
+export { AnyOption, BooleanOption, type ClaimBreak, DeclaredStrategy, DistinctOptions, DistinctRow, DistinctVerdict, EnumOption, EnumerateOptions, GridOptions, KindOptions, ListItem, MemberRule, NoDefault, NoDefaultReason, NumberOption, OptionDeclaration, OptionIssue, OptionRef, OptionScale, OptionSchema, OptionSetting, OptionSupports, OutputHashes, ParamKind, ParamValue, ParamWhen, STRATEGY_SPACE_SCHEMA, SampleOptions, ShapeFilter, SpaceConstraint, SpaceParam, SpaceSize, SpaceSizeOptions, SpaceStage, StageChoice, StageOption, StrategyConfig, StrategySpace, SweepOptions, ValueOption, canonicalConfig, checkConfig, checkOptions, checkSchema, checkSpace, clampOptions, configId, declarationIssues, distinctCount, distinctness, enumerateSpace, joinConfigs, listOptions, optionDefaults, optionIssue, paramActive, paramLevels, paramProblem, paramValue, productSpace, spaceShapeKinds, spaceSize, splitConfig, sweepGrid, sweepOf, sweepValues };

package/build/index.js

@@ -0,0 +1,4 @@
+import { distinctCount, distinctness } from "./distinct.js";
+import { checkOptions, checkSchema, clampOptions, declarationIssues, listOptions, optionDefaults, optionIssue, sweepGrid, sweepOf, sweepValues } from "./strategy-options.js";
+import { STRATEGY_SPACE_SCHEMA, canonicalConfig, checkConfig, checkSpace, configId, enumerateSpace, joinConfigs, paramActive, paramLevels, paramProblem, paramValue, productSpace, spaceShapeKinds, spaceSize, splitConfig } from "./strategy-space.js";
+export { STRATEGY_SPACE_SCHEMA, canonicalConfig, checkConfig, checkOptions, checkSchema, checkSpace, clampOptions, configId, declarationIssues, distinctCount, distinctness, enumerateSpace, joinConfigs, listOptions, optionDefaults, optionIssue, paramActive, paramLevels, paramProblem, paramValue, productSpace, spaceShapeKinds, spaceSize, splitConfig, sweepGrid, sweepOf, sweepValues };

package/build/space-walk.js

@@ -0,0 +1,48 @@
+// src/space-walk.ts
+const refMatches = (ref, choices) => (choices.get(ref.stage) ?? null) === ref.option;
+/** This function tells if the option choices keep a constraint. */
+function holds(c, choices) {
+	if (!refMatches(c.if, choices)) return true;
+	return "not" in c.then ? !refMatches(c.then.not, choices) : refMatches(c.then, choices);
+}
+const otherStage = (c) => "not" in c.then ? c.then.not.stage : c.then.stage;
+/** This function tells if an option of a stage keeps each constraint between that stage and the stages that a walk has fixed. */
+function fitsWalk(constraints, fixed, stage, id) {
+	fixed.set(stage, id);
+	const ok = constraints.every((c) => !fixed.has(c.if.stage === stage ? otherStage(c) : c.if.stage) || holds(c, fixed));
+	fixed.delete(stage);
+	return ok;
+}
+/**
+* This function gives the plan of a walk. Stages of equal size keep the order of the space.
+* The stages of `first` go first, for example the stages of the sample option `fixed`. Thus the other stages draw only from the options that keep the constraints with them.
+*/
+function walkPlan(stages, lists, constraints, n, first = /* @__PURE__ */ new Set()) {
+	return {
+		stages,
+		lists,
+		n,
+		order: stages.map((_, k) => k).sort((a, b) => Number(first.has(stages[b].name)) - Number(first.has(stages[a].name)) || lists[b].length - lists[a].length || a - b),
+		naming: stages.map((s) => constraints.filter((c) => c.if.stage === s.name || otherStage(c) === s.name))
+	};
+}
+/**
+* This function gives the options of one point of a walk. It fixes the largest stage first. Thus that stage keeps its equal strata, and the constraints limit only the smaller stages.
+* The value `picks[k][i]` is the stratum of the stage `k` for the point `i`. A stage with no open option gets `null`, and the caller rejects that point.
+* The argument `fits` lets a test give a fault. The default is `fitsWalk`.
+*/
+function walkPoint(plan, picks, i, fits = fitsWalk) {
+	const fixed = /* @__PURE__ */ new Map();
+	const out = /* @__PURE__ */ new Map();
+	for (const k of plan.order) {
+		const s = plan.stages[k];
+		const open = plan.lists[k].filter((o) => fits(plan.naming[k], fixed, s.name, o?.id ?? null));
+		const o = open[Math.floor(picks[k][i] * open.length / plan.n)] ?? null;
+		fixed.set(s.name, o?.id ?? null);
+		out.set(s.name, o);
+	}
+	return out;
+}
+export { fitsWalk, holds, walkPlan, walkPoint };
+
+//# sourceMappingURL=space-walk.js.map

package/build/space-walk.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"space-walk.js","names":[],"sources":["../src/space-walk.ts"],"sourcesContent":["// The walk draw of a sample of a strategy space (`docs/STRATEGY-SPACE.md`). The package root does not export this file.\nimport type { OptionRef, SpaceConstraint, SpaceStage, StageOption } from \"./strategy-space.ts\";\n\nconst refMatches = (ref: OptionRef, choices: ReadonlyMap<string, string | null>): boolean => (choices.get(ref.stage) ?? null) === ref.option;\n\n/** This function tells if the option choices keep a constraint. */\nexport function holds(c: SpaceConstraint, choices: ReadonlyMap<string, string | null>): boolean {\n  if (!refMatches(c.if, choices)) return true;\n  return \"not\" in c.then ? !refMatches(c.then.not, choices) : refMatches(c.then, choices);\n}\n\nconst otherStage = (c: SpaceConstraint): string => (\"not\" in c.then ? c.then.not.stage : c.then.stage);\n\n/** This function tells if an option of a stage keeps each constraint between that stage and the stages that a walk has fixed. */\nexport function fitsWalk(constraints: readonly SpaceConstraint[], fixed: Map<string, string | null>, stage: string, id: string | null): boolean {\n  fixed.set(stage, id);\n  const ok = constraints.every((c) => !fixed.has(c.if.stage === stage ? otherStage(c) : c.if.stage) || holds(c, fixed));\n  fixed.delete(stage);\n  return ok;\n}\n\n/** The order of the stages of a walk, and the constraints that name each stage. */\nexport interface WalkPlan {\n  /** The stages of the space. */\n  readonly stages: readonly SpaceStage[];\n  /** The options of each stage for a draw. */\n  readonly lists: readonly (readonly (StageOption | null)[])[];\n  /** The indexes of the stages. The stages of `first` come first, in the order of the space. The others follow, from the largest stage to the smallest. */\n  readonly order: readonly number[];\n  /** The constraints that name each stage. */\n  readonly naming: readonly (readonly SpaceConstraint[])[];\n  /** The count of points of a round. */\n  readonly n: number;\n}\n\n/**\n * This function gives the plan of a walk. Stages of equal size keep the order of the space.\n * The stages of `first` go first, for example the stages of the sample option `fixed`. Thus the other stages draw only from the options that keep the constraints with them.\n */\nexport function walkPlan(\n  stages: readonly SpaceStage[],\n  lists: readonly (readonly (StageOption | null)[])[],\n  constraints: readonly SpaceConstraint[],\n  n: number,\n  first: ReadonlySet<string> = new Set(),\n): WalkPlan {\n  return {\n    stages,\n    lists,\n    n,\n    order: stages.map((_, k) => k).sort((a, b) => Number(first.has(stages[b]!.name)) - Number(first.has(stages[a]!.name)) || lists[b]!.length - lists[a]!.length || a - b),\n    naming: stages.map((s) => constraints.filter((c) => c.if.stage === s.name || otherStage(c) === s.name)),\n  };\n}\n\n/**\n * This function gives the options of one point of a walk. It fixes the largest stage first. Thus that stage keeps its equal strata, and the constraints limit only the smaller stages.\n * The value `picks[k][i]` is the stratum of the stage `k` for the point `i`. A stage with no open option gets `null`, and the caller rejects that point.\n * The argument `fits` lets a test give a fault. The default is `fitsWalk`.\n */\nexport function walkPoint(plan: WalkPlan, picks: readonly (readonly number[])[], i: number, fits: typeof fitsWalk = fitsWalk): Map<string, StageOption | null> {\n  const fixed = new Map<string, string | null>();\n  const out = new Map<string, StageOption | null>();\n  for (const k of plan.order) {\n    const s = plan.stages[k]!;\n    const open = plan.lists[k]!.filter((o) => fits(plan.naming[k]!, fixed, s.name, o?.id ?? null));\n    const o = open[Math.floor((picks[k]![i]! * open.length) / plan.n)] ?? null;\n    fixed.set(s.name, o?.id ?? null);\n    out.set(s.name, o);\n  }\n  return out;\n}\n"],"mappings":";AAGA,MAAM,cAAc,KAAgB,aAA0D,QAAQ,IAAI,IAAI,KAAK,KAAK,UAAU,IAAI;;AAGtI,SAAgB,MAAM,GAAoB,SAAsD;CAC9F,IAAI,CAAC,WAAW,EAAE,IAAI,OAAO,GAAG,OAAO;CACvC,OAAO,SAAS,EAAE,OAAO,CAAC,WAAW,EAAE,KAAK,KAAK,OAAO,IAAI,WAAW,EAAE,MAAM,OAAO;AACxF;AAEA,MAAM,cAAc,MAAgC,SAAS,EAAE,OAAO,EAAE,KAAK,IAAI,QAAQ,EAAE,KAAK;;AAGhG,SAAgB,SAAS,aAAyC,OAAmC,OAAe,IAA4B;CAC9I,MAAM,IAAI,OAAO,EAAE;CACnB,MAAM,KAAK,YAAY,OAAO,MAAM,CAAC,MAAM,IAAI,EAAE,GAAG,UAAU,QAAQ,WAAW,CAAC,IAAI,EAAE,GAAG,KAAK,KAAK,MAAM,GAAG,KAAK,CAAC;CACpH,MAAM,OAAO,KAAK;CAClB,OAAO;AACT;;;;;AAoBA,SAAgB,SACd,QACA,OACA,aACA,GACA,wBAA6B,IAAI,IAAI,GAC3B;CACV,OAAO;EACL;EACA;EACA;EACA,OAAO,OAAO,KAAK,GAAG,MAAM,CAAC,CAAC,CAAC,MAAM,GAAG,MAAM,OAAO,MAAM,IAAI,OAAO,EAAE,CAAE,IAAI,CAAC,IAAI,OAAO,MAAM,IAAI,OAAO,EAAE,CAAE,IAAI,CAAC,KAAK,MAAM,EAAE,CAAE,SAAS,MAAM,EAAE,CAAE,UAAU,IAAI,CAAC;EACrK,QAAQ,OAAO,KAAK,MAAM,YAAY,QAAQ,MAAM,EAAE,GAAG,UAAU,EAAE,QAAQ,WAAW,CAAC,MAAM,EAAE,IAAI,CAAC;CACxG;AACF;;;;;;AAOA,SAAgB,UAAU,MAAgB,OAAuC,GAAW,OAAwB,UAA2C;CAC7J,MAAM,wBAAQ,IAAI,IAA2B;CAC7C,MAAM,sBAAM,IAAI,IAAgC;CAChD,KAAK,MAAM,KAAK,KAAK,OAAO;EAC1B,MAAM,IAAI,KAAK,OAAO;EACtB,MAAM,OAAO,KAAK,MAAM,EAAE,CAAE,QAAQ,MAAM,KAAK,KAAK,OAAO,IAAK,OAAO,EAAE,MAAM,GAAG,MAAM,IAAI,CAAC;EAC7F,MAAM,IAAI,KAAK,KAAK,MAAO,MAAM,EAAE,CAAE,KAAM,KAAK,SAAU,KAAK,CAAC,MAAM;EACtE,MAAM,IAAI,EAAE,MAAM,GAAG,MAAM,IAAI;EAC/B,IAAI,IAAI,EAAE,MAAM,CAAC;CACnB;CACA,OAAO;AACT"}

package/build/strategy-options.d.ts

@@ -0,0 +1,189 @@
+import { ParamWhen } from "./strategy-space.js";
+/** The scale of a number option. A sweep on the scale `log` gives values with equal ratios, not with equal differences. */
+export type OptionScale = "linear" | "log";
+/** The reason why an option has no default value. The strategy reads the absence, the caller sets it, the strategy calculates it, or the default is code. */
+export type NoDefaultReason = "unset" | "required" | "derived" | "function";
+/** The statement of an option without a default value that JSON can hold. */
+export interface NoDefault {
+  readonly reason: NoDefaultReason;
+  /** One short sentence that tells what the strategy does without a value. */
+  readonly describe: string;
+}
+/** The fields of each option declaration. */
+interface OptionBase {
+  /** One short sentence that tells what the option sets. The site and the documents show it. */
+  readonly describe: string;
+  /** This field tells why the option has no default. The catalog of an engine has this field or a `default` on each option. */
+  readonly noDefault?: NoDefault;
+  /** The option is active only when an earlier option of the same strategy has one of these values. */
+  readonly when?: ParamWhen;
+}
+/**
+ * The declaration of a number option. The range from `min` to `max` is the range of a control and of a sweep.
+ * The strategy can take a value outside the range. `checkOptions` reports such a value, and `clampOptions` moves it into the range.
+ */
+export interface NumberOption extends OptionBase {
+  /** The type `integer` takes only whole numbers. */
+  readonly type: "number" | "integer";
+  readonly min: number;
+  readonly max: number;
+  /** The grain of a control and of a sweep. A value off the step is valid. Without it, the grain is free (or 1 for an integer). */
+  readonly step?: number;
+  /** The scale of a control and of a sweep. The default is `linear`. The scale `log` needs a `min` above 0. */
+  readonly scale?: OptionScale;
+  /** These values are valid outside the range. For example, `Infinity` sets no limit. */
+  readonly special?: readonly number[];
+  /** These values are the notable values of the option: the default and the values of the sweeps of the benchmark. */
+  readonly marks?: readonly number[];
+  /**
+   * These values are the only valid values of the option, in the order of a control. A control shows them as a list, and a sweep gives them.
+   * Without them, each value on the range is valid.
+   */
+  readonly values?: readonly number[];
+  /** The strategy uses this value when the caller and `defaults` give no value. */
+  readonly default?: number;
+}
+/** The declaration of a boolean option. */
+export interface BooleanOption extends OptionBase {
+  readonly type: "boolean";
+  /** The strategy uses this value when the caller and `defaults` give no value. */
+  readonly default?: boolean;
+}
+/** The declaration of an option with a fixed list of string values. */
+export interface EnumOption<V extends string = string> extends OptionBase {
+  readonly type: "enum";
+  /** The values of the option, in the order of a control. */
+  readonly values: readonly V[];
+  /**
+   * With `function`, the option also takes a rule of the caller in place of a name. A control sets only the names.
+   * Each name is a known rule of the strategy.
+   */
+  readonly custom?: "function";
+  /** The strategy uses this value when the caller and `defaults` give no value. */
+  readonly default?: V;
+}
+/**
+ * The declaration of an option that a control or a sweep cannot set from a range.
+ * The type `function` is a rule, `strategy` is a strategy of the step `step`, `list` is an array and `object` is any other object.
+ */
+export interface ValueOption<V = unknown, S extends string = string> extends OptionBase {
+  readonly type: "function" | "strategy" | "list" | "object";
+  /** The step of the strategy, for the type `strategy`. A control lists the strategies of this step of a registry. */
+  readonly step?: S;
+  /** The kinds of strategy that the option takes, for the type `strategy`. Without them, the option takes each kind. */
+  readonly kinds?: readonly string[];
+  /** The key of the option that holds the options of the chosen strategy, for the type `strategy`. */
+  readonly optionsKey?: string;
+  /** The value `true` lets a value hold its options: a key, or an object with the fields `strategy`, `options` and `id`. This field is for the type `strategy`, and also for an item of a list. */
+  readonly inlineOptions?: boolean;
+  /** The value `false` leaves out the opt-in strategies, because the option finds only the default set of the engine. This field is for the type `strategy`. */
+  readonly optIn?: boolean;
+  /** For each dimension of `supports`, the value that a chosen strategy must take. This field is for the type `strategy`, and also for an item of a list. */
+  readonly needs?: Readonly<Record<string, string>>;
+  /** The declaration of each item, for the type `list`. */
+  readonly of?: ListItem<S>;
+  /** The smallest number of items, for the type `list`. */
+  readonly min?: number;
+  /** The largest number of items, for the type `list`. */
+  readonly max?: number;
+  /** The strategy uses this value when the caller and `defaults` give no value. */
+  readonly default?: V;
+}
+/** The declaration of one option of any type. */
+export type AnyOption<S extends string = string> = NumberOption | BooleanOption | EnumOption | ValueOption<unknown, S>;
+/** This type removes the fields of a whole option from a declaration. */
+type ItemOf<T> = T extends unknown ? Omit<T, "describe" | "default" | "noDefault" | "when"> : never;
+/** The declaration of one item of a list option: an option without its text, its default and its condition. */
+export type ListItem<S extends string = string> = ItemOf<AnyOption<S>>;
+/**
+ * The declaration that fits the type of an option value: numbers, booleans, string unions or other values.
+ * A union of strings and other values takes an enum of the strings or a value declaration. An example is a rule or the name of a rule.
+ * A plain `string` takes an enum or a value declaration, because the value can be the key of a strategy.
+ */
+export type OptionDeclaration<V, S extends string = string> = [V] extends [number] ? NumberOption : [V] extends [boolean] ? BooleanOption : [V] extends [string] ? string extends V ? EnumOption<V> | ValueOption<V, S> : EnumOption<V> : [Extract<V, string>] extends [never] ? ValueOption<V, S> : EnumOption<Extract<V, string>> | ValueOption<V, S>;
+/** The declarations of the options of a strategy. The schema has one declaration for each key of the options type, and no other key. */
+export type OptionSchema<O, S extends string = string> = { readonly [K in keyof O]-?: OptionDeclaration<NonNullable<O[K]>, S>; };
+/** The fields of a strategy that the functions of this module read. An engine can add other fields. */
+export interface DeclaredStrategy<O extends object = object, S extends string = string> {
+  /** The name of the strategy in a message. */
+  readonly name: string;
+  readonly defaults: O;
+  readonly schema?: OptionSchema<O, S>;
+}
+/** One problem of an option value against its declaration. */
+export interface OptionIssue {
+  /** The key of the option. */
+  readonly key: string;
+  readonly value: unknown;
+  /** The kind of the problem: no declaration, the wrong type, out of the range, not a whole number or not one of the values. */
+  readonly problem: "unknown" | "type" | "range" | "integer" | "value";
+  /** One sentence that tells the problem. */
+  readonly message: string;
+}
+/** One setting of a sweep: a name for the rows of a table, and the options of the strategy. */
+export interface OptionSetting<O extends object> {
+  /** The key and the value of each option of the setting, for example `stretch 1.5`. */
+  readonly name: string;
+  readonly options: Partial<O>;
+}
+/** The options of `sweepValues`, `sweepOf` and `sweepGrid`. */
+export interface SweepOptions {
+  /**
+   * The number of values on the range of a number option. Without it, the sweep gives the `marks` of the declaration.
+   * A declaration without `marks` gets 5 values.
+   */
+  readonly count?: number;
+  /** With `true`, a sweep of a number option on the range also gives the `special` values. The default is `false`. */
+  readonly special?: boolean;
+}
+/** This function gives the declared options of a strategy, in the order of its schema, with the effective default of each one. */
+export declare function listOptions<O extends object, S extends string = string>(strategy: DeclaredStrategy<O, S>): {
+  readonly key: keyof O & string;
+  readonly declaration: AnyOption<S>;
+  readonly value: unknown;
+}[];
+/**
+ * This function gives the effective default of each declared option: the value of `defaults`, else the `default` of the declaration.
+ * An option without either value stays out. The strategy gives the same output with this object as with no options.
+ */
+export declare function optionDefaults<O extends object, S extends string = string>(strategy: DeclaredStrategy<O, S>): Partial<O>;
+/** This function gives the problem of one value against its declaration, or `undefined` when the value fits. */
+export declare function optionIssue(key: string, value: unknown, d: AnyOption): OptionIssue | undefined;
+/**
+ * This function examines option values against the schema of a strategy. It gives one issue for each key without a declaration.
+ * It also gives one issue for each value of the wrong type, out of the range, not whole or not one of the values.
+ * It changes no value.
+ * A strategy without a schema gives no issue.
+ */
+export declare function checkOptions<O extends object>(strategy: DeclaredStrategy<O>, options: Partial<O>): OptionIssue[];
+/**
+ * This function moves each number option into the range of its declaration, for a control. An integer option gets the nearest whole number.
+ * An option with a list of `values` gets the nearest value of the list. A special value stays. The function keeps each other value as it is. `checkOptions` reports the values that this function cannot correct.
+ */
+export declare function clampOptions<O extends object>(strategy: DeclaredStrategy<O>, options: Partial<O>): Partial<O>;
+/**
+ * This function gives the values of a sweep of one option declaration.
+ * A number option gives its `marks`, or its list of `values`, or `count` values on its range and its scale. A boolean gives `false` and `true`. An enum gives its values.
+ * An option of another type has no sweep, so the function throws an error.
+ */
+export declare function sweepValues(declaration: AnyOption, options?: SweepOptions): unknown[];
+/**
+ * This function gives the settings of a sweep of one option of a strategy, from its declaration only.
+ * The name of each setting is the key and the value, for example `stretch 1.5`.
+ */
+export declare function sweepOf<O extends object>(strategy: DeclaredStrategy<O>, key: keyof O & string, options?: SweepOptions): OptionSetting<O>[];
+/**
+ * This function gives the settings of a grid of options: each combination of the values of the sweeps of the keys.
+ * The name of a setting joins the names of its values with commas, in the order of the keys.
+ */
+export declare function sweepGrid<O extends object>(strategy: DeclaredStrategy<O>, keys: readonly (keyof O & string)[], options?: SweepOptions): OptionSetting<O>[];
+/** This function gives the problems of one declaration: a bad range, a bad step, or marks and a default that do not fit. */
+export declare function declarationIssues(key: string, d: AnyOption): string[];
+/**
+ * This function examines the schema of a strategy. It gives one message for each option of `defaults` without a declaration.
+ * It also gives one message for each bad declaration, and for each value of `defaults` that does not fit its declaration.
+ * A good schema gives an empty list.
+ */
+export declare function checkSchema(strategy: DeclaredStrategy): string[];
+export {};
+//# sourceMappingURL=strategy-options.d.ts.map

package/build/strategy-options.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"strategy-options.d.ts","names":[],"sources":["../src/strategy-options.ts"],"mappings":";;YAGY;;YAGA;;iBAGK;WACN,QAAQ;;WAER;;;UAID;;WAEC;;WAEA,YAAY;;WAEZ,OAAO;;;;;;iBAOD,qBAAqB;;WAE3B;WACA;WACA;;WAEA;;WAEA,QAAQ;;WAER;;WAEA;;;;;WAKA;;WAEA;;;iBAIM,sBAAsB;WAC5B;;WAEA;;;iBAIM,WAAW,mCAAmC;WACpD;;WAEA,iBAAiB;;;;;WAKjB;;WAEA,UAAU;;;;;;iBAOJ,YAAY,aAAa,mCAAmC;WAClE;;WAEA,OAAO;;WAEP;;WAEA;;WAEA;;WAEA;;WAEA,QAAQ,SAAS;;WAEjB,KAAK,SAAS;;WAEd;;WAEA;;WAEA,UAAU;;;YAIT,UAAU,6BAA6B,eAAe,gBAAgB,aAAa,qBAAqB;;KAG/G,OAAO,KAAK,oBAAoB,KAAK;;YAG9B,SAAS,6BAA6B,OAAO,UAAU;;;;;;YAOvD,kBAAkB,GAAG,8BAA8B,sBAC3D,gBACC,uBACC,iBACC,qCACgB,IACb,WAAW,KAAK,YAAY,GAAG,KAC/B,WAAW,MACZ,QAAQ,8BACP,YAAY,GAAG,KACf,WAAW,QAAQ,cAAc,YAAY,GAAG;;YAG9C,aAAa,GAAG,yCAAyC,WAAW,MAAM,kBAAkB,YAAY,EAAE,KAAK;;iBAG1G,iBAAiB,2BAA2B;;WAElD;WACA,UAAU;WACV,SAAS,aAAa,GAAG;;;iBAInB;;WAEN;WACA;;WAEA;;WAEA;;;iBAIM,cAAc;;WAEpB;WACA,SAAS,QAAQ;;;iBAIX;;;;;WAKN;;WAEA;;;wBAYK,YAAY,kBAAkB,2BAC5C,UAAU,iBAAiB,GAAG;WAClB,WAAW;WAAqB,aAAa,UAAU;WAAa;;;;;;wBASlE,eAAe,kBAAkB,2BAA2B,UAAU,iBAAiB,GAAG,KAAK,QAAQ;;wBAevG,YAAY,aAAa,gBAAgB,GAAG,YAAY;;;;;;;wBAiCxD,aAAa,kBAAkB,UAAU,iBAAiB,IAAI,SAAS,QAAQ,KAAK;;;;;wBAgBpF,aAAa,kBAAkB,UAAU,iBAAiB,IAAI,SAAS,QAAQ,KAAK,QAAQ;;;;;;wBAwC5F,YAAY,aAAa,WAAW,UAAS;;;;;wBA6B7C,QAAQ,kBAAkB,UAAU,iBAAiB,IAAI,WAAW,YAAY,UAAS,eAAoB,cAAc;;;;;wBAQ3H,UAAU,kBAAkB,UAAU,iBAAiB,IAAI,sBAAsB,eAAe,UAAS,eAAoB,cAAc;;wBAU3I,kBAAkB,aAAa,GAAG;;;;;;wBA8BlC,YAAY,UAAU"}