ts-repo-utils 5.0.2 → 5.2.0

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']) */
@@ -20,9 +37,9 @@ export type GenIndexConfig = DeepReadonly<{
   indexExtension?: `.${string}`;
 
   /** File extension to use in export statements (default: '.js') */
-  exportExtension?: `.${string}`;
+  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,15 +49,22 @@ 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}`;
+  exportExtension: `.${string}` | 'none';
   silent: boolean;
 }>;
 
 /**
  * Generates index.ts files recursively in `config.targetDirectory`.
+ *
  * @param config - Configuration for index file generation
  * @throws Error if any step fails.
  */
@@ -65,7 +89,7 @@ export const genIndex = async (config: GenIndexConfig): Promise<void> => {
     }
 
     // Step 2: Generate index files
-    echo('2. Generating index files...');
+    echo('Generating index files...');
     for (const dir of targetDirs) {
       const resolvedDir = path.resolve(dir);
       // eslint-disable-next-line no-await-in-loop
@@ -75,7 +99,7 @@ export const genIndex = async (config: GenIndexConfig): Promise<void> => {
 
     // Step 3: Format generated files
     if (filledConfig.formatCommand !== undefined) {
-      echo('3. Formatting generated files...');
+      echo('Formatting generated files...');
       const fmtResult = await $(filledConfig.formatCommand, {
         silent: filledConfig.silent,
       });
@@ -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 (
@@ -146,8 +188,8 @@ const generateIndexFileForDir = async (
     const actualBaseDir = baseDir ?? dirPath;
     const entries = await fs.readdir(dirPath, { withFileTypes: true });
 
-    const subDirectories: string[] = [];
-    const filesToExport: string[] = [];
+    const mut_subDirectories: string[] = [];
+    const mut_filesToExport: string[] = [];
 
     for (const entry of entries) {
       const entryName = entry.name;
@@ -155,28 +197,35 @@ 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
       }
 
       if (entry.isDirectory()) {
-        subDirectories.push(entryName);
+        mut_subDirectories.push(entryName);
         // 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)) {
-        filesToExport.push(entryName);
+      } else if (
+        entry.isFile() &&
+        shouldExportFile({
+          absolutePath: entryPath,
+          filePath: relativePath,
+          config,
+        })
+      ) {
+        mut_filesToExport.push(entryName);
       }
     }
 
     const indexContent = generateIndexContent(
-      subDirectories,
-      filesToExport,
+      mut_subDirectories,
+      mut_filesToExport,
       config,
     );
 
@@ -191,20 +240,30 @@ 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);
@@ -216,26 +275,47 @@ const shouldExportFile = (
 
   // Don't export the index file itself
   if (
-    /^index\.[cm]?[jt]s[x]?$/u.test(fileName) // Matches index.ts, index.mts, index.js, index.tsx
+    indexRegex.test(fileName) // Matches index.ts, index.mts, index.js, index.tsx
   ) {
     return false;
   }
 
   // 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;
 };
 
+if (import.meta.vitest !== undefined) {
+  describe('index file regex', () => {
+    test.each([
+      ['index.ts', true],
+      ['index.js', true],
+      ['index.mts', true],
+      ['index.mjs', true],
+      ['index.cts', true],
+      ['index.cjs', true],
+      ['index.tsx', true],
+      ['index.jsx', true],
+      ['not-index.ts', false],
+      ['index.txt', false],
+    ] as const)('indexRegex.test($0) to be $1', (fileName, expected) => {
+      expect(indexRegex.test(fileName)).toBe(expected);
+    });
+  });
+}
+
 /**
  * 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.
@@ -247,13 +327,17 @@ const generateIndexContent = (
   config: GenIndexConfigInternal,
 ): string => {
   const exportStatements = [
-    ...subDirectories.map(
-      (subDir) => `export * from "./${subDir}/index${config.exportExtension}";`,
+    ...subDirectories.map((subDir) =>
+      config.exportExtension === 'none'
+        ? `export * from "./${subDir}";`
+        : `export * from "./${subDir}/index${config.exportExtension}";`,
     ),
     ...filesToExport.map((file) => {
       const fileNameWithoutExt = path.basename(file, path.extname(file));
 
-      return `export * from "./${fileNameWithoutExt}${config.exportExtension}";`;
+      return config.exportExtension === 'none'
+        ? `export * from "./${fileNameWithoutExt}";`
+        : `export * from "./${fileNameWithoutExt}${config.exportExtension}";`;
     }),
   ];
 

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 (
@@ -78,34 +83,36 @@ export const executeStages = async (
 
   const sorted = topologicalSortPackages(packages, dependencyGraph);
 
-  const stages: (readonly Package[])[] = [];
-  const completed = new Set<string>();
+  const mut_stages: (readonly Package[])[] = [];
+  const mut_completed = new Set<string>();
 
-  while (completed.size < sorted.length) {
-    const stage: Package[] = [];
+  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) {
-        stage.push(pkg);
+        mut_stage.push(pkg);
       }
     }
 
-    if (stage.length === 0) {
+    if (mut_stage.length === 0) {
       throw new Error('Circular dependency detected');
     }
 
-    stages.push(stage);
-    for (const pkg of stage) completed.add(pkg.name);
+    mut_stages.push(mut_stage);
+    for (const pkg of mut_stage) {
+      mut_completed.add(pkg.name);
+    }
   }
 
-  console.log(`\nExecuting ${scriptName} in ${stages.length} stages...\n`);
+  console.log(`\nExecuting ${scriptName} in ${mut_stages.length} stages...\n`);
 
-  for (const [i, stage] of stages.entries()) {
+  for (const [i, stage] of mut_stages.entries()) {
     if (stage.length > 0) {
       console.log(`Stage ${i + 1}: ${stage.map((p) => p.name).join(', ')}`);
       // eslint-disable-next-line no-await-in-loop
@@ -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,28 +209,28 @@ const topologicalSortPackages = (
   packages: readonly Package[],
   dependencyGraph: ReadonlyMap<string, readonly string[]>,
 ): readonly Package[] => {
-  const visited = new Set<string>();
-  const result: 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) {
       visit(dep);
     }
 
-    result.push(pkgName);
+    mut_result.push(pkgName);
   };
 
   for (const pkg of packages) {
     visit(pkg.name);
   }
 
-  return result
+  return mut_result
     .map((pkgName) => packageMap.get(pkgName))
     .filter(isNotUndefined);
 };
@@ -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 ({
@@ -33,10 +37,10 @@ export const runCmdInParallelAcrossWorkspaces = async ({
 
     await executeParallel(filteredPackages, cmd, concurrency);
     console.log(`\n✅ ${cmd} completed successfully`);
-  } catch (err) {
+  } catch (error) {
     console.error(
       `\n❌ ${cmd} failed:`,
-      err instanceof Error ? err.message : (err?.toString() ?? ''),
+      error instanceof Error ? error.message : (error?.toString() ?? ''),
     );
     process.exit(1);
   }

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 ({
@@ -35,10 +39,10 @@ export const runCmdInStagesAcrossWorkspaces = async ({
 
     await executeStages(filteredPackages, cmd, concurrency);
     console.log(`\n✅ ${cmd} completed successfully`);
-  } catch (err) {
+  } catch (error) {
     console.error(
       `\n❌ ${cmd} failed:`,
-      err instanceof Error ? err.message : (err?.toString() ?? ''),
+      error instanceof Error ? error.message : (error?.toString() ?? ''),
     );
     process.exit(1);
   }

package/src/globals.d.mts

@@ -1 +1,2 @@
+/* eslint-disable import/unambiguous */
 /// <reference types="ts-type-forge" />