claudeos-core 2.4.3 → 2.5.0

package/plan-installer/scanners/scan-frontend.js

@@ -61,7 +61,11 @@ function dirGlobPrefix(dir) {
   return fwd.endsWith("/") ? fwd : fwd + "/";
 }
 
-async function scanFrontendDomains(stack, ROOT) {
+// `opts.projectRoot` (v2.5.0): when the SPA lives in a sub-directory, ROOT is
+// that sub-directory (so all globs are relative to it) while `.claudeos-scan.json`
+// is still read from the PROJECT root, where it is documented to live.
+async function scanFrontendDomains(stack, ROOT, opts = {}) {
+  const PROJECT_ROOT = opts.projectRoot || ROOT;
   const frontendDomains = [];
 
   // ── Angular ──
@@ -129,9 +133,63 @@ async function scanFrontendDomains(stack, ROOT) {
     const skipPages = ["api", "_app", "_document", "fonts", "not-found", "error", "loading",
       "components", "hooks", "widgets", "entities", "features", "modules",
       "lib", "libs", "utils", "util", "config", "types", "shared", "common", "assets"];
-    for (const dir of allDirs) {
+
+    // v2.5.0 — Next.js App Router route groups. `app/(marketing)/about/`,
+    // `app/(shop)/cart/` — the parenthesized folder is invisible in the URL
+    // and exists only to share layouts. Pre-v2.5.0 these were skipped
+    // outright (`name.startsWith("(")`), so any project that organizes
+    // routes under groups (the App Router default in most starters) came
+    // back with ZERO route domains. Expand each group one level so its
+    // children are evaluated exactly like top-level route folders. Nested
+    // groups (`(a)/(b)/x`) are expanded recursively up to 3 levels.
+    async function expandRouteGroups(dirs, depth = 0) {
+      const out = [];
+      for (const dir of dirs) {
+        const name = path.basename(dir.replace(/\/$/, ""));
+        if (name.startsWith("(") && name.endsWith(")") && depth < 3) {
+          const children = await glob(`${dirGlobPrefix(dir)}*/`, { cwd: ROOT, ignore: ["**/node_modules/**"] });
+          out.push(...await expandRouteGroups(children, depth + 1));
+        } else {
+          out.push(dir);
+        }
+      }
+      return out;
+    }
+    const routeDirs = [...new Set(await expandRouteGroups(allDirs))];
+    // Same leaf under different route groups — `(shop)/settings` and
+    // `(admin)/settings` — are DIFFERENT features. Domain names must stay
+    // unique (domain-groups.json, per-domain rules/standards are keyed by
+    // name), so colliding leaves are qualified with their group path:
+    // `shop-settings`, `admin-settings`. Non-colliding leaves keep the bare name.
+    // Two qualification levels: (1) segments after the last `app`/`pages`
+    // (route groups: `shop-settings`); (2) if still not unique — leaves that
+    // differ only BEFORE `pages`, such as `src/mobile/pages/home` vs
+    // `src/desktop/pages/home` — every non-structural segment of the path
+    // (`mobile-home`, `desktop-home`).
+    const STRUCTURAL = new Set(["src", "app", "pages", "apps", "packages"]);
+    const qualify = (dir, full) => {
+      const segs = dir.replace(/\\/g, "/").replace(/\/$/, "").split("/");
+      let from;
+      if (full) from = 0;
+      else {
+        const anchor = Math.max(segs.lastIndexOf("app"), segs.lastIndexOf("pages"));
+        // Segments after the `app`/`pages` anchor (route groups → `shop-settings`).
+        // Without an anchor (`src/views/home`), or when the anchored form adds
+        // nothing (`src/pages/home` → still `home`), qualify with the immediate
+        // parent (`views-home`, `pages-home`) — never with the whole path.
+        from = anchor >= 0 && anchor + 1 < segs.length - 1 ? anchor + 1 : Math.max(0, segs.length - 2);
+      }
+      return segs.slice(from).filter(s => !full || !STRUCTURAL.has(s)).map(s => s.replace(/^\((.*)\)$/, "$1")).join("-");
+    };
+    const count = (arr) => arr.reduce((m, n) => { m[n] = (m[n] || 0) + 1; return m; }, {});
+    const leafCount = count(routeDirs.map(d => path.basename(d)));
+    const level1 = new Map(routeDirs.map(d => [d, leafCount[path.basename(d)] > 1 ? qualify(d, false) : path.basename(d)]));
+    const level1Count = count([...level1.values()]);
+    const domainNames = new Map(routeDirs.map(d => [d, level1Count[level1.get(d)] > 1 ? qualify(d, true) : level1.get(d)]));
+    for (const dir of routeDirs) {
       const name = path.basename(dir);
       if (skipPages.includes(name) || name.startsWith("(") || name.startsWith("[") || name.startsWith("_") || name.startsWith(".")) continue;
+      const domainName = domainNames.get(dir);
       const files = await glob(`${dirGlobPrefix(dir)}**/*.{tsx,jsx,ts,js,vue}`, { cwd: ROOT });
       if (files.length > 0) {
         const pages = files.filter(f => /page\.|index\./.test(f)).length;
@@ -140,7 +198,7 @@ async function scanFrontendDomains(stack, ROOT) {
         const serverFiles = pages + layouts;
         const components = files.filter(f => !/page\.|layout\.|index\.|client\./.test(f)).length;
         frontendDomains.push({
-          name, type: "frontend", pages, layouts, clientFiles, serverFiles, components, totalFiles: files.length,
+          name: domainName, type: "frontend", pages, layouts, clientFiles, serverFiles, components, totalFiles: files.length,
           rscPattern: clientFiles > 0 ? "RSC+Client split" : "default",
         });
       }
@@ -190,7 +248,9 @@ async function scanFrontendDomains(stack, ROOT) {
         const parts = f.replace(/\\/g, "/").split("/");
         const appIdx = parts.indexOf("app");
         const pagesIdx = parts.indexOf("pages");
-        const baseIdx = appIdx >= 0 ? appIdx : pagesIdx;
+        let baseIdx = appIdx >= 0 ? appIdx : pagesIdx;
+        // Route groups `(group)` are URL-transparent — step over them.
+        while (baseIdx >= 0 && baseIdx + 1 < parts.length - 1 && /^\(.*\)$/.test(parts[baseIdx + 1])) baseIdx++;
         if (baseIdx >= 0 && baseIdx + 1 < parts.length - 1) {
           const domain = parts[baseIdx + 1];
           if (!skipNames.includes(domain) && !domain.startsWith("_") && !domain.startsWith("(") && !domain.startsWith("[") && !domain.startsWith(".")) {
@@ -204,7 +264,8 @@ async function scanFrontendDomains(stack, ROOT) {
       for (const f of clientFiles) {
         const parts = f.replace(/\\/g, "/").split("/");
         const appIdx = parts.indexOf("app");
-        const baseIdx = appIdx >= 0 ? appIdx : -1;
+        let baseIdx = appIdx >= 0 ? appIdx : -1;
+        while (baseIdx >= 0 && baseIdx + 1 < parts.length - 1 && /^\(.*\)$/.test(parts[baseIdx + 1])) baseIdx++;
         if (baseIdx >= 0 && baseIdx + 1 < parts.length - 1) {
           const domain = parts[baseIdx + 1];
           if (domainSet[domain]) {
@@ -298,7 +359,7 @@ async function scanFrontendDomains(stack, ROOT) {
   // by routes/-file layouts, which appear across all frontend frameworks.
   if (stack.frontend) {
     // Read optional per-project override (.claudeos-scan.json).
-    const overrides = loadScanOverrides(ROOT).frontendScan || {};
+    const overrides = loadScanOverrides(PROJECT_ROOT).frontendScan || {};
     // Platform-split layout: src/{platform}/{subapp}/ where platform is a
     // device/target-environment OR access-tier keyword. Both form the same
     // structural pattern (top-level segmentation with a common subapp layout).

package/plan-installer/scanners/scan-java.js

@@ -17,11 +17,49 @@ const { glob } = require("glob");
 // Normalize backslash paths from glob on Windows to forward slashes
 const norm = (p) => p.replace(/\\/g, "/");
 
+// v2.5.0 — Module-aware scanning.
+// Source roots (`[<module>/]src/main/java`, `[<module>/]src/main/resources`)
+// are discovered ONCE with a single ignore-filtered walk; every subsequent
+// pattern is then anchored at each discovered module prefix. This finds
+// Gradle/Maven multi-module layouts (`api/src/main/java/...`) with the same
+// pattern set as a single-module root, without re-walking the whole tree
+// (node_modules, web bundles, build output) for every per-domain glob.
+// `src/test/**` and `buildSrc/` are excluded: test-fixture projects
+// (`src/test/resources/projects/demo/src/main/java/...`) and Gradle
+// convention plugins are not application modules.
+const JAVA_ROOT_IGNORE = ["**/node_modules/**", "**/build/**", "**/target/**", "**/out/**", "**/.gradle/**", "**/generated/**", "**/.git/**", "**/src/test/**", "**/buildSrc/**"];
+
+async function discoverModulePrefixes(ROOT) {
+  const javaRoots = (await glob("**/src/main/java/", { cwd: ROOT, ignore: JAVA_ROOT_IGNORE })).map(norm);
+  const resRoots = (await glob("**/src/main/resources/", { cwd: ROOT, ignore: JAVA_ROOT_IGNORE })).map(norm);
+  const prefixes = new Set();
+  for (const r of [...javaRoots, ...resRoots]) {
+    const m = r.replace(/\/$/, "").match(/^(.*?)src\/main\/(?:java|resources)$/);
+    if (m) prefixes.add(m[1]); // "" for root, "api/" for a module
+  }
+  return [...prefixes].sort();
+}
+
+// Run one `src/main/...`-relative pattern against every discovered module
+// prefix and return the merged, normalized, de-duplicated file list.
+function makeModuleGlob(ROOT, prefixes) {
+  return async (pattern) => {
+    const out = new Set();
+    for (const pre of prefixes) {
+      for (const f of await glob(pre + pattern, { cwd: ROOT })) out.add(norm(f));
+    }
+    return [...out];
+  };
+}
+
 async function scanJavaDomains(stack, ROOT) {
   const backendDomains = [];
   let rootPackage = null;
 
-  const javaFiles = (await glob("src/main/java/**/*.java", { cwd: ROOT })).map(norm);
+  const modulePrefixes = await discoverModulePrefixes(ROOT);
+  const gj = makeModuleGlob(ROOT, modulePrefixes.length ? modulePrefixes : [""]);
+
+  const javaFiles = (await gj("src/main/java/**/*.java"));
 
   // v2.4.0 — Pick the LONGEST package prefix (1-4 segments) that still
   // covers ≥80% of layer-bearing files. Pre-v2.4.0 the first matched file
@@ -62,8 +100,86 @@ async function scanJavaDomains(stack, ROOT) {
   const domainMap = {};
   let detectedPattern = null;
 
+  // v2.5.0 — Flat-layout guard for Pattern B/D and the supplementary scan.
+  //
+  // In the standard Spring Initializr layout the layer dirs sit DIRECTLY
+  // under the root package: `com/example/demo/controller/UserController.java`.
+  // The Pattern B glob `**/*/controller/*.java` matched that with `*` =
+  // `demo` (the root package's last segment), so every flat project was
+  // classified as "Pattern B, single domain named after the package" and
+  // Pattern C (domain from class name) was unreachable.
+  //
+  // Two signals must BOTH hold for a `{d}/{layer}/` path to count as flat:
+  //   1. `{d}` is the root package's last segment (the layer dir is a
+  //      direct child of the root package), AND
+  //   2. none of the `*Controller` class stems under `{d}/controller/`
+  //      start with `{d}` — i.e. the classes are named after OTHER things
+  //      (`UserController`, `OrderController` under `demo/`).
+  // Signal 2 keeps single-domain domain-first projects intact: in
+  // `com/example/payment/controller/PaymentController.java` the root
+  // package also ends in `payment`, but the controller stem IS `payment`,
+  // so it stays Pattern B.
+  //
+  // Signal 2 looks at EVERY layer class under the base dir (controller,
+  // service, mapper, repository, dao, dto), not only controllers: a
+  // single-domain project such as `account/{controller/LoginController,
+  // service/AccountService, dto/LoginDto}` is domain-first because
+  // `AccountService` is named after the package, even though no controller is.
+  // A `*Application.java` (Spring Boot main class) sitting DIRECTLY in the base
+  // dir is a positive flat signal on its own — Initializr places it there,
+  // domain-first projects keep it one level above the domain packages.
+  //
+  // Base dirs: the root package, plus — for a file inside a Gradle/Maven
+  // module — `<rootPkg>/<moduleName>` (`api/src/main/java/com/example/api/
+  // controller/`), where the module's own sub-package plays the role of the
+  // Initializr base package and the domains again come from class names.
+  const rootPkgPath = rootPackage ? rootPackage.replace(/\./g, "/") : null;
+  const escRe = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  const flatDirCache = new Map();
+  const LAYER_CLASS_RE = /^(?:controller|service|mapper|repository|dao|dto)\/([A-Za-z0-9]+?)(?:Controller|Service|Mapper|Repository|Dao|Dto)\.java$/;
+  const isFlatBase = (base) => {
+    if (!flatDirCache.has(base)) {
+      const dirRe = new RegExp(`(^|/)src/main/java/${escRe(base)}/`);
+      const under = [];
+      for (const x of javaFiles) {
+        const m = x.match(dirRe);
+        if (m) under.push(x.slice(m.index + m[0].length));
+      }
+      const appInBase = under.some(rel => /^[A-Za-z0-9]*Application\.java$/.test(rel));
+      const stems = under.map(rel => (rel.match(LAYER_CLASS_RE) || [])[1]).filter(Boolean).map(s => s.toLowerCase());
+      const tail = base.split("/").pop().toLowerCase();
+      flatDirCache.set(base, appInBase || (stems.length > 0 && !stems.some(s => s.startsWith(tail))));
+    }
+    return flatDirCache.get(base);
+  };
+  // Directories (relative to src/main/java) holding a Spring Boot main class
+  // (`*Application.java`). The Initializr base package is wherever that class
+  // lives, independent of `rootPackage` (which is capped at 4 segments and
+  // therefore misses `kr/co/<org>/<proj>/<app>` style base packages).
+  const appBases = [...new Set(javaFiles
+    .map(f => (f.match(/src\/main\/java\/(.+)\/[A-Za-z0-9]*Application\.java$/) || [])[1])
+    .filter(Boolean))];
+  const isFlatLayerPath = (f, layerSegment) => {
+    if (!rootPkgPath && appBases.length === 0) return false;
+    const bases = [rootPkgPath, ...appBases].filter(Boolean);
+    const pre = modulePrefixes.find(p => p && f.startsWith(p));
+    if (pre && rootPkgPath) bases.push(`${rootPkgPath}/${pre.replace(/\/$/, "").split("/").pop()}`);
+    for (const base of bases) {
+      const layerRe = new RegExp(`(^|/)src/main/java/${escRe(base)}/${escRe(layerSegment)}/[^/]+\\.java$`);
+      if (layerRe.test(f) && isFlatBase(base)) return true;
+    }
+    return false;
+  };
+
+  // Controllers that Pattern B skipped as "flat" (layer dir directly under the
+  // base package). If another pattern wins (mixed tree: `demo/controller/
+  // HomeController.java` next to `demo/user/controller/UserController.java`),
+  // Pattern C never runs, so these are re-attached below by class name —
+  // a controller must never silently belong to no domain.
+  const flatSkippedControllers = [];
+
   // Pattern A: controller/{domain}/*.java (layer-first — domain under controller)
-  const controllersA = (await glob("src/main/java/**/controller/*/*.java", { cwd: ROOT })).map(norm);
+  const controllersA = (await gj("src/main/java/**/controller/*/*.java"));
   for (const f of controllersA) {
     const m = f.match(/controller\/([^/]+)\//);
     if (m) {
@@ -77,9 +193,10 @@ async function scanJavaDomains(stack, ROOT) {
   // Pattern B/D: {domain}/controller/*.java (domain-first — controller under domain)
   // D extends B: {module}/{domain}/controller/ — auto-upgrade to module/domain on name conflict
   if (!detectedPattern) {
-    const controllersB = (await glob("src/main/java/**/*/controller/*.java", { cwd: ROOT })).map(norm);
+    const controllersB = (await gj("src/main/java/**/*/controller/*.java"));
     const domainPaths = {};
     for (const f of controllersB) {
+      if (isFlatLayerPath(f, "controller")) { flatSkippedControllers.push(f); continue; }
       const m = f.match(/\/([^/]+)\/controller\/[^/]+\.java$/);
       if (m) {
         const d = m[1];
@@ -115,7 +232,7 @@ async function scanJavaDomains(stack, ROOT) {
 
   // Pattern E: DDD/Hexagonal — {domain}/adapter/in/web/*.java or {domain}/adapter/in/rest/*.java
   if (!detectedPattern) {
-    const controllersE = (await glob("src/main/java/**/adapter/in/{web,rest}/*.java", { cwd: ROOT })).map(norm);
+    const controllersE = (await gj("src/main/java/**/adapter/in/{web,rest}/*.java"));
     for (const f of controllersE) {
       const m = f.match(/\/([^/]+)\/adapter\/in\/(web|rest)\/[^/]+\.java$/);
       if (m) {
@@ -129,7 +246,7 @@ async function scanJavaDomains(stack, ROOT) {
 
   // Pattern C: Flat structure — controller/*.java (no domain directory, extract domain from class name)
   if (!detectedPattern) {
-    const controllersC = (await glob("src/main/java/**/controller/*.java", { cwd: ROOT })).map(norm);
+    const controllersC = (await gj("src/main/java/**/controller/*.java"));
     for (const f of controllersC) {
       const m = f.match(/\/([A-Z][a-zA-Z]*)Controller\.java$/);
       if (m) {
@@ -141,16 +258,30 @@ async function scanJavaDomains(stack, ROOT) {
     if (Object.keys(domainMap).length > 0) detectedPattern = "C";
   }
 
+  // Mixed tree: Pattern B/D/E claimed the tree, but flat controllers under the
+  // base package were skipped. Attach each by class name as a Pattern C
+  // domain (`HomeController` → `home`) so it is analyzed and gets rules.
+  if (detectedPattern && detectedPattern !== "C") {
+    for (const f of flatSkippedControllers) {
+      const m = f.match(/\/([A-Z][a-zA-Z]*)Controller\.java$/);
+      if (!m) continue;
+      const d = m[1].toLowerCase();
+      if (!domainMap[d]) domainMap[d] = { controllers: 0, services: 0, mappers: 0, dtos: 0, xmlMappers: 0, pattern: "C" };
+      domainMap[d].controllers++;
+    }
+  }
+
   // ── Supplementary scan: detect domains without controllers (service/dao/aggregator/facade/usecase only) ──
   // Runs for ALL detected patterns (A/B/C/D/E) to catch core-only domains
   {
-    const serviceDirs = (await glob("src/main/java/**/*/service/*.java", { cwd: ROOT })).map(norm);
-    const mapperDirs = (await glob("src/main/java/**/*/{mapper,repository,dao}/*.java", { cwd: ROOT })).map(norm);
-    const orchestrationDirs = (await glob("src/main/java/**/*/{aggregator,facade,usecase,orchestrator}/*.java", { cwd: ROOT })).map(norm);
+    const serviceDirs = (await gj("src/main/java/**/*/service/*.java"));
+    const mapperDirs = (await gj("src/main/java/**/*/{mapper,repository,dao}/*.java"));
+    const orchestrationDirs = (await gj("src/main/java/**/*/{aggregator,facade,usecase,orchestrator}/*.java"));
     const allServiceFiles = [...serviceDirs, ...mapperDirs, ...orchestrationDirs];
     const skipDomains = ["common", "config", "util", "utils", "base", "core", "shared", "global", "framework", "infra", "front", "admin", "back", "internal", "external", "web", "app", "test", "tests", "main", "generated", "build"];
     for (const f of allServiceFiles) {
       const m = f.match(/\/([^/]+)\/(service|mapper|repository|dao|aggregator|facade|usecase|orchestrator)\/[^/]+\.java$/);
+      if (m && isFlatLayerPath(f, m[2])) continue; // flat layout: layer dir directly under root package
       if (m) {
         const d = m[1];
         if (!domainMap[d] && !skipDomains.includes(d) && !/^v\d+$/.test(d)) {
@@ -196,11 +327,11 @@ async function scanJavaDomains(stack, ROOT) {
       ? `src/main/resources/{mapper,mybatis}/**/{${dn}/${capDn}*.xml,${capDn}*.xml}`
       : `src/main/resources/{mapper,mybatis}/**/${dn}/*.xml`;
 
-    const svc = await glob(svcGlob, { cwd: ROOT });
-    const mpr = await glob(mprGlob, { cwd: ROOT });
-    const dto = await glob(dtoGlob, { cwd: ROOT });
-    const xml = await glob(xmlGlob, { cwd: ROOT });
-    const agg = aggGlob ? await glob(aggGlob, { cwd: ROOT }) : [];
+    const svc = await gj(svcGlob);
+    const mpr = await gj(mprGlob);
+    const dto = await gj(dtoGlob);
+    const xml = await gj(xmlGlob);
+    const agg = aggGlob ? await gj(aggGlob) : [];
     domainMap[d].services = svc.length + agg.length;
     domainMap[d].mappers = mpr.length;
     domainMap[d].dtos = dto.length;
@@ -233,7 +364,7 @@ async function scanJavaDomains(stack, ROOT) {
     // domains with healthy direct-layout file counts.
     const standardCount = svc.length + agg.length + mpr.length + dto.length + xml.length;
     if (standardCount === 0 && (p === "B" || p === "D")) {
-      const deepFiles = (await glob(`src/main/java/**/${dn}/**/*.java`, { cwd: ROOT })).map(norm);
+      const deepFiles = (await gj(`src/main/java/**/${dn}/**/*.java`));
       // v2.4.0 — extended layer recognition. Enterprise codebases
       // commonly include implementation/support layers beyond the canonical
       // controller/service/mapper/dto trio. Files in `factory/`, `strategy/`,

package/plan-installer/scanners/scan-kotlin.js

@@ -184,10 +184,12 @@ async function scanKotlinDomains(stack, ROOT) {
     const ktDomains = {};
     const skipNames = ["common", "config", "util", "utils", "base", "shared", "global", "framework", "infra", "main", "generated", "build"];
     const layerKw = ["controller", "service", "repository", "mapper", "dao", "dto", "vo", "entity", "aggregate", "adapter"];
+    const handledByLayerDir = new Set();
     for (const f of ktFiles) {
       const parts = f.replace(/\\/g, "/").split("/");
       for (let i = 0; i < parts.length - 1; i++) {
         if (layerKw.includes(parts[i].toLowerCase())) {
+          handledByLayerDir.add(f);
           // domain/layer/ pattern
           if (i > 0) {
             const d = parts[i - 1].toLowerCase();
@@ -204,10 +206,73 @@ async function scanKotlinDomains(stack, ROOT) {
         }
       }
     }
-    for (const [d, data] of Object.entries(ktDomains)) {
-      if (data.totalFiles > 0) {
-        backendDomains.push({ name: d, type: "backend", ...data, pattern: "kotlin-single" });
+    // v2.5.0 — Package-by-feature without layer sub-directories:
+    //   com/acme/user/UserController.kt, com/acme/user/UserService.kt
+    // (the idiomatic Kotlin/Spring layout — no controller/ or service/ folder).
+    // The loop above needs a layer folder name in the path; before v2.5.0 a
+    // project with none aborted `init` with "invalid totalGroups: 0".
+    // Derive the domain from the directory that directly holds layer-suffixed
+    // classes; if that directory is the root package itself (flat), use the
+    // class-name stem instead (UserController → user).
+    //
+    // Runs for every file the layer-dir loop did NOT handle, so a MIXED layout
+    // (`user/controller/UserController.kt` + `order/OrderController.kt`) keeps
+    // both domains. In that mixed case only feature packages (parent named
+    // after its classes) are accepted; the class-name-stem fallback is reserved
+    // for projects with no layer dirs at all, so a stray `SomeHandler.kt` in
+    // the root package never becomes a domain of an otherwise structured tree.
+    {
+      // The layer-dir loop registers a domain named after the ROOT package
+      // whenever a layer folder (dto/, vo/, entity/…) sits directly under it
+      // (`com/acme/dto/UserDto.kt` → "acme"). That is a flat-root artifact,
+      // not a feature: it must neither switch this fallback into strict mode
+      // nor survive next to real domains.
+      // "Root" here is the longest package prefix shared by ALL .kt files
+      // (`rootPackage` above stops at the first layer dir and may include a
+      // domain segment, so it cannot be used for this). The artifact is the
+      // entry named after that root tail that carries no controllers and no
+      // services — only dto/mapper counts.
+      const pkgDirs = ktFiles.map(f => (f.match(/src\/main\/kotlin\/(.+)\/[^/]+\.kt$/) || [])[1]).filter(Boolean).map(d => d.split("/"));
+      let common = pkgDirs.length ? pkgDirs[0].slice() : [];
+      for (const d of pkgDirs) { let i = 0; while (i < common.length && i < d.length && common[i] === d[i]) i++; common = common.slice(0, i); }
+      const rootTail = common.length ? common[common.length - 1].toLowerCase() : null;
+      const isFlatRootArtifact = (d) => d === rootTail && ktDomains[d] && ktDomains[d].controllers === 0 && ktDomains[d].services === 0;
+      const strict = Object.keys(ktDomains).some(d => !isFlatRootArtifact(d));
+      const suffixRe = /([A-Za-z0-9]+?)(Controller|Service|Repository|Handler|UseCase|Mapper|Dao|Router|Resource)\.kt$/;
+      const bucket = (m) => (m === "Controller" || m === "Router" || m === "Resource") ? "controllers"
+        : (m === "Service" || m === "Handler" || m === "UseCase") ? "services" : "mappers";
+      // Group layer-suffixed classes by the directory that directly holds them.
+      const byParent = {};
+      for (const f of ktFiles) {
+        if (handledByLayerDir.has(f)) continue;
+        const m = f.match(suffixRe);
+        if (!m) continue;
+        const parts = f.split("/");
+        const parent = parts.length >= 2 ? parts[parts.length - 2].toLowerCase() : "";
+        (byParent[parent] = byParent[parent] || []).push({ stem: m[1], kind: m[2] });
+      }
+      const add = (d, kind) => {
+        if (!ktDomains[d]) ktDomains[d] = { controllers: 0, services: 0, mappers: 0, dtos: 0, totalFiles: 0 };
+        ktDomains[d][bucket(kind)]++;
+        ktDomains[d].totalFiles++;
+      };
+      for (const [parent, files] of Object.entries(byParent)) {
+        // A feature package is one whose classes are named after it (user/UserController.kt).
+        // Otherwise the directory is a flat root/app package (app/UserController.kt,
+        // app/OrderController.kt) and each class-name stem is its own domain.
+        const stems = files.map(x => x.stem.toLowerCase());
+        const featurePkg = parent.length > 1 && !skipNames.includes(parent) && !layerKw.includes(parent)
+          && parent !== "kotlin" && parent !== "app" && stems.some(st => st.startsWith(parent.replace(/-/g, "")));
+        if (strict && !featurePkg) continue;
+        for (const x of files) {
+          const d = featurePkg ? parent : x.stem.replace(/([a-z0-9])([A-Z])/g, "$1-$2").toLowerCase();
+          if (d.length > 1 && !skipNames.includes(d)) add(d, x.kind);
+        }
       }
+      if (rootTail && isFlatRootArtifact(rootTail) && Object.keys(ktDomains).length > 1) delete ktDomains[rootTail];
+    }
+    for (const [d, data] of Object.entries(ktDomains)) {
+      if (data.totalFiles > 0) backendDomains.push({ name: d, type: "backend", ...data, pattern: "kotlin-single" });
     }
   }
 

package/plan-installer/scanners/scan-node.js

@@ -8,6 +8,24 @@
 const path = require("path");
 const { glob } = require("glob");
 
+// v2.5.0 — Layer-first stem de-duplication (shared shape with scan-python.js).
+// For every plural key whose singular form is ALSO a key, fold the plural
+// into the singular via `merge(into, from)` and drop the plural. Handles
+// `-ies`→`-y`, `-(s|x|z|ch|sh)es`→base, and plain `-s`. No merge happens
+// when only one form exists — the scanner never invents a singular.
+function mergePluralStems(byDomain, merge) {
+  for (const name of Object.keys(byDomain)) {
+    const cands = [];
+    if (/ies$/.test(name)) cands.push(name.slice(0, -3) + "y");
+    if (/(?:s|x|z|ch|sh)es$/.test(name)) cands.push(name.slice(0, -2));
+    if (/[^s]s$/.test(name)) cands.push(name.slice(0, -1));
+    const singular = cands.find(c => c !== name && byDomain[c]);
+    if (!singular) continue;
+    merge(byDomain[singular], byDomain[name]);
+    delete byDomain[name];
+  }
+}
+
 async function scanNodeDomains(stack, ROOT) {
   const backendDomains = [];
   const skipDirs = ["common", "shared", "config", "utils", "lib", "core", "main", "interfaces", "types", "constants", "guards", "decorators", "pipes", "filters", "interceptors"];
@@ -27,7 +45,104 @@ async function scanNodeDomains(stack, ROOT) {
     }
   }
 
+  // v2.5.0 — Layer-first layouts (Express / Fastify / Koa): src/controllers/,
+  // src/routes/, src/services/, src/models/. Every folder is a LAYER, so the
+  // loop below used to emit "controllers", "services", "routes" as domains.
+  // When (almost) every candidate folder is a layer name, derive domains from
+  // the file stems inside those layers instead: user.controller.js,
+  // users.routes.ts, orderService.js → user, users, order.
+  const LAYER_DIRS = new Set(["controllers", "controller", "routes", "route", "routers", "router", "services", "service",
+    "models", "model", "repositories", "repository", "middlewares", "middleware", "handlers", "handler",
+    "validators", "validations", "schemas", "dtos", "entities", "dao", "helpers", "api"]);
+  // Infrastructure folders that are neither layers nor features.
+  const NODE_GENERIC_DIRS = new Set(["db", "database", "migrations", "seeds", "scripts", "public", "static", "views", "templates",
+    "assets", "test", "tests", "__tests__", "mocks", "__mocks__", "docs", "node_modules", "dist", "build"]);
+  const candidateNames = srcDirs.map(d => path.basename(d.replace(/\/$/, ""))).filter(n => !skipDirs.includes(n) && !NODE_GENERIC_DIRS.has(n));
+  const layerNames = candidateNames.filter(n => LAYER_DIRS.has(n));
+  // A tree is layer-first only when a ROUTING layer folder exists at the
+  // top (`controllers/`, `routes/`, `handlers/`, `api/`). Data-only layer
+  // folders (`entities/`, `dtos/`, `schemas/`, `models/`) also appear in
+  // module-first NestJS trees (`src/users/`, `src/orders/` + shared
+  // `src/entities/`), where the modules are the domains — treating that as
+  // layer-first would rename `users` to `user` and invent one-file domains.
+  const ROUTING_LAYERS = new Set(["controllers", "controller", "routes", "route", "routers", "router", "handlers", "handler", "api"]);
+  const hasRoutingLayer = layerNames.some(n => ROUTING_LAYERS.has(n));
+  // Then: at least two layer folders (or the only candidate is a layer).
+  // Remaining non-layer siblings (`src/jobs/`, `src/billing/`) are MIXED-
+  // layout feature folders and become whole-folder domains — they must not
+  // disable the layer-first path, which would resurrect `controllers` /
+  // `routes` / `services` as domains.
+  if (hasRoutingLayer && (layerNames.length >= 2 || (layerNames.length === 1 && candidateNames.length === 1))) {
+    const byDomain = {};
+    const featureNames = candidateNames.filter(n => !LAYER_DIRS.has(n));
+    for (const dir of srcDirs) {
+      const name = path.basename(dir.replace(/\/$/, ""));
+      if (!featureNames.includes(name)) continue;
+      const files = await glob(`${dir.replace(/\\/g, "/").replace(/\/?$/, "/")}**/*.{ts,js,mjs,cjs}`, { cwd: ROOT, ignore: ["**/*.spec.*", "**/*.test.*", "**/*.d.ts", "**/node_modules/**"] });
+      if (files.length === 0) continue;
+      const e = (byDomain[name] = byDomain[name] || { name, type: "backend", controllers: 0, services: 0, dtos: 0, totalFiles: 0 });
+      for (const f of files) {
+        if (/controller|router|route|handler/.test(f)) e.controllers++;
+        if (/service/.test(f)) e.services++;
+        if (/dto|schema|type|validator/.test(f)) e.dtos++;
+        e.totalFiles++;
+      }
+    }
+    // Layer/role suffixes are stripped REPEATEDLY (`email.service.impl.ts` →
+    // `email`, not `emailimpl`); `impl`, `base`, `abstract`, `interface`,
+    // `types`, `spec` are role words, not domains.
+    // A suffix counts only after a separator (`user.controller`, `user-controller`)
+    // or as a PascalCase word (`userController`, `UserService`) — never as a bare
+    // substring, so `prototype` is not cut down to `proto`.
+    const DOTTED_SUFFIX_RE = /[.\-_](?:controller|router|routes?|service|handler|model|repository|repo|middleware|validator|schema|dto|entity|dao|helper|impl|base|abstract|interface|types?|spec|mock|factory|utils?)s?$/i;
+    const CAMEL_SUFFIX_RE = /(?<=[a-z0-9])(?:Controller|Router|Routes?|Service|Handler|Model|Repository|Repo|Middleware|Validator|Schema|Dto|DTO|Entity|Dao|DAO|Helper|Impl|Base|Abstract|Interface|Types?|Spec|Mock|Factory|Utils?)s?$/;
+    const stemOf = (f) => {
+      const base = path.basename(f).replace(/\.(ts|js|mjs|cjs)$/, "");
+      // user.controller | user-controller | userController | users.routes | UserService | index
+      let stem = base;
+      for (let i = 0; i < 6; i++) {
+        const next = stem.replace(DOTTED_SUFFIX_RE, "").replace(CAMEL_SUFFIX_RE, "");
+        if (next === stem) break;
+        stem = next;
+      }
+      stem = stem.replace(/([a-z0-9])([A-Z])/g, "$1-$2").toLowerCase().replace(/^[.\-_]+|[.\-_]+$/g, "");
+      return stem && stem !== "index" && stem !== "app" && stem !== "main" ? stem : null;
+    };
+    // Role comes from the LAYER FOLDER (authoritative), never from substrings
+    // of the file path (`models/prototype.ts` is not a dto because it contains
+    // "type").
+    const ROLE_OF_LAYER = (layer) => ROUTING_LAYERS.has(layer) ? "controllers"
+      : /^services?$/.test(layer) ? "services"
+      : /^(dtos?|schemas?|validators?|validations|entities)$/.test(layer) ? "dtos" : null;
+    for (const dir of srcDirs) {
+      const layer = path.basename(dir.replace(/\/$/, ""));
+      if (!LAYER_DIRS.has(layer)) continue;
+      const role = ROLE_OF_LAYER(layer);
+      const files = await glob(`${dir.replace(/\\/g, "/").replace(/\/?$/, "/")}**/*.{ts,js,mjs,cjs}`, { cwd: ROOT, ignore: ["**/*.spec.*", "**/*.test.*", "**/*.d.ts"] });
+      for (const f of files) {
+        const d = stemOf(f);
+        if (!d) continue;
+        const e = (byDomain[d] = byDomain[d] || { name: d, type: "backend", controllers: 0, services: 0, dtos: 0, totalFiles: 0 });
+        if (role) e[role]++;
+        e.totalFiles++;
+      }
+    }
+    // Merge a plural stem into its singular twin when BOTH exist
+    // (`users.routes.js` + `user.controller.js` → `user`). Only pairs are
+    // merged — a lone `orders` stays `orders`, so no guessed singularization.
+    mergePluralStems(byDomain, (into, from) => {
+      into.controllers += from.controllers; into.services += from.services;
+      into.dtos += from.dtos; into.totalFiles += from.totalFiles;
+    });
+    for (const d of Object.values(byDomain)) backendDomains.push({ ...d, pattern: "layer-first" });
+    if (backendDomains.length > 0) return { backendDomains };
+    // fall through to the directory loop if stems yielded nothing
+  }
+
   for (let dir of srcDirs) {
+    // A folder named after a layer (`entities/`, `dtos/`, `controllers/`) is
+    // never a feature domain, whichever layout won above.
+    if (LAYER_DIRS.has(path.basename(dir.replace(/\/$/, "")))) continue;
     if (!dir.endsWith("/")) dir += "/";
     const name = path.basename(dir.replace(/\/$/, ""));
     if (skipDirs.includes(name)) continue;

package/plan-installer/scanners/scan-python.js

@@ -7,6 +7,22 @@
 const path = require("path");
 const { glob } = require("glob");
 
+// v2.5.0 — Layer-first stem de-duplication (same rule as scan-node.js).
+// Fold a plural key into its singular twin ONLY when both exist
+// (`routers/users.py` + `models/user.py` → `user`); a lone plural is kept.
+function mergePluralStems(byDomain, merge) {
+  for (const name of Object.keys(byDomain)) {
+    const cands = [];
+    if (/ies$/.test(name)) cands.push(name.slice(0, -3) + "y");
+    if (/(?:s|x|z|ch|sh)es$/.test(name)) cands.push(name.slice(0, -2));
+    if (/[^s]s$/.test(name)) cands.push(name.slice(0, -1));
+    const singular = cands.find(c => c !== name && byDomain[c]);
+    if (!singular) continue;
+    merge(byDomain[singular], byDomain[name]);
+    delete byDomain[name];
+  }
+}
+
 async function scanPythonDomains(stack, ROOT) {
   const backendDomains = [];
 
@@ -46,6 +62,46 @@ async function scanPythonDomains(stack, ROOT) {
       const appFiles = await glob(`${dir.replace(/\\/g, "/")}/*.py`, { cwd: ROOT });
       backendDomains.push({ name, type: "backend", totalFiles: appFiles.length });
     }
+    // v2.5.0 — Layer-first FastAPI/Flask: app/routers/users.py, app/models/user.py,
+    // app/schemas/user.py. Folders are layers, so derive domains from file stems.
+    if (backendDomains.filter(d => d.type === "backend").length === 0) {
+      const PY_LAYER_DIRS = new Set(["routers", "router", "routes", "route", "api", "endpoints", "views", "controllers",
+        "services", "service", "models", "model", "schemas", "schema", "repositories", "repository", "crud", "dao", "handlers"]);
+      const PY_GENERIC_DIRS = new Set(["core", "common", "utils", "__pycache__", "config", "db", "database", "tests", "test", "app", "static", "templates", "migrations",
+        "env", "venv", ".venv", "virtualenv", "node_modules", "site-packages", "scripts", "docs"]);
+      const allSub = (await glob("{app,src/app,src}/*/", { cwd: ROOT, ignore: ["**/venv/**", "**/.venv/**", "**/env/**", "**/virtualenv/**", "**/node_modules/**", "**/site-packages/**", "**/__pycache__/**"] }))
+        .map(d => d.replace(/\\/g, "/").replace(/\/?$/, "/"));
+      const baseOf = (d) => path.basename(d.replace(/\/$/, ""));
+      const parentOf = (d) => d.replace(/\/$/, "").split("/").slice(0, -1).join("/") + "/";
+      const layerDirs = allSub.filter(d => PY_LAYER_DIRS.has(baseOf(d)));
+      // Feature packages that sit NEXT TO the layer folders (same parent):
+      // `src/routers/` + `src/tasks/` is a mixed layout — `tasks` must become a
+      // domain too, not be silently dropped. Scanned symmetrically with the
+      // layer folders (both come from the same glob), never from other trees.
+      const layerParents = new Set(layerDirs.map(parentOf));
+      const featureDirs = allSub.filter(d => layerParents.has(parentOf(d)) && !PY_LAYER_DIRS.has(baseOf(d)) && !PY_GENERIC_DIRS.has(baseOf(d)));
+      if (layerDirs.length > 0) {
+        const byDomain = {};
+        for (const dir of layerDirs) {
+          const files = await glob(`${dir}*.py`, { cwd: ROOT });
+          for (const f of files) {
+            let stem = path.basename(f, ".py").replace(/_(router|routes?|service|model|schema|repository|crud|handler|views?|api)s?$/i, "").toLowerCase();
+            if (!stem || ["__init__", "base", "deps", "dependencies", "main", "app", "utils", "common"].includes(stem)) continue;
+            const e = (byDomain[stem] = byDomain[stem] || { name: stem, type: "backend", totalFiles: 0 });
+            e.totalFiles++;
+          }
+        }
+        for (const dir of featureDirs) {
+          const files = await glob(`${dir}**/*.py`, { cwd: ROOT, ignore: ["**/__pycache__/**"] });
+          if (files.length === 0) continue;
+          const name = baseOf(dir).toLowerCase();
+          const e = (byDomain[name] = byDomain[name] || { name, type: "backend", totalFiles: 0 });
+          e.totalFiles += files.length;
+        }
+        mergePluralStems(byDomain, (into, from) => { into.totalFiles += from.totalFiles; });
+        for (const d of Object.values(byDomain)) backendDomains.push({ ...d, pattern: "layer-first" });
+      }
+    }
     if (backendDomains.filter(d => d.type === "backend").length === 0) {
       const appDirs = await glob("{app,src/app}/*/", { cwd: ROOT });
       for (let dir of appDirs) {