feat(test-mode): add failure type categorization (Phase 3)

Added type-safe failure categorization for --test-mode.

Hook and dependency extraction failures are now logged as warnings
and allow processing to continue, while resolution and bootstrap
failures remain fatal to the package.

Co-Authored-By: Claude <[email protected]>

Signed-off-by: Lalatendu Mohanty <[email protected]>

Author: LalatenduMohanty

src/fromager/bootstrapper.py

@@ -58,6 +58,28 @@ class SourceBuildResult:
     source_type: SourceType
 
 
+# Valid failure types for test mode error recording
+FailureType = typing.Literal["resolution", "bootstrap", "hook", "dependency_extraction"]
+
+
+class FailureRecord(typing.TypedDict):
+    """Record of a package that failed during bootstrap in test mode.
+
+    Attributes:
+        package: The package name that failed.
+        version: The resolved version (None if resolution failed).
+        exception_type: The exception class name.
+        exception_message: The exception message string.
+        failure_type: Category of failure for analysis.
+    """
+
+    package: str
+    version: str | None
+    exception_type: str
+    exception_message: str
+    failure_type: FailureType
+
+
 class Bootstrapper:
     def __init__(
         self,
@@ -98,8 +120,8 @@ def __init__(
 
         self._build_order_filename = self.ctx.work_dir / "build-order.json"
 
-        # Track failed packages in test mode (list of dicts for JSON export)
-        self.failed_packages: list[dict[str, typing.Any]] = []
+        # Track failed packages in test mode (list of typed dicts for JSON export)
+        self.failed_packages: list[FailureRecord] = []
 
     def resolve_and_add_top_level(
         self,
@@ -141,17 +163,7 @@ def resolve_and_add_top_level(
         except Exception as err:
             if not self.test_mode:
                 raise
-            logger.error(
-                "test mode: failed to resolve %s: %s", req.name, err, exc_info=True
-            )
-            self.failed_packages.append(
-                {
-                    "package": str(req.name),
-                    "version": None,
-                    "exception_type": err.__class__.__name__,
-                    "exception_message": str(err),
-                }
-            )
+            self._record_test_mode_failure(req, None, err, "resolution")
             return None
 
     def resolve_version(
@@ -227,23 +239,18 @@ def bootstrap(self, req: Requirement, req_type: RequirementType) -> None:
                 version = str(resolved_version)
             else:
                 version = None
-            logger.error(
-                "test mode: failed to bootstrap %s: %s", req.name, err, exc_info=True
-            )
-            self.failed_packages.append(
-                {
-                    "package": str(req.name),
-                    "version": version,
-                    "exception_type": err.__class__.__name__,
-                    "exception_message": str(err),
-                }
-            )
+            self._record_test_mode_failure(req, version, err, "bootstrap")
 
     def _bootstrap_impl(self, req: Requirement, req_type: RequirementType) -> None:
         """Internal implementation of bootstrap logic.
 
-        Errors raise exceptions for bootstrap() to catch and record in test mode.
-        In normal mode, exceptions propagate immediately (fail-fast).
+        Error Handling:
+            Fatal errors (version resolution, source build, prebuilt download)
+            raise exceptions for bootstrap() to catch and record.
+
+            Non-fatal errors (post-hook, dependency extraction) are recorded
+            locally and processing continues. These are recorded here because
+            the package build succeeded - only optional post-processing failed.
         """
         logger.info(f"bootstrapping {req} as {req_type} dependency of {self.why[-1:]}")
         constraint = self.ctx.constraints.get_constraint(req.name)
@@ -322,26 +329,45 @@ def _bootstrap_impl(self, req: Requirement, req_type: RequirementType) -> None:
                     unpacked_cached_wheel=unpacked_cached_wheel,
                 )
 
-            # Run post-bootstrap hooks
-            hooks.run_post_bootstrap_hooks(
-                ctx=self.ctx,
-                req=req,
-                dist_name=canonicalize_name(req.name),
-                dist_version=str(resolved_version),
-                sdist_filename=build_result.sdist_filename,
-                wheel_filename=build_result.wheel_filename,
-            )
+            # Run post-bootstrap hooks (non-fatal in test mode)
+            try:
+                hooks.run_post_bootstrap_hooks(
+                    ctx=self.ctx,
+                    req=req,
+                    dist_name=canonicalize_name(req.name),
+                    dist_version=str(resolved_version),
+                    sdist_filename=build_result.sdist_filename,
+                    wheel_filename=build_result.wheel_filename,
+                )
+            except Exception as hook_error:
+                if not self.test_mode:
+                    raise
+                self._record_test_mode_failure(
+                    req, str(resolved_version), hook_error, "hook", "warning"
+                )
 
-            # Extract install dependencies
-            install_dependencies = self._get_install_dependencies(
-                req=req,
-                resolved_version=resolved_version,
-                wheel_filename=build_result.wheel_filename,
-                sdist_filename=build_result.sdist_filename,
-                sdist_root_dir=build_result.sdist_root_dir,
-                build_env=build_result.build_env,
-                unpack_dir=build_result.unpack_dir,
-            )
+            # Extract install dependencies (non-fatal in test mode)
+            try:
+                install_dependencies = self._get_install_dependencies(
+                    req=req,
+                    resolved_version=resolved_version,
+                    wheel_filename=build_result.wheel_filename,
+                    sdist_filename=build_result.sdist_filename,
+                    sdist_root_dir=build_result.sdist_root_dir,
+                    build_env=build_result.build_env,
+                    unpack_dir=build_result.unpack_dir,
+                )
+            except Exception as dep_error:
+                if not self.test_mode:
+                    raise
+                self._record_test_mode_failure(
+                    req,
+                    str(resolved_version),
+                    dep_error,
+                    "dependency_extraction",
+                    "warning",
+                )
+                install_dependencies = []
 
             logger.debug(
                 "install dependencies: %s",
@@ -388,6 +414,40 @@ def _track_why(
         finally:
             self.why.pop()
 
+    def _record_test_mode_failure(
+        self,
+        req: Requirement,
+        version: str | None,
+        err: Exception,
+        failure_type: FailureType,
+        log_level: typing.Literal["error", "warning"] = "error",
+    ) -> None:
+        """Record a failure in test mode. Call this after checking test_mode.
+
+        Args:
+            req: The requirement that failed.
+            version: The version being processed (None if not yet resolved).
+            err: The exception that was raised.
+            failure_type: Category of failure for analysis.
+            log_level: Log at error (fatal) or warning (non-fatal, continuing).
+        """
+        version_str = f"=={version}" if version else ""
+        msg = f"test mode: {failure_type} failed for {req.name}{version_str}"
+        if log_level == "warning":
+            logger.warning("%s: %s (continuing)", msg, err)
+        else:
+            logger.error("%s: %s", msg, err, exc_info=True)
+
+        self.failed_packages.append(
+            {
+                "package": str(req.name),
+                "version": version,
+                "exception_type": err.__class__.__name__,
+                "exception_message": str(err),
+                "failure_type": failure_type,
+            }
+        )
+
     @property
     def _explain(self) -> str:
         """Return message formatting current version of why stack."""

tests/test_bootstrap_test_mode.py

@@ -1,10 +1,11 @@
-"""Tests for --test-mode feature (Phase 2: JSON Failure Reports).
+"""Tests for --test-mode feature (Phase 3: Failure Type Categorization).
 
 Tests the test mode functionality:
 - Bootstrapper initialization with test_mode flag
 - Exception handling: catch errors, log, continue
 - Bootstrapper.finalize() exit codes
 - JSON failure report generation
+- failure_type field for categorizing failures
 """
 
 import json
@@ -93,6 +94,7 @@ def test_finalize_with_failures_returns_one(
                 "version": "1.0.0",
                 "exception_type": "RuntimeError",
                 "exception_message": "Build failed",
+                "failure_type": "bootstrap",
             }
         )
         assert bt.finalize() == 1
@@ -109,6 +111,7 @@ def test_finalize_not_in_test_mode_returns_zero(
                 "version": "1.0.0",
                 "exception_type": "RuntimeError",
                 "exception_message": "Error",
+                "failure_type": "bootstrap",
             }
         )
         assert bt.finalize() == 0
@@ -125,18 +128,21 @@ def test_finalize_logs_failed_packages(
                     "version": "1.0",
                     "exception_type": "E",
                     "exception_message": "m",
+                    "failure_type": "bootstrap",
                 },
                 {
                     "package": "pkg-b",
                     "version": "2.0",
                     "exception_type": "E",
                     "exception_message": "m",
+                    "failure_type": "hook",
                 },
                 {
                     "package": "pkg-c",
                     "version": "3.0",
                     "exception_type": "E",
                     "exception_message": "m",
+                    "failure_type": "dependency_extraction",
                 },
             ]
         )
@@ -170,6 +176,7 @@ def test_finalize_writes_json_report(
                 "version": "1.0.0",
                 "exception_type": "CalledProcessError",
                 "exception_message": "Compilation failed",
+                "failure_type": "bootstrap",
             }
         )
 
@@ -189,6 +196,7 @@ def test_finalize_writes_json_report(
         assert report["failures"][0]["version"] == "1.0.0"
         assert report["failures"][0]["exception_type"] == "CalledProcessError"
         assert report["failures"][0]["exception_message"] == "Compilation failed"
+        assert report["failures"][0]["failure_type"] == "bootstrap"
 
     def test_finalize_no_report_when_no_failures(
         self, mock_context: context.WorkContext
@@ -212,6 +220,7 @@ def test_finalize_report_with_null_version(
                 "version": None,
                 "exception_type": "ResolutionError",
                 "exception_message": "Could not resolve version",
+                "failure_type": "resolution",
             }
         )
 
@@ -223,11 +232,12 @@ def test_finalize_report_with_null_version(
             report = json.load(f)
 
         assert report["failures"][0]["version"] is None
+        assert report["failures"][0]["failure_type"] == "resolution"
 
-    def test_finalize_report_multiple_failures(
+    def test_finalize_report_multiple_failure_types(
         self, mock_context: context.WorkContext
     ) -> None:
-        """Test finalize correctly reports multiple failures."""
+        """Test finalize correctly reports multiple failures with different types."""
         bt = bootstrapper.Bootstrapper(ctx=mock_context, test_mode=True)
         bt.failed_packages.extend(
             [
@@ -236,12 +246,21 @@ def test_finalize_report_multiple_failures(
                     "version": "1.0.0",
                     "exception_type": "BuildError",
                     "exception_message": "Failed to compile",
+                    "failure_type": "bootstrap",
                 },
                 {
                     "package": "pkg-b",
                     "version": "2.0.0",
-                    "exception_type": "ConnectionError",
-                    "exception_message": "Download failed",
+                    "exception_type": "HookError",
+                    "exception_message": "Validation failed",
+                    "failure_type": "hook",
+                },
+                {
+                    "package": "pkg-c",
+                    "version": "3.0.0",
+                    "exception_type": "MetadataError",
+                    "exception_message": "Could not read metadata",
+                    "failure_type": "dependency_extraction",
                 },
             ]
         )
@@ -253,7 +272,8 @@ def test_finalize_report_multiple_failures(
         with open(report_path) as f:
             report = json.load(f)
 
-        assert len(report["failures"]) == 2
-        packages = [f["package"] for f in report["failures"]]
-        assert "pkg-a" in packages
-        assert "pkg-b" in packages
+        assert len(report["failures"]) == 3
+        failure_types = [f["failure_type"] for f in report["failures"]]
+        assert "bootstrap" in failure_types
+        assert "hook" in failure_types
+        assert "dependency_extraction" in failure_types