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

package/assets/codemods/transforms/v0.1.8/__tests__/rename-avatar-size-scale.test.mjs

@@ -1,129 +1,161 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
-import {describe, expect, it} from 'vitest';
-import transform from '../rename-avatar-size-scale.mjs';
+import {describe, it, expect} from 'vitest';
 
 async function applyTransform(source) {
+  const {default: transform} = await import('../rename-avatar-size-scale.mjs');
   const jscodeshift = (await import('jscodeshift')).default;
   const j = jscodeshift.withParser('tsx');
   const api = {jscodeshift: j, stats: () => {}, report: () => {}};
-  return transform({source, path: 'test.tsx'}, api) ?? source;
+  const file = {source, path: 'test.tsx'};
+  const result = transform(file, api);
+  return result ?? source;
 }
 
 describe('rename-avatar-size-scale', () => {
-  it('renames every direct Avatar size literal', async () => {
-    const output =
-      await applyTransform(`import {Avatar} from '@astryxdesign/core';
+  it('renames every named size on an Avatar JSX size attribute', async () => {
+    const input = `import {Avatar} from '@astryxdesign/core';
 const a = <Avatar name="A" size="tiny" />;
 const b = <Avatar name="B" size="xsmall" />;
 const c = <Avatar name="C" size="small" />;
 const d = <Avatar name="D" size="medium" />;
-const e = <Avatar name="E" size="large" />;`);
-
-    for (const size of ['xsm', 'sm', 'md', 'lg', 'xl']) {
-      expect(output).toContain(`size='${size}'`);
+const e = <Avatar name="E" size="large" />;`;
+    const output = await applyTransform(input);
+    expect(output).toContain(`size='xsm'`);
+    expect(output).toContain(`size='sm'`);
+    expect(output).toContain(`size='md'`);
+    expect(output).toContain(`size='lg'`);
+    expect(output).toContain(`size='xl'`);
+    for (const old of ['tiny', 'xsmall', 'small', 'medium', 'large']) {
+      expect(output).not.toContain(`size="${old}"`);
     }
   });
 
-  it('renames literals inside satisfies expressions while preserving the type', async () => {
-    const output =
-      await applyTransform(`import {Avatar} from '@astryxdesign/core';
-const view = <Avatar size={'small' satisfies AvatarSize} />;`);
-
-    expect(output).toContain("{'md' satisfies AvatarSize}");
+  it('renames size on AvatarGroup', async () => {
+    const input = `import {AvatarGroup} from '@astryxdesign/core';
+const x = <AvatarGroup size="medium">{kids}</AvatarGroup>;`;
+    const output = await applyTransform(input);
+    expect(output).toContain(`size='lg'`);
   });
 
-  it('renames AvatarGroup and conditional literals', async () => {
-    const output =
-      await applyTransform(`import {AvatarGroup} from '@astryxdesign/core';
-const view = <AvatarGroup size={large ? 'large' : 'small'}>{kids}</AvatarGroup>;`);
-
-    expect(output).toContain("large ? 'xl' : 'md'");
+  it('leaves numeric sizes untouched', async () => {
+    const input = `import {Avatar} from '@astryxdesign/core';
+const x = <Avatar name="A" size={48} />;`;
+    const output = await applyTransform(input);
+    expect(output).toContain('size={48}');
   });
 
-  it('maps import aliases and default subpath imports', async () => {
-    const output =
-      await applyTransform(`import {Avatar as Face} from '@xds/core';
-import Faces from '@astryxdesign/core/AvatarGroup';
-const view = <><Face size="medium" /><Faces size="large" /></>;`);
-
-    expect(output).toContain("<Face size='lg'");
-    expect(output).toContain("<Faces size='xl'");
+  it('is alias-aware', async () => {
+    const input = `import {Avatar as Face} from '@astryxdesign/core';
+const x = <Face name="A" size="small" />;`;
+    const output = await applyTransform(input);
+    expect(output).toContain(`size='md'`);
   });
 
-  it('ignores declaration-level type imports paired with a local Avatar', async () => {
-    const input = `import type {Avatar} from '@astryxdesign/core';
-const Avatar = props => <div {...props} />;
-const view = <Avatar size="small" />;`;
-
-    expect(await applyTransform(input)).toBe(input);
+  it('renames the subpath and legacy import sources', async () => {
+    const sub = `import {Avatar} from '@astryxdesign/core/Avatar';
+const x = <Avatar name="A" size="large" />;`;
+    expect(await applyTransform(sub)).toContain(`size='xl'`);
+    const legacy = `import {Avatar} from '@xds/core';
+const x = <Avatar name="A" size="tiny" />;`;
+    expect(await applyTransform(legacy)).toContain(`size='xsm'`);
   });
 
-  it('ignores mixed type specifiers while migrating runtime imports', async () => {
-    const output =
-      await applyTransform(`import {type Avatar, AvatarGroup} from '@astryxdesign/core';
-const Avatar = props => <div {...props} />;
-const view = <><Avatar size="small" /><AvatarGroup size="large" /></>;`);
+  it('renames a size inside a ternary on an Avatar element', async () => {
+    const input = `import {Avatar} from '@astryxdesign/core';
+const x = <Avatar name="A" size={big ? 'large' : 'small'} />;`;
+    const output = await applyTransform(input);
+    expect(output).toContain(`big ? 'xl' : 'md'`);
+  });
 
-    expect(output).toContain('<Avatar size="small"');
-    expect(output).toContain("<AvatarGroup size='xl'");
+  it('renames the UNIQUE names tiny/xsmall in Storybook options and size args', async () => {
+    const input = `import {Avatar} from '@astryxdesign/core';
+const meta = {
+  argTypes: {size: {control: 'select', options: ['tiny', 'xsmall']}},
+  args: {size: 'tiny'},
+};`;
+    const output = await applyTransform(input);
+    expect(output).toContain(`['xsm', 'sm']`);
+    expect(output).toContain(`size: 'xsm'`);
   });
 
-  it('maps namespace imports', async () => {
-    const output =
-      await applyTransform(`import * as Core from '@astryxdesign/core';
-const view = <Core.Avatar size="small" />;`);
+  it('renames a FULL Storybook options array (unique name unlocks ambiguous members)', async () => {
+    // The presence of a unique name (tiny/xsmall) proves the whole array is the
+    // Avatar size enum, so small/medium/large in it are safe to rename too.
+    const input = `import {Avatar} from '@astryxdesign/core';
+const meta = {
+  argTypes: {size: {control: 'select', options: ['tiny', 'xsmall', 'small', 'medium', 'large']}},
+};`;
+    const output = await applyTransform(input);
+    expect(output).toContain(`['xsm', 'sm', 'md', 'lg', 'xl']`);
+  });
 
-    expect(output).toContain("size='md'");
+  it('renames a standalone Avatar-size array literal used with .map()', async () => {
+    const input = `import {AvatarGroup} from '@astryxdesign/core';
+const sizes = (['tiny', 'xsmall', 'small', 'medium', 'large'] as const).map(s => s);`;
+    const output = await applyTransform(input);
+    expect(output).toContain(`['xsm', 'sm', 'md', 'lg', 'xl']`);
   });
 
-  it('leaves numeric and dynamic sizes untouched', async () => {
+  it('does NOT rename an array of ambiguous words with no unique Avatar name', async () => {
+    // Without tiny/xsmall, the array could be anything (priorities, densities),
+    // so ambiguous members are left untouched.
     const input = `import {Avatar} from '@astryxdesign/core';
-const named = 'small';
-const a = <Avatar size={48} />;
-const b = <Avatar size={named} />;`;
-    expect(await applyTransform(input)).toBe(input);
+const densities = ['small', 'medium', 'large'] as const;`;
+    const output = await applyTransform(input);
+    expect(output).toContain(`['small', 'medium', 'large']`);
   });
 
-  it('leaves objects, types, arrays, and Storybook metadata untouched', async () => {
+  it('renames a UNIQUE name in a size-typed union literal', async () => {
     const input = `import {Avatar} from '@astryxdesign/core';
-type Density = 'tiny' | 'xsmall' | 'small' | 'medium' | 'large';
-const card = {size: 'small'};
-const sizes = ['tiny', 'xsmall', 'small', 'medium', 'large'];
-const meta = {argTypes: {size: {options: sizes}}};
-const view = <Avatar size={card.size} />;`;
-
-    expect(await applyTransform(input)).toBe(input);
+type Props = {size: 'tiny' | 'xsmall'};`;
+    const output = await applyTransform(input);
+    expect(output).toContain(`'xsm' | 'sm'`);
   });
 
-  it('does not touch files without an Avatar import', async () => {
-    const input = `import {Badge} from '@astryxdesign/core';
-const view = <Badge size="small" />;`;
-    expect(await applyTransform(input)).toBe(input);
-  });
+  // --- Precision guards: ambiguous common words must NOT be corrupted in
+  // --- context-blind positions, even in files that import Avatar. ---
 
-  it('ignores same-named components imported from other packages', async () => {
-    const input = `import {Avatar} from '@other/core';
-const view = <Avatar size="small" />;`;
-    expect(await applyTransform(input)).toBe(input);
+  it('does NOT rename ambiguous names in an unrelated union type', async () => {
+    const input = `import {Avatar} from '@astryxdesign/core';
+type TaskPriority = 'urgent' | 'high' | 'medium' | 'low' | 'none';`;
+    const output = await applyTransform(input);
+    expect(output).toContain(`'medium'`);
+    expect(output).not.toContain(`'lg'`);
   });
 
-  it('ignores a local component that shadows an imported alias', async () => {
-    const output =
-      await applyTransform(`import {Avatar as Face} from '@xds/core';
-const migrated = <Face size="medium" />;
-function Local(Face) { return <Face size="large" />; }`);
+  it('does NOT rename an ambiguous name in a non-size object property', async () => {
+    const input = `import {Avatar} from '@astryxdesign/core';
+const cfg = {priority: 'medium', density: 'large'};`;
+    const output = await applyTransform(input);
+    expect(output).toContain(`priority: 'medium'`);
+    expect(output).toContain(`density: 'large'`);
+  });
 
-    expect(output).toContain("size='lg'");
-    expect(output).toContain('size="large"');
+  it('does NOT rename an ambiguous name in a size-keyed object property (component unknown)', async () => {
+    // A `size: 'small'` object entry could belong to any component; renaming it
+    // blind would be unsafe, so it is left for manual migration.
+    const input = `import {Avatar} from '@astryxdesign/core';
+const args = {size: 'small'};`;
+    const output = await applyTransform(input);
+    expect(output).toContain(`size: 'small'`);
   });
 
-  it('leaves unrelated props on Avatar untouched', async () => {
-    const output =
-      await applyTransform(`import {Avatar} from '@astryxdesign/core';
-const view = <Avatar size="small" label="small" />;`);
+  it('does not touch files that never import Avatar/AvatarGroup', async () => {
+    const input = `import {Badge} from '@astryxdesign/core';
+const x = <Badge size="small" />;
+type P = 'tiny' | 'xsmall';`;
+    const output = await applyTransform(input);
+    expect(output).toContain(`size="small"`);
+    expect(output).toContain(`'tiny' | 'xsmall'`);
+  });
 
-    expect(output).toContain("size='md'");
-    expect(output).toContain('label="small"');
+  it('does not rename an unrelated non-size string in an Avatar file', async () => {
+    const input = `import {Avatar} from '@astryxdesign/core';
+const label = 'small';
+const x = <Avatar name="A" size="small" />;`;
+    const output = await applyTransform(input);
+    expect(output).toContain(`const label = 'small'`);
+    expect(output).toContain(`size='md'`);
   });
 });

package/assets/codemods/transforms/v0.1.8/rename-avatar-size-scale.mjs

@@ -4,23 +4,46 @@
  * @file Codemod: Rename Avatar named sizes to Icon's abbreviated scale
  * @see https://github.com/facebook/astryx/issues/2672
  *
- * This transform is deliberately limited to static literals written directly
- * in the `size` prop of an imported Avatar or AvatarGroup JSX element. It does
- * not infer through variables, helpers, objects, types, Storybook metadata, or
- * wrappers: missing an indirect migration is safer than rewriting another
- * component's size vocabulary.
+ * As of v0.1.8, Avatar and AvatarGroup use the same abbreviated size scale as
+ * Icon (`xsm`/`sm`/`md`/`lg`/`xl`) instead of full words. Pixel values are
+ * unchanged — only the names move:
+ *
+ *   tiny (20px)   → xsm
+ *   xsmall (24px) → sm
+ *   small (36px)  → md   ← also the new default (was `small`)
+ *   medium (48px) → lg
+ *   large (128px) → xl
+ *
+ * The default size shifts from `small` to `md`, but that is the SAME 36px, so
+ * call sites that relied on the default need no change.
+ *
+ * ## Precision
+ *
+ * `small`, `medium`, and `large` are common English words that appear as
+ * unrelated string/type literals (priorities, statuses, breakpoints, …). To
+ * avoid corrupting those, the three AMBIGUOUS names are renamed ONLY in a
+ * precise context: a `size` JSX attribute on a component that resolves to an
+ * Avatar/AvatarGroup import (alias-aware).
+ *
+ * `tiny` and `xsmall` are unique to Avatar's scale, so they are additionally
+ * renamed in context-blind positions (object properties keyed `size`/`*Size`,
+ * Storybook `options` arrays, and size-typed union literals) within files that
+ * import Avatar/AvatarGroup.
  */
 
-import {transformProp} from '../../transform-prop.mjs';
-
 export const meta = {
   title: 'Rename Avatar named sizes tiny/xsmall/small/medium/large → xsm/sm/md/lg/xl',
   description:
-    'Renames static sizes written directly on imported Avatar and AvatarGroup ' +
-    'JSX elements. Indirect values are left unchanged for manual migration.',
+    'Avatar and AvatarGroup adopt Icon\'s abbreviated size scale ' +
+    '(xsm/sm/md/lg/xl). Pixel values are unchanged; the default moves from ' +
+    '`small` to `md` (both 36px). The ambiguous names small/medium/large are ' +
+    'only renamed on Avatar/AvatarGroup `size` JSX attributes; the unique ' +
+    'names tiny/xsmall are also renamed in size-keyed props, Storybook ' +
+    'options, and union types in files importing Avatar/AvatarGroup.',
   pr: '#2672',
 };
 
+/** Import sources that provide the Astryx Avatar/AvatarGroup components. */
 const IMPORT_SOURCES = new Set([
   '@astryxdesign/core',
   '@astryxdesign/core/Avatar',
@@ -30,11 +53,10 @@ const IMPORT_SOURCES = new Set([
   '@xds/core/AvatarGroup',
 ]);
 
-const COMPONENT_PROPS = new Map([
-  ['Avatar', new Set(['size'])],
-  ['AvatarGroup', new Set(['size'])],
-]);
+/** Component names whose `size` prop is renamed. */
+const TARGET_IMPORTED_NAMES = new Set(['Avatar', 'AvatarGroup']);
 
+/** Old → new size-name mapping. */
 const RENAMES = new Map([
   ['tiny', 'xsm'],
   ['xsmall', 'sm'],
@@ -43,38 +65,46 @@ const RENAMES = new Map([
   ['large', 'xl'],
 ]);
 
-/** @param {string} name */
-function canonicalComponentName(name) {
-  return name.startsWith('XDS') ? name.slice(3) : name;
-}
+/**
+ * Ambiguous names — common words that must ONLY be renamed in a precise
+ * context. `tiny`/`xsmall` are omitted because they are unique to Avatar's
+ * scale; their presence in a collection proves it is an Avatar size enum.
+ */
+const AMBIGUOUS = new Set(['small', 'medium', 'large']);
+
+/** Names that appear only in Avatar's scale — safe signals of Avatar sizing. */
+const UNIQUE = new Set(['tiny', 'xsmall']);
 
-/** @param {any} node @returns {boolean} */
-function renameStaticValue(node) {
+/**
+ * Rename a string-literal node if its value is an old size name.
+ * Unwraps `'small' as const`. In non-precise contexts, ambiguous names are
+ * skipped. Returns true when a rename occurred.
+ */
+function renameValue(/** @type {any} */ node, {precise = false} = {}) {
   if (!node) return false;
+  const target = node.type === 'TSAsExpression' ? node.expression : node;
+  const isString =
+    target.type === 'StringLiteral' || target.type === 'Literal';
+  if (!isString || typeof target.value !== 'string') return false;
+  const replacement = RENAMES.get(target.value);
+  if (!replacement) return false;
+  if (!precise && AMBIGUOUS.has(target.value)) return false;
+  target.value = replacement;
+  if (target.raw) target.raw = undefined;
+  return true;
+}
+
+/** Extract a plain string value from a literal-ish node, or null. */
+function literalString(/** @type {any} */ node) {
+  const target = node?.type === 'TSAsExpression' ? node.expression : node;
   if (
-    node.type === 'TSAsExpression' ||
-    node.type === 'TSSatisfiesExpression' ||
-    node.type === 'TypeCastExpression' ||
-    node.type === 'ParenthesizedExpression'
-  ) {
-    return renameStaticValue(node.expression);
-  }
-  if (node.type === 'ConditionalExpression') {
-    const consequentChanged = renameStaticValue(node.consequent);
-    const alternateChanged = renameStaticValue(node.alternate);
-    return consequentChanged || alternateChanged;
-  }
-  if (
-    (node.type !== 'StringLiteral' && node.type !== 'Literal') ||
-    typeof node.value !== 'string'
+    target &&
+    (target.type === 'StringLiteral' || target.type === 'Literal') &&
+    typeof target.value === 'string'
   ) {
-    return false;
+    return target.value;
   }
-  const replacement = RENAMES.get(node.value);
-  if (!replacement) return false;
-  node.value = replacement;
-  if (node.raw) node.raw = undefined;
-  return true;
+  return null;
 }
 
 /**
@@ -87,23 +117,122 @@ export default function transformer(file, api) {
   const root = j(file.source);
   let hasChanges = false;
 
-  transformProp(
-    root,
-    j,
-    {
-      matchesImport: source => IMPORT_SOURCES.has(source),
-      components: COMPONENT_PROPS,
-      normalizeComponentName: canonicalComponentName,
-    },
-    propPath => {
-      const prop = propPath.node;
-      const value =
-        prop.value?.type === 'JSXExpressionContainer'
-          ? prop.value.expression
-          : prop.value;
-      if (renameStaticValue(value)) hasChanges = true;
-    },
-  );
+  // Track alias-aware local names for the target components.
+  const targetLocals = new Set();
+  root.find(j.ImportDeclaration).forEach((/** @type {any} */ path) => {
+    if (!IMPORT_SOURCES.has(path.node.source.value)) return;
+    for (const spec of path.node.specifiers ?? []) {
+      if (
+        spec.type === 'ImportSpecifier' &&
+        TARGET_IMPORTED_NAMES.has(spec.imported.name)
+      ) {
+        targetLocals.add(spec.local.name);
+      }
+    }
+  });
+
+  if (targetLocals.size === 0) return undefined;
+
+  function renameArrayElements(/** @type {any} */ node) {
+    let arr = node;
+    if (arr.type === 'TSAsExpression') arr = arr.expression;
+    if (arr.type !== 'ArrayExpression') return;
+    // If the array contains a name unique to Avatar's scale (tiny/xsmall), the
+    // whole collection is unambiguously the Avatar size enum, so it is safe to
+    // rename the ambiguous members too. Otherwise stay conservative.
+    const precise = arr.elements.some((/** @type {any} */ el) => UNIQUE.has(literalString(el)));
+    for (const el of arr.elements) {
+      if (renameValue(el, {precise})) hasChanges = true;
+    }
+  }
+
+  // 1. `size` JSX attributes on target components — PRECISE (component known),
+  //    so all five names, including the ambiguous ones, are renamed here.
+  root.find(j.JSXOpeningElement).forEach((/** @type {any} */ path) => {
+    const name = path.node.name;
+    const componentName = name.type === 'JSXIdentifier' ? name.name : null;
+    if (!componentName || !targetLocals.has(componentName)) return;
+
+    for (const attr of path.node.attributes) {
+      if (attr.type !== 'JSXAttribute' || attr.name?.name !== 'size') continue;
+      const value = attr.value;
+
+      // size="small"
+      if (renameValue(value, {precise: true})) {
+        hasChanges = true;
+        continue;
+      }
+      if (
+        value &&
+        value.type === 'JSXExpressionContainer' &&
+        value.expression
+      ) {
+        // size={'small'}
+        if (renameValue(value.expression, {precise: true})) {
+          hasChanges = true;
+          continue;
+        }
+        // size={cond ? 'small' : 'large'}
+        if (value.expression.type === 'ConditionalExpression') {
+          if (renameValue(value.expression.consequent, {precise: true}))
+            hasChanges = true;
+          if (renameValue(value.expression.alternate, {precise: true}))
+            hasChanges = true;
+        }
+      }
+    }
+  });
+
+  // 2. Object properties keyed `size` (or `*Size`) + Storybook `options`
+  //    arrays — NON-PRECISE (the component isn't known here), so only the
+  //    unique names tiny/xsmall are renamed.
+  const PropertyType = j.ObjectProperty ?? j.Property;
+  root.find(PropertyType).forEach((/** @type {any} */ path) => {
+    const key = path.node.key;
+    const keyName =
+      key.type === 'Identifier'
+        ? key.name
+        : key.type === 'StringLiteral' || key.type === 'Literal'
+          ? key.value
+          : null;
+    if (typeof keyName !== 'string') return;
+
+    const lower = keyName.toLowerCase();
+    if (lower !== 'size' && !lower.endsWith('size')) return;
+
+    const value = path.node.value;
+    // size: 'tiny'
+    if (renameValue(value)) {
+      hasChanges = true;
+      return;
+    }
+    // size: { control: 'select', options: ['tiny', ...] }
+    if (value.type === 'ObjectExpression') {
+      const optionsProp = value.properties.find(
+        (/** @type {any} */ p) => p.key && (p.key.name === 'options' || p.key.value === 'options'),
+      );
+      if (optionsProp) renameArrayElements(optionsProp.value);
+    }
+    // size: ['tiny', 'xsmall', ...]
+    renameArrayElements(value);
+  });
+
+  // 3. Union-type literals — NON-PRECISE, so only the unique names tiny/xsmall
+  //    are renamed. This avoids corrupting unrelated unions that happen to use
+  //    common words like 'medium' (e.g. a priority or breakpoint type) in a
+  //    file that also imports Avatar.
+  root.find(j.TSLiteralType).forEach((/** @type {any} */ path) => {
+    if (renameValue(path.node.literal)) hasChanges = true;
+  });
+
+  // 4. Standalone array literals whose members are exactly the Avatar size
+  //    scale (identified by the presence of a unique name like tiny/xsmall) —
+  //    e.g. `(['tiny', 'xsmall', 'small', 'medium', 'large'] as const).map(...)`
+  //    used to render every size. The unique name proves the whole array is the
+  //    Avatar enum, so its ambiguous members can be renamed safely.
+  root.find(j.ArrayExpression).forEach((/** @type {any} */ path) => {
+    renameArrayElements(path.node);
+  });
 
   if (!hasChanges) return undefined;
   return root.toSource({quote: 'single'});

package/clients/cli/commands/component-package.test.mjs

@@ -5,7 +5,6 @@ import * as fs from 'node:fs';
 import * as path from 'node:path';
 import * as os from 'node:os';
 import {component} from '../../../api/component/component.mjs';
-import {runCli} from '../../../test-utils/run-cli.mjs';
 
 // These tests create a minimal monorepo fixture with:
 // - packages/core (symlinked to real @astryxdesign/core for loadDocs compatibility)
@@ -139,31 +138,4 @@ describe('component() with --package option', () => {
     expect(scoped.type).toBe('component.detail.blocks');
     expect(scoped.data).toEqual(unscoped.data);
   });
-
-  // `cwd` is an explicit API input: --blocks must discover from it, as
-  // --showcase does, not from the process working directory.
-  it('--blocks discovers blocks from options.cwd, like --showcase', async () => {
-    const showcase = await component('ProfileCard', {cwd: tmpDir, showcase: true});
-    expect(showcase.data.source).toContain('ProfileCardShowcase');
-
-    const blocks = await component('ProfileCard', {cwd: tmpDir, blocks: true});
-    expect(blocks.type).toBe('component.detail.blocks');
-    expect(blocks.data.showcase?.name).toBe('ProfileCardShowcase');
-  });
-
-  // List and detail report one import for a legacy package component; the
-  // text list projects the JSON value instead of deriving a Core path.
-  it('the names list gives a legacy package component the import its detail reports', async () => {
-    const detail = await component('ProfileCard', {cwd: tmpDir});
-    const list = await component(undefined, {cwd: tmpDir, list: true});
-    const entry = Object.values(list.data.components)
-      .flat()
-      .find(e => e.name === 'ProfileCard' && e.package === '@test/ext');
-    expect(entry?.import).toBe(detail.data.import);
-
-    const text = await runCli(['component', '--list'], tmpDir);
-    expect(text.code).toBe(0);
-    expect(text.stdout).toContain(`name:   ProfileCard\nimport: ${detail.data.import}  [@test/ext]`);
-    expect(text.stdout).not.toMatch(/^import: +@astryxdesign\/core\S* +\[@test\/ext\]$/m);
-  });
 });

package/foundation/response/response-types.doc.mjs

@@ -36,7 +36,7 @@ export const doc = {
     {
       value: 'component.detail',
       description:
-        "One component's authored ComponentDoc plus ownership fields (package, the owner; import, the specifier; sourceAvailable, whether source exists) and parentDoc (present when the component is documented inside another component's doc, naming that doc).",
+        "One component's authored ComponentDoc plus ownership metadata (owner package, import specifier, and whether source is available).",
     },
     {
       value: 'component.detail.props',
@@ -71,7 +71,7 @@ export const doc = {
     {
       value: 'docs.index',
       description:
-        "One topic's section index (--index): the topic's name, title, and description, plus sections, each {id, title, summary} (pass the id as the section argument; summary is the section's one-line summary).",
+        "One topic's section index (--index): each section's key, title, and one-line summary.",
     },
     {
       value: 'docs.detail.section',
@@ -116,7 +116,7 @@ export const doc = {
     {
       value: 'search',
       description:
-        'The echoed query, `matchCount` (total matches, before `limit`), and results, a ranked SearchResultEntry[] bounded by `limit`: each {domain, name, score, reason, description, command}, plus import (components, hooks), title (docs), or displayName and kind (templates).',
+        'The echoed query, `matchCount` (how many candidates matched in total, before `limit`), plus a ranked SearchResultEntry[] bounded by `limit` (domain, name, score, reason, description, follow-up command, and import path where relevant).',
     },
 
     // build
@@ -128,7 +128,7 @@ export const doc = {
     {
       value: 'build.kit',
       description:
-        'The composition kit: echoed query, hasResults, matchCount (total matched, never a cap), directMatch, pages (closest templates), blocks (drop-in patterns) and domain (idea components/hooks) as SearchResultEntry[], frame and foundation name arrays, and hint {reason, commands} when thin.',
+        'The grouped composition kit: echoed query, hasResults/matchCount/directMatch fields (matchCount is the total matched, never a cap read back), the closest page templates, drop-in block patterns, idea-specific components/hooks, and the always-on frame + foundation component-name arrays.',
     },
 
     // swizzle
@@ -151,7 +151,7 @@ export const doc = {
     {
       value: 'gap-report.file',
       description:
-        'An aggregate receipt: overall status, the selected package, issuesUrl (or null), deliveries in handler order, each {handlerType: project | integration | fallback, handler, audience, status, url, message}, and filedCount/routedOnlyCount totals.',
+        'An aggregate receipt with overall status, the selected package and issues URL, ordered per-handler deliveries, and filedCount/routedOnlyCount totals.',
     },
 
     // template
@@ -228,7 +228,7 @@ export const doc = {
     {
       value: 'theme.targets',
       description:
-        'The whole themeable surface: the echoed filter, componentCount, and targets, one per theming target — {key, className, component, props, states, deprecatedFor?}, where props and states are its legal override keys and deprecatedFor names the canonical replacement key.',
+        'The whole themeable surface: the echoed filter, the component count, and one entry per theming target — {key, className, component, props, states}, where props and states are its legal override keys.',
     },
     {
       value: 'theme.palette.generate',
@@ -276,7 +276,7 @@ export const doc = {
     {
       value: 'integration.pack-check',
       description:
-        'The packed-package check: name, version, packable, tarball {filename, fileCount, size, unpackedSize} or null, inventory {manifest, roots [{kind, path, expectedFiles, missingFiles, complete}], expectedFiles, packedFiles}, contributions {local, packed}, each null or {themes [{slug, exportName}], components, templates [{id, type, name}], codemods [{version, id}], docs, agentDocsAppend}, and issues [{code, severity, message}].',
+        'The packed-package check: package identity, tarball facts, local and packed contribution inventories, and issues.',
     },
     {
       value: 'integration.validate',