An open source design system that's fully customizable and agent ready
TypeScript
// Copyright (c) Meta Platforms, Inc. and affiliates.
/** @file Environment adapter for app-theme doctor evidence. */
import {isOutsideProject} from '../../foundation/env/project-scope.mjs';
import {answeredBy} from '../../foundation/release/run-context.mjs';
import {
knownLatestRelease,
lastCheckFailure,
stateLockHolder,
} from '../../foundation/release/global-state.mjs';
import {
alignCliAndCore,
cliInstallAdvice,
installFolder,
projectAddCommand,
globalBehind,
globalUpgradeCommand,
lastNoticeSkip,
projectLag,
} from '../../foundation/release/notices.mjs';
import {
coreVersionOf,
installPlaceOf,
isGlobalCopy,
} from '../../foundation/release/choose.mjs';
import {readReleaseFacts} from '../../foundation/release/project.mjs';
import {astryxCommandsOnSearchPath} from '../../foundation/env/search-path.mjs';
import {
readDeclaredDependencies,
scanAutolinkCandidates,
} from '../../foundation/integrations/autolink.mjs';
import {
computerSkillFile,
displayHomePath,
inspectComputerAgentText,
skillCommandOf,
skillInstallStepOf,
} from '../../foundation/agent-docs/computer-agent-text.mjs';
import {computerAgentTextSettings} from '../../foundation/env/user-settings.mjs';
import * as fs from 'node:fs';
import {elementPropOrigins} from '../../foundation/discovery/module-exports.mjs';
import {cssImports} from '../../foundation/render/embedded-imports.mjs';
import * as path from 'node:path';
import {
Project,
availableComputerIntegrations,
computerIntegrationCandidates,
} from '../../foundation/config/project.mjs';
import {
discoverUnmigratedThemeCopies,
themeImportPackage,
} from '../../foundation/discovery/theme-discovery.mjs';
import {resolveThemeImports} from '../../foundation/discovery/theme-imports.mjs';
import {
CLI_ROOT,
findProjectCoreDir,
findInstalledPackage,
} from '../../foundation/fs/paths.mjs';
export {
isLocalThemeOwner,
planThemeAppWrite,
readThemeState,
resolveThemeModule,
} from '../../foundation/config/theme-state.mjs';
export {themeBuild, validateThemePrivateInputs} from '../theme/build/build.mjs';
export {resolveRecordedTheme} from '../theme/theme.mjs';
export {collectUnloadedFonts} from '../theme/build/font-warning.mjs';
/**
* Package written to the generated app record for one discovered theme.
* @param {import('../../foundation/discovery/theme-discovery.mjs').DiscoveredTheme} theme
*/
export function themeRecordOwner(theme) {
return themeImportPackage(theme);
}
export const SOURCE_EXTENSIONS = new Set([
'.js',
'.jsx',
'.mjs',
'.cjs',
'.ts',
'.tsx',
'.mts',
'.cts',
]);
const SKIP_DIRS = new Set([
'.git',
'.next',
'build',
'coverage',
'dist',
'node_modules',
]);
/** @param {string} file */
export function readTextFile(file) {
return fs.readFileSync(file, 'utf-8');
}
/** @param {string} file */
export function readTextFileIfExists(file) {
if (!fs.existsSync(file)) return null;
try {
return readTextFile(file);
} catch {
return null;
}
}
/**
* A bounded app-source walk that excludes dependencies, generated output, and
* links. The doctor parses the returned bytes without executing app code.
* @param {string} root
* @param {string} generatedModule
* @param {{stylesheets?: boolean}} [options] - also list `.css` files
*/
export function listProjectSourceFiles(root, generatedModule, options = {}) {
/** @type {string[]} */
const files = [];
/** @type {string[]} */
const queue = [root];
while (queue.length > 0 && files.length < 5000) {
const dir = /** @type {string} */ (queue.shift());
let entries;
try {
entries = fs.readdirSync(dir, {withFileTypes: true});
} catch {
continue;
}
for (const entry of entries) {
if (entry.isSymbolicLink()) continue;
const file = path.join(dir, entry.name);
if (entry.isDirectory()) {
if (!SKIP_DIRS.has(entry.name) && !entry.name.startsWith('.astryx-')) {
queue.push(file);
}
} else if (
entry.isFile() &&
file !== generatedModule &&
(SOURCE_EXTENSIONS.has(path.extname(entry.name)) ||
(options.stylesheets === true && path.extname(entry.name) === '.css'))
) {
files.push(file);
}
}
}
return files;
}
/** @param {string} projectDir */
export async function discoverDoctorThemes(projectDir) {
const project = await Project.load(projectDir, {core: 'project'});
return project.themes();
}
/**
* Resolve one discovered theme's built module and stylesheets.
* @param {import('../../foundation/discovery/theme-discovery.mjs').DiscoveredTheme} theme
* @param {{cwd: string, ownerThemeCount: number}} options
*/
export function resolveDoctorThemeImports(theme, options) {
return resolveThemeImports(theme, options);
}
/** @param {string} projectDir */
export function discoverDoctorUnmigratedCopies(projectDir) {
return discoverUnmigratedThemeCopies(projectDir);
}
/**
* The real path of a file, links resolved; null when it does not exist.
* @param {string} file
* @returns {string | null}
*/
export function realDoctorFile(file) {
try {
return fs.realpathSync(file);
} catch {
return null;
}
}
/**
* Where each `<Name prop={value}>` value of a module is declared (see
* `elementPropOrigins`).
* @param {string} file
* @param {Parameters<typeof elementPropOrigins>[1]} element
*/
export function doctorElementPropOrigins(file, element) {
return elementPropOrigins(file, element);
}
/**
* The `@import` specifiers of a stylesheet, quoted or in `url()`, in any case
* (see `cssImports`); empty for CSS that does not parse.
* @param {string} css
* @returns {Set<string>}
*/
export function doctorStylesheetImports(css) {
return new Set(cssImports(css));
}
/** @param {string} projectDir */
export function findDoctorCoreDir(projectDir) {
return findProjectCoreDir(projectDir);
}
/** @param {string} projectDir @param {string} packageName */
export function findDoctorInstalledPackage(projectDir, packageName) {
return findInstalledPackage(projectDir, packageName);
}
/**
* Names of the `@astryxdesign/theme-*` packages installed in the nearest
* `node_modules` at or above `cwd`, looking up to six levels.
* @param {string} cwd
* @returns {string[]}
*/
export function listDoctorThemePackages(cwd) {
let dir = path.resolve(cwd);
let nodeModules = null;
for (let level = 0; level < 6; level++) {
const candidate = path.join(dir, 'node_modules');
if (fs.existsSync(candidate)) {
nodeModules = candidate;
break;
}
const parent = path.dirname(dir);
if (parent === dir) break;
dir = parent;
}
if (!nodeModules) return [];
const scopeDir = path.join(nodeModules, '@astryxdesign');
let entries;
try {
entries = fs.readdirSync(scopeDir, {withFileTypes: true});
} catch {
return [];
}
/** @type {string[]} */
const names = [];
for (const entry of entries) {
if (!entry.name.startsWith('theme-')) continue;
// pnpm links packages into node_modules/.pnpm, and a symlink entry does
// not report itself as a directory, so check what it points to.
let isDirectory = entry.isDirectory();
if (!isDirectory && entry.isSymbolicLink()) {
try {
isDirectory = fs
.statSync(path.join(scopeDir, entry.name))
.isDirectory();
} catch {
isDirectory = false;
}
}
if (isDirectory) names.push(`@astryxdesign/${entry.name}`);
}
return names;
}
/** @param {string} file */
export function readPackageJson(file) {
try {
return JSON.parse(readTextFile(file));
} catch {
return null;
}
}
/**
* The integrations installed for the computer, and, outside a project, which
* of them the folder loads (spec AST-081 FR12): those it uses, and the names
* of the integrations the folder loads itself, whose copies win.
* @param {string} cwd
* @returns {Promise<{computerIntegrations: import('../../foundation/integrations/computer-integrations.mjs').ComputerIntegrationCandidate[], loadedComputerIntegrations: string[], folderIntegrations: string[]}>}
*/
export async function computerIntegrationsOutside(cwd) {
const computerIntegrations = computerIntegrationCandidates(cwd);
if (computerIntegrations.length === 0) {
return {
computerIntegrations,
loadedComputerIntegrations: [],
folderIntegrations: [],
};
}
try {
const project = await Project.load(cwd, {core: 'project'});
/** @type {Array<{name: string, __computer?: boolean, __loadError?: string}>} */
const loaded = project.loadedIntegrations;
return {
computerIntegrations,
loadedComputerIntegrations: loaded
.filter(i => i.__computer && !i.__loadError)
.map(i => i.name),
folderIntegrations: loaded.filter(i => !i.__computer).map(i => i.name),
};
} catch {
return {
computerIntegrations,
loadedComputerIntegrations: [],
folderIntegrations: [],
};
}
}
/**
* Inside a project: the integrations installed for the computer it could add
* (spec AST-081 FR12), leaving out every package it loads or declares.
* @param {string} cwd
* @param {string[]} loadedNames the integrations the project loads
* @returns {Promise<import('../../foundation/integrations/computer-integrations.mjs').ComputerIntegrationCandidate[]>}
*/
export async function computerIntegrationsToAdd(cwd, loadedNames) {
const installed = new Set([...loadedNames, ...declaredPackageNames(cwd)]);
return availableComputerIntegrations(cwd, installed);
}
/**
* The package names the folder's package.json declares, nearest first.
* @param {string} cwd
* @returns {string[]}
*/
function declaredPackageNames(cwd) {
for (let dir = path.resolve(cwd); ;) {
if (fs.existsSync(path.join(dir, 'package.json'))) {
return readDeclaredDependencies(dir).map(d => d.name);
}
const parent = path.dirname(dir);
if (parent === dir) return [];
dir = parent;
}
}
/**
* The computer-level agent text's setting, its state on disk, and the command
* the skill file tells agents to run and the install step it records for when
* that command is not found (each null when there is no file, or it names
* none).
* @returns {{settings: import('../../foundation/env/user-settings.mjs').ComputerAgentTextSettings, entries: Array<{path: string, state: import('../../foundation/agent-docs/computer-agent-text.mjs').ComputerAgentTextState, link?: true}>, command: string | null, install: string | null}}
*/
export function computerAgentTextState() {
const settings = computerAgentTextSettings();
let command = null;
let install = null;
try {
const text = fs.readFileSync(computerSkillFile(), 'utf8');
command = skillCommandOf(text);
install = skillInstallStepOf(text);
} catch {
// No skill file, or one that cannot be read: no command to check.
}
return {
settings,
entries: inspectComputerAgentText({links: settings.links}),
command,
install,
};
}
export {displayHomePath};
/**
* The release facts doctor reports, read here so the checks stay pure
* (spec AST-081 FR5, FR6, FR10; architecture:cli-surface INV21): who
* answered, the newest release the computer knows of, how far the global copy
* or the project is behind, and every `astryx` on the search path with the
* command that upgrades it.
* @param {string} cwd
* @param {{project: boolean}} options
* @returns {{answeredBy: {cli: string, core: string | null, copy: string}, latest: string | null, globalBehind: ReturnType<typeof globalBehind> | null, projectLag: ReturnType<typeof projectLag> | null, lastNoticeSkip: ReturnType<typeof lastNoticeSkip>, lastCheckFailure: ReturnType<typeof lastCheckFailure>, stateLock: ReturnType<typeof stateLockHolder>, searchPathCommands: Array<import('../../foundation/env/search-path.mjs').SearchPathCommand & {upgrade: string | null, runner: boolean}>}}
*/
export function releaseFacts(cwd, {project}) {
const answered = answeredBy(cwd);
return {
answeredBy: answered,
latest: knownLatestRelease(),
lastNoticeSkip: lastNoticeSkip(),
lastCheckFailure: lastCheckFailure(),
stateLock: stateLockHolder(),
globalBehind:
!project && isGlobalCopy(CLI_ROOT)
? globalBehind({self: {version: answered.cli, root: CLI_ROOT}})
: null,
// The project's version is its own CLI's, or, with none, its Core's:
// installed, else locked, else declared, as the daily notice reads it.
projectLag: project
? projectLag({
cwd,
current:
(answered.copy === 'starting' && projectCoreVersion(cwd)) ||
answered.cli,
})
: null,
searchPathCommands: astryxCommandsOnSearchPath().map(row => ({
...row,
upgrade: row.cliRoot ? globalUpgradeCommand(row.cliRoot) : null,
// A package runner's temporary install, which it puts first on the
// search path only for the run it starts.
runner: row.cliRoot ? installPlaceOf(row.cliRoot).runner : false,
})),
};
}
/** Whether `cwd` is outside every project. */
export function outsideProject(/** @type {string} */ cwd) {
return isOutsideProject(cwd);
}
/**
* The commands that bring a project's own CLI and Core to one release, with
* the project's package manager: Core up to the CLI, then its codemods, when
* the CLI is newer; else the CLI to the Core's release. Null when no
* command fits (see `alignCliAndCore`).
* @param {string} cwd
* @param {string} cli
* @param {string} core
* @returns {string | null}
*/
export function alignCommand(cwd, cli, core) {
return alignCliAndCore({cwd, cli, core});
}
/**
* The Core release the project at `cwd` names: installed, else locked, else
* declared; the version the daily hint and notice compare against (spec
* AST-081 FR2). Null outside a project or when it names none.
* @param {string} cwd
* @returns {string | null}
*/
export function projectCoreVersion(cwd) {
return coreVersionOf(readReleaseFacts(cwd));
}
/**
* Whether the project at `cwd` installs its own CLI (spec AST-081 FR2).
* @param {string} cwd
* @returns {boolean}
*/
export function projectHasOwnCli(cwd) {
return Boolean(readReleaseFacts(cwd).cli);
}
/**
* The command that adds the CLI at `version` with the project's package
* manager, and the Core it matches: from a folder whose package.json declares
* no Astryx package, in the Astryx project above at that project's Core; null
* when there is none (see `cliInstallAdvice`).
* @param {string} cwd
* @param {string} version
* @returns {{command: string, core: string} | null}
*/
export function addCliCommandFor(cwd, version) {
const advice = cliInstallAdvice({cwd, core: version});
return advice?.command ? {command: advice.command, core: advice.core} : null;
}
/**
* The command that adds a package to the project of `cwd`; null in a folder
* that belongs to no project or whose package.json is not the project's (see
* `projectAddCommand`).
* @param {string} cwd
* @returns {((name: string) => string) | null}
*/
export function installCommandFor(cwd) {
return projectAddCommand(cwd);
}
/**
* Whether `cwd` is inside a project whose package.json is not the project's,
* so advice points at the project's folder (see `installFolder`).
* @param {string} cwd
* @returns {boolean}
*/
export function insideProjectElsewhere(cwd) {
return installFolder(cwd)?.moved === true;
}
/** Folders `doctor --built` never reads: installs and version control. */
const BUILT_SKIPPED_DIRS = new Set(['node_modules', '.git', '.hg', '.sl']);
/** Folders that hold build output: read for stylesheets, never as source. */
const BUILD_OUTPUT_DIRS = new Set(['.next', 'dist', 'build', 'out', '.output']);
/** `doctor --built` reads at most this many files, of at most this size. */
export const BUILT_FILE_LIMIT = 20000;
export const BUILT_FILE_MAX_MB = 5;
const BUILT_FILE_MAX_BYTES = BUILT_FILE_MAX_MB * 1024 * 1024;
/**
* The absolute path `doctor --built` checks, or null when it does not exist.
* @param {string} cwd
* @param {string} target
* @returns {string | null}
*/
export function resolveBuiltPath(cwd, target) {
const resolved = path.resolve(cwd, target);
return fs.existsSync(resolved) ? resolved : null;
}
/**
* The files under a `doctor --built` path, in a stable order: each with its
* path relative to the folder (a file's own name when the path is one file),
* whether it sits in build output, and a reader that returns its text, or
* null when it cannot be read or is over 5 MB. Installs and version control
* are skipped; at most `fileLimit` files are listed.
* @param {string} target an existing absolute path
* @param {{fileLimit?: number}} [options] `fileLimit`: BUILT_FILE_LIMIT
* unless the caller reads fewer
* @returns {{files: {rel: string, built: boolean, read: () => string | null}[], truncated: boolean, missing?: number}}
*/
export function readBuiltPath(target, {fileLimit = BUILT_FILE_LIMIT} = {}) {
/** @param {string} file */
const reader = file => () => {
try {
if (fs.statSync(file).size > BUILT_FILE_MAX_BYTES) return null;
return fs.readFileSync(file, 'utf8');
} catch {
return null;
}
};
if (!fs.statSync(target).isDirectory()) {
const inBuild = path
.dirname(target)
.split(path.sep)
.some(part => BUILD_OUTPUT_DIRS.has(part));
/** @type {{rel: string, built: boolean, read: () => string | null}[]} */
const files = [
{rel: path.basename(target), built: inBuild, read: reader(target)},
];
let missing = 0;
// A built page carries its styles and scripts in files it links: read
// the local ones beside it, as built output.
if (/\.html?$/iu.test(target)) {
// A link inside an HTML comment is not one the page loads.
const page = (reader(target)() ?? '').replace(/<!--[\s\S]*?-->/g, ' ');
const seen = new Set([path.resolve(target)]);
for (const match of page.matchAll(
/<(?:link|script)\b[^>]*?\b(?:href|src)\s*=\s*(?:"([^"#?]+)|'([^'#?]+)|([^\s"'#?>]+))/giu,
)) {
const href = match[1] ?? match[2] ?? match[3];
if (/^(?:[a-z][\w+.-]*:|\/\/)/iu.test(href)) continue;
// A root-relative link names a file from the build root: the page's
// folder or the nearest folder above it that holds the file.
let file = path.resolve(path.dirname(target), href.replace(/^\//u, ''));
if (href.startsWith('/')) {
for (let dir = path.dirname(target); ; dir = path.dirname(dir)) {
const candidate = path.join(dir, href);
if (fs.existsSync(candidate)) {
file = candidate;
break;
}
if (path.dirname(dir) === dir) break;
}
}
if (seen.has(file)) continue;
if (!fs.existsSync(file)) {
// Only a missing stylesheet could have held Astryx styles; a
// missing favicon or manifest changes nothing.
if (
/\.css$/iu.test(href) ||
/\brel\s*=\s*["']?stylesheet/iu.test(match[0])
) {
missing++;
}
continue;
}
seen.add(file);
files.push({
rel: path
.relative(path.dirname(target), file)
.split(path.sep)
.join('/'),
built: true,
read: reader(file),
});
}
}
return {files, truncated: false, missing};
}
/** @type {{rel: string, built: boolean, read: () => string | null}[]} */
const files = [];
// A path that is itself build output (`--built dist`) is read as built.
/** @type {{dir: string, built: boolean}[]} */
const stack = [
{dir: target, built: BUILD_OUTPUT_DIRS.has(path.basename(target))},
];
while (stack.length > 0) {
const {dir, built} = /** @type {{dir: string, built: boolean}} */ (
stack.pop()
);
let entries;
try {
entries = fs.readdirSync(dir, {withFileTypes: true});
} catch {
continue;
}
entries.sort((a, b) => a.name.localeCompare(b.name));
for (const entry of entries) {
const full = path.join(dir, entry.name);
if (entry.isDirectory()) {
if (BUILT_SKIPPED_DIRS.has(entry.name)) continue;
stack.push({
dir: full,
built: built || BUILD_OUTPUT_DIRS.has(entry.name),
});
} else if (entry.isFile()) {
if (files.length >= fileLimit) return {files, truncated: true};
files.push({
rel: path.relative(target, full).split(path.sep).join('/'),
built,
read: reader(full),
});
}
}
}
return {files, truncated: false};
}
/**
* The integration packages whose components count as Astryx for a `--built`
* path, read without running anything: each dependency the nearest
* package.json above the path declares whose installed copy, resolved the way
* the CLI autolinks integrations (a workspace root's hoisted copy included),
* holds an integration manifest. Every `@astryxdesign/*` package counts
* beside them.
* @param {string} target the path as given
* @param {string} cwd
* @returns {string[]}
*/
export function builtIntegrationPackages(target, cwd) {
let dir = path.resolve(cwd, target);
try {
if (!fs.statSync(dir).isDirectory()) dir = path.dirname(dir);
} catch {
dir = path.resolve(cwd);
}
for (let at = dir; ; at = path.dirname(at)) {
if (fs.existsSync(path.join(at, 'package.json'))) {
return [
...new Set(scanAutolinkCandidates(at).map(candidate => candidate.spec)),
];
}
if (path.dirname(at) === at) return [];
}
}