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

package/api/integration/authoring-checks.test.mjs

@@ -14,6 +14,7 @@ vi.mock('../../foundation/discovery/template-conflict-release.mjs', () => ({
 }));
 import * as fs from 'node:fs';
 import * as path from 'node:path';
+import {validateIntegration} from './validate-integration.mjs';
 import {discoverCoreTemplates} from '../../foundation/discovery/template-adapter.mjs';
 import {discoverOwnedComponents} from '../../foundation/discovery/component-discovery.mjs';
 import {discoverBuiltinTopics} from '../../foundation/discovery/docs-discovery.mjs';
@@ -1331,3 +1332,222 @@ describe('links in component docs and topic descriptions', () => {
     ]);
   });
 });
+
+describe('validateIntegration runner-command notes', () => {
+  /** The runner-command notes, read back into their parts. */
+  async function runnerNotes() {
+    const {data} = await validateIntegration(undefined, {cwd: tmpDir});
+    const notes = (data.notes ?? [])
+      .filter((/** @type {any} */ note) => note.code === 'runner_command')
+      .map((/** @type {any} */ note) => {
+        const m =
+          /^(\S+): "([^"]+)"(?: \(section "([^"]+)"\))? writes `([^`]+)`(?: \(line (\d+)\))?\./.exec(
+            note.message,
+          );
+        return {
+          file: m?.[1],
+          topic: m?.[2],
+          section: m?.[3] ?? null,
+          command: m?.[4],
+          line: m?.[5] ? Number(m[5]) : null,
+          message: note.message,
+        };
+      });
+    return {data, notes};
+  }
+
+  function writeTopic(/** @type {string} */ text) {
+    fs.writeFileSync(
+      path.join(tmpDir, 'package.json'),
+      JSON.stringify({name: '@acme/widgets', version: '1.2.3'}),
+    );
+    fs.writeFileSync(
+      path.join(tmpDir, 'astryx.integration.mjs'),
+      `export default {docs: './docs'};\n`,
+    );
+    fs.mkdirSync(path.join(tmpDir, 'docs'), {recursive: true});
+    const doc = {
+      type: 'generic',
+      name: 'acme-setup',
+      title: 'Fixture',
+      description: 'Fixture topic.',
+      sections: [
+        {
+          title: 'Overview',
+          content: [
+            {type: 'prose', text},
+            {type: 'code', lang: 'bash', code: 'npx @astryxdesign/cli init'},
+          ],
+        },
+      ],
+    };
+    fs.writeFileSync(
+      path.join(tmpDir, 'docs', 'acme-setup.doc.mjs'),
+      `export default ${JSON.stringify(doc)};\n`,
+    );
+  }
+
+  it('lists a runner command with its line and fix, and raises no issue', async () => {
+    writeTopic('Check it with `pnpm exec astryx doctor` first.');
+
+    const {data, notes} = await runnerNotes();
+    const [hit, ...rest] = notes;
+
+    expect(rest).toEqual([]);
+    expect(hit).toMatchObject({
+      topic: 'acme-setup',
+      section: 'Overview',
+      file: 'docs/acme-setup.doc.mjs',
+      line: 1,
+      command: 'pnpm exec astryx doctor',
+    });
+    expect(hit.message).toContain('Write `astryx doctor`');
+    // A note only: no issue, so no exit changes on it.
+    expect(
+      data.issues.map((/** @type {any} */ issue) => issue.code),
+    ).not.toContain('runner_command');
+  });
+
+  it('puts each copy of a repeated command on its own line', async () => {
+    fs.writeFileSync(
+      path.join(tmpDir, 'package.json'),
+      JSON.stringify({name: '@acme/widgets', version: '1.2.3'}),
+    );
+    fs.writeFileSync(
+      path.join(tmpDir, 'astryx.integration.mjs'),
+      `export default {docs: './docs'};\n`,
+    );
+    fs.mkdirSync(path.join(tmpDir, 'docs'), {recursive: true});
+    const doc = {
+      type: 'generic',
+      name: 'acme-setup',
+      title: 'Fixture',
+      description: 'Fixture topic.',
+      sections: [
+        {
+          title: 'First',
+          content: [{type: 'prose', text: 'Run `npx astryx doctor`.'}],
+        },
+        {
+          title: 'Second',
+          content: [{type: 'prose', text: 'Run `npx astryx doctor` again.'}],
+        },
+        {
+          title: 'Third',
+          content: [{type: 'prose', text: 'Or plain `npx astryx`.'}],
+        },
+      ],
+    };
+    fs.writeFileSync(
+      path.join(tmpDir, 'docs', 'acme-setup.doc.mjs'),
+      `export default ${JSON.stringify(doc, null, 2)};\n`,
+    );
+    const lines = fs
+      .readFileSync(path.join(tmpDir, 'docs', 'acme-setup.doc.mjs'), 'utf8')
+      .split('\n');
+    const lineHolding = (/** @type {string} */ text) =>
+      lines.findIndex(line => line.includes(text)) + 1;
+
+    const {notes} = await runnerNotes();
+
+    expect(
+      notes.map((/** @type {any} */ each) => [
+        each.section,
+        each.line,
+        each.command,
+      ]),
+    ).toEqual([
+      ['First', lineHolding('Run `npx astryx doctor`.'), 'npx astryx doctor'],
+      ['Second', lineHolding('again.'), 'npx astryx doctor'],
+      ['Third', lineHolding('Or plain'), 'npx astryx'],
+    ]);
+  });
+
+  it('puts each copy of an identical one-line string on its own line', async () => {
+    fs.writeFileSync(
+      path.join(tmpDir, 'package.json'),
+      JSON.stringify({name: '@acme/widgets', version: '1.2.3'}),
+    );
+    fs.writeFileSync(
+      path.join(tmpDir, 'astryx.integration.mjs'),
+      `export default {docs: './docs'};\n`,
+    );
+    fs.mkdirSync(path.join(tmpDir, 'docs'), {recursive: true});
+    const block = {type: 'code', lang: 'bash', code: 'npx astryx doctor'};
+    const doc = {
+      type: 'generic',
+      name: 'acme-setup',
+      title: 'Fixture',
+      description: 'Fixture topic.',
+      sections: [
+        {title: 'First', content: [block]},
+        {title: 'Second', content: [block]},
+      ],
+    };
+    fs.writeFileSync(
+      path.join(tmpDir, 'docs', 'acme-setup.doc.mjs'),
+      `export default ${JSON.stringify(doc, null, 2)};\n`,
+    );
+    const lines = fs
+      .readFileSync(path.join(tmpDir, 'docs', 'acme-setup.doc.mjs'), 'utf8')
+      .split('\n');
+    const copies = lines.flatMap((line, at) =>
+      line.includes('"npx astryx doctor"') ? [at + 1] : [],
+    );
+
+    const {notes} = await runnerNotes();
+
+    expect(copies).toHaveLength(2);
+    expect(
+      notes.map((/** @type {any} */ each) => [each.section, each.line]),
+    ).toEqual([
+      ['First', copies[0]],
+      ['Second', copies[1]],
+    ]);
+  });
+
+  it("places a section's command on its own line when the section sits in a constant above the doc", async () => {
+    fs.writeFileSync(
+      path.join(tmpDir, 'package.json'),
+      JSON.stringify({name: '@acme/widgets', version: '1.2.3'}),
+    );
+    fs.writeFileSync(
+      path.join(tmpDir, 'astryx.integration.mjs'),
+      `export default {docs: './docs'};\n`,
+    );
+    fs.mkdirSync(path.join(tmpDir, 'docs'), {recursive: true});
+    fs.writeFileSync(
+      path.join(tmpDir, 'docs', 'acme-setup.doc.mjs'),
+      [
+        "const install = {title: 'Install', content: [{type: 'prose', text: 'Run `npx astryx doctor`.'}]};",
+        '',
+        'export default {',
+        "  type: 'generic',",
+        "  name: 'acme-setup',",
+        "  title: 'Fixture',",
+        "  description: 'Install first: `npx astryx doctor`.',",
+        '  sections: [install],',
+        '};',
+        '',
+      ].join('\n'),
+    );
+
+    const {notes} = await runnerNotes();
+
+    expect(
+      notes.map((/** @type {any} */ each) => [each.section, each.line]),
+    ).toEqual(
+      expect.arrayContaining([
+        [null, 7],
+        ['Install', 1],
+      ]),
+    );
+  });
+
+  it('lists nothing for bare commands and the scoped install step', async () => {
+    writeTopic('Check it with `astryx doctor` first.');
+
+    const {notes} = await runnerNotes();
+    expect((await runnerNotes()).notes).toEqual([]);
+  });
+});

package/api/integration/pack-check.mjs

@@ -26,6 +26,11 @@ import {fileURLToPath} from 'node:url';
 import {spawnSync} from 'node:child_process';
 import {assertWithin} from '../../foundation/fs/path-safety.mjs';
 import {resolvePackageDir} from '../../foundation/integrations/integrations.mjs';
+import {
+  literalThemeName,
+  rootProblem,
+  symlinkedFolder,
+} from '../../foundation/integrations/validate-contributions.mjs';
 import {
   componentReplacesCliProblem,
   docsTreeCliProblem,
@@ -953,6 +958,10 @@ async function validatePackedThemeExports(
       );
     }
 
+    // The name the source gives defineTheme, when the file says it: the
+    // build names its files after it.
+    const builtName = literalThemeName(source, localTheme.exportName);
+
     const declaredOutputs = declaredThemeBuildOutputs(
       localIntegration,
       localTheme,
@@ -1097,7 +1106,15 @@ async function validatePackedThemeExports(
                 ? `Theme "${localTheme.slug}" module is not the module \`${formatCliCommand(`theme build ${sourceRelative}`, localIntegration.__packageDir)}\` writes and does not only wrap it: ${localWrapper.reason}. A module that wraps the built module may only import the theme's own stylesheet and font stylesheet for their side effects and re-export from the built module either everything or only its theme, as ${localTheme.exportName}.`
                 : localWrapper && !localWrapper.ok
                   ? `Theme "${localTheme.slug}" module re-exports ${localWrapper.reason}, which does not match ${sourceRelative}. Run \`${formatCliCommand(`theme build ${sourceRelative}`, localIntegration.__packageDir)}\` before packing.`
-                  : `Theme "${localTheme.slug}" ${output.kind} does not match ${sourceRelative}. Run \`${formatCliCommand(`theme build ${sourceRelative}`, localIntegration.__packageDir)}\` before packing.`,
+                  : (renamedOutputMessage(
+                      localTheme,
+                      output.kind,
+                      output.local,
+                      source,
+                      builtName,
+                      localIntegration.__packageDir,
+                    ) ??
+                    `Theme "${localTheme.slug}" ${output.kind} does not match ${sourceRelative}. Run \`${formatCliCommand(`theme build ${sourceRelative}`, localIntegration.__packageDir)}\` before packing.`),
             ),
           );
         }
@@ -1265,7 +1282,17 @@ export async function integrationPackCheck(options = {}) {
   // ── Phase 1: structure validation ──
   const localResult = await validateLocalIntegration(cwd);
   /** @type {Issue[]} */
-  const issues = [...localResult.issues];
+  const issues = [
+    ...localResult.issues,
+    // Validate lists these layout findings without counting them. A
+    // package.json npm cannot pack is what fails the pack here, as it did
+    // before they were named; the rest stay warnings, which fail nothing.
+    ...(localResult.found ? (localResult.listed ?? []) : []).map(issue =>
+      issue.code === 'invalid_package_json'
+        ? {...issue, severity: /** @type {const} */ ('error')}
+        : issue,
+    ),
+  ];
 
   if (!localResult.found || !localResult.integration) {
     return emptyReceipt(pkgName, [
@@ -1314,6 +1341,8 @@ export async function integrationPackCheck(options = {}) {
     );
   }
   for (const root of fileInv.roots) {
+    // A root that is not a readable folder has its own issue.
+    if (rootProblem(/** @type {string} */ (loaded[root.kind]))) continue;
     if (root.files.length === 0) {
       issues.push(
         error(
@@ -1403,6 +1432,9 @@ export async function integrationPackCheck(options = {}) {
   );
   /** @type {string|null} */
   let scratchBase = null;
+  /** @type {string|undefined} the packed copy of the package */
+  let extractDir;
+  const issuesBeforePack = issues.length;
 
   try {
     // npm pack
@@ -1451,11 +1483,16 @@ export async function integrationPackCheck(options = {}) {
     for (const root of fileInv.roots) {
       const missing = root.files.filter(f => !packResult.packedPaths.has(f));
       if (missing.length === root.files.length && root.files.length > 0) {
+        const absolute = /** @type {string} */ (loaded[root.kind]);
+        const link = symlinkedFolder(absolute, packageDir);
         issues.push(
           error(
             'root_not_packed',
             `Declared ${root.kind} root "${root.path}" has 0 of ${root.files.length} expected ` +
-              `files in the pack list. Add "${root.path.replace(/^\.\//, '')}" to "files" in package.json.`,
+              `files in the pack list. ` +
+              (link
+                ? `It is reached through the symlink "${path.relative(packageDir, link.path).split(path.sep).join('/')}", and npm pack does not follow a symlinked folder. Fix: replace the link with the folder itself, or point "${root.kind}" at the folder it links to.`
+                : `Add "${root.path.replace(/^\.\//, '')}" to "files" in package.json.`),
           ),
         );
       } else {
@@ -1494,7 +1531,6 @@ export async function integrationPackCheck(options = {}) {
     }
 
     // ── Phase 3: extract + identity comparison ──
-    let extractDir;
     try {
       extractDir = resolvePackageDir(pkgName, scratchBase);
     } catch (err) {
@@ -1616,11 +1652,94 @@ export async function integrationPackCheck(options = {}) {
       issues,
     );
   } finally {
+    // The packed copy lives in a scratch folder that is gone once this
+    // returns: name its files the way the package does.
+    if (extractDir && scratchBase) {
+      packageRelative(issues.slice(issuesBeforePack), extractDir, scratchBase);
+    }
     removeTreeBestEffort(tgzTmpDir, 'temporary tarball directory', issues);
     removeTreeBestEffort(scratchBase, 'scratch consumer', issues);
   }
 }
 
+/**
+ * When a theme's source names it something other than the file the package
+ * exports for it, a rebuild writes new files under that name and leaves the
+ * exported one stale forever: say so, with both ways out. Null otherwise.
+ * @param {{slug: string}} theme
+ * @param {string} kind 'module' or 'stylesheet'
+ * @param {string} exported the file the package exports for it
+ * @param {string} source the theme's source
+ * @param {string | null} builtName the literal defineTheme name, if any
+ * @param {string} packageDir
+ * @returns {string | null}
+ */
+function renamedOutputMessage(
+  theme,
+  kind,
+  exported,
+  source,
+  builtName,
+  packageDir,
+) {
+  if (builtName == null || builtName === theme.slug) return null;
+  const extension = kind === 'module' ? '.js' : '.css';
+  if (path.basename(exported) === `${builtName}${extension}`) return null;
+  const rel = (/** @type {string} */ file) =>
+    path.relative(packageDir, file).split(path.sep).join('/');
+  const built = rel(
+    path.join(path.dirname(source), `${builtName}${extension}`),
+  );
+  return `Theme "${theme.slug}" ${kind} is ${rel(exported)}, but ${path.basename(source)} calls defineTheme with name: '${builtName}', so \`${formatCliCommand(`theme build ${rel(source)}`, packageDir)}\` writes ${built} instead and rebuilding never updates ${path.basename(exported)}. Fix: point the package export that serves it at ${built} after building, or set name: '${theme.slug}' in ${path.basename(source)} and rebuild.`;
+}
+
+/**
+ * Rewrite the scratch copy's absolute paths in each issue's message: a file
+ * of the packed package as its path in the package, and any other path in the
+ * scratch consumer (such as the module that resolved an import) as that
+ * consumer. Both folders are gone once verify returns.
+ * @param {Issue[]} issues
+ * @param {string} packedDir the packed package inside the scratch consumer
+ * @param {string} consumerDir the scratch consumer
+ */
+function packageRelative(issues, packedDir, consumerDir) {
+  /** @param {string} dir */
+  const spellings = dir => {
+    const out = [dir];
+    try {
+      const real = fs.realpathSync(dir);
+      if (real !== dir) out.push(real);
+    } catch {
+      // Already removed: the plain path is all there is.
+    }
+    return out;
+  };
+  /** @param {string} text */
+  const escape = text => text.replace(/[.*+?^${}()|[\]\\]/gu, '\\$&');
+  const packed = spellings(packedDir);
+  const consumer = spellings(consumerDir);
+  for (const issue of issues) {
+    if (typeof issue.message !== 'string') continue;
+    let message = issue.message;
+    for (const prefix of packed) {
+      message = message
+        .split(`${prefix}${path.sep}`)
+        .join('')
+        .replace(
+          new RegExp(`${escape(prefix)}(?![\\w-]|\\.\\w)`, 'gu'),
+          'the package root',
+        );
+    }
+    for (const prefix of consumer) {
+      message = message.replace(
+        new RegExp(`${escape(prefix)}[^\\s"'\`]*`, 'gu'),
+        'a consumer project',
+      );
+    }
+    issue.message = message;
+  }
+}
+
 /**
  * Assemble the receipt.
  * @param {string} name

package/api/integration/pack-check.test.mjs

@@ -580,6 +580,24 @@ describe('a theme module that loads its own styles', () => {
     expect(cli.status, cli.stderr).toBe(0);
   });
 
+  it('says a rebuild cannot fix exports that name the theme after its folder once its source renames it', async () => {
+    writePackage({
+      files: ['astryx.integration.mjs', 'themes'],
+      themeExports: true,
+    });
+    fs.writeFileSync(
+      path.join(tmpDir, 'themes', 'ocean', 'oceanTheme.ts'),
+      "import {defineTheme} from '@astryxdesign/core/theme';\n\nexport const oceanTheme = defineTheme({name: 'sea'});\n",
+    );
+
+    const result = await integrationPackCheck({cwd: tmpDir});
+
+    expect(result.data.issues.map(issue => issue.message)).toEqual([
+      `Theme "ocean" module is themes/ocean/ocean.js, but oceanTheme.ts calls defineTheme with name: 'sea', so \`${formatCliCommand('theme build themes/ocean/oceanTheme.ts', tmpDir)}\` writes themes/ocean/sea.js instead and rebuilding never updates ocean.js. Fix: point the package export that serves it at themes/ocean/sea.js after building, or set name: 'ocean' in oceanTheme.ts and rebuild.`,
+      `Theme "ocean" stylesheet is themes/ocean/ocean.css, but oceanTheme.ts calls defineTheme with name: 'sea', so \`${formatCliCommand('theme build themes/ocean/oceanTheme.ts', tmpDir)}\` writes themes/ocean/sea.css instead and rebuilding never updates ocean.css. Fix: point the package export that serves it at themes/ocean/sea.css after building, or set name: 'ocean' in oceanTheme.ts and rebuild.`,
+    ]);
+  });
+
   it('compares a partial export set with the module named after the theme', async () => {
     writeRenamedOcean();
     setThemeExports({'./themes/ocean': './themes/ocean/deep-sea.js'});
@@ -1919,6 +1937,75 @@ describe('integrationPackCheck', () => {
     expect(sourceWarnings[0].message).toContain('stray.tsx');
   });
 
+  it('says npm pack skips a symlinked root instead of asking for a "files" entry', async () => {
+    writePackage({
+      manifest:
+        "export default {themes: './themes', components: './components'};\n",
+    });
+    const real = path.join(tmpDir, 'real-components');
+    fs.mkdirSync(real, {recursive: true});
+    fs.writeFileSync(
+      path.join(real, 'Card.doc.mjs'),
+      "export default {type: 'component', name: 'Card', displayName: 'Card', usage: {description: 'Card.'}, props: []};\n",
+    );
+    fs.writeFileSync(
+      path.join(real, 'Card.tsx'),
+      'export function Card() { return null; }\n',
+    );
+    fs.symlinkSync('real-components', path.join(tmpDir, 'components'));
+
+    const result = await integrationPackCheck({cwd: tmpDir});
+    const codes = result.data.issues.map(issue => issue.code);
+    expect(codes).toContain('symlinked_root');
+    const notPacked = result.data.issues.find(
+      issue => issue.code === 'root_not_packed',
+    );
+    expect(notPacked?.message).toBe(
+      'Declared components root "components" has 0 of 2 expected files in the pack list. It is reached through the symlink "components", and npm pack does not follow a symlinked folder. Fix: replace the link with the folder itself, or point "components" at the folder it links to.',
+    );
+  });
+
+  it('names packed files by their path in the package, never the scratch copy', async () => {
+    writePackage({
+      manifest:
+        "export default {themes: './themes', docs: './docs/a.doc.mjs'};\n",
+    });
+    fs.mkdirSync(path.join(tmpDir, 'docs'), {recursive: true});
+    fs.writeFileSync(path.join(tmpDir, 'docs', 'a.doc.mjs'), '');
+
+    const result = await integrationPackCheck({cwd: tmpDir});
+    const messages = result.data.issues.map(issue => issue.message);
+    expect(messages.join('\n')).not.toContain(
+      path.join(tmpDir, '.astryx-pack-check-'),
+    );
+    expect(messages).toContain(
+      'Packed: Declared docs root is a file, not a folder: docs/a.doc.mjs. Fix: point "docs" in the manifest at the folder that holds them.',
+    );
+    // The root's own issue covers it: no empty-root error, no raw errno.
+    const codes = result.data.issues.map(issue => issue.code);
+    expect(codes).not.toContain('empty_contribution_root');
+    expect(codes).not.toContain('local_discovery_failed');
+    expect(codes).not.toContain('packed_discovery_failed');
+  });
+
+  it('fails on a package.json npm cannot pack, which validate only warns about', async () => {
+    writePackage({files: ['astryx.integration.mjs', 'themes']});
+    const packageFile = path.join(tmpDir, 'package.json');
+    const pkg = JSON.parse(fs.readFileSync(packageFile, 'utf-8'));
+    delete pkg.name;
+    fs.writeFileSync(packageFile, `${JSON.stringify(pkg, null, 2)}\n`);
+
+    const result = await integrationPackCheck({cwd: tmpDir});
+
+    expect(result.data.packable).toBe(false);
+    expect(
+      result.data.issues.map(issue => [issue.code, issue.severity]),
+    ).toEqual([
+      ['invalid_package_json', 'error'],
+      ['pack_failed', 'error'],
+    ]);
+  });
+
   it('cleans up its scratch consumer when npm pack fails', async () => {
     writePackage({
       files: ['astryx.integration.mjs', 'themes'],

package/api/integration/validate-integration-case-disk.test.mjs

@@ -0,0 +1,111 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file A component doc whose file name differs from its source only in
+ * letter case, on a case-insensitive disk (macOS, Windows), where discovery
+ * still pairs the two: a warning naming the rename, not an error. The disk is
+ * simulated by finding the doc's source case-insensitively.
+ */
+
+import {afterEach, beforeEach, describe, expect, it, vi} from 'vitest';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+vi.mock(
+  '../../foundation/discovery/component-discovery.mjs',
+  async importOriginal => {
+    const original =
+      /** @type {typeof import('../../foundation/discovery/component-discovery.mjs')} */ (
+        await importOriginal()
+      );
+    return {
+      ...original,
+      /** @param {string} docPath */
+      integrationSourceForDoc: docPath => {
+        const dir = path.dirname(docPath);
+        const want = `${path
+          .basename(docPath)
+          .replace(/\.doc\.(ts|mjs|js)$/u, '')}.tsx`.toLowerCase();
+        const found = fs
+          .readdirSync(dir)
+          .find(name => name.toLowerCase() === want);
+        return found ? path.join(dir, found) : null;
+      },
+    };
+  },
+);
+
+const {validateIntegration} = await import('./validate-integration.mjs');
+
+/** @type {string} */
+let tmpDir;
+
+beforeEach(() => {
+  tmpDir = fs.mkdtempSync(path.join(process.cwd(), '.astryx-case-disk-'));
+});
+
+afterEach(() => {
+  fs.rmSync(tmpDir, {recursive: true, force: true});
+});
+
+describe('a doc whose name differs from its source only in case, on a case-insensitive disk', () => {
+  it('lists source_without_component_doc with the rename, without an issue', async () => {
+    fs.writeFileSync(
+      path.join(tmpDir, 'package.json'),
+      JSON.stringify({name: '@acme/kit', version: '1.0.0'}),
+    );
+    fs.writeFileSync(
+      path.join(tmpDir, 'astryx.integration.mjs'),
+      "export default {components: './components'};\n",
+    );
+    fs.mkdirSync(path.join(tmpDir, 'components'));
+    fs.writeFileSync(
+      path.join(tmpDir, 'components', 'Acmewidget.doc.mjs'),
+      "export default {type: 'component', name: 'AcmeWidget', displayName: 'AcmeWidget', usage: {description: 'A widget.'}, props: []};\n",
+    );
+    fs.writeFileSync(
+      path.join(tmpDir, 'components', 'AcmeWidget.tsx'),
+      'export function AcmeWidget() { return null; }\n',
+    );
+
+    const {data} = await validateIntegration(undefined, {cwd: tmpDir});
+    expect(data.issues).toEqual([]);
+    expect(data.notes).toEqual([
+      {
+        code: 'source_without_component_doc',
+        message:
+          'Component doc "Acmewidget.doc.mjs" and its source "AcmeWidget.tsx" differ only in letter case. They pair on a case-insensitive disk (macOS, Windows) but not on Linux, where CI and most installs run, so there the component is missing. Fix: rename Acmewidget.doc.mjs to AcmeWidget.doc.mjs.',
+      },
+    ]);
+  });
+
+  it('lists a hidden doc that pairs with its source, without an issue', async () => {
+    fs.writeFileSync(
+      path.join(tmpDir, 'package.json'),
+      JSON.stringify({name: '@acme/kit', version: '1.0.0'}),
+    );
+    fs.writeFileSync(
+      path.join(tmpDir, 'astryx.integration.mjs'),
+      "export default {components: './components'};\n",
+    );
+    fs.mkdirSync(path.join(tmpDir, 'components'));
+    fs.writeFileSync(
+      path.join(tmpDir, 'components', 'Acmewidget.doc.mjs'),
+      "export default {type: 'component',\n  hidden: true,\n  name: 'AcmeWidget', displayName: 'AcmeWidget', usage: {description: 'A widget.'}, props: []};\n",
+    );
+    fs.writeFileSync(
+      path.join(tmpDir, 'components', 'AcmeWidget.tsx'),
+      'export function AcmeWidget() { return null; }\n',
+    );
+
+    const {data} = await validateIntegration(undefined, {cwd: tmpDir});
+    expect(data.issues).toEqual([]);
+    expect(data.notes).toEqual([
+      {
+        code: 'source_without_component_doc',
+        message:
+          'Hidden component doc "Acmewidget.doc.mjs" and its source "AcmeWidget.tsx" differ only in letter case. They pair on a case-insensitive disk (macOS, Windows) but not on Linux, where CI and most installs run. Fix: rename Acmewidget.doc.mjs to AcmeWidget.doc.mjs.',
+      },
+    ]);
+  });
+});