jabbah 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: da38bea94b75acc44485f8bd90544db3358abba97a2644ad5e2c779ee0661eee
+  data.tar.gz: 050f44d09b431c091543f8fb0b3bc0b692f4fb2403ead7daddea419b04ee9c4e
+SHA512:
+  metadata.gz: b05e83a520b8525b9caf56e000bd778586e2e0a5cfb7ff901857654a77b37f1ec79fa6c85267c1a6b994a9b867d19623e7b1beb8172c0669a6380fd99445abc2
+  data.tar.gz: 6f6c4c9c53f110040697dd6382db714dbfc2b61e3d4b8ffdebf647edaaaf73c869aa4df0a3c5caa6fc07455b7d0e1c84adfe18f08ecb9f51a0e04dce9be55a45

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,62 @@
+# Jabbah
+
+Jabbah (ν Scorpii, from Arabic *jabha*, “forehead”) is a dependency-free
+Ruby HTML parser for static documents and reader applications. It builds a
+tolerant tree, supports a useful CSS selector subset, serializes safely, and
+includes conservative sanitization and article extraction. It never executes
+JavaScript.
+
+## Features
+
+- Error-tolerant HTML and fragment parsing with implicit element closing
+- Elements, text, comments, doctypes, attributes, traversal, and cloning
+- Tag, id, class, attribute, descendant/child, and common structural selectors
+- UTF-8, BOM, and declared charset decoding using Ruby's standard library
+- `docs`, `feed`, and `mail` sanitization profiles with XSS-safe URL handling
+- Remote-image blocking with `data-blocked-src`, `cid:` preservation, and callbacks
+- Readability-style article extraction without network access or native extensions
+
+## Installation
+
+```ruby
+gem "jabbah"
+```
+
+```sh
+gem install jabbah
+```
+
+## Quick start
+
+```ruby
+require "jabbah"
+
+document = Jabbah.parse("<article><h1>Hello</h1><p>Welcome.</p></article>")
+puts document.at("article").text
+puts document.to_html
+
+safe = Jabbah::Sanitize.clean(document, profile: :feed, base_url: "https://example.test/")
+article = Jabbah::Extract.article(safe)
+puts article[:title] if article
+```
+
+`Jabbah.parse` returns a `Jabbah::Document`; `Jabbah.fragment` parses a
+fragment without adding `html`, `head`, or `body` wrappers. `Document#at`
+returns the first match and `#search` returns all matches.
+
+Sanitization returns a cloned document. Remote images are blocked by default;
+the number blocked is available as `Document#blocked_count`. Link targets are
+forced to `_blank` with `noopener noreferrer`.
+
+## Development
+
+```sh
+bundle install
+bundle exec rake test
+```
+
+Jabbah has no runtime dependencies and requires Ruby 3.2 or newer.
+
+## License
+
+Jabbah is released under the [MIT License](LICENSE.txt).

data/docs/adr/001-tree-and-serialization.md

@@ -0,0 +1,25 @@
+# ADR 001: Tree and serialization only, no DOM API
+
+- Status: accepted
+- Date: 2026-09-21
+- Author: Yudai Takada
+
+## Context
+
+Jabbah is shared by reader-mode applications that need to inspect and safely
+render static HTML. A browser-compatible live DOM would require JavaScript,
+mutation observers, layout, and a large API surface that these applications do
+not need.
+
+## Decision
+
+Jabbah exposes a snapshot tree of document, element, text, comment, and doctype
+nodes. It provides traversal, CSS selector queries, cloning, and deterministic
+serialization. It does not implement a browser DOM, event dispatch, JavaScript,
+or layout. Sanitization operates on a cloned snapshot and returns a document.
+
+## Consequences
+
+The library remains dependency-free and small enough for local documents,
+feeds, and mail. Applications that need live DOM behavior must use a dedicated
+browser engine; that is intentionally outside Jabbah's scope.

data/lib/jabbah/document.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+module Jabbah
+  class Document
+    attr_reader :encoding, :blocked_count
+
+    def self.parse(input, encoding: :auto)
+      text, detected = EncodingSupport.decode(input, encoding)
+      document = Parser.new(text, fragment: false).parse
+      document.instance_variable_set(:@encoding, detected)
+      document
+    end
+
+    def self.fragment(input, context: "div")
+      text, detected = EncodingSupport.decode(input, :auto)
+      document = Parser.new(text, fragment: true, context: context).parse
+      document.instance_variable_set(:@encoding, detected)
+      document
+    end
+
+    def initialize(tree, encoding: Encoding::UTF_8)
+      @tree = tree
+      @encoding = encoding
+      @blocked_count = 0
+    end
+
+    def root
+      @tree.children.find(&:element?) || @tree
+    end
+
+    def children = @tree.children
+    def head = root.element? ? root.children.find { |node| node.element? && node.name == "head" } : nil
+    def body = root.element? ? root.children.find { |node| node.element? && node.name == "body" } : nil
+    def title = search("title").first&.text&.strip
+    def doctype = @tree.children.find { |node| node.type == :doctype }&.data
+    def text = @tree.text
+
+    def at(selector)
+      search(selector).first
+    end
+
+    def search(selector)
+      Selector.search(@tree, selector)
+    end
+
+    def each(&block) = @tree.each(&block)
+    def to_html(indent: nil) = @tree.to_html(indent: indent)
+    def clone = Document.new(@tree.clone, encoding: encoding)
+
+    def mark_blocked!(count)
+      @blocked_count = count
+      self
+    end
+  end
+
+  module EncodingSupport
+    module_function
+
+    def decode(input, requested)
+      bytes = input.to_s.dup
+      bytes.force_encoding(Encoding::BINARY)
+      if requested != :auto
+        encoding = Encoding.find(requested.to_s)
+        return [bytes.force_encoding(encoding).encode(Encoding::UTF_8, invalid: :replace, undef: :replace), encoding]
+      end
+
+      if bytes.start_with?("\xEF\xBB\xBF".b)
+        return [bytes.byteslice(3..).force_encoding(Encoding::UTF_8).scrub, Encoding::UTF_8]
+      end
+      if bytes.start_with?("\xFF\xFE".b)
+        return [bytes.byteslice(2..).force_encoding(Encoding::UTF_16LE).encode(Encoding::UTF_8, invalid: :replace), Encoding::UTF_16LE]
+      end
+      if bytes.start_with?("\xFE\xFF".b)
+        return [bytes.byteslice(2..).force_encoding(Encoding::UTF_16BE).encode(Encoding::UTF_8, invalid: :replace), Encoding::UTF_16BE]
+      end
+
+      ascii = bytes.byteslice(0, 4096).to_s.force_encoding(Encoding::ASCII_8BIT)
+      declared = ascii[/<meta[^>]+charset\s*=\s*["']?\s*([A-Za-z0-9._-]+)/i, 1]
+      if declared
+        begin
+          encoding = Encoding.find(declared)
+          return [bytes.force_encoding(encoding).encode(Encoding::UTF_8, invalid: :replace, undef: :replace), encoding]
+        rescue ArgumentError
+          # Fall through to UTF-8 for unknown declarations.
+        end
+      end
+      [bytes.force_encoding(Encoding::UTF_8).scrub, Encoding::UTF_8]
+    end
+  end
+end

data/lib/jabbah/extract.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module Jabbah
+  module Extract
+    module_function
+
+    POSITIVE = /article|content|entry|main|page|post|story|text|body/i
+    NEGATIVE = /ad|advert|comment|footer|header|nav|promo|related|share|sidebar|social|sponsor/i
+
+    def article(document)
+      doc = document.is_a?(Document) ? document : Document.parse(document)
+      candidates = doc.search("article, main, section, div, td")
+      scored = candidates.filter_map do |node|
+        score = score_node(node)
+        [score, node] if score >= 1
+      end
+      best = scored.max_by(&:first)&.last
+      return nil unless best
+
+      title = doc.title || doc.at("h1")&.text&.strip
+      byline_node = doc.search("[class], [id]").find { |node| node["class"].to_s.match?(/author|byline/i) || node["id"].to_s.match?(/author|byline/i) }
+      excerpt = normalize(best.text)[0, 240]
+      {title: title, byline: byline_node&.text&.strip, content: best, excerpt: excerpt}
+    end
+
+    def score_node(node)
+      text = normalize(node.text)
+      return -100 if text.length < 40
+
+      paragraphs = node.descendants.count { |child| child.element? && %w[p pre].include?(child.name) }
+      return -100 if paragraphs.zero? && node.name == "div"
+
+      links = node.search("a").sum { |link| normalize(link.text).length }
+      density = text.length - [links * 2, text.length].min
+      classes = "#{node["id"]} #{node["class"]}"
+      score = (density / 100.0) + (paragraphs * 3)
+      score += 25 if classes.match?(POSITIVE)
+      score -= 35 if classes.match?(NEGATIVE)
+      score
+    end
+
+    def normalize(text)
+      text.to_s.gsub(/\s+/, " ").strip
+    end
+  end
+end

data/lib/jabbah/node.rb

@@ -0,0 +1,146 @@
+# frozen_string_literal: true
+
+require "cgi/escape"
+
+module Jabbah
+  class Node
+    VOID_ELEMENTS = %w[area base br col embed hr img input link meta param source track wbr].freeze
+
+    attr_accessor :parent
+    attr_reader :type, :name, :attributes, :children, :data
+
+    def initialize(type, name: nil, attributes: {}, data: nil)
+      @type = type
+      @name = name&.downcase
+      @attributes = attributes.each_with_object({}) { |(key, value), result| result[key.to_s.downcase] = value }
+      @data = data
+      @children = []
+      @parent = nil
+    end
+
+    def element? = type == :element
+    def text? = type == :text
+    def comment? = type == :comment
+    def document? = type == :document
+
+    def [](key)
+      return @data if key.to_s == "text" && text?
+
+      @attributes[key.to_s.downcase]
+    end
+
+    def []=(key, value)
+      raise Error, "attributes are only available on elements" unless element?
+
+      @attributes[key.to_s.downcase] = value
+    end
+
+    def add_child(child)
+      child.remove if child.parent
+      child.parent = self
+      @children << child
+      child
+    end
+
+    def prepend_child(child)
+      child.remove if child.parent
+      child.parent = self
+      @children.unshift(child)
+      child
+    end
+
+    def remove
+      parent&.children&.delete(self)
+      @parent = nil
+      self
+    end
+
+    def each(&block)
+      return enum_for(:each) unless block
+
+      @children.each(&block)
+    end
+
+    def ancestors
+      result = []
+      current = parent
+      while current
+        result << current
+        current = current.parent
+      end
+      result
+    end
+
+    def descendants(&block)
+      nodes = []
+      walk = lambda do |node|
+        node.children.each do |child|
+          nodes << child
+          walk.call(child)
+        end
+      end
+      walk.call(self)
+      return nodes.each(&block) if block
+
+      nodes.each
+    end
+
+    def at(selector)
+      search(selector).first
+    end
+
+    def search(selector)
+      Selector.search(self, selector)
+    end
+
+    def text
+      return data.to_s if text?
+      return "" if %i[comment doctype].include?(type)
+
+      children.map(&:text).join
+    end
+
+    def clone
+      copy = Node.new(type, name: name, attributes: attributes.dup, data: data)
+      children.each { |child| copy.add_child(child.clone) }
+      copy
+    end
+
+    def to_html(indent: nil, level: 0)
+      case type
+      when :document
+        return render_children(nil, level) unless indent
+
+        children.map { |child| "#{indent * level}#{child.to_html(indent: indent, level: level)}" }.join("\n")
+      when :text
+        CGI.escapeHTML(data.to_s)
+      when :comment
+        "<!--#{data}-->"
+      when :doctype
+        "<!DOCTYPE #{data || "html"}>"
+      when :element
+        opening = "<#{name}#{render_attributes}>"
+        return opening if VOID_ELEMENTS.include?(name)
+        closing = "</#{name}>"
+        return "#{opening}#{render_children(nil, level)}#{closing}" unless indent
+        return "#{opening}#{closing}" if children.empty?
+        return "#{opening}#{render_children(nil, level)}#{closing}" if children.none?(&:element?)
+
+        body = children.map { |child| "#{indent * (level + 1)}#{child.to_html(indent: indent, level: level + 1)}" }.join("\n")
+        "#{opening}\n#{body}\n#{indent * level}#{closing}"
+      end
+    end
+
+    private
+
+    def render_attributes
+      attributes.map do |key, value|
+        value.nil? ? " #{key}" : " #{key}=\"#{CGI.escapeHTML(value.to_s)}\""
+      end.join
+    end
+
+    def render_children(indent, level)
+      children.map { |child| child.to_html(indent: indent, level: level) }.join
+    end
+  end
+end

data/lib/jabbah/parser.rb

@@ -0,0 +1,230 @@
+# frozen_string_literal: true
+
+require "cgi/escape"
+
+module Jabbah
+  class Parser
+    BLOCK_ELEMENTS = %w[address article aside blockquote div dl fieldset footer form h1 h2 h3 h4 h5 h6 header hr main nav ol p pre section table ul].freeze
+    RAW_ELEMENTS = %w[script style].freeze
+
+    def initialize(source, fragment:, context: "div")
+      @source = source.to_s.encode(Encoding::UTF_8, invalid: :replace, undef: :replace)
+      @fragment = fragment
+      @context = context.to_s.downcase
+      @document = Node.new(:document)
+      @stack = [@document]
+      @index = 0
+    end
+
+    def parse
+      scan
+      normalize_document unless @fragment
+      Document.new(@document)
+    end
+
+    private
+
+    def scan
+      while @index < @source.length
+        if @source[@index] != "<"
+          add_text(read_text)
+        elsif @source[@index, 4] == "<!--"
+          add_comment
+        elsif @source[@index, 9].to_s.downcase == "<!doctype"
+          add_doctype
+        elsif @source[@index, 9] == "<![CDATA["
+          add_cdata
+        elsif @source[@index, 2] == "</"
+          close_tag
+        elsif @source[@index, 2] == "<?"
+          skip_processing_instruction
+        else
+          add_tag
+        end
+      end
+    end
+
+    def read_text
+      finish = @source.index("<", @index) || @source.length
+      text = @source[@index...finish]
+      @index = finish
+      CGI.unescapeHTML(text)
+    end
+
+    def add_text(text)
+      return if text.empty?
+
+      current = @stack.last
+      if current.children.last&.text?
+        current.children.last.data << text
+      else
+        current.add_child(Node.new(:text, data: text))
+      end
+    end
+
+    def add_comment
+      finish = @source.index("-->", @index + 4)
+      finish ||= @source.length
+      data = @source[(@index + 4)...finish]
+      @stack.last.add_child(Node.new(:comment, data: data))
+      @index = [finish + 3, @source.length].min
+    end
+
+    def add_doctype
+      finish = @source.index(">", @index + 2) || @source.length - 1
+      raw = @source[(@index + 2)...finish].strip
+      raw = raw.sub(/^doctype\s*/i, "")
+      @document.add_child(Node.new(:doctype, data: raw.empty? ? "html" : raw))
+      @index = finish + 1
+    end
+
+    def add_cdata
+      finish = @source.index("]]>", @index + 9)
+      finish ||= @source.length
+      add_text(@source[(@index + 9)...finish])
+      @index = [finish + 3, @source.length].min
+    end
+
+    def skip_processing_instruction
+      finish = @source.index(">", @index + 2) || @source.length - 1
+      @index = finish + 1
+    end
+
+    def close_tag
+      match = @source[(@index + 2)..].match(/\A\s*([A-Za-z][\w:-]*)[^>]*>/)
+      unless match
+        add_text("<")
+        @index += 1
+        return
+      end
+      name = match[1].downcase
+      @index += match[0].length + 2
+      position = @stack.rindex { |node| node.element? && node.name == name }
+      @stack.slice!(position..-1) if position && position.positive?
+    end
+
+    def add_tag
+      match = @source[(@index + 1)..].match(/\A\s*([A-Za-z][\w:-]*)(.*?)(\/?)>/m)
+      unless match
+        add_text("<")
+        @index += 1
+        return
+      end
+      name = match[1].downcase
+      attributes = parse_attributes(match[2])
+      explicit_close = !match[3].empty?
+      close_open_elements(name)
+      node = Node.new(:element, name: name, attributes: attributes)
+      @stack.last.add_child(node)
+      @index += match[0].length + 1
+      return if explicit_close || Node::VOID_ELEMENTS.include?(name)
+
+      if RAW_ELEMENTS.include?(name)
+        @stack << node
+        end_tag = @source.downcase.index("</#{name}", @index)
+        if end_tag
+          add_text(@source[@index...end_tag])
+          @index = end_tag
+          close_tag
+        else
+          add_text(@source[@index..])
+          @index = @source.length
+        end
+      else
+        @stack << node
+      end
+    end
+
+    def parse_attributes(source)
+      attributes = {}
+      index = 0
+      while index < source.length
+        index += 1 while index < source.length && source[index] =~ /\s/
+        break if index >= source.length
+        name_match = source[index..].match(/\A([^\s=\/>]+)/)
+        break unless name_match
+        name = name_match[1].downcase
+        index += name_match[0].length
+        index += 1 while index < source.length && source[index] =~ /\s/
+        value = nil
+        if source[index] == "="
+          index += 1
+          index += 1 while index < source.length && source[index] =~ /\s/
+          if ["\"", "'"].include?(source[index])
+            quote = source[index]
+            index += 1
+            finish = source.index(quote, index) || source.length
+            value = source[index...finish]
+            index = [finish + 1, source.length].min
+          else
+            finish = source[index..].index(/\s/) || (source.length - index)
+            value = source[index, finish]
+            index += finish
+          end
+        end
+        attributes[name] ||= value.nil? ? "" : CGI.unescapeHTML(value)
+      end
+      attributes
+    end
+
+    def close_open_elements(name)
+      current = @stack.last
+      return unless current.element?
+
+      if name == "li"
+        close_until("li")
+      elsif %w[dt dd].include?(name)
+        close_until("dt", "dd")
+      elsif %w[tr].include?(name)
+        close_until("tr")
+      elsif %w[td th].include?(name)
+        close_until("td", "th")
+      elsif name == "option"
+        close_until("option")
+      elsif @stack.any? { |node| node.element? && node.name == "p" } && (BLOCK_ELEMENTS.include?(name) || name == "p")
+        close_until("p")
+      elsif current.name == "a" && name == "a"
+        close_until("a")
+      end
+    end
+
+    def close_until(*names)
+      position = @stack.rindex { |node| node.element? && names.include?(node.name) }
+      @stack.slice!(position..-1) if position && position.positive?
+    end
+
+    def normalize_document
+      html = @document.children.find { |node| node.element? && node.name == "html" }
+      unless html
+        html = Node.new(:element, name: "html")
+        original = @document.children.reject { |node| node.type == :doctype }
+        original.each(&:remove)
+        @document.add_child(html)
+        original.each { |node| html.add_child(node) }
+      end
+      head = html.children.find { |node| node.element? && node.name == "head" }
+      body = html.children.find { |node| node.element? && node.name == "body" }
+      unless head
+        head = Node.new(:element, name: "head")
+        html.prepend_child(head)
+      end
+      unless body
+        body = Node.new(:element, name: "body")
+        html.add_child(body)
+      end
+      # HTML5 places title/meta/link before body; move only obvious head content.
+      html.children.reject { |node| node.equal?(head) || node.equal?(body) }.each do |node|
+        next unless node.element? && %w[base link meta title style].include?(node.name)
+
+        node.remove
+        head.add_child(node)
+      end
+      html.children.reject { |node| node.equal?(head) || node.equal?(body) }.each do |node|
+        next if node.parent.equal?(body)
+
+        node.remove
+        body.add_child(node)
+      end
+    end
+  end
+end

data/lib/jabbah/sanitize.rb

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+require "uri"
+
+module Jabbah
+  module Sanitize
+    DROP_ELEMENTS = %w[base embed form iframe link object script style].freeze
+    PROFILES = {
+      docs: {allow_style: false, allow_remote_images: false},
+      feed: {allow_style: false, allow_remote_images: false},
+      mail: {allow_style: false, allow_remote_images: false}
+    }.freeze
+    DEFAULT = PROFILES[:docs]
+    SAFE_ELEMENTS = %w[a abbr article aside b blockquote body br caption cite code col colgroup dd del details div dl dt em figcaption figure h1 h2 h3 h4 h5 h6 head header hr html i img ins kbd li main mark meta nav ol p pre q rp rt ruby s samp section small span strong sub summary sup table tbody td tfoot th thead time title tr u ul var].freeze
+    GLOBAL_ATTRIBUTES = %w[aria-label aria-describedby aria-hidden class dir id lang role title].freeze
+    URL_ATTRIBUTES = %w[href src cite action poster].freeze
+
+    module_function
+
+    def clean(document, profile: :docs, allow: DEFAULT, base_url: nil, on_blocked: nil)
+      source = document.is_a?(Document) ? document.clone : Document.parse(document)
+      options = profile.is_a?(Hash) ? profile : PROFILES.fetch(profile.to_sym) { DEFAULT }
+      allowed = allow.is_a?(Hash) ? allow : DEFAULT
+      blocked = 0
+      walk = lambda do |node|
+        node.children.dup.each do |child|
+          if child.element?
+            if DROP_ELEMENTS.include?(child.name) || !SAFE_ELEMENTS.include?(child.name)
+              child.remove
+              next
+            end
+            if child.name == "meta" && child["http-equiv"].to_s.casecmp("refresh").zero?
+              child.remove
+              next
+            end
+            sanitize_attributes(child, options, allowed, base_url) do |url|
+              blocked += 1
+              on_blocked&.call(url)
+            end
+            walk.call(child)
+          elsif child.comment?
+            child.remove
+          end
+        end
+      end
+      walk.call(source.instance_variable_get(:@tree))
+      source.mark_blocked!(blocked)
+    end
+
+    def sanitize_attributes(node, options, allowed, base_url)
+      node.attributes.keys.each do |name|
+        value = node[name]
+        unless attribute_allowed?(name, node.name, allowed)
+          node.attributes.delete(name)
+          next
+        end
+        if name.start_with?("on") || name == "style"
+          node.attributes.delete(name)
+          next
+        end
+        if URL_ATTRIBUTES.include?(name)
+          url = clean_url(value, base_url: base_url, attribute: name, node: node,
+            allow_remote_images: options[:allow_remote_images])
+          if url == :blocked_image
+            original = value.to_s
+            node.attributes.delete(name)
+            node["data-blocked-src"] = original
+            yield original
+          elsif url == :invalid
+            node.attributes.delete(name)
+          else
+            node[name] = url
+          end
+        end
+      end
+      if node.name == "a" && node["href"]
+        node["target"] = "_blank"
+        rel = node["rel"].to_s.split
+        node["rel"] = (rel + %w[noopener noreferrer]).uniq.join(" ")
+      end
+    end
+
+    def attribute_allowed?(name, _element, allowed)
+      return true if GLOBAL_ATTRIBUTES.include?(name) || name.start_with?("aria-") || name.start_with?("data-")
+      return true if allowed.is_a?(Hash) && allowed[name]
+
+      %w[alt charset content height href http-equiv id media name rel role src target type width].include?(name)
+    end
+
+    def clean_url(value, base_url:, attribute:, node:, allow_remote_images: false)
+      original = value.to_s.strip.gsub(/[\x00-\x20]/, "")
+      return :invalid if original.empty?
+      downcased = original.downcase
+      if downcased.start_with?("data:")
+        return :invalid unless node.name == "img" && original.match?(/\Adata:image\/(?:png|gif|jpe?g|webp);base64,[a-z0-9+\/=]+\z/i)
+        return original
+      end
+      return :invalid if downcased.start_with?("javascript:", "vbscript:", "file:")
+      return :invalid if attribute != "src" && downcased.start_with?("cid:")
+      return original if downcased.start_with?("cid:")
+
+      if node.name == "img" && !allow_remote_images && downcased.match?(%r{\A(?:https?:)?//})
+        return :blocked_image
+      end
+      return original unless base_url
+
+      URI.join(base_url.to_s, original).to_s
+    rescue URI::InvalidURIError
+      :invalid
+    end
+  end
+end

data/lib/jabbah/selector.rb

@@ -0,0 +1,241 @@
+# frozen_string_literal: true
+
+module Jabbah
+  module Selector
+    module_function
+
+    def search(root, expression)
+      groups = split_groups(expression.to_s)
+      root.descendants.select { |node| node.element? && groups.any? { |group| matches?(node, group) } }
+    end
+
+    def matches?(node, group)
+      parts = parse_group(group)
+      return false if parts.empty? || !simple_match?(node, parts[-1][0])
+
+      current = node
+      (parts.length - 2).downto(0) do |index|
+        simple, combinator = parts[index]
+        if combinator == :child
+          current = current.parent
+          return false unless current&.element? && simple_match?(current, simple)
+        else
+          current = current.ancestors.find { |ancestor| ancestor.element? && simple_match?(ancestor, simple) }
+          return false unless current
+        end
+      end
+      true
+    end
+
+    def split_groups(expression)
+      groups = []
+      start = 0
+      quote = nil
+      depth = 0
+      expression.each_char.with_index do |char, index|
+        if quote
+          quote = nil if char == quote
+        elsif ["\"", "'"].include?(char)
+          quote = char
+        elsif char == "[" || char == "("
+          depth += 1
+        elsif char == "]" || char == ")"
+          depth -= 1
+        elsif char == "," && depth.zero?
+          groups << expression[start...index].strip
+          start = index + 1
+        end
+      end
+      groups << expression[start..].to_s.strip
+      groups.reject(&:empty?)
+    end
+
+    def parse_group(group)
+      simples = []
+      combinators = []
+      buffer = +""
+      quote = nil
+      depth = 0
+      whitespace = false
+      flush = lambda do
+        next if buffer.strip.empty?
+
+        simples << parse_simple(buffer.strip)
+        buffer.clear
+        if simples.length > 1 && combinators.length < simples.length - 1
+          combinators << (whitespace ? :descendant : :child)
+        end
+        whitespace = false
+      end
+
+      group.each_char do |char|
+        if quote
+          buffer << char
+          quote = nil if char == quote
+        elsif ["\"", "'"].include?(char)
+          quote = char
+          buffer << char
+        elsif char == "[" || char == "("
+          depth += 1
+          buffer << char
+        elsif char == "]" || char == ")"
+          depth -= 1
+          buffer << char
+        elsif depth.zero? && char == ">"
+          flush.call
+          whitespace = false
+          combinators << :child if simples.length > combinators.length
+        elsif depth.zero? && char.match?(/\s/)
+          flush.call
+          whitespace = true
+        else
+          buffer << char
+        end
+      end
+      flush.call
+      # The scanner above records explicit child combinators and implicit spaces;
+      # normalize the relation list to one relation per adjacent simple selector.
+      relations = group_relations(group, simples.length)
+      simples.each_with_index.map { |simple, index| [simple, relations[index]] }
+    end
+
+    def group_relations(group, count)
+      return [] if count < 2
+
+      relations = []
+      quote = nil
+      depth = 0
+      pending_space = false
+      group.each_char do |char|
+        if quote
+          quote = nil if char == quote
+        elsif ["\"", "'"].include?(char)
+          quote = char
+        elsif char == "[" || char == "("
+          depth += 1
+        elsif char == "]" || char == ")"
+          depth -= 1
+        elsif depth.zero? && char.match?(/\s/)
+          pending_space = true
+        elsif depth.zero? && char == ">"
+          relations << :child
+          pending_space = false
+        elsif depth.zero? && !char.match?(/\s/)
+          if pending_space && relations.length < count - 1
+            relations << :descendant unless relations.last == :child
+          end
+          pending_space = false
+        end
+      end
+      relations.fill(:descendant, relations.length...count - 1)
+    end
+
+    def parse_simple(source)
+      result = {tag: nil, ids: [], classes: [], attrs: [], pseudos: []}
+      rest = source.dup
+      if (tag = rest[/\A(?:[A-Za-z][\w-]*|\*)/])
+        result[:tag] = tag.downcase unless tag == "*"
+        rest = rest[tag.length..]
+      end
+      until rest.empty?
+        case rest[0]
+        when "#", "."
+          marker = rest[0]
+          match = rest[1..].match(/\A[\w:-]+/)
+          break unless match
+          result[marker == "#" ? :ids : :classes] << match[0]
+          rest = rest[match[0].length + 1..]
+        when "["
+          finish = matching_bracket(rest, "[", "]")
+          break unless finish
+          content = rest[1...finish].strip
+          if (match = content.match(/\A([^\s~|^$*!=]+)\s*(?:(\^=|\$=|\*=|~=|\|=|!=|=)\s*["']?(.*?)["']?)?\z/))
+            result[:attrs] << [match[1].downcase, match[2], match[3]&.strip]
+          end
+          rest = rest[(finish + 1)..]
+        when ":"
+          match = rest.match(/\A:([\w-]+)(?:\((.*?)\))?/)
+          break unless match
+          result[:pseudos] << [match[1].downcase, match[2]]
+          rest = rest[match[0].length..]
+        else
+          rest = rest[1..]
+        end
+      end
+      result
+    end
+
+    def matching_bracket(text, opening, closing)
+      depth = 0
+      quote = nil
+      text.each_char.with_index do |char, index|
+        if quote
+          quote = nil if char == quote
+        elsif ["\"", "'"].include?(char)
+          quote = char
+        elsif char == opening
+          depth += 1
+        elsif char == closing
+          depth -= 1
+          return index if depth.zero?
+        end
+      end
+      nil
+    end
+
+    def simple_match?(node, simple)
+      return false unless node.element?
+      return false if simple[:tag] && node.name != simple[:tag]
+      return false unless simple[:ids].all? { |id| node["id"] == id }
+      classes = node["class"].to_s.split
+      return false unless simple[:classes].all? { |name| classes.include?(name) }
+      return false unless simple[:attrs].all? { |attribute| attribute_match?(node, attribute) }
+      simple[:pseudos].all? { |pseudo, value| pseudo_match?(node, pseudo, value) }
+    end
+
+    def attribute_match?(node, (name, operator, expected))
+      actual = node[name]
+      return !actual.nil? if operator.nil?
+      return false if actual.nil?
+
+      case operator
+      when "=" then actual == expected
+      when "!=" then actual != expected
+      when "^=" then actual.start_with?(expected.to_s)
+      when "$=" then actual.end_with?(expected.to_s)
+      when "*=" then actual.include?(expected.to_s)
+      when "~=" then actual.split.include?(expected.to_s)
+      when "|=" then actual == expected || actual.start_with?("#{expected}-")
+      else false
+      end
+    end
+
+    def pseudo_match?(node, pseudo, value)
+      siblings = node.parent&.children&.select(&:element?) || []
+      index = siblings.index(node)
+      case pseudo
+      when "first-child" then index == 0
+      when "last-child" then index == siblings.length - 1
+      when "only-child" then siblings.length == 1
+      when "root" then node.name == "html"
+      when "empty" then node.children.none? { |child| child.element? || (child.text? && !child.data.empty?) }
+      when "nth-child" then nth?(index.to_i + 1, value)
+      when "not" then !simple_match?(node, parse_simple(value.to_s))
+      else false
+      end
+    end
+
+    def nth?(index, expression)
+      value = expression.to_s.strip.downcase
+      return index == value.to_i if value.match?(/\A\d+\z/)
+      return index.odd? if value == "odd"
+      return index.even? if value == "even"
+      if (match = value.match(/\A([+-]?\d*)n(?:\s*([+-])\s*(\d+))?\z/))
+        coefficient = match[1].empty? || match[1] == "+" ? 1 : match[1] == "-" ? -1 : match[1].to_i
+        offset = match[3].to_i * (match[2] == "-" ? -1 : 1)
+        return (index - offset) * coefficient >= 0 && (index - offset) % coefficient.zero?
+      end
+      false
+    end
+  end
+end

data/lib/jabbah/version.rb

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

data/lib/jabbah.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+require_relative "jabbah/version"
+require_relative "jabbah/node"
+require_relative "jabbah/document"
+require_relative "jabbah/parser"
+require_relative "jabbah/selector"
+require_relative "jabbah/sanitize"
+require_relative "jabbah/extract"
+
+module Jabbah
+  class Error < StandardError; end
+
+  def self.parse(input, encoding: :auto)
+    Document.parse(input, encoding: encoding)
+  end
+
+  def self.fragment(input, context: "div")
+    Document.fragment(input, context: context)
+  end
+end

data/sig/jabbah.rbs

@@ -0,0 +1,62 @@
+module Jabbah
+  VERSION: String
+  def self.parse: (String input, ?encoding: Symbol | String) -> Document
+  def self.fragment: (String input, ?context: String) -> Document
+
+  class Error < StandardError
+  end
+
+  class Node
+    attr_accessor parent: Node?
+    attr_reader type: Symbol
+    attr_reader name: String?
+    attr_reader attributes: Hash[String, String?]
+    attr_reader children: Array[Node]
+    attr_reader data: String?
+    def initialize: (Symbol type, ?name: String?, ?attributes: Hash[String, String?], ?data: String?) -> void
+    def element?: () -> bool
+    def text?: () -> bool
+    def comment?: () -> bool
+    def document?: () -> bool
+    def []: (String | Symbol key) -> untyped
+    def []=: (String | Symbol key, String? value) -> untyped
+    def add_child: (Node child) -> Node
+    def remove: () -> Node
+    def each: () { (Node) -> void } -> Array[Node]
+    def ancestors: () -> Array[Node]
+    def descendants: () -> Enumerator[Node, void]
+    def at: (String selector) -> Node?
+    def search: (String selector) -> Array[Node]
+    def text: () -> String
+    def clone: () -> Node
+    def to_html: (?indent: String?) -> String
+  end
+
+  class Document
+    attr_reader encoding: Encoding
+    attr_reader blocked_count: Integer
+    def self.parse: (String input, ?encoding: Symbol | String) -> Document
+    def self.fragment: (String input, ?context: String) -> Document
+    def root: () -> Node
+    def head: () -> Node?
+    def body: () -> Node?
+    def title: () -> String?
+    def doctype: () -> String?
+    def text: () -> String
+    def at: (String selector) -> Node?
+    def search: (String selector) -> Array[Node]
+    def each: () { (Node) -> void } -> Array[Node]
+    def to_html: (?indent: String?) -> String
+    def clone: () -> Document
+  end
+
+  module Sanitize
+    DEFAULT: Hash[Symbol, bool]
+    PROFILES: Hash[Symbol, Hash[Symbol, bool]]
+    def self.clean: (Document | String document, ?profile: Symbol | Hash[Symbol, bool], ?allow: Hash[Symbol, bool], ?base_url: String?, ?on_blocked: Proc) -> Document
+  end
+
+  module Extract
+    def self.article: (Document | String document) -> Hash[Symbol, untyped]?
+  end
+end

metadata

@@ -0,0 +1,59 @@
+--- !ruby/object:Gem::Specification
+name: jabbah
+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: Jabbah parses malformed HTML into a traversable tree, supports selectors
+  and serialization, and provides sanitization and article extraction.
+email:
+- t.yudai92@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- docs/adr/001-tree-and-serialization.md
+- lib/jabbah.rb
+- lib/jabbah/document.rb
+- lib/jabbah/extract.rb
+- lib/jabbah/node.rb
+- lib/jabbah/parser.rb
+- lib/jabbah/sanitize.rb
+- lib/jabbah/selector.rb
+- lib/jabbah/version.rb
+- sig/jabbah.rbs
+homepage: https://github.com/noxdea/jabbah
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org
+  homepage_uri: https://github.com/noxdea/jabbah
+  source_code_uri: https://github.com/noxdea/jabbah/tree/main
+  changelog_uri: https://github.com/noxdea/jabbah/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.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.16
+specification_version: 4
+summary: A tolerant, secure, dependency-free Ruby HTML parser
+test_files: []