@mark1russell7/coeval 0.5.0 → 0.6.0

package/build/index.js

@@ -508,6 +508,338 @@ function looksLikeKind(value) {
 	return isRecord(value) && isRecord(field(value, "verbs"));
 }
 //#endregion
+//#region src/merge.ts
+/** The exception of a merge with conflicts. It lists each conflict of the merge, not only the first. */
+var MergeError = class extends Error {
+	conflicts;
+	/**
+	* This constructor makes the exception.
+	*
+	* @param conflicts - The conflicts, in the order that the merge found them.
+	*/
+	constructor(conflicts) {
+		const lines = conflicts.map((item) => `At ${JSON.stringify(item.path)}, the parts ${item.parts[0]} and ${item.parts[1]}: ${item.reason}`);
+		super(`The merge has ${conflicts.length === 1 ? "1 conflict" : `${conflicts.length} conflicts`}. ${lines.join(" ")}`);
+		this.name = "MergeError";
+		this.conflicts = conflicts;
+	}
+};
+const NONE$1 = /* @__PURE__ */ new Set();
+function keyOf(path) {
+	return JSON.stringify(path.map(String));
+}
+/** This function sets an own data property. An assignment to the key `__proto__` changes the prototype. */
+function setOwn$2(target, key, value) {
+	if (key === "__proto__") Object.defineProperty(target, key, {
+		value,
+		enumerable: true,
+		writable: true,
+		configurable: true
+	});
+	else target[key] = value;
+}
+function own$1(table, key) {
+	return table !== void 0 && Object.hasOwn(table, key) ? table[key] : void 0;
+}
+/** This function gives a copy of a JSON value without the fields whose value is `undefined`, as JSON writes it. */
+function defined(value) {
+	if (Array.isArray(value)) return value.map(defined);
+	if (!isRecord(value)) return value;
+	const out = {};
+	for (const key of Object.keys(value)) if (value[key] !== void 0) setOwn$2(out, key, defined(value[key]));
+	return out;
+}
+/** Two values are the same when they are equal by `docEquals`. A function and a host value are equal only to themselves. */
+function same(a, b) {
+	return Object.is(a, b) || docEquals(defined(a), defined(b));
+}
+/** Two lists of roots are the same when they hold the same roots, in any order. */
+function sameRoots(a, b) {
+	if (!Array.isArray(a) || !Array.isArray(b)) return same(a, b);
+	return same([...new Set(a.map(String))].sort(), [...new Set(b.map(String))].sort());
+}
+/** The record of a merge: the conflicts, and the part that gave each entry. */
+var Merger = class {
+	conflicts = [];
+	sources = /* @__PURE__ */ new Map();
+	/** This method gives the part that gave the entry at a path, or the entry nearest above it. */
+	sourceOf(path) {
+		for (let length = path.length; length >= 0; length -= 1) {
+			const found = this.sources.get(keyOf(path.slice(0, length)));
+			if (found !== void 0) return found;
+		}
+		return 0;
+	}
+	/** This method records the part that gives a new entry. */
+	give(path, part) {
+		this.sources.set(keyOf(path), part);
+	}
+	/** This method records the part that replaces an entry, and forgets the parts of each entry below it. */
+	replace(path, part) {
+		const below = `${keyOf(path).slice(0, -1)},`;
+		for (const key of [...this.sources.keys()]) if (key.startsWith(below)) this.sources.delete(key);
+		this.give(path, part);
+	}
+	clash(path, part, reason) {
+		this.conflicts.push({
+			path,
+			parts: [this.sourceOf(path), part],
+			reason
+		});
+	}
+};
+/**
+* This function merges one entry of a table into the table. A new entry joins the table. A path in `replaces` gives
+* the later entry. Two entries that are the same give one entry. Each other pair is a conflict.
+*/
+function mergeLeaf(m, table, key, later, path, part, replaces, equal, reason) {
+	if (later === void 0) return;
+	const earlier = own$1(table, key);
+	if (earlier === void 0) {
+		setOwn$2(table, key, later);
+		m.give(path, part);
+	} else if (replaces.has(keyOf(path))) {
+		setOwn$2(table, key, later);
+		m.replace(path, part);
+	} else if (!equal(earlier, later)) m.clash(path, part, reason);
+}
+function what(entry) {
+	if (isKind(entry)) return "a kind";
+	if (isAlias(entry)) return "an alias";
+	return isNamespace(entry) ? "a namespace" : "an entry";
+}
+function mergeFallback(m, earlier, later, path, part, replaces) {
+	const table = earlier === void 0 ? {} : { fallback: earlier };
+	mergeLeaf(m, table, "fallback", later, path, part, replaces, same, "Two parts give two different fallback kinds.");
+	return table["fallback"];
+}
+function mergeEntries(m, into, from, path, part, replaces) {
+	for (const key of Object.keys(from)) {
+		const later = from[key];
+		if (later === void 0) continue;
+		const at = [...path, key];
+		const earlier = own$1(into, key);
+		if (earlier === void 0) {
+			setOwn$2(into, key, later);
+			m.give(at, part);
+		} else setOwn$2(into, key, mergeEntry(m, earlier, later, at, part, replaces));
+	}
+}
+/** This function merges two entries at one path. Two namespaces merge key by key, and their fallbacks merge too. */
+function mergeEntry(m, earlier, later, path, part, replaces) {
+	if (replaces.has(keyOf(path))) {
+		m.replace(path, part);
+		return later;
+	}
+	if (same(earlier, later)) return earlier;
+	if (isNamespace(earlier) && isNamespace(later)) {
+		const kinds = { ...earlier.kinds };
+		mergeEntries(m, kinds, later.kinds, [...path, "kinds"], part, replaces);
+		const fallback = mergeFallback(m, earlier.fallback, later.fallback, [...path, "fallback"], part, replaces);
+		return fallback === void 0 ? { kinds } : {
+			kinds,
+			fallback
+		};
+	}
+	const a = what(earlier);
+	const b = what(later);
+	m.clash(path, part, a === b ? `Two parts give two different ${a === "an alias" ? "aliases" : "kinds"}.` : `One part gives ${a}, and the other part gives ${b}.`);
+	return earlier;
+}
+function worldOf(draft) {
+	const world = {
+		kinds: { ...draft.kinds },
+		defaults: { ...draft.defaults }
+	};
+	return draft.fallback === void 0 ? world : {
+		...world,
+		fallback: draft.fallback
+	};
+}
+function mergeWorldInto(m, draft, part, index, replaces, base) {
+	if (part === void 0) return;
+	if (part.kinds !== void 0) mergeEntries(m, draft.kinds, part.kinds, [...base, "kinds"], index, replaces);
+	const defaults = part.defaults ?? {};
+	for (const verb of Object.keys(defaults)) mergeLeaf(m, draft.defaults, verb, defaults[verb], [
+		...base,
+		"defaults",
+		verb
+	], index, replaces, Object.is, "Two parts give two different defaults for this verb.");
+	const fallback = mergeFallback(m, draft.fallback, part.fallback, [...base, "fallback"], index, replaces);
+	if (fallback !== void 0) draft.fallback = fallback;
+}
+/**
+* This function merges worlds into one world, in the order of the parts. It does not change a part.
+*
+* - Two entries that are equal by `docEquals` give one entry.
+* - Two namespaces merge key by key, at each depth. Their fallbacks merge as each other entry.
+* - The defaults merge verb by verb, and the world keeps one fallback.
+* - Each other pair of entries at one path is a conflict, unless the later part names the path in `replaces`.
+*   Then the later entry wins, with no merge below it.
+*
+* A part can be a function of the merge of the parts before it (`prev`, as an overlay of Nix). Thus a part can read
+* the entry that it replaces.
+*
+* @param parts - The worlds, or functions that give a world from the merge before them.
+* @returns The world. It has no `replaces`.
+* @throws {MergeError} The merge has a conflict. The error lists each conflict.
+*/
+function mergeWorlds(...parts) {
+	const m = new Merger();
+	const draft = {
+		kinds: {},
+		defaults: {}
+	};
+	parts.forEach((input, index) => {
+		const part = typeof input === "function" ? input(worldOf(draft)) : input;
+		mergeWorldInto(m, draft, part, index, new Set((part.replaces ?? []).map(keyOf)), []);
+	});
+	if (m.conflicts.length > 0) throw new MergeError(m.conflicts);
+	return worldOf(draft);
+}
+/** The fields of a machine that merge by their own rules. Each other field is one value, or a conflict. */
+const TABLES = /* @__PURE__ */ new Set([
+	"world",
+	"evaluators",
+	"runners",
+	"derefs",
+	"walkers",
+	"known",
+	"replaces"
+]);
+/**
+* This function composes the hooks `known` in the order of their parts. The first answer that is not `true` wins. A
+* hook does not answer for an evaluator name whose code a later part replaces.
+*/
+function composeKnown(hooks, replaced) {
+	const first = hooks[0];
+	if (first === void 0) return void 0;
+	if (hooks.length === 1 && replaced.size === 0) return first.known;
+	const list = [...hooks];
+	const last = new Map(replaced);
+	return (path, evaluator) => {
+		const after = last.get(evaluator);
+		for (const hook of list) {
+			if (after !== void 0 && hook.part < after) continue;
+			const answer = hook.known(path, evaluator);
+			if (answer !== true) return answer;
+		}
+		return true;
+	};
+}
+function machineOf(draft) {
+	const known = composeKnown(draft.hooks, draft.replaced);
+	return {
+		...draft.rest,
+		world: worldOf(draft.world),
+		evaluators: { ...draft.evaluators },
+		...draft.runners === void 0 ? {} : { runners: { ...draft.runners } },
+		...draft.derefs === void 0 ? {} : { derefs: { ...draft.derefs } },
+		...draft.walkers === void 0 ? {} : { walkers: { ...draft.walkers } },
+		...known === void 0 ? {} : { known }
+	};
+}
+/** This function merges the evaluators and the runners of a part. The evaluator and the runner of a name are its code. */
+function mergeCode(m, draft, part, index, replaces) {
+	if (part.runners !== void 0) draft.runners ??= {};
+	const names = /* @__PURE__ */ new Set([...Object.keys(part.evaluators ?? {}), ...Object.keys(part.runners ?? {})]);
+	for (const name of names) {
+		const evaluator = own$1(part.evaluators, name);
+		const runner = own$1(part.runners, name);
+		if (evaluator === void 0 && runner === void 0) continue;
+		const evaluatorPath = ["evaluators", name];
+		const runnerPath = ["runners", name];
+		if (replaces.has(keyOf(evaluatorPath)) || replaces.has(keyOf(runnerPath))) {
+			if (evaluator === void 0) delete draft.evaluators[name];
+			else setOwn$2(draft.evaluators, name, evaluator);
+			if (runner !== void 0) setOwn$2(draft.runners ??= {}, name, runner);
+			else if (draft.runners !== void 0) delete draft.runners[name];
+			m.replace(evaluatorPath, index);
+			m.replace(runnerPath, index);
+			draft.replaced.set(name, index);
+			continue;
+		}
+		mergeLeaf(m, draft.evaluators, name, evaluator, evaluatorPath, index, NONE$1, Object.is, "Two parts give two different evaluators for this name.");
+		if (runner !== void 0) mergeLeaf(m, draft.runners ??= {}, name, runner, runnerPath, index, NONE$1, Object.is, "Two parts give two different runners for this name.");
+	}
+}
+/** A runner hides the evaluator of its name. Thus a name with a runner and an evaluator needs one part that gives both. */
+function checkHidden(m, draft) {
+	const runners = draft.runners ?? {};
+	for (const name of Object.keys(runners)) {
+		const runner = runners[name];
+		const evaluator = own$1(draft.evaluators, name);
+		if (runner === void 0 || evaluator === void 0) continue;
+		if (draft.parts.some((part) => own$1(part.evaluators, name) === evaluator && own$1(part.runners, name) === runner)) continue;
+		const a = m.sourceOf(["evaluators", name]);
+		const b = m.sourceOf(["runners", name]);
+		m.conflicts.push({
+			path: ["runners", name],
+			parts: [Math.min(a, b), Math.max(a, b)],
+			reason: "The runner of one part hides the evaluator of the other part, because a runner wins over an evaluator of its name."
+		});
+	}
+}
+/**
+* This function merges machines into one machine, in the order of the parts. It does not change a part.
+*
+* - The worlds merge with the rules of `mergeWorlds`. The paths of their conflicts start with `"world"`.
+* - The tables `evaluators`, `runners`, `derefs` and `walkers` merge name by name. A function is equal only to itself.
+* - The evaluator and the runner of a name are its code. A replacement of the name replaces both.
+* - A runner hides the evaluator of its name. Thus one part must give both, or the merge gives a conflict.
+* - The hooks `known` compose in the order of the parts. A hook does not answer for a name that a later part replaces.
+* - Each other field, for example `permits`, `adopt`, `roots`, `plain` or `maxDepth`, is one value. Two different
+*   values are a conflict. An absent field has no value.
+*
+* A conflict stops the merge, unless the later part names its path in `replaces`. A part can be a function of the
+* merge of the parts before it (`prev`, as an overlay of Nix). Thus a part can wrap the code that it replaces.
+*
+* @param parts - The machines, or functions that give a machine from the merge before them.
+* @returns The machine.
+* @throws {MergeError} The merge has a conflict. The error lists each conflict.
+*/
+function mergeMachines(...parts) {
+	const m = new Merger();
+	const draft = {
+		world: {
+			kinds: {},
+			defaults: {}
+		},
+		evaluators: {},
+		hooks: [],
+		replaced: /* @__PURE__ */ new Map(),
+		rest: {},
+		parts: []
+	};
+	parts.forEach((input, index) => {
+		const part = typeof input === "function" ? input(machineOf(draft)) : input;
+		draft.parts.push(part);
+		const replaces = new Set([...part.replaces ?? [], ...(part.world?.replaces ?? []).map((path) => ["world", ...path])].map(keyOf));
+		mergeWorldInto(m, draft.world, part.world, index, replaces, ["world"]);
+		mergeCode(m, draft, part, index, replaces);
+		if (part.derefs !== void 0) {
+			const derefs = draft.derefs ??= {};
+			for (const name of Object.keys(part.derefs)) mergeLeaf(m, derefs, name, part.derefs[name], ["derefs", name], index, replaces, Object.is, "Two parts give two different deref codes for this name.");
+		}
+		if (part.walkers !== void 0) {
+			const walkers = draft.walkers ??= {};
+			for (const name of Object.keys(part.walkers)) mergeLeaf(m, walkers, name, part.walkers[name], ["walkers", name], index, replaces, Object.is, "Two parts give two different walkers for this name.");
+		}
+		if (part.known !== void 0 && !draft.hooks.some((hook) => hook.known === part.known)) draft.hooks.push({
+			part: index,
+			known: part.known
+		});
+		const fields = part;
+		for (const key of Object.keys(fields)) {
+			if (TABLES.has(key)) continue;
+			mergeLeaf(m, draft.rest, key, fields[key], [key], index, replaces, key === "roots" ? sameRoots : same, `Two parts give two different values for ${key}.`);
+		}
+	});
+	checkHidden(m, draft);
+	if (m.conflicts.length > 0) throw new MergeError(m.conflicts);
+	return machineOf(draft);
+}
+//#endregion
 //#region src/ladder.ts
 /** The rungs of the ladder, in the order that a question visits them. */
 const RUNGS = [
@@ -4022,37 +4354,26 @@ function formulaKnown(profile = {}) {
 	};
 }
 /**
-* This function makes a machine for a formula language. The machine has the kinds and the evaluators of the
-* formula kit. It also has the kinds, the evaluators and the walkers that the language adds. Its hook `known` comes
-* from the profile (`formulaKnown`). A hook `known` of the language answers each name that the kit knows.
+* This function makes a machine for a formula language. It merges the kit and the parts that the language adds with
+* `mergeMachines`. Thus a kind `ops.*` or a namespace `ops` of the language extends the namespace of the kit, and
+* the fallback of the kit stays. The hook `known` of the kit comes from the profile (`formulaKnown`). A hook `known`
+* of the language answers after it.
+*
+* A kind or an evaluator of the language that differs from the entry of the kit with its name is a conflict. The
+* language names the path in `replaces` to replace the entry, for example `["world", "kinds", "ref"]` or
+* `["evaluators", "formula.op"]`. Then the hook of the kit does not answer for a replaced evaluator.
 *
 * @param profile - The operations and the rules of the language.
-* @param more - The parts of a machine that the language adds. Its kinds win over the kinds of the kit.
+* @param more - The parts of a machine that the language adds, with the paths of the entries that it replaces.
 * @returns The machine.
+* @throws {MergeError} The language and the kit have a conflict.
 */
 function formulaMachine(profile = {}, more = {}) {
-	const kit = formulaKnown(profile);
-	const replaced = (name) => more.evaluators !== void 0 && Object.hasOwn(more.evaluators, name) || more.runners !== void 0 && Object.hasOwn(more.runners, name);
-	const theirs = more.known;
-	const known = (path, evaluator) => {
-		const answer = replaced(evaluator) ? true : kit(path, evaluator);
-		return answer === true && theirs !== void 0 ? theirs(path, evaluator) : answer;
-	};
-	return {
-		...more,
-		world: {
-			kinds: {
-				...formulaKinds(),
-				...more.world?.kinds
-			},
-			defaults: { ...more.world?.defaults }
-		},
-		evaluators: {
-			...formulaEvaluators(profile),
-			...more.evaluators
-		},
-		known
-	};
+	return mergeMachines({
+		world: { kinds: formulaKinds() },
+		evaluators: formulaEvaluators(profile),
+		known: formulaKnown(profile)
+	}, more);
 }
 //#endregion
 //#region src/reference.ts
@@ -5243,6 +5564,6 @@ function generate(world, options) {
 	});
 }
 //#endregion
-export { CONSTRUCTS, ENVELOPE_KEYS, Failure, Held, PARTS, PART_INFO, ROOTS, RUNGS, STD_CAPS, STD_DEFINITIONS, STD_EVALUATORS, STD_EXT, STD_MACHINE, STD_RUNNERS, STD_WALKERS, STD_WORLD, THING, agree, ask, capKeys, check, checkSteps, classify, context, dataEdges, derefStep, describe, docEquals, effectEdges, entriesAsJson, evaluate, fail, failures, field, flatten, formulaDefinitions, formulaEvaluators, formulaKinds, formulaKnown, formulaMachine, fromJson, generate, intersectCaps, isAlias, isAllowedOrder, isClosure, isEnvelope, isHostThing, isKey, isKind, isNamespace, isRecord, isRef, isStackOverflow, isTypeRef, jsTruthy, kindDocument, kindNamed, kindOf, layers, looksLikeKind, lookupKind, makeContext, mapRefs, narrow, nearestWalker, nodeAt, ok, partCaps, partsOf, pathMatches, permits, placed, planner, prepare, random, ref, reference, refsOf, resolve, run, sameValue, splitParts, stored, tag, thrown, toJson, typeName, typePath, typed, typesOf, valueOfThing, walk, worldThing };
+export { CONSTRUCTS, ENVELOPE_KEYS, Failure, Held, MergeError, PARTS, PART_INFO, ROOTS, RUNGS, STD_CAPS, STD_DEFINITIONS, STD_EVALUATORS, STD_EXT, STD_MACHINE, STD_RUNNERS, STD_WALKERS, STD_WORLD, THING, agree, ask, capKeys, check, checkSteps, classify, context, dataEdges, derefStep, describe, docEquals, effectEdges, entriesAsJson, evaluate, fail, failures, field, flatten, formulaDefinitions, formulaEvaluators, formulaKinds, formulaKnown, formulaMachine, fromJson, generate, intersectCaps, isAlias, isAllowedOrder, isClosure, isEnvelope, isHostThing, isKey, isKind, isNamespace, isRecord, isRef, isStackOverflow, isTypeRef, jsTruthy, kindDocument, kindNamed, kindOf, layers, looksLikeKind, lookupKind, makeContext, mapRefs, mergeMachines, mergeWorlds, narrow, nearestWalker, nodeAt, ok, partCaps, partsOf, pathMatches, permits, placed, planner, prepare, random, ref, reference, refsOf, resolve, run, sameValue, splitParts, stored, tag, thrown, toJson, typeName, typePath, typed, typesOf, valueOfThing, walk, worldThing };
 
 //# sourceMappingURL=index.js.map