@ontrails/regrade 0.2.0

package/src/downstream/ast-rewrite.ts

@@ -0,0 +1,1031 @@
+import type { AstNode, AstScopeContext, SourceEdit } from '@ontrails/source';
+import {
+  applySourceEdits,
+  createSourceEdit,
+  extractPlainTemplateLiteral,
+  getNodeCallee,
+  getStringValue,
+  identifierName,
+  isMemberExpression,
+  isStringLiteral,
+  offsetToLineColumn,
+  parseWithDiagnostics,
+  validateSourceEdits,
+  walkWithScopeContext,
+} from '@ontrails/source';
+import type { GovernedVocabularyTransition } from '@ontrails/warden';
+
+import type {
+  RegradeClass,
+  RegradeClassContext,
+  RegradeClassResult,
+  RegradeReviewDetail,
+} from './report.js';
+
+export interface AstRewriteContext
+  extends AstScopeContext, RegradeClassContext {
+  readonly source: string;
+}
+
+export type AstRewriteMatch =
+  | {
+      readonly edit: SourceEdit;
+      readonly kind: 'edit';
+      readonly note?: string;
+    }
+  | {
+      readonly detail?: RegradeReviewDetail;
+      readonly kind: 'review';
+      readonly note?: string;
+      readonly reason: string;
+    };
+
+export type AstRewriteVisitResult =
+  | AstRewriteMatch
+  | AstRewriteMatch[]
+  | null
+  | undefined;
+
+export interface AstRewriteClassOptions {
+  readonly describe: string;
+  readonly id: string;
+  readonly shouldScan?: (context: RegradeClassContext) => boolean;
+  readonly visit: (
+    node: AstNode,
+    context: AstRewriteContext
+  ) => AstRewriteVisitResult;
+}
+
+const defaultRegradeClassContext: RegradeClassContext = {
+  path: '<regrade-source>',
+};
+
+const toArray = (result: AstRewriteVisitResult): readonly AstRewriteMatch[] => {
+  if (result === undefined || result === null) {
+    return [];
+  }
+  return Array.isArray(result) ? result : [result];
+};
+
+const dedupeEdits = (edits: readonly SourceEdit[]): readonly SourceEdit[] => {
+  const seen = new Set<string>();
+  const unique: SourceEdit[] = [];
+
+  for (const edit of edits) {
+    const key = `${edit.start}:${edit.end}:${edit.replacement}`;
+    if (seen.has(key)) {
+      continue;
+    }
+    seen.add(key);
+    unique.push(edit);
+  }
+
+  return unique;
+};
+
+const notesFor = (matches: readonly AstRewriteMatch[]): readonly string[] =>
+  matches.flatMap((match) => {
+    if (match.note) {
+      return [match.note];
+    }
+    if (match.kind === 'review') {
+      return [match.reason];
+    }
+    return [];
+  });
+
+const invalidEditsResult = (error: unknown): RegradeClassResult => ({
+  kind: 'needs-review',
+  notes: [
+    error instanceof Error
+      ? `AST rewrite edits could not be applied: ${error.message}`
+      : 'AST rewrite edits could not be applied.',
+  ],
+  reason: 'ast-rewrite-invalid-edits',
+});
+
+const astRewriteFailureResult = (
+  context: RegradeClassContext,
+  reason: string,
+  error: unknown
+): RegradeClassResult => ({
+  kind: 'needs-review',
+  notes: [
+    error instanceof Error
+      ? `AST rewrite failed for ${context.path}: ${error.message}`
+      : `AST rewrite failed for ${context.path}.`,
+  ],
+  reason,
+});
+
+const reviewDetailsFor = (
+  classId: string,
+  matches: readonly AstRewriteMatch[]
+): readonly RegradeReviewDetail[] | undefined => {
+  const details = matches.flatMap((match) => {
+    if (match.kind !== 'review' || match.detail === undefined) {
+      return [];
+    }
+    return [{ ...match.detail, classId: match.detail.classId ?? classId }];
+  });
+  return details.length === 0 ? undefined : details;
+};
+
+export const createAstRewriteClass = (
+  options: AstRewriteClassOptions
+): RegradeClass => ({
+  apply: (
+    source: string,
+    context: RegradeClassContext = defaultRegradeClassContext
+  ): RegradeClassResult => {
+    if (options.shouldScan) {
+      try {
+        if (!options.shouldScan(context)) {
+          return {
+            kind: 'skipped',
+            notes: ['Skipped by AST rewrite scan-target filtering.'],
+            reason: 'ast-rewrite-scan-target-filtered',
+          };
+        }
+      } catch (error: unknown) {
+        return astRewriteFailureResult(
+          context,
+          'ast-rewrite-scan-target-failed',
+          error
+        );
+      }
+    }
+
+    const parsed = parseWithDiagnostics(context.path, source);
+    if (!parsed.ast || parsed.diagnostics.length > 0) {
+      return {
+        kind: 'needs-review',
+        notes:
+          parsed.diagnostics.length > 0
+            ? parsed.diagnostics.map(
+                (diagnostic) =>
+                  `Could not safely parse ${context.path}: ${diagnostic.message}`
+              )
+            : [`Could not parse ${context.path} for AST rewrite.`],
+        reason: 'ast-rewrite-parse-failed',
+      };
+    }
+
+    const matches: AstRewriteMatch[] = [];
+    try {
+      walkWithScopeContext(parsed.ast, (node, scopeContext) => {
+        matches.push(
+          ...toArray(
+            options.visit(node, {
+              ...scopeContext,
+              ...context,
+              source,
+            })
+          )
+        );
+      });
+    } catch (error: unknown) {
+      return astRewriteFailureResult(
+        context,
+        'ast-rewrite-visitor-failed',
+        error
+      );
+    }
+
+    const reviewMatches = matches.filter((match) => match.kind === 'review');
+    if (reviewMatches.length > 0) {
+      const reviewDetails = reviewDetailsFor(options.id, reviewMatches);
+      return {
+        kind: 'needs-review',
+        notes: notesFor(reviewMatches),
+        reason: reviewMatches[0]?.reason ?? 'ast-rewrite-review-required',
+        ...(reviewDetails === undefined ? {} : { reviewDetails }),
+      };
+    }
+
+    const edits = dedupeEdits(
+      matches.flatMap((match) => (match.kind === 'edit' ? [match.edit] : []))
+    );
+    if (edits.length === 0) {
+      return {
+        kind: 'no-op',
+        notes: ['No AST rewrite matches found.'],
+      };
+    }
+
+    try {
+      validateSourceEdits(edits);
+      return {
+        kind: 'rewrite',
+        nextSource: applySourceEdits(source, edits),
+        notes: notesFor(matches),
+      };
+    } catch (error) {
+      return invalidEditsResult(error);
+    }
+  },
+  describe: options.describe,
+  id: options.id,
+});
+
+export interface AstIdentifierRenameClassOptions {
+  readonly describe?: string;
+  readonly from: string;
+  readonly id?: string;
+  readonly match?: AstIdentifierRenameMatchMode;
+  /** Route every matching identifier to review instead of producing an edit. */
+  readonly reviewAllMatches?: boolean;
+  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;
+  readonly path: string;
+  readonly source: string;
+  readonly start: number;
+  readonly to: string;
+}
+
+export interface AstStringLiteralRenameClassOptions {
+  readonly allowModuleSpecifier?: boolean;
+  readonly describe?: string;
+  readonly from: string;
+  readonly id?: string;
+  readonly match?: 'exact' | 'property-key' | 'review';
+  readonly moduleSpecifierOnly?: boolean;
+  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,
+  name: string
+): { readonly end: number; readonly start: number } | null => {
+  const end = node.start + name.length;
+  return source.slice(node.start, end) === name
+    ? { end, start: node.start }
+    : 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>();
+
+  return createAstRewriteClass({
+    describe:
+      options.describe ??
+      `Rename identifier "${options.from}" to "${options.to}".`,
+    id: options.id ?? `ast-identifier-rename:${options.from}->${options.to}`,
+    visit: (node, context) => {
+      const match = resolveIdentifierRenameMatch(node, context.source, {
+        from: options.from,
+        match: matchMode,
+        to: options.to,
+      });
+      if (match === null) {
+        return null;
+      }
+
+      const { span } = match;
+      if (span === null) {
+        const location = offsetToLineColumn(context.source, node.start);
+        const caution = `Identifier "${match.from}" token span could not be verified; routed to review.`;
+        return {
+          detail: {
+            candidateReplacement: match.to,
+            expectedTarget: `Rename identifier "${match.from}" to "${match.to}".`,
+            judgment: 'unresolved',
+            matchedForm: match.from,
+            nodeKind: node.type,
+            preserveCautions: [caution],
+            reason: 'ast-identifier-token-span-unverified',
+            signals: ['ast:identifier-rename'],
+            span: {
+              column: location.column,
+              end: node.end,
+              line: location.line,
+              start: node.start,
+            },
+            suggestedValidation: 'bun run typecheck',
+            symbol: match.from,
+          },
+          kind: 'review',
+          note: caution,
+          reason: 'ast-identifier-token-span-unverified',
+        };
+      }
+
+      if (options.reviewAllMatches === true) {
+        const location = offsetToLineColumn(context.source, span.start);
+        const caution = `Identifier "${match.from}" is a derived naming candidate; routed to review.`;
+        return {
+          detail: {
+            candidateReplacement: match.to,
+            expectedTarget: `Review identifier "${match.from}" before renaming it to "${match.to}".`,
+            judgment: 'unresolved',
+            matchedForm: match.from,
+            nodeKind: node.type,
+            preserveCautions: [caution],
+            reason: 'ast-identifier-plan-review',
+            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-plan-review',
+        };
+      }
+
+      if (
+        options.shouldPreserve?.({
+          end: span.end,
+          from: match.from,
+          path: context.path,
+          source: context.source,
+          start: span.start,
+          to: match.to,
+        }) === true
+      ) {
+        return null;
+      }
+
+      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 "${match.from}" resolves to ${declaration.type}; routed to review.`;
+        return {
+          detail: {
+            candidateReplacement: match.to,
+            expectedTarget: `Rename identifier "${match.from}" to "${match.to}".`,
+            judgment: 'unresolved',
+            matchedForm: match.from,
+            nodeKind: node.type,
+            preserveCautions: [caution],
+            reason: 'ast-identifier-review-declaration',
+            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-review-declaration',
+        };
+      }
+
+      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, match.to),
+        kind: 'edit',
+        note: `Renamed identifier "${match.from}" to "${match.to}".`,
+      };
+    },
+  });
+};
+
+const stringLiteralValueSpan = (
+  node: AstNode,
+  source: string,
+  value: string
+): { readonly end: number; readonly start: number } | null => {
+  const raw = source.slice(node.start, node.end);
+  const relativeStart = raw.indexOf(value);
+  if (relativeStart === -1 || raw.includes(value, relativeStart + 1)) {
+    return null;
+  }
+  const start = node.start + relativeStart;
+  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 =>
+  createAstRewriteClass({
+    describe:
+      options.describe ??
+      `Rename string literal "${options.from}" to "${options.to}".`,
+    id:
+      options.id ?? `ast-string-literal-rename:${options.from}->${options.to}`,
+    visit: (node, context) => {
+      const match = matchAstStringLiteral(node, options);
+      if (match === null) {
+        return null;
+      }
+      if (
+        options.moduleSpecifierOnly === true &&
+        !isModuleSpecifierPosition(context)
+      ) {
+        return null;
+      }
+      const { adjacentModuleRoute, value } = match;
+
+      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.`;
+        return {
+          detail: {
+            candidateReplacement: options.to,
+            expectedTarget: `Rename string literal "${options.from}" to "${options.to}".`,
+            judgment: 'unresolved',
+            matchedForm: options.from,
+            nodeKind: node.type,
+            preserveCautions: [caution],
+            reason: 'ast-string-literal-token-span-unverified',
+            signals: ['ast:string-literal-rename'],
+            span: {
+              column: location.column,
+              end: node.end,
+              line: location.line,
+              start: node.start,
+            },
+            suggestedValidation: 'bun run typecheck',
+            symbol: options.from,
+          },
+          kind: 'review',
+          note: caution,
+          reason: 'ast-string-literal-token-span-unverified',
+        };
+      }
+
+      if (
+        options.shouldPreserve?.({
+          end: span.end,
+          from: value,
+          path: context.path,
+          source: context.source,
+          start: span.start,
+          to: options.to,
+        }) === true
+      ) {
+        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',
+        note: `Renamed string literal "${options.from}" to "${options.to}".`,
+      };
+    },
+  });
+
+export const createGovernedAstIdentifierRenameClasses = (
+  transition: GovernedVocabularyTransition,
+  options: {
+    readonly shouldPreserve?: (
+      occurrence: AstIdentifierRenameOccurrence
+    ) => boolean;
+  } = {}
+): 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,
+      })
+    ),
+  ];
+};