FractalDataWorks.CodeBuilder.Abstractions 0.6.0-rc.1

FractalDataWorks.CodeBuilder.Abstractions

Core interfaces and contracts for the FractalDataWorks code generation framework. This package provides the foundational abstractions that enable flexible, extensible code generation capabilities.

Overview

This package contains interface definitions that form the contract layer for:

• Code Building: Fluent builder interfaces for generating source code constructs
• Code Parsing: Language-agnostic parsing capabilities for analyzing existing source code
• Code Generation: Template-based code generation with pluggable language support
• Syntax Tree Representation: Abstract syntax tree interfaces for code analysis
• Incremental Generation: Input tracking for efficient regeneration

Key Interfaces

Core Builder Interfaces

ICodeBuilder

From ICodeBuilder.cs:8-25:

public interface ICodeBuilder
{
    /// <summary>
    /// Builds the code and returns it as a string.
    /// </summary>
    /// <returns>The generated code.</returns>
    string Build();

    /// <summary>
    /// Gets the current indentation level.
    /// </summary>
    int IndentLevel { get; }

    /// <summary>
    /// Gets or sets the indentation string (default is 4 spaces).
    /// </summary>
    string IndentString { get; set; }
}

IClassBuilder

Fluent builder for generating class definitions. From IClassBuilder.cs:9-140:

• Namespace and using directives
• Access modifiers, inheritance, and generic type parameters
• Class modifiers (static, abstract, sealed, partial)
• Members (fields, properties, methods, constructors, nested classes)
• Attributes and XML documentation

IInterfaceBuilder

Specialized builder for interface definitions. From IInterfaceBuilder.cs:9-101:

• Interface inheritance and generic constraints
• Method and property signatures
• Event declarations
• Access modifiers and attributes

IMethodBuilder

Method generation with support for modifiers, parameters, generics, and bodies. From IMethodBuilder.cs:9-140.

IPropertyBuilder

Property generation supporting modern C# features. From IPropertyBuilder.cs:9-128:

• Auto-properties and custom getter/setter implementations
• Access modifiers for individual accessors
• Init-only setters and property initializers
• Expression body properties

IConstructorBuilder

Constructor generation. From IConstructorBuilder.cs:9-81:

• Parameter definitions with default values
• Base and this constructor chaining
• Static constructor support

IFieldBuilder

Field definition builder. From IFieldBuilder.cs:9-82:

• Field modifiers (static, readonly, const, volatile)
• Initializer expressions
• Preprocessor directive support

IEnumBuilder

Enumeration builder. From IEnumBuilder.cs:9-90:

• Underlying type specification
• Enum member definitions with explicit values
• Member-specific attributes and documentation

Code Analysis Interfaces

ICodeParser

From ICodeParser.cs:11-39:

public interface ICodeParser
{
    /// <summary>
    /// Gets the language this parser supports.
    /// </summary>
    string Language { get; }

    /// <summary>
    /// Parses the source code into a syntax tree.
    /// </summary>
    Task<IGenericResult<ISyntaxTree>> Parse(
        string sourceCode,
        string? filePath = null,
        CancellationToken cancellationToken = default);

    /// <summary>
    /// Validates the source code without building a full syntax tree.
    /// </summary>
    Task<IGenericResult> Validate(
        string sourceCode,
        CancellationToken cancellationToken = default);
}

ISyntaxTree

From ISyntaxTree.cs:9-62:

• Root: Access to the root syntax node
• HasErrors: Quick error detection
• FindNodes(): Query nodes by type
• GetNodeAtPosition(): Position-based node lookup
• GetErrors(): Enumeration of error nodes

ISyntaxNode

From ISyntaxNode.cs:9-80:

• Node metadata: Type, text content, position information
• Tree navigation: Parent, children, and descendant traversal
• Error detection and search capabilities

Language Registry Interface

ILanguageRegistry

From ILanguageRegistry.cs:9-53:

• Language discovery and supported file extensions
• Parser registration and retrieval
• Extension-to-language mapping

Code Generation Interface

ICodeGenerator

From ICodeGenerator.cs:9-49:

public interface ICodeGenerator
{
    string TargetLanguage { get; }
    string Generate(ISyntaxTree syntaxTree);
    string Generate(IClassBuilder classBuilder);
    string Generate(IInterfaceBuilder interfaceBuilder);
    string Generate(IEnumBuilder enumBuilder);
    string GenerateCompilationUnit(IEnumerable<ICodeBuilder> builders);
}

Incremental Generation Support

IInputInfoModel

From IInputInfoModel.cs:9-21:

public interface IInputInfoModel
{
    /// <summary>
    /// Gets a hash representing the current state of the model.
    /// </summary>
    string InputHash { get; }

    /// <summary>
    /// Writes the model state to a TextWriter for hash calculation.
    /// </summary>
    void WriteToHash(TextWriter writer);
}

InputHashCalculator

From InputHashCalculator.cs:11-38:

public static class InputHashCalculator
{
    public static string CalculateHash(IInputInfoModel inputInfoModel)
    {
        if (inputInfoModel == null)
        {
            throw new ArgumentNullException(nameof(inputInfoModel), "Input info cannot be null.");
        }

        using var stream = new MemoryStream();
        using var writer = new StreamWriter(stream, Encoding.UTF8);

        inputInfoModel.WriteToHash(writer);
        writer.Flush();

        stream.Position = 0;
        using var sha256 = SHA256.Create();
        var hashBytes = sha256.ComputeHash(stream);

        return Convert.ToBase64String(hashBytes);
    }
}

Usage Examples

Examples from the C# implementation test suite.

Basic Class Generation

From ClassBuilderTests.cs:338-368:

var builder = new ClassBuilder();
var field = new FieldBuilder().WithName("_name").WithType("string").AsReadOnly();
var property = new PropertyBuilder().WithName("Name").WithType("string").AsReadOnly();
var constructor = new ConstructorBuilder()
    .WithClassName("Person")
    .WithParameter("string", "name")
    .AddBodyLine("_name = name;");

var result = builder
    .WithNamespace("MyApp.Models")
    .WithUsings("System")
    .WithName("Person")
    .WithXmlDoc("Represents a person.")
    .WithField(field)
    .WithProperty(property)
    .WithConstructor(constructor)
    .Build();

Method with Generic Constraints

From MethodBuilderTests.cs:193-222:

var builder = new MethodBuilder();

var result = builder
    .WithGenericParameters("T")
    .WithGenericConstraint("T", "class", "new()")
    .Build();

// Assert
result.ShouldContain("where T : class, new()");

Method with Full Documentation

From MethodBuilderTests.cs:328-353:

var builder = new MethodBuilder();

var result = builder
    .WithName("Calculate")
    .WithReturnType("int")
    .WithAccessModifier("public")
    .WithParameter("int", "x")
    .WithParameter("int", "y")
    .WithXmlDoc("Calculates the sum.")
    .WithParamDoc("x", "First value")
    .WithParamDoc("y", "Second value")
    .WithReturnDoc("The sum")
    .WithAttribute("Pure")
    .AddBodyLine("return x + y;")
    .Build();

Dependencies

• FractalDataWorks.Results: Provides IGenericResult for consistent error handling
• Target Framework: netstandard2.0

Related Packages

• FractalDataWorks.CodeBuilder.CSharp: C# implementation of the builder interfaces
• FractalDataWorks.Results: Result types used throughout the API

Design Patterns

Builder Pattern

Method chaining for intuitive code construction with progressive disclosure of complexity.

Strategy Pattern

Language-specific implementations use pluggable parsers and configurable generation rules.

Composite Pattern

Syntax tree representation provides uniform node handling with recursive operations on nested structures.

Best Practices

1. Use the interface types (IClassBuilder, IMethodBuilder) rather than concrete implementations for flexibility
2. Chain builder methods for readable, fluent configuration
3. Handle parse results using the IGenericResult pattern for proper error handling
4. Implement IInputInfoModel for incremental generation scenarios to avoid unnecessary regeneration

Next Steps

• See FractalDataWorks.CodeBuilder.CSharp for the C# implementation
• See FractalDataWorks.Results for result handling patterns