ratatui_ruby-devtools 0.2.1 → 0.3.0

data/lib/ratatui_ruby/devtools/tasks/license/snippet_revision.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: AGPL-3.0-or-later
+#++
+
+require_relative "blame"
+require_relative "copyright"
+
+# One file's snippets brought up to date: each bare snippet asks to be
+# wrapped, and each wrapped one whose notices have moved on asks to be
+# reopened.
+class SnippetRevision # :nodoc:
+  def initialize(path:, text:, syntax:, author:)
+    @path = path
+    @original = text
+    @syntax = syntax
+    @author = author
+    @lines = syntax.cleaned(text.lines)
+    @snippets = syntax.snippets_in(@lines)
+    @notices = []
+    # Blame reads the cleaned lines the snippets were found in, not the file
+    # on disk.
+    @blame = Blame.new(path:, contents: @lines.join)
+  end
+
+  # Revises from the last snippet back, so the earlier ones stay on the lines
+  # blame found them on.
+  def run
+    @snippets.reverse_each { |snippet| snippet.revise(self) }
+    self
+  end
+
+  def text
+    @lines.join
+  end
+
+  def changed?
+    text != @original
+  end
+
+  # What the revision did, for whoever ran it.
+  def messages
+    return [] unless changed?
+
+    wrapped = @snippets.count(&:bare?)
+    summary = if wrapped.zero?
+      "Updated: #{@path}"
+    else
+      "Updated: #{@path} (#{wrapped} code block(s))"
+    end
+    [*@notices.map { |notice| "  #{notice}" }, summary]
+  end
+
+  def contributions(snippet)
+    @blame.contributions([snippet.blame_range], uncommitted_by: @author)
+  end
+
+  def license
+    @syntax.license
+  end
+
+  def wrap(snippet)
+    copyrights = contributions(snippet).map { |contribution| Copyright.of(contribution) }.sort_by(&:holder)
+    @lines.insert(snippet.last + 1, *@syntax.closing(snippet))
+    @lines.insert(snippet.first, *@syntax.opening(snippet, copyrights))
+  end
+
+  def reopen(snippet, renewal)
+    opening = renewal.value
+    @lines[opening.span] = @syntax.opening(snippet, opening.copyrights)
+    @notices.concat(renewal.notices)
+  end
+end

data/lib/ratatui_ruby/devtools/tasks/license/spdx_header.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: AGPL-3.0-or-later
+#++
+
+require_relative "copyright"
+require_relative "renewal"
+
+class SpdxHeader < Data.define(:copyrights, :license) # :nodoc:
+  def self.of(author, contributions, license)
+    copyrights = if contributions.empty?
+      [Copyright.yours(author)]
+    else
+      contributions.map { |contribution| Copyright.of(contribution) }.sort_by(&:holder)
+    end
+    new(copyrights:, license:)
+  end
+
+  def renewal(contributions, license)
+    renewals = copyrights.map { |copyright| copyright.renewal(contributions) }
+    renewed_copyrights = renewals.map(&:value)
+    notices = renewals.flat_map(&:notices)
+    contributions.each do |contribution|
+      next if renewed_copyrights.any? { |copyright| copyright.held_by?(contribution.author) }
+
+      notices << "Adding #{contribution.author.name}'s copyright"
+      renewed_copyrights << Copyright.of(contribution)
+    end
+    notices << "Fixing license: #{self.license} -> #{license}" if self.license != license
+
+    Renewal.new(value: with(copyrights: renewed_copyrights, license:), notices:)
+  end
+
+  def commented(prefix)
+    # REUSE-IgnoreStart
+    copyrights.map { |copyright| "#{prefix} SPDX-FileCopyrightText: #{copyright}\n" }.join +
+      "#{prefix} SPDX-License-Identifier: #{license}\n"
+    # REUSE-IgnoreEnd
+  end
+end

data/lib/ratatui_ruby/devtools/tasks/license/unknown_file.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: AGPL-3.0-or-later
+#++
+
+class UnknownFile < Data.define(:path) # :nodoc:
+  def annotate
+    ["Skipping #{path} (unknown extension: .#{File.extname(path).delete_prefix('.')})"]
+  end
+end

data/lib/ratatui_ruby/devtools/tasks/license/unlicensed_files.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: AGPL-3.0-or-later
+#++
+
+require_relative "licensed_file"
+require_relative "licensing"
+require_relative "markdown_header_syntax"
+require_relative "rbs_header_syntax"
+require_relative "reuse_annotated_file"
+require_relative "ruby_header_syntax"
+require_relative "rust_header_syntax"
+require_relative "unknown_file"
+
+# The files the REUSE Tool finds without headers. The license tasks know each
+# language's header and who to credit, so the tool annotates only the rest.
+class UnlicensedFiles # :nodoc:
+  CODE_EXTENSIONS = %w[rb rs rake gemspec rbs toml yml yaml json lock].freeze
+  DOC_EXTENSIONS = %w[md txt].freeze
+  DOC_LICENSE = "CC-BY-SA-4.0"
+
+  def initialize(tool, repository, overrides, licensing)
+    @tool = tool
+    @repository = repository
+    @overrides = overrides
+    @licensing = licensing
+    @syntaxes = [
+      MarkdownHeaderSyntax.new,
+      RubyHeaderSyntax.new(licensing),
+      RbsHeaderSyntax.new(licensing),
+      RustHeaderSyntax.new(licensing),
+    ]
+  end
+
+  # Licenses what the tool found and says what it did.
+  def license
+    paths = @tool.unlicensed_paths
+    return ["All files have REUSE headers!"] if paths.empty?
+
+    paths.flat_map { |path| file_at(path).annotate.map { |message| "  #{message}" } }
+  end
+
+  private def file_at(path)
+    syntax = @syntaxes.find { |candidate| candidate.covers?(path) }
+    return LicensedFile.new(path:, syntax:, author:) if syntax
+
+    license = license_for(path)
+    return UnknownFile.new(path:) unless license
+
+    ReuseAnnotatedFile.new(path:, license:, copyright:, tool: @tool)
+  end
+
+  private def license_for(path)
+    case File.extname(path).delete_prefix(".")
+    when *CODE_EXTENSIONS then @overrides.fetch("REUSE_CODE_LICENSE") { @licensing.license_for(path) }
+    when *DOC_EXTENSIONS then @overrides.fetch("REUSE_DOC_LICENSE", DOC_LICENSE)
+    end
+  end
+
+  private def copyright
+    @overrides.fetch("REUSE_COPYRIGHT") { author.to_s }
+  end
+
+  private def author
+    @author ||= @repository.author
+  end
+end

data/lib/ratatui_ruby/devtools/tasks/license/wrapped_snippet.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
+#++
+
+# A Snippet that already has its wrapper, opened by its SnippetOpening.
+class WrappedSnippet < Data.define(:snippet, :opening) # :nodoc:
+  def first
+    snippet.first
+  end
+
+  def covers?(other)
+    other.first.between?(snippet.first, snippet.last)
+  end
+
+  def blame_range
+    snippet.blame_range
+  end
+
+  def bare?
+    false
+  end
+
+  def revise(revision)
+    renewal = opening.renewal(revision.contributions(self), revision.license)
+    revision.reopen(snippet, renewal) if renewal.changed?
+  end
+end

data/lib/ratatui_ruby/devtools/tasks/license_tasks.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 "rake/tasklib"
+
+require_relative "license/changed_files"
+require_relative "license/licensed_file"
+require_relative "license/markdown_header_syntax"
+require_relative "license/markdown_snippet_syntax"
+require_relative "license/rbs_header_syntax"
+require_relative "license/rdoc_snippet_syntax"
+require_relative "license/ruby_header_syntax"
+require_relative "license/rust_header_syntax"
+require_relative "license/snippet_file"
+
+# The tasks that write license headers and snippet wrappers.
+class LicenseTasks < Rake::TaskLib # :nodoc:
+  def initialize(licensing)
+    super()
+    @licensing = licensing
+    define
+  end
+
+  private def define
+    namespace :license do
+      namespace :headers do
+        {
+          md: ["Ensure markdown files have correct CC-BY-SA-4.0 headers", MarkdownHeaderSyntax.new],
+          rb: ["Ensure Ruby files have correct SPDX headers", RubyHeaderSyntax.new(@licensing)],
+          rbs: ["Ensure RBS files have correct SPDX headers", RbsHeaderSyntax.new(@licensing)],
+          rs: ["Ensure Rust files have correct SPDX headers", RustHeaderSyntax.new(@licensing)],
+        }.each do |name, (description, syntax)|
+          desc description
+          task name, [:files] do |_t, args|
+            LicensedFile.tracked(args[:files].to_s.split, syntax).flat_map(&:annotate).each { |message| puts message }
+          end
+        end
+
+        desc "Ensure all files have correct license headers"
+        task all: %w[md rb rbs rs]
+      end
+
+      namespace :snippets do
+        {
+          md: ["Add MIT-0 SPDX snippet headers to markdown fenced code blocks", MarkdownSnippetSyntax, ""],
+          rdoc: ["Add MIT-0 SPDX snippet headers to RDoc code examples in Ruby files", RdocSnippetSyntax, "lib/"],
+        }.each do |name, (description, syntax, default)|
+          desc description
+          task name, [:files] do |_t, args|
+            SnippetFile.tracked((args[:files] || default).split, syntax.new).flat_map(&:annotate).each { |message| puts message }
+          end
+        end
+
+        desc "Add MIT-0 SPDX snippet headers to all code examples"
+        task all: %w[md rdoc]
+      end
+
+      desc "Run all license tasks (headers + snippets)"
+      task all: ["headers:all", "snippets:all"]
+
+      desc "Run license tasks on changed files only (staged + unstaged)"
+      task :new do
+        ChangedFiles.new(Repository.new, @licensing).license.each { |message| puts message }
+      end
+    end
+  end
+end

data/lib/ratatui_ruby/devtools/tasks/lint/gem_lockfile.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: AGPL-3.0-or-later
+#++
+
+# The gems Bundler locked for this project.
+#
+# CI installs the lockfile on every supported Ruby, but Bundler only checks
+# gems against the Ruby that resolves it. A lockfile resolved on the newest
+# Ruby can hold gems the oldest one can't install.
+class GemLockfile < Data.define(:specs) # :nodoc:
+  def gems_too_new_for(ruby)
+    specs.reject { |spec| spec.required_ruby_version.satisfied_by?(ruby) }
+  end
+
+  def verify(ruby)
+    too_new = gems_too_new_for(ruby)
+    return if too_new.empty?
+
+    abort <<~MESSAGE
+      These locked gems need a newer Ruby than #{ruby}, the oldest the gemspec supports:
+      #{too_new.map { |spec| "  #{spec.full_name} (Ruby #{spec.required_ruby_version})" }.join("\n")}
+      Resolve them with that Ruby instead:
+        mise x ruby@#{ruby} -- bundle lock --update #{too_new.map(&:name).join(' ')}
+    MESSAGE
+  end
+end

data/lib/ratatui_ruby/devtools/tasks/lint/supported_rubies.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: AGPL-3.0-or-later
+#++
+
+# The Ruby versions a gemspec supports.
+class SupportedRubies < Data.define(:requirement) # :nodoc:
+  def self.of(spec)
+    new(requirement: spec.required_ruby_version)
+  end
+
+  def oldest
+    _, version = requirement.requirements.find { |operator, _| operator == ">=" }
+    version
+  end
+end

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

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: AGPL-3.0-or-later
+#++
+
+require "rubocop/rake_task"
+require "rubycritic/rake_task"
+require "inch/rake"
+require "rake/tasklib"
+
+# The tasks that lint a gem.
+class LintTasks < Rake::TaskLib # :nodoc:
+  def initialize(gem)
+    super()
+    @gem = gem
+    define
+  end
+
+  private def define
+    RuboCop::RakeTask.new
+
+    # Run rubycritic in a shell to prevent it from exiting the rake process
+    task :rubycritic do
+      paths = []
+      paths << "exe" if Dir.exist?("exe")
+      paths << "lib" if Dir.exist?("lib")
+      paths << "sig" if Dir.exist?("sig")
+      sh "bundle exec rubycritic --no-browser #{paths.join(' ')}" unless paths.empty?
+    end
+
+    Inch::Rake::Suggest.new("doc:suggest", "exe/**/*.rb", "lib/**/*.rb", "sig/**/*.rbs") do |suggest|
+      suggest.args << ""
+    end
+
+    namespace :lint do
+      task :safe_rdoc_coverage do
+        if Rake::Task.task_defined?("rdoc:coverage")
+          sh "bundle exec rake rdoc:coverage"
+        else
+          puts "rdoc:coverage task not defined, skipping"
+        end
+      end
+
+      desc "Check that every locked gem installs on the oldest supported Ruby"
+      task :lockfile_ruby do
+        require_relative "lint/gem_lockfile"
+        require_relative "lint/supported_rubies"
+
+        GemLockfile.new(specs: Bundler.load.specs.to_a).verify(SupportedRubies.of(@gem.spec).oldest)
+      end
+
+      # Build dynamic task lists based on what's available
+      docs_tasks = %w[rubycritic]
+      docs_tasks.unshift("autodoc") if Rake::Task.task_defined?("autodoc")
+      docs_tasks << "safe_rdoc_coverage" if Rake::Task.task_defined?("rdoc:coverage")
+
+      code_tasks = %w[rubocop rubycritic lockfile_ruby]
+      code_tasks += %w[cargo:fmt cargo:clippy cargo:test] if Dir.exist?("ext")
+
+      task docs: docs_tasks
+      task code: code_tasks
+      task all: %w[docs code]
+
+      namespace :fix do
+        desc "Auto-fix RuboCop offenses (most aggressive)"
+        task :rubocop do
+          sh "bundle exec rubocop --autocorrect-all"
+        end
+
+        if Dir.exist?("ext")
+          desc "Auto-fix Clippy warnings (most aggressive: --fix --allow-dirty --allow-staged)"
+          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
+
+        # Build dynamic fix:all task
+        fix_all_tasks = %w[lint:fix:rubocop]
+        fix_all_tasks.insert(1, "lint:fix:clippy") if Dir.exist?("ext")
+
+        desc "Run all auto-fix tasks"
+        task all: fix_all_tasks
+      end
+    end
+
+    desc "Run all lint auto-fix tasks"
+    task("lint:fix") { Rake::Task["lint:fix:all"].invoke }
+
+    # Aliases for convenience
+    task "rubocop:autocorrect_all" => "lint:fix:rubocop"
+
+    desc "Run all lint tasks"
+    task(:lint) { Rake::Task["lint:all"].invoke }
+  end
+end

data/lib/ratatui_ruby/devtools/tasks/release/platform_gem.rb

@@ -17,21 +17,20 @@ require_relative "versioned_binary"
 # A PlatformGem collects those binaries and packages them into a single
 # installable gem that serves all supported Ruby versions.
 class PlatformGem
-  # Loads the gemspec and scans for compiled binaries.
-  def initialize(
-    spec = Gem::Specification.load(RatatuiRuby::Devtools.gemspec_file),
-    lib_dir = "lib/#{RatatuiRuby::Devtools.gem_name.tr('-', '_')}"
-  )
-    @spec = spec
-    @lib_dir = lib_dir
-    @binaries = VersionedBinary.scan(lib_dir, RatatuiRuby::Devtools.gem_name)
+  # Scans the gem's library for compiled binaries.
+  #
+  # [gem] The RubyGem to package.
+  def initialize(gem)
+    @spec = gem.spec
+    @lib_dir = "lib/#{gem.name.tr('-', '_')}"
+    @binaries = VersionedBinary.scan(@lib_dir, gem.name)
   end
 
   # Packages the platform gem into +pkg/+.
   def build
     abort "No versioned binaries found in #{@lib_dir}/*/" if @binaries.empty?
 
-    @spec.platform = Gem::Platform.local
+    @spec.platform = platform
     @spec.extensions.clear
     @spec.files += @binaries.map(&:path)
 
@@ -56,8 +55,18 @@ class PlatformGem
     FileUtils.mv(gem_file, "pkg")
     puts "Built pkg/#{File.basename(gem_file)}"
   end
-end
 
-if $PROGRAM_NAME == __FILE__
-  PlatformGem.new.build
+  # The platform of the packaging Ruby, without a darwin version.
+  #
+  # RubyGems installs an <tt>arm64-darwin-23</tt> gem only on a Ruby that
+  # reports exactly darwin 23. That number names the CI image's macOS, not
+  # anything the binary needs. The binary targets macOS 11, the first
+  # release on Apple Silicon, so <tt>arm64-darwin</tt> fits every Mac
+  # that can run it.
+  private def platform
+    local = Gem::Platform.local
+    return local unless local.os == "darwin"
+
+    Gem::Platform.new([local.cpu, local.os, nil])
+  end
 end

data/lib/ratatui_ruby/devtools/tasks/release/versioned_binary.rb

@@ -11,7 +11,7 @@ require_relative "../bump/sem_ver"
 class VersionedBinary < Data.define(:path)
   ##
   # Returns sorted VersionedBinary instances found under +lib_dir+.
-  def self.scan(lib_dir, gem_name = RatatuiRuby::Devtools.gem_name)
+  def self.scan(lib_dir, gem_name)
     Dir.glob("#{lib_dir}/*/#{gem_name.tr('-', '_')}.*")
       .reject { |p| p.end_with?(".rb") }
       .map { |p| new(path: p) }

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

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: AGPL-3.0-or-later
+#++
+
+require "rake/tasklib"
+
+require_relative "bump/repository"
+require_relative "release/platform_gem"
+
+# The tasks that release a gem and its native gems.
+class ReleaseTasks < Rake::TaskLib # :nodoc:
+  def initialize(gem, repository: Repository.new)
+    super()
+    @gem = gem
+    @repository = repository
+    define
+  end
+
+  private def define
+    namespace :release do
+      desc "Package the precompiled binaries in lib/ into a platform gem"
+      task :platform_gem do
+        PlatformGem.new(@gem).build
+      end
+
+      desc "Update stable branch to match release and set as default"
+      task :update_stable do
+        version = @gem.release_version
+
+        # A release that failed leaves the version file ahead of the tags, and
+        # stable would then point at the wrong version.
+        latest_tag = @repository.latest_tag
+        if latest_tag != version.to_tag
+          abort "Fatal: Version mismatch! '#{@gem.version_file}' says #{version.to_tag}, " \
+            "but the latest git tag is #{latest_tag}."
+        end
+
+        stable = @gem.stable_version(@repository)
+        if stable && version.to_gem_version <= stable
+          puts "Skipping stable update: #{version} is not newer than current stable #{stable}"
+          next
+        end
+
+        puts "Updating stable branch to point to #{version.to_tag}..."
+        @repository.move_stable(@repository.released_commit(version.to_tag))
+      end
+    end
+
+    if Rake::Task.task_defined?("release")
+      release = Rake::Task["release"]
+
+      # Bundler tags and publishes in the release task's prerequisites, so a
+      # version its tag can't name has to stop the release before they run.
+      task "release:check_version" do
+        @gem.release_version
+      end
+      release.prerequisites.unshift("release:check_version")
+
+      release.enhance do
+        version = @gem.release_version
+
+        # Bundler tags the release v plus the version as RubyGems writes it, so
+        # a prerelease gets a tag like v1.0.0.pre.beta.1 that isn't SemVer.
+        normalized_tag = "v#{version.to_gem_version}"
+        if normalized_tag != version.to_tag
+          puts "Replacing normalized tag #{normalized_tag} with semver tag #{version.to_tag}..."
+          @repository.delete_tag(normalized_tag)
+          @repository.tag_head(version.to_tag)
+        end
+
+        @gem.crate.release_native_gems(version: version.to_s, sha: @repository.released_commit(version.to_tag))
+
+        Rake::Task["release:update_stable"].invoke
+      end
+    end
+  end
+end

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

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: AGPL-3.0-or-later
+#++
+
+require "rake/tasklib"
+
+require_relative "bump/repository"
+require_relative "license/reuse_tool"
+require_relative "license/unlicensed_files"
+
+# The tasks that check and fix REUSE compliance.
+class ReuseTasks < Rake::TaskLib # :nodoc:
+  def initialize(licensing)
+    super()
+    @licensing = licensing
+    define
+  end
+
+  private def define
+    namespace :reuse do
+      desc "Run the REUSE Tool to confirm REUSE compliance"
+      task :lint do
+        sh "reuse lint"
+      end
+
+      desc "Add SPDX headers to files missing them (per AGENTS.md standards)"
+      task :fix do
+        puts "Checking for files missing REUSE headers..."
+        overrides = ENV.slice("REUSE_COPYRIGHT", "REUSE_CODE_LICENSE", "REUSE_DOC_LICENSE")
+        UnlicensedFiles.new(ReuseTool.new, Repository.new, overrides, @licensing).license.each { |message| puts message }
+      end
+    end
+
+    task(:reuse) { Rake::Task["reuse:lint"].invoke }
+  end
+end

data/lib/ratatui_ruby/devtools/tasks/{test.rake → test_tasks.rb}

@@ -5,14 +5,23 @@
 # SPDX-License-Identifier: AGPL-3.0-or-later
 #++
 
+require "rake/tasklib"
+require "minitest/test_task"
+
 # Minitest task for pure Ruby gems.
 #
 # Consumer gems need test running. This provides a simple Minitest::TestTask
 # that discovers tests in the standard locations. Gems with Rust extensions
 # should define their own test task that includes cargo:test.
+class TestTasks < Rake::TaskLib # :nodoc:
+  def initialize
+    super
+    define
+  end
 
-require "minitest/test_task"
-
-Minitest::TestTask.create(:test) do |t|
-  t.test_globs = ["test/**/*_test.rb", "test/**/test_*.rb"]
+  private def define
+    Minitest::TestTask.create(:test) do |t|
+      t.test_globs = ["test/**/*_test.rb", "test/**/test_*.rb"]
+    end
+  end
 end