codemodctl 0.1.11 → 0.1.13

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,6 +1,6 @@
 #!/usr/bin/env node
-import "./consistent-sharding-DDU9PV2R.js";
-import { analyzeCodeowners } from "./codeowner-analysis-n5QdN_A3.js";
+import "./consistent-sharding-CcnfsY_k.js";
+import { analyzeCodeowners } from "./codeowner-analysis-C8hyzL4c.js";
 import { defineCommand, runMain } from "citty";
 import crypto from "node:crypto";
 import { $ } from "execa";

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

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { calculateOptimalShardCount } from "./consistent-sharding-DDU9PV2R.js";
+import { calculateOptimalShardCount } from "./consistent-sharding-CcnfsY_k.js";
 import { execSync } from "node:child_process";
 import { existsSync } from "node:fs";
 import path, { resolve } from "node:path";

package/dist/codeowners.js

@@ -1,5 +1,5 @@
 #!/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 "./consistent-sharding-CcnfsY_k.js";
+import { analyzeCodeowners, analyzeFilesByOwner, analyzeFilesWithoutOwner, findCodeownersFile, generateShards, getApplicableFiles, getTeamFileInfo, normalizeOwnerName } from "./codeowner-analysis-C8hyzL4c.js";
 
 export { analyzeCodeowners, analyzeFilesByOwner, analyzeFilesWithoutOwner, findCodeownersFile, generateShards, getApplicableFiles, getTeamFileInfo, normalizeOwnerName };

package/dist/consistent-sharding-CcnfsY_k.js

@@ -0,0 +1,113 @@
+#!/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
+*
+* @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);
+}
+/**
+* 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/{consistent-sharding-D0wYSQBl.d.ts → consistent-sharding-D9n1M6by.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
@@ -52,5 +53,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/index.d.ts

@@ -1,3 +1,3 @@
-import { calculateOptimalShardCount, distributeFilesAcrossShards, fitsInShard, getFileHashPosition, getNumericFileNameSha1, getShardForFilename } from "./consistent-sharding-D0wYSQBl.js";
+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, calculateOptimalShardCount, distributeFilesAcrossShards, findCodeownersFile, fitsInShard, generateShards, getApplicableFiles, getFileHashPosition, getNumericFileNameSha1, getShardForFilename, getTeamFileInfo, normalizeOwnerName };
+export { CodeownerAnalysisOptions, CodeownerAnalysisResult, ShardResult, TeamFileInfo, analyzeCodeowners, analyzeFilesByOwner, analyzeFilesWithoutOwner, analyzeShardScaling, calculateOptimalShardCount, distributeFilesAcrossShards, findCodeownersFile, fitsInShard, generateShards, getApplicableFiles, 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 { 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";
 
-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, getApplicableFiles, 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-D9n1M6by.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-CcnfsY_k.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.11",
+  "version": "0.1.13",
   "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 };