Codegen Pipeline Guide

The codegen system transforms the shared FakeDeclaration model into Kotlin source files through a layered pipeline: Model (immutable AST) → Builder (DSL construction) → Renderer (string output).

Instructions

1. Understand the Pipeline

FakeDeclaration                            (from FIR; legacy IR also builds it)
        ↓
SpecToCodegenMapper                        (toCodegenSpecs → method/property specs)
        ↓
FakeGenerator / ConfigurationDslGenerator  (orchestrators)
        ↓
codeFile("pkg") { klass("...") { ... } }  (Builder DSL)
        ↓
CodeFile (immutable AST)                   (Model)
        ↓
CodeFile.renderTo(CodeBuilder)             (Renderer)
        ↓
Kotlin source string                       (written to test source set)

All codegen files live under codegen-runtime/src/main/kotlin/com/rsicarelli/fakt/codegen/.

2. Model Layer — codegen/model/CodeFile.kt

Single file, fully immutable value objects. Key types:

3. Builder Layer — codegen/builder/

Entry point: codeFile(packageName) { } — returns CodeFile. All builders use @CodeDsl marker.

CodeFileBuilder (top-level):

codeFile("com.example") {
    header = "Generated by Fakt"
    import("kotlinx.coroutines.flow.StateFlow")
    klass("FakeImpl") { /* ClassBuilder */ }
    function("fakeFactory") { /* FunctionBuilder */ }
    dataClass("CallData") { /* DataClassBuilder */ }
}

ClassBuilder — klass(name) { }:

klass("FakeUserServiceImpl") {
    public(); internal()
    typeParam("T", "Comparable<T>")
    implements("UserService")               // Simple supertype
    implements("Repository", "User")        // Generic supertype
    annotation("OptIn", "ExperimentalApi::class")
    constructorProperty("getBehavior", "(String) -> User?") { private(); defaultValue = "null" }
    region("Properties")
    property("count", "Int") { private(); mutable(); initializer = "0" }
    function("getUser") { override(); returns("User?"); expressionBody = "getBehavior(id)" }
    endRegion()
}

FunctionBuilder — function(name) { }:

function("getUser") {
    override(); suspend(); inline(); operator()
    receiver("MyType")
    typeParam("T", "Comparable<T>", reified = true)
    parameter("id", "String")
    parameter("count", "Int", defaultValue = "0")
    parameter("items", "String", vararg = true)
    returns("User?")
    compact = true                          // no blank line before next compact sibling
    body = "return getBehavior(id)"         // block body (multi-line: split on \n)
    expressionBody = "getBehavior(id)"      // = syntax (mutually exclusive with body)
    body { buildString { /* lambda */ } }   // builder pattern
}

PropertyBuilder — property(name, type) { }:

property("name", "String") {
    override(); private(); mutable()
    compact = true
    initializer = "\"default\""
    getter = "field.uppercase()"            // get() = ... or get() { ... } if multiline
    setter = "field = value"
}

DataClassBuilder — dataClass(name) { }:

dataClass("GetUserCall") {
    public()
    property("id", "String")
    property("includeDeleted", "Boolean")
}

4. Renderer Layer — codegen/renderer/

CodeBuilder — StringBuilder wrapper with indentation:

val cb = CodeBuilder(indentSize = 4)
cb.appendLine("val x = 1")           // auto-indented
cb.indent { appendLine("inner") }    // increments/decrements level
cb.block("class Foo") { ... }        // "class Foo {" + indented body + "}"
cb.build()                           // final string

Rendering.kt — extension functions: CodeFile.renderTo(builder), CodeFile.renderToString(), and render functions for each model type. Key behaviors:

• Unit return type omitted on expression bodies
• KDoc rendered before annotations
• Compact siblings skip blank lines between them
• Multi-line constructor properties when > 1
• Package segments with Kotlin keywords get backtick-escaped

5. Strategy Layer — codegen/strategy/

DefaultValueResolver — composes strategies in priority order:

To add a new default strategy: implement DefaultValueStrategy interface (supports() + defaultValue()), add to the list in DefaultValueResolver.

6. Extensions Layer — codegen/extensions/

Spec types bridging the FakeDeclaration model to builders:

Extension functions on builders (in separate files):

7. Generation Orchestrators — codegen/generator/ (mapper in codegen/analysis/)

ImplementationGenerator.generateImplementation() flow:

1. decl.toCodegenSpecs() → method and property specs
2. generateCompleteFake() → CodeFile (impl class)
3. generateFactoryFunctionCodeFile() → CodeFile (factory)
4. generateCallHistoryDeclarations() → List<CodeDeclaration> (appended to impl file)
5. Returns GeneratedFakeCode(implementationFile, factoryFunction)

8. Adding a New Generation Pattern

1. Define the output — what Kotlin code should be generated
2. Create spec (if needed) — add to codegen/extensions/ or extend existing specs
3. Add builder extensions — new functions on ClassBuilder or CodeFileBuilder
4. Wire into orchestrator — call from ImplementationGenerator or ConfigurationDslGenerator
5. Add default strategy (if needed) — implement DefaultValueStrategy, add to DefaultValueResolver
6. Test — verify with make publish-local && make test-sample

Related Skills

• feature-option — adding options that conditionally enable/disable generation
• compilation — validate that generated output compiles