@yahoo/uds-create-config 2.44.0 → 3.0.0

package/dist/entities/system/link-plan.js

@@ -0,0 +1,770 @@
+import { rejectData } from "../../framework/rejection.js";
+import { collectRefs, isMintedRow, ref, sourceOf, splitRef } from "../../framework/utils/refs.js";
+import { blockedBy } from "../../framework/plan.js";
+import { PIN_KIND, covers, declarationOf, narrowDeclaration } from "./link-declaration.js";
+import { planCopy, sourceEntries } from "./copy-plan.js";
+//#region src/entities/system/link-plan.ts
+/** The kinds `data` names, with what to take of each. An accessor this config has no kind for is a typo, refused by name. */
+function wantedKinds({ config, slug, data, verb }) {
+	const wanted = [];
+	if (data === "*") for (const kind of config.borrowableKinds(slug)) wanted.push({
+		kind,
+		accessor: config.accessorOf(kind) ?? kind,
+		paths: "*"
+	});
+	else {
+		const accessors = config.accessors();
+		for (const [accessor, paths] of Object.entries(data)) {
+			const cls = accessors[accessor];
+			if (!cls) rejectData(`Cannot ${verb} through "${slug}" — this system has no "${accessor}".`, ["data", accessor]);
+			wanted.push({
+				kind: cls.kind,
+				accessor,
+				paths
+			});
+		}
+	}
+	if (wanted.length === 0) rejectData(`Cannot ${verb} through "${slug}" — name what to take in \`data\`.`);
+	return wanted;
+}
+/** Whether the row here and the source's row at the path trace to one origin, so the source is a second route to something already held. */
+function sharedWithOrigin({ config, source, slug, kind, path }) {
+	const held = config.resolve(kind, path);
+	if (!held || held.copiedThrough === slug) return void 0;
+	const theirs = source.originOf({
+		kind,
+		path
+	});
+	const mine = theirs && config.originOf({
+		kind,
+		path
+	});
+	if (!theirs || !mine || theirs.key !== mine.key) return void 0;
+	return theirs.pin.displayName ?? theirs.key;
+}
+/**
+* Link paths of a source: the declaration that mints them, then the edits that let them show through
+* where this config already holds something.
+*
+* The declaration goes first. A row of this config's own that other rows point at can only be deleted
+* once the declaration covers the path, since the config refuses a delete that leaves a referrer
+* dangling. A row held through another pin is not deleted — that pin's declaration would mint it
+* again, and declaring one path on two pins is a collision nothing derives — so it becomes an
+* extension through this pin: a row of this config's own that shadows the other pin's and follows this
+* source. A member already here from the source's own origin is left alone and kept out of the
+* declaration, so a folder that holds one is declared by its other members.
+*/
+function planLink({ config, input }) {
+	const { path: slug } = input;
+	const source = config.sourceFor(slug);
+	if (!source) rejectData(`Cannot link through "${slug}" — nothing has resolved that link.`);
+	const current = declarationOf(config, slug);
+	const wanted = wantedKinds({
+		config,
+		slug,
+		data: input.data,
+		verb: "link"
+	});
+	const addresses = [];
+	const extended = [];
+	const shared = [];
+	const shadows = [];
+	/** Per accessor, what the declaration gains: the kind whole, or paths. */
+	const gains = /* @__PURE__ */ new Map();
+	let sharedAnywhere = false;
+	const shadow = (kind, path) => {
+		const held = config.resolve(kind, path);
+		if (!held || held.borrowedFrom === slug) return true;
+		if (sharedWithOrigin({
+			config,
+			source,
+			slug,
+			kind,
+			path
+		}) !== void 0) {
+			shared.push({
+				kind,
+				path
+			});
+			sharedAnywhere = true;
+			return false;
+		}
+		if (held.borrowedFrom === void 0) {
+			addresses.push({
+				kind,
+				path
+			});
+			shadows.push({
+				kind,
+				operation: "delete",
+				path
+			});
+			return true;
+		}
+		const stored = config.storedBody(kind, path);
+		const minted = stored !== void 0 && isMintedRow(stored);
+		extended.push({
+			kind,
+			path
+		});
+		shadows.push({
+			kind,
+			operation: minted ? "create" : "replace",
+			path,
+			data: {
+				...ref(kind, path, slug),
+				extend: {}
+			}
+		});
+		return true;
+	};
+	for (const { kind, accessor, paths } of wanted) {
+		const named = paths === "*" ? ["*"] : paths;
+		const gained = [];
+		let whole = paths === "*";
+		for (const path of named) {
+			const entries = sourceEntries({
+				source,
+				kind,
+				path
+			});
+			if (entries.length === 0) {
+				if (path === "*") continue;
+				rejectData(`Cannot link "${path}" through "${slug}" — the source has no ${kind} there.`, ["data", accessor]);
+			}
+			const taken = entries.filter((entry) => shadow(kind, entry.from));
+			if (taken.length === entries.length) {
+				if (path !== "*") gained.push(path);
+				continue;
+			}
+			whole = false;
+			gained.push(...taken.map((entry) => entry.from));
+		}
+		if (whole) gains.set(accessor, "*");
+		else if (gained.length > 0) gains.set(accessor, gained);
+	}
+	const declares = [];
+	let declared = current;
+	if (current !== "*") if (input.data === "*" && !sharedAnywhere) {
+		declared = "*";
+		declares.push({
+			kind: PIN_KIND,
+			operation: "update",
+			path: slug,
+			data: { link: "*" }
+		});
+	} else {
+		const next = { ...current ?? {} };
+		for (const [accessor, gain] of gains) {
+			const before = next[accessor];
+			if (before === "*") continue;
+			if (gain === "*") {
+				next[accessor] = "*";
+				continue;
+			}
+			const added = gain.filter((path) => !covers({
+				declared: current,
+				accessor,
+				path
+			}));
+			if (added.length === 0) continue;
+			next[accessor] = [...before ?? [], ...new Set(added)];
+		}
+		for (const [accessor, value] of Object.entries(next)) {
+			if (current !== void 0 && current[accessor] === value) continue;
+			declares.push({
+				kind: PIN_KIND,
+				operation: "update",
+				path: slug,
+				data: { [`link.${accessor}`]: value }
+			});
+		}
+		declared = Object.keys(next).length === 0 ? current : next;
+	}
+	const patches = [...declares, ...shadows];
+	return {
+		declared,
+		arriving: arrivals({
+			config,
+			slug,
+			patches,
+			named: input.data
+		}),
+		replaces: addresses.length,
+		addresses,
+		extended,
+		shared,
+		patches
+	};
+}
+/**
+* The rows a link mints, read by running its patches on a scratch config and deriving: what is held
+* through the pin afterwards and was not before. Nothing when the op would refuse; the op says why.
+*/
+function arrivals({ config, slug, patches, named }) {
+	if (patches.length === 0) return [];
+	const through = (at) => {
+		const held = /* @__PURE__ */ new Set();
+		for (const kind of at.borrowableKinds(slug)) for (const item of at.list(kind)) if (item.borrowedFrom === slug) held.add(`${kind}:${item.path}`);
+		return held;
+	};
+	let after;
+	try {
+		after = config.applyAll(patches).withDerivedRows();
+	} catch {
+		return [];
+	}
+	const before = through(config);
+	const arriving = [];
+	for (const key of through(after)) {
+		if (before.has(key)) continue;
+		const { kind, path } = splitRef(key);
+		const accessor = config.accessorOf(kind) ?? kind;
+		arriving.push({
+			kind,
+			path,
+			named: covers({
+				declared: named,
+				accessor,
+				path
+			})
+		});
+	}
+	return arriving;
+}
+/**
+* Stop drawing paths of a source. The declaration narrows, or clears, and the rows it minted retire
+* with it inside the apply; nothing authored here moves. Named paths take the linked rows that point
+* at them along (`cascade`), since left linked those would bring them back. A row of this config's own
+* pointing at a minted row would be stranded, and the config refuses that, which `blocked` reports.
+*/
+function planUnlink({ config, input }) {
+	const { path: slug } = input;
+	const current = declarationOf(config, slug);
+	if (current === void 0) return {
+		declared: void 0,
+		removed: [],
+		cascade: [],
+		patches: []
+	};
+	let declared;
+	const patches = [];
+	const cascade = [];
+	if (input.data === void 0 || input.data === "*") {
+		declared = void 0;
+		patches.push({
+			kind: PIN_KIND,
+			operation: "update",
+			path: slug,
+			data: { link: null }
+		});
+	} else {
+		const removal = /* @__PURE__ */ new Map();
+		for (const { accessor, paths } of wantedKinds({
+			config,
+			slug,
+			data: input.data,
+			verb: "unlink"
+		})) removal.set(accessor, paths === "*" ? "*" : [...paths]);
+		for (const row of linkedDependents({
+			config,
+			slug,
+			data: input.data
+		})) {
+			const accessor = config.accessorOf(row.kind) ?? row.kind;
+			const listed = removal.get(accessor);
+			if (listed === "*") continue;
+			if (listed?.some((path) => path === row.path || row.path.startsWith(`${path}/`))) continue;
+			cascade.push(row);
+			removal.set(accessor, [...listed ?? [], row.path]);
+		}
+		declared = narrowDeclaration({
+			config,
+			slug,
+			current,
+			removal,
+			verb: "unlink"
+		});
+		patches.push({
+			kind: PIN_KIND,
+			operation: "update",
+			path: slug,
+			data: { link: declared === void 0 ? null : declared }
+		});
+	}
+	let blocked = blockedBy(() => config.applyAll(patches));
+	const removed = [];
+	if (blocked === void 0) {
+		const after = config.applyAll(patches);
+		for (const kind of config.borrowableKinds(slug)) for (const item of config.list(kind)) {
+			if (item.borrowedFrom !== slug) continue;
+			if (after.resolve(kind, item.path)?.borrowedFrom === slug) continue;
+			removed.push({
+				kind,
+				path: item.path
+			});
+		}
+		if (input.data !== void 0 && removed.length === 0) blocked = stillReached({ slug });
+	}
+	return {
+		declared,
+		removed,
+		cascade,
+		...blocked === void 0 ? {} : { blocked },
+		patches
+	};
+}
+/**
+* The linked rows that point at what `data` names, followed to a fixpoint: a row pointing at one of
+* those, and so on. Read off both ref graphs, since a linked row's refs are the source's spelling and
+* this config's index holds them qualified.
+*/
+function linkedDependents({ config, slug, data }) {
+	const source = config.sourceFor(slug);
+	const named = /* @__PURE__ */ new Set();
+	for (const { kind, paths } of wantedKinds({
+		config,
+		slug,
+		data,
+		verb: "unlink"
+	})) {
+		const list = paths === "*" ? ["*"] : paths;
+		for (const path of list) {
+			if (path !== "*") named.add(`${kind}:${path}`);
+			if (!source) continue;
+			for (const entry of sourceEntries({
+				source,
+				kind,
+				path
+			})) named.add(`${kind}:${entry.from}`);
+		}
+	}
+	const found = /* @__PURE__ */ new Map();
+	const linkedHere = (referrer) => {
+		const parts = splitRef(referrer);
+		if (parts.member !== void 0 || parts.source !== void 0) return;
+		const key = `${parts.kind}:${parts.path}`;
+		if (named.has(key) || found.has(key)) return;
+		if (config.resolve(parts.kind, parts.path)?.borrowedFrom !== slug) return;
+		return {
+			kind: parts.kind,
+			path: parts.path
+		};
+	};
+	const queue = [...named];
+	while (queue.length > 0) {
+		const target = queue.shift();
+		const referrers = [...config.refs.dependents(target), ...source ? source.refs.dependents(target) : []];
+		for (const referrer of referrers) {
+			const row = linkedHere(referrer);
+			if (!row) continue;
+			found.set(`${row.kind}:${row.path}`, row);
+			queue.push(`${row.kind}:${row.path}`);
+		}
+	}
+	return [...found.values()];
+}
+/** Why an unlink of named paths would change nothing, when even its cascade left them minted. */
+function stillReached({ slug }) {
+	return `Nothing would go: what "${slug}" declares still reaches everything named. Keep the values as yours instead.`;
+}
+/** What a copy names, accumulated as `copy` takes it. */
+var CopyRequest = class {
+	#whole = false;
+	#byAccessor = /* @__PURE__ */ new Map();
+	constructor(config) {
+		this.config = config;
+	}
+	everything() {
+		this.#whole = true;
+	}
+	kind(accessor) {
+		this.#byAccessor.set(accessor, "*");
+	}
+	path(kind, path) {
+		const accessor = this.config.accessorOf(kind) ?? kind;
+		const current = this.#byAccessor.get(accessor);
+		if (current === "*") return;
+		if (current) current.add(path);
+		else this.#byAccessor.set(accessor, new Set([path]));
+	}
+	get empty() {
+		return !this.#whole && this.#byAccessor.size === 0;
+	}
+	get data() {
+		if (this.#whole) return "*";
+		return Object.fromEntries([...this.#byAccessor].map(([accessor, paths]) => [accessor, paths === "*" ? "*" : [...paths]]));
+	}
+};
+/** The refs a row of this config's own holds through the pin, as the row spells them. */
+function drawnThroughPin({ config, slug, kind, path }) {
+	return [...new Set(collectRefs(config.storedBody(kind, path)).filter((target) => sourceOf(target) === slug && splitRef(target).member === void 0))];
+}
+/**
+* Break a link: everything drawn through the pin becomes this config's own, or is dropped, and the
+* pin goes.
+*
+* With `keep`, every entity drawn through the pin is copied in — the value the source holds today,
+* written as a row of this config's own — and a row of yours that pointed through the pin has its
+* targets copied too, with the copy pointing it at the copies. The declaration is then cleared and
+* the pin deleted; nothing refers to it by then. Without `keep`, the declaration is cleared and the
+* pin deleted, and a row of yours still pointing through it is what refuses the break.
+*
+* With `data`, the pin stays and the account is of those paths alone: with `keep`, detaching them
+* through `copy` — the rows the copy lands, the rows of yours it rebinds, and the rows still linked
+* that reference what moves; without it, an `unlink` of them — the rows that go, and the refusal a
+* row of yours pointing at one would raise.
+*/
+function planBreak({ config, input }) {
+	const { path: slug } = input;
+	const declared = declarationOf(config, slug);
+	const scoped = input.data !== void 0;
+	const keep = input.keep ?? true;
+	const rows = [];
+	const seen = /* @__PURE__ */ new Set();
+	const rowOf = (row) => {
+		const key = `${row.kind}:${row.path}`;
+		if (seen.has(key)) return;
+		seen.add(key);
+		rows.push(row);
+	};
+	if (scoped && !keep) {
+		const plan = planUnlink({
+			config,
+			input: {
+				path: slug,
+				data: input.data
+			}
+		});
+		const cascaded = new Set(plan.cascade.map((row) => `${row.kind}:${row.path}`));
+		for (const { kind, path } of plan.removed) rowOf({
+			kind,
+			path,
+			folder: false,
+			refs: [ref(kind, path, slug).__ref],
+			outcome: "dropped",
+			reach: cascaded.has(`${kind}:${path}`) ? "taken" : "direct"
+		});
+		return {
+			rows,
+			...plan.blocked === void 0 ? {} : { blocked: plan.blocked },
+			patches: plan.patches
+		};
+	}
+	if (!scoped && !keep) {
+		for (const kind of config.borrowableKinds(slug)) for (const item of config.list(kind)) {
+			if (item.borrowedFrom !== slug) continue;
+			rowOf({
+				kind,
+				path: item.path,
+				folder: false,
+				refs: [ref(kind, item.path, slug).__ref],
+				outcome: "dropped",
+				reach: "direct"
+			});
+		}
+		const patches = [...declared === void 0 ? [] : [{
+			kind: PIN_KIND,
+			operation: "update",
+			path: slug,
+			data: { link: null }
+		}], {
+			kind: PIN_KIND,
+			operation: "delete",
+			path: slug
+		}];
+		const blocked = blockedBy(() => config.applyAll(patches));
+		return {
+			rows,
+			...blocked === void 0 ? {} : { blocked },
+			patches
+		};
+	}
+	const copying = new CopyRequest(config);
+	/** Rows of this config's own that point through the pin, and what each drew. */
+	const pointing = /* @__PURE__ */ new Map();
+	/** Folders drawn through the pin by a pointer of this config's own, released once their members are copied. */
+	const pointedFolders = [];
+	const reach = ({ kind, path, reach }) => {
+		const held = config.resolve(kind, path);
+		if (held?.borrowedFrom === slug) {
+			copying.path(kind, path);
+			rowOf({
+				kind,
+				path,
+				folder: false,
+				refs: [ref(kind, path, slug).__ref],
+				outcome: "copied",
+				reach
+			});
+			return;
+		}
+		if (!held) {
+			if (config.groupBorrowedFrom({
+				kind,
+				groupPath: path
+			}) === slug) {
+				copying.path(kind, path);
+				const meta = config.groupMeta(kind, path);
+				if (meta && !isMintedRow(meta)) pointedFolders.push({
+					kind,
+					path
+				});
+				rowOf({
+					kind,
+					path,
+					folder: true,
+					refs: [ref(kind, path, slug).__ref],
+					outcome: "copied",
+					reach
+				});
+			}
+			return;
+		}
+		const refs = drawnThroughPin({
+			config,
+			slug,
+			kind,
+			path
+		});
+		if (refs.length === 0) return;
+		for (const target of refs) {
+			const parts = splitRef(target);
+			copying.path(parts.kind, parts.path);
+		}
+		pointing.set(`${kind}:${path}`, {
+			refs,
+			reach
+		});
+	};
+	if (scoped) for (const { kind, accessor, paths } of wantedKinds({
+		config,
+		slug,
+		data: input.data,
+		verb: "break"
+	})) {
+		if (paths === "*") {
+			copying.kind(accessor);
+			continue;
+		}
+		for (const path of paths) reach({
+			kind,
+			path,
+			reach: "direct"
+		});
+	}
+	else {
+		if (declared === "*") copying.everything();
+		else if (declared) {
+			for (const [accessor, paths] of Object.entries(declared)) if (paths === "*") copying.kind(accessor);
+		}
+		for (const dependent of config.dependentsOf(PIN_KIND, slug)) {
+			const { kind, path } = splitRef(dependent);
+			const held = config.resolve(kind, path);
+			reach({
+				kind,
+				path,
+				reach: held?.borrowedFrom === slug || !held ? "direct" : "indirect"
+			});
+		}
+	}
+	const patches = [];
+	const released = /* @__PURE__ */ new Set();
+	let copyBlocked;
+	if (!copying.empty) copyBlocked = blockedBy(() => {
+		const plan = planCopy({
+			config,
+			input: {
+				path: slug,
+				data: copying.data
+			}
+		});
+		for (const row of plan.rows) rowOf({
+			kind: row.kind,
+			path: row.path,
+			folder: false,
+			refs: [ref(row.kind, row.path, slug).__ref],
+			outcome: "copied",
+			reach: "taken"
+		});
+		for (const { kind, path } of plan.rebound) {
+			const drew = pointing.get(`${kind}:${path}`);
+			rowOf({
+				kind,
+				path,
+				folder: false,
+				refs: drew?.refs ?? drawnThroughPin({
+					config,
+					slug,
+					kind,
+					path
+				}),
+				outcome: "rebound",
+				reach: drew?.reach ?? "indirect"
+			});
+		}
+		for (const folder of plan.folders) released.add(`${folder.kind}:${folder.path}`);
+		patches.push(...plan.patches.filter((patch) => scoped || !(patch.kind === "linked-system" && patch.operation === "update")));
+	});
+	if (copyBlocked !== void 0) return {
+		rows,
+		blocked: copyBlocked,
+		patches: []
+	};
+	reachReferrers({
+		config,
+		slug,
+		rows,
+		rowOf
+	});
+	if (scoped) return {
+		rows,
+		patches
+	};
+	for (const folder of pointedFolders) {
+		if (released.has(`${folder.kind}:${folder.path}`)) continue;
+		patches.push({
+			kind: folder.kind,
+			operation: "group-update",
+			path: folder.path,
+			data: { ref: null }
+		});
+	}
+	if (declared !== void 0) patches.push({
+		kind: PIN_KIND,
+		operation: "update",
+		path: slug,
+		data: { link: null }
+	});
+	patches.push({
+		kind: PIN_KIND,
+		operation: "delete",
+		path: slug
+	});
+	const blocked = blockedBy(() => config.applyAll(patches));
+	return {
+		rows,
+		...blocked === void 0 ? {} : { blocked },
+		patches
+	};
+}
+/**
+* The rows that reference what a break copies without pointing through the pin themselves. Yours are
+* rebound onto the copies; the source's own, still linked, keep following the source.
+*/
+function reachReferrers({ config, slug, rows, rowOf }) {
+	const copied = rows.filter((row) => row.outcome === "copied");
+	const copiedKeys = new Set(copied.map((row) => `${row.kind}:${row.path}`));
+	const source = config.sourceFor(slug);
+	const referrerOf = (referrer) => {
+		const parts = splitRef(referrer);
+		if (parts.member !== void 0 || parts.source !== void 0) return;
+		if (copiedKeys.has(`${parts.kind}:${parts.path}`)) return;
+		return parts;
+	};
+	const yours = /* @__PURE__ */ new Map();
+	const theirs = /* @__PURE__ */ new Map();
+	for (const { kind, path } of copied) {
+		const target = `${kind}:${path}`;
+		for (const referrer of config.refs.dependents(target)) {
+			const parts = referrerOf(referrer);
+			if (!parts) continue;
+			const body = config.storedBody(parts.kind, parts.path);
+			if (!body || isMintedRow(body)) continue;
+			const held = yours.get(`${parts.kind}:${parts.path}`) ?? /* @__PURE__ */ new Set();
+			held.add(target);
+			yours.set(`${parts.kind}:${parts.path}`, held);
+		}
+		if (!source) continue;
+		for (const referrer of source.refs.dependents(target)) {
+			const parts = referrerOf(referrer);
+			if (!parts) continue;
+			if (config.resolve(parts.kind, parts.path)?.borrowedFrom !== slug) continue;
+			const held = theirs.get(`${parts.kind}:${parts.path}`) ?? /* @__PURE__ */ new Set();
+			held.add(ref(kind, path, slug).__ref);
+			theirs.set(`${parts.kind}:${parts.path}`, held);
+		}
+	}
+	for (const [key, refs] of yours) {
+		const { kind, path } = splitRef(key);
+		rowOf({
+			kind,
+			path,
+			folder: false,
+			refs: [...refs],
+			outcome: "rebound",
+			reach: "indirect"
+		});
+	}
+	for (const [key, refs] of theirs) {
+		const { kind, path } = splitRef(key);
+		rowOf({
+			kind,
+			path,
+			folder: false,
+			refs: [...refs],
+			outcome: "follows",
+			reach: "linked"
+		});
+	}
+}
+const leafItems = (node) => node.type === "item" && node.children.length === 0 ? [node] : [...node.type === "item" ? [node] : [], ...node.children.flatMap(leafItems)];
+/**
+* The source's top-level tree, one row per node, read against what this config holds at each path.
+*
+* Reads the live source, since the closure only carries what this config already reached and a source
+* with nothing linked would list nothing. Kinds are `borrowableKinds`, the intersection of what the
+* source has and this config can hold. Nothing when no source is attached.
+*/
+function sourceRowStates({ config, slug }) {
+	const source = config.liveSourceFor(slug);
+	if (!source) return [];
+	const derived = config.withDerivedRows();
+	const rows = [];
+	for (const kind of config.borrowableKinds(slug)) for (const node of source.tree(kind)) {
+		const members = leafItems(node).filter((leaf) => config.canBorrow({
+			kind,
+			path: leaf.path,
+			slug
+		}).ok);
+		if (members.length === 0) continue;
+		let linked = 0;
+		let local = 0;
+		let shared = 0;
+		let sharedOrigin;
+		for (const leaf of members) {
+			const held = derived.resolve(kind, leaf.path);
+			if (!held) continue;
+			if (held.borrowedFrom === slug) {
+				linked += 1;
+				continue;
+			}
+			local += 1;
+			const origin = sharedWithOrigin({
+				config: derived,
+				source,
+				slug,
+				kind,
+				path: leaf.path
+			});
+			if (origin !== void 0) {
+				shared += 1;
+				sharedOrigin ??= origin;
+			}
+		}
+		rows.push({
+			kind,
+			path: node.path,
+			type: node.type,
+			name: node.item?.displayLabel ?? node.name,
+			members: members.length,
+			linked: linked === members.length,
+			replaces: local - shared,
+			shared,
+			...sharedOrigin === void 0 ? {} : { sharedOrigin }
+		});
+	}
+	return rows;
+}
+//#endregion
+export { planBreak, planLink, planUnlink, sourceRowStates };