ratatui_ruby 1.0.0 → 1.1.0

data/tasks/doc/link/relative_path.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: AGPL-3.0-or-later
+#++
+
+require "pathname"
+
+require_relative "../problem"
+
+# A relative path to a local file.
+#
+# Documentation references sibling files: images, other docs, source code.
+# Files get renamed. Directories restructure. These paths silently break.
+#
+# RelativePath resolves the path against the project root and checks if the
+# target exists. It also handles RDoc's HTML naming convention (converting
+# <tt>foo_rb.html</tt> back to <tt>foo.rb</tt> for validation).
+#
+# === Example
+#
+#   link = RelativePath.new("../images/diagram.png", 20, source_file)
+#   link.problem(root)  # => nil (file exists) or Problem (missing)
+#
+class RelativePath < Link
+  # Returns a Problem if the target file does not exist. Returns <tt>nil</tt>
+  # if the path resolves to an existing file or directory.
+  #
+  # [root] Project root directory for resolving absolute paths.
+  def problem(root)
+    root = Pathname.new(root)
+    resolved = resolve(root)
+    return nil unless resolved
+
+    Problem.new(self, "File not found: #{resolved.relative_path_from(root)}") unless exists?(resolved)
+  end
+
+  private def exists?(resolved) # :nodoc:
+    return true if resolved.exist?
+
+    # RDoc generates foo_rb.html from foo.rb
+    if raw.end_with?("_rb.html")
+      source = Pathname.new(resolved.to_s.sub(/_rb\.html$/, ".rb"))
+      return true if source.exist?
+    end
+
+    resolved.directory? if raw.end_with?("/")
+  end
+
+  private def resolve(root) # :nodoc:
+    path = raw.split("#").first&.split("?")&.first
+    return nil if path.nil? || path.empty? || path.length < 4
+
+    if path.start_with?("/")
+      root.join(path.delete_prefix("/"))
+    else
+      source_file.path.dirname.join(path)
+    end
+  end
+end

data/tasks/doc/link/web_url.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: AGPL-3.0-or-later
+#++
+
+require "net/http"
+require "uri"
+
+require_relative "../problem"
+
+# An HTTP or HTTPS URL in documentation.
+#
+# External links rot. Servers go offline. Pages move. A link that worked last
+# year may 404 today. Manual verification is slow and error-prone.
+#
+# WebUrl checks reachability by making a HEAD request. It returns a Problem if
+# the server responds with an error or is unreachable.
+#
+# === Example
+#
+#   link = WebUrl.new("https://example.com", 15, source_file)
+#   link.web?           # => true
+#   link.problem(root)  # => nil (site is up) or Problem (site is down)
+#
+class WebUrl < Link
+  # Whether this link points to a web URL. Always <tt>true</tt> for WebUrl.
+  def web?
+    true
+  end
+
+  # Returns a Problem if the URL is unreachable. Returns <tt>nil</tt> if the
+  # server responds with a 2xx or 3xx status.
+  #
+  # [_root] Unused. Present for interface compatibility.
+  def problem(_root)
+    Problem.new(self, "URL returned error or is unreachable") unless reachable?
+  end
+
+  private def reachable? # :nodoc:
+    uri = URI.parse(raw)
+    return false unless uri.is_a?(URI::HTTP) || uri.is_a?(URI::HTTPS)
+
+    http = Net::HTTP.new(uri.host, uri.port)
+    http.use_ssl = uri.scheme == "https"
+    http.open_timeout = 5
+    http.read_timeout = 5
+
+    response = http.request_head(uri.request_uri)
+    response.code.to_i < 400
+  rescue
+    false
+  end
+end

data/tasks/doc/link.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: AGPL-3.0-or-later
+#++
+
+# Base class for links found in documentation.
+#
+# Documentation contains links: URLs, file paths, images. These links break.
+# Pages move. Files get renamed. Servers go offline. Manual checking is tedious.
+#
+# Link is the base type. It holds the raw text, line number, and source file.
+# Subclasses (FileUrl, WebUrl, RelativePath) implement <tt>problem</tt> to
+# detect specific breakage.
+#
+# Use <tt>Link.build</tt> to create the correct subclass based on the raw text.
+#
+# === Example
+#
+#   link = Link.build("https://example.com", 42, source_file)
+#   link.web?      # => true
+#   link.problem(root)  # => nil or Problem
+#
+class Link < Data.define(:raw, :line, :source_file)
+  # Creates the appropriate Link subclass based on the raw text.
+  #
+  # [raw] The raw link text extracted from the file.
+  # [line] Line number where the link appears.
+  # [source_file] The SourceFile containing this link.
+  def self.build(raw, line, source_file)
+    if raw.start_with?("file://")
+      FileUrl.new(raw, line, source_file)
+    elsif raw.start_with?("https://", "http://")
+      WebUrl.new(raw, line, source_file)
+    else
+      RelativePath.new(raw, line, source_file)
+    end
+  end
+
+  # Whether this link points to a web URL.
+  #
+  # WebUrl overrides this to return <tt>true</tt>. Other link types return
+  # <tt>false</tt>. The audit uses this to decide whether to skip verification.
+  def web?
+    false
+  end
+end
+
+require_relative "link/file_url"
+require_relative "link/web_url"
+require_relative "link/relative_path"

data/tasks/doc/link_audit.rb

@@ -0,0 +1,116 @@
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: AGPL-3.0-or-later
+#++
+
+require_relative "documentation"
+
+# Results of auditing documentation for broken links.
+#
+# Documentation breaks silently. Links rot. Files move. Paths change. Manual
+# checking is tedious and error-prone. Automated checking catches problems
+# before users do.
+#
+# LinkAudit scans all documentation, checks each link, and collects problems.
+# It separates web URLs (slow to verify) from local paths (fast to check).
+# The results render as a human-readable report via <tt>to_s</tt>.
+#
+# === Example
+#
+#   audit = LinkAudit.new("/project/root", verify_web: false)
+#   puts audit           # prints the full report
+#   exit 1 unless audit.success?
+#
+class LinkAudit
+  # Problems found during the audit.
+  attr_reader :problems
+
+  # Web URLs that were not verified (when <tt>verify_web: false</tt>).
+  attr_reader :unverified
+
+  # Creates a new LinkAudit and runs the scan immediately.
+  #
+  # [root] Project root directory to scan.
+  # [verify_web] Whether to make HTTP requests to verify web URLs.
+  def initialize(root, verify_web: false)
+    @root = root
+    @docs = Documentation.new(root)
+    @verify_web = verify_web
+    @problems = []
+    @unverified = []
+    @checked = 0
+    @web_checked = 0
+    scan
+  end
+
+  # Whether the audit passed with no problems.
+  def success?
+    @problems.empty?
+  end
+
+  # Returns the audit report as a String.
+  def to_s
+    lines = []
+    lines << ""
+    lines << "Scanning for broken links in #{@root}..."
+    lines << ""
+
+    if @verify_web
+      lines << "Checked #{@checked} links in #{@docs.count} files (#{@web_checked} web URLs probed)."
+    else
+      lines << "Checked #{@checked} links in #{@docs.count} files (URL verification skipped)."
+    end
+    lines << ""
+
+    unless @unverified.empty?
+      lines << "📋 Unverified HTTP/HTTPS URLs (#{@unverified.size}):"
+      lines << ""
+      @unverified.uniq(&:raw).each { |link| lines << "  #{link.raw}" }
+      lines << ""
+    end
+
+    if @problems.empty?
+      lines << "✅ No broken links found!"
+    else
+      lines << "❌ Found #{@problems.size} broken link(s):"
+      lines << ""
+
+      @problems.group_by(&:file).each do |path, problems|
+        lines << "#{path}:"
+        problems.each do |problem|
+          lines << "  L#{problem.line || '?'}: #{problem.raw}"
+          lines << "       → #{problem.reason}"
+        end
+        lines << ""
+      end
+    end
+
+    lines.join("\n")
+  end
+
+  private def scan # :nodoc:
+    @docs.each do |file|
+      file.links.each do |link|
+        @checked += 1
+        check(link)
+      end
+    end
+  end
+
+  private def check(link) # :nodoc:
+    if link.web?
+      if @verify_web
+        @web_checked += 1
+        problem = link.problem(@root)
+        @problems << problem if problem
+      else
+        @unverified << link
+      end
+    else
+      problem = link.problem(@root)
+      @problems << problem if problem
+    end
+  end
+end

data/tasks/doc/problem.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: AGPL-3.0-or-later
+#++
+
+# Represents a broken link.
+#
+# Link checking produces results. Some links are fine. Some are broken. You
+# need to report the broken ones with context: where they were found and why
+# they failed.
+#
+# Problem holds the link and the reason it failed. It delegates to the link
+# for file, line, and raw text. Use it to build human-readable error reports.
+#
+# === Example
+#
+#   problem = Problem.new(link, "File not found: missing.md")
+#   problem.file    # => "doc/guide.md"
+#   problem.line    # => 42
+#   problem.raw     # => "missing.md"
+#   problem.reason  # => "File not found: missing.md"
+#
+class Problem < Data.define(:link, :reason)
+  # Relative path to the file containing the broken link.
+  def file
+    link.source_file.relative_path
+  end
+
+  # Line number where the broken link appears.
+  def line
+    link.line
+  end
+
+  # The raw link text that failed validation.
+  def raw
+    link.raw
+  end
+end

data/tasks/doc/source_file.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: AGPL-3.0-or-later
+#++
+
+require "pathname"
+require_relative "link"
+
+# A file that may contain links.
+#
+# Documentation lives in many files: Ruby source with RDoc comments, Markdown
+# guides, RDoc text files. Each file may reference images, other docs, or
+# external URLs. Extracting these links by hand is tedious.
+#
+# SourceFile scans its content with regex patterns. It creates the appropriate
+# Link subclass for each match. It tracks line numbers for error reporting.
+#
+# === Example
+#
+#   file = SourceFile.new("/path/to/guide.md", "/project/root")
+#   file.links.each do |link|
+#     puts "#{link.raw} at line #{link.line}"
+#   end
+#
+class SourceFile
+  # Regex patterns for extracting links from documentation.
+  PATTERNS = {
+    rdoc_image_link: /\{rdoc-image:([^}]+)\}\[link:([^\]]+)\]/,
+    rdoc_link: /\{[^}]*\}\[link:([^\]]+)\]/,
+    rdoc_image: /\{rdoc-image:([^}]+)\}/,
+    markdown_link: /\[(?:[^\]]*)\]\((?!mailto:|#)([^)\s]+)\)/,
+    markdown_image: /!\[[^\]]*\]\(([^)\s]+)\)/,
+    html_src: /src=["']([^"']+)["']/,
+    html_href: /href=["'](?!mailto:|#)([^"']+)["']/,
+  }.freeze
+
+  # The Pathname to this file.
+  attr_reader :path
+
+  # Creates a new SourceFile.
+  #
+  # [path] Path to the file (String or Pathname).
+  # [root] Project root directory for computing relative paths.
+  def initialize(path, root)
+    @path = Pathname.new(path)
+    @root = Pathname.new(root)
+  end
+
+  # Extracts all links from the file content. Returns an Array of Link objects.
+  def links
+    found = []
+
+    PATTERNS.each_value do |pattern|
+      content.scan(pattern) do |matches|
+        matches = [matches] unless matches.is_a?(Array)
+        matches.each do |match|
+          next if match.nil? || match.empty?
+          next unless looks_like_link?(match)
+          found << Link.build(match, line_for(match), self)
+        end
+      end
+    end
+
+    found
+  end
+
+  # The file path relative to the project root.
+  def relative_path
+    @path.relative_path_from(@root).to_s
+  end
+
+  private def content # :nodoc:
+    @content ||= @path.read(mode: "rb").force_encoding("UTF-8").scrub("")
+  end
+
+  private def line_for(link_text) # :nodoc:
+    line_num = 1
+    content.each_line do |line|
+      return line_num if line.include?(link_text)
+      line_num += 1
+    end
+    nil
+  end
+
+  private def looks_like_link?(text) # :nodoc:
+    # Skip regex patterns and other false positives
+    return false if text.match?(/[\[\]^*+?]/) # Contains regex special chars
+    return false if text.length < 4
+    true
+  end
+end

data/tasks/doc.rake

@@ -885,3 +885,21 @@ def build_guides_nav(parent_ul, tree, doc, prefix, current_file_rel, current_tre
     parent_ul.add_child(li)
   end
 end
+
+namespace :doc do
+  desc "Check for broken links in RDoc and Markdown files"
+  task :check_links do
+    require_relative "doc/link_audit"
+
+    root = File.expand_path("..", __dir__)
+
+    print "Verify HTTP/HTTPS URLs (slow)? [Y/n] "
+    $stdout.flush
+    verify_web = $stdin.gets&.strip&.downcase != "n"
+
+    audit = LinkAudit.new(root, verify_web:)
+    puts audit
+
+    exit 1 unless audit.success?
+  end
+end

data/tasks/rbs_predicates/predicate_catalog.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: AGPL-3.0-or-later
+#++
+
+require "ratatui_ruby"
+
+# Catalog of all key predicates sourced from Rust + Ruby generation.
+class PredicateCatalog < Data.define(:base_keys, :media_keys, :modifier_keys, :keyboard_modifiers)
+  # ASCII printable characters that can be RBS method names (with backtick escaping)
+  # Excludes: space (0x20), backtick (`), and characters that break RBS parser (:, etc.)
+  RBS_INCOMPATIBLE = %w[` :].freeze
+  CHARACTERS = (0x21..0x7E).map(&:chr).reject { |c| RBS_INCOMPATIBLE.include?(c) }.freeze
+  # Function keys F1-F24 (conventional terminal range)
+  FUNCTION_KEYS = (1..24).map { |n| "f#{n}" }.freeze
+
+  def self.new
+    data = RatatuiRuby._all_key_codes
+    super(
+      base_keys: data[:base_keys],
+      media_keys: data[:media_keys],
+      modifier_keys: data[:modifier_keys],
+      keyboard_modifiers: data[:keyboard_modifiers]
+    )
+  end
+
+  def characters = CHARACTERS
+  def function_keys = FUNCTION_KEYS
+
+  def all_base_codes
+    base_keys + media_keys + modifier_keys + characters + function_keys
+  end
+
+  def modifier_combinations
+    mods = keyboard_modifiers.sort # Modifiers are stored sorted alphabetically
+    one = mods.map { |m| [m] }
+    two = mods.combination(2).map(&:sort)
+    three = mods.combination(3).map(&:sort)
+    one + two + three
+  end
+
+  def all_predicates
+    simple = all_base_codes
+    combined = modifier_combinations.flat_map do |combo|
+      prefix = combo.join("_")
+      all_base_codes.map { |key| "#{prefix}_#{key}" }
+    end
+    simple + combined
+  end
+end

data/tasks/rbs_predicates/predicate_tests.rb

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: AGPL-3.0-or-later
+#++
+
+require "fileutils"
+
+# The generated Minitest file for Event::Key predicates.
+# The tests know how to persist themselves to disk.
+class PredicateTests < Data.define(:catalog, :output_path)
+  DEFAULT_OUTPUT = File.expand_path("../../test/generated/event_key_predicates_test.rb", __dir__)
+
+  def initialize(catalog:, output_path: DEFAULT_OUTPUT)
+    super
+  end
+
+  def persist!
+    FileUtils.mkdir_p(File.dirname(output_path))
+    File.write(output_path, to_ruby)
+    puts "Generated #{test_methods.size} tests to #{output_path}"
+  end
+
+  def to_ruby
+    <<~RUBY
+      # frozen_string_literal: true
+      
+      #--
+      # SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+      # SPDX-License-Identifier: AGPL-3.0-or-later
+      #++
+      
+      # \u2554\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2557
+      # \u2551                     \u26a0\ufe0f  DO NOT EDIT THIS FILE  \u26a0\ufe0f                  \u2551
+      # \u2551                                                                   \u2551
+      # \u2551  This file is auto-generated by: rake rbs:tests                   \u2551
+      # \u2551  Any manual changes will be overwritten on next generation.       \u2551
+      # \u2551                                                                   \u2551
+      # \u2551  To modify tests, edit: tasks/rbs_predicates/predicate_tests.rb   \u2551
+      # \u255a\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u255d
+      
+      require "test_helper"
+      
+      class GeneratedEventKeyPredicatesTest < Minitest::Test
+        include RatatuiRuby::TestHelper
+      
+      #{test_methods.map { |t| t.to_s.gsub(/^/, '  ') }.join("\n\n")}
+      end
+    RUBY
+  end
+
+  private def test_methods
+    simple_tests + combo_tests
+  end
+
+  private def simple_tests
+    catalog.all_base_codes.map { |code| SimplePredicateTest.new(code) }
+  end
+
+  private def combo_tests
+    sampled_combos.map { |combo| ModifierComboTest.new(combo) }
+  end
+
+  private def sampled_combos
+    sample_keys = %w[a enter up f1]
+    catalog.modifier_combinations.product(sample_keys).map { |mods, key| mods + [key] }
+  end
+
+  # A single predicate test that knows how to render itself.
+  class SimplePredicateTest < Data.define(:code)
+    VALID_IDENTIFIER = /\A[a-z_][a-z0-9_]*\?\z/i
+
+    def to_s
+      <<~RUBY.chomp
+        def test_#{method_name}_predicate
+          RatatuiRuby.inject_test_event("key", { code: #{code.inspect} })
+          event = RatatuiRuby.poll_event
+          #{assertion}
+        end
+      RUBY
+    end
+
+    private def predicate = "#{code}?"
+    private def method_name = code.gsub(/[^a-z0-9_]/i) { |c| "_#{c.ord}_" }
+
+    private def assertion
+      if predicate.match?(VALID_IDENTIFIER)
+        "assert event.#{predicate}"
+      else
+        "assert event.public_send(#{predicate.inspect})"
+      end
+    end
+  end
+
+  # A modifier + key combo test that knows how to render itself.
+  class ModifierComboTest < Data.define(:combo)
+    VALID_IDENTIFIER = /\A[a-z_][a-z0-9_]*\?\z/i
+
+    def to_s
+      <<~RUBY.chomp
+        def test_#{method_name}_predicate
+          RatatuiRuby.inject_test_event("key", { code: #{key.inspect}, modifiers: [#{mods_array}] })
+          event = RatatuiRuby.poll_event
+          #{assertion}
+        end
+      RUBY
+    end
+
+    private def key = combo.last
+    private def mods = combo[0...-1]
+    private def mods_array = mods.map(&:inspect).join(", ")
+    private def predicate = "#{combo.join('_')}?"
+    private def method_name = combo.join("_").gsub(/[^a-z0-9_]/i) { |c| "_#{c.ord}_" }
+
+    private def assertion
+      if predicate.match?(VALID_IDENTIFIER)
+        "assert event.#{predicate}"
+      else
+        "assert event.public_send(#{predicate.inspect})"
+      end
+    end
+  end
+end

data/tasks/rbs_predicates/rbs_signature.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: AGPL-3.0-or-later
+#++
+
+# RBS signature file for Event::Key predicates.
+class RbsSignature < Data.define(:catalog, :output_path)
+  DEFAULT_OUTPUT = File.expand_path("../../sig/generated/event_key_predicates.rbs", __dir__)
+
+  def initialize(catalog:, output_path: DEFAULT_OUTPUT)
+    super
+  end
+
+  def write
+    FileUtils.mkdir_p(File.dirname(output_path))
+    File.write(output_path, content)
+    puts "Generated #{catalog.all_predicates.size} predicates to #{output_path}"
+  end
+
+  def content
+    <<~RBS
+      # SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+      # SPDX-License-Identifier: LGPL-3.0-or-later
+      #
+      # ╔═══════════════════════════════════════════════════════════════════╗
+      # ║                     ⚠️  DO NOT EDIT THIS FILE  ⚠️                 ║
+      # ║                                                                   ║
+      # ║  This file is auto-generated by: rake rbs:predicates              ║
+      # ║  Any manual changes will be overwritten on next generation.       ║
+      # ║                                                                   ║
+      # ║  To modify predicates, edit the source in:                        ║
+      # ║    - ext/ratatui_ruby/src/events.rs (key mappings)                ║
+      # ║    - tasks/rbs_predicates/predicate_catalog.rb                    ║
+      # ╚═══════════════════════════════════════════════════════════════════╝
+
+      module RatatuiRuby
+        class Event
+          class Key < Event
+      #{predicate_declarations.map { |d| "      #{d}" }.join("\n")}
+          end
+        end
+      end
+    RBS
+  end
+
+  private def predicate_declarations
+    catalog.all_predicates.map { |name| rbs_method_def(name) }
+  end
+
+  # Valid Ruby method identifier: starts with letter/underscore, followed by word chars, optional ?
+  VALID_PREDICATE_PATTERN = /\A[a-z_][a-z0-9_]*\?\z/i
+
+  def rbs_method_def(name)
+    method_name = "#{name}?"
+    if method_name.match?(VALID_PREDICATE_PATTERN)
+      "def #{method_name}: () -> bool"
+    else
+      "def `#{method_name}`: () -> bool"
+    end
+  end
+end