C# Template API for pattern matching and code generation (#6916)

* C# Template API for structural pattern matching and code generation

Add an idiomatic C# template API using InterpolatedStringHandler that lets
recipe authors write concise pattern matching and code transformations:

  var expr = Capture.Of<Expression>("expr");
  var pat = CSharpPattern.Create($"Console.Write({expr})");
  var tmpl = CSharpTemplate.Create($"Console.WriteLine({expr})");

Core types:
- Capture<T> / Capture.Of<T>() — typed capture placeholders
- TemplateStringHandler — InterpolatedStringHandler intercepting {holes}
- CSharpPattern — structural matching with Find() for search markers
- CSharpTemplate — code generation via Apply()
- MatchResult — typed dictionary of captured subtrees
- PatternMatchingComparator — parallel tree walk for structural comparison
- TemplateEngine — parse/cache template code snippets

Covers expressions (method invocation, binary, unary, ternary, assignment,
new, cast, array access, lambda, literals), statements (return, throw, if,
while, do-while, foreach, switch, try-catch), and C#-specific syntax
(default, sizeof, switch expressions, tuples, null-forgiving, is-pattern,
as-cast, compound assignment).

85 tests passing across 5 test classes.

* Convert TemplateApplyTests to RewriteRun with before/after assertions

Replace low-level FindFirst + Assert pattern with RewriteRun tests that
validate template replacements via before/after source text. Add tests for
multiple occurrences, binary replacement, throw replacement, new class
replacement, and Raw.Code splice.

Author: jkschneider

rewrite-csharp/csharp/OpenRewrite/CSharp/Template/CSharpCoordinates.cs

@@ -0,0 +1,55 @@
+/*
+ * Copyright 2026 the original author or authors.
+ * <p>
+ * Licensed under the Moderne Source Available License (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ * <p>
+ * https://docs.moderne.io/licensing/moderne-source-available-license
+ * <p>
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+using OpenRewrite.Java;
+
+namespace OpenRewrite.CSharp.Template;
+
+/// <summary>
+/// Specifies where and how to apply a template in the tree.
+/// </summary>
+public sealed class CSharpCoordinates
+{
+    public J Tree { get; }
+    public CoordinateMode Mode { get; }
+
+    private CSharpCoordinates(J tree, CoordinateMode mode)
+    {
+        Tree = tree;
+        Mode = mode;
+    }
+
+    /// <summary>
+    /// Replace the target tree element with the template result.
+    /// </summary>
+    public static CSharpCoordinates Replace(J tree) => new(tree, CoordinateMode.Replace);
+
+    /// <summary>
+    /// Insert the template result before the target tree element.
+    /// </summary>
+    public static CSharpCoordinates Before(J tree) => new(tree, CoordinateMode.Before);
+
+    /// <summary>
+    /// Insert the template result after the target tree element.
+    /// </summary>
+    public static CSharpCoordinates After(J tree) => new(tree, CoordinateMode.After);
+}
+
+public enum CoordinateMode
+{
+    Replace,
+    Before,
+    After
+}

rewrite-csharp/csharp/OpenRewrite/CSharp/Template/CSharpPattern.cs

@@ -0,0 +1,106 @@
+/*
+ * Copyright 2026 the original author or authors.
+ * <p>
+ * Licensed under the Moderne Source Available License (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ * <p>
+ * https://docs.moderne.io/licensing/moderne-source-available-license
+ * <p>
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+using OpenRewrite.Core;
+using OpenRewrite.Java;
+
+namespace OpenRewrite.CSharp.Template;
+
+/// <summary>
+/// A structural pattern for matching against C# AST nodes.
+/// Patterns are created using C# string interpolation with <see cref="Capture{T}"/> placeholders.
+/// </summary>
+/// <example>
+/// <code>
+/// var expr = Capture.Of&lt;Expression&gt;("expr");
+/// var pat = CSharpPattern.Create($"Console.Write({expr})");
+///
+/// if (pat.Match(methodInvocation, cursor) is { } match)
+/// {
+///     var capturedExpr = match.Get(expr);
+/// }
+/// </code>
+/// </example>
+public sealed class CSharpPattern
+{
+    private readonly string _code;
+    private readonly IReadOnlyDictionary<string, object> _captures;
+    private readonly IReadOnlyList<string> _usings;
+    private readonly IReadOnlyList<string> _context;
+    private J? _cachedTree;
+
+    private CSharpPattern(string code, Dictionary<string, object> captures,
+        IReadOnlyList<string>? usings, IReadOnlyList<string>? context)
+    {
+        _code = code;
+        _captures = captures;
+        _usings = usings ?? [];
+        _context = context ?? [];
+    }
+
+    /// <summary>
+    /// Create a pattern from an interpolated string containing <see cref="Capture{T}"/> placeholders.
+    /// </summary>
+    public static CSharpPattern Create(TemplateStringHandler handler,
+        IReadOnlyList<string>? usings = null, IReadOnlyList<string>? context = null)
+    {
+        return new CSharpPattern(handler.GetCode(), handler.GetCaptures(), usings, context);
+    }
+
+    /// <summary>
+    /// Create a pattern from a plain string (no captures — useful for exact matching).
+    /// </summary>
+    public static CSharpPattern Create(string code,
+        IReadOnlyList<string>? usings = null, IReadOnlyList<string>? context = null)
+    {
+        return new CSharpPattern(code, new Dictionary<string, object>(), usings, context);
+    }
+
+    /// <summary>
+    /// Get the parsed pattern tree (cached after first parse).
+    /// </summary>
+    public J GetTree()
+    {
+        return _cachedTree ??= TemplateEngine.Parse(_code, _captures, _usings, _context);
+    }
+
+    /// <summary>
+    /// Match this pattern against an AST node.
+    /// Returns a <see cref="MatchResult"/> if matched, null otherwise.
+    /// </summary>
+    public MatchResult? Match(J tree, Cursor cursor)
+    {
+        var patternTree = GetTree();
+        var comparator = new PatternMatchingComparator(_captures);
+        var captured = comparator.Match(patternTree, tree, cursor);
+        return captured != null ? new MatchResult(captured) : null;
+    }
+
+    /// <summary>
+    /// Check if this pattern matches (without capturing).
+    /// </summary>
+    public bool Matches(J tree, Cursor cursor) => Match(tree, cursor) != null;
+
+    /// <summary>
+    /// If this pattern matches the given tree node, return the node with a
+    /// <see cref="SearchResult"/> marker added. Otherwise return the node unchanged.
+    /// This is the search-only equivalent of template apply — it marks found
+    /// syntax so that <c>/*~~&gt;*/</c> appears in printed output.
+    /// </summary>
+    public T Find<T>(T tree, Cursor cursor, string? description = null) where T : J
+    {
+        return Match(tree, cursor) != null ? SearchResult.Found(tree, description) : tree;
+    }
+}

rewrite-csharp/csharp/OpenRewrite/CSharp/Template/CSharpTemplate.cs

@@ -0,0 +1,119 @@
+/*
+ * Copyright 2026 the original author or authors.
+ * <p>
+ * Licensed under the Moderne Source Available License (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ * <p>
+ * https://docs.moderne.io/licensing/moderne-source-available-license
+ * <p>
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+using OpenRewrite.Core;
+using OpenRewrite.Java;
+
+namespace OpenRewrite.CSharp.Template;
+
+/// <summary>
+/// A parsed and cacheable template for generating C# AST nodes.
+/// Templates are created using C# string interpolation with <see cref="Capture{T}"/> placeholders,
+/// providing the C# equivalent of JavaScript's tagged template literals.
+/// </summary>
+/// <example>
+/// <code>
+/// // Simple template (no captures)
+/// var tmpl = CSharpTemplate.Create($"Console.WriteLine(\"hello\")");
+/// var result = tmpl.Apply(cursor);
+///
+/// // Template with captures from pattern match
+/// var expr = Capture.Of&lt;Expression&gt;("expr");
+/// var tmpl = CSharpTemplate.Create($"Console.WriteLine({expr})");
+/// var result = tmpl.Apply(cursor, values: match);
+///
+/// // Template with usings
+/// var tmpl = CSharpTemplate.Create(
+///     $"JsonSerializer.Serialize({expr})",
+///     usings: ["System.Text.Json"]);
+/// </code>
+/// </example>
+public sealed class CSharpTemplate
+{
+    private readonly string _code;
+    private readonly IReadOnlyDictionary<string, object> _captures;
+    private readonly IReadOnlyList<string> _usings;
+    private readonly IReadOnlyList<string> _context;
+    private J? _cachedTree;
+
+    private CSharpTemplate(string code, Dictionary<string, object> captures,
+        IReadOnlyList<string>? usings, IReadOnlyList<string>? context)
+    {
+        _code = code;
+        _captures = captures;
+        _usings = usings ?? [];
+        _context = context ?? [];
+    }
+
+    /// <summary>
+    /// Create a template from an interpolated string containing <see cref="Capture{T}"/>
+    /// and/or <see cref="Raw"/> placeholders.
+    /// </summary>
+    public static CSharpTemplate Create(TemplateStringHandler handler,
+        IReadOnlyList<string>? usings = null, IReadOnlyList<string>? context = null)
+    {
+        return new CSharpTemplate(handler.GetCode(), handler.GetCaptures(), usings, context);
+    }
+
+    /// <summary>
+    /// Create a template from a plain string (no captures).
+    /// </summary>
+    public static CSharpTemplate Create(string code,
+        IReadOnlyList<string>? usings = null, IReadOnlyList<string>? context = null)
+    {
+        return new CSharpTemplate(code, new Dictionary<string, object>(), usings, context);
+    }
+
+    /// <summary>
+    /// Get the parsed template tree (cached after first parse).
+    /// </summary>
+    public J GetTree()
+    {
+        return _cachedTree ??= TemplateEngine.Parse(_code, _captures, _usings, _context);
+    }
+
+    /// <summary>
+    /// Apply this template, substituting captured values from a <see cref="MatchResult"/>
+    /// and returning the generated AST node.
+    /// </summary>
+    /// <param name="cursor">The cursor pointing to the current location in the tree.</param>
+    /// <param name="values">Optional match result providing values for captures.</param>
+    /// <param name="coordinates">Optional coordinates specifying where to apply (defaults to Replace).</param>
+    /// <returns>The generated AST node with substitutions applied.</returns>
+    public J? Apply(Cursor cursor, MatchResult? values = null,
+        CSharpCoordinates? coordinates = null)
+    {
+        var tree = GetTree();
+
+        // Phase 1: placeholder substitution
+        if (values != null)
+        {
+            tree = TemplateEngine.ApplySubstitutions(tree, values);
+        }
+
+        // Phase 2: coordinate application (prefix preservation)
+        if (coordinates != null)
+        {
+            tree = TemplateEngine.ApplyCoordinates(tree, cursor, coordinates);
+        }
+        else if (cursor.Value is J cursorValue)
+        {
+            tree = TemplateEngine.ApplyCoordinates(tree, cursor,
+                CSharpCoordinates.Replace(cursorValue));
+        }
+
+        return tree;
+    }
+}

rewrite-csharp/csharp/OpenRewrite/CSharp/Template/Capture.cs

@@ -0,0 +1,83 @@
+/*
+ * Copyright 2026 the original author or authors.
+ * <p>
+ * Licensed under the Moderne Source Available License (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ * <p>
+ * https://docs.moderne.io/licensing/moderne-source-available-license
+ * <p>
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+using OpenRewrite.Core;
+using OpenRewrite.Java;
+
+namespace OpenRewrite.CSharp.Template;
+
+/// <summary>
+/// A named placeholder for pattern matching and template substitution.
+/// When used in an interpolated string passed to <see cref="CSharpTemplate.Create"/>
+/// or <see cref="CSharpPattern.Create"/>, the <see cref="TemplateStringHandler"/>
+/// intercepts it and registers the capture automatically.
+/// </summary>
+/// <typeparam name="T">The type of AST node this capture matches.</typeparam>
+public sealed class Capture<T> where T : J
+{
+    public string Name { get; }
+    public bool IsVariadic { get; }
+    public int? MinCount { get; }
+    public int? MaxCount { get; }
+    public Func<T, Cursor, bool>? Constraint { get; }
+
+    internal Capture(string name, bool variadic = false,
+        int? minCount = null, int? maxCount = null,
+        Func<T, Cursor, bool>? constraint = null)
+    {
+        Name = name;
+        IsVariadic = variadic;
+        MinCount = minCount;
+        MaxCount = maxCount;
+        Constraint = constraint;
+    }
+
+    /// <summary>
+    /// Returns the placeholder identifier for this capture.
+    /// Used by <see cref="TemplateStringHandler"/> and as a defense-in-depth
+    /// fallback when used in a plain string interpolation.
+    /// </summary>
+    public override string ToString() => Placeholder.ToPlaceholder(Name);
+}
+
+/// <summary>
+/// Factory methods for creating captures.
+/// </summary>
+public static class Capture
+{
+    private static int _counter;
+
+    /// <summary>
+    /// Create a capture that matches a single AST node of type <typeparamref name="T"/>.
+    /// </summary>
+    public static Capture<T> Of<T>(string? name = null) where T : J
+        => new(name ?? $"_capture_{Interlocked.Increment(ref _counter)}");
+
+    /// <summary>
+    /// Create a variadic capture that matches zero or more elements.
+    /// Useful for matching argument lists, statement sequences, etc.
+    /// </summary>
+    public static Capture<T> Variadic<T>(string? name = null,
+        int? min = null, int? max = null) where T : J
+        => new(name ?? $"_capture_{Interlocked.Increment(ref _counter)}",
+            variadic: true, minCount: min, maxCount: max);
+
+    /// <summary>
+    /// Create a capture with a constraint predicate that must be satisfied for matching.
+    /// </summary>
+    public static Capture<T> WithConstraint<T>(string name,
+        Func<T, Cursor, bool> constraint) where T : J
+        => new(name, constraint: constraint);
+}