docs: JSDoc for 30 exported functions + real LRU in glob matcher cache

Adds concise JSDoc blocks to exports in agent, stdio, suppress-warnings,
utils/get-ipc, and the constants/ getters that were previously bare.
Predicates like supports*() now state the Node version threshold; flag
helpers document what's included in the returned array; abort helpers
document their singleton semantics.

Also rewrites globs.ts getGlobMatcher LRU cache: the separate
matcherAccessOrder array (with O(n) indexOf/splice on every hit) was
expensive and brittle. Replace with a Map whose insertion-order
iteration is the recency order — O(1) touch-on-read, O(1) eviction —
mirroring the pattern applied to git.ts in the previous commit.

Final @fileoverview coverage on src/ (excluding external/ and types/):
100%. Remaining undoc'd exports: two getIpc overload signatures (the
primary overload carries the JSDoc that applies to all three).

Author: jdalton

src/agent.ts

@@ -437,6 +437,17 @@ export interface ExecScriptOptions extends SpawnOptions {
   prepost?: boolean | undefined
 }
 
+/**
+ * Execute a package.json script using the detected package manager.
+ * Picks pnpm, npm, or yarn by walking up to the nearest lockfile; falls back
+ * to running `node --run` or `npm run` directly when no lockfile is found.
+ * Honors `shell: true` by passing through to `spawn()` unchanged.
+ *
+ * @param scriptName - The package.json script to run
+ * @param args - Either the script arguments or an options object
+ * @param options - Spawn options plus `prepost` to force npm-style pre/post scripts
+ * @returns The spawned `ChildProcess`-like promise from the underlying runner.
+ */
 export function execScript(
   scriptName: string,
   args?: string[] | readonly string[] | ExecScriptOptions | undefined,

src/constants/licenses.ts

@@ -11,6 +11,12 @@ export const UNLICENSED = 'UNLICENSED'
 
 // Copy-left licenses.
 let _copyLeftLicenses: Set<string>
+/**
+ * Get the set of SPDX identifiers considered copy-left (AGPL, GPL, EPL,
+ * EUPL, CC-BY-SA variants). The set is lazily built and cached on first call.
+ *
+ * @returns A `Set` of SPDX license identifier strings.
+ */
 export function getCopyLeftLicenses(): Set<string> {
   if (_copyLeftLicenses === undefined) {
     _copyLeftLicenses = new Set([

src/constants/node.ts

@@ -11,59 +11,126 @@ import { maintainedNodeVersions } from './maintained-node-versions'
 const NODE_VERSION = process.version
 
 // Version detection.
+/**
+ * Get the full Node.js version string from `process.version`.
+ *
+ * @returns The runtime version, including the leading `v` (e.g. `v22.11.0`).
+ */
 export function getNodeVersion(): string {
   return NODE_VERSION
 }
 
+/**
+ * Get the major component of the current Node.js version.
+ *
+ * @returns The major version number, or `0` if it cannot be parsed.
+ */
 export function getNodeMajorVersion(): number {
   const major = NODE_VERSION.slice(1).split('.')[0] ?? '0'
   return Number.parseInt(major, 10) || 0
 }
 
+/**
+ * Get the minor component of the current Node.js version.
+ *
+ * @returns The minor version number, or `0` if it cannot be parsed.
+ */
 export function getNodeMinorVersion(): number {
   return Number.parseInt(NODE_VERSION.split('.')[1] ?? '0', 10)
 }
 
+/**
+ * Get the patch component of the current Node.js version.
+ *
+ * @returns The patch version number, or `0` if it cannot be parsed.
+ */
 export function getNodePatchVersion(): number {
   return Number.parseInt(NODE_VERSION.split('.')[2] ?? '0', 10)
 }
 
 // Maintained Node.js versions.
+/**
+ * Get the list of Node.js major versions currently under long-term support.
+ *
+ * @returns The static `maintainedNodeVersions` array shared across the library.
+ */
 export function getMaintainedNodeVersions() {
   return maintainedNodeVersions
 }
 
 // Feature detection.
+/**
+ * Check whether the current runtime exposes the `module.enableCompileCache()` API.
+ * The API is available on Node.js 24+.
+ *
+ * @returns `true` when the current runtime is Node.js 24 or newer.
+ */
 export function supportsNodeCompileCacheApi(): boolean {
   const major = getNodeMajorVersion()
   return major >= 24
 }
 
+/**
+ * Check whether the current runtime honors the `NODE_COMPILE_CACHE` env var.
+ * Env-var-based compile caching is available on Node.js 22+.
+ *
+ * @returns `true` when the current runtime is Node.js 22 or newer.
+ */
 export function supportsNodeCompileCacheEnvVar(): boolean {
   const major = getNodeMajorVersion()
   return major >= 22
 }
 
+/**
+ * Check whether the current runtime supports the `--disable-warning` CLI flag.
+ * The flag is available on Node.js 21+.
+ *
+ * @returns `true` when the current runtime is Node.js 21 or newer.
+ */
 export function supportsNodeDisableWarningFlag(): boolean {
   const major = getNodeMajorVersion()
   return major >= 21
 }
 
+/**
+ * Check whether the current runtime supports the permission model CLI flags
+ * (`--experimental-permission` on Node 20-23, `--permission` on Node 24+).
+ *
+ * @returns `true` when the current runtime is Node.js 20 or newer.
+ */
 export function supportsNodePermissionFlag(): boolean {
   const major = getNodeMajorVersion()
   return major >= 20
 }
 
+/**
+ * Check whether `require()` can synchronously load ESM modules.
+ * Requires Node.js 22.12+ or Node.js 23+.
+ *
+ * @returns `true` when the runtime supports `require()`-ing ES modules.
+ */
 export function supportsNodeRequireModule(): boolean {
   const major = getNodeMajorVersion()
   return major >= 23 || (major === 22 && getNodeMinorVersion() >= 12)
 }
 
+/**
+ * Check whether the current runtime supports `node --run <script>`.
+ * Requires Node.js 22.11+ or Node.js 23+.
+ *
+ * @returns `true` when the runtime can execute package.json scripts via `--run`.
+ */
 export function supportsNodeRun(): boolean {
   const major = getNodeMajorVersion()
   return major >= 23 || (major === 22 && getNodeMinorVersion() >= 11)
 }
 
+/**
+ * Check whether the current runtime supports the `--disable-sigusr1` CLI flag.
+ * Flag landed in v22.14.0 and v23.7.0 and was stabilized in v22.20.0 / v24.8.0.
+ *
+ * @returns `true` when the runtime exposes `--disable-sigusr1`.
+ */
 export function supportsNodeDisableSigusr1Flag(): boolean {
   const major = getNodeMajorVersion()
   const minor = getNodeMinorVersion()
@@ -82,6 +149,13 @@ export function supportsNodeDisableSigusr1Flag(): boolean {
 }
 
 let _nodeDisableSigusr1Flags: string[]
+/**
+ * Get the flags used to block Node.js debugger attachment via SIGUSR1.
+ * Returns `['--disable-sigusr1']` on runtimes that support it and falls back
+ * to `['--no-inspect']` on older versions.
+ *
+ * @returns A non-empty array of CLI flags suitable for passing to `node`.
+ */
 export function getNodeDisableSigusr1Flags(): string[] {
   if (_nodeDisableSigusr1Flags === undefined) {
     // SIGUSR1 is reserved by Node.js for starting the debugger/inspector.
@@ -99,13 +173,27 @@ export function getNodeDisableSigusr1Flags(): string[] {
   return _nodeDisableSigusr1Flags
 }
 
+/**
+ * Check whether this process was spawned with an IPC channel.
+ * When `true`, `process.send()` is callable to message the parent process.
+ *
+ * @returns `true` when the current process has an IPC channel to its parent.
+ */
 export function supportsProcessSend(): boolean {
   return typeof process.send === 'function'
 }
 
 // Node.js flags.
 let _nodeHardenFlags: string[]
 let _nodePermissionFlags: string[]
+/**
+ * Get the permission-grant flags needed to run npm under Node.js 24+'s
+ * `--permission` model. The array is non-empty only on Node.js 24+ and
+ * includes `--allow-fs-read=*`, `--allow-fs-write=*`, and
+ * `--allow-child-process`. Older versions return an empty array.
+ *
+ * @returns The permission flag list (possibly empty) for the current runtime.
+ */
 export function getNodePermissionFlags(): string[] {
   if (_nodePermissionFlags === undefined) {
     const major = getNodeMajorVersion()
@@ -129,6 +217,15 @@ export function getNodePermissionFlags(): string[] {
   return _nodePermissionFlags
 }
 
+/**
+ * Get the hardening flags Socket applies when spawning Node.js subprocesses.
+ * Always includes `--disable-proto=delete`. Also adds `--permission` plus the
+ * grants from {@link getNodePermissionFlags} on Node 24+,
+ * `--experimental-permission` on Node 20-23, and
+ * `--force-node-api-uncaught-exceptions-policy` on Node 22+.
+ *
+ * @returns A non-empty array of CLI flags suitable for passing to `node`.
+ */
 export function getNodeHardenFlags(): string[] {
   if (_nodeHardenFlags === undefined) {
     const major = getNodeMajorVersion()
@@ -156,6 +253,12 @@ export function getNodeHardenFlags(): string[] {
 }
 
 let _nodeNoWarningsFlags: string[]
+/**
+ * Get the flags that silence Node.js runtime warnings and deprecation notices.
+ * Always returns `['--no-warnings', '--no-deprecation']` across all versions.
+ *
+ * @returns A non-empty array of CLI flags suitable for passing to `node`.
+ */
 export function getNodeNoWarningsFlags(): string[] {
   if (_nodeNoWarningsFlags === undefined) {
     _nodeNoWarningsFlags = ['--no-warnings', '--no-deprecation']
@@ -164,6 +267,11 @@ export function getNodeNoWarningsFlags(): string[] {
 }
 
 // Execution path.
+/**
+ * Get the absolute path to the currently running Node.js binary.
+ *
+ * @returns The value of `process.execPath`.
+ */
 export function getExecPath(): string {
   return process.execPath
 }

src/constants/process.ts

@@ -6,13 +6,26 @@
 
 // Abort controller and signal.
 let _abortController: AbortController
+/**
+ * Get the process-scoped shared `AbortController` singleton.
+ * Cooperating modules use this to coordinate cancellation across the library.
+ *
+ * @returns The lazily-created shared `AbortController` instance.
+ */
 export function getAbortController(): AbortController {
   if (_abortController === undefined) {
     _abortController = new AbortController()
   }
   return _abortController
 }
 
+/**
+ * Get the process-scoped shared `AbortSignal` singleton.
+ * This is the `signal` property of {@link getAbortController}'s controller and
+ * is intended to be passed to APIs that accept an `AbortSignal`.
+ *
+ * @returns The shared `AbortSignal` instance.
+ */
 export function getAbortSignal(): AbortSignal {
   return getAbortController().signal
 }

src/constants/typescript.ts

@@ -14,6 +14,12 @@ export function getTsTypesAvailable(): boolean {
   }
 }
 
+/**
+ * Check whether TypeScript's `lib/` directory is resolvable from the current
+ * project by probing `typescript/lib`.
+ *
+ * @returns `true` when the `typescript` package's libs can be resolved.
+ */
 export function getTsLibsAvailable(): boolean {
   try {
     require.resolve('typescript/lib')

src/globs.ts

@@ -153,29 +153,34 @@ export function globStreamLicenses(
 }
 
 const MATCHER_CACHE_MAX_SIZE = 100
+// LRU cache. We exploit Map's insertion-order iteration so eviction is O(1):
+// delete the first key. On read, delete + set moves the entry to the back,
+// keeping the cache in recency order.
 const matcherCache = new Map<string, (path: string) => boolean>()
-const matcherAccessOrder: string[] = []
-
-function evictLRUMatcher() {
-  if (
-    matcherCache.size >= MATCHER_CACHE_MAX_SIZE &&
-    matcherAccessOrder.length > 0
-  ) {
-    const oldest = matcherAccessOrder.shift()
-    if (oldest) {
-      matcherCache.delete(oldest)
-    }
-  }
-}
 
 /**
- * Get a cached glob matcher function.
+ * Return a glob-matcher function, memoized by pattern + options.
+ *
+ * The returned function is a fast synchronous predicate built on picomatch.
+ * Results are memoized — calling `getGlobMatcher(['*.ts'])` a thousand times
+ * in a loop returns the same compiled matcher each time, so callers do not
+ * need to hoist it themselves.
+ *
+ * The cache is LRU with a cap of 100 entries. Cache keys fold together the
+ * (sorted) pattern list and (sorted) option set, so arguments that differ
+ * only in ordering share a matcher.
+ *
+ * Default options: `dot: true`, `nocase: true`. Patterns starting with `!`
+ * become ignore patterns.
  *
  * @example
  * ```typescript
  * const isMatch = getGlobMatcher('*.ts')
  * isMatch('index.ts')  // true
  * isMatch('index.js')  // false
+ *
+ * // With negation
+ * const isSource = getGlobMatcher(['src/**', '!**\/*.test.ts'])
  * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
@@ -193,19 +198,21 @@ export function getGlobMatcher(
         .join(',')
     : ''
   const key = `${sortedPatterns.join('|')}:${sortedOptions}`
-  let matcher: ((path: string) => boolean) | undefined = matcherCache.get(key)
-  if (matcher) {
-    // Move to end of access order (LRU)
-    const index = matcherAccessOrder.indexOf(key)
-    if (index !== -1) {
-      matcherAccessOrder.splice(index, 1)
-      matcherAccessOrder.push(key)
-    }
-    return matcher
+  const existing = matcherCache.get(key)
+  if (existing) {
+    // Re-insert to mark as most-recently-used.
+    matcherCache.delete(key)
+    matcherCache.set(key, existing)
+    return existing
   }
 
-  // Evict oldest entry if cache is full
-  evictLRUMatcher()
+  // Evict oldest entry if cache is full (Map iteration order = insertion order).
+  if (matcherCache.size >= MATCHER_CACHE_MAX_SIZE) {
+    const oldest = matcherCache.keys().next().value
+    if (oldest !== undefined) {
+      matcherCache.delete(oldest)
+    }
+  }
 
   // Separate positive and negative patterns.
   const positivePatterns = patterns.filter(p => !p.startsWith('!'))
@@ -223,13 +230,12 @@ export function getGlobMatcher(
 
   /* c8 ignore next 5 - External picomatch call */
   const picomatch = getPicomatch()
-  matcher = picomatch(
+  const matcher = picomatch(
     positivePatterns.length > 0 ? positivePatterns : patterns,
     matchOptions,
   ) as (path: string) => boolean
 
   matcherCache.set(key, matcher)
-  matcherAccessOrder.push(key)
   return matcher
 }
 

src/stdio/clear.ts

@@ -21,6 +21,13 @@
  * ```
  */
 import process from 'node:process'
+/**
+ * Clear the current line on the given stream.
+ * Uses native TTY methods when available and falls back to `\r\x1b[K` ANSI
+ * escapes on non-TTY streams.
+ *
+ * @param stream - Output stream to clear (defaults to `process.stdout`)
+ */
 export function clearLine(stream: NodeJS.WriteStream = process.stdout): void {
   if (stream.isTTY) {
     // TTY: Use cursor control