ts-repo-utils 7.7.3 → 7.8.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ts-repo-utils",
-  "version": "7.7.3",
+  "version": "7.8.1",
   "private": false,
   "keywords": [
     "typescript"
@@ -84,34 +84,35 @@
     "fast-glob": "^3.3.3",
     "micromatch": "^4.0.8",
     "prettier": "^3.6.2",
-    "ts-data-forge": "^3.3.0",
+    "ts-data-forge": "^3.3.1",
     "tsx": "^4.20.6"
   },
   "devDependencies": {
-    "@octokit/core": "^7.0.5",
-    "@rollup/plugin-replace": "^6.0.2",
+    "@octokit/core": "7.0.6",
+    "@rollup/plugin-replace": "^6.0.3",
     "@rollup/plugin-strip": "^3.0.4",
-    "@rollup/plugin-typescript": "^12.1.4",
+    "@rollup/plugin-typescript": "^12.3.0",
     "@semantic-release/changelog": "^6.0.3",
     "@semantic-release/commit-analyzer": "^13.0.1",
     "@semantic-release/exec": "^7.1.0",
     "@semantic-release/git": "^10.0.1",
-    "@semantic-release/github": "^12.0.0",
+    "@semantic-release/github": "^12.0.1",
     "@semantic-release/npm": "^13.1.1",
     "@semantic-release/release-notes-generator": "^14.1.0",
-    "@types/node": "^24.8.1",
-    "@vitest/coverage-v8": "^3.2.4",
-    "@vitest/ui": "^3.2.4",
+    "@types/node": "^24.10.0",
+    "@vitest/coverage-v8": "^4.0.6",
+    "@vitest/ui": "^4.0.6",
     "conventional-changelog-conventionalcommits": "^9.1.0",
-    "cspell": "^9.2.1",
+    "cspell": "^9.2.2",
     "dedent": "^1.7.0",
-    "eslint": "^9.37.0",
-    "eslint-config-typed": "^1.7.1",
+    "eslint": "9.38.0",
+    "eslint-config-typed": "^3.1.1",
     "fast-glob": "^3.3.3",
+    "jiti": "^2.6.1",
     "markdownlint": "^0.39.0",
     "markdownlint-cli2": "^0.18.1",
     "npm-run-all2": "^8.0.4",
-    "octokit-safe-types": "^1.1.1",
+    "octokit-safe-types": "^1.1.2",
     "prettier": "^3.6.2",
     "prettier-plugin-organize-imports": "^4.3.0",
     "prettier-plugin-packagejson": "^2.5.19",
@@ -120,12 +121,17 @@
     "ts-fortress": "^5.2.0",
     "ts-type-forge": "^2.3.0",
     "tslib": "^2.8.1",
+    "tsx": "^4.20.6",
     "typedoc": "^0.28.14",
     "typedoc-plugin-markdown": "^4.9.0",
     "typescript": "^5.9.3",
-    "vitest": "^3.2.4"
+    "vitest": "^4.0.6"
   },
   "peerDependencies": {
     "prettier": "^3.6.2"
+  },
+  "volta": {
+    "node": "25.0.0",
+    "npm": "11.6.2"
   }
 }

package/src/cmd/assert-repo-is-clean.mts

@@ -5,7 +5,7 @@ import { assertRepoIsClean } from '../functions/index.mjs';
 
 const cmdDef = cmd.command({
   name: 'assert-repo-is-clean-cli',
-  version: '7.7.3',
+  version: '7.8.1',
   args: {
     silent: cmd.flag({
       long: 'silent',
@@ -14,7 +14,7 @@ const cmdDef = cmd.command({
     }),
   },
   handler: (args) => {
-    main(args).catch((error) => {
+    main(args).catch((error: unknown) => {
       console.error('An error occurred:', error);
       process.exit(1);
     });

package/src/cmd/check-should-run-type-checks.mts

@@ -5,7 +5,7 @@ import { checkShouldRunTypeChecks } from '../functions/index.mjs';
 
 const cmdDef = cmd.command({
   name: 'check-should-run-type-checks-cli',
-  version: '7.7.3',
+  version: '7.8.1',
   args: {
     pathsIgnore: cmd.multioption({
       long: 'paths-ignore',
@@ -21,7 +21,7 @@ const cmdDef = cmd.command({
     }),
   },
   handler: (args) => {
-    main(args).catch((error) => {
+    main(args).catch((error: unknown) => {
       console.error('An error occurred:', error);
       process.exit(1);
     });

package/src/cmd/format-diff-from.mts

@@ -6,7 +6,7 @@ import { formatDiffFrom } from '../functions/index.mjs';
 
 const cmdDef = cmd.command({
   name: 'format-diff-from-cli',
-  version: '7.7.3',
+  version: '7.8.1',
   args: {
     base: cmd.positional({
       type: cmd.string,
@@ -50,7 +50,7 @@ const cmdDef = cmd.command({
       excludeStaged: args.excludeStaged ?? false,
       ignoreUnknown: args.ignoreUnknown ?? true,
       silent: args.silent ?? false,
-    }).catch((error) => {
+    }).catch((error: unknown) => {
       console.error('An error occurred:', error);
       process.exit(1);
     });

package/src/cmd/format-uncommitted.mts

@@ -6,7 +6,7 @@ import { formatUncommittedFiles } from '../functions/index.mjs';
 
 const cmdDef = cmd.command({
   name: 'format-uncommitted-cli',
-  version: '7.7.3',
+  version: '7.8.1',
   args: {
     excludeUntracked: cmd.flag({
       long: 'exclude-untracked',
@@ -44,7 +44,7 @@ const cmdDef = cmd.command({
       excludeStaged: args.excludeStaged ?? false,
       ignoreUnknown: args.ignoreUnknown ?? true,
       silent: args.silent ?? false,
-    }).catch((error) => {
+    }).catch((error: unknown) => {
       console.error('An error occurred:', error);
       process.exit(1);
     });

package/src/cmd/gen-index-ts.mts

@@ -2,7 +2,7 @@
 
 import * as cmd from 'cmd-ts';
 
-// eslint-disable-next-line import/no-internal-modules
+// eslint-disable-next-line import-x/no-internal-modules
 import { type InputOf, type OutputOf } from 'cmd-ts/dist/esm/from.js';
 import { expectType } from 'ts-data-forge';
 import { genIndex } from '../functions/index.mjs';
@@ -40,7 +40,7 @@ const nonEmptyArray = <T extends cmd.Type<any, any>>(
 
 const cmdDef = cmd.command({
   name: 'gen-index-ts-cli',
-  version: '7.7.3',
+  version: '7.8.1',
   args: {
     // required args
     targetDirectory: cmd.positional({
@@ -109,7 +109,7 @@ const cmdDef = cmd.command({
     expectType<typeof args.formatCommand, string | undefined>('=');
     expectType<typeof args.silent, boolean | undefined>('=');
 
-    main(args).catch((error) => {
+    main(args).catch((error: unknown) => {
       console.error('An error occurred:', error);
       process.exit(1);
     });

package/src/functions/assert-ext.mts

@@ -1,6 +1,7 @@
-import { Arr, type IMap, isString } from 'ts-data-forge';
+import { Arr, type IMap, isString, Result } from 'ts-data-forge';
 import '../node-global.mjs';
 import { assertPathExists } from './assert-path-exists.mjs';
+import { createResultAssert } from './create-result-assert.mjs';
 
 /** Configuration for directory extension checking. */
 export type CheckExtConfig = DeepReadonly<{
@@ -23,13 +24,21 @@ export type CheckExtConfig = DeepReadonly<{
   }[];
 }>;
 
+export type CheckExtError = Readonly<{
+  message: string;
+  files: readonly string[];
+}>;
+
 /**
  * Validates that all files in specified directories have the correct
- * extensions. Exits with code 1 if any files have incorrect extensions.
+ * extensions.
  *
  * @param config - Configuration specifying directories and expected extensions.
+ * @returns Result.ok when all files pass, otherwise Result.err with details.
  */
-export const assertExt = async (config: CheckExtConfig): Promise<void> => {
+export const checkExt = async (
+  config: CheckExtConfig,
+): Promise<Result<undefined, CheckExtError>> => {
   // Check all directories in parallel
   const results = await Promise.all(
     config.directories.map(async ({ path: dir, extension, ignorePatterns }) => {
@@ -49,59 +58,43 @@ export const assertExt = async (config: CheckExtConfig): Promise<void> => {
   // Collect all incorrect files
   const allIncorrectFiles: readonly string[] = results.flat();
 
-  if (allIncorrectFiles.length > 0) {
-    const generateErrorMessage = (): string => {
-      // Group directories by extension for a cleaner message
-      const extensionGroups: IMap<
-        string,
-        readonly Readonly<{
-          relativePath: string;
-          extKey: string;
-        }>[]
-      > = Arr.groupBy(
-        config.directories.map(({ path: dirPath, extension }) => {
-          const relativePath = path.relative(process.cwd(), dirPath);
-          const extKey = isString(extension)
-            ? extension
-            : extension.join(' or ');
-
-          return {
-            relativePath,
-            extKey,
-          };
-        }),
-        ({ extKey }) => extKey,
-      );
-
-      // Generate message parts for each extension
-      const messageParts = Array.from(
-        extensionGroups.entries(),
-        ([ext, dirs]) => {
-          const dirList =
-            dirs.length === 1
-              ? dirs[0]?.relativePath
-              : dirs.map((d) => d.relativePath).join(', ');
-          return `${dirList} should have ${ext} extension`;
-        },
-      );
-
-      return `All files in ${messageParts.join(' and ')}.`;
-    };
-
-    const errorMessage = [
-      'Files with incorrect extensions found:',
-      ...allIncorrectFiles.map((file) => `  - ${file}`),
-      '',
-      generateErrorMessage(),
-    ].join('\n');
-
-    echo(errorMessage);
-    process.exit(1);
+  if (allIncorrectFiles.length === 0) {
+    return Result.ok(undefined);
   }
 
-  echo('✓ All files have correct extensions');
+  const message = [
+    'Files with incorrect extensions found:',
+    ...allIncorrectFiles.map((file) => `  - ${file}`),
+    '',
+    describeExpectedExtensions(config),
+  ].join('\n');
+
+  return Result.err({
+    message,
+    files: allIncorrectFiles,
+  });
 };
 
+/**
+ * Validates that all files in specified directories have the correct
+ * extensions. Exits with code 1 if any files have incorrect extensions.
+ *
+ * @param config - Configuration specifying directories and expected extensions.
+ */
+export const assertExt = createResultAssert<
+  CheckExtConfig,
+  undefined,
+  CheckExtError
+>({
+  run: checkExt,
+  onError: (error) => {
+    echo(error.message);
+  },
+  onSuccess: () => {
+    echo('✓ All files have correct extensions');
+  },
+});
+
 /**
  * Checks if all files in a directory have the expected extension.
  *
@@ -134,3 +127,36 @@ const getFilesWithIncorrectExtension = async (
     (file) => !expectedExtensions.some((ext) => file.endsWith(ext)),
   );
 };
+
+const describeExpectedExtensions = (config: CheckExtConfig): string => {
+  // Group directories by extension for a cleaner message
+  const extensionGroups: IMap<
+    string,
+    readonly Readonly<{
+      relativePath: string;
+      extKey: string;
+    }>[]
+  > = Arr.groupBy(
+    config.directories.map(({ path: dirPath, extension }) => {
+      const relativePath = path.relative(process.cwd(), dirPath);
+      const extKey = isString(extension) ? extension : extension.join(' or ');
+
+      return {
+        relativePath,
+        extKey,
+      };
+    }),
+    ({ extKey }) => extKey,
+  );
+
+  // Generate message parts for each extension
+  const messageParts = Array.from(extensionGroups.entries(), ([ext, dirs]) => {
+    const dirList =
+      dirs.length === 1
+        ? dirs[0]?.relativePath
+        : dirs.map((d) => d.relativePath).join(', ');
+    return `${dirList} should have ${ext} extension`;
+  });
+
+  return `All files in ${messageParts.join(' and ')}.`;
+};

package/src/functions/create-result-assert.mts

@@ -0,0 +1,59 @@
+import { hasKey, isRecord, isString, Result } from 'ts-data-forge';
+import '../node-global.mjs';
+
+type ResultProducer<TConfig, TOk, TErr> = (
+  config: TConfig,
+) => Promise<Result<TOk, TErr>>;
+
+export type CreateResultAssertOptions<Config, Ok, Err> = Readonly<{
+  run: ResultProducer<Config, Ok, Err>;
+  onSuccess?: (value: Ok, config: Config) => void | Promise<void>;
+  onError?: (error: Err, config: Config) => void | Promise<void>;
+  exitCode?: number;
+}>;
+
+/**
+ * Converts a function that returns a Result into an assert-style variant that
+ * exits the process when the Result is Err. This is useful for building CLI
+ * commands that should stop execution on failure but remain composable when a
+ * Result is preferred.
+ */
+export const createResultAssert = <Config, Ok, Err>({
+  run,
+  onSuccess,
+  onError,
+  exitCode = 1,
+}: CreateResultAssertOptions<Config, Ok, Err>): ((
+  config: Config,
+) => Promise<Ok>) => {
+  const defaultOnError = (error: Err): void => {
+    if (
+      isRecord(error) &&
+      hasKey(error, 'message') &&
+      isString(error.message)
+    ) {
+      echo(error.message);
+    } else {
+      console.error(error);
+    }
+  };
+
+  return async (config: Config): Promise<Ok> => {
+    const result = await run(config);
+
+    if (Result.isErr(result)) {
+      if (onError !== undefined) {
+        await onError(result.value, config);
+      } else {
+        defaultOnError(result.value);
+      }
+      process.exit(exitCode);
+    }
+
+    if (onSuccess !== undefined) {
+      await onSuccess(result.value, config);
+    }
+
+    return result.value;
+  };
+};

package/src/functions/exec-async.mts

@@ -5,6 +5,18 @@ type ExecOptionsCustom = Readonly<{
   silent?: boolean;
 }>;
 
+type ExecOptionsWithStringEncoding = Readonly<
+  childProcess.ExecOptionsWithStringEncoding & ExecOptionsCustom
+>;
+
+type ExecOptionsWithBufferEncoding = Readonly<
+  childProcess.ExecOptionsWithBufferEncoding & ExecOptionsCustom
+>;
+
+type NormalizedExecOptions = Readonly<
+  childProcess.ExecOptions & { encoding?: BufferEncoding | 'buffer' | null }
+>;
+
 export type ExecOptions = childProcess.ExecOptions & ExecOptionsCustom;
 
 export type ExecResult<T extends string | Buffer> = Result<
@@ -23,47 +35,92 @@ export type ExecResult<T extends string | Buffer> = Result<
 export function $(
   command: string,
   // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
-  options?:
-    | ExecOptionsCustom
-    | Readonly<{ encoding: BufferEncoding } & ExecOptions>,
+  options?: ExecOptionsWithStringEncoding,
 ): Promise<ExecResult<string>>;
 
 export function $(
   command: string,
   // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
-  options?: Readonly<{ encoding: 'buffer' | null } & ExecOptions>,
+  options: ExecOptionsWithBufferEncoding,
 ): Promise<ExecResult<Buffer>>;
 
+export function $<
+  TOptions extends
+    | ExecOptionsWithBufferEncoding
+    | ExecOptionsWithStringEncoding
+    | undefined = undefined,
+>(
+  command: string,
+  options?: TOptions,
+): Promise<
+  ExecResult<TOptions extends ExecOptionsWithBufferEncoding ? Buffer : string>
+>;
+
 export function $(
   command: string,
   // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
-  options?: Readonly<
-    { encoding?: BufferEncoding | 'buffer' | null } & ExecOptions
-  >,
+  options?: ExecOptionsWithStringEncoding | ExecOptionsWithBufferEncoding,
 ): Promise<ExecResult<string | Buffer>> {
   const { silent = false, ...restOptions } = options ?? {};
+  const normalizedOptions: NormalizedExecOptions = restOptions;
 
   if (!silent) {
     echo(`$ ${command}`);
   }
 
   return new Promise((resolve) => {
-    // eslint-disable-next-line security/detect-child-process
-    childProcess.exec(command, restOptions, (error, stdout, stderr) => {
+    const handleResult = <T extends string | Buffer>(
+      // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
+      error: childProcess.ExecException | null,
+      stdout: T,
+      stderr: T,
+    ): void => {
       if (!silent) {
-        if (stdout !== '') {
+        if (!isEmpty(stdout)) {
           echo(stdout);
         }
-        if (stderr !== '') {
+        if (!isEmpty(stderr)) {
           console.error(stderr);
         }
       }
 
       if (error !== null) {
         resolve(Result.err(error));
-      } else {
-        resolve(Result.ok({ stdout, stderr }));
+        return;
       }
-    });
+
+      resolve(
+        Result.ok<Readonly<{ stdout: T; stderr: T }>>({ stdout, stderr }),
+      );
+    };
+
+    const encoding = normalizedOptions.encoding;
+
+    if (encoding === 'buffer' || encoding === null) {
+      // eslint-disable-next-line security/detect-child-process
+      childProcess.exec(
+        command,
+        // eslint-disable-next-line total-functions/no-unsafe-type-assertion
+        normalizedOptions as childProcess.ExecOptionsWithBufferEncoding,
+        (error, stdout, stderr) => {
+          handleResult(error, stdout, stderr);
+        },
+      );
+      return;
+    }
+
+    // eslint-disable-next-line security/detect-child-process
+    childProcess.exec(
+      command,
+      // eslint-disable-next-line total-functions/no-unsafe-type-assertion
+      normalizedOptions as childProcess.ExecOptionsWithStringEncoding,
+      (error, stdout, stderr) => {
+        handleResult(error, stdout, stderr);
+      },
+    );
   });
 }
+
+// eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
+const isEmpty = (value: string | Buffer): boolean =>
+  typeof value === 'string' ? value === '' : value.length === 0;

package/src/functions/exec-async.test.mts

@@ -368,8 +368,8 @@ describe('exec-async', () => {
       // Type check for native exec with buffer encoding
       exec('echo "test"', { encoding: 'buffer' }, (error, stdout, stderr) => {
         expectType<ExecException | null, typeof error>('=');
-        expectType<Buffer, typeof stdout>('=');
-        expectType<Buffer, typeof stderr>('=');
+        expectType<Buffer, typeof stdout>('>=');
+        expectType<Buffer, typeof stderr>('>=');
       });
 
       // The $ function should produce the same types wrapped in Result (suppressed for clean output)
@@ -381,15 +381,15 @@ describe('exec-async', () => {
         Promise<
           Result<Readonly<{ stdout: Buffer; stderr: Buffer }>, ExecException>
         >
-      >('=');
+      >('~=');
     });
 
     test('should match exec callback types for null encoding', () => {
       // Type check for native exec with null encoding
       exec('echo "test"', { encoding: null }, (error, stdout, stderr) => {
         expectType<ExecException | null, typeof error>('=');
-        expectType<Buffer, typeof stdout>('=');
-        expectType<Buffer, typeof stderr>('=');
+        expectType<Buffer, typeof stdout>('>=');
+        expectType<Buffer, typeof stderr>('>=');
       });
 
       // The $ function should produce the same types wrapped in Result (suppressed for clean output)

package/src/functions/format.mts

@@ -1,6 +1,6 @@
 import { type ExecException } from 'node:child_process';
 import * as prettier from 'prettier';
-import { Arr, isNotUndefined, Result } from 'ts-data-forge';
+import { Arr, isNotUndefined, pipe, Result } from 'ts-data-forge';
 import '../node-global.mjs';
 import {
   getDiffFrom,
@@ -127,21 +127,28 @@ const defaultIgnoreFn = (filePath: string): boolean => {
     ignoreFiles.has(filename) ||
     filename.startsWith('.env') ||
     ignoreExtensions.some((ext) => filePath.endsWith(ext)) ||
-    ignoreDirs.some((dir) => filename.startsWith(dir))
+    pipe(filePath.split(path.sep)).map((pathSegments) =>
+      pathSegments.some((segment) => ignoreDirs.includes(segment)),
+    ).value
   );
 };
 
 const ignoreFiles: ReadonlySet<string> = new Set([
   '.DS_Store',
   'package-lock.json',
+  'yarn.lock',
+  'pnpm-lock.yaml',
   'LICENSE',
   '.prettierignore',
   '.editorconfig',
   '.gitignore',
   '.npmignore',
+  '.envrc',
+  '.nvmrc',
+  '.npmrc',
 ]);
 
-const ignoreExtensions: readonly string[] = [
+const ignoreExtensions: readonly `.${string}`[] = [
   '.svg',
   '.png',
   '.jpg',
@@ -171,6 +178,7 @@ const ignoreDirs: readonly string[] = [
   '.cache',
   '.vscode',
   '.yarn',
+  '.wireit',
 ] as const;
 
 /**

package/src/functions/index.mts

@@ -1,6 +1,7 @@
 export * from './assert-ext.mjs';
 export * from './assert-path-exists.mjs';
 export * from './assert-repo-is-clean.mjs';
+export * from './create-result-assert.mjs';
 export * from './diff.mjs';
 export * from './exec-async.mjs';
 export * from './format.mjs';

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

@@ -57,7 +57,7 @@ export const executeParallel = async (
 
     const wrappedPromise = promise
       // eslint-disable-next-line @typescript-eslint/no-loop-func
-      .catch((error) => {
+      .catch((error: unknown) => {
         mut_failed = true;
         throw error; // Re-throw to ensure fail-fast propagation
       })

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

@@ -1,4 +1,5 @@
 /* eslint-disable vitest/no-restricted-vi-methods */
+import { type MockInstance } from 'vitest';
 import '../../node-global.mjs';
 import { executeStages } from './execute-parallel.mjs';
 import { getWorkspacePackages } from './get-workspace-packages.mjs';
@@ -16,9 +17,9 @@ vi.mock('./get-workspace-packages.mjs', () => ({
 
 describe('runCmdInStagesAcrossWorkspaces', () => {
   type MockedSpies = Readonly<{
-    consoleLogSpy: ReturnType<typeof vi.spyOn>;
-    consoleErrorSpy: ReturnType<typeof vi.spyOn>;
-    processExitSpy: ReturnType<typeof vi.spyOn>;
+    consoleLogSpy: MockInstance<typeof console.log>;
+    consoleErrorSpy: MockInstance<typeof console.error>;
+    processExitSpy: MockInstance<typeof process.exit>;
   }>;
 
   const setupSpies = (): MockedSpies => {
@@ -30,14 +31,10 @@ describe('runCmdInStagesAcrossWorkspaces', () => {
       .spyOn(console, 'error')
       .mockImplementation((): void => {});
 
-    // eslint-disable-next-line total-functions/no-unsafe-type-assertion
     const processExitSpy = vi
       .spyOn(process, 'exit')
-
       // eslint-disable-next-line total-functions/no-unsafe-type-assertion
-      .mockImplementation((): never => undefined as never) as ReturnType<
-      typeof vi.spyOn
-    >;
+      .mockImplementation((): never => undefined as never);
 
     return { consoleLogSpy, consoleErrorSpy, processExitSpy };
   };

package/src/node-global.mts

@@ -1,8 +1,9 @@
-/* eslint-disable import/no-internal-modules */
+/* eslint-disable import-x/no-internal-modules */
 import glob_ from 'fast-glob';
 import * as fs_ from 'node:fs/promises';
 import * as os_ from 'node:os';
 import * as path_ from 'node:path';
+import { chdir as chdir_ } from 'node:process';
 import { Result as Result_ } from 'ts-data-forge';
 import { $ as $_ } from './functions/exec-async.mjs';
 import { isDirectlyExecuted as isDirectlyExecuted_ } from './functions/is-directly-executed.mjs';
@@ -19,6 +20,7 @@ const globalsDef = {
   $: $_,
   Result: Result_,
   echo: console.log,
+  cd: chdir_,
   isDirectlyExecuted: isDirectlyExecuted_,
 } as const;
 
@@ -35,5 +37,6 @@ declare global {
   const Result: typeof Result_;
   type Result<S, E> = Result_<S, E>;
   const echo: typeof console.log;
+  const cd: typeof chdir_;
   const isDirectlyExecuted: typeof isDirectlyExecuted_;
 }