Skip to content

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

TypeScript

fix(cli): a namespace section read loads the project once, not once per guide below it (#8504)

Christopher Chedeau048476f1c540
diff --git a/.changeset/cli-namespace-section-one-load.md b/.changeset/cli-namespace-section-one-load.md
new file mode 100644
index 0000000000..606a2fbe94
--- /dev/null
+++ b/.changeset/cli-namespace-section-one-load.md
@@ -0,0 +1,7 @@
+---
+'@astryxdesign/cli': patch
+---
+
+[fix] `astryx docs <namespace> <section>` loads the project once instead of once for every guide below the namespace, so on a namespace with many guides, such as `astryx docs authoring <section>`, the read itself takes tens of milliseconds instead of hundreds. The answer is unchanged.
+
+@vjeux
diff --git a/packages/cli/api/docs/_adapter.mjs b/packages/cli/api/docs/_adapter.mjs
index d67f7f2389..c4512093bd 100644
--- a/packages/cli/api/docs/_adapter.mjs
+++ b/packages/cli/api/docs/_adapter.mjs
@@ -1721,14 +1721,19 @@ export async function topicLinks(catalog, entry) {
* decides.
* @param {unknown} topic
* @param {{cwd?: string}} [options]
+ * @param {DocsCatalog} [loaded] internal: a catalog the read already loaded,
+ * so the read and every part of it share one snapshot of the project's docs
+ * (and its memoized lowering) instead of loading the project again for each
+ * part. It is a separate argument, never an option, so no caller of the
+ * public `docs()` can set it
* @returns {Promise<
* | {kind: 'topic', catalog: DocsCatalog, entry: import('../../foundation/discovery/docs-discovery.mjs').DocsTopicEntry}
* | {kind: 'node', catalog: DocsCatalog, tree: import('../../foundation/doc-compiler/tree.mjs').DocsTree, node: import('../../foundation/doc-compiler/tree.mjs').TreeNode}
* | {kind: 'unknown', catalog: DocsCatalog}
* >}
*/
-export async function resolveDocsArgument(topic, {cwd} = {}) {
- const catalog = await loadDocsCatalog(cwd);
+export async function resolveDocsArgument(topic, {cwd} = {}, loaded) {
+ const catalog = loaded ?? (await loadDocsCatalog(cwd));
if (typeof topic !== 'string' || topic === '')
return {kind: 'unknown', catalog};
const tree = await projectTree(catalog);
@@ -1942,13 +1947,14 @@ export function notLoaded(catalog) {
* and lower it for the topic readers.
* @param {unknown} topic
* @param {{lang?: string | null, zh?: boolean, dense?: boolean, cwd?: string}} [options]
+ * @param {DocsCatalog} [loaded] internal, as {@link resolveDocsArgument}
*/
-export async function resolveTopicDocs(topic, options = {}) {
+export async function resolveTopicDocs(topic, options = {}, loaded) {
const {lang = null, zh = false, dense = false, cwd} = options;
const effectiveLang = lang || (dense ? 'dense' : zh ? 'zh' : null);
// A public API caller could pass a non-string topic; it lands on the same
// stable code as an unknown name rather than a raw TypeError.
- const found = await resolveDocsArgument(topic, {cwd});
+ const found = await resolveDocsArgument(topic, {cwd}, loaded);
if (found.kind !== 'topic') {
throw found.kind === 'node'
? new AstryxError(
diff --git a/packages/cli/api/docs/detail/section/section.mjs b/packages/cli/api/docs/detail/section/section.mjs
index acd7fad498..811c805afb 100644
--- a/packages/cli/api/docs/detail/section/section.mjs
+++ b/packages/cli/api/docs/detail/section/section.mjs
@@ -130,7 +130,10 @@ async function sectionResponse({catalog, node, lang, entry}, sections, match) {
* with the section its own section read returns for the query; when that
* section's key (its `id`, else the key its title derives) is the query in
* some guides, those guides answer first. No guide, or several, fail with ERR_UNKNOWN_SECTION, naming
- * the guides to read instead.
+ * the guides to read instead. Every guide is read from `catalog`, the one the
+ * namespace read loaded, so the read loads the project once, not once per
+ * guide below the namespace.
+ * @param {import('../../../../foundation/discovery/docs-discovery.mjs').DocsCatalog} catalog
* @param {import('../../../../foundation/doc-compiler/tree.mjs').DocsTree} tree
* @param {import('../../../../foundation/doc-compiler/tree.mjs').TreeNode} namespace
* @param {string} sectionName
@@ -138,6 +141,7 @@ async function sectionResponse({catalog, node, lang, entry}, sections, match) {
* @returns {Promise<import('../../docs.type.mjs').DocsDetailSectionResponse>}
*/
export async function namespaceSection(
+ catalog,
tree,
namespace,
sectionName,
@@ -148,7 +152,7 @@ export async function namespaceSection(
/** @type {Omit<GuideMatch, 'match'>[]} */
const reads = [];
for (const guide of guides) {
- const resolved = await resolveTopicDocs(guide.route, options);
+ const resolved = await resolveTopicDocs(guide.route, options, catalog);
reads.push({guide, resolved, sections: readerSections(resolved.node)});
}
diff --git a/packages/cli/api/docs/docs.mjs b/packages/cli/api/docs/docs.mjs
index aa3e7f663f..b2b795a039 100644
--- a/packages/cli/api/docs/docs.mjs
+++ b/packages/cli/api/docs/docs.mjs
@@ -155,7 +155,13 @@ async function docsRead(topic, section, options = {}) {
// A namespace answers a section read from the one guide below it that
// has the section (spec:AST-046 FR6). A typed doc is one read.
if (found.node.kind === 'namespace') {
- return namespaceSection(found.tree, found.node, section, options);
+ return namespaceSection(
+ found.catalog,
+ found.tree,
+ found.node,
+ section,
+ options,
+ );
}
throw new AstryxError(
`"${found.node.route}" has no sections. Read it whole: ${formatCliCommand(`docs ${found.node.route}`)}.`,
diff --git a/packages/cli/api/docs/namespace-section.test.mjs b/packages/cli/api/docs/namespace-section.test.mjs
index d5be93a0c3..d513942281 100644
--- a/packages/cli/api/docs/namespace-section.test.mjs
+++ b/packages/cli/api/docs/namespace-section.test.mjs
@@ -9,7 +9,8 @@
import * as fs from 'node:fs';
import * as path from 'node:path';
-import {afterEach, beforeEach, describe, expect, it} from 'vitest';
+import {afterEach, beforeEach, describe, expect, it, vi} from 'vitest';
+import {Project} from '../../foundation/config/project.mjs';
import {docs} from './docs.mjs';
import {oneGuide} from './detail/section/section.mjs';
@@ -97,6 +98,49 @@ afterEach(() => {
});
describe('a section read on a namespace', () => {
+ it(
+ 'ignores a catalog key a caller passes: the read loads its own project',
+ async () => {
+ const reference = await docs('authoring/field-reference', undefined, {
+ index: true,
+ });
+ const key = reference.data.sections[0].id;
+ const expected = await docs('authoring', key);
+ // An undeclared option is not a control (spec:AST-017 FR14).
+ expect(
+ await docs('authoring', key, /** @type {any} */ ({catalog: 'npm'})),
+ ).toEqual(expected);
+ expect(
+ await docs('tokens', undefined, /** @type {any} */ ({catalog: 'npm'})),
+ ).toEqual(await docs('tokens'));
+ },
+ SLOW,
+ );
+
+ it(
+ "loads the project once: every guide below the namespace reads from the read's own catalog",
+ async () => {
+ const reference = await docs('authoring/field-reference', undefined, {
+ index: true,
+ });
+ const key = reference.data.sections[0].id;
+ const load = vi.spyOn(Project, 'load');
+ try {
+ const read = await docs('authoring', key);
+ expect(read).toMatchObject({
+ type: 'docs.detail.section',
+ data: {id: key},
+ });
+ // One load for the read, not one more for each of the dozens of
+ // guides below `authoring`.
+ expect(load).toHaveBeenCalledTimes(1);
+ } finally {
+ load.mockRestore();
+ }
+ },
+ SLOW,
+ );
+
it(
'returns the one guide section, by key and by title, as the guide read does',
async () => {