Skip to content

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

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

/**
 * @file Doc module importers: how the doc reader and discovery execute an
 *   authored doc file.
 *
 * @input An absolute path to a `.doc.{ts,mjs,js}` (or legacy template) file.
 * @output The module's namespace object: the one a plain import of the file
 *   gives, until the file changes; then the edited file's, read once by each
 *   importer, its own way, and shared until the next change. A long-running
 *   process (a docs site's search, an agent harness) thereby sees an edit to
 *   a doc file it already read, as a new process would read it. Only the doc
 *   file's own edits count: a module it imports stays as first loaded.
 * @position Called by ./read.mjs, which hands what comes back to the compiler,
 *   and by discovery, which reads a contributed topic's name and relationships
 *   to build the catalog. Doc files also run outside these importers: each CLI
 *   command imports its own self-docs statically for its help text, and the
 *   README script imports them at build time. ./doc-loads.test.mjs lists, site
 *   by site, every use of these importers and every other place the CLI runs
 *   anything but its static imports of other CLI code (a static doc import is
 *   one); a new site fails it. It catches every ordinary way of running code,
 *   whatever the local names; deliberate obfuscation is out of scope.
 */

import {pathToFileURL} from 'node:url';
import {createJiti} from 'jiti';
import {importUrl} from '../fs/import-url.mjs';
import {
  importUserModule,
  readFreshInTurn,
  readInTurn,
} from '../fs/module-loader.mjs';
import {fileStamp, recordContentRead} from '../fs/read-record.mjs';

/** @type {ReturnType<typeof createJiti> | undefined} */
let jsxJiti;

/**
 * Each doc file imported in this process: its stamp at the last import and,
 * once it changed, the module each importer read for that change.
 * @type {Map<string, {stamp: string, changed: Record<string, Promise<any>> | null}>}
 */
const imported = new Map();

/** Numbers each fresh native import's URL, so it names a new module. */
let changes = 0;

/**
 * Import `file` with `load` until it changes, then once with `loadFresh` for
 * each change, sharing that module until the next one. Each importer (`kind`)
 * keeps its own module, as each has its own loader. The file counts as read
 * by the running operation (see ../fs/read-record.mjs).
 * @param {string} file
 * @param {'doc' | 'template' | 'native'} kind
 * @param {(file: string) => Promise<any>} load
 * @param {(file: string) => Promise<any>} loadFresh
 * @returns {Promise<any>}
 */
function importCurrent(file, kind, load, loadFresh) {
  recordContentRead(file);
  const stamp = fileStamp(file);
  let seen = imported.get(file);
  if (!seen) {
    imported.set(file, {stamp, changed: null});
    return load(file);
  }
  if (seen.stamp !== stamp) {
    seen = {stamp, changed: {}};
    imported.set(file, seen);
  }
  if (!seen.changed) return load(file);
  return (seen.changed[kind] ??= loadFresh(file));
}

/**
 * The file's URL, naming a new module for each change.
 * @param {string} file
 * @returns {string}
 */
function freshUrl(file) {
  const url = pathToFileURL(file);
  url.searchParams.set('astryx-doc', String(++changes));
  return url.href;
}

/**
 * Import `file` from `url`, in its turn with every other read of the file in
 * this process (`readInTurn`, ../fs/module-loader.mjs).
 * @param {string} file
 * @param {string} url
 * @returns {Promise<any>}
 */
function importInTurn(file, url) {
  return readInTurn(file, () => importUrl(url));
}

/**
 * Import `file` again, for a change, as a new module. Node chooses its format
 * as for the first import. The read takes its turn without the file's
 * CommonJS cache entry (`readFreshInTurn`, ../fs/module-loader.mjs).
 * @param {string} file
 * @returns {Promise<any>}
 */
function importFresh(file) {
  return readFreshInTurn(file, () => importUrl(freshUrl(file)));
}

/**
 * Import a component, hook, topic, or self-doc module: `.ts` through jiti,
 * anything else natively.
 * @param {string} file
 * @returns {Promise<any>}
 */
export function importDocModule(file) {
  return importCurrent(file, 'doc', importUserModule, changed =>
    importUserModule(changed, {fresh: true}),
  );
}

/**
 * How core and external template docs have always been imported: `.ts`
 * through a JSX-aware jiti, anything else natively.
 * @param {string} file
 * @returns {Promise<any>}
 */
export function importTemplateModule(file) {
  return importCurrent(
    file,
    'template',
    first => {
      if (first.endsWith('.ts')) {
        jsxJiti ??= createJiti(import.meta.url, {jsx: true});
        return jsxJiti.import(first);
      }
      return importInTurn(first, `file://${first}`);
    },
    changed =>
      changed.endsWith('.ts')
        ? createJiti(import.meta.url, {jsx: true, moduleCache: false}).import(
            changed,
          )
        : importFresh(changed),
  );
}

/**
 * Import a module natively, by file URL: how the docs API, search, and the
 * unchecked component and hook readers have always imported docs. A `.ts`
 * file goes through jiti, as {@link importDocModule} imports it: Node cannot
 * strip types from a file under node_modules, and below 22.18 it does not
 * strip types at all, so a plain import of an installed or linked
 * integration's `.doc.ts` fails.
 * @param {string} file
 * @returns {Promise<any>}
 */
export function importNativeModule(file) {
  if (file.endsWith('.ts')) {
    return importDocModule(file);
  }
  return importCurrent(
    file,
    'native',
    first => importInTurn(first, pathToFileURL(first).href),
    changed => importFresh(changed),
  );
}