Add validateFiles utility for defensive file access validation

Adds validateFiles() function that filters file paths based on readability,
preventing ENOENT errors common with Yarn Berry PnP virtual filesystem,
pnpm content-addressable store symlinks, and filesystem race conditions.

Returns ValidateFilesResult with validPaths and invalidPaths arrays.
Includes comprehensive test coverage for all validation scenarios.

Author: jdalton

src/fs.ts

@@ -674,6 +674,74 @@ export function isSymLinkSync(filepath: PathLike) {
   return false
 }
 
+/**
+ * Result of file readability validation.
+ * Contains lists of valid and invalid file paths.
+ */
+export interface ValidateFilesResult {
+  /**
+   * File paths that passed validation and are readable.
+   */
+  validPaths: string[]
+  /**
+   * File paths that failed validation (unreadable, permission denied, or non-existent).
+   * Common with Yarn Berry PnP virtual filesystem, pnpm symlinks, or filesystem race conditions.
+   */
+  invalidPaths: string[]
+}
+
+/**
+ * Validate that file paths are readable before processing.
+ * Filters out files from glob results that cannot be accessed (common with
+ * Yarn Berry PnP virtual filesystem, pnpm content-addressable store symlinks,
+ * or filesystem race conditions in CI/CD environments).
+ *
+ * This defensive pattern prevents ENOENT errors when files exist in glob
+ * results but are not accessible via standard filesystem operations.
+ *
+ * @param filepaths - Array of file paths to validate
+ * @returns Object with `validPaths` (readable) and `invalidPaths` (unreadable)
+ *
+ * @example
+ * ```ts
+ * import { validateFiles } from '@socketsecurity/lib/fs'
+ *
+ * const files = ['package.json', '.pnp.cjs/virtual-file.json']
+ * const { validPaths, invalidPaths } = validateFiles(files)
+ *
+ * console.log(`Valid: ${validPaths.length}`)
+ * console.log(`Invalid: ${invalidPaths.length}`)
+ * ```
+ *
+ * @example
+ * ```ts
+ * // Typical usage in Socket CLI commands
+ * const packagePaths = await getPackageFilesForScan(targets)
+ * const { validPaths } = validateFiles(packagePaths)
+ * await sdk.uploadManifestFiles(orgSlug, validPaths)
+ * ```
+ */
+/*@__NO_SIDE_EFFECTS__*/
+export function validateFiles(
+  filepaths: string[] | readonly string[],
+): ValidateFilesResult {
+  const fs = getFs()
+  const validPaths: string[] = []
+  const invalidPaths: string[] = []
+  const { R_OK } = fs.constants
+
+  for (const filepath of filepaths) {
+    try {
+      fs.accessSync(filepath, R_OK)
+      validPaths.push(filepath)
+    } catch {
+      invalidPaths.push(filepath)
+    }
+  }
+
+  return { __proto__: null, validPaths, invalidPaths } as ValidateFilesResult
+}
+
 /**
  * Read directory names asynchronously with filtering and sorting.
  * Returns only directory names (not files), with optional filtering for empty directories

test/fs.test.ts

@@ -26,6 +26,7 @@ import {
   safeStats,
   safeStatsSync,
   uniqueSync,
+  validateFiles,
   writeJson,
   writeJsonSync,
 } from '@socketsecurity/lib/fs'
@@ -1198,4 +1199,118 @@ describe('fs', () => {
       }, 'writeJsonSync-no-final-eol-')
     })
   })
+
+  describe('validateFiles', () => {
+    it('should return all files as valid when all exist and are readable', async () => {
+      await runWithTempDir(async tmpDir => {
+        const file1 = path.join(tmpDir, 'package.json')
+        const file2 = path.join(tmpDir, 'tsconfig.json')
+        await fs.writeFile(file1, '{}', 'utf8')
+        await fs.writeFile(file2, '{}', 'utf8')
+
+        const { validPaths, invalidPaths } = validateFiles([file1, file2])
+
+        expect(validPaths).toHaveLength(2)
+        expect(validPaths).toContain(file1)
+        expect(validPaths).toContain(file2)
+        expect(invalidPaths).toHaveLength(0)
+      }, 'validateFiles-all-valid-')
+    })
+
+    it('should return non-existent files as invalid', async () => {
+      await runWithTempDir(async tmpDir => {
+        const existingFile = path.join(tmpDir, 'exists.json')
+        const nonExistentFile = path.join(tmpDir, 'does-not-exist.json')
+        await fs.writeFile(existingFile, '{}', 'utf8')
+
+        const { validPaths, invalidPaths } = validateFiles([
+          existingFile,
+          nonExistentFile,
+        ])
+
+        expect(validPaths).toHaveLength(1)
+        expect(validPaths).toContain(existingFile)
+        expect(invalidPaths).toHaveLength(1)
+        expect(invalidPaths).toContain(nonExistentFile)
+      }, 'validateFiles-non-existent-')
+    })
+
+    it('should return all files as invalid when none exist', async () => {
+      await runWithTempDir(async tmpDir => {
+        const file1 = path.join(tmpDir, 'missing1.json')
+        const file2 = path.join(tmpDir, 'missing2.json')
+
+        const { validPaths, invalidPaths } = validateFiles([file1, file2])
+
+        expect(validPaths).toHaveLength(0)
+        expect(invalidPaths).toHaveLength(2)
+        expect(invalidPaths).toContain(file1)
+        expect(invalidPaths).toContain(file2)
+      }, 'validateFiles-all-invalid-')
+    })
+
+    it('should handle empty file array', () => {
+      const { validPaths, invalidPaths } = validateFiles([])
+
+      expect(validPaths).toHaveLength(0)
+      expect(invalidPaths).toHaveLength(0)
+    })
+
+    it('should work with readonly arrays', async () => {
+      await runWithTempDir(async tmpDir => {
+        const file1 = path.join(tmpDir, 'test.json')
+        await fs.writeFile(file1, '{}', 'utf8')
+
+        const readonlyArray: readonly string[] = [file1] as const
+        const { validPaths, invalidPaths } = validateFiles(readonlyArray)
+
+        expect(validPaths).toHaveLength(1)
+        expect(validPaths).toContain(file1)
+        expect(invalidPaths).toHaveLength(0)
+      }, 'validateFiles-readonly-')
+    })
+
+    it('should handle mixed valid and invalid files', async () => {
+      await runWithTempDir(async tmpDir => {
+        const valid1 = path.join(tmpDir, 'valid1.json')
+        const valid2 = path.join(tmpDir, 'valid2.json')
+        const invalid1 = path.join(tmpDir, 'invalid1.json')
+        const invalid2 = path.join(tmpDir, 'invalid2.json')
+
+        await fs.writeFile(valid1, '{}', 'utf8')
+        await fs.writeFile(valid2, '{}', 'utf8')
+
+        const { validPaths, invalidPaths } = validateFiles([
+          valid1,
+          invalid1,
+          valid2,
+          invalid2,
+        ])
+
+        expect(validPaths).toHaveLength(2)
+        expect(validPaths).toContain(valid1)
+        expect(validPaths).toContain(valid2)
+        expect(invalidPaths).toHaveLength(2)
+        expect(invalidPaths).toContain(invalid1)
+        expect(invalidPaths).toContain(invalid2)
+      }, 'validateFiles-mixed-')
+    })
+
+    it('should preserve file order in results', async () => {
+      await runWithTempDir(async tmpDir => {
+        const file1 = path.join(tmpDir, 'a.json')
+        const file2 = path.join(tmpDir, 'b.json')
+        const file3 = path.join(tmpDir, 'c.json')
+        await fs.writeFile(file1, '{}', 'utf8')
+        await fs.writeFile(file2, '{}', 'utf8')
+        await fs.writeFile(file3, '{}', 'utf8')
+
+        const { validPaths } = validateFiles([file3, file1, file2])
+
+        expect(validPaths[0]).toBe(file3)
+        expect(validPaths[1]).toBe(file1)
+        expect(validPaths[2]).toBe(file2)
+      }, 'validateFiles-order-')
+    })
+  })
 })