nba 0.1.1 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: b953637ba9292b6414aec1db167b451df894d354
-  data.tar.gz: 4d7ba14450b621e09958d41009d7e883a04ab6fb
+SHA256:
+  metadata.gz: 0aa8e7be8eb8ce1f1833d33ea8e26d8d26fba4c2eb4d6068bfec951991477f2a
+  data.tar.gz: b561dcab1d4adfbcc111cf95e033929b351444737bb56821fc1a662b1addd8b4
 SHA512:
-  metadata.gz: dc1baeadf0c937313ac2053e5c53758ee69f30713d6f772b5818ef673855275a20720452d573c21adb7ca04ac9d470253e54ba73a3f26a4d32e6828fa642fa35
-  data.tar.gz: e8a6da21617c53615298400d32ef93f01633933c1ed5fbe4709c42358d9501ff31003a314b3b16941e71fe9ab84cf82cd90abdcf866959090e78c6fb66408cc6
+  metadata.gz: da2139f4a75911fe2237acb2412c1f0bbc2b45ac60f21e6f0b0954f2960295ea41347b0751c771b7fca0d8dda15193b5771177e2a7aed9500f4b10ed67e5ca3e
+  data.tar.gz: 10c7f5dec82e740a73216d0f121146fc7240537367274ac8a636be425c90264d9c9607a0246560e3d55c9d5ef6cd0ddf0116a18e3255b200d27f1d5c701e12ea

data/AGENTS.md

@@ -0,0 +1,362 @@
+# CLAUDE.md
+
+## Project Overview
+
+NBA Ruby is a Ruby interface to the NBA Stats API. It provides an idiomatic
+Ruby wrapper around NBA's statistical data endpoints.
+
+## Development Commands
+
+```bash
+bundle exec rake test      # Run tests
+bundle exec rake lint      # Run RuboCop linter
+bundle exec rake mutant    # Run mutation testing (full suite)
+bundle exec rake steep     # Run type checker
+bundle exec rake yard      # Generate documentation
+bundle exec rake           # Run all quality checks
+```
+
+### Running Mutant for Individual Classes
+
+Always run mutant on individual classes during development rather than the full
+suite. The full mutant suite takes approximately 30 minutes to complete, so
+instead execute more targeted mutant runs on classes you add or modify to
+achieve 100% coverage.
+
+```bash
+bundle exec mutant run --include lib --require nba --use minitest 'NBA::ClassName'
+bundle exec mutant run --include lib --require nba --use minitest 'NBA::ClassName#method_name'
+```
+
+## Reference Libraries
+
+This library should maintain:
+- **Feature parity** with [nba_api](https://github.com/swar/nba_api) (Python)
+- **Style consistency** with [mlb-ruby](https://github.com/sferik/mlb-ruby)
+
+## Code Style and Conventions
+
+### Fixing RuboCop Offenses
+
+When asked to fix RuboCop offenses, **actually refactor the code to fix them.**
+Never disable offenses, either inline with `# rubocop:disable` comments or in
+`.rubocop.yml`. The goal is clean, idiomatic Ruby code that passes all linting
+rules.
+
+### Internal Consistency is Critical
+
+Before implementing any new feature, analyze existing similar features in the
+codebase and follow the same patterns exactly. Look at:
+- How similar API endpoints are implemented
+- How data models are structured
+- How tests are organized
+- How documentation is written
+
+### One Class Per File
+
+Each Ruby file should contain exactly one class or module. This applies to both
+library code in `lib/` and test files in `test/`. When a test file has shared
+helper classes or modules, extract them to a separate `*_test_helper.rb` file.
+
+### Parameter Naming
+
+**Never use parameters ending in `_id` in public methods.** Instead:
+
+```ruby
+# WRONG
+def self.find(player_id:, client: CLIENT)
+  path = "endpoint?PlayerID=#{player_id}"
+  ...
+end
+
+# CORRECT
+def self.find(player:, client: CLIENT)
+  id = Utils.extract_id(player)
+  path = "endpoint?PlayerID=#{id}"
+  ...
+end
+```
+
+Parameters should accept either:
+- An ID (String or Integer)
+- An object with an `id` method (e.g., `NBA::Player`, `NBA::Team`)
+
+Use `Utils.extract_id(entity)` to normalize the value.
+
+### Predicate Methods
+
+Convert boolean-like API responses to Ruby predicate methods:
+
+```ruby
+# API returns "is_active" or boolean flags
+def active?
+  is_active
+end
+
+# API returns "Y"/"N" strings
+def greatest_75?
+  greatest_75_flag.eql?("Y")
+end
+
+# API returns numeric flags (1/0)
+def win?
+  wl.eql?("W")
+end
+
+def loss?
+  wl.eql?("L")
+end
+
+# Shot made (1) or missed (0)
+def made?
+  shot_made_flag.eql?(1)
+end
+```
+
+For enums with few options (win/loss, made/missed), provide predicate methods for each state.
+
+### Value Equality with `.eql?`
+
+**Always use `.eql?` instead of `==`** when comparing values where both would produce the same result:
+
+```ruby
+# WRONG - mutation testing will catch this
+def win?
+  wl == "W"
+end
+
+# CORRECT - survives mutation testing
+def win?
+  wl.eql?("W")
+end
+```
+
+This is required for mutation testing to verify the comparison is actually tested.
+
+### Type Annotations
+
+**Keep all type annotations in `sig/nba.rbs`.** Never add inline type annotations
+(like `#: -> String` or `# @type var`) in Ruby source files. Steep reads type
+signatures from the RBS file, keeping the Ruby code clean and the types
+centralized in one place.
+
+## Mutation Testing Requirements
+
+**All new code must have 100% mutation coverage.** This requires specific testing patterns:
+
+### Testing Hash Key Access
+
+When accessing data from a hash, write tests for both:
+1. When the key is present (returns the value)
+2. When the key is missing (returns nil or raises, depending on `fetch` vs `[]`)
+
+```ruby
+# In the implementation
+def self.build_player(data)
+  Player.new(
+    id: data.fetch("PERSON_ID"),        # Required - raises if missing
+    nickname: data["NICKNAME"]          # Optional - returns nil if missing
+  )
+end
+
+# In tests - test both present AND missing
+def test_handles_missing_nickname_key
+  headers = all_headers.reject { |h| h == "NICKNAME" }
+  row = build_row_without("NICKNAME")
+  # ... stub request and assert attribute is nil
+end
+```
+
+### Testing Predicate Methods
+
+Test both true and false cases:
+
+```ruby
+def test_win_returns_true_when_wl_is_w
+  log = GameLog.new(wl: "W")
+  assert_predicate log, :win?
+end
+
+def test_win_returns_false_when_wl_is_l
+  log = GameLog.new(wl: "L")
+  refute_predicate log, :win?
+end
+```
+
+### Testing Value Equality
+
+Test with equivalent but different types to ensure `.eql?` is used:
+
+```ruby
+def test_made_uses_value_equality
+  shot = Shot.new(shot_made_flag: 1.0)  # Float, not Integer
+  assert_predicate shot, :made?
+end
+```
+
+### Killing Surviving Mutants
+
+When mutant reports surviving mutants, kill them by either:
+
+1. **Adding tests** - Write a test that fails when the mutation is applied
+2. **Replacing with the mutation** - If the mutated code is equivalent or better, adopt it
+
+**Never ignore or exclude code from mutation testing.** Do not:
+- Add exclusions to `.mutant.yml`
+- Use inline `# mutant:disable` comments
+- Skip methods or classes from mutation coverage
+
+If a mutant seems impossible to kill, the code is likely untestable or redundant—refactor it instead of excluding it.
+
+### Test Organization
+
+Each test file must declare its coverage target:
+
+```ruby
+module NBA
+  class MyFeatureTest < Minitest::Test
+    cover MyClass  # Required for mutant coverage
+
+    def test_something
+      # ...
+    end
+  end
+end
+```
+
+## Architecture Patterns
+
+### Data Models
+
+All models inherit from `Shale::Mapper` and include `Equalizer`:
+
+```ruby
+class Player < Shale::Mapper
+  include Equalizer.new(:id)
+
+  attribute :id, Shale::Type::Integer
+  attribute :full_name, Shale::Type::String
+
+  json do
+    map "PERSON_ID", to: :id
+    map "person_id", to: :id
+    map "PersonID", to: :id  # Support multiple API formats
+  end
+end
+```
+
+### Query Modules
+
+API endpoints are implemented as module class methods:
+
+```ruby
+module Players
+  def self.find(player, client: CLIENT)
+    id = Utils.extract_id(player)
+    return unless id
+
+    path = "commonplayerinfo?PlayerID=#{id}"
+    ResponseParser.parse_single(client.get(path)) { |data| build_player(data) }
+  end
+
+  def self.build_player(data)
+    Player.new(**identity_info(data), **physical_info(data))
+  end
+  private_class_method :build_player
+
+  def self.identity_info(data)
+    {id: data.fetch("PERSON_ID"), full_name: data.fetch("DISPLAY_FIRST_LAST")}
+  end
+  private_class_method :identity_info
+end
+```
+
+### Collections
+
+API methods returning multiple items return `Collection` objects (which are `Enumerable`).
+
+### Lazy Hydration
+
+Related objects are fetched lazily via methods, not in constructors:
+
+```ruby
+class Standing
+  def team
+    Teams.find(team_id)
+  end
+end
+```
+
+## Documentation Requirements
+
+All public methods require YARD documentation with 100% coverage:
+
+```ruby
+# Returns whether the player is a Greatest 75 member
+#
+# @api public
+# @example
+#   player.greatest_75? #=> true
+# @return [Boolean] true if in Greatest 75
+def greatest_75?
+  greatest_75_flag.eql?("Y")
+end
+```
+
+## README Usage Examples
+
+After implementing a new feature, add a usage example to the README. **Always
+run the example code in a Ruby console to verify it works and produces the
+expected output.**
+
+### Process
+
+1. Write the example code
+2. Run it in IRB or a script against the live API:
+   ```bash
+   bundle exec irb -r nba
+   ```
+3. Capture the actual output values
+4. Add the example to README.md with real, verified output
+
+### Example Format
+
+Follow the existing README style with comments showing actual return values:
+
+```ruby
+# Get player career stats
+career = NBA::PlayerCareerStats.find(player: 201939)
+career.size # => 16
+
+season = career.last
+season.pts # => 26.4
+season.ast # => 6.1
+```
+
+### Why This Matters
+
+- Examples with fabricated output erode user trust
+- Live-tested examples catch API changes early
+- Real data demonstrates actual library behavior
+- Users can verify their setup works by comparing results
+
+### When to Update
+
+- Adding a new endpoint or query module
+- Adding new model attributes or methods
+- Adding new predicate methods
+- Changing existing API behavior
+
+## Quality Gates
+
+All of these must pass before merging:
+- `rake test` - 100% line and branch coverage
+- `rake lint` - No RuboCop violations
+- `rake mutant` - 100% mutation coverage (no surviving mutants)
+- `rake steep` - No type errors
+- `rake yardstick` - 100% documentation coverage
+
+## Plan Mode
+
+- Make the plan extremely concise. Sacrifice grammar for the sake of concision.
+- At the end of each plan, give me a list of unresolved questions to answer, if any.

data/CHANGELOG.md

@@ -0,0 +1,169 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
+
+## [0.2.0] - 2025-01-16
+
+### Added
+- Core domain objects: Player, Team, Conference, Division, Position
+- Collection class for handling groups of objects
+- Client and Connection classes for API access
+- Utility functions for common operations
+- Full test coverage with Minitest
+- Mutation testing with Mutant
+- Type checking with Steep
+- Documentation with YARD
+- Code quality checks with RuboCop and Standard
+- Uses Shale for JSON mapping
+- Uses Equalizer for object equality
+
+#### Command-Line Interface
+- `nba` CLI tool for quick access to NBA data from the terminal
+- Commands: `games`, `teams`, `player`, `standings`, `leaders`, `schedule`, `roster`
+- Date filtering, conference filtering, and season selection options
+
+#### Player Endpoints
+- `CommonPlayerInfo` - Detailed player biography and career info
+- `PlayerIndex` - Search and list all players
+- `PlayerCareerStats` - Season-by-season career statistics
+- `PlayerGameLog` / `PlayerGameLogs` - Game-by-game player stats
+- `PlayerNextNGames` - Upcoming games for a player
+- `PlayerProfileV2` - Comprehensive player profile data
+- `PlayerAwards` - Career awards and accolades
+- `PlayerCompare` - Head-to-head player comparisons
+- `PlayerDashboard` - Player dashboard statistics
+- `PlayerEstimatedMetrics` - Advanced estimated metrics (EPM, etc.)
+- `PlayerGameStreakFinder` - Find player game streaks
+- `PlayerDashPtPass` - Player tracking passing stats
+- `PlayerDashPtReb` - Player tracking rebounding stats
+- `PlayerDashPtShotDefend` - Player tracking defensive stats
+- `PlayerDashPtShots` - Player tracking shooting stats
+- `PlayerFantasyProfileBarGraph` - Fantasy basketball profile
+- `PlayerVsPlayer` - Player vs player matchup stats
+- `PlayerCareerByCollege` / `PlayerCareerByCollegeRollup` - Stats by college
+
+#### Team Endpoints
+- `TeamDetails` - Team info including arena, owner, GM, coach
+- `TeamDashboard` - Team dashboard statistics
+- `TeamInfoCommon` - Common team information and season ranks
+- `TeamEstimatedMetrics` - Advanced team metrics
+- `TeamHistoricalLeaders` - All-time team statistical leaders
+- `TeamGameStreakFinder` - Find team game streaks
+- `TeamDashPtPass` - Team tracking passing stats
+- `TeamDashPtReb` - Team tracking rebounding stats
+- `TeamDashPtShots` - Team tracking shooting stats
+- `TeamPlayerDashboard` - Player stats within team context
+- `TeamPlayerOnOffDetails` / `TeamPlayerOnOffSummary` - On/off court analysis
+- `TeamVsPlayer` - Team performance vs specific players
+- `TeamAndPlayersVsPlayers` - Team and players vs players matchups
+- `TeamGameLog` / `TeamGameLogs` - Game-by-game team stats
+- `TeamYearByYearStats` - Historical team stats by season
+- `CommonTeamYears` - Team history timeline
+
+#### Box Score Endpoints
+- `BoxScoreTraditional` / `BoxScoreTraditionalV3` - Traditional stats
+- `BoxScoreAdvanced` / `BoxScoreAdvancedV3` - Advanced stats (eFG%, TS%, etc.)
+- `BoxScoreScoring` / `BoxScoreScoringV3` - Scoring breakdown
+- `BoxScoreMisc` / `BoxScoreMiscV3` - Miscellaneous stats
+- `BoxScoreUsage` / `BoxScoreUsageV3` - Usage rate stats
+- `BoxScoreFourFactors` / `BoxScoreFourFactorsV3` - Four factors analysis
+- `BoxScoreHustle` - Hustle stats (deflections, loose balls, etc.)
+- `BoxScoreDefensiveV2` - Defensive statistics
+- `BoxScorePlayerTrack` - Player tracking data (speed, distance, touches)
+- `BoxScoreSummaryV2` / `BoxScoreSummaryV3` - Comprehensive game summaries
+- `BoxScoreMatchupsV3` - Player matchup statistics
+- `BoxScoreSimilarityScore` - Historical game similarity
+- `HustleStatsBoxScore` - Detailed hustle box scores
+
+#### League-Wide Endpoints
+- `LeagueDashTeamStats` - League-wide team statistics
+- `LeagueDashPlayerStats` - League-wide player statistics
+- `LeagueDashLineups` - Lineup statistics across the league
+- `LeagueDashPlayerBioStats` - Player biographical statistics
+- `LeagueDashPlayerClutch` - Player clutch performance stats
+- `LeagueDashTeamClutch` - Team clutch performance stats
+- `LeagueDashPlayerPtShot` - Player tracking shot stats
+- `LeagueDashTeamPtShot` - Team tracking shot stats
+- `LeagueDashOppPtShot` - Opponent tracking shot stats
+- `LeagueDashPlayerShotLocations` - Shot location breakdowns by player
+- `LeagueDashTeamShotLocations` - Shot location breakdowns by team
+- `LeagueDashPtDefend` - Player tracking defensive stats
+- `LeagueDashPtTeamDefend` - Team tracking defensive stats
+- `LeagueDashPtStats` - Player tracking general stats
+- `LeagueLineupViz` - Lineup visualization data
+- `LeaguePlayerOnDetails` - On-court impact details
+- `LeagueSeasonMatchups` - Season matchup statistics
+- `LeagueGameLog` - League-wide game logs
+- `LeagueGameFinder` - Search for games by criteria
+- `LeagueHustleStatsPlayer` / `LeagueHustleStatsTeam` - League hustle stats
+- `LeagueStandings` - Detailed league standings
+
+#### Standings & Leaders
+- `Standings` - Conference and division standings
+- `Leaders` - Current season statistical leaders
+- `AllTimeLeaders` - All-time career statistical leaders
+- `AssistLeaders` / `AssistTracker` - Assist-specific leaderboards
+- `HomePageLeaders` / `LeadersTiles` - Home page leader data
+- `ISTStandings` - In-Season Tournament standings
+- `FranchiseLeaders` - Franchise all-time leaders
+- `FranchiseHistory` - Franchise historical records
+- `FranchisePlayers` - Players in franchise history
+
+#### Game & Schedule
+- `Games` / `Scoreboard` / `ScoreboardV3` - Today's games and scores
+- `LiveScoreboard` - Real-time live game data
+- `Schedule` / `ScheduleInternational` - Team and league schedules
+- `GameRotation` - Player rotation data per game
+- `PlayByPlay` / `PlayByPlayV3` - Play-by-play game data
+- `LivePlayByPlay` - Real-time play-by-play
+- `LiveBoxScore` - Real-time box scores
+- `WinProbability` - In-game win probability
+
+#### Shot Chart
+- `ShotChart` - Individual player shot charts
+- `ShotChartLeagueWide` - League-wide shot data
+- `ShotChartLineupDetail` - Lineup-specific shot charts
+
+#### Draft
+- `DraftHistory` - Historical draft picks
+- `DraftBoard` - Draft board data
+- `DraftCombineStats` - Combine statistical results
+- `DraftCombineSpotShooting` - Spot shooting drill results
+- `DraftCombineDrillResults` - Agility and strength drills
+- `DraftCombineNonStationaryShooting` - Non-stationary shooting
+- `DraftCombinePlayerAnthro` - Anthropometric measurements
+
+#### Video
+- `VideoDetails` / `VideoDetailsAsset` - Video metadata and assets
+- `VideoEvents` / `VideoEventsAsset` - Event-based video clips
+- `VideoStatus` - Video availability status
+
+#### Playoffs
+- `CommonPlayoffSeries` - Playoff series information
+- `PlayoffPicture` - Current playoff picture
+
+#### Synergy & Advanced
+- `SynergyPlayTypes` - Synergy play type statistics
+
+#### Cumulative Stats
+- `CumeStatsPlayer` / `CumeStatsPlayerGames` - Cumulative player stats
+- `CumeStatsTeam` / `CumeStatsTeamGames` - Cumulative team stats
+
+#### Other Features
+- `DefenseHub` - Defensive statistics hub
+- `FantasyWidget` - Fantasy basketball widget data
+- `HomePageV2` - NBA.com home page data
+- `MatchupsRollup` - Matchup summary data
+- `InfographicFanDuelPlayer` - FanDuel player data
+- `DunkScoreLeaders` - Dunk score leaderboards
+- `Static` - Static reference data
+
+#### Infrastructure
+- `LiveConnection` - Real-time API connection for live data
+- `ResponseParser` - Centralized response parsing
+- Predicate methods for boolean-like API responses
+- Support for multiple API response formats (v2/v3 endpoints)
+
+[0.2.0]: https://github.com/sferik/nba-ruby/releases/tag/v0.2.0

data/CLAUDE.md

@@ -0,0 +1 @@
+AGENTS.md

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Erik Berlin
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.