@ontrails/regrade 1.0.0-beta.39 → 1.0.0-beta.41

package/src/downstream/ast-rewrite.ts

@@ -1,19 +1,18 @@
-import type {
-  AstNode,
-  AstScopeContext,
-  SourceEdit,
-} from '@ontrails/warden/ast';
+import type { AstNode, AstScopeContext, SourceEdit } from '@ontrails/source';
 import {
   applySourceEdits,
   createSourceEdit,
+  extractPlainTemplateLiteral,
+  getNodeCallee,
   getStringValue,
   identifierName,
+  isMemberExpression,
   isStringLiteral,
   offsetToLineColumn,
   parseWithDiagnostics,
   validateSourceEdits,
   walkWithScopeContext,
-} from '@ontrails/warden/ast';
+} from '@ontrails/source';
 import type { GovernedVocabularyTransition } from '@ontrails/warden';
 
 import type {
@@ -23,8 +22,8 @@ import type {
   RegradeReviewDetail,
 } from './report.js';
 
-export interface AstRewriteContext extends AstScopeContext {
-  readonly path: string;
+export interface AstRewriteContext
+  extends AstScopeContext, RegradeClassContext {
   readonly source: string;
 }
 
@@ -179,7 +178,7 @@ export const createAstRewriteClass = (
           ...toArray(
             options.visit(node, {
               ...scopeContext,
-              path: context.path,
+              ...context,
               source,
             })
           )
@@ -233,13 +232,17 @@ export interface AstIdentifierRenameClassOptions {
   readonly describe?: string;
   readonly from: string;
   readonly id?: string;
+  readonly match?: AstIdentifierRenameMatchMode;
   readonly reviewDeclarationTypes?: ReadonlySet<string>;
+  readonly reviewExistingTargetSegments?: readonly string[];
   readonly shouldPreserve?: (
     occurrence: AstIdentifierRenameOccurrence
   ) => boolean;
   readonly to: string;
 }
 
+export type AstIdentifierRenameMatchMode = 'exact' | 'identifier-segment';
+
 export interface AstIdentifierRenameOccurrence {
   readonly end: number;
   readonly from: string;
@@ -250,18 +253,111 @@ export interface AstIdentifierRenameOccurrence {
 }
 
 export interface AstStringLiteralRenameClassOptions {
+  readonly allowModuleSpecifier?: boolean;
   readonly describe?: string;
   readonly from: string;
   readonly id?: string;
+  readonly match?: 'exact' | 'property-key' | 'review';
   readonly shouldPreserve?: (
     occurrence: AstIdentifierRenameOccurrence
   ) => boolean;
+  /** Require the owning manifest to already admit this package route. */
+  readonly targetPackage?: string;
   readonly to: string;
 }
 
+const isEsmModuleSpecifierPosition = (context: AstScopeContext): boolean =>
+  context.key === 'source' &&
+  (context.parent?.type === 'ImportDeclaration' ||
+    context.parent?.type === 'ExportAllDeclaration' ||
+    context.parent?.type === 'ExportNamedDeclaration' ||
+    context.parent?.type === 'ImportExpression' ||
+    context.parent?.type === 'TSImportType');
+
+const isTypeScriptModuleSpecifierPosition = (
+  context: AstScopeContext
+): boolean =>
+  (context.key === 'id' && context.parent?.type === 'TSModuleDeclaration') ||
+  (context.key === 'expression' &&
+    context.parent?.type === 'TSExternalModuleReference');
+
+const memberAccessPath = (node: AstNode | undefined): string | null => {
+  const name = identifierName(node);
+  if (name !== null) {
+    return name;
+  }
+  if (!isMemberExpression(node)) {
+    return null;
+  }
+  const object = memberAccessPath(node.object);
+  const property = identifierName(node.property);
+  return object === null || property === null ? null : `${object}.${property}`;
+};
+
+const MODULE_LOADER_CALLEES = new Set([
+  'Bun.mock.module',
+  'jest.createMockFromModule',
+  'jest.doMock',
+  'jest.genMockFromModule',
+  'jest.mock',
+  'jest.requireActual',
+  'jest.requireMock',
+  'jest.unmock',
+  'mock.module',
+  'require',
+  'require.resolve',
+  'vi.doMock',
+  'vi.doUnmock',
+  'vi.importActual',
+  'vi.importMock',
+  'vi.mock',
+  'vi.unmock',
+]);
+
+const isLoaderModuleSpecifierPosition = (context: AstScopeContext): boolean => {
+  if (
+    context.key !== 'arguments' ||
+    context.parent?.type !== 'CallExpression'
+  ) {
+    return false;
+  }
+
+  const callee = memberAccessPath(getNodeCallee(context.parent));
+  return callee !== null && MODULE_LOADER_CALLEES.has(callee);
+};
+
+const isModuleSpecifierPosition = (context: AstScopeContext): boolean =>
+  isEsmModuleSpecifierPosition(context) ||
+  isTypeScriptModuleSpecifierPosition(context) ||
+  isLoaderModuleSpecifierPosition(context);
+
+const isTargetPackageMissing = (
+  context: AstRewriteContext,
+  targetPackage: string | undefined
+): boolean => {
+  if (targetPackage === undefined || context.package?.name === targetPackage) {
+    return false;
+  }
+  const testSource =
+    context.path.split('/').includes('__tests__') ||
+    /(?:^|\.)(?:test|spec)\.[cm]?[jt]sx?$/.test(
+      context.path.split('/').at(-1) ?? ''
+    );
+  const dependencies = testSource
+    ? context.package?.dependencies
+    : (context.package?.runtimeDependencies ?? context.package?.dependencies);
+  return !dependencies?.includes(targetPackage);
+};
+
 const isIdentifierNamed = (node: AstNode, name: string): boolean =>
   node.type === 'Identifier' && identifierName(node) === name;
 
+const stringLiteralNeedsReview = (
+  match: AstStringLiteralRenameClassOptions['match'],
+  contextKey: AstScopeContext['key']
+): boolean =>
+  match === 'review' || (match === 'property-key' && contextKey !== 'key');
+
 const identifierTokenSpan = (
   node: AstNode,
   source: string,
@@ -273,9 +369,170 @@ const identifierTokenSpan = (
     : null;
 };
 
+const toPascalIdentifierSegment = (value: string): string =>
+  value.length === 0
+    ? value
+    : `${value[0]?.toUpperCase() ?? ''}${value.slice(1)}`;
+
+const isScreamingSnakeIdentifier = (name: string): boolean =>
+  /^[A-Z][A-Z0-9]*(?:_[A-Z0-9]+)*$/.test(name);
+
+const replaceScreamingSnakeIdentifierSegment = (
+  name: string,
+  from: string,
+  to: string
+): string | null => {
+  if (!isScreamingSnakeIdentifier(name)) {
+    return null;
+  }
+
+  const fromSegment = from.toUpperCase();
+  const toSegment = to.toUpperCase();
+  let changed = false;
+  const nextName = name
+    .split('_')
+    .map((segment) => {
+      if (segment !== fromSegment) {
+        return segment;
+      }
+      changed = true;
+      return toSegment;
+    })
+    .join('_');
+
+  return changed ? nextName : null;
+};
+
+const replaceCamelOrPascalIdentifierSegment = (
+  name: string,
+  from: string,
+  to: string
+): string | null => {
+  if (!/^[A-Za-z][A-Za-z0-9]*$/.test(name)) {
+    return null;
+  }
+
+  const fromPascalSegment = toPascalIdentifierSegment(from);
+  const toPascalSegment = toPascalIdentifierSegment(to);
+  const segmentPattern = /[A-Z]+(?=[A-Z][a-z]|$)|[A-Z]?[a-z]+|[0-9]+/g;
+  let cursor = 0;
+  let changed = false;
+  let nextName = '';
+
+  for (const match of name.matchAll(segmentPattern)) {
+    const [segment] = match;
+    const { index } = match;
+    if (index === undefined || index !== cursor) {
+      return null;
+    }
+
+    if (segment === from) {
+      changed = true;
+      nextName += to;
+    } else if (segment === fromPascalSegment) {
+      changed = true;
+      nextName += toPascalSegment;
+    } else {
+      nextName += segment;
+    }
+
+    cursor = index + segment.length;
+  }
+
+  if (cursor !== name.length || !changed) {
+    return null;
+  }
+
+  return nextName;
+};
+
+const deriveIdentifierSegmentTarget = (
+  name: string,
+  from: string,
+  to: string
+): string | null => {
+  const leadingUnderscores = /^_+/.exec(name)?.[0] ?? '';
+  const coreName =
+    leadingUnderscores.length > 0
+      ? name.slice(leadingUnderscores.length)
+      : name;
+  if (coreName.length === 0) {
+    return null;
+  }
+
+  const screamingSnakeTarget = replaceScreamingSnakeIdentifierSegment(
+    coreName,
+    from,
+    to
+  );
+  if (screamingSnakeTarget !== null) {
+    return `${leadingUnderscores}${screamingSnakeTarget}`;
+  }
+
+  const camelOrPascalTarget = replaceCamelOrPascalIdentifierSegment(
+    coreName,
+    from,
+    to
+  );
+  return camelOrPascalTarget === null
+    ? null
+    : `${leadingUnderscores}${camelOrPascalTarget}`;
+};
+
+const hasIdentifierSegment = (name: string, segment: string): boolean =>
+  deriveIdentifierSegmentTarget(name, segment, segment) !== null;
+
+interface AstIdentifierRenameMatch {
+  readonly from: string;
+  readonly span: { readonly end: number; readonly start: number } | null;
+  readonly to: string;
+}
+
+const resolveIdentifierRenameMatch = (
+  node: AstNode,
+  source: string,
+  options: {
+    readonly from: string;
+    readonly match: AstIdentifierRenameMatchMode;
+    readonly to: string;
+  }
+): AstIdentifierRenameMatch | null => {
+  if (options.match === 'exact') {
+    if (!isIdentifierNamed(node, options.from)) {
+      return null;
+    }
+
+    return {
+      from: options.from,
+      span: identifierTokenSpan(node, source, options.from),
+      to: options.to,
+    };
+  }
+
+  if (node.type !== 'Identifier') {
+    return null;
+  }
+
+  const name = identifierName(node);
+  if (name === null) {
+    return null;
+  }
+  const target = deriveIdentifierSegmentTarget(name, options.from, options.to);
+  if (target === null) {
+    return null;
+  }
+
+  return {
+    from: name,
+    span: identifierTokenSpan(node, source, name),
+    to: target,
+  };
+};
+
 export const createAstIdentifierRenameClass = (
   options: AstIdentifierRenameClassOptions
 ): RegradeClass => {
+  const matchMode = options.match ?? 'exact';
   const reviewDeclarationTypes =
     options.reviewDeclarationTypes ?? new Set<string>();
 
@@ -285,20 +542,25 @@ export const createAstIdentifierRenameClass = (
       `Rename identifier "${options.from}" to "${options.to}".`,
     id: options.id ?? `ast-identifier-rename:${options.from}->${options.to}`,
     visit: (node, context) => {
-      if (!isIdentifierNamed(node, options.from)) {
+      const match = resolveIdentifierRenameMatch(node, context.source, {
+        from: options.from,
+        match: matchMode,
+        to: options.to,
+      });
+      if (match === null) {
         return null;
       }
 
-      const span = identifierTokenSpan(node, context.source, options.from);
+      const { span } = match;
       if (span === null) {
         const location = offsetToLineColumn(context.source, node.start);
-        const caution = `Identifier "${options.from}" token span could not be verified; routed to review.`;
+        const caution = `Identifier "${match.from}" token span could not be verified; routed to review.`;
         return {
           detail: {
-            candidateReplacement: options.to,
-            expectedTarget: `Rename identifier "${options.from}" to "${options.to}".`,
+            candidateReplacement: match.to,
+            expectedTarget: `Rename identifier "${match.from}" to "${match.to}".`,
             judgment: 'unresolved',
-            matchedForm: options.from,
+            matchedForm: match.from,
             nodeKind: node.type,
             preserveCautions: [caution],
             reason: 'ast-identifier-token-span-unverified',
@@ -310,7 +572,7 @@ export const createAstIdentifierRenameClass = (
               start: node.start,
             },
             suggestedValidation: 'bun run typecheck',
-            symbol: options.from,
+            symbol: match.from,
           },
           kind: 'review',
           note: caution,
@@ -321,26 +583,60 @@ export const createAstIdentifierRenameClass = (
       if (
         options.shouldPreserve?.({
           end: span.end,
-          from: options.from,
+          from: match.from,
           path: context.path,
           source: context.source,
           start: span.start,
-          to: options.to,
+          to: match.to,
         }) === true
       ) {
         return null;
       }
 
-      const declaration = context.getDeclaration(options.from);
+      const existingTargetSegment = (
+        options.reviewExistingTargetSegments ?? [options.to]
+      ).find((segment) => hasIdentifierSegment(match.from, segment));
+      if (
+        matchMode === 'identifier-segment' &&
+        existingTargetSegment !== undefined
+      ) {
+        const location = offsetToLineColumn(context.source, span.start);
+        const caution = `Identifier "${match.from}" already contains target segment "${existingTargetSegment}"; routed to review.`;
+        return {
+          detail: {
+            candidateReplacement: match.to,
+            expectedTarget: `Review identifier "${match.from}" before replacing "${options.from}" with "${options.to}".`,
+            judgment: 'unresolved',
+            matchedForm: match.from,
+            nodeKind: node.type,
+            preserveCautions: [caution],
+            reason: 'ast-identifier-target-segment-present',
+            signals: ['ast:identifier-rename'],
+            span: {
+              column: location.column,
+              end: span.end,
+              line: location.line,
+              start: span.start,
+            },
+            suggestedValidation: 'bun run typecheck',
+            symbol: match.from,
+          },
+          kind: 'review',
+          note: caution,
+          reason: 'ast-identifier-target-segment-present',
+        };
+      }
+
+      const declaration = context.getDeclaration(match.from);
       if (declaration && reviewDeclarationTypes.has(declaration.type)) {
         const location = offsetToLineColumn(context.source, span.start);
-        const caution = `Identifier "${options.from}" resolves to ${declaration.type}; routed to review.`;
+        const caution = `Identifier "${match.from}" resolves to ${declaration.type}; routed to review.`;
         return {
           detail: {
-            candidateReplacement: options.to,
-            expectedTarget: `Rename identifier "${options.from}" to "${options.to}".`,
+            candidateReplacement: match.to,
+            expectedTarget: `Rename identifier "${match.from}" to "${match.to}".`,
             judgment: 'unresolved',
-            matchedForm: options.from,
+            matchedForm: match.from,
             nodeKind: node.type,
             preserveCautions: [caution],
             reason: 'ast-identifier-review-declaration',
@@ -352,7 +648,7 @@ export const createAstIdentifierRenameClass = (
               start: span.start,
             },
             suggestedValidation: 'bun run typecheck',
-            symbol: options.from,
+            symbol: match.from,
           },
           kind: 'review',
           note: caution,
@@ -360,10 +656,43 @@ export const createAstIdentifierRenameClass = (
         };
       }
 
+      if (
+        context.parent?.type === 'ImportSpecifier' ||
+        context.parent?.type === 'ImportDefaultSpecifier' ||
+        context.parent?.type === 'ImportNamespaceSpecifier' ||
+        context.parent?.type === 'ExportSpecifier'
+      ) {
+        const location = offsetToLineColumn(context.source, span.start);
+        const caution = `Identifier "${match.from}" names an import or export boundary; routed to review.`;
+        return {
+          detail: {
+            candidateReplacement: match.to,
+            expectedTarget: `Review public or foreign identifier "${match.from}" before renaming it to "${match.to}".`,
+            judgment: 'unresolved',
+            matchedForm: match.from,
+            nodeKind: node.type,
+            preserveCautions: [caution],
+            reason: 'ast-identifier-module-boundary',
+            signals: ['ast:identifier-rename'],
+            span: {
+              column: location.column,
+              end: span.end,
+              line: location.line,
+              start: span.start,
+            },
+            suggestedValidation: 'bun run typecheck',
+            symbol: match.from,
+          },
+          kind: 'review',
+          note: caution,
+          reason: 'ast-identifier-module-boundary',
+        };
+      }
+
       return {
-        edit: createSourceEdit(span.start, span.end, options.to),
+        edit: createSourceEdit(span.start, span.end, match.to),
         kind: 'edit',
-        note: `Renamed identifier "${options.from}" to "${options.to}".`,
+        note: `Renamed identifier "${match.from}" to "${match.to}".`,
       };
     },
   });
@@ -383,6 +712,35 @@ const stringLiteralValueSpan = (
   return { end: start + value.length, start };
 };
 
+const isAdjacentModuleRoute = (value: string, route: string): boolean =>
+  value.startsWith(`${route}/`) || value.startsWith(`${route}.`);
+
+interface AstStringLiteralMatch {
+  readonly adjacentModuleRoute: boolean;
+  readonly value: string;
+}
+
+const matchAstStringLiteral = (
+  node: AstNode,
+  options: AstStringLiteralRenameClassOptions
+): AstStringLiteralMatch | null => {
+  if (!isStringLiteral(node) && node.type !== 'TemplateLiteral') {
+    return null;
+  }
+  const value = isStringLiteral(node)
+    ? getStringValue(node)
+    : extractPlainTemplateLiteral(node);
+  if (value === null) {
+    return null;
+  }
+  const adjacentModuleRoute =
+    options.allowModuleSpecifier === true &&
+    isAdjacentModuleRoute(value, options.from);
+  return value === options.from || adjacentModuleRoute
+    ? { adjacentModuleRoute, value }
+    : null;
+};
+
 export const createAstStringLiteralRenameClass = (
   options: AstStringLiteralRenameClassOptions
 ): RegradeClass =>
@@ -393,11 +751,13 @@ export const createAstStringLiteralRenameClass = (
     id:
       options.id ?? `ast-string-literal-rename:${options.from}->${options.to}`,
     visit: (node, context) => {
-      if (!isStringLiteral(node) || getStringValue(node) !== options.from) {
+      const match = matchAstStringLiteral(node, options);
+      if (match === null) {
         return null;
       }
+      const { adjacentModuleRoute, value } = match;
 
-      const span = stringLiteralValueSpan(node, context.source, options.from);
+      const span = stringLiteralValueSpan(node, context.source, value);
       if (span === null) {
         const location = offsetToLineColumn(context.source, node.start);
         const caution = `String literal "${options.from}" token span could not be verified; routed to review.`;
@@ -429,7 +789,7 @@ export const createAstStringLiteralRenameClass = (
       if (
         options.shouldPreserve?.({
           end: span.end,
-          from: options.from,
+          from: value,
           path: context.path,
           source: context.source,
           start: span.start,
@@ -439,6 +799,139 @@ export const createAstStringLiteralRenameClass = (
         return null;
       }
 
+      if (adjacentModuleRoute) {
+        const location = offsetToLineColumn(context.source, node.start);
+        const caution = `Module route "${value}" is adjacent to governed route "${options.from}"; routed to review.`;
+        return {
+          detail: {
+            candidateReplacement: `${options.to}${value.slice(options.from.length)}`,
+            expectedTarget: `Review whether module route "${value}" moves with governed route "${options.from}".`,
+            judgment: 'unresolved',
+            matchedForm: value,
+            nodeKind: node.type,
+            preserveCautions: [caution],
+            reason: 'ast-string-literal-adjacent-module-route',
+            signals: ['ast:string-literal-rename', 'ast:module-specifier'],
+            span: {
+              column: location.column,
+              end: node.end,
+              line: location.line,
+              start: node.start,
+            },
+            suggestedValidation:
+              'Confirm whether the adjacent module route is public, private, or intentionally preserved.',
+            symbol: value,
+          },
+          kind: 'review',
+          note: caution,
+          reason: 'ast-string-literal-adjacent-module-route',
+        };
+      }
+
+      if (
+        options.allowModuleSpecifier !== true &&
+        isModuleSpecifierPosition(context)
+      ) {
+        const location = offsetToLineColumn(context.source, node.start);
+        const caution = `String literal "${options.from}" is a module specifier; routed to review.`;
+        return {
+          detail: {
+            candidateReplacement: options.to,
+            expectedTarget: `Review module route "${options.from}" before renaming it to "${options.to}".`,
+            judgment: 'unresolved',
+            matchedForm: options.from,
+            nodeKind: node.type,
+            preserveCautions: [caution],
+            reason: 'ast-string-literal-module-specifier',
+            signals: ['ast:string-literal-rename', 'ast:module-specifier'],
+            span: {
+              column: location.column,
+              end: node.end,
+              line: location.line,
+              start: node.start,
+            },
+            suggestedValidation:
+              'Confirm the module route is owned by this transition before changing it.',
+            symbol: options.from,
+          },
+          kind: 'review',
+          note: caution,
+          reason: 'ast-string-literal-module-specifier',
+        };
+      }
+
+      if (isTargetPackageMissing(context, options.targetPackage)) {
+        const location = offsetToLineColumn(context.source, node.start);
+        const manifest = context.package?.path ?? 'the owning package.json';
+        const invalidManifest = context.package?.manifestState === 'invalid';
+        const caution = invalidManifest
+          ? `Package manifest ${manifest} is invalid; routed to review before rewriting package route "${options.to}".`
+          : `Package route "${options.to}" is not declared by ${manifest}; routed to review before rewriting source.`;
+        return {
+          detail: {
+            candidateReplacement: options.to,
+            expectedTarget: invalidManifest
+              ? `Fix invalid package manifest ${manifest}, declare "${options.targetPackage}", install dependencies, then rename "${options.from}" to "${options.to}".`
+              : `Declare "${options.targetPackage}" in ${manifest}, install dependencies, then rename "${options.from}" to "${options.to}".`,
+            judgment: 'unresolved',
+            matchedForm: options.from,
+            nodeKind: node.type,
+            preserveCautions: [caution],
+            reason: 'package-route-target-dependency-unverified',
+            signals: [
+              'ast:string-literal-rename',
+              'package:dependency',
+              ...(invalidManifest ? ['package:manifest-invalid'] : []),
+            ],
+            span: {
+              column: location.column,
+              end: node.end,
+              line: location.line,
+              start: node.start,
+            },
+            suggestedValidation: invalidManifest
+              ? 'Repair the package manifest, install dependencies, and run the package typecheck.'
+              : 'Install dependencies and run the package typecheck.',
+            symbol: options.from,
+          },
+          kind: 'review',
+          note: caution,
+          reason: 'package-route-target-dependency-unverified',
+        };
+      }
+
+      if (stringLiteralNeedsReview(options.match, context.key)) {
+        const location = offsetToLineColumn(context.source, node.start);
+        const caution = `String literal "${options.from}" is not proven framework-owned; routed to review.`;
+        return {
+          detail: {
+            candidateReplacement: options.to,
+            expectedTarget: `Review whether string literal "${options.from}" is framework-owned before renaming it to "${options.to}".`,
+            judgment: 'unresolved',
+            matchedForm: options.from,
+            nodeKind: node.type,
+            preserveCautions: [caution],
+            reason: 'ast-string-literal-review-position',
+            signals: [
+              'ast:string-literal-rename',
+              'ast:framework-position-required',
+            ],
+            span: {
+              column: location.column,
+              end: node.end,
+              line: location.line,
+              start: node.start,
+            },
+            suggestedValidation:
+              'Confirm the literal is owned by a Trails contract before changing it.',
+            symbol: options.from,
+          },
+          kind: 'review',
+          note: caution,
+          reason: 'ast-string-literal-review-position',
+        };
+      }
+
       return {
         edit: createSourceEdit(span.start, span.end, options.to),
         kind: 'edit',
@@ -454,28 +947,48 @@ export const createGovernedAstIdentifierRenameClasses = (
       occurrence: AstIdentifierRenameOccurrence
     ) => boolean;
   } = {}
-): readonly RegradeClass[] => [
-  ...transition.symbolRenames.map((rename) =>
-    createAstIdentifierRenameClass({
-      describe: `Rename governed symbol "${rename.from}" to "${rename.to}" for ${transition.id}.`,
-      from: rename.from,
-      id: `ast-symbol-rename:${transition.id}:${rename.from}->${rename.to}`,
-      reviewDeclarationTypes: new Set(rename.reviewDeclarationTypes),
-      ...(options.shouldPreserve === undefined
-        ? {}
-        : { shouldPreserve: options.shouldPreserve }),
-      to: rename.to,
-    })
-  ),
-  ...transition.stringLiteralRenames.map((rename) =>
-    createAstStringLiteralRenameClass({
-      describe: `Rename governed string literal "${rename.from}" to "${rename.to}" for ${transition.id}.`,
-      from: rename.from,
-      id: `ast-string-literal-rename:${transition.id}:${rename.from}->${rename.to}`,
-      ...(options.shouldPreserve === undefined
-        ? {}
-        : { shouldPreserve: options.shouldPreserve }),
-      to: rename.to,
-    })
-  ),
-];
+): readonly RegradeClass[] => {
+  const targetSegments = [
+    ...new Set(transition.symbolRenames.map((rename) => rename.to)),
+  ];
+  const orderedLiteralRenames = [...transition.stringLiteralRenames].toSorted(
+    (left, right) =>
+      right.from.length - left.from.length ||
+      left.from.localeCompare(right.from)
+  );
+
+  return [
+    ...transition.symbolRenames.map((rename) =>
+      createAstIdentifierRenameClass({
+        describe: `Rename governed symbol "${rename.from}" to "${rename.to}" for ${transition.id}.`,
+        from: rename.from,
+        id: `ast-symbol-rename:${transition.id}:${rename.from}->${rename.to}`,
+        match: rename.match,
+        reviewDeclarationTypes: new Set(rename.reviewDeclarationTypes),
+        reviewExistingTargetSegments: targetSegments,
+        ...(options.shouldPreserve === undefined
+          ? {}
+          : { shouldPreserve: options.shouldPreserve }),
+        to: rename.to,
+      })
+    ),
+    ...orderedLiteralRenames.map((rename) =>
+      createAstStringLiteralRenameClass({
+        describe: `Rename governed string literal "${rename.from}" to "${rename.to}" for ${transition.id}.`,
+        from: rename.from,
+        id: `ast-string-literal-rename:${transition.id}:${rename.from}->${rename.to}`,
+        ...(rename.match === undefined ? {} : { match: rename.match }),
+        ...(options.shouldPreserve === undefined
+          ? {}
+          : { shouldPreserve: options.shouldPreserve }),
+        ...(rename.moduleSpecifier === undefined
+          ? {}
+          : {
+              allowModuleSpecifier: true,
+              targetPackage: rename.moduleSpecifier.targetPackage,
+            }),
+        to: rename.to,
+      })
+    ),
+  ];
+};