fix(archives): normalize ENOENT surface across zip/tar/tar.gz

Before: `extractZip` on a missing path surfaced adm-zip's generic
`"ADM-ZIP: Invalid filename"` (no path, no error code), while
`extractTar` and `extractTarGz` surfaced the raw Node-level
`ENOENT: no such file or directory, open '<path>'`. Callers
branching on `err.code === 'ENOENT'` (standard fs pattern) got
inconsistent behavior depending on archive format.

After: all three extractors call a new private `assertArchiveExists`
preflight that surfaces a Node-style Error with `code: 'ENOENT'`,
`path: archivePath`, and a message that includes the path. The
preflight runs BEFORE the underlying extractor ever sees the
archive, so the ENOENT path is identical across zip, tar, tar.gz,
and the `extractArchive` dispatcher.

Tests:
- Three `.rejects.toThrow()` assertions that only verified *some*
  rejection happened are now `.rejects.toMatchObject({ code:
  'ENOENT', message: stringContaining(path) })` — they now catch
  a semantic regression (e.g. silent success, wrong error) rather
  than passing on any thrown value.

Misc:
- `scripts/build-externals/config.mts` — comment referenced the
  removed `@socketsecurity/lib/validation/validate-schema` path;
  updated to `@socketsecurity/lib/schema/validate`.

All 38 archive tests + 6327 full-suite tests pass.

Author: jdalton

scripts/build-externals/config.mts

@@ -86,8 +86,8 @@ export const scopedPackages = [
   },
   // @sinclair/typebox powers validateSchema()'s TypeBox path. Bundle
   // so consumers don't need to install typebox separately — they just
-  // import from @socketsecurity/lib/validation/validate-schema and
-  // pass in TypeBox schemas built with our vendored copy of Type.*.
+  // import from @socketsecurity/lib/schema/validate and pass in
+  // TypeBox schemas built with our vendored copy of Type.*.
   //
   // Bundles both the core entry (for Type.* builders) and the /value
   // runtime (for Value.Check + Value.Errors used internally).

src/archives.ts

@@ -3,7 +3,7 @@
  * Supports zip, tar, tar.gz, and tgz formats.
  */
 
-import { createReadStream } from 'node:fs'
+import { createReadStream, existsSync } from 'node:fs'
 import process from 'node:process'
 import { pipeline } from 'node:stream/promises'
 import { createGunzip } from 'node:zlib'
@@ -109,6 +109,29 @@ function validatePathWithinBase(
   }
 }
 
+/**
+ * Assert that an archive file exists on disk before handing it to the
+ * underlying extractor. Normalizes the "missing archive" surface across
+ * all three extractors (zip/tar/tar.gz): each now throws a Node-style
+ * `ENOENT` error with the archive path. Without this preflight, `zip`
+ * goes through adm-zip and surfaces as `"Invalid filename"`, while
+ * `tar`/`tar.gz` surface the raw Node `ENOENT` — inconsistent, and
+ * adm-zip's message didn't include the path.
+ *
+ * @throws Error with `code: 'ENOENT'` if archivePath doesn't exist.
+ * @private
+ */
+function assertArchiveExists(archivePath: string): void {
+  if (!existsSync(archivePath)) {
+    const err = new Error(
+      `ENOENT: no such file or directory, open '${archivePath}'`,
+    ) as Error & { code: string; path: string }
+    err.code = 'ENOENT'
+    err.path = archivePath
+    throw err
+  }
+}
+
 /**
  * Detect archive format from file path.
  *
@@ -199,6 +222,11 @@ export async function extractTar(
   outputDir: string,
   options: ExtractOptions = {},
 ): Promise<void> {
+  // Normalize the "missing archive" surface (see extractZip) — throw
+  // ENOENT up front with a clear message rather than letting the
+  // Node-level createReadStream eventually surface as a stream error.
+  assertArchiveExists(archivePath)
+
   const {
     maxEntries = DEFAULT_MAX_ENTRIES,
     maxFileSize = DEFAULT_MAX_FILE_SIZE,
@@ -331,6 +359,9 @@ export async function extractTarGz(
   outputDir: string,
   options: ExtractOptions = {},
 ): Promise<void> {
+  // Normalize the "missing archive" surface (see extractZip).
+  assertArchiveExists(archivePath)
+
   const {
     maxEntries = DEFAULT_MAX_ENTRIES,
     maxFileSize = DEFAULT_MAX_FILE_SIZE,
@@ -463,6 +494,10 @@ export async function extractZip(
   outputDir: string,
   options: ExtractOptions = {},
 ): Promise<void> {
+  // Normalize the "missing archive" surface — throws ENOENT before
+  // AdmZip can surface its generic "Invalid filename" message.
+  assertArchiveExists(archivePath)
+
   const {
     maxEntries = DEFAULT_MAX_ENTRIES,
     maxFileSize = DEFAULT_MAX_FILE_SIZE,

test/unit/archives.test.mts

@@ -243,10 +243,21 @@ describe('archives', () => {
       }, 'extractZip-windows-path-')
     })
 
-    it('should throw on nonexistent zip file', async () => {
+    it('should throw ENOENT on nonexistent zip file', async () => {
       await runWithTempDir(async tempDir => {
         const nonexistentPath = path.join(tempDir, 'nonexistent.zip')
-        await expect(extractZip(nonexistentPath, tempDir)).rejects.toThrow()
+        // All three extractors normalize "missing archive" to ENOENT
+        // via the shared `assertArchiveExists` preflight — previously
+        // extractZip surfaced adm-zip's generic "Invalid filename"
+        // while tar/tar.gz surfaced the raw Node ENOENT. Assert on
+        // `.code === 'ENOENT'` so the test catches a semantic
+        // regression rather than merely any rejection.
+        await expect(
+          extractZip(nonexistentPath, tempDir),
+        ).rejects.toMatchObject({
+          code: 'ENOENT',
+          message: expect.stringContaining(nonexistentPath),
+        })
       }, 'extractZip-error-')
     })
   })
@@ -321,10 +332,15 @@ describe('archives', () => {
       }, 'extractTar-windows-path-')
     })
 
-    it('should throw on nonexistent tar file', async () => {
+    it('should throw ENOENT on nonexistent tar file', async () => {
       await runWithTempDir(async tempDir => {
         const nonexistentPath = path.join(tempDir, 'nonexistent.tar')
-        await expect(extractTar(nonexistentPath, tempDir)).rejects.toThrow()
+        await expect(
+          extractTar(nonexistentPath, tempDir),
+        ).rejects.toMatchObject({
+          code: 'ENOENT',
+          message: expect.stringContaining(nonexistentPath),
+        })
       }, 'extractTar-error-')
     })
   })
@@ -421,10 +437,15 @@ describe('archives', () => {
       }, 'extractTarGz-windows-path-')
     })
 
-    it('should throw on nonexistent tar.gz file', async () => {
+    it('should throw ENOENT on nonexistent tar.gz file', async () => {
       await runWithTempDir(async tempDir => {
         const nonexistentPath = path.join(tempDir, 'nonexistent.tar.gz')
-        await expect(extractTarGz(nonexistentPath, tempDir)).rejects.toThrow()
+        await expect(
+          extractTarGz(nonexistentPath, tempDir),
+        ).rejects.toMatchObject({
+          code: 'ENOENT',
+          message: expect.stringContaining(nonexistentPath),
+        })
       }, 'extractTarGz-error-')
     })
   })