Document ZipReader DirectoryEntry behavior and add verification test

FORMATS.md

@@ -22,11 +22,16 @@
 | 7Zip (4)               | LZMA, LZMA2, BZip2, PPMd, BCJ, BCJ2, Deflate      | Decompress          | SevenZipArchive | N/A        | N/A           |
 
 1. SOLID Rars are only supported in the RarReader API.
-2. Zip format supports pkware and WinzipAES encryption. However, encrypted LZMA is not supported. Zip64 reading/writing is supported but only with seekable streams as the Zip spec doesn't support Zip64 data in post data descriptors. Deflate64 is only supported for reading.
+2. Zip format supports pkware and WinzipAES encryption. However, encrypted LZMA is not supported. Zip64 reading/writing is supported but only with seekable streams as the Zip spec doesn't support Zip64 data in post data descriptors. Deflate64 is only supported for reading. See [Zip Format Notes](#zip-format-notes) for details on multi-volume archives and streaming behavior.
 3. The Tar format requires a file size in the header. If no size is specified to the TarWriter and the stream is not seekable, then an exception will be thrown.
 4. The 7Zip format doesn't allow for reading as a forward-only stream so 7Zip is only supported through the Archive API
 5. LZip has no support for extra data like the file name or timestamp. There is a default filename used when looking at the entry Key on the archive.
 
+### Zip Format Notes
+
+- Multi-volume/split ZIP archives require ZipArchive (seekable streams) as ZipReader cannot seek across volume files.
+- ZipReader processes entries from LocalEntry headers (which include directory entries ending with `/`) and intentionally skips DirectoryEntry headers from the central directory, as they are redundant in streaming mode - all entry data comes from LocalEntry headers which ZipReader has already processed.
+
 ## Compression Streams
 
 For those who want to directly compress/decompress bits. The single file formats are represented here as well. However, BZip2, LZip and XZ have no metadata (GZip has a little) so using them without something like a Tar file makes little sense.

src/SharpCompress/Readers/Zip/ZipReader.cs

@@ -75,6 +75,14 @@ protected override IEnumerable<ZipEntry> GetEntries(Stream stream)
                             );
                         }
                         break;
+                    case ZipHeaderType.DirectoryEntry:
+                        // DirectoryEntry headers in the central directory are intentionally skipped.
+                        // In streaming mode, we can only read forward, and DirectoryEntry headers
+                        // reference LocalEntry headers that have already been processed. The file
+                        // data comes from LocalEntry headers, not DirectoryEntry headers.
+                        // For multi-volume ZIPs where file data spans multiple files, use ZipArchive
+                        // instead, which requires seekable streams.
+                        break;
                     case ZipHeaderType.DirectoryEnd:
                     {
                         yield break;

tests/SharpCompress.Test/Zip/ZipReaderTests.cs

@@ -1,5 +1,7 @@
 using System;
+using System.Collections.Generic;
 using System.IO;
+using System.Linq;
 using SharpCompress.Archives;
 using SharpCompress.Common;
 using SharpCompress.IO;
@@ -397,4 +399,41 @@ public void Zip_Uncompressed_Encrypted_Read()
         Assert.Equal("second.txt", reader.Entry.Key);
         Assert.Equal(197, reader.Entry.Size);
     }
+
+    [Fact]
+    public void ZipReader_Returns_Same_Entries_As_ZipArchive()
+    {
+        // Verifies that ZipReader and ZipArchive return the same entries
+        // for standard single-volume ZIP files. ZipReader processes LocalEntry
+        // headers sequentially, while ZipArchive uses DirectoryEntry headers
+        // from the central directory and seeks to LocalEntry headers for data.
+        var testFiles = new[] { "Zip.none.zip", "Zip.deflate.zip", "Zip.none.issue86.zip" };
+
+        foreach (var testFile in testFiles)
+        {
+            var path = Path.Combine(TEST_ARCHIVES_PATH, testFile);
+
+            var readerKeys = new List<string>();
+            using (var stream = File.OpenRead(path))
+            using (var reader = ZipReader.Open(stream))
+            {
+                while (reader.MoveToNextEntry())
+                {
+                    readerKeys.Add(reader.Entry.Key!);
+                }
+            }
+
+            var archiveKeys = new List<string>();
+            using (var archive = Archives.Zip.ZipArchive.Open(path))
+            {
+                foreach (var entry in archive.Entries)
+                {
+                    archiveKeys.Add(entry.Key!);
+                }
+            }
+
+            Assert.Equal(archiveKeys.Count, readerKeys.Count);
+            Assert.Equal(archiveKeys.OrderBy(k => k), readerKeys.OrderBy(k => k));
+        }
+    }
 }