Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

perf(cli): the component matcher finds each doc once per operation (#10277)

Christopher Chedeaud34fe915af2f
diff --git a/.changeset/cli-matcher-docs-once.md b/.changeset/cli-matcher-docs-once.md
new file mode 100644
index 0000000000..cc54816d90
--- /dev/null
+++ b/.changeset/cli-matcher-docs-once.md
@@ -0,0 +1,7 @@
+---
+'@astryxdesign/cli': patch
+---
+
+[perf] Within one operation, component discovery reads each component doc once, and the component matcher looks for each component's doc once, not once for each name they resolve. Resolving 30 names that only the matcher finds, such as names in another case, makes 14,794 file-system calls instead of 305,108. Results are unchanged.
+
+@vjeux
diff --git a/packages/cli/foundation/discovery/component-discovery.mjs b/packages/cli/foundation/discovery/component-discovery.mjs
index 17fdedda6e..e07abdd662 100644
--- a/packages/cli/foundation/discovery/component-discovery.mjs
+++ b/packages/cli/foundation/discovery/component-discovery.mjs
@@ -381,6 +381,22 @@ export function familyMember(docs, name) {
* @returns {Record<string, string[]>}
*/
export function discoverComponents(coreDir) {
+ // The component matcher calls this for each name it resolves, so one
+ // operation reads the docs once. Each caller gets its own copy to change.
+ const found = oncePerListing(`components\0${coreDir}`, () =>
+ readComponentGroups(coreDir),
+ );
+ return Object.fromEntries(
+ Object.entries(found).map(([key, names]) => [key, [...names]]),
+ );
+}
+
+/**
+ * The component groups under `coreDir`, read from disk.
+ * @param {string} coreDir
+ * @returns {Record<string, string[]>}
+ */
+function readComponentGroups(coreDir) {
const srcDir = path.join(coreDir, 'src');
/** @type {Map<string, string|null>} componentName → group */
const componentGroups = new Map();
diff --git a/packages/cli/foundation/discovery/component-discovery.test.mjs b/packages/cli/foundation/discovery/component-discovery.test.mjs
index 2731310e19..9cc7d9cf06 100644
--- a/packages/cli/foundation/discovery/component-discovery.test.mjs
+++ b/packages/cli/foundation/discovery/component-discovery.test.mjs
@@ -123,6 +123,25 @@ describe('discoverComponents (real core)', () => {
expect(discoverComponents(core)).toEqual({});
});
+ it('reads the docs once per operation and fresh outside one', () => {
+ const core = mkTmp('as-cd-once-');
+ const dir = path.join(core, 'src', 'Foo');
+ fs.mkdirSync(dir, {recursive: true});
+ fs.writeFileSync(path.join(dir, 'XDSFoo.tsx'), 'x');
+ const doc = path.join(dir, 'Foo.doc.mjs');
+ fs.writeFileSync(doc, 'export default {};\n');
+ withListingCache(() => {
+ const first = discoverComponents(core);
+ expect(first).toEqual({Foo: ['Foo']});
+ first.Foo.push('Bar');
+ fs.writeFileSync(doc, "export default {\n group: 'Widgets',\n};\n");
+ // The operation read the doc once, so the edit does not reach it. A
+ // change to one caller's result does not reach the next caller.
+ expect(discoverComponents(core)).toEqual({Foo: ['Foo']});
+ });
+ expect(discoverComponents(core)).toEqual({Widgets: ['Foo']});
+ });
+
it('lists HStack, VStack and Heading, whose docs live in their family folders', () => {
// Each has its own folder and import path; Stack's doc documents HStack and
// VStack as members, and Heading's own doc sits in the Text folder.
diff --git a/packages/cli/foundation/text/string-utils.mjs b/packages/cli/foundation/text/string-utils.mjs
index a17b87366a..9c028bb13a 100644
--- a/packages/cli/foundation/text/string-utils.mjs
+++ b/packages/cli/foundation/text/string-utils.mjs
@@ -58,7 +58,9 @@ export function findClosestComponents(name, components, maxDistance = 3) {
*/
export async function searchComponents(needle, coreDir, components) {
const {readDocView} = await import('../doc-compiler/read.mjs');
- const fs = await import('node:fs');
+ const {listDirEntries, oncePerListing, pathExists} = await import(
+ '../fs/listing-cache.mjs'
+ );
const path = await import('node:path');
const term = needle.toLowerCase();
@@ -111,32 +113,30 @@ export async function searchComponents(needle, coreDir, components) {
}
// --- Pass 2: Keyword + description matching (async, reads doc files) ---
- for (const comp of allNames) {
- const srcDir = path.join(coreDir, 'src');
-
- let docPath = null;
+ const srcDir = path.join(coreDir, 'src');
+ /**
+ * The doc that Pass 2 reads for `comp`, or null.
+ * @param {string} comp
+ * @returns {string | null}
+ */
+ function docPathOf(comp) {
const direct = path.join(srcDir, comp, comp + '.doc.mjs');
- if (fs.existsSync(direct)) {
- docPath = direct;
- }
- if (!docPath) {
- const xdsDirect = path.join(srcDir, comp, 'XDS' + comp + '.doc.mjs');
- if (fs.existsSync(xdsDirect)) {
- docPath = xdsDirect;
- }
+ if (pathExists(direct)) return direct;
+ const xdsDirect = path.join(srcDir, comp, 'XDS' + comp + '.doc.mjs');
+ if (pathExists(xdsDirect)) return xdsDirect;
+ if (!pathExists(srcDir)) return null;
+ for (const entry of listDirEntries(srcDir)) {
+ if (!entry.isDirectory()) continue;
+ const nested = path.join(srcDir, entry.name, comp, comp + '.doc.mjs');
+ if (pathExists(nested)) return nested;
}
- if (!docPath && fs.existsSync(srcDir)) {
- const entries = fs.readdirSync(srcDir, {withFileTypes: true});
- for (const entry of entries) {
- if (!entry.isDirectory()) continue;
- const nested = path.join(srcDir, entry.name, comp, comp + '.doc.mjs');
- if (fs.existsSync(nested)) {
- docPath = nested;
- break;
- }
- }
- }
-
+ return null;
+ }
+ // Each search probes the same paths, so one operation finds each doc once.
+ for (const comp of allNames) {
+ const docPath = oncePerListing(`search-doc\0${srcDir}\0${comp}`, () =>
+ docPathOf(comp),
+ );
if (!docPath) continue;
try {
diff --git a/packages/cli/foundation/text/string-utils.test.mjs b/packages/cli/foundation/text/string-utils.test.mjs
index 7fff27712a..8ecc5ba8d2 100644
--- a/packages/cli/foundation/text/string-utils.test.mjs
+++ b/packages/cli/foundation/text/string-utils.test.mjs
@@ -13,9 +13,15 @@
* sorts by score desc then name asc.
* The doc-file reading (Pass 2) is exercised end-to-end elsewhere; here we use
* a non-existent coreDir so Pass 2 is a no-op and the tests stay pure + fast.
+ * One case writes a doc in a temporary folder: Pass 2 looks for each doc once
+ * per operation.
*/
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
import {describe, it, expect} from 'vitest';
+import {withListingCache} from '../fs/listing-cache.mjs';
import {
findClosestComponents,
searchComponents,
@@ -81,6 +87,31 @@ describe('findClosestComponents', () => {
});
describe('searchComponents', () => {
+ it('looks for each doc once per operation and fresh outside one', async () => {
+ const core = fs.mkdtempSync(path.join(os.tmpdir(), 'as-su-once-'));
+ try {
+ const dir = path.join(core, 'src', 'Card');
+ fs.mkdirSync(dir, {recursive: true});
+ const matchesKeyword = async () =>
+ (await searchComponents('panel', core, {Card: ['Card']})).some(
+ result => result.reason === 'keyword "panel"',
+ );
+ await withListingCache(async () => {
+ expect(await matchesKeyword()).toBe(false);
+ fs.writeFileSync(
+ path.join(dir, 'Card.doc.mjs'),
+ "export const docs = {keywords: ['panel']};\n",
+ );
+ // The operation looked for the doc once, so the new doc does not
+ // reach it.
+ expect(await matchesKeyword()).toBe(false);
+ });
+ expect(await matchesKeyword()).toBe(true);
+ } finally {
+ fs.rmSync(core, {recursive: true, force: true});
+ }
+ });
+
it('scores an exact name match 100', async () => {
const results = await searchComponents('Button', NO_CORE, COMPONENTS);
expect(results[0]).toEqual({