sandcrawler 0.1.0

data/lib/sandcrawler/fat/allocation_table.rb

@@ -0,0 +1,139 @@
+# frozen_string_literal: true
+
+require "set"
+
+module Sandcrawler
+  module FAT
+    class AllocationTable
+      Chain = Struct.new(:clusters, :status, :warnings, keyword_init: true)
+      attr_reader :warnings, :selection, :copies_consistent
+
+      def initialize(source, boot_sector, fat: nil)
+        @boot = boot_sector
+        @bits = @boot.fat_type.delete_prefix("FAT").to_i
+        @warnings = []
+        @erased_sectors = Set.new
+        fat ||= @boot.active_fat
+        raise UsageError, "FAT must be 1 or 2" if fat && ![1, 2].include?(fat)
+        raise UsageError, "FAT#{fat} does not exist" if fat && fat > @boot.fat_count
+
+        bytes = @boot.fat_sectors * @boot.bytes_per_sector
+        first = source.read_at(@boot.reserved_sectors * @boot.bytes_per_sector, bytes)
+        if @boot.fat_count == 2
+          second = source.read_at((@boot.reserved_sectors + @boot.fat_sectors) * @boot.bytes_per_sector,
+                                  bytes)
+        end
+        @copies_consistent = !second || first == second
+        @selection = "fat#{fat || 1}"
+        @data = first.dup
+        selected = Set.new
+        (0...bytes).step(@boot.bytes_per_sector) do |offset|
+          a = first.byteslice(offset, @boot.bytes_per_sector)
+          b = second&.byteslice(offset, @boot.bytes_per_sector)
+          if b && a != b
+            @warnings << { code: "FAT_MISMATCH",
+                           detail: "FAT copies differ at sector #{offset / @boot.bytes_per_sector}" }
+          end
+          choice = fat || (b && erased?(a) && !erased?(b) ? 2 : 1)
+          selected << choice
+          sector = choice == 2 ? b : a
+          if erased?(sector)
+            @erased_sectors << (offset / @boot.bytes_per_sector)
+            @warnings << { code: "FAT_ERASED",
+                           detail: "Selected FAT sector #{offset / @boot.bytes_per_sector} is erased" }
+          end
+          @data[offset, sector.bytesize] = sector
+        end
+        @selection = selected.size == 1 ? "fat#{selected.first}" : "mixed"
+      end
+
+      def [](cluster)
+        raise OutOfRangeError, "FAT index outside allocation table" unless cluster.between?(0, @boot.cluster_count + 1)
+
+        if @bits == 12
+          value = @data.byteslice(cluster + (cluster / 2), 2).unpack1("v")
+          cluster.even? ? value & 0xFFF : value >> 4
+        elsif @bits == 16
+          @data.byteslice(cluster * 2, 2).unpack1("v")
+        else
+          @data.byteslice(cluster * 4, 4).unpack1("V") & 0x0FFFFFFF
+        end
+      end
+
+      def eoc?(value)
+        value >= { 12 => 0xFF8, 16 => 0xFFF8, 32 => 0x0FFFFFF8 }.fetch(@bits)
+      end
+
+      def allocated?(cluster)
+        return false if erased_entry?(cluster)
+
+        value = self[cluster]
+        value.positive? && value != bad_marker && !reserved?(value)
+      end
+
+      def chain(first, limit: nil)
+        clusters = []
+        visited = Set.new
+        warnings = []
+        current = first
+        status = "ok"
+        loop do
+          if !current.between?(2, @boot.cluster_count + 1) || visited.include?(current)
+            status = "chain_error"
+            warnings << { code: "CHAIN_ERROR", detail: "Invalid or repeated cluster #{current}" }
+            break
+          end
+          visited << current
+          clusters << current
+          if erased_entry?(current)
+            status = "chain_error"
+            warnings << { code: "FAT_ERASED_ENTRY", detail: "Allocation metadata for cluster #{current} is erased" }
+            break
+          end
+          following = self[current]
+          break if eoc?(following)
+
+          if following.zero?
+            status = "truncated"
+            warnings << { code: "CHAIN_FREE", detail: "Cluster #{current} points to free space" }
+            break
+          end
+          if following == bad_marker || reserved?(following)
+            status = "chain_error"
+            warnings << { code: "CHAIN_ERROR", detail: "Bad or reserved link at cluster #{current}" }
+            break
+          end
+          if limit && clusters.length >= limit
+            status = "chain_error"
+            warnings << { code: "CHAIN_TOO_LONG",
+                          detail: "Chain continues beyond declared file size at cluster #{current}" }
+            break
+          end
+          current = following
+        end
+        Chain.new(clusters: clusters, status: status, warnings: warnings)
+      end
+
+      private
+
+      def erased_entry?(cluster)
+        offset = @bits == 12 ? cluster + (cluster / 2) : cluster * (@bits / 8)
+        length = @bits == 32 ? 4 : 2
+        @erased_sectors.include?(offset / @boot.bytes_per_sector) ||
+          @erased_sectors.include?((offset + length - 1) / @boot.bytes_per_sector)
+      end
+
+      def bad_marker
+        { 12 => 0xFF7, 16 => 0xFFF7, 32 => 0x0FFFFFF7 }.fetch(@bits)
+      end
+
+      def reserved?(value)
+        value == 1 || value.between?(bad_marker - 7, bad_marker - 1)
+      end
+
+      def erased?(sector)
+        sector.bytes.all? { |byte| byte == 255 }
+      end
+    end
+  end
+end

data/lib/sandcrawler/fat/boot_sector.rb

@@ -0,0 +1,142 @@
+# frozen_string_literal: true
+
+module Sandcrawler
+  module FAT
+    class BootSector
+      attr_reader :bytes_per_sector, :sectors_per_cluster, :reserved_sectors, :fat_count,
+                  :root_entry_count, :total_sectors, :fat_sectors, :media, :root_cluster,
+                  :root_dir_sectors, :first_data_sector, :cluster_count, :fat_type, :label, :active_fat, :backup_sector
+
+      def initialize(bytes, available_size: nil)
+        raise FormatError, "Boot sector is shorter than 512 bytes" if bytes.bytesize < 512
+        unless (bytes.getbyte(0) == 0xEB && bytes.getbyte(2) == 0x90) || bytes.getbyte(0) == 0xE9
+          raise FormatError, "Invalid FAT jump instruction"
+        end
+        raise FormatError, "Missing FAT signature" unless bytes.byteslice(510, 2) == "\x55\xAA".b
+
+        @bytes_per_sector = bytes.byteslice(11, 2).unpack1("v")
+        @sectors_per_cluster = bytes.getbyte(13)
+        @reserved_sectors = bytes.byteslice(14, 2).unpack1("v")
+        @fat_count = bytes.getbyte(16)
+        @root_entry_count = bytes.byteslice(17, 2).unpack1("v")
+        @total_sectors = bytes.byteslice(19, 2).unpack1("v")
+        @total_sectors = bytes.byteslice(32, 4).unpack1("V") if @total_sectors.zero?
+        @media = bytes.getbyte(21)
+        @fat_sectors = bytes.byteslice(22, 2).unpack1("v")
+        @fat_sectors = bytes.byteslice(36, 4).unpack1("V") if @fat_sectors.zero?
+        validate_geometry(available_size)
+        @root_dir_sectors = ((root_entry_count * 32) + bytes_per_sector - 1) / bytes_per_sector
+        @first_data_sector = reserved_sectors + (fat_count * fat_sectors) + root_dir_sectors
+        @cluster_count = (total_sectors - first_data_sector) / sectors_per_cluster
+        raise FormatError, "FAT volume has no data clusters" unless cluster_count.positive?
+
+        @fat_type = if cluster_count < 4085
+                      "FAT12"
+                    else
+                      cluster_count < 65_525 ? "FAT16" : "FAT32"
+                    end
+        @root_cluster = fat_type == "FAT32" ? bytes.byteslice(44, 4).unpack1("V") & 0x0FFFFFFF : nil
+        validate_fat(bytes)
+        if fat_type == "FAT32"
+          @backup_sector = bytes.byteslice(50, 2).unpack1("v")
+          flags = bytes.byteslice(40, 2).unpack1("v")
+          @active_fat = (flags & 15) + 1 unless (flags & 0x80).zero?
+          raise FormatError, "Active FAT index exceeds FAT count" if active_fat && active_fat > fat_count
+        end
+        @label = bytes.byteslice(fat_type == "FAT32" ? 71 : 43, 11).delete("\0").strip.encode("UTF-8", "IBM437")
+      end
+
+      def self.from_geometry(values, available_size:)
+        geometry = values.transform_keys(&:to_sym)
+        bps, spc, reserved, fats, fatsz, root = %i[bps spc rsvd fats fatsz root].map do |key|
+          Integer(geometry.fetch(key))
+        end
+        unless [512, 1024, 2048, 4096].include?(bps) && spc.between?(1, 128) &&
+               reserved.between?(1, 65_535) && [1, 2].include?(fats) &&
+               fatsz.between?(1, root.zero? ? 0xFFFFFFFF : 65_535) && root.between?(0, 65_535)
+          raise FormatError, "Manual geometry contains out-of-range fields"
+        end
+
+        total = Integer(geometry.fetch(:total) { geometry.fetch(:totsec, available_size / bps) })
+        raise FormatError, "Invalid total sector count" unless total.between?(1, 0xFFFFFFFF)
+
+        media = Integer(geometry.fetch(:media, 0xF8))
+        raise FormatError, "Invalid manual media byte" unless media.between?(0, 255)
+
+        root_cluster = Integer(geometry.fetch(:root_cluster, 2))
+        raise FormatError, "Invalid root cluster" if root.zero? && !root_cluster.between?(2, 0x0FFFFFFF)
+
+        bytes = "\0".b * 512
+        bytes[0, 3] = "\xEB\x3C\x90".b
+        bytes[11, 2] = [bps].pack("v")
+        bytes.setbyte(13, spc)
+        bytes[14, 2] = [reserved].pack("v")
+        bytes.setbyte(16, fats)
+        bytes[17, 2] = [root].pack("v")
+        bytes[32, 4] = [total].pack("V")
+        bytes.setbyte(21, media)
+        if root.zero?
+          bytes[36, 4] = [fatsz].pack("V")
+          bytes[44, 4] = [root_cluster].pack("V")
+        else
+          bytes[22, 2] = [fatsz].pack("v")
+        end
+        bytes[510, 2] = "\x55\xAA".b
+        new(bytes, available_size: available_size)
+      rescue KeyError, ArgumentError, TypeError, RangeError, ZeroDivisionError => e
+        raise FormatError, "Invalid manual geometry: #{e.message}"
+      end
+
+      def cluster_size
+        bytes_per_sector * sectors_per_cluster
+      end
+
+      def byte_size
+        total_sectors * bytes_per_sector
+      end
+
+      def cluster_offset(cluster)
+        raise OutOfRangeError, "Invalid cluster #{cluster}" unless cluster.between?(2, cluster_count + 1)
+
+        (first_data_sector + ((cluster - 2) * sectors_per_cluster)) * bytes_per_sector
+      end
+
+      def to_h
+        { fat_type: fat_type, bytes_per_sector: bytes_per_sector, sectors_per_cluster: sectors_per_cluster,
+          reserved_sectors: reserved_sectors, fat_count: fat_count, fat_sectors: fat_sectors,
+          root_entry_count: root_entry_count, root_cluster: root_cluster, total_sectors: total_sectors,
+          cluster_count: cluster_count, label: label }
+      end
+
+      private
+
+      def validate_geometry(available_size)
+        raise FormatError, "Invalid FAT sector size" unless [512, 1024, 2048, 4096].include?(bytes_per_sector)
+        unless sectors_per_cluster.between?(1, 128) && (sectors_per_cluster & (sectors_per_cluster - 1)).zero?
+          raise FormatError, "Invalid FAT cluster size"
+        end
+        unless reserved_sectors.positive? && [1, 2].include?(fat_count) &&
+               total_sectors.positive? && fat_sectors.positive?
+          raise FormatError, "Invalid FAT geometry"
+        end
+        raise FormatError, "Invalid FAT media byte" unless media == 0xF0 || media.between?(0xF8, 0xFF)
+        raise FormatError, "FAT volume exceeds source" if available_size && byte_size > available_size
+      end
+
+      def validate_fat(bytes)
+        bits = fat_type.delete_prefix("FAT").to_i
+        required_bytes = (((cluster_count + 2) * bits) + 7) / 8
+        raise FormatError, "Allocation table is too short" if required_bytes > fat_sectors * bytes_per_sector
+
+        if fat_type == "FAT32"
+          unless root_entry_count.zero? && root_cluster.between?(2, cluster_count + 1) &&
+                 bytes.byteslice(22, 2).unpack1("v").zero?
+            raise FormatError, "Invalid FAT32 root geometry"
+          end
+        elsif root_entry_count.zero?
+          raise FormatError, "Missing fixed root directory"
+        end
+      end
+    end
+  end
+end

data/lib/sandcrawler/fat/dir_entry.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+require "date"
+require "time"
+
+module Sandcrawler
+  module FAT
+    class DirEntry
+      attr_accessor :path
+      attr_reader :name, :size, :mtime, :attributes, :first_cluster
+
+      def initialize(bytes, fat_type: "FAT12", codepage: "IBM437", name: nil, parent: "")
+        raise FormatError, "Directory entry must contain 32 bytes" unless bytes.bytesize == 32
+
+        @deleted = bytes.getbyte(0) == 0xE5
+        @directory = (bytes.getbyte(11) & 0x10).positive?
+        @attributes = { 1 => "readonly", 2 => "hidden", 4 => "system", 8 => "volume_label", 16 => "directory",
+                        32 => "archive" }
+                      .filter_map do |bit, label|
+          label if (bytes.getbyte(11) & bit).positive?
+        end
+        @name = name || short_name(bytes, codepage)
+        @path = parent.empty? ? @name : "#{parent}/#{@name}"
+        @size = bytes.byteslice(28, 4).unpack1("V")
+        @first_cluster = bytes.byteslice(26, 2).unpack1("v")
+        @first_cluster |= (bytes.byteslice(20, 2).unpack1("v") & 0xFFF) << 16 if fat_type == "FAT32"
+        @mtime = decode_time(bytes.byteslice(24, 2).unpack1("v"), bytes.byteslice(22, 2).unpack1("v"))
+      end
+
+      def self.recovered(path:, size:, first_cluster: nil)
+        bytes = (" " * 11) + ("\0" * 21)
+        bytes.setbyte(11, 0x20)
+        bytes[28, 4] = [size].pack("V")
+        bytes[26, 2] = [(first_cluster || 0) & 0xFFFF].pack("v")
+        bytes[20, 2] = [(first_cluster || 0) >> 16].pack("v")
+        new(bytes, fat_type: "FAT32", name: path.split("/").last).tap { |entry| entry.path = path }
+      end
+
+      def directory?
+        @directory
+      end
+
+      def deleted?
+        @deleted
+      end
+
+      def to_h
+        { path: path, original_name: name, size: size, mtime: mtime&.iso8601,
+          attributes: attributes, first_cluster: first_cluster, deleted: deleted?, directory: directory? }
+      end
+
+      private
+
+      def short_name(bytes, codepage)
+        short = bytes.byteslice(0, 11).dup
+        short.setbyte(0, 0x5F) if deleted?
+        short.setbyte(0, 0xE5) if short.getbyte(0) == 0x05
+        base = short.byteslice(0, 8).rstrip.encode("UTF-8", codepage, invalid: :replace, undef: :replace)
+        extension = short.byteslice(8, 3).rstrip.encode("UTF-8", codepage, invalid: :replace, undef: :replace)
+        base = base.downcase if (bytes.getbyte(12) & 0x08).positive?
+        extension = extension.downcase if (bytes.getbyte(12) & 0x10).positive?
+        extension.empty? ? base : "#{base}.#{extension}"
+      end
+
+      def decode_time(date, time)
+        year = 1980 + (date >> 9)
+        month = (date >> 5) & 15
+        day = date & 31
+        hour = time >> 11
+        minute = (time >> 5) & 63
+        second = (time & 31) * 2
+        return unless Date.valid_date?(year, month, day) && hour < 24 && minute < 60 && second < 60
+
+        Time.local(year, month, day, hour, minute, second)
+      rescue ArgumentError, RangeError
+        nil
+      end
+    end
+  end
+end

data/lib/sandcrawler/fat/lfn_assembler.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module Sandcrawler
+  module FAT
+    class LfnAssembler
+      def initialize
+        @entries = []
+      end
+
+      def add(bytes)
+        @entries.clear if bytes.getbyte(0) != 0xE5 && (bytes.getbyte(0) & 0x40).positive?
+        @entries << bytes
+        @entries.clear if @entries.length > 20
+      end
+
+      def take(short)
+        entries = @entries
+        @entries = []
+        return if entries.empty?
+
+        deleted = short.getbyte(0) == 0xE5
+        return unless valid_entries?(entries, short, deleted)
+
+        units = entries.reverse.flat_map do |bytes|
+          (bytes.byteslice(1, 10) + bytes.byteslice(14, 12) + bytes.byteslice(28, 4)).unpack("v*")
+        end
+        units = units.take_while { |unit| unit != 0 && unit != 0xFFFF }
+        return if units.empty? || units.length > 255
+
+        units.pack("v*").force_encoding("UTF-16LE").encode("UTF-8")
+      rescue EncodingError
+        nil
+      end
+
+      def clear
+        @entries.clear
+      end
+
+      private
+
+      def valid_entries?(entries, short, deleted)
+        return false unless entries.all? { |entry| entry.getbyte(12).zero? && entry.byteslice(26, 2) == "\0\0" }
+
+        if deleted
+          entries.all? { |entry| entry.getbyte(0) == 0xE5 } && entries.map { |entry| entry.getbyte(13) }.uniq.size == 1
+        else
+          count = entries.first.getbyte(0) & 31
+          return false unless entries.first.getbyte(0) == (count | 0x40) && count == entries.length
+
+          checksum = short.byteslice(0, 11).bytes.reduce(0) { |sum, byte| (((sum & 1) << 7) + (sum >> 1) + byte) & 255 }
+          entries.each_with_index.all? do |entry, index|
+            expected = count - index
+            expected |= 0x40 if index.zero?
+            entry.getbyte(0) == expected && entry.getbyte(13) == checksum
+          end
+        end
+      end
+    end
+  end
+end

data/lib/sandcrawler/fat/volume.rb

@@ -0,0 +1,198 @@
+# frozen_string_literal: true
+
+require "set"
+require_relative "../image/slice"
+require_relative "boot_sector"
+require_relative "allocation_table"
+require_relative "dir_entry"
+require_relative "lfn_assembler"
+
+module Sandcrawler
+  module FAT
+    class Volume
+      ReadResult = Struct.new(:data, :status, :warnings, keyword_init: true)
+      attr_reader :boot_sector, :allocation_table, :warnings, :referenced_clusters, :source, :offset
+
+      def initialize(source, offset: 0, boot_sector: nil, fat: nil, codepage: "IBM437")
+        unless offset.is_a?(Integer) && offset >= 0 && offset < source.size
+          raise OutOfRangeError,
+                "Volume offset outside source"
+        end
+
+        Encoding.find(codepage)
+        @offset = offset
+        @boot_sector = boot_sector || BootSector.new(source.read_at(offset, 512), available_size: source.size - offset)
+        @source = Image::Slice.new(source, offset, @boot_sector.byte_size)
+        @allocation_table = AllocationTable.new(@source, @boot_sector, fat: fat)
+        @warnings = @allocation_table.warnings.dup
+        @referenced_clusters = Set.new
+        @cluster_owners = {}
+        @crosslinked_clusters = Set.new
+        @ambiguous_paths = Set.new
+        @indexed = false
+        @codepage = codepage
+      end
+
+      def metadata
+        boot_sector.to_h.merge(offset: offset, fat_selection: allocation_table.selection,
+                               fat_copies_consistent: allocation_table.copies_consistent)
+      end
+
+      def each_entry(recursive: true, deleted: false)
+        return enum_for(__method__, recursive: recursive, deleted: deleted) unless block_given?
+
+        pending = [["", boot_sector.root_cluster]]
+        seen_directories = Set.new
+        seen_paths = Set.new
+        until pending.empty?
+          path, cluster = pending.shift
+          if cluster && seen_directories.include?(cluster)
+            warn_once("DIRECTORY_LOOP", "Directory cluster #{cluster} is already visited")
+            next
+          end
+          seen_directories << cluster if cluster
+          directory_data(cluster, path).then do |data|
+            parse_entries(data, path, deleted: deleted).each do |entry|
+              unless entry.deleted?
+                if seen_paths.include?(entry.path)
+                  @ambiguous_paths << entry.path
+                  warn_once("DUPLICATE_ENTRY", "Multiple live directory entries use #{entry.path}")
+                end
+                seen_paths << entry.path
+                track_entry(entry)
+                pending << [entry.path, entry.first_cluster] if entry.directory? && recursive
+              end
+              yield entry
+            end
+          end
+        end
+        @indexed = true if recursive && !deleted
+      end
+
+      def read(entry)
+        each_entry.to_a unless @indexed
+        warnings = []
+        if @ambiguous_paths.include?(entry.path)
+          warnings << { code: "DUPLICATE_ENTRY", detail: "Multiple live directory entries use #{entry.path}" }
+        end
+        if entry.size.zero?
+          return ReadResult.new(data: "".b, status: warnings.empty? ? "ok" : "chain_error", warnings: warnings)
+        end
+
+        limit = (entry.size + boot_sector.cluster_size - 1) / boot_sector.cluster_size
+        chain = allocation_table.chain(entry.first_cluster, limit: limit)
+        data = "".b
+        warnings += chain.warnings
+        erased = false
+        chain.clusters.each do |cluster|
+          bytes = read_cluster(cluster)
+          erased ||= bytes.bytes.all? { |byte| byte == 255 }
+          data << bytes
+        end
+        status = @ambiguous_paths.include?(entry.path) ? "chain_error" : chain.status
+        if chain.clusters.any? { |cluster| @crosslinked_clusters.include?(cluster) }
+          status = "chain_error"
+          warnings << { code: "CROSS_LINK", detail: "#{entry.path} shares clusters with another directory entry" }
+        end
+        status = "truncated" if status == "ok" && data.bytesize < entry.size
+        if erased
+          warnings << { code: "ERASED_CLUSTER", detail: "#{entry.path} contains an erased cluster" }
+          status = "suspect_erased" if status == "ok"
+        end
+        ReadResult.new(data: data.byteslice(0, [entry.size, data.bytesize].min), status: status, warnings: warnings)
+      rescue Error, IOError, SystemCallError => e
+        ReadResult.new(data: data || "".b, status: "chain_error",
+                       warnings: (warnings || []) + [{ code: "READ_ERROR", detail: e.message }])
+      end
+
+      def read_cluster(cluster)
+        source.read_at(boot_sector.cluster_offset(cluster), boot_sector.cluster_size)
+      end
+
+      private
+
+      def directory_data(cluster, path)
+        unless cluster
+          position = (boot_sector.reserved_sectors + (boot_sector.fat_count * boot_sector.fat_sectors)) *
+                     boot_sector.bytes_per_sector
+          return source.read_at(position, boot_sector.root_entry_count * 32)
+        end
+
+        chain = allocation_table.chain(cluster)
+        track_clusters(chain.clusters, path)
+        chain.warnings.each { |warning| warn_once(warning[:code], warning[:detail]) }
+        data = "".b
+        chain.clusters.each { |number| data << read_cluster(number) }
+        data
+      rescue Error, IOError, SystemCallError => e
+        warn_once("DIRECTORY_ERROR", e.message)
+        data || "".b
+      end
+
+      def parse_entries(data, parent, deleted:)
+        entries = []
+        lfn = LfnAssembler.new
+        past_end = false
+        (0...data.bytesize).step(32) do |position|
+          bytes = data.byteslice(position, 32)
+          break if bytes.bytesize < 32
+
+          if bytes.getbyte(0).zero?
+            past_end = true
+            lfn.clear
+            break unless deleted
+
+            next
+          end
+          if past_end && bytes.getbyte(0) != 0xE5
+            lfn.clear
+            next
+          end
+          if bytes.bytes.all? { |byte| byte == 255 } || (bytes.getbyte(11) & 0xC0).positive?
+            warn_once("DIRECTORY_DAMAGED", "Invalid directory entry in #{parent.empty? ? '/' : parent}")
+            lfn.clear
+            next
+          end
+          if bytes.getbyte(11) == 0x0F
+            lfn.add(bytes)
+            next
+          end
+          name = lfn.take(bytes)
+          next if (bytes.getbyte(11) & 0x08).positive? || (bytes.getbyte(0) == 0xE5 && !deleted)
+          next if [".          ", "..         "].include?(bytes.byteslice(0, 11))
+
+          entry = DirEntry.new(bytes, fat_type: boot_sector.fat_type, codepage: @codepage, name: name, parent: parent)
+          next if [".", "..", ""].include?(entry.name)
+
+          entries << entry
+        end
+        entries
+      end
+
+      def track_entry(entry)
+        return if entry.first_cluster < 2
+        return if entry.size.zero? && !entry.directory?
+
+        limit = entry.directory? ? nil : (entry.size + boot_sector.cluster_size - 1) / boot_sector.cluster_size
+        track_clusters(allocation_table.chain(entry.first_cluster, limit: limit).clusters, entry.path)
+      end
+
+      def track_clusters(clusters, owner)
+        @referenced_clusters.merge(clusters)
+        clusters.each do |cluster|
+          if @cluster_owners.key?(cluster) && @cluster_owners[cluster] != owner
+            @crosslinked_clusters << cluster
+            warn_once("CROSS_LINK", "Cluster #{cluster} is shared by #{@cluster_owners[cluster]} and #{owner}")
+          else
+            @cluster_owners[cluster] = owner
+          end
+        end
+      end
+
+      def warn_once(code, detail)
+        warning = { code: code, detail: detail }
+        warnings << warning unless warnings.include?(warning)
+      end
+    end
+  end
+end