@reckona/mreact-router 0.0.207 → 0.0.209

package/src/boundaries.ts

@@ -11,7 +11,11 @@ import {
   createClientRouteInferenceCache,
   inferClientRouteModule,
 } from "./client-route-inference.js";
-import { resolveAppRouterProjectOptions, type AppRouterProjectOptions } from "./config.js";
+import {
+  resolveAppRouterProjectOptions,
+  type AppRouterExecutionContracts,
+  type AppRouterProjectOptions,
+} from "./config.js";
 import { stripRouteClientSource } from "./route-source.js";
 import { scanAppRoutes } from "./routes.js";
 
@@ -20,18 +24,58 @@ import { scanAppRoutes } from "./routes.js";
  */
 export interface BoundaryReportComponent {
   classification: ClientRouteComponentClassification;
+  decision: BoundaryReportDecision;
   exportName: string;
   file: string;
   origin: ClientRouteComponentOrigin;
 }
 
+export type BoundaryExecutionMode = "client" | "server" | "shared" | "unknown";
+
+export interface BoundaryReportDecision {
+  executionMode: BoundaryExecutionMode;
+  reasonChain: readonly string[];
+  sourceRange?: BoundarySourceRange | undefined;
+}
+
+export interface BoundarySourcePosition {
+  column: number;
+  line: number;
+}
+
+export interface BoundarySourceRange {
+  end: BoundarySourcePosition;
+  start: BoundarySourcePosition;
+}
+
+export interface BoundaryReportByteCost {
+  gzipEstimateBytes: number;
+  observedTransferBytes?: number | undefined;
+  rawBytes: number;
+}
+
+export interface BoundaryReportCost {
+  baseline?:
+    | {
+        initialGzipDeltaBytes?: number | undefined;
+        navigationGzipDeltaBytes?: number | undefined;
+      }
+    | undefined;
+  initial?: BoundaryReportByteCost | undefined;
+  navigation?: BoundaryReportByteCost | undefined;
+  reason?: string | undefined;
+  status: "available" | "unavailable";
+}
+
 /**
  * Describes the rendered component boundary graph for one page route.
  */
 export interface BoundaryReportRoute {
   classification: "client-route" | "server-render";
   components: readonly BoundaryReportComponent[];
+  cost: BoundaryReportCost;
   entry: string;
+  executionModes: readonly BoundaryExecutionMode[];
   path: string;
 }
 
@@ -60,9 +104,11 @@ export interface BoundaryReport {
 
 export interface CreateBoundaryReportRouteInput {
   components: readonly ClientRouteComponent[];
+  cost?: BoundaryReportCost | undefined;
   diagnostics: readonly ClientRouteInferenceDiagnostic[];
   entry: string;
   path: string;
+  source?: string | undefined;
 }
 
 export interface CreateBoundaryReportInput {
@@ -106,21 +152,29 @@ export async function analyzeAppBoundaries(
         diagnostics: inference.diagnostics,
         entry: route.file,
         path: route.path,
+        source,
       };
     }),
   );
 
-  return createBoundaryReport({
+  const report = createBoundaryReport({
     projectRoot: project.projectRoot,
     routes: analyzedRoutes,
   });
+  validateBoundaryExecutionContracts(report, project.executionContracts);
+  return report;
 }
 
 export function createBoundaryReport(input: CreateBoundaryReportInput): BoundaryReport {
   const routes = input.routes
     .map((route): BoundaryReportRoute => {
       const entry = projectRelativePath(input.projectRoot, route.entry);
-      const components = normalizeComponents(input.projectRoot, entry, route.components);
+      const components = normalizeComponents(
+        input.projectRoot,
+        entry,
+        route.components,
+        route.source,
+      );
 
       return {
         classification: components.some(
@@ -132,7 +186,12 @@ export function createBoundaryReport(input: CreateBoundaryReportInput): Boundary
           ? "client-route"
           : "server-render",
         components,
+        cost: route.cost ?? {
+          reason: "No production artifact supplied.",
+          status: "unavailable",
+        },
         entry,
+        executionModes: executionModesForComponents(components),
         path: route.path,
       };
     })
@@ -178,6 +237,8 @@ export function formatBoundaryReport(report: BoundaryReport): string {
       );
     }
 
+    lines.push(`    modes: ${route.executionModes.join(", ")}`);
+
     lines.push("");
   }
 
@@ -213,12 +274,21 @@ function normalizeComponents(
   projectRoot: string,
   entry: string,
   components: readonly ClientRouteComponent[],
+  source: string | undefined,
 ): BoundaryReportComponent[] {
   const unique = new Map<string, BoundaryReportComponent>();
 
   for (const component of components) {
-    const normalized = {
+    const normalized: BoundaryReportComponent = {
       ...component,
+      decision: {
+        executionMode: executionModeForClassification(component.classification),
+        reasonChain: reasonChainForComponent(component, projectRoot, entry),
+        ...(source === undefined ||
+        component.file !== resolveProjectRelativePath(projectRoot, entry)
+          ? {}
+          : sourceRangeField(source, component.exportName)),
+      },
       file: projectRelativePath(projectRoot, component.file),
     };
     unique.set(
@@ -243,6 +313,156 @@ function normalizeComponents(
   });
 }
 
+/** Validates opt-in execution constraints against the normalized boundary report. */
+export function validateBoundaryExecutionContracts(
+  report: BoundaryReport,
+  contracts: AppRouterExecutionContracts | undefined,
+): void {
+  if (contracts === undefined) {
+    return;
+  }
+
+  const violations: string[] = [];
+  const serverOnlyRoutes = contracts.serverOnlyRoutes ?? [];
+  const noCompatComponents = contracts.noCompatComponents ?? [];
+
+  for (const route of report.routes) {
+    if (serverOnlyRoutes.some((pattern) => globMatches(route.path, pattern))) {
+      for (const component of route.components) {
+        if (
+          component.decision.executionMode === "client" ||
+          component.decision.executionMode === "shared" ||
+          component.decision.executionMode === "unknown"
+        ) {
+          violations.push(
+            `server-only route ${JSON.stringify(route.path)} includes ${component.decision.executionMode} execution at ${component.file}#${component.exportName}`,
+          );
+        }
+      }
+    }
+
+    for (const component of route.components) {
+      const componentId = `${component.file}#${component.exportName}`;
+      if (
+        !noCompatComponents.some(
+          (pattern) => globMatches(component.file, pattern) || globMatches(componentId, pattern),
+        )
+      ) {
+        continue;
+      }
+
+      if (component.origin === "compat-filename" || isCompatComponentFile(component.file)) {
+        violations.push(
+          `no-compat component ${componentId} uses compat fallback from its filename`,
+        );
+      } else if (component.decision.executionMode === "unknown") {
+        violations.push(`no-compat component ${componentId} has an unknown compiler decision`);
+      }
+    }
+  }
+
+  if (violations.length > 0) {
+    throw new Error(
+      `mreactRouter execution contract violation(s):\n${violations.map((violation) => `- ${violation}`).join("\n")}`,
+    );
+  }
+}
+
+function isCompatComponentFile(file: string): boolean {
+  return /\.compat(?:\.mreact)?\.[cm]?[jt]sx?$/.test(file.replaceAll("\\", "/"));
+}
+
+function executionModesForComponents(
+  components: readonly BoundaryReportComponent[],
+): BoundaryExecutionMode[] {
+  const order: readonly BoundaryExecutionMode[] = ["client", "server", "shared", "unknown"];
+  const modes = new Set(components.map((component) => component.decision.executionMode));
+  return order.filter((mode) => modes.has(mode));
+}
+
+function executionModeForClassification(
+  classification: ClientRouteComponentClassification,
+): BoundaryExecutionMode {
+  if (classification === "client-boundary" || classification === "client-route") {
+    return "client";
+  }
+  if (classification === "shared") {
+    return "shared";
+  }
+  if (classification === "unknown") {
+    return "unknown";
+  }
+  return "server";
+}
+
+function reasonChainForComponent(
+  component: ClientRouteComponent,
+  projectRoot: string,
+  entry: string,
+): string[] {
+  const reasons = [`classification:${component.classification}`, `origin:${component.origin}`];
+
+  if (component.origin === "inferred-client-runtime") {
+    reasons.push("client-runtime-inference");
+  } else if (component.origin === "compat-filename") {
+    reasons.push("compat-fallback");
+  } else if (component.origin === "unresolved-reference") {
+    reasons.push("unresolved-reference");
+  }
+
+  if (projectRelativePath(projectRoot, component.file) !== entry) {
+    reasons.push(`reachable-from:${entry}`);
+  }
+
+  return reasons;
+}
+
+function sourceRangeField(
+  source: string,
+  exportName: string,
+): { sourceRange?: BoundarySourceRange | undefined } {
+  const escapedName = escapeRegExp(exportName);
+  const pattern =
+    exportName === "default"
+      ? /\bexport\s+default\b/u
+      : new RegExp(
+          `\\bexport\\s+(?:(?:async)\\s+)?(?:function|class|const|let|var)\\s+${escapedName}\\b`,
+          "u",
+        );
+  const match = pattern.exec(source);
+
+  return match === null || match.index === undefined
+    ? {}
+    : {
+        sourceRange: {
+          end: sourcePosition(source, match.index + match[0].length),
+          start: sourcePosition(source, match.index),
+        },
+      };
+}
+
+function sourcePosition(source: string, offset: number): BoundarySourcePosition {
+  const lines = source.slice(0, offset).split("\n");
+  return { column: (lines.at(-1)?.length ?? 0) + 1, line: lines.length };
+}
+
+function escapeRegExp(value: string): string {
+  return value.replace(/[.*+?^${}()|[\]\\]/gu, "\\$&");
+}
+
+function globMatches(value: string, pattern: string): boolean {
+  const escaped = pattern.replace(/[.+^${}()|[\]\\]/gu, "\\$&");
+  const expression = escaped
+    .replaceAll("**", "\u0000")
+    .replaceAll("*", "[^/]*")
+    .replaceAll("\u0000", ".*");
+  return new RegExp(`^${expression}$`, "u").test(value);
+}
+
+function resolveProjectRelativePath(projectRoot: string, relativePath: string): string {
+  return `${projectRoot}/${relativePath}`;
+}
+
 function summarizeBoundaryRoutes(routes: readonly BoundaryReportRoute[]): BoundaryReportSummary {
   const components = routes.flatMap((route) => route.components);