fix(logging): suppress verbose log pollution in build plugins and remove handlers when disabled

This pull request resolves verbose logging output and terminal pollution when building and installing packages utilizing the `git-versioned` backend plugins.

### Key Changes
- **Silence Build Plugins:** Enforced `clear_loggers=True` and adjusted the default logger settings to `level="WARNING"` (down from `INFO`) within the Hatchling, Setuptools, and Maturin plugins.
- **Dangling Handlers Disposal:** Updated `configure_logger` to safely call `logger.remove()` on the active handler and reset the internal handler ID to `None` if logging is disabled.
- **Log Demotion on Fallbacks:** Demoted failed tag and archive resolution logs from `warning` to `info` within version source resolution. This avoids false warning messages when the tool falls back to other resolved sources.
- **Enhanced Test Suites:** Added target regression tests to cover cleanup of logging handlers and adapted E2E tests to verify silence during build operations under normal circumstances, alongside manual log injection flags.

## Type of Change

- [x] Bug fix (non-breaking change which fixes an issue)
- [ ] New feature (non-breaking change which adds functionality)
- [ ] Breaking change (fix or feature that would cause existing functionality to not work as expected)
- [ ] Documentation update (changes to `README.md`, `SUPPORT.md`, docstrings, etc.)
- [x] Maintenance/Refactoring (non-breaking change that improves code structure or quality)

## Test Plan

All changes have been validated by running the local Python test suites through Hatch.

### Automated Test Execution
Run the unit, integration, and E2E regression tests using Hatch:

```bash
# Execute functional test suite (unit + integration tests)
.venv/bin/hatch run python:tests-func

# Execute E2E plugin and CLI integration test suite
.venv/bin/hatch run python:tests-e2e
```

### Results
- `tests-func` successfully executed **836 tests** (all PASSED).
- `tests-e2e` successfully executed **211 tests** (all PASSED).

## Related Issues

- Fixes #None

## Screenshots / Visuals (if applicable)

N/A

## Use of AI

- [ ] Includes AI-assisted code completion
- [x] Includes code generated by an AI application
- [x] Includes AI-generated tests

## Checklist

> [!IMPORTANT]
> Please review and complete this checklist before submitting your PR. This helps our maintainers process your contribution faster and ensures it meets the quality standards.

- [x] "I certify that all code in this PR is my own, except as noted below."
- [x] I have read the [CONTRIBUTING.md](../CONTRIBUTING.md) guide.
- [x] My code follows the established style guidelines.
- [x] I have performed a self-review of my own code.
- [x] I have commented my code, particularly in hard-to-understand areas.
- [x] I have made corresponding changes to the documentation.
- [x] My changes generate no new warnings or errors.
- [x] I have added tests that prove my fix is effective or that my feature works.
- [x] New and existing unit tests pass locally with my changes.

Author: markurtz

src/gitversioned/__init__.py

@@ -56,6 +56,6 @@
     "resolve_version_output_to_stream",
 ]
 
-__version__ = "0.2.1.dev25+02d93d4"
+__version__ = "0.3.1.dev25+652050a"
 
 configure_logger()

src/gitversioned/logging.py

@@ -186,6 +186,10 @@ def configure_logger(  # noqa: C901, PLR0912, PLR0915
     if not settings.enabled:
         logger.disable("gitversioned")
         intercept_standard_logging(False)
+        if isinstance(_state["handler_id"], int):
+            with contextlib.suppress(ValueError):
+                logger.remove(_state["handler_id"])
+            _state["handler_id"] = None
         return
 
     logger.enable("gitversioned")

src/gitversioned/plugins/hatchling_plugin.py

@@ -90,7 +90,8 @@ def get_version_data(self) -> dict[str, str]:
         """
         configure_logger(
             enabled=True,
-            level="INFO",
+            clear_loggers=True,
+            level="WARNING",
             otel_formatting="disable",
             enqueue=False,
             format="<cyan>[gitversioned:hatch]</cyan> <level>{message}</level>\n",
@@ -277,7 +278,8 @@ def initialize(self, version: str, build_data: dict[str, Any]) -> None:  # noqa:
         """
         configure_logger(
             enabled=True,
-            level="INFO",
+            clear_loggers=True,
+            level="WARNING",
             otel_formatting="disable",
             enqueue=False,
             format="<cyan>[gitversioned:hatch-build]</cyan> <level>{message}</level>\n",

src/gitversioned/plugins/maturin_plugin.py

@@ -257,7 +257,7 @@ def _get_maturin() -> types.ModuleType:
         configure_logger(
             enabled=True,
             clear_loggers=True,
-            level="INFO",
+            level="WARNING",
             otel_formatting="auto",
             filter=False,
             enqueue=True,

src/gitversioned/plugins/setuptools_plugin.py

@@ -62,7 +62,8 @@ def setup_keywords(distribution: Distribution, attribute: str, value: Any) -> No
     """
     configure_logger(
         enabled=True,
-        level="INFO",
+        clear_loggers=True,
+        level="WARNING",
         otel_formatting="disable",
         enqueue=False,
         format="[gitversioned:setuptools] {level} - {message}\n",
@@ -105,7 +106,8 @@ def finalize_distribution_options(distribution: Distribution) -> None:
     """
     configure_logger(
         enabled=True,
-        level="INFO",
+        clear_loggers=True,
+        level="WARNING",
         otel_formatting="disable",
         enqueue=False,
         format="[gitversioned:setuptools] {level} - {message}\n",

src/gitversioned/versioning/sources.py

@@ -363,7 +363,7 @@ def resolve_from_git_source(
             version = _extract_versions(patterns, text)[0]
             matches.append((version, reference))
         except VersionResolutionError as ver_err:
-            logger.warning(
+            logger.info(
                 f"Could not extract version from git {type_} '{text}' using "
                 f"patterns {patterns}: {ver_err}"
             )
@@ -452,7 +452,7 @@ def resolve_sources_from_archive(
                 versions = _extract_versions(pattern, attr_val)
                 break
             except ValueError:
-                logger.warning(f"Could not extract version from {source}: {reference}")
+                logger.info(f"Could not extract version from {source}: {reference}")
 
     if not versions:
         raise VersionResolutionError(

tests/e2e/test_logging_stories.py

@@ -389,9 +389,20 @@ def test_hatch_stderr_routing_and_format(
         :param valid_instances: Injected shared context fixture.
         """
         repo_helper = valid_instances["repo"]
+        repo_helper.tag("v0.1.0")
         clean_dist(repo_helper.path)
+
+        # 1. By default, INFO/DEBUG logs should be silent and not pollute stderr
         result = run_build(repo_helper.path)
         assert result.returncode == 0
+        assert "[gitversioned:hatch]" not in result.stderr
+        assert "[gitversioned:hatch]" not in result.stdout
+
+        # 2. When explicitly configured at INFO level, logs should be routed to stderr and match format
+        clean_dist(repo_helper.path)
+        env = {"GITVERSIONED__LOGGING__LEVEL": "INFO"}
+        result = run_build(repo_helper.path, env=env)
+        assert result.returncode == 0
         # Logs should not pollute stdout
         assert "[gitversioned:hatch]" not in result.stdout
         # Logs must go to stderr and match the default hatch prefix
@@ -424,7 +435,7 @@ def test_hatch_verbose_downgrade(self, valid_instances: dict[str, Any]) -> None:
     @pytest.mark.regression
     def test_hatch_protect_native_sinks(self, valid_instances: dict[str, Any]) -> None:
         """
-        Assert Hatchling plugin preserves existing sinks by enforcing clear_loggers=False (AC 2.4).
+        Assert Hatchling plugin clears existing sinks by enforcing clear_loggers=True (AC 2.4).
 
         :param valid_instances: Injected shared context fixture.
         """
@@ -439,9 +450,8 @@ def test_hatch_protect_native_sinks(self, valid_instances: dict[str, Any]) -> No
 source = GitVersionedVersionSource("{str(repo_helper.path)}", {{}})
 source.get_version_data()
 
-# Pre-existing loguru handlers should not be cleared, so parent_logs collects the plugin output
-assert len(parent_logs) > 0
-assert any("get_version_data called" in msg or "gitversioned computed version" in msg for msg in parent_logs)
+# Pre-existing loguru handlers should be cleared by default, so parent_logs should be empty
+assert len(parent_logs) == 0
 print("SUCCESS")
         """
 
@@ -583,12 +593,12 @@ def test_setuptools_root_interception(
 from gitversioned.plugins.setuptools_plugin import finalize_distribution_options
 from setuptools import Distribution
 
-captured = []
-logger.add(captured.append, format="{message}")
-
 dist = Distribution({"name": "test_pkg", "version": "0.0.0"})
 finalize_distribution_options(dist)
 
+captured = []
+logger.add(captured.append, format="{message}")
+
 # Verify handler injection
 root_logger = logging.getLogger()
 assert any(type(h).__name__ == "InterceptHandler" for h in root_logger.handlers)
@@ -609,12 +619,14 @@ def test_setuptools_protect_sinks_and_format(
         self, valid_instances: dict[str, Any]
     ) -> None:
         """
-        Assert clear_loggers=False preserves sinks and format matches tag layout (AC 3.3, 3.4).
+        Assert clear_loggers=True removes pre-existing sinks and format matches tag layout (AC 3.3, 3.4).
 
         :param valid_instances: Injected shared context fixture.
         """
         valid_instances["repo"]
         snippet = """
+import os
+os.environ["GITVERSIONED__LOGGING__LEVEL"] = "INFO"
 from loguru import logger
 from gitversioned.plugins.setuptools_plugin import finalize_distribution_options
 from setuptools import Distribution
@@ -625,9 +637,8 @@ def test_setuptools_protect_sinks_and_format(
 dist = Distribution({"name": "test_pkg", "version": "0.0.0"})
 finalize_distribution_options(dist)
 
-# Verification 1: Parent sinks preserved
-assert len(parent_logs) > 0
-assert any("Finalizing distribution options" in msg or "Resolving version sources" in msg for msg in parent_logs)
+# Verification 1: Parent sinks cleared
+assert len(parent_logs) == 0
 print("SUCCESS")
         """
         result = run_python_snippet(snippet)

tests/python/integration/test_logging.py

@@ -634,6 +634,16 @@ def log_worker(thread_index: int) -> None:
             logger.remove()
             _state["handler_id"] = original_handler_id
 
+    @pytest.mark.regression
+    def test_configure_logger_removes_handler_when_disabled(self) -> None:
+        """Verify configure_logger removes the previously registered handler when disabling."""
+        _state["handler_id"] = 777
+        settings_instance = LoggingSettings(enabled=False)
+        with patch("gitversioned.logging.logger") as mock_loguru:
+            configure_logger(settings_instance)
+            mock_loguru.remove.assert_called_once_with(777)
+            assert _state["handler_id"] is None
+
 
 class TestCLIEntrypoint:
     """Integration test suite for logger behavior under CLI execution context."""
@@ -676,7 +686,8 @@ def test_plugin_logger_setup(self, tmp_path: Path) -> None:
         assert mock_configure.call_count == 1
         call_kwargs = mock_configure.call_args.kwargs
         assert call_kwargs["enabled"] is True
-        assert call_kwargs["level"] == "INFO"
+        assert call_kwargs["clear_loggers"] is True
+        assert call_kwargs["level"] == "WARNING"
         assert call_kwargs["otel_formatting"] == "disable"
         assert call_kwargs["enqueue"] is False
 
@@ -699,7 +710,8 @@ def test_plugin_logger_setup(self, tmp_path: Path) -> None:
         assert mock_configure.call_count == 1
         call_kwargs = mock_configure.call_args.kwargs
         assert call_kwargs["enabled"] is True
-        assert call_kwargs["level"] == "INFO"
+        assert call_kwargs["clear_loggers"] is True
+        assert call_kwargs["level"] == "WARNING"
         assert call_kwargs["otel_formatting"] == "disable"
         assert call_kwargs["enqueue"] is False
 
@@ -714,7 +726,8 @@ def test_plugin_logger_setup(self, tmp_path: Path) -> None:
         assert mock_configure.call_count == 1
         call_kwargs = mock_configure.call_args.kwargs
         assert call_kwargs["enabled"] is True
-        assert call_kwargs["level"] == "INFO"
+        assert call_kwargs["clear_loggers"] is True
+        assert call_kwargs["level"] == "WARNING"
         assert call_kwargs["otel_formatting"] == "disable"
         assert call_kwargs["enqueue"] is False
 

tests/python/unit/test_logging.py

@@ -614,6 +614,16 @@ def test_invocation_clear_loggers_real_logger(self) -> None:
             logger.remove()
             _state["handler_id"] = original_handler_id
 
+    @pytest.mark.regression
+    def test_configure_logger_removes_handler_when_disabled(self) -> None:
+        """Verify configure_logger removes the previously registered handler when disabling."""
+        _state["handler_id"] = 9999
+        settings = LoggingSettings(enabled=False)
+        with patch("gitversioned.logging.logger") as mock_logger:
+            configure_logger(settings)
+            mock_logger.remove.assert_called_once_with(9999)
+            assert _state["handler_id"] is None
+
 
 class TestAutolog:
     """Test suite for autolog module-level decorator."""