refactor: source-order alphabetize functions across remaining 43 modules

Completes the source-order pass started in the prior commit for the 9
core modules. Every file with 3+ function definitions now has:

  private (non-exported) functions in alphabetical order, then
  exported functions in alphabetical order.

Exports stay inline at their definitions — no bottom re-export lists.
debug.ts in particular had a bottom `export { debug }` block that is
now gone; each function carries `export` inline.

Comparison is case-insensitive with ASCII tiebreak (so `debugLog`
precedes `debuglog` when the lowercased names match).

Function bodies, JSDoc blocks, and /*@__NO_SIDE_EFFECTS__*/ pragmas
move as atomic units. Overloaded signature groups (e.g. `safeReadFile`
overloads + implementation) move together as one block sorted by the
shared name. Lazy-init caches (`let _cacheX` module vars) hoist to the
top-of-file declaration block.

Also: generate-api-index.mts now spawns oxfmt via
@socketsecurity/lib-stable/spawn to align the emitted markdown's
table columns with the formatter's expectations — previously the
generated file failed oxfmt --check on every rebuild.

Author: jdalton

docs/api-index.md

@@ -7,10 +7,14 @@
 
 import { readFileSync, writeFileSync } from 'node:fs'
 import path from 'node:path'
+import process from 'node:process'
 import { fileURLToPath } from 'node:url'
 
+import { spawn } from '@socketsecurity/lib-stable/spawn'
+
 const __dirname = path.dirname(fileURLToPath(import.meta.url))
 const rootPath = path.join(__dirname, '..', '..')
+const WIN32 = process.platform === 'win32'
 
 type PackageExports = Record<
   string,
@@ -147,7 +151,7 @@ function renderMarkdown(groups: Map<string, Row[]>): string {
   return lines.join('\n')
 }
 
-function main(): void {
+async function main(): Promise<void> {
   const pkg = JSON.parse(
     readFileSync(path.join(rootPath, 'package.json'), 'utf8'),
   ) as { exports: PackageExports }
@@ -157,8 +161,23 @@ function main(): void {
   const markdown = renderMarkdown(groups)
   const outPath = path.join(rootPath, 'docs', 'api-index.md')
   writeFileSync(outPath, markdown)
+  // Run oxfmt so the checked-in file matches the formatter's expectations
+  // (table column alignment, etc.) — otherwise lint fails on every build.
+  try {
+    await spawn('pnpm', ['exec', 'oxfmt', outPath], {
+      cwd: rootPath,
+      shell: WIN32,
+      stdio: 'ignore',
+    })
+  } catch {
+    // Formatting is best-effort — don't fail the build if oxfmt is missing.
+  }
   // eslint-disable-next-line no-console
   console.log(`Wrote ${rows.length} exports to docs/api-index.md`)
 }
 
-main()
+main().catch(err => {
+  // eslint-disable-next-line no-console
+  console.error(err)
+  process.exitCode = 1
+})

scripts/fix/generate-api-index.mts

@@ -90,6 +90,19 @@ const yarnInstallLikeCommands = new Set([
   'import',
 ])
 
+export interface PnpmOptions extends SpawnOptions {
+  allowLockfileUpdate?: boolean
+}
+
+export interface ExecScriptOptions extends SpawnOptions {
+  prepost?: boolean | undefined
+}
+
+/**
+ * Alias for isNpmLoglevelFlag for pnpm usage.
+ */
+export const isPnpmLoglevelFlag = isNpmLoglevelFlag
+
 /**
  * Execute npm commands with optimized flags and settings.
  *
@@ -154,10 +167,6 @@ export function execNpm(args: string[], options?: SpawnOptions | undefined) {
   )
 }
 
-export interface PnpmOptions extends SpawnOptions {
-  allowLockfileUpdate?: boolean
-}
-
 /**
  * Execute pnpm commands with optimized flags and settings.
  *
@@ -231,6 +240,83 @@ export function execPnpm(args: string[], options?: PnpmOptions | 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,
+  options?: ExecScriptOptions | undefined,
+) {
+  // Handle overloaded signatures: execScript(name, options) or execScript(name, args, options).
+  let resolvedOptions: ExecScriptOptions | undefined
+  let resolvedArgs: string[]
+  if (!Array.isArray(args) && args !== null && typeof args === 'object') {
+    resolvedOptions = args as ExecScriptOptions
+    resolvedArgs = []
+  } else {
+    resolvedOptions = options
+    resolvedArgs = (args || []) as string[]
+  }
+  const { prepost, ...spawnOptions } = {
+    __proto__: null,
+    ...resolvedOptions,
+  } as ExecScriptOptions
+
+  // If shell: true is passed, run the command directly as a shell command.
+  if (spawnOptions.shell === true) {
+    return spawn(scriptName, resolvedArgs, spawnOptions)
+  }
+
+  const useNodeRun = !prepost && supportsNodeRun()
+
+  // Detect package manager based on lockfile by traversing up from current directory.
+  const cwd =
+    (getOwn(spawnOptions, 'cwd') as string | undefined) ?? process.cwd()
+
+  // Check for pnpm-lock.yaml.
+  const pnpmLockPath = findUpSync(PNPM_LOCK_YAML, { cwd }) as string | undefined
+  if (pnpmLockPath) {
+    return execPnpm(['run', scriptName, ...resolvedArgs], spawnOptions)
+  }
+
+  // Check for package-lock.json.
+  // When in an npm workspace, use npm run to ensure workspace binaries are available.
+  const packageLockPath = findUpSync(PACKAGE_LOCK_JSON, { cwd }) as
+    | string
+    | undefined
+  if (packageLockPath) {
+    return execNpm(['run', scriptName, ...resolvedArgs], spawnOptions)
+  }
+
+  // Check for yarn.lock.
+  const yarnLockPath = findUpSync(YARN_LOCK, { cwd }) as string | undefined
+  if (yarnLockPath) {
+    return execYarn(['run', scriptName, ...resolvedArgs], spawnOptions)
+  }
+
+  return spawn(
+    getExecPath(),
+    [
+      ...getNodeNoWarningsFlags(),
+      ...(useNodeRun ? ['--run'] : [NPM_REAL_EXEC_PATH, 'run']),
+      scriptName,
+      ...resolvedArgs,
+    ],
+    {
+      ...spawnOptions,
+    },
+  )
+}
+
 /**
  * Execute yarn commands with optimized flags and settings.
  *
@@ -374,33 +460,33 @@ export function isNpmProgressFlag(cmdArg: string): boolean {
 }
 
 /**
- * Check if a command argument is a pnpm ignore-scripts flag.
+ * Check if a command argument is a pnpm frozen-lockfile flag.
  *
  * @example
  * ```typescript
- * isPnpmIgnoreScriptsFlag('--ignore-scripts')     // true
- * isPnpmIgnoreScriptsFlag('--no-ignore-scripts')  // true
- * isPnpmIgnoreScriptsFlag('--save')               // false
+ * isPnpmFrozenLockfileFlag('--frozen-lockfile')     // true
+ * isPnpmFrozenLockfileFlag('--no-frozen-lockfile')  // true
+ * isPnpmFrozenLockfileFlag('--save')                // false
  * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
-export function isPnpmIgnoreScriptsFlag(cmdArg: string): boolean {
-  return pnpmIgnoreScriptsFlags.has(cmdArg)
+export function isPnpmFrozenLockfileFlag(cmdArg: string): boolean {
+  return pnpmFrozenLockfileFlags.has(cmdArg)
 }
 
 /**
- * Check if a command argument is a pnpm frozen-lockfile flag.
+ * Check if a command argument is a pnpm ignore-scripts flag.
  *
  * @example
  * ```typescript
- * isPnpmFrozenLockfileFlag('--frozen-lockfile')     // true
- * isPnpmFrozenLockfileFlag('--no-frozen-lockfile')  // true
- * isPnpmFrozenLockfileFlag('--save')                // false
+ * isPnpmIgnoreScriptsFlag('--ignore-scripts')     // true
+ * isPnpmIgnoreScriptsFlag('--no-ignore-scripts')  // true
+ * isPnpmIgnoreScriptsFlag('--save')               // false
  * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
-export function isPnpmFrozenLockfileFlag(cmdArg: string): boolean {
-  return pnpmFrozenLockfileFlags.has(cmdArg)
+export function isPnpmIgnoreScriptsFlag(cmdArg: string): boolean {
+  return pnpmIgnoreScriptsFlags.has(cmdArg)
 }
 
 /**
@@ -417,99 +503,3 @@ export function isPnpmFrozenLockfileFlag(cmdArg: string): boolean {
 export function isPnpmInstallCommand(cmdArg: string): boolean {
   return pnpmInstallCommands.has(cmdArg)
 }
-
-/**
- * Alias for isNpmLoglevelFlag for pnpm usage.
- */
-export const isPnpmLoglevelFlag = isNpmLoglevelFlag
-
-/**
- * Execute a package.json script using the appropriate package manager.
- * Automatically detects pnpm, yarn, or npm based on lockfiles.
- *
- * @example
- * ```typescript
- * await execScript('build')
- * await execScript('test', ['--coverage'], { cwd: '/tmp/project' })
- * ```
- */
-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,
-  options?: ExecScriptOptions | undefined,
-) {
-  // Handle overloaded signatures: execScript(name, options) or execScript(name, args, options).
-  let resolvedOptions: ExecScriptOptions | undefined
-  let resolvedArgs: string[]
-  if (!Array.isArray(args) && args !== null && typeof args === 'object') {
-    resolvedOptions = args as ExecScriptOptions
-    resolvedArgs = []
-  } else {
-    resolvedOptions = options
-    resolvedArgs = (args || []) as string[]
-  }
-  const { prepost, ...spawnOptions } = {
-    __proto__: null,
-    ...resolvedOptions,
-  } as ExecScriptOptions
-
-  // If shell: true is passed, run the command directly as a shell command.
-  if (spawnOptions.shell === true) {
-    return spawn(scriptName, resolvedArgs, spawnOptions)
-  }
-
-  const useNodeRun = !prepost && supportsNodeRun()
-
-  // Detect package manager based on lockfile by traversing up from current directory.
-  const cwd =
-    (getOwn(spawnOptions, 'cwd') as string | undefined) ?? process.cwd()
-
-  // Check for pnpm-lock.yaml.
-  const pnpmLockPath = findUpSync(PNPM_LOCK_YAML, { cwd }) as string | undefined
-  if (pnpmLockPath) {
-    return execPnpm(['run', scriptName, ...resolvedArgs], spawnOptions)
-  }
-
-  // Check for package-lock.json.
-  // When in an npm workspace, use npm run to ensure workspace binaries are available.
-  const packageLockPath = findUpSync(PACKAGE_LOCK_JSON, { cwd }) as
-    | string
-    | undefined
-  if (packageLockPath) {
-    return execNpm(['run', scriptName, ...resolvedArgs], spawnOptions)
-  }
-
-  // Check for yarn.lock.
-  const yarnLockPath = findUpSync(YARN_LOCK, { cwd }) as string | undefined
-  if (yarnLockPath) {
-    return execYarn(['run', scriptName, ...resolvedArgs], spawnOptions)
-  }
-
-  return spawn(
-    getExecPath(),
-    [
-      ...getNodeNoWarningsFlags(),
-      ...(useNodeRun ? ['--run'] : [NPM_REAL_EXEC_PATH, 'run']),
-      scriptName,
-      ...resolvedArgs,
-    ],
-    {
-      ...spawnOptions,
-    },
-  )
-}