An open source design system that's fully customizable and agent ready
TypeScript
// Copyright (c) Meta Platforms, Inc. and affiliates.
/**
* @file Shared module-loading + conventional-file-discovery primitives.
*
* Both config loading and integration loading need to (a) import a
* user-authored module (`.ts` via jiti, `.mjs`/`.js` via native dynamic
* import) and (b) find conventional files by basename in a fixed
* load-precedence order. Generated theme artifacts also use a dedicated jiti
* path that resolves extensionless JSX/TSX registry imports and loads the
* stylesheets they import as empty modules. These helpers centralize that
* behavior so callers stay in lockstep. A module's stdout writes go to stderr
* while it loads, so project code that prints cannot corrupt a `--json`
* envelope.
*
* `loadModuleWithParser` builds on these primitives to provide the single
* load/validation boundary shared by config, integration, codemod, and
* template discovery: import the module, take its default export, and hand it
* to the authoring parser (which seals its own zod schema).
*/
import * as path from 'node:path';
import {AsyncLocalStorage} from 'node:async_hooks';
import {createRequire} from 'node:module';
import {pathToFileURL} from 'node:url';
import * as fs from 'node:fs';
import {createJiti} from 'jiti';
import {findPresentFiles} from './present-files.mjs';
export {findPresentFiles};
/** @type {ReturnType<typeof createJiti> | undefined} */
let jitiInstance;
let freshImportNonce = 0;
const requireFromHere = createRequire(import.meta.url);
function getJiti() {
if (!jitiInstance) {
jitiInstance = createJiti(import.meta.url);
}
return jitiInstance;
}
let loadsInFlight = 0;
/** @type {typeof process.stdout.write | undefined} */
let realStdoutWrite;
/** Set in the async context of a module load, and only there. */
const moduleLoad = new AsyncLocalStorage();
/**
* Run a module load with the stdout writes made in its async context sent to
* stderr. Writes from any other context pass through, so the CLI's own output
* stays on stdout even while an abandoned load is still in flight. The gate
* is installed for the first overlapping load and removed after the last.
* @template T
* @param {() => Promise<T>} load
* @returns {Promise<T>}
*/
async function withStdoutOnStderr(load) {
if (loadsInFlight++ === 0) {
const write = process.stdout.write;
realStdoutWrite = write;
process.stdout.write = /** @type {any} */ (
function (/** @type {any} */ chunk, /** @type {any[]} */ ...rest) {
return moduleLoad.getStore()
? process.stderr.write(chunk, ...rest)
: write.call(process.stdout, chunk, ...rest);
}
);
}
try {
return await moduleLoad.run(true, load);
} finally {
if (--loadsInFlight === 0 && realStdoutWrite) {
process.stdout.write = realStdoutWrite;
realStdoutWrite = undefined;
}
}
}
/**
* Import a user-authored module. `.ts` is loaded via jiti; `.mjs`/`.js` use
* native dynamic import for ordinary cached reads. A fresh `.ts` read uses a
* no-cache jiti instance. Any other fresh read drops the module from the
* require cache and imports a cache-busted file URL. Node then chooses its
* format as for the first read, so a fresh read gives what a first read gives.
* Normal loads retain module caching. `fresh` rereads a file that changed
* during this process: one a codemod rewrote, or an edited doc file (the doc
* importers in ../doc-compiler/import.mjs read each change once).
* Anything the module writes to stdout while it loads goes to stderr.
*
* @param {string} file absolute path
* @param {{fresh?: boolean}} [options]
* @returns {Promise<Record<string, unknown>>}
*/
export async function importUserModule(file, {fresh = false} = {}) {
return await withStdoutOnStderr(() => importModule(file, fresh));
}
const THEME_ARTIFACT_EXTENSIONS = [
'.js',
'.jsx',
'.ts',
'.tsx',
'.mjs',
'.cjs',
'.mts',
'.cts',
];
/**
* @param {string | symbol} specifier
* @returns {specifier is string}
*/
function isStylesheetSpecifier(specifier) {
return typeof specifier === 'string' && specifier.endsWith('.css');
}
/**
* Whether `specifier`, resolved from the module at `from`, names an existing
* `.css` file.
* @param {string} specifier
* @param {string} from
*/
function resolvesToStylesheet(specifier, from) {
try {
return createRequire(from).resolve(specifier).endsWith('.css');
} catch {
return false;
}
}
/**
* A built theme module may import a stylesheet so that the app's bundler emits
* it. Node cannot load a stylesheet, so an import that ends in `.css` and
* resolves from the theme module to an existing `.css` file loads as an empty
* module. Any other import loads as before: a missing stylesheet fails like
* any missing import, and `./tokens.css` loads `tokens.css.js` when that is
* the file it names. jiti shows only the import text, so the check resolves it
* from the theme module's folder, not from the importing module's. A module in
* another folder fails on a stylesheet it reaches by a different relative
* path, and passes on a missing stylesheet whose path exists from the theme
* module's folder.
* @param {() => string} themeModule returns the theme module's path
* @returns {Record<string, unknown>}
*/
function themeArtifactStylesheets(themeModule) {
return new Proxy(
{},
{
has: (_target, specifier) =>
specifier !== themeModule() &&
isStylesheetSpecifier(specifier) &&
resolvesToStylesheet(specifier, themeModule()),
get: (_target, specifier) =>
isStylesheetSpecifier(specifier) ? {} : undefined,
},
);
}
class ThemeArtifactNotFoundError extends Error {
code = 'ERR_THEME_ARTIFACT_NOT_FOUND';
/** @param {string} specifier @param {unknown} [cause] */
constructor(specifier, cause) {
super(`Theme artifact "${specifier}" does not resolve.`, {cause});
this.name = 'ThemeArtifactNotFoundError';
}
}
/** @param {unknown} error */
function isMissingPackageExport(error) {
if (error == null || typeof error !== 'object' || !('code' in error)) {
return false;
}
return (
typeof error.code === 'string' &&
[
'ERR_MODULE_NOT_FOUND',
'ERR_PACKAGE_PATH_NOT_EXPORTED',
'MODULE_NOT_FOUND',
].includes(error.code)
);
}
/**
* Load a generated theme artifact and its extensionless JS/JSX/TS/TSX graph.
* Package specifiers resolve from the consumer project, while relative paths
* resolve from that same project root. An import of an existing `.css` file
* loads as an empty module.
* @param {string} specifier
* @param {string} cwd
* @returns {Promise<Record<string, unknown>>}
*/
export async function importThemeArtifact(specifier, cwd) {
let themeModule = path.join(cwd, 'package.json');
const loader = createJiti(path.join(cwd, 'package.json'), {
moduleCache: false,
jsx: true,
interopDefault: true,
extensions: THEME_ARTIFACT_EXTENSIONS,
virtualModules: themeArtifactStylesheets(() => themeModule),
});
let target;
if (specifier.startsWith('.') || path.isAbsolute(specifier)) {
target = path.resolve(cwd, specifier);
} else {
try {
target = loader.resolve(specifier);
} catch (error) {
if (!isMissingPackageExport(error)) throw error;
throw new ThemeArtifactNotFoundError(specifier, error);
}
}
if (!fs.existsSync(target)) {
throw new ThemeArtifactNotFoundError(specifier);
}
themeModule = target;
return await withStdoutOnStderr(() => loader.import(target));
}
/**
* @param {string} file absolute path
* @param {boolean} fresh
* @returns {Promise<Record<string, unknown>>}
*/
async function importModule(file, fresh) {
if (fresh && file.endsWith('.ts')) {
return await createJiti(import.meta.url, {moduleCache: false}).import(file);
}
if (file.endsWith('.ts')) {
return await getJiti().import(file);
}
const url = pathToFileURL(file);
if (!fresh) return await readInTurn(file, () => import(url.href));
// Node chooses the format again, as for the first import: a package's
// "type", the extension, or the source's syntax. The query names a new ES
// module. A CommonJS module also needs its cache entry gone.
url.searchParams.set('astryx-fresh', String(++freshImportNonce));
return await readFreshInTurn(file, () => import(url.href));
}
/**
* The name Node's CommonJS cache gives `file`: its real path, so a link and
* its target name one entry. A file that does not resolve keeps its path.
* @param {string} file absolute path
* @returns {string}
*/
function cacheKey(file) {
try {
return requireFromHere.resolve(file);
} catch {
return file;
}
}
/**
* Each file's latest read, by its cache name, settled once that read ends.
* @type {Map<string, Promise<void>>}
*/
const readsInProgress = new Map();
/**
* Run `read`, an import of `file`, once the imports of `file` started before
* it have ended. Imports of other files do not wait. A fresh read removes the
* file from Node's CommonJS cache. A CommonJS import still in progress needs
* that entry until it ends.
* @template T
* @param {string} file absolute path
* @param {() => Promise<T>} read
* @returns {Promise<T>}
*/
export function readInTurn(file, read) {
const key = cacheKey(file);
const before = readsInProgress.get(key) ?? Promise.resolve();
const result = before.then(read);
const ended = result.then(
() => {},
() => {},
);
readsInProgress.set(key, ended);
void ended.then(() => {
if (readsInProgress.get(key) === ended) readsInProgress.delete(key);
});
return result;
}
/**
* Run `read`, a fresh import of `file`, in the file's turn (`readInTurn`),
* once the file is gone from Node's CommonJS cache. A new URL names a new ES
* module only, so a CommonJS module also needs its cache entry gone.
* @template T
* @param {string} file absolute path
* @param {() => Promise<T>} read
* @returns {Promise<T>}
*/
export function readFreshInTurn(file, read) {
return readInTurn(file, () => {
delete requireFromHere.cache[cacheKey(file)];
return read();
});
}
/**
* Import a user-authored module, take its default export, and validate it
* through an authoring parser. This is the single load/validation boundary for
* all user-authored modules (config, integration, codemod, template): execute
* the module, take the default export, and hand it to the parser, which returns
* the typed value or throws a clear, readable error. Zod stays sealed inside
* the parser — this boundary never touches it.
*
* @template T
* @param {string} file absolute path
* @param {(input: unknown, label?: string) => T} parse an authoring parser
* (parseConfig, parseIntegration, parseCodemod, parseTemplate)
* @param {{label?: string, fresh?: boolean}} [opts] label used in error messages;
* `fresh` bypasses the module cache after an in-process codemod write
* @returns {Promise<T>} parsed + typed value
*/
export async function loadModuleWithParser(
file,
parse,
{label, fresh = false} = {},
) {
const mod = await importUserModule(file, {fresh});
return parse(mod?.default, label ?? file);
}