@yahoo/uds-create-config 2.45.0 → 3.0.1

package/dist/framework/snapshot.d.ts

@@ -0,0 +1,115 @@
+import { Entity } from "./Entity.js";
+import { RefGraph } from "./ref-graph.js";
+import { EntityKind } from "./registry.js";
+
+//#region src/framework/snapshot.d.ts
+/**
+ * How each kind reads the edges its own data implies by NAME — `kind` → its `nameEdges`.
+ *
+ * Kind metadata rather than config state, which is the whole reason a `Snapshot` can hold it: the
+ * readers are fixed once a config has registered its kinds, so no edit can make them stale.
+ */
+type NameEdgeReaders = ReadonlyMap<string, NonNullable<EntityKind['nameEdges']>>;
+/** One kind's stored state. Replaced wholesale when the kind changes, shared by reference when not. */
+interface KindSlice {
+  /** Items, in insertion order — the list a UI maps over. */
+  readonly items: ReadonlyMap<string, Entity>;
+  /** GROUP nodes (a folder's own body), keyed by the group prefix. */
+  readonly groups: ReadonlyMap<string, Entity>;
+  /** Sparse per-member overrides of a DERIVED kind — the only derived data that persists. */
+  readonly overrides: ReadonlyMap<string, Record<string, unknown>>;
+}
+/**
+ * One edit to fold into the next snapshot. `value: undefined` deletes.
+ *
+ * `target` names WHICH of a kind's three stores is addressed, so a group-update and an item update
+ * are the same kind of thing here rather than two code paths.
+ */
+type EntityChange = {
+  kind: string;
+  target: 'item';
+  path: string;
+  value: Entity | undefined;
+} | {
+  kind: string;
+  target: 'group';
+  path: string;
+  value: Entity | undefined;
+} | {
+  kind: string;
+  target: 'override';
+  path: string;
+  value: Record<string, unknown> | undefined;
+};
+declare class Snapshot {
+  #private;
+  private constructor();
+  /**
+   * The same snapshot, reading name-borne edges through `readers` from here on.
+   *
+   * Set once by the `Config` that owns this lineage, from the kinds registered into it — kind
+   * METADATA, which no edit changes, so capturing it is safe in a way capturing a config would not
+   * be. Every derivation below passes it through.
+   *
+   * Re-indexes everything currently held, because the readers decide what the edges ARE: adopting
+   * them without a rebuild would leave items loaded before this call with ref-borne edges only.
+   */
+  withNameEdges(readers: NameEdgeReaders, linkKinds?: readonly string[], singletonKinds?: readonly string[]): Snapshot;
+  /** The empty snapshot — what a freshly constructed config starts from. */
+  static empty(): Snapshot;
+  /**
+   * A snapshot's per-kind slice. Its IDENTITY is stable across any mutation that didn't touch this
+   * kind — that stability is the contract callers memoize on.
+   */
+  slice(kind: string): KindSlice;
+  get(kind: string, path: string): Entity | undefined;
+  has(kind: string, path: string): boolean;
+  values(kind: string): Entity[];
+  group(kind: string, path: string): Entity | undefined;
+  groups(kind: string): ReadonlyMap<string, Entity>;
+  overrides(kind: string): ReadonlyMap<string, Record<string, unknown>>;
+  /** Every kind holding at least one item. Groups alone don't count — matching `ItemStore.kinds()`. */
+  kinds(): string[];
+  /** Every ref in this snapshot, indexed both ways. Built once per snapshot, lazily — most
+   *  mutations never ask, and the index itself was already carried forward incrementally. */
+  get refs(): RefGraph;
+  /**
+   * The next snapshot. Only the kinds named in `changes` get new slices; every other slice is passed
+   * through by reference, which is both the structural sharing and the cache-invalidation signal.
+   */
+  withChanges(changes: readonly EntityChange[]): Snapshot;
+  /**
+   * Move an entity to a new path, KEEPING ITS POSITION in the record.
+   *
+   * Order is key order — from the authored object literal, through the serialized artifact, into the
+   * emitted CSS — so where a key sits is meaning, not incidental. A delete-then-set would put the
+   * renamed entity at the end: a renamed token drops to the bottom of its group, and a renamed group
+   * (which is its members' shared prefix) drops to the bottom of the rail.
+   *
+   * So the map is rebuilt in order with the key swapped in place. A rename ONTO an existing key
+   * collapses onto that key's slot, which is the only sensible reading — there is one key afterwards,
+   * so there is one position.
+   */
+  withRenamed(kind: string, target: 'item' | 'group', from: string, to: string, value: Entity): Snapshot;
+  /**
+   * Rearrange a record's keys — the operation that MOVES something, since order is key order.
+   *
+   * The named keys are permuted among **the slots they already occupy**, and everything unnamed stays
+   * exactly where it is. That is what makes a partial order safe: a drag inside one group names only
+   * that group's entries, and reordering them must not shuffle a neighbouring group past a third one.
+   * For a full order — every key named — this is simply that order.
+   *
+   * A name that is no longer present is skipped rather than refused. A reorder is replayed after the
+   * patches before it, one of which may have deleted something this one names; rejecting would make the
+   * whole patch undroppable for a reason that has nothing to do with what it was trying to do.
+   */
+  withOrder(kind: string, target: 'item' | 'group', order: readonly string[]): Snapshot;
+  /** The wire form the config serializes from — `{ items, groups, overrides }` per kind. */
+  toJSON(): {
+    items: Record<string, Record<string, unknown>>;
+    groups: Record<string, Record<string, unknown>>;
+    overrides: Record<string, Record<string, Record<string, unknown>>>;
+  };
+}
+//#endregion
+export { EntityChange, KindSlice, Snapshot };

package/dist/framework/snapshot.js

@@ -0,0 +1,277 @@
+import { buildRefIndex, refGraphOf, updateRefIndex } from "./ref-graph.js";
+//#region src/framework/snapshot.ts
+/** Whether two link-kind lists say the same thing — the other half of `withNameEdges`' short-circuit. */
+function sameKinds(left, right) {
+	return left.length === right.length && left.every((k, i) => k === right[i]);
+}
+/** Whether two reader maps say the same thing — the identity check that keeps `withNameEdges` free
+*  on the path where a config registers content into kinds it already declared. */
+function sameReaders(left, right) {
+	if (left === right) return true;
+	if (left.size !== right.size) return false;
+	for (const [kind, read] of left) if (right.get(kind) !== read) return false;
+	return true;
+}
+const emptySlice = () => Object.freeze({
+	items: /* @__PURE__ */ new Map(),
+	groups: /* @__PURE__ */ new Map(),
+	overrides: /* @__PURE__ */ new Map()
+});
+/** Apply one change to a mutable draft of a slice. */
+function applyToSlice(draft, change) {
+	let store;
+	if (change.target === "item") store = draft.items;
+	else if (change.target === "group") store = draft.groups;
+	else store = draft.overrides;
+	if (change.value === void 0) store.delete(change.path);
+	else store.set(change.path, change.value);
+}
+var Snapshot = class Snapshot {
+	#nameEdges;
+	/** The kinds a `@slug` resolves against — see `edgesOf`. Kind metadata, captured with the readers
+	*  and for the same reason: no edit can change it. */
+	#linkKinds;
+	/** The kinds whose one item a ref may address by field path — see `edgesOf`. Kind metadata, as
+	*  `#linkKinds` is. */
+	#singletonKinds;
+	#slices;
+	#refIndex;
+	/** Canonical empty slices for kinds this snapshot holds nothing of, so `slice()` is identity-stable
+	*  for them too. Shared along a LINEAGE (derived snapshots inherit the map) but never across
+	*  independent configs — a global singleton would make two unrelated configs that both lack a kind
+	*  collide on one memo key, and each would serve the other's cached result. */
+	#empties;
+	#graph;
+	constructor(slices, refIndex, empties, nameEdges = /* @__PURE__ */ new Map(), linkKinds = [], singletonKinds = []) {
+		this.#slices = slices;
+		this.#refIndex = refIndex;
+		this.#empties = empties;
+		this.#nameEdges = nameEdges;
+		this.#linkKinds = linkKinds;
+		this.#singletonKinds = singletonKinds;
+	}
+	/**
+	* The same snapshot, reading name-borne edges through `readers` from here on.
+	*
+	* Set once by the `Config` that owns this lineage, from the kinds registered into it — kind
+	* METADATA, which no edit changes, so capturing it is safe in a way capturing a config would not
+	* be. Every derivation below passes it through.
+	*
+	* Re-indexes everything currently held, because the readers decide what the edges ARE: adopting
+	* them without a rebuild would leave items loaded before this call with ref-borne edges only.
+	*/
+	withNameEdges(readers, linkKinds = [], singletonKinds = []) {
+		if (sameReaders(this.#nameEdges, readers) && sameKinds(this.#linkKinds, linkKinds) && sameKinds(this.#singletonKinds, singletonKinds)) return this;
+		const entries = [];
+		for (const [kind, slice] of this.#slices) {
+			const read = readers.get(kind);
+			for (const [path, entity] of slice.items) {
+				const data = entity.toJSON();
+				entries.push({
+					ref: `${kind}:${path}`,
+					data,
+					extra: read?.(data)
+				});
+			}
+			for (const [path, entity] of slice.groups) {
+				const data = entity.toJSON();
+				entries.push({
+					ref: `${kind}:${path}`,
+					data,
+					extra: read?.(data)
+				});
+			}
+		}
+		return new Snapshot(this.#slices, buildRefIndex(entries, linkKinds, singletonKinds), this.#empties, readers, linkKinds, singletonKinds);
+	}
+	/** The empty snapshot — what a freshly constructed config starts from. */
+	static empty() {
+		return new Snapshot(/* @__PURE__ */ new Map(), buildRefIndex([]), /* @__PURE__ */ new Map());
+	}
+	/**
+	* A snapshot's per-kind slice. Its IDENTITY is stable across any mutation that didn't touch this
+	* kind — that stability is the contract callers memoize on.
+	*/
+	slice(kind) {
+		const found = this.#slices.get(kind);
+		if (found) return found;
+		let empty = this.#empties.get(kind);
+		if (!empty) {
+			empty = emptySlice();
+			this.#empties.set(kind, empty);
+		}
+		return empty;
+	}
+	get(kind, path) {
+		return this.#slices.get(kind)?.items.get(path);
+	}
+	has(kind, path) {
+		return this.#slices.get(kind)?.items.has(path) ?? false;
+	}
+	values(kind) {
+		return [...this.#slices.get(kind)?.items.values() ?? []];
+	}
+	group(kind, path) {
+		return this.#slices.get(kind)?.groups.get(path);
+	}
+	groups(kind) {
+		return this.slice(kind).groups;
+	}
+	overrides(kind) {
+		return this.slice(kind).overrides;
+	}
+	/** Every kind holding at least one item. Groups alone don't count — matching `ItemStore.kinds()`. */
+	kinds() {
+		const out = [];
+		for (const [kind, slice] of this.#slices) if (slice.items.size > 0) out.push(kind);
+		return out;
+	}
+	/** Every ref in this snapshot, indexed both ways. Built once per snapshot, lazily — most
+	*  mutations never ask, and the index itself was already carried forward incrementally. */
+	get refs() {
+		this.#graph ??= refGraphOf(this.#refIndex);
+		return this.#graph;
+	}
+	/**
+	* The next snapshot. Only the kinds named in `changes` get new slices; every other slice is passed
+	* through by reference, which is both the structural sharing and the cache-invalidation signal.
+	*/
+	withChanges(changes) {
+		if (changes.length === 0) return this;
+		const byKind = /* @__PURE__ */ new Map();
+		for (const change of changes) {
+			const list = byKind.get(change.kind);
+			if (list) list.push(change);
+			else byKind.set(change.kind, [change]);
+		}
+		const slices = new Map(this.#slices);
+		for (const [kind, kindChanges] of byKind) {
+			const current = this.slice(kind);
+			const draft = {
+				items: new Map(current.items),
+				groups: new Map(current.groups),
+				overrides: new Map(current.overrides)
+			};
+			for (const change of kindChanges) applyToSlice(draft, change);
+			slices.set(kind, Object.freeze(draft));
+		}
+		return new Snapshot(slices, updateRefIndex(this.#refIndex, refChanges(changes, this.#nameEdges), this.#linkKinds, this.#singletonKinds), this.#empties, this.#nameEdges, this.#linkKinds, this.#singletonKinds);
+	}
+	/**
+	* Move an entity to a new path, KEEPING ITS POSITION in the record.
+	*
+	* Order is key order — from the authored object literal, through the serialized artifact, into the
+	* emitted CSS — so where a key sits is meaning, not incidental. A delete-then-set would put the
+	* renamed entity at the end: a renamed token drops to the bottom of its group, and a renamed group
+	* (which is its members' shared prefix) drops to the bottom of the rail.
+	*
+	* So the map is rebuilt in order with the key swapped in place. A rename ONTO an existing key
+	* collapses onto that key's slot, which is the only sensible reading — there is one key afterwards,
+	* so there is one position.
+	*/
+	withRenamed(kind, target, from, to, value) {
+		const current = this.slice(kind);
+		const store = target === "item" ? current.items : current.groups;
+		if (!store.has(from)) return this;
+		const rebuilt = /* @__PURE__ */ new Map();
+		for (const [path, entity] of store) if (path === from) rebuilt.set(to, value);
+		else if (path !== to) rebuilt.set(path, entity);
+		const slices = new Map(this.#slices);
+		slices.set(kind, Object.freeze({
+			...current,
+			[target === "item" ? "items" : "groups"]: rebuilt
+		}));
+		return new Snapshot(slices, updateRefIndex(this.#refIndex, [{
+			ref: `${kind}:${from}`,
+			data: void 0
+		}, {
+			ref: `${kind}:${to}`,
+			data: value.toJSON(),
+			extra: this.#nameEdges.get(kind)?.(value.toJSON())
+		}], this.#linkKinds, this.#singletonKinds), this.#empties, this.#nameEdges, this.#linkKinds, this.#singletonKinds);
+	}
+	/**
+	* Rearrange a record's keys — the operation that MOVES something, since order is key order.
+	*
+	* The named keys are permuted among **the slots they already occupy**, and everything unnamed stays
+	* exactly where it is. That is what makes a partial order safe: a drag inside one group names only
+	* that group's entries, and reordering them must not shuffle a neighbouring group past a third one.
+	* For a full order — every key named — this is simply that order.
+	*
+	* A name that is no longer present is skipped rather than refused. A reorder is replayed after the
+	* patches before it, one of which may have deleted something this one names; rejecting would make the
+	* whole patch undroppable for a reason that has nothing to do with what it was trying to do.
+	*/
+	withOrder(kind, target, order) {
+		const current = this.slice(kind);
+		const store = target === "item" ? current.items : current.groups;
+		const moving = order.filter((path) => store.has(path));
+		if (moving.length === 0) return this;
+		const slots = [];
+		const keys = [...store.keys()];
+		keys.forEach((path, index) => {
+			if (moving.includes(path)) slots.push(index);
+		});
+		const redealt = [...keys];
+		slots.forEach((slot, i) => {
+			const path = moving[i];
+			if (path !== void 0) redealt[slot] = path;
+		});
+		const rebuilt = /* @__PURE__ */ new Map();
+		for (const path of redealt) {
+			const entity = store.get(path);
+			if (entity) rebuilt.set(path, entity);
+		}
+		const slices = new Map(this.#slices);
+		slices.set(kind, Object.freeze({
+			...current,
+			[target === "item" ? "items" : "groups"]: rebuilt
+		}));
+		return new Snapshot(slices, this.#refIndex, this.#empties, this.#nameEdges, this.#linkKinds, this.#singletonKinds);
+	}
+	/** The wire form the config serializes from — `{ items, groups, overrides }` per kind. */
+	toJSON() {
+		const items = {};
+		const groups = {};
+		const overrides = {};
+		for (const [kind, slice] of this.#slices) {
+			if (slice.items.size) {
+				items[kind] = {};
+				for (const [path, entity] of slice.items) items[kind][path] = entity.toJSON();
+			}
+			if (slice.groups.size) {
+				groups[kind] = {};
+				for (const [path, entity] of slice.groups) groups[kind][path] = entity.toJSON();
+			}
+			if (slice.overrides.size) overrides[kind] = Object.fromEntries(slice.overrides);
+		}
+		return {
+			items,
+			groups,
+			overrides
+		};
+	}
+};
+/**
+* The ref-index edits a batch of entity changes implies.
+*
+* Items and GROUP nodes both hold refs (an icon library names the component its icons render
+* through), and a group ref is the same `kind:path` shape as an item's — so both are ordinary nodes
+* in the graph. A group path is a strict PREFIX of its items' paths, so the two never collide on one
+* key. Overrides are sparse field patches on a derived kind and contribute no edges.
+*/
+function refChanges(changes, nameEdges) {
+	const out = [];
+	for (const change of changes) {
+		if (change.target === "override") continue;
+		const data = change.value?.toJSON();
+		out.push({
+			ref: `${change.kind}:${change.path}`,
+			data,
+			extra: data === void 0 ? void 0 : nameEdges.get(change.kind)?.(data)
+		});
+	}
+	return out;
+}
+//#endregion
+export { Snapshot };

package/dist/framework/source-integrity.d.ts

@@ -0,0 +1,226 @@
+import { LocalOverlay } from "./sources.js";
+import { Config } from "./Config.js";
+
+//#region src/framework/source-integrity.d.ts
+/** One ref that names something its source does not have. */
+interface DanglingRef {
+  /** The entity holding the ref — `token:color/primary`. */
+  from: string;
+  /** The ref itself — `token:brand/cores@ds`. */
+  ref: string;
+  /** The link it points through. */
+  slug: string;
+}
+/**
+ * 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.
+ */
+declare function danglingSourcedRefs(config: Config): DanglingRef[];
+/** One borrow whose body this config's own kind refuses. */
+interface UnreadableBorrow {
+  /** The entity holding it — `modifier:pressed`. */
+  from: string;
+  /** The pointer it is stored as — `modifier:pressed@mobile-demo`. */
+  ref: string;
+  /** The link it points through. */
+  slug: string;
+  /** Which fields crossed badly, and what that means — {@link Config.canBorrow}'s own sentence. */
+  error: string;
+}
+/**
+ * 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.
+ */
+declare function unreadableBorrows(config: Config): UnreadableBorrow[];
+/** One ref spelled through a link at an entity this config already names locally. */
+interface RedundantQualifier {
+  /** The entity holding the ref — `token:color/brand`, or `token group:palette`. */
+  from: string;
+  /** The ref as written — `token:palette/violet@ds`. */
+  ref: string;
+  /** The link it points through. */
+  slug: string;
+  /** The spelling that names the same entity — `token:palette/violet`. */
+  local: string;
+}
+/**
+ * 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.
+ */
+declare function redundantQualifiers(config: Config): RedundantQualifier[];
+/** A verb the pin declared that the source disagrees with. */
+interface MisdeclaredOverlay {
+  slug: string;
+  kind: string;
+  /** The path as the source spells it. */
+  path: string;
+  /** The verb the pin used. */
+  declared: 'override' | 'extend';
+  /** The field it was wrong about, addressed from the entity body as segments. */
+  field: readonly string[];
+}
+/**
+ * A leaf address: dotted, or spelled as segments where a member key can itself contain a dot (a
+ * compound condition like `dark.lg` is one key under `overrides`).
+ */
+type LeafAddress = string | readonly string[];
+/** Every leaf address under `body`, as segments, so a member key that contains a dot stays one key. */
+declare function leafAddresses(body: unknown): (readonly string[])[];
+/** The value at a leaf address, or `undefined` where the body has none. A ref is one value, not walked into. */
+declare function valueAt(body: unknown, field: LeafAddress): unknown;
+/** The two things a local leaf can be to the source: a value it defines, replaced, or one it lacks, added. */
+type OverlayVerb = 'override' | 'extend';
+/**
+ * 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.
+ */
+declare function leafVerb({
+  ours,
+  theirs
+}: {
+  ours: unknown;
+  theirs: unknown;
+}): OverlayVerb | undefined;
+/**
+ * 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.
+ */
+declare function overlayVerb(overlay: LocalOverlay, field: LeafAddress): OverlayVerb | undefined;
+/**
+ * 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.
+ */
+declare function misdeclaredOverlays(config: Config): MisdeclaredOverlay[];
+/** A directive aimed at a path whose kind the pin never adopted. */
+interface UnadoptedDirective {
+  slug: string;
+  kind: string;
+  path: string;
+  /** Which act the pin declared there. */
+  act: 'hide';
+}
+/**
+ * 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.
+ */
+declare function unadoptedDirectives(config: Config): UnadoptedDirective[];
+/** A directive whose accessor or path reaches nothing. */
+interface DanglingDirective {
+  slug: string;
+  /** The accessor as written — this config may have no kind under it. */
+  accessor: string;
+  path: string;
+  /** `accessor` when no kind is registered under that name, `path` when the source has no such entity. */
+  missing: 'accessor' | 'path';
+}
+/**
+ * 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.
+ */
+declare function danglingDirectives(config: Config): DanglingDirective[];
+/** A borrowed token whose conditional value names a modifier this config does not declare. */
+interface UnstatableCondition {
+  slug: string;
+  /** The source's token path. */
+  token: string;
+  /** The modifier its override names. */
+  modifier: string;
+}
+/**
+ * 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.
+ */
+declare function unstatableConditions(config: Config): UnstatableCondition[];
+//#endregion
+export { DanglingDirective, DanglingRef, LeafAddress, MisdeclaredOverlay, OverlayVerb, RedundantQualifier, UnadoptedDirective, UnreadableBorrow, UnstatableCondition, danglingDirectives, danglingSourcedRefs, leafAddresses, leafVerb, misdeclaredOverlays, overlayVerb, redundantQualifiers, unadoptedDirectives, unreadableBorrows, unstatableConditions, valueAt };