chore(lint): clear socket/* + eslint findings to current fleet ruleset

Resolve the full lint backlog (0 errors, 0 warnings repo-wide):

- optional-explicit-undefined (14): add `| undefined` to optional
  property types across src/ (auth, github, go/import-finder,
  go/mod-parser, go/wasm-executor, decorations, parse-externals,
  purl-alerts manager) to pair with exactOptionalPropertyTypes.
- no-underscore-dangle (2): justify-disable `_pendingEvent` in
  go/wasm-executor — the Go wasm ABI runtime reads/writes the field by
  that exact name; renaming breaks the syscall contract.
- prefer-spawn-over-execsync (5): migrate scripts/{check,test,lint}.mts
  from execSync/execFileSync to spawnSync (array args, no shell) from
  @socketsecurity/lib-stable; check.mts adopts the current fleet shape.
- prefer-ellipsis-char (2): `...` → `…` in lint.mts progress logs.
- no-underscore-dangle (2 in paths.mts): inline
  path.dirname(fileURLToPath(import.meta.url)) instead of named
  __dirname/__filename.
- prefer-node-modules-dot-cache (1): vitest exclude uses the
  `.{idea,git,cache,…}` brace form instead of a bare `.cache/` path.

Assisted-by: Claude Code:opus-4-7

Author: jdalton

.config/vitest.config.mts

@@ -1,5 +1,5 @@
 /**
- * @fileoverview Vitest configuration.
+ * @file Vitest configuration.
  */
 import process from 'node:process'
 
@@ -27,7 +27,7 @@ export default defineConfig({
       '**/node_modules/**',
       '**/dist/**',
       '**/out/**',
-      '**/.cache/**',
+      '**/.{idea,git,cache,output,temp}/**',
       '**/.claude/**',
     ],
     reporters: ['default'],

scripts/check.mts

@@ -1,38 +1,62 @@
 /**
- * @fileoverview Unified check runner — delegates to lint + type +
- * path-hygiene.
- *
- * Forwards CLI scope flags to the lint script so `pnpm run check --all`
- * actually runs a full-scope lint (not the default modified-only scope).
- * `pnpm type` doesn't accept our scope flags, so it's always a full
- * check.
- *
- * Usage:
- *   pnpm run check              # lint in modified scope + full type
- *                                 check + path-hygiene
- *   pnpm run check --staged     # lint staged + full type + paths
- *   pnpm run check --all        # full lint + full type + paths (CI)
- *
- * Byte-identical across every fleet repo. Sync-scaffolding flags drift.
+ * @file Unified check runner — delegates to lint + type + path-hygiene.
+ *   Forwards CLI scope flags to the lint script so `pnpm run check --all`
+ *   actually runs a full-scope lint (not the default modified-only scope).
+ *   `pnpm type` doesn't accept our scope flags, so it's always a full check.
+ *   Usage: pnpm run check # lint in modified scope + full type check +
+ *   path-hygiene pnpm run check --staged # lint staged + full type + paths pnpm
+ *   run check --all # full lint + full type + paths (CI) Byte-identical across
+ *   every fleet repo. Sync-scaffolding flags drift.
  */
 
-import { execSync } from 'node:child_process'
+// prefer-async-spawn: sync-required — top-level CLI runner; entire
+// flow is sequential gate-running with exit-code aggregation.
+import { spawnSync } from '@socketsecurity/lib-stable/process/spawn/child'
 import process from 'node:process'
 
 const args = process.argv.slice(2)
 const forwardedArgs = args.filter(
   a => a === '--all' || a === '--fix' || a === '--quiet' || a === '--staged',
 )
 
-try {
-  const lintArgs = forwardedArgs.length ? ' ' + forwardedArgs.join(' ') : ''
-  execSync(`node scripts/lint.mts${lintArgs}`, { stdio: 'inherit' })
-  execSync('pnpm exec tsgo --noEmit -p tsconfig.check.json', {
-    stdio: 'inherit',
-  })
+// spawnSync with array args — no shell interpolation, matches the
+// socket/prefer-spawn-over-execsync rule.
+export function run(cmd: string, cmdArgs: string[]): boolean {
+  const r = spawnSync(cmd, cmdArgs, { stdio: 'inherit' })
+  return r.status === 0
+}
+
+const steps: Array<() => boolean> = [
+  // Lint scope is forwarded; everything else is full-scope.
+  () => run('node', ['scripts/lint.mts', ...forwardedArgs]),
+  () => run('pnpm', ['exec', 'tsgo', '--noEmit', '-p', 'tsconfig.check.json']),
   // Path-hygiene check (1 path, 1 reference). Mantra-driven gate;
   // see .claude/skills/path-guard/ + .claude/hooks/path-guard/.
-  execSync('node scripts/check-paths.mts --quiet', { stdio: 'inherit' })
-} catch {
-  process.exitCode = 1
+  () => run('node', ['scripts/check-paths.mts', '--quiet']),
+  // Lock-step reference hygiene. Opt-in gate that exits clean when
+  // .config/lock-step-refs.json is absent; for repos that ship
+  // cross-language ports (acorn quadruplet, socket-btm mcp/*.cpp),
+  // it validates every `Lock-step with <Lang>: <path>` comment resolves
+  // to an existing file. Forms documented in
+  // docs/claude.md/fleet/parser-comments.md §5–6.
+  () => run('node', ['scripts/check-lock-step-refs.mts', '--quiet']),
+  // Lock-step header byte-equality. Same opt-in. Where the path-refs
+  // gate above catches stale REFERENCES, this one catches drift in the
+  // top-of-file `BEGIN LOCK-STEP HEADER` / `END LOCK-STEP HEADER` block
+  // — the intent tripwire across the quadruplet. Spec:
+  // docs/claude.md/fleet/parser-comments.md §7.
+  () => run('node', ['scripts/check-lock-step-header.mts', '--quiet']),
+  // Soak-exclude date-annotation gate — pairs with
+  // .claude/hooks/soak-exclude-date-annotation-guard/. Catches
+  // pnpm-workspace.yaml `minimumReleaseAgeExclude` entries that landed
+  // via non-Claude paths without the canonical
+  // `# published: YYYY-MM-DD | removable: YYYY-MM-DD` annotation.
+  () => run('node', ['scripts/check-soak-exclude-dates.mts']),
+]
+
+for (let i = 0, { length } = steps; i < length; i += 1) {
+  if (!steps[i]!()) {
+    process.exitCode = 1
+    break
+  }
 }

scripts/lint.mts

@@ -13,8 +13,8 @@
  *   contract so pre-commit hooks and CI work identically across repos.
  */
 
-import { execFileSync, execSync } from 'node:child_process'
-import type { ExecSyncOptions } from 'node:child_process'
+import { spawnSync } from '@socketsecurity/lib-stable/process/spawn/child'
+import type { SpawnSyncOptions } from 'node:child_process'
 import { existsSync } from 'node:fs'
 import path from 'node:path'
 import process from 'node:process'
@@ -30,7 +30,7 @@ const mode: 'staged' | 'all' | 'modified' = args.includes('--all')
     : 'modified'
 const fix = args.includes('--fix')
 const quiet = args.includes('--quiet') || args.includes('--silent')
-const stdio: ExecSyncOptions['stdio'] = quiet ? 'pipe' : 'inherit'
+const stdio: SpawnSyncOptions['stdio'] = quiet ? 'pipe' : 'inherit'
 
 const LINTABLE_EXTS = new Set(['.cjs', '.cts', '.js', '.mjs', '.mts', '.ts'])
 
@@ -49,26 +49,29 @@ export function filterLintable(files: string[]): string[] {
 }
 
 export function getModifiedFiles(): string[] {
-  return gitFiles('git diff --name-only --diff-filter=ACMR HEAD')
+  return gitFiles(['diff', '--name-only', '--diff-filter=ACMR', 'HEAD'])
 }
 
 export function getStagedFiles(): string[] {
-  return gitFiles('git diff --cached --name-only --diff-filter=ACMR')
+  return gitFiles(['diff', '--cached', '--name-only', '--diff-filter=ACMR'])
 }
 
-export function gitFiles(command: string): string[] {
-  try {
-    const out = execSync(command, {
-      encoding: 'utf8',
-      stdio: ['ignore', 'pipe', 'pipe'],
-    })
-    return out
-      .split('\n')
-      .map(s => s.trim())
-      .filter(s => s.length > 0)
-  } catch {
+// spawnSync with array args — no shell interpolation. Matches the
+// socket/prefer-spawn-over-execsync rule: a shell-string execSync makes
+// every interpolated value an injection vector; the array form can't
+// shell-expand its args.
+export function gitFiles(gitArgs: string[]): string[] {
+  const r = spawnSync('git', gitArgs, {
+    stdio: ['ignore', 'pipe', 'pipe'],
+    stdioString: true,
+  })
+  if (r.status !== 0 || typeof r.stdout !== 'string') {
     return []
   }
+  return r.stdout
+    .split('\n')
+    .map(s => s.trim())
+    .filter(s => s.length > 0)
 }
 
 export function log(msg: string): void {
@@ -78,22 +81,24 @@ export function log(msg: string): void {
 }
 
 export function runAll(): number {
-  log('Formatting all files...')
-  try {
-    execSync(
-      `pnpm exec oxfmt -c .config/oxfmtrc.json ${fix ? '--write' : '--check'} .`,
-      { stdio },
-    )
-  } catch {
+  log('Formatting all files…')
+  const oxfmtArgs = [
+    'exec',
+    'oxfmt',
+    '-c',
+    '.config/oxfmtrc.json',
+    fix ? '--write' : '--check',
+    '.',
+  ]
+  if (spawnSync('pnpm', oxfmtArgs, { stdio }).status !== 0) {
     return 1
   }
-  log('Running oxlint on all files...')
-  try {
-    execSync(
-      `pnpm exec oxlint -c .config/oxlintrc.json${fix ? ' --fix' : ''}`,
-      { stdio },
-    )
-  } catch {
+  log('Running oxlint on all files…')
+  const oxlintArgs = ['exec', 'oxlint', '-c', '.config/oxlintrc.json']
+  if (fix) {
+    oxlintArgs.push('--fix')
+  }
+  if (spawnSync('pnpm', oxlintArgs, { stdio }).status !== 0) {
     return 1
   }
   return 0
@@ -104,7 +109,7 @@ export function runFiles(files: string[]): number {
     log('No lintable files; skipping.')
     return 0
   }
-  log(`Formatting ${files.length} file(s)...`)
+  log(`Formatting ${files.length} file(s)…`)
   const oxfmtArgs = [
     'exec',
     'oxfmt',
@@ -114,20 +119,16 @@ export function runFiles(files: string[]): number {
     '--no-error-on-unmatched-pattern',
     ...files,
   ]
-  try {
-    execFileSync('pnpm', oxfmtArgs, { stdio })
-  } catch {
+  if (spawnSync('pnpm', oxfmtArgs, { stdio }).status !== 0) {
     return 1
   }
-  log(`Running oxlint on ${files.length} file(s)...`)
+  log(`Running oxlint on ${files.length} file(s)…`)
   const oxlintArgs = ['exec', 'oxlint', '-c', '.config/oxlintrc.json']
   if (fix) {
     oxlintArgs.push('--fix')
   }
   oxlintArgs.push(...files)
-  try {
-    execFileSync('pnpm', oxlintArgs, { stdio })
-  } catch {
+  if (spawnSync('pnpm', oxlintArgs, { stdio }).status !== 0) {
     return 1
   }
   return 0

scripts/paths.mts

@@ -1,38 +1,31 @@
 /**
- * @fileoverview Centralized path resolution for vscode-socket-security.
- *
- * Source of truth for every build/test/runtime path. Per the fleet
- * `1 path, 1 reference` rule — every other module imports from here
- * instead of constructing paths inline.
- *
- * Layout follows the socket-btm canonical pattern:
- *   build/<mode>/<platform-arch>/out/<artifact>
- *
- * For this repo specifically, the bundled output is platform-agnostic
- * (esbuild emits a single CommonJS file that runs in whatever Node
- * VSCode provides — the only platform-fork inputs are the embedded
- * WASM binaries which esbuild includes via --loader:.wasm=binary).
- * We still expose getBuildPaths(mode, platformArch) for fleet
- * compatibility; consumers that don't care about platform can call
- * it with a fixed sentinel like 'any'.
- *
- * VSCode marketplace publishing expects `main: ./out/main.js` per
- * package.json. The canonical build output therefore lands at
- * `./out/main.js` directly (no platform/mode subtree) — same place
- * as before this refactor — but `BUILD_ROOT` and `getBuildPaths`
- * are still defined so future build steps (e.g. per-platform sfw
- * shims, signed VSIX outputs) can branch the layout without
- * inventing path conventions ad-hoc.
+ * @file Centralized path resolution for vscode-socket-security. Source of truth
+ *   for every build/test/runtime path. Per the fleet `1 path, 1 reference` rule
+ *   — every other module imports from here instead of constructing paths
+ *   inline. Layout follows the socket-btm canonical pattern:
+ *   build/<mode>/<platform-arch>/out/<artifact> For this repo specifically, the
+ *   bundled output is platform-agnostic (esbuild emits a single CommonJS file
+ *   that runs in whatever Node VSCode provides — the only platform-fork inputs
+ *   are the embedded WASM binaries which esbuild includes via
+ *   --loader:.wasm=binary). We still expose getBuildPaths(mode, platformArch)
+ *   for fleet compatibility; consumers that don't care about platform can call
+ *   it with a fixed sentinel like 'any'. VSCode marketplace publishing expects
+ *   `main: ./out/main.js` per package.json. The canonical build output
+ *   therefore lands at `./out/main.js` directly (no platform/mode subtree) —
+ *   same place as before this refactor — but `BUILD_ROOT` and `getBuildPaths`
+ *   are still defined so future build steps (e.g. per-platform sfw shims,
+ *   signed VSIX outputs) can branch the layout without inventing path
+ *   conventions ad-hoc.
  */
 
 import path from 'node:path'
 import { fileURLToPath } from 'node:url'
 
-const __filename = fileURLToPath(import.meta.url)
-const __dirname = path.dirname(__filename)
-
-// Package root: scripts/../
-export const PACKAGE_ROOT = path.resolve(__dirname, '..')
+// Package root: scripts/../ — derive from this module's own location.
+export const PACKAGE_ROOT = path.resolve(
+  path.dirname(fileURLToPath(import.meta.url)),
+  '..',
+)
 
 // Build roots.
 //
@@ -60,19 +53,18 @@ export const EXTENSION_ENTRY = path.join(SRC_DIR, 'extension.ts')
 /**
  * Build paths for a specific (mode, platform-arch) tuple.
  *
- * @param buildMode  'dev' | 'prod' (determines minify, debug toggles)
- * @param platformArch  e.g. 'darwin-arm64', 'linux-x64', 'win32-x64'.
- *                       Use 'any' when the artifact is platform-agnostic.
+ * @param buildMode 'dev' | 'prod' (determines minify, debug toggles)
+ * @param platformArch E.g. 'darwin-arm64', 'linux-x64', 'win32-x64'. Use 'any'
+ *   when the artifact is platform-agnostic.
  *
- * Returns an object whose keys mirror the socket-btm canonical:
- *   buildDir         build/<mode>/<platformArch>
- *   outputFinalDir   build/<mode>/<platformArch>/out/Final
- *   outputFinalFile  the bundled JS output
+ *   Returns an object whose keys mirror the socket-btm canonical: buildDir
+ *   build/<mode>/<platformArch> outputFinalDir
+ *   build/<mode>/<platformArch>/out/Final outputFinalFile the bundled JS
+ *   output.
  *
- * For vscode-socket-security the `out/Final/main.js` mirror is
- * documentation only — the real shipped path is OUT_DIR/main.js (so
- * vsce packaging finds it). Per-mode build trees are reserved for
- * future use.
+ *   For vscode-socket-security the `out/Final/main.js` mirror is documentation
+ *   only — the real shipped path is OUT_DIR/main.js (so vsce packaging finds
+ *   it). Per-mode build trees are reserved for future use.
  */
 export function getBuildPaths(
   buildMode: 'dev' | 'prod',