Lucewave

Lucewave is a multi-phase source generator pipeline orchestrator for .NET. It solves the fundamental limitation in Roslyn where source generators cannot see each other's outputs by enabling chainable, multi-phase code generation.

The Problem

In Roslyn's current model:

• Source generators run in an unordered manner
• Each generator only sees the original source code
• Generator A cannot consume types generated by Generator B
• This makes complex code generation scenarios (like "generate DTOs from OpenAPI, then generate validators for those DTOs") impossible

The Solution

Lucewave introduces phased execution:

1. Phase 1 generators run and produce output (e.g., contracts, DTOs, interfaces)
2. Those outputs are added to a new compilation
3. Phase 2 generators run against the enriched compilation
4. This continues for any number of phases

Features

• ✅ Multi-phase pipeline execution - Chain generators that depend on each other
• ✅ YAML configuration - Simple, declarative pipeline definition
• ✅ CLI tool - Run pipelines from command line or CI/CD
• ✅ MSBuild integration - Seamless Visual Studio and build integration
• ✅ Caching - Incremental rebuilds based on input hashing
• ✅ Generator discovery - Automatic detection of generators in assemblies
• ✅ Pipeline SDK - Attributes for generator authors to declare dependencies
• ✅ Detailed reporting - Execution times, generated files, and diagnostics

Quick Start

1. Install the CLI tool

dotnet tool install -g Lucewave.Cli

2. Initialize a pipeline configuration

lucewave init

This creates a generator-pipeline.yml file:

phases:
  - name: contracts
    generators:
      - MyCompany.OpenApi.Generator
  
  - name: implementations
    generators:
      - MyCompany.DtoMapper.Generator
      - MyCompany.Validator.Generator

options:
  outputRoot: obj/gen
  cache: true

3. Run the pipeline

lucewave run

MSBuild Integration

Add the NuGet package to your project:

<PackageReference Include="Lucewave.MsBuild" Version="1.0.0" />

The pipeline will automatically run before compilation when a generator-pipeline.yml file exists.

Configuration via MSBuild Properties

<PropertyGroup>
  <LucewaveConfig>custom-pipeline.yml</LucewaveConfig>
  <LucewaveOutputRoot>$(IntermediateOutputPath)generated</LucewaveOutputRoot>
  <LucewaveEnableCache>true</LucewaveEnableCache>
</PropertyGroup>

Configuration Reference

Full Configuration Example

phases:
  - name: contracts
    generators:
      - OpenApi.Generator
      - Protobuf.Generator
    phaseOptions:
      cache: true
      outputDir: contracts
  
  - name: implementations
    generators:
      - Dapper.Generator
      - AutoMapper.Generator
    phaseOptions:
      cache: true
      outputDir: implementations
  
  - name: clients
    generators:
      - Refit.Generator
      - HttpClient.Generator
    phaseOptions:
      cache: true
      outputDir: clients

options:
  outputRoot: obj/gen
  cache: true
  parallel: false
  verbosity: normal
  continueOnError: false

Options

Option	Type	Default	Description
outputRoot	string	obj/gen	Root directory for generated files
cache	boolean	true	Enable caching across phases
parallel	boolean	false	Enable parallel execution within phases
verbosity	enum	normal	Logging verbosity (quiet, minimal, normal, detailed, diagnostic)
continueOnError	boolean	false	Continue pipeline on generator errors

SDK for Generator Authors

Lucewave provides an SDK for generator authors to declare their phase preferences and dependencies:

using Lucewave.Sdk;

[GeneratorPhase(1, PhaseName = "contracts")]
[Consumes("OpenApiSpec")]
[Produces("IApiClient")]
[DependsOnGenerator("OpenApi.Generator")]
public class MyGenerator : IIncrementalGenerator
{
    // ...
}

Generator Manifest

Generators can include a LucewaveManifest.json file:

{
  "packageId": "MyCompany.MyGenerator",
  "manifestVersion": "1.0",
  "preferredPhase": 1,
  "outputCategory": "Contracts",
  "inputs": ["OpenApiSpec", "IEntity"],
  "outputs": ["IApiClient", "EntityDto"],
  "dependsOn": ["OpenApi.Generator"]
}

Architecture

┌─────────────────────────────────────────────────────────────┐
│                     Lucewave                            │
├─────────────────────────────────────────────────────────────┤
│  CLI / MSBuild Task                                          │
│  ├── Configuration Parser (YAML)                             │
│  ├── Pipeline Executor                                       │
│  │   ├── Phase 1: Run generators → Save output              │
│  │   ├── Phase 2: Load previous + Run → Save output         │
│  │   └── Phase N: Continue...                                │
│  ├── Generator Discovery                                     │
│  ├── Caching (SHA256-based)                                  │
│  └── Diagnostics & Reporting                                 │
└─────────────────────────────────────────────────────────────┘

CLI Commands

# Run the pipeline
lucewave run [options]
  -c, --config <file>    Configuration file (default: generator-pipeline.yml)
  -p, --project <dir>    Project directory (default: current)
  -o, --output <dir>     Output directory
  -v, --verbose          Verbose output
  --no-cache             Disable caching

# Initialize configuration
lucewave init [options]
  -t, --template <name>  Template to use (basic, advanced)

# Cache management
lucewave cache clear

Building from Source

# Clone the repository
git clone https://github.com/Taiizor/Lucewave.git
cd Lucewave

# Build
dotnet build

# Run tests
dotnet test

Project Structure

├── src/
│   ├── Lucewave.Core/       # Core pipeline logic
│   ├── Lucewave.Cli/        # Command-line tool
│   ├── Lucewave.MsBuild/    # MSBuild integration
│   └── Lucewave.Sdk/        # SDK for generator authors
├── tests/
│   └── Lucewave.Tests/      # Unit tests
└── samples/                      # Sample projects

Roadmap

• NuGet package resolver for generator references
• Visual Studio extension for pipeline visualization
• F# and VB.NET project support
• Parallel phase execution
• Remote generator caching
• Language Server Protocol integration

Contributing

Contributions are welcome! Please read our contributing guidelines before submitting a pull request.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

This project was inspired by the ongoing discussions in the Roslyn community about chainable source generators and the "Two-Phase Incremental Generators" proposal.