ratatui_ruby-devtools 0.2.0 → 0.3.0

data/lib/ratatui_ruby/devtools/tasks/bump/sem_ver.rb

@@ -17,37 +17,124 @@
 #
 # === Example
 #
-#   SemVer.parse("1.2.3").next(:minor).to_s  # => "1.3.0"
+#   SemVer.parse("1.2.3").next(:minor).to_s        # => "1.3.0"
+#   SemVer.parse("1.2.3").next(:minor, "rc").to_s  # => "1.3.0-rc.1"
 #
 # See https://semver.org/spec/v2.0.0.html
 class SemVer
+  include Comparable
+
   # The valid segment names for version bumping.
   SEGMENTS = [:major, :minor, :patch].freeze
 
+  # Dot-separated prerelease identifiers. Numeric identifiers have no leading
+  # zeroes.
+  PRERELEASE = /\A(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*\z/
+
   # Parses a version string into a SemVer instance.
   #
-  # [string] A version string like <tt>"1.2.3"</tt>.
+  # Raises ArgumentError for a prerelease that isn't SemVer, such as
+  # <tt>"1.0.0.beta.1"</tt> or <tt>"1.0.0-alpha.001"</tt>.
+  #
+  # [string] A version string like <tt>"1.2.3"</tt> or <tt>"1.0.0-rc.1"</tt>.
   def self.parse(string)
     require "rubygems"
-    segments = Gem::Version.new(string).segments.fill(0, 3).first(3)
-    new(segments)
+    # Extract prerelease suffix (e.g., "-beta.1", "-alpha.2", "-rc.1")
+    base, prerelease = string.split("-", 2)
+    version = Gem::Version.new(base)
+    if version.prerelease?
+      raise ArgumentError, "#{string} is not SemVer. Put the prerelease after a hyphen, like 1.0.0-beta.1."
+    end
+    if prerelease && !prerelease.match?(PRERELEASE)
+      raise ArgumentError, "#{string} has an invalid prerelease. Use dot-separated letters, digits, and hyphens, " \
+        "with no leading zeroes in numbers, like 1.0.0-alpha.1."
+    end
+
+    segments = (version.segments + [0, 0, 0]).first(3)
+    new(segments, prerelease:)
   end
 
   # Creates a new SemVer from an array of segments.
   #
   # [segments] An array of three integers: <tt>[major, minor, patch]</tt>.
-  def initialize(segments)
+  def initialize(segments, prerelease: nil)
     @segments = segments
+    @prerelease = prerelease
+  end
+
+  def major = @segments[0] # :nodoc:
+  def minor = @segments[1] # :nodoc:
+  def patch = @segments[2] # :nodoc:
+
+  # Whether this version promises a stable public API: 1.0 or later, and not a
+  # prerelease, which SemVer marks as unstable.
+  def stable?
+    major >= 1 && @prerelease.nil?
   end
 
   # Returns the next version after bumping the given segment.
   #
-  # Bumping a segment resets all following segments to zero.
+  # Bumping a segment resets all following segments to zero. A prerelease
+  # comes before its release, so bumping it to a segment it already leads up
+  # to releases it: <tt>1.0.0-rc.1</tt> becomes <tt>1.0.0</tt> on any segment,
+  # and <tt>1.2.3-rc.1</tt> becomes <tt>1.2.3</tt> on <tt>:patch</tt>.
+  #
+  # Pass a +label+ to get a prerelease of that version instead. Its number
+  # counts up from the prerelease you're on when that leads to the same
+  # version under the same label, and starts at 1 otherwise:
+  # <tt>1.2.0-rc.1</tt> becomes <tt>1.2.0-rc.2</tt> on <tt>:minor</tt> with
+  # <tt>"rc"</tt>, and <tt>1.2.0-beta.3</tt> becomes <tt>1.2.0-rc.1</tt>.
+  #
+  # Raises ArgumentError when the labelled version would come before this
+  # one. SemVer compares labels as text, so <tt>beta</tt> can't follow
+  # <tt>rc</tt>.
   #
   # [segment] One of <tt>:major</tt>, <tt>:minor</tt>, or <tt>:patch</tt>.
-  def next(segment)
+  # [label] A prerelease label such as <tt>"beta"</tt>, or nil.
+  def next(segment, label = nil)
+    release = release_after(segment)
+    return release unless label
+
+    candidate = SemVer.parse("#{release}-#{label}.#{count_toward(release, label) + 1}")
+    return candidate if candidate > self
+
+    raise ArgumentError, "#{candidate} would come before #{self}. SemVer compares prerelease labels as text, " \
+      "so pick a label that sorts after #{@prerelease.split('.').first}."
+  end
+
+  # Compares versions as SemVer orders them: by segment, then a prerelease
+  # before its release, then by prerelease identifiers.
+  def <=>(other)
+    return unless other.is_a?(SemVer)
+
+    by_segments = @segments <=> other.segments
+    by_segments.zero? ? prerelease_order(other.prerelease) : by_segments
+  end
+
+  # Returns the git tag that names this version, such as <tt>v1.0.0-beta.1</tt>.
+  def to_tag
+    "v#{self}"
+  end
+
+  # Returns the version as RubyGems orders it. RubyGems writes
+  # <tt>1.0.0-beta.1</tt> as <tt>1.0.0.pre.beta.1</tt>, and puts it before
+  # <tt>1.0.0</tt>.
+  def to_gem_version
+    Gem::Version.new(to_s)
+  end
+
+  # Returns the version as a string.
+  def to_s
+    base = @segments.join(".")
+    @prerelease ? "#{base}-#{@prerelease}" : base
+  end
+
+  protected attr_reader :segments, :prerelease # :nodoc:
+
+  private def release_after(segment)
     index = SEGMENTS.index(segment)
     raise ArgumentError, "Invalid segment: #{segment}" unless index
+    return SemVer.new(@segments) if @prerelease && @segments[(index + 1)..].all?(&:zero?)
 
     new_segments = @segments.dup
     new_segments[index] += 1
@@ -56,8 +143,38 @@ class SemVer
     SemVer.new(new_segments)
   end
 
-  # Returns the version as a string.
-  def to_s
-    @segments.join(".")
+  # How many prereleases labelled +label+ this one has counted toward
+  # +release+: 1 for rc.1, none for beta.3 or for another version's rc.
+  private def count_toward(release, label)
+    return 0 unless @prerelease && @segments == release.segments
+
+    @prerelease.match(/\A#{Regexp.escape(label)}(?:\.(\d+))?\z/)&.[](1).to_i
+  end
+
+  # Numeric identifiers compare as numbers and come before words, and a
+  # prerelease that runs out of identifiers first comes first.
+  private def prerelease_order(theirs)
+    return 0 if @prerelease == theirs
+    return 1 unless @prerelease
+    return -1 unless theirs
+
+    ours = @prerelease.split(".")
+    theirs = theirs.split(".")
+    ours.zip(theirs) do |mine, other|
+      return 1 unless other
+
+      order = identifier_order(mine, other)
+      return order unless order.zero?
+    end
+    ours.size <=> theirs.size
+  end
+
+  private def identifier_order(mine, other)
+    numbers = [mine, other].map { |identifier| identifier.to_i if identifier.match?(/\A\d+\z/) }
+    return numbers[0] <=> numbers[1] if numbers.all?
+    return -1 if numbers[0]
+    return 1 if numbers[1]
+
+    mine <=> other
   end
 end

data/lib/ratatui_ruby/devtools/tasks/bump/source_hut_project.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: AGPL-3.0-or-later
+#++
+
+# A project on SourceHut, found from its refs link, such as
+# https://git.sr.ht/~me/gem/refs/HEAD. SourceHut has no comparison view, so
+# each link shows the tree at one ref.
+class SourceHutProject < Data.define(:refs) # :nodoc:
+  LINK = %r{\A(.*?/refs/)HEAD\z}
+
+  def self.linked_from(link)
+    refs = link[LINK, 1]
+    new(refs:) if refs
+  end
+
+  def unreleased(_version)
+    "#{refs}HEAD"
+  end
+
+  def release(version)
+    "#{refs}v#{version}"
+  end
+end

data/lib/ratatui_ruby/devtools/tasks/bump/unbranched_release.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: AGPL-3.0-or-later
+#++
+
+require_relative "bump_workflow"
+
+# Before 1.0 there is no older series to patch, so every release happens on
+# trunk and no release branch is cut.
+class UnbranchedRelease < BumpWorkflow # :nodoc:
+  private def prepare
+    puts "Bumping #{@task}: #{@gem.version} -> #{target}"
+  end
+
+  private def finalize
+    puts "\nCommitted. Push and run: bundle exec rake release"
+  end
+end

data/lib/ratatui_ruby/devtools/tasks/bump/unreleased_section.rb

@@ -20,7 +20,7 @@ require "rdoc"
 # Use it during release preparation.
 class UnreleasedSection
   # Regex to match the Unreleased section.
-  PATTERN = /^(## \[Unreleased\].*?)(?=## \[\d)/m
+  PATTERN = /^(## \[Unreleased\].*?)(?=^## \[\d|^\[Unreleased\]: |\z)/m
 
   # Parses the Unreleased section from changelog content.
   #
@@ -72,4 +72,22 @@ class UnreleasedSection
       .map { |line| formatter.wrap(line, 72) }
       .join("\n\n")
   end
+
+  # Returns all changelog entry lines (lines starting with "- ")
+  def entries
+    @content.lines.select { |line| line.strip.start_with?("- ") }.map(&:strip)
+  end
+
+  # Returns a new UnreleasedSection with entries removed that appear in the given list.
+  def without_entries(entries_to_remove)
+    return self if entries_to_remove.empty?
+
+    new_lines = @content.lines.reject do |line|
+      stripped = line.strip
+      entries_to_remove.include?(stripped)
+    end
+
+    # A removed entry leaves the blank lines that set it apart.
+    self.class.new(new_lines.join.gsub(/\n{3,}/, "\n\n").strip)
+  end
 end

data/lib/ratatui_ruby/devtools/tasks/bump_tasks.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: AGPL-3.0-or-later
+#++
+
+require "rake/tasklib"
+require "rubygems"
+
+require_relative "bump/sem_ver"
+require_relative "bump/release_from_trunk"
+require_relative "bump/patch_release"
+require_relative "bump/unbranched_release"
+
+# The tasks that bump a gem's version.
+class BumpTasks < Rake::TaskLib # :nodoc:
+  def initialize(gem)
+    super()
+    @gem = gem
+    define
+  end
+
+  private def define
+    namespace :bump do
+      desc "Bump major version, or to a prerelease with a label (e.g. rake bump:major[beta])"
+      task :major, [:label] do |_, args|
+        BumpWorkflow.for(@gem, :major, args[:label]).call
+      end
+
+      desc "Bump minor version, or to a prerelease with a label (e.g. rake bump:minor[rc])"
+      task :minor, [:label] do |_, args|
+        BumpWorkflow.for(@gem, :minor, args[:label]).call
+      end
+
+      desc "Bump patch version, or to a prerelease with a label (e.g. rake bump:patch[rc])"
+      task :patch, [:label] do |_, args|
+        BumpWorkflow.for(@gem, :patch, args[:label]).call
+      end
+
+      desc "Set exact version (e.g. rake bump:exact[0.1.0])"
+      task :exact, [:version] do |_, args|
+        BumpWorkflow.to(@gem, SemVer.parse(args[:version]), :exact).call
+      end
+    end
+  end
+end

data/lib/ratatui_ruby/devtools/tasks/cargo_tasks.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: AGPL-3.0-or-later
+#++
+
+require "rake/tasklib"
+
+# Cargo tasks for Rust extensions.
+# Only registered if ext/ directory exists.
+class CargoTasks < Rake::TaskLib # :nodoc:
+  def initialize
+    super
+    define
+  end
+
+  private def define
+    if Dir.exist?("ext")
+      namespace :cargo do
+        desc "Run cargo fmt"
+        task :fmt do
+          ext_dirs = Dir.glob("ext/*").select { |d| File.directory?(d) && File.exist?("#{d}/Cargo.toml") }
+          ext_dirs.each do |dir|
+            sh "cd #{dir} && cargo fmt --all -- --check"
+          end
+        end
+
+        desc "Run cargo clippy"
+        task :clippy do
+          ext_dirs = Dir.glob("ext/*").select { |d| File.directory?(d) && File.exist?("#{d}/Cargo.toml") }
+          ext_dirs.each do |dir|
+            sh "cd #{dir} && cargo clippy -- -D warnings"
+          end
+        end
+
+        desc "Run cargo test"
+        task :test do
+          ext_dirs = Dir.glob("ext/*").select { |d| File.directory?(d) && File.exist?("#{d}/Cargo.toml") }
+          ext_dirs.each do |dir|
+            sh "cd #{dir} && cargo test"
+          end
+        end
+
+        namespace :fix do
+          desc "Auto-fix Clippy warnings (most aggressive)"
+          task :clippy do
+            ext_dirs = Dir.glob("ext/*").select { |d| File.directory?(d) && File.exist?("#{d}/Cargo.toml") }
+            ext_dirs.each do |dir|
+              sh "cd #{dir} && cargo clippy --fix --allow-dirty --allow-staged"
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ratatui_ruby/devtools/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/lib/ratatui_ruby/devtools/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/lib/ratatui_ruby/devtools/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/lib/ratatui_ruby/devtools/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/lib/ratatui_ruby/devtools/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"