Restore pre ansible-lint 25.8.1 behavior for compatibility (#520)

- Add ansible-lint version detection via importlib.metadata
- Auto-enable plugin loader for ansible-lint < 25.8.1 to preserve old behavior
- Create compatibility module for backward compatibility logic
- Add utils module for version detection functions
- Add comprehensive parametrized tests for compatibility logic
- Maintain new gated behavior for ansible-lint >= 25.8.1

This change resolves compatibility issues reported by users with older
ansible-lint versions while preserving the improved collection discovery
behavior for newer versions.

Author: cidrblock

src/ansible_compat/compatibility.py

@@ -0,0 +1,27 @@
+"""Compatibility functions for ansible_compat.
+
+This module contains functions that handle backward compatibility
+with different versions of ansible-lint and other tools.
+"""
+
+from __future__ import annotations
+
+from packaging.version import Version
+
+from ansible_compat.constants import ANSIBLE_LINT_MIN_VERSION_EARLY_LOADER
+from ansible_compat.utils import ansible_lint_version
+
+
+def should_auto_enable_plugin_loader() -> bool:
+    """Check if plugin loader should be auto-enabled for backwards compatibility.
+
+    Returns True if ansible-lint version is < ANSIBLE_LINT_MIN_VERSION_EARLY_LOADER.
+
+    Returns:
+        True if plugin loader should be auto-enabled, False otherwise.
+    """
+    # Check ansible-lint version
+    lint_version = ansible_lint_version()
+    return lint_version is not None and lint_version < Version(
+        ANSIBLE_LINT_MIN_VERSION_EARLY_LOADER,
+    )

src/ansible_compat/constants.py

@@ -16,6 +16,9 @@
 # Minimal version of Ansible we support for runtime
 ANSIBLE_MIN_VERSION = "2.16"
 
+# ansible-lint version below which we auto-enable plugin loader for backwards compatibility
+ANSIBLE_LINT_MIN_VERSION_EARLY_LOADER = "25.8.1"
+
 # Based on https://docs.ansible.com/ansible/latest/reference_appendices/config.html
 ANSIBLE_DEFAULT_ROLES_PATH = (
     "~/.ansible/roles:/usr/share/ansible/roles:/etc/ansible/roles"

src/ansible_compat/runtime.py

@@ -23,6 +23,7 @@
 import subprocess_tee
 from packaging.version import Version
 
+from ansible_compat.compatibility import should_auto_enable_plugin_loader
 from ansible_compat.config import (
     AnsibleConfig,
     parse_ansible_version,
@@ -252,6 +253,10 @@ def __init__(
             self.require_module = True
             self._ensure_module_available()
 
+        # For backwards compatibility with ansible-lint < 25.8.1
+        if should_auto_enable_plugin_loader():
+            self.enable_plugin_loader()
+
         # pylint: disable=import-outside-toplevel
         from ansible.utils.display import Display
 

src/ansible_compat/utils.py

@@ -0,0 +1,22 @@
+"""Utility functions for ansible_compat."""
+
+from __future__ import annotations
+
+from importlib.metadata import PackageNotFoundError, version
+
+from packaging.version import Version
+
+from ansible_compat.ports import cache
+
+
+@cache
+def ansible_lint_version() -> Version | None:
+    """Return current Version object for ansible-lint if available.
+
+    Returns:
+        Version object for ansible-lint or None if not found.
+    """
+    try:
+        return Version(version("ansible-lint"))
+    except (ImportError, PackageNotFoundError):
+        return None

test/test_compatibility.py

@@ -0,0 +1,56 @@
+"""Test compatibility functions."""
+
+from __future__ import annotations
+
+import pytest
+from packaging.version import Version
+
+from ansible_compat.compatibility import should_auto_enable_plugin_loader
+
+
+@pytest.mark.parametrize(
+    ("ansible_lint_version", "expected"),
+    (
+        # ansible-lint < 25.8.1 should auto-enable
+        ("25.8.0", True),
+        ("25.7.9", True),
+        ("25.0.0", True),
+        ("24.9.9", True),
+        ("6.22.2", True),
+        # ansible-lint >= 25.8.1 should not auto-enable
+        ("25.8.1", False),
+        ("25.8.2", False),
+        ("25.9.0", False),
+        ("26.0.0", False),
+        ("30.0.0", False),
+        # No ansible-lint should not auto-enable
+        (None, False),
+    ),
+)
+def test_should_auto_enable_plugin_loader(
+    ansible_lint_version: str | None,
+    expected: bool,
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    """Test should_auto_enable_plugin_loader with different ansible-lint versions.
+
+    Args:
+        ansible_lint_version: The ansible-lint version to mock, or None for no ansible-lint.
+        expected: The expected result from should_auto_enable_plugin_loader().
+        monkeypatch: Pytest fixture for mocking.
+    """
+
+    def mock_ansible_lint_version() -> Version | None:
+        if ansible_lint_version is None:
+            return None
+        return Version(ansible_lint_version)
+
+    monkeypatch.setattr(
+        "ansible_compat.compatibility.ansible_lint_version",
+        mock_ansible_lint_version,
+    )
+
+    result = should_auto_enable_plugin_loader()
+    assert (
+        result is expected
+    ), f"Expected {expected} for ansible-lint {ansible_lint_version}, got {result}"