feat: Implement pretty-printing for Pydantic validation errors (#182)

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

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

* refactor #158: address review comments on pydantic error formatting

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

* testing #182: Increase cmd_cli.py coverage to 98% by adding edge-case tests.

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

---------

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.

docs/source/user/config.rst

@@ -48,7 +48,7 @@ to the user running the script.
 Validating the Configuration
 -----------------------------
 
-Before docbuild executes any commands, it validates the provided configuration
+Before ``docbuild`` executes any commands, it validates the provided configuration
 file against a predefined :term:`Pydantic` model.
 
 The validation checks for different aspects of the configuration, such as:
@@ -59,11 +59,43 @@ The validation checks for different aspects of the configuration, such as:
   required.
 * Correct use of placeholders.
 
+Detailed Validation Feedback
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-..
-   TODO: Add a link to the TOML env config reference, add an example of
-   a validation error message, and explain how to fix common issues.
-   a validation error message, and explain how to fix common issues.
+If the configuration is invalid, the application provides a structured, 
+color-coded error report to help you identify and fix the issues. Each error 
+includes:
+
+* **Location**: The exact path in the TOML file (e.g., ``server.host``).
+* **Field Info**: A human-readable title and description of the field's purpose.
+* **Error Detail**: A specific message explaining why the value failed validation.
+* **Documentation Link**: A direct URL to a reference page with more details 
+  on how to resolve that specific error type.
+
+Example error output:
+
+.. code-block:: text
+
+    1 Validation error in config file 'env.devel.toml':
+
+    (1) In 'server.enable_mail':
+        Input should be a valid boolean, unable to interpret input
+        Expected: Enable Email
+        Description: Flag to enable email sending features.
+        See: https://opensuse.github.io/docbuild/latest/errors/bool_parsing.html
+
+Fixing Common Issues
+~~~~~~~~~~~~~~~~~~~~
+
+If you encounter validation errors, check the following common causes:
+
+* **Missing Keys**: Ensure all mandatory fields (like ``paths.root_config_dir``) are defined.
+* **Typing Errors**: Ensure booleans (``true``/``false``) and integers are not enclosed 
+  in quotes.
+* **Permission Issues**: If a path error occurs, verify that the user running 
+  ``docbuild`` has the necessary read/write permissions for the specified directory.
+* **Circular Placeholders**: Ensure that your static placeholders do not point 
+  to each other in a loop (e.g., Key A referencing Key B, which references Key A).
 
 
 .. _config-placeholders:
@@ -120,7 +152,6 @@ Static placeholders follow a specific syntax:
      [paths]
      base_cache_dir = "/tmp/cache"
      base_server_cache_dir = "{base_cache_dir}/{server.name}"
-     base_server_cache_dir = "{base_cache_dir}/{server.name}"
 
   In this example, the key ``base_server_cache_dir`` uses the
   static placeholder ``{server.name}`` to reference the value of the
@@ -161,4 +192,4 @@ between configurations without needing to remember the exact command syntax.
 
    alias docbuild-prod='docbuild --env-config env.production.toml'
    alias docbuild-test='docbuild --env-config env.testing.toml'
-   alias docbuild-dev='docbuild --env-config env.devel.toml'
+   alias docbuild-dev='docbuild --env-config env.devel.toml'

src/docbuild/cli/cmd_cli.py

@@ -1,12 +1,13 @@
 """Main CLI tool for document operations."""
 
+from collections.abc import Sequence
 import logging
 from pathlib import Path
 import sys
 from typing import Any, cast
 
 import click
-from pydantic import ValidationError
+from pydantic import BaseModel, ValidationError
 import rich.console
 from rich.traceback import install as install_traceback
 
@@ -23,6 +24,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
@@ -46,6 +48,41 @@ def _setup_console() -> None:
     install_traceback(console=CONSOLE, show_locals=True)
 
 
+def handle_validation_error(
+    e: Exception,
+    model_class: type[BaseModel],
+    config_files: Sequence[Path] | None,
+    verbose: int,
+    ctx: click.Context,
+) -> None:
+    """Format validation errors and exit the CLI.
+
+    Outsourced logic to avoid code duplication between App and Env config phases.
+    Using Sequence[Path] ensures compatibility with both lists and tuples.
+    :param e: The exception that was raised during validation.
+    :param model_class: The Pydantic model class that was being validated
+      (AppConfig or EnvConfig).
+    :param config_files: The list of config files that were attempted to be loaded, used for error context.
+    :param verbose: The verbosity level from the CLI options, which can be
+      used to control the level of detail in the error output.
+    :param ctx: The Click context, used to exit the CLI with an appropriate
+      status code after handling the error.
+    """
+    config_label = "Application" if model_class == AppConfig else "Environment"
+
+    if isinstance(e, ValidationError):
+        # Safely extract the first config file name for the error header
+        config_file = str((config_files or ["unknown"])[0])
+        format_pydantic_error(
+            e, model_class, config_file, verbose, console=CONSOLE
+        )
+    else:
+        log.error("%s configuration failed validation:", config_label)
+        log.error("Error in config file(s): %s", config_files)
+        log.error(e)
+    ctx.exit(1)
+
+
 @click.group(
     name=APP_NAME,
     context_settings={"show_default": True, "help_option_names": ["-h", "--help"]},
@@ -113,26 +150,22 @@ def cli(
     :param kwargs: Additional keyword arguments.
     """
     if ctx.invoked_subcommand is None:
-        # If no subcommand is invoked, show the help message
         click.echo(10 * "-")
         click.echo(ctx.get_help())
         ctx.exit(0)
 
     if ctx.obj is None:
         ctx.ensure_object(DocBuildContext)
 
-    # Build the context object
     context = ctx.obj
     context.verbose = verbose
     context.dry_run = dry_run
     context.debug = debug
 
-    # --- PHASE 1: Load and Validate Application Config (and setup logging) ---
-    #
-    # 1. Load the raw application config dictionary
+    # --- PHASE 1: Load and Validate Application Config ---
     (
         context.appconfigfiles,
-        raw_appconfig,  # Store config as raw dictionary
+        raw_appconfig,
         context.appconfig_from_defaults,
     ) = handle_config(
         app_config,
@@ -142,32 +175,23 @@ def cli(
         DEFAULT_APP_CONFIG,
     )
 
-    # Explicitly cast the raw_appconfig type to silence Pylance
     raw_appconfig = cast(dict[str, Any], raw_appconfig)
 
-    # 2. Validate the raw config dictionary using Pydantic
     try:
-        # 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)
-        ctx.exit(1)
+        handle_validation_error(e, AppConfig, context.appconfigfiles, verbose, ctx)
 
     # 3. Setup logging using the validated config object
-    # Use model_dump(by_alias=True) to ensure the 'class' alias is used.
     logging_config = context.appconfig.logging.model_dump(
         by_alias=True, exclude_none=True
     )
     setup_logging(cliverbosity=verbose, user_config={"logging": logging_config})
 
     # --- PHASE 2: Load Environment Config, Validate, and Acquire Lock ---
-    #
-    # 1. Load raw Environment Config
     (
         context.envconfigfiles,
-        raw_envconfig,  # Renaming context.envconfig to raw_envconfig locally
+        raw_envconfig,
         context.envconfig_from_defaults,
     ) = handle_config(
         env_config,
@@ -177,52 +201,32 @@ def cli(
         DEFAULT_ENV_CONFIG,
     )
 
-    # Explicitly cast the raw_envconfig type to silence Pylance
     raw_envconfig = cast(dict[str, Any], raw_envconfig)
 
-    # 2. VALIDATE the raw environment config dictionary using Pydantic
     try:
-        # Pydantic validation handles placeholder replacement via @model_validator
-        # 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,
-        )
-        ctx.exit(1)
+        handle_validation_error(e, EnvConfig, context.envconfigfiles, verbose, ctx)
 
-    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 ---
+    # --- CONCURRENCY CONTROL ---
     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.
             ctx.obj.env_lock.__enter__()
             log.info("Acquired lock for environment config: %r", env_config_path.name)
-
         except LockAcquisitionError as e:
-            # Handles lock contention
             log.error(str(e))
             ctx.exit(1)
         except Exception as e:
-            # Handles critical errors
             log.error("Failed to set up environment lock: %s", e)
             ctx.exit(1)
 
-        # 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))
 
 
-# Add subcommand
+# Add subcommands
 cli.add_command(build)
 cli.add_command(c14n)
 cli.add_command(config)

src/docbuild/constants.py

@@ -164,3 +164,8 @@
 
 XMLDATADIR = Path(__file__).parent / "config" / "xml" / "data"
 """Directory where additional files (RNC, XSLT) for XML processing are stored."""
+
+# --- UI and Error Reporting Constants ---
+
+DEFAULT_ERROR_LIMIT = 5
+"""The maximum number of validation errors to display before truncating the output."""

src/docbuild/utils/errors.py

@@ -0,0 +1,114 @@
+"""Utilities for handling and formatting application errors."""
+
+
+from pydantic import BaseModel, ValidationError
+from rich.console import Console
+from rich.text import Text
+
+from ..constants import DEFAULT_ERROR_LIMIT
+
+
+def format_pydantic_error(
+    error: ValidationError,
+    model_class: type[BaseModel],
+    config_file: str,
+    verbose: int = 0,
+    console: Console | None = None,
+) -> 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.
+    :param console: Optional Rich console object. If None, creates a stderr console.
+    """
+    # Use provided console or fall back to default (Dependency Injection)
+    con = console or 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")
+    )
+    con.print(header)
+    con.print()
+
+    # Smart Truncation: Use the constant from constants.py
+    max_display = DEFAULT_ERROR_LIMIT 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
+        # Filter out internal Pydantic tags (strings with '[' or '-')
+        # to keep the path clean for end users.
+        clean_loc = [
+            str(v) for v in err["loc"]
+            if not (isinstance(v, str) and ("[" in v or "-" in v))
+            and not isinstance(v, int)
+        ]
+        loc_path = ".".join(clean_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"]:
+            if (isinstance(current_model, type) and
+                issubclass(current_model, BaseModel) and
+                part in current_model.model_fields):
+
+                field_info = current_model.model_fields[part]
+
+                annotation = field_info.annotation
+                if (isinstance(annotation, type) and
+                    issubclass(annotation, BaseModel)):
+                    current_model = annotation
+                else:
+                    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"
+        )
+
+        con.print(error_panel)
+        con.print()
+
+    # Footer for Truncation
+    if error_count > max_display:
+        con.print(
+            f"[dim]... and {error_count - max_display} more errors. "
+            "Use '-vv' to see all errors.[/dim]\n"
+        )