From d7fac836c11dd1137cde5d29b02e4e46b96ec47d Mon Sep 17 00:00:00 2001
From: Simon Brooke <simon@journeyman.cc>
Date: Tue, 4 Jun 2019 09:50:45 +0100
Subject: [PATCH] Added the index layer
To allow multiple reports from a given tool for the same line of the same file.
---
src/gusqt/wrappers/README.md | 45 +++++++++++++++++++++++++-----------
1 file changed, 32 insertions(+), 13 deletions(-)
diff --git a/src/gusqt/wrappers/README.md b/src/gusqt/wrappers/README.md
index 5e1efff..cee0e43 100644
--- a/src/gusqt/wrappers/README.md
+++ b/src/gusqt/wrappers/README.md
@@ -1,6 +1,7 @@
# Grand Unified Software Quality Tool: Wrappers
-Wrappers are intended to produce unifiable output from the specific tools they wrap. This unifiable output as follows:
+Wrappers are intended to produce unifiable output from the specific tools
+they wrap. This unifiable output as follows:
1. `as-edn` output in the form of a sequence of maps, with keys as follows:
* `column` (optional) the locus of the report within the line
@@ -12,23 +13,41 @@ Wrappers are intended to produce unifiable output from the specific tools they w
2. `as-markdown` output in the form of human-readable markdown
-The full EDN structure is something like this, so that EDNs generated by separate tools can be read and deep-merged.
+The full EDN structure is something like this, so that EDNs generated by
+separate tools can be read and deep-merged.
```clojure
{:file "pathname/of/file.clj"
:lines
{147
{:cloverage
- (:line 147
- :column 0
- :severity :info
- :tool :cloverage
- :text "9 out of 10 forms covered"}
+ {index
+ (:line 147
+ :column 0
+ :severity :info
+ :tool :cloverage
+ :text "9 out of 10 forms covered"}}
:kibit
- {:line 147
- :column 37
- :severity :warn
- :tool :kibit
- :text "Consider using: `(pos? q)` instead of: `(> q 0)`"}}}
-
+ {index
+ {:line 147
+ :column 37
+ :severity :warn
+ :tool :kibit
+ :text "Consider using: `(pos? q)` instead of: `(> q 0)`"}}}}
```
+
+**NOTE THAT** in the above, `index` represents an index into the reports
+generated by the specified tool and is distinct *for that tool*. It is not
+nexecssarily distinct within the document across all tools. It is required
+because one individual tool may generate more than one report from the same
+line.
+
+At present I am using numbers from the set of natural numbers, but it would
+equally be possible to compose a value using something like
+
+```clojure
+(keyword (str tool-name "-" n))
+```
+
+where `n` is a distinct number. *What matters* is that the index of any report
+SHALL BE unique for any given tool within a given EDN file.