* Dariusz Rumiński * * This source file is subject to the MIT license that is bundled * with this source code in the file LICENSE. */ namespace PhpCsFixer\Documentation; use PhpCsFixer\AbstractFixer; use PhpCsFixer\Console\Command\HelpCommand; use PhpCsFixer\Differ\FullDiffer; use PhpCsFixer\Fixer\Basic\Psr0Fixer; use PhpCsFixer\Fixer\ConfigurableFixerInterface; use PhpCsFixer\Fixer\ConfigurationDefinitionFixerInterface; use PhpCsFixer\Fixer\DefinedFixerInterface; use PhpCsFixer\Fixer\DeprecatedFixerInterface; use PhpCsFixer\Fixer\FixerInterface; use PhpCsFixer\FixerConfiguration\AliasedFixerOption; use PhpCsFixer\FixerConfiguration\AllowedValueSubset; use PhpCsFixer\FixerConfiguration\DeprecatedFixerOptionInterface; use PhpCsFixer\FixerDefinition\CodeSampleInterface; use PhpCsFixer\FixerDefinition\FileSpecificCodeSampleInterface; use PhpCsFixer\FixerDefinition\VersionSpecificCodeSampleInterface; use PhpCsFixer\Preg; use PhpCsFixer\RuleSet\RuleSet; use PhpCsFixer\RuleSet\RuleSetDescriptionInterface; use PhpCsFixer\RuleSet\RuleSets; use PhpCsFixer\StdinFileInfo; use PhpCsFixer\Tokenizer\Tokens; use PhpCsFixer\Utils; /** * @internal */ final class DocumentationGenerator { /** * @var FullDiffer */ private $differ; /** * @var string */ private $path; public function __construct() { $this->differ = new FullDiffer(); $this->path = \dirname(__DIR__, 2).'/doc'; } /** * @return string */ public function getFixersDocumentationDirectoryPath() { return $this->path.'/rules'; } /** * @return string */ public function getFixersDocumentationIndexFilePath() { return $this->getFixersDocumentationDirectoryPath().'/index.rst'; } /** * @param AbstractFixer[] $fixers * * @return string */ public function generateFixersDocumentationIndex(array $fixers) { $overrideGroups = [ 'PhpUnit' => 'PHPUnit', 'PhpTag' => 'PHP Tag', 'Phpdoc' => 'PHPDoc', ]; usort($fixers, function (FixerInterface $a, FixerInterface $b) { return strcmp(\get_class($a), \get_class($b)); }); $documentation = <<<'RST' ======================= List of Available Rules ======================= RST; $currentGroup = null; foreach ($fixers as $fixer) { $namespace = Preg::replace('/^.*\\\\(.+)\\\\.+Fixer$/', '$1', \get_class($fixer)); if (isset($overrideGroups[$namespace])) { $group = $overrideGroups[$namespace]; } else { $group = Preg::replace('/(?<=[[:lower:]])(?=[[:upper:]])/', ' ', $namespace); } if ($group !== $currentGroup) { $underline = str_repeat('-', \strlen($group)); $documentation .= "\n\n{$group}\n{$underline}\n"; $currentGroup = $group; } $summary = str_replace('`', '``', $fixer->getDefinition()->getSummary()); $attributes = []; if ($fixer instanceof DeprecatedFixerInterface) { $attributes[] = 'deprecated'; } if ($fixer->isRisky()) { $attributes[] = 'risky'; } if ([] !== $attributes) { $attributes = ' *('.implode(', ', $attributes).')*'; } else { $attributes = ''; } $path = './'.$this->getFixerDocumentationFileRelativePath($fixer); $documentation .= <<getName()} <{$path}>`_{$attributes} {$summary} RST; } return "{$documentation}\n"; } /** * @return string */ public function getFixerDocumentationFilePath(FixerInterface $fixer) { return $this->getFixersDocumentationDirectoryPath().'/'.Preg::replaceCallback( '/^.*\\\\(.+)\\\\(.+)Fixer$/', function (array $matches) { return Utils::camelCaseToUnderscore($matches[1]).'/'.Utils::camelCaseToUnderscore($matches[2]); }, \get_class($fixer) ).'.rst'; } /** * @return string */ public function getFixerDocumentationFileRelativePath(FixerInterface $fixer) { return Preg::replace( '#^'.preg_quote($this->getFixersDocumentationDirectoryPath(), '#').'/#', '', $this->getFixerDocumentationFilePath($fixer) ); } /** * @return string */ public function generateFixerDocumentation(FixerInterface $fixer) { $name = $fixer->getName(); $title = "Rule ``{$name}``"; $titleLine = str_repeat('=', \strlen($title)); $doc = "{$titleLine}\n{$title}\n{$titleLine}"; if ($fixer instanceof DeprecatedFixerInterface) { $doc .= "\n\n.. warning:: This rule is deprecated and will be removed on next major version."; $alternatives = $fixer->getSuccessorsNames(); if ([] !== $alternatives) { $doc .= $this->toRst(sprintf( "\n\nYou should use %s instead.", Utils::naturalLanguageJoinWithBackticks($alternatives) ), 3); } } $riskyDescription = null; $samples = []; if ($fixer instanceof DefinedFixerInterface) { $definition = $fixer->getDefinition(); $doc .= "\n\n".$this->toRst($definition->getSummary()); $description = $definition->getDescription(); if (null !== $description) { $description = $this->toRst($description); $doc .= <<getRiskyDescription(); $samples = $definition->getCodeSamples(); } elseif ($fixer->isRisky()) { $riskyDescription = 'Changes applied by the rule to your code might change its behavior.'; } if (null !== $riskyDescription) { $riskyDescription = $this->toRst($riskyDescription, 3); $doc .= <<getConfigurationDefinition(); foreach ($configurationDefinition->getOptions() as $option) { $optionInfo = "``{$option->getName()}``"; $optionInfo .= "\n".str_repeat('~', \strlen($optionInfo)); if ($option instanceof DeprecatedFixerOptionInterface) { $optionInfo .= "\n\n.. warning:: This option is deprecated and will be removed on next major version. {$this->toRst($option->getDeprecationMessage())}"; } $optionInfo .= "\n\n".$this->toRst($option->getDescription()); if ($option instanceof AliasedFixerOption) { $optionInfo .= "\n\n.. note:: The previous name of this option was ``{$option->getAlias()}`` but it is now deprecated and will be removed on next major version."; } $allowed = HelpCommand::getDisplayableAllowedValues($option); $allowedKind = 'Allowed values'; if (null !== $allowed) { foreach ($allowed as &$value) { if ($value instanceof AllowedValueSubset) { $value = 'a subset of ``'.HelpCommand::toString($value->getAllowedValues()).'``'; } else { $value = '``'.HelpCommand::toString($value).'``'; } } } else { $allowedKind = 'Allowed types'; $allowed = array_map(function ($value) { return '``'.$value.'``'; }, $option->getAllowedTypes()); } if (null !== $allowed) { $allowed = implode(', ', $allowed); $optionInfo .= "\n\n{$allowedKind}: {$allowed}"; } if ($option->hasDefault()) { $default = HelpCommand::toString($option->getDefault()); $optionInfo .= "\n\nDefault value: ``{$default}``"; } else { $optionInfo .= "\n\nThis option is required."; } $doc .= "\n\n{$optionInfo}"; } } elseif ($fixer instanceof ConfigurableFixerInterface) { $doc .= "\n\nThis rule is configurable."; } if (0 !== \count($samples)) { $doc .= <<<'RST' Examples -------- RST; foreach ($samples as $index => $sample) { $title = sprintf('Example #%d', $index + 1); $titleLine = str_repeat('~', \strlen($title)); $doc .= "\n\n{$title}\n{$titleLine}"; if ($fixer instanceof ConfigurableFixerInterface) { if (null === $sample->getConfiguration()) { $doc .= "\n\n*Default* configuration."; } else { $doc .= sprintf( "\n\nWith configuration: ``%s``.", HelpCommand::toString($sample->getConfiguration()) ); } } $doc .= "\n".$this->generateSampleDiff($fixer, $sample, $index + 1, $name); } } $ruleSetConfigs = []; foreach (RuleSets::getSetDefinitionNames() as $set) { $ruleSet = new RuleSet([$set => true]); if ($ruleSet->hasRule($name)) { $ruleSetConfigs[$set] = $ruleSet->getRuleConfiguration($name); } } if ([] !== $ruleSetConfigs) { $plural = 1 !== \count($ruleSetConfigs) ? 's' : ''; $doc .= << $config) { $ruleSetPath = $this->getRuleSetsDocumentationFilePath($set); $ruleSetPath = substr($ruleSetPath, strrpos($ruleSetPath, '/')); $doc .= <<`_ rule set will enable the ``{$name}`` rule RST; if (null !== $config) { $doc .= " with the config below:\n\n ``".HelpCommand::toString($config).'``'; } elseif ($fixer instanceof ConfigurationDefinitionFixerInterface) { $doc .= ' with the default config.'; } else { $doc .= '.'; } } } return "{$doc}\n"; } /** * @return string */ public function getRuleSetsDocumentationDirectoryPath() { return $this->path.'/ruleSets'; } /** * @return string */ public function getRuleSetsDocumentationIndexFilePath() { return $this->getRuleSetsDocumentationDirectoryPath().'/index.rst'; } /** * @param AbstractFixer[] $fixers * * @return string */ public function generateRuleSetsDocumentation(RuleSetDescriptionInterface $definition, array $fixers) { $fixerNames = []; foreach ($fixers as $fixer) { $fixerNames[$fixer->getName()] = $fixer; } $title = "Rule set ``{$definition->getName()}``"; $titleLine = str_repeat('=', \strlen($title)); $doc = "{$titleLine}\n{$title}\n{$titleLine}\n\n".$definition->getDescription(); if ($definition->isRisky()) { $doc .= ' This set contains rules that are risky.'; } $doc .= "\n\n"; $rules = $definition->getRules(); if (\count($rules) < 1) { $doc .= 'This is an empty set.'; } else { $doc .= "Rules\n-----\n"; foreach ($rules as $rule => $config) { if ('@' === $rule[0]) { $ruleSetPath = $this->getRuleSetsDocumentationFilePath($rule); $ruleSetPath = substr($ruleSetPath, strrpos($ruleSetPath, '/')); $doc .= "\n- `{$rule} <.{$ruleSetPath}>`_"; } else { $path = Preg::replace( '#^'.preg_quote($this->getFixersDocumentationDirectoryPath(), '#').'/#', './../rules/', $this->getFixerDocumentationFilePath($fixerNames[$rule]) ); $doc .= "\n- `{$rule} <{$path}>`_"; } if (!\is_bool($config)) { $doc .= "\n config:\n ``".HelpCommand::toString($config).'``'; } } } return $doc."\n"; } /** * @param string $name * * @return string */ public function getRuleSetsDocumentationFilePath($name) { return $this->getRuleSetsDocumentationDirectoryPath().'/'.str_replace(':risky', 'Risky', ucfirst(substr($name, 1))).'.rst'; } /** * @return string */ public function generateRuleSetsDocumentationIndex(array $setDefinitions) { $documentation = <<<'RST' =========================== List of Available Rule sets =========================== RST; foreach ($setDefinitions as $name => $path) { $path = substr($path, strrpos($path, '/')); $documentation .= "\n- `{$name} <.{$path}>`_"; } return $documentation."\n"; } /** * @param int $sampleNumber * @param string $ruleName * * @return string */ private function generateSampleDiff(FixerInterface $fixer, CodeSampleInterface $sample, $sampleNumber, $ruleName) { if ($sample instanceof VersionSpecificCodeSampleInterface && !$sample->isSuitableFor(\PHP_VERSION_ID)) { $existingFile = @file_get_contents($this->getFixerDocumentationFilePath($fixer)); if (false !== $existingFile) { Preg::match("/\\RExample #{$sampleNumber}\\R.+?(?\\R\\.\\. code-block:: diff\\R\\R.*?)\\R(?:\\R\\S|$)/s", $existingFile, $matches); if (isset($matches['diff'])) { return $matches['diff']; } } $error = <<getCode(); $tokens = Tokens::fromCode($old); $file = $sample instanceof FileSpecificCodeSampleInterface ? $sample->getSplFileInfo() : new StdinFileInfo() ; if ($fixer instanceof ConfigurableFixerInterface) { $configuration = $sample->getConfiguration(); if (null === $configuration) { $configuration = []; } if ($fixer instanceof Psr0Fixer && isset($configuration['dir']) && 0 === strpos($configuration['dir'], './')) { // Psr0Fixer relies on realpath() which fails for directories // relative to some path when the working directory is a // different path. Using an absolute path prevents this issue. $configuration['dir'] = \dirname(__DIR__, 2).substr($configuration['dir'], 1); } $fixer->configure($configuration); } $fixer->fix($file, $tokens); $diff = $this->differ->diff($old, $tokens->generateCode()); $diff = Preg::replace('/@@[ \+\-\d,]+@@\n/', '', $diff); $diff = Preg::replace('/\r/', '^M', $diff); $diff = Preg::replace('/^ $/m', '', $diff); $diff = Preg::replace('/\n$/', '', $diff); return <<indent($diff, 3)} RST; } /** * @param string $string * @param int $indent * * @return string */ private function toRst($string, $indent = 0) { $string = wordwrap(Preg::replace('/(?indent($string, $indent); } return $string; } /** * @param string $string * @param int $indent * * @return string */ private function indent($string, $indent) { return Preg::replace('/(\n)(?!\n|$)/', '$1'.str_repeat(' ', $indent), $string); } }