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

package/api/docs/detail/section/section.test.mjs

@@ -10,7 +10,7 @@
 import {describe, it, expect} from 'vitest';
 import {section} from './section.mjs';
 import {AstryxError} from '../../../error.mjs';
-import {loadDocsCatalog, loadTopicDoc} from '../../_adapter.mjs';
+import {loadDocsCatalog, lowerTopic} from '../../_adapter.mjs';
 
 const SLOW = 30_000;
 
@@ -42,7 +42,8 @@ describe('docs.detail.section leaf', () => {
   }, SLOW);
 
   it('reads a section by its stable key', async () => {
-    const doc = await loadTopicDoc((await loadDocsCatalog()).resolve('theme'));
+    const catalog = await loadDocsCatalog();
+    const {doc} = await lowerTopic(catalog, catalog.resolve('theme'));
     const target = doc.sections[doc.sections.length - 1];
     const res = await section('theme', target.id);
     expect(res.data.title).toBe(target.title);
@@ -63,7 +64,7 @@ describe('docs.detail.section leaf', () => {
       const catalog = await loadDocsCatalog();
       let checked = 0;
       for (const entry of catalog.entries()) {
-        const doc = await loadTopicDoc(entry);
+        const {doc} = await lowerTopic(catalog, entry);
         for (const own of doc.sections) {
           if (!own.content.some(block => block.type === 'token-ref')) continue;
           const res = await section(entry.name, own.id, lang ? {lang} : {});

package/api/docs/docs.doc.mjs

@@ -11,6 +11,7 @@ export const doc = {
   type: 'function',
   kind: 'api',
   name: 'docs',
+  namespace: 'cli/api',
   displayName: 'docs()',
   summary:
     'Read the reference docs: list every topic, one topic\'s sections, one section, or a whole topic.',

package/api/docs/docs.type.d.mts

@@ -2,7 +2,7 @@
 // DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
 
 /**
- * xds --json docs
+ * astryx --json docs
  */
 export type DocsListResponse = {
     type: "docs.list";
@@ -23,14 +23,14 @@ export type DocsListEntry = {
     replaces?: string | undefined;
 };
 /**
- * xds --json docs <topic> --index
+ * astryx --json docs <topic> --index
  */
 export type DocsIndexResponse = {
     type: "docs.index";
     data: DocsIndex;
 };
 /**
- * xds --json docs <topic>
+ * astryx --json docs <topic>
  */
 export type DocsDetailResponse = {
     type: "docs.detail";
@@ -62,7 +62,7 @@ export type DocsIndexSection = {
     summary: string;
 };
 /**
- * xds --json docs <topic> <section>
+ * astryx --json docs <topic> <section>
  */
 export type DocsDetailSectionResponse = {
     type: "docs.detail.section";

package/api/docs/docs.type.mjs

@@ -4,17 +4,17 @@
  * @file Colocated types for the `docs` command — source of truth for the docs
  *   command JSON responses. `types/docs.d.ts` re-exports these.
  *
- *   Invocation                          -> type discriminator
+ *   Invocation                           -> type discriminator
  *   ------------------------------------------------------------
- *   xds --json docs                     -> docs.list
- *   xds --json docs <topic>             -> docs.detail
- *   xds --json docs <topic> --index     -> docs.index
- *   xds --json docs <topic> <section>   -> docs.detail.section
- *   (unknown topic/section)             -> CLIError
+ *   astryx --json docs                   -> docs.list
+ *   astryx --json docs <topic>           -> docs.detail
+ *   astryx --json docs <topic> --index   -> docs.index
+ *   astryx --json docs <topic> <section> -> docs.detail.section
+ *   (unknown topic/section)              -> CLIError
  */
 
 /**
- * xds --json docs
+ * astryx --json docs
  * @typedef {object} DocsListResponse
  * @property {'docs.list'} type
  * @property {DocsListEntry[]} data
@@ -31,14 +31,14 @@
  */
 
 /**
- * xds --json docs <topic> --index
+ * astryx --json docs <topic> --index
  * @typedef {object} DocsIndexResponse
  * @property {'docs.index'} type
  * @property {DocsIndex} data
  */
 
 /**
- * xds --json docs <topic>
+ * astryx --json docs <topic>
  * @typedef {object} DocsDetailResponse
  * @property {'docs.detail'} type
  * @property {import('@astryxdesign/cli/authoring').ReferenceDoc} data
@@ -63,7 +63,7 @@
  */
 
 /**
- * xds --json docs <topic> <section>
+ * astryx --json docs <topic> <section>
  * @typedef {object} DocsDetailSectionResponse
  * @property {'docs.detail.section'} type
  * @property {import('@astryxdesign/cli/authoring').ReferenceSection} data

package/api/docs/index/index.mjs

@@ -3,8 +3,9 @@
 /**
  * @file docs.index leaf — the section index of one topic.
  *
- * @input A topic name plus optional {lang, zh, dense, cwd}. Resolves and loads
- *   the topic via the shared adapter.
+ * @input A topic name plus optional {lang, zh, dense, cwd}. Resolves the topic
+ *   via the shared adapter and reads its lowered compiled node; nothing is
+ *   linked, since the index never inlines a token reference.
  * @output { type: 'docs.index', data: DocsIndex } — the topic's name, title and
  *   description and, for each section, the key it is read by, its title, and a
  *   one-line summary. Matches `astryx --json docs <topic> --index`.
@@ -13,7 +14,7 @@
  *   read, is the detail leaf.
  */
 
-import {buildDocsIndexData} from '../../../foundation/discovery/docs-section-key.mjs';
+import {indexView} from '../../../foundation/doc-compiler/lenses.mjs';
 import {resolveTopicDocs} from '../_adapter.mjs';
 
 /**
@@ -26,6 +27,6 @@ import {resolveTopicDocs} from '../_adapter.mjs';
  * @returns {Promise<import('../docs.type.mjs').DocsIndexResponse>}
  */
 export async function index(topic, options = {}) {
-  const {docsData} = await resolveTopicDocs(topic, options);
-  return {type: 'docs.index', data: buildDocsIndexData(docsData)};
+  const {node} = await resolveTopicDocs(topic, options);
+  return {type: 'docs.index', data: indexView(node)};
 }

package/api/docs/list/list.mjs

@@ -14,7 +14,7 @@
  * @position Leaf under api/docs. Sibling of detail; both share _adapter.mjs.
  */
 
-import {pathToFileURL} from 'node:url';
+import {loadTopicFile} from '../../../foundation/doc-compiler/read.mjs';
 import {loadDocsCatalog} from '../_adapter.mjs';
 
 /**
@@ -29,12 +29,8 @@ export async function list({cwd} = {}) {
   for (const entry of catalog.entries()) {
     let description = entry.description ?? '';
     if (entry.description == null) {
-      try {
-        const mod = await import(pathToFileURL(entry.path).href);
-        description = (mod.docs ?? mod.default)?.description ?? '';
-      } catch {
-        description = '';
-      }
+      const file = await loadTopicFile(entry.path, null);
+      description = file.doc?.description ?? '';
     }
     /** @type {import('../docs.type.mjs').DocsListEntry} */
     const listed = {

package/api/doctor/doctor.d.mts

@@ -100,12 +100,34 @@ export function checkPackageManager(ctx: DoctorContext): DoctorCheck;
 export function checkProviderIdentity(ctx: DoctorContext): DoctorCheck;
 /**
  * Every authoring self-doc is reachable from `astryx docs authoring`, loads,
- * and fits in one read. The audit is imported here, inside the try, so a
- * malformed self-doc is reported rather than taking Doctor down.
+ * and fits in one read, and every type `@astryxdesign/cli/authoring` exports
+ * has its doc there: the self-doc beside the module that declares it. The
+ * audits are imported here, inside the try, so a malformed self-doc is
+ * reported rather than taking Doctor down.
  * @param {DoctorContext} [_ctx]
+ * @param {{root?: string, sources?: string[], topicKeys?: Set<string> | null}} [options]
+ *   Another authoring tree, list, or topic index to audit (for tests).
  * @returns {Promise<DoctorCheck>}
  */
-export function checkAuthoringDocs(_ctx?: DoctorContext): Promise<DoctorCheck>;
+export function checkAuthoringDocs(_ctx?: DoctorContext, options?: {
+    root?: string;
+    sources?: string[];
+    topicKeys?: Set<string> | null;
+}): Promise<DoctorCheck>;
+/**
+ * Every command, API function, schema, and enum doc the CLI ships declares a
+ * namespace, and the topic that namespace names reads it: `astryx docs cli`
+ * for `cli/commands` and `cli/api`, `astryx docs authoring` for `authoring`.
+ * @param {DoctorContext | Partial<DoctorContext>} _ctx
+ * @param {{root?: string, sources?: string[], authoringSources?: string[]}} [options]
+ *   test seams: the CLI root, the docs to audit, and the authoring topic's list
+ * @returns {Promise<DoctorCheck>}
+ */
+export function checkCliDocs(_ctx: DoctorContext | Partial<DoctorContext>, options?: {
+    root?: string;
+    sources?: string[];
+    authoringSources?: string[];
+}): Promise<DoctorCheck>;
 /**
  * Every topic reads progressively, in every language it ships: it loads, its
  * section index and each of its sections fit in one read, and no contributed

package/api/doctor/doctor.doc.mjs

@@ -11,6 +11,7 @@ export const doc = {
   type: 'function',
   kind: 'api',
   name: 'doctor',
+  namespace: 'cli/api',
   displayName: 'doctor()',
   summary: 'Read-only project + environment health check.',
   description:

package/api/doctor/doctor.mjs

@@ -34,8 +34,8 @@ import {
   docsIndexBytes,
   oversizedDocSections,
 } from '../../foundation/discovery/docs-output-budget.mjs';
-import {loadTopicDoc, overlayLanguages} from '../docs/_adapter.mjs';
-import {resolveTokenRefs} from '../docs/detail/detail.mjs';
+import {compileTopic, lowerTopic, overlayLanguages} from '../docs/_adapter.mjs';
+import {detailView, indexView} from '../../foundation/doc-compiler/lenses.mjs';
 import {semverCompare, isValidSemver, satisfiesRange} from '../../foundation/env/semver.mjs';
 
 /**
@@ -721,38 +721,144 @@ function joinProblems(problems) {
     : `${problems.length} problems: ${problems.join('; ')}`;
 }
 
+/** How the self-doc audit's problems are fixed. */
+const AUTHORING_DOCS_FIX =
+  'List every authoring self-doc in AUTHORING_SELF_DOCS, fix the one that fails to load, and split a section that is too large.';
+
+/** How the public-surface audit's problems are fixed. */
+const AUTHORING_SURFACE_FIX =
+  'Put a self-doc beside each module whose types @astryxdesign/cli/authoring exports and list it in AUTHORING_SELF_DOCS; export what each listed self-doc documents, or remove that self-doc.';
+
+/** Types one problem names before it counts the rest. */
+const NAMED_TYPES = 40;
+
+/**
+ * @param {string[]} names
+ * @returns {string}
+ */
+function nameTypes(names) {
+  return names.length <= NAMED_TYPES
+    ? names.join(', ')
+    : `${names.slice(0, NAMED_TYPES).join(', ')} and ${names.length - NAMED_TYPES} more`;
+}
+
+/**
+ * The section keys `astryx docs authoring --index` lists, read the way that
+ * command reads them.
+ * @returns {Promise<{keys: Set<string>} | {keys: null, error: string}>}
+ */
+async function authoringTopicKeys() {
+  try {
+    const catalog = DocsCatalog.fromBuiltins();
+    const entry = catalog.resolve('authoring');
+    if (!entry) return {keys: null, error: 'it is not a built-in topic'};
+    const index = indexView(await lowerTopic(catalog, entry));
+    return {keys: new Set(index.sections.map(section => section.id))};
+  } catch (err) {
+    return {
+      keys: null,
+      error: err instanceof Error ? err.message : String(err),
+    };
+  }
+}
+
+/**
+ * @param {Awaited<ReturnType<typeof import('../../foundation/discovery/authoring-surface.mjs').auditAuthoringSurface>>} surface
+ * @returns {string[]}
+ */
+function surfaceProblems(surface) {
+  /** @type {string[]} */
+  const problems = [];
+  if (surface.types === 0 && surface.untraced.length === 0) {
+    problems.push(
+      '@astryxdesign/cli/authoring exports no types, so nothing was compared with `astryx docs authoring`',
+    );
+  }
+  for (const {module, names, reason, source, key} of surface.unreadable) {
+    const why =
+      reason === 'no-self-doc'
+        ? `no self-doc sits beside ${module}`
+        : reason === 'unregistered'
+          ? `${source} is not listed in AUTHORING_SELF_DOCS`
+          : reason === 'failed'
+            ? `${source} does not load`
+            : `${source} renders section "${key}", which the topic's index does not list`;
+    problems.push(
+      `${nameTypes(names)} from ${module} ${names.length === 1 ? 'has' : 'have'} no doc in \`astryx docs authoring\`: ${why}`,
+    );
+  }
+  for (const {name, reason} of surface.untraced) {
+    problems.push(
+      `${name} cannot be traced to the module that declares it: ${reason}`,
+    );
+  }
+  for (const {source, subject} of surface.unmatched) {
+    problems.push(
+      subject
+        ? `${source} documents ${subject}, which @astryxdesign/cli/authoring does not export`
+        : `${source} documents no type @astryxdesign/cli/authoring exports`,
+    );
+  }
+  return problems;
+}
+
 /**
  * Every authoring self-doc is reachable from `astryx docs authoring`, loads,
- * and fits in one read. The audit is imported here, inside the try, so a
- * malformed self-doc is reported rather than taking Doctor down.
+ * and fits in one read, and every type `@astryxdesign/cli/authoring` exports
+ * has its doc there: the self-doc beside the module that declares it. The
+ * audits are imported here, inside the try, so a malformed self-doc is
+ * reported rather than taking Doctor down.
  * @param {DoctorContext} [_ctx]
+ * @param {{root?: string, sources?: string[], topicKeys?: Set<string> | null}} [options]
+ *   Another authoring tree, list, or topic index to audit (for tests).
  * @returns {Promise<DoctorCheck>}
  */
-export async function checkAuthoringDocs(_ctx) {
+export async function checkAuthoringDocs(_ctx, options = {}) {
   const id = 'authoring-docs';
   const label = 'Authoring docs';
   try {
-    const {auditAuthoringSelfDocs} = await import(
-      '../../foundation/discovery/authoring-self-docs.mjs'
-    );
-    const audit = await auditAuthoringSelfDocs();
+    const {auditAuthoringSelfDocs} =
+      await import('../../foundation/discovery/authoring-self-docs.mjs');
+    const {auditAuthoringSurface} =
+      await import('../../foundation/discovery/authoring-surface.mjs');
+    const {root, sources} = options;
+    const audit = await auditAuthoringSelfDocs({root, sources});
     const problems = [
       ...audit.unreachable.map(
         source => `${source} is not in \`astryx docs authoring\``,
       ),
-      ...audit.failed.map(({source, error}) => `${source} failed to load: ${error}`),
+      ...audit.failed.map(
+        ({source, error}) => `${source} failed to load: ${error}`,
+      ),
       ...audit.oversized.map(
         ({key, bytes}) =>
           `authoring section "${key}" is ${kilobytes(bytes)}, over the ${kilobytes(DOC_OUTPUT_BUDGET_BYTES)} one read may return`,
       ),
     ];
-    if (problems.length > 0) {
+    const topic =
+      options.topicKeys === undefined
+        ? await authoringTopicKeys()
+        : {keys: options.topicKeys};
+    const surface = [
+      ...('error' in topic
+        ? [`\`astryx docs authoring\` could not be read: ${topic.error}`]
+        : []),
+      ...surfaceProblems(
+        await auditAuthoringSurface({root, sources, topicKeys: topic.keys}),
+      ),
+    ];
+    if (problems.length + surface.length > 0) {
       return {
         id,
         label,
         status: 'fail',
-        message: joinProblems(problems),
-        fix: 'List every authoring self-doc in AUTHORING_SELF_DOCS, fix the one that fails to load, and split a section that is too large.',
+        message: joinProblems([...problems, ...surface]),
+        fix: [
+          problems.length > 0 ? AUTHORING_DOCS_FIX : null,
+          surface.length > 0 ? AUTHORING_SURFACE_FIX : null,
+        ]
+          .filter(Boolean)
+          .join(' '),
       };
     }
     return {
@@ -772,6 +878,71 @@ export async function checkAuthoringDocs(_ctx) {
   }
 }
 
+/** How the CLI-docs audit's problems are fixed. */
+const CLI_DOCS_FIX =
+  "Set `namespace` on each CLI doc to the one that reads it: cli/commands for a command, cli/api for an API function or the output schema, error codes, and response types, and authoring for a file an author writes (and list it in AUTHORING_SELF_DOCS).";
+
+/**
+ * Every command, API function, schema, and enum doc the CLI ships declares a
+ * namespace, and the topic that namespace names reads it: `astryx docs cli`
+ * for `cli/commands` and `cli/api`, `astryx docs authoring` for `authoring`.
+ * @param {DoctorContext | Partial<DoctorContext>} _ctx
+ * @param {{root?: string, sources?: string[], authoringSources?: string[]}} [options]
+ *   test seams: the CLI root, the docs to audit, and the authoring topic's list
+ * @returns {Promise<DoctorCheck>}
+ */
+export async function checkCliDocs(_ctx, options = {}) {
+  const id = 'cli-docs';
+  const label = 'CLI docs';
+  try {
+    const {auditCliSelfDocs} =
+      await import('../../foundation/discovery/cli-self-docs.mjs');
+    const audit = await auditCliSelfDocs(options);
+    const problems = [
+      ...audit.missing.map(
+        source =>
+          `${source} has no namespace, so no \`astryx docs\` topic reads it`,
+      ),
+      ...audit.unknown.map(
+        ({source, namespace}) =>
+          `${source} has namespace "${namespace}", which no \`astryx docs\` topic reads`,
+      ),
+      ...audit.misfiled.map(({message}) => message),
+      ...audit.failed.map(
+        ({source, error}) => `${source} failed to load: ${error}`,
+      ),
+      ...audit.keyProblems.map(problem => `\`astryx docs cli\`: ${problem}`),
+      ...audit.oversized.map(
+        ({key, bytes}) =>
+          `cli section "${key}" is ${kilobytes(bytes)}, over the ${kilobytes(DOC_OUTPUT_BUDGET_BYTES)} one read may return`,
+      ),
+    ];
+    if (problems.length > 0) {
+      return {
+        id,
+        label,
+        status: 'fail',
+        message: joinProblems(problems),
+        fix: CLI_DOCS_FIX,
+      };
+    }
+    return {
+      id,
+      label,
+      status: 'pass',
+      message: `All ${audit.docs} CLI docs are readable: ${audit.sections} in \`astryx docs cli\` and ${audit.authoring} in \`astryx docs authoring\`.`,
+    };
+  } catch (err) {
+    return {
+      id,
+      label,
+      status: 'fail',
+      message: `The CLI docs could not be audited: ${err instanceof Error ? err.message : String(err)}`,
+      fix: 'Reinstall @astryxdesign/cli.',
+    };
+  }
+}
+
 /**
  * Every topic reads progressively, in every language it ships: it loads, its
  * section index and each of its sections fit in one read, and no contributed
@@ -798,11 +969,7 @@ export async function checkDocsProgressiveDisclosure(ctx) {
       for (const lang of [null, ...overlayLanguages(entry)]) {
         const where = lang ? `${entry.name} [${lang}]` : entry.name;
         try {
-          const doc = await resolveTokenRefs(
-            await loadTopicDoc(entry, {lang}),
-            catalog,
-            {lang},
-          );
+          const doc = detailView(await compileTopic(catalog, entry, lang));
           if (lang == null) topics += 1;
           const indexBytes = docsIndexBytes(buildDocsIndexData(doc));
           if (indexBytes > DOC_OUTPUT_BUDGET_BYTES) {
@@ -933,6 +1100,7 @@ export async function runChecks(options = {}) {
     }
   }
   checks.push(await checkAuthoringDocs(ctx));
+  checks.push(await checkCliDocs(ctx));
   checks.push(await checkDocsProgressiveDisclosure(ctx));
 
   const summary = {pass: 0, warn: 0, fail: 0, info: 0};