/// Top-level configuration for generating Swift bindings from a GIR repository.
///
/// `GenerationConfig` is the Swift-native equivalent of a config file or TOML
/// approach used by other GIR-based generators. It specifies which `.gir` files
/// to read, where to emit output, which types to generate/manually implement/
/// ignore, and any per-type or per-function overrides.
///
/// ### Example
/// ```swift
/// GenerationConfig(
///     library: "Gtk",
///     version: "4.0",
///     girsDirectories: ["/usr/share/gir-1.0"],
///     targetDirectory: "Sources/Gtk",
///     externalLibraries: ["GLib", "GObject"],
///     generate: ["Gtk.Widget", "Gtk.Window"],
///     manual: ["Gtk.CustomWidget"],
///     ignore: ["Gtk.DeprecatedType"],
///     objects: []
/// )
/// ```
public struct GenerationConfig {
    /// The name of the library being wrapped (e.g. `"Gtk"`, `"GLib"`).
    public var library: String

    /// The version string of the GIR namespace (e.g. `"4.0"`).
    public var version: String

    /// Directories to search for `.gir` files.
    public var girsDirectories: [String]

    /// Directory where generated Swift source files should be written.
    public var targetDirectory: String

    /// Names of external libraries whose types may be referenced (e.g. `"GLib"`, `"GObject"`).
    public var externalLibraries: [String]

    /// Fully-qualified type names for which Swift bindings should be generated.
    public var generate: [String]

    /// Fully-qualified type names that are implemented manually and should not be generated.
    public var manual: [String]

    /// Fully-qualified type names that should be skipped entirely.
    public var ignore: [String]

    /// Per-type and per-function override entries.
    public var objects: [ObjectConfig]

    /// Creates a complete generation configuration.
    ///
    /// - Parameters:
    ///   - library: The library name (e.g. `"Gtk"`).
    ///   - version: The GIR namespace version (e.g. `"4.0"`).
    ///   - girsDirectories: Paths to search for `.gir` files.
    ///   - targetDirectory: Output directory for generated Swift sources.
    ///   - externalLibraries: Referenced external library names.
    ///   - generate: Types to generate bindings for.
    ///   - manual: Types handled by hand-written code.
    ///   - ignore: Types to skip.
    ///   - objects: Override entries for types, functions, signals, and properties.
    public init(library: String, version: String, girsDirectories: [String],
                targetDirectory: String, externalLibraries: [String],
                generate: [String], manual: [String], ignore: [String],
                objects: [ObjectConfig]) {
        self.library = library
        self.version = version
        self.girsDirectories = girsDirectories
        self.targetDirectory = targetDirectory
        self.externalLibraries = externalLibraries
        self.generate = generate
        self.manual = manual
        self.ignore = ignore
        self.objects = objects
    }
}

/// A configuration entry targeting a specific type, function, function pattern,
/// signal, or property in the GIR repository.
///
/// Each case carries the overrides or rename rules that should be applied
/// during code generation for the matched element.
public enum ObjectConfig {
    /// Overrides for a specific GObject type identified by its fully-qualified name.
    case object(_ name: String, overrides: ObjectOverrides)

    /// Overrides for a specific function on a type.
    case function(_ type: String, _ name: String, overrides: FunctionOverrides)

    /// A regex-based rename rule applied to matching functions on a type.
    case functionPattern(_ type: String, pattern: String, rename: RenameRule)

    /// Overrides for a specific signal on a type.
    case signal(_ type: String, _ name: String, overrides: SignalOverrides)

    /// Overrides for a specific property on a type.
    case property(_ type: String, _ name: String, overrides: PropertyOverrides)
}

/// Overrides that control how a single GObject type is treated during code generation.
///
/// All properties are optional; only the values that are explicitly set will
/// override the default generation behavior for the matched type.
public struct ObjectOverrides {
    /// Whether to generate, mark as manual, or ignore this type.
    public var status: ObjectStatus?

    /// If `true`, mark the generated class as `final`.
    public var finalType: Bool?

    /// The concurrency model to apply (e.g. `@MainActor`, `Sendable`).
    public var concurrency: ConcurrencyModel?

    /// Minimum version string; the type is only generated when targeting this version or later.
    public var version: String?

    /// An optional `#if` compilation condition to guard the generated code.
    public var cfgCondition: String?

    /// If `true`, generate a builder pattern struct for constructing this type.
    public var generateBuilder: Bool?
}

/// Controls how a generated type should be treated.
public enum ObjectStatus: String {
    /// Generate Swift bindings for this type.
    case generate
    /// This type will be implemented manually; do not generate.
    case manual
    /// Skip this type entirely.
    case ignore
}

/// The concurrency model to apply to a generated type.
public enum ConcurrencyModel: String {
    /// Annotate the generated type with `@MainActor`.
    case mainActor
    /// Mark the generated type as `Sendable`.
    case sendable
    /// No special concurrency annotation.
    case none
}

/// Overrides that control how a single function is treated during code generation.
///
/// All properties are optional; only the values that are explicitly set will
/// override the default generation behavior for the matched function.
public struct FunctionOverrides {
    /// If `true`, skip generating this function entirely.
    public var ignore: Bool?

    /// A rename rule to apply to this function's Swift name.
    public var rename: RenameRule?

    /// Minimum version string; only generate when targeting this version or later.
    public var version: String?

    /// An optional `#if` compilation condition to guard the generated code.
    public var cfgCondition: String?

    /// If `true`, treat this function as a constructor (returns a new instance).
    public var constructor: Bool?

    /// Override the visibility of the generated method.
    public var visibility: Visibility?

    /// Per-parameter overrides keyed by the parameter's original name.
    public var parameters: [String: ParameterOverride]?
}

/// The visibility level for a generated symbol.
public enum Visibility: String {
    /// Visible outside the module.
    case `public`
    /// Visible only within the same module.
    case `internal`
    /// Visible to all modules in the same package.
    case `package`
}

/// Overrides for a single function parameter in the generated API.
public struct ParameterOverride {
    /// If set, overrides whether the parameter is treated as nullable.
    public var nullable: Bool?

    /// If set, renames this parameter in the generated Swift function signature.
    public var newName: String?
}

/// Overrides that control how a GObject signal handler is generated.
///
/// All properties are optional; only the explicitly set values override
/// the default behavior for the matched signal.
public struct SignalOverrides {
    /// If `true`, skip generating a handler API for this signal.
    public var ignore: Bool?

    /// If `true`, the signal can be inhibited (stopped from propagating).
    public var inhibit: Bool?

    /// Per-parameter overrides for the signal handler's closure parameters.
    public var parameters: [String: ParameterOverride]?
}

/// Overrides that control how a GObject property is exposed in the generated API.
public struct PropertyOverrides {
    /// The accessor methods to generate for this property.
    ///
    /// If `nil`, the default set of accessors is generated based on the GIR
    /// metadata. Provide an explicit array to override which accessors are emitted.
    public var generate: [PropertyAccessor]?
}

/// The kind of accessor to generate for a GObject property.
public enum PropertyAccessor: String {
    /// Generate a getter method for the property.
    case get
    /// Generate a setter method for the property.
    case set
    /// Generate a notification callback/handler for property changes.
    case notify
}

/// A regex-based rename rule for transforming GIR symbol names into Swift names.
///
/// Matches the `regex` pattern against the original name and substitutes the
/// `replacement` string, following standard regex capture-group semantics
/// (e.g., `"$1"`, `"$2"`).
///
/// ### Example
/// ```swift
/// RenameRule(regex: "^gtk_", replacement: "")
/// ```
public struct RenameRule {
    /// The regular expression pattern to match against the original name.
    public var regex: String

    /// The replacement string, which may reference capture groups with `$1`, `$2`, etc.
    public var replacement: String

    /// Creates a rename rule with the given regex pattern and replacement.
    ///
    /// - Parameters:
    ///   - regex: A regular expression pattern.
    ///   - replacement: A replacement string (may include capture-group references).
    public init(regex: String, replacement: String) {
        self.regex = regex
        self.replacement = replacement
    }
}