Trim runtime deps: make Nashorn optional, bulk up JS filter tests

build.gradle

@@ -44,13 +44,30 @@ jacocoTestReport {
 
 dependencies {
     implementation 'com.fulcrumgenomics:jlibdeflate:0.1.0'
-    implementation 'commons-logging:commons-logging:1.3.0'
     implementation "org.xerial.snappy:snappy-java:1.1.10.5"
     implementation 'org.apache.commons:commons-compress:1.26.0'
     implementation 'org.tukaani:xz:1.9'
     implementation "org.json:json:20231013"
-    implementation 'org.openjdk.nashorn:nashorn-core:15.4'
-
+
+    // commons-jexl 2.1.1 pulls commons-logging:1.1.1 (released 2007). htsjdk has no direct
+    // need for commons-logging itself, so we publish a version constraint rather than a real
+    // dependency: it kicks in only if commons-logging is pulled transitively, and bumps it to
+    // a maintained version. Drop this if commons-jexl is ever upgraded past 2.1.1.
+    constraints {
+        implementation('commons-logging:commons-logging:1.3.0') {
+            because 'jexl 2.1.1 pulls commons-logging 1.1.1 transitively; pin a maintained version'
+        }
+    }
+
+    // Nashorn is the JSR-223 "js" engine used by the optional JavaScript filter classes
+    // (htsjdk.samtools.filter.JavascriptSamRecordFilter, htsjdk.variant.variantcontext.filter.JavascriptVariantFilter).
+    // It's compileOnly so downstream consumers who don't use those filter classes don't pay the
+    // cost of nashorn-core + 5 ASM artifacts on their runtime classpath. Consumers who do use
+    // them must add nashorn-core to their own runtime classpath; see the error message thrown
+    // by AbstractJavascriptFilter when no JS engine is found.
+    compileOnly 'org.openjdk.nashorn:nashorn-core:15.7'
+    testImplementation 'org.openjdk.nashorn:nashorn-core:15.7'
+
     api "org.apache.commons:commons-jexl:2.1.1"
 
     testImplementation 'org.testng:testng:7.8.0'

src/main/java/htsjdk/samtools/filter/AbstractJavascriptFilter.java

@@ -85,8 +85,7 @@ protected AbstractJavascriptFilter(final Reader scriptReader, final HEADER heade
         final ScriptEngine engine = manager.getEngineByName("js");
         if (engine == null) {
             CloserUtil.close(scriptReader);
-            throw new RuntimeScriptException("The embedded 'javascript' engine is not available in java. "
-                    + "Do you use the SUN/Oracle Java Runtime ?");
+            throw new RuntimeScriptException(noJsEngineMessage(this.getClass().getSimpleName()));
         }
         if (scriptReader == null) {
             throw new RuntimeScriptException("missing ScriptReader.");
@@ -109,6 +108,30 @@ protected AbstractJavascriptFilter(final Reader scriptReader, final HEADER heade
         this.bindings.put(DEFAULT_HEADER_KEY, header);
     }
 
+    static String noJsEngineMessage(final String filterClassName) {
+        return String.join(
+                "\n",
+                "No JSR-223 JavaScript engine (lookup name \"js\") was found on the classpath.",
+                "",
+                "Starting with htsjdk 5.0.0, htsjdk no longer ships a JavaScript engine as a runtime",
+                "dependency, so that consumers who do not use the JavaScript filter classes do not pay",
+                "the cost of carrying ~6 extra jars (nashorn-core plus its ASM transitives, ~2.5 MB).",
+                "",
+                "To use " + filterClassName + ", add a JSR-223-compatible JavaScript engine to your",
+                "runtime classpath. The recommended choice is OpenJDK Nashorn:",
+                "",
+                "    Gradle:  runtimeOnly 'org.openjdk.nashorn:nashorn-core:15.7'",
+                "",
+                "    Maven:   <dependency>",
+                "               <groupId>org.openjdk.nashorn</groupId>",
+                "               <artifactId>nashorn-core</artifactId>",
+                "               <version>15.7</version>",
+                "               <scope>runtime</scope>",
+                "             </dependency>",
+                "",
+                "Any other JSR-223 engine that registers under the name \"js\" will also work.");
+    }
+
     /** return a javascript engine as a Compilable */
     private static Compilable getCompilable(final ScriptEngine engine) {
         if (!(engine instanceof Compilable)) {

src/main/java/htsjdk/samtools/filter/JavascriptSamRecordFilter.java

@@ -30,16 +30,26 @@
 import java.io.Reader;
 
 /**
- * javascript based read filter
+ * JavaScript-based {@link SamRecordFilter}.
  *
+ * <p>The user-supplied script is evaluated against each {@link SAMRecord} with the following
+ * variables in scope:
  *
- * The script puts the following variables in the script context:
+ * <ul>
+ *   <li>{@code record} - the {@link SAMRecord} being evaluated</li>
+ *   <li>{@code header} - the {@link SAMFileHeader} associated with the reader</li>
+ * </ul>
  *
- * - 'record' a SamRecord (
- * https://github.com/samtools/htsjdk/blob/master/src/java/htsjdk/samtools/
- * SAMRecord.java ) - 'header' (
- * https://github.com/samtools/htsjdk/blob/master/src/java/htsjdk/samtools/
- * SAMFileHeader.java )
+ * <p>Example: keep only records with mapping quality >= 30:
+ * <pre>{@code
+ *     new JavascriptSamRecordFilter("record.getMappingQuality() >= 30;", header)
+ * }</pre>
+ *
+ * <p><b>Runtime requirement:</b> as of htsjdk 5.0.0, htsjdk does not ship a JavaScript engine as
+ * a runtime dependency. To use this class, add a JSR-223-compatible JavaScript engine
+ * (e.g. {@code org.openjdk.nashorn:nashorn-core}) to your runtime classpath. If no engine is
+ * available, the constructor throws a {@link htsjdk.samtools.util.RuntimeScriptException} whose
+ * message lists the dependency coordinates.
  *
  * @author Pierre Lindenbaum PhD Institut du Thorax - INSERM - Nantes - France
  */

src/main/java/htsjdk/variant/variantcontext/filter/JavascriptVariantFilter.java

@@ -31,11 +31,26 @@
 import java.io.Reader;
 
 /**
- * javascript based variant filter The script puts the following variables in
- * the script context:
+ * JavaScript-based {@link VariantContextFilter}.
  *
- * - 'header' a htsjdk.variant.vcf.VCFHeader
- * - 'variant' a htsjdk.variant.variantcontext.VariantContext
+ * <p>The user-supplied script is evaluated against each {@link VariantContext} with the following
+ * variables in scope:
+ *
+ * <ul>
+ *   <li>{@code variant} - the {@link VariantContext} being evaluated</li>
+ *   <li>{@code header} - the {@link VCFHeader} associated with the reader</li>
+ * </ul>
+ *
+ * <p>Example: keep only variants on chromosome 1:
+ * <pre>{@code
+ *     new JavascriptVariantFilter("variant.getContig() == '1';", header)
+ * }</pre>
+ *
+ * <p><b>Runtime requirement:</b> as of htsjdk 5.0.0, htsjdk does not ship a JavaScript engine as
+ * a runtime dependency. To use this class, add a JSR-223-compatible JavaScript engine
+ * (e.g. {@code org.openjdk.nashorn:nashorn-core}) to your runtime classpath. If no engine is
+ * available, the constructor throws a {@link htsjdk.samtools.util.RuntimeScriptException} whose
+ * message lists the dependency coordinates.
  *
  * @author Pierre Lindenbaum PhD Institut du Thorax - INSERM - Nantes - France
  */