Core Immutable Generation

/**
 * Marks an interface or abstract class for immutable implementation generation.
 * Generates a concrete immutable class with builder pattern, copy methods, 
 * equals/hashCode, and toString implementations.
 */
@Target(ElementType.TYPE)
@Retention(RetentionPolicy.SOURCE)
@interface Value.Immutable {
  /** Generate singleton object pattern instead of regular immutable */
  boolean singleton() default false;
  
  /** Strongly intern instances on construction for memory efficiency */
  boolean intern() default false;
  
  /** Enable/disable copy methods (withX methods) generation */
  boolean copy() default true;
  
  /** Precompute hashCode during construction for performance */
  boolean prehash() default false;
  
  /** Enable/disable builder pattern generation */
  boolean builder() default true;
  
  /** Force JDK-only class usage, avoiding Guava dependencies */
  boolean jdkOnly() default false;
  
  /** Control visibility of generated implementation class */
  ImplementationVisibility visibility() default ImplementationVisibility.SAME;
}

enum ImplementationVisibility {
  PUBLIC,    // Generated implementation is public
  SAME,      // Same visibility as abstract type  
  PACKAGE,   // Package-private implementation
  PRIVATE    // Private implementation (requires factory methods)
}

// Basic immutable generation
@Value.Immutable
public interface Person {
  String name();
  int age();
}

// Singleton pattern
@Value.Immutable(singleton = true)
public interface Config {
  String apiUrl();
  int timeout();
}

// High-performance settings
@Value.Immutable(intern = true, prehash = true)
public interface Coordinate {
  double x();
  double y();
}

// Private implementation with factory methods
@Value.Immutable(visibility = ImplementationVisibility.PRIVATE)
public interface User {
  String username();
  String email();
  
  static User of(String username, String email) {
    return ImmutableUser.of(username, email);
  }
}

/**
 * Include external classes for processing. Useful for processing types
 * that are not directly annotated but need immutable implementations.
 */
@Target(ElementType.TYPE)
@Retention(RetentionPolicy.SOURCE)
@interface Value.Immutable.Include {
  /** Classes to include for immutable processing */
  Class<?>[] value();
}

@Value.Immutable
@Value.Immutable.Include({ExternalType.class, AnotherType.class})
public interface MyType {
  String value();
}

/**
 * Generate nested immutable classes under umbrella class.
 * Useful for grouping related immutable types together.
 */
@Target(ElementType.TYPE)
@Retention(RetentionPolicy.SOURCE)
@interface Value.Nested {}

public class Models {
  @Value.Immutable
  @Value.Nested
  public interface Person {
    String name();
    int age();
  }
  
  @Value.Immutable
  @Value.Nested  
  public interface Address {
    String street();
    String city();
  }
}

// Usage
Models.ImmutablePerson person = Models.ImmutablePerson.builder()
    .name("Alice")
    .age(30)
    .build();

/**
 * Generate builders for static factory methods.
 * Applied to static methods to generate builder-style creation.
 */
@Target(ElementType.METHOD)
@Retention(RetentionPolicy.SOURCE)
@interface Value.Builder {}

public class PersonFactory {
  @Value.Builder
  public static Person createPerson(String name, int age, Optional<String> email) {
    return ImmutablePerson.of(name, age, email);
  }
}

// Generated builder usage
Person person = new PersonFactory.CreatePersonBuilder()
    .name("Alice")
    .age(30)
    .email("alice@example.com")
    .build();