Skip to content

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

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

/**
 * @file Stray doc pointers (architecture:cli-surface DEC-8): a code span in
 * prose that is exactly `astryx docs <name>`, or its `{@command docs <name>}`
 * token, for a doc that exists. The doc's
 * `{@link}` prints the command that opens the doc and is checked by doctor's
 * link check, so a written command is a pointer nothing checks.
 *
 * @input the docs a package ships, as discoverIntegrationDocs returns them
 * @output each stray pointer, with the link that replaces it
 * @position foundation/discovery, called through api/integration/_adapter.mjs
 */

import fs from 'node:fs';

import {textFields} from '../doc-compiler/links.mjs';
import {builtinGuideFiles} from './docs-discovery.mjs';
import {
  fileWords,
  lineAtOffset,
  loadQuietly,
  locateWords,
  textWords,
} from './copied-passages.mjs';

/**
 * A code span that is exactly the command opening one doc. A command with
 * more words, a flag, or a route is a walkthrough, not a pointer. A name holds
 * what a topic name may (letters, digits, `_` and `-`), never opening with `-`.
 */
const POINTER =
  /`astryx docs ([A-Za-z0-9_][A-Za-z0-9_-]*)`|`?\{@command docs ([A-Za-z0-9_][A-Za-z0-9_-]*)\}`?/g;

/** @type {Promise<Map<string, string>> | undefined} */
let coreKinds;

/**
 * The CLI's own docs by name, each with the kind a link names it by: a
 * namespace doc as `namespace`, a topic or guide as `generic`.
 * @returns {Promise<Map<string, string>>}
 */
function loadCoreKinds() {
  coreKinds ??= (async () => {
    const kinds = new Map();
    for (const file of builtinGuideFiles()) {
      const doc = await loadQuietly(file);
      if (typeof doc?.name === 'string') {
        kinds.set(doc.name, doc.type === 'namespace' ? 'namespace' : 'generic');
      }
    }
    return kinds;
  })();
  return coreKinds;
}

/**
 * The strings of a doc the CLI resolves links in (spec:AST-047 FR9). In a
 * topic: its description and summary, then the text of prose and heading
 * blocks, list items, and table cells in each section's content, with the
 * section's title. In a component doc (any doc with no sections): every text
 * field, such as its description, usage, best practices, and each prop's and
 * example's description, with the field's path. Code is never read.
 *
 * @param {unknown} doc an authored doc object
 * @returns {{text: string, section: string | null, field: string | null}[]}
 */
export function linkableStrings(doc) {
  /** @type {{text: string, section: string | null, field: string | null}[]} */
  const strings = [];
  if (doc == null || typeof doc !== 'object') return strings;
  const top = /** @type {Record<string, any>} */ (doc);
  if (!Array.isArray(top.sections)) {
    for (const {field, text} of textFields(doc)) {
      strings.push({text, section: null, field});
    }
    return strings;
  }
  for (const field of ['description', 'summary']) {
    if (typeof top[field] === 'string') {
      strings.push({text: top[field], section: null, field});
    }
  }
  /**
   * @param {unknown} value
   * @param {string | null} section
   */
  const walk = (value, section) => {
    if (Array.isArray(value)) {
      for (const item of value) walk(item, section);
      return;
    }
    if (value == null || typeof value !== 'object') return;
    const record = /** @type {Record<string, any>} */ (value);
    const title = typeof record.title === 'string' ? record.title : section;
    if (Array.isArray(record.sections)) walk(record.sections, section);
    if (!Array.isArray(record.content)) return;
    for (const block of record.content) {
      const add = (/** @type {unknown} */ text) => {
        if (typeof text === 'string') {
          strings.push({text, section: title, field: null});
        }
      };
      switch (block?.type) {
        case 'prose':
        case 'heading':
          add(block.text);
          break;
        case 'list':
          (block.items ?? []).forEach(add);
          break;
        case 'table':
          (block.headers ?? []).forEach(add);
          for (const row of block.rows ?? []) row.forEach(add);
          break;
        default:
          walk(block, title);
      }
    }
  };
  walk(doc, null);
  return strings;
}

/**
 * Every pointer span in one prose string, in order.
 * @param {string} text
 * @returns {string[]} the doc name each one points at
 */
export function pointersIn(text) {
  return [...text.matchAll(POINTER)].map(match => match[1] ?? match[2]);
}

/**
 * Where a string's words start among a file's words, from `from` on. A
 * one-line string the file holds as a quoted literal is found at that
 * literal, so a list item that is only `astryx docs theme` is not placed at a
 * summary or code block that writes the same words.
 *
 * @param {string[]} lines the file's lines
 * @param {{word: string, line: number}[]} file the file's words
 * @param {string} text
 * @param {{word: string}[]} words the string's words
 * @param {number} from
 * @returns {number}
 */
function locateString(lines, file, text, words, from) {
  /** @type {number[]} */
  const starts = [];
  for (let at = locateWords(file, words); at >= 0;) {
    starts.push(at);
    at = locateWords(file, words, at + 1);
  }
  if (starts.length === 0) return -1;
  const literals = text.includes('\n')
    ? []
    : [`'${text}'`, `"${text}"`, `'${text.replace(/'/g, "\\'")}'`];
  const quoted = starts.filter(at =>
    literals.some(literal => lines[file[at].line - 1]?.includes(literal)),
  );
  const pool = quoted.length > 0 ? quoted : starts;
  return pool.find(at => at >= from) ?? pool[0];
}

/**
 * Each stray pointer in a package's topics and component docs.
 *
 * @param {{records: {name: string, path: string}[], guides?: {name: string, ref?: {topicFile?: string}}[], namespaces?: {doc?: {name?: string}}[], components?: {name: string, file: string}[]}} discovered
 * @returns {Promise<import('../../api/integration/authoring-checks.type.mjs').StrayPointer[]>}
 */
export async function findStrayPointers(discovered) {
  /** @type {{name: string, file: string | undefined, kind: 'topic' | 'component'}[]} */
  const topics = [
    ...discovered.records.map(record => ({
      name: record.name,
      file: record.path,
      kind: /** @type {const} */ ('topic'),
    })),
    ...(discovered.guides ?? []).map(guide => ({
      name: guide.name,
      file: guide.ref?.topicFile,
      kind: /** @type {const} */ ('topic'),
    })),
  ];
  /** @type {Map<string, string>} */
  const own = new Map(topics.map(topic => [topic.name, 'generic']));
  for (const namespace of discovered.namespaces ?? []) {
    const name = namespace?.doc?.name;
    if (typeof name === 'string' && !own.has(name)) own.set(name, 'namespace');
  }
  for (const component of discovered.components ?? []) {
    topics.push({
      name: component.name,
      file: component.file,
      kind: 'component',
    });
  }
  const core = await loadCoreKinds();
  // A topic that extends another has no route of its own: a link to it names
  // the page it shows on, the topic it extends.
  /** @type {Map<string, string>} */
  const extendsOf = new Map();
  for (const topic of topics) {
    if (!topic.file) continue;
    const doc = /** @type {any} */ (await loadQuietly(topic.file));
    if (typeof doc?.extends === 'string')
      extendsOf.set(topic.name, doc.extends);
  }
  /** @param {string} target */
  const linkFor = target => {
    const page = extendsOf.get(target);
    if (page != null) {
      if (own.has(page) && !extendsOf.has(page)) {
        return `{@link ${own.get(page)}:${page}}`;
      }
      return core.has(page)
        ? `{@link @astryxdesign/cli:${core.get(page)}:${page}}`
        : null;
    }
    return own.has(target)
      ? `{@link ${own.get(target)}:${target}}`
      : core.has(target)
        ? `{@link @astryxdesign/cli:${core.get(target)}:${target}}`
        : null;
  };
  /** @type {import('../../api/integration/authoring-checks.type.mjs').StrayPointer[]} */
  const found = [];
  for (const topic of topics) {
    if (!topic.file) continue;
    const doc = await loadQuietly(topic.file);
    if (!doc) continue;
    /** @type {{word: string, line: number}[]} */
    let source = [];
    /** @type {string[]} */
    let lines = [];
    try {
      const raw = fs.readFileSync(topic.file, 'utf8');
      source = fileWords(raw);
      lines = raw.split('\n');
    } catch {
      // No line numbers; the finding still names the section.
    }
    // A component doc is named by its own name: a family doc by the family.
    const name =
      topic.kind === 'component' && typeof doc.name === 'string'
        ? doc.name
        : topic.name;
    const label =
      topic.kind === 'component' ? `component "${name}"` : `"${name}"`;
    // Each string is found by its whole run of words, from where the last
    // one was found, so two strings that open alike keep their own lines.
    let cursor = 0;
    for (const {text, section, field} of linkableStrings(doc)) {
      const words = textWords(text);
      const index = locateString(lines, source, text, words, cursor);
      if (index >= 0) cursor = index + words.length;
      for (const match of text.matchAll(POINTER)) {
        const target = match[1] ?? match[2];
        const link = linkFor(target);
        if (!link) continue;
        // As written: the bare command, or its `{@command}` token.
        const command =
          match[1] != null
            ? `astryx docs ${target}`
            : match[0].replace(/`/g, '');
        const line =
          index < 0
            ? null
            : lineAtOffset(
                source,
                index,
                words,
                /** @type {number} */ (match.index) + 1,
              );
        const where = [
          section ? `section "${section}"` : null,
          field ? `field ${field}` : null,
          line == null ? null : `line ${line}`,
        ]
          .filter(Boolean)
          .join(', ');
        found.push({
          topic: name,
          kind: topic.kind,
          section,
          field,
          file: topic.file,
          line,
          pointer: command,
          link,
          message:
            `${label}${where ? ` (${where})` : ''} points at a doc with the written command \`${command}\`. ` +
            `Replace \`${command}\`, code ticks included, with ${link}: the CLI prints the command that opens the doc, and doctor checks the link.`,
        });
      }
    }
  }
  return found;
}