How m31coding/m31.fluentapi works
Project Type and Purpose
• This is an open‑source .NET library and toolset for automatically generating “fluent” builder APIs at compile time. It leverages Roslyn incremental source generators to inspect your annotated C# classes and emit builder code following the builder pattern (stepwise object construction).
• Key outcomes: consumer projects reference only the attribute library (M31.FluentApi), the generator (M31.FluentApi.Generator) integrates into the compiler, tests verify both analyzers and generated code, and example/storybook projects demonstrate usage.
Top‑Level Components
A. Attribute Library (“M31.FluentApi”)
• Contains all attribute definitions (FluentApiAttribute, FluentMemberAttribute, etc.)
• Referenced by consumer code, the generator, and storybook/demo apps.
B. Source Generator (“M31.FluentApi.Generator”)
• Implements Roslyn incremental source generation with three sub‑layers:
1. SourceAnalyzers: diagnostics and code fixes for attribute misuse.
2. CodeBuilding: building abstract code models (ICode, CodeBuilder, CodeFile).
3. CodeGeneration: orchestrates CodeBoardActors and CodeBoardElements to transform models into C# source files.
C. Test Suite (“M31.FluentApi.Tests”)
• AnalyzerAndCodeFixes: unit tests for diagnostics and code‑fix providers.
• CodeGeneration: tests that input classes produce correct output .g.cs files.
• Components: unit tests for core algorithms (e.g. Tarjan’s SCC).
D. Example and Storybook
• ExampleProject: a console app showing how to annotate POCOs and consume generated APIs.
• M31.FluentApi.Storybook: step‑by‑step code samples in C# guiding new users.
E. Build & CI
• ci.yml in .github/workflows: compiles all projects, runs tests, ensures generator runs under incremental compilation.
• Helper scripts (find-generated-files.sh, delete-generated-files.sh) for managing emitted code.
Data & Dependency Flows
• Consumer code (ExampleProject or any user project) references the attribute library and includes [FluentApi] annotations.
• During compilation MSBuild invokes M31.FluentApi.Generator as a Roslyn source generator.
• The generator’s SourceGenerator analyzes syntax trees → creates SymbolInfo → populates a CodeBoard (using CodeBoardActors) → CodeBuilder builds CodeFile representations → generator emits .g.cs into the compilation.
• The compiler picks up generated code, compiles both user and generated code into the final assembly.
• Tests drive both the analyzer stage (verifying diagnostics) and the generator stage (verifying emitted code matches expectations).
• Storybook and ExampleProject run as normal console apps, consuming the generated builder classes at runtime.
Architectural Patterns and Principles
• Roslyn Incremental Generator: separation of syntax analysis, symbol analysis, and code emission for performance.
• Builder Design Pattern: each generated API is a stepwise builder interface.
• Modularity: generator is split into clear functional areas (analyzers, code building, code generation).
• Test‑Driven Approach: every feature of the generator and analyzer has corresponding unit tests.
• Low coupling: consumer projects need only attribute definitions and get code via the generator automatically.