refactor: enhance Config and command base with comprehensive scenario-aware logging (#4488)

## Summary

Comprehensive enhancement of Config class and command base logging with
scenario-aware context, building on the foundation from merged PRs #4483
and #4484.

## User-Facing Changes

**Enhanced logging context across all Config and command operations:**

### Before: Generic logging without context
```
DEBUG    Validating schema molecule.yml
WARNING  Driver 'default' is currently in use but config defines 'podman'
INFO     Performing prerun with role_name_check=0...
```

### After: Complete scenario and step context
```
DEBUG    smoke ➜ validate: Validating schema /path/to/molecule.yml
WARNING  smoke ➜ config: Driver 'default' is currently in use but config defines 'podman'  
INFO     smoke ➜ prerun: Performing prerun with role_name_check=0...
INFO     smoke ➜ discovery: scenario test matrix: syntax
```

## Technical Implementation

**🏗️ Config Class Enhancements:**
- Add reusable `@property _log` method to Config class for dynamic
scenario context
- Convert all Config logging calls to use scenario-aware loggers
- Enhanced validation logging with hardcoded scenario context during
bootstrap
- Improved galaxy file and driver validation warnings with full context

**🧹 Command Base Logger Consolidation:**
- Replace 5 scattered `get_scenario_logger()` calls with single global
`_log()` function
- Unified logging pattern: `_log(scenario_name, step, message,
level='info')`
- Pre-formatted messages eliminate complex placeholder handling
- Cleaner, more maintainable logger creation across all command
operations

**✅ Enhanced Test Coverage:**
- Updated `test_validate` to use `caplog` instead of mock patching
- Validates scenario logger extras: `molecule_scenario` and
`molecule_step`
- Robust verification of message content and context attributes

## Changes Included

**Config Class (4 commits):**
1. `feat: add step context to command base logger calls`
2. `feat: add scenario context to config file modification warning`  
3. `refactor: add reusable _log property to Config class`
4. `refactor: convert all Config logging to scenario-aware logging`

**Command Base Improvements (2 commits):**
5. `refactor: replace scattered logger initializations with global _log
function`
6. `fix: update test_validate to use caplog and check scenario logger
extras`

**Dependencies (Included):**
- Builds on: All cleanup commits from PR #4487 (unused logger removal)

## Dependencies

- **Depends on**: PR #4487 (unused logger cleanup)
- **Builds on**: PR #4484 (merged - dynamic properties for
dependency/provisioner/verifier)
- **Foundation**: PR #4483 (merged - enhanced logging adapter with
dual-output)

## Testing

- ✅ **Comprehensive**: All config tests passing (45/45)
- ✅ **Enhanced coverage**: Validates scenario logger extras in test
suite
- ✅ **Functional verification**: `molecule syntax` confirms enhanced
logging works
- ✅ **Backwards compatible**: No breaking changes to existing
functionality

## Impact

- **Complete Config context**: All Config operations now include
scenario and step information
- **Unified command logging**: Consistent pattern across all command
base operations
- **Better maintainability**: Single global `_log` function replaces
scattered initializations
- **Enhanced debugging**: Full context for configuration validation and
driver operations

---------

Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>

Author: cidrblock

src/molecule/command/base.py

@@ -50,6 +50,19 @@
     from molecule.types import CommandArgs, MoleculeArgs, ScenariosResults
 
 
+def _log(scenario_name: str, step: str, message: str, level: str = "info") -> None:
+    """Create scenario logger on-demand and log message.
+
+    Args:
+        scenario_name: Name of the scenario for context.
+        step: Step name for context (e.g., 'discovery', 'prerun', 'reset').
+        message: Log message (pre-formatted, no placeholders).
+        level: Log level ('info', 'warning', 'error', 'debug').
+    """
+    scenario_log = logger.get_scenario_logger(__name__, scenario_name, step)
+    getattr(scenario_log, level)(message)
+
+
 class Base(abc.ABC):
     """An abstract base class used to define the command interface."""
 
@@ -170,10 +183,11 @@ def _generate_scenarios(
     if scenario_names is not None:
         for scenario_name in scenario_names:
             if scenario_name != "*" and scenarios:
-                scenario_log = logger.get_scenario_logger(__name__, scenario_name)
-                scenario_log.info(
-                    "scenario test matrix: %s",
-                    ", ".join(scenarios.sequence(scenario_name)),
+                # Use generic "discovery" step since this is scenario discovery phase
+                _log(
+                    scenario_name,
+                    "discovery",
+                    f"scenario test matrix: {', '.join(scenarios.sequence(scenario_name))}",
                 )
 
     return scenarios
@@ -202,16 +216,22 @@ def _run_scenarios(
     for scenario in scenarios.all:
         if scenario.config.config["prerun"]:
             role_name_check = scenario.config.config["role_name_check"]
-            scenario_log = logger.get_scenario_logger(__name__, scenario.config.scenario.name)
-            scenario_log.info("Performing prerun with role_name_check=%s...", role_name_check)
+            _log(
+                scenario.config.scenario.name,
+                "prerun",
+                f"Performing prerun with role_name_check={role_name_check}...",
+            )
             scenario.config.runtime.prepare_environment(
                 install_local=True,
                 role_name_check=role_name_check,
             )
 
         if command_args.get("subcommand") == "reset":
-            scenario_log = logger.get_scenario_logger(__name__, scenario.config.scenario.name)
-            scenario_log.info("Removing %s", scenario.ephemeral_directory)
+            _log(
+                scenario.config.scenario.name,
+                "reset",
+                f"Removing {scenario.ephemeral_directory}",
+            )
             shutil.rmtree(scenario.ephemeral_directory)
             return
         try:
@@ -225,8 +245,13 @@ def _run_scenarios(
                     f"An error occurred during the {scenario.config.subcommand} sequence action: "
                     f"'{scenario.config.action}'. Cleaning up."
                 )
-                scenario_log = logger.get_scenario_logger(__name__, scenario.config.scenario.name)
-                scenario_log.warning(msg)
+                step_name = getattr(scenario.config, "action", "cleanup")
+                _log(
+                    scenario.config.scenario.name,
+                    step_name,
+                    msg,
+                    level="warning",
+                )
                 execute_subcommand(scenario.config, "cleanup")
                 destroy_results = execute_subcommand_default(default_config, "destroy")
                 if destroy_results is not None:
@@ -272,11 +297,11 @@ def execute_subcommand_default(
         # clear results for later reuse
         default.results = []
         return results
-    # Use the default scenario name for this warning since it's about the default scenario
-    scenario_log = logger.get_scenario_logger(__name__, default.name)
-    scenario_log.warning(
-        "%s not found in default scenario, falling back to current scenario",
+    _log(
+        default.name,
         subcommand,
+        f"{subcommand} not found in default scenario, falling back to current scenario",
+        level="warning",
     )
     return None
 

src/molecule/config.py

@@ -22,7 +22,6 @@
 from __future__ import annotations
 
 import copy
-import logging
 import os
 import warnings
 
@@ -32,7 +31,7 @@
 
 from ansible_compat.ports import cache, cached_property
 
-from molecule import api, interpolation, platforms, scenario, state, util
+from molecule import api, interpolation, logger, platforms, scenario, state, util
 from molecule.app import get_app
 from molecule.data import __file__ as data_module
 from molecule.dependency import ansible_galaxy, shell
@@ -55,7 +54,6 @@
     from molecule.verifier.base import Verifier
 
 
-LOG = logging.getLogger(__name__)
 MOLECULE_PARALLEL: bool = boolean(os.environ.get("MOLECULE_PARALLEL", ""))
 MOLECULE_DEBUG: bool = boolean(os.environ.get("MOLECULE_DEBUG", "False"))
 MOLECULE_VERBOSITY: int = int(os.environ.get("MOLECULE_VERBOSITY", "0"))
@@ -287,7 +285,7 @@ def collection(self) -> CollectionData | None:
 
         important_keys = {"name", "namespace"}
         if missing_keys := important_keys.difference(galaxy_data.keys()):
-            LOG.warning(
+            self._log.warning(
                 "The detected galaxy.yml file (%s) is invalid, missing mandatory field %s",
                 galaxy_file,
                 util.oxford_comma(missing_keys),
@@ -401,6 +399,15 @@ def scenario(self) -> scenario.Scenario:
         """
         return scenario.Scenario(self)
 
+    @property
+    def _log(self) -> logger.ScenarioLoggerAdapter:
+        """Get a scenario logger with config step context.
+
+        Returns:
+            A scenario logger adapter with current scenario and step context.
+        """
+        return logger.get_scenario_logger(__name__, self.scenario.name, "config")
+
     @cached_property
     def state(self) -> State:
         """Molecule state object.
@@ -416,7 +423,7 @@ def state(self) -> State:
             if my_state.molecule_yml_date_modified is None:
                 my_state.change_state("molecule_yml_date_modified", modTime)
             elif my_state.molecule_yml_date_modified != modTime:
-                LOG.warning(
+                self._log.warning(
                     "The scenario config file ('%s') has been modified since the scenario was created. "
                     "If recent changes are important, reset the scenario with 'molecule destroy' to clean up created items or "
                     "'molecule reset' to clear current configuration.",
@@ -478,7 +485,7 @@ def _get_driver_name(self) -> str:
                 f"has changed and now defines '{driver_from_scenario}'. "
                 "To change drivers, run 'molecule destroy' for converged scenarios or 'molecule reset' otherwise."
             )
-            LOG.warning(msg)
+            self._log.warning(msg)
 
         return driver_name
 
@@ -670,8 +677,12 @@ def _validate(self) -> None:
         Raises:
             MoleculeError: when config file fails to validate.
         """
+        # Use scenario logger with hardcoded values since scenario property isn't available yet
+        scenario_name = self.config["scenario"]["name"]
+        validation_log = logger.get_scenario_logger(__name__, scenario_name, "validate")
+
         msg = f"Validating schema {self.molecule_file}."
-        LOG.debug(msg)
+        validation_log.debug(msg)
 
         errors = schema_v3.validate(self.config)
         if errors:

tests/unit/test_config.py

@@ -20,6 +20,7 @@
 from __future__ import annotations
 
 import copy
+import logging
 import os
 
 from pathlib import Path
@@ -391,14 +392,26 @@ def test_get_defaults(  # noqa: D103
 def test_validate(  # noqa: D103
     mocker: MockerFixture,
     config_instance: config.Config,
-    patched_logger_debug: Mock,
+    caplog: pytest.LogCaptureFixture,
 ) -> None:
     m = mocker.patch("molecule.model.schema_v3.validate")
     m.return_value = None
 
-    config_instance._validate()
+    with caplog.at_level(logging.DEBUG):
+        config_instance._validate()
+
+    # Check that debug message was logged
+    assert len(caplog.records) == 1
+
+    # Check the log message content
+    record = caplog.records[0]
+    assert "Validating schema" in record.message
+    assert config_instance.molecule_file in record.message
 
-    assert patched_logger_debug.call_count == 1
+    # Check that scenario logger extras are present
+    assert hasattr(record, "molecule_scenario")
+    assert hasattr(record, "molecule_step")
+    assert record.molecule_step == "validate"
 
     m.assert_called_with(config_instance.config)