indexmap 0.2.1 → 0.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c3d316abdab0a6a55f613b44a0481bdf98d7d041d3d5b60b8523524450494333
-  data.tar.gz: a18dd5ad2e6db70ecef78719d8bae1a6d249fd393fe7dc363a8862fedd2faede
+  metadata.gz: ecbb344925e56757c840a508365932942f0344ce8fa38af6c3677e6eb6ec9bf3
+  data.tar.gz: 3facac318f7fb6553f672afc516910b176294b951d85ac61149cd665e00ded8f
 SHA512:
-  metadata.gz: 8dfd199b1b978991b703870f4eb08091b8ce4689156840b7f30a985f951d55d163dce89ba71d7d8d4645931b2cb6980a4134f9b593bd8bde3b97cf272fdfbe4c
-  data.tar.gz: 875b0e45a6d3ad629f03456f62b8311f6379f3d8cde8a308ec66e6bf5233cb122a34d39531d7a245b5b7e3a3e2bc051ee7fd16d5f2981fb5e5eb6b600ef01fa8
+  metadata.gz: 57f1ef28f1339a5cd7afa18f01518a520463eea63087363e765467ffe57f7835b3464345e8a792450c7245c89dedb8338a14771261d99aa06da562ed50ca5e1c
+  data.tar.gz: 513b73b694d00775765fd8a7e86d52a4a77971cc67fee2b4bd6ca6c675a5ab1c2e5ecca4ef9e8bc77ca7ff2f55784640d0b58734f180e757b650d2ecf1e04b63

data/CHANGELOG.md

@@ -5,9 +5,14 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [0.2.1] - 2026-04-21
+## [0.3.1] - 2026-04-22
+
+
+### Fixed
+
+- fix changelog generation (#2)
+
+- harden indexmap runtime defaults and test coverage (#3)
 
-### <!-- 1 -->🐛 Bug Fixes
-- publish built gem in release workflow
 
 

data/README.md

@@ -104,6 +104,47 @@ end
 
 In `:single_file` mode, `indexmap` writes a `urlset` directly to `sitemap.xml`. In the default `:index` mode, it writes a sitemap index plus child sitemap files from `sections`.
 
+## Validation and Parsing
+
+`indexmap` also includes small utilities for working with generated sitemap files:
+
+```ruby
+parser = Indexmap::Parser.new(path: Rails.public_path.join("sitemap.xml"))
+parser.paths
+# => ["/", "/about", "/articles/example"]
+
+Indexmap::Validator.new.validate!
+```
+
+The built-in validator checks for:
+
+- missing sitemap files
+- duplicate sitemap URLs
+- parameterized URLs in sitemap entries
+
+## Search Engine Ping
+
+The gem can ping Google Search Console and IndexNow once your app config provides the required credentials.
+
+```ruby
+Indexmap.configure do |config|
+  config.google.credentials = -> { ENV["GOOGLE_SITEMAP"] }
+  config.index_now.key = -> { ENV["INDEXNOW_KEY"] }
+end
+```
+
+When `config.index_now.key` is set, `sitemap:create` also writes the matching `public/<key>.txt` verification file automatically.
+
+Available rake tasks:
+
+```bash
+bin/rails sitemap:validate
+bin/rails sitemap:google:ping
+bin/rails sitemap:index_now:ping
+bin/rails sitemap:ping
+bin/rails sitemap:index_now:write_key
+```
+
 ## Development
 
 Run tests:
@@ -124,6 +165,12 @@ Run the full default task:
 bundle exec rake
 ```
 
+Tests generate a coverage report automatically. You can run either:
+
+```bash
+bundle exec rake test
+```
+
 Note: `Gemfile.lock` is intentionally not tracked for this gem, following normal Ruby library conventions.
 
 ### Git hooks

data/lib/indexmap/configuration.rb

@@ -24,10 +24,18 @@ module Indexmap
       value.nil? ? :index : value.to_sym
     end
 
+    def google
+      @google ||= GoogleConfiguration.new
+    end
+
     def index_filename
       resolve(@index_filename)
     end
 
+    def index_now
+      @index_now ||= IndexNowConfiguration.new
+    end
+
     def public_path
       value = resolve(@public_path)
       return Pathname("public") if value.nil?

data/lib/indexmap/google_configuration.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Indexmap
+  class GoogleConfiguration
+    attr_writer :credentials, :property
+
+    def credentials
+      resolve(@credentials)
+    end
+
+    def property
+      resolve(@property)
+    end
+
+    private
+
+    def resolve(value)
+      value.respond_to?(:call) ? value.call : value
+    end
+  end
+end

data/lib/indexmap/index_now_configuration.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module Indexmap
+  class IndexNowConfiguration
+    DEFAULT_ENDPOINT = "https://api.indexnow.org"
+    DEFAULT_MAX_URLS_PER_REQUEST = 500
+
+    attr_writer :dry_run, :endpoint, :key, :key_path, :max_urls_per_request
+
+    def dry_run?
+      value = resolve(@dry_run)
+      value == true || value.to_s == "1"
+    end
+
+    def endpoint
+      value = resolve(@endpoint)
+      value.to_s.strip.empty? ? DEFAULT_ENDPOINT : value
+    end
+
+    def key
+      resolve(@key)
+    end
+
+    def key_path(public_path:)
+      configured_path = resolve(@key_path)
+      return Pathname(configured_path) unless configured_path.to_s.strip.empty?
+      return if key.to_s.strip.empty?
+
+      Pathname(public_path).join("#{key}.txt")
+    end
+
+    def max_urls_per_request
+      value = resolve(@max_urls_per_request)
+      return DEFAULT_MAX_URLS_PER_REQUEST if value.nil?
+
+      value.to_i
+    end
+
+    private
+
+    def resolve(value)
+      value.respond_to?(:call) ? value.call : value
+    end
+  end
+end

data/lib/indexmap/parser.rb

@@ -0,0 +1,202 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "nokogiri"
+require "pathname"
+require "uri"
+
+module Indexmap
+  class Parser
+    Entry = Struct.new(:loc, :lastmod, :source_sitemap, keyword_init: true)
+
+    def initialize(path: default_path, rebase_remote_children: false, index_filename: Indexmap.configuration.index_filename, public_path: Indexmap.configuration.public_path)
+      @source = path.to_s
+      @rebase_remote_children = rebase_remote_children
+      @index_filename = index_filename
+      @public_path = public_path
+    end
+
+    def entries(reset: false)
+      return reset! && entries if reset
+      return @entries if defined?(@entries)
+
+      visited = Set.new
+      @entries = parse_source(@source, visited: visited)
+    end
+
+    def paths(reset: false)
+      return reset! && paths if reset
+      return @paths if defined?(@paths)
+
+      seen = Set.new
+      @paths = entries.map do |entry|
+        path = extract_path(entry.loc)
+        next if path.nil?
+
+        normalized = normalize_path(path)
+        next if seen.include?(normalized)
+
+        seen.add(normalized)
+        normalized
+      end.compact
+    end
+
+    def urls(base_url:, reset: false)
+      return reset! && urls(base_url: base_url) if reset
+
+      target = URI.parse(base_url)
+      port_suffix = (target.port && ![80, 443].include?(target.port)) ? ":#{target.port}" : ""
+
+      paths.map do |path|
+        "#{target.scheme}://#{target.host}#{port_suffix}#{path}"
+      end
+    end
+
+    def reset!
+      remove_instance_variable(:@entries) if defined?(@entries)
+      remove_instance_variable(:@paths) if defined?(@paths)
+    end
+
+    private
+
+    attr_reader :index_filename, :public_path
+
+    def default_path
+      Indexmap::Path.existing_public_path(public_path: public_path, index_filename: index_filename)
+    end
+
+    def parse_source(source, visited:)
+      normalized_source = normalize_source(source)
+      return [] if normalized_source.nil? || visited.include?(normalized_source)
+
+      visited.add(normalized_source)
+      xml = read_source(normalized_source)
+      return [] if xml.to_s.strip.empty?
+
+      document = Nokogiri::XML(xml)
+      document.remove_namespaces!
+
+      if document.at_xpath("/sitemapindex")
+        document.xpath("//sitemap/loc").flat_map do |node|
+          child_source = resolve_child_sitemap(normalized_source, node.text.to_s.strip)
+          next [] if child_source.nil?
+
+          parse_source(child_source, visited: visited)
+        end
+      else
+        document.xpath("//url").map do |url_node|
+          loc = url_node.at_xpath("loc")&.text.to_s.strip
+          next if loc.empty?
+
+          lastmod = url_node.at_xpath("lastmod")&.text.to_s.strip
+          Entry.new(loc: loc, lastmod: lastmod.empty? ? nil : lastmod, source_sitemap: normalized_source)
+        end.compact
+      end
+    end
+
+    def resolve_child_sitemap(parent_source, loc)
+      return if loc.empty?
+
+      if remote_source?(parent_source)
+        parent_uri = URI.parse(parent_source)
+        if remote_source?(loc)
+          remote_child_source(parent_uri, loc)
+        else
+          URI.join(parent_uri.to_s, loc).to_s
+        end
+      elsif remote_source?(loc)
+        uri = URI.parse(loc)
+        File.join(File.dirname(parent_source), File.basename(uri.path))
+      else
+        File.expand_path(loc, File.dirname(parent_source))
+      end
+    rescue URI::InvalidURIError
+      File.expand_path(loc, File.dirname(parent_source))
+    end
+
+    def remote_child_source(parent_uri, loc)
+      child_uri = URI.parse(loc)
+      return child_uri.to_s unless @rebase_remote_children
+      return child_uri.to_s if child_uri.host == parent_uri.host && child_uri.port == parent_uri.port && child_uri.scheme == parent_uri.scheme
+
+      child_uri.scheme = parent_uri.scheme
+      child_uri.host = parent_uri.host
+      child_uri.port = parent_uri.port
+      child_uri.to_s
+    end
+
+    def normalize_source(source)
+      return if source.to_s.strip.empty?
+
+      if remote_source?(source)
+        URI.parse(source).to_s
+      else
+        Pathname(source).expand_path.to_s
+      end
+    rescue URI::InvalidURIError
+      nil
+    end
+
+    def remote_source?(value)
+      uri = URI.parse(value.to_s)
+      uri.is_a?(URI::HTTP) || uri.is_a?(URI::HTTPS)
+    rescue URI::InvalidURIError
+      false
+    end
+
+    def read_source(source)
+      if remote_source?(source)
+        fetch_remote_source(source)
+      elsif File.exist?(source)
+        File.read(source, encoding: "UTF-8")
+      end
+    end
+
+    def fetch_remote_source(source, redirects_remaining: 3)
+      uri = URI.parse(source)
+      request = Net::HTTP::Get.new(uri)
+      request["User-Agent"] = "Indexmap::Parser/1.0"
+
+      response = Net::HTTP.start(uri.host, uri.port, use_ssl: uri.scheme == "https", open_timeout: 10, read_timeout: 20) do |http|
+        http.request(request)
+      end
+
+      case response
+      when Net::HTTPSuccess
+        response.body
+      when Net::HTTPRedirection
+        return if redirects_remaining <= 0
+
+        location = response["location"].to_s
+        return if location.empty?
+
+        redirected = URI.join(source, location).to_s
+        fetch_remote_source(redirected, redirects_remaining: redirects_remaining - 1)
+      end
+    rescue URI::InvalidURIError
+      nil
+    end
+
+    def extract_path(loc)
+      return if loc.to_s.strip.empty?
+
+      if loc.start_with?("http://", "https://")
+        path = URI.parse(loc).path
+        (path.nil? || path.empty?) ? "/" : path
+      elsif loc.start_with?("/")
+        loc
+      else
+        "/#{loc}"
+      end
+    rescue URI::InvalidURIError
+      nil
+    end
+
+    def normalize_path(path)
+      return "/" if path == "/"
+
+      normalized = path.start_with?("/") ? path : "/#{path}"
+      normalized.delete_suffix("/")
+    end
+  end
+end

data/lib/indexmap/path.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require "pathname"
+require "uri"
+
+module Indexmap
+  module Path
+    INDEX_FILENAME = "sitemap.xml"
+    LEGACY_FILENAME = "sitemap_index.xml"
+
+    module_function
+
+    def canonical_public_path(public_path: default_public_path_root, index_filename: default_index_filename)
+      Pathname(public_path).join(index_filename)
+    end
+
+    def existing_public_path(public_path: default_public_path_root, index_filename: default_index_filename, legacy_filename: LEGACY_FILENAME)
+      index_path = canonical_public_path(public_path: public_path, index_filename: index_filename)
+      return index_path if index_path.exist?
+
+      Pathname(public_path).join(legacy_filename)
+    end
+
+    def canonical_url(base_url, index_filename: default_index_filename)
+      URI.join(base_url, "/#{index_filename}").to_s
+    end
+
+    def default_index_filename
+      configured = Indexmap.configuration.index_filename
+      configured.to_s.strip.empty? ? INDEX_FILENAME : configured
+    rescue
+      INDEX_FILENAME
+    end
+
+    def default_public_path_root
+      if defined?(Rails)
+        Rails.public_path
+      else
+        Pathname("public")
+      end
+    end
+  end
+end

data/lib/indexmap/pinger/base.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+require "logger"
+require "uri"
+
+module Indexmap
+  module Pinger
+    class Base
+      def self.ping(...)
+        new(...).ping
+      end
+
+      def initialize(configuration: Indexmap.configuration)
+        @configuration = configuration
+      end
+
+      def ping
+        sitemap_files.each do |sitemap_file|
+          ping_sitemap(sitemap_file)
+        end
+      end
+
+      def logger
+        @logger ||= if defined?(Rails) && Rails.respond_to?(:logger) && Rails.logger
+          Rails.logger
+        else
+          Logger.new($stderr).tap do |logger|
+            logger.level = Logger::WARN
+          end
+        end
+      end
+
+      private
+
+      attr_reader :configuration
+
+      def host
+        configuration.base_url
+      end
+
+      def hostname
+        URI.parse(host).host
+      end
+
+      def root_domain
+        hostname.sub(/\Awww\./, "")
+      end
+
+      def sitemap_files
+        Dir.glob(configuration.public_path.join("sitemap*.xml")).sort
+      end
+
+      def ping_sitemap(_sitemap_file)
+        raise NotImplementedError
+      end
+    end
+  end
+end

data/lib/indexmap/pinger/google.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+require "google/apis/searchconsole_v1"
+require "googleauth"
+require "json"
+require "stringio"
+
+module Indexmap
+  module Pinger
+    class Google < Base
+      def initialize(configuration: Indexmap.configuration, service: nil, credentials_builder: nil)
+        super(configuration: configuration)
+        @service = service
+        @credentials_builder = credentials_builder
+      end
+
+      def ping
+        if google_configuration.credentials.to_s.strip.empty?
+          logger.debug("Google sitemap credentials not configured.")
+          return
+        end
+
+        super
+      end
+
+      private
+
+      attr_reader :credentials_builder
+
+      def google_configuration
+        configuration.google
+      end
+
+      def ping_sitemap(sitemap_file)
+        sitemap_url = URI.join(host, File.basename(sitemap_file)).to_s
+
+        unless authorized?
+          logger.error("Google Search Console does not have access to the site: #{root_domain}")
+          return
+        end
+
+        webmasters_service.submit_sitemap(property_identifier, sitemap_url)
+        logger.debug { "Successfully pinged Google with sitemap: #{sitemap_url}" }
+      rescue ::Google::Apis::ClientError => e
+        logger.debug { "Failed to ping Google for #{sitemap_url}. Status: #{e.status_code}, Body: #{e.body}" }
+      end
+
+      def authorized?
+        webmasters_service.list_sites.site_entry.any? { |site| site.site_url.include?(root_domain) }
+      end
+
+      def property_identifier
+        property = google_configuration.property
+        property.to_s.strip.empty? ? "sc-domain:#{root_domain}" : property
+      end
+
+      def webmasters_service
+        @webmasters_service ||= begin
+          service = @service || ::Google::Apis::SearchconsoleV1::SearchConsoleService.new
+          service.authorization = authorizer
+          service
+        end
+      end
+
+      def authorizer
+        json_key = JSON.parse(google_configuration.credentials).to_json
+        scope = "https://www.googleapis.com/auth/webmasters"
+
+        return credentials_builder.call(credentials: json_key, scope: scope) if credentials_builder
+
+        ::Google::Auth::ServiceAccountCredentials.make_creds(
+          json_key_io: StringIO.new(json_key),
+          scope: scope
+        )
+      end
+    end
+  end
+end