reverse-engineering-anything/src/domain/javascript/javascriptRoutePaths.ts

import { z } from "zod";
import { digestSchema } from "../digests.js";

const packageIdentitySchema = z.strictObject({
  path: z.string().min(1),
  sha256: digestSchema,
  container_sha256: digestSchema,
});
export const nextAppSourceContextSchema = z.discriminatedUnion("kind", [
  z.strictObject({
    kind: z.literal("app-directory"),
    directory: z.string().min(1),
    package: packageIdentitySchema,
  }),
  z.strictObject({
    kind: z.literal("compiled-directory"),
    directory: z.string().min(1),
    package: packageIdentitySchema,
  }),
  z.strictObject({
    kind: z.literal("outside-app-directory"),
    package: packageIdentitySchema,
  }),
  z.strictObject({
    kind: z.literal("unknown"),
    reason: z.string(),
    package: packageIdentitySchema.nullable(),
  }),
]);
export type NextAppSourceContext = z.infer<typeof nextAppSourceContextSchema>;
export type NextAppRouteContext =
  | { readonly kind: "source-path"; readonly source: NextAppSourceContext }
  | { readonly kind: "script-url" }
  | {
      readonly kind: "source-literal";
      readonly runtime: "next" | "unknown";
    }
  | { readonly kind: "source-reference" };

/** URL route syntax, independent of filesystem path normalization. */
export const routePath = (
  value: string,
  options: { relative?: boolean; navigation?: boolean } = {},
): string | undefined => {
  const end = options.navigation ? value.search(/[?#]/u) : -1;
  const path = end < 0 ? value : value.slice(0, end);
  if (!path || /[\u0000-\u0020\u007f\\]/u.test(path) || path.startsWith("//"))
    return;
  if (!path.startsWith("/") && !options.relative) return;
  if (/^[a-z][a-z0-9+.-]*:/iu.test(path)) return;
  return path.startsWith("/") ? path : `/${path}`;
};

export type NextAppRoutePath =
  | { readonly kind: "known"; readonly path: string }
  | { readonly kind: "unknown"; readonly reason: string };

/** Classify a page filename without treating missing routing context as absence. */
export const classifyNextAppRoutePath = (
  raw: string,
  context: NextAppRouteContext,
): NextAppRoutePath | undefined => {
  if (raw.includes("\\") || context.kind === "source-reference") return;
  let value = raw;
  if (
    context.kind === "script-url" ||
    (context.kind === "source-literal" && raw.includes("://"))
  ) {
    try {
      value = new URL(raw).pathname;
    } catch {
      return;
    }
  }
  // Ownership selects the routing root before page-segment conversion.
  let relative: string | undefined;
  let chunk = false;
  if (context.kind === "source-path") {
    if (context.source.kind === "outside-app-directory") return;
    if (
      context.source.kind === "app-directory" ||
      context.source.kind === "compiled-directory"
    ) {
      const prefix = `${context.source.directory}/`;
      if (!value.startsWith(prefix)) return;
      relative = value.slice(prefix.length);
      chunk = context.source.kind === "compiled-directory";
    }
  } else if (context.kind === "script-url" || context.runtime === "next") {
    const boundary = "/_next/static/chunks/app/";
    const assetRoot = value.indexOf(boundary);
    const localChunk = ["static/chunks/app/", ".next/static/chunks/app/"].find(
      (prefix) => value.startsWith(prefix),
    );
    if (assetRoot >= 0) {
      relative = value.slice(assetRoot + boundary.length);
      chunk = true;
    } else if (context.kind === "source-literal" && localChunk !== undefined) {
      relative = value.slice(localChunk.length);
      chunk = true;
    } else if (context.kind === "source-literal") {
      const prefix = value.startsWith("src/app/") ? "src/app/" : "app/";
      if (value.startsWith(prefix)) relative = value.slice(prefix.length);
    }
  }
  if (relative === undefined) {
    if (
      /(?:^|\/)app\/(?:.*\/)?page(?:\.[cm]?[jt]sx?|-[^/?#]+\.js|)(?:[?#].*)?$/u.test(
        value,
      )
    )
      return {
        kind: "unknown",
        reason:
          context.kind === "source-path" && context.source.kind === "unknown"
            ? context.source.reason
            : "The page-shaped path has no established Next App Router root or runtime context.",
      };
    return;
  }
  const match =
    /^(?:(.*?)\/)?page(?:-([^/?#]+)\.js|\.(?:[cm]?jsx?|tsx?)|)(?:[?#].*)?$/u.exec(
      relative,
    );
  if (match === null || (match[2] !== undefined && !chunk)) return;
  const sourceSegments = (match[1] ?? "").split("/");
  // A private folder excludes the whole page, including intercepted ancestors.
  // Keep filesystem segment spelling: only Next's explicit %5F escape is
  // normalized below; generic URI decoding merges distinct source filenames.
  if (sourceSegments.some((segment) => segment.startsWith("_"))) return;
  const segments: string[] = [];
  for (const sourceSegment of sourceSegments) {
    const segment = sourceSegment.replace(/%5F/gu, "_");
    if (/^\([^)]*\)$/u.test(segment) || segment.startsWith("@")) continue;
    // Intercepted routes need a parent routing context that a filename does not establish.
    if (segment.startsWith("("))
      return {
        kind: "unknown",
        reason:
          "An intercepted Next page route requires parent routing context unavailable from its filename.",
      };
    if (segment.includes("/") || segment === "." || segment === "..") return;
    const optional = /^\[\[\.\.\.([^\]]+)\]\]$/u.exec(segment);
    const catchAll = /^\[\.\.\.([^\]]+)\]$/u.exec(segment);
    const parameter = /^\[([^\]]+)\]$/u.exec(segment);
    segments.push(
      optional
        ? `:${optional[1]}*`
        : catchAll
          ? `:${catchAll[1]}+`
          : parameter
            ? `:${parameter[1]}`
            : segment,
    );
  }
  const path = routePath(`/${segments.filter(Boolean).join("/")}`);
  return path === undefined ? undefined : { kind: "known", path };
};

export const nextScriptBasePath = (source: string): string | undefined => {
  let path = source;
  if (/^https?:\/\//iu.test(source)) {
    try {
      path = new URL(source).pathname;
    } catch {
      return;
    }
  } else if (!source.startsWith("/")) return;
  const at = path.indexOf("/_next/");
  return at < 0 ? undefined : path.slice(0, at);
};