sdk: support nullable object returns

[eunomie]

Ports dagger/dagger#13879 ("sdk(improvement): support nullable object returns") to this repo.

What

GraphQL fields that return a nullable object or interface had no correct representation in the generated Java client. Every object-typed field was generated lazily — the method appended to the query chain and wrapped the result, so a field that resolved to null still handed back a valid-looking object, and the null only surfaced later as a confusing failure elsewhere.

Nullable methods now resolve the object's id before returning. A missing id becomes Optional.empty(); a present id is rebuilt as a normal, lazy client object. Non-null object methods are unchanged and stay lazy.

Optional<ObjectTypeDef> asObject = typeDef.asObject();
if (asObject.isPresent()) {
  System.out.println(asObject.get().name());
}

Module authors get the mirror capability — declaring Optional<T> as a function return type. That previously did not even build: DaggerType discarded the wrapper, so the generated entrypoint assigned the call to the unwrapped type and javac rejected it.

@Function
public Optional<Directory> maybeDirectory(boolean found) {
  return found ? Optional.of(dag().directory()) : Optional.empty();
}

Compatibility

Generated code is gated on the engine's schema version: below v1.0.0-beta.10 the previous lazy shape is kept, so generating against an older engine still produces a client that engine can serve.

That gate needed plumbing to be meaningful here. The codegen mojo only reads the live version when it queries the schema itself; on this repo's path mod.dang hands it a schema, so the version stayed at the pom's hardcoded 0.21.4 and the gate would have been permanently false. The engine's own version is now passed alongside the schema, with build metadata stripped so the +<commit> suffix does not become a cache key.

Note: the current engine is v1.0.0-beta.9, below the gate — so nothing in this repo's generated output changes yet. The new shape is exercised by the unit tests and by a check that compiles the client at a version past the gate.

One fix beyond the port

Nullability can disagree across an implements relationship: GraphQL lets an implementation strengthen a nullable field to non-null, requires transitive interfaces to be declared, and lets two unrelated interfaces disagree about the same field. Java has one method to satisfy every declaration at once, so optional-ness has to be constant across a whole implements component rather than decided per type — otherwise the generated client does not compile. Coerced fields stay lazy: a non-null field has nothing to resolve, so it costs no round trip and throws nothing.

The reference implementation in dagger/dagger does not handle this and generates uncompilable Java for those schemas. Worth filing upstream separately.

Tests

This repo had no tests and no way to run any: every maven invocation builds with -Dmaven.test.skip=true, and no check ran mvn test.

Test dependencies now live behind a tests maven profile rather than in the module dependency lists — maven resolves test-scoped dependencies even under -Dmaven.test.skip=true, so declaring them unconditionally would undo 1cc5baf and make every cold dagger generate download libraries it cannot use. A packager:unit-tests check runs them, mirroring the SDK's own codegen container (a bare mvn test cannot work: the codegen mojo needs the plugin installed and a schema to generate from).

Coverage: the version gate on both sides of the boundary; the generated shape above and below it; that the generated client compiles, including the disagreeing-nullability cases; the resolve-and-rebuild round trip against a local HTTP server, present and null; the module-side typedef registration and null serialization; and an end-to-end check that generates a module returning Optional<Directory> — which also compiles its entrypoint, the failure this fixes.

The design doc and implementation plan are in hack/designs/.