Bridge Assemblies: The Key to LLM-Ready Internal Documentation

namespace MyCompany.PaymentProcessing
{
    /// <summary>
    /// Processes payment requests with comprehensive validation and error handling.
    /// </summary>
    /// <remarks>
    /// This processor uses internal validation logic and error handling patterns
    /// that are crucial for understanding the complete payment flow.
    /// </remarks>
    public class PaymentProcessor
    {
        /// <summary>
        /// Processes a payment request asynchronously with full validation.
        /// </summary>
        /// <param name="request">The payment request containing all necessary payment information.</param>
        /// <returns>A task representing the asynchronous operation, containing the payment result.</returns>
        /// <exception cref="ArgumentNullException">Thrown when <paramref name="request"/> is null.</exception>
        public async Task<PaymentResult> ProcessPaymentAsync(PaymentRequest request)
        {
            var validator = new PaymentValidator(); // ❌ Internal class - invisible
            var result = await validator.ValidateAsync(request);
            
            if (!result.IsValid)
                return PaymentResult.Failed(result.Errors);
                
            return await ExecutePaymentAsync(request); // ❌ Internal method - invisible
        }

        /// <summary>
        /// Executes the actual payment processing after validation.
        /// </summary>
        /// <param name="request">The validated payment request.</param>
        /// <returns>The payment processing result.</returns>
        /// <remarks>
        /// This method handles the core payment logic including gateway communication,
        /// retry logic, and transaction logging.
        /// </remarks>
        internal async Task<PaymentResult> ExecutePaymentAsync(PaymentRequest request)
        {
            // Core payment processing logic
            return PaymentResult.Success();
        }
    }
    
    /// <summary>
    /// Provides comprehensive validation for payment requests.
    /// </summary>
    /// <remarks>
    /// ❌ Completely invisible to documentation tools
    /// </remarks>
    internal class PaymentValidator
    {
        /// <summary>
        /// Validates a payment request against all business rules and compliance requirements.
        /// </summary>
        /// <param name="request">The payment request to validate.</param>
        /// <returns>A task containing the validation result with detailed error information.</returns>
        /// <exception cref="ArgumentNullException">Thrown when <paramref name="request"/> is null.</exception>
        internal async Task<ValidationResult> ValidateAsync(PaymentRequest request)
        {
            // Rich validation logic that developers need to understand
            return await PerformComplexValidation(request);
        }

        /// <summary>
        /// Performs complex validation including fraud detection and compliance checks.
        /// </summary>
        /// <param name="request">The payment request to validate.</param>
        /// <returns>A detailed validation result.</returns>
        private async Task<ValidationResult> PerformComplexValidation(PaymentRequest request)
        {
            // Implementation details that help understand the validation patterns
            return ValidationResult.Valid();
        }
    }
}

// In AssemblyInfo.cs or as an assembly attribute
[assembly: InternalsVisibleTo("MyCompany.PaymentProcessing.Tests")]
[assembly: InternalsVisibleTo("MyCompany.PaymentProcessing.Documentation")]

// This is what Filip demonstrated
namespace System.Runtime.CompilerServices
{
    [AttributeUsage(AttributeTargets.Assembly, AllowMultiple = true)]
    internal sealed class IgnoresAccessChecksToAttribute : Attribute
    {
        public string AssemblyName { get; }
        public IgnoresAccessChecksToAttribute(string assemblyName)
        {
            AssemblyName = assemblyName;
        }
    }
}

// Apply it to gain access
[assembly: IgnoresAccessChecksTo("ThirdPartyLibrary")]

internal async Task<Compilation> CreateCompilationAsync(IEnumerable<string> references)
{
    // Step 1: Generate the IgnoresAccessChecksTo attribute dynamically
    // We can't rely on it being available in all target frameworks
    var ignoresAccessChecksSource = @"
        namespace System.Runtime.CompilerServices
        {
            [System.AttributeUsage(System.AttributeTargets.Assembly, AllowMultiple = true)]
            internal sealed class IgnoresAccessChecksToAttribute : System.Attribute
            {
                public string AssemblyName { get; }
                public IgnoresAccessChecksToAttribute(string assemblyName)
                {
                    AssemblyName = assemblyName;
                }
            }
        }";

    // Step 2: Create a bridge assembly that references the target
    var assemblyName = Path.GetFileNameWithoutExtension(AssemblyPath);
    var bridgeSource = $@"
        using System.Runtime.CompilerServices;
        [assembly: IgnoresAccessChecksTo(""{assemblyName}"")]";

    // Step 3: Parse both pieces of source code
    var syntaxTrees = new[]
    {
        CSharpSyntaxTree.ParseText(ignoresAccessChecksSource),
        CSharpSyntaxTree.ParseText(bridgeSource)
    };

    // Step 4: Create compilation with enhanced metadata import
    var compilationOptions = new CSharpCompilationOptions(
        OutputKind.DynamicallyLinkedLibrary,
        metadataImportOptions: MetadataImportOptions.All); // 🔑 Critical setting

    var compilation = CSharpCompilation.Create($"{AssemblyName}.DocumentationBridge")
        .WithOptions(compilationOptions)
        .AddSyntaxTrees(syntaxTrees)
        .AddReferences(targetReference);

    return compilation;
}