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

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

@@ -17,6 +17,7 @@ import {
   integrationAddComponent,
   integrationAddTemplate,
 } from './add-contribution.mjs';
+import {formatCliCommand} from '../../foundation/env/package-manager.mjs';
 
 let tmpDir;
 
@@ -213,6 +214,7 @@ function writePackage({
   themeExports = false,
   npmignore,
   components = false,
+  templates = false,
   scripts,
 } = {}) {
   const pkg = {name, version};
@@ -272,6 +274,14 @@ export default {type: 'theme', name: 'ocean', displayName: 'Ocean', description:
       'export default function Card() { return null; }\n',
     );
   }
+  if (templates) {
+    const root = path.join(tmpDir, 'templates');
+    fs.mkdirSync(root, {recursive: true});
+    fs.writeFileSync(
+      path.join(root, 'stray.tsx'),
+      'export default function Stray() { return null; }\n',
+    );
+  }
   if (npmignore) {
     fs.writeFileSync(path.join(tmpDir, '.npmignore'), npmignore);
   }
@@ -303,6 +313,363 @@ function runCliVerify() {
   };
 }
 
+/**
+ * Give the built ocean theme a font stylesheet and an entry module that loads
+ * the theme's own styles, and export them the way such a package does.
+ * @param {string} entry
+ * @param {string} [file] the entry's file name in `entries/`
+ */
+function writeOwnStylesEntry(entry, file = 'ocean.mjs') {
+  fs.writeFileSync(
+    path.join(tmpDir, 'themes', 'ocean', 'ocean.fonts.css'),
+    "@font-face { font-family: 'Ocean Sans'; src: local('Ocean Sans'); }\n",
+  );
+  fs.mkdirSync(path.join(tmpDir, 'entries'), {recursive: true});
+  fs.writeFileSync(path.join(tmpDir, 'entries', file), entry);
+  const packageFile = path.join(tmpDir, 'package.json');
+  const pkg = JSON.parse(fs.readFileSync(packageFile, 'utf-8'));
+  pkg.files = ['astryx.integration.mjs', 'themes', 'entries'];
+  pkg.exports = {
+    './themes/ocean': `./entries/${file}`,
+    './themes/ocean.css': './themes/ocean/ocean.css',
+    './themes/ocean.fonts.css': './themes/ocean/ocean.fonts.css',
+  };
+  fs.writeFileSync(packageFile, `${JSON.stringify(pkg, null, 2)}\n`);
+}
+
+/**
+ * Rename the ocean theme to deep-sea, keeping its `ocean` slug, and build it,
+ * so its outputs are named after the theme: `deep-sea.css` and `deep-sea.js`,
+ * which exports `deepSeaTheme`.
+ */
+function writeRenamedOcean() {
+  writePackage({files: ['astryx.integration.mjs', 'themes', 'entries']});
+  fs.writeFileSync(
+    path.join(tmpDir, 'themes', 'ocean', 'oceanTheme.ts'),
+    "import {defineTheme} from '@astryxdesign/core/theme';\n\nexport const oceanTheme = defineTheme({name: 'deep-sea'});\n",
+  );
+  const built = spawnSync(
+    process.execPath,
+    [
+      path.join(process.cwd(), 'packages/cli/clients/cli/bin/astryx.mjs'),
+      'theme',
+      'build',
+      'themes/ocean/oceanTheme.ts',
+    ],
+    {cwd: tmpDir, encoding: 'utf-8', timeout: 30_000},
+  );
+  if (built.status !== 0) {
+    throw new Error(`Could not build the theme fixture: ${built.stderr}`);
+  }
+}
+
+/**
+ * Give the ocean theme an icon registry and build it, so its built module
+ * also exports `oceanIcons`.
+ */
+function writeOceanWithIcons() {
+  writePackage({files: ['astryx.integration.mjs', 'themes', 'entries']});
+  const themeDir = path.join(tmpDir, 'themes', 'ocean');
+  fs.writeFileSync(
+    path.join(themeDir, 'icons.js'),
+    'export const oceanIcons = {};\n',
+  );
+  fs.writeFileSync(
+    path.join(themeDir, 'oceanTheme.ts'),
+    "import {defineTheme} from '@astryxdesign/core/theme';\nimport {oceanIcons} from './icons';\n\nexport const oceanTheme = defineTheme({name: 'ocean', icons: oceanIcons});\n",
+  );
+  const built = spawnSync(
+    process.execPath,
+    [
+      path.join(process.cwd(), 'packages/cli/clients/cli/bin/astryx.mjs'),
+      'theme',
+      'build',
+      'themes/ocean/oceanTheme.ts',
+    ],
+    {cwd: tmpDir, encoding: 'utf-8', timeout: 30_000},
+  );
+  if (built.status !== 0) {
+    throw new Error(`Could not build the theme fixture: ${built.stderr}`);
+  }
+}
+
+// An entry like one whose import is the whole integration: it loads the
+// theme's fonts and stylesheet, by relative path and through the package's
+// own exports, and re-exports the built theme.
+const OWN_STYLES_ENTRY = `// Copyright (c) Acme.
+
+import '../themes/ocean/ocean.fonts.css';
+import '@acme/widgets/themes/ocean.css';
+
+export {oceanTheme} from '../themes/ocean/ocean.js';
+`;
+
+describe('a theme module that loads its own styles', () => {
+  it('passes an entry that imports the theme stylesheet and fonts and re-exports the built module', async () => {
+    writePackage({themeExports: true});
+    writeOwnStylesEntry(OWN_STYLES_ENTRY);
+
+    const result = await integrationPackCheck({cwd: tmpDir});
+
+    expect(result.data.issues).toEqual([]);
+    expect(result.data.packable).toBe(true);
+    const cli = runCliVerify();
+    expect(cli.status, cli.stderr).toBe(0);
+    expect(cli.receipt?.data.issues).toEqual([]);
+  });
+
+  it('passes an entry that imports its fonts through the package exports and re-exports everything', async () => {
+    writePackage({themeExports: true});
+    writeOwnStylesEntry(
+      "import '@acme/widgets/themes/ocean.fonts.css';\nimport '../themes/ocean/ocean.css';\nexport * from '../themes/ocean/ocean.js';\n",
+    );
+
+    const result = await integrationPackCheck({cwd: tmpDir});
+
+    expect(result.data.issues).toEqual([]);
+    expect(result.data.packable).toBe(true);
+  });
+
+  it.each([
+    [
+      'also imports another stylesheet',
+      `${OWN_STYLES_ENTRY}import './other.css';\n`,
+      "./other.css is not the theme's own stylesheet or font stylesheet",
+    ],
+    [
+      'also imports a script',
+      `import './setup.mjs';\n${OWN_STYLES_ENTRY}`,
+      "./setup.mjs is not the theme's own stylesheet or font stylesheet",
+    ],
+    [
+      'runs code',
+      `${OWN_STYLES_ENTRY}console.log('ocean');\n`,
+      'line 7 is neither a stylesheet import nor the re-export',
+    ],
+    [
+      'exports another value',
+      `${OWN_STYLES_ENTRY}export const extra = 1;\n`,
+      'line 7 is neither a stylesheet import nor the re-export',
+    ],
+    [
+      'renames the theme it re-exports',
+      "import '../themes/ocean/ocean.css';\nexport {oceanTheme, oceanTheme as theme} from '../themes/ocean/ocean.js';\n",
+      'it re-exports names other than oceanTheme',
+    ],
+    [
+      'binds the stylesheet it imports',
+      "import styles from '../themes/ocean/ocean.css';\nexport {oceanTheme} from '../themes/ocean/ocean.js';\n",
+      'its import of ../themes/ocean/ocean.css is not a side-effect import',
+    ],
+    [
+      'imports the stylesheet as a CSS module script',
+      "import '../themes/ocean/ocean.css' with {type: 'css'};\nexport {oceanTheme} from '../themes/ocean/ocean.js';\n",
+      'its import of ../themes/ocean/ocean.css is not a side-effect import',
+    ],
+    [
+      're-exports another name',
+      "import '../themes/ocean/ocean.css';\nexport {oceanTheme, missing} from '../themes/ocean/ocean.js';\n",
+      'it re-exports names other than oceanTheme',
+    ],
+    [
+      're-exports a copy that is not a .js module',
+      "import '../themes/ocean/ocean.css';\nexport {oceanTheme} from './copy.cjs';\n",
+      'its re-export from ./copy.cjs does not name a .js module',
+    ],
+    [
+      'has a directive',
+      `'use client';\n${OWN_STYLES_ENTRY}`,
+      'it has a directive',
+    ],
+    [
+      're-exports twice',
+      `${OWN_STYLES_ENTRY}export * from '../themes/ocean/ocean.js';\n`,
+      'it has more than one re-export',
+    ],
+  ])('fails an entry that %s', async (_label, entry, reason) => {
+    writePackage({themeExports: true});
+    writeOwnStylesEntry(entry);
+    fs.writeFileSync(path.join(tmpDir, 'entries', 'other.css'), '.x {}\n');
+    fs.writeFileSync(path.join(tmpDir, 'entries', 'setup.mjs'), 'export {};\n');
+    fs.copyFileSync(
+      path.join(tmpDir, 'themes', 'ocean', 'ocean.js'),
+      path.join(tmpDir, 'entries', 'copy.cjs'),
+    );
+
+    const result = await integrationPackCheck({cwd: tmpDir});
+
+    expect(result.data.packable).toBe(false);
+    expect(result.data.issues).toEqual([
+      {
+        code: 'theme_module_stale',
+        severity: 'error',
+        message: `Theme "ocean" module is not the module \`${formatCliCommand('theme build themes/ocean/oceanTheme.ts', tmpDir)}\` writes and does not only wrap it: ${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 oceanTheme.`,
+      },
+    ]);
+  });
+
+  it('fails an entry whose re-exported module drifts from source', async () => {
+    writePackage({themeExports: true});
+    writeOwnStylesEntry(OWN_STYLES_ENTRY);
+    fs.appendFileSync(
+      path.join(tmpDir, 'themes', 'ocean', 'ocean.js'),
+      '// stale module\n',
+    );
+
+    const result = await integrationPackCheck({cwd: tmpDir});
+
+    expect(result.data.packable).toBe(false);
+    expect(result.data.issues).toEqual([
+      {
+        code: 'theme_module_stale',
+        severity: 'error',
+        message: `Theme "ocean" module re-exports ../themes/ocean/ocean.js, which does not match themes/ocean/oceanTheme.ts. Run \`${formatCliCommand('theme build themes/ocean/oceanTheme.ts', tmpDir)}\` before packing.`,
+      },
+    ]);
+  });
+
+  it('does not accept a TypeScript entry', async () => {
+    writePackage({themeExports: true});
+    writeOwnStylesEntry(OWN_STYLES_ENTRY, 'ocean.ts');
+
+    const result = await integrationPackCheck({cwd: tmpDir});
+
+    expect(result.data.packable).toBe(false);
+    expect(result.data.issues).toEqual([
+      {
+        code: 'theme_module_stale',
+        severity: 'error',
+        message: `Theme "ocean" module does not match themes/ocean/oceanTheme.ts. Run \`${formatCliCommand('theme build themes/ocean/oceanTheme.ts', tmpDir)}\` before packing.`,
+      },
+    ]);
+  });
+
+  it('does not accept an entry that re-exports itself', async () => {
+    writePackage({themeExports: true});
+    writeOwnStylesEntry(
+      "import '../themes/ocean/ocean.css';\nexport * from './ocean.js';\n",
+      'ocean.js',
+    );
+
+    const result = await integrationPackCheck({cwd: tmpDir});
+
+    expect(result.data.packable).toBe(false);
+    expect(result.data.issues).toContainEqual(
+      expect.objectContaining({
+        code: 'theme_import_unresolvable',
+        message: expect.stringContaining('does not export "oceanTheme"'),
+      }),
+    );
+  });
+
+  it('passes an entry for a theme whose own name differs from its slug', async () => {
+    writeRenamedOcean();
+    writeOwnStylesEntry(
+      "import '../themes/ocean/deep-sea.css';\nexport {deepSeaTheme as oceanTheme} from '../themes/ocean/deep-sea.js';\n",
+    );
+    setThemeExports({
+      './themes/ocean': './entries/ocean.mjs',
+      './themes/ocean.css': './themes/ocean/deep-sea.css',
+    });
+
+    const result = await integrationPackCheck({cwd: tmpDir});
+
+    expect(result.data.issues).toEqual([]);
+    expect(result.data.packable).toBe(true);
+    const cli = runCliVerify();
+    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'});
+
+    const result = await integrationPackCheck({cwd: tmpDir});
+
+    expect(result.data.packable).toBe(true);
+    expect(result.data.issues.map(issue => issue.code)).toEqual([
+      'theme_exports_incomplete',
+    ]);
+  });
+
+  it('passes an entry that re-exports only the theme from a built module that also exports its icons', async () => {
+    writeOceanWithIcons();
+    writeOwnStylesEntry(OWN_STYLES_ENTRY);
+
+    const result = await integrationPackCheck({cwd: tmpDir});
+
+    expect(result.data.issues).toEqual([]);
+    expect(result.data.packable).toBe(true);
+  });
+
+  it('fails an entry that gives the built icons the theme export name', async () => {
+    writeOceanWithIcons();
+    writeOwnStylesEntry(
+      "import '../themes/ocean/ocean.css';\nexport {oceanIcons as oceanTheme} from '../themes/ocean/ocean.js';\n",
+    );
+
+    const result = await integrationPackCheck({cwd: tmpDir});
+
+    expect(result.data.packable).toBe(false);
+    expect(result.data.issues).toEqual([
+      expect.objectContaining({
+        code: 'theme_module_stale',
+        message: expect.stringContaining(
+          'it re-exports oceanIcons, which is not the built theme',
+        ),
+      }),
+    ]);
+  });
+
+  it('fails when packing changes the module an entry re-exports', async () => {
+    const prepack = [
+      "const fs=require('fs')",
+      "fs.copyFileSync('themes/ocean/ocean.js','.ocean.js.orig')",
+      "fs.appendFileSync('themes/ocean/ocean.js','// packed\\n')",
+    ].join(';');
+    const postpack =
+      "require('fs').renameSync('.ocean.js.orig','themes/ocean/ocean.js')";
+    writePackage({
+      themeExports: true,
+      scripts: {
+        prepack: `node -e "${prepack}"`,
+        postpack: `node -e "${postpack}"`,
+      },
+    });
+    writeOwnStylesEntry(OWN_STYLES_ENTRY);
+
+    const result = await integrationPackCheck({cwd: tmpDir});
+
+    expect(result.data.packable).toBe(false);
+    expect(result.data.issues).toEqual([
+      {
+        code: 'packed_theme_module_changed',
+        severity: 'error',
+        message:
+          'Theme "ocean" module changed during packing. Keep the built output unchanged in the tarball.',
+      },
+    ]);
+  });
+});
+
 describe('integrationPackCheck', () => {
   it('returns packable:true for a valid integration with themes', async () => {
     writePackage({files: ['astryx.integration.mjs', 'themes']});
@@ -337,8 +704,7 @@ describe('integrationPackCheck', () => {
       {
         code: 'theme_exports_missing',
         severity: 'warning',
-        message:
-          'Theme "ocean" has no declared built exports. The package remains source-compatible. To make it importable, run `astryx theme build themes/ocean/oceanTheme.ts` and export "./themes/ocean" plus "./themes/ocean.css" from package.json; `astryx integration add theme ocean` creates those exports for a new theme.',
+        message: `Theme "ocean" has no declared built exports. The package remains source-compatible. To make it importable, run \`${formatCliCommand('theme build themes/ocean/oceanTheme.ts', tmpDir)}\` and export "./themes/ocean" plus "./themes/ocean.css" from package.json; \`${formatCliCommand('integration add theme ocean', tmpDir)}\` creates those exports for a new theme.`,
       },
     ]);
     const cli = runCliVerify();
@@ -509,8 +875,7 @@ describe('integrationPackCheck', () => {
       {
         code: 'theme_stylesheet_stale',
         severity: 'warning',
-        message:
-          'Theme "ocean" stylesheet does not match themes/ocean/oceanTheme.ts. This incomplete export remains packable, but run `astryx theme build themes/ocean/oceanTheme.ts` before adding its matching export.',
+        message: `Theme "ocean" stylesheet does not match themes/ocean/oceanTheme.ts. This incomplete export remains packable, but run \`${formatCliCommand('theme build themes/ocean/oceanTheme.ts', tmpDir)}\` before adding its matching export.`,
       },
     ]);
     const cli = runCliVerify();
@@ -543,8 +908,7 @@ describe('integrationPackCheck', () => {
       {
         code: 'theme_stylesheet_stale',
         severity: 'warning',
-        message:
-          'Theme "ocean" stylesheet does not match themes/ocean/oceanTheme.ts. This incomplete export remains packable, but run `astryx theme build themes/ocean/oceanTheme.ts` before adding its matching export.',
+        message: `Theme "ocean" stylesheet does not match themes/ocean/oceanTheme.ts. This incomplete export remains packable, but run \`${formatCliCommand('theme build themes/ocean/oceanTheme.ts', tmpDir)}\` before adding its matching export.`,
       },
     ]);
     const cli = runCliVerify();
@@ -617,14 +981,12 @@ describe('integrationPackCheck', () => {
       {
         code: 'theme_module_stale',
         severity: 'error',
-        message:
-          'Theme "ocean" module does not match themes/ocean/oceanTheme.ts. Run `astryx theme build themes/ocean/oceanTheme.ts` before packing.',
+        message: `Theme "ocean" module does not match themes/ocean/oceanTheme.ts. Run \`${formatCliCommand('theme build themes/ocean/oceanTheme.ts', tmpDir)}\` before packing.`,
       },
       {
         code: 'theme_stylesheet_stale',
         severity: 'error',
-        message:
-          'Theme "ocean" stylesheet does not match themes/ocean/oceanTheme.ts. Run `astryx theme build themes/ocean/oceanTheme.ts` before packing.',
+        message: `Theme "ocean" stylesheet does not match themes/ocean/oceanTheme.ts. Run \`${formatCliCommand('theme build themes/ocean/oceanTheme.ts', tmpDir)}\` before packing.`,
       },
     ]);
     const cli = runCliVerify();
@@ -754,6 +1116,285 @@ describe('integrationPackCheck', () => {
     );
   });
 
+  it('checks the export a component doc names when its file is named otherwise', async () => {
+    fs.writeFileSync(
+      path.join(tmpDir, 'package.json'),
+      `${JSON.stringify({
+        name: '@acme/widgets',
+        version: '1.0.0',
+        files: ['astryx.integration.mjs', 'components'],
+        exports: {'./components/Slides': './components/Slides.tsx'},
+      })}\n`,
+    );
+    fs.writeFileSync(
+      path.join(tmpDir, 'astryx.integration.mjs'),
+      "export default {components: './components'};\n",
+    );
+    fs.mkdirSync(path.join(tmpDir, 'components'));
+    // Slides.tsx exports AcmeCarousel and nothing named Slides.
+    fs.writeFileSync(
+      path.join(tmpDir, 'components', 'Slides.tsx'),
+      'export function AcmeCarousel() { return null; }\n',
+    );
+    fs.writeFileSync(
+      path.join(tmpDir, 'components', 'Slides.doc.mjs'),
+      "export default {type: 'component', name: 'AcmeCarousel', import: '@acme/widgets/components/Slides', description: 'x', props: []};\n",
+    );
+
+    const result = await integrationPackCheck({cwd: tmpDir});
+    expect(result.data.packable).toBe(true);
+    expect(result.data.contributions.packed.components).toEqual([
+      'AcmeCarousel',
+    ]);
+  });
+
+  it('checks each family member against the module its family doc imports', async () => {
+    fs.writeFileSync(
+      path.join(tmpDir, 'package.json'),
+      `${JSON.stringify({
+        name: '@acme/widgets',
+        version: '1.0.0',
+        files: ['astryx.integration.mjs', 'components'],
+        exports: {'./tabs': './components/tabs/index.ts'},
+      })}\n`,
+    );
+    fs.writeFileSync(
+      path.join(tmpDir, 'astryx.integration.mjs'),
+      "export default {components: './components'};\n",
+    );
+    const dir = path.join(tmpDir, 'components', 'tabs');
+    fs.mkdirSync(dir, {recursive: true});
+    fs.writeFileSync(
+      path.join(dir, 'AcmeTabs.tsx'),
+      'export function AcmeTabs() { return null; }\nexport function AcmeTabsLegacy() { return null; }\n',
+    );
+    fs.writeFileSync(
+      path.join(dir, 'tab.tsx'),
+      'export function AcmeTab() { return null; }\n',
+    );
+    // The module apps import exports AcmeTabs and AcmeTab, not AcmeTabsLegacy.
+    fs.writeFileSync(
+      path.join(dir, 'index.ts'),
+      "export {AcmeTabs} from './AcmeTabs';\nexport {AcmeTab} from './tab';\n",
+    );
+    fs.writeFileSync(
+      path.join(dir, 'AcmeTabs.doc.mjs'),
+      "export default {type: 'component', name: 'AcmeTabs', import: '@acme/widgets/tabs', description: 'x', components: [{name: 'AcmeTabs', description: 'x', props: []}, {name: 'AcmeTab', description: 'x', props: []}, {name: 'AcmeTabsLegacy', description: 'x', props: []}]};\n",
+    );
+
+    const result = await integrationPackCheck({cwd: tmpDir});
+
+    expect(result.data.issues).toEqual([]);
+    expect(result.data.packable).toBe(true);
+    expect(result.data.contributions.packed.components).toEqual([
+      'AcmeTab',
+      'AcmeTabs',
+    ]);
+  });
+
+  it.each([
+    'a clean checkout',
+    'a stale build',
+    'a stale build that exports more',
+  ])(
+    'reads members a family imports from output its pack lifecycle builds, from %s',
+    async start => {
+      fs.writeFileSync(
+        path.join(tmpDir, 'package.json'),
+        `${JSON.stringify({
+          name: '@acme/widgets',
+          version: '1.0.0',
+          files: ['astryx.integration.mjs', 'components', 'dist'],
+          exports: {'./tabs': './dist/tabs/index.mjs'},
+          scripts: {prepack: 'node build.mjs'},
+        })}\n`,
+      );
+      fs.writeFileSync(
+        path.join(tmpDir, 'astryx.integration.mjs'),
+        "export default {components: './components'};\n",
+      );
+      // The build writes the module the family imports; a clean checkout has none.
+      fs.writeFileSync(
+        path.join(tmpDir, 'build.mjs'),
+        "import fs from 'node:fs';\nfs.mkdirSync('dist/tabs', {recursive: true});\nfs.writeFileSync('dist/tabs/index.mjs', \"export {AcmeTabs, AcmeTab} from '../../components/tabs/AcmeTabs.tsx';\\n\");\n",
+      );
+      const dir = path.join(tmpDir, 'components', 'tabs');
+      fs.mkdirSync(dir, {recursive: true});
+      fs.writeFileSync(
+        path.join(dir, 'AcmeTabs.tsx'),
+        'export function AcmeTabs() { return null; }\nexport function AcmeTab() { return null; }\nexport function AcmeTabLegacy() { return null; }\n',
+      );
+      fs.writeFileSync(
+        path.join(dir, 'AcmeTabs.doc.mjs'),
+        "export default {type: 'component', name: 'AcmeTabs', import: '@acme/widgets/tabs', description: 'x', components: [{name: 'AcmeTabs', description: 'x', props: []}, {name: 'AcmeTab', description: 'x', props: []}, {name: 'AcmeTabLegacy', description: 'x', props: []}]};\n",
+      );
+
+      if (start !== 'a clean checkout') {
+        // An earlier build: before AcmeTab was exported, or while AcmeTabLegacy
+        // still was.
+        const names =
+          start === 'a stale build'
+            ? 'AcmeTabs'
+            : 'AcmeTabs, AcmeTab, AcmeTabLegacy';
+        fs.mkdirSync(path.join(tmpDir, 'dist', 'tabs'), {recursive: true});
+        fs.writeFileSync(
+          path.join(tmpDir, 'dist', 'tabs', 'index.mjs'),
+          `export {${names}} from '../../components/tabs/AcmeTabs.tsx';\n`,
+        );
+      }
+
+      const result = await integrationPackCheck({cwd: tmpDir});
+
+      expect(result.data.issues).toEqual([]);
+      expect(result.data.packable).toBe(true);
+      expect(result.data.contributions.local.components).toEqual(
+        result.data.contributions.packed.components,
+      );
+    },
+  );
+
+  it.each(['a clean checkout', 'an incremental build'])(
+    'reads members built output re-exports from compiled files, from %s',
+    async start => {
+      fs.writeFileSync(
+        path.join(tmpDir, 'package.json'),
+        `${JSON.stringify({
+          name: '@acme/widgets',
+          version: '1.0.0',
+          files: ['astryx.integration.mjs', 'components', 'dist'],
+          exports: {'./tabs': './dist/tabs/index.mjs'},
+          scripts: {prepack: 'node build.mjs'},
+        })}\n`,
+      );
+      fs.writeFileSync(
+        path.join(tmpDir, 'astryx.integration.mjs'),
+        "export default {components: './components'};\n",
+      );
+      // The build compiles each source to its own file and, like an
+      // incremental build, rewrites only the files whose output changed.
+      const output = {
+        'index.mjs':
+          "export {AcmeTabs} from './tabs.mjs';\nexport * from './tab.mjs';\n",
+        'tabs.mjs': 'export function AcmeTabs() { return null; }\n',
+        'tab.mjs': 'export function AcmeTab() { return null; }\n',
+      };
+      fs.writeFileSync(
+        path.join(tmpDir, 'build.mjs'),
+        `import fs from 'node:fs';\nconst output = ${JSON.stringify(output)};\nfs.mkdirSync('dist/tabs', {recursive: true});\nfor (const [file, text] of Object.entries(output)) {\n  const target = 'dist/tabs/' + file;\n  if (!fs.existsSync(target) || fs.readFileSync(target, 'utf-8') !== text) fs.writeFileSync(target, text);\n}\n`,
+      );
+      const dir = path.join(tmpDir, 'components', 'tabs');
+      fs.mkdirSync(dir, {recursive: true});
+      fs.writeFileSync(
+        path.join(dir, 'AcmeTabs.tsx'),
+        'export function AcmeTabs() { return null; }\n',
+      );
+      fs.writeFileSync(
+        path.join(dir, 'AcmeTab.tsx'),
+        'export function AcmeTab() { return null; }\n',
+      );
+      fs.writeFileSync(
+        path.join(dir, 'AcmeTabs.doc.mjs'),
+        "export default {type: 'component', name: 'AcmeTabs', import: '@acme/widgets/tabs', description: 'x', components: [{name: 'AcmeTabs', description: 'x', props: []}, {name: 'AcmeTab', description: 'x', props: []}]};\n",
+      );
+      if (start === 'an incremental build') {
+        // An earlier build from before AcmeTab existed: the file the import
+        // names is already current, so the build leaves it untouched.
+        fs.mkdirSync(path.join(tmpDir, 'dist', 'tabs'), {recursive: true});
+        for (const [file, text] of Object.entries({...output, 'tab.mjs': ''})) {
+          fs.writeFileSync(path.join(tmpDir, 'dist', 'tabs', file), text);
+        }
+      }
+
+      const result = await integrationPackCheck({cwd: tmpDir});
+
+      expect(result.data.issues).toEqual([]);
+      expect(result.data.packable).toBe(true);
+      expect(result.data.contributions.packed.components).toEqual([
+        'AcmeTab',
+        'AcmeTabs',
+      ]);
+      expect(result.data.contributions.local.components).toEqual(
+        result.data.contributions.packed.components,
+      );
+    },
+  );
+
+  it('passes a member another folder declares, which has no source', async () => {
+    fs.writeFileSync(
+      path.join(tmpDir, 'package.json'),
+      `${JSON.stringify({
+        name: '@acme/widgets',
+        version: '1.0.0',
+        files: ['astryx.integration.mjs', 'components'],
+        exports: {'./menu': './components/menu/index.ts'},
+      })}\n`,
+    );
+    fs.writeFileSync(
+      path.join(tmpDir, 'astryx.integration.mjs'),
+      "export default {components: './components'};\n",
+    );
+    const menu = path.join(tmpDir, 'components', 'menu');
+    const shared = path.join(tmpDir, 'components', 'shared');
+    fs.mkdirSync(menu, {recursive: true});
+    fs.mkdirSync(shared, {recursive: true});
+    fs.writeFileSync(
+      path.join(menu, 'AcmeMenu.doc.mjs'),
+      "export default {type: 'component', name: 'AcmeMenu', import: '@acme/widgets/menu', description: 'x', components: [{name: 'AcmeMenuItem', description: 'x', props: []}]};\n",
+    );
+    fs.writeFileSync(
+      path.join(menu, 'AcmeMenu.tsx'),
+      'export function AcmeMenu() { return null; }\n',
+    );
+    fs.writeFileSync(
+      path.join(menu, 'index.ts'),
+      "export {AcmeMenu} from './AcmeMenu';\nexport {AcmeMenuItem} from '../shared/AcmeMenuItem';\n",
+    );
+    fs.writeFileSync(
+      path.join(shared, 'AcmeMenuItem.tsx'),
+      'export function AcmeMenuItem() { return null; }\n',
+    );
+
+    const result = await integrationPackCheck({cwd: tmpDir});
+
+    expect(result.data.issues).toEqual([]);
+    expect(result.data.packable).toBe(true);
+    expect(result.data.contributions.packed.components).toEqual([
+      'AcmeMenu',
+      'AcmeMenuItem',
+    ]);
+  });
+
+  it('reports a family doc the loader rejects once, not once per member', async () => {
+    fs.writeFileSync(
+      path.join(tmpDir, 'package.json'),
+      `${JSON.stringify({
+        name: '@acme/widgets',
+        version: '1.0.0',
+        files: ['astryx.integration.mjs', 'components'],
+      })}\n`,
+    );
+    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', 'AcmeTabs.tsx'),
+      'export function AcmeTabs() { return null; }\nexport function AcmeTab() { return null; }\nexport function AcmeTabPanel() { return null; }\n',
+    );
+    // A displayName that is not a string makes the loader reject the doc.
+    fs.writeFileSync(
+      path.join(tmpDir, 'components', 'AcmeTabs.doc.mjs'),
+      "export default {type: 'component', name: 'AcmeTabs', displayName: 1, description: 'x', components: [{name: 'AcmeTab', description: 'x', props: []}, {name: 'AcmeTabPanel', description: 'x', props: []}]};\n",
+    );
+
+    const result = await integrationPackCheck({cwd: tmpDir});
+    const codes = result.data.issues.map(issue => issue.code);
+
+    expect(codes).toContain('component_doc_unloadable');
+    expect(codes.length).toBe(new Set(codes).size);
+  });
+
   it('passes a generated component through its exact packed export', async () => {
     fs.writeFileSync(
       path.join(tmpDir, 'package.json'),
@@ -811,6 +1452,86 @@ describe('integrationPackCheck', () => {
     );
   });
 
+  it('does not count a type-only re-export as the component', async () => {
+    fs.writeFileSync(
+      path.join(tmpDir, 'package.json'),
+      `${JSON.stringify({
+        name: '@acme/widgets',
+        version: '1.0.0',
+        files: ['astryx.integration.mjs', 'src'],
+        exports: {'.': './src/index.ts'},
+      })}\n`,
+    );
+    fs.writeFileSync(
+      path.join(tmpDir, 'astryx.integration.mjs'),
+      "export default {components: './src'};\n",
+    );
+    fs.mkdirSync(path.join(tmpDir, 'src'));
+    fs.writeFileSync(
+      path.join(tmpDir, 'src', 'index.ts'),
+      "export type {AcmeWidget} from './AcmeWidget';\n",
+    );
+    fs.writeFileSync(
+      path.join(tmpDir, 'src', 'AcmeWidget.tsx'),
+      'export function AcmeWidget() { return null; }\n',
+    );
+    fs.writeFileSync(
+      path.join(tmpDir, 'src', 'AcmeWidget.doc.mjs'),
+      "export default {type: 'component', name: 'AcmeWidget', import: '@acme/widgets', description: 'Widget.', props: []};\n",
+    );
+
+    const result = await integrationPackCheck({cwd: tmpDir});
+
+    expect(result.data.issues).toContainEqual(
+      expect.objectContaining({code: 'component_export_missing'}),
+    );
+  });
+
+  it('follows a re-export of a folder to its index file', async () => {
+    // `./primitives` names a folder: TypeScript and bundlers load its index file.
+    fs.writeFileSync(
+      path.join(tmpDir, 'package.json'),
+      `${JSON.stringify({
+        name: '@acme/widgets',
+        version: '1.0.0',
+        files: ['astryx.integration.mjs', 'src'],
+        exports: {'.': './src/index.ts'},
+      })}\n`,
+    );
+    fs.writeFileSync(
+      path.join(tmpDir, 'astryx.integration.mjs'),
+      "export default {components: './src'};\n",
+    );
+    const primitives = path.join(tmpDir, 'src', 'primitives');
+    fs.mkdirSync(primitives, {recursive: true});
+    fs.writeFileSync(
+      path.join(tmpDir, 'src', 'index.ts'),
+      "export * from './primitives';\n",
+    );
+    fs.writeFileSync(
+      path.join(primitives, 'index.ts'),
+      "export * from './AcmeWidget';\n",
+    );
+    fs.writeFileSync(
+      path.join(primitives, 'AcmeWidget.tsx'),
+      'export function AcmeWidget() { return null; }\n',
+    );
+    fs.writeFileSync(
+      path.join(primitives, 'AcmeWidget.doc.mjs'),
+      "export default {type: 'component', name: 'AcmeWidget', import: '@acme/widgets', description: 'Widget.', props: []};\n",
+    );
+
+    const result = await integrationPackCheck({cwd: tmpDir});
+
+    expect(result.data.issues).not.toContainEqual(
+      expect.objectContaining({code: 'component_export_missing'}),
+    );
+    expect(
+      result.data.packable,
+      JSON.stringify(result.data.issues, null, 2),
+    ).toBe(true);
+  });
+
   it('fails when packed template source is hidden by package exports', async () => {
     writePackage({
       manifest: "export default {templates: './templates'};\n",
@@ -1199,6 +1920,92 @@ describe('integrationPackCheck', () => {
     expect(sourceWarnings[0].message).toContain('Card.tsx');
   });
 
+  it('reports template sources without metadata as warnings', async () => {
+    writePackage({
+      manifest:
+        "export default {themes: './themes', templates: './templates'};\n",
+      files: ['astryx.integration.mjs', 'themes', 'templates'],
+      templates: true,
+    });
+    const result = await integrationPackCheck({cwd: tmpDir});
+
+    const sourceWarnings = result.data.issues.filter(
+      issue => issue.code === 'source_without_template_doc',
+    );
+    expect(sourceWarnings).toHaveLength(1);
+    expect(sourceWarnings[0].severity).toBe('warning');
+    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'],