Treasure Map

A Java console application simulating treasure-hunting adventurers navigating a map with mountains and treasures. Built following SOLID principles and Test-Driven Development methodology. This project is documented with Javadoc.

Overview

This application processes input files containing map dimensions, mountains, treasures, and adventurer movements, then simulates the treasure hunt and outputs the final state. The codebase demonstrates professional Java development practices with comprehensive testing, static analysis, and documentation.

Architecture & Design Principles

SOLID Principles Implementation:

• Single Responsibility: Each class has one clear purpose (e.g., MoveParser for parsing, RegionMap for map management, FileProcessor for I/O operations)
• Open/Closed: Entity hierarchy uses abstraction (Entity base class, Reachable interface) allowing extension without modification
• Liskov Substitution: All entity subclasses (Mountain, Treasure, Adventurer) can substitute their base Entity class
• Interface Segregation: Focused interfaces like Reachable provide specific contracts
• Dependency Inversion: High-level modules depend on abstractions (e.g., Entity abstraction rather than concrete types)

Design Patterns:

• Singleton pattern for Engine class ensuring single simulation instance
• Strategy pattern for move processing
• Template method pattern in entity hierarchy

Package Organization:

com.knpdev.core      - Application core (Engine, FileProcessor, App)
com.knpdev.entity    - Domain entities (Adventurer, Mountain, Treasure, Orientation)
com.knpdev.map       - Map representation (RegionMap, Cell, Location)
com.knpdev.move      - Movement logic (MoveManager, MoveParser, Move)

Code Quality

Test-Driven Development:

• 12 test classes covering all major components
• 97% line coverage, 93% branch coverage (enforced via JaCoCo)
• Unit tests for: AppTest, EngineTest, FileProcessorTest, AdventurerTest, EntityTest, OrientationTest, TreasureTest, CellTest, RegionMapTest, MoveTest, MoveParserTest, MoveManagerTest

Static Analysis & Code Standards:

• Google Java Format for consistent formatting (enforced via Spotless)
• PMD static analysis with quickstart ruleset
• SpotBugs analysis at maximum effort level
• Maven Enforcer for dependency convergence and version requirements
• Comprehensive Javadoc documentation for public APIs

Build Verification: All code must pass:

• Compilation with Java 25
• Unit tests execution
• 80% line coverage and 70% branch coverage thresholds
• PMD and SpotBugs checks with zero violations
• Code formatting verification

Dependencies

Runtime Environment:

Java 25
Maven 3.9.0+

Testing Frameworks:

JUnit Jupiter 6.0.1      - Unit testing framework
AssertJ 3.27.6           - Fluent assertion library
System Lambda 1.0.0      - Testing system interactions

Code Quality Tools:

Spotless 3.0.0           - Code formatting enforcement (Google Java Format 1.31.0)
JaCoCo 0.8.14            - Code coverage analysis
SpotBugs 4.9.8.1         - Static bug detection
PMD 3.28.0               - Source code analyzer
Maven Enforcer 3.6.2     - Build rules enforcement

Documentation & Build:

Maven Javadoc 3.12.0     - API documentation generation
Maven Compiler 3.14.1    - Java compilation
Maven Surefire 3.5.4     - Test execution
Maven Site 4.0.0-M16     - Project site generation
Maven Jar 3.4.2          - JAR packaging

Build

Quick Build (skip tests):

mvn clean package -DskipTests

Full Build & Verification (recommended):

mvn clean verify

This executes:

• Compilation
• Code formatting verification (Spotless)
• PMD static analysis
• Unit tests with coverage collection
• SpotBugs analysis
• JaCoCo coverage threshold enforcement (80% line, 70% branch)

Generate Project Documentation:

mvn site

Produces comprehensive reports:

• JaCoCo coverage report (target/site/jacoco/index.html)
• PMD analysis report (target/reports/pmd.html)
• SpotBugs findings (target/spotbugsXml.xml)
• Javadoc API documentation (target/site/apidocs/index.html)
• Test results (target/surefire-reports/)

Build Javadoc JAR:

mvn javadoc:jar

Run

Execute the application:

java -jar treasure-1.0.0.jar <input-file-path> <output-file-path>

Example:

java -jar treasure-1.0.0.jar samples/example_3x4_input.txt output.txt

Sample Files: The samples/ directory contains test cases:

• example_3x4_* - Basic 3x4 map scenario
• indiana_adventure_* - Complex adventure scenario
• mountain_maze_* - Navigation with obstacles
• simple_turns_* - Rotation mechanics test
• treasure_hunt_* - Multiple treasure collection
• two_adventurers_* - Multi-adventurer simulation

Each sample includes both input and expected output files for validation.

Input File Format

# Comment lines start with #
C - <width> - <height>                              # Map dimensions
M - <x> - <y>                                       # Mountain position
T - <x> - <y> - <treasure_count>                    # Treasure location
A - <name> - <x> - <y> - <orientation> - <moves>    # Adventurer configuration

Orientations: N (North), S (South), E (East), O (West)
Moves: A (Advance), G (Turn Left/Gauche), D (Turn Right/Droite)

Output File Format

The output file contains the final state after simulation:

• Map dimensions (C)
• Mountain positions (M)
• Remaining treasures with counts (T)
• Adventurer final positions with treasures collected (A)