@astryxdesign/cli 0.7.2 → 0.7.3-canary.0bf23bd

package/foundation/discovery/runner-commands.test.mjs

@@ -0,0 +1,128 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import {fileURLToPath} from 'node:url';
+import {describe, expect, it} from 'vitest';
+
+import {
+  CLI_COMMANDS,
+  findRunnerCommands,
+  runnerCommandsIn,
+} from './runner-commands.mjs';
+
+const COMMAND_DOCS = path.resolve(
+  path.dirname(fileURLToPath(import.meta.url)),
+  '../../clients/cli/commands',
+);
+
+describe('runnerCommandsIn', () => {
+  it('finds an Astryx command after a project runner, with the bare command', () => {
+    expect(runnerCommandsIn('Run `pnpm exec astryx docs theme`.')).toEqual([
+      {written: 'pnpm exec astryx docs', bare: 'astryx docs', download: false},
+    ]);
+    expect(runnerCommandsIn('yarn astryx component Button')).toEqual([
+      {
+        written: 'yarn astryx component',
+        bare: 'astryx component',
+        download: false,
+      },
+    ]);
+  });
+
+  it('always flags the unscoped name after a download runner, even alone', () => {
+    expect(runnerCommandsIn('npx astryx doctor; or `bunx astryx`')).toEqual([
+      {written: 'npx astryx doctor', bare: 'astryx doctor', download: true},
+      {written: 'bunx astryx', bare: 'astryx', download: true},
+    ]);
+  });
+
+  it('leaves the scoped package, a project runner named alone, and other tools', () => {
+    expect(
+      runnerCommandsIn(
+        'Install with `npx @astryxdesign/cli init`. Run it through Yarn (`yarn astryx`). Format with `npx prettier --write`. `npx astryx-tools init`.',
+      ),
+    ).toEqual([]);
+  });
+
+  it('flags `bun x`, a versioned name, and a name that ends a sentence', () => {
+    expect(
+      runnerCommandsIn(
+        'Run `bun x astryx doctor`, `npx astryx@latest init` or `npx astryx@0.7.1 docs`. Or just npx astryx.',
+      ),
+    ).toEqual([
+      {written: 'bun x astryx doctor', bare: 'astryx doctor', download: true},
+      {
+        written: 'npx astryx@latest init',
+        bare: 'astryx init',
+        download: true,
+      },
+      {written: 'npx astryx@0.7.1 docs', bare: 'astryx docs', download: true},
+      {written: 'npx astryx', bare: 'astryx', download: true},
+    ]);
+    expect(
+      runnerCommandsIn('Edit astryx.config, not npx astryx.config.'),
+    ).toEqual([]);
+  });
+
+  it('reads a runner and its command within one line, and needs a CLI command after a project runner', () => {
+    expect(
+      runnerCommandsIn(
+        'Through Yarn, yarn astryx runs the copy in node_modules.\n```\npnpm astryx\nyarn astryx\n```',
+      ),
+    ).toEqual([]);
+    expect(runnerCommandsIn('npx astryx runs an unrelated package')).toEqual([
+      {written: 'npx astryx', bare: 'astryx', download: true},
+    ]);
+    expect(runnerCommandsIn('pnpm\nastryx docs')).toEqual([]);
+    expect(
+      runnerCommandsIn('Run `npx -y astryx doctor` or `npx --yes astryx`.'),
+    ).toEqual([
+      {written: 'npx -y astryx doctor', bare: 'astryx doctor', download: true},
+      {written: 'npx --yes astryx', bare: 'astryx', download: true},
+    ]);
+  });
+});
+
+describe('findRunnerCommands', () => {
+  it('reads a topic that refers back to itself once, without crashing', async () => {
+    const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'runner-self-'));
+    const file = path.join(dir, 'acme-setup.doc.mjs');
+    fs.writeFileSync(
+      file,
+      [
+        'const section = {',
+        "  title: 'Overview',",
+        "  content: [{type: 'prose', text: 'Run `yarn astryx docs` first.'}],",
+        '};',
+        "const doc = {type: 'generic', name: 'acme-setup', sections: [section]};",
+        'section.self = section;',
+        'doc.again = doc;',
+        'export default doc;',
+        '',
+      ].join('\n'),
+    );
+
+    const found = await findRunnerCommands({
+      records: [{name: 'acme-setup', path: file}],
+    });
+
+    expect(
+      found.map(({command, section, line}) => ({command, section, line})),
+    ).toEqual([{command: 'yarn astryx docs', section: 'Overview', line: 3}]);
+  });
+});
+
+describe('CLI_COMMANDS', () => {
+  it('names every top-level command the CLI documents, and nothing else', () => {
+    const documented = fs
+      .readdirSync(COMMAND_DOCS)
+      .filter(file => file.endsWith('.doc.mjs'))
+      .map(file => file.slice(0, -'.doc.mjs'.length))
+      .filter(name => !name.includes('-') || name === 'gap-report');
+    expect([...CLI_COMMANDS].sort()).toEqual(
+      [...new Set([...documented, 'help'])].sort(),
+    );
+  });
+});

package/foundation/discovery/stray-pointers.test.mjs

@@ -16,7 +16,7 @@ describe('pointersIn', () => {
   it('leaves a walkthrough alone: more words, a flag, or a route', () => {
     expect(
       pointersIn(
-        'Run `astryx docs theme overview`, `astryx docs --json`, `astryx docs cli/integrations`, or `astryx docs`.',
+        'Run `astryx docs theme overview`, `astryx docs --json`, `astryx docs authoring/quick-start`, or `astryx docs`.',
       ),
     ).toEqual([]);
   });

package/foundation/discovery/template-adapter.mjs

@@ -1192,6 +1192,23 @@ function reportSamePackageReplacements(pkg, autolinked, templates, errors) {
   }
 }
 
+/**
+ * The fix for a template doc with no same-stem `.tsx`: rename a same-stem
+ * source written in another extension, or add the `.tsx`.
+ * @param {string} docPath
+ * @param {string} sourcePath the `.tsx` it needs
+ */
+function missingTemplateSourceFix(docPath, sourcePath) {
+  const source = path.basename(sourcePath);
+  const stem = source.slice(0, -'.tsx'.length);
+  const other = ['.jsx', '.js', '.ts', '.mjs']
+    .map(extension => `${stem}${extension}`)
+    .find(file => fs.existsSync(path.join(path.dirname(sourcePath), file)));
+  return other
+    ? `Found ${other}, but a template source must be a .tsx file. Fix: rename ${other} to ${source}.`
+    : `Fix: add ${source} beside ${path.basename(docPath)}, with the template as its default export.`;
+}
+
 /**
  * Discover the templates contributed by a SINGLE integration. Same per-template
  * rules as {@link discoverIntegrationTemplates} (same-stem source required,
@@ -1225,7 +1242,7 @@ export async function discoverIntegrationTemplatesForOne(integration) {
       errors.push({
         package: pkgLabel,
         template: id,
-        message: `Template "${id}" is missing its same-stem source file ${path.basename(sourcePath)}.`,
+        message: `Template "${id}" is missing its same-stem source file ${path.basename(sourcePath)}. ${missingTemplateSourceFix(docPath, sourcePath)}`,
       });
       // A replacement this unusable template declares still counts, so its
       // target fails closed instead of going to a sibling.

package/foundation/discovery/template-needs.mjs

@@ -18,7 +18,7 @@
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 import module from 'node:module';
-import {CLI_ROOT} from '../fs/paths.mjs';
+import {CLI_ROOT, findWorkspaceRoot} from '../fs/paths.mjs';
 import {detectStylingSystem} from '../agent-docs/agent-docs.mjs';
 import {
   decidePackageManagerIn,
@@ -71,49 +71,6 @@ const ADD_VERB = {
   npm: 'npm install',
 };
 
-/**
- * Whether a package.json declares a workspace (`workspaces` field).
- * @param {string} dir
- * @returns {{exists: boolean, declaresWorkspace: boolean}}
- */
-function readPackageJson(dir) {
-  const pkgPath = path.join(dir, 'package.json');
-  if (!fs.existsSync(pkgPath)) return {exists: false, declaresWorkspace: false};
-  try {
-    const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf-8'));
-    return {exists: true, declaresWorkspace: pkg.workspaces != null};
-  } catch {
-    return {exists: true, declaresWorkspace: false};
-  }
-}
-
-/**
- * The workspace root (AST-048 FR15): the nearest directory at or above the
- * target that declares a workspace, by `pnpm-workspace.yaml` or a package.json
- * `workspaces` field; outside a workspace, the nearest package.json's
- * directory; with no package.json, the target itself.
- * @param {string} target
- * @returns {string}
- */
-function findWorkspaceRoot(target) {
-  let dir = path.resolve(target);
-  /** @type {string | null} */
-  let nearestPackage = null;
-  for (;;) {
-    const pkg = readPackageJson(dir);
-    if (
-      fs.existsSync(path.join(dir, 'pnpm-workspace.yaml')) ||
-      pkg.declaresWorkspace
-    ) {
-      return dir;
-    }
-    if (pkg.exists && nearestPackage == null) nearestPackage = dir;
-    const parent = path.dirname(dir);
-    if (parent === dir) return nearestPackage ?? path.resolve(target);
-    dir = parent;
-  }
-}
-
 /**
  * The project's package manager for an install command (AST-048 FR17, FR19):
  * the nearest directory from the target up to the workspace root that has a

package/foundation/discovery/theme-discovery.mjs

@@ -22,6 +22,7 @@ import * as path from 'node:path';
 import {lowerDoc} from '../doc-compiler/compile.mjs';
 import {packageSource} from '../doc-compiler/source.mjs';
 import {CLI_ROOT} from '../fs/paths.mjs';
+import {formatCliCommand} from '../env/package-manager.mjs';
 import {LOCAL_THEME_ROOT} from '../config/theme-state.mjs';
 import {assertWithin, PathSafetyError} from '../fs/path-safety.mjs';
 
@@ -958,6 +959,126 @@ function declaresThemeDoc(ast, exportDefault) {
   });
 }
 
+/**
+ * Whether a file is the module `astryx theme build` writes rather than a
+ * theme source: plain JavaScript that carries the build's generated header
+ * and never calls defineTheme.
+ * @param {string} file
+ */
+function isBuiltThemeModule(file) {
+  if (!/\.m?js$/u.test(file)) return false;
+  let text;
+  try {
+    text = fs.readFileSync(file, 'utf8');
+  } catch {
+    return false;
+  }
+  return (
+    /@generated by `astryx theme build`/u.test(text) &&
+    !/\bdefineTheme\b/u.test(text)
+  );
+}
+
+/**
+ * The fix when a descriptor's stem names both a theme source and the module
+ * `astryx theme build` writes beside it (`brand.ts` and its built `brand.js`):
+ * the build names its output after the theme, so the source and descriptor
+ * take the `<name>Theme` stem instead. Null when no built module is among
+ * the matches, or the stem already ends in `Theme`.
+ * @param {string} sourceDir
+ * @param {string[]} sources same-stem module file names
+ * @param {string} doc the descriptor's file name
+ * @param {string} exportName the descriptor's stem
+ * @returns {string | null}
+ */
+function builtThemeSourceFix(sourceDir, sources, doc, exportName) {
+  if (exportName.endsWith('Theme')) return null;
+  const built = sources.filter(file =>
+    isBuiltThemeModule(path.join(sourceDir, file)),
+  );
+  const source = sources.filter(file => !built.includes(file));
+  if (built.length === 0 || source.length !== 1) return null;
+  const extension = source[0].slice(exportName.length);
+  const stem = `${exportName}Theme`;
+  return `Fix: ${built.map(file => `"${file}"`).join(', ')} is the module \`${formatCliCommand('theme build', sourceDir)}\` writes, which takes the theme's name; rename ${source[0]} to ${stem}${extension} and ${doc} to ${stem}${THEME_DOC_SUFFIX}, export \`${stem}\` from it, and build again.`;
+}
+
+/**
+ * Why a descriptor pairs with the built module and the built module lacks
+ * the export the descriptor's stem names (`ocean.doc.mjs` beside a built
+ * `ocean.js` that exports `oceanTheme`): the descriptor is named for the
+ * build's output, not the theme's source. The source is named only when the
+ * built module's `Source:` header, or a source whose defineTheme gives the
+ * theme's name, confirms it; otherwise the message stays generic. Null when
+ * the entry is not a built module.
+ * @param {string} label the descriptor, as messages name it
+ * @param {string} sourceDir
+ * @param {string} entry the file the descriptor pairs with
+ * @param {string} exportName the descriptor's stem
+ * @param {string} doc the descriptor's file name
+ * @param {string} slug the theme's name
+ * @param {string[]} files the theme folder's files
+ * @returns {string | null}
+ */
+function builtModuleDescriptorMessage(
+  label,
+  sourceDir,
+  entry,
+  exportName,
+  doc,
+  slug,
+  files,
+) {
+  if (!isBuiltThemeModule(path.join(sourceDir, entry))) return null;
+  const source = confirmedThemeSource(sourceDir, entry, slug, files);
+  const head = `${label} shares its stem with the built module "${entry}", which does not export "${exportName}": a descriptor must share its stem with the source that calls defineTheme.`;
+  if (source == null) {
+    return `${head} Fix: rename ${doc} to share its stem with the theme's source (the module that calls defineTheme, such as ${exportName}Theme.ts).`;
+  }
+  const stem = source.replace(/\.[^.]+$/u, '');
+  return `${head} The theme's source is "${source}". Fix: rename ${doc} to ${stem}${THEME_DOC_SUFFIX}.`;
+}
+
+/**
+ * The theme's source, when something confirms it: the file the built
+ * module's `Source:` header names, if it is in the folder, else the one
+ * module in the folder whose defineTheme gives the theme's name as a
+ * literal. Null otherwise: a `<name>Theme` file alone may be a helper.
+ * @param {string} sourceDir
+ * @param {string} built the built module's file name
+ * @param {string} slug
+ * @param {string[]} files
+ * @returns {string | null}
+ */
+function confirmedThemeSource(sourceDir, built, slug, files) {
+  const own = files.filter(
+    file =>
+      !file.includes('/') &&
+      file !== built &&
+      THEME_MODULE_EXTENSIONS.some(extension => file.endsWith(extension)),
+  );
+  /** @param {string} file */
+  const read = file => {
+    try {
+      return fs.readFileSync(path.join(sourceDir, file), 'utf8');
+    } catch {
+      return '';
+    }
+  };
+  const header = /^\s*\*?\s*Source:\s*(\S+)\s*$/mu.exec(read(built));
+  if (header) {
+    const named = path.posix.basename(header[1].replace(/\\/gu, '/'));
+    if (own.includes(named)) return named;
+  }
+  const quoted = slug.replace(/[.*+?^${}()|[\]\\]/gu, '\\$&');
+  const naming = new RegExp(
+    `\\bdefineTheme\\s*\\(\\s*\\{[^}]*\\bname\\s*:\\s*['"\`]${quoted}['"\`]`,
+    'u',
+  );
+  const matches = own.filter(file => naming.test(read(file)));
+  return matches.length === 1 ? matches[0] : null;
+}
+
 /** A module named for the theme it exports, such as `oceanTheme.ts`. */
 const THEME_SOURCE_RE = /^[$A-Z_a-z][$\w]*Theme\.(?:mjs|js|mts|ts|tsx|jsx)$/u;
 
@@ -1240,8 +1361,17 @@ export function discoverThemeDirectory(
           : evidence.includes('/')
             ? `; "${evidence}" is in a subfolder`
             : ` beside "${evidence}"`;
+      const themeDoc = formatCliCommand('docs authoring theme-doc', sourceDir);
+      const fix =
+        docs.length > 1
+          ? `Fix: keep the one descriptor that shares its stem with the theme's source and delete the rest.`
+          : evidence.includes('/')
+            ? `Fix: move "${evidence}" up into ${slug}/, beside where its descriptor goes.`
+            : THEME_SOURCE_RE.test(evidence)
+              ? `Fix: add ${evidence.replace(/\.[^.]+$/u, '')}${THEME_DOC_SUFFIX} beside it with type: 'theme' and name: '${slug}'; \`${themeDoc}\` lists its fields.`
+              : `Fix: add a descriptor that shares its stem with the theme's source, with type: 'theme' and name: '${slug}'; \`${themeDoc}\` lists its fields.`;
       throw new Error(
-        `${theme} must contain exactly one same-stem .doc.mjs descriptor; found ${docs.length}${detail}.`,
+        `${theme} must contain exactly one same-stem .doc.mjs descriptor; found ${docs.length}${detail}. ${fix}`,
       );
     }
     const nested = descriptors.find(file => file.includes('/'));
@@ -1267,8 +1397,13 @@ export function discoverThemeDirectory(
       extension => `${exportName}${extension}`,
     ).filter(file => listing.files.includes(file));
     if (sources.length !== 1) {
+      const fix =
+        sources.length > 1
+          ? (builtThemeSourceFix(sourceDir, sources, docs[0], exportName) ??
+            `Fix: keep one of them; the theme's source is a single module.`)
+          : `Fix: add ${exportName}.ts beside ${docs[0]}, exporting \`${exportName}\` from defineTheme.`;
       throw new Error(
-        `${theme} must contain exactly one same-stem source for ${docs[0]}; found ${sources.length}${sources.length > 1 ? `: ${quoted(sources)}` : ''}.`,
+        `${theme} must contain exactly one same-stem source for ${docs[0]}; found ${sources.length}${sources.length > 1 ? `: ${quoted(sources)}` : ''}. ${fix}`,
       );
     }
 
@@ -1314,7 +1449,16 @@ export function discoverThemeDirectory(
           )
         ) {
           throw new ThemeRuntimeExportError(
-            `Theme "${slug}" for ${owner} entry "${entry}" does not export "${exportName}".`,
+            builtModuleDescriptorMessage(
+              label,
+              sourceDir,
+              entry,
+              exportName,
+              docs[0],
+              slug,
+              listing.files,
+            ) ??
+              `Theme "${slug}" for ${owner} entry "${entry}" does not export "${exportName}".`,
           );
         }
       } catch (error) {

package/foundation/doc-compiler/doc-loads.test.mjs

@@ -102,7 +102,15 @@ const RUNNERS = {
     runs: SELF_DOCS,
     sites: ['import ../../../api/blog/blog.doc.mjs', 'import ./blog.doc.mjs'],
   },
-  'clients/cli/commands/build-theme.mjs': {
+  'clients/cli/commands/manifest.mjs': {
+    runs: SELF_DOCS,
+    sites: ['import ./manifest.doc.mjs'],
+  },
+  'clients/cli/commands/postinstall.mjs': {
+    runs: SELF_DOCS,
+    sites: ['import ./postinstall.doc.mjs'],
+  },
+  'clients/cli/commands/theme.mjs': {
     runs: `${SELF_DOCS}; and \`astryx theme build\`, a child process per theme`,
     sites: [
       'child_process.spawn',
@@ -135,11 +143,11 @@ const RUNNERS = {
       'import ./build.doc.mjs',
     ],
   },
-  'clients/cli/commands/component/index.mjs': {
+  'clients/cli/commands/component.mjs': {
     runs: SELF_DOCS,
     sites: [
-      'import ../../../../api/component/component.doc.mjs',
-      'import ../component.doc.mjs',
+      'import ../../../api/component/component.doc.mjs',
+      'import ./component.doc.mjs',
     ],
   },
   'clients/cli/commands/discover.mjs': {
@@ -180,11 +188,11 @@ const RUNNERS = {
       'import ./gap-report.doc.mjs',
     ],
   },
-  'clients/cli/commands/hook/index.mjs': {
+  'clients/cli/commands/hook.mjs': {
     runs: SELF_DOCS,
     sites: [
-      'import ../../../../api/hook/hook.doc.mjs',
-      'import ../hook.doc.mjs',
+      'import ../../../api/hook/hook.doc.mjs',
+      'import ./hook.doc.mjs',
     ],
   },
   'clients/cli/commands/init.mjs': {
@@ -233,8 +241,8 @@ const RUNNERS = {
     ],
   },
   'clients/cli/index.mjs': {
-    runs: 'the command modules, to register each command, and the manifest command doc',
-    sites: ['import ./commands/manifest.doc.mjs', 'import(<computed>)'],
+    runs: 'the command modules, to register each command',
+    sites: ['import(<computed>)'],
   },
   'clients/cli/lib/manifest.mjs': {
     runs: 'the manifest command doc, for the exit codes the manifest reports',
@@ -248,6 +256,10 @@ const RUNNERS = {
     runs: 'astryx.config, through the config parser',
     sites: ['loadModuleWithParser(..., parseConfig)'],
   },
+  'foundation/agent-docs/agent-docs.mjs': {
+    runs: 'git, sl or hg, to read whether the repository ignores an untracked agent file',
+    sites: ['child_process.spawnSync'],
+  },
   'foundation/fs/file-protection.mjs': {
     runs: 'the ignore matcher (CommonJS), loaded when a resolver first reads an ignore file',
     sites: ['require(ignore)'],
@@ -272,6 +284,10 @@ const RUNNERS = {
     runs: 'a contributed topic, for its catalog fields: name, title, description, category, and relationships',
     sites: ['importDocModule'],
   },
+  'foundation/discovery/runner-commands.mjs': {
+    runs: "the package's topics, to find each Astryx command written with a package runner",
+    sites: ['loadTopicModule'],
+  },
   'foundation/discovery/stray-pointers.mjs': {
     runs: "the CLI's own guides, for their names, to tell which written `astryx docs <name>` points at a doc that exists",
     sites: ['builtinGuideFiles'],
@@ -315,6 +331,10 @@ const RUNNERS = {
       'require.cache',
     ],
   },
+  'foundation/fs/read-record.mjs': {
+    runs: "nothing; it wraps node:fs's read calls to record the paths an operation reads, and republishes them to ESM imports",
+    sites: ['module.syncBuiltinESMExports'],
+  },
   'foundation/fs/paths.mjs': {
     runs: "Yarn's pnpapi, under Plug'n'Play, to find an installed package",
     sites: ['require(pnpapi)'],
@@ -339,6 +359,10 @@ const RUNNERS = {
     runs: "the CLI release that answers a project's run, when it is not this copy",
     sites: ['child_process.spawn'],
   },
+  'host/index.mjs': {
+    runs: "another release's host entry, from one of the host's package sets, when that release answers a hosted run",
+    sites: ['import(<computed>)'],
+  },
   'scripts/generate-cli-readme.mjs': {
     runs: '`astryx manifest` and the error-code and response-type docs, to write the README tables (build time, not shipped)',
     sites: ['child_process.spawnSync', 'import(<computed>)'],

package/foundation/doc-compiler/read.mjs

@@ -173,8 +173,23 @@ export async function readDocView(file, options) {
   );
   if (result.loadFailed) throw result.loadFailure;
   if (result.missing) {
-    if (strict)
+    if (strict) {
+      // A doc that exports nothing its reader takes (an empty file, or one
+      // with other exports) is said plainly, with what it does export and
+      // the fix; the schema would only say "(root): Invalid input".
+      const exported =
+        options.exports ??
+        /** @type {Record<string, readonly string[]>} */ (DOC_EXPORTS)[
+          options.root
+        ] ??
+        [];
+      const problem =
+        result.missingValue === undefined
+          ? await missingDocProblem(file, options, exported)
+          : null;
+      if (problem) throw new Error(`${options.label ?? file} ${problem}`);
       parserFor(options.root)(result.missingValue, options.label ?? file);
+    }
     return result.missingValue;
   }
   if (strict && result.failed) throw result.failure;
@@ -182,6 +197,49 @@ export async function readDocView(file, options) {
   return result.view;
 }
 
+/**
+ * Why a doc file exports no doc, with the fix: it is empty, or it exports
+ * other names than the ones its reader takes. Null when neither explains it.
+ * @param {string} file
+ * @param {ReadOptions} options
+ * @param {readonly string[]} exported the export names the reader takes
+ * @returns {Promise<string | null>}
+ */
+async function missingDocProblem(file, options, exported) {
+  // A theme descriptor is read statically, never imported.
+  if (options.root === 'themes') return null;
+  const fix =
+    'Fix: export the doc object as the default export: `export default {type: ..., name: ..., ...}`.';
+  let text;
+  try {
+    text = fs.readFileSync(file, 'utf8');
+  } catch {
+    return null;
+  }
+  const code = text
+    .replace(/^\uFEFF/u, '')
+    .replace(/\/\*[\s\S]*?\*\//gu, '')
+    .replace(/(^|[^:])\/\/.*$/gmu, '$1')
+    .trim();
+  if (code === '') return `is empty, so it documents nothing. ${fix}`;
+  /** @type {string[]} */
+  let names;
+  try {
+    const mod = await LOADERS[options.loader ?? 'user'](file);
+    names = Object.keys(mod ?? {}).filter(name => name !== 'default');
+  } catch {
+    return null;
+  }
+  const takes = exported.map(name =>
+    name === 'default' ? 'default export' : `\`${name}\` export`,
+  );
+  const found =
+    names.length > 0
+      ? ` (it exports ${names.map(name => `\`${name}\``).join(', ')})`
+      : ' (it exports nothing)';
+  return `has no ${takes.join(' or ')}${found}, so it documents nothing. ${fix}`;
+}
+
 /**
  * Load one file as its root reads it: the doc its module exports and, for a
  * component or hook, the translation it exports for `lang`.

package/foundation/doc-compiler/read.test.mjs

@@ -109,10 +109,19 @@ describe('readDocView', () => {
     }
   });
 
-  it("reads a file with no doc as undefined, or as its parser's error when checked", async () => {
+  it('reads a file with no doc as undefined, or, checked, says what it exports instead', async () => {
     const file = write('Empty.doc.mjs', 'export const unrelated = 1;\n');
     await expect(loadDocs(file)).resolves.toBeUndefined();
-    await expect(loadComponentDoc(file)).rejects.toThrow(`${file} is invalid`);
+    await expect(loadComponentDoc(file)).rejects.toThrow(
+      `${file} has no default export or \`docs\` export (it exports \`unrelated\`), so it documents nothing. Fix: export the doc object as the default export`,
+    );
+  });
+
+  it('says a checked doc file is empty', async () => {
+    const file = write('Blank.doc.mjs', '// nothing yet\n');
+    await expect(loadComponentDoc(file)).rejects.toThrow(
+      `${file} is empty, so it documents nothing.`,
+    );
   });
 
   it('applies the translation a module exports for the reading language', async () => {

package/foundation/doc-compiler/split-topic-keywords.test.mjs

@@ -3,7 +3,8 @@
 /**
  * @file A topic split into a namespace of guides indexes each term once, a
  * policy of the docs split itself (no spec clause states it). Below the CLI's own
- * root namespaces (every one but `cli`, its command and API reference), a
+ * root namespaces (every one but `cli`, its command and API reference, and
+ * `authoring`, the integration guides `cli` held before this rule), a
  * guide's search keywords are its own: none repeats a keyword its namespace,
  * a sibling, or a guide of another split topic declares. A term several
  * guides share belongs to their namespace, or to none.
@@ -45,7 +46,7 @@ describe('the keywords of a split topic', () => {
       return doc?.name;
     };
     const roots = [...docs.values()]
-      .filter(doc => doc.type === 'namespace' && !parentOf(doc) && doc.name !== 'cli')
+      .filter(doc => doc.type === 'namespace' && !parentOf(doc) && !['cli', 'authoring'].includes(doc.name))
       .map(doc => doc.name);
     expect(roots).toContain('layout');