basketball 0.0.5 → 0.0.7

data/lib/basketball/scheduling/calendar.rb

@@ -0,0 +1,121 @@
+# frozen_string_literal: true
+
+module Basketball
+  module Scheduling
+    class Calendar < ValueObject
+      class TeamAlreadyBookedError < StandardError; end
+      class InvalidGameOrderError < StandardError; end
+      class OutOfBoundsError < StandardError; end
+
+      attr_reader :preseason_start_date,
+                  :preseason_end_date,
+                  :season_start_date,
+                  :season_end_date
+
+      attr_reader_value :year, :games
+
+      def initialize(year:, games: [])
+        super()
+
+        raise ArgumentError, 'year is required' unless year
+
+        @year                 = year
+        @preseason_start_date = Date.new(year, 9, 30)
+        @preseason_end_date   = Date.new(year, 10, 14)
+        @season_start_date    = Date.new(year, 10, 18)
+        @season_end_date      = Date.new(year + 1, 4, 29)
+        @games                = []
+
+        games.each { |game| add!(game) }
+
+        freeze
+      end
+
+      def add!(game)
+        assert_in_bounds(game)
+        assert_free_date(game)
+
+        @games << game
+
+        self
+      end
+
+      def preseason_games_for(date: nil, team: nil)
+        games_for(date:, team:).select { |game| game.is_a?(PreseasonGame) }
+      end
+
+      def season_games_for(date: nil, team: nil)
+        games_for(date:, team:).select { |game| game.is_a?(SeasonGame) }
+      end
+
+      def games_for(date: nil, team: nil)
+        games.select do |game|
+          (date.nil? || game.date == date) &&
+            (team.nil? || (game.home_team == team || game.away_team == team))
+        end
+      end
+
+      def available_preseason_dates_for(team)
+        all_preseason_dates - preseason_games_for(team:).map(&:date)
+      end
+
+      def available_season_dates_for(team)
+        all_season_dates - season_games_for(team:).map(&:date)
+      end
+
+      def available_preseason_matchup_dates(team1, team2)
+        available_team_dates       = available_preseason_dates_for(team1)
+        available_other_team_dates = available_preseason_dates_for(team2)
+
+        available_team_dates & available_other_team_dates
+      end
+
+      def available_season_matchup_dates(team1, team2)
+        available_team_dates       = available_season_dates_for(team1)
+        available_other_team_dates = available_season_dates_for(team2)
+
+        available_team_dates & available_other_team_dates
+      end
+
+      def teams
+        games.flat_map(&:teams)
+      end
+
+      def team(id)
+        teams.find { |t| t == Team.new(id:) }
+      end
+
+      private
+
+      def all_preseason_dates
+        (preseason_start_date..preseason_end_date).to_a
+      end
+
+      def all_season_dates
+        (season_start_date..season_end_date).to_a
+      end
+
+      def assert_free_date(game)
+        if games_for(date: game.date, team: game.home_team).any?
+          raise TeamAlreadyBookedError, "#{game.home_team} already playing on #{game.date}"
+        end
+
+        return unless games_for(date: game.date, team: game.away_team).any?
+
+        raise TeamAlreadyBookedError, "#{game.away_team} already playing on #{game.date}"
+      end
+
+      def assert_in_bounds(game)
+        if game.is_a?(PreseasonGame)
+          raise OutOfBoundsError, "#{game.date} is before preseason begins" if game.date < preseason_start_date
+          raise OutOfBoundsError, "#{game.date} is after preseason ends"    if game.date > preseason_end_date
+        elsif game.is_a?(SeasonGame)
+          raise OutOfBoundsError, "#{game.date} is before season begins" if game.date < season_start_date
+          raise OutOfBoundsError, "#{game.date} is after season ends"    if game.date > season_end_date
+        else
+          raise ArgumentError, "Dont know what this game type is: #{game.class.name}"
+        end
+      end
+    end
+  end
+end

data/lib/basketball/scheduling/calendar_serializer.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+require_relative 'game'
+require_relative 'preseason_game'
+require_relative 'season_game'
+
+module Basketball
+  module Scheduling
+    class CalendarSerializer
+      GAME_CLASSES = {
+        'PreseasonGame' => PreseasonGame,
+        'SeasonGame' => SeasonGame
+      }.freeze
+
+      def to_hash(calendar)
+        teams = calendar.games.flat_map(&:teams).uniq
+
+        {
+          'year' => calendar.preseason_start_date.year,
+          'teams' => serialize_teams(teams),
+          'games' => serialize_games(calendar.games)
+        }
+      end
+
+      def from_hash(json)
+        Calendar.new(
+          year: json['year'].to_i,
+          games: deserialize_games(json)
+        )
+      end
+
+      def deserialize(string)
+        json = JSON.parse(string)
+
+        from_hash(json)
+      end
+
+      def serialize(calendar)
+        to_hash(calendar).to_json
+      end
+
+      private
+
+      ## Deserialization
+
+      def deserialize_games(json)
+        teams = deserialize_teams(json['teams'])
+
+        (json['games'] || []).map do |game_hash|
+          GAME_CLASSES.fetch(game_hash['type']).new(
+            date: Date.parse(game_hash['date']),
+            home_team: teams.fetch(game_hash['home_team']),
+            away_team: teams.fetch(game_hash['away_team'])
+          )
+        end
+      end
+
+      def deserialize_teams(teams)
+        (teams || []).to_h do |id, team_hash|
+          team = Team.new(id:, name: team_hash['name'])
+
+          [
+            team.id,
+            team
+          ]
+        end
+      end
+
+      ## Serialization
+
+      def serialize_teams(teams)
+        teams.to_h do |team|
+          [
+            team.id,
+            {
+              'name' => team.name
+            }
+          ]
+        end
+      end
+
+      def serialize_games(games)
+        games.sort_by(&:date).map do |game|
+          {
+            'type' => game.class.name.split('::').last,
+            'date' => game.date.to_s,
+            'home_team' => game.home_team.id,
+            'away_team' => game.away_team.id
+          }
+        end
+      end
+    end
+  end
+end

data/lib/basketball/scheduling/cli.rb

@@ -0,0 +1,198 @@
+# frozen_string_literal: true
+
+require_relative 'calendar_serializer'
+require_relative 'conference'
+require_relative 'coordinator'
+require_relative 'division'
+require_relative 'league'
+require_relative 'league_serializer'
+require_relative 'team'
+
+module Basketball
+  module Scheduling
+    # Examples:
+    #   exe/basketball-schedule -o tmp/league.json
+    #   exe/basketball-schedule -i tmp/league.json -o tmp/calendar.json
+    #   exe/basketball-schedule -i tmp/league.json -o tmp/calendar.json -y 2005
+    #   exe/basketball-schedule -c tmp/calendar.json
+    #   exe/basketball-schedule -c tmp/calendar.json -t C0-D0-T0
+    #   exe/basketball-schedule -c tmp/calendar.json -d 2005-02-03
+    #   exe/basketball-schedule -c tmp/calendar.json -d 2005-02-03 -t C0-D0-T0
+    class CLI
+      attr_reader :opts,
+                  :league_serializer,
+                  :calendar_serializer,
+                  :io,
+                  :coordinator
+
+      def initialize(args:, io: $stdout)
+        @io                  = io
+        @opts                = slop_parse(args)
+        @league_serializer   = LeagueSerializer.new
+        @calendar_serializer = CalendarSerializer.new
+        @coordinator         = Coordinator.new
+
+        freeze
+      end
+
+      def invoke!
+        if output?
+          out_dir = File.dirname(output)
+          FileUtils.mkdir_p(out_dir)
+        end
+
+        if output? && no_input?
+          execute_with_no_input
+        elsif output?
+          execute_with_input
+        end
+
+        output_cal_query if cal
+
+        self
+      end
+
+      private
+
+      def output_cal_query
+        contents      = File.read(cal)
+        calendar      = calendar_serializer.deserialize(contents)
+        team_instance = team ? calendar.team(team) : nil
+        games         = calendar.games_for(date:, team: team_instance).sort_by(&:date)
+        pre_counter   = 1
+        counter       = 1
+
+        io.puts("Games for [team: #{team}, date: #{date}]")
+        games.each do |game|
+          if game.is_a?(PreseasonGame)
+            io.puts("##{pre_counter} - #{game}")
+            pre_counter += 1
+          else
+            io.puts("##{counter} - #{game}")
+            counter += 1
+          end
+        end
+      end
+
+      def execute_with_input
+        io.puts("Loading league from: #{input}")
+
+        contents = File.read(input)
+        league   = league_serializer.deserialize(contents)
+
+        io.puts("Generating calendar for the year #{year}...")
+
+        calendar = coordinator.schedule(league:, year:)
+        contents = calendar_serializer.serialize(calendar)
+
+        File.write(output, contents)
+
+        io.puts("Calendar written to: #{output}")
+      end
+
+      def execute_with_no_input
+        league   = generate_league
+        contents = league_serializer.serialize(league)
+
+        File.write(output, contents)
+
+        io.puts("League written to: #{output}")
+      end
+
+      def cal
+        opts[:cal].to_s.empty? ? nil : opts[:cal]
+      end
+
+      def team
+        opts[:team].to_s.empty? ? nil : opts[:team]
+      end
+
+      def date
+        opts[:date].to_s.empty? ? nil : Date.parse(opts[:date])
+      end
+
+      def year
+        opts[:year].to_s.empty? ? Date.today.year : opts[:year]
+      end
+
+      def no_input?
+        input.to_s.empty?
+      end
+
+      def input
+        opts[:input]
+      end
+
+      def output?
+        !output.to_s.empty?
+      end
+
+      def output
+        opts[:output]
+      end
+
+      def generate_conferences
+        2.times.map do |i|
+          id = "C#{i}"
+
+          Conference.new(
+            id:,
+            name: Faker::Esport.league,
+            divisions: generate_divisions("#{id}-")
+          )
+        end
+      end
+
+      def generate_divisions(id_prefix)
+        3.times.map do |j|
+          id = "#{id_prefix}D#{j}"
+
+          Division.new(
+            id:,
+            name: Faker::Address.community,
+            teams: generate_teams("#{id}-")
+          )
+        end
+      end
+
+      def generate_teams(id_prefix)
+        5.times.map do |k|
+          Team.new(
+            id: "#{id_prefix}T#{k}",
+            name: Faker::Team.name
+          )
+        end
+      end
+
+      def generate_league
+        League.new(conferences: generate_conferences)
+      end
+
+      def slop_parse(args)
+        Slop.parse(args) do |o|
+          o.banner = 'Usage: basketball-schedule [options] ...'
+
+          output_description = <<~DESC
+            If input path is omitted then a new league will be written to this path.
+            If an input path is specified then a Calendar will be written to the output path.
+          DESC
+
+          # League and Calendar Generation Interface
+          o.string  '-i', '--input',  'Path to load the League from. If omitted then a new league will be generated.'
+          o.string  '-o', '--output', output_description
+          o.integer '-y', '--year',   'Year to use to generate a calendar for (defaults to current year).'
+
+          # Calendar Query Interface
+          o.string  '-c', '--cal',  'Path to load a Calendar from. If omitted then no matchups will be outputted.'
+          o.string  '-d', '--date', 'Filter matchups to just the date specified (requires --cal option).'
+          o.string  '-t', '--team', 'Filter matchups to just the team ID specified (requires --cal option).'
+
+          o.on '-h', '--help', 'Print out help, like this is doing right now.' do
+            io.puts(o)
+            exit
+          end
+        end.to_h
+      end
+    end
+  end
+end

data/lib/basketball/scheduling/conference.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module Basketball
+  module Scheduling
+    class Conference < Entity
+      DIVISIONS_SIZE = 3
+
+      attr_reader :name, :divisions
+
+      def initialize(id:, name: '', divisions: [])
+        super(id)
+
+        @name      = name.to_s
+        @divisions = []
+
+        divisions.each { |d| register_division!(d) }
+
+        if divisions.length != DIVISIONS_SIZE
+          raise BadDivisionsSizeError, "#{id} should have exactly #{DIVISIONS_SIZE} divisions"
+        end
+
+        freeze
+      end
+
+      def to_s
+        (["[#{super}] #{name}"] + divisions.map(&:to_s)).join("\n")
+      end
+
+      def division?(division)
+        divisions.include?(division)
+      end
+
+      def teams
+        divisions.flat_map(&:teams)
+      end
+
+      def team?(team)
+        teams.include?(team)
+      end
+
+      private
+
+      def register_division!(division)
+        raise ArgumentError, 'division is required' unless division
+        raise DivisionAlreadyRegisteredError, "#{division} already registered" if division?(division)
+
+        division.teams.each do |team|
+          raise TeamAlreadyRegisteredError, "#{team} already registered" if team?(team)
+        end
+
+        divisions << division
+
+        self
+      end
+    end
+  end
+end

data/lib/basketball/scheduling/coordinator.rb

@@ -0,0 +1,180 @@
+# frozen_string_literal: true
+
+require_relative 'calendar'
+
+module Basketball
+  module Scheduling
+    # This is the service class responsible for actually picking out free dates ane pairing up teams to
+    # play each other.  This is a reasonable naive first pass at some underlying match-making algorithms
+    # but could definitely use some help with the complexity/runtime/etc.
+    class Coordinator
+      MIN_PRESEASON_GAMES_PER_TEAM = 4
+      MAX_PRESEASON_GAMES_PER_TEAM = 6
+
+      private_constant :MIN_PRESEASON_GAMES_PER_TEAM,
+                       :MAX_PRESEASON_GAMES_PER_TEAM
+
+      def schedule(year:, league:)
+        Calendar.new(year:).tap do |calendar|
+          schedule_preseason!(calendar:, league:)
+          schedule_season!(calendar:, league:)
+        end
+      end
+
+      private
+
+      def base_matchup_count(league, team1, team2)
+        # Same Conference, Same Division
+        if league.division_for(team1) == league.division_for(team2)
+          4
+        # Same Conference, Different Division  and one of 4/10 that play 3 times
+        elsif league.conference_for(team1) == league.conference_for(team2)
+          3
+        # Different Conference
+        else
+          2
+        end
+      end
+
+      # rubocop:disable Metrics/AbcSize
+      # This method derives the plan for which a schedule can be generated from.
+      def matchup_plan(league)
+        matchups    = {}
+        game_counts = league.teams.to_h { |t| [t, 0] }
+        teams       = game_counts.keys
+
+        (0...teams.length).each do |i|
+          team1 = teams[i]
+
+          (i + 1...teams.length).each do |j|
+            team2              = teams[j]
+            key                = [team1, team2].sort
+            count              = base_matchup_count(league, team1, team2)
+            matchups[key]      = count
+            game_counts[team1] += count
+            game_counts[team2] += count
+          end
+        end
+
+        # Each team will play 6 games against conference opponents in other divisions.
+        # The fours hash will be that plan.
+        find_fours(league).each do |team, opponents|
+          next if game_counts[team] == 82
+
+          opponents.each do |opponent|
+            next if game_counts[team] == 82
+            next if game_counts[opponent] == 82
+
+            game_counts[team] += 1
+            game_counts[opponent] += 1
+
+            key = [team, opponent].sort
+
+            matchups[key] += 1
+          end
+        end
+
+        matchups
+      end
+      # rubocop:enable Metrics/AbcSize
+
+      # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
+      # I am not liking this algorithm implementation at all but it will seemingly produce a valid
+      # result about 1 out of every 1000 cycles. I have yet to spot the assignment pattern to make
+      # this way more deterministic.
+      def find_fours(league)
+        balanced     = false
+        count        = 0
+        four_tracker = {}
+
+        until balanced
+          # Let's not completely thrash our CPUs in case this algorithm hits an infinite loop.
+          # Instead, lets hard-fail against a hard boundary.
+          raise ArgumentError, 'we spent too much CPU time and didnt resolve fours' if count > 100_000
+
+          four_tracker = league.teams.to_h { |team| [team, []] }
+
+          league.teams.each do |team|
+            opponents = league.cross_division_opponents_for(team).shuffle
+
+            opponents.each do |opponent|
+              if four_tracker[team].length < 6 && four_tracker[opponent].length < 6
+                four_tracker[opponent] << team
+                four_tracker[team] << opponent
+              end
+            end
+          end
+
+          good = true
+
+          # trip-wire: if one team isnt balanced then we are not balanced
+          four_tracker.each { |_k, v| good = false if v.length < 6 }
+
+          balanced = good
+
+          count += 1
+        end
+
+        four_tracker
+      end
+      # rubocop:enable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
+
+      def schedule_season!(calendar:, league:)
+        matchups = matchup_plan(league)
+
+        matchups.each do |(team1, team2), count|
+          candidates = calendar.available_season_matchup_dates(team1, team2)
+          dates      = candidates.sample(count)
+          games      = balanced_games(dates, team1, team2)
+
+          games.each { |game| calendar.add!(game) }
+        end
+      end
+
+      def balanced_games(dates, team1, team2)
+        dates.map.with_index(1) do |date, index|
+          if index.even?
+            SeasonGame.new(date:, home_team: team1, away_team: team2)
+          else
+            SeasonGame.new(date:, home_team: team2, away_team: team1)
+          end
+        end
+      end
+
+      def schedule_preseason!(calendar:, league:)
+        league.teams.each do |team|
+          current_games = calendar.preseason_games_for(team:)
+          count         = current_games.length
+
+          next if count >= MIN_PRESEASON_GAMES_PER_TEAM
+
+          other_teams = (league.teams - [team]).shuffle
+
+          other_teams.each do |other_team|
+            break if count > MIN_PRESEASON_GAMES_PER_TEAM
+            next  if calendar.preseason_games_for(team: other_team).length >= MAX_PRESEASON_GAMES_PER_TEAM
+
+            candidates = calendar.available_preseason_matchup_dates(team, other_team)
+
+            next if candidates.empty?
+
+            date = candidates.sample
+            game = random_preseason_game(date, team, other_team)
+
+            calendar.add!(game)
+
+            count += 1
+          end
+        end
+      end
+
+      def random_preseason_game(date, team1, team2)
+        if rand(1..2) == 1
+          PreseasonGame.new(date:, home_team: team1, away_team: team2)
+        else
+          PreseasonGame.new(date:, home_team: team2, away_team: team1)
+        end
+      end
+    end
+  end
+end

data/lib/basketball/scheduling/division.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module Basketball
+  module Scheduling
+    class Division < Entity
+      TEAMS_SIZE = 5
+
+      attr_reader :name, :teams
+
+      def initialize(id:, name: '', teams: [])
+        super(id)
+
+        @name  = name.to_s
+        @teams = []
+
+        teams.each { |t| register_team!(t) }
+
+        raise BadTeamsSizeError, "#{id} should have exactly #{TEAMS_SIZE} teams" if teams.length != TEAMS_SIZE
+
+        freeze
+      end
+
+      def to_s
+        (["[#{super}] #{name}"] + teams.map(&:to_s)).join("\n")
+      end
+
+      def team?(team)
+        teams.include?(team)
+      end
+
+      private
+
+      def register_team!(team)
+        raise ArgumentError, 'team is required' unless team
+        raise TeamAlreadyRegisteredError, "#{team} already registered" if team?(team)
+
+        teams << team
+
+        self
+      end
+    end
+  end
+end