codemodctl 0.1.12 → 0.1.14

package/README.md

@@ -38,9 +38,14 @@ const belongsToShard = fitsInShard('src/components/Button.tsx', {
   shardIndex: 2 
 });
 
-// Distribute all files across shards
+// Distribute all files across shards with consistent hashing
 const files = ['file1.ts', 'file2.ts', 'file3.ts'];
 const distribution = distributeFilesAcrossShards(files, 5);
+
+// Check scaling behavior - minimal reassignment when growing
+const scalingAnalysis = analyzeShardScaling(files, 5, 6);
+console.log(`${scalingAnalysis.stableFiles} files stay in same shard`);
+console.log(`${scalingAnalysis.reassignmentPercentage}% reassignment`); // Much less than 100%
 ```
 
 #### Codeowner Analysis
@@ -73,13 +78,14 @@ const analysis = await codemodctl.codeowners.analyzeCodeowners(options);
 
 ## Key Features
 
-### Deterministic File Sharding
+### Consistent File Sharding
 
-The sharding algorithm uses deterministic hashing to ensure:
+The sharding algorithm uses **consistent hashing** to ensure:
 
 - **Perfect consistency**: Same file + same shard count = same result, always
 - **No external dependencies**: Result depends only on filename and shard count  
-- **Even distribution**: SHA1 hashing provides good distribution across shards
+- **Minimal reassignment**: When scaling up, only ~20-40% of files move (not 100%)
+- **Stable scaling**: Adding new shards doesn't reorganize existing file assignments
 - **Simple API**: No complex parameters or configuration needed
 - **Team-aware sharding**: Works with codeowner boundaries
 
@@ -99,9 +105,12 @@ The sharding algorithm uses deterministic hashing to ensure:
 - `distributeFilesAcrossShards(files, shardCount)` - Distribute files across shards
 - `calculateOptimalShardCount(totalFiles, targetShardSize)` - Calculate optimal shard count
 - `getFileHashPosition(filename)` - Get consistent hash position for a file
+- `analyzeShardScaling(files, oldCount, newCount)` - Analyze reassignment when scaling
 
 All functions are deterministic: same input always produces the same output.
 
+**Scaling behavior**: When going from N to N+1 shards, typically only 20-40% of files get reassigned to new locations, making it ideal for incremental scaling scenarios.
+
 ### Codeowner Functions
 
 - `analyzeCodeowners(options)` - Complete analysis with shard generation
@@ -125,20 +134,27 @@ const shard1 = getShardForFilename('src/components/Button.tsx', { shardCount: 5
 const shard2 = getShardForFilename('src/components/Button.tsx', { shardCount: 5 });
 console.log(shard1 === shard2); // always true
 
-// Different shard counts may give different results (that's expected)
+// Different shard counts give different results (expected behavior)
 const shard5 = getShardForFilename('src/components/Button.tsx', { shardCount: 5 });
 const shard10 = getShardForFilename('src/components/Button.tsx', { shardCount: 10 });
-// shard5 and shard10 may be different, but each is consistent
+// shard5 and shard10 will likely be different, but each is consistent
 
-// Distribute files deterministically  
+// Distribute files with consistent hashing for stable scaling
 const files = ['file1.ts', 'file2.ts', 'file3.ts'];
 const distribution = distributeFilesAcrossShards(files, 5);
+
+// When you need more capacity, most files stay in place
+const moreFiles = [...files, 'newFile.ts'];
+const analysis = analyzeShardScaling(files, 5, 6);
+// Only ~20-40% of files get reassigned, not all of them!
 ```
 
 ### Key Benefits
 - **No complex parameters**: Just filename and shard count
 - **Perfectly deterministic**: Same input = same output, always
-- **Fast and simple**: Pure hash-based assignment
+- **Stable scaling**: When adding shards, most files stay in their original shards
+- **Minimal reassignment**: Only ~20-40% of files move when scaling up
+- **Fast and simple**: Hash-based assignment with consistent ring placement
 - **Works across runs**: File gets same shard whether filesystem changes or not
 
 ## CLI Commands

package/dist/cli.js

@@ -1,15 +1,16 @@
 #!/usr/bin/env node
-import "./consistent-sharding-DDU9PV2R.js";
-import { analyzeCodeowners } from "./codeowner-analysis-n5QdN_A3.js";
+import { analyzeCodeowners, getApplicableFiles } from "./codeowner-analysis-pG3p0RPU.js";
+import { calculateOptimalShardCount, distributeFilesAcrossShards } from "./consistent-sharding-pjG1rI6w.js";
 import { defineCommand, runMain } from "citty";
 import crypto from "node:crypto";
 import { $ } from "execa";
 import { writeFile } from "node:fs/promises";
+import path from "node:path";
 
-//#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 +157,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 +231,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 +262,194 @@ const codeownerCommand = defineCommand({
 	}
 });
 
+//#endregion
+//#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
+//#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 +457,10 @@ const shardCommand = defineCommand({
 		name: "shard",
 		description: "Sharding operations for distributing work"
 	},
-	subCommands: { codeowner: codeownerCommand }
+	subCommands: {
+		codeowner: codeownerCommand,
+		directory: directoryCommand
+	}
 });
 
 //#endregion
@@ -257,7 +472,7 @@ const main = defineCommand({
 		description: "CLI tool for workflow engine operations"
 	},
 	subCommands: {
-		pr: prCommand,
+		git: gitCommand,
 		shard: shardCommand
 	}
 });

package/dist/{codeowner-analysis-D1oVulJ6.d.ts → codeowner-analysis-B7Jrhm9T.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/{codeowner-analysis-n5QdN_A3.js → codeowner-analysis-pG3p0RPU.js}

@@ -1,10 +1,31 @@
 #!/usr/bin/env node
-import { calculateOptimalShardCount } from "./consistent-sharding-DDU9PV2R.js";
-import { execSync } from "node:child_process";
 import { existsSync } from "node:fs";
 import path, { resolve } from "node:path";
 import Codeowners from "codeowners";
+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
 //#region src/utils/codeowner-analysis.ts
 /**
 * Finds and resolves the CODEOWNERS file path
@@ -32,25 +53,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 +86,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 +142,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 +164,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 {

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-B7Jrhm9T.js";
+export { CodeownerAnalysisOptions, CodeownerAnalysisResult, ShardResult, TeamFileInfo, analyzeCodeowners, analyzeFilesByOwner, analyzeFilesWithoutOwner, findCodeownersFile, generateShards, getTeamFileInfo, normalizeOwnerName };

package/dist/codeowners.js

@@ -1,5 +1,4 @@
 #!/usr/bin/env node
-import "./consistent-sharding-DDU9PV2R.js";
-import { analyzeCodeowners, analyzeFilesByOwner, analyzeFilesWithoutOwner, findCodeownersFile, generateShards, getApplicableFiles, getTeamFileInfo, normalizeOwnerName } from "./codeowner-analysis-n5QdN_A3.js";
+import { analyzeCodeowners, analyzeFilesByOwner, analyzeFilesWithoutOwner, findCodeownersFile, generateShards, getTeamFileInfo, normalizeOwnerName } from "./codeowner-analysis-pG3p0RPU.js";
 
-export { analyzeCodeowners, analyzeFilesByOwner, analyzeFilesWithoutOwner, findCodeownersFile, generateShards, getApplicableFiles, getTeamFileInfo, normalizeOwnerName };
+export { analyzeCodeowners, analyzeFilesByOwner, analyzeFilesWithoutOwner, findCodeownersFile, generateShards, getTeamFileInfo, normalizeOwnerName };

package/dist/{consistent-sharding-D0wYSQBl.d.ts → consistent-sharding-CwWnbSoW.d.ts}

@@ -1,6 +1,7 @@
 //#region src/utils/consistent-sharding.d.ts
 /**
  * Generates a numeric hash from a filename using SHA1
+ * Uses only the first 8 characters of the hex digest to avoid JavaScript number precision issues
  */
 declare function getNumericFileNameSha1(filename: string): number;
 /**
@@ -9,8 +10,8 @@ declare function getNumericFileNameSha1(filename: string): number;
  */
 declare function getFileHashPosition(filename: string): number;
 /**
- * Gets the shard index for a filename using deterministic hashing
- * Files get assigned to a consistent preferred shard regardless of total count
+ * Gets the shard index for a filename using consistent hashing
+ * Files are assigned to the next shard clockwise on the hash ring
  *
  * @param filename - The file path to hash
  * @param shardCount - Total number of shards
@@ -22,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
@@ -52,5 +48,20 @@ declare function distributeFilesAcrossShards(filenames: string[], shardCount: nu
  * @returns Number of shards needed
  */
 declare function calculateOptimalShardCount(totalFiles: number, targetShardSize: number): number;
+/**
+ * Analyzes file reassignment when scaling from oldShardCount to newShardCount
+ * Returns statistics about how many files would need to be reassigned
+ *
+ * @param filenames - Array of file paths to analyze
+ * @param oldShardCount - Current number of shards
+ * @param newShardCount - Target number of shards
+ * @returns Object with reassignment statistics
+ */
+declare function analyzeShardScaling(filenames: string[], oldShardCount: number, newShardCount: number): {
+  totalFiles: number;
+  reassignedFiles: number;
+  reassignmentPercentage: number;
+  stableFiles: number;
+};
 //#endregion
-export { calculateOptimalShardCount, distributeFilesAcrossShards, fitsInShard, getFileHashPosition, getNumericFileNameSha1, getShardForFilename };
+export { analyzeShardScaling, calculateOptimalShardCount, distributeFilesAcrossShards, fitsInShard, getFileHashPosition, getNumericFileNameSha1, getShardForFilename };

package/dist/consistent-sharding-pjG1rI6w.js

@@ -0,0 +1,112 @@
+#!/usr/bin/env node
+import crypto from "node:crypto";
+
+//#region src/utils/consistent-sharding.ts
+const HASH_RING_SIZE = 1e6;
+/**
+* Generates a numeric hash from a filename using SHA1
+* Uses only the first 8 characters of the hex digest to avoid JavaScript number precision issues
+*/
+function getNumericFileNameSha1(filename) {
+	const hex = crypto.createHash("sha1").update(filename).digest("hex").substring(0, 8);
+	return parseInt(hex, 16);
+}
+/**
+* Maps a filename to a consistent position on the hash ring (0 to HASH_RING_SIZE-1)
+* This position remains constant regardless of shard count changes
+*/
+function getFileHashPosition(filename) {
+	return getNumericFileNameSha1(filename) % HASH_RING_SIZE;
+}
+/**
+* Get the position for a specific shard index on the hash ring
+* Shards get fixed positions that don't change when other shards are added
+*/
+function getShardPosition(shardIndex) {
+	return parseInt(crypto.createHash("sha1").update(`shard-${shardIndex}`).digest("hex").substring(0, 8), 16) % HASH_RING_SIZE;
+}
+/**
+* Gets the shard index for a filename using consistent hashing
+* Files are assigned to the next shard clockwise on the hash ring
+*
+* @param filename - The file path to hash
+* @param shardCount - Total number of shards
+* @returns Shard index (0-based)
+*/
+function getShardForFilename(filename, { shardCount }) {
+	if (shardCount <= 0) throw new Error("Shard count must be greater than 0");
+	const filePosition = getFileHashPosition(filename);
+	const shardInfo = [];
+	for (let i = 0; i < shardCount; i++) shardInfo.push({
+		index: i,
+		position: getShardPosition(i)
+	});
+	shardInfo.sort((a, b) => a.position - b.position);
+	for (const shard of shardInfo) if (filePosition <= shard.position) return shard.index;
+	return shardInfo[0].index;
+}
+/**
+* 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 shard - Shard object containing files array
+* @returns True if file is in the shard's files list
+*/
+function fitsInShard(filename, shard) {
+	return shard.files.includes(filename);
+}
+/**
+* Distributes files across shards using deterministic hashing
+*
+* @param filenames - Array of file paths
+* @param shardCount - Total number of shards
+* @returns Map of shard index to array of filenames
+*/
+function distributeFilesAcrossShards(filenames, shardCount) {
+	if (shardCount <= 0) throw new Error("Shard count must be greater than 0");
+	const shardMap = /* @__PURE__ */ new Map();
+	for (let i = 0; i < shardCount; i++) shardMap.set(i, []);
+	for (const filename of filenames) {
+		const shardIndex = getShardForFilename(filename, { shardCount });
+		shardMap.get(shardIndex).push(filename);
+	}
+	return shardMap;
+}
+/**
+* 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 calculateOptimalShardCount(totalFiles, targetShardSize) {
+	return Math.ceil(totalFiles / targetShardSize);
+}
+/**
+* Analyzes file reassignment when scaling from oldShardCount to newShardCount
+* Returns statistics about how many files would need to be reassigned
+*
+* @param filenames - Array of file paths to analyze
+* @param oldShardCount - Current number of shards
+* @param newShardCount - Target number of shards
+* @returns Object with reassignment statistics
+*/
+function analyzeShardScaling(filenames, oldShardCount, newShardCount) {
+	let reassignedFiles = 0;
+	for (const filename of filenames) {
+		const oldShard = getShardForFilename(filename, { shardCount: oldShardCount });
+		const newShard = getShardForFilename(filename, { shardCount: newShardCount });
+		if (oldShard !== newShard) reassignedFiles++;
+	}
+	const stableFiles = filenames.length - reassignedFiles;
+	const reassignmentPercentage = filenames.length > 0 ? reassignedFiles / filenames.length * 100 : 0;
+	return {
+		totalFiles: filenames.length,
+		reassignedFiles,
+		reassignmentPercentage,
+		stableFiles
+	};
+}
+
+//#endregion
+export { analyzeShardScaling, calculateOptimalShardCount, distributeFilesAcrossShards, fitsInShard, getFileHashPosition, getNumericFileNameSha1, getShardForFilename };

package/dist/index.d.ts

@@ -1,3 +1,3 @@
-import { calculateOptimalShardCount, distributeFilesAcrossShards, fitsInShard, getFileHashPosition, getNumericFileNameSha1, getShardForFilename } from "./consistent-sharding-D0wYSQBl.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, calculateOptimalShardCount, distributeFilesAcrossShards, findCodeownersFile, fitsInShard, generateShards, getApplicableFiles, getFileHashPosition, getNumericFileNameSha1, getShardForFilename, getTeamFileInfo, normalizeOwnerName };
+import { analyzeShardScaling, calculateOptimalShardCount, distributeFilesAcrossShards, fitsInShard, getFileHashPosition, getNumericFileNameSha1, getShardForFilename } from "./consistent-sharding-CwWnbSoW.js";
+import { CodeownerAnalysisOptions, CodeownerAnalysisResult, ShardResult, TeamFileInfo, analyzeCodeowners, analyzeFilesByOwner, analyzeFilesWithoutOwner, findCodeownersFile, generateShards, getTeamFileInfo, normalizeOwnerName } from "./codeowner-analysis-B7Jrhm9T.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,5 @@
 #!/usr/bin/env node
-import { calculateOptimalShardCount, distributeFilesAcrossShards, fitsInShard, getFileHashPosition, getNumericFileNameSha1, getShardForFilename } from "./consistent-sharding-DDU9PV2R.js";
-import { analyzeCodeowners, analyzeFilesByOwner, analyzeFilesWithoutOwner, findCodeownersFile, generateShards, getApplicableFiles, getTeamFileInfo, normalizeOwnerName } from "./codeowner-analysis-n5QdN_A3.js";
+import { analyzeCodeowners, analyzeFilesByOwner, analyzeFilesWithoutOwner, findCodeownersFile, generateShards, getTeamFileInfo, normalizeOwnerName } from "./codeowner-analysis-pG3p0RPU.js";
+import { analyzeShardScaling, calculateOptimalShardCount, distributeFilesAcrossShards, fitsInShard, getFileHashPosition, getNumericFileNameSha1, getShardForFilename } from "./consistent-sharding-pjG1rI6w.js";
 
-export { analyzeCodeowners, analyzeFilesByOwner, analyzeFilesWithoutOwner, 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 { calculateOptimalShardCount, distributeFilesAcrossShards, fitsInShard, getFileHashPosition, getNumericFileNameSha1, getShardForFilename } from "./consistent-sharding-D0wYSQBl.js";
-export { calculateOptimalShardCount, distributeFilesAcrossShards, fitsInShard, getFileHashPosition, getNumericFileNameSha1, getShardForFilename };
+import { analyzeShardScaling, calculateOptimalShardCount, distributeFilesAcrossShards, fitsInShard, getFileHashPosition, getNumericFileNameSha1, getShardForFilename } from "./consistent-sharding-CwWnbSoW.js";
+export { analyzeShardScaling, calculateOptimalShardCount, distributeFilesAcrossShards, fitsInShard, getFileHashPosition, getNumericFileNameSha1, getShardForFilename };

package/dist/sharding.js

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

package/package.json

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

package/dist/consistent-sharding-DDU9PV2R.js

@@ -1,71 +0,0 @@
-#!/usr/bin/env node
-import crypto from "node:crypto";
-
-//#region src/utils/consistent-sharding.ts
-const HASH_RING_SIZE = 1e6;
-/**
-* Generates a numeric hash from a filename using SHA1
-*/
-function getNumericFileNameSha1(filename) {
-	return parseInt(crypto.createHash("sha1").update(filename).digest("hex"), 16);
-}
-/**
-* Maps a filename to a consistent position on the hash ring (0 to HASH_RING_SIZE-1)
-* This position remains constant regardless of shard count changes
-*/
-function getFileHashPosition(filename) {
-	return getNumericFileNameSha1(filename) % HASH_RING_SIZE;
-}
-/**
-* Gets the shard index for a filename using deterministic hashing
-* Files get assigned to a consistent preferred shard regardless of total count
-*
-* @param filename - The file path to hash
-* @param shardCount - Total number of shards
-* @returns Shard index (0-based)
-*/
-function getShardForFilename(filename, { shardCount }) {
-	if (shardCount <= 0) throw new Error("Shard count must be greater than 0");
-	return getNumericFileNameSha1(filename) % 10 % shardCount;
-}
-/**
-* Checks if a file belongs to a specific shard
-*
-* @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
-*/
-function fitsInShard(filename, { shardCount, shardIndex }) {
-	return getShardForFilename(filename, { shardCount }) === shardIndex;
-}
-/**
-* Distributes files across shards using deterministic hashing
-*
-* @param filenames - Array of file paths
-* @param shardCount - Total number of shards
-* @returns Map of shard index to array of filenames
-*/
-function distributeFilesAcrossShards(filenames, shardCount) {
-	if (shardCount <= 0) throw new Error("Shard count must be greater than 0");
-	const shardMap = /* @__PURE__ */ new Map();
-	for (let i = 0; i < shardCount; i++) shardMap.set(i, []);
-	for (const filename of filenames) {
-		const shardIndex = getShardForFilename(filename, { shardCount });
-		shardMap.get(shardIndex).push(filename);
-	}
-	return shardMap;
-}
-/**
-* 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 calculateOptimalShardCount(totalFiles, targetShardSize) {
-	return Math.ceil(totalFiles / targetShardSize);
-}
-
-//#endregion
-export { calculateOptimalShardCount, distributeFilesAcrossShards, fitsInShard, getFileHashPosition, getNumericFileNameSha1, getShardForFilename };