"""Check 原语基类与上下文。"""

from __future__ import annotations
from dataclasses import dataclass, field
from typing import Any, TYPE_CHECKING
from fastapi_modules.fastapi_leaudit.govdoc_engine.models import Document, Paragraph
from fastapi_modules.fastapi_leaudit.govdoc_engine.dsl.schema import RuleStage

if TYPE_CHECKING:
    from fastapi_modules.fastapi_leaudit.govdoc_engine.parser.entities import SemanticEntity


@dataclass
class CheckContext:
    document: Document
    paragraphs: list[Paragraph]
    stage: RuleStage
    entities: dict[str, "SemanticEntity | None"] = field(default_factory=dict)
    target: "SemanticEntity | None" = None
    rule_id: str = ""


@dataclass
class CheckHit:
    paragraph: Paragraph | None
    char_start: int = 0
    char_end: int = 0
    actual: dict[str, Any] | None = None
    expected: dict[str, Any] | None = None
    message: str | None = None
    confidence: float = 1.0


@dataclass
class CheckResult:
    passed: bool
    hits: list[CheckHit] = field(default_factory=list)
    skipped: bool = False
    skip_reason: str = ""


class CheckBase:
    """所有 check 原语的抽象基类。"""

    name: str = ""

    def run(self, ctx: CheckContext) -> CheckResult:
        raise NotImplementedError
