codemodctl 0.1.27 → 0.1.29

package/dist/cli.d.mts

@@ -0,0 +1,2 @@
+
+export { };

package/dist/cli.mjs

@@ -0,0 +1,405 @@
+#!/usr/bin/env node
+import { analyzeCodeowners } from "./codeowners.mjs";
+import { analyzeDirectories } from "./directory.mjs";
+import { defineCommand, runMain } from "citty";
+import crypto from "node:crypto";
+import { $ } from "execa";
+import { writeFile } from "node:fs/promises";
+
+//#region src/commands/git/create-pr.ts
+function logExecError(message, error) {
+	console.error(message);
+	if (error && typeof error === "object" && "stderr" in error) {
+		const execError = error;
+		if (execError.stderr) console.error(execError.stderr);
+		if (execError.stdout) console.error(execError.stdout);
+	} else console.error(error instanceof Error ? error.message : String(error));
+}
+const createPrCommand = defineCommand({
+	meta: {
+		name: "create-pr",
+		description: "Create a pull request"
+	},
+	args: {
+		title: {
+			type: "string",
+			description: "Title of the pull request",
+			required: true
+		},
+		body: {
+			type: "string",
+			description: "Body/description of the pull request",
+			required: false
+		},
+		head: {
+			type: "string",
+			description: "Head branch for the pull request",
+			required: false
+		},
+		base: {
+			type: "string",
+			description: "Base branch to merge into",
+			required: false
+		},
+		push: {
+			type: "boolean",
+			required: false
+		},
+		commitMessage: {
+			alias: "m",
+			type: "string",
+			description: "Message to commit",
+			required: false
+		},
+		branchName: {
+			alias: "b",
+			type: "string",
+			description: "Branch to create the pull request from",
+			required: false
+		}
+	},
+	async run({ args }) {
+		const { title, body, head, base, push, commitMessage, branchName } = args;
+		if (push && !commitMessage) {
+			console.error("Error: commitMessage is required if commit is true");
+			process.exit(1);
+		}
+		const apiEndpoint = process.env.BUTTERFLOW_API_ENDPOINT;
+		const authToken = process.env.BUTTERFLOW_API_AUTH_TOKEN;
+		const taskId = process.env.CODEMOD_TASK_ID;
+		if (!taskId) {
+			console.error("Error: CODEMOD_TASK_ID environment variable is required");
+			process.exit(1);
+		}
+		if (!apiEndpoint) {
+			console.error("Error: BUTTERFLOW_API_ENDPOINT environment variable is required");
+			process.exit(1);
+		}
+		if (!authToken) {
+			console.error("Error: BUTTERFLOW_API_AUTH_TOKEN environment variable is required");
+			process.exit(1);
+		}
+		const prData = { title };
+		if (push) {
+			try {
+				await $`git diff --quiet`;
+				await $`git diff --cached --quiet`;
+				console.error("No changes detected, skipping pull request creation.");
+				process.exit(0);
+			} catch {
+				console.log("Changes detected, proceeding with pull request creation...");
+			}
+			const taskIdSignature = crypto.createHash("sha256").update(taskId).digest("hex").slice(0, 8);
+			const codemodBranchName = branchName ? branchName : `codemod-${taskIdSignature}`;
+			let remoteBaseBranch;
+			try {
+				remoteBaseBranch = (await $`git remote show origin`).stdout.match(/HEAD branch: (.+)/)?.[1]?.trim() || "main";
+			} catch (error) {
+				logExecError("Error: Failed to get remote base branch", error);
+				process.exit(1);
+			}
+			if (codemodBranchName) prData.head = codemodBranchName;
+			if (remoteBaseBranch) prData.base = remoteBaseBranch;
+			console.debug(`Remote base branch: ${remoteBaseBranch}`);
+			try {
+				await $`git checkout -b ${codemodBranchName}`;
+			} catch (error) {
+				logExecError("Error: Failed to checkout branch", error);
+				process.exit(1);
+			}
+			try {
+				await $`git add .`;
+			} catch (error) {
+				logExecError("Error: Failed to add changes", error);
+				process.exit(1);
+			}
+			try {
+				await $`git commit --no-verify -m ${commitMessage}`;
+			} catch (error) {
+				logExecError("Error: Failed to commit changes", error);
+				process.exit(1);
+			}
+			try {
+				await $({ env: process.env.DEBUG ? {
+					GIT_TRACE: "1",
+					GIT_TRACE_PACKET: "1"
+				} : {} })`git push origin ${codemodBranchName} --force`;
+				console.log(`Pushed branch to origin: ${codemodBranchName}`);
+			} catch (error) {
+				if ((error && typeof error === "object" && "stderr" in error ? String(error.stderr) : "").includes("Everything up-to-date")) console.log(`Branch ${codemodBranchName} is already up-to-date on remote, continuing...`);
+				else {
+					logExecError("Error: Failed to push changes", error);
+					process.exit(1);
+				}
+			}
+		}
+		if (body) prData.body = body;
+		if (head && !prData.head) prData.head = head;
+		if (base && !prData.base) prData.base = base;
+		const prUrl = `${apiEndpoint}/api/butterflow/v1/tasks/${taskId}/pull-request`;
+		try {
+			console.log("Creating pull request...");
+			console.log(`  URL: ${prUrl}`);
+			console.log(`  Title: ${title}`);
+			console.log(`  Head: ${prData.head ?? head ?? "(not set)"}`);
+			console.log(`  Base: ${prData.base ?? base ?? "(not set)"}`);
+			if (body) console.log(`  Body: ${body}`);
+			const response = await fetch(prUrl, {
+				method: "POST",
+				headers: {
+					Authorization: `Bearer ${authToken}`,
+					"Content-Type": "application/json"
+				},
+				body: JSON.stringify(prData)
+			});
+			if (!response.ok) {
+				const errorText = await response.text();
+				console.error(`❌ Failed to create pull request: HTTP ${response.status}`);
+				console.error(`  Response: ${errorText}`);
+				process.exit(1);
+			}
+			await response.json();
+			console.log("✅ Pull request created successfully!");
+		} catch (error) {
+			console.error("❌ Failed to create pull request:");
+			console.error(`  URL: ${prUrl}`);
+			console.error(`  PR data: ${JSON.stringify(prData)}`);
+			if (error instanceof TypeError && error.message === "fetch failed") {
+				const cause = error.cause;
+				console.error(`  Cause: ${cause instanceof Error ? cause.message : String(cause ?? "unknown")}`);
+			} else console.error(`  Error: ${error instanceof Error ? error.message : String(error)}`);
+			process.exit(1);
+		}
+	}
+});
+
+//#endregion
+//#region src/commands/git/index.ts
+const gitCommand = defineCommand({
+	meta: {
+		name: "git",
+		description: "Git operations"
+	},
+	subCommands: { "create-pr": 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",
+		description: "Analyze GitHub CODEOWNERS file and create 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
+		},
+		codeowners: {
+			type: "string",
+			description: "Path to CODEOWNERS file (optional)",
+			required: false
+		},
+		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, codeowners: codeownersPath, 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}`);
+			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 result = await analyzeCodeowners({
+				shardSize,
+				codeownersPath,
+				rulePath: codemodFilePath,
+				projectRoot: process.cwd(),
+				language,
+				existingState
+			});
+			const stateOutput = `${stateProp}=${JSON.stringify(result.shards)}\n`;
+			console.log(`Writing state output to: ${stateOutputsPath}`);
+			await writeFile(stateOutputsPath, stateOutput, { flag: "a" });
+			console.log("✅ Sharding completed successfully!");
+			console.log("Generated shards:", JSON.stringify(result.shards, null, 2));
+		} catch (error) {
+			console.error("❌ Failed to process codeowner file:");
+			console.error(error instanceof Error ? error.message : String(error));
+			process.exit(1);
+		}
+	}
+});
+
+//#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 result = await analyzeDirectories({
+				shardSize,
+				target,
+				rulePath: codemodFilePath,
+				projectRoot: process.cwd(),
+				language,
+				existingState
+			});
+			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({
+	meta: {
+		name: "shard",
+		description: "Sharding operations for distributing work"
+	},
+	subCommands: {
+		codeowner: codeownerCommand,
+		directory: directoryCommand
+	}
+});
+
+//#endregion
+//#region src/cli.ts
+runMain(defineCommand({
+	meta: {
+		name: "codemodctl",
+		version: "0.1.0",
+		description: "CLI tool for workflow engine operations"
+	},
+	subCommands: {
+		git: gitCommand,
+		shard: shardCommand
+	}
+}));
+
+//#endregion
+export {  };

package/dist/codemod-cli-D-ormE6R.mjs

@@ -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 --allow-fs --allow-fetch --allow-child-process --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 as t };

package/dist/codeowners.d.mts

@@ -0,0 +1,96 @@
+
+//#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 */
+  _meta_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;
+}
+/**
+ * Finds and resolves the CODEOWNERS file path
+ * Searches in common locations: root, .github/, docs/
+ * Returns null if no CODEOWNERS file is found
+ */
+declare function findCodeownersFile(projectRoot?: string, explicitPath?: string): Promise<string | null>;
+/**
+ * Normalizes owner name by removing `@` prefix and converting to lowercase
+ */
+declare function normalizeOwnerName(owner: string): string;
+/**
+ * Analyzes files and groups them by codeowner team
+ */
+declare function analyzeFilesByOwner(codeownersPath: string, language: string, rulePath: string, projectRoot?: string): Promise<Map<string, string[]>>;
+/**
+ * Analyzes files without codeowner parsing - assigns all files to "unassigned"
+ */
+declare function analyzeFilesWithoutOwner(language: string, rulePath: string, projectRoot?: string): Promise<Map<string, string[]>>;
+/**
+ * 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, 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.
+ * 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, getTeamFileInfo, normalizeOwnerName };

package/dist/codeowners.mjs

@@ -0,0 +1,158 @@
+#!/usr/bin/env node
+import { t as getApplicableFiles } from "./codemod-cli-D-ormE6R.mjs";
+import Codeowners from "codeowners";
+import { existsSync } from "node:fs";
+import path, { resolve } from "node:path";
+
+//#region src/utils/codeowner-analysis.ts
+/**
+* Finds and resolves the CODEOWNERS file path
+* Searches in common locations: root, .github/, docs/
+* Returns null if no CODEOWNERS file is found
+*/
+async function findCodeownersFile(projectRoot = process.cwd(), explicitPath) {
+	if (explicitPath) {
+		const resolvedPath = resolve(explicitPath);
+		if (!existsSync(resolvedPath)) throw new Error(`CODEOWNERS file not found at: ${resolvedPath}`);
+		return resolvedPath;
+	}
+	const searchPaths = [
+		resolve(projectRoot, "CODEOWNERS"),
+		resolve(projectRoot, ".github", "CODEOWNERS"),
+		resolve(projectRoot, "docs", "CODEOWNERS")
+	];
+	for (const searchPath of searchPaths) if (existsSync(searchPath)) return searchPath;
+	return null;
+}
+/**
+* Normalizes owner name by removing `@` prefix and converting to lowercase
+*/
+function normalizeOwnerName(owner) {
+	return owner.replace("@", "").toLowerCase();
+}
+/**
+* Analyzes files and groups them by codeowner team
+*/
+async function analyzeFilesByOwner(codeownersPath, language, rulePath, projectRoot = process.cwd()) {
+	const codeowners = new Codeowners(codeownersPath);
+	const gitRootDir = codeowners.codeownersDirectory;
+	const filesByOwner = /* @__PURE__ */ new Map();
+	const applicableFiles = await getApplicableFiles(rulePath, language, projectRoot);
+	for (const filePath of applicableFiles) {
+		const absolutePath = path.resolve(projectRoot, filePath);
+		const relativePath = path.relative(gitRootDir, absolutePath);
+		const owners = codeowners.getOwner(relativePath);
+		let ownerKey;
+		if (owners && owners.length > 0) {
+			const owner = owners[0];
+			ownerKey = normalizeOwnerName(owner ?? "unknown");
+		} else ownerKey = "unassigned";
+		if (!filesByOwner.has(ownerKey)) filesByOwner.set(ownerKey, []);
+		filesByOwner.get(ownerKey)?.push(relativePath);
+	}
+	return filesByOwner;
+}
+/**
+* Analyzes files without codeowner parsing - assigns all files to "unassigned"
+*/
+async function analyzeFilesWithoutOwner(language, rulePath, projectRoot = process.cwd()) {
+	const filesByOwner = /* @__PURE__ */ new Map();
+	const unassignedFiles = (await getApplicableFiles(rulePath, language, projectRoot)).map((filePath) => {
+		return path.relative(projectRoot, path.resolve(projectRoot, filePath));
+	});
+	filesByOwner.set("unassigned", unassignedFiles);
+	return filesByOwner;
+}
+/**
+* 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);
+}
+/**
+* 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 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}`,
+				_meta_files: shardFiles
+			});
+		}
+	}
+	return allShards;
+}
+/**
+* Converts file ownership map to team info array
+*/
+function getTeamFileInfo(filesByOwner) {
+	return Array.from(filesByOwner.entries()).map(([team, files]) => ({
+		team,
+		fileCount: files.length,
+		files
+	}));
+}
+/**
+* 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(), existingState } = options;
+	const resolvedCodeownersPath = await findCodeownersFile(projectRoot, codeownersPath);
+	let filesByOwner;
+	console.debug(`Using rule file: ${rulePath}`);
+	console.debug(`Shard size: ${shardSize}`);
+	if (resolvedCodeownersPath) {
+		console.log(`Analyzing CODEOWNERS file: ${resolvedCodeownersPath}`);
+		console.log("Analyzing files with CLI command...");
+		filesByOwner = await analyzeFilesByOwner(resolvedCodeownersPath, language, rulePath, projectRoot);
+	} else {
+		console.log("No CODEOWNERS file found, assigning all files to 'unassigned'");
+		console.log("Analyzing files with CLI command...");
+		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, 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 {
+		teams,
+		shards,
+		totalFiles
+	};
+}
+
+//#endregion
+export { analyzeCodeowners, analyzeFilesByOwner, analyzeFilesWithoutOwner, findCodeownersFile, generateShards, getTeamFileInfo, normalizeOwnerName };

package/dist/directory.d.mts

@@ -0,0 +1,73 @@
+
+//#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 */
+  _meta_files: string[];
+  /** The name of the shard */
+  name: 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
+ * @param projectRoot - Root directory of the project for resolving relative paths
+ * @returns Map of subdirectory paths to their file lists
+ */
+declare function groupFilesByDirectory(files: string[], target: string, projectRoot: 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.mjs

@@ -0,0 +1,98 @@
+#!/usr/bin/env node
+import { t as getApplicableFiles } from "./codemod-cli-D-ormE6R.mjs";
+import { calculateOptimalShardCount, distributeFilesAcrossShards } from "./sharding.mjs";
+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
+* @param projectRoot - Root directory of the project for resolving relative paths
+* @returns Map of subdirectory paths to their file lists
+*/
+function groupFilesByDirectory(files, target, projectRoot) {
+	const resolvedTarget = path.resolve(projectRoot, target);
+	const filesByDirectory = /* @__PURE__ */ new Map();
+	for (const filePath of files) {
+		const normalizedFile = path.normalize(filePath);
+		const resolvedFile = path.resolve(projectRoot, normalizedFile);
+		if (!resolvedFile.startsWith(resolvedTarget)) continue;
+		const relativePath = path.relative(projectRoot, resolvedFile);
+		const relativeFromTarget = path.relative(resolvedTarget, resolvedFile);
+		if (!relativeFromTarget.includes(path.sep)) continue;
+		const firstDir = relativeFromTarget.split(path.sep)[0];
+		if (!firstDir) continue;
+		const subdirectory = path.relative(projectRoot, path.join(resolvedTarget, firstDir));
+		if (!filesByDirectory.has(subdirectory)) filesByDirectory.set(subdirectory, []);
+		filesByDirectory.get(subdirectory)?.push(relativePath);
+	}
+	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,
+				_meta_files: shardFiles.sort(),
+				name: `${directory} (${shardIndex + 1}/${shardCount})`
+			});
+		}
+	}
+	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;
+	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, path.resolve(projectRoot, target), projectRoot);
+	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/index.d.mts

@@ -0,0 +1,4 @@
+
+import { analyzeShardScaling, calculateOptimalShardCount, distributeFilesAcrossShards, fitsInShard, getFileHashPosition, getNumericFileNameSha1, getShardForFilename } from "./sharding.mjs";
+import { CodeownerAnalysisOptions, CodeownerAnalysisResult, ShardResult, TeamFileInfo, analyzeCodeowners, analyzeFilesByOwner, analyzeFilesWithoutOwner, findCodeownersFile, generateShards, getTeamFileInfo, normalizeOwnerName } from "./codeowners.mjs";
+export { CodeownerAnalysisOptions, CodeownerAnalysisResult, ShardResult, TeamFileInfo, analyzeCodeowners, analyzeFilesByOwner, analyzeFilesWithoutOwner, analyzeShardScaling, calculateOptimalShardCount, distributeFilesAcrossShards, findCodeownersFile, fitsInShard, generateShards, getFileHashPosition, getNumericFileNameSha1, getShardForFilename, getTeamFileInfo, normalizeOwnerName };

package/dist/index.mjs

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+import { analyzeCodeowners, analyzeFilesByOwner, analyzeFilesWithoutOwner, findCodeownersFile, generateShards, getTeamFileInfo, normalizeOwnerName } from "./codeowners.mjs";
+import { analyzeShardScaling, calculateOptimalShardCount, distributeFilesAcrossShards, fitsInShard, getFileHashPosition, getNumericFileNameSha1, getShardForFilename } from "./sharding.mjs";
+
+export { analyzeCodeowners, analyzeFilesByOwner, analyzeFilesWithoutOwner, analyzeShardScaling, calculateOptimalShardCount, distributeFilesAcrossShards, findCodeownersFile, fitsInShard, generateShards, getFileHashPosition, getNumericFileNameSha1, getShardForFilename, getTeamFileInfo, normalizeOwnerName };

package/dist/sharding.d.mts

@@ -0,0 +1,68 @@
+
+//#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;
+/**
+ * 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
+ */
+declare function getFileHashPosition(filename: string): number;
+/**
+ * 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)
+ */
+declare function getShardForFilename(filename: string, {
+  shardCount
+}: {
+  shardCount: number;
+}): number;
+/**
+ * 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
+ */
+declare function fitsInShard(filename: string, shard: {
+  _meta_files: string[];
+}): boolean;
+/**
+ * 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
+ */
+declare function distributeFilesAcrossShards(filenames: string[], shardCount: number): Map<number, string[]>;
+/**
+ * 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
+ */
+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 { analyzeShardScaling, calculateOptimalShardCount, distributeFilesAcrossShards, fitsInShard, getFileHashPosition, getNumericFileNameSha1, getShardForFilename };

package/dist/sharding.mjs

@@ -0,0 +1,108 @@
+#!/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 ?? 0;
+}
+/**
+* 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._meta_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) if (getShardForFilename(filename, { shardCount: oldShardCount }) !== getShardForFilename(filename, { shardCount: newShardCount })) 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "codemodctl",
-  "version": "0.1.27",
+  "version": "0.1.29",
   "description": "CLI tool and utilities for workflow engine operations, file sharding, and codeowner analysis",
   "type": "module",
   "exports": {
@@ -33,9 +33,9 @@
   },
   "devDependencies": {
     "@types/node": "^22.16.5",
-    "@typescript/native-preview": "7.0.0-dev.20251120.1",
+    "@typescript/native-preview": "7.0.0-dev.20260122.3",
     "oxlint": "^1.29.0",
-    "tsdown": "^0.15.4",
+    "tsdown": "0.20.3",
     "typescript": "^5.9.3",
     "vitest": "^4.0.9",
     "@acme/tsconfig": "0.1.0"