codemodctl 0.1.13 → 0.1.15

package/dist/cli.js

@@ -1,15 +1,17 @@
 #!/usr/bin/env node
-import "./consistent-sharding-CcnfsY_k.js";
-import { analyzeCodeowners } from "./codeowner-analysis-C8hyzL4c.js";
+import "./codemod-cli-DailrcEf.js";
+import { analyzeCodeowners } from "./codeowner-analysis-BcFoet6s.js";
+import "./consistent-sharding-lYO6XLIO.js";
+import { analyzeDirectories } from "./directory-analysis-6DFgAaDz.js";
 import { defineCommand, runMain } from "citty";
 import crypto from "node:crypto";
 import { $ } from "execa";
 import { writeFile } from "node:fs/promises";
 
-//#region src/commands/pr/create.ts
-const createCommand = defineCommand({
+//#region src/commands/git/create-pr.ts
+const createPrCommand = defineCommand({
 	meta: {
-		name: "create",
+		name: "create-pr",
 		description: "Create a pull request"
 	},
 	args: {
@@ -156,17 +158,30 @@ const createCommand = defineCommand({
 });
 
 //#endregion
-//#region src/commands/pr/index.ts
-const prCommand = defineCommand({
+//#region src/commands/git/index.ts
+const gitCommand = defineCommand({
 	meta: {
-		name: "pr",
-		description: "Pull request operations"
+		name: "git",
+		description: "Git operations"
 	},
-	subCommands: { create: createCommand }
+	subCommands: { createPr: createPrCommand }
 });
 
 //#endregion
 //#region src/commands/shard/codeowner.ts
+/**
+* Codeowner-based sharding command
+*
+* Creates shards by grouping files by their CODEOWNERS team assignments.
+* Uses simple file distribution within each team group, maintaining
+* consistency with existing state when available.
+*
+* Example usage:
+* npx codemodctl shard codeowner -l tsx -c ./codemod.ts -s 30 --stateProp shards --codeowners .github/CODEOWNERS
+*
+* This will analyze all applicable files, group them by CODEOWNERS team assignments, and create
+* shards with approximately 30 files each within each team.
+*/
 const codeownerCommand = defineCommand({
 	meta: {
 		name: "codeowner",
@@ -217,12 +232,22 @@ const codeownerCommand = defineCommand({
 		}
 		try {
 			console.log(`State property: ${stateProp}`);
+			const existingStateJson = process.env.CODEMOD_STATE;
+			let existingState;
+			if (existingStateJson) try {
+				existingState = JSON.parse(existingStateJson)[stateProp];
+				console.log(`Found existing state with ${existingState.length} shards`);
+			} catch (parseError) {
+				console.warn(`Warning: Failed to parse existing state: ${parseError}`);
+				existingState = void 0;
+			}
 			const analysisOptions = {
 				shardSize,
 				codeownersPath,
 				rulePath: codemodFilePath,
 				projectRoot: process.cwd(),
-				language
+				language,
+				existingState
 			};
 			const result = await analyzeCodeowners(analysisOptions);
 			const stateOutput = `${stateProp}=${JSON.stringify(result.shards)}\n`;
@@ -238,6 +263,103 @@ const codeownerCommand = defineCommand({
 	}
 });
 
+//#endregion
+//#region src/commands/shard/directory.ts
+/**
+* Directory-based sharding command
+*
+* Creates shards by grouping files within subdirectories of a target directory.
+* Uses consistent hashing to distribute files within each directory group, maintaining
+* consistency with existing state when available.
+*
+* Example usage:
+* npx codemodctl shard directory -l tsx -c ./codemod.ts -s 30 --stateProp shards --target packages/
+*
+* This will analyze all applicable files within subdirectories of 'packages/' and create
+* shards with approximately 30 files each, grouped by directory.
+*/
+const directoryCommand = defineCommand({
+	meta: {
+		name: "directory",
+		description: "Create directory-based sharding output"
+	},
+	args: {
+		shardSize: {
+			type: "string",
+			alias: "s",
+			description: "Number of files per shard",
+			required: true
+		},
+		stateProp: {
+			type: "string",
+			alias: "p",
+			description: "Property name for state output",
+			required: true
+		},
+		target: {
+			type: "string",
+			description: "Target directory to shard by subdirectories",
+			required: true
+		},
+		codemodFile: {
+			type: "string",
+			alias: "c",
+			description: "Path to codemod file",
+			required: true
+		},
+		language: {
+			type: "string",
+			alias: "l",
+			description: "Language of the codemod",
+			required: true
+		}
+	},
+	async run({ args }) {
+		const { shardSize: shardSizeStr, stateProp, target, codemodFile: codemodFilePath, language } = args;
+		const shardSize = parseInt(shardSizeStr, 10);
+		if (isNaN(shardSize) || shardSize <= 0) {
+			console.error("Error: shard-size must be a positive number");
+			process.exit(1);
+		}
+		const stateOutputsPath = process.env.STATE_OUTPUTS;
+		if (!stateOutputsPath) {
+			console.error("Error: STATE_OUTPUTS environment variable is required");
+			process.exit(1);
+		}
+		try {
+			console.log(`State property: ${stateProp}`);
+			console.log(`Target directory: ${target}`);
+			const existingStateJson = process.env.CODEMOD_STATE;
+			let existingState;
+			if (existingStateJson) try {
+				existingState = JSON.parse(existingStateJson)[stateProp];
+				console.log(`Found existing state with ${existingState.length} shards`);
+			} catch (parseError) {
+				console.warn(`Warning: Failed to parse existing state: ${parseError}`);
+				existingState = void 0;
+			}
+			const analysisOptions = {
+				shardSize,
+				target,
+				rulePath: codemodFilePath,
+				projectRoot: process.cwd(),
+				language,
+				existingState
+			};
+			const result = await analyzeDirectories(analysisOptions);
+			const stateOutput = `${stateProp}=${JSON.stringify(result.shards)}\n`;
+			console.log(`Writing state output to: ${stateOutputsPath}`);
+			await writeFile(stateOutputsPath, stateOutput, { flag: "a" });
+			console.log("✅ Directory-based sharding completed successfully!");
+			console.log("Generated shards:", JSON.stringify(result.shards, null, 2));
+		} catch (error) {
+			console.error("❌ Failed to process directory sharding:");
+			console.error(error instanceof Error ? error.message : String(error));
+			process.exit(1);
+		}
+	}
+});
+
 //#endregion
 //#region src/commands/shard/index.ts
 const shardCommand = defineCommand({
@@ -245,7 +367,10 @@ const shardCommand = defineCommand({
 		name: "shard",
 		description: "Sharding operations for distributing work"
 	},
-	subCommands: { codeowner: codeownerCommand }
+	subCommands: {
+		codeowner: codeownerCommand,
+		directory: directoryCommand
+	}
 });
 
 //#endregion
@@ -257,7 +382,7 @@ const main = defineCommand({
 		description: "CLI tool for workflow engine operations"
 	},
 	subCommands: {
-		pr: prCommand,
+		git: gitCommand,
 		shard: shardCommand
 	}
 });

package/dist/codemod-cli-DailrcEf.js

@@ -0,0 +1,26 @@
+#!/usr/bin/env node
+import { execSync } from "node:child_process";
+
+//#region src/utils/codemod-cli.ts
+/**
+* Executes the codemod CLI command and returns applicable file paths
+*/
+async function getApplicableFiles(rulePath, language, projectRoot) {
+	try {
+		const command = `npx -y codemod@latest jssg list-applicable --language ${language} --target ${projectRoot} ${rulePath}`;
+		console.debug(`Executing: ${command}`);
+		const applicableFiles = execSync(command, {
+			encoding: "utf8",
+			cwd: projectRoot,
+			maxBuffer: 10 * 1024 * 1024
+		}).split("\n").filter((line) => line.startsWith("[Applicable] ")).map((line) => line.replace("[Applicable] ", "").trim()).filter((filePath) => filePath.length > 0);
+		console.debug(`Found ${applicableFiles.length} applicable files`);
+		return applicableFiles;
+	} catch (error) {
+		console.error("Error executing codemod CLI:", error);
+		throw new Error(`Failed to execute codemod CLI: ${error}`);
+	}
+}
+
+//#endregion
+export { getApplicableFiles };

package/dist/{codeowner-analysis-C8hyzL4c.js → codeowner-analysis-BcFoet6s.js}

@@ -1,6 +1,5 @@
 #!/usr/bin/env node
-import { calculateOptimalShardCount } from "./consistent-sharding-CcnfsY_k.js";
-import { execSync } from "node:child_process";
+import { getApplicableFiles } from "./codemod-cli-DailrcEf.js";
 import { existsSync } from "node:fs";
 import path, { resolve } from "node:path";
 import Codeowners from "codeowners";
@@ -32,25 +31,6 @@ function normalizeOwnerName(owner) {
 	return owner.replace("@", "").toLowerCase();
 }
 /**
-* Executes the codemod CLI command and returns applicable file paths
-*/
-async function getApplicableFiles(rulePath, language, projectRoot) {
-	try {
-		const command = `npx -y codemod@latest jssg list-applicable --language ${language} --target ${projectRoot} ${rulePath}`;
-		console.debug(`Executing: ${command}`);
-		const applicableFiles = execSync(command, {
-			encoding: "utf8",
-			cwd: projectRoot,
-			maxBuffer: 10 * 1024 * 1024
-		}).split("\n").filter((line) => line.startsWith("[Applicable] ")).map((line) => line.replace("[Applicable] ", "").trim()).filter((filePath) => filePath.length > 0);
-		console.debug(`Found ${applicableFiles.length} applicable files`);
-		return applicableFiles;
-	} catch (error) {
-		console.error("Error executing codemod CLI:", error);
-		throw new Error(`Failed to execute codemod CLI: ${error}`);
-	}
-}
-/**
 * Analyzes files and groups them by codeowner team
 */
 async function analyzeFilesByOwner(codeownersPath, language, rulePath, projectRoot = process.cwd()) {
@@ -84,19 +64,48 @@ async function analyzeFilesWithoutOwner(language, rulePath, projectRoot = proces
 	return filesByOwner;
 }
 /**
-* Generates shard configuration from team file analysis
+* Calculate optimal number of shards based on target shard size
+*
+* @param totalFiles - Total number of files
+* @param targetShardSize - Desired number of files per shard
+* @returns Number of shards needed
 */
-function generateShards(filesByOwner, shardSize) {
+function calculateOptimalShardCount(totalFiles, targetShardSize) {
+	return Math.ceil(totalFiles / targetShardSize);
+}
+/**
+* Generates shard configuration from team file analysis with actual file distribution.
+* Maintains consistency with existing state when provided.
+*
+* @param filesByOwner - Map of team names to their file arrays
+* @param shardSize - Target number of files per shard
+* @param existingState - Optional existing state for consistency
+* @returns Array of team-based shards with file assignments
+*/
+function generateShards(filesByOwner, shardSize, existingState) {
 	const allShards = [];
+	const existingByTeam = /* @__PURE__ */ new Map();
+	if (existingState) for (const shard of existingState) {
+		if (!existingByTeam.has(shard.team)) existingByTeam.set(shard.team, []);
+		existingByTeam.get(shard.team).push(shard);
+	}
 	for (const [team, files] of filesByOwner.entries()) {
 		const fileCount = files.length;
-		const numShards = calculateOptimalShardCount(fileCount, shardSize);
-		console.log(`Team "${team}" owns ${fileCount} files, creating ${numShards} shards`);
-		for (let i = 1; i <= numShards; i++) allShards.push({
-			team,
-			shard: `${i}/${numShards}`,
-			shardId: `${team} ${i}/${numShards}`
-		});
+		const optimalShardCount = calculateOptimalShardCount(fileCount, shardSize);
+		const existingShardCount = (existingByTeam.get(team) || []).length;
+		const numShards = existingShardCount > 0 ? existingShardCount : optimalShardCount;
+		console.log(`Team "${team}" owns ${fileCount} files, ${existingShardCount > 0 ? `maintaining ${numShards} existing shards` : `creating ${numShards} new shards`}`);
+		const sortedFiles = [...files].sort();
+		for (let i = 1; i <= numShards; i++) {
+			const shardFiles = [];
+			for (let fileIndex = i - 1; fileIndex < sortedFiles.length; fileIndex += numShards) shardFiles.push(sortedFiles[fileIndex] ?? "");
+			allShards.push({
+				team,
+				shard: `${i}/${numShards}`,
+				shardId: `${team} ${i}/${numShards}`,
+				files: shardFiles
+			});
+		}
 	}
 	return allShards;
 }
@@ -111,10 +120,14 @@ function getTeamFileInfo(filesByOwner) {
 	}));
 }
 /**
-* Main function to analyze codeowners and generate shard configuration
+* Main function to analyze codeowners and generate shard configuration.
+* Maintains consistency with existing state when provided.
+*
+* @param options - Configuration options for codeowner analysis
+* @returns Promise resolving to codeowner analysis result
 */
 async function analyzeCodeowners(options) {
-	const { shardSize, codeownersPath, rulePath, language, projectRoot = process.cwd() } = options;
+	const { shardSize, codeownersPath, rulePath, language, projectRoot = process.cwd(), existingState } = options;
 	const resolvedCodeownersPath = await findCodeownersFile(projectRoot, codeownersPath);
 	let filesByOwner;
 	console.debug(`Using rule file: ${rulePath}`);
@@ -129,8 +142,9 @@ async function analyzeCodeowners(options) {
 		filesByOwner = await analyzeFilesWithoutOwner(language, rulePath, projectRoot);
 	}
 	console.log("File analysis completed. Generating shards...");
+	if (existingState) console.debug(`Using existing state with ${existingState.length} shards`);
 	const teams = getTeamFileInfo(filesByOwner);
-	const shards = generateShards(filesByOwner, shardSize);
+	const shards = generateShards(filesByOwner, shardSize, existingState);
 	const totalFiles = Array.from(filesByOwner.values()).reduce((sum, files) => sum + files.length, 0);
 	console.log(`Generated ${shards.length} total shards for ${totalFiles} files`);
 	return {
@@ -141,4 +155,4 @@ async function analyzeCodeowners(options) {
 }
 
 //#endregion
-export { analyzeCodeowners, analyzeFilesByOwner, analyzeFilesWithoutOwner, findCodeownersFile, generateShards, getApplicableFiles, getTeamFileInfo, normalizeOwnerName };
+export { analyzeCodeowners, analyzeFilesByOwner, analyzeFilesWithoutOwner, findCodeownersFile, generateShards, getTeamFileInfo, normalizeOwnerName };

package/dist/{codeowner-analysis-D1oVulJ6.d.ts → codeowner-analysis-CkGR1oU6.d.ts}

@@ -1,24 +1,54 @@
 //#region src/utils/codeowner-analysis.d.ts
+/**
+ * Result for a single team-based shard
+ */
 interface ShardResult {
+  /** The team that owns these files */
   team: string;
+  /** The shard identifier string (e.g., "1/3") */
   shard: string;
+  /** The combined shard ID (e.g., "team-name 1/3") */
   shardId: string;
+  /** Array of file paths in this shard */
+  files: string[];
 }
+/**
+ * Information about a team and their files
+ */
 interface TeamFileInfo {
+  /** Team name */
   team: string;
+  /** Number of files owned by this team */
   fileCount: number;
+  /** Array of file paths owned by this team */
   files: string[];
 }
+/**
+ * Options for codeowner-based analysis
+ */
 interface CodeownerAnalysisOptions {
+  /** Target number of files per shard */
   shardSize: number;
+  /** Optional path to CODEOWNERS file */
   codeownersPath?: string;
+  /** Path to the codemod rule file */
   rulePath: string;
+  /** Programming language for the codemod */
   language: string;
+  /** Project root directory (defaults to process.cwd()) */
   projectRoot?: string;
+  /** Existing state for consistency (optional) */
+  existingState?: ShardResult[];
 }
+/**
+ * Result of codeowner-based analysis
+ */
 interface CodeownerAnalysisResult {
+  /** Array of team information */
   teams: TeamFileInfo[];
+  /** Array of team-based shards with file assignments */
   shards: ShardResult[];
+  /** Total number of files processed */
   totalFiles: number;
 }
 /**
@@ -31,10 +61,6 @@ declare function findCodeownersFile(projectRoot?: string, explicitPath?: string)
  * Normalizes owner name by removing @ prefix and converting to lowercase
  */
 declare function normalizeOwnerName(owner: string): string;
-/**
- * Executes the codemod CLI command and returns applicable file paths
- */
-declare function getApplicableFiles(rulePath: string, language: string, projectRoot: string): Promise<string[]>;
 /**
  * Analyzes files and groups them by codeowner team
  */
@@ -44,16 +70,26 @@ declare function analyzeFilesByOwner(codeownersPath: string, language: string, r
  */
 declare function analyzeFilesWithoutOwner(language: string, rulePath: string, projectRoot?: string): Promise<Map<string, string[]>>;
 /**
- * Generates shard configuration from team file analysis
+ * Generates shard configuration from team file analysis with actual file distribution.
+ * Maintains consistency with existing state when provided.
+ *
+ * @param filesByOwner - Map of team names to their file arrays
+ * @param shardSize - Target number of files per shard
+ * @param existingState - Optional existing state for consistency
+ * @returns Array of team-based shards with file assignments
  */
-declare function generateShards(filesByOwner: Map<string, string[]>, shardSize: number): ShardResult[];
+declare function generateShards(filesByOwner: Map<string, string[]>, shardSize: number, existingState?: ShardResult[]): ShardResult[];
 /**
  * Converts file ownership map to team info array
  */
 declare function getTeamFileInfo(filesByOwner: Map<string, string[]>): TeamFileInfo[];
 /**
- * Main function to analyze codeowners and generate shard configuration
+ * Main function to analyze codeowners and generate shard configuration.
+ * Maintains consistency with existing state when provided.
+ *
+ * @param options - Configuration options for codeowner analysis
+ * @returns Promise resolving to codeowner analysis result
  */
 declare function analyzeCodeowners(options: CodeownerAnalysisOptions): Promise<CodeownerAnalysisResult>;
 //#endregion
-export { CodeownerAnalysisOptions, CodeownerAnalysisResult, ShardResult, TeamFileInfo, analyzeCodeowners, analyzeFilesByOwner, analyzeFilesWithoutOwner, findCodeownersFile, generateShards, getApplicableFiles, getTeamFileInfo, normalizeOwnerName };
+export { CodeownerAnalysisOptions, CodeownerAnalysisResult, ShardResult, TeamFileInfo, analyzeCodeowners, analyzeFilesByOwner, analyzeFilesWithoutOwner, findCodeownersFile, generateShards, getTeamFileInfo, normalizeOwnerName };

package/dist/codeowners.d.ts

@@ -1,2 +1,2 @@
-import { CodeownerAnalysisOptions, CodeownerAnalysisResult, ShardResult, TeamFileInfo, analyzeCodeowners, analyzeFilesByOwner, analyzeFilesWithoutOwner, findCodeownersFile, generateShards, getApplicableFiles, getTeamFileInfo, normalizeOwnerName } from "./codeowner-analysis-D1oVulJ6.js";
-export { CodeownerAnalysisOptions, CodeownerAnalysisResult, ShardResult, TeamFileInfo, analyzeCodeowners, analyzeFilesByOwner, analyzeFilesWithoutOwner, findCodeownersFile, generateShards, getApplicableFiles, getTeamFileInfo, normalizeOwnerName };
+import { CodeownerAnalysisOptions, CodeownerAnalysisResult, ShardResult, TeamFileInfo, analyzeCodeowners, analyzeFilesByOwner, analyzeFilesWithoutOwner, findCodeownersFile, generateShards, getTeamFileInfo, normalizeOwnerName } from "./codeowner-analysis-CkGR1oU6.js";
+export { CodeownerAnalysisOptions, CodeownerAnalysisResult, ShardResult, TeamFileInfo, analyzeCodeowners, analyzeFilesByOwner, analyzeFilesWithoutOwner, findCodeownersFile, generateShards, getTeamFileInfo, normalizeOwnerName };

package/dist/codeowners.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import "./consistent-sharding-CcnfsY_k.js";
-import { analyzeCodeowners, analyzeFilesByOwner, analyzeFilesWithoutOwner, findCodeownersFile, generateShards, getApplicableFiles, getTeamFileInfo, normalizeOwnerName } from "./codeowner-analysis-C8hyzL4c.js";
+import "./codemod-cli-DailrcEf.js";
+import { analyzeCodeowners, analyzeFilesByOwner, analyzeFilesWithoutOwner, findCodeownersFile, generateShards, getTeamFileInfo, normalizeOwnerName } from "./codeowner-analysis-BcFoet6s.js";
 
-export { analyzeCodeowners, analyzeFilesByOwner, analyzeFilesWithoutOwner, findCodeownersFile, generateShards, getApplicableFiles, getTeamFileInfo, normalizeOwnerName };
+export { analyzeCodeowners, analyzeFilesByOwner, analyzeFilesWithoutOwner, findCodeownersFile, generateShards, getTeamFileInfo, normalizeOwnerName };

package/dist/{consistent-sharding-D9n1M6by.d.ts → consistent-sharding-B-Si8jYX.d.ts}

@@ -23,19 +23,14 @@ declare function getShardForFilename(filename: string, {
   shardCount: number;
 }): number;
 /**
- * Checks if a file belongs to a specific shard
+ * Checks if a file belongs to a specific shard by simply checking if it's in the shard's files list
  *
  * @param filename - The file path to check
- * @param shardCount - Total number of shards
- * @param shardIndex - The shard index to check against (0-based)
- * @returns True if file belongs to the specified shard
+ * @param shard - Shard object containing files array
+ * @returns True if file is in the shard's files list
  */
-declare function fitsInShard(filename: string, {
-  shardCount,
-  shardIndex
-}: {
-  shardCount: number;
-  shardIndex: number;
+declare function fitsInShard(filename: string, shard: {
+  files: string[];
 }): boolean;
 /**
  * Distributes files across shards using deterministic hashing

package/dist/{consistent-sharding-CcnfsY_k.js → consistent-sharding-lYO6XLIO.js}

@@ -46,15 +46,14 @@ function getShardForFilename(filename, { shardCount }) {
 	return shardInfo[0].index;
 }
 /**
-* Checks if a file belongs to a specific shard
+* Checks if a file belongs to a specific shard by simply checking if it's in the shard's files list
 *
 * @param filename - The file path to check
-* @param shardCount - Total number of shards
-* @param shardIndex - The shard index to check against (0-based)
-* @returns True if file belongs to the specified shard
+* @param shard - Shard object containing files array
+* @returns True if file is in the shard's files list
 */
-function fitsInShard(filename, { shardCount, shardIndex }) {
-	return getShardForFilename(filename, { shardCount }) === shardIndex;
+function fitsInShard(filename, shard) {
+	return shard.files.includes(filename);
 }
 /**
 * Distributes files across shards using deterministic hashing

package/dist/directory-analysis-6DFgAaDz.js

@@ -0,0 +1,97 @@
+#!/usr/bin/env node
+import { getApplicableFiles } from "./codemod-cli-DailrcEf.js";
+import { calculateOptimalShardCount, distributeFilesAcrossShards } from "./consistent-sharding-lYO6XLIO.js";
+import path from "node:path";
+
+//#region src/utils/directory-analysis.ts
+/**
+* Groups files by their immediate subdirectory within the target directory
+*
+* @param files - Array of file paths to group
+* @param target - Target directory to analyze subdirectories within
+* @returns Map of subdirectory paths to their file lists
+*/
+function groupFilesByDirectory(files, target) {
+	const normalizedTarget = path.normalize(target);
+	const filesByDirectory = /* @__PURE__ */ new Map();
+	for (const filePath of files) {
+		const normalizedFile = path.normalize(filePath);
+		if (!normalizedFile.startsWith(normalizedTarget)) continue;
+		const relativePath = path.relative(normalizedTarget, normalizedFile);
+		if (!relativePath.includes(path.sep)) continue;
+		const firstDir = relativePath.split(path.sep)[0];
+		if (!firstDir) continue;
+		const subdirectory = path.join(normalizedTarget, firstDir);
+		if (!filesByDirectory.has(subdirectory)) filesByDirectory.set(subdirectory, []);
+		filesByDirectory.get(subdirectory).push(normalizedFile);
+	}
+	return filesByDirectory;
+}
+/**
+* Creates directory-based shards using consistent hashing within each directory group.
+* Maintains consistency with existing state when provided.
+*
+* @param filesByDirectory - Map of directory paths to their file lists
+* @param shardSize - Target number of files per shard
+* @param existingState - Optional existing state for consistency
+* @returns Array of directory-based shards
+*/
+function createDirectoryShards(filesByDirectory, shardSize, existingState) {
+	const allShards = [];
+	const existingByDirectory = /* @__PURE__ */ new Map();
+	if (existingState) for (const shard of existingState) {
+		if (!existingByDirectory.has(shard.directory)) existingByDirectory.set(shard.directory, []);
+		existingByDirectory.get(shard.directory).push(shard);
+	}
+	for (const [directory, files] of filesByDirectory.entries()) {
+		const fileCount = files.length;
+		const optimalShardCount = calculateOptimalShardCount(fileCount, shardSize);
+		const existingShards = existingByDirectory.get(directory) || [];
+		const existingShardCount = existingShards.length > 0 ? existingShards[0]?.shardCount ?? 0 : 0;
+		const shardCount = existingShardCount > 0 ? existingShardCount : optimalShardCount;
+		console.log(`Directory "${directory}" contains ${fileCount} files, ${existingShardCount > 0 ? `maintaining ${shardCount} existing shards` : `creating ${shardCount} new shards`}`);
+		const shardMap = distributeFilesAcrossShards(files, shardCount);
+		for (let shardIndex = 0; shardIndex < shardCount; shardIndex++) {
+			const shardFiles = shardMap.get(shardIndex) || [];
+			allShards.push({
+				directory,
+				shard: shardIndex + 1,
+				shardCount,
+				files: shardFiles.sort()
+			});
+		}
+	}
+	return allShards;
+}
+/**
+* Main function to analyze directories and generate shard configuration.
+* Maintains consistency with existing state when provided.
+*
+* @param options - Configuration options for directory analysis
+* @returns Promise resolving to directory analysis result
+* @throws Error if no files found in target subdirectories
+*/
+async function analyzeDirectories(options) {
+	const { shardSize, target, rulePath, language, projectRoot = process.cwd(), existingState } = options;
+	console.debug(`Using rule file: ${rulePath}`);
+	console.debug(`Target directory: ${target}`);
+	console.debug(`Shard size: ${shardSize}`);
+	if (existingState) console.debug(`Using existing state with ${existingState.length} shards`);
+	console.log("Analyzing files with CLI command...");
+	const applicableFiles = await getApplicableFiles(rulePath, language, projectRoot);
+	console.log("Grouping files by directory...");
+	const filesByDirectory = groupFilesByDirectory(applicableFiles, target);
+	if (filesByDirectory.size === 0) throw new Error(`No files found in subdirectories of target: ${target}`);
+	console.log(`Found ${filesByDirectory.size} subdirectories in target`);
+	console.log("Generating directory-based shards...");
+	const shards = createDirectoryShards(filesByDirectory, shardSize, existingState);
+	const totalFiles = Array.from(filesByDirectory.values()).reduce((sum, files) => sum + files.length, 0);
+	console.log(`Generated ${shards.length} total shards for ${totalFiles} files across ${filesByDirectory.size} directories`);
+	return {
+		shards,
+		totalFiles
+	};
+}
+
+//#endregion
+export { analyzeDirectories, createDirectoryShards, groupFilesByDirectory };

package/dist/directory.d.ts

@@ -0,0 +1,69 @@
+//#region src/utils/directory-analysis.d.ts
+/**
+ * Result for a single directory-based shard
+ */
+interface DirectoryShardResult {
+  /** The directory path this shard belongs to */
+  directory: string;
+  /** The shard number (1-based) within this directory */
+  shard: number;
+  /** Total number of shards for this directory */
+  shardCount: number;
+  /** Array of file paths in this shard */
+  files: string[];
+}
+/**
+ * Options for directory-based analysis
+ */
+interface DirectoryAnalysisOptions {
+  /** Target number of files per shard */
+  shardSize: number;
+  /** Target directory to analyze subdirectories within */
+  target: string;
+  /** Path to the codemod rule file */
+  rulePath: string;
+  /** Programming language for the codemod */
+  language: string;
+  /** Project root directory (defaults to process.cwd()) */
+  projectRoot?: string;
+  /** Existing state for consistency (optional) */
+  existingState?: DirectoryShardResult[];
+}
+/**
+ * Result of directory-based analysis
+ */
+interface DirectoryAnalysisResult {
+  /** Array of directory-based shards */
+  shards: DirectoryShardResult[];
+  /** Total number of files processed */
+  totalFiles: number;
+}
+/**
+ * Groups files by their immediate subdirectory within the target directory
+ *
+ * @param files - Array of file paths to group
+ * @param target - Target directory to analyze subdirectories within
+ * @returns Map of subdirectory paths to their file lists
+ */
+declare function groupFilesByDirectory(files: string[], target: string): Map<string, string[]>;
+/**
+ * Creates directory-based shards using consistent hashing within each directory group.
+ * Maintains consistency with existing state when provided.
+ *
+ * @param filesByDirectory - Map of directory paths to their file lists
+ * @param shardSize - Target number of files per shard
+ * @param existingState - Optional existing state for consistency
+ * @returns Array of directory-based shards
+ */
+declare function createDirectoryShards(filesByDirectory: Map<string, string[]>, shardSize: number, existingState?: DirectoryShardResult[]): DirectoryShardResult[];
+/**
+ * Main function to analyze directories and generate shard configuration.
+ * Maintains consistency with existing state when provided.
+ *
+ * @param options - Configuration options for directory analysis
+ * @returns Promise resolving to directory analysis result
+ * @throws Error if no files found in target subdirectories
+ */
+declare function analyzeDirectories(options: DirectoryAnalysisOptions): Promise<DirectoryAnalysisResult>;
+//#endregion
+export { DirectoryAnalysisOptions, DirectoryAnalysisResult, DirectoryShardResult, analyzeDirectories, createDirectoryShards, groupFilesByDirectory };

package/dist/directory.js

@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+import "./codemod-cli-DailrcEf.js";
+import "./consistent-sharding-lYO6XLIO.js";
+import { analyzeDirectories, createDirectoryShards, groupFilesByDirectory } from "./directory-analysis-6DFgAaDz.js";
+
+export { analyzeDirectories, createDirectoryShards, groupFilesByDirectory };

package/dist/index.d.ts

@@ -1,3 +1,3 @@
-import { analyzeShardScaling, calculateOptimalShardCount, distributeFilesAcrossShards, fitsInShard, getFileHashPosition, getNumericFileNameSha1, getShardForFilename } from "./consistent-sharding-D9n1M6by.js";
-import { CodeownerAnalysisOptions, CodeownerAnalysisResult, ShardResult, TeamFileInfo, analyzeCodeowners, analyzeFilesByOwner, analyzeFilesWithoutOwner, findCodeownersFile, generateShards, getApplicableFiles, getTeamFileInfo, normalizeOwnerName } from "./codeowner-analysis-D1oVulJ6.js";
-export { CodeownerAnalysisOptions, CodeownerAnalysisResult, ShardResult, TeamFileInfo, analyzeCodeowners, analyzeFilesByOwner, analyzeFilesWithoutOwner, analyzeShardScaling, calculateOptimalShardCount, distributeFilesAcrossShards, findCodeownersFile, fitsInShard, generateShards, getApplicableFiles, getFileHashPosition, getNumericFileNameSha1, getShardForFilename, getTeamFileInfo, normalizeOwnerName };
+import { analyzeShardScaling, calculateOptimalShardCount, distributeFilesAcrossShards, fitsInShard, getFileHashPosition, getNumericFileNameSha1, getShardForFilename } from "./consistent-sharding-B-Si8jYX.js";
+import { CodeownerAnalysisOptions, CodeownerAnalysisResult, ShardResult, TeamFileInfo, analyzeCodeowners, analyzeFilesByOwner, analyzeFilesWithoutOwner, findCodeownersFile, generateShards, getTeamFileInfo, normalizeOwnerName } from "./codeowner-analysis-CkGR1oU6.js";
+export { CodeownerAnalysisOptions, CodeownerAnalysisResult, ShardResult, TeamFileInfo, analyzeCodeowners, analyzeFilesByOwner, analyzeFilesWithoutOwner, analyzeShardScaling, calculateOptimalShardCount, distributeFilesAcrossShards, findCodeownersFile, fitsInShard, generateShards, getFileHashPosition, getNumericFileNameSha1, getShardForFilename, getTeamFileInfo, normalizeOwnerName };

package/dist/index.js

@@ -1,5 +1,6 @@
 #!/usr/bin/env node
-import { analyzeShardScaling, calculateOptimalShardCount, distributeFilesAcrossShards, fitsInShard, getFileHashPosition, getNumericFileNameSha1, getShardForFilename } from "./consistent-sharding-CcnfsY_k.js";
-import { analyzeCodeowners, analyzeFilesByOwner, analyzeFilesWithoutOwner, findCodeownersFile, generateShards, getApplicableFiles, getTeamFileInfo, normalizeOwnerName } from "./codeowner-analysis-C8hyzL4c.js";
+import "./codemod-cli-DailrcEf.js";
+import { analyzeCodeowners, analyzeFilesByOwner, analyzeFilesWithoutOwner, findCodeownersFile, generateShards, getTeamFileInfo, normalizeOwnerName } from "./codeowner-analysis-BcFoet6s.js";
+import { analyzeShardScaling, calculateOptimalShardCount, distributeFilesAcrossShards, fitsInShard, getFileHashPosition, getNumericFileNameSha1, getShardForFilename } from "./consistent-sharding-lYO6XLIO.js";
 
-export { analyzeCodeowners, analyzeFilesByOwner, analyzeFilesWithoutOwner, analyzeShardScaling, calculateOptimalShardCount, distributeFilesAcrossShards, findCodeownersFile, fitsInShard, generateShards, getApplicableFiles, getFileHashPosition, getNumericFileNameSha1, getShardForFilename, getTeamFileInfo, normalizeOwnerName };
+export { analyzeCodeowners, analyzeFilesByOwner, analyzeFilesWithoutOwner, analyzeShardScaling, calculateOptimalShardCount, distributeFilesAcrossShards, findCodeownersFile, fitsInShard, generateShards, getFileHashPosition, getNumericFileNameSha1, getShardForFilename, getTeamFileInfo, normalizeOwnerName };

package/dist/sharding.d.ts

@@ -1,2 +1,2 @@
-import { analyzeShardScaling, calculateOptimalShardCount, distributeFilesAcrossShards, fitsInShard, getFileHashPosition, getNumericFileNameSha1, getShardForFilename } from "./consistent-sharding-D9n1M6by.js";
+import { analyzeShardScaling, calculateOptimalShardCount, distributeFilesAcrossShards, fitsInShard, getFileHashPosition, getNumericFileNameSha1, getShardForFilename } from "./consistent-sharding-B-Si8jYX.js";
 export { analyzeShardScaling, calculateOptimalShardCount, distributeFilesAcrossShards, fitsInShard, getFileHashPosition, getNumericFileNameSha1, getShardForFilename };

package/dist/sharding.js

@@ -1,4 +1,4 @@
 #!/usr/bin/env node
-import { analyzeShardScaling, calculateOptimalShardCount, distributeFilesAcrossShards, fitsInShard, getFileHashPosition, getNumericFileNameSha1, getShardForFilename } from "./consistent-sharding-CcnfsY_k.js";
+import { analyzeShardScaling, calculateOptimalShardCount, distributeFilesAcrossShards, fitsInShard, getFileHashPosition, getNumericFileNameSha1, getShardForFilename } from "./consistent-sharding-lYO6XLIO.js";
 
 export { analyzeShardScaling, calculateOptimalShardCount, distributeFilesAcrossShards, fitsInShard, getFileHashPosition, getNumericFileNameSha1, getShardForFilename };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "codemodctl",
-  "version": "0.1.13",
+  "version": "0.1.15",
   "description": "CLI tool and utilities for workflow engine operations, file sharding, and codeowner analysis",
   "type": "module",
   "exports": {