Initial version with decent API and documentation

Author: mpizenberg

.github/workflows/pull-request.yml

@@ -0,0 +1,31 @@
+name: Pull Request Check
+
+on:
+  pull_request:
+    branches: [ dev ]
+
+env:
+  CARGO_TERM_COLOR: always
+
+jobs:
+  build:
+
+    runs-on: ubuntu-latest
+
+    steps:
+    - uses: actions/checkout@v2
+
+    - name: Cache
+      uses: actions/cache@v2
+      with:
+        path: |
+            ./target
+            ~/.cargo
+        key: ${{ runner.os }}-${{ hashFiles('Cargo.toml') }}
+        restore-keys: ${{ runner.os }}
+
+    - name: Build
+      run: cargo build --verbose
+
+    - name: Run tests
+      run: cargo test --verbose

.github/workflows/main.yml renamed to .github/workflows/push.yml

@@ -1,10 +1,8 @@
-name: Rust
+name: Build code, run tests and deploy doc
 
 on:
   push:
-    branches: [ master, dev ]
-  pull_request:
-    branches: [ master ]
+    branches: [ dev ]
 
 env:
   CARGO_TERM_COLOR: always
@@ -40,3 +38,4 @@ jobs:
       with:
         github_token: ${{ secrets.GITHUB_TOKEN }}
         publish_dir: ./target/doc
+        force_orphan: true

Cargo.toml

@@ -1,8 +1,15 @@
 [package]
 name = "pubgrub"
 version = "0.1.0"
-authors = ["Matthieu Pizenberg <[email protected]>"]
+authors = ["Matthieu Pizenberg <[email protected]>", "Alex Tokarev <[email protected]>"]
 edition = "2018"
+description = "PubGrub version solving algorithm"
+readme = "README.md"
+repository = "https://github.com/mpizenberg/pubgrub-rs"
+license = "MPL-2.0"
+keywords = ["dependency", "pubgrub", "semver", "solver", "version"]
+categories = ["algorithms"]
+include = ["Cargo.toml", "LICENSE", "README.md", "src/**", "tests/**", "examples/**"]
 
 # See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html
 
@@ -11,4 +18,3 @@ thiserror = "1.0"
 
 [dev-dependencies]
 proptest = "0.10.1"
-anyhow = "1.0"

README.md

@@ -7,8 +7,8 @@ that satisfy all the constraints of a given project dependencies.
 In addition, when that is not possible,
 PubGrub tries to provide a very human-readable and clear
 explanation as to why that failed.
-Below is an example of explanation present in
-the introductory blog post about PubGrub
+Below is an example of an explanation present in
+the introductory blog post about PubGrub.
 
 ```txt
 Because dropdown >=2.0.0 depends on icons >=2.0.0 and
@@ -65,7 +65,7 @@ An introductory blog post was
 
 The detailed explanation of the algorithm is
 [provided on GitHub][github-pubgrub].
-The foundation of the algorithm is based on ASP (Answer Set Programming)
+The foundation of the algorithm is based on ASP (Answer Set Programming),
 and a book called
 "[Answer Set Solving in Practice][potassco-book]"
 by Martin Gebser, Roland Kaminski, Benjamin Kaufmann and Torsten Schaub.

examples/branching_error_reporting.rs

@@ -1,13 +1,12 @@
-use pubgrub::cache::{Cache, SimpleCache};
 use pubgrub::error::PubGrubError;
 use pubgrub::range::Range;
 use pubgrub::report::{DefaultStringReporter, Reporter};
-use pubgrub::solver::Solver;
+use pubgrub::solver::{OfflineSolver, Solver};
 use pubgrub::version::SemanticVersion;
 
 // https://github.com/dart-lang/pub/blob/master/doc/solver.md#branching-error-reporting
 fn main() {
-    let mut solver = SimpleCache::<&str, SemanticVersion>::new();
+    let mut solver = OfflineSolver::<&str, SemanticVersion>::new();
     #[rustfmt::skip]
     // root 1.0.0 depends on foo ^1.0.0
     solver.add_dependencies(

examples/doc_interface.rs

@@ -1,6 +1,5 @@
-use pubgrub::cache::{Cache, SimpleCache};
 use pubgrub::range::Range;
-use pubgrub::solver::Solver;
+use pubgrub::solver::{OfflineSolver, Solver};
 use pubgrub::version::NumberVersion;
 
 // `root` depends on `menu` and `icons`
@@ -9,7 +8,7 @@ use pubgrub::version::NumberVersion;
 // `icons` has no dependency
 #[rustfmt::skip]
 fn main() {
-    let mut solver = SimpleCache::<&str, NumberVersion>::new();
+    let mut solver = OfflineSolver::<&str, NumberVersion>::new();
     solver.add_dependencies(
         "root", 1, vec![("menu", Range::any()), ("icons", Range::any())],
     );

examples/doc_interface_error.rs

@@ -1,8 +1,7 @@
-use pubgrub::cache::{Cache, SimpleCache};
 use pubgrub::error::PubGrubError;
 use pubgrub::range::Range;
 use pubgrub::report::{DefaultStringReporter, Reporter};
-use pubgrub::solver::Solver;
+use pubgrub::solver::{OfflineSolver, Solver};
 use pubgrub::version::SemanticVersion;
 
 // `root` depends on `menu`, `icons 1.0.0` and `intl 5.0.0`
@@ -14,7 +13,7 @@ use pubgrub::version::SemanticVersion;
 // `intl` has no dependency
 #[rustfmt::skip]
 fn main() {
-    let mut solver = SimpleCache::<&str, SemanticVersion>::new();
+    let mut solver = OfflineSolver::<&str, SemanticVersion>::new();
     // Direct dependencies: menu and icons.
     solver.add_dependencies("root", (1, 0, 0), vec![
         ("menu", Range::any()),

examples/doc_interface_semantic.rs

@@ -1,8 +1,7 @@
-use pubgrub::cache::{Cache, SimpleCache};
 use pubgrub::error::PubGrubError;
 use pubgrub::range::Range;
 use pubgrub::report::{DefaultStringReporter, Reporter};
-use pubgrub::solver::Solver;
+use pubgrub::solver::{OfflineSolver, Solver};
 use pubgrub::version::SemanticVersion;
 
 // `root` depends on `menu` and `icons 1.0.0`
@@ -13,7 +12,7 @@ use pubgrub::version::SemanticVersion;
 // `icons` has no dependency
 #[rustfmt::skip]
 fn main() {
-    let mut solver = SimpleCache::<&str, SemanticVersion>::new();
+    let mut solver = OfflineSolver::<&str, SemanticVersion>::new();
     // Direct dependencies: menu and icons.
     solver.add_dependencies("root", (1, 0, 0), vec![
         ("menu", Range::any()),

examples/linear_error_reporting.rs

@@ -1,13 +1,12 @@
-use pubgrub::cache::{Cache, SimpleCache};
 use pubgrub::error::PubGrubError;
 use pubgrub::range::Range;
 use pubgrub::report::{DefaultStringReporter, Reporter};
-use pubgrub::solver::Solver;
+use pubgrub::solver::{OfflineSolver, Solver};
 use pubgrub::version::SemanticVersion;
 
 // https://github.com/dart-lang/pub/blob/master/doc/solver.md#linear-error-reporting
 fn main() {
-    let mut solver = SimpleCache::<&str, SemanticVersion>::new();
+    let mut solver = OfflineSolver::<&str, SemanticVersion>::new();
     #[rustfmt::skip]
     // root 1.0.0 depends on foo ^1.0.0 and baz ^1.0.0
     solver.add_dependencies(

src/cache.rs

@@ -17,7 +17,7 @@ pub enum PubGrubError<P: Package, V: Version> {
     #[error("No solution")]
     NoSolution(DerivationTree<P, V>),
 
-    /// Error arising when the implenter of `Solver`
+    /// Error arising when the implementer of `Solver`
     /// returned an error in the method `list_available_versions`.
     #[error("Retrieving available versions of package {package} failed)")]
     ErrorRetrievingVersions {

src/error.rs

@@ -81,15 +81,15 @@ impl<P: Package, V: Version> State<P, V> {
                     // we must perform conflict resolution.
                     Relation::Satisfied => {
                         let root_cause = self.conflict_resolution(&incompat)?;
-                        // root_cause is guaranted to be almost satisfied by the partial solution
+                        // root_cause is guaranteed to be almost satisfied by the partial solution
                         // according to PubGrub documentation.
                         match self.partial_solution.relation(&root_cause) {
                             Relation::AlmostSatisfied(package_almost, term) => {
                                 changed = vec![package_almost.clone()];
                                 // Add (not term) to the partial solution with incompat as cause.
                                 self.partial_solution.add_derivation(package_almost, term.negate(), root_cause);
                             }
-                            _ => return Err(PubGrubError::Failure("This should never happen, root_cause is guaranted to be almost satisfied by the partial solution".into())),
+                            _ => return Err(PubGrubError::Failure("This should never happen, root_cause is guaranteed to be almost satisfied by the partial solution".into())),
                         }
                     }
                     Relation::AlmostSatisfied(package_almost, term) => {

src/internal/core.rs

@@ -201,14 +201,14 @@ impl<P: Package, V: Version> Incompatibility<P, V> {
     /// they are collapsed together into the single incompatibility {foo ^1.0.0, not bar ^1.0.0}
     /// (provided that no other version of foo exists between 1.0.0 and 2.0.0).
     /// We could collapse them into { foo (1.0.0 ∪ 1.1.0), not bar ^1.0.0 }
-    /// without having to check existance of other versions though.
+    /// without having to check the existence of other versions though.
     /// And it would even keep the same `Kind`: `FromDependencyOf foo`.
     ///
     /// Here we do the simple stupid thing of just growing the Vec.
     /// TODO: improve this.
     /// It may not be trivial since those incompatibilities
     /// may already have derived others.
-    /// Maybe this should not be persued.
+    /// Maybe this should not be pursued.
     pub fn merge_into(self, incompatibilities: &mut Vec<Self>) {
         incompatibilities.push(self);
     }