"""UKO Layer 3: Rust-specific vocabulary (``uko-rs:``).

Extends Layer 2 Object-Oriented (``uko-oo:``) paradigm with
Rust-specific semantic refinements:

Classes:
- ``RustStruct``          -- Rust struct (extends ``uko-oo:Class``)
- ``RustTrait``           -- Rust trait (extends ``uko-oo:Interface``)
- ``RustImpl``            -- Rust impl block
- ``RustFunction``        -- Rust function/method
- ``RustDeriveAttribute`` -- ``#[derive(...)]`` macro attribute

Rust extends at the SIGNATURES level with:
- Visibility modifiers (``pub``, ``pub(crate)``)
- Lifetime parameters
- Trait bounds
- ``unsafe`` markers
- ``#[derive]`` macros
- ``#[must_use]`` annotations

Based on ``docs/specification.md`` ~lines 44405-44420.
"""

from __future__ import annotations

from cleveragents.acms.uko.vocabulary import (
    OO_EFFECTIVE_LEVELS,
    UKO_CODE_IRI,
    UKO_FUNC_IRI,
    UKO_OO_IRI,
    Layer2Dependency,
    UKOClass,
    UKOProperty,
    UKOVocabulary,
    build_detail_level_map,
)

__all__: list[str] = [
    "RUST_DETAIL_LEVELS",
    "RUST_VOCABULARY",
    "RustDeriveAttribute",
    "RustFunction",
    "RustImpl",
    "RustStruct",
    "RustTrait",
]

# ---------------------------------------------------------------------------
# Namespace constants
# ---------------------------------------------------------------------------

UKO_RS_IRI = "https://cleveragents.ai/ontology/uko/rs#"
UKO_RS_PREFIX = "uko-rs:"


# ---------------------------------------------------------------------------
# OWL Class definitions
# ---------------------------------------------------------------------------

RustStruct = UKOClass(
    uri=f"{UKO_RS_IRI}RustStruct",
    label="RustStruct",
    comment=(
        "A Rust struct definition — extends uko-oo:Class. "
        "Includes derive macros, visibility, and lifetime parameters."
    ),
    subclass_of=(f"{UKO_OO_IRI}Class",),
)

RustTrait = UKOClass(
    uri=f"{UKO_RS_IRI}RustTrait",
    label="RustTrait",
    comment=(
        "A Rust trait definition — extends uko-oo:Interface. "
        "Includes associated types, default implementations, and supertraits."
    ),
    subclass_of=(f"{UKO_OO_IRI}Interface",),
)

# NOTE: subclasses uko-code:TypeDefinition as a pragmatic approximation.
# Impl blocks add methods to existing types, not define new types.
# Pending uko-code:CodeBlock base class (see #576 review).
RustImpl = UKOClass(
    uri=f"{UKO_RS_IRI}RustImpl",
    label="RustImpl",
    comment=(
        "A Rust impl block — either inherent or trait implementation. "
        "Extends uko-code:TypeDefinition."
    ),
    subclass_of=(f"{UKO_CODE_IRI}TypeDefinition",),
)

RustFunction = UKOClass(
    uri=f"{UKO_RS_IRI}RustFunction",
    label="RustFunction",
    comment=(
        "A Rust function or method — extends uko-oo:Method. "
        "Includes lifetime parameters, trait bounds, and unsafe markers."
    ),
    subclass_of=(f"{UKO_OO_IRI}Method",),
)

# NOTE: subclasses uko-code:TypeDefinition as a pragmatic approximation.
# Derive attributes are macro metadata, not type definitions.
# Pending uko-code:Annotation base class (see #576 review).
RustDeriveAttribute = UKOClass(
    uri=f"{UKO_RS_IRI}RustDeriveAttribute",
    label="RustDeriveAttribute",
    comment=(
        "A #[derive(...)] macro attribute applied to a struct/enum. "
        "Records which traits are automatically derived."
    ),
    subclass_of=(f"{UKO_CODE_IRI}TypeDefinition",),
)


# ---------------------------------------------------------------------------
# OWL Property definitions
# ---------------------------------------------------------------------------

_rs_visibility = UKOProperty(
    uri=f"{UKO_RS_IRI}visibility",
    label="visibility",
    comment=(
        "Visibility modifier: 'pub', 'pub(crate)', 'pub(super)', 'private' (default)."
    ),
    domain=(
        f"{UKO_RS_IRI}RustStruct",
        f"{UKO_RS_IRI}RustTrait",
        f"{UKO_RS_IRI}RustFunction",
    ),
    range_uri="xsd:string",
    is_object_property=False,
)

_rs_lifetime_params = UKOProperty(
    uri=f"{UKO_RS_IRI}lifetimeParameters",
    label="lifetimeParameters",
    comment="Lifetime parameter string (e.g. \"<'a, 'b>\").",
    domain=(
        f"{UKO_RS_IRI}RustStruct",
        f"{UKO_RS_IRI}RustImpl",
        f"{UKO_RS_IRI}RustFunction",
        f"{UKO_RS_IRI}RustTrait",
    ),
    range_uri="xsd:string",
    is_object_property=False,
)

_rs_trait_bounds = UKOProperty(
    uri=f"{UKO_RS_IRI}traitBounds",
    label="traitBounds",
    comment=("Trait bound constraints (e.g. 'T: Clone + Send')."),
    domain=(
        f"{UKO_RS_IRI}RustStruct",
        f"{UKO_RS_IRI}RustFunction",
        f"{UKO_RS_IRI}RustImpl",
    ),
    range_uri="xsd:string",
    is_object_property=False,
)

_rs_is_unsafe = UKOProperty(
    uri=f"{UKO_RS_IRI}isUnsafe",
    label="isUnsafe",
    comment="Whether this item is marked as 'unsafe'.",
    domain=(
        f"{UKO_RS_IRI}RustFunction",
        f"{UKO_RS_IRI}RustImpl",
        f"{UKO_RS_IRI}RustTrait",
    ),
    range_uri="xsd:boolean",
    is_object_property=False,
)

_rs_derive_traits = UKOProperty(
    uri=f"{UKO_RS_IRI}deriveTraits",
    label="deriveTraits",
    comment=(
        "Comma-separated list of traits in #[derive(...)]. "
        "E.g. 'Clone, Debug, Serialize'."
    ),
    domain=(f"{UKO_RS_IRI}RustDeriveAttribute",),
    range_uri="xsd:string",
    is_object_property=False,
)

_rs_must_use = UKOProperty(
    uri=f"{UKO_RS_IRI}mustUse",
    label="mustUse",
    comment="Whether this item carries a #[must_use] annotation.",
    domain=(
        f"{UKO_RS_IRI}RustStruct",
        f"{UKO_RS_IRI}RustFunction",
    ),
    range_uri="xsd:boolean",
    is_object_property=False,
)

_rs_has_derive = UKOProperty(
    uri=f"{UKO_RS_IRI}hasDerive",
    label="hasDerive",
    comment="Links a struct to its #[derive] attribute.",
    domain=(f"{UKO_RS_IRI}RustStruct",),
    range_uri=f"{UKO_RS_IRI}RustDeriveAttribute",
    is_object_property=True,
)

_rs_implements_trait = UKOProperty(
    uri=f"{UKO_RS_IRI}implementsTrait",
    label="implementsTrait",
    comment="Links an impl block to the trait it implements.",
    domain=(f"{UKO_RS_IRI}RustImpl",),
    range_uri=f"{UKO_RS_IRI}RustTrait",
    is_object_property=True,
)


# ---------------------------------------------------------------------------
# Layer 2 dependencies
# ---------------------------------------------------------------------------

_RS_LAYER2_DEPS = (
    Layer2Dependency(
        uri=f"{UKO_OO_IRI}Class",
        prefix="uko-oo:",
        description="OO class (RustStruct extends this).",
    ),
    Layer2Dependency(
        uri=f"{UKO_OO_IRI}Interface",
        prefix="uko-oo:",
        description="OO interface (RustTrait extends this).",
    ),
    Layer2Dependency(
        uri=f"{UKO_OO_IRI}Method",
        prefix="uko-oo:",
        description="OO method (RustFunction extends this).",
    ),
    # Conceptual reference — no Layer 3 class directly extends this.
    Layer2Dependency(
        uri=f"{UKO_FUNC_IRI}PureFunction",
        prefix="uko-func:",
        description=("Functional pure function (Rust supports functional patterns)."),
    ),
    # Conceptual reference — no Layer 3 class directly extends this.
    Layer2Dependency(
        uri=f"{UKO_FUNC_IRI}TypeClass",
        prefix="uko-func:",
        description=(
            "Functional type class (Rust traits parallel Haskell typeclasses)."
        ),
    ),
    Layer2Dependency(
        uri=f"{UKO_CODE_IRI}TypeDefinition",
        prefix="uko-code:",
        layer=1,
        description="General type definition (RustImpl, RustDeriveAttribute).",
    ),
)


# ---------------------------------------------------------------------------
# DetailLevelMap: extends uko-oo: at SIGNATURES level
# ---------------------------------------------------------------------------

# Rust extends at SIGNATURES level — enriches the content at
# SIGNATURES depth with visibility, lifetimes, trait bounds, unsafe,
# derive macros, must_use.  No new depth levels are inserted.
_RS_INSERTIONS: tuple[tuple[str, int], ...] = ()

RUST_DETAIL_LEVELS: tuple[tuple[str, int], ...] = build_detail_level_map(
    OO_EFFECTIVE_LEVELS, _RS_INSERTIONS
)


# ---------------------------------------------------------------------------
# Vocabulary definition
# ---------------------------------------------------------------------------

RUST_VOCABULARY = UKOVocabulary(
    namespace=UKO_RS_IRI,
    prefix=UKO_RS_PREFIX,
    layer=3,
    label="Rust Technology Vocabulary",
    comment=(
        "Layer 3 technology-specific vocabulary for Rust. "
        "Extends uko-oo: with visibility modifiers, "
        "lifetime parameters, trait bounds, unsafe markers, "
        "#[derive] macros, and #[must_use] annotations."
    ),
    parent_prefixes=("uko-oo:",),
    classes=(
        RustStruct,
        RustTrait,
        RustImpl,
        RustFunction,
        RustDeriveAttribute,
    ),
    properties=(
        _rs_visibility,
        _rs_lifetime_params,
        _rs_trait_bounds,
        _rs_is_unsafe,
        _rs_derive_traits,
        _rs_must_use,
        _rs_has_derive,
        _rs_implements_trait,
    ),
    layer2_dependencies=_RS_LAYER2_DEPS,
    inserted_levels=(),
)
