<?php

declare(strict_types=1);

namespace Drupal\flowdrop_runtime\Service\Compiler;

use Drupal\flowdrop_runtime\DTO\Compiler\DependencyGraph;

/**
 * Validates that tool_availability edges target capable consumers.
 *
 * A `tool_availability` edge means "the source node may use the target as a
 * tool". For that to do anything, the source node's processor must implement
 * {@see \Drupal\flowdrop\Plugin\FlowDropNodeProcessor\ToolsAwareInterface} —
 * otherwise the wired tools are silently ignored. This validator resolves the
 * processor class (which the dependency-light compiler cannot) and flags such
 * mis-wirings so they fail at compile time instead of confusing an author.
 */
interface ToolConsumerValidatorInterface {

  /**
   * Finds tool_availability edges whose consumer cannot consume tools.
   *
   * Only flags a consumer when its processor class is resolved and definitively
   * does NOT implement the capability; unresolvable consumers are skipped to
   * avoid false positives.
   *
   * @param \Drupal\flowdrop_runtime\DTO\Compiler\DependencyGraph $graph
   *   The dependency graph.
   *
   * @return array<int, string>
   *   Human-readable error messages, one per offending consumer (empty if OK).
   */
  public function validate(DependencyGraph $graph): array;

}
