svelte-kit-vice/uix.aliases.js

/**
 * The framework's import map — ONE table for every tool that resolves a `$…`
 * or `@/` specifier: `vite.config.ts` (dev, build, both vitest projects),
 * `svelte.config.js` (Kit writes it into `.svelte-kit/tsconfig.json` and hands
 * it to Vite), `scripts/generate-boot.ts` (esbuild), `scripts/docs-check.ts`
 * (invariant 8), and any app in this workspace that consumes the framework as
 * source (`docs/consuming.md`).
 *
 * It is `.js` with JSDoc, not `.ts`: Node loads `svelte.config.js` with no
 * bundler, and that file imports this one.
 *
 * ORDER IS LOAD-BEARING. Vite and esbuild match a string alias as a prefix
 * (`$svrs` also matches `$svrs/auth/testing`) and SvelteKit hands them over in
 * insertion order, so a longer specifier must come before any key that is its
 * prefix. `src/uix/aliases.test.ts` fails if it does not.
 */
import { resolve } from 'node:path';

/**
 * Specifier → path relative to the repository root.
 *
 * @type {Readonly<Record<string, string>>}
 */
export const UIX_ALIASES = Object.freeze({
	// ── Runtime artifacts (src/arts) ──────────────────────────────────────
	'$active-app': 'src/arts/active-app',
	$adom: 'src/arts/adom',
	$agent: 'src/arts/agent',
	$auth: 'src/arts/auth',
	$bus: 'src/arts/bus',
	$cache: 'src/arts/cache',
	$clipboard: 'src/arts/clipboard',
	$color: 'src/arts/color',
	$connection: 'src/arts/connection',
	$ethereal: 'src/arts/ethereal',
	$format: 'src/arts/format',
	$http: 'src/arts/http',
	$langs: 'src/arts/langs',
	$logger: 'src/arts/logger',
	$motion: 'src/arts/motion',
	$orca: 'src/arts/orca',
	$perf: 'src/arts/perf',
	$perm: 'src/arts/perm',
	$prefs: 'src/arts/prefs',
	$scene: 'src/arts/scene',
	$session: 'src/arts/session',
	$sium: 'src/arts/sium',
	$sound: 'src/arts/sound',
	$storage: 'src/arts/storage',
	$timer: 'src/arts/timer',

	// ── Pure helpers (src/libs) ───────────────────────────────────────────
	$libs: 'src/libs',
	$locale: 'src/libs/locale',
	$reactive: 'src/libs/reactive',

	// ── Encapsulated opt-in packs (src/packs) ─────────────────────────────
	$packs: 'src/packs',

	// ── Server-authoritative engines (src/svrs) ───────────────────────────
	//    The GATE of each engine is a native SvelteKit server-only module
	//    (`*.server.ts`), so the alias points at the file and no consumer
	//    import changes. Longest specifier first: these are prefix matches.
	'$svrs/auth/testing': 'src/svrs/auth/testing.server.ts',
	'$svrs/auth': 'src/svrs/auth/index.server.ts',
	$svrs: 'src/svrs',

	// ── UIX layers (src/uix) ──────────────────────────────────────────────
	$uix: 'src/uix',
	'$active-uix': 'src/uix/active-uix',
	$soma: 'src/uix/soma',

	// ── Blocks tier (src/uix/blocks) — page-function compositions ─────────
	$blocks: 'src/uix/blocks',

	// ── Demo controls (src/lib/_demo) — the frozen docs site's widgets ────
	$demo: 'src/lib/_demo',

	// ── @/ catch-all ──────────────────────────────────────────────────────
	'@': 'src'
});

/**
 * The same table with absolute paths, in table order.
 *
 * @param {string} root Absolute path of the repository root.
 * @returns {Record<string, string>}
 */
export function resolveUixAliases(root) {
	return Object.fromEntries(
		Object.entries(UIX_ALIASES).map(([specifier, path]) => [specifier, resolve(root, path)])
	);
}