Add helpUri to HTML report (#76) (#88)

Author: balgillo

CONTRIBUTING.md

@@ -19,7 +19,7 @@ Pull requests are welcome.
 
 1. Fork the repository.
 2. Make and test your changes (see Developer Guide below).
-3. Run `poetry run black sarif` to format the code.
+3. Run `poetry run ruff format` and `poetry run black sarif` to format the code.
 4. Run `poetry run pylint sarif` and check for no new errors or warnings.
 5. Raise Pull Request in GitHub.com.
 
@@ -54,8 +54,8 @@ To check that the right versions are being run:
 
 ```bash
 poetry run python --version
-poetry run sarif --version
-poetry run python -m sarif --version
+poetry run sarif --version --debug
+poetry run python -m sarif --version --debug
 ```
 
 To see which executable is being run:

README.md

@@ -676,7 +676,7 @@ The data in each `result` object can then be used for filtering via the `--filte
 
 ```yaml
 # Lines beginning with # are interpreted as comments and ignored.
-# Optional description for the filter.  If no title is specified, the filter file name is used.
+# Optional description for the filter.  If not specified, the filter file name is used.
 description: Example filter from README.md
 
 # Optional configuration section to override default values.

sarif/operations/html_op.py

@@ -9,8 +9,7 @@
 
 from jinja2 import Environment, FileSystemLoader, select_autoescape
 
-from sarif import charts
-from sarif import sarif_file
+from sarif import charts, sarif_file
 
 _THIS_MODULE_PATH = os.path.dirname(__file__)
 
@@ -90,7 +89,7 @@ def _generate_single_html(
         total_distinct_issue_codes += distinct_issue_codes
 
         severity_details = _enrich_details(
-            report.get_issues_grouped_by_type_for_severity(severity)
+            report.get_issues_grouped_by_type_for_severity(severity), input_file
         )
 
         severity_section = {
@@ -129,8 +128,30 @@ def _generate_single_html(
         file_out.write(html_content)
 
 
-def _enrich_details(records_of_severity):
-    return [
-        {"code": key, "count": len(records), "details": records}
-        for (key, records) in records_of_severity.items()
-    ]
+def _extract_help_links_from_rules(rules, link_to_desc, key):
+    for rule in rules:
+        if "helpUri" in rule:
+            uri = rule["helpUri"]
+            if uri not in link_to_desc:
+                desc = rule.get("fullDescription", {}).get("text")
+                if not desc:
+                    desc = rule.get("name")
+                if not desc:
+                    desc = key
+                link_to_desc[uri] = desc
+
+
+def _enrich_details(records_of_severity, input_file):
+    ret = []
+
+    for key, records in records_of_severity.items():
+        link_to_desc = {}
+        for record in records:
+            rule_id = record["Code"]
+            rules = input_file.get_rules_by_id(rule_id)
+            _extract_help_links_from_rules(rules, link_to_desc, key)
+        links = [(desc, uri) for (uri, desc) in link_to_desc.items()]
+        ret.append(
+            {"code": key, "count": len(records), "links": links, "details": records}
+        )
+    return ret

sarif/operations/templates/sarif_summary.html

@@ -101,24 +101,27 @@ <h4>Total number of distinct issues of all severities ({{ severities }}): <b>{{
 {% for problem in problems %}
 <h3>Severity : {{ problem.type }} [ {{ problem.count }} ]</h3>
 <ul>
-    {% for error in problem.details -%}
+    {%- for error in problem.details %}
     <li>
         <button class="collapsible">{{- error.code }}: <b>{{ error.count -}}</b></button>
         <div class="content">
             <ul>
-                {%- for line in error.details -%}
-                  {%- if line.Location %}
-                    <li>{{ line.Location }}:{{ line.Line }}</li>
-                  {%- else %}
-                    <li>{{ line.Description }}</li>
-                  {%- endif %}
-                {%- endfor %}
+            {%- for link in error.links %}
+                <li><a href="{{ link.1 }}" target="_blank">{{ link.0 }}</a></li>
+            {%- endfor %}
+            {%- for line in error.details %}
+                {%- if line.Location %}
+                <li>{{ line.Location }}:{{ line.Line }}</li>
+                {%- else %}
+                <li>{{ line.Description }}</li>
+                {%- endif %}
+            {%- endfor %}
             </ul>
         </div>
     </li>
-    {% endfor %}
+    {%- endfor %}
 </ul>
-{% endfor -%}
+{%- endfor %}
 
 <script>
     var coll = document.getElementsByClassName("collapsible");

sarif/sarif_file.py

@@ -193,6 +193,19 @@ def get_conversion_tool_name(self) -> Optional[str]:
             )
         return None
 
+    def get_rules_by_id(self, rule_id: str) -> List[Dict]:
+        """
+        Get the sarif rule for the given ID, if it exists in this run.
+        """
+        ret = []
+        rule_id = rule_id.strip()
+        if not rule_id:
+            return ret
+        for rule in self.run_data.get("tool", {}).get("driver", {}).get("rules", []):
+            if rule.get("id", "") == rule_id:
+                ret.append(rule)
+        return ret
+
     def get_results(self) -> List[Dict]:
         """
         Get the results from this run.  These are the Result objects as defined in the SARIF
@@ -443,6 +456,15 @@ def get_distinct_tool_names(self):
         """
         return sorted(list(set(run.get_tool_name() for run in self.runs)))
 
+    def get_rules_by_id(self, rule_id: str) -> List[Dict]:
+        """
+        Get the sarif rule(s) for the given ID.
+        """
+        ret = []
+        for run in self.runs:
+            ret.extend(run.get_rules_by_id(rule_id))
+        return ret
+
     def get_results(self) -> List[Dict]:
         """
         Get the results from all runs in this file.  These are the Result objects as defined in the
@@ -625,6 +647,17 @@ def get_distinct_tool_names(self) -> List[str]:
 
         return sorted(list(all_tool_names))
 
+    def get_rules_by_id(self, rule_id: str) -> List[Dict]:
+        """
+        Get the sarif rule(s) for the given ID.
+        """
+        ret = []
+        for subdir in self.subdirs:
+            ret.extend(subdir.get_rules_by_id(rule_id))
+        for input_file in self.files:
+            ret.extend(input_file.get_rules_by_id(rule_id))
+        return ret
+
     def get_results(self) -> List[Dict]:
         """
         Get the results from all runs in all files.  These are the Result objects as defined in the

tests/ops/html/test_html.py

@@ -10,7 +10,18 @@
     "version": "2.1.0",
     "runs": [
         {
-            "tool": {"driver": {"name": "unit test"}},
+            "tool": {
+                "driver": {
+                    "name": "unit test",
+                    "rules": [
+                        {
+                            "id": "CA2101",
+                            "name": "Specify <marshalling> for P/Invoke string arguments",
+                            "helpUri": "https://learn.microsoft.com/dotnet/fundamentals/code-analysis/quality-rules/ca2101",
+                        }
+                    ],
+                }
+            },
             "results": [
                 {
                     "ruleId": "CA2101",
@@ -33,7 +44,8 @@
 }
 
 
-EXPECTED_OUTPUT_TXT = """<head>
+EXPECTED_OUTPUT_TXT = """
+<head>
     <style>
         #pageContainer {
             margin: auto;
@@ -110,37 +122,32 @@
     </style>
 </head>
 
-
-
 <h3>Sarif Summary: <b>unit test</b></h3>
 <h4>Document generated on: <b><date_val></b></h4>
 <h4>Total number of distinct issues of all severities (error, warning, note): <b>1</b></h4>
 
-
-
-
-
 <h3>Severity : error [ 1 ]</h3>
 <ul>
     <li>
         <button class="collapsible">CA2101: <b>1</b></button>
         <div class="content">
             <ul>
-                    <li>file:///C:/Code/main.c:24</li>
+                <li><a href="https://learn.microsoft.com/dotnet/fundamentals/code-analysis/quality-rules/ca2101" target="_blank">Specify &lt;marshalling&gt; for P/Invoke string arguments</a></li>
+                <li>file:///C:/Code/main.c:24</li>
             </ul>
         </div>
     </li>
-    
+
 </ul>
 
 <h3>Severity : warning [ 0 ]</h3>
 <ul>
-    
+
 </ul>
 
 <h3>Severity : note [ 0 ]</h3>
 <ul>
-    
+
 </ul>
 <script>
     var coll = document.getElementsByClassName("collapsible");
@@ -185,6 +192,17 @@ def test_html():
         pie_chart_end = output.find("/>", pie_chart_start) + 2
         output = output[:pie_chart_start] + output[pie_chart_end:]
 
-        assert output == EXPECTED_OUTPUT_TXT.replace("\n", os.linesep).replace(
+        # Check the output line-by-line, ignoring whitespace around and between lines.
+        output_split = output.splitlines()
+        for check_line in EXPECTED_OUTPUT_TXT.replace(
             "<date_val>", mtime.strftime("%Y-%m-%d %H:%M:%S.%f")
-        )
+        ).splitlines():
+            expected = check_line.strip()
+            if not expected:
+                continue
+            actual = ""
+            while output_split:
+                actual = output_split.pop(0).strip()
+                if actual:
+                    break
+            assert actual == expected