@astryxdesign/cli 0.7.2-canary.f16dc9f → 0.7.2-canary.fbc03f7

package/api/component/list/list.mjs

@@ -16,6 +16,7 @@ import {
   discoverComponents,
   discoverExternalComponentsGrouped,
   discoverValidIntegrationComponents,
+  familyMember,
   findComponentReadme,
   findExternalComponentDoc,
   resolveImportPath,
@@ -66,6 +67,33 @@ async function legacyImport(ext, name, coreDir, docOpts) {
  */
 const coreEntry = doc => ({name: doc.name, package: CORE_PACKAGE, ...doc});
 
+/**
+ * The full-level entry for a component documented as a member of its family's
+ * doc (VStack in Stack's doc): a component doc built from the member's own
+ * entry, under its own name, display name and import, shaped like every other
+ * full entry. Null when the doc is the component's own.
+ * @param {any} docs
+ * @param {string} name
+ * @param {string} coreDir
+ * @returns {any}
+ */
+function memberEntry(docs, name, coreDir) {
+  const member = familyMember(docs, name);
+  if (!member) return null;
+  return {
+    name,
+    package: CORE_PACKAGE,
+    displayName: member.displayName ?? name,
+    ...(docs.group ? {group: docs.group} : {}),
+    ...(docs.category ? {category: docs.category} : {}),
+    usage: member.usage ?? {description: member.description ?? ''},
+    props: member.props ?? [],
+    ...(member.examples ? {examples: member.examples} : {}),
+    ...(docs.theming ? {theming: docs.theming} : {}),
+    import: resolveImportPath(coreDir, name),
+  };
+}
+
 /**
  * The entry for a Core slot an integration component replaces
  * (spec:AST-035 FR11), at the list's detail level: the replacement's own name,
@@ -177,7 +205,11 @@ export async function componentList(
             entries.push({
               name: comp,
               package: CORE_PACKAGE,
-              description: docs.usage?.description || docs.description || '',
+              description:
+                familyMember(docs, comp)?.description ||
+                docs.usage?.description ||
+                docs.description ||
+                '',
               import: resolveImportPath(coreDir, comp),
             });
           } catch {
@@ -215,7 +247,8 @@ export async function componentList(
         const readme = findComponentReadme(coreDir, comp);
         if (readme && readme.endsWith('.doc.mjs')) {
           try {
-            entries.push(coreEntry(await loadComponentDoc(readme, {zh, lang, dense})));
+            const docs = await loadComponentDoc(readme, {zh, lang, dense});
+            entries.push(memberEntry(docs, comp, coreDir) ?? coreEntry(docs));
           } catch {
             entries.push({name: `XDS${comp}`, package: CORE_PACKAGE, description: ''});
           }
@@ -269,7 +302,11 @@ export async function componentList(
             result[cat].push({
               name: comp,
               package: CORE_PACKAGE,
-              description: docs.usage?.description || docs.description || '',
+              description:
+                familyMember(docs, comp)?.description ||
+                docs.usage?.description ||
+                docs.description ||
+                '',
               import: resolveImportPath(coreDir, comp),
             });
           } catch {
@@ -310,7 +347,8 @@ export async function componentList(
         const readme = findComponentReadme(coreDir, comp);
         if (readme && readme.endsWith('.doc.mjs')) {
           try {
-            result[cat].push(coreEntry(await loadComponentDoc(readme, {zh, lang, dense})));
+            const docs = await loadComponentDoc(readme, {zh, lang, dense});
+            result[cat].push(memberEntry(docs, comp, coreDir) ?? coreEntry(docs));
           } catch {
             result[cat].push({name: `XDS${comp}`, package: CORE_PACKAGE, description: ''});
           }

package/api/integration/pack-check.mjs

@@ -660,11 +660,10 @@ async function validateIncompleteThemeExports(
   const expectedCss = path.join(expectedDir, `${localTheme.slug}.css`);
   try {
     if (outputs.some(output => output.kind !== 'font stylesheet')) {
-      const receipt = await themeBuild(
-        source,
-        {out: expectedCss},
-        {cwd: packageDir},
-      );
+      // The scratch directory is the write root; the package stays the cwd,
+      // so the build selects the package's Core and its paths as before.
+      const scratchBuild = {out: expectedCss, __writeRoot: expectedDir};
+      const receipt = await themeBuild(source, scratchBuild, {cwd: packageDir});
       if (receipt == null || receipt.type !== 'theme.build') {
         throw new Error('the theme build produced no complete receipt');
       }
@@ -847,11 +846,12 @@ async function validatePackedThemeExports(
     );
     const expectedCss = path.join(expectedDir, `${localTheme.slug}.css`);
     try {
-      const receipt = await themeBuild(
-        source,
-        {out: expectedCss},
-        {cwd: localIntegration.__packageDir},
-      );
+      // The scratch directory is the write root; the package stays the cwd,
+      // so the build selects the package's Core and its paths as before.
+      const scratchBuild = {out: expectedCss, __writeRoot: expectedDir};
+      const receipt = await themeBuild(source, scratchBuild, {
+        cwd: localIntegration.__packageDir,
+      });
       if (receipt == null || receipt.type !== 'theme.build') {
         issues.push(
           error(

package/api/search/search.mjs

@@ -85,6 +85,7 @@ import {findCoreDir} from '../../foundation/fs/paths.mjs';
 import {
   discoverComponents,
   discoverValidIntegrationComponents,
+  familyMember,
   findComponentReadme,
   resolveImportPath,
   resolveIntegrationImportPath,
@@ -1079,7 +1080,11 @@ async function gatherCoreComponents(coreDir) {
     /** @type {string[]} */
     let guidance = [];
     if (readme && readme.endsWith('.doc.mjs')) {
-      const doc = await loadModuleDoc(readme);
+      const loaded = await loadModuleDoc(readme);
+      // A member documented in its family's doc (VStack in Stack's doc) is
+      // indexed from its own entry: the family's keywords and guidance
+      // describe the family, not the member.
+      const doc = familyMember(loaded, comp) ?? loaded;
       if (doc) {
         keywords = Array.isArray(doc.keywords) ? doc.keywords : [];
         description = doc.usage?.description || doc.description || '';
@@ -1225,11 +1230,11 @@ export async function componentKeywords(coreDir, cwd) {
     .flat()
     .map(async name => {
       const readme = findComponentReadme(coreDir, name);
-      const doc =
+      const loaded =
         readme && readme.endsWith('.doc.mjs')
           ? await loadModuleDoc(readme)
           : null;
-      return {name, keywords: keywordsOf(doc)};
+      return {name, keywords: keywordsOf(familyMember(loaded, name) ?? loaded)};
     });
   const loadedIntegrations = await loadIntegrationsSafely(cwd);
   const replacements = await loadComponentReplacements(

package/api/search/search.test.mjs

@@ -616,6 +616,42 @@ describe('search leaf — a theme is found by its names; its description is pros
   );
 });
 
+describe('search leaf — components whose docs live in a family folder', () => {
+  it("indexes a family member from its own entry, not the family's keywords", async () => {
+    // HStack and VStack are documented in Stack's doc, whose keywords
+    // (horizontal, vertical, row, column, ...) describe Stack.
+    const reasons = async (/** @type {string} */ query) =>
+      Object.fromEntries(
+        (await search(query, {cwd, type: 'component'})).data.results.map(r => [
+          r.name,
+          r.reason,
+        ]),
+      );
+    const column = await reasons('column');
+    expect(column.HStack ?? '').not.toMatch(/keyword/);
+    expect(column.VStack ?? '').not.toMatch(/keyword/);
+    expect(column.Stack).toMatch(/keyword/);
+    const vertical = (await search('vertical', {cwd, type: 'component'})).data.results.map(
+      r => r.name,
+    );
+    expect(vertical.indexOf('VStack')).toBeGreaterThanOrEqual(0);
+    if (vertical.includes('HStack')) {
+      expect(vertical.indexOf('VStack')).toBeLessThan(vertical.indexOf('HStack'));
+    }
+  }, SLOW);
+
+  it('ranks VStack, HStack and Heading first for their own names, with their own import', async () => {
+    for (const name of ['VStack', 'HStack', 'Heading']) {
+      const r = await search(name.toLowerCase(), {cwd, type: 'component'});
+      expect(r.data.results[0]).toMatchObject({
+        domain: 'component',
+        name,
+        import: `@astryxdesign/core/${name}`,
+      });
+    }
+  }, SLOW);
+});
+
 describe('search leaf — integration components', () => {
   /**
    * A minimal consumer project: a stub `@astryxdesign/core` (so `findCoreDir`

package/api/template/template.test.mjs

@@ -1,7 +1,14 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
 import {describe, it, expect} from 'vitest';
-import {stripTemplateAssetRefs, template} from './template.mjs';
+import {
+  stripTemplateAssetRefs,
+  template,
+  extractComponents,
+} from './template.mjs';
 
 describe('stripTemplateAssetRefs', () => {
   it('replaces a /template-assets image path with an inline data URI', () => {
@@ -31,8 +38,7 @@ describe('stripTemplateAssetRefs', () => {
   });
 
   it('preserves surrounding source structure', () => {
-    const src =
-      "const data = [{src: '/template-assets/x.png', alt: 'X'}];";
+    const src = "const data = [{src: '/template-assets/x.png', alt: 'X'}];";
     const out = stripTemplateAssetRefs(src);
     expect(out).toContain("alt: 'X'");
     expect(out).toContain('const data = [{src:');
@@ -102,4 +108,115 @@ describe('template --skeleton component extraction (prefix-agnostic)', () => {
 
     expect(result.data.skeleton).toContain('columns={{minWidth: 200}}');
   });
+
+  it('filters out local helper components declared in the same file', () => {
+    const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-test-'));
+    const pagePath = path.join(tmpDir, 'page.tsx');
+    fs.writeFileSync(
+      pagePath,
+      `
+import {Card} from '@astryxdesign/core/Layout';
+
+function TimelineSection() {
+  return <div />;
+}
+
+export default function Page() {
+  return (
+    <Card>
+      <TimelineSection />
+    </Card>
+  );
+}
+      `,
+    );
+
+    try {
+      const components = extractComponents(pagePath);
+      expect(components).toContain('Card');
+      expect(components).not.toContain('Timeline');
+    } finally {
+      fs.rmSync(tmpDir, {recursive: true, force: true});
+    }
+  });
+
+  it('filters out a type-annotated local helper', () => {
+    const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-test-'));
+    const pagePath = path.join(tmpDir, 'page.tsx');
+    fs.writeFileSync(
+      pagePath,
+      `
+import type {FC} from 'react';
+import {Card} from '@astryxdesign/core/Layout';
+
+const TimelineSection: FC = () => <div />;
+
+export default function Page() {
+  return (
+    <Card>
+      <TimelineSection />
+    </Card>
+  );
+}
+`,
+    );
+    try {
+      const components = extractComponents(pagePath);
+      expect(components).toContain('Card');
+      expect(components).not.toContain('Timeline');
+    } finally {
+      fs.rmSync(tmpDir, {recursive: true, force: true});
+    }
+  });
+
+  it('keeps an imported component when declaration-like text appears in a comment or string', () => {
+    const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-test-'));
+    const pagePath = path.join(tmpDir, 'page.tsx');
+    fs.writeFileSync(
+      pagePath,
+      `
+import {Card} from '@astryxdesign/core/Layout';
+
+// const Card = () => null;
+const note = 'function Card() {}';
+
+export default function Page() {
+  return <Card>{note}</Card>;
+}
+`,
+    );
+    try {
+      expect(extractComponents(pagePath)).toContain('Card');
+    } finally {
+      fs.rmSync(tmpDir, {recursive: true, force: true});
+    }
+  });
+
+  it('keeps a bare imported component whose name is itself a stripped suffix', () => {
+    const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-test-'));
+    const pagePath = path.join(tmpDir, 'page.tsx');
+    fs.writeFileSync(
+      pagePath,
+      `
+import {Section} from '@astryxdesign/core/Section';
+
+function SectionHeading() {
+  return <div />;
+}
+
+export default function Page() {
+  return (
+    <Section>
+      <SectionHeading />
+    </Section>
+  );
+}
+`,
+    );
+    try {
+      expect(extractComponents(pagePath)).toContain('Section');
+    } finally {
+      fs.rmSync(tmpDir, {recursive: true, force: true});
+    }
+  });
 });

package/api/theme/build/build.family.test.mjs

@@ -252,6 +252,22 @@ describe('themeBuildFamily()', () => {
     expect(fs.existsSync(dtsPath)).toBe(false);
   });
 
+  it('refuses family outputs outside cwd before checking or writing', async () => {
+    const dir = makeDir();
+    const files = writeFamily(dir).map(file => path.join(dir, file));
+    const app = path.join(dir, 'app');
+    fs.mkdirSync(app);
+
+    for (const check of [false, true]) {
+      await expect(
+        themeBuildFamily(files, {familyKey: FAMILY_KEY, check}, {cwd: app}),
+      ).rejects.toMatchObject({code: 'ERR_PATH_TRAVERSAL'});
+    }
+    for (const output of OUTPUTS) {
+      expect(fs.existsSync(path.join(dir, 'themes', output))).toBe(false);
+    }
+  });
+
   it('fails without publishing a mixed trio when staging a write fails', async () => {
     const dir = makeDir();
     const files = writeFamily(dir);

package/api/theme/build/build.mjs

@@ -27,6 +27,8 @@
  * files; an internal callback lets the CLI make only the process status fail.
  * Human progress is emitted through the shared `logger` (silent by default), so
  * the CLI keeps its exact output while a programmatic caller stays quiet.
+ * Every output, explicit or beside the theme file, stays inside `cwd`
+ * (`ERR_PATH_TRAVERSAL` otherwise), in check mode too.
  *
  * The installed `@astryxdesign/core` is an independently versioned optional
  * peer, so it can be older than the CLI. A theme that uses only baseline
@@ -270,6 +272,25 @@ function realOrSelf(file) {
   }
 }
 
+/**
+ * `target` spelled through real directories: the deepest ancestor that exists
+ * is resolved through its symlinks, and the missing rest is appended as given.
+ * @param {string} target absolute path
+ * @returns {string}
+ */
+function realLocation(target) {
+  /** @type {string[]} */
+  const missing = [];
+  let existing = target;
+  while (!fs.existsSync(existing)) {
+    const parent = path.dirname(existing);
+    if (parent === existing) break;
+    missing.unshift(path.basename(existing));
+    existing = parent;
+  }
+  return path.join(realOrSelf(existing), ...missing);
+}
+
 /**
  * The Core the project at `cwd` installed, when it differs from the one the
  * CLI's own import found and loads. The app's `<Theme>` runs on the app's
@@ -506,6 +527,47 @@ function checkedBuildOutputs(writes, cwd) {
     .map(write => path.relative(cwd, write.dest));
 }
 
+/** Remedies that end a confinement error, by where the output path came from. */
+const OUT_REMEDY = 'Pass an --out path inside it.';
+const SOURCE_REMEDY =
+  'Without --out the outputs go beside the theme file, so run the build from a directory that contains the theme file, or pass an --out path inside the working directory.';
+const FAMILY_REMEDY =
+  "Family outputs go beside the family's root theme file, so run the build from a directory that contains it.";
+
+/**
+ * Refuse an output outside `root`: every write is confined, whether `out` names
+ * the path or it defaults to the theme file's directory (architecture:cli-surface
+ * INV10). Both sides are compared by real location, so an absolute path that
+ * reaches the working directory through a symlink is inside it, and a symlink
+ * inside it that leads elsewhere is not.
+ * @param {string} dest absolute output path
+ * @param {string} root the directory writes stay inside: the working directory
+ * @param {string} remedy what to do instead; ends the error message
+ * @param {string} [shown] the path as the caller wrote it, for the message
+ */
+function confineOutput(dest, root, remedy, shown = dest) {
+  try {
+    assertWithin(realLocation(dest), realOrSelf(path.resolve(root)), {
+      allowAbsolute: true,
+      label: 'output path',
+    });
+  } catch (err) {
+    if (!(err instanceof PathSafetyError)) throw err;
+    throw new AstryxError(
+      err.code === ERROR_CODES.ERR_PATH_TRAVERSAL
+        ? `Output path "${shown}" is outside the working directory (${root}). ${remedy}`
+        : err.message,
+      undefined,
+      ERROR_CODES.ERR_PATH_TRAVERSAL,
+    );
+  }
+}
+
+/** @param {Array<{dest: string}>} writes @param {string} root @param {string} remedy */
+function confineOutputs(writes, root, remedy) {
+  for (const write of writes) confineOutput(write.dest, root, remedy);
+}
+
 /** @param {Array<{dest: string, content: string}>} writes */
 function writeBuildOutputs(writes) {
   if (writes.length === 0) return;
@@ -2344,9 +2406,10 @@ function validateHeadingTypeAugmentationSupport(themeDef) {
  * `logger` (silent by default).
  *
  * @param {string} file - Theme file path, resolved against `cwd`.
- * @param {{out?: string, check?: boolean, iconsSpecifier?: string, __prepareFamily?: boolean, __familyLoader?: any, __familyInterception?: any, __onPrivateVarError?: () => void}} [options] -
+ * @param {{out?: string, check?: boolean, iconsSpecifier?: string, __prepareFamily?: boolean, __familyLoader?: any, __familyInterception?: any, __onPrivateVarError?: () => void, __writeRoot?: string}} [options] -
  *   `out` overrides the output CSS path; `check` compares against on-disk outputs
- *   instead of writing. `iconsSpecifier` overrides the icon registry import
+ *   instead of writing. `__writeRoot` replaces `cwd` as the directory every
+ *   output must stay inside, for a CLI-internal scratch build. `iconsSpecifier` overrides the icon registry import
  *   specifier in the generated module (e.g. `./icons.mjs`); when omitted, the
  *   direct registry specifiers from the theme source are emitted unchanged.
  * @param {{cwd?: string}} [ctx]
@@ -2791,25 +2854,14 @@ async function themeBuildInternal(
   // Derive the default CSS name from the theme name so .css/.js/.d.ts
   // share one scheme; an explicit --out still wins.
   const baseName = themeDef.name;
+  // Every write stays inside cwd. A CLI-internal caller that renders into a
+  // scratch directory it creates and removes names that directory instead.
+  const writeRoot = options.__writeRoot ?? cwd;
   let outPath;
   if (options.out) {
+    // Relative or absolute, the explicit output stays inside the write root.
     outPath = path.resolve(cwd, options.out);
-    // Guard: relative paths must not escape cwd via `../`. Absolute paths are
-    // trusted (the user explicitly controls where output goes, like gcc -o).
-    if (!path.isAbsolute(options.out)) {
-      try {
-        assertWithin(options.out, cwd, {label: 'output path'});
-      } catch (err) {
-        if (err instanceof PathSafetyError) {
-          throw new AstryxError(
-            err.message,
-            undefined,
-            ERROR_CODES.ERR_PATH_TRAVERSAL,
-          );
-        }
-        throw err;
-      }
-    }
+    confineOutput(outPath, writeRoot, OUT_REMEDY, options.out);
   } else {
     outPath = path.join(path.dirname(filePath), `${baseName}.css`);
   }
@@ -2905,6 +2957,11 @@ async function themeBuildInternal(
     writes.push({dest: variantDtsPath, content: variantContent});
   }
 
+  // Every output stays inside cwd, including the defaults beside the theme
+  // file. Check mode refuses the same paths, so it never passes outputs that a
+  // build would refuse to write.
+  confineOutputs(writes, writeRoot, options.out ? OUT_REMEDY : SOURCE_REMEDY);
+
   // Check mode: compare generated content against what's on disk instead of
   // writing. A file is "stale" if it's missing or its content differs once the
   // volatile @generated `Command:` line is ignored. Returns a
@@ -3449,6 +3506,8 @@ export async function themeBuildFamily(
     js: path.relative(cwd, jsPath),
     dts: path.relative(cwd, dtsPath),
   };
+  // The family's outputs stay inside cwd too, in check mode as well.
+  confineOutputs(writes, cwd, FAMILY_REMEDY);
   if (options.check) {
     const stale = staleBuildOutputs(writes, cwd);
     const upToDate = stale.length === 0;

package/api/theme/themeBuild.doc.mjs

@@ -58,7 +58,7 @@ export const doc = {
       name: 'options.out',
       type: 'string',
       description:
-        'Override the output CSS path. The .js, .d.ts and any .variants.d.ts are written in the same directory, named after the theme (<name>.js), not after the CSS file. A relative path must stay within cwd.',
+        'Override the output CSS path, relative or absolute; it must resolve inside cwd. The .js, .d.ts and any .variants.d.ts are written in the same directory, named after the theme (<name>.js), not after the CSS file.',
     },
     {
       name: 'options.check',
@@ -77,7 +77,7 @@ export const doc = {
       name: 'ctx.cwd',
       type: 'string',
       description:
-        'Directory the theme file, a relative out path, and the returned output paths resolve against.',
+        'Directory the theme file, a relative out path, and the returned output paths resolve against. Every output is written inside it, including the default outputs beside the theme file.',
       default: 'process.cwd()',
     },
   ],
@@ -105,7 +105,7 @@ export const doc = {
     },
     {
       code: 'ERR_PATH_TRAVERSAL',
-      when: 'the theme name contains a path separator or traversal marker, or a relative `out` path resolves outside cwd (including through a symlink)',
+      when: 'the theme name contains a path separator or traversal marker, or an output resolves outside cwd (including through a symlink): an `out` path, relative or absolute, or the default outputs beside a theme file outside cwd (also rejected in check mode)',
     },
     {
       code: 'ERR_CORE_NOT_FOUND',

package/assets/codemods/transforms/next/__tests__/migrate-list-edge-compensation-to-edge.test.mjs

@@ -0,0 +1,120 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+import {describe, expect, it} from 'vitest';
+import transform from '../migrate-list-edge-compensation-to-edge.mjs';
+
+async function applyTransform(source) {
+  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;
+}
+
+describe('migrate-list-edge-compensation-to-edge', () => {
+  it("renames edgeCompensation='inline' to edge='outset'", async () => {
+    const output =
+      await applyTransform(`import {List, ListItem} from '@astryxdesign/core/List';
+const a = <List edgeCompensation="inline"><ListItem label="a" /></List>;
+const b = <List hasDividers edgeCompensation={'inline'} />;`);
+
+    expect(output).not.toContain('edgeCompensation');
+    expect(output.match(/edge='outset'/g)).toHaveLength(2);
+    expect(output).toContain('hasDividers');
+  });
+
+  it('follows aliases and the package root import', async () => {
+    const output =
+      await applyTransform(`import {List as Rows} from '@astryxdesign/core';
+const a = <Rows edgeCompensation="inline" />;`);
+
+    expect(output).toContain("<Rows edge='outset' />");
+  });
+
+  it('drops edgeCompensation beside an edge string, whatever its value', async () => {
+    const output =
+      await applyTransform(`import {List} from '@astryxdesign/core/List';
+const a = <List edge="bleed" edgeCompensation="inline" />;
+const b = <List edge={'flush'} edgeCompensation={mode} />;
+const c = <List {...rest} edge="padded" edgeCompensation="inline" />;`);
+
+    // c: the spread comes before edge, so it cannot override it.
+    expect(output).toContain('edge="bleed"');
+    expect(output).toContain("edge={'flush'}");
+    expect(output).toContain('edge="padded"');
+    expect(output).not.toContain('edgeCompensation');
+    expect(output).not.toContain('TODO');
+  });
+
+  it('leaves a TODO where edge may be undefined at runtime', async () => {
+    const output =
+      await applyTransform(`import {List} from '@astryxdesign/core/List';
+const a = <List edge={edge} edgeCompensation="inline" />;
+const b = <List edge="flush" {...rest} edgeCompensation="inline" />;
+const c = <List edge={props.edge} edgeCompensation={mode} />;`);
+
+    // a and c: a computed edge falls back to the old prop when undefined.
+    // b: the spread after edge may set it to undefined.
+    expect(output.match(/TODO\(astryx upgrade\)/g)).toHaveLength(3);
+    expect(output.match(/edgeCompensation=/g)).toHaveLength(3);
+    expect(output).toContain('edge={edge}');
+    expect(output).toContain('edge={props.edge}');
+  });
+
+  it('leaves a TODO on a dynamic value and keeps it working', async () => {
+    const output =
+      await applyTransform(`import {List} from '@astryxdesign/core/List';
+const a = <List edgeCompensation={mode} />;
+const b = <List edgeCompensation={flag ? 'inline' : undefined} />;`);
+
+    expect(output.match(/TODO\(astryx upgrade\)/g)).toHaveLength(2);
+    expect(output).toContain('edgeCompensation={mode}');
+    expect(output).toContain("edgeCompensation={flag ? 'inline' : undefined}");
+  });
+
+  it('keeps edgeCompensation with a TODO when the List also spreads props', async () => {
+    const output =
+      await applyTransform(`import {List} from '@astryxdesign/core/List';
+const a = <List {...rest} edgeCompensation="inline" />;
+const b = <List edgeCompensation="inline" {...rest} />;
+const c = <List {...rest} edgeCompensation={mode} />;
+const d = <List {...props} />;
+const e = <List {...rest} edge="padded" />;`);
+
+    // a: an edge in the spread wins today, and a new edge would override
+    // it. b: the spread may override either prop. c: dynamic value and a
+    // spread, one TODO. d: no evidence of the old prop, so unchanged; its
+    // @deprecated type reports a typed use where the props are written.
+    // e: no old prop.
+    expect(output.match(/TODO\(astryx upgrade\)/g)).toHaveLength(3);
+    const code = output.replace(/\/\*[\s\S]*?\*\//g, '');
+    expect(code).not.toContain("edge='outset'");
+    expect(code.match(/edgeCompensation="inline"/g)).toHaveLength(2);
+    expect(output).toContain('edgeCompensation={mode}');
+    expect(output).toContain('const d = <List {...props} />;');
+    expect(output).toContain('edge="padded"');
+  });
+
+  it('leaves other components, other packages, and unrelated spreads alone', async () => {
+    const source = `import {List} from '@astryxdesign/core/List';
+import {TabList} from '@astryxdesign/core/TabList';
+import {List as Other} from 'some-other-package';
+const a = <TabList edgeCompensation="inline" {...props} />;
+const b = <Other edgeCompensation="inline" {...props} />;
+const c = <div {...props} />;`;
+    expect(await applyTransform(source)).toBe(source);
+  });
+
+  it('changes nothing on a second run', async () => {
+    const once =
+      await applyTransform(`import {List} from '@astryxdesign/core/List';
+const a = <List edgeCompensation="inline" />;
+const b = <List edgeCompensation={mode} />;
+const c = <List {...props} edgeCompensation="inline" />;
+const d = <List edge="flush" edgeCompensation="inline" />;
+const e = <List edge={edge} edgeCompensation="inline" />;`);
+    const twice = await applyTransform(once);
+
+    expect(twice).toBe(once);
+    expect(twice.match(/TODO\(astryx upgrade\)/g)).toHaveLength(3);
+  });
+});

package/assets/codemods/transforms/next/index.mjs

@@ -7,4 +7,14 @@
  * this file into the resolved version folder.
  */
 
-export default [];
+import migrateListEdgeCompensationToEdge, {
+  meta as migrateListEdgeCompensationToEdgeMeta,
+} from './migrate-list-edge-compensation-to-edge.mjs';
+
+export default [
+  {
+    name: 'migrate-list-edge-compensation-to-edge',
+    transform: migrateListEdgeCompensationToEdge,
+    meta: migrateListEdgeCompensationToEdgeMeta,
+  },
+];