From 0734edf6f0449a0fbbea8c3a2cc73449440bf25a Mon Sep 17 00:00:00 2001
From: William Ballenthin <william.ballenthin@fireeye.com>
Date: Mon, 31 Aug 2020 16:34:10 -0600
Subject: [PATCH 1/3] tests: fmt: add test for #263

---
 tests/test_fmt.py | 22 ++++++++++++++++++++++
 1 file changed, 22 insertions(+)

diff --git a/tests/test_fmt.py b/tests/test_fmt.py
index 1ca4725a..bac79d6c 100644
--- a/tests/test_fmt.py
+++ b/tests/test_fmt.py
@@ -92,6 +92,8 @@ def test_rule_reformat_order():
 
 
 def test_rule_reformat_meta_update():
+    # test updating the rule content after parsing
+
     rule = textwrap.dedent(
         """
         rule:
@@ -112,3 +114,23 @@ def test_rule_reformat_meta_update():
     rule = capa.rules.Rule.from_yaml(rule)
     rule.name = "test rule"
     assert rule.to_yaml() == EXPECTED
+
+
+def test_rule_reformat_string_description():
+    # see #263
+    src = textwrap.dedent(
+        """
+        rule:
+          meta:
+            name: test rule
+            author: user@domain.com
+            scope: function
+          features:
+            - and:
+              - string: foo
+                description: bar
+        """
+    )
+
+    rule = capa.rules.Rule.from_yaml(src)
+    assert rule.to_yaml() == src

From 7e0ebb8c5b1da5f0e5e3451df3a41b3d5c409c36 Mon Sep 17 00:00:00 2001
From: William Ballenthin <william.ballenthin@fireeye.com>
Date: Mon, 31 Aug 2020 16:49:54 -0600
Subject: [PATCH 2/3] rules: fmt: fix formatting of description block

closes #263
---
 capa/rules.py     | 14 +++++++++++++-
 tests/test_fmt.py |  3 ++-
 2 files changed, 15 insertions(+), 2 deletions(-)

diff --git a/capa/rules.py b/capa/rules.py
index 6b9eba58..55ce2014 100644
--- a/capa/rules.py
+++ b/capa/rules.py
@@ -624,7 +624,19 @@ class Rule(object):
                 continue
             meta[key] = value
 
-        return ostream.getvalue().decode("utf-8").rstrip("\n") + "\n"
+        doc = ostream.getvalue().decode("utf-8").rstrip("\n") + "\n"
+        # when we have something like:
+        #
+        #     and:
+        #       - string: foo
+        #         description: bar
+        #
+        # we want the `description` horizontally aligned with the start of the `string`.
+        # tweaking `ruamel.indent()` doesn't quite give us the control we want.
+        # so, add the two extra spaces that we've determined we need through experimentation.
+        # see #263
+        doc = doc.replace("  description:", "    description:")
+        return doc
 
 
 def get_rules_with_scope(rules, scope):
diff --git a/tests/test_fmt.py b/tests/test_fmt.py
index bac79d6c..92bd4ffa 100644
--- a/tests/test_fmt.py
+++ b/tests/test_fmt.py
@@ -117,6 +117,7 @@ def test_rule_reformat_meta_update():
 
 
 def test_rule_reformat_string_description():
+    # the `description` should be aligned with the preceding feature name.
     # see #263
     src = textwrap.dedent(
         """
@@ -130,7 +131,7 @@ def test_rule_reformat_string_description():
               - string: foo
                 description: bar
         """
-    )
+    ).lstrip()
 
     rule = capa.rules.Rule.from_yaml(src)
     assert rule.to_yaml() == src

From 7310b0feda65962b689d2db72382d9fda5f231e4 Mon Sep 17 00:00:00 2001
From: William Ballenthin <william.ballenthin@fireeye.com>
Date: Mon, 31 Aug 2020 16:55:54 -0600
Subject: [PATCH 3/3] rules: documentation formatting

---
 capa/rules.py | 8 +++++++-
 1 file changed, 7 insertions(+), 1 deletion(-)

diff --git a/capa/rules.py b/capa/rules.py
index 55ce2014..81df0c80 100644
--- a/capa/rules.py
+++ b/capa/rules.py
@@ -631,7 +631,13 @@ class Rule(object):
         #       - string: foo
         #         description: bar
         #
-        # we want the `description` horizontally aligned with the start of the `string`.
+        # we want the `description` horizontally aligned with the start of the `string` (like above).
+        # however, ruamel will give us (which I don't think is even valid yaml):
+        #
+        #     and:
+        #       - string: foo
+        #      description: bar
+        #
         # tweaking `ruamel.indent()` doesn't quite give us the control we want.
         # so, add the two extra spaces that we've determined we need through experimentation.
         # see #263