@astryxdesign/cli 0.7.2-canary.fe2c655 → 0.7.2

package/api/upgrade/status/status.mjs

@@ -10,6 +10,10 @@
  *   - `config_fixable` — DRY-RUN only: the config fails strict validation but a
  *     pending core CONFIG codemod would repair it; preview the fix, don't write.
  *
+ * `no_codemods` and `config_fixable` also carry `cliBehindCore` when the
+ * installed Core is newer than this CLI: the run cannot finish the upgrade, so
+ * neither says it is done, and `logCliBehindCore` names the command that can.
+ *
  * These builders own the exact human progress lines for their path (emitted via
  * the shared `logger`) and return the `upgrade.status` envelope; the caller
  * just returns what they hand back.
@@ -40,13 +44,43 @@ export function statusUpToDate({from, to, agentDocs, registryCompositions}) {
 }
 
 /**
- * No core or integration codemods apply to the requested version range.
- * @param {{from: string, to: string, agentDocs: import('../upgrade.type.mjs').AgentDocsSummary, registryCompositions?: import('../upgrade.type.mjs').RegistryCompositionSummary}} data
+ * The one warning for a CLI older than the installed Core: it has no codemods
+ * for the releases after its own version, and the pinned command does. The
+ * command gets a line of its own, so it copies exactly, whatever quotes or
+ * backticks its arguments carry. On Windows it is written for PowerShell, and
+ * the warning says so.
+ * @param {import('../upgrade.type.mjs').CliBehindCore} cliBehindCore
+ * @param {string} to the installed Core version
+ * @param {string} [platform] the `process.platform` the command was printed
+ *   for, as `quoteCommandArgument` and `commandInFolder` take it
+ */
+export function logCliBehindCore({cliVersion, command}, to, platform = process.platform) {
+  const shell = platform === 'win32' ? ' in PowerShell' : '';
+  logger.warn(
+    `This CLI (${cliVersion}) is older than the installed @astryxdesign/core (${to}): ` +
+      `it has no codemods for releases after ${cliVersion}, so it cannot finish this upgrade. ` +
+      `Run it${shell} with the CLI that matches your Core:`,
+  );
+  logger.warn(`  ${command}`);
+}
+
+/**
+ * No core or integration codemods apply to the requested version range. When
+ * the CLI is older than the installed Core, that only means this CLI has none:
+ * the result carries `cliBehindCore` and the human lines say so.
+ * @param {{from: string, to: string, agentDocs: import('../upgrade.type.mjs').AgentDocsSummary, registryCompositions?: import('../upgrade.type.mjs').RegistryCompositionSummary, cliBehindCore?: import('../upgrade.type.mjs').CliBehindCore | null}} data
  * @returns {import('../upgrade.type.mjs').UpgradeStatusResponse}
  */
-export function statusNoCodemods({from, to, agentDocs, registryCompositions}) {
-  logger.log('[ok] No codemods available for this version range.');
-  logger.log(registryCompositions?.ok === false ? 'Finished with unresolved registry items\n' : 'Done\n');
+export function statusNoCodemods({from, to, agentDocs, registryCompositions, cliBehindCore}) {
+  if (cliBehindCore) logCliBehindCore(cliBehindCore, to);
+  else logger.log('[ok] No codemods available for this version range.');
+  logger.log(
+    registryCompositions?.ok === false
+      ? 'Finished with unresolved registry items\n'
+      : cliBehindCore
+        ? 'Upgrade incomplete\n'
+        : 'Done\n',
+  );
   return {
     type: 'upgrade.status',
     data: {
@@ -55,6 +89,7 @@ export function statusNoCodemods({from, to, agentDocs, registryCompositions}) {
       to,
       agentDocs,
       ...(registryCompositions ? {registryCompositions} : {}),
+      ...(cliBehindCore ? {cliBehindCore} : {}),
     },
   };
 }
@@ -63,10 +98,10 @@ export function statusNoCodemods({from, to, agentDocs, registryCompositions}) {
  * DRY-RUN only: the consumer's astryx.config fails strict validation, but a
  * pending core CONFIG codemod previewed a change that would repair it. Preview
  * the fix + report the exact `--apply` command; integrations are skipped here.
- * @param {{from: string, to: string, configError: string, configCodemods: string[], agentDocs: import('../upgrade.type.mjs').AgentDocsSummary}} data
+ * @param {{from: string, to: string, configError: string, configCodemods: string[], agentDocs: import('../upgrade.type.mjs').AgentDocsSummary, cliBehindCore?: import('../upgrade.type.mjs').CliBehindCore | null}} data
  * @returns {import('../upgrade.type.mjs').UpgradeStatusResponse}
  */
-export function statusConfigFixable({from, to, configError, configCodemods, agentDocs}) {
+export function statusConfigFixable({from, to, configError, configCodemods, agentDocs, cliBehindCore}) {
   const codemodFlags = configCodemods.map(name => `--codemod ${name}`).join(' ');
   const suggestedCommand = `astryx upgrade --from ${from} ${codemodFlags} --apply`;
   const guidance =
@@ -77,7 +112,8 @@ export function statusConfigFixable({from, to, configError, configCodemods, agen
   logger.warn(guidance);
   logger.log(`  ${formatCliCommand(suggestedCommand)}`);
   logger.log('Integrations are skipped in this preview; they will be processed on the --apply run.');
-  logger.log('Dry run complete\n');
+  if (cliBehindCore) logCliBehindCore(cliBehindCore, to);
+  logger.log(cliBehindCore ? 'Upgrade incomplete\n' : 'Dry run complete\n');
   return {
     type: 'upgrade.status',
     data: {
@@ -90,6 +126,7 @@ export function statusConfigFixable({from, to, configError, configCodemods, agen
       message: guidance,
       note: 'Integrations are skipped in this preview; they will be processed on the --apply run.',
       agentDocs,
+      ...(cliBehindCore ? {cliBehindCore} : {}),
     },
   };
 }

package/api/upgrade/upgrade.doc.mjs

@@ -22,7 +22,10 @@ export const doc = {
     'loaded, so they can repair an invalid config. Also updates copied compositions from ' +
     'their install receipts: unchanged files are updated, non-overlapping edits are merged, ' +
     'and conflicts are left untouched. `list` only lists codemods; `registry` only updates ' +
-    'copied compositions.',
+    'copied compositions. Core codemods ship inside the CLI, so a CLI older than the installed ' +
+    'Core has none for the releases after its own version: the result then carries ' +
+    '`cliBehindCore` with the command that runs the same upgrade on the matching CLI.' +
+    " In global mode: in a project, the CLI runs `upgrade` with the project's own CLI, whichever astryx command started it (in a project with no CLI of its own, the one you started); this function runs the codemods of the package it is imported from. With `cwd` outside a project, `list` lists this release's codemods, `registry` finds no copied compositions, and a migration writes nothing and fails with `ERR_VERSION_DETECT`. See {@link namespace:global} and {@link generic:who-answers}.",
   importPath: '@astryxdesign/cli/api',
   signature:
     'upgrade(options?: UpgradeOptions, ctx?: {cwd?: string}): Promise<UpgradeListResponse | UpgradeRegistryResponse | UpgradeStatusResponse | UpgradeRunResponse>',
@@ -118,12 +121,12 @@ export const doc = {
     {
       type: 'upgrade.status',
       description:
-        'A short-circuit outcome (no codemods executed): `up_to_date` (`from` is at/after the installed target and no `force`), `no_codemods` (none apply to the range), or `config_fixable` (dry-run preview that a pending config codemod would repair an invalid astryx.config). up_to_date and no_codemods carry the agent-docs summary and, when receipts are found, the copied-composition summary; config_fixable carries configError, configCodemods, suggestedCommand, message, note, and the agent-docs summary.',
+        'A short-circuit outcome (no codemods executed): `up_to_date` (`from` is at/after the installed target and no `force`), `no_codemods` (none apply to the range), or `config_fixable` (dry-run preview that a pending config codemod would repair an invalid astryx.config). up_to_date and no_codemods carry the agent-docs summary and, when receipts are found, the copied-composition summary; config_fixable carries configError, configCodemods, suggestedCommand, message, note, and the agent-docs summary. When the installed Core is newer than the CLI, no_codemods and config_fixable also carry cliBehindCore ({cliVersion, command}): this CLI has no codemods for the releases after cliVersion, and command runs the same upgrade with the CLI release that matches the installed Core.',
     },
     {
       type: 'upgrade.run',
       description:
-        'The terminal run receipt: from, to, codemods (count), integrations, agentDocs, agentDocsRefreshed, registryCompositions (when receipts are found), sourcePathFound (false when the resolved `path` does not exist, so nothing was scanned), filesChanged, transformsApplied, modifiedFiles, protectedFiles, declinedCandidates, errors, and complete. When a protected file still requires a change, complete is false and errorCode is ERR_CODEMOD_PROTECTED; the CLI exits nonzero while preserving the structured receipt.',
+        'The terminal run receipt: from, to, codemods (count), integrations, agentDocs, agentDocsRefreshed, registryCompositions (when receipts are found), sourcePathFound (false when the resolved `path` does not exist, so nothing was scanned), filesChanged, transformsApplied, modifiedFiles, protectedFiles, declinedCandidates, errors, and complete. When a protected file still requires a change, complete is false and errorCode is ERR_CODEMOD_PROTECTED; the CLI exits nonzero while preserving the structured receipt. When the installed Core is newer than the CLI, it also carries cliBehindCore ({cliVersion, command}): codemods for the releases after cliVersion did not run, and command runs the same upgrade with the matching CLI.',
     },
   ],
   throws: [

package/api/upgrade/upgrade.mjs

@@ -26,6 +26,7 @@ import {registryUpgrade} from './registry/registry.mjs';
 import {run} from './run/run.mjs';
 import {isValidSemver} from '../../foundation/env/semver.mjs';
 import {getCliInvocation} from '../../foundation/env/package-manager.mjs';
+import {isOutsideProject} from '../../foundation/env/project-scope.mjs';
 import {ERROR_CODES} from '../../foundation/response/error-codes.mjs';
 import {AstryxError} from '../error.mjs';
 import {logger} from '../logger.mjs';
@@ -91,7 +92,10 @@ export async function upgrade(options = {}, {cwd = process.cwd()} = {}) {
   }
 
   if (!options.list && !options.from) {
-    const msg = `Missing required --from. Install the target version first, then run \`${getCliInvocation()} upgrade --from <old-version>\`.`;
+    // Outside a project there is no version to install (spec AST-081 FR3).
+    const msg = isOutsideProject(cwd)
+      ? 'Missing required --from. This folder is outside a project; upgrade migrates the code of an app project that installs @astryxdesign/core.'
+      : `Missing required --from. Install the target version first, then run \`${getCliInvocation()} upgrade --from <old-version>\`.`;
     logger.error(msg);
     logger.log('Aborted\n');
     throw new AstryxError(msg, undefined, ERROR_CODES.ERR_INVALID_ARGUMENT);

package/api/upgrade/upgrade.type.d.mts

@@ -160,6 +160,22 @@ export type ProtectedCodemodFile = {
      */
     commands: string[];
 };
+/**
+ * Present only when the installed `@astryxdesign/core` (the response's `to`) is
+ * newer than the running CLI. Core codemods ship inside the CLI, so this CLI
+ * has none for the releases after `cliVersion`: the run could not migrate them,
+ * whatever else the response reports.
+ */
+export type CliBehindCore = {
+    /**
+     * The running CLI's version, the last release it has codemods for.
+     */
+    cliVersion: string;
+    /**
+     * The same upgrade, run with the CLI release that matches the installed Core. It first changes to the folder this run used, then names the directory this run scanned as an absolute `--path`, both with symbolic links resolved, so pasted from any folder it finds the same Core and scans the same directory. It is written for a POSIX shell (sh, bash, zsh), or for PowerShell on Windows, with each argument quoted for that shell; cmd.exe is not a target.
+     */
+    command: string;
+};
 /**
  * astryx --json upgrade [--apply]
  */
@@ -190,6 +206,7 @@ export type UpgradeRunResponse = {
             codemod: string;
             error: string;
         }[] | undefined;
+        cliBehindCore?: CliBehindCore | undefined;
     };
 };
 /**
@@ -202,6 +219,10 @@ export type UpgradeRunResponse = {
  *   range) would repair it. The dry run previews the fix without writing and
  *   reports the exact command to apply it; integrations are skipped for the
  *   preview (they will be processed on the `--apply` run).
+ *
+ * `no_codemods` and `config_fixable` carry `cliBehindCore` when the installed
+ * Core is newer than this CLI; `no_codemods` then means only that this CLI has
+ * no codemods for the range.
  */
 export type UpgradeStatusResponse = {
     type: "upgrade.status";
@@ -217,6 +238,7 @@ export type UpgradeStatusResponse = {
         to: string;
         agentDocs: AgentDocsSummary;
         registryCompositions?: RegistryCompositionSummary;
+        cliBehindCore?: CliBehindCore;
     } | {
         status: "config_fixable";
         from: string;
@@ -227,6 +249,7 @@ export type UpgradeStatusResponse = {
         message: string;
         note: string;
         agentDocs: AgentDocsSummary;
+        cliBehindCore?: CliBehindCore;
     };
 };
 /**

package/api/upgrade/upgrade.type.mjs

@@ -106,6 +106,16 @@
  * @property {string[]} commands Exact regeneration commands found in generated headers, when present.
  */
 
+/**
+ * Present only when the installed `@astryxdesign/core` (the response's `to`) is
+ * newer than the running CLI. Core codemods ship inside the CLI, so this CLI
+ * has none for the releases after `cliVersion`: the run could not migrate them,
+ * whatever else the response reports.
+ * @typedef {object} CliBehindCore
+ * @property {string} cliVersion The running CLI's version, the last release it has codemods for.
+ * @property {string} command The same upgrade, run with the CLI release that matches the installed Core. It first changes to the folder this run used, then names the directory this run scanned as an absolute `--path`, both with symbolic links resolved, so pasted from any folder it finds the same Core and scans the same directory. It is written for a POSIX shell (sh, bash, zsh), or for PowerShell on Windows, with each argument quoted for that shell; cmd.exe is not a target.
+ */
+
 /**
  * astryx --json upgrade [--apply]
  * @typedef {object} UpgradeRunResponse
@@ -127,6 +137,7 @@
  * @property {Array<{file: string, location?: string, reason: string}>} [data.declinedCandidates] Candidates left unchanged because proof was insufficient.
  * @property {number} [data.transformsApplied] Total codemod changes. A code or config codemod counts once for each file it changed, so one file changed by four of them counts four times; a project codemod counts once, however many files it writes.
  * @property {Array<{file: string, codemod: string, error: string}>} [data.errors] Per-codemod errors, when any codemod failed.
+ * @property {CliBehindCore} [data.cliBehindCore] Present only when the installed Core is newer than this CLI: codemods for the releases after `cliBehindCore.cliVersion` did not run.
  */
 
 /**
@@ -140,9 +151,13 @@
  *   reports the exact command to apply it; integrations are skipped for the
  *   preview (they will be processed on the `--apply` run).
  *
+ * `no_codemods` and `config_fixable` carry `cliBehindCore` when the installed
+ * Core is newer than this CLI; `no_codemods` then means only that this CLI has
+ * no codemods for the range.
+ *
  * @typedef {object} UpgradeStatusResponse
  * @property {'upgrade.status'} type
- * @property {{status: 'up_to_date', from: string, to: string, agentDocs: AgentDocsSummary, registryCompositions?: RegistryCompositionSummary} | {status: 'no_codemods', from: string, to: string, agentDocs: AgentDocsSummary, registryCompositions?: RegistryCompositionSummary} | {status: 'config_fixable', from: string, to: string, configError: string, configCodemods: string[], suggestedCommand: string, message: string, note: string, agentDocs: AgentDocsSummary}} data
+ * @property {{status: 'up_to_date', from: string, to: string, agentDocs: AgentDocsSummary, registryCompositions?: RegistryCompositionSummary} | {status: 'no_codemods', from: string, to: string, agentDocs: AgentDocsSummary, registryCompositions?: RegistryCompositionSummary, cliBehindCore?: CliBehindCore} | {status: 'config_fixable', from: string, to: string, configError: string, configCodemods: string[], suggestedCommand: string, message: string, note: string, agentDocs: AgentDocsSummary, cliBehindCore?: CliBehindCore}} data
  */
 
 /**

package/assets/codemods/__tests__/registry.test.mjs

@@ -31,6 +31,7 @@ describe('registry', () => {
         '0.6.4',
         '0.6.7',
         '0.7.0',
+        '0.7.2',
       ]);
     });
   });

package/assets/codemods/registry.mjs

@@ -32,6 +32,7 @@ const registry = new Map([
   ['0.6.4', () => import('./transforms/v0.6.4/index.mjs')],
   ['0.6.7', () => import('./transforms/v0.6.7/index.mjs')],
   ['0.7.0', () => import('./transforms/v0.7.0/index.mjs')],
+  ['0.7.2', () => import('./transforms/v0.7.2/index.mjs')],
 ]);
 
 // Re-export from the shared utility so registry callers and other consumers

package/assets/codemods/runner.mjs

@@ -418,6 +418,7 @@ async function runProjectCodemod(
  * @param {boolean} [options.silent] - Suppress all human-facing output (for --json)
  * @param {string} [options.root] - Project root a project codemod reads (default: the process cwd)
  * @param {{root: string, classify: (file: string) => import('../../foundation/fs/file-protection.mjs').FileProtection[]}} [options.protection] - Preloaded protection resolver
+ * @param {boolean} [options.coversTarget] - False when these codemods stop before the installed target (the CLI is older than Core), so a run with no changes does not say the code is up to date. Default true.
  * @returns {Promise<{totalFilesChanged: number, totalTransformsApplied: number, totalValidationBlocked: number, changedFiles: string[], writtenFiles: string[], stagedContents: Map<string, string>, protectedFiles: import('../../authoring/codemod/type').CodemodRunResult['protectedFiles'], errors: Array<{file: string, codemod: string, error: string}>, skippedOptional: Array<{name: string, meta: {title: string, description?: string, fileExtensions?: string[], codemodType?: string}, version: string}>} | {ok: false, reason: string, resolvedPath: string}>}
  */
 export async function runCodemods(
@@ -430,6 +431,7 @@ export async function runCodemods(
     silent = false,
     root = process.cwd(),
     protection: providedProtection,
+    coversTarget = true,
   },
 ) {
   // No-op stub object so silent mode skips log output entirely without
@@ -643,7 +645,11 @@ export async function runCodemods(
     errors.length === 0 &&
     protectedFiles.length === 0
   ) {
-    log.success('No changes needed — your code is already up to date!');
+    // Codemods that stop before the installed target cannot vouch for the
+    // code; the caller says what is missing.
+    if (coversTarget) {
+      log.success('No changes needed — your code is already up to date!');
+    }
   } else if (apply && protectedFiles.length > 0) {
     log.warn(
       `Applied ${totalTransformsApplied} owned change${totalTransformsApplied === 1 ? '' : 's'} across ${totalFilesChanged} file${totalFilesChanged === 1 ? '' : 's'}; protected changes remain.`,

package/assets/codemods/transforms/v0.7.2/__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/v0.7.2/index.mjs

@@ -0,0 +1,20 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file next transform manifest
+ *
+ * Staged codemods for the next release. The Version Packages PR promotes
+ * this file into the resolved version folder.
+ */
+
+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/v0.7.2/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'});
+}