@astryxdesign/cli 0.7.2 → 0.7.3-canary.0bf23bd

package/api/discover/_adapter.test.mjs

@@ -21,6 +21,10 @@ import {
   withDeclaredOfficial,
 } from './_adapter.mjs';
 import {parseDiscoverCatalog} from '../../authoring/discover/parse.mjs';
+import {
+  _resetHostedRun,
+  activateHostedRun,
+} from '../../foundation/runtime/package-root.mjs';
 
 /** No official packages, so a test sees only its own sources after it. */
 const NO_OFFICIAL = {packages: []};
@@ -230,6 +234,44 @@ describe('callSources', () => {
     expect(otherRequest.sources[0].status).toBe('failed');
   });
 
+  it("keeps a host's saved copies per host, so one tool never answers with another's", async () => {
+    let online = true;
+    const source = async () => {
+      if (!online) throw new Error('offline');
+      return catalog('Acme catalog', [pkg('@acme/one')]);
+    };
+    const options = {cacheDir, official: NO_OFFICIAL};
+    try {
+      activateHostedRun({
+        discoverSources: [source],
+        startingRoot: '/tools/acme',
+      });
+      await callSources(undefined, {}, options);
+      online = false;
+      const sameHost = await callSources(undefined, {}, options);
+      expect(sameHost.sources[0]).toMatchObject({
+        name: 'Acme catalog',
+        from: 'the host',
+        status: 'saved',
+      });
+
+      _resetHostedRun();
+      activateHostedRun({
+        discoverSources: [source],
+        startingRoot: '/tools/other',
+      });
+      const otherHost = await callSources(undefined, {}, options);
+      expect(otherHost.sources[0]).toMatchObject({
+        from: 'the host',
+        status: 'failed',
+        error: 'offline',
+      });
+      expect(otherHost.packages).toEqual([]);
+    } finally {
+      _resetHostedRun();
+    }
+  });
+
   it('keeps the saved copy in the cache directory, not in the project', async () => {
     await callSources(
       project({

package/api/docs/_adapter.d.mts

@@ -226,7 +226,7 @@ export function topicUp(entry: import("../../foundation/discovery/docs-discovery
 export function placeLinks(tree: DocsTree, node: TreeNode): import("./docs.type.mjs").DocsLinks;
 /**
  * The moves a topic read offers: from its place in the tree, where a guide
- * sits in its namespace and a flat topic in the Unorganized level.
+ * sits in its namespace and a flat topic in its topic level.
  * @param {DocsCatalog} catalog
  * @param {import('../../foundation/discovery/docs-discovery.mjs').DocsTopicEntry} entry
  * @returns {Promise<import('./docs.type.mjs').DocsLinks>}
@@ -290,7 +290,7 @@ export function holdsOwnName(tree: DocsTree, catalog: DocsCatalog, entry: import
 /**
  * The doc that took a flat topic's route in the docs tree, when it is not
  * that topic (spec:AST-046 FR11): the CLI keeps its routes, such as `cli`
- * and `unorganized`, and a namespace keeps its route over a topic of the same
+ * and `guides`, and a namespace keeps its route over a topic of the same
  * name. Null when the topic owns its route, or the tree has no node there.
  * @param {DocsTree} tree
  * @param {import('../../foundation/discovery/docs-discovery.mjs').DocsTopicEntry} entry

package/api/docs/_adapter.mjs

@@ -52,6 +52,7 @@ import {
   cliDocSection,
 } from '../../foundation/discovery/cli-self-docs.mjs';
 import {
+  AUTHORING_REFERENCE_ROUTE,
   loadAuthoringSelfDocs,
   schemaFieldTable,
   selfDocSection,
@@ -385,7 +386,7 @@ export function projectTree(catalog, {fresh = false} = {}) {
 let cliTreeInputs;
 
 /**
- * Every flat topic in the catalog, as the tree's Unorganized level reads it.
+ * Every flat topic in the catalog, as the tree's topic levels read it.
  * @param {DocsCatalog} catalog
  * @returns {Promise<import('../../foundation/doc-compiler/tree.mjs').TreeTopicInput[]>}
  */
@@ -394,12 +395,13 @@ async function flatTopicInputs(catalog) {
   const topics = [];
   for (const entry of catalog.entries()) {
     const aliases = catalog.aliasesOf(entry);
-    let {title, description} = entry;
-    if (title == null || description == null) {
+    let {title, description, category} = entry;
+    if (title == null || description == null || category === undefined) {
       try {
         const file = await loadTopicFile(entry.path, null);
         title ??= file.doc?.title;
         description ??= file.doc?.description;
+        category ??= file.doc?.category;
       } catch {
         // A topic that does not load is reported where it is read.
       }
@@ -410,6 +412,7 @@ async function flatTopicInputs(catalog) {
       name: entry.name,
       title: title ?? entry.name,
       summary: description ?? '',
+      category: category ?? null,
       source: `${entry.package}:${entry.name}`,
       ...(aliases.length > 0 ? {aliases} : {}),
     });
@@ -419,7 +422,7 @@ async function flatTopicInputs(catalog) {
 
 /**
  * The CLI's tree, each configured integration's namespaces and guides, and
- * every flat topic in the generated Unorganized level.
+ * every flat topic in the generated level for its category.
  * @param {DocsCatalog} catalog
  * @param {boolean} fresh
  * @returns {Promise<DocsTree>}
@@ -509,23 +512,22 @@ function identitiesOf(tree) {
 }
 
 /**
- * The CLI's authoring docs, by kind and name. `astryx docs authoring` reads
- * each as one section keyed by its name, so a link to one opens that section.
- * Loaded once per process, like the CLI's tree files.
+ * The CLI's authoring docs, by kind and name. The field reference under
+ * `astryx docs authoring` reads each as one section keyed by its name, so a
+ * link to one opens that section. Loaded once per process, like the CLI's
+ * tree files.
  * @type {Promise<Map<string, any>> | undefined}
  */
 let authoringDocs;
 
 /**
- * The CLI authoring doc a link names, while `astryx docs authoring` is the
- * CLI's own topic.
- * @param {DocsCatalog} catalog
+ * The CLI authoring doc a link names. The `authoring` namespace is the CLI's
+ * own, so no integration can take its route.
  * @param {string} kind
  * @param {string} name
  * @returns {Promise<any | null>}
  */
-async function authoringDoc(catalog, kind, name) {
-  if (catalog.resolve('authoring')?.package !== CLI_PROVIDER_ID) return null;
+async function authoringDoc(kind, name) {
   authoringDocs ??= loadAuthoringSelfDocs().then(
     ({loaded}) =>
       new Map(loaded.map(({doc}) => [`${doc.type}\u0000${doc.name}`, doc])),
@@ -611,14 +613,14 @@ function docFinderOver(catalog, tree, fromProvider, summaries = true) {
     }
     const authored =
       provider === CLI_PROVIDER_ID
-        ? await authoringDoc(catalog, parsed.kind, parsed.name)
+        ? await authoringDoc(parsed.kind, parsed.name)
         : null;
     if (authored) {
       return {
         link: {
           target,
           id: createDocId(provider, authored.type, authored.name),
-          route: 'authoring',
+          route: AUTHORING_REFERENCE_ROUTE,
           title: authored.displayName ?? authored.name,
           summary: authored.description ?? '',
           command: `astryx docs authoring ${authored.name}`,
@@ -1146,6 +1148,14 @@ function packageCatalog(integration, discovered) {
  * @returns {Promise<Array<{severity: 'warning', message: string}>>}
  */
 export async function packageComponentLinkProblems(integration, discovered) {
+  // A package with no provider id (its manifest's, else its name) links
+  // nothing, as on the read path: its text reads as written, so there is
+  // nothing to report.
+  try {
+    normalizeProviderId(integration.providerId ?? integration.name);
+  } catch {
+    return [];
+  }
   const catalog = packageCatalog(integration, discovered);
   return (await componentLinkProblems(catalog, integration.name)).map(
     message => ({severity: /** @type {const} */ ('warning'), message}),
@@ -1176,11 +1186,15 @@ async function componentLinkProblems(catalog, owner) {
       // The components check reports a doc that does not load.
       continue;
     }
-    const linked = await linkComponentDoc(
-      catalog,
-      componentLinkProvider(record.package, record.providerId),
-      doc,
-    );
+    let provider;
+    try {
+      provider = componentLinkProvider(record.package, record.providerId);
+    } catch {
+      // An owner that is not a provider id links nothing (as on the read
+      // path); its text reads as written.
+      continue;
+    }
+    const linked = await linkComponentDoc(catalog, provider, doc);
     const name = typeof doc?.name === 'string' ? doc.name : record.name;
     for (const problem of linked.problems) {
       problems.push(
@@ -1416,7 +1430,7 @@ export function placeLinks(tree, node) {
 
 /**
  * The moves a topic read offers: from its place in the tree, where a guide
- * sits in its namespace and a flat topic in the Unorganized level.
+ * sits in its namespace and a flat topic in its topic level.
  * @param {DocsCatalog} catalog
  * @param {import('../../foundation/discovery/docs-discovery.mjs').DocsTopicEntry} entry
  * @returns {Promise<import('./docs.type.mjs').DocsLinks>}
@@ -1514,7 +1528,7 @@ function treeArgument(catalog, tree, node) {
 /**
  * The doc that took a flat topic's route in the docs tree, when it is not
  * that topic (spec:AST-046 FR11): the CLI keeps its routes, such as `cli`
- * and `unorganized`, and a namespace keeps its route over a topic of the same
+ * and `guides`, and a namespace keeps its route over a topic of the same
  * name. Null when the topic owns its route, or the tree has no node there.
  * @param {DocsTree} tree
  * @param {import('../../foundation/discovery/docs-discovery.mjs').DocsTopicEntry} entry
@@ -1528,6 +1542,35 @@ export function routeOwner(tree, entry) {
     : node;
 }
 
+/**
+ * Routes that moved, old prefix first: the integration guides moved from
+ * `cli/integrations` (and, before that, the `cli-integrations` topic) into
+ * `authoring`, the one home for integration authors.
+ * Only the not-found error reads this, to name where a doc went; an old route
+ * opens nothing.
+ */
+const MOVED_ROUTES = [
+  ['cli/integrations', 'authoring'],
+  ['cli-integrations', 'authoring'],
+];
+
+/**
+ * The node an old route moved to, or null.
+ * @param {unknown} topic
+ * @param {DocsTree} tree
+ * @returns {TreeNode | null}
+ */
+function movedRoute(topic, tree) {
+  if (typeof topic !== 'string') return null;
+  const wanted = topic.toLowerCase();
+  for (const [from, to] of MOVED_ROUTES) {
+    if (wanted !== from && !wanted.startsWith(`${from}/`)) continue;
+    const node = tree.getFolded(`${to}${wanted.slice(from.length)}`);
+    if (node) return node;
+  }
+  return null;
+}
+
 /**
  * The error for a docs argument that names nothing. For a route, it suggests
  * the children of the deepest namespace the route reaches; otherwise, every
@@ -1560,8 +1603,7 @@ export async function unknownTopicError(topic, catalog) {
   }
   if (suggestions.length === 0 && typeof topic === 'string') {
     // The docs whose own name it is (`doctor` is cli/commands/doctor), or whose
-    // route it spells with hyphens (`cli-integrations`, the guide's name before
-    // it moved to cli/integrations).
+    // route it spells with hyphens (`cli-host-entry` is cli/host-entry).
     const wanted = topic.toLowerCase();
     suggestions = [...tree.nodes.values()]
       .filter(
@@ -1580,6 +1622,19 @@ export async function unknownTopicError(topic, catalog) {
       ...catalog.names().map(name => ({name, reason: 'available topic'})),
     ];
   }
+  // A route that moved names where it went, ahead of the usual suggestions
+  // (spec:AST-046 FR9, FR6).
+  const moved = movedRoute(topic, tree);
+  if (moved) {
+    return new AstryxError(
+      `Unknown topic "${String(topic)}". It moved to "${moved.route}"${notLoaded(catalog)}`,
+      [
+        {name: moved.route, reason: moved.summary},
+        ...suggestions.filter(entry => entry.name !== moved.route),
+      ],
+      ERROR_CODES.ERR_UNKNOWN_TOPIC,
+    );
+  }
   return new AstryxError(
     `Unknown topic "${String(topic)}"${notLoaded(catalog)}`,
     suggestions,

package/api/docs/docs-homes.test.mjs

@@ -0,0 +1,127 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Every Core doc has a named home in the docs tree (spec:AST-046 FR12).
+ *
+ * A reader sees a doc's home in its path (`Guides › Getting started`) and in
+ * its Up move. A flat Core topic sits in Guides or Foundations by the
+ * category it declares, so a new topic with no category, or one the levels
+ * do not know, fails here instead of landing in a catch-all. The integration
+ * guides and their field reference live under `authoring`, and the routes
+ * they left name where they went.
+ */
+
+import {describe, expect, it} from 'vitest';
+import {docs} from './docs.mjs';
+import {TOPIC_LEVELS} from '../../foundation/doc-compiler/tree.mjs';
+
+const CLI = '@astryxdesign/cli';
+const SLOW = 60_000;
+
+describe('every Core doc has a named home', () => {
+  it(
+    'puts each flat Core topic in Guides or Foundations by its category',
+    async () => {
+      const list = await docs();
+      const core = list.data.filter(topic => topic.package === CLI);
+      expect(core.length).toBeGreaterThan(10);
+      /** @type {string[]} */
+      const unfiled = [];
+      for (const topic of core) {
+        const read = await docs(topic.topic);
+        const {category} = read.data;
+        if (category !== 'guide' && category !== 'foundations') {
+          unfiled.push(`${topic.topic} (category ${String(category)})`);
+          continue;
+        }
+        const level =
+          category === 'foundations'
+            ? TOPIC_LEVELS.foundations
+            : TOPIC_LEVELS.guides;
+        expect(read.data.links.up, topic.topic).toBe(
+          `astryx docs ${level.route}`,
+        );
+      }
+      expect(unfiled, 'Core topics with no home: give each a category').toEqual(
+        [],
+      );
+    },
+    SLOW,
+  );
+
+  it(
+    'lists each level under a plain name, and no catch-all',
+    async () => {
+      const list = await docs();
+      const roots = (list.meta.namespaces ?? []).map(entry => entry.topic);
+      expect(roots).toEqual(expect.arrayContaining(['guides', 'foundations']));
+      expect(roots).not.toContain('unorganized');
+      const guides = await docs('guides');
+      expect(guides.data).toMatchObject({route: 'guides', title: 'Guides'});
+      expect(guides.data.slots[0].children.map(child => child.route)).toEqual(
+        expect.arrayContaining(['getting-started', 'principles', 'theme']),
+      );
+      const foundations = await docs('foundations');
+      expect(foundations.data.title).toBe('Foundations');
+      expect(
+        foundations.data.slots[0].children.map(child => child.route),
+      ).toEqual(expect.arrayContaining(['color', 'icons', 'spacing']));
+      await expect(docs('unorganized')).rejects.toMatchObject({
+        code: 'ERR_UNKNOWN_TOPIC',
+      });
+    },
+    SLOW,
+  );
+
+  it(
+    'keeps everything for integration authors under authoring, and names where an old route went',
+    async () => {
+      const authoring = await docs('authoring');
+      expect(authoring.data).toMatchObject({
+        route: 'authoring',
+        kind: 'namespace',
+        breadcrumb: [],
+        links: {up: 'astryx docs'},
+      });
+      const children = authoring.data.slots.flatMap(slot =>
+        slot.children.map(child => child.route),
+      );
+      expect(children).toEqual(
+        expect.arrayContaining([
+          'authoring/quick-start',
+          'authoring/building-blocks',
+          'authoring/ship',
+          'authoring/help',
+          'authoring/field-reference',
+        ]),
+      );
+      // Every field reference section still opens from the namespace by its
+      // key, as `astryx docs authoring <name>` did on the topic (FR13).
+      const reference = await docs('authoring/field-reference', undefined, {
+        index: true,
+      });
+      const keys = reference.data.sections.map(section => section.id);
+      expect(keys.length).toBeGreaterThan(15);
+      for (const key of keys) {
+        const section = await docs('authoring', key);
+        expect(section.type, key).toBe('docs.detail.section');
+        expect(section.data.id, key).toBe(key);
+      }
+      for (const [old, now] of [
+        ['cli/integrations', 'authoring'],
+        ['cli/integrations/quick-start', 'authoring/quick-start'],
+        ['cli/integrations/ship/publishing', 'authoring/ship/publishing'],
+      ]) {
+        const error = await docs(old).catch(e => e);
+        expect(error).toMatchObject({
+          code: 'ERR_UNKNOWN_TOPIC',
+          message: expect.stringContaining(`It moved to "${now}"`),
+        });
+        // The new route comes first, ahead of the suggestions any unknown
+        // route gets (FR6).
+        expect(error.suggestions[0]).toMatchObject({name: now});
+      }
+    },
+    SLOW,
+  );
+});

package/api/docs/docs.doc.mjs

@@ -28,7 +28,7 @@ export const doc = {
     '`cli/api` returns its children one level down (`depth` reads as many ' +
     'levels as asked, and `detail` how much of each doc below), a typed doc such as ' +
     "`cli/api/functions/search` returns its content, and a guide the tree " +
-    'places (`cli/integrations/quick-start`) reads like any topic. ' +
+    'places (`authoring/quick-start`) reads like any topic. ' +
     'Every read but the list carries `links`, the commands that move from it: ' +
     '`up` to the level it sits in, `previous` and `next` to its neighbors, and, ' +
     'for a typed doc, `related` to the docs it names (its command or function, ' +
@@ -162,12 +162,12 @@ export const doc = {
     },
     {
       label: 'A namespace and everything below it, in full',
-      code: "await docs('cli/integrations', undefined, {depth: 'all', detail: 'full'});",
+      code: "await docs('authoring', undefined, {depth: 'all', detail: 'full'});",
     },
     {label: 'One API function', code: "await docs('cli/api/functions/search');"},
     {
       label: 'A whole guide from the docs tree',
-      code: "await docs('cli/integrations/quick-start');",
+      code: "await docs('authoring/quick-start');",
     },
     {label: 'One section by key', code: "await docs('spacing', 'scale');"},
   ],

package/api/docs/docs.test.mjs

@@ -93,7 +93,7 @@ describe('docs() dispatcher routing', () => {
 
   it("lists the docs tree's namespaces in meta, so every data entry reads as a topic", async () => {
     const res = await docs();
-    expect(res.meta.namespaces.map(entry => entry.topic)).toEqual(['cli', 'global', 'internationalization', 'layout', 'migration', 'styling', 'styling-libraries', 'tokens', 'typography', 'unorganized']);
+    expect(res.meta.namespaces.map(entry => entry.topic)).toEqual(['authoring', 'cli', 'foundations', 'global', 'guides', 'internationalization', 'layout', 'migration', 'styling', 'styling-libraries', 'tokens', 'typography']);
     for (const entry of res.data) {
       expect((await docs(entry.topic)).type).toBe('docs.detail');
     }
@@ -123,7 +123,13 @@ describe('docs() dispatcher routing', () => {
       kind: 'namespace',
       package: '@astryxdesign/cli',
       breadcrumb: [{route: 'cli', title: 'Astryx CLI'}],
-      content: [],
+      // Its one block points to the host entry's guide.
+      content: [
+        {
+          type: 'prose',
+          text: expect.stringContaining('`astryx docs cli/host-entry`'),
+        },
+      ],
     });
     expect(r.data.slots.flatMap(slot => slot.children.map(c => c.route))).toEqual([
       'cli/api/functions',
@@ -152,8 +158,8 @@ describe('docs() dispatcher routing', () => {
   }, SLOW);
 
   it('a guide the tree places reads like a topic: the whole doc, its index, a section', async () => {
-    // cli/integrations is a namespace of short guides; each guide reads like a topic.
-    const integrations = await docs('cli/integrations');
+    // authoring is a namespace of short guides; each guide reads like a topic.
+    const integrations = await docs('authoring');
     expect(integrations.type).toBe('docs.node');
     const guide = placedGuide(integrations.data);
     expect((await docs(guide)).type).toBe('docs.detail');
@@ -172,7 +178,7 @@ describe('docs() dispatcher routing', () => {
     expect(leaf.links.up).toBe('astryx docs cli/api/functions');
     expect(leaf.links.previous).toMatch(/^astryx docs cli\/api\/functions\/[a-z-]+$/);
     expect(leaf.links.next).toMatch(/^astryx docs cli\/api\/functions\/[a-z-]+$/);
-    const integrations = (await docs('cli/integrations')).data;
+    const integrations = (await docs('authoring')).data;
     const guide = placedGuide(integrations);
     const siblings = integrations.slots
       .find(slot => slot.children.some(child => child.route === guide))
@@ -181,7 +187,7 @@ describe('docs() dispatcher routing', () => {
     const index = await docs(guide, undefined, {index: true});
     // A guide moves across its namespace's slot, as any tree node does.
     expect(index.data.links).toEqual({
-      up: 'astryx docs cli/integrations',
+      up: 'astryx docs authoring',
       ...(at > 0 ? {previous: `astryx docs ${siblings[at - 1]}`} : {}),
       ...(at < siblings.length - 1
         ? {next: `astryx docs ${siblings[at + 1]}`}
@@ -198,16 +204,22 @@ describe('docs() dispatcher routing', () => {
     expect(end.links.previous).toBe(
       `astryx docs ${guide} ${index.data.sections.at(-2).id}`,
     );
-    // A flat topic's home is the Unorganized level, and it moves across it.
+    // A flat topic's home is the level for its category, and it moves across it.
     const flat = (await docs('principles')).data.links;
-    expect(flat.up).toBe('astryx docs unorganized');
+    expect(flat.up).toBe('astryx docs guides');
     expect(flat.previous).toMatch(/^astryx docs [a-z-]+$/);
     expect(flat.next).toMatch(/^astryx docs [a-z-]+$/);
-    const home = (await docs('unorganized')).data;
-    expect(home).toMatchObject({id: null, kind: 'namespace', links: {up: 'astryx docs'}});
-    expect(home.slots[0].children.map(child => child.route)).toEqual(
-      (await docs()).data.map(entry => entry.topic),
-    );
+    const guides = (await docs('guides')).data;
+    expect(guides).toMatchObject({id: null, kind: 'namespace', links: {up: 'astryx docs'}});
+    const foundations = (await docs('foundations')).data;
+    expect(foundations).toMatchObject({id: null, kind: 'namespace', links: {up: 'astryx docs'}});
+    // Between them the two levels hold every flat topic, each in list order.
+    const topics = (await docs()).data.map(entry => entry.topic);
+    const held = [guides, foundations].map(level => level.slots[0].children.map(child => child.route));
+    for (const routes of held) {
+      expect(routes).toEqual(topics.filter(topic => routes.includes(topic)));
+    }
+    expect(held.flat().sort()).toEqual([...topics].sort());
   }, SLOW);
 
   it('names a node by its doc identity; a generated level has id null', async () => {
@@ -234,10 +246,9 @@ describe('docs() dispatcher routing', () => {
   }, SLOW);
 
   it("the guide's old flat name is gone, and its error names the new route", async () => {
-    await expect(docs('cli-integrations')).rejects.toMatchObject({
-      code: 'ERR_UNKNOWN_TOPIC',
-      suggestions: [expect.objectContaining({name: 'cli/integrations'})],
-    });
+    const error = await docs('cli-integrations').catch(e => e);
+    expect(error.code).toBe('ERR_UNKNOWN_TOPIC');
+    expect(error.suggestions[0]).toMatchObject({name: 'authoring'});
     expect((await docs()).data.map(entry => entry.topic)).not.toContain(
       'cli-integrations',
     );
@@ -247,11 +258,16 @@ describe('docs() dispatcher routing', () => {
     const err = await docs('cli', 'zzzz-nope').catch(e => e);
     expect(err).toBeInstanceOf(AstryxError);
     expect(err.code).toBe('ERR_UNKNOWN_SECTION');
-    // It names every guide below the namespace, at any depth.
     const names = err.suggestions.map(s => s.name);
     expect(names).toContain('cli/component-lookups');
-    expect(names).toContain('cli/integrations/quick-start');
     expect(names.every(name => name.startsWith('cli/'))).toBe(true);
+    // It names every guide below the namespace, at any depth.
+    const deep = await docs('authoring', 'zzzz-nope').catch(e => e);
+    expect(deep.code).toBe('ERR_UNKNOWN_SECTION');
+    const below = deep.suggestions.map(s => s.name);
+    expect(below).toContain('authoring/quick-start');
+    expect(below).toContain('authoring/building-blocks/components/add-a-component');
+    expect(below.every(name => name.startsWith('authoring/'))).toBe(true);
   }, SLOW);
 
   it('an unknown route suggests the children of the deepest namespace it reaches', async () => {