feat: extract ErrorCollector utility and add AddError overload

Address review comments from wgtmac on PR #358:

1. Add AddError(Error err) overload to accept existing Error objects
   This allows propagating errors from other components without
   deconstructing and reconstructing them.

2. Extract error collection into reusable ErrorCollector utility class
   This eliminates code duplication between PendingUpdateTyped and
   TableMetadataBuilder, and provides a reusable pattern for other
   builders in the codebase.

Changes:
- Add src/iceberg/util/error_collector.h with ErrorCollector class
- Update PendingUpdateTyped to use ErrorCollector internally
- Update TableMetadataBuilder to use ErrorCollector instead of
  std::vector<Error>
- Add test for AddError(Error err) overload
- Add comprehensive documentation with usage examples

All 12 tests pass.

Author: shangxinli

src/iceberg/pending_update.h

@@ -22,12 +22,10 @@
 /// \file iceberg/pending_update.h
 /// API for table changes using builder pattern
 
-#include <string>
-#include <vector>
-
 #include "iceberg/iceberg_export.h"
 #include "iceberg/result.h"
 #include "iceberg/type_fwd.h"
+#include "iceberg/util/error_collector.h"
 
 namespace iceberg {
 
@@ -126,13 +124,20 @@ class ICEBERG_EXPORT PendingUpdateTyped : public PendingUpdate {
   /// \param kind The kind of error
   /// \param message The error message
   void AddError(ErrorKind kind, std::string message) {
-    errors_.emplace_back(kind, std::move(message));
+    error_collector_.AddError(kind, std::move(message));
   }
 
+  /// \brief Add an existing error object to be returned later
+  ///
+  /// Useful when propagating errors from other components.
+  ///
+  /// \param err The error to add
+  void AddError(Error err) { error_collector_.AddError(std::move(err)); }
+
   /// \brief Check if any errors have been collected
   ///
   /// \return true if there are accumulated errors
-  bool HasErrors() const { return !errors_.empty(); }
+  bool HasErrors() const { return error_collector_.HasErrors(); }
 
   /// \brief Check for accumulated errors and return them if any exist
   ///
@@ -141,26 +146,17 @@ class ICEBERG_EXPORT PendingUpdateTyped : public PendingUpdate {
   ///
   /// \return Status::OK if no errors, or a ValidationFailed error with
   ///         all accumulated error messages
-  Status CheckErrors() const {
-    if (!errors_.empty()) {
-      std::string error_msg = "Validation failed due to the following errors:\n";
-      for (const auto& [kind, message] : errors_) {
-        error_msg += "  - " + message + "\n";
-      }
-      return ValidationFailed("{}", error_msg);
-    }
-    return {};
-  }
+  Status CheckErrors() const { return error_collector_.CheckErrors(); }
 
   /// \brief Clear all accumulated errors
   ///
   /// This can be useful for resetting the error state in tests or
   /// when reusing a builder instance.
-  void ClearErrors() { errors_.clear(); }
+  void ClearErrors() { error_collector_.ClearErrors(); }
 
  private:
   // Error collection (since builder methods return *this and cannot throw)
-  std::vector<Error> errors_;
+  ErrorCollector error_collector_;
 };
 
 }  // namespace iceberg

src/iceberg/table_metadata.cc

@@ -36,6 +36,7 @@
 #include "iceberg/snapshot.h"
 #include "iceberg/sort_order.h"
 #include "iceberg/table_update.h"
+#include "iceberg/util/error_collector.h"
 #include "iceberg/util/gzip_internal.h"
 #include "iceberg/util/macros.h"
 #include "iceberg/util/uuid.h"
@@ -276,7 +277,7 @@ struct TableMetadataBuilder::Impl {
   std::vector<std::unique_ptr<TableUpdate>> changes;
 
   // Error collection (since methods return *this and cannot throw)
-  std::vector<Error> errors;
+  ErrorCollector error_collector;
 
   // Metadata location tracking
   std::optional<std::string> metadata_location;
@@ -348,7 +349,8 @@ TableMetadataBuilder& TableMetadataBuilder::AssignUUID(std::string_view uuid) {
 
   // Validation: UUID cannot be empty
   if (uuid_str.empty()) {
-    impl_->errors.emplace_back(ErrorKind::kInvalidArgument, "Cannot assign empty UUID");
+    impl_->error_collector.AddError(ErrorKind::kInvalidArgument,
+                                    "Cannot assign empty UUID");
     return *this;
   }
 
@@ -499,13 +501,7 @@ TableMetadataBuilder& TableMetadataBuilder::RemoveEncryptionKey(std::string_view
 
 Result<std::unique_ptr<TableMetadata>> TableMetadataBuilder::Build() {
   // 1. Check for accumulated errors
-  if (!impl_->errors.empty()) {
-    std::string error_msg = "Failed to build TableMetadata due to validation errors:\n";
-    for (const auto& [kind, message] : impl_->errors) {
-      error_msg += "  - " + message + "\n";
-    }
-    return CommitFailed("{}", error_msg);
-  }
+  ICEBERG_RETURN_UNEXPECTED(impl_->error_collector.CheckErrors());
 
   // 2. Validate metadata consistency through TableMetadata#Validate
 

src/iceberg/test/pending_update_test.cc

@@ -94,6 +94,9 @@ class MockPendingUpdate : public PendingUpdateTyped<MockSnapshot> {
   bool ApplyCalled() const { return apply_called_; }
   bool CommitCalled() const { return commit_called_; }
 
+  // Test helper to expose protected AddError(Error) method
+  void TestAddExistingError(Error err) { AddError(std::move(err)); }
+
  private:
   std::string name_;
   int64_t id_ = 0;
@@ -201,4 +204,18 @@ TEST(PendingUpdateTest, ErrorCollectionPartialValidation) {
   EXPECT_THAT(result, HasErrorMessage("ID must be non-negative"));
 }
 
+TEST(PendingUpdateTest, ErrorCollectionAddErrorOverload) {
+  // Test the AddError(Error err) overload for adding existing error objects
+  MockPendingUpdate update;
+
+  // Create an error externally and add it
+  Error external_error{.kind = ErrorKind::kInvalidArgument,
+                       .message = "External error message"};
+  update.TestAddExistingError(std::move(external_error));
+
+  auto result = update.Apply();
+  EXPECT_THAT(result, IsError(ErrorKind::kValidationFailed));
+  EXPECT_THAT(result, HasErrorMessage("External error message"));
+}
+
 }  // namespace iceberg

src/iceberg/util/error_collector.h

@@ -0,0 +1,126 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+#pragma once
+
+/// \file iceberg/util/error_collector.h
+/// Utility for collecting validation errors in builder patterns
+
+#include <string>
+#include <vector>
+
+#include "iceberg/result.h"
+
+namespace iceberg {
+
+/// \brief Utility class for collecting validation errors in builder patterns
+///
+/// This class provides error accumulation functionality for builders that
+/// cannot throw exceptions. Builder methods can call AddError() to accumulate
+/// validation errors, and CheckErrors() returns all errors at once.
+///
+/// This allows users to see all validation errors at once rather than fixing
+/// them one by one (fail-slow instead of fail-fast).
+///
+/// Example usage:
+/// \code
+///   class MyBuilder {
+///    protected:
+///     ErrorCollector errors_;
+///
+///     MyBuilder& SetValue(int val) {
+///       if (val < 0) {
+///         errors_.AddError(ErrorKind::kInvalidArgument, "Value must be non-negative");
+///         return *this;
+///       }
+///       value_ = val;
+///       return *this;
+///     }
+///
+///     Result<MyObject> Build() {
+///       ICEBERG_RETURN_UNEXPECTED(errors_.CheckErrors());
+///       return MyObject{value_};
+///     }
+///   };
+/// \endcode
+class ErrorCollector {
+ public:
+  ErrorCollector() = default;
+
+  /// \brief Add a validation error
+  ///
+  /// \param kind The kind of error
+  /// \param message The error message
+  void AddError(ErrorKind kind, std::string message) {
+    errors_.emplace_back(kind, std::move(message));
+  }
+
+  /// \brief Add an existing error object
+  ///
+  /// Useful when propagating errors from other components or reusing
+  /// error objects without deconstructing and reconstructing them.
+  ///
+  /// \param err The error to add
+  void AddError(Error err) { errors_.push_back(std::move(err)); }
+
+  /// \brief Check if any errors have been collected
+  ///
+  /// \return true if there are accumulated errors
+  bool HasErrors() const { return !errors_.empty(); }
+
+  /// \brief Get the number of errors collected
+  ///
+  /// \return The count of accumulated errors
+  size_t ErrorCount() const { return errors_.size(); }
+
+  /// \brief Check for accumulated errors and return them if any exist
+  ///
+  /// This should be called before completing a builder operation (e.g.,
+  /// in Build(), Apply(), or Commit() methods) to validate that no errors
+  /// were accumulated during the builder method calls.
+  ///
+  /// \return Status::OK if no errors, or a ValidationFailed error with
+  ///         all accumulated error messages
+  Status CheckErrors() const {
+    if (!errors_.empty()) {
+      std::string error_msg = "Validation failed due to the following errors:\n";
+      for (const auto& [kind, message] : errors_) {
+        error_msg += "  - " + message + "\n";
+      }
+      return ValidationFailed("{}", error_msg);
+    }
+    return {};
+  }
+
+  /// \brief Clear all accumulated errors
+  ///
+  /// This can be useful for resetting the error state in tests or
+  /// when reusing a builder instance.
+  void ClearErrors() { errors_.clear(); }
+
+  /// \brief Get read-only access to all collected errors
+  ///
+  /// \return A const reference to the vector of errors
+  const std::vector<Error>& Errors() const { return errors_; }
+
+ private:
+  std::vector<Error> errors_;
+};
+
+}  // namespace iceberg