indexmap 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 52c07631052b8a72f3745d578239e22f97d047a517d7e1f9bdd8172a98cef453
-  data.tar.gz: 6ee1835d41386d143dbea600f81e48eff7d147ddd29ad806797195ff8eb3b0e1
+  metadata.gz: 7a655a2fa64beda7c2724d6fb4f283a13a5baf47519863c489e982efa86f2c32
+  data.tar.gz: 42dac8a1312d05bba81df9534bba52eaa69d55c236688473757252a1038dae06
 SHA512:
-  metadata.gz: 6b66319af63650f80ac5139cc0502cac097ec93d9d0613f0d856db1b695aa7c6b28a7f0d525eb0513bbd2b5989becae575baf00933fcfcf2b4cceec9388a054b
-  data.tar.gz: 01130bad021a01134530cbcd1e389e1d25c69637d40fa8f31b4023fbf4015b4caaf79c55895936e76cb54e493495aa35d75a7b86d3a5b77f452b7ba945d37059
+  metadata.gz: d0615154aef9cf51613b73c46f834efb16c53b77dfb3611f8f980a8ae5c1e8eedaa653ca84ca5610a27b58377717e7c3acbd0fc1cdb162df90fd84d660912ed6
+  data.tar.gz: 796aeed197f26684ebbd74bb7b47d37c878fea855c02c4ec0636cd7ce28c44f32fb73a3c2a911955d194d175c8c80ce351c8b2f955e03707543a88e4ab740763

data/CHANGELOG.md

@@ -5,9 +5,12 @@ 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.3.0] - 2026-04-22
+## [0.4.0] - 2026-04-22
+
+
+### Documentation
+
+- improve the task messages (#4)
 
-### <!-- 0 -->🚀 Features
-- expand indexmap with sitemap parsing, validation, and search engine pinging
 
 

data/README.md

@@ -3,7 +3,7 @@
 [![Gem Version](https://badge.fury.io/rb/indexmap.svg)](https://badge.fury.io/rb/indexmap)
 [![Ruby](https://github.com/ethos-link/indexmap/actions/workflows/ruby.yml/badge.svg)](https://github.com/ethos-link/indexmap/actions/workflows/ruby.yml)
 
-`indexmap` is a small Ruby gem for generating XML sitemap indexes and child sitemaps from explicit section definitions.
+`indexmap` is a small Ruby gem for generating XML sitemaps from explicit Ruby data.
 
 It is designed for Rails apps that want:
 
@@ -12,7 +12,7 @@ It is designed for Rails apps that want:
 - first-party rake tasks instead of a large DSL
 - easy extraction of sitemap logic into app-owned manifests
 
-The default output mode is a sitemap index plus one or more child sitemap files. For simpler sites, `indexmap` also supports an explicit single-file mode that writes a single `urlset` directly to `sitemap.xml`.
+By default, `indexmap` writes a sitemap index plus one or more child sitemap files. For simpler sites, it also supports `:single_file` mode, which writes a single `urlset` directly to `sitemap.xml`.
 
 ## Installation
 
@@ -34,7 +34,7 @@ Or install it directly:
 gem install indexmap
 ```
 
-## Ruby usage
+## Ruby Usage
 
 ```ruby
 require "indexmap"
@@ -56,7 +56,7 @@ Indexmap::Writer.new(
 ).write
 ```
 
-## Rails configuration
+## Rails Usage
 
 In an initializer:
 
@@ -77,14 +77,24 @@ Indexmap.configure do |config|
 end
 ```
 
-This enables:
+Then run:
 
 ```bash
 bin/rails sitemap:create
 bin/rails sitemap:format
+bin/rails sitemap:validate
 ```
 
-### Single-file mode
+`sitemap:create` is the main task. It writes sitemap files, formats them, and validates the result.
+
+### Default Index Mode
+
+This is the default behavior. `indexmap` writes:
+
+- `public/sitemap.xml` as a sitemap index
+- one or more child sitemap files from `config.sections`
+
+### Single-File Mode
 
 For sites that only want one `public/sitemap.xml` file:
 
@@ -102,9 +112,9 @@ Indexmap.configure do |config|
 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`.
+In `:single_file` mode, `indexmap` writes a `urlset` directly to `sitemap.xml` and reads entries from `config.entries` instead of `config.sections`.
 
-## Validation and Parsing
+## Validation And Parsing
 
 `indexmap` also includes small utilities for working with generated sitemap files:
 
@@ -124,27 +134,72 @@ The built-in validator checks for:
 
 ## Search Engine Ping
 
-The gem can ping Google Search Console and IndexNow once your app config provides the required credentials.
+`indexmap` can ping Google Search Console and IndexNow after sitemap generation.
+
+Available rake tasks:
+
+```bash
+bin/rails sitemap:validate
+bin/rails sitemap:google:ping
+bin/rails sitemap:index_now:ping
+bin/rails sitemap:index_now:write_key
+bin/rails sitemap:ping
+```
+
+### Google Search Console
+
+Google pinging requires service account credentials:
+
+```ruby
+Indexmap.configure do |config|
+  config.google.credentials = -> { ENV["GOOGLE_SITEMAP"] }
+end
+```
+
+If `config.google.credentials` is blank, `sitemap:google:ping` skips Google submission.
+
+You can optionally override the Search Console property identifier:
 
 ```ruby
 Indexmap.configure do |config|
   config.google.credentials = -> { ENV["GOOGLE_SITEMAP"] }
+  config.google.property = -> { "sc-domain:example.com" }
+end
+```
+
+If `config.google.property` is not set, `indexmap` defaults to `sc-domain:<host>`.
+
+### IndexNow
+
+IndexNow submission requires a key. `indexmap` supports two ways to provide it:
+
+- set `config.index_now.key`
+- or keep a valid verification file at `public/<key>.txt`
+
+Configured-key example:
+
+```ruby
+Indexmap.configure do |config|
   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.
+If `config.index_now.key` is set, `sitemap:create` also writes the matching `public/<key>.txt` verification file automatically.
 
-Available rake tasks:
+If you prefer the file-based flow, run:
 
 ```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
 ```
 
+That task:
+
+- reuses an existing valid key file when present
+- otherwise generates a new key in `public/<key>.txt`
+- makes that key available to `sitemap:index_now:ping` without adding `config.index_now.key`
+
+If neither a configured key nor a valid key file is present, `sitemap:index_now:ping` skips IndexNow submission.
+
 ## Development
 
 Run tests:
@@ -165,6 +220,8 @@ Run the full default task:
 bundle exec rake
 ```
 
+Tests generate a coverage report automatically.
+
 Note: `Gemfile.lock` is intentionally not tracked for this gem, following normal Ruby library conventions.
 
 ### Git hooks

data/lib/indexmap/index_now_configuration.rb

@@ -13,16 +13,17 @@ module Indexmap
     end
 
     def endpoint
-      resolve(@endpoint).presence || DEFAULT_ENDPOINT
+      value = resolve(@endpoint)
+      value.to_s.strip.empty? ? DEFAULT_ENDPOINT : value
     end
 
     def key
       resolve(@key)
     end
 
-    def key_path(public_path:)
+    def key_path(public_path:, key: self.key)
       configured_path = resolve(@key_path)
-      return Pathname(configured_path) if configured_path.present?
+      return Pathname(configured_path) unless configured_path.to_s.strip.empty?
       return if key.to_s.strip.empty?
 
       Pathname(public_path).join("#{key}.txt")

data/lib/indexmap/path.rb

@@ -26,7 +26,8 @@ module Indexmap
     end
 
     def default_index_filename
-      Indexmap.configuration.index_filename.presence || INDEX_FILENAME
+      configured = Indexmap.configuration.index_filename
+      configured.to_s.strip.empty? ? INDEX_FILENAME : configured
     rescue
       INDEX_FILENAME
     end

data/lib/indexmap/pinger/base.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-require "active_support/tagged_logging"
+require "logger"
 require "uri"
 
 module Indexmap
@@ -24,7 +24,9 @@ module Indexmap
         @logger ||= if defined?(Rails) && Rails.respond_to?(:logger) && Rails.logger
           Rails.logger
         else
-          ActiveSupport::TaggedLogging.new(Logger.new($stdout))
+          Logger.new($stderr).tap do |logger|
+            logger.level = Logger::WARN
+          end
         end
       end
 

data/lib/indexmap/pinger/google.rb

@@ -50,7 +50,8 @@ module Indexmap
       end
 
       def property_identifier
-        google_configuration.property.presence || "sc-domain:#{root_domain}"
+        property = google_configuration.property
+        property.to_s.strip.empty? ? "sc-domain:#{root_domain}" : property
       end
 
       def webmasters_service

data/lib/indexmap/pinger/index_now.rb

@@ -2,6 +2,7 @@
 
 require "faraday"
 require "json"
+require "securerandom"
 require "time"
 
 module Indexmap
@@ -37,16 +38,26 @@ module Indexmap
         end
       end
 
-      def write_key_file
-        key = index_now_configuration.key.to_s.strip
+      def write_key_file(key: index_now_configuration.key, path: nil)
+        key = key.to_s.strip
         return if key.empty?
 
-        path = index_now_configuration.key_path(public_path: configuration.public_path)
+        path ||= index_now_configuration.key_path(public_path: configuration.public_path, key: key)
         FileUtils.mkdir_p(path.dirname)
         File.write(path, "#{key}\n")
         path
       end
 
+      def ensure_key_file
+        configured_key = index_now_configuration.key.to_s.strip
+        return write_key_file(key: configured_key) unless configured_key.empty?
+
+        return existing_key_file if existing_key_file
+
+        key = generated_key
+        write_key_file(key: key, path: configuration.public_path.join("#{key}.txt"))
+      end
+
       private
 
       attr_reader :connection
@@ -158,15 +169,27 @@ module Indexmap
         configured_key = index_now_configuration.key.to_s.strip
         return configured_key unless configured_key.empty?
 
-        key_file = configuration.public_path.glob("*.txt").find do |file|
-          filename = file.basename(".txt").to_s
-          next unless filename.match?(/\A[a-zA-Z0-9-]{8,128}\z/)
+        existing_key_file&.read&.strip
+      end
 
-          File.read(file).strip == filename
-        end
-        return nil unless key_file
+      def existing_key_file
+        configured_path = index_now_configuration.key_path(public_path: configuration.public_path)
+        return configured_path if valid_key_file?(configured_path)
+
+        configuration.public_path.glob("*.txt").find { |file| valid_key_file?(file) }
+      end
+
+      def valid_key_file?(path)
+        return false unless path&.file?
+
+        filename = path.basename(".txt").to_s
+        return false unless filename.match?(/\A[a-zA-Z0-9-]{8,128}\z/)
+
+        path.read.strip == filename
+      end
 
-        File.read(key_file).strip
+      def generated_key
+        SecureRandom.uuid
       end
     end
   end

data/lib/indexmap/task_runner.rb

@@ -11,7 +11,7 @@ module Indexmap
     def create
       remove_existing_sitemap_files
       configuration.writer.write
-      write_index_now_key
+      {files: sitemap_files, index_now_key_path: write_index_now_key}
     end
 
     def format
@@ -27,28 +27,38 @@ module Indexmap
 
         File.write(file_path, document.to_xml(indent: 2, save_with: save_options))
       end
+
+      sitemap_files
     end
 
     def validate
       Validator.new(configuration: configuration).validate!
+      sitemap_files
     end
 
-    def write_index_now_key
-      Pinger::IndexNow.new(configuration: configuration).write_key_file
+    def write_index_now_key(generate_if_missing: false)
+      pinger = Pinger::IndexNow.new(configuration: configuration)
+      return pinger.ensure_key_file if generate_if_missing
+
+      pinger.write_key_file
+    end
+
+    def public_path
+      configuration.public_path
     end
 
     private
 
     attr_reader :configuration
 
-    def sitemap_files
-      Dir.glob(configuration.public_path.join("sitemap*.xml"))
-    end
-
     def remove_existing_sitemap_files
       Dir.glob(configuration.public_path.join("sitemap*.xml*")).each do |file_path|
         File.delete(file_path)
       end
     end
+
+    def sitemap_files
+      Dir.glob(configuration.public_path.join("sitemap*.xml")).sort
+    end
   end
 end

data/lib/indexmap/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Indexmap
-  VERSION = "0.3.0"
+  VERSION = "0.4.0"
 end

data/lib/tasks/indexmap_tasks.rake

@@ -2,19 +2,28 @@ namespace :sitemap do
   desc "Create sitemap files"
   task create: :environment do
     runner = Indexmap::TaskRunner.new
-    runner.create
+    create_result = runner.create
     runner.format
-    runner.validate
+    validated_files = runner.validate
+
+    puts "Created, formatted, and validated #{file_count(validated_files)} in #{public_directory(runner)}."
+    puts "IndexNow key file: #{create_result[:index_now_key_path]}" if create_result[:index_now_key_path]
   end
 
   desc "Format sitemap files for better readability"
   task format: :environment do
-    Indexmap::TaskRunner.new.format
+    runner = Indexmap::TaskRunner.new
+    formatted_files = runner.format
+
+    puts "Formatted #{file_count(formatted_files)} in #{public_directory(runner)}."
   end
 
   desc "Validate sitemap shape and URL hygiene"
   task validate: :environment do
-    Indexmap::TaskRunner.new.validate
+    runner = Indexmap::TaskRunner.new
+    validated_files = runner.validate
+
+    puts "Validated #{file_count(validated_files)} for sitemap shape and URL hygiene."
   end
 
   desc "Ping all configured search engines"
@@ -36,10 +45,23 @@ namespace :sitemap do
       Indexmap::Pinger::IndexNow.new.ping
     end
 
-    desc "Write the IndexNow key file into public/"
+    desc "Ensure the IndexNow key file exists in public/"
     task write_key: :environment do
-      path = Indexmap::TaskRunner.new.write_index_now_key
-      puts "Wrote #{path}" if path
+      path = Indexmap::TaskRunner.new.write_index_now_key(generate_if_missing: true)
+      if path
+        puts "IndexNow key file available at #{path}."
+      else
+        puts "IndexNow key is not configured; skipped key file write."
+      end
     end
   end
+
+  def file_count(files)
+    count = Array(files).size
+    "#{count} sitemap #{(count == 1) ? "file" : "files"}"
+  end
+
+  def public_directory(runner)
+    runner.public_path
+  end
 end

data/test/indexmap/pinger/index_now_test.rb

@@ -17,6 +17,46 @@ class IndexmapPingerIndexNowTest < Minitest::Test
     end
   end
 
+  def test_ensure_key_file_generates_a_key_when_configuration_is_missing
+    Dir.mktmpdir do |dir|
+      configuration = Indexmap::Configuration.new
+      configuration.base_url = "https://www.example.com"
+      configuration.public_path = Pathname(dir)
+
+      path = Indexmap::Pinger::IndexNow.new(configuration: configuration).ensure_key_file
+
+      assert_match(/\A[a-z0-9-]{8,128}\.txt\z/, path.basename.to_s)
+      assert_equal "#{path.basename(".txt")}\n", path.read
+    end
+  end
+
+  def test_pings_using_existing_key_file_when_key_is_not_configured
+    Dir.mktmpdir do |dir|
+      public_path = Pathname(dir)
+      key_path = public_path.join("test-key-123.txt")
+      key_path.write("test-key-123\n")
+      write_sitemap_files(
+        public_path,
+        marketing_lastmod: "2026-04-18T00:00:00Z",
+        insights_lastmod: "2026-04-10T00:00:00Z"
+      )
+
+      configuration = Indexmap::Configuration.new
+      configuration.base_url = "https://www.example.com"
+      configuration.public_path = public_path
+
+      indexnow_url = "https://api.indexnow.org/indexnow"
+      stub_request(:post, indexnow_url).to_return(status: 200, body: "", headers: {})
+
+      Indexmap::Pinger::IndexNow.new(configuration: configuration).ping
+
+      assert_requested(:post, indexnow_url, times: 1) do |request|
+        payload = JSON.parse(request.body)
+        assert_equal "test-key-123", payload.fetch("key")
+      end
+    end
+  end
+
   def test_pings_all_sitemap_urls_when_no_cutoff_is_provided
     Dir.mktmpdir do |dir|
       public_path = Pathname(dir)

data/test/indexmap/task_runner_test.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+require "test_helper"
+
+class IndexmapTaskRunnerTest < Minitest::Test
+  def test_create_removes_existing_sitemap_files_writes_new_sitemap_and_key_file
+    Dir.mktmpdir do |dir|
+      public_path = Pathname(dir)
+      public_path.join("sitemap.xml").write("old")
+      public_path.join("sitemap-pages.xml.gz").write("old")
+
+      configuration = Indexmap::Configuration.new
+      configuration.base_url = "https://example.com"
+      configuration.public_path = public_path
+      configuration.sections = [
+        Indexmap::Section.new(
+          filename: "sitemap-pages.xml",
+          entries: [Indexmap::Entry.new(loc: "https://example.com/about")]
+        )
+      ]
+      configuration.index_now.key = "test-key"
+
+      result = Indexmap::TaskRunner.new(configuration: configuration).create
+
+      assert_equal false, public_path.join("sitemap-pages.xml.gz").exist?
+      assert_includes public_path.join("sitemap.xml").read, "<sitemapindex"
+      assert_equal "test-key\n", public_path.join("test-key.txt").read
+      assert_equal [public_path.join("sitemap-pages.xml").to_s, public_path.join("sitemap.xml").to_s], result[:files]
+      assert_equal public_path.join("test-key.txt"), result[:index_now_key_path]
+    end
+  end
+
+  def test_write_index_now_key_returns_nil_when_key_is_not_configured
+    Dir.mktmpdir do |dir|
+      configuration = Indexmap::Configuration.new
+      configuration.base_url = "https://example.com"
+      configuration.public_path = Pathname(dir)
+      configuration.sections = [
+        Indexmap::Section.new(
+          filename: "sitemap-pages.xml",
+          entries: [Indexmap::Entry.new(loc: "https://example.com/about")]
+        )
+      ]
+
+      result = Indexmap::TaskRunner.new(configuration: configuration).write_index_now_key
+
+      assert_nil result
+    end
+  end
+
+  def test_write_index_now_key_can_generate_a_key_when_requested
+    Dir.mktmpdir do |dir|
+      configuration = Indexmap::Configuration.new
+      configuration.base_url = "https://example.com"
+      configuration.public_path = Pathname(dir)
+
+      result = Indexmap::TaskRunner.new(configuration: configuration).write_index_now_key(generate_if_missing: true)
+
+      assert_match(/\A[a-z0-9-]{8,128}\.txt\z/, result.basename.to_s)
+      assert_equal "#{result.basename(".txt")}\n", result.read
+    end
+  end
+end

data/test/indexmap/validator_test.rb

@@ -3,6 +3,18 @@
 require "test_helper"
 
 class IndexmapValidatorTest < Minitest::Test
+  def test_validate_raises_for_missing_sitemap
+    Dir.mktmpdir do |directory|
+      path = Pathname(directory).join("missing.xml")
+
+      error = assert_raises(Indexmap::ValidationError) do
+        Indexmap::Validator.new(path: path).validate!
+      end
+
+      assert_equal "Missing sitemap file: #{path}", error.message
+    end
+  end
+
   def test_validate_raises_for_duplicate_urls
     Dir.mktmpdir do |directory|
       path = Pathname(directory).join("sitemap.xml")

data/test/test_helper.rb

@@ -2,6 +2,13 @@
 
 $LOAD_PATH.unshift File.expand_path("../lib", __dir__)
 
+require "simplecov"
+
+SimpleCov.start do
+  enable_coverage :branch
+  add_filter "/test/"
+end
+
 require "minitest/autorun"
 require "tmpdir"
 require "date"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: indexmap
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.4.0
 platform: ruby
 authors:
 - Paulo Fidalgo
@@ -122,6 +122,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: simplecov
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.22'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.22'
 - !ruby/object:Gem::Dependency
   name: standard
   requirement: !ruby/object:Gem::Requirement
@@ -183,6 +197,7 @@ files:
 - test/indexmap/path_test.rb
 - test/indexmap/pinger/google_test.rb
 - test/indexmap/pinger/index_now_test.rb
+- test/indexmap/task_runner_test.rb
 - test/indexmap/validator_test.rb
 - test/indexmap/writer_test.rb
 - test/test_helper.rb