feat(mapper): split repeated flat file families

Author: steipete

CHANGELOG.md

@@ -19,6 +19,7 @@
 - Added generic package-less monorepo app-root mapping for Node/Next projects under roots such as `apps/*` and `packages/*` when positive source or framework signals are present.
 - Added Maven project mapping for root, nested, and multi-module Java/Kotlin projects with Spring role slices, Maven validation defaults, and `pom.xml` detection, thanks @julianshess.
 - Added a release-prep checklist for auditing changelog, package metadata, and dry-run package contents without publishing.
+- Improved bounded source grouping so large flat directories split repeated filename families like command, plugin, doctor, and runtime files into more coherent review slices.
 - Improved OpenCode malformed JSON diagnostics with output length, event kinds, and a bounded preview, thanks @rohitjavvadi.
 - Fixed Express route mapping for aliased Router imports that follow block comment banners, thanks @rohitjavvadi.
 - Fixed Laravel route mapping to include array-style `Route::group` prefixes, thanks @rohitjavvadi.

README.md

@@ -58,7 +58,8 @@ validation commands and records a patch attempt under `.clawpatch/`.
 - generic extension/plugin packages under workspace roots such as `extensions/*`
   and `plugins/*`, including package metadata, source, docs, and nearby tests
 - semantic Node source groups for large packages, including runtime, commands,
-  auth, storage, monitor, webhook, setup, server, and client slices
+  auth, storage, monitor, webhook, setup, server, client, and repeated filename
+  family slices
 - Nx project metadata from `project.json`, including project-scoped validation
   targets
 - Turborepo task metadata for workspace-aware validation commands and feature

docs/feature-mapping.md

@@ -37,7 +37,8 @@ Supported deterministic mappers today:
 - Nx project metadata from `project.json`, including project names, source roots, project types, and target names
 - Turborepo `turbo.json` metadata for workspace-aware validation commands and feature context
 - bounded Node/TypeScript source groups under `src/`, `lib/`, `app/`,
-  `pages/`, `scripts/`, `server/`, and `api/`
+  `pages/`, `scripts/`, `server/`, and `api/`, with oversized flat
+  directories split by repeated filename families
 - React Router `<Route path element>` declarations and React components in
   root or nested frontend packages such as `frontend/`, `client/`, `web/`,
   workspaces, and packages under `apps/` or `packages/`

src/mappers/grouping.test.ts

@@ -0,0 +1,47 @@
+import { describe, expect, it } from "vitest";
+import { partitionFileGroups } from "./grouping.js";
+
+describe("partitionFileGroups", () => {
+  it("splits repeated direct file families before numeric chunks", () => {
+    const groups = partitionFileGroups(
+      "src",
+      [
+        "src/cli/command-alpha.ts",
+        "src/cli/command-beta.ts",
+        "src/cli/config-alpha.ts",
+        "src/cli/config-beta.ts",
+        "src/cli/other-a.ts",
+        "src/cli/other-b.ts",
+        "src/cli/solo.ts",
+      ],
+      3,
+    );
+
+    expect(groups).toContainEqual({
+      label: "src/cli/:command",
+      files: ["src/cli/command-alpha.ts", "src/cli/command-beta.ts"],
+    });
+    expect(groups).toContainEqual({
+      label: "src/cli/:config",
+      files: ["src/cli/config-alpha.ts", "src/cli/config-beta.ts"],
+    });
+    expect(groups).toContainEqual({
+      label: "src/cli/:other",
+      files: ["src/cli/other-a.ts", "src/cli/other-b.ts"],
+    });
+    expect(groups).toContainEqual({ label: "src/cli", files: ["src/cli/solo.ts"] });
+  });
+
+  it("keeps singleton families in the fallback chunk", () => {
+    const groups = partitionFileGroups(
+      "src",
+      ["src/commands.ts", "src/config.ts", "src/index.ts", "src/runtime.ts", "src/session.ts"],
+      3,
+    );
+
+    expect(groups).toEqual([
+      { label: "src#1", files: ["src/commands.ts", "src/config.ts", "src/index.ts"] },
+      { label: "src#2", files: ["src/runtime.ts", "src/session.ts"] },
+    ]);
+  });
+});

src/mappers/grouping.ts

@@ -44,10 +44,22 @@ function partitionAt(
   }
 
   if (buckets.size === 0) {
-    return chunkFiles(labelFor(sourceRoot, files, depth), files, maxFiles);
+    return partitionDirectFiles(
+      sourceRoot,
+      files,
+      maxFiles,
+      depth,
+      labelFor(sourceRoot, files, depth),
+    );
   }
 
-  const groups = chunkFiles(labelFor(sourceRoot, files, depth), directFiles, maxFiles);
+  const groups = partitionDirectFiles(
+    sourceRoot,
+    directFiles,
+    maxFiles,
+    depth,
+    labelFor(sourceRoot, files, depth),
+  );
   for (const [segment, bucketFiles] of [...buckets.entries()].toSorted(([left], [right]) =>
     left.localeCompare(right),
   )) {
@@ -80,6 +92,86 @@ function chunkFiles(label: string, files: string[], maxFiles: number): FileGroup
   return groups;
 }
 
+function partitionDirectFiles(
+  sourceRoot: string,
+  files: string[],
+  maxFiles: number,
+  depth: number,
+  label: string,
+): FileGroup[] {
+  if (files.length === 0) {
+    return [];
+  }
+  if (files.length <= maxFiles) {
+    return [{ label, files }];
+  }
+
+  const buckets = new Map<string, string[]>();
+  const fallbackFiles: string[] = [];
+  for (const file of files) {
+    const family = directFileFamily(sourceRoot, file, depth);
+    if (family === null) {
+      fallbackFiles.push(file);
+      continue;
+    }
+    const bucket = buckets.get(family) ?? [];
+    bucket.push(file);
+    buckets.set(family, bucket);
+  }
+
+  const groups: FileGroup[] = [];
+  for (const [family, bucketFiles] of [...buckets.entries()].toSorted(([left], [right]) =>
+    left.localeCompare(right),
+  )) {
+    if (bucketFiles.length < 2) {
+      fallbackFiles.push(...bucketFiles);
+      continue;
+    }
+    groups.push(...chunkFiles(`${label}/:${family}`, bucketFiles.toSorted(), maxFiles));
+  }
+  groups.push(...chunkFiles(label, fallbackFiles.toSorted(), maxFiles));
+  return groups;
+}
+
+function directFileFamily(sourceRoot: string, file: string, depth: number): string | null {
+  const relativePath = file.startsWith(`${sourceRoot}/`) ? file.slice(sourceRoot.length + 1) : file;
+  const leaf = relativePath.split("/")[depth];
+  if (leaf === undefined) {
+    return null;
+  }
+  const stem = leaf
+    .replace(/\.[cm]?tsx?$/u, "")
+    .replace(/\.[cm]?jsx?$/u, "")
+    .replace(/\.[^.]+$/u, "")
+    .toLowerCase();
+  const dotIndex = stem.indexOf(".");
+  const prefix = dotIndex < 0 ? stem : stem.slice(0, dotIndex);
+  const family = dotIndex < 0 ? (prefix.split(/[-_]/u)[0] ?? null) : prefix;
+  if (family === null || !isUsefulFamily(family)) {
+    return null;
+  }
+  return family;
+}
+
+const unhelpfulFamilies = new Set([
+  "index",
+  "main",
+  "shared",
+  "helper",
+  "helpers",
+  "util",
+  "utils",
+  "type",
+  "types",
+  "spec",
+  "test",
+  "tests",
+]);
+
+function isUsefulFamily(family: string): boolean {
+  return family.length >= 3 && !/^\d+$/u.test(family) && !unhelpfulFamilies.has(family);
+}
+
 function labelFor(sourceRoot: string, files: string[], depth: number): string {
   if (depth === 0) {
     return sourceRoot;