Fix first-run collection discovery by gating plugin loader initialization (#516)

* fix: gate plugin loader initialization to prevent early collection path capture

Fixes first-run collection discovery issue where ansible-lint fails to find
plugins from collections installed during prepare_environment().

The problem occurs because Ansible's plugin loader was initialized too early
with incomplete collection paths, before prepare_environment() installs
dependencies from requirements.yml and galaxy.yml files. This particularly
affects Templar usage since it relies on the collection loader for template
rendering and plugin discovery.

Changes:
- Add Runtime.plugin_loader_enabled class variable to gate access
- Add enable_plugin_loader() method for explicit initialization
- Modify Plugins.__getattribute__ to raise RuntimeError if accessed early
- Enhance clean() to reset flags and unload ansible modules for test isolation
- Move plugin loader init from _ensure_module_available() to enable_plugin_loader()

This ensures plugin loader initialization happens after collections are
installed, eliminating the 'works on second run' behavior.

* chore: auto fixes from pre-commit.com hooks

* lint fixes

* deps

* chore: auto fixes from pre-commit.com hooks

---------

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

Author: cidrblock

.config/constraints.txt

@@ -8,29 +8,29 @@ beautifulsoup4==4.13.4    # via linkchecker, mkdocs-htmlproofer-plugin
 black==25.1.0             # via ansible-compat (pyproject.toml)
 cairocffi==1.7.1          # via cairosvg
 cairosvg==2.7.1           # via mkdocs-ansible
-certifi==2025.6.15        # via requests
+certifi==2025.8.3         # via requests
 cffi==1.17.1              # via cairocffi, cryptography
-charset-normalizer==3.4.2  # via requests
+charset-normalizer==3.4.3  # via requests
 click==8.2.1              # via black, mkdocs
 colorama==0.4.6           # via griffe, mkdocs-material
-coverage==7.9.2           # via ansible-compat (pyproject.toml)
-cryptography==45.0.5      # via ansible-core
+coverage==7.10.3          # via ansible-compat (pyproject.toml)
+cryptography==45.0.6      # via ansible-core
 csscompressor==0.9.5      # via mkdocs-minify-plugin
 cssselect2==0.8.0         # via cairosvg
 defusedxml==0.7.1         # via cairosvg
 dnspython==2.7.0          # via linkchecker
 exceptiongroup==1.3.0     # via pytest
 ghp-import==2.1.0         # via mkdocs
-griffe==1.7.3             # via mkdocstrings-python
+griffe==1.11.1            # via mkdocstrings-python
 hjson==3.1.0              # via mkdocs-macros-plugin, super-collections
 htmlmin2==0.1.13          # via mkdocs-minify-plugin
 idna==3.10                # via requests
 iniconfig==2.1.0          # via pytest
 jinja2==3.1.6             # via ansible-core, mkdocs, mkdocs-macros-plugin, mkdocs-material, mkdocstrings
 jsmin==3.0.1              # via mkdocs-minify-plugin
-jsonschema==4.24.0        # via ansible-compat (pyproject.toml)
+jsonschema==4.25.0        # via ansible-compat (pyproject.toml)
 jsonschema-specifications==2025.4.1  # via jsonschema
-linkchecker==10.5.0       # via mkdocs-ansible
+linkchecker==10.6.0       # via mkdocs-ansible
 markdown==3.8.2           # via markdown-include, mkdocs, mkdocs-autorefs, mkdocs-htmlproofer-plugin, mkdocs-material, mkdocstrings, pymdown-extensions
 markdown-exec==1.11.0     # via mkdocs-ansible
 markdown-include==0.8.1   # via mkdocs-ansible
@@ -42,11 +42,11 @@ mkdocs-autorefs==1.4.2    # via mkdocstrings, mkdocstrings-python
 mkdocs-gen-files==0.5.0   # via mkdocs-ansible
 mkdocs-get-deps==0.2.0    # via mkdocs
 mkdocs-htmlproofer-plugin==1.3.0  # via mkdocs-ansible
-mkdocs-macros-plugin==1.3.7  # via mkdocs-ansible
-mkdocs-material==9.6.15   # via mkdocs-ansible
+mkdocs-macros-plugin==1.3.9  # via mkdocs-ansible
+mkdocs-material==9.6.16   # via mkdocs-ansible
 mkdocs-material-extensions==1.3.1  # via mkdocs-ansible, mkdocs-material
 mkdocs-minify-plugin==0.8.0  # via mkdocs-ansible
-mkdocstrings==0.29.1      # via mkdocs-ansible, mkdocstrings-python
+mkdocstrings==0.30.0      # via mkdocs-ansible, mkdocstrings-python
 mkdocstrings-python==1.16.12  # via mkdocs-ansible
 mypy-extensions==1.1.0    # via black
 packaging==25.0           # via ansible-core, black, mkdocs, mkdocs-macros-plugin, pytest, ansible-compat (pyproject.toml)
@@ -57,7 +57,7 @@ platformdirs==4.3.8       # via black, mkdocs-get-deps
 pluggy==1.6.0             # via pytest
 pycparser==2.22           # via cffi
 pygments==2.19.2          # via mkdocs-material, pytest
-pymdown-extensions==10.16  # via markdown-exec, mkdocs-ansible, mkdocs-material, mkdocstrings
+pymdown-extensions==10.16.1  # via markdown-exec, mkdocs-ansible, mkdocs-material, mkdocstrings
 pytest==8.4.1             # via pytest-instafail, pytest-mock, pytest-plus, ansible-compat (pyproject.toml)
 pytest-instafail==0.5.0   # via ansible-compat (pyproject.toml)
 pytest-mock==3.14.1       # via ansible-compat (pyproject.toml)
@@ -67,7 +67,7 @@ pyyaml==6.0.2             # via ansible-core, mkdocs, mkdocs-get-deps, mkdocs-ma
 pyyaml-env-tag==1.1       # via mkdocs
 referencing==0.36.2       # via jsonschema, jsonschema-specifications
 requests==2.32.4          # via linkchecker, mkdocs-htmlproofer-plugin, mkdocs-material
-rpds-py==0.26.0           # via jsonschema, referencing
+rpds-py==0.27.0           # via jsonschema, referencing
 six==1.17.0               # via python-dateutil
 soupsieve==2.7            # via beautifulsoup4
 subprocess-tee==0.4.2     # via ansible-compat (pyproject.toml)

.config/pydoclint-baseline.txt

@@ -58,10 +58,6 @@ src/ansible_compat/runtime.py
     DOC101: Method `Plugins.__getattribute__`: Docstring contains fewer arguments than in function signature.
     DOC103: Method `Plugins.__getattribute__`: Docstring arguments are different from function arguments. (Or could be other formatting issues: https://jsh9.github.io/pydoclint/violation_codes.html#notes-on-doc103 ). Arguments in the function signature but not in the docstring: [attr: str].
     DOC201: Method `Plugins.__getattribute__` does not have a return section in docstring
-    DOC501: Method `Plugins.__getattribute__` has raise statements, but the docstring does not have a "Raises" section
-    DOC503: Method `Plugins.__getattribute__` exceptions in the "Raises" section in the docstring do not match those in the function body. Raised exceptions in the docstring: []. Raised exceptions in the body: ['AnsibleCompatError'].
-    DOC601: Class `Runtime`: Class docstring contains fewer class attributes than actual class attributes.  (Please read https://jsh9.github.io/pydoclint/checking_class_attributes.html on how to correctly document class attributes.)
-    DOC603: Class `Runtime`: Class docstring attributes are different from actual class attributes. (Or could be other formatting issues: https://jsh9.github.io/pydoclint/violation_codes.html#notes-on-doc103 ). Attributes in the class definition but not in the docstring: [_has_playbook_cache: dict[tuple[str, Path | None], bool], _version: Version | None, cache_dir: Path, collections: OrderedDict[str, Collection], initialized: bool, plugins: Plugins, require_module: bool]. (Please read https://jsh9.github.io/pydoclint/checking_class_attributes.html on how to correctly document class attributes.)
     DOC101: Method `Runtime.__init__`: Docstring contains fewer arguments than in function signature.
     DOC103: Method `Runtime.__init__`: Docstring arguments are different from function arguments. (Or could be other formatting issues: https://jsh9.github.io/pydoclint/violation_codes.html#notes-on-doc103 ). Arguments in the function signature but not in the docstring: [environ: dict[str, str] | None, isolated: bool, max_retries: int, min_required_version: str | None, project_dir: Path | None, require_module: bool, verbosity: int].
     DOC501: Method `Runtime.__init__` has raise statements, but the docstring does not have a "Raises" section
@@ -129,8 +125,6 @@ src/ansible_compat/schema.py
     DOC201: Method `JsonSchemaError.to_friendly` does not have a return section in docstring
 --------------------
 test/conftest.py
-    DOC101: Function `runtime`: Docstring contains fewer arguments than in function signature.
-    DOC103: Function `runtime`: Docstring arguments are different from function arguments. (Or could be other formatting issues: https://jsh9.github.io/pydoclint/violation_codes.html#notes-on-doc103 ). Arguments in the function signature but not in the docstring: [scope: str].
     DOC402: Function `runtime` has "yield" statements, but the docstring does not have a "Yields" section
     DOC101: Function `runtime_tmp`: Docstring contains fewer arguments than in function signature.
     DOC103: Function `runtime_tmp`: Docstring arguments are different from function arguments. (Or could be other formatting issues: https://jsh9.github.io/pydoclint/violation_codes.html#notes-on-doc103 ). Arguments in the function signature but not in the docstring: [scope: str, tmp_path: pathlib.Path].

src/ansible_compat/runtime.py

@@ -107,7 +107,12 @@ class Plugins:  # pylint: disable=too-many-instance-attributes
 
     @no_type_check
     def __getattribute__(self, attr: str):  # noqa: ANN204
-        """Get attribute."""
+        """Get attribute.
+
+        Raises:
+            RuntimeError: If plugin loader has not been enabled yet.
+            AnsibleCompatError: If unexpected output from ansible-doc.
+        """
         if attr in {
             "become",
             "cache",
@@ -130,6 +135,14 @@ def __getattribute__(self, attr: str):  # noqa: ANN204
             try:
                 result = super().__getattribute__(attr)
             except AttributeError as exc:
+                # If plugin loader is not enabled yet, raise RuntimeError
+                if not Runtime.plugin_loader_enabled:
+                    msg = (
+                        f"Plugin loader has not been enabled yet. "
+                        f"Cannot access runtime.plugins.{attr} before calling "
+                        f"runtime.enable_plugin_loader()."
+                    )
+                    raise RuntimeError(msg) from exc
                 proc = self.runtime.run(
                     ["ansible-doc", "--json", "-l", "-t", attr],
                 )
@@ -146,14 +159,27 @@ def __getattribute__(self, attr: str):  # noqa: ANN204
 
 # pylint: disable=too-many-instance-attributes
 class Runtime:
-    """Ansible Runtime manager."""
+    """Ansible Runtime manager.
+
+    Attributes:
+        _version: Cached version of Ansible.
+        collections: Ordered dictionary of collections.
+        cache_dir: Path to cache directory.
+        initialized: Flag tracking if Ansible runtime has been initialized.
+        plugin_loader_enabled: Flag controlling when plugin loader initialization is allowed.
+        plugins: Plugins instance for accessing Ansible plugins.
+        _has_playbook_cache: Cache for playbook existence checks.
+        require_module: Flag indicating if module is required.
+    """
 
     _version: Version | None = None
     collections: OrderedDict[str, Collection] = OrderedDict()
     cache_dir: Path
     # Used to track if we have already initialized the Ansible runtime as attempts
     # to do it multiple tilmes will cause runtime warnings from within ansible-core
     initialized: bool = False
+    # Flag to control when plugin loader initialization is allowed
+    plugin_loader_enabled: bool = False
     plugins: Plugins
     _has_playbook_cache: dict[tuple[str, Path | None], bool] = {}
     require_module: bool = False
@@ -368,26 +394,52 @@ def _ensure_module_available(self) -> None:
             msg = f"Ansible CLI ({self.version}) and python module ({ansible_module_version}) versions do not match. This indicates a broken execution environment."
             raise RuntimeError(msg)
 
-        # We need to initialize the plugin loader
-        # https://github.com/ansible/ansible-lint/issues/2945
+    def enable_plugin_loader(self) -> None:
+        """Enable plugin loader initialization with current collections paths."""
+        Runtime.plugin_loader_enabled = True
+
+        # Initialize the plugin loader now with the full collections paths
         if not Runtime.initialized:
-            col_path = [f"{self.cache_dir}/collections"]
+            col_paths = self.config.collections_paths
+            if self.isolated:
+                col_paths = [str(self.cache_dir / "collections"), *col_paths]
             # noinspection PyProtectedMember
             # pylint: disable=import-outside-toplevel,no-name-in-module
             from ansible.plugins.loader import init_plugin_loader
             from ansible.utils.collection_loader._collection_finder import (  # pylint: disable=import-outside-toplevel
                 _AnsibleCollectionFinder,  # noqa: PLC2701
             )
 
-            _AnsibleCollectionFinder(  # noqa: SLF001
-                paths=col_path,
-            )._remove()  # pylint: disable=protected-access
-            init_plugin_loader(col_path)
+            with contextlib.suppress(Exception):
+                _AnsibleCollectionFinder()._remove()  # pylint: disable=protected-access  # noqa: SLF001
+
+            init_plugin_loader(col_paths)
+            Runtime.initialized = True
 
     def clean(self) -> None:
-        """Remove content of cache_dir."""
+        """Remove content of cache_dir and reset global Runtime state."""
         shutil.rmtree(self.cache_dir, ignore_errors=True)
 
+        # Reset global Runtime class state to allow fresh initialization
+        Runtime.initialized = False
+        Runtime.plugin_loader_enabled = False
+
+        # Unload ansible modules that cache plugin/collection state
+        # This ensures fresh plugin loader and collection finder state
+        modules_to_remove = [
+            mod
+            for mod in sys.modules
+            if mod.startswith(
+                (
+                    "ansible.plugins.",  # Plugin loaders and cached plugins
+                    "ansible.utils.collection_loader",  # Collection finder system
+                    "ansible.collections.",  # Loaded collection modules
+                ),
+            )
+        ]
+        for mod in modules_to_remove:
+            del sys.modules[mod]
+
     def run(  # ruff: disable=PLR0913
         self,
         args: str | list[str],
@@ -667,6 +719,7 @@ def prepare_environment(  # noqa: C901
             required_collections = {}
 
         self._prepare_ansible_paths()
+
         # first one is standard for collection layout repos and the last two
         # are part of Tower specification
         # https://docs.ansible.com/ansible-tower/latest/html/userguide/projects.html#ansible-galaxy-support

src/ansible_compat/schema.py

@@ -107,7 +107,7 @@ def validate(
         errors.append(error)
         return errors
 
-    for validation_error in validator(schema).iter_errors(data):
+    for validation_error in validator(schema).iter_errors(data):  # type: ignore[call-arg]
         if isinstance(validation_error, jsonschema.ValidationError):
             error = JsonSchemaError(
                 message=validation_error.message,

test/conftest.py

@@ -14,10 +14,15 @@
 
 
 @pytest.fixture
-# pylint: disable=unused-argument
-def runtime(scope: str = "session") -> Generator[Runtime, None, None]:  # noqa: ARG001
-    """Isolated runtime fixture."""
-    instance = Runtime(isolated=True)
+def runtime(request: pytest.FixtureRequest) -> Generator[Runtime, None, None]:
+    """Isolated runtime fixture with configurable parameters.
+
+    Args:
+        request: Pytest fixture request object containing test parameters.
+    """
+    provided_params = getattr(request, "param", {}) if hasattr(request, "param") else {}
+    use_params = provided_params or {"isolated": True}
+    instance = Runtime(**use_params)
     yield instance
     instance.clean()
 

test/test_runtime.py

@@ -81,9 +81,16 @@ def test_runtime_mismatch_ansible_module(monkeypatch: MonkeyPatch) -> None:
         Runtime(require_module=True)
 
 
-def test_runtime_require_module() -> None:
-    """Check that require_module successful pass."""
-    Runtime(require_module=True)
+@pytest.mark.parametrize("runtime", ({"require_module": True},), indirect=True)
+def test_runtime_require_module(runtime: Runtime) -> None:
+    """Check that require_module successful pass.
+
+    Enable the plugin loader to make sure that the module is loaded.
+
+    Args:
+        runtime: Runtime fixture with require_module=True.
+    """
+    runtime.enable_plugin_loader()
     # Now we try to set the collection path, something to check if that is
     # causing an exception, as 2.15 introduced new init code.
     from ansible.utils.collection_loader import (  # pylint: disable=import-outside-toplevel
@@ -759,6 +766,7 @@ def test_load_plugins(
     with cwd(Path(path)):
         runtime = Runtime(isolated=True, require_module=True)
         runtime.prepare_environment(install_local=True)
+        runtime.enable_plugin_loader()
         for plugin_name in expected_plugins:
             assert (
                 plugin_name in runtime.plugins.module
@@ -898,6 +906,7 @@ def test_runtime_exec_env(runtime: Runtime) -> None:
 
 def test_runtime_plugins(runtime: Runtime) -> None:
     """Tests ability to access detected plugins."""
+    runtime.enable_plugin_loader()
     assert len(runtime.plugins.cliconf) == 0
     # ansible.netcommon.restconf might be in httpapi
     assert isinstance(runtime.plugins.httpapi, dict)
@@ -1031,3 +1040,23 @@ def test_runtime_exception(monkeypatch: pytest.MonkeyPatch) -> None:
         match=r"ANSIBLE_COLLECTIONS_PATHS was detected, replace it with ANSIBLE_COLLECTIONS_PATH to continue.",
     ):
         Runtime()
+
+
+def test_runtime_plugin_loader_enabled(runtime: Runtime) -> None:
+    """Test that plugin loader works after being enabled.
+
+    Args:
+        runtime: Runtime fixture for testing plugin loader functionality.
+    """
+    # Initially, plugin loader should not be enabled and accessing plugins should fail
+    with pytest.raises(RuntimeError, match="Plugin loader has not been enabled yet"):
+        _ = runtime.plugins.become
+
+    # Enable the plugin loader
+    runtime.enable_plugin_loader()
+
+    # Now accessing plugins should work without errors
+    become_plugins = runtime.plugins.become
+    assert isinstance(become_plugins, dict)
+    # Should have at least the built-in 'sudo' become plugin
+    assert len(become_plugins) >= 0  # Could be empty in isolated test environment