ratatui_ruby-devtools 0.2.1 → 0.4.0

data/lib/ratatui_ruby/devtools/tasks/license/blame.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
+#++
+
+require "date"
+require "open3"
+require_relative "contribution"
+
+# Who last touched each line of a file. Given +contents+, it blames that text
+# against the file's history instead of what's on disk, so line numbers can
+# refer to lines that are about to be written.
+#
+# Only commit authors count. Co-Authored-By trailers credit AI tools, which
+# can't hold copyright, and people whose idea a commit took up without their
+# code; git history already credits both.
+#
+# Commits listed in .git-blame-ignore-revs count for no one, so a change too
+# small to hold copyright, such as a corrected path, adds no notice. Git reads
+# that file only when each contributor configures it, so blame names it here.
+class Blame < Data.define(:path, :contents) # :nodoc:
+  UNCOMMITTED = "0" * 40
+  IGNORE_REVS = ".git-blame-ignore-revs"
+
+  def initialize(path:, contents: nil)
+    super
+  end
+
+  # Each author once, with the latest year they touched the lines.
+  # [line_ranges] Pairs of first and last line numbers, counting from 1.
+  #   Omit them to blame the whole file.
+  # [uncommitted_by] The author to credit, this year, for lines not yet
+  #   committed. Without one, those lines count for nobody.
+  def contributions(line_ranges = nil, uncommitted_by: nil)
+    found = (line_ranges || [nil]).flat_map { |range| contributions_in(range, uncommitted_by) }
+    found.group_by(&:author).map { |_, same| same.max_by(&:year) }
+  end
+
+  private def contributions_in(range, uncommitted_by)
+    # A file git doesn't track yet is uncommitted throughout.
+    commits = commits_in(range) || { UNCOMMITTED => {} }
+    commits.flat_map do |commit, author|
+      if commit == UNCOMMITTED
+        next [] unless uncommitted_by
+
+        next [Contribution.new(author: uncommitted_by, year: Date.today.year)]
+      end
+
+      next [] unless author[:name] && author[:email]
+
+      year = author[:year] || Date.today.year
+      [Contribution.new(author: Repository::Author.new(name: author[:name].strip, email: author[:email].strip), year:)]
+    end
+  end
+
+  private def commits_in(range)
+    command = %w[git blame --porcelain]
+    command += ["-L", range.join(",")] if range
+    command += ["--contents", "-"] if contents
+    command += ["--ignore-revs-file", IGNORE_REVS] if File.exist?(IGNORE_REVS)
+    output, status = Open3.capture2(*command, "--", path, stdin_data: contents.to_s, err: File::NULL)
+    return unless status.success?
+
+    commits = {}
+    commit = nil
+    output.each_line do |line|
+      case line
+      when /^([a-f0-9]{40})/ then commit = $1
+      when /^author (.+)$/ then (commits[commit] ||= {})[:name] = $1
+      when /^author-mail <(.+)>$/ then (commits[commit] ||= {})[:email] = $1
+      when /^author-time (\d+)$/ then (commits[commit] ||= {})[:year] = Time.at($1.to_i).year
+      end
+    end
+    commits
+  end
+end

data/lib/ratatui_ruby/devtools/tasks/license/changed_files.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_relative "../bump/repository"
+require_relative "markdown_files"
+require_relative "rbs_files"
+require_relative "ruby_files"
+require_relative "rust_files"
+
+class ChangedFiles < Data.define(:repository, :licensing) # :nodoc:
+  # Licenses what changed and says what it did.
+  def license
+    languages = [
+      MarkdownFiles.changed(repository),
+      RubyFiles.changed(repository, licensing),
+      RbsFiles.changed(repository, licensing),
+      RustFiles.changed(repository, licensing),
+    ]
+    changed = languages.reject { |language| language.count.zero? }
+    return ["No changed #{sentence(languages.map(&:label))} files to process"] if changed.empty?
+
+    changed.flat_map do |language|
+      ["Processing #{language.count} changed #{language.label} file(s)...", *language.license]
+    end
+  end
+
+  private def sentence(words)
+    "#{words[0...-1].join(', ')}, or #{words.last}"
+  end
+end

data/lib/ratatui_ruby/devtools/tasks/license/contribution.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
+#++
+
+require_relative "../bump/repository"
+
+# An author's work on a file, as of the latest year they touched it.
+class Contribution < Data.define(:author, :year) # :nodoc:
+end

data/lib/ratatui_ruby/devtools/tasks/license/copyright.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 "date"
+require_relative "renewal"
+
+class Copyright < Data.define(:year, :holder) # :nodoc:
+  def self.of(contribution)
+    new(year: contribution.year, holder: contribution.author.to_s)
+  end
+
+  # For work with no history to credit, such as an empty file.
+  def self.yours(author)
+    new(year: Date.today.year, holder: author.to_s)
+  end
+
+  # A holder matches an author when any word of the holder appears in the
+  # author's name and email, so "Jane Doe <...>" matches either name.
+  def self.latest_year(contributions, words)
+    contributions.select { |contribution| words.any? { |word| contribution.author.to_s.include?(word) } }
+      .map(&:year).max
+  end
+
+  def held_by?(author)
+    [author.name, author.email].any? { |identifier| holder.include?(identifier) }
+  end
+
+  # Git can know less than the notice does, as when history was rewritten or
+  # the work came from elsewhere.
+  def renewal(contributions)
+    latest_year = self.class.latest_year(contributions, holder.split)
+    return Renewal.unchanged(self) unless latest_year && latest_year > year
+
+    Renewal.new(
+      value: with(year: latest_year),
+      notices: ["Updated #{holder.split.first}'s copyright year: #{year} -> #{latest_year}"]
+    )
+  end
+
+  def to_s
+    "#{year} #{holder}"
+  end
+end

data/lib/ratatui_ruby/devtools/tasks/license/directory_licensing.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 "blame"
+require_relative "licensing"
+
+# Source code takes its license from where it lives, and everything below its
+# license header counts toward an author's copyright year.
+module DirectoryLicensing # :nodoc:
+  def initialize(licensing)
+    @licensing = licensing
+  end
+
+  def covers?(path)
+    extensions.include?(File.extname(path).delete_prefix(".")) &&
+      directories.any? { |directory| path.start_with?("#{directory}/") }
+  end
+
+  def tracked_patterns
+    directories.flat_map do |directory|
+      extensions.flat_map { |extension| ["#{directory}/*.#{extension}", "#{directory}/**/*.#{extension}"] }
+    end
+  end
+
+  def license_for(path)
+    @licensing.license_for(path)
+  end
+
+  # Editing the license header, as when relicensing, isn't authorship of the
+  # file.
+  def contributions(path, lines, author)
+    Blame.new(path).contributions(header_in(lines).blame_ranges(lines), uncommitted_by: author)
+  end
+
+  private def after_header(lines, end_line)
+    lines.drop(end_line + 1).drop_while { |line| line.strip.empty? }
+  end
+end

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

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: AGPL-3.0-or-later
+#++
+
+# A file's license header, ending on +end_line+ counting from 0.
+class ExistingHeader < Data.define(:header, :end_line) # :nodoc:
+  def revise(revision)
+    renewal = header.renewal(revision.contributions, revision.license)
+    revision.replace(renewal, end_line) if renewal.changed?
+  end
+
+  # The lines below the header, as git blame counts them, from 1.
+  def blame_ranges(lines)
+    return [] if end_line + 1 >= lines.length
+
+    [[end_line + 2, lines.length]]
+  end
+end

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

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: AGPL-3.0-or-later
+#++
+
+require_relative "spdx_header"
+
+# One file's license header brought up to date: the header the file has asks
+# to be replaced, or the one it lacks asks to be added.
+class HeaderRevision # :nodoc:
+  attr_reader :text
+
+  def initialize(path:, lines:, syntax:, author:)
+    @path = path
+    @lines = lines
+    @syntax = syntax
+    @author = author
+    @messages = []
+  end
+
+  def contributions
+    @contributions ||= @syntax.contributions(@path, @lines, @author)
+  end
+
+  def license
+    @syntax.license_for(@path)
+  end
+
+  def replace(renewal, end_line)
+    @text = @syntax.replaced(renewal.value, @lines, end_line)
+    @messages = [*renewal.notices.map { |notice| "  #{notice}" }, "Updated: #{@path}"]
+  end
+
+  def add
+    @text = @syntax.added(SpdxHeader.of(@author, contributions, license), @lines)
+    @messages = ["Added header: #{@path}"]
+  end
+
+  # What the revision did, for whoever ran it.
+  def messages
+    @messages.dup
+  end
+end

data/lib/ratatui_ruby/devtools/tasks/license/licensed_file.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 "../bump/repository"
+require_relative "header_revision"
+
+class LicensedFile < Data.define(:path, :syntax, :author) # :nodoc:
+  def self.changed(syntax, repository: Repository.new)
+    of(repository.changed_files.select { |path| syntax.covers?(path) }, syntax, repository)
+  end
+
+  def self.tracked(paths, syntax, repository: Repository.new)
+    of(repository.tracked_files_for(paths, syntax), syntax, repository)
+  end
+
+  # Asking git for the author only when there are files keeps a run with
+  # nothing to annotate working where git has no identity, as in CI.
+  private_class_method def self.of(files, syntax, repository)
+    return [] if files.empty?
+
+    author = repository.author
+    files.map { |file| new(path: file, syntax:, author:) }
+  end
+
+  # Brings the file's header 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.
+    lines = File.read(path, mode: "rb", encoding: "UTF-8").lines
+    revision = HeaderRevision.new(path:, lines:, syntax:, author:)
+    syntax.header_in(lines).revise(revision)
+    File.write(path, revision.text, mode: "wb") if revision.text
+    revision.messages
+  end
+end

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

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: AGPL-3.0-or-later
+#++
+
+require "rubygems"
+
+# The gem's own license is about linking, and an app links only the code it
+# requires and the extensions it compiles. Code a gem treats as a large
+# snippet is free to copy, like the snippets in its docs.
+class Licensing < Data.define(:snippets, :linked, :runtime, :non_runtime) # :nodoc:
+  SNIPPET = "MIT-0"
+
+  def self.of(spec, snippets:, non_runtime:)
+    new(
+      snippets:,
+      linked: [*spec.require_paths, *spec.extensions.map { |extension| File.dirname(extension) }]
+        .map { |directory| "#{directory}/" },
+      runtime: spec.licenses.join(" OR "),
+      non_runtime:
+    )
+  end
+
+  def license_for(path)
+    if path.start_with?(*snippets)
+      SNIPPET
+    elsif path.start_with?(*linked)
+      runtime
+    else
+      non_runtime
+    end
+  end
+end

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

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: AGPL-3.0-or-later
+#++
+
+class MarkdownDocument < Data.define(:lines) # :nodoc:
+  FENCE = /^(````*)\w*$/
+
+  def fence?(index)
+    lines[index].match?(FENCE)
+  end
+
+  # The line that closes the fence opening at +index+, when one does.
+  def fence_end(index)
+    marker = lines[index][FENCE, 1]
+    return unless marker
+
+    closing = /^#{Regexp.escape(marker)}$/
+    (index + 1).upto(lines.length - 1).find { |later| lines[later].match?(closing) }
+  end
+end

data/lib/ratatui_ruby/devtools/tasks/license/markdown_files.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 "licensed_file"
+require_relative "markdown_header_syntax"
+require_relative "markdown_snippet_syntax"
+require_relative "snippet_file"
+
+class MarkdownFiles < Data.define(:files) # :nodoc:
+  def self.changed(repository)
+    new(files: LicensedFile.changed(MarkdownHeaderSyntax.new, repository:))
+  end
+
+  def label
+    "Markdown"
+  end
+
+  def count
+    files.count
+  end
+
+  def license
+    syntax = MarkdownSnippetSyntax.new
+    files.flat_map(&:annotate) +
+      files.flat_map { |file| SnippetFile.new(path: file.path, syntax:, author: file.author).annotate }
+  end
+end

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

@@ -0,0 +1,104 @@
+# 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"
+require_relative "existing_header"
+require_relative "markdown_document"
+require_relative "missing_header"
+require_relative "spdx_header"
+
+class MarkdownHeaderSyntax # :nodoc:
+  LICENSE = "CC-BY-SA-4.0"
+  # REUSE-IgnoreStart
+  COPYRIGHT = /SPDX-FileCopyrightText:\s*(\d{4})\s+(.+)$/
+  LICENSE_LINE = /SPDX-License-Identifier:\s*(.+)$/
+  # REUSE-IgnoreEnd
+
+  def extensions
+    %w[md]
+  end
+
+  def covers?(path)
+    path.end_with?(".md")
+  end
+
+  def tracked_patterns
+    ["*.md"]
+  end
+
+  def license_for(_path)
+    LICENSE
+  end
+
+  # Code blocks hold examples rather than prose, so only prose lines count
+  # toward who wrote the document and when.
+  def contributions(path, lines, author)
+    Blame.new(path).contributions(prose_ranges(lines), uncommitted_by: author)
+  end
+
+  def header_in(lines)
+    closing = comment_end(lines)
+    return MissingHeader.new unless closing
+
+    comment = lines[..closing]
+    copyrights = comment.grep(COPYRIGHT) { Copyright.new(year: $1.to_i, holder: $2.strip) }
+    license = comment.grep(LICENSE_LINE) { $1.strip }.last
+    return MissingHeader.new unless copyrights.any? || license
+
+    ExistingHeader.new(header: SpdxHeader.new(copyrights:, license:), end_line: closing)
+  end
+
+  def added(header, lines)
+    "#{block(header)}#{lines.join}"
+  end
+
+  def replaced(header, lines, end_line)
+    "#{block(header)}#{lines.drop(end_line + 1).join}"
+  end
+
+  private def block(header)
+    "<!--\n#{header.commented(' ')}-->\n"
+  end
+
+  # Line ranges counting from 1, between the header and each code block.
+  private def prose_ranges(lines)
+    start = header_length(lines)
+    ranges = []
+    code_blocks(lines).each do |first, last|
+      ranges << [start + 1, first] if start < first
+      start = last + 1
+    end
+    ranges << [start + 1, lines.length] if start < lines.length
+    ranges
+  end
+
+  private def header_length(lines)
+    closing = comment_end(lines)
+    closing ? closing + 1 : 0
+  end
+
+  # The index of the line closing a comment that opens the file.
+  private def comment_end(lines)
+    lines.index { |line| line.include?("-->") } if lines.first&.include?("<!--")
+  end
+
+  private def code_blocks(lines)
+    document = MarkdownDocument.new(lines)
+    blocks = []
+    index = 0
+    while index < lines.length
+      closing = document.fence_end(index)
+      if closing
+        blocks << [index, closing]
+        index = closing
+      end
+      index += 1
+    end
+    blocks
+  end
+end

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

@@ -0,0 +1,159 @@
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: AGPL-3.0-or-later
+#++
+
+require_relative "markdown_document"
+require_relative "snippet"
+require_relative "snippet_opening"
+require_relative "wrapped_snippet"
+
+# Fenced code blocks, and the code synced into a README between SYNC markers,
+# which the wrapper goes around so syncing doesn't erase it.
+class MarkdownSnippetSyntax # :nodoc:
+  LICENSE = "MIT-0"
+  SYNC_START = /<!--\s*SYNC:START/
+  SYNC_END = /<!--\s*SYNC:END/
+
+  def extensions
+    %w[md]
+  end
+
+  def tracked_patterns
+    ["*.md"]
+  end
+
+  def license
+    LICENSE
+  end
+
+  # Without the wrappers that don't license their code MIT-0, so the code they
+  # held can be wrapped again, and with the copyright notices of the rest
+  # under the snippet tag.
+  def cleaned(lines)
+    _, removals = scan(lines, first_pass: true)
+    lines = lines.dup
+    removals.sort_by { |first, _| -first }.each do |first, last|
+      lines.delete_at(last)
+      (opening_end(lines, first) - first + 1).times { lines.delete_at(first) }
+    end
+    lines.each_index.select { |index| lines[index].include?("SPDX-SnippetBegin") }.each do |first|
+      first.upto(opening_end(lines, first)) { |index| lines[index] = Snippet.tag(lines[index]) }
+    end
+    lines
+  end
+
+  def snippets_in(lines)
+    regions, = scan(lines, first_pass: false)
+    regions
+  end
+
+  def opening(_snippet, copyrights)
+    # REUSE-IgnoreStart
+    [
+      "<!-- SPDX-SnippetBegin -->\n",
+      "<!--\n",
+      *copyrights.map { |copyright| "  #{Snippet::COPYRIGHT_TAG}: #{copyright}\n" },
+      "  SPDX-License-Identifier: #{LICENSE}\n",
+      "-->\n",
+    ]
+    # REUSE-IgnoreEnd
+  end
+
+  def closing(_snippet)
+    # REUSE-IgnoreStart
+    ["<!-- SPDX-SnippetEnd -->\n"]
+    # REUSE-IgnoreEnd
+  end
+
+  # The last line of the opening wrapper at +first+. A SnippetBegin comment
+  # that closes on its own line is followed by the comment holding the SPDX
+  # tags, which goes with it.
+  private def opening_end(lines, first)
+    start = tags_follow?(lines, first) ? first + 1 : first
+    start.upto(lines.length - 1).find { |index| lines[index].include?("-->") } || (lines.length - 1)
+  end
+
+  private def tags_follow?(lines, first)
+    lines[first].include?("-->") && lines[first + 1]&.include?("<!--")
+  end
+
+  # A wrapper from its SnippetBegin to its SnippetEnd, with the code between
+  # its opening tags and its end.
+  private def wrapped_region(lines, first, finish)
+    opening = SnippetOpening.in(lines, first, opening_end(lines, first))
+    return if opening.last + 1 > finish - 1
+
+    WrappedSnippet.new(snippet: Snippet.around(first, finish, code: [opening.last + 1, finish - 1]), opening:)
+  end
+
+  # The first pass leaves MIT-0 wrappers alone and marks the rest for
+  # removal. The second, after removal, reports the wrappers left with their
+  # openings.
+  private def scan(lines, first_pass:)
+    document = MarkdownDocument.new(lines)
+    regions = []
+    removals = []
+    index = 0
+    while index < lines.length
+      if lines[index].include?("SPDX-SnippetBegin")
+        finish = index.upto(lines.length - 1).find { |later| lines[later].include?("SPDX-SnippetEnd") }
+        if !first_pass
+          wrapped = wrapped_region(lines, index, finish) if finish
+          regions << wrapped if wrapped
+          index = (finish || lines.length) + 1
+          next
+        elsif finish
+          removals << [index, finish] unless licensed?(lines, index)
+          index = finish + 1
+          next
+        end
+      end
+
+      region = sync_region(lines, document, index) || fence_region(document, index)
+      if region
+        regions << region
+        index = region.last + 1
+      else
+        index += 1
+      end
+    end
+    [regions, removals]
+  end
+
+  private def sync_region(lines, document, start)
+    return unless lines[start].match?(SYNC_START)
+
+    code_start = code_end = finish = nil
+    (start + 1).upto(lines.length - 1) do |later|
+      if document.fence?(later)
+        if code_start
+          code_end = later
+        else
+          code_start = later
+        end
+      elsif lines[later].match?(SYNC_END)
+        finish = later
+        break
+      end
+    end
+    Snippet.around(start, finish, code: [code_start, code_end]) if code_start && code_end && finish
+  end
+
+  private def fence_region(document, start)
+    finish = document.fence_end(start)
+    Snippet.around(start, finish) if finish
+  end
+
+  # A wrapper that already credits someone under MIT-0 stays, whoever it
+  # credits.
+  private def licensed?(lines, begin_line)
+    tags = lines[(begin_line + 1)..].take_while { |line| !line.include?("-->") }
+    # REUSE-IgnoreStart
+    tags.any? { |line| line.include?(Snippet::COPYRIGHT_TAG) || line.include?(Snippet::FILE_COPYRIGHT_TAG) } &&
+      tags.any? { |line| line.include?(LICENSE) && line.include?("SPDX-License-Identifier") }
+    # REUSE-IgnoreEnd
+  end
+end