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.mdnew file mode 100644index 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.++@vjeuxdiff --git a/packages/cli/api/docs/_adapter.mjs b/packages/cli/api/docs/_adapter.mjsindex 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.mjsindex 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.mjsindex 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.mjsindex 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 () => {