@astryxdesign/cli 0.6.3-canary.98a2e4e → 0.6.3-canary.9c4d44d

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

@@ -74,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 () => {
@@ -169,10 +169,7 @@ describe('discoverIntegrationDocs', () => {
               id: 'steps',
               title: 'Steps',
               content: [
-                {
-                  type: 'workflow',
-                  steps: [{title: 'Install', description: 'Run install.'}],
-                },
+                {type: 'collection', source: {slot: 'guides'}},
               ],
             },
           ],
@@ -180,7 +177,69 @@ describe('discoverIntegrationDocs', () => {
       }),
     );
     expect(records).toEqual([]);
-    expect(errors[0].message).toContain('requires the compiled graph renderer');
+    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`',
+    );
   });
 });
 
@@ -251,6 +310,46 @@ describe('problemsInTopic', () => {
     }
   });
 
+  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',
@@ -485,11 +584,14 @@ describe('mergeTopic', () => {
     ]);
   });
 
-  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('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.');
   });
 });
 
@@ -500,30 +602,29 @@ describe('problemsInTopic section keys', () => {
     name: 'keys',
     title: 'Keys',
     description: 'Section keys.',
-    sections: sections.map(s => ({content: [{type: 'prose', text: 'x'}], ...s})),
+    sections: sections.map(s => ({
+      content: [{type: 'prose', text: 'x'}],
+      ...s,
+    })),
   });
 
-  it('rejects two sections that derive the same key', () => {
+  it('keeps legacy title-only key conflicts readable', () => {
     expect(
       problemsInTopic(doc([{title: 'Quick Start'}, {title: 'Quick-start'}])),
-    ).toEqual([
-      expect.stringContaining('"quick-start" is already used by sections[0]'),
-    ]);
+    ).toEqual([]);
   });
 
   it('rejects an unsafe id', () => {
-    expect(problemsInTopic(doc([{id: 'Quick Start', title: 'Quick Start'}]))).toEqual(
-      [expect.stringContaining('is not a stable key')],
-    );
+    expect(
+      problemsInTopic(doc([{id: 'Quick Start', title: 'Quick Start'}])),
+    ).toEqual([expect.stringContaining('is not a stable key')]);
   });
 
-  it('rejects a title no key derives from, unless it has an id', () => {
-    expect(problemsInTopic(doc([{title: '亮/暗模式'}]))).toEqual([
-      expect.stringContaining('Give the section an id'),
-    ]);
-    expect(problemsInTopic(doc([{id: 'light-dark', title: '亮/暗模式'}]))).toEqual(
-      [],
-    );
+  it('keeps a legacy title that has no derived key readable', () => {
+    expect(problemsInTopic(doc([{title: '亮/暗模式'}]))).toEqual([]);
+    expect(
+      problemsInTopic(doc([{id: 'light-dark', title: '亮/暗模式'}])),
+    ).toEqual([]);
   });
 });
 
@@ -535,12 +636,17 @@ describe('mergeTopic by section key', () => {
       {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]);
+  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'}]},
+        {
+          id: 'quick-start',
+          title: 'Quick Start with Acme',
+          content: [{type: 'prose', text: 'acme'}],
+        },
       ],
     });
     expect(titles(merged)).toEqual([
@@ -549,19 +655,28 @@ describe('mergeTopic by section key', () => {
     ]);
   });
 
-  it('replaces the section a title variant derives the same key as', () => {
+  it('keeps a legacy title variant as a separate section', () => {
     const merged = mergeTopic(base, {
-      sections: [{title: 'Light-Dark Mode', content: [{type: 'prose', text: 'acme'}]}],
+      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'}]}],
+      sections: [
+        {
+          id: 'light-dark-mode',
+          title: 'Quick Start',
+          content: [{type: 'prose', text: 'acme'}],
+        },
+      ],
     });
     expect(titles(merged)).toEqual([
       [null, 'Quick Start', 'base'],

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

@@ -9,10 +9,10 @@
  */
 export function docPayloadBytes(payload: unknown): number;
 /**
- * @param {import('../../api/docs/docs.type.mjs').DocsIndex} index
+ * @param {Omit<import('../../api/docs/docs.type.mjs').DocsIndex, 'links'> | import('../../api/docs/docs.type.mjs').DocsIndex} index
  * @returns {number}
  */
-export function docsIndexBytes(index: import("../../api/docs/docs.type.mjs").DocsIndex): 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

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

@@ -26,7 +26,7 @@ export function docPayloadBytes(payload) {
 }
 
 /**
- * @param {import('../../api/docs/docs.type.mjs').DocsIndex} index
+ * @param {Omit<import('../../api/docs/docs.type.mjs').DocsIndex, 'links'> | import('../../api/docs/docs.type.mjs').DocsIndex} index
  * @returns {number}
  */
 export function docsIndexBytes(index) {

package/foundation/discovery/docs-section-key.d.mts

@@ -31,9 +31,24 @@ export function sectionTitleKey(title: unknown): string;
  */
 export function sectionKey(section: any): string;
 /**
- * Problems with the keys of a topic's sections: an authored id that is not a
- * stable key, a title no key derives from, and two sections sharing a key.
- * Keys are never suffixed to make them unique, because readers link to them.
+ * A name as a docs-tree route segment: lowercase words joined by hyphens, so
+ * `integrationPackCheck` and `integration pack` both read naturally.
+ * @param {string} name
+ * @returns {string}
+ */
+export function routeSegment(name: string): string;
+/**
+ * Fatal key problems: only an explicitly authored `id` can make a previously
+ * readable topic invalid. Derived-key collisions and titles with no Latin
+ * letters or digits are handled by {@link withSectionKeys} for 0.6.x
+ * compatibility.
+ * @param {any[]} sections
+ * @returns {string[]}
+ */
+export function sectionKeyErrors(sections: any[]): string[];
+/**
+ * Compatibility notices for section keys. These inputs loaded in 0.6.x, so
+ * readers keep accepting them and assign deterministic fallback keys.
  * @param {any[]} sections
  * @returns {string[]}
  */
@@ -49,13 +64,16 @@ export function withSectionKeys<T extends {
     sections: any[];
 }>(doc: T): T;
 /**
- * Find the section a reader asked for: by key, then by exact title (or the
- * key the query derives), then by a title that contains the query. More than
- * one match is refused rather than guessed.
+ * Find the section a reader asked for. The 0.6.x first-match title-substring
+ * lookup remains first in the authored-title view. In a localized view, an
+ * exact stable key resolves before translated title substrings because those
+ * translations cannot participate in language-stable key allocation. Generated
+ * keys avoid authored-title conflicts, and authored IDs that would shadow an
+ * authored legacy query are rejected.
  * @param {any[]} sections
  * @param {string} query
- * @returns {{section: any | null, candidates: any[]}} `candidates` lists the
- *   matches when the query is ambiguous, and is empty when nothing matches
+ * @returns {{section: any | null, candidates: any[]}} `candidates` lists every
+ *   legacy title match when the query is ambiguous
  */
 export function findDocSection(sections: any[], query: string): {
     section: any | null;
@@ -73,14 +91,14 @@ export function sectionSummary(section: any, max?: number): string;
  * The index a topic-only read returns: what the topic is, and one entry per
  * section with the key to read it by.
  * @param {{name: string, title: string, description: string, sections: any[]}} doc
- * @returns {import('../../api/docs/docs.type.mjs').DocsIndex}
+ * @returns {Omit<import('../../api/docs/docs.type.mjs').DocsIndex, 'links'>}
  */
 export function buildDocsIndexData(doc: {
     name: string;
     title: string;
     description: string;
     sections: any[];
-}): import("../../api/docs/docs.type.mjs").DocsIndex;
+}): Omit<import("../../api/docs/docs.type.mjs").DocsIndex, "links">;
 /**
  * @file Stable section keys, section lookup, and the topic index.
  *

package/foundation/discovery/docs-section-key.mjs

@@ -34,7 +34,10 @@ const SOURCE_TITLE = Symbol('astryx.docs.sourceTitle');
  * @returns {T}
  */
 export function withSourceTitle(section, title) {
-  Object.defineProperty(section, SOURCE_TITLE, {value: title, configurable: true});
+  Object.defineProperty(section, SOURCE_TITLE, {
+    value: title,
+    configurable: true,
+  });
   return section;
 }
 
@@ -77,9 +80,77 @@ export function sectionKey(section) {
 }
 
 /**
- * Problems with the keys of a topic's sections: an authored id that is not a
- * stable key, a title no key derives from, and two sections sharing a key.
- * Keys are never suffixed to make them unique, because readers link to them.
+ * The first section the 0.6.x title-substring lookup would return for a query.
+ * @param {any[]} sections
+ * @param {string} query
+ * @returns {number}
+ */
+function legacyTitleMatchIndex(sections, query) {
+  const lower = query.toLowerCase();
+  return sections.findIndex(section => {
+    const title = sourceTitle(section);
+    return typeof title === 'string' && title.toLowerCase().includes(lower);
+  });
+}
+
+/**
+ * A name as a docs-tree route segment: lowercase words joined by hyphens, so
+ * `integrationPackCheck` and `integration pack` both read naturally.
+ * @param {string} name
+ * @returns {string}
+ */
+export function routeSegment(name) {
+  return String(name)
+    .replace(/([a-z0-9])([A-Z])/g, '$1-$2')
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '');
+}
+
+/**
+ * Fatal key problems: only an explicitly authored `id` can make a previously
+ * readable topic invalid. Derived-key collisions and titles with no Latin
+ * letters or digits are handled by {@link withSectionKeys} for 0.6.x
+ * compatibility.
+ * @param {any[]} sections
+ * @returns {string[]}
+ */
+export function sectionKeyErrors(sections) {
+  /** @type {string[]} */
+  const problems = [];
+  /** @type {Map<string, number>} */
+  const seen = new Map();
+  sections.forEach((section, s) => {
+    if (section?.id == null) return;
+    const at = `sections[${s}]`;
+    if (typeof section.id !== 'string' || !SECTION_KEY_RE.test(section.id)) {
+      problems.push(
+        `${at}.id: ${JSON.stringify(section.id)} is not a stable key. Use lowercase letters and digits joined by single hyphens.`,
+      );
+      return;
+    }
+    const first = seen.get(section.id);
+    if (first != null) {
+      problems.push(
+        `${at}: the key "${section.id}" is already used by sections[${first}]. Give one of them a distinct id.`,
+      );
+      return;
+    }
+    const legacyOwner = legacyTitleMatchIndex(sections, section.id);
+    if (legacyOwner !== -1 && legacyOwner !== s) {
+      problems.push(
+        `${at}.id: the key "${section.id}" is already a legacy title query for sections[${legacyOwner}]. Choose an id that resolves to this section.`,
+      );
+      return;
+    }
+    seen.set(section.id, s);
+  });
+  return problems;
+}
+
+/**
+ * Compatibility notices for section keys. These inputs loaded in 0.6.x, so
+ * readers keep accepting them and assign deterministic fallback keys.
  * @param {any[]} sections
  * @returns {string[]}
  */
@@ -90,7 +161,6 @@ export function sectionKeyProblems(sections) {
   const seen = new Map();
   sections.forEach((section, s) => {
     const at = `sections[${s}]`;
-    // A missing title is reported where titles are checked; no key to judge.
     if (
       section?.id == null &&
       (typeof section?.title !== 'string' || section.title === '')
@@ -109,14 +179,14 @@ export function sectionKeyProblems(sections) {
     const key = sectionKey(section);
     if (key === '') {
       problems.push(
-        `${at}: no key derives from the title ${JSON.stringify(section?.title)}. Give the section an id.`,
+        `${at}: no key derives from the title ${JSON.stringify(section?.title)}. A deterministic section-N compatibility key is used; add an explicit id.`,
       );
       return;
     }
     const first = seen.get(key);
     if (first != null) {
       problems.push(
-        `${at}: the key "${key}" is already used by sections[${first}]. Give one of them a distinct id or title.`,
+        `${at}: the key "${key}" is already used by sections[${first}]. A suffixed compatibility key is used for title-derived collisions; give one of them a distinct id or title.`,
       );
       return;
     }
@@ -133,48 +203,79 @@ export function sectionKeyProblems(sections) {
  * @returns {T}
  */
 export function withSectionKeys(doc) {
+  const reserved = new Set(
+    doc.sections
+      .map(section => section?.id)
+      .filter(id => typeof id === 'string' && SECTION_KEY_RE.test(id)),
+  );
+  const used = new Set();
   return {
     ...doc,
-    sections: doc.sections.map(section =>
-      section.id != null
-        ? section
-        : withSourceTitle(
-            {...section, id: sectionKey(section)},
-            sourceTitle(section),
-          ),
-    ),
+    sections: doc.sections.map((section, index) => {
+      if (section.id != null) {
+        used.add(section.id);
+        return section;
+      }
+      const base =
+        sectionTitleKey(sourceTitle(section)) || `section-${index + 1}`;
+      let key = base;
+      let suffix = 2;
+      while (
+        reserved.has(key) ||
+        used.has(key) ||
+        (legacyTitleMatchIndex(doc.sections, key) !== -1 &&
+          legacyTitleMatchIndex(doc.sections, key) !== index)
+      ) {
+        key = `${base}-${suffix}`;
+        suffix += 1;
+      }
+      used.add(key);
+      return withSourceTitle({...section, id: key}, sourceTitle(section));
+    }),
   };
 }
 
 /**
- * Find the section a reader asked for: by key, then by exact title (or the
- * key the query derives), then by a title that contains the query. More than
- * one match is refused rather than guessed.
+ * Find the section a reader asked for. The 0.6.x first-match title-substring
+ * lookup remains first in the authored-title view. In a localized view, an
+ * exact stable key resolves before translated title substrings because those
+ * translations cannot participate in language-stable key allocation. Generated
+ * keys avoid authored-title conflicts, and authored IDs that would shadow an
+ * authored legacy query are rejected.
  * @param {any[]} sections
  * @param {string} query
- * @returns {{section: any | null, candidates: any[]}} `candidates` lists the
- *   matches when the query is ambiguous, and is empty when nothing matches
+ * @returns {{section: any | null, candidates: any[]}} `candidates` lists every
+ *   legacy title match when the query is ambiguous
  */
 export function findDocSection(sections, query) {
   const wanted = query.trim();
   const byKey = sections.find(section => sectionKey(section) === wanted);
-  if (byKey) return {section: byKey, candidates: []};
+  const hasLocalizedTitles = sections.some(
+    section => sourceTitle(section) !== section.title,
+  );
+  if (byKey && hasLocalizedTitles) {
+    return {section: byKey, candidates: []};
+  }
 
   const lower = wanted.toLowerCase();
-  const derived = sectionTitleKey(wanted);
-  const exact = sections.filter(
-    section =>
-      section.title.toLowerCase() === lower ||
-      (derived !== '' && sectionTitleKey(sourceTitle(section)) === derived),
+  const legacy = sections.filter(section =>
+    section.title.toLowerCase().includes(lower),
   );
-  if (exact.length === 1) return {section: exact[0], candidates: []};
-  if (exact.length > 1) return {section: null, candidates: exact};
+  if (legacy.length > 0) {
+    return {section: legacy[0], candidates: legacy.length > 1 ? legacy : []};
+  }
 
-  const partial = sections.filter(section =>
-    section.title.toLowerCase().includes(lower),
+  const byFallbackKey = sections.find(
+    section => sectionKey(section) === wanted,
+  );
+  if (byFallbackKey) return {section: byFallbackKey, candidates: []};
+
+  const derived = sectionTitleKey(wanted);
+  const byDerivedKey = sections.find(
+    section =>
+      derived !== '' && sectionTitleKey(sourceTitle(section)) === derived,
   );
-  if (partial.length === 1) return {section: partial[0], candidates: []};
-  return {section: null, candidates: partial};
+  return {section: byDerivedKey ?? null, candidates: []};
 }
 
 /**
@@ -205,7 +306,7 @@ export function sectionSummary(section, max = SECTION_SUMMARY_MAX) {
  * The index a topic-only read returns: what the topic is, and one entry per
  * section with the key to read it by.
  * @param {{name: string, title: string, description: string, sections: any[]}} doc
- * @returns {import('../../api/docs/docs.type.mjs').DocsIndex}
+ * @returns {Omit<import('../../api/docs/docs.type.mjs').DocsIndex, 'links'>}
  */
 export function buildDocsIndexData(doc) {
   return {