@astryxdesign/cli 0.6.3-canary.ea2f048 → 0.6.3-canary.ebaebc4

package/clients/cli/formatters/index.mjs

@@ -11,7 +11,8 @@
  * which fields to show and in what order.
  *
  * Constraints (deliberately narrow):
- *   - Plain ASCII only. No color, no TTY detection, no width wrapping. Output is
+ *   - Plain ASCII only. No color and no TTY detection. Long lines wrap at a
+ *     fixed {@link WRAP_WIDTH}, never at the terminal's width, so output is
  *     byte-for-byte deterministic whether printed or piped to an agent.
  *   - Renderers return an opaque {@link Block}; `emit` accepts ONLY Blocks, so a
  *     stray string can't leak onto stdout (the compiler rejects `emit('x')`).
@@ -33,6 +34,50 @@ export const BULLET = '-';
 export const ERR = '!!';
 export const WARN = '!';
 
+/** The column long human-output lines wrap at. */
+export const WRAP_WIDTH = 120;
+
+/** The widest first column an inline record pads to; a longer value overhangs. */
+const INLINE_LEAD_MAX = 32;
+
+/**
+ * Characters a terminal draws two columns wide: CJK ideographs and
+ * punctuation, kana, hangul, and fullwidth forms. A line may break between
+ * any two of them.
+ */
+const WIDE_CHAR =
+  /[\u1100-\u115f\u2e80-\u303e\u3041-\u33ff\u3400-\u4dbf\u4e00-\u9fff\ua000-\ua4cf\uac00-\ud7a3\uf900-\ufaff\ufe30-\ufe4f\uff00-\uff60\uffe0-\uffe6]/u;
+
+/**
+ * How many terminal columns a string takes.
+ * @param {string} s
+ * @returns {number}
+ */
+export function displayWidth(s) {
+  let width = 0;
+  for (const ch of String(s)) width += WIDE_CHAR.test(ch) ? 2 : 1;
+  return width;
+}
+
+/**
+ * Cut a line to `width` columns, ending it with `...` when anything was cut.
+ * @param {string} line
+ * @param {number} width
+ * @returns {string}
+ */
+function truncateToWidth(line, width) {
+  if (displayWidth(line) <= width) return line;
+  let out = '';
+  let used = 0;
+  for (const ch of line) {
+    const w = WIDE_CHAR.test(ch) ? 2 : 1;
+    if (used + w > width - 3) break;
+    out += ch;
+    used += w;
+  }
+  return `${out.trimEnd()}...`;
+}
+
 /**
  * An opaque, renderer-produced block of output. Nominal via a private field:
  * nothing outside this file can construct one, so `emit` can trust that whatever
@@ -67,6 +112,13 @@ export class Block {
  * @property {Record<string, string>} [labels] - Rename a key for display.
  * @property {Record<string, (value: any) => string>} [format] - Transform a
  *   value before rendering (e.g. prefix a command with the package manager).
+ * @property {'stacked' | 'inline'} [layout] - `stacked` (the default): one
+ *   `key: value` line per field, a blank line between records. `inline`: one
+ *   record per line, the first field in a padded column and the rest joined by
+ *   ` - `, for a list a reader scans.
+ * @property {'wrap' | 'truncate'} [overflow] - What an inline record longer
+ *   than {@link WRAP_WIDTH} does: `wrap` (the default) continues under the
+ *   first column; `truncate` cuts it to one line.
  */
 
 /** @param {unknown} v @returns {boolean} */
@@ -103,6 +155,72 @@ function toAscii(s) {
     .replace(/\u00a0/g, ' ');
 }
 
+/**
+ * Word-wrap text at `width`, keeping its own line breaks. A word longer than
+ * the width stays whole on a line of its own. Continuation lines start with
+ * `indent`.
+ * @param {string} input
+ * @param {{width?: number, indent?: string}} [options]
+ * @returns {string}
+ */
+export function wrapText(input, {width = WRAP_WIDTH, indent = ''} = {}) {
+  return String(input)
+    .split('\n')
+    .map(line => wrapLine(line, width, indent))
+    .join('\n');
+}
+
+/**
+ * @param {string} line
+ * @param {number} width
+ * @param {string} indent
+ * @returns {string}
+ */
+function wrapLine(line, width, indent) {
+  if (displayWidth(line) <= width) return line;
+  const lead = /^\s*/.exec(line)?.[0] ?? '';
+  // Tokens a line may break between: words, and each wide character on its
+  // own, since CJK text has no spaces to break at. `gap` is what joined a
+  // token to the one before it.
+  /** @type {{text: string, gap: string}[]} */
+  const tokens = [];
+  let gap = '';
+  let word = '';
+  const flush = () => {
+    if (word === '') return;
+    tokens.push({text: word, gap});
+    gap = '';
+    word = '';
+  };
+  for (const ch of line.slice(lead.length)) {
+    if (ch === ' ') {
+      flush();
+      gap = ' ';
+    } else if (WIDE_CHAR.test(ch)) {
+      flush();
+      tokens.push({text: ch, gap});
+      gap = '';
+    } else {
+      word += ch;
+    }
+  }
+  flush();
+  /** @type {string[]} */
+  const out = [];
+  let current = lead;
+  tokens.forEach(({text: token, gap: before}, i) => {
+    const joined = i === 0 ? current + token : current + before + token;
+    if (i > 0 && displayWidth(joined) > width && current.trim() !== '') {
+      out.push(current);
+      current = indent + token;
+    } else {
+      current = joined;
+    }
+  });
+  out.push(current);
+  return out.join('\n');
+}
+
 /**
  * A group label, optionally with an explanatory subtitle rendered on the line(s)
  * directly beneath the heading (no blank line between). Whatever list/records
@@ -177,10 +295,53 @@ export function record(obj, options = {}) {
  * @returns {Block}
  */
 export function records(items, options = {}) {
+  if (options.layout === 'inline') return inlineRecords(items, options);
   const blocks = items.map(o => record(o, options).toString()).filter(Boolean);
   return new Block(blocks.join('\n\n'));
 }
 
+/**
+ * @param {any[]} items
+ * @param {RecordOptions} options
+ * @returns {Block}
+ */
+function inlineRecords(items, options) {
+  const [lead, ...rest] = (options.fields ?? Object.keys(items[0] ?? {})).filter(
+    k => !options.omit?.includes(k),
+  );
+  if (lead == null) return new Block('');
+  /** @param {any} o @param {string} k */
+  const value = (o, k) => {
+    const fmt = options.format?.[k];
+    return fmt ? fmt(o[k]) : renderValue(o[k]);
+  };
+  const leads = items.map(o => (isEmpty(o[lead]) ? '' : value(o, lead)));
+  const column = Math.min(
+    Math.max(0, ...leads.map(l => displayWidth(l))),
+    INLINE_LEAD_MAX,
+  );
+  const indent = ' '.repeat(column + 2);
+  const lines = items.map((o, i) => {
+    const tail = toAscii(
+      rest
+        .filter(k => !isEmpty(o[k]))
+        .map(k => value(o, k))
+        .join(' - '),
+    );
+    if (tail === '') return toAscii(leads[i]);
+    const head = toAscii(`${leads[i].padEnd(column)}  `);
+    if (options.overflow === 'truncate') {
+      return truncateToWidth(head + tail, WRAP_WIDTH);
+    }
+    // Wrap only the tail, so the padded first column survives the wrap.
+    const [first, ...more] = wrapText(tail, {
+      width: Math.max(20, WRAP_WIDTH - displayWidth(head)),
+    }).split('\n');
+    return [head + first, ...more.map(line => indent + line)].join('\n');
+  });
+  return new Block(lines.join('\n'));
+}
+
 /**
  * A verbatim block — source dumps, layout skeletons, or a markdown doc. Output
  * is byte-for-byte (NOT ASCII-normalized), so it survives piping

package/clients/cli/formatters/index.test.mjs

@@ -8,6 +8,9 @@ import {
   list,
   record,
   records,
+  wrapText,
+  displayWidth,
+  WRAP_WIDTH,
   code,
   Block,
   BULLET,
@@ -148,3 +151,91 @@ describe('emit', () => {
     expect(spy).not.toHaveBeenCalled();
   });
 });
+
+describe('wrapText', () => {
+  it('leaves short lines and its own line breaks alone', () => {
+    expect(wrapText('a b\nc')).toBe('a b\nc');
+  });
+
+  it('wraps at the width with a hanging indent', () => {
+    expect(wrapText('aaa bbb ccc', {width: 7, indent: '  '})).toBe('aaa bbb\n  ccc');
+  });
+
+  it('keeps a word longer than the width whole', () => {
+    expect(wrapText('x '.concat('y'.repeat(20)), {width: 10})).toBe(
+      `x\n${'y'.repeat(20)}`,
+    );
+  });
+});
+
+describe('records inline layout', () => {
+  const items = [
+    {id: 'a', title: 'Alpha', summary: 'First.'},
+    {id: 'bbb', title: 'Beta', summary: ''},
+  ];
+
+  it('puts one record on each line under a padded first column', () => {
+    expect(
+      records(items, {fields: ['id', 'title', 'summary'], layout: 'inline'}).toString(),
+    ).toBe('a    Alpha - First.\nbbb  Beta');
+  });
+
+  it('wraps a long record under the first column', () => {
+    const out = records([{id: 'a', text: 'word '.repeat(40).trim()}], {
+      layout: 'inline',
+    }).toString();
+    expect(out.split('\n').length).toBeGreaterThan(1);
+    expect(out.split('\n').every(line => line.length <= WRAP_WIDTH)).toBe(true);
+    expect(out.split('\n')[1].startsWith('   word')).toBe(true);
+  });
+
+  it('keeps the first column padded on a record that wraps', () => {
+    const out = records(
+      [
+        {id: 'a', text: 'word '.repeat(40).trim()},
+        {id: 'longer', text: 'x'},
+      ],
+      {layout: 'inline'},
+    ).toString();
+    const lines = out.split('\n');
+    expect(lines[0].startsWith(`a${' '.repeat(7)}word`)).toBe(true);
+    expect(lines[1].startsWith(' '.repeat(8) + 'word')).toBe(true);
+    expect(lines.at(-1)).toBe('longer  x');
+    expect(lines.every(line => line.length <= WRAP_WIDTH)).toBe(true);
+  });
+
+  it('cuts a long record to one line when asked', () => {
+    const out = records([{id: 'a', text: 'word '.repeat(40).trim()}], {
+      layout: 'inline',
+      overflow: 'truncate',
+    }).toString();
+    expect(out.includes('\n')).toBe(false);
+    expect(out.length).toBeLessThanOrEqual(WRAP_WIDTH);
+    expect(out.endsWith('...')).toBe(true);
+  });
+});
+
+describe('wide characters', () => {
+  it('counts CJK characters as two columns', () => {
+    expect(displayWidth('亮/暗模式')).toBe(9);
+  });
+
+  it('wraps CJK text, which has no spaces, by columns', () => {
+    const out = wrapText('中'.repeat(100), {width: 20});
+    expect(out.split('\n').every(line => displayWidth(line) <= 20)).toBe(true);
+    expect(out.split('\n')).toHaveLength(10);
+  });
+
+  it('keeps spaces between Latin words next to CJK', () => {
+    expect(wrapText('运行 astryx docs 查看', {width: 200})).toBe('运行 astryx docs 查看');
+  });
+
+  it('cuts an inline record to columns, not characters', () => {
+    const out = records([{id: 'a', text: '中'.repeat(100)}], {
+      layout: 'inline',
+      overflow: 'truncate',
+    }).toString();
+    expect(displayWidth(out)).toBeLessThanOrEqual(WRAP_WIDTH);
+    expect(out.endsWith('...')).toBe(true);
+  });
+});

package/clients/cli/lib/manifest.mjs

@@ -55,7 +55,7 @@ export const RESPONSE_TYPES = {
     'component.detail.showcase',
     'component.detail.blocks',
   ],
-  docs: ['docs.list', 'docs.detail', 'docs.detail.section'],
+  docs: ['docs.list', 'docs.index', 'docs.detail', 'docs.detail.section'],
   blog: ['blog.list', 'blog.detail'],
   discover: [
     'discover.list',
@@ -105,7 +105,12 @@ const EXAMPLES = {
     'astryx component XDSButton',
     'astryx component XDSButton --props --json',
   ],
-  docs: ['astryx docs', 'astryx docs spacing --json'],
+  docs: [
+    'astryx docs',
+    'astryx docs spacing --json',
+    'astryx docs theme --index',
+    'astryx docs theme quick-start',
+  ],
   discover: ['astryx discover --json'],
   search: [
     'astryx search modal --json',

package/foundation/config/project.mjs

@@ -38,6 +38,7 @@ import {parseConfig} from '../../authoring/config/parse.mjs';
 import {
   loadIntegrations,
   loadLocalIntegration,
+  markProviderConflicts,
 } from '../integrations/integrations.mjs';
 import {autolinkIntegrations} from '../integrations/autolink.mjs';
 import {
@@ -203,10 +204,11 @@ export class Project {
   /** @type {ProjectIntegrationIssue[]} */
   #issues = [];
   /**
-   * Package names of integrations whose issues have already been collected
-   * (via a discovery method or a direct issues() validation), so issues() can
-   * fill in only the ones not yet visited and never double-collect.
-   * @type {Set<string>}
+   * Loaded integrations whose issues have already been collected (via a
+   * discovery method or a direct issues() validation), so issues() can fill in
+   * only the ones not yet visited and never double-collect. Keyed by entry, not
+   * label: two entries can share a package name (an alias at another version).
+   * @type {Set<object>}
    */
   #visitedIssues = new Set();
 
@@ -277,6 +279,8 @@ export class Project {
       loadedIntegrations = await loadIntegrations(integrations, {
         cwd: projectDir,
         fresh,
+        // Provider identity is resolved once, below, over the final set.
+        resolveProviders: false,
       });
     }
 
@@ -310,6 +314,10 @@ export class Project {
       else loadedIntegrations[existing] = localIntegration;
     }
 
+    // Autolinked and local packages can claim a provider ID that a configured
+    // package already holds, so identity is resolved once over the final set.
+    loadedIntegrations = markProviderConflicts(loadedIntegrations);
+
     // The debug recorder resolves its settings synchronously, long before any
     // command gets here, so this is where a project's `debug` block gets a
     // turn. The event is not written until process exit, so settings applied
@@ -436,6 +444,13 @@ export class Project {
    * @returns {string}
    */
   #pkgLabel(integration) {
+    // A set-aside package is labelled name@version, so its issue never reads as
+    // the winner's, even when both share a package name.
+    if (integration?.__providerConflict) {
+      return integration.version
+        ? `${integration.name}@${integration.version}`
+        : (integration.__spec ?? integration.name);
+    }
     return integration?.name ?? integration?.__spec ?? '(integration)';
   }
 
@@ -463,8 +478,8 @@ export class Project {
    */
   async #collectIssues(integration) {
     const pkg = this.#pkgLabel(integration);
-    if (this.#visitedIssues.has(pkg)) return;
-    this.#visitedIssues.add(pkg);
+    if (this.#visitedIssues.has(integration)) return;
+    this.#visitedIssues.add(integration);
     // A manifest that failed to load (throwing import / invalid shape) is
     // recorded as a marker by loadIntegrations — surface it as an issue and
     // skip validation (there's no manifest to validate).

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

@@ -0,0 +1,69 @@
+// @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 `root`, relative and sorted.
+ * @param {string} [root]
+ * @returns {string[]}
+ */
+export function discoverAuthoringSelfDocSources(root?: string): string[];
+/**
+ * Import each self-doc. 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 loadAuthoringSelfDocs(sources?: string[], root?: string): Promise<{
+    loaded: {
+        source: string;
+        doc: any;
+    }[];
+    failed: {
+        source: string;
+        error: string;
+    }[];
+}>;
+/**
+ * The `authoring` topic: one section per self-doc, in the order given.
+ * @param {any[]} docs
+ * @returns {import('../../authoring/doctypes/reference/type').ReferenceDoc}
+ */
+export function buildAuthoringReferenceDoc(docs: any[]): import("../../authoring/doctypes/reference/type").ReferenceDoc;
+/**
+ * The `authoring` topic from every self-doc that loads. One that fails is left
+ * out here and reported by {@link auditAuthoringSelfDocs}.
+ * @returns {Promise<import('../../authoring/doctypes/reference/type').ReferenceDoc>}
+ */
+export function buildAuthoringTopic(): Promise<import("../../authoring/doctypes/reference/type").ReferenceDoc>;
+/**
+ * What stands between a self-doc and a reader of `astryx docs authoring`.
+ * @param {{root?: string, sources?: string[], budget?: number}} [options]
+ * @returns {Promise<{
+ *   sections: number,
+ *   unreachable: string[],
+ *   failed: {source: string, error: string}[],
+ *   oversized: {key: string, title: string, bytes: number}[],
+ * }>}
+ */
+export function auditAuthoringSelfDocs({ root, sources, budget, }?: {
+    root?: string;
+    sources?: string[];
+    budget?: number;
+}): Promise<{
+    sections: number;
+    unreachable: string[];
+    failed: {
+        source: string;
+        error: string;
+    }[];
+    oversized: {
+        key: string;
+        title: string;
+        bytes: number;
+    }[];
+}>;
+/** The directory the self-docs live under. */
+export const AUTHORING_ROOT: string;
+/** Every authoring self-doc, relative to {@link AUTHORING_ROOT}, in reading order. */
+export const AUTHORING_SELF_DOCS: string[];

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

@@ -0,0 +1,214 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file The authoring self-docs, and the `authoring` topic built from them.
+ *
+ * @input The SchemaDoc each authoring module colocates as `*.doc.mjs` under
+ *   packages/cli/authoring.
+ * @output {@link AUTHORING_SELF_DOCS} (every self-doc, in reading order), the
+ *   `authoring` reference topic with one section per self-doc, and an audit
+ *   naming any self-doc the topic cannot reach, any that fails to load, and any
+ *   section over the docs output budget.
+ * @position Read by assets/docs/authoring.doc.mjs (the topic) and by Doctor
+ *   (the audit). Lives in foundation because authoring/ holds only contracts.
+ *   A new `*.doc.mjs` under authoring/ must be added to the list, or Doctor and
+ *   the self-doc tests fail.
+ */
+
+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 {
+  DOC_OUTPUT_BUDGET_BYTES,
+  oversizedDocSections,
+} from './docs-output-budget.mjs';
+
+/** The directory the self-docs live under. */
+export const AUTHORING_ROOT = path.join(CLI_ROOT, 'authoring');
+
+/** Every authoring self-doc, relative to {@link AUTHORING_ROOT}, in reading order. */
+export const AUTHORING_SELF_DOCS = [
+  'integration/integration.doc.mjs',
+  'config/config.doc.mjs',
+  'codemod/codemod.doc.mjs',
+  'identity/identity.doc.mjs',
+  'doctypes/base/graph-fields.doc.mjs',
+  'doctypes/component/component.doc.mjs',
+  'doctypes/hook/hook.doc.mjs',
+  'doctypes/function/function.doc.mjs',
+  'doctypes/command/command.doc.mjs',
+  'doctypes/enum/enum.doc.mjs',
+  'doctypes/namespace/namespace.doc.mjs',
+  'doctypes/reference/reference.doc.mjs',
+  'doctypes/schema/schema.doc.mjs',
+  'doctypes/template/template.doc.mjs',
+];
+
+/** Blocks a self-doc note may carry that a topic section can render. */
+const TOPIC_BLOCKS = new Set(['prose', 'list', 'code', 'heading', 'table']);
+
+/**
+ * Every `*.doc.mjs` under `root`, relative and sorted.
+ * @param {string} [root]
+ * @returns {string[]}
+ */
+export function discoverAuthoringSelfDocSources(root = AUTHORING_ROOT) {
+  /** @type {string[]} */
+  const found = [];
+  /** @param {string} dir */
+  const walk = dir => {
+    for (const entry of fs.readdirSync(dir, {withFileTypes: true})) {
+      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')) {
+        found.push(path.relative(root, full).split(path.sep).join('/'));
+      }
+    }
+  };
+  walk(root);
+  return found.sort();
+}
+
+/**
+ * Import each self-doc. 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 async function loadAuthoringSelfDocs(
+  sources = AUTHORING_SELF_DOCS,
+  root = AUTHORING_ROOT,
+) {
+  const loaded = [];
+  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') {
+        throw new Error('exports no doc with a name and a description');
+      }
+      loaded.push({source, doc});
+    } catch (error) {
+      failed.push({
+        source,
+        error: error instanceof Error ? error.message : String(error),
+      });
+    }
+  }
+  return {loaded, failed};
+}
+
+/**
+ * @param {any[]} fields
+ * @returns {string[][]}
+ */
+function fieldRows(fields) {
+  return fields.flatMap(field => [
+    [
+      String(field.name),
+      String(field.type ?? ''),
+      field.required ? 'yes' : 'no',
+      [
+        field.description,
+        field.default != null ? `Default: ${field.default}.` : null,
+        field.example != null ? `Example: ${field.example}.` : null,
+      ]
+        .filter(Boolean)
+        .join(' '),
+    ],
+    ...fieldRows(field.fields ?? []),
+  ]);
+}
+
+/**
+ * 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) {
+  /** @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,
+    });
+  }
+  for (const example of doc.examples ?? []) {
+    if (typeof example?.code !== 'string' || example.code.trim() === '') continue;
+    content.push({
+      type: 'code',
+      lang: example.lang ?? 'js',
+      ...(example.label ? {label: example.label} : {}),
+      code: example.code,
+    });
+  }
+  for (const note of doc.notes ?? []) {
+    if (TOPIC_BLOCKS.has(note?.type)) content.push(note);
+  }
+  return {id: doc.name, title: doc.displayName ?? doc.name, content};
+}
+
+/**
+ * The `authoring` topic: one section per self-doc, in the order given.
+ * @param {any[]} docs
+ * @returns {import('../../authoring/doctypes/reference/type').ReferenceDoc}
+ */
+export function buildAuthoringReferenceDoc(docs) {
+  return /** @type {any} */ ({
+    name: 'authoring',
+    title: 'Authoring Reference',
+    category: 'guide',
+    description:
+      'Every file an integration author writes, field by field: the integration manifest, astryx.config, codemods, identity, and each doc type.',
+    sections: docs.map(selfDocSection),
+  });
+}
+
+/**
+ * The `authoring` topic from every self-doc that loads. One that fails is left
+ * out here and reported by {@link auditAuthoringSelfDocs}.
+ * @returns {Promise<import('../../authoring/doctypes/reference/type').ReferenceDoc>}
+ */
+export async function buildAuthoringTopic() {
+  const {loaded} = await loadAuthoringSelfDocs();
+  return buildAuthoringReferenceDoc(loaded.map(entry => entry.doc));
+}
+
+/**
+ * What stands between a self-doc and a reader of `astryx docs authoring`.
+ * @param {{root?: string, sources?: string[], budget?: number}} [options]
+ * @returns {Promise<{
+ *   sections: number,
+ *   unreachable: string[],
+ *   failed: {source: string, error: string}[],
+ *   oversized: {key: string, title: string, bytes: number}[],
+ * }>}
+ */
+export async function auditAuthoringSelfDocs({
+  root = AUTHORING_ROOT,
+  sources = AUTHORING_SELF_DOCS,
+  budget = DOC_OUTPUT_BUDGET_BYTES,
+} = {}) {
+  const listed = new Set(sources);
+  const unreachable = discoverAuthoringSelfDocSources(root).filter(
+    source => !listed.has(source),
+  );
+  const {loaded, failed} = await loadAuthoringSelfDocs(sources, root);
+  const topic = buildAuthoringReferenceDoc(loaded.map(entry => entry.doc));
+  return {
+    sections: topic.sections.length,
+    unreachable,
+    failed,
+    oversized: oversizedDocSections(topic.sections, budget),
+  };
+}