"""Rule contract for the tq analysis engine."""

from __future__ import annotations

from typing import TYPE_CHECKING, Protocol, runtime_checkable

if TYPE_CHECKING:
    from tq.engine.context import AnalysisContext
    from tq.engine.models import Finding
    from tq.engine.rule_id import RuleId


@runtime_checkable
class Rule(Protocol):
    """Contract for analysis rules used by the orchestration engine."""

    @property
    def rule_id(self) -> RuleId:
        """Return stable rule identifier for diagnostics and selection."""

    def evaluate(self, context: AnalysisContext) -> tuple[Finding, ...]:
        """Evaluate a rule against immutable analysis context.

        Args:
            context: Immutable analysis context for this engine run.

        Returns:
            Deterministic collection of findings emitted by this rule.
        """
