@astryxdesign/cli 0.6.3-canary.7ada42e → 0.6.3-canary.7ec7be0

package/foundation/doc-compiler/links.test.mjs

@@ -0,0 +1,192 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Links between docs (spec:AST-047 FR9): the target grammar, and how a
+ * list of blocks comes back with every link resolved or named as a problem.
+ */
+
+import {describe, expect, it} from 'vitest';
+import {
+  linkBlocks,
+  linkSections,
+  parseLinkTarget,
+  unlinkText,
+} from './links.mjs';
+
+/** A resolver over two docs, the second from another provider. */
+const resolve = async (/** @type {string} */ target) => {
+  const docs = {
+    'command:doctor': {route: 'cli/commands/doctor', title: 'astryx doctor'},
+    '@acme/kit:generic:setup': {route: 'acme/setup', title: 'Set up Acme'},
+  };
+  const doc = /** @type {any} */ (docs)[target];
+  return doc
+    ? {
+        target,
+        id: `id:${target}`,
+        route: doc.route,
+        title: doc.title,
+        summary: `About ${doc.title}.`,
+        command: `astryx docs ${doc.route}`,
+      }
+    : {problem: `"${target}" names no doc`};
+};
+
+describe('parseLinkTarget', () => {
+  it('reads a doc of the same provider, or of a named one', () => {
+    expect(parseLinkTarget('command:theme build')).toEqual({
+      provider: null,
+      kind: 'command',
+      name: 'theme build',
+    });
+    expect(parseLinkTarget('@astryxdesign/cli:function:search')).toEqual({
+      provider: '@astryxdesign/cli',
+      kind: 'function',
+      name: 'search',
+    });
+  });
+
+  it('refuses a target that is not `[<provider>:]<kind>:<name>`', () => {
+    for (const bad of ['', 'search', 'a:b:c:d', 'command:', 'widget:x']) {
+      expect(parseLinkTarget(bad)).toHaveProperty('error');
+    }
+  });
+});
+
+describe('linkBlocks', () => {
+  it('reads an inline link as the command that opens its doc', async () => {
+    const {content, problems} = await linkBlocks(
+      [
+        {type: 'prose', text: 'Check it with {@link command:doctor}.'},
+        {type: 'list', style: 'unordered', items: ['See {@link @acme/kit:generic:setup}']},
+        {type: 'table', headers: ['Doc'], rows: [['{@link command:doctor}']]},
+        {type: 'code', lang: 'js', code: '{@link command:doctor}'},
+      ],
+      resolve,
+    );
+    expect(problems).toEqual([]);
+    expect(content[0].text).toBe('Check it with `astryx docs cli/commands/doctor`.');
+    expect(content[1].items).toEqual(['See `astryx docs acme/setup`']);
+    expect(content[2].rows).toEqual([['`astryx docs cli/commands/doctor`']]);
+    // Code is an example: it is shown as written.
+    expect(content[3].code).toBe('{@link command:doctor}');
+  });
+
+  it('shows a link written in code ticks as written', async () => {
+    const {content, problems} = await linkBlocks(
+      [{type: 'prose', text: 'Write `{@link <target>}` to link; {@link command:doctor} checks it.'}],
+      resolve,
+    );
+    expect(problems).toEqual([]);
+    expect(content[0].text).toBe(
+      'Write `{@link <target>}` to link; `astryx docs cli/commands/doctor` checks it.',
+    );
+  });
+
+  it('gives a reference block and each workflow step the doc they name', async () => {
+    const {content, problems} = await linkBlocks(
+      [
+        {type: 'reference', target: 'command:doctor'},
+        {
+          type: 'workflow',
+          steps: [{title: 'Check', references: ['command:doctor']}],
+        },
+      ],
+      resolve,
+    );
+    expect(problems).toEqual([]);
+    expect(content[0].link).toMatchObject({
+      route: 'cli/commands/doctor',
+      command: 'astryx docs cli/commands/doctor',
+      title: 'astryx doctor',
+    });
+    expect(content[1].steps[0].links[0].command).toBe(
+      'astryx docs cli/commands/doctor',
+    );
+  });
+
+  it('includes what a reference block names, and marks what it cannot include', async () => {
+    /** @type {any[]} */
+    const asked = [];
+    const include = async (/** @type {any} */ block) => {
+      asked.push(block.target);
+      return {
+        content: [{type: 'prose', text: 'The doctor command.'}],
+        problems: block.projection ? ['projection.fields: no such field'] : [],
+      };
+    };
+    const {content, problems} = await linkBlocks(
+      [
+        {type: 'reference', target: 'command:doctor'},
+        {
+          type: 'reference',
+          target: 'command:doctor',
+          projection: {fields: ['--nope']},
+        },
+        {type: 'reference', target: 'command:gone'},
+      ],
+      resolve,
+      {section: 'check'},
+      include,
+    );
+    // A target that names no doc is never handed to the includer.
+    expect(asked).toEqual(['command:doctor', 'command:doctor']);
+    expect(content[0]).toMatchObject({
+      link: {command: 'astryx docs cli/commands/doctor'},
+      content: [{type: 'prose', text: 'The doctor command.'}],
+    });
+    expect(content[2]).toEqual({
+      type: 'reference',
+      target: 'command:gone',
+      link: null,
+    });
+    // Both are the authoring check's: the block includes content, where a
+    // link only points at it.
+    expect(problems).toEqual([
+      {
+        target: 'command:doctor',
+        message: 'projection.fields: no such field',
+        include: true,
+        section: 'check',
+      },
+      {
+        target: 'command:gone',
+        message: '"command:gone" names no doc',
+        include: true,
+        section: 'check',
+      },
+    ]);
+  });
+
+  it('names every link that finds no doc, and never guesses', async () => {
+    const {content, problems} = await linkSections(
+      [
+        {
+          id: 'one',
+          title: 'One',
+          content: [
+            {type: 'prose', text: 'See {@link command:nope}.'},
+            {type: 'reference', target: 'generic:gone'},
+            {type: 'collection', source: {slot: 'guides'}},
+          ],
+        },
+      ],
+      resolve,
+    ).then(({sections, problems}) => ({content: sections[0].content, problems}));
+    expect(content[0].text).toBe('See {@link command:nope}.');
+    expect(content[1].link).toBeNull();
+    expect(problems.map(p => [p.section, p.target])).toEqual([
+      ['one', 'command:nope'],
+      ['one', 'generic:gone'],
+      ['one', 'collection:guides'],
+    ]);
+  });
+});
+
+describe('unlinkText', () => {
+  it('keeps the name of each link, for an index', () => {
+    expect(unlinkText('Run {@link command:theme build} or {@link x}.')).toBe(
+      'Run theme build or x.',
+    );
+  });
+});

package/foundation/doc-compiler/lower-doc.test.mjs

@@ -386,7 +386,10 @@ describe('parseCompiledDocNode and parseCompiledDocsBundle', () => {
   it('accepts a node of every kind and a bundle, as given', () => {
     const value = bundle();
     expect(parseCompiledDocsBundle(value)).toBe(value);
-    expect(COMPILED_DOC_KINDS).toHaveLength(9);
+    expect(COMPILED_DOC_KINDS).toHaveLength(10);
+    // A namespace doc, which the docs tree reads, lowers to a node too.
+    const namespace = {...node(), kind: 'namespace'};
+    expect(parseCompiledDocNode(namespace)).toBe(namespace);
   });
 
   it('names schema skew with its own diagnostic, before anything else', () => {
@@ -413,7 +416,7 @@ describe('parseCompiledDocNode and parseCompiledDocsBundle', () => {
     ],
     [
       'an unknown kind',
-      (/** @type {any} */ n) => (n.kind = 'namespace'),
+      (/** @type {any} */ n) => (n.kind = 'workflow'),
       /not a compiled doc kind/,
     ],
     [

package/foundation/doc-compiler/read.d.mts

@@ -73,11 +73,12 @@ export const DOC_EXPORTS: Readonly<{
     hooks: string[];
     templates: string[];
     'self-docs': string[];
+    tree: string[];
 }>;
 /** The localized overlays a docs read can apply. */
 export const OVERLAY_LANGUAGES: string[];
 export type ReadOptions = {
-    root: "components" | "hooks" | "templates" | "themes" | "self-docs";
+    root: "components" | "hooks" | "templates" | "themes" | "self-docs" | "tree";
     /**
      * overlay language; null reads the authored
      * text
@@ -101,7 +102,7 @@ export type ReadOptions = {
      * how to import the module (default
      * `user`)
      */
-    loader?: "template" | "user" | "native" | undefined;
+    loader?: "template" | "native" | "user" | undefined;
     /**
      * which exports name the doc, in
      * precedence order, for a reader that has always read a narrower set than its

package/foundation/doc-compiler/read.mjs

@@ -45,6 +45,8 @@ export const DOC_EXPORTS = Object.freeze({
   hooks: ['default', 'docs'],
   templates: ['default', 'doc'],
   'self-docs': ['doc', 'docs', 'default'],
+  // The docs tree's own files: namespace docs and the guides it places.
+  tree: ['docs', 'default'],
 });
 
 /** How a reader imports a doc module. */
@@ -59,7 +61,7 @@ const LOADERS = Object.freeze({
 
 /**
  * @typedef {object} ReadOptions
- * @property {'components' | 'hooks' | 'templates' | 'themes' | 'self-docs'} root
+ * @property {'components' | 'hooks' | 'templates' | 'themes' | 'self-docs' | 'tree'} root
  * @property {string | null} [lang] overlay language; null reads the authored
  *   text
  * @property {string} [label] how a parse error names the file (default: its
@@ -307,14 +309,17 @@ export async function loadTopicInput(entry, lang) {
     extensions.push({
       ...(await loadTopicFile(extension.path, lang)),
       provider: extension.package,
+      providerId: extension.providerId ?? extension.package,
     });
   }
   return {
     id: entry.name,
     provider: entry.package,
+    providerId: entry.providerId ?? entry.package,
     replaces: entry.replaces ?? null,
     lang,
     base: await loadTopicFile(entry.path, lang),
     extensions,
+    ...(entry.tree === true ? {tree: true} : {}),
   };
 }

package/foundation/doc-compiler/tree.d.mts

@@ -0,0 +1,288 @@
+// @generated by scripts/sync-api-types.mjs from the JSDoc in foundation/**/*.mjs.
+// DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
+
+/**
+ * Build the tree. Pure: the same inputs give the same tree, whatever order
+ * they arrive in.
+ *
+ * A doc's home is decided once, in this order: its explicit `placement`, then
+ * the one adoption rule in its package that matches its group and kind. A
+ * placement that fails withdraws the doc; it never falls back to adoption. A
+ * doc with neither is a flat topic: it keeps its flat name as its route, and its
+ * home is the generated Unorganized level. The CLI keeps its own routes: an
+ * integration's node that would take one is withdrawn with a diagnostic.
+ *
+ * @param {{namespaces: TreeNamespaceInput[], docs: TreeDocInput[], topics?: TreeTopicInput[]}} inputs
+ * @returns {DocsTree}
+ */
+export function buildDocsTree({ namespaces, docs, topics }: {
+    namespaces: TreeNamespaceInput[];
+    docs: TreeDocInput[];
+    topics?: TreeTopicInput[];
+}): DocsTree;
+/**
+ * The files under {@link TREE_DOCS_DIR}, sorted.
+ * @param {string} [dir]
+ * @returns {string[]}
+ */
+export function treeDocFiles(dir?: string): string[];
+/**
+ * The CLI's own tree inputs: the namespace docs and guides under
+ * assets/docs/tree, and, unless left out, every typed self-doc with its
+ * `namespace` group. A file that fails to load or parse is a diagnostic, never
+ * a thrown error.
+ * @param {{selfDocs?: boolean, dir?: string}} [options]
+ * @returns {Promise<{namespaces: TreeNamespaceInput[], docs: TreeDocInput[], diagnostics: CompilerDiagnostic[]}>}
+ */
+export function loadTreeInputs({ selfDocs, dir, }?: {
+    selfDocs?: boolean;
+    dir?: string;
+}): Promise<{
+    namespaces: TreeNamespaceInput[];
+    docs: TreeDocInput[];
+    diagnostics: CompilerDiagnostic[];
+}>;
+/**
+ * The CLI's own docs tree, built once per process. With `selfDocs: false` it
+ * holds only the namespaces and guides, which is all a topic list needs.
+ * @param {{selfDocs?: boolean, fresh?: boolean}} [options]
+ * @returns {Promise<DocsTree>}
+ */
+export function loadDocsTree({ selfDocs, fresh }?: {
+    selfDocs?: boolean;
+    fresh?: boolean;
+}): Promise<DocsTree>;
+export { routeSegment };
+/** Where the CLI keeps the docs that only the tree reads. */
+export const TREE_DOCS_DIR: string;
+/** One route segment: lowercase letters and digits joined by single hyphens. */
+export const ROUTE_SEGMENT_RE: RegExp;
+/**
+ * The generated level that `groupBy: 'kind'` makes for each kind: its route
+ * segment, title, and summary.
+ * @type {Readonly<Record<string, {segment: string, title: string, summary: string}>>}
+ */
+export const KIND_GROUPS: Readonly<Record<string, {
+    segment: string;
+    title: string;
+    summary: string;
+}>>;
+/**
+ * @typedef {import('../../authoring/doctypes/namespace/type').NamespaceDoc} NamespaceDoc
+ * @typedef {import('../../authoring/doctypes/base/type').DocPlacement} DocPlacement
+ * @typedef {import('./diagnostics.mjs').CompilerDiagnostic} CompilerDiagnostic
+ */
+/**
+ * @typedef {object} TreeNamespaceInput
+ * @property {string} provider the package that owns the namespace
+ * @property {string} providerId the provider's ProviderId (its manifest
+ *   `providerId`, else its package name); node ids are built from it
+ * @property {number} [rank] which provider wins a contested route: the CLI's
+ *   own docs are 0, then each integration in configured order
+ * @property {string} source `<package>/<path>` of its file
+ * @property {NamespaceDoc} doc
+ */
+/**
+ * @typedef {object} TreeDocInput
+ * @property {string} provider the package that authored the doc
+ * @property {string} providerId the provider's ProviderId (its manifest
+ *   `providerId`, else its package name); node ids are built from it
+ * @property {number} [rank] which provider wins a contested route: the CLI's
+ *   own docs are 0, then each integration in configured order
+ * @property {string} source
+ * @property {import('../../authoring/doctypes/base/type').AuthoredDocKind} kind
+ *   the authored kind: `generic`, `command`, `function`, `schema`, or `enum`
+ * @property {string} name the doc's stable name
+ * @property {string} title
+ * @property {string} summary
+ * @property {string | null} group the discovery group adoption reads, or null
+ * @property {DocPlacement | undefined} placement
+ * @property {any} [ref] what a reader needs to open the doc, carried as given
+ */
+/**
+ * @typedef {object} TreeSlot
+ * @property {string} name
+ * @property {string} title
+ * @property {string[]} children child routes, in reading order
+ */
+/**
+ * A flat topic: a reference topic that no namespace places. The tree gives it
+ * a home in the generated Unorganized level, under its own name.
+ * @typedef {object} TreeTopicInput
+ * @property {string} provider the package that owns the topic
+ * @property {string} providerId the provider's ProviderId
+ * @property {string} name the topic's name, which stays its route
+ * @property {string} title
+ * @property {string} summary
+ * @property {string} source where the topic comes from, for diagnostics
+ * @property {string[]} [aliases] every other name the topic answers to: the
+ *   topics it replaced, directly or through a chain
+ */
+/** The route of the generated level that holds every flat topic. */
+export const UNORGANIZED: "unorganized";
+export type NamespaceDoc = import("../../authoring/doctypes/namespace/type").NamespaceDoc;
+export type DocPlacement = import("../../authoring/doctypes/base/type").DocPlacement;
+export type CompilerDiagnostic = import("./diagnostics.mjs").CompilerDiagnostic;
+export type TreeNamespaceInput = {
+    /**
+     * the package that owns the namespace
+     */
+    provider: string;
+    /**
+     * the provider's ProviderId (its manifest
+     * `providerId`, else its package name); node ids are built from it
+     */
+    providerId: string;
+    /**
+     * which provider wins a contested route: the CLI's
+     * own docs are 0, then each integration in configured order
+     */
+    rank?: number | undefined;
+    /**
+     * `<package>/<path>` of its file
+     */
+    source: string;
+    doc: NamespaceDoc;
+};
+export type TreeDocInput = {
+    /**
+     * the package that authored the doc
+     */
+    provider: string;
+    /**
+     * the provider's ProviderId (its manifest
+     * `providerId`, else its package name); node ids are built from it
+     */
+    providerId: string;
+    /**
+     * which provider wins a contested route: the CLI's
+     * own docs are 0, then each integration in configured order
+     */
+    rank?: number | undefined;
+    source: string;
+    /**
+     *   the authored kind: `generic`, `command`, `function`, `schema`, or `enum`
+     */
+    kind: import("../../authoring/doctypes/base/type").AuthoredDocKind;
+    /**
+     * the doc's stable name
+     */
+    name: string;
+    title: string;
+    summary: string;
+    /**
+     * the discovery group adoption reads, or null
+     */
+    group: string | null;
+    placement: DocPlacement | undefined;
+    /**
+     * what a reader needs to open the doc, carried as given
+     */
+    ref?: any;
+};
+export type TreeSlot = {
+    name: string;
+    title: string;
+    /**
+     * child routes, in reading order
+     */
+    children: string[];
+};
+/**
+ * A flat topic: a reference topic that no namespace places. The tree gives it
+ * a home in the generated Unorganized level, under its own name.
+ */
+export type TreeTopicInput = {
+    /**
+     * the package that owns the topic
+     */
+    provider: string;
+    /**
+     * the provider's ProviderId
+     */
+    providerId: string;
+    /**
+     * the topic's name, which stays its route
+     */
+    name: string;
+    title: string;
+    summary: string;
+    /**
+     * where the topic comes from, for diagnostics
+     */
+    source: string;
+    /**
+     * every other name the topic answers to: the
+     * topics it replaced, directly or through a chain
+     */
+    aliases?: string[] | undefined;
+};
+export type TreeNode = {
+    /**
+     * the doc's DocId, built from its provider's
+     * ProviderId, kind, and name: stable when the route moves; null on a
+     * generated level, which has no authored doc
+     */
+    id: string | null;
+    route: string;
+    /**
+     * `namespace` or the doc's authored kind
+     */
+    kind: string;
+    /**
+     * the package that owns it
+     */
+    provider: string;
+    /**
+     * its provider's ProviderId
+     */
+    providerId: string;
+    name: string;
+    title: string;
+    summary: string;
+    /**
+     * the parent's route; null at the top
+     */
+    parent: string | null;
+    /**
+     * the parent slot this node sits in
+     */
+    slot: string | null;
+    order: number | null;
+    /**
+     * made by the compiler (a `groupBy: 'kind'`
+     * level, or the Unorganized level), not authored
+     */
+    generated: boolean;
+    /**
+     * a namespace's slots; empty for a leaf
+     */
+    slots: TreeSlot[];
+    source: string;
+    ref?: any;
+};
+export type DocsTree = {
+    /**
+     * by route, in route order
+     */
+    nodes: Map<string, TreeNode>;
+    /**
+     * sorted
+     */
+    diagnostics: CompilerDiagnostic[];
+    get: (route: string) => TreeNode | undefined;
+    /**
+     * the node at a
+     * route compared without case, as topic names are
+     */
+    getFolded: (route: string) => TreeNode | undefined;
+    /**
+     * the namespaces with no parent
+     */
+    roots: () => TreeNode[];
+    /**
+     * top first, not the node
+     */
+    ancestors: (node: TreeNode) => TreeNode[];
+};
+import { routeSegment } from '../discovery/docs-section-key.mjs';