iklil 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 9cac2ea2480eeeaa590210ce6c7e7af40e20e0b727959a8bda34f89e358ed057
+  data.tar.gz: 804925a2664425344bcbf54ec0fbd79ef0a5cc1a0947ae263735b0a7a7b53a56
+SHA512:
+  metadata.gz: 2c703082516cc60d10de1fe797b33688ade12535195e227266f20dda0a8cbe96137f8640b2a8a6d3b6fb7d152b13341833320434305c1c52e055b9f23346d7da
+  data.tar.gz: 1c94b8ba11b241d925f61456427a1a76a8c1189a7e38ef15809577302ea91edb2ea0dad87f8871b359d25c04b895fde8eb6f0bd432dec84a91068f823137342e

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,63 @@
+# Iklil
+
+Iklil (ρ Scorpii, from Arabic *iklīl*, “crown”) is a dependency-free Ruby
+parser for RSS, Atom, JSON Feed, and OPML. It converts the formats into one
+small immutable model and keeps diagnostics instead of dropping an entire feed
+when one item is malformed.
+
+## Features
+
+- RSS 0.90/0.91/0.92/2.0 and RSS 1.0 (RDF)
+- Atom 1.0
+- JSON Feed 1.0 and 1.1
+- OPML 1.0/2.0 import and deterministic export
+- Relative URL resolution, date normalization, and common namespace extensions
+- BOM/encoding handling, named-entity repair, control-character removal, and
+  truncated XML recovery
+- DTD and external entity removal before XML parsing
+- Ruby standard library only; Ruby 3.2+
+
+## Installation
+
+```ruby
+gem "iklil"
+```
+
+## Quick start
+
+```ruby
+require "iklil"
+
+feed = Iklil.parse(File.binread("feed.xml"), base_url: "https://example.test/")
+feed.format
+feed.entries.first.title
+feed.entries.first.published_at # a Time, or nil when absent/invalid
+feed.diagnostics
+```
+
+All feed formats expose `Iklil::Feed`, `Iklil::Entry`, and
+`Iklil::Enclosure`. `Entry#content_type` is `:html` or `:text`; Iklil does not
+execute or sanitize HTML.
+
+```ruby
+subscriptions = Iklil.parse_opml(File.binread("subscriptions.opml"))
+File.write("copy.opml", Iklil.render_opml(subscriptions, title: "Feeds"))
+```
+
+## Security
+
+Iklil never fetches URLs. XML DTDs and entity declarations are removed before
+REXML receives untrusted input, so feeds cannot make the parser read local or
+remote files. Use a separate sanitizer before displaying HTML content.
+
+## Development
+
+```sh
+bundle install
+bundle exec rake
+gem build --strict iklil.gemspec
+```
+
+## License
+
+MIT. See [LICENSE.txt](LICENSE.txt).

data/docs/adr/001-normalized-model.md

@@ -0,0 +1,21 @@
+# ADR 001: Normalize feed formats into one model
+
+- Status: Accepted
+- Date: 2026-09-21
+- Author: Yudai Takada
+
+## Decision
+
+RSS, Atom, and JSON Feed are parsed into immutable `Feed`, `Entry`, and
+`Enclosure` values. Format-specific fields remain in `Entry#extensions`.
+
+## Context
+
+The reader needs to display and sort entries without knowing which wire format
+produced them. Keeping format branches in the application would duplicate URL,
+date, and content handling.
+
+## Consequences
+
+Consumers get one stable API. New namespace fields are not lost, but consumers
+must explicitly opt into them. The parser does not perform HTML sanitization.

data/docs/adr/002-tolerant-safe-parsing.md

@@ -0,0 +1,23 @@
+# ADR 002: Tolerant parsing with diagnostics and fail-closed XML
+
+- Status: Accepted
+- Date: 2026-09-21
+- Author: Yudai Takada
+
+## Decision
+
+Iklil repairs common feed damage, returns readable fields when possible, and
+records warnings in `Feed#diagnostics`. DTDs and entity declarations are
+removed before REXML parses untrusted input.
+
+## Context
+
+Public feeds frequently contain undeclared entities, invalid dates, truncated
+downloads, or inconsistent encoding. A single bad item should not hide every
+other item. XML external entities are not needed for feeds and create an
+unacceptable local-file and network access risk.
+
+## Consequences
+
+Applications must inspect diagnostics when they need strict ingestion. Iklil
+never resolves external entities and never performs network requests.

data/docs/normalization.md

@@ -0,0 +1,20 @@
+# Feed normalization
+
+Iklil maps each supported input to the same `Feed`, `Entry`, and `Enclosure`
+models. Missing values remain `nil`; malformed values add a warning to
+`Feed#diagnostics` rather than aborting the complete feed.
+
+| Common field | RSS 2.0 / RSS 0.9x | RSS 1.0 | Atom 1.0 | JSON Feed |
+| --- | --- | --- | --- | --- |
+| `id` | `guid`, then `link`, then SHA-256 | `rdf:about`, then `link`, then SHA-256 | `id`, then link, then SHA-256 | `id`, then `url`, then SHA-256 |
+| `title` | `title` | `title` | `title` | `title` |
+| `published_at` | `pubDate`, `date` | `dc:date`, `date` | `published` | `date_published` |
+| `updated_at` | `lastBuildDate` | `dc:date` | `updated` | `date_modified` |
+| `summary` | `description` | `description` | `summary` | `summary` |
+| `content` | `content:encoded`, then `description` | `content:encoded`, then `description` | `content`, then `summary` | `content_html`, then `content_text`, then `summary` |
+| `content_type` | `:html` for `content:encoded`, otherwise `:text` | same | `type="html"`/`xhtml` => `:html` | `content_html` => `:html`, otherwise `:text` |
+| `url` | `link` | `link` | alternate `link` | `url` |
+
+Relative URLs are resolved against the caller's `base_url` and inherited
+`xml:base` values. Namespace fields not needed for the common model are kept
+in `Entry#extensions` under their original qualified name.

data/lib/iklil/models.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module Iklil
+  Diagnostic = Data.define(:severity, :message, :path) do
+    def warning?
+      severity == :warning
+    end
+  end
+
+  Enclosure = Data.define(:url, :type, :length, :duration, :title)
+
+  Entry = Data.define(
+    :id, :title, :url, :summary, :content, :content_type,
+    :published_at, :updated_at, :authors, :categories, :enclosures, :extensions
+  ) do
+    def html?
+      content_type == :html
+    end
+
+    def text?
+      content_type == :text
+    end
+  end
+
+  Feed = Data.define(
+    :title, :subtitle, :url, :site_url, :updated_at, :language, :icon,
+    :authors, :entries, :format, :diagnostics
+  ) do
+    def valid?
+      !diagnostics.any? { |diagnostic| diagnostic.severity == :error }
+    end
+  end
+
+  Subscription = Data.define(
+    :title, :xml_url, :html_url, :type, :text, :description, :language
+  )
+end

data/lib/iklil/opml.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+module Iklil
+  module OPML
+    module_function
+
+    def parse(bytes)
+      text = Preprocess.call(bytes)
+      document = REXML::Document.new(text)
+      outlines = document.root && document.root.elements.to_a("body//outline")
+      outlines ||= []
+      outlines.filter_map do |outline|
+        xml_url = XML.attribute(outline, "xmlUrl") || XML.attribute(outline, "xmlurl")
+        next unless xml_url && !xml_url.empty?
+
+        Subscription.new(
+          title: XML.attribute(outline, "title") || XML.attribute(outline, "text"),
+          xml_url: xml_url,
+          html_url: XML.attribute(outline, "htmlUrl") || XML.attribute(outline, "htmlurl"),
+          type: XML.attribute(outline, "type"), text: XML.attribute(outline, "text"),
+          description: XML.attribute(outline, "description"), language: XML.attribute(outline, "language")
+        )
+      end
+    rescue REXML::ParseException => error
+      raise Error, "invalid OPML: #{error.message}"
+    end
+
+    def render(subscriptions, title:)
+      groups = Hash.new { |hash, key| hash[key] = [] }
+      Array(subscriptions).each do |subscription|
+        groups[group_value(subscription)] << subscription
+      end
+      body = groups.map do |group, items|
+        children = items.map { |item| render_outline(item) }.join
+        if group.nil? || group.empty?
+          children
+        else
+          "<outline text=\"#{escape(group)}\" title=\"#{escape(group)}\">#{children}</outline>"
+        end
+      end.join
+      <<~XML
+        <?xml version="1.0" encoding="UTF-8"?>
+        <opml version="2.0">
+          <head><title>#{escape(title)}</title></head>
+          <body>#{body}</body>
+        </opml>
+      XML
+    end
+
+    def render_outline(subscription)
+      values = {
+        text: value(subscription, :text) || value(subscription, :title),
+        title: value(subscription, :title) || value(subscription, :text),
+        type: value(subscription, :type) || "rss",
+        xmlUrl: value(subscription, :xml_url),
+        htmlUrl: value(subscription, :html_url),
+        description: value(subscription, :description),
+        language: value(subscription, :language)
+      }
+      attributes = values.filter_map { |key, value| "#{key}=\"#{escape(value)}\"" if value && !value.to_s.empty? }.join(" ")
+      "<outline #{attributes}/>"
+    end
+
+    def value(subscription, key)
+      return subscription.public_send(key) if subscription.respond_to?(key)
+      return subscription[key.to_s] || subscription[key] if subscription.is_a?(Hash)
+
+      nil
+    end
+
+    def group_value(subscription)
+      value(subscription, :group) || value(subscription, :category)
+    end
+
+    def escape(value)
+      CGI.escapeHTML(value.to_s)
+    end
+  end
+end

data/lib/iklil/parser.rb

@@ -0,0 +1,279 @@
+# frozen_string_literal: true
+
+module Iklil
+  class Parser
+    class << self
+      def parse(bytes, base_url:, encoding:)
+        data = bytes.respond_to?(:read) ? bytes.read : bytes
+        format = detect(data)
+        return parse_json(data, base_url: base_url) if format == :json_feed
+
+        text = Preprocess.call(data, encoding: encoding)
+        document = xml_document(text)
+        root = document.root
+        return empty_feed(format, "feed has no root element") unless root
+
+        case XML.local_name(root)
+        when "rss"
+          parse_rss(root, base_url: base_url)
+        when "RDF", "rdf"
+          parse_rss1(root, base_url: base_url)
+        when "feed"
+          parse_atom(root, base_url: base_url)
+        else
+          empty_feed(nil, "unsupported feed root #{root.name.inspect}")
+        end
+      rescue JSON::ParserError => error
+        empty_feed(:json_feed, "invalid JSON Feed: #{error.message}")
+      rescue REXML::ParseException => error
+        empty_feed(format, "invalid XML: #{error.message}")
+      rescue StandardError => error
+        empty_feed(format, "could not parse feed: #{error.message}")
+      end
+
+      def detect(bytes)
+        raw = (bytes.respond_to?(:read) ? bytes.read : bytes).to_s.b.sub(/\A(?:\xEF\xBB\xBF|\xFF\xFE|\xFE\xFF)/n, "")
+        stripped = raw.lstrip
+        if stripped.start_with?("{") || stripped.start_with?("[")
+          begin
+            value = JSON.parse(raw.force_encoding(Encoding::UTF_8))
+            return :json_feed if value.is_a?(Hash) && value["version"].to_s.match?(%r{jsonfeed\.org/version/1})
+          rescue JSON::ParserError
+            return :json_feed if raw.match?(/"version"\s*:\s*"https?:\/\/jsonfeed\.org\/version\/1/i)
+          end
+        end
+
+        root = stripped[/<\s*([A-Za-z_][\w:.-]*)/, 1].to_s.split(":").last
+        case root
+        when "rss"
+          version = stripped[/<rss\b[^>]*\bversion\s*=\s*["']([^"']+)/i, 1].to_s
+          version.start_with?("0.9") ? :rss09 : :rss2
+        when "RDF", "rdf"
+          :rss1
+        when "feed"
+          :atom
+        else
+          nil
+        end
+      end
+
+      private
+
+      def xml_document(text)
+        REXML::Document.new(text)
+      rescue REXML::ParseException
+        recovered = Preprocess.close_open_elements(text)
+        raise if recovered == text
+
+        REXML::Document.new(recovered)
+      end
+
+      def parse_rss(root, base_url:)
+        diagnostics = []
+        channel = XML.child(root, "channel") || root
+        feed_base = XML.base_url(base_url, channel)
+        entries = XML.children(channel, "item").map.with_index do |item, index|
+          rss_entry(item, base_url: XML.base_url(feed_base, item), diagnostics: diagnostics, path: "channel/item[#{index}]")
+        end
+        self_url = XML.children(channel).filter_map do |node|
+          next unless XML.local_name(node) == "link" && XML.attribute(node, "rel") == "self"
+
+          XML.resolve_url(XML.attribute(node, "href"), feed_base)
+        end.first
+        Feed.new(
+          title: XML.path_text(channel, "title"),
+          subtitle: XML.path_text(channel, "description"),
+          url: self_url || feed_base,
+          site_url: XML.resolve_url(XML.path_text(channel, "link"), feed_base),
+          updated_at: date_value(XML.path_text(channel, "lastBuildDate"), diagnostics, "channel/lastBuildDate"),
+          language: XML.path_text(channel, "language"),
+          icon: XML.resolve_url(XML.path_text(channel, "image", "url"), feed_base),
+          authors: rss_authors(channel),
+          entries: entries,
+          format: root.attributes["version"].to_s.start_with?("0.9") ? :rss09 : :rss2,
+          diagnostics: diagnostics
+        )
+      end
+
+      def parse_rss1(root, base_url:)
+        diagnostics = []
+        channel = XML.child(root, "channel") || root
+        feed_base = XML.base_url(base_url, channel)
+        entries = XML.children(root, "item").map.with_index do |item, index|
+          rss_entry(item, base_url: XML.base_url(feed_base, item), diagnostics: diagnostics, path: "item[#{index}]")
+        end
+        Feed.new(
+          title: XML.path_text(channel, "title"),
+          subtitle: XML.path_text(channel, "description"),
+          url: feed_base,
+          site_url: XML.resolve_url(XML.path_text(channel, "link"), feed_base),
+          updated_at: date_value(XML.path_text(channel, "date"), diagnostics, "channel/date"),
+          language: XML.path_text(channel, "language"),
+          icon: nil,
+          authors: rss_authors(channel),
+          entries: entries,
+          format: :rss1,
+          diagnostics: diagnostics
+        )
+      end
+
+      def parse_atom(root, base_url:)
+        diagnostics = []
+        feed_base = XML.base_url(base_url, root)
+        links = XML.children(root, "link")
+        self_url = links.find { |link| XML.attribute(link, "rel").to_s == "self" }
+        site_url = links.find { |link| [nil, "alternate"].include?(XML.attribute(link, "rel")) }
+        entries = XML.children(root, "entry").map.with_index do |entry, index|
+          atom_entry(entry, base_url: XML.base_url(feed_base, entry), diagnostics: diagnostics, path: "entry[#{index}]")
+        end
+        Feed.new(
+          title: XML.deep_text(XML.child(root, "title")),
+          subtitle: XML.deep_text(XML.child(root, "subtitle")),
+          url: XML.resolve_url(XML.attribute(self_url, "href"), feed_base) || feed_base,
+          site_url: XML.resolve_url(XML.attribute(site_url, "href"), feed_base),
+          updated_at: date_value(XML.path_text(root, "updated"), diagnostics, "updated"),
+          language: XML.attribute(root, "lang"),
+          icon: XML.resolve_url(XML.path_text(root, "icon"), feed_base),
+          authors: atom_authors(root),
+          entries: entries,
+          format: :atom,
+          diagnostics: diagnostics
+        )
+      end
+
+      def parse_json(bytes, base_url:)
+        diagnostics = []
+        raw = bytes.respond_to?(:read) ? bytes.read : bytes
+        value = JSON.parse(raw.to_s.sub(/\A\xEF\xBB\xBF/, ""))
+        unless value.is_a?(Hash) && value["version"].to_s.match?(%r{jsonfeed\.org/version/1})
+          return empty_feed(:json_feed, "JSON document is not JSON Feed 1.x")
+        end
+        feed_base = base_url
+        entries = Array(value["items"]).each_with_index.each_with_object([]) do |(item, index), result|
+          if item.is_a?(Hash)
+            result << json_entry(item, base_url: feed_base, diagnostics: diagnostics, path: "items[#{index}]")
+          else
+            diagnostics << Diagnostic.new(severity: :warning, message: "item is not an object", path: "items[#{index}]")
+          end
+        end
+        Feed.new(
+          title: value["title"], subtitle: value["description"], url: XML.resolve_url(value["feed_url"], feed_base) || feed_base,
+          site_url: XML.resolve_url(value["home_page_url"], feed_base), updated_at: date_value(value["date_modified"], diagnostics, "date_modified"),
+          language: value["language"], icon: value["icon"], authors: json_authors(value["author"] || value["authors"]),
+          entries: entries, format: :json_feed, diagnostics: diagnostics
+        )
+      end
+
+      def rss_entry(item, base_url:, diagnostics:, path:)
+        link = XML.resolve_url(XML.path_text(item, "link"), base_url)
+        guid = XML.path_text(item, "guid") || XML.attribute(item, "about")
+        encoded = XML.child(item, "encoded") || XML.children(item).find { |node| node.name.to_s == "content:encoded" }
+        summary = XML.path_text(item, "description")
+        content = encoded ? XML.deep_text(encoded) : summary
+        content_type = encoded ? :html : :text
+        published = XML.path_text(item, "pubDate") || XML.path_text(item, "date")
+        updated = XML.path_text(item, "lastBuildDate") || XML.path_text(item, "date")
+        Entry.new(
+          id: guid || link || stable_id(item, content), title: XML.path_text(item, "title"), url: link,
+          summary: summary, content: content, content_type: content_type,
+          published_at: date_value(published, diagnostics, "#{path}/pubDate"),
+          updated_at: date_value(updated, diagnostics, "#{path}/lastBuildDate"), authors: rss_authors(item),
+          categories: XML.children(item, "category").filter_map { |node| XML.text(node) },
+          enclosures: rss_enclosures(item, base_url),
+          extensions: XML.extension_values(item, known: %w[title link guid description pubDate date lastBuildDate author category enclosure])
+        )
+      end
+
+      def atom_entry(entry, base_url:, diagnostics:, path:)
+        links = XML.children(entry, "link")
+        link = links.find { |node| [nil, "alternate"].include?(XML.attribute(node, "rel")) }
+        content_node = XML.child(entry, "content")
+        raw_content_type = XML.attribute(content_node, "type").to_s.downcase
+        content = content_node && (content_node.has_elements? ? XML.inner_xml(content_node) : XML.deep_text(content_node))
+        content_type = if %w[html xhtml text/html application/xhtml+xml].include?(raw_content_type) || (raw_content_type.empty? && content_node&.has_elements?)
+                         :html
+                       else
+                         :text
+                       end
+        summary = XML.deep_text(XML.child(entry, "summary"))
+        Entry.new(
+          id: XML.path_text(entry, "id") || XML.resolve_url(XML.attribute(link, "href"), base_url) || stable_id(entry, content),
+          title: XML.deep_text(XML.child(entry, "title")), url: XML.resolve_url(XML.attribute(link, "href"), base_url),
+          summary: summary, content: content || summary, content_type: content_type,
+          published_at: date_value(XML.path_text(entry, "published"), diagnostics, "#{path}/published"),
+          updated_at: date_value(XML.path_text(entry, "updated"), diagnostics, "#{path}/updated"),
+          authors: atom_authors(entry), categories: XML.children(entry, "category").filter_map { |node| XML.attribute(node, "term") || XML.text(node) },
+          enclosures: links.filter_map do |node|
+            next unless XML.attribute(node, "rel") == "enclosure"
+            Enclosure.new(url: XML.resolve_url(XML.attribute(node, "href"), base_url), type: XML.attribute(node, "type"), length: integer(XML.attribute(node, "length")), duration: nil, title: XML.attribute(node, "title"))
+          end,
+          extensions: XML.extension_values(entry, known: %w[id title link summary content published updated author category])
+        )
+      end
+
+      def json_entry(item, base_url:, diagnostics:, path:)
+        html = item["content_html"]
+        text = item["content_text"]
+        content = html || text || item["summary"]
+        content_type = html ? :html : :text
+        attachments = Array(item["attachments"]).filter_map do |attachment|
+          next unless attachment.is_a?(Hash) && attachment["url"]
+          Enclosure.new(url: XML.resolve_url(attachment["url"].to_s, base_url), type: attachment["mime_type"], length: integer(attachment["size_in_bytes"]), duration: attachment["duration_in_seconds"], title: attachment["title"])
+        end
+        Entry.new(
+          id: item["id"] || XML.resolve_url(item["url"].to_s, base_url) || stable_id(item, content),
+          title: item["title"], url: XML.resolve_url(item["url"].to_s, base_url), summary: item["summary"], content: content,
+          content_type: content_type, published_at: date_value(item["date_published"], diagnostics, "#{path}/date_published"),
+          updated_at: date_value(item["date_modified"], diagnostics, "#{path}/date_modified"), authors: json_authors(item["author"] || item["authors"]),
+          categories: Array(item["tags"]), enclosures: attachments,
+          extensions: item.reject { |key, _| %w[id title url external_url content_html content_text summary date_published date_modified author authors tags attachments].include?(key) }
+        )
+      end
+
+      def rss_authors(element)
+        %w[author creator].filter_map { |name| XML.children(element, name).filter_map { |node| XML.text(node) } }.flatten.uniq
+      end
+
+      def atom_authors(element)
+        XML.children(element, "author").filter_map do |author|
+          XML.deep_text(XML.child(author, "name")) || XML.text(author)
+        end.uniq
+      end
+
+      def json_authors(author)
+        Array(author).filter_map { |value| value.is_a?(Hash) ? (value["name"] || value["url"]) : value }.map(&:to_s).reject(&:empty?).uniq
+      end
+
+      def rss_enclosures(item, base_url)
+        XML.children(item).filter_map do |node|
+          next unless %w[enclosure content].include?(XML.local_name(node)) && (node.name == "enclosure" || XML.attribute(node, "url"))
+          Enclosure.new(url: XML.resolve_url(XML.attribute(node, "url"), base_url), type: XML.attribute(node, "type"), length: integer(XML.attribute(node, "length") || XML.attribute(node, "fileSize")), duration: XML.attribute(node, "duration"), title: XML.attribute(node, "title"))
+        end
+      end
+
+      def date_value(value, diagnostics, path)
+        return nil if value.nil? || value.to_s.strip.empty?
+
+        DateTime.parse(value.to_s).to_time
+      rescue ArgumentError, TypeError
+        diagnostics << Diagnostic.new(severity: :warning, message: "invalid date #{value.inspect}", path: path)
+        nil
+      end
+
+      def integer(value)
+        Integer(value, 10) if value && value.to_s.match?(/\A\d+\z/)
+      rescue ArgumentError
+        nil
+      end
+
+      def stable_id(value, content)
+        source = value.respond_to?(:expanded_name) ? XML.inner_xml(value) : value.to_s
+        Digest::SHA256.hexdigest([source, content].join("\u0000"))
+      end
+
+      def empty_feed(format, message)
+        Feed.new(title: nil, subtitle: nil, url: nil, site_url: nil, updated_at: nil, language: nil, icon: nil, authors: [], entries: [], format: format, diagnostics: [Diagnostic.new(severity: :error, message: message, path: nil)])
+      end
+    end
+  end
+end

data/lib/iklil/preprocess.rb

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+module Iklil
+  # Converts untrusted XML bytes into a UTF-8, non-executable XML document.
+  # DTDs are removed before REXML sees the input; REXML must never resolve
+  # external entities from a feed.
+  module Preprocess
+    module_function
+
+    XML_DECLARATION = /\A\s*<\?xml\s+[^>]*encoding\s*=\s*["']([^"']+)["']/im
+    VALID_ENTITIES = %w[amp apos gt lt quot].freeze
+    NAMED_ENTITIES = {
+      "nbsp" => 160, "copy" => 169, "reg" => 174, "trade" => 8482,
+      "hellip" => 8230, "mdash" => 8212, "ndash" => 8211, "laquo" => 171,
+      "raquo" => 187, "ldquo" => 8220, "rdquo" => 8221, "lsquo" => 8216,
+      "rsquo" => 8217, "bull" => 8226, "rarr" => 8594, "times" => 215,
+      "euro" => 8364, "yen" => 165, "pound" => 163
+    }.freeze
+
+    def call(bytes, encoding: :auto)
+      raw = (bytes.respond_to?(:read) ? bytes.read : bytes).to_s.b.dup
+      source_encoding = encoding == :auto ? sniff_encoding(raw) : encoding
+      raw = strip_bom(raw)
+      text = decode(raw, source_encoding)
+      text = strip_dtd(text)
+      text = repair_entities(text)
+      text = strip_control_chars(text)
+      text.force_encoding(Encoding::UTF_8)
+      text
+    end
+
+    def strip_bom(bytes)
+      bytes.sub(/\A(?:\xEF\xBB\xBF|\xFF\xFE|\xFE\xFF)/n, "")
+    end
+
+    def sniff_encoding(bytes)
+      return Encoding::UTF_16LE if bytes.start_with?("\xFF\xFE".b)
+      return Encoding::UTF_16BE if bytes.start_with?("\xFE\xFF".b)
+
+      match = bytes.byteslice(0, 512).to_s.force_encoding(Encoding::ASCII_8BIT).match(XML_DECLARATION)
+      return Encoding::UTF_8 unless match
+
+      Encoding.find(match[1].strip.tr("_", "-"))
+    rescue ArgumentError
+      Encoding::UTF_8
+    end
+
+    def decode(bytes, encoding)
+      source = encoding.is_a?(Encoding) ? encoding : Encoding.find(encoding.to_s)
+      bytes.dup.force_encoding(source).encode(Encoding::UTF_8, invalid: :replace, undef: :replace, replace: "�")
+    rescue Encoding::ConverterNotFoundError, Encoding::InvalidByteSequenceError, Encoding::UndefinedConversionError
+      bytes.dup.force_encoding(Encoding::UTF_8).scrub("�")
+    end
+
+    def strip_dtd(text)
+      # Handles both a simple declaration and an internal subset containing >.
+      without_doctype = text.gsub(/<!DOCTYPE\b[^\[]*(?:\[[\s\S]*?\]\s*)?>/i, "")
+      without_doctype.gsub(/<!ENTITY\b[^>]*>/i, "")
+    end
+
+    def repair_entities(text)
+      text.gsub(/&(#(?:x[0-9a-f]+|[0-9]+)|[A-Za-z][A-Za-z0-9]+);/i) do |entity|
+        value = Regexp.last_match(1)
+        if valid_numeric_entity?(value) || VALID_ENTITIES.include?(value)
+          entity
+        elsif NAMED_ENTITIES.key?(value.downcase)
+          "&#" + NAMED_ENTITIES.fetch(value.downcase).to_s + ";"
+        else
+          "&amp;#{value};"
+        end
+      end
+    end
+
+    def strip_control_chars(text)
+      text.delete("\x00-\x08\x0B\x0C\x0E-\x1F\x7F")
+    end
+
+    def valid_numeric_entity?(value)
+      return false unless value.start_with?("#")
+
+      number = value.start_with?("#x", "#X") ? value[2..].to_i(16) : value[1..].to_i(10)
+      number == 9 || number == 10 || number == 13 || (number >= 0x20 && number <= 0xD7FF) ||
+        (number >= 0xE000 && number <= 0xFFFD) || (number >= 0x10000 && number <= 0x10FFFF)
+    end
+
+    # A small recovery pass for the common case of a feed truncated while it
+    # was being downloaded. It is only used after REXML rejects the document.
+    def close_open_elements(text)
+      stack = []
+      text.scan(/<\s*(\/?)\s*([A-Za-z_][\w:.-]*)(?:\s[^<>]*?)?(\/?)\s*>/) do |closing, name, self_closing|
+        if closing == "/"
+          index = stack.rindex(name)
+          stack.slice!(index..-1) if index
+        elsif self_closing != "/" && !%w[br hr img link meta].include?(name.downcase)
+          stack << name
+        end
+      end
+      stack.reverse.reduce(text) { |value, name| "#{value}</#{name}>" }
+    end
+  end
+end

data/lib/iklil/version.rb

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

data/lib/iklil/xml.rb

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+module Iklil
+  module XML
+    module_function
+
+    def local_name(element)
+      element.name.to_s.split(":").last
+    end
+
+    def child(element, name)
+      return nil unless element
+
+      element.elements.find { |item| local_name(item) == name }
+    end
+
+    def children(element, name = nil)
+      return [] unless element
+
+      elements = element.elements.to_a
+      name ? elements.select { |item| local_name(item) == name } : elements
+    end
+
+    def text(element)
+      return nil unless element
+
+      value = element.texts.map(&:value).join
+      value = value.strip
+      value.empty? ? nil : value
+    end
+
+    def attribute(element, name)
+      return nil unless element
+
+      element.attributes.each_attribute do |attribute|
+        return attribute.value if attribute.expanded_name == name || attribute.name == name || attribute.name.split(":").last == name
+      end
+      nil
+    end
+
+    def path_text(element, *names)
+      names.reduce(element) { |current, name| child(current, name) }.then { |node| text(node) }
+    end
+
+    def base_url(base, element)
+      relative = attribute(element, "base")
+      return base unless relative && !relative.empty?
+      return relative unless base && !base.empty?
+
+      URI.join(base, relative).to_s
+    rescue URI::InvalidURIError
+      relative
+    end
+
+    def resolve_url(value, base)
+      return nil if value.nil? || value.empty?
+      return value unless base && !base.empty?
+
+      URI.join(base, value).to_s
+    rescue URI::InvalidURIError
+      value
+    end
+
+    def tree_text(element)
+      return "" unless element
+
+      element.children.map { |node| node.respond_to?(:value) ? node.value.to_s : tree_text(node) }.join
+    end
+
+    def deep_text(element)
+      return nil unless element
+
+      value = tree_text(element).strip
+      value.empty? ? nil : value
+    end
+
+    def inner_xml(element)
+      return "" unless element
+
+      element.children.map do |node|
+        if node.respond_to?(:value)
+          CGI.escapeHTML(node.value.to_s)
+        else
+          attributes = node.attributes.each_attribute.map { |attribute| "#{attribute.expanded_name}=\"#{CGI.escapeHTML(attribute.value.to_s)}\"" }
+          opening = attributes.empty? ? "<#{node.name}>" : "<#{node.name} #{attributes.join(" ")}>"
+          "#{opening}#{inner_xml(node)}</#{node.name}>"
+        end
+      end.join
+    end
+
+    def extension_values(element, known: [])
+      return {} unless element
+
+      element.elements.each_with_object({}) do |node, result|
+        local = local_name(node)
+        next if known.include?(local)
+
+        key = node.expanded_name.to_s
+        value = if node.has_elements?
+                  extension_values(node)
+                else
+                  text(node) || ""
+                end
+        result[key] = result.key?(key) ? Array(result[key]) + [value] : value
+      end
+    end
+  end
+end

data/lib/iklil.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+require "cgi"
+require "date"
+require "digest"
+require "json"
+require "rexml/document"
+require "time"
+require "uri"
+
+require_relative "iklil/version"
+require_relative "iklil/models"
+require_relative "iklil/preprocess"
+require_relative "iklil/xml"
+require_relative "iklil/parser"
+require_relative "iklil/opml"
+
+module Iklil
+  class Error < StandardError; end
+
+  module_function
+
+  def parse(bytes, base_url: nil, encoding: :auto)
+    Parser.parse(bytes, base_url: base_url, encoding: encoding)
+  end
+
+  def detect(bytes)
+    Parser.detect(bytes)
+  end
+
+  def parse_opml(bytes)
+    OPML.parse(bytes)
+  end
+
+  def render_opml(subscriptions, title: "Iklil subscriptions")
+    OPML.render(subscriptions, title: title)
+  end
+end

data/sig/iklil.rbs

@@ -0,0 +1,69 @@
+module Iklil
+  VERSION: String
+
+  class Error < StandardError
+  end
+
+  class Diagnostic
+    attr_reader severity: Symbol
+    attr_reader message: String
+    attr_reader path: String?
+    def initialize: (severity: Symbol, message: String, path: String?) -> void
+    def warning?: () -> bool
+  end
+
+  class Enclosure
+    attr_reader url: String?
+    attr_reader type: String?
+    attr_reader length: Integer?
+    attr_reader duration: Integer?
+    attr_reader title: String?
+  end
+
+  class Entry
+    attr_reader id: String
+    attr_reader title: String?
+    attr_reader url: String?
+    attr_reader summary: String?
+    attr_reader content: String?
+    attr_reader content_type: Symbol
+    attr_reader published_at: Time?
+    attr_reader updated_at: Time?
+    attr_reader authors: Array[String]
+    attr_reader categories: Array[String]
+    attr_reader enclosures: Array[Enclosure]
+    attr_reader extensions: Hash[String, untyped]
+    def html?: () -> bool
+    def text?: () -> bool
+  end
+
+  class Feed
+    attr_reader title: String?
+    attr_reader subtitle: String?
+    attr_reader url: String?
+    attr_reader site_url: String?
+    attr_reader updated_at: Time?
+    attr_reader language: String?
+    attr_reader icon: String?
+    attr_reader authors: Array[String]
+    attr_reader entries: Array[Entry]
+    attr_reader format: Symbol?
+    attr_reader diagnostics: Array[Diagnostic]
+    def valid?: () -> bool
+  end
+
+  class Subscription
+    attr_reader title: String?
+    attr_reader xml_url: String
+    attr_reader html_url: String?
+    attr_reader type: String?
+    attr_reader text: String?
+    attr_reader description: String?
+    attr_reader language: String?
+  end
+
+  def self.parse: (String | IO, base_url: String?, encoding: Symbol | String | Encoding) -> Feed
+  def self.detect: (String | IO) -> Symbol?
+  def self.parse_opml: (String | IO) -> Array[Subscription]
+  def self.render_opml: (Array[Subscription], title: String) -> String
+end

metadata

@@ -0,0 +1,60 @@
+--- !ruby/object:Gem::Specification
+name: iklil
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Yudai Takada
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies: []
+description: A dependency-free Ruby parser that normalizes RSS, Atom, JSON Feed, and
+  OPML data while safely handling malformed input.
+email:
+- t.yudai92@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- docs/adr/001-normalized-model.md
+- docs/adr/002-tolerant-safe-parsing.md
+- docs/normalization.md
+- lib/iklil.rb
+- lib/iklil/models.rb
+- lib/iklil/opml.rb
+- lib/iklil/parser.rb
+- lib/iklil/preprocess.rb
+- lib/iklil/version.rb
+- lib/iklil/xml.rb
+- sig/iklil.rbs
+homepage: https://github.com/noxdea/iklil
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org
+  homepage_uri: https://github.com/noxdea/iklil
+  source_code_uri: https://github.com/noxdea/iklil/tree/main
+  changelog_uri: https://github.com/noxdea/iklil/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.2'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.16
+specification_version: 4
+summary: Tolerant RSS, Atom, JSON Feed, and OPML parser
+test_files: []