ttstd_family_care/.agents/skills/kotlin-tooling-java-to-kotlin/references/CONVERSION-METHODOLOGY.md

# Conversion Methodology

You are a senior Kotlin engineer and Java-Kotlin JVM interop specialist. Your task is
to convert provided Java code into **idiomatic Kotlin**, preserving behaviour while
improving readability, safety and maintainability.

## The 4-Step Precognition Process

Before emitting any code, run through the provided Java input and perform these 4 steps
of thinking. After each step, output the code as you have it after that step's
transformation has been applied.

### Step 1: Faithful 1:1 Translation

Convert the Java code 1 to 1 into Kotlin, prioritising faithfulness to the original
Java semantics, to replicate the Java code's functionality and logic exactly.

**Rules:**
- Java classes that are implicitly open MUST be converted as Kotlin classes that are
  explicitly `open`, using the `open` keyword.
- To convert Java constructors that inject into fields, use the Kotlin primary
  constructor. Any further logic within the Java constructor can be replicated with the
  Kotlin secondary constructor.

### Step 2: Nullability & Mutability

Check that mutability and nullability are correctly expressed in your Kotlin conversion.
Only express types as non-null where you are sure that it can never be null, inferred
from the original Java. Use `val` instead of `var` where you see variables that are
never modified.

**Rules:**
- If you see a logical assertion that a value is not null (e.g., `Objects.requireNonNull`),
  this shows that the author has considered that the value can never be null. Use a
  non-null type in this case, and remove the logical assertion.
- In all other cases, preserve the fact that types can be null in Java by using the
  Kotlin nullable version of that type.

### Step 3: Collection Type Conversion

Convert datatypes like collections from their Java variants to the Kotlin variants.

**Rules:**
- For Java collections like `List` that are mutable by default, always use the Kotlin
  `MutableList`, unless you see explicitly that the Java code uses an immutable wrapper
  (e.g., `Collections.unmodifiableList()`) — in this case, use the Kotlin `List` (and
  so on for other collections like `Set`, `Map` etc.)

### Step 4: Idiomatic Transformations

Introduce syntactic transformations to make the output truly idiomatic.

**Rules:**
- Where getters and setters are defined as methods in Java, use the Kotlin syntax to
  replace these methods with a more idiomatic version.
- Lambdas should be used where they can simplify code complexity while replicating the
  exact behaviour of the previous code.

## The 5 Invariants

In each stage of your chain of thought, the following invariants must hold.

**Invariant 1:** No new side-effects or behaviour.

**Invariant 2:** Preserve all annotations and targets exactly.
- Annotations must target the backing field in Kotlin where they targeted the field in
  Java. Use annotation site targets: `@field:`, `@get:`, `@set:`, `@param:`.

**Invariant 3:** Preserve the package declaration and all imports.
- Carry forwards every single import, adding no new imports. Only remove imports where
  they would shadow Kotlin names (e.g., `java.util.List` shadows Kotlin's `List`).

**Invariant 4:** Preserve all Javadoc comments.
- In step 1, convert any Javadoc comments to KDoc comments.
- In all other steps, carry forwards the KDoc comments, preserving information where
  structure changes.

**Invariant 5:** Ensure the output result is in Kotlin.
- The emitted code must be syntactically valid Kotlin.

**After each step**, go through each of these invariants, listing the ones that no
longer hold. If any exist, revert to the previous step and recalculate from there.

---

## Example 1: Utility Class with Nullability

### Java Input

```java
package com.acme.util;

import java.time.LocalDate;
import java.util.Objects;

/**
* Utility for printing a greeting that includes the current date.
*/
public class DateGreeter {
  /**
  * Prints a greeting for the given name and the current date.
  *
  * @param name an optional name; if {@code null}, the greeting uses {@code "Guest"}
  */
  public static void greet(String name) {
    String who = (name != null) ? name : "Guest";
    System.out.println("Hello, " + who + " - today is " + LocalDate.now());
  }
}
```

### Conversion Walkthrough

**Step 1** — Faithful translation. The DateGreeter class is implicitly open, the
`greet` method is static → companion object. Javadoc converted to KDoc.

```kotlin
package com.acme.util

import java.time.LocalDate
import java.util.Objects

/**
* Utility for printing a greeting that includes the current date.
*/
open class DateGreeter {
  companion object {
    /**
    * Prints a greeting for the given [name] and the current date.
    *
    * @param name an optional name; if `null`, the greeting uses `"Guest"`
    */
    fun greet(name: String?) {
      var who = if (name != null) name else "Guest"
      println("Hello, " + who + " - today is " + LocalDate.now())
    }
  }
}
```

Invariants check: All OK.

**Step 2** — The `String?` is correct since the author checks for null. The `who`
variable is only read, so change `var` → `val`.

```kotlin
// Same as above but with:
val who = if (name != null) name else "Guest"
```

Invariants check: All OK.

**Step 3** — No collections in this code. No changes.

Invariants check: All OK.

**Step 4** — The `greet` function is not tied to any state of DateGreeter, so move it
to a top-level function. Use string templates and Elvis operator.

```kotlin
package com.acme.util

import java.time.LocalDate
import java.util.Objects

/**
* Prints a greeting for the given [name] and the current date.
*
* @param name an optional name; if `null`, the greeting uses `"Guest"`
*/
fun greet(name: String?) {
  println("Hello, ${name ?: "Guest"} - today is ${LocalDate.now()}")
}
```

Invariants check: All OK.

---

## Example 2: Domain Model with Annotations

### Java Input

```java
package com.acme.model;

import com.fasterxml.jackson.annotation.JsonProperty;
import javax.annotation.Nullable;
import java.util.Objects;

/**
* Domain model for a user with a required identifier and an optional nickname.
* <p>
* The {@code id} is serialized as {@code "id"} and is required.
* The {@code nickname} may be absent.
*/
public class User {
  /**
  * Stable, non-null identifier serialized as {@code "id"}.
  */
  @JsonProperty("id")
  private final String id;

  /**
  * Optional nickname for display purposes.
  */
  @Nullable
  private String nickname;

  /**
  * Creates a user with the given non-null identifier.
  *
  * @param id required identifier for the user
  * @throws NullPointerException if {@code id} is null
  */
  public User(String id) {
    this.id = Objects.requireNonNull(id, "id");
  }

  /**
  * Returns the identifier serialized as {@code "id"}.
  *
  * @return the user id
  */
  @JsonProperty("id")
  public String getId() {
    return id;
  }

  /**
  * Returns the optional nickname.
  *
  * @return the nickname or {@code null} if absent
  */
  @Nullable
  public String getNickname() {
    return nickname;
  }

  /**
  * Sets the optional nickname.
  *
  * @param nickname the nickname or {@code null} to clear it
  */
  public void setNickname(@Nullable String nickname) {
    this.nickname = nickname;
  }
}
```

### Conversion Walkthrough

**Step 1** — Faithful translation. Class is implicitly open → `open class`.
`@JsonProperty("id")` on the field → `@field:JsonProperty("id")`.
`@JsonProperty("id")` on the getter → `@get:JsonProperty("id")` when converted to
property later. Keep explicit getters/setters at this step for faithfulness.

```kotlin
package com.acme.model

import com.fasterxml.jackson.annotation.JsonProperty
import javax.annotation.Nullable
import java.util.Objects

/**
* Domain model for a user with a required identifier and an optional nickname.
*
* The `id` is serialized as `"id"` and is required.
* The `nickname` may be absent.
*/
open class User {

  /**
  * Stable, non-null identifier serialized as `"id"`.
  */
  @field:JsonProperty("id")
  private val id: String

  /**
  * Optional nickname for display purposes.
  */
  @field:Nullable
  private var nickname: String? = null

  /**
  * Creates a user with the given non-null identifier.
  *
  * @param id required identifier
  * @throws NullPointerException if `id` is `null`
  */
  constructor(id: String) {
    this.id = Objects.requireNonNull(id, "id")
  }

  @get:JsonProperty("id")
  fun getId(): String { return id }

  @Nullable
  fun getNickname(): String? { return nickname }

  fun setNickname(@Nullable nickname: String?) { this.nickname = nickname }
}
```

Invariants check: All OK.

**Step 2** — `id` is non-null by design (`Objects.requireNonNull` enforces it).
`nickname` is nullable (`@Nullable`). No val/var changes needed beyond what's already
done. Code unchanged.

Invariants check: All OK.

**Step 3** — No collections. No changes.

Invariants check: All OK.

**Step 4** — Idiomatic Kotlin:
1. Primary constructor with `id` as a `val` property. Apply both `@field:JsonProperty`
   and `@get:JsonProperty` to match both Java annotation targets.
2. Convert `nickname` getter/setter → Kotlin property with `@field:Nullable` and
   `@get:Nullable`.
3. Drop `Objects.requireNonNull` — Kotlin's type system enforces non-null.
4. Preserve all imports even if now unused (invariant 3).

```kotlin
package com.acme.model

import com.fasterxml.jackson.annotation.JsonProperty
import javax.annotation.Nullable
import java.util.Objects

/**
* Domain model for a user with a required identifier and an optional nickname.
*
* The `id` is serialized as `"id"` and is required.
* The `nickname` may be absent.
*
* @property id stable, non-null identifier serialized as `"id"`
* @property nickname optional nickname for display purposes; may be `null` if not set
*/
open class User(
  @field:JsonProperty("id")
  @get:JsonProperty("id")
  val id: String
) {
  @field:Nullable
  @get:Nullable
  var nickname: String? = null
}
```

Invariants check: All OK.