@yahoo/uds-create-config 2.44.0 → 3.0.0

package/dist/entities/system/component-module.js

@@ -0,0 +1,258 @@
+import { ref, splitRef } from "../../framework/utils/refs.js";
+import { Settings } from "./Settings.js";
+import { createSliceMemo } from "../../framework/memo.js";
+import { File } from "./File.js";
+import { Component } from "./Component.js";
+import { contentKey } from "../../framework/utils/content-key.js";
+import { isNativeConfig } from "../../configs/platform.js";
+//#region src/entities/system/component-module.ts
+/**
+* What names a compiled component module: a content key over the module's config-visible build
+* closure. The build stores the artifact under this key and the canvas requests it by the same
+* formula, so "is the stored module current" is never asked: an input edit mints a new key, the
+* request misses, and the miss is the rebuild trigger.
+*/
+/**
+* The shared compiler/runtime contract. Bump whenever codegen can produce different module bytes
+* from identical config-visible inputs (shim contracts, entry shape, transforms, and so on).
+*/
+const COMPONENT_MODULE_BUILD_VERSION = 3;
+/**
+* Generated web runtime inputs shared by every component module. These are intentionally separate
+* from the per-file closure: editing an unrelated component should not invalidate this module, but
+* changing the runtime that interprets its styles must.
+*/
+const WEB_RUNTIME_KINDS = [
+	"style-property",
+	"modifier",
+	"motion",
+	"composite"
+];
+const componentsByFileCache = /* @__PURE__ */ new WeakMap();
+/** Documentation and examples never enter emitted component modules. */
+function buildEntityBody(kind, body) {
+	if (kind !== "component") return body;
+	const { previewProps: _preview, description: _description, ...buildBody } = body;
+	return buildBody;
+}
+/**
+* The generated runtime embedded in every web component module. Config v2 structurally shares
+* unchanged kind slices, so component edits reuse this full-runtime projection without walking it.
+*/
+const componentRuntimeEntitiesKey = createSliceMemo({
+	kinds: WEB_RUNTIME_KINDS,
+	compute: (config) => {
+		const entities = {};
+		const groups = {};
+		for (const kind of WEB_RUNTIME_KINDS) {
+			for (const entity of config.list(kind)) entities[`${kind}:${entity.path}`] = entity.toJSON();
+			for (const group of config.groups(kind)) groups[`${kind}:${group.path}`] = group.meta;
+		}
+		return contentKey({
+			entities,
+			groups
+		});
+	}
+});
+function componentRuntimeKey(config) {
+	return contentKey({
+		version: COMPONENT_MODULE_BUILD_VERSION,
+		name: config.name,
+		settings: Settings.get(config)?.toJSON(),
+		entities: componentRuntimeEntitiesKey(config)
+	});
+}
+/** Every local sealed file -> the components it declares. One file is one module. */
+function componentsByFile(config) {
+	const cached = componentsByFileCache.get(config);
+	if (cached) return cached;
+	const byFile = /* @__PURE__ */ new Map();
+	for (const component of Component.list(config)) {
+		const { file, export: exportName } = component.body;
+		if (!file || !exportName) continue;
+		const ref = splitRef(file.__ref);
+		if (ref.source) continue;
+		const components = byFile.get(ref.path) ?? [];
+		components.push(component);
+		byFile.set(ref.path, components);
+	}
+	componentsByFileCache.set(config, byFile);
+	return byFile;
+}
+/**
+* Component-only imports made by one sealed file, expressed in config-v2's existing identities.
+*
+* `File.imports` already records the authored specifier, resolved File, and imported names;
+* `Component.file` + `Component.export` already say which of those names are registry components.
+* Joining those facts here avoids inventing another dependency graph for incremental modules.
+*/
+function componentRegistryImports(config, filePath) {
+	const file = File.get(config, filePath);
+	if (!file?.imports) return [];
+	const byFile = componentsByFile(config);
+	const imports = [];
+	for (const [specifier, imported] of Object.entries(file.imports)) {
+		if (!imported.target || !imported.names || imported.names.length === 0) continue;
+		const target = splitRef(imported.target.__ref);
+		if (target.kind !== "file" || target.source) continue;
+		const byExport = /* @__PURE__ */ new Map();
+		const ambiguous = /* @__PURE__ */ new Set();
+		for (const component of byFile.get(target.path) ?? []) {
+			const { export: exportName } = component.body;
+			if (!exportName) continue;
+			if (byExport.has(exportName)) ambiguous.add(exportName);
+			byExport.set(exportName, {
+				componentRef: Component.ref(component.path).__ref,
+				exportName
+			});
+		}
+		const bindings = imported.names.flatMap((name) => {
+			if (name === "*" || ambiguous.has(name)) return [];
+			const binding = byExport.get(name);
+			return binding ? [binding] : [];
+		});
+		if (bindings.length !== imported.names.length) continue;
+		imports.push({
+			specifier,
+			targetFilePath: target.path,
+			bindings
+		});
+	}
+	return imports.sort((left, right) => left.specifier.localeCompare(right.specifier));
+}
+function componentModuleBuildPlan(config, filePath) {
+	const byFile = componentsByFile(config);
+	const entities = {};
+	const groups = {};
+	const registryComponents = {};
+	const settings = { own: {
+		name: config.name,
+		settings: Settings.get(config)?.toJSON()
+	} };
+	const visitedComponents = /* @__PURE__ */ new Set();
+	const visitedFiles = /* @__PURE__ */ new Set();
+	const pendingFiles = [filePath];
+	const recordGroups = (owner, source, kind, path) => {
+		if (source) settings[`source:${source}`] ??= {
+			name: owner.name,
+			settings: Settings.get(owner)?.toJSON()
+		};
+		for (const group of owner.groups(kind)) {
+			if (!path.startsWith(`${group.path}/`)) continue;
+			groups[`${source ? `${source}:` : ""}${kind}:${group.path}`] = group.meta;
+		}
+	};
+	const recordEntity = (target) => {
+		const ref = splitRef(target);
+		const owner = ref.source ? config.sourceFor(ref.source) : config;
+		const entity = owner?.resolve(ref.kind, ref.path);
+		if (!owner || !entity) return;
+		const key = `${ref.source ? `${ref.source}:` : ""}${ref.kind}:${ref.path}`;
+		entities[key] = buildEntityBody(ref.kind, entity.toJSON());
+		recordGroups(owner, ref.source, ref.kind, ref.path);
+		if (ref.kind === "file" && !ref.source) pendingFiles.push(ref.path);
+	};
+	const recordRegistryComponent = (target) => {
+		const parsed = splitRef(target);
+		if (parsed.kind !== "component" || parsed.source) return false;
+		const component = Component.get(config, parsed.path);
+		const { file, export: exportName } = component?.body ?? {};
+		if (!component || !file || !exportName) return false;
+		const owner = splitRef(file.__ref);
+		if (owner.kind !== "file" || owner.source) return false;
+		registryComponents[Component.ref(component.path).__ref] = {
+			filePath: owner.path,
+			exportName
+		};
+		return true;
+	};
+	const recordDependencyClosure = (target) => {
+		const parsed = splitRef(target);
+		if (recordRegistryComponent(target)) return;
+		recordEntity(target);
+		if (parsed.kind === "file") return;
+		const owner = parsed.source ? config.sourceFor(parsed.source) : config;
+		if (!owner) return;
+		for (const dependency of owner.dependenciesOf(parsed.kind, parsed.path, { transitive: true })) {
+			const nested = splitRef(dependency);
+			const qualified = parsed.source && !nested.source ? ref(nested.kind, nested.path, parsed.source).__ref : dependency;
+			if (!recordRegistryComponent(qualified)) recordEntity(qualified);
+		}
+	};
+	const recordComponent = (component) => {
+		if (visitedComponents.has(component.path)) return;
+		visitedComponents.add(component.path);
+		recordEntity(`component:${component.path}`);
+		for (const dependency of config.dependenciesOf("component", component.path)) recordDependencyClosure(dependency);
+	};
+	while (pendingFiles.length > 0) {
+		const next = pendingFiles.pop();
+		if (!next || visitedFiles.has(next)) continue;
+		visitedFiles.add(next);
+		const file = File.get(config, next);
+		if (!file?.hash) continue;
+		recordEntity(`file:${next}`);
+		const imports = file.body.imports ?? {};
+		const registryImports = new Map(componentRegistryImports(config, next).map((entry) => [entry.specifier, entry]));
+		for (const [specifier, imported] of Object.entries(imports)) {
+			const registryImport = registryImports.get(specifier);
+			if (registryImport) {
+				for (const binding of registryImport.bindings) recordRegistryComponent(binding.componentRef);
+				continue;
+			}
+			if (imported.target) recordEntity(imported.target.__ref);
+		}
+		for (const component of byFile.get(next) ?? []) recordComponent(component);
+	}
+	return {
+		version: COMPONENT_MODULE_BUILD_VERSION,
+		runtimeKey: componentRuntimeKey(config),
+		settings,
+		entities,
+		groups,
+		registryComponents
+	};
+}
+/**
+* Local sealed files required to rebuild one component module. This is the File half of the exact
+* build plan used by {@link componentModuleKey}: the entry and its statically imported helpers.
+* Component-only imports stop at stable registry refs; package pins and linked-system files stay in
+* the key but have no local bytes for this branch to fetch.
+*/
+function componentModuleFilePaths(config, filePath) {
+	return Object.keys(componentModuleBuildPlan(config, filePath).entities).filter((key) => key.startsWith("file:")).map((key) => key.slice(5)).sort();
+}
+/**
+* One sealed local file's web module key, or `undefined` when the file is not sealed. Stable across
+* clients: the key is a sorted-serialization content hash, so two holders of one config spell it
+* identically.
+*/
+function componentModuleKey(config, filePath) {
+	if (!File.get(config, filePath)?.hash) return void 0;
+	return contentKey(componentModuleBuildPlan(config, filePath));
+}
+/**
+* Resolve a component ref through config-v2's existing Component -> File facts to the independently
+* rebuildable module that owns it. Studio-authored anatomy has no File and linked source files are
+* not owned by this config's branch, so neither claims a local runtime URL.
+*/
+function componentModuleSource(config, componentPathOrRef) {
+	if (isNativeConfig(config)) return void 0;
+	const component = Component.get(config, componentPathOrRef);
+	if (!component) return void 0;
+	const { file, export: exportName } = component.body;
+	if (!file || !exportName) return void 0;
+	const ref = splitRef(file.__ref);
+	if (ref.source) return void 0;
+	const moduleKey = componentModuleKey(config, ref.path);
+	if (!moduleKey) return void 0;
+	return {
+		componentRef: Component.ref(component.path).__ref,
+		filePath: ref.path,
+		moduleKey,
+		exportName,
+		entryExportName: `${exportName}Entry`
+	};
+}
+//#endregion
+export { componentModuleFilePaths, componentModuleKey, componentModuleSource, componentRegistryImports };

package/dist/entities/system/copy-plan.d.ts

@@ -0,0 +1,98 @@
+import { Config, Patch } from "../../framework/Config.js";
+
+//#region src/entities/system/copy-plan.d.ts
+/** `copy`'s own input, as a plan takes it — `path` is the link's slug, spelled as the op spells it. */
+interface CopyPlanInput {
+  readonly path: string;
+  /**
+   * What to take, keyed by accessor: `'*'` for every entry of that kind, or the source's paths, where a
+   * path that names a folder takes its members. `'*'` alone takes every kind the source offers and
+   * this config can hold.
+   */
+  readonly data: '*' | Readonly<Record<string, '*' | readonly string[]>>;
+  /**
+   * What happens at a path this config already holds. `'skip'` (the default) reuses the row and binds
+   * copied refs to it; `'replace'` writes the source's body over a row of yours, and over a row held
+   * through another pin when the call names it. A row the copy only reaches through a ref stays the
+   * other pin's either way.
+   */
+  readonly onConflict?: 'skip' | 'replace';
+}
+/** One entry a source path names: the source's path and where it lands here. */
+interface SourceEntry {
+  readonly from: string;
+  readonly to: string;
+}
+/**
+ * The source's entries one path names: every item of the kind for `'*'`, a folder's members for a
+ * group path, the item itself otherwise. Rows keep the source's own names.
+ */
+declare function sourceEntries({
+  source,
+  kind,
+  path
+}: {
+  /** The source config — the catalogue being drawn from, not the one borrowing. */readonly source: Config;
+  readonly kind: string;
+  readonly path: string;
+}): readonly SourceEntry[];
+/** One row a copy lands. */
+interface CopyPlanRow {
+  readonly kind: string;
+  /** Where it lands here, which is also the path the source spells. */
+  readonly path: string;
+  /**
+   * `create` for a path nothing of yours holds, or one inherited by the pin's declaration; `replace`
+   * for a pointer stored at the path, which becomes the literal it stood for; `overwrite` for a row of
+   * yours, or one held through another pin, that the call asked to write over (`onConflict: 'replace'`).
+   */
+  readonly status: 'create' | 'replace' | 'overwrite';
+  /** Named by the call, as opposed to brought along because something named points at it. */
+  readonly named: boolean;
+}
+/**
+ * What one `copy` call does, as data — the rows that land, the folders whose meta comes with them, and
+ * the rows of yours that copied refs bind to instead of copying over.
+ *
+ * `patches` is the same answer as the write the op makes: the op applies exactly these, so a surface
+ * that plans a copy and the copy it then runs cannot disagree.
+ */
+interface CopyPlan {
+  readonly rows: readonly CopyPlanRow[];
+  readonly folders: readonly {
+    kind: string;
+    path: string;
+  }[];
+  /** Paths this config already holds as its own, which a copied ref points at rather than through the pin. */
+  readonly reused: readonly {
+    kind: string;
+    path: string;
+  }[];
+  /** Rows of this config's own whose refs at a copied entity are respelled bare, so they point at the
+   *  copy rather than through the pin. */
+  readonly rebound: readonly {
+    kind: string;
+    path: string;
+  }[];
+  readonly patches: readonly Patch[];
+}
+/**
+ * What `copy` would do with this input, and the patches that do it.
+ *
+ * A copied row stands on its own: every ref into the source is followed and its target is taken too,
+ * unless this config already holds that path — then the copy points at what is here. A code
+ * component's files come along the same way, so the copy renders from its own rows. A ref through a
+ * third system is theirs to resolve and is left as spelled, and a kind this config can't hold stays
+ * qualified, since the pin survives to answer it.
+ *
+ * Refuses exactly what the op refuses, since the op is this plan applied.
+ */
+declare function planCopy({
+  config,
+  input
+}: {
+  readonly config: Config;
+  readonly input: CopyPlanInput;
+}): CopyPlan;
+//#endregion
+export { CopyPlan, CopyPlanInput, CopyPlanRow, planCopy, sourceEntries };