ts-repo-utils 5.3.0 → 6.0.1

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

@@ -0,0 +1,147 @@
+#!/usr/bin/env -S npx tsx
+
+import * as cmd from 'cmd-ts';
+
+// eslint-disable-next-line import/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';
+
+type Ext = `.${string}`;
+
+const extensionType = cmd.extendType(cmd.string, {
+  from: (s) => {
+    if (!s.startsWith('.')) {
+      throw new Error(`ext should start with '.'`);
+    }
+    // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion
+    return Promise.resolve(s as Ext);
+  },
+});
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+const nonEmptyArray = <T extends cmd.Type<any, any>>(
+  t: T,
+  commandName: string,
+): cmd.Type<InputOf<T>[], NonEmptyArray<OutputOf<T>>> =>
+  cmd.extendType(cmd.array(t), {
+    from: (arr) => {
+      if (arr.length === 0) {
+        throw new Error(
+          `No value provided for --${commandName}. At least one value is required.`,
+        );
+      }
+      // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion
+      return Promise.resolve(arr as unknown as NonEmptyArray<OutputOf<T>>);
+    },
+  });
+
+const cmdDef = cmd.command({
+  name: 'gen-index-ts-cli',
+  version: '6.0.1',
+  args: {
+    // required args
+    targetDirectory: cmd.positional({
+      type: cmd.string,
+      displayName: 'target-directory',
+      description:
+        'Directory where the index file will be generated  (Comma-separated list can be used)',
+    }),
+
+    targetExtensions: cmd.multioption({
+      long: 'target-ext',
+      type: nonEmptyArray(extensionType, 'target-ext'),
+      description: 'File extensions to include in the index file',
+    }),
+    indexFileExtension: cmd.option({
+      long: 'index-ext',
+      type: extensionType,
+      description: 'Extension of the index file to be generated',
+    }),
+    exportStatementExtension: cmd.option({
+      long: 'export-ext',
+      type: cmd.union([
+        extensionType,
+        cmd.extendType(cmd.string, {
+          from: (s) => {
+            if (s !== 'none') {
+              throw new Error(
+                `export-ext should be 'none' or a valid extension`,
+              );
+            }
+            return Promise.resolve('none' as const);
+          },
+        }),
+      ]),
+      description: 'Extension of the export statements in the index file',
+    }),
+
+    // optional args
+    exclude: cmd.multioption({
+      long: 'exclude',
+      type: cmd.optional(cmd.array(cmd.string)),
+      description:
+        'Glob patterns of files to exclude from the index file (e.g., "*.d.mts", "*.test.mts")',
+    }),
+    formatCommand: cmd.option({
+      long: 'fmt',
+      type: cmd.optional(cmd.string),
+      description:
+        'Command to format after generating the index file (e.g., "npm run fmt")',
+    }),
+    silent: cmd.flag({
+      long: 'silent',
+      type: cmd.optional(cmd.boolean),
+      description: 'If true, suppresses output messages (default: false)',
+    }),
+  },
+  handler: (args) => {
+    console.log(args);
+
+    expectType<typeof args.targetDirectory, string>('=');
+    expectType<typeof args.targetExtensions, NonEmptyArray<Ext>>('=');
+    expectType<typeof args.exportStatementExtension, Ext | 'none'>('=');
+    expectType<typeof args.indexFileExtension, Ext>('=');
+
+    expectType<typeof args.exclude, string[] | undefined>('=');
+    expectType<typeof args.formatCommand, string | undefined>('=');
+    expectType<typeof args.silent, boolean | undefined>('=');
+
+    main(args).catch((error) => {
+      console.error('An error occurred:', error);
+      process.exit(1);
+    });
+  },
+});
+
+const main = async ({
+  targetDirectory,
+  targetExtensions,
+  exportStatementExtension,
+  indexFileExtension,
+  exclude,
+  formatCommand,
+  silent,
+}: Readonly<{
+  targetDirectory: string;
+  targetExtensions: readonly Ext[];
+  exportStatementExtension: Ext | 'none';
+  indexFileExtension: Ext;
+  exclude?: readonly string[] | undefined;
+  formatCommand?: string | undefined;
+  silent?: boolean | undefined;
+}>): Promise<void> => {
+  await genIndex({
+    targetDirectory: targetDirectory.includes(',')
+      ? targetDirectory.split(',').map((dir) => dir.trim())
+      : targetDirectory,
+    exportStatementExtension,
+    targetExtensions,
+    exclude,
+    indexFileExtension,
+    formatCommand,
+    silent,
+  });
+};
+
+await cmd.run(cmdDef, process.argv.slice(2));

package/src/functions/gen-index.mts

@@ -10,7 +10,8 @@ export type GenIndexConfig = DeepReadonly<{
 
   /**
    * Glob patterns of files or predicate function to exclude from exports
-   * (default: excludes `'**\/*.{test,spec}.?(c|m)[jt]s?(x)'`)
+   * (default: excludes `'**\/*.{test,spec}.?(c|m)[jt]s?(x)'` and
+   * `'**\/*.d.?(c|m)ts'`)
    */
   exclude?:
     | readonly string[]
@@ -22,22 +23,14 @@ export type GenIndexConfig = DeepReadonly<{
         }>,
       ) => 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']) */
-  sourceExtensions?: readonly `.${string}`[];
+  targetExtensions?: readonly `.${string}`[];
 
   /** File extension of index files to generate (default: '.ts') */
-  indexExtension?: `.${string}`;
+  indexFileExtension?: `.${string}`;
 
   /** File extension to use in export statements (default: '.js') */
-  exportExtension?: `.${string}` | 'none';
+  exportStatementExtension?: `.${string}` | 'none';
 
   /** Command to run for formatting generated files (optional) */
   formatCommand?: string;
@@ -46,6 +39,16 @@ export type GenIndexConfig = DeepReadonly<{
   silent?: boolean;
 }>;
 
+const defaultConfig = {
+  exclude: ['**/*.{test,spec}.?(c|m)[jt]s?(x)', '**/*.d.?(c|m)ts'],
+  targetExtensions: ['.ts', '.tsx'],
+  indexFileExtension: '.ts',
+  exportStatementExtension: '.js', // For ESM imports, .mts resolves to .mjs
+  silent: false,
+} as const satisfies Required<
+  StrictOmit<GenIndexConfig, 'targetDirectory' | 'formatCommand'>
+>;
+
 type GenIndexConfigInternal = DeepReadonly<{
   formatCommand: string | undefined;
   targetDirectory: ISet<string>;
@@ -56,9 +59,9 @@ type GenIndexConfigInternal = DeepReadonly<{
       fileName: string;
     }>,
   ) => boolean;
-  sourceExtensions: ISet<`.${string}`>;
-  indexExtension: `.${string}`;
-  exportExtension: `.${string}` | 'none';
+  targetExtensions: ISet<`.${string}`>;
+  indexFileExtension: `.${string}`;
+  exportStatementExtension: `.${string}` | 'none';
   silent: boolean;
 }>;
 
@@ -117,8 +120,11 @@ export const genIndex = async (config: GenIndexConfig): Promise<void> => {
 };
 
 const fillConfig = (config: GenIndexConfig): GenIndexConfigInternal => {
-  const sourceExtensions = config.sourceExtensions ?? ['.ts'];
-  const exportExtension = config.exportExtension ?? '.js'; // For ESM imports, .mts resolves to .mjs
+  const targetExtensions =
+    config.targetExtensions ?? defaultConfig.targetExtensions;
+
+  const exportExtension =
+    config.exportStatementExtension ?? defaultConfig.exportStatementExtension;
 
   return {
     formatCommand: config.formatCommand,
@@ -127,8 +133,7 @@ const fillConfig = (config: GenIndexConfig): GenIndexConfigInternal => {
         ? [config.targetDirectory]
         : config.targetDirectory,
     ),
-    // eslint-disable-next-line @typescript-eslint/no-deprecated
-    exclude: pipe(config.exclude ?? config.excludePatterns).map((exclude) =>
+    exclude: pipe(config.exclude).map((exclude) =>
       typeof exclude === 'function'
         ? exclude
         : pipe(
@@ -137,7 +142,7 @@ const fillConfig = (config: GenIndexConfig): GenIndexConfigInternal => {
                 if (exclude !== undefined && Array.isArray(exclude)) {
                   yield* exclude;
                 }
-                yield '**/*.{test,spec}.?(c|m)[jt]s?(x)';
+                yield* defaultConfig.exclude;
               }),
             ),
           ).map(
@@ -162,10 +167,11 @@ const fillConfig = (config: GenIndexConfig): GenIndexConfigInternal => {
               },
           ).value,
     ).value,
-    sourceExtensions: ISet.create(sourceExtensions),
-    indexExtension: config.indexExtension ?? '.ts',
-    exportExtension,
-    silent: config.silent ?? false,
+    targetExtensions: ISet.create(targetExtensions),
+    indexFileExtension:
+      config.indexFileExtension ?? defaultConfig.indexFileExtension,
+    exportStatementExtension: exportExtension,
+    silent: config.silent ?? defaultConfig.silent,
   };
 };
 
@@ -229,7 +235,7 @@ const generateIndexFileForDir = async (
       config,
     );
 
-    const indexPath = path.join(dirPath, `index${config.indexExtension}`);
+    const indexPath = path.join(dirPath, `index${config.indexFileExtension}`);
 
     await fs.writeFile(indexPath, indexContent);
     echo(`Generated: ${path.relative(process.cwd(), indexPath)}`);
@@ -269,7 +275,7 @@ const shouldExportFile = ({
   const ext = path.extname(fileName);
 
   // Must have the correct source extension
-  if (!config.sourceExtensions.has(ext)) {
+  if (!config.targetExtensions.has(ext)) {
     return false;
   }
 
@@ -328,16 +334,16 @@ const generateIndexContent = (
 ): string => {
   const exportStatements = [
     ...subDirectories.map((subDir) =>
-      config.exportExtension === 'none'
+      config.exportStatementExtension === 'none'
         ? `export * from "./${subDir}";`
-        : `export * from "./${subDir}/index${config.exportExtension}";`,
+        : `export * from "./${subDir}/index${config.exportStatementExtension}";`,
     ),
     ...filesToExport.map((file) => {
       const fileNameWithoutExt = path.basename(file, path.extname(file));
 
-      return config.exportExtension === 'none'
+      return config.exportStatementExtension === 'none'
         ? `export * from "./${fileNameWithoutExt}";`
-        : `export * from "./${fileNameWithoutExt}${config.exportExtension}";`;
+        : `export * from "./${fileNameWithoutExt}${config.exportStatementExtension}";`;
     }),
   ];
 

package/src/functions/should-run.mts

@@ -1,47 +1,112 @@
-import { pipe, Result } from 'ts-data-forge';
+import { Result } from 'ts-data-forge';
 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 a base
+ * branch. Skips type checks if all changed files match the ignored patterns.
  *
- * Ignored file patterns:
+ * This function is typically used in CI/CD pipelines to determine whether
+ * expensive type checking operations should be performed. If all changed files
+ * are documentation, configuration, or other non-TypeScript files, type checks
+ * can be safely skipped to improve build performance.
  *
- * - '.cspell.json'
- * - '**.md'
- * - '**.txt'
- * - 'docs/**'
+ * @example
+ *   ```typescript
+ *   // Use default settings (compare against origin/main, ignore docs/md/txt files)
+ *   await checkShouldRunTypeChecks();
  *
- * @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.
+ *   // Custom ignore patterns
+ *   await checkShouldRunTypeChecks({
+ *     pathsIgnore: ['.eslintrc.json', 'docs/', '**.md', 'scripts/'],
+ *   });
+ *
+ *   // Custom base branch
+ *   await checkShouldRunTypeChecks({
+ *     baseBranch: 'origin/develop',
+ *   });
+ *   ```;
+ *
+ * @example
+ *   GitHub Actions usage
+ *   ```yaml
+ *   - name: Check if type checks should run
+ *   id: check_diff
+ *   run: npx check-should-run-type-checks
+ *
+ *   - name: Run type checks
+ *   if: steps.check_diff.outputs.should_run == 'true'
+ *   run: npm run type-check
+ *   ```
+ *
+ * @param options - Configuration options
+ * @param options.pathsIgnore - Array of patterns to ignore when determining if
+ *   type checks should run. Supports three pattern types:
+ *
+ *   - **Exact file matches**: e.g., `.cspell.json` matches only that file
+ *   - **Directory prefixes**: e.g., `docs/` matches any file in docs directory
+ *   - **File extensions**: e.g., `**.md` matches any markdown file Defaults to:
+ *       `['LICENSE', '.editorconfig', '.gitignore', '.cspell.json',
+ *       '.markdownlint-cli2.mjs', '.npmignore', '.prettierignore',
+ *       '.prettierrc', 'docs/', '**.md', '**.txt']`
+ *
+ * @param options.baseBranch - Base branch to compare against for determining
+ *   changed files. Defaults to `'origin/main'`
+ * @returns A promise that resolves when the check is complete. The function
+ *   will set the GITHUB_OUTPUT environment variable with `should_run=true` or
+ *   `should_run=false` if running in GitHub Actions environment.
  */
-export const checkShouldRunTypeChecks = async (): Promise<void> => {
-  // paths-ignore:
-  //   - '.cspell.json'
-  //   - '**.md'
-  //   - '**.txt'
-  //   - 'docs/**'
+export const checkShouldRunTypeChecks = async (
+  options?: Readonly<{
+    pathsIgnore?: readonly string[];
+    baseBranch?: string;
+  }>,
+): Promise<void> => {
+  const pathsIgnore = options?.pathsIgnore ?? [
+    'LICENSE',
+    '.editorconfig',
+    '.gitignore',
+    '.cspell.json',
+    '.markdownlint-cli2.mjs',
+    '.npmignore',
+    '.prettierignore',
+    '.prettierrc',
+    'docs/',
+    '**.md',
+    '**.txt',
+  ];
+
+  const baseBranch = options?.baseBranch ?? 'origin/main';
 
   const GITHUB_OUTPUT = process.env['GITHUB_OUTPUT'];
 
-  const files = await getDiffFrom('origin/main');
+  const files = await getDiffFrom(baseBranch);
 
   if (Result.isErr(files)) {
     console.error('Error getting diff:', files.value);
     process.exit(1);
   }
 
-  const shouldRunTsChecks: boolean = !files.value.every(
-    (file) =>
-      file === '.cspell.json' ||
-      file.startsWith('docs/') ||
-      pipe(path.basename(file)).map(
-        (filename) => filename.endsWith('.md') || filename.endsWith('.txt'),
-      ).value,
+  const shouldRunTsChecks: boolean = !files.value.every((file) =>
+    pathsIgnore.some((pattern) => {
+      // Exact file match
+      if (pattern === file) {
+        return true;
+      }
+
+      // Directory prefix match (pattern ends with '/')
+      if (pattern.endsWith('/') && file.startsWith(pattern)) {
+        return true;
+      }
+
+      // File extension pattern match (pattern starts with '**.')
+      if (pattern.startsWith('**.')) {
+        const extension = pattern.slice(2); // Remove '**'
+        return path.basename(file).endsWith(extension);
+      }
+
+      return false;
+    }),
   );
 
   if (GITHUB_OUTPUT !== undefined) {

package/src/index.mts

@@ -1,3 +1 @@
-/// <reference types="ts-type-forge" />
-
 export * from './functions/index.mjs';