scythe-codegen 0.19.0

use std::collections::HashMap;
use std::fmt::Write;

use scythe_backend::manifest::BackendManifest;
use scythe_backend::naming::{
    composite_type_name, enum_type_name, enum_variant_name, fn_name, to_camel_case, to_pascal_case,
};
use scythe_backend::types::resolve_type;

use scythe_core::SqlDialect;
use scythe_core::analyzer::{AnalyzedQuery, CompositeInfo, EnumInfo};
use scythe_core::errors::{ErrorCode, ScytheError};
use scythe_core::parser::QueryCommand;

use crate::backend_options::reject_unknown_options;
use crate::backend_trait::{CodegenBackend, GroupedQueryFn, ResolvedColumn, ResolvedParam};
use crate::backends::jvm_common;

const DEFAULT_MANIFEST_PG: &str = include_str!("../../manifests/kotlin-exposed.toml");

pub struct KotlinExposedBackend {
    manifest: BackendManifest,
}

impl KotlinExposedBackend {
    pub fn new(engine: &str) -> Result<Self, ScytheError> {
        let default_toml = match engine {
            "postgresql" | "postgres" | "pg" => DEFAULT_MANIFEST_PG,
            _ => {
                return Err(ScytheError::new(
                    ErrorCode::InvalidConfig,
                    format!("unsupported engine '{}' for kotlin-exposed backend", engine),
                ));
            }
        };
        let manifest = super::parse_manifest(default_toml)?;
        Ok(Self { manifest })
    }
}

/// Get the Exposed column type function for a given Kotlin type.
fn exposed_column_fn(kotlin_type: &str) -> &str {
    match kotlin_type {
        "Boolean" => "bool",
        "Byte" => "byte",
        "Short" => "short",
        "Int" => "integer",
        "Long" => "long",
        "Float" => "float",
        "Double" => "double",
        "String" => "text",
        "ByteArray" => "binary",
        _ if kotlin_type.contains("BigDecimal") => "decimal",
        _ if kotlin_type.contains("LocalDate") => "date",
        _ if kotlin_type.contains("LocalTime") => "time",
        _ if kotlin_type.contains("OffsetTime") => "time",
        _ if kotlin_type.contains("LocalDateTime") => "datetime",
        _ if kotlin_type.contains("OffsetDateTime") => "timestampWithTimeZone",
        _ if kotlin_type.contains("UUID") => "uuid",
        _ => "text",
    }
}

/// The Kotlin element type an array column's `List<{T}>` reader casts each
/// element to. See `kotlin_jdbc.rs`'s `element_kotlin_type` -- identical
/// reasoning, duplicated rather than shared because it is a five-line wrapper
/// and the two backends have no other coupling.
fn element_kotlin_type(element_neutral: &str, manifest: &BackendManifest) -> String {
    resolve_type(element_neutral, manifest, false)
        .map(|t| t.into_owned())
        .unwrap_or_else(|_| "Any".to_string())
}

/// The Kotlin `List<T>` expression that turns a `java.sql.Array` (already
/// known non-null) into the declared element type. See `kotlin_jdbc.rs`'s
/// `array_list_expr` for the full reasoning.
fn array_list_expr(sql_array_expr: &str, element_type: &str) -> String {
    format!("({sql_array_expr}.array as Array<*>).map {{ it as {element_type} }}")
}

/// Splits a PostgreSQL composite's text form (`"(a,b,c)"`) into its raw field tokens. See
/// `java_jdbc.rs`'s twin constant for the full reasoning -- duplicated rather than shared
/// because the two backends have no other coupling.
const KT_PARSE_COMPOSITE_FIELDS_METHOD: &str = r#"        /**
         * ~keep Splits a PostgreSQL composite's text form ("(a,b,c)") into its raw field tokens,
         * honoring its escaping rules: an empty unquoted field is SQL NULL (returned as `null`);
         * a field needing quoting (containing a comma, paren, quote, backslash, or
         * leading/trailing space, or the empty string) is wrapped in double quotes with `"` and
         * `\` backslash-escaped inside; every other field is unquoted and taken literally. A
         * nested composite's own "(x,y)" text form always contains parens, so it always comes
         * back quoted here, ready for that type's own `fromText` to parse recursively.
         */
        private fun parseCompositeFields(text: String): List<String?> {
            val fields = mutableListOf<String?>()
            val inner = text.substring(1, text.length - 1)
            var i = 0
            val n = inner.length
            while (true) {
                val field = StringBuilder()
                var isNull = false
                if (i < n && inner[i] == '"') {
                    i++
                    while (i < n) {
                        val c = inner[i]
                        if (c == '\\' && i + 1 < n) {
                            field.append(inner[i + 1])
                            i += 2
                        } else if (c == '"' && i + 1 < n && inner[i + 1] == '"') {
                            field.append('"')
                            i += 2
                        } else if (c == '"') {
                            i++
                            break
                        } else {
                            field.append(c)
                            i++
                        }
                    }
                } else {
                    val start = i
                    while (i < n && inner[i] != ',') {
                        i++
                    }
                    field.append(inner, start, i)
                    isNull = field.isEmpty()
                }
                fields.add(if (isNull) null else field.toString())
                if (i < n && inner[i] == ',') {
                    i++
                    continue
                }
                break
            }
            return fields
        }
"#;

/// PostgreSQL's default `bytea` text output is hex (`"\x48656c6c6f"`); decode the digits after
/// the `\x` prefix back into bytes. Emitted only when a composite has a `bytes` field.
const KT_PARSE_COMPOSITE_BYTES_METHOD: &str = r#"        /**
         * ~keep PostgreSQL's default `bytea` text output is hex: "\x48656c6c6f". Decode the hex
         * digits after the "\x" prefix back into bytes.
         */
        private fun parseCompositeBytes(hex: String): ByteArray {
            val digits = hex.substring(2)
            val result = ByteArray(digits.length / 2)
            for (i in result.indices) {
                result[i] = digits.substring(i * 2, i * 2 + 2).toInt(16).toByte()
            }
            return result
        }
"#;

/// PostgreSQL's default `timestamptz` text output uses a space instead of `T` and omits the
/// offset's minutes when they are zero; normalize both before handing the text to `java.time`.
/// Emitted only when a composite has a `datetime_tz` field.
const KT_PARSE_COMPOSITE_OFFSET_DATETIME_METHOD: &str = r#"        /**
         * ~keep PostgreSQL's default `timestamptz` text output uses a space instead of `T`
         * ("2024-01-15 10:30:00+00") and omits the offset's minutes when they are zero ("+00"
         * rather than "+00:00"). Normalize both before parsing.
         */
        private fun parseCompositeOffsetDateTime(raw: String): java.time.OffsetDateTime {
            var s = raw.replace(' ', 'T')
            val sign = s[s.length - 3]
            if (sign == '+' || sign == '-') {
                s += ":00"
            }
            return java.time.OffsetDateTime.parse(s)
        }
"#;

/// PostgreSQL's default `timetz` text output omits the offset's minutes when they are zero;
/// `OffsetTime.parse` rejects that. Emitted only when a composite has a `time_tz` field.
const KT_PARSE_COMPOSITE_OFFSET_TIME_METHOD: &str = r#"        /**
         * ~keep PostgreSQL's default `timetz` text output omits the offset's minutes when they
         * are zero ("13:22:43-05" rather than "13:22:43-05:00"), which `OffsetTime.parse` rejects.
         */
        private fun parseCompositeOffsetTime(raw: String): java.time.OffsetTime {
            var s = raw
            val sign = s[s.length - 3]
            if (sign == '+' || sign == '-') {
                s += ":00"
            }
            return java.time.OffsetTime.parse(s)
        }
"#;

fn composite_needs_bytes_helper(composite: &CompositeInfo) -> bool {
    composite.fields.iter().any(|f| f.neutral_type == "bytes")
}

fn composite_needs_offset_datetime_helper(composite: &CompositeInfo) -> bool {
    composite.fields.iter().any(|f| f.neutral_type == "datetime_tz")
}

fn composite_needs_offset_time_helper(composite: &CompositeInfo) -> bool {
    composite.fields.iter().any(|f| f.neutral_type == "time_tz")
}

/// ~keep Convert one non-null composite field token into its non-null Kotlin type. Nullable
/// fields wrap this expression in `?.let` at the call site so SQL NULL remains Kotlin null.
fn composite_field_from_text_kotlin(
    neutral_type: &str,
    field_type: &str,
    raw: &str,
    manifest: &BackendManifest,
) -> String {
    if let Some(sql_name) = neutral_type.strip_prefix("composite::") {
        return format!(
            "{}.fromText({})!!",
            composite_type_name(sql_name, &manifest.naming),
            raw
        );
    }
    if neutral_type.starts_with("enum::") {
        return format!("{}.fromValue({})", field_type, raw);
    }
    match neutral_type {
        "bool" => format!("{} == \"t\"", raw),
        "int16" => format!("{}.toShort()", raw),
        "int32" => format!("{}.toInt()", raw),
        "int64" => format!("{}.toLong()", raw),
        "float32" => format!("{}.toFloat()", raw),
        "float64" => format!("{}.toDouble()", raw),
        "decimal" => format!("java.math.BigDecimal({})", raw),
        "uuid" => format!("java.util.UUID.fromString({})", raw),
        "date" => format!("java.time.LocalDate.parse({})", raw),
        "time" => format!("java.time.LocalTime.parse({})", raw),
        "datetime" => format!("java.time.LocalDateTime.parse({}.replace(' ', 'T'))", raw),
        "datetime_tz" => format!("parseCompositeOffsetDateTime({})", raw),
        "time_tz" => format!("parseCompositeOffsetTime({})", raw),
        "bytes" => format!("parseCompositeBytes({})", raw),
        // ~keep String-like fields need no conversion. Unsupported composite field kinds retain
        // the existing raw-token fallback.
        _ => raw.to_string(),
    }
}

/// The inline read expression for a kotlin-exposed column.
///
/// Exposed's `exec(sql) { rs -> ... }` block hands out a plain
/// `java.sql.ResultSet`, so this is the same problem `kotlin-jdbc` has and the
/// same answer: a named getter where JDBC has one, `rs.getObject(col,
/// T::class.java)` where it does not, and never the untyped
/// `rs.getObject(col)` whose `Any!` result is assignable to nothing.
///
/// Nullable columns return the preamble local written by
/// [`write_exposed_nullable_preamble`] instead of an inline read. This backend
/// had no preamble at all: a nullable `Int?` column was read with
/// `rs.getInt(col)`, which JDBC specifies to return `0` — not null — for SQL
/// NULL, so every NULL in a nullable numeric or boolean column silently became
/// `0`/`false` in the row object.
///
/// board #196: a composite column is checked before the blanket `col.nullable` preamble
/// dispatch -- pgjdbc registers no type map for a user-defined composite, so
/// `rs.getObject(col, T::class.java)` throws `PSQLException: conversion to class T ... not
/// supported` at runtime. `T.fromText` (emitted by `generate_composite_def`) parses the
/// driver's text form instead and is already null-safe, so composite needs no preamble local
/// (see the matching skip in `write_exposed_nullable_preamble`).
fn exposed_rs_expr(col: &ResolvedColumn, manifest: &BackendManifest) -> String {
    if col.neutral_type.starts_with("composite::") {
        // ~keep `fromText` returns `T?` so a NULL column stays expressible; a NOT NULL column's
        // field is declared `T` and needs the unwrap or Kotlin rejects the argument. Same fix as
        // `kotlin_jdbc::kt_rs_expr`; Java has no compile-time nullability and so needs nothing.
        let unwrap = if col.nullable { "" } else { "!!" };
        return format!("{}.fromText(rs.getString(\"{}\")){}", col.lang_type, col.name, unwrap);
    }
    if col.nullable {
        return col.field_name.clone();
    }
    if let Some(element) = jvm_common::array_element_neutral_type(&col.neutral_type) {
        let element_type = element_kotlin_type(element, manifest);
        return array_list_expr(&format!("rs.getArray(\"{}\")", col.name), &element_type);
    }
    if jvm_common::is_enum_column(&col.neutral_type) {
        return format!("{}.fromValue(rs.getString(\"{}\"))", col.lang_type, col.name);
    }
    jvm_common::kotlin_jdbc_read_call(&col.name, &col.lang_type)
}

/// Emit the nullable-column preamble locals a following row construction reads
/// through [`exposed_rs_expr`].
fn write_exposed_nullable_preamble(
    out: &mut String,
    cols: &[ResolvedColumn],
    indent: &str,
    manifest: &BackendManifest,
) {
    for col in cols {
        if !col.nullable {
            continue;
        }
        // ~keep board #196: `exposed_rs_expr` returns the composite's `fromText` call inline
        // for every composite column, nullable or not (see its own comment) -- so no preamble
        // local is ever read for one, and emitting `rs.getObject(col, T::class.java)` here
        // would both be dead code and reintroduce the type-map-less accessor this fix removes.
        if col.neutral_type.starts_with("composite::") {
            continue;
        }
        if let Some(element) = jvm_common::array_element_neutral_type(&col.neutral_type) {
            // ~keep A nullable array column's `rs.getArray(col)` returns
            // `null` for SQL NULL; calling `.array` on that null throws
            // `NullPointerException`, so the guard is on the `java.sql.Array`
            // local, before the element conversion runs.
            let element_type = element_kotlin_type(element, manifest);
            let _ = writeln!(
                out,
                "{}val {}SqlArray = rs.getArray(\"{}\")",
                indent, col.field_name, col.name
            );
            let list_expr = array_list_expr(&format!("{}SqlArray", col.field_name), &element_type);
            let _ = writeln!(
                out,
                "{}val {} = if ({}SqlArray == null) null else {}",
                indent, col.field_name, col.field_name, list_expr
            );
            continue;
        }
        if jvm_common::is_enum_column(&col.neutral_type) {
            // ~keep `getString` returns null for SQL NULL, so the guard is on
            // the raw string: `fromValue(rs.getString(col))` would throw on
            // exactly the value a nullable enum column exists to hold.
            let _ = writeln!(
                out,
                "{}val {}Value = rs.getString(\"{}\")",
                indent, col.field_name, col.name
            );
            let _ = writeln!(
                out,
                "{}val {} = if ({}Value == null) null else {}.fromValue({}Value)",
                indent, col.field_name, col.field_name, col.lang_type, col.field_name
            );
            continue;
        }
        let _ = writeln!(
            out,
            "{}val {}Value = {}",
            indent,
            col.field_name,
            jvm_common::kotlin_jdbc_read_call(&col.name, &col.lang_type)
        );
        let _ = writeln!(
            out,
            "{}val {} = if (rs.wasNull()) null else {}Value",
            indent, col.field_name, col.field_name
        );
    }
}

/// Get the Exposed column type class for use in `exec()` parameter binding.
fn exposed_column_type_class(kotlin_type: &str) -> &str {
    match kotlin_type {
        "Boolean" => "BooleanColumnType()",
        "Byte" => "ByteColumnType()",
        "Short" => "ShortColumnType()",
        "Int" => "IntegerColumnType()",
        "Long" => "LongColumnType()",
        "Float" => "FloatColumnType()",
        "Double" => "DoubleColumnType()",
        "String" => "TextColumnType()",
        "ByteArray" => "BinaryColumnType()",
        _ if kotlin_type.contains("BigDecimal") => "DecimalColumnType(10, 2)",
        _ if kotlin_type.contains("LocalDate") => "JavaLocalDateColumnType()",
        _ if kotlin_type.contains("LocalTime") => "JavaLocalTimeColumnType()",
        _ if kotlin_type.contains("OffsetTime") => "JavaLocalTimeColumnType()",
        _ if kotlin_type.contains("LocalDateTime") => "JavaLocalDateTimeColumnType()",
        _ if kotlin_type.contains("OffsetDateTime") => "JavaOffsetDateTimeColumnType()",
        _ if kotlin_type.contains("UUID") => "UUIDColumnType()",
        _ => "TextColumnType()",
    }
}

/// ~keep The value bound at an Exposed `exec` placeholder for `param`.
///
/// An enum parameter is paired with `TextColumnType()` -- the SQL side genuinely is text --
/// but the *value* must be the enum's SQL spelling, not the Kotlin enum object. Exposed's
/// `exec(sql, args: List<Pair<IColumnType, Any?>>)` takes `Any?`, so binding the object
/// compiles and then fails at execution time against a `user_status` column. `.value` is the
/// accessor `generate_enum_def` already emits and the exact inverse of the `fromValue(...)`
/// the read path uses, so a value round-trips even when its SQL spelling is not the uppercase
/// of its variant name.
fn exposed_bind_value(param: &ResolvedParam) -> String {
    exposed_bind_value_for(param, &param.field_name)
}

fn exposed_bind_value_for(param: &ResolvedParam, receiver: &str) -> String {
    if param.neutral_type.starts_with("enum::") {
        format!("{receiver}?.value")
    } else if param.neutral_type.starts_with("composite::") {
        format!("{receiver}?.toPgText()")
    } else {
        receiver.to_string()
    }
}

impl CodegenBackend for KotlinExposedBackend {
    fn name(&self) -> &str {
        "kotlin-exposed"
    }

    fn manifest(&self) -> &scythe_backend::manifest::BackendManifest {
        &self.manifest
    }

    fn manifest_mut(&mut self) -> &mut scythe_backend::manifest::BackendManifest {
        &mut self.manifest
    }

    fn apply_options(&mut self, options: &HashMap<String, String>) -> Result<(), ScytheError> {
        reject_unknown_options(&["field_case"], options)?;

        if let Some(value) = options.get("field_case") {
            super::apply_field_case_option(&mut self.manifest.naming, "kotlin-exposed", value)?;
        }
        Ok(())
    }

    fn supported_engines(&self) -> &[&str] {
        &["postgresql"]
    }

    fn file_header(&self) -> String {
        // ~keep `package generated` to match kotlin_jdbc.rs:593 and the directory the CLI writes
        // into. Without it the file lands in the default package and any caller doing
        // `import generated.*` -- which is how every kotlin harness reaches the query functions --
        // fails with "Unresolved reference 'generated'". java_r2dbc and kotlin_r2dbc shipped with
        // the same omission; it stays invisible until something actually imports the output.
        "package generated\n\n\
         import org.jetbrains.exposed.v1.core.dao.id.IntIdTable\n\
         import org.jetbrains.exposed.v1.core.dao.id.LongIdTable\n\
         import org.jetbrains.exposed.v1.core.dao.id.java.UUIDTable\n\
         import org.jetbrains.exposed.v1.core.BinaryColumnType\n\
         import org.jetbrains.exposed.v1.core.BooleanColumnType\n\
         import org.jetbrains.exposed.v1.core.ByteColumnType\n\
         import org.jetbrains.exposed.v1.core.DecimalColumnType\n\
         import org.jetbrains.exposed.v1.core.IColumnType\n\
         import org.jetbrains.exposed.v1.core.DoubleColumnType\n\
         import org.jetbrains.exposed.v1.core.FloatColumnType\n\
         import org.jetbrains.exposed.v1.core.IntegerColumnType\n\
         import org.jetbrains.exposed.v1.core.LongColumnType\n\
         import org.jetbrains.exposed.v1.core.ShortColumnType\n\
         import org.jetbrains.exposed.v1.core.TextColumnType\n\
         import org.jetbrains.exposed.v1.core.java.UUIDColumnType\n\
         import org.jetbrains.exposed.v1.javatime.JavaLocalDateColumnType\n\
         import org.jetbrains.exposed.v1.javatime.JavaLocalDateTimeColumnType\n\
         import org.jetbrains.exposed.v1.javatime.JavaLocalTimeColumnType\n\
         import org.jetbrains.exposed.v1.javatime.JavaOffsetDateTimeColumnType\n\
         import org.jetbrains.exposed.v1.core.statements.StatementType\n\
         import org.jetbrains.exposed.v1.jdbc.transactions.transaction\n"
            .to_string()
    }

    fn generate_struct_decl(
        &self,
        struct_name: &str,
        _query_name: &str,
        columns: &[ResolvedColumn],
    ) -> Result<String, ScytheError> {
        let mut out = String::new();
        let _ = writeln!(out, "data class {}(", struct_name);
        for col in columns.iter() {
            let _ = writeln!(out, "    val {}: {},", col.field_name, col.full_type);
        }
        let _ = writeln!(out, ")");
        Ok(out)
    }

    /// #214: this used to declare only `object EvTable : IntIdTable("ev")`
    /// and no row type at all, while the query function `determine_struct_name`
    /// pairs it with constructs `Ev(...)` -- a type declared nowhere. Exposed's
    /// idiom genuinely is a table object (there is no idiomatic way to drop
    /// it), so the fix emits *both*: the table object, for callers who want to
    /// build Exposed DSL queries against it, and the `data class` the query
    /// function already references.
    ///
    /// `struct_name` is derived through [`crate::model_struct_name`] -- the
    /// same function the base trait's default `generate_model_struct` and
    /// `determine_struct_name` both use -- not `to_pascal_case(table_name)`,
    /// whose un-singularized spelling (`"events"` -> `Events`, not `Event`) is
    /// exactly the #164 divergence this repo already fixed for every other
    /// backend.
    fn generate_model_struct(&self, table_name: &str, columns: &[ResolvedColumn]) -> Result<String, ScytheError> {
        let struct_name = crate::model_struct_name(table_name, &self.manifest.naming);
        let table_obj_name = format!("{}Table", struct_name);
        let mut out = String::new();
        let table_base = exposed_id_table_type(columns);
        let _ = writeln!(out, "object {} : {}(\"{}\") {{", table_obj_name, table_base, table_name);
        for col in columns.iter() {
            let col_fn = exposed_column_fn(&col.lang_type);
            let nullable_suffix = if col.nullable { ".nullable()" } else { "" };
            let _ = writeln!(
                out,
                "    val {} = {}(\"{}\"){}",
                col.field_name, col_fn, col.name, nullable_suffix
            );
        }
        let _ = writeln!(out, "}}");
        let _ = writeln!(out);
        let row_decl = self.generate_struct_decl(&struct_name, &struct_name, columns)?;
        out.push_str(&row_decl);
        Ok(out)
    }

    fn generate_query_fn(
        &self,
        analyzed: &AnalyzedQuery,
        struct_name: &str,
        columns: &[ResolvedColumn],
        params: &[ResolvedParam],
    ) -> Result<String, ScytheError> {
        let func_name = fn_name(&analyzed.name, &self.manifest.naming);
        let dialect = SqlDialect::PostgreSQL;
        let cleaned_sql = super::clean_sql_oneline_with_optional_dialect(
            &analyzed.sql,
            dialect,
            &analyzed.optional_params,
            &analyzed.params,
        );
        let (rewritten_sql, occurrences) =
            super::rewrite_pg_typed_placeholders(&cleaned_sql, &analyzed.params, params, true, |_| "?".to_string());
        let sql = crate::sql_literal::escape_kotlin_string(&rewritten_sql);

        let mut out = String::new();

        let write_fn_sig = |out: &mut String, name: &str, ret: &str, params: &[ResolvedParam]| {
            let inline_params: String = params
                .iter()
                .map(|p| format!("{}: {}", p.field_name, p.full_type))
                .collect::<Vec<_>>()
                .join(", ");
            let sig = format!("fun {}({}){} =", name, inline_params, ret);
            if sig.len() <= 100 {
                let _ = writeln!(out, "{}", sig);
            } else {
                let _ = writeln!(out, "fun {}(", name);
                for p in params {
                    let _ = writeln!(out, "    {}: {},", p.field_name, p.full_type);
                }
                let _ = writeln!(out, "){} =", ret);
            }
            let _ = writeln!(out, "    transaction {{");
        };

        let build_args = |occurrences: &[u32]| -> String {
            if occurrences.is_empty() {
                return String::new();
            }
            let pairs: Vec<String> = occurrences
                .iter()
                .map(|&position| {
                    let p = super::resolved_param_for_position(&analyzed.params, params, position);
                    format!(
                        "{} to {}",
                        exposed_column_type_class(&p.lang_type),
                        exposed_bind_value(p)
                    )
                })
                .collect();
            // ~keep The explicit element type is load-bearing, not decoration. A bare `listOf(...)`
            // makes Kotlin infer one `T` across heterogeneous pairs, and with a mixed
            // parameter set -- `Pair<TextColumnType, String>` beside
            // `Pair<UUIDColumnType, UUID>` and `Pair<TextColumnType, TortureAddress?>` --
            // inference gives up: "Not enough information to infer type argument for 'T'",
            // then a cascade that even reports "actual type is 'String', but 'String' was
            // expected". Naming the type Exposed's `exec` actually takes short-circuits all
            // of it. The pg fixture happened to infer cleanly; the torture schema did not.
            format!(", listOf<Pair<IColumnType<*>, Any?>>({})", pairs.join(", "))
        };

        match &analyzed.command {
            QueryCommand::Exec => {
                write_fn_sig(&mut out, &func_name, "", params);
                let args = build_args(&occurrences);
                let _ = writeln!(out, "        exec(\"{}\"{})", sql, args);
                let _ = writeln!(out, "    }}");
            }
            QueryCommand::ExecResult | QueryCommand::ExecRows => {
                // ~keep This used to emit `exec(sql, args) ?: 0` typed `: Int`, which never
                // compiled against any Exposed this backend could resolve: the no-transform
                // `Transaction.exec(String, Iterable<Pair<IColumnType<*>, Any?>>, StatementType?)`
                // returns `Unit`, not `Int?` (verified from the exposed-core jar for both 0.56.0
                // and 0.61.0), so the elvis produced `Any` and the function failed with
                // "actual type is 'Any', but 'Int' was expected". Exposed surfaces an update count
                // only through the prepared-statement API, so that is what an affected-rows query
                // has to use. `false` is `returnKeys` -- these queries want the count, not
                // generated keys.
                write_fn_sig(&mut out, &func_name, ": Int", params);
                let args = build_args(&occurrences);
                let _ = writeln!(
                    out,
                    "        val stmt = connection.prepareStatement(\"{}\", false)",
                    sql
                );
                if !args.is_empty() {
                    // `build_args` renders a leading ", " for the exec call site; this one needs
                    // the list on its own.
                    let list = args.trim_start_matches(", ");
                    let _ = writeln!(out, "        stmt.fillParameters({})", list);
                }
                let _ = writeln!(out, "        stmt.executeUpdate()");
                let _ = writeln!(out, "    }}");
            }
            QueryCommand::One | QueryCommand::Opt => {
                // ~keep #192: see java-jdbc's generate_query_fn for the full
                // reasoning -- this shared arm used to render byte-identical
                // code for :one and :opt, so :one silently returned null on a
                // missing row instead of erroring. `is_one` is the only
                // difference from here down. The `rs.next()` if/else itself
                // -- including its `null` branch -- stays identical between
                // :one and :opt: `Transaction.exec(sql) { rs -> T }` returns
                // `T?` regardless of what the lambda's branches do, so a
                // throw *inside* the lambda would not change the static
                // nullability of the `exec(...)` call it's nested in, and
                // `: {Struct}` (no `?`) would not type-check against it. The
                // fallback instead sits on the *outer* call, as `exec(...) {
                // ... } ?: throw NoSuchElementException(...)` -- turning the
                // nullable result non-null the same way it would for a
                // driver-level absent-ResultSet null, not only the
                // rs.next()-false case (`kotlin.NoSuchElementException` is in
                // Kotlin's default imports, so no import is needed).
                let is_one = matches!(analyzed.command, QueryCommand::One);
                let ret = if is_one {
                    format!(": {}", struct_name)
                } else {
                    format!(": {}?", struct_name)
                };
                write_fn_sig(&mut out, &func_name, &ret, params);
                let args = build_args(&occurrences);
                let _ = writeln!(
                    out,
                    "        exec(\"{}\"{}, explicitStatementType = StatementType.SELECT) {{ rs ->",
                    sql, args
                );
                let _ = writeln!(out, "            if (rs.next()) {{");
                write_exposed_nullable_preamble(&mut out, columns, "                ", &self.manifest);
                let _ = writeln!(out, "                {}(", struct_name);
                for col in columns.iter() {
                    let _ = writeln!(
                        out,
                        "                    {} = {},",
                        col.field_name,
                        exposed_rs_expr(col, &self.manifest)
                    );
                }
                let _ = writeln!(out, "                )");
                let _ = writeln!(out, "            }} else {{");
                let _ = writeln!(out, "                null");
                let _ = writeln!(out, "            }}");
                if is_one {
                    let _ = writeln!(
                        out,
                        "        }} ?: throw NoSuchElementException(\"{}: no rows returned\")",
                        func_name
                    );
                } else {
                    let _ = writeln!(out, "        }}");
                }
                let _ = writeln!(out, "    }}");
            }
            QueryCommand::Batch => {
                let batch_fn_name = format!("{}Batch", func_name);
                if params.len() > 1 {
                    let params_class_name = format!("{}BatchParams", to_pascal_case(&analyzed.name));
                    let _ = writeln!(out, "data class {}(", params_class_name);
                    for p in params {
                        let _ = writeln!(out, "    val {}: {},", p.field_name, p.full_type);
                    }
                    let _ = writeln!(out, ")");
                    let _ = writeln!(out);
                    let _ = writeln!(out, "fun {}(items: List<{}>) =", batch_fn_name, params_class_name);
                    let _ = writeln!(out, "    transaction {{");
                    let _ = writeln!(out, "        for (item in items) {{");
                    let args: Vec<String> = occurrences
                        .iter()
                        .map(|&position| {
                            let p = super::resolved_param_for_position(&analyzed.params, params, position);
                            let receiver = format!("item.{}", p.field_name);
                            format!(
                                "{} to {}",
                                exposed_column_type_class(&p.lang_type),
                                exposed_bind_value_for(p, &receiver)
                            )
                        })
                        .collect();
                    let _ = writeln!(out, "            exec(\"{}\", listOf({}))", sql, args.join(", "));
                    let _ = writeln!(out, "        }}");
                    let _ = writeln!(out, "    }}");
                } else if params.len() == 1 {
                    let _ = writeln!(out, "fun {}(items: List<{}>) =", batch_fn_name, params[0].full_type);
                    let _ = writeln!(out, "    transaction {{");
                    let _ = writeln!(out, "        for (item in items) {{");
                    let args: Vec<String> = occurrences
                        .iter()
                        .map(|_| {
                            format!(
                                "{} to {}",
                                exposed_column_type_class(&params[0].lang_type),
                                exposed_bind_value_for(&params[0], "item")
                            )
                        })
                        .collect();
                    let _ = writeln!(out, "            exec(\"{}\", listOf({}))", sql, args.join(", "));
                    let _ = writeln!(out, "        }}");
                    let _ = writeln!(out, "    }}");
                } else {
                    let _ = writeln!(out, "fun {}(count: Int) =", batch_fn_name);
                    let _ = writeln!(out, "    transaction {{");
                    let _ = writeln!(out, "        repeat(count) {{");
                    let _ = writeln!(out, "            exec(\"{}\")", sql);
                    let _ = writeln!(out, "        }}");
                    let _ = writeln!(out, "    }}");
                }
            }
            QueryCommand::Grouped => {
                unreachable!("routed to generate_grouped_query_fn")
            }
            QueryCommand::Many => {
                let ret = format!(": List<{}>", struct_name);
                write_fn_sig(&mut out, &func_name, &ret, params);
                let args = build_args(&occurrences);
                let _ = writeln!(out, "        val result = mutableListOf<{}>()", struct_name);
                let _ = writeln!(
                    out,
                    "        exec(\"{}\"{}, explicitStatementType = StatementType.SELECT) {{ rs ->",
                    sql, args
                );
                let _ = writeln!(out, "            while (rs.next()) {{");
                write_exposed_nullable_preamble(&mut out, columns, "                ", &self.manifest);
                let _ = writeln!(out, "                result.add(");
                let _ = writeln!(out, "                    {}(", struct_name);
                for col in columns.iter() {
                    let _ = writeln!(
                        out,
                        "                        {} = {},",
                        col.field_name,
                        exposed_rs_expr(col, &self.manifest)
                    );
                }
                let _ = writeln!(out, "                    ),");
                let _ = writeln!(out, "                )");
                let _ = writeln!(out, "            }}");
                let _ = writeln!(out, "        }}");
                let _ = writeln!(out, "        result");
                let _ = writeln!(out, "    }}");
            }
        }

        Ok(out)
    }

    fn generate_enum_def(&self, enum_info: &EnumInfo) -> Result<String, ScytheError> {
        let type_name = enum_type_name(&enum_info.sql_name, &self.manifest.naming);
        let mut out = String::new();
        let _ = writeln!(out, "enum class {}(val value: String) {{", type_name);
        for (i, value) in enum_info.values.iter().enumerate() {
            let variant = enum_variant_name(value, &self.manifest.naming);
            let sep = if i + 1 < enum_info.values.len() { "," } else { ";" };
            let _ = writeln!(out, "    {}(\"{}\"){}", variant, value, sep);
        }
        let _ = writeln!(out);
        // ~keep #213: see `java_jdbc.rs`'s `generate_enum_def` for the full
        // reasoning -- decoding against the declared `value` rather than the
        // sanitised variant spelling is what makes `fromValue(x.value) == x`
        // hold for every variant.
        let _ = writeln!(out, "    companion object {{");
        let _ = writeln!(out, "        fun fromValue(value: String): {} =", type_name);
        let _ = writeln!(out, "            values().firstOrNull {{ it.value == value }}");
        let _ = writeln!(
            out,
            "                ?: throw IllegalArgumentException(\"Unknown {} value: $value\")",
            type_name
        );
        let _ = writeln!(out, "    }}");
        let _ = writeln!(out, "}}");
        Ok(out)
    }

    fn generate_composite_def(&self, composite: &CompositeInfo) -> Result<String, ScytheError> {
        let name = composite_type_name(&composite.sql_name, &self.manifest.naming);
        let mut out = String::new();
        let field_types: Vec<String> = composite
            .fields
            .iter()
            .map(|f| {
                resolve_type(&f.neutral_type, &self.manifest, f.nullable)
                    .map(|t| t.into_owned())
                    .unwrap_or_else(|_| "Any".to_string())
            })
            .collect();
        let field_base_types: Vec<String> = composite
            .fields
            .iter()
            .map(|f| {
                resolve_type(&f.neutral_type, &self.manifest, false)
                    .map(|t| t.into_owned())
                    .unwrap_or_else(|_| "Any".to_string())
            })
            .collect();
        let _ = writeln!(out, "data class {}(", name);
        for (field, field_type) in composite.fields.iter().zip(&field_types) {
            let field_name = to_camel_case(&field.name);
            let _ = writeln!(out, "    val {}: {},", field_name, field_type);
        }
        // ~keep board #196: a zero-field composite cannot exist in PostgreSQL (`CREATE TYPE ...
        // AS ()` is rejected), so -- like `kotlin_jdbc.rs`'s twin case -- there is no reachable
        // runtime value that would need a `fromText` here.
        if composite.fields.is_empty() {
            let _ = writeln!(out, ")");
            return Ok(out);
        }
        let _ = writeln!(out, ") {{");
        let encoded_fields = composite
            .fields
            .iter()
            .map(|field| {
                let field_name = to_camel_case(&field.name);
                if field.neutral_type.starts_with("composite::") {
                    format!("{field_name}?.toPgText()")
                } else if field.neutral_type.starts_with("enum::") {
                    format!("{field_name}?.value")
                } else if field.neutral_type == "bytes" {
                    format!("{field_name}?.joinToString(\"\") {{ \"%02x\".format(it) }}?.let {{ \"\\\\\\\\x\" + it }}")
                } else {
                    field_name.into_owned()
                }
            })
            .collect::<Vec<_>>()
            .join(", ");
        let _ = writeln!(
            out,
            "    fun toPgText(): String = listOf({encoded_fields}).joinToString(\",\", \"(\", \")\") {{ encodeCompositeField(it) }}"
        );
        let _ = writeln!(out);
        let _ = writeln!(out, "    companion object {{");
        let _ = writeln!(out, "        private fun encodeCompositeField(value: Any?): String {{");
        let _ = writeln!(out, "            if (value == null) return \"\"");
        let _ = writeln!(out, "            val raw = value.toString()");
        out.push_str(
            r#"            val quote = raw.isEmpty() || raw.any { it in charArrayOf('(', ')', ',', '"', '\\') } || raw != raw.trim()
"#,
        );
        let _ = writeln!(out, "            if (!quote) return raw");
        out.push_str(
            r#"            return "\"" + raw.replace("\\", "\\\\").replace("\"", "\"\"") + "\""
"#,
        );
        let _ = writeln!(out, "        }}");
        let _ = writeln!(out);
        let _ = writeln!(out, "        /**");
        let _ = writeln!(
            out,
            "         * ~keep board #196: pgjdbc registers no `getObject(col, {}::class.java)`",
            name
        );
        let _ = writeln!(
            out,
            "         * type map for this composite -- it throws `PSQLException: conversion to"
        );
        let _ = writeln!(
            out,
            "         * class {}` at runtime. Parse the driver's composite text form instead.",
            name
        );
        let _ = writeln!(out, "         */");
        let _ = writeln!(out, "        fun fromText(text: String?): {}? {{", name);
        let _ = writeln!(out, "            if (text == null) {{");
        let _ = writeln!(out, "                return null");
        let _ = writeln!(out, "            }}");
        let _ = writeln!(out, "            val f = parseCompositeFields(text)");
        let _ = writeln!(out, "            return {}(", name);
        for (i, (field, field_type)) in composite.fields.iter().zip(&field_base_types).enumerate() {
            let raw = format!("f[{}]", i);
            let expr = if field.nullable {
                let conversion =
                    composite_field_from_text_kotlin(&field.neutral_type, field_type, "value", &self.manifest);
                format!("{raw}?.let {{ value -> {conversion} }}")
            } else {
                composite_field_from_text_kotlin(&field.neutral_type, field_type, &format!("{raw}!!"), &self.manifest)
            };
            let _ = writeln!(out, "                {},", expr);
        }
        let _ = writeln!(out, "            )");
        let _ = writeln!(out, "        }}");
        let _ = writeln!(out);
        out.push_str(KT_PARSE_COMPOSITE_FIELDS_METHOD);
        if composite_needs_bytes_helper(composite) {
            let _ = writeln!(out);
            out.push_str(KT_PARSE_COMPOSITE_BYTES_METHOD);
        }
        if composite_needs_offset_datetime_helper(composite) {
            let _ = writeln!(out);
            out.push_str(KT_PARSE_COMPOSITE_OFFSET_DATETIME_METHOD);
        }
        if composite_needs_offset_time_helper(composite) {
            let _ = writeln!(out);
            out.push_str(KT_PARSE_COMPOSITE_OFFSET_TIME_METHOD);
        }
        let _ = writeln!(out, "    }}");
        let _ = writeln!(out, "}}");
        Ok(out)
    }

    fn generate_grouped_structs(
        &self,
        parent_struct_name: &str,
        child_struct_name: &str,
        parent_columns: &[ResolvedColumn],
        child_columns: &[ResolvedColumn],
        _key_column: &str,
    ) -> Result<String, ScytheError> {
        let mut out = String::new();

        let _ = writeln!(out, "data class {}(", child_struct_name);
        for col in child_columns {
            let _ = writeln!(out, "    val {}: {},", col.field_name, col.full_type);
        }
        let _ = writeln!(out, ")");
        let _ = writeln!(out);

        let _ = writeln!(out, "data class {}(", parent_struct_name);
        for col in parent_columns {
            let _ = writeln!(out, "    val {}: {},", col.field_name, col.full_type);
        }
        let _ = writeln!(out, "    val children: MutableList<{}>,", child_struct_name);
        let _ = write!(out, ")");

        Ok(out)
    }

    fn generate_grouped_query_fn(&self, request: &GroupedQueryFn<'_>) -> Result<String, ScytheError> {
        let analyzed = request.analyzed;
        let parent_struct_name = request.parent_struct_name;
        let child_struct_name = request.child_struct_name;
        let parent_columns = request.parent_columns;
        let child_columns = request.child_columns;
        let params = request.params;
        let key_column = request.key_column;

        let func_name = fn_name(&analyzed.name, &self.manifest.naming);
        let dialect = SqlDialect::PostgreSQL;
        let cleaned_sql = super::clean_sql_oneline_with_optional_dialect(
            &analyzed.sql,
            dialect,
            &analyzed.optional_params,
            &analyzed.params,
        );
        let (rewritten_sql, occurrences) =
            super::rewrite_pg_typed_placeholders(&cleaned_sql, &analyzed.params, params, true, |_| "?".to_string());
        let sql = crate::sql_literal::escape_kotlin_string(&rewritten_sql);

        let key_col = parent_columns
            .iter()
            .find(|c| c.name == key_column)
            .unwrap_or(&parent_columns[0]);
        let key_type = key_col.full_type.trim_end_matches('?');

        let args = if occurrences.is_empty() {
            String::new()
        } else {
            let pairs: Vec<String> = occurrences
                .iter()
                .map(|&position| {
                    let p = super::resolved_param_for_position(&analyzed.params, params, position);
                    format!(
                        "{} to {}",
                        exposed_column_type_class(&p.lang_type),
                        exposed_bind_value(p)
                    )
                })
                .collect();
            // ~keep The explicit element type is load-bearing, not decoration. A bare `listOf(...)`
            // makes Kotlin infer one `T` across heterogeneous pairs, and with a mixed
            // parameter set -- `Pair<TextColumnType, String>` beside
            // `Pair<UUIDColumnType, UUID>` and `Pair<TextColumnType, TortureAddress?>` --
            // inference gives up: "Not enough information to infer type argument for 'T'",
            // then a cascade that even reports "actual type is 'String', but 'String' was
            // expected". Naming the type Exposed's `exec` actually takes short-circuits all
            // of it. The pg fixture happened to infer cleanly; the torture schema did not.
            format!(", listOf<Pair<IColumnType<*>, Any?>>({})", pairs.join(", "))
        };

        let inline_params: String = params
            .iter()
            .map(|p| format!("{}: {}", p.field_name, p.full_type))
            .collect::<Vec<_>>()
            .join(", ");
        let sig = format!("fun {}({}): List<{parent_struct_name}> =", func_name, inline_params);
        let mut out = String::new();
        if sig.len() <= 100 {
            let _ = writeln!(out, "{sig}");
        } else {
            let _ = writeln!(out, "fun {}(", func_name);
            for p in params {
                let _ = writeln!(out, "    {}: {},", p.field_name, p.full_type);
            }
            let _ = writeln!(out, "): List<{parent_struct_name}> =");
        }
        let _ = writeln!(out, "    transaction {{");
        let _ = writeln!(
            out,
            "        val lookup = LinkedHashMap<{key_type}, {parent_struct_name}>()"
        );
        let _ = writeln!(out, "        val result = mutableListOf<{parent_struct_name}>()");
        let _ = writeln!(out, "        exec(\"{sql}\"{args}) {{ rs ->");
        let _ = writeln!(out, "            while (rs.next()) {{");

        write_exposed_nullable_preamble(&mut out, child_columns, "                ", &self.manifest);
        write_exposed_nullable_preamble(&mut out, parent_columns, "                ", &self.manifest);

        let key_expr = exposed_rs_expr(key_col, &self.manifest);
        let _ = writeln!(out, "                val key = {key_expr}");

        let _ = writeln!(out, "                val child = {child_struct_name}(");
        for col in child_columns {
            let _ = writeln!(
                out,
                "                    {} = {},",
                col.field_name,
                exposed_rs_expr(col, &self.manifest)
            );
        }
        let _ = writeln!(out, "                )");

        let _ = writeln!(out, "                if (lookup.containsKey(key)) {{");
        let _ = writeln!(out, "                    lookup[key]!!.children.add(child)");
        let _ = writeln!(out, "                }} else {{");
        let _ = writeln!(out, "                    val parent = {parent_struct_name}(");
        for col in parent_columns {
            let _ = writeln!(
                out,
                "                        {} = {},",
                col.field_name,
                exposed_rs_expr(col, &self.manifest)
            );
        }
        let _ = writeln!(out, "                        children = mutableListOf(child),");
        let _ = writeln!(out, "                    )");
        let _ = writeln!(out, "                    lookup[key] = parent");
        let _ = writeln!(out, "                    result.add(parent)");
        let _ = writeln!(out, "                }}");
        let _ = writeln!(out, "            }}");
        let _ = writeln!(out, "        }}");
        let _ = writeln!(out, "        result");
        let _ = write!(out, "    }}");

        Ok(out)
    }
}

fn exposed_id_table_type(columns: &[ResolvedColumn]) -> &str {
    let Some(id_column) = columns.iter().find(|column| column.name.eq_ignore_ascii_case("id")) else {
        return "IntIdTable";
    };
    match id_column.lang_type.as_str() {
        "Long" => "LongIdTable",
        ty if ty.contains("UUID") => "UUIDTable",
        _ => "IntIdTable",
    }
}

#[cfg(test)]
mod tests {
    use std::collections::HashMap;

    use scythe_core::analyzer::{
        AnalyzedColumn, AnalyzedParam, AnalyzedQuery, CompositeFieldInfo, CompositeInfo, GroupByConfig,
    };
    use scythe_core::parser::QueryCommand;

    use super::KotlinExposedBackend;
    use crate::backend_trait::CodegenBackend;

    #[test]
    fn generated_fixture_uses_exposed_v1_imports() {
        let backend = KotlinExposedBackend::new("postgresql").unwrap();
        let header = backend.file_header();
        let fixture = include_str!("../../../../integration_tests/kotlin-exposed/src/main/kotlin/generated/queries.kt");
        let imports = |source: &str| {
            source
                .lines()
                .filter(|line| line.starts_with("import org.jetbrains.exposed."))
                .map(str::to_owned)
                .collect::<Vec<_>>()
        };

        assert_eq!(imports(&header), imports(fixture));
        assert!(header.contains("import org.jetbrains.exposed.v1.core.java.UUIDColumnType"));
        assert!(header.contains("import org.jetbrains.exposed.v1.core.dao.id.java.UUIDTable"));
        assert!(header.contains("import org.jetbrains.exposed.v1.jdbc.transactions.transaction"));
        assert!(!header.contains("org.jetbrains.exposed.sql."));
        assert!(!header.contains("org.jetbrains.exposed.dao."));
    }

    fn make_grouped_query() -> AnalyzedQuery {
        let parent_cols = vec![
            AnalyzedColumn {
                name: "id".to_string(),
                neutral_type: "int32".to_string(),
                nullable: false,
                ..Default::default()
            },
            AnalyzedColumn {
                name: "name".to_string(),
                neutral_type: "string".to_string(),
                nullable: false,
                ..Default::default()
            },
        ];
        let child_cols = vec![
            AnalyzedColumn {
                name: "order_id".to_string(),
                neutral_type: "int32".to_string(),
                nullable: false,
                ..Default::default()
            },
            AnalyzedColumn {
                name: "total".to_string(),
                neutral_type: "decimal".to_string(),
                nullable: true,
                ..Default::default()
            },
        ];
        let all_cols = [parent_cols.clone(), child_cols.clone()].concat();
        AnalyzedQuery::build(|aq| {
            aq.name = "GetUsersWithOrders".to_string();
            aq.command = QueryCommand::Grouped;
            aq.sql = "SELECT u.id, u.name, o.id AS order_id, o.total FROM users u JOIN orders o ON o.user_id = u.id"
                .to_string();
            aq.columns = all_cols;
            aq.params = vec![];
            aq.deprecated = None;
            aq.source_table = None;
            aq.composites = vec![];
            aq.enums = vec![];
            aq.optional_params = vec![];
            aq.group_by = Some(GroupByConfig {
                table: "users".to_string(),
                key_column: "id".to_string(),
                parent_columns: parent_cols,
                child_columns: child_cols,
            });
            aq.custom = vec![];
        })
    }

    #[test]
    fn test_grouped_kotlin_exposed_structs() {
        let backend = crate::backends::get_backend("kotlin-exposed", "postgresql").unwrap();
        let query = make_grouped_query();
        let result = crate::generate_with_backend(&query, &*backend).unwrap();
        let row_struct = result.row_struct.as_deref().unwrap();

        assert!(
            row_struct.contains("data class GetUsersWithOrdersChildRow"),
            "missing child data class; got:\n{row_struct}"
        );
        assert!(
            row_struct.contains("data class GetUsersWithOrdersRow"),
            "missing parent data class; got:\n{row_struct}"
        );
        assert!(
            row_struct.contains("val children: MutableList<GetUsersWithOrdersChildRow>"),
            "parent missing children field; got:\n{row_struct}"
        );
        let child_pos = row_struct.find("data class GetUsersWithOrdersChildRow").unwrap();
        let parent_pos = row_struct.find("data class GetUsersWithOrdersRow(").unwrap();
        assert!(child_pos < parent_pos, "child must precede parent");
    }

    #[test]
    fn test_grouped_kotlin_exposed_query_fn() {
        let backend = crate::backends::get_backend("kotlin-exposed", "postgresql").unwrap();
        let query = make_grouped_query();
        let result = crate::generate_with_backend(&query, &*backend).unwrap();
        let query_fn = result.query_fn.as_deref().unwrap();

        assert!(
            query_fn.contains("List<GetUsersWithOrdersRow>"),
            "wrong return type; got:\n{query_fn}"
        );
        assert!(
            query_fn.contains("transaction {"),
            "must use transaction block; got:\n{query_fn}"
        );
        assert!(
            query_fn.contains("LinkedHashMap"),
            "must use LinkedHashMap for fold lookup; got:\n{query_fn}"
        );
        assert!(
            query_fn.contains("lookup.containsKey(key)"),
            "must fold with containsKey; got:\n{query_fn}"
        );
        assert!(
            query_fn.contains("children.add(child)"),
            "must append child; got:\n{query_fn}"
        );
    }

    fn make_one_query_with_snake_case_columns() -> AnalyzedQuery {
        AnalyzedQuery::build(|q| {
            q.name = "GetSession".to_string();
            q.command = QueryCommand::One;
            q.sql = "SELECT id, user_id FROM sessions WHERE id = $1".to_string();
            q.columns = vec![
                AnalyzedColumn {
                    name: "id".to_string(),
                    neutral_type: "int32".to_string(),
                    nullable: false,
                    ..Default::default()
                },
                AnalyzedColumn {
                    name: "user_id".to_string(),
                    neutral_type: "int32".to_string(),
                    nullable: false,
                    ..Default::default()
                },
            ];
            // ~keep The SQL text declares `$1`; the analyzer would always
            // register a matching `AnalyzedParam` for a placeholder it sees,
            // so an empty list here (as this fixture had before #149) is a
            // combination the real pipeline never produces and panics
            // `resolved_param_for_position` (#149's occurrence-based bind
            // lookup has no position to resolve `$1` against).
            q.params = vec![AnalyzedParam {
                name: "id".to_string(),
                neutral_type: "int32".to_string(),
                nullable: false,
                position: 1,
                source_relation: None,
            }];
            q.deprecated = None;
            q.source_table = None;
            q.composites = vec![];
            q.enums = vec![];
            q.optional_params = vec![];
            q.group_by = None;
            q.custom = vec![];
        })
    }

    /// The safety invariant this whole feature depends on: renaming the
    /// declared field must never touch the key the driver is asked to look
    /// up. `generate_query_fn`'s `One`/`Opt` branch reads `rs.getInt(col.name)`
    /// -- the raw SQL column name -- and only the data class' declared
    /// property (`col.field_name`) changes under `field_case = "camelCase"`.
    #[test]
    fn test_field_case_camel_case_renames_field_but_keeps_raw_lookup_key() {
        let mut backend = KotlinExposedBackend::new("postgresql").unwrap();
        backend
            .apply_options(&HashMap::from([("field_case".to_string(), "camelCase".to_string())]))
            .unwrap();
        let query = make_one_query_with_snake_case_columns();
        let result = crate::generate_with_backend(&query, &backend).unwrap();
        let row_struct = result.row_struct.as_deref().unwrap();
        let query_fn = result.query_fn.as_deref().unwrap();

        assert!(
            row_struct.contains("val userId: Int"),
            "field_case must rename the declared data class property; got:\n{row_struct}"
        );
        assert!(
            !row_struct.contains("val user_id"),
            "must not leave the raw SQL name in the declared property; got:\n{row_struct}"
        );
        assert!(
            query_fn.contains("userId = rs.getInt(\"user_id\")"),
            "the ResultSet lookup key must stay the raw SQL column name; got:\n{query_fn}"
        );
        assert!(
            !query_fn.contains("rs.getInt(\"userId\")"),
            "must never look the driver up by the renamed field; got:\n{query_fn}"
        );
    }

    fn make_select_star_query() -> AnalyzedQuery {
        AnalyzedQuery::build(|q| {
            q.name = "GetAllUsers".to_string();
            q.command = QueryCommand::Many;
            q.sql = "SELECT * FROM users".to_string();
            q.columns = vec![
                AnalyzedColumn {
                    name: "id".to_string(),
                    neutral_type: "int32".to_string(),
                    nullable: false,
                    ..Default::default()
                },
                AnalyzedColumn {
                    name: "name".to_string(),
                    neutral_type: "string".to_string(),
                    nullable: false,
                    ..Default::default()
                },
            ];
            q.params = vec![];
            q.deprecated = None;
            q.source_table = Some("users".to_string());
            q.composites = vec![];
            q.enums = vec![];
            q.optional_params = vec![];
            q.group_by = None;
            q.custom = vec![];
        })
    }

    /// #214: `generate_model_struct` used to emit only the Exposed table
    /// object (`object UserTable : IntIdTable("users")`), never a row type,
    /// while `determine_struct_name` -- shared naming code this backend does
    /// not control -- decided the query function would construct `User(...)`,
    /// a type declared nowhere. `test_select_star_declares_and_references_the_same_struct_name_across_all_backends`
    /// in `lib.rs` checks this invariant generically across every backend;
    /// this test exercises the same fix directly so it lives with the code it
    /// covers.
    #[test]
    fn test_select_star_declares_both_the_table_object_and_the_row_data_class() {
        let backend = KotlinExposedBackend::new("postgresql").unwrap();
        let query = make_select_star_query();
        let result = crate::generate_with_backend(&query, &backend).unwrap();
        let model_struct = result.model_struct.as_deref().unwrap();
        let query_fn = result.query_fn.as_deref().unwrap();

        assert!(
            model_struct.contains("object UserTable : IntIdTable(\"users\") {"),
            "must still declare the Exposed table object; got:\n{model_struct}"
        );
        assert!(
            model_struct.contains("data class User("),
            "must also declare the row type the query function references; got:\n{model_struct}"
        );
        assert!(
            query_fn.contains("User("),
            "the query function must construct the declared row type; got:\n{query_fn}"
        );
    }

    #[test]
    fn test_field_case_option_rejects_invalid_value() {
        let mut backend = KotlinExposedBackend::new("postgresql").unwrap();
        let result = backend.apply_options(&HashMap::from([("field_case".to_string(), "PascalCase".to_string())]));
        assert!(result.is_err(), "expected 'PascalCase' to be rejected");
    }

    fn make_composite_with_consecutive_capitals() -> CompositeInfo {
        CompositeInfo {
            sql_name: "CreateAPIKey".to_string(),
            fields: vec![
                CompositeFieldInfo {
                    name: "HTTPSUrl".to_string(),
                    neutral_type: "string".to_string(),
                    nullable: false,
                },
                CompositeFieldInfo {
                    name: "internal_id".to_string(),
                    neutral_type: "int32".to_string(),
                    nullable: false,
                },
            ],
        }
    }

    /// `to_pascal_case`/`to_camel_case` now normalize consecutive capitals
    /// through `to_snake_case` (commit 6ab8994), so a composite's field
    /// names that carry runs of capitals ("HTTPSUrl") changed shape here too
    /// -- this backend's `generate_composite_def` had no coverage of that
    /// change landing.
    #[test]
    fn test_composite_def_normalizes_consecutive_capitals() {
        let backend = KotlinExposedBackend::new("postgresql").unwrap();
        let composite = make_composite_with_consecutive_capitals();
        let def = backend.generate_composite_def(&composite).unwrap();

        assert!(
            def.contains("data class CreateApiKey("),
            "composite type name must normalize consecutive capitals; got:\n{def}"
        );
        assert!(
            def.contains("val httpsUrl: String"),
            "composite field name must normalize consecutive capitals; got:\n{def}"
        );
        assert!(
            def.contains("val internalId: Int"),
            "composite field name must still camelCase a plain snake_case field; got:\n{def}"
        );
    }
}