feat: Enhanced Markdown Report Formatting and Readability (#30)

* fix(plan_report): move Analysis header after if statement

* fix(plan_report): format to CommonMark standards

* feat(plan_report): add link to tfsumpy in footer

* fix(plan_report): Use Jinja2 whitespace controls

(- in {%- and -%})

* style(plan_report): add markdownlint-disable-next-line comments

where Jinja2 functions and Markdown headers should be immedialy next to each other, so additional line breaks are not rendered

* fix(plan_report): Jinja2 whitespace controls for `--detailed` output

* style(plan_report): customize attribute output based on its resource.action

only show both before and after attributes when an action is update or replace

* style(plan_report): show change.attributes Before and After values in Block Quote Style

This is intended to make it easier to read and compare longer values

* test(plan_report): update test criteria

Author: bcdady

tests/plan/test_plan_reporter.py

@@ -134,10 +134,12 @@ def test_print_report_markdown_with_details(self, reporter, sample_report_data):
 
             # Verify detailed information
             assert '## Resource Changes' in written_text
-            assert '### Details:' in written_text
+            assert '#### Details for aws_s3_bucket.data_bucket' in written_text
+            assert '#### Details for aws_instance.web_server' in written_text
+            assert '#### Details for aws_security_group.old_sg' in written_text
             assert '**Provider**:' in written_text
             assert '**Module**:' in written_text
-            assert '**Dependencies**:' in written_text
+            # Dependencies is optional and only shown if they exist
 
     def test_print_report_json(self, reporter, sample_report_data):
         """Test JSON report generation."""

tfsumpy/templates/plan_report.md

@@ -1,39 +1,69 @@
 # Terraform Plan Analysis Report
 
 ## Summary
+
 - **Total Resources**: {{ total_resources }}
 - **Resources to Add**: {{ resources_to_add }}
 - **Resources to Change**: {{ resources_to_change }}
 - **Resources to Destroy**: {{ resources_to_destroy }}
 
 ## Resource Changes
+
 {% for resource in resources %}
+{# <!-- markdownlint-disable-next-line MD022 --> #}
 ### {{ resource.resource_type }}.{{ resource.identifier }}
-**Action:** {{ resource.action | upper }}
+
+**Action:** {{ resource.action | title }}
+
 {% if resource.replacement and resource.replacement_triggers %}
-- **Replacement triggered by:** {{ resource.replacement_triggers | join(', ') }}
+{# <!-- markdownlint-disable-next-line MD032 --> #}
+**Replacement triggered by:** {{ resource.replacement_triggers | join(', ') }}
 {% endif %}
 {% if resource.changes %}
-#### Changes:
+{# <!-- markdownlint-disable-next-line MD022 --> #}
+#### Changes for {{ resource.resource_type }}.{{ resource.identifier }}
+
 {% for change in resource.changes %}
-- **{{ change.attribute }}**: {{ change.before }} → {{ change.after }}
+{# <!-- markdownlint-disable MD032 --> #}
+{% if resource.action == 'create' %}
+- **{{ change.attribute }}**: {{ change.after }}
+{% elif resource.action == 'delete' %}
+- **{{ change.attribute }}**: {{ change.before }}
+{% else %}
+- **{{ change.attribute }}**:
+  - Before: {{ change.before }}
+  - After:  {{ change.after }}
+{% endif %}
+{# <!-- markdownlint-enable MD032 --> #}
 {% endfor %}
 {% endif %}
 {% if show_details %}
-#### Details:
+{# <!-- markdownlint-disable-next-line MD032 --> #}
+
+#### Details for {{ resource.resource_type }}.{{ resource.identifier }}
+
 - **Provider**: {{ resource.provider }}
 - **Module**: {{ resource.module }}
+{% if resource.dependencies %}
 - **Dependencies**: {{ resource.dependencies|join(', ') }}
 {% endif %}
+{# end if show_details #}
+{% endif %}
+{# The next line is blank so an empty line is rendered after Details #}
+
 {% endfor %}
 
+{%- if analysis and analysis|length > 0 -%}
+{# <!-- markdownlint-disable-next-line MD022 --> #}
 ## Analysis
-{% if analysis %}
-{% for item in analysis %}
+
+{%- for item in analysis -%}
+{# <!-- markdownlint-disable-next-line MD022 --> #}
 ### {{ item.title }}
+
+{# <!-- markdownlint-disable-line MD003 MD022 --> #}
 {{ item.description }}
 {% endfor %}
 {% endif %}
-
 ---
-*Generated by tfsumpy on {{ timestamp }}* 
+*Generated by [tfsumpy](https://github.com/rafaelherik/tfsumpy) on {{ timestamp }}*