remove more spurious jQuery objects by using externs

javascript/ql/src/semmle/javascript/frameworks/jQuery.qll

@@ -51,7 +51,9 @@ private class OrdinaryJQueryObject extends JQueryObjectInternal {
 bindingset[methodName, call]
 private predicate returnsAJQueryObject(DataFlow::CallNode call, string methodName) {
   not (
-    methodName = "val" // `jQuery.val()`
+    neverReturnsJQuery(methodName)
+    or
+    methodName = "val" and call.getNumArgument() = 0 // `jQuery.val()`
     or
     methodName = ["html", "text"] and call.getNumArgument() = 0 // `jQuery.html()`/`jQuery.text()`
     or
@@ -59,20 +61,23 @@ private predicate returnsAJQueryObject(DataFlow::CallNode call, string methodNam
     methodName = ["attr", "prop"] and
     call.getNumArgument() = 1 and
     call.getArgument(0).mayHaveStringValue(_)
-    or
-    // `jQuery.data()`
-    methodName = "data" and call.getNumArgument() = 0
-    or
-    // `jQuery.data(key)`
-    methodName = "data" and call.getNumArgument() = 1 and call.getArgument(0).mayHaveStringValue(_)
-    or
-    methodName = ["Event", "Deferred"] // $.Event / $.Deferred
-    or
-    methodName = "trim" // $.trim()
-    or
-    // `$.ajax`, and related methods.
-    // note: there are 2 different `get` methods, and none of them return a jQuery object.
-    methodName = ["ajax", "get", "getJSON", "getScript", "post", "load"]
+  )
+}
+
+/**
+ * Holds if a jQuery method named `name` never returns a JQuery object.
+ */
+private predicate neverReturnsJQuery(string name) {
+  forex(ExternalMemberDecl decl |
+    decl.getBaseName() = "jQuery" and
+    decl.getName() = name
+  |
+    not decl
+        .getDocumentation()
+        .getATagByTitle("return")
+        .getType()
+        .getAnUnderlyingType()
+        .hasQualifiedName("jQuery")
   )
 }
 

javascript/ql/test/library-tests/frameworks/jQuery/jquery-3.2.js

@@ -0,0 +1,65 @@
+/*
+ * Copyright 2017 The Closure Compiler Authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+/**
+ * @fileoverview Externs for jQuery 3.1
+ *
+ * Note that some functions use different return types depending on the number
+ * of parameters passed in. In these cases, you may need to annotate the type
+ * of the result in your code, so the JSCompiler understands which type you're
+ * expecting. For example:
+ *    <code>var elt = /** @type {Element} * / (foo.get(0));</code>
+ *
+ * @see http://api.jquery.com/
+ * @externs
+ */
+
+/**
+ * @typedef {(Window|Document|Element|Array<Element>|string|jQuery|
+ *     NodeList)}
+ */
+var jQuerySelector;
+
+/**
+ * @constructor
+ * @param {(jQuerySelector|Object|function())=} arg1
+ * @param {(Element|jQuery|Document|
+ *     Object<string, (string|function(!jQuery.Event))>)=} arg2
+ * @throws {Error} on invalid selector
+ * @return {!jQuery}
+ * @implements {Iterable}
+ */
+function jQuery(arg1, arg2) { };
+
+/**
+ * @const
+ */
+var $ = jQuery;
+
+/**
+ * @param {(string|jQueryAjaxSettings|Object<string,*>)} arg1
+ * @param {(jQueryAjaxSettings|Object<string, *>)=} settings
+ * @return {!jQuery.jqXHR}
+ */
+jQuery.ajax = function (arg1, settings) { };
+
+/**
+ * @param {string} str
+ * @return {string}
+ * @nosideeffects
+ */
+jQuery.trim = function (str) { };
+