New tool that converts SARIF file to txt suitable for Emacs (#16)

Introduce new 'emacs' sub-command (cloned html command) that converts
SARIF to a text file. When opened in emacs, this file will bring
a compilation mode, allowing easy navigation among code scan issues.

Author: dkloper

sarif/cmdline/main.py

@@ -15,6 +15,7 @@
     csv_op,
     diff_op,
     html_op,
+    emacs_op,
     info_op,
     ls_op,
     summary_op,
@@ -81,7 +82,7 @@ def _create_arg_parser():
         + "(or for diff, an increase in issues at that level).",
     )
 
-    for cmd in ["blame", "csv", "html", "summary", "word"]:
+    for cmd in ["blame", "csv", "html", "emacs", "summary", "word"]:
         subparser[cmd].add_argument(
             "--output", "-o", type=str, metavar="PATH", help="Output file or directory"
         )
@@ -90,7 +91,7 @@ def _create_arg_parser():
             "--output", "-o", type=str, metavar="FILE", help="Output file"
         )
 
-    for cmd in ["copy", "csv", "diff", "summary", "html", "trend", "word"]:
+    for cmd in ["copy", "csv", "diff", "summary", "html", "emacs", "trend", "word"]:
         subparser[cmd].add_argument(
             "--blame-filter",
             "-b",
@@ -122,7 +123,7 @@ def _create_arg_parser():
         help="Strip off the common prefix of paths in the CSV output",
     )
     # word and html default to trimming
-    for cmd in ["html", "word"]:
+    for cmd in ["html", "emacs", "word"]:
         subparser[cmd].add_argument(
             "--no-autotrim",
             "-n",
@@ -135,7 +136,7 @@ def _create_arg_parser():
             help="Image to include at top of file - SARIF logo by default",
         )
     # csv, html and word allow trimmable paths to be specified
-    for cmd in ["csv", "word", "html"]:
+    for cmd in ["csv", "word", "html", "emacs"]:
         subparser[cmd].add_argument(
             "--trim",
             metavar="PREFIX",
@@ -371,6 +372,15 @@ def _html(args):
     html_op.generate_html(input_files, args.image, output, multiple_file_output)
     return _check(input_files, args.check)
 
+def _emacs(args):
+    input_files = loader.load_sarif_files(*args.files_or_dirs)
+    input_files.init_default_line_number_1()
+    _init_path_prefix_stripping(input_files, args, strip_by_default=True)
+    _init_blame_filtering(input_files, args)
+    (output, multiple_file_output) = _prepare_output(input_files, args.output, ".txt")
+    emacs_op.generate_compile(input_files, output)
+    return _check(input_files, args.check)
+
 
 def _info(args):
     input_files = loader.load_sarif_files(*args.files_or_dirs)
@@ -459,6 +469,10 @@ def _word(args):
         "fn": _html,
         "desc": "Write an HTML representation of SARIF file(s) for viewing in a web browser",
     },
+    "emacs": {
+        "fn": _emacs,
+        "desc": "Write a representation of SARIF file(s) for viewing in emacs",
+    },
     "info": {"fn": _info, "desc": "Print information about SARIF file(s) structure"},
     "ls": {"fn": _ls, "desc": "List all SARIF files in the directories specified"},
     "summary": {

sarif/operations/emacs_op.py

@@ -0,0 +1,114 @@
+"""
+Code for `sarif emacs` command.
+"""
+
+import base64
+from datetime import datetime
+import os
+
+from jinja2 import Environment, FileSystemLoader, select_autoescape
+
+from sarif import charts
+from sarif.sarif_file import SarifFileSet
+
+_THIS_MODULE_PATH = os.path.dirname(__file__)
+
+_TEMPLATES_PATH = os.path.join(_THIS_MODULE_PATH, "templates")
+
+_ENV = Environment(
+    loader=FileSystemLoader(searchpath=_TEMPLATES_PATH),
+    autoescape=select_autoescape(),
+)
+
+
+def generate_compile(
+    input_files: SarifFileSet, output: str, output_multiple_files: bool
+):
+    """
+    Generate txt file from the input files.
+    """
+    date_val = datetime.now()
+
+    output_file = output
+    if output_multiple_files:
+        for input_file in input_files:
+            output_file_name = input_file.get_file_name_without_extension() + ".txt"
+            print(
+                "Writing results for",
+                input_file.get_file_name(),
+                "to",
+                output_file_name,
+            )
+            _generate_single_txt(
+                input_file,
+                os.path.join(output, output_file_name),
+                date_val
+            )
+        output_file = os.path.join(output, ".compile.txt")
+    source_description = input_files.get_description()
+    print(
+        "Writing results for",
+        source_description,
+        "to",
+        os.path.basename(output_file),
+    )
+    _generate_single_txt(
+        input_files, output_file, date_val
+    )
+
+
+def _generate_single_txt(
+    input_file, output_file, date_val
+):
+
+    all_tools = input_file.get_distinct_tool_names()
+
+    total_distinct_issue_codes = 0
+    problems = []
+
+    issues_by_severity = input_file.get_records_grouped_by_severity()
+    for (severity, issues_of_severity) in issues_by_severity.items():
+        issue_code_histogram = input_file.get_issue_code_histogram(severity)
+
+        distinct_issue_codes = len(issue_code_histogram)
+        total_distinct_issue_codes += distinct_issue_codes
+
+        severity_details = _enrich_details(issue_code_histogram, issues_of_severity)
+
+        severity_section = {
+            "type": severity,
+            "count": distinct_issue_codes,
+            "details": severity_details,
+        }
+
+        problems.append(severity_section)
+
+    filtered = None
+    filter_stats = input_file.get_filter_stats()
+    if filter_stats:
+        filtered = f"Results were filtered by {filter_stats}."
+
+    template = _ENV.get_template("sarif_emacs.txt")
+    txt_content = template.render(
+        report_type=", ".join(all_tools),
+        report_date=date_val,
+        severities=", ".join(issues_by_severity.keys()),
+        total=total_distinct_issue_codes,
+        problems=problems,
+        filtered=filtered,
+    )
+
+    with open(output_file, "wt", encoding="utf-8") as file_out:
+        file_out.write(txt_content)
+
+
+def _enrich_details(histogram, records_of_severity):
+    enriched_details = []
+
+    for (error_code, count) in histogram:
+        error_lines = [e for e in records_of_severity if e["Code"] == error_code]
+        lines = sorted(
+            error_lines, key=lambda x: x["Location"] + str(x["Line"]).zfill(6)
+        )
+        enriched_details.append({"code": error_code, "count": count, "details": lines})
+    return enriched_details

sarif/operations/templates/sarif_emacs.txt

@@ -0,0 +1,18 @@
+-*- compilation -*-
+
+Sarif Summary: {{ report_type }}
+Document generated on: {{ report_date }}
+Total number of distinct issues of all severities ({{ severities }}): {{ total }}
+{% if filtered -%}
+<p>{{ filtered }}</p>
+{%- endif %}
+
+{% for problem in problems %}
+Severity : {{ problem.type }} [{{ problem.count }}]
+{% for error in problem.details -%}
+{% for line in error.details -%}
+{{ line.Location }}:{{ line.Line }}: {{ error.code }}
+{% endfor %}
+{% endfor %}
+{% endfor -%}
+