<?php

/**
 * @file
 *
 * Throw-away script which scans all visible test classes and ensures that
 * each test case has a doc-comment.
 *
 * To call the script, obtain a Drupal 8-compatible version of Drush
 * (e.g. "git clone git://git.drupalcode.org/project/drush.git")
 * and run:
 *
 * $ drush scr test-doc-validator.php
 *
 * FIXME: Shouldn't this work be done by the coder module?
 * ... someone else thinks so: http://drupal.org/node/1359786
 */

/**
 * Value object representing an under-documented item in source-code
 */
class TestClassValidationResult {
  var $fileName;
  var $line;
  var $symbolType;
  var $symbol;
  var $message;
}

/**
 * Identify classes and test methods that are missing doc comments
 */
class TestClassValidator {

  /**
   * Find all visible test classes and ensure that they have doc comments
   *
   * @param $file string
   * @param $className string
   * @return array(TestClassValidationResult)
   */
  function validateAll() {
    $result = array();
    foreach (simpletest_test_get_all() as $testGroup) {
      foreach ($testGroup as $className => $test) {
        $clazz = new ReflectionClass($className);
        foreach ($this->validateClass($clazz) as $validationResult) {
          $result[] = $validationResult;
        }

        foreach ($clazz->getMethods() as $method) {
          foreach ($this->validateMethod($method) as $validationResult) {
            $result[] = $validationResult;
          }
        }
      }
    }
    return $result;
  }

  /**
   * Identify any problems with a class
   *
   * @return array(TestClassValidationResult)
   */
  function validateClass(ReflectionClass $clazz) {
    $result = array();

    // When class-level comments are missing, sometimes they get confused for @file-level comments.
    if ($clazz->getDocComment() === FALSE || preg_match('/@file/', $clazz->getDocComment()) || $this->isBlank($clazz->getDocComment())) {
      $validationResult = new TestClassValidationResult();
      $validationResult->symbolType = 'class';
      $validationResult->symbol = $clazz->getName();
      $validationResult->fileName = $clazz->getFileName();
      $validationResult->line = $clazz->getStartLine();
      $validationResult->message = 'Missing doc comment';
      $result[] = $validationResult;
    }

    return $result;
  }

  /**
   * Identify any problems with a method
   *
   * @return array(TestClassValidationResult)
   */
  function validateMethod(ReflectionMethod $method) {
    $result = array();
    if (!preg_match('/^test/', $method->getName())) {
      // don't care
    } elseif ($method->getDocComment() === FALSE || $this->isBlank($method->getDocComment())) {
      $validationResult = new TestClassValidationResult();
      $validationResult->symbolType = 'method';
      $validationResult->symbol = $method->getName();
      $validationResult->fileName = $method->getFileName();
      $validationResult->line = $method->getStartLine();
      $validationResult->message = 'Missing doc comment';
      $result[] = $validationResult;
    }
    return $result;
  }

  /**
   * @param $comment raw comment string
   * @return array(string) cleaned-up comment lines
   */
  protected function parseCommentLines($comment) {
    $result = array();
    $comment = preg_replace('/^\/\*\*/', '', $comment);
    $comment = preg_replace('/\*\\/$/', '', $comment);
    $lines = explode("\n", $comment);
    foreach ($lines as $line) {
      $line = preg_replace('/\r/', '', $line);
      $line = preg_replace('/^ *\* */', '', $line);
      $line = trim($line);
      $result[] = $line;
    }
    return $result;
  }

  /**
   * @param $comment raw comment string
   * @return bool
   */
  protected function isBlank($comment) {
    foreach ($this->parseCommentLines($comment) as $commentLine) {
      if (!empty($commentLine)) {
        return FALSE;
      }
    }
    return TRUE;
  }
}

/**
 * Find and print any problems with test classes
 */
function test_class_validate_main() {
  $testClassValidator = new TestClassValidator();
  foreach ($testClassValidator->validateAll() as $validationResult) {
    printf("%s line %d: %s %s\n", $validationResult->fileName,
      $validationResult->line,
      $validationResult->symbolType,
      $validationResult->symbol
      // $validationResult->message
    );
  }
}

test_class_validate_main();