fix: provide clear messaging about config file loading

Fix bug where tox is silently ignoring loading pyproject.toml files
that failed be loaded by tomllint and falling back to other config.

- if pyproject.toml does not have one of the two expected sections
  it will be logged, so it would be visible with `-v`
- make pyproject.toml failure to load a fatal error with clear
  information about cause
- keeps ignoring missing pyproject.toml files as expected

With these, users of tox will not be surprised when they break the
config file by mistake, like adding a duplicate section.

Author: ssbarnea

docs/changelog/3567.bugfix.rst

@@ -0,0 +1,2 @@
+Makes the error message more clear when pyproject.toml file cannot be loaded
+or is missing expected keys.

src/tox/config/source/discover.py

@@ -5,6 +5,7 @@
 from pathlib import Path
 from typing import TYPE_CHECKING
 
+from tox.config.types import MissingRequiredConfigKeyError
 from tox.report import HandledError
 
 from .legacy_toml import LegacyToml
@@ -59,21 +60,32 @@ def _locate_source() -> Source | None:
     for base in chain([folder], folder.parents):
         for src_type in SOURCE_TYPES:
             candidate: Path = base / src_type.FILENAME
-            try:
-                return src_type(candidate)
-            except ValueError:
-                pass
+            if candidate.exists():
+                try:
+                    return src_type(candidate)
+                except MissingRequiredConfigKeyError as e:
+                    msg = f"{src_type.__name__} skipped loading {candidate.resolve()} due to {e}"
+                    logging.info(msg)
+                except ValueError as e:
+                    msg = f"{src_type.__name__} failed loading {candidate.resolve()} due to {e}"
+                    raise HandledError(msg) from e
     return None
 
 
 def _load_exact_source(config_file: Path) -> Source:
     # if the filename matches to the letter some config file name do not fallback to other source types
+    if not config_file.exists():
+        msg = f"config file {config_file} does not exist"
+        raise HandledError(msg)
     exact_match = [s for s in SOURCE_TYPES if config_file.name == s.FILENAME]  # pragma: no cover
     for src_type in exact_match or SOURCE_TYPES:  # pragma: no branch
         try:
             return src_type(config_file)
-        except ValueError:  # noqa: PERF203
+        except MissingRequiredConfigKeyError:  # noqa: PERF203
             pass
+        except ValueError as e:
+            msg = f"{src_type.__name__} failed loading {config_file.resolve()} due to {e}"
+            raise HandledError(msg) from e
     msg = f"could not recognize config file {config_file}"
     raise HandledError(msg)
 
@@ -88,7 +100,7 @@ def _create_default_source(root_dir: Path | None) -> Source:
     else:  # if not set use where we find pyproject.toml in the tree or cwd
         empty = root_dir
     names = " or ".join({i.FILENAME: None for i in SOURCE_TYPES})
-    logging.warning("No %s found, assuming empty tox.ini at %s", names, empty)
+    logging.warning("No loadable %s found, assuming empty tox.ini at %s", names, empty)
     return ToxIni(empty / "tox.ini", content="")
 
 

src/tox/config/source/legacy_toml.py

@@ -2,6 +2,8 @@
 
 import sys
 
+from tox.config.types import MissingRequiredConfigKeyError
+
 if sys.version_info >= (3, 11):  # pragma: no cover (py311+)
     import tomllib
 else:  # pragma: no cover (py311+)
@@ -27,7 +29,8 @@ def __init__(self, path: Path) -> None:
         try:
             content = toml_content["tool"]["tox"]["legacy_tox_ini"]
         except KeyError as exc:
-            raise ValueError(path) from exc
+            msg = f"`tool.tox.legacy_tox_ini` missing from {path}"
+            raise MissingRequiredConfigKeyError(msg) from exc
         super().__init__(path, content=content)
 
 

src/tox/config/types.py

@@ -10,6 +10,13 @@ class CircularChainError(ValueError):
     """circular chain in config"""
 
 
+class MissingRequiredConfigKeyError(ValueError):
+    """missing required config key
+
+    Used by the two toml loaders in order to identify if config keys are present.
+    """
+
+
 class Command:  # noqa: PLW1641
     """A command to execute."""