@yahoo/uds-create-config 2.45.0 → 3.0.1

package/dist/framework/source-integrity.js

@@ -0,0 +1,478 @@
+import { collectRefs, isExtendedRef, isRef, kindOf, memberOf, pathOf, sourceOf, splitRef } from "./utils/refs.js";
+import { isPlainObject, setAtPath } from "./utils/field-path.js";
+//#region src/framework/source-integrity.ts
+/**
+* Every `@source` ref in `config` that does not resolve against its attached source.
+*
+* This is the guarantee the emitted types can only approximate. A union narrows what an author can type, but
+* nothing types a Studio-authored patch, a js consumer, or a config whose source moved on since the last
+* install — and an unresolvable ref renders as the empty string, so the stylesheet gets `--x: ;`: syntactically
+* a declaration, semantically nothing, and silent. Precisely the failure mode a build should refuse.
+*
+* Only sourced refs are checked here. A dangling local ref is the dependency graph's own complaint and has its
+* own reporting; this is about the seam between systems, where the other side can change without us.
+*
+* Walks what this config authored, not what it currently resolves to, and the difference is two bugs
+* rather than a nicety. Resolution loses the subject in both directions:
+*
+*   • An extension whose base cannot be found resolves to nothing, so the item drops out of `list` and
+*     the broken ref goes unreported — a build passing on a config whose token has silently vanished.
+*     That is the case a `Token.ref('palette@ds')` naming a group produces, since a group is not an
+*     item and the lookup misses.
+*   • An extension that can be found resolves to its source's fields merged over ours, so the walk sees
+*     the source's refs through the source's slugs. A source that itself borrows made this config
+*     report `@upstream` — a slug it never declared and cannot resolve — and refuse a legitimate chain.
+*
+* The authored body has neither problem: it is exactly the set of refs this config is answerable for.
+*/
+function danglingSourcedRefs(config) {
+	const found = [];
+	/**
+	* Whether a slug is answerable — the three-state question, not the two-state one.
+	*
+	* `sourceStatus` keeps three answers and only two of them are a problem here. Nobody asked
+	* (`undefined`, an ordinary `fromJSON` in an editor) is not a broken ref: the config was never
+	* resolved, so every sourced ref would read as dangling and the report would be noise. Asked and
+	* could not (`unavailable`) is broken, and is exactly what a build must refuse.
+	*
+	* Reading only `liveSourceFor` collapsed those into one, which is why the sole non-build caller —
+	* `orphanedBorrowsFromJSON` in the studio — had to filter its results down to the one slug it had
+	* attached, with a comment explaining that otherwise "its every sourced ref dangles". That filter is
+	* a workaround for this line.
+	*
+	* Both halves are needed, and `sourceStatus` alone is not enough: `registerSources` attaches a
+	* source without recording a state, so a config assembled that way answers `undefined` while
+	* holding a perfectly good source. So the question is whether there is anything to be answerable
+	* against — an attached source, or a resolver's recorded answer.
+	*/
+	const answerable = (slug) => config.liveSourceFor(slug) !== void 0 || config.sourceStatus(slug) !== void 0;
+	for (const kind of config.ownedKinds()) {
+		for (const item of config.authoredItems(kind)) for (const target of collectRefs(item.body)) {
+			const slug = sourceOf(target);
+			if (slug === void 0) continue;
+			if (!answerable(slug)) continue;
+			if (config.liveSourceFor(slug)?.resolve(kindOf(target), pathOf(target))) continue;
+			found.push({
+				from: `${kind}:${item.path}`,
+				ref: target,
+				slug
+			});
+		}
+		for (const group of config.groups(kind)) {
+			const ref = group.meta.ref;
+			if (!isRef(ref)) continue;
+			const slug = sourceOf(ref);
+			if (slug === void 0) continue;
+			if (!answerable(slug)) continue;
+			const path = pathOf(ref);
+			if (config.liveSourceFor(slug)?.members(kind, path).length) continue;
+			found.push({
+				from: `${kind} group:${group.path}`,
+				ref: ref.__ref,
+				slug
+			});
+		}
+	}
+	return found;
+}
+/**
+* Every extended borrow whose merged body this config's kind will not parse.
+*
+* The third way a link can be broken, and the only one that is nobody's mistake: the source resolved
+* perfectly and said something this config has no way to hold. Two config types need not share a
+* value domain — a native modifier activates on `{ state: 'pressed' }` where a web one takes a CSS
+* fragment, a mode, a composite or a list of modes — so the same kind string can name two shapes
+* neither of which contains the other. `mobile-app`'s `size/control` is the same crossing answered
+* rather than broken: `1rem` has no arm in `NativeToken`, and the local `extend: { value: 16 }` is
+* what makes the merged body legal.
+*
+* A report rather than a throw. Reads answer "nothing" for
+* a row they cannot express, because they must: `list`, `sourceClosure` and `toJSON` all reach stored
+* rows, and a throw from inside serialization has no caller in a position to catch it. So the refusal
+* has to live somewhere a caller asks, which is here — a build refuses on it, and a surface says which
+* Entity and which field.
+*
+* Walks what this config authored, for the reason {@link danglingSourcedRefs} does: a row that fails
+* to resolve is absent from `list`, so a walk over resolved entities is a walk with the subject
+* already removed from it.
+*/
+function unreadableBorrows(config) {
+	const found = [];
+	for (const kind of config.ownedKinds()) for (const item of config.authoredItems(kind)) {
+		if (!isExtendedRef(item.body)) continue;
+		const slug = sourceOf(item.body);
+		if (slug === void 0) continue;
+		const verdict = config.canBorrow({
+			kind,
+			path: pathOf(item.body),
+			slug,
+			extend: item.body.extend
+		});
+		if (verdict.ok) continue;
+		found.push({
+			from: `${kind}:${item.path}`,
+			ref: item.body.__ref,
+			slug,
+			error: verdict.error
+		});
+	}
+	return found;
+}
+/**
+* Every sourced ref whose target this config already holds at that path, so the qualifier says
+* nothing the bare path doesn't.
+*
+* A link brings a row per entity it takes, at the path the source spells it, so after the build
+* `token:palette/violet` and `token:palette/violet@ds` are one entity with two names. Two spellings
+* for one thing is what this refuses. It reads as harmless and isn't: the qualified form resolves
+* through the seam, so it breaks the moment the pin is retargeted or dropped while the bare form
+* follows the row wherever it goes, and a config with both in it has half its references surviving the
+* pin's deletion.
+*
+* The one qualified spelling that stays is an entity pointer — `Token.ref('violet@ds').extend({ … })`
+* stored as the row's own body, and a linked folder's `ref`. Both are authored at the local key the
+* bare form would name, so there is nothing else they could say. Everything below that key is a value
+* pointing at another entity, and that is what this walks.
+*
+* A row the pin declares is the subject, never one reachability derived. `sourceClosure` seeds from
+* this config's own refs too, so a hand-written borrow with no `link` declaration derives a row at its
+* target — and telling that author to drop the qualifier would delete the only reason the row exists,
+* leaving a bare ref pointing at nothing. Hence {@link Config.adoptedFrom}: what stands without the
+* ref asking.
+*
+* Walks what this config authored, for the reason {@link danglingSourcedRefs} does — a resolved
+* borrow carries its source's refs through its source's slugs, none of which this config wrote.
+*/
+function redundantQualifiers(config) {
+	const found = [];
+	/**
+	* Whether a row of this config's stands at `path` pointing at the same entity as the ref.
+	*
+	* Nothing here asks whether that row was derived. A row is minted for what a pin adopts and for
+	* nothing else, so a derived row is a declared one — where a row seeded by reachability would have
+	* existed because of the very ref being judged, and telling that author to drop the qualifier would
+	* delete the only reason the row is there.
+	*/
+	const named = (kind, path, slug) => {
+		const pointsHere = (body) => isRef(body) && sourceOf(body) === slug && pathOf(body) === path;
+		return pointsHere(config.storedBody(kind, path)) || pointsHere(config.groupMeta(kind, path)?.ref);
+	};
+	const check = (from, data) => {
+		for (const target of new Set(collectRefs(data))) {
+			if (memberOf(target) !== void 0) continue;
+			const slug = sourceOf(target);
+			if (slug === void 0) continue;
+			const kind = kindOf(target);
+			const path = pathOf(target);
+			if (!named(kind, path, slug)) continue;
+			found.push({
+				from,
+				ref: target,
+				slug,
+				local: `${kind}:${path}`
+			});
+		}
+	};
+	for (const kind of config.ownedKinds()) {
+		for (const item of config.authoredItems(kind)) {
+			let body = item.body;
+			if (isRef(item.body)) body = isExtendedRef(item.body) ? item.body.extend : {};
+			check(`${kind}:${item.path}`, body);
+		}
+		for (const group of config.groups(kind)) {
+			const { ref: _pointer, ...rest } = group.meta;
+			check(`${kind} group:${group.path}`, rest);
+		}
+	}
+	return found;
+}
+function segmentsOf(field) {
+	return typeof field === "string" ? field.split(".") : field;
+}
+/** A leaf is anything that is not a plain object to walk into. A ref is one value, not a shape. */
+function leafEntries(value, prefix = []) {
+	if (!isPlainObject(value) || isRef(value)) return [[prefix, value]];
+	return Object.entries(value).flatMap(([key, child]) => leafEntries(child, [...prefix, key]));
+}
+/** Every leaf address under `body`, as segments, so a member key that contains a dot stays one key. */
+function leafAddresses(body) {
+	return leafEntries(body).map(([address]) => address).filter((address) => address.length > 0);
+}
+/** The value at a leaf address, or `undefined` where the body has none. A ref is one value, not walked into. */
+function valueAt(body, field) {
+	return segmentsOf(field).reduce((at, key) => isPlainObject(at) && !isRef(at) ? at[key] : void 0, body);
+}
+/**
+* The verb one local leaf is against the source's value at the same address: `extend` where the
+* source has nothing there, `override` where it has something different, and `undefined` where
+* nothing local sits there or the two agree. A leaf carried along unchanged is not overlaid: a sub-op
+* copies the whole record it touched into the delta, so a token given one local condition holds the
+* source's other conditions beside it.
+*/
+function leafVerb({ ours, theirs }) {
+	if (ours === void 0) return void 0;
+	if (theirs === void 0) return "extend";
+	return sameValue(ours, theirs) ? void 0 : "override";
+}
+/**
+* Which verb this config's value at `field` is, in the pin's vocabulary — `override` where the source
+* defines the leaf, `extend` where it does not — and `undefined` where nothing local sits there. A
+* record field answers `override` when any member under it does, else `extend` when any was added.
+*/
+function overlayVerb(overlay, field) {
+	if (valueAt(overlay.override, field) !== void 0) return "override";
+	if (valueAt(overlay.extend, field) !== void 0) return "extend";
+}
+/** Structural equality over JSON-shaped values. */
+function sameValue(a, b) {
+	if (a === b) return true;
+	if (Array.isArray(a) && Array.isArray(b)) return a.length === b.length && a.every((item, i) => sameValue(item, b[i]));
+	if (isPlainObject(a) && isPlainObject(b)) {
+		const keys = Object.keys(a);
+		return keys.length === Object.keys(b).length && keys.every((key) => sameValue(a[key], b[key]));
+	}
+	return false;
+}
+/**
+* Every overlay whose verb the source disagrees with — an `extend` at a field they already define, or
+* an `override` at one they do not.
+*
+* The verb is derivable, and this is the derivation. It runs anyway because a declared verb is the
+* only thing that notices the source moving: a field they add in a later version turns an extension
+* into an override, and without the declaration there is nothing for that to contradict. The same
+* check catches the first-order mistake, which is writing an extension for something they already had.
+*
+* Judged leaf by leaf, because one entity legitimately carries both — a token overridden under one
+* modifier and extended under another is one body with two verbs, and a whole-entity comparison would
+* have to call it one or the other.
+*/
+function misdeclaredOverlays(config) {
+	const found = [];
+	for (const slug of config.sourceSlugs()) {
+		const source = config.liveSourceFor(slug);
+		if (!source) continue;
+		for (const { kind, path } of config.sourceDirectives(slug)) {
+			if (kind === void 0) continue;
+			const overlay = config.sourceOverlay(slug, kind, path);
+			if (!overlay) continue;
+			const theirs = source.resolve(kind, path)?.toJSON();
+			for (const field of leafAddresses(overlay.extend)) if (valueAt(theirs, field) !== void 0) found.push({
+				slug,
+				kind,
+				path,
+				declared: "extend",
+				field
+			});
+			for (const field of leafAddresses(overlay.override)) if (valueAt(theirs, field) === void 0) found.push({
+				slug,
+				kind,
+				path,
+				declared: "override",
+				field
+			});
+		}
+	}
+	return found;
+}
+/**
+* Split a merged body into `override`/`extend` by judging each leaf against the source — the forward
+* direction of the walk {@link misdeclaredOverlays} runs to check one. A leaf the source defines
+* differently is an override; one it lacks is an extension; one it spells the same is neither, and is
+* left out.
+*
+* What a directive written this way can never do is trip the check that classified it: every leaf
+* lands on the side the live source agrees it belongs on, by construction.
+*/
+function classifyOverlay(local, theirs) {
+	let override = {};
+	let extend = {};
+	for (const [address, value] of leafEntries(local)) {
+		if (address.length === 0) continue;
+		const verb = leafVerb({
+			ours: value,
+			theirs: valueAt(theirs, address)
+		});
+		if (verb === "override") override = setAtPath(override, address, value);
+		else if (verb === "extend") extend = setAtPath(extend, address, value);
+	}
+	return {
+		...Object.keys(override).length > 0 ? { override } : {},
+		...Object.keys(extend).length > 0 ? { extend } : {}
+	};
+}
+/**
+* Every hide the pin aims at a kind it does not adopt.
+*
+* A hide takes a name back, and a config that never adopted the kind never had it: their entity is
+* reachable only qualified either way, so the entry changes nothing and reads as though it did.
+* Reported rather than ignored, because the fix is usually the missing adoption.
+*
+* An overlay on an unadopted path is a different question and is not this one — it would be laid over
+* a row that is never minted, which is worth reporting too, but the message is about a body rather
+* than about a name.
+*/
+function unadoptedDirectives(config) {
+	const found = [];
+	for (const slug of config.sourceSlugs()) for (const { kind, path } of config.sourceDirectives(slug)) {
+		if (kind === void 0) continue;
+		if (config.sourceStance(slug, kind, path).adopted) continue;
+		if (config.sourceOverlay(slug, kind, path)?.hidden === true) found.push({
+			slug,
+			kind,
+			path,
+			act: "hide"
+		});
+	}
+	return found;
+}
+/**
+* Every directive aimed at nothing — an accessor this config has no kind for, or a path the source
+* does not have.
+*
+* The one mistake the other checks structurally cannot see. Each of them answers for a path it is
+* already holding, so it asks "does the declaration mention this one" — and a name nobody has is
+* never a question anyone puts. `toknes` and `palette/nope` both simply cover nothing, silently, and
+* an overlay that covers nothing looks exactly like one that was never needed.
+*
+* Also what notices the source dropping a path. A directive written against an entity a later version
+* removed keeps parsing and keeps doing nothing, which is the same failure the declared verb exists to
+* catch one level down.
+*/
+function danglingDirectives(config) {
+	const found = [];
+	for (const slug of config.sourceSlugs()) {
+		const source = config.liveSourceFor(slug);
+		if (!source) continue;
+		for (const { kind, accessor, path } of config.sourceDirectives(slug)) {
+			if (kind === void 0) {
+				found.push({
+					slug,
+					accessor,
+					path,
+					missing: "accessor"
+				});
+				continue;
+			}
+			if (source.resolve(kind, path) || source.members(kind, path).length > 0) continue;
+			found.push({
+				slug,
+				accessor,
+				path,
+				missing: "path"
+			});
+		}
+	}
+	return found;
+}
+/**
+* Every borrowed token that varies under a modifier this config does not declare.
+*
+* A borrowed token's conditional values apply under your modifier of that name — so if you don't have the
+* name, the condition is unstatable and the token silently behaves like a lesser version of itself: one
+* colour where the source had two. Refusing is the same rule inlining already enforces; this is the other
+* path to the same place, for a token a consumer references directly rather than one that got inlined.
+*/
+function unstatableConditions(config) {
+	const found = [];
+	for (const slug of config.sourceSlugs()) {
+		const source = config.liveSourceFor(slug);
+		if (!source) continue;
+		for (const target of config.sourceClosure(slug, "token")) {
+			const token = pathOf(target);
+			const { overrides } = source.resolve("token", token)?.toJSON() ?? {};
+			if (!overrides) continue;
+			for (const entry of Object.values(overrides)) {
+				const refs = Array.isArray(entry.on) ? entry.on : [entry.on];
+				for (const ref of refs) {
+					if (!isRef(ref)) continue;
+					const modifier = splitRef(ref.__ref).qualifiedPath;
+					if (config.resolve("modifier", modifier)) continue;
+					found.push({
+						slug,
+						token,
+						modifier
+					});
+				}
+			}
+		}
+	}
+	return found;
+}
+/**
+* Which of this item's own fields point outside the config, and through which slug — the walk behind
+* the `linked` computed the framework installs on every kind.
+*
+* This is the one fact resolution cannot supply, and it is what a provenance surface names: reading a
+* ref is uniform (`resolveFieldValue` chases local and sourced refs identically, which is what makes
+* referencing one feature rather than two), so nothing about the read says a value came from another
+* System. A badge, a link adornment and a "Source" row all want that, and this is where they get it.
+*
+* Not the write gate, which is {@link borrowedSlug}. Naming where a value comes from and deciding
+* whose the entity is are different questions, and this one answers the first: a ref this config
+* declared is ours to retarget however far away it points, so an edit gated on this locks a pointer
+* its own author wrote.
+*
+* Shallow and structural — no field is named and no kind is asked. A ref sitting one level down is a
+* value this item uses, not a claim about the item, so `{ styles: { bg: violet@ds } }` reports nothing
+* while `{ styles: violet@ds }` reports the slug.
+*
+* A local ref reports nothing on purpose. It resolves through the same chase, but it points inside
+* this config, and there is no other system for a surface to name.
+*
+* One kind is asked, not named: a ref at a kind declaring `linkable: false` (`File`) can never be
+* copied in, so the pin stays qualified forever by design — that permanence is an implementation
+* detail of how the item's code loads, not a claim that the item itself still follows the link. A
+* `config` lets this tell the two apart; without one (a bare fixture with no config to ask) every
+* qualified ref still counts, which is the answer this gave before the distinction existed.
+*/
+function sourcedFields(member, config) {
+	const fields = {};
+	for (const [field, value] of Object.entries(member)) {
+		if (!isRef(value)) continue;
+		const slug = sourceOf(value);
+		if (slug === void 0) continue;
+		if (config?.entityOf(kindOf(value))?.linkable === false) continue;
+		fields[field] = slug;
+	}
+	return fields;
+}
+/**
+* The dependencies this item's own fields point through, deduped — the `sources` computed the
+* framework installs on every kind.
+*
+* Which fields borrow is {@link sourcedFields}; which dependencies they borrow from is every
+* provenance surface's question, and it is the same walk. Sorted so the value is stable across field
+* order, because it lands in a memoized entity that dep arrays hold.
+*
+* Usually one slug. Two means the item's fields disagree about where it comes from, and the callers
+* split there rather than here: `Entity.sources.length > 0` says the item draws on something outside
+* this config at all, while `Entity.source` answers `undefined`, because naming one of two would put
+* a confident wrong label on screen.
+*/
+function sourceSlugs(member, config) {
+	return [...new Set(Object.values(sourcedFields(member, config)))].sort();
+}
+/**
+* The dependency this item's stored body is borrowed from — the `borrowedFrom` computed the framework
+* installs on every kind, and the question {@link sourcedFields} cannot answer.
+*
+* An item stored as a ref into a source (`Token.ref('palette/accent@ds').extend({ value: 16 })`) is
+* that source's item, resolved there and shallowly overlaid by the fields named here. An item this
+* Config authored is its own, and stays its own no matter where its fields point.
+*
+* That is the whole distinction, and it is the one a write gate needs. `sources` reports where a
+* value comes from, which is what a provenance badge names — and for a local item holding a sourced
+* ref (`{ value: token:palette/accent@ds }`) it reports the source while the item is ours, so gating
+* an edit on it locks a pointer we declared. Retargeting that pointer is an ordinary local edit; the
+* ref is in our artifact, and nothing on the other side changes when it moves.
+*
+* Reads the stored body rather than the resolved one, because resolution is exactly what erases the
+* difference: an extension resolves to the source's fields merged with ours, and those fields hold
+* whatever literals the source authored — so the resolved item looks local and `sources` on it reads
+* empty. The pointer only exists before the merge.
+*/
+function borrowedSlug(body) {
+	return isRef(body) ? sourceOf(body) : void 0;
+}
+//#endregion
+export { borrowedSlug, classifyOverlay, danglingDirectives, danglingSourcedRefs, leafAddresses, leafVerb, misdeclaredOverlays, overlayVerb, redundantQualifiers, sourceSlugs, unadoptedDirectives, unreadableBorrows, unstatableConditions, valueAt };