Porytiles2 MVP: Core compilation pipeline and domain architecture (#185)

This PR represents a major milestone in the Porytiles2 development
effort, establishing the core architecture and outline of the primary
tileset compilation pipeline (more implementation work to come).

- Implemented ChainableResult type for composable error handling with
context propagation
- Created FormattableError system with rich formatting capabilities
- Added UserDiagnostics interface with stderr implementation
- Introduced PT_TRY macros for ergonomic error handling
- Implemented error chain visualization with metatile and tile printers
- Added provenance tracking for configuration values

- Implemented RgbaTileNormalizer service for normalizing tiles to
canonical form
- Created NormalizedTile and NormalizedPal domain types
- Added RgbaTileDenormalizer for reconstructing original tiles from
normalized form
- Implemented tile masking system with ShapeMask (formerly MaskPixels)
- Created canonical tile types: CanonicalPixelTile and
CanonicalShapeTile
- Developed shape-based tile isomorphism detection system
- Added batch normalization capabilities

- Implemented ColorSet domain type for managing palette color
collections
- Created ColorSetBuilder service for constructing color sets
- Added ColorIndexMapBuilder for mapping colors to palette indices
- Integrated support for multiple extrinsic transparency values

- Implemented PrimaryTilesetCompiler service with multi-stage pipeline
architecture
- Created operation framework with ConstructRgbaMetatilesOp and other
pipeline operations
- Added OperandBundle for managing pipeline data flow
- Implemented tile validation services (e.g.,
validate_unique_color_count)

- Implemented RgbaLayerImageMetatileizer for converting layer images to
metatiles
- Created RgbaImageTileizer for breaking images into tiles
- Added MetatileAttribute domain model with support for
pokeemerald-specific attributes
- Implemented metatile decomposition capabilities
- Added MetatileDecompiler service stub

- Implemented ProjectTilesetArtifactReader with support for reading
pokeemerald attributes
- Created ProjectTilesetArtifactWriter with integration tests
- Added TilesPngWorkspace for managing tiles.png operations
- Enhanced artifact reading to correctly parse binary attribute formats

- Refactored TextFormatter with varargs support and multiple style
options
- Implemented FormatParam with implicit conversion support
- Removed fmtlib types from public API for better encapsulation
- Added convenience formatting methods throughout codebase

- Migrated from global config values to tileset-specific configuration
- Implemented configuration provenance tracking with
std::source_location
- Added extract_simple_function_name utility for source location
handling
- Updated DomainConfig to use tileset-prefixed keys
- Implemented lazy layered configuration evaluation

- Removed legacy BGR color classes in favor of RGBA
- Deleted IsoXTile types and associated services
- Removed domain/model subfolder structure for simplified organization
- Consolidated tile domain model package
- Refactored template library into multiple focused packages (xcut,
utilities)
- Deleted unused code and old notes files
- Created new package structure for better domain separation

- Added comprehensive unit tests for normalization, color management,
and metatileization
- Created integration tests for artifact I/O
- Added test resources for various edge cases (normalization,
attributes, etc.)
- Improved test organization under Resources/Tests/unit

- Added debug flags and coverage build configuration
- Integrated Doxygen Awesome CSS dependency
- Enhanced CMake FetchContent logging
- Added find_and_replace.sh utility script
- Updated .gitignore and launch.json configuration

- Restructured debug commands into comprehensive debug_commands.hpp
- Added tileset verification command
- Improved command validation
- Enhanced error messaging and diagnostics output

This PR establishes the foundational domain-driven design architecture
for Porytiles2:
- Clear separation between domain models, services, and utilities
- Template-based generic programming for flexibility
- Pipeline-based compilation with composable operations
- Rich error handling with full context propagation
- Transparent artifact I/O with format-agnostic interfaces

All changes include corresponding unit and integration tests. The test
suite covers:
- Tile normalization and denormalization round-trips
- Color set and index map generation
- Metatile construction and decomposition
- Artifact reading and writing
- Error handling and propagation
- Configuration provenance tracking

Major areas:
- Porytiles2/include/porytiles2/domain/ (extensive changes)
- Porytiles2/lib/domain/ (extensive changes)
- Porytiles2/include/porytiles2/utilities/ (new package structure)
- Porytiles2/tests/ (new test coverage)
- Resources/Tests/ (new test resources)

Author: grunt-lucas

.gitignore

@@ -1,13 +1,15 @@
 # IDE and filesystem metadata
 .vscode/*
 !.vscode/c_cpp_properties.json
+!.vscode/launch.json
 .idea
 .DS_Store
 .claude
 
 # Build artifacts and executables
 build/**
-cmake-build-*/**
+vscode-build/**
+clion-build-*/**
 
 # Doxygen
 Documentation/html/**

.vscode/launch.json

@@ -0,0 +1,21 @@
+{
+    "version": "0.2.0",
+    "configurations": [
+        {
+            "name": "LLDB - Porytiles2 Driver Debug Command",
+            "type": "lldb",
+            "request": "launch",
+            "program": "${workspaceFolder}/build/Porytiles2/tools/driver/porytiles2",
+            "args": ["debug", "porytiles2_test"],
+            "cwd": "${workspaceFolder}/../pokeemerald-expansion"
+        },
+        {
+            "name": "LLDB - Porytiles2AllTests",
+            "type": "lldb",
+            "request": "launch",
+            "program": "${workspaceFolder}/build/Porytiles2/tests/Porytiles2AllTests",
+            "args": [],
+            "cwd": "${workspaceFolder}"
+        }
+    ]
+}

CLAUDE.md

@@ -32,23 +32,19 @@ cmake -B build-release -DCMAKE_BUILD_TYPE=Release
 # Build project
 cmake --build build -j7
 ```
-
-### Build Variants
-Multiple build configurations are available:
-- `build/` - Debug build
-- `build-coverage/` - Debug build with coverage
-- `build-release/` - Release build
+Alternatively, if there is a build directory called `clion-build-debug`, use that instead of `build`.
 
 ## Testing
 - Doctests for legacy version at `./build/Porytiles1/tests/Porytiles1Tests`
 - GoogleTest unit tests at `./build/Porytiles2/tests/Porytiles2UnitTests`
 - GoogleTest integration tests at `./build/Porytiles2/tests/Porytiles2IntegrationTests`
+- GoogleTest all test runner at `./build/Porytiles2/tests/Porytiles2AllTests
+
+Prefer to simply run all tests using the all test runner.
 
 Run all tests:
 ```bash
-./build/Porytiles1/tests/Porytiles1Tests
-./build/Porytiles2/tests/Porytiles2UnitTests
-./build/Porytiles2/tests/Porytiles2IntegrationTests
+./build/Porytiles2/tests/Porytiles2AllTests # this runs both Porytiles2UnitTests and Porytiles2IntegrationTests
 ```
 
 ## Code Quality Tools
@@ -112,7 +108,7 @@ Use the following example snippet as a guide for code style.
 - **Never** include header files using relative paths
 - Follow const correctness principles
 - Always use namespace `porytiles2`, don't create child namespaces
-- When creating private helper functions, if possible **prefer to place them in an anonymous namespace in the cpp file** instead of the `private:` section of the header file
+- When creating private helper functions, **PREFER TO PLACE THEM IN AN ANONYMOUS NAMESPACE IN THE CPP FILE** instead of the `private:` section of the header file
 - Both GCC and Clang are supported compilers, so any proposed code **should not be compiler-specific**
 - WHEN RUNNING THE CMAKE BUILD COMMAND, SEND OUTPUT TO A TEMPORARY FILE SO YOU DON'T POLLUTE YOUR CONTEXT. You can then check if the build succeeded by looking at the exit code. If non-zero, inspect the file and see what went wrong.
 

CMakeLists.txt

@@ -6,6 +6,7 @@ set(CMAKE_CXX_STANDARD 23)
 set(CMAKE_CXX_STANDARD_REQUIRED ON)
 set(CMAKE_CXX_EXTENSIONS OFF)
 set(CMAKE_VERBOSE_MAKEFILE ON)
+set(FETCHCONTENT_QUIET OFF)
 
 # Enable compilation warnings
 if (MSVC)

Documentation/CMakeLists.txt

@@ -2,7 +2,7 @@ include(FetchContent)
 FetchContent_Declare(
         doxygen-awesome-css
         GIT_REPOSITORY "https://github.com/jothepro/doxygen-awesome-css"
-        GIT_TAG "v2.3.4")
+        GIT_TAG "v2.4.0")
 FetchContent_MakeAvailable(doxygen-awesome-css)
 FetchContent_GetProperties(doxygen-awesome-css SOURCE_DIR AWESOME_CSS_DIR)
 

Porytiles2/CMakeLists.txt

@@ -2,6 +2,8 @@
 # Set a variable that points to the global include directory for Porytiles
 set(PORYTILES2_INCLUDE_DIR ${CMAKE_SOURCE_DIR}/Porytiles2/include)
 
+set(CMAKE_CXX_FLAGS_DEBUG "-O0 -g -fstandalone-debug -fno-limit-debug-info -fno-omit-frame-pointer")
+
 add_subdirectory(lib)
 add_subdirectory(tests)
 add_subdirectory(tools)

Porytiles2/Notes/artifact_key_crtp.md

@@ -4,7 +4,7 @@
 
 The following code is **not legal C++** because virtual functions cannot be templated:
 
-```cpp
+```c++
 template<typename T>
 [[nodiscard]] virtual ArtifactKey<T> key_for(const std::string &tileset_name, const TilesetArtifact &artifact) const = 0;
 ```
@@ -17,7 +17,7 @@ Move the template to the class level and use static polymorphism instead of virt
 
 ### Basic Implementation
 
-```cpp
+```c++
 template<typename T, typename Derived>
 class ArtifactKeyProvider {
 public:
@@ -42,7 +42,7 @@ public:
 
 ### Simple Concept Constraint
 
-```cpp
+```c++
 #include <concepts>
 #include <type_traits>
 
@@ -68,7 +68,7 @@ public:
 
 ### Comprehensive Concept with Additional Checks
 
-```cpp
+```c++
 // More detailed concept with additional checks
 template<typename Derived, typename T>
 concept HasKeyForImpl = requires {
@@ -94,7 +94,7 @@ concept IsArtifactKeyProvider =
 
 If you're not on C++20 or prefer static assertions:
 
-```cpp
+```c++
 template<typename T, typename Derived>
 class ArtifactKeyProvider {
 private:
@@ -128,7 +128,7 @@ public:
 
 ### Correct Implementation
 
-```cpp
+```c++
 // This will compile fine
 template<typename T>
 class GoodProvider : public ArtifactKeyProvider<T, GoodProvider<T>> {
@@ -142,7 +142,7 @@ public:
 
 ### Incorrect Implementation (Compile-Time Error)
 
-```cpp
+```c++
 // This will fail at compile time with a clear error about not satisfying HasKeyForImpl
 template<typename T>
 class BadProvider : public ArtifactKeyProvider<T, BadProvider<T>> {