Skip to content

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

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

/**
 * @file Tests for the stable error-code contract.
 *
 * Two layers:
 *
 *   1. Unit — the taxonomy itself: every code is a non-empty, unique,
 *      stable string; the object is frozen; helpers behave.
 *
 *   2. End-to-end — spawn the CLI as a subprocess and assert that
 *      representative error paths emit the right `code` in their JSON
 *      envelope. Spawning is the only way to exercise Commander hooks,
 *      the json-shim, and the bin error boundary together.
 */

import {describe, it, expect} from 'vitest';
import * as fs from 'node:fs';
import * as os from 'node:os';
import * as path from 'node:path';
import {ERROR_CODES, isErrorCode, allErrorCodes} from './error-codes.mjs';
import {runCli} from '../../test-utils/run-cli.mjs';

/** Parse the JSON envelope from stdout. Throws if stdout isn't clean JSON. */
function envelope(stdout) {
  return JSON.parse(stdout);
}

describe('error-codes taxonomy', () => {
  it('every code is a non-empty string', () => {
    for (const [key, value] of Object.entries(ERROR_CODES)) {
      expect(typeof value).toBe('string');
      expect(value.length).toBeGreaterThan(0);
      // Key and value must match — the object is a string enum.
      expect(value).toBe(key);
    }
  });

  it('every code follows the ERR_ naming convention', () => {
    for (const value of Object.values(ERROR_CODES)) {
      expect(value).toMatch(/^ERR_[A-Z0-9_]+$/);
    }
  });

  it('all codes are unique', () => {
    const values = Object.values(ERROR_CODES);
    expect(new Set(values).size).toBe(values.length);
  });

  it('includes the generic fallback', () => {
    expect(ERROR_CODES.ERR_UNKNOWN).toBe('ERR_UNKNOWN');
  });

  it('the taxonomy object is frozen (codes are stable, append-only)', () => {
    expect(Object.isFrozen(ERROR_CODES)).toBe(true);
    expect(() => {
      // @ts-expect-error - intentional mutation attempt
      ERROR_CODES.ERR_NEW = 'ERR_NEW';
    }).toThrow();
    expect(ERROR_CODES.ERR_NEW).toBeUndefined();
  });

  it('isErrorCode recognizes known codes and rejects others', () => {
    expect(isErrorCode('ERR_UNKNOWN_COMPONENT')).toBe(true);
    expect(isErrorCode('ERR_UNKNOWN')).toBe(true);
    expect(isErrorCode('ERR_NOT_A_REAL_CODE')).toBe(false);
    expect(isErrorCode('')).toBe(false);
    expect(isErrorCode(42)).toBe(false);
    expect(isErrorCode(undefined)).toBe(false);
  });

  it('allErrorCodes returns the sorted, complete set', () => {
    const codes = allErrorCodes();
    expect(codes.length).toBe(Object.keys(ERROR_CODES).length);
    expect(codes).toEqual([...codes].sort());
    expect(codes).toContain('ERR_UNKNOWN');
    expect(codes).toContain('ERR_UNKNOWN_COMPONENT');
  });
});

describe('error codes: shipped set', () => {
  // Every code a release has published. INV3: a shipped code is never removed
  // or respelled. Add a code here once it ships; never delete an entry.
  const SHIPPED = [
    'ERR_AMBIGUOUS_COMPONENT',
    'ERR_AMBIGUOUS_TEMPLATE',
    'ERR_AMBIGUOUS_THEME',
    'ERR_CODEMOD_FAILED',
    'ERR_CODEMOD_PROTECTED',
    'ERR_CODEMOD_PROTECTION_SOURCE',
    'ERR_CORE_INCOMPATIBLE',
    'ERR_CORE_NOT_FOUND',
    'ERR_DEP_MISSING',
    'ERR_FETCH_FAILED',
    'ERR_FILE_EXISTS',
    'ERR_FILE_NOT_FOUND',
    'ERR_GH_CLI',
    'ERR_INTEGRATION_EXPORT_CONFLICT',
    'ERR_INTEGRATION_ROOT_CONFLICT',
    'ERR_INVALID_ARGUMENT',
    'ERR_INVALID_DETAIL',
    'ERR_INVALID_DOC',
    'ERR_INVALID_LANG',
    'ERR_INVALID_OPTION',
    'ERR_INVALID_VERSION',
    'ERR_LAYOUT_INVALID',
    'ERR_LAYOUT_PARSE',
    'ERR_MISSING_ARGUMENT',
    'ERR_NODE_VERSION',
    'ERR_NOT_FOUND',
    'ERR_NO_DOC',
    'ERR_NO_SHOWCASE',
    'ERR_NO_SOURCE',
    'ERR_PALETTE_GENERATION',
    'ERR_PATH_TRAVERSAL',
    'ERR_PROJECT_REQUIRED',
    'ERR_SIGNAL_TERMINATED',
    'ERR_THEME_INVALID',
    'ERR_THEME_LOAD',
    'ERR_UNCLASSIFIED_EXIT',
    'ERR_UNKNOWN',
    'ERR_UNKNOWN_AGENT',
    'ERR_UNKNOWN_CATEGORY',
    'ERR_UNKNOWN_CODEMOD',
    'ERR_UNKNOWN_COMMAND',
    'ERR_UNKNOWN_COMPONENT',
    'ERR_UNKNOWN_FEATURE',
    'ERR_UNKNOWN_HOOK',
    'ERR_UNKNOWN_PACKAGE',
    'ERR_UNKNOWN_POST',
    'ERR_UNKNOWN_SECTION',
    'ERR_UNKNOWN_SUBCOMMAND',
    'ERR_UNKNOWN_TEMPLATE',
    'ERR_UNKNOWN_THEME',
    'ERR_UNKNOWN_TOPIC',
    'ERR_VERSION_DETECT',
    'ERR_VERSIONS_UNAVAILABLE',
    'ERR_WRITE_FAILED',
  ];

  it('still carries every shipped code, spelled the same', () => {
    const missing = SHIPPED.filter(
      code => !isErrorCode(code) || ERROR_CODES[code] !== code,
    );
    expect(missing, 'shipped codes removed or respelled').toEqual([]);
  });
});

describe('error codes: end-to-end JSON envelopes', () => {
  const cases = [
    {
      name: 'unknown component',
      args: ['component', 'Bogus', '--json'],
      code: 'ERR_UNKNOWN_COMPONENT',
    },
    {
      name: 'unknown hook',
      args: ['hook', 'bogusHook', '--json'],
      code: 'ERR_UNKNOWN_HOOK',
    },
    {
      name: 'unknown topic',
      args: ['docs', 'bogusTopic', '--json'],
      code: 'ERR_UNKNOWN_TOPIC',
    },
    {
      name: 'unknown template',
      args: ['template', 'bogusTemplate', '--json'],
      code: 'ERR_UNKNOWN_TEMPLATE',
    },
    {
      name: 'unknown command',
      args: ['bogus-cmd', '--json'],
      code: 'ERR_UNKNOWN_COMMAND',
    },
    {
      name: 'invalid --lang',
      args: ['docs', 'color', '--lang', 'fr', '--json'],
      code: 'ERR_INVALID_LANG',
    },
    {
      name: 'invalid --detail',
      args: ['docs', 'color', '--detail', 'bogus', '--json'],
      code: 'ERR_INVALID_DETAIL',
    },
    {
      name: 'unknown option',
      args: ['component', 'Button', '--bogus-flag', '--json'],
      code: 'ERR_INVALID_OPTION',
    },
    {
      name: 'missing argument',
      args: ['theme', 'build', '--json'],
      code: 'ERR_MISSING_ARGUMENT',
    },
    // `theme` is not on the --json allowlist, so --json on any theme subcommand
    // is rejected at the preAction gate with a stable invalid-option code.
    {
      name: 'json not supported',
      args: ['theme', '--json'],
      code: 'ERR_INVALID_OPTION',
    },
    // A group given a word it does not have names the unknown subcommand,
    // in JSON as in text.
    {
      name: 'unknown subcommand of a group',
      args: ['theme', 'bogus-sub', '--json'],
      code: 'ERR_UNKNOWN_SUBCOMMAND',
    },
  ];

  for (const {name, args, code} of cases) {
    it(`${name} → ${code}`, async () => {
      const {status, stdout} = await runCli(args);
      expect(status).toBe(1);
      const env = envelope(stdout);
      expect(env).toHaveProperty('apiVersion');
      expect(env).toHaveProperty('error');
      expect(env.code).toBe(code);
      // The code must be a recognized member of the taxonomy.
      expect(isErrorCode(env.code)).toBe(true);
    });
  }

  it('a filesystem failure carries a registered code, never the Node errno', async () => {
    const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-errno-'));
    try {
      // A file where the target directory should be: mkdir fails with ENOTDIR.
      fs.writeFileSync(path.join(dir, 'blocker'), 'x');
      const {status, stdout} = await runCli(
        ['template', 'dashboard', 'blocker/out', '--json'],
        {cwd: dir},
      );
      expect(status).toBe(1);
      const env = envelope(stdout);
      expect(env.error).toMatch(/ENOTDIR/);
      expect(isErrorCode(env.code)).toBe(true);
    } finally {
      fs.rmSync(dir, {recursive: true, force: true});
    }
  });

  it('every error envelope carries a code (even unmatched paths fall back to ERR_UNKNOWN)', async () => {
    const {stdout} = await runCli(['component', 'Bogus', '--json']);
    const env = envelope(stdout);
    expect(typeof env.code).toBe('string');
    expect(env.code.length).toBeGreaterThan(0);
  });
});

describe('error codes: human mode stays clean', () => {
  it('the code is NOT printed in the human-facing error line', async () => {
    const {status, stderr, stdout} = await runCli(['component', 'Bogus']);
    expect(status).toBe(1);
    // Human output goes to stderr and must not leak the machine code.
    expect(stderr).toContain('No component named');
    expect(stderr).not.toContain('ERR_UNKNOWN_COMPONENT');
    expect(stdout).not.toContain('ERR_UNKNOWN_COMPONENT');
  });

  it('refuses --built with a doctor integration check', async () => {
    const json = await runCli(['--json', 'doctor', '--built', 'dist', 'integration', 'validate']);
    expect(json.status).toBe(1);
    expect(JSON.parse(json.stdout)).toMatchObject({code: 'ERR_INVALID_OPTION'});
    const text = await runCli(['doctor', '--built', 'dist', 'integration', 'docs']);
    expect(text.status).toBe(1);
    expect(text.stderr).toContain('goes with `doctor` alone');
  });

  it('unknown subcommand exits 1, with the code in JSON and not in text', async () => {
    // A group that is not JSON-capable itself still answers an unknown
    // subcommand in JSON, so a JSON caller learns the subcommands it has.
    const {status, stderr} = await runCli(['theme', 'bogus-sub']);
    expect(status).toBe(1);
    expect(stderr).toContain("unknown subcommand 'theme bogus-sub'");
    expect(stderr).not.toContain('ERR_UNKNOWN_SUBCOMMAND');
    for (const args of [
      ['--json', 'theme', 'bogus-sub'],
      ['theme', 'bogus-sub', '--json'],
      ['--json', 'doctor', 'integration', 'bogus-sub'],
    ]) {
      const json = await runCli(args);
      expect(json.status, args.join(' ')).toBe(1);
      expect(JSON.parse(json.stdout), args.join(' ')).toMatchObject({
        code: 'ERR_UNKNOWN_SUBCOMMAND',
        suggestions: expect.arrayContaining([expect.objectContaining({reason: 'available subcommand'})]),
      });
    }
    // Text and JSON agree for a group that shows help when run bare.
    const text = await runCli(['doctor', 'integration', 'bogus-sub']);
    expect(text.status).toBe(1);
    expect(text.stderr).toContain("unknown subcommand 'doctor integration bogus-sub'");
    const doctor = await runCli(['doctor', 'integrations']);
    expect(doctor.status).toBe(1);
    expect(doctor.stderr).toContain("unknown subcommand 'doctor integrations'");
  });
});