Skip to content

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

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

/**
 * @file Compiler inputs — every authored descriptor a project reads, listed once.
 *
 * @input A loaded Project: the components, hooks, templates, themes, and doc
 *   topics its discovery found, plus the CLI's own self-documentation.
 * @output One {@link DocInput} per descriptor file, in read order, and the
 *   problems found while listing them: a file two roots both claim, or two
 *   files under one input id.
 * @position Between discovery and the doc compiler. Discovery still decides
 *   what each root contributes; this module lists that result in one shape so
 *   the compiler and the completeness check read the same set. Internal to the
 *   CLI: nothing here is a public type, and an input id is not a published
 *   identifier.
 */

import * as fs from 'node:fs';
import * as path from 'node:path';
import {
  CORE_PACKAGE,
  findComponentReadme,
} from '../discovery/component-discovery.mjs';
import {discoverHooks, findHookDoc} from '../discovery/hook-discovery.mjs';
import {themeImportPackage} from '../discovery/theme-discovery.mjs';
import {astryxIconDefinitions} from '../discovery/icon-definition-discovery.mjs';
import {CLI_ROOT, findCoreDir} from '../fs/paths.mjs';
import {packageSource} from './source.mjs';
import {treeDocFiles} from './tree.mjs';

export {packageSource};

/** The package that owns the CLI's own self-documentation. */
const CLI_PACKAGE = '@astryxdesign/cli';

/** Where the CLI keeps self-documentation, relative to its package root. */
export const SELF_DOC_TREES = ['api', 'clients', 'authoring', 'foundation'];

/** Directories that hold test inputs, never shipped descriptors. */
const NON_DESCRIPTOR_DIRS = new Set([
  '__tests__',
  '__fixtures__',
  'fixtures',
  'node_modules',
]);

/**
 * @typedef {'components' | 'hooks' | 'templates' | 'themes' | 'icon-definitions' | 'docs' | 'self-docs' | 'tree'} DocRoot
 */

/**
 * One authored descriptor, as the compiler will read it.
 * @typedef {object} DocInput
 * @property {string} id `owner:root:name`, unique within a project
 * @property {DocRoot} root the kind of root that reads it
 * @property {string} name the name a reader asks for
 * @property {string} owner the package that contributes it, as discovery
 *   reports it
 * @property {string} file absolute path; never leaves the CLI
 * @property {string} source `<package>/<path inside it>` for the file itself:
 *   where it ships, independent of the machine it was found on
 * @property {'base' | 'extension'} [role] for a doc topic: its own file, or an
 *   extension merged onto it
 * @property {false} [listed] a component doc that `component <Name>` reads but
 *   the component list leaves out
 */

/**
 * @typedef {object} DocInputProblem
 * @property {'duplicate_file' | 'duplicate_id'} code
 * @property {string} provider the package of the input that was not added
 * @property {string} source `<package>/<path>` of its file
 * @property {string} message
 */

/**
 * List every descriptor the project reads.
 *
 * @param {import('../config/project.mjs').Project} project
 * @returns {Promise<{inputs: DocInput[], problems: DocInputProblem[]}>}
 */
export async function collectDocInputs(project) {
  const list = new InputList();

  // A component documented as a member of its family's doc (HStack and VStack
  // in Stack's doc) is read through the family's own entry: one descriptor,
  // one reader. Own docs go first so the family keeps its name.
  /** @type {Array<{name: string, package: string, docPath: string}>} */
  const ownDocs = [];
  /** @type {Array<{name: string, package: string, docPath: string}>} */
  const familyDocs = [];
  for (const record of await project.components()) {
    if (record.docPath == null) continue;
    const stem = path
      .basename(record.docPath)
      .replace(/\.doc\.[cm]?[jt]s$/u, '')
      .replace(/^XDS/u, '');
    const entry = {
      name: record.name,
      package: record.package,
      docPath: record.docPath,
    };
    (stem === record.name ? ownDocs : familyDocs).push(entry);
  }
  for (const record of ownDocs) {
    list.add('components', record.name, record.package, record.docPath);
  }
  for (const record of familyDocs) {
    if (list.claims(record.docPath)) continue;
    list.add('components', record.name, record.package, record.docPath);
  }

  const coreDir =
    typeof project.coreDir === 'function'
      ? project.coreDir()
      : findCoreDir(project.cwd);
  if (coreDir != null) {
    for (const name of Object.values(discoverHooks(coreDir)).flat()) {
      const file = findHookDoc(coreDir, name);
      if (file != null) list.add('hooks', name, CORE_PACKAGE, file);
    }
    // `component <Name>` finds a core doc by its file name even when the
    // component list, which needs a same-stem source, leaves it out.
    for (const {name, file} of unlistedCoreComponentDocs(coreDir, list)) {
      list.add('components', name, CORE_PACKAGE, file, undefined, false);
    }
  }

  // A template is looked up by its type and directory name; its display name
  // is only a title, and a showcase can share it with the block it shows.
  for (const template of /** @type {any[]} */ (await project.templates())) {
    list.add(
      'templates',
      `${template.type}/${template.dirName}`,
      template.package ?? CORE_PACKAGE,
      template.docPath,
    );
  }

  for (const theme of await project.themes()) {
    list.add('themes', theme.slug, themeImportPackage(theme), theme.docPath);
  }

  // Icon definitions: Astryx's, then each installed set's own.
  for (const {doc, file} of astryxIconDefinitions().definitions) {
    list.add('icon-definitions', doc.name, CLI_PACKAGE, file);
  }
  for (const set of (await project.iconSets()).sets) {
    for (const {doc, file} of set.definitions) {
      list.add(
        'icon-definitions',
        `${set.name}/${doc.name}`,
        set.package,
        file,
      );
    }
  }

  for (const topic of (await project.docs()).entries()) {
    list.add('docs', topic.name, topic.package, topic.path, 'base');
    for (const extension of topic.extensions) {
      list.add(
        'docs',
        topic.name,
        extension.package,
        extension.path,
        'extension',
      );
    }
  }

  // The docs tree's own files: its namespaces and the guides it places.
  for (const file of treeDocFiles()) {
    list.add('tree', path.basename(file, '.doc.mjs'), CLI_PACKAGE, file);
  }
  for (const file of selfDocFiles()) {
    const name = path
      .relative(CLI_ROOT, file)
      .split(path.sep)
      .join('/')
      .replace(/\.doc\.mjs$/u, '');
    list.add('self-docs', name, CLI_PACKAGE, file);
  }

  return {inputs: list.inputs, problems: list.problems};
}

/**
 * Core component docs outside the component list that `component <Name>`
 * still reads: every core doc, outside the hooks directory, that is not listed
 * yet and that its own file name resolves back to.
 *
 * @param {string} coreDir
 * @param {InputList} list the inputs so far
 * @returns {Array<{name: string, file: string}>}
 */
function unlistedCoreComponentDocs(coreDir, list) {
  const srcDir = path.join(coreDir, 'src');
  const hooksDir = path.join(srcDir, 'hooks');
  /** @type {Array<{name: string, file: string}>} */
  const found = [];
  /** @param {string} dir */
  const walk = dir => {
    const entries = fs
      .readdirSync(dir, {withFileTypes: true})
      .sort((a, b) => a.name.localeCompare(b.name));
    for (const entry of entries) {
      const full = path.join(dir, entry.name);
      if (entry.isDirectory()) {
        if (full !== hooksDir && !NON_DESCRIPTOR_DIRS.has(entry.name)) {
          walk(full);
        }
      } else if (entry.isFile() && entry.name.endsWith('.doc.mjs')) {
        if (list.claims(full)) continue;
        const name = entry.name.slice(0, -'.doc.mjs'.length);
        const resolved = findComponentReadme(coreDir, name);
        if (resolved != null && realPath(resolved) === realPath(full)) {
          found.push({name, file: full});
        }
      }
    }
  };
  if (fs.existsSync(srcDir)) walk(srcDir);
  return found;
}

/**
 * Every self-documentation file the CLI ships, in path order.
 * @returns {string[]} absolute paths
 */
export function selfDocFiles() {
  /** @type {string[]} */
  const files = [];
  /** @param {string} dir */
  const walk = dir => {
    const entries = fs
      .readdirSync(dir, {withFileTypes: true})
      .sort((a, b) => a.name.localeCompare(b.name));
    for (const entry of entries) {
      const full = path.join(dir, entry.name);
      if (entry.isDirectory()) {
        if (!NON_DESCRIPTOR_DIRS.has(entry.name)) walk(full);
      } else if (entry.isFile() && entry.name.endsWith('.doc.mjs')) {
        files.push(full);
      }
    }
  };
  for (const tree of SELF_DOC_TREES) {
    const dir = path.join(CLI_ROOT, tree);
    if (fs.existsSync(dir)) walk(dir);
  }
  return files;
}

/** Collects inputs in read order and records what could not be added. */
class InputList {
  /** @type {DocInput[]} */
  inputs = [];
  /** @type {DocInputProblem[]} */
  problems = [];
  /** @type {Map<string, DocInput>} real path -> the input that claimed it */
  #byFile = new Map();
  /** @type {Map<string, DocInput>} */
  #byId = new Map();

  /**
   * @param {string} file
   * @returns {boolean} whether an input already reads this file
   */
  claims(file) {
    return this.#byFile.has(realPath(file));
  }

  /**
   * @param {DocRoot} root
   * @param {string} name
   * @param {string} owner
   * @param {string} file
   * @param {'base' | 'extension'} [role]
   * @param {false} [listed]
   */
  add(root, name, owner, file, role, listed) {
    const real = realPath(file);
    const claimed = this.#byFile.get(real);
    if (claimed != null) {
      this.problems.push({
        code: 'duplicate_file',
        provider: owner,
        source: packageSource(real),
        message: `${packageSource(real)} is read as ${root} "${name}" and as ${claimed.root} "${claimed.name}"; one descriptor must have one reader.`,
      });
      return;
    }
    // An extension is named by its file too: one package may extend a topic
    // from more than one file.
    const id =
      role === 'extension'
        ? `${owner}:${root}:${name}+${path.basename(file).replace(/\.doc\.[cm]?[jt]s$/u, '')}`
        : `${owner}:${root}:${name}`;
    const taken = this.#byId.get(id);
    if (taken != null) {
      this.problems.push({
        code: 'duplicate_id',
        provider: owner,
        source: packageSource(real),
        message: `${packageSource(real)} and ${taken.source} both read as ${root} "${name}" from ${owner}.`,
      });
      return;
    }
    /** @type {DocInput} */
    const input = {
      id,
      root,
      name,
      owner,
      file: real,
      source: packageSource(real),
      ...(role == null ? {} : {role}),
      ...(listed === false ? {listed} : {}),
    };
    this.#byFile.set(real, input);
    this.#byId.set(id, input);
    this.inputs.push(input);
  }
}

/** @param {string} file */
function realPath(file) {
  try {
    return fs.realpathSync(file);
  } catch {
    return path.resolve(file);
  }
}