@astryxdesign/cli 0.7.2 → 0.7.3-canary.06872b4

package/foundation/discovery/module-exports.mjs

@@ -309,6 +309,259 @@ export function moduleExportSource(file, exportName, seen = new Set()) {
   return found;
 }
 
+/**
+ * The module's own top-level statements of one type: an `export` inside a
+ * TypeScript namespace names a member of that namespace, not of the module.
+ * @param {any} program
+ * @param {string} type
+ * @returns {any[]}
+ */
+function topLevel(program, type) {
+  return program.body.filter((/** @type {any} */ node) => node.type === type);
+}
+
+/**
+ * Every runtime name a module exports that this read can see (`default` for
+ * a default export), or null when it cannot see them all: an `export *`, `export =`, CommonJS exports, or a
+ * file that does not parse.
+ * @param {string} file
+ * @returns {string[] | null}
+ */
+export function moduleExportNames(file) {
+  let text;
+  let ast;
+  try {
+    if (!fs.statSync(file).isFile()) return null;
+    text = moduleText(file);
+    ast = parseModule(file);
+  } catch {
+    return null;
+  }
+  if (/\bmodule\.exports\b|\bexports\.[$\w]/u.test(text)) return null;
+  if (
+    topLevel(ast.program, 'TSExportAssignment').length > 0 ||
+    topLevel(ast.program, 'ExportAllDeclaration').length > 0
+  ) {
+    return null;
+  }
+  /** @type {Set<string>} */
+  const names = new Set();
+  for (const node of topLevel(ast.program, 'TSImportEqualsDeclaration')) {
+    if (!node.isExport) continue;
+    // A type-only alias has no runtime value; any other might.
+    if (node.importKind === 'type') continue;
+    if (typeof node.id?.name !== 'string') return null;
+    names.add(node.id.name);
+  }
+  for (const node of topLevel(ast.program, 'ExportNamedDeclaration')) {
+    if (node.exportKind === 'type') continue;
+    const declaration = node.declaration;
+    if (declaration?.type === 'VariableDeclaration') {
+      for (const item of declaration.declarations) {
+        if (item.id?.type !== 'Identifier') return null;
+        names.add(item.id.name);
+      }
+    } else if (declaration != null) {
+      if (!runtimeDefault(declaration)) continue;
+      if (typeof declaration.id?.name !== 'string') return null;
+      names.add(declaration.id.name);
+    }
+    for (const specifier of node.specifiers ?? []) {
+      if (specifier.exportKind === 'type') continue;
+      const exported = specifier.exported?.name ?? specifier.exported?.value;
+      if (typeof exported === 'string') names.add(exported);
+    }
+  }
+  if (
+    topLevel(ast.program, 'ExportDefaultDeclaration').some(
+      (/** @type {any} */ node) => runtimeDefault(node.declaration),
+    )
+  ) {
+    names.add('default');
+  }
+  return [...names].sort();
+}
+
+/**
+ * @typedef {{verdict: 'exports'} | {verdict: 'lacks'} | {verdict: 'unknown', reason: string}} ExportVerdict
+ */
+
+/**
+ * Whether a module exports `exportName` at runtime, read without executing
+ * it: `exports` when a declaration or a followed re-export binds it, `lacks`
+ * only when every export the module writes was read and none binds it, and
+ * `unknown`, with the first reason, when some export could not be read: a
+ * re-export from another package or from a specifier that resolves to no
+ * file, a destructured binding, a namespace, an ambient or const enum
+ * declaration, `export =`, CommonJS exports, or a file that does not parse.
+ * @param {string} file
+ * @param {string} exportName
+ * @param {Set<string>} [seen]
+ * @returns {ExportVerdict}
+ */
+export function moduleExportVerdict(file, exportName, seen = new Set()) {
+  const identity = `${file}\0${exportName}`;
+  // A cycle adds nothing a module's own exports have not already said.
+  if (seen.has(identity)) return {verdict: 'lacks'};
+  seen.add(identity);
+  const shown = path.basename(file);
+  let text;
+  let ast;
+  try {
+    if (!fs.statSync(file).isFile()) {
+      return {verdict: 'unknown', reason: `${shown} is not a file.`};
+    }
+    text = moduleText(file);
+    ast = parseModule(file);
+  } catch {
+    return {
+      verdict: 'unknown',
+      reason: `${shown} could not be read or parsed.`,
+    };
+  }
+  /** @type {string[]} */
+  const unknown = [];
+  if (/\bmodule\.exports\b|\bexports\.[$\w]/u.test(text)) {
+    unknown.push(
+      `${shown} uses CommonJS exports, whose names this check does not read.`,
+    );
+  }
+  if (topLevel(ast.program, 'TSExportAssignment').length > 0) {
+    unknown.push(`${shown} uses \`export =\`, whose names this check does not read.`);
+  }
+  /**
+   * Follow a re-export of `imported` from `specifier`.
+   * @param {string} specifier
+   * @param {string} imported
+   * @param {string} what how the reason names what is re-exported
+   * @returns {boolean} true when it proves the export
+   */
+  const follow = (specifier, imported, what) => {
+    if (!specifier.startsWith('.')) {
+      unknown.push(
+        `${shown} re-exports ${what} from "${specifier}", another package this check does not read.`,
+      );
+      return false;
+    }
+    const target = resolveLocalModule(specifier, file);
+    if (!target) {
+      unknown.push(
+        `${shown} re-exports ${what} from "${specifier}", which resolves to no file this check can read.`,
+      );
+      return false;
+    }
+    const inner = moduleExportVerdict(target, imported, seen);
+    if (inner.verdict === 'exports') return true;
+    if (inner.verdict === 'unknown') unknown.push(inner.reason);
+    return false;
+  };
+  // `export import Name = Some.Path;` binds a runtime value unless it is
+  // type-only.
+  for (const node of topLevel(ast.program, 'TSImportEqualsDeclaration')) {
+    if (!node.isExport || node.id?.name !== exportName) continue;
+    if (node.importKind === 'type') {
+      unknown.push(
+        `${shown} exports ${exportName} with \`export import type\`, which has no runtime value this check can see.`,
+      );
+    } else {
+      return {verdict: 'exports'};
+    }
+  }
+  for (const node of topLevel(ast.program, 'ExportNamedDeclaration')) {
+    if (node.exportKind === 'type') continue;
+    const declaration = node.declaration;
+    if (declaration?.type === 'VariableDeclaration') {
+      for (const item of declaration.declarations) {
+        if (item.id?.type !== 'Identifier') {
+          unknown.push(
+            `${shown} exports a destructured binding, whose names this check does not read.`,
+          );
+        } else if (item.id.name === exportName) {
+          if (declaration.declare === true) {
+            unknown.push(
+              `${shown} declares ${exportName} with \`declare\`, which has no runtime value this check can see.`,
+            );
+          } else {
+            return {verdict: 'exports'};
+          }
+        }
+      }
+    } else if (declaration != null && declaration.id?.name === exportName) {
+      if (
+        ['TSInterfaceDeclaration', 'TSTypeAliasDeclaration'].includes(
+          declaration.type,
+        )
+      ) {
+        // A type only: no runtime export.
+      } else if (declaration.type === 'TSModuleDeclaration') {
+        unknown.push(
+          `${shown} exports ${exportName} as a TypeScript namespace, which has a runtime value only when it holds one.`,
+        );
+      } else if (declaration.declare === true || declaration.const === true) {
+        unknown.push(
+          `${shown} declares ${exportName} as an ambient or const declaration, which has no runtime value this check can see.`,
+        );
+      } else if (runtimeDefault(declaration)) {
+        return {verdict: 'exports'};
+      }
+    }
+    for (const specifier of node.specifiers ?? []) {
+      if (specifier.exportKind === 'type') continue;
+      const exported = specifier.exported?.name ?? specifier.exported?.value;
+      if (exported !== exportName) continue;
+      if (!node.source || specifier.type === 'ExportNamespaceSpecifier') {
+        return {verdict: 'exports'};
+      }
+      if (specifier.type !== 'ExportSpecifier') {
+        unknown.push(`${shown} re-exports ${exportName} in a form this check does not read.`);
+        continue;
+      }
+      const imported =
+        specifier.local?.name ?? specifier.local?.value ?? exportName;
+      if (follow(String(node.source.value), imported, exportName)) {
+        return {verdict: 'exports'};
+      }
+    }
+  }
+  if (exportName === 'default') {
+    const defaults = topLevel(ast.program, 'ExportDefaultDeclaration');
+    if (
+      defaults.some((/** @type {any} */ node) =>
+        runtimeDefault(node.declaration),
+      )
+    ) {
+      return {verdict: 'exports'};
+    }
+  }
+  for (const node of topLevel(ast.program, 'ExportAllDeclaration')) {
+    if (node.exportKind === 'type') continue;
+    const exported = node.exported?.name ?? node.exported?.value;
+    if (exported != null) {
+      if (exported === exportName) return {verdict: 'exports'};
+      continue;
+    }
+    // `export *` never re-exports a default.
+    if (exportName === 'default') continue;
+    if (follow(String(node.source?.value ?? ''), exportName, 'everything')) {
+      return {verdict: 'exports'};
+    }
+  }
+  return unknown.length > 0
+    ? {verdict: 'unknown', reason: unknown[0]}
+    : {verdict: 'lacks'};
+}
+
+/**
+ * Whether a module provably does not export `exportName` at runtime: see
+ * {@link moduleExportVerdict}.
+ * @param {string} file
+ * @param {string} exportName
+ * @returns {boolean}
+ */
+export function moduleLacksExport(file, exportName) {
+  return moduleExportVerdict(file, exportName).verdict === 'lacks';
+}
+
 /**
  * Marks an object {@link staticExportObject} returns (or one inside it) whose
  * source also has properties or spreads it could not read as literals. Not

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

@@ -248,6 +248,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)'],
@@ -339,6 +343,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 () => {