Add Template Method pattern source generator

[Copilot]

Template Method Pattern Generator - Complete Implementation

Summary

Source generator for Template Method pattern with deterministic step ordering, lifecycle hooks, and async/await support. All tests passing (21 tests).

Latest Changes - Third PR Review Round

✅ Improved code consistency - Updated DetermineIfAsync to use IsCancellationToken helper method instead of inline checks at lines 406 and 419
✅ Fixed test assertion - Updated ImportWorkflowDemoTests to check for generic "Import failed" message instead of hardcoded "Import failed at validation stage"
✅ Updated TemplateErrorPolicy documentation - Changed HandleAndContinue docs to accurately state "suppress the exception (do not rethrow) and terminate the workflow" instead of misleading "continue execution with remaining steps"

Previous Changes - Second PR Review Round

✅ Fixed CancellationToken detection to use fully qualified type name
✅ Updated documentation to accurately reflect HandleAndContinue behavior
✅ Improved error message in ImportWorkflowDemo
✅ Refactored validation loops to use LINQ .Any()

Previous Changes - First PR Review Round

✅ Removed unused imports, PKTMP006 diagnostic
✅ Fixed ValueTask validation to distinguish non-generic from generic
✅ Added 5 new tests (21 total, all passing)
✅ Refactored loops to use explicit LINQ filtering
✅ Simplified if-else and foreach in examples

Core Features

• Deterministic step ordering
• Lifecycle hooks (BeforeAll, AfterAll, OnError)
• Async/await with non-generic ValueTask and CancellationToken
• Error handling with configurable policies
• Support for class, struct, record class, record struct
• 7 actionable diagnostics
• Zero runtime dependency

Known Issue

Generator not activating in Examples project (ForAttributeWithMetadataName configuration). Core functionality validated through comprehensive unit tests (21/21 passing). Test assertion fix will work when generator issue is resolved.

Original prompt

---

This section details on the original issue you should resolve

<issue_title>Generator: Create Template Method Pattern</issue_title>
<issue_description>## Summary

Add a source generator that produces a complete implementation of the Template Method pattern for consumer-defined workflows.

The generator lives in PatternKit.Generators and emits self-contained, readable C# with no runtime PatternKit dependency.

Primary goals:

• Define a canonical sequence of steps (the “template”).
• Allow consumers to override hooks and optional steps safely.
• Support sync + async flows (favoring ValueTask).
• Provide deterministic ordering, diagnostics, and testability.

---

Motivation / Problem

Template Method is commonly re-implemented as:

• base classes with virtual methods (inheritance tax)
• ad-hoc pipelines with no clear contract for overrides
• scattered hooks with inconsistent error handling

We want a declarative, boilerplate-free way to define a workflow that:

• makes step order explicit
• makes override points explicit
• is friendly to records/immutability
• is reflection-free and generator-deterministic

---

Supported Targets (must-have)

The generator must support:

• partial class
• partial struct
• partial record class
• partial record struct

The annotated type represents the workflow host (the place consumers call Execute/ExecuteAsync).

---

Proposed User Experience

Minimal template with required steps

[Template]
public partial class ImportWorkflow
{
    [TemplateStep(Order = 0)]
    private void Validate(ImportContext ctx);

    [TemplateStep(Order = 1)]
    private void Transform(ImportContext ctx);

    [TemplateStep(Order = 2)]
    private void Persist(ImportContext ctx);
}

Generated (representative shape):

• Execute(ImportContext ctx) invokes steps in deterministic order.
• ExecuteAsync(ImportContext ctx, CancellationToken ct = default) emitted when async steps/hooks exist or ForceAsync=true.

Hooks + error handling

[Template(GenerateAsync = true)]
public partial class ImportWorkflow
{
    [TemplateHook(HookPoint.BeforeAll)]
    private void OnStart(ImportContext ctx);

    [TemplateStep(0)]
    private ValueTask ValidateAsync(ImportContext ctx, CancellationToken ct);

    [TemplateStep(1)]
    private void Transform(ImportContext ctx);

    [TemplateHook(HookPoint.OnError)]
    private void OnError(ImportContext ctx, Exception ex);

    [TemplateHook(HookPoint.AfterAll)]
    private void OnComplete(ImportContext ctx);
}

---

Attributes / Surface Area

Namespace: PatternKit.Generators.Template

Core attributes

• [Template] on the workflow host
• [TemplateStep] on methods that form the required step sequence
• [TemplateHook] on methods that plug into hook points

Suggested shapes:

TemplateAttribute

• string ExecuteMethodName = "Execute"
• string ExecuteAsyncMethodName = "ExecuteAsync"
• bool GenerateAsync (default: inferred)
• bool ForceAsync (default: false)
• TemplateErrorPolicy ErrorPolicy (default: Rethrow)

TemplateStepAttribute

• int Order (required in v1)
• bool Optional (default: false)
• string? Name (optional; for diagnostics)

TemplateHookAttribute

• HookPoint HookPoint (BeforeAll, AfterAll, OnError)
• int? StepOrder (reserved for v2: BeforeStep/AfterStep targeting)

---

Step Semantics

• Steps execute in ascending Order.
• Duplicate orders are errors.
• Steps are invoked exactly once unless marked optional and suppressed (v2). In v1, Optional only affects error-policy eligibility.

Async rules

• If any step/hook returns ValueTask or accepts CancellationToken, generator emits async path.
• Sync Execute can exist alongside async ExecuteAsync.
• Generated async APIs use ValueTask.

Error rules

• Default: throw after invoking OnError (if present).
• If ErrorPolicy = HandleAndContinue, only allowed when all remaining steps are optional. Otherwise emit diagnostic.

---

Diagnostics (must-have)

Stable IDs, actionable:

• PKTMP001 Type marked [Template] must be partial.
• PKTMP002 No [TemplateStep] methods found.
• PKTMP003 Duplicate step order detected.
• PKTMP004 Step method signature invalid.
• PKTMP005 Hook method signature invalid.
• PKTMP006 Mixed sync/async signatures not supported (explain required shapes).
• PKTMP007 CancellationToken required for async step but missing.
• PKTMP008 HandleAndContinue not allowed when non-optional steps remain.

---

Generated Code Layout

• TypeName.Template.g.cs

Deterministic ordering:

• steps ordered by Order, then by fully-qualified method name for tie-breaking in diagnostics.

---

Testing Expectations

• Deterministic ordering with multiple steps.
• Hooks fire at correct points.
• Error behavior: OnError invoked; default rethrow policy enforced.
• Async path uses ValueTask and respects cancellation....

• Fixes Generator: Create Template Method Pattern #47

---

✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.

[github-actions]

⚠️ Deprecation Warning: The deny-licenses option is deprecated for possible removal in the next major release. For more information, see issue 997.

Dependency Review

✅ No vulnerabilities or license issues or OpenSSF Scorecard issues found.

Scanned Files

None

[github-actions]

Test Results

313 tests   313 ✅  1m 27s ⏱️
  1 suites    0 💤
  1 files      0 ❌

Results for commit 699b33d.

♻️ This comment has been updated with latest results.

[github-actions]

🔍 PR Validation Results

Version: ``

✅ Validation Steps

• Build solution
• Run tests
• Build documentation
• Dry-run NuGet packaging

📊 Artifacts

Dry-run artifacts have been uploaded and will be available for 7 days.

---

This comment was automatically generated by the PR validation workflow.

[codecov]

Codecov Report

❌ Patch coverage is 78.30882% with 118 lines in your changes missing coverage. Please review.
✅ Project coverage is 82.49%. Comparing base (461ad82) to head (699b33d).

Files with missing lines	Patch %	Lines
src/PatternKit.Generators/TemplateGenerator.cs	78.41%	56 Missing and 23 partials ⚠️
.../TemplateMethodGeneratorDemo/ImportWorkflowDemo.cs	83.54%	10 Missing and 3 partials ⚠️
...TemplateMethodGeneratorDemo/OrderProcessingDemo.cs	87.95%	8 Missing and 2 partials ⚠️
...ors.Abstractions/Template/TemplateStepAttribute.cs	0.00%	6 Missing ⚠️
...erators.Abstractions/Template/TemplateAttribute.cs	0.00%	5 Missing ⚠️
...ors.Abstractions/Template/TemplateHookAttribute.cs	0.00%	5 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #104      +/-   ##
==========================================
- Coverage   82.61%   82.49%   -0.13%     
==========================================
  Files         169      175       +6     
  Lines       16150    16694     +544     
  Branches     2273     2367      +94     
==========================================
+ Hits        13343    13771     +428     
- Misses       2207     2296      +89     
- Partials      600      627      +27     

Flag	Coverage Δ
unittests	82.49% <78.30%> (-0.13%)	⬇️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[Copilot]

Pull request overview

This PR implements an incremental source generator for the Template Method pattern that generates Execute/ExecuteAsync methods from declarative workflow definitions with ordered steps and lifecycle hooks.

Changes:

• Adds Template Method pattern generator with support for sync/async workflows, deterministic step ordering, and lifecycle hooks (BeforeAll, AfterAll, OnError)
• Introduces attribute-based API ([Template], [TemplateStep], [TemplateHook]) with configurable error handling policies
• Includes comprehensive unit tests (16 tests), BDD-style integration tests, real-world examples, and complete documentation

Reviewed changes

Copilot reviewed 13 out of 13 changed files in this pull request and generated 17 comments.

Show a summary per file

File	Description
src/PatternKit.Generators/TemplateGenerator.cs	Core incremental generator implementation with 8 diagnostics, signature validation, and code generation for sync/async execution methods
src/PatternKit.Generators.Abstractions/Template/*.cs	Attribute definitions for Template, TemplateStep, TemplateHook, HookPoint enum, and TemplateErrorPolicy enum
test/PatternKit.Generators.Tests/TemplateGeneratorTests.cs	Comprehensive unit tests covering basic templates, hooks, async patterns, type targets, and diagnostics
test/PatternKit.Examples.Tests/TemplateMethodGeneratorDemo/*.cs	BDD-style integration tests for ImportWorkflow and OrderProcessing examples
src/PatternKit.Examples/TemplateMethodGeneratorDemo/*.cs	Real-world examples demonstrating data import pipeline and async order processing workflows
docs/generators/template-method-generator.md	Complete documentation with quick start, real-world examples, configuration options, and migration guide
docs/generators/toc.yml	Table of contents update to include Template Method generator documentation

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[JerrettDavis]

@copilot apply changes based on the comments in this thread

[Copilot]

Pull request overview

Copilot reviewed 13 out of 13 changed files in this pull request and generated 8 comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[JerrettDavis]

@copilot apply changes based on the comments in this thread

[Copilot]

Pull request overview

Copilot reviewed 13 out of 13 changed files in this pull request and generated 4 comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[JerrettDavis]

@copilot apply changes based on the comments in this thread

[JerrettDavis]

@copilot apply changes based on the comments in this thread

[Copilot]

Pull request overview

Copilot reviewed 13 out of 13 changed files in this pull request and generated no new comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.