Skip to content

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

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

/**
 * @file Every pair of options an icon command declares has a decided result
 * (spec:AST-042 FR5): for each command, the pairs come from its CommandDoc
 * (its options and its optional arguments; a required argument is always
 * given), and each pair is either
 *   - refused together with `ERR_INVALID_OPTION` (the `refused` table), or
 *   - composed: the call succeeds with both (the `composes` table), or
 *   - prevented by another rule: the call fails with another code the
 *     function documents (every other pair).
 * A pair that succeeds without being listed as composing fails this test, so
 * a new option, or a change that starts ignoring one, is decided in review.
 */

import * as fs from 'node:fs';
import * as os from 'node:os';
import * as path from 'node:path';
import {afterAll, beforeAll, describe, expect, it} from 'vitest';
import {writeIconSetProject} from '../../test-utils/icon-set-fixture.mjs';
import {runFolder} from '../../test-utils/global-local-fixtures.mjs';
import {icon} from './icon.mjs';
import {iconAdd} from './add/add.mjs';
import {iconMap} from './map/map.mjs';
import {iconNewSet} from './new-set/new-set.mjs';
import {iconNewDefinition} from './new-definition/new-definition.mjs';
import {iconUse} from './use/use.mjs';
import {doc as iconCommand} from '../../clients/cli/commands/experimental-icon.doc.mjs';
import {doc as addCommand} from '../../clients/cli/commands/experimental-icon-add.doc.mjs';
import {doc as mapCommand} from '../../clients/cli/commands/experimental-icon-map.doc.mjs';
import {doc as newSetCommand} from '../../clients/cli/commands/experimental-icon-new-set.doc.mjs';
import {doc as newDefinitionCommand} from '../../clients/cli/commands/experimental-icon-new-definition.doc.mjs';
import {doc as useCommand} from '../../clients/cli/commands/experimental-icon-use.doc.mjs';
import {doc as iconFn} from './icon.doc.mjs';
import {doc as addFn} from './iconAdd.doc.mjs';
import {doc as mapFn} from './iconMap.doc.mjs';
import {doc as newSetFn} from './iconNewSet.doc.mjs';
import {doc as newDefinitionFn} from './iconNewDefinition.doc.mjs';
import {doc as useFn} from './iconUse.doc.mjs';

/** @type {string} */
let tmp;
beforeAll(() => {
  // In a run's folder, the node project's global teardown removes every
  // package the pairs made with the run's other fixtures.
  tmp = fs.mkdtempSync(
    path.join(runFolder() ?? os.tmpdir(), 'astryx-icon-pairs-'),
  );
});
afterAll(() => {
  if (!runFolder()) fs.rmSync(tmp, {recursive: true, force: true});
});

const FROM = '@acme/glyph-library';

/**
 * An icon-set package `@acme/icons` with an installed library, and, unless
 * `bare`, its set `glyphs` made from that library with two variants.
 * @param {{bare?: boolean}} [options]
 * @returns {Promise<string>}
 */
async function makePackage({bare = false} = {}) {
  const dir = fs.mkdtempSync(path.join(tmp, 'pkg-'));
  fs.writeFileSync(
    path.join(dir, 'package.json'),
    `${JSON.stringify({name: '@acme/icons', version: '1.0.0', license: 'MIT', type: 'module'}, null, 2)}\n`,
  );
  const lib = path.join(dir, 'node_modules', '@acme', 'glyph-library');
  fs.mkdirSync(lib, {recursive: true});
  fs.writeFileSync(
    path.join(lib, 'package.json'),
    JSON.stringify({
      name: '@acme/glyph-library',
      version: '2.0.0',
      type: 'module',
      exports: {'.': './index.js', './solid': './solid.js'},
    }),
  );
  const icons =
    'export const Bin = props => null;\nexport const Close = props => null;\n';
  fs.writeFileSync(path.join(lib, 'index.js'), icons);
  fs.writeFileSync(path.join(lib, 'solid.js'), icons);
  if (!bare) {
    await iconNewSet('glyphs', {
      cwd: dir,
      from: FROM,
      variants: 'outline,solid',
    });
  }
  return dir;
}

/**
 * @typedef {object} Case
 * @property {any} command the CommandDoc
 * @property {any} fn the FunctionDoc
 * @property {(...args: any[]) => Promise<unknown>} call
 * @property {() => Promise<string>} cwd a fresh folder for one call
 * @property {Record<string, unknown>} values a value for each API parameter
 * @property {Array<[string, string]>} refused pairs refused together
 * @property {Array<[string, string]>} composes pairs that succeed together
 */

/** @type {Record<string, Case>} */
const CASES = {
  'experimental icon': {
    command: iconCommand,
    fn: iconFn,
    call: icon,
    cwd: async () =>
      writeIconSetProject(fs.mkdtempSync(path.join(tmp, 'app-'))),
    values: {
      query: 'trash',
      'options.list': true,
      'options.set': 'glyphs',
      'options.limit': 3,
      'options.definitions': true,
      'options.allIcons': true,
    },
    refused: [
      ['query', '--list'],
      ['query', '--definitions'],
      ['query', '--all-icons'],
      ['--list', '--set'],
      ['--list', '--limit'],
      ['--list', '--definitions'],
      ['--list', '--all-icons'],
      ['--set', '--definitions'],
      ['--limit', '--definitions'],
      ['--limit', '--all-icons'],
      ['--definitions', '--all-icons'],
    ],
    composes: [
      ['query', '--set'],
      ['query', '--limit'],
      ['--set', '--all-icons'],
    ],
  },
  'experimental icon add': {
    command: addCommand,
    fn: addFn,
    call: iconAdd,
    cwd: () => makePackage(),
    values: {
      exportName: 'Bin',
      'options.from': FROM,
      'options.definition': 'delete',
      'options.newDefinition': 'binIt',
      'options.description': 'Put something in the bin.',
      'options.words': ['bin'],
      'options.useDefault': true,
      'options.variant': 'solid',
      'options.all': true,
      'options.id': 'bin',
      'options.set': 'glyphs',
    },
    refused: [
      ['export', '--all'],
      ['--definition', '--new-definition'],
      ['--definition', '--description'],
      ['--definition', '--words'],
      ['--definition', '--all'],
      ['--new-definition', '--all'],
      ['--description', '--all'],
      ['--words', '--all'],
      ['--default', '--all'],
      ['--all', '--id'],
      // A description and words describe only a new definition.
      ['export', '--description'],
      ['export', '--words'],
      ['--from', '--description'],
      ['--from', '--words'],
      ['--description', '--words'],
      ['--description', '--default'],
      ['--description', '--variant'],
      ['--description', '--id'],
      ['--description', '--set'],
      ['--words', '--default'],
      ['--words', '--variant'],
      ['--words', '--id'],
      ['--words', '--set'],
    ],
    composes: [['export', '--from']],
  },
  'experimental icon map': {
    command: mapCommand,
    fn: mapFn,
    call: iconMap,
    cwd: () => makePackage(),
    values: {
      definition: 'delete',
      icon: 'bin',
      'options.set': 'glyphs',
      'options.remove': true,
      'options.pairs': 'close=close',
    },
    refused: [
      ['definition', '--pairs'],
      ['icon', '--remove'],
      ['icon', '--pairs'],
      ['--remove', '--pairs'],
    ],
    composes: [
      ['definition', 'icon'],
      ['definition', '--remove'],
      ['--set', '--pairs'],
    ],
  },
  'experimental icon new-set': {
    command: newSetCommand,
    fn: newSetFn,
    call: iconNewSet,
    cwd: () => makePackage({bare: true}),
    values: {
      name: 'glyphs',
      'options.dryRun': true,
      'options.from': FROM,
      'options.exclude': 'Close',
      'options.variants': 'outline,solid',
      'options.defaultVariant': 'solid',
      'options.displayName': 'Glyphs',
      'options.description': 'Glyph icons.',
    },
    refused: [
      // `--exclude` needs `--from`, `--default-variant` needs `--variants`.
      ['--dry-run', '--exclude'],
      ['--dry-run', '--default-variant'],
      ['--exclude', '--variants'],
      ['--exclude', '--default-variant'],
      ['--exclude', '--display-name'],
      ['--exclude', '--description'],
      ['--from', '--default-variant'],
      ['--default-variant', '--display-name'],
      ['--default-variant', '--description'],
    ],
    composes: [
      ['--dry-run', '--from'],
      ['--dry-run', '--variants'],
      ['--dry-run', '--display-name'],
      ['--dry-run', '--description'],
      ['--from', '--exclude'],
      ['--from', '--variants'],
      ['--from', '--display-name'],
      ['--from', '--description'],
      ['--variants', '--default-variant'],
      ['--variants', '--display-name'],
      ['--variants', '--description'],
      ['--display-name', '--description'],
    ],
  },
  'experimental icon new-definition': {
    command: newDefinitionCommand,
    fn: newDefinitionFn,
    call: iconNewDefinition,
    cwd: () => makePackage(),
    values: {
      name: 'binIt',
      'options.dryRun': true,
      'options.set': 'glyphs',
      'options.description': 'Put something in the bin.',
      'options.words': ['bin'],
      'options.icon': 'bin',
    },
    refused: [],
    composes: [['--description', '--words']],
  },
  'experimental icon use': {
    command: useCommand,
    fn: useFn,
    call: iconUse,
    cwd: async () =>
      writeIconSetProject(fs.mkdtempSync(path.join(tmp, 'app-'))),
    values: {set: 'glyphs'},
    refused: [],
    composes: [],
  },
};

/**
 * The pair members a command declares: its optional arguments, by name, and
 * its options, by long flag; each with the API parameter it sets.
 * @param {any} command
 * @returns {Array<{label: string, param: string}>}
 */
function members(command) {
  return [
    ...(command.args ?? [])
      .filter((/** @type {any} */ arg) => arg.required !== true)
      .map((/** @type {any} */ arg) => ({label: arg.name, param: arg.param})),
    ...(command.options ?? []).map((/** @type {any} */ option) => ({
      label: option.flag.split(/[\s,]/u)[0],
      param: option.param,
    })),
  ];
}

/** @param {[string, string]} pair */
const key = ([a, b]) => [a, b].sort().join(' + ');

describe.each(Object.entries(CASES))('%s', (_name, spec) => {
  const declared = members(spec.command);
  const labels = declared.map(each => each.label);
  /** @type {Array<[string, string]>} */
  const pairs = [];
  for (let i = 0; i < declared.length; i++) {
    for (let j = i + 1; j < declared.length; j++) {
      pairs.push([declared[i].label, declared[j].label]);
    }
  }
  const refused = new Set(spec.refused.map(key));
  const composes = new Set(spec.composes.map(key));
  const documented = new Set(
    (spec.fn.throws ?? []).map((/** @type {any} */ each) => each.code),
  );

  it('names only pairs the command declares, each in one table', () => {
    for (const pair of [...spec.refused, ...spec.composes]) {
      expect(labels, key(pair)).toEqual(expect.arrayContaining(pair));
    }
    expect([...refused].filter(each => composes.has(each))).toEqual([]);
    for (const {param} of declared) {
      expect(Object.keys(spec.values), param).toContain(param);
    }
  });

  if (pairs.length === 0) return;
  it.each(pairs)('%s with %s', async (a, b) => {
    const given = new Set([a, b]);
    const cwd = await spec.cwd();
    // Required arguments are always given, in order; the rest only when
    // they are one of the pair.
    const args = (spec.command.args ?? []).map((/** @type {any} */ arg) =>
      arg.required === true || given.has(arg.name)
        ? spec.values[arg.param]
        : undefined,
    );
    /** @type {Record<string, unknown>} */
    const options = {cwd};
    for (const {label, param} of declared) {
      if (given.has(label) && param.startsWith('options.')) {
        options[param.slice('options.'.length)] = spec.values[param];
      }
    }
    /** @type {any} */
    let error = null;
    try {
      await spec.call(...args, options);
    } catch (thrown) {
      error = thrown;
    }
    const pair = key([a, b]);
    if (refused.has(pair)) {
      expect(error?.code, `${pair}: ${error?.message}`).toBe(
        'ERR_INVALID_OPTION',
      );
    } else if (composes.has(pair)) {
      expect(error, `${pair}: ${error?.message}`).toBeNull();
    } else {
      // Prevented by another rule: a documented code, never a silent
      // success and never an unknown error.
      expect(
        error,
        `${pair} succeeded but is not listed as composing`,
      ).not.toBeNull();
      expect(error.code, `${pair}: ${error.message}`).not.toBe(
        'ERR_INVALID_OPTION',
      );
      expect([...documented], `${pair}: ${error.message}`).toContain(
        error.code,
      );
    }
  });
});