Merge pull request #27 from codelicia/report

Add checkstyle output

README.md

@@ -5,25 +5,25 @@
 [![All Contributors](https://img.shields.io/badge/all_contributors-3-orange.svg?style=flat-square)](#contributors-)
 <!-- ALL-CONTRIBUTORS-BADGE:END -->
 
-**Xulieta** is a light php binary that find code snippets thought out 
-documentation files — as for example `*.md`, `*.markdown` and `*.rst` 
+**Xulieta** is a light php binary that find code snippets thought out
+documentation files — as for example `*.md`, `*.markdown` and `*.rst`
 — and lint the pieces of code, so you can find basic documentation errors.
 
-**NOTE**: For now we just lint PHP code. 
+**NOTE**: For now we just lint PHP code.
 
 ### Installation
 
 ```shell script
-composer require codelicia/xulieta 
+composer require codelicia/xulieta
 ```
 
 ### Checking for errors
 
 <table>
 <tr>
-<td><img src="./meme.jpg"  alt="Xulieta" width="300" height="214"/></td> 
+<td><img src="./meme.jpg"  alt="Xulieta" width="300" height="214"/></td>
 <td>
-In order to lint the basics of documentation structure, one just needs to provide a path for a 
+In order to lint the basics of documentation structure, one just needs to provide a path for a
 directory or file to be linted.
 
 ```shell script
@@ -33,7 +33,24 @@ directory or file to be linted.
 </tr>
 </table>
 
-### Configuration
+### Integration with GitHub Actions
+
+We provide out  of the box an  `output` format that you can  use to have
+automatic  feedback from  GitHub  CI.  That is  done  by specifying  the
+`checkstyle` output and passing it to some external binary that does the
+commenting.
+
+We recommend the usage of [cs2pr](https://github.com/staabm/annotate-pull-request-from-checkstyle).
+
+```
+./vendor/bin/xulieta check:erromeu <directory> --output=checkstyle | cs2pr
+```
+
+#### Commenting example
+
+<img src="./github-action.png"  alt="Codelicia\Xulieta" />
+
+### Advanced Configuration
 
 **Xulieta** tries to find a `.xulieta.xml` file in the root of your project
 with the following configuration format:

src/Command/App.php

@@ -5,13 +5,16 @@
 namespace Codelicia\Xulieta\Command;
 
 use Codelicia\Xulieta\DocFinder;
+use Codelicia\Xulieta\Output\Checkstyle;
+use Codelicia\Xulieta\Output\Stdout;
 use Codelicia\Xulieta\Plugin\MultiplePlugin;
 use Codelicia\Xulieta\Plugin\Plugin;
 use InvalidArgumentException;
 use RuntimeException;
 use Symfony\Component\Console\Command\Command;
 use Symfony\Component\Console\Input\InputArgument;
 use Symfony\Component\Console\Input\InputInterface;
+use Symfony\Component\Console\Input\InputOption;
 use Symfony\Component\Console\Output\OutputInterface;
 use Symfony\Component\Finder\SplFileInfo;
 use Webmozart\Assert\Assert;
@@ -42,6 +45,13 @@ protected function configure() : void
         $this
             ->setName('check:erromeu')
             ->setDescription('Lint code snippets through the documentation "directory"')
+            ->addOption(
+                'output',
+                'o',
+                InputOption::VALUE_OPTIONAL,
+                'Specify output format, it can be "checkstyle" or "stdout"',
+                'stdout'
+            )
             ->addArgument(
                 'directory',
                 InputArgument::REQUIRED,
@@ -55,9 +65,15 @@ protected function configure() : void
      * @throws InvalidArgumentException
      * @throws RuntimeException
      */
-    protected function execute(InputInterface $input, OutputInterface $output) : int
+    protected function execute(InputInterface $input, OutputInterface $symfonyOutput) : int
     {
-        $directory = $input->getArgument('directory');
+        $directory    = $input->getArgument('directory');
+        $outputOption = $input->getOption('output');
+        $output       = new Stdout($symfonyOutput);
+
+        if ($outputOption === 'checkstyle') {
+            $output = new Checkstyle($symfonyOutput);
+        }
 
         Assert::string($directory);
         Assert::interfaceExists(Plugin::class);

src/Output/Checkstyle.php

@@ -0,0 +1,48 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Codelicia\Xulieta\Output;
+
+use Codelicia\Xulieta\ValueObject\Violation;
+use Symfony\Component\Console\Output\OutputInterface;
+use function htmlspecialchars;
+
+final class Checkstyle implements OutputFormatter
+{
+    private OutputInterface $output;
+
+    public function __construct(OutputInterface $output)
+    {
+        $this->output = $output;
+        $this->output->writeln('<?xml version="1.0" encoding="UTF-8"?>');
+        $this->output->writeln('<checkstyle>');
+    }
+
+    public function addViolation(Violation $violation) : void
+    {
+        $this->output->writeln('  <file name="' . htmlspecialchars($violation->file()) . '">');
+
+        $error  = '    ';
+        $error .= '<error';
+        $error .= ' line="' . $violation->absoluteLine() . '"';
+        $error .= ' column="1"';
+        $error .= ' severity="error"';
+        $error .= ' message="Codelicia/Xulieta: ' . htmlspecialchars($violation->message()) . '"';
+        $error .= ' source="Codelicia/Xulieta"';
+        $error .= '/>';
+
+        $this->output->writeln($error);
+        $this->output->writeln('  </file>');
+    }
+
+    public function __destruct()
+    {
+        echo '</checkstyle>';
+    }
+
+    public function writeln(string $text) : void
+    {
+        // Intentionally left empty
+    }
+}

src/Output/OutputFormatter.php

@@ -0,0 +1,14 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Codelicia\Xulieta\Output;
+
+use Codelicia\Xulieta\ValueObject\Violation;
+
+interface OutputFormatter
+{
+    public function addViolation(Violation $violation) : void;
+
+    public function writeln(string $text) : void;
+}

src/Output/Stdout.php

@@ -0,0 +1,31 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Codelicia\Xulieta\Output;
+
+use Codelicia\Xulieta\ValueObject\Violation;
+use Symfony\Component\Console\Output\OutputInterface;
+use const PHP_EOL;
+
+final class Stdout implements OutputFormatter
+{
+    private OutputInterface $output;
+
+    public function __construct(OutputInterface $output)
+    {
+        $this->output = $output;
+    }
+
+    public function addViolation(Violation $violation) : void
+    {
+        $this->writeln('<error>Wrong code on file: ' . $violation->code()->file() . '</error>');
+        $this->writeln($violation->message() . PHP_EOL);
+        $this->writeln($violation->code()->code());
+    }
+
+    public function writeln(string $text) : void
+    {
+        $this->output->writeln($text);
+    }
+}

src/Plugin/MultiplePlugin.php

@@ -5,7 +5,7 @@
 namespace Codelicia\Xulieta\Plugin;
 
 use Assert\Assert;
-use Symfony\Component\Console\Output\OutputInterface;
+use Codelicia\Xulieta\Output\OutputFormatter;
 use Symfony\Component\Finder\SplFileInfo;
 use function array_map;
 use function array_merge_recursive;
@@ -44,7 +44,7 @@ public function canHandle(SplFileInfo $file) : bool
         return false;
     }
 
-    public function __invoke(SplFileInfo $file, OutputInterface $output) : bool
+    public function __invoke(SplFileInfo $file, OutputFormatter $output) : bool
     {
         foreach ($this->plugins as $plugin) {
             if ($plugin->canHandle($file)) {

src/Plugin/PhpOnMarkdownPlugin.php

@@ -7,10 +7,11 @@
 use Codelicia\Xulieta\External\Markinho;
 use Codelicia\Xulieta\Lint\Lint;
 use Codelicia\Xulieta\Lint\PhpLint;
-use Symfony\Component\Console\Output\OutputInterface;
+use Codelicia\Xulieta\Output\OutputFormatter;
+use Codelicia\Xulieta\ValueObject\Violation;
 use Symfony\Component\Finder\SplFileInfo;
 use function in_array;
-use const PHP_EOL;
+use function preg_match;
 
 final class PhpOnMarkdownPlugin implements Plugin
 {
@@ -32,17 +33,21 @@ public function canHandle(SplFileInfo $file) : bool
         return in_array($file->getExtension(), $this->supportedExtensions(), true);
     }
 
-    public function __invoke(SplFileInfo $file, OutputInterface $output) : bool
+    public function __invoke(SplFileInfo $file, OutputFormatter $output) : bool
     {
         foreach (Markinho::extractCodeBlocks($file->getPathname(), $file->getContents()) as $codeBlock) {
             if ($codeBlock->language() !== 'php') {
                 continue;
             }
 
             if ($this->phpLint->hasViolation($codeBlock->code())) {
-                $output->writeln('<error>Wrong code on file: ' . $codeBlock->file() . '</error>');
-                $output->writeln($this->phpLint->getViolation($codeBlock->code()) . PHP_EOL);
-                $output->writeln($codeBlock->code());
+                $message = $this->phpLint->getViolation($codeBlock->code());
+
+                preg_match('{on line (\d+)}', $message, $line);
+
+                $validationErrorInLine = $line[1] ?? 0;
+
+                $output->addViolation(new Violation($codeBlock, $message, (int) $validationErrorInLine));
 
                 return false;
             }

src/Plugin/PhpOnRstPlugin.php

@@ -6,11 +6,13 @@
 
 use Codelicia\Xulieta\Lint\Lint;
 use Codelicia\Xulieta\Lint\PhpLint;
+use Codelicia\Xulieta\Output\OutputFormatter;
 use Codelicia\Xulieta\Parser\Parser;
 use Codelicia\Xulieta\Parser\RstParser;
-use Symfony\Component\Console\Output\OutputInterface;
+use Codelicia\Xulieta\ValueObject\Violation;
 use Symfony\Component\Finder\SplFileInfo;
 use function in_array;
+use function preg_match;
 use const PHP_EOL;
 
 final class PhpOnRstPlugin implements Plugin
@@ -35,7 +37,7 @@ public function canHandle(SplFileInfo $file) : bool
         return in_array($file->getExtension(), $this->supportedExtensions(), true);
     }
 
-    public function __invoke(SplFileInfo $file, OutputInterface $output) : bool
+    public function __invoke(SplFileInfo $file, OutputFormatter $output) : bool
     {
         if (! $this->rstParser->isValid($file)) {
             $output->writeln(PHP_EOL . '<error>Error parsing file: ' . $file->getRelativePath() . '</error>');
@@ -49,9 +51,13 @@ public function __invoke(SplFileInfo $file, OutputInterface $output) : bool
             }
 
             if ($this->phpLint->hasViolation($sampleCode->code())) {
-                $output->writeln('<error>Wrong code on file: ' . $sampleCode->file() . '</error>');
-                $output->writeln($this->phpLint->getViolation($sampleCode->code()) . PHP_EOL);
-                $output->writeln($sampleCode->code());
+                $message = $this->phpLint->getViolation($sampleCode->code());
+
+                preg_match('{on line (\d+)}', $message, $line);
+
+                $validationErrorInLine = $line[1] ?? 0;
+
+                $output->addViolation(new Violation($sampleCode, $message, (int) $validationErrorInLine));
 
                 return false;
             }

src/Plugin/Plugin.php

@@ -4,7 +4,7 @@
 
 namespace Codelicia\Xulieta\Plugin;
 
-use Symfony\Component\Console\Output\OutputInterface;
+use Codelicia\Xulieta\Output\OutputFormatter;
 use Symfony\Component\Finder\SplFileInfo;
 
 interface Plugin
@@ -14,5 +14,5 @@ public function supportedExtensions() : array;
 
     public function canHandle(SplFileInfo $file) : bool;
 
-    public function __invoke(SplFileInfo $file, OutputInterface $output) : bool;
+    public function __invoke(SplFileInfo $file, OutputFormatter $output) : bool;
 }

src/ValueObject/Violation.php

@@ -0,0 +1,47 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Codelicia\Xulieta\ValueObject;
+
+final class Violation
+{
+    private SampleCode $code;
+    private string $message;
+    private int $violationLine;
+
+    public function __construct(
+        SampleCode $code,
+        string $message,
+        int $violationLine = 0
+    ) {
+        $this->code          = $code;
+        $this->message       = $message;
+        $this->violationLine = $violationLine;
+    }
+
+    public function code() : SampleCode
+    {
+        return $this->code;
+    }
+
+    public function file() : string
+    {
+        return $this->code->file();
+    }
+
+    public function violationLine() : int
+    {
+        return $this->violationLine;
+    }
+
+    public function message() : string
+    {
+        return $this->message;
+    }
+
+    public function absoluteLine() : int
+    {
+        return $this->code()->position() + $this->violationLine();
+    }
+}

tests/assets/syntax-error-checkstyle.md

@@ -0,0 +1,10 @@
+This code has a missing semi comma on the echo statement.
+
+```php
+<?php
+
+if (true) {
+    echo 'Hello World!'
+}
+```
+

tests/functional/md-syntax-error-checkstyle.phpt

@@ -0,0 +1,16 @@
+--TEST--
+Report a warning using checkstyle in case of missing PHP open tag
+--FILE--
+<?php
+
+$checkRunner = require __DIR__ . '/init.php';
+
+$checkRunner('tests/assets/syntax-error-checkstyle.md --output=checkstyle');
+
+--EXPECTF--
+<?xml version="1.0" encoding="UTF-8"?>
+<checkstyle>
+  <file name="tests/assets/syntax-error-checkstyle.md">
+    <error line="7" column="1" severity="error" message="Codelicia/Xulieta: Syntax error, unexpected '}', expecting ';' on line 5" source="Codelicia/Xulieta"/>
+  </file>
+</checkstyle>