@astryxdesign/cli 0.6.3 → 0.6.4-canary.06c8fa3

package/foundation/discovery/authoring-surface.test.mjs

@@ -0,0 +1,392 @@
+// 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';
+
+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(process.cwd(), '.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', 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;
+}

package/foundation/discovery/cli-self-docs.d.mts

@@ -0,0 +1,119 @@
+// @generated by scripts/sync-api-types.mjs from the JSDoc in foundation/**/*.mjs.
+// DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
+
+/**
+ * Every `*.doc.mjs` under the CLI's doc directories, relative to `root` and
+ * sorted. Fixture, test, and dependency directories are skipped.
+ * @param {string} [root]
+ * @returns {string[]}
+ */
+export function discoverCliSelfDocSources(root?: string): string[];
+/**
+ * Read each doc through the compiler and keep the kinds that declare a
+ * namespace. One that fails is reported, never thrown, so one bad file cannot
+ * take the rest of the topic down with it.
+ * @param {string[]} [sources]
+ * @param {string} [root]
+ * @returns {Promise<{loaded: {source: string, doc: any}[], failed: {source: string, error: string}[]}>}
+ */
+export function loadCliSelfDocs(sources?: string[], root?: string): Promise<{
+    loaded: {
+        source: string;
+        doc: any;
+    }[];
+    failed: {
+        source: string;
+        error: string;
+    }[];
+}>;
+/**
+ * What cross-links need: the loaded function docs by name, the command names,
+ * and the route the docs tree gave a doc, if it gave one.
+ * @typedef {object} CliDocIndex
+ * @property {Map<string, any>} functions
+ * @property {Set<string>} commands
+ * @property {(kind: string, name: string) => string | null} route
+ */
+/**
+ * @param {any[]} docs every loaded CLI typed doc
+ * @param {(kind: string, name: string) => string | null} [route]
+ * @returns {CliDocIndex}
+ */
+export function cliDocIndex(docs: any[], route?: (kind: string, name: string) => string | null): CliDocIndex;
+/**
+ * What `astryx docs <route>` prints for one CLI typed doc: its title and the
+ * blocks of its content, with cross-links to the routes the tree gave.
+ * @param {any} doc
+ * @param {CliDocIndex} index
+ * @returns {{id: string, title: string, content: any[]}}
+ */
+export function cliDocSection(doc: any, index: CliDocIndex): {
+    id: string;
+    title: string;
+    content: any[];
+};
+/**
+ * What stands between a CLI doc and a reader: a missing namespace, one nothing
+ * reads, one that disagrees with the authoring topic's list, a doc that fails
+ * to load, and a tree leaf too large for one read. Whether the tree gives
+ * every `cli/...` doc a route is the docs-tree check's job.
+ * @param {{root?: string, sources?: string[], budget?: number, authoringSources?: string[]}} [options]
+ * @returns {Promise<{
+ *   docs: number,
+ *   tree: number,
+ *   authoring: number,
+ *   missing: string[],
+ *   unknown: {source: string, namespace: string}[],
+ *   misfiled: {source: string, message: string}[],
+ *   failed: {source: string, error: string}[],
+ *   oversized: {key: string, title: string, bytes: number}[],
+ * }>}
+ */
+export function auditCliSelfDocs({ root, sources, budget, authoringSources, }?: {
+    root?: string;
+    sources?: string[];
+    budget?: number;
+    authoringSources?: string[];
+}): Promise<{
+    docs: number;
+    tree: number;
+    authoring: number;
+    missing: string[];
+    unknown: {
+        source: string;
+        namespace: string;
+    }[];
+    misfiled: {
+        source: string;
+        message: string;
+    }[];
+    failed: {
+        source: string;
+        error: string;
+    }[];
+    oversized: {
+        key: string;
+        title: string;
+        bytes: number;
+    }[];
+}>;
+/** The directories, relative to the CLI root, that hold the CLI's own docs. */
+export const CLI_SELF_DOC_DIRS: string[];
+/**
+ * Every namespace a CLI doc may declare, and what reads it. The docs tree
+ * adopts `cli/commands` (under `cli/commands`) and `cli/api` (under
+ * `cli/api/<kind>s`); `astryx docs authoring` reads `authoring` from its list.
+ * @type {Record<string, {reader: 'tree' | 'authoring'}>}
+ */
+export const CLI_DOC_NAMESPACES: Record<string, {
+    reader: "tree" | "authoring";
+}>;
+/**
+ * What cross-links need: the loaded function docs by name, the command names,
+ * and the route the docs tree gave a doc, if it gave one.
+ */
+export type CliDocIndex = {
+    functions: Map<string, any>;
+    commands: Set<string>;
+    route: (kind: string, name: string) => string | null;
+};