Skip to content

rsicarelli/fakt / .claude/skills/codegen

codegen

Verified

Documents the Fakt code generation pipeline — immutable AST model, builder DSL, renderer, default value strategies, and extension functions. Use when modifying code generation, changing generated output, adding new generated patterns, understanding builders or renderers, adding a new default value strategy, or debugging generated output. Make sure to use this skill whenever generated Kotlin code needs to change — the pipeline has strict conventions (immutable AST, builder DSL, renderer separation) that must be followed even for small changes.

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:

TypePurpose
CodeFileRoot: package + imports + declarations
CodeDeclarationSealed: CodeClass, CodeDataClass, CodeFunction, CodeProperty
CodeMemberSealed: class body items (CodeFunction, CodeProperty, CodeComment, CodeRegionStart/End)
CodeClassClass with modifiers, supertypes, members, constructor properties
CodeDataClassData class with typed properties
CodeFunctionFunction with params, return type, body
CodePropertyProperty with initializer, getter/setter
CodeTypeSealed: Simple, Generic, Nullable, Lambda
CodeBlockSealed: Expression, Statements, Empty
CodeExpressionSealed: StringLiteral, NumberLiteral, Lambda, FunctionCall, Raw
CodeModifierEnum: PUBLIC, PRIVATE, INTERNAL, OVERRIDE, SUSPEND, INLINE, etc.
ConstructorPropertyConstructor parameter with optional default value

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:

PriorityStrategyHandles
1NullableDefaultStrategyT? → null
2PrimitiveDefaultStrategyString → "", Int → 0, Boolean → false, etc.
3StdlibDefaultStrategyUnit, Flow<T> → emptyFlow(), StateFlow<T> → MutableStateFlow(...), Result<T>
4CollectionDefaultStrategyList<T> → emptyList(), Map<K,V> → emptyMap(), Array<T>, Mutable*
fallbackerror"Type '...' requires explicit configuration..."

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:

SpecPurpose
MethodSpecMethod metadata: name, params, return type, suspend, operator, default behavior
PropertySpecProperty metadata: name, type, isStateFlow, isMutable, default behavior
AnnotationSpecAnnotation with OptIn detection
FactoryFunctionSpecFactory function metadata for fakeXxx {} generation

Extension functions on builders (in separate files):

FileFunctionsPurpose
FakeGenerator.ktgenerateCompleteFake()Main fake class generation
MethodExtensions.ktoverrideMethod(), overrideVarargMethod(), configureMethod()Method overrides + configure methods
PropertyExtensions.ktstateFlowProperty(), behaviorProperty(), suspendBehaviorProperty(), nullableBehaviorProperty(), nullableSuspendBehaviorProperty()Property overrides + behavior lambdas
CallTrackingExtensions.ktcallHistoryBackingField(), propertyGetterCallHistoryField(), propertySetterCallHistoryField()Call tracking fields
CallHistoryDsl.ktcallDataClass(), verifierClass(), unitVerifierClass(), verifyFunction(), unitVerifyFunction()Call history data classes + verifiers
CallHistoryGenerator.ktaddCallHistoryComponents(), generateCallHistoryDeclarations()Orchestrates all call history code
FactoryExtensions.ktgenerateFactoryFunctionCodeFile()fakeXxx {} factory function
TypeParamRegex.kteraseTypeParamsToAny(), typeContainsAnyParam()Generic type erasure utilities
HistoryStorageInfo.ktresolveHistoryStorageType()Resolves call history storage (unit vs data class)
KDocGenerator.ktKDoc generation utilitiesGenerated documentation for fakes
TypeParamsInfo.ktType parameter analysis helpersType parameter metadata extraction
VisibilityExtensions.ktVisibility mapping helpersFIR visibility to codegen modifier mapping

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

FileClassRole
analysis/SpecToCodegenMapper.kt—FakeDeclaration.toCodegenSpecs(), toRenderableMethodSpec(), toRenderablePropertySpec()
generator/ImplementationGenerator.ktImplementationGeneratorProduces FakeXxxImpl class + factory function + call history
generator/ConfigurationDslGenerator.ktConfigurationDslGeneratorProduces FakeXxxConfig DSL class

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
writing-skillsobra/superpowersUse when creating new skills, editing existing skills, or verifying skills work before deploymentStars: 319kUpdated Claude CodeCodexVerifiedInstall
xlsxanthropics/skillsUse this skill any time a spreadsheet file is the primary input or output. This means any task where the user wants to: open, read, edit, or fix an existing .xlsx, .xlsm, .xltx, .csv, or .tsv file (e.g., adding columns, computing formulas, formatting, charting, cleaning messy data); create a new spreadsheet from scratch or from other data sources; or convert between tabular file formats. Trigger especially when the user references a spreadsheet file by name or path — even casually (like "the xlsx in my downloads") — and wants something done to it or produced from it. Also trigger for cleaning or restructuring messy tabular data files (malformed rows, misplaced headers, junk data) into proper spreadsheets. The deliverable must be a spreadsheet file. Do NOT trigger when the primary deliverable is a Word document, HTML report, standalone Python script, database pipeline, or Google Sheets API integration, even if tabular data is involved.Stars: 196kUpdated Claude CodeCodexVerifiedInstall
shipping-and-launchaddyosmani/agent-skillsPrepares production launches. Use when preparing to deploy to production, or when asking what needs to be in place before shipping. Use when you need a pre-launch checklist, when setting up monitoring, when planning a staged rollout, or when you need a rollback strategy.Stars: 118kUpdated Claude CodeCodexVerifiedInstall
childhoodthedotmack/claude-memBabysit a shipped release after merge, publication, or deployment. Verify published packages, production behavior, installed plugins, and late CI or user reports until the observation window is clean; use babysit for PR readiness before release.Stars: 118kUpdated Claude CodeCodexVerifiedInstall