DOP-969: Add an environment variable to support emitting diagnostics in JSON (#153)

* add serialize method to diag class and env variable

* mypy type inference failing?

* serialize() returns SerializedNode

* add test to test_main

* add test for JSON option

* in test, check message matches diagnostic.message attribute

* test all diag attributes

* lint

* main print returns json objects, not json converted to str

* clean up

* lint

* updates from CR

* add docstring to serialize()

* fix env vars in module docstring

* change default of DIAGNOSTICS_FORMAT env var, other updates following CR

Author: madelinezec

snooty/diagnostics.py

@@ -1,6 +1,8 @@
 import enum
-from typing import Tuple, Union
+from typing import Tuple, Union, Dict
 from pathlib import Path
+from .n import SerializableType
+from . import n
 
 
 class Diagnostic:
@@ -46,6 +48,14 @@ def severity(self) -> "Diagnostic.Level":
     def severity_string(self) -> str:
         return self.severity.name.title()
 
+    def serialize(self) -> n.SerializedNode:
+        """Create dict containing diagnostic attributes for neatly reporting diagnostics at program completion"""
+        diag: Dict[str, SerializableType] = {}
+        diag["severity"] = self.severity_string.upper()
+        diag["start"] = self.start[0]
+        diag["message"] = self.message
+        return diag
+
 
 class UnexpectedIndentation(Diagnostic):
     severity = Diagnostic.Level.error

snooty/main.py

@@ -9,13 +9,19 @@
   -h --help                 Show this screen.
   --commit=<commit_hash>    Commit hash of build.
   --patch=<patch_id>        Patch ID of build. Must be specified with a commit hash.
+
+Environment variables:
+  SNOOTY_PARANOID           0, 1 where 0 is default
+  DIAGNOSTICS_FORMAT        JSON, text where text is default
+
 """
 import getpass
 import logging
 import os
 import pymongo
 import sys
 import toml
+import json
 import watchdog.events
 import watchdog.observers
 from pathlib import Path, PurePath
@@ -81,16 +87,17 @@ def on_progress(self, progress: int, total: int, message: str) -> None:
         pass
 
     def on_diagnostics(self, path: FileId, diagnostics: List[Diagnostic]) -> None:
+        output = os.environ.get("DIAGNOSTICS_FORMAT", "text")
+
         for diagnostic in diagnostics:
-            # Line numbers are currently... uh, "approximate"
-            print(
-                "{}({}:{}ish): {}".format(
-                    diagnostic.severity_string.upper(),
-                    path,
-                    diagnostic.start[0],
-                    diagnostic.message,
-                )
-            )
+            info = diagnostic.serialize()
+            info["path"] = path.as_posix()
+
+            if output == "JSON":
+                document = {"diagnostic": info}
+                print(json.dumps(document))
+            else:
+                print("{severity}({path}:{start}ish): {message}".format(**info))
             self.total_warnings += 1
 
     def on_update(

snooty/test_main.py

@@ -1,3 +1,5 @@
+import os
+import json
 import builtins
 from typing import Any, List
 from .types import FileId
@@ -14,20 +16,59 @@ def test_print(*values: Any, **kwargs: Any) -> None:
     backend = main.Backend()
     orig_print = builtins.print
     builtins.print = test_print
+    test_diagnostics = [
+        InvalidLiteralInclude("invalid literal include error", 10, 12),
+        InvalidURL((10, 0), (12, 30)),
+        UnknownSubstitution("unknown substitution warning", 10),
+    ]
     try:
-        backend.on_diagnostics(
-            FileId("foo/bar.rst"),
-            [InvalidLiteralInclude("an error", 10, 12), InvalidURL((10, 0), (12, 30))],
-        )
-        backend.on_diagnostics(
-            FileId("foo/foo.rst"), [UnknownSubstitution("a warning", 10)]
-        )
+        backend.on_diagnostics(FileId("foo/bar.rst"), test_diagnostics[0:2])
+        backend.on_diagnostics(FileId("foo/foo.rst"), test_diagnostics[2:])
         assert backend.total_warnings == 3
     finally:
         builtins.print = orig_print
 
     assert messages == [
-        "ERROR(foo/bar.rst:10ish): an error",
-        "ERROR(foo/bar.rst:10ish): Invalid URL",
-        "WARNING(foo/foo.rst:10ish): a warning",
+        f"ERROR(foo/bar.rst:10ish): {test_diagnostics[0].message}",
+        f"ERROR(foo/bar.rst:10ish): {test_diagnostics[1].message}",
+        f"WARNING(foo/foo.rst:10ish): {test_diagnostics[2].message}",
+    ]
+
+    # test returning diagnostic messages as JSON
+    backend = main.Backend()
+    messages.clear()
+    builtins.print = test_print
+    os.environ["DIAGNOSTICS_FORMAT"] = "JSON"
+    try:
+        backend.on_diagnostics(FileId("foo/bar.rst"), test_diagnostics[0:2])
+        backend.on_diagnostics(FileId("foo/foo.rst"), test_diagnostics[2:])
+        assert backend.total_warnings == 3
+    finally:
+        builtins.print = orig_print
+
+    assert [json.loads(message) for message in messages] == [
+        {
+            "diagnostic": {
+                "severity": "ERROR",
+                "start": 10,
+                "message": test_diagnostics[0].message,
+                "path": "foo/bar.rst",
+            }
+        },
+        {
+            "diagnostic": {
+                "severity": "ERROR",
+                "start": 10,
+                "message": test_diagnostics[1].message,
+                "path": "foo/bar.rst",
+            }
+        },
+        {
+            "diagnostic": {
+                "severity": "WARNING",
+                "start": 10,
+                "message": test_diagnostics[2].message,
+                "path": "foo/foo.rst",
+            }
+        },
     ]