An open source design system that's fully customizable and agent ready
TypeScript
// Copyright (c) Meta Platforms, Inc. and affiliates.
/**
* @file Search's adapter: the only place search reads the environment. It
* gathers every candidate from the domains a query asks for (one file per
* domain, _gather-*.mjs) and loads the tree's static data before it runs.
*/
import {readFileSync} from 'node:fs';
import * as path from 'node:path';
import {requireCoreDir} from '../../foundation/fs/paths.mjs';
import {withListingCache} from '../../foundation/fs/listing-cache.mjs';
import {
reusedWhileUnchanged,
unchangedSince,
} from '../../foundation/fs/read-record.mjs';
import {isOutsideProject} from '../../foundation/env/project-scope.mjs';
import {coreDirOrThrow} from '../error.mjs';
import {loadBlockPicker} from '../build/_adapter.mjs';
import {CORELESS_DOMAINS} from './_query.mjs';
import {gatherComponents} from './_gather-components.mjs';
import {gatherHooks} from './_gather-hooks.mjs';
import {gatherDocs} from './_gather-docs.mjs';
import {gatherTemplates, gatherThemes} from './_gather-templates.mjs';
export {componentKeywords} from './_gather-components.mjs';
/** @typedef {import('./_lexical.mjs').Candidate} Candidate */
/**
* The Core a typed search reads: the project's, else the release's own,
* installed into the per-user cache first when needed (a network install and
* an npm subprocess; spec AST-081 FR3). Throws as requireCoreDir does.
* @param {string} cwd
* @returns {string}
*/
export function requireSearchCoreDir(cwd) {
return requireCoreDir(cwd);
}
/**
* Gathers every candidate the query's domains hold. The gather runs in one
* listing-cache operation, so its discovery helpers list each folder once, as
* in the CLI's searches. A caller that runs its own operation shares it.
*
* @param {{cwd?: string, type?: string}} options
* @returns {Promise<{all: Candidate[], components: Candidate[], searchedComponents: boolean, outside: boolean, coreSkipped: string | null, coreSkippedCode: string | null}>}
*/
export function gatherCandidates(options) {
return withListingCache(() => gatherDomains(options));
}
/**
* The Core a search of `type` reads, and the domains it gathers. `astryx docs`
* reads docs without @astryxdesign/core, and `astryx theme list` reads themes
* without it, so a docs or themes search never looks for Core. Every other
* domain reads Core: the project's, else the answering release's own,
* installed into the per-user cache on first need (spec AST-081 FR3). A Core
* domain asked for by name throws the lookup's coded error. An open search
* without Core gathers the docs and themes alone and records why in
* `coreSkipped`; it never fails silently.
* @param {string | undefined} type
* @param {(cwd: string) => string} lookup finds the Core folder, or throws
* @param {string} cwd
* @returns {{coreDir: string | null, coreSkipped: string | null, coreSkippedCode: string | null, wants: (domain: string) => boolean}}
*/
export function resolveSearchCore(type, lookup, cwd) {
const needsCore = !type || !CORELESS_DOMAINS.includes(type);
/** @type {string | null} */
let coreDir = null;
/** @type {string | null} */
let coreSkipped = null;
/** @type {string | null} */
let coreSkippedCode = null;
if (needsCore && type) {
coreDir = coreDirOrThrow(lookup, cwd);
} else if (needsCore) {
try {
coreDir = lookup(cwd);
} catch (error) {
coreSkipped = /** @type {Error} */ (error).message;
const code = /** @type {any} */ (error)?.code;
coreSkippedCode = typeof code === 'string' ? code : null;
}
}
/** @param {string} domain */
const wants = domain =>
(!type && (coreDir != null || CORELESS_DOMAINS.includes(domain))) ||
type === domain;
return {coreDir, coreSkipped, coreSkippedCode, wants};
}
/**
* @param {{cwd?: string, type?: string}} options
*/
async function gatherDomains(options) {
const {cwd = process.cwd(), type} = options;
const {coreDir, coreSkipped, coreSkippedCode, wants} = resolveSearchCore(
type,
requireSearchCoreDir,
cwd,
);
const [components, hooks, docTopics, templates, themes] = await Promise.all([
wants('component')
? gatherComponents(/** @type {string} */ (coreDir), cwd)
: [],
wants('hook') ? gatherHooks(/** @type {string} */ (coreDir)) : [],
wants('doc') ? gatherDocs(cwd) : [],
wants('template') ? gatherTemplates(cwd) : [],
wants('theme') ? gatherThemes(cwd) : [],
]);
const all = [...components, ...hooks, ...docTopics, ...templates, ...themes];
// Outside a project a theme cannot be added to an app, so its command forks
// the source instead (spec AST-081 FR3).
const outside = themes.length > 0 && isOutsideProject(cwd);
return {
all,
components,
searchedComponents: wants('component'),
outside,
coreSkipped,
coreSkippedCode,
};
}
/**
* @typedef {Awaited<ReturnType<typeof gatherCandidates>>} Gathered
* @type {Map<string, (options?: {fresh?: boolean}) => Promise<Gathered>>}
*/
const gathered = new Map();
/**
* gatherCandidates, reused within one process: a later search in the same
* folder, for the same `type`, ranks the candidates an earlier search
* gathered when none of the files that gather read, and none of the folders
* it listed or probed, changed since (each is checked by its change time and
* size, so an edited doc in a linked package is seen on the next call). That
* holds for a gather that is still running too, so searches that start
* together (a docs site's search right after it starts) share one gather. A
* long-running caller (a docs site's search, an agent harness) then pays the
* gather once. A one-shot `astryx search` gathers once, as before.
* @param {{cwd?: string, type?: string}} options
* @returns {Promise<Gathered>}
*/
export function gatherCandidatesReused(options) {
const cwd = path.resolve(options.cwd ?? process.cwd());
const type = options.type;
const key = `${cwd}\0${type ?? ''}`;
let gather = gathered.get(key);
if (!gather) {
gather = reusedWhileUnchanged(
() => gatherCandidates({cwd, type}),
unchangedSince,
);
gathered.set(key, gather);
}
return gather();
}
/**
* @typedef {{w: number[], mu: number[], sd: number[]}} SearcherWeights
* @typedef {object} SearchData
* @property {Record<string, {what?: string, synonyms?: string[], props?: string[]}>} cards
* Each Core component's and hook's source-built card: what it is, the words
* people type for it, its main props.
* @property {import('../../foundation/route/route.mjs').ClassifierWeights} router The root classifier's weights.
* @property {SearcherWeights} main The main searcher's weights.
* @property {SearcherWeights} doc The doc searcher's weights.
* @property {SearcherWeights} template The template searcher's weights.
* @property {import('../build/blocks/blocks.mjs').BlockPickerWeights | null} picker
* Build's block-picker weights, which the fit pass (_fit-order.mjs) reads;
* null when build's loader finds the file absent, unreadable, or the wrong
* shape.
* @typedef {Awaited<ReturnType<typeof gatherCandidates>> & {data: SearchData}} SearchCatalog
*/
/** @type {SearchData | null} */
let searchData = null;
/**
* The search tree's static data, read once: the entry cards, each node's
* weights file, and build's block-picker weights for the fit pass. Build's
* loader (loadBlockPicker) reads and checks the picker weights, only when the
* pass first needs them.
*
* These files are static, reviewed data that only order matches inside a score
* band; ORDERING.md beside them says what each holds and how
* they are refreshed.
* @returns {SearchData}
*/
export function loadSearchData() {
if (!searchData) {
/** @param {string} file */
const read = file =>
JSON.parse(readFileSync(new URL(file, import.meta.url), 'utf8'));
searchData = {
cards: read('./_cards.json'),
router: read('./tree.weights.json'),
main: read('./_main-searcher.weights.json'),
doc: read('./_doc-searcher.weights.json'),
template: read('./_template-searcher.weights.json'),
// Read on first use: most searches never reach the fit pass.
get picker() {
return loadBlockPicker();
},
};
}
return searchData;
}