Micronaut Sourcegen

Micronaut Sourcegen

Use this skill when a Micronaut module wants to generate types with Micronaut Sourcegen instead of handwritten source strings, reflection, JavaPoet/KotlinPoet calls in visitors, or ad hoc bytecode. The target module may emit Java source, Kotlin source, Groovy-compatible source, or bytecode, but the generation logic should model the type once with io.micronaut.sourcegen.model.

Goal

Help other modules adopt Micronaut Sourcegen safely: choose the right backend, wire the right processor dependencies, build language-neutral model definitions, and verify generated Java/Kotlin/bytecode behavior with targeted tests.

Trigger Examples

Should trigger:

• "Use Micronaut Sourcegen in this module to generate a repository implementation."
• "Generate bytecode instead of Java source for this visitor."
• "Make this annotation processor generate Java and Kotlin outputs with Sourcegen."
• "Replace handwritten generated-source strings with ClassDef and MethodDef."
• "Add method bodies with switches, static calls, static field arguments, and constructor calls."

Should not trigger:

• "Only edit user guide text."
• "Only change Gradle publishing metadata."
• "Only refactor backend writer internals without a module consuming Sourcegen."
• "Explain Micronaut annotation processing without generated types."

Procedure

1. Identify the consuming module and generation target.
2. Choose one backend for each compilation path.
3. Wire dependencies using the repository version catalogs and processor configurations.
4. Implement generation in a visitor with Sourcegen model builders and helpers.
5. Emit through SourceGenerator.write(...) or bytecode writer APIs as appropriate.
6. Add cross-target tests for the generated contract.
7. Run focused compile/test/style verification.

1) Identify the Consuming Module

• Confirm whether the module is an annotation processor/generator module, an application/test-suite module consuming a generator, or a backend writer module.
• Locate existing visitor registration under META-INF/services/io.micronaut.inject.visitor.TypeElementVisitor.
• Identify source language paths:
  • Java annotation processing uses annotationProcessor.
  • Kotlin compilation usually uses ksp.
  • Bytecode generation runs during Java-language processing and writes class files directly.
• Inspect existing generated-type tests before changing behavior.

2) Choose the Backend

• Use sourcegen-generator-java when the module should emit .java source for VisitorContext.Language.JAVA; it also provides GroovyPoetSourceGenerator for GROOVY.
• Use sourcegen-generator-kotlin when Kotlin/KSP processing should emit .kt source for VisitorContext.Language.KOTLIN.
• Use sourcegen-generator-bytecode when Java-language processing should emit .class files directly through ByteCodeGenerator.
• Do not put both Java-source and bytecode Sourcegen generators on the same Java annotation-processor path unless the module intentionally owns selection. Both advertise VisitorContext.Language.JAVA, and SourceGenerators.findByLanguage(JAVA) expects a single effective backend.
• Use sourcegen-bytecode-writer directly only when implementing or testing bytecode writer behavior, not as the normal integration point for consuming annotation processors.

3) Wire Dependencies

• In a generator/processor module, depend on sourcegen-generator for the model and service lookup APIs. Add sourcegen-annotations only when the module consumes Sourcegen annotations such as builders/wither support.
• In a Java consumer/test module, add the chosen backend and the custom generator to annotationProcessor.
• In a Kotlin consumer/test module, add the Kotlin backend and KSP-compatible custom generator to ksp.
• In a bytecode consumer/test module, add sourcegen-generator-bytecode to annotationProcessor.
• Use Gradle version catalogs and existing project accessors. Do not hardcode dependency coordinates or versions.

Example repository-local shapes:

dependencies {
    implementation(projects.sourcegenGenerator)

    annotationProcessor(projects.sourcegenGeneratorJava)
    annotationProcessor(projects.myCustomGenerators)
}

dependencies {
    ksp(projects.sourcegenGeneratorKotlin)
    ksp(projects.myCustomGeneratorsKotlin)
}

dependencies {
    annotationProcessor(projects.sourcegenGeneratorBytecode)
    annotationProcessor(projects.myCustomGenerators)
}

4) Build Models With Factories, Not Record Constructors

• Always create Sourcegen model elements through builders, factory methods, or helper methods: ClassDef.builder, InterfaceDef.builder, RecordDef.builder, EnumDef.builder, AnnotationObjectDef.builder, MethodDef.builder, MethodDef.constructor, FieldDef.builder, PropertyDef.builder, ParameterDef.builder, TypeDef.of, ClassTypeDef.of, TypeDef.parameterized, ExpressionDef.constant, StatementDef.multi, StatementDef.doTry, expr.returning, expr.invoke, type.invokeStatic, type.getStaticField, and switch/if helper methods.
• Do not instantiate DSL records directly in consuming modules, for example avoid new ClassTypeDef.Parameterized(...), new TypeDef.Array(...), new ExpressionDef.Constant(...), new StatementDef.Switch(...), or other new ...record(...) forms.
• If a construct has no public helper yet, add or use a small named helper/factory at the nearest appropriate level instead of spreading direct record construction through module code.
• Keep model construction language-neutral. Do not call JavaPoet, KotlinPoet, ASM, or write source strings from a visitor unless the task is explicitly inside a backend writer.

5) Implement Visitors

• Prefer TypeElementVisitor with VisitorKind.ISOLATING when generated output depends only on the visited element.
• Resolve the backend through SourceGenerators.findByLanguage(context.getLanguage()).orElse(null) and return when none is available.
• Build ObjectDef instances from Micronaut AST metadata (ClassElement, MethodElement, FieldElement, PropertyElement) when possible.
• Emit with sourceGenerator.write(objectDef, context, originatingElement).
• Use SourceGenerators.handleFatalException(...) when generation may postpone to a later round.

Minimal visitor shape:

SourceGenerator sourceGenerator = SourceGenerators.findByLanguage(context.getLanguage()).orElse(null);
if (sourceGenerator == null) {
    return;
}

ClassDef generated = ClassDef.builder(element.getPackageName() + ".Generated")
    .addModifiers(Modifier.PUBLIC, Modifier.FINAL)
    .addMethod(MethodDef.builder("name")
        .addModifiers(Modifier.PUBLIC)
        .returns(TypeDef.STRING)
        .build((aThis, params) -> ExpressionDef.constant("generated").returning()))
    .build();

sourceGenerator.write(generated, context, element);

6) Model Generated Behavior

• Use ClassDef, InterfaceDef, RecordDef, EnumDef, and AnnotationObjectDef for generated type kind.
• Use TypeDef and ClassTypeDef for primitives, arrays, generics, generated class names, nullability, and static field owners.
• Use MethodDef body builders for executable logic. Prefer explicit returns(...) for public or non-trivial generated methods.
• When generated code reads or writes a field that the same generator defines, keep the FieldDef instance and reference it with aThis.field(fieldDef) or generatedType.getStaticField(fieldDef) instead of repeating the field name and type.
• When generated code invokes a method that the same generator defines, keep the MethodDef instance and invoke it with receiver.invoke(methodDef, ...) or generatedType.invokeStatic(methodDef, ...) instead of repeating the method name, parameter types, and return type.
• When generated code targets an existing method or field that is accessible reflectively and present on the annotation processor classpath, prefer a reflective handle from ReflectionUtils.getRequiredMethod(...) or ReflectionUtils.getRequiredField(...). Pass method handles to receiver.invoke(method, ...) or type.invokeStatic(method, ...); pass static field handles to type.getStaticField(field); for instance fields, centralize the field-name/type bridge in a helper fed by the reflective Field. This uses reflection only at generation time to describe a known member; it must not generate runtime reflection.
• Use StatementDef.multi(...), expr.returning(), expr.newLocal(...), condition.doIf(...), expr.asExpressionSwitch(...), expr.asStatementSwitch(...), StatementDef.doTry(...), and invocation helpers to compose bodies.
• Use ClassTypeDef.getStaticField("NAME", valueType) for enum constants, static constants, class literals, and static-field arguments passed to invocations.
• String switches are supported. For string switch cases, use a TypeDef.STRING switch expression and ExpressionDef.constant("case") keys with asExpressionSwitch(...) or asStatementSwitch(...).