Skip to content

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

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

/**
 * @file Every doc whose behavior changes in global mode says so (spec
 * AST-081). Global mode changes behavior in ways a reader cannot guess from
 * one page: a command that does something else outside a project, or an
 * integration that applies only outside projects when installed for the
 * computer. Each such doc carries one note in a single shared form, a prose
 * block that starts with `In global mode:` and links the global guide with
 * `{@link namespace:global}`, so a reader of any of them finds the guide.
 *
 * - Every command doc whose `outsideProject` is not `same` carries one.
 * - So does every authoring doc on integration manifests and their
 *   contributions: the integration guides' namespaces, the guides placed
 *   under them, and the manifest and discover-source schema docs.
 * - So does every API function doc whose result depends on whether `cwd` is
 *   inside a project or on the integrations installed for the computer, in
 *   its description (function docs have no notes field).
 */

import * as fs from 'node:fs';
import * as path from 'node:path';
import {fileURLToPath, pathToFileURL} from 'node:url';
import {describe, expect, it} from 'vitest';

const CLI = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
const NOTE = /^In global mode: [\s\S]*\{@link namespace:global\}/;

/**
 * Every prose text in a doc, wherever it sits.
 * @param {unknown} value
 * @param {string[]} [out]
 * @returns {string[]}
 */
function proseTexts(value, out = []) {
  if (Array.isArray(value)) {
    for (const item of value) proseTexts(item, out);
  } else if (value && typeof value === 'object') {
    const block = /** @type {Record<string, unknown>} */ (value);
    if (block.type === 'prose' && typeof block.text === 'string') {
      out.push(block.text);
    }
    for (const child of Object.values(block)) proseTexts(child, out);
  }
  return out;
}

/** @param {unknown} doc */
const hasNote = doc => proseTexts(doc).some(text => NOTE.test(text));

/**
 * @param {string} file
 * @returns {Promise<any>}
 */
async function load(file) {
  const mod = await import(pathToFileURL(file).href);
  return mod.doc ?? mod.docs;
}

/**
 * Guides under those namespaces about how to write one item's content, whose
 * behavior global mode never changes. Every other guide there carries the
 * note.
 */
const WRITING_DETAIL_GUIDES = new Set([
  'check-your-docs',
  'define-the-theme',
  'document-the-theme',
  'fonts-and-assets',
  'generate-a-palette',
  'links',
  'sections-and-placement',
  'short-and-findable',
]);

/** The namespaces whose guides are about integration manifests and what they add. */
const AUTHORING_NAMESPACES = [
  'integrations',
  'building-blocks',
  'configuration',
  'components',
  'templates',
  'docs',
  'themes',
];

describe('global mode notes', () => {
  it('every command doc that does not answer outside a project as in a new one carries the note', async () => {
    const dir = path.join(CLI, 'clients/cli/commands');
    const missing = [];
    let checked = 0;
    for (const name of fs.readdirSync(dir).sort()) {
      if (!name.endsWith('.doc.mjs')) continue;
      const doc = await load(path.join(dir, name));
      if (!doc?.outsideProject || doc.outsideProject === 'same') continue;
      checked++;
      if (!hasNote(doc.notes)) missing.push(doc.name);
    }
    expect(checked).toBeGreaterThan(5);
    expect(missing).toEqual([]);
  });

  it('every authoring doc on integration manifests and contributions carries the note', async () => {
    const tree = path.join(CLI, 'assets/docs/tree');
    /** @type {Array<{file: string, doc: any}>} */
    const docs = [];
    for (const name of fs.readdirSync(tree).sort()) {
      if (!name.endsWith('.doc.mjs')) continue;
      docs.push({file: name, doc: await load(path.join(tree, name))});
    }
    const parents = new Set(AUTHORING_NAMESPACES.map(n => `namespace:${n}`));
    const authoring = docs.filter(
      ({doc}) =>
        (doc.type === 'namespace' && AUTHORING_NAMESPACES.includes(doc.name)) ||
        (doc.type === 'generic' &&
          parents.has(doc.placement?.parent) &&
          doc.name !== 'global-integrations' &&
          !WRITING_DETAIL_GUIDES.has(doc.name)),
    );
    for (const file of [
      'authoring/integration/integration.doc.mjs',
      'authoring/discover/discover.doc.mjs',
    ]) {
      authoring.push({file, doc: await load(path.join(CLI, file))});
    }
    expect(authoring.length).toBeGreaterThan(10);
    expect(
      authoring.filter(({doc}) => !hasNote(doc)).map(({file}) => file),
    ).toEqual([]);
  });

  it('every API function doc whose result depends on global mode carries the note in its description', async () => {
    const missing = [];
    for (const name of [
      'component',
      'discover',
      'docs',
      'doctor',
      'init',
      'search',
      'upgrade',
    ]) {
      const doc = await load(path.join(CLI, 'api', name, `${name}.doc.mjs`));
      const at = doc.description?.indexOf('In global mode: ') ?? -1;
      if (at < 0 || !NOTE.test(doc.description.slice(at))) missing.push(name);
    }
    expect(missing).toEqual([]);
  });

  it('the global guide links down to every child and each child links back up', async () => {
    const tree = path.join(CLI, 'assets/docs/tree');
    const global = await load(path.join(tree, 'global.doc.mjs'));
    const text =
      proseTexts(global.blocks).join('\n') + JSON.stringify(global.blocks);
    const children = [];
    for (const name of fs.readdirSync(tree).sort()) {
      if (!name.endsWith('.doc.mjs')) continue;
      const doc = await load(path.join(tree, name));
      if (doc.placement?.parent === 'namespace:global') children.push(doc);
    }
    expect(children.map(c => c.name).sort()).toEqual([
      'ci-and-containers',
      'computer-agent-guide',
      'computer-integrations',
      'install-once',
      'monorepos',
      'problems',
      'project-global-or-both',
      'reference',
      'uninstall',
      'updates',
      'who-answers',
    ]);
    for (const child of children) {
      expect(text, child.name).toContain(`{@link generic:${child.name}}`);
      expect(
        proseTexts(child).some(t => t.includes('{@link namespace:global}')),
        child.name,
      ).toBe(true);
    }
  });
});