An open source design system that's fully customizable and agent ready
TypeScript
feat(cli): experimental exportSearchIndex() and rankSearchIndex() (#10375)
Joey3b90d333f9be
diff --git a/.changeset/search-index-api.md b/.changeset/search-index-api.mdnew file mode 100644index 0000000000..d6f6f39247--- /dev/null+++ b/.changeset/search-index-api.md@@ -0,0 +1,7 @@+---+'@astryxdesign/cli': patch+---++[experimental] `exportSearchIndex()` and `rankSearchIndex()` from `@astryxdesign/cli/api` store and rank search's candidates. `exportSearchIndex({cwd, package})` returns `{version, candidates}`: what `search()` ranks in a folder, as plain JSON (with `package`, only that package's entries). `rankSearchIndex(query, indexes, {type, limit})` ranks stored indexes with search's own tree: an index made in a project answers as `search(query)` does there, with the same response; for an index made outside a project, theme results name `theme add` where `search` there names `theme eject`. A catalog that lists packages it must not load makes the index where loading is safe and ranks it per query. An index is ranked only by the CLI version that made it. Both are experimental (they may change in a patch release), and their docs are not search results, so `search` and `build` answer exactly as before. When they are promoted to stable, their docs join search.++@josephfarinadiff --git a/packages/cli/api/index.mjs b/packages/cli/api/index.mjsindex a91c9a6628..30cb6c8aa6 100644--- a/packages/cli/api/index.mjs+++ b/packages/cli/api/index.mjs@@ -48,6 +48,7 @@ export {} from './theme/theme.mjs';export {hook} from './hook/hook.mjs';export {search} from './search/search.mjs';+export {exportSearchIndex, rankSearchIndex} from './search/search-index.mjs';export {build} from './build/build.mjs';export {swizzle} from './swizzle/swizzle.mjs';export {gapReport} from './gap-report/gap-report.mjs';diff --git a/packages/cli/api/search/_adapter.mjs b/packages/cli/api/search/_adapter.mjsindex f93f11c451..43d2d25f1d 100644--- a/packages/cli/api/search/_adapter.mjs+++ b/packages/cli/api/search/_adapter.mjs@@ -43,46 +43,62 @@ export function requireSearchCoreDir(cwd) {* 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}>}+ * @returns {Promise<{all: Candidate[], components: Candidate[], searchedComponents: boolean, outside: boolean, coreSkipped: string | null, coreSkippedCode: string | null}>}*/export function gatherCandidates(options) {return withListingCache(() => gatherDomains(options));}/**- * @param {{cwd?: string, type?: string}} 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}}*/-async function gatherDomains(options) {- const {cwd = process.cwd(), type} = options;- // `astryx docs` reads docs without @astryxdesign/core, and `astryx theme- // list` reads themes without it (bundled themes need no project), so a- // search of either must too. Every other domain reads core: asked for by- // name, it is an error without core; an open search then covers the docs- // and themes alone.+export function resolveSearchCore(type, lookup, cwd) {const needsCore = !type || !CORELESS_DOMAINS.includes(type);- // A domain that reads Core gets it as `component` does: the project's, else- // the answering release's own, installed into the per-user cache on first- // need (spec AST-081 FR3). Asked for by name, a Core that cannot be had is- // the error; an open search answers from the rest and says what it skipped- // and why, never silently./** @type {string | null} */let coreDir = null;/** @type {string | null} */let coreSkipped = null;+ /** @type {string | null} */+ let coreSkippedCode = null;if (needsCore && type) {- coreDir = coreDirOrThrow(requireSearchCoreDir, cwd);+ coreDir = coreDirOrThrow(lookup, cwd);} else if (needsCore) {try {- coreDir = requireSearchCoreDir(cwd);+ 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};+}- // Gather candidates from each requested domain in parallel.- /** @param {string} d */- const wants = d =>- (!type && (coreDir != null || CORELESS_DOMAINS.includes(d))) || type === d;+/**+ * @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)@@ -103,6 +119,7 @@ async function gatherDomains(options) {searchedComponents: wants('component'),outside,coreSkipped,+ coreSkippedCode,};}diff --git a/packages/cli/api/search/exportSearchIndex.doc.mjs b/packages/cli/api/search/exportSearchIndex.doc.mjsnew file mode 100644index 0000000000..ae7578db57--- /dev/null+++ b/packages/cli/api/search/exportSearchIndex.doc.mjs@@ -0,0 +1,58 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++/**+ * @file FunctionDoc for `exportSearchIndex()`. Colocated with the API function it+ * documents; the shape source of truth stays in `search.type.mjs`.+ * @position packages/cli/api/search — function documentation+ */++/** @type {import('@astryxdesign/cli/authoring').FunctionDoc} */+export const doc = {+ type: 'function',+ kind: 'api',+ name: 'exportSearchIndex',+ namespace: 'cli/api',+ stability: 'experimental',+ displayName: 'exportSearchIndex()',+ summary:+ 'The candidates search ranks in a folder, as plain JSON to store and rank later with rankSearchIndex().',+ description:+ "Gathers what `search()` would rank in `cwd` and returns it as `{version, candidates}`. Gathering reads each installed package's docs and loads its integration manifest, which runs that package's code, so a catalog that lists packages it must not load makes the index where loading is safe (a folder with those packages installed), stores it, and ranks it with {@link function:rankSearchIndex}. With `package`, the index keeps only that package's candidates, for a catalog that stores one index per package. A component description's inline doc tokens are resolved where the index is made, as `search` prints them; when Core could not be had there, the index says why in `coreSkipped`. Fields that point into the folder are left out, so an index reads the same wherever it was made. The candidates are the ranker's input, not a stable shape: an index is ranked only by the CLI version that made it. Experimental: it may change or be removed in a patch release.",+ importPath: '@astryxdesign/cli/api',+ signature: 'exportSearchIndex(options?: {cwd?: string, package?: string}): Promise<SearchIndex>',+ keywords: ['search index', 'stored search index'],+ params: [+ {+ name: 'options.cwd',+ type: 'string',+ description: 'The folder to gather from, read as `search()` reads it.',+ default: 'process.cwd()',+ },+ {+ name: 'options.package',+ type: 'string',+ description:+ "Keep only the candidates this npm package owns: its components, templates, themes, and doc parts. Without it the index holds everything the folder's search ranks, Core's entries and the CLI's docs included.",+ },+ ],+ returns: [+ {+ type: 'SearchIndex',+ description:+ '`version`, the CLI version that made it, and `candidates`, the gathered entries as plain JSON.',+ },+ ],+ throws: [+ {+ code: 'ERR_INVALID_ARGUMENT',+ when: '`package` is given and is not a non-empty string',+ },+ ],+ examples: [+ {+ label: 'Index one installed integration',+ code: "const index = await exportSearchIndex({cwd: '/tmp/harness', package: '@acme/ui'});",+ },+ ],+ related: ['search', 'rankSearchIndex'],+};diff --git a/packages/cli/api/search/rankSearchIndex.doc.mjs b/packages/cli/api/search/rankSearchIndex.doc.mjsnew file mode 100644index 0000000000..8f9166ab73--- /dev/null+++ b/packages/cli/api/search/rankSearchIndex.doc.mjs@@ -0,0 +1,79 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++/**+ * @file FunctionDoc for `rankSearchIndex()`. Colocated with the API function it+ * documents; the shape source of truth stays in `search.type.mjs`.+ * @position packages/cli/api/search — function documentation+ */++/** @type {import('@astryxdesign/cli/authoring').FunctionDoc} */+export const doc = {+ type: 'function',+ kind: 'api',+ name: 'rankSearchIndex',+ namespace: 'cli/api',+ stability: 'experimental',+ displayName: 'rankSearchIndex()',+ summary:+ "Ranks stored search indexes with search's own tree: an index made in one folder answers as search() does there.",+ description:+ "Ranks the candidates of every index together, with the same tree, weights, and order as {@link function:search}. An index made with `exportSearchIndex()` in one folder ranks exactly as `search(query)` does in that folder: the same results, order, and scores. Indexes made in separate folders are ranked together as one list; a doc that one package replaces or extends in another is not merged across them, so a project's own `search` can differ where that happens. A theme result's command is the in-project `theme add`. When every index was made where Core could not be had, an open rank (no `type`) carries `meta.partial`, as `search` does; a rank of `type` `component`, `hook`, or `template` throws the error `search` throws there. Every index must come from this CLI's version, because the candidates' shape is the ranker's input. Experimental: it may change or be removed in a patch release.",+ importPath: '@astryxdesign/cli/api',+ signature:+ 'rankSearchIndex(query: string, indexes: SearchIndex | SearchIndex[], options?: {type?: SearchDomain, limit?: number}): Promise<SearchResponse>',+ keywords: ['search index', 'stored search index'],+ params: [+ {+ name: 'query',+ type: 'string',+ description: 'Free-text search term.',+ required: true,+ },+ {+ name: 'indexes',+ type: 'SearchIndex | SearchIndex[]',+ description:+ 'Indexes made by `exportSearchIndex()` with this CLI version.',+ required: true,+ },+ {+ name: 'options.type',+ type: "'component' | 'hook' | 'doc' | 'template' | 'theme'",+ description: 'Restrict results to a single domain.',+ },+ {+ name: 'options.limit',+ type: 'number',+ description: 'Maximum number of results.',+ default: '20',+ },+ ],+ returns: [+ {+ type: 'search',+ description:+ 'The same response as `search()`: the query, `matchCount`, and the ranked results bounded by `limit`.',+ },+ ],+ throws: [+ {+ code: 'ERR_INVALID_ARGUMENT',+ when: 'the query is empty, `type` is unknown, `limit` is not a positive integer, an index is not `{version, candidates}`, or an index was made by another CLI version',+ },+ {+ code: 'ERR_CORE_NOT_FOUND',+ when: 'every index was made where @astryxdesign/core could not be found, and `type` names a domain that reads it: `component`, `hook`, or `template`',+ },+ {+ code: 'ERR_VERSIONS_UNAVAILABLE',+ when: 'every index was made where the Core of the release that answers could not be installed into the per-user cache, and `type` names a domain that reads it: `component`, `hook`, or `template`; a rank with no `type` answers with `meta.partial` instead',+ },+ ],+ examples: [+ {+ label: 'Rank stored indexes',+ code: 'const r = await rankSearchIndex(text, [coreIndex, ...packageIndexes]);',+ },+ ],+ related: ['search', 'exportSearchIndex'],+};diff --git a/packages/cli/api/search/search-index.mjs b/packages/cli/api/search/search-index.mjsnew file mode 100644index 0000000000..91ee6a0c7a--- /dev/null+++ b/packages/cli/api/search/search-index.mjs@@ -0,0 +1,270 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++/**+ * @file A stored search index: the candidates `search` gathers in a folder, as+ * plain JSON, and the ranking of stored candidates with search's own tree.+ *+ * Gathering reads every package's docs and loads its manifest, which runs the+ * package's code. A catalog that lists packages it must not load (a web page+ * that lists every published integration) stores each package's index once,+ * where loading is safe, and ranks the stored indexes per query.+ * @position api/search; search.mjs is the folder-reading search.+ */++import {+ docPackageManager,+ runWithDocPackageManager,+} from '../../foundation/env/package-manager.mjs';+import {withListingCache} from '../../foundation/fs/listing-cache.mjs';+import {cliVersion} from '../../foundation/release/run-context.mjs';+import {runTree} from '../../foundation/route/route.mjs';+import {ERROR_CODES} from '../../foundation/response/error-codes.mjs';+import {linkSearchResponse} from '../component/_adapter.mjs';+import {AstryxError} from '../error.mjs';+import {+ gatherCandidates,+ loadSearchData,+ resolveSearchCore,+} from './_adapter.mjs';+import {checkSearchArgs} from './_result.mjs';+import {SEARCH_TREE} from './tree.mjs';++/**+ * Fields a gathered candidate holds that point into the folder it was read+ * from. They decide ownership while gathering and never rank, so an index+ * leaves them out and reads the same wherever it was made.+ */+const LOCAL_FIELDS = ['_docPath'];++/**+ * A component candidate's description as `search` prints it: its inline+ * `{@link}`, `{@pm}` and `{@command}` tokens resolved in the folder the index+ * is made in. The raw description stays the one that is scored.+ */+const DISPLAY_FIELD = '_displayDescription';++/** Stands for the Core the indexes were made with, which ranking never reads. */+const STORED_CORE = 'stored-index';++/**+ * @param {Record<string, unknown>} candidate+ * @returns {Record<string, unknown>}+ */+function portable(candidate) {+ /** @type {Record<string, unknown>} */+ const out = JSON.parse(JSON.stringify(candidate));+ for (const field of LOCAL_FIELDS) delete out[field];+ return out;+}++/**+ * The candidates `search` ranks in a folder, as plain JSON: store it, and rank+ * it later with {@link rankSearchIndex}.+ *+ * Experimental (spec:AST-017 FR27): may change or be removed in a patch+ * release.+ * @experimental+ * @param {object} [options]+ * @param {string} [options.cwd] - The folder to gather from, as `search` reads it.+ * @param {string} [options.package] - Keep only the candidates this npm package+ * owns (its components, templates, themes, and doc parts).+ * @returns {Promise<import('./search.type.mjs').SearchIndex>}+ */+export async function exportSearchIndex(options = {}) {+ const {cwd = process.cwd(), package: owner} = options;+ if (owner != null && (typeof owner !== 'string' || owner.trim() === '')) {+ throw new AstryxError(+ `Invalid package "${owner}". Pass an npm package name.`,+ undefined,+ ERROR_CODES.ERR_INVALID_ARGUMENT,+ );+ }+ return runWithDocPackageManager(docPackageManager(cwd), () =>+ withListingCache(async () => {+ const gathered = await gatherCandidates({cwd});+ const kept =+ owner == null+ ? gathered.all+ : gathered.all.filter(candidate => candidate._package === owner);+ const candidates = kept.map(candidate =>+ portable(/** @type {Record<string, unknown>} */ (candidate)),+ );+ await addDisplayDescriptions(candidates, cwd);+ return {+ version: cliVersion(),+ candidates,+ ...(gathered.coreSkipped == null+ ? {}+ : {+ coreSkipped: gathered.coreSkipped,+ ...(gathered.coreSkippedCode == null+ ? {}+ : {coreSkippedCode: gathered.coreSkippedCode}),+ }),+ };+ }),+ );+}++/**+ * Resolves each component description's inline tokens as `search` does for+ * the results it prints, and keeps the printed text beside the scored one.+ * @param {Record<string, unknown>[]} candidates+ * @param {string} cwd+ */+async function addDisplayDescriptions(candidates, cwd) {+ const linkable = candidates.filter(+ candidate =>+ candidate.domain === 'component' &&+ typeof candidate.description === 'string' &&+ candidate.description.includes('{@'),+ );+ if (linkable.length === 0) return;+ const response = await linkSearchResponse(+ /** @type {any} */ ({+ type: 'search',+ data: {+ results: linkable.map(candidate => ({+ domain: 'component',+ package: candidate._package,+ description: candidate.description,+ })),+ },+ }),+ cwd,+ );+ response.data.results.forEach(+ (/** @type {any} */ result, /** @type {number} */ i) => {+ if (result.description !== linkable[i].description)+ linkable[i][DISPLAY_FIELD] = result.description;+ },+ );+}++/**+ * Ranks stored indexes with search's tree. An index made in one folder answers+ * as `search(query)` does there (a theme result's command is the in-project+ * `theme add`). Indexes made in separate folders, such as one per package+ * (made with `package`) and one for Core, are ranked together as one list; a+ * doc that one package replaces or extends in another is not merged across+ * them. Every index must come from this CLI's version, since the tree reads+ * the candidates' shape. When every index was made where Core could not be+ * had, the answer carries `meta.partial`, as `search` does.+ *+ * Experimental (spec:AST-017 FR27): may change or be removed in a patch+ * release.+ * @experimental+ * @param {string} query - Free-text search term.+ * @param {import('./search.type.mjs').SearchIndex | import('./search.type.mjs').SearchIndex[]} indexes+ * @param {object} [options]+ * @param {import('./search.type.mjs').SearchDomain} [options.type] - Restrict to one domain.+ * @param {number} [options.limit] - Max results (default 20).+ * @returns {Promise<import('./search.type.mjs').SearchResponse>}+ */+export async function rankSearchIndex(query, indexes, options = {}) {+ checkSearchArgs(query, options);+ const list = Array.isArray(indexes) ? indexes : [indexes];+ const version = cliVersion();+ /** @type {any[]} */+ const all = [];+ for (const index of list) {+ if (index == null || !Array.isArray(index.candidates)) {+ throw new AstryxError(+ 'A search index is {version, candidates}, as exportSearchIndex() returns it.',+ undefined,+ ERROR_CODES.ERR_INVALID_ARGUMENT,+ );+ }+ if (index.version !== version) {+ throw new AstryxError(+ `This search index was made by CLI ${index.version}; this is CLI ${version}. Make it again with this version's exportSearchIndex().`,+ undefined,+ ERROR_CODES.ERR_INVALID_ARGUMENT,+ );+ }+ all.push(...index.candidates);+ }+ const {type} = options;+ const wanted =+ type == null ? all : all.filter(candidate => candidate.domain === type);+ const {searchedComponents, coreSkipped} = coreFlags(list, type);+ const response = /** @type {import('./search.type.mjs').SearchResponse} */ (+ await runTree(+ SEARCH_TREE,+ {query, options: {type, limit: options.limit}},+ {+ all: wanted,+ components: wanted.filter(+ candidate => candidate.domain === 'component',+ ),+ searchedComponents,+ outside: false,+ coreSkipped,+ coreSkippedCode: null,+ data: loadSearchData(),+ },+ )+ );+ return withDisplayDescriptions(response, wanted);+}++/**+ * The catalog flags `search` derives from Core for a request of `type`, by+ * search's own rule (`resolveSearchCore`). Core is missing only when no index+ * had it. An open search then names what it skipped. A docs or themes search+ * never reads Core. A Core domain asked for by name throws the error that+ * `search` throws.+ * @param {import('./search.type.mjs').SearchIndex[]} list+ * @param {import('./search.type.mjs').SearchDomain | undefined} type+ * @returns {{searchedComponents: boolean, coreSkipped: string | null}}+ */+function coreFlags(list, type) {+ const missing =+ list.length > 0 &&+ list.every(index => typeof index.coreSkipped === 'string');+ const lookup = () => {+ if (!missing) return STORED_CORE;+ throw Object.assign(+ new Error(/** @type {string} */ (list[0].coreSkipped)),+ {+ code: list[0].coreSkippedCode ?? ERROR_CODES.ERR_CORE_NOT_FOUND,+ },+ );+ };+ const {coreSkipped, wants} = resolveSearchCore(type, lookup, STORED_CORE);+ return {searchedComponents: wants('component'), coreSkipped};+}++/**+ * The response with each component result's description as `search` prints+ * it, from the text the index stored when it was made.+ * @param {import('./search.type.mjs').SearchResponse} response+ * @param {any[]} candidates+ * @returns {import('./search.type.mjs').SearchResponse}+ */+function withDisplayDescriptions(response, candidates) {+ /** @type {Map<string, string>} */+ const display = new Map();+ for (const candidate of candidates) {+ if (+ candidate.domain === 'component' &&+ typeof candidate[DISPLAY_FIELD] === 'string'+ )+ display.set(+ `${candidate._package}\u0000${candidate._resultName ?? candidate.name}`,+ candidate[DISPLAY_FIELD],+ );+ }+ if (display.size === 0) return response;+ return {+ ...response,+ data: {+ ...response.data,+ results: response.data.results.map(result => {+ if (result.domain !== 'component') return result;+ const text = display.get(`${result.package}\u0000${result.name}`);+ return text == null ? result : {...result, description: text};+ }),+ },+ };+}diff --git a/packages/cli/api/search/search-index.test.mjs b/packages/cli/api/search/search-index.test.mjsnew file mode 100644index 0000000000..50daba409f--- /dev/null+++ b/packages/cli/api/search/search-index.test.mjs@@ -0,0 +1,254 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++/**+ * @file A stored search index ranks as the folder's search does: an index of+ * the whole project, and per-package indexes plus a Core index when no package+ * replaces another's docs, ranked by `rankSearchIndex`, answer every golden+ * query with the whole response `search` gives in that project, linked+ * descriptions of an integration's components included.+ */++import fs from 'node:fs';+import os from 'node:os';+import path from 'node:path';+import {fileURLToPath} from 'node:url';+import {afterAll, beforeAll, describe, expect, it} from 'vitest';+import {search} from './search.mjs';+import {exportSearchIndex, rankSearchIndex} from './search-index.mjs';++const SLOW = 120_000;+const packages = path.resolve(+ path.dirname(fileURLToPath(import.meta.url)),+ '../../..',+);+const INTEGRATIONS = ['richtext', 'lab'];+const GOLDEN = [+ 'button',+ 'date picker',+ 'rich text editor',+ 'data table with filters',+ 'modal dialog',+ 'sidebar navigation',+ 'theme',+ 'empty state',+ 'avatar group',+ 'toast notification',+ 'useDebounce',+ 'search input',+ 'chart',+ 'settings page',+ 'comment thread',+ 'AcmeButton',+ 'branded press target',+];+const ACME = '@acme/ui';++/** An integration whose component description holds inline doc tokens. */+function writeAcme(dir) {+ const root = path.join(dir, 'node_modules', '@acme', 'ui');+ fs.mkdirSync(path.join(root, 'src'), {recursive: true});+ fs.writeFileSync(+ path.join(root, 'package.json'),+ JSON.stringify({+ name: ACME,+ version: '1.0.0',+ type: 'module',+ exports: {'./AcmeButton': './src/AcmeButton.tsx'},+ }),+ );+ fs.writeFileSync(+ path.join(root, 'astryx.integration.mjs'),+ "export default {components: './src'};\n",+ );+ fs.writeFileSync(+ path.join(root, 'src', 'AcmeButton.tsx'),+ 'export function AcmeButton() { return null; }\n',+ );+ fs.writeFileSync(+ path.join(root, 'src', 'AcmeButton.doc.mjs'),+ `export const docs = ${JSON.stringify({+ name: 'AcmeButton',+ displayName: 'Acme Button',+ category: 'Actions',+ description:+ 'AcmeButton is a branded press target. Add it with {@command component AcmeButton}.',+ keywords: ['acme button', 'branded button'],+ props: [],+ })};\n`,+ );+}++/**+ * @param {string} name+ * @param {string[]} linked+ */+function project(name, linked, acme = false) {+ const dir = fs.mkdtempSync(path.join(os.tmpdir(), `astryx-${name}-`));+ fs.writeFileSync(+ path.join(dir, 'package.json'),+ JSON.stringify({+ name,+ dependencies: Object.fromEntries([+ ...linked.map(pkg => [`@astryxdesign/${pkg}`, '*']),+ ...(acme ? [[ACME, '*']] : []),+ ]),+ }),+ );+ if (acme) writeAcme(dir);+ const scope = path.join(dir, 'node_modules', '@astryxdesign');+ fs.mkdirSync(scope, {recursive: true});+ for (const pkg of linked)+ fs.symlinkSync(path.join(packages, pkg), path.join(scope, pkg), 'dir');+ return dir;+}++/**+ * The whole response, as JSON carries it.+ * @param {unknown} response+ */+const ranked = response => JSON.parse(JSON.stringify(response));++describe('rankSearchIndex over stored indexes', () => {+ /** @type {string[]} */+ const dirs = [];+ /** @type {string} */+ let full;+ /** @type {import('./search.type.mjs').SearchIndex[]} */+ let indexes;+ beforeAll(async () => {+ full = project('full', ['core', ...INTEGRATIONS], true);+ const coreOnly = project('core-only', ['core']);+ dirs.push(full, coreOnly);+ indexes = [+ JSON.parse(JSON.stringify(await exportSearchIndex({cwd: coreOnly}))),+ ];+ for (const pkg of INTEGRATIONS) {+ const alone = project(pkg, ['core', pkg]);+ dirs.push(alone);+ const index = await exportSearchIndex({+ cwd: alone,+ package: `@astryxdesign/${pkg}`,+ });+ // Stored and read back, as a catalog keeps it.+ indexes.push(JSON.parse(JSON.stringify(index)));+ }+ const acme = project('acme', ['core'], true);+ dirs.push(acme);+ indexes.push(+ JSON.parse(+ JSON.stringify(await exportSearchIndex({cwd: acme, package: ACME})),+ ),+ );+ }, SLOW);+ afterAll(() => {+ for (const dir of dirs) fs.rmSync(dir, {recursive: true, force: true});+ });++ it.each(GOLDEN)(+ '`%s` from the whole-project index answers as search() does there',+ async query => {+ const whole = JSON.parse(+ JSON.stringify(await exportSearchIndex({cwd: full})),+ );+ const expected = ranked(await search(query, {cwd: full, limit: 50}));+ const actual = ranked(await rankSearchIndex(query, whole, {limit: 50}));+ expect(actual).toEqual(expected);+ },+ SLOW,+ );++ it.each(GOLDEN)(+ '`%s` from per-package indexes answers as search() does in the project',+ async query => {+ const expected = ranked(await search(query, {cwd: full, limit: 50}));+ const actual = ranked(await rankSearchIndex(query, indexes, {limit: 50}));+ expect(actual).toEqual(expected);+ },+ SLOW,+ );++ it(+ 'a domain restriction answers as search() does',+ async () => {+ const expected = ranked(+ await search('editor', {cwd: full, type: 'template', limit: 50}),+ );+ const actual = ranked(+ await rankSearchIndex('editor', indexes, {type: 'template', limit: 50}),+ );+ expect(actual).toEqual(expected);+ },+ SLOW,+ );++ it(+ "an integration component's description prints with its tokens resolved",+ async () => {+ const {results} = (await rankSearchIndex('AcmeButton', indexes)).data;+ expect(results[0]).toMatchObject({package: ACME, name: 'AcmeButton'});+ expect(results[0].description).not.toContain('{@');+ expect(results[0].description).toContain('astryx component AcmeButton');+ },+ SLOW,+ );++ it('reports meta.partial when no index had Core, as search() does', async () => {+ const docsOnly = {+ ...indexes[0],+ candidates: indexes[0].candidates.filter(c => c.domain === 'doc'),+ coreSkipped: 'Core is not installed here.',+ };+ const response = await rankSearchIndex('button', [docsOnly]);+ expect(response.meta?.partial).toMatchObject({+ reason: 'Core is not installed here.',+ });+ const withCore = await rankSearchIndex('button', [docsOnly, indexes[1]]);+ expect(withCore.meta?.partial).toBeUndefined();+ // A docs-only search never reads Core, so it reports nothing skipped.+ const docs = await rankSearchIndex('button', [docsOnly], {type: 'doc'});+ expect(docs.meta?.partial).toBeUndefined();+ // A domain that reads Core, asked for by name, is refused as search() is.+ await expect(+ rankSearchIndex('button', [docsOnly], {type: 'component'}),+ ).rejects.toMatchObject({code: 'ERR_CORE_NOT_FOUND'});+ // The stored lookup error is the one thrown.+ const uncached = {...docsOnly, coreSkippedCode: 'ERR_VERSIONS_UNAVAILABLE'};+ await expect(+ rankSearchIndex('button', [uncached], {type: 'hook'}),+ ).rejects.toMatchObject({code: 'ERR_VERSIONS_UNAVAILABLE'});+ const open = await rankSearchIndex('button', [uncached]);+ expect(open.meta?.partial?.skipped).toEqual([+ 'component',+ 'hook',+ 'template',+ ]);+ });++ it('a package index holds only that package, with no folder paths', () => {+ const index = indexes[1];+ expect(index.candidates.length).toBeGreaterThan(0);+ for (const candidate of index.candidates) {+ expect(candidate._package).toBe('@astryxdesign/richtext');+ expect(candidate).not.toHaveProperty('_docPath');+ }+ });++ it('refuses an index made by another CLI version', async () => {+ const stale = {...indexes[0], version: '0.0.0-other'};+ await expect(rankSearchIndex('button', [stale])).rejects.toMatchObject({+ code: 'ERR_INVALID_ARGUMENT',+ });+ });++ it('refuses a value that is not an index', async () => {+ await expect(+ rankSearchIndex('button', /** @type {any} */ ([{candidates: null}])),+ ).rejects.toMatchObject({code: 'ERR_INVALID_ARGUMENT'});+ });++ it('refuses an empty package name', async () => {+ await expect(+ exportSearchIndex({cwd: full, package: ' '}),+ ).rejects.toMatchObject({code: 'ERR_INVALID_ARGUMENT'});+ });+});diff --git a/packages/cli/api/search/search.type.mjs b/packages/cli/api/search/search.type.mjsindex 7202d6c5ba..270b2dc5e1 100644--- a/packages/cli/api/search/search.type.mjs+++ b/packages/cli/api/search/search.type.mjs@@ -51,6 +51,23 @@* The results are the docs and themes.*/+/**+ * The candidates `search` ranks in a folder, as `exportSearchIndex()` returns them:+ * plain JSON to store and rank later with `rankSearchIndex()`.+ * @experimental May change or be removed in a patch release.+ * @typedef {object} SearchIndex+ * @property {string} version - The CLI version that made it. `rankSearchIndex()`+ * ranks only indexes made by its own version.+ * @property {Record<string, unknown>[]} candidates - The gathered candidates,+ * each the entry search scores. Their fields are the ranker's input, not a+ * contract: they may change in any release, which is why `version` must match.+ * @property {string} [coreSkipped] - Why Core could not be had where the index+ * was made, when it could not: its components, hooks and templates are then+ * missing, and `rankSearchIndex()` answers as `search` does without Core+ * (`meta.partial` for an open search; refused for a domain that reads Core).+ * @property {string} [coreSkippedCode] - The error code that Core lookup gave.+ */+/*** Options for `search()`.* @typedef {object} SearchOptions