Skip to content

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

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

/**
 * @file Unit + subprocess tests for the "JSON is always JSON" contract.
 *
 * Guarantees under test:
 *   1. Every JSON envelope carries apiVersion (success and error).
 *   2. humanLog/humanWarn are suppressed in JSON mode (stdout discipline).
 *   3. jsonOut supports optional meta as a sibling of data.
 *   4. An uncaught throw in --json mode becomes a JSON error envelope
 *      (the bin error boundary), never a raw stack trace.
 */

import {describe, it, expect, beforeEach, afterEach, vi} from 'vitest';
import {spawnSync} from 'node:child_process';
import * as fs from 'node:fs';
import * as os from 'node:os';
import * as path from 'node:path';
import {fileURLToPath} from 'node:url';
import {
  API_VERSION,
  jsonOut,
  jsonError,
  toErrorEnvelope,
  setJsonMode,
  isJsonMode,
  humanLog,
  humanWarn,
} from './json.mjs';

const __dirname = path.dirname(fileURLToPath(import.meta.url));
const CLI = path.resolve(
  __dirname,
  '..',
  '..',
  'clients',
  'cli',
  'bin',
  'astryx.mjs',
);

/** @param {string[]} args @param {{cwd?: string}} [options] */
function runCli(args, {cwd = process.cwd()} = {}) {
  return spawnSync(process.execPath, [CLI, ...args], {
    cwd,
    encoding: 'utf8',
    timeout: 20_000,
    stdio: ['ignore', 'pipe', 'pipe'],
    env: {...process.env, FORCE_COLOR: '0', CI: ''},
  });
}

describe('json envelope shape', () => {
  let logs;
  beforeEach(() => {
    logs = [];
    vi.spyOn(console, 'log').mockImplementation((...a) =>
      logs.push(a.join(' ')),
    );
    setJsonMode(false);
  });
  afterEach(() => {
    vi.restoreAllMocks();
    setJsonMode(false);
  });

  it('jsonOut stamps apiVersion + type + data', () => {
    jsonOut({type: 'docs.list', data: [{name: 'Button'}]});
    const env = JSON.parse(logs[0]);
    expect(env.apiVersion).toBe(API_VERSION);
    expect(env.type).toBe('docs.list');
    expect(env.data).toEqual([{name: 'Button'}]);
    // The only meta every result carries names who answered (AST-081 FR5).
    expect(Object.keys(env.meta)).toEqual(['answeredBy']);
    const {cli, core, copy} = env.meta.answeredBy;
    expect(typeof cli).toBe('string');
    expect(core === null || typeof core === 'string').toBe(true);
    expect(['project', 'matched', 'carried']).toContain(copy);
  });

  it('jsonOut attaches optional meta as a sibling of data', () => {
    jsonOut({type: 'discover.list', data: [], meta: {configured: false}});
    const env = JSON.parse(logs[0]);
    expect(env.meta).toEqual({configured: false, answeredBy: expect.any(Object)});
    expect(env.data).toEqual([]);
  });

  it('toErrorEnvelope produces { apiVersion, error, code } from string or Error', () => {
    expect(toErrorEnvelope('boom')).toEqual({
      apiVersion: API_VERSION,
      error: 'boom',
      code: 'ERR_UNKNOWN',
    });
    expect(toErrorEnvelope(new Error('kaboom'))).toEqual({
      apiVersion: API_VERSION,
      error: 'kaboom',
      code: 'ERR_UNKNOWN',
    });
  });

  it('toErrorEnvelope honors an explicit code argument', () => {
    expect(toErrorEnvelope('boom', undefined, 'ERR_UNKNOWN_COMPONENT')).toEqual(
      {
        apiVersion: API_VERSION,
        error: 'boom',
        code: 'ERR_UNKNOWN_COMPONENT',
      },
    );
  });

  it('toErrorEnvelope reads a code carried on a thrown Error', () => {
    const err = Object.assign(new Error('kaboom'), {code: 'ERR_NO_DOC'});
    expect(toErrorEnvelope(err)).toEqual({
      apiVersion: API_VERSION,
      error: 'kaboom',
      code: 'ERR_NO_DOC',
    });
  });

  it('toErrorEnvelope never emits an unregistered code', () => {
    // A Node system error carries `code: 'EACCES'`; that is not an Astryx code.
    const sysErr = Object.assign(new Error('EACCES: permission denied'), {
      code: 'EACCES',
    });
    expect(toErrorEnvelope(sysErr).code).toBe('ERR_UNKNOWN');
    expect(toErrorEnvelope('boom', undefined, 'ENOENT').code).toBe('ERR_UNKNOWN');
    const docErr = Object.assign(new Error('no doc'), {code: 'ERR_NO_DOC'});
    expect(toErrorEnvelope(docErr, undefined, 'ENOENT').code).toBe('ERR_NO_DOC');
  });

  it('toErrorEnvelope includes suggestions when present', () => {
    const env = toErrorEnvelope('x', [{name: 'Button', reason: 'close match'}]);
    expect(env.suggestions).toEqual([{name: 'Button', reason: 'close match'}]);
  });

  it('toErrorEnvelope omits suggestions for an empty array', () => {
    expect('suggestions' in toErrorEnvelope('x', [])).toBe(false);
  });

  it('toErrorEnvelope drops non-array suggestions (only a real Suggestion[] is attached)', () => {
    // The guard is `Array.isArray(...) && .length`, not a bare `?.length` — a
    // string ("hello".length === 5) or a `{length: n}` object must NOT slip
    // through as `suggestions`, which is contractually a Suggestion[].
    expect(
      'suggestions' in toErrorEnvelope('x', /** @type {any} */ ('hello')),
    ).toBe(false);
    expect(
      'suggestions' in toErrorEnvelope('x', /** @type {any} */ ({length: 3})),
    ).toBe(false);
  });
});

describe('stdout discipline (humanLog / humanWarn)', () => {
  let logs, errs;
  beforeEach(() => {
    logs = [];
    errs = [];
    vi.spyOn(console, 'log').mockImplementation((...a) =>
      logs.push(a.join(' ')),
    );
    vi.spyOn(console, 'error').mockImplementation((...a) =>
      errs.push(a.join(' ')),
    );
  });
  afterEach(() => {
    vi.restoreAllMocks();
    setJsonMode(false);
  });

  it('humanLog prints when NOT in json mode', () => {
    setJsonMode(false);
    expect(isJsonMode()).toBe(false);
    humanLog('hello');
    expect(logs).toEqual(['hello']);
  });

  it('humanLog is a no-op in json mode', () => {
    setJsonMode(true);
    expect(isJsonMode()).toBe(true);
    humanLog('should not appear');
    expect(logs).toEqual([]);
  });

  it('humanWarn is a no-op in json mode', () => {
    setJsonMode(true);
    humanWarn('warning');
    expect(errs).toEqual([]);
  });
});

describe('contract: every --json emission is valid JSON with apiVersion', () => {
  it('astryx --version --json', () => {
    const r = runCli(['--version', '--json']);
    const env = JSON.parse(r.stdout);
    expect(env.apiVersion).toBe(API_VERSION);
    expect(env.type).toBe('version');
  });

  it('astryx --json (bare) help envelope', () => {
    const r = runCli(['--json']);
    const env = JSON.parse(r.stdout);
    expect(env.apiVersion).toBe(API_VERSION);
    expect(env.type).toBe('help');
  });

  it('unsupported command error envelope carries apiVersion', () => {
    // `theme` is a command group with no output of its own, so it stays off
    // the --json allowlist. (`init` used to be the example here until it grew
    // a receipt of its own.)
    const r = runCli(['theme', '--json']);
    const env = JSON.parse(r.stdout);
    expect(env.apiVersion).toBe(API_VERSION);
    expect(env.error).toMatch(/theme/);
  });

  it('init emits its install receipt', () => {
    const cwd = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-json-contract-'));
    try {
      const r = runCli(['init', '--json'], {cwd});
      const env = JSON.parse(r.stdout);
      expect(env.apiVersion).toBe(API_VERSION);
      expect(env.type).toBe('init.run');
    } finally {
      fs.rmSync(cwd, {recursive: true, force: true});
    }
  });

  it('supported command (discover) emits clean JSON, no human chatter leak', () => {
    const r = runCli(['discover', '--json']);
    // Whole stdout must parse — nothing printed before/after the envelope.
    const env = JSON.parse(r.stdout);
    expect(env.apiVersion).toBe(API_VERSION);
    expect(env.type).toBe('discover.list');
  });
});