ts-repo-utils 10.2.0 → 10.3.0

package/README.md

@@ -8,7 +8,7 @@
 
 [![npm downloads](https://img.shields.io/npm/dm/ts-repo-utils.svg)](https://www.npmjs.com/package/ts-repo-utils)
 [![License](https://img.shields.io/npm/l/ts-repo-utils.svg)](https://github.com/noshiro-pf/mono/blob/main/libs/ts-repo-utils/LICENSE)
-[![codecov](https://codecov.io/gh/noshiro-pf/mono/graph/badge.svg?token=S4688Q0CX3)](https://codecov.io/gh/noshiro-pf/mono)
+[![codecov](https://codecov.io/gh/noshiro-pf/mono/graph/badge.svg?component=ts-repo-utils)](https://codecov.io/gh/noshiro-pf/mono)
 
 Utilities for TypeScript Repositories.
 
@@ -161,10 +161,56 @@ npm exec -- gen-index-ts ./src --target-ext .mts --index-ext .mts --export-ext .
 - `--min-depth` - Minimum depth to start generating index files (default: 0)
 - `--silent` - Suppress output messages (optional)
 
+### `check-should-run`
+
+Checks whether a CI step should run, based on which files differ from the base branch. Reports `false` when every changed file matches one of the `--paths-ignore` patterns, so a step can be skipped when nothing it checks has changed.
+
+Prefer this over a workflow-level `paths-ignore` trigger filter: a workflow that a path filter skips never reports a status check, so a pull request that changed only the filtered paths waits forever on a required check that never arrives. Gating the individual steps keeps the workflow running — and reporting — while doing no work.
+
+```bash
+# Skip when the diff only touches a directory nothing checks
+npm exec -- check-should-run --paths-ignore 'experimental/'
+
+# Several patterns, and a custom base branch
+npm exec -- check-should-run \
+  --paths-ignore 'experimental/' \
+  --paths-ignore 'docs/' \
+  --paths-ignore '**.md' \
+  --base-branch origin/develop
+```
+
+```yaml
+# Example in GitHub Actions
+- name: Check diff
+  id: check_diff
+  run: npm exec -- check-should-run --paths-ignore 'experimental/'
+
+- name: Run the checks
+  if: steps.check_diff.outputs.should_run == 'true'
+  run: npm run check
+```
+
+**Options:**
+
+- `--paths-ignore` - Patterns whose files do not affect the gated step (optional, can be specified multiple times). Matched with [micromatch](https://github.com/micromatch/micromatch) (with `dot: true`) against paths relative to the repository root, with one shorthand: a pattern ending with `/` is a directory prefix.
+    - Exact file matches: `.editorconfig`
+    - Directory prefixes: `docs/` (the same as `docs/**`)
+    - Globs: `**.md`, `libs/*/samples/**`
+    - Default: `[]` — nothing is ignored, so the step always runs when anything changed
+- `--base-branch` - Base branch to compare against for determining changed files (default: `origin/main`)
+
+An empty diff reads as "nothing changed", so it reports `should_run=false`. On a push to the base branch itself the diff against that branch is empty for that reason; pass the commit the branch pointed at before the push as `--base-branch` there.
+
+**GitHub Actions Integration:**
+
+When running in GitHub Actions, the command appends `should_run=true` or `should_run=false` to the file named by the `GITHUB_OUTPUT` environment variable, which can be used in subsequent steps.
+
 ### `check-should-run-type-checks`
 
 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. The determination of "non-TypeScript files" is based on configurable ignore patterns, which can be specified using the `--paths-ignore` option.
 
+This is [`check-should-run`](#check-should-run) with a default ignore list of the files a TypeScript project typically has but never type-checks. For a step that is not a type check, use `check-should-run` and state its paths.
+
 ```bash
 # Basic usage (compares against origin/main)
 npm exec -- check-should-run-type-checks
@@ -193,11 +239,11 @@ npm exec -- check-should-run-type-checks \
 
 **Options:**
 
-- `--paths-ignore` - Patterns to ignore when checking if type checks should run (optional, can be specified multiple times)
+- `--paths-ignore` - Patterns to ignore when checking if type checks should run (optional, can be specified multiple times). Matched as described for [`check-should-run`](#check-should-run); passing it replaces the default list rather than adding to it.
     - Supports exact file matches: `.cspell.config.yaml`
     - Directory prefixes: `docs/` (matches any file in docs directory)
     - File extensions: `**.md` (matches any markdown file)
-    - Default: `['LICENSE', '.editorconfig', '.gitignore', '.cspell.config.yaml', '.markdownlint-cli2.mjs', '.npmignore', '.prettierignore', '.prettierrc', 'docs/', '**.md', '**.txt']`
+    - Default: `['LICENSE', '.editorconfig', '.gitignore', '.cspell.json', '.cspell.config.yaml', '.markdownlint-cli2.mjs', '.npmignore', '.prettierignore', '.prettierrc', 'docs/', '**.md', '**.txt']`
 - `--base-branch` - Base branch to compare against for determining changed files (default: `origin/main`)
 
 **GitHub Actions Integration:**
@@ -498,13 +544,27 @@ type Ret = Result<
 
 #### Build Optimization Utilities
 
+##### `checkShouldRun(options?): Promise<boolean>`
+
+Checks whether a CI step should run, based on which files differ from the base branch. Reports `false` when every changed file matches one of the ignored patterns.
+(Function version of the `check-should-run` command)
+
 ##### `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.
+`checkShouldRun` with a default ignore list of the files a TypeScript project typically has but never type-checks. 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)
 
 ```tsx
-import { $, checkShouldRunTypeChecks } from 'ts-repo-utils';
+import { $, checkShouldRun, checkShouldRunTypeChecks } from 'ts-repo-utils';
+
+// Gate any step on the paths it cares about
+const shouldRunStyleChecks = await checkShouldRun({
+    pathsIgnore: ['experimental/'],
+});
+
+if (shouldRunStyleChecks) {
+    await $('npm run fmt:check');
+}
 
 // Use default settings (compare against origin/main)
 const shouldRun = await checkShouldRunTypeChecks();
@@ -520,15 +580,17 @@ const shouldRun2 = await checkShouldRunTypeChecks({
 });
 ```
 
-**Options:**
+**Options (both functions):**
 
-- `pathsIgnore?` - Patterns to ignore when checking if type checks should run:
+- `pathsIgnore?` - Patterns whose files do not affect the gated step. Matched with [micromatch](https://github.com/micromatch/micromatch) (with `dot: true`) against paths relative to the repository root, with a trailing `/` as the shorthand for a directory:
     - Exact file matches: `.cspell.config.yaml`
-    - Directory prefixes: `docs/` (matches any file in docs directory)
-    - File extensions: `**.md` (matches any markdown file)
-    - Default: `['LICENSE', '.editorconfig', '.gitignore', '.cspell.config.yaml', '.markdownlint-cli2.mjs', '.npmignore', '.prettierignore', '.prettierrc', 'docs/', '**.md', '**.txt']`
+    - Directory prefixes: `docs/` (the same as `docs/**`)
+    - Globs: `**.md` (matches any markdown file), `libs/*/samples/**`
+    - Default: `[]` for `checkShouldRun`; for `checkShouldRunTypeChecks`, `['LICENSE', '.editorconfig', '.gitignore', '.cspell.json', '.cspell.config.yaml', '.markdownlint-cli2.mjs', '.npmignore', '.prettierignore', '.prettierrc', 'docs/', '**.md', '**.txt']` — passing the option replaces that list rather than adding to it
 - `baseBranch?` - Base branch to compare against (default: `origin/main`)
 
+Both return whether the step should run, and, in GitHub Actions, append `should_run=<result>` to the file named by `GITHUB_OUTPUT`. An empty diff reads as "nothing changed" and so returns `false`.
+
 ### Code Formatting Utilities
 
 #### `formatFilesGlob(pathGlob: string, options?): Promise<Result<undefined, unknown>>`

package/dist/cmd/check-should-run.d.mts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=check-should-run.d.mts.map

package/dist/cmd/check-should-run.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"check-should-run.d.mts","sourceRoot":"","sources":["../../src/cmd/check-should-run.mts"],"names":[],"mappings":""}

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

@@ -0,0 +1,44 @@
+#!/usr/bin/env node
+import * as cmd from 'cmd-ts';
+import { Arr } from 'ts-data-forge';
+import 'node:path';
+import 'node:fs/promises';
+import 'fast-glob';
+import 'node:child_process';
+import 'prettier';
+import 'micromatch';
+import 'node:fs';
+import 'node:url';
+import { checkShouldRun } from '../functions/should-run.mjs';
+import '@sindresorhus/is';
+
+const cmdDef = cmd.command({
+  name: "check-should-run-cli",
+  version: "10.2.0",
+  args: {
+    pathsIgnore: cmd.multioption({
+      long: "paths-ignore",
+      type: cmd.optional(cmd.array(cmd.string)),
+      description: 'Patterns whose files do not affect the gated step. Matched with micromatch against repository-relative paths, with a trailing "/" as the shorthand for a directory (e.g. "experimental/", ".editorconfig", "**.md"). Defaults to ignoring nothing.'
+    }),
+    baseBranch: cmd.option({
+      long: "base-branch",
+      type: cmd.optional(cmd.string),
+      description: 'Base branch to compare against for determining changed files. Defaults to "origin/main"'
+    })
+  },
+  handler: (args) => {
+    main(args).catch((error) => {
+      console.error("An error occurred:", error);
+      process.exit(1);
+    });
+  }
+});
+const main = async (args) => {
+  await checkShouldRun({
+    pathsIgnore: args.pathsIgnore,
+    baseBranch: args.baseBranch
+  });
+};
+await cmd.run(cmdDef, Arr.skip(process.argv, 2));
+//# sourceMappingURL=check-should-run.mjs.map

package/dist/cmd/check-should-run.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"check-should-run.mjs","sources":["../../src/cmd/check-should-run.mts"],"sourcesContent":["#!/usr/bin/env node\n\nimport * as cmd from 'cmd-ts';\nimport { Arr } from 'ts-data-forge';\nimport { checkShouldRun } from '../functions/index.mjs';\n\nconst cmdDef = cmd.command({\n  name: 'check-should-run-cli',\n  version: '10.2.0',\n  args: {\n    pathsIgnore: cmd.multioption({\n      long: 'paths-ignore',\n      type: cmd.optional(cmd.array(cmd.string)),\n      description:\n        'Patterns whose files do not affect the gated step. Matched with micromatch against repository-relative paths, with a trailing \"/\" as the shorthand for a directory (e.g. \"experimental/\", \".editorconfig\", \"**.md\"). Defaults to ignoring nothing.',\n    }),\n    baseBranch: cmd.option({\n      long: 'base-branch',\n      type: cmd.optional(cmd.string),\n      description:\n        'Base branch to compare against for determining changed files. Defaults to \"origin/main\"',\n    }),\n  },\n  handler: (args) => {\n    main(args).catch((error: unknown) => {\n      console.error('An error occurred:', error);\n\n      process.exit(1);\n    });\n  },\n});\n\nconst main = async (\n  args: Readonly<{\n    pathsIgnore?: readonly string[];\n    baseBranch?: string;\n  }>,\n): Promise<void> => {\n  await checkShouldRun({\n    pathsIgnore: args.pathsIgnore,\n    baseBranch: args.baseBranch,\n  });\n};\n\nawait cmd.run(cmdDef, Arr.skip(process.argv, 2));\n"],"names":[],"mappings":";;;;;;;;;;;;;;AAMA,MAAM,MAAA,GAAS,IAAI,OAAA,CAAQ;AAAA,EACzB,IAAA,EAAM,sBAAA;AAAA,EACN,OAAA,EAAS,QAAA;AAAA,EACT,IAAA,EAAM;AAAA,IACJ,WAAA,EAAa,IAAI,WAAA,CAAY;AAAA,MAC3B,IAAA,EAAM,cAAA;AAAA,MACN,MAAM,GAAA,CAAI,QAAA,CAAS,IAAI,KAAA,CAAM,GAAA,CAAI,MAAM,CAAC,CAAA;AAAA,MACxC,WAAA,EACE;AAAA,KACH,CAAA;AAAA,IACD,UAAA,EAAY,IAAI,MAAA,CAAO;AAAA,MACrB,IAAA,EAAM,aAAA;AAAA,MACN,IAAA,EAAM,GAAA,CAAI,QAAA,CAAS,GAAA,CAAI,MAAM,CAAA;AAAA,MAC7B,WAAA,EACE;AAAA,KACH;AAAA,GACH;AAAA,EACA,OAAA,EAAS,CAAC,IAAA,KAAS;AACjB,IAAA,IAAA,CAAK,IAAI,CAAA,CAAE,KAAA,CAAM,CAAC,KAAA,KAAmB;AACnC,MAAA,OAAA,CAAQ,KAAA,CAAM,sBAAsB,KAAK,CAAA;AAEzC,MAAA,OAAA,CAAQ,KAAK,CAAC,CAAA;AAAA,IAChB,CAAC,CAAA;AAAA,EACH;AACF,CAAC,CAAA;AAED,MAAM,IAAA,GAAO,OACX,IAAA,KAIkB;AAClB,EAAA,MAAM,cAAA,CAAe;AAAA,IACnB,aAAa,IAAA,CAAK,WAAA;AAAA,IAClB,YAAY,IAAA,CAAK;AAAA,GAClB,CAAA;AACH,CAAA;AAEA,MAAM,GAAA,CAAI,IAAI,MAAA,EAAQ,GAAA,CAAI,KAAK,OAAA,CAAQ,IAAA,EAAM,CAAC,CAAC,CAAA"}

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

@@ -9,6 +9,7 @@ import 'prettier';
 import { genIndex } from '../functions/gen-index.mjs';
 import 'node:fs';
 import 'node:url';
+import 'micromatch';
 import '@sindresorhus/is';
 
 const extensionType = cmd.extendType(cmd.string, {

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

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

package/dist/entry-point.mjs

@@ -10,7 +10,7 @@ export { genIndex } from './functions/gen-index.mjs';
 export { glob } from './functions/glob.mjs';
 export { isDirectlyExecuted } from './functions/is-directly-executed.mjs';
 export { makeEmptyDir } from './functions/make-empty-dir.mjs';
-export { checkShouldRunTypeChecks } from './functions/should-run.mjs';
+export { checkShouldRun, checkShouldRunTypeChecks } from './functions/should-run.mjs';
 export { executeParallel, executeStages } from './functions/workspace-utils/execute-parallel.mjs';
 export { getWorkspacePackages } from './functions/workspace-utils/get-workspace-packages.mjs';
 export { runCmdInParallelAcrossWorkspaces } from './functions/workspace-utils/run-cmd-in-parallel.mjs';

package/dist/functions/index.mjs

@@ -9,7 +9,7 @@ export { genIndex } from './gen-index.mjs';
 export { glob } from './glob.mjs';
 export { isDirectlyExecuted } from './is-directly-executed.mjs';
 export { makeEmptyDir } from './make-empty-dir.mjs';
-export { checkShouldRunTypeChecks } from './should-run.mjs';
+export { checkShouldRun, checkShouldRunTypeChecks } from './should-run.mjs';
 export { executeParallel, executeStages } from './workspace-utils/execute-parallel.mjs';
 export { getWorkspacePackages } from './workspace-utils/get-workspace-packages.mjs';
 export { runCmdInParallelAcrossWorkspaces } from './workspace-utils/run-cmd-in-parallel.mjs';

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

@@ -1,7 +1,68 @@
+/**
+ * Checks whether a CI step should run, based on which files differ from a base
+ * branch. Reports `false` when every changed file matches one of the ignored
+ * patterns.
+ *
+ * This is the general form of {@link checkShouldRunTypeChecks}: it carries no
+ * default ignore list, so the caller states exactly which paths are irrelevant
+ * to the step being gated.
+ *
+ * Prefer gating the individual steps of a workflow with this over a
+ * `paths-ignore` trigger filter: a workflow that a path filter skips never
+ * reports a status check, so a pull request that changed only the filtered
+ * paths waits forever on a required check that will never arrive.
+ *
+ * @example
+ *   ```typescript
+ *   // Skip when the diff only touches a directory nothing checks
+ *   await checkShouldRun({ pathsIgnore: ['experimental/'] });
+ *
+ *   // Custom base branch
+ *   await checkShouldRun({
+ *     pathsIgnore: ['docs/', '**.md'],
+ *     baseBranch: 'origin/develop',
+ *   });
+ *   ```;
+ *
+ * @example
+ *   GitHub Actions usage
+ *   ```yaml
+ *   - name: Check diff
+ *   id: check_diff
+ *   run: npm exec -- check-should-run --paths-ignore 'experimental/'
+ *
+ *   - name: Run the checks
+ *   if: steps.check_diff.outputs.should_run == 'true'
+ *   run: npm run check
+ *   ```
+ *
+ * @param options - Configuration options
+ * @param options.pathsIgnore - Patterns whose files do not affect the step.
+ *   Matched with micromatch (with `dot: true`) against paths relative to the
+ *   repository root, with one shorthand: a pattern ending with `/` is a
+ *   directory prefix, so `docs/` is `docs/**`. Exact file names
+ *   (`.editorconfig`) and ordinary globs (`**.md`, `docs/**`) both work.
+ *   Defaults to `[]`, which ignores nothing.
+ * @param options.baseBranch - Base branch to compare against for determining
+ *   changed files. Defaults to `'origin/main'`
+ * @returns Whether the step should run. An empty diff reads as "nothing
+ *   changed" and so returns `false`. When running in GitHub Actions, also
+ *   appends `should_run=true` or `should_run=false` to the file named by the
+ *   `GITHUB_OUTPUT` environment variable.
+ */
+export declare const checkShouldRun: (options?: Readonly<{
+    pathsIgnore?: readonly string[];
+    baseBranch?: string;
+}>) => Promise<boolean>;
 /**
  * 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.
  *
+ * This is {@link checkShouldRun} with an ignore list of the files that a
+ * TypeScript project typically has but never type-checks — documentation,
+ * tooling configuration, license text. Pass `pathsIgnore` to replace that list,
+ * or call {@link checkShouldRun} directly for a step that is not a type check.
+ *
  * 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
@@ -37,7 +98,7 @@
  *
  * @param options - Configuration options
  * @param options.pathsIgnore - Array of patterns to ignore when determining if
- *   type checks should run. Supports three pattern types:
+ *   type checks should run. Matched as described in {@link checkShouldRun}:
  *
  *   - **Exact file matches**: e.g., `.cspell.config.yaml` matches only that file
  *   - **Directory prefixes**: e.g., `docs/` matches any file in docs directory

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":"AAKA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqDG;AACH,eAAO,MAAM,wBAAwB,aACzB,QAAQ,CAAC;IACjB,WAAW,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAChC,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB,CAAC,KACD,OAAO,CAAC,OAAO,CAyDjB,CAAC"}
+{"version":3,"file":"should-run.d.mts","sourceRoot":"","sources":["../../src/functions/should-run.mts"],"names":[],"mappings":"AAMA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmDG;AACH,eAAO,MAAM,cAAc,aACf,QAAQ,CAAC;IACjB,WAAW,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAChC,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB,CAAC,KACD,OAAO,CAAC,OAAO,CAyCjB,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0DG;AACH,eAAO,MAAM,wBAAwB,aACzB,QAAQ,CAAC;IACjB,WAAW,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAChC,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB,CAAC,KACD,OAAO,CAAC,OAAO,CAId,CAAC"}

package/dist/functions/should-run.mjs

@@ -1,51 +1,55 @@
+import micromatch from 'micromatch';
 import * as fs from 'node:fs/promises';
 import * as path from 'node:path';
-import { Result } from 'ts-data-forge';
-import { getDiffFrom } from './diff.mjs';
+import { Result, castMutable } from 'ts-data-forge';
+import { getGitRoot, getDiffFrom } from './diff.mjs';
 
-const checkShouldRunTypeChecks = async (options) => {
-  const pathsIgnore = options?.pathsIgnore ?? [
-    "LICENSE",
-    ".editorconfig",
-    ".gitignore",
-    ".cspell.json",
-    ".cspell.config.yaml",
-    ".markdownlint-cli2.mjs",
-    ".npmignore",
-    ".prettierignore",
-    ".prettierrc",
-    "docs/",
-    "**.md",
-    "**.txt"
-  ];
+const checkShouldRun = async (options) => {
+  const pathsIgnore = options?.pathsIgnore ?? [];
   const baseBranch = options?.baseBranch ?? "origin/main";
   const GITHUB_OUTPUT = process.env["GITHUB_OUTPUT"];
+  const gitRoot = await getGitRoot();
+  if (Result.isErr(gitRoot)) {
+    console.error("Error getting the git root:", gitRoot.value);
+    process.exit(1);
+  }
   const files = await getDiffFrom(baseBranch);
   if (Result.isErr(files)) {
     console.error("Error getting diff:", files.value);
     process.exit(1);
   }
-  const shouldRunTsChecks = !files.value.every(
-    (file) => pathsIgnore.some((pattern) => {
-      if (pattern === file) {
-        return true;
-      }
-      if (pattern.endsWith("/") && file.startsWith(pattern)) {
-        return true;
-      }
-      if (pattern.startsWith("**.")) {
-        const extension = pattern.slice(2);
-        return path.basename(file).endsWith(extension);
-      }
-      return false;
-    })
+  const changedFiles = files.value.map(
+    (file) => path.relative(gitRoot.value, file).split(path.sep).join("/")
+  );
+  const patterns = pathsIgnore.map(toMatchPattern);
+  const shouldRun = changedFiles.some(
+    (file) => !micromatch.isMatch(file, castMutable(patterns), { dot: true })
   );
   if (GITHUB_OUTPUT !== void 0) {
-    await fs.appendFile(GITHUB_OUTPUT, `should_run=${shouldRunTsChecks}
+    await fs.appendFile(GITHUB_OUTPUT, `should_run=${shouldRun}
 `);
   }
-  return shouldRunTsChecks;
+  return shouldRun;
 };
+const checkShouldRunTypeChecks = async (options) => checkShouldRun({
+  pathsIgnore: options?.pathsIgnore ?? defaultTypeCheckPathsIgnore,
+  baseBranch: options?.baseBranch
+});
+const defaultTypeCheckPathsIgnore = [
+  "LICENSE",
+  ".editorconfig",
+  ".gitignore",
+  ".cspell.json",
+  ".cspell.config.yaml",
+  ".markdownlint-cli2.mjs",
+  ".npmignore",
+  ".prettierignore",
+  ".prettierrc",
+  "docs/",
+  "**.md",
+  "**.txt"
+];
+const toMatchPattern = (pattern) => pattern.endsWith("/") ? `${pattern}**` : pattern;
 
-export { checkShouldRunTypeChecks };
+export { checkShouldRun, checkShouldRunTypeChecks };
 //# sourceMappingURL=should-run.mjs.map

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

@@ -1 +1 @@
-{"version":3,"file":"should-run.mjs","sources":["../../src/functions/should-run.mts"],"sourcesContent":["import * as fs from 'node:fs/promises';\nimport * as path from 'node:path';\nimport { Result } from 'ts-data-forge';\nimport { getDiffFrom } from './diff.mjs';\n\n/**\n * Checks if TypeScript type checks should run based on the diff from a base\n * branch. Skips type checks if all changed files match the ignored patterns.\n *\n * This function is typically used in CI/CD pipelines to determine whether\n * expensive type checking operations should be performed. If all changed files\n * are documentation, configuration, or other non-TypeScript files, type checks\n * can be safely skipped to improve build performance.\n *\n * @example\n *   ```typescript\n *   // Use default settings (compare against origin/main, ignore docs/md/txt files)\n *   await checkShouldRunTypeChecks();\n *\n *   // Custom ignore patterns\n *   await checkShouldRunTypeChecks({\n *     pathsIgnore: ['.eslintrc.json', 'docs/', '**.md', 'scripts/'],\n *   });\n *\n *   // Custom base branch\n *   await checkShouldRunTypeChecks({\n *     baseBranch: 'origin/develop',\n *   });\n *   ```;\n *\n * @example\n *   GitHub Actions usage\n *   ```yaml\n *   - name: Check if type checks should run\n *   id: check_diff\n *   run: npm exec check-should-run-type-checks\n *\n *   - name: Run type checks\n *   if: steps.check_diff.outputs.should_run == 'true'\n *   run: npm run type-check\n *   ```\n *\n * @param options - Configuration options\n * @param options.pathsIgnore - Array of patterns to ignore when determining if\n *   type checks should run. Supports three pattern types:\n *\n *   - **Exact file matches**: e.g., `.cspell.config.yaml` matches only that file\n *   - **Directory prefixes**: e.g., `docs/` matches any file in docs directory\n *   - **File extensions**: e.g., `**.md` matches any markdown file Defaults to:\n *       `['LICENSE', '.editorconfig', '.gitignore', '.cspell.json', '.cspell.config.yaml',\n *       '.markdownlint-cli2.mjs', '.npmignore', '.prettierignore',\n *       '.prettierrc', 'docs/', '**.md', '**.txt']`\n *\n * @param options.baseBranch - Base branch to compare against for determining\n *   changed files. Defaults to `'origin/main'`\n * @returns A promise that resolves when the check is complete. The function\n *   will set the GITHUB_OUTPUT environment variable with `should_run=true` or\n *   `should_run=false` if running in GitHub Actions environment.\n */\nexport const checkShouldRunTypeChecks = async (\n  options?: Readonly<{\n    pathsIgnore?: readonly string[];\n    baseBranch?: string;\n  }>,\n): Promise<boolean> => {\n  const pathsIgnore = options?.pathsIgnore ?? [\n    'LICENSE',\n    '.editorconfig',\n    '.gitignore',\n    '.cspell.json',\n    '.cspell.config.yaml',\n    '.markdownlint-cli2.mjs',\n    '.npmignore',\n    '.prettierignore',\n    '.prettierrc',\n    'docs/',\n    '**.md',\n    '**.txt',\n  ];\n\n  const baseBranch = options?.baseBranch ?? 'origin/main';\n\n  const GITHUB_OUTPUT = process.env['GITHUB_OUTPUT'];\n\n  const files = await getDiffFrom(baseBranch);\n\n  if (Result.isErr(files)) {\n    console.error('Error getting diff:', files.value);\n\n    process.exit(1);\n  }\n\n  const shouldRunTsChecks: boolean = !files.value.every((file) =>\n    pathsIgnore.some((pattern) => {\n      // Exact file match\n      if (pattern === file) {\n        return true;\n      }\n\n      // Directory prefix match (pattern ends with '/')\n      if (pattern.endsWith('/') && file.startsWith(pattern)) {\n        return true;\n      }\n\n      // File extension pattern match (pattern starts with '**.')\n      if (pattern.startsWith('**.')) {\n        const extension = pattern.slice(2); // Remove '**'\n\n        return path.basename(file).endsWith(extension);\n      }\n\n      return false;\n    }),\n  );\n\n  if (GITHUB_OUTPUT !== undefined) {\n    // eslint-disable-next-line security/detect-non-literal-fs-filename\n    await fs.appendFile(GITHUB_OUTPUT, `should_run=${shouldRunTsChecks}\\n`);\n  }\n\n  return shouldRunTsChecks;\n};\n"],"names":[],"mappings":";;;;;AA2DO,MAAM,wBAAA,GAA2B,OACtC,OAAA,KAIqB;AACrB,EAAA,MAAM,WAAA,GAAc,SAAS,WAAA,IAAe;AAAA,IAC1C,SAAA;AAAA,IACA,eAAA;AAAA,IACA,YAAA;AAAA,IACA,cAAA;AAAA,IACA,qBAAA;AAAA,IACA,wBAAA;AAAA,IACA,YAAA;AAAA,IACA,iBAAA;AAAA,IACA,aAAA;AAAA,IACA,OAAA;AAAA,IACA,OAAA;AAAA,IACA;AAAA,GACF;AAEA,EAAA,MAAM,UAAA,GAAa,SAAS,UAAA,IAAc,aAAA;AAE1C,EAAA,MAAM,aAAA,GAAgB,OAAA,CAAQ,GAAA,CAAI,eAAe,CAAA;AAEjD,EAAA,MAAM,KAAA,GAAQ,MAAM,WAAA,CAAY,UAAU,CAAA;AAE1C,EAAA,IAAI,MAAA,CAAO,KAAA,CAAM,KAAK,CAAA,EAAG;AACvB,IAAA,OAAA,CAAQ,KAAA,CAAM,qBAAA,EAAuB,KAAA,CAAM,KAAK,CAAA;AAEhD,IAAA,OAAA,CAAQ,KAAK,CAAC,CAAA;AAAA,EAChB;AAEA,EAAA,MAAM,iBAAA,GAA6B,CAAC,KAAA,CAAM,KAAA,CAAM,KAAA;AAAA,IAAM,CAAC,IAAA,KACrD,WAAA,CAAY,IAAA,CAAK,CAAC,OAAA,KAAY;AAE5B,MAAA,IAAI,YAAY,IAAA,EAAM;AACpB,QAAA,OAAO,IAAA;AAAA,MACT;AAGA,MAAA,IAAI,QAAQ,QAAA,CAAS,GAAG,KAAK,IAAA,CAAK,UAAA,CAAW,OAAO,CAAA,EAAG;AACrD,QAAA,OAAO,IAAA;AAAA,MACT;AAGA,MAAA,IAAI,OAAA,CAAQ,UAAA,CAAW,KAAK,CAAA,EAAG;AAC7B,QAAA,MAAM,SAAA,GAAY,OAAA,CAAQ,KAAA,CAAM,CAAC,CAAA;AAEjC,QAAA,OAAO,IAAA,CAAK,QAAA,CAAS,IAAI,CAAA,CAAE,SAAS,SAAS,CAAA;AAAA,MAC/C;AAEA,MAAA,OAAO,KAAA;AAAA,IACT,CAAC;AAAA,GACH;AAEA,EAAA,IAAI,kBAAkB,MAAA,EAAW;AAE/B,IAAA,MAAM,EAAA,CAAG,UAAA,CAAW,aAAA,EAAe,CAAA,WAAA,EAAc,iBAAiB;AAAA,CAAI,CAAA;AAAA,EACxE;AAEA,EAAA,OAAO,iBAAA;AACT;;;;"}
+{"version":3,"file":"should-run.mjs","sources":["../../src/functions/should-run.mts"],"sourcesContent":["import micromatch from 'micromatch';\nimport * as fs from 'node:fs/promises';\nimport * as path from 'node:path';\nimport { castMutable, Result } from 'ts-data-forge';\nimport { getDiffFrom, getGitRoot } from './diff.mjs';\n\n/**\n * Checks whether a CI step should run, based on which files differ from a base\n * branch. Reports `false` when every changed file matches one of the ignored\n * patterns.\n *\n * This is the general form of {@link checkShouldRunTypeChecks}: it carries no\n * default ignore list, so the caller states exactly which paths are irrelevant\n * to the step being gated.\n *\n * Prefer gating the individual steps of a workflow with this over a\n * `paths-ignore` trigger filter: a workflow that a path filter skips never\n * reports a status check, so a pull request that changed only the filtered\n * paths waits forever on a required check that will never arrive.\n *\n * @example\n *   ```typescript\n *   // Skip when the diff only touches a directory nothing checks\n *   await checkShouldRun({ pathsIgnore: ['experimental/'] });\n *\n *   // Custom base branch\n *   await checkShouldRun({\n *     pathsIgnore: ['docs/', '**.md'],\n *     baseBranch: 'origin/develop',\n *   });\n *   ```;\n *\n * @example\n *   GitHub Actions usage\n *   ```yaml\n *   - name: Check diff\n *   id: check_diff\n *   run: npm exec -- check-should-run --paths-ignore 'experimental/'\n *\n *   - name: Run the checks\n *   if: steps.check_diff.outputs.should_run == 'true'\n *   run: npm run check\n *   ```\n *\n * @param options - Configuration options\n * @param options.pathsIgnore - Patterns whose files do not affect the step.\n *   Matched with micromatch (with `dot: true`) against paths relative to the\n *   repository root, with one shorthand: a pattern ending with `/` is a\n *   directory prefix, so `docs/` is `docs/**`. Exact file names\n *   (`.editorconfig`) and ordinary globs (`**.md`, `docs/**`) both work.\n *   Defaults to `[]`, which ignores nothing.\n * @param options.baseBranch - Base branch to compare against for determining\n *   changed files. Defaults to `'origin/main'`\n * @returns Whether the step should run. An empty diff reads as \"nothing\n *   changed\" and so returns `false`. When running in GitHub Actions, also\n *   appends `should_run=true` or `should_run=false` to the file named by the\n *   `GITHUB_OUTPUT` environment variable.\n */\nexport const checkShouldRun = async (\n  options?: Readonly<{\n    pathsIgnore?: readonly string[];\n    baseBranch?: string;\n  }>,\n): Promise<boolean> => {\n  const pathsIgnore = options?.pathsIgnore ?? [];\n\n  const baseBranch = options?.baseBranch ?? 'origin/main';\n\n  const GITHUB_OUTPUT = process.env['GITHUB_OUTPUT'];\n\n  const gitRoot = await getGitRoot();\n\n  if (Result.isErr(gitRoot)) {\n    console.error('Error getting the git root:', gitRoot.value);\n\n    process.exit(1);\n  }\n\n  const files = await getDiffFrom(baseBranch);\n\n  if (Result.isErr(files)) {\n    console.error('Error getting diff:', files.value);\n\n    process.exit(1);\n  }\n\n  // `getDiffFrom` returns absolute paths, while the patterns are written\n  // relative to the repository root.\n  const changedFiles = files.value.map((file) =>\n    path.relative(gitRoot.value, file).split(path.sep).join('/'),\n  );\n\n  const patterns = pathsIgnore.map(toMatchPattern);\n\n  const shouldRun: boolean = changedFiles.some(\n    (file) => !micromatch.isMatch(file, castMutable(patterns), { dot: true }),\n  );\n\n  if (GITHUB_OUTPUT !== undefined) {\n    // eslint-disable-next-line security/detect-non-literal-fs-filename\n    await fs.appendFile(GITHUB_OUTPUT, `should_run=${shouldRun}\\n`);\n  }\n\n  return shouldRun;\n};\n\n/**\n * Checks if TypeScript type checks should run based on the diff from a base\n * branch. Skips type checks if all changed files match the ignored patterns.\n *\n * This is {@link checkShouldRun} with an ignore list of the files that a\n * TypeScript project typically has but never type-checks — documentation,\n * tooling configuration, license text. Pass `pathsIgnore` to replace that list,\n * or call {@link checkShouldRun} directly for a step that is not a type check.\n *\n * This function is typically used in CI/CD pipelines to determine whether\n * expensive type checking operations should be performed. If all changed files\n * are documentation, configuration, or other non-TypeScript files, type checks\n * can be safely skipped to improve build performance.\n *\n * @example\n *   ```typescript\n *   // Use default settings (compare against origin/main, ignore docs/md/txt files)\n *   await checkShouldRunTypeChecks();\n *\n *   // Custom ignore patterns\n *   await checkShouldRunTypeChecks({\n *     pathsIgnore: ['.eslintrc.json', 'docs/', '**.md', 'scripts/'],\n *   });\n *\n *   // Custom base branch\n *   await checkShouldRunTypeChecks({\n *     baseBranch: 'origin/develop',\n *   });\n *   ```;\n *\n * @example\n *   GitHub Actions usage\n *   ```yaml\n *   - name: Check if type checks should run\n *   id: check_diff\n *   run: npm exec check-should-run-type-checks\n *\n *   - name: Run type checks\n *   if: steps.check_diff.outputs.should_run == 'true'\n *   run: npm run type-check\n *   ```\n *\n * @param options - Configuration options\n * @param options.pathsIgnore - Array of patterns to ignore when determining if\n *   type checks should run. Matched as described in {@link checkShouldRun}:\n *\n *   - **Exact file matches**: e.g., `.cspell.config.yaml` matches only that file\n *   - **Directory prefixes**: e.g., `docs/` matches any file in docs directory\n *   - **File extensions**: e.g., `**.md` matches any markdown file Defaults to:\n *       `['LICENSE', '.editorconfig', '.gitignore', '.cspell.json', '.cspell.config.yaml',\n *       '.markdownlint-cli2.mjs', '.npmignore', '.prettierignore',\n *       '.prettierrc', 'docs/', '**.md', '**.txt']`\n *\n * @param options.baseBranch - Base branch to compare against for determining\n *   changed files. Defaults to `'origin/main'`\n * @returns A promise that resolves when the check is complete. The function\n *   will set the GITHUB_OUTPUT environment variable with `should_run=true` or\n *   `should_run=false` if running in GitHub Actions environment.\n */\nexport const checkShouldRunTypeChecks = async (\n  options?: Readonly<{\n    pathsIgnore?: readonly string[];\n    baseBranch?: string;\n  }>,\n): Promise<boolean> =>\n  checkShouldRun({\n    pathsIgnore: options?.pathsIgnore ?? defaultTypeCheckPathsIgnore,\n    baseBranch: options?.baseBranch,\n  });\n\nconst defaultTypeCheckPathsIgnore = [\n  'LICENSE',\n  '.editorconfig',\n  '.gitignore',\n  '.cspell.json',\n  '.cspell.config.yaml',\n  '.markdownlint-cli2.mjs',\n  '.npmignore',\n  '.prettierignore',\n  '.prettierrc',\n  'docs/',\n  '**.md',\n  '**.txt',\n] as const;\n\n/**\n * Expands the trailing-slash shorthand for a directory into the glob\n * micromatch needs. Every other pattern is already one.\n */\nconst toMatchPattern = (pattern: string): string =>\n  pattern.endsWith('/') ? (`${pattern}**` as const) : pattern;\n"],"names":[],"mappings":";;;;;;AA0DO,MAAM,cAAA,GAAiB,OAC5B,OAAA,KAIqB;AACrB,EAAA,MAAM,WAAA,GAAc,OAAA,EAAS,WAAA,IAAe,EAAC;AAE7C,EAAA,MAAM,UAAA,GAAa,SAAS,UAAA,IAAc,aAAA;AAE1C,EAAA,MAAM,aAAA,GAAgB,OAAA,CAAQ,GAAA,CAAI,eAAe,CAAA;AAEjD,EAAA,MAAM,OAAA,GAAU,MAAM,UAAA,EAAW;AAEjC,EAAA,IAAI,MAAA,CAAO,KAAA,CAAM,OAAO,CAAA,EAAG;AACzB,IAAA,OAAA,CAAQ,KAAA,CAAM,6BAAA,EAA+B,OAAA,CAAQ,KAAK,CAAA;AAE1D,IAAA,OAAA,CAAQ,KAAK,CAAC,CAAA;AAAA,EAChB;AAEA,EAAA,MAAM,KAAA,GAAQ,MAAM,WAAA,CAAY,UAAU,CAAA;AAE1C,EAAA,IAAI,MAAA,CAAO,KAAA,CAAM,KAAK,CAAA,EAAG;AACvB,IAAA,OAAA,CAAQ,KAAA,CAAM,qBAAA,EAAuB,KAAA,CAAM,KAAK,CAAA;AAEhD,IAAA,OAAA,CAAQ,KAAK,CAAC,CAAA;AAAA,EAChB;AAIA,EAAA,MAAM,YAAA,GAAe,MAAM,KAAA,CAAM,GAAA;AAAA,IAAI,CAAC,IAAA,KACpC,IAAA,CAAK,QAAA,CAAS,OAAA,CAAQ,KAAA,EAAO,IAAI,CAAA,CAAE,KAAA,CAAM,IAAA,CAAK,GAAG,CAAA,CAAE,KAAK,GAAG;AAAA,GAC7D;AAEA,EAAA,MAAM,QAAA,GAAW,WAAA,CAAY,GAAA,CAAI,cAAc,CAAA;AAE/C,EAAA,MAAM,YAAqB,YAAA,CAAa,IAAA;AAAA,IACtC,CAAC,IAAA,KAAS,CAAC,UAAA,CAAW,OAAA,CAAQ,IAAA,EAAM,WAAA,CAAY,QAAQ,CAAA,EAAG,EAAE,GAAA,EAAK,IAAA,EAAM;AAAA,GAC1E;AAEA,EAAA,IAAI,kBAAkB,MAAA,EAAW;AAE/B,IAAA,MAAM,EAAA,CAAG,UAAA,CAAW,aAAA,EAAe,CAAA,WAAA,EAAc,SAAS;AAAA,CAAI,CAAA;AAAA,EAChE;AAEA,EAAA,OAAO,SAAA;AACT;AA6DO,MAAM,wBAAA,GAA2B,OACtC,OAAA,KAKA,cAAA,CAAe;AAAA,EACb,WAAA,EAAa,SAAS,WAAA,IAAe,2BAAA;AAAA,EACrC,YAAY,OAAA,EAAS;AACvB,CAAC;AAEH,MAAM,2BAAA,GAA8B;AAAA,EAClC,SAAA;AAAA,EACA,eAAA;AAAA,EACA,YAAA;AAAA,EACA,cAAA;AAAA,EACA,qBAAA;AAAA,EACA,wBAAA;AAAA,EACA,YAAA;AAAA,EACA,iBAAA;AAAA,EACA,aAAA;AAAA,EACA,OAAA;AAAA,EACA,OAAA;AAAA,EACA;AACF,CAAA;AAMA,MAAM,cAAA,GAAiB,CAAC,OAAA,KACtB,OAAA,CAAQ,SAAS,GAAG,CAAA,GAAK,CAAA,EAAG,OAAO,CAAA,EAAA,CAAA,GAAiB,OAAA;;;;"}

package/dist/functions/workspace-utils/get-workspace-packages.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"get-workspace-packages.d.mts","sourceRoot":"","sources":["../../../src/functions/workspace-utils/get-workspace-packages.mts"],"names":[],"mappings":"AAiBA,OAAO,EAEL,KAAK,eAAe,EACpB,KAAK,OAAO,EACb,MAAM,aAAa,CAAC;AAErB;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,oBAAoB,uBACX,MAAM,qBACR,SAAS,eAAe,EAAE,KAC3C,OAAO,CAAC,SAAS,OAAO,EAAE,CAqE5B,CAAC"}
+{"version":3,"file":"get-workspace-packages.d.mts","sourceRoot":"","sources":["../../../src/functions/workspace-utils/get-workspace-packages.mts"],"names":[],"mappings":"AAcA,OAAO,EAEL,KAAK,eAAe,EACpB,KAAK,OAAO,EACb,MAAM,aAAa,CAAC;AAErB;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,oBAAoB,uBACX,MAAM,qBACR,SAAS,eAAe,EAAE,KAC3C,OAAO,CAAC,SAAS,OAAO,EAAE,CAqE5B,CAAC"}

package/dist/functions/workspace-utils/get-workspace-packages.mjs

@@ -1,6 +1,6 @@
 import * as fs from 'node:fs/promises';
 import * as path from 'node:path';
-import { Result, Json, isNotUndefined, isRecord, hasKey, Arr, isString } from 'ts-data-forge';
+import { Result, Json, isNotUndefined, isRecord, hasKey, Arr, isString, Obj } from 'ts-data-forge';
 import { glob } from '../glob.mjs';
 import { defaultDependencyFields } from './types.mjs';
 
@@ -63,10 +63,7 @@ const getKeyValueRecordFromJsonValue = (value, key) => {
   if (!isRecord(obj)) {
     return {};
   }
-  const entries = Object.entries(obj).filter(
-    (entry) => isString(entry[1])
-  );
-  return Object.fromEntries(entries);
+  return Obj.filter(obj, isString);
 };
 
 export { getWorkspacePackages };

package/dist/functions/workspace-utils/get-workspace-packages.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"get-workspace-packages.mjs","sources":["../../../src/functions/workspace-utils/get-workspace-packages.mts"],"sourcesContent":["import * as fs from 'node:fs/promises';\nimport * as path from 'node:path';\nimport {\n  Arr,\n  hasKey,\n  isNotUndefined,\n  isRecord,\n  isString,\n  Json,\n  Result,\n} from 'ts-data-forge';\nimport {\n  type JsonValue,\n  type MutableFixedLengthTuple,\n  type ReadonlyRecord,\n} from 'ts-type-forge';\nimport { glob } from '../glob.mjs';\nimport {\n  defaultDependencyFields,\n  type DependencyField,\n  type Package,\n} from './types.mjs';\n\n/**\n * Retrieves all workspace packages from a monorepo based on the workspace\n * patterns defined in the root package.json file.\n *\n * @param rootPackageJsonDir - The directory containing the root package.json\n *   file\n * @param dependencyFields - Which `package.json` fields contribute to each\n *   package's `dependencies` map. Defaults to\n *   {@link defaultDependencyFields}.\n * @returns A promise that resolves to an array of Package objects containing\n *   package metadata\n */\nexport const getWorkspacePackages = async (\n  rootPackageJsonDir: string,\n  dependencyFields: readonly DependencyField[] = defaultDependencyFields,\n): Promise<readonly Package[]> => {\n  // Read root package.json\n  // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment\n  const rootPackageJson: JsonValue = JSON.parse(\n    // eslint-disable-next-line security/detect-non-literal-fs-filename\n    await fs.readFile(path.join(rootPackageJsonDir, 'package.json'), 'utf8'),\n  );\n\n  const workspacePatterns: readonly string[] = getStrArrayFromJsonValue(\n    rootPackageJson,\n    'workspaces',\n  );\n\n  const packagePromises = workspacePatterns.map(async (pattern) => {\n    const globResult = await glob(pattern, {\n      cwd: rootPackageJsonDir,\n      ignore: ['**/node_modules/**'],\n      onlyDirectories: true,\n      absolute: true,\n    });\n\n    if (Result.isErr(globResult)) {\n      return [];\n    }\n\n    const matches = globResult.value;\n\n    const packageJsonList: readonly (\n      readonly [string, JsonValue] | undefined\n    )[] = await Promise.all(\n      matches.map(async (match) => {\n        const maybePackagePath = path.join(match, 'package.json');\n\n        const result = await Result.fromPromise(\n          // eslint-disable-next-line security/detect-non-literal-fs-filename\n          fs.readFile(maybePackagePath, 'utf8'),\n        );\n\n        if (Result.isErr(result)) return undefined;\n\n        const parsed = Json.parse(result.value);\n\n        if (Result.isErr(parsed)) return undefined;\n\n        return [maybePackagePath, parsed.value] as const;\n      }),\n    );\n\n    const packageInfos: readonly Package[] = packageJsonList\n      .filter(isNotUndefined)\n      .map(([packagePath, packageJson]) => ({\n        name: getStrFromJsonValue(packageJson, 'name'),\n        path: path.dirname(packagePath),\n        packageJson,\n        dependencies: Object.fromEntries(\n          dependencyFields.flatMap((field) =>\n            Object.entries(getKeyValueRecordFromJsonValue(packageJson, field)),\n          ),\n        ),\n      }));\n\n    return packageInfos;\n  });\n\n  const allPackageArrays = await Promise.all(packagePromises);\n\n  const finalPackages = allPackageArrays.flat();\n\n  return finalPackages;\n};\n\nconst getStrFromJsonValue = (value: JsonValue, key: string): string =>\n  isRecord(value) && hasKey(value, key) && isString(value[key])\n    ? value[key]\n    : '';\n\nconst getStrArrayFromJsonValue = (\n  value: JsonValue,\n  key: string,\n): readonly string[] =>\n  isRecord(value) &&\n  hasKey(value, key) &&\n  Arr.isArray(value[key]) &&\n  value[key].every(isString)\n    ? value[key]\n    : ([] as const);\n\nconst getKeyValueRecordFromJsonValue = (\n  value: JsonValue,\n  key: string,\n): ReadonlyRecord<string, string> => {\n  if (!isRecord(value) || !hasKey(value, key)) {\n    return {};\n  }\n\n  const obj = value[key];\n\n  if (!isRecord(obj)) {\n    return {};\n  }\n\n  const entries = Object.entries(obj).filter(\n    (entry): entry is MutableFixedLengthTuple<2, string> => isString(entry[1]),\n  );\n\n  return Object.fromEntries(entries);\n};\n"],"names":[],"mappings":"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"}
+{"version":3,"file":"get-workspace-packages.mjs","sources":["../../../src/functions/workspace-utils/get-workspace-packages.mts"],"sourcesContent":["import * as fs from 'node:fs/promises';\nimport * as path from 'node:path';\nimport {\n  Arr,\n  hasKey,\n  isNotUndefined,\n  isRecord,\n  isString,\n  Json,\n  Obj,\n  Result,\n} from 'ts-data-forge';\nimport { type JsonValue, type ReadonlyRecord } from 'ts-type-forge';\nimport { glob } from '../glob.mjs';\nimport {\n  defaultDependencyFields,\n  type DependencyField,\n  type Package,\n} from './types.mjs';\n\n/**\n * Retrieves all workspace packages from a monorepo based on the workspace\n * patterns defined in the root package.json file.\n *\n * @param rootPackageJsonDir - The directory containing the root package.json\n *   file\n * @param dependencyFields - Which `package.json` fields contribute to each\n *   package's `dependencies` map. Defaults to\n *   {@link defaultDependencyFields}.\n * @returns A promise that resolves to an array of Package objects containing\n *   package metadata\n */\nexport const getWorkspacePackages = async (\n  rootPackageJsonDir: string,\n  dependencyFields: readonly DependencyField[] = defaultDependencyFields,\n): Promise<readonly Package[]> => {\n  // Read root package.json\n  // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment\n  const rootPackageJson: JsonValue = JSON.parse(\n    // eslint-disable-next-line security/detect-non-literal-fs-filename\n    await fs.readFile(path.join(rootPackageJsonDir, 'package.json'), 'utf8'),\n  );\n\n  const workspacePatterns: readonly string[] = getStrArrayFromJsonValue(\n    rootPackageJson,\n    'workspaces',\n  );\n\n  const packagePromises = workspacePatterns.map(async (pattern) => {\n    const globResult = await glob(pattern, {\n      cwd: rootPackageJsonDir,\n      ignore: ['**/node_modules/**'],\n      onlyDirectories: true,\n      absolute: true,\n    });\n\n    if (Result.isErr(globResult)) {\n      return [];\n    }\n\n    const matches = globResult.value;\n\n    const packageJsonList: readonly (\n      readonly [string, JsonValue] | undefined\n    )[] = await Promise.all(\n      matches.map(async (match) => {\n        const maybePackagePath = path.join(match, 'package.json');\n\n        const result = await Result.fromPromise(\n          // eslint-disable-next-line security/detect-non-literal-fs-filename\n          fs.readFile(maybePackagePath, 'utf8'),\n        );\n\n        if (Result.isErr(result)) return undefined;\n\n        const parsed = Json.parse(result.value);\n\n        if (Result.isErr(parsed)) return undefined;\n\n        return [maybePackagePath, parsed.value] as const;\n      }),\n    );\n\n    const packageInfos: readonly Package[] = packageJsonList\n      .filter(isNotUndefined)\n      .map(([packagePath, packageJson]) => ({\n        name: getStrFromJsonValue(packageJson, 'name'),\n        path: path.dirname(packagePath),\n        packageJson,\n        dependencies: Object.fromEntries(\n          dependencyFields.flatMap((field) =>\n            Object.entries(getKeyValueRecordFromJsonValue(packageJson, field)),\n          ),\n        ),\n      }));\n\n    return packageInfos;\n  });\n\n  const allPackageArrays = await Promise.all(packagePromises);\n\n  const finalPackages = allPackageArrays.flat();\n\n  return finalPackages;\n};\n\nconst getStrFromJsonValue = (value: JsonValue, key: string): string =>\n  isRecord(value) && hasKey(value, key) && isString(value[key])\n    ? value[key]\n    : '';\n\nconst getStrArrayFromJsonValue = (\n  value: JsonValue,\n  key: string,\n): readonly string[] =>\n  isRecord(value) &&\n  hasKey(value, key) &&\n  Arr.isArray(value[key]) &&\n  value[key].every(isString)\n    ? value[key]\n    : ([] as const);\n\nconst getKeyValueRecordFromJsonValue = (\n  value: JsonValue,\n  key: string,\n): ReadonlyRecord<string, string> => {\n  if (!isRecord(value) || !hasKey(value, key)) {\n    return {};\n  }\n\n  const obj = value[key];\n\n  if (!isRecord(obj)) {\n    return {};\n  }\n\n  return Obj.filter(obj, isString);\n};\n"],"names":[],"mappings":"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"}

package/dist/index.mjs

@@ -9,7 +9,7 @@ export { genIndex } from './functions/gen-index.mjs';
 export { glob } from './functions/glob.mjs';
 export { isDirectlyExecuted } from './functions/is-directly-executed.mjs';
 export { makeEmptyDir } from './functions/make-empty-dir.mjs';
-export { checkShouldRunTypeChecks } from './functions/should-run.mjs';
+export { checkShouldRun, checkShouldRunTypeChecks } from './functions/should-run.mjs';
 export { executeParallel, executeStages } from './functions/workspace-utils/execute-parallel.mjs';
 export { getWorkspacePackages } from './functions/workspace-utils/get-workspace-packages.mjs';
 export { runCmdInParallelAcrossWorkspaces } from './functions/workspace-utils/run-cmd-in-parallel.mjs';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ts-repo-utils",
-  "version": "10.2.0",
+  "version": "10.3.0",
   "private": false,
   "keywords": [
     "typescript"
@@ -30,6 +30,7 @@
   "types": "./dist/types.d.mts",
   "bin": {
     "assert-repo-is-clean": "./dist/cmd/assert-repo-is-clean.mjs",
+    "check-should-run": "./dist/cmd/check-should-run.mjs",
     "check-should-run-type-checks": "./dist/cmd/check-should-run-type-checks.mjs",
     "format-diff-from": "./dist/cmd/format-diff-from.mjs",
     "format-uncommitted": "./dist/cmd/format-uncommitted.mjs",
@@ -48,37 +49,34 @@
     "cmd-ts": "^0.15.0",
     "fast-glob": "^3.3.3",
     "micromatch": "^4.0.8",
-    "ts-data-forge": "^14.2.1",
+    "ts-data-forge": "^14.4.0",
     "ts-type-forge": "^9.2.1"
   },
   "devDependencies": {
-    "@rollup/plugin-replace": "6.0.3",
-    "@rollup/plugin-strip": "3.0.4",
     "@types/node": "26.2.0",
     "@vitest/coverage-v8": "4.1.10",
     "@vitest/ui": "4.1.10",
     "cspell": "10.0.1",
     "dedent": "1.7.2",
-    "esbuild": "0.28.1",
-    "eslint": "10.8.0",
+    "esbuild": "0.28.2",
+    "eslint": "10.8.1",
     "jiti": "2.7.0",
     "npm-run-all2": "9.0.3",
     "prettier": "3.9.6",
     "prettier-plugin-organize-imports": "4.3.0",
     "prettier-plugin-packagejson": "3.0.2",
     "rollup": "4.62.4",
-    "rollup-plugin-esbuild": "6.2.1",
-    "tsx": "4.23.4",
+    "tsx": "4.23.12",
     "typedoc": "0.28.20",
     "typedoc-github-theme": "0.4.0",
     "typescript": "6.0.3",
     "typescript-native": "npm:typescript@7.0.2",
-    "vite": "8.2.0",
+    "vite": "8.2.1",
     "vitest": "4.1.10",
-    "eslint-config-typed": "5.8.5",
-    "eslint-plugin-ts-fortress": "1.0.1",
-    "eslint-plugin-ts-data-forge": "0.4.4",
-    "eslint-plugin-ts-type-forge": "0.6.3"
+    "eslint-plugin-ts-data-forge": "0.4.8",
+    "eslint-config-typed": "5.9.3",
+    "eslint-plugin-ts-fortress": "1.0.4",
+    "eslint-plugin-ts-type-forge": "0.6.6"
   },
   "peerDependencies": {
     "prettier": ">=3.0.0"

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

@@ -0,0 +1,45 @@
+#!/usr/bin/env node
+
+import * as cmd from 'cmd-ts';
+import { Arr } from 'ts-data-forge';
+import { checkShouldRun } from '../functions/index.mjs';
+
+const cmdDef = cmd.command({
+  name: 'check-should-run-cli',
+  version: '10.2.0',
+  args: {
+    pathsIgnore: cmd.multioption({
+      long: 'paths-ignore',
+      type: cmd.optional(cmd.array(cmd.string)),
+      description:
+        'Patterns whose files do not affect the gated step. Matched with micromatch against repository-relative paths, with a trailing "/" as the shorthand for a directory (e.g. "experimental/", ".editorconfig", "**.md"). Defaults to ignoring nothing.',
+    }),
+    baseBranch: cmd.option({
+      long: 'base-branch',
+      type: cmd.optional(cmd.string),
+      description:
+        'Base branch to compare against for determining changed files. Defaults to "origin/main"',
+    }),
+  },
+  handler: (args) => {
+    main(args).catch((error: unknown) => {
+      console.error('An error occurred:', error);
+
+      process.exit(1);
+    });
+  },
+});
+
+const main = async (
+  args: Readonly<{
+    pathsIgnore?: readonly string[];
+    baseBranch?: string;
+  }>,
+): Promise<void> => {
+  await checkShouldRun({
+    pathsIgnore: args.pathsIgnore,
+    baseBranch: args.baseBranch,
+  });
+};
+
+await cmd.run(cmdDef, Arr.skip(process.argv, 2));

package/src/functions/should-run.mts

@@ -1,12 +1,118 @@
+import micromatch from 'micromatch';
 import * as fs from 'node:fs/promises';
 import * as path from 'node:path';
-import { Result } from 'ts-data-forge';
-import { getDiffFrom } from './diff.mjs';
+import { castMutable, Result } from 'ts-data-forge';
+import { getDiffFrom, getGitRoot } from './diff.mjs';
+
+/**
+ * Checks whether a CI step should run, based on which files differ from a base
+ * branch. Reports `false` when every changed file matches one of the ignored
+ * patterns.
+ *
+ * This is the general form of {@link checkShouldRunTypeChecks}: it carries no
+ * default ignore list, so the caller states exactly which paths are irrelevant
+ * to the step being gated.
+ *
+ * Prefer gating the individual steps of a workflow with this over a
+ * `paths-ignore` trigger filter: a workflow that a path filter skips never
+ * reports a status check, so a pull request that changed only the filtered
+ * paths waits forever on a required check that will never arrive.
+ *
+ * @example
+ *   ```typescript
+ *   // Skip when the diff only touches a directory nothing checks
+ *   await checkShouldRun({ pathsIgnore: ['experimental/'] });
+ *
+ *   // Custom base branch
+ *   await checkShouldRun({
+ *     pathsIgnore: ['docs/', '**.md'],
+ *     baseBranch: 'origin/develop',
+ *   });
+ *   ```;
+ *
+ * @example
+ *   GitHub Actions usage
+ *   ```yaml
+ *   - name: Check diff
+ *   id: check_diff
+ *   run: npm exec -- check-should-run --paths-ignore 'experimental/'
+ *
+ *   - name: Run the checks
+ *   if: steps.check_diff.outputs.should_run == 'true'
+ *   run: npm run check
+ *   ```
+ *
+ * @param options - Configuration options
+ * @param options.pathsIgnore - Patterns whose files do not affect the step.
+ *   Matched with micromatch (with `dot: true`) against paths relative to the
+ *   repository root, with one shorthand: a pattern ending with `/` is a
+ *   directory prefix, so `docs/` is `docs/**`. Exact file names
+ *   (`.editorconfig`) and ordinary globs (`**.md`, `docs/**`) both work.
+ *   Defaults to `[]`, which ignores nothing.
+ * @param options.baseBranch - Base branch to compare against for determining
+ *   changed files. Defaults to `'origin/main'`
+ * @returns Whether the step should run. An empty diff reads as "nothing
+ *   changed" and so returns `false`. When running in GitHub Actions, also
+ *   appends `should_run=true` or `should_run=false` to the file named by the
+ *   `GITHUB_OUTPUT` environment variable.
+ */
+export const checkShouldRun = async (
+  options?: Readonly<{
+    pathsIgnore?: readonly string[];
+    baseBranch?: string;
+  }>,
+): Promise<boolean> => {
+  const pathsIgnore = options?.pathsIgnore ?? [];
+
+  const baseBranch = options?.baseBranch ?? 'origin/main';
+
+  const GITHUB_OUTPUT = process.env['GITHUB_OUTPUT'];
+
+  const gitRoot = await getGitRoot();
+
+  if (Result.isErr(gitRoot)) {
+    console.error('Error getting the git root:', gitRoot.value);
+
+    process.exit(1);
+  }
+
+  const files = await getDiffFrom(baseBranch);
+
+  if (Result.isErr(files)) {
+    console.error('Error getting diff:', files.value);
+
+    process.exit(1);
+  }
+
+  // `getDiffFrom` returns absolute paths, while the patterns are written
+  // relative to the repository root.
+  const changedFiles = files.value.map((file) =>
+    path.relative(gitRoot.value, file).split(path.sep).join('/'),
+  );
+
+  const patterns = pathsIgnore.map(toMatchPattern);
+
+  const shouldRun: boolean = changedFiles.some(
+    (file) => !micromatch.isMatch(file, castMutable(patterns), { dot: true }),
+  );
+
+  if (GITHUB_OUTPUT !== undefined) {
+    // eslint-disable-next-line security/detect-non-literal-fs-filename
+    await fs.appendFile(GITHUB_OUTPUT, `should_run=${shouldRun}\n`);
+  }
+
+  return shouldRun;
+};
 
 /**
  * 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.
  *
+ * This is {@link checkShouldRun} with an ignore list of the files that a
+ * TypeScript project typically has but never type-checks — documentation,
+ * tooling configuration, license text. Pass `pathsIgnore` to replace that list,
+ * or call {@link checkShouldRun} directly for a step that is not a type check.
+ *
  * 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
@@ -42,7 +148,7 @@ import { getDiffFrom } from './diff.mjs';
  *
  * @param options - Configuration options
  * @param options.pathsIgnore - Array of patterns to ignore when determining if
- *   type checks should run. Supports three pattern types:
+ *   type checks should run. Matched as described in {@link checkShouldRun}:
  *
  *   - **Exact file matches**: e.g., `.cspell.config.yaml` matches only that file
  *   - **Directory prefixes**: e.g., `docs/` matches any file in docs directory
@@ -62,61 +168,30 @@ export const checkShouldRunTypeChecks = async (
     pathsIgnore?: readonly string[];
     baseBranch?: string;
   }>,
-): Promise<boolean> => {
-  const pathsIgnore = options?.pathsIgnore ?? [
-    'LICENSE',
-    '.editorconfig',
-    '.gitignore',
-    '.cspell.json',
-    '.cspell.config.yaml',
-    '.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(baseBranch);
-
-  if (Result.isErr(files)) {
-    console.error('Error getting diff:', files.value);
-
-    process.exit(1);
-  }
-
-  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;
-      }
+): Promise<boolean> =>
+  checkShouldRun({
+    pathsIgnore: options?.pathsIgnore ?? defaultTypeCheckPathsIgnore,
+    baseBranch: options?.baseBranch,
+  });
 
-      // File extension pattern match (pattern starts with '**.')
-      if (pattern.startsWith('**.')) {
-        const extension = pattern.slice(2); // Remove '**'
+const defaultTypeCheckPathsIgnore = [
+  'LICENSE',
+  '.editorconfig',
+  '.gitignore',
+  '.cspell.json',
+  '.cspell.config.yaml',
+  '.markdownlint-cli2.mjs',
+  '.npmignore',
+  '.prettierignore',
+  '.prettierrc',
+  'docs/',
+  '**.md',
+  '**.txt',
+] as const;
 
-        return path.basename(file).endsWith(extension);
-      }
-
-      return false;
-    }),
-  );
-
-  if (GITHUB_OUTPUT !== undefined) {
-    // eslint-disable-next-line security/detect-non-literal-fs-filename
-    await fs.appendFile(GITHUB_OUTPUT, `should_run=${shouldRunTsChecks}\n`);
-  }
-
-  return shouldRunTsChecks;
-};
+/**
+ * Expands the trailing-slash shorthand for a directory into the glob
+ * micromatch needs. Every other pattern is already one.
+ */
+const toMatchPattern = (pattern: string): string =>
+  pattern.endsWith('/') ? (`${pattern}**` as const) : pattern;

package/src/functions/should-run.test.mts

@@ -0,0 +1,196 @@
+import * as fs from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import * as path from 'node:path';
+import { $ } from './exec-async.mjs';
+import { checkShouldRun, checkShouldRunTypeChecks } from './should-run.mjs';
+
+describe('should-run', () => {
+  /**
+   * Creates a repository with one commit, applies `changedFiles` on top of it
+   * (staged, not committed, which `git diff <base>` reports all the same), and
+   * runs `check` from the repository root.
+   */
+  const withChangedFiles = async <T,>(
+    changedFiles: readonly string[],
+    check: (repoRoot: string) => Promise<T>,
+  ): Promise<T> => {
+    const repoPath = await fs.mkdtemp(path.join(tmpdir(), 'should-run-'));
+
+    const originalCwd = process.cwd();
+
+    try {
+      process.chdir(repoPath);
+
+      await $(
+        [
+          'git init --initial-branch=main',
+          'git config user.name "Test User"',
+          'git config user.email "test@example.com"',
+          // The machine running the tests may sign commits by default, which
+          // needs a key this repository does not have.
+          'git config commit.gpgsign false',
+          'git commit --allow-empty -m "initial commit" --no-verify',
+        ].join(' && '),
+        { silent: true },
+      );
+
+      await Promise.all(
+        changedFiles.map(async (file) => {
+          const filePath = path.join(repoPath, file);
+
+          // eslint-disable-next-line security/detect-non-literal-fs-filename
+          await fs.mkdir(path.dirname(filePath), { recursive: true });
+
+          // eslint-disable-next-line security/detect-non-literal-fs-filename
+          await fs.writeFile(filePath, 'content');
+        }),
+      );
+
+      await $('git add --all', { silent: true });
+
+      return await check(repoPath);
+    } finally {
+      process.chdir(originalCwd);
+
+      await fs.rm(repoPath, { recursive: true, force: true });
+    }
+  };
+
+  describe(checkShouldRun, () => {
+    test('should report false when every changed file is ignored', async () => {
+      const result = await withChangedFiles(
+        ['experimental/a/b.mts', 'experimental/c.md'],
+        async () =>
+          checkShouldRun({
+            pathsIgnore: ['experimental/'],
+            baseBranch: 'HEAD',
+          }),
+      );
+
+      assert.isFalse(result);
+    });
+
+    test('should report true when one changed file is not ignored', async () => {
+      const result = await withChangedFiles(
+        ['experimental/a/b.mts', 'libs/x/src/a.mts'],
+        async () =>
+          checkShouldRun({
+            pathsIgnore: ['experimental/'],
+            baseBranch: 'HEAD',
+          }),
+      );
+
+      assert.isTrue(result);
+    });
+
+    test('should report true when nothing is ignored', async () => {
+      const result = await withChangedFiles(['experimental/a.mts'], async () =>
+        checkShouldRun({ baseBranch: 'HEAD' }),
+      );
+
+      assert.isTrue(result);
+    });
+
+    test('should report false when nothing changed', async () => {
+      const result = await withChangedFiles([], async () =>
+        checkShouldRun({ pathsIgnore: ['experimental/'], baseBranch: 'HEAD' }),
+      );
+
+      assert.isFalse(result);
+    });
+
+    test('should match patterns against repository-relative paths', async () => {
+      // Every pattern kind at once: an exact file name, a directory prefix,
+      // an extension glob, and a glob with a wildcard segment. All four are
+      // relative to the repository root, so a file outside `docs/` is not
+      // ignored by the `docs/` pattern even though its own path contains it.
+      const result = await withChangedFiles(
+        ['LICENSE', 'docs/a.yml', 'a/b.md', 'libs/x/docs/note.yml'],
+        async () =>
+          checkShouldRun({
+            pathsIgnore: ['LICENSE', 'docs/', '**.md', 'libs/*/docs/**'],
+            baseBranch: 'HEAD',
+          }),
+      );
+
+      assert.isFalse(result);
+    });
+
+    test('should not ignore a file that only shares a prefix with a directory pattern', async () => {
+      const result = await withChangedFiles(['docs-site/a.yml'], async () =>
+        checkShouldRun({ pathsIgnore: ['docs/'], baseBranch: 'HEAD' }),
+      );
+
+      assert.isTrue(result);
+    });
+
+    test('should match dotfiles', async () => {
+      const result = await withChangedFiles(
+        ['.changeset/happy-pandas-sing.md', '.editorconfig'],
+        async () =>
+          checkShouldRun({
+            pathsIgnore: ['**.md', '.editorconfig'],
+            baseBranch: 'HEAD',
+          }),
+      );
+
+      assert.isFalse(result);
+    });
+
+    test('should write the result to GITHUB_OUTPUT', async () => {
+      const contents = await withChangedFiles(
+        ['experimental/a.mts'],
+        async (repoPath) => {
+          const outputPath = path.join(repoPath, 'github-output.txt');
+
+          vi.stubEnv('GITHUB_OUTPUT', outputPath);
+
+          try {
+            await checkShouldRun({
+              pathsIgnore: ['experimental/'],
+              baseBranch: 'HEAD',
+            });
+
+            // eslint-disable-next-line security/detect-non-literal-fs-filename
+            return await fs.readFile(outputPath, 'utf8');
+          } finally {
+            vi.unstubAllEnvs();
+          }
+        },
+      );
+
+      assert.deepStrictEqual(contents, 'should_run=false\n');
+    });
+  });
+
+  describe(checkShouldRunTypeChecks, () => {
+    test('should ignore documentation and tooling configuration by default', async () => {
+      const result = await withChangedFiles(
+        ['README.md', 'LICENSE', 'docs/design.md', '.prettierrc', 'notes.txt'],
+        async () => checkShouldRunTypeChecks({ baseBranch: 'HEAD' }),
+      );
+
+      assert.isFalse(result);
+    });
+
+    test('should report true when a source file changed', async () => {
+      const result = await withChangedFiles(
+        ['README.md', 'libs/x/src/a.mts'],
+        async () => checkShouldRunTypeChecks({ baseBranch: 'HEAD' }),
+      );
+
+      assert.isTrue(result);
+    });
+
+    test('should replace the default ignore list when pathsIgnore is given', async () => {
+      const result = await withChangedFiles(['README.md'], async () =>
+        checkShouldRunTypeChecks({
+          pathsIgnore: ['experimental/'],
+          baseBranch: 'HEAD',
+        }),
+      );
+
+      assert.isTrue(result);
+    });
+  });
+});

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

@@ -7,13 +7,10 @@ import {
   isRecord,
   isString,
   Json,
+  Obj,
   Result,
 } from 'ts-data-forge';
-import {
-  type JsonValue,
-  type MutableFixedLengthTuple,
-  type ReadonlyRecord,
-} from 'ts-type-forge';
+import { type JsonValue, type ReadonlyRecord } from 'ts-type-forge';
 import { glob } from '../glob.mjs';
 import {
   defaultDependencyFields,
@@ -137,9 +134,5 @@ const getKeyValueRecordFromJsonValue = (
     return {};
   }
 
-  const entries = Object.entries(obj).filter(
-    (entry): entry is MutableFixedLengthTuple<2, string> => isString(entry[1]),
-  );
-
-  return Object.fromEntries(entries);
+  return Obj.filter(obj, isString);
 };