Upgrade to Paper 1.21, Java 21, and add comprehensive unit tests

[Chafficui]

Summary

This PR modernizes MiningLevels to target Paper 1.21 and Java 21, migrates from CrucialAPI 2.1.7 to CrucialLib 3.0.0, and introduces comprehensive unit test coverage for the core API and utilities.

Key Changes

Platform & Dependency Updates

• Java version: Updated from Java 8/14 to Java 21 (LTS)
• Server API: Migrated from Spigot 1.15 to Paper 1.21
• CrucialAPI → CrucialLib: Updated all imports from io.github.chafficui.CrucialAPI to io.github.chafficui.CrucialLib (package rename in v3.0.0)
• Maven compiler: Updated to 3.11.0 with Java 21 source/target
• plugin.yml: Updated api-version from 1.15 to 1.21 and softdepend from CrucialAPI to CrucialLib

Unit Tests (New)

Added comprehensive test suite with 100+ test cases covering:

• MiningLevelTest (227 lines): Tests level retrieval, progression, XP thresholds, and skill properties (haste, instant break, extra ore)
• MiningPlayerTest (178 lines): Tests player creation, level management, XP tracking, and duplicate prevention
• MiningBlockTest (130 lines): Tests block registration, material mapping, and XP/level requirements
• RewardTest (50 lines): Tests reward item creation and retrieval
• MathUtilsTest (36 lines): Tests probability calculations with repeated runs
• ConfigStringsTest (68 lines): Tests configuration constants and permissions

All tests use JUnit 5 with MockBukkit 4.101.0 for Bukkit API mocking (Materials, ItemStacks, etc.).

CI/CD

• Replaced .github/workflows/maven.yml with new .github/workflows/ci.yml
• Updated to JDK 21 and added test result artifact uploads
• Maven Surefire plugin configured for test execution

Documentation (New)

• ARCHITECTURE.md: High-level system design, package structure, and data flow
• RUNBOOK.md: Release process, common configuration tasks, and troubleshooting
• CONTRIBUTING.md: Development setup, branch naming, and testing guidelines
• CLAUDE.md: Project overview for AI assistants
• DECISIONS/001-spigot-1.21-update.md: ADR for platform upgrade
• DECISIONS/002-add-unit-tests.md: ADR for test framework selection

Code Improvements

• Crucial.java: Refactored static plugin initialization to use lazy loading pattern; updated error messages to reference CrucialLib GitHub releases
• MiningPlayer.java: Updated CrucialLib imports
• All GUI classes: Updated CrucialLib imports (LevelList, LevelEdit, BlockList, BlockEdit, LeaderboardList, MiningLevelProfile)
• pom.xml: Added maven-surefire-plugin configuration and shade plugin exclusions for CrucialLib, Paper, and PlaceholderAPI

Implementation Details

• Tests use MockBukkit.mock() only (not MockBukkit.load()) to avoid plugin lifecycle initialization that requires CrucialLib at runtime
• Static registries (MiningLevel.miningLevels, MiningBlock.miningBlocks, MiningPlayer.miningPlayers) are cleared in @BeforeEach for test isolation
• All test classes follow consistent naming: <Class>Test with descriptive test method names (methodName_condition_expectedBehavior)
• Maven build now runs mvn clean verify to compile, test, and package in one step

Breaking Changes

None for end users. The plugin API remains compatible; only internal dependency versions have changed.

https://claude.ai/code/session_01EyodQnKSvWcNzA6W8pCmyu