Skip to content

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

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

/**
 * @file The README's hand-written envelope shapes and `search` flags match the
 * CLI. The generated tables are covered by readme-gen.test.mjs.
 */

import * as fs from 'node:fs';
import * as os from 'node:os';
import * as path from 'node:path';
import {fileURLToPath} from 'node:url';
import {afterAll, beforeAll, describe, it, expect} from 'vitest';
import {JSON_SUPPORTED} from '../clients/cli/index.mjs';
import {program} from '../clients/cli/program.mjs';
import {buildManifest} from '../clients/cli/lib/manifest.mjs';
import {runCli} from '../test-utils/run-cli.mjs';

/**
 * Every temporary folder these tests make lives here, removed once they
 * finish. It is made in beforeAll, not when the module loads: Vitest skips
 * both hooks when a run filters out every test here.
 */
let TEMP_ROOT = '';
beforeAll(() => {
  TEMP_ROOT = fs.mkdtempSync(
    path.join(os.tmpdir(), 'astryx-readme-prose-test-'),
  );
});
afterAll(() => {
  fs.rmSync(TEMP_ROOT, {recursive: true, force: true});
});

const README = fs
  .readFileSync(path.join(path.dirname(fileURLToPath(import.meta.url)), '../README.md'), 'utf8')
  .replace(/<!-- BEGIN GENERATED: (\S+) -->[\s\S]*?<!-- END GENERATED: \1 -->/g, '');

/**
 * INV2: success is {apiVersion, type, data} + package?, meta? (INV28 adds
 * `package` for a result about one artifact); failure is
 * {apiVersion, error, code} + suggestions?.
 */
const SHAPES = {
  success: {required: ['apiVersion', 'type', 'data'], optional: ['package', 'meta']},
  failure: {required: ['apiVersion', 'error', 'code'], optional: ['suggestions']},
};

/** Every balanced `{...}` group in `text`. @param {string} text */
function braceGroups(text) {
  const groups = [];
  const open = [];
  for (let i = 0; i < text.length; i++) {
    if (text[i] === '{') open.push(i);
    else if (text[i] === '}' && open.length > 0) groups.push(text.slice(open.pop(), i + 1));
  }
  return groups;
}

/**
 * Top-level keys of an object literal or shape: `{ a, b?: x, "c": {...} }`.
 * @param {string} group
 */
function topLevelKeys(group) {
  const keys = [];
  let depth = 0;
  let quote = '';
  let entry = '';
  const flush = () => {
    const m = /^\s*["']?([A-Za-z_$][\w$]*)["']?\??\s*(?::|$)/.exec(entry);
    if (m) keys.push(m[1]);
    entry = '';
  };
  const body = group.slice(1, -1);
  for (let i = 0; i < body.length; i++) {
    const ch = body[i];
    if (quote) {
      entry += ch;
      if (ch === '\\') entry += body[++i] ?? '';
      else if (ch === quote) quote = '';
    } else if (ch === '"' || ch === "'") {
      quote = ch;
      entry += ch;
    } else if ('{[('.includes(ch)) {
      depth++;
      entry += ch;
    } else if ('}])'.includes(ch)) {
      depth--;
      entry += ch;
    } else if (ch === ',' && depth === 0) {
      flush();
    } else {
      entry += ch;
    }
  }
  flush();
  return keys;
}

/** The README's envelope shapes: groups keyed like a success or a failure. */
function readmeEnvelopes() {
  return braceGroups(README)
    .map((group) => ({group, keys: topLevelKeys(group)}))
    .flatMap(({group, keys}) => {
      if (keys.includes('error')) return [{group, keys, kind: 'failure'}];
      if (keys.includes('type') && keys.includes('data')) return [{group, keys, kind: 'success'}];
      return [];
    });
}

describe('README envelope shapes', () => {
  it('finds the hand-written envelopes', () => {
    const kinds = readmeEnvelopes().map((e) => e.kind);
    expect(kinds.filter((k) => k === 'success').length).toBeGreaterThanOrEqual(4);
    expect(kinds.filter((k) => k === 'failure').length).toBeGreaterThanOrEqual(2);
  });

  it('real envelopes carry exactly the documented keys', async () => {
    const cwd = fs.mkdtempSync(path.join(TEMP_ROOT, 'astryx-readme-'));
    const success = JSON.parse((await runCli(['--json', 'docs'], {cwd})).stdout);
    const failure = JSON.parse((await runCli(['--json', 'docs', 'no-such-topic'], {cwd})).stdout);
    for (const [kind, envelope] of /** @type {const} */ ([
      ['success', success],
      ['failure', failure],
    ])) {
      const {required, optional} = SHAPES[kind];
      for (const key of required) expect(Object.keys(envelope), kind).toContain(key);
      for (const key of Object.keys(envelope)) expect([...required, ...optional], kind).toContain(key);
    }
  });

  it.each(readmeEnvelopes().map((e) => [e.group.replace(/\s+/g, ' ').slice(0, 70), e]))(
    '%s names the INV2 keys',
    (_label, {keys, kind}) => {
      const {required, optional} = SHAPES[kind];
      for (const key of required) expect(keys).toContain(key);
      for (const key of keys) expect([...required, ...optional]).toContain(key);
    },
  );
});

describe('README search options', () => {
  const manifest = buildManifest(program, {jsonSupported: JSON_SUPPORTED, version: '0.0.0-test'});
  const search = manifest.commands.find((c) => c.name === 'search');
  const section = README.slice(
    README.indexOf('## Finding things: `astryx search`'),
    README.indexOf('## Commands'),
  );
  const bullets = [...section.matchAll(/^- `(--[\w-]+)( <[^>]+>)?`/gm)];

  it('lists the search options', () => {
    expect(bullets.length).toBeGreaterThanOrEqual(3);
  });

  it.each(bullets.map((m) => [m[1], Boolean(m[2])]))(
    '`%s` is a search or global option with the same arity',
    (flag, takesValue) => {
      const option = [...search.options, ...manifest.globalOptions].find((o) =>
        o.flag.split(/[\s,]+/).includes(flag),
      );
      expect(option, `${flag} is not accepted by astryx search`).toBeDefined();
      expect(option.type !== 'boolean', `${flag} value arity`).toBe(takesValue);
    },
  );
});