feat(gradle-plugin): auto-generate FlagRegistry initializers per module

[kirich1409]

Summary

• Adds generateFlagRegistrar Gradle task that reads scanLocalFlags output and emits GeneratedFlagRegistrar.kt with an object GeneratedFlagRegistrar { fun register() { ... } } calling FlagRegistry.register(...) for every @LocalFlag-annotated ConfigParam in the module
• Extends LocalFlagEntry with propertyName and ownerName fields; adds kotlinReference computed property for compile-safe reference generation
• Updates LocalFlagScanner regex to capture the Kotlin property name and resolves the nearest enclosing object/companion object as the owner
• Updates ScanResultParser with backwards-compatible 6-field format (4-field lines from older scan output parse successfully)
• Generated file is KMP-safe — imports only dev.androidbroadcast.featured.registry.FlagRegistry

AndroidX App Startup integration and app-level aggregator generation are deferred as future work per the issue spec.

Test plan

• ./gradlew :featured-gradle-plugin:test — all 121 tests pass
• ./gradlew spotlessCheck — no formatting violations
• FlagRegistrarGeneratorTest — 11 unit tests covering package, import, object/function generation, register calls for owned/top-level/legacy entries
• GenerateFlagRegistrarTaskRegistrationTest — 7 tests verifying task registration, type, group, outputFile, packageName, dependency chain, output path
• LocalFlagEntryKotlinReferenceTest — 4 tests for the kotlinReference computed property
• LocalFlagScannerPropertyCaptureTest — 7 tests verifying property name and owner capture from scanned source

Closes #20

🤖 Generated with Claude Code

[Copilot]

Pull request overview

Adds a new Gradle-plugin capability to generate a per-module Kotlin registrar (GeneratedFlagRegistrar) that registers all @LocalFlag ConfigParams with FlagRegistry, and extends the local-flag scanning/reporting format to support generating compile-time references.

Changes:

• Add generateFlagRegistrar task + FlagRegistrarGenerator to emit GeneratedFlagRegistrar.kt.
• Extend LocalFlagEntry and scanning/parsing pipeline to include propertyName + ownerName (with backwards-compatible parsing).
• Add unit tests covering scanner property/owner capture, Kotlin reference generation, generator output, and task registration.

Reviewed changes

Copilot reviewed 12 out of 12 changed files in this pull request and generated 8 comments.

Show a summary per file

File	Description
featured-gradle-plugin/src/main/kotlin/dev/androidbroadcast/featured/gradle/FeaturedPlugin.kt	Registers the new generateFlagRegistrar task.
featured-gradle-plugin/src/main/kotlin/dev/androidbroadcast/featured/gradle/GenerateFlagRegistrarTask.kt	Implements the task that reads scan output and writes generated Kotlin source.
featured-gradle-plugin/src/main/kotlin/dev/androidbroadcast/featured/gradle/FlagRegistrarGenerator.kt	Generates the Kotlin source for GeneratedFlagRegistrar.
featured-gradle-plugin/src/main/kotlin/dev/androidbroadcast/featured/gradle/LocalFlagEntry.kt	Adds propertyName, ownerName, and kotlinReference to scan entries.
featured-gradle-plugin/src/main/kotlin/dev/androidbroadcast/featured/gradle/LocalFlagScanner.kt	Updates scanning regex + adds owner-resolution heuristic.
featured-gradle-plugin/src/main/kotlin/dev/androidbroadcast/featured/gradle/ScanLocalFlagsTask.kt	Updates scan report output to include propertyName and ownerName.
featured-gradle-plugin/src/main/kotlin/dev/androidbroadcast/featured/gradle/ScanResultParser.kt	Adds backwards-compatible support for parsing both 4-field and 6-field scan lines.
featured-gradle-plugin/src/test/kotlin/dev/androidbroadcast/featured/gradle/LocalFlagScannerTest.kt	Updates scanner tests to assert propertyName/ownerName.
featured-gradle-plugin/src/test/kotlin/dev/androidbroadcast/featured/gradle/LocalFlagScannerPropertyCaptureTest.kt	Adds tests for property and owner capture behavior.
featured-gradle-plugin/src/test/kotlin/dev/androidbroadcast/featured/gradle/LocalFlagEntryKotlinReferenceTest.kt	Adds tests for kotlinReference.
featured-gradle-plugin/src/test/kotlin/dev/androidbroadcast/featured/gradle/FlagRegistrarGeneratorTest.kt	Adds tests for generated registrar source output.
featured-gradle-plugin/src/test/kotlin/dev/androidbroadcast/featured/gradle/GenerateFlagRegistrarTaskRegistrationTest.kt	Adds tests ensuring the task is registered and configured.

[Copilot]

GenerateFlagRegistrarTask KDoc claims the plugin wires the generated source directory into Kotlin source sets automatically, but FeaturedPlugin currently only registers the task and doesn’t add build/generated/featured as a Kotlin source directory. Either implement the wiring (for KMP/JVM/Android projects) or adjust the documentation to avoid implying the generated registrar will be available without extra build configuration.

[Copilot]

The KDoc says the function returns an empty list when the file "contains lines that do not conform", but the implementation actually skips non-conforming lines and still returns any successfully parsed entries. Either tighten the wording (e.g., "ignores lines that do not conform") or change the implementation to fail the whole parse if any line is malformed.

[Copilot]

The generated KDoc suggests calling GeneratedFlagRegistrar.register() from Application.onCreate(), which is Android-specific. Since this file is intended to be KMP-safe and usable from common code, consider rewording to a platform-agnostic suggestion (e.g., "call once during app startup") to avoid implying an Android-only integration path.

Suggested change

	appendLine(" * Call this once at application startup, e.g. from `Application.onCreate()`.")
	appendLine(" * Call this once during application startup from your platform's initialization code.")

[Copilot]

OBJECT_DECL_REGEX intentionally matches companion object but discards its owner name (group 1 is empty), which means ownerName becomes null and the generated reference becomes unqualified. Flags declared inside a companion object will therefore generate invalid references (they need to be qualified with the enclosing class/object). Consider capturing the enclosing class name for companion objects (or at least emitting a distinct sentinel so the generator can qualify correctly).

[Copilot]

resolveOwner() currently picks the last object/companion object whose opening { appears before the flag’s offset, without verifying that the flag is actually inside that object's brace range. This will mis-attribute ownerName for top-level flags that appear after any object declaration, and for flags in an outer object after an inner object closes (nested objects). This can lead to incorrect generated references that won’t compile or will point at the wrong symbol; consider tracking brace depth to compute (start,end) ranges for object blocks and only returning an owner when offset falls within the range.

Suggested change

	* Builds a sorted list of (startOffset, ownerName?) pairs representing each
	* `object` or `companion object` block found in [source].
	* Used by [resolveOwner] to determine the enclosing owner of a property.
	*/
	private fun buildOwnerIndex(source: String): List<Pair<Int, String?>> =
	OBJECT_DECL_REGEX
	.findAll(source)
	.map { m ->
	val name = m.groupValues[1].takeIf { it.isNotEmpty() }
	m.range.first to name
	}.sortedBy { it.first }
	.toList()
	/**
	* Returns the name of the nearest `object` or `companion object` whose opening `{`
	* appears before [offset], or `null` if no such enclosing object is found.
	*
	* This is a heuristic: it picks the last object declaration whose start offset is
	* less than [offset], which covers the common pattern where `@LocalFlag` properties
	* are declared directly inside a single-level `object` block.
	*/
	private fun List<Pair<Int, String?>>.resolveOwner(offset: Int): String? = lastOrNull { (start, _) -> start < offset }?.second
	* Represents a single `object` or `companion object` block in the source.
	*
	* @property start Inclusive offset of the opening `{`.
	* @property end Inclusive offset of the matching closing `}`.
	* @property name Simple object name, or `null` for `companion object`.
	*/
	private data class OwnerBlock(
	val start: Int,
	val end: Int,
	val name: String?,
	)
	/**
	* Builds a sorted list of [OwnerBlock] entries representing each
	* `object` or `companion object` block found in [source].
	* Used by [resolveOwner] to determine the enclosing owner of a property.
	*/
	private fun buildOwnerIndex(source: String): List<OwnerBlock> {
	val owners = mutableListOf<OwnerBlock>()
	OBJECT_DECL_REGEX
	.findAll(source)
	.forEach { match ->
	// Determine the simple name of the object, if present.
	val name = match.groupValues[1].takeIf { it.isNotEmpty() }
	// Find the opening brace for this object.
	val openingBraceIndex = source.indexOf('{', startIndex = match.range.first)
	if (openingBraceIndex == -1) {
	// Malformed object declaration; skip.
	return@forEach
	}
	var depth = 0
	var i = openingBraceIndex
	var closingBraceIndex = -1
	// Walk forward to find the matching closing brace for this object block.
	while (i < source.length) {
	when (source[i]) {
	'{' -> {
	depth++
	}
	'}' -> {
	depth--
	if (depth == 0) {
	closingBraceIndex = i
	break
	}
	}
	}
	i++
	}
	if (closingBraceIndex != -1) {
	owners += OwnerBlock(
	start = openingBraceIndex,
	end = closingBraceIndex,
	name = name,
	)
	}
	}
	return owners.sortedBy { it.start }
	}
	/**
	* Returns the name of the nearest `object` or `companion object` whose block
	* actually encloses [offset], or `null` if no such enclosing object is found.
	*/
	private fun List<OwnerBlock>.resolveOwner(offset: Int): String? =
	lastOrNull { block -> block.start < offset && offset <= block.end }
	?.name

[Copilot]

The generated registrar uses unqualified references like MyFlags.flagA / darkTheme but the generated file only imports FlagRegistry and is placed in a fixed package. Unless every flag lives in the same package (and is otherwise in scope), this will not compile; the generator needs to either emit fully-qualified references (requires capturing each flag’s package and, for companion objects, enclosing class name) or generate appropriate imports per entry.

[Copilot]

The generated public fun register() is missing an explicit return type. Many modules in this repo enable Kotlin explicitApi(), which requires public functions to declare their return type; the generated source should use public fun register(): Unit to avoid compilation failures in explicit-API modules.

Suggested change

	appendLine(" public fun register() {")
	appendLine(" public fun register(): Unit {")

[Copilot]

ScanLocalFlagsTask now writes 6 fields (...|propertyName|ownerName) but the report format documentation in this task (and downstream tasks) still describes the 4-field format. Update the KDoc to reflect the new output so external consumers and future tasks don’t parse the report incorrectly.