Fix thread safety, reduce duplication, improve error context, add tests and XML docs

- Fix race condition in RoslynTokenExpressionProvider: volatile + Interlocked.Exchange
  for __runtimeContext, capture context locally in GetTokenExpression/Compile
- Extract shared ParseConditionalToken in TokenParser to eliminate duplicated
  ParseIfToken/ParseWhileToken logic
- Add TokenId property to TemplateException for error diagnostics; pass token.Id
  from TokenProcessor error sites; preserve TemplateException re-throw in parser
- Add 17 new tests: edge cases (unmatched blocks, invalid identifiers, malformed
  expressions), token style variants (SingleBrace, DollarBrace, PoundBrace),
  and thread safety (concurrent caching, reset during concurrent use)
- Add XML documentation to all public API types and members

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: bfarmer67

src/Hyperbee.Templating/Compiler/MethodInvoker.cs

@@ -1,14 +1,20 @@
-
+
 namespace Hyperbee.Templating.Compiler;
 
+/// <summary>Defines a method that can be invoked from within template expressions.</summary>
 public interface IMethodInvoker
 {
+    /// <summary>Invokes the method with the specified arguments.</summary>
+    /// <param name="args">The arguments to pass to the method.</param>
+    /// <returns>The result of the method invocation.</returns>
     object Invoke( params object[] args );
 }
 
+/// <summary>Wraps a delegate as an <see cref="IMethodInvoker"/> for use in template expressions.</summary>
 public sealed class MethodInvoker( Func<object[], object> invoker ) : IMethodInvoker
 {
     private readonly Func<object[], object> _invoker = invoker ?? throw new ArgumentNullException( nameof( invoker ) );
 
+    /// <inheritdoc />
     public object Invoke( params object[] args ) => _invoker( args );
 }

src/Hyperbee.Templating/Compiler/RoslynTokenExpressionProvider.cs

@@ -34,7 +34,7 @@ private sealed class RuntimeContext( ImmutableArray<MetadataReference> metadataR
         public DynamicAssemblyLoadContext AssemblyLoadContext { get; } = new( metadataReferences );
     }
 
-    private static RuntimeContext __runtimeContext = new( MetadataReferences );
+    private static volatile RuntimeContext __runtimeContext = new( MetadataReferences );
     private static int __counter;
 
     private static readonly CSharpCompilationOptions CompilationOptions =
@@ -43,15 +43,16 @@ private sealed class RuntimeContext( ImmutableArray<MetadataReference> metadataR
     [MethodImpl( MethodImplOptions.AggressiveInlining )]
     public TokenExpression GetTokenExpression( string codeExpression, MemberDictionary members )
     {
-        return __runtimeContext.TokenExpressions.GetOrAdd( codeExpression, Compile( codeExpression, members ) );
+        var context = __runtimeContext;
+        return context.TokenExpressions.GetOrAdd( codeExpression, _ => Compile( codeExpression, members, context ) );
     }
 
     public static void Reset()
     {
-        __runtimeContext = new RuntimeContext( MetadataReferences );
+        Interlocked.Exchange( ref __runtimeContext, new RuntimeContext( MetadataReferences ) );
     }
 
-    private static TokenExpression Compile( string codeExpression, MemberDictionary members )
+    private static TokenExpression Compile( string codeExpression, MemberDictionary members, RuntimeContext context )
     {
         // Create a shim to compile the expression
 
@@ -126,7 +127,7 @@ public static object Invoke( {{nameof( IReadOnlyMemberDictionary )}} members )
         }
 
         peStream.Seek( 0, SeekOrigin.Begin );
-        var assembly = __runtimeContext.AssemblyLoadContext.LoadFromStream( peStream );
+        var assembly = context.AssemblyLoadContext.LoadFromStream( peStream );
 
         var methodDelegate = assembly!
             .GetType( "TokenExpressionInvoker" )!

src/Hyperbee.Templating/Compiler/TokenExpression.cs

@@ -1,10 +1,18 @@
-using Hyperbee.Templating.Text;
+using Hyperbee.Templating.Text;
 
 namespace Hyperbee.Templating.Compiler;
 
+/// <summary>A delegate that evaluates a compiled token expression against a member dictionary.</summary>
+/// <param name="members">The read-only dictionary of template variables and methods.</param>
+/// <returns>The result of evaluating the expression.</returns>
 public delegate object TokenExpression( IReadOnlyMemberDictionary members );
 
+/// <summary>Provides compilation of token expressions for template evaluation.</summary>
 public interface ITokenExpressionProvider
 {
+    /// <summary>Compiles a code expression string into an executable <see cref="TokenExpression"/>.</summary>
+    /// <param name="codeExpression">The expression string to compile (e.g., a lambda expression).</param>
+    /// <param name="members">The member dictionary providing variable and method context.</param>
+    /// <returns>A compiled delegate that can be invoked to evaluate the expression.</returns>
     public TokenExpression GetTokenExpression( string codeExpression, MemberDictionary members );
 }

src/Hyperbee.Templating/Configure/MethodBuilder.cs

@@ -2,6 +2,7 @@
 
 namespace Hyperbee.Templating.Configure;
 
+/// <summary>Provides a fluent API for registering typed method delegates with template options.</summary>
 public class MethodBuilder( string name, TemplateOptions options )
 {
     public TemplateOptions Expression<TOutput>( Func<TOutput> func )

src/Hyperbee.Templating/Configure/TemplateOptions.cs

@@ -7,8 +7,11 @@
 
 namespace Hyperbee.Templating.Configure;
 
+/// <summary>Configuration options for template rendering, including variables, methods, and expression providers.</summary>
 public class TemplateOptions
 {
+    /// <summary>Creates a new <see cref="TemplateOptions"/> instance.</summary>
+    /// <returns>A new default options instance.</returns>
     public static TemplateOptions Create() => new();
 
     public IDictionary<string, IMethodInvoker> Methods { get; }

src/Hyperbee.Templating/Core/KeyHelper.cs

@@ -1,5 +1,8 @@
 namespace Hyperbee.Templating.Core;
 
+/// <summary>A delegate that validates whether a token identifier is well-formed.</summary>
+/// <param name="key">The token identifier to validate.</param>
+/// <returns><c>true</c> if the identifier is valid; otherwise, <c>false</c>.</returns>
 public delegate bool KeyValidator( ReadOnlySpan<char> key );
 
 internal static class KeyHelper

src/Hyperbee.Templating/Text/MemberDictionary.cs

@@ -4,12 +4,23 @@
 
 namespace Hyperbee.Templating.Text;
 
+/// <summary>A read-only view of template variables and methods available during expression evaluation.</summary>
 public interface IReadOnlyMemberDictionary : IReadOnlyDictionary<string, string>
 {
+    /// <summary>Gets a variable value converted to the specified type.</summary>
+    /// <typeparam name="TType">The target type to convert to.</typeparam>
+    /// <param name="name">The variable name.</param>
+    /// <returns>The converted value.</returns>
     public TType GetValueAs<TType>( string name ) where TType : IConvertible;
+
+    /// <summary>Invokes a registered method by name.</summary>
+    /// <param name="methodName">The method name.</param>
+    /// <param name="args">The arguments to pass to the method.</param>
+    /// <returns>The result of the method invocation.</returns>
     public object Invoke( string methodName, params object[] args );
 }
 
+/// <summary>Stores template variables and methods, providing dictionary-style access for token resolution.</summary>
 public class MemberDictionary : IReadOnlyMemberDictionary
 {
     protected internal IDictionary<string, string> Variables { get; }

src/Hyperbee.Templating/Text/Runtime/TemplateParser.cs

@@ -198,9 +198,13 @@ private void ParseTemplate( ref BufferManager bufferManager, TextReader reader,
             if ( state.Frames.Depth != 0 )
                 throw new TemplateException( "Missing end if, or end while." );
         }
+        catch ( TemplateException )
+        {
+            throw;
+        }
         catch ( Exception ex )
         {
-            throw new TemplateException( "Error processing template.", ex );
+            throw new TemplateException( $"Error processing template at token {state.NextTokenId}.", ex );
         }
         finally
         {

src/Hyperbee.Templating/Text/Runtime/TokenParser.cs

@@ -93,39 +93,7 @@ private TokenType ParseIfToken( ReadOnlySpan<char> span, ref TokenEvaluation tok
         if ( span.Length != 2 && !char.IsWhiteSpace( span[2] ) )
             return TokenType.Undefined;
 
-        // Remove the "if" prefix
-        span = span[2..].Trim();
-
-        if ( span.IsEmpty )
-            throw new TemplateException( "Invalid `if` statement. Missing identifier." );
-
-        var bang = false;
-
-        if ( span[0] == '!' )
-        {
-            bang = true;
-            span = span[1..].Trim();
-        }
-
-        var isFatArrow = span.IndexOfIgnoreDelimitedRanges( "=>", "\"" ) != -1;
-
-        if ( !isFatArrow && !_validateKey( span ) )
-            throw new TemplateException( "Invalid `if` statement. Invalid identifier in truthy expression." );
-
-        if ( bang && isFatArrow )
-            throw new TemplateException( "Invalid `if` statement. The '!' operator is not supported for token expressions." );
-
-        if ( isFatArrow )
-        {
-            tokenEvaluation = TokenEvaluation.Expression;
-            tokenExpression = span;
-        }
-        else
-        {
-            tokenEvaluation = bang ? TokenEvaluation.Falsy : TokenEvaluation.Truthy;
-            name = span;
-        }
-
+        ParseConditionalToken( span, 2, "if", ref tokenEvaluation, ref tokenExpression, ref name );
         return TokenType.If;
     }
 
@@ -153,11 +121,25 @@ private TokenType ParseWhileToken( ReadOnlySpan<char> span, ref TokenEvaluation
         if ( span.Length != 5 && !char.IsWhiteSpace( span[5] ) )
             return TokenType.Undefined;
 
-        // Remove the "while" prefix
-        span = span[5..].Trim();
+        ParseConditionalToken( span, 5, "while", ref tokenEvaluation, ref tokenExpression, ref name );
+        return TokenType.While;
+    }
+
+    private static TokenType ParseEndWhileToken( ReadOnlySpan<char> span )
+    {
+        if ( span.Length != 6 )
+            throw new TemplateException( "Invalid `/while` statement. Invalid characters." );
+
+        return TokenType.EndWhile;
+    }
+
+    private void ParseConditionalToken( ReadOnlySpan<char> span, int keywordLength, string keywordName,
+        ref TokenEvaluation tokenEvaluation, ref ReadOnlySpan<char> tokenExpression, ref ReadOnlySpan<char> name )
+    {
+        span = span[keywordLength..].Trim();
 
         if ( span.IsEmpty )
-            throw new TemplateException( "Invalid `while` statement. Missing identifier." );
+            throw new TemplateException( $"Invalid `{keywordName}` statement. Missing identifier." );
 
         var bang = false;
 
@@ -170,10 +152,10 @@ private TokenType ParseWhileToken( ReadOnlySpan<char> span, ref TokenEvaluation
         var isFatArrow = span.IndexOfIgnoreDelimitedRanges( "=>", "\"" ) != -1;
 
         if ( !isFatArrow && !_validateKey( span ) )
-            throw new TemplateException( "Invalid `while` statement. Invalid identifier in truthy expression." );
+            throw new TemplateException( $"Invalid `{keywordName}` statement. Invalid identifier in truthy expression." );
 
         if ( bang && isFatArrow )
-            throw new TemplateException( "Invalid `while` statement. The '!' operator is not supported for token expressions." );
+            throw new TemplateException( $"Invalid `{keywordName}` statement. The '!' operator is not supported for token expressions." );
 
         if ( isFatArrow )
         {
@@ -185,16 +167,6 @@ private TokenType ParseWhileToken( ReadOnlySpan<char> span, ref TokenEvaluation
             tokenEvaluation = bang ? TokenEvaluation.Falsy : TokenEvaluation.Truthy;
             name = span;
         }
-
-        return TokenType.While;
-    }
-
-    private static TokenType ParseEndWhileToken( ReadOnlySpan<char> span )
-    {
-        if ( span.Length != 6 )
-            throw new TemplateException( "Invalid `/while` statement. Invalid characters." );
-
-        return TokenType.EndWhile;
     }
 
     private TokenType ParseEachToken( ReadOnlySpan<char> span, ref TokenEvaluation tokenEvaluation, ref ReadOnlySpan<char> tokenExpression, ref ReadOnlySpan<char> name )

src/Hyperbee.Templating/Text/Runtime/TokenProcessor.cs

@@ -62,13 +62,13 @@ public TokenAction ProcessToken( TokenDefinition token, TemplateState state, out
                 return ProcessElseToken( frames, token );
 
             case TokenType.Endif:
-                return ProcessEndIfToken( frames );
+                return ProcessEndIfToken( frames, token );
 
             case TokenType.EndWhile:
-                return ProcessEndWhileToken( frames );
+                return ProcessEndWhileToken( frames, token );
 
             case TokenType.EndEach:
-                return ProcessEndEachToken( frames );
+                return ProcessEndEachToken( frames, token );
 
             case TokenType.Define:
                 return ProcessDefineToken( token );
@@ -149,16 +149,16 @@ private static TokenAction ProcessIfToken( TokenDefinition token, FrameStack fra
     private static TokenAction ProcessElseToken( FrameStack frames, TokenDefinition token )
     {
         if ( !frames.IsTokenType( TokenType.If ) )
-            throw new TemplateException( "Syntax error. Invalid `else` without matching `if`." );
+            throw new TemplateException( "Syntax error. Invalid `else` without matching `if`.", token.Id );
 
         frames.Push( token, !frames.IsTruthy );
         return TokenAction.Ignore;
     }
 
-    private static TokenAction ProcessEndIfToken( FrameStack frames )
+    private static TokenAction ProcessEndIfToken( FrameStack frames, TokenDefinition token )
     {
         if ( frames.Depth == 0 || !frames.IsTokenType( TokenType.If ) && !frames.IsTokenType( TokenType.Else ) )
-            throw new TemplateException( "Syntax error. Invalid `/if` without matching `if`." );
+            throw new TemplateException( "Syntax error. Invalid `/if` without matching `if`.", token.Id );
 
         if ( frames.IsTokenType( TokenType.Else ) )
             frames.Pop(); // pop the else
@@ -174,10 +174,10 @@ private static TokenAction ProcessWhileToken( TokenDefinition token, FrameStack
         return TokenAction.Ignore;
     }
 
-    private TokenAction ProcessEndWhileToken( FrameStack frames )
+    private TokenAction ProcessEndWhileToken( FrameStack frames, TokenDefinition token )
     {
         if ( frames.Depth == 0 || !frames.IsTokenType( TokenType.While ) )
-            throw new TemplateException( "Syntax error. Invalid `/while` without matching `while`." );
+            throw new TemplateException( "Syntax error. Invalid `/while` without matching `while`.", token.Id );
 
         var whileToken = frames.Peek().Token;
 
@@ -217,10 +217,10 @@ private TokenAction ProcessEachToken( TokenDefinition token, FrameStack frames,
         return TokenAction.Ignore;
     }
 
-    private TokenAction ProcessEndEachToken( FrameStack frames )
+    private TokenAction ProcessEndEachToken( FrameStack frames, TokenDefinition token )
     {
         if ( frames.Depth == 0 || !frames.IsTokenType( TokenType.Each ) )
-            throw new TemplateException( "Syntax error. Invalid /each without matching each." );
+            throw new TemplateException( "Syntax error. Invalid /each without matching each.", token.Id );
 
         var frame = frames.Peek();
         var (currentName, enumerator) = frame.EnumeratorDefinition;