feat(linear-static-3d-euler-beam): step 8 - core-diagnostics

include/fesa/core/diagnostic.hpp

@@ -0,0 +1,30 @@
+#pragma once
+
+#include "fesa/core/source_identity.hpp"
+
+#include <string>
+#include <vector>
+
+namespace fesa {
+
+// Distinguishes recoverable warnings from errors that stop the current operation.
+enum class Severity {
+    warning,
+    error
+};
+
+// Carries a structured, backend-independent diagnostic record.
+struct Diagnostic {
+    Severity severity;
+    std::string code;
+    SourceLocation location;
+    std::string keyword;
+    std::string entityIdentity;
+    std::string message;
+};
+
+// Orders diagnostics by their externally visible source tuple while retaining
+// discovery order for records with identical keys.
+void sortDiagnostics(std::vector<Diagnostic>& diagnostics);
+
+} // namespace fesa

include/fesa/core/source_identity.hpp

@@ -0,0 +1,23 @@
+#pragma once
+
+#include <cstddef>
+#include <cstdint>
+#include <filesystem>
+#include <string>
+
+namespace fesa {
+
+// Identifies the physical input location that produced a model item or diagnostic.
+struct SourceLocation {
+    std::filesystem::path file;
+    std::size_t line;
+};
+
+// Preserves both semantic and raw-text forms of an input entity identity.
+struct SourceEntityId {
+    std::string instanceName;
+    std::int64_t sourceLabel;
+    std::string sourceLabelText;
+};
+
+} // namespace fesa

include/fesa/core/status.hpp

@@ -0,0 +1,94 @@
+#pragma once
+
+#include "fesa/core/diagnostic.hpp"
+
+#include <optional>
+#include <stdexcept>
+#include <utility>
+#include <vector>
+
+namespace fesa {
+
+// Maps a failure to the stable command-line exit-code classes defined by V0.
+enum class FailureCategory {
+    input,
+    model,
+    solver,
+    output
+};
+
+// Transports success or structured diagnostics without exposing backend errors.
+class Status {
+public:
+    static Status ok();
+    static Status failure(std::vector<Diagnostic> diagnostics);
+    static Status failure(
+        FailureCategory category, std::vector<Diagnostic> diagnostics);
+
+    bool isOk() const noexcept;
+    std::optional<FailureCategory> failureCategory() const noexcept;
+    const std::vector<Diagnostic>& diagnostics() const noexcept;
+
+private:
+    Status(
+        bool isOk,
+        std::optional<FailureCategory> category,
+        std::vector<Diagnostic> diagnostics);
+
+    bool isOk_;
+    std::optional<FailureCategory> category_;
+    std::vector<Diagnostic> diagnostics_;
+};
+
+// Owns exactly one successful value or one failed Status.
+template<class T>
+class Result {
+public:
+    static Result success(T value) {
+        return Result{SuccessTag{}, std::move(value)};
+    }
+
+    static Result failure(Status status) {
+        if (status.isOk()) {
+            throw std::invalid_argument{"A failed Result requires a failed Status."};
+        }
+        return Result{FailureTag{}, std::move(status)};
+    }
+
+    bool hasValue() const noexcept {
+        return value_.has_value();
+    }
+
+    T& value() {
+        if (!value_) {
+            throw std::logic_error{"Result has no value."};
+        }
+        return *value_;
+    }
+
+    const T& value() const {
+        if (!value_) {
+            throw std::logic_error{"Result has no value."};
+        }
+        return *value_;
+    }
+
+    const Status& status() const noexcept {
+        return status_;
+    }
+
+private:
+    struct SuccessTag {};
+    struct FailureTag {};
+
+    Result(SuccessTag, T value)
+        : value_{std::move(value)}, status_{Status::ok()} {}
+
+    Result(FailureTag, Status status)
+        : value_{std::nullopt}, status_{std::move(status)} {}
+
+    std::optional<T> value_;
+    Status status_;
+};
+
+} // namespace fesa