C#: Scaffold strategies for class members and attributes in template engine

[knutwannheden]

Summary

• Add ScaffoldKind enum (Expression, Statement, ClassMember, Attribute) to control how template code is wrapped and extracted
• Add factory methods Expression(), Statement(), ClassMember(), Attribute() on both CSharpTemplate and CSharpPattern
• Keep Create() for backward compatibility (auto-unwraps ExpressionStatement)

Previously the template engine only supported expression/statement context (wrapping in a method body). This adds purpose-built scaffolds so class members, attributes, and standalone expressions can be templated with correct AST structure and type attribution.

Usage examples

// Expression — scaffolds as: class __T__ { object __v__ = <code>; }
var tmpl = CSharpTemplate.Expression("1 + 2");
var tree = tmpl.GetTree(); // Binary

// Statement — scaffolds in method body, does NOT auto-unwrap ExpressionStatement
var tmpl = CSharpTemplate.Statement("throw new Exception()");
var tree = tmpl.GetTree(); // Throw

// ClassMember — scaffolds as: class __T__ { <code> }
var tmpl = CSharpTemplate.ClassMember("public void Foo() { }");
var tree = tmpl.GetTree(); // MethodDeclaration

var tmpl = CSharpTemplate.ClassMember("public string Name { get; set; }");
var tree = tmpl.GetTree(); // PropertyDeclaration

// Attribute — scaffolds as: class __T__ { [<code>] void __M__() {} }
// Extracts the Annotation node with full type attribution
var tmpl = CSharpTemplate.Attribute("Obsolete(\"Use new API\")",
    usings: ["System"]);
var tree = tmpl.GetTree(); // Annotation

// Pattern matching works the same way
var pat = CSharpPattern.Attribute("Obsolete");
if (pat.Match(someAnnotation, cursor) is { } match) { ... }

// Captures work in all scaffold kinds
var name = Capture.Name("name");
var tmpl = CSharpTemplate.ClassMember($"public void {name}() {{ }}");

Key design decisions

• ScaffoldKind is internal — consumers use the factory methods
• Create() unchanged: uses null scaffold kind → legacy auto-unwrap path
• Statement() does NOT auto-unwrap ExpressionStatement (unlike Create())
• Expression scaffold uses object __v__ (not var) to handle null/default
• ClassMember auto-appends ; when code doesn't end with ; or }
• Cache key includes scaffold kind to prevent collisions

Test plan

• 24 new tests in ScaffoldStrategyTests.cs covering all scaffold kinds
• Tests for both CSharpTemplate and CSharpPattern factory methods
• Cache isolation test (same code, different scaffold kinds → different AST)
• Statement vs Create unwrap contract documented in tests
• Expression with typed capture (regression test for preamble field bug)
• All 164 existing template tests still pass