Skip to content

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

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

/**
 * @file Every error code each icon API function documents (spec:AST-042 FR2,
 * AST-084): one case per function and code, each asserting the code the
 * function's reference doc lists, and a check that the docs list exactly the
 * codes these cases raise.
 */

import * as fs from 'node:fs';
import * as os from 'node:os';
import * as path from 'node:path';
import {afterEach, beforeEach, describe, expect, it, vi} from 'vitest';
import {
  writeIconPackage,
  writeIconSetProject,
} from '../../test-utils/icon-set-fixture.mjs';

// The manifest's root changes between the dry run and the write when a case
// sets `conflict.root`: the write then meets a root it did not plan for.
const conflict = vi.hoisted(() => ({
  root: /** @type {string | null} */ (null),
}));
vi.mock(
  '../../foundation/integrations/manifest-writer.mjs',
  async importOriginal => {
    const actual =
      /** @type {typeof import('../../foundation/integrations/manifest-writer.mjs')} */ (
        await importOriginal()
      );
    return {
      ...actual,
      /** @type {typeof actual.patchIntegrationRoot} */
      patchIntegrationRoot: async (packageDir, key, rootPath, options) => {
        if (conflict.root && !options?.dryRun) {
          fs.writeFileSync(
            path.join(packageDir, 'astryx.integration.mjs'),
            `export default {experimental: {iconSets: '${conflict.root}'}};\n`,
          );
        }
        return actual.patchIntegrationRoot(packageDir, key, rootPath, options);
      },
    };
  },
);

const {icon} = await import('./icon.mjs');
const {iconAdd} = await import('./add/add.mjs');
const {iconMap} = await import('./map/map.mjs');
const {iconUse} = await import('./use/use.mjs');
const {iconNewSet} = await import('./new-set/new-set.mjs');
const {iconNewDefinition} = await import('./new-definition/new-definition.mjs');

/** @type {string} */
let tmp;
/** @type {string[]} */
let locked;
beforeEach(() => {
  tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-icon-errors-'));
  locked = [];
  conflict.root = null;
});
afterEach(() => {
  for (const dir of locked) fs.chmodSync(dir, 0o755);
  fs.rmSync(tmp, {recursive: true, force: true});
});

/** A fresh folder: no package.json above it and no project. */
function outside() {
  return fs.mkdtempSync(path.join(tmp, 'outside-'));
}

/** The icon-set package `@acme/glyphs`, with its set `glyphs`. */
function pkg() {
  const dir = path.join(fs.mkdtempSync(path.join(tmp, 'pkg-')), 'glyphs');
  writeIconPackage(dir);
  return dir;
}

/** A package with a name and no icon set yet. @returns {string} */
function bare() {
  const dir = fs.mkdtempSync(path.join(tmp, 'bare-'));
  fs.writeFileSync(
    path.join(dir, 'package.json'),
    JSON.stringify({name: '@acme/bare', version: '1.0.0'}),
  );
  return dir;
}

/** @param {Parameters<typeof writeIconSetProject>[1]} [options] */
function app(options) {
  return writeIconSetProject(fs.mkdtempSync(path.join(tmp, 'app-')), options);
}

/** A folder nothing may write into, unlocked after the test. @param {string} dir */
function lock(dir) {
  fs.mkdirSync(dir, {recursive: true});
  fs.chmodSync(dir, 0o555);
  locked.push(dir);
}

/** @param {string} dir @param {string} text */
function manifest(dir, text) {
  fs.writeFileSync(path.join(dir, 'astryx.integration.mjs'), text);
}

/** @param {string} dir */
function withSecondSet(dir) {
  const from = path.join(dir, 'icon-sets', 'glyphs');
  const to = path.join(dir, 'icon-sets', 'extra');
  fs.mkdirSync(to);
  fs.writeFileSync(
    path.join(to, 'extra.doc.mjs'),
    fs
      .readFileSync(path.join(from, 'glyphs.doc.mjs'), 'utf8')
      .replace('"glyphs"', '"extra"'),
  );
  fs.copyFileSync(
    path.join(from, 'glyphs.icons.json'),
    path.join(to, 'extra.icons.json'),
  );
  return dir;
}

const DEFINITION = {description: 'Turn something.', words: ['turn']};

/**
 * Each function's cases, by the code each raises.
 * @type {Record<string, Record<string, () => Promise<unknown>>>}
 */
const CASES = {
  icon: {
    ERR_MISSING_ARGUMENT: () => icon('', {cwd: app()}),
    ERR_INVALID_ARGUMENT: () => icon('close', {cwd: app(), limit: 0}),
    ERR_NOT_FOUND: () => icon('glyphs/nope', {cwd: app()}),
    ERR_INVALID_OPTION: () => icon('close', {cwd: app(), list: true}),
  },
  iconAdd: {
    ERR_INVALID_OPTION: () =>
      iconAdd('XIcon', {cwd: pkg(), from: './icons/x.js', all: true}),
    ERR_PROJECT_REQUIRED: () =>
      iconAdd('XIcon', {cwd: outside(), from: './x.js'}),
    ERR_INVALID_ARGUMENT: () =>
      iconAdd('not a name', {cwd: pkg(), from: './icons/x.js'}),
    ERR_MISSING_ARGUMENT: () =>
      iconAdd('XIcon', /** @type {any} */ ({cwd: pkg()})),
    ERR_NOT_FOUND: () =>
      iconAdd('NopeIcon', {
        cwd: pkg(),
        from: './icons/x.js',
        definition: 'close',
      }),
    ERR_FILE_NOT_FOUND: () =>
      iconAdd('XIcon', {cwd: pkg(), from: './icons/missing.js'}),
    ERR_FILE_EXISTS: () =>
      iconAdd('XIcon', {
        cwd: pkg(),
        from: './icons/x.js',
        definition: 'close',
        id: 'search',
      }),
    ERR_PATH_TRAVERSAL: () =>
      iconAdd('XIcon', {cwd: pkg(), from: '../outside.js'}),
    ERR_WRITE_FAILED: () => {
      const dir = pkg();
      lock(path.join(dir, 'icon-sets', 'glyphs'));
      return iconAdd('XIcon', {
        cwd: dir,
        from: './icons/x.js',
        definition: 'close',
        id: 'x-again',
      });
    },
  },
  iconMap: {
    ERR_PROJECT_REQUIRED: () => iconMap('close', 'x', {cwd: outside()}),
    ERR_INVALID_OPTION: () =>
      iconMap('close', undefined, {cwd: pkg(), pairs: 'close=x'}),
    ERR_MISSING_ARGUMENT: () => iconMap('', 'x', {cwd: pkg()}),
    ERR_INVALID_ARGUMENT: () =>
      iconMap('close', 'x', {cwd: withSecondSet(pkg())}),
    ERR_NOT_FOUND: () => iconMap('notADefinition', 'x', {cwd: pkg()}),
    ERR_PATH_TRAVERSAL: () => {
      const dir = pkg();
      manifest(dir, "export default {experimental: {iconSets: '../out'}};\n");
      return iconMap('close', 'x', {cwd: dir});
    },
    ERR_WRITE_FAILED: () => {
      const dir = pkg();
      lock(path.join(dir, 'icon-sets', 'glyphs'));
      return iconMap('home', 'x', {cwd: dir});
    },
  },
  iconUse: {
    ERR_PROJECT_REQUIRED: () => iconUse('glyphs', {cwd: outside()}),
    ERR_MISSING_ARGUMENT: () => iconUse('', {cwd: app()}),
    ERR_NOT_FOUND: () => iconUse('nope', {cwd: app()}),
    ERR_INVALID_ARGUMENT: () =>
      iconUse('glyphs', {
        cwd: app({packages: [{}, {name: '@acme/lines', set: 'glyphs'}]}),
      }),
    // A config whose default export is not an object literal.
    ERR_WRITE_FAILED: () => {
      const dir = app();
      fs.writeFileSync(
        path.join(dir, 'astryx.config.mjs'),
        'function make() {\n  return {};\n}\nexport default make();\n',
      );
      return iconUse('glyphs', {cwd: dir});
    },
    ERR_CODEMOD_PROTECTED: () => {
      const dir = app();
      fs.writeFileSync(
        path.join(dir, '.gitattributes'),
        'astryx.config.mjs linguist-generated\n',
      );
      return iconUse('glyphs', {cwd: dir});
    },
    // A .gitattributes rule with no attribute cannot be read.
    ERR_CODEMOD_PROTECTION_SOURCE: () => {
      const dir = app();
      fs.writeFileSync(path.join(dir, '.gitattributes'), 'astryx.config.mjs\n');
      return iconUse('glyphs', {cwd: dir});
    },
  },
  iconNewSet: {
    ERR_PROJECT_REQUIRED: () => iconNewSet('outline', {cwd: outside()}),
    ERR_INVALID_ARGUMENT: () => iconNewSet('Outline', {cwd: bare()}),
    ERR_INVALID_OPTION: () =>
      iconNewSet('outline', {cwd: bare(), exclude: 'Meta'}),
    ERR_FILE_EXISTS: async () => {
      const dir = bare();
      await iconNewSet('outline', {cwd: dir});
      return iconNewSet('outline', {cwd: dir});
    },
    ERR_PATH_TRAVERSAL: () => {
      const dir = bare();
      manifest(dir, "export default {experimental: {iconSets: '../x'}};\n");
      return iconNewSet('outline', {cwd: dir});
    },
    // The manifest names another root by the time the set is written.
    ERR_INTEGRATION_ROOT_CONFLICT: () => {
      conflict.root = './elsewhere';
      return iconNewSet('outline', {cwd: bare()});
    },
    ERR_WRITE_FAILED: () => {
      const dir = bare();
      manifest(dir, "export default {experimental: {iconSets: './taken'}};\n");
      fs.writeFileSync(path.join(dir, 'taken'), 'not a directory');
      return iconNewSet('outline', {cwd: dir});
    },
    ERR_NOT_FOUND: () =>
      iconNewSet('outline', {cwd: bare(), from: 'not-installed-library'}),
    ERR_FILE_NOT_FOUND: () =>
      iconNewSet('outline', {cwd: bare(), from: './missing.js'}),
  },
  iconNewDefinition: {
    ERR_PROJECT_REQUIRED: () =>
      iconNewDefinition('random', {cwd: outside(), ...DEFINITION}),
    ERR_INVALID_ARGUMENT: () =>
      iconNewDefinition('Not-Camel', {cwd: pkg(), ...DEFINITION}),
    ERR_MISSING_ARGUMENT: () =>
      iconNewDefinition('random', {cwd: pkg(), words: ['turn']}),
    ERR_FILE_EXISTS: async () => {
      const dir = pkg();
      await iconNewDefinition('random', {cwd: dir, ...DEFINITION});
      return iconNewDefinition('random', {cwd: dir, ...DEFINITION});
    },
    ERR_NOT_FOUND: () =>
      iconNewDefinition('random', {cwd: pkg(), ...DEFINITION, icon: 'nope'}),
    ERR_PATH_TRAVERSAL: () => {
      const dir = pkg();
      manifest(dir, "export default {experimental: {iconSets: '../out'}};\n");
      return iconNewDefinition('random', {cwd: dir, ...DEFINITION});
    },
    ERR_WRITE_FAILED: () => {
      const dir = pkg();
      lock(path.join(dir, 'icon-sets', 'glyphs', 'definitions'));
      return iconNewDefinition('random', {cwd: dir, ...DEFINITION});
    },
  },
};

/** The codes a function's reference doc lists. @param {string} name */
async function documented(name) {
  const {doc} = await import(`./${name}.doc.mjs`);
  return (doc.throws ?? []).map((/** @type {any} */ each) => each.code).sort();
}

describe.each(Object.entries(CASES))('%s', (name, cases) => {
  it('documents exactly the codes it raises', async () => {
    expect(await documented(name)).toEqual(Object.keys(cases).sort());
  });

  it.each(Object.entries(cases))('raises %s', async (code, run) => {
    await expect(run()).rejects.toMatchObject({code});
  });
});

describe('a write that fails leaves the package as it was', () => {
  it('iconNewSet: a root that changes before the write rolls back package.json', async () => {
    const dir = bare();
    const before = fs.readFileSync(path.join(dir, 'package.json'), 'utf8');
    conflict.root = './elsewhere';
    await expect(iconNewSet('outline', {cwd: dir})).rejects.toMatchObject({
      code: 'ERR_INTEGRATION_ROOT_CONFLICT',
    });
    expect(fs.readFileSync(path.join(dir, 'package.json'), 'utf8')).toBe(
      before,
    );
    // No file of the set is left (the shared write transaction keeps the
    // folders it made).
    const left = fs.existsSync(path.join(dir, 'icon-sets'))
      ? fs
          .readdirSync(path.join(dir, 'icon-sets'), {recursive: true})
          .filter(each =>
            fs.statSync(path.join(dir, 'icon-sets', String(each))).isFile(),
          )
      : [];
    expect(left).toEqual([]);
  });
});

describe('iconUse beside a spread', () => {
  it('refuses with ERR_WRITE_FAILED and leaves a config that spreads another object as it was', async () => {
    const dir = app();
    const file = path.join(dir, 'astryx.config.mjs');
    fs.writeFileSync(
      path.join(dir, 'base.mjs'),
      "export default {integrations: ['@acme/glyphs']};\n",
    );
    const before =
      "import base from './base.mjs';\n\nexport default {\n  ...base,\n};\n";
    fs.writeFileSync(file, before);
    await expect(iconUse('glyphs', {cwd: dir})).rejects.toMatchObject({
      code: 'ERR_WRITE_FAILED',
      message: expect.stringContaining('spreads another object'),
    });
    expect(fs.readFileSync(file, 'utf8')).toBe(before);
  });
});