Skip to content

An open source design system that's fully customizable and agent ready

TypeScript
10.0 KB
Raw Blame
// Copyright (c) Meta Platforms, Inc. and affiliates.

/**
 * @file docs.node leaf — one namespace or typed doc in the docs tree.
 *
 * @input A route the docs tree resolves: a namespace such as `cli/api`, or a
 *   typed doc such as `cli/api/functions/search`, plus {cwd}.
 * @output { type: 'docs.node', data: DocsNode } — the node's identity, title
 *   and summary, the namespaces above it, and either its slots with their
 *   children (a namespace) or its content (a typed doc). By default a
 *   namespace lists its children one level down; a depth read goes as far
 *   down as asked, with each doc below as its identity (brief) or with its
 *   text (compact, full). Matches `astryx --json docs <route> [--depth <n>]`.
 * @position Leaf under api/docs, beside the topic leaves. A guide the tree
 *   places is a topic: the detail leaf reads it by its route.
 */

import {detailView} from '../../../foundation/doc-compiler/lenses.mjs';
import {
  childIdentity,
  compileTopic,
  guideEntry,
  nodeContent,
  placeLinks,
  resolveDocsArgument,
  stabilityOf,
  unknownTopicError,
} from '../_adapter.mjs';

/**
 * @typedef {import('../../../foundation/doc-compiler/tree.mjs').DocsTree} DocsTree
 * @typedef {import('../../../foundation/doc-compiler/tree.mjs').TreeNode} TreeNode
 * @typedef {import('../../../foundation/discovery/docs-discovery.mjs').DocsCatalog} DocsCatalog
 */

/**
 * How far a read goes below the node it names, and how much of each doc below
 * it shows: `depth` levels (Infinity for every level), and `detail` brief (its
 * identity), or compact or full (with its text: a namespace's intro, a guide's
 * sections, a typed doc's content). `lang` selects the guides' language.
 * @typedef {object} DepthRead
 * @property {number} depth
 * @property {'brief' | 'compact' | 'full'} detail
 * @property {string | null} lang
 */

/**
 * The docs.node view of one tree node. Without a depth read, a namespace lists
 * its children one level down.
 * @param {DocsCatalog} catalog
 * @param {DocsTree} tree
 * @param {TreeNode} node
 * @param {DepthRead} [read] how far down to go, and how much of each doc below
 * @returns {Promise<import('../docs.type.mjs').DocsNode>}
 */
export async function nodeView(catalog, tree, node, read) {
  const {content} = await nodeContent(catalog, tree, node);
  const slots = node.slots.filter(slot => slot.children.length > 0);
  /** @type {import('../docs.type.mjs').DocsNode} */
  const view = {
    id: node.id,
    route: node.route,
    kind: node.kind,
    package: node.provider,
    title: node.title,
    summary: node.summary,
    ...stabilityOf(tree, node),
    breadcrumb: tree
      .ancestors(node)
      .map(ancestor => ({route: ancestor.route, title: ancestor.title})),
    slots: !read
      ? slots.map(slot => ({
          name: slot.name,
          title: slot.title,
          children: slot.children.map(route =>
            childIdentity(tree, /** @type {TreeNode} */ (tree.get(route))),
          ),
        }))
      : read.depth >= 1
        ? await slotsBelow(catalog, tree, slots, 1, read)
        : [],
    content,
    links: nodeLinks(tree, node),
  };
  if (read && read.depth < 1 && slots.length > 0) {
    view.childCount = countChildren(slots);
  }
  return view;
}

/**
 * @param {TreeNode['slots']} slots
 * @returns {number}
 */
function countChildren(slots) {
  return slots.reduce((count, slot) => count + slot.children.length, 0);
}

/**
 * Slots read `level` levels below the named node: each child at the read's
 * detail, and its own slots while the read goes deeper.
 * @param {DocsCatalog} catalog
 * @param {DocsTree} tree
 * @param {TreeNode['slots']} slots
 * @param {number} level
 * @param {DepthRead} read
 * @returns {Promise<import('../docs.type.mjs').DocsNodeSlot[]>}
 */
async function slotsBelow(catalog, tree, slots, level, read) {
  return Promise.all(
    slots.map(async slot => ({
      name: slot.name,
      title: slot.title,
      children: await Promise.all(
        slot.children.map(route =>
          childBelow(
            catalog,
            tree,
            /** @type {TreeNode} */ (tree.get(route)),
            level,
            read,
          ),
        ),
      ),
    })),
  );
}

/**
 * One child of a depth read. Where the read stops, a child with docs below it
 * says how many, so a reader knows to go deeper.
 * @param {DocsCatalog} catalog
 * @param {DocsTree} tree
 * @param {TreeNode} child
 * @param {number} level
 * @param {DepthRead} read
 * @returns {Promise<import('../docs.type.mjs').DocsNodeChild>}
 */
async function childBelow(catalog, tree, child, level, read) {
  const view = childIdentity(tree, child);
  if (read.detail !== 'brief') {
    Object.assign(view, await childText(catalog, tree, child, read.lang));
  }
  const slots = child.slots.filter(slot => slot.children.length > 0);
  if (slots.length > 0) {
    if (level < read.depth) {
      view.slots = await slotsBelow(catalog, tree, slots, level + 1, read);
    } else {
      view.childCount = countChildren(slots);
    }
  }
  return view;
}

/**
 * A child's text: a guide's compiled sections, or the content of a namespace
 * or typed doc.
 * @param {DocsCatalog} catalog
 * @param {DocsTree} tree
 * @param {TreeNode} child
 * @param {string | null} lang
 * @returns {Promise<{content?: any[], sections?: any[]}>}
 */
async function childText(catalog, tree, child, lang) {
  if (child.kind === 'generic') {
    const entry = child.ref?.topicFile
      ? guideEntry(child)
      : child.ref?.flatTopic
        ? catalog.resolve(child.ref.flatTopic)
        : null;
    if (!entry) return {};
    return {
      sections: detailView(await compileTopic(catalog, entry, lang)).sections,
    };
  }
  const {content} = await nodeContent(catalog, tree, child);
  return {content};
}

/**
 * The moves a node offers (spec:AST-047): up to the level it sits in (the
 * topic list, for a top-level namespace), and across to the nodes before and
 * after it in its parent's slot.
 * @param {DocsTree} tree
 * @param {TreeNode} node
 * @returns {import('../docs.type.mjs').DocsLinks}
 */
function nodeLinks(tree, node) {
  const links = placeLinks(tree, node);
  const related = typedEdges(tree, node).routes;
  if (related.length > 0) {
    links.related = related.map(
      route =>
        /** @type {import('../docs.type.mjs').DocsCommand} */ (
          `astryx docs ${route}`
        ),
    );
  }
  return links;
}

/** @type {WeakMap<DocsTree, Map<string, string>>} */
const routeIndexes = new WeakMap();

/**
 * The route of each node, by its kind and name.
 * @param {DocsTree} tree
 * @returns {Map<string, string>}
 */
function routeIndex(tree) {
  let routes = routeIndexes.get(tree);
  if (!routes) {
    routes = new Map();
    for (const each of tree.nodes.values()) {
      routes.set(`${each.kind}\u0000${each.name}`, each.route);
    }
    routeIndexes.set(tree, routes);
  }
  return routes;
}

/**
 * The kinds of doc each typed field may name. A bare name in one of these
 * fields names a doc of the same provider and one of these kinds, so it is a
 * doc identity (spec:AST-047 FR9).
 */
const EDGE_KINDS = {
  function: {command: ['command'], related: ['function']},
  command: {fn: ['function'], related: ['command']},
};

/**
 * The typed edges a doc declares (spec:AST-047 FR5), resolved to routes: a
 * function doc's `command` and `related`, and a command doc's `fn` and
 * `related`. A bare name resolves among the kinds its field allows; a name
 * that matches docs of more than one allowed kind is an error, never a silent
 * pick. A `command` resolves to the command doc its leading words name, so
 * `integration add theme` (the `integration add` command with its kind
 * argument) opens `integration add`. Every name that resolves to no doc, or to
 * more than one, is returned in `unresolved`; the graph walk test fails on it,
 * so no edge a doc declares can go stale.
 * @param {DocsTree} tree
 * @param {TreeNode} node
 * @returns {{routes: string[], unresolved: string[]}}
 */
export function typedEdges(tree, node) {
  const doc = /** @type {any} */ (node.ref)?.selfDoc;
  /** @type {string[]} */
  const routes = [];
  /** @type {string[]} */
  const unresolved = [];
  const fields = /** @type {Record<string, string[]> | undefined} */ (
    /** @type {any} */ (EDGE_KINDS)[node.kind]
  );
  if (!doc || !fields) return {routes, unresolved};
  const index = routeIndex(tree);
  /** @param {string[]} kinds @param {string} name */
  const among = (kinds, name) =>
    kinds
      .map(kind => index.get(`${kind}\u0000${name}`))
      .filter(route => typeof route === 'string');
  for (const [field, kinds] of Object.entries(fields)) {
    const value = doc[field];
    const names = Array.isArray(value) ? value : value == null ? [] : [value];
    for (const name of names) {
      if (typeof name !== 'string' || name.trim() === '') continue;
      let found = among(kinds, name);
      if (found.length === 0 && field === 'command') {
        const words = name.trim().split(/\s+/);
        for (let n = words.length - 1; n > 0 && found.length === 0; n--) {
          found = among(kinds, words.slice(0, n).join(' '));
        }
      }
      if (found.length === 1) routes.push(/** @type {string} */ (found[0]));
      else if (found.length === 0) {
        unresolved.push(`${field} "${name}" names no ${kinds.join(' or ')} doc`);
      } else {
        unresolved.push(
          `${field} "${name}" names more than one doc (${found.join(', ')})`,
        );
      }
    }
  }
  return {
    routes: [...new Set(routes)].filter(route => route !== node.route),
    unresolved,
  };
}

/**
 * @param {string} route
 * @param {{cwd?: string}} [options]
 * @returns {Promise<import('../docs.type.mjs').DocsNodeResponse>}
 */
export async function node(route, options = {}) {
  const found = await resolveDocsArgument(route, options);
  if (found.kind !== 'node')
    throw await unknownTopicError(route, found.catalog);
  return {
    type: 'docs.node',
    // The docs tree names each node's npm package as its provider.
    package: found.node.provider,
    data: await nodeView(found.catalog, found.tree, found.node),
  };
}