ratatui_ruby-devtools 0.2.0 → 0.3.0

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

@@ -0,0 +1,27 @@
+# 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 "rbs_header_syntax"
+
+class RbsFiles < Data.define(:files) # :nodoc:
+  def self.changed(repository, licensing)
+    new(files: LicensedFile.changed(RbsHeaderSyntax.new(licensing), repository:))
+  end
+
+  def label
+    "RBS"
+  end
+
+  def count
+    files.count
+  end
+
+  def license
+    files.flat_map(&:annotate)
+  end
+end

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

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: AGPL-3.0-or-later
+#++
+
+require_relative "directory_licensing"
+require_relative "ruby_comment_header"
+
+# RBS has no magic comments, so its header opens the file.
+class RbsHeaderSyntax # :nodoc:
+  include DirectoryLicensing
+  include RubyCommentHeader
+
+  def extensions
+    %w[rbs]
+  end
+
+  def directories
+    %w[sig]
+  end
+
+  def added(header, lines)
+    "#{block(header)}\n#{lines.drop_while { |line| line.strip.empty? }.join}"
+  end
+
+  def replaced(header, lines, end_line)
+    "#{block(header)}\n#{after_header(lines, end_line).join}"
+  end
+end

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

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: AGPL-3.0-or-later
+#++
+
+require "rdoc"
+require_relative "rdoc_examples"
+require_relative "snippet"
+
+# A run of comment lines, read the way RDoc reads it. Indentation alone
+# doesn't make an example: a list item's continuation and a call-seq are
+# indented too, and blank lines after an example aren't part of it.
+class RdocComment < Data.define(:first, :prefix, :lines) # :nodoc:
+  def self.all_in(file_lines)
+    file_lines.each_with_index
+      .select { |line, _| prefix_of(line) }
+      .chunk_while { |(line, index), (other, other_index)| other_index == index + 1 && prefix_of(other) == prefix_of(line) }
+      .map { |run| new(first: run.first.last, prefix: prefix_of(run.first.first), lines: run.map(&:first)) }
+  end
+
+  def self.prefix_of(line)
+    line[/\A(\s*)#/, 1]
+  end
+
+  # RDoc's markup carries no line numbers, and its own steps drop lines on
+  # the way, so each example is found again by all of its lines.
+  def examples
+    cursor = 0
+    RDoc::Markup.parse(markup).accept(RdocExamples.new).filter_map do |verbatim|
+      code = verbatim.text.lines.map(&:strip)
+      start = cursor.upto(lines.length - code.length).find { |index| code_at?(index, code) }
+      next unless start
+
+      cursor = start + code.length
+      Snippet.around(first + start, first + cursor - 1, prefix:)
+    end
+  end
+
+  # An :include: directive names a file RDoc would read in, but it holds no
+  # example from this one.
+  private def markup
+    text, = RDoc::Comment.parse(lines.map { |line| line.delete_prefix(prefix) }.join, nil, first, :ruby) { "" }
+    text
+  end
+
+  private def code_at?(index, code)
+    lines[index, code.length].map { |line| line.sub(/\A\s*#+/, "").strip } == code
+  end
+end

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

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: AGPL-3.0-or-later
+#++
+
+require "rdoc"
+
+# The code blocks of an RDoc document, wherever they sit, as RDoc's own
+# table of contents collects its headings.
+class RdocExamples < RDoc::Markup::Formatter # :nodoc:
+  def start_accepting
+    @examples = []
+  end
+
+  def end_accepting
+    @examples
+  end
+
+  def accept_verbatim(verbatim)
+    @examples << verbatim
+  end
+
+  def ignore(*)
+  end
+
+  alias accept_block_quote ignore
+  alias accept_raw ignore
+  alias accept_rule ignore
+  alias accept_blank_line ignore
+  alias accept_hard_break ignore
+  alias accept_heading ignore
+  alias accept_paragraph ignore
+  alias accept_indented_paragraph ignore
+  alias accept_list_start ignore
+  alias accept_list_end ignore
+  alias accept_list_item_start ignore
+  alias accept_list_item_end ignore
+  alias accept_table ignore
+end

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

@@ -0,0 +1,119 @@
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: AGPL-3.0-or-later
+#++
+
+require_relative "rdoc_comment"
+require_relative "snippet"
+require_relative "snippet_opening"
+require_relative "wrapped_snippet"
+
+# The SPDX wrapper sits between #-- and #++ so RDoc leaves it out of the
+# docs.
+class RdocSnippetSyntax # :nodoc:
+  LICENSE = "MIT-0"
+
+  def extensions
+    %w[rb]
+  end
+
+  def tracked_patterns
+    ["*.rb"]
+  end
+
+  # Existing wrappers with their copyright notices under the snippet tag,
+  # without the blank lines that once followed their code inside them, and
+  # only around text RDoc shows as code.
+  def cleaned(lines)
+    in_tags = false
+    tagged = lines.map do |line|
+      in_tags = true if line.match?(/^\s*# SPDX-SnippetBegin\s*$/)
+      cleaned_line = in_tags ? Snippet.tag(line) : line
+      in_tags = false if line.match?(/^\s*#\+\+\s*$/)
+      cleaned_line
+    end
+    without_wrappers_around_prose(blanks_after_wrappers(tagged))
+  end
+
+  def license
+    LICENSE
+  end
+
+  # A wrapper marks its own snippet, whatever RDoc makes of the code inside
+  # it. RDoc finds the examples that have no wrapper yet.
+  def snippets_in(lines)
+    wrapped = wrapped_in(lines)
+    bare = examples(lines).reject { |example| wrapped.any? { |snippet| snippet.covers?(example) } }
+    (wrapped + bare).sort_by(&:first)
+  end
+
+  def opening(snippet, copyrights)
+    prefix = snippet.prefix
+    # REUSE-IgnoreStart
+    [
+      "#{prefix}#--\n",
+      "#{prefix}# SPDX-SnippetBegin\n",
+      *copyrights.map { |copyright| "#{prefix}# #{Snippet::COPYRIGHT_TAG}: #{copyright}\n" },
+      "#{prefix}# SPDX-License-Identifier: #{LICENSE}\n",
+      "#{prefix}#++\n",
+    ]
+    # REUSE-IgnoreEnd
+  end
+
+  def closing(snippet)
+    prefix = snippet.prefix
+    # REUSE-IgnoreStart
+    [
+      "#{prefix}#--\n",
+      "#{prefix}# SPDX-SnippetEnd\n",
+      "#{prefix}#++\n",
+    ]
+    # REUSE-IgnoreEnd
+  end
+
+  private def examples(lines)
+    RdocComment.all_in(lines).flat_map(&:examples)
+  end
+
+  # The code between each SnippetBegin's #++ and its SnippetEnd's #--.
+  private def wrapped_in(lines)
+    lines.each_index.filter_map do |index|
+      next unless lines[index].match?(/^\s*# SPDX-SnippetBegin\s*$/)
+
+      prefix = lines[index][/\A\s*/]
+      opened = (index + 1).upto(lines.length - 1).find { |line| lines[line].match?(/^#{Regexp.escape(prefix)}#\+\+\s*$/) }
+      ended = opened && (opened + 1).upto(lines.length - 1).find { |line| lines[line].match?(/^\s*# SPDX-SnippetEnd\s*$/) }
+      next unless ended && ended - 2 > opened
+
+      snippet = Snippet.around(opened + 1, ended - 2, prefix:)
+      WrappedSnippet.new(snippet:, opening: SnippetOpening.in(lines, index - 1, opened))
+    end
+  end
+
+  # Wrappers once went around every indented comment, list items' text
+  # included. A wrapper whose lines RDoc shows as prose comes off.
+  private def without_wrappers_around_prose(lines)
+    code = examples(lines).map(&:first)
+    prose = wrapped_in(lines).reject { |wrapped| code.include?(wrapped.first) }
+    prose.reverse_each.with_object(lines.dup) do |wrapped, unwrapped|
+      ended = wrapped.snippet.last + 1
+      unwrapped.slice!(ended..(ended + 2))
+      unwrapped.slice!(wrapped.opening.span)
+    end
+  end
+
+  # Blank comment lines after an example aren't part of it, as RDoc reads it.
+  private def blanks_after_wrappers(lines)
+    lines = lines.dup
+    lines.each_index do |index|
+      next unless lines[index].match?(/^\s*#--\s*$/) && lines[index + 1]&.match?(/^\s*# SPDX-SnippetEnd\s*$/)
+
+      first_blank = index
+      first_blank -= 1 while first_blank.positive? && lines[first_blank - 1].match?(/^\s*#\s*$/)
+      lines.insert(first_blank + 3, *lines.slice!(first_blank...index)) if first_blank < index
+    end
+    lines
+  end
+end

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

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: AGPL-3.0-or-later
+#++
+
+# Something brought up to date, with a notice for each change made to it.
+class Renewal < Data.define(:value, :notices) # :nodoc:
+  def self.unchanged(value)
+    new(value:, notices: [])
+  end
+
+  def changed?
+    notices.any?
+  end
+end

data/lib/ratatui_ruby/devtools/tasks/license/reuse_annotated_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 ReuseAnnotatedFile < Data.define(:path, :license, :copyright, :tool) # :nodoc:
+  def annotate
+    ["Annotating #{path} with #{license}", *tool.annotate(path, license:, copyright:)]
+  end
+end

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

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: AGPL-3.0-or-later
+#++
+
+require "open3"
+
+class ReuseTool # :nodoc:
+  # The lint report lists files with no copyright and licensing information
+  # under a heading of their own, up to the next heading.
+  def unlicensed_paths
+    listed = false
+    `reuse lint 2>&1`.lines.filter_map do |line|
+      listed = true if line.include?("no copyright and licensing")
+      listed = false if line.start_with?("# ") && !line.include?("copyright")
+      # On Windows the tool reports paths with backslashes.
+      line[/^\* (.+)/, 1]&.tr("\\", "/") if listed
+    end
+  end
+
+  # Lockfiles and plain text have no comments to hold a header, so they get
+  # a .license file beside them.
+  def annotate(path, license:, copyright:)
+    output, status = Open3.capture2e(
+      "reuse", "annotate", "--license", license, "--copyright", copyright,
+      "--fallback-dot-license", "--skip-existing", path
+    )
+    raise "reuse annotate failed for #{path}:\n#{output}" unless status.success?
+
+    output.lines(chomp: true)
+  end
+end

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

@@ -0,0 +1,49 @@
+# 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 "existing_header"
+require_relative "missing_header"
+require_relative "spdx_header"
+
+# Ruby and RBS share comments, so their headers sit between the same #-- and
+# #++ that keep a Ruby header out of the docs.
+module RubyCommentHeader # :nodoc:
+  # REUSE-IgnoreStart
+  COPYRIGHT = /^#\s*SPDX-FileCopyrightText:\s*(\d{4})\s+(.+)$/
+  LICENSE = /^#\s*SPDX-License-Identifier:\s*(.+)$/
+  # REUSE-IgnoreEnd
+
+  # The header is in the comments the file opens with. Without its #++, it
+  # ends at its last tag.
+  def header_in(lines)
+    copyrights = []
+    license = nil
+    last_tag = nil
+    lines.each_with_index do |line, index|
+      case line
+      when COPYRIGHT
+        copyrights << Copyright.new(year: $1.to_i, holder: $2.strip)
+        last_tag = index
+      when LICENSE
+        license = $1.strip
+        last_tag = index
+      when /^#\+\+\s*$/
+        return ExistingHeader.new(header: SpdxHeader.new(copyrights:, license:), end_line: index) if last_tag
+      when /^\s*[^#\s]/
+        break
+      end
+    end
+    return MissingHeader.new unless last_tag
+
+    ExistingHeader.new(header: SpdxHeader.new(copyrights:, license:), end_line: last_tag)
+  end
+
+  private def block(header)
+    "#--\n#{header.commented('#')}#++\n"
+  end
+end

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

@@ -0,0 +1,36 @@
+# 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 "rdoc_snippet_syntax"
+require_relative "ruby_header_syntax"
+require_relative "snippet_file"
+
+class RubyFiles < Data.define(:files) # :nodoc:
+  def self.changed(repository, licensing)
+    new(files: LicensedFile.changed(RubyHeaderSyntax.new(licensing), repository:))
+  end
+
+  def label
+    "Ruby"
+  end
+
+  def count
+    files.count
+  end
+
+  def license
+    files.flat_map(&:annotate) + library.flat_map(&:annotate)
+  end
+
+  # RDoc examples only appear in the documented library.
+  private def library
+    syntax = RdocSnippetSyntax.new
+    files.select { |file| file.path.start_with?("lib/") && file.path.end_with?(".rb") }
+      .map { |file| SnippetFile.new(path: file.path, syntax:, author: file.author) }
+  end
+end

data/lib/ratatui_ruby/devtools/tasks/license/ruby_header_syntax.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_relative "directory_licensing"
+require_relative "ruby_comment_header"
+
+class RubyHeaderSyntax # :nodoc:
+  include DirectoryLicensing
+  include RubyCommentHeader
+
+  FROZEN_STRING_LITERAL = "# frozen_string_literal: true\n"
+
+  def extensions
+    %w[rb]
+  end
+
+  def directories
+    %w[lib ext test examples tasks bin]
+  end
+
+  def added(header, lines)
+    frozen = frozen_string_literal_in(lines)
+    body = (frozen ? lines.drop(1) : lines).drop_while { |line| line.strip.empty? }
+    "#{frozen || FROZEN_STRING_LITERAL}\n#{block(header)}\n#{body.join}"
+  end
+
+  def replaced(header, lines, end_line)
+    frozen = frozen_string_literal_in(lines)
+    "#{frozen || FROZEN_STRING_LITERAL}\n#{block(header)}\n#{after_header(lines, end_line).join}"
+  end
+
+  private def frozen_string_literal_in(lines)
+    lines.first if lines.first&.include?("frozen_string_literal")
+  end
+end

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

@@ -0,0 +1,27 @@
+# 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 "rust_header_syntax"
+
+class RustFiles < Data.define(:files) # :nodoc:
+  def self.changed(repository, licensing)
+    new(files: LicensedFile.changed(RustHeaderSyntax.new(licensing), repository:))
+  end
+
+  def label
+    "Rust"
+  end
+
+  def count
+    files.count
+  end
+
+  def license
+    files.flat_map(&:annotate)
+  end
+end

data/lib/ratatui_ruby/devtools/tasks/license/rust_header_syntax.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_relative "copyright"
+require_relative "directory_licensing"
+require_relative "existing_header"
+require_relative "missing_header"
+require_relative "spdx_header"
+
+class RustHeaderSyntax # :nodoc:
+  include DirectoryLicensing
+
+  # REUSE-IgnoreStart
+  COPYRIGHT = %r{^//\s*SPDX-FileCopyrightText:\s*(\d{4})\s+(.+)$}
+  LICENSE = %r{^//\s*SPDX-License-Identifier:\s*(.+)$}
+  # REUSE-IgnoreEnd
+
+  def extensions
+    %w[rs]
+  end
+
+  def directories
+    %w[ext]
+  end
+
+  def header_in(lines)
+    copyrights = []
+    license = nil
+    last_tag = nil
+    lines.each_with_index do |line, index|
+      case line
+      when COPYRIGHT
+        copyrights << Copyright.new(year: $1.to_i, holder: $2.strip)
+        last_tag = index
+      when LICENSE
+        license = $1.strip
+        last_tag = index
+      else
+        next if line.start_with?("//")
+        break if license || !line.strip.empty?
+      end
+    end
+    return MissingHeader.new unless last_tag
+
+    ExistingHeader.new(header: SpdxHeader.new(copyrights:, license:), end_line: last_tag)
+  end
+
+  def added(header, lines)
+    "#{header.commented('//')}\n#{lines.join}"
+  end
+
+  def replaced(header, lines, end_line)
+    "#{header.commented('//')}\n#{after_header(lines, end_line).join}"
+  end
+end

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

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: AGPL-3.0-or-later
+#++
+
+# A code example inside a file, wrapped from its first to its last line
+# counting from 0, behind the given comment prefix. Its year comes from the
+# code lines alone, which can sit inside markers the wrapper goes around.
+class Snippet < Data.define(:first, :last, :prefix, :code) # :nodoc:
+  # REUSE 3.3 requires copyright notices inside a snippet to use the snippet
+  # tag. Earlier wrappers used the file tag.
+  # REUSE-IgnoreStart
+  COPYRIGHT_TAG = "SPDX-SnippetCopyrightText"
+  FILE_COPYRIGHT_TAG = "SPDX-FileCopyrightText"
+  # REUSE-IgnoreEnd
+
+  def self.around(first, last, prefix: "", code: [first, last])
+    new(first:, last:, prefix:, code:)
+  end
+
+  # A line of a wrapper's tags, using the snippet copyright tag.
+  def self.tag(line)
+    line.sub(FILE_COPYRIGHT_TAG, COPYRIGHT_TAG)
+  end
+
+  # The code lines as git blame counts them, from 1.
+  def blame_range
+    code.map { |line| line + 1 }
+  end
+
+  def lines_in(file_lines)
+    file_lines[first..last]
+  end
+
+  def bare?
+    true
+  end
+
+  def revise(revision)
+    revision.wrap(self)
+  end
+end

data/lib/ratatui_ruby/devtools/tasks/license/snippet_file.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
+#++
+
+require_relative "../bump/repository"
+require_relative "snippet_revision"
+
+class SnippetFile < Data.define(:path, :syntax, :author) # :nodoc:
+  def self.tracked(paths, syntax, repository: Repository.new)
+    files = repository.tracked_files_for(paths, syntax)
+    return [] if files.empty?
+
+    author = repository.author
+    files.map { |path| new(path:, syntax:, author:) }
+  end
+
+  # Brings the file's snippets up to date and says what changed.
+  def annotate
+    # Binary mode keeps the file's own line endings, which text mode on
+    # Windows would turn into CRLF.
+    text = File.read(path, mode: "rb", encoding: "UTF-8")
+    revision = SnippetRevision.new(path:, text:, syntax:, author:).run
+    File.write(path, revision.text, mode: "wb") if revision.changed?
+    revision.messages
+  end
+end

data/lib/ratatui_ruby/devtools/tasks/license/snippet_opening.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_relative "copyright"
+require_relative "renewal"
+require_relative "spdx_header"
+
+# The tags that open a snippet already wrapped, from their first to their last
+# line counting from 0, with the notices they hold.
+class SnippetOpening < Data.define(:first, :last, :header) # :nodoc:
+  # REUSE-IgnoreStart
+  COPYRIGHT = /SPDX-(?:Snippet|File)CopyrightText:\s*(\d{4})\s+(.+)$/
+  LICENSE = /SPDX-License-Identifier:\s*(\S+)/
+  # REUSE-IgnoreEnd
+
+  def self.in(lines, first, last)
+    tags = lines[first..last]
+    copyrights = tags.grep(COPYRIGHT) { Copyright.new(year: $1.to_i, holder: $2.strip) }
+    license = tags.grep(LICENSE) { $1 }.last
+    new(first:, last:, header: SpdxHeader.new(copyrights:, license:))
+  end
+
+  def span
+    first..last
+  end
+
+  def copyrights
+    header.copyrights
+  end
+
+  def renewal(contributions, license)
+    renewal = header.renewal(contributions, license)
+    Renewal.new(value: with(header: renewal.value), notices: renewal.notices)
+  end
+end