Turn external API query into diagnostics query

* Expose (partial) CSV model for the API
* Rework and simplify predicates

Author: Benjamin Muskalla

java/ql/src/Telemetry/ExternalAPI.qll

@@ -1,16 +1,29 @@
-import java
-import APIUsage
-private import experimental.semmle.code.java.Logging
+private import java
+private import APIUsage
+private import semmle.code.java.dataflow.ExternalFlow
 
 class ExternalAPI extends Callable {
   ExternalAPI() { not this.fromSource() }
 
-  string simpleName() {
-    result = getDeclaringType().getSourceDeclaration() + "#" + this.getStringSignature()
+  predicate isTestLibrary() { getDeclaringType() instanceof TestLibrary }
+
+  predicate isInteresting() {
+    getNumberOfParameters() > 0 and
+    not (
+      getReturnType() instanceof VoidType or
+      getReturnType() instanceof PrimitiveType or
+      getReturnType() instanceof BoxedType
+    )
+  }
+
+  string asCSV(ExternalAPI api) {
+    result =
+      api.getDeclaringType().getPackage() + ";?;" + api.getDeclaringType().getSourceDeclaration() +
+        ";" + api.getName() + ";" + paramsString(api)
   }
 }
 
-class TestLibrary extends RefType {
+private class TestLibrary extends RefType {
   TestLibrary() {
     getPackage()
         .getName()

java/ql/src/Telemetry/ExternalAPIUsages.ql

@@ -2,19 +2,23 @@
  * @name Usage of APIs coming from external libraries
  * @description A list of 3rd party APIs used in the codebase. Excludes test and generated code.
  * @id java/telemetry/external-api
+ * @kind diagnostic
  */
 
 import java
+import APIUsage
 import ExternalAPI
 import semmle.code.java.GeneratedFiles
 
+// TODO [bm]: decide whether to drop the order by or
+// turn Usage into string for diagnostic kind
+// https://github.slack.com/archives/C01JJP3EF8E/p1627910071013000
 from ExternalAPI api
 where
-  not api.getDeclaringType() instanceof TestLibrary and
-  isInterestingAPI(api)
-select api.simpleName() as API,
+  not api.isTestLibrary() and
+  api.isInteresting()
+select api.asCSV(api) as csv,
   count(Call c |
     c.getCallee() = api and
     not c.getFile() instanceof GeneratedFile
-  ) as Usages, supportKind(api) as Kind, api.getReturnType() as ReturnType,
-  api.getDeclaringType().getPackage() as Package order by Usages desc
+  ) as Usages, supportKind(api) as Kind order by Usages desc

java/ql/src/Telemetry/ExternalLibraryUsage.ql

@@ -16,6 +16,6 @@ where
       c.getCallee() = a and
       not c.getFile() instanceof GeneratedFile and
       a.getCompilationUnit().getParentContainer*() = jar and
-      not a.getDeclaringType() instanceof TestLibrary
+      not a.isTestLibrary()
     )
 select jar.getFile().getStem() + "." + jar.getFile().getExtension(), Usages order by Usages desc