@spectrabrain/eds 0.3.0 → 0.3.1

package/consumer/align-analysis.mjs

@@ -20,6 +20,18 @@ import {
   generatedStylesFileName,
   layerOrder,
   minimumMajors,
+  minimumPluginReactVersion,
+  minimumTailwindViteVersion,
+  minimumVersions,
+  maximumSupportedViteMajor,
+  preservedMockCamelCaseFilePattern,
+  preservedResourceDirectoryNames,
+  preservedResourceDirectoryPattern,
+  preservedMockPathPattern,
+  preservedResourceFilePattern,
+  preservedResourceHookPattern,
+  preservedResourceDependencyPattern,
+  preservedSourceHint,
   replacementRules,
   requiredDependencies,
   requiredDevDependencies,
@@ -34,22 +46,58 @@ import {
   templateDevDependencies,
   testDirectoryNames,
   testFilePattern,
+  testHelperFilePattern,
+  testConfigFilePattern,
+  testSupportFilePattern,
   testSetupFilePattern,
-  testSupportHint,
   testToolingPattern,
   unsupportedFrameworks,
 } from "./align-rules.mjs";
-import { createExitError, generatedCssRelativePath, readTextIfExists, toPosix } from "./paths.mjs";
+import {
+  createExitError,
+  generatedCssRelativePath,
+  readTextIfExists,
+  toPosix,
+} from "./paths.mjs";
 
-const scriptExtensions = new Set([".ts", ".tsx", ".js", ".jsx", ".mts", ".cts", ".mjs", ".cjs"]);
+const scriptExtensions = new Set([
+  ".ts",
+  ".tsx",
+  ".js",
+  ".jsx",
+  ".mts",
+  ".cts",
+  ".mjs",
+  ".cjs",
+]);
 const javascriptExtensions = new Set([".js", ".jsx", ".mjs", ".cjs"]);
 const styleExtensions = new Set([".css", ".scss", ".sass", ".less", ".styl"]);
-const walkExcludedDirectories = new Set(["node_modules", "dist", "build", "coverage", "storybook-static", "out"]);
+const walkExcludedDirectories = new Set([
+  "node_modules",
+  "dist",
+  "build",
+  "coverage",
+  "storybook-static",
+  "out",
+]);
 const frontendSearchDepth = 3;
 const kebabCasePattern = /^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/;
-const koreanPattern = /[ㄱ-ㆎ가-힣]/;
-const eslintConfigNames = ["eslint.config.js", "eslint.config.mjs", "eslint.config.cjs", "eslint.config.ts", "eslint.config.mts", "eslint.config.cts"];
-const legacyEslintConfigNames = [".eslintrc", ".eslintrc.js", ".eslintrc.cjs", ".eslintrc.json", ".eslintrc.yml", ".eslintrc.yaml"];
+const eslintConfigNames = [
+  "eslint.config.js",
+  "eslint.config.mjs",
+  "eslint.config.cjs",
+  "eslint.config.ts",
+  "eslint.config.mts",
+  "eslint.config.cts",
+];
+const legacyEslintConfigNames = [
+  ".eslintrc",
+  ".eslintrc.js",
+  ".eslintrc.cjs",
+  ".eslintrc.json",
+  ".eslintrc.yml",
+  ".eslintrc.yaml",
+];
 const prettierConfigNames = [
   ".prettierrc",
   ".prettierrc.json",
@@ -66,7 +114,14 @@ const prettierConfigNames = [
   "prettier.config.mjs",
   "prettier.config.ts",
 ];
-const viteConfigNames = ["vite.config.ts", "vite.config.mts", "vite.config.cts", "vite.config.js", "vite.config.mjs", "vite.config.cjs"];
+const viteConfigNames = [
+  "vite.config.ts",
+  "vite.config.mts",
+  "vite.config.cts",
+  "vite.config.js",
+  "vite.config.mjs",
+  "vite.config.cjs",
+];
 // Packages an aligned frontend may declare besides the required ones; anything else is listed for review.
 const conventionalPackages = new Set([
   ...requiredDependencies,
@@ -82,8 +137,6 @@ const conventionalPackages = new Set([
   "react-virtuoso",
   "react-markdown",
   "remark-gfm",
-  "msw",
-  "@faker-js/faker",
   "@tailwindcss/postcss",
   "@tailwindcss/vite",
   "tailwindcss-animate",
@@ -99,23 +152,78 @@ const conventionalPackages = new Set([
 
 export function hashFile(filePath) {
   try {
-    return crypto.createHash("sha1").update(fs.readFileSync(filePath)).digest("hex");
+    return crypto
+      .createHash("sha1")
+      .update(fs.readFileSync(filePath))
+      .digest("hex");
   } catch {
     return null;
   }
 }
 
 function joinPosix(...parts) {
-  const joined = path.posix.join(...parts.filter((part) => part !== "" && part !== "."));
+  const joined = path.posix.join(
+    ...parts.filter((part) => part !== "" && part !== ".")
+  );
   return joined === "" ? "." : joined;
 }
 
-// Test files, files in test directories and test setup files are outside the conventions: every check skips them.
+// Match test paths so alignment checks leave them unchanged.
 export function isTestSupport(relativePath) {
   const parts = relativePath.split("/");
-  return testFilePattern.test(relativePath) ||
-    parts.slice(0, -1).some((part) => testDirectoryNames.includes(part)) ||
-    testSetupFilePattern.test(parts[parts.length - 1]);
+  return (
+    testFilePattern.test(relativePath) ||
+    testSupportFilePattern.test(parts[parts.length - 1]) ||
+    testHelperFilePattern.test(parts[parts.length - 1]) ||
+    parts.some((part) => testDirectoryNames.includes(part.toLowerCase())) ||
+    testSetupFilePattern.test(parts[parts.length - 1]) ||
+    testConfigFilePattern.test(parts[parts.length - 1])
+  );
+}
+
+function isPreservedDirectoryName(name, parts, index) {
+  const lowerName = name.toLowerCase();
+  const sourceIndex = parts.lastIndexOf("src");
+  const isMessageResourceDirectory =
+    lowerName === "messages" && (index === 0 || index === sourceIndex + 1);
+  return (
+    testDirectoryNames.includes(lowerName) ||
+    preservedResourceDirectoryNames.includes(lowerName) ||
+    isMessageResourceDirectory ||
+    preservedResourceDirectoryPattern.test(name) ||
+    preservedMockPathPattern.test(name)
+  );
+}
+
+function isInsidePreservedPath(relativePath, preservedPaths) {
+  const filePath = toPosix(relativePath).replace(/^\.\//, "");
+  return preservedPaths.some((entry) => {
+    const preservedPath = toPosix(entry)
+      .replace(/^\.\//, "")
+      .replace(/\/+$/, "");
+    return (
+      preservedPath === "" ||
+      preservedPath === "." ||
+      filePath === preservedPath ||
+      filePath.startsWith(preservedPath + "/")
+    );
+  });
+}
+
+export function isPreservedSourcePath(relativePath, preservedPaths = []) {
+  const parts = relativePath.split("/");
+  return (
+    isTestSupport(relativePath) ||
+    parts.some(
+      (part, index) =>
+        isPreservedDirectoryName(part, parts, index) ||
+        preservedResourceFilePattern.test(part) ||
+        preservedResourceHookPattern.test(part) ||
+        preservedMockPathPattern.test(part) ||
+        preservedMockCamelCaseFilePattern.test(part)
+    ) ||
+    isInsidePreservedPath(relativePath, preservedPaths)
+  );
 }
 
 // Blanks // and /* */ comments while keeping strings, template literals and every line break, so indices and
@@ -143,9 +251,13 @@ export function stripComments(source) {
       index = stop;
       continue;
     }
-    if (character === "\"" || character === "'") {
+    if (character === '"' || character === "'") {
       let end = index + 1;
-      while (end < source.length && source[end] !== character && source[end] !== "\n") {
+      while (
+        end < source.length &&
+        source[end] !== character &&
+        source[end] !== "\n"
+      ) {
         end += source[end] === "\\" ? 2 : 1;
       }
       output.push(source.slice(index, end + 1));
@@ -153,12 +265,21 @@ export function stripComments(source) {
       lastSignificant = character;
       continue;
     }
-    if (character === "`" || (character === "}" && templateDepth.length > 0 && templateDepth[templateDepth.length - 1] === 0)) {
+    if (
+      character === "`" ||
+      (character === "}" &&
+        templateDepth.length > 0 &&
+        templateDepth[templateDepth.length - 1] === 0)
+    ) {
       if (character === "}") {
         templateDepth.pop();
       }
       let end = index + 1;
-      while (end < source.length && source[end] !== "`" && !(source[end] === "$" && source[end + 1] === "{")) {
+      while (
+        end < source.length &&
+        source[end] !== "`" &&
+        !(source[end] === "$" && source[end + 1] === "{")
+      ) {
         end += source[end] === "\\" ? 2 : 1;
       }
       if (source[end] === "$") {
@@ -173,10 +294,18 @@ export function stripComments(source) {
       lastSignificant = "`";
       continue;
     }
-    if (character === "/" && (lastSignificant === "" || "(,=:[!&|?{};+-*%<>~^".includes(lastSignificant))) {
+    if (
+      character === "/" &&
+      (lastSignificant === "" ||
+        "(,=:[!&|?{};+-*%<>~^".includes(lastSignificant))
+    ) {
       let end = index + 1;
       let inClass = false;
-      while (end < source.length && source[end] !== "\n" && (inClass || source[end] !== "/")) {
+      while (
+        end < source.length &&
+        source[end] !== "\n" &&
+        (inClass || source[end] !== "/")
+      ) {
         if (source[end] === "\\") {
           end += 2;
           continue;
@@ -203,98 +332,6 @@ export function stripComments(source) {
   return output.join("");
 }
 
-// Spans of the string and template literals in comment-free code, with the regex-literal heuristic of stripComments.
-// A template literal is one span from its opening to its closing backtick, and `text` holds its static parts.
-function literalSpans(code) {
-  const spans = [];
-  const templates = [];
-  let index = 0;
-  let lastSignificant = "";
-  while (index < code.length) {
-    const character = code[index];
-    const open = templates[templates.length - 1];
-    if (character === "\"" || character === "'") {
-      let end = index + 1;
-      while (end < code.length && code[end] !== character && code[end] !== "\n") {
-        end += code[end] === "\\" ? 2 : 1;
-      }
-      spans.push({ start: index, end: end + 1, text: code.slice(index + 1, end) });
-      index = end + 1;
-      lastSignificant = character;
-      continue;
-    }
-    if (character === "`" || (character === "}" && open?.inExpression && open.depth === 0)) {
-      const template = character === "`" ? { start: index, text: "", depth: 0, inExpression: false } : open;
-      if (character === "`") {
-        templates.push(template);
-      }
-      template.inExpression = false;
-      let end = index + 1;
-      while (end < code.length && code[end] !== "`" && !(code[end] === "$" && code[end + 1] === "{")) {
-        end += code[end] === "\\" ? 2 : 1;
-      }
-      template.text += code.slice(index + 1, end);
-      if (code[end] === "$") {
-        template.inExpression = true;
-        template.depth = 0;
-        index = end + 2;
-        lastSignificant = "{";
-        continue;
-      }
-      templates.pop();
-      spans.push({ start: template.start, end: end + 1, text: template.text });
-      index = end + 1;
-      lastSignificant = "`";
-      continue;
-    }
-    if (character === "/" && (lastSignificant === "" || "(,=:[!&|?{};+-*%<>~^".includes(lastSignificant))) {
-      let end = index + 1;
-      let inClass = false;
-      while (end < code.length && code[end] !== "\n" && (inClass || code[end] !== "/")) {
-        if (code[end] === "\\") {
-          end += 2;
-          continue;
-        }
-        if (code[end] === "[") inClass = true;
-        if (code[end] === "]") inClass = false;
-        end += 1;
-      }
-      index = end + 1;
-      lastSignificant = "/";
-      continue;
-    }
-    if (open?.inExpression) {
-      if (character === "{") open.depth += 1;
-      if (character === "}") open.depth -= 1;
-    }
-    if (!/\s/.test(character)) {
-      lastSignificant = character;
-    }
-    index += 1;
-  }
-  return spans;
-}
-
-// Index of the first literal with Korean text that a + or += operator joins to other text, or -1. UI text is written
-// inline for now and moves to translation resources later, which needs whole sentences.
-export function koreanConcatenationIndex(code) {
-  for (const span of literalSpans(code)) {
-    if (!koreanPattern.test(span.text)) {
-      continue;
-    }
-    let before = span.start - 1;
-    while (before >= 0 && /\s/.test(code[before])) before -= 1;
-    let after = span.end;
-    while (after < code.length && /\s/.test(code[after])) after += 1;
-    const plusBefore = (code[before] === "+" && code[before - 1] !== "+") || (code[before] === "=" && code[before - 1] === "+");
-    const plusAfter = code[after] === "+" && code[after + 1] !== "+" && code[after + 1] !== "=";
-    if (plusBefore || plusAfter) {
-      return span.start;
-    }
-  }
-  return -1;
-}
-
 // JSON with comments and trailing commas (tsconfig.json, components.json).
 export function parseJsonc(text) {
   return JSON.parse(stripComments(text).replace(/,(\s*[}\]])/g, "$1"));
@@ -302,7 +339,11 @@ export function parseJsonc(text) {
 
 function lineNumberAt(text, index) {
   let line = 1;
-  for (let position = text.indexOf("\n"); position >= 0 && position < index; position = text.indexOf("\n", position + 1)) {
+  for (
+    let position = text.indexOf("\n");
+    position >= 0 && position < index;
+    position = text.indexOf("\n", position + 1)
+  ) {
     line += 1;
   }
   return line;
@@ -321,18 +362,31 @@ export function extractImports(source) {
   for (const pattern of importPatterns) {
     for (const match of code.matchAll(pattern)) {
       const specifierIndex = match.index + match[0].lastIndexOf(match[1]);
-      found.push({ specifier: match[1], line: lineNumberAt(code, specifierIndex) });
+      found.push({
+        specifier: match[1],
+        line: lineNumberAt(code, specifierIndex),
+      });
     }
   }
   return found.sort((left, right) => left.line - right.line);
 }
 
 export function packageNameOf(specifier) {
-  if (specifier.startsWith(".") || specifier.startsWith("/") || specifier.startsWith("@/") || specifier.startsWith("~/") || specifier.startsWith("node:")) {
+  if (
+    specifier.startsWith(".") ||
+    specifier.startsWith("/") ||
+    specifier.startsWith("@/") ||
+    specifier.startsWith("~/") ||
+    specifier.startsWith("node:")
+  ) {
     return null;
   }
   const parts = specifier.split("/");
-  return specifier.startsWith("@") ? (parts.length >= 2 ? parts[0] + "/" + parts[1] : null) : parts[0];
+  return specifier.startsWith("@")
+    ? parts.length >= 2
+      ? parts[0] + "/" + parts[1]
+      : null
+    : parts[0];
 }
 
 // Resolves an import made by a file under the source directory. Returns { path } relative to the source directory,
@@ -341,8 +395,15 @@ export function resolveSourceImport(fromRelativePath, specifier) {
   if (specifier.startsWith("@/")) {
     return { path: path.posix.normalize(specifier.slice(2)), alias: true };
   }
-  if (specifier === "." || specifier === ".." || specifier.startsWith("./") || specifier.startsWith("../")) {
-    const joined = path.posix.normalize(path.posix.join(path.posix.dirname(fromRelativePath), specifier));
+  if (
+    specifier === "." ||
+    specifier === ".." ||
+    specifier.startsWith("./") ||
+    specifier.startsWith("../")
+  ) {
+    const joined = path.posix.normalize(
+      path.posix.join(path.posix.dirname(fromRelativePath), specifier)
+    );
     if (joined === ".." || joined.startsWith("../")) {
       return { outside: true };
     }
@@ -354,9 +415,10 @@ export function resolveSourceImport(fromRelativePath, specifier) {
 export function classifyModule(relativePath) {
   const parts = relativePath.split("/");
   const layer = layerOrder.includes(parts[0]) ? parts[0] : null;
-  const slice = layer !== null && slicedLayers.has(layer) && parts.length >= 2
-    ? parts[1].replace(/\.[cm]?[jt]sx?$/, "")
-    : null;
+  const slice =
+    layer !== null && slicedLayers.has(layer) && parts.length >= 2
+      ? parts[1].replace(/\.[cm]?[jt]sx?$/, "")
+      : null;
   return { layer, slice };
 }
 
@@ -378,43 +440,90 @@ export function checkImportRule({ fromPath, specifier, line, srcLabel }) {
     return {
       level: "error",
       kind: "import",
-      message: location + " imports " + specifier + " (" + source.layer + " must not import the higher layer " + destination.layer + ")",
+      message:
+        location +
+        " imports " +
+        specifier +
+        " (" +
+        source.layer +
+        " must not import the higher layer " +
+        destination.layer +
+        ")",
     };
   }
-  const crossesSlice = sourceRank === destinationRank && source.slice !== null && destination.slice !== null && source.slice !== destination.slice;
-  if (crossesSlice && (source.layer === "pages" || source.layer === "features")) {
+  const crossesSlice =
+    sourceRank === destinationRank &&
+    source.slice !== null &&
+    destination.slice !== null &&
+    source.slice !== destination.slice;
+  if (
+    crossesSlice &&
+    (source.layer === "pages" || source.layer === "features")
+  ) {
     return {
       level: "error",
       kind: "import",
-      message: location + " imports " + specifier + " (" + source.layer + "/" + source.slice + " must not import another " +
-        source.layer + " slice, " + destination.slice + ")",
+      message:
+        location +
+        " imports " +
+        specifier +
+        " (" +
+        source.layer +
+        "/" +
+        source.slice +
+        " must not import another " +
+        source.layer +
+        " slice, " +
+        destination.slice +
+        ")",
     };
   }
   if (crossesSlice && source.layer === "widgets") {
     return {
       level: "warning",
       kind: "import",
-      message: location + " imports " + specifier + " (widgets/" + source.slice + " depends on widgets/" + destination.slice + ")",
+      message:
+        location +
+        " imports " +
+        specifier +
+        " (widgets/" +
+        source.slice +
+        " depends on widgets/" +
+        destination.slice +
+        ")",
     };
   }
-  if (!target.alias && (sourceRank !== destinationRank || source.slice !== destination.slice)) {
+  if (
+    !target.alias &&
+    (sourceRank !== destinationRank || source.slice !== destination.slice)
+  ) {
     return {
       level: "warning",
       kind: "import",
-      message: location + " imports " + specifier + " with a relative path across slices; use @/" + target.path,
+      message:
+        location +
+        " imports " +
+        specifier +
+        " with a relative path across slices; use @/" +
+        target.path,
     };
   }
   return null;
 }
 
-export function checkImports({ files, srcLabel }) {
+export function checkImports({ files, srcLabel, preservedPaths = [] }) {
   const findings = [];
   for (const file of files) {
-    if (isTestSupport(file.path)) {
+    if (isPreservedSourcePath(file.path, preservedPaths)) {
       continue;
     }
     for (const { specifier, line } of extractImports(file.contents)) {
-      const finding = checkImportRule({ fromPath: file.path, specifier, line, srcLabel });
+      const finding = checkImportRule({
+        fromPath: file.path,
+        specifier,
+        line,
+        srcLabel,
+      });
       if (finding !== null) {
         findings.push(finding);
       }
@@ -434,7 +543,8 @@ export function walkFiles(root) {
       if (entry.name.startsWith(".") && entry.isDirectory()) {
         continue;
       }
-      const relativePath = prefix === "" ? entry.name : prefix + "/" + entry.name;
+      const relativePath =
+        prefix === "" ? entry.name : prefix + "/" + entry.name;
       if (entry.isDirectory()) {
         if (!walkExcludedDirectories.has(entry.name)) {
           walk(path.join(directory, entry.name), relativePath);
@@ -448,23 +558,88 @@ export function walkFiles(root) {
   return files.sort();
 }
 
-export function checkStructure({ files, srcLabel }) {
+// Enumerate files under paths recorded relative to a repository root. Hidden resource directories are included.
+export function filesUnderPaths(root, relativePaths = []) {
+  const rootPath = path.resolve(root);
+  const files = new Set();
+  const excludedDirectories = new Set([...walkExcludedDirectories, ".git"]);
+  const isInsideRoot = (candidate) =>
+    candidate === rootPath || candidate.startsWith(rootPath + path.sep);
+  const addSymlink = (absolutePath, relativePath) => {
+    try {
+      if (isInsideRoot(fs.realpathSync(absolutePath)))
+        files.add(toPosix(relativePath));
+    } catch {
+      // A dangling symlink has no readable target to snapshot.
+    }
+  };
+  const walk = (absoluteDirectory, relativeDirectory) => {
+    for (const entry of fs.readdirSync(absoluteDirectory, {
+      withFileTypes: true,
+    })) {
+      const relativePath =
+        relativeDirectory === ""
+          ? entry.name
+          : relativeDirectory + "/" + entry.name;
+      const absolutePath = path.join(absoluteDirectory, entry.name);
+      if (entry.isDirectory()) {
+        if (!excludedDirectories.has(entry.name))
+          walk(absolutePath, relativePath);
+      } else if (entry.isFile()) {
+        files.add(toPosix(relativePath));
+      } else if (entry.isSymbolicLink()) {
+        addSymlink(absolutePath, relativePath);
+      }
+    }
+  };
+
+  for (const rawPath of relativePaths) {
+    if (typeof rawPath !== "string" || rawPath === "") continue;
+    const relativePath = toPosix(rawPath).replace(/^\.\//, "");
+    const absolutePath = path.resolve(rootPath, ...relativePath.split("/"));
+    if (!isInsideRoot(absolutePath)) continue;
+    let stat;
+    try {
+      stat = fs.lstatSync(absolutePath);
+    } catch {
+      continue;
+    }
+    if (stat.isDirectory()) {
+      walk(absolutePath, relativePath);
+    } else if (stat.isFile()) {
+      files.add(relativePath);
+    } else if (stat.isSymbolicLink()) {
+      addSymlink(absolutePath, relativePath);
+    }
+  }
+  return [...files].sort();
+}
+
+export function checkStructure({ files, srcLabel, preservedPaths = [] }) {
   const findings = [];
-  const error = (message) => findings.push({ level: "error", kind: "structure", message });
-  const warning = (message) => findings.push({ level: "warning", kind: "structure", message });
+  const error = (message) =>
+    findings.push({ level: "error", kind: "structure", message });
+  const warning = (message) =>
+    findings.push({ level: "warning", kind: "structure", message });
   const label = (relativePath) => joinPosix(srcLabel, relativePath);
   const reportedDirectories = new Set();
   // Required files a root-file move already names, so the same move is not reported twice.
   const movedTargets = new Set();
 
   for (const file of files) {
-    if (isTestSupport(file)) {
+    if (isPreservedSourcePath(file, preservedPaths)) {
       continue;
     }
     const parts = file.split("/");
     const extension = path.posix.extname(file);
     if (javascriptExtensions.has(extension) && !file.endsWith(".d.ts")) {
-      findings.push({ level: "error", kind: "language", message: label(file) + " is JavaScript; convert it to TypeScript (.ts or .tsx)" });
+      findings.push({
+        level: "error",
+        kind: "language",
+        message:
+          label(file) +
+          " is JavaScript; convert it to TypeScript (.ts or .tsx)",
+      });
     }
     if (parts.length === 1) {
       if (!allowedSourceRootFiles.includes(file)) {
@@ -472,45 +647,103 @@ export function checkStructure({ files, srcLabel }) {
         const [target, ...remark] = (hint ?? "").split(" ");
         if (target.includes("/")) {
           movedTargets.add(target);
-          error(label(file) + " must move to " + label(target) + (remark.length > 0 ? " " + remark.join(" ") : ""));
+          error(
+            label(file) +
+              " must move to " +
+              label(target) +
+              (remark.length > 0 ? " " + remark.join(" ") : "")
+          );
         } else {
-          error(label(file) + " must live inside a layer" + (hint ? " (" + hint + ")" : ""));
+          error(
+            label(file) +
+              " must live inside a layer" +
+              (hint ? " (" + hint + ")" : "")
+          );
         }
       }
       continue;
     }
     const [top] = parts;
-    if (!layerOrder.includes(top) && !auxiliarySourceDirectories.includes(top)) {
+    if (
+      !layerOrder.includes(top) &&
+      !auxiliarySourceDirectories.includes(top)
+    ) {
       if (!reportedDirectories.has(top)) {
         reportedDirectories.add(top);
         const hint = structureHints[top.toLowerCase()];
-        error(label(top) + "/ is not an FSD layer; move its files" +
-          (hint ? " to " + hint : " into app, pages, widgets, features, entities or shared") + " (under " + srcLabel + "/)");
+        error(
+          label(top) +
+            "/ is not an FSD layer; move its files" +
+            (hint
+              ? " to " + hint
+              : " into app, pages, widgets, features, entities or shared") +
+            " (under " +
+            srcLabel +
+            "/)"
+        );
       }
       continue;
     }
     if (top === "styles" && file !== "styles/" + generatedStylesFileName) {
-      error(label(file) + " must move: src/styles holds only " + generatedStylesFileName + ", which eds sync generates (global CSS goes in app/styles/index.css)");
+      error(
+        label(file) +
+          " must move: src/styles holds only " +
+          generatedStylesFileName +
+          ", which eds sync generates (global CSS goes in app/styles/index.css)"
+      );
       continue;
     }
     if (top === "types" && !file.endsWith(".d.ts")) {
-      warning(label(file) + " is not a declaration file; API types go in entities/<domain>/types and src/types keeps global .d.ts files");
+      warning(
+        label(file) +
+          " is not a declaration file; API types go in entities/<domain>/types and src/types keeps global .d.ts files"
+      );
     } else if (top === "app" && !appEntries.includes(parts[1])) {
-      warning(label(file) + " is outside the app layer entries (" + appEntries.join(", ") + ")");
+      warning(
+        label(file) +
+          " is outside the app layer entries (" +
+          appEntries.join(", ") +
+          ")"
+      );
     } else if (top === "shared" && !sharedSegments.includes(parts[1])) {
-      warning(label(file) + " is outside the shared segments (" + sharedSegments.join(", ") + ")");
+      warning(
+        label(file) +
+          " is outside the shared segments (" +
+          sharedSegments.join(", ") +
+          ")"
+      );
     } else if (top === "entities") {
       checkSliceNaming(parts, label, warning);
-      if (parts.length === 2 || (parts.length === 3 && parts[2] !== "index.ts")) {
-        warning(label(file) + " belongs in an entity segment (" + entitySegments.join(", ") + ")");
+      if (
+        parts.length === 2 ||
+        (parts.length === 3 && parts[2] !== "index.ts")
+      ) {
+        warning(
+          label(file) +
+            " belongs in an entity segment (" +
+            entitySegments.join(", ") +
+            ")"
+        );
       } else if (parts.length > 3 && !entitySegments.includes(parts[2])) {
-        warning(label(file) + " is outside the entity segments (" + entitySegments.join(", ") + ")");
+        warning(
+          label(file) +
+            " is outside the entity segments (" +
+            entitySegments.join(", ") +
+            ")"
+        );
       }
     } else if (top === "features") {
       checkSliceNaming(parts, label, warning);
       checkFeaturePath(parts, file, label, warning);
-    } else if (top === "pages" && extension === ".tsx" && path.posix.basename(file) !== "page.tsx") {
-      warning(label(file) + " is a page component not named page.tsx (pages/<domain>/<action>/page.tsx, or pages/<name>/page.tsx outside a backend resource); move shared parts to widgets or features");
+    } else if (
+      top === "pages" &&
+      extension === ".tsx" &&
+      path.posix.basename(file) !== "page.tsx"
+    ) {
+      warning(
+        label(file) +
+          " is a page component not named page.tsx (pages/<domain>/<action>/page.tsx, or pages/<name>/page.tsx outside a backend resource); move shared parts to widgets or features"
+      );
     }
   }
 
@@ -521,12 +754,18 @@ export function checkStructure({ files, srcLabel }) {
     }
   }
   // A misnamed slice is reported once, not once per file inside it.
-  return findings.filter((finding, index) => findings.findIndex((other) => other.message === finding.message) === index);
+  return findings.filter(
+    (finding, index) =>
+      findings.findIndex((other) => other.message === finding.message) === index
+  );
 }
 
 function checkSliceNaming(parts, label, warning) {
   if (parts.length >= 3 && !kebabCasePattern.test(parts[1])) {
-    warning(label(parts.slice(0, 2).join("/")) + " must be a lower-case domain name (for example accounts, device-groups)");
+    warning(
+      label(parts.slice(0, 2).join("/")) +
+        " must be a lower-case domain name (for example accounts, device-groups)"
+    );
   }
 }
 
@@ -538,7 +777,12 @@ function checkFeaturePath(parts, file, label, warning) {
   }
   if (parts.length === 3) {
     if (parts[2] !== "index.ts") {
-      warning(label(file) + " belongs in a feature segment (" + featureSegments.join(", ") + ")");
+      warning(
+        label(file) +
+          " belongs in a feature segment (" +
+          featureSegments.join(", ") +
+          ")"
+      );
     }
     return;
   }
@@ -546,52 +790,95 @@ function checkFeaturePath(parts, file, label, warning) {
     return;
   }
   if (!kebabCasePattern.test(parts[2])) {
-    warning(label(parts.slice(0, 3).join("/")) + " must be a kebab-case feature name (for example edit-device)");
+    warning(
+      label(parts.slice(0, 3).join("/")) +
+        " must be a kebab-case feature name (for example edit-device)"
+    );
   }
   if (parts.length === 4 && parts[3] !== "index.ts") {
-    warning(label(file) + " belongs in a feature segment (" + featureSegments.join(", ") + ")");
+    warning(
+      label(file) +
+        " belongs in a feature segment (" +
+        featureSegments.join(", ") +
+        ")"
+    );
   } else if (parts.length > 4 && !featureSegments.includes(parts[3])) {
-    warning(label(file) + " is outside the feature segments (" + featureSegments.join(", ") + ")");
+    warning(
+      label(file) +
+        " is outside the feature segments (" +
+        featureSegments.join(", ") +
+        ")"
+    );
   }
 }
 
 // Heuristics for the code patterns. They never fail the check: each is either fixed or justified in PLAN.md.
-export function checkPatterns({ files, allFiles, srcLabel }) {
+export function checkPatterns({
+  files,
+  allFiles,
+  srcLabel,
+  preservedPaths = [],
+}) {
   const findings = [];
-  const warning = (message) => findings.push({ level: "warning", kind: "pattern", message });
+  const warning = (message) =>
+    findings.push({ level: "warning", kind: "pattern", message });
   const label = (relativePath) => joinPosix(srcLabel, relativePath);
 
   for (const file of files) {
-    if (isTestSupport(file.path) || file.path.startsWith("mocks/") || file.path.endsWith(".d.ts")) {
+    if (
+      isPreservedSourcePath(file.path, preservedPaths) ||
+      file.path.endsWith(".d.ts")
+    ) {
       continue;
     }
     const code = stripComments(file.contents);
     const inSharedApi = file.path.startsWith("shared/api/");
     const fetchIndex = code.search(/(?<![\w$.])fetch\s*\(/);
     if (fetchIndex >= 0 && !inSharedApi) {
-      warning(label(file.path) + ":" + lineNumberAt(code, fetchIndex) + " calls fetch(); call the backend through shared/api and an entity service");
-    }
-    const axiosIndex = code.search(/\baxios\s*\.\s*(?:create|get|post|put|patch|delete|request)\s*\(/);
+      warning(
+        label(file.path) +
+          ":" +
+          lineNumberAt(code, fetchIndex) +
+          " calls fetch(); call the backend through shared/api and an entity service"
+      );
+    }
+    const axiosIndex = code.search(
+      /\baxios\s*\.\s*(?:create|get|post|put|patch|delete|request)\s*\(/
+    );
     if (axiosIndex >= 0 && !inSharedApi) {
-      warning(label(file.path) + ":" + lineNumberAt(code, axiosIndex) + " uses axios directly; use the instance from @/shared/api");
+      warning(
+        label(file.path) +
+          ":" +
+          lineNumberAt(code, axiosIndex) +
+          " uses axios directly; use the instance from @/shared/api"
+      );
     }
     const { layer } = classifyModule(file.path);
-    if (file.path.endsWith(".tsx") && ["widgets", "features", "entities", "shared"].includes(layer ?? "") && /\bexport\s+default\b/.test(code)) {
-      warning(label(file.path) + " has a default export; components outside pages use named exports");
-    }
-    const joinedIndex = koreanConcatenationIndex(code);
-    if (joinedIndex >= 0) {
-      warning(label(file.path) + ":" + lineNumberAt(code, joinedIndex) + " joins Korean text with +; write the sentence as one string " +
-        "(a template literal when it holds values) so it can move to a translation resource later");
+    if (
+      file.path.endsWith(".tsx") &&
+      ["widgets", "features", "entities", "shared"].includes(layer ?? "") &&
+      /\bexport\s+default\b/.test(code)
+    ) {
+      warning(
+        label(file.path) +
+          " has a default export; components outside pages use named exports"
+      );
     }
   }
 
   for (const file of allFiles) {
-    if (isTestSupport(file)) {
+    if (isPreservedSourcePath(file, preservedPaths)) {
       continue;
     }
-    if (styleExtensions.has(path.posix.extname(file)) && file !== "app/styles/index.css" && file !== "styles/" + generatedStylesFileName) {
-      warning(label(file) + " is a separate stylesheet; move global rules to app/styles/index.css and component styles to Tailwind classNames");
+    if (
+      styleExtensions.has(path.posix.extname(file)) &&
+      file !== "app/styles/index.css" &&
+      file !== "styles/" + generatedStylesFileName
+    ) {
+      warning(
+        label(file) +
+          " is a separate stylesheet; move global rules to app/styles/index.css and component styles to Tailwind classNames"
+      );
     }
   }
   return findings;
@@ -602,11 +889,168 @@ export function majorOf(version) {
   return match ? Number.parseInt(match[1], 10) : null;
 }
 
+function compareViteRangeVersions(left, right) {
+  const leftParts = versionParts(left);
+  const rightParts = versionParts(right);
+  for (let index = 0; index < 3; index += 1) {
+    if (leftParts[index] !== rightParts[index]) {
+      return leftParts[index] < rightParts[index] ? -1 : 1;
+    }
+  }
+  return 0;
+}
+
+function viteRangeUpperMajor(range) {
+  const clause = String(range ?? "").trim();
+  if (clause === "") return null;
+
+  const hyphenRange = clause.match(/^([^\s]+)\s+-\s+([^\s]+)$/);
+  if (hyphenRange) {
+    const upper = hyphenRange[2].match(
+      /^v?(\d+)(?:\.(\d+|x|\*))?(?:\.(\d+|x|\*))?$/i
+    );
+    return upper ? Number.parseInt(upper[1], 10) : null;
+  }
+
+  const tokens = clause.split(/[\s,]+/).filter(Boolean);
+  let upperMajor = Number.POSITIVE_INFINITY;
+  let hasUpperBound = false;
+  for (const token of tokens) {
+    const match = token.match(
+      /^(\^|~|>=|<=|>|<|=)?v?(\d+)(?:\.(\d+|x|\*))?(?:\.(\d+|x|\*))?(?:-[0-9A-Za-z.-]+)?$/i
+    );
+    if (!match) return null;
+    const operator = match[1] ?? "";
+    const major = Number.parseInt(match[2], 10);
+    const minor = /^\d+$/.test(match[3] ?? "")
+      ? Number.parseInt(match[3], 10)
+      : null;
+    const patch = /^\d+$/.test(match[4] ?? "")
+      ? Number.parseInt(match[4], 10)
+      : null;
+
+    if (["", "^", "~", "="].includes(operator)) {
+      upperMajor = Math.min(upperMajor, major);
+      hasUpperBound = true;
+    } else if (operator === "<" || operator === "<=") {
+      const boundMajor =
+        operator === "<" &&
+        (minor === null || minor === 0) &&
+        (patch === null || patch === 0)
+          ? major - 1
+          : major;
+      upperMajor = Math.min(upperMajor, boundMajor);
+      hasUpperBound = true;
+    }
+  }
+
+  return hasUpperBound ? upperMajor : null;
+}
+
+function viteRangeLowerVersion(range) {
+  const clause = String(range ?? "").trim();
+  if (clause === "") return null;
+
+  const hyphenRange = clause.match(/^([^\s]+)\s+-\s+([^\s]+)$/);
+  const tokens = hyphenRange
+    ? [hyphenRange[1]]
+    : clause.split(/[\s,]+/).filter(Boolean);
+  let lowerBound = null;
+  for (const token of tokens) {
+    const match = token.match(
+      /^(\^|~|>=|<=|>|<|=)?v?(\d+)(?:\.(\d+|x|\*))?(?:\.(\d+|x|\*))?$/i
+    );
+    if (!match) return null;
+    const operator = match[1] ?? "";
+    if (operator === "<" || operator === "<=") continue;
+
+    const major = Number.parseInt(match[2], 10);
+    const minor = /^\d+$/.test(match[3] ?? "")
+      ? Number.parseInt(match[3], 10)
+      : 0;
+    const patch = /^\d+$/.test(match[4] ?? "")
+      ? Number.parseInt(match[4], 10)
+      : 0;
+    const version = major + "." + minor + "." + patch;
+    const exclusive = operator === ">";
+    const comparison =
+      lowerBound === null
+        ? 1
+        : compareViteRangeVersions(version, lowerBound.version);
+    if (
+      lowerBound === null ||
+      comparison > 0 ||
+      (comparison === 0 && exclusive && !lowerBound.exclusive)
+    ) {
+      lowerBound = { version, exclusive };
+    }
+  }
+  return lowerBound?.version ?? null;
+}
+
+function analyzeViteRange(range) {
+  const alternatives = String(range ?? "")
+    .split("||")
+    .map((alternative) => alternative.trim());
+  if (alternatives.length === 0 || alternatives.some((value) => value === "")) {
+    return { status: "unknown", major: null };
+  }
+
+  const majors = [];
+  let unverified = false;
+  let outsideSingleMajor = false;
+  let belowMinimum = false;
+  for (const alternative of alternatives) {
+    const upperMajor = viteRangeUpperMajor(alternative);
+    if (upperMajor === null) {
+      unverified = true;
+      continue;
+    }
+    const lowerVersion = viteRangeLowerVersion(alternative);
+    if (lowerVersion === null) {
+      outsideSingleMajor = true;
+      continue;
+    }
+    const lowerMajor = majorOf(lowerVersion);
+    if (lowerMajor !== upperMajor) {
+      outsideSingleMajor = true;
+      continue;
+    }
+    majors.push(lowerMajor);
+    if (isOlderVersion(lowerVersion, minimumVersions.vite)) {
+      belowMinimum = true;
+    }
+  }
+
+  if (unverified) return { status: "unknown", major: null };
+  const uniqueMajors = [...new Set(majors)];
+  if (
+    outsideSingleMajor ||
+    uniqueMajors.length !== alternatives.length ||
+    uniqueMajors.length !== 1
+  ) {
+    return { status: "range", major: null };
+  }
+
+  const major = uniqueMajors[0];
+  if (major > maximumSupportedViteMajor) {
+    return { status: "unsupported", major };
+  }
+  if (belowMinimum) return { status: "range", major };
+  return { status: "verified", major };
+}
+
+export function hasVerifiedViteRange(range) {
+  return analyzeViteRange(range).status === "verified";
+}
+
 // Reads the installed version by walking node_modules upward, like Node's resolution, without honoring exports.
 export function installedVersion(packageDirectory, name) {
   let directory = packageDirectory;
   for (;;) {
-    const manifest = readTextIfExists(path.join(directory, "node_modules", name, "package.json"));
+    const manifest = readTextIfExists(
+      path.join(directory, "node_modules", name, "package.json")
+    );
     if (manifest !== null) {
       try {
         return String(JSON.parse(manifest).version ?? "") || null;
@@ -624,7 +1068,11 @@ export function installedVersion(packageDirectory, name) {
 
 export function declaredDependencies(packageJson) {
   const declared = new Map();
-  for (const section of ["dependencies", "devDependencies", "optionalDependencies"]) {
+  for (const section of [
+    "dependencies",
+    "devDependencies",
+    "optionalDependencies",
+  ]) {
     for (const [name, range] of Object.entries(packageJson?.[section] ?? {})) {
       if (!declared.has(name)) {
         declared.set(name, { range: String(range), section });
@@ -635,7 +1083,9 @@ export function declaredDependencies(packageJson) {
 }
 
 export function detectFramework(declared) {
-  const unsupported = unsupportedFrameworks.find(([name]) => declared.has(name));
+  const unsupported = unsupportedFrameworks.find(([name]) =>
+    declared.has(name)
+  );
   return {
     unsupported: unsupported ? unsupported[1] : null,
     react: declared.has("react"),
@@ -646,7 +1096,11 @@ export function detectFramework(declared) {
 // Dependency classification for the plan and the check. backendUsed lists packages the protected code imports.
 function versionParts(version) {
   const match = String(version ?? "").match(/(\d+)(?:\.(\d+))?(?:\.(\d+))?/);
-  return match ? [match[1], match[2] ?? "0", match[3] ?? "0"].map((part) => Number.parseInt(part, 10)) : null;
+  return match
+    ? [match[1], match[2] ?? "0", match[3] ?? "0"].map((part) =>
+        Number.parseInt(part, 10)
+      )
+    : null;
 }
 
 export function isOlderVersion(version, minimum) {
@@ -663,9 +1117,45 @@ export function isOlderVersion(version, minimum) {
   return false;
 }
 
+function isCompatibleVite8CompilerPeer(name, version) {
+  const parts = versionParts(version);
+  if (parts === null || /\d+\.\d+\.\d+-/.test(String(version))) {
+    return false;
+  }
+  if (name === rolldownBabelPackage) {
+    return (
+      (parts[0] === 0 &&
+        parts[1] === 1 &&
+        !isOlderVersion(version, minimumVersions.rolldownPluginForVite8)) ||
+      (parts[0] === 0 && parts[1] === 2)
+    );
+  }
+  if (name === "babel-plugin-react-compiler") {
+    return (
+      parts[0] === 1 &&
+      !isOlderVersion(version, minimumVersions.reactCompilerForVite8)
+    );
+  }
+  if (name === "@babel/core") {
+    return (
+      (parts[0] === 7 &&
+        !isOlderVersion(version, minimumVersions.babelCoreForVite8)) ||
+      parts[0] === 8
+    );
+  }
+  return false;
+}
+
 // toolVersions: the installed (or else declared) version of each templateToolMinimums package. restCalls: whether the
 // frontend code calls fetch() or axios, which keeps axios required next to a data SDK.
-export function classifyDependencies({ declared, majors = {}, backendUsed = new Set(), toolVersions = {}, restCalls = true }) {
+export function classifyDependencies({
+  declared,
+  majors = {},
+  backendUsed = new Set(),
+  toolVersions = {},
+  restCalls = true,
+  nodeVersion = process.versions.node,
+}) {
   const replacements = [];
   const replaced = new Set();
   for (const rule of replacementRules) {
@@ -682,14 +1172,45 @@ export function classifyDependencies({ declared, majors = {}, backendUsed = new
       }
     }
   }
-  const backendClients = backendClientPackages.filter((name) => declared.has(name));
-  const dataClients = backendDataClientPackages.filter((name) => declared.has(name));
-  const sdkOnly = dataClients.length > 0 && !restCalls && !declared.has("axios");
-  const backendServers = backendServerPackages.filter((name) => declared.has(name));
-  const viteMajor = majors.vite ?? majorOf(declared.get("vite")?.range);
+  const backendClients = backendClientPackages.filter((name) =>
+    declared.has(name)
+  );
+  const dataClients = backendDataClientPackages.filter((name) =>
+    declared.has(name)
+  );
+  const sdkOnly =
+    dataClients.length > 0 && !restCalls && !declared.has("axios");
+  const backendServers = backendServerPackages.filter((name) =>
+    declared.has(name)
+  );
+  const declaredViteRange = declared.get("vite")?.range ?? null;
+  const viteRange = declared.has("vite")
+    ? analyzeViteRange(declaredViteRange)
+    : null;
+  const installedViteMajor =
+    majors.vite ?? majorOf(toolVersions.vite);
+  const viteMajor = installedViteMajor ?? viteRange?.major ?? null;
+  const viteRangeMismatch =
+    viteRange?.status === "verified" &&
+    installedViteMajor !== null &&
+    installedViteMajor !== viteRange.major;
+  const unverifiedViteRange = viteRange?.status === "unknown";
+  const unsupportedViteRange =
+    declared.has("vite") &&
+    (viteRange?.status === "range" ||
+      viteRange?.status === "unknown" ||
+      viteRangeMismatch);
+  const unsupportedVite =
+    declared.has("vite") &&
+    (viteRange?.status !== "verified" || viteRangeMismatch);
+  const unsupportedNode =
+    viteMajor === 8 &&
+    (versionParts(nodeVersion) === null ||
+      isOlderVersion(nodeVersion, minimumVersions.nodeForVite8));
   const missing = [];
   for (const name of requiredDependencies) {
-    if (!declared.has(name)) missing.push({ name, dev: name === "tailwindcss" });
+    if (!declared.has(name))
+      missing.push({ name, dev: name === "tailwindcss" });
   }
   if (!sdkOnly && !declared.has("axios")) {
     missing.push({ name: "axios", dev: false });
@@ -697,8 +1218,12 @@ export function classifyDependencies({ declared, majors = {}, backendUsed = new
   for (const name of requiredDevDependencies) {
     if (!declared.has(name)) missing.push({ name, dev: true });
   }
-  if (viteMajor !== null && viteMajor >= 8 && !declared.has(rolldownBabelPackage)) {
-    missing.push({ name: rolldownBabelPackage, dev: true });
+  if (viteMajor === 8) {
+    for (const name of [rolldownBabelPackage, "@babel/core"]) {
+      if (!declared.has(name)) {
+        missing.push({ name, dev: true });
+      }
+    }
   }
   const outdated = [];
   for (const [name, minimum] of Object.entries(minimumMajors)) {
@@ -707,73 +1232,360 @@ export function classifyDependencies({ declared, majors = {}, backendUsed = new
       outdated.push({ name, major, minimum });
     }
   }
+  const pluginReactMinimum = minimumPluginReactVersion(viteMajor);
+  const pluginReactVersion =
+    toolVersions["@vitejs/plugin-react"] ??
+    declared.get("@vitejs/plugin-react")?.range;
+  const pluginReactParts = versionParts(pluginReactVersion);
+  const pluginReactMajor =
+    majors["@vitejs/plugin-react"] ??
+    pluginReactParts?.[0] ??
+    majorOf(declared.get("@vitejs/plugin-react")?.range);
+  const usesVite8Plugin = viteMajor === 8;
+  const pluginReactCompatible =
+    unsupportedVite ||
+    (pluginReactParts !== null &&
+      (usesVite8Plugin
+        ? pluginReactParts[0] === 6 &&
+          !isOlderVersion(pluginReactVersion, pluginReactMinimum)
+        : pluginReactParts[0] === 5 ||
+          (pluginReactParts[0] === 4 &&
+            !isOlderVersion(pluginReactVersion, pluginReactMinimum))));
+  if (
+    !unsupportedVite &&
+    declared.has("@vitejs/plugin-react") &&
+    !pluginReactCompatible
+  ) {
+    outdated.push({
+      name: "@vitejs/plugin-react",
+      major: pluginReactMajor ?? "unknown",
+      version: pluginReactParts?.join(".") ?? "unknown",
+      minimum: pluginReactMinimum,
+      allowedRange: usesVite8Plugin
+        ? "^" + pluginReactMinimum
+        : "^" + pluginReactMinimum + " or ^5",
+      requiredBy: "Vite " + (viteMajor ?? "5.2+"),
+    });
+  }
+  const vite8CompilerPeerRequirements = [
+    {
+      name: rolldownBabelPackage,
+      allowedRange: "^0.1.7 or ^0.2.0",
+    },
+    {
+      name: "babel-plugin-react-compiler",
+      allowedRange: "^1.0.0",
+    },
+    {
+      name: "@babel/core",
+      allowedRange: "^7.29.0 or ^8.0.0-rc.1",
+    },
+  ];
+  if (viteMajor === 8) {
+    for (const requirement of vite8CompilerPeerRequirements) {
+      if (!declared.has(requirement.name)) {
+        continue;
+      }
+      const version =
+        toolVersions[requirement.name] ??
+        declared.get(requirement.name).range;
+      if (!isCompatibleVite8CompilerPeer(requirement.name, version)) {
+        outdated.push({
+          name: requirement.name,
+          version: versionParts(version)?.join(".") ?? "unknown",
+          allowedRange: requirement.allowedRange,
+          requiredBy: "Vite 8 React Compiler",
+          compilerPeer: true,
+        });
+      }
+    }
+  }
+  const viteVersion = toolVersions.vite ?? declared.get("vite")?.range;
+  const viteParts = versionParts(viteVersion);
+  if (declared.has("vite")) {
+    if (unsupportedVite) {
+      outdated.push({
+        name: "vite",
+        major: viteMajor ?? "unknown",
+        version: viteParts?.join(".") ?? "unknown",
+        unsupported: true,
+        unsupportedRange:
+          unsupportedViteRange &&
+          !(viteMajor !== null && viteMajor > maximumSupportedViteMajor),
+        unverifiedRange: unverifiedViteRange,
+        range: declaredViteRange,
+      });
+    } else if (
+      viteParts === null ||
+      isOlderVersion(viteVersion, minimumVersions.vite)
+    ) {
+      outdated.push({
+        name: "vite",
+        major: viteParts?.[0] ?? majorOf(viteVersion),
+        version: viteParts?.join(".") ?? "unknown",
+        minimum: minimumVersions.vite,
+      });
+    }
+  }
+  const tailwindViteVersion =
+    toolVersions["@tailwindcss/vite"] ?? declared.get("@tailwindcss/vite")?.range;
+  const tailwindViteParts = versionParts(tailwindViteVersion);
+  const tailwindViteMinimum = minimumTailwindViteVersion(viteMajor);
+  if (
+    tailwindViteMinimum !== null &&
+    declared.has("@tailwindcss/vite") &&
+    (tailwindViteParts === null ||
+      isOlderVersion(tailwindViteVersion, tailwindViteMinimum))
+  ) {
+    outdated.push({
+      name: "@tailwindcss/vite",
+      major: tailwindViteParts?.[0] ?? majorOf(tailwindViteVersion),
+      version: tailwindViteParts?.join(".") ?? "unknown",
+      minimum: tailwindViteMinimum,
+      requiredBy: "Vite " + viteMajor,
+    });
+  }
   const outdatedTools = Object.entries(templateToolMinimums)
-    .filter(([name, minimum]) => declared.has(name) && isOlderVersion(toolVersions[name] ?? declared.get(name).range, minimum))
-    .map(([name, minimum]) => ({ name, version: versionParts(toolVersions[name] ?? declared.get(name).range).join("."), minimum }));
-  const others = [...declared.keys()].filter((name) =>
-    !replaced.has(name) && !conventionalPackages.has(name) && !backendClients.includes(name) && !backendServers.includes(name) &&
-    !backendUsed.has(name) && !testToolingPattern.test(name) && !name.startsWith("@radix-ui/") && !name.startsWith("@types/")).sort();
+    .filter(
+      ([name, minimum]) =>
+        declared.has(name) &&
+        isOlderVersion(toolVersions[name] ?? declared.get(name).range, minimum)
+    )
+    .map(([name, minimum]) => ({
+      name,
+      version: versionParts(
+        toolVersions[name] ?? declared.get(name).range
+      ).join("."),
+      minimum,
+    }));
+  const others = [...declared.keys()]
+    .filter(
+      (name) =>
+        !replaced.has(name) &&
+        !conventionalPackages.has(name) &&
+        !backendClients.includes(name) &&
+        !backendServers.includes(name) &&
+        !backendUsed.has(name) &&
+        !testToolingPattern.test(name) &&
+        !preservedResourceDependencyPattern.test(name) &&
+        !name.startsWith("@radix-ui/") &&
+        !name.startsWith("@types/")
+    )
+    .sort();
   const lucideRange = declared.get("lucide-react")?.range ?? null;
-  const lucideMismatch = lucideRange !== null && edsLucideVersion !== null && lucideRange.replace(/^[\^~=v]+/, "") !== edsLucideVersion ? lucideRange : null;
-  return { replacements, missing, outdated, outdatedTools, backendClients, dataClients, sdkOnly, backendServers, others, viteMajor, lucideMismatch };
+  const lucideMismatch =
+    lucideRange !== null &&
+    edsLucideVersion !== null &&
+    lucideRange.replace(/^[\^~=v]+/, "") !== edsLucideVersion
+      ? lucideRange
+      : null;
+  return {
+    replacements,
+    missing,
+    outdated,
+    outdatedTools,
+    unsupportedVite: unsupportedVite
+      ? viteRange?.status === "unsupported"
+        ? viteRange.major
+        : viteMajor !== null && viteMajor > maximumSupportedViteMajor
+          ? viteMajor
+          : unverifiedViteRange
+            ? "unknown"
+            : "range"
+      : null,
+    unsupportedViteRange,
+    unsupportedNode: unsupportedNode ? nodeVersion ?? "unknown" : null,
+    backendClients,
+    dataClients,
+    sdkOnly,
+    backendServers,
+    others,
+    viteMajor,
+    lucideMismatch,
+  };
 }
 
 export function checkDependencies(classification) {
   const findings = [];
+  if (classification.unsupportedNode) {
+    findings.push({
+      level: "error",
+      kind: "dependency",
+      message:
+        "Vite 8 React Compiler setup requires Node " +
+        minimumVersions.nodeForVite8 +
+        " or later; current Node is " +
+        classification.unsupportedNode,
+    });
+  }
   for (const entry of classification.replacements) {
     if (!entry.keptForBackend) {
-      findings.push({ level: "error", kind: "dependency", message: entry.name + " is still declared; replace it with " + entry.target + " (" + entry.category + ")" });
+      findings.push({
+        level: "error",
+        kind: "dependency",
+        message:
+          entry.name +
+          " is still declared; replace it with " +
+          entry.target +
+          " (" +
+          entry.category +
+          ")",
+      });
     }
   }
   for (const entry of classification.missing) {
-    findings.push({ level: "error", kind: "dependency", message: entry.name + " is not declared" + (entry.dev ? " (devDependencies)" : "") });
+    findings.push({
+      level: "error",
+      kind: "dependency",
+      message:
+        entry.name +
+        " is not declared" +
+        (entry.dev ? " (devDependencies)" : ""),
+    });
   }
   for (const entry of classification.outdated) {
-    findings.push({ level: "error", kind: "dependency", message: entry.name + " is major " + entry.major + "; the conventions use " + entry.minimum + " or later" });
+      findings.push({
+        level: "error",
+        kind: "dependency",
+        message:
+          entry.unsupported
+            ? entry.unsupportedRange
+              ? "Vite range " +
+                entry.range +
+                " must guarantee Vite 5.2.0 or later within one supported major; eds align supports Vite 5.2.0–" +
+                maximumSupportedViteMajor +
+                ".x"
+              : entry.version === "unknown"
+              ? "Vite version cannot be verified; eds align supports Vite 5.2.0–" +
+                maximumSupportedViteMajor +
+                ".x"
+              : "Vite " +
+                entry.version +
+                " is outside the supported range; eds align supports Vite 5.2.0–" +
+                maximumSupportedViteMajor +
+                ".x"
+            : entry.allowedRange !== undefined
+            ? entry.version === "unknown"
+              ? entry.name +
+                " version cannot be verified for " +
+              entry.requiredBy +
+              "; use " +
+              entry.name +
+              "@" +
+              entry.allowedRange
+            : entry.name +
+              " " +
+              entry.version +
+              " is incompatible with " +
+              entry.requiredBy +
+              "; use " +
+              entry.name +
+              "@" +
+              entry.allowedRange
+          : entry.version !== undefined
+            ? entry.version === "unknown"
+              ? entry.name +
+                " version cannot be verified; the minimum is " +
+                entry.minimum
+              : entry.name +
+                " " +
+                entry.version +
+                " is below the minimum " +
+                entry.minimum +
+                (entry.name === "vite"
+                  ? " required by @tailwindcss/vite 4"
+                  : " required for " + entry.requiredBy)
+            : entry.name +
+              " is major " +
+              entry.major +
+              "; the conventions use " +
+              entry.minimum +
+              " or later",
+    });
   }
   if (classification.lucideMismatch) {
     findings.push({
       level: "warning",
       kind: "dependency",
-      message: "lucide-react " + classification.lucideMismatch + " differs from the version EDS uses (" + edsLucideVersion + "); declare " + edsLucideVersion + " so the icon code is bundled once",
+      message:
+        "lucide-react " +
+        classification.lucideMismatch +
+        " differs from the version EDS uses (" +
+        edsLucideVersion +
+        "); declare " +
+        edsLucideVersion +
+        " so the icon code is bundled once",
     });
   }
   for (const entry of classification.outdatedTools ?? []) {
-    findings.push({ level: "error", kind: "config", message: entry.name + " " + entry.version + " is older than the eslint.config template requires (" + entry.minimum + ")" });
+    findings.push({
+      level: "error",
+      kind: "config",
+      message:
+        entry.name +
+        " " +
+        entry.version +
+        " is older than the eslint.config template requires (" +
+        entry.minimum +
+        ")",
+    });
   }
   return findings;
 }
 
 function findExisting(directory, names) {
-  return names.find((name) => fs.existsSync(path.join(directory, name))) ?? null;
+  return (
+    names.find((name) => fs.existsSync(path.join(directory, name))) ?? null
+  );
 }
 
 function readIgnoreLines(text) {
-  return (text ?? "").split(/\r?\n/).map((line) => line.trim()).filter((line) => line !== "" && !line.startsWith("#"));
+  return (text ?? "")
+    .split(/\r?\n/)
+    .map((line) => line.trim())
+    .filter((line) => line !== "" && !line.startsWith("#"));
 }
 
 export function ignoreCovers(lines, relativePath) {
-  const normalized = lines.map((line) => line.replace(/^\//, "").replace(/\/\*\*$/, "").replace(/\/$/, ""));
+  const normalized = lines.map((line) =>
+    line
+      .replace(/^\//, "")
+      .replace(/\/\*\*$/, "")
+      .replace(/\/$/, "")
+  );
   const parts = relativePath.split("/");
   for (let length = parts.length; length >= 1; length -= 1) {
     if (normalized.includes(parts.slice(0, length).join("/"))) {
       return true;
     }
   }
-  return normalized.includes(path.posix.basename(relativePath)) || normalized.includes("**/" + path.posix.basename(relativePath));
+  return (
+    normalized.includes(path.posix.basename(relativePath)) ||
+    normalized.includes("**/" + path.posix.basename(relativePath))
+  );
 }
 
 export function readScriptEntry(indexHtml) {
-  const tag = indexHtml.match(/<script\b[^>]*\btype=["']module["'][^>]*>/i)?.[0] ?? null;
+  const tag =
+    indexHtml.match(/<script\b[^>]*\btype=["']module["'][^>]*>/i)?.[0] ?? null;
   return tag?.match(/\bsrc=["']([^"']+)["']/i)?.[1] ?? null;
 }
 
 // Config and script checks. app.srcDir and app.appDir are relative to the package directory.
-export function checkConfigs({ packageDirectory, packageJson, app, protectedInside, declared }) {
+export function checkConfigs({
+  packageDirectory,
+  packageJson,
+  app,
+  protectedInside,
+  declared,
+}) {
   const findings = [];
-  const error = (kind, message) => findings.push({ level: "error", kind, message });
-  const warning = (kind, message) => findings.push({ level: "warning", kind, message });
-  const read = (relativePath) => readTextIfExists(path.join(packageDirectory, relativePath));
+  const error = (kind, message) =>
+    findings.push({ level: "error", kind, message });
+  const warning = (kind, message) =>
+    findings.push({ level: "warning", kind, message });
+  const read = (relativePath) =>
+    readTextIfExists(path.join(packageDirectory, relativePath));
 
   const eslintConfig = findExisting(packageDirectory, eslintConfigNames);
   if (eslintConfig === null) {
@@ -781,20 +1593,40 @@ export function checkConfigs({ packageDirectory, packageJson, app, protectedInsi
   } else {
     const contents = read(eslintConfig);
     if (!/typescript-eslint/.test(contents) || !/react-hooks/.test(contents)) {
-      warning("config", eslintConfig + " does not use typescript-eslint and eslint-plugin-react-hooks like the template");
-    }
-    const unignored = protectedInside.filter((relativePath) =>
-      isDirectory(path.join(packageDirectory, relativePath)) && !contents.includes("\"" + relativePath) && !contents.includes("'" + relativePath));
+      warning(
+        "config",
+        eslintConfig +
+          " does not use typescript-eslint and eslint-plugin-react-hooks like the template"
+      );
+    }
+    const unignored = protectedInside.filter(
+      (relativePath) =>
+        isDirectory(path.join(packageDirectory, relativePath)) &&
+        !contents.includes('"' + relativePath) &&
+        !contents.includes("'" + relativePath)
+    );
     if (unignored.length > 0) {
-      warning("config", eslintConfig + " should list the protected paths in globalIgnores: " + unignored.join(", "));
+      warning(
+        "config",
+        eslintConfig +
+          " should list the protected paths in globalIgnores: " +
+          unignored.join(", ")
+      );
     }
   }
   const legacyEslint = findExisting(packageDirectory, legacyEslintConfigNames);
   if (legacyEslint !== null || packageJson.eslintConfig !== undefined) {
-    error("config", (legacyEslint ?? "package.json eslintConfig") + " is a legacy ESLint config; remove it after moving its rules to eslint.config.js");
+    error(
+      "config",
+      (legacyEslint ?? "package.json eslintConfig") +
+        " is a legacy ESLint config; remove it after moving its rules to eslint.config.js"
+    );
   }
 
-  if (findExisting(packageDirectory, prettierConfigNames) === null && packageJson.prettier === undefined) {
+  if (
+    findExisting(packageDirectory, prettierConfigNames) === null &&
+    packageJson.prettier === undefined
+  ) {
     error("config", "no Prettier config (.prettierrc.json)");
   }
   const prettierIgnore = read(".prettierignore");
@@ -803,9 +1635,16 @@ export function checkConfigs({ packageDirectory, packageJson, app, protectedInsi
   } else {
     const lines = readIgnoreLines(prettierIgnore);
     const required = [toPosix(generatedCssRelativePath), ...protectedInside];
-    const uncovered = required.filter((relativePath) => !ignoreCovers(lines, relativePath));
+    const uncovered = required.filter(
+      (relativePath) => !ignoreCovers(lines, relativePath)
+    );
     if (uncovered.length > 0) {
-      error("config", ".prettierignore must list " + uncovered.join(", ") + " (generated or protected files must not be reformatted)");
+      error(
+        "config",
+        ".prettierignore must list " +
+          uncovered.join(", ") +
+          " (generated or protected files must not be reformatted)"
+      );
     }
   }
 
@@ -827,46 +1666,90 @@ export function checkConfigs({ packageDirectory, packageJson, app, protectedInsi
     }
     // Through @tailwindcss/postcss, url() in imported package CSS is not rebased: the EDS font is not emitted.
     if (declared.has("tailwindcss") && !/@tailwindcss\/vite/.test(contents)) {
-      error("config", viteConfig + " must run Tailwind through @tailwindcss/vite (with @tailwindcss/postcss the EDS font file is not emitted)");
+      error(
+        "config",
+        viteConfig +
+          " must run Tailwind through @tailwindcss/vite (with @tailwindcss/postcss the EDS font file is not emitted)"
+      );
     }
   }
   if (declared.has("@tailwindcss/postcss")) {
-    warning("config", "@tailwindcss/postcss is declared; remove it and its postcss.config entry once @tailwindcss/vite runs Tailwind");
+    warning(
+      "config",
+      "@tailwindcss/postcss is declared; remove it and its postcss.config entry once @tailwindcss/vite runs Tailwind"
+    );
   }
 
   const componentsJsonText = read("components.json");
-  const usesRadix = [...declared.keys()].some((name) => name.startsWith("@radix-ui/react-"));
+  const usesRadix = [...declared.keys()].some((name) =>
+    name.startsWith("@radix-ui/react-")
+  );
   if (componentsJsonText !== null) {
     try {
       const aliases = parseJsonc(componentsJsonText).aliases ?? {};
-      if (aliases.ui !== "@/shared/ui" || aliases.utils !== "@/shared/lib/utils") {
-        warning("config", "components.json aliases must point ui to @/shared/ui and utils to @/shared/lib/utils");
+      if (
+        aliases.ui !== "@/shared/ui" ||
+        aliases.utils !== "@/shared/lib/utils"
+      ) {
+        warning(
+          "config",
+          "components.json aliases must point ui to @/shared/ui and utils to @/shared/lib/utils"
+        );
       }
     } catch (parseError) {
-      warning("config", "components.json could not be parsed (" + parseError.message + ")");
+      warning(
+        "config",
+        "components.json could not be parsed (" + parseError.message + ")"
+      );
     }
   } else if (usesRadix) {
-    warning("config", "no components.json although shadcn/Radix components are used");
+    warning(
+      "config",
+      "no components.json although shadcn/Radix components are used"
+    );
   }
 
   const indexHtml = read(joinPosix(app.appDir, "index.html"));
-  const entry = indexHtml === null ? null : readScriptEntry(indexHtml)?.replace(/^\.\//, "/") ?? null;
-  const expectedEntry = "/" + joinPosix(path.posix.relative(app.appDir, app.srcDir) || ".", entryModule);
+  const entry =
+    indexHtml === null
+      ? null
+      : readScriptEntry(indexHtml)?.replace(/^\.\//, "/") ?? null;
+  const expectedEntry =
+    "/" +
+    joinPosix(path.posix.relative(app.appDir, app.srcDir) || ".", entryModule);
   if (entry !== expectedEntry) {
     // Moving the entry is part of the FSD structure step, so this is a structure finding, not a config one.
-    error("structure", joinPosix(app.appDir, "index.html") + " must load " + expectedEntry + (entry === null ? "" : " (loads " + entry + ")"));
+    error(
+      "structure",
+      joinPosix(app.appDir, "index.html") +
+        " must load " +
+        expectedEntry +
+        (entry === null ? "" : " (loads " + entry + ")")
+    );
   }
 
   const scripts = packageJson.scripts ?? {};
   for (const [name, command] of Object.entries(requiredScripts)) {
     if (typeof scripts[name] !== "string") {
-      error("script", "package.json has no \"" + name + "\" script (template: \"" + command + "\")");
+      error(
+        "script",
+        'package.json has no "' +
+          name +
+          '" script (template: "' +
+          command +
+          '")'
+      );
     }
   }
 
   const agents = read("AGENTS.md");
   if (agents === null || !agents.includes(conventionsFileName)) {
-    warning("agents", "AGENTS.md does not point at " + conventionsFileName + " yet (PLAN.md step 8)");
+    warning(
+      "agents",
+      "AGENTS.md does not point at " +
+        conventionsFileName +
+        " yet (PLAN.md step 8)"
+    );
   }
   return findings;
 }
@@ -885,11 +1768,213 @@ function checkTsconfig({ packageDirectory, app, read, error }) {
         return;
       }
     } catch (parseError) {
-      error("config", name + " could not be parsed (" + parseError.message + ")");
+      error(
+        "config",
+        name + " could not be parsed (" + parseError.message + ")"
+      );
       return;
     }
   }
-  error("config", "tsconfig.json must map \"@/*\" to [\"./" + app.srcDir + "/*\"]");
+  error("config", 'tsconfig.json must map "@/*" to ["./' + app.srcDir + '/*"]');
+}
+
+const preservedTsconfigFields = ["include", "exclude", "types", "references"];
+
+function stableJson(value) {
+  if (Array.isArray(value)) return "[" + value.map(stableJson).join(",") + "]";
+  if (value !== null && typeof value === "object") {
+    return (
+      "{" +
+      Object.keys(value)
+        .sort()
+        .map((key) => JSON.stringify(key) + ":" + stableJson(value[key]))
+        .join(",") +
+      "}"
+    );
+  }
+  return JSON.stringify(value);
+}
+
+// Keep existing TypeScript include/exclude/type/reference settings by config file for --check.
+export function collectPreservedTsconfigSettings(
+  packageDirectory,
+  filePaths = walkFiles(packageDirectory)
+) {
+  const settings = {};
+  const configPaths = filePaths.filter((relativePath) =>
+    /^tsconfig(?:\..+)?\.json$/i.test(path.posix.basename(relativePath))
+  );
+  for (const relativePath of configPaths) {
+    const fileSettings = Object.fromEntries(
+      preservedTsconfigFields.map((field) => [field, new Set()])
+    );
+    const contents = fs.readFileSync(
+      path.join(packageDirectory, relativePath),
+      "utf8"
+    );
+    let config;
+    try {
+      config = parseJsonc(contents);
+    } catch {
+      settings[relativePath] = {
+        parseErrorHash: crypto
+          .createHash("sha256")
+          .update(contents)
+          .digest("hex"),
+      };
+      continue;
+    }
+    for (const field of preservedTsconfigFields) {
+      const values = Array.isArray(
+        field === "types" ? config.compilerOptions?.types : config[field]
+      )
+        ? field === "types"
+          ? config.compilerOptions.types
+          : config[field]
+        : [];
+      for (const value of values) {
+        const pathValue =
+          field === "references" && typeof value === "object" && value !== null
+            ? value.path
+            : value;
+        const serialized =
+          typeof pathValue === "string"
+            ? pathValue.replaceAll("\\", "/")
+            : JSON.stringify(value);
+        const normalizedPath =
+          typeof pathValue === "string"
+            ? path.posix.normalize(
+                path.posix.join(path.posix.dirname(relativePath), serialized)
+              )
+            : null;
+        const normalized =
+          field === "references" && typeof value === "object" && value !== null
+            ? stableJson({
+                ...value,
+                ...(normalizedPath === null ? {} : { path: normalizedPath }),
+              })
+            : ["include", "exclude", "references"].includes(field) &&
+              normalizedPath !== null
+            ? normalizedPath
+            : serialized;
+        fileSettings[field].add(normalized);
+      }
+    }
+    settings[relativePath] = Object.fromEntries(
+      Object.entries(fileSettings).map(([field, values]) => [
+        field,
+        [...values].sort(),
+      ])
+    );
+  }
+  return settings;
+}
+
+export function isLegacyPreservedTsconfigSettings(settings) {
+  return (
+    settings !== null &&
+    typeof settings === "object" &&
+    Object.keys(settings).length > 0 &&
+    Object.values(settings).every(Array.isArray)
+  );
+}
+
+export function checkPreservedTsconfigSettings({
+  baseline = {},
+  current = {},
+}) {
+  const findings = [];
+  if (isLegacyPreservedTsconfigSettings(baseline)) {
+    for (const field of preservedTsconfigFields) {
+      const currentValues = new Set(
+        Object.values(current).flatMap((settings) => settings[field] ?? [])
+      );
+      for (const value of baseline[field] ?? []) {
+        if (!currentValues.has(value)) {
+          findings.push({
+            level: "error",
+            kind: "preserved",
+            message:
+              "tsconfig " +
+              field +
+              " no longer includes the existing setting " +
+              JSON.stringify(value) +
+              "; restore it or rerun eds align to refresh the plan",
+          });
+        }
+      }
+    }
+    return findings;
+  }
+  for (const [configPath, baselineSettings] of Object.entries(baseline)) {
+    if (!Object.hasOwn(current, configPath)) {
+      findings.push({
+        level: "error",
+        kind: "preserved",
+        message: "tsconfig " + configPath + " was removed; restore the file",
+      });
+      continue;
+    }
+    const primaryConfig =
+      configPath === "tsconfig.json" || configPath === "tsconfig.app.json";
+    const baselineParseErrorHash = baselineSettings?.parseErrorHash;
+    const currentParseErrorHash = current[configPath]?.parseErrorHash;
+    if (typeof baselineParseErrorHash === "string") {
+      if (currentParseErrorHash !== baselineParseErrorHash) {
+        findings.push({
+          level: "error",
+          kind: "preserved",
+          message:
+            "tsconfig " +
+            configPath +
+            " could not be parsed when the plan was created and has changed; fix it and rerun eds align",
+        });
+      } else if (!primaryConfig) {
+        findings.push({
+          level: "error",
+          kind: "config",
+          message:
+            "tsconfig " +
+            configPath +
+            " could not be parsed; existing settings cannot be checked",
+        });
+      }
+      continue;
+    }
+    if (typeof currentParseErrorHash === "string") {
+      if (!primaryConfig) {
+        findings.push({
+          level: "error",
+          kind: "config",
+          message:
+            "tsconfig " +
+            configPath +
+            " could not be parsed; existing settings cannot be checked",
+        });
+      }
+      continue;
+    }
+    for (const field of preservedTsconfigFields) {
+      const currentValues = new Set(current[configPath]?.[field] ?? []);
+      for (const value of baselineSettings[field] ?? []) {
+        if (!currentValues.has(value)) {
+          findings.push({
+            level: "error",
+            kind: "preserved",
+            message:
+              "tsconfig " +
+              configPath +
+              " " +
+              field +
+              " no longer includes the existing setting " +
+              JSON.stringify(value) +
+              "; restore it",
+          });
+        }
+      }
+    }
+  }
+  return findings;
 }
 
 // Finds package directories (relative to root) whose package.json declares react.
@@ -910,7 +1995,11 @@ export function findFrontendPackages(root) {
       return;
     }
     for (const entry of fs.readdirSync(directory, { withFileTypes: true })) {
-      if (entry.isDirectory() && !entry.name.startsWith(".") && !walkExcludedDirectories.has(entry.name)) {
+      if (
+        entry.isDirectory() &&
+        !entry.name.startsWith(".") &&
+        !walkExcludedDirectories.has(entry.name)
+      ) {
         visit(path.join(directory, entry.name), depth + 1);
       }
     }
@@ -925,32 +2014,58 @@ export function locateApp(packageDirectory) {
   const visit = (directory, depth) => {
     const indexHtml = readTextIfExists(path.join(directory, "index.html"));
     if (indexHtml !== null && readScriptEntry(indexHtml) !== null) {
-      candidates.push(toPosix(path.relative(packageDirectory, directory)) || ".");
+      candidates.push(
+        toPosix(path.relative(packageDirectory, directory)) || "."
+      );
     }
     if (depth >= 2) {
       return;
     }
     for (const entry of fs.readdirSync(directory, { withFileTypes: true })) {
-      if (entry.isDirectory() && !entry.name.startsWith(".") && !walkExcludedDirectories.has(entry.name) && entry.name !== "public" && entry.name !== "src") {
+      if (
+        entry.isDirectory() &&
+        !entry.name.startsWith(".") &&
+        !walkExcludedDirectories.has(entry.name) &&
+        entry.name !== "public" &&
+        entry.name !== "src"
+      ) {
         visit(path.join(directory, entry.name), depth + 1);
       }
     }
   };
   visit(packageDirectory, 0);
-  const appDir = candidates.includes(".") ? "." : candidates.length === 1 ? candidates[0] : null;
+  const appDir = candidates.includes(".")
+    ? "."
+    : candidates.length === 1
+    ? candidates[0]
+    : null;
   if (appDir === null) {
     throw createExitError(
       candidates.length === 0
-        ? "No index.html with a <script type=\"module\"> entry in the frontend package; eds align supports Vite apps only."
-        : "Several index.html entries (" + candidates.join(", ") + "); run eds align inside the package of the app to align.",
-      2,
+        ? 'No index.html with a <script type="module"> entry in the frontend package; eds align supports Vite apps only.'
+        : "Several index.html entries (" +
+            candidates.join(", ") +
+            "); run eds align inside the package of the app to align.",
+      2
     );
   }
   const srcDir = joinPosix(appDir, "src");
-  if (!fs.existsSync(path.join(packageDirectory, srcDir)) || !fs.statSync(path.join(packageDirectory, srcDir)).isDirectory()) {
-    throw createExitError("No " + srcDir + " directory next to " + joinPosix(appDir, "index.html") + ".", 2);
+  if (
+    !fs.existsSync(path.join(packageDirectory, srcDir)) ||
+    !fs.statSync(path.join(packageDirectory, srcDir)).isDirectory()
+  ) {
+    throw createExitError(
+      "No " +
+        srcDir +
+        " directory next to " +
+        joinPosix(appDir, "index.html") +
+        ".",
+      2
+    );
   }
-  const indexHtml = readTextIfExists(path.join(packageDirectory, appDir, "index.html"));
+  const indexHtml = readTextIfExists(
+    path.join(packageDirectory, appDir, "index.html")
+  );
   return { appDir, srcDir, entry: readScriptEntry(indexHtml) };
 }
 
@@ -964,18 +2079,33 @@ function isDirectory(filePath) {
 
 function readSourceFiles(root, relativePaths) {
   return relativePaths
-    .filter((relativePath) => scriptExtensions.has(path.posix.extname(relativePath)))
-    .map((relativePath) => ({ path: relativePath, contents: fs.readFileSync(path.join(root, relativePath), "utf8") }));
+    .filter((relativePath) =>
+      scriptExtensions.has(path.posix.extname(relativePath))
+    )
+    .map((relativePath) => ({
+      path: relativePath,
+      contents: fs.readFileSync(path.join(root, relativePath), "utf8"),
+    }));
 }
 
 // A relative import target without extension resolved the way bundlers do (file, then index file).
 function resolveModuleFile(packageDirectory, relativePath) {
   const candidates = [
     relativePath,
-    ...[...scriptExtensions, ".json"].map((extension) => relativePath + extension),
-    ...[...scriptExtensions].map((extension) => relativePath + "/index" + extension),
+    ...[...scriptExtensions, ".json"].map(
+      (extension) => relativePath + extension
+    ),
+    ...[...scriptExtensions].map(
+      (extension) => relativePath + "/index" + extension
+    ),
   ];
-  return candidates.find((candidate) => fs.existsSync(path.join(packageDirectory, candidate)) && !isDirectory(path.join(packageDirectory, candidate))) ?? relativePath;
+  return (
+    candidates.find(
+      (candidate) =>
+        fs.existsSync(path.join(packageDirectory, candidate)) &&
+        !isDirectory(path.join(packageDirectory, candidate))
+    ) ?? relativePath
+  );
 }
 
 // Binaries whose package name differs from the command.
@@ -991,15 +2121,28 @@ function scriptPackages(command, declared) {
 }
 
 // Backend and deployment paths. inside: relative to the package; repository: relative to the git root.
-export function detectProtectedPaths({ packageDirectory, gitRoot, declared, scripts }) {
+export function detectProtectedPaths({
+  packageDirectory,
+  gitRoot,
+  declared,
+  scripts,
+}) {
   const packageRelative = toPosix(path.relative(gitRoot, packageDirectory));
-  const toRepository = (relativePath) => (packageRelative === "" ? relativePath : packageRelative + "/" + relativePath);
+  const toRepository = (relativePath) =>
+    packageRelative === ""
+      ? relativePath
+      : packageRelative + "/" + relativePath;
   const inside = [];
   for (const name of backendDirectoryNames) {
     if (isDirectory(path.join(packageDirectory, name))) inside.push(name);
   }
-  const hasBackend = inside.length > 0 || backendServerPackages.some((name) => declared.has(name));
-  if (hasBackend && isDirectory(path.join(packageDirectory, sharedWithBackendDirectoryName))) {
+  const hasBackend =
+    inside.length > 0 ||
+    backendServerPackages.some((name) => declared.has(name));
+  if (
+    hasBackend &&
+    isDirectory(path.join(packageDirectory, sharedWithBackendDirectoryName))
+  ) {
     inside.push(sharedWithBackendDirectoryName);
   }
   for (const name of backendMarkerFiles) {
@@ -1013,33 +2156,57 @@ export function detectProtectedPaths({ packageDirectory, gitRoot, declared, scri
   }
 
   // Packages the backend code in this package imports, and frontend files it imports (their exports must stay).
-  const backendUsed = new Set(backendServerPackages.filter((name) => declared.has(name)));
+  const backendUsed = new Set(
+    backendServerPackages.filter((name) => declared.has(name))
+  );
   const importedFrontendFiles = new Set();
-  const insideDirectories = inside.filter((relativePath) => isDirectory(path.join(packageDirectory, relativePath)));
-  const isInsideProtected = (relativePath) => inside.some((entry) => relativePath === entry || relativePath.startsWith(entry + "/"));
+  const insideDirectories = inside.filter((relativePath) =>
+    isDirectory(path.join(packageDirectory, relativePath))
+  );
+  const isInsideProtected = (relativePath) =>
+    inside.some(
+      (entry) => relativePath === entry || relativePath.startsWith(entry + "/")
+    );
   for (const directory of insideDirectories) {
-    for (const file of readSourceFiles(path.join(packageDirectory, directory), walkFiles(path.join(packageDirectory, directory)))) {
+    for (const file of readSourceFiles(
+      path.join(packageDirectory, directory),
+      walkFiles(path.join(packageDirectory, directory))
+    )) {
       const filePath = directory + "/" + file.path;
       for (const { specifier } of extractImports(file.contents)) {
         const name = packageNameOf(specifier);
         if (name !== null && declared.has(name)) {
           backendUsed.add(name);
         } else if (specifier.startsWith(".")) {
-          const target = path.posix.normalize(path.posix.join(path.posix.dirname(filePath), specifier));
+          const target = path.posix.normalize(
+            path.posix.join(path.posix.dirname(filePath), specifier)
+          );
           if (!target.startsWith("..") && !isInsideProtected(target)) {
-            importedFrontendFiles.add(resolveModuleFile(packageDirectory, target));
+            importedFrontendFiles.add(
+              resolveModuleFile(packageDirectory, target)
+            );
           }
         }
       }
     }
   }
 
-  const directoryPattern = insideDirectories.length === 0
-    ? null
-    : new RegExp("(?:^|[\\s\"'=(])(?:\\./)?(?:" + insideDirectories.map((entry) => entry.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")).join("|") + ")/");
+  const directoryPattern =
+    insideDirectories.length === 0
+      ? null
+      : new RegExp(
+          "(?:^|[\\s\"'=(])(?:\\./)?(?:" +
+            insideDirectories
+              .map((entry) => entry.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"))
+              .join("|") +
+            ")/"
+        );
   const backendScripts = {};
   for (const [name, command] of Object.entries(scripts ?? {})) {
-    if (typeof command === "string" && (backendScriptPattern.test(command) || directoryPattern?.test(command))) {
+    if (
+      typeof command === "string" &&
+      (backendScriptPattern.test(command) || directoryPattern?.test(command))
+    ) {
       backendScripts[name] = command;
       for (const packageUsed of scriptPackages(command, declared)) {
         backendUsed.add(packageUsed);
@@ -1058,26 +2225,96 @@ export function detectProtectedPaths({ packageDirectory, gitRoot, declared, scri
 }
 
 // Paths changed since the base commit (from git), classified against the protected list recorded in the state.
-export function classifyChangedPaths({ changed, baseline, hashOf, packageRelative, protectedPaths, alignRelative, base }) {
+export function classifyChangedPaths({
+  changed,
+  baseline,
+  hashOf,
+  packageRelative,
+  protectedPaths,
+  preservedPaths = [],
+  baseTrackedPaths = [],
+  alignRelative,
+  base,
+}) {
   const shortBase = String(base ?? "").slice(0, 12);
   const findings = [];
-  const inPackage = (relativePath) => packageRelative === "" || relativePath === packageRelative || relativePath.startsWith(packageRelative + "/");
-  for (const relativePath of [...new Set(changed)].sort()) {
-    if (relativePath === alignRelative || relativePath.startsWith(alignRelative + "/")) {
+  const inPackage = (relativePath) =>
+    packageRelative === "" ||
+    relativePath === packageRelative ||
+    relativePath.startsWith(packageRelative + "/");
+  const isPreserved = (relativePath) =>
+    isPreservedSourcePath(relativePath) ||
+    preservedPaths.some(
+      (entry) => relativePath === entry || relativePath.startsWith(entry + "/")
+    );
+  const changedPaths = new Set(changed);
+  const baseTracked = new Set(baseTrackedPaths);
+  for (const [relativePath, baselineHash] of Object.entries(baseline)) {
+    if (baselineHash !== hashOf(relativePath)) {
+      changedPaths.add(relativePath);
+    }
+  }
+  for (const relativePath of [...changedPaths].sort()) {
+    if (
+      relativePath === alignRelative ||
+      relativePath.startsWith(alignRelative + "/")
+    ) {
       continue;
     }
-    if (Object.prototype.hasOwnProperty.call(baseline, relativePath) && baseline[relativePath] === hashOf(relativePath)) {
+    if (
+      Object.prototype.hasOwnProperty.call(baseline, relativePath) &&
+      baseline[relativePath] === hashOf(relativePath)
+    ) {
       continue;
     }
-    if (protectedPaths.some((entry) => relativePath === entry || relativePath.startsWith(entry + "/"))) {
+    if (
+      protectedPaths.some(
+        (entry) =>
+          relativePath === entry || relativePath.startsWith(entry + "/")
+      )
+    ) {
       findings.push({
         level: "error",
         kind: "protected",
-        message: relativePath + " changed since " + shortBase + "; it is backend or deployment code (git checkout " + shortBase + " -- " +
-          relativePath + " restores it; delete it if it is new)",
+        message:
+          relativePath +
+          " changed since " +
+          shortBase +
+          "; it is backend or deployment code (git checkout " +
+          shortBase +
+          " -- " +
+          relativePath +
+          " restores it; delete it if it is new)",
+      });
+    } else if (
+      !inPackage(relativePath) &&
+      !(packageRelative !== "" && rootLockfiles.includes(relativePath))
+    ) {
+      findings.push({
+        level: "error",
+        kind: "outside",
+        message:
+          relativePath +
+          " changed since " +
+          shortBase +
+          " outside the frontend package",
+      });
+    } else if (isPreserved(relativePath)) {
+      if (
+        !Object.hasOwn(baseline, relativePath) &&
+        !baseTracked.has(relativePath)
+      ) {
+        continue;
+      }
+      findings.push({
+        level: "error",
+        kind: "preserved",
+        message:
+          relativePath +
+          " changed since " +
+          shortBase +
+          "; restore the file to its state and location at the alignment baseline",
       });
-    } else if (!inPackage(relativePath) && !(packageRelative !== "" && rootLockfiles.includes(relativePath))) {
-      findings.push({ level: "error", kind: "outside", message: relativePath + " changed since " + shortBase + " outside the frontend package" });
     }
   }
   return findings;
@@ -1086,74 +2323,250 @@ export function classifyChangedPaths({ changed, baseline, hashOf, packageRelativ
 export function checkBackendPackage({ packageJson, state }) {
   const findings = [];
   const scripts = packageJson.scripts ?? {};
-  for (const [name, command] of Object.entries(state.protected.backendScripts ?? {})) {
+  for (const [name, command] of Object.entries(
+    state.protected.backendScripts ?? {}
+  )) {
     if (scripts[name] !== command) {
       findings.push({
         level: "error",
         kind: "backend-script",
-        message: "package.json script \"" + name + "\" runs backend code and must stay " + JSON.stringify(command) +
-          (scripts[name] === undefined ? " (it was removed)" : " (now " + JSON.stringify(scripts[name]) + ")"),
+        message:
+          'package.json script "' +
+          name +
+          '" runs backend code and must stay ' +
+          JSON.stringify(command) +
+          (scripts[name] === undefined
+            ? " (it was removed)"
+            : " (now " + JSON.stringify(scripts[name]) + ")"),
       });
     }
   }
   const declared = declaredDependencies(packageJson);
   for (const name of state.protected.backendUsed ?? []) {
     if (!declared.has(name)) {
-      findings.push({ level: "error", kind: "backend-dependency", message: name + " was removed from package.json but the backend code uses it" });
+      findings.push({
+        level: "error",
+        kind: "backend-dependency",
+        message:
+          name + " was removed from package.json but the backend code uses it",
+      });
     }
   }
   return findings;
 }
 
 // Everything the plan and the check need, read from the working tree.
-export function analyzeFrontend({ packageDirectory, gitRoot, protectedInfo = null }) {
-  const packageJson = JSON.parse(fs.readFileSync(path.join(packageDirectory, "package.json"), "utf8"));
+export function analyzeFrontend({
+  packageDirectory,
+  gitRoot,
+  protectedInfo = null,
+  preservedPaths = [],
+  nodeVersion = process.versions.node,
+}) {
+  const packageJson = JSON.parse(
+    fs.readFileSync(path.join(packageDirectory, "package.json"), "utf8")
+  );
   const declared = declaredDependencies(packageJson);
   const app = locateApp(packageDirectory);
-  const detectedProtected = protectedInfo ?? detectProtectedPaths({ packageDirectory, gitRoot, declared, scripts: packageJson.scripts });
+  const detectedProtected =
+    protectedInfo ??
+    detectProtectedPaths({
+      packageDirectory,
+      gitRoot,
+      declared,
+      scripts: packageJson.scripts,
+    });
   const majors = {};
-  for (const name of ["vite", "react", "tailwindcss", "@tanstack/react-query", "typescript", "@vitejs/plugin-react"]) {
+  for (const name of [
+    "vite",
+    "react",
+    "tailwindcss",
+    "@tanstack/react-query",
+    "typescript",
+    "@vitejs/plugin-react",
+  ]) {
     const installed = installedVersion(packageDirectory, name);
-    majors[name] = majorOf(installed ?? declared.get(name)?.range);
+    majors[name] =
+      name === "vite"
+        ? majorOf(installed)
+        : majorOf(installed ?? declared.get(name)?.range);
   }
   const srcRoot = path.join(packageDirectory, app.srcDir);
   const allFiles = walkFiles(srcRoot);
-  const sourceFiles = readSourceFiles(srcRoot, allFiles.filter((file) => !file.endsWith(".d.ts")));
-  const toolVersions = Object.fromEntries(Object.keys(templateToolMinimums).map((name) => [name, installedVersion(packageDirectory, name)]).filter(([, version]) => version !== null));
-  const restCalls = sourceFiles.some((file) => /\bfetch\s*\(|\baxios\b/.test(file.contents));
-  const dependencies = classifyDependencies({ declared, majors, backendUsed: new Set(detectedProtected.backendUsed), toolVersions, restCalls });
+  const sourceFiles = readSourceFiles(
+    srcRoot,
+    allFiles.filter((file) => !file.endsWith(".d.ts"))
+  );
+  const packageFiles = walkFiles(packageDirectory);
+  const preservedTsconfigSettings = collectPreservedTsconfigSettings(
+    packageDirectory,
+    packageFiles
+  );
+  const preservedFilePaths = packageFiles.filter((relativePath) =>
+    isPreservedSourcePath(relativePath)
+  );
+  const preservedDirectoryPaths = new Set();
+  for (const file of preservedFilePaths) {
+    const parts = file.split("/");
+    for (let index = 0; index < parts.length - 1; index += 1) {
+      if (isPreservedDirectoryName(parts[index], parts, index)) {
+        preservedDirectoryPaths.add(parts.slice(0, index + 1).join("/"));
+      }
+    }
+  }
+  const autoPreservedPaths = [
+    ...new Set([...preservedFilePaths, ...preservedDirectoryPaths]),
+  ].sort();
+  const normalizedPreservedPaths = [...new Set(preservedPaths)].sort();
+  const allPreservedPaths = [
+    ...new Set([...autoPreservedPaths, ...normalizedPreservedPaths]),
+  ].sort();
+  const sourcePrefix = app.srcDir + "/";
+  const preservedSourcePaths = allPreservedPaths.flatMap((relativePath) => {
+    if (relativePath === ".") return ["."];
+    if (relativePath === app.srcDir) return ["."];
+    return relativePath.startsWith(sourcePrefix)
+      ? [relativePath.slice(sourcePrefix.length)]
+      : [];
+  });
+  const isPreservedPackageFile = (relativePath) =>
+    isPreservedSourcePath(relativePath, allPreservedPaths);
+  const alignedSourceFiles = sourceFiles.filter(
+    (file) => !isPreservedSourcePath(file.path, preservedSourcePaths)
+  );
+  const reactMigrationTargets = alignedSourceFiles
+    .filter(({ path: file }) => /\.(?:js|jsx|ts|tsx)$/i.test(file))
+    .map(({ path: file }) => joinPosix(app.srcDir, file));
+  const existingPreservedFiles = packageFiles.filter(isPreservedPackageFile);
+  const preservedFiles = readSourceFiles(
+    packageDirectory,
+    existingPreservedFiles
+  );
+  const toolVersions = Object.fromEntries(
+    [
+      ...new Set([
+        "vite",
+        "@vitejs/plugin-react",
+        "@tailwindcss/vite",
+        rolldownBabelPackage,
+        "babel-plugin-react-compiler",
+        ...Object.keys(templateToolMinimums),
+      ]),
+    ]
+      .map((name) => [name, installedVersion(packageDirectory, name)])
+      .filter(([, version]) => version !== null)
+  );
+  const restCalls = alignedSourceFiles.some((file) =>
+    /\bfetch\s*\(|\baxios\b/.test(file.contents)
+  );
+  const dependencies = classifyDependencies({
+    declared,
+    majors,
+    backendUsed: new Set(detectedProtected.backendUsed),
+    toolVersions,
+    restCalls,
+    nodeVersion,
+  });
+  majors.vite = dependencies.viteMajor;
   // shadcn ui files that import a package the plan replaces (for example form.tsx and react-hook-form).
   dependencies.uiDependents = dependencies.replacements
     .filter((entry) => !entry.keptForBackend)
-    .flatMap((entry) => sourceFiles
-      .filter((file) => /(^|\/)ui\//.test(file.path) && new RegExp("from\\s+[\"']" + entry.name.replace(/[.*+?^${}()|[\]\\/]/g, "\\$&") + "[\"'/]").test(file.contents))
-      .map((file) => ({ file: joinPosix(app.srcDir, file.path), name: entry.name })));
+    .flatMap((entry) =>
+      alignedSourceFiles
+        .filter(
+          (file) =>
+            /(^|\/)ui\//.test(file.path) &&
+            new RegExp(
+              "from\\s+[\"']" +
+                entry.name.replace(/[.*+?^${}()|[\]\\/]/g, "\\$&") +
+                "[\"'/]"
+            ).test(file.contents)
+        )
+        .map((file) => ({
+          file: joinPosix(app.srcDir, file.path),
+          name: entry.name,
+        }))
+    );
+  dependencies.preservedDependents = dependencies.replacements
+    .filter((entry) => !entry.keptForBackend)
+    .flatMap((entry) =>
+      preservedFiles
+        .filter((file) =>
+          extractImports(file.contents).some(
+            ({ specifier }) => packageNameOf(specifier) === entry.name
+          )
+        )
+        .map((file) => ({ file: file.path, name: entry.name }))
+    );
   const findings = [
-    ...checkStructure({ files: allFiles, srcLabel: app.srcDir }),
-    ...checkImports({ files: sourceFiles, srcLabel: app.srcDir }),
+    ...checkStructure({
+      files: allFiles,
+      srcLabel: app.srcDir,
+      preservedPaths: preservedSourcePaths,
+    }),
+    ...checkImports({
+      files: sourceFiles,
+      srcLabel: app.srcDir,
+      preservedPaths: preservedSourcePaths,
+    }),
     ...checkDependencies(dependencies),
-    ...checkConfigs({ packageDirectory, packageJson, app, protectedInside: detectedProtected.inside, declared }),
-    ...checkPatterns({ files: sourceFiles, allFiles, srcLabel: app.srcDir }),
+    ...checkConfigs({
+      packageDirectory,
+      packageJson,
+      app,
+      protectedInside: detectedProtected.inside,
+      declared,
+    }),
+    ...checkPatterns({
+      files: sourceFiles,
+      allFiles,
+      srcLabel: app.srcDir,
+      preservedPaths: preservedSourcePaths,
+    }),
   ];
-  return { packageJson, declared, app, protectedInfo: detectedProtected, majors, dependencies, allFiles, findings };
+  return {
+    packageJson,
+    declared,
+    app,
+    protectedInfo: detectedProtected,
+    majors,
+    dependencies,
+    allFiles,
+    reactMigrationTargets,
+    autoPreservedPaths,
+    preservedPaths: allPreservedPaths,
+    preservedSourcePaths,
+    preservedTsconfigSettings,
+    findings,
+  };
 }
 
 // src/ top-level entries with their file counts and where each goes.
-export function summarizeStructure(allFiles) {
+export function summarizeStructure(allFiles, preservedPaths = []) {
   const entries = new Map();
   for (const file of allFiles) {
     const [top] = file.split("/");
     const isFile = !file.includes("/");
-    const entry = entries.get(top) ?? { name: top, type: isFile ? "file" : "directory", files: 0 };
+    const entry = entries.get(top) ?? {
+      name: top,
+      type: isFile ? "file" : "directory",
+      files: 0,
+    };
     entry.files += 1;
     entries.set(top, entry);
   }
   return [...entries.values()].map((entry) => {
-    const test = entry.type === "directory" ? testDirectoryNames.includes(entry.name) : isTestSupport(entry.name);
+    const preserved = isPreservedSourcePath(entry.name, preservedPaths);
     return {
       ...entry,
-      fsd: test || layerOrder.includes(entry.name) || auxiliarySourceDirectories.includes(entry.name) || allowedSourceRootFiles.includes(entry.name),
-      hint: test ? testSupportHint : structureHints[entry.name.toLowerCase()] ?? null,
+      fsd:
+        preserved ||
+        layerOrder.includes(entry.name) ||
+        auxiliarySourceDirectories.includes(entry.name) ||
+        allowedSourceRootFiles.includes(entry.name),
+      hint: preserved
+        ? preservedSourceHint
+        : structureHints[entry.name.toLowerCase()] ?? null,
     };
   });
 }