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

package/api/integration/authoring-checks.mjs

@@ -51,6 +51,8 @@ import {
   validateInstalledIntegration,
   validateLocalIntegration,
 } from './validate-integration.mjs';
+import {rootProblem} from '../../foundation/integrations/validate-contributions.mjs';
+import {normalizeProviderId} from '../../foundation/identity/provider-identity.mjs';
 
 /** @param {string} value */
 export function shellArg(value) {
@@ -58,15 +60,61 @@ export function shellArg(value) {
   return `'${value.replace(/'/g, `'\\''`)}'`;
 }
 
+/**
+ * The provider ID a package without a name is checked under: a valid bare
+ * package name no published package can hold (npm names are lowercase).
+ */
+const UNNAMED_PROVIDER = 'astryx-unnamed-local-package';
+
+/**
+ * A message as the package sees it: the stand-in provider ID gone, its docs
+ * named by their path in the package.
+ * @param {string} message
+ */
+function unnamedShown(message) {
+  return message
+    .split(`${UNNAMED_PROVIDER}/`)
+    .join('')
+    .split(UNNAMED_PROVIDER)
+    .join('this package');
+}
+
 /**
  * Resolve one local or installed integration for an authoring check.
  * @param {string | undefined} pkg
  * @param {string} cwd
  */
 async function resolveIntegration(pkg, cwd) {
-  return pkg
-    ? validateInstalledIntegration(pkg, cwd)
-    : validateLocalIntegration(cwd);
+  const resolved = pkg
+    ? await validateInstalledIntegration(pkg, cwd)
+    : await validateLocalIntegration(cwd);
+  const integration = resolved.found ? resolved.integration : undefined;
+  if (!integration) return resolved;
+  // A root that is not a readable folder is reported in the issues; the
+  // checks read nothing from it rather than fail on it.
+  /** @type {typeof integration & {__unnamed?: boolean}} */
+  const usable = {...integration};
+  // The provider ID readers key the package on: the manifest's providerId,
+  // else its name. A package with neither (validate warned about it) is
+  // still checked; the docs check names its docs under a stand-in ID.
+  try {
+    usable.providerId = normalizeProviderId(
+      integration.__declaredProviderId ?? integration.name,
+    );
+  } catch {
+    usable.__unnamed = true;
+  }
+  for (const kind of /** @type {const} */ ([
+    'components',
+    'templates',
+    'codemods',
+    'docs',
+    'themes',
+  ])) {
+    const root = usable[kind];
+    if (root != null && rootProblem(root)) usable[kind] = undefined;
+  }
+  return {...resolved, integration: usable};
 }
 
 /**
@@ -387,8 +435,20 @@ export async function integrationDocConflicts(pkg, options = {}) {
     };
   }
 
+  // The docs tree names a package's docs by its provider ID, which a
+  // package.json without a name does not give: its docs are checked under a
+  // stand-in ID, which no message names.
+  const unnamed = /** @type {{__unnamed?: boolean}} */ (resolved.integration)
+    .__unnamed;
+  const docsIntegration = unnamed
+    ? {
+        ...resolved.integration,
+        name: UNNAMED_PROVIDER,
+        providerId: UNNAMED_PROVIDER,
+      }
+    : resolved.integration;
   const [discovered, builtinTopics] = await Promise.all([
-    discoverIntegrationDocs(resolved.integration),
+    discoverIntegrationDocs(docsIntegration),
     Promise.resolve(discoverBuiltinTopics()),
   ]);
   const {records, errors} = discovered;
@@ -458,27 +518,40 @@ export async function integrationDocConflicts(pkg, options = {}) {
   // its docs (spec:AST-046, spec:AST-047).
   if (errors.length === 0) {
     for (const {severity, message} of await packageDocsProblems(
-      /** @type {{name: string}} */ (resolved.integration),
+      /** @type {{name: string}} */ (docsIntegration),
       discovered,
     )) {
-      issues.push({code: 'invalid_doc_graph', severity, message});
+      issues.push({
+        code: 'invalid_doc_graph',
+        severity,
+        message: unnamedShown(message),
+      });
     }
 
     // A reference block includes content rather than linking to it, so one
     // that cannot include what it names loses that content for every reader:
     // an error, where a link that names no doc still prints as written.
     for (const message of await packageReferenceProblems(
-      /** @type {{name: string}} */ (resolved.integration),
+      /** @type {{name: string}} */ (docsIntegration),
       discovered,
     )) {
-      issues.push({code: 'invalid_doc_reference', severity: 'error', message});
+      issues.push({
+        code: 'invalid_doc_reference',
+        severity: 'error',
+        message: unnamedShown(message),
+      });
     }
 
     // One fact has one owner: a passage two topics repeat goes stale in one
     // of them. Each is listed and is a warning (architecture:cli-surface
     // DEC-8), so `integration check --strict` fails until it is fixed;
     // `doctor integration docs` keeps its exit code, as it fails on errors.
-    copiedPassages.push(...(await integrationCopiedPassages(discovered)));
+    copiedPassages.push(
+      ...(await integrationCopiedPassages(discovered)).map(passage => ({
+        ...passage,
+        message: unnamedShown(passage.message),
+      })),
+    );
     for (const {message} of copiedPassages) {
       issues.push({code: 'copied_passage', severity: 'warning', message});
     }
@@ -488,6 +561,7 @@ export async function integrationDocConflicts(pkg, options = {}) {
       ...(await integrationFluff(discovered)).map(each => ({
         ...each,
         file: fromPackage(each.file),
+        message: unnamedShown(each.message),
       })),
     );
     for (const {message} of fluff) {

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'],