@yahoo/uds-create-config 2.44.0 → 3.0.0

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

@@ -0,0 +1,55 @@
+import { Config } from "./Config.js";
+
+//#region src/framework/ref-integrity.d.ts
+/** One ref that names something this config does not have. */
+interface DanglingLocalRef {
+  /** The entity holding the ref — `token:color/accent`. */
+  readonly from: string;
+  /** The ref itself — `token:color/brand`, or `component:Button#props/size` for a member. */
+  readonly ref: string;
+}
+/**
+ * Every local ref in `config` that resolves to nothing, with the entity holding it.
+ *
+ * Walks items and group nodes alike — a group carries authored data too, and the rename cascade
+ * rewrites both, so a check that only read items would call a fixed config broken and a broken one
+ * fixed depending on where the ref sat.
+ */
+declare function danglingLocalRefs(config: Config): DanglingLocalRef[];
+/** One bare leaf in a style bag that names nothing the property accepts. */
+interface UnknownStyleLeaf {
+  /** The entity holding the bag — `component:Card`. */
+  readonly from: string;
+  /** The style property the bag sets — `bg`. */
+  readonly prop: string;
+  /** The leaf as written — `brand`. */
+  readonly leaf: string;
+}
+/**
+ * Every bare leaf in a style bag that names nothing its property accepts.
+ *
+ * The companion to {@link danglingLocalRefs}, for the references that were never refs. A leaf that
+ * resolves gets STORED as a ref (`bindBagTokens` mints one, which is what puts a component's actual
+ * usage in the dep graph); a leaf that resolves to nothing is left as the plain string it is, on
+ * purpose — minting a ref to a token that doesn't exist would be a dangling edge, worse than the
+ * missing one it replaced. The cost of that choice is that the ref graph cannot see the failure, so
+ * `cascadeRename` can never fix it and nothing was reporting it.
+ *
+ * This is the form a hand-authored token rename leaves behind most often, because `bg: 'brand'` is how
+ * most styling is written. It emits a class with no token behind it: dead CSS, and silent.
+ *
+ * Three gates, each one removing a class of false positive, because a check that refuses a valid build
+ * gets deleted rather than fixed:
+ *
+ *  - the KEY must resolve as a style property. A bag may also be keyed by a component's own prop (a
+ *    variant, a composite), whose domain lives elsewhere.
+ *  - the VALUE must be name-shaped. See {@link NAME_SHAPED} — raw literals are ordinary here.
+ *  - the PROP must actually draw on a token group. A colour rename cannot hide behind `cursor`, and
+ *    reporting as if it could is how one rename produced hundreds of warnings nobody could act on.
+ *
+ * Judged against `stylePropValueLeaves`, the same list the emitter and the validator read, so a leaf
+ * this reports is exactly a leaf that paints nothing.
+ */
+declare function unknownStyleLeaves(config: Config): UnknownStyleLeaf[];
+//#endregion
+export { DanglingLocalRef, UnknownStyleLeaf, danglingLocalRefs, unknownStyleLeaves };

package/dist/framework/ref-integrity.js

@@ -0,0 +1,171 @@
+import { collectRefs, kindOf, memberOf, pathOf, sourceOf } from "./utils/refs.js";
+import { cssValueIssue } from "../css/values.js";
+import { stylePropEntries } from "./projections.js";
+//#region src/framework/ref-integrity.ts
+/**
+* Whether a config's LOCAL refs hold — every `{ __ref }` that names something this config was
+* supposed to own, and doesn't.
+*
+* The sourced direction lives in `source-integrity.ts`, because a broken borrow is a fact about the
+* seam between two systems and reads differently: the other side moved. This is the direction where
+* the AUTHOR moved, and it has one cause worth naming.
+*
+* A rename cascades because it is an OPERATION — `Config.apply`'s rename walks the ref index and
+* rewrites every dependent (`cascadeRename`). Editing `uds.config.ts` by hand performs no operation:
+* the config is simply constructed with the new name, so nothing knows the old one existed and every
+* ref to it is left pointing at nothing. Same for a patch stream that reached storage without its
+* cascade, and for a JS consumer assembling a config by hand.
+*
+* What makes it worth refusing rather than reporting: an unresolvable ref renders as the EMPTY
+* STRING. The stylesheet gets `--x: ;` — syntactically a declaration, semantically nothing — and a
+* component's default reads as absent rather than as broken. The build is the last place that can
+* still tell the difference.
+*/
+/**
+* Whether `target` names something this config has.
+*
+* Four ref shapes, and the grammar is not mine to invent — it is the one `memberEntries` reads when it
+* turns a ref into a value domain (`projections.ts`), so a ref this calls broken is exactly a ref that
+* offers no values there:
+*
+*   `motion:`                 a KIND ROOT — "any item of this kind", what a prop declares when the
+*                             things it can name aren't grouped under anything
+*   `token:color/brand`       an ITEM
+*   `token:color`             a GROUP
+*   `icon:phosphor#variants`  a FACET — a field of the group node listing the values
+*   `component:Button#props/size`  a MEMBER of a declared sub-entity collection
+*
+* The kind root and the facet are why this can't be `config.resolve` alone. Both appear in a config
+* that is perfectly well-formed — Box's `motion` prop is `motion:`, Icon's `variant` prop is
+* `icon:phosphor#variants` — and reading either as dangling would refuse every build we ship.
+*
+* Exported because a second caller needs the same answer: a spec node's `type` is one of these refs,
+* and `validateSpec` asking `config.resolve` alone accepted `package:@ariakit/react#Menu` for any
+* module that exists, whatever it exports. Two readings of "resolves" is how one of them goes stale.
+*/
+function refResolves(config, target) {
+	const kind = kindOf(target);
+	const path = pathOf(target);
+	const member = memberOf(target);
+	if (member === void 0 && path === "") return true;
+	if (member === void 0) return config.resolve(kind, path) !== void 0 || config.groups(kind).some((group) => group.path === path);
+	const slash = member.indexOf("/");
+	if (slash === -1) {
+		const group = config.groups(kind).find((entry) => entry.path === path);
+		if (Array.isArray(group?.meta[member])) return true;
+		const bare = config.entityOf(kind)?.bareMember;
+		if (bare === void 0) return false;
+		const collection = config.resolve(kind, path)?.toJSON()?.[bare];
+		return typeof collection === "object" && collection !== null && member in collection;
+	}
+	const collection = (config.resolve(kind, path)?.toJSON())?.[member.slice(0, slash)];
+	if (typeof collection !== "object" || collection === null) return false;
+	return member.slice(slash + 1) in collection;
+}
+/**
+* Every local ref in `config` that resolves to nothing, with the entity holding it.
+*
+* Walks items and group nodes alike — a group carries authored data too, and the rename cascade
+* rewrites both, so a check that only read items would call a fixed config broken and a broken one
+* fixed depending on where the ref sat.
+*/
+function danglingLocalRefs(config) {
+	const found = [];
+	const check = (from, data) => {
+		for (const target of collectRefs(data)) {
+			if (sourceOf(target) !== void 0) continue;
+			if (!config.entityOf(kindOf(target))) continue;
+			if (!refResolves(config, target)) found.push({
+				from,
+				ref: target
+			});
+		}
+	};
+	for (const kind of config.ownedKinds()) {
+		for (const item of config.list(kind)) check(`${kind}:${item.path}`, item.toJSON());
+		for (const group of config.groups(kind)) check(`${kind}:${group.path}`, group.meta);
+	}
+	return found;
+}
+/**
+* A leaf shaped like a NAME — an identifier, not a value.
+*
+* The one distinction that makes this check usable. A style prop with an enumerated domain still
+* accepts a raw CSS value written plainly (`lineHeight: '96px'`, `fontWeight: '300'`, `strokeWidth:
+* '2.5'`); the config we ship is full of them, and reading those as broken names would refuse every
+* build. A stale token name looks nothing like them, so shape is what separates "you meant a token
+* that is gone" from "you meant this literal".
+*/
+const NAME_SHAPED = /^[a-zA-Z][\w-]*$/;
+/**
+* Every bare leaf in a style bag that names nothing its property accepts.
+*
+* The companion to {@link danglingLocalRefs}, for the references that were never refs. A leaf that
+* resolves gets STORED as a ref (`bindBagTokens` mints one, which is what puts a component's actual
+* usage in the dep graph); a leaf that resolves to nothing is left as the plain string it is, on
+* purpose — minting a ref to a token that doesn't exist would be a dangling edge, worse than the
+* missing one it replaced. The cost of that choice is that the ref graph cannot see the failure, so
+* `cascadeRename` can never fix it and nothing was reporting it.
+*
+* This is the form a hand-authored token rename leaves behind most often, because `bg: 'brand'` is how
+* most styling is written. It emits a class with no token behind it: dead CSS, and silent.
+*
+* Three gates, each one removing a class of false positive, because a check that refuses a valid build
+* gets deleted rather than fixed:
+*
+*  - the KEY must resolve as a style property. A bag may also be keyed by a component's own prop (a
+*    variant, a composite), whose domain lives elsewhere.
+*  - the VALUE must be name-shaped. See {@link NAME_SHAPED} — raw literals are ordinary here.
+*  - the PROP must actually draw on a token group. A colour rename cannot hide behind `cursor`, and
+*    reporting as if it could is how one rename produced hundreds of warnings nobody could act on.
+*
+* Judged against `stylePropValueLeaves`, the same list the emitter and the validator read, so a leaf
+* this reports is exactly a leaf that paints nothing.
+*/
+function unknownStyleLeaves(config) {
+	const found = [];
+	const domains = /* @__PURE__ */ new Map();
+	const propertiesOf = (prop) => {
+		const declared = (config.resolve("style-property", prop)?.toJSON())?.properties;
+		return Array.isArray(declared) ? declared : [];
+	};
+	/** The leaves a token-consuming property accepts, or `undefined` when it isn't one to judge. */
+	const domainOf = (prop) => {
+		if (domains.has(prop)) return domains.get(prop);
+		const entries = stylePropEntries(config, prop);
+		const leaves = new Set(entries.map((entry) => entry.leaf));
+		const judge = leaves.size > 0 && entries.some((entry) => entry.value !== void 0 && config.resolve("token", entry.value)) ? leaves : void 0;
+		domains.set(prop, judge);
+		return judge;
+	};
+	for (const kind of config.ownedKinds()) {
+		const sites = config.entityOf(kind)?.styleBags;
+		if (!sites) continue;
+		for (const item of config.list(kind)) {
+			const body = item.toJSON();
+			for (const { bag } of sites(body)) {
+				const own = bag === body.defaultProps ? body.props : void 0;
+				for (const [prop, value] of Object.entries(bag)) {
+					if (typeof value !== "string" || !NAME_SHAPED.test(value)) continue;
+					if (!config.resolve("style-property", prop)) continue;
+					const declared = own?.[prop];
+					if (declared && declared.type !== "styleProperty") continue;
+					const domain = domainOf(prop);
+					if (!domain || domain.has(value)) continue;
+					if (propertiesOf(prop).some((css) => cssValueIssue({
+						property: css,
+						value
+					}) === void 0)) continue;
+					found.push({
+						from: `${kind}:${item.path}`,
+						prop,
+						leaf: value
+					});
+				}
+			}
+		}
+	}
+	return found;
+}
+//#endregion
+export { danglingLocalRefs, refResolves, unknownStyleLeaves };

package/dist/framework/registered.d.ts

@@ -0,0 +1,95 @@
+//#region src/framework/registered.d.ts
+/**
+ * The augmentation points a config's emitted `uds-env.d.ts` fills in.
+ *
+ * All three registries are empty here on purpose. A consumer that has run a build gets an
+ * augmentation declaring what its own system actually contains, and every ref helper narrows to
+ * those paths; a consumer that hasn't still compiles, because an unaugmented interface falls back to
+ * `string`. Type safety appears when there are types to be safe about, and nothing breaks before then.
+ *
+ * This is the whole point of emitting types at all: `Token.ref('color/brnad')` should be a compile error
+ * in a consumer's editor, and a component's `bg` prop should offer that system's colours.
+ */
+/**
+ * Kind → the paths that kind has, as a string union. Filled per config:
+ *
+ * ```ts
+ * declare module '@yahoo/uds-create-config' {
+ *   interface RegisteredPaths {
+ *     token: 'color/brand' | 'spacing/4';
+ *     component: 'Box' | 'Text';
+ *   }
+ * }
+ * ```
+ */
+interface RegisteredPaths {}
+/**
+ * Style prop → the values it accepts, as a string union (including a bracket template literal when the
+ * prop allows off-system values). What a component's JSX props are typed against.
+ */
+interface RegisteredStyleProps {}
+/**
+ * Accessor name → the entity class that accessor addresses. Filled per config:
+ *
+ * ```ts
+ * declare module '@yahoo/uds-create-config' {
+ *   interface RegisteredEntities {
+ *     tokens: typeof Token;
+ *     components: typeof Component;
+ *   }
+ * }
+ * ```
+ *
+ * A field keyed by accessor, whose values are bodies of the kind that accessor addresses — a linked
+ * system's `options`, where `options.tokens['color/brand'].override` is checked against the token
+ * schema. The kind can't be recovered from the key by any type written here: a config file is
+ * accessor-keyed, and the map from accessor to kind belongs to the config type, which the kind
+ * declaring that field is itself a member of — naming it in the schema would be self-referential.
+ *
+ * The emitted file supplies it, like {@link RegisteredPaths}. Unaugmented, the field stays the open
+ * record its schema describes and still compiles.
+ *
+ * Kinds only — the accessor a source is declared under is absent, since a pin is never borrowed
+ * (`EntityKind.linkable`) and so is never something a pin says anything about.
+ */
+interface RegisteredEntities {}
+/**
+ * Qualified linked component path → the component contract installed for that path.
+ *
+ * Unlike {@link RegisteredPaths}, this map is deliberately limited to linked components: a local
+ * `defineComponent` handle already carries its exact declarations in TypeScript, while a ref to a
+ * linked component otherwise carries only a string. The consumer's emitted `uds-env.d.ts` fills the
+ * gap from the installed source config.
+ *
+ * The framework treats the values structurally. `layers` and `props` retain their literal keys and
+ * declarations so `Component.ref('Button@web').extend(...).render(...)` can infer the same render
+ * arguments a locally authored component would.
+ */
+interface RegisteredComponentContracts {}
+/** The generated contract for one qualified linked component, or an open fallback before build. */
+type ComponentContractOf<P extends string> = P extends keyof RegisteredComponentContracts ? RegisteredComponentContracts[P] : {
+  layers: Record<string, unknown>;
+  props: Record<string, unknown>;
+  defaultProps: Record<string, unknown>;
+  forwards: Record<string, unknown>;
+};
+/**
+ * The path type for a kind — its registered union when a config declared one, else `string`.
+ *
+ * The fallback is what keeps this optional: an unaugmented consumer, and every test in this repo, goes
+ * on passing plain strings.
+ *
+ * The `#member` form is admitted on top of the emitted union because a FACET ref
+ * (`Icon.ref('phosphor#variants')`) addresses a field of a group node rather than an entity, so no
+ * path the build enumerates could ever spell it. The entity half still has to be a registered path,
+ * which is the half a typo lands in; what follows the `#` is a field name the kind owns and
+ * `ref-integrity` is what checks it. The `@source` half needs no such widening — a source's paths are
+ * emitted already qualified. A consumer holding a path only known at runtime (a canvas node's type
+ * into whatever system it names) asserts at its own call site rather than this type widening for
+ * every consumer.
+ */
+type PathOf<K extends string> = K extends keyof RegisteredPaths ? RegisteredPaths[K] extends string ? RegisteredPaths[K] | `${RegisteredPaths[K]}#${string}` : string : string;
+/** The value type for a style prop — its registered union, else `string`. */
+type ValueOf<P extends string> = P extends keyof RegisteredStyleProps ? RegisteredStyleProps[P] extends string | number ? RegisteredStyleProps[P] : string : string;
+//#endregion
+export { ComponentContractOf, PathOf, RegisteredComponentContracts, RegisteredEntities, RegisteredPaths, RegisteredStyleProps, ValueOf };

package/dist/framework/registry-dir.d.ts

@@ -0,0 +1,42 @@
+//#region src/framework/registry-dir.d.ts
+/**
+ * Where a project's build directories live, relative to the project root — the registry it pulls
+ * into, the directory it writes to, and the one it is allowed to read from.
+ *
+ * One resolution rule each, shared by every consumer, because a default spelled at the call site is
+ * a default that drifts: `.uds` was written out at eight of them before this.
+ *
+ * The registry half is shared by `uds pull` (writes the registry), `uds build` (regenerates linked
+ * CSS from it), the bundler loaders (skip its files), and the push seal (excludes its files from a
+ * consumer's own sealed sources): `build.registryDir` when the consumer sets one, else the schema's
+ * default at the project root.
+ */
+/** The build setting this reads — structural, so a caller passes `Settings.get(config)?.build`, or
+ *  the bare `build` record of an artifact it never loaded. */
+interface RegistryDirOptions {
+  registryDir?: string;
+}
+/** The build settings the directory resolvers read. Structural for the same reason. */
+interface BuildDirOptions {
+  inputDir?: string;
+  outDir?: string;
+}
+/** Project-root-relative POSIX path of the linked-system registry. */
+declare function resolveRegistryDir(buildOptions: RegistryDirOptions | undefined): string;
+/**
+ * Project-root-relative POSIX path of the build output directory.
+ *
+ * The schema's default unless the system says otherwise. A CLI `--output-dir` overrides both, which is
+ * why this takes only the config: a scratch build is the caller's business, not the system's.
+ */
+declare function resolveOutDir(buildOptions: BuildDirOptions | undefined): string;
+/**
+ * Config-relative POSIX path of the directory every sealed file must live under, or `undefined` when
+ * the system declares none.
+ *
+ * `undefined` is not a default in disguise — it is the answer that keeps the `uds/components/`
+ * anchor convention in charge, so a config that never set this emits exactly what it emitted before.
+ */
+declare function resolveInputDir(buildOptions: BuildDirOptions | undefined): string | undefined;
+//#endregion
+export { resolveInputDir, resolveOutDir, resolveRegistryDir };

package/dist/framework/registry-dir.js

@@ -0,0 +1,48 @@
+import { BUILD_DEFAULTS } from "../configs/build-options.js";
+//#region src/framework/registry-dir.ts
+/**
+* Where a project's build directories live, relative to the project root — the registry it pulls
+* into, the directory it writes to, and the one it is allowed to read from.
+*
+* One resolution rule each, shared by every consumer, because a default spelled at the call site is
+* a default that drifts: `.uds` was written out at eight of them before this.
+*
+* The registry half is shared by `uds pull` (writes the registry), `uds build` (regenerates linked
+* CSS from it), the bundler loaders (skip its files), and the push seal (excludes its files from a
+* consumer's own sealed sources): `build.registryDir` when the consumer sets one, else the schema's
+* default at the project root.
+*/
+/** Scanned rather than matched with `/\/+$/`: anchoring a repeated group at the end makes the engine
+*  backtrack across the whole run, which is quadratic on a path that is all slashes. */
+const normalize = (p) => {
+	const posix = p.replace(/\\/g, "/");
+	let end = posix.length;
+	while (end > 0 && posix[end - 1] === "/") end--;
+	return posix.slice(0, end);
+};
+/** Project-root-relative POSIX path of the linked-system registry. */
+function resolveRegistryDir(buildOptions) {
+	return normalize(buildOptions?.registryDir ?? BUILD_DEFAULTS.registryDir);
+}
+/**
+* Project-root-relative POSIX path of the build output directory.
+*
+* The schema's default unless the system says otherwise. A CLI `--output-dir` overrides both, which is
+* why this takes only the config: a scratch build is the caller's business, not the system's.
+*/
+function resolveOutDir(buildOptions) {
+	return normalize(buildOptions?.outDir ?? BUILD_DEFAULTS.outDir);
+}
+/**
+* Config-relative POSIX path of the directory every sealed file must live under, or `undefined` when
+* the system declares none.
+*
+* `undefined` is not a default in disguise — it is the answer that keeps the `uds/components/`
+* anchor convention in charge, so a config that never set this emits exactly what it emitted before.
+*/
+function resolveInputDir(buildOptions) {
+	if (!buildOptions?.inputDir) return void 0;
+	return normalize(buildOptions.inputDir);
+}
+//#endregion
+export { resolveInputDir, resolveOutDir, resolveRegistryDir };