@astryxdesign/cli 0.7.2-canary.ebcc404 → 0.7.2-canary.f8f7cf1

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

@@ -132,6 +132,35 @@ export const GRAPH_BLOCK_TYPES: Set<string>;
  * load; a guide the tree places may set `placement` (spec:AST-046).
  */
 export const GRAPH_ONLY_FIELDS: string[];
+/**
+ * A component a link can name: its owner's provider id, package, and name,
+ * and the doc file that describes it.
+ * @typedef {object} LinkableComponent
+ * @property {string} providerId
+ * @property {string} package
+ * @property {string} name
+ * @property {string | null} docPath
+ * @property {string} [replaces] the Core component whose name it answers to
+ *   in unqualified lookups (spec:AST-035 FR11)
+ */
+/**
+ * A page or block template a link can name, by the id `astryx template` takes.
+ * @typedef {object} LinkableTemplate
+ * @property {string} providerId
+ * @property {string} package
+ * @property {'page' | 'block'} type
+ * @property {string} id
+ * @property {string} name
+ * @property {string} [displayName]
+ * @property {string} [description]
+ * @property {string} [replaces] the Core template id it answers to in
+ *   unqualified lookups
+ */
+/**
+ * The component and template docs links can name (spec:AST-047 FR9). No docs
+ * tree holds them, so a catalog carries the records the project reads.
+ * @typedef {{components: LinkableComponent[], templates: LinkableTemplate[]}} LinkableContributions
+ */
 /**
  * Every topic a project can read, and the relationships between them.
  *
@@ -181,6 +210,18 @@ export class DocsCatalog {
         namespaces: import("../doc-compiler/tree.mjs").TreeNamespaceInput[];
         guides: import("../doc-compiler/tree.mjs").TreeDocInput[];
     }>;
+    /**
+     * Say where links find component, page, and block docs: the records
+     * `astryx component` and `astryx template` read, loaded on first use.
+     * @param {() => Promise<LinkableContributions>} load
+     */
+    setContributions(load: () => Promise<LinkableContributions>): void;
+    /**
+     * The component and template docs links can name, or null when nothing set
+     * them, so no link to one resolves.
+     * @returns {Promise<LinkableContributions | null>}
+     */
+    contributions(): Promise<LinkableContributions | null>;
     /**
      * Add one integration-contributed doc, honoring what it declares. Returns
      * the issue it caused, or null when it applied cleanly — the caller owns
@@ -290,4 +331,44 @@ export type DocsTopicEntry = {
      */
     tree?: boolean | undefined;
 };
+/**
+ * A component a link can name: its owner's provider id, package, and name,
+ * and the doc file that describes it.
+ */
+export type LinkableComponent = {
+    providerId: string;
+    package: string;
+    name: string;
+    docPath: string | null;
+    /**
+     * the Core component whose name it answers to
+     * in unqualified lookups (spec:AST-035 FR11)
+     */
+    replaces?: string | undefined;
+};
+/**
+ * A page or block template a link can name, by the id `astryx template` takes.
+ */
+export type LinkableTemplate = {
+    providerId: string;
+    package: string;
+    type: "page" | "block";
+    id: string;
+    name: string;
+    displayName?: string | undefined;
+    description?: string | undefined;
+    /**
+     * the Core template id it answers to in
+     * unqualified lookups
+     */
+    replaces?: string | undefined;
+};
+/**
+ * The component and template docs links can name (spec:AST-047 FR9). No docs
+ * tree holds them, so a catalog carries the records the project reads.
+ */
+export type LinkableContributions = {
+    components: LinkableComponent[];
+    templates: LinkableTemplate[];
+};
 import { withSourceTitle } from './docs-section-key.mjs';

package/foundation/discovery/docs-discovery.mjs

@@ -633,6 +633,38 @@ function findMergeTarget(sections, section) {
   return sections.findIndex(candidate => candidate.id === key);
 }
 
+/**
+ * A component a link can name: its owner's provider id, package, and name,
+ * and the doc file that describes it.
+ * @typedef {object} LinkableComponent
+ * @property {string} providerId
+ * @property {string} package
+ * @property {string} name
+ * @property {string | null} docPath
+ * @property {string} [replaces] the Core component whose name it answers to
+ *   in unqualified lookups (spec:AST-035 FR11)
+ */
+
+/**
+ * A page or block template a link can name, by the id `astryx template` takes.
+ * @typedef {object} LinkableTemplate
+ * @property {string} providerId
+ * @property {string} package
+ * @property {'page' | 'block'} type
+ * @property {string} id
+ * @property {string} name
+ * @property {string} [displayName]
+ * @property {string} [description]
+ * @property {string} [replaces] the Core template id it answers to in
+ *   unqualified lookups
+ */
+
+/**
+ * The component and template docs links can name (spec:AST-047 FR9). No docs
+ * tree holds them, so a catalog carries the records the project reads.
+ * @typedef {{components: LinkableComponent[], templates: LinkableTemplate[]}} LinkableContributions
+ */
+
 /**
  * Every topic a project can read, and the relationships between them.
  *
@@ -644,6 +676,10 @@ function findMergeTarget(sections, section) {
 export class DocsCatalog {
   /** @type {Map<string, DocsTopicEntry>} */
   #topics = new Map();
+  /** @type {(() => Promise<LinkableContributions>) | null} */
+  #contributions = null;
+  /** @type {Promise<LinkableContributions> | null} */
+  #contributionsLoaded = null;
   /** @type {Map<string, string>} old topic name → the name that replaced it */
   #aliases = new Map();
   /** @type {Array<{namespaces: import('../doc-compiler/tree.mjs').TreeNamespaceInput[], guides: import('../doc-compiler/tree.mjs').TreeDocInput[]}>} */
@@ -687,6 +723,27 @@ export class DocsCatalog {
     return this.#treeInputs;
   }
 
+  /**
+   * Say where links find component, page, and block docs: the records
+   * `astryx component` and `astryx template` read, loaded on first use.
+   * @param {() => Promise<LinkableContributions>} load
+   */
+  setContributions(load) {
+    this.#contributions = load;
+    this.#contributionsLoaded = null;
+  }
+
+  /**
+   * The component and template docs links can name, or null when nothing set
+   * them, so no link to one resolves.
+   * @returns {Promise<LinkableContributions | null>}
+   */
+  contributions() {
+    if (!this.#contributions) return Promise.resolve(null);
+    this.#contributionsLoaded ??= this.#contributions();
+    return this.#contributionsLoaded;
+  }
+
   /**
    * Seed a catalog with the CLI's own topics.
    * @param {Record<string, string>} [builtins] topic name → absolute path

package/foundation/discovery/integration-doc-files.d.mts

@@ -0,0 +1,22 @@
+// @generated by scripts/sync-api-types.mjs from the JSDoc in foundation/**/*.mjs.
+// DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
+
+/** @typedef {import('./doc-types.mjs').DocFile} DocFile */
+/** @typedef {import('./doc-types.mjs').DocRoot} DocRoot */
+/**
+ * Every doc file an integration's roots hold, each assigned to the deepest
+ * root that holds it, each root a reader could not read, and how many test
+ * fixtures no reader serves.
+ * @param {any} integration a loaded integration
+ * @returns {Promise<{files: DocFile[], unread: Array<{path: string, reason: string}>, fixtures: number}>}
+ */
+export function integrationDocFiles(integration: any): Promise<{
+    files: DocFile[];
+    unread: Array<{
+        path: string;
+        reason: string;
+    }>;
+    fixtures: number;
+}>;
+export type DocFile = import("./doc-types.mjs").DocFile;
+export type DocRoot = import("./doc-types.mjs").DocRoot;

package/foundation/discovery/integration-doc-files.mjs

@@ -0,0 +1,231 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file The doc files an integration package ships, by root: every doc its
+ * roots hold, so the doc type check covers each one an agent can open.
+ *
+ * Each root's reader names the docs it serves, with the kind it reads each
+ * as:
+ * - components: the doc each component discovery records;
+ * - templates: the doc of each template template discovery serves;
+ * - docs: the file of each topic, namespace and placed guide docs discovery
+ *   serves, and each topic's and guide's `zh` and `dense` overlay that a docs
+ *   read applies;
+ * - themes: each theme's descriptor, as theme discovery resolves it. A themes
+ *   root that discovery cannot read serves no theme, and is listed with the
+ *   reason.
+ * A doc no reader serves still ships: a `hidden` one, a second doc for one
+ * name, an overlay without its topic. It goes to its root's kind. A test
+ * fixture does not ship as a doc, and is only counted: a doc under
+ * `__tests__` in the components or docs root, which those readers skip.
+ * A file two roots hold goes to the deepest.
+ *
+ * @input A loaded integration and its resolved roots.
+ * @output DocFile entries for checkDocTypes, each with the root it belongs to,
+ *   the roots a reader could not read, and how many test fixtures it left
+ *   out.
+ * @position Read by `astryx doctor integration validate` before it checks
+ *   each doc against its authoring type.
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import {OVERLAY_LANGUAGES, overlayPath} from '../doc-compiler/read.mjs';
+import {discoverIntegrationComponents} from './component-discovery.mjs';
+import {discoverIntegrationDocs} from './docs-discovery.mjs';
+import {discoverIntegrationTemplatesForOne} from './template-adapter.mjs';
+import {discoverThemeDirectory} from './theme-discovery.mjs';
+import {rootProblem} from '../integrations/validate-contributions.mjs';
+
+/** @typedef {import('./doc-types.mjs').DocFile} DocFile */
+/** @typedef {import('./doc-types.mjs').DocRoot} DocRoot */
+
+/**
+ * Every doc file an integration's roots hold, each assigned to the deepest
+ * root that holds it, each root a reader could not read, and how many test
+ * fixtures no reader serves.
+ * @param {any} integration a loaded integration
+ * @returns {Promise<{files: DocFile[], unread: Array<{path: string, reason: string}>, fixtures: number}>}
+ */
+export async function integrationDocFiles(integration) {
+  const {components, templates, docs, themes} = integration ?? {};
+  /** @type {Array<[DocRoot, string, string[]]>} */
+  const read = [];
+  /** @type {Array<{path: string, reason: string}>} */
+  const unread = [];
+  // A root `validate` already reports (missing, a file, unreadable) is left
+  // to that issue. A reader that fails inside a root, such as on a folder it
+  // cannot read, leaves the root listed with the reason.
+  /** @type {(root: string | undefined, label: string, files: () => Promise<Array<[DocRoot, string[]]>>) => Promise<void>} */
+  const take = async (root, label, files) => {
+    if (!root || rootProblem(root)) return;
+    try {
+      for (const [kind, list] of await files()) read.push([kind, root, list]);
+    } catch (err) {
+      unread.push({
+        path: root,
+        reason: `the ${label} root does not load, so no doc in it was checked: ${err instanceof Error ? err.message : String(err)}`,
+      });
+    }
+  };
+  await take(components, 'components', async () => [
+    [
+      'components',
+      discoverIntegrationComponents(integration).map(c => c.docPath),
+    ],
+  ]);
+  await take(templates, 'templates', async () => [
+    [
+      'templates',
+      (await discoverIntegrationTemplatesForOne(integration)).templates.map(
+        t => t.docPath,
+      ),
+    ],
+  ]);
+  await take(docs, 'docs', async () => {
+    const found = await discoverIntegrationDocs(integration);
+    // Topics and placed guides are read with their overlays; a namespace
+    // names its file `<package name>/<path in the root>`.
+    const withOverlays = [
+      ...found.records.map(record => record.path),
+      ...found.guides.map(guide => guide.ref.topicFile),
+    ];
+    const prefix = `${integration.name}/`;
+    const namespaces = found.namespaces.map(entry =>
+      path.join(
+        /** @type {string} */ (docs),
+        ...(entry.source.startsWith(prefix)
+          ? entry.source.slice(prefix.length)
+          : entry.source
+        ).split('/'),
+      ),
+    );
+    return [
+      ['docs', [...withOverlays, ...namespaces]],
+      [
+        'docs-overlay',
+        withOverlays.flatMap(file =>
+          OVERLAY_LANGUAGES.map(lang => overlayPath(file, lang)).filter(
+            overlay => fs.existsSync(overlay),
+          ),
+        ),
+      ],
+    ];
+  });
+  await take(themes, 'themes', async () => [
+    [
+      'themes',
+      discoverThemeDirectory(
+        /** @type {string} */ (themes),
+        integration?.name ?? 'the package',
+      ).map(theme => theme.docPath),
+    ],
+  ]);
+  /** @type {Map<string, {root: DocRoot, dir: string}>} */
+  const owners = new Map();
+  /** @type {(table: Map<string, {root: DocRoot, dir: string}>, root: DocRoot, dir: string, file: string) => void} */
+  const own = (table, root, dir, file) => {
+    const owner = table.get(file);
+    if (!owner || dir.length > owner.dir.length) table.set(file, {root, dir});
+  };
+  for (const [root, dir, files] of read) {
+    for (const file of files) own(owners, root, dir, file);
+  }
+  // The docs no reader serves, in each root a reader could read.
+  /** @type {Map<string, {root: DocRoot, dir: string}>} */
+  const shipped = new Map();
+  const readable = new Set(read.map(([, dir]) => dir));
+  for (const [
+    kind,
+    dir,
+  ] of /** @type {Array<[DocRoot, string | undefined]>} */ ([
+    ['components', components],
+    ['templates', templates],
+    ['docs', docs],
+    ['themes', themes],
+  ])) {
+    if (!dir || !readable.has(dir)) continue;
+    for (const file of docFilesUnder(dir)) {
+      const overlay = OVERLAY_LANGUAGES.some(lang =>
+        file.endsWith(`.doc.${lang}.mjs`),
+      );
+      if (overlay && kind !== 'docs') continue;
+      own(shipped, overlay ? 'docs-overlay' : kind, dir, file);
+    }
+  }
+  let fixtures = 0;
+  for (const [file, owner] of shipped) {
+    if (owners.has(file)) continue;
+    if (isFixture(path.relative(owner.dir, file), owner.root)) fixtures++;
+    else owners.set(file, owner);
+  }
+  return {
+    files: [...owners]
+      .map(([file, {root}]) => ({path: file, root}))
+      .sort((a, b) => a.path.localeCompare(b.path)),
+    unread,
+    fixtures,
+  };
+}
+
+/**
+ * Whether a doc file is a test fixture: under `__tests__` in a root whose
+ * reader skips that folder (components and docs). The template reader reads
+ * it, so a template doc there is the package's like any other.
+ * @param {string} file its path relative to its root
+ * @param {DocRoot} root
+ */
+function isFixture(file, root) {
+  return (
+    root !== 'templates' &&
+    root !== 'themes' &&
+    file.split(path.sep).includes('__tests__')
+  );
+}
+
+/**
+ * Every doc file under a folder: a `.doc.ts`, `.doc.mjs` or `.doc.js` file,
+ * or a `zh` or `dense` overlay, through its folders and linked files, but not
+ * `node_modules`, `.git` or a linked folder.
+ * @param {string} dir
+ * @returns {string[]}
+ */
+function docFilesUnder(dir) {
+  /** @type {string[]} */
+  const found = [];
+  /** @type {(folder: string) => void} */
+  const walk = folder => {
+    /** @type {fs.Dirent[]} */
+    let entries;
+    try {
+      entries = fs.readdirSync(folder, {withFileTypes: true});
+    } catch {
+      return;
+    }
+    for (const entry of entries) {
+      if (entry.name === 'node_modules' || entry.name === '.git') continue;
+      const full = path.join(folder, entry.name);
+      if (entry.isDirectory()) {
+        walk(full);
+        continue;
+      }
+      if (entry.isSymbolicLink()) {
+        try {
+          if (!fs.statSync(full).isFile()) continue;
+        } catch {
+          continue;
+        }
+      } else if (!entry.isFile()) {
+        continue;
+      }
+      if (
+        /\.doc\.(ts|mjs|js)$/.test(entry.name) ||
+        OVERLAY_LANGUAGES.some(lang => entry.name.endsWith(`.doc.${lang}.mjs`))
+      ) {
+        found.push(full);
+      }
+    }
+  };
+  walk(dir);
+  return found;
+}

package/foundation/discovery/integration-doc-files.test.mjs

@@ -0,0 +1,246 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file integrationDocFiles(): exactly the docs each root's reader serves, a
+ * nested root's files given to that root, and a root its reader cannot read.
+ */
+
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import {afterEach, beforeEach, describe, expect, it} from 'vitest';
+import {discoverIntegrationComponents} from './component-discovery.mjs';
+import {integrationDocFiles} from './integration-doc-files.mjs';
+
+/** @type {string} */
+let pkg;
+
+beforeEach(() => {
+  pkg = fs.realpathSync(
+    fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-doc-files-')),
+  );
+});
+
+afterEach(() => {
+  fs.rmSync(pkg, {recursive: true, force: true});
+});
+
+/**
+ * @param {string} rel
+ * @param {string} text
+ */
+function write(rel, text) {
+  const file = path.join(pkg, rel);
+  fs.mkdirSync(path.dirname(file), {recursive: true});
+  fs.writeFileSync(file, text);
+  return file;
+}
+
+/** @param {string} name */
+const component = name =>
+  `export default {type: 'component', name: '${name}', displayName: '${name}', usage: {description: 'x'}, props: []};\n`;
+/** @param {string} name */
+const topic = name =>
+  `export default {type: 'generic', name: '${name}', title: 'T', description: 'D', sections: [{title: 'S', content: [{type: 'prose', text: 'x'}]}]};\n`;
+/** @param {string} rel a template doc, with its same-stem source */
+const template = rel => {
+  write(rel.replace(/\.doc\.mjs$/, '.tsx'), 'export default () => null;\n');
+  return write(
+    rel,
+    `export default {type: 'block', name: '${path.basename(rel, '.doc.mjs')}', description: 'D'};\n`,
+  );
+};
+
+/** @param {Awaited<ReturnType<typeof integrationDocFiles>>['files']} files */
+const listed = files =>
+  files
+    .map(f => [path.relative(pkg, f.path).split(path.sep).join('/'), f.root])
+    .sort();
+
+describe('integrationDocFiles', () => {
+  it('reads a fixture folder relative to its root, so a package under a `__tests__` folder is checked', async () => {
+    write(
+      '__tests__/acme/components/Hidden.doc.mjs',
+      `${component('Hidden')}\n  hidden: true\n`,
+    );
+    write(
+      '__tests__/acme/components/__tests__/Tested.doc.mjs',
+      component('Tested'),
+    );
+
+    const {files, fixtures} = await integrationDocFiles({
+      name: '@acme/widgets',
+      components: path.join(pkg, '__tests__', 'acme', 'components'),
+    });
+
+    expect(listed(files)).toEqual([
+      ['__tests__/acme/components/Hidden.doc.mjs', 'components'],
+    ]);
+    expect(fixtures).toBe(1);
+  });
+
+  it("gives a nested root's files to that root", async () => {
+    write('src/Badge.doc.mjs', component('Badge'));
+    write('src/docs/guide.doc.mjs', topic('guide'));
+    write('src/docs/guide.doc.zh.mjs', 'export const docsZh = {};\n');
+    template('templates/hero.doc.mjs');
+
+    const {files, unread} = await integrationDocFiles({
+      name: '@acme/widgets',
+      components: path.join(pkg, 'src'),
+      docs: path.join(pkg, 'src', 'docs'),
+      templates: path.join(pkg, 'templates'),
+    });
+
+    expect(unread).toEqual([]);
+    expect(listed(files)).toEqual([
+      ['src/Badge.doc.mjs', 'components'],
+      ['src/docs/guide.doc.mjs', 'docs'],
+      ['src/docs/guide.doc.zh.mjs', 'docs-overlay'],
+      ['templates/hero.doc.mjs', 'templates'],
+    ]);
+  });
+
+  it('takes every doc the roots hold, served or not, and counts a test fixture no reader serves', async () => {
+    write('components/__fixtures__/Fixture.doc.mjs', component('Fixture'));
+    write('components/.drafts/Draft.doc.mjs', component('Draft'));
+    write('components/__tests__/Tested.doc.mjs', component('Tested'));
+    write(
+      'components/Hidden.doc.mjs',
+      `${component('Hidden')}\n  hidden: true\n`,
+    );
+    write('components/Twice.doc.mjs', component('Twice'));
+    write('components/again/Twice.doc.mjs', component('Twice'));
+    write('shared/Linked.doc.mjs', component('Linked'));
+    fs.symlinkSync(
+      path.join(pkg, 'shared', 'Linked.doc.mjs'),
+      path.join(pkg, 'components', 'Linked.doc.mjs'),
+    );
+    template('templates/__tests__/tested.doc.mjs');
+    write('templates/orphan.doc.mjs', "export default {type: 'block'};\n");
+    // The template reader reads `__fixtures__`: a template doc there without
+    // its source is the package's, so it is checked.
+    write(
+      'templates/__fixtures__/bad.doc.mjs',
+      "export default {type: 'block'};\n",
+    );
+    write('docs/__tests__/sample.doc.mjs', topic('sample'));
+    write('docs/.drafts/topic.doc.mjs', topic('topic'));
+    write('docs/.drafts/topic.doc.zh.mjs', 'export const docsZh = {};\n');
+    write('docs/copy.doc.mjs', topic('topic'));
+    write('docs/orphan.doc.dense.mjs', 'export const docsDense = {};\n');
+    write('themes/oceanTheme.doc.mjs', 'export default {};\n');
+    const integration = {
+      name: '@acme/widgets',
+      components: path.join(pkg, 'components'),
+      templates: path.join(pkg, 'templates'),
+      docs: path.join(pkg, 'docs'),
+      themes: path.join(pkg, 'themes'),
+    };
+
+    const {files, unread, fixtures} = await integrationDocFiles(integration);
+
+    // Component discovery skips `__tests__` and a `hidden` doc, and serves the
+    // first doc of a name; a template without its source, a second topic of
+    // a name, and an overlay without its topic are not served either. All of
+    // them ship, so all are checked, but a test fixture no reader serves.
+    const served = discoverIntegrationComponents(integration).map(c =>
+      path.relative(pkg, c.docPath),
+    );
+    expect(served.filter(file => file.endsWith('Twice.doc.mjs'))).toHaveLength(
+      1,
+    );
+    expect(listed(files)).toEqual(
+      [
+        ...served.map(file => [file, 'components']),
+        ['components/Hidden.doc.mjs', 'components'],
+        ['components/again/Twice.doc.mjs', 'components'],
+        ['docs/.drafts/topic.doc.mjs', 'docs'],
+        ['docs/.drafts/topic.doc.zh.mjs', 'docs-overlay'],
+        ['docs/copy.doc.mjs', 'docs'],
+        ['docs/orphan.doc.dense.mjs', 'docs-overlay'],
+        ['templates/__fixtures__/bad.doc.mjs', 'templates'],
+        ['templates/__tests__/tested.doc.mjs', 'templates'],
+        ['templates/orphan.doc.mjs', 'templates'],
+      ].sort(),
+    );
+    // `components/__tests__/Tested` and `docs/__tests__/sample`.
+    expect(fixtures).toBe(2);
+    expect(served.sort()).toEqual(
+      expect.arrayContaining([
+        'components/.drafts/Draft.doc.mjs',
+        'components/Linked.doc.mjs',
+        'components/__fixtures__/Fixture.doc.mjs',
+      ]),
+    );
+    expect(served.some(file => /Tested|Hidden/.test(file))).toBe(false);
+    // Theme discovery serves no theme from this root, so none is checked,
+    // and the root says why.
+    expect(unread).toEqual([
+      {
+        path: integration.themes,
+        reason: expect.stringMatching(
+          /^the themes root does not load, so no doc in it was checked: .*lower-kebab/,
+        ),
+      },
+    ]);
+  });
+
+  it("takes a scoped package's namespace docs and placed guides where they are, with each guide's overlays", async () => {
+    write(
+      'docs/guides/guides.doc.mjs',
+      `export const docs = ${JSON.stringify({type: 'namespace', name: 'guides', title: 'Guides', summary: 'Every guide.', slots: {guides: {title: 'Guides', accepts: {kinds: ['generic']}}}})};\n`,
+    );
+    write(
+      'docs/guides/setup.doc.mjs',
+      `export const docs = ${JSON.stringify({type: 'generic', name: 'setup', title: 'Set up', description: 'D', placement: {parent: 'namespace:guides', slot: 'guides', order: 1}, sections: [{title: 'S', content: [{type: 'prose', text: 'x'}]}]})};\n`,
+    );
+    write('docs/guides/setup.doc.zh.mjs', 'export const docsZh = {};\n');
+    write('docs/guides/setup.doc.dense.mjs', 'export const docsDense = {};\n');
+
+    const {files, unread} = await integrationDocFiles({
+      name: '@acme/widgets',
+      docs: path.join(pkg, 'docs'),
+    });
+
+    expect(unread).toEqual([]);
+    expect(listed(files)).toEqual([
+      ['docs/guides/guides.doc.mjs', 'docs'],
+      ['docs/guides/setup.doc.dense.mjs', 'docs-overlay'],
+      ['docs/guides/setup.doc.mjs', 'docs'],
+      ['docs/guides/setup.doc.zh.mjs', 'docs-overlay'],
+    ]);
+  });
+
+  it('leaves a root validate reports to that issue, and lists a root whose reader fails inside it', async () => {
+    write('components/Badge.doc.mjs', component('Badge'));
+    write('components/locked/Inner.doc.mjs', component('Inner'));
+    write('docs/guide.doc.mjs', topic('guide'));
+    const locked = path.join(pkg, 'components', 'locked');
+    fs.chmodSync(path.join(pkg, 'docs'), 0o000);
+    fs.chmodSync(locked, 0o000);
+    try {
+      const {files, unread} = await integrationDocFiles({
+        name: '@acme/widgets',
+        components: path.join(pkg, 'components'),
+        docs: path.join(pkg, 'docs'),
+        templates: path.join(pkg, 'missing'),
+      });
+
+      // `validate` reports the unreadable docs root and the missing templates
+      // root itself; the components root reads until its locked folder.
+      expect(files).toEqual([]);
+      expect(unread).toEqual([
+        {
+          path: path.join(pkg, 'components'),
+          reason: expect.stringMatching(
+            /^the components root does not load, so no doc in it was checked: .*EACCES/,
+          ),
+        },
+      ]);
+    } finally {
+      fs.chmodSync(path.join(pkg, 'docs'), 0o755);
+      fs.chmodSync(locked, 0o755);
+    }
+  });
+});

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

@@ -29,3 +29,9 @@ export function moduleExportSource(file: string, exportName: string, seen?: Set<
  * @returns {Record<string, unknown> | null}
  */
 export function staticExportObject(file: string, exportNames: readonly string[]): Record<string, unknown> | null;
+/**
+ * Marks an object {@link staticExportObject} returns (or one inside it) whose
+ * source also has properties or spreads it could not read as literals. Not
+ * enumerable, so the object compares and serializes as its literal properties.
+ */
+export const HAS_COMPUTED: unique symbol;