@astryxdesign/cli 0.6.3-canary.98a2e4e → 0.6.3-canary.9c4d44d

package/foundation/config/project.test.mjs

@@ -6,6 +6,7 @@ import * as path from 'node:path';
 import {Project, DEFAULT_ISSUES_URL, findConfigPath} from './project.mjs';
 import {InMemoryConfigCache} from './config-cache.mjs';
 import * as componentDiscovery from '../discovery/component-discovery.mjs';
+import {discoverCoreTemplates} from '../discovery/template-adapter.mjs';
 
 let tmpDir;
 let originalCwd;
@@ -21,6 +22,9 @@ function scaffold({
   issuesUrl,
   withComponents = true,
   withTemplates = true,
+  templateId = 'hero',
+  templateType = 'block',
+  templateReplaces = null,
   withCodemods = true,
   brokenComponent = false,
   brokenCodemod = false,
@@ -65,7 +69,7 @@ function scaffold({
     fs.mkdirSync(compDir, {recursive: true});
     fs.writeFileSync(
       path.join(compDir, 'Widget.doc.mjs'),
-      `export const docs = { name: 'Widget', usage: {description: 'A widget'} };\n`,
+      `export const docs = { name: 'Widget', usage: {description: 'A widget'}, props: [] };\n`,
     );
     if (!brokenComponent) {
       fs.writeFileSync(
@@ -80,12 +84,12 @@ function scaffold({
     const tDir = path.join(pkgDir, 'templates');
     fs.mkdirSync(tDir, {recursive: true});
     fs.writeFileSync(
-      path.join(tDir, 'hero.doc.mjs'),
-      `export default { type: 'block', name: 'Hero', description: 'A hero' };\n`,
+      path.join(tDir, `${templateId}.doc.mjs`),
+      `export default { type: '${templateType}', name: 'Fixture template', description: 'A fixture template'${templateReplaces == null ? '' : `, replaces: ${JSON.stringify(templateReplaces)}`} };\n`,
     );
     fs.writeFileSync(
-      path.join(tDir, 'hero.tsx'),
-      `export default function Hero() { return null; }\n`,
+      path.join(tDir, `${templateId}.tsx`),
+      `export default function FixtureTemplate() { return null; }\n`,
     );
   }
 
@@ -163,7 +167,7 @@ function scaffoldLocalPackage({name = '@acme/local'} = {}) {
 
   fs.mkdirSync(path.join(tmpDir, 'templates'));
   fs.writeFileSync(
-    path.join(tmpDir, 'templates', 'local-page.template.mjs'),
+    path.join(tmpDir, 'templates', 'local-page.doc.mjs'),
     `export default {type: 'page', name: 'Local page', description: 'Local page.'};\n`,
   );
   fs.writeFileSync(
@@ -181,21 +185,8 @@ function scaffoldLocalPackage({name = '@acme/local'} = {}) {
 
   fs.mkdirSync(path.join(tmpDir, 'themes', 'ocean'), {recursive: true});
   fs.writeFileSync(
-    path.join(tmpDir, 'themes', 'manifest.json'),
-    JSON.stringify({
-      version: 1,
-      themes: [
-        {
-          slug: 'ocean',
-          displayName: 'Ocean',
-          description: 'Ocean theme.',
-          maintained: true,
-          entry: 'oceanTheme.ts',
-          exportName: 'oceanTheme',
-          files: ['oceanTheme.ts'],
-        },
-      ],
-    }),
+    path.join(tmpDir, 'themes', 'ocean', 'oceanTheme.doc.mjs'),
+    `/** @type {import('@astryxdesign/cli/authoring').ThemeDoc} */\nexport default {type: 'theme', name: 'ocean', displayName: 'Ocean', description: 'Ocean theme.', maintained: true};\n`,
   );
   fs.writeFileSync(
     path.join(tmpDir, 'themes', 'ocean', 'oceanTheme.ts'),
@@ -337,6 +328,91 @@ describe('Project discovery', () => {
     expect(hero.type).toBe('block');
   });
 
+  it('templates() projects a valid integration replacement instead of its Core target', async () => {
+    const corePage = (await discoverCoreTemplates()).find(
+      template => template.type === 'page',
+    );
+    expect(corePage).toBeDefined();
+    scaffold({
+      templateId: 'acme-app-shell',
+      templateType: 'page',
+      templateReplaces: corePage.dirName,
+    });
+    const project = await Project.load(tmpDir);
+
+    const templates = await project.templates();
+
+    expect(
+      templates.find(template => template.dirName === 'acme-app-shell'),
+    ).toMatchObject({
+      package: '@acme/widgets',
+      replaces: corePage.dirName,
+    });
+    expect(
+      templates.find(
+        template =>
+          template.dirName === corePage.dirName &&
+          template.package !== '@acme/widgets',
+      ),
+    ).toBeUndefined();
+    expect(await project.issues()).toEqual([]);
+  });
+
+  it('reports replacement issues regardless of discovery call order without hiding other contributions', async () => {
+    scaffold({
+      templateReplaces: 'missing-core-template',
+    });
+
+    const componentsFirst = await Project.load(tmpDir);
+    expect(
+      (await componentsFirst.components()).some(
+        component => component.package === '@acme/widgets',
+      ),
+    ).toBe(true);
+    expect(await componentsFirst.issues()).toEqual(
+      expect.arrayContaining([
+        expect.objectContaining({
+          code: 'missing_template_replacement_target',
+          package: '@acme/widgets',
+        }),
+      ]),
+    );
+
+    const issuesFirst = await Project.load(tmpDir, {fresh: true});
+    expect(await issuesFirst.issues()).toEqual(
+      expect.arrayContaining([
+        expect.objectContaining({
+          code: 'missing_template_replacement_target',
+          package: '@acme/widgets',
+        }),
+      ]),
+    );
+    expect(
+      (await issuesFirst.components()).some(
+        component => component.package === '@acme/widgets',
+      ),
+    ).toBe(true);
+    const ownTemplate = (await issuesFirst.templates()).find(
+      template =>
+        template.package === '@acme/widgets' && template.dirName === 'hero',
+    );
+    expect(ownTemplate).toBeDefined();
+    expect(ownTemplate).not.toHaveProperty('replaces');
+
+    const sharedCache = new InMemoryConfigCache();
+    const warm = await Project.load(tmpDir, {cache: sharedCache});
+    await warm.templates();
+    const cached = await Project.load(tmpDir, {cache: sharedCache});
+    expect(await cached.issues()).toEqual(
+      expect.arrayContaining([
+        expect.objectContaining({
+          code: 'missing_template_replacement_target',
+          package: '@acme/widgets',
+        }),
+      ]),
+    );
+  });
+
   it('codemods() returns core registry groups + integration groups', async () => {
     scaffold();
     const project = await Project.load(tmpDir);
@@ -481,6 +557,53 @@ describe('Project issues (skip + warn)', () => {
     expect(issues.some(i => i.package === '@acme/widgets')).toBe(true);
   });
 
+  it('keeps valid contribution kinds and siblings when others are broken', async () => {
+    const pkgDir = scaffold({brokenComponent: true});
+    fs.writeFileSync(
+      path.join(pkgDir, 'templates', 'broken.template.mjs'),
+      `export default {type: 'block', name: 'Broken', description: 'Missing source'};\n`,
+    );
+    fs.writeFileSync(
+      path.join(pkgDir, 'components', 'ValidWidget.doc.mjs'),
+      `export default {type: 'component', name: 'ValidWidget', props: []};\n`,
+    );
+    fs.writeFileSync(
+      path.join(pkgDir, 'components', 'ValidWidget.tsx'),
+      `export function ValidWidget() { return null; }\n`,
+    );
+    const project = await Project.load(tmpDir);
+
+    const templates = await project.templates();
+    const components = await project.components();
+    const issues = await project.issues();
+
+    expect(
+      templates.find(
+        template =>
+          template.dirName === 'hero' && template.package === '@acme/widgets',
+      ),
+    ).toBeDefined();
+    expect(
+      components.find(
+        component =>
+          component.name === 'ValidWidget' &&
+          component.package === '@acme/widgets',
+      ),
+    ).toBeDefined();
+    expect(
+      components.find(
+        component =>
+          component.name === 'Widget' && component.package === '@acme/widgets',
+      ),
+    ).toBeUndefined();
+    expect(issues).toEqual(
+      expect.arrayContaining([
+        expect.objectContaining({code: 'invalid_component'}),
+        expect.objectContaining({code: 'invalid_template'}),
+      ]),
+    );
+  });
+
   it('does not throw when an integration codemod is broken', async () => {
     scaffold({brokenCodemod: true});
     const project = await Project.load(tmpDir);
@@ -515,6 +638,132 @@ describe('Project issues (skip + warn)', () => {
   });
 });
 
+describe('Project loads each integration in isolation', () => {
+  /**
+   * Install a package under node_modules with the given root files.
+   * @param {string} name
+   * @param {string[]} manifests manifest basenames to write
+   */
+  function installPackage(name, manifests) {
+    const dir = path.join(tmpDir, 'node_modules', ...name.split('/'));
+    fs.mkdirSync(dir, {recursive: true});
+    fs.writeFileSync(
+      path.join(dir, 'package.json'),
+      JSON.stringify({name, version: '1.0.0'}),
+    );
+    for (const file of manifests) {
+      fs.writeFileSync(path.join(dir, file), 'export default {};\n');
+    }
+  }
+
+  /** @param {string[]} integrations */
+  function writeConfig(integrations) {
+    fs.writeFileSync(
+      path.join(tmpDir, 'astryx.config.mjs'),
+      `export default ${JSON.stringify({integrations})};\n`,
+    );
+  }
+
+  /** @param {Project} project */
+  async function widgetComponents(project) {
+    return (await project.components())
+      .filter(component => component.package === '@acme/widgets')
+      .map(component => component.name);
+  }
+
+  it.each([
+    ['is not installed', '@acme/broken', () => {}, /Install it first/],
+    [
+      'has no root manifest',
+      '@acme/broken',
+      () => installPackage('@acme/broken', []),
+      /no conventional root manifest/,
+    ],
+    [
+      'has two root manifests',
+      '@acme/broken',
+      () =>
+        installPackage('@acme/broken', [
+          'astryx.integration.mjs',
+          'astryx.integration.js',
+        ]),
+      /multiple root manifests/,
+    ],
+    [
+      'is not a bare package name',
+      '../escape',
+      () => {},
+      /Invalid integration package name/,
+    ],
+  ])(
+    'keeps the others when a configured package %s',
+    async (_label, spec, install, message) => {
+      scaffold();
+      install();
+      writeConfig([spec, '@acme/widgets']);
+
+      const project = await Project.load(tmpDir);
+
+      expect(await widgetComponents(project)).toEqual(['Widget']);
+      expect(await project.issues()).toContainEqual(
+        expect.objectContaining({
+          package: spec,
+          code: 'integration_error',
+          message: expect.stringMatching(message),
+        }),
+      );
+    },
+  );
+
+  it('keeps configured integrations when the package being authored has two root manifests', async () => {
+    scaffold();
+    fs.writeFileSync(
+      path.join(tmpDir, 'package.json'),
+      JSON.stringify({name: '@acme/local', version: '1.0.0'}),
+    );
+    fs.writeFileSync(
+      path.join(tmpDir, 'astryx.integration.mjs'),
+      'export default {};\n',
+    );
+    fs.writeFileSync(
+      path.join(tmpDir, 'astryx.integration.js'),
+      'export default {};\n',
+    );
+
+    const project = await Project.load(tmpDir);
+
+    expect(await widgetComponents(project)).toEqual(['Widget']);
+    expect(await project.issues()).toContainEqual(
+      expect.objectContaining({
+        package: '@acme/local',
+        code: 'integration_error',
+        message: expect.stringMatching(/multiple root manifests/),
+      }),
+    );
+  });
+
+  it('puts the package being authored at its configured position when the config names it', async () => {
+    scaffold();
+    scaffoldLocalPackage({name: '@acme/local'});
+    writeConfig(['@acme/local', '@acme/widgets']);
+
+    const project = await Project.load(tmpDir);
+
+    expect(
+      project.loadedIntegrations.map(integration => [
+        integration.name,
+        Boolean(integration.__local),
+      ]),
+    ).toEqual([
+      ['@acme/local', true],
+      ['@acme/widgets', false],
+    ]);
+    expect(await project.issues()).not.toContainEqual(
+      expect.objectContaining({package: '@acme/local', code: 'integration_error'}),
+    );
+  });
+});
+
 describe('Project.issuesUrl routing', () => {
   it('routes core to config.issuesUrl, falling back to the default', async () => {
     scaffold({issuesUrl: 'https://example.com/core'});

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

@@ -24,6 +24,24 @@ export function loadAuthoringSelfDocs(sources?: string[], root?: string): Promis
         error: string;
     }[];
 }>;
+/**
+ * A schema's fields as the table its section prints, each nested field on the
+ * row after its parent; null when there are none. A reference block that
+ * names some of a schema's fields includes this table of just those.
+ * @param {any[]} fields
+ * @returns {{type: 'table', headers: string[], rows: string[][]} | null}
+ */
+export function schemaFieldTable(fields: any[]): {
+    type: "table";
+    headers: string[];
+    rows: string[][];
+} | null;
+/**
+ * One self-doc as a topic section, keyed by the doc's own name.
+ * @param {any} doc
+ * @returns {import('../../authoring/doctypes/reference/type').ReferenceSection}
+ */
+export function selfDocSection(doc: any): import("../../authoring/doctypes/reference/type").ReferenceSection;
 /**
  * The `authoring` topic: one section per self-doc, in the order given.
  * @param {any[]} docs

package/foundation/discovery/authoring-self-docs.mjs

@@ -17,8 +17,8 @@
 
 import * as fs from 'node:fs';
 import * as path from 'node:path';
-import {pathToFileURL} from 'node:url';
 import {CLI_ROOT} from '../fs/paths.mjs';
+import {readDocView} from '../doc-compiler/read.mjs';
 import {
   DOC_OUTPUT_BUDGET_BYTES,
   oversizedDocSections,
@@ -31,6 +31,9 @@ export const AUTHORING_ROOT = path.join(CLI_ROOT, 'authoring');
 export const AUTHORING_SELF_DOCS = [
   'integration/integration.doc.mjs',
   'config/config.doc.mjs',
+  'debug/debug.doc.mjs',
+  'gap-report/gap-report.doc.mjs',
+  'discover/discover.doc.mjs',
   'codemod/codemod.doc.mjs',
   'identity/identity.doc.mjs',
   'doctypes/base/graph-fields.doc.mjs',
@@ -43,6 +46,7 @@ export const AUTHORING_SELF_DOCS = [
   'doctypes/reference/reference.doc.mjs',
   'doctypes/schema/schema.doc.mjs',
   'doctypes/template/template.doc.mjs',
+  'doctypes/theme/theme.doc.mjs',
 ];
 
 /** Blocks a self-doc note may carry that a topic section can render. */
@@ -59,7 +63,8 @@ export function discoverAuthoringSelfDocSources(root = AUTHORING_ROOT) {
   /** @param {string} dir */
   const walk = dir => {
     for (const entry of fs.readdirSync(dir, {withFileTypes: true})) {
-      if (entry.name === 'node_modules' || entry.name.startsWith('__')) continue;
+      if (entry.name === 'node_modules' || entry.name.startsWith('__'))
+        continue;
       const full = path.join(dir, entry.name);
       if (entry.isDirectory()) walk(full);
       else if (entry.name.endsWith('.doc.mjs')) {
@@ -86,9 +91,14 @@ export async function loadAuthoringSelfDocs(
   const failed = [];
   for (const source of sources) {
     try {
-      const mod = await import(pathToFileURL(path.join(root, source)).href);
-      const doc = mod.doc ?? mod.docs ?? mod.default;
-      if (typeof doc?.name !== 'string' || typeof doc?.description !== 'string') {
+      const doc = await readDocView(path.join(root, source), {
+        root: 'self-docs',
+        loader: 'native',
+      });
+      if (
+        typeof doc?.name !== 'string' ||
+        typeof doc?.description !== 'string'
+      ) {
         throw new Error('exports no doc with a name and a description');
       }
       loaded.push({source, doc});
@@ -124,27 +134,40 @@ function fieldRows(fields) {
   ]);
 }
 
+/**
+ * A schema's fields as the table its section prints, each nested field on the
+ * row after its parent; null when there are none. A reference block that
+ * names some of a schema's fields includes this table of just those.
+ * @param {any[]} fields
+ * @returns {{type: 'table', headers: string[], rows: string[][]} | null}
+ */
+export function schemaFieldTable(fields) {
+  const rows = fieldRows(fields);
+  return rows.length > 0
+    ? {
+        type: 'table',
+        headers: ['Field', 'Type', 'Required', 'Description'],
+        rows,
+      }
+    : null;
+}
+
 /**
  * One self-doc as a topic section, keyed by the doc's own name.
  * @param {any} doc
  * @returns {import('../../authoring/doctypes/reference/type').ReferenceSection}
  */
-function selfDocSection(doc) {
+export function selfDocSection(doc) {
   /** @type {any[]} */
   const content = [{type: 'prose', text: doc.description}];
   if (doc.appliesTo) {
     content.push({type: 'prose', text: `Applies to: ${doc.appliesTo}`});
   }
-  const rows = fieldRows(doc.fields ?? []);
-  if (rows.length > 0) {
-    content.push({
-      type: 'table',
-      headers: ['Field', 'Type', 'Required', 'Description'],
-      rows,
-    });
-  }
+  const table = schemaFieldTable(doc.fields ?? []);
+  if (table) content.push(table);
   for (const example of doc.examples ?? []) {
-    if (typeof example?.code !== 'string' || example.code.trim() === '') continue;
+    if (typeof example?.code !== 'string' || example.code.trim() === '')
+      continue;
     content.push({
       type: 'code',
       lang: example.lang ?? 'js',

package/foundation/discovery/authoring-self-docs.test.mjs

@@ -9,7 +9,14 @@ import {
   buildAuthoringTopic,
   discoverAuthoringSelfDocSources,
 } from './authoring-self-docs.mjs';
-import {problemsInTopic} from './docs-discovery.mjs';
+import {
+  GRAPH_BLOCK_TYPES,
+  GRAPH_ONLY_FIELDS,
+  problemsInTopic,
+} from './docs-discovery.mjs';
+import {doc as graphFieldsDoc} from '../../authoring/doctypes/base/graph-fields.doc.mjs';
+import {doc as namespaceDoc} from '../../authoring/doctypes/namespace/namespace.doc.mjs';
+import {doc as referenceDoc} from '../../authoring/doctypes/reference/reference.doc.mjs';
 import {docs} from '../../api/docs/docs.mjs';
 
 const SLOW = 60_000;
@@ -37,14 +44,74 @@ describe('authoring self-docs', () => {
     expect(topic.sections).toHaveLength(AUTHORING_SELF_DOCS.length);
   });
 
-  it('is readable progressively through the docs API', async () => {
-    const index = await docs('authoring', undefined, {index: true});
-    expect(index.type).toBe('docs.index');
-    expect(index.data.sections.map(s => s.id)).toContain('integration');
-    const section = await docs('authoring', 'integration');
-    expect(section.data.title).toBe('Astryx Integration');
-    expect(section.data.content.some(block => block.type === 'table')).toBe(true);
-  }, SLOW);
+  it(
+    'is readable progressively through the docs API',
+    async () => {
+      const index = await docs('authoring', undefined, {index: true});
+      expect(index.type).toBe('docs.index');
+      expect(index.data.sections.map(s => s.id)).toContain('integration');
+      const section = await docs('authoring', 'integration');
+      expect(section.data.title).toBe('Astryx Integration');
+      expect(section.data.content.some(block => block.type === 'table')).toBe(
+        true,
+      );
+    },
+    SLOW,
+  );
+});
+
+describe('what the authoring docs say about the docs tree', () => {
+  it('marks exactly the fields the docs tree does not read yet', () => {
+    const notReadYet = graphFieldsDoc.fields
+      .filter(field => /Not read yet/.test(field.description))
+      .map(field => field.name);
+    // The tree reads `placement` for every guide (spec:AST-046); the other
+    // graph fields are still refused by every topic reader.
+    expect(notReadYet.sort()).toEqual(
+      GRAPH_ONLY_FIELDS.filter(field => field !== 'placement').sort(),
+    );
+    for (const field of graphFieldsDoc.fields) {
+      if (GRAPH_ONLY_FIELDS.includes(field.name)) {
+        expect(field.description).toMatch(/fails to load/);
+      }
+    }
+    const placement = graphFieldsDoc.fields.find(f => f.name === 'placement');
+    expect(placement.description).toMatch(
+      /Read for every guide, the CLI's and each integration's/,
+    );
+    expect(graphFieldsDoc.description).toMatch(/not built yet/);
+  });
+
+  it('keeps graph blocks behind the separate GraphContentBlock type, and a section takes a reference block', () => {
+    const content = referenceDoc.fields
+      .flatMap(field => [field, ...(field.fields ?? [])])
+      .find(field => field.name === 'sections[].content');
+    expect(content.type).toBe('(ReferenceContentBlock | ReferenceDocBlock)[]');
+    expect(content.description).toContain('GraphContentBlock');
+    for (const type of GRAPH_BLOCK_TYPES) {
+      expect(content.description).toContain(type);
+    }
+    // A section's reference block reads as the doc it includes.
+    expect(GRAPH_BLOCK_TYPES.has('reference')).toBe(false);
+    expect(content.description).toMatch(
+      /A `reference` block .* includes another doc/,
+    );
+  });
+
+  it('says where namespace docs live: the CLI tree, and each integration', () => {
+    expect(namespaceDoc.description).toMatch(
+      /an integration ships its own in its docs directory/,
+    );
+    expect(
+      problemsInTopic({
+        ...namespaceDoc.examples?.[0],
+        type: 'namespace',
+        name: 'x',
+      }),
+    ).toEqual([
+      '"x" is a namespace doc, which the docs tree reads, not the topic list. The CLI keeps its own in assets/docs/tree; an integration ships its namespace docs in its docs directory.',
+    ]);
+  });
 });
 
 describe('auditAuthoringSelfDocs', () => {
@@ -68,17 +135,25 @@ describe('auditAuthoringSelfDocs', () => {
       path.join(root, 'kept', 'forgotten.doc.mjs'),
       "export const doc = {name: 'forgotten', description: 'Not listed.'};\n",
     );
-    const audit = await auditAuthoringSelfDocs({root, sources: ['kept/kept.doc.mjs']});
+    const audit = await auditAuthoringSelfDocs({
+      root,
+      sources: ['kept/kept.doc.mjs'],
+    });
     expect(audit.unreachable).toEqual(['kept/forgotten.doc.mjs']);
   });
 
   it('reports a self-doc that fails to load instead of throwing', async () => {
-    fs.writeFileSync(path.join(root, 'kept', 'broken.doc.mjs'), 'export const doc = {;\n');
+    fs.writeFileSync(
+      path.join(root, 'kept', 'broken.doc.mjs'),
+      'export const doc = {;\n',
+    );
     const audit = await auditAuthoringSelfDocs({
       root,
       sources: ['kept/kept.doc.mjs', 'kept/broken.doc.mjs'],
     });
-    expect(audit.failed.map(entry => entry.source)).toEqual(['kept/broken.doc.mjs']);
+    expect(audit.failed.map(entry => entry.source)).toEqual([
+      'kept/broken.doc.mjs',
+    ]);
     expect(audit.sections).toBe(1);
   });
 

package/foundation/discovery/authoring-surface.d.mts

@@ -0,0 +1,74 @@
+// @generated by scripts/sync-api-types.mjs from the JSDoc in foundation/**/*.mjs.
+// DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
+
+/**
+ * Every type `@astryxdesign/cli/authoring` exports, in the order index.d.ts
+ * lists them, each traced to the module that declares it. A value export that
+ * traces to a JavaScript module (a parser) is not a type and is left out;
+ * anything else that cannot be traced is reported, never dropped.
+ * @param {string} [root]
+ * @returns {{
+ *   types: {name: string, module: string}[],
+ *   untraced: {name: string, reason: string}[],
+ * }} `module` is relative to `root`
+ */
+export function tracePublicAuthoringTypes(root?: string): {
+    types: {
+        name: string;
+        module: string;
+    }[];
+    untraced: {
+        name: string;
+        reason: string;
+    }[];
+};
+/**
+ * What stands between each type `@astryxdesign/cli/authoring` exports and a
+ * reader of `astryx docs authoring`. A type is readable when a self-doc beside
+ * the module that declares it is listed in AUTHORING_SELF_DOCS, loads, and
+ * renders a section the topic's index lists. A registered self-doc must
+ * document something public: a public type declared beside it, and, when its
+ * title is the name of a type declared beside it, that type.
+ * @param {{root?: string, sources?: string[], topicKeys?: Set<string> | null}} [options]
+ *   `topicKeys` are the keys `astryx docs authoring --index` lists; null skips
+ *   that comparison.
+ * @returns {Promise<{
+ *   types: number,
+ *   unreadable: {module: string, names: string[], reason: UnreadableReason, source?: string, key?: string}[],
+ *   untraced: {name: string, reason: string}[],
+ *   unmatched: {source: string, key?: string, subject?: string}[],
+ * }>}
+ */
+export function auditAuthoringSurface({ root, sources, topicKeys, }?: {
+    root?: string;
+    sources?: string[];
+    topicKeys?: Set<string> | null;
+}): Promise<{
+    types: number;
+    unreadable: {
+        module: string;
+        names: string[];
+        reason: UnreadableReason;
+        source?: string;
+        key?: string;
+    }[];
+    untraced: {
+        name: string;
+        reason: string;
+    }[];
+    unmatched: {
+        source: string;
+        key?: string;
+        subject?: string;
+    }[];
+}>;
+/** The barrel the `types` condition of `@astryxdesign/cli/authoring` names. */
+export const AUTHORING_SURFACE: "index.d.ts";
+export type Tracer = {
+    root: string;
+    /**
+     * top-level statements by absolute path
+     */
+    parsed: Map<string, any[]>;
+};
+export type UnreadableReason = "no-self-doc" | "unregistered" | "failed" | "missing-section";