Skip to content

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

TypeScript

perf(cli): findComponentReadme probes only folders that hold the name (#9904)

Christopher Chedeaubb7702ce0aac
diff --git a/.changeset/cli-readme-folder-index.md b/.changeset/cli-readme-folder-index.md
new file mode 100644
index 0000000000..09a29e0e5c
--- /dev/null
+++ b/.changeset/cli-readme-folder-index.md
@@ -0,0 +1,7 @@
+---
+'@astryxdesign/cli': patch
+---
+
+[perf] `astryx search` and `astryx build` look for a component's doc only in the Core folders whose listing holds its name, not in every folder. A search makes about a quarter of the file checks it made before. Results are unchanged.
+
+@vjeux
diff --git a/packages/cli/foundation/discovery/component-discovery.mjs b/packages/cli/foundation/discovery/component-discovery.mjs
index 70b3d7b887..007431c3ac 100644
--- a/packages/cli/foundation/discovery/component-discovery.mjs
+++ b/packages/cli/foundation/discovery/component-discovery.mjs
@@ -11,6 +11,7 @@ import {DOC_EXPORTS} from '../doc-compiler/read.mjs';
import {
listDir,
listDirEntries,
+ listingCacheActive,
oncePerListing,
pathExists,
withListingCache,
@@ -511,6 +512,42 @@ export function discoverComponents(coreDir) {
return ordered;
}
+/**
+ * The folders of `srcDir`, in listing order, whose own listing holds one of
+ * `names`: the only folders a probe for `<folder>/<name>` can find. Inside an
+ * operation each listing is read once, for every name. Outside one, every
+ * folder is returned, so each probe reads the disk.
+ * @param {string} srcDir
+ * @param {fs.Dirent[]} entries `srcDir`'s listing
+ * @param {string[]} names
+ * @returns {fs.Dirent[]}
+ */
+function foldersHolding(srcDir, entries, names) {
+ const folders = entries.filter(entry => entry.isDirectory());
+ if (!listingCacheActive()) return folders;
+ const byName = oncePerListing(`folder-names\0${srcDir}`, () => {
+ /** @type {Map<string, Set<string>>} */
+ const index = new Map();
+ for (const folder of folders) {
+ let listed;
+ try {
+ listed = listDir(path.join(srcDir, folder.name));
+ } catch {
+ continue;
+ }
+ for (const name of listed) {
+ let holders = index.get(name);
+ if (!holders) index.set(name, (holders = new Set()));
+ holders.add(folder.name);
+ }
+ }
+ return index;
+ });
+ return folders.filter(folder =>
+ names.some(name => byName.get(name)?.has(folder.name)),
+ );
+}
+
/**
* Find the .doc.mjs file for a component.
* For sub-components (e.g. StackItem), returns the parent's .doc.mjs
@@ -532,8 +569,7 @@ export function findComponentReadme(coreDir, name) {
// Nested match: src/*/{name}/{Name}.doc.mjs or src/*/{name}/Astryx{Name}.doc.mjs
const entries = listDirEntries(srcDir);
- for (const entry of entries) {
- if (!entry.isDirectory()) continue;
+ for (const entry of foldersHolding(srcDir, entries, [name])) {
const nested = path.join(srcDir, entry.name, name, exactDoc);
if (existsCaseExact(nested, srcDir)) return nested;
const nestedXds = path.join(srcDir, entry.name, name, xdsDoc);
@@ -541,8 +577,7 @@ export function findComponentReadme(coreDir, name) {
}
// Per-component doc in a parent directory: src/*/{Name}.doc.mjs or src/*/Astryx{Name}.doc.mjs
- for (const entry of entries) {
- if (!entry.isDirectory()) continue;
+ for (const entry of foldersHolding(srcDir, entries, [exactDoc, xdsDoc])) {
const perComp = path.join(srcDir, entry.name, exactDoc);
if (existsCaseExact(perComp, srcDir)) return perComp;
const perCompXds = path.join(srcDir, entry.name, xdsDoc);
diff --git a/packages/cli/foundation/discovery/component-discovery.readme.test.mjs b/packages/cli/foundation/discovery/component-discovery.readme.test.mjs
new file mode 100644
index 0000000000..bd482926e9
--- /dev/null
+++ b/packages/cli/foundation/discovery/component-discovery.readme.test.mjs
@@ -0,0 +1,69 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Verifies that `findComponentReadme` finds the same doc inside an
+ * operation, where it reads each folder's listing once for every name, as
+ * outside one, where every probe reads the disk.
+ *
+ * Runs against the real packages/core source, not mocks.
+ */
+
+import {describe, expect, it} from 'vitest';
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import {fileURLToPath} from 'node:url';
+import {withListingCache} from '../fs/listing-cache.mjs';
+import {
+ discoverComponents,
+ findComponentReadme,
+} from './component-discovery.mjs';
+
+// packages/cli/foundation/discovery/ -> up 4 = repo root (has packages/core).
+const CORE = path.resolve(
+ path.dirname(fileURLToPath(import.meta.url)),
+ '../../../core',
+);
+
+describe('findComponentReadme inside an operation', () => {
+ it('finds the doc it finds outside one, for a sample of Core names', () => {
+ // Every eighth name keeps the probes outside an operation short.
+ const names = Object.values(discoverComponents(CORE))
+ .flat()
+ .sort()
+ .filter((_, index) => index % 8 === 0);
+ const sample = [
+ ...names,
+ ...names.map(name => name.toLowerCase()),
+ ...names.map(name => `XDS${name}`),
+ 'Nope',
+ ];
+ const outside = sample.map(name => findComponentReadme(CORE, name));
+ const inside = withListingCache(() =>
+ sample.map(name => findComponentReadme(CORE, name)),
+ );
+ expect(inside.filter(Boolean).length).toBeGreaterThan(20);
+ expect(inside).toEqual(outside);
+ });
+
+ it('keeps the first folder in listing order when several hold the name', () => {
+ const core = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-readme-order-'));
+ try {
+ for (const folder of ['Alpha', 'Beta', 'Gamma']) {
+ const dir = path.join(core, 'src', folder);
+ fs.mkdirSync(path.join(dir, 'Card'), {recursive: true});
+ fs.writeFileSync(path.join(dir, 'Card', 'Card.doc.mjs'), '');
+ fs.writeFileSync(path.join(dir, 'Tile.doc.mjs'), '');
+ }
+ for (const name of ['Card', 'Tile']) {
+ const outside = findComponentReadme(core, name);
+ expect(outside).not.toBeNull();
+ expect(withListingCache(() => findComponentReadme(core, name))).toBe(
+ outside,
+ );
+ }
+ } finally {
+ fs.rmSync(core, {recursive: true, force: true});
+ }
+ });
+});