ukdah 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: f5f25b1e78bf1060ab0607178933eb83caad1db9aad4090ec052ddacddc43d97
+  data.tar.gz: ddbd1df65e46f8c066cf438c5ddd8bef6c9b2484358efd4eb3bfc4bbfebb58bd
+SHA512:
+  metadata.gz: '09787badaeca8cb3a6c5c925615139de645166b6a7588f3ac564691824e5ae6018a2e8df3e1d2f7b170321e25a7f8e47284a607dd443c5b10aae26148e7ee2de'
+  data.tar.gz: b1e878a5b9a370843603cabb61dda27288fa25e7516e20276f90401148bbd153a452a9cc817cef5a005f64d95ce6ddc3e34ea4336397d2115afa14b2a9b8d9d7

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+# Changelog
+
+## 0.1.0 — 2026-09-21
+
+- Initial release.

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 ydah
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,60 @@
+# Ukdah
+
+Ukdah (ι Cancri, from Arabic *ʿuqdah*, “knot”) is a dependency-free Ruby
+parser for RFC 5322 messages and MIME bodies. It is deliberately a parser,
+not a mail transport client: it never connects to IMAP, POP, or SMTP.
+
+## Features
+
+- Folded headers, RFC 2047 encoded words, comments, quoted names, and groups
+- RFC 2231 parameters, multipart trees, base64 and quoted-printable bodies
+- Attachment and inline-part discovery, including `cid:` identifiers
+- Tolerant parsing with diagnostics for malformed messages and boundaries
+- mbox splitting with envelope and `Content-Length` support
+- Lightweight `Message-ID`/`References` threading and quote segmentation
+- Charset decoding through an injectable decoder; no runtime dependencies
+
+## Installation
+
+```ruby
+gem "ukdah"
+```
+
+## Quick start
+
+```ruby
+require "ukdah"
+
+message = Ukdah::Message.parse(File.binread("message.eml"))
+puts message.subject
+puts message.from.first.email
+puts message.decoded(message.text_part)
+message.attachments.each do |part|
+  File.binwrite(part.filename, part.body)
+end
+```
+
+Applications with a charset detector can inject it without adding a runtime
+dependency:
+
+```ruby
+message.decoded(message.text_part, decoder: ->(bytes, charset) {
+  Menkar.decode(bytes, Menkar.detect(bytes, hint: charset))
+})
+```
+
+Malformed input is returned as far as it can be read. Inspect
+`message.diagnostics` when a source needs attention. Ukdah does not sanitize
+HTML; pass HTML parts through a sanitizer before displaying them.
+
+## Development
+
+```sh
+bundle install
+bundle exec rake
+gem build --strict ukdah.gemspec
+```
+
+## License
+
+MIT. See [LICENSE.txt](LICENSE.txt).

data/Rakefile

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task test: :spec
+task default: :test

data/docs/adr/000-template.md

@@ -0,0 +1,18 @@
+# ADR NNN: Implementation decision title
+
+- Status: Proposed
+- Date: YYYY-MM-DD
+
+## Context
+
+Describe the concrete implementation question and the compatibility,
+data, runtime, or component constraints.
+
+## Decision
+
+Describe the durable boundary or architecture choice.
+
+## Consequences
+
+Describe the important positive and negative trade-offs, including what would
+make this decision worth revisiting.

data/docs/adr/001-parsing-only.md

@@ -0,0 +1,20 @@
+# ADR 001: Parsing only, no transport
+
+- Status: Accepted
+- Date: 2026-09-21
+
+## Context
+
+Ukdah is the mail source's parsing boundary. Adding IMAP, POP, or SMTP would
+turn a deterministic library into a network client with credentials, retry,
+and security policy concerns.
+
+## Decision
+
+Ukdah parses RFC 5322, MIME, and mbox bytes only. Network transport and message
+construction remain outside the gem.
+
+## Consequences
+
+The runtime stays small, dependency-free, and safe to use on untrusted files.
+Applications must provide transport and persistence separately.

data/docs/adr/002-decoder-injection.md

@@ -0,0 +1,20 @@
+# ADR 002: Charset decoding is injectable
+
+- Status: Accepted
+- Date: 2026-09-21
+
+## Context
+
+Mail charset declarations are frequently wrong. A parser should retain the
+decoded transfer bytes without depending on a particular charset detector.
+
+## Decision
+
+`Message#decoded` accepts an optional callable receiving bytes and the declared
+charset. The standard-library fallback handles common Ruby encodings, while an
+application may inject a stronger detector such as menkar.
+
+## Consequences
+
+Ukdah has no runtime dependency on the reader application or a charset gem.
+Callers that need detection beyond Ruby's encodings must inject that policy.

data/docs/adr/README.md

@@ -0,0 +1,8 @@
+# Architecture decision records
+
+These records document durable implementation boundaries. Commands and test
+fixtures belong in the README and test suite.
+
+- [ADR template](000-template.md)
+- [ADR 001: Parsing only](001-parsing-only.md)
+- [ADR 002: Charset decoding is injectable](002-decoder-injection.md)

data/lib/ukdah/address.rb

@@ -0,0 +1,125 @@
+# frozen_string_literal: true
+
+module Ukdah
+  Address = Struct.new(:name, :email, :group, keyword_init: true) do
+    class << self
+      def parse_list(value)
+        return [] if value.nil? || value.to_s.strip.empty?
+
+        result = []
+        split_top_level(value.to_s, ",").each do |token|
+          if token =~ /\A\s*(.*?)\s*:\s*(.*?)\s*;\s*\z/m
+            group = clean_name(Regexp.last_match(1))
+            split_top_level(Regexp.last_match(2), ",").each do |member|
+              address = parse_one(member, group)
+              result << address if address
+            end
+          else
+            address = parse_one(token, nil)
+            result << address if address
+          end
+        end
+        result
+      end
+
+      private
+
+      def parse_one(token, group)
+        value = remove_comments(token.to_s).strip
+        return nil if value.empty?
+
+        if value =~ /\A(.*?)\s*<\s*([^<>]+?)\s*>\s*\z/m
+          name = clean_name(Regexp.last_match(1))
+          email = Regexp.last_match(2).strip
+        else
+          name = nil
+          email = value.gsub(/[<>]/, "").strip
+        end
+        return nil if email.empty?
+
+        Address.new(name: name, email: email, group: group)
+      end
+
+      def clean_name(value)
+        name = value.to_s.strip
+        if name.start_with?('"') && name.end_with?('"') && name.length >= 2
+          name = name[1...-1].gsub(/\\(.)/, '\\1')
+        end
+        Header.decode(name).strip
+      end
+
+      def remove_comments(value)
+        result = +""
+        depth = 0
+        quoted = false
+        escaped = false
+        value.each_char do |char|
+          if escaped
+            result << char if depth.zero?
+            escaped = false
+          elsif char == "\\" && quoted
+            result << char if depth.zero?
+            escaped = true
+          elsif char == '"' && depth.zero?
+            quoted = !quoted
+            result << char
+          elsif char == "(" && !quoted
+            depth += 1
+          elsif char == ")" && depth.positive?
+            depth -= 1
+          elsif depth.zero?
+            result << char
+          end
+        end
+        result
+      end
+
+      def split_top_level(value, separator)
+        pieces = []
+        current = +""
+        quote = false
+        angle = false
+        comment = 0
+        group = false
+        escaped = false
+        value.each_char do |char|
+          if escaped
+            current << char
+            escaped = false
+          elsif char == "\\" && (quote || comment.positive?)
+            current << char
+            escaped = true
+          elsif char == '"' && comment.zero?
+            quote = !quote
+            current << char
+          elsif char == "<" && !quote && comment.zero?
+            angle = true
+            current << char
+          elsif char == ">" && !quote && comment.zero?
+            angle = false
+            current << char
+          elsif char == "(" && !quote
+            comment += 1
+            current << char
+          elsif char == ")" && comment.positive? && !quote
+            comment -= 1
+            current << char
+          elsif char == ":" && separator == "," && !quote && !angle && comment.zero?
+            group = true
+            current << char
+          elsif char == ";" && separator == "," && !quote && !angle && comment.zero?
+            group = false
+            current << char
+          elsif char == separator && !quote && !angle && comment.zero? && !group
+            pieces << current.strip
+            current = +""
+          else
+            current << char
+          end
+        end
+        pieces << current.strip unless current.strip.empty?
+        pieces
+      end
+    end
+  end
+end

data/lib/ukdah/header.rb

@@ -0,0 +1,192 @@
+# frozen_string_literal: true
+
+module Ukdah
+  module Header
+    ENCODED_WORD = /=\?([^?\s]+)\?([bBqQ])\?([^?]*)\?=/
+    BASE64_ALPHABET = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/"
+
+    module_function
+
+    def parse(section, diagnostics = nil)
+      result = Hash.new { |hash, key| hash[key] = [] }
+      current = nil
+      section.to_s.split(/\r?\n/, -1).each do |line|
+        if line.match?(/\A[ \t]/)
+          if current
+            current[:value] << " " << line.strip
+          elsif diagnostics
+            diagnostics << "header continuation without a header"
+          end
+        elsif (match = line.match(/\A([^:]+):(.*)\z/))
+          current = { name: match[1].strip.downcase, value: match[2].strip }
+          result[current[:name]] << current[:value]
+        elsif !line.empty? && diagnostics
+          diagnostics << "malformed header ignored: #{line.byteslice(0, 80)}"
+        end
+      end
+      result
+    end
+
+    def decode(value)
+      original = value.to_s
+      return original unless original.include?("=?")
+
+      text = value.to_s.dup.force_encoding(Encoding::BINARY)
+      loop do
+        changed = text.gsub(/(=\?[^?\s]+\?[bBqQ]\?[^?]*\?=)[ \t\r\n]+(?==\?)/, "\\1")
+        break if changed == text
+
+        text = changed
+      end
+      text.gsub(ENCODED_WORD) do
+        decode_word(Regexp.last_match(1), Regexp.last_match(2), Regexp.last_match(3))
+      end
+    rescue StandardError
+      value.to_s
+    end
+
+    def decode_word(charset, mode, payload)
+      bytes = if mode.casecmp("b").zero?
+                decode_base64(payload)
+              else
+                payload.tr("_", " ").gsub(/=([0-9A-Fa-f]{2})/) { Regexp.last_match(1).to_i(16).chr }
+              end
+      Ukdah.decode_bytes(bytes, charset)
+    rescue StandardError
+      payload
+    end
+
+    def decode_base64(payload)
+      buffer = 0
+      bits = 0
+      output = []
+      payload.to_s.each_byte do |byte|
+        char = byte.chr
+        next if char == "=" || char.match?(/[ \t\r\n]/)
+
+        value = BASE64_ALPHABET.index(char)
+        next if value.nil?
+
+        buffer = (buffer << 6) | value
+        bits += 6
+        while bits >= 8
+          bits -= 8
+          output << ((buffer >> bits) & 0xff)
+        end
+      end
+      output.pack("C*")
+    end
+
+    def split_parameters(value)
+      pieces = []
+      current = +""
+      quoted = false
+      escaped = false
+      value.to_s.each_char do |char|
+        if escaped
+          current << char
+          escaped = false
+        elsif char == "\\" && quoted
+          current << char
+          escaped = true
+        elsif char == '"'
+          quoted = !quoted
+          current << char
+        elsif char == ";" && !quoted
+          pieces << current.strip
+          current = +""
+        else
+          current << char
+        end
+      end
+      pieces << current.strip unless current.empty?
+      pieces
+    end
+
+    def unquote(value)
+      text = value.to_s.strip
+      text = text[1...-1] if text.start_with?('"') && text.end_with?('"') && text.length >= 2
+      text.gsub(/\\(.)/, '\\1')
+    end
+
+    def content_type(value, diagnostics = nil)
+      parse_parameterized(value, diagnostics)
+    end
+
+    def disposition(value, diagnostics = nil)
+      parse_parameterized(value, diagnostics)
+    end
+
+    def parse_parameterized(value, diagnostics = nil)
+      pieces = split_parameters(value)
+      main = pieces.shift.to_s.strip.downcase
+      raw = {}
+      pieces.each do |piece|
+        name, parameter = piece.split("=", 2)
+        if parameter.nil?
+          diagnostics << "malformed parameter ignored: #{piece}" if diagnostics
+          next
+        end
+        raw[name.to_s.strip.downcase] = unquote(parameter)
+      end
+      [main, decode_parameters(raw, diagnostics)]
+    end
+
+    def decode_parameters(raw, diagnostics = nil)
+      parameters = {}
+      grouped = Hash.new { |hash, key| hash[key] = [] }
+      raw.each do |name, value|
+        if (match = name.match(/\A(.+)\*(\d+)(\*)?\z/))
+          grouped[match[1]] << [match[2].to_i, !match[3].nil?, value]
+        elsif name.end_with?("*")
+          parameters[name[0...-1]] = decode_extended(value, diagnostics)
+        else
+          parameters[name] = value
+        end
+      end
+      grouped.each do |name, segments|
+        segments.sort_by!(&:first)
+        expected = 0
+        charset = nil
+        encoded = +""
+        segments.each do |index, is_encoded, value|
+          if index != expected
+            diagnostics << "missing RFC 2231 parameter segment: #{name}*#{expected}" if diagnostics
+            expected = index
+          end
+          expected += 1
+          segment = value
+          if index.zero? && is_encoded && segment =~ /\A([^']*)'[^']*'(.*)\z/m
+            charset = Regexp.last_match(1)
+            segment = Regexp.last_match(2)
+          end
+          encoded << (is_encoded ? percent_decode(segment) : segment)
+        end
+        parameters[name] = Ukdah.decode_bytes(encoded, charset)
+      end
+      parameters
+    end
+
+    def decode_extended(value, diagnostics = nil)
+      text = value.to_s
+      if text =~ /\A([^']*)'[^']*'(.*)\z/m
+        Ukdah.decode_bytes(percent_decode(Regexp.last_match(2)), Regexp.last_match(1))
+      else
+        diagnostics << "malformed RFC 2231 parameter" if diagnostics
+        percent_decode(text)
+      end
+    end
+
+    def percent_decode(value)
+      value.to_s.gsub(/%([0-9A-Fa-f]{2})/) { Regexp.last_match(1).to_i(16).chr }
+    end
+
+    def message_ids(value)
+      value.to_s.scan(/<([^>]+)>/).flatten.tap do |ids|
+        if ids.empty?
+          ids.concat(value.to_s.split(/[ \t,]+/).map { |id| id.gsub(/[<>]/, "") }.reject(&:empty?))
+        end
+      end
+    end
+  end
+end

data/lib/ukdah/mbox.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+module Ukdah
+  module Mbox
+    module_function
+
+    def each(io)
+      return enum_for(:each, io) unless block_given?
+
+      data = io.respond_to?(:read) ? io.read.to_s : io.to_s
+      starts = envelope_offsets(data)
+      if starts.empty?
+        yield Message.parse(data) unless data.empty?
+        return
+      end
+
+      index = 0
+      while index < starts.length
+        start = starts[index]
+        message_start = line_end(data, start)
+        next_start = starts[index + 1] || data.bytesize
+        explicit_end = content_length_end(data, message_start, next_start)
+        finish = explicit_end || next_start
+        finish = next_start if finish > data.bytesize
+        yield Message.parse(data.byteslice(message_start, finish - message_start).to_s)
+        if explicit_end
+          index += 1
+          index += 1 while index < starts.length && starts[index] < finish
+        else
+          index += 1
+        end
+      end
+    end
+
+    def envelope_offsets(data)
+      result = []
+      offset = 0
+      data.to_s.each_line do |line|
+        if line.match?(/\AFrom \S+ (?:Mon|Tue|Wed|Thu|Fri|Sat|Sun)\s/)
+          result << offset
+        end
+        offset += line.bytesize
+      end
+      result
+    end
+
+    def line_end(data, offset)
+      newline = data.index("\n", offset)
+      newline ? newline + 1 : data.bytesize
+    end
+
+    def content_length_end(data, start, limit)
+      lf_end = data.index("\n\n", start)
+      crlf_end = data.index("\r\n\r\n", start)
+      header_end = if lf_end.nil?
+                     crlf_end
+                   elsif crlf_end.nil?
+                     lf_end
+                   else
+                     [lf_end, crlf_end].min
+                   end
+      return nil unless header_end && header_end < limit
+
+      header = data.byteslice(start, header_end - start)
+      match = header.match(/(?:\A|\r?\n)Content-Length\s*:\s*(\d+)/i)
+      return nil unless match
+
+      separator_length = data.byteslice(header_end, 4) == "\r\n\r\n" ? 4 : 2
+      header_end + separator_length + match[1].to_i
+    end
+  end
+end

data/lib/ukdah/message.rb

@@ -0,0 +1,234 @@
+# frozen_string_literal: true
+
+require "time"
+
+module Ukdah
+  class Message
+    attr_reader :headers, :parts, :raw, :diagnostics
+
+    def initialize(headers:, parts:, raw:, diagnostics: [])
+      @headers = headers
+      @parts = parts
+      @raw = raw
+      @diagnostics = diagnostics
+    end
+
+    def self.parse(bytes)
+      Parser.new(bytes).parse
+    end
+
+    def header(name)
+      headers_all(name).first
+    end
+
+    def headers_all(name)
+      Array(@headers[name.to_s.downcase]).map { |value| Header.decode(value) }
+    end
+
+    def from
+      addresses("from")
+    end
+
+    def to
+      addresses("to")
+    end
+
+    def cc
+      addresses("cc")
+    end
+
+    def bcc
+      addresses("bcc")
+    end
+
+    def reply_to
+      addresses("reply-to")
+    end
+
+    def subject
+      header("subject")
+    end
+
+    def date
+      value = header("date")
+      return nil if value.nil? || value.empty?
+
+      Time.rfc2822(value)
+    rescue ArgumentError
+      begin
+        Time.parse(value)
+      rescue ArgumentError
+        nil
+      end
+    end
+
+    def message_id
+      Header.message_ids(header("message-id")).first
+    end
+
+    def in_reply_to
+      Header.message_ids(header("in-reply-to"))
+    end
+
+    def references
+      Header.message_ids(header("references"))
+    end
+
+    def text_part
+      find_part { |part| part.content_type == "text/plain" }
+    end
+
+    def html_part
+      find_part { |part| part.content_type == "text/html" }
+    end
+
+    def attachments
+      leaves.select do |part|
+        part.disposition == "attachment" || !part.filename.to_s.empty?
+      end
+    end
+
+    def inline_parts
+      leaves.each_with_object({}) do |part, result|
+        next if part.content_id.to_s.empty?
+        next unless part.disposition == "inline" || part.disposition.to_s.empty?
+
+        id = normalize_content_id(part.content_id)
+        result[id] = part
+        result["<#{id}>"] = part
+      end
+    end
+
+    def decoded(part, decoder: nil)
+      return "" unless part
+
+      bytes = part.body.to_s.dup.force_encoding(Encoding::BINARY)
+      charset = part.parameters["charset"]
+      if decoder
+        result = decoder.arity == 1 ? decoder.call(bytes) : decoder.call(bytes, charset)
+        return result.to_s
+      end
+      Ukdah.decode_bytes(bytes, charset)
+    end
+
+    def leaves
+      parts.flat_map { |part| part.each_leaf.to_a }
+    end
+
+    private
+
+    def addresses(name)
+      headers_all(name).flat_map { |value| Address.parse_list(value) }
+    end
+
+    def find_part
+      leaves.find { |part| yield part }
+    end
+
+    def normalize_content_id(value)
+      value.to_s.strip.gsub(/\A<|>\z/, "").downcase
+    end
+
+    class Parser
+      def initialize(bytes)
+        @raw = bytes.to_s.dup.force_encoding(Encoding::BINARY)
+        @diagnostics = []
+      end
+
+      def parse
+        headers, body = entity(@raw)
+        root = part_from(headers, body)
+        parts = root.multipart? ? root.parts : [root]
+        Message.new(headers: headers, parts: parts, raw: @raw, diagnostics: @diagnostics)
+      rescue StandardError => error
+        @diagnostics << "parser recovered from #{error.class}: #{error.message}"
+        Message.new(headers: {}, parts: [], raw: @raw, diagnostics: @diagnostics)
+      end
+
+      private
+
+      def entity(bytes)
+        match = bytes.match(/\r?\n\r?\n/)
+        return [Header.parse(bytes, @diagnostics), ""] unless match
+
+        [Header.parse(bytes.byteslice(0, match.begin(0)), @diagnostics), bytes.byteslice(match.end(0)..-1).to_s]
+      end
+
+      def part_from(headers, body)
+        type, parameters = Header.content_type(first(headers, "content-type"), @diagnostics)
+        type = "text/plain" if type.nil? || type.empty?
+        disposition, disposition_parameters = Header.disposition(first(headers, "content-disposition"), @diagnostics)
+        disposition = nil if disposition.nil? || disposition.empty?
+        filename = disposition_parameters["filename"] || parameters["name"]
+        content_id = Header.decode(first(headers, "content-id").to_s).strip
+        encoding = first(headers, "content-transfer-encoding").to_s.downcase
+
+        if type.start_with?("multipart/")
+          children = multipart_children(body, parameters["boundary"])
+          return Part.new(content_type: type, parameters: parameters, disposition: disposition,
+                          filename: filename, content_id: content_id, encoding: encoding,
+                          body: children.empty? ? transfer_decode(body, encoding) : nil, parts: children)
+        end
+
+        Part.new(content_type: type, parameters: parameters, disposition: disposition,
+                 filename: filename, content_id: content_id, encoding: encoding,
+                 body: transfer_decode(body, encoding), parts: [])
+      end
+
+      def multipart_children(body, boundary)
+        unless boundary && !boundary.empty?
+          @diagnostics << "multipart has no boundary"
+          return []
+        end
+
+        marker = "--#{boundary}"
+        children = []
+        current = nil
+        closed = false
+        body.to_s.split(/\r?\n/, -1).each do |line|
+          if line =~ /\A#{Regexp.escape(marker)}(--)?[ \t]*\z/
+            if current
+              child = current.join("\n")
+              children << part_from(*entity(child)) unless child.strip.empty?
+            end
+            if Regexp.last_match(1)
+              current = nil
+              closed = true
+            else
+              current = []
+            end
+          elsif current
+            current << line
+          end
+        end
+        if current && !current.empty?
+          child = current.join("\n")
+          children << part_from(*entity(child)) unless child.strip.empty?
+          @diagnostics << "multipart boundary terminator missing"
+        elsif !closed
+          @diagnostics << "multipart boundary not found"
+        end
+        children
+      end
+
+      def transfer_decode(body, encoding)
+        value = body.to_s.dup.force_encoding(Encoding::BINARY)
+        case encoding.to_s.downcase
+        when "base64"
+          Header.decode_base64(value)
+        when "quoted-printable"
+          value.gsub(/=\r?\n/, "").gsub(/=([0-9A-Fa-f]{2})/) { Regexp.last_match(1).to_i(16).chr }
+        else
+          value
+        end
+      rescue StandardError => error
+        @diagnostics << "transfer decoding failed for #{encoding}: #{error.message}"
+        value
+      end
+
+      def first(headers, name)
+        Array(headers[name]).first.to_s
+      end
+    end
+  end
+end

data/lib/ukdah/part.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Ukdah
+  Part = Struct.new(:content_type, :parameters, :disposition, :filename,
+                    :content_id, :encoding, :body, :parts, keyword_init: true) do
+    def multipart?
+      content_type.to_s.start_with?("multipart/")
+    end
+
+    def leaf?
+      !multipart? && Array(parts).empty?
+    end
+
+    def each_leaf(&block)
+      return enum_for(:each_leaf) unless block
+
+      if Array(parts).empty?
+        yield self
+      else
+        parts.each { |part| part.each_leaf(&block) }
+      end
+    end
+
+    def media_type
+      content_type.to_s.split("/", 2).first.to_s
+    end
+
+    def subtype
+      content_type.to_s.split("/", 2).last.to_s
+    end
+  end
+end

data/lib/ukdah/quote.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Ukdah
+  module Quote
+    module_function
+
+    def segments(text)
+      groups = []
+      text.to_s.split(/\r?\n/, -1).each do |line|
+        depth = line[/\A(?:>\s*)+/].to_s.count(">")
+        if groups.last && groups.last[0] == depth
+          groups.last[1] << line
+        else
+          groups << [depth, [line]]
+        end
+      end
+      groups
+    end
+  end
+end

data/lib/ukdah/thread.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+module Ukdah
+  module Thread_
+    class Node
+      attr_accessor :parent
+      attr_reader :message, :children
+
+      def initialize(message = nil)
+        @message = message
+        @children = []
+        @parent = nil
+      end
+
+      def id
+        message && message.message_id
+      end
+
+      def placeholder?
+        message.nil?
+      end
+    end
+
+    module_function
+
+    def build(messages)
+      nodes = {}
+      ordered = []
+      Array(messages).each do |message|
+        id = normalize(message.message_id)
+        next if id.nil? || id.empty? || (nodes[id] && !nodes[id].placeholder?)
+
+        node = nodes[id] || Node.new
+        node.instance_variable_set(:@message, message)
+        nodes[id] = node
+        ordered << node unless ordered.include?(node)
+      end
+
+      Array(messages).each do |message|
+        child = nodes[normalize(message.message_id)]
+        next unless child
+
+        parent = nil
+        (Array(message.references) + Array(message.in_reply_to)).each do |reference|
+          reference_id = normalize(reference)
+          next if reference_id.nil? || reference_id.empty?
+
+          candidate = nodes[reference_id] ||= Node.new
+          ordered << candidate unless ordered.include?(candidate)
+          parent = candidate
+        end
+        next unless parent && parent != child
+
+        detach(child)
+        child.parent = parent
+        parent.children << child unless parent.children.include?(child)
+      end
+
+      ordered.select { |node| node.parent.nil? }
+    end
+
+    def normalize(id)
+      id.to_s.strip.gsub(/\A<|>\z/, "").downcase unless id.nil?
+    end
+
+    def detach(node)
+      return unless node.parent
+
+      node.parent.children.delete(node)
+      node.parent = nil
+    end
+  end
+end

data/lib/ukdah/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Ukdah
+  VERSION = "0.1.0"
+end

data/lib/ukdah.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+require_relative "ukdah/version"
+require_relative "ukdah/header"
+require_relative "ukdah/address"
+require_relative "ukdah/part"
+require_relative "ukdah/message"
+require_relative "ukdah/mbox"
+require_relative "ukdah/quote"
+require_relative "ukdah/thread"
+
+module Ukdah
+  class Error < StandardError; end
+
+  class << self
+    def decode_bytes(bytes, charset = nil)
+      value = bytes.to_s.dup.force_encoding(Encoding::BINARY)
+      return value.encode("UTF-8", invalid: :replace, undef: :replace) if charset.nil? || charset.empty?
+
+      encoding = Encoding.find(charset.to_s.strip.gsub(/\A["']|["']\z/, ""))
+      value.force_encoding(encoding).encode("UTF-8", invalid: :replace, undef: :replace)
+    rescue ArgumentError, Encoding::UndefinedConversionError, Encoding::InvalidByteSequenceError
+      value.force_encoding(Encoding::UTF_8).encode("UTF-8", invalid: :replace, undef: :replace)
+    end
+  end
+end

data/sig/ukdah.rbs

@@ -0,0 +1,4 @@
+module Ukdah
+  VERSION: String
+  # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+end

metadata

@@ -0,0 +1,64 @@
+--- !ruby/object:Gem::Specification
+name: ukdah
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Yudai Takada
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies: []
+description: A tolerant pure-Ruby parser for mail headers, MIME trees, attachments,
+  mbox files, and threads.
+email:
+- t.yudai92@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- Rakefile
+- docs/adr/000-template.md
+- docs/adr/001-parsing-only.md
+- docs/adr/002-decoder-injection.md
+- docs/adr/README.md
+- lib/ukdah.rb
+- lib/ukdah/address.rb
+- lib/ukdah/header.rb
+- lib/ukdah/mbox.rb
+- lib/ukdah/message.rb
+- lib/ukdah/part.rb
+- lib/ukdah/quote.rb
+- lib/ukdah/thread.rb
+- lib/ukdah/version.rb
+- sig/ukdah.rbs
+homepage: https://github.com/noxdea/ukdah
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org
+  homepage_uri: https://github.com/noxdea/ukdah
+  source_code_uri: https://github.com/noxdea/ukdah/tree/main
+  changelog_uri: https://github.com/noxdea/ukdah/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.1'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.16
+specification_version: 4
+summary: Dependency-free RFC 5322 and MIME message parser
+test_files: []