Enhance HL7 CQL toolkit with new methods and improvements

Added new methods for handling assembly binaries from FHIR libraries in the `InvocationToolkitExtensions` class. Renamed and expanded the `ResourceFileInfoResolver` delegate for better file resolution of FHIR resources. Improved documentation comments for clarity and made minor adjustments in the `CqlParameterInfo` struct. Removed unused using directives in `InvocationToolkitExtensions.FhirLibraryAdding.cs`.

Author: baseTwo

Cql/Cql.Invocation/PublicAPI.Unshipped.txt

@@ -34,6 +34,8 @@ Hl7.Cql.Invocation.Toolkit.Extensions.LibraryInvokerExtensions
 Hl7.Cql.Invocation.Toolkit.Extensions.LibrarySetInvokerExtensions
 Hl7.Cql.Invocation.Toolkit.Extensions.PostInvokeDefinitionHandler
 Hl7.Cql.Invocation.Toolkit.Extensions.PreInvokeDefinitionHandler
+Hl7.Cql.Invocation.Toolkit.Extensions.ResourceFileInfoResolver
+Hl7.Cql.Invocation.Toolkit.Extensions.ResourceFileInfoResolvers
 Hl7.Cql.Invocation.Toolkit.Extensions.SelectResultsOptions
 Hl7.Cql.Invocation.Toolkit.Extensions.SelectResultsOptions.Deconstruct(out Hl7.Cql.Invocation.Toolkit.Extensions.DefinitionArgumentsProvider? ProviderArgumentsCallback, out Hl7.Cql.Invocation.Toolkit.Extensions.PreInvokeDefinitionHandler? PreInvokeDefinitionCallback, out Hl7.Cql.Invocation.Toolkit.Extensions.PostInvokeDefinitionHandler? PostInvokeDefinitionCallback, out Hl7.Cql.Runtime.BatchProcessExceptionHandler<Hl7.Cql.Invocation.Toolkit.DefinitionInvoker!>? InvocationExceptionCallback) -> void
 Hl7.Cql.Invocation.Toolkit.Extensions.SelectResultsOptions.InvocationExceptionCallback.get -> Hl7.Cql.Runtime.BatchProcessExceptionHandler<Hl7.Cql.Invocation.Toolkit.DefinitionInvoker!>?
@@ -90,6 +92,7 @@ static Hl7.Cql.Invocation.Toolkit.Extensions.ElmToolkitInvocationExtensions.Crea
 static Hl7.Cql.Invocation.Toolkit.Extensions.ElmToolkitInvocationExtensions.CreateLibrarySetInvoker(this Hl7.Cql.CodeGeneration.NET.Toolkit.ElmToolkit! elmToolkit, string! name = "") -> Hl7.Cql.Invocation.Toolkit.LibrarySetInvoker!
 static Hl7.Cql.Invocation.Toolkit.Extensions.ElmToolkitInvocationExtensions.UseLibrarySetInvoker(this Hl7.Cql.CodeGeneration.NET.Toolkit.ElmToolkit! elmToolkit, System.Action<Hl7.Cql.Invocation.Toolkit.LibrarySetInvoker!>! useLibrarySetInvoker, string! librarySetName = "") -> void
 static Hl7.Cql.Invocation.Toolkit.Extensions.InvocationToolkitExtensions.AddAssemblyBinaries(this Hl7.Cql.Invocation.Toolkit.InvocationToolkit! invocationToolkit, params Hl7.Cql.CodeGeneration.NET.AssemblyBinary![]! assemblyBinary) -> Hl7.Cql.Invocation.Toolkit.InvocationToolkit!
+static Hl7.Cql.Invocation.Toolkit.Extensions.InvocationToolkitExtensions.AddAssemblyBinariesFromFhirLibraryAndDependencies(this Hl7.Cql.Invocation.Toolkit.InvocationToolkit! invocationToolkit, Hl7.Cql.Runtime.CqlVersionedLibraryIdentifier libraryIdentifier, Hl7.Cql.Invocation.Toolkit.Extensions.ResourceFileInfoResolver! fhirFileResolver, System.Func<System.IO.FileInfo!, bool>? filePredicate = null, Hl7.Cql.Abstractions.Mutator<System.Text.Json.JsonSerializerOptions!>? configureJsonSerializerOptions = null) -> Hl7.Cql.Invocation.Toolkit.InvocationToolkit!
 static Hl7.Cql.Invocation.Toolkit.Extensions.InvocationToolkitExtensions.AddAssemblyBinariesInFhirLibrariesFromDirectory(this Hl7.Cql.Invocation.Toolkit.InvocationToolkit! invocationToolkit, System.IO.DirectoryInfo! directory, System.IO.EnumerationOptions? options = null, System.Func<System.IO.FileInfo!, bool>? filePredicate = null, Hl7.Cql.Abstractions.Mutator<System.Text.Json.JsonSerializerOptions!>? configureJsonSerializerOptions = null) -> Hl7.Cql.Invocation.Toolkit.InvocationToolkit!
 static Hl7.Cql.Invocation.Toolkit.Extensions.InvocationToolkitExtensions.AddAssemblyBinaryFiles(this Hl7.Cql.Invocation.Toolkit.InvocationToolkit! invocationToolkit, System.Collections.Generic.IEnumerable<System.IO.FileInfo!>! files) -> Hl7.Cql.Invocation.Toolkit.InvocationToolkit!
 static Hl7.Cql.Invocation.Toolkit.Extensions.InvocationToolkitExtensions.AddAssemblyBinaryFilesFromDirectory(this Hl7.Cql.Invocation.Toolkit.InvocationToolkit! invocationToolkit, System.IO.DirectoryInfo! directory, System.IO.EnumerationOptions? options = null, System.Func<System.IO.FileInfo!, bool>? filePredicate = null) -> Hl7.Cql.Invocation.Toolkit.InvocationToolkit!
@@ -102,13 +105,15 @@ static Hl7.Cql.Invocation.Toolkit.Extensions.LibrarySetInvokerExtensions.InvokeL
 static Hl7.Cql.Invocation.Toolkit.Extensions.LibrarySetInvokerExtensions.SelectDefinitions(this Hl7.Cql.Invocation.Toolkit.LibrarySetInvoker! librarySetInvoker) -> System.Collections.Generic.IEnumerable<Hl7.Cql.Invocation.Toolkit.DefinitionInvoker!>!
 static Hl7.Cql.Invocation.Toolkit.Extensions.LibrarySetInvokerExtensions.SelectExpressions(this Hl7.Cql.Invocation.Toolkit.LibrarySetInvoker! librarySetInvoker, Hl7.Cql.Invocation.Toolkit.Extensions.DefinitionPredicate? filter = null) -> System.Collections.Generic.IEnumerable<Hl7.Cql.Invocation.Toolkit.DefinitionInvoker!>!
 static Hl7.Cql.Invocation.Toolkit.Extensions.LibrarySetInvokerExtensions.SelectExpressionsForLibrary(this Hl7.Cql.Invocation.Toolkit.LibrarySetInvoker! librarySetInvoker, Hl7.Cql.Runtime.CqlVersionedLibraryIdentifier libraryIdentifier, Hl7.Cql.Invocation.Toolkit.Extensions.DefinitionPredicate? filter = null) -> System.Collections.Generic.IEnumerable<Hl7.Cql.Invocation.Toolkit.DefinitionInvoker!>!
+static Hl7.Cql.Invocation.Toolkit.Extensions.ResourceFileInfoResolvers.FromDirectory(System.IO.DirectoryInfo! directory, string! resourceType = "Library") -> Hl7.Cql.Invocation.Toolkit.Extensions.ResourceFileInfoResolver!
 static Hl7.Cql.Invocation.Toolkit.Extensions.SelectResultsOptions.Default.get -> Hl7.Cql.Invocation.Toolkit.Extensions.SelectResultsOptions!
 static Hl7.Cql.Invocation.Toolkit.Extensions.SelectResultsOptions.operator !=(Hl7.Cql.Invocation.Toolkit.Extensions.SelectResultsOptions? left, Hl7.Cql.Invocation.Toolkit.Extensions.SelectResultsOptions? right) -> bool
 static Hl7.Cql.Invocation.Toolkit.Extensions.SelectResultsOptions.operator ==(Hl7.Cql.Invocation.Toolkit.Extensions.SelectResultsOptions? left, Hl7.Cql.Invocation.Toolkit.Extensions.SelectResultsOptions? right) -> bool
 virtual Hl7.Cql.Invocation.Toolkit.Extensions.DefinitionArgumentsProvider.Invoke(Hl7.Cql.Invocation.Toolkit.DefinitionInvoker! definitionInvoker, Hl7.Cql.Runtime.CqlContext! cqlContext) -> object?[]!
 virtual Hl7.Cql.Invocation.Toolkit.Extensions.DefinitionPredicate.Invoke(Hl7.Cql.Invocation.Toolkit.DefinitionInvoker! definitionInvoker) -> bool
 virtual Hl7.Cql.Invocation.Toolkit.Extensions.PostInvokeDefinitionHandler.Invoke(Hl7.Cql.Invocation.Toolkit.DefinitionInvoker! definitionInvoker, Hl7.Cql.Runtime.CqlContext! cqlContext, object?[]! definitionArguments, object? definitionResult) -> void
 virtual Hl7.Cql.Invocation.Toolkit.Extensions.PreInvokeDefinitionHandler.Invoke(Hl7.Cql.Invocation.Toolkit.DefinitionInvoker! definitionInvoker, Hl7.Cql.Runtime.CqlContext! cqlContext, object?[]! definitionArguments) -> void
+virtual Hl7.Cql.Invocation.Toolkit.Extensions.ResourceFileInfoResolver.Invoke(Hl7.Cql.Runtime.CqlVersionedLibraryIdentifier libraryIdentifier) -> System.IO.FileInfo!
 virtual Hl7.Cql.Invocation.Toolkit.Extensions.SelectResultsOptions.<Clone>$() -> Hl7.Cql.Invocation.Toolkit.Extensions.SelectResultsOptions!
 virtual Hl7.Cql.Invocation.Toolkit.Extensions.SelectResultsOptions.EqualityContract.get -> System.Type!
 virtual Hl7.Cql.Invocation.Toolkit.Extensions.SelectResultsOptions.Equals(Hl7.Cql.Invocation.Toolkit.Extensions.SelectResultsOptions? other) -> bool

Cql/Cql.Invocation/Toolkit/CqlParameterInfo.cs

@@ -10,11 +10,11 @@ namespace Hl7.Cql.Invocation.Toolkit;
 public readonly record struct CqlParameterInfo(string Name, Type Type)
 {
     /// <summary>
-    /// Returns a string representation of the CQL parameter information, 
+    /// Returns a string representation of the CQL parameter information,
     /// including its type and name.
     /// </summary>
     /// <returns>
-    /// A string in the format "<c>{Type}</c> '<c>{Name}</c>'", where <c>{Type}</c> 
+    /// A string in the format "<c>{Type}</c> '<c>{Name}</c>'", where <c>{Type}</c>
     /// is the C# representation of the parameter's type and <c>{Name}</c> is the parameter's name.
     /// </returns>
     public override string ToString() => $"{Type.ToCSharpString()} '{Name}'";

Cql/Cql.Invocation/Toolkit/Extensions/InvocationToolkitExtensions.FhirLibraryAdding.cs

@@ -14,8 +14,6 @@
 using Hl7.Fhir.Serialization;
 using Hl7.Fhir.Validation;
 using System.Text.Json;
-using Hl7.Cql.Abstractions.Infrastructure;
-using Hl7.Fhir.Utility;
 
 namespace Hl7.Cql.Invocation.Toolkit.Extensions;
 
@@ -67,11 +65,38 @@ public static InvocationToolkit AddAssemblyBinariesInFhirLibrariesFromDirectory(
         return invocationToolkit.AddAssemblyBinaries(assemblyBinaries);
     }
 
-
+    /// <summary>
+    /// Adds assembly binaries from a specified FHIR library and its dependencies to the <see cref="InvocationToolkit"/>.
+    /// </summary>
+    /// <param name="invocationToolkit">
+    /// The <see cref="InvocationToolkit"/> instance to which the assembly binaries will be added.
+    /// </param>
+    /// <param name="libraryIdentifier">
+    /// The identifier of the FHIR library, including its version, to load the assembly binaries from.
+    /// </param>
+    /// <param name="fhirFileResolver">
+    /// A delegate that resolves the file information for a given FHIR library identifier.
+    /// </param>
+    /// <param name="filePredicate">
+    /// An optional predicate to filter the files to be processed. If <c>null</c>, all files are processed.
+    /// </param>
+    /// <param name="configureJsonSerializerOptions">
+    /// An optional mutator to configure the <see cref="JsonSerializerOptions"/> used during processing.
+    /// </param>
+    /// <returns>
+    /// The updated <see cref="InvocationToolkit"/> instance with the added assembly binaries.
+    /// </returns>
+    /// <remarks>
+    /// This method processes the specified FHIR library and its dependencies to extract assembly binaries.
+    /// It applies the provided file predicate and JSON serializer configuration during the process.
+    /// </remarks>
+    /// <exception cref="ArgumentNullException">
+    /// Thrown if <paramref name="invocationToolkit"/>, <paramref name="libraryIdentifier"/>, or <paramref name="fhirFileResolver"/> is <c>null</c>.
+    /// </exception>
     public static InvocationToolkit AddAssemblyBinariesFromFhirLibraryAndDependencies(
         this InvocationToolkit invocationToolkit,
         CqlVersionedLibraryIdentifier libraryIdentifier,
-        ResourceFileInfoFromIdentifierResolver fhirFileResolver,
+        ResourceFileInfoResolver fhirFileResolver,
         Func<FileInfo, bool>? filePredicate = null,
         Mutator<JsonSerializerOptions>? configureJsonSerializerOptions = null)
     {
@@ -99,12 +124,12 @@ public static InvocationToolkit AddAssemblyBinariesFromFhirLibraryAndDependencie
     }
 }
 
-public static partial class FhirLibraryUtilities
+internal static partial class FhirLibraryUtilities
 {
     public static IEnumerable<FhirLibrary> LoadFhirLibraryAndDependencies(
         ILogger logger,
         CqlVersionedLibraryIdentifier libraryIdentifier,
-        ResourceFileInfoFromIdentifierResolver fhirFileResolver,
+        ResourceFileInfoResolver fhirFileResolver,
         Func<FileInfo, bool>? filePredicate = null,
         Mutator<JsonSerializerOptions>? configureJsonSerializerOptions = null)
     {

Cql/Cql.Invocation/Toolkit/Extensions/ResourceFileInfoResolvers.cs

@@ -24,19 +24,29 @@ namespace Hl7.Cql.Invocation.Toolkit.Extensions;
 /// <remarks>
 /// It should not be assumed that the file exists.
 /// </remarks>
-public delegate FileInfo ResourceFileInfoFromIdentifierResolver(CqlVersionedLibraryIdentifier libraryIdentifier);
+public delegate FileInfo ResourceFileInfoResolver(CqlVersionedLibraryIdentifier libraryIdentifier);
 
+/// <summary>
+/// Provides extension methods for resolving file information related to FHIR resource libraries.
+/// </summary>
+/// <remarks>
+/// This class includes methods to create resolvers that map FHIR resource library identifiers
+/// to corresponding file information, such as resolving files from a specified directory.
+/// </remarks>
 public static class ResourceFileInfoResolvers
 {
     /// <summary>
-    /// Creates a <see cref="ResourceFileInfoFromIdentifierResolver"/> that resolves file information
+    /// Creates a <see cref="ResourceFileInfoResolver"/> that resolves file information
     /// for FHIR resource library located in a specified directory.
     /// </summary>
     /// <param name="directory">
     /// The directory from which the FHIR resource library files are resolved.
     /// </param>
+    /// <param name="resourceType">
+    /// The type of the resource, defaulting to "Library".
+    /// </param>
     /// <returns>
-    /// A <see cref="ResourceFileInfoFromIdentifierResolver"/> that resolves a <see cref="FileInfo"/>
+    /// A <see cref="ResourceFileInfoResolver"/> that resolves a <see cref="FileInfo"/>
     /// instance for a given <see cref="CqlVersionedLibraryIdentifier"/> by locating the corresponding
     /// file in the specified directory.
     /// </returns>
@@ -45,7 +55,7 @@ public static class ResourceFileInfoResolvers
     /// using the <see cref="ResourceFileName"/> to construct the file name.
     /// It does not guarantee that the resolved file exists.
     /// </remarks>
-    public static ResourceFileInfoFromIdentifierResolver FromDirectory(
+    public static ResourceFileInfoResolver FromDirectory(
         DirectoryInfo directory,
         string resourceType = "Library") =>
         libraryIdentifier =>

Cql/Cql.Packaging/PublicAPI.Unshipped.txt

@@ -102,6 +102,7 @@ override Hl7.Cql.Packaging.Toolkit.PackagingToolkitResultArtifacts.GetHashCode()
 static Hl7.Cql.Packaging.CqlTypeToFhirMapping.operator !=(Hl7.Cql.Packaging.CqlTypeToFhirMapping? left, Hl7.Cql.Packaging.CqlTypeToFhirMapping? right) -> bool
 static Hl7.Cql.Packaging.CqlTypeToFhirMapping.operator ==(Hl7.Cql.Packaging.CqlTypeToFhirMapping? left, Hl7.Cql.Packaging.CqlTypeToFhirMapping? right) -> bool
 static Hl7.Cql.Packaging.ResourceFileName.Create(string! type, string! identifier, string? version = null) -> Hl7.Cql.Packaging.ResourceFileName
+static Hl7.Cql.Packaging.ResourceFileName.implicit operator string!(Hl7.Cql.Packaging.ResourceFileName resourceFileName) -> string!
 static Hl7.Cql.Packaging.ResourceFileName.operator !=(Hl7.Cql.Packaging.ResourceFileName left, Hl7.Cql.Packaging.ResourceFileName right) -> bool
 static Hl7.Cql.Packaging.ResourceFileName.operator ==(Hl7.Cql.Packaging.ResourceFileName left, Hl7.Cql.Packaging.ResourceFileName right) -> bool
 static Hl7.Cql.Packaging.ResourceFileName.Parse(string! s, System.IFormatProvider? provider) -> Hl7.Cql.Packaging.ResourceFileName