@uniformdev/next-app-router-upgrade 0.0.0-stage → 0.2.0

package/src/scan.js

@@ -0,0 +1,523 @@
+import fs from "node:fs";
+import path from "node:path";
+import ts from "typescript";
+
+import { COMPOSITION_METADATA, findClientContextIssues, STABLE_CONTEXT_OPTIONS } from "./client-context.js";
+import {
+  REMOVED_CONFIG_KEYS,
+  REMOVED_EXPORTS,
+  REMOVED_OPTIONS,
+  REMOVED_PAGE_STATE_FIELDS,
+  RULES,
+} from "./rules.js";
+
+const SOURCE_EXTENSIONS = new Set([".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs", ".mts", ".cts"]);
+const SKIP_DIRS = new Set(["node_modules", ".next", ".git", "dist", "build", "out", "coverage", ".vercel", ".turbo"]);
+const SDK = "@uniformdev/next-app-router";
+const RESOLVERS = new Set(["resolveRouteFromCode", "resolvePlaygroundRoute"]);
+const LITE_MIDDLEWARE = new Set(["uniformMiddleware", "handleUniformRoute"]);
+const MIN_NEXT = [16, 0, 7];
+const STABLE = "The stable SDK (20.82 to 20.85)";
+
+/**
+ * Scans the project at `root` and returns { project, findings }.
+ * `contents` maps absolute file paths to text that replaces the file on disk. The migration uses it
+ * to scan its result before it writes the files.
+ */
+export function scanProject(root, { uniformDataDir, contents } = {}) {
+  const findings = [];
+  const add = (rule, details) => findings.push({ rule, ...RULES[rule], ...details });
+  const read = (file) => contents?.get(file) ?? fs.readFileSync(file, "utf8");
+
+  const pkg = readPackageJson(root, read);
+  const deps = { ...pkg?.dependencies, ...pkg?.devDependencies };
+  const project = {
+    root,
+    name: pkg?.name,
+    sdkVersion: deps[SDK],
+    usesV1: Boolean(deps["@uniformdev/canvas-next-rsc"]),
+    usesAkamaiWorker: false,
+    filesScanned: 0,
+    compositionsWithPersonalization: 0,
+  };
+
+  checkPackageJson(pkg, deps, add);
+
+  const files = listSourceFiles(root);
+  project.filesScanned = files.length;
+  const state = { usesLiteMiddleware: false, importsVercelFunctions: [] };
+  for (const file of files) {
+    scanSourceFile(root, file, add, state, read);
+  }
+  project.usesAkamaiWorker = Boolean(state.usesAkamaiWorker);
+
+  if (state.processPlaygroundPath && !state.middlewarePassesPlaygroundPath) {
+    add("playground-path", {
+      ...state.processPlaygroundPath,
+      message: "createPreviewGETRouteHandler gets processPlaygroundPath. The middleware of the developer preview accepts the same option, so that it finds the playground path for the locale.",
+      fix: "Give the same processPlaygroundPath function to the middleware.",
+    });
+  }
+
+  if (state.importsVercelFunctions.length && !deps["@vercel/functions"]) {
+    for (const where of state.importsVercelFunctions) {
+      add("vercel-functions-transitive", {
+        ...where,
+        message: `The app imports @vercel/functions, but package.json does not list it. ${STABLE} installs it as a dependency of the SDK. The developer preview makes it an optional peer dependency.`,
+        fix: "Add @vercel/functions to the dependencies in package.json.",
+      });
+    }
+  }
+
+  scanUniformData(root, uniformDataDir, project, add);
+  scanNotFoundRoutes(root, files, add);
+
+  if (state.usesLiteMiddleware) {
+    const count = project.compositionsWithPersonalization;
+    add("lite-mode-flicker", {
+      ...state.liteMiddlewareLocation,
+      message:
+        `${STABLE} chooses personalization and test variants in the middleware. With uniformMiddleware or handleUniformRoute, the developer preview renders the default variants on the server, and the browser changes them after hydration.` +
+        (count ? ` The uniform-data folder has ${count} composition(s) with a personalization or a test.` : ""),
+      fix: "No code change is required. To keep the first paint correct, turn on edge mode: migrate --edge <host>.",
+    });
+  }
+
+  if (project.sdkVersion) {
+    add("not-found-html", {
+      message:
+        `${STABLE} rewrites missing routes to /404 in the middleware. The developer preview calls notFound() while the page renders. The response is still 404, but Next.js sends an empty HTML shell, and the 404 content (also app/not-found.tsx) shows only after hydration. Tested with Next.js 16.2.10 and 16.4.0.`,
+      fix: "No code change is required. Visitors without JavaScript see an empty 404 page.",
+    });
+    add("redirect-status", {
+      message: "The page applies Uniform redirects. A 301 or 308 redirect gives a 308, and other redirects give a 307. A missing route gives notFound().",
+      fix: "No change is required.",
+    });
+  }
+
+  return { project, findings };
+}
+
+function readPackageJson(root, read = (file) => fs.readFileSync(file, "utf8")) {
+  try {
+    return JSON.parse(read(path.join(root, "package.json")));
+  } catch {
+    return undefined;
+  }
+}
+
+function parseVersion(range) {
+  const match = /(\d+)\.(\d+)\.(\d+)/.exec(range ?? "");
+  return match ? match.slice(1, 4).map(Number) : undefined;
+}
+
+function isLower(a, b) {
+  for (let i = 0; i < 3; i++) {
+    if (a[i] !== b[i]) return a[i] < b[i];
+  }
+  return false;
+}
+
+function checkPackageJson(pkg, deps, add) {
+  if (!pkg) return;
+  const where = { file: "package.json" };
+
+  const next = parseVersion(deps.next);
+  if (next && isLower(next, MIN_NEXT)) {
+    add("next-version", {
+      ...where,
+      message: `package.json has next ${deps.next}. The developer preview requires Next.js 16.0.7 or later.`,
+      fix: "Upgrade Next.js to 16.0.7 or later.",
+    });
+  }
+
+  // @uniformdev/toolbar-* and @uniformdev/context-edge have their own version lines.
+  const uniform = Object.entries(deps).filter(
+    ([name]) => name.startsWith("@uniformdev/") && !name.startsWith("@uniformdev/toolbar") && name !== "@uniformdev/context-edge"
+  );
+  const versions = new Set(uniform.map(([, version]) => version));
+  if (versions.size > 1) {
+    add("uniform-version-mismatch", {
+      ...where,
+      message: `The @uniformdev packages have different versions: ${uniform.map(([n, v]) => `${n}@${v}`).join(", ")}. Different versions can install two copies of @uniformdev/context.`,
+      fix: "Install all @uniformdev packages with the same version.",
+    });
+  }
+
+  if (deps["@uniformdev/toolbar-react"] && !pkg.overrides?.["@uniformdev/context"]) {
+    add("prerelease-peer-range", {
+      ...where,
+      message: "@uniformdev/toolbar-react has the peer range @uniformdev/context ^20.72. That range does not accept prerelease versions, so npm shows ERESOLVE for a developer preview version. A stable release is not affected.",
+      fix: 'For a prerelease version, add "overrides": { "@uniformdev/context": "$@uniformdev/context" } to package.json.',
+    });
+  }
+
+  if (deps["@uniformdev/context-edge"]) {
+    add("context-edge-dependency", {
+      ...where,
+      message: "The edge, vercel, cf-vinext and akamai entry points of @uniformdev/next-app-router contain @uniformdev/context-edge.",
+      fix: "You can remove @uniformdev/context-edge from package.json, if the app does not import it.",
+    });
+  }
+}
+
+export function listSourceFiles(root) {
+  const out = [];
+  const walk = (dir) => {
+    let entries;
+    try {
+      entries = fs.readdirSync(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const entry of entries) {
+      if (entry.isDirectory()) {
+        if (!SKIP_DIRS.has(entry.name) && !entry.name.startsWith(".")) walk(path.join(dir, entry.name));
+      } else if (SOURCE_EXTENSIONS.has(path.extname(entry.name)) && !entry.name.endsWith(".d.ts")) {
+        out.push(path.join(dir, entry.name));
+      }
+    }
+  };
+  walk(root);
+  return out.sort();
+}
+
+export function scriptKind(file) {
+  const ext = path.extname(file);
+  if (ext === ".tsx") return ts.ScriptKind.TSX;
+  if (ext === ".jsx") return ts.ScriptKind.JSX;
+  if (ext === ".ts" || ext === ".mts" || ext === ".cts") return ts.ScriptKind.TS;
+  return ts.ScriptKind.JS;
+}
+
+function scanSourceFile(root, file, add, state, read) {
+  const text = read(file);
+  const sf = ts.createSourceFile(file, text, ts.ScriptTarget.Latest, true, scriptKind(file));
+  const rel = path.relative(root, file);
+  const at = (node) => ({ file: rel, line: sf.getLineAndCharacterOfPosition(node.getStart(sf)).line + 1 });
+
+  const isConfigFile = /^uniform\.server\.config\.[cm]?[jt]s$/.test(path.basename(file));
+  const isMiddlewareFile = /^(src\/)?(middleware|proxy)\.[cm]?[jt]s$/.test(rel.split(path.sep).join("/"));
+
+  // Local names of SDK imports: local name -> { module, imported }.
+  const sdkLocals = new Map();
+  const sdkNamespaces = new Map();
+  let importsSdk = false;
+
+  for (const statement of sf.statements) {
+    if (!ts.isImportDeclaration(statement) || !ts.isStringLiteral(statement.moduleSpecifier)) continue;
+    const module = statement.moduleSpecifier.text;
+
+    if (module === "@vercel/functions" || module.startsWith("@vercel/functions/")) {
+      state.importsVercelFunctions.push(at(statement));
+    }
+    if (!module.startsWith(SDK)) continue;
+    importsSdk = true;
+    if (module === `${SDK}/akamai`) state.usesAkamaiWorker = true;
+
+    if (module === `${SDK}/cache`) {
+      add("cached-resolver", {
+        ...at(statement),
+        message: "The resolvers of @uniformdev/next-app-router/cache now use 'use cache' only for published content. Draft and editor requests are not cached.",
+        fix: "No change is required.",
+      });
+    }
+
+    const bindings = statement.importClause?.namedBindings;
+    if (bindings && ts.isNamespaceImport(bindings)) {
+      sdkNamespaces.set(bindings.name.text, module);
+    }
+    if (bindings && ts.isNamedImports(bindings)) {
+      for (const element of bindings.elements) {
+        const imported = (element.propertyName ?? element.name).text;
+        sdkLocals.set(element.name.text, { module, imported });
+        checkImportedName(module, imported, element, add, at, state);
+      }
+    }
+  }
+
+  if (isConfigFile) importsSdk = true;
+  if (isMiddlewareFile && text.includes("processPlaygroundPath")) state.middlewarePassesPlaygroundPath = true;
+
+  scanClientContext(sf, sdkLocals, add, at);
+
+  const resultVariables = new Set();
+
+  const visit = (node) => {
+    // ns.removedExport
+    if (ts.isPropertyAccessExpression(node) && ts.isIdentifier(node.expression)) {
+      const module = sdkNamespaces.get(node.expression.text);
+      if (module) checkImportedName(module, node.name.text, node, add, at, state);
+    }
+
+    // Removed options: { dataClient } and { pathPatternsWithVariations }.
+    if (importsSdk && (ts.isPropertyAssignment(node) || ts.isShorthandPropertyAssignment(node))) {
+      const name = propertyName(node.name);
+      if (name && REMOVED_OPTIONS[name]) {
+        add("removed-option", { ...at(node), message: `The option "${name}" is removed.`, fix: REMOVED_OPTIONS[name] });
+      }
+      if (name && REMOVED_CONFIG_KEYS[name] && (isConfigFile || isServerConfigContext(node))) {
+        add("removed-config-key", { ...at(node), message: `The server configuration option "${name}" is removed.`, fix: REMOVED_CONFIG_KEYS[name] });
+      }
+      if (name && STABLE_CONTEXT_OPTIONS[name] && (isConfigFile || isServerConfigContext(node))) {
+        add("context-storage-options", {
+          ...at(node),
+          message: `The server configuration option "context.${name}" came in 20.85.0. The developer preview does not have it.`,
+          fix: `Remove it. ${STABLE_CONTEXT_OPTIONS[name]}`,
+        });
+      }
+      if (name === "defaultConsent" && isMiddlewareFile && !isBooleanLiteral(node)) {
+        add("per-request-consent", {
+          ...at(node),
+          message: "The middleware writes the default consent into the page code. Each value makes a different cached page.",
+          fix: "If you use createUniformStaticParams, list each value in its defaultConsent option.",
+        });
+      }
+    }
+
+    // createPreviewGETRouteHandler({ processPlaygroundPath })
+    if (ts.isCallExpression(node) && ts.isIdentifier(node.expression) && sdkLocals.get(node.expression.text)?.imported === "createPreviewGETRouteHandler") {
+      const options = node.arguments[0];
+      const option = options && ts.isObjectLiteralExpression(options) && options.properties.find((p) => p.name && propertyName(p.name) === "processPlaygroundPath");
+      if (option) state.processPlaygroundPath ??= at(option);
+    }
+
+    // <UniformContext result={result}>...</UniformContext>, the API of 20.81.1-alpha.25.
+    if (ts.isJsxElement(node) || ts.isJsxSelfClosingElement(node)) {
+      const opening = ts.isJsxElement(node) ? node.openingElement : node;
+      const local = ts.isIdentifier(opening.tagName) ? sdkLocals.get(opening.tagName.text) : undefined;
+      if (local?.imported === "UniformContext" && local.module.startsWith(SDK)) {
+        const hasResult = opening.attributes.properties.some((p) => ts.isJsxAttribute(p) && p.name.getText(sf) === "result");
+        const hasChildren = ts.isJsxElement(node) && node.children.some((child) => !(ts.isJsxText(child) && child.containsOnlyTriviaWhiteSpaces));
+        if (hasResult || hasChildren) {
+          add("uniform-context-props", {
+            ...at(node),
+            message: "UniformContext no longer takes result or children. Render it once after the compositions of the page, or in the root layout. The primary composition sets the composition metadata and the default consent.",
+            fix: "Render the compositions, then <UniformContext />. Add pageComposition to the UniformResolvedComposition of the page.",
+          });
+        }
+      }
+    }
+
+    // <UniformComposition dataClient={...} />
+    if (ts.isJsxAttribute(node) && importsSdk) {
+      const name = node.name.getText(sf);
+      if (REMOVED_OPTIONS[name]) {
+        add("removed-option", { ...at(node), message: `The prop "${name}" is removed.`, fix: REMOVED_OPTIONS[name] });
+      }
+    }
+
+    // pageState.components and the other removed fields.
+    if (ts.isPropertyAccessExpression(node) && REMOVED_PAGE_STATE_FIELDS.includes(node.name.text)) {
+      if (endsWithPageState(node.expression)) {
+        add("removed-page-state-field", {
+          ...at(node),
+          message: `pageState.${node.name.text} is removed. The page code no longer contains evaluation results.`,
+          fix: node.name.text === "quirks" ? "Read quirks in the browser with useQuirks()." : "No replacement.",
+        });
+      }
+    }
+    if (ts.isVariableDeclaration(node) && ts.isObjectBindingPattern(node.name) && node.initializer && endsWithPageState(node.initializer)) {
+      for (const element of node.name.elements) {
+        const name = (element.propertyName ?? element.name).getText(sf);
+        if (REMOVED_PAGE_STATE_FIELDS.includes(name)) {
+          add("removed-page-state-field", { ...at(element), message: `pageState.${name} is removed.`, fix: "No replacement." });
+        }
+      }
+    }
+
+    // const result = await resolveRouteFromCode(...); result.code
+    if (ts.isVariableDeclaration(node) && ts.isIdentifier(node.name) && node.initializer) {
+      const call = unwrapAwait(node.initializer);
+      if (call && ts.isCallExpression(call) && ts.isIdentifier(call.expression)) {
+        const local = sdkLocals.get(call.expression.text);
+        if (local && RESOLVERS.has(local.imported)) resultVariables.add(node.name.text);
+      }
+    }
+    const isResolverCall = (expression) => {
+      const call = unwrapAwait(expression);
+      if (!call || !ts.isCallExpression(call) || !ts.isIdentifier(call.expression)) return false;
+      return RESOLVERS.has(sdkLocals.get(call.expression.text)?.imported);
+    };
+    if (
+      ts.isPropertyAccessExpression(node) &&
+      node.name.text === "code" &&
+      ((ts.isIdentifier(node.expression) && resultVariables.has(node.expression.text)) || isResolverCall(node.expression))
+    ) {
+      add("result-code", { ...at(node), message: "ResolvedRouteResult no longer has a code field.", fix: "Keep the code from the [code] route parameter." });
+    }
+
+    // result.route.compositionApiResponse without a type check.
+    if (importsSdk && ts.isPropertyAccessExpression(node) && node.name.text === "compositionApiResponse") {
+      const target = node.expression;
+      if (ts.isPropertyAccessExpression(target) && target.name.text === "route" && !isNarrowedToComposition(node)) {
+        add("route-union", {
+          ...at(node),
+          message: "result.route can now also be a redirect, so TypeScript does not accept route.compositionApiResponse without a check.",
+          fix: 'Check result.route?.type === "composition" first, or call requireComposition(result).',
+        });
+      }
+    }
+
+    // Hard-coded old page codes.
+    if ((ts.isStringLiteral(node) || ts.isNoSubstitutionTemplateLiteral(node)) && /(^|\/)2~\d+~/.test(node.text)) {
+      add("old-page-code", { ...at(node), message: `The string "${node.text.slice(0, 60)}" has a page code in the old format. Old codes do not work.`, fix: "Link to the path of the page, not to /uniform/<code>." });
+    }
+
+    // Lite middleware.
+    if (isMiddlewareFile && ts.isCallExpression(node) && ts.isIdentifier(node.expression)) {
+      const local = sdkLocals.get(node.expression.text);
+      if (local && local.module === `${SDK}/middleware` && LITE_MIDDLEWARE.has(local.imported)) {
+        state.usesLiteMiddleware = true;
+        state.liteMiddlewareLocation ??= at(node);
+      }
+    }
+
+    ts.forEachChild(node, visit);
+  };
+  visit(sf);
+}
+
+function scanClientContext(sf, sdkLocals, add, at) {
+  const { hookArguments, props, options } = findClientContextIssues(sf, sdkLocals);
+  for (const { argument } of hookArguments) {
+    add("context-composition-metadata", {
+      ...at(argument),
+      message: "useInitUniformContext takes only the callback now. The SDK sends the composition metadata of the page composition to the Context.",
+      fix: "Remove the second argument of useInitUniformContext.",
+    });
+  }
+  for (const { element, name } of props) {
+    if (name === COMPOSITION_METADATA) {
+      add("context-composition-metadata", {
+        ...at(element),
+        message: "ClientContextComponentProps no longer has compositionMetadata.",
+        fix: "Remove the prop. Do not give it to useInitUniformContext.",
+      });
+    } else {
+      add("context-storage-options", {
+        ...at(element),
+        message: `ClientContextComponentProps has no "${name}" in the developer preview. It came in 20.85.0.`,
+        fix: `Remove the prop. ${STABLE_CONTEXT_OPTIONS[name]}`,
+      });
+    }
+  }
+  for (const { property, name } of options) {
+    add("context-storage-options", {
+      ...at(property),
+      message: `createClientUniformContext has no "${name}" option in the developer preview. It came in 20.85.0.`,
+      fix: `Remove the option. ${STABLE_CONTEXT_OPTIONS[name]}`,
+    });
+  }
+}
+
+function checkImportedName(module, imported, node, add, at) {
+  const removed = REMOVED_EXPORTS[module]?.[imported];
+  if (removed) {
+    add("removed-export", { ...at(node), message: `"${imported}" is no longer exported from ${module}.`, fix: removed });
+  }
+  if ((imported === "PersonalizeProps" || imported === "TestProps") && module.startsWith(SDK)) {
+    add("placement-props", {
+      ...at(node),
+      message: `${imported} changed: indexes is now defaultIndexes, index is now defaultIndex, and PersonalizeProps has a new personalization prop.`,
+      fix: "Update the custom placement component.",
+    });
+  }
+  if (imported === "createUniformStaticParams" || imported === "createUniformPlaygroundStaticParams") {
+    add("static-params", {
+      ...at(node),
+      message: `${imported} now makes one code for each path (and each defaultConsent and edgeMode value), not one for each variant combination.`,
+      fix: "No change is required. With edge mode, use edgeMode: [true, false].",
+    });
+  }
+}
+
+function propertyName(name) {
+  if (ts.isIdentifier(name) || ts.isStringLiteral(name)) return name.text;
+  return undefined;
+}
+
+function isBooleanLiteral(node) {
+  return ts.isPropertyAssignment(node) && (node.initializer.kind === ts.SyntaxKind.TrueKeyword || node.initializer.kind === ts.SyntaxKind.FalseKeyword);
+}
+
+function isServerConfigContext(node) {
+  for (let parent = node.parent; parent; parent = parent.parent) {
+    if (ts.isVariableDeclaration(parent) && parent.type && /UniformServerConfig/.test(parent.type.getText())) return true;
+    if (ts.isSatisfiesExpression?.(parent) && /UniformServerConfig/.test(parent.type.getText())) return true;
+  }
+  return false;
+}
+
+function endsWithPageState(expression) {
+  if (ts.isIdentifier(expression)) return expression.text === "pageState";
+  if (ts.isPropertyAccessExpression(expression)) return expression.name.text === "pageState";
+  return false;
+}
+
+function unwrapAwait(expression) {
+  let current = expression;
+  while (current && (ts.isAwaitExpression(current) || ts.isParenthesizedExpression(current))) current = current.expression;
+  return current;
+}
+
+// True when an enclosing if statement or conditional checks `.type === "composition"`.
+function isNarrowedToComposition(node) {
+  for (let parent = node.parent; parent; parent = parent.parent) {
+    const condition = ts.isIfStatement(parent) || ts.isConditionalExpression(parent) ? parent.expression ?? parent.condition : undefined;
+    if (condition && /\.type\s*===?\s*["']composition["']/.test(condition.getText())) return true;
+    if (ts.isFunctionLike(parent)) {
+      const body = parent.body?.getText() ?? "";
+      if (/requireComposition\(/.test(body) || /\.type\s*!==?\s*["']composition["']/.test(body)) return true;
+    }
+  }
+  return false;
+}
+
+function scanUniformData(root, uniformDataDir, project, add) {
+  const dir = path.resolve(root, uniformDataDir ?? "uniform-data");
+  if (!fs.existsSync(dir)) return;
+
+  const readYaml = (sub) => {
+    const folder = path.join(dir, sub);
+    if (!fs.existsSync(folder)) return [];
+    return fs
+      .readdirSync(folder)
+      .filter((f) => /\.(ya?ml|json)$/.test(f))
+      .map((f) => ({ file: path.relative(root, path.join(folder, f)), text: fs.readFileSync(path.join(folder, f), "utf8") }));
+  };
+
+  for (const { file, text } of readYaml("projectMapNode")) {
+    if (/queryStrings\s*:/.test(text) && !/queryStrings\s*:\s*\[\s*\]/.test(text)) {
+      add("project-map-query-strings", {
+        file,
+        message: "This project map node declares query strings. The developer preview middleware no longer reads them, and removes all query strings from the route path.",
+        fix: "List the query strings in the queryStrings option of the middleware.",
+      });
+    }
+  }
+
+  let withViz = 0;
+  for (const { text } of [...readYaml("composition"), ...readYaml("compositionPattern"), ...readYaml("componentPattern")]) {
+    if (/\$personalization|\$test\b/.test(text)) project.compositionsWithPersonalization++;
+    if (/\$viz/.test(text)) withViz++;
+  }
+  if (withViz) {
+    add("visibility-rules", {
+      file: path.relative(root, dir),
+      message: `${withViz} composition(s) or pattern(s) use visibility rules. These components render only in the browser, so they are not in the server HTML.`,
+      fix: "Do not put content for search engines in components with visibility rules.",
+    });
+  }
+}
+
+function scanNotFoundRoutes(root, files, add) {
+  const notFoundRoutes = files.filter((f) => /(^|\/)app\/(.*\/)?404\/page\.[jt]sx?$/.test(path.relative(root, f).split(path.sep).join("/")));
+  for (const file of notFoundRoutes) {
+    add("not-found-page", {
+      file: path.relative(root, file),
+      message: `${STABLE} rewrites missing routes to /404. The developer preview calls notFound() on the page, so this route no longer renders for missing pages.`,
+      fix: "Move the 404 content to app/not-found.tsx.",
+    });
+  }
+}