molinillo 0.5.7 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA256:
-  metadata.gz: bc6b96b69bd48c80f9653d4f9ec6dc89278555651dce6708d46b72d29d672f1f
-  data.tar.gz: 79e47c90d5bd5122df464d52a578547df0b9813e91c9d222152033a214ab8642
+SHA1:
+  metadata.gz: 9546ad44db45ffeeb600e30f638fb9210cf6c961
+  data.tar.gz: de98b81edb5384a6f0c25608f2809e7671a90559
 SHA512:
-  metadata.gz: f2decb13085180919a650dcb5ded11ac64e4f3d86f5dfad349e05e434bdd425b56229f5c0aec8eefc2185a4eba88a03a5ba8ccb9faf0f1824fb59ce20c1c588d
-  data.tar.gz: 46ab35180ece2e5b385599842fe26487114d1255298ff0a573c891a270f8d0697c9976bf15f0cc279d0288f7c17492e4dceb5f0ed7a47d1b9aa4ff2fc7de0c0c
+  metadata.gz: 6bf39875c6f19a858fbebe6ffd35b7e01bf5e7c45e081289bbda2020b4be8ba6229fd6b9b1629f04017165e5a9cbc1f8affb5fde1ba521670631b3fb1e091e38
+  data.tar.gz: 87eed61627ccbd8f4dbabdd362971e64e028354811fa7548c035749a5baf14999cc15937ba227046f5d96b90a46b8e9a7ecdd97dd8fa630bb6c420fe07ade143

data/ARCHITECTURE.md

@@ -0,0 +1,102 @@
+# Molinillo Architecture
+
+At the highest level, Molinillo is a dependency resolution algorithm.
+You hand the `Resolver` a list of dependencies and a 'locking' `DependencyGraph`, and you get a resulting dependency graph out of that.
+In order to guarantee that the list of dependencies is properly resolved, however, an algorithm is required that is smarter than just walking the list of dependencies and activating each, and its own dependencies, in turn.
+
+## Backtracking
+
+At the heart of Molinillo is a [backtracking](http://en.wikipedia.org/wiki/Backtracking) algorithm with [forward checking](http://en.wikipedia.org/wiki/Look-ahead_(backtracking)).
+Essentially, the resolution process keeps track of two types of states (dependency and possibility) in a stack.
+If that stack is ever exhausted, resolution was impossible.
+New states are pushed onto the stack for every dependency, and every time a dependency is successfully 'activated' a new state is pushed onto the stack that represents that activation.
+This stack-based approach is used because backtracking (also known as *unwinding*) becomes as simple as popping a state off that stack.
+
+### Walkthrough
+
+1. The client initializes a `Resolver` with a `SpecificationProvider` and `UI`
+2. The client calls `resolve` with an array of user-requested dependencies and an optional 'locking' `DependencyGraph`
+3. The `Resolver` creates a new `Resolution` with those four user-specified parameters and calls `resolve` on it
+4. The `Resolution` creates an `initial_state`, which takes the user-requested dependencies and puts them into a `DependencyState`
+  - In the process of creating the state, the `SpecificationProvider` is asked to sort the dependencies and return all the `possibilities` for the `initial_requirement` (taking into account whether the dependency is `locked`). These possibilities are then grouped into `PossibilitySet`s, with each set representing a group of versions for the dependency which share the same sub-dependency requirements
+  - A `DependencyGraph` is created that has all of these requirements point to `root_vertices`
+5. The resolution process now enters its main loop, which continues as long as there is a current `state` to process, and the current state has requirements left to process
+6. `UI#indicate_progress` is called to allow the client to report progress
+7. If the current state is a `DependencyState`, we have it pop off a `PossibilityState` that encapsulates a `PossibilitySet` for that dependency
+8. Process the topmost state on the stack
+9. If there is a non-empty `PossibilitySet` for the state, `attempt_to_activate` it (jump to #11)
+10. If there is no non-empty `PossibilitySet` for the state, `create_conflict` if the state is a `PossibilityState`, and then `unwind_for_conflict`
+  - `create_conflict` builds a `Conflict` object, with details of all of the requirements for the given dependency, and adds it to a hash of conflicts stored on the `state`, indexed by the name of the dependency
+  - `unwind_for_conflict` loops through all the conflicts on the `state`, looking for a state it can rewind to that might avoid that conflict. If no such state exists, it raises a VersionConflict error. Otherwise, it takes the most recent state with a chance to avoid the current conflicts and rewinds to it (go to #6)
+11. Check if there is an existing vertex in the `activated` dependency graph for the dependency this state's `requirement` relates to
+12. If there is no existing vertex in the `activated` dependency graph for the dependency this state's `requirement` relates to, `activate_new_spec`. This creates a new vertex in the `activated` dependency graph, with it's payload set to the possibility's `PossibilitySet`. It also pushes a new `DependencyState`, with the now-activated `PossibilitySet`'s own dependencies. Go to #6
+13. If there is an existing, `activated` vertex for the dependency, `attempt_to_filter_existing_spec`
+  - This filters the contents of the existing vertex's `PossibilitySet` by the current state's `requirement`
+  - If any possibilities remain within the `PossibilitySet`, it updates the activated vertex's payload with the new, filtered state and pushes a new `DependencyState`
+  - If no possibilities remain within the `PossibilitySet` after filtering, or if the current state's `PossibilitySet` had a different set of sub-dependecy requirements to the existing vertex's `PossibilitySet`, `create_conflict` and `unwind_for_conflict`, back to the last `DependencyState` that has a chance to not generate a conflict. Go to #6
+15. Terminate with the topmost state's dependency graph when there are no more requirements left
+16. For each vertex with a payload of allowable versions for this resolution (i.e., a `PossibilitySet`), pick a single specific version.
+
+### Optimal unwinding
+
+For our backtracking algorithm to be efficient as well as correct, we need to
+unwind efficiently after a conflict is encountered. Unwind too far and we'll
+miss valid resolutions - once we unwind passed a DependencyState we can never
+get there again. Unwind too little and resolution will be extremely slow - we'll
+repeatedly hit the same conflict, processing many unnecessary iterations before
+getting to a branch that avoids it.
+
+To unwind the optimal amount, we consider the current conflict, along with all
+the previous unwinds that have determined our current state.
+
+1. First, consider the current conflict as follows:
+  - Find the earliest (lowest index) set of requirements which combine to cause
+  the conflict. Any non-binding requirements can be ignored, as removing them
+  would not resolve the current onflict
+  - For each binding requirement, find all the alternative possibilities that
+  would relax the requirement:
+    - the requirement's DependencyState might have alternative possibilities
+    that would satisfy all the other requirements
+    - the parent of the requirement might have alternative possibilities that
+    would prevent the requirement existing
+    - the parent of the parent of the requirement might have alternative
+    possibilities that would prevent the parent, and thus the requirement,
+    from existing
+    - etc., etc.
+  - Group all of the above possibilities into an array, and pick the one with
+  the highest index (i.e., the smallest rewind) as our candidate rewind
+2. Next, consider any previous unwinds that were not executed (because a
+different, smaller unwind was chosen instead):
+  - Ignore any previously unused unwinds that would now unwind further than the
+  highest index found in (1), if any
+  - For the remaining unused unwinds, check whether the unwind has a chance of
+  preventing us encountering the current conflict. For this to be the case, the
+  unwind must have been rejected in favour of an unwind to one of the states in
+  the current conflict's requirement tree
+  - If any such unwinds exist, use the one with the highest index (smallest
+  unwind) instead of the one found in (1)
+3a. If no possible unwind was found in (1) and (2), raise a VersionConflict
+error as resolution is not possible.
+3b. Filter the state that we're unwinding to, in order to remove any
+possibilities we know will result in a conflict. Consider all possible unwinds
+to the chosen state (there may be several, amasssed from previous unused
+unwinds for different conflicts) when doing this filtering - only
+possibilities that will certainly result in *all* of those conflicts can be
+filtered out as having no chance of resolution
+4. Update the list of unused unwinds:
+  - Add all possible unwinds for the current conflict
+  - Update the `requirements_unwound_to_instead` attribute on any considered
+  unwind that was only rejected because it had a lower index than the chosen one
+  - Remove all unwinds to a state greater than or equal to the chosen unwind
+5. Go to #6 in the main loop
+
+## Specification Provider
+
+The `SpecificationProvider` module forms the basis for the key integration point for a client library with Molinillo.
+Its methods convert the client's domain-specific model objects into concepts the resolver understands:
+
+- Nested dependencies
+- Names
+- Requirement satisfaction
+- Finding specifications (known internally as `possibilities`)
+- Sorting dependencies (for the sake of reasonable resolver performance)

data/CHANGELOG.md

@@ -0,0 +1,352 @@
+# Molinillo Changelog
+
+## 0.6.0 (2017-07-27)
+
+##### Breaking
+
+* Objects returned by `dependencies_for` and passed to `resolve` must properly implement
+  both `==` and `eql?`, such that they return `true` when they exhibit the same behavior in
+  `requirement_satisfied_by?`.  
+
+##### Enhancements
+
+* Speed up dependency resolution by considering multiple possible versions of a
+  dependency at once, grouped by sub-dependencies. Groups are then filtered as
+  additional requirements are introduced. If a group's sub-dependencies cause
+  conflicts the entire group can be discarded, which reduces the number of
+  possibilities that have to be tested to find a resolution.  
+  [Grey Baker](https://github.com/greysteil)
+  [Samuel Giddins](https://github.com/segiddins)
+  [#69](https://github.com/CocoaPods/Molinillo/pull/69)
+
+* Check for locked requirements when generating a new state's possibilities
+  array, and reduce possibilities set accordingly. Reduces scope for erroneous
+  VersionConflict errors.  
+  [Grey Baker](https://github.com/greysteil)
+  [#67](https://github.com/CocoaPods/Molinillo/pull/67)
+
+* Add `VersionConflict#message_with_trees` for consumers who prefer a more verbose
+  conflict message that includes full requirement trees for all conflicts.  
+  [Samuel Giddins](https://github.com/segiddins)
+
+##### Bug Fixes
+
+* Improve unwinding by considering previous conflicts for the same dependency
+  when deciding which state to unwind to. Previously, prior conflicts were
+  stored in a hash indexed by their name, with only the most recent conflict
+  stored for each dependency. With this fix, Molinillo can resolve anything
+  that's thrown at it. 🎉  
+  [Grey Baker](https://github.com/greysteil)
+  [#73](https://github.com/CocoaPods/Molinillo/pull/73)
+
+* Only raise CircularDependency errors if they prevent resolution.  
+  [Ian Young](https://github.com/iangreenleaf)
+  [Grey Baker](https://github.com/greysteil)
+  [#78](https://github.com/CocoaPods/Molinillo/pull/78)
+
+* Consider additional (binding) requirements that caused a conflict when
+  determining which state to unwind to. Previously, in some cases Molinillo
+  would erroneously throw a VersionConflict error if multiple requirements
+  combined to cause a conflict.  
+  [Grey Baker](https://github.com/greysteil)
+  [#72](https://github.com/CocoaPods/Molinillo/pull/72) 
+
+* Consider previous conflicts when determining the state to unwind to. If a
+  previous conflict, for a different dependency, is the reason we ended up with
+  the current conflict, then unwinding to a state that would not have caused
+  that conflict could prevent the current one, too.  
+  [Grey Baker](https://github.com/greysteil)
+  [#72](https://github.com/CocoaPods/Molinillo/pull/72)
+
+
+## 0.5.7 (2017-03-03)
+
+##### Enhancements
+
+* None.  
+
+##### Bug Fixes
+
+* Keep a stack of parents per requirement, so unwinding past a swap point that
+  updated the parent of the requirement works.  
+  [Samuel Giddins](https://github.com/segiddins)
+  [bundler#5425](https://github.com/bundler/bundler/issues/5425)
+
+
+## 0.5.6 (2017-02-08)
+
+##### Enhancements
+
+* None.  
+
+##### Bug Fixes
+
+* Only reset the parent of a requirement after swapping when its original parent
+  was the same vertex being swapped.  
+  [Samuel Giddins](https://github.com/segiddins)
+  [bundler#5359](https://github.com/bundler/bundler/issues/5359)
+  [bundler#5362](https://github.com/bundler/bundler/issues/5362)
+
+
+## 0.5.5 (2017-01-07)
+
+##### Enhancements
+
+* None.  
+
+##### Bug Fixes
+
+* Only remove requirements from the to-be-resolved list if there are no
+  activated vertices depending upon them after swapping.  
+  [Samuel Giddins](https://github.com/segiddins)
+  [bundler#5294](https://github.com/bundler/bundler/issues/5294)
+
+
+## 0.5.4 (2016-11-14)
+
+##### Enhancements
+
+* None.  
+
+##### Bug Fixes
+
+* Fix unwinding when both sides of a conflict have a common parent
+  requirement.  
+  [Samuel Giddins](https://github.com/segiddins)
+  [bundler#5154](https://github.com/bundler/bundler/issues/5154)
+
+
+## 0.5.3 (2016-10-28)
+
+##### Enhancements
+
+* None.  
+
+##### Bug Fixes
+
+* Fixed a regression in v0.5.2 that could cause resolution to fail after
+  swapping, because stale dependencies would still be in the requirements
+  list.  
+  [Samuel Giddins](https://github.com/segiddins)
+  [#48](https://github.com/CocoaPods/Molinillo/issues/48)
+
+* Rename `Action.name` to `Action.action_name` to avoid overriding
+  `Module.name`.  
+  [Samuel Giddins](https://github.com/segiddins)
+  [#50](https://github.com/CocoaPods/Molinillo/issues/50)
+
+
+## 0.5.2 (2016-10-24)
+
+##### Enhancements
+
+* None.  
+
+##### Bug Fixes
+
+* Fixed a bug where `Resolution#parent_of` would return the incorrect parent for
+  a dependency after swapping had occurred, resulting in resolution failing.  
+  [Samuel Giddins](https://github.com/segiddins)
+  [bundler#5059](https://github.com/bundler/bundler/issues/5059)
+
+
+## 0.5.1 (2016-09-12)
+
+##### Enhancements
+
+* None.  
+
+##### Bug Fixes
+
+* Fixed a bug where `Resolution#parent_of` would return the incorrect parent for
+  a dependency, resulting in resolution failing.  
+  [Samuel Giddins](https://github.com/segiddins)
+  [bundler#4961](https://github.com/bundler/bundler/issues/4961)
+
+
+## 0.5.0 (2016-06-14)
+
+##### Enhancements
+
+* Add an operation log to `DependencyGraph` to eliminate the need for graph
+  copies during dependency resolution, resulting in a 3-100x speedup and
+  reduction in allocations.  
+  [Samuel Giddins](https://github.com/segiddins)
+  [bundler#4376](https://github.com/bundler/bundler/issues/4376)
+
+* Remove all metaprogramming to reduce array allocation overhead and improve
+  discoverability.  
+  [Samuel Giddins](https://github.com/segiddins)
+
+##### Bug Fixes
+
+* None.  
+
+
+## 0.4.5 (2016-04-30)
+
+##### Enhancements
+
+* For performance, don't needlessly dup objects in
+  `Resolution#push_state_for_requirements`.  
+  [Joe Rafaniello](https://github.com/jrafanie)
+
+##### Bug Fixes
+
+* Recursively prune requirements when removing an orphan after swapping.  
+  [Daniel DeLeo](https://github.com/danielsdeleo)
+  [berkshelf/solve#57](https://github.com/berkshelf/solve/issues/57)
+
+
+## 0.4.4 (2016-02-28)
+
+##### Bug Fixes
+
+* Fix mutating a frozen string in `NoSuchDependencyError#message`.  
+  [Samuel Giddins](https://github.com/segiddins)
+
+
+## 0.4.3 (2016-02-18)
+
+##### Enhancements
+
+* Add frozen string literal comments to all ruby files.  
+  [Samuel Giddins](https://github.com/segiddins)
+
+##### Bug Fixes
+
+* Prune the dependency list when removing an orphan after swapping.  
+  [Samuel Giddins](https://github.com/segiddins)
+  [bundler/bundler#4276](https://github.com/bundler/bundler/issues/4276)
+
+
+## 0.4.2 (2016-01-30)
+
+##### Bug Fixes
+
+* Detaching a vertex correctly removes it from the list of successors of its
+  predecessors.  
+  [Samuel Giddins](https://github.com/segiddins)
+
+* Vertices orphaned after swapping dependencies are properly cleaned up from the
+  graph of activated specs.  
+  [Samuel Giddins](https://github.com/segiddins)
+  [bundler/bundler#4198](https://github.com/bundler/bundler/issues/4198)
+
+
+## 0.4.1 (2015-12-30)
+
+##### Enhancements
+
+* Ensure every API is 100% documented.  
+  [Samuel Giddins](https://github.com/segiddins)
+  [#22](https://github.com/CocoaPods/Molinillo/issues/22)
+
+
+## 0.4.0 (2015-07-27)
+
+##### API Breaking Changes
+
+* The `DependencyGraph` no longer treats root vertices specially, nor does it
+  maintain a direct reference to `edges`. Additionally, `Vertex` no longer
+  has a reference to its parent graph.  
+
+##### Enhancements
+
+* Resolution has been sped up by 25x in some pathological cases, and in general
+  recursive operations on a `DependencyGraph` or `Vertex` are now `O(n)`.  
+  [Samuel Giddins](https://github.com/segiddins)
+  [Bundler#3803](https://github.com/bundler/bundler/issues/3803)
+
+* Re-sorting of dependencies is skipped when the unresolved dependency list has
+  not changed, speeding up resolution of fully locked graphs.  
+  [Samuel Giddins](https://github.com/segiddins)
+
+
+## 0.3.1 (2015-07-24)
+
+##### Enhancements
+
+* Add `Conflict#activated_by_name` to allow even richer version conflict
+  messages.  
+  [Samuel Giddins](https://github.com/segiddins)
+
+##### Bug Fixes
+
+* Ensure `Conflict#requirement_trees` is exhaustive.  
+  [Samuel Giddins](https://github.com/segiddins)
+  [Bundler#3860](https://github.com/bundler/bundler/issues/3860)
+
+
+## 0.3.0 (2015-06-29)
+
+##### Enhancements
+
+* Add the ability to optionally skip dependencies that have no possibilities.  
+  [Samuel Giddins](https://github.com/segiddins)
+
+
+## 0.2.3 (2015-03-28)
+
+##### Bug Fixes
+
+* Silence a silly MRI warning about declaring private attributes.  
+  [Piotr Szotkowski](https://github.com/chastell)
+  [Bundler#3516](https://github.com/bundler/bundler/issues/3516)
+  [Bundler#3525](https://github.com/bundler/bundler/issues/3525)
+
+
+## 0.2.2 (2015-03-27)
+
+##### Bug Fixes
+
+* Use an ivar in `DependencyGraph#initialize_copy` to silence an MRI warning.  
+  [Samuel Giddins](https://github.com/segiddins)
+  [Bundler#3516](https://github.com/bundler/bundler/issues/3516)
+
+
+## 0.2.1 (2015-02-21)
+
+* Allow resolving some pathological cases where the backjumping algorithm would
+  skip over a valid possibility.  
+  [Samuel Giddins](https://github.com/segiddins)
+
+
+## 0.2.0 (2014-12-25)
+
+* Institute stricter forward checking by backjumping to the source of a
+  conflict, even if that source comes from the existing spec. This further
+  improves performance in highly conflicting situations when sorting heuristics
+  prove misleading.  
+  [Samuel Giddins](https://github.com/segiddins)
+  [Smit Shah](https://github.com/Who828)
+
+* Add support for topologically sorting a dependency graph's vertices.  
+  [Samuel Giddins](https://github.com/segiddins)
+
+
+## 0.1.2 (2014-11-19)
+
+##### Enhancements
+
+* Improve performance in highly conflicting situations by backtracking more than
+  one state at a time.  
+  [Samuel Giddins](https://github.com/segiddins)
+
+##### Bug Fixes
+
+* Ensure that recursive invocations of `detach_vertex_named` don't lead to
+  messaging `nil`.  
+  [Samuel Giddins](https://github.com/segiddins)
+  [CocoaPods#2805](https://github.com/CocoaPods/CocoaPods/issues/2805)
+
+## 0.1.1 (2014-11-06)
+
+* Ensure that an unwanted exception is not raised when an error occurs before
+  the initial state has been pushed upon the stack.  
+  [Samuel Giddins](https://github.com/segiddins)
+
+## 0.1.0 (2014-10-26)
+
+* Initial release.  
+  [Samuel Giddins](https://github.com/segiddins)