Skip to content

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

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

/**
 * @file Colocated tests for `parseIntegration` — the load-boundary validator for
 * `astryx.integration.*`. Zod is sealed inside the parser; these exercise the
 * public contract (validated value out / readable error thrown) with the same
 * accept/reject set the old `AstryxIntegrationSchema` had.
 */

import {describe, it, expect} from 'vitest';
import {parseIntegration} from './parse.mjs';
import {integrationSchema, unknownIntegrationKeys} from './schema.mjs';

/** Run parseIntegration and return the thrown message (asserting it throws). */
function reason(value, label = 'integration') {
  try {
    parseIntegration(value, label);
  } catch (err) {
    return err instanceof Error ? err.message : String(err);
  }
  throw new Error('expected parseIntegration to throw');
}

describe('parseIntegration (load boundary)', () => {
  it('accepts an empty manifest and a valid one', () => {
    expect(parseIntegration({})).toEqual({});
    expect(parseIntegration({components: './src'})).toEqual({
      components: './src',
    });
    expect(parseIntegration({docs: './docs'})).toEqual({docs: './docs'});
    expect(parseIntegration({providerId: '@acme/legacy-widgets'})).toEqual({
      providerId: '@acme/legacy-widgets',
    });
    expect(parseIntegration({themes: './themes'})).toEqual({
      themes: './themes',
    });
    expect(() =>
      parseIntegration({components: './c', issuesUrl: 'https://example.com/i'}),
    ).not.toThrow();
  });

  it('ignores a key it does not know, and keeps the rest of the manifest', () => {
    // A key from a NEWER CLI is the common case, not an authoring mistake: the
    // integration is published once and installed against many CLI versions.
    // Rejecting the manifest took the whole package's contributions down with
    // it, silently, on every older consumer (#5119).
    expect(
      parseIntegration({components: './src', futureRoot: './future'}),
    ).toEqual({
      components: './src',
    });
    expect(
      unknownIntegrationKeys({components: './src', futureRoot: './future'}),
    ).toEqual(['futureRoot']);
    expect(unknownIntegrationKeys({components: './src'})).toEqual([]);
    // Not a manifest at all — nothing to report, and the parser owns the error.
    expect(unknownIntegrationKeys(null)).toEqual([]);
    expect(unknownIntegrationKeys([1, 2])).toEqual([]);
  });

  it('reports no known key as unknown, whatever the schema grows', () => {
    // The census is read off the schema, so this holds for keys that do not
    // exist yet. A hand-maintained list would pass today and start warning
    // falsely about a supported field the day someone forgot to update it.
    const everyKnownKey = Object.fromEntries(
      Object.keys(integrationSchema.shape).map(key => [
        key,
        key === 'issuesUrl'
          ? 'https://example.com/issues'
          : key === 'agentDocs'
            ? {}
            : key === 'providerId'
              ? '@acme/widgets'
              : './x',
      ]),
    );
    expect(unknownIntegrationKeys(everyKnownKey)).toEqual([]);
  });

  it('still rejects a known key of the wrong type', () => {
    // The relaxation is about keys this CLI has never heard of. A key it DOES
    // know, holding the wrong type, is a real authoring mistake.
    expect(reason({components: 42})).toContain('components');
  });

  it('rejects a non-URL issuesUrl', () => {
    expect(reason({issuesUrl: 'nope'})).toContain('issuesUrl');
  });

  it('accepts a docsiteUrl as a known key', () => {
    const manifest = {docsiteUrl: 'https://widgets.example.com'};
    expect(parseIntegration(manifest)).toEqual(manifest);
    expect(unknownIntegrationKeys(manifest)).toEqual([]);
  });

  it('rejects a non-URL docsiteUrl', () => {
    expect(reason({docsiteUrl: 'nope'})).toContain('docsiteUrl');
  });

  it('accepts a cliCommand and rejects one that is not a single clean line', () => {
    expect(parseIntegration({cliCommand: 'acme astryx'})).toEqual({
      cliCommand: 'acme astryx',
    });
    expect(reason({cliCommand: ''})).toContain('cliCommand');
    expect(reason({cliCommand: ' acme astryx'})).toContain('cliCommand');
    expect(reason({cliCommand: 'acme\nastryx'})).toContain('cliCommand');
    expect(reason({cliCommand: 'a'.repeat(121)})).toContain('120');
    expect(reason({cliCommand: 42})).toContain('cliCommand');
  });

  it('rejects a noncanonical providerId', () => {
    expect(reason({providerId: 'Acme Widgets'})).toContain('providerId');
  });

  it('accepts an optional append array as manifest data', () => {
    expect(
      parseIntegration({
        agentDocs: {
          append: ['Run acme verify before finishing.'],
        },
      }),
    ).toEqual({
      agentDocs: {
        append: ['Run acme verify before finishing.'],
      },
    });
  });

  it('strips future nested agentDocs keys without rejecting append', () => {
    expect(
      parseIntegration({
        agentDocs: {
          append: ['Run acme verify before finishing.'],
          futureField: true,
        },
      }),
    ).toEqual({
      agentDocs: {
        append: ['Run acme verify before finishing.'],
      },
    });
  });

  it('caps append at eight lines', () => {
    expect(
      reason({
        agentDocs: {
          append: Array.from({length: 9}, (_, index) => `after ${index}`),
        },
      }),
    ).toMatch(/at most 8 lines/);
  });

  it('counts Unicode code points rather than UTF-16 code units', () => {
    expect(() =>
      parseIntegration({agentDocs: {append: ['😀'.repeat(240)]}}),
    ).not.toThrow();
    expect(reason({agentDocs: {append: ['😀'.repeat(241)]}})).toMatch(
      /240 Unicode code points/,
    );
  });

  it.each([
    ['', /blank/],
    ['   ', /blank/],
    [' leading', /surrounding whitespace/],
    ['trailing ', /surrounding whitespace/],
    ['two\nlines', /single line|line separators/],
    ['two\rlines', /control characters|line separators/],
    ['unicode\u2028separator', /single line/],
    ['nul\u0000byte', /NUL/],
    ['control\u0001byte', /control characters/],
    ['control\u0085byte', /control characters/],
    ['<!-- ASTRYX:START -->', /managed marker text/],
    ['XDS:END', /managed marker text/],
  ])('rejects forbidden agentDocs line %#', (line, message) => {
    expect(reason({agentDocs: {append: [line]}})).toMatch(message);
  });

  it('rejects functions and other non-data shapes', () => {
    expect(reason({agentDocs: () => ({append: ['x']})})).toContain('agentDocs');
    expect(reason({agentDocs: {append: ['ok', 42]}})).toContain('append');
  });
});