@astryxdesign/cli 0.7.2-canary.fdd384f → 0.7.2

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,345 @@ 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('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 +686,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 +857,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 +890,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 +963,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();
@@ -1558,6 +1902,23 @@ 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('cleans up its scratch consumer when npm pack fails', async () => {
     writePackage({
       files: ['astryx.integration.mjs', 'themes'],

package/api/integration/validate-integration-fixes.test.mjs

@@ -37,6 +37,8 @@ const componentDoc = name =>
   `export default {type: 'component', name: '${name}', displayName: '${name}', usage: {description: '${name}.'}, props: []};\n`;
 /** @param {string} name */
 const componentSource = name => `export function ${name}() { return null; }\n`;
+const templateSource = name =>
+  `export default function ${name}() { return null; }\n`;
 /** @param {string} name */
 const topic = name =>
   `export default ${JSON.stringify({
@@ -1131,6 +1133,71 @@ describe('source_without_component_doc fixes hold when followed', () => {
   });
 });
 
+describe('source_without_template_doc fixes hold when followed', () => {
+  it('adds the named doc, which resolves the warning', async () => {
+    const dir = writePackage({
+      [MANIFEST]: manifest({templates: './templates'}),
+      'templates/hero.tsx': templateSource('Hero'),
+      'templates/hero.test.tsx': templateSource('HeroTest'),
+    });
+
+    const message = only(await issuesOf(dir), 'source_without_template_doc');
+    expect(message).toBe(
+      "Template source \"hero.tsx\" has no same-stem metadata file hero.doc.mjs, so `astryx template` never lists it. Fix: add hero.doc.mjs beside it with type: 'page' or 'block'; `astryx docs authoring integration-template-doc` lists its fields. If it is not a template, move it out of the templates root.",
+    );
+
+    const fixed = follow(dir, {
+      write: {
+        'templates/hero.doc.mjs': `export default {type: 'page', name: 'hero', displayName: 'Hero'};\n`,
+      },
+    });
+    expect(await issuesOf(fixed)).toEqual([]);
+  });
+
+  it('checks a dotted template id, but no test, spec or story file', async () => {
+    const dir = writePackage({
+      [MANIFEST]: manifest({templates: './templates'}),
+      'templates/landing.page.tsx': templateSource('LandingPage'),
+      'templates/hero.test.tsx': templateSource('HeroTest'),
+      'templates/hero.spec.tsx': templateSource('HeroSpec'),
+      'templates/hero.stories.tsx': templateSource('HeroStories'),
+    });
+
+    const message = only(await issuesOf(dir), 'source_without_template_doc');
+    expect(message).toContain(
+      'Template source "landing.page.tsx" has no same-stem metadata file landing.page.doc.mjs',
+    );
+
+    const fixed = follow(dir, {
+      write: {
+        'templates/landing.page.doc.mjs': `export default {type: 'page', name: 'landing.page', displayName: 'Landing'};\n`,
+      },
+    });
+    expect(await issuesOf(fixed)).toEqual([]);
+  });
+
+  it('never flags a helper in a subfolder of the templates root', async () => {
+    const dir = writePackage({
+      [MANIFEST]: manifest({templates: './templates'}),
+      'templates/hero.doc.mjs': `export default {type: 'page', name: 'hero', displayName: 'Hero'};\n`,
+      'templates/hero.tsx': templateSource('Hero'),
+      'templates/hero/HeroCard.tsx': templateSource('HeroCard'),
+    });
+
+    expect(await issuesOf(dir)).toEqual([]);
+  });
+
+  it('accepts a released .template.mjs spec as the metadata', async () => {
+    const dir = writePackage({
+      [MANIFEST]: manifest({templates: './templates'}),
+      'templates/hero.tsx': templateSource('Hero'),
+      'templates/hero.template.mjs': `export default {type: 'page', name: 'hero', displayName: 'Hero'};\n`,
+    });
+
+    expect(await issuesOf(dir)).toEqual([]);
+  });
+});
+
 describe('codemod fixes hold when followed', () => {
   it('moves a stray codemod into a version folder, and renames a mis-named one', async () => {
     const dir = writePackage({

package/api/integration/validate-integration.d.mts

@@ -67,6 +67,14 @@ export type ValidateResult = {
      */
     reason?: "no_package_json" | undefined;
     issues: Issue[];
+    /**
+     * Information that
+     * fails nothing, such as `invalid_cli_command` (a malformed `cliCommand`).
+     */
+    notes?: {
+        code: string;
+        message: string;
+    }[] | undefined;
     integration?: import("../../foundation/integrations/integrations.mjs").LoadedIntegration | undefined;
 };
 import { validateLoadedIntegration } from '../../foundation/integrations/validate-contributions.mjs';

package/api/integration/validate-integration.mjs

@@ -35,6 +35,7 @@ import * as fs from 'node:fs';
 import * as path from 'node:path';
 import {assertWithin} from '../../foundation/fs/path-safety.mjs';
 import {integrationDocTypes} from '../docs/_adapter.mjs';
+import {integrationDocConsistency} from '../../foundation/discovery/doc-consistency.mjs';
 import {
   THEME_SLUG_RE,
   unreadThemeFolders,
@@ -55,11 +56,13 @@ import {
 // The on-disk contribution validators live in foundation: Project and
 // integration-warnings need them too, and foundation must not depend on api.
 import {
+  INVALID_CLI_COMMAND,
   validateLoadedIntegration,
   issueError as error,
   issueWarning as warning,
   rootProblem,
 } from '../../foundation/integrations/validate-contributions.mjs';
+import {formatCliCommand} from '../../foundation/env/package-manager.mjs';
 
 export {validateLoadedIntegration};
 
@@ -75,6 +78,8 @@ export {validateLoadedIntegration};
  * @property {string} [manifestFile] Absolute path to the loaded manifest.
  * @property {'no_package_json'} [reason] Why nothing was validated (internal).
  * @property {Issue[]} issues
+ * @property {Array<{code: string, message: string}>} [notes] Information that
+ *   fails nothing, such as `invalid_cli_command` (a malformed `cliCommand`).
  * @property {import('../../foundation/integrations/integrations.mjs').LoadedIntegration} [integration]
  */
 
@@ -124,7 +129,7 @@ function unreadThemeFolderIssues(packageDir, loaded) {
     let fix;
     if (THEME_SLUG_RE.test(name)) {
       const stem = `${name.replace(/-([a-z0-9])/gu, (_, character) => character.toUpperCase())}Theme`;
-      fix = `if it is a theme, add ${stem}.ts and ${stem}.doc.mjs to it (\`astryx integration add theme ${name}\` writes both) and move its code into ${stem}.ts; if not, ${hide}.`;
+      fix = `if it is a theme, add ${stem}.ts and ${stem}.doc.mjs to it (\`${formatCliCommand(`integration add theme ${name}`, packageDir)}\` writes both) and move its code into ${stem}.ts; if not, ${hide}.`;
     } else {
       fix = `${hide}; a theme folder needs a lower-kebab name.`;
     }
@@ -283,11 +288,14 @@ async function validateAtPackageDir(
   let unknownKeys;
   /** @type {string | undefined} */
   let agentDocsError;
+  /** @type {string | undefined} */
+  let cliCommandError;
   try {
-    ({manifest, unknownKeys, agentDocsError} = await loadManifest(
-      manifestFile,
-      `Integration manifest (${path.basename(manifestFile)})`,
-    ));
+    ({manifest, unknownKeys, agentDocsError, cliCommandError} =
+      await loadManifest(
+        manifestFile,
+        `Integration manifest (${path.basename(manifestFile)})`,
+      ));
   } catch (err) {
     issues.push(error('invalid_manifest', /** @type {any} */ (err).message));
     return result;
@@ -319,6 +327,8 @@ async function validateAtPackageDir(
     themes: resolveRoot(manifest.themes),
     issuesUrl: manifest.issuesUrl,
     agentDocs: manifest.agentDocs,
+    cliCommand: manifest.cliCommand,
+    __cliCommandError: cliCommandError,
     __agentDocsError: agentDocsError,
     __unknownKeys: unknownKeys,
     __spec: identity.name,
@@ -329,9 +339,35 @@ async function validateAtPackageDir(
 
   // Roots + contribution checks are shared with validateLoadedIntegration so
   // the everyday-command nudge runs the exact same validators.
-  issues.push(...(await validateLoadedIntegration(loaded)));
+  // A malformed `cliCommand` is an info note beside the issues, not an issue:
+  // `integration check --strict` fails on any warning, and a new failure code
+  // joins only in a minor release (architecture:cli-surface INV35). Doctor's
+  // project check still warns about it.
+  for (const issue of await validateLoadedIntegration(loaded)) {
+    if (issue.code === INVALID_CLI_COMMAND) {
+      (result.notes ??= []).push({code: issue.code, message: issue.message});
+    } else {
+      issues.push(issue);
+    }
+  }
   if (loaded.themes && !rootProblem(loaded.themes))
     issues.push(...unreadThemeFolderIssues(packageDir, loaded));
+  // What the docs say that no reader serves: a prop listed twice, an
+  // overlay's text for a prop the doc lacks, an empty or unreachable section,
+  // and an overlay of no topic.
+  issues.push(
+    ...(await integrationDocConsistency(
+      {
+        components:
+          loaded.components && !rootProblem(loaded.components)
+            ? loaded.components
+            : undefined,
+        docs:
+          loaded.docs && !rootProblem(loaded.docs) ? loaded.docs : undefined,
+      },
+      packageDir,
+    )),
+  );
   if (scanUnreachable) {
     issues.push(
       ...(await findUnreachableContributionIssues(packageDir, loaded)),
@@ -468,6 +504,7 @@ export async function validateIntegration(pkg, options = {}) {
   const docTypes = integration
     ? await integrationDocTypes(integration, cwd)
     : undefined;
+  const notes = result.found ? (result.notes ?? []) : [];
   return {
     type: 'integration.validate',
     data: {
@@ -476,9 +513,18 @@ export async function validateIntegration(pkg, options = {}) {
       validated: result.found,
       name: result.found ? (result.name ?? null) : null,
       version: result.found ? (result.version ?? null) : null,
-      issues: result.reason === 'no_package_json'
-        ? [{code: 'no_package', severity: 'error', message: 'No package.json found. Run this command inside a package directory.'}]
-        : result.issues,
+      issues:
+        result.reason === 'no_package_json'
+          ? [
+              {
+                code: 'no_package',
+                severity: 'error',
+                message:
+                  'No package.json found. Run this command inside a package directory.',
+              },
+            ]
+          : result.issues,
+      ...(notes.length > 0 ? {notes} : {}),
       ...(docTypes ? {docTypes} : {}),
     },
   };