ratatui_ruby-devtools 0.1.0

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

@@ -0,0 +1,143 @@
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: AGPL-3.0-or-later
+#++
+
+# Shared utility for detecting contributors from git blame and Co-Authored-By trailers.
+#
+# This module provides methods to:
+# - Get all contributors (authors and co-authors) who touched specific lines
+# - Track the latest year each contributor touched those lines
+# - Parse Co-Authored-By trailers from commit messages
+
+require "open3"
+require "date"
+
+# Extracts contributor information from git history.
+#
+# License headers need accurate copyright years and contributor names. Git
+# blame provides line-level authorship. Commit messages contain Co-Authored-By
+# trailers. Combining these sources manually is tedious.
+#
+# This module queries git blame and parses commit messages. It returns
+# contributor names with their latest modification years. Use it when
+# generating or updating SPDX headers.
+module LicenseUtils
+  # A contributor with their latest modification year.
+  #
+  # [name] The contributor's display name.
+  # [email] The contributor's email address.
+  # [year] The most recent year they modified the file.
+  Contributor = Data.define(:name, :email, :year)
+
+  class << self
+    # Get all contributors who touched lines in a file (or range of lines).
+    # Returns a Hash of { "Name <email>" => year } mapping each contributor to their latest year.
+    #
+    # This considers both the commit author AND any Co-Authored-By trailers in commit messages.
+    def get_contributors_for_lines(filepath, start_line = nil, end_line = nil)
+      blame_cmd = if start_line && end_line
+        %W[git blame -L #{start_line},#{end_line} --porcelain -- #{filepath}]
+      else
+        %W[git blame --porcelain -- #{filepath}]
+      end
+
+      output, _status = Open3.capture2(*blame_cmd)
+
+      contributors = {}  # "Name <email>" => year
+      commit_cache = {}  # commit_hash => { year:, author:, co_authors: [] }
+
+      current_commit = nil
+
+      output.each_line do |line|
+        if line =~ /^([a-f0-9]{40})/
+          current_commit = $1
+        elsif line =~ /^author (.+)$/
+          commit_cache[current_commit] ||= {}
+          commit_cache[current_commit][:author_name] = $1
+        elsif line =~ /^author-mail <(.+)>$/
+          commit_cache[current_commit] ||= {}
+          commit_cache[current_commit][:author_email] = $1
+        elsif line =~ /^author-time (\d+)$/
+          commit_cache[current_commit] ||= {}
+          timestamp = $1.to_i
+          commit_cache[current_commit][:year] = Time.at(timestamp).year
+        end
+      end
+
+      # Now fetch co-authors for each unique commit
+      commit_cache.each do |commit_hash, data|
+        next if commit_hash == "0" * 40 # Skip uncommitted lines
+
+        # Get commit message for Co-Authored-By parsing
+        msg_output, _status = Open3.capture2("git", "log", "-1", "--format=%B", commit_hash)
+        co_authors = parse_co_authors(msg_output)
+        data[:co_authors] = co_authors
+
+        # Add author
+        if data[:author_name] && data[:author_email]
+          key = "#{data[:author_name]} <#{data[:author_email]}>"
+          year = data[:year] || Date.today.year
+          contributors[key] = [contributors[key] || 0, year].max
+        end
+
+        # Add co-authors with same year as commit
+        co_authors.each do |ca|
+          key = "#{ca[:name]} <#{ca[:email]}>"
+          year = data[:year] || Date.today.year
+          contributors[key] = [contributors[key] || 0, year].max
+        end
+      end
+
+      contributors
+    end
+
+    # Get YOUR latest year contribution to the file/lines.
+    # your_identifiers should be an array of strings that identify you (name, email fragments).
+    def get_your_latest_year(filepath, your_identifiers, start_line = nil, end_line = nil)
+      contributors = get_contributors_for_lines(filepath, start_line, end_line)
+
+      your_year = nil
+      contributors.each do |contributor, year|
+        if your_identifiers.any? { |id| contributor.include?(id) }
+          your_year = [your_year || 0, year].max
+        end
+      end
+
+      your_year || Date.today.year
+    end
+
+    # Get all contributors EXCEPT you, with their latest years.
+    # Returns array of { name:, email:, year: }
+    def get_other_contributors(filepath, your_identifiers, start_line = nil, end_line = nil)
+      contributors = get_contributors_for_lines(filepath, start_line, end_line)
+
+      others = []
+      contributors.each do |contributor, year|
+        next if your_identifiers.any? { |id| contributor.include?(id) }
+
+        # Parse "Name <email>" format
+        if contributor =~ /^(.+?)\s*<(.+)>$/
+          others << { name: $1.strip, email: $2.strip, year: }
+        end
+      end
+
+      others
+    end
+
+    private def parse_co_authors(message)
+      co_authors = []
+
+      message.each_line do |line|
+        # Match "Co-Authored-By: Name <email>" (case insensitive)
+        if line =~ /^Co-Authored-By:\s*(.+?)\s*<(.+?)>\s*$/i
+          co_authors << { name: $1.strip, email: $2.strip }
+        end
+      end
+
+      co_authors
+    end
+  end
+end

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

@@ -0,0 +1,353 @@
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: AGPL-3.0-or-later
+#++
+
+# Script to add SPDX snippet headers to fenced code blocks in markdown files.
+#
+# Usage: ruby tasks/license/snippets_md.rb [path...]
+#
+# If no paths are given, processes all .md files via git ls-files.
+#
+# Rules:
+# - Wraps all fenced code blocks (``` or ````) with SPDX snippet headers (MIT-0)
+# - For SYNC:START/SYNC:END blocks, wraps AROUND the sync markers (not inside)
+# - Uses git blame to determine the latest edit year for the code lines
+# - Skips blocks that are already properly wrapped with MIT-0 and Kerrick Long
+# - Removes malformed existing SPDX-Snippet blocks and replaces with correct ones
+
+require "open3"
+require "date"
+
+# The name for SPDX-FileCopyrightText in code snippets.
+COPYRIGHT_HOLDER = "Kerrick Long"
+
+# The SPDX license identifier for code snippets.
+LICENSE = "MIT-0"
+
+# Files to skip entirely (relative paths from repo root)
+EXCLUDED_FILES = [
+  "doc/contributors/v1.0.0_blockers.md",
+  "doc/contributors/upstream_requests/tab_rects.md",
+  "doc/contributors/upstream_requests/title_rects.md",
+].freeze
+
+# Determines the latest edit year for a line range using git blame.
+#
+# Copyright years come from when code was last modified. Git blame provides
+# per-line authorship. Extract and return the most recent year.
+#
+# [file] Path to the file.
+# [start_line] First line number (1-indexed).
+# [end_line] Last line number (1-indexed).
+def get_latest_git_year(file, start_line, end_line)
+  cmd = %W[git blame -L #{start_line},#{end_line} --date=short -- #{file}]
+  output, _status = Open3.capture2(*cmd)
+  years = output.scan(/(\d{4})-\d{2}-\d{2}/).flatten.map(&:to_i)
+  years.empty? ? Date.today.year : years.max
+end
+
+# Checks if an existing SPDX snippet header matches our required format.
+#
+# Already-correct snippets should be skipped. Re-wrapping wastes time and
+# creates noisy diffs. This function validates existing headers.
+#
+# [lines] Array of line strings.
+# [idx] Index of the SPDX-SnippetBegin line.
+def is_our_snippet_header?(lines, idx)
+  # Check if the current SPDX-SnippetBegin block already has our copyright/license
+  i = idx + 1
+  has_our_copyright = false
+  has_mit0 = false
+
+  while i < lines.length && !lines[i].include?("-->")
+    line = lines[i]
+    has_our_copyright = true if line.include?(COPYRIGHT_HOLDER) && line.include?("SPDX-FileCopyrightText")
+    has_mit0 = true if line.include?("MIT-0") && line.include?("SPDX-License-Identifier")
+    i += 1
+  end
+
+  has_our_copyright && has_mit0
+end
+
+# Locates the SPDX-SnippetEnd marker for a snippet block.
+#
+# Snippet blocks have paired begin/end markers. Removing or replacing a block
+# requires finding both. This scans forward from a start position.
+#
+# [lines] Array of line strings.
+# [start_idx] Index to start searching from.
+def find_snippet_end(lines, start_idx)
+  i = start_idx
+  while i < lines.length
+    return i if lines[i].include?("SPDX-SnippetEnd")
+    i += 1
+  end
+  nil
+end
+
+# Wraps code blocks in a markdown file with SPDX snippet headers.
+#
+# Each code block needs MIT-0 licensing. Processing involves scanning for
+# fenced blocks, removing malformed existing headers, and inserting correct
+# ones. This function orchestrates that workflow.
+#
+# [filepath] Path to the markdown file.
+def process_file(filepath)
+  # Skip excluded files
+  return if EXCLUDED_FILES.any? { |excluded| filepath.end_with?(excluded) }
+
+  content = File.read(filepath)
+  lines = content.lines
+
+  # Track code block ranges (to exclude from file header year calculation)
+  code_block_ranges = []
+  changes = []
+  removals = [] # existing malformed SPDX snippet blocks to remove
+  i = 0
+
+  while i < lines.length
+    line = lines[i]
+
+    # Check if we're at an existing SPDX-SnippetBegin
+    if line.include?("SPDX-SnippetBegin")
+      snippet_start = i
+      snippet_end = find_snippet_end(lines, i)
+
+      if snippet_end
+        # Check if this is already our proper snippet
+        if is_our_snippet_header?(lines, i)
+          # Skip this block entirely - it's already correct
+          i = snippet_end + 1
+          next
+        else
+          # Mark for removal - we'll re-wrap the inner content
+          removals << { start: snippet_start, end: snippet_end }
+          i = snippet_end + 1
+          next
+        end
+      end
+    end
+
+    # Check for SYNC:START pattern
+    if line =~ /<!--\s*SYNC:START/
+      sync_start_line = i
+      j = i + 1
+      code_start = nil
+      code_end = nil
+      sync_end_line = nil
+
+      while j < lines.length
+        if lines[j] =~ /^(````*)(\w*)$/
+          if code_start.nil?
+            code_start = j
+          else
+            code_end = j
+          end
+        elsif lines[j] =~ /<!--\s*SYNC:END/
+          sync_end_line = j
+          break
+        end
+        j += 1
+      end
+
+      if code_start && code_end && sync_end_line
+        year = get_latest_git_year(filepath, code_start + 1, code_end + 1)
+        changes << {
+          type: :sync_block,
+          start: sync_start_line,
+          end: sync_end_line,
+          year:,
+        }
+        code_block_ranges << (code_start..code_end)
+        i = sync_end_line + 1
+        next
+      end
+    end
+
+    # Check for standalone fenced code block
+    if line =~ /^(````*)(\w*)$/
+      fence_marker = $1
+      fence_start = i
+      re_end = /^#{Regexp.escape(fence_marker)}$/
+
+      j = i + 1
+      fence_end = nil
+      while j < lines.length
+        if lines[j] =~ re_end
+          fence_end = j
+          break
+        end
+        j += 1
+      end
+
+      if fence_end
+        year = get_latest_git_year(filepath, fence_start + 1, fence_end + 1)
+        changes << {
+          type: :code_block,
+          start: fence_start,
+          end: fence_end,
+          year:,
+        }
+        code_block_ranges << (fence_start..fence_end)
+        i = fence_end + 1
+        next
+      end
+    end
+
+    i += 1
+  end
+
+  # Handle removals and additions
+  has_changes = !changes.empty? || !removals.empty?
+
+  # Remove existing malformed SPDX blocks (in reverse order)
+  removals.sort_by { |r| -r[:start] }.each do |removal|
+    # Remove the SnippetEnd line
+    lines.delete_at(removal[:end])
+    # Remove lines from SnippetBegin through the --> closing the comment
+    close_idx = removal[:start]
+    while close_idx < lines.length && !lines[close_idx].include?("-->")
+      close_idx += 1
+    end
+    # Remove from start to close_idx inclusive
+    (close_idx - removal[:start] + 1).times { lines.delete_at(removal[:start]) }
+  end
+
+  # Recalculate content after removals
+  content = lines.join
+  lines = content.lines
+
+  # Re-scan for code blocks that need wrapping
+  changes = []
+  i = 0
+
+  while i < lines.length
+    line = lines[i]
+
+    # Skip if already inside an SPDX-SnippetBegin block
+    if line.include?("SPDX-SnippetBegin")
+      while i < lines.length && !lines[i].include?("SPDX-SnippetEnd")
+        i += 1
+      end
+      i += 1
+      next
+    end
+
+    # Check for SYNC:START pattern
+    if line =~ /<!--\s*SYNC:START/
+      sync_start_line = i
+      j = i + 1
+      code_start = nil
+      code_end = nil
+      sync_end_line = nil
+
+      while j < lines.length
+        if lines[j] =~ /^(````*)(\w*)$/
+          if code_start.nil?
+            code_start = j
+          else
+            code_end = j
+          end
+        elsif lines[j] =~ /<!--\s*SYNC:END/
+          sync_end_line = j
+          break
+        end
+        j += 1
+      end
+
+      if code_start && code_end && sync_end_line
+        year = get_latest_git_year(filepath, code_start + 1, code_end + 1)
+        changes << {
+          type: :sync_block,
+          start: sync_start_line,
+          end: sync_end_line,
+          year:,
+        }
+        i = sync_end_line + 1
+        next
+      end
+    end
+
+    # Check for standalone fenced code block
+    if line =~ /^(````*)(\w*)$/
+      fence_marker = $1
+      fence_start = i
+      re_end = /^#{Regexp.escape(fence_marker)}$/
+
+      j = i + 1
+      fence_end = nil
+      while j < lines.length
+        if lines[j] =~ re_end
+          fence_end = j
+          break
+        end
+        j += 1
+      end
+
+      if fence_end
+        year = get_latest_git_year(filepath, fence_start + 1, fence_end + 1)
+        changes << {
+          type: :code_block,
+          start: fence_start,
+          end: fence_end,
+          year:,
+        }
+        i = fence_end + 1
+        next
+      end
+    end
+
+    i += 1
+  end
+
+  return if changes.empty? && !has_changes
+
+  # Apply changes in reverse order to preserve line numbers
+  changes.sort_by { |c| -c[:start] }.each do |change|
+    # REUSE-IgnoreStart
+    snippet_begin = "<!-- SPDX-SnippetBegin -->\n<!--\n  SPDX-FileCopyrightText: #{change[:year]} #{COPYRIGHT_HOLDER}\n  SPDX-License-Identifier: #{LICENSE}\n-->\n"
+    snippet_end = "<!-- SPDX-SnippetEnd -->\n"
+    # REUSE-IgnoreEnd
+
+    # Insert end marker after the block
+    lines.insert(change[:end] + 1, snippet_end)
+    # Insert begin marker before the block
+    lines.insert(change[:start], snippet_begin)
+  end
+
+  File.write(filepath, lines.join)
+  puts "Updated: #{filepath} (#{changes.length} code block(s))"
+end
+
+# Finds markdown files to process.
+#
+# License automation runs on file sets. Users may specify paths or want all
+# files. This handles both cases using git ls-files for tracking.
+#
+# [paths] Explicit paths to process, or empty for all tracked .md files.
+def find_md_files(paths)
+  # Use git ls-files to respect .gitignore
+  if paths.empty?
+    `git ls-files '*.md'`.split("\n")
+  else
+    paths.flat_map do |path|
+      if File.directory?(path)
+        `git ls-files '#{path}/**/*.md'`.split("\n")
+      else
+        path
+      end
+    end
+  end
+end
+
+if __FILE__ == $0
+  paths = ARGV.empty? ? [] : ARGV
+  files = find_md_files(paths)
+
+  files.each do |file|
+    process_file(file)
+  end
+end

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

@@ -0,0 +1,186 @@
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: AGPL-3.0-or-later
+#++
+
+# Script to add SPDX snippet headers to RDoc code examples in Ruby files.
+#
+# Usage: ruby scripts/add_spdx_rdoc_snippets.rb [path...]
+#
+# If no paths are given, processes all .rb files via git ls-files.
+#
+# Rules:
+# - Wraps RDoc code examples (indented comment lines) with SPDX snippet headers
+# - Uses #-- and #++ to hide the SPDX headers from RDoc rendering
+# - Uses git blame to determine the latest edit year for the code lines
+# - Skips blocks that are already wrapped with SPDX-SnippetBegin
+
+require "open3"
+require "date"
+
+COPYRIGHT_HOLDER = "Kerrick Long"
+LICENSE = "MIT-0"
+
+# Determines the latest edit year for a line range using git blame.
+#
+# Copyright years come from when code was last modified. Git blame provides
+# per-line authorship. Extract and return the most recent year.
+#
+# [file] Path to the file.
+# [start_line] First line number (1-indexed).
+# [end_line] Last line number (1-indexed).
+def get_latest_git_year(file, start_line, end_line)
+  cmd = %W[git blame -L #{start_line},#{end_line} --date=short -- #{file}]
+  output, _status = Open3.capture2(*cmd)
+  years = output.scan(/(\d{4})-\d{2}-\d{2}/).flatten.map(&:to_i)
+  years.empty? ? Date.today.year : years.max
+end
+
+# Identifies RDoc code blocks in Ruby source files.
+#
+# RDoc code examples are indented comment lines. They need MIT-0 licensing
+# separate from the file. This scans for the indentation pattern that
+# identifies code blocks.
+#
+# [lines] Array of line strings from the file.
+def find_rdoc_code_blocks(lines)
+  # Find all RDoc code blocks (indented comment lines)
+  # Returns array of {start:, end:, indent:} where indent is the comment prefix
+  blocks = []
+  i = 0
+
+  while i < lines.length
+    line = lines[i]
+
+    # Check if this is an indented code line in a comment
+    # Pattern: optional leading whitespace, #, then 3+ spaces (RDoc code indent)
+    if line =~ /^(\s*)#(   +)(\S.*)$/
+      prefix = $1 # leading whitespace before #
+      block_start = i
+
+      # Find the extent of this code block
+      j = i
+      while j < lines.length
+        current = lines[j]
+        # Code block continues if line is indented code OR empty comment line
+        if current =~ /^#{Regexp.escape(prefix)}#(   +|\s*$)/
+          j += 1
+        else
+          break
+        end
+      end
+
+      block_end = j - 1
+
+      # Only count as a block if it has actual code (not just empty lines)
+      has_code = (block_start..block_end).any? { |k| lines[k] =~ /^#{Regexp.escape(prefix)}#   +\S/ }
+
+      if has_code && block_end > block_start
+        blocks << { start: block_start, end: block_end, prefix: }
+      end
+
+      i = j
+    else
+      i += 1
+    end
+  end
+
+  blocks
+end
+
+# Checks if a code block already has SPDX snippet headers.
+#
+# Already-wrapped blocks should be skipped. Re-wrapping wastes time and
+# creates noisy diffs. This checks for the #++ marker before a block.
+#
+# [lines] Array of line strings.
+# [block_start] Index of the code block start.
+# [prefix] The indentation prefix for this block.
+def is_already_wrapped?(lines, block_start, prefix)
+  # Check if the line before the block is #++ (meaning it's already wrapped)
+  return false if block_start < 1
+
+  prev_line = lines[block_start - 1]
+  prev_line =~ /^#{Regexp.escape(prefix)}#\+\+\s*$/
+end
+
+# Wraps RDoc code blocks in a Ruby file with SPDX snippet headers.
+#
+# Each code example needs MIT-0 licensing. Processing involves scanning for
+# indented examples and inserting hidden SPDX headers. This function
+# orchestrates that workflow.
+#
+# [filepath] Path to the Ruby file.
+def process_file(filepath)
+  content = File.read(filepath)
+  lines = content.lines
+
+  blocks = find_rdoc_code_blocks(lines)
+
+  # Filter out already-wrapped blocks
+  blocks.reject! { |b| is_already_wrapped?(lines, b[:start], b[:prefix]) }
+
+  return if blocks.empty?
+
+  # Apply changes in reverse order to preserve line numbers
+  blocks.sort_by { |b| -b[:start] }.each do |block|
+    year = get_latest_git_year(filepath, block[:start] + 1, block[:end] + 1)
+    prefix = block[:prefix]
+
+    # Build the wrapper lines
+    # REUSE-IgnoreStart
+    begin_wrapper = [
+      "#{prefix}#--\n",
+      "#{prefix}# SPDX-SnippetBegin\n",
+      "#{prefix}# SPDX-FileCopyrightText: #{year} #{COPYRIGHT_HOLDER}\n",
+      "#{prefix}# SPDX-License-Identifier: #{LICENSE}\n",
+      "#{prefix}#++\n",
+    ]
+
+    end_wrapper = [
+      "#{prefix}#--\n",
+      "#{prefix}# SPDX-SnippetEnd\n",
+      "#{prefix}#++\n",
+    ]
+    # REUSE-IgnoreEnd
+
+    # Insert end wrapper after the block
+    lines.insert(block[:end] + 1, *end_wrapper)
+    # Insert begin wrapper before the block
+    lines.insert(block[:start], *begin_wrapper)
+  end
+
+  File.write(filepath, lines.join)
+  puts "Updated: #{filepath} (#{blocks.length} code block(s))"
+end
+
+# Finds Ruby files to process.
+#
+# License automation runs on file sets. Users may specify paths or want all
+# files. This handles both cases using git ls-files for tracking.
+#
+# [paths] Explicit paths to process, or empty for all tracked .rb files.
+def find_rb_files(paths)
+  if paths.empty?
+    `git ls-files '*.rb'`.split("\n")
+  else
+    paths.flat_map do |path|
+      if File.directory?(path)
+        `git ls-files '#{path}/**/*.rb'`.split("\n")
+      else
+        path
+      end
+    end
+  end
+end
+
+if __FILE__ == $0
+  paths = ARGV.empty? ? [] : ARGV
+  files = find_rb_files(paths)
+
+  files.each do |file|
+    process_file(file)
+  end
+end