@astryxdesign/cli 0.6.3 → 0.6.4-canary.06c8fa3

package/api/integration/validate-integration.mjs

@@ -33,8 +33,19 @@
 
 import * as fs from 'node:fs';
 import * as path from 'node:path';
-import jscodeshift from 'jscodeshift';
 import {assertWithin} from '../../foundation/fs/path-safety.mjs';
+import {
+  THEME_SLUG_RE,
+  unreadThemeFolders,
+} from '../../foundation/discovery/theme-discovery.mjs';
+import {
+  createFixContext,
+  DOC_CANDIDATE_RE,
+  pathIsInside,
+  stampOf,
+  TEMPLATE_CANDIDATE_RE,
+  unreachableFix,
+} from '../../foundation/integrations/contribution-fixes.mjs';
 import {
   findManifestPaths,
   loadManifest,
@@ -90,106 +101,35 @@ const UNREACHABLE_SKIP_DIRS = new Set([
   '.next',
   'out',
 ]);
-const DOC_CANDIDATE_RE = /\.doc\.(?:ts|mjs|js)$/u;
-const TEMPLATE_CANDIDATE_RE = /\.template\.(?:ts|mjs|js)$/u;
-const STATIC_DOC_TYPES = new Set(['component', 'generic', 'page', 'block']);
-const STATIC_TEMPLATE_TYPES = new Set(['page', 'block']);
-const j = jscodeshift.withParser('tsx');
-
-/** @param {any} node @returns {any} */
-function unwrapStaticExpression(node) {
-  let current = node;
-  while (
-    current &&
-    [
-      'TSSatisfiesExpression',
-      'TSAsExpression',
-      'TypeCastExpression',
-      'ParenthesizedExpression',
-    ].includes(current.type)
-  ) {
-    current = current.expression;
-  }
-  if (current?.type === 'CallExpression' && current.arguments.length > 0) {
-    current = unwrapStaticExpression(current.arguments[0]);
-  }
-  return current;
-}
-
-/** @param {any} property @param {string} name */
-function staticPropertyNamed(property, name) {
-  if (
-    !property ||
-    !['ObjectProperty', 'Property'].includes(property.type) ||
-    property.computed
-  ) {
-    return false;
-  }
-  return (
-    (property.key?.type === 'Identifier' && property.key.name === name) ||
-    (['Literal', 'StringLiteral'].includes(property.key?.type) &&
-      property.key.value === name)
-  );
-}
-
 /**
- * Identify contribution metadata without importing it. Doctor scans files that
- * the manifest does not declare, so executing those files would run code the
- * package never asked Astryx to load.
- *
- * @param {string} file
- * @param {boolean} templateOnly
+ * A warning for each folder under the themes root that holds modules but is
+ * not read as a theme. Either branch of its fix leaves nothing to warn about:
+ * the folder becomes a theme, or a dot-folder discovery skips.
+ * @param {string} packageDir
+ * @param {import('../../foundation/integrations/integrations.mjs').LoadedIntegration} loaded
+ * @returns {Issue[]}
  */
-function isStaticContributionMetadata(file, templateOnly) {
-  let ast;
-  try {
-    ast = j(fs.readFileSync(file, 'utf-8'));
-  } catch {
-    return false;
-  }
-  /** @type {any[]} */
-  const candidates = [];
-  ast
-    .find(j.ExportDefaultDeclaration)
-    .forEach((/** @type {any} */ exportPath) => {
-      candidates.push(exportPath.value.declaration);
-    });
-  ast
-    .find(j.ExportNamedDeclaration)
-    .forEach((/** @type {any} */ exportPath) => {
-      const declaration = exportPath.value.declaration;
-      if (declaration?.type !== 'VariableDeclaration') return;
-      for (const declarator of declaration.declarations) {
-        if (
-          declarator.id?.type === 'Identifier' &&
-          declarator.id.name === 'docs'
-        ) {
-          candidates.push(declarator.init);
-        }
-      }
-    });
-
-  const allowedTypes = templateOnly ? STATIC_TEMPLATE_TYPES : STATIC_DOC_TYPES;
-  for (const candidate of candidates) {
-    const object = unwrapStaticExpression(candidate);
-    if (object?.type !== 'ObjectExpression') continue;
-    const typeProperty = object.properties.find((/** @type {any} */ property) =>
-      staticPropertyNamed(property, 'type'),
-    );
-    const value = unwrapStaticExpression(typeProperty?.value);
-    if (
-      ['Literal', 'StringLiteral'].includes(value?.type) &&
-      allowedTypes.has(value.value)
-    ) {
-      return true;
+function unreadThemeFolderIssues(packageDir, loaded) {
+  const themes = /** @type {string} */ (loaded.themes);
+  return unreadThemeFolders(themes, {
+    packageDir,
+    packageName: loaded.name,
+  }).map(folder => {
+    const name = path.basename(folder);
+    const shown = `${path.relative(packageDir, folder).split(path.sep).join('/')}/`;
+    const hide = `rename it to .${name} so Astryx skips it`;
+    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}.`;
+    } else {
+      fix = `${hide}; a theme folder needs a lower-kebab name.`;
     }
-  }
-  return false;
-}
-
-/** @param {string} candidate @param {string} root */
-function pathIsInside(candidate, root) {
-  return candidate === root || candidate.startsWith(`${root}${path.sep}`);
+    return warning(
+      'unread_theme_folder',
+      `Folder "${shown}" holds modules but no <name>Theme source or .doc.mjs descriptor, so Astryx does not read it as a theme. Fix: ${fix}`,
+    );
+  });
 }
 
 /**
@@ -214,6 +154,7 @@ async function findUnreachableContributionIssues(packageDir, loaded) {
   );
   /** @type {Issue[]} */
   const issues = [];
+  const context = createFixContext(packageDir, loaded);
   let scanned = 0;
   let truncated = false;
 
@@ -237,13 +178,18 @@ async function findUnreachableContributionIssues(packageDir, loaded) {
         truncated = true;
         return;
       }
-      const isTemplate = TEMPLATE_CANDIDATE_RE.test(entry.name);
-      if (!isTemplate && !DOC_CANDIDATE_RE.test(entry.name)) continue;
-      if (!isStaticContributionMetadata(full, isTemplate)) continue;
+      if (
+        !TEMPLATE_CANDIDATE_RE.test(entry.name) &&
+        !DOC_CANDIDATE_RE.test(entry.name)
+      ) {
+        continue;
+      }
+      const stamp = stampOf(context, full);
+      if (stamp == null) continue;
       issues.push(
         warning(
           'unreachable_contribution',
-          `Found contribution metadata "${path.relative(packageDir, full)}" outside every declared integration root, so it contributes nothing. Move it under the matching root or update the manifest root.`,
+          `Found contribution metadata "${path.relative(packageDir, full)}" outside every declared integration root, so it contributes nothing. ${unreachableFix(context, full, stamp)}`,
         ),
       );
     }
@@ -366,6 +312,8 @@ 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)));
+  if (loaded.themes)
+    issues.push(...unreadThemeFolderIssues(packageDir, loaded));
   if (scanUnreachable) {
     issues.push(
       ...(await findUnreachableContributionIssues(packageDir, loaded)),
@@ -400,8 +348,10 @@ export async function validateLocalIntegration(cwd = process.cwd()) {
   try {
     pkg = JSON.parse(fs.readFileSync(pkgJsonPath, 'utf-8'));
   } catch (err) {
+    // A null name means "no manifest here"; this package has one.
     return {
       found: true,
+      name: '(local package)',
       manifestFile: manifests[0],
       issues: [
         error(

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

@@ -13,10 +13,16 @@ import {afterEach, beforeEach, describe, expect, it} from 'vitest';
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 import {
+  validateIntegration,
   validateLocalIntegration,
   validateInstalledIntegration,
   summarizeIssues,
 } from './validate-integration.mjs';
+import {
+  integrationComponentConflicts,
+  integrationDocConflicts,
+  integrationTemplateConflicts,
+} from './authoring-checks.mjs';
 
 let tmpDir;
 
@@ -154,7 +160,7 @@ describe('validate-integration API', () => {
     fs.mkdirSync(componentsDir);
     fs.writeFileSync(
       path.join(componentsDir, 'Widget.doc.mjs'),
-      `export default {name: 'Widget'};\n`,
+      `export default {name: 'Widget', props: []};\n`,
     );
     fs.writeFileSync(
       path.join(componentsDir, 'Widget.tsx'),
@@ -187,6 +193,39 @@ describe('validate-integration API', () => {
     expect(byCode(result.issues, 'invalid_codemod')).toHaveLength(1);
   });
 
+  it('names a broken codemod of an installed package by its path inside the package', async () => {
+    const consumer = path.join(tmpDir, 'consumer');
+    fs.mkdirSync(consumer, {recursive: true});
+    fs.writeFileSync(
+      path.join(consumer, 'package.json'),
+      JSON.stringify({name: 'consumer'}),
+    );
+    const pkgDir = path.join(consumer, 'node_modules', '@acme', 'kit');
+    writePackage(pkgDir, {
+      name: '@acme/kit',
+      manifest: `export default { codemods: './codemods' };\n`,
+    });
+    fs.mkdirSync(path.join(pkgDir, 'codemods', '1.1.0'), {recursive: true});
+    fs.writeFileSync(
+      path.join(pkgDir, 'codemods', '1.1.0', 'no-default.mjs'),
+      'export const nope = 1;\n',
+    );
+    fs.writeFileSync(
+      path.join(pkgDir, 'codemods', 'stray.mjs'),
+      `export default {type: 'code', title: 'Stray', transform: file => file.source};\n`,
+    );
+
+    const result = await validateInstalledIntegration('@acme/kit', consumer);
+
+    const [broken] = byCode(result.issues, 'invalid_codemod');
+    expect(broken.message).toContain('(codemods/1.1.0/no-default.mjs)');
+    const [stray] = byCode(result.issues, 'codemod_outside_version');
+    expect(stray.message).toContain('"codemods/stray.mjs"');
+    for (const issue of result.issues) {
+      expect(issue.message).not.toContain(tmpDir);
+    }
+  });
+
   it('flags a broken template as invalid_template error', async () => {
     const pkgDir = path.join(tmpDir, 'pkg');
     writePackage(pkgDir, {
@@ -204,33 +243,24 @@ describe('validate-integration API', () => {
     expect(byCode(result.issues, 'invalid_template')).toHaveLength(1);
   });
 
-  it('reports no errors for a valid source-theme catalog', async () => {
+  it('reports no errors for a valid source-theme descriptor', async () => {
     const pkgDir = path.join(tmpDir, 'pkg');
     writePackage(pkgDir, {
-      manifest: `export default { themes: './themes' };\n`,
+      manifest: `export default { themes: './themes' };
+`,
     });
     const themeDir = path.join(pkgDir, 'themes', 'ocean');
     fs.mkdirSync(themeDir, {recursive: true});
     fs.writeFileSync(
-      path.join(pkgDir, 'themes', 'manifest.json'),
-      JSON.stringify({
-        version: 1,
-        themes: [
-          {
-            slug: 'ocean',
-            displayName: 'Ocean',
-            description: 'Blue and calm.',
-            maintained: true,
-            entry: 'oceanTheme.ts',
-            exportName: 'oceanTheme',
-            files: ['oceanTheme.ts'],
-          },
-        ],
-      }),
+      path.join(themeDir, 'oceanTheme.doc.mjs'),
+      `/** @type {import('@astryxdesign/cli/authoring').ThemeDoc} */
+export default {type: 'theme', name: 'ocean', displayName: 'Ocean', description: 'Blue and calm.', maintained: true};
+`,
     );
     fs.writeFileSync(
       path.join(themeDir, 'oceanTheme.ts'),
-      `export const oceanTheme = {};\n`,
+      `export const oceanTheme = {};
+`,
     );
 
     const result = await validateLocalIntegration(pkgDir);
@@ -238,13 +268,17 @@ describe('validate-integration API', () => {
     expect(summarizeIssues(result.issues).errors).toBe(0);
   });
 
-  it('flags an unreadable source-theme catalog as invalid_theme', async () => {
+  it('flags an obsolete source-theme catalog as invalid_theme', async () => {
     const pkgDir = path.join(tmpDir, 'pkg');
     writePackage(pkgDir, {
-      manifest: `export default { themes: './themes' };\n`,
+      manifest: `export default { themes: './themes' };
+`,
     });
     fs.mkdirSync(path.join(pkgDir, 'themes'), {recursive: true});
-    fs.writeFileSync(path.join(pkgDir, 'themes', 'manifest.json'), '{not-json');
+    fs.writeFileSync(
+      path.join(pkgDir, 'themes', 'manifest.json'),
+      '{"version":1}',
+    );
 
     const result = await validateLocalIntegration(pkgDir);
     expect(byCode(result.issues, 'invalid_theme')).toHaveLength(1);
@@ -269,6 +303,11 @@ describe('validate-integration API', () => {
         message: expect.stringContaining('InvisibleWidget.doc.mjs'),
       }),
     ]);
+    expect(
+      byCode(result.issues, 'source_without_component_doc')[0].message,
+    ).toContain(
+      "Fix: add InvisibleWidget.doc.mjs beside it with type: 'component'",
+    );
   });
 
   it('reports codemods outside semver folders and invalid folder names', async () => {
@@ -284,8 +323,12 @@ describe('validate-integration API', () => {
 
     const result = await validateLocalIntegration(pkgDir);
 
-    expect(byCode(result.issues, 'codemod_outside_version')).toHaveLength(1);
-    expect(byCode(result.issues, 'invalid_codemod_version')).toHaveLength(1);
+    const [stray] = byCode(result.issues, 'codemod_outside_version');
+    expect(stray.message).toContain('"codemods/forgotten.mjs"');
+    expect(stray.message).toContain('codemods/1.2.0/forgotten.mjs');
+    expect(stray.message).not.toContain(tmpDir);
+    const [folder] = byCode(result.issues, 'invalid_codemod_version');
+    expect(folder.message).toContain('Fix: rename it');
   });
 
   it('warns about valid contribution metadata outside every declared root', async () => {
@@ -327,6 +370,31 @@ describe('validate-integration API', () => {
     const unreachable = byCode(result.issues, 'unreachable_contribution');
     expect(unreachable).toHaveLength(1);
     expect(unreachable[0].message).toContain('src/orphan.doc.mjs');
+    // No docs root is declared, but src/ also holds a .doc.mjs that is not a
+    // topic, which a docs root at src/ would read too; so the fix moves it.
+    expect(unreachable[0].message).toContain(
+      "Fix: move it into docs/ and set `docs: './docs'` in astryx.integration.mjs.",
+    );
+  });
+
+  it('names the root that reads misplaced metadata when one is declared', async () => {
+    const pkgDir = path.join(tmpDir, 'pkg');
+    writePackage(pkgDir, {
+      manifest: `export default { templates: './templates' };\n`,
+    });
+    fs.mkdirSync(path.join(pkgDir, 'templates'));
+    fs.mkdirSync(path.join(pkgDir, 'src', 'blocks'), {recursive: true});
+    fs.writeFileSync(
+      path.join(pkgDir, 'src', 'blocks', 'Carousel.doc.mjs'),
+      `export default {type: 'block', name: 'Carousel', displayName: 'Carousel', aspectRatio: 1};\n`,
+    );
+
+    const result = await validateLocalIntegration(pkgDir);
+
+    const [issue] = byCode(result.issues, 'unreachable_contribution');
+    expect(issue.message).toContain(
+      "Fix: move it under templates/ (the templates root), or set `templates: './src/blocks'` in astryx.integration.mjs.",
+    );
   });
 
   it('never executes unreachable metadata while diagnosing it', async () => {
@@ -417,7 +485,7 @@ describe('validate-integration API', () => {
     fs.mkdirSync(cDir, {recursive: true});
     fs.writeFileSync(
       path.join(cDir, 'Widget.doc.mjs'),
-      `export default { name: 'Widget' };\n`,
+      `export default { type: 'component', name: 'Widget', props: [] };\n`,
     );
     fs.writeFileSync(
       path.join(cDir, 'Widget.tsx'),
@@ -439,7 +507,7 @@ describe('validate-integration API', () => {
     // Doc with no sibling Widget.tsx.
     fs.writeFileSync(
       path.join(cDir, 'Widget.doc.mjs'),
-      `export default { name: 'Widget' };\n`,
+      `export default { type: 'component', name: 'Widget', props: [] };\n`,
     );
 
     const result = await validateLocalIntegration(pkgDir);
@@ -472,3 +540,88 @@ describe('validate-integration API', () => {
     expect(byCode(result.issues, 'invalid_package_spec')).toHaveLength(1);
   });
 });
+
+describe('integration diagnostics are read-only', () => {
+  /** Every directory and file under `dir`, with file bytes. */
+  function snapshot(dir) {
+    /** @type {Record<string, string>} */
+    const entries = {};
+    /** @param {string} current */
+    const walk = current => {
+      for (const entry of fs.readdirSync(current, {withFileTypes: true})) {
+        const full = path.join(current, entry.name);
+        const key = path.relative(dir, full);
+        if (entry.isDirectory()) {
+          entries[`${key}/`] = '';
+          walk(full);
+        } else {
+          entries[key] = fs.readFileSync(full, 'base64');
+        }
+      }
+    };
+    walk(dir);
+    return entries;
+  }
+
+  /** A package with valid, broken, conflicting, and unreachable contributions. */
+  function writeDiagnosedPackage(dir) {
+    writePackage(dir, {
+      manifest:
+        "export default {\n  components: './components',\n  templates: './templates',\n  docs: './docs',\n  codemods: './gone',\n  themes: './themes',\n};\n",
+    });
+    const write = (relative, contents) => {
+      fs.mkdirSync(path.dirname(path.join(dir, relative)), {recursive: true});
+      fs.writeFileSync(path.join(dir, relative), contents);
+    };
+    write(
+      'components/Card.doc.mjs',
+      "export default {type: 'component', name: 'Card', props: []};\n",
+    );
+    write('components/Card.tsx', 'export function Card() { return null; }\n');
+    write(
+      'components/Orphan.doc.mjs',
+      "export default {type: 'component', name: 'Orphan', props: []};\n",
+    );
+    write('templates/dash.doc.mjs', "export default {type: 'page', name: 'Dash'};\n");
+    write(
+      'docs/theme.doc.mjs',
+      "export default {type: 'generic', name: 'theme', title: 'Theme', description: 'x', sections: [{title: 'A', content: [{type: 'prose', text: 'x'}]}]};\n",
+    );
+    write('themes/manifest.json', '{"version": 1, "themes": [{"slug": 7}]}\n');
+    write(
+      'stray/Stray.doc.mjs',
+      "export default {type: 'component', name: 'Stray', props: []};\n",
+    );
+  }
+
+  it('leaves local and installed packages byte-for-byte unchanged', async () => {
+    const pkgDir = path.join(tmpDir, 'pkg');
+    writeDiagnosedPackage(pkgDir);
+    const consumer = path.join(tmpDir, 'consumer');
+    fs.mkdirSync(consumer, {recursive: true});
+    fs.writeFileSync(
+      path.join(consumer, 'package.json'),
+      JSON.stringify({name: 'consumer'}),
+    );
+    writeDiagnosedPackage(path.join(consumer, 'node_modules', '@acme', 'widgets'));
+    const before = {pkg: snapshot(pkgDir), consumer: snapshot(consumer)};
+
+    const local = await validateIntegration(undefined, {cwd: pkgDir});
+    const installed = await validateIntegration('@acme/widgets', {
+      cwd: consumer,
+    });
+    for (const [pkg, cwd] of [
+      [undefined, pkgDir],
+      ['@acme/widgets', consumer],
+    ]) {
+      await integrationTemplateConflicts(pkg, {cwd});
+      await integrationComponentConflicts(pkg, {cwd});
+      await integrationDocConflicts(pkg, {cwd});
+    }
+
+    expect(summarizeIssues(local.data.issues).errors).toBeGreaterThan(0);
+    expect(byCode(local.data.issues, 'unreachable_contribution')).toHaveLength(1);
+    expect(summarizeIssues(installed.data.issues).errors).toBeGreaterThan(0);
+    expect({pkg: snapshot(pkgDir), consumer: snapshot(consumer)}).toEqual(before);
+  });
+});

package/api/integration/validate-unread-theme-folders.test.mjs

@@ -0,0 +1,110 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file `doctor integration validate` warns about a folder under the themes
+ * root that holds modules but is not read as a theme, and both branches of
+ * its fix leave nothing to warn about.
+ *
+ * @input a local integration package with a themes root
+ * @output the unread_theme_folder warnings validation reports
+ * @position packages/cli/api/integration — validation regression tests
+ */
+
+import {afterEach, beforeEach, describe, expect, it} from 'vitest';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import {validateLocalIntegration} from './validate-integration.mjs';
+import {integrationAddTheme} from './add-theme.mjs';
+
+let tmpDir;
+
+beforeEach(() => {
+  tmpDir = fs.mkdtempSync(path.join(process.cwd(), '.astryx-unread-theme-'));
+  fs.writeFileSync(
+    path.join(tmpDir, 'package.json'),
+    JSON.stringify({name: '@acme/kit', version: '1.0.0'}),
+  );
+  fs.writeFileSync(
+    path.join(tmpDir, 'astryx.integration.mjs'),
+    "export default {themes: './themes'};\n",
+  );
+});
+
+afterEach(() => {
+  fs.rmSync(tmpDir, {recursive: true, force: true});
+});
+
+/** @param {Record<string, string>} files paths under themes/ */
+function writeThemes(files) {
+  for (const [file, contents] of Object.entries(files)) {
+    const target = path.join(tmpDir, 'themes', file);
+    fs.mkdirSync(path.dirname(target), {recursive: true});
+    fs.writeFileSync(target, contents);
+  }
+}
+
+const OCEAN = {
+  'ocean/oceanTheme.doc.mjs':
+    "/** @type {import('@astryxdesign/cli/authoring').ThemeDoc} */\nexport default {type: 'theme', name: 'ocean', displayName: 'Ocean', description: 'Blue.', maintained: true};\n",
+  'ocean/oceanTheme.ts':
+    "import {blue} from '@acme/kit/themes/shared/palette';\nexport const oceanTheme = {blue};\n",
+  'shared/palette.ts': 'export const blue = 1;\n',
+};
+
+async function unread() {
+  const {issues} = await validateLocalIntegration(tmpDir);
+  return issues.filter(issue => issue.code === 'unread_theme_folder');
+}
+
+describe('unread theme folders', () => {
+  it('warns about each folder that looks like a theme but is not read as one', async () => {
+    writeThemes({
+      ...OCEAN,
+      'sand/sand.ts': 'export const sand = {};\n',
+      'sand/sand.doc.ts': "export default {type: 'theme', name: 'sand'};\n",
+      'reef/index.ts': 'export const reefTheme = {};\n',
+      'Tide_Pool/index.ts': 'export const tide = {};\n',
+      'fonts/inter.woff2': 'x',
+      'utils/format.ts': 'export const format = String;\n',
+      '.cache/index.ts': 'export {};\n',
+    });
+    const issues = await unread();
+    expect(issues.map(issue => issue.severity)).toEqual([
+      'warning',
+      'warning',
+      'warning',
+    ]);
+    expect(issues.map(issue => issue.message)).toEqual([
+      'Folder "themes/Tide_Pool/" holds modules but no <name>Theme source or .doc.mjs descriptor, so Astryx does not read it as a theme. Fix: rename it to .Tide_Pool so Astryx skips it; a theme folder needs a lower-kebab name.',
+      'Folder "themes/reef/" holds modules but no <name>Theme source or .doc.mjs descriptor, so Astryx does not read it as a theme. Fix: if it is a theme, add reefTheme.ts and reefTheme.doc.mjs to it (`astryx integration add theme reef` writes both) and move its code into reefTheme.ts; if not, rename it to .reef so Astryx skips it.',
+      'Folder "themes/sand/" holds modules but no <name>Theme source or .doc.mjs descriptor, so Astryx does not read it as a theme. Fix: if it is a theme, add sandTheme.ts and sandTheme.doc.mjs to it (`astryx integration add theme sand` writes both) and move its code into sandTheme.ts; if not, rename it to .sand so Astryx skips it.',
+    ]);
+  });
+
+  it('does not warn about a helper folder a module imports by a relative path', async () => {
+    writeThemes({
+      ...OCEAN,
+      'index.ts':
+        "export * from './ocean/oceanTheme';\nexport * from './util';\n",
+      'util/index.ts': 'export const util = 1;\n',
+    });
+    expect(await unread()).toEqual([]);
+  });
+
+  it('holds when either branch of the fix is followed', async () => {
+    writeThemes({
+      ...OCEAN,
+      'sand/sand.ts': 'export const sand = {};\n',
+      'reef/index.ts': 'export const reefTheme = {};\n',
+      'Tide_Pool/index.ts': 'export const tide = {};\n',
+    });
+    await integrationAddTheme('sand', {cwd: tmpDir});
+    await integrationAddTheme('reef', {cwd: tmpDir});
+    fs.renameSync(
+      path.join(tmpDir, 'themes', 'Tide_Pool'),
+      path.join(tmpDir, 'themes', '.Tide_Pool'),
+    );
+    const {issues} = await validateLocalIntegration(tmpDir);
+    expect(issues).toEqual([]);
+  });
+});

package/api/integration/validateIntegration.doc.mjs

@@ -12,6 +12,7 @@ export const doc = {
   type: 'function',
   kind: 'api',
   name: 'validateIntegration',
+  namespace: 'cli/api',
   displayName: 'validateIntegration()',
   summary:
     'Validate a single Astryx integration package and report its issues.',
@@ -45,7 +46,7 @@ export const doc = {
     {
       type: 'integration.validate',
       description:
-        'The result envelope: `data.name` and `data.version` of the validated package (both null when no local manifest is found), plus `data.issues`, an AstryxIntegrationIssue[] of {code, severity: `warning` | `error`, message}.',
+        'The result envelope: `data.name` and `data.version` of the validated package (both null only when no local manifest is found; `data.name` is `(local package)` when the local package.json has no readable name), plus `data.issues`, an AstryxIntegrationIssue[] of {code, severity: `warning` | `error`, message}.',
     },
   ],
   examples: [
@@ -59,5 +60,5 @@ export const doc = {
     },
   ],
   command: 'doctor integration validate',
-  related: ['summarizeIssues', 'doctor integration templates', 'upgrade'],
+  related: ['summarizeIssues', 'integrationTemplateConflicts', 'upgrade'],
 };

package/api/json/assertResponse.doc.mjs

@@ -11,6 +11,7 @@ export const doc = {
   type: 'function',
   kind: 'api',
   name: 'assertResponse',
+  namespace: 'cli/api',
   displayName: 'assertResponse()',
   summary:
     'Parse and assert one expected response type, throwing on an error or a mismatch.',