ratatui_ruby 1.2.2 → 1.3.0

data/tasks/doc/documentation.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: AGPL-3.0-or-later
+#++
+
+require "pathname"
+require_relative "source_file"
+
+# All documentation files in the project.
+#
+# Projects contain many files. Only some are documentation: Ruby source with
+# RDoc, Markdown guides, RDoc text files. Finding them manually is tedious.
+# Missing files means missing broken links.
+#
+# Documentation enumerates all relevant files. It excludes vendor and temp
+# directories. It wraps each path in a SourceFile for link extraction.
+#
+# === Example
+#
+#   docs = Documentation.new("/project/root")
+#   docs.each do |file|
+#     file.links.each { |link| puts link.raw }
+#   end
+#   docs.count  # => 392
+#
+class Documentation
+  include Enumerable
+
+  # File extensions to scan for links.
+  EXTENSIONS = %w[rb md rdoc].freeze
+
+  # Directories to skip.
+  EXCLUDES = %w[/vendor/ /tmp/].freeze
+
+  # Creates a new Documentation collection.
+  #
+  # [root] Project root directory to scan.
+  def initialize(root)
+    @root = Pathname.new(root)
+  end
+
+  # Yields each SourceFile in the project.
+  def each(&)
+    files.each(&)
+  end
+
+  private def files # :nodoc:
+    @files ||= EXTENSIONS.flat_map { |ext| glob(ext) }
+  end
+
+  private def glob(extension) # :nodoc:
+    Dir.glob(@root.join("**/*.#{extension}")).filter_map do |path|
+      next if EXCLUDES.any? { |exclude| path.include?(exclude) }
+      SourceFile.new(path, @root)
+    end
+  end
+end

data/tasks/doc/link/file_url.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: AGPL-3.0-or-later
+#++
+
+require_relative "../problem"
+
+# A <tt>file://</tt> URL in documentation.
+#
+# IDEs generate these links for local file access. They work on your machine.
+# They break for everyone else. Published docs cannot contain local paths.
+#
+# FileUrl always returns a Problem. There is no valid use case for
+# <tt>file://</tt> URLs in published documentation.
+#
+# === Example
+#
+#   link = FileUrl.new("file:///path/to/file.rb", 10, source_file)
+#   link.problem(root)  # => Problem (always)
+#
+class FileUrl < Link
+  # Returns a Problem. <tt>file://</tt> URLs never work in published docs.
+  #
+  # [_root] Unused. Present for interface compatibility.
+  def problem(_root)
+    Problem.new(self, "file:// URLs won't work when published")
+  end
+end

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