Scala Support

[graemerocher]

Summary

Adds first-class Scala 3 support to Micronaut by integrating Scala compilation with Micronaut's compile-time visitor and bean definition infrastructure.

This PR introduces the Scala compiler integration, the Scala element model used by Micronaut visitors, collection and annotation metadata support, documentation for users, and broad parity coverage for framework features exercised from Scala source.

Implementation details

Scala 3 compiler plugin integration

The implementation uses the Scala 3 compiler plugin API to observe Scala sources during compilation and feed Micronaut's compile-time processing model with Scala-native symbols, types, annotations, members, constructors, fields, methods, properties, companion structures, enum constants, and generic signatures.

The compiler plugin entry point lives under inject-scala/src/main/scala/io/micronaut/scala/processing/MicronautScalaCompilerPlugin.scala. It bridges Scala compiler phases into Micronaut processing so existing TypeElementVisitor implementations can operate over Scala classes in the same style as Java, Kotlin, and Groovy sources.

Scala element model

The inject-scala module adds a Scala-specific visitor model under io.micronaut.scala.processing.visitor, including:

• ScalaProcessingEngine to coordinate processing.
• ScalaVisitorContext for visitor state, generated elements, diagnostics, and classpath access.
• ScalaClassElement, ScalaMethodElement, ScalaConstructorElement, ScalaFieldElement, ScalaParameterElement, ScalaPropertyElement, ScalaPackageElement, and enum/generic/wildcard variants.
• ScalaAnnotationMetadataBuilder and related data types to convert Scala compiler annotation data into Micronaut annotation metadata.
• Loaded class support for classpath symbols and inherited metadata.

This keeps the Scala implementation aligned with Micronaut's existing compile-time abstractions instead of creating a separate runtime path.

Annotation metadata and type handling

The implementation resolves Scala annotation constructor arguments, defaults, aliases, annotation mappers/remappers/transformers, class-valued members, constants, placeholders, wildcard bounds, explicit-null unions, inherited metadata, type variables, nested generics, arrays, and enum constants.

It also adds support for visitor-generated beans, visitor ordering, annotation mutations, classpath annotation lookup, service-loader expressions, package elements, member equality, and diagnostic handling at Scala compiler phase boundaries.

Bean definition, injection, AOP, and configuration support

Scala sources can now participate in core Micronaut compile-time features, including:

• Bean discovery and bean definition generation.
• Constructor, field, method, and member injection.
• Qualifiers, scopes, default scopes, stereotypes, Provider, BeanRegistration, and collection/map injection.
• Factory methods, factory properties, nullable factories, primitive factories, implicit/named factories, and factory method collision handling.
• Bean introspection, immutable configuration properties, JavaBean-style properties, field access introspection, enum introspection, constructor forwarding, validation metadata, and property filters.
• AOP around advice, introduction advice, lifecycle advice, retry advice, hotswap/proxy-target behavior, trait default method bridges, generated adapter methods, and generic introduction metadata.
• Scala collection and Option handling, including mutable and immutable collection binding/injection paths.

Documentation and examples

The user guide now includes Scala language support documentation and Scala snippets across the docs where parity examples are available. The PR adds a Scala test suite with examples covering HTTP clients and servers, filters, routing, binding, uploads, SSE/streaming, configuration, factories, validation, events, propagation, resources, scopes, qualifiers, replacements, AOP, introspection, and other documented framework features.

The Scala docs examples are backed by tests in test-suite-scala, and the disabled-test tracking files document remaining parity gaps and follow-up areas.

Testing

The branch adds dedicated Scala compiler and visitor tests in inject-scala-test, plus documentation parity coverage in test-suite-scala.

Key coverage areas include:

• Scala compiler plugin proof of concept and processing engine behavior.
• Annotation metadata parity.
• Bean definition and bean introspection parity.
• Element completeness, mutation, visitor context, visitor ordering, and generated-bean coverage.
• AOP, configuration properties, factories, qualifiers, lifecycle, collection injection, enum introspection, explicit nullability, and docs snippet parity.

Notes for reviewers

This is intentionally opened as a draft because the change set is broad and spans compiler integration, framework compile-time model support, docs, and parity tests. Review is probably easiest by starting with the Scala compiler plugin and inject-scala visitor model, then moving through the focused parity specs and finally the documentation/test-suite additions.

[WojciechMazur]

One things that's not in the plan is the long term maintance plan - we cannot expect Micronaut team to know Scala, and especially about compiler plugin knowledge, so if it's merged there should be somebody responsible for this part.

As a compiler team member, and release officer I can help with opening PRs for upgrade to new minor, but I have no domain knowledge about this ecosystem, so I'd rather limit my involvement to version upgrades and critical compiler fixes. However, I'm involved in multiple different OSS areas, so my time might be really limited

[graemerocher]

hopefully this can be low overhead, but it is great if you can be a contact if we have a blocking change we can't work out ourselves

[WojciechMazur]

Other part is publishing and maintance of the plugin - compiler plugins have neither binary or source binary compatibility. The sources typically dont't change much, but compiler plugin is strongly coupled with compiler itself - we're not operating on abstraction over compiler, we're touching it directly, so any change compiler, but introduce source incompatibility for maintianers, or when using 2 different versions, binary issues for users.

Every compiler plugin should be published per supported Scala version using full-cross version, so we need a plan for this part as well:

• all Scala versions since 3.3 LTS?
• only latest versions in series LTS and Next series
• only LTS versions?
• a single version?

Personally I'd lean toward: latest 3.3 LTS (supported for 1 more year) and latest 3.9 LTS (first release in 6-9 weeks)

https://docs.scala-lang.org/overviews/plugins/index.html#binary-compatibility-of-compiler-plugins

Example of such an issue (an links to other known to me historical problems in the ecosystem): scalus3/scalus#225

[graemerocher]

some good points here, it might make sense to have an external micronaut-scala project where this lives so it can have a different versioning lifecycle

[WojciechMazur]

hasFlag takes a FlagSet, yet you're invoking it multiple times

Suggested change

	private def skipMethod(symbol: Symbol)(using Context): Boolean =
	symbol == Symbols.NoSymbol ||
	symbol.denot.isConstructor ||
	hasFlag(symbol, Flags.Synthetic) ||
	hasFlag(symbol, Flags.Artifact) ||
	hasFlag(symbol, Flags.Accessor)
	private def skipMethod(symbol: Symbol)(using Context): Boolean =
	symbol.denot.isConstructor ||
	hasFlag(symbol, Flags.Synthetic | Flags.Artifact | Flags.Accessor)

I think NoSymbol.denot returns NoDenotation which is safe to use directly to cehck for isConstructor of flags directly. It might only throw when trying to access owner

[WojciechMazur]

I don't quite understand why reflective invocation is required to start the compiler plugin, and why we can't do it directly. It should be documented in there.

[graemerocher]

Micronaut itself supports compiler extensions to the main processor, so I guess this is trying to allow dynamic load of these extensions, but will review if it is necessary

[WojciechMazur]

Using LLMs is fine for contributing, but let's keep some redability standards...
We're represeting the Scala community here against multiple JVM languages

Suggested change

	arrayLiteralValues(tree) match
	case Some(values) =>
	values
	case None =>
	classLiteralValue(tree) match
	case Some(value) =>
	value
	case None =>
	nestedAnnotationValue(tree) match
	case Some(value) =>
	value
	case None =>
	typedConstantValue(tree) match
	case Some(value) =>
	value
	case None =>
	tree match
	case literal: tpd.Literal =>
	annotationConstantValue(literal.const.value).orNull
	case select: tpd.Select if isEnumConstant(select.symbol) =>
	select.name.toString
	case ident: tpd.Ident if ident.name.toString == "_" =>
	null
	case ident: tpd.Ident if isEnumConstant(ident.symbol) =>
	ident.name.toString
	case _ =>
	renderedClassLiteralValue(tree.show).map(name => classValueData(name)).getOrElse(tree.show)
	arrayLiteralValues(tree)
	.orElse(classLiteralValue(tree))
	.orElse(nestedAnnotationValue(tree))
	...

[gbrennon]

that a comment that im happy to read :)
its important to keep readability something that acts as a characteristic of that framework 👍

[WojciechMazur]

we can easily drop most the the helper method

Suggested change

	case constant: ConstantType =>
	annotationConstantValue(constant.value.value)
	case ConstantType(constant) =>
	constant.value match
	case _: Unit => None
	case value: AnyVal => Some(value)
	case value: String => ???
	case _ => null

[WojciechMazur]

Wouldn't that be easier to flip the check? Literal can be AnyVal | Class | String | Nul, AnyVal includes Unit
Constant has isAnyVa check so only remaining check guarding against Unit.

[WojciechMazur]

generaly you should match on symbol or type, not the string representation