@reckona/mreact-router 0.0.195 → 0.0.197

package/src/boundaries.ts

@@ -0,0 +1,285 @@
+import { readFile } from "node:fs/promises";
+import { relative, sep } from "node:path";
+import type { UserConfig } from "vite";
+import type {
+  ClientRouteComponent,
+  ClientRouteComponentClassification,
+  ClientRouteComponentOrigin,
+  ClientRouteInferenceDiagnostic,
+} from "./client-route-inference.js";
+import {
+  createClientRouteInferenceCache,
+  inferClientRouteModule,
+} from "./client-route-inference.js";
+import { resolveAppRouterProjectOptions, type AppRouterProjectOptions } from "./config.js";
+import { stripRouteClientSource } from "./route-source.js";
+import { scanAppRoutes } from "./routes.js";
+
+/**
+ * Describes one statically traced component in a route boundary report.
+ */
+export interface BoundaryReportComponent {
+  classification: ClientRouteComponentClassification;
+  exportName: string;
+  file: string;
+  origin: ClientRouteComponentOrigin;
+}
+
+/**
+ * Describes the rendered component boundary graph for one page route.
+ */
+export interface BoundaryReportRoute {
+  classification: "client-route" | "server-render";
+  components: readonly BoundaryReportComponent[];
+  entry: string;
+  path: string;
+}
+
+/**
+ * Counts route and component classifications across a boundary report.
+ */
+export interface BoundaryReportSummary {
+  clientBoundaries: number;
+  clientRoutes: number;
+  serverOnlyComponents: number;
+  serverRenderComponents: number;
+  serverRenderRoutes: number;
+  sharedComponents: number;
+  unknownComponents: number;
+}
+
+/**
+ * Contains a deterministic, versioned snapshot of app-router component boundaries.
+ */
+export interface BoundaryReport {
+  diagnostics: readonly ClientRouteInferenceDiagnostic[];
+  routes: readonly BoundaryReportRoute[];
+  summary: BoundaryReportSummary;
+  version: 1;
+}
+
+export interface CreateBoundaryReportRouteInput {
+  components: readonly ClientRouteComponent[];
+  diagnostics: readonly ClientRouteInferenceDiagnostic[];
+  entry: string;
+  path: string;
+}
+
+export interface CreateBoundaryReportInput {
+  projectRoot: string;
+  routes: readonly CreateBoundaryReportRouteInput[];
+}
+
+/**
+ * Supplies project and Vite settings for standalone boundary analysis.
+ */
+export interface AnalyzeAppBoundariesOptions extends AppRouterProjectOptions {
+  viteConfig?: Pick<UserConfig, "define" | "plugins"> | undefined;
+}
+
+/**
+ * Inspects every page route without writing build artifacts or executing application code.
+ */
+export async function analyzeAppBoundaries(
+  options: AnalyzeAppBoundariesOptions,
+): Promise<BoundaryReport> {
+  const project = resolveAppRouterProjectOptions(options);
+  const routes = (await scanAppRoutes({ appDir: project.routesDir })).filter(
+    (route) => route.kind === "page",
+  );
+  const cache = createClientRouteInferenceCache();
+  const analyzedRoutes = await Promise.all(
+    routes.map(async (route): Promise<CreateBoundaryReportRouteInput> => {
+      const source = await readFile(route.file, "utf8");
+      const inference = await inferClientRouteModule({
+        appDir: project.routesDir,
+        cache,
+        code: stripRouteClientSource({ code: source, filename: route.file }),
+        collectComponents: true,
+        filename: route.file,
+        routePath: route.path,
+        vitePlugins: options.viteConfig?.plugins,
+      });
+
+      return {
+        components: inference.components ?? [],
+        diagnostics: inference.diagnostics,
+        entry: route.file,
+        path: route.path,
+      };
+    }),
+  );
+
+  return createBoundaryReport({
+    projectRoot: project.projectRoot,
+    routes: analyzedRoutes,
+  });
+}
+
+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);
+
+      return {
+        classification: components.some(
+          (component) =>
+            component.file === entry &&
+            component.exportName === "default" &&
+            component.classification === "client-route",
+        )
+          ? "client-route"
+          : "server-render",
+        components,
+        entry,
+        path: route.path,
+      };
+    })
+    .sort((left, right) =>
+      left.path === right.path
+        ? left.entry.localeCompare(right.entry)
+        : left.path.localeCompare(right.path),
+    );
+  const diagnostics = input.routes
+    .flatMap((route) => route.diagnostics)
+    .map((diagnostic) => {
+      const filename = projectRelativePath(input.projectRoot, diagnostic.filename);
+
+      return {
+        ...diagnostic,
+        filename,
+        message: diagnostic.message.split(diagnostic.filename).join(filename),
+      };
+    })
+    .sort((left, right) =>
+      left.filename === right.filename
+        ? left.code.localeCompare(right.code)
+        : left.filename.localeCompare(right.filename),
+    );
+
+  return {
+    diagnostics,
+    routes,
+    summary: summarizeBoundaryRoutes(routes),
+    version: 1,
+  };
+}
+
+export function formatBoundaryReport(report: BoundaryReport): string {
+  const lines = ["Boundaries:"];
+
+  for (const route of report.routes) {
+    lines.push(`  ${route.path} [${route.classification}]`);
+
+    for (const component of route.components) {
+      lines.push(
+        `    ${component.file}#${component.exportName}  ${component.classification}${formatComponentOrigin(component.origin)}`,
+      );
+    }
+
+    lines.push("");
+  }
+
+  if (report.diagnostics.length > 0) {
+    lines.push("Warnings:");
+    for (const diagnostic of report.diagnostics) {
+      lines.push(`  ${diagnostic.code}: ${diagnostic.message}`);
+    }
+    lines.push("");
+  }
+
+  const summary = report.summary;
+  lines.push(
+    [
+      `Summary: ${summary.serverRenderRoutes} ${plural(summary.serverRenderRoutes, "server-render route")}`,
+      `${summary.clientRoutes} ${plural(summary.clientRoutes, "client route")}`,
+      `${summary.clientBoundaries} ${plural(summary.clientBoundaries, "client boundary")}`,
+      `${summary.serverRenderComponents} ${plural(summary.serverRenderComponents, "server-render component")}`,
+      `${summary.serverOnlyComponents} ${plural(summary.serverOnlyComponents, "server-only component")}`,
+      `${summary.sharedComponents} ${plural(summary.sharedComponents, "shared component")}`,
+      `${summary.unknownComponents} ${plural(summary.unknownComponents, "unknown component")}`,
+    ].join(", "),
+  );
+
+  return `${lines.join("\n")}\n`;
+}
+
+export function formatBoundaryReportJson(report: BoundaryReport): string {
+  return `${JSON.stringify(report, null, 2)}\n`;
+}
+
+function normalizeComponents(
+  projectRoot: string,
+  entry: string,
+  components: readonly ClientRouteComponent[],
+): BoundaryReportComponent[] {
+  const unique = new Map<string, BoundaryReportComponent>();
+
+  for (const component of components) {
+    const normalized = {
+      ...component,
+      file: projectRelativePath(projectRoot, component.file),
+    };
+    unique.set(
+      `${normalized.file}\0${normalized.exportName}\0${normalized.classification}`,
+      normalized,
+    );
+  }
+
+  return Array.from(unique.values()).sort((left, right) => {
+    const leftEntry = left.file === entry;
+    const rightEntry = right.file === entry;
+
+    if (leftEntry !== rightEntry) {
+      return leftEntry ? -1 : 1;
+    }
+
+    return left.file === right.file
+      ? left.exportName === right.exportName
+        ? left.classification.localeCompare(right.classification)
+        : left.exportName.localeCompare(right.exportName)
+      : left.file.localeCompare(right.file);
+  });
+}
+
+function summarizeBoundaryRoutes(routes: readonly BoundaryReportRoute[]): BoundaryReportSummary {
+  const components = routes.flatMap((route) => route.components);
+
+  return {
+    clientBoundaries: countClassification(components, "client-boundary"),
+    clientRoutes: routes.filter((route) => route.classification === "client-route").length,
+    serverOnlyComponents: countClassification(components, "server-only"),
+    serverRenderComponents: countClassification(components, "server-render"),
+    serverRenderRoutes: routes.filter((route) => route.classification === "server-render").length,
+    sharedComponents: countClassification(components, "shared"),
+    unknownComponents: countClassification(components, "unknown"),
+  };
+}
+
+function countClassification(
+  components: readonly BoundaryReportComponent[],
+  classification: ClientRouteComponentClassification,
+): number {
+  return components.filter((component) => component.classification === classification).length;
+}
+
+function projectRelativePath(projectRoot: string, file: string): string {
+  const value = relative(projectRoot, file).split(sep).join("/");
+  return value === "" ? "." : value;
+}
+
+function formatComponentOrigin(origin: ClientRouteComponentOrigin): string {
+  if (origin === "use-client-directive") return ' ("use client")';
+  if (origin === "use-server-directive") return ' ("use server")';
+  if (origin === "client-filename") return " (.client.*)";
+  if (origin === "compat-filename") return " (.compat.*)";
+  if (origin === "inferred-client-runtime") return " (inferred)";
+  if (origin === "server-only-import") return " (server-only import)";
+  if (origin === "unresolved-reference") return " (unresolved)";
+  return "";
+}
+
+function plural(count: number, singular: string): string {
+  return count === 1 ? singular : `${singular}s`;
+}

package/src/build.ts

@@ -36,8 +36,11 @@ import {
   navigationRuntimeLinkDisabledDiagnostic,
   resolveNavigationRuntime,
   type ClientRouteManifestEntry,
+  type ClientRouteComponent,
+  type ClientRouteInferenceDiagnostic,
   type ClientRouteInferenceCache,
 } from "./client-route-inference.js";
+import { createBoundaryReport, type BoundaryReport } from "./boundaries.js";
 import {
   buildClientRouteBatchOutput,
   buildNavigationRuntimeBundle,
@@ -129,6 +132,8 @@ export type AwsLambdaGeneratedHandlerPreloadMode =
 export interface BuildAppOptions extends AppRouterProjectOptions {
   awsLambdaPreload?: AwsLambdaGeneratedHandlerPreloadMode | undefined;
   awsLambdaPreloadRoutes?: readonly string[] | undefined;
+  /** Receives the full route and component boundary report after source analysis. */
+  onBoundaryReport?: ((report: BoundaryReport) => void) | undefined;
   onBuildProgress?: ((event: BuildAppProgressEvent) => void) | undefined;
   onBuildPhaseTiming?: ((timing: BuildAppPhaseTiming) => void) | undefined;
   outDir: string;
@@ -382,6 +387,8 @@ interface BuildRouteSourceAnalysis extends BuildSourceAnalysis {
   clientBoundaryImports: readonly string[];
   clientBoundaryFallbackImports: readonly string[];
   clientRoute: boolean;
+  components: readonly ClientRouteComponent[];
+  diagnostics: readonly ClientRouteInferenceDiagnostic[];
   file: string;
   route: AppRoute & { kind: "page" };
   routeCode: string;
@@ -389,6 +396,7 @@ interface BuildRouteSourceAnalysis extends BuildSourceAnalysis {
 }
 
 interface BuildSourceAnalysisScope {
+  boundaryReport: BoundaryReport;
   byFile: ReadonlyMap<string, BuildSourceAnalysis>;
   byRouteFile: ReadonlyMap<string, BuildRouteSourceAnalysis>;
 }
@@ -485,6 +493,7 @@ async function buildAppWithResolvedProject(
             vitePlugins,
           }),
         );
+  options.onBoundaryReport?.(sourceAnalysis.boundaryReport);
 
   if (shouldTrackBuildPhases === false) {
     await validateProductionRoutes({
@@ -1347,6 +1356,7 @@ async function analyzeBuildRouteSources(options: {
         appDir: options.project.routesDir,
         cache: options.clientRouteInferenceCache,
         code: stripRouteClientSource({ code: source, filename: route.file }),
+        collectComponents: true,
         filename: route.file,
         routePath: route.path,
         vitePlugins: options.vitePlugins,
@@ -1363,6 +1373,8 @@ async function analyzeBuildRouteSources(options: {
           clientBoundaryImports: clientInference.clientBoundaryImports,
           clientBoundaryFallbackImports: clientInference.clientBoundaryFallbackImports,
           clientRoute: clientInference.client,
+          components: clientInference.components ?? [],
+          diagnostics: clientInference.diagnostics,
           file,
           route,
           routeCode,
@@ -1384,7 +1396,19 @@ async function analyzeBuildRouteSources(options: {
     }
   }
 
-  return { byFile, byRouteFile };
+  return {
+    boundaryReport: createBoundaryReport({
+      projectRoot: options.projectRoot,
+      routes: Array.from(byRouteFile.values(), (analysis) => ({
+        components: analysis.components,
+        diagnostics: analysis.diagnostics,
+        entry: analysis.route.file,
+        path: analysis.route.path,
+      })),
+    }),
+    byFile,
+    byRouteFile,
+  };
 }
 
 function analyzeBuildSource(source: string, filename: string): BuildSourceAnalysis {

package/src/bundle-pipeline.ts

@@ -1,6 +1,6 @@
 import { builtinModules } from "node:module";
 import { access } from "node:fs/promises";
-import { dirname, extname, isAbsolute, join, resolve } from "node:path";
+import { basename, dirname, extname, isAbsolute, join, relative, resolve } from "node:path";
 import { pathToFileURL } from "node:url";
 import {
   build as viteBuild,
@@ -28,6 +28,7 @@ export interface RouterBundleOptions {
   platform: "browser" | "node";
   preserveExports?: boolean | undefined;
   root?: string | undefined;
+  sourceRegionModulePaths?: ReadonlySet<string> | undefined;
   plugins?: readonly RouterCompatPlugin[] | undefined;
   vitePlugins?: readonly PluginOption[] | undefined;
   sourceMap?: boolean | undefined;
@@ -47,6 +48,7 @@ export interface RouterBundleModulesOptions {
   platform: "browser" | "node";
   plugins?: readonly RouterCompatPlugin[] | undefined;
   root?: string | undefined;
+  sourceRegionModulePaths?: ReadonlySet<string> | undefined;
   vitePlugins?: readonly PluginOption[] | undefined;
   sourceMap?: boolean | undefined;
   target?: string | undefined;
@@ -351,7 +353,11 @@ async function bundleRouterModuleUncached(
 
   return {
     ...(assets.length === 0 ? {} : { assets }),
-    code: stripSourceMappingUrl(chunk.code),
+    code: sanitizeBundleCode(
+      chunk.code,
+      options.sourceRegionModulePaths,
+      options.root ?? dirname(options.filename),
+    ),
     ...(map !== undefined && typeof map.source === "string" ? { map: map.source } : {}),
   };
 }
@@ -448,7 +454,11 @@ export async function bundleRouterModules(
       const map = mapAssets.get(`${chunk.fileName}.map`);
 
       return {
-        code: stripSourceMappingUrl(chunk.code),
+        code: sanitizeBundleCode(
+          chunk.code,
+          options.sourceRegionModulePaths,
+          options.root ?? dirname(options.entries[0]?.filename ?? process.cwd()),
+        ),
         fileName: chunk.fileName,
         imports: chunk.imports ?? [],
         isEntry: chunk.isEntry === true,
@@ -577,6 +587,43 @@ function stripSourceMappingUrl(code: string): string {
   return code.replace(/\n?\/\/# sourceMappingURL=[^\n]+\.map\s*$/u, "");
 }
 
+function sanitizeBundleCode(
+  code: string,
+  sourceRegionModulePaths: ReadonlySet<string> | undefined,
+  root: string,
+): string {
+  const withoutSourceMapUrl = stripSourceMappingUrl(code);
+
+  if (sourceRegionModulePaths === undefined) {
+    return withoutSourceMapUrl;
+  }
+
+  const sourceRegionCandidates = new Set<string>();
+
+  for (const modulePath of sourceRegionModulePaths) {
+    sourceRegionCandidates.add(normalizeSourceRegionPath(modulePath));
+    sourceRegionCandidates.add(normalizeSourceRegionPath(relative(root, modulePath)));
+    sourceRegionCandidates.add(normalizeSourceRegionPath(relative(process.cwd(), modulePath)));
+  }
+
+  return withoutSourceMapUrl.replace(
+    /^\/\/#region ([^\r\n]+)$/gmu,
+    (match, sourcePathWithQuery: string) => {
+      const queryIndex = sourcePathWithQuery.indexOf("?");
+      const sourcePath =
+        queryIndex === -1 ? sourcePathWithQuery : sourcePathWithQuery.slice(0, queryIndex);
+
+      return sourceRegionCandidates.has(normalizeSourceRegionPath(sourcePath))
+        ? `//#region ${basename(normalizeSourceRegionPath(sourcePath))}${queryIndex === -1 ? "" : sourcePathWithQuery.slice(queryIndex)}`
+        : match;
+    },
+  );
+}
+
+function normalizeSourceRegionPath(path: string): string {
+  return path.replaceAll("\\", "/");
+}
+
 function virtualEntryPlugin(entryId: string, code: string): VitePlugin {
   return {
     name: "mreact-router-virtual-entry",

package/src/cli-options.ts

@@ -21,6 +21,7 @@ export interface ParsedCliArguments {
   help?: boolean | undefined;
   host?: string | undefined;
   hostPolicy?: RequestHostPolicy | undefined;
+  json?: boolean | undefined;
   log?: CliRequestLogMode | undefined;
   out?: string | undefined;
   port?: number | undefined;
@@ -49,6 +50,14 @@ export function parseCliArguments(argv: readonly string[]): ParsedCliArguments {
       continue;
     }
 
+    if (value === "--json") {
+      if (command !== "boundaries") {
+        throw new Error("--json is only supported by the boundaries command");
+      }
+      parsed.json = true;
+      continue;
+    }
+
     if (value === "--log") {
       parsed.log = parseCliRequestLogMode(readOptionValue(argv, index, "log"));
       index += 1;
@@ -255,6 +264,29 @@ export function formatCliHelp(command?: string | undefined): string {
     ].join("\n");
   }
 
+  if (command === "boundaries") {
+    return [
+      "Usage: mreact-router boundaries [appDir] [options]",
+      "",
+      "Inspect server and client component boundaries for every route without building.",
+      "",
+      "Project resolution:",
+      "  Without appDir, load the same Vite project configuration as build.",
+      "  With appDir, inspect that directory directly.",
+      "",
+      "Classifications:",
+      "  server-render, client-boundary, client-route, server-only, shared, unknown",
+      "",
+      "Options:",
+      "  --json          Print a machine-readable versioned report.",
+      "  -h, --help      Show this help message.",
+      "",
+      "Examples:",
+      "  mreact-router boundaries",
+      "  mreact-router boundaries src/app --json",
+    ].join("\n");
+  }
+
   if (command === "package") {
     return [
       "Usage: mreact-router package <target> [options]",
@@ -335,6 +367,7 @@ export function formatCliHelp(command?: string | undefined): string {
     "Commands:",
     "  dev [appDir]                              Start the development server.",
     `  build [appDir]                            Build ${defaultTargetLabel} artifacts by default.`,
+    "  boundaries [appDir]                       Inspect route and component boundaries.",
     "  build --target=aws-lambda                 Build Lambda artifacts including generated handler and import policy.",
     "  start [outDir]                            Serve built Node output.",
     "  package aws-lambda --from .mreact --out .lambda",
@@ -477,7 +510,9 @@ function parseCliPort(value: string): number {
     return port;
   }
 
-  throw new Error(`Unsupported port ${JSON.stringify(value)}. Expected an integer from 0 to 65535.`);
+  throw new Error(
+    `Unsupported port ${JSON.stringify(value)}. Expected an integer from 0 to 65535.`,
+  );
 }
 
 function parseCliHostPolicy(value: string): RequestHostPolicy {

package/src/cli.ts

@@ -9,6 +9,11 @@ import {
   type BuildAppPhase,
   type BuildAppProgressEvent,
 } from "./build.js";
+import {
+  analyzeAppBoundaries,
+  formatBoundaryReport,
+  formatBoundaryReportJson,
+} from "./boundaries.js";
 import {
   buildTargetsFromCliTarget,
   createCliRequestLogger,
@@ -70,6 +75,9 @@ if (parsed !== undefined) {
             ...(parsed.clientSourceMaps === undefined
               ? {}
               : { clientSourceMaps: parsed.clientSourceMaps }),
+            onBoundaryReport(report) {
+              console.log(formatBoundaryReport(report).trimEnd());
+            },
             onBuildProgress(event) {
               activeBuildPhase = updateBuildProgressLog(event, activeBuildPhase);
             },
@@ -90,6 +98,21 @@ if (parsed !== undefined) {
           }
           throw error;
         }
+      } else if (command === "boundaries") {
+        const loaded =
+          routeArg === undefined
+            ? await loadMreactRouterViteConfigDetails({ command: "build", cwd: process.cwd() })
+            : { project: { appDir: resolve(routeArg) }, viteConfig: undefined };
+        const report = await analyzeAppBoundaries({
+          ...loaded.project,
+          viteConfig: loaded.viteConfig,
+        });
+        console.log(
+          (parsed.json === true
+            ? formatBoundaryReportJson(report)
+            : formatBoundaryReport(report)
+          ).trimEnd(),
+        );
       } else if (command === "package") {
         if (routeArg === "aws-lambda") {
           const manifest = await packageAwsLambdaArtifact({

package/src/client-route-inference.ts

@@ -14,6 +14,9 @@ export {
   resolveNavigationRuntime,
   routeToClientManifestEntry,
   type ClientReferenceImport,
+  type ClientRouteComponent,
+  type ClientRouteComponentClassification,
+  type ClientRouteComponentOrigin,
   type ClientRouteInferenceCache,
   type ClientRouteInferenceDiagnostic,
   type ClientRouteInferenceResult,