Module Transformation

/**
 * Perform all of the generic ES6 module rewriting needed to handle initial
 * module processing. This function will rewrite the majority of the given
 * program to reference the modules described by the returned metadata,
 * and returns a list of statements for use when initializing the module.
 */
function rewriteModuleStatementsAndPrepareHeader(
  path: NodePath<Program>,
  options: RewriteModuleStatementsAndPrepareHeaderOptions
): { meta: ModuleMetadata; headers: Statement[] };

interface RewriteModuleStatementsAndPrepareHeaderOptions {
  /** Name for the exported object (e.g., "exports" or "module.exports") */
  exportName?: string;
  /** Whether to use strict mode handling */
  strict: boolean;
  /** Allow `this` in top-level scope */
  allowTopLevelThis?: boolean;
  /** Add "use strict" directive */
  strictMode: boolean;
  /** Use loose transformation mode (deprecated) */
  loose?: boolean;
  /** Import interoperability strategy */
  importInterop?: ImportInterop;
  /** Disable interop helpers (deprecated, use importInterop: "none") */
  noInterop?: boolean;
  /** Lazy loading configuration */
  lazy?: Lazy;
  /** Function to determine wrapper payload for imports */
  getWrapperPayload?: (
    source: string,
    metadata: SourceModuleMetadata,
    importNodes: Node[]
  ) => unknown;
  /** Function to wrap import references */
  wrapReference?: (ref: Expression, payload: unknown) => Expression | null;
  /** Only handle ES namespace imports */
  esNamespaceOnly?: boolean;
  /** Source filename for module name generation */
  filename: string | undefined;
  /** Use constant re-exports (performance optimization) */
  constantReexports?: boolean | void;
  /** Make module metadata enumerable */
  enumerableModuleMeta?: boolean | void;
  /** Skip incomplete namespace import detection */
  noIncompleteNsImportDetection?: boolean | void;
}

type ImportInterop = 
  | "none"       // No interop helpers
  | "babel"      // Babel-style interop
  | "node"       // Node.js-style interop
  | ((source: string, filename?: string) => "none" | "babel" | "node");

type Lazy = boolean | string[] | ((source: string) => boolean);

import { rewriteModuleStatementsAndPrepareHeader, isModule } from "@babel/helper-module-transforms";
import type { NodePath, Program } from "@babel/core";

function transformToCommonJS(programPath: NodePath<Program>) {
  if (!isModule(programPath)) {
    throw new Error("Cannot process module statements in a script");
  }

  // Transform the module with CommonJS-compatible settings
  const result = rewriteModuleStatementsAndPrepareHeader(programPath, {
    strict: false,
    strictMode: true,
    allowTopLevelThis: false,
    importInterop: "babel",
    filename: programPath.hub.file?.opts.filename,
    constantReexports: false,
    enumerableModuleMeta: true
  });

  // The result contains transformed metadata and initialization statements
  return {
    moduleMetadata: result.meta,
    initializationCode: result.headers
  };
}

/**
 * Flag a set of statements as hoisted above all else so that module init
 * statements all run before user code.
 */
function ensureStatementsHoisted(statements: Statement[]): void;

import { ensureStatementsHoisted } from "@babel/helper-module-transforms";

// After generating module initialization statements
const initStatements = generateModuleInitStatements();
ensureStatementsHoisted(initStatements);
// Now these statements will be executed before any user code

/**
 * Given an expression for a standard import object, like "require('foo')",
 * wrap it in a call to the interop helpers based on the type.
 */
function wrapInterop(
  programPath: NodePath<Program>,
  expr: Expression,
  type: InteropType
): CallExpression | null;

type InteropType =
  | "default"        // Babel interop for default-only imports
  | "namespace"      // Babel interop for namespace or default+named imports
  | "node-default"   // Node.js interop for default-only imports
  | "node-namespace" // Node.js interop for namespace or default+named imports
  | "none";          // No interop, or named-only imports

import { wrapInterop } from "@babel/helper-module-transforms";
import { types as t } from "@babel/core";

// Wrap a require() call with appropriate interop helper
const requireCall = t.callExpression(t.identifier("require"), [t.stringLiteral("some-module")]);
const wrappedCall = wrapInterop(programPath, requireCall, "default");
// Results in: _interopRequireDefault(require("some-module"))

// Some interop types return null (no wrapping needed)
const noWrapCall = wrapInterop(programPath, requireCall, "none");
// Results in: null (use original expression)

/**
 * Create the runtime initialization statements for a given requested source.
 * These will initialize all of the runtime import/export logic that
 * can't be handled statically by the statements created by
 * buildExportInitializationStatements().
 */
function buildNamespaceInitStatements(
  metadata: ModuleMetadata,
  sourceMetadata: SourceModuleMetadata,
  constantReexports?: boolean | void,
  wrapReference?: (ref: Identifier, payload: unknown) => Expression | null
): Statement[];

/**
 * Rewrite all `this` references in the top-level scope to be `void 0` (undefined).
 * This is necessary because modules have undefined `this` in the top level.
 */
function rewriteThis(programPath: NodePath): void;

import { rewriteThis } from "@babel/helper-module-transforms";

// Rewrite `this` to `undefined` in module scope
rewriteThis(programPath);