fix(codegen): complete follow-up fixes for issue #418

Author: wax911

.agents/skills/retrofit-graphql-build-dependencies/references/build-map.md

@@ -11,7 +11,7 @@ Use this map to choose the right build file before editing.
 | Shared dependency strategy | `buildSrc/.../strategy/DependencyStrategy.kt` | Default Kotlin, Retrofit, OkHttp, coroutines, and test libraries per module type |
 | Shared Dokka behavior | `buildSrc/.../components/AndroidOptions.kt` | `dokkaHtml` task, `reportUndocumented = true`, internal packages suppressed, Android docs linked |
 | Shared formatting | `buildSrc/.../components/AndroidConfiguration.kt` (Spotless config), `spotless/copyright.kt` | Ktlint and license header configuration |
-| Publishing options | `buildSrc/.../components/AndroidOptions.kt` (Android), per-module `build.gradle.kts` (JVM) | AGP component-backed publications via `singleVariant("release")` + `withSourcesJar()`. JVM modules (`:annotations`, `:codegen-core`) inline publishing. Publication name `"maven"` for all modules. |
+| Publishing options | `buildSrc/.../components/AndroidOptions.kt` (Android), per-module `build.gradle.kts` (JVM), `gradle-plugin/build.gradle.kts`, `gradle-plugin/buildSrc/.../JvmConfiguration.kt`, `.jitpack.yml` | Root Android publications use AGP components. The standalone `gradle-plugin` composite build publishes both the plugin implementation + marker artifacts and republishes included `:codegen-core` with explicit coordinates from `gradle/version.properties`. `.jitpack.yml` must run both root and standalone plugin `publishToMavenLocal` commands. |
 | Dependency versions and aliases | `gradle/libs.versions.toml` | Add or update aliases here first |
 | Library build | `library/build.gradle.kts` | Applies the shared plugin; no module-specific overrides needed for standard changes |
 | Sample app build | `app/build.gradle.kts` | Applies the shared plugin; Room compiler options, build config fields from `.config/` |
@@ -28,4 +28,5 @@ Use this map to choose the right build file before editing.
 - Cross-module convention: `buildSrc`.
 - One module only: that module's `build.gradle.kts`.
 - Documentation generation or publish behavior: Dokka config in `buildSrc/...AndroidOptions.kt` plus the workflow file.
+- Standalone plugin publishing or plugin marker issues: `gradle-plugin/build.gradle.kts`, `gradle-plugin/settings.gradle.kts`, `gradle-plugin/buildSrc/.../JvmConfiguration.kt`, and `.jitpack.yml`.
 - Memory or JVM tuning: `gradle.properties` (repo-wide) or `~/.gradle/gradle.properties` (user-local, preferred for personal overrides).

.gitignore

@@ -61,6 +61,9 @@ captures/
 # External native build folder generated in Android Studio 2.2 and later
 .externalNativeBuild
 
+# Deepwork session state
+.slim/deepwork/
+
 # Google Services (e.g. APIs or Firebase)
 # google-services.json
 

.jitpack.yml

@@ -0,0 +1,5 @@
+jdk:
+  - openjdk21
+install:
+  - ./gradlew build publishToMavenLocal
+  - ./gradlew -p gradle-plugin publishToMavenLocal

AGENTS.md

@@ -61,7 +61,7 @@ The project is organized into composable modules under the `co.anitrend.retrofit
 | `:android-assets` | Android | Runtime asset-based query discovery: `GraphProcessor`, `AssetManagerDiscoveryPlugin`, APQ, logging |
 | `:runtime` | Android | Retrofit `Converter.Factory`: `GraphConverter`, `GraphRequestConverter`, `GraphResponseConverter`. Depends on `:api`, `:android-assets`, `:annotations` |
 | `:codegen-core` | Kotlin JVM | Code generation engine: parses `.graphql` files with graphql-java, generates Kotlin with KotlinPoet. Uses `SchemaIndex` for typed schema metadata, `GraphQLTypeMapper` for kind-aware mapping, `GraphQLDefaultValueRenderer` for default literals, and `GraphQLTypeUsageValidator` for recursive scalar validation. |
-| `:gradle-plugin` | Gradle Plugin | Plugin `id("co.anitrend.retrofit.graphql.codegen")`. Registers `GenerateGraphQLSourcesTask`, wires output into source sets. Lives in composite build under `pluginManagement` |
+| `:gradle-plugin` | Gradle Plugin | Plugin `id("co.anitrend.retrofit.graphql.codegen")`. Registers `GenerateGraphQLSourcesTask`, wires output into source sets, owns standalone functional tests, and publishes its own marker/implementation artifacts from the composite build. |
 | `:serialization-gson` | Android | Gson-backed `GraphQLJson` serialization |
 | `:serialization-kotlinx` | Android | kotlinx.serialization-backed `GraphQLJson` |
 | `:library` | Android | **Deprecated** aggregator. Re-exports all modules via `api()`. Contains type aliases from old `io.github.wax911.library` package |
@@ -83,7 +83,7 @@ The project is organized into composable modules under the `co.anitrend.retrofit
 - **Toolchain**: Java/Kotlin 21 (pinned in `.java-version`). Local dev uses `jenv`; CI uses `actions/setup-java`.
 - **SDK**: `compileSdk=37`, `minSdk=23`, `targetSdk=37`.
 - **Formatting**: Ktlint via Spotless. License header at `spotless/copyright.kt`.
-- **Publishing**: JitPack. JitPack badge/coordinates at top of README.
+- **Publishing**: JitPack. Root modules publish from the main build; the standalone `:gradle-plugin` composite build must also publish separately. `.jitpack.yml` runs both `./gradlew build publishToMavenLocal` and `./gradlew -p gradle-plugin publishToMavenLocal` so plugin marker + implementation artifacts and the included `:codegen-core` dependency are materialized for JitPack.
 - **CI**: Only `:library` is built/tested in CI environments. It serves as the aggregate facade and transitively builds all sub-modules via `api()` deps. `:app` is excluded in CI (see `settings.gradle.kts`).
 - **Dokka**: Generated via `buildSrc` `AndroidOptions.kt`. Published at `https://anitrend.github.io/retrofit-graphql/`. Currently generates from `:library` only; multi-module Dokka is a planned follow-up.
 

MIGRATION.md

@@ -71,6 +71,17 @@ dependencies {
 If you want to replace asset-based discovery with build-time code generation:
 
 ```kotlin
+// settings.gradle.kts
+pluginManagement {
+    repositories {
+        maven(url = uri("https://jitpack.io"))
+        gradlePluginPortal()
+        mavenCentral()
+        google()
+    }
+}
+
+// build.gradle.kts
 plugins {
     id("co.anitrend.retrofit.graphql.codegen") version "{tag}"
 }
@@ -117,18 +128,33 @@ Generated output (under `build/generated/source/graphql/`) includes:
 
 Wire the registry into your converter via Koin or manual construction:
 ```kotlin
-// Koin
+// Koin, registry-only (no Context required)
 single<GraphQLDocumentRegistry> { GeneratedGraphQLRegistry }
+factory { GraphConverter.create(registry = get()) }
+
+// Koin, mixed asset + codegen fallback
 factory { GraphConverter.create(context = get(), registry = get()) }
 
-// Manual
-val factory = GraphConverter.create(
+// Manual, registry-only
+val registryOnlyFactory = GraphConverter.create(
+    registry = GeneratedGraphQLRegistry,
+)
+
+// Manual, custom Gson + registry-only
+val customGsonFactory = GraphConverter.create(
+    gson = GsonBuilder().serializeNulls().create(),
+    registry = GeneratedGraphQLRegistry,
+)
+
+// Manual, mixed asset + codegen fallback
+val mixedFactory = GraphConverter.create(
     context = context,
     registry = GeneratedGraphQLRegistry,
 )
 ```
 
-> **Note:** `GraphConverter.create(context, registry)` is the recommended factory for codegen consumers. It wires the generated registry while keeping asset-based discovery as a fallback.
+> **Note:** `GraphConverter.create(registry)` and `GraphConverter.create(gson, registry)` are the new codegen-first factories. Use `GraphConverter.create(context, registry)` when you still want asset-based fallback during a mixed migration.
+> **Note:** In registry-only mode, unresolved operations do not throw during conversion. The request is still built and the serialized GraphQL `query` remains `null`.
 
 ### Multipart Uploads
 
@@ -263,6 +289,8 @@ New (with optional registry for codegen):
 GraphConverter(processor, gson, registry = GeneratedGraphQLRegistry)
 // or via static factory:
 GraphConverter.create(androidContext(), registry = GeneratedGraphQLRegistry)
+GraphConverter.create(registry = GeneratedGraphQLRegistry)
+GraphConverter.create(gson, registry = GeneratedGraphQLRegistry)
 ```
 
 ### Query Resolution

README.md

@@ -103,6 +103,52 @@ dependencies {
 
 For code generation support, apply the Gradle plugin and add a `retrofitGraphQL { }` config block. The plugin generates operation constants, a document registry, enum classes, variable classes, and typed request helpers. See [MIGRATION.md](MIGRATION.md) for the full migration guide and the [wiki Code Generation page](https://github.com/AniTrend/retrofit-graphql/wiki/Codegen) for the DSL reference.
 
+### Gradle Plugin Consumption
+
+The codegen plugin can now be consumed through the Gradle `plugins {}` DSL.
+
+```kotlin
+pluginManagement {
+    repositories {
+        mavenLocal() // optional for local verification / development
+        maven(url = uri("https://jitpack.io"))
+        gradlePluginPortal()
+        mavenCentral()
+        google()
+    }
+}
+
+plugins {
+    id("co.anitrend.retrofit.graphql.codegen") version "{latest_version}"
+}
+```
+
+> **JitPack note:** this repository now ships a root `.jitpack.yml` that runs both the main build publication and the standalone `gradle-plugin` publication path. Local verification in this repository resolves the plugin from `mavenLocal()` using the published plugin marker artifact; remote JitPack resolution should follow the same published metadata flow.
+
+### Converter Factories for Codegen Registries
+
+Codegen-only consumers no longer need an Android `Context` just to use the generated registry:
+
+```kotlin
+val converter = GraphConverter.create(registry = GeneratedGraphQLRegistry)
+
+val customGsonConverter = GraphConverter.create(
+    gson = GsonBuilder().serializeNulls().create(),
+    registry = GeneratedGraphQLRegistry,
+)
+```
+
+If you want generated documents first **and** asset-based fallback for mixed migrations, keep using the context-backed overload:
+
+```kotlin
+val converter = GraphConverter.create(
+    context = context,
+    registry = GeneratedGraphQLRegistry,
+)
+```
+
+In registry-only mode, if an operation is missing from the registry, the request body is still built and the serialized GraphQL `query` remains `null`.
+
 - __Optional R8 / ProGuard Rules__
 
 If you are using R8 the shrinking and obfuscation rules are included automatically.

android-assets/src/main/kotlin/co/anitrend/retrofit/graphql/annotation/processor/contract/AbstractGraphProcessor.kt

@@ -48,7 +48,8 @@ abstract class AbstractGraphProcessor {
      * @param annotations A collection of method annotation from an ongoing request
      *
      * @return GraphQL query in the form of [String] or null if the request method was not
-     * annotated with [GraphQuery] or if the no such file could be found
+     * annotated with [GraphQuery], if no such file could be found, or when a no-op processor is
+     * intentionally used for registry-only runtime lookup.
      */
     abstract fun getQuery(annotations: Array<out Annotation>): String?
 

api/src/main/kotlin/co/anitrend/retrofit/graphql/model/GraphQLDocumentRegistry.kt

@@ -20,7 +20,8 @@ package co.anitrend.retrofit.graphql.model
  * A registry that provides GraphQL document text and APQ hash for a given operation name.
  *
  * Implementations can be generated at build time (e.g., [GeneratedGraphQLRegistry]) or
- * provided manually by the consumer.
+ * provided manually by the consumer. Runtime converter integrations check this registry before
+ * attempting legacy asset-based discovery.
  */
 public interface GraphQLDocumentRegistry {
     /**

api/src/main/kotlin/co/anitrend/retrofit/graphql/model/request/QueryContainerBuilder.kt

@@ -83,8 +83,10 @@ open class QueryContainerBuilder(
     }
 
     /**
-     * Should only be called by the GraphQLConverter or any other subclasses of it
-     * after the query has been added to the request
+     * Should only be called by the GraphQL converter after query resolution has been attempted.
+     *
+     * The built request may still contain a `null` query when neither a generated registry nor an
+     * asset-backed processor can resolve the referenced operation.
      *
      * @see co.anitrend.retrofit.graphql.converter.GraphConverter
      */

gradle-plugin/build.gradle.kts

@@ -1,13 +1,31 @@
+import co.anitrend.retrofit.graphql.buildSrc.plugin.components.applyStandaloneBuildCoordinates
 import co.anitrend.retrofit.graphql.buildSrc.plugin.components.configureSpotlessForJvm
+import org.gradle.api.tasks.SourceSetContainer
+import org.gradle.api.tasks.testing.Test
+import org.gradle.api.publish.maven.MavenPublication
 
 plugins {
     kotlin("jvm")
     `java-gradle-plugin`
+    `maven-publish`
 }
 
+applyStandaloneBuildCoordinates()
+
 configureSpotlessForJvm()
 
+val sourceSets = the<SourceSetContainer>()
+val functionalTestSourceSet = sourceSets.create("functionalTest")
+
+configurations[functionalTestSourceSet.implementationConfigurationName].extendsFrom(
+    configurations.testImplementation.get(),
+)
+configurations[functionalTestSourceSet.runtimeOnlyConfigurationName].extendsFrom(
+    configurations.testRuntimeOnly.get(),
+)
+
 gradlePlugin {
+    testSourceSets(functionalTestSourceSet)
     plugins {
         create("retrofitGraphQL") {
             id = "co.anitrend.retrofit.graphql.codegen"
@@ -16,10 +34,65 @@ gradlePlugin {
     }
 }
 
+publishing {
+    publications.withType(MavenPublication::class.java).configureEach {
+        pom {
+            name.set("Retrofit GraphQL Gradle Plugin")
+            description.set("Standalone Gradle plugin for retrofit-graphql GraphQL source generation")
+            url.set("https://github.com/anitrend/retrofit-graphql")
+            licenses {
+                license {
+                    name.set("Apache License, Version 2.0")
+                    url.set("http://www.apache.org/licenses/LICENSE-2.0.txt")
+                }
+            }
+            developers {
+                developer {
+                    id.set("wax911")
+                    name.set("Maxwell Mapako")
+                    organizationUrl.set("https://github.com/anitrend")
+                }
+            }
+        }
+    }
+}
+
 dependencies {
     api(project(":codegen-core"))
     implementation(libs.kotlinpoet)
     implementation(gradleApi())
     compileOnly(libs.android.gradle.plugin)
+
+    add(functionalTestSourceSet.implementationConfigurationName, gradleTestKit())
+    add(functionalTestSourceSet.implementationConfigurationName, kotlin("test"))
+    add(functionalTestSourceSet.implementationConfigurationName, libs.junit)
 }
 
+val functionalTest = tasks.register<Test>("functionalTest") {
+    description = "Runs Gradle TestKit functional tests"
+    group = "verification"
+    testClassesDirs = functionalTestSourceSet.output.classesDirs
+    classpath = functionalTestSourceSet.runtimeClasspath
+    filter {
+        excludeTestsMatching("co.anitrend.retrofit.graphql.codegen.PublishedConsumerPluginResolutionTest")
+    }
+    shouldRunAfter(tasks.test)
+}
+
+val publishedConsumerTest = tasks.register<Test>("publishedConsumerTest") {
+    description = "Verifies plugin resolution from mavenLocal"
+    group = "verification"
+    testClassesDirs = functionalTestSourceSet.output.classesDirs
+    classpath = functionalTestSourceSet.runtimeClasspath
+    // Runs separately from functionalTest because it validates the published-marker flow
+    // and needs fresh local publications before executing.
+    dependsOn("publishToMavenLocal")
+    filter {
+        includeTestsMatching("co.anitrend.retrofit.graphql.codegen.PublishedConsumerPluginResolutionTest")
+    }
+    shouldRunAfter(functionalTest)
+}
+
+tasks.check {
+    dependsOn(functionalTest)
+}