java.ts

/*---------------------------------------------------------------------------------------------
 *  Copyright (c) Microsoft Corporation. All rights reserved.
 *--------------------------------------------------------------------------------------------*/

/**
 * Java code generator for session-events and RPC types.
 * Generates Java source files under src/generated/java/ from JSON Schema files.
 */

import fs from "fs/promises";
import type { JSONSchema7 } from "json-schema";
import path from "path";
import { fileURLToPath } from "url";

const __filename = fileURLToPath(import.meta.url);
const __dirname = path.dirname(__filename);

/** Root of the copilot-sdk-java repo */
const REPO_ROOT = path.resolve(__dirname, "../..");

/** Event types to exclude from generation (internal/legacy types) */
const EXCLUDED_EVENT_TYPES = new Set(["session.import_legacy"]);

function isSchemaInternal(schema: JSONSchema7 | null | undefined): boolean {
    return typeof schema === "object" &&
        schema !== null &&
        (schema as Record<string, unknown>).visibility === "internal";
}

const AUTO_GENERATED_HEADER = `// AUTO-GENERATED FILE - DO NOT EDIT`;
const GENERATED_FROM_SESSION_EVENTS = `// Generated from: session-events.schema.json`;
const GENERATED_FROM_API = `// Generated from: api.schema.json`;
const GENERATED_ANNOTATION = `@javax.annotation.processing.Generated("copilot-sdk-codegen")`;
const COPYRIGHT = `/*---------------------------------------------------------------------------------------------\n *  Copyright (c) Microsoft Corporation. All rights reserved.\n *--------------------------------------------------------------------------------------------*/`;

// ── Naming utilities ─────────────────────────────────────────────────────────

/**
 * Correct the GitHub brand casing in a generated identifier or documentation
 * string. Schema titles/definition names and value-derived identifiers may
 * render the brand as "Github"; the correct casing is "GitHub". Lowercase
 * wire/protocol values (e.g. "github") are left untouched. Idempotent.
 */
function fixBrandCasing(value: string): string {
    return value.replace(/Github/g, "GitHub");
}

const BRAND_NORMALIZED_STRING_KEYS = new Set(["title", "description", "markdownDescription"]);

/**
 * Recursively normalize GitHub brand casing within a parsed JSON schema:
 * definition-map keys, `$ref` pointers (definition-name segment only), and
 * documentation strings. Wire-level values (`const`, `enum`, `default`, ...) are
 * left untouched. Mutates in place and returns the schema.
 */
function normalizeSchemaBrandCasing<T>(schema: T): T {
    normalizeBrandCasingNode(schema);
    return schema;
}

function normalizeBrandCasingNode(node: unknown): void {
    if (Array.isArray(node)) {
        for (const item of node) normalizeBrandCasingNode(item);
        return;
    }
    if (node === null || typeof node !== "object") return;
    const obj = node as Record<string, unknown>;

    for (const defsKey of ["definitions", "$defs"] as const) {
        const defs = obj[defsKey];
        if (defs && typeof defs === "object" && !Array.isArray(defs)) {
            renameBrandDefinitionKeys(defs as Record<string, unknown>);
        }
    }

    for (const [key, value] of Object.entries(obj)) {
        if (typeof value === "string") {
            if (key === "$ref") {
                obj[key] = fixBrandRef(value);
            } else if (BRAND_NORMALIZED_STRING_KEYS.has(key)) {
                obj[key] = fixBrandCasing(value);
            }
        } else {
            normalizeBrandCasingNode(value);
        }
    }
}

function fixBrandRef(ref: string): string {
    const lastSlash = ref.lastIndexOf("/");
    if (lastSlash === -1) return ref;
    return `${ref.slice(0, lastSlash + 1)}${fixBrandCasing(ref.slice(lastSlash + 1))}`;
}

function stableStringify(value: unknown): string {
    if (Array.isArray(value)) {
        return `[${value.map((item) => stableStringify(item)).join(",")}]`;
    }

    if (value && typeof value === "object") {
        const entries = Object.entries(value as Record<string, unknown>).sort(([a], [b]) => a.localeCompare(b));
        return `{${entries.map(([key, entryValue]) => `${JSON.stringify(key)}:${stableStringify(entryValue)}`).join(",")}}`;
    }

    return JSON.stringify(value) ?? "undefined";
}

function renameBrandDefinitionKeys(defs: Record<string, unknown>): void {
    for (const oldKey of Object.keys(defs)) {
        const newKey = fixBrandCasing(oldKey);
        if (newKey === oldKey) continue;
        if (newKey in defs && stableStringify(defs[newKey]) !== stableStringify(defs[oldKey])) {
            throw new Error(
                `Brand-casing normalization collision: "${oldKey}" -> "${newKey}" but a different definition already exists under "${newKey}".`
            );
        }
        defs[newKey] = defs[oldKey];
        delete defs[oldKey];
    }
}

function toPascalCase(name: string): string {
    return fixBrandCasing(name.split(/[-_.]/).map((p) => p.charAt(0).toUpperCase() + p.slice(1)).join(""));
}

function toJavaClassName(typeName: string): string {
    return fixBrandCasing(typeName.split(/[._]/).map((p) => p.charAt(0).toUpperCase() + p.slice(1)).join(""));
}

/** Java reserved keywords and Object method names that cannot be used as record component names. */
const JAVA_RESERVED_IDENTIFIERS = new Set([
    "abstract", "assert", "boolean", "break", "byte", "case", "catch", "char", "class", "const",
    "continue", "default", "do", "double", "else", "enum", "extends", "final", "finally", "float",
    "for", "goto", "if", "implements", "import", "instanceof", "int", "interface", "long", "native",
    "new", "package", "private", "protected", "public", "return", "short", "static", "strictfp",
    "super", "switch", "synchronized", "this", "throw", "throws", "transient", "try", "void",
    "volatile", "while",
    // Object methods that conflict with record component accessor names
    "wait", "notify", "notifyAll", "getClass", "clone", "finalize", "toString", "hashCode", "equals",
]);

function toCamelCase(name: string): string {
    const pascal = toPascalCase(name);
    let result = pascal.charAt(0).toLowerCase() + pascal.slice(1);
    if (JAVA_RESERVED_IDENTIFIERS.has(result)) {
        result = result + "_";
    }
    return result;
}

function toEnumConstant(value: string): string {
    return value.toUpperCase().replace(/[-. /:]/g, "_").replace(/^_+/, "").replace(/_+/g, "_");
}

// ── Schema path resolution ───────────────────────────────────────────────────

/**
 * Resolve a JSON schema shipped by the `@github/copilot` CLI package.
 *
 * The CLI package layout changed in 1.0.64-1: the umbrella `@github/copilot`
 * package became a thin loader and its bundled assets (including the JSON
 * schemas) moved into the platform-specific packages installed as optional
 * dependencies, e.g. `@github/copilot-linux-x64` or `@github/copilot-win32-x64`.
 *
 * We search both the Java codegen install (`scripts/codegen/node_modules`) and
 * the Node SDK install (`nodejs/node_modules`), checking the umbrella package
 * first (older versions) and then whichever platform package is present.
 */
async function resolveCopilotSchemaPath(fileName: string): Promise<string> {
    const nodeModulesDirs = [
        path.join(REPO_ROOT, "scripts/codegen/node_modules"),
        path.join(REPO_ROOT, "nodejs/node_modules"),
    ];

    const candidates: string[] = [];
    for (const nodeModulesDir of nodeModulesDirs) {
        candidates.push(path.join(nodeModulesDir, "@github/copilot/schemas", fileName));
        const githubScopeDir = path.join(nodeModulesDir, "@github");
        try {
            for (const entry of await fs.readdir(githubScopeDir)) {
                if (entry.startsWith("copilot-")) {
                    candidates.push(path.join(githubScopeDir, entry, "schemas", fileName));
                }
            }
        } catch (err) {
            const code = (err as NodeJS.ErrnoException).code;
            if (code !== "ENOENT" && code !== "ENOTDIR") {
                throw err;
            }
            // @github scope directory may not exist; try the next location.
        }
    }

    for (const candidate of candidates) {
        try {
            await fs.access(candidate);
            return candidate;
        } catch {
            // Try the next candidate.
        }
    }

    throw new Error(`${fileName} not found. Run 'npm ci' in java/scripts/codegen or java/nodejs first.`);
}

async function getSessionEventsSchemaPath(): Promise<string> {
    return resolveCopilotSchemaPath("session-events.schema.json");
}

async function getApiSchemaPath(): Promise<string> {
    return resolveCopilotSchemaPath("api.schema.json");
}

// ── File writing ─────────────────────────────────────────────────────────────

async function writeGeneratedFile(relativePath: string, content: string): Promise<string> {
    const fullPath = path.join(REPO_ROOT, relativePath);
    await fs.mkdir(path.dirname(fullPath), { recursive: true });
    await fs.writeFile(fullPath, content, "utf-8");
    console.log(`  ✓ ${relativePath}`);
    return fullPath;
}

// ── Java type mapping ─────────────────────────────────────────────────────────

interface JavaTypeResult {
    javaType: string;
    imports: Set<string>;
}

// Module-level state for $ref resolution during codegen.
// Set before each schema generation pass; used by schemaTypeToJava and helpers.
let currentDefinitions: Record<string, JSONSchema7> = {};
const pendingStandaloneTypes = new Map<string, JSONSchema7>();

// Cross-schema definitions: keyed by schema filename (e.g. "session-events.schema.json"),
// value is the definitions map from that schema. Populated by generateRpcTypes so that
// cross-schema $ref values like "session-events.schema.json#/definitions/Foo" can be resolved.
const crossSchemaDefinitions = new Map<string, Record<string, JSONSchema7>>();

/**
 * Resolve a $ref in a JSON Schema against the current definitions.
 * Returns the resolved schema, or the original if no $ref is present.
 */
function resolveRef(schema: JSONSchema7 | undefined): JSONSchema7 | undefined {
    if (!schema) return schema;
    if (schema.$ref) {
        const name = schema.$ref.replace(/^#\/definitions\//, "");
        const resolved = currentDefinitions[name];
        if (!resolved) {
            console.warn(`[codegen] Unresolved $ref: ${schema.$ref}`);
            return schema;
        }
        return resolved;
    }
    return schema;
}

/** Extract the definition name from a $ref string (e.g., "#/definitions/Foo" → "Foo") */
function extractRefName(schema: JSONSchema7 | null | undefined): string | null {
    if (!schema?.$ref) return null;
    // Handle cross-schema refs
    const crossMatch = schema.$ref.match(/^[^#]+#\/definitions\/(.+)$/);
    if (crossMatch) return crossMatch[1];
    return schema.$ref.replace(/^#\/definitions\//, "");
}

// ── Discriminated union support ─────────────────────────────────────────────

interface DiscriminatorInfo {
    property: string;
    mapping: Map<string, { value: unknown; schema: JSONSchema7 }>;
}

/**
 * Find a discriminator property shared by all variants in an anyOf.
 * A discriminator is a property with a `const` value that uniquely identifies each variant.
 */
function findDiscriminator(variants: JSONSchema7[]): DiscriminatorInfo | null {
    if (variants.length === 0) return null;
    const firstVariant = variants[0];
    if (!firstVariant.properties) return null;

    for (const [propName, propSchema] of Object.entries(firstVariant.properties).sort(([a], [b]) => a.localeCompare(b))) {
        if (typeof propSchema !== "object") continue;
        const schema = propSchema as JSONSchema7;
        if (schema.const === undefined) continue;

        const mapping = new Map<string, { value: unknown; schema: JSONSchema7 }>();
        let isValidDiscriminator = true;

        for (const variant of variants) {
            if (!variant.properties) { isValidDiscriminator = false; break; }
            const variantProp = variant.properties[propName];
            if (typeof variantProp !== "object") { isValidDiscriminator = false; break; }
            const variantSchema = variantProp as JSONSchema7;
            if (variantSchema.const === undefined) { isValidDiscriminator = false; break; }
            const key = String(variantSchema.const);
            if (mapping.has(key)) { isValidDiscriminator = false; break; }
            mapping.set(key, { value: variantSchema.const, schema: variant });
        }

        if (isValidDiscriminator && mapping.size === variants.length) {
            return { property: propName, mapping };
        }
    }
    return null;
}

/**
 * Resolve anyOf variants, handling $ref to definitions.
 */
function resolveAnyOfVariants(anyOf: JSONSchema7[]): JSONSchema7[] {
    return anyOf
        .map((v) => {
            if (v.$ref) {
                const name = v.$ref.replace(/^#\/definitions\//, "");
                return currentDefinitions[name] ?? v;
            }
            return v;
        })
        .filter((v) => v.type !== "null");
}

/**
 * Generate a polymorphic base class and variant subclasses for a discriminated union result type.
 */
async function generatePolymorphicResultClass(
    className: string,
    schema: JSONSchema7,
    packageName: string,
    packageDir: string
): Promise<void> {
    const anyOf = schema.anyOf as JSONSchema7[];
    const variants = resolveAnyOfVariants(anyOf);
    const discriminator = findDiscriminator(variants);

    if (!discriminator) {
        console.warn(`[codegen] Cannot find discriminator for ${className} — skipping polymorphic generation`);
        return;
    }

    // Collect variant info
    interface VariantInfo {
        discriminatorValue: string;
        variantClassName: string;
        schema: JSONSchema7;
    }

    const variantInfos: VariantInfo[] = [];
    for (const [discValue, { schema: variantSchema }] of discriminator.mapping) {
        const variantClassName = (variantSchema as JSONSchema7 & { title?: string }).title ?? `${className}${toPascalCase(discValue)}`;
        variantInfos.push({ discriminatorValue: discValue, variantClassName, schema: variantSchema });
    }

    // Generate the abstract base class
    const baseLines: string[] = [];
    baseLines.push(COPYRIGHT);
    baseLines.push("");
    baseLines.push(AUTO_GENERATED_HEADER);
    baseLines.push(GENERATED_FROM_API);
    baseLines.push("");
    baseLines.push(`package ${packageName};`);
    baseLines.push("");
    baseLines.push(`import com.fasterxml.jackson.annotation.JsonIgnoreProperties;`);
    baseLines.push(`import com.fasterxml.jackson.annotation.JsonSubTypes;`);
    baseLines.push(`import com.fasterxml.jackson.annotation.JsonTypeInfo;`);
    baseLines.push(`import javax.annotation.processing.Generated;`);
    baseLines.push("");
    if (schema.description) {
        baseLines.push(`/**`);
        baseLines.push(` * ${schema.description}`);
        baseLines.push(` *`);
        baseLines.push(` * @since 1.0.0`);
        baseLines.push(` */`);
    }
    baseLines.push(`@JsonTypeInfo(use = JsonTypeInfo.Id.NAME, property = "${discriminator.property}", visible = true)`);
    baseLines.push(`@JsonSubTypes({`);
    for (let i = 0; i < variantInfos.length; i++) {
        const v = variantInfos[i];
        const comma = i < variantInfos.length - 1 ? "," : "";
        baseLines.push(`    @JsonSubTypes.Type(value = ${v.variantClassName}.class, name = "${v.discriminatorValue}")${comma}`);
    }
    baseLines.push(`})`);
    baseLines.push(`@JsonIgnoreProperties(ignoreUnknown = true)`);
    baseLines.push(GENERATED_ANNOTATION);
    baseLines.push(`public abstract class ${className} {`);
    baseLines.push("");
    baseLines.push(`    /**`);
    baseLines.push(`     * Returns the discriminator value for this variant.`);
    baseLines.push(`     *`);
    baseLines.push(`     * @return the ${discriminator.property} discriminator`);
    baseLines.push(`     */`);
    baseLines.push(`    public abstract String get${toPascalCase(discriminator.property)}();`);
    baseLines.push(`}`);
    baseLines.push("");

    await writeGeneratedFile(`${packageDir}/${className}.java`, baseLines.join("\n"));

    // Generate each variant subclass
    for (const variant of variantInfos) {
        await generatePolymorphicVariantClass(variant.variantClassName, variant.schema, variant.discriminatorValue, discriminator.property, className, packageName, packageDir);
    }
}

/**
 * Generate a single variant subclass of a polymorphic result type.
 */
async function generatePolymorphicVariantClass(
    className: string,
    schema: JSONSchema7,
    discriminatorValue: string,
    discriminatorProperty: string,
    baseClassName: string,
    packageName: string,
    packageDir: string
): Promise<void> {
    const allImports = new Set<string>([
        "com.fasterxml.jackson.annotation.JsonIgnoreProperties",
        "com.fasterxml.jackson.annotation.JsonInclude",
        "com.fasterxml.jackson.annotation.JsonProperty",
        "javax.annotation.processing.Generated",
    ]);
    const nestedTypes = new Map<string, JavaClassDef>();

    // Collect fields (excluding the discriminator property)
    interface FieldInfo {
        jsonName: string;
        javaName: string;
        javaType: string;
        description?: string;
    }

    const fields: FieldInfo[] = [];
    if (schema.properties) {
        for (const [propName, propSchema] of Object.entries(schema.properties)) {
            if (propName === discriminatorProperty) continue;
            if (typeof propSchema !== "object") continue;
            const prop = propSchema as JSONSchema7;
            const result = schemaTypeToJava(prop, false, className, propName, nestedTypes);
            for (const imp of result.imports) allImports.add(imp);
            fields.push({
                jsonName: propName,
                javaName: toCamelCase(propName),
                javaType: result.javaType,
                description: prop.description,
            });
        }
    }

    const lines: string[] = [];
    lines.push(COPYRIGHT);
    lines.push("");
    lines.push(AUTO_GENERATED_HEADER);
    lines.push(GENERATED_FROM_API);
    lines.push("");
    lines.push(`package ${packageName};`);
    lines.push("");

    // Placeholder for imports
    const importPlaceholderIdx = lines.length;
    lines.push("__IMPORTS__");
    lines.push("");

    if (schema.description) {
        lines.push(`/**`);
        lines.push(` * ${schema.description}`);
        lines.push(` *`);
        lines.push(` * @since 1.0.0`);
        lines.push(` */`);
    } else {
        lines.push(`/**`);
        lines.push(` * Variant {@code ${discriminatorValue}} of {@link ${baseClassName}}.`);
        lines.push(` *`);
        lines.push(` * @since 1.0.0`);
        lines.push(` */`);
    }
    lines.push(`@JsonIgnoreProperties(ignoreUnknown = true)`);
    lines.push(`@JsonInclude(JsonInclude.Include.NON_NULL)`);
    lines.push(GENERATED_ANNOTATION);
    lines.push(`public final class ${className} extends ${baseClassName} {`);
    lines.push("");

    // Discriminator field
    lines.push(`    @JsonProperty("${discriminatorProperty}")`);
    lines.push(`    private final String ${toCamelCase(discriminatorProperty)} = "${discriminatorValue}";`);
    lines.push("");
    lines.push(`    @Override`);
    lines.push(`    public String get${toPascalCase(discriminatorProperty)}() { return ${toCamelCase(discriminatorProperty)}; }`);
    lines.push("");

    // Other fields
    for (const field of fields) {
        if (field.description) {
            lines.push(`    /** ${field.description} */`);
        }
        lines.push(`    @JsonProperty("${field.jsonName}")`);
        lines.push(`    private ${field.javaType} ${field.javaName};`);
        lines.push("");
    }

    // Getters and setters
    for (const field of fields) {
        lines.push(`    public ${field.javaType} get${field.javaName.charAt(0).toUpperCase() + field.javaName.slice(1)}() { return ${field.javaName}; }`);
        lines.push(`    public void set${field.javaName.charAt(0).toUpperCase() + field.javaName.slice(1)}(${field.javaType} ${field.javaName}) { this.${field.javaName} = ${field.javaName}; }`);
        lines.push("");
    }

    // Render nested types
    for (const [, nested] of nestedTypes) {
        lines.push(...renderNestedType(nested, 1, new Map(), allImports));
    }

    if (lines[lines.length - 1] === "") lines.pop();
    lines.push(`}`);
    lines.push("");

    // Replace import placeholder
    const sortedImports = [...allImports].sort();
    const importLines = sortedImports.map((i) => `import ${i};`).join("\n");
    lines[importPlaceholderIdx] = importLines;

    await writeGeneratedFile(`${packageDir}/${className}.java`, lines.join("\n"));
}

function schemaTypeToJava(
    schema: JSONSchema7,
    required: boolean,
    context: string,
    propName: string,
    nestedTypes: Map<string, JavaClassDef>
): JavaTypeResult {
    const imports = new Set<string>();

    // Resolve $ref first — register standalone types for generation
    if (schema.$ref) {
        // Handle cross-schema $ref (e.g. "session-events.schema.json#/definitions/Foo")
        const crossSchemaMatch = schema.$ref.match(/^([^#]+)#\/definitions\/(.+)$/);
        if (crossSchemaMatch) {
            const [, schemaFile, typeName] = crossSchemaMatch;
            const externalDefs = crossSchemaDefinitions.get(schemaFile);
            if (externalDefs) {
                const resolved = externalDefs[typeName];
                if (resolved) {
                    // Save and swap currentDefinitions so recursive calls resolve against
                    // the external schema's definitions.
                    const savedDefs = currentDefinitions;
                    currentDefinitions = externalDefs;
                    const result = schemaTypeToJava(resolved, required, context, propName, nestedTypes);
                    currentDefinitions = savedDefs;
                    return result;
                }
            }
            // Fallback: extract just the type name and warn
            console.warn(`[codegen] Unresolved cross-schema $ref: ${schema.$ref}`);
            return { javaType: typeName, imports };
        }

        const name = schema.$ref.replace(/^#\/definitions\//, "");
        const resolved = currentDefinitions[name];
        if (resolved) {
            // Enum or object types → register for standalone generation, return ref name
            if ((resolved.type === "string" && resolved.enum) ||
                (resolved.type === "object" && resolved.properties)) {
                pendingStandaloneTypes.set(name, resolved);
                return { javaType: name, imports };
            }
            // Other types (primitives, arrays, maps, anyOf unions) → resolve and recurse
            return schemaTypeToJava(resolved, required, context, propName, nestedTypes);
        }
        // Unresolved $ref — return name as-is
        console.warn(`[codegen] Unresolved $ref: ${schema.$ref}`);
        return { javaType: name, imports };
    }

    if (schema.anyOf) {
        const hasNull = schema.anyOf.some((s) => typeof s === "object" && (s as JSONSchema7).type === "null");
        const nonNull = schema.anyOf.filter((s) => typeof s === "object" && (s as JSONSchema7).type !== "null");
        if (nonNull.length === 1) {
            const result = schemaTypeToJava(nonNull[0] as JSONSchema7, required && !hasNull, context, propName, nestedTypes);
            return result;
        }
        // Multi-branch anyOf: fall through to Object, matching the C# generator's
        // behavior.  Java has no union types, so Object is the correct erasure for
        // anyOf[string, object] and similar multi-variant schemas.
        console.warn(`[codegen] ${context}.${propName}: anyOf with ${nonNull.length} non-null branches — falling back to Object`);
        return { javaType: "Object", imports };
    }

    if (schema.type === "string") {
        if (schema.format === "uuid") {
            imports.add("java.util.UUID");
            return { javaType: "UUID", imports };
        }
        if (schema.format === "date-time") {
            imports.add("java.time.OffsetDateTime");
            return { javaType: "OffsetDateTime", imports };
        }
        if (schema.enum && Array.isArray(schema.enum)) {
            const enumName = `${context}${toPascalCase(propName)}`;
            nestedTypes.set(enumName, {
                kind: "enum",
                name: enumName,
                values: schema.enum as string[],
                description: schema.description,
            });
            return { javaType: enumName, imports };
        }
        return { javaType: "String", imports };
    }

    if (Array.isArray(schema.type)) {
        const nonNullTypes = schema.type.filter((t) => t !== "null");
        if (nonNullTypes.length === 1) {
            const baseSchema = { ...schema, type: nonNullTypes[0] };
            return schemaTypeToJava(baseSchema as JSONSchema7, required, context, propName, nestedTypes);
        }
    }

    if (schema.type === "integer") {
        // JSON Schema "integer" maps to Long (boxed — always used for records).
        // Use primitive long for required fields in mutable-bean contexts if needed.
        return { javaType: required ? "long" : "Long", imports };
    }

    if (schema.type === "number") {
        return { javaType: required ? "double" : "Double", imports };
    }

    if (schema.type === "boolean") {
        return { javaType: required ? "boolean" : "Boolean", imports };
    }

    if (schema.type === "array") {
        const items = schema.items as JSONSchema7 | undefined;
        if (items) {
            // Always pass required=false so primitives are boxed (List<Long>, not List<long>)
            const itemResult = schemaTypeToJava(items, false, context, propName + "Item", nestedTypes);
            imports.add("java.util.List");
            for (const imp of itemResult.imports) imports.add(imp);
            return { javaType: `List<${itemResult.javaType}>`, imports };
        }
        imports.add("java.util.List");
        console.warn(`[codegen] ${context}.${propName}: array without typed items — falling back to List<Object>`);
        return { javaType: "List<Object>", imports };
    }

    if (schema.type === "object") {
        if (schema.properties && Object.keys(schema.properties).length > 0) {
            const nestedName = `${context}${toPascalCase(propName)}`;
            if (!nestedTypes.has(nestedName)) {
                nestedTypes.set(nestedName, {
                    kind: "class",
                    name: nestedName,
                    schema,
                    description: schema.description,
                });
            }
            return { javaType: nestedName, imports };
        }
        if (schema.additionalProperties) {
            const valueSchema = typeof schema.additionalProperties === "object"
                ? schema.additionalProperties as JSONSchema7
                : { type: "object" } as JSONSchema7;
            // Always pass required=false so primitives are boxed (Map<String, Long>, not Map<String, long>)
            const valueResult = schemaTypeToJava(valueSchema, false, context, propName + "Value", nestedTypes);
            imports.add("java.util.Map");
            for (const imp of valueResult.imports) imports.add(imp);
            return { javaType: `Map<String, ${valueResult.javaType}>`, imports };
        }
        imports.add("java.util.Map");
        console.warn(`[codegen] ${context}.${propName}: object without typed properties or additionalProperties — falling back to Map<String, Object>`);
        return { javaType: "Map<String, Object>", imports };
    }

    console.warn(`[codegen] ${context}.${propName}: unrecognized schema (type=${JSON.stringify(schema.type)}) — falling back to Object`);
    return { javaType: "Object", imports };
}

// ── Class definitions ─────────────────────────────────────────────────────────

interface JavaClassDef {
    kind: "class" | "enum";
    name: string;
    description?: string;
    schema?: JSONSchema7;
    values?: string[];  // for enum
}

// ── Session Events codegen ────────────────────────────────────────────────────

interface EventVariant {
    typeName: string;
    className: string;
    dataSchema: JSONSchema7 | null;
    description?: string;
    stability?: string;
    deprecated?: boolean;
}

function extractEventVariants(schema: JSONSchema7): EventVariant[] {
    const definitions = schema.definitions as Record<string, JSONSchema7>;
    const sessionEvent = definitions?.SessionEvent;
    if (!sessionEvent?.anyOf) throw new Error("Schema must have SessionEvent definition with anyOf");

    return (sessionEvent.anyOf as JSONSchema7[])
        .map((variant) => {
            // Resolve $ref if present (1.0.35+ schema uses $ref to named definitions)
            let resolved = variant;
            if (variant.$ref) {
                const refName = variant.$ref.replace(/^#\/definitions\//, "");
                resolved = definitions[refName];
                if (!resolved) throw new Error(`Unresolved $ref: ${variant.$ref}`);
            }
            const typeSchema = resolved.properties?.type as JSONSchema7;
            const typeName = typeSchema?.const as string;
            if (!typeName) throw new Error("Variant must have type.const");
            const baseName = toJavaClassName(typeName);
            let dataSchema = resolved.properties?.data as JSONSchema7 | undefined;
            // Resolve $ref on data schema if present
            if (dataSchema?.$ref) {
                const dataRefName = dataSchema.$ref.replace(/^#\/definitions\//, "");
                dataSchema = definitions[dataRefName];
            }
            return {
                typeName,
                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) && !isSchemaInternal(v.dataSchema));
}

async function generateSessionEvents(schemaPath: string): Promise<void> {
    console.log("\n📋 Generating session event classes...");
    const schemaContent = await fs.readFile(schemaPath, "utf-8");
    const schema = normalizeSchemaBrandCasing(JSON.parse(schemaContent) as JSONSchema7);

    // Set module-level definitions for $ref resolution
    currentDefinitions = (schema.definitions ?? {}) as Record<string, JSONSchema7>;
    pendingStandaloneTypes.clear();

    const variants = extractEventVariants(schema);
    const packageName = "com.github.copilot.generated";
    const packageDir = `src/generated/java/com/github/copilot/generated`;

    // Generate base SessionEvent class
    await generateSessionEventBaseClass(variants, packageName, packageDir);

    // Generate one class file per event variant
    for (const variant of variants) {
        await generateEventVariantClass(variant, packageName, packageDir);
    }

    // Generate standalone types discovered via $ref resolution
    await generatePendingStandaloneTypes(packageName, packageDir, GENERATED_FROM_SESSION_EVENTS);

    console.log(`✅ Generated ${variants.length + 1} session event files`);
}

async function generateSessionEventBaseClass(
    variants: EventVariant[],
    packageName: string,
    packageDir: string
): Promise<void> {
    const lines: string[] = [];
    lines.push(COPYRIGHT);
    lines.push("");
    lines.push(AUTO_GENERATED_HEADER);
    lines.push(GENERATED_FROM_SESSION_EVENTS);
    lines.push("");
    lines.push(`package ${packageName};`);
    lines.push("");
    lines.push(`import com.fasterxml.jackson.annotation.JsonIgnoreProperties;`);
    lines.push(`import com.fasterxml.jackson.annotation.JsonInclude;`);
    lines.push(`import com.fasterxml.jackson.annotation.JsonProperty;`);
    lines.push(`import com.fasterxml.jackson.annotation.JsonSubTypes;`);
    lines.push(`import com.fasterxml.jackson.annotation.JsonTypeInfo;`);
    lines.push(`import java.time.OffsetDateTime;`);
    lines.push(`import java.util.UUID;`);
    lines.push(`import javax.annotation.processing.Generated;`);
    lines.push("");
    lines.push(`/**`);
    lines.push(` * Base class for all generated session events.`);
    lines.push(` *`);
    lines.push(` * @since 1.0.0`);
    lines.push(` */`);
    lines.push(`@JsonIgnoreProperties(ignoreUnknown = true)`);
    lines.push(`@JsonInclude(JsonInclude.Include.NON_NULL)`);
    lines.push(`@JsonTypeInfo(use = JsonTypeInfo.Id.NAME, property = "type", visible = true, defaultImpl = UnknownSessionEvent.class)`);
    lines.push(`@JsonSubTypes({`);
    for (let i = 0; i < variants.length; i++) {
        const v = variants[i];
        const comma = i < variants.length - 1 ? "," : "";
        lines.push(`    @JsonSubTypes.Type(value = ${v.className}.class, name = "${v.typeName}")${comma}`);
    }
    lines.push(`})`);
    lines.push(GENERATED_ANNOTATION);

    // Build the permits clause (all variant classes + UnknownSessionEvent last)
    const allPermitted = [...variants.map((v) => v.className), "UnknownSessionEvent"];
    lines.push(`public abstract sealed class SessionEvent permits`);
    for (let i = 0; i < allPermitted.length; i++) {
        const comma = i < allPermitted.length - 1 ? "," : " {";
        lines.push(`        ${allPermitted[i]}${comma}`);
    }
    lines.push("");
    lines.push(`    /** Unique event identifier (UUID v4), generated when the event is emitted. */`);
    lines.push(`    @JsonProperty("id")`);
    lines.push(`    private UUID id;`);
    lines.push("");
    lines.push(`    /** ISO 8601 timestamp when the event was created. */`);
    lines.push(`    @JsonProperty("timestamp")`);
    lines.push(`    private OffsetDateTime timestamp;`);
    lines.push("");
    lines.push(`    /** ID of the chronologically preceding event in the session. Null for the first event. */`);
    lines.push(`    @JsonProperty("parentId")`);
    lines.push(`    private UUID parentId;`);
    lines.push("");
    lines.push(`    /** Sub-agent instance identifier. Absent for events from the root/main agent and session-level events. */`);
    lines.push(`    @JsonProperty("agentId")`);
    lines.push(`    private String agentId;`);
    lines.push("");
    lines.push(`    /** When true, the event is transient and not persisted to the session event log on disk. */`);
    lines.push(`    @JsonProperty("ephemeral")`);
    lines.push(`    private Boolean ephemeral;`);
    lines.push("");
    lines.push(`    /**`);
    lines.push(`     * Returns the event-type discriminator string (e.g., {@code "session.idle"}).`);
    lines.push(`     *`);
    lines.push(`     * @return the event type`);
    lines.push(`     */`);
    lines.push(`    public abstract String getType();`);
    lines.push("");
    lines.push(`    public UUID getId() { return id; }`);
    lines.push(`    public void setId(UUID id) { this.id = id; }`);
    lines.push("");
    lines.push(`    public OffsetDateTime getTimestamp() { return timestamp; }`);
    lines.push(`    public void setTimestamp(OffsetDateTime timestamp) { this.timestamp = timestamp; }`);
    lines.push("");
    lines.push(`    public UUID getParentId() { return parentId; }`);
    lines.push(`    public void setParentId(UUID parentId) { this.parentId = parentId; }`);
    lines.push("");
    lines.push(`    public String getAgentId() { return agentId; }`);
    lines.push(`    public void setAgentId(String agentId) { this.agentId = agentId; }`);
    lines.push("");
    lines.push(`    public Boolean getEphemeral() { return ephemeral; }`);
    lines.push(`    public void setEphemeral(Boolean ephemeral) { this.ephemeral = ephemeral; }`);
    lines.push(`}`);
    lines.push("");

    await writeGeneratedFile(`${packageDir}/SessionEvent.java`, lines.join("\n"));

    // Also generate the UnknownSessionEvent fallback
    await generateUnknownEventClass(packageName, packageDir);
}

async function generateUnknownEventClass(packageName: string, packageDir: string): Promise<void> {
    const lines: string[] = [];
    lines.push(COPYRIGHT);
    lines.push("");
    lines.push(AUTO_GENERATED_HEADER);
    lines.push(GENERATED_FROM_SESSION_EVENTS);
    lines.push("");
    lines.push(`package ${packageName};`);
    lines.push("");
    lines.push(`import com.fasterxml.jackson.annotation.JsonIgnoreProperties;`);
    lines.push(`import com.fasterxml.jackson.annotation.JsonProperty;`);
    lines.push(`import javax.annotation.processing.Generated;`);
    lines.push("");
    lines.push(`/**`);
    lines.push(` * Fallback for event types not yet known to this SDK version.`);
    lines.push(` * <p>`);
    lines.push(` * {@link #getType()} returns the original type string from the JSON payload,`);
    lines.push(` * preserving forward compatibility with event types introduced by newer CLI versions.`);
    lines.push(` *`);
    lines.push(` * @since 1.0.0`);
    lines.push(` */`);
    lines.push(`@JsonIgnoreProperties(ignoreUnknown = true)`);
    lines.push(GENERATED_ANNOTATION);
    lines.push(`public final class UnknownSessionEvent extends SessionEvent {`);
    lines.push("");
    lines.push(`    @JsonProperty("type")`);
    lines.push(`    private String type = "unknown";`);
    lines.push("");
    lines.push(`    @Override`);
    lines.push(`    public String getType() { return type; }`);
    lines.push(`}`);
    lines.push("");

    await writeGeneratedFile(`${packageDir}/UnknownSessionEvent.java`, lines.join("\n"));
}

/** Render a nested type (enum or record) indented at the given level. */
function renderNestedType(nested: JavaClassDef, indentLevel: number, nestedTypes: Map<string, JavaClassDef>, allImports: Set<string>): string[] {
    const ind = "    ".repeat(indentLevel);
    const lines: string[] = [];

    if (nested.kind === "enum") {
        lines.push("");
        if (nested.description) {
            lines.push(`${ind}/** ${nested.description} */`);
        }
        lines.push(`${ind}public enum ${nested.name} {`);
        for (let i = 0; i < (nested.values || []).length; i++) {
            const v = nested.values![i];
            const comma = i < nested.values!.length - 1 ? "," : ";";
            lines.push(`${ind}    /** The {@code ${v}} variant. */`);
            lines.push(`${ind}    ${toEnumConstant(v)}("${v}")${comma}`);
        }
        lines.push("");
        lines.push(`${ind}    private final String value;`);
        lines.push(`${ind}    ${nested.name}(String value) { this.value = value; }`);
        lines.push(`${ind}    @com.fasterxml.jackson.annotation.JsonValue`);
        lines.push(`${ind}    public String getValue() { return value; }`);
        lines.push(`${ind}    @com.fasterxml.jackson.annotation.JsonCreator`);
        lines.push(`${ind}    public static ${nested.name} fromValue(String value) {`);
        lines.push(`${ind}        for (${nested.name} v : values()) {`);
        lines.push(`${ind}            if (v.value.equals(value)) return v;`);
        lines.push(`${ind}        }`);
        lines.push(`${ind}        throw new IllegalArgumentException("Unknown ${nested.name} value: " + value);`);
        lines.push(`${ind}    }`);
        lines.push(`${ind}}`);
    } else if (nested.kind === "class" && nested.schema?.properties) {
        const localNestedTypes = new Map<string, JavaClassDef>();
        const fields: { jsonName: string; javaName: string; javaType: string; description?: string }[] = [];

        for (const [propName, propSchema] of Object.entries(nested.schema.properties)) {
            if (typeof propSchema !== "object") continue;
            const prop = propSchema as JSONSchema7;
            // Record components are always boxed (nullable by design).
            const result = schemaTypeToJava(prop, false, nested.name, propName, localNestedTypes);
            for (const imp of result.imports) allImports.add(imp);
            fields.push({ jsonName: propName, javaName: toCamelCase(propName), javaType: result.javaType, description: prop.description });
        }

        lines.push("");
        if (nested.description) {
            lines.push(`${ind}/** ${nested.description} */`);
        }
        lines.push(`${ind}@JsonIgnoreProperties(ignoreUnknown = true)`);
        lines.push(`${ind}@JsonInclude(JsonInclude.Include.NON_NULL)`);
        if (fields.length === 0) {
            lines.push(`${ind}public record ${nested.name}() {`);
        } else {
            lines.push(`${ind}public record ${nested.name}(`);
            for (let i = 0; i < fields.length; i++) {
                const f = fields[i];
                const comma = i < fields.length - 1 ? "," : "";
                if (f.description) lines.push(`${ind}    /** ${f.description} */`);
                lines.push(`${ind}    @JsonProperty("${f.jsonName}") ${f.javaType} ${f.javaName}${comma}`);
            }
            lines.push(`${ind}) {`);
        }
        // Render any further nested types inside this record
        for (const [, localNested] of localNestedTypes) {
            lines.push(...renderNestedType(localNested, indentLevel + 1, nestedTypes, allImports));
        }
        if (lines[lines.length - 1] !== "") lines.push("");
        lines.pop(); // remove trailing blank before closing brace
        lines.push(`${ind}}`);
    }

    return lines;
}

async function generateEventVariantClass(
    variant: EventVariant,
    packageName: string,
    packageDir: string
): Promise<void> {
    const lines: string[] = [];
    const allImports = new Set<string>([
        "com.fasterxml.jackson.annotation.JsonIgnoreProperties",
        "com.fasterxml.jackson.annotation.JsonProperty",
        "com.fasterxml.jackson.annotation.JsonInclude",
        "javax.annotation.processing.Generated",
    ]);
    const nestedTypes = new Map<string, JavaClassDef>();

    // Collect data record fields
    interface FieldInfo {
        jsonName: string;
        javaName: string;
        javaType: string;
        description?: string;
    }

    const dataFields: FieldInfo[] = [];

    if (variant.dataSchema?.properties) {
        for (const [propName, propSchema] of Object.entries(variant.dataSchema.properties)) {
            if (typeof propSchema !== "object") continue;
            const prop = propSchema as JSONSchema7;
            // Record components are always boxed (nullable by design).
            const result = schemaTypeToJava(prop, false, `${variant.className}Data`, propName, nestedTypes);
            for (const imp of result.imports) allImports.add(imp);
            dataFields.push({
                jsonName: propName,
                javaName: toCamelCase(propName),
                javaType: result.javaType,
                description: prop.description,
            });
        }
    }

    // Whether a data record should be emitted (always when dataSchema is present)
    const hasDataSchema = variant.dataSchema !== null;

    // Build the file
    lines.push(COPYRIGHT);
    lines.push("");
    lines.push(AUTO_GENERATED_HEADER);
    lines.push(GENERATED_FROM_SESSION_EVENTS);
    lines.push("");
    lines.push(`package ${packageName};`);
    lines.push("");

    // Placeholder for imports
    const importPlaceholderIdx = lines.length;
    lines.push("__IMPORTS__");
    lines.push("");

    if (variant.description) {
        lines.push(`/**`);
        lines.push(` * ${variant.description}`);
    } else {
        lines.push(`/**`);
        lines.push(` * The {@code ${variant.typeName}} session event.`);
    }
    if (variant.stability === "experimental") {
        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`);
    }
    if (variant.stability === "experimental") {
        allImports.add("com.github.copilot.CopilotExperimental");
        lines.push(`@CopilotExperimental`);
    }
    lines.push(`@JsonIgnoreProperties(ignoreUnknown = true)`);
    lines.push(`@JsonInclude(JsonInclude.Include.NON_NULL)`);
    lines.push(GENERATED_ANNOTATION);
    lines.push(`public final class ${variant.className} extends SessionEvent {`);
    lines.push("");
    lines.push(`    @Override`);
    lines.push(`    public String getType() { return "${variant.typeName}"; }`);

    if (hasDataSchema) {
        lines.push("");
        lines.push(`    @JsonProperty("data")`);
        lines.push(`    private ${variant.className}Data data;`);
        lines.push("");
        lines.push(`    public ${variant.className}Data getData() { return data; }`);
        lines.push(`    public void setData(${variant.className}Data data) { this.data = data; }`);
        lines.push("");
        // Generate data inner record
        lines.push(`    /** Data payload for {@link ${variant.className}}. */`);
        lines.push(`    @JsonIgnoreProperties(ignoreUnknown = true)`);
        lines.push(`    @JsonInclude(JsonInclude.Include.NON_NULL)`);
        if (dataFields.length === 0) {
            lines.push(`    public record ${variant.className}Data() {`);
        } else {
            lines.push(`    public record ${variant.className}Data(`);
            for (let i = 0; i < dataFields.length; i++) {
                const field = dataFields[i];
                const comma = i < dataFields.length - 1 ? "," : "";
                if (field.description) {
                    lines.push(`        /** ${field.description} */`);
                }
                lines.push(`        @JsonProperty("${field.jsonName}") ${field.javaType} ${field.javaName}${comma}`);
            }
            lines.push(`    ) {`);
        }
        // Render nested types inside Data record
        for (const [, nested] of nestedTypes) {
            lines.push(...renderNestedType(nested, 2, nestedTypes, allImports));
        }
        if (nestedTypes.size > 0 && lines[lines.length - 1] === "") lines.pop();
        lines.push(`    }`);
    }

    lines.push(`}`);
    lines.push("");

    // Replace import placeholder
    const sortedImports = [...allImports].sort();
    const importLines = sortedImports.map((i) => `import ${i};`).join("\n");
    lines[importPlaceholderIdx] = importLines;

    await writeGeneratedFile(`${packageDir}/${variant.className}.java`, lines.join("\n"));
}

// ── Standalone $ref type generation ──────────────────────────────────────────

/**
 * Generate all pending standalone types discovered via $ref resolution.
 * Iterates until no new types are discovered (handles transitive $ref chains).
 */
async function generatePendingStandaloneTypes(
    packageName: string,
    packageDir: string,
    headerComment: string
): Promise<void> {
    const generated = new Set<string>();

    while (true) {
        const batch: [string, JSONSchema7][] = [];
        for (const [name, schema] of pendingStandaloneTypes) {
            if (!generated.has(name)) {
                batch.push([name, schema]);
                generated.add(name);
            }
        }
        pendingStandaloneTypes.clear();

        if (batch.length === 0) break;

        for (const [name, schema] of batch) {
            if (schema.type === "string" && schema.enum) {
                await generateStandaloneEnum(name, schema, packageName, packageDir, headerComment);
            } else if (schema.type === "object" && schema.properties) {
                await generateStandaloneRecord(name, schema, packageName, packageDir, headerComment);
            } else if (schema.anyOf && Array.isArray(schema.anyOf)) {
                const variants = resolveAnyOfVariants(schema.anyOf as JSONSchema7[]);
                if (variants.length > 1 && findDiscriminator(variants)) {
                    await generatePolymorphicResultClass(name, schema, packageName, packageDir);
                } else {
                    console.warn(`[codegen] Cannot generate standalone type for ${name}: anyOf without discriminator`);
                }
            } else {
                console.warn(`[codegen] Cannot generate standalone type for ${name}: type=${schema.type}`);
            }
        }
        // Generating records may have discovered more $ref targets — loop again
    }
}

async function generateStandaloneEnum(
    name: string,
    schema: JSONSchema7,
    packageName: string,
    packageDir: string,
    headerComment: string
): Promise<void> {
    const values = schema.enum as string[];
    const lines: string[] = [];
    lines.push(COPYRIGHT);
    lines.push("");
    lines.push(AUTO_GENERATED_HEADER);
    lines.push(headerComment);
    lines.push("");
    lines.push(`package ${packageName};`);
    lines.push("");
    lines.push(`import javax.annotation.processing.Generated;`);
    lines.push("");
    if (schema.description) {
        lines.push(`/**`);
        lines.push(` * ${schema.description}`);
        lines.push(` *`);
        lines.push(` * @since 1.0.0`);
        lines.push(` */`);
    }
    lines.push(GENERATED_ANNOTATION);
    lines.push(`public enum ${name} {`);
    for (let i = 0; i < values.length; i++) {
        const v = values[i];
        const comma = i < values.length - 1 ? "," : ";";
        lines.push(`    /** The {@code ${v}} variant. */`);
        lines.push(`    ${toEnumConstant(v)}("${v}")${comma}`);
    }
    lines.push("");
    lines.push(`    private final String value;`);
    lines.push(`    ${name}(String value) { this.value = value; }`);
    lines.push(`    @com.fasterxml.jackson.annotation.JsonValue`);
    lines.push(`    public String getValue() { return value; }`);
    lines.push(`    @com.fasterxml.jackson.annotation.JsonCreator`);
    lines.push(`    public static ${name} fromValue(String value) {`);
    lines.push(`        for (${name} v : values()) {`);
    lines.push(`            if (v.value.equals(value)) return v;`);
    lines.push(`        }`);
    lines.push(`        throw new IllegalArgumentException("Unknown ${name} value: " + value);`);
    lines.push(`    }`);
    lines.push(`}`);
    lines.push("");

    await writeGeneratedFile(`${packageDir}/${name}.java`, lines.join("\n"));
}

async function generateStandaloneRecord(
    name: string,
    schema: JSONSchema7,
    packageName: string,
    packageDir: string,
    headerComment: string
): Promise<void> {
    const nestedTypes = new Map<string, { code: string }>();
    const { code, imports } = generateRpcClass(name, schema, nestedTypes, packageName);

    const lines: string[] = [];
    lines.push(COPYRIGHT);
    lines.push("");
    lines.push(AUTO_GENERATED_HEADER);
    lines.push(headerComment);
    lines.push("");
    lines.push(`package ${packageName};`);
    lines.push("");

    const allImports = new Set<string>([
        "com.fasterxml.jackson.annotation.JsonIgnoreProperties",
        "com.fasterxml.jackson.annotation.JsonProperty",
        "com.fasterxml.jackson.annotation.JsonInclude",
        "javax.annotation.processing.Generated",
        ...imports,
    ]);
    const sortedImports = [...allImports].sort();
    for (const imp of sortedImports) {
        lines.push(`import ${imp};`);
    }
    lines.push("");

    if (schema.description) {
        lines.push(`/**`);
        lines.push(` * ${schema.description}`);
        lines.push(` *`);
        lines.push(` * @since 1.0.0`);
        lines.push(` */`);
    }
    lines.push(GENERATED_ANNOTATION);
    lines.push(code);
    lines.push("");

    await writeGeneratedFile(`${packageDir}/${name}.java`, lines.join("\n"));
}

// ── RPC types codegen ─────────────────────────────────────────────────────────

interface RpcMethod {
    rpcMethod: string;
    params: JSONSchema7 | null;
    result: JSONSchema7 | null;
    stability?: string;
    deprecated?: boolean;
}

function isRpcMethod(node: unknown): node is RpcMethod {
    return typeof node === "object" && node !== null && "rpcMethod" in node;
}

function collectRpcMethods(node: Record<string, unknown>): [string, RpcMethod][] {
    const results: [string, RpcMethod][] = [];
    for (const [key, value] of Object.entries(node)) {
        if (isRpcMethod(value)) {
            results.push([key, value]);
        } else if (typeof value === "object" && value !== null) {
            results.push(...collectRpcMethods(value as Record<string, unknown>));
        }
    }
    return results;
}

/** Convert an RPC method name to a Java class name prefix (e.g., "models.list" -> "ModelsList") */
function rpcMethodToClassName(rpcMethod: string): string {
    return rpcMethod.split(/[._-]/).map((p) => p.charAt(0).toUpperCase() + p.slice(1)).join("");
}

/** Generate a Java record for a JSON Schema object type. Returns the class content. */
function generateRpcClass(
    className: string,
    schema: JSONSchema7,
    _nestedTypes: Map<string, { code: string }>,
    _packageName: string,
    visibility: "public" | "internal" = "public"
): { code: string; imports: Set<string> } {
    const imports = new Set<string>();
    const localNestedTypes = new Map<string, JavaClassDef>();
    const lines: string[] = [];
    const visModifier = visibility === "public" ? "public " : "";

    const properties = Object.entries(schema.properties || {});
    const fields = properties.flatMap(([propName, propSchema]) => {
        if (typeof propSchema !== "object") return [];
        const prop = propSchema as JSONSchema7;
        // Record components are always boxed (nullable by design).
        const result = schemaTypeToJava(prop, false, className, propName, localNestedTypes);
        for (const imp of result.imports) imports.add(imp);
        return [{ propName, javaName: toCamelCase(propName), javaType: result.javaType, description: prop.description }];
    });

    lines.push(`@JsonInclude(JsonInclude.Include.NON_NULL)`);
    lines.push(`@JsonIgnoreProperties(ignoreUnknown = true)`);
    if (fields.length === 0) {
        lines.push(`${visModifier}record ${className}() {`);
    } else {
        lines.push(`${visModifier}record ${className}(`);
        for (let i = 0; i < fields.length; i++) {
            const f = fields[i];
            const comma = i < fields.length - 1 ? "," : "";
            if (f.description) {
                lines.push(`    /** ${f.description} */`);
            }
            lines.push(`    @JsonProperty("${f.propName}") ${f.javaType} ${f.javaName}${comma}`);
        }
        lines.push(`) {`);
    }

    // Add nested types as nested records/enums inside this record
    for (const [, nested] of localNestedTypes) {
        lines.push(...renderNestedType(nested, 1, new Map(), imports));
    }

    if (localNestedTypes.size > 0 && lines[lines.length - 1] === "") lines.pop();
    lines.push(`}`);

    return { code: lines.join("\n"), imports };
}

async function generateRpcTypes(schemaPath: string): Promise<void> {
    console.log("\n🔌 Generating RPC types...");
    const schemaContent = await fs.readFile(schemaPath, "utf-8");
    const schema = normalizeSchemaBrandCasing(JSON.parse(schemaContent)) as Record<string, unknown> & {
        server?: Record<string, unknown>;
        session?: Record<string, unknown>;
        clientSession?: Record<string, unknown>;
        clientGlobal?: Record<string, unknown>;
        definitions?: Record<string, JSONSchema7>;
    };

    // Set module-level definitions for $ref resolution
    currentDefinitions = (schema.definitions ?? {}) as Record<string, JSONSchema7>;
    pendingStandaloneTypes.clear();
    crossSchemaDefinitions.clear();

    // Load cross-schema definitions (session-events) so that cross-schema $ref values
    // like "session-events.schema.json#/definitions/Foo" can be resolved.
    try {
        const sessionEventsSchemaPath = await getSessionEventsSchemaPath();
        const sessionEventsContent = await fs.readFile(sessionEventsSchemaPath, "utf-8");
        const sessionEventsSchema = normalizeSchemaBrandCasing(JSON.parse(sessionEventsContent) as JSONSchema7);
        crossSchemaDefinitions.set("session-events.schema.json",
            (sessionEventsSchema.definitions ?? {}) as Record<string, JSONSchema7>);
    } catch (e) {
        console.warn(`[codegen] Could not load session-events schema for cross-ref resolution: ${e}`);
    }

    const packageName = "com.github.copilot.generated.rpc";
    const packageDir = `src/generated/java/com/github/copilot/generated/rpc`;

    // Collect all RPC methods from all sections
    const sections: [string, Record<string, unknown>][] = [];
    if (schema.server) sections.push(["server", schema.server]);
    if (schema.session) sections.push(["session", schema.session]);
    if (schema.clientSession) sections.push(["clientSession", schema.clientSession]);
    if (schema.clientGlobal) sections.push(["clientGlobal", schema.clientGlobal]);

    const generatedClasses = new Map<string, boolean>();
    const allFiles: string[] = [];

    for (const [sectionName, sectionNode] of sections) {
        const methods = collectRpcMethods(sectionNode);
        for (const [, method] of methods) {
            const className = rpcMethodToClassName(method.rpcMethod);

            // Generate params class — resolve $ref if params is a reference
            let paramsSchema = method.params as JSONSchema7 | null;
            const paramsRefName = extractRefName(paramsSchema);
            if (paramsRefName && sectionName === "clientGlobal") {
                const resolvedParamsSchema = resolveRef(paramsSchema ?? undefined);
                if (resolvedParamsSchema?.type === "object" && resolvedParamsSchema.properties) {
                    pendingStandaloneTypes.set(paramsRefName, resolvedParamsSchema);
                }
                paramsSchema = null;
            } else if (paramsSchema?.$ref) {
                paramsSchema = resolveRef(paramsSchema) as JSONSchema7;
            }
            if (paramsSchema && typeof paramsSchema === "object" && paramsSchema.properties) {
                const paramsClassName = `${className}Params`;
                if (!generatedClasses.has(paramsClassName)) {
                    generatedClasses.set(paramsClassName, true);
                    allFiles.push(await generateRpcDataClass(paramsClassName, paramsSchema, packageName, packageDir, method.rpcMethod, "params", method.stability, method.deprecated === true));
                }
            }

            // Generate result class — resolve $ref if result is a reference
            let resultSchema = method.result as JSONSchema7 | null;
            const resultRefName = extractRefName(resultSchema);
            if (resultSchema?.$ref) resultSchema = resolveRef(resultSchema) as JSONSchema7;
            if (resultSchema && typeof resultSchema === "object") {
                if (
                    resultSchema.properties &&
                    (Object.keys(resultSchema.properties).length > 0 ||
                        (resultRefName && sectionName === "clientGlobal"))
                ) {
                    // Object with properties → generate a record class
                    const resultClassName = `${className}Result`;
                    if (!generatedClasses.has(resultClassName)) {
                        generatedClasses.set(resultClassName, true);
                        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
                    pendingStandaloneTypes.set(resultRefName, resultSchema);
                } else if (resultRefName && resultSchema.anyOf && Array.isArray(resultSchema.anyOf)) {
                    // anyOf discriminated union → generate polymorphic hierarchy
                    const variants = resolveAnyOfVariants(resultSchema.anyOf as JSONSchema7[]);
                    if (variants.length > 1 && findDiscriminator(variants)) {
                        if (!generatedClasses.has(resultRefName)) {
                            generatedClasses.set(resultRefName, true);
                            await generatePolymorphicResultClass(resultRefName, resultSchema, packageName, packageDir);
                        }
                    }
                } else if (resultRefName && resultSchema.type === "object" && !resultSchema.properties) {
                    // Empty named object → generate empty record
                    if (!generatedClasses.has(resultRefName)) {
                        generatedClasses.set(resultRefName, true);
                        allFiles.push(await generateRpcDataClass(resultRefName, resultSchema, packageName, packageDir, method.rpcMethod, "result"));
                    }
                } else if (resultRefName && resultSchema.type === "array") {
                    // Named array aliases (e.g. AccountGetAllUsersResult) are returned
                    // as List<T> by wrappers, but resolving them here discovers any
                    // referenced item records that need standalone generation.
                    schemaTypeToJava(resultSchema, false, resultRefName, "item", new Map());
                } else if (resultSchema.type === "array") {
                    // Inline arrays also need their referenced item records generated.
                    schemaTypeToJava(resultSchema, false, `${className}Result`, "item", new Map());
                }
            }
        }
    }

    // Generate standalone types discovered via $ref resolution
    await generatePendingStandaloneTypes(packageName, packageDir, GENERATED_FROM_API);

    console.log(`✅ Generated ${allFiles.length} RPC type files`);
}

async function generateRpcDataClass(
    className: string,
    schema: JSONSchema7,
    packageName: string,
    packageDir: string,
    rpcMethod: string,
    kind: "params" | "result",
    stability?: string,
    deprecated?: boolean
): Promise<string> {
    const nestedTypes = new Map<string, { code: string }>();
    const { code, imports } = generateRpcClass(className, schema, nestedTypes, packageName);

    const lines: string[] = [];
    lines.push(COPYRIGHT);
    lines.push("");
    lines.push(AUTO_GENERATED_HEADER);
    lines.push(GENERATED_FROM_API);
    lines.push("");
    lines.push(`package ${packageName};`);
    lines.push("");

    const allImports = new Set<string>([
        "com.fasterxml.jackson.annotation.JsonIgnoreProperties",
        "com.fasterxml.jackson.annotation.JsonProperty",
        "com.fasterxml.jackson.annotation.JsonInclude",
        "javax.annotation.processing.Generated",
        ...imports,
    ]);
    if (stability === "experimental") {
        allImports.add("com.github.copilot.CopilotExperimental");
    }
    const sortedImports = [...allImports].sort();
    for (const imp of sortedImports) {
        lines.push(`import ${imp};`);
    }
    lines.push("");

    if (schema.description) {
        lines.push(`/**`);
        lines.push(` * ${schema.description}`);
    } else {
        lines.push(`/**`);
        lines.push(` * ${kind === "params" ? "Request parameters" : "Result"} for the {@code ${rpcMethod}} RPC method.`);
    }
    if (stability === "experimental") {
        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`);
    }
    if (stability === "experimental") {
        lines.push(`@CopilotExperimental`);
    }
    lines.push(GENERATED_ANNOTATION);
    lines.push(code);
    lines.push("");

    await writeGeneratedFile(`${packageDir}/${className}.java`, lines.join("\n"));
    return className;
}

// ── RPC wrapper generation ───────────────────────────────────────────────────

/** A single RPC method node parsed from the schema */
interface RpcMethodNode {
    rpcMethod: string;
    stability: string;
    deprecated: boolean;
    params: JSONSchema7 | null;
    result: JSONSchema7 | null;
}

/** Namespace tree node: holds direct methods and sub-namespace trees */
interface NamespaceTree {
    methods: Map<string, RpcMethodNode>;   // leaf method name -> info
    subspaces: Map<string, NamespaceTree>; // sub-namespace name -> tree
}

/** Build a namespace tree by recursively walking a schema section object */
function buildNamespaceTree(node: Record<string, unknown>): NamespaceTree {
    const tree: NamespaceTree = { methods: new Map(), subspaces: new Map() };
    for (const [key, value] of Object.entries(node)) {
        if (typeof value !== "object" || value === null) continue;
        const obj = value as Record<string, unknown>;
        if ("rpcMethod" in obj) {
            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,
            });
        } else {
            const child = buildNamespaceTree(obj);
            // Only add non-empty sub-trees
            if (child.methods.size > 0 || child.subspaces.size > 0) {
                tree.subspaces.set(key, child);
            }
        }
    }
    return tree;
}

/**
 * Derive the Java class name for an API namespace class.
 * e.g., prefix="Server", path=["mcp","config"] → "ServerMcpConfigApi"
 */
function apiClassName(prefix: string, path: string[]): string {
    const parts = [prefix, ...path].map((p) => p.charAt(0).toUpperCase() + p.slice(1));
    return parts.join("") + "Api";
}

/**
 * Derive the Java result type for an RPC method.
 * Handles $ref to named definitions (enums, anyOf unions, objects with properties, arrays).
 * Falls back to Void for null results or schemas with no meaningful type.
 */
function wrapperResultClassName(method: RpcMethodNode): string {
    const originalResult = method.result;
    if (!originalResult) return "Void";

    // If result is a $ref, use the definition name directly
    const refName = extractRefName(originalResult);
    if (refName) {
        const resolved = currentDefinitions[refName];
        if (resolved) {
            // String enum → use the definition name
            if (resolved.type === "string" && resolved.enum) {
                return refName;
            }
            // anyOf discriminated union → use the definition name
            if (resolved.anyOf && Array.isArray(resolved.anyOf)) {
                const variants = resolveAnyOfVariants(resolved.anyOf as JSONSchema7[]);
                if (variants.length > 1 && findDiscriminator(variants)) {
                    return refName;
                }
            }
            // Object with properties → use MethodNameResult
            if (resolved.type === "object" && resolved.properties && Object.keys(resolved.properties).length > 0) {
                return rpcMethodToClassName(method.rpcMethod) + "Result";
            }
            // Empty object (no properties) that is a named definition → use definition name
            if (resolved.type === "object" && !resolved.properties) {
                return refName;
            }
            // Named array aliases → use the underlying List<T> Java type.
            if (resolved.type === "array") {
                const result = schemaTypeToJava(resolved, false, refName, "item", new Map());
                return result.javaType;
            }
        }
    }

    // Inline result schema with properties
    let result = originalResult;
    if (result.$ref) result = resolveRef(result) as JSONSchema7;
    if (
        result &&
        typeof result === "object" &&
        result.properties &&
        Object.keys(result.properties).length > 0
    ) {
        return rpcMethodToClassName(method.rpcMethod) + "Result";
    }

    if (result && typeof result === "object" && result.type === "array") {
        const javaResult = schemaTypeToJava(result, false, `${rpcMethodToClassName(method.rpcMethod)}Result`, "item", new Map());
        return javaResult.javaType;
    }

    // Free-form object with additionalProperties (e.g., x-opaque-json) → JsonNode
    if (
        result &&
        typeof result === "object" &&
        result.type === "object" &&
        result.additionalProperties &&
        !result.properties
    ) {
        return "JsonNode";
    }

    return "Void";
}

function wrapperResultTypeExpression(resultType: string): string {
    const listMatch = resultType.match(/^List<([^<>]+)>$/);
    if (listMatch) {
        return `RpcMapper.INSTANCE.getTypeFactory().constructCollectionType(List.class, ${javaClassLiteral(listMatch[1])})`;
    }

    return javaClassLiteral(resultType);
}

function javaClassLiteral(javaType: string): string {
    return javaType === "Void" ? "Void.class" : `${javaType}.class`;
}

function addWrapperResultImports(resultType: string, allImports: Set<string>, packageName: string): void {
    if (resultType === "Void") {
        return;
    }

    if (resultType === "JsonNode") {
        allImports.add("com.fasterxml.jackson.databind.JsonNode");
        return;
    }

    if (resultType.startsWith("List<")) {
        allImports.add("java.util.List");
    }

    const builtInTypes = new Set(["Boolean", "Double", "Long", "List", "Object", "String", "Void"]);
    for (const typeName of resultType.match(/\b[A-Z][A-Za-z0-9_]*\b/g) ?? []) {
        if (!builtInTypes.has(typeName)) {
            allImports.add(`${packageName}.${typeName}`);
        }
    }
}

/**
 * Return the params class name if the method has a params schema with user-supplied properties.
 * Session-scoped wrappers inject sessionId automatically, but server-scoped wrappers must let
 * callers supply it explicitly.
 */
function wrapperParamsClassName(method: RpcMethodNode, isSession: boolean): string | null {
    let params = method.params;
    if (params?.$ref) params = resolveRef(params) as JSONSchema7;
    if (!params || typeof params !== "object") return null;
    const props = params.properties ?? {};
    const userProps = Object.keys(props).filter((k) => !isSession || k !== "sessionId");
    if (userProps.length === 0) return null;
    return rpcMethodToClassName(method.rpcMethod) + "Params";
}

/** True if the method's params schema contains a "sessionId" property */
function methodHasSessionId(method: RpcMethodNode): boolean {
    let params = method.params;
    if (params?.$ref) params = resolveRef(params) as JSONSchema7;
    return !!params?.properties && "sessionId" in params.properties;
}

/**
 * Generate the Java source for a single method in a wrapper API class.
 * Returns the Java source lines and whether an ObjectMapper is required.
 */
function generateApiMethod(
    key: string,
    method: RpcMethodNode,
    isSession: boolean,
    sessionIdExpr: string
): { lines: string[]; needsMapper: boolean; needsExperimentalImport: boolean } {
    const resultClass = wrapperResultClassName(method);
    const paramsClass = wrapperParamsClassName(method, isSession);
    const hasSessionId = methodHasSessionId(method);
    const hasExtraParams = paramsClass !== null;
    let needsMapper = false;

    const lines: string[] = [];

    // Javadoc
    const description = (method.params as JSONSchema7 | null)?.description
        ?? (method.result as JSONSchema7 | null)?.description
        ?? `Invokes {@code ${method.rpcMethod}}.`;
    lines.push(`    /**`);
    lines.push(`     * ${description}`);
    if (isSession && hasExtraParams && hasSessionId) {
        lines.push(`     * <p>`);
        lines.push(`     * Note: the {@code sessionId} field in the params record is overridden`);
        lines.push(`     * by the session-scoped wrapper; any value provided is ignored.`);
    }
    if (method.stability === "experimental") {
        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 (method.deprecated) {
        lines.push(`    @Deprecated`);
    }
    if (method.stability === "experimental") {
        lines.push(`    @CopilotExperimental`);
    }

    // Signature
    if (hasExtraParams) {
        lines.push(`    public CompletableFuture<${resultClass}> ${key}(${paramsClass} params) {`);
    } else {
        lines.push(`    public CompletableFuture<${resultClass}> ${key}() {`);
    }

    // Body
    if (isSession) {
        if (hasExtraParams) {
            // Merge sessionId into the params using Jackson ObjectNode
            needsMapper = true;
            lines.push(`        com.fasterxml.jackson.databind.node.ObjectNode _p = MAPPER.valueToTree(params);`);
            lines.push(`        _p.put("sessionId", ${sessionIdExpr});`);
            lines.push(`        return caller.invoke("${method.rpcMethod}", _p, ${wrapperResultTypeExpression(resultClass)});`);
        } else if (hasSessionId) {
            lines.push(`        return caller.invoke("${method.rpcMethod}", java.util.Map.of("sessionId", ${sessionIdExpr}), ${wrapperResultTypeExpression(resultClass)});`);
        } else {
            lines.push(`        return caller.invoke("${method.rpcMethod}", java.util.Map.of(), ${wrapperResultTypeExpression(resultClass)});`);
        }
    } else {
        // Server-side: pass params directly (or empty map if no params)
        if (hasExtraParams) {
            lines.push(`        return caller.invoke("${method.rpcMethod}", params, ${wrapperResultTypeExpression(resultClass)});`);
        } else {
            lines.push(`        return caller.invoke("${method.rpcMethod}", java.util.Map.of(), ${wrapperResultTypeExpression(resultClass)});`);
        }
    }

    lines.push(`    }`);
    lines.push(``);

    return { lines, needsMapper, needsExperimentalImport: method.stability === "experimental" };
}

/**
 * Generate a Java source file for a single namespace API class.
 * Returns the generated class name and whether a mapper static field is needed.
 */
async function generateNamespaceApiFile(
    prefix: string,
    namespacePath: string[],
    tree: NamespaceTree,
    isSession: boolean,
    packageName: string,
    packageDir: string
): Promise<string> {
    const className = apiClassName(prefix, namespacePath);
    const sessionIdExpr = "this.sessionId";

    const classLines: string[] = [];
    const allImports = new Set<string>([
        "java.util.concurrent.CompletableFuture",
        "javax.annotation.processing.Generated",
    ]);
    let needsMapper = false;

    // Generate sub-namespace fields
    const subFields: string[] = [];
    const subInits: string[] = [];
    for (const [subKey, subTree] of tree.subspaces) {
        const subClass = apiClassName(prefix, [...namespacePath, subKey]);
        subFields.push(`    /** API methods for the {@code ${[...namespacePath, subKey].join(".")}} sub-namespace. */`);
        subFields.push(`    public final ${subClass} ${subKey};`);
        if (isSession) {
            subInits.push(`        this.${subKey} = new ${subClass}(caller, sessionId);`);
        } else {
            subInits.push(`        this.${subKey} = new ${subClass}(caller);`);
        }
        // Recursively generate sub-namespace files
        await generateNamespaceApiFile(prefix, [...namespacePath, subKey], subTree, isSession, packageName, packageDir);
    }

    // Collect result/param imports and generate methods
    const methodLines: string[] = [];
    for (const [key, method] of tree.methods) {
        const resultClass = wrapperResultClassName(method);
        const paramsClass = wrapperParamsClassName(method, isSession);
        addWrapperResultImports(resultClass, allImports, packageName);
        if (paramsClass) allImports.add(`${packageName}.${paramsClass}`);

        const { lines, needsMapper: nm, needsExperimentalImport } = generateApiMethod(key, method, isSession, sessionIdExpr);
        methodLines.push(...lines);
        if (nm) needsMapper = true;
        if (needsExperimentalImport) allImports.add("com.github.copilot.CopilotExperimental");
    }

    // Build class body
    const qualifiedNs = namespacePath.length > 0 ? namespacePath.join(".") : prefix.toLowerCase();
    classLines.push(COPYRIGHT);
    classLines.push(``);
    classLines.push(AUTO_GENERATED_HEADER);
    classLines.push(GENERATED_FROM_API);
    classLines.push(``);
    classLines.push(`package ${packageName};`);
    classLines.push(``);

    // Add imports (skip same-package imports)
    const sortedImports = [...allImports].filter(imp => !imp.startsWith(packageName + ".")).sort();
    for (const imp of sortedImports) {
        classLines.push(`import ${imp};`);
    }
    classLines.push(``);

    // Javadoc for class
    classLines.push(`/**`);
    classLines.push(` * API methods for the {@code ${qualifiedNs}} namespace.`);
    classLines.push(` *`);
    classLines.push(` * @since 1.0.0`);
    classLines.push(` */`);
    classLines.push(GENERATED_ANNOTATION);
    classLines.push(`public final class ${className} {`);
    classLines.push(``);
    if (needsMapper) {
        classLines.push(`    private static final com.fasterxml.jackson.databind.ObjectMapper MAPPER = RpcMapper.INSTANCE;`);
        classLines.push(``);
    }
    classLines.push(`    private final RpcCaller caller;`);
    if (isSession) {
        classLines.push(`    private final String sessionId;`);
    }

    // Sub-namespace fields
    if (subFields.length > 0) {
        classLines.push(``);
        classLines.push(...subFields);
    }

    // Constructor
    classLines.push(``);
    if (isSession) {
        classLines.push(`    /** @param caller the RPC transport function */`);
        classLines.push(`    ${className}(RpcCaller caller, String sessionId) {`);
        classLines.push(`        this.caller = caller;`);
        classLines.push(`        this.sessionId = sessionId;`);
    } else {
        classLines.push(`    /** @param caller the RPC transport function */`);
        classLines.push(`    ${className}(RpcCaller caller) {`);
        classLines.push(`        this.caller = caller;`);
    }
    for (const init of subInits) {
        classLines.push(init);
    }
    classLines.push(`    }`);
    classLines.push(``);

    // Methods
    classLines.push(...methodLines);

    classLines.push(`}`);
    classLines.push(``);

    await writeGeneratedFile(`${packageDir}/${className}.java`, classLines.join("\n"));
    return className;
}

/**
 * Generate ServerRpc.java or SessionRpc.java — the top-level wrapper class.
 */
async function generateRpcRootFile(
    sectionName: string, // "server" | "session"
    tree: NamespaceTree,
    isSession: boolean,
    packageName: string,
    packageDir: string
): Promise<void> {
    const prefix = sectionName === "server" ? "Server" : "Session";
    const rootClassName = prefix + "Rpc";
    const sessionIdExpr = "this.sessionId";

    const classLines: string[] = [];
    const allImports = new Set<string>([
        "java.util.concurrent.CompletableFuture",
        "javax.annotation.processing.Generated",
    ]);
    let needsMapper = false;

    // Sub-namespace fields and init lines
    const subFields: string[] = [];
    const subInits: string[] = [];
    for (const [nsKey, nsTree] of tree.subspaces) {
        const nsClass = apiClassName(prefix, [nsKey]);
        subFields.push(`    /** API methods for the {@code ${nsKey}} namespace. */`);
        subFields.push(`    public final ${nsClass} ${nsKey};`);
        if (isSession) {
            subInits.push(`        this.${nsKey} = new ${nsClass}(caller, sessionId);`);
        } else {
            subInits.push(`        this.${nsKey} = new ${nsClass}(caller);`);
        }
        // Generate the namespace API class file (recursively)
        await generateNamespaceApiFile(prefix, [nsKey], nsTree, isSession, packageName, packageDir);
    }

    // Collect result/param imports and generate top-level method bodies
    const methodLines: string[] = [];
    for (const [key, method] of tree.methods) {
        const resultClass = wrapperResultClassName(method);
        const paramsClass = wrapperParamsClassName(method, isSession);
        addWrapperResultImports(resultClass, allImports, packageName);
        if (paramsClass) allImports.add(`${packageName}.${paramsClass}`);

        const { lines, needsMapper: nm, needsExperimentalImport } = generateApiMethod(key, method, isSession, sessionIdExpr);
        methodLines.push(...lines);
        if (nm) needsMapper = true;
        if (needsExperimentalImport) allImports.add("com.github.copilot.CopilotExperimental");
    }

    // Build file content
    classLines.push(COPYRIGHT);
    classLines.push(``);
    classLines.push(AUTO_GENERATED_HEADER);
    classLines.push(GENERATED_FROM_API);
    classLines.push(``);
    classLines.push(`package ${packageName};`);
    classLines.push(``);

    const sortedImports = [...allImports].filter(imp => !imp.startsWith(packageName + ".")).sort();
    for (const imp of sortedImports) {
        classLines.push(`import ${imp};`);
    }
    classLines.push(``);

    classLines.push(`/**`);
    if (isSession) {
        classLines.push(` * Typed client for session-scoped RPC methods.`);
        classLines.push(` * <p>`);
        classLines.push(` * Provides strongly-typed access to all session-level API namespaces.`);
        classLines.push(` * The {@code sessionId} is injected automatically into every call.`);
        classLines.push(` * <p>`);
        classLines.push(` * Obtain an instance by calling {@code new SessionRpc(caller, sessionId)}.`);
    } else {
        classLines.push(` * Typed client for server-level RPC methods.`);
        classLines.push(` * <p>`);
        classLines.push(` * Provides strongly-typed access to all server-level API namespaces.`);
        classLines.push(` * <p>`);
        classLines.push(` * Obtain an instance by calling {@code new ServerRpc(caller)}.`);
    }
    classLines.push(` *`);
    classLines.push(` * @since 1.0.0`);
    classLines.push(` */`);
    classLines.push(GENERATED_ANNOTATION);
    classLines.push(`public final class ${rootClassName} {`);
    classLines.push(``);
    if (needsMapper) {
        classLines.push(`    private static final com.fasterxml.jackson.databind.ObjectMapper MAPPER = RpcMapper.INSTANCE;`);
        classLines.push(``);
    }
    classLines.push(`    private final RpcCaller caller;`);
    if (isSession) {
        classLines.push(`    private final String sessionId;`);
    }
    if (subFields.length > 0) {
        classLines.push(``);
        classLines.push(...subFields);
    }
    classLines.push(``);

    // Constructor
    if (isSession) {
        classLines.push(`    /**`);
        classLines.push(`     * Creates a new session RPC client.`);
        classLines.push(`     *`);
        classLines.push(`     * @param caller    the RPC transport function (e.g., {@code jsonRpcClient::invoke})`);
        classLines.push(`     * @param sessionId the session ID to inject into every request`);
        classLines.push(`     */`);
        classLines.push(`    public ${rootClassName}(RpcCaller caller, String sessionId) {`);
        classLines.push(`        this.caller = caller;`);
        classLines.push(`        this.sessionId = sessionId;`);
    } else {
        classLines.push(`    /**`);
        classLines.push(`     * Creates a new server RPC client.`);
        classLines.push(`     *`);
        classLines.push(`     * @param caller the RPC transport function (e.g., {@code jsonRpcClient::invoke})`);
        classLines.push(`     */`);
        classLines.push(`    public ${rootClassName}(RpcCaller caller) {`);
        classLines.push(`        this.caller = caller;`);
    }
    for (const init of subInits) {
        classLines.push(init);
    }
    classLines.push(`    }`);
    classLines.push(``);

    // Top-level methods
    classLines.push(...methodLines);

    classLines.push(`}`);
    classLines.push(``);

    await writeGeneratedFile(`${packageDir}/${rootClassName}.java`, classLines.join("\n"));
}

/** Generate the RpcCaller functional interface */
async function generateRpcCallerInterface(packageName: string, packageDir: string): Promise<void> {
    const lines: string[] = [];
    lines.push(COPYRIGHT);
    lines.push(``);
    lines.push(AUTO_GENERATED_HEADER);
    lines.push(GENERATED_FROM_API);
    lines.push(``);
    lines.push(`package ${packageName};`);
    lines.push(``);
    lines.push(`import com.fasterxml.jackson.databind.JavaType;`);
    lines.push(`import com.fasterxml.jackson.databind.JsonNode;`);
    lines.push(`import java.util.concurrent.CompletableFuture;`);
    lines.push(`import java.util.concurrent.CompletionException;`);
    lines.push(`import javax.annotation.processing.Generated;`);
    lines.push(``);
    lines.push(`/**`);
    lines.push(` * Interface for invoking JSON-RPC methods with typed responses.`);
    lines.push(` * <p>`);
    lines.push(` * Implementations delegate to the underlying transport layer`);
    lines.push(` * (e.g., a {@code JsonRpcClient} instance). A method reference is typically the clearest`);
    lines.push(` * way to adapt a generic {@code invoke} method to this interface:`);
    lines.push(` * <pre>{@code`);
    lines.push(` * RpcCaller caller = jsonRpcClient::invoke;`);
    lines.push(` * }</pre>`);
    lines.push(` *`);
    lines.push(` * @since 1.0.0`);
    lines.push(` */`);
    lines.push(GENERATED_ANNOTATION);
    lines.push(`public interface RpcCaller {`);
    lines.push(``);
    lines.push(`    /**`);
    lines.push(`     * Invokes a JSON-RPC method and returns a future for the typed response.`);
    lines.push(`     *`);
    lines.push(`     * @param <T>        the expected response type`);
    lines.push(`     * @param method     the JSON-RPC method name`);
    lines.push(`     * @param params     the request parameters (may be a {@code Map}, DTO record, or {@code JsonNode})`);
    lines.push(`     * @param resultType the {@link Class} of the expected response type`);
    lines.push(`     * @return a {@link CompletableFuture} that completes with the deserialized result`);
    lines.push(`     */`);
    lines.push(`    <T> CompletableFuture<T> invoke(String method, Object params, Class<T> resultType);`);
    lines.push(``);
    lines.push(`    /**`);
    lines.push(`     * Invokes a JSON-RPC method and returns a future for the typed response.`);
    lines.push(`     *`);
    lines.push(`     * @param <T>        the expected response type`);
    lines.push(`     * @param method     the JSON-RPC method name`);
    lines.push(`     * @param params     the request parameters (may be a {@code Map}, DTO record, or {@code JsonNode})`);
    lines.push(`     * @param resultType the Jackson {@link JavaType} of the expected response type`);
    lines.push(`     * @return a {@link CompletableFuture} that completes with the deserialized result`);
    lines.push(`     */`);
    lines.push(`    default <T> CompletableFuture<T> invoke(String method, Object params, JavaType resultType) {`);
    lines.push(`        if (resultType.hasRawClass(Void.class) || resultType.hasRawClass(Void.TYPE)) {`);
    lines.push(`            return invoke(method, params, Void.class).thenApply(ignored -> null);`);
    lines.push(`        }`);
    lines.push(`        return invoke(method, params, JsonNode.class).thenApply(result -> {`);
    lines.push(`            try {`);
    lines.push(`                return RpcMapper.INSTANCE.readerFor(resultType).readValue(result);`);
    lines.push(`            } catch (java.io.IOException e) {`);
    lines.push(`                throw new CompletionException(e);`);
    lines.push(`            }`);
    lines.push(`        });`);
    lines.push(`    }`);
    lines.push(`}`);
    lines.push(``);

    await writeGeneratedFile(`${packageDir}/RpcCaller.java`, lines.join("\n"));
}

/**
 * Generate RpcMapper.java — a package-private holder for the shared ObjectMapper used
 * when merging sessionId into session API call params.  All session API classes that
 * need an ObjectMapper reference this single instance instead of instantiating their own.
 */
async function generateRpcMapperClass(packageName: string, packageDir: string): Promise<void> {
    const lines: string[] = [];
    lines.push(COPYRIGHT);
    lines.push(``);
    lines.push(AUTO_GENERATED_HEADER);
    lines.push(GENERATED_FROM_API);
    lines.push(``);
    lines.push(`package ${packageName};`);
    lines.push(``);
    lines.push(`import javax.annotation.processing.Generated;`);
    lines.push(``);
    lines.push(`/**`);
    lines.push(` * Package-private holder for the shared {@link com.fasterxml.jackson.databind.ObjectMapper}`);
    lines.push(` * used by session API classes when merging {@code sessionId} into call parameters.`);
    lines.push(` * <p>`);
    lines.push(` * {@link com.fasterxml.jackson.databind.ObjectMapper} is thread-safe and expensive to`);
    lines.push(` * instantiate, so a single shared instance is used across all generated API classes.`);
    lines.push(` * The configuration mirrors {@code JsonRpcClient}'s mapper (JavaTimeModule, lenient`);
    lines.push(` * unknown-property handling, ISO date format, NON_NULL inclusion).`);
    lines.push(` *`);
    lines.push(` * @since 1.0.0`);
    lines.push(` */`);
    lines.push(GENERATED_ANNOTATION);
    lines.push(`final class RpcMapper {`);
    lines.push(``);
    lines.push(`    static final com.fasterxml.jackson.databind.ObjectMapper INSTANCE = createMapper();`);
    lines.push(``);
    lines.push(`    private static com.fasterxml.jackson.databind.ObjectMapper createMapper() {`);
    lines.push(`        com.fasterxml.jackson.databind.ObjectMapper mapper = new com.fasterxml.jackson.databind.ObjectMapper();`);
    lines.push(`        mapper.registerModule(new com.fasterxml.jackson.datatype.jsr310.JavaTimeModule());`);
    lines.push(`        mapper.configure(com.fasterxml.jackson.databind.DeserializationFeature.FAIL_ON_UNKNOWN_PROPERTIES, false);`);
    lines.push(`        mapper.configure(com.fasterxml.jackson.databind.SerializationFeature.WRITE_DATES_AS_TIMESTAMPS, false);`);
    lines.push(`        mapper.setDefaultPropertyInclusion(com.fasterxml.jackson.annotation.JsonInclude.Include.NON_NULL);`);
    lines.push(`        return mapper;`);
    lines.push(`    }`);
    lines.push(``);
    lines.push(`    private RpcMapper() {}`);
    lines.push(`}`);
    lines.push(``);

    await writeGeneratedFile(`${packageDir}/RpcMapper.java`, lines.join("\n"));
}

/** Main entry point for RPC wrapper generation */
async function generateRpcWrappers(schemaPath: string): Promise<void> {
    console.log("\n🔧 Generating RPC wrapper classes...");

    const schemaContent = await fs.readFile(schemaPath, "utf-8");
    const schema = normalizeSchemaBrandCasing(JSON.parse(schemaContent)) as {
        server?: Record<string, unknown>;
        session?: Record<string, unknown>;
        clientSession?: Record<string, unknown>;
        definitions?: Record<string, JSONSchema7>;
    };

    // Set module-level definitions for $ref resolution in wrapper helpers
    currentDefinitions = (schema.definitions ?? {}) as Record<string, JSONSchema7>;

    const packageName = "com.github.copilot.generated.rpc";
    const packageDir = `src/generated/java/com/github/copilot/generated/rpc`;

    // RpcCaller interface and shared ObjectMapper holder
    await generateRpcCallerInterface(packageName, packageDir);
    await generateRpcMapperClass(packageName, packageDir);

    // Server-side wrappers
    if (schema.server) {
        const serverTree = buildNamespaceTree(schema.server);
        await generateRpcRootFile("server", serverTree, false, packageName, packageDir);
    }

    // Session-side wrappers
    if (schema.session) {
        const sessionTree = buildNamespaceTree(schema.session);
        await generateRpcRootFile("session", sessionTree, true, packageName, packageDir);
    }

    console.log(`✅ RPC wrapper classes generated`);
}

// ── Package-info generation ──────────────────────────────────────────────────

async function generateGeneratedPackageInfo(packageDir: string): Promise<void> {
    const lines: string[] = [];
    lines.push(COPYRIGHT);
    lines.push("");
    lines.push(AUTO_GENERATED_HEADER);
    lines.push(GENERATED_FROM_SESSION_EVENTS);
    lines.push("");
    lines.push(`/**`);
    lines.push(` * Auto-generated session event types for the GitHub Copilot SDK.`);
    lines.push(` *`);
    lines.push(` * <p>`);
    lines.push(` * This package contains Java classes generated from the Copilot CLI's`);
    lines.push(` * {@code session-events.schema.json}. Each event type corresponds to a`);
    lines.push(` * notification emitted during a {@link com.github.copilot.CopilotSession}`);
    lines.push(` * interaction.`);
    lines.push(` *`);
    lines.push(` * <h2>Key Classes</h2>`);
    lines.push(` * <ul>`);
    lines.push(` * <li>{@link com.github.copilot.generated.SessionEvent} - Abstract sealed base`);
    lines.push(` * class for all session events. Deserialized polymorphically via the`);
    lines.push(` * {@code type} discriminator.</li>`);
    lines.push(` * <li>{@link com.github.copilot.generated.UnknownSessionEvent} - Fallback for`);
    lines.push(` * event types not yet known to this SDK version, preserving forward`);
    lines.push(` * compatibility.</li>`);
    lines.push(` * </ul>`);
    lines.push(` *`);
    lines.push(` * <h2>Example Usage</h2>`);
    lines.push(` *`);
    lines.push(` * <pre>{@code`);
    lines.push(` * session.on(AssistantMessageEvent.class, msg -> {`);
    lines.push(` *     System.out.println(msg.getData().content());`);
    lines.push(` * });`);
    lines.push(` * }</pre>`);
    lines.push(` *`);
    lines.push(` * <h2>Related Packages</h2>`);
    lines.push(` * <ul>`);
    lines.push(` * <li>{@link com.github.copilot} - Core SDK classes</li>`);
    lines.push(` * <li>{@link com.github.copilot.generated.rpc} - Auto-generated RPC`);
    lines.push(` * parameter and result types</li>`);
    lines.push(` * </ul>`);
    lines.push(` *`);
    lines.push(` * @see com.github.copilot.CopilotSession`);
    lines.push(` * @see com.github.copilot.generated.SessionEvent`);
    lines.push(` */`);
    lines.push(`package com.github.copilot.generated;`);
    lines.push("");

    await writeGeneratedFile(`${packageDir}/package-info.java`, lines.join("\n"));
}

async function generateRpcPackageInfo(packageDir: string): Promise<void> {
    const lines: string[] = [];
    lines.push(COPYRIGHT);
    lines.push("");
    lines.push(AUTO_GENERATED_HEADER);
    lines.push(GENERATED_FROM_API);
    lines.push("");
    lines.push(`/**`);
    lines.push(` * Auto-generated RPC parameter and result types for the GitHub Copilot SDK.`);
    lines.push(` *`);
    lines.push(` * <p>`);
    lines.push(` * This package contains Java records and classes generated from the Copilot`);
    lines.push(` * CLI's {@code api.schema.json}. These types represent the request parameters`);
    lines.push(` * and response payloads for all JSON-RPC methods exposed by the CLI.`);
    lines.push(` *`);
    lines.push(` * <h2>Key Classes</h2>`);
    lines.push(` * <ul>`);
    lines.push(` * <li>{@link com.github.copilot.generated.rpc.RpcCaller} - Functional interface`);
    lines.push(` * for invoking JSON-RPC methods with typed responses.</li>`);
    lines.push(` * <li>{@link com.github.copilot.generated.rpc.ServerRpc} - Typed client for`);
    lines.push(` * server-level RPC methods (session management, model listing, etc.).</li>`);
    lines.push(` * <li>{@link com.github.copilot.generated.rpc.SessionRpc} - Typed client for`);
    lines.push(` * session-scoped RPC methods (send messages, manage tools, etc.). Automatically`);
    lines.push(` * injects the {@code sessionId} into every call.</li>`);
    lines.push(` * </ul>`);
    lines.push(` *`);
    lines.push(` * <h2>Related Packages</h2>`);
    lines.push(` * <ul>`);
    lines.push(` * <li>{@link com.github.copilot} - Core SDK classes</li>`);
    lines.push(` * <li>{@link com.github.copilot.generated} - Auto-generated session event`);
    lines.push(` * types</li>`);
    lines.push(` * </ul>`);
    lines.push(` *`);
    lines.push(` * @see com.github.copilot.CopilotClient`);
    lines.push(` * @see com.github.copilot.generated.rpc.ServerRpc`);
    lines.push(` * @see com.github.copilot.generated.rpc.SessionRpc`);
    lines.push(` */`);
    lines.push(`package com.github.copilot.generated.rpc;`);
    lines.push("");

    await writeGeneratedFile(`${packageDir}/package-info.java`, lines.join("\n"));
}

// ── Main entry point ──────────────────────────────────────────────────────────

async function main(): Promise<void> {
    console.log("🚀 Java SDK code generator");
    console.log("============================");

    // Clean the generated output directory to remove orphaned files from previous runs
    const generatedOutputDir = path.join(REPO_ROOT, "src/generated/java/com/github/copilot/generated");
    console.log(`🧹 Cleaning output directory: ${generatedOutputDir}`);
    await fs.rm(generatedOutputDir, { recursive: true, force: true });
    await fs.mkdir(generatedOutputDir, { recursive: true });

    const sessionEventsSchemaPath = await getSessionEventsSchemaPath();
    console.log(`📄 Session events schema: ${sessionEventsSchemaPath}`);
    const apiSchemaPath = await getApiSchemaPath();
    console.log(`📄 API schema: ${apiSchemaPath}`);

    await generateSessionEvents(sessionEventsSchemaPath);
    await generateRpcTypes(apiSchemaPath);
    await generateRpcWrappers(apiSchemaPath);

    // Generate package-info.java for each generated package
    const generatedPkgDir = `src/generated/java/com/github/copilot/generated`;
    const rpcPkgDir = `src/generated/java/com/github/copilot/generated/rpc`;
    await generateGeneratedPackageInfo(generatedPkgDir);
    await generateRpcPackageInfo(rpcPkgDir);

    console.log("\n✅ Java code generation complete!");
}

main().catch((err) => {
    console.error("❌ Code generation failed:", err);
    process.exit(1);
});