bref-ui 0.3.0 → 2.0.0

package/cli/installation/exports/utils.ts

@@ -0,0 +1,54 @@
+import type { ExportNamedDeclaration, ExportSpecifier, Pattern } from 'estree';
+
+/**
+ * Read an AST identifier or string-literal name, including TypeScript declaration IDs.
+ * @param node Parser node with a name or string value, or an absent declaration name.
+ * @returns The name, or null when the node does not identify a public name.
+ */
+export const readName = (node: unknown): string | null => {
+	if (typeof node !== 'object' || node === null) return null;
+	if ('name' in node && typeof node.name === 'string') return node.name;
+	return 'value' in node && typeof node.value === 'string' ? node.value : null;
+};
+
+/**
+ * Find a module path only for a direct runtime default re-export.
+ * @param declaration Export list containing the specifier and optional module path.
+ * @param specifier Named export such as default as Button.
+ * @returns Module path, or null for type-only, named or local exports.
+ */
+export const readDefaultReExportPath = (
+	declaration: ExportNamedDeclaration,
+	specifier: ExportSpecifier
+): string | null => {
+	if (
+		('exportKind' in declaration && declaration.exportKind === 'type') ||
+		('exportKind' in specifier && specifier.exportKind === 'type') ||
+		readName(specifier.local) !== 'default'
+	)
+		return null;
+	const module = declaration.source?.value;
+	return typeof module === 'string' ? module : null;
+};
+
+/**
+ * Read variable names from identifiers, defaults, rest and nested destructuring patterns.
+ * @param binding Variable binding pattern from an exported declaration.
+ * @returns Declared names in source order, skipping omitted array elements.
+ */
+export const readBindingNames = (binding: Pattern): string[] => {
+	if (binding.type === 'Identifier') return [binding.name];
+	if (binding.type === 'AssignmentPattern') return readBindingNames(binding.left);
+	if (binding.type === 'RestElement') return readBindingNames(binding.argument);
+	if (binding.type === 'ObjectPattern')
+		return binding.properties.flatMap((property) =>
+			readBindingNames(
+				property.type === 'RestElement' ? property.argument : (property.value as Pattern)
+			)
+		);
+	if (binding.type === 'ArrayPattern')
+		return binding.elements.flatMap((element) =>
+			element === null ? [] : readBindingNames(element)
+		);
+	return [];
+};

package/cli/installation/index.ts

@@ -0,0 +1,35 @@
+import type { RegistryEntry } from '../registry/types.js';
+import { copyFiles } from './copy/index.js';
+import { prepareExports } from './exports/index.js';
+import { prepareSource } from './prepare/index.js';
+import { previewChanges } from './preview/index.js';
+import type { PreviewChange } from './types.js';
+
+/**
+ * Prepare component sources and index.ts, review their changes, then copy approved files.
+ * No destination files are written until review accepts the complete preview.
+ * @param entries Validated dependency-first entries returned by planDependencies.
+ * @param destination Absolute consumer UI directory.
+ * @param review Receive the preview and return approved relative overwrite paths,
+ * including index.ts when it conflicts. Return an empty list to accept without
+ * overwrites, or null to cancel the installation without writing files.
+ * @returns installed after copying completes, or cancelled when review returns null.
+ * Identical files are skipped; accepting an unchanged installation returns installed.
+ * @throws When preparation, preview or review fails, or a conflict lacks approval.
+ * Copy failures propagate and may leave some files copied; writes are not atomic.
+ */
+export const installComponent = async (
+	entries: RegistryEntry[],
+	destination: string,
+	review: (changes: PreviewChange[]) => Promise<string[] | null>
+): Promise<'installed' | 'cancelled'> => {
+	const sources = await prepareSource(entries);
+	const exports = await prepareExports(entries, destination);
+	const files = [...sources, exports];
+	const changes = await previewChanges(files, destination);
+	const overwrites = await review(changes);
+	if (overwrites === null) return 'cancelled';
+
+	await copyFiles(files, destination, overwrites);
+	return 'installed';
+};

package/cli/installation/parser/index.ts

@@ -0,0 +1,29 @@
+import { parse } from 'svelte/compiler';
+import type { ParsedScript } from './types.js';
+import { escapeClosingTags, restoreModulePositions } from './utils.js';
+
+/**
+ * Parse standalone script text with Svelte's existing TypeScript-aware parser.
+ * A synthetic module script exposes imports and exports without compiling or changing text.
+ * @param content Original JavaScript or TypeScript text.
+ * @param filename Source path used in syntax errors.
+ * @returns Top-level statements and the wrapper offset for corrected module positions.
+ * @throws When the script contains invalid syntax or syntax unsupported by Svelte's parser.
+ */
+export const parseScript = (content: string, filename: string): ParsedScript => {
+	const prefix = '<script module lang="ts">';
+	const escaped = escapeClosingTags(content);
+	try {
+		const component = parse(`${prefix}${escaped.content}\n</script>`, { filename, modern: true });
+		const statements = restoreModulePositions(
+			component.module!.content.body,
+			escaped.positions,
+			prefix.length
+		);
+		return { statements, offset: prefix.length };
+	} catch (error) {
+		throw new Error(`${filename}: ${error instanceof Error ? error.message : String(error)}`, {
+			cause: error
+		});
+	}
+};

package/cli/installation/parser/types.ts

@@ -0,0 +1,12 @@
+import type { AST } from 'svelte/compiler';
+
+/** Top-level ESTree statement returned by Svelte's TypeScript-aware parser. */
+export type ScriptStatement = AST.Script['content']['body'][number];
+
+/** Parsed statements and the position adjustment for the synthetic script wrapper. */
+export interface ParsedScript {
+	/** Statements from the original script, including TypeScript declarations. */
+	statements: ScriptStatement[];
+	/** Prefix length to subtract from corrected module positions to address original text. */
+	offset: number;
+}

package/cli/installation/parser/utils.ts

@@ -0,0 +1,45 @@
+import type { ScriptStatement } from './types.js';
+
+/**
+ * Escape literal closing script tags so the synthetic HTML wrapper cannot truncate JavaScript.
+ * @param content Original script; Unicode escapes keep string-literal values unchanged.
+ * @returns Parser text and original positions of the expanded less-than characters.
+ */
+export const escapeClosingTags = (content: string): { content: string; positions: number[] } => ({
+	content: content.replace(/<(?=\/script\s*>)/g, '\\u003c'),
+	positions: [...content.matchAll(/<(?=\/script\s*>)/g)].map((match) => match.index)
+});
+
+/**
+ * Undo escape expansion for import/export module positions used by source rewriting.
+ * @param statements Locally parsed statements; only their module literals need original positions.
+ * @param positions Original escaped character positions, before the wrapper prefix.
+ * @param prefix Length of the synthetic script prefix.
+ * @returns Statements with module start/end positions corrected; literal values stay unchanged.
+ */
+export const restoreModulePositions = (
+	statements: ScriptStatement[],
+	positions: number[],
+	prefix: number
+): ScriptStatement[] =>
+	statements.map((statement) => {
+		if (!('source' in statement) || !statement.source) return statement;
+		const module = statement.source as typeof statement.source & { start: number; end: number };
+		module.start = restorePosition(module.start, positions, prefix);
+		module.end = restorePosition(module.end, positions, prefix);
+		return statement;
+	});
+
+/**
+ * Remove the five extra characters inserted by each earlier Unicode escape.
+ * @param position Position reported in the wrapped and escaped parser input.
+ * @param positions Original escaped character positions.
+ * @param prefix Wrapper prefix length, retained for the caller's final adjustment.
+ * @returns Position before escape expansion, still including the wrapper prefix.
+ */
+const restorePosition = (position: number, positions: number[], prefix: number): number =>
+	position -
+	positions.reduce(
+		(count, start, index) => count + (start + prefix + index * 5 < position ? 5 : 0),
+		0
+	);

package/cli/installation/prepare/collect-source-files.ts

@@ -0,0 +1,15 @@
+import type { RegistryEntry } from '../../registry/types.js';
+import type { SourceFile } from './types.js';
+
+/**
+ * Build source and destination-relative paths in dependency and manifest order.
+ * @param entries Dependency-first entries returned by planDependencies.
+ * @returns Each source path paired with its destination-relative path.
+ */
+export const collectSourceFiles = (entries: RegistryEntry[]): SourceFile[] =>
+	entries.flatMap((entry) =>
+		entry.files.map((file) => ({
+			source: `${entry.directory}/${file}`,
+			path: `${entry.directory.split('/').filter(Boolean).at(-1)}/${file}`
+		}))
+	);

package/cli/installation/prepare/index.ts

@@ -0,0 +1,15 @@
+import type { RegistryEntry } from '../../registry/types.js';
+import type { PreparedFile } from '../types.js';
+import { collectSourceFiles } from './collect-source-files.js';
+import { readSourceFiles } from './read-source-files.js';
+
+/**
+ * Read planned sources and redirect uncopied local type imports to bref-ui/types.
+ * @param entries Dependency-first entries returned by planDependencies.
+ * @returns Prepared files in entry and manifest order, retaining source folder names.
+ * @throws When a file cannot be read or parsed, or a local import mixes types and values.
+ */
+export const prepareSource = async (entries: RegistryEntry[]): Promise<PreparedFile[]> => {
+	const sources = collectSourceFiles(entries);
+	return readSourceFiles(sources);
+};

package/cli/installation/prepare/read-source-files.ts

@@ -0,0 +1,21 @@
+import type { PreparedFile } from '../types.js';
+import type { SourceFile } from './types.js';
+import { rewriteSource } from './rewrite-source.js';
+
+/**
+ * Read and prepare source files concurrently while retaining input order.
+ * @param files Source paths and their destination-relative paths.
+ * @returns Prepared files in the supplied order.
+ * @throws When a source cannot be read or its contents cannot be prepared.
+ */
+export const readSourceFiles = async (files: SourceFile[]): Promise<PreparedFile[]> =>
+	Promise.all(
+		files.map(async ({ source, path }) => ({
+			path,
+			content: rewriteSource(
+				await Bun.file(source).text(),
+				source,
+				files.map((file) => file.source)
+			)
+		}))
+	);

package/cli/installation/prepare/rewrite-imports.ts

@@ -0,0 +1,50 @@
+import { dirname, resolve } from 'node:path';
+import { parseScript } from '../parser/index.js';
+
+/**
+ * Replace only the module text of relative, type-only imports.
+ * @param content Script content to parse as TypeScript.
+ * @param filename Source path included in preparation errors.
+ * @param copiedFiles Source files copied alongside this file, whose relative imports stay local.
+ * @returns Script text preserving import syntax, quotes, formatting and runtime imports.
+ * @throws When syntax is invalid or a relative non-component import mixes type and value specifiers.
+ */
+export const rewriteImports = (
+	content: string,
+	filename: string,
+	copiedFiles: readonly string[] = []
+): string => {
+	const { statements, offset } = parseScript(content, filename);
+	return statements.reduceRight((source, statement) => {
+		if (statement.type !== 'ImportDeclaration' || typeof statement.source.value !== 'string')
+			return source;
+
+		const module = statement.source;
+		const path = module.value as string;
+		if (!/^\.{1,2}\//.test(path) || path.endsWith('.svelte')) return source;
+		const importedFile = resolve(dirname(filename), path);
+		if (
+			copiedFiles.some((file) => {
+				const copiedFile = resolve(file);
+				return copiedFile === importedFile || copiedFile === importedFile.replace(/\.js$/, '.ts');
+			})
+		)
+			return source;
+		const specifiers = statement.specifiers;
+		if (specifiers.length === 0) return source;
+
+		const namedTypes = specifiers.filter((item) => item.type === 'ImportSpecifier');
+		const onlyTypes =
+			('importKind' in statement && statement.importKind === 'type') ||
+			(namedTypes.length === specifiers.length &&
+				namedTypes.every((item) => 'importKind' in item && item.importKind === 'type'));
+		if (!onlyTypes) {
+			if (namedTypes.some((item) => 'importKind' in item && item.importKind === 'type'))
+				throw new Error(`${filename}: separate type and value imports from "${path}".`);
+			return source;
+		}
+
+		const { start, end } = module as typeof module & { start: number; end: number };
+		return source.slice(0, start - offset + 1) + 'bref-ui/types' + source.slice(end - offset - 1);
+	}, content);
+};

package/cli/installation/prepare/rewrite-source.ts

@@ -0,0 +1,36 @@
+import { parse } from 'svelte/compiler';
+import { rewriteImports } from './rewrite-imports.js';
+
+/**
+ * Rewrite imports only within scripts, preserving markup, CSS and all other text.
+ * @param content Original file content.
+ * @param filename Source path used to select the parser and report errors.
+ * @param copiedFiles Source files copied alongside this file, whose relative imports stay local.
+ * @returns Content with local type module specifiers replaced.
+ * @throws When Svelte parsing or import preparation fails.
+ */
+export const rewriteSource = (
+	content: string,
+	filename: string,
+	copiedFiles: readonly string[] = []
+): string => {
+	if (!filename.endsWith('.svelte'))
+		return /\.[cm]?[jt]s$/.test(filename)
+			? rewriteImports(content, filename, copiedFiles)
+			: content;
+
+	const component = parse(content, { filename, modern: true });
+	const scripts = [component.module, component.instance]
+		.filter((script) => script !== null && script !== undefined)
+		.map((script) => script.content as typeof script.content & { start: number; end: number })
+		.sort((left, right) => right.start - left.start);
+
+	return scripts.reduce((source, script) => {
+		const { start, end } = script;
+		return (
+			source.slice(0, start) +
+			rewriteImports(source.slice(start, end), filename, copiedFiles) +
+			source.slice(end)
+		);
+	}, content);
+};

package/cli/installation/prepare/types.ts

@@ -0,0 +1,7 @@
+/** A canonical source path paired with its consumer-relative destination path. */
+export interface SourceFile {
+	/** Source path in the current workspace. */
+	source: string;
+	/** Destination path relative to the configured UI directory. */
+	path: string;
+}

package/cli/installation/preview/compare-prepared-files.ts

@@ -0,0 +1,18 @@
+import type { PreparedFile, PreviewChange } from '../types.js';
+import type { DestinationFile } from './types.js';
+
+/**
+ * Compare each prepared file with the destination result at the same position.
+ * @param files Prepared sources in caller order.
+ * @param existingFiles Destination results in the same order as files.
+ * @returns Addition, unchanged or conflict statuses in prepared-file order.
+ */
+export const comparePreparedFiles = (
+	files: PreparedFile[],
+	existingFiles: DestinationFile[]
+): PreviewChange[] =>
+	files.map(({ path, content }, index) => {
+		const existing = existingFiles[index];
+		if (!existing.exists) return { path, status: 'add' };
+		return { path, status: existing.content === content ? 'unchanged' : 'conflict' };
+	});

package/cli/installation/preview/index.ts

@@ -0,0 +1,18 @@
+import type { PreparedFile, PreviewChange } from '../types.js';
+import { comparePreparedFiles } from './compare-prepared-files.js';
+import { readDestinationFiles } from './read-destination-files.js';
+
+/**
+ * Compare prepared sources with destination files without writing changes.
+ * @param files Prepared files with paths relative to the destination directory.
+ * @param destination Consumer project's configured UI directory.
+ * @returns Addition, unchanged or conflict statuses in prepared-file order.
+ * @throws When an existing destination file cannot be read.
+ */
+export const previewChanges = async (
+	files: PreparedFile[],
+	destination: string
+): Promise<PreviewChange[]> => {
+	const existingFiles = await readDestinationFiles(files, destination);
+	return comparePreparedFiles(files, existingFiles);
+};

package/cli/installation/preview/read-destination-files.ts

@@ -0,0 +1,25 @@
+import type { PreparedFile } from '../types.js';
+import type { DestinationFile } from './types.js';
+
+/**
+ * Read destination files concurrently while preserving prepared-file order.
+ * @param files Prepared files whose destination paths should be inspected.
+ * @param destination Consumer project's configured UI directory.
+ * @returns Existing contents, or a missing marker, for each prepared file.
+ * @throws When a destination file cannot be read for a reason other than ENOENT.
+ */
+export const readDestinationFiles = async (
+	files: PreparedFile[],
+	destination: string
+): Promise<DestinationFile[]> =>
+	Promise.all(
+		files.map(async ({ path }): Promise<DestinationFile> => {
+			try {
+				return { path, exists: true, content: await Bun.file(`${destination}/${path}`).text() };
+			} catch (error) {
+				if (error instanceof Error && 'code' in error && error.code === 'ENOENT')
+					return { path, exists: false };
+				throw error;
+			}
+		})
+	);

package/cli/installation/preview/types.ts

@@ -0,0 +1,9 @@
+/** Read result for one destination path. */
+export interface DestinationFile {
+	/** Destination path relative to the configured UI directory. */
+	path: string;
+	/** Whether the destination file exists. */
+	exists: boolean;
+	/** Existing file content, present when the file exists. */
+	content?: string;
+}

package/cli/installation/types.ts

@@ -0,0 +1,15 @@
+/** Component source or index.ts ready for preview and copying into the consumer project. */
+export interface PreparedFile {
+	/** Destination path relative to the configured UI directory. */
+	path: string;
+	/** Prepared content, including rewritten source imports or merged component exports. */
+	content: string;
+}
+
+/** Result of comparing one prepared source against its destination file. */
+export interface PreviewChange {
+	/** Destination path relative to the configured UI directory. */
+	path: string;
+	/** Whether the file is absent, identical or contains different content. */
+	status: 'add' | 'unchanged' | 'conflict';
+}

package/cli/pack.ts

@@ -0,0 +1,6 @@
+import { loadRegistry } from './registry/load/index.js';
+
+/** Validate the canonical registry before assembling the local package. */
+const sourceRoot = Bun.fileURLToPath(new URL('../src/lib/', import.meta.url));
+const registry = await loadRegistry(sourceRoot);
+console.log(`Validated ${registry.size} registry entries for packaging.`);

package/cli/registry/load/create-registry.ts

@@ -0,0 +1,25 @@
+import type { RegistryEntry } from '../types.js';
+
+/**
+ * Index entries while enforcing globally unique component IDs and export names.
+ * @param entries Loaded entries in discovery order.
+ * @returns A catalogue keyed by component ID, preserving entry order.
+ * @throws When a component ID or export name appears more than once.
+ */
+export const createRegistry = (entries: RegistryEntry[]): Map<string, RegistryEntry> => {
+	const exports = new Set<string>();
+
+	return entries.reduce((registry, entry) => {
+		const manifest = `${entry.directory}/registry.json`;
+		if (registry.has(entry.id))
+			throw new Error(`${manifest}: duplicate component ID "${entry.id}".`);
+
+		Object.keys(entry.exports).forEach((name) => {
+			if (exports.has(name)) throw new Error(`${manifest}: duplicate component export "${name}".`);
+			exports.add(name);
+		});
+
+		registry.set(entry.id, entry);
+		return registry;
+	}, new Map<string, RegistryEntry>());
+};

package/cli/registry/load/discover-manifests.ts

@@ -0,0 +1,9 @@
+/**
+ * Find registry manifests one folder below the source root.
+ * @param sourceRoot Directory to scan.
+ * @returns Sorted manifest paths prefixed with the source root.
+ */
+export const discoverManifests = (sourceRoot: string): string[] =>
+	Array.from(new Bun.Glob('*/registry.json').scanSync({ cwd: sourceRoot }))
+		.sort()
+		.map((path) => `${sourceRoot}/${path}`);

package/cli/registry/load/index.ts

@@ -0,0 +1,21 @@
+import type { RegistryEntry } from '../types.js';
+import { createRegistry } from './create-registry.js';
+import { discoverManifests } from './discover-manifests.js';
+import { loadEntry } from './load-entry.js';
+import { validateDependencies } from './validate-dependencies.js';
+
+/**
+ * Load and validate the component catalogue without writing files.
+ * @param sourceRoot Directory containing immediate component folders.
+ * @returns Entries keyed by component ID, in sorted manifest-path order.
+ * @throws When manifests cannot be read, metadata or files are invalid,
+ * IDs or exports collide, or dependencies are missing or circular.
+ */
+export const loadRegistry = async (sourceRoot: string): Promise<Map<string, RegistryEntry>> => {
+	const manifests = discoverManifests(sourceRoot);
+	const entries = await Promise.all(manifests.map(loadEntry));
+	const registry = createRegistry(entries);
+	validateDependencies(registry);
+
+	return registry;
+};

package/cli/registry/load/load-entry.ts

@@ -0,0 +1,22 @@
+import type { RegistryEntry } from '../types.js';
+import { parseItem } from './utils.js';
+
+/**
+ * Read a manifest, validate its metadata and check that listed files exist.
+ * @param manifest Path to a component's registry.json.
+ * @returns Validated metadata with its containing directory.
+ * @throws When the manifest cannot be read, metadata is invalid or a file is missing.
+ */
+export const loadEntry = async (manifest: string): Promise<RegistryEntry> => {
+	const item = parseItem(await Bun.file(manifest).json(), manifest);
+	const directory = manifest.slice(0, -'/registry.json'.length);
+
+	await Promise.all(
+		item.files.map(async (file) => {
+			if (!(await Bun.file(`${directory}/${file}`).exists()))
+				throw new Error(`${manifest}: missing file "${file}".`);
+		})
+	);
+
+	return { ...item, directory };
+};

package/cli/registry/load/utils.ts

@@ -0,0 +1,70 @@
+import type { RegistryItem } from '../types.js';
+
+/**
+ * Check for a lowercase kebab-case identifier beginning with a letter.
+ * @param value Unvalidated manifest value.
+ * @returns Whether the value is a valid component ID.
+ */
+const isId = (value: unknown): value is string =>
+	typeof value === 'string' && /^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/.test(value);
+
+/**
+ * Check for a relative, slash-separated path without empty, dot or parent segments.
+ * Backslashes and colons are rejected; filesystem symlinks are not resolved.
+ * @param value Unvalidated manifest value.
+ * @returns Whether the path satisfies the registry's lexical path rules.
+ */
+const isRelativeFile = (value: unknown): value is string =>
+	typeof value === 'string' &&
+	!value.includes('\\') &&
+	!value.includes(':') &&
+	value.split('/').every((part) => part !== '' && part !== '.' && part !== '..');
+
+/**
+ * Validate manifest fields, including unique files and dependencies and exports
+ * referencing listed files. File existence and dependency graphs are checked later.
+ * @param value Decoded JSON to validate.
+ * @param manifest Manifest path used in error messages.
+ * @returns The validated manifest object.
+ * @throws When any required field has an invalid shape or value.
+ */
+export const parseItem = (value: unknown, manifest: string): RegistryItem => {
+	if (typeof value !== 'object' || value === null || Array.isArray(value))
+		throw new Error(`${manifest}: expected a registry item object.`);
+
+	if (!('id' in value) || !isId(value.id))
+		throw new Error(`${manifest}: "id" must be a kebab-case identifier.`);
+
+	if (
+		!('files' in value) ||
+		!Array.isArray(value.files) ||
+		value.files.length === 0 ||
+		!value.files.every(isRelativeFile) ||
+		new Set(value.files).size !== value.files.length
+	)
+		throw new Error(`${manifest}: "files" must contain unique relative file paths.`);
+	const files = value.files;
+
+	if (
+		!('exports' in value) ||
+		typeof value.exports !== 'object' ||
+		value.exports === null ||
+		Array.isArray(value.exports) ||
+		Object.keys(value.exports).length === 0 ||
+		!Object.entries(value.exports).every(
+			([name, file]) =>
+				/^[A-Z][a-zA-Z0-9]*$/.test(name) && typeof file === 'string' && files.includes(file)
+		)
+	)
+		throw new Error(`${manifest}: "exports" must map component names to listed files.`);
+
+	if (
+		!('dependencies' in value) ||
+		!Array.isArray(value.dependencies) ||
+		!value.dependencies.every(isId) ||
+		new Set(value.dependencies).size !== value.dependencies.length
+	)
+		throw new Error(`${manifest}: "dependencies" must contain unique component IDs.`);
+
+	return value as RegistryItem;
+};

package/cli/registry/load/validate-dependencies.ts

@@ -0,0 +1,33 @@
+import type { RegistryEntry } from '../types.js';
+
+/**
+ * Traverse dependency chains to reject missing components and cycles.
+ * @param registry Catalogue to validate; its entries and order remain unchanged.
+ * @throws When a dependency ID is unknown or a dependency chain is circular.
+ */
+export const validateDependencies = (registry: Map<string, RegistryEntry>): void => {
+	/** Component IDs in the current recursive dependency chain. */
+	const visiting = new Set<string>();
+	/** Component IDs whose dependency chains have already passed validation. */
+	const visited = new Set<string>();
+
+	/**
+	 * Validate one component and its dependencies, skipping completed checks.
+	 * @param id Component ID to visit.
+	 * @throws When the ID is missing or already belongs to the active chain.
+	 */
+	const visit = (id: string): void => {
+		if (visiting.has(id)) throw new Error(`Circular registry dependency at "${id}".`);
+		if (visited.has(id)) return;
+
+		const entry = registry.get(id);
+		if (!entry) throw new Error(`Unknown registry dependency "${id}".`);
+
+		visiting.add(id);
+		entry.dependencies.forEach(visit);
+		visiting.delete(id);
+		visited.add(id);
+	};
+
+	registry.forEach((entry) => visit(entry.id));
+};

package/cli/registry/plan/collect-entries.ts

@@ -0,0 +1,28 @@
+import type { RegistryEntry } from '../types.js';
+
+/**
+ * Collect dependency entries before their dependent component.
+ * @param id Component ID to collect.
+ * @param registry Catalogue to resolve IDs against.
+ * @param planned Component IDs already included in this plan's traversal.
+ * @returns Ordered entries, or an empty list when the component was already included.
+ * @throws When the component ID is absent from the catalogue.
+ */
+export const collectEntries = (
+	id: string,
+	registry: Map<string, RegistryEntry>,
+	planned: Set<string>
+): RegistryEntry[] => {
+	if (planned.has(id)) return [];
+
+	const entry = registry.get(id);
+	if (!entry) throw new Error(`Unknown registry component "${id}".`);
+
+	planned.add(id);
+	return [
+		...entry.dependencies.flatMap((dependencyId) =>
+			collectEntries(dependencyId, registry, planned)
+		),
+		entry
+	];
+};