feat #158: implement pretty-printing for pydantic validation errors

Signed-off-by: sushant-suse <[email protected]>

Author: sushant-suse

changelog.d/158.feature.rst

@@ -0,0 +1 @@
+Added a rich-formatted Pydantic validation error reporter for the CLI, providing field descriptions, expected values, and documentation links.

src/docbuild/cli/cmd_cli.py

@@ -23,6 +23,7 @@
 from ..logging import setup_logging
 from ..models.config.app import AppConfig
 from ..models.config.env import EnvConfig
+from ..utils.errors import format_pydantic_error
 from ..utils.pidlock import LockAcquisitionError, PidFileLock
 from .cmd_build import build
 from .cmd_c14n import c14n
@@ -150,9 +151,16 @@ def cli(
         # Pydantic validation also handles placeholder replacement via @model_validator
         context.appconfig = AppConfig.from_dict(raw_appconfig)
     except (ValueError, ValidationError) as e:
-        log.error("Application configuration failed validation:")
-        log.error("Error in config file(s): %s", context.appconfigfiles)
-        log.error(e)
+        if isinstance(e, ValidationError):
+            # FIXED: Added fallback for config files to avoid subscripting None
+            config_file = str((context.appconfigfiles or ["unknown"])[0])
+            format_pydantic_error(
+                e, AppConfig, config_file, context.verbose
+            )
+        else:
+            log.error("Application configuration failed validation:")
+            log.error("Error in config file(s): %s", context.appconfigfiles)
+            log.error(e)
         ctx.exit(1)
 
     # 3. Setup logging using the validated config object
@@ -186,20 +194,27 @@ def cli(
         # The result is the validated Pydantic object, stored in context.envconfig
         context.envconfig = EnvConfig.from_dict(raw_envconfig)
     except (ValueError, ValidationError) as e:
-        log.error(
-            "Environment configuration failed validation: "
-            "Error in config file(s): %s %s",
-            context.envconfigfiles,
-            e,
-        )
+        if isinstance(e, ValidationError):
+            # FIXED: Added fallback for config files to avoid subscripting None
+            config_file = str((context.envconfigfiles or ["unknown"])[0])
+            format_pydantic_error(
+                e, EnvConfig, config_file, context.verbose
+            )
+        else:
+            log.error(
+                "Environment configuration failed validation: "
+                "Error in config file(s): %s %s",
+                context.envconfigfiles,
+                e,
+            )
         ctx.exit(1)
 
-    env_config_path = context.envconfigfiles[0] if context.envconfigfiles else None
+    env_config_path = (context.envconfigfiles or [None])[0]
 
     # --- CONCURRENCY CONTROL: Use explicit __enter__ and cleanup registration ---
     if env_config_path:
         # 1. Instantiate the lock object
-        ctx.obj.env_lock = PidFileLock(resource_path=env_config_path)
+        ctx.obj.env_lock = PidFileLock(resource_path=cast(Path, env_config_path))
 
         try:
             # 2. Acquire the lock by explicitly calling the __enter__ method.
@@ -217,8 +232,6 @@ def cli(
 
         # 3. Register the lock's __exit__ method to be called when the context
         # terminates.
-        # We use a lambda to supply the three mandatory positional arguments (None)
-        # expected by __exit__, satisfying the click.call_on_close requirement.
         ctx.call_on_close(lambda: ctx.obj.env_lock.__exit__(None, None, None))
 
 

src/docbuild/utils/errors.py

@@ -0,0 +1,103 @@
+"""Utilities for handling and formatting application errors."""
+
+from pydantic import BaseModel, ValidationError
+from rich.console import Console
+from rich.text import Text
+
+
+def format_pydantic_error(
+    error: ValidationError,
+    model_class: type[BaseModel],
+    config_file: str,
+    verbose: int = 0
+) -> None:
+    """Centralized formatter for Pydantic ValidationErrors using Rich.
+
+    :param error: The caught ValidationError object.
+    :param model_class: The Pydantic model class that failed validation.
+    :param config_file: The name/path of the config file being processed.
+    :param verbose: Verbosity level to control error detail.
+    """
+    console = Console(stderr=True)
+    errors = error.errors()
+    error_count = len(errors)
+
+    # Header
+    header = Text.assemble(
+        (f"{error_count} Validation error{'s' if error_count > 1 else ''} ", "bold red"),
+        ("in config file ", "white"),
+        (f"'{config_file}'", "bold cyan"),
+        (":", "white")
+    )
+    console.print(header)
+    console.print()
+
+    # Smart Truncation: Show only first 5 unless verbose
+    max_display = 5 if verbose < 2 else error_count
+    display_errors = errors[:max_display]
+
+    for i, err in enumerate(display_errors, 1):
+        # 1. Resolve Location and Field Info
+        loc_path = ".".join(str(v) for v in err["loc"])
+        err_type = err["type"]
+        msg = err["msg"]
+
+        # 2. Extract Field Metadata from the Model Class
+        field_info = None
+        current_model = model_class
+
+        for part in err["loc"]:
+            # Check if current_model is a Pydantic class and contains the field
+            if (isinstance(current_model, type) and
+                issubclass(current_model, BaseModel) and
+                part in current_model.model_fields):
+
+                field_info = current_model.model_fields[part]
+
+                # Move deeper into the tree if the annotation is another model
+                annotation = field_info.annotation
+                if (isinstance(annotation, type) and
+                    issubclass(annotation, BaseModel)):
+                    current_model = annotation
+                else:
+                    # We have reached a leaf node or a complex type (List, etc.)
+                    # Stop traversing but keep the field_info
+                    current_model = None
+            else:
+                field_info = None
+                break
+
+        # 3. Build the Display
+        error_panel = Text()
+        error_panel.append(f"({i}) In '", style="white")
+        error_panel.append(loc_path, style="bold yellow")
+        error_panel.append("':\n", style="white")
+
+        # Error detail
+        error_panel.append(f"    {msg}\n", style="red")
+
+        # Helpful context from Field metadata
+        if field_info:
+            if field_info.title:
+                error_panel.append("    Expected: ", style="dim")
+                error_panel.append(f"{field_info.title}\n", style="italic green")
+            if verbose > 0 and field_info.description:
+                error_panel.append("    Description: ", style="dim")
+                error_panel.append(f"{field_info.description}\n", style="dim italic")
+
+        # Documentation Link
+        error_panel.append("    See: ", style="dim")
+        error_panel.append(
+            f"https://opensuse.github.io/docbuild/latest/errors/{err_type}.html",
+            style="link underline blue"
+        )
+
+        console.print(error_panel)
+        console.print()
+
+    # Footer for Truncation
+    if error_count > max_display:
+        console.print(
+            f"[dim]... and {error_count - max_display} more errors. "
+            "Use '-vv' to see all errors.[/dim]\n"
+        )

tests/cli/test_cmd_cli.py

@@ -176,11 +176,11 @@ def test_cli_config_validation_failure(
     mock_config_models,
     is_app_config_failure,
 ):
-    """Test that the CLI handles Pydantic validation errors gracefully."""
+    """Test that the CLI handles Pydantic validation errors with the new formatter."""
     app_file = app_config_file
     app_file.write_text("bad data")
 
-    # 1. Mock the log.error function to check output
+    # 1. Mock the log.error function
     mock_log_error = Mock()
     monkeypatch.setattr(cli_mod.log, "error", mock_log_error)
 
@@ -196,19 +196,12 @@ def test_cli_config_validation_failure(
         ],
     )
 
-    # Define the simple error structure that the CLI error formatting relies on:
-    # MOCK_ERROR_DETAIL = {
-    #     'loc': ('server', 'port'),
-    #     'msg': 'value is not a valid integer (mocked)',
-    #     'input': 'not_an_int'
-    # }
-
     if is_app_config_failure:
         mock_config_models["app_from_dict"].side_effect = mock_validation_error
     else:
         mock_config_models["env_from_dict"].side_effect = mock_validation_error
 
-    # 3. Mock handle_config to return raw data successfully (no file read error)
+    # 3. Mock handle_config to return raw data successfully
     def resolver(user_path, *a, **kw):
         if user_path == app_file:
             return (app_file,), {"raw_app_data": "x"}, False
@@ -217,6 +210,7 @@ def resolver(user_path, *a, **kw):
     fake_handle_config(resolver)
 
     context = DocBuildContext()
+    # Click runner captures stdout/stderr. Our rich formatter prints to stderr.
     result = runner.invoke(
         cli,
         ["--app-config", str(app_file), "capture"],
@@ -227,23 +221,14 @@ def resolver(user_path, *a, **kw):
     # 4. Assertions
     assert result.exit_code == 1
 
-    if is_app_config_failure:
-        assert (
-            "Application configuration failed validation"
-            in mock_log_error.call_args_list[0][0][0]
-        )
-    else:
-        assert (
-            "Environment configuration failed validation"
-            in mock_log_error.call_args_list[0][0][0]
-        )
-
-    # --- REMOVE FRAGILE ASSERTIONS ON LOG CALL COUNT ---
-    # assert mock_log_error.call_count > 1
-    # assert mock_log_error.call_count >= 2
-    # assert any("Field: (" in call[0][0] for call in mock_log_error.call_args_list)
+    # For ValidationErrors, the CLI now uses format_pydantic_error, NOT log.error
+    assert mock_log_error.call_count == 0
 
-    assert mock_log_error.call_count >= 1
+    # Check that our new pretty-printer output exists in the captured terminal output
+    assert "Validation error" in result.output
+    assert "server.port" in result.output
+    # Check for the Pydantic error message
+    assert "Input should be a valid integer" in result.output
 
 
 def test_cli_verbose_and_debug(

tests/utils/test_errors.py

@@ -0,0 +1,74 @@
+"""Tests for the Pydantic error formatting utility."""
+
+from typing import Any
+
+from pydantic import BaseModel, Field, ValidationError
+
+from docbuild.utils.errors import format_pydantic_error
+
+
+class SubModel(BaseModel):
+    """A sub-model for testing nested validation."""
+
+    name: str = Field(title="Sub Name", description="A sub description")
+
+
+class MockModel(BaseModel):
+    """A mock model for testing top-level validation."""
+
+    age: int = Field(title="User Age")
+    sub: SubModel
+
+
+def test_format_pydantic_error_smoke(capsys):
+    """Smoke test to ensure the formatter runs without crashing."""
+    # Using Any to bypass static type checking for invalid data types
+    invalid_data: dict[str, Any] = {"age": "not-an-int", "sub": {"name": 123}}
+
+    try:
+        # Trigger a validation error
+        MockModel(**invalid_data)
+    except ValidationError as e:
+        # Run the formatter
+        format_pydantic_error(e, MockModel, "test.toml", verbose=1)
+
+    captured = capsys.readouterr()
+
+    # Check for key UI elements
+    assert "Validation error" in captured.err
+    assert "test.toml" in captured.err
+    assert "User Age" in captured.err
+    assert "A sub description" in captured.err
+    assert "https://opensuse.github.io/docbuild/latest/errors/" in captured.err
+
+
+def test_format_pydantic_error_truncation(capsys):
+    """Verify that truncation message appears when many errors exist."""
+
+    class MultiModel(BaseModel):
+        """A model with many fields to trigger truncation."""
+
+        a: int
+        b: int
+        c: int
+        d: int
+        e: int
+        f: int
+
+    # Cast to Any to bypass static type checking for the invalid input
+    invalid_input: dict[str, Any] = {
+        "a": "x",
+        "b": "x",
+        "c": "x",
+        "d": "x",
+        "e": "x",
+        "f": "x",
+    }
+
+    try:
+        MultiModel(**invalid_input)
+    except ValidationError as e:
+        format_pydantic_error(e, MultiModel, "test.toml", verbose=0)
+
+    captured = capsys.readouterr()
+    assert "... and 1 more errors" in captured.err