tint_me 1.0.0

data/docs/agents/rubocop.md

@@ -0,0 +1,55 @@
+# RuboCop Fix Workflow for AI Agents
+
+This guide outlines a safe, repeatable process to fix RuboCop offenses while preserving behavior and keeping PRs focused.
+
+## Goals
+- Keep changes minimal and behavior‑preserving; prefer small, focused PRs.
+- Use safe autocorrect first; apply unsafe corrections only when reviewed and covered by tests.
+- Centralize rule changes in `.rubocop.yml`; never hand‑edit `.rubocop_todo.yml`.
+
+## Quick Commands
+- Full lint: `rake rubocop`
+- File/dir lint: `rubocop path/to/file.rb`
+- Safe autocorrect: `rubocop -a`
+- Targeted unsafe: `rubocop -A --only Cop/Name`
+- Run tests: `rake spec`
+- Regenerate TODO: `docquet regenerate-todo`
+ - Temporarily enable a TODO‑disabled cop: comment out its block in `.rubocop_todo.yml`
+
+## Workflow
+1) Reproduce locally
+- Run `rake rubocop` and note failing cops/files.
+
+2) Safe autocorrect first
+- Run `rubocop -a` on specific files or directories to reduce blast radius.
+- Re‑run `rake rubocop` and `rake spec` to verify no behavior changes.
+
+3) Target specific cops (if still failing)
+- For stylistic issues, fix manually or run `rubocop -A --only Cop/Name` on the smallest scope.
+- For logic‑sensitive cops (e.g., Performance, Lint), prefer manual fixes with tests.
+
+3a) If the cop is disabled in `.rubocop_todo.yml`
+- Open `.rubocop_todo.yml`, locate the `Cop/Name` entry, and temporarily comment out (or remove locally) that entire block. RuboCop respects TODO disables even with `--only`, so this is required to surface offenses.
+- Run `rubocop --only Cop/Name` (optionally `-A`) on a narrow path and fix findings.
+- Validate with `rake rubocop` and `rake spec`.
+- Refresh the TODO: run `docquet regenerate-todo` to update/remove the entry based on remaining offenses. Commit code changes and the regenerated `.rubocop_todo.yml` together in the same commit/PR.
+
+4) Update configuration (rare)
+- If a rule conflicts with project style, adjust `.rubocop.yml` with rationale in the PR body.
+- Do not edit `.rubocop_todo.yml` manually. After large cleanups, run `docquet regenerate-todo` and commit only that file.
+
+5) No inline disables
+- Do not use comment-based disables (`# rubocop:disable ...`). This project forbids inline disables.
+- If a finding cannot be safely fixed, pause and ask the maintainer for guidance. Options may include refining the rule in `.rubocop.yml` or adjusting the approach.
+
+6) Validate and commit
+- Ensure `rake` (tests + lint) is green.
+- Commit messages must start with a GitHub `:emoji:` and use imperative mood.
+  Examples:
+  - `:lipstick: RuboCop: safe autocorrect in lib/tint_me/style.rb`
+  - `:rotating_light: RuboCop: fix Lint/UnusedMethodArgument`
+
+## PR Guidance
+- Keep changes small and single‑purpose (e.g., “fix Style/StringLiterals in lib/tint_me”).
+- Include before/after snippets if unsafe autocorrect or refactor was applied.
+- Link any rule changes to rationale and project conventions.

data/lib/tint_me/error.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module TIntMe
+  # Base error class for TIntMe
+  class Error < StandardError; end
+end

data/lib/tint_me/sgr_builder.rb

@@ -0,0 +1,259 @@
+# frozen_string_literal: true
+
+module TIntMe
+  # Builds ANSI SGR (Select Graphic Rendition) escape sequences for terminal styling
+  #
+  # This class is responsible for generating the correct ANSI escape sequences
+  # for colors and text effects. It supports standard colors, bright colors,
+  # RGB colors, and various text decorations.
+  #
+  # @api private
+  class SGRBuilder
+    # ANSI escape sequence components
+    ESC = "\e"
+    public_constant :ESC
+
+    CSI = "#{ESC}[".freeze # Control Sequence Introducer
+    public_constant :CSI
+
+    SGR_END = "m"
+    public_constant :SGR_END
+
+    RESET_CODE = "#{CSI}0#{SGR_END}".freeze
+    public_constant :RESET_CODE
+
+    # Standard colors + bright colors
+    COLORS = {
+      black: 30,
+      red: 31,
+      green: 32,
+      yellow: 33,
+      blue: 34,
+      magenta: 35,
+      cyan: 36,
+      white: 37,
+      default: 39,
+      gray: 90,
+      # Bright colors (90-97)
+      bright_black: 90,
+      bright_red: 91,
+      bright_green: 92,
+      bright_yellow: 93,
+      bright_blue: 94,
+      bright_magenta: 95,
+      bright_cyan: 96,
+      bright_white: 97
+    }.freeze
+    public_constant :COLORS
+
+    # Effects mapping (SGR parameters)
+    EFFECTS = {
+      bold: 1,
+      faint: 2,
+      italic: 3,
+      underline: 4,
+      blink: 5,
+      inverse: 7,
+      conceal: 8,
+      overline: 53,
+      double_underline: 21
+    }.freeze
+    public_constant :EFFECTS
+
+    # Returns the singleton instance of SGRBuilder
+    # @return [SGRBuilder] The singleton instance
+    def self.instance
+      @instance ||= new
+    end
+
+    # Make new private to enforce singleton pattern
+    private_class_method :new
+
+    # Generates SGR prefix codes for the given styles
+    #
+    # Parameters are processed in this order for predictable output:
+    # 1. Foreground color (30-37, 90-97, or 38;2;r;g;b for RGB)
+    # 2. Background color (40-47, 100-107, or 48;2;r;g;b for RGB)
+    # 3. Text effects in numerical SGR code order:
+    #    bold(1), faint(2), italic(3), underline(4), blink(5), inverse(7),
+    #    conceal(8), double_underline(21), overline(53)
+    #
+    # @param foreground [Symbol, String, nil] Foreground color
+    #   - Symbol: :red, :green, :blue, :yellow, :magenta, :cyan, :white, :black,
+    #     :gray, :bright_red, :bright_green, etc.
+    #   - String: Hex colors like "#FF0000", "FF0000", "#F00", "F00"
+    # @param background [Symbol, String, nil] Background color (same format as foreground)
+    # @param bold [Boolean, nil] Bold text effect
+    # @param faint [Boolean, nil] Faint text effect
+    # @param italic [Boolean, nil] Italic text effect
+    # @param underline [Boolean, Symbol, nil] Underline effect (true, :double, or nil)
+    # @param blink [Boolean, nil] Blink effect
+    # @param inverse [Boolean, nil] Inverse/reverse effect
+    # @param conceal [Boolean, nil] Conceal/hide effect
+    # @param overline [Boolean, nil] Overline effect
+    # @return [String] The SGR escape sequence string
+    #
+    # @example Standard colors
+    #   prefix_codes(foreground: :red, bold: true)
+    #   # => "\e[31;1m"
+    #
+    # @example 256-color RGB (true color)
+    #   prefix_codes(foreground: "#FF6B35", background: "#F7931E")
+    #   # => "\e[38;2;255;107;53;48;2;247;147;30m"
+    #
+    # @example Multiple effects with colors (colors first, then effects in numerical order)
+    #   prefix_codes(foreground: :red, background: :blue, bold: true, italic: true)
+    #   # => "\e[31;44;1;3m" (red=31, blue_bg=44, bold=1, italic=3)
+    #
+    # @example Double underline
+    #   prefix_codes(foreground: :blue, underline: :double)
+    #   # => "\e[34;21m"
+    def prefix_codes(
+      foreground: nil,
+      background: nil,
+      bold: nil,
+      faint: nil,
+      italic: nil,
+      underline: nil,
+      blink: nil,
+      inverse: nil,
+      conceal: nil,
+      overline: nil
+    )
+      parameters = build_parameters(
+        foreground:,
+        background:,
+        bold:,
+        faint:,
+        italic:,
+        underline:,
+        blink:,
+        inverse:,
+        conceal:,
+        overline:
+      )
+      build_sgr_sequence(parameters)
+    end
+
+    # Returns the SGR reset code
+    # @return [String] The reset escape sequence
+    def reset_code
+      RESET_CODE
+    end
+
+    # Converts RGB values to SGR parameters
+    # @param red [Integer] Red component (0-255)
+    # @param green [Integer] Green component (0-255)
+    # @param blue [Integer] Blue component (0-255)
+    # @param background [Boolean] Whether this is for background color
+    # @return [String] The SGR parameter string for RGB color
+    private def rgb_to_sgr(red, green, blue, background: false)
+      base = background ? 48 : 38
+      "#{base};2;#{red};#{green};#{blue}"
+    end
+
+    private def build_parameters(
+      foreground:,
+      background:,
+      bold:,
+      faint:,
+      italic:,
+      underline:,
+      blink:,
+      inverse:,
+      conceal:,
+      overline:
+    )
+      parameters = []
+
+      # Process foreground color
+      parameters << process_foreground_color(foreground) if foreground
+
+      # Process background color
+      parameters << process_background_color(background) if background
+
+      # Collect effects and sort by SGR code for predictable order
+      effects = []
+      effects << EFFECTS[:bold] if bold == true
+      effects << EFFECTS[:faint] if faint == true
+      effects << EFFECTS[:italic] if italic == true
+      case underline
+      when true
+        effects << EFFECTS[:underline]
+      when :double
+        effects << EFFECTS[:double_underline]
+      when nil
+        # No underline
+      else
+        raise ArgumentError, "Invalid underline value: #{underline.inspect}"
+      end
+      effects << EFFECTS[:blink] if blink == true
+      effects << EFFECTS[:inverse] if inverse == true
+      effects << EFFECTS[:conceal] if conceal == true
+      effects << EFFECTS[:overline] if overline == true
+
+      parameters.concat(effects.sort)
+    end
+
+    private def process_foreground_color(foreground)
+      case foreground
+      when String
+        raise ArgumentError, "Invalid hex color: #{foreground}" unless hex_color?(foreground)
+
+        red, green, blue = hex_to_rgb(foreground)
+        rgb_to_sgr(red, green, blue, background: false)
+      when Symbol
+        raise ArgumentError, "Unknown foreground color: #{foreground}" unless COLORS.key?(foreground)
+
+        COLORS[foreground]
+      else
+        raise ArgumentError, "Invalid foreground type: #{foreground.class}"
+      end
+    end
+
+    private def process_background_color(background)
+      case background
+      when String
+        raise ArgumentError, "Invalid hex color: #{background}" unless hex_color?(background)
+
+        red, green, blue = hex_to_rgb(background)
+        rgb_to_sgr(red, green, blue, background: true)
+      when Symbol
+        raise ArgumentError, "Unknown background color: #{background}" unless COLORS.key?(background)
+
+        color_code = COLORS[background]
+        # Convert to background color code
+        color_code += 10 if color_code.between?(30, 37)
+        color_code += 10 if color_code.between?(90, 97)
+        color_code
+      else
+        raise ArgumentError, "Invalid background type: #{background.class}"
+      end
+    end
+
+    private def build_sgr_sequence(parameters)
+      return "" if parameters.empty?
+
+      "#{CSI}#{parameters.join(";")}#{SGR_END}"
+    end
+
+    private def hex_color?(value)
+      value.match?(/\A#?[0-9A-Fa-f]{3}([0-9A-Fa-f]{3})?\z/)
+    end
+
+    private def hex_to_rgb(hex)
+      # Remove # if present
+      hex = hex.delete_prefix("#")
+
+      # Expand 3-digit hex to 6-digit
+      hex = hex.chars.map {|c| c * 2 }.join if hex.length == 3
+
+      # Convert to RGB values
+      [
+        hex[0..1].to_i(16),
+        hex[2..3].to_i(16),
+        hex[4..5].to_i(16)
+      ]
+    end
+  end
+end

data/lib/tint_me/style/schema.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require "dry-schema"
+
+module TIntMe
+  class Style
+    # Schema for validating Style initialization arguments
+    Schema = Dry::Schema.define {
+      optional(:foreground).maybe(Types::Color)
+      optional(:background).maybe(Types::Color)
+      optional(:inverse).value(Types::BooleanOption)
+      optional(:bold).value(Types::BooleanOption)
+      optional(:faint).value(Types::BooleanOption)
+      optional(:underline).value(Types::UnderlineOption)
+      optional(:overline).value(Types::BooleanOption)
+      optional(:blink).value(Types::BooleanOption)
+      optional(:italic).value(Types::BooleanOption)
+      optional(:conceal).value(Types::BooleanOption)
+    }
+    private_constant :Schema
+  end
+end

data/lib/tint_me/style/types.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+require "dry-types"
+
+module TIntMe
+  class Style
+    # Type definitions for Style attributes using dry-types
+    module Types
+      include Dry.Types()
+
+      # Standard ANSI color names + bright colors
+      ColorSymbol = Symbol.enum(
+        :default,
+        :reset,
+        :black,
+        :red,
+        :green,
+        :yellow,
+        :blue,
+        :magenta,
+        :cyan,
+        :white,
+        :gray,
+        # Bright colors (90-97)
+        :bright_black,
+        :bright_red,
+        :bright_green,
+        :bright_yellow,
+        :bright_blue,
+        :bright_magenta,
+        :bright_cyan,
+        :bright_white
+      )
+      public_constant :ColorSymbol
+
+      # Hex color strings (3 or 6 digits, with or without #)
+      ColorString = String.constrained(format: /\A#?\h{3}(?:\h{3})?\z/)
+      public_constant :ColorString
+
+      Color = ColorSymbol | ColorString
+      public_constant :Color
+
+      BooleanOption = (Bool | Symbol.enum(:reset)).optional
+      public_constant :BooleanOption
+
+      UnderlineOption = (Bool | Symbol.enum(:double, :reset)).optional
+      public_constant :UnderlineOption
+    end
+  end
+end

data/lib/tint_me/style.rb

@@ -0,0 +1,286 @@
+# frozen_string_literal: true
+
+module TIntMe
+  Style = Data.define(
+    :foreground,
+    :background,
+    :inverse,
+    :bold,
+    :faint,
+    :underline,
+    :overline,
+    :blink,
+    :italic,
+    :conceal
+  )
+
+  # A style class for applying ANSI colors and text effects to terminal output.
+  #
+  # This class provides an immutable way to define and compose terminal styling options.
+  # It supports foreground/background colors, text decorations (bold, italic, underline, etc.),
+  # and composition via the >> operator for layering styles.
+  #
+  # @example Basic usage
+  #   style = Style.new(foreground: :red, bold: true)
+  #   puts style.call("Hello")  # or style["Hello"] or style.("Hello")
+  #
+  # @example Style composition
+  #   base = Style.new(foreground: :blue)
+  #   emphasis = Style.new(bold: true, underline: true)
+  #   combined = base >> emphasis
+  #   puts combined.call("Styled text")  # or combined["Styled text"] or combined.("Styled text")
+  #
+  # @example Color and decoration options
+  #   Style.new(
+  #     foreground: :red,           # :default, :red, :green, :blue, etc. or hex "#FF0000"
+  #     background: :yellow,        # same as foreground
+  #     bold: true,                 # nil (unset), false (off), true (on)
+  #     faint: false,               # mutually exclusive with bold
+  #     underline: :double,         # nil, false, true, :double
+  #     italic: true,               # nil, false, true
+  #     inverse: true,              # nil, false, true
+  #     # ... other boolean effects: overline, blink, conceal
+  #   )
+  class Style
+    # Returns the singleton instance of SGRBuilder
+    # @return [SGRBuilder] The SGR builder instance
+    # @api private
+    def self.sgr_builder
+      SGRBuilder.instance
+    end
+    # @!attribute [r] foreground
+    #   @return [Symbol, String] The foreground color (:red, :blue, :default, :reset, hex "#FF0000", etc.)
+
+    # @!attribute [r] background
+    #   @return [Symbol, String] The background color (same format as foreground)
+
+    # @!attribute [r] inverse
+    #   @return [nil, true, false, :reset] Whether to reverse foreground/background colors
+
+    # @!attribute [r] bold
+    #   @return [nil, true, false, :reset] Whether text is bold (mutually exclusive with faint)
+
+    # @!attribute [r] faint
+    #   @return [nil, true, false, :reset] Whether text is faint/dim (mutually exclusive with bold)
+
+    # @!attribute [r] underline
+    #   @return [nil, true, false, :double, :reset] Underline decoration type
+
+    # @!attribute [r] overline
+    #   @return [nil, true, false, :reset] Whether text has overline decoration
+
+    # @!attribute [r] blink
+    #   @return [nil, true, false, :reset] Whether text blinks
+
+    # @!attribute [r] italic
+    #   @return [nil, true, false, :reset] Whether text is italic
+
+    # @!attribute [r] conceal
+    #   @return [nil, true, false, :reset] Whether text is hidden/concealed
+
+    # Initialize a new Style with the given attributes
+    #
+    # @param foreground [Symbol, String] Foreground color. Accepts color names (:red, :green, :blue, etc.),
+    #   :default for terminal default, :reset for composition clearing, or hex strings ("#FF0000", "FF0000")
+    # @param background [Symbol, String] Background color. Same format as foreground
+    # @param inverse [nil, true, false, :reset] Reverse foreground/background colors
+    # @param bold [nil, true, false, :reset] Bold text (mutually exclusive with faint)
+    # @param faint [nil, true, false, :reset] Faint/dim text (mutually exclusive with bold)
+    # @param underline [nil, true, false, :double, :reset] Underline decoration
+    # @param overline [nil, true, false, :reset] Overline decoration
+    # @param blink [nil, true, false, :reset] Blinking text
+    # @param italic [nil, true, false, :reset] Italic text
+    # @param conceal [nil, true, false, :reset] Hidden/concealed text
+    # @raise [ArgumentError] If both bold and faint are true
+    # @raise [ArgumentError] If any parameter has invalid type or value
+    # @example Valid usage
+    #   Style.new(foreground: :red, bold: true)
+    #   Style.new(underline: :double, background: "#FF0000")
+    # @example Invalid usage (raises ArgumentError)
+    #   Style.new(foreground: 123)        # Invalid color type
+    #   Style.new(bold: "true")           # Invalid boolean type
+    #   Style.new(underline: :invalid)    # Invalid underline option
+    #   Style.new(bold: true, faint: true) # Mutually exclusive options
+    def initialize(
+      foreground: nil,
+      background: nil,
+      inverse: nil,
+      bold: nil,
+      faint: nil,
+      underline: nil,
+      overline: nil,
+      blink: nil,
+      italic: nil,
+      conceal: nil
+    )
+      # Schema validation
+      result = Schema.call({
+        foreground:,
+        background:,
+        inverse:,
+        bold:,
+        faint:,
+        underline:,
+        overline:,
+        blink:,
+        italic:,
+        conceal:
+      })
+
+      raise ArgumentError, result.errors.to_h unless result.success?
+
+      # Handle bold/faint mutual exclusion
+      if bold && faint
+        raise ArgumentError, "Cannot specify both bold and faint simultaneously"
+      end
+
+      # Pre-compute SGR sequences before freezing
+      # (Data.define freezes the instance after super)
+      sgr_builder = self.class.sgr_builder
+
+      # Prepare color values
+      foreground_color = foreground if foreground && foreground != :default
+      background_color = background if background && background != :default
+
+      # Handle underline effect
+      underline_effect = case underline
+                         when true then true
+                         when :double then :double
+                         when nil, false then nil
+                         else raise ArgumentError, "Invalid underline value: #{underline.inspect}"
+                         end
+
+      # Calculate prefix once
+      @prefix = sgr_builder.prefix_codes(
+        foreground: foreground_color,
+        background: background_color,
+        bold: bold == true ? true : nil,
+        faint: faint == true ? true : nil,
+        italic: italic == true ? true : nil,
+        underline: underline_effect,
+        blink: blink == true ? true : nil,
+        inverse: inverse == true ? true : nil,
+        conceal: conceal == true ? true : nil,
+        overline: overline == true ? true : nil
+      )
+
+      # Pre-compute reset code
+      @reset_code = sgr_builder.reset_code
+
+      super
+    end
+
+    # Apply the style to the given text using native ANSI escape sequences
+    #
+    # @param text [String] The text to apply styling to
+    # @return [String] The styled text with ANSI escape codes, or original text if no styles are set
+    # @example
+    #   style = Style.new(foreground: :red, bold: true)
+    #   style.call("Hello")  # => "\e[31;1mHello\e[0m"
+    #   style["World"]       # => "\e[31;1mWorld\e[0m" (alias)
+    def call(text)
+      return text if @prefix.empty?
+
+      "#{@prefix}#{text}#{@reset_code}"
+    end
+
+    alias [] call
+
+    # Compose this style with another style, creating a new Style instance.
+    # The right-hand style takes precedence for non-nil values.
+    # Handles bold/faint mutual exclusion automatically.
+    #
+    # == Composition Rules
+    #
+    # For `a >> b`, the resulting value for each attribute is determined by:
+    #
+    # <table>
+    #   <tr>
+    #     <th>b's value</th>
+    #     <th>Result</th>
+    #     <th>Description</th>
+    #   </tr>
+    #   <tr>
+    #     <td><code>nil</code></td>
+    #     <td><code>a</code>'s value</td>
+    #     <td>Preserves the original value</td>
+    #   </tr>
+    #   <tr>
+    #     <td><code>:reset</code></td>
+    #     <td><code>nil</code></td>
+    #     <td>Explicitly resets to no styling</td>
+    #   </tr>
+    #   <tr>
+    #     <td>any other</td>
+    #     <td><code>b</code>'s value</td>
+    #     <td>Adopts the new value</td>
+    #   </tr>
+    # </table>
+    #
+    # This applies to all attributes: colors (foreground, background) and
+    # style attributes (bold, italic, underline, inverse, overline, blink, conceal).
+    #
+    # @param other [Style] The style to compose with this one
+    # @return [Style] A new Style instance with composed attributes
+    #
+    # @example Basic composition
+    #   base = Style.new(foreground: :red, bold: true)
+    #   overlay = Style.new(background: :blue, underline: true)
+    #   result = base >> overlay  # => red text, blue background, bold and underlined
+    #
+    # @example Using nil to preserve values
+    #   styled = Style.new(foreground: :red, bold: true)
+    #   partial = Style.new(foreground: nil, italic: true)  # nil preserves red
+    #   result = styled >> partial  # => foreground: :red, bold: true, italic: true
+    #
+    # @example Using :reset to clear styles
+    #   styled = Style.new(foreground: :red, bold: true)
+    #   reset = Style.new(foreground: :reset, bold: :reset)
+    #   result = styled >> reset  # => foreground: nil, bold: nil
+    #
+    # @example Bold/faint mutual exclusion
+    #   bold_style = Style.new(bold: true)
+    #   faint_style = Style.new(faint: true)
+    #   result1 = bold_style >> faint_style  # => faint wins (right-hand takes precedence)
+    #   result2 = faint_style >> bold_style  # => bold wins (right-hand takes precedence)
+    def >>(other)
+      # Handle bold/faint mutual exclusion in composition
+      composed_bold = compose_attribute(bold, other.bold)
+      composed_faint = compose_attribute(faint, other.faint)
+
+      # If other explicitly sets bold, clear faint; if other explicitly sets faint, clear bold
+      if other.bold == true
+        composed_faint = false
+      elsif other.faint == true
+        composed_bold = false
+      elsif other.bold == :reset
+        composed_bold = nil
+      elsif other.faint == :reset
+        composed_faint = nil
+      end
+
+      Style.new(
+        foreground: compose_attribute(foreground, other.foreground),
+        background: compose_attribute(background, other.background),
+        inverse: compose_attribute(inverse, other.inverse),
+        bold: composed_bold,
+        faint: composed_faint,
+        underline: compose_attribute(underline, other.underline),
+        overline: compose_attribute(overline, other.overline),
+        blink: compose_attribute(blink, other.blink),
+        italic: compose_attribute(italic, other.italic),
+        conceal: compose_attribute(conceal, other.conceal)
+      )
+    end
+
+    private def compose_attribute(current, other)
+      if other.nil?
+        current
+      elsif other == :reset
+        nil
+      else
+        other
+      end
+    end
+  end
+end

data/lib/tint_me/version.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module TIntMe
+  # Current version of the TIntMe gem
+  # @return [String] The semantic version string
+  VERSION = "1.0.0"
+  public_constant :VERSION
+end