rkoans 0.0.1 → 0.1.0

data/exercises/runtime-context/runtime_context.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Exercises
+  # Reads the process inputs and identifies the running Ruby files and version.
+  class RuntimeContext
+    # Return the context hash described in the brief without consuming arguments.
+    def self.context
+      { arguments: [], greeting: '', program: '', file: '', encoding: '', ruby: '' }
+    end
+  end
+end

data/exercises/shared-rows/brief.md

@@ -0,0 +1,8 @@
+# Three Rows, One Surprise
+
+Fix `Exercises::SharedRows.rows(count)` in `shared_rows.rb` so it returns the
+requested number of empty, mutable arrays. Changing one row must leave the
+others untouched. Return `[]` for zero rows and fresh rows on each call.
+
+The starter supplies one array as the initial value to `Array.new`. Explore why
+appending to one row changes the others, then change how the rows are created.

data/exercises/shared-rows/hint.md

@@ -0,0 +1,7 @@
+# Hint
+
+An array holds references to objects. Passing a second argument to `Array.new`
+places that same object in every position; it does not copy it.
+
+The block form runs once per position. What could the block return so each row
+has its own mutable contents?

data/exercises/shared-rows/shared_rows.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Exercises
+  # Builds rows whose mutable contents are independent.
+  class SharedRows
+    # Returns count empty rows, each with its own mutable array.
+    # @param count [Integer] nonnegative number of rows
+    # @return [Array<Array<Object>>]
+    def self.rows(count)
+      Array.new(count, [])
+    end
+  end
+end

data/exercises/singleton-pattern/brief.md

@@ -0,0 +1,8 @@
+# One configuration object
+
+Use the standard-library Singleton module so Configuration.instance returns the same instance and Configuration.new is not a public constructor. Keep the default mode "learning". Distinguish this module from singleton methods, which are methods on one object.
+
+Use `rkoans check` to investigate one failing check at a time. Hints are optional.
+
+Edit `singleton_pattern.rb` in this exercise's folder. Checks call
+`Exercises::SingletonPattern` and its example classes.

data/exercises/singleton-pattern/hint.md

@@ -0,0 +1,5 @@
+# Hint
+
+Reusing the same instance is different from creating a fresh one on every call.
+
+The Singleton module supplies instance and changes construction visibility.

data/exercises/singleton-pattern/singleton_pattern.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require 'singleton'
+module Exercises
+  # Use the standard-library Singleton module so Configuration.instance returns the same instance
+  # and Configuration.new is not a public constructor.
+  class SingletonPattern
+    # Example Configuration for singleton pattern.
+    class Configuration
+      attr_accessor :mode
+
+      # Stores the initial values used by this example.
+      # @return [void]
+      def initialize = @mode = 'learning'
+      # Returns the shared configuration instance.
+      # @return [Configuration]
+      def self.instance = new
+    end
+  end
+end

data/exercises/time-and-date/brief.md

@@ -0,0 +1,8 @@
+# Offsets and leap days
+
+Implement `utc(text)` to parse an ISO8601 timestamp with an explicit offset and return the same instant formatted in UTC. Implement `days_between(first,last)` using Date ISO8601 parsing; return the integer number of calendar days, including leap days. Do not read the current clock.
+
+Use `rkoans check` to investigate one failing check at a time. Hints are optional.
+
+Edit `time_and_date.rb` in this exercise's folder. Checks call
+`Exercises::TimeAndDate` and its example classes.

data/exercises/time-and-date/hint.md

@@ -0,0 +1,5 @@
+# Hint
+
+An offset is part of the timestamp; UTC conversion must preserve the instant.
+
+Date subtraction returns an exact difference in calendar days.

data/exercises/time-and-date/time_and_date.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+# The example deliberately contrasts received arguments with values actually used.
+# rubocop:disable Lint/UnusedMethodArgument
+
+require 'time'
+require 'date'
+module Exercises
+  # Implement utc(text) to parse an ISO8601 timestamp with an explicit offset and return the same
+  # instant formatted in UTC.
+  class TimeAndDate
+    # Normalizes an offset ISO8601 timestamp to its UTC representation.
+    # @return [String]
+    def self.utc(text) = Time.iso8601(text).iso8601
+    # Returns the signed integer calendar-day difference between ISO dates.
+    # @return [Integer]
+    def self.days_between(first, last) = 0
+  end
+end
+
+# rubocop:enable Lint/UnusedMethodArgument

data/exercises/visibility/brief.md

@@ -0,0 +1,8 @@
+# An API boundary
+
+Wallet has an internal balance reader used when comparing wallets, and a normalizer used within deposit. Make balance protected, normalize private, and deposit/compare public. Other wallet instances must be able to compare balances, while callers cannot invoke balance or normalize directly. Preserve explicit self.normalize inside deposit: it is valid on the current Ruby.
+
+Use `rkoans check` to investigate one failing check at a time. Hints are optional.
+
+Edit `visibility.rb` in this exercise's folder. Checks call
+`Exercises::Visibility` and its example classes.

data/exercises/visibility/hint.md

@@ -0,0 +1,5 @@
+# Hint
+
+Protected methods allow suitable peer-object calls; private methods belong to internal use.
+
+Visibility declarations affect instance methods, not automatically singleton methods.

data/exercises/visibility/visibility.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+# The explicit receiver is part of the method-call experiment.
+# Explicit getter definitions are compared with attr_reader and attr_accessor.
+# rubocop:disable Style/RedundantSelf, Style/TrivialAccessors
+
+module Exercises
+  # Wallet has an internal balance reader used when comparing wallets, and a normalizer used within
+  # deposit.
+  class Visibility
+    # Example Wallet for visibility.
+    class Wallet
+      # Stores the initial values used by this example.
+      # @return [void]
+      def initialize(balance) = @balance = balance
+      # Returns the protected balance used for peer comparisons.
+      # @return [Integer]
+      def balance = @balance
+      # Converts a deposit amount to its nonnegative value.
+      # @return [Integer]
+      def normalize(value) = value.abs
+      # Adds the normalized amount to the balance.
+      # @return [Integer]
+      def deposit(value) = @balance += self.normalize(value)
+      # Compares this balance with another wallet's balance.
+      # @return [Integer]
+      def compare(other) = balance <=> other.balance
+    end
+  end
+end
+
+# rubocop:enable Style/RedundantSelf, Style/TrivialAccessors

data/lib/rkoans/catalog.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+require 'json'
+require_relative 'error'
+
+module Rkoans
+  # Loads the ordered exercise IDs and their packaged asset root.
+  class Catalog
+    attr_reader :root, :ids
+
+    # @param root [String] directory containing exercises, checks, and references
+    def initialize(root: File.expand_path('../..', __dir__))
+      @root = File.expand_path(root)
+      @ids = JSON.parse(File.read(File.join(@root, 'exercises/catalog.json')))
+      raise Error, 'Invalid exercise catalog: expected unique exercise IDs in order.' unless valid_ids?
+
+      @ids.each(&:freeze)
+      @ids.freeze
+    rescue JSON::ParserError, SystemCallError => e
+      raise Error, "Invalid exercise catalog: #{e.message}"
+    end
+
+    private
+
+    # @return [Boolean] whether IDs are unique, nonempty, and safe for asset paths
+    def valid_ids?
+      @ids.is_a?(Array) && !@ids.empty? && @ids.uniq == @ids &&
+        @ids.all? { |id| id.is_a?(String) && id.match?(/\A[a-z]+(?:-[a-z]+)*\z/) }
+    end
+  end
+end

data/lib/rkoans/checker.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+require 'rbconfig'
+require 'tempfile'
+require 'timeout'
+
+module Rkoans
+  # Runs ordinary Minitest checks in a child process with a time limit.
+  class Checker
+    MAX_KB = 65_536
+    Result = Data.define(:output, :exit_code)
+
+    # @param [Integer | Float] timeout
+    def initialize(timeout: 30)
+      @timeout = timeout
+    end
+
+    # @param [Rkoans::Exercise] exercise
+    # @return [Rkoans::Checker::Result]
+    def run(exercise)
+      Tempfile.create('rkoans-check') do |output|
+        pid = Process.spawn(
+          RbConfig.ruby, '-rminitest/autorun', exercise.checks, exercise.solution,
+          in: File::NULL, out: output, err: output, pgroup: true
+        )
+        begin
+          status = Timeout.timeout(@timeout) { Process.wait2(pid).last }
+          output.rewind
+          Result.new(output.read(MAX_KB), status.exitstatus || 1)
+        rescue Timeout::Error
+          Result.new("Checks timed out after #{@timeout} seconds.\n", 1)
+        ensure
+          stop_group(pid:)
+          begin
+            Process.wait(pid)
+          rescue Errno::ECHILD
+            # The child has already been reaped.
+          end
+        end
+      end
+    end
+
+    private
+
+    # @param [Integer] pid
+    # @return [Integer, nil]
+    def stop_group(pid:)
+      Process.kill('TERM', -pid)
+      sleep 0.05
+      reap_exited_child(pid)
+      Process.kill('KILL', -pid)
+    rescue Errno::ESRCH
+      nil
+    end
+
+    def reap_exited_child(pid)
+      Process.waitpid(pid, Process::WNOHANG)
+    rescue Errno::ECHILD
+      nil
+    end
+  end
+end

data/lib/rkoans/cli.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+module Rkoans
+  # Dispatches the command and renders each check run in the terminal.
+  class CLI
+    # @param [IO] out
+    # @param [IO] err
+    # @param [String] directory
+    # @param catalog [Catalog, nil] ordered exercises used by this component
+    def initialize(out: $stdout, err: $stderr, input: $stdin, directory: File.join(Dir.home, 'ruby-koans'),
+                   catalog: nil)
+      @catalog = catalog
+      @out = out
+      @err = err
+      @directory = directory
+      @input = input
+      @session = nil
+    end
+
+    # @param [Array<String>] arguments
+    # @return [Integer]
+    def run(arguments)
+      @out.sync = true
+      command = arguments.empty? ? 'start' : arguments.first
+      return usage_error if arguments.size > 2 || (arguments.size == 2 && command != 'start')
+
+      dispatch(command, arguments[1])
+    rescue Interrupt
+      @out.puts "\nStopped. Your edits are preserved."
+      130
+    rescue Error, SystemCallError => e
+      @err.puts e.message
+      2
+    end
+
+    private
+
+    # Loads installation data inside run's setup-error handler, only when needed.
+    # @return [Catalog]
+    def catalog
+      @catalog ||= Catalog.new
+    end
+
+    # Creates the interactive coordinator after the catalog has been validated.
+    # @return [Session]
+    def session
+      @session ||= Session.new(directory: @directory, out: @out, input: @input, catalog: catalog)
+    end
+
+    def dispatch(command, id)
+      case command
+      when 'start'
+        session.start(id)
+      when 'check'
+        session.check
+      when 'list'
+        @out.puts catalog.ids
+        0
+      when '--help', '-h'
+        help
+      else
+        usage_error
+      end
+    end
+
+    # @return [Integer]
+    def help
+      @out.puts 'Usage: rkoans [start [EXERCISE]|check|list]'
+      @out.puts 'Start watches your exercise for saves. Ctrl-C exits. No command means start.'
+      0
+    end
+
+    # @return [Integer]
+    def usage_error
+      @err.puts 'Usage: rkoans [start [EXERCISE]|check|list]'
+      2
+    end
+  end
+end

data/lib/rkoans/error.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module Rkoans
+  # Identifies command and installation errors that can be reported without a backtrace.
+  class Error < StandardError; end
+end

data/lib/rkoans/exercise.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+require 'fileutils'
+
+module Rkoans
+  # Locates the packaged exercise and creates its editable learner copy.
+  class Exercise
+    attr_reader :solution, :id
+
+    # @param [String] directory
+    # @param catalog [Catalog] source assets and allowed exercise IDs
+    def initialize(directory: File.join(Dir.home, 'ruby-koans'), catalog: Catalog.new, id: catalog.ids.first)
+      raise Error, "Unknown exercise: #{id}; run rkoans list" unless catalog.ids.include?(id)
+
+      @id = id
+      @root = catalog.root
+      @source = File.join(@root, "exercises/#{id}")
+      @solution = File.join(File.expand_path(directory), 'exercises', id, "#{id.tr('-', '_')}.rb")
+    end
+
+    # @return [Integer, nil]
+    def prepare
+      FileUtils.mkdir_p(File.dirname(solution))
+      File.open(solution, File::WRONLY | File::CREAT | File::EXCL) do |file|
+        file.write(File.read(File.join(@source, File.basename(solution))))
+      end
+    rescue Errno::EEXIST
+      # Starting again preserves the learner's work.
+      nil
+    end
+
+    # @return [String]
+    def instructions
+      File.read(File.join(@source, 'brief.md'))
+    end
+
+    # @return [String]
+    def checks
+      File.join(@root, "test/exercises/#{id.tr('-', '_')}_test.rb")
+    end
+
+    def reference
+      File.join(@root, "solutions/#{id}/#{File.basename(solution)}")
+    end
+
+    def hint
+      File.read(File.join(@source, 'hint.md'))
+    end
+  end
+end

data/lib/rkoans/keyboard.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+require 'io/console'
+require 'io/wait'
+
+module Rkoans
+  # Reads immediate keys while reserving Enter confirmation for next and quit.
+  class Keyboard
+    def initialize(input:)
+      @input = input
+      @pending = nil
+    end
+
+    def with_terminal(&block)
+      if @input&.tty?
+        @input.raw(intr: true, &block)
+      else
+        block.call
+      end
+    end
+
+    def read(interval)
+      unless @input
+        sleep interval
+        return
+      end
+      return unless @input.wait_readable(interval)
+
+      key = @input.read_nonblock(1, exception: false)
+      @input = nil unless key
+      decode(key) if key.is_a?(String)
+    end
+
+    private
+
+    def decode(key)
+      case key
+      when "\n", "\r"
+        command = @pending
+        @pending = nil
+        command
+      when 'n', 'q'
+        @pending = key
+        nil
+      else
+        @pending = nil
+        key unless ["\e", "\b", "\u007f", ' '].include?(key)
+      end
+    end
+  end
+end

data/lib/rkoans/progress.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'fileutils'
+require 'tempfile'
+
+module Rkoans
+  # Stores completed exercise IDs independently of the current selection.
+  class Progress
+    # @param catalog [Catalog] ordered exercises used by this component
+    def initialize(directory:, catalog: Catalog.new)
+      @catalog = catalog
+      @path = File.join(directory, '.rkoans', 'completed.json')
+    end
+
+    def completed
+      ids = JSON.parse(File.read(@path))
+      raise Error, "Invalid progress file: #{@path}" unless ids.is_a?(Array) && ids.all?(String)
+
+      ids & @catalog.ids
+    rescue Errno::ENOENT
+      []
+    rescue JSON::ParserError
+      raise Error, "Invalid progress file: #{@path}"
+    end
+
+    def mark_done(id)
+      ids = completed
+      return if ids.include?(id)
+
+      FileUtils.mkdir_p(File.dirname(@path))
+      Tempfile.create('completed', File.dirname(@path)) do |file|
+        file.write(JSON.generate(ids + [id]))
+        file.close
+        File.rename(file.path, @path)
+      end
+    end
+  end
+end

data/lib/rkoans/selection.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+require 'fileutils'
+require 'tempfile'
+
+module Rkoans
+  # Remembers the active exercise without changing any learner files.
+  class Selection
+    # @param catalog [Catalog] ordered exercises used by this component
+    def initialize(directory:, catalog: Catalog.new)
+      @catalog = catalog
+      @path = File.join(directory, '.rkoans', 'selection')
+    end
+
+    def read
+      File.read(@path).strip
+    rescue Errno::ENOENT
+      @catalog.ids.first
+    end
+
+    def write(id)
+      directory = File.dirname(@path)
+      FileUtils.mkdir_p(directory)
+      Tempfile.create('selection', directory) do |file|
+        file.write("#{id}\n")
+        file.close
+        File.rename(file.path, @path)
+      end
+    end
+  end
+end

data/lib/rkoans/session.rb

@@ -0,0 +1,127 @@
+# frozen_string_literal: true
+
+module Rkoans
+  # Coordinates checks, file watching, keyboard commands, and completion.
+  class Session
+    # @param catalog [Catalog] ordered exercises used by this component
+    def initialize(directory:, out:, input:, catalog: Catalog.new)
+      @catalog = catalog
+      @directory = directory
+      @input = input
+      @listing = false
+      @selection = Selection.new(directory: directory, catalog: catalog)
+      @checker = Checker.new
+      @progress = Progress.new(directory: directory, catalog: catalog)
+      @view = TerminalView.new(out: out, catalog: catalog)
+    end
+
+    # Keeps the current exercise open until the user advances or quits.
+    def start(id)
+      selected = id || @selection.read
+      loop do
+        activate(selected)
+        action = watch
+        return 0 if action == :quit
+
+        selected = action
+      end
+    end
+
+    # @return [Integer]
+    def check
+      @exercise = Exercise.new(directory: @directory, id: @selection.read, catalog: @catalog)
+      raise Error, 'No exercise found. Run rkoans start first.' unless File.file?(@exercise.solution)
+
+      show_checks(watching: false)
+    end
+
+    private
+
+    def activate(id)
+      @listing = false
+      @exercise = Exercise.new(directory: @directory, id: id, catalog: @catalog)
+      @exercise.prepare
+      @selection.write(id)
+    end
+
+    def watch
+      catch(:session_action) do
+        Watcher.new(@exercise.solution).run(input: @input) do |command|
+          command ? handle_command(command) : show_checks(watching: true)
+        end
+      end
+    end
+
+    def handle_command(command)
+      case command
+      when 'n'
+        @listing = false
+        advance
+      when 'q'
+        show_message('Stopped. Your edits are preserved.', watching: false)
+        throw :session_action, :quit
+      when 'l', 's'
+        @listing = command == 'l'
+        show_checks(watching: true)
+      when 'h' then show_hint
+      when '?' then show_message(TerminalView::HELP)
+      else
+        show_message('Press ? for keyboard help.')
+      end
+    end
+
+    def advance
+      result = check_result
+      unless result.exit_code.zero?
+        render(result, watching: true, message: 'Finish the current exercise before moving on.')
+        return
+      end
+      ids = @catalog.ids
+      next_id = ids[ids.index(@exercise.id) + 1]
+      throw :session_action, next_id if next_id
+
+      message = if @progress.completed.size == ids.size
+                  'All exercises complete. You can keep experimenting or enter q to quit.'
+                else
+                  'No next exercise. Other exercises remain; enter l to list them or q to quit.'
+                end
+      render(result, watching: true, message: message)
+    end
+
+    # @param [Boolean] watching
+    # @return [Integer]
+    def show_checks(watching:)
+      render(check_result, watching: watching)
+    end
+
+    def check_result
+      result = @checker.run(@exercise)
+      @passed = result.exit_code.zero?
+      @progress.mark_done(@exercise.id) if @passed
+      result
+    end
+
+    def render(result, watching:, message: nil)
+      if watching && @listing
+        @view.show_list(exercise: @exercise, completed: @progress.completed, passed: @passed)
+      else
+        @view.render(exercise: @exercise, result: result, completed: @progress.completed,
+                     watching: watching, message: message)
+      end
+      result.exit_code
+    end
+
+    def show_message(message, watching: true)
+      mode = @listing ? :list : :current
+      mode = :quit unless watching
+      @view.show_message(message, exercise: @exercise, completed: @progress.completed,
+                                  passed: @passed, mode: mode)
+    end
+
+    def show_hint
+      return if @listing || @passed
+
+      show_message(@exercise.hint)
+    end
+  end
+end