test(tar-xz): wrap defensive-unreachable branches with v8 ignore start/stop (#123)

Six call-sites are guarded by checks that TypeScript's strict mode
(noUncheckedIndexedAccess + typed errors) requires but cannot fire
at runtime under current invariants. Suppress them from coverage so
the metrics reflect only paths that real tests can exercise.

- file.ts: ELOOP on POSIX writeFile (O_NOFOLLOW vs ensureSafeTarget),
  ENOENT on the unlink-after-failed-open race, EEXIST on the wx-retry
  TOCTOU re-open, ENOENT on the unlink-before-link race for hardlinks,
  and the Win32 best-effort chmod/utimes catch arms. All five mirror
  the PR #114 Win32 TOCTOU hardening contract — the contract is
  locked by the adversarial review and SECURITY.md scenarios; race
  windows are too flaky for unit tests.
- tar-parser.ts: parseHeader === null after isEmptyBlock — the prior
  empty-block check guarantees the header parses successfully.
- xz-helpers.ts: '!unxzStream.destroyed' early-return guard inside
  the AsyncIterable's finally block — the fully-iterated path always
  destroys before finally runs, so the falsy arm is only hit on early
  generator.return() (not exercised by current tests; stream is
  destroyed idempotently anyway).
- checksum.ts: compound parseOctal condition split so only the
  noUncheckedIndexedAccess-required 'byte === undefined' arm is
  suppressed. The reachable 'byte === 0 || byte === 0x20' continues
  to count toward coverage.

Coverage delta on tar-xz: statements 82.05 -> 86.96; xz-helpers.ts
reaches 100. Real test cases for the still-uncovered EACCES,
filter, and malformed-archive paths will land in a follow-up PR.
707 tests pass byte-identical.

Author: oorabona

packages/tar-xz/src/node/file.ts

@@ -238,7 +238,9 @@ async function extractHardlinkEntry(
   try {
     await unlink(target);
   } catch (err) {
+    /* v8 ignore start: race-window — target disappears between existence check and unlink; benign ENOENT in concurrent extraction */
     if ((err as NodeJS.ErrnoException).code !== 'ENOENT') throw err;
+    /* v8 ignore stop */
   }
   await link(linkSource, target);
 }
@@ -265,9 +267,11 @@ async function writeFileEntryPosix(
       fileMode
     );
   } catch (err) {
+    /* v8 ignore start: race-window — O_NOFOLLOW fires only if ensureSafeTarget missed a symlink in the TOCTOU gap; unreachable under normal test conditions */
     if ((err as NodeJS.ErrnoException).code === 'ELOOP') {
       throw new Error(`Refusing '${entry.name}': target path is an existing symlink (O_NOFOLLOW)`);
     }
+    /* v8 ignore stop */
     throw err;
   }
   try {
@@ -319,11 +323,14 @@ async function openFileExclusive(
     try {
       await unlink(target);
     } catch (unlinkErr) {
+      /* v8 ignore start: race-window — target disappears between failed open() and unlink(); PR #114 Win32 TOCTOU hardening */
       if ((unlinkErr as NodeJS.ErrnoException).code !== 'ENOENT') throw unlinkErr;
+      /* v8 ignore stop */
     }
     try {
       return await open(target, 'wx', fileMode);
     } catch (retryErr) {
+      /* v8 ignore start: race-window — TOCTOU injection between unlink and retry-open; PR #114 Win32 TOCTOU hardening, locked by adversarial review */
       if ((retryErr as NodeJS.ErrnoException).code === 'EEXIST') {
         // A symlink (or junction) was injected between our unlink and our open.
         // Fail-closed: do NOT write through the symlink.
@@ -332,6 +339,7 @@ async function openFileExclusive(
             `possible symlink/junction injection or concurrent creation at the target path between unlink and open`
         );
       }
+      /* v8 ignore stop */
       throw retryErr;
     }
   }
@@ -366,18 +374,22 @@ async function writeFileEntryWin32(
     // On Windows these metadata updates are best-effort: some filesystems can
     // reject them (for example with EPERM) even when the file contents were
     // written successfully.
+    /* v8 ignore start: Windows best-effort — chmod/utimes can fail with EPERM on some filesystems; platform-specific defensive branch */
     try {
       await handle.chmod(fileMode);
     } catch {
       // Best-effort on Windows.
     }
+    /* v8 ignore stop */
     if (entry.mtime > 0) {
       const mt = new Date(entry.mtime * 1000);
+      /* v8 ignore start: Windows best-effort — utimes can fail with EPERM on some filesystems; platform-specific defensive branch */
       try {
         await handle.utimes(mt, mt);
       } catch {
         // Best-effort on Windows.
       }
+      /* v8 ignore stop */
     }
   } finally {
     await handle.close();

packages/tar-xz/src/node/tar-parser.ts

@@ -104,9 +104,11 @@ export function parseNextHeader(state: HeaderParserState): HeaderParseResult {
 
   // Parse header
   const raw = parseHeader(headerBlock);
+  /* v8 ignore start: defensive — isEmptyBlock() check above ensures parseHeader() never returns null here; contract invariant */
   if (!raw) {
     return { action: 'pax-consumed' };
   }
+  /* v8 ignore stop */
 
   // PAX extended header — read data blocks and store attributes
   if (raw.type === TarEntryType.PAX_HEADER) {

packages/tar-xz/src/node/xz-helpers.ts

@@ -61,9 +61,11 @@ export function streamXz(input: TarInputNode): AsyncIterable<Uint8Array> {
       // If the consumer stopped iterating early (generator.return() was called),
       // destroy the Transform stream so the pipeline does not keep running.
       // destroy() is idempotent — safe to call even if the stream already ended.
+      /* v8 ignore start: early-return path — destroy() guard only fires when consumer stops iterating before stream ends; not reached in full-iteration tests */
       if (!unxzStream.destroyed) {
         unxzStream.destroy();
       }
+      /* v8 ignore stop */
       // Swallow any subsequent pipeline rejection caused by the destroy() above.
       await pipelinePromise.catch(() => undefined);
     }

packages/tar-xz/src/tar/checksum.ts

@@ -85,8 +85,11 @@ export function parseOctal(header: Uint8Array, offset: number, length: number):
 
   for (let i = 0; i < length; i++) {
     const byte = header[offset + i];
-    // Stop at null, space, or out-of-bounds (undefined)
-    if (byte === undefined || byte === 0 || byte === 0x20) {
+    /* v8 ignore start: defensive vs noUncheckedIndexedAccess; offset+i is always within header bounds at runtime */
+    if (byte === undefined) break;
+    /* v8 ignore stop */
+    // Stop at null or space
+    if (byte === 0 || byte === 0x20) {
       break;
     }
     str += String.fromCharCode(byte);