Problem

When ansible-lint runs on collections for the first time, it fails to discover plugins from collections installed by ansible-compat during prepare_environment(). The issue occurs because Ansible's plugin loader is initialized too early with incomplete collection paths, before prepare_environment() has a chance to install dependencies.

Root Cause

The plugin loader was being initialized during Runtime.__init__() or early module imports, capturing collection paths before:

1. Collections are installed from requirements.yml and galaxy.yml dependencies
2. The cache directory (/.ansible/collections) is populated
3. ANSIBLE_COLLECTIONS_PATH includes the newly installed collections

The problem was particularly acute because ansible-lint's Templar class internally uses Ansible's collection loader for template rendering and plugin discovery. When the plugin loader was initialized early with incomplete paths, Templar would fail to find collections that were installed during prepare_environment(), leading to template rendering failures and missing plugin errors.

Solution

Introduced a plugin loader gate mechanism to delay initialization until the environment is fully prepared:

1. Gated Plugin Loader Access

• Added Runtime.plugin_loader_enabled class variable (defaults to False)
• Modified Plugins.__getattribute__ to raise RuntimeError if plugin loader is accessed before being enabled
• This provides clear error messages when the loader is accessed prematurely

2. Explicit Plugin Loader Enablement

• Added Runtime.enable_plugin_loader() method to explicitly initialize the plugin loader
• Moved plugin loader initialization from _ensure_module_available() to this dedicated method
• ansible-lint now calls enable_plugin_loader() after prepare_environment() completes

3. Enhanced State Management

• Modified Runtime.clean() to reset both initialized and plugin_loader_enabled flags
• Added module unloading for ansible.plugins.*, ansible.utils.collection_loader, and ansible.collections.* to ensure fresh state between test runs

Changes Made

• runtime.py: Added plugin loader gating and explicit enablement
• test_runtime.py: Added test for plugin loader gating behavior

Impact

• First-run collection discovery now works reliably
• Plugin loader initialization is deterministic and controlled
• Templar can access collections installed during prepare_environment through the properly initialized collection loader
• Better error messages when plugin loader is accessed prematurely
• Improved test isolation through enhanced state cleanup
• No breaking changes to existing ansible-compat API

This change ensures that ansible-lint can successfully discover and use collection plugins on the first run, eliminating the "works on second run" behavior that users were experiencing.