kettle-dev 2.5.18 → 2.5.19

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6ce9b09d7f7b63282d83f98a7599f0e3a1e2f4253c4f342c5a386220ad957a1d
-  data.tar.gz: 108a6343526873d70684091ae6fddb5b0663644b26a2428dfe89721f29767096
+  metadata.gz: a8ffb38694a14518e416b497413025d417137ce7b7cf8673dd31f68aa46c8539
+  data.tar.gz: 71d1ff523dc11ba20f72994792ad3edd4ff43a0ceea2c8c84e46e65b77e72977
 SHA512:
-  metadata.gz: dc871e4686bc80667419140219bd8655c64375b6d24d556d562275437876f9fefa71bbf6b3dac7fc0c332dd23bdbc4311333700b6b151c683e943424b0ca628d
-  data.tar.gz: 311013ce7d7751d9d7f6b8ac2ae165a73ea366711af9921ae70f6b2514c6689141f1ac06ab7481429f3e2dba3073b912fa4d9b94c48835a7b896c0e16e1d4c30
+  metadata.gz: a7cf27e978644578be5e2839670c4981343b9d84646d59ece70e4d83eb388404dcd52b77c3f90929164ff86f698bc6bfc93ecfa42f8bfc9a2ec342d764030aa3
+  data.tar.gz: 59de547a4f7a50905bed8bc66c8b919eca375ff9d4d31bd079371dfee717d540bf800477bae8dad644a2efe7935d7cb44b53e059cb4554a99c54d5655d372dc2

data/CHANGELOG.md

@@ -30,6 +30,23 @@ Please file a bug if you notice a violation of semantic versioning.
 
 ### Security
 
+## [2.5.19] - 2026-08-06
+
+- TAG: [v2.5.19][2.5.19t]
+- COVERAGE: 91.34% -- 5431/5946 lines in 47 files
+- BRANCH COVERAGE: 75.28% -- 2037/2706 branches in 47 files
+- 50.64% documented
+
+### Changed
+
+- Track the released kettle-gha-pins client and its cache/tag-resolution contract in the development lockfile and specs.
+
+### Fixed
+
+- Add release validation for Markdown reference labels and local heading anchors.
+
+- Restore the Discord badge reference in CONTRIBUTING.md.
+
 ## [2.5.18] - 2026-08-03
 
 - TAG: [v2.5.18][2.5.18t]
@@ -3242,7 +3259,9 @@ Please file a bug if you notice a violation of semantic versioning.
   - Selecting will run the selected workflow via `act`
   - This may move to its own gem in the future.
 
-[Unreleased]: https://github.com/kettle-dev/kettle-dev/compare/v2.5.18...HEAD
+[Unreleased]: https://github.com/kettle-dev/kettle-dev/compare/v2.5.19...HEAD
+[2.5.19]: https://github.com/kettle-dev/kettle-dev/compare/v2.5.18...v2.5.19
+[2.5.19t]: https://github.com/kettle-dev/kettle-dev/releases/tag/v2.5.19
 [2.5.18]: https://github.com/kettle-dev/kettle-dev/compare/v2.5.17...v2.5.18
 [2.5.18t]: https://github.com/kettle-dev/kettle-dev/releases/tag/v2.5.18
 [2.5.17]: https://github.com/kettle-dev/kettle-dev/compare/v2.5.16...v2.5.17

data/README.md

@@ -409,6 +409,8 @@ What it does:
 - Script: `exe/kettle-release` (run as `kettle-release`)
 - Purpose: guided release helper that:
     - Runs `kettle-pre-release` as step 0 on full releases, aborting before release setup if any pre-release gate fails.
+    - Validates Markdown reference definitions and local heading anchors across releasable documentation before network checks.
+      Markdown fixtures under `spec/` and `test/`, along with `tmp/`, are intentionally excluded.
     - Skips pre-release checks for any `start_step` greater than `0`, so resumptions begin directly at the requested numbered step.
     - Runs sanity checks (`bin/setup`, `bin/rake`), confirms version/changelog, optionally updates Appraisals, regenerates docs via `bin/rake yard`, commits “🔖 Prepare release vX.Y.Z”.
     - Optionally runs your CI locally with `act` before any push:
@@ -1005,7 +1007,7 @@ Thanks for RTFM. ☺️
 [📌gitmoji]: https://gitmoji.dev
 [📌gitmoji-img]: https://img.shields.io/badge/gitmoji_commits-%20%F0%9F%98%9C%20%F0%9F%98%8D-34495e.svg?style=flat-square
 [🧮kloc]: https://www.youtube.com/watch?v=dQw4w9WgXcQ
-[🧮kloc-img]: https://img.shields.io/badge/KLOC-5.788-FFDD67.svg?style=for-the-badge&logo=YouTube&logoColor=blue
+[🧮kloc-img]: https://img.shields.io/badge/KLOC-5.946-FFDD67.svg?style=for-the-badge&logo=YouTube&logoColor=blue
 [🔐security]: https://github.com/kettle-dev/kettle-dev/blob/main/SECURITY.md
 [🔐security-img]: https://img.shields.io/badge/security-policy-259D6C.svg?style=flat
 [📄copyright-notice-explainer]: https://opensource.stackexchange.com/questions/5778/why-do-licenses-such-as-the-mit-license-specify-a-single-year

data/lib/kettle/dev/markdown_reference_validator.rb

@@ -0,0 +1,254 @@
+# frozen_string_literal: true
+
+require "set"
+require "uri"
+
+module Kettle
+  module Dev
+    # Validates Markdown reference labels and local link destinations.
+    #
+    # This is intentionally a small source scanner rather than a second Markdown
+    # rendering pipeline. The release gate needs reference integrity and local
+    # anchor checks, while the existing Markdown merge/parser dependencies are
+    # not runtime dependencies of kettle-dev.
+    class MarkdownReferenceValidator
+      Issue = Struct.new(:path, :line, :message)
+      Report = Struct.new(:file_count, :reference_count, :local_target_count, :issues)
+
+      FENCE_RE = /\A\s*(`{3,}|~{3,})/.freeze
+      IGNORED_PATH_PREFIXES = %w[tmp/ .git/ spec/ test/].freeze
+      REFERENCE_DEFINITION_RE = /\A {0,3}\[([^\]]+)\]:\s*(?:<([^>]+)>|(\S+))/
+      REFERENCE_USAGE_RE = /!?\[([^\]]*)\]\[([^\]]*)\]/
+      INLINE_LINK_RE = /!?\[[^\]]*\]\((<[^>]+>|[^)]*)\)/
+      ATX_HEADING_RE = /\A {0,3}\#{1,6}\s+(.+?)\s*\#*\s*\z/
+      SETEXT_HEADING_RE = /\A {0,3}(=+|-+)\s*\z/
+
+      def initialize(root: Dir.pwd, files: nil)
+        @root = File.expand_path(root)
+        @files = (files || default_files).reject { |path| ignored_path?(path) }
+      end
+
+      def validate!
+        documents = @files.each_with_object({}) do |path, result|
+          absolute = absolute_path(path)
+          result[path] = parse_document(path, absolute) if File.file?(absolute)
+        end
+        report = build_report(documents)
+        return report if report.issues.empty?
+
+        warn("[kettle-pre-release] Markdown reference validation failed:")
+        report.issues.each do |issue|
+          warn("  - #{Kettle::Dev.display_path(issue.path)}:#{issue.line}: #{issue.message}")
+        end
+        raise Kettle::Dev::Error, "Markdown reference validation failed (#{report.issues.size} issue(s))"
+      end
+
+      private
+
+      def default_files
+        if defined?(Kettle::Dev::PreReleaseCLI::Markdown)
+          Kettle::Dev::PreReleaseCLI::Markdown.project_markdown_files.reject { |path| ignored_path?(path) }
+        else
+          Dir.glob(["**/*.md", "**/*.markdown", "**/*.md.example"]).reject { |path| ignored_path?(path) }.sort
+        end
+      end
+
+      def ignored_path?(path)
+        IGNORED_PATH_PREFIXES.any? { |prefix| path.to_s.start_with?(prefix) }
+      end
+
+      def absolute_path(path)
+        File.expand_path(path, @root)
+      end
+
+      def parse_document(path, absolute)
+        lines = File.readlines(absolute, chomp: true)
+        definitions = {}
+        usages = []
+        local_targets = []
+        headings = []
+        in_fence = false
+        fence_char = nil
+        fence_length = 0
+        previous_text = nil
+
+        lines.each_with_index do |line, index|
+          line_number = index + 1
+          fence = line.match(FENCE_RE)
+          if in_fence
+            if fence && fence[1][0] == fence_char && fence[1].length >= fence_length
+              in_fence = false
+            end
+            next
+          elsif fence
+            in_fence = true
+            fence_char = fence[1][0]
+            fence_length = fence[1].length
+            next
+          end
+
+          definition = line.match(REFERENCE_DEFINITION_RE)
+          if definition
+            label = normalize_label(definition[1])
+            target = definition[2] || definition[3]
+            definitions[label] ||= []
+            definitions[label] << [line_number, target]
+            local_targets << [line_number, target]
+            previous_text = nil
+            next
+          end
+
+          line.scan(REFERENCE_USAGE_RE) do |text, label|
+            resolved_label = label.empty? ? text : label
+            usages << [line_number, normalize_label(resolved_label)]
+          end
+          line.scan(INLINE_LINK_RE) do |destination|
+            target = destination[0]
+            target = target[1..-2] if target.start_with?("<") && target.end_with?(">")
+            target = target.split(/\s+/, 2).first
+            local_targets << [line_number, target] unless target.to_s.empty?
+          end
+
+          if line.match?(SETEXT_HEADING_RE) && previous_text
+            headings << [line_number - 1, previous_text]
+            previous_text = nil
+          else
+            heading = heading_for(line)
+            headings << heading if heading
+            previous_text = line.strip unless line.strip.empty?
+          end
+        end
+
+        {
+          path: path,
+          definitions: definitions,
+          usages: usages,
+          local_targets: local_targets,
+          headings: heading_slugs(headings)
+        }
+      rescue Errno::EACCES, Errno::ENOENT => error
+        {
+          path: path,
+          definitions: {},
+          usages: [],
+          local_targets: [],
+          headings: [],
+          read_error: error
+        }
+      end
+
+      def build_report(documents)
+        issues = []
+        reference_count = 0
+        local_target_count = 0
+        heading_cache = {}
+
+        documents.each_value do |document|
+          if document[:read_error]
+            issues << Issue.new(document[:path], 1, "could not read Markdown file: #{document[:read_error].message}")
+            next
+          end
+
+          document[:definitions].each do |label, definitions|
+            if definitions.length > 1
+              definitions.drop(1).each do |line_number, _target|
+                issues << Issue.new(document[:path], line_number, "duplicate reference definition #{label.inspect}")
+              end
+            end
+          end
+
+          document[:usages].each do |line_number, label|
+            next if label.include?("<") || label.include?(">")
+
+            reference_count += 1
+            next if document[:definitions].key?(label)
+
+            issues << Issue.new(document[:path], line_number, "undefined Markdown reference #{label.inspect}")
+          end
+
+          document[:local_targets].each do |line_number, target|
+            destination = local_destination(target)
+            next unless destination
+
+            local_target_count += 1
+            target_path, fragment = destination
+            target_document = target_path.empty? ? document : documents_for_path(documents, document[:path], target_path)
+            if target_document.nil?
+              issues << Issue.new(document[:path], line_number, "local Markdown target does not exist: #{target_path.inspect}")
+              next
+            end
+            next if fragment.empty?
+
+            slugs = heading_cache[target_document[:path]] ||= target_document[:headings]
+            next if slugs.include?(fragment)
+
+            issues << Issue.new(document[:path], line_number, "local heading target does not exist: ##{fragment}")
+          end
+        end
+
+        Report.new(documents.size, reference_count, local_target_count, issues)
+      end
+
+      def documents_for_path(documents, source_path, target_path)
+        candidate = File.expand_path(target_path, File.dirname(absolute_path(source_path)))
+        documents.values.find { |document| absolute_path(document[:path]) == candidate }
+      end
+
+      def local_destination(target)
+        value = target.to_s.strip
+        return nil if value.empty? || value.start_with?("//")
+
+        uri = URI.parse(value)
+        return nil if uri.scheme || uri.host
+        path = unescape(uri.path.to_s)
+        fragment = unescape(uri.fragment.to_s).downcase
+        return nil if fragment.empty?
+        return nil unless path.empty? || markdown_path?(path)
+
+        [path, fragment]
+      rescue URI::InvalidURIError
+        nil
+      end
+
+      def unescape(value)
+        parser = defined?(URI::RFC2396_PARSER) ? URI::RFC2396_PARSER : URI::DEFAULT_PARSER
+        parser.unescape(value)
+      end
+
+      def markdown_path?(path)
+        path.downcase.end_with?(".md", ".markdown", ".md.example")
+      end
+
+      def normalize_label(label)
+        label.to_s.downcase.gsub(/\s+/, " ").strip
+      end
+
+      def heading_for(line)
+        match = line.match(ATX_HEADING_RE)
+        match ? [line[/\A\s*/].to_s.length + 1, match[1]] : nil
+      end
+
+      def heading_slugs(headings)
+        counts = Hash.new(0)
+        headings.each_with_object(Set.new) do |(_line, text), slugs|
+          slug = slugify(text)
+          next if slug.empty?
+
+          suffix = counts[slug]
+          counts[slug] += 1
+          slugs.add(suffix.zero? ? slug : "#{slug}-#{suffix}")
+        end
+      end
+
+      def slugify(text)
+        text.to_s.gsub(/<[^>]+>/, "").downcase
+          .gsub(/[*_~`]/, "")
+          .gsub(/[^\p{Alnum}\s-]/u, "")
+          .gsub(/\s+/, "-")
+          .squeeze("-")
+          .sub(/\A-/, "")
+          .sub(/-\z/, "")
+      end
+    end
+  end
+end

data/lib/kettle/dev/pre_release_cli.rb

@@ -11,6 +11,7 @@ require "net/http"
 require "openssl"
 require "time"
 require_relative "cache_progress"
+require_relative "markdown_reference_validator"
 require "kettle/ndjson"
 begin
   require "addressable/uri"
@@ -24,7 +25,8 @@ module Kettle
     # Checks:
     #   1) Ensure GitHub Actions workflow actions are pinned to current SHAs.
     #   2) Normalize Markdown image URLs using Addressable normalization.
-    #   3) Validate Markdown image links resolve via cached HTTP(S) HEAD/GET.
+    #   3) Validate Markdown references and local heading targets.
+    #   4) Validate Markdown image links resolve via cached HTTP(S) HEAD/GET.
     #
     # Usage: Kettle::Dev::PreReleaseCLI.new(check_num: 1).run
     class PreReleaseCLI
@@ -288,6 +290,7 @@ module Kettle
         checks = []
         checks << method(:check_github_actions_sha_pins!)
         checks << method(:check_markdown_uri_normalization!)
+        checks << method(:check_markdown_references!)
         checks << method(:check_markdown_images_http!)
 
         start = @check_num
@@ -376,10 +379,30 @@ module Kettle
         normalized.to_s
       end
 
-      # Check 3: Validate Markdown image links by cached HTTP HEAD/GET.
+      # Check 3: Validate Markdown references and local heading targets.
+      # @return [void]
+      def check_markdown_references!
+        puts "[kettle-pre-release] Check 3: Validate Markdown references and local heading targets"
+        report = MarkdownReferenceValidator.new(
+          root: Dir.pwd,
+          files: Markdown.project_markdown_files
+        ).validate!
+        puts "[kettle-pre-release] Markdown references: #{report.reference_count} references, #{report.local_target_count} local targets, #{report.file_count} files."
+        emit_pre_release_event(
+          action: "markdown_references",
+          status: "ok",
+          files: report.file_count,
+          references: report.reference_count,
+          local_targets: report.local_target_count,
+          failures: 0
+        )
+        nil
+      end
+
+      # Check 4: Validate Markdown image links by cached HTTP HEAD/GET.
       # @return [void]
       def check_markdown_images_http!
-        puts "[kettle-pre-release] Check 3: Validate Markdown image links (cached HTTP HEAD, with GET fallback)"
+        puts "[kettle-pre-release] Check 4: Validate Markdown image links (cached HTTP HEAD, with GET fallback)"
         urls = Markdown.extract_image_urls_from_files
         puts "[kettle-pre-release] Found #{urls.size} unique image URL(s)."
         skipped = []

data/lib/kettle/dev/version.rb

@@ -5,7 +5,7 @@ module Kettle
     # Version namespace for this gem.
     module Version
       # Current gem version.
-      VERSION = "2.5.18"
+      VERSION = "2.5.19"
     end
     # Current gem version exposed at the traditional constant location.
     VERSION = Version::VERSION # Traditional Constant Location

data/lib/kettle/dev.rb

@@ -44,6 +44,7 @@ module Kettle
     autoload :InputAdapter, "kettle/dev/input_adapter"
     autoload :InteractiveReleaseCommand, "kettle/dev/interactive_release_command"
     autoload :LockfileReset, "kettle/dev/lockfile_reset"
+    autoload :MarkdownReferenceValidator, "kettle/dev/markdown_reference_validator"
     autoload :ReadmeBackers, "kettle/dev/readme_backers"
     autoload :OpenCollectiveConfig, "kettle/dev/open_collective_config"
     autoload :ReleaseNotifier, "kettle/dev/release_notifier"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: kettle-dev
 version: !ruby/object:Gem::Version
-  version: 2.5.18
+  version: 2.5.19
 platform: ruby
 authors:
 - Peter H. Boling
@@ -370,6 +370,7 @@ files:
 - lib/kettle/dev/input_adapter.rb
 - lib/kettle/dev/interactive_release_command.rb
 - lib/kettle/dev/lockfile_reset.rb
+- lib/kettle/dev/markdown_reference_validator.rb
 - lib/kettle/dev/open_collective_config.rb
 - lib/kettle/dev/pre_release_cli.rb
 - lib/kettle/dev/rakelib/appraisal.rake
@@ -401,10 +402,10 @@ licenses:
 - AGPL-3.0-only
 metadata:
   homepage_uri: https://kettle-dev.galtzo.com
-  source_code_uri: https://github.com/kettle-dev/kettle-dev/tree/v2.5.18
-  changelog_uri: https://github.com/kettle-dev/kettle-dev/blob/v2.5.18/CHANGELOG.md
+  source_code_uri: https://github.com/kettle-dev/kettle-dev/tree/v2.5.19
+  changelog_uri: https://github.com/kettle-dev/kettle-dev/blob/v2.5.19/CHANGELOG.md
   bug_tracker_uri: https://github.com/kettle-dev/kettle-dev/issues
-  documentation_uri: https://www.rubydoc.info/gems/kettle-dev/2.5.18
+  documentation_uri: https://www.rubydoc.info/gems/kettle-dev/2.5.19
   funding_uri: https://github.com/sponsors/pboling
   wiki_uri: https://github.com/kettle-dev/kettle-dev/wiki
   news_uri: https://www.railsbling.com/tags/kettle-dev