codoc 0.1.0

//! Schema types for the Codoc unified documentation format.
//!
//! These types match the JSON schema defined in `schema.json`.

use serde::{Deserialize, Serialize};
use std::collections::HashMap;

/// Root document structure for Codoc output.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct Document {
    /// Schema version identifier.
    pub schema: String,

    /// Project metadata.
    pub metadata: Metadata,

    /// Top-level documented entities.
    pub entities: Vec<Entity>,

    /// Flat symbol table for quick lookups and linking.
    pub symbols: Vec<SymbolEntry>,

    /// Symbols referenced but not found in entities or external mappings.
    #[serde(
        rename = "unresolvedReferences",
        skip_serializing_if = "Vec::is_empty",
        default
    )]
    pub unresolved_references: Vec<UnresolvedReference>,
}

impl Document {
    /// Creates a new document with the current schema version.
    pub fn new(metadata: Metadata) -> Self {
        Self {
            schema: crate::SCHEMA_VERSION.to_string(),
            metadata,
            entities: Vec::new(),
            symbols: Vec::new(),
            unresolved_references: Vec::new(),
        }
    }
}

/// Project metadata.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct Metadata {
    /// Project/package name.
    pub name: String,

    /// Project version.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub version: Option<String>,

    /// Source language.
    pub language: Language,

    /// Generation timestamp.
    #[serde(rename = "generatedAt")]
    pub generated_at: String,

    /// Root directory for source files.
    #[serde(rename = "sourceRoot", skip_serializing_if = "Option::is_none")]
    pub source_root: Option<String>,

    /// Prefix for all entity IDs.
    #[serde(rename = "idPrefix", skip_serializing_if = "Option::is_none")]
    pub id_prefix: Option<String>,

    /// List of parsed files.
    #[serde(skip_serializing_if = "Vec::is_empty", default)]
    pub files: Vec<String>,

    /// External symbol link mappings by package/gem name.
    #[serde(
        rename = "externalLinks",
        skip_serializing_if = "HashMap::is_empty",
        default
    )]
    pub external_links: HashMap<String, ExternalLinkMapping>,
}

/// Source language.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "lowercase")]
pub enum Language {
    /// Ruby language.
    Ruby,
    /// TypeScript language.
    TypeScript,
}

/// Configuration for linking to external documentation.
#[derive(Debug, Clone, Serialize, Deserialize, Default)]
pub struct ExternalLinkMapping {
    /// Base URL for documentation.
    #[serde(rename = "baseUrl", skip_serializing_if = "Option::is_none")]
    pub base_url: Option<String>,

    /// URL template with placeholders.
    #[serde(rename = "urlTemplate", skip_serializing_if = "Option::is_none")]
    pub url_template: Option<String>,

    /// Explicit URL overrides for specific symbols.
    #[serde(skip_serializing_if = "HashMap::is_empty", default)]
    pub symbols: HashMap<String, String>,

    /// Transform rules for symbol names.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub transform: Option<TransformRules>,
}

/// Transform rules for symbol names in URLs.
#[derive(Debug, Clone, Serialize, Deserialize, Default)]
pub struct TransformRules {
    /// How to transform `::` or `.` in qualified names.
    #[serde(rename = "nameSeparator", skip_serializing_if = "Option::is_none")]
    pub name_separator: Option<String>,

    /// Prefix for instance method anchors.
    #[serde(rename = "methodPrefix", skip_serializing_if = "Option::is_none")]
    pub method_prefix: Option<String>,

    /// Prefix for class method anchors.
    #[serde(rename = "classMethodPrefix", skip_serializing_if = "Option::is_none")]
    pub class_method_prefix: Option<String>,

    /// Whether to lowercase the symbol name in URLs.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub lowercase: Option<bool>,
}

/// Entry in the symbol table for linking.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct SymbolEntry {
    /// Unique identifier.
    pub id: String,

    /// Short name.
    pub name: String,

    /// Fully qualified name.
    #[serde(rename = "qualifiedName")]
    pub qualified_name: String,

    /// Entity kind.
    pub kind: String,

    /// Parent entity ID.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub parent: Option<String>,

    /// Source file path.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub file: Option<String>,

    /// Line number.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub line: Option<u32>,

    /// Short signature for methods.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub signature: Option<String>,
}

/// Unresolved reference.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct UnresolvedReference {
    /// Unresolved type/symbol name.
    pub name: String,

    /// Attempted qualified name.
    #[serde(rename = "qualifiedName", skip_serializing_if = "Option::is_none")]
    pub qualified_name: Option<String>,

    /// Package hint if available.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub package: Option<String>,

    /// Entity IDs that reference this unresolved symbol.
    #[serde(rename = "referencedFrom")]
    pub referenced_from: Vec<String>,
}

/// A documented entity.
#[derive(Debug, Clone, Serialize, Deserialize)]
#[serde(tag = "kind")]
pub enum Entity {
    /// A module (Ruby module or TypeScript namespace).
    #[serde(rename = "module")]
    Module(Module),

    /// A class.
    #[serde(rename = "class")]
    Class(Class),

    /// An interface (TypeScript).
    #[serde(rename = "interface")]
    Interface(Interface),

    /// A type alias (TypeScript).
    #[serde(rename = "type")]
    TypeAlias(TypeAlias),

    /// An enum (TypeScript).
    #[serde(rename = "enum")]
    Enum(Enum),

    /// A method.
    #[serde(rename = "method")]
    Method(Callable),

    /// A standalone function.
    #[serde(rename = "function")]
    Function(Callable),

    /// A constructor.
    #[serde(rename = "constructor")]
    Constructor(Callable),

    /// A property.
    #[serde(rename = "property")]
    Property(Property),

    /// A constant.
    #[serde(rename = "constant")]
    Constant(Constant),
}

impl Entity {
    /// Returns the entity's ID.
    pub fn id(&self) -> &str {
        match self {
            Entity::Module(m) => &m.base.id,
            Entity::Class(c) => &c.base.id,
            Entity::Interface(i) => &i.base.id,
            Entity::TypeAlias(t) => &t.base.id,
            Entity::Enum(e) => &e.base.id,
            Entity::Method(c) | Entity::Function(c) | Entity::Constructor(c) => &c.base.id,
            Entity::Property(p) => &p.base.id,
            Entity::Constant(c) => &c.base.id,
        }
    }

    /// Returns the entity's name.
    pub fn name(&self) -> &str {
        match self {
            Entity::Module(m) => &m.base.name,
            Entity::Class(c) => &c.base.name,
            Entity::Interface(i) => &i.base.name,
            Entity::TypeAlias(t) => &t.base.name,
            Entity::Enum(e) => &e.base.name,
            Entity::Method(c) | Entity::Function(c) | Entity::Constructor(c) => &c.base.name,
            Entity::Property(p) => &p.base.name,
            Entity::Constant(c) => &c.base.name,
        }
    }
}

/// Base properties shared by all documented entities.
#[derive(Debug, Clone, Serialize, Deserialize, Default)]
pub struct BaseEntity {
    /// Unique identifier for cross-referencing.
    pub id: String,

    /// Entity name.
    pub name: String,

    /// Source location.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub location: Option<SourceLocation>,

    /// Documentation.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub docs: Option<Documentation>,

    /// Visibility/access level.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub visibility: Option<Visibility>,

    /// Marked with @private tag.
    #[serde(rename = "isPrivateApi", skip_serializing_if = "Option::is_none")]
    pub is_private_api: Option<bool>,
}

/// Location in source code.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct SourceLocation {
    /// Relative file path.
    pub file: String,

    /// Line number (1-indexed).
    pub line: u32,

    /// Column number (0-indexed).
    #[serde(skip_serializing_if = "Option::is_none")]
    pub column: Option<u32>,
}

/// Visibility/access level.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "lowercase")]
pub enum Visibility {
    /// Public access.
    Public,
    /// Protected access (subclasses only).
    Protected,
    /// Private access.
    Private,
    /// Internal access (package/module only).
    Internal,
}

/// Documentation fields.
#[derive(Debug, Clone, Serialize, Deserialize, Default)]
pub struct Documentation {
    /// Brief one-line summary.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub summary: Option<String>,

    /// Full description (may contain markdown).
    #[serde(skip_serializing_if = "Option::is_none")]
    pub description: Option<String>,

    /// Code examples.
    #[serde(skip_serializing_if = "Vec::is_empty", default)]
    pub examples: Vec<Example>,

    /// Cross-references.
    #[serde(skip_serializing_if = "Vec::is_empty", default)]
    pub see: Vec<SeeReference>,

    /// Important notes.
    #[serde(skip_serializing_if = "Vec::is_empty", default)]
    pub notes: Vec<String>,

    /// TODO items.
    #[serde(skip_serializing_if = "Vec::is_empty", default)]
    pub todos: Vec<String>,

    /// Deprecation notice.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub deprecated: Option<Deprecation>,

    /// Version when introduced.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub since: Option<String>,

    /// Custom tags.
    #[serde(skip_serializing_if = "HashMap::is_empty", default)]
    pub tags: HashMap<String, String>,
}

/// A code example.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct Example {
    /// Optional title.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub title: Option<String>,

    /// The example code.
    pub code: String,

    /// Language hint.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub language: Option<String>,
}

/// Cross-reference to related documentation.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct SeeReference {
    /// Display text.
    pub text: String,

    /// Reference ID or URL.
    #[serde(rename = "ref", skip_serializing_if = "Option::is_none")]
    pub reference: Option<String>,
}

/// Deprecation notice.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct Deprecation {
    /// Deprecation message.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub message: Option<String>,

    /// Version when deprecated.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub since: Option<String>,

    /// Suggested replacement.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub replacement: Option<String>,
}

/// Reference to a type.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct TypeReference {
    /// Type name.
    pub name: String,

    /// Kind of type reference.
    pub kind: TypeKind,

    /// Generic type arguments.
    #[serde(skip_serializing_if = "Vec::is_empty", default)]
    pub args: Vec<TypeReference>,

    /// Union/intersection/tuple members.
    #[serde(skip_serializing_if = "Vec::is_empty", default)]
    pub members: Vec<TypeReference>,

    /// Literal value for literal types.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub value: Option<serde_json::Value>,

    /// Whether this type can be null/nil.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub nullable: Option<bool>,

    /// Reference ID to a documented entity.
    #[serde(rename = "ref", skip_serializing_if = "Option::is_none")]
    pub reference: Option<String>,

    /// External package/gem name.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub package: Option<String>,

    /// Fully qualified name for external symbol resolution.
    #[serde(rename = "qualifiedName", skip_serializing_if = "Option::is_none")]
    pub qualified_name: Option<String>,
}

impl TypeReference {
    /// Creates a simple type reference.
    pub fn simple(name: impl Into<String>) -> Self {
        Self {
            name: name.into(),
            kind: TypeKind::Simple,
            args: Vec::new(),
            members: Vec::new(),
            value: None,
            nullable: None,
            reference: None,
            package: None,
            qualified_name: None,
        }
    }

    /// Creates a void type reference.
    pub fn void() -> Self {
        Self::simple("void")
    }

    /// Creates a union type reference.
    pub fn union(members: Vec<TypeReference>) -> Self {
        Self {
            name: String::new(),
            kind: TypeKind::Union,
            args: Vec::new(),
            members,
            value: None,
            nullable: None,
            reference: None,
            package: None,
            qualified_name: None,
        }
    }

    /// Creates a generic type reference.
    pub fn generic(name: impl Into<String>, args: Vec<TypeReference>) -> Self {
        Self {
            name: name.into(),
            kind: TypeKind::Generic,
            args,
            members: Vec::new(),
            value: None,
            nullable: None,
            reference: None,
            package: None,
            qualified_name: None,
        }
    }

    /// Makes this type nullable.
    pub fn nullable(mut self) -> Self {
        self.nullable = Some(true);
        self
    }

    /// Adds a reference to an internal entity.
    pub fn with_ref(mut self, reference: impl Into<String>) -> Self {
        self.reference = Some(reference.into());
        self
    }

    /// Adds an external package reference.
    pub fn external(
        mut self,
        package: impl Into<String>,
        qualified_name: impl Into<String>,
    ) -> Self {
        self.package = Some(package.into());
        self.qualified_name = Some(qualified_name.into());
        self
    }
}

/// Kind of type reference.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "lowercase")]
pub enum TypeKind {
    /// Simple type (e.g., `String`, `number`).
    Simple,
    /// Generic type (e.g., `Array<T>`).
    Generic,
    /// Union type (e.g., `string | number`).
    Union,
    /// Intersection type (e.g., `A & B`).
    Intersection,
    /// Array type.
    Array,
    /// Tuple type.
    Tuple,
    /// Literal type (e.g., `"hello"`, `42`).
    Literal,
    /// Function type.
    Function,
    /// Unknown type.
    Unknown,
}

/// A function/method parameter.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct Parameter {
    /// Parameter name.
    pub name: String,

    /// Parameter type.
    #[serde(rename = "type", skip_serializing_if = "Option::is_none")]
    pub param_type: Option<TypeReference>,

    /// Description.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub description: Option<String>,

    /// Default value.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub default: Option<String>,

    /// Whether optional.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub optional: Option<bool>,

    /// Whether this is a rest/splat parameter.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub rest: Option<bool>,

    /// Hash/object options.
    #[serde(skip_serializing_if = "Vec::is_empty", default)]
    pub options: Vec<OptionEntry>,
}

/// An entry in a Hash/object options parameter.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct OptionEntry {
    /// Option key name.
    pub name: String,

    /// Option type.
    #[serde(rename = "type", skip_serializing_if = "Option::is_none")]
    pub option_type: Option<TypeReference>,

    /// Description.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub description: Option<String>,

    /// Whether required.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub required: Option<bool>,

    /// Default value.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub default: Option<String>,
}

/// An exception/error that can be thrown.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct Throws {
    /// Exception type.
    #[serde(rename = "type", skip_serializing_if = "Option::is_none")]
    pub throw_type: Option<TypeReference>,

    /// Description.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub description: Option<String>,
}

/// Block/callback parameter documentation.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct YieldBlock {
    /// Description.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub description: Option<String>,

    /// Block parameters.
    #[serde(skip_serializing_if = "Vec::is_empty", default)]
    pub params: Vec<Parameter>,

    /// Return type.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub returns: Option<TypeReference>,
}

/// Generic type parameter.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct TypeParameter {
    /// Parameter name.
    pub name: String,

    /// Constraint.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub constraint: Option<TypeReference>,

    /// Default type.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub default: Option<TypeReference>,

    /// Description.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub description: Option<String>,
}

// =============================================================================
// Entity Types
// =============================================================================

/// A module/namespace.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct Module {
    #[serde(flatten)]
    /// Base entity information.
    pub base: BaseEntity,

    /// Extended modules (Ruby).
    #[serde(skip_serializing_if = "Vec::is_empty", default)]
    pub extends: Vec<TypeReference>,

    /// Included modules (Ruby).
    #[serde(skip_serializing_if = "Vec::is_empty", default)]
    pub includes: Vec<TypeReference>,

    /// Functions.
    #[serde(skip_serializing_if = "Vec::is_empty", default)]
    pub functions: Vec<Callable>,

    /// Properties.
    #[serde(skip_serializing_if = "Vec::is_empty", default)]
    pub properties: Vec<Property>,

    /// Constants.
    #[serde(skip_serializing_if = "Vec::is_empty", default)]
    pub constants: Vec<Constant>,

    /// Nested classes.
    #[serde(skip_serializing_if = "Vec::is_empty", default)]
    pub classes: Vec<Class>,

    /// Nested modules.
    #[serde(skip_serializing_if = "Vec::is_empty", default)]
    pub modules: Vec<Module>,

    /// Interfaces (TypeScript).
    #[serde(skip_serializing_if = "Vec::is_empty", default)]
    pub interfaces: Vec<Interface>,

    /// Type aliases (TypeScript).
    #[serde(skip_serializing_if = "Vec::is_empty", default)]
    pub types: Vec<TypeAlias>,

    /// Enums.
    #[serde(skip_serializing_if = "Vec::is_empty", default)]
    pub enums: Vec<Enum>,

    /// Whether this is an ActiveSupport::Concern (Ruby).
    #[serde(rename = "isConcern", skip_serializing_if = "Option::is_none")]
    pub is_concern: Option<bool>,

    /// Instance methods (Ruby modules).
    #[serde(
        rename = "instanceMethods",
        skip_serializing_if = "Vec::is_empty",
        default
    )]
    pub instance_methods: Vec<Callable>,

    /// Class methods from ClassMethods module (Ruby concerns).
    #[serde(
        rename = "classMethods",
        skip_serializing_if = "Vec::is_empty",
        default
    )]
    pub class_methods: Vec<Callable>,
}

/// A class.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct Class {
    #[serde(flatten)]
    /// Base entity information.
    pub base: BaseEntity,

    /// Parent class.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub extends: Option<TypeReference>,

    /// Implemented interfaces (TypeScript).
    #[serde(skip_serializing_if = "Vec::is_empty", default)]
    pub implements: Vec<TypeReference>,

    /// Included modules (Ruby).
    #[serde(skip_serializing_if = "Vec::is_empty", default)]
    pub includes: Vec<TypeReference>,

    /// Prepended modules (Ruby).
    #[serde(skip_serializing_if = "Vec::is_empty", default)]
    pub prepends: Vec<TypeReference>,

    /// Type parameters (TypeScript).
    #[serde(rename = "typeParams", skip_serializing_if = "Vec::is_empty", default)]
    pub type_params: Vec<TypeParameter>,

    /// Whether abstract.
    #[serde(rename = "abstract", skip_serializing_if = "Option::is_none")]
    pub is_abstract: Option<bool>,

    /// Constructor.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub constructor: Option<Box<Callable>>,

    /// Instance properties.
    #[serde(skip_serializing_if = "Vec::is_empty", default)]
    pub properties: Vec<Property>,

    /// Instance methods.
    #[serde(skip_serializing_if = "Vec::is_empty", default)]
    pub methods: Vec<Callable>,

    /// Static properties.
    #[serde(
        rename = "staticProperties",
        skip_serializing_if = "Vec::is_empty",
        default
    )]
    pub static_properties: Vec<Property>,

    /// Static methods.
    #[serde(
        rename = "staticMethods",
        skip_serializing_if = "Vec::is_empty",
        default
    )]
    pub static_methods: Vec<Callable>,

    /// Constants.
    #[serde(skip_serializing_if = "Vec::is_empty", default)]
    pub constants: Vec<Constant>,

    /// Nested entities.
    #[serde(skip_serializing_if = "Vec::is_empty", default)]
    pub nested: Vec<Entity>,
}

/// An interface (TypeScript).
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct Interface {
    #[serde(flatten)]
    /// Base entity information.
    pub base: BaseEntity,

    /// Extended interfaces.
    #[serde(skip_serializing_if = "Vec::is_empty", default)]
    pub extends: Vec<TypeReference>,

    /// Type parameters.
    #[serde(rename = "typeParams", skip_serializing_if = "Vec::is_empty", default)]
    pub type_params: Vec<TypeParameter>,

    /// Properties.
    #[serde(skip_serializing_if = "Vec::is_empty", default)]
    pub properties: Vec<Property>,

    /// Methods.
    #[serde(skip_serializing_if = "Vec::is_empty", default)]
    pub methods: Vec<Callable>,

    /// Call signatures.
    #[serde(
        rename = "callSignatures",
        skip_serializing_if = "Vec::is_empty",
        default
    )]
    pub call_signatures: Vec<Callable>,

    /// Index signatures.
    #[serde(
        rename = "indexSignatures",
        skip_serializing_if = "Vec::is_empty",
        default
    )]
    pub index_signatures: Vec<IndexSignature>,
}

/// Index signature.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct IndexSignature {
    /// Key type.
    #[serde(rename = "keyType", skip_serializing_if = "Option::is_none")]
    pub key_type: Option<TypeReference>,

    /// Value type.
    #[serde(rename = "valueType", skip_serializing_if = "Option::is_none")]
    pub value_type: Option<TypeReference>,

    /// Whether readonly.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub readonly: Option<bool>,
}

/// A type alias (TypeScript).
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct TypeAlias {
    #[serde(flatten)]
    /// Base entity information.
    pub base: BaseEntity,

    /// The aliased type.
    #[serde(rename = "type", skip_serializing_if = "Option::is_none")]
    pub aliased_type: Option<TypeReference>,

    /// Type parameters.
    #[serde(rename = "typeParams", skip_serializing_if = "Vec::is_empty", default)]
    pub type_params: Vec<TypeParameter>,
}

/// An enum.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct Enum {
    #[serde(flatten)]
    /// Base entity information.
    pub base: BaseEntity,

    /// Enum members.
    #[serde(skip_serializing_if = "Vec::is_empty", default)]
    pub members: Vec<EnumMember>,
}

/// An enum member.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct EnumMember {
    /// Member name.
    pub name: String,

    /// Member value.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub value: Option<serde_json::Value>,

    /// Documentation.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub docs: Option<Documentation>,
}

/// A callable (method, function, or constructor).
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct Callable {
    #[serde(flatten)]
    /// Base entity information.
    pub base: BaseEntity,

    /// Parameters.
    #[serde(skip_serializing_if = "Vec::is_empty", default)]
    pub params: Vec<Parameter>,

    /// Return type.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub returns: Option<TypeReference>,

    /// Return description.
    #[serde(rename = "returnsDescription", skip_serializing_if = "Option::is_none")]
    pub returns_description: Option<String>,

    /// Exceptions that can be thrown.
    #[serde(skip_serializing_if = "Vec::is_empty", default)]
    pub throws: Vec<Throws>,

    /// Yield block.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub yields: Option<YieldBlock>,

    /// Whether async.
    #[serde(rename = "async", skip_serializing_if = "Option::is_none")]
    pub is_async: Option<bool>,

    /// Whether static.
    #[serde(rename = "static", skip_serializing_if = "Option::is_none")]
    pub is_static: Option<bool>,

    /// Whether abstract.
    #[serde(rename = "abstract", skip_serializing_if = "Option::is_none")]
    pub is_abstract: Option<bool>,

    /// Whether generator.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub generator: Option<bool>,

    /// Type parameters.
    #[serde(rename = "typeParams", skip_serializing_if = "Vec::is_empty", default)]
    pub type_params: Vec<TypeParameter>,

    /// Method overloads (TypeScript).
    #[serde(skip_serializing_if = "Vec::is_empty", default)]
    pub overloads: Vec<Callable>,
}

/// A property.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct Property {
    #[serde(flatten)]
    /// Base entity information.
    pub base: BaseEntity,

    /// Property type.
    #[serde(rename = "type", skip_serializing_if = "Option::is_none")]
    pub prop_type: Option<TypeReference>,

    /// Default value.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub default: Option<String>,

    /// Whether readonly.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub readonly: Option<bool>,

    /// Whether static.
    #[serde(rename = "static", skip_serializing_if = "Option::is_none")]
    pub is_static: Option<bool>,

    /// Whether optional.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub optional: Option<bool>,

    /// Whether this property has a getter accessor.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub getter: Option<bool>,

    /// Whether this property has a setter accessor.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub setter: Option<bool>,
}

/// A constant.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct Constant {
    #[serde(flatten)]
    /// Base entity information.
    pub base: BaseEntity,

    /// Constant type.
    #[serde(rename = "type", skip_serializing_if = "Option::is_none")]
    pub const_type: Option<TypeReference>,

    /// String representation of the value.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub value: Option<String>,
}