Edburns/ghcp 1573 java ensure zod metadata shows thru (#1591)

* feat(java): emit @deprecated and @APinote from schema stability/deprecated metadata

- Add deprecated field to RpcMethod, RpcMethodNode, and EventVariant interfaces
- Emit @deprecated annotation on classes/methods where deprecated=true
- Emit @APinote Javadoc on event classes, RPC wrapper methods, and
  params/result classes where stability=experimental
- Regenerate all 914 generated files with updated metadata

* Move import of JSONSchema7

Author: edburns

java/scripts/codegen/java.ts

@@ -8,9 +8,9 @@
  */
 
 import fs from "fs/promises";
+import type { JSONSchema7 } from "json-schema";
 import path from "path";
 import { fileURLToPath } from "url";
-import type { JSONSchema7 } from "json-schema";
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
@@ -663,6 +663,8 @@ interface EventVariant {
     className: string;
     dataSchema: JSONSchema7 | null;
     description?: string;
+    stability?: string;
+    deprecated?: boolean;
 }
 
 function extractEventVariants(schema: JSONSchema7): EventVariant[] {
@@ -694,6 +696,8 @@ function extractEventVariants(schema: JSONSchema7): EventVariant[] {
                 className: `${baseName}Event`,
                 dataSchema: dataSchema ?? null,
                 description: resolved.description,
+                stability: (variant as unknown as Record<string, unknown>).stability as string | undefined,
+                deprecated: (variant as unknown as Record<string, unknown>).deprecated === true,
             };
         })
         .filter((v) => !EXCLUDED_EVENT_TYPES.has(v.typeName));
@@ -985,15 +989,18 @@ async function generateEventVariantClass(
     if (variant.description) {
         lines.push(`/**`);
         lines.push(` * ${variant.description}`);
-        lines.push(` *`);
-        lines.push(` * @since 1.0.0`);
-        lines.push(` */`);
     } else {
         lines.push(`/**`);
         lines.push(` * The {@code ${variant.typeName}} session event.`);
+    }
+    if (variant.stability === "experimental") {
         lines.push(` *`);
-        lines.push(` * @since 1.0.0`);
-        lines.push(` */`);
+        lines.push(` * @apiNote This method is experimental and may change in a future version.`);
+    }
+    lines.push(` * @since 1.0.0`);
+    lines.push(` */`);
+    if (variant.deprecated) {
+        lines.push(`@Deprecated`);
     }
     lines.push(`@JsonIgnoreProperties(ignoreUnknown = true)`);
     lines.push(`@JsonInclude(JsonInclude.Include.NON_NULL)`);
@@ -1197,6 +1204,7 @@ interface RpcMethod {
     params: JSONSchema7 | null;
     result: JSONSchema7 | null;
     stability?: string;
+    deprecated?: boolean;
 }
 
 function isRpcMethod(node: unknown): node is RpcMethod {
@@ -1322,7 +1330,7 @@ async function generateRpcTypes(schemaPath: string): Promise<void> {
                 const paramsClassName = `${className}Params`;
                 if (!generatedClasses.has(paramsClassName)) {
                     generatedClasses.set(paramsClassName, true);
-                    allFiles.push(await generateRpcDataClass(paramsClassName, paramsSchema, packageName, packageDir, method.rpcMethod, "params"));
+                    allFiles.push(await generateRpcDataClass(paramsClassName, paramsSchema, packageName, packageDir, method.rpcMethod, "params", method.stability, method.deprecated === true));
                 }
             }
 
@@ -1336,7 +1344,7 @@ async function generateRpcTypes(schemaPath: string): Promise<void> {
                     const resultClassName = `${className}Result`;
                     if (!generatedClasses.has(resultClassName)) {
                         generatedClasses.set(resultClassName, true);
-                        allFiles.push(await generateRpcDataClass(resultClassName, resultSchema, packageName, packageDir, method.rpcMethod, "result"));
+                        allFiles.push(await generateRpcDataClass(resultClassName, resultSchema, packageName, packageDir, method.rpcMethod, "result", method.stability, method.deprecated === true));
                     }
                 } else if (resultRefName && resultSchema.type === "string" && resultSchema.enum) {
                     // String enum → register for standalone generation
@@ -1373,7 +1381,9 @@ async function generateRpcDataClass(
     packageName: string,
     packageDir: string,
     rpcMethod: string,
-    kind: "params" | "result"
+    kind: "params" | "result",
+    stability?: string,
+    deprecated?: boolean
 ): Promise<string> {
     const nestedTypes = new Map<string, { code: string }>();
     const { code, imports } = generateRpcClass(className, schema, nestedTypes, packageName);
@@ -1403,15 +1413,18 @@ async function generateRpcDataClass(
     if (schema.description) {
         lines.push(`/**`);
         lines.push(` * ${schema.description}`);
-        lines.push(` *`);
-        lines.push(` * @since 1.0.0`);
-        lines.push(` */`);
     } else {
         lines.push(`/**`);
         lines.push(` * ${kind === "params" ? "Request parameters" : "Result"} for the {@code ${rpcMethod}} RPC method.`);
+    }
+    if (stability === "experimental") {
         lines.push(` *`);
-        lines.push(` * @since 1.0.0`);
-        lines.push(` */`);
+        lines.push(` * @apiNote This method is experimental and may change in a future version.`);
+    }
+    lines.push(` * @since 1.0.0`);
+    lines.push(` */`);
+    if (deprecated) {
+        lines.push(`@Deprecated`);
     }
     lines.push(GENERATED_ANNOTATION);
     lines.push(code);
@@ -1427,6 +1440,7 @@ async function generateRpcDataClass(
 interface RpcMethodNode {
     rpcMethod: string;
     stability: string;
+    deprecated: boolean;
     params: JSONSchema7 | null;
     result: JSONSchema7 | null;
 }
@@ -1447,6 +1461,7 @@ function buildNamespaceTree(node: Record<string, unknown>): NamespaceTree {
             tree.methods.set(key, {
                 rpcMethod: String(obj.rpcMethod),
                 stability: String(obj.stability ?? "stable"),
+                deprecated: obj.deprecated === true,
                 params: (obj.params as JSONSchema7) ?? null,
                 result: (obj.result as JSONSchema7) ?? null,
             });
@@ -1588,6 +1603,9 @@ function generateApiMethod(
     }
     lines.push(`     * @since 1.0.0`);
     lines.push(`     */`);
+    if (method.deprecated) {
+        lines.push(`    @Deprecated`);
+    }
 
     // Signature
     if (hasExtraParams) {

java/src/generated/java/com/github/copilot/generated/AbortEvent.java

@@ -14,7 +14,6 @@
 
 /**
  * Session event "abort". Turn abort information including the reason for termination
- *
  * @since 1.0.0
  */
 @JsonIgnoreProperties(ignoreUnknown = true)

java/src/generated/java/com/github/copilot/generated/AssistantIntentEvent.java

@@ -14,7 +14,6 @@
 
 /**
  * Session event "assistant.intent". Agent intent description for current activity or plan
- *
  * @since 1.0.0
  */
 @JsonIgnoreProperties(ignoreUnknown = true)

java/src/generated/java/com/github/copilot/generated/AssistantMessageDeltaEvent.java

@@ -14,7 +14,6 @@
 
 /**
  * Session event "assistant.message_delta". Streaming assistant message delta for incremental response updates
- *
  * @since 1.0.0
  */
 @JsonIgnoreProperties(ignoreUnknown = true)

java/src/generated/java/com/github/copilot/generated/AssistantMessageEvent.java

@@ -15,7 +15,6 @@
 
 /**
  * Session event "assistant.message". Assistant response containing text content, optional tool requests, and interaction metadata
- *
  * @since 1.0.0
  */
 @JsonIgnoreProperties(ignoreUnknown = true)

java/src/generated/java/com/github/copilot/generated/AssistantMessageStartEvent.java

@@ -14,7 +14,6 @@
 
 /**
  * Session event "assistant.message_start". Streaming assistant message start metadata
- *
  * @since 1.0.0
  */
 @JsonIgnoreProperties(ignoreUnknown = true)

java/src/generated/java/com/github/copilot/generated/AssistantReasoningDeltaEvent.java

@@ -14,7 +14,6 @@
 
 /**
  * Session event "assistant.reasoning_delta". Streaming reasoning delta for incremental extended thinking updates
- *
  * @since 1.0.0
  */
 @JsonIgnoreProperties(ignoreUnknown = true)

java/src/generated/java/com/github/copilot/generated/AssistantReasoningEvent.java

@@ -14,7 +14,6 @@
 
 /**
  * Session event "assistant.reasoning". Assistant reasoning content for timeline display with complete thinking text
- *
  * @since 1.0.0
  */
 @JsonIgnoreProperties(ignoreUnknown = true)

java/src/generated/java/com/github/copilot/generated/AssistantStreamingDeltaEvent.java

@@ -14,7 +14,6 @@
 
 /**
  * Session event "assistant.streaming_delta". Streaming response progress with cumulative byte count
- *
  * @since 1.0.0
  */
 @JsonIgnoreProperties(ignoreUnknown = true)

java/src/generated/java/com/github/copilot/generated/AssistantTurnEndEvent.java

@@ -14,7 +14,6 @@
 
 /**
  * Session event "assistant.turn_end". Turn completion metadata including the turn identifier
- *
  * @since 1.0.0
  */
 @JsonIgnoreProperties(ignoreUnknown = true)