Add --dependencies and --offline options

README.md

@@ -221,3 +221,37 @@ To run a tool installed locally using `npm` you can use `npx`:
 `npx` adds the local `node_modules/.bin/` folder to `$PATH` when it executes the command passed to it. This means that if you have installed `elm` locally, `elm-test` will automatically find that local installation.
 
 As mentioned in [Installation](#installation) we recommend installing elm-test locally in every project. This ensures all contributors and CI use the same version, to avoid nasty “works on my computer” issues.
+
+### --dependencies
+
+This is useful when developing an Elm Package (`"type": "package"` in elm.json).
+
+    elm-test --dependencies oldest
+
+Let’s say your package has the dependency `"elm/json": "1.0.0 <= v < 2.0.0"`. That allows a whole range of `elm/json` versions to be used with your package. Exactly which version of `elm/json` is going to be used in tests? Does it matter?
+
+Turns it it _does_ matter sometimes. For example, `elm/json` 1.1.0 added the `Json.Decode.oneOrMore` function. Let’s say you start using `oneOrMore` in your package. If the tests run with 1.1.0 or later, they are going to pass. But if they run with 1.0.0 (also allowed by the range), the tests are not even going to compile, because `oneOrMore` does not exist. Oops!
+
+When running `elm make` in a package project, the Elm compiler uses the _latest_ version permitted by the dependency ranges and makes sure that your project compiles. But it does not stop you from publishing a package with a too low version boundary.
+
+Tests to the rescue! By using `elm-test --dependencies oldest` your tests are going to be compiled and run with the _oldest_ permitted versions of your dependencies. If your use of the `oneOrMore` function has test coverage, the tests are going to fail (not compile)! The solution is to bump the lower bound: `"elm-test": "1.1.0 <= v < 2.0.0"`.
+
+`--dependencies` defaults to `newest`, because that was the behavior before the flag was added, and it is less surprising since it does the same thing as a plain `elm make`. But not now that you know about this little gotcha, go ahead and start using `--dependencies oldest` for your package!
+
+If you do start using `--dependencies oldest`, remember that your tests could fail due to bugs in a dependency that have been fixed in a later version. If that turns out to be the case, bump the lower bound.
+
+Note: Even with `--dependencies oldest` there are still edge cases. In the example above, let’s say your package also has another dependency, and that dependency in turn also depends on `elm/json`. But it has already specified that it wants at least 1.1.0. Then `--dependencies oldest` has no choice but installing 1.1.0, even if _your_ range allows 1.0.0. So `--dependencies oldest` is no guarantee that your lower version bounds are correct, but it does make it more likely.
+
+The flag is ignored for applications (`"type": "application"` in elm.json), because for applications all dependency versions are specified exactly (no ranges). (In rare edge cases, there _can_ be situations where your pinned _indirect_ dependencies can’t be honored perfectly, due to the merge between regular dependencies, test dependencies and the test runner dependencies that elm-test has to perform. But then we let the solver pick a working version and don’t consider the `--dependencies` flag.)
+
+If you use this together with `--offline`, beware that “oldest” and “newest” refer to what you packages you have on disk on your computer, not what the actually oldest and newest versions available on the package site are. Going back to the example with `"elm-json": "1.0.0 <= v < 2.0.0"`, if the only `elm/json` version you have on your computer is 1.1.0 then that’s what you’re gonna get with `--dependencies oldest --offline`. Even though 1.0.0 exists on the Internet, the tests are going to use 1.1.0 and therefore _not_ fail (as they would have with 1.0.0).
+
+### --offline
+
+Tell elm-test to fail instead of making HTTP request when “solving dependencies:”
+
+    elm-test --offline
+
+Before running tests, elm-test needs to merge your regular dependencies, test dependencies and dependencies of the test runner, and find a working set of versions. When doing so, elm-test needs to ask the package server for available versions of packages. The results are cached in `~/.elm` (`$ELM_HOME`). If you already have a cache that is supposed to be up-to-date cache, and want elm-test to fail instead of making HTTP requests to the package server if it isn’t, pass `--offline`.
+
+Note: `--offline` only controls HTTP requests that elm-test makes directly. The Elm compiler might still make HTTP requests.

example-package/elm.json

@@ -10,6 +10,7 @@
     "elm-version": "0.19.0 <= v < 0.20.0",
     "dependencies": {
         "elm/core": "1.0.0 <= v < 2.0.0",
+        "elm/json": "1.0.0 <= v < 2.0.0",
         "elm/project-metadata-utils": "1.0.0 <= v < 2.0.0"
     },
     "test-dependencies": {

example-package/tests/DependenciesTest.elm

@@ -0,0 +1,22 @@
+module DependenciesTest exposing (testOneOrMore)
+
+import Expect
+import Json.Decode as Decode
+import Test exposing (Test, test)
+
+
+{-| This test should pass with `--dependencies newest`,
+but fail with `--dependencies oldest`, since the range
+in elm.json is: `"elm/json": "1.0.0 <= v < 2.0.0"` and
+`oneOrMore` was added in 1.1.0.
+-}
+testOneOrMore : Test
+testOneOrMore =
+    test "Json.Decode.oneOrMore (added in elm/json 1.1.0) works" <|
+        \() ->
+            let
+                decoder =
+                    Decode.oneOrMore (::) Decode.int
+            in
+            Decode.decodeString decoder "[1, 2, 3]"
+                |> Expect.equal (Ok [ 1, 2, 3 ])

lib/DependencyProvider.js

@@ -119,7 +119,7 @@ class OnlineVersionsCache {
   }
 }
 
-class OnlineAvailableVersionLister {
+class AvailableVersionLister {
   /**
    * Memoization cache to avoid doing the same work twice in list.
    * @type { Map<string, Array<string>> }
@@ -132,19 +132,18 @@ class OnlineAvailableVersionLister {
    * @param {OnlineVersionsCache} onlineCache
    */
   constructor(onlineCache) {
-    onlineCache.update();
     this.onlineCache = onlineCache;
   }
 
   /**
    * @param { string } pkg
-   * @param { undefined | string } pinnedVersion
+   * @param { OrderConstraints } orderConstraints
    * @returns { Array<string> }
    */
-  list(pkg, pinnedVersion) {
+  list(pkg, orderConstraints) {
     const memoVersions = this.memoCache.get(pkg);
     if (memoVersions !== undefined) {
-      return prioritizePinnedIndirectVersion(memoVersions, pinnedVersion);
+      return applyOrderConstraints(memoVersions, orderConstraints);
     }
     const offlineVersions = readVersionsInElmHomeAndSort(pkg);
     const allVersionsSet = new Set(this.onlineCache.getVersions(pkg));
@@ -154,32 +153,7 @@ class OnlineAvailableVersionLister {
     }
     const allVersions = [...allVersionsSet].sort(flippedSemverCompare);
     this.memoCache.set(pkg, allVersions);
-    return prioritizePinnedIndirectVersion(allVersions, pinnedVersion);
-  }
-}
-
-class OfflineAvailableVersionLister {
-  /**
-   * Memoization cache to avoid doing the same work twice in list.
-   * @type { Map<string, Array<string>> }
-   */
-  cache = new Map();
-
-  /**
-   * @param { string } pkg
-   * @param { undefined | string } pinnedVersion
-   * @returns { Array<string> }
-   */
-  list(pkg, pinnedVersion) {
-    const memoVersions = this.cache.get(pkg);
-    if (memoVersions !== undefined) {
-      return prioritizePinnedIndirectVersion(memoVersions, pinnedVersion);
-    }
-
-    const offlineVersions = readVersionsInElmHomeAndSort(pkg);
-
-    this.cache.set(pkg, offlineVersions);
-    return prioritizePinnedIndirectVersion(offlineVersions, pinnedVersion);
+    return applyOrderConstraints(allVersions, orderConstraints);
   }
 }
 
@@ -206,7 +180,7 @@ function readVersionsInElmHomeAndSort(pkg) {
  * When doing `import('./DependencyProvider').DependencyProvider`,
  * TypeScript says `DependencyProvider` is not exported for some reason.
  * But `import('./DependencyProvider').DependencyProviderType` works.
- * @typedef {DependencyProvider} DependencyProviderType
+ * @typedef { DependencyProvider } DependencyProviderType
  */
 
 class DependencyProvider {
@@ -219,67 +193,30 @@ class DependencyProvider {
   }
 
   /**
-   * Solve dependencies completely offline, without any http request.
-   *
-   * @param { string } elmJson
+   * @param { boolean } offline
+   * @param { import('./ElmJson').ElmJson } elmJson
    * @param { boolean } useTest
    * @param { Record<string, string> } extra
+   * @param { PackageStrategy } packageStrategy
    * @returns { string }
    */
-  solveOffline(elmJson, useTest, extra) {
-    const lister = new OfflineAvailableVersionLister();
-    const dependencies = JSON.parse(elmJson).dependencies;
-    const indirectDeps =
-      dependencies === undefined ? undefined : dependencies.indirect;
+  solve(offline, elmJson, useTest, extra, packageStrategy) {
+    const lister = new AvailableVersionLister(this.cache);
 
     try {
       return wasm.solve_deps(
-        elmJson,
+        JSON.stringify(elmJson),
         useTest,
         extra,
-        fetchElmJsonOffline,
+        offline
+          ? fetchElmJsonOffline
+          : fetchElmJsonOnline.bind(null, this.syncHttpGet),
         /** @type { (pkg: string) => Array<string> } */
         (pkg) =>
-          lister.list(
-            pkg,
-            indirectDeps === undefined ? undefined : indirectDeps[pkg]
-          )
+          lister.list(pkg, toOrderConstraints(elmJson, packageStrategy, pkg))
       );
     } catch (errorMessage) {
-      throw new Error(errorMessage);
-    }
-  }
-
-  /**
-   * Solve dependencies with http requests when required.
-   *
-   * @param { string } elmJson
-   * @param { boolean } useTest
-   * @param { Record<string, string> } extra
-   * @returns { string }
-   */
-  solveOnline(elmJson, useTest, extra) {
-    const lister = new OnlineAvailableVersionLister(this.cache);
-    const dependencies = JSON.parse(elmJson).dependencies;
-    const indirectDeps =
-      dependencies === undefined ? undefined : dependencies.indirect;
-
-    try {
-      return wasm.solve_deps(
-        elmJson,
-        useTest,
-        extra,
-        /** @type { (pkg: string, version: string) => string } */
-        (pkg, version) => fetchElmJsonOnline(this.syncHttpGet, pkg, version),
-        /** @type { (pkg: string) => Array<string> } */
-        (pkg) =>
-          lister.list(
-            pkg,
-            indirectDeps === undefined ? undefined : indirectDeps[pkg]
-          )
-      );
-    } catch (errorMessage) {
-      throw new Error(errorMessage);
+      throw new Error(`Failed to solve dependencies:\n${errorMessage}`);
     }
   }
 }
@@ -350,6 +287,59 @@ function onlineVersionsFromScratch(syncHttpGet, cachePath, remotePackagesUrl) {
 
 // Helper functions ##################################################
 
+/**
+ * @typedef {
+    | { for: 'application', pinnedVersion: string | undefined }
+    | { for: 'package', strategy: PackageStrategy }
+  } OrderConstraints
+ *
+ * @typedef { 'newest' | 'oldest' } PackageStrategy
+ *
+ * @param { import('./ElmJson').ElmJson } elmJson
+ * @param { PackageStrategy } packageStrategy
+ * @param { string } pkg
+ * @returns { OrderConstraints }
+ */
+function toOrderConstraints(elmJson, packageStrategy, pkg) {
+  switch (elmJson.type) {
+    case 'application':
+      return {
+        for: 'application',
+        pinnedVersion: elmJson.dependencies.indirect[pkg],
+      };
+
+    case 'package':
+      return {
+        for: 'package',
+        strategy: packageStrategy,
+      };
+  }
+}
+
+/**
+ * @param { Array<string> } versions
+ * @param { OrderConstraints } orderConstraints
+ * @returns { Array<string> }
+ */
+function applyOrderConstraints(versions, orderConstraints) {
+  switch (orderConstraints.for) {
+    case 'application':
+      return prioritizePinnedIndirectVersion(
+        versions,
+        orderConstraints.pinnedVersion
+      );
+
+    case 'package':
+      switch (orderConstraints.strategy) {
+        case 'newest':
+          return versions;
+
+        case 'oldest':
+          return versions.slice().reverse();
+      }
+  }
+}
+
 /**
  * Enforces respecting pinned indirect dependencies.
  *

lib/ElmJson.js

@@ -253,9 +253,25 @@ function getElmExplorationsTestPackageVersionOrRange(elmJson) {
   }
 }
 
+/**
+ * @param { string } dir
+ * @returns { number }
+ */
+function mtime(dir) {
+  const elmJsonPath = getPath(dir);
+
+  try {
+    const stats = fs.statSync(elmJsonPath);
+    return stats.mtimeMs;
+  } catch (_) {
+    return 0;
+  }
+}
+
 module.exports = {
   ELM_TEST_PACKAGE: ELM_TEST_PACKAGE,
   getPath: getPath,
+  mtime: mtime,
   parseDirectAndIndirectDependencies: parseDirectAndIndirectDependencies,
   read: read,
   requireElmTestPackage: requireElmTestPackage,

lib/Generate.js

@@ -87,10 +87,19 @@ function getGeneratedSrcDir(generatedCodeDir) {
 
 /**
  * @param { import('./DependencyProvider').DependencyProviderType } dependencyProvider
+ * @param { import('./DependencyProvider').PackageStrategy } packageStrategy
  * @param { import('./Project').Project } project
+ * @param { boolean } offline
+ * @param { () => void } onBeforeSolve
  * @returns { void }
  */
-function generateElmJson(dependencyProvider, project) {
+function generateElmJson(
+  dependencyProvider,
+  packageStrategy,
+  project,
+  offline,
+  onBeforeSolve
+) {
   const generatedSrc = getGeneratedSrcDir(project.generatedCodeDir);
 
   fs.mkdirSync(generatedSrc, { recursive: true });
@@ -121,7 +130,13 @@ function generateElmJson(dependencyProvider, project) {
     type: 'application',
     'source-directories': sourceDirs,
     'elm-version': '0.19.2',
-    dependencies: Solve.getDependenciesCached(dependencyProvider, project),
+    dependencies: Solve.getDependenciesCached(
+      dependencyProvider,
+      packageStrategy,
+      project,
+      offline,
+      onBeforeSolve
+    ),
     'test-dependencies': {
       direct: {},
       indirect: {},