@astryxdesign/cli 0.7.2-canary.db3a2e7 → 0.7.2-canary.ebcc404

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,
+  },
+];

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

@@ -0,0 +1,198 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Codemod: migrate List edgeCompensation to edge
+ *
+ * `edgeCompensation="inline"` on an imported `List` becomes `edge="outset"`,
+ * the value it already resolves to. List resolves
+ * `edge ?? (edgeCompensation === 'inline' ? 'outset' : 'padded')`, so `edge`
+ * wins only when it has a value. The deprecated prop is removed beside an
+ * `edge` string that no later spread can override; beside a computed `edge`,
+ * which may be undefined at runtime, it gets a TODO instead.
+ *
+ * Built on the shared `transformProp` helper, so it does not follow
+ * variables, helpers, wrappers, or types. Where a List writes
+ * `edgeCompensation` but the codemod cannot prove the result, it keeps the
+ * old prop and leaves a TODO instead of guessing: on a dynamic value, and
+ * wherever the List also spreads props. A spread before the old prop may
+ * carry an `edge` that wins today and that a new `edge` would override; one
+ * after it may override either prop. A spread onto a List that never writes
+ * `edgeCompensation` is not evidence of use, so it stays unchanged
+ * (`spec:AST-040` FR1): the deprecated prop keeps working through it, and
+ * its `@deprecated` type reports a typed use where the props are written.
+ * Comments are the codemod's only report channel (`api.report` is a stub),
+ * and each is added once, so a second run changes nothing.
+ */
+
+import {transformProp} from '../../transform-prop.mjs';
+
+export const meta = {
+  title: 'Migrate List edgeCompensation to edge',
+  description:
+    'Renames `edgeCompensation="inline"` to `edge="outset"` on List, and ' +
+    'drops `edgeCompensation` beside an `edge` string. Keeps the old prop ' +
+    'with a TODO where `edge` is computed or a later spread may override ' +
+    'it, on a dynamic value, and where the List also spreads props; the ' +
+    'deprecated prop still works there.',
+};
+
+const OLD_NAME = 'edgeCompensation';
+const NEW_NAME = 'edge';
+const CORE_IMPORT_RE = /^@(astryxdesign|xds)\/core(?:\/|$)/;
+
+const COMPONENT_PROPS = new Map([['List', new Set([OLD_NAME])]]);
+
+const DYNAMIC_COMMENT =
+  ' TODO(astryx upgrade): edgeCompensation is deprecated. Replace ' +
+  'edgeCompensation="inline" with edge="outset" by hand; this value is ' +
+  'computed. ';
+const BOTH_SET_COMMENT =
+  ' TODO(astryx upgrade): edgeCompensation is deprecated. edge is also set ' +
+  'here, but it may be undefined, and then edgeCompensation still applies. ' +
+  'Make edge default to "outset" where edgeCompensation is "inline", then ' +
+  'remove edgeCompensation. ';
+const SPREAD_COMMENT =
+  ' TODO(astryx upgrade): edgeCompensation is deprecated, but this List ' +
+  'also spreads props that may set edge, so it was left unchanged. Replace ' +
+  'edgeCompensation="inline" with edge="outset" by hand, after checking ' +
+  'which edge the spread passes. ';
+
+const TYPE_WRAPPERS = new Set([
+  'TSAsExpression',
+  'TSSatisfiesExpression',
+  'TSTypeAssertion',
+  'TSNonNullExpression',
+  'TypeCastExpression',
+  'ParenthesizedExpression',
+]);
+
+/** @param {any} node */
+function unwrap(node) {
+  let current = node;
+  while (current && TYPE_WRAPPERS.has(current.type)) {
+    current = current.expression;
+  }
+  return current;
+}
+
+/** @param {any} node */
+function isStringLiteral(node) {
+  const value = unwrap(node);
+  return (
+    value != null &&
+    (value.type === 'StringLiteral' || value.type === 'Literal') &&
+    typeof value.value === 'string'
+  );
+}
+
+/**
+ * The value of a JSX attribute: the string of `edge="flush"`, or the
+ * expression inside `edge={...}`.
+ * @param {any} attribute
+ */
+function attributeValue(attribute) {
+  return attribute.value?.type === 'JSXExpressionContainer'
+    ? attribute.value.expression
+    : attribute.value;
+}
+
+/** @param {any} node */
+function isInlineLiteral(node) {
+  const value = unwrap(node);
+  return (
+    value != null &&
+    (value.type === 'StringLiteral' || value.type === 'Literal') &&
+    value.value === 'inline'
+  );
+}
+
+/**
+ * Attach a comment to a node once, so re-running the codemod adds nothing.
+ * @param {any} j @param {any} node @param {string} text
+ */
+function addComment(j, node, text) {
+  node.comments ??= [];
+  if (node.comments.some((/** @type {any} */ c) => c.value === text)) {
+    return false;
+  }
+  node.comments.push(j.commentBlock(text, true, false));
+  return true;
+}
+
+/** @param {any} attributes */
+function firstSpread(attributes) {
+  return attributes.find(
+    (/** @type {any} */ attribute) => attribute.type === 'JSXSpreadAttribute',
+  );
+}
+
+/**
+ * @param {import('../../../../authoring/codemod/type').AstryxCodemodFile} file
+ * @param {import('../../../../authoring/codemod/type').CodemodTransformApi} api
+ * @returns {string | null | undefined}
+ */
+export default function transformer(file, api) {
+  const j = api.jscodeshift;
+  const root = j(file.source);
+  let hasChanges = false;
+
+  transformProp(
+    root,
+    j,
+    {
+      matchesImport: source => CORE_IMPORT_RE.test(source),
+      components: COMPONENT_PROPS,
+    },
+    propPath => {
+      const opening = propPath.parent?.node;
+      const attributes = opening?.attributes ?? [];
+      const prop = propPath.node;
+      const edgeIndex = attributes.findIndex(
+        (/** @type {any} */ attribute) =>
+          attribute.type === 'JSXAttribute' &&
+          attribute.name?.name === NEW_NAME,
+      );
+      if (edgeIndex !== -1) {
+        // `edge` wins only when it has a value. A string that no later
+        // spread can override always does, so the old prop is inert and
+        // removing it changes nothing. A computed `edge` may be undefined,
+        // and then the old prop still decides.
+        const isProven =
+          isStringLiteral(attributeValue(attributes[edgeIndex])) &&
+          !attributes
+            .slice(edgeIndex + 1)
+            .some(
+              (/** @type {any} */ attribute) =>
+                attribute.type === 'JSXSpreadAttribute',
+            );
+        if (isProven) {
+          opening.attributes = attributes.filter(
+            (/** @type {any} */ attribute) => attribute !== prop,
+          );
+          hasChanges = true;
+        } else {
+          hasChanges = addComment(j, prop, BOTH_SET_COMMENT) || hasChanges;
+        }
+        return;
+      }
+      // With a spread on the element the rename cannot be proven: a spread
+      // before the old prop may carry an `edge` that wins today and that a
+      // new `edge` would override, and one after it may override either
+      // prop. The old prop keeps working, so it stays, with a TODO.
+      if (firstSpread(attributes)) {
+        hasChanges = addComment(j, prop, SPREAD_COMMENT) || hasChanges;
+        return;
+      }
+      if (isInlineLiteral(attributeValue(prop))) {
+        prop.name.name = NEW_NAME;
+        prop.value = j.stringLiteral('outset');
+        hasChanges = true;
+      } else {
+        hasChanges = addComment(j, prop, DYNAMIC_COMMENT) || hasChanges;
+      }
+    },
+  );
+
+  if (!hasChanges) return undefined;
+  return root.toSource({quote: 'single'});
+}