@spectrabrain/eds 0.1.0 → 0.1.1

package/consumer/align-analysis.mjs

@@ -0,0 +1,1159 @@
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import {
+  allowedSourceRootFiles,
+  appEntries,
+  auxiliarySourceDirectories,
+  backendClientPackages,
+  backendDataClientPackages,
+  edsLucideVersion,
+  templateToolMinimums,
+  backendDirectoryNames,
+  backendMarkerFiles,
+  backendScriptPattern,
+  backendServerPackages,
+  conventionsFileName,
+  entitySegments,
+  entryModule,
+  featureSegments,
+  generatedStylesFileName,
+  layerOrder,
+  minimumMajors,
+  replacementRules,
+  requiredDependencies,
+  requiredDevDependencies,
+  requiredScripts,
+  requiredSourceFiles,
+  rolldownBabelPackage,
+  rootLockfiles,
+  sharedSegments,
+  sharedWithBackendDirectoryName,
+  slicedLayers,
+  structureHints,
+  templateDevDependencies,
+  testDirectoryNames,
+  testFilePattern,
+  testSetupFilePattern,
+  testSupportHint,
+  testToolingPattern,
+  unsupportedFrameworks,
+} from "./align-rules.mjs";
+import { createExitError, generatedCssRelativePath, readTextIfExists, toPosix } from "./paths.mjs";
+
+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 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 prettierConfigNames = [
+  ".prettierrc",
+  ".prettierrc.json",
+  ".prettierrc.json5",
+  ".prettierrc.yaml",
+  ".prettierrc.yml",
+  ".prettierrc.toml",
+  ".prettierrc.js",
+  ".prettierrc.cjs",
+  ".prettierrc.mjs",
+  ".prettierrc.ts",
+  "prettier.config.js",
+  "prettier.config.cjs",
+  "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"];
+// Packages an aligned frontend may declare besides the required ones; anything else is listed for review.
+const conventionalPackages = new Set([
+  ...requiredDependencies,
+  ...requiredDevDependencies,
+  ...templateDevDependencies,
+  rolldownBabelPackage,
+  "axios",
+  "zustand",
+  "lucide-react",
+  "class-variance-authority",
+  "date-fns",
+  "react-day-picker",
+  "react-virtuoso",
+  "react-markdown",
+  "remark-gfm",
+  "msw",
+  "@faker-js/faker",
+  "@tailwindcss/postcss",
+  "@tailwindcss/vite",
+  "tailwindcss-animate",
+  "postcss",
+  "autoprefixer",
+  "shadcn",
+  "js-cookie",
+  "@types/js-cookie",
+  "@types/react",
+  "@types/react-dom",
+  "@types/node",
+]);
+
+export function hashFile(filePath) {
+  try {
+    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 !== "."));
+  return joined === "" ? "." : joined;
+}
+
+// Test files, files in test directories and test setup files are outside the conventions: every check skips them.
+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]);
+}
+
+// Blanks // and /* */ comments while keeping strings, template literals and every line break, so indices and
+// line numbers still point into the original text. Regular expression literals are recognized heuristically.
+export function stripComments(source) {
+  const output = [];
+  const templateDepth = [];
+  let index = 0;
+  let lastSignificant = "";
+  const blank = (text) => text.replace(/[^\r\n]/g, " ");
+  while (index < source.length) {
+    const character = source[index];
+    const next = source[index + 1];
+    if (character === "/" && next === "/") {
+      const end = source.indexOf("\n", index);
+      const stop = end < 0 ? source.length : end;
+      output.push(blank(source.slice(index, stop)));
+      index = stop;
+      continue;
+    }
+    if (character === "/" && next === "*") {
+      const end = source.indexOf("*/", index + 2);
+      const stop = end < 0 ? source.length : end + 2;
+      output.push(blank(source.slice(index, stop)));
+      index = stop;
+      continue;
+    }
+    if (character === "\"" || character === "'") {
+      let end = index + 1;
+      while (end < source.length && source[end] !== character && source[end] !== "\n") {
+        end += source[end] === "\\" ? 2 : 1;
+      }
+      output.push(source.slice(index, end + 1));
+      index = end + 1;
+      lastSignificant = character;
+      continue;
+    }
+    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] === "{")) {
+        end += source[end] === "\\" ? 2 : 1;
+      }
+      if (source[end] === "$") {
+        templateDepth.push(0);
+        output.push(source.slice(index, end + 2));
+        index = end + 2;
+        lastSignificant = "{";
+        continue;
+      }
+      output.push(source.slice(index, end + 1));
+      index = end + 1;
+      lastSignificant = "`";
+      continue;
+    }
+    if (character === "/" && (lastSignificant === "" || "(,=:[!&|?{};+-*%<>~^".includes(lastSignificant))) {
+      let end = index + 1;
+      let inClass = false;
+      while (end < source.length && source[end] !== "\n" && (inClass || source[end] !== "/")) {
+        if (source[end] === "\\") {
+          end += 2;
+          continue;
+        }
+        if (source[end] === "[") inClass = true;
+        if (source[end] === "]") inClass = false;
+        end += 1;
+      }
+      output.push(source.slice(index, end + 1));
+      index = end + 1;
+      lastSignificant = "/";
+      continue;
+    }
+    if (templateDepth.length > 0) {
+      if (character === "{") templateDepth[templateDepth.length - 1] += 1;
+      if (character === "}") templateDepth[templateDepth.length - 1] -= 1;
+    }
+    if (!/\s/.test(character)) {
+      lastSignificant = character;
+    }
+    output.push(character);
+    index += 1;
+  }
+  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"));
+}
+
+function lineNumberAt(text, index) {
+  let line = 1;
+  for (let position = text.indexOf("\n"); position >= 0 && position < index; position = text.indexOf("\n", position + 1)) {
+    line += 1;
+  }
+  return line;
+}
+
+const importPatterns = [
+  /(?:^|[^\w$.])(?:import|export)\s+(?:type\s+)?(?:[\w$*{}\s,]+?\s+from\s*)?["']([^"'\n]+)["']/g,
+  /(?:^|[^\w$.])import\s*\(\s*["']([^"'\n]+)["']\s*\)/g,
+  /(?:^|[^\w$.])require\s*\(\s*["']([^"'\n]+)["']\s*\)/g,
+];
+
+// Static, dynamic and require() module specifiers with their line numbers.
+export function extractImports(source) {
+  const code = stripComments(source);
+  const found = [];
+  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) });
+    }
+  }
+  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:")) {
+    return null;
+  }
+  const parts = specifier.split("/");
+  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,
+// { outside: true } for a relative import that leaves it, or null for packages and other aliases.
+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 (joined === ".." || joined.startsWith("../")) {
+      return { outside: true };
+    }
+    return { path: joined, alias: false };
+  }
+  return null;
+}
+
+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;
+  return { layer, slice };
+}
+
+// One import checked against the FSD direction rules. Entities may import other entities (the EVA convention).
+export function checkImportRule({ fromPath, specifier, line, srcLabel }) {
+  const target = resolveSourceImport(fromPath, specifier);
+  if (target === null || target.outside) {
+    return null;
+  }
+  const source = classifyModule(fromPath);
+  const destination = classifyModule(target.path);
+  if (source.layer === null || destination.layer === null) {
+    return null;
+  }
+  const location = joinPosix(srcLabel, fromPath) + ":" + line;
+  const sourceRank = layerOrder.indexOf(source.layer);
+  const destinationRank = layerOrder.indexOf(destination.layer);
+  if (destinationRank < sourceRank) {
+    return {
+      level: "error",
+      kind: "import",
+      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")) {
+    return {
+      level: "error",
+      kind: "import",
+      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 + ")",
+    };
+  }
+  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,
+    };
+  }
+  return null;
+}
+
+export function checkImports({ files, srcLabel }) {
+  const findings = [];
+  for (const file of files) {
+    if (isTestSupport(file.path)) {
+      continue;
+    }
+    for (const { specifier, line } of extractImports(file.contents)) {
+      const finding = checkImportRule({ fromPath: file.path, specifier, line, srcLabel });
+      if (finding !== null) {
+        findings.push(finding);
+      }
+    }
+  }
+  return findings;
+}
+
+// Walks a directory and returns file paths relative to it (POSIX). Dependency, build and dot directories are skipped.
+export function walkFiles(root) {
+  if (!fs.existsSync(root)) {
+    return [];
+  }
+  const files = [];
+  const walk = (directory, prefix) => {
+    for (const entry of fs.readdirSync(directory, { withFileTypes: true })) {
+      if (entry.name.startsWith(".") && entry.isDirectory()) {
+        continue;
+      }
+      const relativePath = prefix === "" ? entry.name : prefix + "/" + entry.name;
+      if (entry.isDirectory()) {
+        if (!walkExcludedDirectories.has(entry.name)) {
+          walk(path.join(directory, entry.name), relativePath);
+        }
+      } else if (entry.isFile()) {
+        files.push(relativePath);
+      }
+    }
+  };
+  walk(root, "");
+  return files.sort();
+}
+
+export function checkStructure({ files, srcLabel }) {
+  const findings = [];
+  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)) {
+      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)" });
+    }
+    if (parts.length === 1) {
+      if (!allowedSourceRootFiles.includes(file)) {
+        const hint = structureHints[file.toLowerCase()];
+        const [target, ...remark] = (hint ?? "").split(" ");
+        if (target.includes("/")) {
+          movedTargets.add(target);
+          error(label(file) + " must move to " + label(target) + (remark.length > 0 ? " " + remark.join(" ") : ""));
+        } else {
+          error(label(file) + " must live inside a layer" + (hint ? " (" + hint + ")" : ""));
+        }
+      }
+      continue;
+    }
+    const [top] = parts;
+    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 + "/)");
+      }
+      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)");
+      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");
+    } else if (top === "app" && !appEntries.includes(parts[1])) {
+      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(", ") + ")");
+    } 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(", ") + ")");
+      } else if (parts.length > 3 && !entitySegments.includes(parts[2])) {
+        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");
+    }
+  }
+
+  const fileSet = new Set(files);
+  for (const requiredFile of requiredSourceFiles) {
+    if (!fileSet.has(requiredFile) && !movedTargets.has(requiredFile)) {
+      error("missing " + label(requiredFile));
+    }
+  }
+  // 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);
+}
+
+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)");
+  }
+}
+
+// features/<domain>/{ui,lib,types}/... is shared inside the domain; features/<domain>/<feature>/{ui,lib,types}/... is one feature.
+function checkFeaturePath(parts, file, label, warning) {
+  if (parts.length === 2) {
+    warning(label(file) + " belongs in features/<domain>/<feature>/");
+    return;
+  }
+  if (parts.length === 3) {
+    if (parts[2] !== "index.ts") {
+      warning(label(file) + " belongs in a feature segment (" + featureSegments.join(", ") + ")");
+    }
+    return;
+  }
+  if (featureSegments.includes(parts[2])) {
+    return;
+  }
+  if (!kebabCasePattern.test(parts[2])) {
+    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(", ") + ")");
+  } else if (parts.length > 4 && !featureSegments.includes(parts[3])) {
+    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 }) {
+  const findings = [];
+  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")) {
+      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*\(/);
+    if (axiosIndex >= 0 && !inSharedApi) {
+      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");
+    }
+  }
+
+  for (const file of allFiles) {
+    if (isTestSupport(file)) {
+      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");
+    }
+  }
+  return findings;
+}
+
+export function majorOf(version) {
+  const match = String(version ?? "").match(/^[^\d]*(\d+)/);
+  return match ? Number.parseInt(match[1], 10) : null;
+}
+
+// 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"));
+    if (manifest !== null) {
+      try {
+        return String(JSON.parse(manifest).version ?? "") || null;
+      } catch {
+        return null;
+      }
+    }
+    const parent = path.dirname(directory);
+    if (parent === directory) {
+      return null;
+    }
+    directory = parent;
+  }
+}
+
+export function declaredDependencies(packageJson) {
+  const declared = new Map();
+  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 });
+      }
+    }
+  }
+  return declared;
+}
+
+export function detectFramework(declared) {
+  const unsupported = unsupportedFrameworks.find(([name]) => declared.has(name));
+  return {
+    unsupported: unsupported ? unsupported[1] : null,
+    react: declared.has("react"),
+    vite: declared.has("vite"),
+  };
+}
+
+// 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;
+}
+
+export function isOlderVersion(version, minimum) {
+  const actual = versionParts(version);
+  const required = versionParts(minimum);
+  if (actual === null || required === null) {
+    return false;
+  }
+  for (let index = 0; index < 3; index += 1) {
+    if (actual[index] !== required[index]) {
+      return actual[index] < required[index];
+    }
+  }
+  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 }) {
+  const replacements = [];
+  const replaced = new Set();
+  for (const rule of replacementRules) {
+    for (const name of rule.packages) {
+      if (declared.has(name)) {
+        replaced.add(name);
+        replacements.push({
+          name,
+          category: rule.category,
+          target: rule.target,
+          label: rule.label ?? rule.target,
+          keptForBackend: backendUsed.has(name),
+        });
+      }
+    }
+  }
+  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 missing = [];
+  for (const name of requiredDependencies) {
+    if (!declared.has(name)) missing.push({ name, dev: name === "tailwindcss" });
+  }
+  if (!sdkOnly && !declared.has("axios")) {
+    missing.push({ name: "axios", dev: false });
+  }
+  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 });
+  }
+  const outdated = [];
+  for (const [name, minimum] of Object.entries(minimumMajors)) {
+    const major = majors[name] ?? majorOf(declared.get(name)?.range);
+    if (declared.has(name) && major !== null && major < minimum) {
+      outdated.push({ name, major, minimum });
+    }
+  }
+  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();
+  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 };
+}
+
+export function checkDependencies(classification) {
+  const findings = [];
+  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 + ")" });
+    }
+  }
+  for (const entry of classification.missing) {
+    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" });
+  }
+  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",
+    });
+  }
+  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 + ")" });
+  }
+  return findings;
+}
+
+function findExisting(directory, names) {
+  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("#"));
+}
+
+export function ignoreCovers(lines, relativePath) {
+  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));
+}
+
+export function readScriptEntry(indexHtml) {
+  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 }) {
+  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 eslintConfig = findExisting(packageDirectory, eslintConfigNames);
+  if (eslintConfig === null) {
+    error("config", "no ESLint flat config (eslint.config.js)");
+  } 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));
+    if (unignored.length > 0) {
+      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");
+  }
+
+  if (findExisting(packageDirectory, prettierConfigNames) === null && packageJson.prettier === undefined) {
+    error("config", "no Prettier config (.prettierrc.json)");
+  }
+  const prettierIgnore = read(".prettierignore");
+  if (prettierIgnore === null) {
+    error("config", "no .prettierignore");
+  } else {
+    const lines = readIgnoreLines(prettierIgnore);
+    const required = [toPosix(generatedCssRelativePath), ...protectedInside];
+    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)");
+    }
+  }
+
+  checkTsconfig({ packageDirectory, app, read, error });
+
+  const viteConfig = findExisting(packageDirectory, viteConfigNames);
+  if (viteConfig === null) {
+    error("config", "no vite.config.ts");
+  } else {
+    const contents = read(viteConfig);
+    if (!/babel-plugin-react-compiler|reactCompilerPreset/.test(contents)) {
+      error("config", viteConfig + " does not enable the React Compiler");
+    }
+    if (!/["']@["']\s*:|find\s*:\s*["']@["']/.test(contents)) {
+      error("config", viteConfig + " does not define the @ alias");
+    }
+    if (!/svgr/.test(contents)) {
+      warning("config", viteConfig + " does not register vite-plugin-svgr");
+    }
+    // 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)");
+    }
+  }
+  if (declared.has("@tailwindcss/postcss")) {
+    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-"));
+  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");
+      }
+    } catch (parseError) {
+      warning("config", "components.json could not be parsed (" + parseError.message + ")");
+    }
+  } else if (usesRadix) {
+    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);
+  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 + ")"));
+  }
+
+  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 + "\")");
+    }
+  }
+
+  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)");
+  }
+  return findings;
+}
+
+function checkTsconfig({ packageDirectory, app, read, error }) {
+  const candidates = ["tsconfig.json", "tsconfig.app.json"];
+  const expected = new Set(["./" + app.srcDir + "/*", app.srcDir + "/*"]);
+  for (const name of candidates) {
+    const text = read(name);
+    if (text === null) {
+      continue;
+    }
+    try {
+      const paths = parseJsonc(text).compilerOptions?.paths?.["@/*"];
+      if (Array.isArray(paths) && expected.has(String(paths[0]))) {
+        return;
+      }
+    } catch (parseError) {
+      error("config", name + " could not be parsed (" + parseError.message + ")");
+      return;
+    }
+  }
+  error("config", "tsconfig.json must map \"@/*\" to [\"./" + app.srcDir + "/*\"]");
+}
+
+// Finds package directories (relative to root) whose package.json declares react.
+export function findFrontendPackages(root) {
+  const found = [];
+  const visit = (directory, depth) => {
+    const manifest = readTextIfExists(path.join(directory, "package.json"));
+    if (manifest !== null) {
+      try {
+        if (declaredDependencies(JSON.parse(manifest)).has("react")) {
+          found.push(toPosix(path.relative(root, directory)) || ".");
+        }
+      } catch {
+        // A broken package.json is not a frontend candidate.
+      }
+    }
+    if (depth >= frontendSearchDepth) {
+      return;
+    }
+    for (const entry of fs.readdirSync(directory, { withFileTypes: true })) {
+      if (entry.isDirectory() && !entry.name.startsWith(".") && !walkExcludedDirectories.has(entry.name)) {
+        visit(path.join(directory, entry.name), depth + 1);
+      }
+    }
+  };
+  visit(root, 0);
+  return found;
+}
+
+// The Vite root is the directory of index.html; the source directory is src/ next to it.
+export function locateApp(packageDirectory) {
+  const candidates = [];
+  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)) || ".");
+    }
+    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") {
+        visit(path.join(directory, entry.name), depth + 1);
+      }
+    }
+  };
+  visit(packageDirectory, 0);
+  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,
+    );
+  }
+  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);
+  }
+  const indexHtml = readTextIfExists(path.join(packageDirectory, appDir, "index.html"));
+  return { appDir, srcDir, entry: readScriptEntry(indexHtml) };
+}
+
+function isDirectory(filePath) {
+  try {
+    return fs.statSync(filePath).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+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") }));
+}
+
+// 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),
+  ];
+  return candidates.find((candidate) => fs.existsSync(path.join(packageDirectory, candidate)) && !isDirectory(path.join(packageDirectory, candidate))) ?? relativePath;
+}
+
+// Binaries whose package name differs from the command.
+const binaryPackages = { tsc: "typescript" };
+
+// Declared packages a backend script runs (for example tsx, esbuild, drizzle-kit).
+function scriptPackages(command, declared) {
+  return command
+    .split(/[\s;&|()]+/)
+    .filter((token) => token !== "" && !token.includes("="))
+    .map((token) => binaryPackages[token] ?? token)
+    .filter((token) => declared.has(token));
+}
+
+// Backend and deployment paths. inside: relative to the package; repository: relative to the git root.
+export function detectProtectedPaths({ packageDirectory, gitRoot, declared, scripts }) {
+  const packageRelative = toPosix(path.relative(gitRoot, packageDirectory));
+  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))) {
+    inside.push(sharedWithBackendDirectoryName);
+  }
+  for (const name of backendMarkerFiles) {
+    if (fs.existsSync(path.join(packageDirectory, name))) inside.push(name);
+  }
+  const repositoryOnly = [];
+  if (packageRelative !== "") {
+    for (const name of [...backendDirectoryNames, ...backendMarkerFiles]) {
+      if (fs.existsSync(path.join(gitRoot, name))) repositoryOnly.push(name);
+    }
+  }
+
+  // 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 importedFrontendFiles = new Set();
+  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)))) {
+      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));
+          if (!target.startsWith("..") && !isInsideProtected(target)) {
+            importedFrontendFiles.add(resolveModuleFile(packageDirectory, target));
+          }
+        }
+      }
+    }
+  }
+
+  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))) {
+      backendScripts[name] = command;
+      for (const packageUsed of scriptPackages(command, declared)) {
+        backendUsed.add(packageUsed);
+      }
+    }
+  }
+
+  return {
+    inside,
+    repository: [...inside.map(toRepository), ...repositoryOnly],
+    repositoryOnly,
+    backendUsed: [...backendUsed].sort(),
+    importedFrontendFiles: [...importedFrontendFiles].sort(),
+    backendScripts,
+  };
+}
+
+// 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 }) {
+  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 + "/")) {
+      continue;
+    }
+    if (Object.prototype.hasOwnProperty.call(baseline, relativePath) && baseline[relativePath] === hashOf(relativePath)) {
+      continue;
+    }
+    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)",
+      });
+    } 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;
+}
+
+export function checkBackendPackage({ packageJson, state }) {
+  const findings = [];
+  const scripts = packageJson.scripts ?? {};
+  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]) + ")"),
+      });
+    }
+  }
+  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" });
+    }
+  }
+  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"));
+  const declared = declaredDependencies(packageJson);
+  const app = locateApp(packageDirectory);
+  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"]) {
+    const installed = installedVersion(packageDirectory, name);
+    majors[name] = 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 });
+  // 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 })));
+  const findings = [
+    ...checkStructure({ files: allFiles, srcLabel: app.srcDir }),
+    ...checkImports({ files: sourceFiles, srcLabel: app.srcDir }),
+    ...checkDependencies(dependencies),
+    ...checkConfigs({ packageDirectory, packageJson, app, protectedInside: detectedProtected.inside, declared }),
+    ...checkPatterns({ files: sourceFiles, allFiles, srcLabel: app.srcDir }),
+  ];
+  return { packageJson, declared, app, protectedInfo: detectedProtected, majors, dependencies, allFiles, findings };
+}
+
+// src/ top-level entries with their file counts and where each goes.
+export function summarizeStructure(allFiles) {
+  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 };
+    entry.files += 1;
+    entries.set(top, entry);
+  }
+  return [...entries.values()].map((entry) => {
+    const test = entry.type === "directory" ? testDirectoryNames.includes(entry.name) : isTestSupport(entry.name);
+    return {
+      ...entry,
+      fsd: test || layerOrder.includes(entry.name) || auxiliarySourceDirectories.includes(entry.name) || allowedSourceRootFiles.includes(entry.name),
+      hint: test ? testSupportHint : structureHints[entry.name.toLowerCase()] ?? null,
+    };
+  });
+}