Skip to content

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

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

/**
 * @file `doctor integration validate` (and so `integration check`) notes a
 * template or namespace doc that sets `stability`, which a CLI before 0.7.4
 * refuses and drops (spec:AST-017 FR27), unless the package's CLI peer range
 * admits only CLIs that read it. A note is additive data, never an issue: it
 * is not counted and never fails a check. A component doc or guide that sets
 * the field is not noted: older CLIs ignore it there.
 */

import * as fs from 'node:fs';
import * as os from 'node:os';
import * as path from 'node:path';
import {afterEach, beforeEach, describe, expect, it} from 'vitest';
import {validateIntegration} from './validate-integration.mjs';
import {integrationCheck} from './check/check.mjs';
import {runCli} from '../../test-utils/run-cli.mjs';

/** @type {string} */
let dir;

beforeEach(() => {
  dir = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-doc-stability-'));
});
afterEach(() => {
  fs.rmSync(dir, {recursive: true, force: true});
});

/**
 * @param {Record<string, unknown>} pkgExtra
 * @param {string} stability the field, or '' for none
 */
function writePackage(pkgExtra, stability) {
  /** @param {string} rel @param {string} text */
  const write = (rel, text) => {
    fs.mkdirSync(path.dirname(path.join(dir, rel)), {recursive: true});
    fs.writeFileSync(path.join(dir, rel), text);
  };
  write(
    'package.json',
    JSON.stringify({name: '@acme/stab', version: '1.0.0', ...pkgExtra}),
  );
  write(
    'astryx.integration.mjs',
    "export default {templates: './templates', docs: './docs', components: './components'};\n",
  );
  write(
    'templates/stab-hero.tsx',
    'export default function StabHero() { return null; }\n',
  );
  write(
    'templates/stab-hero.doc.mjs',
    `export default {type: 'block', name: 'Stab hero', description: 'A hero block.', aspectRatio: 2, componentsUsed: []${stability}};\n`,
  );
  write(
    'docs/stabns.doc.mjs',
    `export default {type: 'namespace', name: 'stabns', title: 'Stab', summary: 'Stab docs.'${stability}, slots: {guides: {title: 'Guides', accepts: {kinds: ['generic']}}}};\n`,
  );
  write(
    'components/StabWidget.tsx',
    'export function StabWidget() { return null; }\n',
  );
  write(
    'components/StabWidget.doc.mjs',
    `/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */\nexport default {type: 'component', name: 'StabWidget', displayName: 'Stab Widget', category: 'Layout', usage: {description: 'A widget.', bestPractices: []}, props: []${stability}};\n`,
  );
}

/** @returns {Promise<any>} */
async function validated() {
  return (await validateIntegration(undefined, {cwd: dir})).data;
}

describe('olderCliNotes', () => {
  it('notes each template and namespace doc that sets stability, never as an issue', async () => {
    writePackage({}, ", stability: 'experimental'");
    const data = await validated();
    expect(
      data.olderCliNotes.map((/** @type {any} */ note) => [
        note.file,
        note.kind,
      ]),
    ).toEqual(
      expect.arrayContaining([
        ['docs/stabns.doc.mjs', 'namespace'],
        ['templates/stab-hero.doc.mjs', 'template'],
      ]),
    );
    expect(data.olderCliNotes).toHaveLength(2);
    for (const note of data.olderCliNotes) {
      expect(note.message).toContain('CLIs before 0.7.4 drop this descriptor');
      expect(note.message).toContain('">=0.7.4"');
    }
    expect(
      data.olderCliNotes.find(
        (/** @type {any} */ note) => note.kind === 'namespace',
      ).message,
    ).toContain("hide the package's doc topics");
    // Not an issue: nothing about stability is counted.
    expect(JSON.stringify(data.issues)).not.toContain('stability');
  });

  it('never fails integration check --strict, with or without --next', async () => {
    writePackage(
      {peerDependencies: {'@astryxdesign/cli': '>=0.6.4'}},
      ", stability: 'experimental'",
    );
    // Not a `next` finding either: no minor release turns it into a warning.
    const ahead = await integrationCheck({cwd: dir, strict: true, next: true});
    expect(JSON.stringify(ahead.data.failures)).not.toContain('stability');
    const strict = await integrationCheck({cwd: dir, strict: true});
    expect(JSON.stringify(strict.data.failures)).not.toContain('stability');
    const validate = strict.data.checks.find(each => each.check === 'validate');
    expect(
      /** @type {any} */ (validate).response.data.olderCliNotes,
    ).toHaveLength(2);
    const text = await runCli(['integration', 'check', '--strict'], dir);
    expect(text.stdout).toContain('Notes for older CLIs');
    expect(text.stdout).toContain('templates/stab-hero.doc.mjs');
  }, 60_000);

  it('notes a template that declares icons, which 0.7.2 drops', async () => {
    writePackage({}, '');
    const doc = path.join(dir, 'templates', 'stab-hero.doc.mjs');
    fs.writeFileSync(
      doc,
      fs
        .readFileSync(doc, 'utf-8')
        .replace(
          'componentsUsed: []',
          "componentsUsed: [], icons: {XIcon: 'close'}",
        ),
    );
    const data = await validated();
    expect(data.olderCliNotes).toEqual([
      expect.objectContaining({
        file: 'templates/stab-hero.doc.mjs',
        kind: 'template',
        field: 'icons',
        message: expect.stringContaining('declares `icons`: CLIs before 0.7.4'),
      }),
    ]);
  });

  it('notes a CLI peer range that starts at 0.7.3, which drops the descriptor', async () => {
    writePackage(
      {peerDependencies: {'@astryxdesign/cli': '>=0.7.3'}},
      ", stability: 'experimental'",
    );
    const data = await validated();
    expect(data.olderCliNotes).toEqual(
      expect.arrayContaining([
        expect.objectContaining({kind: 'template', field: 'stability'}),
      ]),
    );
  });

  it('says nothing when the CLI peer range starts at 0.7.4', async () => {
    writePackage(
      {peerDependencies: {'@astryxdesign/cli': '>=0.7.4'}},
      ", stability: 'experimental'",
    );
    expect(await validated()).not.toHaveProperty('olderCliNotes');
  });

  it('says nothing when no descriptor sets stability', async () => {
    writePackage({}, '');
    expect(await validated()).not.toHaveProperty('olderCliNotes');
  });
});

describe('template icons a template never imports', () => {
  it('notes each `icons` key the source does not import, never as an issue', async () => {
    writePackage({peerDependencies: {'@astryxdesign/cli': '>=0.7.4'}}, '');
    const doc = path.join(dir, 'templates', 'stab-hero.doc.mjs');
    fs.writeFileSync(
      doc,
      fs
        .readFileSync(doc, 'utf-8')
        .replace(
          'componentsUsed: []',
          "componentsUsed: [], icons: {BinGlyph: 'delete', XIcon: 'close'}",
        ),
    );
    fs.writeFileSync(
      path.join(dir, 'templates', 'stab-hero.tsx'),
      "import {BinGlyph} from '@acme/library';\nexport default function StabHero() { return <BinGlyph />; }\n",
    );
    const data = await validated();
    expect(
      data.notes.filter(
        (/** @type {any} */ note) => note.code === 'template_icon_not_imported',
      ),
    ).toEqual([
      {
        code: 'template_icon_not_imported',
        message: expect.stringContaining(
          'templates/stab-hero.doc.mjs declares icon "XIcon" in `icons`, which templates/stab-hero.tsx does not import',
        ),
      },
    ]);
    expect(JSON.stringify(data.issues)).not.toContain('XIcon');
    const strict = await integrationCheck({cwd: dir, strict: true});
    expect(JSON.stringify(strict.data.failures)).not.toContain('XIcon');
    // A note that is never counted: no `next`, so --next does not count it.
    const ahead = await integrationCheck({cwd: dir, strict: true, next: true});
    expect(JSON.stringify(ahead.data.failures)).not.toContain('XIcon');
    const validate = ahead.data.checks.find(each => each.check === 'validate');
    expect(
      /** @type {any} */ (validate).response.data.notes.find(
        (/** @type {any} */ note) => note.code === 'template_icon_not_imported',
      ),
    ).not.toHaveProperty('next');
  }, 60_000);
});