rcas 0.2.0

data/lib/rcas/chat/session.rb

@@ -0,0 +1,137 @@
+# frozen_string_literal: true
+
+require "json"
+require "fileutils"
+require "securerandom"
+require "time"
+require "date"
+
+module RCAS
+  module Chat
+    # A saved session: the transcript, the conversation with Claude and the
+    # settings, as JSON under ~/.rcas/sessions. Variables are not stored;
+    # they are rebuilt by replaying the transcript's Ruby when resuming.
+    class Session
+      DIR = ENV.fetch("RCAS_SESSION_DIR", File.join(HOME, "sessions"))
+
+      attr_reader :id, :created_at
+      attr_accessor :title, :model, :mode, :transcript, :messages, :usage, :updated_at, :cwd
+
+      def self.dir = DIR
+
+      def self.path(id) = File.join(dir, "#{id}.json")
+
+      def self.list
+        return [] unless File.directory?(dir)
+        Dir[File.join(dir, "*.json")].filter_map { |f| load(File.basename(f, ".json")) rescue nil }.sort_by { |s| [s.updated_at, s.id] }.reverse
+      end
+
+      def self.latest = list.first
+
+      # By id, by name (exact, then unique prefix, case-insensitive), by a
+      # unique id prefix, or by a 1-based index into the list.
+      def self.find(ref, among: nil)
+        return latest if ref.nil? || ref.to_s.empty?
+        return load(ref) if among.nil? && File.file?(path(ref))
+        sessions = among || list
+        ref = ref.to_s.strip
+        return sessions[ref.to_i - 1] if ref.match?(/\A\d{1,3}\z/) && ref.to_i.between?(1, sessions.size)
+        exact = sessions.select { |s| s.id == ref || s.title&.casecmp?(ref) }
+        return exact.first if exact.size == 1
+        matches = sessions.select { |s| s.id.start_with?(ref) || s.title.to_s.downcase.start_with?(ref.downcase) }
+        matches.size == 1 ? matches.first : nil
+      end
+
+      def self.load(id)
+        data = JSON.parse(File.read(path(id)), symbolize_names: true)
+        new(id: data[:id], created_at: Time.parse(data[:created_at])).tap do |s|
+          s.updated_at = Time.parse(data[:updated_at])
+          s.title = data[:title]
+          s.model = data[:model]
+          s.mode = data[:mode]&.to_sym
+          s.cwd = data[:cwd]
+          s.transcript = data[:transcript].to_a.map { |e| [e[0].to_sym, *e[1..]] }
+          s.messages = data[:messages].to_a
+          s.usage = (data[:usage] || {}).transform_keys(&:to_sym)
+        end
+      end
+
+      def initialize(id: nil, created_at: Time.now)
+        @id = id || "#{created_at.strftime('%Y%m%d-%H%M%S')}-#{SecureRandom.hex(2)}"
+        @created_at = created_at
+        @updated_at = created_at
+        @transcript = []
+        @messages = []
+        @usage = {}
+        @cwd = Dir.pwd
+      end
+
+      def path = self.class.path(id)
+
+      def save
+        @updated_at = Time.now
+        @title ||= transcript.find { |k, _| k == :input }&.[](1)&.lines&.first&.strip&.[](0, 60)
+        FileUtils.mkdir_p(self.class.dir)
+        File.write(path, JSON.pretty_generate(to_h))
+        self
+      end
+
+      def to_h
+        {
+          id: id, created_at: created_at.iso8601(6), updated_at: updated_at.iso8601(6), title: title,
+          model: model, mode: mode, cwd: cwd, usage: usage,
+          transcript: transcript,
+          messages: JSON.parse(JSON.generate(messages))
+        }
+      end
+
+      def delete
+        File.delete(path) if File.file?(path)
+      end
+
+      def turns = transcript.count { |k, _| k == :input }
+
+      # The first thing typed, as a one-line preview.
+      def first_input
+        transcript.find { |k, _| k == :input }&.[](1)&.lines&.first&.strip&.[](0, 80)
+      end
+
+      # The title, or the first input when the session was never named.
+      def name = title.to_s.empty? ? (first_input || "(empty)") : title
+
+      # "just now", "5m ago", "3h ago", "yesterday 14:02", "Sep 10 14:02"
+      def relative_time(now = Time.now)
+        age = now - updated_at
+        return "just now" if age < 60
+        return "#{(age / 60).floor}m ago" if age < 3600
+        return "#{(age / 3600).floor}h ago" if age < 86_400 && updated_at.to_date == now.to_date
+        return "yesterday #{updated_at.strftime('%H:%M')}" if updated_at.to_date == (now.to_date - 1)
+        updated_at.strftime(updated_at.year == now.year ? "%b %d %H:%M" : "%Y-%m-%d")
+      end
+
+      def summary
+        "#{id}  #{relative_time.ljust(15)}  #{turns.to_s.rjust(3)} inputs  #{name}"
+      end
+
+      # Bring a workspace back to the state the transcript left it in.
+      def replay_into(workspace)
+        transcript.each do |kind, text, _|
+          case kind
+          when :input
+            next if text.start_with?("!", "?")
+            if text.start_with?("/")
+              case text
+              when %r{\A/forget\b(.*)} then RCAS.forget(*Regexp.last_match(1).split.map(&:to_sym))
+              when %r{\A/reset\b} then workspace = Workspace.new
+              end
+              next
+            end
+            workspace.replay(text)
+          when :tool then workspace.replay(text)
+          end
+        end
+        workspace
+      end
+    end
+  end
+end

data/lib/rcas/chat/settings.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+require "json"
+require "fileutils"
+
+module RCAS
+  module Chat
+    # ~/.rcas (RCAS_HOME): settings.json, history, sessions/
+    HOME = ENV.fetch("RCAS_HOME", File.join(Dir.home, ".rcas"))
+
+    # Persistent defaults in ~/.rcas/settings.json. Precedence, lowest first:
+    # this file, environment variables, command-line flags, /commands in a
+    # session. `/settings save` writes the current values back.
+    module Settings
+      FILE = File.join(HOME, "settings.json")
+      KEYS = %w[output backend scale theme wrap plotstyle unicode numbered model fallbacks].freeze
+
+      module_function
+
+      def load(file = FILE)
+        return {} unless File.file?(file)
+        data = JSON.parse(File.read(file))
+        raise Error, "settings must be a JSON object" unless data.is_a?(Hash)
+        data.select { |k, _| KEYS.include?(k) }
+      rescue JSON::ParserError, Error => e
+        warn "rcas: ignoring #{file}: #{e.message}"
+        {}
+      end
+
+      def save(settings, file = FILE)
+        FileUtils.mkdir_p(File.dirname(file))
+        File.write(file, JSON.pretty_generate(settings.select { |k, _| KEYS.include?(k) }) + "\n")
+        file
+      end
+
+      def reset(file = FILE)
+        File.delete(file) if File.file?(file)
+      end
+
+      # Apply the file's rendering defaults where no environment variable
+      # overrides them. Output mode, model and fallbacks are consumed by the
+      # REPL because they depend on the session.
+      def apply(settings)
+        Render.backend = settings["backend"].to_sym if settings["backend"] && !ENV["RCAS_TEX_BACKEND"]
+        Render.scale = settings["scale"].to_f if settings["scale"] && !ENV["RCAS_TEX_SCALE"]
+        Render.theme = settings["theme"].to_sym if settings["theme"] && !ENV["RCAS_TEX_THEME"]
+        Render.wrap = settings["wrap"].to_i if settings["wrap"] && !ENV["RCAS_TEX_WRAP"]
+        Plot.style = settings["plotstyle"] if settings["plotstyle"] && !ENV["RCAS_PLOT_STYLE"]
+        RCAS.unicode = settings["unicode"] if settings.key?("unicode") && !ENV["RCAS_UNICODE"]
+        RCAS.numbered = settings["numbered"] if settings.key?("numbered") && !ENV["RCAS_NUMBERED"]
+        settings
+      end
+
+      # The values in force right now, in the file's format.
+      def current(ui, assistant)
+        {
+          "output" => ui.mode.to_s,
+          "backend" => (Render.available? ? Render.selected.name.to_s : nil),
+          "scale" => Render.scale,
+          "theme" => Render.theme.to_s,
+          "wrap" => Render.wrap,
+          "plotstyle" => Plot.style.to_s,
+          "unicode" => RCAS.unicode?,
+          "numbered" => RCAS.numbered?,
+          "model" => (assistant.model if assistant.available?),
+          "fallbacks" => (assistant.fallbacks if assistant.available?)
+        }.compact
+      end
+    end
+  end
+end

data/lib/rcas/chat/style.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module RCAS
+  module Chat
+    # ANSI colours, off when not writing to a terminal or NO_COLOR is set.
+    module Style
+      CODES = { bold: 1, dim: 2, italic: 3, red: 31, green: 32, yellow: 33, blue: 34, magenta: 35, cyan: 36, white: 37 }.freeze
+
+      class << self
+        attr_writer :enabled
+
+        def enabled?
+          return @enabled unless @enabled.nil?
+          $stdout.respond_to?(:tty?) && $stdout.tty? && ENV["NO_COLOR"].nil? && ENV["TERM"] != "dumb"
+        end
+
+        def paint(text, *styles)
+          return text.to_s if styles.empty? || !enabled?
+          "\e[#{styles.map { |s| CODES.fetch(s) }.join(';')}m#{text}\e[0m"
+        end
+
+        def strip(text) = text.to_s.gsub(/\e\[[\d;]*m/, "")
+
+        CODES.each_key do |name|
+          define_method(name) { |text| paint(text, name) }
+        end
+      end
+    end
+  end
+end

data/lib/rcas/chat/tool.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module RCAS
+  module Chat
+    # The tool Claude calls to run Ruby in the session. It subclasses the
+    # anthropic gem's classes, so it is loaded after the gem and only with
+    # it, by Chat.load_anthropic.
+    class EvalInput < Anthropic::BaseModel
+      required :code, String, doc: "Ruby code to evaluate in the user's rcas session. Variables persist between calls."
+      optional :show, Anthropic::Boolean, doc: "Display the result typeset in the user's terminal. Use it for the final result(s) the user asked for."
+    end
+
+    # Runs Ruby in the workspace on Claude's behalf and echoes the call and
+    # its result to the terminal, Claude-Code style.
+    class EvalTool < Anthropic::BaseTool
+      self.tool_name = "rcas_eval"
+      description "Evaluate Ruby code in the live rcas session and return the printed output and the result (as text and LaTeX)."
+      input_schema EvalInput
+
+      MAX_RESULT = 6000
+
+      attr_accessor :on_call
+
+      def initialize(workspace, ui)
+        @workspace = workspace
+        @ui = ui
+      end
+
+      def call(input)
+        code = input.code.to_s
+        @ui.tool_call("rcas_eval", code)
+        value, output = @ui.busy("computing") { @workspace.eval(code, capture: true) }
+        shown = "#{output}=> #{@ui.text_of(value)}"
+        @ui.tool_result(shown)
+        @ui.typeset(value, force: true) if input.show
+        on_call&.call(code, shown)
+        @ui.busy_start("thinking")
+        reply = shown
+        reply += "\nLaTeX: #{LaTeX.of(value)}" if @ui.typesettable?(value)
+        reply.size > MAX_RESULT ? "#{reply[0, MAX_RESULT]}\n… (truncated)" : reply
+      rescue StandardError, ScriptError => e
+        message = "#{e.class}: #{e.message.lines.first&.strip}"
+        hint = Usage.hint(e)
+        @ui.tool_result(message, error: true)
+        @ui.hint(hint)
+        message = ([message] + hint).join("\n") if hint
+        on_call&.call(code, message)
+        @ui.busy_start("thinking")
+        raise StandardError, message
+      end
+    end
+  end
+end

data/lib/rcas/chat/ui.rb

@@ -0,0 +1,316 @@
+# frozen_string_literal: true
+
+module RCAS
+  module Chat
+    # Everything that is printed: results in the chosen output mode, the
+    # banner, Claude's streamed text and its tool calls.
+    class UI
+      # How results are displayed:
+      #   :text    - plain rcas text only
+      #   :typeset - typeset picture only (text when the value has no LaTeX form)
+      #   :both    - text, then the picture
+      #   :latex   - text, then the LaTeX source
+      MODES = %i[text typeset both latex].freeze
+      # :tex was this mode's name until Sept 2026; a settings.json written
+      # before then, and the habit, still say it.
+      ALIASES = { tex: :typeset }.freeze
+
+      attr_reader :out, :mode
+
+      def initialize(out: $stdout, mode: nil)
+        @out = out
+        @mode = mode || default_mode
+      end
+
+      def default_mode
+        Render.inline?(@out) && Render.available? ? :typeset : :text
+      end
+
+      def mode=(value)
+        value = self.class.mode_for(value)
+        raise Error, "output mode must be one of #{MODES.join(', ')}" if value.nil?
+        @mode = value
+      end
+
+      # The mode +name+ stands for, or nil for a name that is none.
+      def self.mode_for(name)
+        return nil if name.nil? || name.to_s.empty?
+        name = name.to_sym
+        name = ALIASES.fetch(name, name)
+        MODES.include?(name) ? name : nil
+      end
+
+      def typeset? = %i[typeset both].include?(@mode)
+
+      def io = @out
+      def puts(text = "") = @out.puts(text)
+      def print(text) = @out.print(text)
+      def flush = @out.flush
+
+      # ---- banner -------------------------------------------------------------
+
+      # Without Claude configured, nothing here hints that it exists.
+      def banner(model:, backend:, assistant:, session: nil)
+        tagline = assistant ? "type Ruby or ask a question" : "type Ruby"
+        lines = [
+          "#{Style.paint('✻', :magenta, :bold)} #{Style.bold("rcas #{RCAS::VERSION}")} #{Style.dim("- symbols are indeterminates; #{tagline}")}",
+          ""
+        ]
+        lines << "  #{Style.dim('model')}    #{model}" if assistant
+        lines << "  #{Style.dim('output')}   #{@mode}#{typeset? ? Style.dim(" via #{backend}") : ''}"
+        lines << "  #{Style.dim('help')}     /help   #{Style.dim('quit')} /exit or Ctrl-D"
+        lines << "  #{Style.dim('session')}  #{session}" if session
+        lines << ""
+        examples = ["e = (x + 1) * (1 - x)", "e.expand", "ZZ[x].(x**6 - 1).factor"]
+        examples << "factor x**6 - 1 over the integers" if assistant
+        lines << "  #{Style.dim('try')}      #{examples.first}"
+        examples.drop(1).each { |ex| lines << "           #{ex}" }
+        box(lines)
+      end
+
+      def box(lines)
+        width = [lines.map { |l| visible_width(l) }.max + 2, columns - 2].min
+        width = 20 if width < 20
+        puts Style.dim("╭#{'─' * width}╮")
+        lines.each do |l|
+          l = truncate(l, width - 2)
+          pad = [width - visible_width(l) - 1, 0].max
+          puts "#{Style.dim('│')} #{l}#{' ' * pad}#{Style.dim('│')}"
+        end
+        puts Style.dim("╰#{'─' * width}╯")
+      end
+
+      # Cut a (possibly coloured) line to +max+ visible characters.
+      def truncate(line, max)
+        return line if visible_width(line) <= max
+        plain = Style.strip(line)
+        "#{plain[0, [max - 1, 0].max]}…"
+      end
+
+      def visible_width(text) = Style.strip(text).size
+
+      def columns
+        require "io/console"
+        width = @out.respond_to?(:winsize) && @out.tty? ? @out.winsize[1] : 0
+        width = ENV.fetch("COLUMNS", "0").to_i if width.to_i <= 0
+        width.to_i.positive? ? width.to_i : 100
+      rescue StandardError
+        100
+      end
+
+      # ---- results ------------------------------------------------------------
+
+      # A plot is braille art unless /plotstyle image asks for a picture.
+      def plot_picture(value, force: false)
+        return false unless force || Plot.image?
+        return false unless value.picture?(@out)
+        print "   "
+        value.picture(io: @out)
+      end
+
+      def result(value)
+        Results.record(value) # `Out[3]` reaches the result of the session's third line
+        return if value.is_a?(Plot) && plot_picture(value)
+        show_text = @mode != :typeset || !typesettable?(value) || !Render.inline?(@out)
+        if show_text
+          lines = text_of(value).lines.map(&:chomp)
+          mark = Results.mark
+          indent = " " * (mark ? mark.length + 1 : 0)
+          puts "#{mark ? "#{Style.dim(mark)} " : ''}#{Style.green(lines.first.to_s)}"
+          lines.drop(1).each { |l| puts "#{indent}#{Style.green(l)}" }
+        end
+        case @mode
+        when :typeset, :both then typeset(value)
+        when :latex then puts "   #{Style.dim(LaTeX.of(value))}" if typesettable?(value)
+        end
+      end
+
+      def text_of(value)
+        value.respond_to?(:to_latex) && !value.is_a?(String) ? value.to_s : value.inspect
+      end
+
+      # Inline picture when possible; otherwise nothing (the text is there).
+      def typeset(value, force: false)
+        return unless typesettable?(value)
+        return puts("   #{LaTeX.of(value)}") unless Render.inline?(@out) && Render.available?
+        return unless force || typeset?
+        print "   "
+        Render.show(value, io: @out)
+      rescue Render::Error => e
+        info("(typesetting failed: #{e.message.lines.first&.strip})")
+      end
+
+      def typesettable?(value)
+        case value
+        when Expression, Polynomial, Factorization, Domain, Vector, Matrix, VectorSpace, MatrixSpace, Symbol, Numeric then true
+        when ->(v) { defined?(Equation) && v.is_a?(Equation) } then true
+        when ->(v) { v.respond_to?(:to_latex) && !v.is_a?(String) } then true # inequalities, sets, field elements, ...
+        when Array then !value.empty? && value.all? { |v| typesettable?(v) }
+        when Hash then !value.empty? && value.values.all? { |v| v.is_a?(Domain) }
+        else false
+        end
+      end
+
+      def error(message) = puts(Style.red("  #{message}"))
+      def info(message) = puts(Style.dim("  #{message}"))
+      def warning(message) = puts(Style.yellow("  warning: #{message}"))
+
+      # A usage hint under an error: the first line in cyan, the rest dimmed.
+      def hint(lines)
+        return if lines.nil? || lines.empty?
+        first, *rest = lines
+        puts "  #{Style.cyan(first)}"
+        rest.each { |l| puts "  #{Style.dim(l)}" }
+      end
+
+      # ---- waiting ------------------------------------------------------------
+
+      def tty? = @out.respond_to?(:tty?) && @out.tty?
+
+      # A horizontal rule across the terminal.
+      def rule = Style.dim("─" * [columns, 200].min)
+
+      # Animate +label+ on the current line while the block runs; the line is
+      # cleared before anything else is printed. Returns the block's value.
+      def busy(label)
+        busy_start(label)
+        yield
+      ensure
+        busy_stop
+      end
+
+      def busy_start(label)
+        busy_stop
+        return unless tty?
+        @spinner = Spinner.new(@out, label).start
+      end
+
+      def busy_stop
+        @spinner&.stop
+        @spinner = nil
+      end
+
+      # Seconds a computation took, mentioned only when it was noticeable.
+      # At the right edge of the terminal, where it is out of the way of the
+      # result; piped output has no edge to hang it on, so there it is
+      # indented like any other aside.
+      def took(seconds)
+        return if seconds < 1.5
+        text = "(#{seconds.round(1)}s)"
+        return info(text) unless tty?
+        puts Style.dim(text.rjust([columns - 1, text.size + 2].max))
+      end
+
+      # A dimmed replay of earlier turns when a session is resumed.
+      def history(transcript, limit: 12)
+        entries = transcript.last(limit)
+        info("… #{transcript.size - entries.size} earlier entries") if transcript.size > entries.size
+        entries.each do |kind, a, b|
+          case kind
+          when :input then puts "#{Style.dim('❯')} #{Style.dim(a)}"
+          when :result then puts "   #{Style.dim("=> #{a.lines.first&.chomp}#{a.lines.size > 1 ? ' …' : ''}")}"
+          when :error then puts "   #{Style.dim(a.lines.first&.chomp)}"
+          when :assistant then puts "#{Style.dim('⏺')} #{Style.dim(a.to_s.lines.first(3).join.chomp)}#{a.to_s.lines.size > 3 ? Style.dim(' …') : ''}"
+          when :tool then puts "#{Style.dim('⏺')} #{Style.dim("rcas_eval(#{a.lines.first&.chomp})")}"
+          when :shell then puts "#{Style.dim('!')} #{Style.dim(a)}"
+          end
+        end
+        puts
+      end
+
+      # ---- assistant turn -----------------------------------------------------
+
+      def assistant_start
+        @in_text = false
+      end
+
+      def assistant_text(delta)
+        busy_stop
+        unless @in_text
+          print "#{Style.paint('⏺', :white, :bold)} "
+          @in_text = true
+        end
+        print delta.gsub("\n", "\n  ")
+        flush
+      end
+
+      def assistant_end
+        busy_stop
+        puts if @in_text
+        @in_text = false
+      end
+
+      def tool_call(name, code)
+        busy_stop
+        assistant_end
+        first, *rest = code.lines.map(&:chomp)
+        puts "#{Style.paint('⏺', :green, :bold)} #{Style.bold(name)}#{Style.dim('(')}#{Style.cyan(first)}#{rest.empty? ? Style.dim(')') : ''}"
+        rest.each_with_index { |l, i| puts "  #{Style.cyan(l)}#{i == rest.size - 1 ? Style.dim(')') : ''}" }
+      end
+
+      def tool_result(text, error: false)
+        busy_stop
+        lines = text.to_s.lines.map(&:chomp)
+        lines = lines.first(12) + ["… (#{lines.size - 12} more lines)"] if lines.size > 13
+        lines.each_with_index do |l, i|
+          prefix = i.zero? ? "  #{Style.dim('⎿')}  " : "     "
+          puts "#{prefix}#{error ? Style.red(l) : Style.dim(l)}"
+        end
+      end
+    end
+
+    # A braille spinner with a label and, after a while, the elapsed time.
+    # Runs in its own thread so CPU-bound work in the main thread still
+    # lets it turn (Ruby switches threads every 100ms).
+    class Spinner
+      FRAMES = %w[⠋ ⠙ ⠹ ⠸ ⠼ ⠴ ⠦ ⠧ ⠇ ⠏].freeze
+
+      def initialize(out, label, delay: 0.15, interval: 0.08)
+        @out = out
+        @label = label
+        @delay = delay
+        @interval = interval
+        @shown = false
+      end
+
+      def start
+        @started = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+        @thread = Thread.new do
+          sleep @delay
+          i = 0
+          loop do
+            draw(FRAMES[i % FRAMES.size])
+            i += 1
+            sleep @interval
+          end
+        end
+        @thread.report_on_exception = false
+        self
+      end
+
+      def stop
+        @thread&.kill
+        @thread&.join(0.2)
+        @thread = nil
+        if @shown
+          @out.print "\r\e[2K"
+          @out.flush
+          @shown = false
+        end
+        elapsed
+      end
+
+      def elapsed = @started ? Process.clock_gettime(Process::CLOCK_MONOTONIC) - @started : 0.0
+
+      private
+
+      def draw(frame)
+        secs = elapsed
+        time = secs >= 2 ? Style.dim(" #{secs.round}s") : ""
+        @out.print "\r\e[2K#{Style.magenta(frame)} #{Style.dim("#{@label}…")}#{time}"
+        @out.flush
+        @shown = true
+      end
+    end
+  end
+end

data/lib/rcas/chat/usage.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module RCAS
+  module Chat
+    # Usage hints for errors raised inside rcas, taken from the source: the
+    # `def` line of the method the user called and the comment block above
+    # it (rcas documents every public function that way).
+    #
+    #   Usage.hint(error)   # => ["usage: sum(f, k = nil, from = nil, to = nil, **range)",
+    #                       #     "sum(k**2, k, 1, n) or sum(k**2, k: 1..n); an endless range means infinity"]
+    module Usage
+      LIB = File.expand_path("../..", __dir__)
+      USER_FRAME = "(rcas)"
+      MAX_DOC_LINES = 4
+
+      module_function
+
+      # Lines to print under an error, or nil when there is nothing to say.
+      # Only a plain ArgumentError counts: subclasses such as DomainError
+      # describe the mathematics, not the call.
+      # +user_frame+ is the file name the front end evaluates input under.
+      def hint(error, user_frame: USER_FRAME)
+        return nil unless error.instance_of?(ArgumentError)
+        frame = entry_frame(error, user_frame) or return nil
+        info = describe(frame.path, frame.lineno) or return nil
+        lines = ["usage: #{info[:signature]}"]
+        lines.concat(info[:doc].first(MAX_DOC_LINES))
+        lines
+      end
+
+      # The outermost rcas frame that the user's code called directly.
+      def entry_frame(error, user_frame = USER_FRAME)
+        locations = error.backtrace_locations or return nil
+        before_user = locations.take_while { |l| l.path != user_frame }
+        return nil if before_user.size == locations.size
+        before_user.reverse.find { |l| l.path.start_with?(LIB) }
+      end
+
+      # => { name:, signature:, doc: [...] } for the method whose body
+      # contains +lineno+ of +path+.
+      def describe(path, lineno)
+        lines = File.readlines(path)
+        i = lineno - 1
+        i -= 1 while i >= 0 && !lines[i].match?(/^\s*def\s/)
+        return nil if i.negative?
+        m = lines[i].match(/def\s+(?:self\.)?(?<name>[A-Za-z_]\w*[?!=]?|[+\-*\/%<>=!\[\]~^&|]+@?)\s*(?:\((?<params>.*?)\))?/)
+        return nil unless m
+        doc = []
+        j = i - 1
+        while j >= 0 && lines[j].match?(/^\s*#/)
+          doc.unshift(lines[j].sub(/^\s*#\s?/, "").rstrip)
+          j -= 1
+        end
+        params = m[:params].to_s.strip
+        signature = params.empty? ? m[:name] : "#{m[:name]}(#{params})"
+        { name: m[:name], signature: signature, doc: doc }
+      rescue SystemCallError, IOError
+        nil
+      end
+    end
+  end
+end