fix(filesystem): prevent off-by-one line count in tailFile with trailing newlines

src/filesystem/__tests__/tail-head-real-fs.test.ts

@@ -0,0 +1,76 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import fs from 'fs/promises';
+import path from 'path';
+import os from 'os';
+import { tailFile, headFile } from '../lib.js';
+
+describe('tailFile and headFile (real filesystem)', () => {
+  let tmpDir: string;
+
+  beforeEach(async () => {
+    tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), 'tail-head-test-'));
+  });
+
+  afterEach(async () => {
+    await fs.rm(tmpDir, { recursive: true, force: true });
+  });
+
+  describe('tailFile - trailing newline handling', () => {
+    it('returns the exact requested number of lines when file has a trailing newline', async () => {
+      const filePath = path.join(tmpDir, 'trailing.txt');
+      await fs.writeFile(filePath, 'line1\nline2\nline3\n', 'utf-8');
+
+      const result = await tailFile(filePath, 2);
+      expect(result).toBe('line2\nline3');
+    });
+
+    it('returns the exact requested number of lines when file has NO trailing newline', async () => {
+      const filePath = path.join(tmpDir, 'no-trailing.txt');
+      await fs.writeFile(filePath, 'line1\nline2\nline3', 'utf-8');
+
+      const result = await tailFile(filePath, 2);
+      expect(result).toBe('line2\nline3');
+    });
+
+    it('returns all lines if requested count exceeds total lines (with trailing newline)', async () => {
+      const filePath = path.join(tmpDir, 'all-trailing.txt');
+      await fs.writeFile(filePath, 'line1\nline2\nline3\n', 'utf-8');
+
+      const result = await tailFile(filePath, 5);
+      expect(result).toBe('line1\nline2\nline3');
+    });
+
+    it('handles CRLF line endings with trailing newline', async () => {
+      const filePath = path.join(tmpDir, 'crlf.txt');
+      await fs.writeFile(filePath, 'line1\r\nline2\r\nline3\r\n', 'utf-8');
+
+      const result = await tailFile(filePath, 2);
+      expect(result).toBe('line2\nline3');
+    });
+
+    it('handles single line without trailing newline', async () => {
+      const filePath = path.join(tmpDir, 'single.txt');
+      await fs.writeFile(filePath, 'hello', 'utf-8');
+
+      const result = await tailFile(filePath, 1);
+      expect(result).toBe('hello');
+    });
+
+    it('handles single line with trailing newline', async () => {
+      const filePath = path.join(tmpDir, 'single-nl.txt');
+      await fs.writeFile(filePath, 'hello\n', 'utf-8');
+
+      const result = await tailFile(filePath, 1);
+      expect(result).toBe('hello');
+    });
+
+    it('handles large file across chunk boundaries with trailing newline', async () => {
+      const filePath = path.join(tmpDir, 'large.txt');
+      const lines = Array.from({ length: 200 }, (_, i) => `line_${String(i + 1).padStart(3, '0')}`);
+      await fs.writeFile(filePath, lines.join('\n') + '\n', 'utf-8');
+
+      const result = await tailFile(filePath, 3);
+      expect(result).toBe('line_198\nline_199\nline_200');
+    });
+  });
+});

src/filesystem/lib.ts

@@ -297,6 +297,7 @@ export async function tailFile(filePath: string, numLines: number): Promise<stri
     let chunk = Buffer.alloc(CHUNK_SIZE);
     let linesFound = 0;
     let remainingText = '';
+    let isLastChunk = true;
 
     // Read chunks from the end of the file until we have enough lines
     while (position > 0 && linesFound < numLines) {
@@ -308,12 +309,23 @@ export async function tailFile(filePath: string, numLines: number): Promise<stri
 
       // Get the chunk as a string and prepend any remaining text from previous iteration
       const readData = chunk.slice(0, bytesRead).toString('utf-8');
-      const chunkText = readData + remainingText;
+      let chunkText = readData + remainingText;
+
+      // If this is the very first chunk read (from the very end of the file)
+      // and it ends with a newline, strip that trailing newline so split doesn't produce
+      // an empty trailing line that skews the line count.
+      if (isLastChunk) {
+        chunkText = normalizeLineEndings(chunkText);
+        if (chunkText.endsWith('\n')) {
+          chunkText = chunkText.slice(0, -1);
+        }
+        isLastChunk = false;
+      }
 
       // Split by newlines and count
       const chunkLines = normalizeLineEndings(chunkText).split('\n');
 
-      // If this isn't the end of the file, the first line is likely incomplete
+      // If this isn't the beginning of the file, the first line is likely incomplete
       // Save it to prepend to the next chunk
       if (position > 0) {
         remainingText = chunkLines[0];
@@ -327,6 +339,11 @@ export async function tailFile(filePath: string, numLines: number): Promise<stri
       }
     }
 
+    // If we reached the start of the file and still have remainingText, add it
+    if (position === 0 && remainingText && linesFound < numLines) {
+      lines.unshift(remainingText);
+    }
+
     return lines.join('\n');
   } finally {
     await fileHandle.close();