Add support for cache results

.gitignore

@@ -4,6 +4,7 @@
 .project
 .buildpath
 .settings
+.phpmd.result-cache.php
 *.phar
 /*.xml
 composer.lock

README.rst

@@ -136,6 +136,15 @@ Command line options
   - ``--ignore-violations-on-exit`` - will exit with a zero code, even if any
     violations are found.
 
+  - ``--cache`` - will enable the result cache. Will default to ``.phpmd.result-cache.php`` in the
+    current working directory.
+
+  - ``--cache-file`` - in cooperation with ``--cache`` will override the default result cache file path of
+    ``.phpmd.result-cache.php`` to the given file path.
+
+  - ``--cache-strategy`` - sets the caching strategy to determine if a file is still fresh. Either
+    `content` to base it on the file contents, or `timestamp` to base it on the file modified timestamp.
+
   - ``--generate-baseline`` - will generate a ``phpmd.baseline.xml`` for existing violations
     next to the ruleset definition file. The file paths of the violations will be relative to the current
     working directory.
@@ -144,7 +153,8 @@ Command line options
     that no longer exist. New violations will _not_ be added. The file path of the violations will be relative
     to the current working directory.
 
-  - ``--baseline-file`` - the filepath to a custom baseline xml file.
+  - ``--baseline-file`` - the filepath to a custom baseline xml file. If absent will
+    default to ``phpmd.baseline.xml``
 
   An example command line: ::
 

src/main/php/PHPMD/AbstractRule.php

@@ -21,6 +21,7 @@
 use PHPMD\Node\ClassNode;
 use PHPMD\Node\EnumNode;
 use PHPMD\Node\InterfaceNode;
+use PHPMD\Node\NodeInfoFactory;
 use PHPMD\Node\TraitNode;
 
 /**
@@ -396,7 +397,7 @@ protected function addViolation(
             'args' => $args,
         );
 
-        $ruleViolation = new RuleViolation($this, $node, $message, $metric);
+        $ruleViolation = new RuleViolation($this, NodeInfoFactory::fromNode($node), $message, $metric);
         $this->report->addRuleViolation($ruleViolation);
     }
 

src/main/php/PHPMD/Cache/Model/ResultCacheKey.php

@@ -0,0 +1,59 @@
+<?php
+
+namespace PHPMD\Cache\Model;
+
+class ResultCacheKey
+{
+    /** @var bool */
+    private $strict;
+    /** @var string|null */
+    private $baselineHash;
+    /** @var array<string, string> */
+    private $rules;
+    /** @var array<string, string> */
+    private $composer;
+    /** @var int */
+    private $phpVersion;
+
+    /**
+     * @param bool                  $strict
+     * @param string|null           $baselineHash
+     * @param array<string, string> $rules
+     * @param array<string, string> $composer
+     * @param int                   $phpVersion
+     */
+    public function __construct($strict, $baselineHash, $rules, $composer, $phpVersion)
+    {
+        $this->strict       = $strict;
+        $this->baselineHash = $baselineHash;
+        $this->rules        = $rules;
+        $this->composer     = $composer;
+        $this->phpVersion   = $phpVersion;
+    }
+
+    /**
+     * @return array
+     */
+    public function toArray()
+    {
+        return array(
+            'strict'       => $this->strict,
+            'baselineHash' => $this->baselineHash,
+            'rules'        => $this->rules,
+            'composer'     => $this->composer,
+            'phpVersion'   => $this->phpVersion,
+        );
+    }
+
+    /**
+     * @return bool
+     */
+    public function isEqualTo(ResultCacheKey $other)
+    {
+        return $this->strict === $other->strict
+            && $this->baselineHash === $other->baselineHash
+            && $this->rules === $other->rules
+            && $this->composer === $other->composer
+            && $this->phpVersion === $other->phpVersion;
+    }
+}

src/main/php/PHPMD/Cache/Model/ResultCacheState.php

@@ -0,0 +1,167 @@
+<?php
+
+namespace PHPMD\Cache\Model;
+
+use PHPMD\Node\NodeInfo;
+use PHPMD\Rule;
+use PHPMD\RuleSet;
+use PHPMD\RuleViolation;
+use PHPMD\Utility\Paths;
+
+class ResultCacheState
+{
+    /** @var ResultCacheKey */
+    private $cacheKey;
+
+    /** @var array{files: array<string, array{hash: string, violations: array}>} */
+    private $state;
+
+    /**
+     * @param array{files: array<string, array{hash: string, violations: array}>} $state
+     */
+    public function __construct(ResultCacheKey $cacheKey, $state = array())
+    {
+        $this->cacheKey = $cacheKey;
+        $this->state    = $state;
+    }
+
+    /**
+     * @return ResultCacheKey
+     */
+    public function getCacheKey()
+    {
+        return $this->cacheKey;
+    }
+
+    /**
+     * @param string $filePath
+     * @return array
+     */
+    public function getViolations($filePath)
+    {
+        if (isset($this->state['files'][$filePath]['violations']) === false) {
+            return array();
+        }
+
+        return $this->state['files'][$filePath]['violations'];
+    }
+
+    /**
+     * @param string $filePath
+     */
+    public function setViolations($filePath, array $violations)
+    {
+        $this->state['files'][$filePath]['violations'] = $violations;
+    }
+
+    /**
+     * @param string $filePath
+     */
+    public function addRuleViolation($filePath, RuleViolation $violation)
+    {
+        $this->state['files'][$filePath]['violations'][] = array(
+            'rule'          => get_class($violation->getRule()),
+            'namespaceName' => $violation->getNamespaceName(),
+            'className'     => $violation->getClassName(),
+            'methodName'    => $violation->getMethodName(),
+            'functionName'  => $violation->getFunctionName(),
+            'beginLine'     => $violation->getBeginLine(),
+            'endLine'       => $violation->getEndLine(),
+            'description'   => $violation->getDescription(),
+            'args'          => $violation->getArgs(),
+            'metric'        => $violation->getMetric()
+        );
+    }
+
+    /**
+     * @param string    $basePath
+     * @param RuleSet[] $ruleSetList
+     */
+    public function getRuleViolations($basePath, array $ruleSetList)
+    {
+        if (isset($this->state['files']) === false) {
+            return array();
+        }
+
+        $ruleViolations = array();
+
+        foreach ($this->state['files'] as $filePath => $violations) {
+            if (isset($violations['violations']) === false) {
+                continue;
+            }
+            foreach ($violations['violations'] as $violation) {
+                $rule     = self::findRuleIn($violation['rule'], $ruleSetList);
+                $nodeInfo = new NodeInfo(
+                    Paths::concat($basePath, $filePath),
+                    $violation['namespaceName'],
+                    $violation['className'],
+                    $violation['methodName'],
+                    $violation['functionName'],
+                    $violation['beginLine'],
+                    $violation['endLine']
+                );
+
+                if ($violation['args'] === null) {
+                    $violationMessage = $violation['description'];
+                } else {
+                    $violationMessage = array('args' => $violation['args'], 'message' => $violation['description']);
+                }
+                $ruleViolations[] = new RuleViolation($rule, $nodeInfo, $violationMessage, $violation['metric']);
+            }
+        }
+
+        return $ruleViolations;
+    }
+
+    /**
+     * @param string $filePath
+     * @param string $hash
+     * @return bool
+     */
+    public function isFileModified($filePath, $hash)
+    {
+        if (isset($this->state['files'][$filePath]['hash']) === false) {
+            return true;
+        }
+
+        return $this->state['files'][$filePath]['hash'] !== $hash;
+    }
+
+    /**
+     * @param string $filePath
+     * @param string $hash
+     */
+    public function setFileState($filePath, $hash)
+    {
+        return $this->state['files'][$filePath]['hash'] = $hash;
+    }
+
+    /**
+     * @return array
+     */
+    public function toArray()
+    {
+        return array(
+            'key'   => $this->cacheKey->toArray(),
+            'state' => $this->state
+        );
+    }
+
+    /**
+     * @param string    $ruleClassName
+     * @param RuleSet[] $ruleSetList
+     * @return Rule|null
+     */
+    private static function findRuleIn($ruleClassName, array $ruleSetList)
+    {
+        foreach ($ruleSetList as $ruleSet) {
+            foreach ($ruleSet->getRules() as $rule) {
+                if (get_class($rule) === $ruleClassName) {
+                    return $rule;
+                }
+            }
+        }
+
+        return null;
+    }
+}

src/main/php/PHPMD/Cache/Model/ResultCacheStrategy.php

@@ -0,0 +1,16 @@
+<?php
+
+namespace PHPMD\Cache\Model;
+
+class ResultCacheStrategy
+{
+    /**
+     * Determine the file cache freshness based on sha hash of the contents of the file
+     */
+    const CONTENT = 'content';
+
+    /**
+     * Determine the file cache freshness based on the file modified timestamp
+     */
+    const TIMESTAMP = 'timestamp';
+}

src/main/php/PHPMD/Cache/ResultCacheEngine.php

@@ -0,0 +1,50 @@
+<?php
+
+namespace PHPMD\Cache;
+
+class ResultCacheEngine
+{
+    /** @var ResultCacheFileFilter */
+    private $fileFilter;
+
+    /** @var ResultCacheUpdater */
+    private $updater;
+
+    /** @var ResultCacheWriter */
+    private $writer;
+
+    public function __construct(
+        ResultCacheFileFilter $fileFilter,
+        ResultCacheUpdater    $updater,
+        ResultCacheWriter     $writer
+    ) {
+
+        $this->fileFilter = $fileFilter;
+        $this->updater    = $updater;
+        $this->writer     = $writer;
+    }
+
+    /**
+     * @return ResultCacheFileFilter
+     */
+    public function getFileFilter()
+    {
+        return $this->fileFilter;
+    }
+
+    /**
+     * @return ResultCacheUpdater
+     */
+    public function getUpdater()
+    {
+        return $this->updater;
+    }
+
+    /**
+     * @return ResultCacheWriter
+     */
+    public function getWriter()
+    {
+        return $this->writer;
+    }
+}

src/main/php/PHPMD/Cache/ResultCacheEngineFactory.php

@@ -0,0 +1,49 @@
+<?php
+
+namespace PHPMD\Cache;
+
+use PHPMD\RuleSet;
+use PHPMD\TextUI\CommandLineOptions;
+
+class ResultCacheEngineFactory
+{
+    /** @var ResultCacheKeyFactory */
+    private $cacheKeyFactory;
+    /** @var ResultCacheStateFactory */
+    private $cacheStateFactory;
+
+    public function __construct(ResultCacheKeyFactory $cacheKeyFactory, ResultCacheStateFactory $cacheStateFactory)
+    {
+        $this->cacheKeyFactory   = $cacheKeyFactory;
+        $this->cacheStateFactory = $cacheStateFactory;
+    }
+
+    /**
+     * @param string    $basePath
+     * @param RuleSet[] $ruleSetList
+     * @return ResultCacheEngine|null
+     */
+    public function create($basePath, CommandLineOptions $options, array $ruleSetList)
+    {
+        if ($options->isCacheEnabled() === false) {
+            return null;
+        }
+
+        // create cache key based on the current rules and environment
+        $cacheKey = $this->cacheKeyFactory->create($options->hasStrict(), $ruleSetList);
+
+        // load result cache from file
+        $state = $this->cacheStateFactory->fromFile($options->cacheFile());
+
+        // the cache key doesn't match the stored cache key. Invalidate cache
+        if ($state !== null && $state->getCacheKey()->isEqualTo($cacheKey) === false) {
+            $state = null;
+        }
+
+        return new ResultCacheEngine(
+            new ResultCacheFileFilter($basePath, $options->cacheStrategy(), $cacheKey, $state),
+            new ResultCacheUpdater($basePath),
+            new ResultCacheWriter($options->cacheFile())
+        );
+    }
+}