ratatui_ruby-devtools 0.1.0

data/lib/ratatui_ruby/devtools/tasks/autodoc/examples.rb

@@ -0,0 +1,133 @@
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: AGPL-3.0-or-later
+#++
+
+# Synchronizes code snippets with documentation.
+#
+# Documentation contains code examples. Source files change. Copy-pasting
+# leads to stale examples. Tests pass but the README lies.
+#
+# This module scans markdown files for SYNC markers and replaces content
+# with live source. The documentation stays accurate. No manual updates.
+#
+# Use it to keep README examples in sync with working code.
+module Autodoc
+  # Synchronizes code snippets from source files into markdown.
+  #
+  # Markdown files contain embedded code examples. Maintaining them manually
+  # drifts from the source. This class scans for SYNC markers and injects
+  # live code from the referenced files.
+  #
+  # Use it to sync README.md examples with your actual implementation.
+  #
+  # === Example
+  #
+  # In your README.md:
+  #   <!-- SYNC:START:examples/hello/app.rb:main -->
+  #   ```ruby
+  #   # This content gets replaced
+  #   ```
+  #   <!-- SYNC:END -->
+  #
+  # Then run:
+  #   Autodoc::Examples.sync
+  #
+  class Examples
+    # Synchronize all README files in the repository.
+    def self.sync
+      new.sync
+    end
+
+    # Synchronize all README files.
+    #
+    # Scans for SYNC markers in markdown files and replaces content with
+    # source file snippets.
+    def sync
+      Dir.glob("{README.md,doc/**/*.md,examples/*/README.md}").each do |readme_path|
+        sync_readme(readme_path)
+      end
+    end
+
+    private def sync_readme(readme_path)
+      content = File.read(readme_path)
+      dir = File.dirname(readme_path)
+
+      new_content = content.gsub(/<!-- SYNC:START:([^ ]+) -->.*?<!-- SYNC:END -->/m) do
+        marker_info = $1
+        source_rel_path, segment_id = marker_info.split(":")
+
+        # Support both repo-root-relative paths (no leading ./) and file-relative paths
+        source_path = if source_rel_path.start_with?("./", "../")
+          File.join(dir, source_rel_path)
+        else
+          source_rel_path # Already relative to repo root
+        end
+
+        unless File.exist?(source_path)
+          warn "Warning: Source file not found: #{source_path}"
+          next $&
+        end
+
+        source_content = File.read(source_path)
+        extracted_content = if segment_id
+          extract_segment(source_content, segment_id, source_path)
+        else
+          source_content
+        end
+
+        # Detect language from extension
+        ext = File.extname(source_path).delete(".")
+        lang = (ext == "rb") ? "ruby" : ext
+
+        # Build replacement
+        "<!-- SYNC:START:#{marker_info} -->\n```#{lang}\n#{extracted_content}```\n<!-- SYNC:END -->"
+      end
+
+      if new_content != content
+        puts "Syncing #{readme_path}..."
+        File.write(readme_path, new_content)
+      end
+    end
+
+    # Extracts a named segment from source content.
+    #
+    # Source files contain segment markers like <tt>[SYNC:START:main]</tt>.
+    # This method extracts the content between matching markers.
+    #
+    # [content] The source file content.
+    # [segment_id] The segment name to extract.
+    # [source_path] The source file path (for error messages).
+    def extract_segment(content, segment_id, source_path)
+      start_marker = /#\s*\[SYNC:START:#{segment_id}\]/
+      end_marker = /#\s*\[SYNC:END:#{segment_id}\]/
+
+      lines = content.lines
+      start_idx = lines.find_index { |l| l =~ start_marker }
+      end_idx = lines.find_index { |l| l =~ end_marker }
+
+      if start_idx && end_idx
+        "#{unindent(lines[(start_idx + 1)...end_idx].join).strip}\n"
+      else
+        warn "Warning: Segment '#{segment_id}' not found in #{source_path}"
+        content
+      end
+    end
+
+    # Removes common leading indentation from text.
+    #
+    # Code segments often have indentation from their context. This method
+    # strips the common prefix so the output looks clean.
+    #
+    # [text] The text to unindent.
+    def unindent(text)
+      lines = text.lines
+      return text if lines.empty?
+
+      indentation = lines.grep(/\S/).map { |l| l[/^\s*/].length }.min || 0
+      lines.map { |l| (l.length > indentation) ? l[indentation..-1] : "#{l.strip}\n" }.join
+    end
+  end
+end

data/lib/ratatui_ruby/devtools/tasks/autodoc/member.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
+#++
+
+module Autodoc
+  # Member types for autodoc generation.
+  #
+  # Autodoc generates RBS types and RDoc comments for TUI factory methods.
+  # Each method type (delegate, factory, helper) has different documentation
+  # patterns. Writing these by hand is tedious and error-prone.
+  #
+  # These Data classes generate consistent RBS and RDoc output for each
+  # member type. Feed them method names. Get documentation.
+  module Member
+    # A method that delegates to an identically-named module method.
+    #
+    # Some instance methods simply call a module-level method. This class
+    # generates the RBS signature and RDoc comment for such methods.
+    #
+    # [name] The method name.
+    class Delegate < Data.define(:name)
+      # Generates an RBS type signature for this delegate.
+      #
+      # Autodoc writes .rbs files. Each method needs a signature. Delegates
+      # forward all arguments, so they use a generic variadic signature.
+      def rbs
+        "    def #{name}: (*untyped args, **untyped kwargs) ?{ (*untyped) -> untyped } -> untyped"
+      end
+
+      # Generates RDoc comment lines for this delegate.
+      #
+      # Autodoc writes method documentation. Each method needs a comment.
+      # Delegates describe forwarding to the module method. This returns
+      # the correctly-formatted comment lines.
+      def rdoc
+        [
+          "    # :method: #{name}",
+          "    # :call-seq: #{name}(*args, **kwargs, &block)",
+          "    #",
+          "    # Delegates to RatatuiRuby.#{name}.",
+          "    #",
+        ]
+      end
+    end
+
+    # A factory method that creates instances of a widget class.
+    #
+    # Factory methods like <tt>paragraph</tt> create <tt>Paragraph.new</tt>.
+    # This class generates the RBS signature and RDoc comment.
+    #
+    # [name] The method name.
+    # [const_name] The constant name (e.g., <tt>Paragraph</tt>).
+    class Factory < Data.define(:name, :const_name)
+      # Generates an RBS type signature for this factory.
+      #
+      # Autodoc writes .rbs files. Each method needs a signature. Factories
+      # forward all arguments to constructors, so they use a generic variadic
+      # signature.
+      def rbs
+        "    def #{name}: (*untyped args, **untyped kwargs) ?{ (*untyped) -> untyped } -> untyped"
+      end
+
+      # Generates RDoc comment lines for this factory.
+      #
+      # Autodoc writes method documentation. Each method needs a comment.
+      # Factories describe creating a widget instance. This returns the
+      # correctly-formatted comment lines.
+      def rdoc
+        [
+          "    # :method: #{name}",
+          "    # :call-seq: #{name}(*args, **kwargs, &block)",
+          "    #",
+          "    # Factory for RatatuiRuby::#{const_name}.new.",
+          "    #",
+        ]
+      end
+    end
+
+    # A helper method that wraps a class method.
+    #
+    # Helper methods call class methods with simplified signatures. This
+    # class generates the RBS signature and RDoc comment.
+    #
+    # [name] The method name.
+    # [class_method] The class method being wrapped.
+    # [const_name] The constant name.
+    class Helper < Data.define(:name, :class_method, :const_name)
+      # Generates an RBS type signature for this helper.
+      #
+      # Autodoc writes .rbs files. Each method needs a signature. Helpers
+      # forward all arguments to class methods, so they use a generic variadic
+      # signature.
+      def rbs
+        "    def #{name}: (*untyped args, **untyped kwargs) ?{ (*untyped) -> untyped } -> untyped"
+      end
+
+      # Generates RDoc comment lines for this helper.
+      #
+      # Autodoc writes method documentation. Each method needs a comment.
+      # Helpers describe calling a class method. This returns the
+      # correctly-formatted comment lines.
+      def rdoc
+        [
+          "    # :method: #{name}",
+          "    # :call-seq: #{name}(*args, **kwargs, &block)",
+          "    #",
+          "    # Helper for RatatuiRuby::#{const_name}.#{class_method}.",
+          "    #",
+        ]
+      end
+    end
+  end
+end

data/lib/ratatui_ruby/devtools/tasks/autodoc/name.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: AGPL-3.0-or-later
+#++
+
+module Autodoc
+  # Wraps a name string with case conversion utilities.
+  #
+  # Ruby uses snake_case. Constants use PascalCase. Converting between them
+  # by hand invites typos. This class handles the conversion.
+  #
+  # [string] The name string.
+  class Name < Data.define(:string)
+    # Converts the name to snake_case.
+    #
+    # === Example
+    #
+    #   Autodoc::Name.new("BarChart").snake  # => "bar_chart"
+    def snake
+      string.to_s
+        .gsub(/([A-Z]+)([A-Z][a-z])/, '\1_\2')
+        .gsub(/([a-z\d])([A-Z])/, '\1_\2')
+        .downcase
+    end
+
+    # Returns the original string.
+    def to_s
+      string.to_s
+    end
+  end
+end

data/lib/ratatui_ruby/devtools/tasks/autodoc.rake

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: AGPL-3.0-or-later
+#++
+
+require_relative "autodoc/examples"
+
+namespace :autodoc do
+  desc "Update all automatically generated documentation"
+  task all: [:examples]
+
+  desc "Sync code snippets in example READMEs with source files"
+  task :examples do
+    Autodoc::Examples.sync
+  end
+end
+
+desc "Update all automatically generated documentation"
+task autodoc: "autodoc:all"

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

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: AGPL-3.0-or-later
+#++
+
+# Refreshes Cargo.lock after version changes.
+#
+# Rust crates have lockfiles that pin dependency versions. After updating
+# Cargo.toml, the lockfile becomes stale. Running cargo update fixes it.
+#
+# This class wraps the lockfile refresh operation. It runs cargo update
+# in the crate directory. Use it after bumping Rust extension versions.
+#
+# [path] The path to the Cargo.lock file.
+# [dir] The directory containing the Cargo.toml.
+# [name] The crate name to update.
+class CargoLockfile < Data.define(:path, :dir, :name)
+  # Checks whether the lockfile exists on disk.
+  #
+  # Pure Ruby gems have no Cargo.lock. Refreshing a missing file fails. Check
+  # this before calling refresh to avoid errors.
+  def exists?
+    File.exist?(path)
+  end
+
+  # Refreshes the lockfile by running cargo update.
+  #
+  # Runs <tt>cargo update -p {name} --offline</tt> in the crate directory.
+  def refresh
+    return unless exists?
+
+    Dir.chdir(dir) do
+      system("cargo update -p #{name} --offline")
+    end
+  end
+end

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

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: AGPL-3.0-or-later
+#++
+
+require_relative "links"
+require_relative "unreleased_section"
+require_relative "history"
+require_relative "header"
+
+# Manages the project's CHANGELOG.md file.
+#
+# Changelogs track user-facing changes. During a release, the Unreleased
+# section becomes a versioned section. Links update. The Unreleased section
+# resets. Doing this by hand invites errors.
+#
+# This class orchestrates the changelog update. It parses the sections, moves
+# content, updates links, and writes the result. One call. Clean changelog.
+#
+# Use it during version bumps to update the release notes.
+class Changelog
+  # Creates a new Changelog manager.
+  #
+  # [path] The path to the changelog file. Defaults to <tt>CHANGELOG.md</tt>.
+  def initialize(path: "CHANGELOG.md")
+    @path = path
+  end
+
+  # Releases a new version in the changelog.
+  #
+  # Moves unreleased changes to a dated version section. Resets the Unreleased
+  # section. Updates the comparison links.
+  #
+  # [new_version] The SemVer or version string to release.
+  def release(new_version)
+    content = File.read(@path)
+
+    header = Header.parse(content)
+    unreleased = UnreleasedSection.parse(content)
+    links = Links.from_markdown(content)
+
+    raise "Could not parse CHANGELOG.md" unless header && unreleased && links
+
+    history = History.parse(content, header.length, unreleased.to_s.length, links.to_s)
+
+    links.release(new_version)
+    history.add(unreleased.as_version(new_version))
+
+    File.write(@path, "#{header}#{UnreleasedSection.fresh}\n\n#{history}\n#{links}")
+    nil
+  end
+
+  # Generates a commit message for the release.
+  #
+  # Extracts the unreleased changes and formats them for a commit body.
+  #
+  # [version] The version being released.
+  def commit_message(version)
+    content = File.read(@path)
+    unreleased = UnreleasedSection.parse(content)
+    return nil unless unreleased
+
+    "chore: release v#{version}\n\n#{unreleased.commit_body}"
+  end
+end

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

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: AGPL-3.0-or-later
+#++
+
+# Manages the header section of a changelog.
+#
+# Changelogs start with a header: title, description, format reference. During
+# updates, this section stays unchanged. Extracting it ensures safe rewrites.
+#
+# This class parses the header from changelog markdown. It preserves it
+# during modifications.
+class Header
+  # Regex to match everything before the Unreleased section.
+  PATTERN = /^(.*?)(?=## \[Unreleased\])/m
+
+  # Parses the header from changelog content.
+  #
+  # [content] The full changelog text.
+  def self.parse(content)
+    match = content.match(PATTERN)
+    new(match[1]) if match
+  end
+
+  # Creates a new Header.
+  #
+  # [content] The raw header text.
+  def initialize(content)
+    @content = content.dup
+  end
+
+  # Returns the byte length of the header.
+  def length
+    @content.length
+  end
+
+  # Returns the header as a string.
+  def to_s
+    @content
+  end
+end

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

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: AGPL-3.0-or-later
+#++
+
+# Manages the versioned history section of a changelog.
+#
+# Changelogs contain past version entries below the Unreleased section. During
+# a release, new version entries prepend to this history. Manipulating it
+# manually risks corruption.
+#
+# This class extracts history from the changelog. It prepends new version
+# entries. It serializes back to markdown.
+#
+# Use it during release preparation.
+class History
+  # Parses the history section from changelog content.
+  #
+  # [content] The full changelog text.
+  # [header_length] Length of the header section.
+  # [unreleased_length] Length of the Unreleased section.
+  # [links_text] The links section text (used as end marker).
+  def self.parse(content, header_length, unreleased_length, links_text)
+    start = header_length + unreleased_length
+    text = "#{content[start...(content.index(links_text))].strip}\n"
+    new(text)
+  end
+
+  # Creates a new History.
+  #
+  # [content] The raw history text.
+  def initialize(content)
+    @content = content.dup
+  end
+
+  # Adds a new versioned section to the beginning of history.
+  #
+  # [section] The version section text to prepend.
+  def add(section)
+    @content = "#{"#{section}\n\n#{@content}".strip}\n"
+    nil
+  end
+
+  # Returns the history as a string.
+  def to_s
+    @content
+  end
+end

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

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: AGPL-3.0-or-later
+#++
+
+# Manages the version comparison links at the botton of the changelog.
+#
+# Release automation needs to update links. Manually calculating git diff URLs
+# for every release is tedious and error-prone. SourceHut does not have
+# standard comparison views, complicating matters further.
+#
+# This class manages the collection of links. It parses them from the markdown.
+# It generates the correct tree links for SourceHut. It properly shifts the
+# "Unreleased" pointer.
+#
+# Use it to update the changelog during a release.
+class Links
+  # Regex to match the markdown links section.
+  #
+  # Changelogs end with reference-style links. Scanning the whole document is
+  # wasteful. This pattern finds where the links begin.
+  PATTERN = /^(\[Unreleased\]: .*)$/m
+
+  # Regex to extract the base URL from the Unreleased link.
+  #
+  # New version links derive from the Unreleased URL structure. Parsing the
+  # URL components enables programmatic link generation.
+  UNRELEASED_PATTERN = %r{^\[Unreleased\]: (.*?/refs/)HEAD$}
+
+  # Creates a Links object from the full markdown content.
+  #
+  # [content] String. The full text of the changelog.
+  def self.from_markdown(content)
+    match = content.match(PATTERN)
+    return unless match
+
+    new(match[1].strip)
+  end
+
+  # Returns the raw text of the links.
+  attr_reader :text
+
+  # Creates a new Links object.
+  #
+  # [text] String. The raw text of the links section.
+  def initialize(text)
+    @text = text.dup
+  end
+
+  # Releases a new version.
+  #
+  # Updates the "Unreleased" link to point to the new head. Adds a new link for
+  # the just-released version pointing to its specific tag.
+  #
+  # [version] String. The new version number (e.g., <tt>"0.5.0"</tt>).
+  def release(version)
+    return unless base_url
+
+    new_unreleased = "[Unreleased]: #{base_url}HEAD" # .../HEAD
+    new_version_link = "[#{version}]: #{base_url}v#{version}" # .../v1.0.0
+
+    @text.sub!(UNRELEASED_PATTERN, "#{new_unreleased}\n#{new_version_link}")
+    self
+  end
+
+  # Returns the string representation of the links.
+  def to_s
+    @text
+  end
+
+  # The base URL for the repository's references.
+  private def base_url
+    match = @text.match(UNRELEASED_PATTERN)
+    match[1] if match
+  end
+end

data/lib/ratatui_ruby/devtools/tasks/bump/manifest.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
+#++
+
+# Represents a file that contains a version number.
+#
+# Gems have version numbers in multiple places: version.rb, Cargo.toml, etc.
+# Finding and updating them by hand risks inconsistency. One file says 1.2.3,
+# another says 1.2.2.
+#
+# This class wraps a file path with a regex pattern. It reads the current
+# version and writes new versions. Use lookaround patterns to match precisely.
+#
+# [path] The file path.
+# [pattern] A regex with lookarounds to match the version string.
+# [primary] Whether this is the primary source of truth.
+#
+# === Example
+#
+#   manifest = Manifest.new(
+#     path: "lib/my_gem/version.rb",
+#     pattern: /(?<=VERSION = ")[^"]+(?=")/,
+#     primary: true
+#   )
+#   manifest.version.to_s  # => "1.2.3"
+#
+class Manifest < Data.define(:path, :pattern, :primary)
+  # Creates a new Manifest.
+  #
+  # [path] The file path.
+  # [pattern] A regex with lookarounds to match the version string.
+  # [primary] Whether this is the primary source of truth.
+  def initialize(path:, pattern:, primary: false)
+    super
+  end
+
+  # Reads the file content.
+  def read
+    File.read(path)
+  end
+
+  # Returns the current version from this manifest.
+  def version
+    content = read
+    match = content.match(pattern)
+    raise "Version missing in manifest #{path}" unless match
+
+    SemVer.parse(match[0])
+  end
+
+  # Writes a new version to this manifest.
+  #
+  # [version] The SemVer to write.
+  def write(version)
+    return unless File.exist?(path)
+
+    new_content = read.gsub(pattern, version.to_s)
+    File.write(path, new_content)
+  end
+end