From 323a9b0a47affff18fef32dae7015954f68437cf Mon Sep 17 00:00:00 2001
From: Chris Kipp <ckipp@pm.me>
Date: Sun, 10 Apr 2022 12:56:45 +0200
Subject: [PATCH] feat: update Problem to account for related information and
 code

This PR makes changes to the existing `xsbti.Problem` to account for an
optional diagnostic code that the compiler can return for a given
diagnostic and also related information.

Given a piece of code like:

```scala
try {}
```

You'll receive the following:

```
-- [E002] Syntax Warning: /Users/ckipp/Documents/scala-workspace/dotty-error-index/examples/002_EmptyCatchAndFinallyBlockID.scala:3:2
3 |  try {}
  |  ^^^^^^
  |  A try without catch or finally is equivalent to putting
  |  its body in a block; no exceptions are handled.
```

The `E002` here is the actual code. Right now there would be no
description.

Some diagnostics have multiple positions that they need to represent.
You can see an example of this
[here](https://github.com/lampepfl/dotty/pull/14002) in Dotty with the
use of inlining. Instead of needing to rely on including all of that
information in the diagnostic message it can now be extracted out into
a `DiagnosticRelatedInformation`.

These changes reference the conversation in https://github.com/sbt/sbt/discussions/6868
---
 .../src/main/java/xsbti/DiagnosticCode.java   | 23 +++++++++++++++++++
 .../xsbti/DiagnosticRelatedInformation.java   | 20 ++++++++++++++++
 .../src/main/java/xsbti/Problem.java          | 22 ++++++++++++++++++
 3 files changed, 65 insertions(+)
 create mode 100644 internal/util-interface/src/main/java/xsbti/DiagnosticCode.java
 create mode 100644 internal/util-interface/src/main/java/xsbti/DiagnosticRelatedInformation.java

diff --git a/internal/util-interface/src/main/java/xsbti/DiagnosticCode.java b/internal/util-interface/src/main/java/xsbti/DiagnosticCode.java
new file mode 100644
index 00000000000..6633e2b4ec3
--- /dev/null
+++ b/internal/util-interface/src/main/java/xsbti/DiagnosticCode.java
@@ -0,0 +1,23 @@
+/*
+ * sbt
+ * Copyright 2011 - 2018, Lightbend, Inc.
+ * Copyright 2008 - 2010, Mark Harrah
+ * Licensed under Apache License 2.0 (see LICENSE)
+ */
+
+package xsbti;
+
+import java.util.Optional;
+
+/**
+ * A DiagnosticCode is a unique identifier that the compiler can associate with a diagnostic. This
+ * is useful for tools to be able to quickly identify what diagnostic is being reported without
+ * having to rely on parsing the actual diagnostic message, which might not be stable.
+ */
+public interface DiagnosticCode {
+  /** The unique code. This is typically in the format of E000 */
+  String code();
+
+  /** Possible explanation to explain the meaning of the code */
+  Optional<String> explanation();
+}
diff --git a/internal/util-interface/src/main/java/xsbti/DiagnosticRelatedInformation.java b/internal/util-interface/src/main/java/xsbti/DiagnosticRelatedInformation.java
new file mode 100644
index 00000000000..17e41941f15
--- /dev/null
+++ b/internal/util-interface/src/main/java/xsbti/DiagnosticRelatedInformation.java
@@ -0,0 +1,20 @@
+/*
+ * sbt
+ * Copyright 2011 - 2018, Lightbend, Inc.
+ * Copyright 2008 - 2010, Mark Harrah
+ * Licensed under Apache License 2.0 (see LICENSE)
+ */
+
+package xsbti;
+
+/**
+ * Related information for a given diagnostic. At times this can be another place in your code
+ * contributing to the diagnostic or just relevant code relating to the diagnostic.
+ */
+public interface DiagnosticRelatedInformation {
+  /** Position of the related inforamtion */
+  Position position();
+
+  /** Message indicating why this related information is attatched to the diagnostic. */
+  String message();
+}
diff --git a/internal/util-interface/src/main/java/xsbti/Problem.java b/internal/util-interface/src/main/java/xsbti/Problem.java
index 78c9145a321..b90adec0729 100644
--- a/internal/util-interface/src/main/java/xsbti/Problem.java
+++ b/internal/util-interface/src/main/java/xsbti/Problem.java
@@ -7,6 +7,8 @@
 
 package xsbti;
 
+import java.util.Collections;
+import java.util.List;
 import java.util.Optional;
 
 public interface Problem {
@@ -26,4 +28,24 @@ public interface Problem {
   default Optional<String> rendered() {
     return Optional.empty();
   }
+
+  /**
+   * The unique code attatched to the diagnostic being reported.
+   *
+   * <p>NOTE: To avoid breaking compatibility we provide a default to account for older Scala
+   * version that do not have codes.
+   */
+  default Optional<DiagnosticCode> diagnosticCode() {
+    return Optional.empty();
+  }
+
+  /**
+   * The possible releated information for the diagnostic being reported.
+   *
+   * <p>NOTE: To avoid breaking compatibility we provide a default to account for older Scala
+   * version that do not have the concept of "related information".
+   */
+  default List<DiagnosticRelatedInformation> diagnosticReleatedInforamation() {
+    return Collections.emptyList();
+  }
 }