Skip to content

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

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

/**
 * @file Everything that can fail `astryx integration check --strict`.
 *
 * Builds run `integration check --strict`, so what fails it is a contract: a
 * new check, or a new failure code, joins only in a minor release that names
 * it. The list
 * beside this file, integration-check-failures.json, names every check, every
 * field of a check's result that is counted, every code a failure can carry,
 * and every comparison a check carries, read here from the code:
 * - `checks`: the checks `integration check` runs, in order;
 * - `results`: per check, the fields of its result besides its identity, read
 *   from a run against a package with every kind of root;
 * - `codes`: every issue code the checks' modules can raise (scanned in each
 *   module the command imports), the codes a conflict, a package with no
 *   manifest, or a skipped comparison carries, and every finding code a
 *   comparison declares;
 * - `reports`: each comparison a check carries, with the code its skip has.
 * Adding to any of them fails this test until the list changes, so a new way
 * to fail a build always shows up in review.
 */

import * as fs from 'node:fs';
import * as path from 'node:path';
import {fileURLToPath} from 'node:url';
import {afterAll, beforeAll, describe, expect, it} from 'vitest';
import {requireNatively} from '../test-utils/native-require.mjs';
import {REPO_ROOT} from '../test-utils/repo-root.mjs';

const require = requireNatively(import.meta.url);
/** @type {typeof import('../api/integration/check/check.mjs')} */
const {
  CONFLICT_CODES,
  INTEGRATION_CHECKS,
  NO_MANIFEST_CODE,
  integrationCheck,
  isCheckReport,
  skippedCode,
} = require('../api/integration/check/check.mjs');

const HERE = path.dirname(fileURLToPath(import.meta.url));
const CLI = path.resolve(HERE, '..');
const LIST = path.join(HERE, 'integration-check-failures.json');
const ENTRY = path.join(CLI, 'api', 'integration', 'check', 'check.mjs');

/**
 * Modules the command imports whose codes cannot fail it, with why.
 * @type {Record<string, string>}
 */
const NOT_SCANNED = {
  // Only `integration verify` compares a packed tarball with the source.
  'foundation/integrations/contribution-inventory.mjs':
    'its codes come from comparing a packed tarball, which only integration verify does',
};

/** The authoring schemas: their codes are the schema library's, not issues. */
const AUTHORING = `authoring${path.sep}`;

/** @type {{checks: string[], results: Record<string, string[]>, codes: string[], reports: Record<string, string>}} */
const list = JSON.parse(fs.readFileSync(LIST, 'utf8'));

/**
 * Every CLI module `entry` reaches through static relative imports, docs and
 * tests aside.
 * @param {string} entry
 */
function reachableModules(entry) {
  const IMPORT =
    /(?:import|export)\s[^'"]*?from\s*['"](\.[^'"]+)['"]|import\(\s*['"](\.[^'"]+)['"]\s*\)/g;
  const seen = new Set();
  const queue = [entry];
  while (queue.length > 0) {
    const file = /** @type {string} */ (queue.shift());
    if (seen.has(file)) continue;
    seen.add(file);
    const text = fs.readFileSync(file, 'utf8');
    for (const match of text.matchAll(IMPORT)) {
      let target = path.resolve(path.dirname(file), match[1] ?? match[2]);
      if (!fs.existsSync(target) && fs.existsSync(`${target}.mjs`)) {
        target = `${target}.mjs`;
      }
      if (
        !target.startsWith(CLI + path.sep) ||
        !/\.(?:mjs|js)$/.test(target) ||
        /\.(?:doc|test)\.mjs$/.test(target) ||
        !fs.existsSync(target)
      ) {
        continue;
      }
      queue.push(target);
    }
  }
  return [...seen];
}

/**
 * The issue codes and finding codes one module can raise: a `code:` it
 * writes (or its fallback), each code in the first argument of `issueError`
 * and `issueWarning` under any name it imports them as (both branches of a
 * conditional), the code an error list is added under, the members of a
 * `code` property typed as a union of codes, and the members of a
 * finding-kind union whose members are all snake-case codes.
 * @param {string} text
 */
function codesIn(text) {
  const codes = new Set();
  const constants = new Map(
    [
      ...text.matchAll(
        /\bconst\s+([A-Z][A-Z0-9_]*)\s*=\s*'([a-z][a-z0-9_]*)'/g,
      ),
    ].map(m => [m[1], m[2]]),
  );
  const raisers = ['issueError', 'issueWarning'];
  for (const m of text.matchAll(/\bissue(?:Error|Warning)\s+as\s+(\w+)/g)) {
    raisers.push(m[1]);
  }
  const raise = new RegExp(`\\b(?:${raisers.join('|')})\\(([^,]*),`, 'g');
  for (const m of text.matchAll(raise)) {
    for (const each of m[1].matchAll(
      /'([a-z][a-z0-9_]*)'|\b([A-Z][A-Z0-9_]*)\b/g,
    )) {
      const code = each[1] ?? constants.get(each[2]);
      if (code) codes.add(code);
    }
  }
  for (const m of text.matchAll(/@property\s+\{([^}]*)\}\s+code\b/g)) {
    const members = [...m[1].matchAll(/'([^']*)'/g)].map(each => each[1]);
    if (
      members.length > 0 &&
      members.every(member => /^[a-z]+(?:_[a-z]+)+$/.test(member))
    ) {
      for (const member of members) codes.add(member);
    }
  }
  for (const m of text.matchAll(/\bcode:\s*'([a-z][a-z0-9_]*)'/g))
    codes.add(m[1]);
  for (const m of text.matchAll(
    /\bcode:\s*[^,\n}]*?\?\?\s*'([a-z][a-z0-9_]*)'/g,
  )) {
    codes.add(m[1]);
  }
  for (const m of text.matchAll(
    /\baddErrors\([^;]*?'([a-z][a-z0-9_]*)'\s*\)/g,
  )) {
    codes.add(m[1]);
  }
  for (const m of text.matchAll(
    /@typedef\s+\{([^}]*)\}\s+\w*(?:Kind|Problem)\b/g,
  )) {
    const members = [...m[1].matchAll(/'([^']*)'/g)].map(each => each[1]);
    if (
      members.length > 0 &&
      members.every(member => /^[a-z]+(?:_[a-z]+)+$/.test(member))
    ) {
      for (const member of members) codes.add(member);
    }
  }
  return codes;
}

/** @type {string} */
let pkg;
/** @type {import('../api/integration/integration-check.type.mjs').IntegrationCheckCommandResponse} */
let result;

beforeAll(async () => {
  // Under the repository, so the components check resolves Core. Every kind
  // of root, so every field a check's result can carry is present.
  pkg = fs.mkdtempSync(path.join(REPO_ROOT, '.astryx-check-failures-'));
  const write = (/** @type {string} */ rel, /** @type {string} */ text) => {
    fs.mkdirSync(path.dirname(path.join(pkg, rel)), {recursive: true});
    fs.writeFileSync(path.join(pkg, rel), text);
  };
  // Its own TypeScript config, scoped to its own files: with none, it gets
  // the repository's root config, as `tsc` reads it, and the components check
  // compiles every file in the repository.
  write(
    'tsconfig.json',
    `${JSON.stringify({extends: '../tsconfig.json', include: ['**/*']})}\n`,
  );
  write(
    'package.json',
    JSON.stringify({name: '@acme/widgets', version: '1.2.3'}),
  );
  write(
    'astryx.integration.mjs',
    "export default {components: './components', templates: './templates', docs: './docs'};\n",
  );
  write(
    'components/AcmeButton.doc.mjs',
    "export default {type: 'component', name: 'AcmeButton', displayName: 'Acme Button', description: 'A button.', props: []};\n",
  );
  write(
    'components/AcmeButton.tsx',
    'export function AcmeButton() { return null; }\n',
  );
  write(
    'templates/acme-page.doc.mjs',
    "export default {type: 'page', name: 'Acme page', displayName: 'Acme page', description: 'A page.'};\n",
  );
  write(
    'templates/acme-page.tsx',
    'export default function Fixture() { return null; }\n',
  );
  // The button's example, so the fixture draws no note.
  write(
    'templates/acme-button-showcase.doc.mjs',
    "export default {type: 'block', name: 'acme-button-showcase', displayName: 'Acme Button showcase', description: 'A button in use.', category: 'Acme - Actions', exampleFor: 'AcmeButton', isShowcase: true};\n",
  );
  write(
    'templates/acme-button-showcase.tsx',
    "import {AcmeButton} from '@acme/widgets';\nexport default function Showcase() { return <AcmeButton />; }\n",
  );
  write(
    'docs/acme-guide.doc.mjs',
    "export default {type: 'generic', name: 'acme-guide', title: 'Acme guide', description: 'A guide.', sections: [{title: 'One', content: [{type: 'prose', text: 'One.'}]}]};\n",
  );
  result = await integrationCheck({cwd: pkg, strict: true});
}, 60_000);

afterAll(() => {
  fs.rmSync(pkg, {recursive: true, force: true});
});

describe('what can fail integration check --strict', () => {
  it('runs the listed checks, in order', () => {
    expect([...INTEGRATION_CHECKS]).toEqual(list.checks);
    expect(result.data.checks.map(check => check.check)).toEqual(list.checks);
  });

  it('counts the listed fields of each check’s result', () => {
    /** @type {Record<string, string[]>} */
    const fields = {};
    for (const {check, response} of result.data.checks) {
      fields[check] = Object.keys(response.data)
        .filter(key => !['validated', 'name', 'version'].includes(key))
        .sort();
    }
    expect(
      fields,
      'A check’s result has a new field. If it can fail integration check, it is a new failure: list it (a minor-release change).',
    ).toEqual(
      Object.fromEntries(
        Object.entries(list.results).map(([check, keys]) => [
          check,
          [...keys].sort(),
        ]),
      ),
    );
  });

  it('lists each comparison a check carries, with the code its skip has', () => {
    /** @type {Record<string, string>} */
    const reports = {};
    for (const {response} of result.data.checks) {
      for (const [key, value] of Object.entries(response.data)) {
        if (isCheckReport(value)) reports[key] = skippedCode(key);
      }
    }
    expect(reports).toEqual(list.reports);
  });

  it('lists every code a failure can carry', () => {
    const codes = new Set([
      ...Object.values(CONFLICT_CODES),
      NO_MANIFEST_CODE,
      ...Object.values(list.reports),
    ]);
    for (const file of reachableModules(ENTRY)) {
      const rel = path.relative(CLI, file).split(path.sep).join('/');
      if (rel in NOT_SCANNED || file.startsWith(path.join(CLI, AUTHORING))) {
        continue;
      }
      for (const code of codesIn(fs.readFileSync(file, 'utf8'))) {
        codes.add(code);
      }
    }
    const found = [...codes].sort();
    const added = found.filter(code => !list.codes.includes(code));
    const removed = list.codes.filter(code => !codes.has(code));
    expect(
      added,
      'These codes can now fail integration check --strict. List them: a new failure code joins only in a minor release that names it.',
    ).toEqual([]);
    expect(
      removed,
      'Nothing raises these codes any more. Remove them from integration-check-failures.json.',
    ).toEqual([]);
  });

  it('reads the codes a module raises, under every name', () => {
    expect(
      [
        ...codesIn(
          [
            "import {issueError as error} from './x.mjs';",
            "const DUPLICATE = 'duplicate_thing';",
            "error('first_code', 'm'); issueWarning(DUPLICATE, 'm');",
            "error(found ? 'ternary_one' : 'ternary_two', 'm');",
            "/** @property {'typed_code_one' | 'typed_code_two'} code */",
            "issues.push({code: 'second_code', severity: 'warning'});",
            "x = {code: e.code ?? 'fallback_code'};",
            "addErrors(issues, errors, 'added_code');",
            "/** @typedef {'not_in_code' | 'type_mismatch'} DriftKind */",
            "/** @typedef {'page' | 'block'} TemplateKind */",
          ].join('\n'),
        ),
      ].sort(),
    ).toEqual([
      'added_code',
      'duplicate_thing',
      'fallback_code',
      'first_code',
      'not_in_code',
      'second_code',
      'ternary_one',
      'ternary_two',
      'type_mismatch',
      'typed_code_one',
      'typed_code_two',
    ]);
  });
});