@cosmicdrift/kumiko-framework 0.367.0 → 0.369.0

package/src/scripts/codemod/feature-factory.ts

@@ -0,0 +1,429 @@
+#!/usr/bin/env bun
+// feature-factory — the bundled-feature constants (`tagsFeature`, ...) became factories
+// (`createTagsFeature()`); the constants stay as deprecated aliases for one release.
+//
+// Usage:
+//   bun scripts/codemod/feature-factory.ts <targetDir...> [--check | --dry-run | --write] [--no-format]
+// Without a mode flag it writes (kumiko-upgrade --apply calls it that way). --check exits 1
+// while any rewritable or manual site is left; --dry-run only reports.
+
+import {
+  type ImportDeclaration,
+  type ImportSpecifier,
+  Node,
+  Project,
+  type SourceFile,
+  SyntaxKind,
+} from "ts-morph";
+import {
+  type CodemodResult,
+  type CodemodSite,
+  hasImportBinding,
+  removeNamedImport,
+  runCodemodCli,
+  type SiteLists,
+  sourceRelativeModule,
+} from "./codemod-support.js";
+
+export interface FeatureFactoryEntry {
+  readonly factory: string;
+  readonly folder: string;
+}
+
+const BUNDLED_PACKAGE = "@cosmicdrift/kumiko-bundled-features";
+const BUNDLED_SRC_MARKER = "/packages/bundled-features/src/";
+
+// fileProviderS3EnvFeature is not listed: s3-imports.ts folds it into createFileProviderS3Feature.
+export const FEATURE_FACTORIES: Readonly<Record<string, FeatureFactoryEntry>> = {
+  authFoundationFeature: { factory: "createAuthFoundationFeature", folder: "auth-foundation" },
+  authMfaUserDataFeature: {
+    factory: "createAuthMfaUserDataFeature",
+    folder: "auth-mfa-user-data",
+  },
+  billingFoundationFeature: {
+    factory: "createBillingFoundationFeature",
+    folder: "billing-foundation",
+  },
+  capCounterFeature: { factory: "createCapCounterFeature", folder: "cap-counter" },
+  complianceProfilesOpsFeature: {
+    factory: "createComplianceProfilesOpsFeature",
+    folder: "compliance-profiles-ops",
+  },
+  customFieldsFeature: { factory: "createCustomFieldsFeature", folder: "custom-fields" },
+  derivativesSharpFeature: {
+    factory: "createDerivativesSharpFeature",
+    folder: "derivatives-sharp",
+  },
+  documentIngestFoundationFeature: {
+    factory: "createDocumentIngestFoundationFeature",
+    folder: "document-ingest-foundation",
+  },
+  fileDerivativesFeature: {
+    factory: "createFileDerivativesFeature",
+    folder: "file-derivatives",
+  },
+  fileFoundationFeature: { factory: "createFileFoundationFeature", folder: "file-foundation" },
+  fileProviderInMemoryFeature: {
+    factory: "createFileProviderInMemoryFeature",
+    folder: "file-provider-inmemory",
+  },
+  fileProviderS3Feature: { factory: "createFileProviderS3Feature", folder: "file-provider-s3" },
+  foldersFeature: { factory: "createFoldersFeature", folder: "folders" },
+  foldersUserDataFeature: {
+    factory: "createFoldersUserDataFeature",
+    folder: "folders-user-data",
+  },
+  formDraftFeature: { factory: "createFormDraftFeature", folder: "form-draft" },
+  formDraftUserDataFeature: {
+    factory: "createFormDraftUserDataFeature",
+    folder: "form-draft-user-data",
+  },
+  inboundMailFoundationFeature: {
+    factory: "createInboundMailFoundationFeature",
+    folder: "inbound-mail-foundation",
+  },
+  inboundProviderImapFeature: {
+    factory: "createInboundProviderImapFeature",
+    folder: "inbound-provider-imap",
+  },
+  inboundProviderInMemoryFeature: {
+    factory: "createInboundProviderInMemoryFeature",
+    folder: "inbound-provider-inmemory",
+  },
+  ledgerFeature: { factory: "createLedgerFeature", folder: "ledger" },
+  mailFoundationFeature: { factory: "createMailFoundationFeature", folder: "mail-foundation" },
+  mailTransportInMemoryFeature: {
+    factory: "createMailTransportInMemoryFeature",
+    folder: "mail-transport-inmemory",
+  },
+  mailTransportSmtpFeature: {
+    factory: "createMailTransportSmtpFeature",
+    folder: "mail-transport-smtp",
+  },
+  notesHistoryFeature: { factory: "createNotesHistoryFeature", folder: "notes-history" },
+  notesHistoryUserDataFeature: {
+    factory: "createNotesHistoryUserDataFeature",
+    folder: "notes-history-user-data",
+  },
+  readinessFeature: { factory: "createReadinessFeature", folder: "readiness" },
+  tagsFeature: { factory: "createTagsFeature", folder: "tags" },
+  templateResolverUserDataFeature: {
+    factory: "createTemplateResolverUserDataFeature",
+    folder: "template-resolver-user-data",
+  },
+  tenantSettingsFeature: { factory: "createTenantSettingsFeature", folder: "tenant-settings" },
+  tierEngineFeature: { factory: "createTierEngineFeature", folder: "tier-engine" },
+  workflowRunnerFeature: { factory: "createWorkflowRunnerFeature", folder: "workflow-runner" },
+};
+
+const CHEAP_PREFILTER = new RegExp(`\\b(${Object.keys(FEATURE_FACTORIES).join("|")})\\b`);
+const SKIPPED_PATH_SUFFIXES: readonly string[] = [
+  "packages/framework/src/scripts/codemod/feature-factory.ts",
+  "packages/framework/src/__tests__/feature-factory-codemod.test.ts",
+];
+
+const IDENTITY_OPERATORS: ReadonlySet<SyntaxKind> = new Set([
+  SyntaxKind.EqualsEqualsToken,
+  SyntaxKind.EqualsEqualsEqualsToken,
+  SyntaxKind.ExclamationEqualsToken,
+  SyntaxKind.ExclamationEqualsEqualsToken,
+]);
+// Identity-comparing calls: a fresh factory result never matches the instance it is compared to.
+const IDENTITY_METHODS: ReadonlySet<string> = new Set([
+  "toBe",
+  "toContain",
+  "includes",
+  "indexOf",
+  "lastIndexOf",
+  "has",
+]);
+
+function bundledModuleFolder(specifier: string, filePath: string): string | undefined {
+  if (specifier.startsWith(`${BUNDLED_PACKAGE}/`))
+    return specifier.slice(BUNDLED_PACKAGE.length + 1);
+  const relativeModule = sourceRelativeModule(specifier, filePath, BUNDLED_SRC_MARKER);
+  return relativeModule?.module.replace(/\/(feature|index)$/, "");
+}
+
+function isIdentityUse(reference: Node): boolean {
+  const parent = reference.getParent();
+  if (Node.isBinaryExpression(parent)) {
+    return IDENTITY_OPERATORS.has(parent.getOperatorToken().getKind());
+  }
+  if (!Node.isCallExpression(parent) || !parent.getArguments().includes(reference)) return false;
+  const callee = parent.getExpression();
+  return (
+    callee.getText() === "Object.is" ||
+    (Node.isPropertyAccessExpression(callee) && IDENTITY_METHODS.has(callee.getName()))
+  );
+}
+
+interface TextEdit {
+  readonly start: number;
+  readonly end: number;
+  readonly text: string;
+}
+
+interface Candidate {
+  readonly declarationIndex: number;
+  readonly importedName: string;
+  readonly entry: FeatureFactoryEntry;
+}
+
+function referenceEdit(reference: Node, entry: FeatureFactoryEntry): TextEdit | "manual-export" {
+  const parent = reference.getParent();
+  if (Node.isTypeQuery(parent)) {
+    return {
+      start: parent.getStart(),
+      end: parent.getEnd(),
+      text: `ReturnType<typeof ${entry.factory}>`,
+    };
+  }
+  if (Node.isShorthandPropertyAssignment(parent)) {
+    return {
+      start: reference.getStart(),
+      end: reference.getEnd(),
+      text: `${reference.getText()}: ${entry.factory}()`,
+    };
+  }
+  if (Node.isExportSpecifier(parent)) return "manual-export";
+  return { start: reference.getStart(), end: reference.getEnd(), text: `${entry.factory}()` };
+}
+
+function site(file: string, node: Node, description: string): CodemodSite {
+  return { file, line: node.getStartLineNumber(), description };
+}
+
+function findCandidates(
+  sourceFile: SourceFile,
+  filePath: string,
+  result: SiteLists,
+): { candidates: Candidate[]; declarations: ImportDeclaration[] } {
+  const declarations = sourceFile.getImportDeclarations();
+  const candidates: Candidate[] = [];
+  for (const [declarationIndex, declaration] of declarations.entries()) {
+    const specifier = declaration.getModuleSpecifierValue();
+    const folder = bundledModuleFolder(specifier, filePath);
+    if (folder === undefined) continue;
+    for (const named of declaration.getNamedImports()) {
+      const entry = FEATURE_FACTORIES[named.getName()];
+      if (entry === undefined) continue;
+      if (entry.folder !== folder) {
+        result.manual.push(
+          site(
+            filePath,
+            named,
+            `${named.getName()} imported from ${specifier}: expected ${BUNDLED_PACKAGE}/${entry.folder}, use ${entry.factory}() by hand`,
+          ),
+        );
+        continue;
+      }
+      if (named.getAliasNode() !== undefined) {
+        result.manual.push(
+          site(
+            filePath,
+            named,
+            `${named.getName()} is imported under an alias: import ${entry.factory} and call it by hand`,
+          ),
+        );
+        continue;
+      }
+      candidates.push({ declarationIndex, importedName: named.getName(), entry });
+    }
+  }
+  return { candidates, declarations };
+}
+
+function referencesOutsideImports(specifier: ImportSpecifier): Node[] {
+  const importDeclaration = specifier.getImportDeclaration();
+  const nameNode = specifier.getNameNode();
+  if (!Node.isIdentifier(nameNode)) return [];
+  return nameNode
+    .findReferencesAsNodes()
+    .filter(
+      (reference) =>
+        reference.getFirstAncestor((ancestor) => ancestor === importDeclaration) === undefined,
+    );
+}
+
+function collectEdits(
+  candidates: readonly Candidate[],
+  declarations: readonly ImportDeclaration[],
+  filePath: string,
+  result: SiteLists,
+): { edits: TextEdit[]; applied: Candidate[] } {
+  const edits: TextEdit[] = [];
+  const applied: Candidate[] = [];
+  for (const candidate of candidates) {
+    const named = declarations[candidate.declarationIndex]
+      ?.getNamedImports()
+      .find((n) => n.getName() === candidate.importedName);
+    if (named === undefined) continue;
+    const references = referencesOutsideImports(named);
+    const identityUse = references.find(isIdentityUse);
+    if (identityUse !== undefined) {
+      result.manual.push(
+        site(
+          filePath,
+          identityUse,
+          `${candidate.importedName} is compared by identity; ${candidate.entry.factory}() returns a new instance`,
+        ),
+      );
+      continue;
+    }
+    const candidateEdits: TextEdit[] = [];
+    for (const reference of references) {
+      const edit = referenceEdit(reference, candidate.entry);
+      if (edit === "manual-export") {
+        result.manual.push(
+          site(
+            filePath,
+            reference,
+            `${candidate.importedName} is exported from this module: export ${candidate.entry.factory} as well`,
+          ),
+        );
+        continue;
+      }
+      candidateEdits.push(edit);
+      result.rewrites.push(
+        site(filePath, reference, `${candidate.importedName} -> ${candidate.entry.factory}()`),
+      );
+    }
+    edits.push(...candidateEdits);
+    applied.push(candidate);
+  }
+  return { edits, applied };
+}
+
+function applyEdits(source: string, edits: readonly TextEdit[]): string {
+  let output = source;
+  for (const edit of [...edits].sort((a, b) => b.start - a.start)) {
+    output = output.slice(0, edit.start) + edit.text + output.slice(edit.end);
+  }
+  return output;
+}
+
+function renameImports(
+  sourceFile: SourceFile,
+  applied: readonly Candidate[],
+  filePath: string,
+  result: SiteLists,
+): void {
+  for (const { importedName, entry } of applied) {
+    const declaration = sourceFile
+      .getImportDeclarations()
+      .find((d) => d.getNamedImports().some((n) => n.getName() === importedName));
+    const named = declaration?.getNamedImports().find((n) => n.getName() === importedName);
+    if (declaration === undefined || named === undefined) continue;
+    result.rewrites.push(site(filePath, named, `import ${importedName} -> ${entry.factory}`));
+    if (hasImportBinding(sourceFile, entry.factory)) {
+      removeNamedImport(sourceFile, declaration, named);
+    } else {
+      named.getNameNode().replaceWithText(entry.factory);
+    }
+  }
+}
+
+function reportNamespaceAccesses(
+  sourceFile: SourceFile,
+  filePath: string,
+  result: SiteLists,
+): void {
+  for (const declaration of sourceFile.getImportDeclarations()) {
+    const namespace = declaration.getNamespaceImport();
+    const folder = bundledModuleFolder(declaration.getModuleSpecifierValue(), filePath);
+    if (namespace === undefined || folder === undefined) continue;
+    for (const access of sourceFile.getDescendantsOfKind(SyntaxKind.PropertyAccessExpression)) {
+      const entry = FEATURE_FACTORIES[access.getName()];
+      if (entry?.folder === folder && access.getExpression().getText() === namespace.getText()) {
+        result.manual.push(
+          site(
+            filePath,
+            access,
+            `${access.getText()}: call ${namespace.getText()}.${entry.factory}()`,
+          ),
+        );
+      }
+    }
+  }
+}
+
+function reportReexports(sourceFile: SourceFile, filePath: string, result: SiteLists): void {
+  for (const declaration of sourceFile.getExportDeclarations()) {
+    const specifier = declaration.getModuleSpecifierValue();
+    const folder = specifier === undefined ? undefined : bundledModuleFolder(specifier, filePath);
+    if (folder === undefined) continue;
+    const exported = declaration.getNamedExports().map((e) => e.getName());
+    for (const name of exported) {
+      const entry = FEATURE_FACTORIES[name];
+      if (entry?.folder !== folder || exported.includes(entry.factory)) continue;
+      result.manual.push(
+        site(
+          filePath,
+          declaration,
+          `${name} re-exported from ${specifier}: re-export ${entry.factory}`,
+        ),
+      );
+    }
+  }
+}
+
+function reportDynamicImports(sourceFile: SourceFile, filePath: string, result: SiteLists): void {
+  for (const call of sourceFile.getDescendantsOfKind(SyntaxKind.CallExpression)) {
+    if (call.getExpression().getKind() !== SyntaxKind.ImportKeyword) continue;
+    const argument = call.getArguments()[0];
+    if (argument === undefined || !Node.isStringLiteral(argument)) continue;
+    const folder = bundledModuleFolder(argument.getLiteralValue(), filePath);
+    const touchesFolder = Object.values(FEATURE_FACTORIES).some((entry) => entry.folder === folder);
+    if (touchesFolder) {
+      result.manual.push(
+        site(
+          filePath,
+          call,
+          `dynamic import of ${argument.getLiteralValue()}: use the create*Feature factory by hand`,
+        ),
+      );
+    }
+  }
+}
+
+export function transformFeatureFactorySource(
+  source: string,
+  filePath = "source.ts",
+): CodemodResult {
+  const result: SiteLists = { rewrites: [], manual: [] };
+  if (!CHEAP_PREFILTER.test(source)) return { output: source, ...result };
+  const project = new Project({
+    useInMemoryFileSystem: true,
+    skipAddingFilesFromTsConfig: true,
+    skipFileDependencyResolution: true,
+  });
+  const sourceFile = project.createSourceFile(filePath, source);
+  reportNamespaceAccesses(sourceFile, filePath, result);
+  reportReexports(sourceFile, filePath, result);
+  reportDynamicImports(sourceFile, filePath, result);
+  const { candidates, declarations } = findCandidates(sourceFile, filePath, result);
+  const { edits, applied } = collectEdits(candidates, declarations, filePath, result);
+  if (applied.length === 0) return { output: source, ...result };
+  const withReferences = project.createSourceFile(
+    `${filePath}.rewritten.ts`,
+    applyEdits(source, edits),
+  );
+  renameImports(withReferences, applied, filePath, result);
+  return { output: withReferences.getFullText(), ...result };
+}
+
+function isSkippedPath(file: string): boolean {
+  return SKIPPED_PATH_SUFFIXES.some((suffix) => file.endsWith(suffix));
+}
+
+if (import.meta.main) {
+  await runCodemodCli(
+    {
+      name: "feature-factory",
+      transform: transformFeatureFactorySource,
+      isSkippedPath,
+    },
+    process.argv.slice(2),
+  );
+}

package/src/scripts/codemod/s3-imports.ts

@@ -0,0 +1,274 @@
+#!/usr/bin/env bun
+// s3-imports — the S3 file providers merged into one `file-provider-s3` subpath:
+//   .../files-provider-s3                                -> .../file-provider-s3/lib
+//   fileProviderS3EnvFeature (.../file-provider-s3-env)  -> createFileProviderS3Feature({ fromEnv: true })
+// `fileProviderS3Feature` -> `createFileProviderS3Feature()` is feature-factory.ts's job; the two
+// codemods leave the same result in either order.
+//
+// Usage:
+//   bun scripts/codemod/s3-imports.ts <targetDir...> [--check | --dry-run | --write] [--no-format]
+// Without a mode flag it writes (kumiko-upgrade --apply calls it that way). --check exits 1
+// while any rewritable or manual site is left; --dry-run only reports.
+
+import { type ImportDeclaration, Node, Project, type SourceFile, SyntaxKind } from "ts-morph";
+import {
+  type CodemodResult,
+  type CodemodSite,
+  ensureNamedImport,
+  hasImportBinding,
+  relativeSpecifier,
+  removeNamedImport,
+  runCodemodCli,
+  type SiteLists,
+  sourceRelativeModule,
+} from "./codemod-support.js";
+
+const BUNDLED_PACKAGE = "@cosmicdrift/kumiko-bundled-features";
+const BUNDLED_SRC_MARKER = "/packages/bundled-features/src/";
+const OLD_LIB_FOLDER = "files-provider-s3";
+const NEW_LIB_MODULE = "file-provider-s3/lib";
+const ENV_FOLDER = "file-provider-s3-env";
+const MERGED_FOLDER = "file-provider-s3";
+const ENV_CONSTANT = "fileProviderS3EnvFeature";
+const MERGED_FACTORY = "createFileProviderS3Feature";
+const ENV_CALL = `${MERGED_FACTORY}({ fromEnv: true })`;
+
+const CHEAP_PREFILTER = /files-provider-s3|fileProviderS3EnvFeature/;
+const SKIPPED_PATH_SUFFIXES: readonly string[] = [
+  "packages/bundled-features/src/files-provider-s3/index.ts",
+  "packages/bundled-features/src/file-provider-s3-env/index.ts",
+  "packages/framework/src/scripts/codemod/s3-imports.ts",
+  "packages/framework/src/__tests__/s3-imports-codemod.test.ts",
+];
+
+function newLibSpecifier(specifier: string, filePath: string): string | undefined {
+  if (specifier === `${BUNDLED_PACKAGE}/${OLD_LIB_FOLDER}`) {
+    return `${BUNDLED_PACKAGE}/${NEW_LIB_MODULE}`;
+  }
+  const relativeModule = sourceRelativeModule(specifier, filePath, BUNDLED_SRC_MARKER);
+  if (relativeModule === undefined) return undefined;
+  const { root, module, extension } = relativeModule;
+  if (module !== OLD_LIB_FOLDER && !module.startsWith(`${OLD_LIB_FOLDER}/`)) return undefined;
+  return relativeSpecifier(
+    filePath,
+    root,
+    `${NEW_LIB_MODULE}${module.slice(OLD_LIB_FOLDER.length)}`,
+    extension,
+  );
+}
+
+function envModuleReplacement(specifier: string, filePath: string): string | undefined {
+  if (specifier === `${BUNDLED_PACKAGE}/${ENV_FOLDER}`) {
+    return `${BUNDLED_PACKAGE}/${MERGED_FOLDER}`;
+  }
+  const relativeModule = sourceRelativeModule(specifier, filePath, BUNDLED_SRC_MARKER);
+  if (relativeModule === undefined) return undefined;
+  const { root, module, extension } = relativeModule;
+  if (module !== ENV_FOLDER && !/^file-provider-s3-env\/(index|feature)$/.test(module)) {
+    return undefined;
+  }
+  return relativeSpecifier(
+    filePath,
+    root,
+    `${MERGED_FOLDER}${module.slice(ENV_FOLDER.length)}`,
+    extension,
+  );
+}
+
+function site(file: string, node: Node, description: string): CodemodSite {
+  return { file, line: node.getStartLineNumber(), description };
+}
+
+function stringLiteralOf(node: Node | undefined): Node | undefined {
+  return node !== undefined && Node.isStringLiteral(node) ? node : undefined;
+}
+
+interface TextEdit {
+  readonly start: number;
+  readonly end: number;
+  readonly text: string;
+}
+
+function applyEdits(source: string, edits: readonly TextEdit[]): string {
+  let output = source;
+  for (const edit of [...edits].sort((x, y) => y.start - x.start)) {
+    output = output.slice(0, edit.start) + edit.text + output.slice(edit.end);
+  }
+  return output;
+}
+
+function moduleSpecifierLiterals(sourceFile: SourceFile): Node[] {
+  const literals: Node[] = [];
+  for (const declaration of [
+    ...sourceFile.getImportDeclarations(),
+    ...sourceFile.getExportDeclarations(),
+  ]) {
+    const literal = declaration.getModuleSpecifier();
+    if (literal !== undefined) literals.push(literal);
+  }
+  for (const importType of sourceFile.getDescendantsOfKind(SyntaxKind.ImportType)) {
+    const argument = importType.getArgument();
+    if (Node.isLiteralTypeNode(argument)) literals.push(argument.getLiteral());
+  }
+  for (const call of sourceFile.getDescendantsOfKind(SyntaxKind.CallExpression)) {
+    const callee = call.getExpression();
+    const isModuleLoad =
+      callee.getKind() === SyntaxKind.ImportKeyword || callee.getText() === "mock.module";
+    const literal = stringLiteralOf(call.getArguments()[0]);
+    if (isModuleLoad && literal !== undefined) literals.push(literal);
+  }
+  return literals;
+}
+
+function rewriteLibSpecifiers(
+  sourceFile: SourceFile,
+  source: string,
+  filePath: string,
+  result: SiteLists,
+): string {
+  const edits: TextEdit[] = [];
+  for (const literal of moduleSpecifierLiterals(sourceFile)) {
+    if (!Node.isStringLiteral(literal)) continue;
+    const current = literal.getLiteralValue();
+    const next = newLibSpecifier(current, filePath);
+    if (next === undefined) continue;
+    result.rewrites.push(site(filePath, literal, `${current} -> ${next}`));
+    edits.push({ start: literal.getStart(), end: literal.getEnd(), text: JSON.stringify(next) });
+  }
+  return applyEdits(source, edits);
+}
+
+function envFactoryEdit(reference: Node): TextEdit | "manual-type" | "manual-export" {
+  const parent = reference.getParent();
+  if (Node.isTypeQuery(parent)) return "manual-type";
+  if (Node.isExportSpecifier(parent)) return "manual-export";
+  const text = Node.isShorthandPropertyAssignment(parent)
+    ? `${ENV_CONSTANT}: ${ENV_CALL}`
+    : ENV_CALL;
+  return { start: reference.getStart(), end: reference.getEnd(), text };
+}
+
+interface EnvImportTarget {
+  readonly specifier: string;
+  readonly isTypeOnly: boolean;
+}
+
+// Collects the call-site edits of one import declaration. Returns false when a site can only be
+// fixed by hand, so the import is left untouched too.
+function planEnvDeclaration(
+  declaration: ImportDeclaration,
+  filePath: string,
+  edits: TextEdit[],
+  result: SiteLists,
+): boolean {
+  const named = declaration.getNamedImports().find((n) => n.getName() === ENV_CONSTANT);
+  if (named === undefined) return false;
+  const nameNode = named.getNameNode();
+  if (named.getAliasNode() !== undefined || !Node.isIdentifier(nameNode)) {
+    result.manual.push(
+      site(filePath, named, `${ENV_CONSTANT} imported under an alias: call ${ENV_CALL} by hand`),
+    );
+    return false;
+  }
+  const references = nameNode
+    .findReferencesAsNodes()
+    .filter((reference) => reference.getFirstAncestor((a) => a === declaration) === undefined);
+  const planned = references.map((reference) => ({ reference, edit: envFactoryEdit(reference) }));
+  const blocked = planned.filter(({ edit }) => typeof edit === "string");
+  for (const { reference, edit } of blocked) {
+    result.manual.push(
+      site(
+        filePath,
+        reference,
+        edit === "manual-type"
+          ? `typeof ${ENV_CONSTANT}: use the return type of ${MERGED_FACTORY} by hand`
+          : `${ENV_CONSTANT} is exported from this module: export ${MERGED_FACTORY} as well`,
+      ),
+    );
+  }
+  if (blocked.length > 0) return false;
+  for (const { reference, edit } of planned) {
+    if (typeof edit === "string") continue;
+    edits.push(edit);
+    result.rewrites.push(site(filePath, reference, `${ENV_CONSTANT} -> ${ENV_CALL}`));
+  }
+  return true;
+}
+
+function rewriteEnvFeature(source: string, filePath: string, result: SiteLists): string {
+  const project = new Project({
+    useInMemoryFileSystem: true,
+    skipAddingFilesFromTsConfig: true,
+    skipFileDependencyResolution: true,
+  });
+  const sourceFile = project.createSourceFile(filePath, source);
+  const edits: TextEdit[] = [];
+  const targetSpecifiers: EnvImportTarget[] = [];
+  for (const declaration of sourceFile.getImportDeclarations()) {
+    const replacement = envModuleReplacement(declaration.getModuleSpecifierValue(), filePath);
+    if (replacement === undefined) continue;
+    if (!planEnvDeclaration(declaration, filePath, edits, result)) continue;
+    targetSpecifiers.push({ specifier: replacement, isTypeOnly: declaration.isTypeOnly() });
+  }
+  if (targetSpecifiers.length === 0) return source;
+
+  const next = project.createSourceFile(`${filePath}.rewritten.ts`, applyEdits(source, edits));
+  for (const { specifier, isTypeOnly } of targetSpecifiers) {
+    const declaration = next
+      .getImportDeclarations()
+      .find((d) => d.getNamedImports().some((n) => n.getName() === ENV_CONSTANT));
+    const named = declaration?.getNamedImports().find((n) => n.getName() === ENV_CONSTANT);
+    if (declaration === undefined || named === undefined) continue;
+    result.rewrites.push(
+      site(filePath, named, `import ${ENV_CONSTANT} -> ${MERGED_FACTORY} from ${specifier}`),
+    );
+    removeNamedImport(next, declaration, named);
+    if (!hasImportBinding(next, MERGED_FACTORY)) {
+      ensureNamedImport(next, specifier, MERGED_FACTORY, isTypeOnly);
+    }
+  }
+  return next.getFullText();
+}
+
+function reportEnvReexports(sourceFile: SourceFile, filePath: string, result: SiteLists): void {
+  for (const declaration of sourceFile.getExportDeclarations()) {
+    const specifier = declaration.getModuleSpecifierValue();
+    if (specifier === undefined || envModuleReplacement(specifier, filePath) === undefined)
+      continue;
+    if (declaration.getNamedExports().some((e) => e.getName() === ENV_CONSTANT)) {
+      result.manual.push(
+        site(
+          filePath,
+          declaration,
+          `${ENV_CONSTANT} re-exported from ${specifier}: re-export ${MERGED_FACTORY}`,
+        ),
+      );
+    }
+  }
+}
+
+export function transformS3ImportsSource(source: string, filePath = "source.ts"): CodemodResult {
+  const result: SiteLists = { rewrites: [], manual: [] };
+  if (!CHEAP_PREFILTER.test(source)) return { output: source, ...result };
+  const project = new Project({
+    useInMemoryFileSystem: true,
+    skipAddingFilesFromTsConfig: true,
+    skipFileDependencyResolution: true,
+  });
+  const sourceFile = project.createSourceFile(filePath, source);
+  reportEnvReexports(sourceFile, filePath, result);
+  const libRewritten = rewriteLibSpecifiers(sourceFile, source, filePath, result);
+  const output = rewriteEnvFeature(libRewritten, filePath, result);
+  return { output, ...result };
+}
+
+function isSkippedPath(file: string): boolean {
+  return SKIPPED_PATH_SUFFIXES.some((suffix) => file.endsWith(suffix));
+}
+
+if (import.meta.main) {
+  await runCodemodCli(
+    { name: "s3-imports", transform: transformS3ImportsSource, isSkippedPath },
+    process.argv.slice(2),
+  );
+}