fix lint errors; updated semver interpretation documentation

.editorconfig

@@ -14,3 +14,10 @@ indent_size = false
 
 [Makefile]
 indent_style = tab
+
+[test/fast/Unit tests/package_json_templates/*]
+indent_style = unset
+
+[test/fast/Unit tests/nvm_get_node_from_pkg_json]
+indent_style = unset
+indent_size = unset

semver.md

@@ -1,38 +1,8 @@
-# Node semantic version interpretation documentation
+# Semantic version interpretation documentation
 
-Node versions are dynamically interpretted from the semver expression that is extracted from the local package.json file. The algorithm for doing this is expressed below. Each step is isolated into its own function to make testing and debugging easier.
+Node versions are interpretted from the semver expression located in the engines.node value of the local package.json file. The algorithm for interpretting the semver is expressed at a high level below and is intended to work with the [semantic versioner for npm](https://docs.npmjs.com/misc/semver).
 
-## 1. Extract the semver expression located in the engines.node value of the local package.json file.
+## 1. Convert the semver into the following grammar:
-  
-#### Required input grammar for semver expression extracted from package.json:
-  
-> Grammar is copied from https://docs.npmjs.com/misc/semver
-> ```
-> range-set  ::= range ( logical-or range ) *
-> logical-or ::= ( ' ' ) * '||' ( ' ' ) *
-> range      ::= hyphen | simple ( ' ' simple ) * | ''
-> hyphen     ::= partial ' - ' partial
-> simple     ::= primitive | partial | tilde | caret
-> primitive  ::= ( '<' | '>' | '>=' | '<=' | '=' | ) partial
-> partial    ::= xr ( '.' xr ( '.' xr qualifier ? )? )?
-> xr         ::= 'x' | 'X' | '*' | nr
-> nr         ::= '0' | ['1'-'9'] ( ['0'-'9'] ) *
-> tilde      ::= '~' partial
-> caret      ::= '^' partial
-> qualifier  ::= ( '-' pre )? ( '+' build )?
-> pre        ::= parts
-> build      ::= parts
-> parts      ::= part ( '.' part ) *
-> part       ::= nr | [-0-9A-Za-z]+
-> ```
-> Lazy grammar validation is used at this point. Basically any string in the engines.node value will be accepted at this point that matches the following regexp:  
-> "[|<> [:alnum:].^=~*-]\+"  
-> 
-> NOTE: all whitespace inside the engines.node value is normalized to be a single space in this step.
-  
-## 2. Check that the extracted semver expression from the previous step matches the above grammar. If so, normalize it into the following grammar that is expected by the interpretation logic.
-  
-#### Required input grammar for internal interpretation logic:
 
 > ```
 > semver         ::= comparator_set ( ' || '  comparator_set )*
@@ -40,11 +10,43 @@ Node versions are dynamically interpretted from the semver expression that is ex
 > comparator     ::= ( '<' | '<=' | '>' | '>=' | '' ) [0-9]+ '.' [0-9]+ '.' [0-9]+
 > ```
 
-## 3. Interpret the normalized semver expression.
+## 2. Resolve each comparator set to its newest compatible node version
 
-> 1. Resolve each comparator set to the newest compatible node version
+**First, if semver only contains a single comparator_set, we may be able to quickly find the newest compatible version.**
-> - iterate through node versions from newest to oldest
+
-> - find the first node version that satisfies all comparators
+```pseudocode
-> - if reached a point where no older node versions will satisfy comparator, stop iterating through node versions.
+if semver is looking for an exact match of some specified version and the specified version is a valid node version
-> 2. Choose the newest node version among the resolved node versions from the previous step.
+  resolve to the specified version
+else if semver is looking for a version less than or equal to some specified version and the specified version is a valid node version
+  resolve to the specified version
+else if semver is looking for a version greater than or equal to some specified version and the current newest node version is greater than or equal to the specified version
+  resolve to the current newest node version
+else if semver is looking for a version strictly greater than to some specified version and the current newest node version is greater than the specified version
+  resolve to the current newest node version
+else
+  quick resolution of semver interpretation not possible
+```
+
+**If quick resolution of semver interpretation does not work, try more complex semver interpretation algorithm.**
+
+```pseudocode
+initialize highest_compatible_versions to an empty list
+initialize node_version_list to the list of current remote node versions
+for each current_comparator_set in the semver {
+  for each current_node_version in node_version_list {
+    for each current_comparator in current_comparator_set {
+      if current_node_version is compatible with current_comparator
+        continue seeing if current_node_version might be compatible with all comparators in current_comparator_set
+      else if current_node_version is not compatible with current_comparator
+        if it can be determined that no older version will satisfy this comparator, we can move on to the next comparator_set in the semver
+      else
+        stop seeing if current_node_version is compatible with all comparators in current_comparator_set and move on to the next version
+    }
+    if current_node_version was found to be compatible with all comparators in current_comparator_set
+      add current_node_version to the highest_compatible_versions list
+  }
+}
+
+resolve to the highest version among all the versions collected in highest_compatible_versions
+```