# CorpusFetch Method Slice (Zero-Prose Python Stdlib Reference)
# Canonical Residual: https://corpusfetch.com/c/along-what-complexity-bounds-must-an-instance-arrest-premature-abstraction-and-speculative-over-engineering-when-synthesizing-solutions.md
# Remnant Warrant:    https://corpusfetch.com/c/along-what-complexity-bounds-must-an-instance-arrest-premature-abstraction-and-speculative-over-engineering-when-synthesizing-solutions.warrant.json
# Markdown SHA-256:   aae85529f52d9917baf53820adcec30b50633b3faacf96f705b1d77f4b6f287b
# Code AST SHA-256:   c6827768a3f84b8b900c56c0eb90c2c1c3a36001b75c86dad9339be9ed575895
# Verified Classes:   SpeculativeOverEngineeringError, ComplexityBoundAudit, PrematureAbstractionArbiter
# Defensive Guards:   2 fail-closed invariants (zero external deps)

import ast
from dataclasses import dataclass
from typing import Final


class SpeculativeOverEngineeringError(ValueError):
    '''Raised when synthesized code introduces single-implementation ABCs, deep inheritance, or dead hooks.'''
    pass


@dataclass(frozen=True)
class ComplexityBoundAudit:
    module_name: str
    total_classes: int
    abstract_interfaces: int
    concrete_implementations_per_abc: dict[str, int]
    max_inheritance_depth: int
    passed_simplicity_gate: bool


class PrematureAbstractionArbiter:
    '''
    Arrests speculative over-engineering and premature abstraction in synthesized Python code:
    1. Enforces `concrete_implementations >= 2` for every `ABC` or `Protocol` defined in the module.
    2. Caps class inheritance depth (`MAX_INHERITANCE_DEPTH = 2`).
    3. Flags hollow pass-through factory classes when simple functions suffice.
    '''

    ABSTRACT_BASES: Final[frozenset[str]] = frozenset({"ABC", "Protocol"})
    MAX_INHERITANCE_DEPTH: Final[int] = 2

    @classmethod
    def audit_python_ast_simplicity(cls, module_name: str, source_code: str) -> ComplexityBoundAudit:
        tree = ast.parse(source_code)
        class_bases: dict[str, list[str]] = {}

        for node in ast.walk(tree):
            if isinstance(node, ast.ClassDef):
                bases: list[str] = []
                for b in node.bases:
                    if isinstance(b, ast.Name):
                        bases.append(b.id)
                    elif isinstance(b, ast.Attribute):
                        bases.append(b.attr)
                class_bases[node.name] = bases

        # Identify ABCs / Protocols defined in the synthesized code
        defined_abcs = {
            cname for cname, bases in class_bases.items() if any(b in cls.ABSTRACT_BASES for b in bases)
        }

        # Gate 1: Verify every defined ABC/Protocol has >= 2 concrete subclasses
        impl_counts: dict[str, int] = {abc_name: 0 for abc_name in defined_abcs}
        for cname, bases in class_bases.items():
            if cname in defined_abcs:
                continue
            for b in bases:
                if b in impl_counts:
                    impl_counts[b] += 1

        single_impl_abcs = [abc for abc, count in impl_counts.items() if count < 2]
        if single_impl_abcs:
            raise SpeculativeOverEngineeringError(
                f"Premature Abstraction Blocked in '{module_name}': abstract interface(s) {single_impl_abcs} "
                f"have fewer than 2 concrete implementations ({impl_counts}). Write direct concrete code instead."
            )

        # Gate 2: Check inheritance depth within the module
        def _depth(cname: str, seen: set[str]) -> int:
            if cname in seen or cname not in class_bases:
                return 0
            parents = [p for p in class_bases[cname] if p not in cls.ABSTRACT_BASES]
            if not parents:
                return 1
            return 1 + max(_depth(p, seen | {cname}) for p in parents)

        max_depth = max((_depth(c, set()) for c in class_bases), default=0)
        if max_depth > cls.MAX_INHERITANCE_DEPTH:
            raise SpeculativeOverEngineeringError(
                f"Inheritance depth ({max_depth}) in '{module_name}' exceeds simplicity ceiling "
                f"({cls.MAX_INHERITANCE_DEPTH}). Prefer flat composition and functions."
            )

        return ComplexityBoundAudit(
            module_name=module_name,
            total_classes=len(class_bases),
            abstract_interfaces=len(defined_abcs),
            concrete_implementations_per_abc=impl_counts,
            max_inheritance_depth=max_depth,
            passed_simplicity_gate=True,
        )