ts-repo-utils 7.3.0 → 7.4.0

package/README.md

@@ -236,6 +236,39 @@ type Ret = Promise<
 
 ### Script Execution Utilities
 
+#### `isDirectlyExecuted(fileUrl: string): boolean`
+
+Determines whether a script is being executed directly via CLI or imported as a module. This is useful for creating scripts that can both be imported as libraries and executed directly.
+
+```typescript
+import { isDirectlyExecuted } from 'ts-repo-utils';
+
+// or
+// import "ts-repo-utils"; // isDirectlyExecuted is globally defined in ts-repo-utils
+
+// calculator.mjs
+export const add = (a: number, b: number): number => a + b;
+export const multiply = (a: number, b: number): number => a * b;
+
+// Only run main logic when executed directly: node calculator.mjs (or tsx calculator.mts)
+// When imported elsewhere, only the functions are available
+if (isDirectlyExecuted(import.meta.url)) {
+    console.log('Calculator CLI');
+    console.log('2 + 3 =', add(2, 3));
+    console.log('4 × 5 =', multiply(4, 5));
+}
+```
+
+When executed directly (`node calculator.mjs`), it runs the main function and prints the results. When imported (`import { add } from './calculator.mjs'`), it only provides the functions without executing the main logic.
+
+NOTE: If you use [tsx](https://www.npmjs.com/package/tsx) or [ts-node](https://www.npmjs.com/package/ts-node), run your scripts with the extension `.(m)ts` instead of `.(m)js` so that `isDirectlyExecuted` can correctly determine if the script is executed directly.
+
+**Use Cases:**
+
+- Creating CLI tools that can also be used as libraries
+- Preventing automatic execution when a file is imported
+- Running initialization code only during direct execution
+
 ### Path and File System Utilities
 
 #### `pathExists(filePath: string): Promise<boolean>`
@@ -361,6 +394,39 @@ type Ret = Result<
 >;
 ```
 
+#### Build Optimization Utilities
+
+##### `checkShouldRunTypeChecks(options?): Promise<boolean>`
+
+Checks whether TypeScript type checks should run based on file changes from the base branch. Optimizes CI/CD pipelines by skipping type checks when only non-TypeScript files have changed.
+(Function version of the `check-should-run-type-checks` command)
+
+```typescript
+import { checkShouldRunTypeChecks } from 'ts-repo-utils';
+
+// Use default settings (compare against origin/main)
+const shouldRun = await checkShouldRunTypeChecks();
+
+if (shouldRun) {
+    await $('npm run type-check');
+}
+
+// Custom ignore patterns and base branch
+const shouldRun2 = await checkShouldRunTypeChecks({
+    pathsIgnore: ['.eslintrc.json', 'docs/', '**.md', 'scripts/'],
+    baseBranch: 'origin/develop',
+});
+```
+
+**Options:**
+
+- `pathsIgnore?` - Patterns to ignore when checking if type checks should run:
+    - Exact file matches: `.cspell.json`
+    - Directory prefixes: `docs/` (matches any file in docs directory)
+    - File extensions: `**.md` (matches any markdown file)
+    - Default: `['LICENSE', '.editorconfig', '.gitignore', '.cspell.json', '.markdownlint-cli2.mjs', '.npmignore', '.prettierignore', '.prettierrc', 'docs/', '**.md', '**.txt']`
+- `baseBranch?` - Base branch to compare against (default: `origin/main`)
+
 ### Code Formatting Utilities
 
 #### `formatFilesGlob(pathGlob: string, options?): Promise<Result<undefined, unknown>>`
@@ -668,6 +734,10 @@ const configJson: string = await fs.readFile('./config.json', {
 });
 
 const files: readonly string[] = await glob('**/*.ts');
+
+if (isDirectlyExecuted(import.meta.url)) {
+    echo('Running as CLI');
+}
 ```
 
 - `$` - The command execution utility described above.
@@ -675,6 +745,7 @@ const files: readonly string[] = await glob('**/*.ts');
 - `path` - `node:path`
 - `fs` - `node:fs/promises`
 - `glob` - `fast-glob`
+- `isDirectlyExecuted` - The script execution utility described above.
 
 ## Common Patterns
 

package/dist/cmd/assert-repo-is-clean.mjs

@@ -11,7 +11,7 @@ import 'child_process';
 
 const cmdDef = cmd.command({
     name: 'assert-repo-is-clean-cli',
-    version: '7.3.0',
+    version: '7.4.0',
     args: {
         silent: cmd.flag({
             long: 'silent',

package/dist/cmd/check-should-run-type-checks.mjs

@@ -11,7 +11,7 @@ import 'child_process';
 
 const cmdDef = cmd.command({
     name: 'check-should-run-type-checks-cli',
-    version: '7.3.0',
+    version: '7.4.0',
     args: {
         pathsIgnore: cmd.multioption({
             long: 'paths-ignore',

package/dist/cmd/format-diff-from.mjs

@@ -10,7 +10,7 @@ import 'child_process';
 
 const cmdDef = cmd.command({
     name: 'format-diff-from-cli',
-    version: '7.3.0',
+    version: '7.4.0',
     args: {
         base: cmd.positional({
             type: cmd.string,

package/dist/cmd/format-uncommitted.mjs

@@ -10,7 +10,7 @@ import 'child_process';
 
 const cmdDef = cmd.command({
     name: 'format-uncommitted-cli',
-    version: '7.3.0',
+    version: '7.4.0',
     args: {
         excludeUntracked: cmd.flag({
             long: 'exclude-untracked',

package/dist/cmd/gen-index-ts.mjs

@@ -29,7 +29,7 @@ const nonEmptyArray = (t, commandName) => cmd.extendType(cmd.array(t), {
 });
 const cmdDef = cmd.command({
     name: 'gen-index-ts-cli',
-    version: '7.3.0',
+    version: '7.4.0',
     args: {
         // required args
         targetDirectory: cmd.positional({

package/dist/functions/should-run.d.mts

@@ -56,5 +56,5 @@ import '../node-global.mjs';
 export declare const checkShouldRunTypeChecks: (options?: Readonly<{
     pathsIgnore?: readonly string[];
     baseBranch?: string;
-}>) => Promise<void>;
+}>) => Promise<boolean>;
 //# sourceMappingURL=should-run.d.mts.map

package/dist/functions/should-run.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"should-run.d.mts","sourceRoot":"","sources":["../../src/functions/should-run.mts"],"names":[],"mappings":"AACA,OAAO,oBAAoB,CAAC;AAG5B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqDG;AACH,eAAO,MAAM,wBAAwB,GACnC,UAAU,QAAQ,CAAC;IACjB,WAAW,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAChC,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB,CAAC,KACD,OAAO,CAAC,IAAI,CAmDd,CAAC"}
+{"version":3,"file":"should-run.d.mts","sourceRoot":"","sources":["../../src/functions/should-run.mts"],"names":[],"mappings":"AACA,OAAO,oBAAoB,CAAC;AAG5B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqDG;AACH,eAAO,MAAM,wBAAwB,GACnC,UAAU,QAAQ,CAAC;IACjB,WAAW,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAChC,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB,CAAC,KACD,OAAO,CAAC,OAAO,CAqDjB,CAAC"}

package/dist/functions/should-run.mjs

@@ -96,6 +96,7 @@ const checkShouldRunTypeChecks = async (options) => {
     if (GITHUB_OUTPUT !== undefined) {
         await fs.appendFile(GITHUB_OUTPUT, `should_run=${shouldRunTsChecks}\n`);
     }
+    return shouldRunTsChecks;
 };
 
 export { checkShouldRunTypeChecks };

package/dist/functions/should-run.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"should-run.mjs","sources":["../../src/functions/should-run.mts"],"sourcesContent":[null],"names":[],"mappings":";;;;AAIA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAqDG;MACU,wBAAwB,GAAG,OACtC,OAGE,KACe;AACjB,IAAA,MAAM,WAAW,GAAG,OAAO,EAAE,WAAW,IAAI;QAC1C,SAAS;QACT,eAAe;QACf,YAAY;QACZ,cAAc;QACd,wBAAwB;QACxB,YAAY;QACZ,iBAAiB;QACjB,aAAa;QACb,OAAO;QACP,OAAO;QACP,QAAQ;KACT;AAED,IAAA,MAAM,UAAU,GAAG,OAAO,EAAE,UAAU,IAAI,aAAa;IAEvD,MAAM,aAAa,GAAG,OAAO,CAAC,GAAG,CAAC,eAAe,CAAC;AAElD,IAAA,MAAM,KAAK,GAAG,MAAM,WAAW,CAAC,UAAU,CAAC;AAE3C,IAAA,IAAI,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC,EAAE;QACvB,OAAO,CAAC,KAAK,CAAC,qBAAqB,EAAE,KAAK,CAAC,KAAK,CAAC;AACjD,QAAA,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC;IACjB;IAEA,MAAM,iBAAiB,GAAY,CAAC,KAAK,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,IAAI,KACzD,WAAW,CAAC,IAAI,CAAC,CAAC,OAAO,KAAI;;AAE3B,QAAA,IAAI,OAAO,KAAK,IAAI,EAAE;AACpB,YAAA,OAAO,IAAI;QACb;;AAGA,QAAA,IAAI,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,IAAI,CAAC,UAAU,CAAC,OAAO,CAAC,EAAE;AACrD,YAAA,OAAO,IAAI;QACb;;AAGA,QAAA,IAAI,OAAO,CAAC,UAAU,CAAC,KAAK,CAAC,EAAE;YAC7B,MAAM,SAAS,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;YACnC,OAAO,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,QAAQ,CAAC,SAAS,CAAC;QAChD;AAEA,QAAA,OAAO,KAAK;IACd,CAAC,CAAC,CACH;AAED,IAAA,IAAI,aAAa,KAAK,SAAS,EAAE;QAC/B,MAAM,EAAE,CAAC,UAAU,CAAC,aAAa,EAAE,CAAA,WAAA,EAAc,iBAAiB,CAAA,EAAA,CAAI,CAAC;IACzE;AACF;;;;"}
+{"version":3,"file":"should-run.mjs","sources":["../../src/functions/should-run.mts"],"sourcesContent":[null],"names":[],"mappings":";;;;AAIA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAqDG;MACU,wBAAwB,GAAG,OACtC,OAGE,KACkB;AACpB,IAAA,MAAM,WAAW,GAAG,OAAO,EAAE,WAAW,IAAI;QAC1C,SAAS;QACT,eAAe;QACf,YAAY;QACZ,cAAc;QACd,wBAAwB;QACxB,YAAY;QACZ,iBAAiB;QACjB,aAAa;QACb,OAAO;QACP,OAAO;QACP,QAAQ;KACT;AAED,IAAA,MAAM,UAAU,GAAG,OAAO,EAAE,UAAU,IAAI,aAAa;IAEvD,MAAM,aAAa,GAAG,OAAO,CAAC,GAAG,CAAC,eAAe,CAAC;AAElD,IAAA,MAAM,KAAK,GAAG,MAAM,WAAW,CAAC,UAAU,CAAC;AAE3C,IAAA,IAAI,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC,EAAE;QACvB,OAAO,CAAC,KAAK,CAAC,qBAAqB,EAAE,KAAK,CAAC,KAAK,CAAC;AACjD,QAAA,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC;IACjB;IAEA,MAAM,iBAAiB,GAAY,CAAC,KAAK,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,IAAI,KACzD,WAAW,CAAC,IAAI,CAAC,CAAC,OAAO,KAAI;;AAE3B,QAAA,IAAI,OAAO,KAAK,IAAI,EAAE;AACpB,YAAA,OAAO,IAAI;QACb;;AAGA,QAAA,IAAI,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,IAAI,CAAC,UAAU,CAAC,OAAO,CAAC,EAAE;AACrD,YAAA,OAAO,IAAI;QACb;;AAGA,QAAA,IAAI,OAAO,CAAC,UAAU,CAAC,KAAK,CAAC,EAAE;YAC7B,MAAM,SAAS,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;YACnC,OAAO,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,QAAQ,CAAC,SAAS,CAAC;QAChD;AAEA,QAAA,OAAO,KAAK;IACd,CAAC,CAAC,CACH;AAED,IAAA,IAAI,aAAa,KAAK,SAAS,EAAE;QAC/B,MAAM,EAAE,CAAC,UAAU,CAAC,aAAa,EAAE,CAAA,WAAA,EAAc,iBAAiB,CAAA,EAAA,CAAI,CAAC;IACzE;AAEA,IAAA,OAAO,iBAAiB;AAC1B;;;;"}

package/dist/node-global.d.mts

@@ -2,11 +2,13 @@ import { default as glob_ } from 'fast-glob';
 import * as fs_ from 'node:fs/promises';
 import * as path_ from 'node:path';
 import { $ as $_ } from './functions/exec-async.mjs';
+import { isDirectlyExecuted as isDirectlyExecuted_ } from './functions/is-directly-executed.mjs';
 declare global {
     const $: typeof $_;
     const echo: typeof console.log;
     const path: typeof path_;
     const fs: typeof fs_;
     const glob: typeof glob_;
+    const isDirectlyExecuted: typeof isDirectlyExecuted_;
 }
 //# sourceMappingURL=node-global.d.mts.map

package/dist/node-global.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"node-global.d.mts","sourceRoot":"","sources":["../src/node-global.mts"],"names":[],"mappings":"AACA,OAAO,EAAE,OAAO,IAAI,KAAK,EAAE,MAAM,WAAW,CAAC;AAC7C,OAAO,KAAK,GAAG,MAAM,kBAAkB,CAAC;AACxC,OAAO,KAAK,KAAK,MAAM,WAAW,CAAC;AACnC,OAAO,EAAE,CAAC,IAAI,EAAE,EAAE,MAAM,4BAA4B,CAAC;AAgBrD,OAAO,CAAC,MAAM,CAAC;IACb,MAAM,CAAC,EAAE,OAAO,EAAE,CAAC;IACnB,MAAM,IAAI,EAAE,OAAO,OAAO,CAAC,GAAG,CAAC;IAE/B,MAAM,IAAI,EAAE,OAAO,KAAK,CAAC;IACzB,MAAM,EAAE,EAAE,OAAO,GAAG,CAAC;IACrB,MAAM,IAAI,EAAE,OAAO,KAAK,CAAC;CAE1B"}
+{"version":3,"file":"node-global.d.mts","sourceRoot":"","sources":["../src/node-global.mts"],"names":[],"mappings":"AACA,OAAO,EAAE,OAAO,IAAI,KAAK,EAAE,MAAM,WAAW,CAAC;AAC7C,OAAO,KAAK,GAAG,MAAM,kBAAkB,CAAC;AACxC,OAAO,KAAK,KAAK,MAAM,WAAW,CAAC;AACnC,OAAO,EAAE,CAAC,IAAI,EAAE,EAAE,MAAM,4BAA4B,CAAC;AACrD,OAAO,EAAE,kBAAkB,IAAI,mBAAmB,EAAE,MAAM,sCAAsC,CAAC;AAejG,OAAO,CAAC,MAAM,CAAC;IACb,MAAM,CAAC,EAAE,OAAO,EAAE,CAAC;IACnB,MAAM,IAAI,EAAE,OAAO,OAAO,CAAC,GAAG,CAAC;IAE/B,MAAM,IAAI,EAAE,OAAO,KAAK,CAAC;IACzB,MAAM,EAAE,EAAE,OAAO,GAAG,CAAC;IACrB,MAAM,IAAI,EAAE,OAAO,KAAK,CAAC;IACzB,MAAM,kBAAkB,EAAE,OAAO,mBAAmB,CAAC;CACtD"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ts-repo-utils",
-  "version": "7.3.0",
+  "version": "7.4.0",
   "private": false,
   "keywords": [
     "typescript"

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.3.0',
+  version: '7.4.0',
   args: {
     silent: cmd.flag({
       long: 'silent',

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.3.0',
+  version: '7.4.0',
   args: {
     pathsIgnore: cmd.multioption({
       long: 'paths-ignore',

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.3.0',
+  version: '7.4.0',
   args: {
     base: cmd.positional({
       type: cmd.string,

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.3.0',
+  version: '7.4.0',
   args: {
     excludeUntracked: cmd.flag({
       long: 'exclude-untracked',

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

@@ -38,7 +38,7 @@ const nonEmptyArray = <T extends cmd.Type<any, any>>(
 
 const cmdDef = cmd.command({
   name: 'gen-index-ts-cli',
-  version: '7.3.0',
+  version: '7.4.0',
   args: {
     // required args
     targetDirectory: cmd.positional({

package/src/functions/should-run.mts

@@ -61,7 +61,7 @@ export const checkShouldRunTypeChecks = async (
     pathsIgnore?: readonly string[];
     baseBranch?: string;
   }>,
-): Promise<void> => {
+): Promise<boolean> => {
   const pathsIgnore = options?.pathsIgnore ?? [
     'LICENSE',
     '.editorconfig',
@@ -112,4 +112,6 @@ export const checkShouldRunTypeChecks = async (
   if (GITHUB_OUTPUT !== undefined) {
     await fs.appendFile(GITHUB_OUTPUT, `should_run=${shouldRunTsChecks}\n`);
   }
+
+  return shouldRunTsChecks;
 };

package/src/node-global.mts

@@ -25,5 +25,5 @@ declare global {
   const path: typeof path_;
   const fs: typeof fs_;
   const glob: typeof glob_;
-  // const isDirectlyExecuted: typeof isDirectlyExecuted_;
+  const isDirectlyExecuted: typeof isDirectlyExecuted_;
 }