"""One authority for the 14 vault dimensions and the labels that name them.

`vault_dimensions` is a list of bare integers, so a range check is the only
validation a number can carry on its own — and a range check cannot tell that
`4` means Audience Interaction while the prose beside it says humor. That gap is
how entries came to file evidence under dimensions they are not about.

This registry closes it by making the prose label resolvable. Every label the
catalog actually uses is an owner-approved alias of exactly one dimension, so a
`Dimension N (Label)` claim can be checked: does N match where the label
resolves? A label with no alias does not resolve, and the auditor reports it for
owner review rather than guessing — the migration stays reviewed rather than
becoming an automatic renumbering.
"""

from __future__ import annotations

import re
from dataclasses import dataclass
from pathlib import Path
from typing import Any, Iterable, Mapping

import yaml

from catalog_normalization import normalize_catalog_alias


DIMENSION_REGISTRY_SCHEMA_VERSION = 1
DIMENSION_COUNT = 14
REGISTRY_FILENAME = "_dimensions.yaml"

# `Dimension 4 (Audience Engagement)` and `Vault Dimension 13 (Slide Design)`
# are the two shapes the catalog uses.
DIMENSION_CLAIM_RE = re.compile(r"(?:Vault )?Dimension (\d+) \(([^)]+)\)")


class CatalogDimensionRegistryError(ValueError):
    """The dimension registry is missing, malformed, or self-contradictory."""


@dataclass(frozen=True)
class Dimension:
    """One canonical dimension and every label approved to name it."""

    id: str
    ordinal: int
    name: str
    aliases: tuple[str, ...]


@dataclass(frozen=True)
class DimensionRegistry:
    """The loaded registry, indexed for resolution."""

    dimensions: tuple[Dimension, ...]
    _by_normalized_label: Mapping[str, int]

    def ordinal_for_label(self, label: str) -> int | None:
        """Resolve a prose label to its canonical ordinal, or None.

        None means the label is not owner-approved for any dimension. It is
        never a reason to fall back to the number already written beside it —
        that number is exactly what is under review.
        """
        return self._by_normalized_label.get(normalize_catalog_alias(label))

    def by_ordinal(self, ordinal: int) -> Dimension | None:
        for dimension in self.dimensions:
            if dimension.ordinal == ordinal:
                return dimension
        return None


def _require_mapping(value: object, label: str) -> Mapping[str, Any]:
    if not isinstance(value, Mapping):
        raise CatalogDimensionRegistryError(f"{label} must be a mapping")
    return value


def _require_text(value: object, label: str) -> str:
    if not isinstance(value, str) or not value.strip():
        raise CatalogDimensionRegistryError(f"{label} must be a non-empty string")
    return value


def load_dimension_registry(catalog_dir: Path | str) -> DimensionRegistry:
    """Load and validate the registry beside the catalog entries."""
    path = Path(catalog_dir) / REGISTRY_FILENAME
    try:
        raw = path.read_text(encoding="utf-8")
    except OSError as exc:
        raise CatalogDimensionRegistryError(
            f"cannot read dimension registry {path}: {exc}"
        ) from exc
    try:
        parsed = yaml.safe_load(raw)
    except yaml.YAMLError as exc:
        # The auditor promises a `dimension_registry_invalid` finding for a
        # registry it cannot use. A YAMLError escaping this call would crash it
        # instead, turning the one reportable failure into no report at all.
        raise CatalogDimensionRegistryError(
            f"cannot parse dimension registry {path}: {exc}"
        ) from exc
    document = _require_mapping(parsed, str(path))
    version = document.get("schema_version")
    if version != DIMENSION_REGISTRY_SCHEMA_VERSION:
        raise CatalogDimensionRegistryError(
            f"{path} schema_version must be {DIMENSION_REGISTRY_SCHEMA_VERSION}, "
            f"got {version!r}"
        )
    entries = document.get("dimensions")
    if not isinstance(entries, list) or len(entries) != DIMENSION_COUNT:
        raise CatalogDimensionRegistryError(
            f"{path} must declare exactly {DIMENSION_COUNT} dimensions"
        )

    dimensions: list[Dimension] = []
    by_label: dict[str, int] = {}
    seen_ordinals: set[int] = set()
    seen_ids: set[str] = set()
    for index, entry in enumerate(entries):
        mapping = _require_mapping(entry, f"{path} dimensions[{index}]")
        unknown = set(mapping) - {"id", "ordinal", "name", "aliases"}
        if unknown:
            raise CatalogDimensionRegistryError(
                f"{path} dimensions[{index}] has unknown keys {sorted(unknown)}"
            )
        identifier = _require_text(mapping.get("id"), f"{path} dimensions[{index}].id")
        name = _require_text(mapping.get("name"), f"{path} dimensions[{index}].name")
        ordinal = mapping.get("ordinal")
        if not isinstance(ordinal, int) or isinstance(ordinal, bool):
            raise CatalogDimensionRegistryError(
                f"{path} dimensions[{index}].ordinal must be an integer"
            )
        if not 1 <= ordinal <= DIMENSION_COUNT:
            raise CatalogDimensionRegistryError(
                f"{path} dimensions[{index}].ordinal {ordinal} is out of range"
            )
        if ordinal in seen_ordinals:
            raise CatalogDimensionRegistryError(f"{path} repeats ordinal {ordinal}")
        if identifier in seen_ids:
            raise CatalogDimensionRegistryError(f"{path} repeats id {identifier!r}")
        seen_ordinals.add(ordinal)
        seen_ids.add(identifier)

        raw_aliases = mapping.get("aliases", [])
        if not isinstance(raw_aliases, list):
            raise CatalogDimensionRegistryError(
                f"{path} dimensions[{index}].aliases must be an array"
            )
        aliases = tuple(
            _require_text(alias, f"{path} dimensions[{index}].aliases[{position}]")
            for position, alias in enumerate(raw_aliases)
        )
        # The canonical name resolves too, so an entry already using it needs no
        # alias entry to duplicate it.
        for label in (name, *aliases):
            normalized = normalize_catalog_alias(label)
            if not normalized:
                raise CatalogDimensionRegistryError(
                    f"{path} dimensions[{index}] label {label!r} normalizes empty"
                )
            previous = by_label.get(normalized)
            if previous is not None and previous != ordinal:
                # One label naming two dimensions makes every claim using it
                # unresolvable, which is worse than having no alias at all.
                raise CatalogDimensionRegistryError(
                    f"{path} label {label!r} resolves to both dimension "
                    f"{previous} and {ordinal}"
                )
            by_label[normalized] = ordinal
        dimensions.append(
            Dimension(id=identifier, ordinal=ordinal, name=name, aliases=aliases)
        )

    if seen_ordinals != set(range(1, DIMENSION_COUNT + 1)):
        raise CatalogDimensionRegistryError(
            f"{path} must cover ordinals 1-{DIMENSION_COUNT} exactly once"
        )
    return DimensionRegistry(
        dimensions=tuple(sorted(dimensions, key=lambda item: item.ordinal)),
        _by_normalized_label=by_label,
    )


@dataclass(frozen=True)
class DimensionClaim:
    """One `Dimension N (Label)` claim found in entry prose."""

    stated_ordinal: int
    label: str
    resolved_ordinal: int | None

    @property
    def agrees(self) -> bool:
        return self.resolved_ordinal == self.stated_ordinal

    @property
    def unresolved(self) -> bool:
        return self.resolved_ordinal is None


def dimension_claims(text: str, registry: DimensionRegistry) -> list[DimensionClaim]:
    """Read every dimension claim in one entry's prose."""
    return [
        DimensionClaim(
            stated_ordinal=int(match.group(1)),
            label=match.group(2).strip(),
            resolved_ordinal=registry.ordinal_for_label(match.group(2).strip()),
        )
        for match in DIMENSION_CLAIM_RE.finditer(text)
    ]


def resolved_vault_dimensions(claims: Iterable[DimensionClaim]) -> list[int]:
    """The `vault_dimensions` the prose supports, sorted.

    A resolved claim contributes where its label resolves. An UNRESOLVED claim
    contributes the number already written beside it — preserved, not endorsed.
    Dropping it would silently delete a membership on the strength of a missing
    alias, which is a bigger change than the drift being fixed; the auditor
    reports the unresolved label separately so an owner decides it explicitly.
    """
    ordinals: set[int] = set()
    for claim in claims:
        resolved = claim.resolved_ordinal
        ordinals.add(claim.stated_ordinal if resolved is None else resolved)
    return sorted(ordinals)