fix(cli) #175: handle TOML syntax errors gracefully

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

Author: sushant-suse

src/docbuild/cli/cmd_cli.py

@@ -10,6 +10,7 @@
 from pydantic import BaseModel, ValidationError
 import rich.console
 from rich.traceback import install as install_traceback
+import tomllib
 
 from ..__about__ import __version__
 from ..config.load import handle_config
@@ -24,7 +25,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.errors import format_pydantic_error, format_toml_error
 from ..utils.pidlock import LockAcquisitionError, PidFileLock
 from .cmd_build import build
 from .cmd_c14n import c14n
@@ -68,16 +69,16 @@ def handle_validation_error(
     :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"
+    # Determine which file we were working on
+    config_file = str((config_files or ["unknown"])[0])
 
-    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
-        )
+    if isinstance(e, tomllib.TOMLDecodeError):
+        format_toml_error(e, config_file, console=CONSOLE)
+    elif isinstance(e, ValidationError):
+        format_pydantic_error(e, model_class, config_file, verbose, console=CONSOLE)
     else:
-        log.error("%s configuration failed validation:", config_label)
+        config_label = "Application" if model_class == AppConfig else "Environment"
+        log.error("%s configuration failed:", config_label)
         log.error("Error in config file(s): %s", config_files)
         log.error(e)
     ctx.exit(1)
@@ -171,18 +172,26 @@ def cli(
     context.dry_run = dry_run
     context.debug = debug
 
+    # --- INITIALIZE TO AVOID UNBOUND ERRORS ---
+    raw_appconfig: dict[str, Any] = {}
+    raw_envconfig: dict[str, Any] = {}
+
     # --- PHASE 1: Load and Validate Application Config ---
-    (
-        context.appconfigfiles,
-        raw_appconfig,
-        context.appconfig_from_defaults,
-    ) = handle_config(
-        app_config,
-        CONFIG_PATHS,
-        APP_CONFIG_BASENAMES + PROJECT_LEVEL_APP_CONFIG_FILENAMES,
-        None,
-        DEFAULT_APP_CONFIG,
-    )
+    try:
+        # We cast the return of handle_config to the expected tuple type
+        result = handle_config(
+            app_config,
+            CONFIG_PATHS,
+            APP_CONFIG_BASENAMES + PROJECT_LEVEL_APP_CONFIG_FILENAMES,
+            None,
+            DEFAULT_APP_CONFIG,
+        )
+        context.appconfigfiles, raw_appconfig, context.appconfig_from_defaults = cast(
+            tuple[tuple[Path, ...] | None, dict[str, Any], bool], result
+        )
+    except tomllib.TOMLDecodeError as e:
+        files = (app_config,) if app_config else None
+        handle_validation_error(e, AppConfig, files, verbose, ctx)
 
     raw_appconfig = cast(dict[str, Any], raw_appconfig)
 
@@ -200,18 +209,21 @@ def cli(
     )
     setup_logging(cliverbosity=verbose, user_config={"logging": logging_config})
 
-    # --- PHASE 2: Load Environment Config, Validate, and Acquire Lock ---
-    (
-        context.envconfigfiles,
-        raw_envconfig,
-        context.envconfig_from_defaults,
-    ) = handle_config(
-        env_config,
-        (PROJECT_DIR,),
-        None,
-        DEFAULT_ENV_CONFIG_FILENAME,
-        DEFAULT_ENV_CONFIG,
-    )
+    # --- PHASE 2: Load Environment Config ---
+    try:
+        result = handle_config(
+            env_config,
+            (PROJECT_DIR,),
+            None,
+            DEFAULT_ENV_CONFIG_FILENAME,
+            DEFAULT_ENV_CONFIG,
+        )
+        context.envconfigfiles, raw_envconfig, context.envconfig_from_defaults = cast(
+            tuple[tuple[Path, ...] | None, dict[str, Any], bool], result
+        )
+    except tomllib.TOMLDecodeError as e:
+        files = (env_config,) if env_config else None
+        handle_validation_error(e, EnvConfig, files, verbose, ctx)
 
     raw_envconfig = cast(dict[str, Any], raw_envconfig)
 

src/docbuild/utils/errors.py

@@ -4,6 +4,7 @@
 from pydantic import BaseModel, ValidationError
 from rich.console import Console
 from rich.text import Text
+import tomllib
 
 from ..constants import DEFAULT_ERROR_LIMIT
 
@@ -112,3 +113,31 @@ def format_pydantic_error(
             f"[dim]... and {error_count - max_display} more errors. "
             "Use '-vv' to see all errors.[/dim]\n"
         )
+
+def format_toml_error(
+    error: tomllib.TOMLDecodeError,
+    config_file: str,
+    console: Console | None = None,
+) -> None:
+    """Format TOML syntax errors using Rich.
+
+    :param error: The caught TOMLDecodeError object.
+    :param config_file: The name/path of the config file with the syntax error.
+    :param console: Optional Rich console object.
+    """
+    con = console or Console(stderr=True)
+
+    header = Text.assemble(
+        ("Syntax error ", "bold red"),
+        ("in config file ", "white"),
+        (f"'{config_file}'", "bold cyan"),
+        (":", "white")
+    )
+    con.print(header)
+    
+    # tomllib error messages include the line and column info naturally
+    con.print(f"    [red]{error}[/red]")
+    con.print()
+    con.print("    [dim]Please verify that the file is a valid TOML file.[/dim]")
+    con.print("    [dim]Note: Booleans must be lowercase (true/false) in TOML.[/dim]")
+    

tests/cli/test_cmd_cli.py

@@ -6,6 +6,7 @@
 import click
 from pydantic import ValidationError
 import pytest
+import tomllib
 
 import docbuild.cli.cmd_cli as cli_mod
 from docbuild.cli.context import DocBuildContext
@@ -267,3 +268,32 @@ def resolver(user_path, *args, **kwargs):
     assert result.exit_code == 0
     assert context.verbose == 3
     assert context.debug is True
+
+
+@pytest.mark.parametrize("is_app_config_failure", [True, False])
+def test_cli_toml_syntax_error(
+    runner,
+    fake_handle_config,
+    mock_config_models,
+    is_app_config_failure,
+):
+    """Verify that the CLI handles TOML syntax errors gracefully (Issue #175)."""
+    
+    # Define a resolver that raises TOMLDecodeError
+    def resolver_with_syntax_error(user_path, *args, **kwargs):
+        # We simulate the exact error raised by tomllib
+        raise tomllib.TOMLDecodeError("Invalid value", "test.toml", 0)
+
+    fake_handle_config(resolver_with_syntax_error)
+
+    # Invoke the CLI. Whether it's app or env config, the handle_config 
+    # call is now wrapped in a try/except in cmd_cli.py
+    result = runner.invoke(cli, ["capture"])
+
+    assert result.exit_code == 1
+    assert "Syntax error in config file" in result.output
+    assert "Invalid value" in result.output
+    # Verify our specific 'Note' from the formatter appears
+    assert "Booleans must be lowercase" in result.output
+    # Crucially, ensure no raw Python traceback is leaked to the user
+    assert "Traceback (most recent call last)" not in result.output

tests/utils/test_errors.py

@@ -1,6 +1,7 @@
 """Tests for the Pydantic error formatting utility."""
 
 from typing import Any
+import tomllib
 
 from pydantic import BaseModel, Field, IPvAnyAddress, ValidationError, create_model
 from rich.console import Console
@@ -94,3 +95,23 @@ class UnionModel(BaseModel):
     assert "In 'host':" in captured.err
     # Verify no bracketed pydantic internals leaked in the path part
     assert "[" not in captured.err.split("In '")[1].split("':")[0]
+
+
+def test_format_toml_error_smoke(capsys):
+    """Verify that the TOML syntax error formatter prints correctly."""
+    from docbuild.utils.errors import format_toml_error
+    
+    # 1. Manually trigger a TOML syntax error
+    bad_toml_content = "enable_mail = True"  # Invalid: Capital T
+    try:
+        tomllib.loads(bad_toml_content)
+    except tomllib.TOMLDecodeError as e:
+        # 2. Call our new formatter
+        format_toml_error(e, "env.devel.toml")
+
+    captured = capsys.readouterr()
+
+    # 3. Assertions to verify the "Rich" output content
+    assert "Syntax error in config file 'env.devel.toml'" in captured.err
+    assert "Invalid value" in captured.err
+    assert "Booleans must be lowercase" in captured.err