Add result markdown docs (#21)

Signed-off-by: Patrick Abrahão <patrick@ivex.ai>

qc_baselib/result.py

@@ -100,6 +100,62 @@ def write_to_file(self, xml_output_file_path: str) -> None:
             )
             report_xml_file.write(xml_text)
 
+    def write_markdown_doc(self, markdown_file_path: str) -> None:
+        if self._report_results is None:
+            raise RuntimeError(
+                "Report documentation dump with empty report, the report needs to be loaded first"
+            )
+
+        bundles_text = "# Checker bundles\n\n"
+        for bundle in self._report_results.checker_bundles:
+            bundle_text = ""
+            bundle_text += f"## Checker bundle: **{bundle.name}**\n"
+            bundle_text += f"- Build date:     {bundle.build_date}\n"
+            bundle_text += f"- Build version:  {bundle.version}\n"
+            bundle_text += f"- Description:    {bundle.description}\n"
+            bundle_text += f"- Summary:        {bundle.summary}\n"
+
+            bundle_text += "\n"
+            bundle_text += f"### Parameters:\n"
+            param_text = ""
+            for param in bundle.params:
+                param_text += f"1. {param.name} = {param.value}\n"
+
+            if len(param_text) == 0:
+                param_text += f"* None\n"
+
+            bundle_text += param_text
+
+            bundle_text += "\n"
+            bundle_text += f"### Checkers:\n"
+            checker_text = ""
+            for checker in bundle.checkers:
+                checker_text += "\n"
+                checker_text += f"#### Checker:     {checker.checker_id}\n"
+                checker_text += f"* Description: {checker.description}\n"
+                checker_text += f"* Status:      {checker.status.value if checker.status is not None else ''}\n"
+                checker_text += f"* Summary:     {checker.summary}\n"
+
+                checker_text += f"+ Addressed rules:\n"
+                rule_text = ""
+                for rule in checker.addressed_rule:
+                    rule_text += f"    1. {rule.rule_uid}\n"
+
+                if len(rule_text) == 0:
+                    rule_text += f"    * None"
+
+                checker_text += rule_text
+
+            if len(checker_text) == 0:
+                checker_text += f"* None"
+
+            bundle_text += checker_text
+
+            bundles_text += bundle_text
+
+        with open(markdown_file_path, "wb") as doc_file:
+            doc_file.write(bundles_text.encode())
+
     def set_result_version(self, version: str) -> None:
         if self._report_results is None:
             self.version = version

tests/data/result_markdown_docs.md

@@ -0,0 +1,19 @@
+# Checker bundles
+
+## Checker bundle: **TestBundle**
+- Build date:     2024-05-31
+- Build version:  0.0.1
+- Description:    Example checker bundle
+- Summary:        Tested example checkers
+
+### Parameters:
+* None
+
+### Checkers:
+
+#### Checker:     TestChecker
+* Description: Test checker
+* Status:      completed
+* Summary:     Executed evaluation
++ Addressed rules:
+    1. test.com:qc:1.0.0:qwerty.qwerty

tests/test_result.py

@@ -9,7 +9,9 @@
 DEMO_REPORT_PATH = "tests/data/demo_checker_bundle.xqar"
 EXTENDED_DEMO_REPORT_PATH = "tests/data/demo_checker_bundle_extended.xqar"
 EXAMPLE_OUTPUT_REPORT_PATH = "tests/data/result_test_output.xqar"
+EXAMPLE_OUTPUT_MARKDOWN_DOC_PATH = "tests/data/result_markdown_docs.md"
 TEST_REPORT_OUTPUT_PATH = "tests/result_test_output.xqar"
+TEST_MARKDOWN_DOC_OUTPUT_PATH = "tests/result_markdown_docs.md"
 
 
 @pytest.fixture
@@ -579,3 +581,67 @@ def test_get_issue_by_rule_uid() -> None:
         == f"Issue found at odr on rule uid {rule_uid_2}"
     )
     assert rule_uid_2_issues[0].level == IssueSeverity.INFORMATION
+
+
+def test_markdown_docs_output():
+    result = Result()
+
+    result.register_checker_bundle(
+        name="TestBundle",
+        build_date="2024-05-31",
+        description="Example checker bundle",
+        version="0.0.1",
+        summary="Tested example checkers",
+    )
+
+    result.register_checker(
+        checker_bundle_name="TestBundle",
+        checker_id="TestChecker",
+        description="Test checker",
+        summary="Executed evaluation",
+    )
+
+    rule_uid = result.register_rule(
+        checker_bundle_name="TestBundle",
+        checker_id="TestChecker",
+        emanating_entity="test.com",
+        standard="qc",
+        definition_setting="1.0.0",
+        rule_full_name="qwerty.qwerty",
+    )
+
+    issue_id = result.register_issue(
+        checker_bundle_name="TestBundle",
+        checker_id="TestChecker",
+        description="Issue found at odr",
+        level=IssueSeverity.INFORMATION,
+        rule_uid=rule_uid,
+    )
+
+    result.add_file_location(
+        checker_bundle_name="TestBundle",
+        checker_id="TestChecker",
+        issue_id=issue_id,
+        row=1,
+        column=0,
+        description="Location for issue",
+    )
+
+    result.set_checker_status(
+        checker_bundle_name="TestBundle",
+        checker_id="TestChecker",
+        status=StatusType.COMPLETED,
+    )
+
+    result.write_markdown_doc(TEST_MARKDOWN_DOC_OUTPUT_PATH)
+
+    example_md_text = ""
+    output_md_text = ""
+    with open(EXAMPLE_OUTPUT_MARKDOWN_DOC_PATH, "r") as md_file:
+        example_md_text = md_file.read()
+    with open(TEST_MARKDOWN_DOC_OUTPUT_PATH, "r") as md_file:
+        output_md_text = md_file.read()
+
+    assert output_md_text == example_md_text
+
+    os.remove(TEST_MARKDOWN_DOC_OUTPUT_PATH)