jinja[spacing]: use black for formatting (#2375)

.config/dictionary.txt

@@ -178,6 +178,7 @@ toctree
 toidentifier
 tomli
 toolset
+uncook
 ungrouped
 unignored
 unimported

.github/workflows/tox.yml

@@ -166,7 +166,7 @@ jobs:
       WSLENV: FORCE_COLOR:PYTEST_REQPASS:TOXENV:TOX_PARALLEL_NO_SPINNER
       # Number of expected test passes, safety measure for accidental skip of
       # tests. Update value if you add/remove tests.
-      PYTEST_REQPASS: 698
+      PYTEST_REQPASS: 702
 
     steps:
       - name: Activate WSL1

.pre-commit-config.yaml

@@ -141,6 +141,7 @@ repos:
         additional_dependencies:
           - ansible-compat>=2.2.0
           - ansible-core
+          - black
           - enrich
           - filelock
           - flaky
@@ -167,6 +168,7 @@ repos:
         additional_dependencies:
           - ansible-compat>=2.2.0
           - ansible-core
+          - black
           - docutils
           - enrich
           - filelock

examples/playbooks/jinja-spacing.yml

@@ -82,7 +82,7 @@
 
     - name: Invalid multiline nested JSON
       ansible.builtin.debug:
-        # <-- 8
+        # not an error currently because current implementation skips multiline expressions
         msg: >-
           {{ {'dummy_2': {'nested_dummy_1': value_1,
                           'nested_dummy_2': value_2}} |

examples/playbooks/vars/jinja-spacing.yml

@@ -35,7 +35,7 @@ valid_multiline_nested_json: >-
   {{ {'dummy_2': {'nested_dummy_1': value_1,
                   'nested_dummy_2': value_2}} |
   combine(dummy_1) }}
-invalid_multiline_nested_json: >- # <-- 8
+invalid_multiline_nested_json: >- # ignored multiline expression, for now
   {{ {'dummy_2': {'nested_dummy_1': value_1,
                   'nested_dummy_2': value_2}} |
   combine(dummy_1)}}

setup.cfg

@@ -69,6 +69,7 @@ zip_safe = False
 install_requires =
   ansible-compat>=2.2.0  # GPLv3
   ansible-core>=2.12.0  # GPLv3
+  black>=22.1.0  # MIT
   enrich>=1.2.6
   filelock  # The Unlicense
   jsonschema>=4.9.0  # MIT, version needed for improved errors

src/ansiblelint/rules/jinja.md

@@ -15,18 +15,39 @@ curious how black would reformat a small sniped feel free to visit
 include the entire jinja2 template, so instead of `{{ 1+2==3 }}`, do paste
 only `1+2==3`.
 
+In ansible, `changed_when`, `failed_when`, `until`, `when` are considered to
+use implicit jinja2 templating, meaning that they do not require `{{ }}`. Our
+rule will suggest the removal of the braces for these fields.
+
 ## Problematic code
 
 ```yaml
 ---
-foo: "{{some|dict2items}}" # <-- jinja[spacing]
-bar: "{{ & }}" # <-- jinja[invalid]
+- name: Some task
+  vars:
+    foo: "{{some|dict2items}}" # <-- jinja[spacing]
+    bar: "{{ & }}" # <-- jinja[invalid]
+  when: "{{ foo | bool }}" # <-- jinja[spacing] - 'when' has implicit templating
 ```
 
 ## Correct code
 
 ```yaml
 ---
-foo: "{{ some | dict2items }}"
-bar: "{{ '&' }}"
+- name: Some task
+  vars:
+    foo: "{{ some | dict2items }}"
+    bar: "{{ '&' }}"
+  when: foo | bool
 ```
+
+## Current limitations
+
+In its current form, this rule presents the following limitations:
+
+- Jinja2 blocks that have newlines in them will not be reformatted because we
+  consider that the user deliberately wanted to format them in a particular way.
+- Jinja2 blocks that use tilde as a binary operation are ignored because black
+  does not support tilde as a binary operator. Example: `{{ a ~ b }}`.
+- Jinja2 blocks that use dot notation with numbers are ignored because python
+  and black do not allow it. Example: `{{ foo.0.bar }}`