Skip to content

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

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

/**
 * @file Colocated tests for authoring-surface.mjs: every type this repo's
 *   `@astryxdesign/cli/authoring` exports traces to a readable self-doc, and
 *   each way a type loses its doc, or a self-doc loses its type, is named.
 */

import {afterEach, describe, expect, it} from 'vitest';
import * as fs from 'node:fs';
import * as path from 'node:path';
import {
  auditAuthoringSurface,
  tracePublicAuthoringTypes,
} from './authoring-surface.mjs';
import {docs} from '../../api/docs/docs.mjs';
import {REPO_ROOT} from '../../test-utils/repo-root.mjs';

const SLOW = 60_000;

/** @type {string[]} */
const roots = [];
afterEach(() => {
  while (roots.length) {
    fs.rmSync(/** @type {string} */ (roots.pop()), {
      recursive: true,
      force: true,
    });
  }
});

/**
 * A throwaway authoring tree. Kept under the working directory so its
 * self-docs import the way the real ones do.
 * @param {Record<string, string>} files
 * @returns {string}
 */
function tree(files) {
  const root = fs.mkdtempSync(path.join(REPO_ROOT, '.astryx-surface-'));
  roots.push(root);
  for (const [rel, content] of Object.entries(files)) {
    const abs = path.join(root, rel);
    fs.mkdirSync(path.dirname(abs), {recursive: true});
    fs.writeFileSync(abs, content);
  }
  return root;
}

/**
 * @param {string} name
 * @param {string} [displayName]
 */
const selfDoc = (name, displayName = name) =>
  `export const doc = {type: 'schema', name: '${name}', displayName: '${displayName}', description: 'About ${name}.', fields: []};\n`;

/** One public type with its self-doc beside it. */
const FOO = {
  'index.d.ts': "export type {FooDoc} from './foo/type.js';\n",
  'foo/type.ts': 'export interface FooDoc {\n  name: string;\n}\n',
  'foo/foo.doc.mjs': selfDoc('foo-doc', 'FooDoc'),
};

describe('the public authoring surface of this repo', () => {
  it('traces every exported type to the module that declares it, and leaves the parsers out', () => {
    const {types, untraced} = tracePublicAuthoringTypes();
    expect(untraced).toEqual([]);
    const moduleOf = Object.fromEntries(types.map(t => [t.name, t.module]));
    expect(moduleOf).toMatchObject({
      NamespaceDoc: 'doctypes/namespace/type.ts',
      ComponentDoc: 'doctypes/component/type.ts',
      WorkflowDocBlock: 'doctypes/reference/type.ts',
      CollectionDocBlock: 'doctypes/reference/type.ts',
      ReferenceDocBlock: 'doctypes/reference/type.ts',
      AuthoredDocGraphFields: 'doctypes/base/type.ts',
      DocPlacement: 'doctypes/base/type.ts',
      ProviderId: 'identity/type.ts',
      AstryxConfig: 'config/type.ts',
      DebugConfig: 'config/type.ts',
      AstryxIntegration: 'integration/type.ts',
      DebugEvent: 'debug/type.ts',
      GapReportHandler: 'gap-report/type.ts',
    });
    expect(types.filter(t => t.name.startsWith('parse'))).toEqual([]);
    expect(new Set(types.map(t => t.name)).size).toBe(types.length);
  });

  it(
    'audits clean: every exported type has a readable doc and every self-doc documents one',
    async () => {
      const index = await docs('authoring/field-reference', undefined, {index: true});
      const topicKeys = new Set(
        index.data.sections.map((/** @type {any} */ s) => s.id),
      );
      expect(await auditAuthoringSurface({topicKeys})).toEqual({
        types: tracePublicAuthoringTypes().types.length,
        unreadable: [],
        untraced: [],
        unmatched: [],
      });
    },
    SLOW,
  );
});

describe('auditAuthoringSurface', () => {
  it('passes a type whose registered self-doc sits beside its module', async () => {
    const root = tree(FOO);
    expect(
      await auditAuthoringSurface({
        root,
        sources: ['foo/foo.doc.mjs'],
        topicKeys: new Set(['foo-doc']),
      }),
    ).toEqual({types: 1, unreadable: [], untraced: [], unmatched: []});
  });

  it('names an exported type with no self-doc beside its module', async () => {
    const root = tree({
      ...FOO,
      'index.d.ts': `${FOO['index.d.ts']}export type {BarDoc, BarField} from './bar/type.js';\n`,
      'bar/type.ts':
        'export interface BarDoc {}\nexport type BarField = string;\n',
    });
    const audit = await auditAuthoringSurface({
      root,
      sources: ['foo/foo.doc.mjs'],
    });
    expect(audit.unreadable).toEqual([
      {
        module: 'bar/type.ts',
        names: ['BarDoc', 'BarField'],
        reason: 'no-self-doc',
      },
    ]);
  });

  it('does not let a self-doc in a parent folder stand in for one beside the module', async () => {
    const root = tree({
      ...FOO,
      'index.d.ts': `${FOO['index.d.ts']}export type {FooPart} from './foo/part/type.js';\n`,
      'foo/part/type.ts': 'export interface FooPart {}\n',
    });
    const audit = await auditAuthoringSurface({
      root,
      sources: ['foo/foo.doc.mjs'],
    });
    expect(audit.unreadable).toEqual([
      {module: 'foo/part/type.ts', names: ['FooPart'], reason: 'no-self-doc'},
    ]);
  });

  it('names a self-doc that exists but is not registered', async () => {
    const audit = await auditAuthoringSurface({root: tree(FOO), sources: []});
    expect(audit.unreadable).toEqual([
      {
        module: 'foo/type.ts',
        names: ['FooDoc'],
        reason: 'unregistered',
        source: 'foo/foo.doc.mjs',
      },
    ]);
  });

  it('names a registered self-doc that does not load', async () => {
    const root = tree({...FOO, 'foo/foo.doc.mjs': 'export const doc = {;\n'});
    const audit = await auditAuthoringSurface({
      root,
      sources: ['foo/foo.doc.mjs'],
    });
    expect(audit.unreadable).toEqual([
      {
        module: 'foo/type.ts',
        names: ['FooDoc'],
        reason: 'failed',
        source: 'foo/foo.doc.mjs',
      },
    ]);
  });

  it("names a registered self-doc whose section the topic's index does not list", async () => {
    const audit = await auditAuthoringSurface({
      root: tree(FOO),
      sources: ['foo/foo.doc.mjs'],
      topicKeys: new Set(['something-else']),
    });
    expect(audit.unreadable).toEqual([
      {
        module: 'foo/type.ts',
        names: ['FooDoc'],
        reason: 'missing-section',
        source: 'foo/foo.doc.mjs',
        key: 'foo-doc',
      },
    ]);
  });

  it('names a registered self-doc that documents no exported type', async () => {
    const root = tree({
      ...FOO,
      'bar/type.ts': 'export interface BarDoc {}\n',
      'bar/bar.doc.mjs': selfDoc('bar-doc', 'BarDoc'),
      'notes/notes.doc.mjs': selfDoc('notes', 'Notes'),
    });
    const audit = await auditAuthoringSurface({
      root,
      sources: ['foo/foo.doc.mjs', 'bar/bar.doc.mjs', 'notes/notes.doc.mjs'],
    });
    expect(audit.unmatched).toEqual([
      {source: 'bar/bar.doc.mjs', key: 'bar-doc'},
      {source: 'notes/notes.doc.mjs', key: 'notes'},
    ]);
    expect(audit.unreadable).toEqual([]);
  });

  it('names a self-doc titled after a type beside it that the surface does not export', async () => {
    const root = tree({
      ...FOO,
      'index.d.ts': "export type {FooField} from './foo/type.js';\n",
      'foo/type.ts':
        'export interface FooDoc {}\nexport type FooField = string;\n',
      // What the declaration build writes beside a JavaScript module.
      'foo/foo.doc.d.mts': 'export const doc: {\n  name: string;\n};\n',
    });
    const audit = await auditAuthoringSurface({
      root,
      sources: ['foo/foo.doc.mjs'],
    });
    expect(audit.unmatched).toEqual([
      {source: 'foo/foo.doc.mjs', key: 'foo-doc', subject: 'FooDoc'},
    ]);
  });

  it('does not treat a title that is no declared name as a subject', async () => {
    const root = tree({
      ...FOO,
      'foo/foo.doc.mjs': selfDoc('foo', 'Foo Doc'),
    });
    const audit = await auditAuthoringSurface({
      root,
      sources: ['foo/foo.doc.mjs'],
    });
    expect(audit.unmatched).toEqual([]);
  });

  it('follows named, renamed, star, and imported re-exports to the declaring module', () => {
    const root = tree({
      'index.d.ts': [
        "export type {A, B as Bee} from './barrel.js';",
        "import type {C} from './c/type.js';",
        'export type {C};',
        "export type * from './d/type.js';",
        "export type * as E from './e/type.js';",
        '',
      ].join('\n'),
      'barrel.ts':
        "export type * from './a/type.js';\nexport type {B} from './b/type.js';\n",
      'a/type.ts': 'export interface A {}\n',
      'b/type.ts': 'export type B = number;\n',
      'c/type.ts': 'export interface C {}\n',
      'd/type.ts': 'export interface D1 {}\nexport type D2 = D1[];\n',
      'e/type.ts': 'export interface E1 {}\n',
    });
    expect(tracePublicAuthoringTypes(root)).toEqual({
      types: [
        {name: 'A', module: 'a/type.ts'},
        {name: 'Bee', module: 'b/type.ts'},
        {name: 'C', module: 'c/type.ts'},
        {name: 'D1', module: 'd/type.ts'},
        {name: 'D2', module: 'd/type.ts'},
        {name: 'E', module: 'e/type.ts'},
      ],
      untraced: [],
    });
  });

  it('leaves out a value exported from a JavaScript module, and keeps a value-style export of a type', () => {
    const root = tree({
      'index.d.ts':
        "export {parseFoo} from './foo/parse.mjs';\nexport {FooDoc} from './foo/type.js';\nexport type {FooShape} from './foo/parse.mjs';\n",
      'foo/type.ts': 'export interface FooDoc {}\n',
      'foo/parse.mjs': 'export function parseFoo(x) {\n  return x;\n}\n',
    });
    expect(tracePublicAuthoringTypes(root)).toEqual({
      types: [
        {name: 'FooDoc', module: 'foo/type.ts'},
        {name: 'FooShape', module: 'foo/parse.mjs'},
      ],
      untraced: [],
    });
  });

  it('reports an export it cannot trace instead of dropping it', () => {
    const root = path.join(
      tree({
        'authoring/index.d.ts': [
          "export type {Ghost} from './foo/type.js';",
          "export type {Lost} from './nowhere/type.js';",
          "export type {Outside} from '../elsewhere/type.js';",
          "export * from './foo/parse.mjs';",
          "export type * from './barrel.js';",
          "export type {Loop} from './loop-a.js';",
          '',
        ].join('\n'),
        'authoring/foo/type.ts': 'export interface FooDoc {}\n',
        'authoring/foo/parse.mjs': 'export const parseFoo = x => x;\n',
        'authoring/barrel.ts': "export * from './foo/parse.mjs';\n",
        'authoring/loop-a.ts': "export type {Loop} from './loop-b.js';\n",
        'authoring/loop-b.ts': "export type {Loop} from './loop-a.js';\n",
        'elsewhere/type.ts': 'export interface Outside {}\n',
      }),
      'authoring',
    );
    const {types, untraced} = tracePublicAuthoringTypes(root);
    expect(types).toEqual([]);
    expect(untraced).toEqual([
      {
        name: 'Ghost',
        reason:
          'index.d.ts exports Ghost from "./foo/type.js", which does not declare it',
      },
      {
        name: 'Lost',
        reason:
          'index.d.ts names "./nowhere/type.js", which is not a file in authoring/',
      },
      {
        name: 'Outside',
        reason:
          'index.d.ts names "../elsewhere/type.js", which is not a file in authoring/',
      },
      {
        name: '* from "./foo/parse.mjs"',
        reason:
          'index.d.ts re-exports everything "./foo/parse.mjs" exports, and what a JavaScript module exports cannot be listed',
      },
      {
        name: '* from "./barrel.js"',
        reason:
          'barrel.ts re-exports every type of "./foo/parse.mjs", a JavaScript module whose types cannot be listed',
      },
      {
        name: 'Loop',
        reason:
          'loop-b.ts exports Loop from "./loop-a.js", which does not declare it',
      },
    ]);
  });

  it('gives a type declared in index.d.ts itself no doc, since nothing sits beside the barrel', async () => {
    const root = tree({'index.d.ts': 'export interface Loose {}\n'});
    const audit = await auditAuthoringSurface({root, sources: []});
    expect(audit.unreadable).toEqual([
      {module: 'index.d.ts', names: ['Loose'], reason: 'no-self-doc'},
    ]);
  });

  it('never executes a module it traces through', async () => {
    const marker = path.join(
      process.cwd(),
      `.astryx-surface-ran-${process.pid}`,
    );
    const root = tree({
      ...FOO,
      'index.d.ts': `${FOO['index.d.ts']}export {parseFoo} from './foo/parse.mjs';\nexport type {Shape} from './foo/shape.mjs';\n`,
      'foo/parse.mjs': `import * as fs from 'node:fs';\nfs.writeFileSync(${JSON.stringify(marker)}, 'ran');\nexport const parseFoo = x => x;\n`,
      'foo/shape.mjs': `import * as fs from 'node:fs';\nfs.writeFileSync(${JSON.stringify(marker)}, 'ran');\n`,
    });
    const before = listTree(root);
    await auditAuthoringSurface({root, sources: ['foo/foo.doc.mjs']});
    expect(fs.existsSync(marker)).toBe(false);
    expect(listTree(root)).toEqual(before);
  });
});

/**
 * Every file under `root` with its contents, to prove a read left it alone.
 * @param {string} root
 * @returns {Record<string, string>}
 */
function listTree(root) {
  /** @type {Record<string, string>} */
  const out = {};
  /** @param {string} dir */
  const walk = dir => {
    for (const entry of fs.readdirSync(dir, {withFileTypes: true})) {
      const full = path.join(dir, entry.name);
      if (entry.isDirectory()) walk(full);
      else out[path.relative(root, full)] = fs.readFileSync(full, 'utf8');
    }
  };
  walk(root);
  return out;
}