@spectrabrain/eds 0.3.0 → 0.4.0

package/consumer/align.mjs

@@ -5,20 +5,52 @@ import { fileURLToPath } from "node:url";
 import {
   analyzeFrontend,
   checkBackendPackage,
+  checkPreservedTsconfigSettings,
   classifyChangedPaths,
   declaredDependencies,
   detectFramework,
+  filesUnderPaths,
   findFrontendPackages,
   hashFile,
+  isLegacyPreservedTsconfigSettings,
+  isPreservedSourcePath,
   parseJsonc,
   summarizeStructure,
   walkFiles,
 } from "./align-analysis.mjs";
-import { countFindings, packageManagerCommands, renderNotes, renderPlan } from "./align-plan.mjs";
-import { alignDirectory, conventionsFileName, planFileName, rootLockfiles, stateFileName, stateSchemaVersion, templatesDirectoryName } from "./align-rules.mjs";
-import { cliCommand, createExitError, detectPackageManager, generatedCssRelativePath, installCommand, packageName, readPackageJson, resolvePackage, toPosix } from "./paths.mjs";
+import {
+  countFindings,
+  packageManagerCommands,
+  renderNotes,
+  renderPlan,
+} from "./align-plan.mjs";
+import {
+  alignDirectory,
+  conventionsFileName,
+  maximumSupportedViteMajor,
+  minimumVersions,
+  planFileName,
+  rootLockfiles,
+  stateFileName,
+  stateSchemaVersion,
+  templatesDirectoryName,
+} from "./align-rules.mjs";
+import {
+  cliCommand,
+  createExitError,
+  detectPackageManager,
+  generatedCssRelativePath,
+  installCommand,
+  packageName,
+  readPackageJson,
+  resolvePackage,
+  toPosix,
+} from "./paths.mjs";
 
-const packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const packageRoot = path.resolve(
+  path.dirname(fileURLToPath(import.meta.url)),
+  ".."
+);
 const templatesRoot = path.join(packageRoot, "consumer", "align", "templates");
 const notesFileName = "NOTES.md";
 const findingLimitPerKind = 40;
@@ -26,7 +58,12 @@ const placeholderPattern = /\{\{eds\.(\w+)\}\}/g;
 
 function git(cwd, args) {
   try {
-    return execFileSync("git", args, { cwd, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"], maxBuffer: 64 * 1024 * 1024 });
+    return execFileSync("git", args, {
+      cwd,
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "pipe"],
+      maxBuffer: 64 * 1024 * 1024,
+    });
   } catch {
     return null;
   }
@@ -44,10 +81,24 @@ function readState(statePath, shown = (relativePath) => relativePath) {
   try {
     state = JSON.parse(fs.readFileSync(statePath, "utf8"));
   } catch (error) {
-    throw createExitError(toPosix(statePath) + " could not be read (" + error.message + "); delete " + shown(alignDirectory) + " and run eds align again.", 2);
+    throw createExitError(
+      toPosix(statePath) +
+        " could not be read (" +
+        error.message +
+        "); delete " +
+        shown(alignDirectory) +
+        " and run eds align again.",
+      2
+    );
   }
   if (state?.schemaVersion !== stateSchemaVersion) {
-    throw createExitError(toPosix(statePath) + " was written by another eds align version; delete " + shown(alignDirectory) + " and run eds align again.", 2);
+    throw createExitError(
+      toPosix(statePath) +
+        " was written by another eds align version; delete " +
+        shown(alignDirectory) +
+        " and run eds align again.",
+      2
+    );
   }
   return state;
 }
@@ -58,7 +109,10 @@ function resolveFrontendDirectory(consumerRoot, frontendOption) {
   if (frontendOption) {
     const directory = path.resolve(consumerRoot, frontendOption);
     if (!fs.existsSync(path.join(directory, "package.json"))) {
-      throw createExitError("--frontend " + frontendOption + " has no package.json.", 2);
+      throw createExitError(
+        "--frontend " + frontendOption + " has no package.json.",
+        2
+      );
     }
     return directory;
   }
@@ -69,15 +123,19 @@ function resolveFrontendDirectory(consumerRoot, frontendOption) {
   if (own !== null && declaredDependencies(own).has("react")) {
     return consumerRoot;
   }
-  const candidates = findFrontendPackages(consumerRoot).filter((candidate) => candidate !== ".");
+  const candidates = findFrontendPackages(consumerRoot).filter(
+    (candidate) => candidate !== "."
+  );
   if (candidates.length === 1) {
     return path.join(consumerRoot, candidates[0]);
   }
   throw createExitError(
     candidates.length === 0
       ? "No package here or below declares react; run eds align inside the frontend package."
-      : "Several React packages (" + candidates.join(", ") + "); rerun with --frontend <dir>.",
-    2,
+      : "Several React packages (" +
+          candidates.join(", ") +
+          "); rerun with --frontend <dir>.",
+    2
   );
 }
 
@@ -89,6 +147,78 @@ function changedSince(gitRoot, commit) {
   ];
 }
 
+function normalizeRepositoryPaths(paths, alignRelative) {
+  if (!Array.isArray(paths)) {
+    throw createExitError(
+      "state.json `preservedPaths` must be an array of paths relative to the git root.",
+      2
+    );
+  }
+  const normalized = [];
+  for (const entry of paths) {
+    if (typeof entry !== "string" || entry.trim() === "") {
+      throw createExitError(
+        "state.json `preservedPaths` must contain non-empty paths relative to the git root.",
+        2
+      );
+    }
+    const pathText = entry.trim().replaceAll("\\", "/");
+    const relativePath = path.posix.normalize(pathText);
+    if (
+      path.posix.isAbsolute(pathText) ||
+      /^[A-Za-z]:\//.test(pathText) ||
+      relativePath === "." ||
+      relativePath === ".." ||
+      relativePath.startsWith("../")
+    ) {
+      throw createExitError(
+        "state.json `preservedPaths` must use paths inside the git repository, relative to its root: " +
+          JSON.stringify(entry),
+        2
+      );
+    }
+    if (
+      relativePath === alignRelative ||
+      relativePath.startsWith(alignRelative + "/")
+    ) {
+      throw createExitError(
+        "state.json `preservedPaths` cannot include " + alignRelative + ".",
+        2
+      );
+    }
+    normalized.push(relativePath);
+  }
+  return [...new Set(normalized)].sort();
+}
+
+export function packagePathsFromRepository(paths, packageRelative) {
+  const prefix = packageRelative === "" ? "" : packageRelative + "/";
+  return paths.flatMap((relativePath) => {
+    if (packageRelative === "") return [relativePath];
+    if (relativePath === packageRelative) return ["."];
+    return relativePath.startsWith(prefix)
+      ? [relativePath.slice(prefix.length)]
+      : [];
+  });
+}
+
+function isAutomaticPreservedRepositoryPath(relativePath, packageRelative) {
+  const packagePath = packagePathsFromRepository(
+    [relativePath],
+    packageRelative
+  )[0];
+  return packagePath !== undefined && isPreservedSourcePath(packagePath);
+}
+
+function hashPaths(root, relativePaths) {
+  const hashes = {};
+  for (const relativePath of filesUnderPaths(root, relativePaths)) {
+    const hash = hashFile(path.join(root, relativePath));
+    if (hash !== null) hashes[relativePath] = hash;
+  }
+  return hashes;
+}
+
 function readStrictOption(packageDirectory) {
   for (const name of ["tsconfig.json", "tsconfig.app.json"]) {
     const filePath = path.join(packageDirectory, name);
@@ -96,7 +226,10 @@ function readStrictOption(packageDirectory) {
       continue;
     }
     try {
-      if (parseJsonc(fs.readFileSync(filePath, "utf8")).compilerOptions?.strict === true) {
+      if (
+        parseJsonc(fs.readFileSync(filePath, "utf8")).compilerOptions
+          ?.strict === true
+      ) {
         return true;
       }
     } catch {
@@ -107,23 +240,40 @@ function readStrictOption(packageDirectory) {
 }
 
 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;
 }
 
 // Templates rendered with this repository's paths. Keys are target paths relative to the frontend package.
-export function renderTemplates({ app, protectedInside, packageJson, viteMajor, strict }) {
-  const eslintFileName = packageJson.type === "module" ? "eslint.config.js" : "eslint.config.mjs";
-  const viteTemplate = viteMajor !== null && viteMajor >= 8 ? "vite.config.rolldown.ts" : "vite.config.babel.ts";
+export function renderTemplates({
+  app,
+  protectedInside,
+  packageJson,
+  viteMajor,
+  strict,
+}) {
+  if (viteMajor !== null && viteMajor > maximumSupportedViteMajor) {
+    throw createExitError(
+      "eds align supports Vite 5.2.0–" + maximumSupportedViteMajor + ".x only.",
+      2
+    );
+  }
+  const eslintFileName =
+    packageJson.type === "module" ? "eslint.config.js" : "eslint.config.mjs";
+  const viteTemplate =
+    viteMajor === 8 ? "vite.config.rolldown.ts" : "vite.config.babel.ts";
   const values = {
     srcDir: app.srcDir,
     strict: String(strict),
-    eslintIgnores: ["dist", "coverage", ".eds", ...protectedInside].map((entry) => JSON.stringify(entry)).join(", "),
+    eslintIgnores: ["dist", "coverage", ".eds", ...protectedInside]
+      .map((entry) => JSON.stringify(entry))
+      .join(", "),
     prettierIgnores: [
       "dist",
       "coverage",
       ".eds",
-      joinPosix(app.appDir, "public/mockServiceWorker.js"),
       toPosix(generatedCssRelativePath),
       "*.md",
       ...rootLockfiles,
@@ -133,15 +283,19 @@ export function renderTemplates({ app, protectedInside, packageJson, viteMajor,
   const rendered = new Map();
   for (const templatePath of walkFiles(templatesRoot)) {
     let target;
-    if (templatePath === "vite.config.babel.ts" || templatePath === "vite.config.rolldown.ts") {
+    if (
+      templatePath === "vite.config.babel.ts" ||
+      templatePath === "vite.config.rolldown.ts"
+    ) {
       if (templatePath !== viteTemplate) continue;
       target = "vite.config.ts";
     } else if (templatePath === "eslint.config.js") {
       target = eslintFileName;
-    } else if (templatePath === "prettierrc.json" || templatePath === "prettierignore") {
+    } else if (
+      templatePath === "prettierrc.json" ||
+      templatePath === "prettierignore"
+    ) {
       target = "." + templatePath;
-    } else if (templatePath === "env.mock") {
-      target = joinPosix(app.appDir, ".env.mock");
     } else if (templatePath.startsWith("src/")) {
       target = joinPosix(app.srcDir, templatePath.slice("src/".length));
     } else if (templatePath.startsWith("public/")) {
@@ -149,12 +303,16 @@ export function renderTemplates({ app, protectedInside, packageJson, viteMajor,
     } else {
       target = templatePath;
     }
-    const contents = fs.readFileSync(path.join(templatesRoot, templatePath), "utf8").replace(placeholderPattern, (match, name) => {
-      if (!Object.prototype.hasOwnProperty.call(values, name)) {
-        throw new Error("Unknown template placeholder " + match + " in " + templatePath);
-      }
-      return values[name];
-    });
+    const contents = fs
+      .readFileSync(path.join(templatesRoot, templatePath), "utf8")
+      .replace(placeholderPattern, (match, name) => {
+        if (!Object.prototype.hasOwnProperty.call(values, name)) {
+          throw new Error(
+            "Unknown template placeholder " + match + " in " + templatePath
+          );
+        }
+        return values[name];
+      });
     rendered.set(target, contents);
   }
   return rendered;
@@ -171,18 +329,39 @@ function logFindings(findings, log) {
       continue;
     }
     shown.set(key, count + 1);
-    log("[EDS] " + (finding.level === "warning" ? "warning " : "") + finding.kind + ": " + finding.message);
+    log(
+      "[EDS] " +
+        (finding.level === "warning" ? "warning " : "") +
+        finding.kind +
+        ": " +
+        finding.message
+    );
   }
   for (const [key, count] of hidden) {
-    log("[EDS] … " + count + " more " + key + " findings (fix the ones above and run the check again)");
+    log(
+      "[EDS] … " +
+        count +
+        " more " +
+        key +
+        " findings (fix the ones above and run the check again)"
+    );
   }
 }
 
 // The rules file as an agent reaches it from the frontend package: through node_modules (the frontend's own or a hoisted
 // one up to the git root) when EDS is installed there, else the resolved package directory (pnpm store, linked install).
 function conventionsPathFrom(packageDirectory, gitRoot, packageRoot) {
-  for (let directory = packageDirectory; ; directory = path.dirname(directory)) {
-    const candidate = path.join(directory, "node_modules", packageName, conventionsFileName);
+  for (
+    let directory = packageDirectory;
+    ;
+    directory = path.dirname(directory)
+  ) {
+    const candidate = path.join(
+      directory,
+      "node_modules",
+      packageName,
+      conventionsFileName
+    );
     if (fs.existsSync(candidate)) {
       return toPosix(path.relative(packageDirectory, candidate));
     }
@@ -190,29 +369,42 @@ function conventionsPathFrom(packageDirectory, gitRoot, packageRoot) {
       break;
     }
   }
-  return toPosix(path.join(path.relative(packageDirectory, packageRoot), conventionsFileName));
+  return toPosix(
+    path.join(path.relative(packageDirectory, packageRoot), conventionsFileName)
+  );
 }
 
 function verificationCommands(commands) {
-  return ["format:check", "lint", "typecheck", "build", "eds:doctor"].map((script) => commands.run(script)).join(", ");
+  return ["format:check", "lint", "typecheck", "build", "eds:doctor"]
+    .map((script) => commands.run(script))
+    .join(", ");
 }
 
 function locateFrontend({ consumerRoot, frontend }) {
-  const packageDirectory = fs.realpathSync(resolveFrontendDirectory(consumerRoot, frontend));
+  const packageDirectory = fs.realpathSync(
+    resolveFrontendDirectory(consumerRoot, frontend)
+  );
   const packageJson = readPackageJson(packageDirectory);
   const framework = detectFramework(declaredDependencies(packageJson));
   if (framework.unsupported !== null) {
     throw createExitError(
-      framework.unsupported + " found: moving it to Vite is a framework migration, not alignment. eds align supports Vite + React single-page apps.",
-      2,
+      framework.unsupported +
+        " found: moving it to Vite is a framework migration, not alignment. eds align supports Vite + React single-page apps.",
+      2
     );
   }
   if (!framework.vite || !framework.react) {
-    throw createExitError("eds align needs a Vite + React app; " + toPosix(path.join(packageDirectory, "package.json")) + " must declare vite and react.", 2);
+    throw createExitError(
+      "eds align needs a Vite + React app; " +
+        toPosix(path.join(packageDirectory, "package.json")) +
+        " must declare vite and react.",
+      2
+    );
   }
   const topLevel = git(packageDirectory, ["rev-parse", "--show-toplevel"]);
   const gitRoot = topLevel === null ? null : fs.realpathSync(topLevel.trim());
-  const packageRelative = gitRoot === null ? "" : toPosix(path.relative(gitRoot, packageDirectory));
+  const packageRelative =
+    gitRoot === null ? "" : toPosix(path.relative(gitRoot, packageDirectory));
   return { packageDirectory, packageJson, gitRoot, packageRelative };
 }
 
@@ -222,63 +414,217 @@ function requireGit(gitRoot) {
       "eds align needs git: the base commit is how --check proves the backend did not change. Ask the user to create a git repository at " +
         "the project root (the directory that holds both frontend and backend) with a .gitignore covering node_modules, build output and " +
         ".env files, commit everything once, then rerun eds align.",
-      2,
+      2
     );
   }
 }
 
-export function runAlign({ consumerRoot, env = process.env, check = false, frontend = null, dryRun = false, log = console.log }) {
+export function runAlign({
+  consumerRoot,
+  env = process.env,
+  check = false,
+  frontend = null,
+  dryRun = false,
+  nodeVersion = process.versions.node,
+  log = console.log,
+}) {
   const located = locateFrontend({ consumerRoot, frontend });
   // Paths in the output are relative to the current directory, which differs from the frontend package with --frontend.
-  const fromCwd = toPosix(path.relative(consumerRoot, located.packageDirectory));
-  const shown = (relativePath) => (fromCwd === "" ? relativePath : fromCwd + "/" + relativePath);
+  const fromCwd = toPosix(
+    path.relative(consumerRoot, located.packageDirectory)
+  );
+  const shown = (relativePath) =>
+    fromCwd === "" ? relativePath : fromCwd + "/" + relativePath;
   // With --frontend the rerun hint keeps the flag, or the check could not locate the package again.
   const frontendFlag = frontend ? " --frontend " + frontend : "";
-  return check ? runCheck({ ...located, env, log, shown, frontendFlag }) : runPlan({ ...located, env, dryRun, log, fromCwd, shown });
+  return check
+    ? runCheck({ ...located, env, log, shown, frontendFlag, nodeVersion })
+    : runPlan({ ...located, env, dryRun, log, fromCwd, shown, nodeVersion });
 }
 
-function runPlan({ packageDirectory, packageJson, gitRoot, packageRelative, env, dryRun, log, fromCwd, shown }) {
+function runPlan({
+  packageDirectory,
+  packageJson,
+  gitRoot,
+  packageRelative,
+  env,
+  dryRun,
+  log,
+  fromCwd,
+  shown,
+  nodeVersion,
+}) {
   requireGit(gitRoot);
   let pkg;
   try {
     pkg = resolvePackage(packageDirectory);
   } catch {
-    throw createExitError("Install " + packageName + " in " + (packageRelative || ".") + " first (" + installCommand(detectPackageManager(packageDirectory, env)) + "), then run eds align there.", 2);
+    throw createExitError(
+      "Install " +
+        packageName +
+        " in " +
+        (packageRelative || ".") +
+        " first (" +
+        installCommand(detectPackageManager(packageDirectory, env)) +
+        "), then run eds align there.",
+      2
+    );
   }
   if (fs.realpathSync(pkg.packageRoot) !== fs.realpathSync(packageRoot)) {
-    log("[EDS] note: this is eds from " + toPosix(packageRoot) + ", but the frontend has " + packageName + "@" + pkg.version + " installed; run its own CLI (" + cliCommand(detectPackageManager(packageDirectory, env), "align") + ") so the plan matches the installed documents.");
+    log(
+      "[EDS] note: this is eds from " +
+        toPosix(packageRoot) +
+        ", but the frontend has " +
+        packageName +
+        "@" +
+        pkg.version +
+        " installed; run its own CLI (" +
+        cliCommand(detectPackageManager(packageDirectory, env), "align") +
+        ") so the plan matches the installed documents."
+    );
   }
   const packageManager = detectPackageManager(packageDirectory, env);
   const alignPath = path.join(packageDirectory, alignDirectory);
-  const alignRelative = packageRelative === "" ? alignDirectory : packageRelative + "/" + alignDirectory;
+  const alignRelative =
+    packageRelative === ""
+      ? alignDirectory
+      : packageRelative + "/" + alignDirectory;
   const previous = readState(path.join(alignPath, stateFileName), shown);
-
-  const analysis = analyzeFrontend({ packageDirectory, gitRoot, protectedInfo: previous?.protected ?? null });
+  const previousPreservedPaths = normalizeRepositoryPaths(
+    previous?.preservedPaths ?? [],
+    alignRelative
+  );
+  const previousAutoPreservedPaths = normalizeRepositoryPaths(
+    previous?.autoPreservedPaths ??
+      previousPreservedPaths.filter((relativePath) =>
+        isAutomaticPreservedRepositoryPath(relativePath, packageRelative)
+      ),
+    alignRelative
+  );
+  const previousAutoSet = new Set(previousAutoPreservedPaths);
+  const manualPreservedPaths = previousPreservedPaths.filter(
+    (relativePath) => !previousAutoSet.has(relativePath)
+  );
+  const analysis = analyzeFrontend({
+    packageDirectory,
+    gitRoot,
+    protectedInfo: previous?.protected ?? null,
+    preservedPaths: packagePathsFromRepository(
+      previousPreservedPaths,
+      packageRelative
+    ),
+    nodeVersion,
+  });
+  if (analysis.dependencies.unsupportedVite !== null) {
+    const vite = analysis.dependencies.unsupportedVite;
+    throw createExitError(
+      "eds align supports Vite 5.2.0–" +
+        maximumSupportedViteMajor +
+        ".x only; " +
+        (vite === "unknown"
+          ? "the declared Vite version cannot be verified"
+          : vite === "range"
+            ? "the declared Vite range must guarantee Vite 5.2.0 or later within one supported major"
+            : "Vite " + vite + " has not been verified") +
+        ".",
+      2
+    );
+  }
+  if (analysis.dependencies.unsupportedNode !== null) {
+    throw createExitError(
+      "Vite 8 React Compiler setup requires Node " +
+        minimumVersions.nodeForVite8 +
+        " or later; eds align is running on Node " +
+        analysis.dependencies.unsupportedNode +
+        ".",
+      2
+    );
+  }
+  const currentAutoPreservedPaths = analysis.autoPreservedPaths.map(
+    (relativePath) =>
+      packageRelative === ""
+        ? relativePath
+        : packageRelative + "/" + relativePath
+  );
+  const autoPreservedPaths = [
+    ...new Set([...previousAutoPreservedPaths, ...currentAutoPreservedPaths]),
+  ].sort();
+  const preservedRepositoryPaths = [
+    ...new Set([...manualPreservedPaths, ...autoPreservedPaths]),
+  ].sort();
   let base;
   let baseline;
   if (previous !== null) {
     base = previous.git.base;
-    baseline = previous.git.baseline;
+    baseline = { ...(previous.git.baseline ?? {}) };
   } else {
     base = git(gitRoot, ["rev-parse", "--verify", "HEAD"])?.trim() ?? null;
     if (!base) {
-      throw createExitError("The repository has no commit yet, so --check has no base. Ask the user to commit the current files once " +
-        "(with a .gitignore covering node_modules, build output and .env files), then rerun eds align.", 2);
+      throw createExitError(
+        "The repository has no commit yet, so --check has no base. Ask the user to commit the current files once " +
+          "(with a .gitignore covering node_modules, build output and .env files), then rerun eds align.",
+        2
+      );
     }
-    // Uncommitted changes that already exist are the baseline. Only paths the check guards are recorded:
-    // everything else inside the frontend package may change freely.
+    // Record the frontend's existing changes so later-added preserved paths can use the original plan baseline.
+    // The check still ignores ordinary in-package paths that are not protected or preserved.
     baseline = {};
     const guarded = (relativePath) =>
-      analysis.protectedInfo.repository.some((entry) => relativePath === entry || relativePath.startsWith(entry + "/")) ||
-      (packageRelative !== "" && relativePath !== packageRelative && !relativePath.startsWith(packageRelative + "/"));
+      analysis.protectedInfo.repository.some(
+        (entry) =>
+          relativePath === entry || relativePath.startsWith(entry + "/")
+      ) ||
+      preservedRepositoryPaths.some(
+        (entry) =>
+          relativePath === entry || relativePath.startsWith(entry + "/")
+      ) ||
+      (packageRelative !== "" &&
+        relativePath !== packageRelative &&
+        !relativePath.startsWith(packageRelative + "/"));
     for (const relativePath of changedSince(gitRoot, "HEAD")) {
-      if (relativePath !== alignRelative && !relativePath.startsWith(alignRelative + "/") && guarded(relativePath)) {
-        baseline[relativePath] = hashFile(path.join(gitRoot, relativePath));
+      const inPackage =
+        packageRelative === "" ||
+        relativePath === packageRelative ||
+        relativePath.startsWith(packageRelative + "/");
+      if (
+        relativePath !== alignRelative &&
+        !relativePath.startsWith(alignRelative + "/") &&
+        (inPackage || guarded(relativePath))
+      ) {
+        const hash = hashFile(path.join(gitRoot, relativePath));
+        if (hash !== null) baseline[relativePath] = hash;
+      }
+    }
+    Object.assign(baseline, hashPaths(gitRoot, preservedRepositoryPaths));
+  }
+  if (previous !== null) {
+    // A refreshed plan adopts newly added preserved files while keeping earlier file hashes unchanged.
+    for (const [relativePath, hash] of Object.entries(
+      hashPaths(gitRoot, preservedRepositoryPaths)
+    )) {
+      if (!Object.hasOwn(baseline, relativePath)) baseline[relativePath] = hash;
+    }
+  }
+  // Upgrade older plans that did not record preserved paths, then report later edits against this baseline.
+  if (previous?.preservedPaths === undefined) {
+    for (const relativePath of changedSince(gitRoot, base)) {
+      if (
+        preservedRepositoryPaths.some(
+          (entry) =>
+            relativePath === entry || relativePath.startsWith(entry + "/")
+        ) &&
+        !Object.hasOwn(baseline, relativePath)
+      ) {
+        const hash = hashFile(path.join(gitRoot, relativePath));
+        if (hash !== null) baseline[relativePath] = hash;
       }
     }
   }
 
-  analysis.structure = summarizeStructure(analysis.allFiles);
+  analysis.structure = summarizeStructure(
+    analysis.allFiles,
+    analysis.preservedSourcePaths
+  );
   const templates = renderTemplates({
     app: analysis.app,
     protectedInside: analysis.protectedInfo.inside,
@@ -287,7 +633,11 @@ function runPlan({ packageDirectory, packageJson, gitRoot, packageRelative, env,
     strict: readStrictOption(packageDirectory),
   });
   const createdAt = previous?.createdAt ?? new Date().toISOString();
-  const frontendState = { packageRelative, appDir: analysis.app.appDir, srcDir: analysis.app.srcDir };
+  const frontendState = {
+    packageRelative,
+    appDir: analysis.app.appDir,
+    srcDir: analysis.app.srcDir,
+  };
   const state = {
     schemaVersion: stateSchemaVersion,
     createdBy: packageName + "@" + pkg.version,
@@ -295,6 +645,14 @@ function runPlan({ packageDirectory, packageJson, gitRoot, packageRelative, env,
     frontend: frontendState,
     git: { base, baseline },
     protected: analysis.protectedInfo,
+    preservedPaths: preservedRepositoryPaths,
+    autoPreservedPaths,
+    manualPreservedPaths,
+    preservedTsconfigSettings:
+      previous?.preservedTsconfigSettings &&
+      !isLegacyPreservedTsconfigSettings(previous.preservedTsconfigSettings)
+        ? previous.preservedTsconfigSettings
+        : analysis.preservedTsconfigSettings,
   };
   const plan = renderPlan({
     version: pkg.version,
@@ -305,25 +663,71 @@ function runPlan({ packageDirectory, packageJson, gitRoot, packageRelative, env,
     analysis,
     templates: [...templates.keys()],
     alignLabel: alignDirectory,
-    conventionsPath: conventionsPathFrom(packageDirectory, gitRoot, pkg.packageRoot),
+    conventionsPath: conventionsPathFrom(
+      packageDirectory,
+      gitRoot,
+      pkg.packageRoot
+    ),
   });
   const counts = countFindings(analysis.findings);
 
-  log("[EDS] align: frontend " + (packageRelative || ".") + " (Vite " + (analysis.majors.vite ?? "?") + ", React " + (analysis.majors.react ?? "?") +
-    ", " + packageManager.name + "), sources " + analysis.app.srcDir);
+  log(
+    "[EDS] align: frontend " +
+      (packageRelative || ".") +
+      " (Vite " +
+      (analysis.majors.vite ?? "?") +
+      ", React " +
+      (analysis.majors.react ?? "?") +
+      ", " +
+      packageManager.name +
+      "), sources " +
+      analysis.app.srcDir
+  );
   const protectedList = analysis.protectedInfo.repository;
-  log("[EDS] align: protected paths: " + (protectedList.length > 0 ? protectedList.join(", ") : "none detected") +
-    (packageRelative === "" ? "" : ", plus everything outside " + packageRelative));
-  log("[EDS] align: " + counts.errors + " " + plural(counts.errors, "error") + (counts.errorSummary ? " (" + counts.errorSummary + ")" : "") + ", " +
-    counts.warnings + " " + plural(counts.warnings, "warning") + " to resolve");
+  log(
+    "[EDS] align: protected paths: " +
+      (protectedList.length > 0 ? protectedList.join(", ") : "none detected") +
+      (packageRelative === ""
+        ? ""
+        : ", plus files outside " + packageRelative + " (except repository root lockfiles)")
+  );
+  log(
+    "[EDS] align: " +
+      counts.errors +
+      " " +
+      plural(counts.errors, "error") +
+      (counts.errorSummary ? " (" + counts.errorSummary + ")" : "") +
+      ", " +
+      counts.warnings +
+      " " +
+      plural(counts.warnings, "warning") +
+      " to resolve"
+  );
   if (previous !== null) {
-    log("[EDS] align: kept the base commit " + base.slice(0, 12) + " from " + createdAt.slice(0, 10) + "; delete " + shown(alignDirectory) + " to start over.");
+    log(
+      "[EDS] align: kept the base commit " +
+        base.slice(0, 12) +
+        " from " +
+        createdAt.slice(0, 10) +
+        "; delete " +
+        shown(alignDirectory) +
+        " to start over."
+    );
   }
   const planPath = path.join(alignPath, planFileName);
   if (dryRun) {
     const notesExist = fs.existsSync(path.join(alignPath, notesFileName));
-    log("[EDS] would write " + shown(alignDirectory + "/" + planFileName) + ", " + (notesExist ? "" : shown(alignDirectory + "/" + notesFileName) + ", ") +
-      shown(alignDirectory + "/" + stateFileName) + " and " + templates.size + " templates in " + shown(alignDirectory + "/" + templatesDirectoryName));
+    log(
+      "[EDS] would write " +
+        shown(alignDirectory + "/" + planFileName) +
+        ", " +
+        (notesExist ? "" : shown(alignDirectory + "/" + notesFileName) + ", ") +
+        shown(alignDirectory + "/" + stateFileName) +
+        " and " +
+        templates.size +
+        " templates in " +
+        shown(alignDirectory + "/" + templatesDirectoryName)
+    );
     return 0;
   }
 
@@ -332,7 +736,10 @@ function runPlan({ packageDirectory, packageJson, gitRoot, packageRelative, env,
   fs.mkdirSync(alignPath, { recursive: true });
   // The directory ignores itself, so the plan never lands in a commit or in the base comparison.
   fs.writeFileSync(path.join(alignPath, ".gitignore"), "*\n");
-  fs.writeFileSync(path.join(alignPath, stateFileName), JSON.stringify(state, null, 2) + "\n");
+  fs.writeFileSync(
+    path.join(alignPath, stateFileName),
+    JSON.stringify(state, null, 2) + "\n"
+  );
   fs.writeFileSync(planPath, plan);
   const notesPath = path.join(alignPath, notesFileName);
   if (!fs.existsSync(notesPath)) {
@@ -344,55 +751,184 @@ function runPlan({ packageDirectory, packageJson, gitRoot, packageRelative, env,
     fs.writeFileSync(targetPath, contents);
   }
   const commands = packageManagerCommands(packageManager);
-  log("[EDS] wrote " + shown(alignDirectory + "/" + planFileName) + ", " + notesFileName + ", " + stateFileName + " and " + templates.size + " templates (base " + base.slice(0, 12) + ")");
-  log("[EDS] Next: " + (fromCwd === "" ? "" : "cd " + fromCwd + ", then ") + "follow " + alignDirectory + "/" + planFileName + " step by step; " +
-    commands.eds("align --check") + " verifies each step" + (fromCwd === "" ? "." : " (run every PLAN.md command from " + fromCwd + ")."));
+  log(
+    "[EDS] wrote " +
+      shown(alignDirectory + "/" + planFileName) +
+      ", " +
+      notesFileName +
+      ", " +
+      stateFileName +
+      " and " +
+      templates.size +
+      " templates (base " +
+      base.slice(0, 12) +
+      ")"
+  );
+  log(
+    "[EDS] Next: " +
+      (fromCwd === "" ? "" : "cd " + fromCwd + ", then ") +
+      "follow " +
+      alignDirectory +
+      "/" +
+      planFileName +
+      " step by step; " +
+      commands.eds("align --check") +
+      " verifies each step" +
+      (fromCwd === ""
+        ? "."
+        : " (run every PLAN.md command from " + fromCwd + ").")
+  );
   return 0;
 }
 
-// With a plan, the check also proves that no protected or out-of-package file changed since its base commit.
+// With a plan, the check also proves that no protected, preserved or out-of-package file except repository root lockfiles changed since its base commit.
 // Without one (after step 8 removed .eds/align), it checks the conventions only.
-function runCheck({ packageDirectory, gitRoot, packageRelative, env, log, shown, frontendFlag = "" }) {
-  const state = readState(path.join(packageDirectory, alignDirectory, stateFileName), shown);
-  const commands = packageManagerCommands(detectPackageManager(packageDirectory, env));
+function runCheck({
+  packageDirectory,
+  gitRoot,
+  packageRelative,
+  env,
+  log,
+  shown,
+  frontendFlag = "",
+  nodeVersion,
+}) {
+  const state = readState(
+    path.join(packageDirectory, alignDirectory, stateFileName),
+    shown
+  );
+  const commands = packageManagerCommands(
+    detectPackageManager(packageDirectory, env)
+  );
   const findings = [];
   let analysis;
   if (state === null) {
-    log("[EDS] note: no " + shown(alignDirectory + "/" + stateFileName) + ": checking the conventions only (the protected-path check needs the base commit of eds align).");
-    analysis = analyzeFrontend({ packageDirectory, gitRoot: gitRoot ?? packageDirectory });
+    log(
+      "[EDS] note: no " +
+        shown(alignDirectory + "/" + stateFileName) +
+        ": checking the conventions only (the protected-path check needs the base commit of eds align)."
+    );
+    analysis = analyzeFrontend({
+      packageDirectory,
+      gitRoot: gitRoot ?? packageDirectory,
+      nodeVersion,
+    });
   } else {
     requireGit(gitRoot);
-    if (git(gitRoot, ["cat-file", "-e", state.git.base + "^{commit}"]) === null) {
-      throw createExitError("The base commit " + state.git.base.slice(0, 12) + " is not in this repository; delete " + shown(alignDirectory) + " and run eds align again.", 2);
+    if (
+      git(gitRoot, ["cat-file", "-e", state.git.base + "^{commit}"]) === null
+    ) {
+      throw createExitError(
+        "The base commit " +
+          state.git.base.slice(0, 12) +
+          " is not in this repository; delete " +
+          shown(alignDirectory) +
+          " and run eds align again.",
+        2
+      );
     }
-    const alignRelative = packageRelative === "" ? alignDirectory : packageRelative + "/" + alignDirectory;
-    findings.push(...classifyChangedPaths({
-      changed: changedSince(gitRoot, state.git.base),
-      baseline: state.git.baseline ?? {},
-      hashOf: (relativePath) => hashFile(path.join(gitRoot, relativePath)),
-      packageRelative,
-      protectedPaths: state.protected.repository ?? [],
-      alignRelative,
-      base: state.git.base,
-    }));
-    analysis = analyzeFrontend({ packageDirectory, gitRoot, protectedInfo: state.protected });
-    findings.push(...checkBackendPackage({ packageJson: analysis.packageJson, state }));
+    const alignRelative =
+      packageRelative === ""
+        ? alignDirectory
+        : packageRelative + "/" + alignDirectory;
+    const statePreservedPaths = normalizeRepositoryPaths(
+      state.preservedPaths ?? [],
+      alignRelative
+    );
+    findings.push(
+      ...classifyChangedPaths({
+        changed: changedSince(gitRoot, state.git.base),
+        baseline: state.git.baseline ?? {},
+        hashOf: (relativePath) => hashFile(path.join(gitRoot, relativePath)),
+        packageRelative,
+        protectedPaths: state.protected.repository ?? [],
+        preservedPaths: statePreservedPaths,
+        baseTrackedPaths: gitPaths(gitRoot, [
+          "ls-tree",
+          "-r",
+          "-z",
+          "--name-only",
+          state.git.base,
+        ]),
+        alignRelative,
+        base: state.git.base,
+      })
+    );
+    analysis = analyzeFrontend({
+      packageDirectory,
+      gitRoot,
+      protectedInfo: state.protected,
+      preservedPaths: packagePathsFromRepository(
+        statePreservedPaths,
+        packageRelative
+      ),
+      nodeVersion,
+    });
+    findings.push(
+      ...checkBackendPackage({ packageJson: analysis.packageJson, state })
+    );
+    findings.push(
+      ...checkPreservedTsconfigSettings({
+        baseline: state.preservedTsconfigSettings,
+        current: analysis.preservedTsconfigSettings,
+      })
+    );
   }
   findings.push(...analysis.findings);
   const counts = countFindings(findings);
   const since = state === null ? "" : " since " + state.git.base.slice(0, 12);
   logFindings(findings, log);
   if (counts.errors === 0) {
-    log("[EDS] align: " + analysis.app.srcDir + " follows the EVA frontend conventions" +
-      (state === null ? "" : ", and no protected or out-of-package file changed" + since) +
-      (counts.warnings > 0 ? " (" + counts.warnings + " " + plural(counts.warnings, "warning") + ": fix them or record why)" : "") + ".");
-    log("[EDS] Also required: " + verificationCommands(commands) + " (each must exit 0, and eds:doctor must print [EDS] synced with)" +
-      (state === null ? "." : ", then step 8 of " + shown(alignDirectory + "/" + planFileName) + "."));
+    log(
+      "[EDS] align: " +
+        analysis.app.srcDir +
+        " follows the EVA frontend conventions" +
+        (state === null
+          ? ""
+          : ", and no protected, preserved or out-of-package file changed (repository root lockfiles are excluded)" +
+            since) +
+        (counts.warnings > 0
+          ? " (" +
+            counts.warnings +
+            " " +
+            plural(counts.warnings, "warning") +
+            ": fix them or record why)"
+          : "") +
+        "."
+    );
+    log(
+      "[EDS] Also required: " +
+        verificationCommands(commands) +
+        " (each must exit 0, and eds:doctor must print [EDS] synced with)" +
+        (state === null
+          ? "."
+          : ", then step 8 of " +
+            shown(alignDirectory + "/" + planFileName) +
+            ".")
+    );
     return 0;
   }
-  log("[EDS] align: " + counts.errors + " " + plural(counts.errors, "error") + " (" + counts.errorSummary + "), " + counts.warnings + " " +
-    plural(counts.warnings, "warning") + since + ". Fix the errors and run " + commands.eds("align --check" + frontendFlag) + " again" +
-    (state === null ? "." : "; " + shown(alignDirectory + "/" + planFileName) + " maps each kind to a step, and protected, outside and backend-* errors mean revert that change."));
+  log(
+    "[EDS] align: " +
+      counts.errors +
+      " " +
+      plural(counts.errors, "error") +
+      " (" +
+      counts.errorSummary +
+      "), " +
+      counts.warnings +
+      " " +
+      plural(counts.warnings, "warning") +
+      since +
+      ". Fix the errors and run " +
+      commands.eds("align --check" + frontendFlag) +
+      " again" +
+      (state === null
+        ? "."
+        : "; " +
+          shown(alignDirectory + "/" + planFileName) +
+          " maps each kind to a step; protected, preserved, outside and backend-* errors mean revert that change.")
+  );
   return 1;
 }