@astryxdesign/cli 0.6.3 → 0.6.4-canary.06c8fa3

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

@@ -0,0 +1,162 @@
+// @generated by scripts/sync-api-types.mjs from the JSDoc in foundation/**/*.mjs.
+// DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
+
+/**
+ * @typedef {object} LinkTarget
+ * @property {string | null} provider the provider id it names, or null for the
+ *   linking doc's own provider
+ * @property {string} kind
+ * @property {string} name
+ */
+/**
+ * The doc a link opens, as a docs read returns it.
+ * @typedef {object} DocLink
+ * @property {string} target the target as written: `[<provider>:]<kind>:<name>`
+ * @property {string} id the doc's identity (a DocId)
+ * @property {string} route what `astryx docs <route>` opens
+ * @property {string} title
+ * @property {string} summary
+ * @property {string} command the command that opens it, `astryx docs <route>`
+ */
+/**
+ * Finds the doc a target names, or says why none matches.
+ * @typedef {(target: string) => Promise<DocLink | {problem: string}>} LinkResolver
+ */
+/**
+ * @typedef {object} LinkProblem
+ * @property {string} target the target as written
+ * @property {string} message
+ * @property {string} [section] the key of the section the link sits in
+ * @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
+ */
+/**
+ * What a `reference` block in a topic section includes of the doc it names:
+ * stable content blocks, with anything it could not include named in
+ * `problems`.
+ * @typedef {(block: any) => Promise<{content: any[], problems: string[]}>} DocIncluder
+ */
+/**
+ * Parse `[<provider>:]<kind>:<name>`. A name may hold spaces
+ * (`command:theme build`); no part holds a colon.
+ * @param {unknown} target
+ * @returns {LinkTarget | {error: string}}
+ */
+export function parseLinkTarget(target: unknown): LinkTarget | {
+    error: string;
+};
+/**
+ * Text with each inline link replaced by its name, for indexes that must not
+ * read the link syntax as words.
+ * @param {string} text
+ * @returns {string}
+ */
+export function unlinkText(text: string): string;
+/**
+ * Resolve every link in a list of content blocks, in order.
+ * @param {any[]} blocks
+ * @param {LinkResolver} resolve
+ * @param {{section?: string}} [at]
+ * @param {DocIncluder} [include] how a `reference` block includes the doc it
+ *   names; without it, the block only carries its `link`
+ * @returns {Promise<{content: any[], problems: LinkProblem[]}>}
+ */
+export function linkBlocks(blocks: any[], resolve: LinkResolver, at?: {
+    section?: string;
+}, include?: DocIncluder): Promise<{
+    content: any[];
+    problems: LinkProblem[];
+}>;
+/**
+ * Resolve every link in a topic's sections.
+ * @param {any[]} sections
+ * @param {LinkResolver} resolve
+ * @returns {Promise<{sections: any[], problems: LinkProblem[]}>}
+ */
+export function linkSections(sections: any[], resolve: LinkResolver): Promise<{
+    sections: any[];
+    problems: LinkProblem[];
+}>;
+/**
+ * @file Links between docs, named by doc identity (spec:AST-047 FR9).
+ *
+ * @input A link target, `[<provider>:]<kind>:<name>`, written as a `reference`
+ *   block, in a `workflow` step's `references`, or inline in text as
+ *   `{@link <target>}`; and a resolver that finds the doc a target names.
+ * @output The same content with every link resolved: an inline link becomes
+ *   the `astryx docs` command that opens its doc, and a block carries a `link`
+ *   with the doc's identity, route, title, summary, and command. A reference
+ *   block in a topic section also carries the `content` it includes. A link
+ *   that names no doc is a problem, never a guess.
+ * @position Pure. The docs adapter owns the resolver (the project's docs tree
+ *   and topic catalog) and applies this to every read and every doctor check.
+ */
+/** The kinds a link can name: every authored doc kind. */
+export const LINK_KINDS: Set<string>;
+/** An inline link in text: `{@link <target>}`. */
+export const INLINE_LINK: RegExp;
+export type LinkTarget = {
+    /**
+     * the provider id it names, or null for the
+     * linking doc's own provider
+     */
+    provider: string | null;
+    kind: string;
+    name: string;
+};
+/**
+ * The doc a link opens, as a docs read returns it.
+ */
+export type DocLink = {
+    /**
+     * the target as written: `[<provider>:]<kind>:<name>`
+     */
+    target: string;
+    /**
+     * the doc's identity (a DocId)
+     */
+    id: string;
+    /**
+     * what `astryx docs <route>` opens
+     */
+    route: string;
+    title: string;
+    summary: string;
+    /**
+     * the command that opens it, `astryx docs <route>`
+     */
+    command: string;
+};
+/**
+ * Finds the doc a target names, or says why none matches.
+ */
+export type LinkResolver = (target: string) => Promise<DocLink | {
+    problem: string;
+}>;
+export type LinkProblem = {
+    /**
+     * the target as written
+     */
+    target: string;
+    message: string;
+    /**
+     * the key of the section the link sits in
+     */
+    section?: string | undefined;
+    /**
+     * 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
+     */
+    include?: true | undefined;
+};
+/**
+ * What a `reference` block in a topic section includes of the doc it names:
+ * stable content blocks, with anything it could not include named in
+ * `problems`.
+ */
+export type DocIncluder = (block: any) => Promise<{
+    content: any[];
+    problems: string[];
+}>;

package/foundation/doc-compiler/links.mjs

@@ -0,0 +1,294 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Links between docs, named by doc identity (spec:AST-047 FR9).
+ *
+ * @input A link target, `[<provider>:]<kind>:<name>`, written as a `reference`
+ *   block, in a `workflow` step's `references`, or inline in text as
+ *   `{@link <target>}`; and a resolver that finds the doc a target names.
+ * @output The same content with every link resolved: an inline link becomes
+ *   the `astryx docs` command that opens its doc, and a block carries a `link`
+ *   with the doc's identity, route, title, summary, and command. A reference
+ *   block in a topic section also carries the `content` it includes. A link
+ *   that names no doc is a problem, never a guess.
+ * @position Pure. The docs adapter owns the resolver (the project's docs tree
+ *   and topic catalog) and applies this to every read and every doctor check.
+ */
+
+/** The kinds a link can name: every authored doc kind. */
+export const LINK_KINDS = new Set([
+  'generic',
+  'command',
+  'function',
+  'schema',
+  'enum',
+  'namespace',
+  'component',
+  'page',
+  'block',
+]);
+
+/** An inline link in text: `{@link <target>}`. */
+export const INLINE_LINK = /\{@link\s+([^{}]+?)\s*\}/g;
+
+/** Code spans in text, which show link syntax as written. */
+const CODE_SPAN = /(`[^`]*`)/;
+
+/**
+ * @typedef {object} LinkTarget
+ * @property {string | null} provider the provider id it names, or null for the
+ *   linking doc's own provider
+ * @property {string} kind
+ * @property {string} name
+ */
+
+/**
+ * The doc a link opens, as a docs read returns it.
+ * @typedef {object} DocLink
+ * @property {string} target the target as written: `[<provider>:]<kind>:<name>`
+ * @property {string} id the doc's identity (a DocId)
+ * @property {string} route what `astryx docs <route>` opens
+ * @property {string} title
+ * @property {string} summary
+ * @property {string} command the command that opens it, `astryx docs <route>`
+ */
+
+/**
+ * Finds the doc a target names, or says why none matches.
+ * @typedef {(target: string) => Promise<DocLink | {problem: string}>} LinkResolver
+ */
+
+/**
+ * @typedef {object} LinkProblem
+ * @property {string} target the target as written
+ * @property {string} message
+ * @property {string} [section] the key of the section the link sits in
+ * @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
+ */
+
+/**
+ * What a `reference` block in a topic section includes of the doc it names:
+ * stable content blocks, with anything it could not include named in
+ * `problems`.
+ * @typedef {(block: any) => Promise<{content: any[], problems: string[]}>} DocIncluder
+ */
+
+/**
+ * Parse `[<provider>:]<kind>:<name>`. A name may hold spaces
+ * (`command:theme build`); no part holds a colon.
+ * @param {unknown} target
+ * @returns {LinkTarget | {error: string}}
+ */
+export function parseLinkTarget(target) {
+  if (typeof target !== 'string' || target.trim() === '') {
+    return {
+      error:
+        'a link target is a non-empty string: `[<provider>:]<kind>:<name>`',
+    };
+  }
+  const parts = target.trim().split(':');
+  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;
+  const kind = parts[parts.length - 2].trim();
+  const name = parts[parts.length - 1].trim();
+  if (!LINK_KINDS.has(kind)) {
+    return {
+      error: `"${target}" names the kind "${kind}"; a doc kind is one of ${[
+        ...LINK_KINDS,
+      ].join(', ')}`,
+    };
+  }
+  return {provider, kind, name};
+}
+
+/**
+ * Text with each inline link replaced by its name, for indexes that must not
+ * read the link syntax as words.
+ * @param {string} text
+ * @returns {string}
+ */
+export function unlinkText(text) {
+  return text
+    .split(CODE_SPAN)
+    .map(part =>
+      part.startsWith('`')
+        ? part
+        : part.replace(INLINE_LINK, (_, target) => {
+            const parsed = parseLinkTarget(target);
+            return 'error' in parsed ? target : parsed.name;
+          }),
+    )
+    .join('');
+}
+
+/**
+ * Resolve every link in a list of content blocks, in order.
+ * @param {any[]} blocks
+ * @param {LinkResolver} resolve
+ * @param {{section?: string}} [at]
+ * @param {DocIncluder} [include] how a `reference` block includes the doc it
+ *   names; without it, the block only carries its `link`
+ * @returns {Promise<{content: any[], problems: LinkProblem[]}>}
+ */
+export async function linkBlocks(blocks, resolve, at = {}, include) {
+  /** @type {LinkProblem[]} */
+  const problems = [];
+  const where = at.section ? {section: at.section} : {};
+  /**
+   * @param {string} target
+   * @returns {Promise<DocLink | null>}
+   */
+  const find = async target => {
+    const found = await resolve(target);
+    if ('problem' in found) {
+      problems.push({target, message: found.problem, ...where});
+      return null;
+    }
+    return found;
+  };
+  /**
+   * @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;
+  };
+  /**
+   * @param {unknown[]} values
+   * @returns {Promise<any[]>}
+   */
+  const linkAll = async values => {
+    const out = [];
+    for (const value of values) out.push(await linkText(value));
+    return out;
+  };
+
+  const content = [];
+  for (const block of blocks ?? []) {
+    switch (block?.type) {
+      case 'prose':
+      case 'heading':
+        content.push({...block, text: await linkText(block.text)});
+        break;
+      case 'list':
+        content.push({...block, items: await linkAll(block.items ?? [])});
+        break;
+      case 'table': {
+        const rows = [];
+        for (const row of block.rows ?? []) rows.push(await linkAll(row));
+        content.push({
+          ...block,
+          headers: await linkAll(block.headers ?? []),
+          rows,
+        });
+        break;
+      }
+      case 'reference': {
+        // A reference includes content, so what it cannot include is a
+        // problem the authoring check fails on, not one that prints as written.
+        const found = await resolve(block.target);
+        if ('problem' in found) {
+          problems.push({
+            target: block.target,
+            message: found.problem,
+            include: true,
+            ...where,
+          });
+          content.push({...block, link: null});
+          break;
+        }
+        /** @type {any} */
+        const linked = {...block, link: found};
+        if (include) {
+          const included = await include(block);
+          for (const message of included.problems) {
+            problems.push({
+              target: block.target,
+              message,
+              include: true,
+              ...where,
+            });
+          }
+          linked.content = included.content;
+        }
+        content.push(linked);
+        break;
+      }
+      case 'workflow': {
+        const steps = [];
+        for (const step of block.steps ?? []) {
+          /** @type {any} */
+          const linked = {...step};
+          if (step.description != null) {
+            linked.description = await linkText(step.description);
+          }
+          if (Array.isArray(step.references)) {
+            const links = [];
+            for (const target of step.references) links.push(await find(target));
+            linked.links = links;
+          }
+          steps.push(linked);
+        }
+        content.push({...block, steps});
+        break;
+      }
+      case 'collection':
+        problems.push({
+          target: `collection:${block.source?.slot ?? ''}`,
+          message:
+            'a collection block is not rendered yet; link each doc with a reference block instead',
+          ...where,
+        });
+        content.push(block);
+        break;
+      default:
+        content.push(block);
+    }
+  }
+  return {content, problems};
+}
+
+/**
+ * Resolve every link in a topic's sections.
+ * @param {any[]} sections
+ * @param {LinkResolver} resolve
+ * @returns {Promise<{sections: any[], problems: LinkProblem[]}>}
+ */
+export async function linkSections(sections, resolve) {
+  /** @type {LinkProblem[]} */
+  const problems = [];
+  const out = [];
+  for (const section of sections ?? []) {
+    const linked = await linkBlocks(section.content, resolve, {
+      section: section.id ?? section.title,
+    });
+    problems.push(...linked.problems);
+    out.push({...section, content: linked.content});
+  }
+  return {sections: out, problems};
+}

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.',
+    );
+  });
+});