@astryxdesign/cli 0.6.3-canary.db4e378 → 0.6.3-canary.ddb63c3

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)),

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

@@ -193,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, {
@@ -210,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);
@@ -244,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);
@@ -275,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 () => {
@@ -290,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 () => {
@@ -333,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 () => {

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

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

package/api/json/isError.doc.mjs

@@ -11,6 +11,7 @@ export const doc = {
   type: 'function',
   kind: 'api',
   name: 'isError',
+  namespace: 'cli/api',
   displayName: 'isError()',
   summary: 'Did the CLI return an error envelope?',
   description:

package/api/json/parseResponse.doc.mjs

@@ -11,6 +11,7 @@ export const doc = {
   type: 'function',
   kind: 'api',
   name: 'parseResponse',
+  namespace: 'cli/api',
   displayName: 'parseResponse()',
   summary: 'Parse `astryx --json` stdout into the structural response envelope.',
   description:

package/api/layout/layoutCheck.doc.mjs

@@ -12,6 +12,7 @@ export const doc = {
   type: 'function',
   kind: 'api',
   name: 'layoutCheck',
+  namespace: 'cli/api',
   displayName: 'layoutCheck()',
   summary: 'Validate a layout expression without expanding it.',
   description:

package/api/layout/layoutExpand.doc.mjs

@@ -12,6 +12,7 @@ export const doc = {
   type: 'function',
   kind: 'api',
   name: 'layoutExpand',
+  namespace: 'cli/api',
   displayName: 'layoutExpand()',
   summary: 'Expand a validated layout expression into XDS TSX.',
   description:

package/api/layout/layoutGrammar.doc.mjs

@@ -12,6 +12,7 @@ export const doc = {
   type: 'function',
   kind: 'api',
   name: 'layoutGrammar',
+  namespace: 'cli/api',
   displayName: 'layoutGrammar()',
   summary: 'Return the XLE/XLO grammar cheatsheet for this install.',
   description:

package/api/search/search.doc.mjs

@@ -11,6 +11,7 @@ export const doc = {
   type: 'function',
   kind: 'api',
   name: 'search',
+  namespace: 'cli/api',
   displayName: 'search()',
   summary:
     'Unified ranked search across components, hooks, docs, and templates.',

package/api/search/search.mjs

@@ -50,7 +50,7 @@
  * queries they have nothing to do with.
  */
 
-import {pathToFileURL} from 'node:url';
+import {readDocView} from '../../foundation/doc-compiler/read.mjs';
 import {findCoreDir} from '../../foundation/fs/paths.mjs';
 import {
   discoverComponents,
@@ -528,16 +528,26 @@ export function scoreCandidate(
 }
 
 /**
- * Load a doc module's `docs`/`doc` export, swallowing errors.
+ * A component or hook doc, compiled, or null when it cannot be read.
  * @param {string} docPath
  * @param {string} [exportName]
+ * @param {'components' | 'hooks'} [root]
  * @returns {Promise<any>}
  */
-async function loadModuleDoc(docPath, exportName = 'docs') {
+async function loadModuleDoc(
+  docPath,
+  exportName = 'docs',
+  root = 'components',
+) {
   try {
-    const mod = await import(pathToFileURL(docPath).href);
     // Support both the stamped default export and the legacy named export.
-    return mod?.default ?? mod[exportName] ?? null;
+    return (
+      (await readDocView(docPath, {
+        root,
+        loader: 'native',
+        exports: ['default', exportName],
+      })) ?? null
+    );
   } catch {
     return null;
   }
@@ -701,7 +711,7 @@ async function gatherHooks(coreDir) {
     let description = '';
     let importPath = '@astryxdesign/core/hooks';
     if (docPath) {
-      const doc = await loadModuleDoc(docPath);
+      const doc = await loadModuleDoc(docPath, 'docs', 'hooks');
       if (doc) {
         keywords = Array.isArray(doc.keywords) ? doc.keywords : [];
         description = doc.usage?.description || doc.description || '';

package/api/swizzle/swizzle.doc.mjs

@@ -11,6 +11,7 @@ export const doc = {
   type: 'function',
   kind: 'api',
   name: 'swizzle',
+  namespace: 'cli/api',
   displayName: 'swizzle()',
   summary: "Eject a component's source into your project for customization.",
   description: