[Java] @CopilotTool ergonomics 4.2: Schema generation utility (TypeMirror to JSON Schema) #1759

Overview

Create a compile-time schema generation utility that maps javax.lang.model types (TypeMirror, DeclaredType) to JSON Schema represented as Java source code literals (Map.of(...) expressions).

Branch: edburns/1682-java-tool-ergonomics on upstream (⚠️ NOT main — PRs must target this branch)

Prerequisites

• Task 4.1 (annotations) must be complete and merged to the branch.
• Before writing any code, read the entire implementation plan at:
  1682-java-tool-ergonomics-prompts-remove-before-merge/dd-3018003-ignorance-reduction-for-implementation-plan.md

Relevant plan sections to carefully re-read

• Section 3.4 — Type-to-JSON-Schema mapping (Resolution: maximum viable set of 23 type mappings with full table)
• Section 3.5 — Generated code shape (Resolution: how generated code uses schema maps)
• Section 4.2 — Schema generation utility (compile-time) (the primary task description)

Deliverables

Files to create

1. java/src/main/java/com/github/copilot/tool/SchemaGenerator.java

Functional specification

SchemaGenerator is a compile-time utility invoked by the annotation processor. It receives javax.lang.model.type.TypeMirror instances and produces a String containing the Java source code literal for the JSON Schema Map. For example, given a String type, it should produce the source code string: Map.of("type", "string").

Type mappings to implement (from Resolution 3.4)

API design

public class SchemaGenerator {
    /**
     * Given a TypeMirror from the annotation processing environment,
     * return a String containing Java source code for a Map literal
     * representing the JSON Schema of that type.
     */
    public String generateSchemaSource(TypeMirror type, Types typeUtils, Elements elementUtils) { ... }

    /**
     * Generate the full "parameters" schema source for a method's parameters.
     * Produces a Map.of("type", "object", "properties", Map.of(...), "required", List.of(...)).
     */
    public String generateParametersSchemaSource(List<? extends VariableElement> parameters,
                                                  Types typeUtils, Elements elementUtils) { ... }
}

The class should use javax.lang.model.type.TypeKind, DeclaredType.getTypeArguments(), ElementKind.ENUM_CONSTANT, and related APIs. It does NOT use java.lang.reflect at all.

Gating tests and criteria

All of the following must pass before this task is considered complete:

1. Unit tests: Create java/src/test/java/com/github/copilot/tool/SchemaGeneratorTest.java that tests schema generation. Since TypeMirror instances are hard to mock, use the compilation-testing approach: write small Java source snippets, compile them with javax.tools.JavaCompiler, and have a test processor that exercises SchemaGenerator during compilation. Alternatively, use a test annotation processor that logs generated schema and asserts correctness.

2. Minimum type coverage tests: The test must verify correct schema generation for at minimum:

   • String → {"type": "string"}
   • int / Integer → {"type": "integer"}
   • boolean / Boolean → {"type": "boolean"}
   • double / Double → {"type": "number"}
   • An enum type → {"type": "string", "enum": [...]}
   • List<String> → {"type": "array", "items": {"type": "string"}}
   • A simple record with 2-3 fields → {"type": "object", "properties": {...}, "required": [...]}
   • Optional<String> → schema of String, NOT in required
   • Map<String, String> → {"type": "object", "additionalProperties": {"type": "string"}}

3. Generated source validity: For each test case, verify the generated source code string is syntactically valid Java (it should compile if pasted into a method body).

4. Spotless format check: mvn spotless:check passes.

5. Full test suite: mvn clean verify passes (existing tests and 4.1 tests not broken).

Constraints

• ✅✅ YOU MUST run mvn spotless:apply before every commit.

• This class operates exclusively at compile time with javax.lang.model APIs.

• Do NOT use java.lang.reflect anywhere in this class.

• Do NOT modify any files outside the java/ directory.

• Follow existing code style (4-space indent, Javadoc on public APIs).

• The generated source code strings must use java.util.Map.of() and java.util.List.of() (Java 9+ immutable collections) for the schema literals.