playoffs 1.0.0

data/lib/playoffs/basketball.rb

@@ -0,0 +1,120 @@
+# typed: strict
+# frozen_string_literal: true
+
+module Playoffs
+  # Knows how to create a tournament specific to professional basketball.
+  class Basketball
+    extend T::Sig
+
+    # rubocop:disable Metrics/MethodLength, Metrics/AbcSize
+    sig do
+      params(
+        eastern_teams: T::Array[Team],
+        western_teams: T::Array[Team]
+      ).returns(Tournament)
+    end
+    def self.tournament_for(eastern_teams:, western_teams:)
+      eastern_teams = eastern_teams.uniq
+      western_teams = western_teams.uniq
+
+      raise IncorrectTeamCount unless eastern_teams.size == 10
+      raise IncorrectTeamCount unless western_teams.size == 10
+
+      play_in_best_of = BestOf.new(1)
+
+      eastern_play_in78 = Series.new(best_of: play_in_best_of)
+        .register(T.must(eastern_teams[6]))
+        .register(T.must(eastern_teams[7]))
+
+      eastern_play_in910 = Series
+        .new(best_of: play_in_best_of)
+        .register(T.must(eastern_teams[8]))
+        .register(T.must(eastern_teams[9]))
+
+      eastern_play_in_consolation = Series
+        .new(best_of: play_in_best_of)
+        .loser_of(eastern_play_in78)
+        .winner_of(eastern_play_in910)
+
+      western_play_in78 = Series
+        .new(best_of: play_in_best_of)
+        .register(T.must(western_teams[6]))
+        .register(T.must(western_teams[7]))
+
+      western_play_in910 = Series
+        .new(best_of: play_in_best_of)
+        .register(T.must(western_teams[8]))
+        .register(T.must(western_teams[9]))
+
+      western_play_in_consolation = Series
+        .new(best_of: play_in_best_of)
+        .loser_of(western_play_in78)
+        .loser_of(western_play_in910)
+
+      championship =
+        Series
+          .new
+          .winner_of(
+            Series.new
+              .winner_of(
+                Series.new
+                  .winner_of(
+                    Series.new
+                      .register(T.must(eastern_teams[0]))
+                      .winner_of(eastern_play_in_consolation)
+                  )
+                  .winner_of(
+                    Series.new
+                      .register(T.must(eastern_teams[3]))
+                      .register(T.must(eastern_teams[4]))
+                  )
+              )
+              .winner_of(
+                Series.new
+                  .winner_of(
+                    Series.new
+                      .register(T.must(eastern_teams[2]))
+                      .register(T.must(eastern_teams[5]))
+                  )
+                  .winner_of(
+                    Series.new
+                      .register(T.must(eastern_teams[1]))
+                      .winner_of(eastern_play_in78)
+                  )
+              )
+          )
+          .winner_of(
+            Series.new
+              .winner_of(
+                Series.new
+                  .winner_of(
+                    Series.new
+                      .register(T.must(western_teams[0]))
+                      .winner_of(western_play_in_consolation)
+                  )
+                  .winner_of(
+                    Series.new
+                      .register(T.must(western_teams[3]))
+                      .register(T.must(western_teams[4]))
+                  )
+              )
+              .winner_of(
+                Series.new
+                  .winner_of(
+                    Series.new
+                      .register(T.must(western_teams[2]))
+                      .register(T.must(western_teams[5]))
+                  )
+                  .winner_of(
+                    Series.new
+                      .register(T.must(western_teams[1]))
+                      .winner_of(western_play_in78)
+                  )
+              )
+          )
+
+      Tournament.new(championship)
+    end
+    # rubocop:enable Metrics/MethodLength, Metrics/AbcSize
+  end
+end

data/lib/playoffs/best_of.rb

@@ -0,0 +1,38 @@
+# typed: strict
+# frozen_string_literal: true
+
+module Playoffs
+  # Contains rules for how many total a series can be.
+  class BestOf
+    extend T::Sig
+
+    sig { returns(Integer) }
+    attr_reader :total
+
+    sig { params(total: Integer).void }
+    def initialize(total = 7)
+      raise ArgumentError, 'total has to be positive' unless total.positive?
+      raise ArgumentError, 'total has to be odd' unless total.odd?
+
+      @total = total
+
+      freeze
+    end
+
+    sig { returns(Integer) }
+    def to_win
+      (total / 2.0).ceil
+    end
+
+    sig { returns(String) }
+    def to_s
+      "#{self.class.to_s.split('::').last}::#{total}"
+    end
+
+    sig { params(other: BestOf).returns(T::Boolean) }
+    def ==(other)
+      total == other.total
+    end
+    alias eql? ==
+  end
+end

data/lib/playoffs/cli.rb

@@ -0,0 +1,201 @@
+# typed: strict
+# frozen_string_literal: true
+
+module Playoffs
+  # A very simple list of commands matching ARGV as input. Allows for capturing the output
+  # via the passed in IO object used for construction. This class is an example of how the
+  # underlying data structures, such as: BestOf, Round, Series, Team, and Tournament,
+  # in this library can be used.
+  class Cli
+    extend T::Sig
+
+    sig { returns(T.any(IO, StringIO)) }
+    attr_reader :io
+
+    sig { returns(String) }
+    attr_reader :script
+
+    sig { params(io: T.any(IO, StringIO), script: String).void }
+    def initialize(io, script: 'bin/playoffs')
+      @io = io
+      @script = script
+    end
+
+    sig { params(args: T::Array[String]).returns(Cli) }
+    def run(args)
+      path = args[0].to_s
+      action = args[1].to_s
+
+      if path.empty? && action.empty?
+        run_help(path, action, args)
+
+        return self
+      end
+
+      action = 'bracket' if action.empty?
+
+      method_name = "run_#{action}"
+
+      if respond_to?(method_name, true)
+        send(method_name, path, action, args)
+      else
+        io.puts("Unknown: #{action}")
+      end
+
+      self
+    end
+
+    protected
+
+    sig { overridable.params(path: String, tournament: Tournament).returns(Cli) }
+    def save(path, tournament)
+      FileUtils.mkdir_p(File.dirname(path))
+
+      File.open(path, 'w') { |out| YAML.dump(tournament, out) }
+
+      self
+    end
+
+    sig { overridable.params(path: String).returns(Tournament) }
+    def load(path)
+      YAML.load_file(
+        path,
+        permitted_classes: [
+          BestOf,
+          Round,
+          Series,
+          Team,
+          Tournament
+        ],
+        aliases: true
+      )
+    end
+
+    sig { overridable.params(series: Series).returns(Team) }
+    def pick(series)
+      index = rand(0..1)
+
+      T.must(series.teams[index])
+    end
+
+    private
+
+    # rubocop:disable Metrics/AbcSize
+    sig { params(_path: String, _action: String, _args: T::Array[String]).returns(Cli) }
+    def run_help(_path, _action, _args)
+      io.puts('Usage:')
+      io.puts("  Help:                   #{script}")
+      io.puts("  Generate New Playoff:   #{script} <path> new <team_ids>")
+      io.puts("  View Bracket:           #{script} <path>")
+      io.puts("  View All Rounds:        #{script} <path> rounds")
+      io.puts("  View Next Round/Series: #{script} <path> up")
+      io.puts("  Log Next Game Winner:   #{script} <path> win <team_id>")
+      io.puts("  Random Simulation:      #{script} <path> sim")
+      io.puts("  Winner:                 #{script} <path> winner")
+      io.puts
+      io.puts('Where:')
+      io.puts('  <path> is a path to a YAML file.')
+      io.puts('  <team_ids> is a list of 20 team IDs separated by a comma.')
+      io.puts
+      io.puts('Example(s):')
+      io.puts("  #{script} 2024.yaml new BOS,NYK,MIL,CLE,ORL,IND,PHI,MIA,CHI,ATL,OKC,DEN,MIN,LAC,DAL,PHX,LAL,NO,SAC,GS")
+      io.puts("  #{script} 2024.yaml")
+      io.puts("  #{script} 2024.yaml rounds")
+      io.puts("  #{script} 2024.yaml up")
+      io.puts("  #{script} 2024.yaml win MIA")
+      io.puts("  #{script} 2024.yaml sim")
+      io.puts("  #{script} 2024.yaml winner")
+
+      self
+    end
+    # rubocop:enable Metrics/AbcSize
+
+    sig { params(path: String, _action: String, args: T::Array[String]).returns(Cli) }
+    def run_new(path, _action, args)
+      ids = args[2].to_s.split(',')
+      teams = ids.map { |id| Team.new(id) }
+      eastern_teams = teams[0..9] || []
+      western_teams = teams[10..19] || []
+
+      tournament = Basketball.tournament_for(eastern_teams:, western_teams:)
+
+      save(path, tournament)
+
+      self
+    end
+
+    sig { params(path: String, _action: String, _args: T::Array[String]).returns(Cli) }
+    def run_bracket(path, _action, _args)
+      io.puts(load(path).print_bracket)
+
+      self
+    end
+
+    sig { params(path: String, _action: String, _args: T::Array[String]).returns(Cli) }
+    def run_rounds(path, _action, _args)
+      io.puts(load(path).print_rounds)
+
+      self
+    end
+
+    sig { params(path: String, _action: String, _args: T::Array[String]).returns(Cli) }
+    def run_up(path, _action, _args)
+      tournament = load(path)
+
+      series = tournament.up_next
+
+      io.puts(tournament.up_next) if series
+
+      self
+    end
+
+    sig { params(path: String, _action: String, args: T::Array[String]).returns(Cli) }
+    def run_win(path, _action, args)
+      id = args[2].to_s
+
+      team = Team.new(id)
+      tournament = load(path)
+      series = tournament.up_next
+
+      T.must(series).win(team)
+
+      io.puts(series)
+
+      save(path, tournament)
+
+      self
+    end
+
+    sig { params(path: String, _action: String, _args: T::Array[String]).returns(Cli) }
+    def run_sim(path, _action, _args)
+      tournament = load(path)
+
+      total = 0
+      # while not nil (and assign series)
+      while (series = tournament.up_next)
+        team = pick(series)
+
+        series.win(team)
+
+        total += 1
+      end
+
+      io.puts(total.to_s)
+
+      io.puts(tournament.winner.to_s)
+
+      save(path, tournament)
+
+      self
+    end
+
+    sig { params(path: String, _action: String, _args: T::Array[String]).returns(Cli) }
+    def run_winner(path, _action, _args)
+      tournament = load(path)
+
+      io.puts(tournament.winner) if tournament.over?
+
+      self
+    end
+  end
+end

data/lib/playoffs/contestant.rb

@@ -0,0 +1,8 @@
+# typed: strict
+# frozen_string_literal: true
+
+module Playoffs
+  # A contestant is an object that feeds into a series which can either be a winner/loser
+  # of another series or a team.
+  Contestant = T.type_alias { T.any(Series, Team) }
+end

data/lib/playoffs/round.rb

@@ -0,0 +1,42 @@
+# typed: strict
+# frozen_string_literal: true
+
+module Playoffs
+  # Represents a group of series that can be played at the same time.
+  class Round
+    extend T::Sig
+
+    sig { returns(T::Array[Series]) }
+    attr_reader :series
+
+    sig { params(series: T::Array[Series]).void }
+    def initialize(series)
+      @series = series
+    end
+
+    sig { returns(String) }
+    def to_s
+      series.map(&:to_s).join("\n")
+    end
+
+    sig { returns(T.nilable(Series)) }
+    def up_next
+      not_over.first
+    end
+
+    sig { returns(T::Boolean) }
+    def over?
+      not_over.empty?
+    end
+
+    sig { returns(T::Boolean) }
+    def not_over?
+      !over?
+    end
+
+    sig { returns(T::Array[Series]) }
+    def not_over
+      series.reject(&:over?).sort_by(&:games_played)
+    end
+  end
+end

data/lib/playoffs/series.rb

@@ -0,0 +1,167 @@
+# typed: strict
+# frozen_string_literal: true
+
+module Playoffs
+  # A node in a directed acyclic graph which represents a current or future series between two teams.
+  # The teams are able to be resolved later in the graph by connecting series together:
+  # a contestestant does not have to be a team, it can be the promise of a team via
+  # another series (as the winner or loser).
+  class Series
+    extend T::Sig
+
+    sig { returns(T::Array[Contestant]) }
+    attr_reader :contestants
+
+    sig { returns(T.nilable(Series)) }
+    attr_accessor :winner_advances_to
+
+    sig { returns(T.nilable(Series)) }
+    attr_accessor :loser_advances_to
+
+    sig { returns(BestOf) }
+    attr_reader :best_of
+
+    sig { returns(T::Array[Team]) }
+    attr_reader :winners_by_game
+
+    sig { returns(T.nilable(Team)) }
+    attr_reader :winner
+
+    sig { params(best_of: BestOf).void }
+    def initialize(best_of: BestOf.new)
+      @contestants = T.let([], T::Array[Contestant])
+      @best_of = best_of
+      @winners_by_game = T.let([], T::Array[Team])
+    end
+
+    sig { returns(T::Array[Team]) }
+    def teams
+      contestants.map do |contestant|
+        case contestant
+        when Team
+          contestant
+        when Series
+          contestant.winner_advances_to == self ? contestant.winner : contestant.loser
+        else
+          T.absurd(contestant)
+        end
+      end.compact
+    end
+
+    sig { returns(T.nilable(Team)) }
+    def loser
+      return unless winner
+
+      (teams - [winner]).first
+    end
+
+    sig { params(team: Team).returns(Series) }
+    def win(team)
+      raise NotEnoughTeamsError unless teams.length == 2
+
+      saved_team = teams.find { |t| t == team }
+
+      raise InvalidTeamError unless saved_team
+      raise SeriesOverError if over?
+
+      winners_by_game << saved_team
+
+      @winner = T.let(saved_team, T.nilable(Team)) if winner?(saved_team)
+
+      self
+    end
+
+    sig { returns(Integer) }
+    def games_played
+      winners_by_game.length
+    end
+
+    sig { returns(T::Boolean) }
+    def over?
+      !not_over?
+    end
+
+    sig { returns(T::Boolean) }
+    def not_over?
+      winner.nil?
+    end
+
+    sig { returns(T::Boolean) }
+    def valid?
+      return false if contestants.length != 2
+
+      contestants.each do |contestant|
+        case contestant
+        when Team
+          # Teams are always valid
+        when Series
+          # short-circuit because we cant be valid if the previous series (children) aren't.
+          return false unless contestant.valid?
+        else
+          T.absurd(contestant)
+        end
+      end
+
+      true
+    end
+
+    sig { params(team: Team).returns(Integer) }
+    def win_count_for(team)
+      winners_by_game.select { |winner| winner == team }.length
+    end
+
+    # rubocop:disable Metrics/AbcSize
+    sig { returns(String) }
+    def to_s
+      team_lines = teams.map do |contestant|
+        [contestant.to_s, win_count_for(contestant)]
+      end
+
+      team_lines += [['TBD', 0]] * (2 - team_lines.length)
+
+      [
+        valid? ? nil : '!INVALID!',
+        best_of.to_s,
+        self.class.to_s.split('::').last,
+        team_lines,
+        over? ? 'Done' : nil
+      ].compact.flatten.join('::')
+    end
+    # rubocop:enable Metrics/AbcSize
+
+    sig { params(series: Series).returns(Series) }
+    def winner_of(series)
+      series.winner_advances_to = self
+
+      add(series)
+    end
+
+    sig { params(series: Series).returns(Series) }
+    def loser_of(series)
+      series.loser_advances_to = self
+
+      add(series)
+    end
+
+    sig { params(team: Team).returns(Series) }
+    def register(team)
+      add(team)
+    end
+
+    private
+
+    sig { params(team: Team).returns(T::Boolean) }
+    def winner?(team)
+      winners_by_game.select { |w| w == team }.length == best_of.to_win
+    end
+
+    sig { params(contestant: Contestant).returns(Series) }
+    def add(contestant)
+      raise ArgumentError, 'No more than two contestants allowed.' if contestants.length >= 2
+
+      contestants << contestant
+
+      self
+    end
+  end
+end

data/lib/playoffs/team.rb

@@ -0,0 +1,7 @@
+# typed: strict
+# frozen_string_literal: true
+
+module Playoffs
+  # Represents a team in the context of playoffs.
+  class Team < Primitive::Entity; end
+end

data/lib/playoffs/tournament/bracketable.rb

@@ -0,0 +1,93 @@
+# typed: strict
+# frozen_string_literal: true
+
+module Playoffs
+  # Print out a basic, tree-based, text hierarchy of all series.
+  module Bracketable
+    extend T::Helpers
+    extend T::Sig
+
+    abstract!
+
+    sig { abstract.returns(Series) }
+    def championship; end
+
+    sig { returns(String) }
+    def print_bracket
+      top_line =
+        if championship.valid? && championship.over?
+          championship.winner.to_s
+        elsif championship.valid?
+          'TBD'
+        else
+          '!INVALID!'
+        end
+
+      ([top_line] + traverse_to_s(championship)).join("\n")
+    end
+
+    private
+
+    # rubocop:disable Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
+    sig do
+      params(
+        series: Series,
+        next_series: T.nilable(Series),
+        depth: Integer,
+        draw_sibling_depths: T::Array[Integer]
+      ).returns(String)
+    end
+    def series_line(series, next_series = nil, depth = 0, draw_sibling_depths = [])
+      type =
+        if next_series && next_series == series.loser_advances_to
+          '::LoserAdvances'
+        elsif next_series && series.loser_advances_to
+          '::WinnerAdvances'
+        end
+
+      line = ''
+
+      (0...depth).each do |d|
+        line += (draw_sibling_depths.include?(d) ? '│ ' : '  ')
+      end
+
+      current_char =
+        if depth.positive? && draw_sibling_depths.include?(depth)
+          '├ '
+        else
+          '└ '
+        end
+
+      line + "#{current_char}#{series}#{type}"
+    end
+    # rubocop:enable Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
+
+    # rubocop:disable Metrics/ParameterLists
+    sig do
+      params(
+        series: Series,
+        next_series: T.nilable(Series),
+        depth: Integer,
+        lines: T::Array[String],
+        draw_sibling_depths: T::Array[Integer]
+      ).returns(T::Array[String])
+    end
+    def traverse_to_s(series, next_series = nil, depth = 0, lines = [], draw_sibling_depths = [])
+      lines << series_line(series, next_series, depth, draw_sibling_depths)
+
+      series.contestants.each_with_index do |contestant, index|
+        new_siblings_depths =
+          if index < series.contestants.length - 1
+            draw_sibling_depths + [depth + 1]
+          else
+            draw_sibling_depths
+          end
+
+        traverse_to_s(contestant, series, depth + 1, lines, new_siblings_depths) if contestant.is_a?(Series)
+      end
+
+      lines
+    end
+    # rubocop:enable Metrics/ParameterLists
+  end
+end