@astryxdesign/cli 0.7.2-canary.fdd384f → 0.7.2

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

@@ -29,6 +29,8 @@
  * @property {string} target the target as written
  * @property {string} message
  * @property {string} [section] the key of the section the link sits in
+ * @property {string} [field] the field the link sits in, outside any section:
+ *   `description`, or a path such as `props[2].description`
  * @property {true} [include] the problem is in a `reference` block, which
  *   includes content rather than linking to it: a reader loses that content,
  *   so the authoring check fails on it
@@ -55,6 +57,31 @@ export function parseLinkTarget(target: unknown): LinkTarget | {
  * @returns {string}
  */
 export function unlinkText(text: string): string;
+/**
+ * Every text field of a doc object, in authored order, by the same rules
+ * {@link linkFields} resolves links by: the strings a reader reads, never a
+ * name, type, default, or code.
+ * @param {unknown} doc
+ * @returns {{field: string, text: string}[]}
+ */
+export function textFields(doc: unknown): {
+    field: string;
+    text: string;
+}[];
+/**
+ * Resolve every inline link in the text fields of a doc object, such as a
+ * component doc or a topic's summary fields (spec:AST-047 FR9): its
+ * description, its usage and best practices, each prop's and example's
+ * description, at any depth. Code and code ticks show link syntax as written.
+ * @template T
+ * @param {T} doc
+ * @param {LinkResolver} resolve
+ * @returns {Promise<{doc: T, problems: LinkProblem[]}>}
+ */
+export function linkFields<T>(doc: T, resolve: LinkResolver): Promise<{
+    doc: T;
+    problems: LinkProblem[];
+}>;
 /**
  * Resolve every link in a list of content blocks, in order.
  * @param {any[]} blocks
@@ -148,6 +175,11 @@ export type LinkProblem = {
      * the key of the section the link sits in
      */
     section?: string | undefined;
+    /**
+     * the field the link sits in, outside any section:
+     * `description`, or a path such as `props[2].description`
+     */
+    field?: string | undefined;
     /**
      * the problem is in a `reference` block, which
      * includes content rather than linking to it: a reader loses that content,

package/foundation/doc-compiler/links.mjs

@@ -65,6 +65,8 @@ const CODE_SPAN = /(`[^`]*`)/;
  * @property {string} target the target as written
  * @property {string} message
  * @property {string} [section] the key of the section the link sits in
+ * @property {string} [field] the field the link sits in, outside any section:
+ *   `description`, or a path such as `props[2].description`
  * @property {true} [include] the problem is in a `reference` block, which
  *   includes content rather than linking to it: a reader loses that content,
  *   so the authoring check fails on it
@@ -91,7 +93,11 @@ export function parseLinkTarget(target) {
     };
   }
   const parts = target.trim().split(':');
-  if (parts.length < 2 || parts.length > 3 || parts.some(p => p.trim() === '')) {
+  if (
+    parts.length < 2 ||
+    parts.length > 3 ||
+    parts.some(p => p.trim() === '')
+  ) {
     return {error: `"${target}" is not \`[<provider>:]<kind>:<name>\``};
   }
   const provider = parts.length === 3 ? parts[0].trim() : null;
@@ -127,6 +133,159 @@ export function unlinkText(text) {
     .join('');
 }
 
+/**
+ * Text with each inline link replaced by the command that opens its doc. A
+ * link written inside code ticks is shown as written: it documents the syntax,
+ * it does not link. A link that names no doc prints as written: text that was
+ * never meant as a link reads the way it did, and doctor names the problem.
+ * @param {unknown} text
+ * @param {(target: string) => Promise<DocLink | null>} find
+ * @returns {Promise<any>}
+ */
+async function resolveInline(text, find) {
+  if (typeof text !== 'string' || !text.includes('{@link')) return text;
+  let out = '';
+  for (const part of text.split(CODE_SPAN)) {
+    if (part.startsWith('`')) {
+      out += part;
+      continue;
+    }
+    let last = 0;
+    for (const match of part.matchAll(INLINE_LINK)) {
+      const link = await find(match[1]);
+      const at = /** @type {number} */ (match.index);
+      out += part.slice(last, at);
+      out += link ? `\`${link.command}\`` : match[0];
+      last = at + match[0].length;
+    }
+    out += part.slice(last);
+  }
+  return out;
+}
+
+/**
+ * The fields of a doc that hold text a reader reads, where a link resolves:
+ * a description or summary, an example's label, and each value of a
+ * `propDescriptions` overlay. Every other string is a name, a type, a
+ * default, or code, and is shown as written.
+ */
+const TEXT_FIELDS = new Set(['description', 'summary', 'label']);
+
+/** Fields that hold code or data, never text: nothing below them links. */
+const CODE_FIELDS = new Set([
+  'code',
+  'playground',
+  'slotElements',
+  'registry',
+  'keywords',
+]);
+
+/**
+ * Every text field of a doc object, in authored order, by the same rules
+ * {@link linkFields} resolves links by: the strings a reader reads, never a
+ * name, type, default, or code.
+ * @param {unknown} doc
+ * @returns {{field: string, text: string}[]}
+ */
+export function textFields(doc) {
+  /** @type {{field: string, text: string}[]} */
+  const out = [];
+  /**
+   * @param {unknown} value
+   * @param {string} at
+   * @param {boolean} text
+   */
+  const walk = (value, at, text) => {
+    if (typeof value === 'string') {
+      if (text) out.push({field: at, text: value});
+      return;
+    }
+    if (Array.isArray(value)) {
+      value.forEach((item, i) => walk(item, `${at}[${i}]`, false));
+      return;
+    }
+    if (value == null || typeof value !== 'object') return;
+    for (const [key, field] of Object.entries(value)) {
+      const path = at === '' ? key : `${at}.${key}`;
+      if (CODE_FIELDS.has(key)) continue;
+      if (key === 'propDescriptions' && field && typeof field === 'object') {
+        for (const [prop, description] of Object.entries(field)) {
+          walk(description, `${path}.${prop}`, true);
+        }
+      } else {
+        walk(field, path, TEXT_FIELDS.has(key));
+      }
+    }
+  };
+  walk(doc, '', false);
+  return out;
+}
+
+/**
+ * Resolve every inline link in the text fields of a doc object, such as a
+ * component doc or a topic's summary fields (spec:AST-047 FR9): its
+ * description, its usage and best practices, each prop's and example's
+ * description, at any depth. Code and code ticks show link syntax as written.
+ * @template T
+ * @param {T} doc
+ * @param {LinkResolver} resolve
+ * @returns {Promise<{doc: T, problems: LinkProblem[]}>}
+ */
+export async function linkFields(doc, resolve) {
+  /** @type {LinkProblem[]} */
+  const problems = [];
+  /**
+   * @param {unknown} value
+   * @param {string} at the field path, e.g. `usage.bestPractices[0].description`
+   * @param {boolean} text whether a string here is text
+   * @returns {Promise<any>}
+   */
+  const walk = async (value, at, text) => {
+    if (typeof value === 'string') {
+      if (!text) return value;
+      return resolveInline(value, async target => {
+        const found = await resolve(target);
+        if ('problem' in found) {
+          problems.push({target, message: found.problem, field: at});
+          return null;
+        }
+        return found;
+      });
+    }
+    if (Array.isArray(value)) {
+      const out = [];
+      for (let i = 0; i < value.length; i++) {
+        out.push(await walk(value[i], `${at}[${i}]`, false));
+      }
+      return out;
+    }
+    if (value == null || typeof value !== 'object') return value;
+    /** @type {Record<string, unknown>} */
+    const out = {};
+    for (const [key, field] of Object.entries(value)) {
+      const path = at === '' ? key : `${at}.${key}`;
+      if (CODE_FIELDS.has(key)) {
+        out[key] = field;
+      } else if (
+        key === 'propDescriptions' &&
+        field &&
+        typeof field === 'object'
+      ) {
+        /** @type {Record<string, unknown>} */
+        const described = {};
+        for (const [prop, description] of Object.entries(field)) {
+          described[prop] = await walk(description, `${path}.${prop}`, true);
+        }
+        out[key] = described;
+      } else {
+        out[key] = await walk(field, path, TEXT_FIELDS.has(key));
+      }
+    }
+    return out;
+  };
+  return {doc: await walk(doc, '', false), problems};
+}
+
 /**
  * Resolve every link in a list of content blocks, in order.
  * @param {any[]} blocks
@@ -156,30 +315,7 @@ export async function linkBlocks(blocks, resolve, at = {}, include) {
    * @param {unknown} text
    * @returns {Promise<any>}
    */
-  const linkText = async text => {
-    if (typeof text !== 'string' || !text.includes('{@link')) return text;
-    let out = '';
-    // A link written inside code ticks is shown as written: it documents the
-    // syntax, it does not link.
-    for (const part of text.split(CODE_SPAN)) {
-      if (part.startsWith('`')) {
-        out += part;
-        continue;
-      }
-      let last = 0;
-      for (const match of part.matchAll(INLINE_LINK)) {
-        const link = await find(match[1]);
-        const at = /** @type {number} */ (match.index);
-        out += part.slice(last, at);
-        // A link that names no doc prints as written: text that was never
-        // meant as a link reads the way it did, and doctor names the problem.
-        out += link ? `\`${link.command}\`` : match[0];
-        last = at + match[0].length;
-      }
-      out += part.slice(last);
-    }
-    return out;
-  };
+  const linkText = text => resolveInline(text, find);
   /**
    * @param {unknown[]} values
    * @returns {Promise<any[]>}
@@ -251,7 +387,8 @@ export async function linkBlocks(blocks, resolve, at = {}, include) {
           }
           if (Array.isArray(step.references)) {
             const links = [];
-            for (const target of step.references) links.push(await find(target));
+            for (const target of step.references)
+              links.push(await find(target));
             linked.links = links;
           }
           steps.push(linked);

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

@@ -8,8 +8,10 @@
 import {describe, expect, it} from 'vitest';
 import {
   linkBlocks,
+  linkFields,
   linkSections,
   parseLinkTarget,
+  textFields,
   unlinkText,
 } from './links.mjs';
 
@@ -58,14 +60,20 @@ describe('linkBlocks', () => {
     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: '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[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.
@@ -74,7 +82,12 @@ describe('linkBlocks', () => {
 
   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.'}],
+      [
+        {
+          type: 'prose',
+          text: 'Write `{@link <target>}` to link; {@link command:doctor} checks it.',
+        },
+      ],
       resolve,
     );
     expect(problems).toEqual([]);
@@ -172,7 +185,10 @@ describe('linkBlocks', () => {
         },
       ],
       resolve,
-    ).then(({sections, problems}) => ({content: sections[0].content, problems}));
+    ).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([
@@ -190,3 +206,80 @@ describe('unlinkText', () => {
     );
   });
 });
+
+describe('linkFields', () => {
+  /** A component doc with a link in every kind of text field, and in code. */
+  const DOC = {
+    name: 'AcmeButton',
+    description: 'Run {@link command:doctor} first.',
+    usage: {
+      description: 'Set it up: {@link @acme/kit:generic:setup}.',
+      bestPractices: [
+        {guidance: true, description: 'Check with {@link command:doctor}.'},
+      ],
+    },
+    props: [
+      {
+        name: 'tone',
+        type: '{@link command:doctor}',
+        default: "'{@link command:doctor}'",
+        description: 'Like `{@link command:doctor}`, or {@link generic:nope}.',
+      },
+    ],
+    propDescriptions: {tone: 'See {@link command:doctor}.'},
+    examples: [
+      {label: 'From {@link command:doctor}', code: '{@link command:doctor}'},
+    ],
+    playground: {defaults: {label: '{@link command:doctor}'}},
+  };
+
+  it('resolves each text field and leaves names, types, defaults, and code as written', async () => {
+    const {doc, problems} = await linkFields(DOC, resolve);
+    expect(doc).toEqual({
+      ...DOC,
+      description: 'Run `astryx docs cli/commands/doctor` first.',
+      usage: {
+        description: 'Set it up: `astryx docs acme/setup`.',
+        bestPractices: [
+          {
+            guidance: true,
+            description: 'Check with `astryx docs cli/commands/doctor`.',
+          },
+        ],
+      },
+      props: [
+        {
+          ...DOC.props[0],
+          description:
+            'Like `{@link command:doctor}`, or {@link generic:nope}.',
+        },
+      ],
+      propDescriptions: {tone: 'See `astryx docs cli/commands/doctor`.'},
+      examples: [
+        {
+          label: 'From `astryx docs cli/commands/doctor`',
+          code: '{@link command:doctor}',
+        },
+      ],
+    });
+    expect(problems).toEqual([
+      {
+        target: 'generic:nope',
+        message: expect.any(String),
+        field: 'props[0].description',
+      },
+    ]);
+  });
+
+  it('names the same text fields textFields reads', async () => {
+    const {problems} = await linkFields(DOC, async target => ({
+      problem: `no ${target}`,
+    }));
+    const fields = textFields(DOC)
+      .filter(({text}) => text.replace(/`[^`]*`/g, '').includes('{@link'))
+      .map(({field}) => field);
+    expect([...new Set(problems.map(problem => problem.field))]).toEqual(
+      fields,
+    );
+  });
+});

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

@@ -102,7 +102,7 @@ export type ReadOptions = {
      * how to import the module (default
      * `user`)
      */
-    loader?: "template" | "native" | "user" | undefined;
+    loader?: "template" | "user" | "native" | 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/tree.mjs

@@ -242,7 +242,8 @@ export function buildDocsTree({namespaces, docs, topics = []}) {
   // without case, as topic names do, so `CLI` claims `cli`.
   const cliRoutes = new Set(topics.length > 0 ? [UNORGANIZED] : []);
   for (const topic of topics) {
-    if (topic.provider === CLI_PROVIDER) cliRoutes.add(topic.name.toLowerCase());
+    if (topic.provider === CLI_PROVIDER)
+      cliRoutes.add(topic.name.toLowerCase());
   }
   // Every other name a topic answers to (the topics it replaced, directly or
   // through a chain) is that topic's route too: `astryx docs <name>` opens the
@@ -375,6 +376,34 @@ export function buildDocsTree({namespaces, docs, topics = []}) {
       return false;
     }
     const taken = byFoldedRoute.get(folded);
+    if (
+      taken &&
+      taken.provider === CLI_PROVIDER &&
+      node.provider !== CLI_PROVIDER &&
+      !node.generated
+    ) {
+      // Astryx's own doc keeps its route: name both docs as an author knows
+      // them, never by their ids, and say what to change.
+      const what = (/** @type {TreeNode} */ n) =>
+        n.kind === 'namespace'
+          ? 'namespace'
+          : n.kind === 'generic'
+            ? 'topic'
+            : `${n.kind} doc`;
+      const scope = String(node.provider).split('/').pop() ?? '';
+      const suggestion = `${
+        scope
+          .replace(/[^a-z0-9]+/gi, '-')
+          .replace(/^-|-$/g, '')
+          .toLowerCase() || 'my'
+      }-${node.name.toLowerCase()}`;
+      report(
+        'duplicate_route',
+        at,
+        `The ${what(node)} "${node.name}" from ${node.provider} and Astryx's own ${what(taken)} "${taken.name}" both have the route "${node.route}", so \`astryx docs ${node.route}\` cannot open both. Fix: rename "${node.name}" (its \`name\` and its file), such as \`name: '${suggestion}'\`${node.route.includes('/') ? ', or place it elsewhere' : ''}.`,
+      );
+      return false;
+    }
     if (taken) {
       report(
         'duplicate_route',

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

@@ -171,6 +171,13 @@ describe('buildDocsTree', () => {
         ['duplicate_route', expect.stringContaining('takes the route "UNORGANIZED", which the CLI\'s own docs keep')],
       ]),
     );
+    // It names both docs as their authors know them, never by artifact id,
+    // and says what to change.
+    const taken = problems(tree).find(([, message]) => message.includes('route "CLI"'))?.[1];
+    expect(taken).toBe(
+      `The topic "CLI" from ${P} and Astryx's own namespace "cli" both have the route "CLI", so \`astryx docs CLI\` cannot open both. Fix: rename "CLI" (its \`name\` and its file), such as \`name: 'kit-cli'\`.`,
+    );
+    expect(taken).not.toContain('astryx:artifact');
     expect(tree.getFolded('THEME')?.provider).toBe(CLI);
     // A CLI topic whose own name has capitals keeps its route against a
     // lowercase namespace, although namespaces go into the tree first.
@@ -495,7 +502,7 @@ describe("the CLI's own docs tree", () => {
     async () => {
       const tree = await loadDocsTree({fresh: true});
       expect(tree.diagnostics).toEqual([]);
-      expect(tree.roots().map(node => node.route)).toEqual(['cli', 'internationalization', 'layout', 'migration', 'styling', 'styling-libraries', 'tokens', 'typography']);
+      expect(tree.roots().map(node => node.route)).toEqual(['cli', 'global', 'internationalization', 'layout', 'migration', 'styling', 'styling-libraries', 'tokens', 'typography']);
       // Every slot child is a node one level below the namespace that places
       // it, and every node but the root is placed. Read from the tree, so a
       // restructure of the guides does not need this test edited.

package/foundation/env/cli-command.d.mts

@@ -0,0 +1,83 @@
+// @generated by scripts/sync-api-types.mjs from the JSDoc in foundation/**/*.mjs.
+// DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
+
+/**
+ * Run `fn` with `command` as the door printed commands start with. The slot a
+ * host fills for one call. An integration's `cliCommand` still comes first,
+ * and conflicting ones still fall back to the guess.
+ * @template T
+ * @param {string} command e.g. `astryx` for a global launcher
+ * @param {() => T} fn
+ * @returns {T}
+ */
+export function runWithCliDoor<T>(command: string, fn: () => T): T;
+/**
+ * The door of the current call, if a host set one.
+ * @returns {string | undefined}
+ */
+export function cliDoor(): string | undefined;
+/**
+ * The commands a set of loaded integrations declares, in load order. An
+ * integration that failed to load, or was set aside for a provider conflict,
+ * contributes nothing, so it declares nothing either.
+ * @param {ReadonlyArray<{name?: string, __spec?: string, cliCommand?: string, __loadError?: string, __providerConflict?: unknown}>} integrations
+ * @returns {DeclaredCliCommand[]}
+ */
+export function declaredCliCommandsOf(integrations: ReadonlyArray<{
+    name?: string;
+    __spec?: string;
+    cliCommand?: string;
+    __loadError?: string;
+    __providerConflict?: unknown;
+}>): DeclaredCliCommand[];
+/**
+ * Choose among declarations: one command, declared by one or more
+ * integrations, is used; different commands are a conflict.
+ * @param {DeclaredCliCommand[]} declared
+ * @returns {{command?: string, conflict: boolean, declared: DeclaredCliCommand[]}}
+ */
+export function chooseDeclaredCliCommand(declared: DeclaredCliCommand[]): {
+    command?: string;
+    conflict: boolean;
+    declared: DeclaredCliCommand[];
+};
+/**
+ * Record the commands a project's loaded integrations declare. Called by
+ * `Project.load` each time it resolves the integration set; the latest load
+ * wins.
+ * @param {string} projectDir
+ * @param {Parameters<typeof declaredCliCommandsOf>[0]} integrations
+ * @returns {void}
+ */
+export function recordDeclaredCliCommands(projectDir: string, integrations: Parameters<typeof declaredCliCommandsOf>[0]): void;
+/**
+ * Whether this process has loaded the project at `targetDir`.
+ * @param {string} [targetDir=process.cwd()]
+ * @returns {boolean}
+ */
+export function hasRecordedProject(targetDir?: string): boolean;
+/**
+ * What the integrations of the project at `targetDir` declare, as recorded by
+ * its last `Project.load` in this process; see
+ * {@link chooseDeclaredCliCommand}.
+ * @param {string} [targetDir=process.cwd()]
+ * @returns {{command?: string, conflict: boolean, declared: DeclaredCliCommand[]}}
+ */
+export function declaredCliCommand(targetDir?: string): {
+    command?: string;
+    conflict: boolean;
+    declared: DeclaredCliCommand[];
+};
+/**
+ * One integration's declared command.
+ */
+export type DeclaredCliCommand = {
+    /**
+     * the integration package that declared it
+     */
+    package: string;
+    /**
+     * its `cliCommand` value
+     */
+    command: string;
+};