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, and the step index in README.md.
 * - HELPERS.md, the toolbox a project calls from its own domain steps.
 * - The generated tables in docs/configuration.md.
 *
 * It also validates that:
 *
 * - The steps read in the documented format.
 * - 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\Step\Given;
use Behat\Step\Then;
use Behat\Step\When;
use DrevOps\BehatSteps\Behat\Config\ConfigSchemaReader;
use DrevOps\BehatSteps\Behat\Config\GroupName;
use DrevOps\BehatSteps\Behat\Config\Option;
use DrevOps\BehatSteps\Behat\Config\TagOverrideResolver;
use DrevOps\BehatSteps\Behat\Context\DrupalContext;
use DrevOps\BehatSteps\Behat\Context\WebContext;
use DrevOps\BehatSteps\Behat\Context\WebRawContext;
use DrevOps\BehatSteps\Behat\Prerequisite\Prerequisite;
use DrevOps\BehatSteps\Behat\Prerequisite\PrerequisiteReader;
use DrevOps\BehatSteps\Behat\ServiceContainer\BehatStepsExtension;
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;

/**
 * Matches a first-person pronoun anywhere in a step.
 *
 * A `When` narrates what the person does and reads in the first person. A
 * `Given` states a precondition and a `Then` names the entity it asserts on,
 * so neither refers to the person at all.
 */
const FIRST_PERSON = '/\b(I|[Mm]y|[Mm]e|[Mm]yself|[Ww]e|[Uu]s|[Oo]ur)\b/';

/**
 * 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';

/**
 * 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 part of the toolbox.
 */
const REGISTERED_ATTRIBUTE_PREFIXES = [
  'Behat\\Step\\',
  'Behat\\Hook\\',
  'Behat\\Transformation\\',
  'DrevOps\\BehatSteps\\Behat\\Hook\\Attribute\\',
];

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

/**
 * Classes published in the toolbox reference alongside the step traits.
 *
 * The root context contributes the backend access and the scenario plumbing a
 * domain step is written against, so that surface is part of the toolbox too.
 */
const TOOLBOX_CLASSES = [WebRawContext::class];

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

/**
 * File holding the configuration reference, relative to the repository root.
 */
const CONFIGURATION_FILE = 'docs/configuration.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_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.md' => [
      ['# Available steps', '[//]: # (END)', PHP_EOL . render_info($info, $base_path) . PHP_EOL],
    ],
    'README.md' => [
      ['## Available steps', '[//]: # (END)', PHP_EOL . render_info($info, $base_path, 'STEPS.md') . PHP_EOL],
    ],
    HELPERS_FILE => [
      ['# Available helpers', '[//]: # (END)', PHP_EOL . 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],
    ],
  ];

  $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;
    }
  }

  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) {
    file_put_contents($path, $contents);
  }

  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, so a reference document covers the whole vocabulary
 * rather than the part one 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\\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', 'context', 'methods',
 *   'options', 'prerequisites', 'description' and 'description_full' keys.
 *
 * @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,
      '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;
      }

      $parsed_comment = parse_method_comment((string) $method->getDocComment());
      $methods_by_keyword[explode(' ', $steps[0], 2)[0]][] = [
        'steps' => $steps,
        'description' => $parsed_comment['description'] ?? '',
        'example' => $parsed_comment['example'] ?? '',
        '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 one trait.
 *
 * Discovery goes through the reader the runtime uses, so the generator 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\Behat\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 one 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\Behat\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.
 */
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-')));

  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));
  }

  return [
    'description' => $description,
    'description_full' => $full_description,
  ];
}

/**
 * Parse comment.
 *
 * Extracts description and example from the docblock comment.
 *
 * @param string $comment
 *   The comment.
 *
 * @return array<string, string>|null
 *   Array of 'description' and 'example' keys or NULL if the comment is empty.
 */
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;
    }
    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 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),
    ];
  }

  if ($rows === []) {
    return '';
  }

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

/**
 * 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))),
    ];
  }

  if ($rows === []) {
    return '';
  }

  return '### Prerequisites' . PHP_EOL . PHP_EOL . array_to_markdown_table(['Prerequisite', 'Capability'], $rows) . PHP_EOL . PHP_EOL;
}

/**
 * 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 toolbox helpers from the class.
 *
 * 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', 'context', 'source',
 *   'steps_anchor', 'helpers', 'description' and 'description_full' keys,
 *   keyed by trait 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,
      '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,
      '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 (TOOLBOX_CLASSES as $toolbox_class) {
    $reflection = new \ReflectionClass($toolbox_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,
      'context' => 'Toolbox',
      '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 toolbox methods a class or trait contributes.
 *
 * Visibility is the marker: a public method that Behat does not register is
 * part of the toolbox. 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, ahead of the ones 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;
}

/**
 * Convert info to content.
 *
 * @param array<string,array<string, array<int, array<string, array<int,string>|string>>|string>> $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, or the index tables alone when '$path_for_links' is set.
 */
function render_info(array $info, string $base_path = __DIR__, ?string $path_for_links = NULL): string {
  $content_output = [];

  $index_rows = [];

  foreach ($info as $trait => $class_info) {
    $context = $class_info['context'];
    // @phpstan-ignore-next-line
    $src_file = sprintf('%s/%s/%s.php', STEPS_DIRECTORY, $context, $trait);
    $src_file_path = $base_path . '/' . $src_file;

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

    $example_name = camel_to_snake(str_replace('Trait', '', $trait));
    $prefix = $context !== DEFAULT_CONTEXT
      // @phpstan-ignore-next-line
      ? strtolower((string) $context) . '_'
      : '';
    $example_file = sprintf('tests/behat/features/%s%s.feature', $prefix, $example_name);
    $example_file_path = $base_path . '/' . $example_file;

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

    // @phpstan-ignore-next-line
    $content_output[$context] ??= '';
    // @phpstan-ignore-next-line
    $content_output[$context] .= sprintf('## %s', $class_info['name_contextual']) . PHP_EOL . PHP_EOL;
    // @phpstan-ignore-next-line
    $content_output[$context] .= sprintf('[Source](%s), [Example](%s)', $src_file, $example_file) . PHP_EOL . PHP_EOL;

    $description_full = '';
    // @phpstan-ignore-next-line
    $lines = explode(PHP_EOL, $class_info['description_full']);
    $was_list = FALSE;
    $in_code_block = FALSE;
    $code_block = '';

    foreach ($lines 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;
        $description_full .= '```' . PHP_EOL;
        $description_full .= rtrim($code_block) . PHP_EOL;
        $description_full .= '```' . 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) {
          $description_full .= $line . '<br/><br/>' . PHP_EOL;
        }
        else {
          $description_full .= $line . PHP_EOL;
        }

        $was_list = FALSE;
      }
      else {
        if (str_ends_with($description_full, '<br/><br/>' . PHP_EOL)) {
          $description_full = rtrim($description_full, '<br/><br/>' . PHP_EOL) . PHP_EOL;
        }

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

    $description_full = preg_replace('/^/m', '>  ', $description_full);
    // @phpstan-ignore-next-line
    $content_output[$context] .= $description_full . PHP_EOL . PHP_EOL;
    // @phpstan-ignore-next-line
    $content_output[$context] .= render_trait_prerequisites($class_info['prerequisites'] ?? []);
    // @phpstan-ignore-next-line
    $content_output[$context] .= render_trait_options($trait, $class_info['options'] ?? []);
    // @phpstan-ignore-next-line
    $index_rows_path = '#' . heading_anchor((string) $class_info['name_contextual']);

    if ($path_for_links) {
      $index_rows_path = $path_for_links . $index_rows_path;
    }

    // @phpstan-ignore-next-line
    $index_rows[$context][] = [
      // @phpstan-ignore-next-line
      sprintf('[%s](%s)', $class_info['name_contextual'], $index_rows_path),
      $class_info['description'],
    ];

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

      $method['steps'] = array_reduce($method['steps'], static fn(string $carry, string $item): string => $carry . sprintf("%s\n", $item), '');
      $method['steps'] = rtrim((string) $method['steps'], "\n");

      $method['description'] = rtrim((string) $method['description'], '.');

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

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

```gherkin
[example]
```

</details>

EOT;

      // @phpstan-ignore-next-line
      $content_output[$context] .= strtr(
        $template,
        [
          '[description]' => $method['description'],
          '[step]' => $method['steps'],
          '[example]' => $method['example'],
        ]
      );

      // @phpstan-ignore-next-line
      $content_output[$context] .= PHP_EOL;
    }
  }

  $index_rows[DEFAULT_CONTEXT] ??= [];
  $index_rows = array_merge(
    [DEFAULT_CONTEXT => $index_rows[DEFAULT_CONTEXT]],
    array_diff_key($index_rows, [DEFAULT_CONTEXT => []])
  );

  $index_output = '';

  foreach ($index_rows as $index_rows_context_name => $index_rows_contextual) {
    $index_output .= sprintf('### Index of %s steps', $index_rows_context_name) . PHP_EOL . PHP_EOL;
    // @phpstan-ignore-next-line
    $index_output .= array_to_markdown_table(['Class', 'Description'], $index_rows_contextual) . PHP_EOL . PHP_EOL;
  }

  $content_output[DEFAULT_CONTEXT] ??= '';
  $content_output = array_merge(
    [DEFAULT_CONTEXT => $content_output[DEFAULT_CONTEXT]],
    array_diff_key($content_output, [DEFAULT_CONTEXT => []])
  );
  $content_output = implode(PHP_EOL . PHP_EOL, $content_output);

  $output = '';

  $output .= $index_output . PHP_EOL;

  if (!$path_for_links) {
    $output .= '---' . PHP_EOL . PHP_EOL;
    $output .= $content_output . 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 {
  $content_output = [];
  $index_rows = [];

  foreach ($info as $class_info) {
    $context = (string) $class_info['context'];
    $name_contextual = (string) $class_info['name_contextual'];
    $anchor = heading_anchor($name_contextual);
    $helpers = is_array($class_info['helpers']) ? $class_info['helpers'] : [];

    $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));
    }

    $steps_anchor = $class_info['steps_anchor'] ?? NULL;
    $links = sprintf('[Source](%s)', $src_file);

    if (is_string($steps_anchor)) {
      $links .= sprintf(', [Steps](STEPS.md#%s)', $steps_anchor);
    }

    $content_output[$context] ??= '';
    $content_output[$context] .= sprintf('## %s', $name_contextual) . PHP_EOL . PHP_EOL;
    $content_output[$context] .= $links . PHP_EOL . PHP_EOL;
    $content_output[$context] .= '> ' . $class_info['description'] . PHP_EOL . PHP_EOL;

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

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

      if ($example !== '') {
        $content_output[$context] .= '```' . PHP_EOL . rtrim($example) . PHP_EOL . '```' . PHP_EOL . PHP_EOL;
      }

      $content_output[$context] .= '</details>' . PHP_EOL . PHP_EOL;
    }

    $index_rows[$context][] = [
      sprintf('[%s](#%s)', $name_contextual, $anchor),
      (string) count($helpers),
      (string) $class_info['description'],
    ];
  }

  $index_rows[DEFAULT_CONTEXT] ??= [];
  $index_rows = array_merge([DEFAULT_CONTEXT => $index_rows[DEFAULT_CONTEXT]], array_diff_key($index_rows, [DEFAULT_CONTEXT => []]));

  $output = '';

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

  $content_output[DEFAULT_CONTEXT] ??= '';
  $content_output = array_merge([DEFAULT_CONTEXT => $content_output[DEFAULT_CONTEXT]], array_diff_key($content_output, [DEFAULT_CONTEXT => []]));

  $output .= '---' . PHP_EOL . PHP_EOL;
  $output .= implode('', $content_output);

  return rtrim($output) . PHP_EOL;
}

/**
 * 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 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();

  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 (str_starts_with($step, '@Given') && str_ends_with($step, ':') && !str_contains($step, 'following')) {
        $errors[] = sprintf('  %s::%s - %s' . PHP_EOL, $class_name, $method['name'], 'Missing "following" in the step');
      }

      if (str_starts_with($step, '@Given') && preg_match(FIRST_PERSON, $step) === 1) {
        $errors[] = sprintf('  %s::%s - %s' . PHP_EOL, $class_name, $method['name'], 'Given step is in the first person but should state a precondition');
      }

      if (str_starts_with($step, '@When') && !str_starts_with($step, '@When I ')) {
        $errors[] = sprintf('  %s::%s - %s' . PHP_EOL, $class_name, $method['name'], 'When step does not start with "I "');
      }

      if (str_starts_with($step, '@Then')) {
        if (preg_match(FIRST_PERSON, $step) === 1) {
          $errors[] = sprintf('  %s::%s - %s' . PHP_EOL, $class_name, $method['name'], 'Then step is in the first person but should start with the asserted entity');
        }

        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 '))) {
          $errors[] = sprintf('  %s::%s - %s' . PHP_EOL, $class_name, $method['name'], 'Missing "the", "a" or "an" in the step');
        }

        if (str_starts_with($step, '@Then no ')) {
          $errors[] = sprintf('  %s::%s - %s' . PHP_EOL, $class_name, $method['name'], 'Then step negates with "no" but should negate with "should not"');
        }

        // 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) the [a-z]+(?: [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');
      }

      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, so only a step
      // naming its destination in words is 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('/:([a-zA-Z_][a-zA-Z0-9_]*) ([a-z]+)/', $step, $followed, PREG_SET_ORDER);

      foreach ($followed as [, $placeholder, $word]) {
        // A bundle placeholder qualifies the entity noun after it, as in
        // "the :media_type media", rather than naming that noun.
        if (str_ends_with($placeholder, '_type')) {
          continue;
        }

        if (in_array($word, explode('_', $placeholder), TRUE) || str_starts_with($word, $placeholder)) {
          $errors[] = sprintf('  %s::%s - %s' . PHP_EOL, $class_name, $method['name'], sprintf('Placeholder ":%s" in the step precedes its own noun "%s"', $placeholder, $word));
        }
      }

      if (preg_match('/(?<!\bvalue ):value\b/', $step) === 1) {
        $errors[] = sprintf('  %s::%s - %s' . PHP_EOL, $class_name, $method['name'], 'Placeholder ":value" in the step does not read "the value :value"');
      }

      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));
        }
      }

      // A placeholder before "should" names the asserted target, so what the
      // step compares against it is a value rather than a whole body of text.
      [$subject, $predicate] = array_pad(explode(' should ', $step, 2), 2, '');

      if (preg_match('/:[a-zA-Z_]/', $subject) === 1 && preg_match('/:text\b/', $predicate) === 1) {
        $errors[] = sprintf('  %s::%s - %s' . PHP_EOL, $class_name, $method['name'], 'Placeholder ":text" in the step compares against a named target but should be ":value"');
      }

      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, so a pattern
 * that shadows another one is 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;
}

/**
 * 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',
  ];
}

/**
 * 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 edit the ' => 'I visit the ... edit page',
    ' a viewport' => ' the viewport',
    'the select element ' => 'the select ',
    ' should have been ' => ' should be ',
  ];
}

/**
 * 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' => 'Switch off every hook of the named trait, such as `EmailTrait`. On a trait that declares an `enabled` option, the tag sets it to FALSE. A value not shaped like a trait name, or naming a trait no context of the suite composes, fails the run at scenario start.',
    ],
    'behat-steps-entity-cleanup-skip' => [
      'form' => 'parametrized',
      'description' => 'Keep entities of the named entity type after the scenario. Repeat the tag to keep several types.',
    ],
    'backend' => [
      'form' => 'parametrized',
      'description' => 'Move the named backend to the front of the configured backend list for the scenario. Repeat the tag to promote several: they keep the configured order among themselves, so the order the tags are written in does not matter. The tag reorders the list; it never adds to it.',
    ],
    'module' => [
      'form' => 'parametrized',
      'description' => 'Enable the named module for the scenario, or disable it when the name is prefixed with `!`. The original state is restored afterwards.',
    ],
    'breakpoint' => [
      'form' => 'parametrized',
      'description' => "Resize the viewport to the named breakpoint before the first step. 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`.",
    ],
    'email' => [
      'form' => 'parametrized',
      'description' => 'Collect email for the scenario with the named handler type. A bare `@email` uses the `default` handler.',
    ],
    'watchdog' => [
      'form' => 'parametrized',
      'description' => 'Track the named Watchdog message type in addition to `php`, which is always tracked.',
    ],
    'disable-config-override' => [
      'form' => 'parametrized',
      'description' => 'Disable `settings.php` overrides for the named configuration object for the duration of the scenario.',
    ],
    'accessibility' => [
      'form' => 'parametrized',
      'description' => 'Assess every page the scenario visits. The value sets the impact threshold that fails the scenario: `critical`, `serious`, `moderate`, `minor`, `any`, `warning` or `strict`.',
    ],
    'bigpipe' => [
      'form' => 'flag',
      'description' => 'Render BigPipe placeholders server-side, for a browser driver without JavaScript.',
    ],
    'disable-form-validation' => [
      'form' => 'flag',
      'description' => 'Strip HTML5 validation from every form on the page so a scenario can submit values the browser would block.',
    ],
    'js-errors' => [
      'form' => 'flag',
      'description' => 'Allow JavaScript errors, which otherwise fail the scenario. They are still collected. Sets the `javascript.fail_on_errors` option to FALSE.',
    ],
    'download' => [
      'form' => 'flag',
      'description' => 'Prepare the download directory for the scenario and clean it up afterwards.',
    ],
    'testmode' => [
      'form' => 'flag',
      'description' => 'Enable the Testmode module for the scenario.',
    ],
    'debug' => [
      'form' => 'flag',
      'description' => 'Print detailed diagnostics while the scenario runs.',
    ],
    'error' => [
      'form' => 'flag',
      'description' => 'Expect the scenario to log an error. The errors are still read and cleared, and the scenario is not failed. 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.
 *
 * @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() : '';

  $lines = array_filter(array_map(trim(...), explode(PHP_EOL, $info)), static fn(string $line): bool => $line !== '');

  return str_replace('|', '\\|', implode('<br/>', $lines));
}

/**
 * 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, so a prefix that shares a leading
  // segment with a shorter one is 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));
}