@uniformdev/next-app-router-upgrade 0.1.0 → 0.2.0

package/src/edge/common.js

@@ -0,0 +1,400 @@
+// Phase 2 steps that the hosts share: the edge middleware, the static params, the preview route
+// and the text edits for them.
+
+import fs from "node:fs";
+import path from "node:path";
+import ts from "typescript";
+
+import { addToBlock } from "../json-text.js";
+import { applyEdits } from "../migrate.js";
+import { listSourceFiles, scriptKind } from "../scan.js";
+
+export const SDK = "@uniformdev/next-app-router";
+export const EDGE_HEADER = "x-uniform-edge-origin";
+export const WEBHOOK_REMINDER =
+  "In Uniform, make sure that a webhook sends manifest.published, composition.*, entry.*, projectmap.node.* and redirect.* to /api/preview. The migration cannot check this.";
+const DEFAULT_SOURCE = "/((?!api|_next/static|_next/image|favicon.ico|sitemap.xml|robots.txt).*)";
+const MISSING_RULE = `[{ type: "header", key: "${EDGE_HEADER}" }]`;
+const LITE = new Set(["uniformMiddleware"]);
+// The edge middleware factories of the SDK, and their entry points.
+const EDGE_FACTORIES = {
+  vercelUniformEdgeMiddleware: `${SDK}/vercel`,
+  cfVinextUniformEdgeMiddleware: `${SDK}/cf-vinext`,
+  uniformEdgeMiddleware: `${SDK}/edge`,
+  handleUniformEdgeRoute: `${SDK}/edge`,
+};
+
+/**
+ * Returns { changes, contents, manual, reminders } for phase 2 on a host with an edge middleware.
+ * `host` is { factory, module, runtime, onRevalidateTags, packages, reminders }:
+ * - `factory` and `module`: the edge middleware and its entry point.
+ * - `runtime`: true when the middleware must run on the edge runtime, in middleware.ts.
+ * - `onRevalidateTags`: { name, module } of the function that the preview route must call, if any.
+ * - `packages`: [{ name, range, description }] to add to the dependencies.
+ * `base` maps absolute paths to the text after phase 1, so that the two phases make one plan.
+ */
+export function planEdge(root, { base = new Map(), host }) {
+  const read = (file) => base.get(file) ?? fs.readFileSync(file, "utf8");
+  const changes = [];
+  const contents = new Map();
+  const manual = [];
+  const save = (file, text, fileChanges) => {
+    if (text !== read(file)) contents.set(file, text);
+    changes.push(...fileChanges);
+  };
+
+  // Step 1: packages.
+  const pkgFile = path.join(root, "package.json");
+  let pkgText = read(pkgFile);
+  const pkg = JSON.parse(pkgText);
+  const pkgChanges = [];
+  for (const { name, range, description } of host.packages ?? []) {
+    if (pkg.dependencies?.[name] || pkg.devDependencies?.[name]) continue;
+    pkgText = addToBlock(pkgText, "dependencies", name, range);
+    pkgChanges.push({ file: "package.json", rule: "edge-package", description: `Add ${name} ${range}. ${description}` });
+  }
+  if (pkgChanges.length) save(pkgFile, pkgText, pkgChanges);
+
+  // Step 2: the middleware.
+  const middleware = findMiddlewareFile(root);
+  if (!middleware) {
+    manual.push(`No middleware.ts was found. Add middleware.ts with ${host.factory}, as in the docs.`);
+  } else if (host.runtime && /^proxy\./.test(path.basename(middleware))) {
+    manual.push(
+      `${path.relative(root, middleware)}: edge mode needs middleware.ts with runtime "experimental-edge" (vercel/next.js#82344). Rename the file to middleware.ts, and then run the migration again.`
+    );
+  } else {
+    const result = migrateEdgeMiddleware(root, middleware, read(middleware), host);
+    save(middleware, result.text, result.changes);
+    manual.push(...result.manual);
+  }
+
+  // Steps 3 and 4: static params and the preview route, in all source files.
+  const routes = migrateRouteFiles(root, read, { skip: middleware, onRevalidateTags: host.onRevalidateTags });
+  for (const { file, text, changes: fileChanges } of routes.files) save(file, text, fileChanges);
+  manual.push(...routes.manual);
+
+  return { changes, contents, manual, reminders: [...(host.reminders ?? []), WEBHOOK_REMINDER] };
+}
+
+/** Runs migrateRouteFile on each source file that imports the SDK. */
+export function migrateRouteFiles(root, read, { skip, onRevalidateTags } = {}) {
+  const files = [];
+  const manual = [];
+  for (const file of listSourceFiles(root)) {
+    if (file === skip) continue;
+    const text = read(file);
+    if (!text.includes(SDK)) continue;
+    const result = migrateRouteFile(root, file, text, { onRevalidateTags });
+    if (result.changes.length || result.manual.length) {
+      files.push({ file, text: result.text, changes: result.changes });
+      manual.push(...result.manual);
+    }
+  }
+  return { files, manual };
+}
+
+export function findMiddlewareFile(root) {
+  for (const dir of ["", "src"]) {
+    for (const name of ["middleware", "proxy"]) {
+      for (const ext of [".ts", ".js", ".mts", ".mjs", ".tsx", ".jsx"]) {
+        const file = path.join(root, dir, name + ext);
+        if (fs.existsSync(file)) return file;
+      }
+    }
+  }
+  return undefined;
+}
+
+export function parse(file, text) {
+  return ts.createSourceFile(file, text, ts.ScriptTarget.Latest, true, scriptKind(file));
+}
+
+export function sdkImports(sf) {
+  const locals = new Map();
+  for (const statement of sf.statements) {
+    if (!ts.isImportDeclaration(statement) || !ts.isStringLiteral(statement.moduleSpecifier)) continue;
+    const module = statement.moduleSpecifier.text;
+    if (!module.startsWith(SDK)) continue;
+    const bindings = statement.importClause?.namedBindings;
+    if (bindings && ts.isNamedImports(bindings)) {
+      for (const element of bindings.elements) {
+        locals.set(element.name.text, { module, imported: (element.propertyName ?? element.name).text, element, statement });
+      }
+    }
+  }
+  return locals;
+}
+
+// The middleware file
+
+/** Changes the middleware to `host.factory`. Refer to planEdge for `host`. */
+export function migrateEdgeMiddleware(root, file, text, host) {
+  const sf = parse(file, text);
+  const rel = path.relative(root, file);
+  const lineOf = (node) => sf.getLineAndCharacterOfPosition(node.getStart(sf)).line + 1;
+  const edits = [];
+  const changes = [];
+  const manual = [];
+  const record = (node, description) => changes.push({ file: rel, line: node ? lineOf(node) : undefined, rule: "edge-middleware", description });
+  const { factory, module } = host;
+
+  const locals = sdkImports(sf);
+  const usesEdge = [...locals.values()].some((info) => info.module === module && info.imported === factory);
+  const otherEdge = [...locals.values()].find((info) => EDGE_FACTORIES[info.imported] === info.module && info.imported !== factory);
+  const lite = [...locals.entries()].find(([, info]) => info.module === `${SDK}/middleware` && LITE.has(info.imported));
+  const handle = [...locals.entries()].find(([, info]) => info.module === `${SDK}/middleware` && info.imported === "handleUniformRoute");
+
+  if (!usesEdge && otherEdge) {
+    manual.push(`${rel}: the middleware uses ${otherEdge.imported}. Replace it with ${factory} from ${module}.`);
+  } else if (!usesEdge && lite) {
+    const [local, info] = lite;
+    // Swap the factory only when each reference is a call: uniformMiddleware({ ... }).
+    const references = [];
+    let other = false;
+    const visit = (node) => {
+      if (ts.isIdentifier(node) && node.text === local && node !== info.element.name && !ts.isImportSpecifier(node.parent)) {
+        if (ts.isCallExpression(node.parent) && node.parent.expression === node) references.push(node);
+        else other = true;
+      }
+      ts.forEachChild(node, visit);
+    };
+    visit(sf);
+
+    if (other || !references.length) {
+      manual.push(`${rel}: ${local} is used in a way that the migration cannot change. Replace it with ${factory} from ${module}.`);
+    } else {
+      for (const reference of references) {
+        edits.push({ start: reference.getStart(sf), end: reference.end, text: factory });
+        record(reference, `Replace ${local}(...) with ${factory}(...). It accepts the same options.`);
+      }
+      edits.push(...replaceImport(sf, info, factory, module));
+    }
+  } else if (!usesEdge && handle) {
+    manual.push(
+      `${rel}: the middleware calls handleUniformRoute in a custom function. Replace it with ${factory}(options)(request, event), or with handleUniformEdgeRoute. The migration does not change custom middleware.`
+    );
+  } else if (!usesEdge) {
+    manual.push(`${rel}: the middleware does not use uniformMiddleware. Add ${factory}, as in the docs.`);
+  }
+
+  // export const config = { matcher, runtime }
+  const config = findExportedConst(sf, "config");
+  const runtimeHint = host.runtime ? ', and runtime: "experimental-edge"' : "";
+  if (!config) {
+    const runtimeLine = host.runtime ? `\n  runtime: "experimental-edge",` : "";
+    const block = `\nexport const config = {\n  matcher: [\n    {\n      source: "${DEFAULT_SOURCE}",\n      missing: ${MISSING_RULE},\n    },\n  ],${runtimeLine}\n};\n`;
+    edits.push({ start: text.length, end: text.length, text: (text.endsWith("\n") ? "" : "\n") + block });
+    record(
+      undefined,
+      `Add the middleware config: the default matcher of the docs with the missing header rule${host.runtime ? ', and runtime "experimental-edge"' : ""}. Before, the middleware ran on all paths.`
+    );
+  } else if (!ts.isObjectLiteralExpression(config)) {
+    manual.push(`${rel}: the middleware config is not an object literal. Add missing: ${MISSING_RULE} to each matcher${runtimeHint}.`);
+  } else {
+    const matcher = findProperty(config, "matcher");
+    if (!matcher) {
+      edits.push(insertProperty(sf, config, `matcher: [{ source: "${DEFAULT_SOURCE}", missing: ${MISSING_RULE} }]`));
+      record(config, "Add a matcher with the missing header rule.");
+    } else if (ts.isPropertyAssignment(matcher)) {
+      const value = matcher.initializer;
+      if (ts.isStringLiteral(value) || ts.isNoSubstitutionTemplateLiteral(value)) {
+        edits.push({ start: value.getStart(sf), end: value.end, text: `[{ source: ${value.getText(sf)}, missing: ${MISSING_RULE} }]` });
+        record(matcher, "Change the matcher to an object with the missing header rule.");
+      } else if (ts.isArrayLiteralExpression(value)) {
+        for (const element of value.elements) {
+          if (ts.isStringLiteral(element) || ts.isNoSubstitutionTemplateLiteral(element)) {
+            edits.push({ start: element.getStart(sf), end: element.end, text: `{ source: ${element.getText(sf)}, missing: ${MISSING_RULE} }` });
+            record(element, "Add the missing header rule to the matcher.");
+          } else if (ts.isObjectLiteralExpression(element)) {
+            const missing = findProperty(element, "missing");
+            if (!missing) {
+              edits.push(insertProperty(sf, element, `missing: ${MISSING_RULE}`));
+              record(element, "Add the missing header rule to the matcher.");
+            } else if (!missing.getText(sf).includes(EDGE_HEADER)) {
+              if (ts.isPropertyAssignment(missing) && ts.isArrayLiteralExpression(missing.initializer)) {
+                edits.push(insertArrayElement(sf, missing.initializer, `{ type: "header", key: "${EDGE_HEADER}" }`));
+                record(missing, "Add the edge origin header to the missing rules of the matcher.");
+              } else {
+                manual.push(`${rel}:${lineOf(missing)}: add { type: "header", key: "${EDGE_HEADER}" } to the missing rules.`);
+              }
+            }
+          } else {
+            manual.push(`${rel}:${lineOf(element)}: add missing: ${MISSING_RULE} to this matcher.`);
+          }
+        }
+      } else {
+        manual.push(`${rel}:${lineOf(matcher)}: the matcher is not a literal. Add missing: ${MISSING_RULE} to each matcher.`);
+      }
+    }
+
+    if (host.runtime) {
+      const runtime = findProperty(config, "runtime");
+      if (!runtime) {
+        edits.push(insertProperty(sf, config, 'runtime: "experimental-edge"'));
+        record(config, 'Add runtime: "experimental-edge". The edge middleware needs the edge runtime.');
+      } else if (!/["'`](experimental-)?edge["'`]/.test(runtime.getText(sf))) {
+        manual.push(`${rel}:${lineOf(runtime)}: set runtime to "experimental-edge". The edge middleware needs the edge runtime (vercel/next.js#82344).`);
+      }
+    }
+  }
+
+  return { text: applyEdits(text, mergeInsertions(edits)), changes, manual };
+}
+
+function findExportedConst(sf, name) {
+  for (const statement of sf.statements) {
+    if (!ts.isVariableStatement(statement)) continue;
+    if (!statement.modifiers?.some((m) => m.kind === ts.SyntaxKind.ExportKeyword)) continue;
+    for (const declaration of statement.declarationList.declarations) {
+      if (ts.isIdentifier(declaration.name) && declaration.name.text === name) {
+        let value = declaration.initializer;
+        while (value && (ts.isSatisfiesExpression?.(value) || ts.isAsExpression(value) || ts.isParenthesizedExpression(value))) value = value.expression;
+        return value;
+      }
+    }
+  }
+  return undefined;
+}
+
+function findProperty(object, name) {
+  return object.properties.find((p) => p.name && (ts.isIdentifier(p.name) || ts.isStringLiteral(p.name)) && p.name.text === name);
+}
+
+// Route files: createUniformStaticParams and createPreviewPOSTRouteHandler
+
+/**
+ * Adds edgeMode: [true, false] to createUniformStaticParams. With `onRevalidateTags`
+ * ({ name, module, description }), also makes createPreviewPOSTRouteHandler call that function with
+ * the revalidated tags.
+ */
+export function migrateRouteFile(root, file, text, { onRevalidateTags } = {}) {
+  const sf = parse(file, text);
+  const rel = path.relative(root, file);
+  const lineOf = (node) => sf.getLineAndCharacterOfPosition(node.getStart(sf)).line + 1;
+  const edits = [];
+  const changes = [];
+  const manual = [];
+  const locals = sdkImports(sf);
+  const isCall = (node, imported) =>
+    ts.isCallExpression(node) && ts.isIdentifier(node.expression) && locals.get(node.expression.text)?.imported === imported;
+  let needsImport = false;
+  const expire = onRevalidateTags?.name;
+  const hasImport = [...locals.values()].some((info) => info.imported === expire);
+  const previewChange = onRevalidateTags?.description ?? `Expire the host cache when content is published: onRevalidateTags: ${expire}.`;
+
+  const visit = (node) => {
+    if (isCall(node, "createUniformStaticParams")) {
+      const options = node.arguments[0];
+      if (options && ts.isObjectLiteralExpression(options)) {
+        const edgeMode = findProperty(options, "edgeMode");
+        if (!edgeMode) {
+          edits.push(insertProperty(sf, options, "edgeMode: [true, false]"));
+          changes.push({ file: rel, line: lineOf(node), rule: "edge-static-params", description: "Add edgeMode: [true, false], so that the build prebuilds both edge mode values." });
+        } else if (!/\btrue\b/.test(edgeMode.getText(sf))) {
+          manual.push(`${rel}:${lineOf(edgeMode)}: add true to the edgeMode option of createUniformStaticParams.`);
+        }
+      } else {
+        manual.push(`${rel}:${lineOf(node)}: add edgeMode: [true, false] to the options of createUniformStaticParams.`);
+      }
+    }
+
+    if (expire && isCall(node, "createPreviewPOSTRouteHandler")) {
+      const options = node.arguments[0];
+      if (!options) {
+        const open = sf.getFullText().indexOf("(", node.expression.end);
+        edits.push({ start: open + 1, end: node.arguments.end, text: `{ onRevalidateTags: ${expire} }` });
+        changes.push({ file: rel, line: lineOf(node), rule: "edge-preview-route", description: previewChange });
+        needsImport = true;
+      } else if (ts.isObjectLiteralExpression(options)) {
+        const existing = findProperty(options, "onRevalidateTags");
+        if (!existing) {
+          edits.push(insertProperty(sf, options, `onRevalidateTags: ${expire}`));
+          changes.push({ file: rel, line: lineOf(node), rule: "edge-preview-route", description: previewChange });
+          needsImport = true;
+        } else if (!existing.getText(sf).includes(expire)) {
+          manual.push(`${rel}:${lineOf(existing)}: you have your own onRevalidateTags. Also call ${expire}(tags) from ${onRevalidateTags.module} in it.`);
+        }
+      } else {
+        manual.push(`${rel}:${lineOf(node)}: add onRevalidateTags: ${expire} to the options of createPreviewPOSTRouteHandler.`);
+      }
+    }
+    ts.forEachChild(node, visit);
+  };
+  visit(sf);
+
+  if (needsImport && !hasImport) edits.push(...addNamedImport(sf, expire, onRevalidateTags.module));
+  return { text: applyEdits(text, mergeInsertions(edits)), changes, manual };
+}
+
+// Text edits
+
+/** Inserts `property` as the last property of `object`, in the style of the object. */
+function insertProperty(sf, object, property) {
+  const text = sf.getFullText();
+  const props = object.properties;
+  if (!props.length) {
+    return { start: object.getStart(sf) + 1, end: object.end - 1, text: ` ${property} ` };
+  }
+  const last = props[props.length - 1];
+  let at = last.end;
+  const comma = /^\s*,/.exec(text.slice(at));
+  const trailingComma = Boolean(comma);
+  if (comma) at += comma[0].length;
+  const multiline = text.slice(object.getStart(sf), object.end).includes("\n");
+  if (!multiline) return { start: at, end: at, text: `${trailingComma ? "" : ","} ${property}${trailingComma ? "," : ""}` };
+  const indent = /([ \t]*)$/.exec(text.slice(0, last.getStart(sf)))[1];
+  return { start: at, end: at, text: `${trailingComma ? "" : ","}\n${indent}${property}${trailingComma ? "," : ""}` };
+}
+
+function insertArrayElement(sf, array, element) {
+  const fake = { properties: array.elements, getStart: (s) => array.getStart(s), end: array.end };
+  return insertProperty(sf, fake, element);
+}
+
+/** Replaces the import of `info` with `name` from `module`. */
+function replaceImport(sf, info, name, module) {
+  const statement = info.statement;
+  const named = statement.importClause.namedBindings;
+  const quote = statement.moduleSpecifier.getText(sf)[0];
+  const line = `import { ${name} } from ${quote}${module}${quote};`;
+  if (named.elements.length === 1 && !statement.importClause.name) {
+    return [{ start: statement.getStart(sf), end: statement.end, text: line }];
+  }
+  // Remove the specifier, and add the new import after the statement.
+  const elements = [...named.elements];
+  const i = elements.indexOf(info.element);
+  const removal =
+    i < elements.length - 1
+      ? { start: info.element.getStart(sf), end: elements[i + 1].getStart(sf), text: "" }
+      : { start: elements[i - 1].end, end: info.element.end, text: "" };
+  return [removal, { start: statement.end, end: statement.end, text: `\n${line}` }];
+}
+
+/** Adds `import { name } from module`, or adds `name` to an existing import from the module. */
+function addNamedImport(sf, name, module) {
+  const imports = sf.statements.filter(ts.isImportDeclaration);
+  const existing = imports.find((s) => ts.isStringLiteral(s.moduleSpecifier) && s.moduleSpecifier.text === module && s.importClause?.namedBindings && ts.isNamedImports(s.importClause.namedBindings));
+  if (existing) {
+    const elements = existing.importClause.namedBindings.elements;
+    const last = elements[elements.length - 1];
+    return [{ start: last.end, end: last.end, text: `, ${name}` }];
+  }
+  const quote = imports[0]?.moduleSpecifier.getText(sf)[0] ?? '"';
+  const line = `import { ${name} } from ${quote}${module}${quote};`;
+  const after = imports[imports.length - 1];
+  if (after) return [{ start: after.end, end: after.end, text: `\n${line}` }];
+  return [{ start: 0, end: 0, text: `${line}\n` }];
+}
+
+/** Joins insertions at the same position, so that applyEdits accepts them. */
+function mergeInsertions(edits) {
+  const out = [];
+  for (const edit of [...edits].sort((a, b) => a.start - b.start || a.end - b.end)) {
+    const previous = out[out.length - 1];
+    if (previous && previous.start === edit.start && previous.end === previous.start && edit.end === edit.start) {
+      previous.text += edit.text;
+    } else out.push({ ...edit });
+  }
+  return out;
+}

package/src/edge/index.js

@@ -1,5 +1,7 @@
 // Phase 2: edge mode for each host. Add a provider here when its migration is ready.
 
+import { planAkamaiEdge } from "./akamai.js";
+import { planCloudflareEdge } from "./cloudflare.js";
 import { planVercelEdge } from "./vercel.js";
 
 const DOCS = "https://docs.uniform.app/docs/sdk/nextjs-app-router/edge-mode";
@@ -14,9 +16,10 @@ export const PROVIDERS = {
   },
   cloudflare: {
     name: "Cloudflare",
-    available: false,
-    summary: "Coming soon.",
+    available: true,
+    summary: "cfVinextUniformEdgeMiddleware, for vinext on Cloudflare Workers.",
     docs: `${DOCS}#set-up-edge-mode-on-other-hosts`,
+    plan: planCloudflareEdge,
   },
   netlify: {
     name: "Netlify",
@@ -26,9 +29,10 @@ export const PROVIDERS = {
   },
   akamai: {
     name: "Akamai",
-    available: false,
-    summary: "Coming soon.",
+    available: true,
+    summary: "akamaiUniformEdgeWorker, an EdgeWorker in front of the app.",
     docs: `${DOCS}#set-up-edge-mode-on-other-hosts`,
+    plan: planAkamaiEdge,
   },
 };