feat: compare versions using ecosystem-specific semantics (#157)

* feat: use spec compliant implementation to compare versions from packagist ecosystem

* refactor: use a map and common type to make it easier to implement ecosystem version comparators

* fix: remove build metadata when comparing build versions

* feat: implement proper semver v2 comparator

* feat: implement comparator for NuGet

* feat: implement comparator for RubyGems

* feat: implement comparator for Maven

* feat: implement comparator for PyPI

* feat: implement comparator for Debian

* test: improve reporting for `semantic` specs

* fix: minor bugs in RubyGems comparator

* fix: minor bugs in Packagist comparator

* fix: properly preserve original version string in parsing

* test: create scripts to generate semantic fixtures for ecosystems based off their respective osv dbs

* docs: update details about how comparisons are done

* fix: compare Maven versions with `sp` correctly

* feat: restructure `semantic` parser and comparator implementation

* feat: use `CompareAs` field to allow using different comparators for csvs

* feat: replace `compareComponent` with `Cmp` on `Components`

* refactor: move utilities around

* fix: support `Pub` ecosystem

* refactor: move stuff around

* refactor: deduplicate some switch statements

Author: G-Rath

README.md

@@ -81,9 +81,9 @@ osv-detector --parse-as 'package-lock.json' path/to/my/file.lock
 ```
 
 By default, the detector attempts to detect known vulnerabilities by checking
-the versions of packages specified by the parsed lockfile against the versions
-specified by the OSVs in the loaded OSV databases, using an internal
-semver-based package that aims to minimize false negatives (see
+the versions of packages specified by the OVSs in the loaded OSV databases,
+comparing based on the version ordering rules for the specific ecosystem being
+checked as closely as possible (see
 [this section](#version-parsing-and-comparing) for more details about version
 handling).
 
@@ -335,7 +335,7 @@ the detector doesn't know about, such as `NuGet`.
 You can either pass in CSV rows:
 
 ```
-osv-detector --parse-as csv-row 'npm,@typescript-eslint/types,5.13.0' 'Packagist,sentry/sdk,2.0.4'
+osv-detector --parse-as csv-row 'npm,,@typescript-eslint/types,5.13.0' 'Packagist,sentry/sdk,2.0.4'
 ```
 
 or you can specify paths to csv files:
@@ -344,25 +344,43 @@ or you can specify paths to csv files:
 osv-detector --parse-as csv-file path/to/my/first-csv path/to/my/second-csv
 ```
 
-Each CSV row must have at least three fields which hold the ecosystem, package
-name, and version (or commit) respectively, and CSV files cannot contain a
-header.
+Each CSV row represents a package and is made up of at least four fields:
+
+1. The ecosystem that the package is from, which is used as part of identifying
+   if an OSV is about the given package
+   - This does not have to be one of the ecosystems referenced in the detector,
+     or in the OSV specification
+   - This should be omitted if you are wanting to compare a commit using an API
+     database
+2. The ecosystem whose version comparison semantics to use when determining if
+   an OSV applies to the given package
+   - This has to be an ecosystem for which the detector supports comparing
+     versions of; this field can be blank if the first field refers to an
+     ecosystem the detector supports comparing, otherwise it should be the
+     ecosystem whose version semantics most closely match that of your arbitrary
+     ecosystem
+   - This should be omitted if you are wanting to compare a commit using an API
+     database
+3. The name of the package
+4. The version of the package, or the SHA of a `git` commit
+   - If you are providing a commit, then you must leave the first two fields
+     empty and ensure an API-based database is loaded i.e. via `--use-api`
+
+> **Warning**
+>
+> Do not include a header if you are using a CSV file
 
 The `ecosystem` does _not_ have to be one listed by the detector as known,
 meaning you can use any ecosystem that [osv.dev](https://osv.dev/) provides.
 
-If the ecosystem field is empty, then the `version` field is expected to be a
-commit. In this case, the `package` column is decorative as only the commit is
-passed to the API.
-
 > Remember to tell the detector to use the `osv.dev` API via the `--use-api`
 > flag if you're wanting to check commits!
 
 You can also omit the version to have the detector list all known
 vulnerabilities in the loaded database that apply to the given package:
 
 ```
-osv-detector --parse-as csv-row 'NuGet,Yarp.ReverseProxy,'
+osv-detector --parse-as csv-row 'NuGet,,Yarp.ReverseProxy,'
 ```
 
 While this uses the `--parse-as` flag, these are _not_ considered standard
@@ -417,8 +435,10 @@ The following packages were found in /path/to/my/Gemfile.lock:
 
 ## Version parsing and comparing
 
-Versions are compared using an internal `semver` package which aims to support
-any number of components followed by a build string.
+Versions are compared using an internal `semantic` package which aims to support
+compare versions accurately per the version semantics of each ecosystem, falling
+back to a relaxed version of SemVer that supports unlimited number components
+followed by a build string.
 
 Components are numbers broken up by dots, e.g. `1.2.3` has the components
 `1, 2, 3`. Anything that is not a number or a dot is considered to be the start

fixtures/csvs-files/two-rows.csv

@@ -1,2 +1,2 @@
-NuGet,Yarp.ReverseProxy,
-npm,@typescript-eslint/types,5.13.0
+NuGet,,Yarp.ReverseProxy,
+npm,,@typescript-eslint/types,5.13.0

generators/GenerateMavenVersions.java

@@ -0,0 +1,209 @@
+import org.apache.maven.artifact.versioning.ComparableVersion;
+
+import org.json.JSONArray;
+import org.json.JSONObject;
+
+import java.io.*;
+import java.net.URL;
+import java.nio.channels.Channels;
+import java.nio.channels.ReadableByteChannel;
+import java.nio.charset.StandardCharsets;
+import java.util.*;
+import java.util.stream.Collectors;
+import java.util.stream.IntStream;
+import java.util.zip.ZipEntry;
+import java.util.zip.ZipFile;
+
+/**
+ * Script for generating a list of maven version comparison fixtures based off
+ * every version mentioned in the OSV Maven database, sorted using the native
+ * Maven implementation.
+ * <p>
+ * To run this, you need to ensure copies of the following libraries are present
+ * on the class path:
+ *
+ * <ul>
+ * <li><a href="https://search.maven.org/artifact/org.json/json/20220924/bundle"><code>json</code></a></li>
+ * <li><a href="https://search.maven.org/artifact/org.apache.maven/maven-artifact/3.8.6/jar"><code>maven-artifact</code></a></li>
+ * </ul>
+ * The easiest way to do this is by putting the jars into a <code>lib</code> subfolder and then running:
+ * <code>
+ *   java -cp generators/lib/* generators/GenerateMavenVersions.java
+ * </code>
+ */
+public class GenerateMavenVersions {
+  public static String downloadMavenDb() throws IOException {
+    URL website = new URL("https://osv-vulnerabilities.storage.googleapis.com/Maven/all.zip");
+    String file = "./maven-db.zip";
+
+    ReadableByteChannel rbc = Channels.newChannel(website.openStream());
+
+    try(FileOutputStream fos = new FileOutputStream(file)) {
+      fos.getChannel().transferFrom(rbc, 0, Long.MAX_VALUE);
+    }
+
+    return file;
+  }
+
+  public static Map<String, List<String>> fetchPackageVersions() throws IOException {
+    String dbPath = downloadMavenDb();
+    List<JSONObject> osvs = loadOSVs(dbPath);
+
+    Map<String, List<String>> packages = new HashMap<>();
+
+    osvs.forEach(osv -> osv.getJSONArray("affected").forEach(aff -> {
+      JSONObject affected = (JSONObject) aff;
+
+      String pkgName = affected.getJSONObject("package").getString("name");
+
+      if(!affected.has("versions")) {
+        return;
+      }
+      JSONArray versions = affected.getJSONArray("versions");
+
+      packages.putIfAbsent(pkgName, new ArrayList<>());
+
+      if(versions.isEmpty()) {
+        return;
+      }
+
+      versions.forEach(version -> packages.get(pkgName).add((String) version));
+    }));
+
+    packages.forEach((key, _ignore) -> packages.put(
+      key,
+      packages.get(key)
+              .stream()
+              .distinct()
+              .sorted(Comparator.comparing(ComparableVersion::new))
+              .collect(Collectors.toList())
+    ));
+
+    return packages;
+  }
+
+  public static List<JSONObject> loadOSVs(String pathToDbZip) throws IOException {
+    List<JSONObject> osvs = new ArrayList<>();
+
+    try(ZipFile zipFile = new ZipFile(pathToDbZip)) {
+      Enumeration<? extends ZipEntry> entries = zipFile.entries();
+
+      while(entries.hasMoreElements()) {
+        ZipEntry entry = entries.nextElement();
+        InputStream stream = zipFile.getInputStream(entry);
+
+        BufferedReader streamReader = new BufferedReader(new InputStreamReader(stream, StandardCharsets.UTF_8));
+        StringBuilder responseStrBuilder = new StringBuilder();
+
+        String inputStr;
+        while((inputStr = streamReader.readLine()) != null) {
+          responseStrBuilder.append(inputStr);
+        }
+        osvs.add(new JSONObject(responseStrBuilder.toString()));
+      }
+    }
+
+    return osvs;
+  }
+
+  public static void writeToFile(String outfile, List<String> lines) throws IOException {
+    try(PrintWriter writer = new PrintWriter(outfile, StandardCharsets.UTF_8)) {
+      lines.forEach(writer::println);
+    }
+  }
+
+  public static boolean compareVers(String version1, String op, String version2) {
+    ComparableVersion v1 = new ComparableVersion(version1);
+    ComparableVersion v2 = new ComparableVersion(version2);
+
+    int r = v1.compareTo(v2);
+
+    if(op.equals("=")) {
+      return r == 0;
+    }
+
+    if(op.equals("<")) {
+      return r < 0;
+    }
+
+    if(op.equals(">")) {
+      return r > 0;
+    }
+
+    throw new RuntimeException("unsupported comparison operator " + op);
+  }
+
+  public static void compareVersions(List<String> lines, String select) {
+    lines.forEach(line -> {
+      line = line.trim();
+
+      if(line.isEmpty() || line.startsWith("#") || line.startsWith("//")) {
+        return;
+      }
+
+      String[] parts = line.split(" ");
+      String v1 = parts[0];
+      String op = parts[1];
+      String v2 = parts[2];
+
+      boolean r = compareVers(v1, op, v2);
+
+      if(select.equals("failures") && r) {
+        return;
+      }
+
+      if(select.equals("successes") && !r) {
+        return;
+      }
+
+      String color = r ? "\033[92m" : "\033[91m";
+      String rs = r ? "T" : "F";
+
+      System.out.printf("%s%s\033[0m: \033[93m%s\033[0m\n", color, rs, line);
+    });
+  }
+
+  public static void compareVersionsInFile(String filepath, String select) throws IOException {
+    List<String> lines = new ArrayList<>();
+
+    try(BufferedReader br = new BufferedReader(new FileReader(filepath))) {
+      String line = br.readLine();
+
+      while(line != null) {
+        lines.add(line);
+        line = br.readLine();
+      }
+    }
+
+    compareVersions(lines, select);
+  }
+
+  public static List<String> generateVersionCompares(List<String> versions) {
+    return IntStream.range(1, versions.size()).mapToObj(i -> {
+      String currentVersion = versions.get(i);
+      String previousVersion = versions.get(i - 1);
+      String op = compareVers(currentVersion, "=", previousVersion) ? "=" : "<";
+
+      return String.format("%s %s %s", previousVersion, op, currentVersion);
+    }).collect(Collectors.toList());
+  }
+
+  public static List<String> generatePackageCompares(Map<String, List<String>> packages) {
+    return packages
+             .values()
+             .stream()
+             .map(GenerateMavenVersions::generateVersionCompares)
+             .flatMap(Collection::stream)
+             .distinct()
+             .collect(Collectors.toList());
+  }
+
+  public static void main(String[] args) throws IOException {
+    String outfile = "maven-versions-generated.txt";
+    Map<String, List<String>> packages = fetchPackageVersions();
+
+    writeToFile(outfile, generatePackageCompares(packages));
+
+    compareVersionsInFile(outfile, "failures");
+  }
+}