@astryxdesign/cli 0.6.3 → 0.6.4-canary.078fd25

package/foundation/discovery/docs-discovery.test.mjs

@@ -31,7 +31,9 @@ function topic(fields) {
     name: 'deploying',
     title: 'Deploying',
     description: 'How to ship it.',
-    sections: [{title: 'Overview', content: [{type: 'prose', text: 'Ship it.'}]}],
+    sections: [
+      {title: 'Overview', content: [{type: 'prose', text: 'Ship it.'}]},
+    ],
     ...fields,
   };
 }
@@ -72,16 +74,16 @@ describe('discoverBuiltinTopics', () => {
 
 describe('discoverIntegrationDocs', () => {
   it('contributes nothing when no docs root is declared or the root is gone', async () => {
-    expect(await discoverIntegrationDocs({name: '@acme/widgets'})).toEqual({
-      records: [],
-      errors: [],
-    });
+    const nothing = {records: [], errors: [], namespaces: [], guides: []};
+    expect(await discoverIntegrationDocs({name: '@acme/widgets'})).toEqual(
+      nothing,
+    );
     expect(
       await discoverIntegrationDocs({
         name: '@acme/widgets',
         docs: path.join(tmpDir, 'nope'),
       }),
-    ).toEqual({records: [], errors: []});
+    ).toEqual(nothing);
   });
 
   it('reads every topic under the root, with what it declares', async () => {
@@ -97,7 +99,9 @@ describe('discoverIntegrationDocs', () => {
       }),
     );
     expect(errors).toEqual([]);
-    expect(records.map(r => [r.name, r.package, r.replaces, r.extendsTopic])).toEqual([
+    expect(
+      records.map(r => [r.name, r.package, r.replaces, r.extendsTopic]),
+    ).toEqual([
       ['deploying', '@acme/widgets', undefined, undefined],
       ['getting-started', '@acme/widgets', 'getting-started', undefined],
       ['theme-extra', '@acme/widgets', undefined, 'theme'],
@@ -126,7 +130,9 @@ describe('discoverIntegrationDocs', () => {
 
   it('reports a doc that exports nothing, rather than skipping it silently', async () => {
     const {records, errors} = await discoverIntegrationDocs(
-      integration('@acme/empty', {'deploying.doc.mjs': 'export const nope = 1;\n'}),
+      integration('@acme/empty', {
+        'deploying.doc.mjs': 'export const nope = 1;\n',
+      }),
     );
     expect(records).toEqual([]);
     expect(errors).toHaveLength(1);
@@ -153,6 +159,88 @@ describe('discoverIntegrationDocs', () => {
     expect(records).toEqual([]);
     expect(errors[0].message).toContain('declares both');
   });
+
+  it('rejects graph blocks at the legacy topic-reader boundary', async () => {
+    const {records, errors} = await discoverIntegrationDocs(
+      integration('@acme/graph-block', {
+        'deploying.doc.mjs': topic({
+          sections: [
+            {
+              id: 'steps',
+              title: 'Steps',
+              content: [
+                {type: 'collection', source: {slot: 'guides'}},
+              ],
+            },
+          ],
+        }),
+      }),
+    );
+    expect(records).toEqual([]);
+    expect(errors[0].message).toContain('Invalid discriminator value');
+  });
+
+  it('hands namespace docs and placed guides to the docs tree, by provider id', async () => {
+    const found = await discoverIntegrationDocs({
+      ...integration('@acme/namespace', {
+        'guides.doc.mjs': {
+          type: 'namespace',
+          name: 'guides',
+          title: 'Guides',
+          summary: 'Every guide.',
+          slots: {guides: {title: 'Guides', accepts: {kinds: ['generic']}}},
+        },
+        'setup.doc.mjs': topic({
+          name: 'setup',
+          title: 'Set up',
+          placement: {parent: 'namespace:guides', slot: 'guides', order: 1},
+        }),
+        'deploying.doc.mjs': topic(),
+      }),
+      providerId: '@acme/tree-provider',
+    });
+    expect(found.errors).toEqual([]);
+    expect(found.records.map(record => record.name)).toEqual(['deploying']);
+    expect(found.records[0].providerId).toBe('@acme/tree-provider');
+    expect(found.namespaces).toMatchObject([
+      {
+        provider: '@acme/namespace',
+        providerId: '@acme/tree-provider',
+        source: '@acme/namespace/guides.doc.mjs',
+        doc: {name: 'guides'},
+      },
+    ]);
+    expect(found.guides).toMatchObject([
+      {
+        provider: '@acme/namespace',
+        providerId: '@acme/tree-provider',
+        kind: 'generic',
+        name: 'setup',
+        placement: {parent: 'namespace:guides', slot: 'guides', order: 1},
+      },
+    ]);
+  });
+
+  it('names what a namespace doc lacks, and refuses a placed guide that replaces a topic', async () => {
+    const {errors, namespaces, guides} = await discoverIntegrationDocs(
+      integration('@acme/namespace', {
+        'guides.doc.mjs': {type: 'namespace', name: 'guides', title: 'Guides'},
+        'setup.doc.mjs': topic({
+          name: 'setup',
+          replaces: 'getting-started',
+          placement: {parent: 'namespace:guides', slot: 'guides'},
+        }),
+      }),
+    );
+    expect(namespaces).toEqual([]);
+    expect(guides).toEqual([]);
+    expect(errors.map(error => error.message).join('\n')).toMatch(
+      /guides\.doc\.mjs.*slots/,
+    );
+    expect(errors.map(error => error.message).join('\n')).toContain(
+      'is placed in the docs tree and also declares `replaces`',
+    );
+  });
 });
 
 describe('problemsInTopic', () => {
@@ -170,7 +258,11 @@ describe('problemsInTopic', () => {
     // A misspelled required field: the block renders nothing at all.
     expect(
       problemsInTopic(
-        topic({sections: [{title: 'Overview', content: [{type: 'prose', txt: 'oops'}]}]}),
+        topic({
+          sections: [
+            {title: 'Overview', content: [{type: 'prose', txt: 'oops'}]},
+          ],
+        }),
       ),
     ).toEqual([
       'sections[0].content[0].text: required for a prose block',
@@ -180,7 +272,12 @@ describe('problemsInTopic', () => {
     expect(
       problemsInTopic(
         topic({
-          sections: [{title: 'Overview', content: [{type: 'heading', level: 2, text: 'x'}]}],
+          sections: [
+            {
+              title: 'Overview',
+              content: [{type: 'heading', level: 2, text: 'x'}],
+            },
+          ],
         }),
       ),
     ).toContain('sections[0].content[0].level: 2 is not one of 3, 4, 5, 6');
@@ -196,11 +293,67 @@ describe('problemsInTopic', () => {
           ],
         }),
       ),
-    ).toContain('sections[0].content[0].rows[0]: has 1 cells but the table has 2 headers');
+    ).toContain(
+      'sections[0].content[0].rows[0]: has 1 cells but the table has 2 headers',
+    );
+  });
+
+  it('rejects graph metadata at the legacy topic-reader boundary', () => {
+    for (const fields of [
+      {placement: {parent: 'namespace:cli'}},
+      {aliases: ['setup']},
+      {audience: 'internal'},
+    ]) {
+      expect(problemsInTopic(topic(fields)).join('\n')).toContain(
+        'requires the compiled graph reader',
+      );
+    }
+  });
+
+  it('takes a reference block, and checks its projection and presentation', () => {
+    /** @param {any[]} content */
+    const withBlocks = content =>
+      problemsInTopic(topic({sections: [{title: 'Overview', content}]}));
+    expect(
+      withBlocks([
+        {type: 'reference', target: 'schema:integration'},
+        {
+          type: 'reference',
+          target: '@astryxdesign/cli:schema:integration',
+          projection: {fields: ['docs']},
+          presentation: 'compact',
+        },
+      ]),
+    ).toEqual([]);
+    expect(
+      withBlocks([
+        {type: 'reference', target: ''},
+        {type: 'reference', target: 'schema:x', presentation: 'card'},
+        {type: 'reference', target: 'schema:x', projection: {fields: []}},
+        {type: 'reference', target: 'schema:x', projection: {rows: ['a']}},
+        {type: 'reference', target: 'schema:x', projection: ['docs']},
+        {type: 'reference', target: 'schema:x', link: {}},
+      ]),
+    ).toEqual([
+      'sections[0].content[0].target: expected a non-empty string',
+      'sections[0].content[1].presentation: "card" is not one of summary, compact, full',
+      'sections[0].content[2].projection.fields: expected a non-empty array of names',
+      'sections[0].content[3].projection.rows: not a field of a projection',
+      'sections[0].content[4].projection: expected {fields?, sections?}, naming the parts of the doc to include',
+      'sections[0].content[5].link: not a field of a reference block',
+    ]);
+    // Workflow and collection blocks stay in a namespace doc's `blocks`.
+    for (const type of ['workflow', 'collection']) {
+      expect(withBlocks([{type}]).join('\n')).toContain(
+        'requires the compiled graph renderer',
+      );
+    }
   });
 
   it('rejects a name that is not URL-safe', () => {
-    expect(problemsInTopic(topic({name: 'not a topic'})).join('\n')).toContain('URL-safe');
+    expect(problemsInTopic(topic({name: 'not a topic'})).join('\n')).toContain(
+      'URL-safe',
+    );
   });
 });
 
@@ -228,11 +381,23 @@ describe('DocsCatalog', () => {
     expect(catalog.resolve('deploying').package).toBe('@acme/widgets');
   });
 
+  it('treats topic identities case-insensitively without losing display case', () => {
+    const catalog = DocsCatalog.fromBuiltins();
+    expect(catalog.add(record({name: 'Deploying'}))).toBeNull();
+    expect(catalog.resolve('deploying').name).toBe('Deploying');
+    expect(catalog.resolve('DEPLOYING').name).toBe('Deploying');
+
+    const issue = catalog.add(
+      record({name: 'deploying', package: '@acme/duplicate'}),
+    );
+    expect(issue).toMatchObject({code: 'invalid_doc', severity: 'error'});
+  });
+
   it('refuses to shadow an existing topic by name alone', () => {
     const catalog = DocsCatalog.fromBuiltins({tokens: '/cli/tokens.doc.mjs'});
     const issue = catalog.add(record({name: 'tokens'}));
     expect(issue).toMatchObject({code: 'invalid_doc', severity: 'error'});
-    expect(issue.message).toContain("already provided by @astryxdesign/cli");
+    expect(issue.message).toContain('already provided by @astryxdesign/cli');
     expect(issue.message).toContain("replaces: 'tokens'");
     // The built-in topic is untouched.
     expect(catalog.resolve('tokens').package).toBe(BUILTIN_DOCS_PACKAGE);
@@ -244,7 +409,9 @@ describe('DocsCatalog', () => {
       tokens: '/cli/tokens.doc.mjs',
     });
     expect(
-      catalog.add(record({name: 'getting-started', replaces: 'getting-started'})),
+      catalog.add(
+        record({name: 'getting-started', replaces: 'getting-started'}),
+      ),
     ).toBeNull();
     expect(catalog.names()).toEqual(['getting-started', 'tokens']);
     const entry = catalog.resolve('getting-started');
@@ -276,12 +443,16 @@ describe('DocsCatalog', () => {
 
   it('warns, and lets the later package win, when two replace one topic', () => {
     const catalog = DocsCatalog.fromBuiltins({tokens: '/cli/tokens.doc.mjs'});
-    expect(catalog.add(record({name: 'tokens', replaces: 'tokens'}))).toBeNull();
+    expect(
+      catalog.add(record({name: 'tokens', replaces: 'tokens'})),
+    ).toBeNull();
     const issue = catalog.add(
       record({name: 'tokens', package: '@acme/later', replaces: 'tokens'}),
     );
     expect(issue).toMatchObject({code: 'duplicate_doc', severity: 'warning'});
-    expect(issue.message).toContain('@acme/later is configured later, so it wins');
+    expect(issue.message).toContain(
+      '@acme/later is configured later, so it wins',
+    );
     expect(catalog.resolve('tokens').package).toBe('@acme/later');
   });
 
@@ -327,15 +498,210 @@ describe('mergeTopic', () => {
         {title: 'Internal', content: [{type: 'prose', text: 'the meta way'}]},
       ],
     });
-    expect(merged.sections.map(s => s.title)).toEqual(['Install', 'Tokens', 'Internal']);
+    expect(merged.sections.map(s => s.title)).toEqual([
+      'Install',
+      'Tokens',
+      'Internal',
+    ]);
     expect(merged.sections[0].content[0].text).toBe('yarn add');
     expect(merged.sections[1].content[0].text).toBe('use tokens');
     // The base is untouched.
     expect(base.sections[0].content[0].text).toBe('npm i');
   });
 
-  it('takes the title and description only when the overlay states them', () => {
-    expect(mergeTopic(base, {sections: []}).title).toBe('Theme');
-    expect(mergeTopic(base, {title: 'Theming', sections: []}).title).toBe('Theming');
+  it('finds a retitled base section by the key its old title derives', () => {
+    // A base section retitled later keeps its old key as its `id`; an
+    // extension that still names it by the old title replaces it.
+    const merged = mergeTopic(
+      {
+        ...base,
+        sections: [
+          {id: 'quick-start', title: 'Wrap your app in a theme', content: []},
+          {id: 'tokens', title: 'Tokens', content: []},
+        ],
+      },
+      {sections: [{title: 'Quick Start', content: []}]},
+    );
+    expect(merged.sections.map(section => [section.id, section.title])).toEqual(
+      [
+        ['quick-start', 'Quick Start'],
+        ['tokens', 'Tokens'],
+      ],
+    );
+  });
+
+  it('replaces a section by stable ID even when its title changes', () => {
+    const merged = mergeTopic(
+      {
+        ...base,
+        sections: [
+          {id: 'install', title: 'Install', content: []},
+          {id: 'tokens', title: 'Tokens', content: []},
+        ],
+      },
+      {
+        sections: [{id: 'install', title: 'Setup', content: []}],
+      },
+    );
+    expect(merged.sections.map(section => [section.id, section.title])).toEqual(
+      [
+        ['install', 'Setup'],
+        ['tokens', 'Tokens'],
+      ],
+    );
+  });
+
+  it('migrates a legacy section to a stable ID without duplicating it', () => {
+    const merged = mergeTopic(base, {
+      sections: [
+        {
+          id: 'install',
+          title: 'Install',
+          content: [{type: 'prose', text: 'yarn add'}],
+        },
+      ],
+    });
+    expect(
+      merged.sections.map(section => [section.id ?? null, section.title]),
+    ).toEqual([
+      ['install', 'Install'],
+      [null, 'Tokens'],
+    ]);
+    expect(merged.sections[0].content[0].text).toBe('yarn add');
+  });
+
+  it('lets a legacy extension replace a section that has since gained an ID', () => {
+    const merged = mergeTopic(
+      {
+        ...base,
+        sections: [
+          {id: 'setup-steps', title: 'Install', content: []},
+          {title: 'Tokens', content: []},
+        ],
+      },
+      {
+        sections: [
+          {title: 'Install', content: [{type: 'prose', text: 'yarn add'}]},
+        ],
+      },
+    );
+    expect(
+      merged.sections.map(section => [section.id ?? null, section.title]),
+    ).toEqual([
+      ['setup-steps', 'Install'],
+      [null, 'Tokens'],
+    ]);
+    expect(merged.sections[0].content[0].text).toBe('yarn add');
+  });
+
+  it('keeps two different authored IDs distinct under one title', () => {
+    const merged = mergeTopic(
+      {...base, sections: [{id: 'install', title: 'Install', content: []}]},
+      {sections: [{id: 'install-yarn', title: 'Install', content: []}]},
+    );
+    expect(merged.sections.map(section => section.id)).toEqual([
+      'install',
+      'install-yarn',
+    ]);
+  });
+
+  it('keeps the base title and description: an extension never renames a topic', () => {
+    const merged = mergeTopic(base, {
+      title: 'Acme theme notes',
+      description: 'Our additions.',
+      sections: [],
+    });
+    expect(merged.title).toBe('Theme');
+    expect(merged.description).toBe('Theming.');
+  });
+});
+
+describe('problemsInTopic section keys', () => {
+  /** @param {object[]} sections */
+  const doc = sections => ({
+    type: 'generic',
+    name: 'keys',
+    title: 'Keys',
+    description: 'Section keys.',
+    sections: sections.map(s => ({
+      content: [{type: 'prose', text: 'x'}],
+      ...s,
+    })),
+  });
+
+  it('keeps legacy title-only key conflicts readable', () => {
+    expect(
+      problemsInTopic(doc([{title: 'Quick Start'}, {title: 'Quick-start'}])),
+    ).toEqual([]);
+  });
+
+  it('rejects an unsafe id', () => {
+    expect(
+      problemsInTopic(doc([{id: 'Quick Start', title: 'Quick Start'}])),
+    ).toEqual([expect.stringContaining('is not a stable key')]);
+  });
+
+  it('keeps a legacy title that has no derived key readable', () => {
+    expect(problemsInTopic(doc([{title: '亮/暗模式'}]))).toEqual([]);
+    expect(
+      problemsInTopic(doc([{id: 'light-dark', title: '亮/暗模式'}])),
+    ).toEqual([]);
+  });
+});
+
+describe('mergeTopic by section key', () => {
+  const base = {
+    title: 'Theme',
+    sections: [
+      {title: 'Quick Start', content: [{type: 'prose', text: 'base'}]},
+      {title: 'Light/Dark Mode', content: [{type: 'prose', text: 'base'}]},
+    ],
+  };
+  const titles = doc =>
+    doc.sections.map(s => [s.id ?? null, s.title, s.content[0].text]);
+
+  it('replaces the section whose derived key an extension id names', () => {
+    const merged = mergeTopic(base, {
+      sections: [
+        {
+          id: 'quick-start',
+          title: 'Quick Start with Acme',
+          content: [{type: 'prose', text: 'acme'}],
+        },
+      ],
+    });
+    expect(titles(merged)).toEqual([
+      ['quick-start', 'Quick Start with Acme', 'acme'],
+      [null, 'Light/Dark Mode', 'base'],
+    ]);
+  });
+
+  it('keeps a legacy title variant as a separate section', () => {
+    const merged = mergeTopic(base, {
+      sections: [
+        {title: 'Light-Dark Mode', content: [{type: 'prose', text: 'acme'}]},
+      ],
+    });
+    expect(titles(merged)).toEqual([
+      [null, 'Quick Start', 'base'],
+      [null, 'Light/Dark Mode', 'base'],
+      [null, 'Light-Dark Mode', 'acme'],
+    ]);
+  });
+
+  it('prefers the key over a legacy title for an extension with an id', () => {
+    const merged = mergeTopic(base, {
+      sections: [
+        {
+          id: 'light-dark-mode',
+          title: 'Quick Start',
+          content: [{type: 'prose', text: 'acme'}],
+        },
+      ],
+    });
+    expect(titles(merged)).toEqual([
+      [null, 'Quick Start', 'base'],
+      ['light-dark-mode', 'Quick Start', 'acme'],
+    ]);
   });
 });

package/foundation/discovery/docs-output-budget.d.mts

@@ -0,0 +1,28 @@
+// @generated by scripts/sync-api-types.mjs from the JSDoc in foundation/**/*.mjs.
+// DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
+
+/**
+ * A payload's size as `--json` prints it: the envelope data, two-space
+ * indented, in UTF-8 bytes.
+ * @param {unknown} payload
+ * @returns {number}
+ */
+export function docPayloadBytes(payload: unknown): number;
+/**
+ * @param {Omit<import('../../api/docs/docs.type.mjs').DocsIndex, 'links'> | import('../../api/docs/docs.type.mjs').DocsIndex} index
+ * @returns {number}
+ */
+export function docsIndexBytes(index: Omit<import("../../api/docs/docs.type.mjs").DocsIndex, "links"> | import("../../api/docs/docs.type.mjs").DocsIndex): number;
+/**
+ * The sections a single read would return more than `budget` bytes for.
+ * @param {any[]} sections
+ * @param {number} [budget]
+ * @returns {{key: string, title: string, bytes: number}[]}
+ */
+export function oversizedDocSections(sections: any[], budget?: number): {
+    key: string;
+    title: string;
+    bytes: number;
+}[];
+/** The most one index or one section read may return, in bytes. */
+export const DOC_OUTPUT_BUDGET_BYTES: number;

package/foundation/discovery/docs-output-budget.mjs

@@ -0,0 +1,50 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file The most one progressive docs read may return.
+ *
+ * @input Docs payloads: one topic's section index, or one section.
+ * @output Their size in bytes as `--json` prints them, and the sections over
+ *   the budget.
+ * @position Shared by Doctor's docs checks and the authoring self-doc audit, so
+ *   both hold every read to the same limit.
+ */
+
+import {sectionKey} from './docs-section-key.mjs';
+
+/** The most one index or one section read may return, in bytes. */
+export const DOC_OUTPUT_BUDGET_BYTES = 32 * 1024;
+
+/**
+ * A payload's size as `--json` prints it: the envelope data, two-space
+ * indented, in UTF-8 bytes.
+ * @param {unknown} payload
+ * @returns {number}
+ */
+export function docPayloadBytes(payload) {
+  return Buffer.byteLength(JSON.stringify(payload, null, 2), 'utf8');
+}
+
+/**
+ * @param {Omit<import('../../api/docs/docs.type.mjs').DocsIndex, 'links'> | import('../../api/docs/docs.type.mjs').DocsIndex} index
+ * @returns {number}
+ */
+export function docsIndexBytes(index) {
+  return docPayloadBytes({type: 'docs.index', data: index});
+}
+
+/**
+ * The sections a single read would return more than `budget` bytes for.
+ * @param {any[]} sections
+ * @param {number} [budget]
+ * @returns {{key: string, title: string, bytes: number}[]}
+ */
+export function oversizedDocSections(sections, budget = DOC_OUTPUT_BUDGET_BYTES) {
+  return sections
+    .map(section => ({
+      key: sectionKey(section),
+      title: section.title,
+      bytes: docPayloadBytes({type: 'docs.detail.section', data: section}),
+    }))
+    .filter(entry => entry.bytes > budget);
+}