Provide a way to ignore error on specific lines (#162)

README.md

@@ -59,112 +59,6 @@ Removes any space before and after opening and closing of arrays and hashes.
 
 ## Custom configuration
 
-### Standard
-
-By default, the twig-cs-fixer standard is enabled with the twig coding standard rules and the following rules:
-
- - `BlankEOFRule`: ensures that files end with one blank line.
- - `BlockNameSpacingRule`: ensure there is one space before and after block names.
- - `EmptyLinesRule`: ensures that 2 empty lines do not follow each other.
- - `IndentRule`: ensures that files are not indented with tabs.
- - `TrailingCommaSingleLineRule`: ensures that single-line arrays, objects and argument lists do not have a trailing comma.
- - `TrailingSpaceRule`: ensures that files have no trailing spaces.
-
-If you want to use the basic Twig standard, another standard and/or add/disable a rule, you can provide
-your own configuration with a `.twig-cs-fixer.php` file which returns a `TwigCsFixer\Config\Config` class:
-
-```php
-<?php
-
-$ruleset = new TwigCsFixer\Ruleset\Ruleset();
-$ruleset->addStandard(new TwigCsFixer\Standard\Twig());
-$ruleset->addRule(\TwigCsFixer\Rules\Whitespace\EmptyLinesRule::class);
-
-$config = new TwigCsFixer\Config\Config();
-$config->setRuleset($ruleset);
-
-return $config;
-```
-
-If your config is not located in your current directory, you can specify its path using `--config` when running the command:
-
-```bash
-vendor/bin/twig-cs-fixer lint --config=dir/.twig-cs-fixer.php /path/to/code
-```
-
-### Files
-
-By default, all `.twig` files in the current directory are linted, except the ones in the `vendor` directory.
-
-If you want to lint specific files or directories you can pass them as argument. If you want a more sophisticated
-rule, you can configure it in the `.twig-cs-fixer.php` file:
-
-```php
-<?php
-
-$finder = new TwigCsFixer\File\Finder();
-$finder->exclude('myCustomDirectory');
-
-$config = new TwigCsFixer\Config\Config();
-$config->setFinder($finder);
-
-return $config;
-```
-
-### Cache
-
-By default, cache is enabled and stored in `.twig-cs-fixer.cache`. Further runs are therefore much
-faster. Cache is invalidated when a different PHP version, twig-cs-fixer version or ruleset is used.
-
-If you want a custom cache location you can configure it in `.twig-cs-fixer.php`:
-
-```php
-<?php
-
-$config = new TwigCsFixer\Config\Config();
-$config->setCacheFile('/tmp/.twig-cs-fixer.cache');
-
-return $config;
-```
-
-To disable cache you can either pass `--no-cache` when running the command:
-
-```bash
-vendor/bin/twig-cs-fixer lint --no-cache
-```
-
-or set the cache file to `null` in your config:
-
-```php
-<?php
-
-$config = new TwigCsFixer\Config\Config();
-$config->setCacheFile(null);
-
-return $config;
-```
-
-### Token parser
-
-If you're using custom token parsers or binary/unary operators, they can be added in your config:
-
-```php
-<?php
-
-$config = new TwigCsFixer\Config\Config();
-$config->addTwigExtension(new App\Twig\CustomTwigExtension());
-$config->addTokenParser(new App\Twig\CustomTokenParser());
-
-return $config;
-```
-
-### Reporter
-
-The `--report` option allows to choose the output format for the linter report.
-
-Supported formats are:
-- `text` selected by default.
-- `checkstyle` following the common checkstyle XML schema.
-- `github` if you want annotations on GitHub actions.
-- `junit` following JUnit schema XML from Jenkins.
-- `null` if you don't want any reporting.
+- [CLI options](docs/command.md)
+- [Configuration file](docs/configuration.md)
+- [How to disable a rule on a specific file or line](docs/identifiers.md)

docs/command.md

@@ -0,0 +1,19 @@
+# CLI options
+
+## Reporter
+
+The `--report` option allows to choose the output format for the linter report.
+
+Supported formats are:
+- `text` selected by default.
+- `checkstyle` following the common checkstyle XML schema.
+- `github` if you want annotations on GitHub actions.
+- `junit` following JUnit schema XML from Jenkins.
+- `null` if you don't want any reporting.
+
+## Debug mode
+
+The `--debug` option displays error identifiers instead of messages. This is
+useful if you want to disable a specific error with a comment in your code.
+
+See also [how to disable a rule on a specific file or line](identifiers.md).

docs/configuration.md

@@ -0,0 +1,100 @@
+# Configuration file
+
+## Standard
+
+By default, the twig-cs-fixer standard is enabled with the twig coding standard rules and the following rules:
+
+- `BlankEOFRule`: ensures that files end with one blank line.
+- `BlockNameSpacingRule`: ensure there is one space before and after block names.
+- `EmptyLinesRule`: ensures that 2 empty lines do not follow each other.
+- `IndentRule`: ensures that files are not indented with tabs.
+- `TrailingCommaSingleLineRule`: ensures that single-line arrays, objects and argument lists do not have a trailing comma.
+- `TrailingSpaceRule`: ensures that files have no trailing spaces.
+
+If you want to use the basic Twig standard, another standard and/or add/disable a rule, you can provide
+your own configuration with a `.twig-cs-fixer.php` file which returns a `TwigCsFixer\Config\Config` class:
+
+```php
+<?php
+
+$ruleset = new TwigCsFixer\Ruleset\Ruleset();
+$ruleset->addStandard(new TwigCsFixer\Standard\Twig());
+$ruleset->addRule(\TwigCsFixer\Rules\Whitespace\EmptyLinesRule::class);
+
+$config = new TwigCsFixer\Config\Config();
+$config->setRuleset($ruleset);
+
+return $config;
+```
+
+If your config is not located in your current directory, you can specify its path using `--config` when running the command:
+
+```bash
+vendor/bin/twig-cs-fixer lint --config=dir/.twig-cs-fixer.php /path/to/code
+```
+
+## Files
+
+By default, all `.twig` files in the current directory are linted, except the ones in the `vendor` directory.
+
+If you want to lint specific files or directories you can pass them as argument. If you want a more sophisticated
+rule, you can configure it in the `.twig-cs-fixer.php` file:
+
+```php
+<?php
+
+$finder = new TwigCsFixer\File\Finder();
+$finder->exclude('myCustomDirectory');
+
+$config = new TwigCsFixer\Config\Config();
+$config->setFinder($finder);
+
+return $config;
+```
+
+## Cache
+
+By default, cache is enabled and stored in `.twig-cs-fixer.cache`. Further runs are therefore much
+faster. Cache is invalidated when a different PHP version, twig-cs-fixer version or ruleset is used.
+
+If you want a custom cache location you can configure it in `.twig-cs-fixer.php`:
+
+```php
+<?php
+
+$config = new TwigCsFixer\Config\Config();
+$config->setCacheFile('/tmp/.twig-cs-fixer.cache');
+
+return $config;
+```
+
+To disable cache you can either pass `--no-cache` when running the command:
+
+```bash
+vendor/bin/twig-cs-fixer lint --no-cache
+```
+
+or set the cache file to `null` in your config:
+
+```php
+<?php
+
+$config = new TwigCsFixer\Config\Config();
+$config->setCacheFile(null);
+
+return $config;
+```
+
+## Token parser & Twig Extension
+
+If you're using custom token parsers or binary/unary operators, they can be added in your config:
+
+```php
+<?php
+
+$config = new TwigCsFixer\Config\Config();
+$config->addTwigExtension(new App\Twig\CustomTwigExtension());
+$config->addTokenParser(new App\Twig\CustomTokenParser());
+
+return $config;
+```

docs/identifiers.md

@@ -0,0 +1,45 @@
+# How to disable a rule on a specific file or line
+
+All errors have an identifier with the syntax: `A.B:C:D` with
+- A: The rule short name (mainly made from the class name)
+- B: The error identifier (like the error level or a specific name)
+- C: The line the error occurs
+- D: The position of the token in the line the error occurs
+
+NB: The four parts are optional, all those format are working
+- A
+- A.B
+- A.B:C
+- A.B:C:D
+- A:C
+- A:C:D
+- A::D
+
+When you want to disable a rule, you can use of the following syntax:
+```twig
+{# twig-cs-fixer-disable A.B:C:D #} => Apply to the whole file
+{# twig-cs-fixer-disable-line A.B:C:D #} => Apply to the line of the comment
+{# twig-cs-fixer-disable-next-line A.B:C:D #} => Apply to the next line of the comment
+```
+
+For instance:
+```twig
+{# twig-cs-fixer-disable #} => Disable every rule for the whole file
+{# twig-cs-fixer-disable-line #} => Disable every rule for the current line
+{# twig-cs-fixer-disable-next-line #} => Disable every rule for the next line
+
+{# twig-cs-fixer-disable A #} => Disable the rule A for the whole file
+{# twig-cs-fixer-disable A:42 #} => Disable the rule A for the line 42 of the file
+{# twig-cs-fixer-disable-line A.B #} => Disable the error B of the rule A for the current line
+{# twig-cs-fixer-disable-next-line A::42 #} => Disable the rule A for the next line but only for the token 42
+```
+
+You can also disable multiple errors with a single comment, by separating them
+with a space or a comma:
+```twig
+{# twig-cs-fixer-disable A B C #} => Disable A and B and C for the whole file
+{# twig-cs-fixer-disable-line A.B,C.D #} => Disable A.B and C.D for the current line
+```
+
+If you need to know the errors identifier you have/want to ignore, you can run the 
+linter command with the `--debug` options. See also [the command options](command.md).

src/Command/TwigCsFixerCommand.php

@@ -70,6 +70,12 @@ protected function configure(): void
                     InputOption::VALUE_NONE,
                     'Disable cache while running the fixer'
                 ),
+                new InputOption(
+                    'debug',
+                    '',
+                    InputOption::VALUE_NONE,
+                    'Display error identifiers instead of messages',
+                ),
             ])
         ;
     }
@@ -129,7 +135,7 @@ private function runLinter(Config $config, InputInterface $input, OutputInterfac
 
         $reporterFactory = new ReporterFactory();
         $reporter = $reporterFactory->getReporter($input->getOption('report'));
-        $reporter->display($output, $report, $input->getOption('level'));
+        $reporter->display($output, $report, $input->getOption('level'), $input->getOption('debug'));
 
         return $report;
     }

src/Report/Reporter/CheckstyleReporter.php

@@ -12,8 +12,12 @@ final class CheckstyleReporter implements ReporterInterface
 {
     public const NAME = 'checkstyle';
 
-    public function display(OutputInterface $output, Report $report, ?string $level = null): void
-    {
+    public function display(
+        OutputInterface $output,
+        Report $report,
+        ?string $level,
+        bool $debug
+    ): void {
         $text = '<?xml version="1.0" encoding="UTF-8"?>'."\n";
 
         $text .= '<checkstyle>'."\n";
@@ -38,7 +42,7 @@ public function display(OutputInterface $output, Report $report, ?string $level
                     $text .= ' column="'.$linePosition.'"';
                 }
                 $text .= ' severity="'.strtolower(Violation::getLevelAsString($violation->getLevel())).'"';
-                $text .= ' message="'.$this->xmlEncode($violation->getMessage()).'"';
+                $text .= ' message="'.$this->xmlEncode($violation->getDebugMessage($debug)).'"';
                 if (null !== $ruleName) {
                     $text .= ' source="'.$ruleName.'"';
                 }

src/Report/Reporter/GithubReporter.php

@@ -17,8 +17,12 @@ final class GithubReporter implements ReporterInterface
 {
     public const NAME = 'github';
 
-    public function display(OutputInterface $output, Report $report, ?string $level = null): void
-    {
+    public function display(
+        OutputInterface $output,
+        Report $report,
+        ?string $level,
+        bool $debug
+    ): void {
         $violations = $report->getViolations($level);
         foreach ($violations as $violation) {
             $text = match ($violation->getLevel()) {
@@ -40,7 +44,7 @@ public function display(OutputInterface $output, Report $report, ?string $level
 
             // newlines need to be encoded
             // see https://github.com/actions/starter-workflows/issues/68#issuecomment-581479448
-            $text .= '::'.str_replace("\n", '%0A', $violation->getMessage());
+            $text .= '::'.str_replace("\n", '%0A', $violation->getDebugMessage($debug));
 
             $output->writeln($text);
         }

src/Report/Reporter/JUnitReporter.php

@@ -12,8 +12,12 @@ final class JUnitReporter implements ReporterInterface
 {
     public const NAME = 'junit';
 
-    public function display(OutputInterface $output, Report $report, ?string $level = null): void
-    {
+    public function display(
+        OutputInterface $output,
+        Report $report,
+        ?string $level,
+        bool $debug
+    ): void {
         $violations = $report->getViolations($level);
         $count = \count($violations);
 
@@ -30,7 +34,7 @@ public function display(OutputInterface $output, Report $report, ?string $level
                 $text .= $this->createTestCase(
                     sprintf('%s:%s', $violation->getFilename(), $violation->getLine() ?? 0),
                     strtolower(Violation::getLevelAsString($violation->getLevel())),
-                    $violation->getMessage()
+                    $violation->getDebugMessage($debug)
                 );
             }
         } else {

src/Report/Reporter/NullReporter.php

@@ -14,7 +14,11 @@ final class NullReporter implements ReporterInterface
 {
     public const NAME = 'null';
 
-    public function display(OutputInterface $output, Report $report, ?string $level = null): void
-    {
+    public function display(
+        OutputInterface $output,
+        Report $report,
+        ?string $level,
+        bool $debug
+    ): void {
     }
 }