ratatui_ruby-devtools 0.2.1 → 0.3.0

data/lib/ratatui_ruby/devtools/scaffold/template_renderer.rb

@@ -0,0 +1,282 @@
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: AGPL-3.0-or-later
+#++
+
+require "erb"
+require "fileutils"
+
+# Renders ERB templates into the target directory.
+#
+# Templates use ERB to inject gem-specific values. This class handles the
+# rendering and file creation with proper directory structure.
+class TemplateRenderer
+  # Creates a new renderer with config and paths.
+  #
+  # [config] The ScaffoldConfig with gem parameters.
+  # [templates_dir] Path to the ERB templates.
+  # [output_dir] Path where rendered files are written.
+  # [update_mode] Whether to ask before overwriting a file that differs.
+  # [input] Where the answers to those questions come from.
+  def initialize(config, templates_dir, output_dir, update_mode: false, input: $stdin)
+    @config = config
+    @templates_dir = templates_dir
+    @output_dir = output_dir
+    @update_mode = update_mode
+    @input = input
+  end
+
+  # Renders all templates into the output directory.
+  def render_all
+    FileUtils.mkdir_p(@output_dir)
+
+    render_template(".gitignore.erb", ".gitignore")
+    render_template(".pre-commit-config.yaml.erb", ".pre-commit-config.yaml")
+    render_template(".rubocop.yml.erb", ".rubocop.yml")
+    render_template("AGENTS.md.erb", "AGENTS.md")
+    render_template("CHANGELOG.md.erb", "CHANGELOG.md") unless @update_mode
+    render_template("CONTRIBUTING.md.erb", "CONTRIBUTING.md")
+    render_template("CODE_OF_CONDUCT.md.erb", "CODE_OF_CONDUCT.md")
+    render_template("Gemfile.erb", "Gemfile")
+    render_template("README.md.erb", "README.md")
+    render_template("REUSE.toml.erb", "REUSE.toml")
+    render_template("Rakefile.erb", "Rakefile")
+    render_template("gemspec.erb", "#{@config.gem_name}.gemspec")
+    render_template("mise.toml.erb", "mise.toml")
+
+    # bin/ scripts
+    render_template("bin/setup.erb", "bin/setup", executable: true)
+    render_template("bin/setup.ps1.erb", "bin/setup.ps1")
+    render_template("bin/console.erb", "bin/console", executable: true)
+
+    # GitHub Actions CI workflow
+    render_template(".github/workflows/ci.yml.erb", ".github/workflows/ci.yml")
+
+    # GitHub Actions build-gems workflow (Rust only)
+    render_template(".github/workflows/build-gems.yml.erb", ".github/workflows/build-gems.yml") if @config.has_rust
+
+    # task resources
+    copy_task_resources
+
+    # doc files (RDoc styling)
+    copy_doc_files
+
+    # lib/ structure
+    create_lib_structure
+
+    # Rust extension (if enabled)
+    create_rust_extension if @config.has_rust
+
+    puts "Scaffolded #{@config.gem_name} in #{@output_dir}"
+  end
+
+  private def render_template(template_name, output_name, executable: false)
+    template_path = File.join(@templates_dir, template_name)
+    output_path = File.join(@output_dir, output_name)
+
+    FileUtils.mkdir_p(File.dirname(output_path))
+
+    unless File.exist?(template_path)
+      warn "  WARNING: Template not found: #{template_name}"
+      return
+    end
+
+    content = if template_name.end_with?(".erb")
+      ERB.new(File.read(template_path), trim_mode: "-").result(binding_for_config)
+    else
+      File.read(template_path)
+    end
+
+    if @update_mode && File.exist?(output_path)
+      existing = File.read(output_path)
+      if existing == content
+        puts "  Unchanged #{output_name}"
+        return
+      end
+      puts "  Conflict #{output_name}"
+      show_diff(output_path, content)
+      print "  Overwrite #{output_name}? [y/N] "
+      answer = @input.gets&.strip
+      unless answer&.match?(/^[Yy]/)
+        puts "  Skipped #{output_name}"
+        return
+      end
+    end
+
+    File.write(output_path, content)
+    FileUtils.chmod(0o755, output_path) if executable
+    puts "  Created #{output_name}"
+  end
+
+  private def show_diff(existing_path, new_content)
+    require "tempfile"
+    Tempfile.create(["scaffold", File.extname(existing_path)]) do |tmp|
+      tmp.write(new_content)
+      tmp.flush
+      system("git", "--no-pager", "diff", "--no-index", "--color", existing_path, tmp.path)
+    end
+  end
+
+  private def copy_task_resources
+    # Render example_viewer.html.erb to tasks/
+    render_template("tasks/example_viewer.html.erb", "tasks/example_viewer.html.erb")
+
+    # Create exe/.gitkeep
+    exe_dir = File.join(@output_dir, "exe")
+    FileUtils.mkdir_p(exe_dir)
+    gitkeep = File.join(exe_dir, ".gitkeep")
+    FileUtils.touch(gitkeep)
+    puts "  Created exe/.gitkeep"
+  end
+
+  private def copy_doc_files
+    doc_dir = File.join(@output_dir, "doc")
+    FileUtils.mkdir_p(doc_dir)
+    FileUtils.mkdir_p(File.join(doc_dir, "getting_started"))
+    FileUtils.mkdir_p(File.join(doc_dir, "concepts"))
+    FileUtils.mkdir_p(File.join(doc_dir, "images"))
+
+    # Render custom.css (now an ERB template)
+    render_template("doc/custom.css.erb", "doc/custom.css")
+
+    # Create images/.gitkeep
+    FileUtils.touch(File.join(doc_dir, "images", ".gitkeep"))
+    puts "  Created doc/images/.gitkeep"
+
+    # Render doc templates
+    render_template("doc/index.md.erb", "doc/index.md")
+    render_template("doc/getting_started/quickstart.md.erb", "doc/getting_started/quickstart.md")
+    render_template("doc/concepts/application_architecture.md.erb", "doc/concepts/application_architecture.md")
+    render_template("doc/concepts/application_testing.md.erb", "doc/concepts/application_testing.md")
+  end
+
+  private def create_lib_structure
+    lib_path = File.join(@output_dir, "lib", @config.require_path)
+    FileUtils.mkdir_p(lib_path)
+
+    # RuboCop config shipped inside the gem (resolved via inherit_gem)
+    render_template("lib/rubocop.yml", "lib/#{@config.require_path}/rubocop.yml")
+
+    # Main require file
+    render_template("lib/main.rb.erb", "lib/#{@config.require_path}.rb")
+
+    # Version file
+    render_template("lib/version.rb.erb", "lib/#{@config.require_path}/version.rb")
+
+    # Test helper shipped inside the gem
+    render_template("lib/test_helper.rb.erb", "lib/#{@config.require_path}/test_helper.rb")
+
+    # Test directory with placeholder
+    FileUtils.mkdir_p(File.join(@output_dir, "test"))
+    render_template("test/test_helper.rb.erb", "test/test_helper.rb")
+  end
+
+  private def create_rust_extension
+    ext_name = @config.gem_name.tr("-", "_")
+
+    render_template("ext/Cargo.toml.erb", "ext/#{ext_name}/Cargo.toml")
+    render_template("ext/extconf.rb.erb", "ext/#{ext_name}/extconf.rb")
+    render_template("ext/.cargo/config.toml.erb", "ext/#{ext_name}/.cargo/config.toml")
+    render_template("ext/.gitignore.erb", "ext/#{ext_name}/.gitignore")
+    render_template("ext/clippy.toml.erb", "ext/#{ext_name}/clippy.toml")
+    render_template("ext/src/lib.rs.erb", "ext/#{ext_name}/src/lib.rs")
+  end
+
+  private def generate_nested_module(parts, content, indent = 0, is_outermost = true)
+    return content if parts.empty?
+
+    prefix = "  " * indent
+    first, *rest = parts
+    inner = generate_nested_module(rest, content, indent + 1, false)
+    inner_prefix = "  " * (indent + 1)
+
+    if rest.empty?
+      # Innermost module - content is a doc comment that goes BEFORE the module
+      if content.empty?
+        "#{prefix}module #{first}\n#{prefix}end"
+      else
+        "#{prefix}#{content}\n#{prefix}module #{first}\n#{prefix}end"
+      end
+    else
+      # Outer modules get :nodoc: to avoid "missing documentation" warnings
+      # (they're documented in the main require file or the core gem)
+      nodoc = is_outermost ? " # :nodoc: Documented in the ratatui_ruby gem." : ""
+      "#{prefix}module #{first}#{nodoc}\n#{inner}\n#{prefix}end"
+    end
+  end
+
+  private def generate_nested_module_with_error(parts, indent = 0)
+    prefix = "  " * indent
+    if parts.length == 1
+      # Innermost module with documented Error class
+      <<~RUBY.chomp
+        #{prefix}module #{parts.first}
+        #{prefix}  # Base error class for this library.
+        #{prefix}  #
+        #{prefix}  # All library-specific exceptions inherit from this class.
+        #{prefix}  # Catch this to handle any library error generically.
+        #{prefix}  class Error < StandardError; end
+        #{prefix}end
+      RUBY
+    else
+      first, *rest = parts
+      inner = generate_nested_module_with_error(rest, indent + 1)
+      "#{prefix}module #{first}\n#{inner}\n#{prefix}end"
+    end
+  end
+
+  private def generate_nested_module_with_version(parts, indent = 0, is_outermost = true)
+    prefix = "  " * indent
+    if parts.length == 1
+      # Innermost module with documented VERSION constant
+      <<~RUBY.chomp
+        #{prefix}module #{parts.first}
+        #{prefix}  # The version of this gem.
+        #{prefix}  # See https://semver.org/spec/v2.0.0.html
+        #{prefix}  VERSION = "0.0.0"
+        #{prefix}end
+      RUBY
+    else
+      first, *rest = parts
+      inner = generate_nested_module_with_version(rest, indent + 1, false)
+      # Outer modules get :nodoc: to avoid "missing documentation" warnings
+      # (they're documented in the main require file or the core gem)
+      nodoc = is_outermost ? " # :nodoc: Documented in the ratatui_ruby gem." : ""
+      "#{prefix}module #{first}#{nodoc}\n#{inner}\n#{prefix}end"
+    end
+  end
+
+  private def binding_for_config
+    module_parts = @config.module_name.split("::")
+    ext_name = @config.gem_name.tr("-", "_")
+
+    # Create a binding with all config values available to templates
+    b = binding
+    b.local_variable_set(:gem_name, @config.gem_name)
+    b.local_variable_set(:gem_display_name, @config.module_name)
+    b.local_variable_set(:module_name, @config.module_name)
+    b.local_variable_set(:require_path, @config.require_path)
+    b.local_variable_set(:copyright_holder, @config.copyright_holder)
+    b.local_variable_set(:license, @config.license)
+    b.local_variable_set(:author, @config.author)
+    b.local_variable_set(:email, @config.email)
+    b.local_variable_set(:year, @config.year)
+    b.local_variable_set(:has_rdoc, true)
+    b.local_variable_set(:has_rust, @config.has_rust)
+    b.local_variable_set(:rubies, @config.ruby_versions)
+    b.local_variable_set(:ext_name, ext_name)
+    b.local_variable_set(:nested_module, generate_nested_module(module_parts, "# Namespace for library functionality."))
+    b.local_variable_set(:nested_module_with_version, generate_nested_module_with_version(module_parts))
+    b.local_variable_set(:update_mode, @update_mode)
+    b.local_variable_set(:dependencies, [])
+    b.local_variable_set(:summary, "Part of the RatatuiRuby ecosystem")
+    b.local_variable_set(:description, "#{@config.module_name} - part of the RatatuiRuby TUI framework ecosystem")
+    b.local_variable_set(:github_repo, "setdef/#{@config.module_name}")
+    b.local_variable_set(:project_name, @config.module_name)
+    b.local_variable_set(:version_file_require, "lib/#{@config.require_path}/version")
+    b.local_variable_set(:version_file, "lib/#{@config.require_path}/version.rb")
+    b
+  end
+end

data/lib/ratatui_ruby/devtools/task_scope.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: AGPL-3.0-or-later
+#++
+
+require "rake"
+
+module RatatuiRuby
+  module Devtools
+    # Where devtools' task files run. Imported at the top level, the helpers
+    # and constants they define would land on every object in your Rakefile.
+    # Here they stay with the tasks that use them, and the tasks can reach
+    # whatever the scope offers.
+    class TaskScope # :nodoc:
+      include Rake::DSL
+
+      def load(dir)
+        Dir.glob("#{dir}/*.rake").each { |path| instance_eval(File.read(path), path) }
+      end
+    end
+  end
+end

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

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: AGPL-3.0-or-later
+#++
+
+require "rake/tasklib"
+require_relative "autodoc/examples"
+
+class AutodocTasks < Rake::TaskLib # :nodoc:
+  def initialize
+    super
+    define
+  end
+
+  private def define
+    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"
+  end
+end

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

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: AGPL-3.0-or-later
+#++
+
+require_relative "repository"
+require_relative "changelog"
+
+# Base class for version bump workflows.
+# Subclasses implement the template methods: assert_can_bump!, prepare,
+# release_on_branch, finalize.
+class BumpWorkflow # :nodoc:
+  def self.for(gem, segment, label = nil)
+    to(gem, gem.version.next(segment, label), segment)
+  end
+
+  # From 1.0 on, each minor version gets a release branch, so its users can
+  # take patch releases without the next minor's changes. The version a bump
+  # releases decides which branch it belongs on, whichever task named it: a
+  # patch bump that finishes 1.0.0-beta.1 opens the 1.0 series, and so does
+  # an exact bump to 1.0.0.
+  def self.to(gem, target, task)
+    workflow = if !target.stable?
+      UnbranchedRelease
+    elsif target.patch.zero?
+      ReleaseFromTrunk
+    else
+      PatchRelease
+    end
+    workflow.new(gem:, task:, target:)
+  end
+
+  def initialize(gem:, task:, target:, repository: Repository.new)
+    @gem = gem
+    @task = task
+    @target = target
+    @repository = repository
+  end
+
+  def call
+    @repository.assert_pristine!
+    assert_can_bump!
+
+    prepare
+    release_on_branch
+    finalize
+  end
+
+  attr_reader :target
+
+  private def release_on_branch
+    changelog = Changelog.new
+    @commit_message = changelog.commit_message(target)
+    changelog.release(target)
+    @gem.update_version(target)
+    @repository.commit_all(@commit_message)
+  end
+
+  # Every release but a patch to an older series happens on trunk.
+  private def assert_can_bump!
+    return if @repository.on_trunk?
+
+    raise ArgumentError, "Cannot bump:#{@task} from #{@repository.current_branch}. Switch to trunk first."
+  end
+
+  # Template methods for subclasses
+  private def prepare = nil
+  private def finalize = nil
+end

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

@@ -41,14 +41,62 @@ class Changelog
     unreleased = UnreleasedSection.parse(content)
     links = Links.from_markdown(content)
 
-    raise "Could not parse CHANGELOG.md" unless header && unreleased && links
+    raise "Could not parse CHANGELOG.md" unless header && unreleased
 
-    history = History.parse(content, header.length, unreleased.to_s.length, links.to_s)
+    history = History.parse(content, header.length, unreleased.to_s.length, links)
 
     links.release(new_version)
     history.add(unreleased.as_version(new_version))
 
-    File.write(@path, "#{header}#{UnreleasedSection.fresh}\n\n#{history}\n#{links}")
+    File.write(@path, "#{header}#{UnreleasedSection.fresh}\n\n#{history}#{links.footer}")
+    nil
+  end
+
+  # Removes entries from [Unreleased] that were released in the given version.
+  # Used when creating a release branch from trunk.
+  def prune_released_entries(released_entries)
+    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
+
+    history = History.parse(content, header.length, unreleased.to_s.length, links)
+
+    pruned = unreleased.without_entries(released_entries)
+
+    File.write(@path, "#{header}#{pruned}\n\n#{history}#{links.footer}")
+    nil
+  end
+
+  # Imports a release section from another branch's changelog.
+  # Adds the version section to history and dedupes from [Unreleased].
+  # Uses "first wins" — if entry already deduped, doesn't re-add it.
+  def import_release(version, release_changelog_content)
+    release_section = extract_version_section(release_changelog_content, version)
+    return unless release_section
+
+    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
+
+    history = History.parse(content, header.length, unreleased.to_s.length, links)
+
+    # Add the release section to history (inserted in version order)
+    history.add(release_section)
+    links.release(version)
+
+    # Dedupe from [Unreleased] (first-wins: if already gone, no-op)
+    release_entries = release_section.lines.select { |l| l.strip.start_with?("- ") }.map(&:strip)
+    pruned = unreleased.without_entries(release_entries)
+
+    File.write(@path, "#{header}#{pruned}\n\n#{history}#{links.footer}")
     nil
   end
 
@@ -64,4 +112,13 @@ class Changelog
 
     "chore: release v#{version}\n\n#{unreleased.commit_body}"
   end
+
+  private def extract_version_section(changelog_content, version)
+    # Match the version heading and capture until the next version heading or links section
+    pattern = /^## \[#{Regexp.escape(version.to_s)}\][^\n]*\n(.*?)(?=^## \[|\n\[Unreleased\]:)/m
+    match = changelog_content.match(pattern)
+    return nil unless match
+
+    "## [#{version}]#{match[0].split("\n", 2).first.split(']', 2).last}\n#{match[1].rstrip}"
+  end
 end

data/lib/ratatui_ruby/devtools/tasks/bump/github_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 GitHub, found from any link into it, such as
+# https://github.com/me/gem/releases/tag/HEAD.
+class GitHubProject < Data.define(:url) # :nodoc:
+  LINK = %r{\A(https://github\.com/[^/]+/[^/]+)/}
+
+  def self.linked_from(link)
+    url = link[LINK, 1]
+    new(url:) if url
+  end
+
+  # Readers browse the code as it stands, rather than read a comparison.
+  def unreleased(_version)
+    "#{url}/tree/HEAD"
+  end
+
+  def release(version)
+    "#{url}/releases/tag/v#{version}"
+  end
+end

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

@@ -21,10 +21,10 @@ class History
   # [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)
+  # [links] The changelog's Links, where the history ends.
+  def self.parse(content, header_length, unreleased_length, links)
     start = header_length + unreleased_length
-    text = "#{content[start...(content.index(links_text))].strip}\n"
+    text = "#{content[start...(links.start_in(content))].strip}\n"
     new(text)
   end
 

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

@@ -5,15 +5,19 @@
 # SPDX-License-Identifier: AGPL-3.0-or-later
 #++
 
+require_relative "github_project"
+require_relative "no_links"
+require_relative "source_hut_project"
+
 # 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.
+# Release automation needs to update links. Manually calculating the URLs
+# for every release is tedious and error-prone, and each forge shapes them
+# differently.
 #
 # 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.
+# It finds the project from the "Unreleased" link and asks it for the new
+# links, on GitHub or SourceHut. It properly shifts the "Unreleased" pointer.
 #
 # Use it to update the changelog during a release.
 class Links
@@ -23,20 +27,20 @@ class Links
   # wasteful. This pattern finds where the links begin.
   PATTERN = /^(\[Unreleased\]: .*)$/m
 
-  # Regex to extract the base URL from the Unreleased link.
+  # Regex to extract the URL of 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$}
+  # New version links derive from the project it links into.
+  UNRELEASED_PATTERN = /^\[Unreleased\]: (\S+)$/
+
+  # The forges whose links a release can write.
+  PROJECTS = [GitHubProject, SourceHutProject].freeze
 
   # 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)
+    match ? new(match[1].strip) : NoLinks.new
   end
 
   # Returns the raw text of the links.
@@ -52,27 +56,38 @@ class Links
   # 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.
+  # the just-released version pointing to its specific tag. Warns instead when
+  # the "Unreleased" link isn't into a GitHub or SourceHut project.
   #
   # [version] String. The new version number (e.g., <tt>"0.5.0"</tt>).
   def release(version)
-    return unless base_url
+    link = @text[UNRELEASED_PATTERN, 1]
+    project = PROJECTS.lazy.filter_map { |forge| forge.linked_from(link) }.first
+    unless project
+      warn "The changelog's Unreleased link, #{link}, isn't into a GitHub or SourceHut project, " \
+        "so #{version} has no link. Add one by hand."
+      return self
+    end
 
-    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}")
+    @text.sub!(UNRELEASED_PATTERN, "[Unreleased]: #{project.unreleased(version)}\n[#{version}]: #{project.release(version)}")
     self
   end
 
+  # Returns where the links begin in +content+, which is where the history
+  # before them ends.
+  #
+  # [content] String. The full text of the changelog.
+  def start_in(content)
+    content.index(@text)
+  end
+
+  # Returns the links as the changelog ends with them, after a blank line.
+  def footer
+    "\n#{@text}\n"
+  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