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

package/foundation/config/project.mjs

@@ -40,7 +40,7 @@ import {parseConfig} from '../../authoring/config/parse.mjs';
 import {
   loadIntegrations,
   loadLocalIntegration,
-  resolvePackageDir,
+  resolveInstalledIntegrationDir,
 } from '../integrations/integrations.mjs';
 import {loadAutolinkCandidates} from '../integrations/autolink.mjs';
 import {
@@ -65,7 +65,7 @@ import {
   discoverValidIntegrationComponents,
 } from '../discovery/component-discovery.mjs';
 import {resolveComponentReplacements} from '../discovery/component-replacement.mjs';
-import {CLI_ROOT, findCoreDir, findProjectCoreDir} from '../fs/paths.mjs';
+import {CLI_ROOT, findCoreDir, findPackageRoot, findProjectCoreDir} from '../fs/paths.mjs';
 import {
   applyTemplateReplacements,
   effectiveTemplateDiscovery,
@@ -89,6 +89,10 @@ import {
 } from '../../assets/codemods/integration-discovery.mjs';
 import {validateLoadedIntegration} from '../integrations/validate-contributions.mjs';
 import {recordDeclaredCliCommands} from '../env/cli-command.mjs';
+import {
+  hostedRun,
+  recordResolvedIntegrations,
+} from '../runtime/package-root.mjs';
 import {
   InMemoryConfigCache,
   cacheKey,
@@ -121,9 +125,16 @@ function errorMessage(err) {
  */
 export function computerIntegrationCandidates(cwd = process.cwd()) {
   try {
-    const cliRoot = isOutsideProject(cwd) ? CLI_ROOT : globalCliRoot(cwd);
+    const outside = isOutsideProject(cwd);
+    const cliRoot = outside ? CLI_ROOT : globalCliRoot(cwd);
     return cliRoot
-      ? scanComputerIntegrations({cliRoot, release: cliVersion()})
+      ? scanComputerIntegrations({
+          cliRoot,
+          release: cliVersion(),
+          // Outside a project, the integrations a host approves load from the
+          // package set that serves the run too (cli-surface INV30).
+          approved: outside ? (hostedRun()?.integrations ?? []) : [],
+        })
       : [];
   } catch {
     return [];
@@ -212,7 +223,7 @@ async function loadConfiguredIntegrations(specs, {cwd, fresh}) {
       /** @type {string|undefined} */
       let packageDir;
       try {
-        packageDir = resolvePackageDir(spec, cwd);
+        packageDir = resolveInstalledIntegrationDir(spec, cwd);
       } catch {
         // Not a bare package name: there is no install location to record.
       }
@@ -315,22 +326,6 @@ export const CONFIG_BASENAMES = [
 export const DEFAULT_ISSUES_URL =
   'https://github.com/facebook/astryx/issues/new';
 
-/**
- * Find the directory of the nearest package.json walking up from startDir.
- * @param {string} startDir
- * @returns {string|null}
- */
-function findPackageRoot(startDir) {
-  let dir = startDir;
-  for (let i = 0; i < 50; i++) {
-    if (fs.existsSync(path.join(dir, 'package.json'))) return dir;
-    const parent = path.dirname(dir);
-    if (parent === dir) break;
-    dir = parent;
-  }
-  return null;
-}
-
 /**
  * Whether this project accepts `debug` handlers contributed by the
  * integrations it loads.
@@ -495,7 +490,8 @@ export class Project {
     // The project root: the config's directory when there is one (findConfigPath
     // resolves the config as a sibling of the nearest package.json, so the two
     // agree), otherwise that package.json's directory. Dependencies are declared
-    // there, and node_modules sits there.
+    // there, and installed packages resolve from there up the node_modules
+    // chain.
     const projectDir = configPath
       ? path.dirname(configPath)
       : (findPackageRoot(cwd) ?? cwd);
@@ -580,6 +576,8 @@ export class Project {
         : []),
     ]);
     loadedIntegrations = resolution.integrations;
+    // A hosted run returns each package it resolved (cli-surface INV30).
+    recordResolvedIntegrations(loadedIntegrations);
     // The picker (getCliInvocation) is synchronous, so the commands these
     // integrations declare are recorded here, where they become known.
     recordDeclaredCliCommands(projectDir, loadedIntegrations);

package/foundation/config/project.test.mjs

@@ -291,6 +291,32 @@ describe('Project.load', () => {
   });
 });
 
+describe('Project.issues and a near-miss manifest key', () => {
+  it.each([
+    [
+      'alone, while the loaded integration fills providerId from the package name',
+      {providerID: '@acme/widgets'},
+      'Fix: rename "providerID" to "providerId" in astryx.integration.mjs.',
+    ],
+    [
+      'beside the key it suggests',
+      {providerID: '@acme/widgets', providerId: '@acme/widgets'},
+      'Fix: remove "providerID" from astryx.integration.mjs; it already sets "providerId".',
+    ],
+  ])(
+    'reads the keys the manifest declares: providerID %s',
+    async (_label, unknownKeys, fix) => {
+      scaffold({unknownKeys});
+      const project = await Project.load(tmpDir);
+      const keys = (await project.issues()).filter(
+        issue => issue.code === 'unknown_manifest_key',
+      );
+      expect(keys).toHaveLength(1);
+      expect(keys[0].message).toContain(fix);
+    },
+  );
+});
+
 describe('Project.load and the cliCommand an integration declares', () => {
   it('records it, so the picker prints commands with it', async () => {
     scaffold({cliCommand: 'acme astryx'});
@@ -830,6 +856,36 @@ describe('Project loads each integration in isolation', () => {
   });
 });
 
+describe('Project finds configured integrations a workspace hoists', () => {
+  // npm, Yarn and Bun workspaces install a member's dependencies at the
+  // workspace root, so the member's own node_modules does not hold them.
+  it('loads an integration named in a member config from the workspace root', async () => {
+    scaffold();
+    fs.writeFileSync(
+      path.join(tmpDir, 'package.json'),
+      JSON.stringify({name: 'root', private: true, workspaces: ['apps/*']}),
+    );
+    fs.rmSync(path.join(tmpDir, 'astryx.config.mjs'));
+    const member = path.join(tmpDir, 'apps', 'web');
+    fs.mkdirSync(member, {recursive: true});
+    fs.writeFileSync(path.join(member, 'package.json'), JSON.stringify({name: 'web'}));
+    fs.writeFileSync(
+      path.join(member, 'astryx.config.mjs'),
+      `export default ${JSON.stringify({integrations: ['@acme/widgets']})};\n`,
+    );
+
+    const project = await Project.load(member);
+
+    const widgets = (await project.components()).filter(
+      component => component.package === '@acme/widgets',
+    );
+    expect(widgets.map(component => component.name)).toEqual(['Widget']);
+    expect(await project.issues()).not.toContainEqual(
+      expect.objectContaining({package: '@acme/widgets', code: 'integration_error'}),
+    );
+  });
+});
+
 describe('Project.issuesUrl routing', () => {
   it('routes core to config.issuesUrl, falling back to the default', async () => {
     scaffold({issuesUrl: 'https://example.com/core'});

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

@@ -83,5 +83,12 @@ export function auditAuthoringSelfDocs({ root, sources, budget, }?: {
 }>;
 /** The directory the self-docs live under. */
 export const AUTHORING_ROOT: string;
+/** The guide that holds every authoring schema, one section each. */
+export const AUTHORING_REFERENCE_NAME: "field-reference";
+/**
+ * Its route. `astryx docs authoring <name>` reads one of its sections through
+ * the authoring namespace (spec:AST-046 FR6).
+ */
+export const AUTHORING_REFERENCE_ROUTE: "authoring/field-reference";
 /** Every authoring self-doc, relative to {@link AUTHORING_ROOT}, in reading order. */
 export const AUTHORING_SELF_DOCS: string[];

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

@@ -9,7 +9,7 @@
  *   `authoring` reference topic with one section per self-doc, and an audit
  *   naming any self-doc the topic cannot reach, any that fails to load, and any
  *   section over the docs output budget.
- * @position Read by assets/docs/authoring.doc.mjs (the topic) and by Doctor
+ * @position Read by assets/docs/tree/field-reference.doc.mjs (the guide) and by Doctor
  *   (the audit). Lives in foundation because authoring/ holds only contracts.
  *   A new `*.doc.mjs` under authoring/ must be added to the list, or Doctor and
  *   the self-doc tests fail.
@@ -27,6 +27,15 @@ import {
 /** The directory the self-docs live under. */
 export const AUTHORING_ROOT = path.join(CLI_ROOT, 'authoring');
 
+/** The guide that holds every authoring schema, one section each. */
+export const AUTHORING_REFERENCE_NAME = 'field-reference';
+
+/**
+ * Its route. `astryx docs authoring <name>` reads one of its sections through
+ * the authoring namespace (spec:AST-046 FR6).
+ */
+export const AUTHORING_REFERENCE_ROUTE = `authoring/${AUTHORING_REFERENCE_NAME}`;
+
 /** Every authoring self-doc, relative to {@link AUTHORING_ROOT}, in reading order. */
 export const AUTHORING_SELF_DOCS = [
   'integration/integration.doc.mjs',
@@ -189,11 +198,14 @@ export function selfDocSection(doc) {
  */
 export function buildAuthoringReferenceDoc(docs) {
   return /** @type {any} */ ({
-    name: 'authoring',
-    title: 'Authoring Reference',
+    type: 'generic',
+    name: AUTHORING_REFERENCE_NAME,
+    placement: {parent: 'namespace:authoring', slot: 'reference', order: 10},
+    title: 'Field reference',
     category: 'guide',
+    keywords: ['authoring reference', 'field reference', 'every field'],
     description:
-      'Every file an integration author writes, field by field: the integration manifest, astryx.config, codemods, identity, and each doc type. The step-by-step guides are under `astryx docs cli/integrations`.',
+      'Every file an integration author writes, field by field: the integration manifest, astryx.config, codemods, identity, and each doc type. The guides that use them are the rest of {@link namespace:authoring}.',
     sections: docs.map(selfDocSection),
   });
 }

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

@@ -38,20 +38,32 @@ describe('authoring self-docs', () => {
     });
   });
 
-  it('builds a valid topic with one section per self-doc', async () => {
-    const topic = await buildAuthoringTopic();
+  it('builds a valid guide with one section per self-doc, placed under authoring', async () => {
+    const {placement, ...topic} = await buildAuthoringTopic();
     expect(problemsInTopic(topic)).toEqual([]);
     expect(topic.sections).toHaveLength(AUTHORING_SELF_DOCS.length);
+    expect(placement).toEqual({
+      parent: 'namespace:authoring',
+      slot: 'reference',
+      order: 10,
+    });
   });
 
   it(
     'is readable progressively through the docs API',
     async () => {
-      const index = await docs('authoring', undefined, {index: true});
+      const index = await docs('authoring/field-reference', undefined, {
+        index: true,
+      });
       expect(index.type).toBe('docs.index');
       expect(index.data.sections.map(s => s.id)).toContain('integration');
+      // The namespace answers a section read from the field reference, as
+      // `astryx docs authoring <name>` always has.
       const section = await docs('authoring', 'integration');
       expect(section.data.title).toBe('Astryx Integration');
+      expect(
+        (await docs('authoring/field-reference', 'integration')).data,
+      ).toEqual(section.data);
       expect(section.data.content.some(block => block.type === 'table')).toBe(
         true,
       );

package/foundation/discovery/authoring-surface.d.mts

@@ -30,7 +30,7 @@ export function tracePublicAuthoringTypes(root?: string): {
  * 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.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;
+};