@astryxdesign/cli 0.6.3-canary.98a2e4e → 0.6.3-canary.9c4d44d

package/assets/codemods/transforms/next/migrate-theme-catalog-to-descriptors.mjs

@@ -0,0 +1,141 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Give each integration theme a typed descriptor instead of the
+ *   `manifest.json` theme catalog.
+ *
+ * Astryx 0.6 scaffolded integration themes into one catalog,
+ * `<themes root>/manifest.json`. Each theme now carries a strongly typed
+ * same-stem `.doc.mjs` descriptor, and a themes root that still holds the
+ * catalog is refused. This project codemod reads the package's integration
+ * manifest, plans one descriptor per catalog entry beside that theme's source,
+ * and removes the catalog. When any entry cannot convert, it plans nothing and
+ * names the entry, so the package is never left half converted.
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import {loadManifestObject} from '../../../../foundation/integrations/integrations.mjs';
+import {findLocalIntegrationManifestOrNull} from '../../../../foundation/integrations/manifest-writer.mjs';
+import {themeDescriptorSource} from '../../../../foundation/integrations/theme-descriptor.mjs';
+
+export const meta = {
+  title:
+    'Give each integration theme a typed descriptor instead of the manifest.json catalog',
+  description:
+    'Writes <name>Theme.doc.mjs beside each theme the catalog lists, then removes the catalog.',
+  codemodType: 'project',
+};
+
+const SLUG = /^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/u;
+const SOURCE = /\.(?:ts|tsx|mjs|js)$/u;
+
+/**
+ * @param {string} root the package directory
+ * @returns {Promise<import('../../runner.mjs').ProjectCodemodPlan>}
+ */
+export default async function migrateThemeCatalogToDescriptors(root) {
+  /** @type {import('../../runner.mjs').ProjectCodemodPlan} */
+  const plan = {writes: [], deletes: [], problems: []};
+  /** @param {string} file @returns {string} */
+  const rel = file => path.relative(root, file).split(path.sep).join('/');
+  /** @param {string} file @param {string} message */
+  const problem = (file, message) => plan.problems.push({file, message});
+
+  const manifestFile = findLocalIntegrationManifestOrNull(root);
+  if (!manifestFile) return plan;
+  const manifest = await loadManifestObject(
+    manifestFile,
+    `Integration manifest ${path.basename(manifestFile)}`,
+    {fresh: true},
+  );
+  if (typeof manifest.themes !== 'string') return plan;
+  const themesRoot = path.resolve(root, manifest.themes);
+  const fromRoot = path.relative(root, themesRoot);
+  if (fromRoot.startsWith('..') || path.isAbsolute(fromRoot)) return plan;
+  const catalogFile = path.join(themesRoot, 'manifest.json');
+  if (!fs.existsSync(catalogFile)) return plan;
+  const catalogPath = rel(catalogFile);
+
+  let catalog;
+  try {
+    catalog = JSON.parse(fs.readFileSync(catalogFile, 'utf-8'));
+  } catch (error) {
+    const reason = error instanceof Error ? error.message : String(error);
+    problem(catalogPath, `is not valid JSON (${reason}).`);
+    return plan;
+  }
+  if (
+    !catalog ||
+    typeof catalog !== 'object' ||
+    catalog.version !== 1 ||
+    !Array.isArray(catalog.themes)
+  ) {
+    problem(catalogPath, 'is not a version 1 theme catalog.');
+    return plan;
+  }
+
+  for (const [index, entry] of catalog.themes.entries()) {
+    const slug = entry?.slug;
+    if (typeof slug !== 'string' || !SLUG.test(slug)) {
+      problem(
+        catalogPath,
+        `themes[${index}] has no lowercase kebab-case slug; fix the entry or add that theme's descriptor by hand.`,
+      );
+      continue;
+    }
+    const themeDir = path.join(themesRoot, slug);
+    const source = entry.entry;
+    if (
+      typeof source !== 'string' ||
+      !SOURCE.test(source) ||
+      source !== path.basename(source)
+    ) {
+      problem(
+        catalogPath,
+        `theme "${slug}" has entry ${JSON.stringify(source)}; a descriptor sits beside a .ts, .tsx, .mjs, or .js source directly in ${rel(themeDir)}/.`,
+      );
+      continue;
+    }
+    const stem = source.replace(SOURCE, '');
+    if (entry.exportName !== stem) {
+      problem(
+        catalogPath,
+        `theme "${slug}" exports ${JSON.stringify(entry.exportName)} from ${source}; a descriptor takes the export name from the file name, so rename the export or the file to match.`,
+      );
+      continue;
+    }
+    if (typeof entry.displayName !== 'string' || !entry.displayName.trim()) {
+      problem(catalogPath, `theme "${slug}" has no displayName.`);
+      continue;
+    }
+    if (typeof entry.description !== 'string') {
+      problem(catalogPath, `theme "${slug}" has no description string.`);
+      continue;
+    }
+    if (typeof entry.maintained !== 'boolean') {
+      problem(catalogPath, `theme "${slug}" has no maintained flag.`);
+      continue;
+    }
+    if (!fs.existsSync(path.join(themeDir, source))) {
+      problem(rel(themeDir), `holds no ${source} for theme "${slug}".`);
+      continue;
+    }
+    const descriptor = path.join(themeDir, `${stem}.doc.mjs`);
+    if (fs.existsSync(descriptor)) continue;
+    plan.writes.push({
+      path: descriptor,
+      contents: themeDescriptorSource({
+        type: 'theme',
+        name: slug,
+        displayName: entry.displayName,
+        description: entry.description,
+        maintained: entry.maintained,
+      }),
+    });
+  }
+  if (plan.problems.length > 0)
+    return {writes: [], deletes: [], problems: plan.problems};
+  plan.deletes.push(catalogFile);
+  return plan;
+}

package/assets/codemods/transforms/v0.0.14/__tests__/rename-status-variants.test.mjs

@@ -1,205 +1,126 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
-import {describe, it, expect} from 'vitest';
+import {describe, expect, it} from 'vitest';
+import transform from '../rename-status-variants.mjs';
 
 async function applyTransform(source) {
-  const {default: transform} = await import(
-    '../rename-status-variants.mjs'
-  );
   const jscodeshift = (await import('jscodeshift')).default;
   const j = jscodeshift.withParser('tsx');
   const api = {jscodeshift: j, stats: () => {}, report: () => {}};
-  const file = {source, path: 'test.tsx'};
-  const result = transform(file, api);
-  return result ?? source;
+  return transform({source, path: 'test.tsx'}, api) ?? source;
 }
 
 describe('rename-status-variants', () => {
-  it('renames StatusDot variant="positive" to "success"', async () => {
-    const input = `<XDSStatusDot variant="positive" label="Online" />`;
-    const output = await applyTransform(input);
-    expect(output).toContain("'success'");
-    expect(output).not.toContain("'positive'");
-  });
+  it('renames direct StatusDot literals and ternary branches', async () => {
+    const output = await applyTransform(`import {StatusDot} from '@astryxdesign/core';
+const a = <StatusDot variant="positive" />;
+const b = <StatusDot variant={'negative'} />;
+const c = <StatusDot variant={ready ? 'info' : 'positive'} />;`);
 
-  it('renames StatusDot variant="negative" to "error"', async () => {
-    const input = `<XDSStatusDot variant="negative" label="Offline" />`;
-    const output = await applyTransform(input);
-    expect(output).toContain("'error'");
-    expect(output).not.toContain("'negative'");
+    expect(output).toContain("variant='success'");
+    expect(output).toContain("variant={'error'}");
+    expect(output).toContain("ready ? 'accent' : 'success'");
   });
 
-  it('renames StatusDot variant="info" to "accent"', async () => {
-    const input = `<XDSStatusDot variant="info" label="Info" />`;
-    const output = await applyTransform(input);
-    expect(output).toContain("'accent'");
-    expect(output).not.toContain("'info'");
-  });
+  it('renames literals inside satisfies expressions while preserving the type', async () => {
+    const output =
+      await applyTransform(`import {StatusDot} from '@astryxdesign/core';
+const view = <StatusDot variant={'positive' satisfies StatusDotVariant} />;`);
 
-  it('renames AvatarStatusDot variant="positive" to "success"', async () => {
-    const input = `<XDSAvatarStatusDot variant="positive" label="Online" />`;
-    const output = await applyTransform(input);
-    expect(output).toContain("'success'");
-    expect(output).not.toContain("'positive'");
+    expect(output).toContain("{'success' satisfies StatusDotVariant}");
   });
 
-  it('renames Icon color="positive" to "success"', async () => {
-    const input = `<XDSIcon color="positive" icon={CheckIcon} />`;
-    const output = await applyTransform(input);
-    expect(output).toContain("'success'");
-    expect(output).not.toContain("'positive'");
-  });
+  it('renames Icon, SVGIcon, AvatarStatusDot, and ProgressBar props', async () => {
+    const output = await applyTransform(`import {
+  Icon,
+  SVGIcon,
+  AvatarStatusDot,
+  ProgressBar,
+} from '@astryxdesign/core';
+const view = <>
+  <Icon color="negative" />
+  <SVGIcon color="positive" />
+  <AvatarStatusDot variant="negative" />
+  <ProgressBar variant="positive" />
+</>;`);
 
-  it('renames Icon color="negative" to "error"', async () => {
-    const input = `<XDSIcon color="negative" icon={XIcon} />`;
-    const output = await applyTransform(input);
-    expect(output).toContain("'error'");
-    expect(output).not.toContain("'negative'");
+    expect(output.match(/'error'/g)).toHaveLength(2);
+    expect(output.match(/'success'/g)).toHaveLength(2);
   });
 
-  it('renames ProgressBar variant="positive" to "success"', async () => {
-    const input = `<XDSProgressBar variant="positive" value={50} />`;
-    const output = await applyTransform(input);
-    expect(output).toContain("'success'");
-    expect(output).not.toContain("'positive'");
-  });
+  it('maps import aliases and default subpath imports', async () => {
+    const output = await applyTransform(`import {StatusDot as Dot} from '@xds/core';
+import IconGlyph from '@astryxdesign/core/Icon';
+const view = <><Dot variant="positive" /><IconGlyph color="negative" /></>;`);
 
-  it('renames ProgressBar variant="negative" to "error"', async () => {
-    const input = `<XDSProgressBar variant="negative" value={50} />`;
-    const output = await applyTransform(input);
-    expect(output).toContain("'error'");
-    expect(output).not.toContain("'negative'");
+    expect(output).toContain("<Dot variant='success'");
+    expect(output).toContain("<IconGlyph color='error'");
   });
 
-  it('handles expression container: variant={"positive"}', async () => {
-    const input = `<XDSStatusDot variant={'positive'} label="Online" />`;
-    const output = await applyTransform(input);
-    expect(output).toContain("'success'");
-    expect(output).not.toContain("'positive'");
-  });
+  it('maps namespace imports', async () => {
+    const output = await applyTransform(`import * as Core from '@astryxdesign/core';
+const view = <Core.StatusDot variant="info" />;`);
 
-  it('handles ternary: variant={x ? "positive" : "negative"}', async () => {
-    const input = `<XDSStatusDot variant={isOnline ? 'positive' : 'negative'} label="Status" />`;
-    const output = await applyTransform(input);
-    expect(output).toContain("'success'");
-    expect(output).toContain("'error'");
-    expect(output).not.toContain("'positive'");
-    expect(output).not.toContain("'negative'");
+    expect(output).toContain("variant='accent'");
   });
 
-  it('renames object property values in files importing target components', async () => {
-    const input = `import { XDSStatusDot } from '@xds/core/StatusDot';
-const args = { variant: 'positive' };`;
-    const output = await applyTransform(input);
-    expect(output).toContain("'success'");
-    expect(output).not.toContain("'positive'");
-  });
+  it('keeps Badge info distinct while renaming its removed variants', async () => {
+    const output = await applyTransform(`import {Badge} from '@astryxdesign/core';
+const view = <>
+  <Badge variant="info" />
+  <Badge variant="positive" />
+  <Badge variant="negative" />
+</>;`);
 
-  it('renames unambiguous values in Storybook argType options arrays but leaves ambiguous "info"', async () => {
-    const input = `import { XDSStatusDot } from '@xds/core/StatusDot';
-const meta = { argTypes: { variant: { options: ['positive', 'negative', 'warning', 'info', 'neutral'] } } };`;
-    const output = await applyTransform(input);
-    expect(output).toContain("'success'");
-    expect(output).toContain("'error'");
-    expect(output).not.toContain("'positive'");
-    expect(output).not.toContain("'negative'");
-    // 'info' is ambiguous (valid on Badge etc.) and this is a context-blind
-    // path — the codemod cannot tell which component the options describe, so
-    // it is left for human review rather than risk rewriting a valid value.
-    expect(output).toContain("'info'");
-    expect(output).not.toContain("'accent'");
-    // warning and neutral are unchanged
-    expect(output).toContain("'warning'");
-    expect(output).toContain("'neutral'");
+    expect(output).toContain('variant="info"');
+    expect(output).toContain("variant='success'");
+    expect(output).toContain("variant='error'");
   });
 
-  it('does not touch unrelated components', async () => {
-    const input = `<XDSBadge variant="info" label="New" />`;
-    const output = await applyTransform(input);
-    // XDSBadge is not in the target list
-    expect(output).toContain('info');
+  it('leaves variables, helpers, objects, types, and Storybook metadata untouched', async () => {
+    const input = `import {StatusDot} from '@astryxdesign/core';
+type CellTone = 'positive' | 'negative' | 'info';
+const args = {variant: 'positive'};
+const options = ['positive', 'negative', 'info'];
+function tone() { return 'negative' as const; }
+const view = <StatusDot variant={tone()} />;`;
+
+    expect(await applyTransform(input)).toBe(input);
   });
 
-  it('does not rewrite Badge config "info" in a file that also imports a target (Icon)', async () => {
-    // Regression: a file may import a target component (e.g. XDSIcon) AND
-    // declare a typed config object for a NON-target component (Badge, whose
-    // BadgeVariantMap still has `info`). The context-blind object-property path
-    // must NOT rewrite that `info` to `accent` just because the file imports a
-    // target — `accent` is not a valid Badge variant. positive/negative stay
-    // renamed (no component keeps them), but info is preserved.
-    const input = `import { XDSIcon } from '@xds/core/Icon';
-import { XDSBadge, type XDSBadgeVariant } from '@xds/core/Badge';
-const PROGRESS_CONFIG: Record<string, {label: string; variant: XDSBadgeVariant}> = {
-  OPEN: {label: 'Open', variant: 'info'},
-  DONE: {label: 'Done', variant: 'positive'},
-  BLOCKED: {label: 'Blocked', variant: 'negative'},
-};`;
-    const output = await applyTransform(input);
-    // Ambiguous 'info' on a Badge config is left intact.
-    expect(output).toContain("variant: 'info'");
-    expect(output).not.toContain("'accent'");
-    // Unambiguous values are still migrated (no component retains them).
-    expect(output).toContain("variant: 'success'");
-    expect(output).toContain("variant: 'error'");
-    expect(output).not.toContain("'positive'");
-    expect(output).not.toContain("'negative'");
+  it('leaves unrelated props untouched', async () => {
+    const output = await applyTransform(`import {StatusDot} from '@astryxdesign/core';
+const view = <StatusDot variant="positive" label="positive" />;`);
+
+    expect(output).toContain("variant='success'");
+    expect(output).toContain('label="positive"');
   });
 
-  it('still renames "info" to "accent" on a direct target JSX attribute', async () => {
-    // The precise path (component is known) keeps the full mapping, including
-    // the ambiguous info -> accent, even when other components are imported.
-    const input = `import { XDSStatusDot } from '@xds/core/StatusDot';
-import { XDSBadge } from '@xds/core/Badge';
-const a = <XDSStatusDot variant="info" label="Status" />;
-const b = <XDSBadge variant="info" label="New" />;`;
-    const output = await applyTransform(input);
-    // StatusDot's info -> accent (precise), Badge's info stays.
-    expect(output).toContain("<XDSStatusDot variant='accent'");
-    expect(output).toContain('<XDSBadge variant="info"');
+  it('ignores same-named components imported from other packages', async () => {
+    const input = `import {StatusDot} from '@other/core';
+const view = <StatusDot variant="positive" />;`;
+    expect(await applyTransform(input)).toBe(input);
   });
 
-  it('does not touch unrelated props on target components', async () => {
-    const input = `<XDSStatusDot variant="positive" label="positive result" />`;
-    const output = await applyTransform(input);
-    expect(output).toContain("'success'");
-    // The label "positive result" should NOT be renamed
-    expect(output).toContain('positive result');
+  it('ignores a local component that shadows an imported alias', async () => {
+    const output = await applyTransform(`import {StatusDot as Dot} from '@xds/core';
+const migrated = <Dot variant="positive" />;
+function Local(Dot) { return <Dot variant="negative" />; }`);
+
+    expect(output).toContain("variant='success'");
+    expect(output).toContain('variant="negative"');
   });
 
-  it('returns undefined when no changes needed', async () => {
-    const {default: transform} = await import(
-      '../rename-status-variants.mjs'
-    );
+  it('returns undefined when no direct prop needs a change', async () => {
     const jscodeshift = (await import('jscodeshift')).default;
     const j = jscodeshift.withParser('tsx');
-    const api = {jscodeshift: j, stats: () => {}, report: () => {}};
-    const source = `<XDSStatusDot variant='success' label='Online' />`;
-    const result = transform({source, path: 'test.tsx'}, api);
-    expect(result).toBeUndefined();
-  });
-
-  it('handles a full component file', async () => {
-    const input = `import { XDSStatusDot } from '@xds/core/StatusDot';
-import { XDSIcon } from '@xds/core/Icon';
-
-function StatusIndicator({ isOnline }: { isOnline: boolean }) {
-  return (
-    <div>
-      <XDSStatusDot
-        variant={isOnline ? 'positive' : 'negative'}
-        label={isOnline ? 'Online' : 'Offline'}
-      />
-      <XDSIcon
-        icon={isOnline ? CheckIcon : XIcon}
-        color={isOnline ? 'positive' : 'negative'}
-      />
-    </div>
-  );
-}`;
-    const output = await applyTransform(input);
-    expect(output).toContain("'success'");
-    expect(output).toContain("'error'");
-    expect(output).not.toContain("'positive'");
-    expect(output).not.toContain("'negative'");
+    const source = `import {StatusDot} from '@astryxdesign/core';
+const view = <StatusDot variant="success" />;`;
+    expect(
+      transform(
+        {source, path: 'test.tsx'},
+        {jscodeshift: j, stats: () => {}, report: () => {}},
+      ),
+    ).toBeUndefined();
   });
 });