@astryxdesign/cli 0.7.2 → 0.7.3-canary.02f5fe4

package/foundation/discovery/authoring-surface.mjs

@@ -7,7 +7,7 @@
  * @input authoring/index.d.ts and the type modules it re-exports, parsed with
  *   jscodeshift and never imported or type-checked (consumer installs have no
  *   TypeScript); the self-docs on disk and in AUTHORING_SELF_DOCS; and the
- *   section keys `astryx docs authoring --index` lists.
+ *   section keys `astryx docs authoring/field-reference --index` lists.
  * @output {@link tracePublicAuthoringTypes}: each exported type and the module
  *   that declares it. {@link auditAuthoringSurface}: each module whose exported
  *   types a reader cannot reach and why, each export that cannot be traced,
@@ -424,7 +424,7 @@ function declaredIn(t, folder, name) {
  * document something public: a public type declared beside it, and, when its
  * title is the name of a type declared beside it, that type.
  * @param {{root?: string, sources?: string[], topicKeys?: Set<string> | null}} [options]
- *   `topicKeys` are the keys `astryx docs authoring --index` lists; null skips
+ *   `topicKeys` are the keys `astryx docs authoring/field-reference --index` lists; null skips
  *   that comparison.
  * @returns {Promise<{
  *   types: number,

package/foundation/discovery/authoring-surface.test.mjs

@@ -86,7 +86,7 @@ describe('the public authoring surface of this repo', () => {
   it(
     'audits clean: every exported type has a readable doc and every self-doc documents one',
     async () => {
-      const index = await docs('authoring', undefined, {index: true});
+      const index = await docs('authoring/field-reference', undefined, {index: true});
       const topicKeys = new Set(
         index.data.sections.map((/** @type {any} */ s) => s.id),
       );

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

@@ -102,7 +102,8 @@ export const CLI_SELF_DOC_DIRS: string[];
 /**
  * Every namespace a CLI doc may declare, and what reads it. The docs tree
  * adopts `cli/commands` (under `cli/commands`) and `cli/api` (under
- * `cli/api/<kind>s`); `astryx docs authoring` reads `authoring` from its list.
+ * `cli/api/<kind>s`); the field reference (`astryx docs authoring/field-reference`)
+ * reads `authoring` from its list.
  * @type {Record<string, {reader: 'tree' | 'authoring'}>}
  */
 export const CLI_DOC_NAMESPACES: Record<string, {

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

@@ -41,7 +41,8 @@ const NAMESPACED_KINDS = new Set(['command', 'function', 'schema', 'enum']);
 /**
  * Every namespace a CLI doc may declare, and what reads it. The docs tree
  * adopts `cli/commands` (under `cli/commands`) and `cli/api` (under
- * `cli/api/<kind>s`); `astryx docs authoring` reads `authoring` from its list.
+ * `cli/api/<kind>s`); the field reference (`astryx docs authoring/field-reference`)
+ * reads `authoring` from its list.
  * @type {Record<string, {reader: 'tree' | 'authoring'}>}
  */
 export const CLI_DOC_NAMESPACES = {
@@ -492,13 +493,13 @@ export async function auditCliSelfDocs({
       else {
         misfiled.push({
           source,
-          message: `${source} has namespace "authoring", but \`${formatCliCommand('docs authoring')}\` does not list it`,
+          message: `${source} has namespace "authoring", but \`${formatCliCommand('docs authoring/field-reference')}\` does not list it`,
         });
       }
     } else if (inAuthoring) {
       misfiled.push({
         source,
-        message: `${source} is read in \`${formatCliCommand('docs authoring')}\`, but its namespace is "${namespace}"`,
+        message: `${source} is read in \`${formatCliCommand('docs authoring/field-reference')}\`, but its namespace is "${namespace}"`,
       });
     } else {
       treeDocs.push(doc);

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

@@ -146,8 +146,8 @@ describe('auditCliSelfDocs', () => {
     });
     const result = await audit(root, ['y/y.doc.mjs', 'z/z.doc.mjs']);
     expect(result.misfiled.map(entry => entry.message)).toEqual([
-      `authoring/x/x.doc.mjs has namespace "authoring", but \`${formatCliCommand('docs authoring')}\` does not list it`,
-      `authoring/y/y.doc.mjs is read in \`${formatCliCommand('docs authoring')}\`, but its namespace is "cli/api"`,
+      `authoring/x/x.doc.mjs has namespace "authoring", but \`${formatCliCommand('docs authoring/field-reference')}\` does not list it`,
+      `authoring/y/y.doc.mjs is read in \`${formatCliCommand('docs authoring/field-reference')}\`, but its namespace is "cli/api"`,
     ]);
     expect(result.authoring).toBe(1);
     expect(result.tree).toBe(0);

package/foundation/discovery/component-discovery.d.mts

@@ -1,6 +1,13 @@
 // @generated by scripts/sync-api-types.mjs from the JSDoc in foundation/**/*.mjs.
 // DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
 
+/**
+ * Whether a component doc is hidden (`hidden: true`), read as discovery
+ * reads it: discovery skips a hidden doc.
+ * @param {string} docPath
+ * @returns {boolean}
+ */
+export function isHiddenComponentDoc(docPath: string): boolean;
 /**
  * The entry a family doc gives `name` in its `components`, when the doc is not
  * the component's own (Stack's doc for VStack); null otherwise.
@@ -117,6 +124,36 @@ export function discoverExternalComponentsGrouped(docsDir: string): Record<strin
 export function findExternalComponentDoc(docsDir: string, name: string): string | null;
 /** @param {string} docPath */
 export function docStem(docPath: string): string;
+/**
+ * The local module a doc's import names: the doc's own `import`, else the
+ * subpath its directory publishes, read through the package's `exports` (its
+ * `main` when it has none). Undefined when the package directory is unknown;
+ * null when the import names another package or resolves to no file.
+ *
+ * @param {{name?: string, __packageDir?: string, __packageExports?: Record<string, unknown>|null}} integration
+ * @param {string} docPath
+ * @param {Record<string, any> | null} doc
+ * @returns {string | null | undefined}
+ */
+export function importedModule(integration: {
+    name?: string;
+    __packageDir?: string;
+    __packageExports?: Record<string, unknown> | null;
+}, docPath: string, doc: Record<string, any> | null): string | null | undefined;
+/**
+ * The file an import of the package's own name resolves to, through its
+ * package.json `exports` (or `main` when it has none): `@acme/kit` or
+ * `@acme/kit/widget`. Null when the specifier names another package, or the
+ * package publishes nothing at it.
+ * @param {{name?: string, __packageDir?: string, __packageExports?: Record<string, unknown> | null}} integration
+ * @param {string} specifier
+ * @returns {string | null}
+ */
+export function ownPackageModule(integration: {
+    name?: string;
+    __packageDir?: string;
+    __packageExports?: Record<string, unknown> | null;
+}, specifier: string): string | null;
 /**
  * The `.tsx` file in `folder`, or below it, that declares `name`, taking files
  * in path order: the source of a member whose import never reaches a `.tsx`

package/foundation/discovery/component-discovery.mjs

@@ -118,6 +118,16 @@ function scanDocText(text) {
   };
 }
 
+/**
+ * Whether a component doc is hidden (`hidden: true`), read as discovery
+ * reads it: discovery skips a hidden doc.
+ * @param {string} docPath
+ * @returns {boolean}
+ */
+export function isHiddenComponentDoc(docPath) {
+  return readDocMeta(docPath).hidden;
+}
+
 /**
  * Read the `group`, `hiddenComponents`, and `hidden` fields from a
  * component's .doc.mjs file (synchronous), with what {@link scanDocText}
@@ -994,7 +1004,7 @@ function packageMain(packageDir) {
  * @param {Record<string, any> | null} doc
  * @returns {string | null | undefined}
  */
-function importedModule(integration, docPath, doc) {
+export function importedModule(integration, docPath, doc) {
   const packageName = integration?.name;
   const packageDir = integration?.__packageDir;
   if (!packageName || !packageDir) return undefined;
@@ -1024,6 +1034,42 @@ function importedModule(integration, docPath, doc) {
   ).target;
 }
 
+/**
+ * The file an import of the package's own name resolves to, through its
+ * package.json `exports` (or `main` when it has none): `@acme/kit` or
+ * `@acme/kit/widget`. Null when the specifier names another package, or the
+ * package publishes nothing at it.
+ * @param {{name?: string, __packageDir?: string, __packageExports?: Record<string, unknown> | null}} integration
+ * @param {string} specifier
+ * @returns {string | null}
+ */
+export function ownPackageModule(integration, specifier) {
+  const packageName = integration?.name;
+  const packageDir = integration?.__packageDir;
+  if (!packageName || !packageDir) return null;
+  if (specifier !== packageName && !specifier.startsWith(`${packageName}/`)) {
+    return null;
+  }
+  const exportsMap =
+    integration.__packageExports === undefined
+      ? readPackageExports(packageDir)
+      : integration.__packageExports;
+  if (specifier === packageName && exportsMap == null) {
+    return packageMain(packageDir) ?? null;
+  }
+  const subpath =
+    specifier === packageName
+      ? '.'
+      : `./${specifier.slice(packageName.length + 1)}`;
+  return (
+    inspectPackageExport(
+      {name: packageName, exports: exportsMap ?? undefined},
+      packageDir,
+      subpath,
+    ).target ?? null
+  );
+}
+
 /**
  * Whether `file` sits in `folder` or below it.
  * @param {string} folder
@@ -1211,6 +1257,19 @@ export function integrationMemberEntry(doc, record) {
   );
 }
 
+/**
+ * Whether `dir` is a folder to list. A declared root that is a file is
+ * reported by the root check; discovery finds nothing in it.
+ * @param {string} dir
+ */
+function isFolder(dir) {
+  try {
+    return fs.statSync(dir).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
 /**
  * Visit every component doc under an integration's components root, hidden
  * ones included, in discovery order, with its stem.
@@ -1218,10 +1277,26 @@ export function integrationMemberEntry(doc, record) {
  * @param {(docPath: string, stem: string) => void} visit
  */
 export function forEachIntegrationDoc(componentsDir, visit) {
-  if (!componentsDir || !pathExists(componentsDir)) return;
+  if (!componentsDir || !isFolder(componentsDir)) return;
+  /** @param {string} name */
+  const key = name => {
+    const rank = INTEGRATION_DOC_SUFFIXES.findIndex(s => name.endsWith(s));
+    return rank < 0
+      ? {stem: name, rank}
+      : {stem: name.slice(0, -INTEGRATION_DOC_SUFFIXES[rank].length), rank};
+  };
   /** @param {string} dirPath */
   function scanDir(dirPath) {
-    for (const entry of listDirEntries(dirPath)) {
+    // Name order, and for two docs of one stem the suffix precedence, so the
+    // doc a stem records is the one a lookup by name finds, on every disk.
+    const entries = listDirEntries(dirPath).sort((a, b) => {
+      const left = key(a.name);
+      const right = key(b.name);
+      return left.stem === right.stem
+        ? left.rank - right.rank
+        : byCodeUnit(left.stem, right.stem);
+    });
+    for (const entry of entries) {
       if (entry.name === 'node_modules' || entry.name === '__tests__') continue;
       const fullPath = path.join(dirPath, entry.name);
       if (entry.isDirectory()) {
@@ -1270,7 +1345,7 @@ export function discoverIntegrationComponents(
   {documentedNames = true} = {},
 ) {
   const componentsDir = integration?.components;
-  if (!componentsDir || !pathExists(componentsDir)) return [];
+  if (!componentsDir || !isFolder(componentsDir)) return [];
 
   /** @type {Map<string, {name: string, package: string, docPath: string, sourcePath: string|null, issuesUrl: string|undefined, group: string|null}>} */
   const byName = new Map();
@@ -1485,7 +1560,7 @@ function findDocumentedComponent(integration, componentsDir, name) {
  */
 export function findIntegrationComponent(integration, name) {
   const componentsDir = integration?.components;
-  if (!componentsDir || !pathExists(componentsDir)) return null;
+  if (!componentsDir || !isFolder(componentsDir)) return null;
   const sameStem = findSameStemDoc(componentsDir, name);
   if (sameStem) {
     const exportName = otherExportName({

package/foundation/discovery/component-loader.d.mts

@@ -43,5 +43,5 @@ export type LoadDocOptions = {
      * which root reads the doc
      * (default: components)
      */
-    root?: "hooks" | "components" | undefined;
+    root?: "components" | "hooks" | undefined;
 };

package/foundation/discovery/docs-discovery.mjs

@@ -423,6 +423,19 @@ export function problemsInNamespace(doc) {
   return problems;
 }
 
+/**
+ * Whether `dir` is a folder to list. A declared root that is a file is
+ * reported by the root check; discovery finds nothing in it.
+ * @param {string} dir
+ */
+function isFolder(dir) {
+  try {
+    return fs.statSync(dir).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
 /**
  * Discover the topics contributed by a single loaded integration. Mirrors
  * `discoverIntegrationComponents`: walk the resolved root, take every
@@ -450,7 +463,7 @@ export async function discoverIntegrationDocs(integration) {
   const namespaces = [];
   /** @type {import('../doc-compiler/tree.mjs').TreeDocInput[]} */
   const guides = [];
-  if (!docsDir || !fs.existsSync(docsDir)) {
+  if (!docsDir || !isFolder(docsDir)) {
     return {records, errors, namespaces, guides};
   }
   const providerId = integration.providerId ?? integration.name;

package/foundation/discovery/module-exports.d.mts

@@ -18,6 +18,39 @@ export function moduleExportsName(file: string, exportName: string, seen?: Set<s
  * @returns {string | null}
  */
 export function moduleExportSource(file: string, exportName: string, seen?: Set<string>): string | null;
+/**
+ * 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: string): string[] | null;
+/**
+ * @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: string, exportName: string, seen?: Set<string>): ExportVerdict;
+/**
+ * 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: string, exportName: string): boolean;
 /**
  * The object a module exports, as plain data, read without running it: the
  * first of `exportNames` it exports, an object literal in place or a top-level
@@ -35,3 +68,11 @@ export function staticExportObject(file: string, exportNames: readonly string[])
  * enumerable, so the object compares and serializes as its literal properties.
  */
 export const HAS_COMPUTED: unique symbol;
+export type ExportVerdict = {
+    verdict: "exports";
+} | {
+    verdict: "lacks";
+} | {
+    verdict: "unknown";
+    reason: string;
+};

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/runner-allowlist.d.mts

@@ -14,10 +14,8 @@
  *   command, except in `runnerExamples`, where `npx @astryxdesign/cli …` and a
  *   project's runner may (still never the unscoped name through npx).
  *
- * TODO(doctor-runner-check): the Doctor lane's integration-docs runner check
- * (foundation/discovery/runner-commands.mjs) becomes the single rule; then the
- * repo test runs that check over Core's and the CLI's own docs with this
- * allowlist.
+ * The matcher is runnerCommandsIn (foundation/discovery/runner-commands.mjs),
+ * the rule `doctor integration validate` holds integrations to.
  *
  * @input  nothing
  * @output the allowlist

package/foundation/discovery/runner-allowlist.mjs

@@ -13,10 +13,8 @@
  *   command, except in `runnerExamples`, where `npx @astryxdesign/cli …` and a
  *   project's runner may (still never the unscoped name through npx).
  *
- * TODO(doctor-runner-check): the Doctor lane's integration-docs runner check
- * (foundation/discovery/runner-commands.mjs) becomes the single rule; then the
- * repo test runs that check over Core's and the CLI's own docs with this
- * allowlist.
+ * The matcher is runnerCommandsIn (foundation/discovery/runner-commands.mjs),
+ * the rule `doctor integration validate` holds integrations to.
  *
  * @input  nothing
  * @output the allowlist