ts-repo-utils 5.1.0 → 5.2.0

package/src/functions/diff.test.mts

@@ -26,12 +26,12 @@ describe('diff', () => {
     });
 
     test('should detect newly created files', async () => {
-      const testFiles = new Set<string>();
+      const mut_testFiles = new Set<string>();
 
       // Create a new file in project root
       const testFileName = 'test-new-file.tmp';
       const testFilePath = path.join(process.cwd(), testFileName);
-      testFiles.add(testFilePath);
+      mut_testFiles.add(testFilePath);
 
       await fs.writeFile(testFilePath, 'test content');
 
@@ -43,25 +43,25 @@ describe('diff', () => {
         expect(files).toContain(testFileName);
       }
 
-      await cleanupTestFiles(testFiles);
+      await cleanupTestFiles(mut_testFiles);
     });
 
     test('should detect modified existing files', async () => {
-      const testFiles = new Set<string>();
+      const mut_testFiles = new Set<string>();
 
       // Use an existing file in the project that we can modify safely
       const testFileName = 'test-modify-file.tmp';
-      const testFilePath = path.join(process.cwd(), testFileName);
-      testFiles.add(testFilePath);
+      const mut_testFilePath = path.join(process.cwd(), testFileName);
+      mut_testFiles.add(mut_testFilePath);
 
       // Create and commit the file first
-      await fs.writeFile(testFilePath, 'initial content');
+      await fs.writeFile(mut_testFilePath, 'initial content');
 
       // Add to git to track it
       await $(`git add ${testFileName}`, { silent: true });
 
       // Modify the file
-      await fs.writeFile(testFilePath, 'modified content');
+      await fs.writeFile(mut_testFilePath, 'modified content');
 
       const result = await getUntrackedFiles({ silent: true });
 
@@ -74,17 +74,17 @@ describe('diff', () => {
       // Reset git state
       await $(`git reset HEAD ${testFileName}`, { silent: true });
 
-      await cleanupTestFiles(testFiles);
+      await cleanupTestFiles(mut_testFiles);
     });
 
     test('should detect multiple types of changes', async () => {
-      const testFiles = new Set<string>();
+      const mut_testFiles = new Set<string>();
 
       // Create multiple test files
       const newFile = path.join(process.cwd(), 'test-new-file.tmp');
       const modifyFile = path.join(process.cwd(), 'test-modify-file.tmp');
-      testFiles.add(newFile);
-      testFiles.add(modifyFile);
+      mut_testFiles.add(newFile);
+      mut_testFiles.add(modifyFile);
 
       // Create new file
       await fs.writeFile(newFile, 'new file content');
@@ -108,7 +108,7 @@ describe('diff', () => {
       // Reset git state
       await $(`git reset HEAD test-modify-file.tmp`, { silent: true });
 
-      await cleanupTestFiles(testFiles);
+      await cleanupTestFiles(mut_testFiles);
     });
 
     test('should exclude deleted files from results', async () => {

package/src/functions/exec-async.mts

@@ -3,6 +3,7 @@ import { Result } from 'ts-data-forge';
 
 /**
  * Executes a shell command asynchronously.
+ *
  * @param cmd - The command to execute.
  * @param options - Optional configuration for command execution.
  * @returns A promise that resolves with the command result.

package/src/functions/format.mts

@@ -5,6 +5,7 @@ import { getDiffFrom, getUntrackedFiles } from './diff.mjs';
 
 /**
  * Format a list of files using Prettier
+ *
  * @param files - Array of file paths to format
  * @returns 'ok' if successful, 'err' if any errors occurred
  */
@@ -74,6 +75,7 @@ export const formatFilesList = async (
 
 /**
  * Format files matching the given glob pattern using Prettier
+ *
  * @param pathGlob - Glob pattern to match files
  * @returns 'ok' if successful, 'err' if any errors occurred
  */
@@ -107,6 +109,7 @@ export const formatFiles = async (
 
 /**
  * Format only files that have been changed (git status)
+ *
  * @param options - Options for formatting
  * @returns 'ok' if successful, 'err' if any errors occurred
  */
@@ -169,10 +172,14 @@ export const formatUntracked = async (
 
 /**
  * Format only files that differ from the specified base branch or commit
- * @param base - Base branch name or commit hash to compare against (defaults to 'main')
+ *
+ * @param base - Base branch name or commit hash to compare against (defaults to
+ *   'main')
  * @param options - Options for formatting
- * @param options.includeUntracked - Include untracked files in addition to diff files (default is true)
- * @param options.silent - Silent mode to suppress command output (default is false)
+ * @param options.includeUntracked - Include untracked files in addition to diff
+ *   files (default is true)
+ * @param options.silent - Silent mode to suppress command output (default is
+ *   false)
  * @returns 'ok' if successful, 'err' if any errors occurred
  */
 export const formatDiffFrom = async (

package/src/functions/gen-index.mts

@@ -1,16 +1,33 @@
 import micromatch from 'micromatch';
-import { Arr, ISet, isString, Result } from 'ts-data-forge';
+import { Arr, ISet, isString, pipe, Result } from 'ts-data-forge';
 import '../node-global.mjs';
 import { assertPathExists } from './assert-path-exists.mjs';
 
-/**
- * Configuration for index file generation.
- */
+/** Configuration for index file generation. */
 export type GenIndexConfig = DeepReadonly<{
   /** Target directories to generate index files for (string or array of strings) */
   targetDirectory: string | readonly string[];
 
-  /** Glob patterns of files to exclude from exports (default: excludes `'**\/*.{test,spec}.?(c|m)[jt]s?(x)'`) */
+  /**
+   * Glob patterns of files or predicate function to exclude from exports
+   * (default: excludes `'**\/*.{test,spec}.?(c|m)[jt]s?(x)'`)
+   */
+  exclude?:
+    | readonly string[]
+    | ((
+        args: Readonly<{
+          absolutePath: string;
+          relativePath: string;
+          fileName: string;
+        }>,
+      ) => boolean);
+
+  /**
+   * Glob patterns of files or predicate function to exclude from exports
+   * (default: excludes `'**\/*.{test,spec}.?(c|m)[jt]s?(x)'`)
+   *
+   * @deprecated Use `exclude` instead.
+   */
   excludePatterns?: readonly string[];
 
   /** File extensions of source files to export (default: ['.ts', '.tsx']) */
@@ -22,7 +39,7 @@ export type GenIndexConfig = DeepReadonly<{
   /** File extension to use in export statements (default: '.js') */
   exportExtension?: `.${string}` | 'none';
 
-  /** Command to run for formatting generated files (default: 'npm run fmt') */
+  /** Command to run for formatting generated files (optional) */
   formatCommand?: string;
 
   /** Whether to suppress output during execution (default: false) */
@@ -32,7 +49,13 @@ export type GenIndexConfig = DeepReadonly<{
 type GenIndexConfigInternal = DeepReadonly<{
   formatCommand: string | undefined;
   targetDirectory: ISet<string>;
-  excludePatterns: ISet<string>;
+  exclude: (
+    args: Readonly<{
+      absolutePath: string;
+      relativePath: string;
+      fileName: string;
+    }>,
+  ) => boolean;
   sourceExtensions: ISet<`.${string}`>;
   indexExtension: `.${string}`;
   exportExtension: `.${string}` | 'none';
@@ -41,6 +64,7 @@ type GenIndexConfigInternal = DeepReadonly<{
 
 /**
  * Generates index.ts files recursively in `config.targetDirectory`.
+ *
  * @param config - Configuration for index file generation
  * @throws Error if any step fails.
  */
@@ -92,17 +116,6 @@ export const genIndex = async (config: GenIndexConfig): Promise<void> => {
   }
 };
 
-/**
- * Fills the configuration with default values.
- * Default values:
- * - sourceExtensions: ['.ts']
- * - indexExtension: '.ts'
- * - exportExtension: '.js'
- * - excludePatterns: ['**\/*.{test,spec}.?(c|m)[jt]s?(x)']
- * - silent: false
- * @param config - The input configuration object.
- * @returns The configuration object with all required properties filled with defaults.
- */
 const fillConfig = (config: GenIndexConfig): GenIndexConfigInternal => {
   const sourceExtensions = config.sourceExtensions ?? ['.ts'];
   const exportExtension = config.exportExtension ?? '.js'; // For ESM imports, .mts resolves to .mjs
@@ -114,14 +127,41 @@ const fillConfig = (config: GenIndexConfig): GenIndexConfigInternal => {
         ? [config.targetDirectory]
         : config.targetDirectory,
     ),
-    excludePatterns: ISet.create(
-      Arr.generate(function* () {
-        if (config.excludePatterns !== undefined) {
-          yield* config.excludePatterns;
-        }
-        yield '**/*.{test,spec}.?(c|m)[jt]s?(x)';
-      }),
-    ),
+    // eslint-disable-next-line @typescript-eslint/no-deprecated
+    exclude: pipe(config.exclude ?? config.excludePatterns).map((exclude) =>
+      typeof exclude === 'function'
+        ? exclude
+        : pipe(
+            ISet.create<string>(
+              Arr.generate(function* () {
+                if (exclude !== undefined && Array.isArray(exclude)) {
+                  yield* exclude;
+                }
+                yield '**/*.{test,spec}.?(c|m)[jt]s?(x)';
+              }),
+            ),
+          ).map(
+            (set) =>
+              ({
+                relativePath,
+                fileName,
+              }: Readonly<{
+                absolutePath: string;
+                relativePath: string;
+                fileName: string;
+              }>) => {
+                for (const pattern of set.values()) {
+                  if (
+                    micromatch.isMatch(relativePath, pattern) ||
+                    micromatch.isMatch(fileName, pattern)
+                  ) {
+                    return true;
+                  }
+                }
+                return false;
+              },
+          ).value,
+    ).value,
     sourceExtensions: ISet.create(sourceExtensions),
     indexExtension: config.indexExtension ?? '.ts',
     exportExtension,
@@ -130,11 +170,13 @@ const fillConfig = (config: GenIndexConfig): GenIndexConfigInternal => {
 };
 
 /**
- * Generates an index.ts file for the given directory.
- * Recursively calls itself for subdirectories.
+ * Generates an index.ts file for the given directory. Recursively calls itself
+ * for subdirectories.
+ *
  * @param dirPath - The absolute path to the directory to process.
  * @param config - The merged configuration object.
- * @param baseDir - The base directory path for calculating relative paths (optional, defaults to dirPath).
+ * @param baseDir - The base directory path for calculating relative paths
+ *   (optional, defaults to dirPath).
  * @throws Error if directory processing fails.
  */
 const generateIndexFileForDir = async (
@@ -155,11 +197,11 @@ const generateIndexFileForDir = async (
       const relativePath = path.relative(actualBaseDir, entryPath);
 
       if (
-        config.excludePatterns.some(
-          (pat) =>
-            micromatch.isMatch(relativePath, pat) ||
-            micromatch.isMatch(entryName, pat),
-        )
+        config.exclude({
+          absolutePath: entryPath,
+          relativePath,
+          fileName: entryName,
+        })
       ) {
         continue; // Skip excluded directories/files
       }
@@ -169,7 +211,14 @@ const generateIndexFileForDir = async (
         // Recursively call for subdirectories first
         // eslint-disable-next-line no-await-in-loop
         await generateIndexFileForDir(entryPath, config, actualBaseDir);
-      } else if (entry.isFile() && shouldExportFile(relativePath, config)) {
+      } else if (
+        entry.isFile() &&
+        shouldExportFile({
+          absolutePath: entryPath,
+          filePath: relativePath,
+          config,
+        })
+      ) {
         mut_filesToExport.push(entryName);
       }
     }
@@ -194,19 +243,27 @@ const generateIndexFileForDir = async (
 const indexRegex = /^index\.[cm]?[jt]s[x]?$/u;
 
 /**
- * Determines if a file should be exported in the index file.
- * A file is exported if:
+ * Determines if a file should be exported in the index file. A file is exported
+ * if:
+ *
  * - It has one of the configured source extensions
  * - It's not an index file itself
  * - It doesn't match any exclusion patterns
+ *
  * @param filePath - The relative path to the file from the target directory.
+ * @param absolutePath - The absolute path to the file.
  * @param config - The merged configuration object.
  * @returns True if the file should be exported.
  */
-const shouldExportFile = (
-  filePath: string,
-  config: GenIndexConfigInternal,
-): boolean => {
+const shouldExportFile = ({
+  absolutePath,
+  filePath,
+  config,
+}: Readonly<{
+  absolutePath: string;
+  filePath: string;
+  config: GenIndexConfigInternal;
+}>): boolean => {
   const fileName = path.basename(filePath);
 
   const ext = path.extname(fileName);
@@ -224,13 +281,14 @@ const shouldExportFile = (
   }
 
   // Check against exclusion patterns
-  for (const pattern of config.excludePatterns.values()) {
-    if (
-      micromatch.isMatch(filePath, pattern) ||
-      micromatch.isMatch(fileName, pattern)
-    ) {
-      return false;
-    }
+  if (
+    config.exclude({
+      absolutePath,
+      relativePath: filePath,
+      fileName,
+    })
+  ) {
+    return false;
   }
 
   return true;
@@ -257,6 +315,7 @@ if (import.meta.vitest !== undefined) {
 
 /**
  * Generates the content for an index file.
+ *
  * @param subDirectories - Array of subdirectory names.
  * @param filesToExport - Array of file names to export.
  * @param config - The merged configuration object.

package/src/functions/should-run.mts

@@ -3,18 +3,21 @@ import '../node-global.mjs';
 import { getDiffFrom } from './diff.mjs';
 
 /**
- * Checks if TypeScript type checks should run based on the diff from origin/main.
- * Skips type checks if all changed files are documentation files, spell check config,
- * or other non-TypeScript files that don't affect type checking.
+ * Checks if TypeScript type checks should run based on the diff from
+ * origin/main. Skips type checks if all changed files are documentation files,
+ * spell check config, or other non-TypeScript files that don't affect type
+ * checking.
  *
  * Ignored file patterns:
+ *
  * - '.cspell.json'
  * - '**.md'
  * - '**.txt'
  * - 'docs/**'
  *
- * @returns A promise that resolves when the check is complete. Sets GITHUB_OUTPUT
- * environment variable with should_run=true/false if running in GitHub Actions.
+ * @returns A promise that resolves when the check is complete. Sets
+ *   GITHUB_OUTPUT environment variable with should_run=true/false if running in
+ *   GitHub Actions.
  */
 export const checkShouldRunTypeChecks = async (): Promise<void> => {
   // paths-ignore:

package/src/functions/workspace-utils/execute-parallel.mts

@@ -13,10 +13,13 @@ import { type Package } from './types.mjs';
 const DEBUG = false as boolean;
 
 /**
- * Executes a npm script across multiple packages in parallel with a concurrency limit.
+ * Executes a npm script across multiple packages in parallel with a concurrency
+ * limit.
+ *
  * @param packages - Array of Package objects to execute the script in
  * @param scriptName - The name of the npm script to execute
- * @param concurrency - Maximum number of packages to process simultaneously (default: 3)
+ * @param concurrency - Maximum number of packages to process simultaneously
+ *   (default: 3)
  * @returns A promise that resolves to an array of execution results
  */
 export const executeParallel = async (
@@ -30,7 +33,7 @@ export const executeParallel = async (
     Result<Readonly<{ code?: number; skipped?: boolean }>, Error>
   >[] = [];
 
-  const executing = new Set<Promise<unknown>>();
+  const mut_executing = new Set<Promise<unknown>>();
 
   for (const pkg of packages) {
     const promise = executeScript(pkg, scriptName);
@@ -38,22 +41,22 @@ export const executeParallel = async (
     mut_resultPromises.push(promise);
 
     const wrappedPromise = promise.finally(() => {
-      executing.delete(wrappedPromise);
+      mut_executing.delete(wrappedPromise);
       if (DEBUG) {
-        console.debug('executing size', executing.size);
+        console.debug('executing size', mut_executing.size);
       }
     });
 
-    executing.add(wrappedPromise);
+    mut_executing.add(wrappedPromise);
 
     if (DEBUG) {
-      console.debug('executing size', executing.size);
+      console.debug('executing size', mut_executing.size);
     }
 
     // If we reach concurrency limit, wait for one to finish
-    if (executing.size >= concurrency) {
+    if (mut_executing.size >= concurrency) {
       // eslint-disable-next-line no-await-in-loop
-      await Promise.race(executing);
+      await Promise.race(mut_executing);
     }
   }
 
@@ -61,12 +64,14 @@ export const executeParallel = async (
 };
 
 /**
- * Executes a npm script across packages in dependency order stages.
- * Packages are grouped into stages where each stage contains packages whose
- * dependencies have been completed in previous stages.
+ * Executes a npm script across packages in dependency order stages. Packages
+ * are grouped into stages where each stage contains packages whose dependencies
+ * have been completed in previous stages.
+ *
  * @param packages - Array of Package objects to execute the script in
  * @param scriptName - The name of the npm script to execute
- * @param concurrency - Maximum number of packages to process simultaneously within each stage (default: 3)
+ * @param concurrency - Maximum number of packages to process simultaneously
+ *   within each stage (default: 3)
  * @returns A promise that resolves when all stages are complete
  */
 export const executeStages = async (
@@ -79,16 +84,16 @@ export const executeStages = async (
   const sorted = topologicalSortPackages(packages, dependencyGraph);
 
   const mut_stages: (readonly Package[])[] = [];
-  const completed = new Set<string>();
+  const mut_completed = new Set<string>();
 
-  while (completed.size < sorted.length) {
+  while (mut_completed.size < sorted.length) {
     const mut_stage: Package[] = [];
 
     for (const pkg of sorted) {
-      if (completed.has(pkg.name)) continue;
+      if (mut_completed.has(pkg.name)) continue;
 
       const deps = dependencyGraph.get(pkg.name) ?? [];
-      const depsCompleted = deps.every((dep) => completed.has(dep));
+      const depsCompleted = deps.every((dep) => mut_completed.has(dep));
 
       if (depsCompleted) {
         mut_stage.push(pkg);
@@ -100,7 +105,9 @@ export const executeStages = async (
     }
 
     mut_stages.push(mut_stage);
-    for (const pkg of mut_stage) completed.add(pkg.name);
+    for (const pkg of mut_stage) {
+      mut_completed.add(pkg.name);
+    }
   }
 
   console.log(`\nExecuting ${scriptName} in ${mut_stages.length} stages...\n`);
@@ -116,11 +123,14 @@ export const executeStages = async (
 
 /**
  * Executes a npm script in a specific package directory.
+ *
  * @param pkg - The package object containing path and metadata
  * @param scriptName - The name of the npm script to execute
  * @param options - Configuration options
- * @param options.prefix - Whether to prefix output with package name (default: true)
- * @returns A promise that resolves to execution result with exit code or skipped flag
+ * @param options.prefix - Whether to prefix output with package name (default:
+ *   true)
+ * @returns A promise that resolves to execution result with exit code or
+ *   skipped flag
  */
 const executeScript = (
   pkg: Package,
@@ -189,8 +199,9 @@ const executeScript = (
   ).value;
 
 /**
- * Performs a topological sort on packages based on their dependencies,
- * ensuring dependencies are ordered before their dependents.
+ * Performs a topological sort on packages based on their dependencies, ensuring
+ * dependencies are ordered before their dependents.
+ *
  * @param packages - Array of Package objects to sort
  * @returns An array of packages in dependency order (dependencies first)
  */
@@ -198,14 +209,14 @@ const topologicalSortPackages = (
   packages: readonly Package[],
   dependencyGraph: ReadonlyMap<string, readonly string[]>,
 ): readonly Package[] => {
-  const visited = new Set<string>();
+  const mut_visited = new Set<string>();
   const mut_result: string[] = [];
 
   const packageMap = new Map(packages.map((p) => [p.name, p]));
 
   const visit = (pkgName: string): void => {
-    if (visited.has(pkgName)) return;
-    visited.add(pkgName);
+    if (mut_visited.has(pkgName)) return;
+    mut_visited.add(pkgName);
 
     const deps = dependencyGraph.get(pkgName) ?? [];
     for (const dep of deps) {
@@ -227,21 +238,23 @@ const topologicalSortPackages = (
 /**
  * Builds a dependency graph from the given packages, mapping each package name
  * to its internal workspace dependencies.
+ *
  * @param packages - Array of Package objects to analyze
- * @returns A readonly map where keys are package names and values are arrays of their dependency package names
+ * @returns A readonly map where keys are package names and values are arrays of
+ *   their dependency package names
  */
 const buildDependencyGraph = (
   packages: readonly Package[],
 ): ReadonlyMap<string, readonly string[]> => {
   const packageMap = new Map(packages.map((p) => [p.name, p]));
-  const graph = new Map<string, readonly string[]>();
+  const mut_graph = new Map<string, readonly string[]>();
 
   for (const pkg of packages) {
     const deps = Object.keys(pkg.dependencies).filter((depName) =>
       packageMap.has(depName),
     );
-    graph.set(pkg.name, deps);
+    mut_graph.set(pkg.name, deps);
   }
 
-  return graph;
+  return mut_graph;
 };

package/src/functions/workspace-utils/get-workspace-packages.mts

@@ -12,10 +12,13 @@ import '../../node-global.mjs';
 import { type Package } from './types.mjs';
 
 /**
- * Retrieves all workspace packages from a monorepo based on the workspace patterns
- * defined in the root package.json file.
- * @param rootPackageJsonDir - The directory containing the root package.json file
- * @returns A promise that resolves to an array of Package objects containing package metadata
+ * Retrieves all workspace packages from a monorepo based on the workspace
+ * patterns defined in the root package.json file.
+ *
+ * @param rootPackageJsonDir - The directory containing the root package.json
+ *   file
+ * @returns A promise that resolves to an array of Package objects containing
+ *   package metadata
  */
 export const getWorkspacePackages = async (
   rootPackageJsonDir: string,

package/src/functions/workspace-utils/run-cmd-in-parallel.mts

@@ -5,11 +5,15 @@ import { getWorkspacePackages } from './get-workspace-packages.mjs';
 
 /**
  * Executes a npm script command across all workspace packages in parallel.
+ *
  * @param options - Configuration options for the parallel execution
- * @param options.rootPackageJsonDir - The directory containing the root package.json file
+ * @param options.rootPackageJsonDir - The directory containing the root
+ *   package.json file
  * @param options.cmd - The npm script command to execute in each package
- * @param options.concurrency - Maximum number of packages to process simultaneously (default: 3)
- * @param options.filterWorkspacePattern - Optional function to filter packages by name
+ * @param options.concurrency - Maximum number of packages to process
+ *   simultaneously (default: 3)
+ * @param options.filterWorkspacePattern - Optional function to filter packages
+ *   by name
  * @returns A promise that resolves when all packages have completed execution
  */
 export const runCmdInParallelAcrossWorkspaces = async ({

package/src/functions/workspace-utils/run-cmd-in-stages.mts

@@ -4,14 +4,18 @@ import { executeStages } from './execute-parallel.mjs';
 import { getWorkspacePackages } from './get-workspace-packages.mjs';
 
 /**
- * Executes a npm script command across all workspace packages in dependency order stages.
- * Packages are grouped into stages where each stage contains packages whose
- * dependencies have been completed in previous stages.
+ * Executes a npm script command across all workspace packages in dependency
+ * order stages. Packages are grouped into stages where each stage contains
+ * packages whose dependencies have been completed in previous stages.
+ *
  * @param options - Configuration options for the staged execution
- * @param options.rootPackageJsonDir - The directory containing the root package.json file
+ * @param options.rootPackageJsonDir - The directory containing the root
+ *   package.json file
  * @param options.cmd - The npm script command to execute in each package
- * @param options.concurrency - Maximum number of packages to process simultaneously within each stage (default: 3)
- * @param options.filterWorkspacePattern - Optional function to filter packages by name
+ * @param options.concurrency - Maximum number of packages to process
+ *   simultaneously within each stage (default: 3)
+ * @param options.filterWorkspacePattern - Optional function to filter packages
+ *   by name
  * @returns A promise that resolves when all stages have completed execution
  */
 export const runCmdInStagesAcrossWorkspaces = async ({