basketball 0.0.7 → 0.0.9

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 00ac0278bb2e786c5a68b3cc7ac8fd5d49005f9f9a01fad32501c75a00880dce
-  data.tar.gz: 4b76f9d42a702a206c837346de20396c6948c9bcb071a4143610e8179ba93c64
+  metadata.gz: ab187320b9735e8bc6ace40a171cbc9fecd27058e78e5ee18ab1b663b6ea3d54
+  data.tar.gz: 6173d1bfdb1b531d54763d369f248944c532916e5fecac89698ac4f49a72e4d9
 SHA512:
-  metadata.gz: 806f800744de18f81e590cd712adf83592e372b8f1b19c3b8f9a6e702c7fbc04981380ba784b63436f2cc34d5f80238c0fce53366eed8a2a8a63eb9b64cb69c4
-  data.tar.gz: acffa65b0315e7d5ec6638cd92c217e9aa665787114935d0859a4b6b02cfb0c8afd6e66d7914de6b147d6878d83ca210b2d5f5bfbdeb748784f559300fe79d46
+  metadata.gz: df618bc45b196219e9f607a1842f5fda8513ea4dc7bce54756c98a327b87c9905bf41ded2c3dbf04cc70459d06ea4ab76864ff02713ecc2cf400e959cda081a6
+  data.tar.gz: 536c2f5fff03419da03604302743b6ec0fccde9957238a0ae4c71c8b560b1709e3460afbc18e0fc377f239c20f4fb82fbb5e2d184b45f60c05d974d4f8615894

data/.rubocop.yml

@@ -6,36 +6,26 @@ AllCops:
   NewCops: enable
   Exclude:
     - bin/*
-    - lib/basketball/draft/cli.rb
     - tmp/**/*
     - vendor/**/*
 
-Style/Documentation:
-  Enabled: false
-
-Metrics/MethodLength:
-  Max: 35
+RSpec/MultipleMemoizedHelpers:
+  Max: 30
 
 RSpec/ExampleLength:
-  Max: 20
+  Max: 25
 
-RSpec/MultipleMemoizedHelpers:
-  Max: 10
+RSpec/NestedGroups:
+  Max: 5
 
 Metrics/ParameterLists:
   Max: 6
 
-Metrics/AbcSize:
-  Max: 25
-
 Metrics/ClassLength:
-  Max: 200
+  Max: 300
 
-Metrics/BlockLength:
+Metrics/MethodLength:
   Max: 30
 
-Metrics/CyclomaticComplexity:
-  Max: 9
-
-Metrics/PerceivedComplexity:
-  Max: 9
+Metrics/AbcSize:
+  Max: 25

data/CHANGELOG.md

@@ -1,31 +1 @@
-#### 0.0.7 - May 14th, 2023
-
-* Added #to_hash and #from_hash serializer methods to allow larger consumer json constructions more directly.
-* Opt for string keys during serialization/deserialization.
-
-#### 0.0.6 - May 11th, 2023
-
-* Added Scheduling module that can generate full schedules for entire league.
-* Drafting::Event does not have identity anymore (no current tangible benefit).
-
-#### 0.0.5 - May 5th, 2023
-
-* Remove the notion of Team in favor of a flat front office.
-#### 0.0.4 - May 5th, 2023
-
-* Add ability to skip draft picks using `Basketball::Drafting::Engine#skip!`
-* Add ability to output event full drafting event log using CLI: `basketball-draft -i tmp/draft-wip.json -l`
-* Add ability to skip draft picks using CLI: `basketball-draft -i tmp/draft-wip.json -x 1`
-
-#### 0.0.3 - May 5th, 2023
-
-* `Drafting::Engine#sim!` should return events
-* Added `Drafting::Engine#undrafted_player_search`
-
-#### 0.0.2 - May 4th, 2023
-
-* Remove autoloading in favor of require statements.
-
-#### 0.0.1 - May 4th, 2023
-
-* Initial release with Drafting module only
+Will not be kept track of until stable version 1.0.0

data/README.md

@@ -1,12 +1,45 @@
-# :basketball: Basketball
+# Basketball
 
 [![Gem Version](https://badge.fury.io/rb/basketball.svg)](https://badge.fury.io/rb/basketball) [![CI](https://github.com/mattruggio/basketball/actions/workflows/ci.yaml/badge.svg)](https://github.com/mattruggio/basketball/actions/workflows/ci.yaml) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-#### Basketball League Game Engine
+:warning: **Note:** This is currently in the early phases of initial development. Consider all < 1 releases as having unstable APIs between versions. A formal 1.0.0 major release will be eventually released which will honor [Semver](https://semver.org/).
 
 This library is meant to serve as the domain for a basketball league/season simulator/turn-based game. It models core ideas such as: players, general managers, draft strategy, drafting, season generation, season simultation, playoff generation, playoff simulation, and more.
 
-## Installation
+![Architecture](/docs/architecture.png)
+
+Element      | Description
+:------------ | :-----------
+**Arena** | Determines exhibition and regular season game outcomes.
+**Assessment** | When the Room needs to know who a Front Office wants to select, the Room will send the Front Office an Assessment. The Assessment is a report of where the team currently stands: players picked, players available, and round information.
+**basketball-room** | Command-line executable script illustrating an example of how to subclass and consume the drafting module.
+**Calendar** | Stores important boundary dates (preseason start, preseason end, season start, and season end).
+**Coordinator CLI** | Underlying Ruby class that powers the `basketball-coordinator` script. Basically a terminal wrapper over the Coordinator object.
+**Coordinator Repository** | Understands how to save and load Coordinator objects from JSON files on disk.
+**Coordinator** | Object which can take a League, Calendar, Games, and an Arena and provide an iterable interface to enumerate through days and simulate games as results.
+**Draft** | Bounded context (sub-module) dealing with running a round-robin player draft for teams.
+**Exhibition** | Pre-season game which has no impact to team record.
+**External Dependency** | Some outside system which this library or portions of this library are dependent on.
+**File System** | Local operating system that the CLI will use for persistence.
+**Front Office** | Identifiable as a team, contains logic for how to auto-pick draft selections.  Meant to be subclassed and extended to include more intricate player selection logic as the base will simply randomly select a player.
+**Game** | Matches up a date with two teams (home and away) to represent a coordinatord match-up.
+**League** | Describes a league in terms of structure composed of teams and players.
+**Match** | When the Coordinator needs an Arena instance to select a game winner, it will send the Arena a Match. A match is Game but also includes the active roster (players) for both teams that will participate in the game.
+**Org** | Bounded context (sub-module) dealing with overall organizational structure of a sports assocation.
+**Pick** | Result event emitted when a player is automatically or manually selected.
+**Player** | Identitiable as a person able to be drafted.  Meant to be subclassed and extended to include more intricate descriptions of a specific sport player, such as abilities, ratings, and statistics.  Right now it has none of these types of traits and it meant to only serve as the base with only an overall attribute.
+**Regular** | Game that counts towards regular season record.
+**Result** | The outcome of a game (typically with a home and away score).
+**Room CLI** | Underlying Ruby class that powers the `basketball-room` script. Basically a terminal wrapper for the Room object.
+**Room Repository** | Understands how to save and load Room objects from JSON files on disk.
+**Room** | Main object responsible for providing an iterable interface capable of executing a draft, pick by pick.
+**Scout** | Knows how to stack rank lists of players.
+**Season** | Bounded context (sub-module) dealing with calendar and matchup generation.
+**Skip** | Result event emitted when a front office decides to skip a round.
+**Team Group** | Set of rosters that together form a cohesive league.
+**Team** | Member of a league and signs players.  Has games assigned and played.
+
+### Installation
 
 To install through Rubygems:
 
@@ -20,176 +53,124 @@ You can also add this to your Gemfile using:
 bundle add basketball
 ````
 
-Install executable scripts:
-
-````
-bundle binstubs basketball
-````
-
-## Sub-Modules
-
-This library is broken down into several bounded contexts that can be consumed either via its Ruby API's or CLI through provided executable scripts:
-
-![Basketball Architecture - Overview](/docs/architecture/overview.png)
+### Draft Module
 
-#### Command Line Interfaces
+The input for the main object `Basketball::Draft::Room` is an array of teams (`Basketball::Draft::FrontOffice`) and players (`Basketball::Org::Players`). Once instantiated there are four main methods:
 
-Each module is meant to be interfaced with using its Ruby API by consuming applications.  Each module also ships with a CLI script (backed by a module service) which a user can interact with to emulate different portions of the league management process.  Technically speaking, the CLI provides an example application built on top of the each individual core module. Each module section below should contain with it example CLI calls.
+* **Basketball::Draft::Room#sim!**: Simulate the next pick.
+* **Basketball::Draft::Room#skip!**: Skip the next pick.
+* **Basketball::Draft::Room#pick!(player)**: Pick an exact player for the current front office.
+* **Basketball::Draft::Room#sim_rest!**: Simulate the rest of the picks.
 
-## Drafting Module
+#### Command Line Interface
 
-The drafting module is responsible for providing a turn-based iterator allowing the consumer to either manually pick or simulate picks.  Here is a cartoon showing the major components:
-
-![Basketball Architecture - Drafting](/docs/architecture/drafting.png)
-
-Element      | Description
-:------------ | :-----------
-**Drafting** | Bounded context (sub-module) dealing with executing an asynchronous draft.
-**Engine** | Aggregate root responsible for providing an iterable interface capable of executing a draft, pick by pick.
-**Event** | Represents one cycle execution result from the Engine.
-**External Ruby App** | An example consumer for the Drafting context.
-**Front Office** | Identifiable as a team, contains configuration for how to auto-pick draft selections.
-**League** | Set of rosters that together form a cohesive league.
-**Pick Event** | Result event emitted when a player is manually selected.
-**Player** | Identitiable as a person able to be drafted.
-**Position** | Value object based on position code: PG, SG, SF, PF, and C.
-**Roster** | Identifiable as a team, set of players that make up a single team.
-**Sim Event** | Result event emitted when a player is automatically selected by a front office.
-**Skip Event** | Result event emitted when a front office decides to skip a round.
-
-#### The Drafting CLI
-
-The drafting module's main object: `Basketball::Drafting::Engine` is a stateful iterator. Each time a CLI command is executed, it's results will be re-saved to disk so the output file can then be used as the next command's input file to string together commands.
+This library ships with an example of how the Draft module could be used implemented as a command-line executable script. The script is file-based and will de-serialize into a Room object, execute operations, then serialize and write it back to disk.
 
 ###### Generate a Fresh Draft
 
 ```zsh
-basketball-draft -o tmp/draft.json
+basketball-room -o tmp/draft.json
 ```
 
 ###### N Top Available Players
 
 ```zsh
-basketball-draft -i tmp/draft.json -t 10
+basketball-room -i tmp/draft.json -t 10
 ```
 
 ###### N Top Available Players for a Position
 
 ```zsh
-basketball-draft -i tmp/draft.json -t 10 -q PG
+basketball-room -i tmp/draft.json -t 10 -q PG
 ```
 
-###### Output Current Rosters
+###### Output League
 
 ```zsh
-basketball-draft -i tmp/draft.json -r
+basketball-room -i tmp/draft.json -l
 ```
 
 ###### Output Event Log
 
 ```zsh
-basketball-draft -i tmp/draft.json -l
+basketball-room -i tmp/draft.json -e
 ```
 
 ###### Simulate N Picks
 
 ```zsh
-basketball-draft -i tmp/draft.json -s 10
+basketball-room -i tmp/draft.json -s 10
 ```
 
 ###### Skip N Picks
 
 ```zsh
-basketball-draft -i tmp/draft.json -x 10
+basketball-room -i tmp/draft.json -x 10
 ```
 
 ###### Pick Players
 
 ```zsh
-basketball-draft -i tmp/draft.json -p P-100,P-200,P-300
+basketball-room -i tmp/draft.json -p P-100,P-200,P-300
 ```
 
 ###### Simulate the Rest of the Draft
 
 ```zsh
-basketball-draft -i tmp/draft.json -a
+basketball-room -i tmp/draft.json -a
 ```
 
 ###### Help Menu
 
 ```zsh
-basketball-draft -h
+basketball-room -h
 ```
 
-## Scheduling Module
-
-The Scheduling module is meant to take a League (conferences/divisions/teams) and turn it into a Calendar.  This Calendar creation is atomic - the full calendar will be generated completely all in one call.  Here is a cartoon showing the major components:
-
-![Basketball Architecture - Scheduling](/docs/architecture/scheduling.png)
-
-Element      | Description
-:------------ | :-----------
-**Away Team** | Team object designated as the away team for a Game.
-**Calendar Serializer** | Understands how to serialize and deserialize a Calendar object.
-**Calendar** | Hold a calendar for a year season.  Pass in a year and the Calendar will know how to mark important boundary dates (preseason start, preseason end, season start, and season end) and it knows how to ensure Calendar correctness regarding dates.
-**Conference** | Describes a conference in terms of structure; composed of an array of divisions (there can only 3).
-**Coordinator** | Service which can generate a Calendar from a League.
-**Division** | Describes a division in terms of structure; composed of an array of teams (there can only 5).
-**Game** | Matches up a date with two teams (home and away) to represent a scheduled matchup.
-**Home Team** | Team object designated as the home team for a Game.
-**League Serializer** | Understands how to serialize and deserialize a League object.
-**League** | Describes a league in terms of structure; composed of an array conferences (there can only be 2).
-**Scheduling** | Bounded context (sub-module) dealing with matchup and calendar generation.
-**Team** | Identified by an ID and described by a name: represents a basketball team that can be scheduled.
-
-#### The Scheduling CLI
+### Season Module
 
-###### Generate League
+The Season module knows how to execute a calendar of games for a League and generate results. The main object is the `Basketball::Season::Coordinator` class. Once instantiated there are four main methods:
 
-```zsh
-basketball-schedule -o tmp/league.json
-```
+* **Basketball::Season::Coordinator#sim!**: Simulate the next day of games.
+* **Basketball::Season::Coordinator#sim_rest!**: Simulate the rest of the games.
 
-###### Generate Calendar From League
+#### Command Line Interface
 
-```zsh
-basketball-schedule -i tmp/league.json -o tmp/calendar.json
-```
+This library ships with an example of how the Season module could be used implemented as a command-line executable script.  The script is file-based and will de-serialize into a Coordinator object, execute operations, then serialize and write it back to disk.
 
-###### Generate Calendar From League For a Specific Year
+###### Generate Random coordinator
 
 ```zsh
-basketball-schedule -i tmp/league.json -o tmp/calendar.json -y 2005
+exe/basketball-coordinator -o tmp/coordinator.json
 ```
 
-###### Output a Generated Calendar's Matchups
+###### Sim One Day and Save to New File
 
 ```zsh
-basketball-schedule -c tmp/calendar.json
+exe/basketball-coordinator -i tmp/coordinator.json -o tmp/coordinator2.json -d 1
 ```
 
-###### Output a Generated Calendar's Matchups For a Specific Team
+###### Output Event Log
 
 ```zsh
-basketball-schedule -c tmp/calendar.json -t C0-D0-T0
+exe/basketball-coordinator -i tmp/coordinator.json -e
 ```
 
-###### Output a Generated Calendar's Matchups For a Specific Date
+###### Sim Two Days and Save To Input File
 
 ```zsh
-basketball-schedule -c tmp/calendar.json -d 2005-02-03
+exe/basketball-coordinator -i tmp/coordinator.json -d 2
 ```
 
-###### Output a Generated Calendar's Matchups For a Specific Team and Date
+###### Sim Rest of Calendar
 
 ```zsh
-basketball-schedule -c tmp/calendar.json -d 2005-02-03 -t C0-D0-T0
+exe/basketball-coordinator -i tmp/coordinator.json -a
 ```
 
 ###### Help Menu
 
 ```zsh
-basketball-schedule -h
+basketball-coordinator -h
 ```
 
 ## Contributing

data/basketball.gemspec

@@ -5,19 +5,17 @@ require './lib/basketball/version'
 Gem::Specification.new do |s|
   s.name        = 'basketball'
   s.version     = Basketball::VERSION
-  s.summary     = 'Basketball League Game Engine'
+  s.summary     = 'Basketball Simulation Domain Model'
 
   s.description = <<-DESC
-    This library is meant to serve as the domain for a basketball league/season simulator/turn-based game.
-    It models core ideas such as: players, general managers, draft strategy, drafting, season generation, season simultation,
-    playoff generation, playoff simulation, and more.
+    This library is meant to serve as the domain for a basketball league/season simulator/turn-based game. It models core ideas such as: players, general managers, draft strategy, drafting, season generation, season simultation, playoff generation, playoff simulation, and more.
   DESC
 
   s.authors     = ['Matthew Ruggio']
   s.email       = ['mattruggio@icloud.com']
   s.files       = `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(.github|bin|docs|spec)/}) }
   s.bindir      = 'exe'
-  s.executables = %w[basketball-draft basketball-schedule]
+  s.executables = %w[basketball-coordinator basketball-room]
   s.homepage    = 'https://github.com/mattruggio/basketball'
   s.license     = 'MIT'
   s.metadata    = {
@@ -31,6 +29,5 @@ Gem::Specification.new do |s|
 
   s.required_ruby_version = '>= 3.2.1'
 
-  s.add_dependency('faker', '~>3.2')
   s.add_dependency('slop', '~>4.10')
 end

data/exe/{basketball-schedule → basketball-coordinator}

@@ -4,4 +4,4 @@
 require 'bundler/setup'
 require 'basketball'
 
-Basketball::Scheduling::CLI.new(args: ARGV).invoke!
+Basketball::App::CoordinatorCLI.new(args: ARGV).invoke!

data/exe/{basketball-draft → basketball-room}

@@ -4,4 +4,4 @@
 require 'bundler/setup'
 require 'basketball'
 
-Basketball::Drafting::CLI.new(args: ARGV).invoke!
+Basketball::App::RoomCLI.new(args: ARGV).invoke!

data/lib/basketball/app/coordinator_cli.rb

@@ -0,0 +1,243 @@
+# frozen_string_literal: true
+
+module Basketball
+  module App
+    # Examples:
+    #   exe/basketball-coordinator -o tmp/coordinator.json
+    #   exe/basketball-coordinator -i tmp/coordinator.json -o tmp/coordinator2.json -d 1
+    #   exe/basketball-coordinator -i tmp/coordinator2.json -e
+    #   exe/basketball-coordinator -i tmp/coordinator2.json -o tmp/coordinator2.json -d 2
+    #   exe/basketball-coordinator -i tmp/coordinator2.json -a
+    #
+    #   exe/basketball-coordinator -o tmp/coordinator.json -ae
+    class CoordinatorCLI
+      attr_reader :opts, :io, :repository
+
+      def initialize(args:, io: $stdout)
+        @io         = io
+        @opts       = slop_parse(args)
+        @repository = CoordinatorRepository.new
+
+        if no_input? && no_output?
+          io.puts('Input and/or output paths are required.')
+
+          exit
+        end
+
+        freeze
+      end
+
+      def invoke!
+        coordinator = read
+
+        execute(coordinator)
+        output_status(coordinator)
+        write(coordinator)
+        events(coordinator)
+
+        self
+      end
+
+      private
+
+      def output_status(coordinator)
+        io.puts
+        io.puts('Status')
+
+        if coordinator.done?
+          io.puts('Coordinator is complete!')
+        else
+          io.puts("#{coordinator.days_left} Remaining day(s) (#{coordinator.total_days} total)")
+          io.puts("Currently on: #{coordinator.current_date}")
+          io.puts("#{coordinator.exhibitions_left} Remaining preseason (#{coordinator.total_exhibitions} total)")
+          io.puts("#{coordinator.regulars_left} Remaining season (#{coordinator.total_regulars} total)")
+        end
+      end
+
+      def execute(coordinator)
+        event_count = 0
+
+        io.puts
+        io.puts('New Events')
+
+        days&.times do
+          coordinator.sim! do |event|
+            io.puts(event)
+
+            event_count += 1
+          end
+        end
+
+        if sim_all
+          coordinator.sim_rest! do |event|
+            io.puts(event)
+
+            event_count += 1
+          end
+        end
+
+        io.puts("Generated #{event_count} new event(s)")
+
+        nil
+      end
+
+      def days
+        opts[:days]
+      end
+
+      def sim_all
+        opts[:sim_all]
+      end
+
+      def write(coordinator)
+        path = output? ? output : input
+
+        repository.save(path, coordinator)
+
+        path
+      end
+
+      def make_league(team_count: 2, players_per_team_count: 4)
+        Org::League.new.tap do |league|
+          team_count.times do |i|
+            team = Org::Team.new(id: "T-#{i}")
+
+            players_per_team_count.times do |j|
+              player = Org::Player.new(
+                id: "T-#{i}-P-#{j}",
+                overall: rand(20..100),
+                position: Org::Position.random
+              )
+
+              team.sign!(player)
+            end
+
+            league.register!(team)
+          end
+        end
+      end
+
+      def make_calendar(league:)
+        preseason_start_date = Date.new(2000, 1, 1)
+        season_start_date = Date.new(2000, 1, 11)
+
+        exhibitions = make_games(
+          start_date: preseason_start_date,
+          count: 10,
+          league:,
+          game_class: Season::Exhibition
+        )
+
+        regulars = make_games(
+          start_date: season_start_date,
+          count: 10,
+          league:,
+          game_class: Season::Regular
+        )
+
+        Season::Calendar.new(
+          preseason_start_date:,
+          preseason_end_date: Date.new(2000, 1, 10),
+          season_start_date:,
+          season_end_date: Date.new(2000, 1, 20),
+          games: exhibitions + regulars
+        )
+      end
+
+      def make_games(start_date:, count:, league:, game_class:)
+        count.times.map do |i|
+          home_team, away_team = league.teams.sample(2)
+
+          game_class.new(
+            date: start_date + i,
+            home_opponent: Season::Opponent.new(id: home_team.id),
+            away_opponent: Season::Opponent.new(id: away_team.id)
+          )
+        end
+      end
+
+      def make_coordinator
+        league       = make_league
+        current_date = Date.new(2000, 1, 1)
+        calendar     = make_calendar(league:)
+
+        Season::Coordinator.new(
+          calendar:,
+          current_date:,
+          league:
+        )
+      end
+
+      def read
+        coordinator =
+          if input?
+            io.puts("Coordinator loaded from: #{input}")
+
+            repository.load(input)
+          else
+            io.puts('Input path was not provided, generating fresh coordinator')
+
+            make_coordinator
+          end
+
+        io.puts("Current Date: #{coordinator.current_date}")
+
+        coordinator
+      end
+
+      def input
+        opts[:input]
+      end
+
+      def input?
+        !no_input?
+      end
+
+      def no_input?
+        input.to_s.empty?
+      end
+
+      def output
+        opts[:output]
+      end
+
+      def no_output?
+        output.to_s.empty?
+      end
+
+      def output?
+        !no_output?
+      end
+
+      def events(coordinator)
+        return unless opts[:events]
+
+        io.puts
+        io.puts('Event Log')
+
+        puts coordinator.results
+      end
+
+      def slop_parse(args)
+        Slop.parse(args) do |o|
+          o.banner = 'Usage: basketball-coordinator [options] ...'
+
+          input_description = <<~DESC
+            Path to load the Coordinator from. If omitted then a new coordinator will be created.
+          DESC
+
+          o.string  '-i', '--input', input_description.chomp
+          o.string  '-o', '--output',  'Path to save updated coordinator. If omitted then the input path will be used.'
+          o.integer '-d', '--days',    'Number of days to simulate'
+          o.bool    '-a', '--sim-all', 'Simulate the rest of the coordinator', default: false
+          o.bool    '-e', '--events',  'Output event log.', default: false
+
+          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