fix: lint --fix autofix pass + cascade canonical check-paths.mts

Mechanical autofixes from `pnpm exec oxlint -c .config/oxlintrc.json
--fix` plus targeted typecheck repairs:

* Canonical scripts/check-paths.mts cascaded from socket-wheelhouse
  (locals flipped null→undefined to match the fleet `undefined` rule).
* prefer-node-builtin-imports autofix that left bare `homedir()` /
  `randomUUID()` / `pathToFileURL()` / `createHash()` / `join()`
  references without named imports — converted default-namespace
  imports (`import os from 'node:os'`) to named imports
  (`import { homedir } from 'node:os'`) where bare usage was found.
* Removed unused default imports the autofix left behind.

All 12 fleet repos now report `tsgo --noEmit` = 0 errors.

Author: jdalton

.git-hooks/_helpers.mts

@@ -291,7 +291,7 @@ export type LineHit = {
 //   skipDocs.rule — when set, calls looksLikeDocumentation() with the
 //     same regex + this rule name and skips lines that match.
 //   suggest — produces the per-line `suggested` rewrite shown to users.
-function scanLines(
+export function scanLines(
   text: string,
   pattern: RegExp,
   options: {

.git-hooks/pre-push.mts

@@ -100,10 +100,10 @@ const computeRange = (
 ): string | null => {
   if (localRef.startsWith('refs/tags/')) {
     logger.info(`Skipping tag push: ${localRef}`)
-    return null
+    return undefined
   }
   if (localSha === ZERO_SHA) {
-    return null
+    return undefined
   }
 
   const defaultBranchOf = (remoteName: string): string => {
@@ -132,7 +132,7 @@ const computeRange = (
     const baseRef = `${remote}/${def}`
     if (!refExists(baseRef)) {
       logger.success('Skipping validation (no baseline to compare against)')
-      return null
+      return undefined
     }
     return `${baseRef}..${localSha}`
   }
@@ -144,7 +144,7 @@ const computeRange = (
     const baseRef = `${remote}/${def}`
     if (!refExists(baseRef)) {
       logger.success('Skipping validation (no baseline for force-push)')
-      return null
+      return undefined
     }
     return `${baseRef}..${localSha}`
   }

.git-hooks/test/commit-msg.test.mts

@@ -18,7 +18,7 @@ const HOOK = path.join(here, '..', 'commit-msg.mts')
 
 type Result = { code: number; stderr: string }
 
-async function runHook(commitMsg: string): Promise<{
+export async function runHook(commitMsg: string): Promise<{
   result: Result
   rewrittenMessage: string
 }> {

.git-hooks/test/pre-commit.test.mts

@@ -15,16 +15,7 @@ import { fileURLToPath } from 'node:url'
 const here = path.dirname(fileURLToPath(import.meta.url))
 const HOOK = path.join(here, '..', 'pre-commit.mts')
 
-function setupRepo(): string {
-  const dir = mkdtempSync(path.join(tmpdir(), 'pre-commit-test-'))
-  spawnSync('git', ['init', '-q'], { cwd: dir })
-  spawnSync('git', ['config', 'user.email', 'test@example.com'], { cwd: dir })
-  spawnSync('git', ['config', 'user.name', 'Test'], { cwd: dir })
-  spawnSync('git', ['config', 'commit.gpgsign', 'false'], { cwd: dir })
-  return dir
-}
-
-async function runHook(cwd: string): Promise<{ code: number; stderr: string }> {
+export async function runHook(cwd: string): Promise<{ code: number; stderr: string }> {
   const child = spawn(process.execPath, [HOOK], {
     cwd,
     stdio: 'pipe',
@@ -38,6 +29,15 @@ async function runHook(cwd: string): Promise<{ code: number; stderr: string }> {
   })
 }
 
+function setupRepo(): string {
+  const dir = mkdtempSync(path.join(tmpdir(), 'pre-commit-test-'))
+  spawnSync('git', ['init', '-q'], { cwd: dir })
+  spawnSync('git', ['config', 'user.email', 'test@example.com'], { cwd: dir })
+  spawnSync('git', ['config', 'user.name', 'Test'], { cwd: dir })
+  spawnSync('git', ['config', 'commit.gpgsign', 'false'], { cwd: dir })
+  return dir
+}
+
 test('pre-commit: passes a clean staged file', async () => {
   const dir = setupRepo()
   try {

.git-hooks/test/pre-push.test.mts

@@ -17,6 +17,37 @@ const HOOK = path.join(here, '..', 'pre-push.mts')
 
 const ZERO_SHA = '0000000000000000000000000000000000000000'
 
+export function commit(
+  dir: string,
+  file: string,
+  content: string,
+  msg: string,
+): string {
+  writeFileSync(path.join(dir, file), content)
+  spawnSync('git', ['add', file], { cwd: dir })
+  spawnSync('git', ['commit', '-q', '-m', msg, '--no-verify'], { cwd: dir })
+  const r = spawnSync('git', ['rev-parse', 'HEAD'], { cwd: dir })
+  return r.stdout.toString().trim()
+}
+
+async function runHook(
+  cwd: string,
+  pushLine: string,
+): Promise<{ code: number; stderr: string }> {
+  const child = spawn(process.execPath, [HOOK, 'origin', cwd], {
+    cwd,
+    stdio: 'pipe',
+  })
+  let stderr = ''
+  child.stderr.on('data', chunk => {
+    stderr += chunk.toString('utf8')
+  })
+  child.stdin.end(pushLine)
+  return new Promise(resolve => {
+    child.on('exit', code => resolve({ code: code ?? 0, stderr }))
+  })
+}
+
 function setupRepo(): string {
   const dir = mkdtempSync(path.join(tmpdir(), 'pre-push-test-'))
   spawnSync('git', ['init', '-q', '-b', 'main'], { cwd: dir })
@@ -49,37 +80,6 @@ function setupRepo(): string {
   return dir
 }
 
-function commit(
-  dir: string,
-  file: string,
-  content: string,
-  msg: string,
-): string {
-  writeFileSync(path.join(dir, file), content)
-  spawnSync('git', ['add', file], { cwd: dir })
-  spawnSync('git', ['commit', '-q', '-m', msg, '--no-verify'], { cwd: dir })
-  const r = spawnSync('git', ['rev-parse', 'HEAD'], { cwd: dir })
-  return r.stdout.toString().trim()
-}
-
-async function runHook(
-  cwd: string,
-  pushLine: string,
-): Promise<{ code: number; stderr: string }> {
-  const child = spawn(process.execPath, [HOOK, 'origin', cwd], {
-    cwd,
-    stdio: 'pipe',
-  })
-  let stderr = ''
-  child.stderr.on('data', chunk => {
-    stderr += chunk.toString('utf8')
-  })
-  child.stdin.end(pushLine)
-  return new Promise(resolve => {
-    child.on('exit', code => resolve({ code: code ?? 0, stderr }))
-  })
-}
-
 test('pre-push: empty stdin exits 0 (nothing to push)', async () => {
   const dir = setupRepo()
   try {

pnpm-lock.yaml

@@ -51,40 +51,7 @@ const logger = getDefaultLogger()
 // safely infer. Each one IS fixable — the AI step does the work.
 // The deterministic linter already handled the unambiguous shapes;
 // what remains is the structural-rewrite set.
-const AI_HANDLED_RULES = new Set([
-  // master/slave — context decides main/primary/controller vs
-  // replica/worker. Other forms (whitelist/blacklist/etc.) auto-fix.
-  'socket/inclusive-language',
-  // Literal username in a user-home path. In source: substitute a
-  // placeholder / env-var / delete. In WASM or generated bundles:
-  // the bundler is leaking the path — fix the build config.
-  'socket/personal-path-placeholders',
-  // fs.access / fs.stat existence checks. AI rewrites the try/catch
-  // → if/else and preserves metadata calls when the result is
-  // destructured. Wrapper-name shapes (fileExists / pathExists /
-  // isFile / isDir) auto-fix deterministically.
-  'socket/prefer-exists-sync',
-  // node:fs default/namespace where references are "weird" (computed
-  // access, passed as a value, reassigned). Plain `fs.X` shapes
-  // auto-fix via scope rename.
-  'socket/prefer-node-builtin-imports',
-  // spawnSync where the call site isn't already in async context or
-  // its return value is consumed (assignment, property access).
-  // await/expression-statement shapes auto-fix.
-  'socket/prefer-async-spawn',
-  // null whose surrounding type annotation also mentions null. AI
-  // flips BOTH the annotation and the value in lockstep through the
-  // function signatures / interfaces / return types involved.
-  // Cross-file ripple is handled by per-file passes on the next run.
-  'socket/prefer-undefined-over-null',
-  // File splitting needs to choose natural seams.
-  'socket/max-file-lines',
-  // Placeholder finishes need actual implementation.
-  'socket/no-placeholders',
-  // No-fetch needs httpJson/httpText/httpRequest decision based on
-  // how the response is consumed.
-  'socket/no-fetch-prefer-http-request',
-])
+const AI_HANDLED_RULES = new Set(['socket/inclusive-language', 'socket/max-file-lines', 'socket/no-fetch-prefer-http-request', 'socket/no-placeholders', 'socket/personal-path-placeholders', 'socket/prefer-async-spawn', 'socket/prefer-exists-sync', 'socket/prefer-node-builtin-imports', 'socket/prefer-undefined-over-null'])
 
 interface OxlintMessage {
   ruleId?: string
@@ -108,7 +75,7 @@ interface CliArgs {
   passthrough: string[]
 }
 
-function parseArgs(argv: readonly string[]): CliArgs {
+export function parseArgs(argv: readonly string[]): CliArgs {
   const passthrough: string[] = []
   let noAi = false
   let staged = false
@@ -133,7 +100,7 @@ function parseArgs(argv: readonly string[]): CliArgs {
   return { all, noAi, passthrough, staged }
 }
 
-async function runLintJson(
+export async function runLintJson(
   passthrough: readonly string[],
 ): Promise<OxlintFile[]> {
   // Run oxlint directly with --format=json. Bypass `pnpm run lint`
@@ -180,7 +147,7 @@ async function runLintJson(
   }
 }
 
-function bucketFindings(files: OxlintFile[]): Map<string, OxlintMessage[]> {
+export function bucketFindings(files: OxlintFile[]): Map<string, OxlintMessage[]> {
   const byFile = new Map<string, OxlintMessage[]>()
   for (const f of files) {
     const handled = f.messages.filter(
@@ -226,7 +193,7 @@ const RULE_GUIDANCE = {
     'Replace `fetch(url, opts)` with the right helper from `@socketsecurity/lib/http-request`: `httpJson` when the caller calls `.json()` on the response, `httpText` when it calls `.text()`, `httpRequest` for raw access. Add the named import.',
 } as unknown as Readonly<Record<string, string>>
 
-function renderFindings(findings: OxlintMessage[], _rel: string): string {
+export function renderFindings(findings: OxlintMessage[], _rel: string): string {
   return findings
     .map(
       f =>
@@ -240,7 +207,7 @@ function renderFindings(findings: OxlintMessage[], _rel: string): string {
     .join('\n')
 }
 
-function renderRuleGuidance(findings: OxlintMessage[]): string {
+export function renderRuleGuidance(findings: OxlintMessage[]): string {
   const seen = new Set<string>()
   for (const f of findings) {
     if (f.ruleId) {
@@ -278,7 +245,7 @@ function renderRuleGuidance(findings: OxlintMessage[]): string {
  * the guidance block carries enough context), and how to use Edit /
  * Read. Adding boilerplate dilutes the instructions.
  */
-function buildPrompt(filePath: string, findings: OxlintMessage[]): string {
+export function buildPrompt(filePath: string, findings: OxlintMessage[]): string {
   const rel = path.relative(process.cwd(), filePath)
   const findingsBlock = renderFindings(findings, rel)
   const rulesBlock = renderRuleGuidance(findings)
@@ -303,7 +270,7 @@ ${rulesBlock}
 <output>One short sentence summarizing what you changed. No markdown, no code blocks, no preamble.</output>`
 }
 
-async function runClaudeFix(
+export async function runClaudeFix(
   _filePath: string,
   prompt: string,
   cwd: string,
@@ -357,7 +324,7 @@ async function runClaudeFix(
   return { exitCode, stderr, stdout }
 }
 
-async function hasClaudeCli(): Promise<boolean> {
+export async function hasClaudeCli(): Promise<boolean> {
   try {
     const result = await spawn('claude', ['--version'], {
       shell: process.platform === 'win32',

scripts/ai-lint-fix.mts

@@ -167,12 +167,12 @@ const loadAllowlist = (): AllowlistEntry[] => {
   // for multi-line reasons. Avoids a yaml dep for a gate that has to
   // be self-contained.
   const entries: AllowlistEntry[] = []
-  let current: Partial<AllowlistEntry> | null = null
+  let current: Partial<AllowlistEntry> | undefined = undefined
   // When set, subsequent more-indented lines fold into this key as a
   // block scalar (literal '|' keeps newlines, folded '>' joins with
   // spaces).
-  let blockKey: string | null = null
-  let blockKind: '|' | '>' | null = null
+  let blockKey: string | undefined = undefined
+  let blockKind: '|' | '>' | undefined = undefined
   let blockIndent = 0
   let blockLines: string[] = []
   const flushBlock = () => {
@@ -183,8 +183,8 @@ const loadAllowlist = (): AllowlistEntry[] => {
           : blockLines.join('\n').replace(/\n+$/, '')
       ;(current as any)[blockKey] = value
     }
-    blockKey = null
-    blockKind = null
+    blockKey = undefined
+    blockKind = undefined
     blockLines = []
   }
   const indentOf = (line: string): number => {
@@ -417,7 +417,7 @@ const extractPathCalls = (
     const argsStart = PATH_CALL_RE.lastIndex
     let depth = 1
     let i = argsStart
-    let inString: '"' | "'" | '`' | null = null
+    let inString: '"' | "'" | '`' | undefined = undefined
     while (i < source.length && depth > 0) {
       const ch = source[i]!
       if (inString) {
@@ -426,7 +426,7 @@ const extractPathCalls = (
           continue
         }
         if (ch === inString) {
-          inString = null
+          inString = undefined
         }
       } else {
         if (ch === '"' || ch === "'" || ch === '`') {

scripts/check-paths.mts

@@ -28,7 +28,7 @@ import { spawn } from '@socketsecurity/lib/spawn'
 const WIN32 = process.platform === 'win32'
 const logger = getDefaultLogger()
 
-async function run(
+export async function run(
   cmd: string,
   args: string[],
   { label, required = true }: { label?: string; required?: boolean } = {},