.check_core_imports.yaml

# Configuration for scripts/check_core_imports.py
#
# This enforces the architectural principle that hexdag/kernel contains pure
# abstractions (ports, domain models) and should NOT import from concrete
# implementations in hexdag/drivers or hexdag/stdlib.
#
# Allowed exceptions are documented below with rationale.

# Directory to check (relative to repo root)
check_directory: hexdag/kernel

# Forbidden import patterns (regex)
forbidden_patterns:
  - '^from\s+hexdag\.api'
  - '^from\s+hexdag\.drivers'
  - '^from\s+hexdag\.stdlib'
  - '^from\s+hexdag\.cli'
  - '^import\s+hexdag\.api'
  - '^import\s+hexdag\.drivers'
  - '^import\s+hexdag\.stdlib'
  - '^import\s+hexdag\.cli'
  # Legacy paths (catch any leftovers from pre-rename)
  - '^from\s+hexdag\.adapters'
  - '^from\s+hexdag\.builtin'
  - '^import\s+hexdag\.adapters'
  - '^import\s+hexdag\.builtin'

# Allowed exceptions: file_path -> [list of exact import statements]
# Each exception requires a comment explaining WHY it's needed.
allowed_exceptions:
  # Orchestrator needs default executor implementation
  # This is the ONLY place where kernel imports from drivers.
  # Rationale: User convenience - orchestrator works out-of-the-box without
  # requiring explicit executor injection in every use case.
  hexdag/kernel/orchestration/orchestrator.py:
    - "from hexdag.drivers.executors import ("

  # PortsBuilder provides convenience factory methods for common adapters
  # These are lazy imports inside helper methods, not module-level dependencies.
  # Rationale: Developer experience - quick setup without manual instantiation.
  hexdag/kernel/ports_builder.py:
    - "from hexdag.drivers.observer_manager import ("
    - "from hexdag.stdlib.adapters.mock import MockLLM  # lazy: optional default providers"
    - "from hexdag.stdlib.adapters.openai import OpenAIAdapter"
    - "from hexdag.stdlib.adapters.anthropic import AnthropicAdapter"

  # ExecutionCoordinator needs FieldExtractor for input_mapping feature
  # This provides $input.field and node.field path extraction during execution.
  # Rationale: Input mapping is a core execution feature that reuses existing extraction logic.
  hexdag/kernel/orchestration/components/execution_coordinator.py:
    - "from hexdag.stdlib.nodes.mapped_input import FieldExtractor"

  # Models.py has doctest examples that import adapters for demonstration
  # These are documentation/test imports, not runtime dependencies.
  # Rationale: Doctests need concrete examples to be runnable.
  hexdag/kernel/orchestration/models.py:
    - "from hexdag.stdlib.adapters.mock import MockLLM"
    - "from hexdag.stdlib.adapters.openai import OpenAIAdapter"
    - "from hexdag.stdlib.adapters.anthropic import AnthropicAdapter"

  # lib_base.py is a backward-compat re-export shim.
  # The canonical location is hexdag.stdlib.lib_base.
  # Rationale: Maintains import compatibility while lib contract lives in stdlib.
  hexdag/kernel/lib_base.py:
    - "from hexdag.stdlib.lib_base import HexDAGLib, get_lib_tool_schemas  # noqa: F401"

  # observers/__init__.py is a backward-compat re-export shim.
  # The canonical location is hexdag.stdlib.lib.observers.
  # Rationale: Maintains import compatibility while observer implementations live in stdlib.
  hexdag/kernel/orchestration/events/observers/__init__.py:
    - "from hexdag.stdlib.lib.observers import ("

  # port_wrappers.py stacks middleware (observable, structured output) onto ports.
  # These are lazy imports inside prepare_ports(), not module-level dependencies.
  # Rationale: Middleware stacking is an orchestration concern that needs concrete middleware.
  hexdag/kernel/orchestration/port_wrappers.py:
    - "from hexdag.stdlib.middleware.observable import ObservableLLM"
    - "from hexdag.stdlib.middleware.observable_tool_router import ObservableToolRouter"
    - "from hexdag.stdlib.middleware.structured_output import StructuredOutputFallback"

  # Resolver imports stdlib.nodes to trigger auto-discovery and alias registration
  # Also imports adapter/macro discovery for the unified alias system.
  # These are lazy imports inside _ensure_builtin_bootstrapped(), not module-level dependencies.
  # Rationale: Enables auto-discovery of component factories without hardcoding builtin knowledge.
  hexdag/kernel/resolver.py:
    - "import hexdag.stdlib.nodes  # noqa: F401  # lazy: bootstrap discovery"
    - "from hexdag.stdlib.adapters._discovery import ("
    - "from hexdag.stdlib.macros._discovery import ("