@reckona/mreact-compiler 0.0.160 → 0.0.162

package/src/oxc.ts

@@ -71,8 +71,10 @@ import {
   type OxcChildAnalysisContext,
 } from "./oxc-child-analysis.js";
 import {
+  analyzeCompatCreateElementFunctionRoot,
   analyzeCompatCreateElementRoot,
   collectCompatCreateElementNames,
+  collectCompatRenderToStringNames,
   collectFunctionShadowedNames,
   hasLowerableCompatCreateElementReturn,
 } from "./oxc-compat-create-element.js";
@@ -95,6 +97,7 @@ import {
 import { containsRawJsxInIr } from "./oxc-raw-jsx.js";
 import type { AnalyzeModuleOptions, CompileTarget, Diagnostic } from "./types.js";
 
+/** Reports OXC analysis parity data used by compiler migration and diagnostics tests. */
 export interface OxcParityResult {
   matches: boolean;
   oxc: {
@@ -151,6 +154,7 @@ function createOxcChildAnalysisContext(
   };
 }
 
+/** Compares OXC component discovery and IR output against parity expectations for one module. */
 export function analyzeOxcParity(input: AnalyzeToIrInput): OxcParityResult {
   const oxc = parseSync(input.filename, input.code, {
     lang: "tsx",
@@ -182,6 +186,7 @@ export function analyzeOxcParity(input: AnalyzeToIrInput): OxcParityResult {
   };
 }
 
+/** Analyzes source code into compiler IR using OXC parsing and lowering. */
 export function analyzeWithOxc(input: AnalyzeToIrInput): AnalyzeToIrOutput {
   return analyzeCompilerModuleContextWithOxc(createCompilerModuleContextWithOxc(input), {
     target: input.target,
@@ -189,6 +194,7 @@ export function analyzeWithOxc(input: AnalyzeToIrInput): AnalyzeToIrOutput {
   });
 }
 
+/** Analyzes a cached OXC compiler module context into compiler IR. */
 export function analyzeCompilerModuleContextWithOxc(
   context: CompilerModuleContext,
   input: Omit<AnalyzeToIrInput, "code" | "filename">,
@@ -245,11 +251,23 @@ function analyzeOxcToIr(
       : undefined;
   const localJsxReturnFunctionNames =
     target === "server" ? collectOxcLocalJsxReturnFunctionNames(program) : new Set<string>();
-  // Stream emit keeps interpreting compat trees for now; only the string
-  // pipeline lowers createElement calls.
   const compatCreateElementNames =
-    target === "server" && options?.serverOutput !== "stream"
-      ? collectCompatCreateElementNames(program)
+    target === "server" ? collectCompatCreateElementNames(program) : new Set<string>();
+  const compatRenderToStringNames =
+    target === "server" ? collectCompatRenderToStringNames(program) : new Set<string>();
+  const compatCreateElementLocalFunctionLikes =
+    target === "server"
+      ? collectCompatCreateElementLocalFunctionLikes(program)
+      : new Map<string, Record<string, unknown>>();
+  const compatRenderToStringLowerableTargets =
+    target === "server"
+      ? collectCompatRenderToStringLowerableTargets(
+          code,
+          body,
+          compatCreateElementNames,
+          compatRenderToStringNames,
+          compatCreateElementLocalFunctionLikes,
+        )
       : new Set<string>();
   const localJsxHelperHtmlParameters =
     target === "server"
@@ -277,7 +295,15 @@ function analyzeOxcToIr(
 
     if (
       isOxcJsxComponentStatement(statement, localJsxReturnFunctionNames) ||
-      isCompatCreateElementComponentStatement(code, statement, compatCreateElementNames) ||
+      isCompatCreateElementComponentStatement(
+        code,
+        statement,
+        compatCreateElementNames,
+        compatRenderToStringNames,
+        compatCreateElementLocalFunctionLikes,
+        compatRenderToStringLowerableTargets,
+        options?.serverOutput,
+      ) ||
       (options?.compatReactNodeReturn === true && isOxcExportedFunctionLike(statement))
     ) {
       const declaration = readObject(readObject(statement).declaration);
@@ -342,6 +368,9 @@ function analyzeOxcToIr(
       diagnostics,
       options?.bodyStatementJsx ?? "dom-node",
       compatCreateElementNames,
+      compatRenderToStringNames,
+      compatCreateElementLocalFunctionLikes,
+      compatRenderToStringLowerableTargets,
       moduleRenderValueBindings,
       options?.compatReactNodeReturn === true,
       options?.serverOutput,
@@ -553,32 +582,292 @@ function readCompatCreateElementPlainComponent(
   return undefined;
 }
 
+function collectCompatCreateElementLocalFunctionLikes(
+  program: unknown,
+): Map<string, Record<string, unknown>> {
+  const functionLikes = new Map<string, Record<string, unknown>>();
+
+  for (const statement of readArray(readObject(program).body)) {
+    const object = readObject(statement);
+    const declaration =
+      object.type === "ExportNamedDeclaration" ? readObject(object.declaration) : object;
+
+    if (declaration.type === "FunctionDeclaration") {
+      const id = readObject(declaration.id);
+
+      if (typeof id.name === "string") {
+        functionLikes.set(id.name, declaration);
+      }
+      continue;
+    }
+
+    if (declaration.type !== "VariableDeclaration") {
+      continue;
+    }
+
+    for (const declarator of readArray(declaration.declarations)) {
+      const declaratorObject = readObject(declarator);
+      const id = readObject(declaratorObject.id);
+      const initializer = unwrapOxcComponentFunctionLikeInitializer(
+        readObject(declaratorObject.init),
+      );
+
+      if (typeof id.name === "string" && initializer !== undefined) {
+        functionLikes.set(id.name, initializer);
+      }
+    }
+  }
+
+  return functionLikes;
+}
+
+function collectCompatRenderToStringLowerableTargets(
+  code: string,
+  body: readonly unknown[],
+  createElementNames: ReadonlySet<string>,
+  renderToStringNames: ReadonlySet<string>,
+  localFunctionLikes: ReadonlyMap<string, Record<string, unknown>>,
+): Set<string> {
+  const targets = new Set<string>();
+
+  if (createElementNames.size === 0 || renderToStringNames.size === 0) {
+    return targets;
+  }
+
+  for (const statement of body) {
+    const functionLike = unwrapOxcStatementFunctionLike(statement);
+
+    if (functionLike === undefined) {
+      continue;
+    }
+
+    const targetName = readCompatRenderToStringWrapperTargetName(
+      code,
+      functionLike,
+      renderToStringNames,
+    );
+    const targetFunctionLike =
+      targetName === undefined ? undefined : localFunctionLikes.get(targetName);
+
+    if (
+      targetName !== undefined &&
+      targetFunctionLike !== undefined &&
+      analyzeCompatCreateElementFunctionRoot(code, targetFunctionLike, createElementNames) !==
+        undefined
+    ) {
+      targets.add(targetName);
+    }
+  }
+
+  return targets;
+}
+
+function unwrapOxcStatementFunctionLike(statement: unknown): Record<string, unknown> | undefined {
+  const object = readObject(statement);
+  const declaration =
+    object.type === "ExportNamedDeclaration" || object.type === "ExportDefaultDeclaration"
+      ? readObject(object.declaration)
+      : object;
+
+  if (declaration.type === "FunctionDeclaration") {
+    return declaration;
+  }
+
+  if (declaration.type !== "VariableDeclaration") {
+    return unwrapOxcComponentFunctionLikeInitializer(declaration);
+  }
+
+  for (const declarator of readArray(declaration.declarations)) {
+    const initializer = unwrapOxcComponentFunctionLikeInitializer(
+      readObject(readObject(declarator).init),
+    );
+
+    if (initializer !== undefined) {
+      return initializer;
+    }
+  }
+
+  return undefined;
+}
+
+function readCompatRenderToStringWrapperTargetName(
+  code: string,
+  functionLike: Record<string, unknown>,
+  renderToStringNames: ReadonlySet<string>,
+): string | undefined {
+  const expression = readCompatRenderToStringWrapperReturnExpression(functionLike);
+
+  if (expression === undefined) {
+    return undefined;
+  }
+
+  return readCompatRenderToStringTargetName(
+    expression,
+    renderToStringNames,
+    collectFunctionShadowedNames(functionLike, renderToStringNames),
+  );
+}
+
+function readCompatRenderToStringWrapperReturnExpression(
+  functionLike: Record<string, unknown>,
+): Record<string, unknown> | undefined {
+  const body = unwrapOxcParentheses(readObject(functionLike.body));
+
+  if (body.type !== "BlockStatement") {
+    return body;
+  }
+
+  for (const statement of readArray(body.body)) {
+    const statementObject = readObject(statement);
+
+    if (statementObject.type === "ReturnStatement") {
+      return unwrapOxcParentheses(readObject(statementObject.argument));
+    }
+  }
+
+  return undefined;
+}
+
+function readCompatRenderToStringTargetName(
+  expression: Record<string, unknown>,
+  renderToStringNames: ReadonlySet<string>,
+  shadowedNames: ReadonlySet<string>,
+): string | undefined {
+  if (
+    renderToStringNames.size === 0 ||
+    expression.type !== "CallExpression" ||
+    expression.optional === true
+  ) {
+    return undefined;
+  }
+
+  const callee = unwrapOxcParentheses(readObject(expression.callee));
+
+  if (
+    callee.type !== "Identifier" ||
+    typeof callee.name !== "string" ||
+    !renderToStringNames.has(callee.name) ||
+    shadowedNames.has(callee.name)
+  ) {
+    return undefined;
+  }
+
+  const args = readArray(expression.arguments);
+
+  if (args.length !== 1) {
+    return undefined;
+  }
+
+  const target = unwrapOxcParentheses(readObject(args[0]));
+
+  return target.type === "Identifier" && typeof target.name === "string" ? target.name : undefined;
+}
+
+function hasCompatRenderToStringWrapperReturn(
+  code: string,
+  functionLike: Record<string, unknown>,
+  renderToStringNames: ReadonlySet<string>,
+): boolean {
+  return (
+    readCompatRenderToStringWrapperTargetName(code, functionLike, renderToStringNames) !== undefined
+  );
+}
+
+function analyzeCompatRenderToStringWrapperRoot(
+  code: string,
+  functionLike: Record<string, unknown>,
+  returnExpression: Record<string, unknown>,
+  createElementNames: ReadonlySet<string>,
+  renderToStringNames: ReadonlySet<string>,
+  localFunctionLikes: ReadonlyMap<string, Record<string, unknown>>,
+): ComponentIr["root"] | undefined {
+  const targetName = readCompatRenderToStringTargetName(
+    returnExpression,
+    renderToStringNames,
+    collectFunctionShadowedNames(functionLike, renderToStringNames),
+  );
+
+  if (targetName === undefined) {
+    return undefined;
+  }
+
+  const targetFunctionLike = localFunctionLikes.get(targetName);
+  const lowered =
+    targetFunctionLike === undefined
+      ? undefined
+      : analyzeCompatCreateElementFunctionRoot(code, targetFunctionLike, createElementNames);
+
+  if (lowered !== undefined) {
+    return lowered;
+  }
+
+  return {
+    kind: "expr",
+    code: normalizeOxcExpressionCode(readSource(code, returnExpression)),
+    renderMode: "html",
+  };
+}
+
 function isCompatCreateElementComponentStatement(
   code: string,
   statement: unknown,
   names: ReadonlySet<string>,
+  renderToStringNames: ReadonlySet<string>,
+  localFunctionLikes: ReadonlyMap<string, Record<string, unknown>>,
+  renderToStringLowerableTargets: ReadonlySet<string>,
+  serverOutput?: AnalyzeModuleOptions["serverOutput"],
 ): boolean {
-  if (names.size === 0) {
+  if (names.size === 0 && renderToStringNames.size === 0) {
     return false;
   }
 
   const object = readObject(statement);
 
   if (object.type === "ExportDefaultDeclaration") {
-    return readCompatCreateElementFunctionLike(code, readObject(object.declaration), names) !== undefined;
+    const functionLike = unwrapOxcComponentFunctionLikeInitializer(readObject(object.declaration));
+
+    return (
+      readCompatCreateElementFunctionLike(code, readObject(object.declaration), names) !==
+        undefined ||
+      (functionLike !== undefined &&
+        hasCompatRenderToStringWrapperReturn(code, functionLike, renderToStringNames))
+    );
   }
 
   if (object.type === "ExportNamedDeclaration") {
     const declaration = readObject(object.declaration);
 
     if (declaration.type === "FunctionDeclaration") {
-      return hasLowerableCompatCreateElementReturn(code, declaration, names);
+      return (
+        hasLowerableCompatCreateElementReturn(code, declaration, names) ||
+        hasCompatRenderToStringWrapperReturn(code, declaration, renderToStringNames)
+      );
     }
 
     return readCompatCreateElementPlainComponent(code, declaration, names) !== undefined;
   }
 
-  return readCompatCreateElementPlainComponent(code, statement, names) !== undefined;
+  const plainComponent = readCompatCreateElementPlainComponent(code, statement, names);
+
+  if (serverOutput === "stream") {
+    return (
+      plainComponent !== undefined &&
+      renderToStringLowerableTargets.has(plainComponent.name) &&
+      localFunctionLikes.get(plainComponent.name) === plainComponent.initializer
+    );
+  }
+
+  if (plainComponent !== undefined) {
+    return true;
+  }
+
+  const functionLike = unwrapOxcStatementFunctionLike(statement);
+
+  if (functionLike === undefined) {
+    return false;
+  }
+
+  return hasCompatRenderToStringWrapperReturn(code, functionLike, renderToStringNames);
 }
 
 function analyzeOxcComponent(
@@ -589,6 +878,9 @@ function analyzeOxcComponent(
   diagnostics: Diagnostic[],
   bodyStatementJsx: OxcBodyStatementJsxMode,
   compatCreateElementNames: ReadonlySet<string>,
+  compatRenderToStringNames: ReadonlySet<string>,
+  compatCreateElementLocalFunctionLikes: ReadonlyMap<string, Record<string, unknown>>,
+  compatRenderToStringLowerableTargets: ReadonlySet<string>,
   moduleRenderValueBindings: Set<string>,
   compatReactNodeReturn: boolean,
   serverOutput: AnalyzeModuleOptions["serverOutput"],
@@ -606,7 +898,8 @@ function analyzeOxcComponent(
     if (
       declaration === undefined ||
       (!hasOxcFunctionLikeComponentReturn(declaration) &&
-        !hasLowerableCompatCreateElementReturn(code, declaration, compatCreateElementNames))
+        !hasLowerableCompatCreateElementReturn(code, declaration, compatCreateElementNames) &&
+        !hasCompatRenderToStringWrapperReturn(code, declaration, compatRenderToStringNames))
     ) {
       return [];
     }
@@ -624,6 +917,8 @@ function analyzeOxcComponent(
         diagnostics,
         bodyStatementJsx,
         compatCreateElementNames,
+        compatRenderToStringNames,
+        compatCreateElementLocalFunctionLikes,
         moduleRenderValueBindings,
         compatReactNodeReturn,
         serverOutput,
@@ -640,12 +935,18 @@ function analyzeOxcComponent(
   if (object.type !== "ExportNamedDeclaration") {
     const plainComponent =
       readOxcPlainComponent(statement) ??
-      readCompatCreateElementPlainComponent(code, statement, compatCreateElementNames);
+      (serverOutput === "stream"
+        ? undefined
+        : readCompatCreateElementPlainComponent(code, statement, compatCreateElementNames));
 
     if (plainComponent === undefined) {
       return [];
     }
 
+    if (compatRenderToStringLowerableTargets.has(plainComponent.name)) {
+      return [];
+    }
+
     return [
       {
         ...analyzeOxcFunctionLikeComponent(
@@ -658,6 +959,8 @@ function analyzeOxcComponent(
           diagnostics,
           bodyStatementJsx,
           compatCreateElementNames,
+          compatRenderToStringNames,
+          compatCreateElementLocalFunctionLikes,
           moduleRenderValueBindings,
           compatReactNodeReturn,
           serverOutput,
@@ -694,6 +997,8 @@ function analyzeOxcComponent(
         diagnostics,
         bodyStatementJsx,
         compatCreateElementNames,
+        compatRenderToStringNames,
+        compatCreateElementLocalFunctionLikes,
         moduleRenderValueBindings,
         compatReactNodeReturn,
         serverOutput,
@@ -711,7 +1016,8 @@ function analyzeOxcComponent(
     (!compatReactNodeReturn &&
       !hasComponentReturn(declaration.body) &&
       !hasLocalJsxHelperCallReturn(declaration.body, localJsxReturnFunctionNames) &&
-      !hasLowerableCompatCreateElementReturn(code, declaration, compatCreateElementNames))
+      !hasLowerableCompatCreateElementReturn(code, declaration, compatCreateElementNames) &&
+      !hasCompatRenderToStringWrapperReturn(code, declaration, compatRenderToStringNames))
   ) {
     return [];
   }
@@ -733,6 +1039,8 @@ function analyzeOxcComponent(
       diagnostics,
       bodyStatementJsx,
       compatCreateElementNames,
+      compatRenderToStringNames,
+      compatCreateElementLocalFunctionLikes,
       moduleRenderValueBindings,
       compatReactNodeReturn,
       serverOutput,
@@ -783,6 +1091,8 @@ function analyzeOxcFunctionLikeComponent(
   diagnostics: Diagnostic[],
   bodyStatementJsx: OxcBodyStatementJsxMode,
   compatCreateElementNames: ReadonlySet<string>,
+  compatRenderToStringNames: ReadonlySet<string>,
+  compatCreateElementLocalFunctionLikes: ReadonlyMap<string, Record<string, unknown>>,
   moduleRenderValueBindings: Set<string>,
   compatReactNodeReturn: boolean,
   serverOutput: AnalyzeModuleOptions["serverOutput"],
@@ -869,6 +1179,14 @@ function analyzeOxcFunctionLikeComponent(
           names: compatCreateElementNames,
           shadowed: collectFunctionShadowedNames(functionLike, compatCreateElementNames),
         })) ??
+    analyzeCompatRenderToStringWrapperRoot(
+      code,
+      functionLike,
+      returnExpression,
+      compatCreateElementNames,
+      compatRenderToStringNames,
+      compatCreateElementLocalFunctionLikes,
+    ) ??
     (isJsxRoot(returnExpression.type) || returnExpression.type === "JSXFragment"
       ? analyzeOxcJsxNode(code, returnExpression, childAnalysisContext)
       : isOxcComponentCallExpression(returnExpression)

package/src/transform.ts

@@ -15,6 +15,7 @@ import type {
   TransformOutput,
 } from "./types.js";
 
+/** Compiles one mreact source module into client or server JavaScript output. */
 export function transform(input: TransformInput): TransformOutput {
   return transformWithAnalyzer(input, (analyzeTarget, analyzeOptions) =>
     analyzeWithOxc({
@@ -26,6 +27,7 @@ export function transform(input: TransformInput): TransformOutput {
   );
 }
 
+/** Compiles a pre-parsed compiler module context into client or server JavaScript output. */
 export function transformCompilerModuleContext(
   input: TransformInput & { moduleContext: CompilerModuleContext },
 ): TransformOutput {

package/src/types.ts

@@ -15,14 +15,25 @@ import type {
   TransformOutput as SharedTransformOutput,
 } from "@reckona/mreact-shared/compiler-contract";
 
+/** Names whether the compiler emits client or server output. */
 export type CompileTarget = SharedCompileTarget;
+
+/** Names the server renderer output format produced by the compiler. */
 export type ServerOutputMode = SharedServerOutputMode;
+
+/** Names how the server renderer should emit bootstrap scripts. */
 export type ServerBootstrapMode = SharedServerBootstrapMode;
+
+/** Names the parser backend used by the compiler. */
 export type ParserMode = "oxc";
+
+/** Names the frontend implementation that produced compiler metadata. */
 export type CompilerFrontend = SharedCompilerFrontend;
 
+/** Names how JSX found in component body statements should be lowered. */
 export type BodyStatementJsxMode = "dom-node" | "compat-object" | "server-string" | "unsupported";
 
+/** Configures lower-level module analysis before code emission. */
 export interface AnalyzeModuleOptions {
   topLevelJsx?: "diagnostic" | "compat-object" | "server-string";
   bodyStatementJsx?: BodyStatementJsxMode;
@@ -34,6 +45,7 @@ export interface AnalyzeModuleOptions {
   compatReactNodeReturnRenderMode?: "react-node";
 }
 
+/** Configures a single compiler transform call. */
 export interface TransformInput {
   code: string;
   filename: string;
@@ -54,19 +66,41 @@ export interface TransformInput {
   reactSuspenseRevealScriptSrc?: string;
 }
 
+/** Configures imports for the server HTML escape helper emitted by the compiler. */
 export interface ServerEscapeOptions {
   batchImportName: string;
   batchImportSource: string;
 }
 
+/** Describes emitted code, source map data, diagnostics, and metadata from a transform. */
 export type TransformOutput = SharedTransformOutput;
+
+/** Describes a compiler diagnostic message. */
 export type Diagnostic = SharedDiagnostic;
+
+/** Describes a suggested fix attached to a compiler diagnostic. */
 export type DiagnosticSuggestion = SharedDiagnosticSuggestion;
+
+/** Describes a one-based source location for diagnostics and metadata. */
 export type SourceLocation = SharedSourceLocation;
+
+/** Describes metadata collected for one transformed module. */
 export type ModuleMetadata = SharedModuleMetadata;
+
+/** Describes compiler frontend metadata for one transformed module. */
 export type CompilerMetadata = SharedModuleMetadata["compiler"];
+
+/** Describes a client boundary reference discovered during compilation. */
 export type ClientReferenceMetadata = SharedClientReferenceMetadata;
+
+/** Describes one compiled component discovered in a module. */
 export type ComponentMetadata = SharedComponentMetadata;
+
+/** Describes a runtime import required by emitted compiler output. */
 export type RuntimeImport = SharedRuntimeImport;
+
+/** Describes event hydration metadata emitted for server-rendered handlers. */
 export type EventHydrationManifestMetadata = SharedEventHydrationManifestMetadata;
+
+/** Describes one event hydration entry in a compiler metadata manifest. */
 export type EventHydrationEntryMetadata = SharedEventHydrationEntryMetadata;