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

package/src/session.js

@@ -0,0 +1,206 @@
+// The migration flow, shared by `migrate` and the interactive mode: plan, show, check, write.
+
+import fs from "node:fs";
+import path from "node:path";
+
+import { gitState, unifiedDiff, validate, writeAll } from "./apply.js";
+import { PROVIDERS } from "./edge/index.js";
+import { planMigration, uniformDependencies } from "./migrate.js";
+import { publishedAt } from "./registry.js";
+import { TARGET_VERSION } from "./report.js";
+import { scanProject } from "./scan.js";
+
+export const NAME = "uniform-next-app-router-upgrade";
+
+export function colors(enabled) {
+  return (code, s) => (enabled ? `\u001b[${code}m${s}\u001b[0m` : s);
+}
+
+/** Phase 1, and phase 2 when `edge` names a provider, as one plan. */
+export async function buildPlan(root, { edge, uniformData } = {}) {
+  const pkg = JSON.parse(fs.readFileSync(path.join(root, "package.json"), "utf8"));
+  const published = await publishedAt(uniformDependencies(pkg), TARGET_VERSION);
+  const phase1 = planMigration(root, { published });
+  let changes = phase1.changes.map((change) => ({ ...change, phase: 1 }));
+  let contents = phase1.contents;
+  let steps = [...phase1.manual];
+  let reminders = [];
+
+  if (edge) {
+    const phase2 = PROVIDERS[edge].plan(root, { base: phase1.contents });
+    changes = [...changes, ...phase2.changes.map((change) => ({ ...change, phase: 2 }))];
+    contents = new Map([...phase1.contents, ...phase2.contents]);
+    steps = [...steps, ...phase2.manual];
+    reminders = phase2.reminders ?? [];
+  }
+
+  const after = scanProject(root, { uniformDataDir: uniformData, contents });
+  return {
+    changes,
+    contents,
+    steps,
+    reminders,
+    manual: after.findings.filter((f) => f.severity === "error"),
+    reviews: after.findings.filter((f) => f.severity === "warning"),
+  };
+}
+
+/**
+ * Runs the migration and returns an exit code: 0 no code changes left, 1 manual changes left,
+ * 2 nothing was written.
+ * `ask(question, defaultYes)` returns a promise of true or false. Without it, the flow uses the
+ * options only.
+ */
+export async function executeMigration({ root, edge, dryRun, yes, allowDirty, color, uniformData, ask, interactive = false, diff = true }) {
+  const c = colors(color);
+  const plan = await buildPlan(root, { edge, uniformData });
+  const { changes, contents, steps, reminders, manual, reviews } = plan;
+
+  printChanges(root, changes, c);
+  if (changes.length && (diff === true || (diff === "ask" && ask && (await ask("Show the diff?", true))))) {
+    for (const [file, text] of contents) {
+      console.log(unifiedDiff(path.relative(root, file), fs.readFileSync(file, "utf8"), text, { color }));
+      console.log("");
+    }
+  }
+  printManual(manual, reviews, steps, c);
+  if (reminders.length) {
+    console.log(c("36;1", "Reminders:"));
+    for (const reminder of reminders) console.log(`  ${c("36", "•")} ${reminder}`);
+    console.log("");
+  }
+
+  const exitCode = manual.length || steps.length ? 1 : 0;
+  if (!changes.length || !contents.size) return exitCode;
+
+  const problems = validate(contents);
+  if (problems.length) {
+    console.error(c("31;1", "Nothing was written. A change makes a file that does not parse:"));
+    for (const problem of problems) console.error(`  ${path.relative(root, problem.file)}: ${problem.message}`);
+    console.error("Please report this problem to Uniform, with the file.");
+    return 2;
+  }
+
+  if (dryRun) {
+    console.log(c("1", "Dry run: no files were changed."));
+    return exitCode;
+  }
+
+  const git = gitState(root, [...contents.keys()]);
+  if (!allowDirty && (git.notGit || git.dirty.length)) {
+    if (git.notGit) {
+      console.error(c("31;1", "The app is not in a git repository, so you cannot undo the changes with git."));
+    } else {
+      console.error(c("31;1", "These files contain changes that are not committed:"));
+      for (const file of git.dirty) console.error(`  ${file}`);
+    }
+    // Only the interactive mode asks. With options, --allow-dirty is the only way past this check.
+    const proceed = interactive && ask ? await ask("Write the changes anyway?", false) : false;
+    if (!proceed) {
+      console.error(interactive ? "Nothing was written." : "Nothing was written. Commit or stash the changes first, or use --allow-dirty.");
+      return 2;
+    }
+  }
+
+  if (!yes) {
+    let approved = false;
+    if (ask) approved = await ask(`Write ${changes.length} change(s) to ${contents.size} file(s)?`, false);
+    else {
+      console.error("Nothing was written. To write the changes in a shell without a terminal, use --yes.");
+      return 2;
+    }
+    if (!approved) {
+      console.log("Nothing was written.");
+      return 2;
+    }
+  }
+
+  try {
+    writeAll(contents);
+  } catch (error) {
+    console.error(c("31;1", `Nothing was written: ${error.message}`));
+    return 2;
+  }
+
+  console.log(c("32;1", `Wrote ${changes.length} change(s) to ${contents.size} file(s).`));
+  console.log("");
+  console.log("Next steps:");
+  const next = [
+    "Install the new versions: npm install (or pnpm install, or yarn).",
+    ...(manual.length + steps.length ? [`Do the ${manual.length + steps.length} manual change(s) above.`] : []),
+    `Run the check again: ${NAME} check`,
+    edge === "vercel"
+      ? "Build and start the app, and do the edge mode test of the docs: next build && next start"
+      : edge
+        ? `Build and deploy the app${edge === "akamai" ? " and the EdgeWorker" : ""}, and do the edge mode test of the docs.`
+        : "Build and test the app: next build",
+    "Read the changes: git diff",
+  ];
+  next.forEach((step, i) => console.log(`  ${i + 1}. ${step}`));
+  if (edge) console.log(c("2", `  Docs: ${PROVIDERS[edge].docs}`));
+  console.log("");
+  return exitCode;
+}
+
+function printChanges(root, changes, c) {
+  if (!changes.length) {
+    console.log("No automatic changes are necessary.");
+    console.log("");
+    return;
+  }
+  for (const phase of [1, 2]) {
+    const items = changes.filter((change) => change.phase === phase);
+    if (!items.length) continue;
+    const title = phase === 1 ? "Phase 1: upgrade the SDK" : "Phase 2: turn on edge mode";
+    console.log(c("1", `${title} (${items.length} automatic change(s)):`));
+    for (const change of items) console.log(`  ${c("32", "•")} ${change.file}${change.line ? `:${change.line}` : ""}  ${change.description}`);
+    console.log("");
+  }
+}
+
+function printManual(manual, reviews, steps, c) {
+  if (manual.length || steps.length) {
+    console.log(c("31;1", `Manual changes (${manual.length + steps.length}). The migration does not change this code, because the correct change depends on your app:`));
+    for (const step of steps) console.log(`  ${c("31", "•")} ${step}`);
+    for (const f of manual) {
+      console.log(`  ${c("31", "•")} ${f.file ? `${f.file}${f.line ? `:${f.line}` : ""}  ` : ""}${f.message}`);
+      console.log(`    Fix: ${f.fix}`);
+    }
+    console.log("");
+  } else {
+    console.log(c("32", "No manual code changes are necessary."));
+    console.log("");
+  }
+  if (reviews.length) {
+    console.log(c("33;1", `Behavior changes to review (${reviews.length}). For the details, run: ${NAME} check`));
+    for (const f of reviews) console.log(`  ${c("33", "•")} ${f.title}${f.file ? c("2", `  (${f.file}${f.line ? `:${f.line}` : ""})`) : ""}`);
+    console.log("");
+  }
+}
+
+/** A short status of the project, for the interactive mode. */
+export function projectStatus(root, { uniformData } = {}) {
+  const scan = scanProject(root, { uniformDataDir: uniformData });
+  const pkg = JSON.parse(fs.readFileSync(path.join(root, "package.json"), "utf8"));
+  const deps = { ...pkg.dependencies, ...pkg.devDependencies };
+  const phase1 = planMigration(root);
+  const text = (file) => (fs.existsSync(file) ? fs.readFileSync(file, "utf8") : "");
+  const middleware = ["middleware.ts", "middleware.js", "src/middleware.ts", "src/middleware.js", "proxy.ts", "src/proxy.ts"]
+    .map((file) => text(path.join(root, file)))
+    .join("\n");
+  return {
+    scan,
+    sdkVersion: deps["@uniformdev/next-app-router"],
+    atTarget: deps["@uniformdev/next-app-router"] === TARGET_VERSION,
+    phase1Pending: phase1.changes.length,
+    edgeMode: /vercelUniformEdgeMiddleware/.test(middleware)
+      ? "vercel"
+      : /cfVinextUniformEdgeMiddleware/.test(middleware)
+        ? "cloudflare"
+        : scan.project.usesAkamaiWorker
+          ? "akamai"
+          : /uniformEdgeMiddleware|handleUniformEdgeRoute/.test(middleware)
+            ? "custom"
+            : undefined,
+  };
+}