test(tar-xz): close file.ts coverage partials with tests + v8 ignores (#128)

Address ten remaining partial branches in file.ts: two are real
reachable paths that get fixtures, eight are defensive guards that
get v8 ignore start/stop wraps with inline rationale.

Real tests added (2 in coverage-trivial-branches.spec.ts):
- extractSymlinkEntry early-return: a SYMLINK entry whose linkname
  is a single component is silently skipped when strip=1, exercising
  the if (!strippedLinkname) return; branch.
- extractHardlinkEntry early-return: same shape for hardlinks.

The coverage-trivial-branches helper buildSingleEntryTar gains an
optional linkname parameter so the tests can craft SYMLINK and
HARDLINK archives without depending on coverage-final.spec.ts.

v8 ignore wraps applied (7 sites in file.ts):
- ensureSafeName: TS-defensive 'undefined' early-return AND the
  NUL-byte rejection. Discovery during this work: parseString in
  tar/format.ts already terminates a name field at the first 0x00,
  so any name reaching ensureSafeName cannot contain a NUL. The
  guard is meaningful only for non-TAR callers and is unreachable
  via the public extract path; suppress accordingly.
- hasSymlinkAncestor non-ENOENT rethrow: race-window where the
  ancestor directory disappears between lstat calls; non-ENOENT
  branches are EACCES/EIO that test fixtures cannot trigger.
- hasSymlinkAncestor parent === dir guard: filesystem-root
  invariant; tar entries are relative paths under cwd so the loop
  never reaches POSIX '/' or Windows 'C:\'.
- ensureSafeTarget non-ENOENT rethrow: race-window in the
  stat-then-validate sequence.
- extractSymlinkEntry non-ENOENT rethrow on unlink: race-window
  where the existing symlink disappears between ensureSafeTarget
  and the unlink call.
- extractHardlinkEntry non-ENOENT rethrow on lstat: race-window
  on the link source.
- openFileExclusive non-EEXIST rethrow on the first open: same
  race-window class as the existing wraps in the same function;
  closes the symmetry hole.

Coverage:
- file.ts branches 83.72% -> 92.85% (+9.13).
- tar-xz overall branches 92.80% -> 94.98% (+2.18).
- tar-xz lines stay 100%.

tar-xz tests: 209 pass / 3 skipped -> 211 pass / 3 skipped (+2).

Author: oorabona

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

@@ -35,9 +35,13 @@ const SAFE_MODE_MASK = 0o0777;
  *  - Dot-segment-only names ('.', '..') that resolve to cwd or its parent
  */
 function ensureSafeName(s: string | undefined, label: string): void {
+  /* v8 ignore start: TS-defensive — callers only pass string (TarEntry.name/linkname are typed non-optional); undefined arm exists for future extensibility */
   if (s === undefined) return;
+  /* v8 ignore stop */
   if (s.length === 0) throw new Error(`Refusing entry: empty ${label}`);
+  /* v8 ignore start: unreachable via public API — TAR parser parseString() stops at the first NUL byte so no parsed entry name or linkname can ever contain U+0000 */
   if (s.includes('\x00')) throw new Error(`Refusing entry: ${label} contains NUL byte`);
+  /* v8 ignore stop */
   // R7-1: reject names that are dot-segment-only after normalising separators.
   // './' → '.', '../' → '..', '.\' → '.' etc.
   const normalized = s.replace(/\\/g, '/').replace(/\/+$/, '');
@@ -79,10 +83,14 @@ async function hasSymlinkAncestor(filePath: string, root: string): Promise<boole
       // ENOENT is fine — this intermediate dir doesn't exist yet, keep walking up.
       // A higher ancestor may still be a symlink.
       const code = (err as NodeJS.ErrnoException).code;
+      /* v8 ignore start: race-window — ancestor dir deleted between lstat and dirname call; non-ENOENT errors (EACCES/EIO) are system-level and cannot be triggered in tests */
       if (code !== 'ENOENT') throw err;
+      /* v8 ignore stop */
     }
     const parent = dirname(dir);
+    /* v8 ignore start: filesystem-root invariant — dirname('/') === '/' on POSIX and dirname('C:\\') === 'C:\\' on Win32; loop cannot reach root in practice because tar entries are relative paths under cwd */
     if (parent === dir) break; // filesystem root reached
+    /* v8 ignore stop */
     dir = parent;
   }
   return false;
@@ -131,7 +139,9 @@ async function ensureSafeTarget(
         throw new Error(`Refusing '${entryName}': target path is an existing symlink`);
       }
     } catch (err) {
+      /* v8 ignore start: race-window — target path disappears between the symlink check and lstat; non-ENOENT errors (EACCES/EIO) are system-level and cannot be triggered in tests */
       if ((err as NodeJS.ErrnoException).code !== 'ENOENT') throw err;
+      /* v8 ignore stop */
     }
   }
 }
@@ -175,7 +185,9 @@ async function extractSymlinkEntry(
   try {
     await unlink(target);
   } catch (err) {
+    /* v8 ignore start: race-window — existing symlink deleted between ensureSafeTarget check and unlink; non-ENOENT errors (EACCES/EIO) are system-level and cannot be triggered in tests */
     if ((err as NodeJS.ErrnoException).code !== 'ENOENT') throw err;
+    /* v8 ignore stop */
   }
   await symlink(strippedLinkname, target);
 }
@@ -220,7 +232,9 @@ async function extractHardlinkEntry(
   try {
     linkSrcStat = await lstat(linkSource);
   } catch (err) {
+    /* v8 ignore start: race-window — link source deleted between existence check and lstat; non-ENOENT errors (EACCES/EIO) are system-level and cannot be triggered in tests */
     if ((err as NodeJS.ErrnoException).code !== 'ENOENT') throw err;
+    /* v8 ignore stop */
   }
   if (linkSrcStat?.isSymbolicLink()) {
     throw new Error(
@@ -316,7 +330,9 @@ async function openFileExclusive(
   try {
     return await open(target, 'wx', fileMode);
   } catch (firstErr) {
+    /* v8 ignore start: race-window — non-EEXIST errors from first open() (e.g., EACCES, ENOSPC) are system-level and cannot be triggered in tests; PR #114 Win32 TOCTOU hardening */
     if ((firstErr as NodeJS.ErrnoException).code !== 'EEXIST') throw firstErr;
+    /* v8 ignore stop */
     // Target exists — legitimate overwrite: unlink then retry.
     // If the target disappears between the failed open() and unlink(), ignore
     // ENOENT and still retry the atomic exclusive create.

packages/tar-xz/test/coverage-trivial-branches.spec.ts

@@ -26,6 +26,7 @@ function buildSingleEntryTar(options: {
   type?: string;
   mtime?: number;
   mode?: number;
+  linkname?: string;
 }): Buffer {
   const type = options.type ?? TarEntryType.FILE;
   const isLink =
@@ -40,6 +41,7 @@ function buildSingleEntryTar(options: {
     type: type as '0',
     mtime: options.mtime,
     mode: options.mode,
+    linkname: options.linkname,
   });
 
   const blocks: Buffer[] = [Buffer.from(header)];
@@ -165,3 +167,102 @@ describe('extractFile() — mode=0 in TAR header (mode code path, POSIX only)',
     }
   );
 });
+
+// ---------------------------------------------------------------------------
+// Test B — file.ts:170  SYMLINK with linkname fully stripped → early return
+//
+// When strip=N removes all components from the SYMLINK linkname, the early-
+// return `if (!strippedLinkname) return;` fires and the entry is silently
+// skipped (no symlink created on disk, no error).
+// ---------------------------------------------------------------------------
+
+describe('extractFile() — SYMLINK entry skipped when strip removes entire linkname', () => {
+  let tempDir: string;
+
+  beforeEach(async () => {
+    tempDir = await fs.mkdtemp(path.join(os.tmpdir(), 'tar-xz-zeta-sym-'));
+  });
+
+  afterEach(async () => {
+    await fs.rm(tempDir, { recursive: true, force: true }).catch(() => {});
+  });
+
+  it('silently skips a SYMLINK entry when strip=1 removes its 1-component linkname', async () => {
+    // entry name: "prefix/link-target.txt" → strip=1 strips "prefix/" → yielded as "link-target.txt"
+    // linkname: "only-one-part" → extractSymlinkEntry strips 1 component →
+    //   parts = ['only-one-part'], parts.slice(1) = [] → strippedLinkname = '' → early return
+    const rawTar = buildSingleEntryTar({
+      name: 'prefix/link-target.txt',
+      content: Buffer.alloc(0),
+      type: TarEntryType.SYMLINK,
+      linkname: 'only-one-part',
+    });
+
+    const archivePath = path.join(tempDir, 'sym-strip.tar.xz');
+    await fs.writeFile(archivePath, xzSync(rawTar));
+
+    const dest = path.join(tempDir, 'out');
+    await fs.mkdir(dest);
+
+    // strip=1 strips "prefix/" from the entry name (yielded as "link-target.txt")
+    // and also strips "only-one-part" → strippedLinkname = '' → early return in extractSymlinkEntry
+    await extractFile(archivePath, { cwd: dest, strip: 1 });
+
+    // The symlink must NOT have been created (silently skipped)
+    const symlinkPath = path.join(dest, 'link-target.txt');
+    const exists = await fs
+      .lstat(symlinkPath)
+      .then(() => true)
+      .catch(() => false);
+    expect(exists).toBe(false);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Test C — file.ts:208  HARDLINK with linkname fully stripped → early return
+//
+// When strip=N removes all components from the HARDLINK linkname, the early-
+// return `if (!strippedLinkname) return;` fires and the entry is silently
+// skipped (no hardlink created on disk, no error).
+// ---------------------------------------------------------------------------
+
+describe('extractFile() — HARDLINK entry skipped when strip removes entire linkname', () => {
+  let tempDir: string;
+
+  beforeEach(async () => {
+    tempDir = await fs.mkdtemp(path.join(os.tmpdir(), 'tar-xz-zeta-hard-'));
+  });
+
+  afterEach(async () => {
+    await fs.rm(tempDir, { recursive: true, force: true }).catch(() => {});
+  });
+
+  it('silently skips a HARDLINK entry when strip=1 removes its 1-component linkname', async () => {
+    // HARDLINK linkname has exactly 1 component: "only-one-part"
+    // After strip=1 → parts.slice(1) = [] → strippedLinkname = '' → early return
+    const rawTar = buildSingleEntryTar({
+      name: 'prefix/hardlink-target.txt',
+      content: Buffer.alloc(0),
+      type: TarEntryType.HARDLINK,
+      linkname: 'only-one-part',
+    });
+
+    const archivePath = path.join(tempDir, 'hard-strip.tar.xz');
+    await fs.writeFile(archivePath, xzSync(rawTar));
+
+    const dest = path.join(tempDir, 'out');
+    await fs.mkdir(dest);
+
+    // strip=1 strips "prefix/" from the entry name and strips
+    // "only-one-part" → ['only-one-part'].slice(1) = [] → strippedLinkname = ''
+    await extractFile(archivePath, { cwd: dest, strip: 1 });
+
+    // The hardlink must NOT have been created (silently skipped)
+    const hardlinkPath = path.join(dest, 'hardlink-target.txt');
+    const exists = await fs
+      .lstat(hardlinkPath)
+      .then(() => true)
+      .catch(() => false);
+    expect(exists).toBe(false);
+  });
+});