@astryxdesign/cli 0.1.2 → 0.1.3

package/src/codemods/transforms/v0.1.3/__tests__/migrate-layout-components-to-experimental.test.mjs

@@ -0,0 +1,360 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+import {describe, it, expect} from 'vitest';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+/**
+ * Invoke the transform directly with a configured jscodeshift api, mirroring
+ * how other transform tests (and `runConfigCodemod`) drive transforms via the
+ * unified `(file, api) => string | null | undefined` contract.
+ *
+ * @param {string} source
+ * @param {string} [filePath]
+ * @returns {Promise<string|null>} the rewritten source, or null for no-op
+ */
+async function applyTransform(source, filePath = 'astryx.config.mjs') {
+  const {default: transform} = await import(
+    '../migrate-layout-components-to-experimental.mjs'
+  );
+  const jscodeshift = (await import('jscodeshift')).default;
+  const j = jscodeshift.withParser('babel');
+  const api = {jscodeshift: j, stats: () => {}, report: () => {}};
+  return transform({source, path: filePath}, api);
+}
+
+describe('migrate-layout-components-to-experimental — meta', () => {
+  it('declares itself as a config codemod', async () => {
+    const {meta} = await import(
+      '../migrate-layout-components-to-experimental.mjs'
+    );
+    expect(meta.codemodType).toBe('config');
+    expect(meta.title).toMatch(/layout\.components/);
+    expect(typeof meta.description).toBe('string');
+  });
+});
+
+describe('migrate-layout-components-to-experimental — string → {from}', () => {
+  it('normalizes a string entry to { from } (named import semantics)', async () => {
+    const input = `export default {
+  layout: {
+    components: {
+      KpiCard: '@/components/KpiCard',
+    },
+  },
+};
+`;
+    const output = await applyTransform(input);
+    expect(output).not.toBeNull();
+    // No longer under layout.
+    expect(output).not.toMatch(/layout\s*:/);
+    // Relocated under experimental.xle.components as { from }.
+    expect(output).toContain('experimental');
+    expect(output).toContain('xle');
+    expect(output).toMatch(/KpiCard:\s*\{\s*from:\s*['"]@\/components\/KpiCard['"]/);
+  });
+
+  it('normalizes multiple string entries', async () => {
+    const input = `export default {
+  layout: {
+    components: {
+      KpiCard: '@/components/KpiCard',
+      Banner: '@/components/Banner',
+    },
+  },
+};
+`;
+    const output = await applyTransform(input);
+    expect(output).toMatch(/KpiCard:\s*\{\s*from:\s*['"]@\/components\/KpiCard['"]/);
+    expect(output).toMatch(/Banner:\s*\{\s*from:\s*['"]@\/components\/Banner['"]/);
+  });
+});
+
+describe('migrate-layout-components-to-experimental — object entries carried unchanged', () => {
+  it('preserves default: true (default import semantics)', async () => {
+    const input = `export default {
+  layout: {
+    components: {
+      Chart: { from: '@/c/Chart', default: true },
+    },
+  },
+};
+`;
+    const output = await applyTransform(input);
+    expect(output).toContain("from: '@/c/Chart'");
+    expect(output).toContain('default: true');
+    expect(output).toContain('experimental');
+    expect(output).toContain('xle');
+  });
+
+  it('preserves description', async () => {
+    const input = `export default {
+  layout: {
+    components: {
+      Chart: { from: '@/c/Chart', description: 'A chart' },
+    },
+  },
+};
+`;
+    const output = await applyTransform(input);
+    expect(output).toContain("from: '@/c/Chart'");
+    expect(output).toContain("description: 'A chart'");
+  });
+
+  it('preserves from/description/default and key order', async () => {
+    const input = `export default {
+  layout: {
+    components: {
+      Chart: { from: '@/c/Chart', description: 'A chart', default: true },
+    },
+  },
+};
+`;
+    const output = await applyTransform(input);
+    // Order: from, then description, then default.
+    expect(output).toMatch(
+      /from:\s*'@\/c\/Chart',\s*description:\s*'A chart',\s*default:\s*true/,
+    );
+  });
+
+  it('migrates a mix of string and object entries', async () => {
+    const input = `export default {
+  layout: {
+    components: {
+      KpiCard: '@/components/KpiCard',
+      Chart: { from: '@/c/Chart', default: true },
+    },
+  },
+};
+`;
+    const output = await applyTransform(input);
+    expect(output).toMatch(/KpiCard:\s*\{\s*from:\s*['"]@\/components\/KpiCard['"]/);
+    expect(output).toContain("from: '@/c/Chart'");
+    expect(output).toContain('default: true');
+  });
+});
+
+describe('migrate-layout-components-to-experimental — wrapper forms', () => {
+  it('handles bare object literal default export', async () => {
+    const input = `export default {
+  layout: { components: { KpiCard: '@/components/KpiCard' } },
+};
+`;
+    const output = await applyTransform(input);
+    expect(output).toContain('experimental');
+    expect(output).toContain('xle');
+  });
+
+  it('handles createConfig({ ... }) wrapper', async () => {
+    const input = `import { createConfig } from '@astryxdesign/cli';
+
+export default createConfig({
+  layout: { components: { KpiCard: '@/components/KpiCard' } },
+});
+`;
+    const output = await applyTransform(input);
+    expect(output).not.toBeNull();
+    expect(output).toContain('createConfig(');
+    expect(output).toContain('experimental');
+    expect(output).toContain('xle');
+    expect(output).toMatch(/KpiCard:\s*\{\s*from:\s*['"]@\/components\/KpiCard['"]/);
+    expect(output).not.toMatch(/layout\s*:/);
+  });
+});
+
+describe('migrate-layout-components-to-experimental — placement', () => {
+  it('adds xle to a pre-existing experimental (no xle)', async () => {
+    const input = `export default {
+  experimental: { foo: true },
+  layout: { components: { KpiCard: '@/components/KpiCard' } },
+};
+`;
+    const output = await applyTransform(input);
+    expect(output).toContain('foo: true');
+    expect(output).toContain('xle');
+    expect(output).toMatch(/KpiCard:\s*\{\s*from:/);
+  });
+});
+
+describe('migrate-layout-components-to-experimental — no-op cases', () => {
+  it('returns null when there is no layout', async () => {
+    const input = `export default { theme: 'dark' };\n`;
+    const output = await applyTransform(input);
+    expect(output).toBeNull();
+  });
+
+  it('returns null when layout has no components', async () => {
+    const input = `export default { layout: { foo: 1 } };\n`;
+    // layout exists but has no components → no-op (return null) BEFORE the
+    // "extra key" check, because there is nothing to migrate.
+    const output = await applyTransform(input);
+    expect(output).toBeNull();
+  });
+
+  it('returns null on an already-migrated config (idempotence-ish)', async () => {
+    const input = `export default {
+  experimental: { xle: { components: { KpiCard: { from: '@/components/KpiCard' } } } },
+};
+`;
+    const output = await applyTransform(input);
+    expect(output).toBeNull();
+  });
+});
+
+describe('migrate-layout-components-to-experimental — bail (throw) cases', () => {
+  it('throws when experimental.xle already exists', async () => {
+    const input = `export default {
+  experimental: { xle: { components: {} } },
+  layout: { components: { KpiCard: '@/components/KpiCard' } },
+};
+`;
+    await expect(applyTransform(input)).rejects.toThrow(/experimental\.xle/);
+  });
+
+  it('throws when layout has an extra key besides components', async () => {
+    const input = `export default {
+  layout: {
+    components: { KpiCard: '@/components/KpiCard' },
+    spacing: 8,
+  },
+};
+`;
+    await expect(applyTransform(input)).rejects.toThrow(/other than/);
+  });
+
+  it('throws when an entry value is an identifier', async () => {
+    const input = `const Kpi = '@/components/KpiCard';
+export default {
+  layout: { components: { KpiCard: Kpi } },
+};
+`;
+    await expect(applyTransform(input)).rejects.toThrow(/cannot be safely migrated/);
+  });
+
+  it('throws when an entry value is a call expression', async () => {
+    const input = `export default {
+  layout: { components: { KpiCard: resolve('@/components/KpiCard') } },
+};
+`;
+    await expect(applyTransform(input)).rejects.toThrow(/cannot be safely migrated/);
+  });
+
+  it('throws on a non-object default export (variable reference)', async () => {
+    const input = `const config = { layout: { components: {} } };
+export default config;
+`;
+    await expect(applyTransform(input)).rejects.toThrow(/statically analyze/);
+  });
+});
+
+describe('migrate-layout-components-to-experimental — end-to-end via runConfigCodemod', () => {
+  it('rewrites astryx.config.mjs on disk through the unified runner', async () => {
+    const {runConfigCodemod} = await import('../../../run-codemod.mjs');
+    const {default: transform, meta} = await import(
+      '../migrate-layout-components-to-experimental.mjs'
+    );
+    const jscodeshift = (await import('jscodeshift')).default;
+
+    const originalCwd = process.cwd();
+    const tmpDir = fs.mkdtempSync(
+      path.join(process.cwd(), '.astryx-v013-codemod-test-'),
+    );
+    try {
+      process.chdir(tmpDir);
+      fs.writeFileSync(
+        path.join(tmpDir, 'package.json'),
+        JSON.stringify({name: 'consumer'}),
+      );
+      fs.writeFileSync(
+        path.join(tmpDir, 'astryx.config.mjs'),
+        `export default {
+  layout: { components: { KpiCard: '@/components/KpiCard' } },
+};
+`,
+      );
+
+      const entry = {
+        id: 'migrate-layout-components-to-experimental',
+        type: 'config',
+        codemod: {title: meta.title, transform},
+        package: 'core',
+        version: '0.1.3',
+      };
+      const log = {
+        step() {},
+        info() {},
+        success() {},
+        warn() {},
+        error() {},
+        message() {},
+      };
+      const result = runConfigCodemod(entry, {apply: true, log, jscodeshift});
+
+      expect(result.errors).toHaveLength(0);
+      expect(result.filesChanged).toBe(1);
+      const rewritten = fs.readFileSync(
+        path.join(tmpDir, 'astryx.config.mjs'),
+        'utf-8',
+      );
+      expect(rewritten).toContain('experimental');
+      expect(rewritten).toContain('xle');
+      expect(rewritten).toMatch(/KpiCard:\s*\{\s*from:/);
+      expect(rewritten).not.toMatch(/layout\s*:/);
+    } finally {
+      process.chdir(originalCwd);
+      fs.rmSync(tmpDir, {recursive: true, force: true});
+    }
+  });
+
+  it('surfaces a thrown bail as a structured error through runConfigCodemod', async () => {
+    const {runConfigCodemod} = await import('../../../run-codemod.mjs');
+    const {default: transform, meta} = await import(
+      '../migrate-layout-components-to-experimental.mjs'
+    );
+    const jscodeshift = (await import('jscodeshift')).default;
+
+    const originalCwd = process.cwd();
+    const tmpDir = fs.mkdtempSync(
+      path.join(process.cwd(), '.astryx-v013-codemod-test-'),
+    );
+    try {
+      process.chdir(tmpDir);
+      fs.writeFileSync(
+        path.join(tmpDir, 'package.json'),
+        JSON.stringify({name: 'consumer'}),
+      );
+      fs.writeFileSync(
+        path.join(tmpDir, 'astryx.config.mjs'),
+        `export default {
+  experimental: { xle: { components: {} } },
+  layout: { components: { KpiCard: '@/components/KpiCard' } },
+};
+`,
+      );
+
+      const entry = {
+        id: 'migrate-layout-components-to-experimental',
+        type: 'config',
+        codemod: {title: meta.title, transform},
+        package: 'core',
+        version: '0.1.3',
+      };
+      const log = {
+        step() {},
+        info() {},
+        success() {},
+        warn() {},
+        error() {},
+        message() {},
+      };
+      const result = runConfigCodemod(entry, {apply: true, log, jscodeshift});
+
+      expect(result.filesChanged).toBe(0);
+      expect(result.errors).toHaveLength(1);
+      expect(result.errors[0].error).toMatch(/experimental\.xle/);
+    } finally {
+      process.chdir(originalCwd);
+      fs.rmSync(tmpDir, {recursive: true, force: true});
+    }
+  });
+});

package/src/codemods/transforms/v0.1.3/index.mjs

@@ -0,0 +1,19 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file v0.1.3 transform manifest
+ *
+ * Lists all codemods for the v0.1.3 release in the order they should run.
+ */
+
+import migrateLayoutComponentsToExperimental, {
+  meta as migrateLayoutComponentsToExperimentalMeta,
+} from './migrate-layout-components-to-experimental.mjs';
+
+export default [
+  {
+    name: 'migrate-layout-components-to-experimental',
+    transform: migrateLayoutComponentsToExperimental,
+    meta: migrateLayoutComponentsToExperimentalMeta,
+  },
+];

package/src/codemods/transforms/v0.1.3/migrate-layout-components-to-experimental.mjs

@@ -0,0 +1,260 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Codemod: migrate astryx.config `layout.components` to
+ * `experimental.xle.components`.
+ *
+ * The published 0.1.2 CLI read XLE app-component registration from
+ * `astryx.config.*` under `layout.components`. The next release relocates this
+ * to `experimental.xle.components`, validated by a strict schema that REJECTS
+ * unknown keys — so any consumer that still has `layout.components` would
+ * hard-error on upgrade. This codemod performs the straight relocation.
+ *
+ * The semantics are IDENTICAL between the old and new shapes; this is purely a
+ * MOVE plus a string→object normalization. No meaning is changed:
+ *
+ *   OLD `layout.components` entry forms (from the 0.1.2 shim):
+ *     - string `'X'`  → a NAMED import; the KEY is both the local name and the
+ *       export name.
+ *     - object `{ from, description?, default? }` → `default: true` means a
+ *       default import; otherwise a named import (key = export name).
+ *
+ *   NEW `experimental.xle.components` entry shape (already shipped on the
+ *   branch; unchanged here): `{ from, description?, default? }`, with the same
+ *   semantics.
+ *
+ *   So the migration is:
+ *     - string `'X'`                            → `{ from: 'X' }`
+ *     - object `{ from, description?, default? }` → carried over UNCHANGED
+ *       (from/description/default preserved, key order preserved).
+ *
+ * The transform recognizes the config default export as EITHER a bare object
+ * literal (`export default { ... }`) or a `createConfig({ ... })` call wrapping
+ * an object literal (`export default createConfig({ ... })`). Anything else is
+ * not statically analyzable and the transform THROWS with a clear
+ * migrate-manually message (the unified config-codemod contract has no
+ * structured-error return — `runConfigCodemod` surfaces a thrown `err.message`
+ * as `{file, codemod, error}`).
+ */
+
+export const meta = {
+  title: 'Migrate astryx.config layout.components to experimental.xle.components',
+  description:
+    'Relocates XLE app-component registration from the legacy ' +
+    '`layout.components` config key to `experimental.xle.components`. String ' +
+    'entries (`Name: "@/path"`) are normalized to `{ from: "@/path" }` ' +
+    '(named import, key = export name); object entries are carried over ' +
+    'unchanged (from/description/default preserved). Bails with a clear ' +
+    'migrate-manually error when the config cannot be statically analyzed or ' +
+    'when merging would be unsafe.',
+  codemodType: 'config',
+};
+
+const MANUAL =
+  'migrate layout.components to experimental.xle.components manually';
+
+/**
+ * @param {{source: string, path: string}} file
+ * @param {{jscodeshift: Function}} api
+ * @returns {string|null}
+ */
+export default function transformer(file, api) {
+  const j = api.jscodeshift;
+  const root = j(file.source);
+
+  const defaultExports = root.find(j.ExportDefaultDeclaration);
+  if (defaultExports.size() === 0) {
+    throw new Error(
+      `could not statically analyze astryx config (no default export); ${MANUAL}`,
+    );
+  }
+
+  const declaration = defaultExports.paths()[0].node.declaration;
+
+  // Resolve the config object literal from either form:
+  //   export default { ... }
+  //   export default createConfig({ ... })
+  const configObject = resolveConfigObject(j, declaration);
+  if (!configObject) {
+    throw new Error(
+      `could not statically analyze astryx config; ${MANUAL}`,
+    );
+  }
+
+  // Locate the top-level `layout` property and its `components` value.
+  const layoutProp = findObjectProperty(j, configObject, 'layout');
+  if (!layoutProp) {
+    return null; // no layout → nothing to migrate
+  }
+  if (!j.ObjectExpression.check(layoutProp.value)) {
+    throw new Error(
+      `astryx config \`layout\` is not an object literal; ${MANUAL}`,
+    );
+  }
+
+  const componentsProp = findObjectProperty(j, layoutProp.value, 'components');
+  if (!componentsProp) {
+    return null; // no layout.components → nothing to migrate
+  }
+  if (!j.ObjectExpression.check(componentsProp.value)) {
+    throw new Error(
+      `astryx config \`layout.components\` is not an object literal; ${MANUAL}`,
+    );
+  }
+
+  // `components` was the only documented `layout` key. Anything else is
+  // unexpected and we cannot safely guess intent.
+  const otherLayoutKeys = layoutProp.value.properties.filter(
+    p => p !== componentsProp,
+  );
+  if (otherLayoutKeys.length > 0) {
+    throw new Error(
+      `astryx config \`layout\` has keys other than \`components\`; ${MANUAL}`,
+    );
+  }
+
+  // Build the migrated `components` object literal entry by entry.
+  const migratedComponents = buildMigratedComponents(j, componentsProp.value);
+
+  // Placement into `experimental.xle.components`.
+  const experimentalProp = findObjectProperty(j, configObject, 'experimental');
+  if (experimentalProp) {
+    if (!j.ObjectExpression.check(experimentalProp.value)) {
+      throw new Error(
+        `astryx config \`experimental\` is not an object literal; ${MANUAL}`,
+      );
+    }
+    const xleProp = findObjectProperty(j, experimentalProp.value, 'xle');
+    if (xleProp) {
+      // Can't safely merge into a pre-existing experimental.xle.
+      throw new Error(
+        `astryx config already defines \`experimental.xle\`; ${MANUAL}`,
+      );
+    }
+    experimentalProp.value.properties.push(
+      j.objectProperty(j.identifier('xle'), buildXleObject(j, migratedComponents)),
+    );
+  } else {
+    configObject.properties.push(
+      j.objectProperty(
+        j.identifier('experimental'),
+        j.objectExpression([
+          j.objectProperty(j.identifier('xle'), buildXleObject(j, migratedComponents)),
+        ]),
+      ),
+    );
+  }
+
+  // Remove the migrated data from `layout`. Since `components` was the only
+  // key (asserted above), remove the entire `layout` property.
+  configObject.properties = configObject.properties.filter(
+    p => p !== layoutProp,
+  );
+
+  return root.toSource();
+}
+
+/**
+ * Resolve the wrapped config object literal from a default-export declaration.
+ * Handles `{ ... }` and `createConfig({ ... })`.
+ * @returns {object|null} the ObjectExpression node, or null if not analyzable
+ */
+function resolveConfigObject(j, declaration) {
+  if (!declaration) return null;
+  if (j.ObjectExpression.check(declaration)) {
+    return declaration;
+  }
+  if (
+    j.CallExpression.check(declaration) &&
+    declaration.arguments.length >= 1 &&
+    j.ObjectExpression.check(declaration.arguments[0])
+  ) {
+    return declaration.arguments[0];
+  }
+  return null;
+}
+
+/**
+ * Find a (non-computed, non-spread) property on an object literal by key name.
+ * Supports Identifier and string-literal keys.
+ * @returns {object|undefined} the property node
+ */
+function findObjectProperty(j, objectExpression, name) {
+  return objectExpression.properties.find(prop => {
+    if (
+      !j.ObjectProperty.check(prop) &&
+      !j.Property.check(prop)
+    ) {
+      return false;
+    }
+    if (prop.computed) return false;
+    const key = prop.key;
+    if (j.Identifier.check(key)) return key.name === name;
+    if (j.StringLiteral.check(key)) return key.value === name;
+    if (j.Literal.check(key)) return key.value === name;
+    return false;
+  });
+}
+
+/**
+ * Build the migrated `components` ObjectExpression from the old one.
+ * @returns {object} ObjectExpression
+ */
+function buildMigratedComponents(j, oldComponents) {
+  const newProps = oldComponents.properties.map(prop => {
+    if (
+      (!j.ObjectProperty.check(prop) && !j.Property.check(prop)) ||
+      prop.computed
+    ) {
+      throw new Error(
+        `astryx config \`layout.components\` has a non-literal entry; ${MANUAL}`,
+      );
+    }
+
+    const value = prop.value;
+
+    // string `'X'` → `{ from: 'X' }`
+    if (j.StringLiteral.check(value) || (j.Literal.check(value) && typeof value.value === 'string')) {
+      return j.objectProperty(
+        cloneKey(j, prop.key),
+        j.objectExpression([
+          j.objectProperty(j.identifier('from'), cloneStringLiteral(j, value)),
+        ]),
+      );
+    }
+
+    // object `{ from, description?, default? }` → carried over UNCHANGED
+    if (j.ObjectExpression.check(value)) {
+      return j.objectProperty(cloneKey(j, prop.key), value);
+    }
+
+    // anything else (identifier, call, ternary, etc.) → cannot safely migrate
+    throw new Error(
+      `astryx config \`layout.components\` entry is neither a string nor an ` +
+        `object literal and cannot be safely migrated; ${MANUAL}`,
+    );
+  });
+
+  return j.objectExpression(newProps);
+}
+
+/** Build `{ components: <obj> }` for `experimental.xle`. */
+function buildXleObject(j, migratedComponents) {
+  return j.objectExpression([
+    j.objectProperty(j.identifier('components'), migratedComponents),
+  ]);
+}
+
+/** Clone a property key node so we don't reuse a node across the tree. */
+function cloneKey(j, key) {
+  if (j.Identifier.check(key)) return j.identifier(key.name);
+  if (j.StringLiteral.check(key)) return j.stringLiteral(key.value);
+  if (j.Literal.check(key)) return j.literal(key.value);
+  return key;
+}
+
+/** Build a fresh string literal preserving the original raw quoting if possible. */
+function cloneStringLiteral(j, value) {
+  if (j.StringLiteral.check(value)) return j.stringLiteral(value.value);
+  return j.literal(value.value);
+}

package/src/commands/agent-docs.mjs

@@ -180,6 +180,9 @@ export function generateCompressedIndex(version, {coreDir, runPrefix = getRunPre
   // Rules — the top error-preventers.
   lines.push('RULES:');
   lines.push('- No <div> — components do all layout/spacing. Full page → AppShell; sidebar nav → SideNav.');
+  lines.push('- Frame first: pick the shell (AppShell / Layout+LayoutPanel) and budget regions in px BEFORE writing content (`astryx docs layout`).');
+  lines.push('- Dense data = rows (Table, List/Item) edge-to-edge — never Card-wrapped list items. Card = dashboard widgets, galleries, settings groups only.');
+  lines.push('- Status → StatusDot/Token; Badge only for counts and enumerated states, never decoration.');
   // Styling guidance tailored to the project's configured system — never
   // recommend a path that isn't compiled here (xstyle needs the StyleX compiler;
   // utilities need Tailwind). Tokens are always the source of truth.
@@ -207,7 +210,7 @@ export function generateCompressedIndex(version, {coreDir, runPrefix = getRunPre
       .sort();
     if (topics.length > 0) lines.push(`  docs <topic>       ${topics.join(', ')}`);
   }
-  lines.push('  swizzle <Name>     eject component source (--gap reports why)');
+  lines.push('  swizzle <Name>     eject component source for deep customization');
   lines.push('  upgrade --apply    run after any @astryxdesign/core bump');
   lines.push(MARKER_END);