docs.php

<?php

/**
 * @file
 * Reference documentation generator.
 *
 * It parses the PHP attributes and docblock comments of the traits under the
 * vocabulary directory and writes:
 *
 * - STEPS.md, the step vocabulary.
 * - HELPERS.md, the helpers a project calls from its own domain steps.
 * - The steps again for the documentation site, in 1 section per context,
 *   such as docs/content/drupal-steps/: an index in the README.md of the
 *   section, and 1 page per trait.
 * - The generated tables in docs/content/guides/configuration-reference.md.
 *
 * It also validates that:
 *
 * - The steps read in the documented format.
 * - Every step declares its actor, and its wording matches it.
 * - Every documented step matches exactly 1 definition.
 * - Every step trait names its page with a title.
 * - Every published helper carries a summary.
 * - Registered parametrized tags use `:` as their value separator.
 * - Every environment variable the source reads is documented.
 *
 * Run with --fail-on-change to fail if the documentation is not up to date.
 * Run with --path=path/to/dir to use another repository root: the autoloader,
 * the sources and the written documents all resolve under it.
 */

declare(strict_types=1);

use Behat\Behat\Definition\Pattern\Policy\TurnipPatternPolicy;
use Behat\Gherkin\Node\TableNode;
use Behat\Step\Given;
use Behat\Step\Then;
use Behat\Step\When;
use DrevOps\BehatSteps\DrupalContext;
use DrevOps\BehatSteps\Extension\Config\ConfigSchemaReader;
use DrevOps\BehatSteps\Extension\Config\GroupName;
use DrevOps\BehatSteps\Extension\Config\Option;
use DrevOps\BehatSteps\Extension\Config\TagOverrideResolver;
use DrevOps\BehatSteps\Extension\Prerequisite\Prerequisite;
use DrevOps\BehatSteps\Extension\Prerequisite\PrerequisiteReader;
use DrevOps\BehatSteps\Extension\ServiceContainer\BehatStepsExtension;
use DrevOps\BehatSteps\WebContext;
use DrevOps\BehatSteps\WebRawContext;
use Symfony\Component\Config\Definition\ArrayNode;
use Symfony\Component\Config\Definition\BooleanNode;
use Symfony\Component\Config\Definition\Builder\TreeBuilder;
use Symfony\Component\Config\Definition\IntegerNode;
use Symfony\Component\Config\Definition\NodeInterface;
use Symfony\Component\Config\Definition\PrototypedArrayNode;

/**
 * Directory holding the step vocabulary, relative to the repository root.
 *
 * Each directory directly below it is a context and gives its traits their
 * context name.
 */
const STEPS_DIRECTORY = 'src/Steps';

/**
 * Context whose traits are named and sorted without their context prefix.
 *
 * Its traits head the index, so the documents lead with the steps a suite
 * uses first. Their example features carry no name prefix.
 */
const DEFAULT_CONTEXT = 'Web';

/**
 * Values the "@actor:<value>" tag of a step docblock accepts.
 *
 * "person" marks a step a person performs or observes through something they
 * operate, so it reads in the first person. "system" marks a step about the
 * site or the test set-up, so it does not.
 */
const STEP_ACTORS = ['person', 'system'];

/**
 * Attribute namespaces that mark a method as registered with Behat.
 *
 * A method carrying one of these is a step, a hook or a transformation, so it
 * is not a helper.
 */
const REGISTERED_ATTRIBUTE_PREFIXES = [
  'Behat\\Step\\',
  'Behat\\Hook\\',
  'Behat\\Transformation\\',
  'DrevOps\\BehatSteps\\Extension\\Hook\\Attribute\\',
  'DrevOps\\BehatSteps\\Extension\\Drupal\\Hook\\Attribute\\',
];

/**
 * Directory holding the helper traits, relative to the repository root.
 */
const HELPERS_DIRECTORY = 'src/Steps/Helper';

/**
 * Classes published in the helper reference alongside the traits.
 *
 * The root context contributes the backend access and the scenario plumbing a
 * domain step is written against. Its public methods are helpers too.
 */
const HELPER_CLASSES = [WebRawContext::class];

/**
 * Context the helper classes are published under.
 */
const HELPER_CLASSES_CONTEXT = 'Root context';

/**
 * File holding the step reference, relative to the repository root.
 */
const STEPS_FILE = 'STEPS.md';

/**
 * File holding the helper reference, relative to the repository root.
 */
const HELPERS_FILE = 'HELPERS.md';

/**
 * File holding the step skill, relative to the repository root.
 */
const STEP_SKILL_FILE = 'skills/create-behat-step/SKILL.md';

/**
 * Directory of the documentation site's pages, relative to the repository root.
 *
 * The steps of each context get a section directory in it, such as
 * 'drupal-steps', whose README.md holds the index of its pages.
 */
const PAGES_DIRECTORY = 'docs/content';

/**
 * File holding the configuration reference, relative to the repository root.
 */
const CONFIGURATION_FILE = 'docs/content/guides/configuration-reference.md';

// The main function runs only when the script is run directly, not when it
// is included.
// @codeCoverageIgnoreStart
if (basename((string) $_SERVER['SCRIPT_FILENAME']) === 'docs.php') {
  $options = getopt('', ['fail-on-change', 'path::']);
  main($options);
}

// @codeCoverageIgnoreEnd

/**
 * Main function to handle the documentation generation process.
 *
 * @param array<string, bool|string|array<int, string>> $options
 *   Command line options.
 *
 * @codeCoverageIgnoreStart
 */
function main(array $options = []): void {
  $base_path = is_string($options['path'] ?? NULL) ? $options['path'] : __DIR__;

  require_once $base_path . '/build/vendor/autoload.php';

  $contexts = [WebContext::class, DrupalContext::class];
  $info = extract_info($contexts, [], $base_path);
  $helpers = extract_helpers($contexts, [], $base_path);

  $errors = validate($info);
  $errors = array_merge($errors, validate_step_patterns($info));
  $errors = array_merge($errors, validate_helpers($helpers));
  $errors = array_merge($errors, validate_titles($info));
  $errors = array_merge($errors, validate_tags($info, $base_path));
  $errors = array_merge($errors, validate_env_vars($base_path));

  if (!empty($errors)) {
    echo 'Errors found:' . PHP_EOL;

    foreach ($errors as $error) {
      echo $error;
    }

    exit(1);
  }

  $targets = [
    STEPS_FILE => [
      [
        '# Available steps',
        '[//]: # (END)',
        PHP_EOL . render_step_skill_link(STEPS_FILE) . render_info($info, $base_path) . PHP_EOL,
      ],
    ],
    HELPERS_FILE => [
      [
        '# Available helpers',
        '[//]: # (END)',
        PHP_EOL . render_step_skill_link(HELPERS_FILE) . render_helpers($helpers, $base_path) . PHP_EOL,
      ],
    ],
    CONFIGURATION_FILE => [
      [
        '[//]: # (START_EXTENSION_OPTIONS)',
        '[//]: # (END_EXTENSION_OPTIONS)',
        PHP_EOL . render_extension_options() . PHP_EOL,
      ],
      ['[//]: # (START_TAGS)', '[//]: # (END_TAGS)', PHP_EOL . render_tag_reference() . PHP_EOL],
    ],
  ];

  foreach (render_page_indexes($info) as $index => $table) {
    $targets[$index] = [['[//]: # (START_INDEX)', '[//]: # (END_INDEX)', PHP_EOL . $table . PHP_EOL]];
  }

  $outdated = [];
  $updated = [];

  foreach ($targets as $file => $regions) {
    $path = $base_path . '/' . $file;

    $contents = file_get_contents($path);

    if ($contents === FALSE) {
      printf('Failed to read %s.' . PHP_EOL, $file);
      exit(1);
    }

    $replaced = $contents;

    foreach ($regions as $region) {
      $replaced = replace_content($replaced, $region[0], $region[1], $region[2]);
    }

    if ($replaced !== $contents) {
      $outdated[] = $file;
      $updated[$path] = $replaced;
    }
  }

  $pages = render_step_pages($info, $helpers, $base_path);

  foreach ($pages as $file => $contents) {
    $path = $base_path . '/' . $file;

    if (!is_file($path) || file_get_contents($path) !== $contents) {
      $outdated[] = $file;
      $updated[$path] = $contents;
    }
  }

  $removed = [];

  foreach (stale_pages($base_path, $pages) as $file) {
    $outdated[] = $file;
    $removed[] = $base_path . '/' . $file;
  }

  if ($outdated === []) {
    echo 'Documentation is up to date. No changes were made.' . PHP_EOL;
    exit(0);
  }

  if (isset($options['fail-on-change'])) {
    printf('Documentation is outdated: %s. No changes were made.' . PHP_EOL, implode(', ', $outdated));
    exit(1);
  }

  foreach ($updated as $path => $contents) {
    if (!is_dir(dirname($path))) {
      mkdir(dirname($path), 0777, TRUE);
    }

    file_put_contents($path, $contents);
  }

  foreach ($removed as $path) {
    unlink($path);
  }

  printf('Documentation updated: %s.' . PHP_EOL, implode(', ', $outdated));
}

// @codeCoverageIgnoreEnd

/**
 * Check whether a PHP file declares a trait.
 *
 * @param string $file_path
 *   Path to the PHP file.
 *
 * @return bool
 *   TRUE when the file declares a trait.
 */
function file_declares_trait(string $file_path): bool {
  $contents = file_get_contents($file_path);

  return $contents !== FALSE && preg_match('/^\s*trait\s+\w+/m', $contents) === 1;
}

/**
 * Collect the vocabulary traits composed into the given classes.
 *
 * Every trait declared under the vocabulary directory has to be composed into
 * one of the classes. A reference document then covers the whole vocabulary
 * rather than the part 1 context uses.
 *
 * @param array<int, class-string> $class_names
 *   The classes documenting the vocabulary, 1 per context.
 * @param array<int, string> $exclude
 *   Array of trait names to exclude.
 * @param string $base_path
 *   Base path for the repository.
 *
 * @return array<string, array{reflection: \ReflectionClass<object>, context: string, host: class-string}>
 *   The trait reflection, its context and the class composing it, keyed by
 *   trait short name and sorted by that name.
 *
 * @throws \ReflectionException
 */
function collect_step_traits(array $class_names, array $exclude = [], string $base_path = __DIR__): array {
  $traits_path = $base_path . '/' . STEPS_DIRECTORY;
  $traits_files = [];

  if (is_dir($traits_path)) {
    $contexts = scandir($traits_path) ?: [];

    foreach ($contexts as $context) {
      $context_path = $traits_path . '/' . $context;

      if (!is_dir($context_path) || $context === '.' || $context === '..') {
        continue;
      }

      $context_files = scandir($context_path) ?: [];

      foreach ($context_files as $context_file) {
        $context_file_path = $context_path . '/' . $context_file;

        if (is_file($context_file_path) && file_declares_trait($context_file_path)) {
          $traits_files[] = basename($context_file, '.php');
        }
      }
    }

    sort($traits_files);
  }

  // Entries are removed from $traits_files as each trait is found, so the
  // membership test below reads a copy taken first.
  $vocabulary = $traits_files;
  $collected = [];

  foreach ($class_names as $class_name) {
    $reflection = new \ReflectionClass($class_name);

    foreach ($reflection->getTraits() as $trait) {
      $trait_name = $trait->getShortName();

      // A context composes helper traits beside the vocabulary, and only the
      // vocabulary belongs in the step reference. The directory a trait sits
      // in determines which it is.
      if (!in_array($trait_name, $vocabulary, TRUE)) {
        continue;
      }

      if (in_array($trait_name, $traits_files, TRUE)) {
        unset($traits_files[array_search($trait_name, $traits_files, TRUE)]);
      }

      if (in_array($trait_name, $exclude, TRUE)) {
        continue;
      }

      $trait_file_path = $trait->getFileName();

      // @codeCoverageIgnoreStart
      if (!$trait_file_path) {
        throw new \RuntimeException(sprintf('Trait %s does not have a file path', $trait_name));
      }

      // @codeCoverageIgnoreEnd
      $relative_path = str_replace($base_path . DIRECTORY_SEPARATOR . STEPS_DIRECTORY . DIRECTORY_SEPARATOR, '', $trait_file_path);
      $context = explode(DIRECTORY_SEPARATOR, $relative_path)[0];

      $collected[$trait_name] = ['reflection' => $trait, 'context' => $context, 'host' => $class_name];
    }
  }

  if (!empty($traits_files)) {
    throw new \RuntimeException(sprintf('The following traits were not found in the class: %s', implode(', ', $traits_files)));
  }

  uksort($collected, strcasecmp(...));

  return $collected;
}

/**
 * Collect the helper traits the package publishes.
 *
 * Every trait of the directory is published, and the directory marks it as
 * plumbing rather than vocabulary. The half it sits in names the context it
 * is available to, so the reference groups helpers the way the steps are
 * grouped.
 *
 * @param string $base_path
 *   Base path for the repository.
 *
 * @return array<string, array{reflection: \ReflectionClass<object>, context: string}>
 *   The trait reflection and its half, keyed by short name and sorted by that
 *   name.
 *
 * @throws \ReflectionException
 */
function collect_helper_traits(string $base_path = __DIR__): array {
  $helpers_path = $base_path . '/' . HELPERS_DIRECTORY;
  $collected = [];

  if (!is_dir($helpers_path)) {
    return $collected;
  }

  foreach (scandir($helpers_path) ?: [] as $context) {
    $context_path = $helpers_path . '/' . $context;

    if ($context === '.' || $context === '..' || !is_dir($context_path)) {
      continue;
    }

    foreach (scandir($context_path) ?: [] as $file) {
      $file_path = $context_path . '/' . $file;

      if (!is_file($file_path) || !file_declares_trait($file_path)) {
        continue;
      }

      $short_name = basename($file, '.php');
      /** @var class-string $trait_name */
      $trait_name = 'DrevOps\\BehatSteps\\Steps\\Helper\\' . $context . '\\' . $short_name;

      $collected[$short_name] = ['reflection' => new \ReflectionClass($trait_name), 'context' => $context];
    }
  }

  uksort($collected, strcasecmp(...));

  return $collected;
}

/**
 * Parse info from the classes.
 *
 * @param array<int, class-string> $class_names
 *   The classes documenting the vocabulary, 1 per context.
 * @param array<int, string> $exclude
 *   Array of trait names to exclude.
 * @param string $base_path
 *   Base path for the repository.
 *
 * @return array<string, array<string, mixed>>
 *   Array of info with 'name', 'name_contextual', 'class', 'context',
 *   'methods', 'options', 'prerequisites', 'description' and
 *   'description_full' keys, and a 'title' key when the trait declares one.
 *
 * @throws \ReflectionException
 */
function extract_info(array $class_names, array $exclude = [], string $base_path = __DIR__): array {
  $info = [];

  foreach (collect_step_traits($class_names, $exclude, $base_path) as $trait_name => $collected) {
    $trait = $collected['reflection'];
    $context = $collected['context'];

    $class_info = [
      'name' => $trait_name,
      'name_contextual' => ($context !== DEFAULT_CONTEXT ? $context . '\\' : '') . $trait_name,
      'class' => $trait->getName(),
      'context' => $context,
      'methods' => [],
      'options' => extract_trait_options($collected['host'], $trait_name),
      'prerequisites' => extract_trait_prerequisites($collected['host'], $trait->getName()),
    ];
    $class_info += parse_class_comment($trait_name, (string) $trait->getDocComment());

    $methods = $trait->getMethods(\ReflectionMethod::IS_PUBLIC);
    $trait_prefix = str_replace('Trait', '', $trait_name);
    // Methods group by the keyword of their first step, so the reference lists
    // Given steps first and Then steps last.
    $methods_by_keyword = ['@Given' => [], '@When' => [], '@Then' => []];

    foreach ($methods as $method) {
      if (!str_starts_with(strtolower($method->getName()), strtolower($trait_prefix))) {
        continue;
      }

      $steps = extract_method_steps($method);

      if (empty($steps)) {
        continue;
      }

      try {
        $parsed_comment = parse_method_comment((string) $method->getDocComment());
      }
      catch (\RuntimeException $exception) {
        throw new \RuntimeException(sprintf('%s::%s(): %s', $trait_name, $method->getName(), $exception->getMessage()), $exception->getCode(), $exception);
      }

      if (!isset($parsed_comment['actor'])) {
        throw new \RuntimeException(sprintf('Missing actor tag on %s::%s(). Add "@actor:%s" to its docblock.', $trait_name, $method->getName(), implode('" or "@actor:', STEP_ACTORS)));
      }

      $methods_by_keyword[explode(' ', $steps[0], 2)[0]][] = [
        'steps' => $steps,
        'description' => $parsed_comment['description'],
        'example' => $parsed_comment['example'],
        'actor' => $parsed_comment['actor'],
        'takes_table' => method_takes_table($method),
        'name' => $method->getName(),
      ];
    }

    $class_info['methods'] = array_merge(...array_values($methods_by_keyword));

    $info[$trait_name] = $class_info;
  }

  return $info;
}

/**
 * Read the option declarations of 1 trait.
 *
 * Discovery goes through the reader the runtime uses. The generator therefore
 * rejects a malformed declaration with the same message rather than
 * documenting an incomplete option table.
 *
 * @param string $class_name
 *   The context class composing the trait.
 * @param string $trait_name
 *   The short trait name.
 *
 * @return array<string, \DrevOps\BehatSteps\Extension\Config\Option>
 *   Options keyed by name, empty when the trait declares none.
 */
function extract_trait_options(string $class_name, string $trait_name): array {
  return (new ConfigSchemaReader())->read($class_name)[trait_option_group($trait_name)] ?? [];
}

/**
 * Convert a trait name to the group its options are configured under.
 *
 * @param string $trait_name
 *   The short trait name.
 *
 * @return string
 *   The group name, in snake case.
 */
function trait_option_group(string $trait_name): string {
  return GroupName::fromTraitName($trait_name);
}

/**
 * Read the prerequisite declarations of 1 trait.
 *
 * Discovery goes through the reader the runtime uses, so the generator rejects
 * a malformed declaration with the same message.
 *
 * @param string $class_name
 *   The context class composing the trait.
 * @param string $trait
 *   The fully qualified trait name.
 *
 * @return array<int, \DrevOps\BehatSteps\Extension\Prerequisite\Prerequisite>
 *   The prerequisites in declaration order, empty when the trait declares
 *   none.
 */
function extract_trait_prerequisites(string $class_name, string $trait): array {
  /** @var class-string $class_name */
  $context = (new \ReflectionClass($class_name))->newInstanceWithoutConstructor();

  return (new PrerequisiteReader())->read($context, $trait);
}

/**
 * Parse class comment.
 *
 * @param string $trait_name
 *   The trait name.
 * @param string $comment
 *   The comment.
 *
 * @return array<string, string>
 *   Array of 'description' and 'description_full' keys, and a 'title' key
 *   when the comment declares one.
 *
 * @throws \RuntimeException
 *   When the comment is empty or malformed, or its title is empty or
 *   repeated.
 */
function parse_class_comment(string $trait_name, string $comment): array {
  if (empty($comment)) {
    throw new \RuntimeException(sprintf('Class comment for %s is empty', $trait_name));
  }

  $comment = preg_replace('#^/\*\*|^\s*\*\/$#m', '', $comment);
  $lines = explode("\n", (string) $comment);
  // Strips the docblock asterisk and at most 1 space, so any further
  // indentation is preserved.
  $lines = array_map(static fn(string $line): string => preg_replace('/^\s*\* ?/', '', $line), $lines);

  if (count($lines) > 1 && empty($lines[0])) {
    array_shift($lines);
  }

  if (count($lines) > 1 && empty($lines[count($lines) - 1])) {
    array_pop($lines);
  }

  $in_code_block = FALSE;
  $lines = array_map(static function (string $line) use (&$in_code_block): string {
    if (str_starts_with(trim($line), '@code')) {
      $in_code_block = TRUE;
      return trim($line);
    }

    if (str_starts_with(trim($line), '@endcode')) {
      $in_code_block = FALSE;
      return trim($line);
    }

    if ($in_code_block) {
      return rtrim($line);
    }

    return trim($line);
  }, $lines);

  // Static-analysis annotations state the trait's contract for tooling, not
  // for the reader of the generated documentation.
  $lines = array_values(array_filter($lines, static fn(string $line): bool => !str_starts_with($line, '@phpstan-')));

  // The title names the class's pages on the documentation site, so it is
  // not part of the description.
  $titles = array_values(array_filter($lines, static fn(string $line): bool => preg_match('/^@title\b/', $line) === 1));
  $lines = array_values(array_filter($lines, static fn(string $line): bool => preg_match('/^@title\b/', $line) !== 1));

  if (count($titles) > 1) {
    throw new \RuntimeException(sprintf('Class comment for %s has more than 1 title', $trait_name));
  }

  $title = $titles === [] ? NULL : trim(substr($titles[0], strlen('@title')));

  if ($title === '') {
    throw new \RuntimeException(sprintf('Class comment for %s has an empty title', $trait_name));
  }

  while ($lines !== [] && end($lines) === '') {
    array_pop($lines);
  }

  if (empty($lines)) {
    throw new \RuntimeException(sprintf('Class comment for %s is empty', $trait_name));
  }

  $description = $lines[0];

  if (empty($description)) {
    throw new \RuntimeException(sprintf('Class comment for %s is empty', $trait_name));
  }

  if (str_starts_with($description, 'Trait ')) {
    throw new \RuntimeException(sprintf('Class comment should have a descriptive content for %s', $trait_name));
  }

  $full_description = implode(PHP_EOL, $lines);

  if (substr_count($full_description, '`') % 2 !== 0) {
    throw new \RuntimeException(sprintf('Class inline code block is not closed for %s', $trait_name));
  }

  $parsed = [
    'description' => $description,
    'description_full' => $full_description,
  ];

  return $title === NULL ? $parsed : $parsed + ['title' => $title];
}

/**
 * Parse comment.
 *
 * Extracts description, example and the "@actor" tag from the docblock
 * comment. A tag inside the example is part of the example.
 *
 * @param string $comment
 *   The comment.
 *
 * @return array<string, string>|null
 *   Array of 'description' and 'example' keys, plus 'actor' when the comment
 *   declares one, or NULL if the comment is empty.
 *
 * @throws \RuntimeException
 *   When the example is not closed, or the actor tag is unknown or repeated.
 */
function parse_method_comment(string $comment): ?array {
  if (empty($comment)) {
    return NULL;
  }

  $return = [
    'description' => '',
    'example' => '',
  ];

  $lines = explode("\n", $comment);

  $example_start = FALSE;

  foreach ($lines as $line) {
    $line = str_replace('/*', '', $line);
    $line = str_replace('/**', '', $line);
    $line = str_replace('*/', '', $line);
    $line = preg_replace('/^\s*\*/', '', $line);
    $line = rtrim((string) $line, " \t\n\r\0\x0B");
    // All docblock lines start with a space.
    $line = substr($line, 1);

    if (str_starts_with($line, '@code')) {
      $example_start = TRUE;
    }
    elseif (str_starts_with($line, '@endcode')) {
      $example_start = FALSE;
    }
    elseif (!$example_start && str_starts_with($line, '@actor')) {
      $actor = substr($line, strlen('@actor:'));

      if (!str_starts_with($line, '@actor:') || !in_array($actor, STEP_ACTORS, TRUE)) {
        throw new \RuntimeException(sprintf('Unknown actor tag "%s". Use "@actor:%s".', $line, implode('" or "@actor:', STEP_ACTORS)));
      }

      if (isset($return['actor'])) {
        throw new \RuntimeException(sprintf('Repeated actor tag "%s". A step has 1 actor.', $line));
      }

      $return['actor'] = $actor;
    }
    else {
      if (!$example_start && empty($line)) {
        continue;
      }

      if ($example_start) {
        $line = rtrim($line, "\t\n\r\0\x0B");
        $return['example'] .= $line . PHP_EOL;
      }

      if (empty($return['description'])) {
        $line = trim($line);
        $return['description'] .= $line . ' ';
      }
    }
  }

  if ($example_start) {
    throw new \RuntimeException('Example not closed');
  }

  $return['description'] = trim($return['description']);

  if (!empty($return['example'])) {
    $lines = explode(PHP_EOL, $return['example']);
    $first_line = '';

    foreach ($lines as $line) {
      if ($line !== '') {
        $first_line = $line;
        break;
      }
    }

    $indentation = strspn($first_line, ' ');

    foreach ($lines as $key => $line) {
      $line = rtrim($line);

      if (strlen($line) > $indentation) {
        $lines[$key] = substr($line, $indentation);
      }
    }

    $return['example'] = implode(PHP_EOL, $lines);
  }

  return $return;
}

/**
 * Extract step patterns from method attributes.
 *
 * @param \ReflectionMethod $method
 *   The reflection method.
 *
 * @return array<int, string>
 *   Array of step patterns prefixed with @Given, @When, or @Then.
 */
function extract_method_steps(\ReflectionMethod $method): array {
  $step_classes = [
    Given::class => '@Given',
    When::class => '@When',
    Then::class => '@Then',
  ];

  $steps = [];

  foreach ($step_classes as $class => $prefix) {
    $attributes = $method->getAttributes($class);

    foreach ($attributes as $attribute) {
      $args = $attribute->getArguments();
      $pattern = $args[0] ?? $args['pattern'] ?? NULL;

      if ($pattern !== NULL) {
        $steps[] = $prefix . ' ' . $pattern;
      }
    }
  }

  $sorted = [];

  foreach (['@Given', '@When', '@Then'] as $step_prefix) {
    foreach ($steps as $step) {
      if (str_starts_with($step, $step_prefix)) {
        $sorted[] = $step;
      }
    }
  }

  return $sorted;
}

/**
 * Check whether a step method takes a table.
 *
 * A step taking a table and one taking a block of text both end with a colon.
 * The type of the last parameter therefore tells them apart.
 *
 * @param \ReflectionMethod $method
 *   The reflection method.
 *
 * @return bool
 *   TRUE when the last parameter is a table.
 */
function method_takes_table(\ReflectionMethod $method): bool {
  $parameters = $method->getParameters();

  if ($parameters === []) {
    return FALSE;
  }

  $type = end($parameters)->getType();

  return $type instanceof \ReflectionNamedType && $type->getName() === TableNode::class;
}

/**
 * Check whether a method is registered with Behat.
 *
 * @param \ReflectionMethod $method
 *   The reflection method.
 *
 * @return bool
 *   TRUE when the method carries a step, hook or transformation attribute.
 */
function method_is_registered(\ReflectionMethod $method): bool {
  foreach ($method->getAttributes() as $attribute) {
    foreach (REGISTERED_ATTRIBUTE_PREFIXES as $prefix) {
      if (str_starts_with($attribute->getName(), $prefix)) {
        return TRUE;
      }
    }
  }

  return FALSE;
}

/**
 * Check whether a docblock excludes the member from the published API.
 *
 * @param string $comment
 *   The docblock comment.
 *
 * @return bool
 *   TRUE when the comment carries an '@internal' tag.
 */
function comment_is_internal(string $comment): bool {
  return preg_match('/^\s*\*\s*@internal\b/m', $comment) === 1;
}

/**
 * Render a type declaration as it reads in a signature.
 *
 * @param \ReflectionType|null $type
 *   The reflection type, or NULL when the declaration has none.
 *
 * @return string
 *   The type with class names shortened, or an empty string when untyped.
 */
function render_type(?\ReflectionType $type): string {
  $short = static function (string $name): string {
    $position = strrpos($name, '\\');

    return $position === FALSE ? $name : substr($name, $position + 1);
  };

  if ($type instanceof \ReflectionNamedType) {
    $name = $short($type->getName());
    $is_nullable = $type->allowsNull() && !in_array($name, ['mixed', 'null'], TRUE);

    return ($is_nullable ? '?' : '') . $name;
  }

  if ($type instanceof \ReflectionUnionType || $type instanceof \ReflectionIntersectionType) {
    $glue = $type instanceof \ReflectionUnionType ? '|' : '&';
    $parts = array_map(render_type(...), $type->getTypes());

    return implode($glue, $parts);
  }

  return '';
}

/**
 * Render a value as it reads in PHP source.
 *
 * @param mixed $value
 *   The value.
 *
 * @return string
 *   The rendered value.
 */
function render_value(mixed $value): string {
  if ($value === NULL) {
    return 'NULL';
  }

  if (is_bool($value)) {
    return $value ? 'TRUE' : 'FALSE';
  }

  if (is_array($value)) {
    return $value === [] ? '[]' : '[...]';
  }

  if (is_string($value)) {
    return "'" . $value . "'";
  }

  return is_scalar($value) ? (string) $value : 'object';
}

/**
 * Render a trait's option declarations as a markdown table.
 *
 * @param string $trait_name
 *   The short trait name.
 * @param mixed $options
 *   The options the trait declared, keyed by option name.
 *
 * @return string
 *   The table, or an empty string when the trait declares no option.
 */
function render_trait_options(string $trait_name, mixed $options): string {
  $group = trait_option_group($trait_name);
  $rows = [];

  foreach (is_array($options) ? $options : [] as $option) {
    if (!$option instanceof Option) {
      continue;
    }

    $tags = array_keys($option->tags);

    if ($option->name === Option::ENABLED) {
      $tags[] = TagOverrideResolver::SKIP_TAG_PREFIX . $trait_name;
    }

    $tags = array_map(static fn(string $tag): string => '`@' . $tag . '`', $tags);

    $rows[] = [
      sprintf('`%s.%s`', $group, $option->name),
      trait_option_type($option->default),
      sprintf('`%s`', render_value($option->default)),
      $tags === [] ? '-' : implode(', ', $tags),
      str_replace('|', '\\|', $option->description),
    ];
  }

  return array_to_markdown_table(['Option', 'Type', 'Default', 'Tag', 'Description'], $rows);
}

/**
 * Render a trait's prerequisite declarations as a markdown table.
 *
 * @param mixed $prerequisites
 *   The prerequisites the trait declared, in declaration order.
 *
 * @return string
 *   The table, or an empty string when the trait declares none.
 */
function render_trait_prerequisites(mixed $prerequisites): string {
  $rows = [];

  foreach (is_array($prerequisites) ? $prerequisites : [] as $prerequisite) {
    if (!$prerequisite instanceof Prerequisite) {
      continue;
    }

    $rows[] = [
      str_replace('|', '\\|', ucfirst($prerequisite->description)),
      sprintf('`%s`', basename(str_replace('\\', '/', $prerequisite->capability))),
    ];
  }

  return array_to_markdown_table(['Prerequisite', 'Capability'], $rows);
}

/**
 * Name the type of an option, taken from the type its default carries.
 *
 * @param mixed $default
 *   The declared default.
 *
 * @return string
 *   The type name, in the vocabulary the configuration reference uses.
 */
function trait_option_type(mixed $default): string {
  return match (get_debug_type($default)) {
    'bool' => 'boolean',
    'int' => 'integer',
    'float' => 'float',
    'array' => 'map',
    default => 'string',
  };
}

/**
 * Render a method signature.
 *
 * @param \ReflectionMethod $method
 *   The reflection method.
 *
 * @return string
 *   The signature, with class names shortened to their class part.
 */
function render_method_signature(\ReflectionMethod $method): string {
  $parameters = [];

  foreach ($method->getParameters() as $parameter) {
    $type = render_type($parameter->getType());
    $rendered = $type === '' ? '' : $type . ' ';
    $rendered .= ($parameter->isVariadic() ? '...' : '') . '$' . $parameter->getName();

    if ($parameter->isDefaultValueAvailable()) {
      $rendered .= ' = ' . render_value($parameter->getDefaultValue());
    }

    $parameters[] = $rendered;
  }

  $return = render_type($method->getReturnType());

  return sprintf(
    '%s%s function %s(%s)%s',
    $method->isPublic() ? 'public' : 'protected',
    $method->isStatic() ? ' static' : '',
    $method->getName(),
    implode(', ', $parameters),
    $return === '' ? '' : ': ' . $return
  );
}

/**
 * Render the anchor a trait heading resolves to.
 *
 * @param string $name
 *   The contextual trait name, such as 'Drupal\ContentTrait'.
 *
 * @return string
 *   The anchor, without the leading hash.
 */
function heading_anchor(string $name): string {
  return (string) preg_replace('/[^A-Za-z0-9_\-]/', '', strtolower($name));
}

/**
 * Parse the helpers from the classes.
 *
 * A helper is a public method a project calls from its own domain steps: one
 * carrying no Behat attribute and no '@internal' tag.
 *
 * @param array<int, class-string> $class_names
 *   The classes documenting the vocabulary, 1 per context.
 * @param array<int, string> $exclude
 *   Array of trait names to exclude.
 * @param string $base_path
 *   Base path for the repository.
 *
 * @return array<string, array<string, mixed>>
 *   Array of info with 'name', 'name_contextual', 'class', 'context',
 *   'source', 'steps_anchor', 'helpers', 'description' and 'description_full'
 *   keys, and a 'title' key when the class declares one, keyed by short name.
 *   Traits contributing no helper are left out.
 *
 * @throws \ReflectionException
 */
function extract_helpers(array $class_names, array $exclude = [], string $base_path = __DIR__): array {
  $info = [];

  foreach (collect_step_traits($class_names, $exclude, $base_path) as $trait_name => $collected) {
    $trait = $collected['reflection'];
    $context = $collected['context'];

    $helpers = collect_helper_methods($trait, str_replace('Trait', '', $trait_name), (string) $trait->getFileName());

    if ($helpers === []) {
      continue;
    }

    $name_contextual = ($context !== DEFAULT_CONTEXT ? $context . '\\' : '') . $trait_name;

    $class_info = [
      'name' => $trait_name,
      'name_contextual' => $name_contextual,
      'class' => $trait->getName(),
      'context' => $context,
      'source' => sprintf('%s/%s/%s.php', STEPS_DIRECTORY, $context, $trait_name),
      'steps_anchor' => heading_anchor($name_contextual),
      'helpers' => $helpers,
    ];
    $class_info += parse_class_comment($trait_name, (string) $trait->getDocComment());

    $info[$trait_name] = $class_info;
  }

  foreach (collect_helper_traits($base_path) as $trait_name => $collected) {
    $trait = $collected['reflection'];
    $context = $collected['context'];
    $helpers = collect_helper_methods($trait, NULL, (string) $trait->getFileName(), helper_trait_contracts($trait, $class_names));

    if ($helpers === []) {
      continue;
    }

    $name_contextual = ($context !== DEFAULT_CONTEXT ? $context . '\\' : '') . $trait_name;
    $class_info = [
      'name' => $trait_name,
      'name_contextual' => $name_contextual,
      'class' => $trait->getName(),
      'context' => $context,
      'source' => sprintf('%s/%s/%s.php', HELPERS_DIRECTORY, $context, $trait_name),
      'steps_anchor' => NULL,
      'helpers' => $helpers,
    ];
    $class_info += parse_class_comment($trait_name, (string) $trait->getDocComment());

    $info[$trait_name] = $class_info;
  }

  foreach (HELPER_CLASSES as $helper_class) {
    $reflection = new \ReflectionClass($helper_class);
    $short_name = $reflection->getShortName();

    // A composed helper trait is published under its own name, so the context
    // reports only what its own file declares.
    $helpers = collect_helper_methods($reflection, NULL, (string) $reflection->getFileName());

    // @codeCoverageIgnoreStart
    if ($helpers === []) {
      continue;
    }

    // @codeCoverageIgnoreEnd
    $class_info = [
      'name' => $short_name,
      'name_contextual' => $short_name,
      'class' => $reflection->getName(),
      'context' => HELPER_CLASSES_CONTEXT,
      'source' => relative_source_path((string) $reflection->getFileName(), $base_path),
      'steps_anchor' => NULL,
      'helpers' => $helpers,
    ];
    $class_info += parse_class_comment($short_name, (string) $reflection->getDocComment());

    $info[$short_name] = $class_info;
  }

  return $info;
}

/**
 * List the contracts the classes composing a helper trait declare.
 *
 * A trait cannot implement an interface, so the class composing it declares
 * the contract instead. A trait method carrying '{@inheritdoc}' is documented
 * on that interface rather than on the trait.
 *
 * @param \ReflectionClass<object> $trait
 *   The helper trait.
 * @param array<int, class-string> $class_names
 *   The classes documenting the vocabulary.
 *
 * @return array<int, \ReflectionClass<object>>
 *   The interfaces of every given class composing the trait.
 *
 * @throws \ReflectionException
 */
function helper_trait_contracts(\ReflectionClass $trait, array $class_names): array {
  $contracts = [];

  foreach ($class_names as $class_name) {
    $reflection = new \ReflectionClass($class_name);

    if (!composes_trait($reflection, $trait->getName())) {
      continue;
    }

    foreach ($reflection->getInterfaces() as $interface) {
      $contracts[$interface->getName()] = $interface;
    }
  }

  return array_values($contracts);
}

/**
 * Determine whether a class reaches a trait through any depth of composition.
 *
 * 'getTraits()' reports only what a class composes itself, and a helper trait
 * is composed by the step trait that uses it.
 *
 * @param \ReflectionClass<object> $reflection
 *   The class or trait to walk.
 * @param string $trait_name
 *   Fully qualified name of the trait to look for.
 *
 * @return bool
 *   TRUE when the trait is composed at any depth.
 */
function composes_trait(\ReflectionClass $reflection, string $trait_name): bool {
  foreach ($reflection->getTraits() as $composed) {
    if ($composed->getName() === $trait_name || composes_trait($composed, $trait_name)) {
      return TRUE;
    }
  }

  $parent = $reflection->getParentClass();

  return $parent instanceof \ReflectionClass && composes_trait($parent, $trait_name);
}

/**
 * Collect the helpers a class or trait contributes.
 *
 * Visibility is the marker: a public method that Behat does not register and
 * that carries no '@internal' tag is a helper. A protected method
 * is an implementation detail with no contract to a consuming project.
 *
 * @param \ReflectionClass<object> $reflection
 *   The class or trait reflection.
 * @param string|null $prefix
 *   Method name prefix to require, or NULL to take every method the class
 *   declares itself.
 * @param string|null $source_file
 *   Absolute path a method has to be declared in, or NULL to accept any. A
 *   method flattened in from a trait keeps the trait's file name.
 * @param array<int, \ReflectionClass<object>> $contracts
 *   Interfaces to resolve an inherited docblock against. A trait declares no
 *   interface of its own, so its contract has to be named from outside.
 *
 * @return array<int, array<string, string>>
 *   Helper entries with 'name', 'signature', 'description' and 'example',
 *   sorted by name.
 */
function collect_helper_methods(\ReflectionClass $reflection, ?string $prefix = NULL, ?string $source_file = NULL, array $contracts = []): array {
  $helpers = [];

  foreach ($reflection->getMethods(\ReflectionMethod::IS_PUBLIC) as $method) {
    if ($source_file !== NULL && $method->getFileName() !== $source_file) {
      continue;
    }

    if ($prefix === NULL) {
      if ($method->getDeclaringClass()->getName() !== $reflection->getName()) {
        continue;
      }
    }
    elseif (!str_starts_with(strtolower($method->getName()), strtolower($prefix))) {
      continue;
    }

    if (method_is_registered($method)) {
      continue;
    }

    $comment = resolve_inherited_comment($method, $contracts);

    if (comment_is_internal($comment)) {
      continue;
    }

    $parsed_comment = parse_method_comment($comment);
    $helpers[] = [
      'name' => $method->getName(),
      'signature' => render_method_signature($method),
      'description' => $parsed_comment['description'] ?? '',
      'example' => $parsed_comment['example'] ?? '',
    ];
  }

  usort($helpers, static fn(array $a, array $b): int => strcmp($a['name'], $b['name']));

  return $helpers;
}

/**
 * Read a method's docblock, following '{@inheritdoc}' to its declaration.
 *
 * @param \ReflectionMethod $method
 *   The reflection method.
 * @param array<int, \ReflectionClass<object>> $contracts
 *   Further classes or interfaces to search after the parent class, ahead of
 *   the interfaces the declaring class states itself.
 *
 * @return string
 *   The docblock that carries the description, or the method's own when the
 *   declaration it inherits from has none.
 */
function resolve_inherited_comment(\ReflectionMethod $method, array $contracts = []): string {
  $comment = (string) $method->getDocComment();

  if (stripos($comment, '{@inheritdoc}') === FALSE) {
    return $comment;
  }

  $declaring = $method->getDeclaringClass();
  $candidates = array_merge($contracts, array_values($declaring->getInterfaces()));

  $parent = $declaring->getParentClass();

  if ($parent instanceof \ReflectionClass) {
    array_unshift($candidates, $parent);
  }

  foreach ($candidates as $candidate) {
    if (!$candidate->hasMethod($method->getName())) {
      continue;
    }

    $inherited = (string) $candidate->getMethod($method->getName())->getDocComment();

    if ($inherited !== '' && stripos($inherited, '{@inheritdoc}') === FALSE) {
      return $inherited;
    }
  }

  return $comment;
}

/**
 * Express a source file path relative to the repository it belongs to.
 *
 * @param string $file_path
 *   Absolute path to the file.
 * @param string $base_path
 *   Base path for the repository being documented.
 *
 * @return string
 *   The path relative to the repository root, or unchanged when it sits
 *   outside both the documented repository and this one.
 */
function relative_source_path(string $file_path, string $base_path = __DIR__): string {
  foreach ([$base_path, __DIR__] as $root) {
    if (str_starts_with($file_path, $root . DIRECTORY_SEPARATOR)) {
      return substr($file_path, strlen($root) + 1);
    }
  }

  return $file_path;
}

/**
 * Render the path of a link from one repository file to another.
 *
 * @param string $from_file
 *   The file holding the link, relative to the repository root.
 * @param string $to_path
 *   The link target, relative to the repository root.
 *
 * @return string
 *   The target's path relative to the directory of the linking file.
 */
function relative_link(string $from_file, string $to_path): string {
  $directory = dirname($from_file);
  $from = $directory === '.' ? [] : explode('/', $directory);
  $to = explode('/', $to_path);

  // The last segment of the target stays, so the link always names it.
  while ($from !== [] && count($to) > 1 && $from[0] === $to[0]) {
    array_shift($from);
    array_shift($to);
  }

  return str_repeat('../', count($from)) . implode('/', $to);
}

/**
 * Render the paragraph opening a reference that points at the step skill.
 *
 * @param string $from_file
 *   The reference holding the paragraph, relative to the repository root.
 *
 * @return string
 *   The paragraph, followed by a blank line.
 */
function render_step_skill_link(string $from_file): string {
  $link = sprintf('[%s](%s)', STEP_SKILL_FILE, relative_link($from_file, STEP_SKILL_FILE));

  return sprintf('When no step says what a scenario needs, an AI coding agent can write a step of your own on the helpers with the `%s` skill, in %s.', basename(dirname(STEP_SKILL_FILE)), $link) . PHP_EOL . PHP_EOL;
}

/**
 * Convert info to content.
 *
 * @param array<string, array<string, mixed>> $info
 *   The extracted trait info from extract_info().
 * @param string $base_path
 *   Base path for the repository.
 *
 * @return string
 *   The index table of each context, followed by a horizontal rule and every
 *   trait's section.
 */
function render_info(array $info, string $base_path = __DIR__): string {
  $sections = [];

  foreach ($info as $trait => $class_info) {
    $context = (string) $class_info['context'];
    $sections[$context] ??= '';
    $sections[$context] .= render_step_section((string) $trait, $class_info, $base_path);
  }

  $index = render_step_index($info, static fn(array $class_info): string => '#' . heading_anchor((string) $class_info['name_contextual']));

  return $index . PHP_EOL . '---' . PHP_EOL . PHP_EOL . implode(PHP_EOL . PHP_EOL, context_first($sections, '')) . PHP_EOL;
}

/**
 * Render the index of the step traits, 1 table per context.
 *
 * @param array<string, array<string, mixed>> $info
 *   The extracted trait info from extract_info().
 * @param callable(array<string, mixed>): string $link
 *   Returns the link target of a trait's row.
 *
 * @return string
 *   The table of each context under its heading, the generic context's first.
 */
function render_step_index(array $info, callable $link): string {
  $rows = [];

  foreach ($info as $class_info) {
    $rows[(string) $class_info['context']][] = [
      sprintf('[%s](%s)', $class_info['name_contextual'], $link($class_info)),
      (string) $class_info['description'],
    ];
  }

  $output = '';

  foreach (context_first($rows, []) as $context => $context_rows) {
    $output .= sprintf('## Index of %s steps', $context) . PHP_EOL . PHP_EOL;
    $output .= array_to_markdown_table(['Class', 'Description'], $context_rows) . PHP_EOL . PHP_EOL;
  }

  return $output;
}

/**
 * Render a trait's section of the step reference.
 *
 * The headings name the trait, so a search result or a link that lands on one
 * of them says which trait it belongs to.
 *
 * @param string $trait
 *   The short trait name.
 * @param array<string, mixed> $class_info
 *   The trait info from extract_info().
 * @param string $base_path
 *   Base path for the repository.
 *
 * @return string
 *   The section, from the trait's heading to its last step.
 */
function render_step_section(string $trait, array $class_info, string $base_path): string {
  $name_contextual = (string) $class_info['name_contextual'];

  $output = sprintf('## %s', $name_contextual) . PHP_EOL . PHP_EOL;
  $output .= render_step_links($trait, $class_info, STEPS_FILE, $base_path) . PHP_EOL . PHP_EOL;
  $output .= render_class_description((string) $class_info['description_full']) . PHP_EOL . PHP_EOL;
  $output .= render_titled(sprintf('### %s prerequisites', $name_contextual), render_trait_prerequisites($class_info['prerequisites'] ?? []));
  $output .= render_titled(sprintf('### %s options', $name_contextual), render_trait_options($trait, $class_info['options'] ?? []));

  return $output . render_step_details(is_array($class_info['methods'] ?? NULL) ? $class_info['methods'] : []);
}

/**
 * Render the documentation site's page of each step trait.
 *
 * @param array<string, array<string, mixed>> $info
 *   The extracted trait info from extract_info().
 * @param array<string, array<string, mixed>> $helpers
 *   The helper info from extract_helpers(), so a trait with helpers links to
 *   its section of the helper reference.
 * @param string $base_path
 *   Base path for the repository.
 *
 * @return array<string, string>
 *   The contents of each page, keyed by its path relative to the repository
 *   root.
 */
function render_step_pages(array $info, array $helpers, string $base_path = __DIR__): array {
  $pages = [];
  $positions = page_positions($info);

  foreach ($info as $trait => $class_info) {
    $trait = (string) $trait;
    $context = (string) $class_info['context'];
    $title = (string) $class_info['title'];
    $page = reference_page($context, $trait);

    $links = render_step_links($trait, $class_info, $page, $base_path);

    if (($helpers[$trait]['context'] ?? NULL) === $context) {
      $links .= sprintf(', [Helpers](%s#%s)', relative_link($page, HELPERS_FILE), heading_anchor((string) $helpers[$trait]['name_contextual']));
    }

    $output = render_front_matter([
      'title' => sprintf('%s - %s steps', $title, $context),
      'sidebar_label' => $title,
      'sidebar_position' => $positions[$trait],
      'description' => str_replace('`', '', (string) $class_info['description']),
      'custom_edit_url' => NULL,
    ]) . PHP_EOL;
    $output .= '# ' . $title . PHP_EOL . PHP_EOL;
    $output .= sprintf('`%s` - %s', $class_info['class'], $links) . PHP_EOL . PHP_EOL;
    $output .= rtrim(render_class_description((string) $class_info['description_full'])) . PHP_EOL . PHP_EOL;
    $output .= render_titled('## Prerequisites', render_trait_prerequisites($class_info['prerequisites'] ?? []));
    $output .= render_titled('## Options', render_trait_options($trait, $class_info['options'] ?? []));
    $output .= render_titled('## Steps', rtrim(render_step_details(is_array($class_info['methods'] ?? NULL) ? $class_info['methods'] : [])));

    $pages[$page] = rtrim($output) . PHP_EOL;
  }

  return $pages;
}

/**
 * Render the links of a trait to its source and its example feature.
 *
 * @param string $trait
 *   The short trait name.
 * @param array<string, mixed> $class_info
 *   The trait info from extract_info().
 * @param string $from_file
 *   The file holding the links, relative to the repository root.
 * @param string $base_path
 *   Base path for the repository.
 *
 * @return string
 *   The links, separated by commas.
 *
 * @throws \RuntimeException
 *   When the source or the example feature does not exist.
 */
function render_step_links(string $trait, array $class_info, string $from_file, string $base_path): string {
  $context = (string) $class_info['context'];
  $src_file = sprintf('%s/%s/%s.php', STEPS_DIRECTORY, $context, $trait);

  if (!file_exists($base_path . '/' . $src_file)) {
    throw new \RuntimeException(sprintf('Source file %s does not exist', $base_path . '/' . $src_file));
  }

  $prefix = $context !== DEFAULT_CONTEXT ? strtolower($context) . '_' : '';
  $example_file = sprintf('tests/behat/features/%s%s.feature', $prefix, camel_to_snake(str_replace('Trait', '', $trait)));

  if (!file_exists($base_path . '/' . $example_file)) {
    throw new \RuntimeException(sprintf('Example file %s does not exist', $base_path . '/' . $example_file));
  }

  return sprintf('[Source](%s), [Example](%s)', relative_link($from_file, $src_file), relative_link($from_file, $example_file));
}

/**
 * Render a class description as a blockquote.
 *
 * A '@code' block becomes a fenced block, and an empty line becomes 2 line
 * breaks, except before a list.
 *
 * @param string $description_full
 *   The full class description from parse_class_comment().
 *
 * @return string
 *   The description, with every line quoted.
 */
function render_class_description(string $description_full): string {
  $output = '';
  $was_list = FALSE;
  $in_code_block = FALSE;
  $code_block = '';

  foreach (explode(PHP_EOL, $description_full) as $line) {
    $trimmed_line = trim($line);

    if (str_starts_with($trimmed_line, '@code')) {
      $in_code_block = TRUE;
      $code_block = '';
      continue;
    }

    if (str_starts_with($trimmed_line, '@endcode')) {
      $in_code_block = FALSE;
      $output .= '```' . PHP_EOL;
      $output .= rtrim($code_block) . PHP_EOL;
      $output .= '```' . PHP_EOL;
      $code_block = '';
      continue;
    }

    if ($in_code_block) {
      $code_block .= $line . PHP_EOL;
      continue;
    }

    $is_list = str_starts_with($trimmed_line, '-');

    if (!$is_list) {
      if (empty($line) && !$was_list) {
        $output .= $line . '<br/><br/>' . PHP_EOL;
      }
      else {
        $output .= $line . PHP_EOL;
      }

      $was_list = FALSE;
    }
    else {
      $break = '<br/><br/>' . PHP_EOL;

      if (str_ends_with($output, $break)) {
        $output = substr($output, 0, -strlen($break));
      }

      $output .= $line . PHP_EOL;
      $was_list = TRUE;
    }
  }

  return (string) preg_replace('/^/m', '>  ', $output);
}

/**
 * Render each step method of a trait as a collapsible block.
 *
 * @param array<int|string, mixed> $methods
 *   The trait's step methods from extract_info().
 *
 * @return string
 *   1 block per method, with its steps, its description and its example.
 */
function render_step_details(array $methods): string {
  $output = '';

  foreach ($methods as $method) {
    $steps = is_array($method['steps']) ? $method['steps'] : [$method['steps']];
    $description = is_string($method['description']) ? $method['description'] : '';
    $example = is_string($method['example']) ? $method['example'] : '';

    $template = <<<EOT
<details>
  <summary><code>[step]</code></summary>

<br/>
[description]
<br/><br/>

```gherkin
[example]
```

</details>

EOT;

    $output .= strtr($template, [
      '[description]' => rtrim($description, '.'),
      '[step]' => implode("\n", $steps),
      '[example]' => rtrim($example),
    ]) . PHP_EOL;
  }

  return $output;
}

/**
 * Convert helper info to content.
 *
 * @param array<string, array<string, mixed>> $info
 *   Array of helper info items from extract_helpers().
 * @param string $base_path
 *   Base path for the repository.
 *
 * @return string
 *   Markdown content.
 */
function render_helpers(array $info, string $base_path = __DIR__): string {
  $sections = [];

  foreach ($info as $class_info) {
    $context = (string) $class_info['context'];
    $sections[$context] ??= '';
    $sections[$context] .= render_helper_section($class_info, $base_path);
  }

  $output = render_helper_index($info, static fn(array $class_info): string => '#' . heading_anchor((string) $class_info['name_contextual']));
  $output .= '---' . PHP_EOL . PHP_EOL;
  $output .= implode('', context_first($sections, ''));

  return rtrim($output) . PHP_EOL;
}

/**
 * Render the index of the classes contributing helpers, 1 table per context.
 *
 * @param array<string, array<string, mixed>> $info
 *   Array of helper info items from extract_helpers().
 * @param callable(array<string, mixed>): string $link
 *   Returns the link target of a class's row.
 *
 * @return string
 *   The table of each context under its heading, the generic context's first.
 */
function render_helper_index(array $info, callable $link): string {
  $rows = [];

  foreach ($info as $class_info) {
    $rows[(string) $class_info['context']][] = [
      sprintf('[%s](%s)', $class_info['name_contextual'], $link($class_info)),
      (string) count(is_array($class_info['helpers']) ? $class_info['helpers'] : []),
      (string) $class_info['description'],
    ];
  }

  $output = '';

  foreach (context_first($rows, []) as $context => $context_rows) {
    $output .= sprintf('## Index of %s helpers', $context) . PHP_EOL . PHP_EOL;
    $output .= array_to_markdown_table(['Class', 'Helpers', 'Description'], $context_rows) . PHP_EOL . PHP_EOL;
  }

  return $output;
}

/**
 * Render a class's section of the helper reference.
 *
 * @param array<string, mixed> $class_info
 *   The helper info of the class from extract_helpers().
 * @param string $base_path
 *   Base path for the repository.
 *
 * @return string
 *   The section, from the class's heading to its last helper.
 */
function render_helper_section(array $class_info, string $base_path): string {
  $steps_anchor = $class_info['steps_anchor'] ?? NULL;
  $steps_link = is_string($steps_anchor) ? relative_link(HELPERS_FILE, STEPS_FILE) . '#' . $steps_anchor : NULL;

  $output = sprintf('## %s', $class_info['name_contextual']) . PHP_EOL . PHP_EOL;
  $output .= render_helper_links($class_info, HELPERS_FILE, $steps_link, $base_path) . PHP_EOL . PHP_EOL;
  $output .= '> ' . $class_info['description'] . PHP_EOL . PHP_EOL;

  return $output . render_helper_details(is_array($class_info['helpers']) ? $class_info['helpers'] : []);
}

/**
 * Render the links of a class to its source and to its steps.
 *
 * @param array<string, mixed> $class_info
 *   The helper info of the class from extract_helpers().
 * @param string $from_file
 *   The file holding the links, relative to the repository root.
 * @param string|null $steps_link
 *   The link target of the class's steps, or NULL when it has none.
 * @param string $base_path
 *   Base path for the repository.
 *
 * @return string
 *   The links, separated by commas.
 *
 * @throws \RuntimeException
 *   When the source does not exist.
 */
function render_helper_links(array $class_info, string $from_file, ?string $steps_link, string $base_path): string {
  $src_file = (string) $class_info['source'];

  if (!file_exists($base_path . '/' . $src_file)) {
    throw new \RuntimeException(sprintf('Source file %s does not exist', $base_path . '/' . $src_file));
  }

  $links = sprintf('[Source](%s)', relative_link($from_file, $src_file));

  return $steps_link === NULL ? $links : $links . sprintf(', [Steps](%s)', $steps_link);
}

/**
 * Render each helper of a class as a collapsible block.
 *
 * @param array<int|string, mixed> $helpers
 *   The helpers of the class from extract_helpers().
 *
 * @return string
 *   1 block per helper, with its signature, its description and its example.
 */
function render_helper_details(array $helpers): string {
  $output = '';

  foreach ($helpers as $helper) {
    $example = (string) $helper['example'];

    $output .= '<details>' . PHP_EOL;
    $output .= sprintf('  <summary><code>%s</code></summary>', (string) $helper['signature']) . PHP_EOL . PHP_EOL;
    $output .= '<br/>' . PHP_EOL;
    $output .= rtrim((string) $helper['description'], '.') . PHP_EOL;
    $output .= '<br/><br/>' . PHP_EOL . PHP_EOL;

    if ($example !== '') {
      $output .= '```' . PHP_EOL . rtrim($example) . PHP_EOL . '```' . PHP_EOL . PHP_EOL;
    }

    $output .= '</details>' . PHP_EOL . PHP_EOL;
  }

  return $output;
}

/**
 * Render a block under its heading.
 *
 * @param string $heading
 *   The heading, with its level.
 * @param string $body
 *   The block.
 *
 * @return string
 *   The heading and the block, or an empty string when the block is empty.
 */
function render_titled(string $heading, string $body): string {
  return $body === '' ? '' : $heading . PHP_EOL . PHP_EOL . $body . PHP_EOL . PHP_EOL;
}

/**
 * Render the front matter of a generated page.
 *
 * A string is written as a JSON string, which YAML reads as a double-quoted
 * scalar, so no character in the string ends the value early.
 *
 * @param array<string, string|int|null> $fields
 *   The values, keyed by field name.
 *
 * @return string
 *   The fields between the 2 delimiter lines.
 */
function render_front_matter(array $fields): string {
  $lines = ['---'];

  foreach ($fields as $name => $value) {
    $lines[] = sprintf('%s: %s', $name, match (TRUE) {
      is_string($value) => json_encode($value, JSON_UNESCAPED_SLASHES | JSON_UNESCAPED_UNICODE | JSON_THROW_ON_ERROR),
      $value === NULL => 'null',
      default => (string) $value,
    });
  }

  $lines[] = '---';

  return implode(PHP_EOL, $lines) . PHP_EOL;
}

/**
 * Render the directory of a section of the documentation site.
 *
 * @param string $context
 *   The context of a trait, such as 'Drupal'.
 *
 * @return string
 *   The directory relative to the repository root, such as
 *   'docs/content/drupal-steps'.
 */
function page_directory(string $context): string {
  return sprintf('%s/%s-steps', PAGES_DIRECTORY, strtolower($context));
}

/**
 * Render the path of the documentation site's page of a trait.
 *
 * @param string $context
 *   The context of the trait, such as 'Drupal'.
 * @param string $name
 *   The short trait name, such as 'BigPipeTrait'.
 *
 * @return string
 *   The path relative to the repository root, in the directory of the trait's
 *   section and named after the trait without its 'Trait' suffix.
 */
function reference_page(string $context, string $name): string {
  return sprintf('%s/%s.md', page_directory($context), camel_to_snake((string) preg_replace('/Trait$/', '', $name), '-'));
}

/**
 * Number the pages of each section of the documentation site by their title.
 *
 * @param array<string, array<string, mixed>> $info
 *   The extracted trait info from extract_info(), keyed by short name.
 *
 * @return array<string, int>
 *   The position of each trait's page in its section, from 1, keyed like the
 *   info.
 */
function page_positions(array $info): array {
  $titles = [];

  foreach ($info as $key => $class_info) {
    $titles[page_directory((string) $class_info['context'])][(string) $key] = (string) $class_info['title'];
  }

  $positions = [];

  foreach ($titles as $section_titles) {
    uasort($section_titles, strcasecmp(...));
    $positions += array_combine(array_keys($section_titles), range(1, count($section_titles)));
  }

  return $positions;
}

/**
 * Render the index of each section of the documentation site.
 *
 * @param array<string, array<string, mixed>> $info
 *   The extracted trait info from extract_info(), keyed by short name.
 *
 * @return array<string, string>
 *   The table linking the pages of each section in their sidebar order, keyed
 *   by the path of the section's README.md relative to the repository root.
 */
function render_page_indexes(array $info): array {
  $positions = page_positions($info);
  $rows = [];

  foreach ($info as $key => $class_info) {
    $context = (string) $class_info['context'];
    $index = page_directory($context) . '/README.md';
    $link = relative_link($index, reference_page($context, (string) $class_info['name']));
    $rows[$index][$positions[(string) $key]] = [
      sprintf('[%s](%s)', $class_info['title'], $link),
      sprintf('`%s`', $class_info['name_contextual']),
      (string) $class_info['description'],
    ];
  }

  $indexes = [];

  foreach ($rows as $index => $section_rows) {
    ksort($section_rows);
    $indexes[$index] = array_to_markdown_table(['Name', 'Trait', 'Description'], $section_rows);
  }

  return $indexes;
}

/**
 * Order entries keyed by context with the generic context first.
 *
 * @param array<string, mixed> $entries
 *   The entries, keyed by context.
 * @param mixed $default
 *   The entry of the generic context when the entries hold none.
 *
 * @return array<string, mixed>
 *   The entries, the generic context's first and the rest in their order.
 */
function context_first(array $entries, mixed $default): array {
  return array_merge([DEFAULT_CONTEXT => $entries[DEFAULT_CONTEXT] ?? $default], array_diff_key($entries, [DEFAULT_CONTEXT => $default]));
}

/**
 * List the generated pages of the documentation site the run no longer writes.
 *
 * Every page of a section directory but its README.md is generated, and the
 * README.md holds the index.
 *
 * @param string $base_path
 *   Base path for the repository.
 * @param array<string, string> $pages
 *   The pages the run writes, keyed by path relative to the repository root.
 *
 * @return array<int, string>
 *   The paths of the pages to remove, relative to the repository root, sorted.
 */
function stale_pages(string $base_path, array $pages): array {
  $stale = [];

  foreach (glob(sprintf('%s/%s/*-steps/*.md', $base_path, PAGES_DIRECTORY)) ?: [] as $file) {
    $relative = substr($file, strlen($base_path) + 1);

    if (basename($file) !== 'README.md' && !isset($pages[$relative])) {
      $stale[] = $relative;
    }
  }

  sort($stale);

  return $stale;
}

/**
 * Validate the published helpers.
 *
 * @param array<string, array<string, mixed>> $info
 *   Array of helper info items from extract_helpers().
 *
 * @return array<string>
 *   Array of errors.
 */
function validate_helpers(array $info): array {
  $errors = [];

  foreach ($info as $class_info) {
    $class_name = is_string($class_info['name'] ?? NULL) ? $class_info['name'] : '';

    foreach ((is_array($class_info['helpers'] ?? NULL) ? $class_info['helpers'] : []) as $helper) {
      $name = is_string($helper['name'] ?? NULL) ? $helper['name'] : '';
      $description = is_string($helper['description'] ?? NULL) ? $helper['description'] : '';

      if (trim($description) === '') {
        $errors[] = sprintf('  %s::%s - %s' . PHP_EOL, $class_name, $name, 'Published helper has no summary. Write one, or mark the helper @internal');
      }
    }
  }

  return $errors;
}

/**
 * Validate that every step trait names its page on the documentation site.
 *
 * @param array<string, array<string, mixed>> $info
 *   The extracted trait info from extract_info().
 *
 * @return array<string>
 *   Array of errors, 1 per trait without a title.
 */
function validate_titles(array $info): array {
  $errors = [];

  foreach ($info as $class_info) {
    if (!isset($class_info['title'])) {
      $errors[] = sprintf('  %s - %s' . PHP_EOL, $class_info['name_contextual'], 'Class comment has no "@title" naming its page on the documentation site');
    }
  }

  return $errors;
}

/**
 * Validate the info.
 *
 * @param array<string,array<string, array<int, array<string, array<int,string>|string>>|string>> $info
 *   The extracted trait info from extract_info().
 *
 * @return array<string>
 *   Array of errors.
 */
function validate(array $info): array {
  $errors = [];
  $non_descriptive_placeholders = non_descriptive_placeholders();
  $placeholder_synonyms = placeholder_synonyms();
  $rejected_step_phrases = rejected_step_phrases();
  $kind_placeholders = kind_placeholders();
  $acronyms = step_acronyms();
  $determiners = ['the', 'a', 'an', 'no', 'following'];

  foreach ($info as $class_info) {
    $class_name = is_string($class_info['name']) ? $class_info['name'] : '';

    // @phpstan-ignore-next-line
    foreach ($class_info['methods'] as $method) {
      $method['steps'] = is_array($method['steps']) ? $method['steps'] : [$method['steps']];
      $method['name'] = is_string($method['name']) ? $method['name'] : '';
      $method['description'] = is_string($method['description']) ? $method['description'] : '';
      $method['example'] = is_string($method['example']) ? $method['example'] : '';

      if (count($method['steps']) > 1) {
        $errors[] = sprintf('  %s::%s - %s' . PHP_EOL, $class_name, $method['name'], 'Multiple steps found');
      }

      $step = (string) $method['steps'][0];

      if (isset($method['takes_table']) && $method['takes_table'] === TRUE && !str_contains($step, ' the following ')) {
        $errors[] = sprintf('  %s::%s - %s' . PHP_EOL, $class_name, $method['name'], 'Missing "the following" before the table the step takes');
      }

      if (preg_match('/^@(?:Given|When) /', $step) === 1 && str_contains($step, ' should ')) {
        $errors[] = sprintf('  %s::%s - %s' . PHP_EOL, $class_name, $method['name'], 'Step uses "should", but only a Then step checks');
      }

      $actor = isset($method['actor']) && is_string($method['actor']) ? $method['actor'] : NULL;
      $is_first_person = preg_match('/^@(?:Given|When|Then) I /', $step) === 1;

      if ($actor === 'person' && !$is_first_person) {
        $errors[] = sprintf('  %s::%s - %s' . PHP_EOL, $class_name, $method['name'], 'Actor is "person" but the step does not start with "I "');
      }

      if ($actor === 'system' && $is_first_person) {
        $errors[] = sprintf('  %s::%s - %s' . PHP_EOL, $class_name, $method['name'], 'Actor is "system" but the step starts with "I "');
      }

      if (str_starts_with($step, '@Then')) {
        if (!str_contains((string) $method['name'], 'Assert')) {
          $errors[] = sprintf('  %s::%s - %s' . PHP_EOL, $class_name, $method['name'], 'Missing "Assert" in the method name');
        }

        if (str_contains((string) $method['name'], 'Should')) {
          $errors[] = sprintf('  %s::%s - %s' . PHP_EOL, $class_name, $method['name'], 'Assert method contains "Should", but it should not.');
        }

        if (!str_contains($step, ' should ')) {
          $errors[] = sprintf('  %s::%s - %s' . PHP_EOL, $class_name, $method['name'], 'Missing "should" in the step');
        }

        if (!(str_contains($step, ' the ') || str_contains($step, ' a ') || str_contains($step, ' an ') || str_contains($step, ' no '))) {
          $errors[] = sprintf('  %s::%s - %s' . PHP_EOL, $class_name, $method['name'], 'Missing "the", "a", "an" or "no" in the step');
        }

        // A qualifier after "exist" or "be <state>" narrows the subject. One after
        // a predicate's own object, as in "should match the XSD schema in the
        // file :filename", narrows that object, so it stays.
        if (preg_match('/ should (?:not )?(?:exist|be [a-z]+) (?:in|within|on|at|from|with) the (?:[a-z]+ )*:[a-z_]+$/', $step) === 1) {
          $errors[] = sprintf('  %s::%s - %s' . PHP_EOL, $class_name, $method['name'], 'Qualifier follows the predicate but should precede "should" with the subject it narrows');
        }
      }

      // The pattern also matches names the snake_case rule rejects, so a
      // violation is reported rather than truncated to a legal prefix.
      preg_match_all('/:([a-zA-Z_][a-zA-Z0-9_]*)/', $step, $placeholders);

      foreach ($placeholders[1] as $placeholder) {
        if (in_array($placeholder, $non_descriptive_placeholders, TRUE)) {
          $errors[] = sprintf('  %s::%s - %s' . PHP_EOL, $class_name, $method['name'], sprintf('Non-descriptive placeholder ":%s" in the step', $placeholder));
        }

        if (isset($placeholder_synonyms[$placeholder])) {
          $errors[] = sprintf('  %s::%s - %s' . PHP_EOL, $class_name, $method['name'], sprintf('Placeholder ":%s" in the step is a synonym of ":%s"', $placeholder, $placeholder_synonyms[$placeholder]));
        }

        if (preg_match('/^[a-z][a-z0-9_]*$/', $placeholder) !== 1) {
          $errors[] = sprintf('  %s::%s - %s' . PHP_EOL, $class_name, $method['name'], sprintf('Placeholder ":%s" in the step is not snake_case', $placeholder));
        }
      }

      if (preg_match('/^@(?:Given|When|Then) :/', $step) === 1) {
        $errors[] = sprintf('  %s::%s - %s' . PHP_EOL, $class_name, $method['name'], 'Step starts with a placeholder but should start with the noun it names');
      }

      if (preg_match('/^@(?:Given|When|Then) \//', $step) === 1) {
        $errors[] = sprintf('  %s::%s - %s' . PHP_EOL, $class_name, $method['name'], 'Step is a regular expression but should be words and placeholders');
      }

      // The trailing space lets a phrase that ends with one match at the end.
      foreach ($rejected_step_phrases as $rejected => $replacement) {
        if (str_contains($step . ' ', $rejected)) {
          $errors[] = sprintf('  %s::%s - %s' . PHP_EOL, $class_name, $method['name'], sprintf('Step reads "%s" but should read "%s"', trim($rejected), trim($replacement)));
        }
      }

      // "I visit :path" opens whatever page its argument names. Only a step
      // naming its destination in words is therefore held to naming a page
      // or a link.
      if (preg_match('/^@When I visit (?!:)/', $step) === 1 && preg_match('/ (?:page|link)\b/', $step) !== 1) {
        $errors[] = sprintf('  %s::%s - %s' . PHP_EOL, $class_name, $method['name'], 'Navigation step does not name the page it opens, as in "I visit the ... page"');
      }

      preg_match_all('/\bcontaining :([a-zA-Z_][a-zA-Z0-9_]*)/', $step, $partials);

      foreach ($partials[1] as $placeholder) {
        if (!str_starts_with($placeholder, 'partial_')) {
          $errors[] = sprintf('  %s::%s - %s' . PHP_EOL, $class_name, $method['name'], sprintf('Placeholder ":%s" after "containing" in the step is not prefixed with "partial_"', $placeholder));
        }
      }

      if (preg_match('/ (?:exists?|should (?:not )?exist) with the following /', $step) === 1) {
        $errors[] = sprintf('  %s::%s - %s' . PHP_EOL, $class_name, $method['name'], 'Table follows the verb but should follow the thing it describes, as in "the meta tag with the following attributes should exist:"');
      }

      $tokens = explode(' ', (string) preg_replace('/^@(?:Given|When|Then) /', '', $step));
      $is_kind = static fn(string $token): bool => preg_match('/^:([a-zA-Z_][a-zA-Z0-9_]*)/', $token, $match) === 1 && in_array($match[1], $kind_placeholders, TRUE);

      foreach ($tokens as $index => $token) {
        if ($index === 0 || preg_match('/^:([a-zA-Z_][a-zA-Z0-9_]*)/', $token, $placeholder_match) !== 1) {
          continue;
        }

        $placeholder = $placeholder_match[1];
        $previous = $tokens[$index - 1];

        // A placeholder after an article or another placeholder sits before its
        // noun, where only a kind or a count goes.
        if (!$is_kind($token) && (in_array($previous, $determiners, TRUE) || str_starts_with($previous, ':'))) {
          $errors[] = sprintf('  %s::%s - %s' . PHP_EOL, $class_name, $method['name'], sprintf('Placeholder ":%s" sits before its noun but says which one, so it should follow the noun', $placeholder));
        }
        elseif (placeholder_precedes_own_noun($placeholder, array_slice($tokens, $index + 1, 3))) {
          $errors[] = sprintf('  %s::%s - %s' . PHP_EOL, $class_name, $method['name'], sprintf('Placeholder ":%s" sits before the noun it names, so it should follow it', $placeholder));
        }

        if ($index >= 2 && !str_starts_with($previous, ':') && $is_kind($tokens[$index - 2])) {
          $errors[] = sprintf('  %s::%s - %s' . PHP_EOL, $class_name, $method['name'], sprintf('Placeholder ":%s" follows a noun with a kind before it, so it should read "with the <property> :%s"', $placeholder, $placeholder));
        }

        // A thing with no kind before its noun takes its name right after it.
        // The phrase "with the name" is therefore only for a noun such as
        // "the :vocabulary term".
        if ($index >= 4 && array_slice($tokens, $index - 3, 3) === ['with', 'the', 'name']) {
          $before = $index - 4;

          while ($before > 0 && preg_match('/^[a-z]+$/', $tokens[$before]) === 1 && !in_array($tokens[$before], $determiners, TRUE)) {
            $before--;
          }

          if (!$is_kind($tokens[$before])) {
            $errors[] = sprintf('  %s::%s - %s' . PHP_EOL, $class_name, $method['name'], 'Step reads "with the name", but a name should follow its noun, as in "the cookie :name"');
          }
        }

        if (preg_match('/^text\d*$/', $placeholder) === 1 && $actor !== 'person' && $previous !== 'text') {
          $errors[] = sprintf('  %s::%s - %s' . PHP_EOL, $class_name, $method['name'], sprintf('Placeholder ":%s" is for text on the page, so a step checking anything else should use ":value"', $placeholder));
        }
      }

      if (preg_match('/\b(?!(?:have|has|with|and)\b)([a-z]+) the value :/', $step, $named_value) === 1) {
        $errors[] = sprintf('  %s::%s - %s' . PHP_EOL, $class_name, $method['name'], sprintf('Step reads "%s the value", but a value after a verb reads bare and only "have" takes "the value"', $named_value[1]));
      }

      preg_match_all('/\b(' . implode('|', $acronyms) . ')\b/i', (string) preg_replace('/:[a-zA-Z_][a-zA-Z0-9_]*/', '', $step), $acronym_matches);

      foreach ($acronym_matches[1] as $acronym) {
        if ($acronym !== strtoupper($acronym)) {
          $errors[] = sprintf('  %s::%s - %s' . PHP_EOL, $class_name, $method['name'], sprintf('Acronym "%s" in the step should be uppercase', $acronym));
        }
      }

      if (empty($method['example'])) {
        $errors[] = sprintf('  %s::%s - Missing example' . PHP_EOL, $class_name, $method['name']);
      }
    }
  }

  return $errors;
}

/**
 * Validate that every documented step matches exactly 1 definition.
 *
 * Behat resolves definitions per step text while a scenario runs. A pattern
 * that shadows another one is therefore only reported once a scenario uses the
 * shadowed step.
 *
 * @param array<string,array<string, array<int, array<string, array<int,string>|string>>|string>> $info
 *   Array of trait info keyed by trait name.
 *
 * @return array<string>
 *   Array of errors.
 */
function validate_step_patterns(array $info): array {
  $errors = [];
  $policy = new TurnipPatternPolicy();
  $steps = [];

  foreach ($info as $class_info) {
    $class_name = is_string($class_info['name']) ? $class_info['name'] : '';

    // @phpstan-ignore-next-line
    foreach ($class_info['methods'] as $method) {
      $method_steps = is_array($method['steps']) ? $method['steps'] : [$method['steps']];
      $method_name = is_string($method['name']) ? $method['name'] : '';
      $method_example = is_string($method['example']) ? $method['example'] : '';
      $pattern = (string) preg_replace('/^@(?:Given|When|Then)\s+/', '', (string) ($method_steps[0] ?? ''));

      if ($pattern === '') {
        continue;
      }

      $steps[$method_name . '|' . $pattern] = [
        'label' => $class_name . '::' . $method_name,
        'method' => $method_name,
        'pattern' => $pattern,
        'regex' => $policy->transformPatternToRegex($pattern),
        'examples' => extract_step_examples($method_example),
      ];
    }
  }

  $examples = [];

  foreach ($steps as $step) {
    foreach ($step['examples'] as $example) {
      $examples[$example] ??= $step['label'];
    }
  }

  foreach ($examples as $example => $label) {
    $matched = [];

    foreach ($steps as $step) {
      if (preg_match($step['regex'], (string) $example) === 1) {
        $matched[$step['method']] = $step['pattern'];
      }
    }

    if (count($matched) > 1) {
      $conflicts = [];

      foreach ($matched as $matched_method => $matched_pattern) {
        $conflicts[] = sprintf('%s() as "%s"', $matched_method, $matched_pattern);
      }

      $errors[] = sprintf('  %s - Step "%s" matches more than one definition: %s' . PHP_EOL, $label, $example, implode(', ', $conflicts));
    }
  }

  // A renamed pattern whose example was not updated is reported here.
  foreach ($steps as $step) {
    $is_documented = FALSE;

    foreach ($step['examples'] as $example) {
      if (preg_match($step['regex'], $example) === 1) {
        $is_documented = TRUE;
        break;
      }
    }

    if (!$is_documented) {
      $errors[] = sprintf('  %s - No example matches the step "%s"' . PHP_EOL, $step['label'], $step['pattern']);
    }
  }

  return $errors;
}

/**
 * Extract Gherkin step texts from a documented example.
 *
 * @param string $example
 *   The example block.
 *
 * @return array<int, string>
 *   Array of step texts with the Gherkin keyword removed.
 */
function extract_step_examples(string $example): array {
  $steps = [];

  foreach (explode(PHP_EOL, $example) as $line) {
    if (preg_match('/^\s*(?:Given|When|Then|And|But)\s+(.+)$/', $line, $matches) === 1) {
      $steps[] = trim($matches[1]);
    }
  }

  return $steps;
}

/**
 * Check whether a placeholder sits right before the noun it is named after.
 *
 * The noun is 1 to 3 words joined with "_", as in ":media_type media type".
 * A "(s)" plural token or the colon ending a step is not part of it.
 *
 * @param string $placeholder
 *   The placeholder name, without the leading colon.
 * @param array<int, string> $words
 *   The up to 3 words that follow the placeholder in the step.
 *
 * @return bool
 *   TRUE when the words name the placeholder's own noun.
 */
function placeholder_precedes_own_noun(string $placeholder, array $words): bool {
  $words = array_map(static fn(string $word): string => str_replace('(s)', '', rtrim($word, ':')), $words);
  $word_count = count($words);

  for ($length = 1; $length <= $word_count; $length++) {
    $noun = implode('_', array_slice($words, 0, $length));

    if ($noun === $placeholder || str_ends_with($placeholder, '_' . $noun)) {
      return TRUE;
    }
  }

  return FALSE;
}

/**
 * Placeholder names that name a value's type or abbreviate its role.
 *
 * A placeholder is the only description a step gives of what a consumer must
 * pass. It names the thing in full (`:tolerance`, `:selector`, `:count`)
 * rather than its PHP type, a bare category or an abbreviation.
 *
 * A name listed here is rejected in step patterns.
 *
 * @return array<int, string>
 *   List of rejected placeholder names, without the leading colon.
 */
function non_descriptive_placeholders(): array {
  return [
    'arg',
    'argument',
    'array',
    'bool',
    'boolean',
    'data',
    'float',
    'int',
    'integer',
    'number',
    'param',
    'string',
    'type',
    'var',
  ];
}

/**
 * Placeholder names that duplicate a concept another name already carries.
 *
 * 1 concept takes 1 placeholder name across every trait, so a step using
 * a synonym is rejected in favor of the name the vocabulary uses.
 *
 * @return array<string, string>
 *   Map of the rejected name to the name to use, both without the colon.
 */
function placeholder_synonyms(): array {
  return [
    'email' => 'address',
    'file_name' => 'filename',
    'link_number' => 'index',
    'mail' => 'address',
    'role_name' => 'role',
    'term_name' => 'name',
  ];
}

/**
 * Placeholder names that say what kind or how many, so they precede a noun.
 *
 * Every other placeholder says which one and follows its noun, as in "the
 * user :name". These come first, as in "the :content_type content",
 * ":count item(s)" and "a REST :method request".
 *
 * @return array<int, string>
 *   List of placeholder names, without the leading colon.
 */
function kind_placeholders(): array {
  return [
    'bundle',
    'content_block_type',
    'content_type',
    'count',
    'direction',
    'entity_type',
    'media_type',
    'method',
    'offset',
    'paragraph_type',
    'parent_bundle',
    'parent_entity_type',
    'seconds',
    'tolerance',
    'vocabulary',
  ];
}

/**
 * Phrases the step vocabulary rejects in favor of 1 settled form.
 *
 * A step containing a key fails validation, and the error names the value as
 * the phrase to write instead.
 *
 * @return array<string, string>
 *   Map of the rejected phrase to the phrase that replaces it.
 */
function rejected_step_phrases(): array {
  return [
    'I click the ' => 'I click on the ',
    'I click on the link ' => 'I follow the link ',
    'I click on the button ' => 'I press the button ',
    'I press the link ' => 'I follow the link ',
    'I follow the button ' => 'I press the button ',
    // Mink registers "I should see :text", so a step in this library names
    // the text.
    'I should see :' => 'I should see the text :',
    'I should not see :' => 'I should not see the text :',
    'I edit the ' => 'I visit the ... edit page',
    ' the current ' => ' the ',
    ' a viewport' => ' the viewport',
    'the select element ' => 'the select ',
    ' be equal to ' => ' have the value ',
    ' contain :count ' => ' have :count ',
  ];
}

/**
 * Acronyms a step writes in capitals.
 *
 * A step containing one of these in any other case fails validation.
 *
 * @return array<int, string>
 *   List of acronyms.
 */
function step_acronyms(): array {
  return [
    'AJAX',
    'CSS',
    'DTD',
    'ECK',
    'HTML',
    'HTTP',
    'JS',
    'JSON',
    'REST',
    'URI',
    'URL',
    'WYSIWYG',
    'XML',
    'XSD',
  ];
}

/**
 * Canonical registry of the library's special Behat tags.
 *
 * The separator between a tag and its value is always a colon: a `parametrized`
 * tag is written `@prefix:value`, never `@prefix-value`. Hyphens only join
 * words inside a tag name (e.g. `@disable-form-validation`).
 *
 * A `flag` tag stands alone and takes no value.
 *
 * @return array<string, array{form: string, description: string}>
 *   Map of tag prefix to its form, one of 'parametrized' or 'flag', and the
 *   one-line description rendered into the configuration reference.
 */
function tag_registry(): array {
  return [
    'behat-steps-skip' => [
      'form' => 'parametrized',
      'description' => "Switches off every hook of the named trait, such as `EmailTrait`, for the scenario, and the trait's steps still work. On a trait that declares an `enabled` option, the tag sets it to `FALSE`. A value that isn't a trait name, a missing value or a trait that no context of the suite composes stops the whole run at that scenario's start.",
    ],
    'behat-steps-entity-cleanup-skip' => [
      'form' => 'parametrized',
      'description' => "Keeps the entities of the named entity type, such as `node`, that the scenario's steps created, instead of deleting them after the scenario. Repeated tags keep several types. Users and roles that the user steps create are deleted either way.",
    ],
    'backend' => [
      'form' => 'parametrized',
      'description' => "Moves the named backend to the front of the configured `backends` list for the scenario. Repeated tags promote several: the scenario's names go first, then the feature's, each group in the configured order, so the order the tags are written in doesn't matter. The tag reorders the list and never adds to it, so a name the list doesn't hold, or no name, stops the whole run at that scenario's start.",
    ],
    'module' => [
      'form' => 'parametrized',
      'description' => "Installs the named module for the scenario, or uninstalls it when the name starts with `!`, as in `@module:!redirect`, and restores the module's original state afterwards. Uninstalling deletes the module's data, which the restore doesn't bring back. A module the codebase doesn't hold fails the scenario.",
    ],
    'breakpoint' => [
      'form' => 'parametrized',
      'description' => "Resizes the browser window to the named breakpoint before the first step: `mobile_portrait`, `mobile_landscape`, `tablet_portrait`, `tablet_landscape`, `laptop`, `desktop` or a breakpoint a context's constructor adds through `responsiveSetBreakpoints()`. A scenario and its feature take 1 tag each, and the scenario's replaces the feature's. The scenario or its feature has to be `@javascript`, and an unknown name fails the scenario.",
    ],
    'email' => [
      'form' => 'parametrized',
      'description' => "Collects the email the site sends during the scenario, by pointing the named key of `system.mail`'s `interface` map, such as `default`, at a test collector and restoring it afterwards. A bare `@email` collects the `default` key, and repeated tags collect several.",
    ],
    'watchdog' => [
      'form' => 'parametrized',
      'description' => 'Adds the named log type, such as `my_module`, to the types the Watchdog check reads, beside `php`, which it always reads. An entry of a tracked type at warning severity or worse fails the scenario, unless `@error` allows it.',
    ],
    'disable-config-override' => [
      'form' => 'parametrized',
      'description' => 'Asks the site to ignore the `settings.php` overrides of the named configuration object, by sending its name in an `X-Config-No-Override` header with each request of the scenario. The site has to read the header itself, and a Selenium2 session sends no request headers.',
    ],
    'accessibility' => [
      'form' => 'parametrized',
      'description' => "Assesses every page the scenario visits with axe-core, and fails the scenario on the violations a threshold selects. `critical`, `serious`, `moderate` or `minor` fails on that impact or a worse one, `any` fails on every violation and `warning`, or `warn`, reports without failing. `strict` also fails the scenario on findings axe-core can't decide, whatever the threshold. A bare `@accessibility`, or a value outside these, uses the `accessibility.failure_threshold` option. The scenario has to be `@javascript`.",
    ],
    'bigpipe' => [
      'form' => 'flag',
      'description' => "Sets the `big_pipe_nojs` cookie before each step, so Drupal renders BigPipe placeholders on the server, for a browser driver that can't run JavaScript. A driver that runs JavaScript doesn't get the cookie.",
    ],
    'disable-form-validation' => [
      'form' => 'flag',
      'description' => "Adds `novalidate` to every form on the page after each step, so a scenario can submit values the browser's own validation would block. It acts only in a browser that runs JavaScript, since BrowserKit doesn't validate forms.",
    ],
    'js-errors' => [
      'form' => 'flag',
      'description' => 'Lets a `@javascript` scenario pass with JavaScript errors, which otherwise fail it. The errors are still collected. Sets the `javascript.fail_on_errors` option to `FALSE`.',
    ],
    'download' => [
      'form' => 'flag',
      'description' => 'Empties and creates the directory the `file_download.temp_dir` option names before the scenario, and deletes it afterwards, so the download steps write into an empty directory. Anything already in that directory is deleted.',
    ],
    'testmode' => [
      'form' => 'flag',
      'description' => 'Switches on the test mode of the Testmode module, from `drupal/testmode`, for the scenario, and switches it off afterwards. The module has to be enabled already, or the scenario fails at its start.',
    ],
    'debug' => [
      'form' => 'flag',
      'description' => 'Prints every email the collector holds, with its subject, body and addresses, each time an email step reads it. It works only in an `@email` scenario.',
    ],
    'error' => [
      'form' => 'flag',
      'description' => 'Lets the scenario pass when it logs errors to Watchdog, which otherwise fail it. The errors are still read and cleared, and a scenario that logs none passes too. Sets the `watchdog.fail_on_errors` option to `FALSE`.',
    ],
  ];
}

/**
 * Render the tag reference table.
 *
 * @return string
 *   Markdown table of every tag in the registry.
 */
function render_tag_reference(): string {
  $rows = [];

  foreach (tag_registry() as $tag => $definition) {
    $rows[] = [
      $definition['form'] === 'parametrized' ? sprintf('`@%s:VALUE`', $tag) : sprintf('`@%s`', $tag),
      $definition['description'],
    ];
  }

  return array_to_markdown_table(['Tag', 'Description'], $rows);
}

/**
 * Render the extension options table.
 *
 * The table is built from the extension's own configuration tree, so an option
 * cannot be added to the code without appearing in the reference.
 *
 * @return string
 *   Markdown table of every option the extension accepts.
 */
function render_extension_options(): string {
  $builder = new TreeBuilder(BehatStepsExtension::CONFIG_KEY);
  (new BehatStepsExtension())->configure($builder->getRootNode());

  $root = $builder->buildTree();
  $rows = [];

  if ($root instanceof ArrayNode) {
    $rows = extension_option_rows($root->getChildren());
  }

  return array_to_markdown_table(['Option', 'Type', 'Default', 'Description'], $rows);
}

/**
 * Flatten configuration nodes into table rows.
 *
 * @param array<string, \Symfony\Component\Config\Definition\NodeInterface> $nodes
 *   The child nodes to render.
 * @param string|null $prefix
 *   Dotted path of the parent node, or NULL at the root.
 *
 * @return array<int, array<int, string>>
 *   Rows of option path, type, default and description.
 */
function extension_option_rows(array $nodes, ?string $prefix = NULL): array {
  $rows = [];

  foreach ($nodes as $name => $node) {
    $path = $prefix === NULL ? (string) $name : $prefix . '.' . $name;
    $children = $node instanceof ArrayNode && !$node instanceof PrototypedArrayNode ? $node->getChildren() : [];

    $default = '-';

    if ($node->isRequired()) {
      $default = 'required';
    }
    elseif ($node->hasDefaultValue()) {
      $default = '`' . render_value($node->getDefaultValue()) . '`';
    }

    $rows[] = [
      '`' . $path . '`',
      extension_option_type($node),
      $children === [] ? $default : '-',
      extension_option_description($node),
    ];

    $rows = array_merge($rows, extension_option_rows($children, $path));
  }

  return $rows;
}

/**
 * Name the type of a configuration node.
 *
 * @param \Symfony\Component\Config\Definition\NodeInterface $node
 *   The configuration node.
 *
 * @return string
 *   The type as it reads in the reference.
 */
function extension_option_type(NodeInterface $node): string {
  if ($node instanceof PrototypedArrayNode) {
    return 'map';
  }

  if ($node instanceof ArrayNode) {
    return 'section';
  }

  if ($node instanceof IntegerNode) {
    return 'integer';
  }

  if ($node instanceof BooleanNode) {
    return 'boolean';
  }

  return 'string';
}

/**
 * Render the description of a configuration node as 1 table cell.
 *
 * An indented line of the node's info belongs to an example, which renders as
 * a code block keeping its relative indentation. A double-quoted value in the
 * description renders as code, so a URL in it does not become a link.
 *
 * Every line of an example ends in a '<br/>', since a line break would end the
 * table row. The last line ends in one too, so the site renders a 1-line
 * example as a block.
 *
 * @param \Symfony\Component\Config\Definition\NodeInterface $node
 *   The configuration node.
 *
 * @return string
 *   The description with line breaks and pipes made table-safe.
 */
function extension_option_description(NodeInterface $node): string {
  $info = method_exists($node, 'getInfo') ? (string) $node->getInfo() : '';

  $description = [];
  $example = [];

  foreach (explode(PHP_EOL, $info) as $line) {
    if (trim($line) === '') {
      continue;
    }

    if (str_starts_with($line, ' ')) {
      $example[] = rtrim($line);
      continue;
    }

    $description[] = (string) preg_replace('/"([^"]+)"/', '`$1`', trim($line));
  }

  $cell = implode('<br/>', $description);

  if ($example !== []) {
    $indentation = min(array_map(static fn(string $line): int => strspn($line, ' '), $example));
    $example = array_map(static fn(string $line): string => htmlspecialchars(substr($line, $indentation), ENT_NOQUOTES), $example);

    $cell .= '<pre><code>' . implode('<br/>', $example) . '<br/></code></pre>';
  }

  return str_replace('|', '\\|', $cell);
}

/**
 * Validate that every environment variable the source reads is documented.
 *
 * The variables have no registry to generate from, so the reference is written
 * by hand and this check keeps it complete.
 *
 * @param string $base_path
 *   Base path for the repository.
 *
 * @return array<string>
 *   Array of errors.
 */
function validate_env_vars(string $base_path = __DIR__): array {
  $source = $base_path . '/src';
  $reference = $base_path . '/' . CONFIGURATION_FILE;

  if (!is_dir($source) || !is_file($reference)) {
    return [];
  }

  $documented = (string) file_get_contents($reference);
  $errors = [];

  $iterator = new \RecursiveIteratorIterator(new \RecursiveDirectoryIterator($source, \FilesystemIterator::SKIP_DOTS));
  $files = [];

  foreach ($iterator as $file) {
    if ($file instanceof \SplFileInfo && $file->getExtension() === 'php') {
      $files[] = $file->getPathname();
    }
  }

  sort($files);

  foreach ($files as $file) {
    // Comments carry examples of what a consuming project reads, which is a
    // different contract from what this source reads.
    $code = '';

    foreach (token_get_all((string) file_get_contents($file)) as $token) {
      if (is_array($token) && in_array($token[0], [T_COMMENT, T_DOC_COMMENT], TRUE)) {
        continue;
      }

      $code .= is_array($token) ? $token[1] : $token;
    }

    preg_match_all('/getenv\(\s*[\'"]([A-Z][A-Z0-9_]*)[\'"]\s*\)/', $code, $matches);

    foreach (array_unique($matches[1]) as $variable) {
      // A '\b' boundary does not separate a name from a following
      // underscore, so the lookarounds test for name characters instead.
      if (preg_match('/(?<![A-Z0-9_])' . preg_quote($variable, '/') . '(?![A-Z0-9_])/', $documented) === 1) {
        continue;
      }

      $relative = substr($file, strlen($base_path) + 1);
      $errors[$variable] = sprintf('  %s - Environment variable %s is read but not documented in %s' . PHP_EOL, $relative, $variable, CONFIGURATION_FILE);
    }
  }

  return array_values($errors);
}

/**
 * Extract Behat tag names from a block of text.
 *
 * Matches `@tag` tokens while ignoring email addresses (the `@` in
 * `user@example.com` is preceded by a word character) and `@@`. Trailing prose
 * punctuation is stripped so a tag at the end of a sentence is captured cleanly.
 *
 * @param string $text
 *   The text to scan: a docblock, an example, or a feature file.
 *
 * @return array<int, string>
 *   Unique tag names without the leading `@`.
 */
function extract_tags(string $text): array {
  preg_match_all('/(?<![\w@])@([a-zA-Z0-9][a-zA-Z0-9:!._-]*)/', $text, $matches);

  $tags = [];

  foreach ($matches[1] as $tag) {
    $tag = rtrim($tag, '.,;');

    if ($tag !== '') {
      $tags[$tag] = $tag;
    }
  }

  return array_values($tags);
}

/**
 * Validate a single tag against the separator convention.
 *
 * @param string $tag
 *   The tag name without the leading `@`.
 * @param array<string, array{form: string, description: string}> $registry
 *   The tag registry from tag_registry().
 *
 * @return string|null
 *   An error message when a parametrized tag uses `-` instead of `:` as its
 *   value separator, or NULL when the tag conforms or is not a library tag.
 */
function validate_tag(string $tag, array $registry): ?string {
  $prefixes = array_keys($registry);
  // The longest prefix is tried first. A prefix that shares a leading segment
  // with a shorter one is therefore matched against its full, most specific
  // form.
  usort($prefixes, static fn(string $a, string $b): int => strlen($b) <=> strlen($a));

  foreach ($prefixes as $prefix) {
    if ($tag === $prefix || str_starts_with($tag, $prefix . ':')) {
      return NULL;
    }

    if (str_starts_with($tag, $prefix . '-')) {
      if ($registry[$prefix]['form'] !== 'parametrized') {
        return NULL;
      }

      $value = substr($tag, strlen($prefix) + 1);

      return sprintf('"@%s" must use ":" as the value separator (use "@%s:%s", not "@%s-%s").', $prefix, $prefix, $value, $prefix, $value);
    }
  }

  return NULL;
}

/**
 * Validate tag separators across documentation and feature files.
 *
 * Scans every trait description, every step example, and every feature file for
 * tag tokens, then checks each against the registry. A parametrized tag written
 * with a `-` separator instead of a `:` is reported so the documented format
 * stays consistent with the established convention.
 *
 * @param array<string, mixed> $info
 *   The extracted trait info from extract_info().
 * @param string $base_path
 *   Base path for the repository.
 *
 * @return array<int, string>
 *   Array of error messages, 1 per offending tag and source.
 */
function validate_tags(array $info, string $base_path = __DIR__): array {
  $registry = tag_registry();
  $errors = [];

  foreach ($info as $trait => $class_info) {
    if (!is_array($class_info)) {
      continue;
    }

    $label = is_string($class_info['name'] ?? NULL) ? $class_info['name'] : (string) $trait;

    $texts = [];

    if (is_string($class_info['description_full'] ?? NULL)) {
      $texts[] = $class_info['description_full'];
    }

    foreach ((is_array($class_info['methods'] ?? NULL) ? $class_info['methods'] : []) as $method) {
      if (is_array($method) && is_string($method['example'] ?? NULL)) {
        $texts[] = $method['example'];
      }
    }

    foreach ($texts as $text) {
      foreach (extract_tags($text) as $tag) {
        $message = validate_tag($tag, $registry);

        if ($message !== NULL) {
          $errors[$label . '|' . $tag] = sprintf('  %s - Tag %s' . PHP_EOL, $label, $message);
        }
      }
    }
  }

  $features_dir = $base_path . '/tests/behat/features';

  if (is_dir($features_dir)) {
    foreach (glob($features_dir . '/*.feature') ?: [] as $file) {
      $contents = file_get_contents($file);

      // @codeCoverageIgnoreStart
      if ($contents === FALSE) {
        continue;
      }

      // @codeCoverageIgnoreEnd
      $relative = 'tests/behat/features/' . basename($file);

      foreach (extract_tags($contents) as $tag) {
        $message = validate_tag($tag, $registry);

        if ($message !== NULL) {
          $errors[$relative . '|' . $tag] = sprintf('  %s - Tag %s' . PHP_EOL, $relative, $message);
        }
      }
    }
  }

  return array_values($errors);
}

/**
 * Convert a string to snake case.
 *
 * @param string $string
 *   The string to convert.
 * @param string $separator
 *   The separator.
 *
 * @return string
 *   The converted string.
 */
function camel_to_snake(string $string, string $separator = '_'): string {
  $string = preg_replace_callback('/([^0-9])(\d+)/', static fn(array $matches): string => $matches[1] . $separator . $matches[2], $string);

  $replacements = [];

  foreach (mb_str_split((string) $string) as $key => $char) {
    $lower_case_char = mb_strtolower($char);

    if ($lower_case_char !== $char && $key !== 0) {
      $replacements[$char] = $separator . $char;
    }
  }

  $string = str_replace(array_keys($replacements), array_values($replacements), $string);

  $string = trim($string, $separator);

  return mb_strtolower($string);
}

/**
 * Replace content in a string.
 *
 * @param string $haystack
 *   The content to search and replace in.
 * @param string $start
 *   The start of the content to replace.
 * @param string $end
 *   The end of the content to replace.
 * @param string $replacement
 *   The replacement content.
 */
function replace_content(string $haystack, string $start, string $end, string $replacement): string {
  if (!str_contains($haystack, $start)) {
    throw new \RuntimeException('Start not found in the haystack');
  }

  if (!str_contains($haystack, $end)) {
    throw new \RuntimeException('End not found in the haystack');
  }

  if (strpos($haystack, $start) > strpos($haystack, $end)) {
    throw new \RuntimeException('Start is after the end');
  }

  $pattern = '/' . preg_quote($start, '/') . '.*?' . preg_quote($end, '/') . '/s';
  $replacement = $start . PHP_EOL . $replacement . PHP_EOL . $end;

  return (string) preg_replace($pattern, $replacement, $haystack);
}

/**
 * Convert an array to a markdown table.
 *
 * @param array<int, string> $headers
 *   The headers for the table.
 * @param array<array-key, array<int, string>> $rows
 *   The rows for the table. Keys are ignored; the rows render in their
 *   current order.
 *
 * @return string
 *   The markdown table.
 */
function array_to_markdown_table(array $headers, array $rows): string {
  if (empty($headers) || empty($rows)) {
    return '';
  }

  $header_row = '| ' . implode(' | ', $headers) . ' |';
  $separator_row = '| ' . implode(' | ', array_fill(0, count($headers), '---')) . ' |';
  $data_rows = array_map(static fn(array $row): string => '| ' . implode(' | ', $row) . ' |', $rows);

  return implode(PHP_EOL, array_merge([$header_row, $separator_row], $data_rows));
}