Rules¶

def get_number_of_principles(language: LanguageZenPrinciples) -> int:
    """Count principles defined for a single language.

    Args:
        language (LanguageZenPrinciples): The ``LanguageZenPrinciples`` instance to inspect.

    Returns:
        int: Number of ``ZenPrinciple`` entries in *language*.
    """
    return language.principle_count

def get_number_of_priniciple(language: LanguageZenPrinciples) -> int:
    """Backward-compatible alias for ``get_number_of_principles`` (typo preserved).

    Args:
        language (LanguageZenPrinciples): Delegated to ``get_number_of_principles``.

    Returns:
        int: Same as ``get_number_of_principles``.
    """
    return get_number_of_principles(language)

def get_rule_ids(language: LanguageZenPrinciples) -> set[str]:
    """Collect the unique ``ZenPrinciple.id`` values for a language.

    Args:
        language (LanguageZenPrinciples): The ``LanguageZenPrinciples`` to extract IDs from.

    Returns:
        set[str]: Set of principle IDs (e.g. ``{"python-001", "python-002", …}``).
    """
    return {principle.id for principle in language.principles}

def get_total_principles(
    registry: dict[str, LanguageZenPrinciples],
) -> int:
    """Sum principle counts across every language in *registry*.

    Args:
        registry (dict[str, LanguageZenPrinciples]): The ``ZEN_REGISTRY`` mapping (language key → principles).

    Returns:
        int: Aggregate principle count.
    """
    return sum(language.principle_count for language in registry.values())

def get_missing_detector_rules(
    language: LanguageZenPrinciples,
    *,
    explicit_only: bool = True,
) -> list[str]:
    """Identify principle IDs that have no dedicated detector registered.

    When *explicit_only* is ``True`` (the default), the generic
    ``RulePatternDetector`` fallback is ignored — only purpose-built
    detectors count as coverage.

    Args:
        language (LanguageZenPrinciples): The ``LanguageZenPrinciples`` whose coverage is checked.
        explicit_only (bool, optional): If ``True``, exclude the catch-all pattern detector
            from the coverage calculation. Default to True.

    Returns:
        list[str]: Sorted list of principle IDs without detector coverage.

    See Also:
        ``get_rule_id_coverage`` — also reports *unknown* detector mappings.
    """
    from mcp_zen_of_languages.analyzers import registry_bootstrap  # noqa: F401
    from mcp_zen_of_languages.analyzers.registry import REGISTRY
    from mcp_zen_of_languages.languages.rule_pattern import RulePatternDetector

    missing: list[str] = []
    for principle in language.principles:
        metas = REGISTRY.detectors_for_rule(principle.id, language.language)
        if explicit_only:
            metas = [
                meta for meta in metas if meta.detector_class is not RulePatternDetector
            ]
        if not metas:
            missing.append(principle.id)
    return missing

def get_rule_id_coverage(
    language: LanguageZenPrinciples,
    *,
    explicit_only: bool = True,
) -> tuple[list[str], list[str]]:
    """Compute bidirectional coverage between principles and detectors.

    Returns two lists:

    * **missing** — principle IDs with no mapped detector.
    * **unknown** — detector rule-IDs that reference principles not defined
      in the canonical rule set (potential stale registrations).

    Args:
        language (LanguageZenPrinciples): The ``LanguageZenPrinciples`` to audit.
        explicit_only (bool, optional): When ``True``, ignore ``RulePatternDetector`` fallbacks. Default to True.

    Returns:
        tuple[list[str], list[str]]: ``(missing, unknown)`` — both lists sorted alphabetically.
    """
    from mcp_zen_of_languages.analyzers import registry_bootstrap  # noqa: F401
    from mcp_zen_of_languages.analyzers.registry import REGISTRY
    from mcp_zen_of_languages.languages.rule_pattern import RulePatternDetector

    expected = get_rule_ids(language)
    mapped: set[str] = set()
    for meta in REGISTRY.items():
        if meta.language != language.language:
            continue
        if explicit_only and meta.detector_class is RulePatternDetector:
            continue
        mapped.update(meta.rule_ids)
    missing = sorted(expected - mapped)
    unknown = sorted(mapped - expected)
    return missing, unknown

def get_registry_rule_id_gaps(
    registry: dict[str, LanguageZenPrinciples],
    *,
    explicit_only: bool = True,
) -> dict[str, dict[str, list[str]]]:
    """Run ``get_rule_id_coverage`` across every language and collect gaps.

    Languages with no gaps are omitted from the result.

    Args:
        registry (dict[str, LanguageZenPrinciples]): Full ``ZEN_REGISTRY`` mapping.
        explicit_only (bool, optional): Passed through to ``get_rule_id_coverage``. Default to True.

    Returns:
        dict[str, dict[str, list[str]]]: ``{language: {"missing": [...], "unknown": [...]}}`` for each
        language that has at least one gap.
    """
    gaps: dict[str, dict[str, list[str]]] = {}
    for language in registry.values():
        missing, unknown = get_rule_id_coverage(language, explicit_only=explicit_only)
        if missing or unknown:
            gaps[language.language] = {"missing": missing, "unknown": unknown}
    return gaps

def get_registry_detector_gaps(
    registry: dict[str, LanguageZenPrinciples],
    *,
    explicit_only: bool = True,
) -> dict[str, list[str]]:
    """Return principle IDs lacking a dedicated detector for each language.

    This is a convenience wrapper around ``get_missing_detector_rules``
    applied to every language in *registry*.

    Args:
        registry (dict[str, LanguageZenPrinciples]): Full ``ZEN_REGISTRY`` mapping.
        explicit_only (bool, optional): Passed through to ``get_missing_detector_rules``. Default to True.

    Returns:
        dict[str, list[str]]: ``{language: [rule_id, …]}`` for each language with missing detectors.
    """
    gaps: dict[str, list[str]] = {}
    for language in registry.values():
        if missing := get_missing_detector_rules(language, explicit_only=explicit_only):
            gaps[language.language] = missing
    return gaps

def build_rule_coverage(language: str) -> RuleCoverageMap:
    """Build an inclusive rule-to-detector map for *language*.

    Includes ``RulePatternDetector`` fallback registrations alongside
    purpose-built detectors.

    Args:
        language (str): Lowercase language key (e.g. ``"python"``).

    Returns:
        RuleCoverageMap: A ``RuleCoverageMap`` covering every principle defined for *language*.

    Raises:
        ValueError: If *language* is not present in the registry.
    """
    from mcp_zen_of_languages.analyzers import registry_bootstrap  # noqa: F401
    from mcp_zen_of_languages.analyzers.registry import REGISTRY

    lang_zen = get_language_zen(language)
    if lang_zen is None:
        msg = f"Unknown language: {language}"
        raise ValueError(msg)
    rules: dict[str, list[str]] = {}
    for principle in lang_zen.principles:
        metas = REGISTRY.detectors_for_rule(principle.id, language)
        detector_ids = sorted({meta.detector_id for meta in metas})
        rules[principle.id] = detector_ids
    return RuleCoverageMap(language=language, rules=rules)

def build_explicit_rule_coverage(language: str) -> RuleCoverageMap:
    """Build a strict rule-to-detector map excluding ``RulePatternDetector`` fallbacks.

    Raises ``ValueError`` if any principle lacks a purpose-built detector.

    Args:
        language (str): Lowercase language key.

    Returns:
        RuleCoverageMap: A ``RuleCoverageMap`` containing only explicitly registered detectors.

    Raises:
        ValueError: If *language* is unknown or any principle is uncovered.
    """
    from mcp_zen_of_languages.analyzers import registry_bootstrap  # noqa: F401
    from mcp_zen_of_languages.analyzers.registry import REGISTRY

    lang_zen = get_language_zen(language)
    if lang_zen is None:
        msg = f"Unknown language: {language}"
        raise ValueError(msg)
    rules: dict[str, list[str]] = {}
    for principle in lang_zen.principles:
        metas = REGISTRY.detectors_for_rule(principle.id, language)
        if detector_ids := sorted(
            {
                meta.detector_id
                for meta in metas
                if meta.detector_class is not RulePatternDetector
            },
        ):
            rules[principle.id] = detector_ids
        else:
            msg = f"Explicit coverage missing for {language} rule {principle.id}"
            raise ValueError(msg)
    return RuleCoverageMap(language=language, rules=rules)

def build_rule_config_coverage(language: str) -> RuleConfigCoverageMap:
    """Build an inclusive rule-to-config-class map for *language*.

    Args:
        language (str): Lowercase language key.

    Returns:
        RuleConfigCoverageMap: A ``RuleConfigCoverageMap`` listing every ``DetectorConfig`` subclass
        serving each principle.

    Raises:
        ValueError: If *language* is not present in the registry.
    """
    from mcp_zen_of_languages.analyzers import registry_bootstrap  # noqa: F401
    from mcp_zen_of_languages.analyzers.registry import REGISTRY

    lang_zen = get_language_zen(language)
    if lang_zen is None:
        msg = f"Unknown language: {language}"
        raise ValueError(msg)
    rules: dict[str, list[type[DetectorConfig]]] = {}
    for principle in lang_zen.principles:
        metas = REGISTRY.detectors_for_rule(principle.id, language)
        ordered_metas = sorted(metas, key=lambda meta: meta.detector_id)
        configs: list[type[DetectorConfig]] = []
        seen: set[type[DetectorConfig]] = set()
        for meta in ordered_metas:
            config_model = meta.config_model
            if config_model in seen:
                continue
            seen.add(config_model)
            configs.append(config_model)
        rules[principle.id] = configs
    return RuleConfigCoverageMap(language=language, rules=rules)

def build_explicit_rule_config_coverage(language: str) -> RuleConfigCoverageMap:
    """Build a strict rule-to-config-class map excluding ``RulePatternDetector`` fallbacks.

    Raises ``ValueError`` if any principle lacks an explicit config class.

    Args:
        language (str): Lowercase language key.

    Returns:
        RuleConfigCoverageMap: A ``RuleConfigCoverageMap`` containing only explicitly registered configs.

    Raises:
        ValueError: If *language* is unknown or any principle is uncovered.
    """
    from mcp_zen_of_languages.analyzers import registry_bootstrap  # noqa: F401
    from mcp_zen_of_languages.analyzers.registry import REGISTRY

    lang_zen = get_language_zen(language)
    if lang_zen is None:
        msg = f"Unknown language: {language}"
        raise ValueError(msg)
    rules: dict[str, list[type[DetectorConfig]]] = {}
    for principle in lang_zen.principles:
        metas = REGISTRY.detectors_for_rule(principle.id, language)
        ordered_metas = sorted(
            (meta for meta in metas if meta.detector_class is not RulePatternDetector),
            key=lambda meta: meta.detector_id,
        )
        configs: list[type[DetectorConfig]] = []
        seen: set[type[DetectorConfig]] = set()
        for meta in ordered_metas:
            config_model = meta.config_model
            if config_model in seen:
                continue
            seen.add(config_model)
            configs.append(config_model)
        if not configs:
            msg = f"Explicit config coverage missing for {language} rule {principle.id}"
            raise ValueError(msg)
        rules[principle.id] = configs
    return RuleConfigCoverageMap(language=language, rules=rules)

def build_all_rule_coverage(
    languages: list[str] | None = None,
) -> list[RuleCoverageMap]:
    """Build inclusive rule coverage maps for all (or selected) languages.

    Args:
        languages (list[str] | None, optional): Restrict to these language keys.  ``None`` means all
            languages in the registry. Default to None.

    Returns:
        list[RuleCoverageMap]: One ``RuleCoverageMap`` per language.
    """
    langs = languages or get_all_languages()
    return [build_rule_coverage(lang) for lang in langs]

def build_all_explicit_rule_coverage(
    languages: list[str] | None = None,
) -> list[RuleCoverageMap]:
    """Build strict rule coverage maps (no fallback) for all (or selected) languages.

    Args:
        languages (list[str] | None, optional): Restrict to these language keys.  ``None`` means all. Default to None.

    Returns:
        list[RuleCoverageMap]: One ``RuleCoverageMap`` per language (raises on gaps).
    """
    langs = languages or get_all_languages()
    return [build_explicit_rule_coverage(lang) for lang in langs]

def build_all_rule_config_coverage(
    languages: list[str] | None = None,
) -> list[RuleConfigCoverageMap]:
    """Build inclusive config coverage maps for all (or selected) languages.

    Args:
        languages (list[str] | None, optional): Restrict to these language keys.  ``None`` means all. Default to None.

    Returns:
        list[RuleConfigCoverageMap]: One ``RuleConfigCoverageMap`` per language.
    """
    langs = languages or get_all_languages()
    return [build_rule_config_coverage(lang) for lang in langs]

def build_all_explicit_rule_config_coverage(
    languages: list[str] | None = None,
) -> list[RuleConfigCoverageMap]:
    """Build strict config coverage maps (no fallback) for all (or selected) languages.

    Args:
        languages (list[str] | None, optional): Restrict to these language keys.  ``None`` means all. Default to None.

    Returns:
        list[RuleConfigCoverageMap]: One ``RuleConfigCoverageMap`` per language (raises on gaps).
    """
    langs = languages or get_all_languages()
    return [build_explicit_rule_config_coverage(lang) for lang in langs]

def detect_ts_optional_chaining(code: str) -> TsOptionalChainingFinding:
    """Detect manual null-check chains replaceable by optional chaining.

    Args:
        code (str): TypeScript source text.

    Returns:
        TsOptionalChainingFinding: Detection result.
    """
    pattern = re.compile(r"\b\w+\s*&&\s*\w+\.\w+\s*&&\s*\w+\.\w+\.\w+")
    return TsOptionalChainingFinding(count=len(pattern.findall(code)))

def detect_ts_index_loops(code: str) -> TsIndexLoopFinding:
    """Detect C-style index-based for loops.

    Args:
        code (str): TypeScript source text.

    Returns:
        TsIndexLoopFinding: Detection result.
    """
    pattern = re.compile(r"for\s*\(\s*let\s+\w+\s*=\s*0\s*;\s*\w+\s*<")
    return TsIndexLoopFinding(count=len(pattern.findall(code)))

def detect_ts_promise_chains(code: str) -> TsPromiseChainFinding:
    """Detect raw .then() promise chains.

    Args:
        code (str): TypeScript source text.

    Returns:
        TsPromiseChainFinding: Detection result.
    """
    pattern = re.compile(r"\.then\s*\(")
    return TsPromiseChainFinding(count=len(pattern.findall(code)))