An open source design system that's fully customizable and agent ready
TypeScript
feat(docsite): search panel runs the CLI's own search (#7830)
Joeyd6ee72b7997a
diff --git a/.changeset/search-reuses-gathered-catalog.md b/.changeset/search-reuses-gathered-catalog.mdnew file mode 100644index 0000000000..5ce101d55b--- /dev/null+++ b/.changeset/search-reuses-gathered-catalog.md@@ -0,0 +1,7 @@+---+'@astryxdesign/cli': patch+---++[fix] `search()` from `@astryxdesign/cli/api` answers faster when one process searches again: it reuses the components, docs, templates and themes it gathered for the same folder and `type` while no file it read, and no folder it listed, has changed since (a linked workspace package included). To see those reads, the first such search in a process wraps `node:fs`'s read functions for that process; outside a search they behave exactly as before. Results are unchanged. Short-lived runs are unaffected: each `astryx search` command gathers once, as before.++@josephfarinadiff --git a/apps/docsite/next.config.mjs b/apps/docsite/next.config.mjsindex 16f15b1036..de34c14a3b 100644--- a/apps/docsite/next.config.mjs+++ b/apps/docsite/next.config.mjs@@ -38,6 +38,34 @@ const stagesStaticApps =/** @type {import('next').NextConfig} */const nextConfig = {cacheComponents: true,+ // The search API (app/api/search) runs `astryx search` itself. The CLI stays+ // an external module (see webpack below), so its code and dependencies are+ // traced as installed; these are the files it reads from disk at run time:+ // its docs and templates, and each documented package's docs and sources.+ outputFileTracingIncludes: {+ '/api/search': [+ './astryx.config.mjs',+ '../../packages/cli/package.json',+ '../../packages/cli/{api,assets,authoring,clients,foundation,host}/**/*',+ '../../packages/core/package.json',+ '../../packages/core/src/**/*',+ // Integrations resolve through the site's node_modules, so they are+ // traced at that path.+ './node_modules/@astryxdesign/{lab,charts,richtext,vega}/{package.json,astryx.integration.mjs}',+ './node_modules/@astryxdesign/{lab,charts,richtext,vega}/{src,blocks,docs,dist}/**/*',+ ],+ },+ // Packages the CLI imports for other commands but a search never loads+ // (bundlers, compilers, browsers, test runners), and built output it never+ // reads. Leaving them out keeps the search function small; the parity test+ // and a traced-files-only build hold it to `astryx search`.+ outputFileTracingExcludes: {+ '/api/search': [+ '../../node_modules/.pnpm/{esbuild,@esbuild+*,typescript,playwright,playwright-core,vite,rolldown,@rolldown+*,flow-parser,esprima,tsx,vitest,@vitest+*,chai,@testing-library+*}@*/**',+ '../../packages/*/dist/**',+ './src/**',+ ],+ },// Sandbox exports trailing-slash directories; Next's automatic slash// redirect runs before rewrites. Vercel deployments preserve those URLs;// local builds keep the docsite's existing canonical redirects.@@ -120,6 +148,14 @@ const nextConfig = {];},webpack: (config, {isServer, webpack}) => {+ // The search API loads the CLI as installed, never bundled: the CLI reads+ // its docs, templates and the installed packages from disk.+ if (isServer) {+ config.externals = [+ ...[config.externals ?? []].flat(),+ {'@astryxdesign/cli/api': 'module @astryxdesign/cli/api'},+ ];+ }// Webpack's CSS @import resolver doesn't follow package.json "exports".// Map each theme's /theme.css subpath to the actual dist file.const themesDir = resolve(import.meta.dirname, '../../packages/themes');diff --git a/apps/docsite/scripts/generate-data.mjs b/apps/docsite/scripts/generate-data.mjsindex aa738c4bb6..8592ca8386 100644--- a/apps/docsite/scripts/generate-data.mjs+++ b/apps/docsite/scripts/generate-data.mjs@@ -36,6 +36,7 @@ import {mergeFlatTopics,namespacePage,routeSlug,+ sectionAnchors,withCliCommands,withoutResolvedTokens,} from './docs-pages.mjs';@@ -58,6 +59,7 @@ import {} from '../src/lib/integrationTargets.mjs';import {expandWorkspaceDirs} from '../../../scripts/lib/workspace-globs.mjs';import {projectThemingDoc} from './lib/theming-doc.mjs';+import {searchLinkTables} from '../src/lib/searchLinks.mjs';import {collectBlogImages} from './lib/blog-images.mjs';import {buildTypeDefinitionIndex,@@ -1999,6 +2001,46 @@ export const docRedirects: Record<string, string> = ${JSON.stringify(docRedirectreturn {docTopics, docsCount: docTopics.length};}+/**+ * The tables the search panel opens a CLI search result through+ * (src/lib/searchLinks.mjs): this build's doc pages, redirects, section+ * anchors, component and template pages, and the page each block shows on.+ * The search API (app/api/search/route.ts) reads them.+ */+function generateSearchLinks({+ docTopics,+ allComponents,+ templates,+ blocks,+ packages,+}) {+ const docRedirects = JSON.parse(+ fs.readFileSync(path.join(OUT_DIR, 'docRedirects.json'), 'utf-8'),+ );+ const tables = searchLinkTables({+ docTopics,+ docRedirects,+ components: Object.values(allComponents)+ .flat()+ .map(c => c.name),+ templates: templates.map(t => t.slug),+ blocks,+ // The package pages /docs/[topic] serves; theme packages show on /themes.+ packagePages: packages+ .map(p => p.name)+ .filter(name => !name.startsWith('@astryxdesign/theme-'))+ .map(name => name.replace('@astryxdesign/', '')),+ sectionAnchors,+ });+ fs.writeFileSync(+ path.join(OUT_DIR, 'searchLinks.json'),+ `${JSON.stringify(tables)}\n`,+ );+ console.log(+ ` wrote ${path.relative(REPO_ROOT, path.join(OUT_DIR, 'searchLinks.json'))}`,+ );+}+async function generateThemeRegistry(packages) {console.log('Generating theme registry...');const themePackages = packages.filter(p =>@@ -2528,7 +2570,8 @@ async function main() {const {blocks, blockCount} = await generateBlockRegistry();generatePackageStyles(packages, blocks, allComponents);const {templates, templateCount} = await generateTemplateRegistry();- const {docsCount} = await generateDocsRegistry();+ const {docTopics, docsCount} = await generateDocsRegistry();+ generateSearchLinks({docTopics, allComponents, templates, blocks, packages});const {blogPostCount} = await generateBlogRegistry();const shadcnCounts = generateShadcnRegistryForTarget({target: DOCSITE_TARGET,diff --git a/apps/docsite/src/__tests__/cli-search.test.ts b/apps/docsite/src/__tests__/cli-search.test.tsnew file mode 100644index 0000000000..57006d0885--- /dev/null+++ b/apps/docsite/src/__tests__/cli-search.test.ts@@ -0,0 +1,324 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++/**+ * @file The site's search answers what `astryx search` answers.+ *+ * The search panel asks the site's search API (app/api/search/route.ts),+ * which calls the CLI's `search()`. These tests hold it to the CLI: for a+ * fixed list of public, made-up queries, the API's results are the results+ * `astryx search --json` prints from this site's project, in the same order;+ * every result opens a page the site has; and the panel keeps the CLI's order.+ */++import {execFile} from 'node:child_process';+import path from 'node:path';+import {promisify} from 'node:util';+import {describe, expect, it} from 'vitest';+import type {SearchResponse} from '@astryxdesign/cli/api';+import {GET} from '../app/api/search/route';+import {searchResultHref} from '../lib/searchLinks.mjs';+import type {SearchLinkTables} from '../lib/searchLinks.mjs';+import {+ createCliSearchSource,+ searchTarget,+ toSearchItem,+} from '../lib/cliSearchSource';+import type {SiteSearchResult} from '../lib/cliSearchTypes';+import docsiteConfig from '../../astryx.config.mjs';+import {docTopics, docRedirects} from '../generated/docsRegistry';+import {packages} from '../generated/packageRegistry';+import admittedRecord from '../generated/integrationPackages.json';+import linkTables from '../generated/searchLinks.json';++const run = promisify(execFile);+const ROOT = path.resolve(import.meta.dirname, '../..');+const ASTRYX = path.join(ROOT, 'node_modules', '.bin', 'astryx');+const links = linkTables as SearchLinkTables;+const SLOW = 120_000;++/** Public, made-up queries across every domain. */+const QUERIES = [+ 'button',+ 'date picker',+ 'dark mode',+ 'how do I theme my app',+ 'sidebar layout',+ 'table with sorting',+ 'modal dialog',+ 'tokens spacing',+ 'toast notification',+ 'login form',+ 'useMediaQuery',+ 'chart',+];++/** What the site's API answers for a query. */+async function api(query: string) {+ const response = await GET(+ new Request(`http://site/api/search?q=${encodeURIComponent(query)}`),+ );+ expect(response.status).toBe(200);+ return (await response.json()) as SearchResponse & {+ data: {results: SiteSearchResult[]};+ };+}++// The API answers for the packages this build documents. On canary that is+// every configured integration, the same set `astryx search` reads here.+const documentsEveryIntegration =+ docsiteConfig.integrations.length === admittedRecord.packages.length;++describe('site search = astryx search', () => {+ it.skipIf(!documentsEveryIntegration)(+ 'answers each query with the results `astryx search --json` prints',+ async () => {+ const printed = await Promise.all(+ QUERIES.map(async query => {+ const {stdout} = await run(ASTRYX, ['search', query, '--json'], {+ cwd: ROOT,+ maxBuffer: 16 * 1024 * 1024,+ });+ return JSON.parse(stdout) as SearchResponse;+ }),+ );+ for (const [i, query] of QUERIES.entries()) {+ const {data} = await api(query);+ expect(data.results.length, query).toBeGreaterThan(0);+ const {results: siteResults, ...rest} = data;+ const results = siteResults as SiteSearchResult[];+ const {results: cliResults, ...cliRest} = printed[i].data;+ expect(rest, query).toEqual(cliRest);+ expect(+ results.map(+ ({href: _href, siteTitle: _siteTitle, ...result}) => result,+ ),+ query,+ ).toEqual(cliResults);+ }+ },+ SLOW,+ );++ it('refuses an empty or overlong query', async () => {+ for (const q of ['', ' ', 'x'.repeat(201)]) {+ const response = await GET(+ new Request(`http://site/api/search?q=${encodeURIComponent(q)}`),+ );+ expect(response.status).toBe(400);+ }+ });+});++describe('site search links', () => {+ const pages = new Set([+ ...docTopics.map(topic => topic.topic),+ ...packages+ .map(p => p.name)+ .filter(name => !name.startsWith('@astryxdesign/theme-'))+ .map(name => name.replace('@astryxdesign/', '')),+ ]);+ const redirectTargets = new Set(Object.values(docRedirects));+ const components = new Set(links.components);+ const templates = new Set(links.templates);++ /** Whether the site serves this path. */+ const served = (href: string): boolean => {+ if (['/components', '/templates', '/themes', '/docs'].includes(href)) {+ return true;+ }+ if (redirectTargets.has(href)) {+ return true;+ }+ const [pathname] = href.split('#');+ const [, area, slug] = pathname.split('/');+ if (area === 'components') {+ return components.has(slug);+ }+ if (area === 'templates') {+ return templates.has(slug);+ }+ if (area === 'docs') {+ return pages.has(slug);+ }+ return false;+ };++ it(+ 'opens a page the site has for every result of every query',+ async () => {+ for (const query of QUERIES) {+ for (const result of (await api(query)).data.results) {+ expect(+ served(result.href),+ `${query}: ${result.domain} ${result.name} -> ${result.href}`,+ ).toBe(true);+ }+ }+ },+ SLOW,+ );++ it("opens a section at its own guide's anchor when a page repeats its key", () => {+ // A namespace page holds several guides' sections, and section keys are+ // unique only within a guide. Group the guide-keyed entries by page and+ // key: each guide's copy must open its own anchor.+ const byKey = new Map<string, {starts: Set<string>; hrefs: Set<string>}>();+ for (const [key, href] of Object.entries(links.anchors)) {+ const [guide, section] = key.split('#');+ const page = href.split('#')[0];+ const target = links.redirects[guide];+ if (!target || target.split('#')[0] !== page) {+ continue;+ }+ const group = `${page} ${section}`;+ if (!byKey.has(group)) {+ byKey.set(group, {starts: new Set(), hrefs: new Set()});+ }+ // A namespace with no text of its own starts where its first guide does.+ byKey.get(group)!.starts.add(target);+ byKey.get(group)!.hrefs.add(href);+ }+ const repeated = [...byKey.entries()].filter(([, v]) => v.starts.size > 1);+ expect(+ repeated.length,+ 'a page that repeats a section key',+ ).toBeGreaterThan(0);+ for (const [group, {starts, hrefs}] of repeated) {+ expect(hrefs.size, group).toBe(starts.size);+ }+ });++ it("opens an integration's example block on its component page", () => {+ const blocks = Object.entries(links.blocks).filter(([key]) =>+ key.startsWith('-astryxdesign-'),+ );+ expect(blocks.length).toBeGreaterThan(0);+ for (const [key, page] of blocks) {+ const [, pkg, name] = /^-astryxdesign-([a-z]+)-(.+)$/.exec(key)!;+ expect(+ searchResultHref(+ {+ domain: 'template',+ kind: 'block',+ name,+ package: `@astryxdesign/${pkg}`,+ },+ links,+ ),+ key,+ ).toBe(page);+ }+ });++ it(+ 'titles doc results the way the site does, never with the docs-tree path',+ async () => {+ for (const query of [+ 'authoring',+ 'how do I theme my app',+ 'tokens spacing',+ ]) {+ for (const result of (await api(query)).data.results) {+ if (result.domain !== 'doc') continue;+ expect(result.siteTitle, `${query}: ${result.name}`).toBeTruthy();+ expect(result.siteTitle).not.toMatch(/Unorganized/);+ }+ }+ },+ SLOW,+ );++ it('opens a doc section at its anchor', () => {+ const href = searchResultHref(+ {domain: 'doc', name: 'author-a-theme', section: 'palette'},+ links,+ );+ expect(href).toMatch(/^\/docs\/theme#/);+ });+});++describe('search panel order', () => {+ it(+ 'keeps the CLI order: no groups, one item per place',+ async () => {+ const {data} = await api('button');+ const urls: string[] = [];+ const source = createCliSearchSource(async url => {+ urls.push(url);+ return new Response(JSON.stringify({data}));+ });+ expect(source.bootstrap()).toEqual([]);+ const items = await source.search('button');+ expect(urls).toEqual(['/api/search?q=button']);+ const results = data.results as SiteSearchResult[];+ const firstPerPlace = results.filter(+ (result, i) =>+ results.findIndex(other => other.href === result.href) === i,+ );+ expect(items.map(item => item.auxiliaryData.name)).toEqual(+ firstPerPlace.map(result => result.name),+ );+ expect(new Set(items.map(item => item.id)).size).toBe(items.length);+ for (const item of items) {+ expect(item.auxiliaryData).not.toHaveProperty('group');+ expect(source.item(item.id)).toBe(item);+ }+ expect(toSearchItem(data.results[0], 0).label).toBeTruthy();+ },+ SLOW,+ );++ it(+ 'lists each place once, with a label no other row has',+ async () => {+ for (const query of ['dark mode', 'authoring', 'tokens spacing']) {+ const {data} = await api(query);+ const source = createCliSearchSource(+ async () => new Response(JSON.stringify({data})),+ );+ const items = await source.search(query);+ const hrefs = items.map(item => item.auxiliaryData.href);+ expect(new Set(hrefs).size, `${query}: ${hrefs}`).toBe(hrefs.length);+ const docLabels = items+ .filter(item => item.auxiliaryData.domain === 'doc')+ .map(item => item.label);+ expect(new Set(docLabels).size, `${query}: ${docLabels}`).toBe(+ docLabels.length,+ );+ }+ },+ SLOW,+ );++ it('reports a selection by what it opens, as the registries name it', () => {+ expect(searchTarget('/components/Button')).toEqual({+ item: 'Button',+ type: 'component',+ });+ expect(searchTarget('/docs/theme#dark-mode')).toEqual({+ item: 'theme',+ type: 'doc',+ });+ expect(searchTarget('/templates/login')).toEqual({+ item: 'login',+ type: 'template',+ });+ expect(searchTarget('/themes')).toEqual({item: 'themes', type: 'theme'});+ });++ it('sends only the last query typed', async () => {+ const urls: string[] = [];+ const source = createCliSearchSource(async (url, init) => {+ urls.push(url);+ if (init.signal?.aborted) {+ throw new Error('aborted');+ }+ return new Response(JSON.stringify({data: {results: []}}));+ });+ const first = source.search('bu');+ const second = source.search('button');+ expect(await first).toEqual([]);+ await second;+ expect(urls).toEqual(['/api/search?q=button']);+ });+});diff --git a/apps/docsite/src/__tests__/component-sidebar-data.test.ts b/apps/docsite/src/__tests__/component-sidebar-data.test.tsnew file mode 100644index 0000000000..b187c3d90f--- /dev/null+++ b/apps/docsite/src/__tests__/component-sidebar-data.test.ts@@ -0,0 +1,72 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++/**+ * @file Component sidebar grouping: ready families stay unified, and canary-only+ * packages are grouped by package with their components marked not ready.+ */++import {describe, it, expect} from 'vitest';+import {components} from '../generated/componentRegistry';+import {packages} from '../generated/packageRegistry';+import {+ flattenComponentSidebarEntries,+ getComponentSidebarData,+} from '../components/componentSidebarData';++describe('component sidebar data', () => {+ it('marks canary-only package components not ready, and every other one ready', () => {+ const entries = flattenComponentSidebarEntries();+ const canaryPackages = new Set(+ packages.filter(pkg => pkg.canaryOnly).map(pkg => pkg.name),+ );+ const canaryEntries = entries.filter(entry =>+ canaryPackages.has(entry.packageName),+ );++ expect(canaryEntries.length).toBeGreaterThan(0);+ expect(canaryEntries.every(entry => !entry.isReady)).toBe(true);+ expect(+ entries+ .filter(entry => !canaryPackages.has(entry.packageName))+ .every(entry => entry.isReady),+ ).toBe(true);+ });++ it('keeps ready families unified and groups canary components by package', () => {+ const {componentItems, canaryCategories} = getComponentSidebarData();+ const readyGroups = componentItems.filter(item => item.type === 'group');++ expect(readyGroups.filter(group => group.label === 'Chat')).toHaveLength(1);+ expect(+ readyGroups+ .find(group => group.label === 'Chat')+ ?.entries.every(entry => entry.isReady),+ ).toBe(true);++ // One canary category per canary-only package with components; a+ // configured integration that is a stable release joins the ready view.+ expect(canaryCategories.map(category => category.displayName)).toEqual(+ packages+ .filter(pkg => pkg.canaryOnly && components[pkg.name]?.length)+ .map(pkg => pkg.displayName)+ .sort((a, b) => a.localeCompare(b)),+ );+ const chartEntries = canaryCategories.flatMap(category =>+ category.componentItems.flatMap(item =>+ item.type === 'entry' || item.label !== 'Charts' ? [] : item.entries,+ ),+ );+ expect(chartEntries.map(entry => entry.name)).toEqual(+ expect.arrayContaining(['Chart', 'ChartSwatch', 'ChartBar', 'ChartLine']),+ );+ expect(chartEntries.every(entry => !entry.isReady)).toBe(true);++ const lab = canaryCategories.find(+ category => category.displayName === 'Lab',+ );+ const threeD = lab?.componentItems.find(+ item => item.type === 'group' && item.label === '3D',+ );+ expect(threeD?.displayName).toBe('3D');+ });+});diff --git a/apps/docsite/src/__tests__/hidden-shadcn-production.test.ts b/apps/docsite/src/__tests__/hidden-shadcn-production.test.tsindex bcdc747be9..3aeffc2fa4 100644--- a/apps/docsite/src/__tests__/hidden-shadcn-production.test.ts+++ b/apps/docsite/src/__tests__/hidden-shadcn-production.test.ts@@ -25,36 +25,34 @@ const [{GET: getLlmsTxt},{GET: getRss},{POST: postMcp},+ {GET: getSearch},{CURRENT_TARGET},{components},{blocks},{templates},{docTopics},{blogPosts},- {packages},{showcaseRegistry},{exampleRegistry},{shadcnRegistryIsPreview, shadcnRegistryOrigin},{flattenComponentSidebarEntries},- {buildSearchPaletteItems},] = await Promise.all([import('../app/robots'),import('../app/sitemap'),import('../app/llms.txt/route'),import('../app/rss.xml/route'),import('../app/mcp/route'),+ import('../app/api/search/route'),import('../lib/docsVersions'),import('../generated/componentRegistry'),import('../generated/blockRegistry'),import('../generated/templateRegistry'),import('../generated/docsRegistry'),import('../generated/blogRegistry'),- import('../generated/packageRegistry'),import('../generated/showcaseRegistry'),import('../generated/exampleRegistry'),import('../generated/shadcnRegistry'),import('../components/componentSidebarData'),- import('../components/searchPaletteData'),]);const FORBIDDEN_DISCOVERY_PATTERNS = [@@ -193,18 +191,6 @@ describeHiddenProduction('hidden production ShadCN discovery', () => {href: entry.href,label: entry.displayName,}));- const search = buildSearchPaletteItems({- components,- packages,- docTopics,- templates,- }).map(item => ({- id: item.id,- label: item.label,- group: item.auxiliaryData.group,- keywords: item.auxiliaryData.keywords,- }));-expectNoShadcnPromotion(docTopics.map(topic => ({topic: topic.topic, title: topic.title})),'docs navigation',@@ -214,9 +200,28 @@ describeHiddenProduction('hidden production ShadCN discovery', () => {'blog indexes',);expectNoShadcnPromotion(sidebar, 'component navigation');- expectNoShadcnPromotion(search, 'global search');});+ it('keeps the site search (astryx search) free of registry promotion', async () => {+ // Like the MCP search below, it may name ShadCN only inside the CLI's own+ // docs (the migration guide); it never points at the registry.+ const response = await getSearch(+ new Request('http://site/api/search?q=shadcn%20registry%20install'),+ );+ const {data} = (await response.json()) as {+ data: {results: Array<Record<string, unknown>>};+ };+ expectNoRegistryDiscovery(data, 'site search');+ for (const result of data.results) {+ if (/shadcn/i.test(JSON.stringify(result))) {+ expect(result).toMatchObject({+ domain: 'doc',+ package: '@astryxdesign/cli',+ });+ }+ }+ }, 60_000);+it('keeps sitemap, RSS, and llms.txt clean', async () => {const sitemapEntries = await sitemap();const rss = await (await getRss()).text();diff --git a/apps/docsite/src/__tests__/search-palette.test.ts b/apps/docsite/src/__tests__/search-palette.test.tsdeleted file mode 100644index 552d9abb23..0000000000--- a/apps/docsite/src/__tests__/search-palette.test.ts+++ /dev/null@@ -1,149 +0,0 @@-// Copyright (c) Meta Platforms, Inc. and affiliates.--/**- * @file Search palette data tests.- *- * Validates that the global docsite command palette indexes the same component- * links as the sidebar.- */--import {describe, it, expect} from 'vitest';-import {components} from '../generated/componentRegistry';-import {packages} from '../generated/packageRegistry';-import {docTopics} from '../generated/docsRegistry';-import {templateMetadata as templates} from '../generated/templateMetadataRegistry';-import {- flattenComponentSidebarEntries,- getComponentSidebarData,-} from '../components/componentSidebarData';-import {- buildSearchPaletteItems,- getSearchItemKeywords,-} from '../components/searchPaletteData';--function buildItems() {- return buildSearchPaletteItems({- components,- packages,- docTopics,- templates,- });-}--function searchItems(query: string) {- const lower = query.toLowerCase().trim();- return buildItems().filter(- item =>- item.label.toLowerCase().includes(lower) ||- getSearchItemKeywords(item).some(kw => kw.toLowerCase().includes(lower)),- );-}--describe('SearchPalette data', () => {- it('uses the sidebar entries as the command palette component set', () => {- const componentIds = buildItems()- .filter(item =>- ['Component', 'Canary component'].includes(item.auxiliaryData.group),- )- .map(item => item.id);- const sidebarIds = flattenComponentSidebarEntries().map(- entry => entry.href,- );-- expect(new Set(componentIds).size).toBe(componentIds.length);- expect(new Set(componentIds)).toEqual(new Set(sidebarIds));- expect(componentIds).toContain('/components/DropdownMenu');- expect(componentIds).toContain('/components/DropdownMenuItem');- expect(componentIds).toContain('/components/CommandPalette');- expect(componentIds).toContain('/components/Table');- });-- it('includes canary-only component packages with canary metadata', () => {- const entries = flattenComponentSidebarEntries();- const items = buildItems();- const canaryPackages = new Set(- packages.filter(pkg => pkg.canaryOnly).map(pkg => pkg.name),- );- const canaryEntries = entries.filter(entry =>- canaryPackages.has(entry.packageName),- );-- expect(canaryEntries.length).toBeGreaterThan(0);- expect(canaryEntries.every(entry => !entry.isReady)).toBe(true);- expect(- canaryEntries.every(entry => {- const item = items.find(item => item.id === entry.href);- return (- item?.auxiliaryData.isReady === false &&- item.auxiliaryData.group === 'Canary component'- );- }),- ).toBe(true);- expect(- entries- .filter(entry => !canaryPackages.has(entry.packageName))- .every(entry => entry.isReady),- ).toBe(true);- });-- it('keeps ready families unified and groups canary components by package', () => {- const {componentItems, canaryCategories} = getComponentSidebarData();- const readyGroups = componentItems.filter(item => item.type === 'group');-- expect(readyGroups.filter(group => group.label === 'Chat')).toHaveLength(1);- expect(- readyGroups- .find(group => group.label === 'Chat')- ?.entries.every(entry => entry.isReady),- ).toBe(true);-- // One canary category per canary-only package with components; a- // configured integration that is a stable release joins the ready view.- expect(canaryCategories.map(category => category.displayName)).toEqual(- packages- .filter(pkg => pkg.canaryOnly && components[pkg.name]?.length)- .map(pkg => pkg.displayName)- .sort((a, b) => a.localeCompare(b)),- );- const chartEntries = canaryCategories.flatMap(category =>- category.componentItems.flatMap(item =>- item.type === 'entry' || item.label !== 'Charts' ? [] : item.entries,- ),- );- expect(chartEntries.map(entry => entry.name)).toEqual(- expect.arrayContaining(['Chart', 'ChartSwatch', 'ChartBar', 'ChartLine']),- );- expect(chartEntries.every(entry => !entry.isReady)).toBe(true);-- const lab = canaryCategories.find(- category => category.displayName === 'Lab',- );- const threeD = lab?.componentItems.find(- item => item.type === 'group' && item.label === '3D',- );- expect(threeD?.displayName).toBe('3D');- });-- it('finds Dropdown Menu by spaced display name and PascalCase API name', () => {- const items = buildItems();- const dropdown = items.find(item => item.id === '/components/DropdownMenu');- expect(dropdown?.label).toBe('Dropdown Menu');-- expect(searchItems('dropdown menu').map(item => item.id)).toContain(- '/components/DropdownMenu',- );- expect(searchItems('DropdownMenu').map(item => item.id)).toContain(- '/components/DropdownMenu',- );- });-- it('finds AppShell when searching for app shell with a space', () => {- const items = buildItems();- const appShell = items.find(item => item.id === '/components/AppShell');- expect(appShell?.label).toBe('App Shell');-- expect(searchItems('app shell').map(item => item.id)).toContain(- '/components/AppShell',- );- });-});diff --git a/apps/docsite/src/app/api/search/route.ts b/apps/docsite/src/app/api/search/route.tsnew file mode 100644index 0000000000..5041c2c4ff--- /dev/null+++ b/apps/docsite/src/app/api/search/route.ts@@ -0,0 +1,81 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++/**+ * @file GET /api/search?q=<query>: `astryx search <query>`, run by the site.+ * @input The query, as `astryx search` takes it.+ * @output The CLI's search response, each result with the site path it opens.+ * @position Called by the search panel (lib/cliSearchSource.ts).+ *+ * The site's search is the CLI's: this calls `search()` from+ * `@astryxdesign/cli/api`, the function behind `astryx search --json`, in this+ * site's project, so the panel gives the CLI's results in the CLI's order and+ * every change to the CLI's search reaches the site. Nothing here ranks.+ */++import {search} from '@astryxdesign/cli/api';+import {+ searchResultHref,+ searchResultTitle,+} from '../../../lib/searchLinks.mjs';+import type {SearchLinkTables} from '../../../lib/searchLinks.mjs';+import links from '../../../generated/searchLinks.json';+import admitted from '../../../generated/integrationPackages.json';+import docsiteConfig from '../../../../astryx.config.mjs';++/** Packages this build documents: Core, the CLI's docs and themes, and the+ * integrations it admits (canary: all configured; latest: stable ones). */+const DOCUMENTED = new Set([+ '@astryxdesign/core',+ '@astryxdesign/cli',+ ...admitted.packages,+]);++/** Whether this build leaves out an integration the site's project has. */+const FILTERED = docsiteConfig.integrations.some(+ (name: string) => !DOCUMENTED.has(name),+);++/** How many results the panel shows: `astryx search`'s default. */+const LIMIT = 20;++/** Longest query the API accepts. */+const MAX_QUERY = 200;++export async function GET(request: Request): Promise<Response> {+ const query = new URL(request.url).searchParams.get('q')?.trim() ?? '';+ if (query === '' || query.length > MAX_QUERY) {+ return Response.json(+ {error: `q must be 1 to ${MAX_QUERY} characters`},+ {status: 400},+ );+ }+ // When this build leaves out an integration, ask for every match, drop+ // that integration's, then count and cut to the panel's 20; otherwise this+ // is exactly `astryx search <query>`.+ const response = await search(query, {+ cwd: process.cwd(),+ ...(FILTERED ? {limit: Number.MAX_SAFE_INTEGER} : {}),+ });+ const kept = FILTERED+ ? response.data.results.filter(+ result => result.package == null || DOCUMENTED.has(result.package),+ )+ : response.data.results;+ const matchCount = FILTERED ? kept.length : response.data.matchCount;+ const results = kept.slice(0, LIMIT).map(result => {+ const href = searchResultHref(result, links as SearchLinkTables);+ const siteTitle = searchResultTitle(+ result,+ href,+ links as SearchLinkTables,+ );+ return {...result, href, ...(siteTitle ? {siteTitle} : {})};+ });+ return Response.json(+ {...response, data: {...response.data, matchCount, results}},+ {+ // A query's answer changes only when the site is rebuilt.+ headers: {'Cache-Control': 'public, max-age=300, s-maxage=86400'},+ },+ );+}diff --git a/apps/docsite/src/components/SearchPalette.tsx b/apps/docsite/src/components/SearchPalette.tsxindex f65e4dfc22..acb7f2686e 100644--- a/apps/docsite/src/components/SearchPalette.tsx+++ b/apps/docsite/src/components/SearchPalette.tsx@@ -6,60 +6,38 @@ import {useMemo, useCallback} from 'react';import {useRouter} from 'next/navigation';import {CommandPalette} from '@astryxdesign/core/CommandPalette';import {Text} from '@astryxdesign/core/Text';-import {createStaticSource} from '@astryxdesign/core/Typeahead';-import {components} from '../generated/componentRegistry';-import {packages} from '../generated/packageRegistry';-import {docTopics} from '../generated/docsRegistry';-import {templateMetadata} from '../generated/templateMetadataRegistry';import {trackSearch} from '../lib/analytics';import {- buildSearchPaletteItems,- getSearchItemKeywords,-} from './searchPaletteData';+ createCliSearchSource,+ resultKind,+ searchTarget,+} from '../lib/cliSearchSource';interface SearchPaletteProps {isOpen: boolean;onOpenChange: (open: boolean) => void;}+/**+ * The site's search: `astryx search`, run by the site's search API+ * (app/api/search/route.ts), so it answers what the CLI answers.+ */export function SearchPalette({isOpen, onOpenChange}: SearchPaletteProps) {const router = useRouter();- // Component items come from the same grouped registry as the sidebar so- // sidebar and command palette navigation stay in lockstep.- const searchSource = useMemo(() => {- const items = buildSearchPaletteItems({- components,- packages,- docTopics,- templates: templateMetadata,- });-- return createStaticSource(items, {- keywords: getSearchItemKeywords,- });- }, []);+ const searchSource = useMemo(() => createCliSearchSource(), []);const handleValueChange = useCallback(- (value: string) => {- if (value && value.startsWith('/')) {- // Determine type from path prefix- const type = value.startsWith('/components/')- ? 'component'- : value.startsWith('/templates/')- ? 'template'- : value.startsWith('/themes/')- ? 'theme'- : value.startsWith('/docs/')- ? 'doc'- : 'page';- const item = value.split('/').pop() || value;- trackSearch({target: 'select', item, type});- router.push(value);- onOpenChange(false);+ (id: string) => {+ const result = searchSource.item(id)?.auxiliaryData;+ if (!result) {+ return;}+ trackSearch({target: 'select', ...searchTarget(result.href)});+ router.push(result.href);+ onOpenChange(false);},- [router, onOpenChange],+ [searchSource, router, onOpenChange],);return (@@ -67,7 +45,15 @@ export function SearchPalette({isOpen, onOpenChange}: SearchPaletteProps) {isOpen={isOpen}onOpenChange={onOpenChange}searchSource={searchSource}- renderItem={item => <Text type="inherit">{item.label}</Text>}+ renderItem={item => (+ <Text type="inherit">+ {item.label}+ <Text type="supporting" color="secondary">+ {' '}+ {resultKind(item.auxiliaryData)}+ </Text>+ </Text>+ )}label="Search docs, components, and templates"value=""onValueChange={handleValueChange}diff --git a/apps/docsite/src/components/searchPaletteData.ts b/apps/docsite/src/components/searchPaletteData.tsdeleted file mode 100644index fc0bfc412f..0000000000--- a/apps/docsite/src/components/searchPaletteData.ts+++ /dev/null@@ -1,128 +0,0 @@-// Copyright (c) Meta Platforms, Inc. and affiliates.--import type {SearchableItem} from '@astryxdesign/core/Typeahead';-import type {ComponentEntry} from '../generated/componentRegistry';-import type {PackageMeta} from '../generated/packageRegistry';-import type {DocTopic} from '../generated/docsRegistry';-import type {TemplateMetadataEntry} from '../generated/templateMetadataRegistry';-import {flattenComponentSidebarEntries} from './componentSidebarData';--export interface SearchItemAuxiliaryData {- group: string;- keywords: string[];- isReady: boolean;-}--export interface SearchItem extends SearchableItem<SearchItemAuxiliaryData> {- id: string;- label: string;- auxiliaryData: SearchItemAuxiliaryData;-}--interface SearchPaletteDataInput {- components: Record<string, ComponentEntry[]>;- packages: PackageMeta[];- docTopics: DocTopic[];- templates: TemplateMetadataEntry[];-}--function uniqueKeywords(keywords: Array<string | null | undefined>): string[] {- return [...new Set(keywords.filter((kw): kw is string => Boolean(kw)))];-}--function splitWords(value: string): string {- return value.replace(/([a-z0-9])([A-Z])/g, '$1 $2').replace(/[_-]+/g, ' ');-}--export function getSearchItemKeywords(item: SearchItem): string[] {- return [- item.auxiliaryData.group,- splitWords(item.label),- ...item.auxiliaryData.keywords.flatMap(keyword => [- keyword,- splitWords(keyword),- ]),- ];-}--export function buildSearchPaletteItems({- components,- packages,- docTopics,- templates,-}: SearchPaletteDataInput): SearchItem[] {- const items: SearchItem[] = [];- const componentLookup = new Map<string, ComponentEntry>();-- for (const entries of Object.values(components)) {- for (const comp of entries) {- componentLookup.set(comp.name, comp);- }- }-- for (const entry of flattenComponentSidebarEntries()) {- const comp = componentLookup.get(entry.name);- items.push({- id: entry.href,- label: entry.displayName,- auxiliaryData: {- group: entry.isReady ? 'Component' : 'Canary component',- isReady: entry.isReady,- keywords: uniqueKeywords([- entry.name,- entry.displayName,- entry.packageName,- entry.isReady ? null : 'canary',- comp?.moduleName,- ...(comp?.keywords ?? []),- ]),- },- });- }-- for (const pkg of packages) {- const isTheme = pkg.name.includes('theme-');- // All themes share the single /themes surface — the per-theme- // dynamic route was removed in favor of state-driven selection.- // Search results for theme packages all land on /themes with- // Neutral as the default seed; users browse to the specific- // theme they want via the sidebar picker.- items.push({- id: isTheme- ? '/themes'- : `/docs/${pkg.name.replace('@astryxdesign/', '')}`,- label: pkg.displayName,- auxiliaryData: {- group: pkg.canaryOnly ? 'Canary package' : 'Package',- isReady: !pkg.canaryOnly,- keywords: uniqueKeywords([pkg.name, pkg.displayName]),- },- });- }-- for (const doc of docTopics) {- items.push({- id: `/docs/${doc.topic}`,- label: doc.title,- auxiliaryData: {- group: doc.category === 'guide' ? 'Guide' : 'Foundations',- isReady: true,- keywords: uniqueKeywords([doc.topic, doc.title, doc.category]),- },- });- }-- for (const tmpl of templates) {- items.push({- id: `/templates/${tmpl.slug}`,- label: tmpl.name,- auxiliaryData: {- group: 'Template',- isReady: true,- keywords: uniqueKeywords([tmpl.slug, tmpl.name, tmpl.category]),- },- });- }-- return items;-}diff --git a/apps/docsite/src/lib/cliSearchSource.ts b/apps/docsite/src/lib/cliSearchSource.tsnew file mode 100644index 0000000000..92c00bed14--- /dev/null+++ b/apps/docsite/src/lib/cliSearchSource.ts@@ -0,0 +1,154 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++/**+ * @file The search panel's source: each query goes to the site's search API+ * (app/api/search/route.ts), which runs `astryx search`, and its results come+ * back in the CLI's order.+ * @position Consumed by SearchPalette.tsx.+ *+ * Items carry no `group`, since CommandPalette orders grouped items by group+ * and the CLI's order is the answer. Each place on the site is listed once.+ */++import type {SearchSource, SearchableItem} from '@astryxdesign/core/Typeahead';+import type {SiteSearchResult} from './cliSearchTypes';++export interface CliSearchItem extends SearchableItem<SiteSearchResult> {+ id: string;+ label: string;+ auxiliaryData: SiteSearchResult;+}++/**+ * What a selected result opens, as the site's registries name it: the page's+ * type and its identifier (component name, template slug, doc topic).+ */+export function searchTarget(href: string): {item: string; type: string} {+ const [pathname] = href.split('#');+ const [, area = '', slug = ''] = pathname.split('/');+ const type =+ area === 'components'+ ? 'component'+ : area === 'templates'+ ? 'template'+ : area === 'themes'+ ? 'theme'+ : area === 'docs'+ ? 'doc'+ : 'page';+ return {item: slug || area || 'home', type};+}++/** The kind a result is, as the panel labels it. */+export function resultKind(result: SiteSearchResult): string {+ switch (result.domain) {+ case 'component':+ return 'Component';+ case 'hook':+ return 'Hook';+ case 'doc':+ return 'Docs';+ case 'template':+ return result.kind === 'block' ? 'Block' : 'Template';+ case 'theme':+ return 'Theme';+ default:+ return result.domain;+ }+}++/** The panel item for one result, in the order the CLI gave it. */+export function toSearchItem(+ result: SiteSearchResult,+ position: number,+): CliSearchItem {+ const label =+ result.domain === 'doc'+ ? (result.siteTitle ?? result.title ?? result.name)+ : (result.displayName ?? result.name);+ return {+ // Two results can open the same page (sections, blocks), so the id is+ // the position, never the link.+ id: `${position}:${result.domain}:${result.name}${result.section ? `#${result.section}` : ''}`,+ label,+ auxiliaryData: result,+ };+}++/** How long typing must pause before a query is sent. */+const DEBOUNCE_MS = 120;++/**+ * A SearchSource that answers with `astryx search`, through the site's API.+ * @param fetchSearch - Fetches one query's response; the site passes `fetch`.+ */+export function createCliSearchSource(+ fetchSearch: (url: string, init: RequestInit) => Promise<Response> = (+ url,+ init,+ ) => fetch(url, init),+): SearchSource<CliSearchItem> & {+ item(id: string): CliSearchItem | undefined;+} {+ // The items of the newest answer, by id, for the panel's selection.+ let shown = new Map<string, CliSearchItem>();+ let inFlight: AbortController | null = null;++ return {+ bootstrap() {+ return [];+ },+ async search(query) {+ if (query.trim() === '') {+ return [];+ }+ inFlight?.abort();+ const controller = new AbortController();+ inFlight = controller;+ try {+ await new Promise((resolve, reject) => {+ const timer = setTimeout(resolve, DEBOUNCE_MS);+ controller.signal.addEventListener('abort', () => {+ clearTimeout(timer);+ reject(controller.signal.reason);+ });+ });+ const response = await fetchSearch(+ `/api/search?q=${encodeURIComponent(query)}`,+ {signal: controller.signal},+ );+ if (!response.ok) {+ throw new Error(`search: HTTP ${response.status}`);+ }+ const body = (await response.json()) as {+ data: {results: SiteSearchResult[]};+ };+ // Two results can open the same place on the site (a topic and the+ // page that shows it): the panel lists each place once, at its+ // first result, keeping the CLI's order.+ const opened = new Set<string>();+ const items = body.data.results+ .filter(result => {+ if (opened.has(result.href)) return false;+ opened.add(result.href);+ return true;+ })+ .map(toSearchItem);+ shown = new Map(items.map(item => [item.id, item]));+ return items;+ } catch (error) {+ if (!controller.signal.aborted) {+ console.error(error);+ }+ return [];+ }+ },+ item(id) {+ return shown.get(id);+ },+ cancel() {+ inFlight?.abort();+ inFlight = null;+ },+ };+}diff --git a/apps/docsite/src/lib/cliSearchTypes.ts b/apps/docsite/src/lib/cliSearchTypes.tsnew file mode 100644index 0000000000..e2c42f9e74--- /dev/null+++ b/apps/docsite/src/lib/cliSearchTypes.ts@@ -0,0 +1,10 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++import type {SearchResultEntry} from '@astryxdesign/cli/api';++/** One `astryx search` result, with the site path it opens and, for a doc,+ * the title the site shows for it. */+export type SiteSearchResult = SearchResultEntry & {+ href: string;+ siteTitle?: string;+};diff --git a/apps/docsite/src/lib/searchLinks.mjs b/apps/docsite/src/lib/searchLinks.mjsnew file mode 100644index 0000000000..43a14f535f--- /dev/null+++ b/apps/docsite/src/lib/searchLinks.mjs@@ -0,0 +1,236 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++/**+ * @file Where a search result opens on the site.+ * @input A result of the CLI's search (`search()` from `@astryxdesign/cli/api`)+ * and the site's link tables, built with the site by searchLinkTables().+ * @output The site path the result opens: a component, template, theme, or+ * doc page, with the anchor of a doc section.+ * @position Shared by scripts/generate-data.mjs (builds the tables) and the+ * site's search API (reads them). Plain JS so both can import it.+ *+ * The CLI answers with docs-tree routes and section keys, but the site shows+ * each root namespace as one page with anchors, folds some topics into+ * another page, and redirects old slugs (scripts/docs-pages.mjs). So a doc+ * result opens through the pages and redirects the site generated, never by+ * building `/docs/<route>`.+ */++/**+ * @typedef {object} SearchLinkTables+ * @property {string[]} pages - Every doc page slug.+ * @property {Record<string, string>} redirects - Slug -> where its text is shown.+ * @property {Record<string, string>} anchors - `<guide slug>#<section key>`+ * (or `<page>#<section key>`) -> the path of that section, with its anchor.+ * @property {string[]} components - Component and hook names with a page.+ * @property {string[]} templates - Page template slugs with a page.+ * @property {Record<string, string>} blocks - Block name -> the page that shows it.+ * @property {Record<string, string>} titles - A doc page's path, or a+ * section's path with its anchor, -> the title the site shows for it.+ */++/**+ * The anchor ids of a page's sections, as the page's outline builds them.+ * @callback SectionAnchors+ * @param {Array<{title: string, content?: unknown[]}>} sections+ * @returns {string[]}+ */++/**+ * The tables a result's link is read from.+ * @param {object} site+ * @param {Array<{topic: string, title?: string, sections?: Array<{id?: string, title: string}>}>} site.docTopics+ * @param {Record<string, string>} site.docRedirects+ * @param {string[]} site.components+ * @param {string[]} site.templates+ * @param {Array<{name: string, dirName: string, exampleFor: string | null}>} site.blocks+ * @param {string[]} site.packagePages - Slugs of package pages (`cli` for+ * @astryxdesign/cli), which /docs/<slug> also serves.+ * @param {SectionAnchors} site.sectionAnchors+ * @returns {SearchLinkTables}+ */+export function searchLinkTables(site) {+ /** @type {Record<string, string>} */+ const anchors = {};+ /** @type {Record<string, string>} */+ const titles = {};+ // A namespace page (and a merged page) holds the sections of several+ // guides, and a section key is unique only within its guide. Each guide's+ // slug redirects to its first section, so the redirects give each guide's+ // range of sections on the page: a section is keyed by the guide that owns+ // it, `<guide slug>#<section key>`, the way search names it.+ /** @type {Map<string, Array<[number, string]>>} page -> [first section index, guide slug] */+ const starts = new Map();+ const pageAnchors = new Map(+ site.docTopics.map(page => [+ page.topic,+ site.sectionAnchors(/** @type {any} */ (page.sections ?? [])),+ ]),+ );+ for (const [slug, target] of Object.entries(site.docRedirects)) {+ const match = /^\/docs\/([^#]+)#(.+)$/.exec(target);+ if (!match) continue;+ const index = pageAnchors.get(match[1])?.indexOf(match[2]) ?? -1;+ if (index < 0) continue;+ if (!starts.has(match[1])) starts.set(match[1], []);+ starts.get(match[1])?.push([index, slug]);+ }+ for (const page of site.docTopics) {+ const ids = pageAnchors.get(page.topic) ?? [];+ const guides = (starts.get(page.topic) ?? []).sort((a, b) => a[0] - b[0]);+ titles[`/docs/${page.topic}`] = page.title ?? page.topic;+ (page.sections ?? []).forEach((section, i) => {+ titles[`/docs/${page.topic}#${ids[i]}`] =+ `${page.title ?? page.topic} › ${section.title}`;+ if (!section.id) return;+ // The guides whose range holds this section: the latest start at or+ // before it (two slugs can share a start: a namespace with no text of+ // its own and its first guide).+ const at = guides.filter(([start]) => start <= i);+ const owner = at.length ? at[at.length - 1][0] : -1;+ const keys = [+ `${page.topic}#${section.id}`,+ ...at+ .filter(([start]) => start === owner)+ .map(([, slug]) => `${slug}#${section.id}`),+ ];+ for (const key of keys) {+ if (!Object.hasOwn(anchors, key))+ anchors[key] = `/docs/${page.topic}#${ids[i]}`;+ }+ });+ }+ const components = new Set(site.components);+ const templates = new Set(site.templates);+ /** @type {Record<string, string>} */+ const blocks = {};+ for (const block of site.blocks) {+ const owner = block.exampleFor;+ const href =+ owner && components.has(owner)+ ? `/components/${owner}`+ : owner && templates.has(owner)+ ? `/templates/${owner}`+ : null;+ // Search names a block by its file name, which a Core block's dirName is.+ if (href)+ for (const name of [block.dirName, block.name]) blocks[name] ??= href;+ }+ return {+ pages: [+ ...new Set([+ ...site.docTopics.map(page => page.topic),+ ...site.packagePages,+ ]),+ ].sort(),+ redirects: site.docRedirects,+ anchors,+ components: [...components].sort(),+ templates: [...templates].sort(),+ blocks,+ titles,+ };+}++/** @type {WeakMap<SearchLinkTables, {pages: Set<string>, components: Set<string>, templates: Set<string>}>} */+const sets = new WeakMap();++/** @param {SearchLinkTables} tables */+function setsOf(tables) {+ let hit = sets.get(tables);+ if (!hit) {+ hit = {+ pages: new Set(tables.pages),+ components: new Set(tables.components),+ templates: new Set(tables.templates),+ };+ sets.set(tables, hit);+ }+ return hit;+}++/**+ * The page a docs-tree route or topic opens: its own page, the page a+ * redirect shows it on, else the nearest route above it that has one.+ * @param {string} route+ * @param {SearchLinkTables} tables+ * @returns {string}+ */+function docPage(route, tables) {+ const {pages} = setsOf(tables);+ for (let at = route; at; at = at.slice(0, Math.max(0, at.lastIndexOf('/')))) {+ const slug = at.replaceAll('/', '-');+ if (pages.has(slug)) return `/docs/${slug}`;+ if (Object.hasOwn(tables.redirects, slug)) return tables.redirects[slug];+ }+ return '/docs';+}++/**+ * The site path a search result opens.+ * @param {{domain: string, name: string, package?: string, section?: string, kind?: string}} result+ * @param {SearchLinkTables} tables+ * @returns {string}+ */+export function searchResultHref(result, tables) {+ const {components, templates} = setsOf(tables);+ switch (result.domain) {+ case 'component':+ case 'hook':+ return components.has(result.name)+ ? `/components/${result.name}`+ : '/components';+ case 'template':+ if (result.kind === 'block') {+ // A Core block's page is keyed by its name; an integration's by+ // `<package>-<name>`, as the site names its folder.+ for (const key of [+ result.name,+ `${result.package ?? ''}-${result.name}`.replace(+ /[^a-zA-Z0-9_-]/g,+ '-',+ ),+ ]) {+ if (Object.hasOwn(tables.blocks, key)) return tables.blocks[key];+ }+ return '/templates';+ }+ return templates.has(result.name)+ ? `/templates/${result.name}`+ : '/templates';+ case 'theme':+ return '/themes';+ case 'doc': {+ if (result.section) {+ // The section where its own guide shows it, else on its page.+ const own = `${result.name.replaceAll('/', '-')}#${result.section}`;+ if (Object.hasOwn(tables.anchors, own)) return tables.anchors[own];+ }+ const page = docPage(result.name, tables);+ if (!result.section) return page;+ const slug = page.replace(/^\/docs\/?/, '').replace(/#.*$/, '');+ const key = `${slug}#${result.section}`;+ return Object.hasOwn(tables.anchors, key) ? tables.anchors[key] : page;+ }+ default:+ return '/';+ }+}++/**+ * The title the site shows for a doc result: the title of the page, and of+ * the section, its link opens, as the sidebar and page outline name them.+ * Other results keep the CLI's name.+ * @param {{domain: string, name: string, section?: string, title?: string}} result+ * @param {string} href - searchResultHref of the result.+ * @param {SearchLinkTables} tables+ * @returns {string | undefined}+ */+export function searchResultTitle(result, href, tables) {+ if (result.domain !== 'doc') return undefined;+ // The page, or the page and section, the result's link opens.+ if (Object.hasOwn(tables.titles, href)) return tables.titles[href];+ // A doc with no page of its own (an API or command reference) keeps the+ // CLI's title, without the docs tree's placeholder level for unfiled docs.+ return result.title?.replace(/^Unorganized › /, '');+}diff --git a/docs/specs/AST-033/spec.md b/docs/specs/AST-033/spec.mdindex 72cff51896..2b76792d0d 100644--- a/docs/specs/AST-033/spec.md+++ b/docs/specs/AST-033/spec.md@@ -6,8 +6,8 @@ id: spec:AST-033authority: currentarchive_reason: nullsuperseded_by: null-approved_by: cixzhang-approved_at: 2026-09-29+approved_by: josephfarina+approved_at: 2026-10-21phase: acceptedowners: [cixzhang]affects_architecture: []@@ -38,7 +38,8 @@ affects_consumer_docs: [docsite]"FR19","FR20","FR21",- "DEC-7"+ "DEC-7",+ "DEC-8"]}}@@ -85,13 +86,17 @@ for each bug.readiness state, availability rule, or visibility rule. When no current upstreamowner defines a needed fact, the Docsite reports or routes that authority gaprather than deciding it in view code.-- **FR2 — Projections preserve catalog facts.** Gallery, sidebar, search, direct+- **FR2 — Projections preserve catalog facts.** Gallery, sidebar, directroutes, detail pages, preview, playground handoff, and Docsite API projectionsMUST derive membership and canonical item facts from the generated registries. Asurface MAY define local display order, shorten labels, or derive display-onlygroups from canonical fields with a deterministic fallback. Those presentationchoices MUST NOT change catalog membership or be exported or reused as canonical- taxonomy.+ taxonomy. Site search answers with the CLI's own search: the site's search+ endpoint calls `search()` from the CLI package the site builds with and returns+ its results in the CLI's order, so the site and `astryx search` give one answer.+ The generated registries stay the source for the pages and links those results+ open.- **FR3 — Availability and visibility are separate projections.** Availabilitymeans that a named Docsite operation has the source, loader, route, or handoffrequired to present an admitted item on the current content line. Visibility means@@ -118,7 +123,11 @@ for each bug.docs, and Docsite-authored content remain workspace-backed on both targets wherethe pipeline currently declares that boundary. A projection MUST NOT describeworkspace-backed content as release-pinned merely because the build target is- `latest`.+ `latest`. Site search is workspace-backed on both targets: it runs the CLI the+ site builds with, over the workspace docs and packages that CLI reads, the same+ source as the site's CLI reference pages. On `latest` it leaves out+ integrations without published docs, and a result whose page is not published+ links to the nearest published index page.- **FR6 — Canary status is projected once at the owning level.** A surface SHOULDgroup canary status at the package or category level when children share it,instead of repeating a marker on every item. The install command, search result,@@ -309,7 +318,7 @@ exact source already serving those public surfaces.| Contract | Verification | Representative states | Mutation or failure expectation || --------- | ---------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------- |-| FR1–FR3 | generator/data-extraction tests plus cross-projection inventory | package, component, template, theme; gallery, sidebar, search, direct route, preview, playground | a local map changes membership or a canonical item fact, or availability and visibility collapse into one projection |+| FR1–FR3 | generator/data-extraction tests plus cross-projection inventory; search endpoint parity with `astryx search --json` | package, component, template, theme; gallery, sidebar, search, direct route, preview, playground | a local map changes membership or a canonical item fact, or availability and visibility collapse into one projection || FR4–FR6 | latest/canary generation and projection tests | stable package, canary-only package, ready/unready item, overview-hidden item, invalid integration metadata | latest exposes canary package docs, workspace-backed content is called release-pinned, a second readiness state appears, or projections disagree || FR7–FR9 | navigation-family checks plus real-browser navigation/history tests | direct link, modified click, new tab, deep link, primary selection, secondary tab/filter, canonicalization, Back/Forward | Docsite misclassifies a destination, canonical identity diverges, primary selections replace one another, or secondary state clutters history || FR10–FR12 | selection/transition tests plus real-browser visible-content checks | initial open, reopen, deep link, direct selection, pending previous/next, close, supersede, reject, unmount | header/body/actions disagree, stale content paints without its owning pending state, or obsolete selection work commits after supersession |@@ -331,6 +340,8 @@ creating another catalog.Rejected: page-owned item lists, parallel membership/classification maps, and agenerator inventing product policy absent an upstream owner.+Site search is governed by DEC-8.+### DEC-2 — Browser history follows semantic weight**Reference:** `spec:AST-033/DEC-2`@@ -411,6 +422,20 @@ Rejected: continuing a second stable-app build on `gh-pages`, silently droppingold bookmarks, automatically redirecting every old deep path without recoverychoice, and using the compatibility origin for visual or test evidence.+### DEC-8 — Site search uses the CLI's search++**Reference:** `spec:AST-033/DEC-8`+**Decider:** `josephfarina`, `2026-10-21`++Maintainer decision: site search uses the CLI's search instead of a separate index+derived from the registries, and reads the workspace docs the site builds with on+every target, so each search improvement reaches the live site. One ranking implementation means every search+improvement reaches the site with no copy to keep in sync. A parity test holds the+endpoint equal to `astryx search --json` for the site's project.++Rejected: a site-owned index or ranking, and a browser copy of the CLI's search+data that has to track every CLI release.+## Open questionsNone.diff --git a/packages/cli/api/search/_adapter.mjs b/packages/cli/api/search/_adapter.mjsindex c75aa08d42..30aa50660f 100644--- a/packages/cli/api/search/_adapter.mjs+++ b/packages/cli/api/search/_adapter.mjs@@ -7,7 +7,9 @@*/import {readFileSync} from 'node:fs';+import * as path from 'node:path';import {requireCoreDir} from '../../foundation/fs/paths.mjs';+import {recordReads, unchangedSince} from '../../foundation/fs/read-record.mjs';import {isOutsideProject} from '../../foundation/env/project-scope.mjs';import {coreDirOrThrow} from '../error.mjs';import {CORELESS_DOMAINS} from './_query.mjs';@@ -91,6 +93,43 @@ export async function gatherCandidates(options) {};}+/**+ * @typedef {Awaited<ReturnType<typeof gatherCandidates>>} Gathered+ * @type {Map<string, {reads: Map<string, string>, value: 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). 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 async function gatherCandidatesReused(options) {+ const cwd = path.resolve(options.cwd ?? process.cwd());+ const key = `${cwd}\0${options.type ?? ''}`;+ const hit = gathered.get(key);+ if (hit && unchangedSince(hit.reads)) return hit.value;+ /** @type {Map<string, string>} */+ const seen = new Map();+ const value = recordReads(seen, () => gatherCandidates({...options, cwd}));+ try {+ await value;+ } catch (error) {+ if (gathered.get(key)?.value === value) gathered.delete(key);+ throw error;+ }+ // Each path's state was taken as it was first read, so an edit made while+ // the gather ran shows as a change on the next call.+ gathered.set(key, {reads: seen, value});+ return value;+}+/*** @typedef {{w: number[], mu: number[], sd: number[]}} SearcherWeights* @typedef {object} SearchDatadiff --git a/packages/cli/api/search/_adapter.test.mjs b/packages/cli/api/search/_adapter.test.mjsnew file mode 100644index 0000000000..499b245fdb--- /dev/null+++ b/packages/cli/api/search/_adapter.test.mjs@@ -0,0 +1,173 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++/**+ * @file Tests for search's adapter: a long-running caller reuses the gathered+ * candidates while their inputs are unchanged (gatherCandidatesReused), and+ * gathers again when an input changes or for another folder or `type`.+ *+ * Whether inputs changed is read-record's answer (tested in+ * read-record.test.mjs). Other tests running at the same time change shared+ * folders a gather reads (the temp folder, the repository root), so here the+ * reuse case holds that answer at "unchanged", and every other case only+ * checks that a change forces a new gather, which concurrent changes cannot+ * undo.+ */++import {describe, it, expect, vi} from 'vitest';+import * as fs from 'node:fs';+import * as os from 'node:os';+import * as path from 'node:path';+import * as readRecord from '../../foundation/fs/read-record.mjs';+import {gatherCandidates, gatherCandidatesReused} from './_adapter.mjs';++vi.mock('../../foundation/fs/read-record.mjs', async original => {+ const real = /** @type {typeof readRecord} */ (await original());+ return {...real, unchangedSince: vi.fn(real.unchangedSince)};+});+const unchangedSince = vi.mocked(readRecord.unchangedSince);++const SLOW = 60_000;++/** A folder with only a package.json: a docs search there reads the CLI's docs. */+function scratchProject() {+ const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-gather-reuse-'));+ fs.writeFileSync(path.join(dir, 'package.json'), '{"name":"app"}');+ return dir;+}++describe('gatherCandidatesReused', () => {+ it(+ 'reuses the gathered candidates while the inputs are unchanged',+ async () => {+ const cwd = scratchProject();+ const first = await gatherCandidatesReused({cwd, type: 'doc'});+ unchangedSince.mockReturnValueOnce(true);+ expect(await gatherCandidatesReused({cwd, type: 'doc'})).toBe(first);+ expect(first.all.length).toBeGreaterThan(0);+ // The same candidates a fresh gather finds.+ expect(JSON.parse(JSON.stringify(first))).toEqual(+ JSON.parse(JSON.stringify(await gatherCandidates({cwd, type: 'doc'}))),+ );+ },+ SLOW,+ );++ it(+ 'gathers again when an input file changes',+ async () => {+ const cwd = scratchProject();+ const first = await gatherCandidatesReused({cwd, type: 'doc'});+ const later = new Date(Date.now() + 5_000);+ fs.utimesSync(path.join(cwd, 'package.json'), later, later);+ expect(await gatherCandidatesReused({cwd, type: 'doc'})).not.toBe(first);+ fs.writeFileSync(+ path.join(cwd, 'astryx.config.mjs'),+ 'export default {};\n',+ );+ expect(await gatherCandidatesReused({cwd, type: 'doc'})).not.toBe(first);+ },+ SLOW,+ );++ it(+ 'keeps one entry per folder and type',+ async () => {+ const cwd = scratchProject();+ const docs = await gatherCandidatesReused({cwd, type: 'doc'});+ const themes = await gatherCandidatesReused({cwd, type: 'theme'});+ expect(themes).not.toBe(docs);+ expect(themes.all.every(c => c.domain === 'theme')).toBe(true);+ expect(+ await gatherCandidatesReused({cwd: scratchProject(), type: 'doc'}),+ ).not.toBe(docs);+ },+ SLOW,+ );++ it(+ 'gathers again when a file the gather read changes, in a linked package too',+ async () => {+ // A consumer whose integration is a symlink to a package folder+ // elsewhere, as a workspace package is.+ const dir = fs.mkdtempSync(+ path.join(process.cwd(), '.astryx-gather-reuse-'),+ );+ const pkg = fs.mkdtempSync(+ path.join(os.tmpdir(), 'astryx-linked-widgets-'),+ );+ try {+ fs.writeFileSync(path.join(dir, 'package.json'), '{"name":"consumer"}');+ fs.writeFileSync(+ path.join(dir, 'astryx.config.mjs'),+ "export default { integrations: ['@acme/widgets'] };\n",+ );+ fs.mkdirSync(+ path.join(dir, 'node_modules', '@astryxdesign', 'core', 'src'),+ {+ recursive: true,+ },+ );+ fs.mkdirSync(path.join(pkg, 'components'));+ fs.writeFileSync(+ path.join(pkg, 'package.json'),+ '{"name":"@acme/widgets","version":"1.0.0"}',+ );+ fs.writeFileSync(+ path.join(pkg, 'astryx.integration.mjs'),+ "export default { components: './components' };\n",+ );+ fs.writeFileSync(+ path.join(pkg, 'components', 'FancyGizmo.doc.mjs'),+ `export default {+ type: 'component',+ name: 'FancyGizmo',+ keywords: ['gizmo'],+ usage: {description: 'A fancy part.'},+ props: [],+ };\n`,+ );+ fs.writeFileSync(+ path.join(pkg, 'components', 'FancyGizmo.tsx'),+ 'export function FancyGizmo() { return null; }\n',+ );+ fs.mkdirSync(path.join(dir, 'node_modules', '@acme'));+ fs.symlinkSync(+ pkg,+ path.join(dir, 'node_modules', '@acme', 'widgets'),+ 'dir',+ );+ const options = {cwd: dir, type: 'component'};+ const first = await gatherCandidatesReused(options);+ expect(first.all.map(c => c.name)).toContain('FancyGizmo');++ // A new component in the linked package: its folder changed.+ fs.writeFileSync(+ path.join(pkg, 'components', 'TinySprocket.doc.mjs'),+ `export default {+ type: 'component',+ name: 'TinySprocket',+ keywords: ['sprocket'],+ usage: {description: 'A small part.'},+ props: [],+ };\n`,+ );+ fs.writeFileSync(+ path.join(pkg, 'components', 'TinySprocket.tsx'),+ 'export function TinySprocket() { return null; }\n',+ );+ const second = await gatherCandidatesReused(options);+ expect(second).not.toBe(first);+ expect(second.all.map(c => c.name)).toContain('TinySprocket');++ // An edited file the gather read: the linked package's manifest.+ const later = new Date(Date.now() + 5_000);+ fs.utimesSync(path.join(pkg, 'package.json'), later, later);+ expect(await gatherCandidatesReused(options)).not.toBe(second);+ } finally {+ fs.rmSync(dir, {recursive: true, force: true});+ fs.rmSync(pkg, {recursive: true, force: true});+ }+ },+ SLOW,+ );+});diff --git a/packages/cli/api/search/search.mjs b/packages/cli/api/search/search.mjsindex 1f57a9db5b..e116468b3d 100644--- a/packages/cli/api/search/search.mjs+++ b/packages/cli/api/search/search.mjs@@ -15,7 +15,11 @@*/import {withListingCache} from '../../foundation/fs/listing-cache.mjs';-import {gatherCandidates, loadSearchData} from './_adapter.mjs';+import {+ gatherCandidates,+ gatherCandidatesReused,+ loadSearchData,+} from './_adapter.mjs';import {rankLexical} from './_lexical.mjs';import {checkSearchArgs} from './_result.mjs';import {runTree} from '../../foundation/route/route.mjs';@@ -56,7 +60,7 @@ export async function search(query, options = {}) {await runTree(SEARCH_TREE,{query, options},- {...(await gatherCandidates(options)), data: loadSearchData()},+ {...(await gatherCandidatesReused(options)), data: loadSearchData()},)),options.cwd ?? process.cwd(),diff --git a/packages/cli/foundation/doc-compiler/doc-loads.test.mjs b/packages/cli/foundation/doc-compiler/doc-loads.test.mjsindex 2c1fb39b79..2b18a26663 100644--- a/packages/cli/foundation/doc-compiler/doc-loads.test.mjs+++ b/packages/cli/foundation/doc-compiler/doc-loads.test.mjs@@ -331,6 +331,10 @@ const RUNNERS = {'require.cache',],},+ 'foundation/fs/read-record.mjs': {+ runs: "nothing; it wraps node:fs's read calls to record the paths an operation reads, and republishes them to ESM imports",+ sites: ['module.syncBuiltinESMExports'],+ },'foundation/fs/paths.mjs': {runs: "Yarn's pnpapi, under Plug'n'Play, to find an installed package",sites: ['require(pnpapi)'],diff --git a/packages/cli/foundation/fs/read-record.mjs b/packages/cli/foundation/fs/read-record.mjsnew file mode 100644index 0000000000..5387ff7874--- /dev/null+++ b/packages/cli/foundation/fs/read-record.mjs@@ -0,0 +1,131 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++/**+ * @file Which files and folders an operation read, so a long-running caller+ * can tell whether its inputs changed since.+ *+ * @input An operation run inside `recordReads(seen, fn)`.+ * @output `seen` gets every file whose content the operation read through fs+ * and every folder it listed or probed, each with its state when first+ * read; `unchangedSince(seen)` says whether all are still in that state.+ * @position Used by search's adapter to reuse a gathered catalog only while+ * it is exact. Outside `recordReads` nothing is recorded and every fs call+ * behaves as before.+ */++import {AsyncLocalStorage} from 'node:async_hooks';+import {createRequire, syncBuiltinESMExports} from 'node:module';+import * as path from 'node:path';+import {fileURLToPath} from 'node:url';++/**+ * The paths the running operation touched: every file it read and every+ * folder it listed or probed.+ * @type {AsyncLocalStorage<Map<string, string>>}+ */+const reads = new AsyncLocalStorage();++/** node:fs's module object, whose functions every import of it shares. */+const fs = createRequire(import.meta.url)('node:fs');++/** The fs reads whose path argument is recorded. */+const RECORDED = [+ 'readFileSync',+ 'readdirSync',+ 'statSync',+ 'lstatSync',+ 'existsSync',+ 'realpathSync',+ 'accessSync',+ 'openSync',+];++/** The reads that see a file's content, so the file itself is checked. */+const CONTENT_READS = new Set(['readFileSync', 'openSync']);++let recording = false;++/** fs.statSync as loaded, before installRecorder wraps it. */+const statSyncRaw = fs.statSync;++/**+ * Wrap fs's read calls once so that, inside `reads.run`, each path they are+ * given is added to that run's set. Outside a run they behave exactly as+ * before.+ */+function installRecorder() {+ if (recording) return;+ recording = true;+ for (const name of RECORDED) {+ const original = fs[name];+ if (typeof original !== 'function') continue;+ /**+ * @this {unknown}+ * @param {...any} args+ */+ const wrapped = function (...args) {+ const seen = reads.getStore();+ const target = args[0];+ if (seen && (typeof target === 'string' || target instanceof URL)) {+ const file =+ typeof target === 'string'+ ? path.resolve(target)+ : fileURLToPath(target);+ // A file read is checked itself; a probe or listing is checked by its+ // folder, whose time changes when an entry is added, removed or+ // renamed.+ const checked =+ CONTENT_READS.has(name) || name === 'readdirSync'+ ? file+ : path.dirname(file);+ // Its state is taken when it is first read, before the read, so a+ // change made while the operation runs shows as a change afterwards.+ if (!seen.has(checked)) seen.set(checked, stateOf(checked));+ }+ return original.apply(this, args);+ };+ Object.assign(wrapped, original);+ fs[name] = wrapped;+ }+ // ESM imports of node:fs see the wrapped functions too.+ syncBuiltinESMExports();+}++/**+ * One path's state: its change time and size, or that it is absent.+ * @param {string} file+ * @returns {string}+ */+function stateOf(file) {+ try {+ const stat = statSyncRaw(file);+ return `${stat.mtimeMs}\0${stat.size}`;+ } catch {+ return '-';+ }+}++/**+ * Whether every recorded path is still in the state it had when it was read.+ * @param {Map<string, string>} recorded - From recordReads.+ * @returns {boolean}+ */+export function unchangedSince(recorded) {+ for (const [file, state] of recorded) {+ if (stateOf(file) !== state) return false;+ }+ return true;+}++/**+ * Run `fn`, adding to `seen` each path it reads, with that path's state when+ * it was first read (see the file header).+ * @template T+ * @param {Map<string, string>} seen+ * @param {() => T} fn+ * @returns {T}+ */+export function recordReads(seen, fn) {+ installRecorder();+ return reads.run(seen, fn);+}diff --git a/packages/cli/foundation/fs/read-record.test.mjs b/packages/cli/foundation/fs/read-record.test.mjsnew file mode 100644index 0000000000..67675c7e7c--- /dev/null+++ b/packages/cli/foundation/fs/read-record.test.mjs@@ -0,0 +1,77 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++/**+ * @file Tests for read-record: which paths an operation read, and whether+ * any changed since, including a change made while the operation ran.+ */++import {describe, it, expect} from 'vitest';+import * as fs from 'node:fs';+import * as os from 'node:os';+import * as path from 'node:path';+import {recordReads, unchangedSince} from './read-record.mjs';++function scratch() {+ const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-read-record-'));+ const file = path.join(dir, 'doc.txt');+ fs.writeFileSync(file, 'one');+ return {dir, file};+}++describe('recordReads', () => {+ it('records a read file and a listed folder, and sees them unchanged', () => {+ const {dir, file} = scratch();+ /** @type {Map<string, string>} */+ const seen = new Map();+ recordReads(seen, () => {+ fs.readFileSync(file, 'utf8');+ fs.readdirSync(dir);+ });+ expect([...seen.keys()]).toEqual(expect.arrayContaining([file, dir]));+ expect(unchangedSince(seen)).toBe(true);+ });++ it('sees an edit made after the operation', () => {+ const {file} = scratch();+ /** @type {Map<string, string>} */+ const seen = new Map();+ recordReads(seen, () => fs.readFileSync(file, 'utf8'));+ const later = new Date(Date.now() + 5_000);+ fs.writeFileSync(file, 'two, longer');+ fs.utimesSync(file, later, later);+ expect(unchangedSince(seen)).toBe(false);+ });++ it('sees an edit made while the operation ran, after the file was read', () => {+ const {file} = scratch();+ /** @type {Map<string, string>} */+ const seen = new Map();+ recordReads(seen, () => {+ fs.readFileSync(file, 'utf8');+ const later = new Date(Date.now() + 5_000);+ fs.writeFileSync(file, 'edited mid-run');+ fs.utimesSync(file, later, later);+ });+ expect(unchangedSince(seen)).toBe(false);+ });++ it('sees a file added to a folder it probed', () => {+ const {dir} = scratch();+ /** @type {Map<string, string>} */+ const seen = new Map();+ recordReads(seen, () => fs.existsSync(path.join(dir, 'missing.txt')));+ const later = new Date(Date.now() + 5_000);+ fs.writeFileSync(path.join(dir, 'missing.txt'), 'now here');+ fs.utimesSync(dir, later, later);+ expect(unchangedSince(seen)).toBe(false);+ });++ it('records nothing outside an operation', () => {+ const {file} = scratch();+ /** @type {Map<string, string>} */+ const seen = new Map();+ recordReads(seen, () => {});+ fs.readFileSync(file, 'utf8');+ expect(seen.size).toBe(0);+ });+});