[#1207] Updated docs for Twig CS Fixer. (#1224)

Co-authored-by: Alex Skrypnyk <[email protected]>

.circleci/config.yml

@@ -260,8 +260,8 @@ jobs:
           name: Lint code with PHPMD
           command: docker compose exec -T cli vendor/bin/phpmd . text phpmd.xml || [ "${DREVOPS_CI_PHPMD_IGNORE_FAILURE:-0}" -eq 1 ]
       - run:
-          name: Lint code with Twigcs
-          command: docker compose exec -T cli vendor/bin/twig-cs-fixer || [ "${DREVOPS_CI_TWIGCS_IGNORE_FAILURE:-0}" -eq 1 ]
+          name: Lint code with Twig CS Fixer
+          command: docker compose exec -T cli vendor/bin/twig-cs-fixer || [ "${DREVOPS_CI_TWIG_CS_FIXER_IGNORE_FAILURE:-0}" -eq 1 ]
       - run:
           name: Lint code with NPM linters
           command: docker compose exec -T cli bash -c "npm run --prefix \${DREVOPS_WEBROOT}/themes/custom/\${DRUPAL_THEME} lint" || [ "${DREVOPS_CI_NPM_LINT_IGNORE_FAILURE:-0}" -eq 1 ]

.drevops/docs/.utils/.aspell.en.pws

@@ -73,7 +73,7 @@ Ssl
 Suboptimal
 TBD
 Terminalizer
-Twigcs
+Twig CS Fixer
 UAT
 UI
 UUID

.drevops/docs/.utils/variables/extra/ci.variables.sh

@@ -21,8 +21,8 @@ DREVOPS_CI_RECTOR_IGNORE_FAILURE=0
 # Ignore PHPMD failures.
 DREVOPS_CI_PHPMD_IGNORE_FAILURE=0
 
-# Ignore Twigcs failures.
-DREVOPS_CI_TWIGCS_IGNORE_FAILURE=0
+# Ignore Twig CS Fixer failures.
+DREVOPS_CI_TWIG_CS_FIXER_IGNORE_FAILURE=0
 
 # Ignore NPM linters failures.
 DREVOPS_CI_NPM_LINT_IGNORE_FAILURE=0

.drevops/docs/content/introduction/architecture.md

@@ -78,7 +78,7 @@ with addition of several configuration files and directories.
 ├── .gitignore               # Intentionally untracked files to ignore in Git.
 ├── .gitignore.deployment    # Intentionally untracked files to ignore in artifact deployment.
 ├── .lagoon.yml              # Lagoon configuration file. Removed if not using Lagoon hosting.
-├── .twig-cs-fixer.php       # Twigcs configuration file.
+├── .twig-cs-fixer.php       # Twig CS Fixer configuration file.
 ├── behat.yml                # Behat configuration file.
 ├── composer.json            # Composer configuration file.
 ├── docker-compose.yml       # Docker Compose configuration file.

.drevops/docs/content/introduction/features.md

@@ -51,7 +51,7 @@ The following list includes ✅ completed  and 💡 upcoming features.
     * ✅ [PHPUnit](https://phpunit.de/)
     * ✅ [SASS Lint](https://github.com/sasstools/sass-lint)
     * ✅ [SASS](https://sass-lang.com/)
-    * ✅ [Twigcs](https://github.com/VincentLanglet/Twig-CS-Fixer)
+    * ✅ [Twig CS Fixer](https://github.com/VincentLanglet/Twig-CS-Fixer)
     * 💡 [Pa11y](https://pa11y.org/)
 * ⚙️ Workflow
     * ✅ Database from FTP, CURL, Docker image, hosting provider

.drevops/docs/content/tools/README.md

@@ -10,20 +10,20 @@ Some of the tools run in CI and would fail the build if they detect issues.
 
 Head over to the tool-specific documentation to learn more.
 
-| Name                            | Description                                                      |
-|---------------------------------|------------------------------------------------------------------|
-| [Ahoy](ahoy.md)                 | CLI command wrapper                                              |
-| [Behat](behat.md)               | Testing framework for for autotesting your business expectations |
-| [Docker](docker.md)             | A platform for containerizing and running applications           |
-| [Doctor](doctor.md)             | Check DrevOps project requirements or print info                 |
-| [Drush](drush.md)               | Command line shell and Unix scripting interface for Drupal       |
-| [Git artifact](git-artifact.md) | Package and push files to remote repositories                    |
-| [PHPCS](phpcs.md)               | Check that code adheres to coding standards                      |
-| [PHPMD](phpmd.md)               | Detect code smells and possible errors                           |
-| [PHPStan](phpstan.md)           | PHP Static Analysis Tool                                         |
-| [PHPUnit](phpunit.md)           | The PHP Testing Framework                                        |
-| [Pygmy](pygmy.md)               | A local reverse-proxy and email catcher                          |
-| [Rector](rector.md)             | Instant Upgrades and Automated Refactoring                       |
-| [Renovate](renovate.md)         | A bot for automated dependency updates                           |
-| [Twigcs](twigcs.md)             | Checkstyle for Twig                                              |
-| [Xdebug](xdebug.md)             | Debugger and Profiler Tool for PHP                               |
+| Name                              | Description                                                      |
+|-----------------------------------|------------------------------------------------------------------|
+| [Ahoy](ahoy.md)                   | CLI command wrapper                                              |
+| [Behat](behat.md)                 | Testing framework for for autotesting your business expectations |
+| [Docker](docker.md)               | A platform for containerizing and running applications           |
+| [Doctor](doctor.md)               | Check DrevOps project requirements or print info                 |
+| [Drush](drush.md)                 | Command line shell and Unix scripting interface for Drupal       |
+| [Git artifact](git-artifact.md)   | Package and push files to remote repositories                    |
+| [PHPCS](phpcs.md)                 | Check that code adheres to coding standards                      |
+| [PHPMD](phpmd.md)                 | Detect code smells and possible errors                           |
+| [PHPStan](phpstan.md)             | PHP Static Analysis Tool                                         |
+| [PHPUnit](phpunit.md)             | The PHP Testing Framework                                        |
+| [Pygmy](pygmy.md)                 | A local reverse-proxy and email catcher                          |
+| [Rector](rector.md)               | Instant Upgrades and Automated Refactoring                       |
+| [Renovate](renovate.md)           | A bot for automated dependency updates                           |
+| [Twig CS Fixer](twig-cs-fixer.md) | Checkstyle for Twig                                              |
+| [Xdebug](xdebug.md)               | Debugger and Profiler Tool for PHP                               |

.drevops/docs/content/tools/twig-cs-fixer.md

@@ -0,0 +1,97 @@
+# Twig CS Fixer
+
+https://github.com/VincentLanglet/Twig-CS-Fixer
+
+> The missing checkstyle for twig!
+>
+> Twig CS Fixer aims to be what phpcs is to php. It checks your codebase for violations on coding standards.
+
+DrevOps comes with [pre-configured Twig-cs-fixer ruleset](../../../../.twig-cs-fixer.php) for Drupal projects.
+
+## Usage
+
+```shell
+vendor/bin/twig-cs-fixer
+```
+or
+```shell
+ahoy lint-fe
+```
+
+## Configuration
+
+See [configuration reference](https://github.com/VincentLanglet/Twig-CS-Fixer/blob/main/docs/configuration.md).
+
+All global configuration takes place in the [`.twig-cs-fixer.php`](../../../../.twig-cs-fixer.php) file.
+
+Targets include custom modules and themes.
+
+Adding or removing targets:
+```php
+$ruleset = new TwigCsFixer\Ruleset\Ruleset();
+$ruleset->addStandard(new TwigCsFixer\Standard\Twig());
+
+$finder = new TwigCsFixer\File\Finder();
+$finder->in(__DIR__ . '/web/modules/custom');
+$finder->in(__DIR__ . '/web/themes/custom');
+
+$config = new TwigCsFixer\Config\Config();
+$config->setRuleset($ruleset);
+$config->setFinder($finder);
+
+return $config;
+```
+
+## Ignoring
+
+Ignoring rules **globally** takes place in the  [`.twig-cs-fixer.php`](../../../../.twig-cs-fixer.php) file:
+```php
+$finder->exclude('myCustomDirectory');
+```
+
+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
+
+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`
+
+If you need to know the errors identifier you have/want to ignore, you can run
+the linter command with the `--debug` option.
+
+To ignore **all Twig CS Fixer rules** within a file, place in the file header:
+```twig
+{# twig-cs-fixer-disable #}
+```
+
+To ignore **a specific rule** within a file, place in the file header:
+```twig
+{# twig-cs-fixer-disable A.B:C:D #}
+```
+
+Twig CS Fixer does not support ignoring of the **code blocks**.
+
+To ignore only the **current line**:
+```twig
+{# twig-cs-fixer-disable-next-line A.B:C:D #}
+```
+
+To ignore only the **next line**:
+```twig
+{# twig-cs-fixer-disable-line A.B:C:D #}
+```
+
+## Ignoring fail in CI
+
+This tool runs in CI by default and fails the build if there are any violations.
+
+Set `DREVOPS_CI_TWIG_CS_FIXER_IGNORE_FAILURE` environment variable to `1` to
+ignore failures. The tool will still run and report violations, if any.

.drevops/docs/content/workflows/variables.md

@@ -170,9 +170,9 @@ Default value: `/tmp/tests`
 
 Defined in: `CI config`
 
-### `DREVOPS_CI_TWIGCS_IGNORE_FAILURE`
+### `DREVOPS_CI_TWIG_CS_FIXER_IGNORE_FAILURE`
 
-Ignore Twigcs failures.
+Ignore Twig CS Fixer failures.
 
 Default value: `UNDEFINED`
 

.drevops/docs/mkdocs.yml

@@ -206,7 +206,7 @@ nav:
       - Pygmy: tools/pygmy.md
       - Rector: tools/rector.md
       - Renovate: tools/renovate.md
-      - Twigcs: tools/twigcs.md
+      - Twig CS Fixer: tools/twig-cs-fixer.md
       - Xdebug: tools/xdebug.md
 
   - 🧩 Integrations:

.drevops/tests/bats/_helper.workflow.bash

@@ -375,7 +375,7 @@ assert_ahoy_lint_fe() {
   ahoy cli rm -f "${webroot}/themes/custom/star_wars/scss/components/_test.scss"
   sync_to_container
 
-  substep "Assert that FE lint failure works for Twigcs"
+  substep "Assert that FE lint failure works for Twig CS Fixer"
   mkdir -p "${webroot}/modules/custom/sw_core/templates/block"
   mkdir -p "${webroot}/themes/custom/star_wars/templates/block"
   echo "{{ set a='a' }}" >>"${webroot}/modules/custom/sw_core/templates/block/test1.twig"