Merge pull request #89 from bboczula/codex/issue-45-diagnostics-helpers

[AS2-E2-S6] Add diagnostics helpers for probe and decode failures

Author: bboczula

source/common/AssetSuite.cpp

@@ -4,6 +4,7 @@
 #include "AssetSuiteContext.h"
 
 #include "../runtime/AssetSuiteRuntime.h"
+#include "../runtime/AssetSuiteRuntimeDiagnostics.h"
 #include "../runtime/AssetSuiteRuntimeState.h"
 #include "../wavefront/ModelLoader.h"
 #include "../bmp/BmpDecoder.h"
@@ -182,7 +183,10 @@ AssetSuite::Result AssetSuite::LoadFile(ContextHandle context, const char* fileP
 	const Result mappedResult = MapFileLoadResult(loadResult);
 	if (mappedResult != Result::Success)
 	{
-		context->Runtime().Diagnostics().Add(loadResult, "Failed to load blob source file.");
+		context->Runtime().EmitDiagnostic(
+			loadResult,
+			LogLevel::Error,
+			Internal::Diagnostics::BlobLoadFailed);
 		return mappedResult;
 	}
 
@@ -246,13 +250,17 @@ AssetSuite::Result AssetSuite::DecodeImageFromFile(ContextHandle context, const
 	const Result mappedResult = MapFileLoadResult(loadResult);
 	if (mappedResult != Result::Success)
 	{
-		context->Runtime().Diagnostics().Add(loadResult, "Failed to load image source file.");
+		context->Runtime().EmitDiagnostic(
+			loadResult,
+			LogLevel::Error,
+			Internal::Diagnostics::ImageLoadFailed);
 		return mappedResult;
 	}
 
 	try
 	{
 		Internal::Blob blob(std::move(rawBytes), Internal::MakeBlobSourceMetadata(filePath));
+		// DecodeImageBlob owns probe/decode diagnostics so this wrapper does not duplicate them.
 		return context->Runtime().DecodeImageBlob(blob, outImage);
 	}
 	catch (const std::bad_alloc&)
@@ -308,13 +316,17 @@ AssetSuite::Result AssetSuite::DecodeMeshFromFile(ContextHandle context, const c
 	const Result mappedResult = MapFileLoadResult(loadResult);
 	if (mappedResult != Result::Success)
 	{
-		context->Runtime().Diagnostics().Add(loadResult, "Failed to load mesh source file.");
+		context->Runtime().EmitDiagnostic(
+			loadResult,
+			LogLevel::Error,
+			Internal::Diagnostics::MeshLoadFailed);
 		return mappedResult;
 	}
 
 	try
 	{
 		Internal::Blob blob(std::move(rawBytes), Internal::MakeBlobSourceMetadata(filePath));
+		// DecodeMeshBlob owns probe/decode diagnostics so this wrapper does not duplicate them.
 		return context->Runtime().DecodeMeshBlob(blob, outMesh);
 	}
 	catch (const std::bad_alloc&)

source/runtime/AssetSuiteRuntime.cpp

@@ -1,4 +1,5 @@
 #include "AssetSuiteRuntime.h"
+#include "AssetSuiteRuntimeDiagnostics.h"
 
 #include <new>
 #include <utility>
@@ -158,28 +159,40 @@ AssetSuite::Result AssetSuite::Internal::RuntimeContext::DecodeImageBlob(
 		static_cast<size_t>(blob.ByteSize()));
 	if (decoder == ImageDecoders::Auto)
 	{
-		Diagnostics().Add(ErrorCode::FileTypeNotSupported, "Image blob format is not supported.");
+		EmitDiagnostic(
+			ErrorCode::FileTypeNotSupported,
+			LogLevel::Warning,
+			Diagnostics::UnsupportedImageFormat);
 		return Result::ErrorUnsupportedFormat;
 	}
 
 	if (!HasMinimumImageDecodeBytes(decoder, blob))
 	{
-		Diagnostics().Add(ErrorCode::Undefined, "Image blob is too small for the selected decoder.");
+		EmitDiagnostic(
+			ErrorCode::Undefined,
+			LogLevel::Error,
+			Diagnostics::ImageBlobTooSmall);
 		return Result::ErrorMalformedData;
 	}
 
 	ImageDecoder* imageDecoder = CodecRegistry().FindImageDecoder(decoder);
 	if (!imageDecoder)
 	{
-		Diagnostics().Add(ErrorCode::FileTypeNotSupported, "Image decoder is not registered.");
+		EmitDiagnostic(
+			ErrorCode::FileTypeNotSupported,
+			LogLevel::Warning,
+			Diagnostics::ImageDecoderMissing);
 		return Result::ErrorUnsupportedFormat;
 	}
 
 	std::vector<BYTE> decodedBytes;
 	ImageDescriptor descriptor = {};
 	if (!imageDecoder->Decode(decodedBytes, const_cast<BYTE*>(reinterpret_cast<const BYTE*>(blob.Data())), descriptor))
 	{
-		Diagnostics().Add(ErrorCode::Undefined, "Image decoder rejected malformed data.");
+		EmitDiagnostic(
+			ErrorCode::Undefined,
+			LogLevel::Error,
+			Diagnostics::ImageDecodeRejected);
 		return MapSelectedDecoderFailure();
 	}
 
@@ -218,20 +231,29 @@ AssetSuite::Result AssetSuite::Internal::RuntimeContext::DecodeMeshBlob(
 		static_cast<size_t>(blob.ByteSize()));
 	if (decoder == MeshDecoders::Auto)
 	{
-		Diagnostics().Add(ErrorCode::FileTypeNotSupported, "Mesh blob format is not supported.");
+		EmitDiagnostic(
+			ErrorCode::FileTypeNotSupported,
+			LogLevel::Warning,
+			Diagnostics::UnsupportedMeshFormat);
 		return Result::ErrorUnsupportedFormat;
 	}
 
 	if (!HasMinimumMeshDecodeBytes(decoder, blob))
 	{
-		Diagnostics().Add(ErrorCode::Undefined, "Mesh blob is too small for the selected decoder.");
+		EmitDiagnostic(
+			ErrorCode::Undefined,
+			LogLevel::Error,
+			Diagnostics::MeshBlobTooSmall);
 		return Result::ErrorMalformedData;
 	}
 
 	MeshDecoder* meshDecoder = CodecRegistry().FindMeshDecoder(decoder);
 	if (!meshDecoder)
 	{
-		Diagnostics().Add(ErrorCode::FileTypeNotSupported, "Mesh decoder is not registered.");
+		EmitDiagnostic(
+			ErrorCode::FileTypeNotSupported,
+			LogLevel::Warning,
+			Diagnostics::MeshDecoderMissing);
 		return Result::ErrorUnsupportedFormat;
 	}
 
@@ -242,7 +264,10 @@ AssetSuite::Result AssetSuite::Internal::RuntimeContext::DecodeMeshBlob(
 	MeshDescriptor descriptor = {};
 	if (!meshDecoder->Decode(decodedBytes, decodeBuffer.data(), descriptor))
 	{
-		Diagnostics().Add(ErrorCode::Undefined, "Mesh decoder rejected malformed data.");
+		EmitDiagnostic(
+			ErrorCode::Undefined,
+			LogLevel::Error,
+			Diagnostics::MeshDecodeRejected);
 		return MapSelectedDecoderFailure();
 	}
 
@@ -294,3 +319,12 @@ void AssetSuite::Internal::RuntimeContext::DispatchLogEvent(LogLevel level, cons
 
 	logging.callback(level, message, logging.userData);
 }
+
+void AssetSuite::Internal::RuntimeContext::EmitDiagnostic(
+	ErrorCode code,
+	LogLevel level,
+	const char* message)
+{
+	Diagnostics().Add(code, message);
+	DispatchLogEvent(level, message);
+}

source/runtime/AssetSuiteRuntime.h

@@ -36,6 +36,7 @@ namespace AssetSuite::Internal
 
 		void SetLoggingCallback(LoggingCallback callback, LogLevel minimumLevel, void* userData) noexcept;
 		void DispatchLogEvent(LogLevel level, const char* message) const;
+		void EmitDiagnostic(ErrorCode code, LogLevel level, const char* message);
 
 	private:
 		struct LoggingState

source/runtime/AssetSuiteRuntimeDiagnostics.h

@@ -0,0 +1,29 @@
+#pragma once
+
+namespace AssetSuite::Internal::Diagnostics
+{
+	inline constexpr const char* UnsupportedImageFormat =
+		"ASSET_UNSUPPORTED_FORMAT: Image blob format is not supported.";
+	inline constexpr const char* ImageBlobTooSmall =
+		"ASSET_MALFORMED_DATA: Image blob is too small for the selected decoder.";
+	inline constexpr const char* ImageDecoderMissing =
+		"ASSET_UNSUPPORTED_FORMAT: Image decoder is not registered.";
+	inline constexpr const char* ImageDecodeRejected =
+		"ASSET_MALFORMED_DATA: Image decoder rejected malformed data.";
+
+	inline constexpr const char* UnsupportedMeshFormat =
+		"ASSET_UNSUPPORTED_FORMAT: Mesh blob format is not supported.";
+	inline constexpr const char* MeshBlobTooSmall =
+		"ASSET_MALFORMED_DATA: Mesh blob is too small for the selected decoder.";
+	inline constexpr const char* MeshDecoderMissing =
+		"ASSET_UNSUPPORTED_FORMAT: Mesh decoder is not registered.";
+	inline constexpr const char* MeshDecodeRejected =
+		"ASSET_MALFORMED_DATA: Mesh decoder rejected malformed data.";
+
+	inline constexpr const char* BlobLoadFailed =
+		"ASSET_FILE_LOAD_FAILED: Failed to load blob source file.";
+	inline constexpr const char* ImageLoadFailed =
+		"ASSET_FILE_LOAD_FAILED: Failed to load image source file.";
+	inline constexpr const char* MeshLoadFailed =
+		"ASSET_FILE_LOAD_FAILED: Failed to load mesh source file.";
+}

source/runtime/README.md

@@ -67,6 +67,14 @@ persistent public `BlobHandle`.
 
 The public SDK adapter maps `NonExistingFile` to `Result::ErrorFileNotFound` and `IoFailure` to `Result::ErrorIoFailure`. Text-mode loads append a null terminator after successful reads; binary loads preserve the exact file bytes.
 
+## Diagnostics And Logging
+
+Runtime probe, decode, and file-load failures record private diagnostics and may emit one callback log event through the registered logging callback. Callback messages use stable internal `ASSET_*` prefixes, but diagnostic storage and runtime error details remain private implementation state.
+
+Decode-from-file wrappers own file-load diagnostics only. Once bytes are wrapped in a temporary blob, `DecodeImageBlob` and `DecodeMeshBlob` own probe/decode diagnostics so a single public failure path does not log the same failure twice.
+
+This story keeps cleanup scope limited to cleanup that occurs inside failed file/decode wrapper flows. Explicit invalid cleanup API calls such as failed `ReleaseBlob`, `ReleaseImage`, `ReleaseMesh`, and repeated `DestroyContext` validation remain non-logging paths unless a later story expands that behavior.
+
 ## Deferred Scope
 
 This runtime layer is intentionally foundational. The following work is deferred to later stories: