Version assertion improvements #714 #715 (#716)

.vscode/settings.json

@@ -16,7 +16,8 @@
     "yaml.schemas": {
         "./schemas/PSRule-options.schema.json": [
             "/tests/PSRule.Tests/PSRule.*.yml",
-            "/docs/scenarios/*/ps-rule.yaml"
+            "/docs/scenarios/*/ps-rule.yaml",
+            "/ps-rule.yaml"
         ],
         "./schemas/PSRule-language.schema.json": [
             "/tests/PSRule.Tests/**.Rule.yaml",

docs/CHANGELOG-v1.md

@@ -12,8 +12,13 @@ See [upgrade notes][upgrade-notes] for helpful information when upgrading from p
 
 What's changed since pre-release v1.4.0-B2105004:
 
+- General improvements:
+  - Improved support for version constraints by:
+    - Constraints can include prerelease versions of other matching versions. [#714](https://github.com/microsoft/PSRule/issues/714)
+    - Constraint sets allow multiple constraints to be joined together. [#715](https://github.com/microsoft/PSRule/issues/715)
+    - See [about_PSRule_Assert] for details.
 - Bug fixes:
-  - Fixed pre-release constraint handling for pre-releases versions. [#712](https://github.com/microsoft/PSRule/issues/712)
+  - Fixed prerelease constraint handling for prerelease versions. [#712](https://github.com/microsoft/PSRule/issues/712)
 
 ## v1.4.0-B2105004 (pre-release)
 

docs/concepts/PSRule/en-US/about_PSRule_Assert.md

@@ -1178,6 +1178,8 @@ The following parameters are accepted:
 - `field` - The name of the field to check.
 This is a case insensitive compare.
 - `constraint` (optional) - A version constraint, see below for details of version constrain format.
+- `includePrerelease` (optional) - Determines if prerelease versions are included.
+Unless specified this defaults to `$False`.
 
 The following are supported constraints:
 
@@ -1198,15 +1200,29 @@ The following are supported constraints:
 
 An empty, null or `*` constraint matches all valid semantic versions.
 
+Multiple constraints can be joined together:
+
+- Use a _space_ to separate multiple constraints, each must be true (_logical AND_).
+- Separates constraint sets with the double pipe `||`.
+Only one constraint set must be true (_logical OR_).
+
+By example:
+
+- `1.2.3 || >=3.4.5 <5.0.0` results in:
+  - Pass: `1.2.3`, `3.4.5`, `3.5.0`, `4.9.9`.
+  - Fail: `3.0.0`, `5.0.0`.
+
 Handling for pre-release versions:
 
 - Constraints and versions containing pre-release identifiers are supported.
 i.e. `>=1.2.3-build.1` or `1.2.3-build.1`.
 - A version containing a pre-release identifer follows semantic versioning rules.
 i.e. `1.2.3-alpha` < `1.2.3-alpha.1` < `1.2.3-alpha.beta` < `1.2.3-beta` < `1.2.3-beta.2` < `1.2.3-beta.11` < `1.2.3-rc.1` < `1.2.3`.
-- A constraint without a pre-release identifer will only match a stable version.
+- A constraint without a pre-release identifer will only match a stable version by default.
+Set `includePrerelease` to `$True` to include prerelease versions.
 - Constraints with a pre-release identifer will only match:
-  - Matching pre-release versions of the same major.minor.patch version.
+  - Matching pre-release versions of the same major.minor.patch version by default.
+  Set `includePrerelease` to `$True` to include prerelease versions of all matching versions.
   - Matching stable versions.
 
 By example:

schemas/PSRule-options.schema.json

@@ -513,8 +513,19 @@
             "description": "Specifies the required version of a module to use.",
             "markdownDescription": "Specifies the required version of a module to use. [See help](https://microsoft.github.io/PSRule/concepts/PSRule/en-US/about_PSRule_Options.html#requires)",
             "additionalProperties": {
-                "type": "string"
-            }
+                "type": "string",
+                "title": "Version constraint",
+                "description": "Specifies a module to constrain to a specific version.",
+                "markdownDescription": "Specifies a module to constrain to a specific version. [See help](https://microsoft.github.io/PSRule/concepts/PSRule/en-US/about_PSRule_Options.html#requires)"
+            },
+            "defaultSnippets": [
+                {
+                    "label": "Version constraint",
+                    "body": {
+                        "${1:Module}": "${2:'>=1.0.0'}"
+                    }
+                }
+            ]
         },
         "rule-option": {
             "type": "object",

src/PSRule/Common/EnvironmentHelper.cs

@@ -2,7 +2,6 @@
 // Licensed under the MIT License.
 
 using System;
-using System.Collections;
 using System.Collections.Generic;
 using System.Net;
 using System.Security;

src/PSRule/Common/KeyMapDictionary.cs

@@ -136,7 +136,7 @@ internal void Load(string prefix, EnvironmentHelper env, Func<string, string> fo
                         suffix = format(suffix);
 
                     _Map[suffix] = (TValue)variable.Value;
-                }   
+                }
             }
         }
 

src/PSRule/Configuration/BaselineOption.cs

@@ -4,7 +4,6 @@
 using PSRule.Definitions;
 using System.Collections;
 using System.Collections.Generic;
-using System.Linq;
 
 namespace PSRule.Configuration
 {

src/PSRule/Pipeline/PipelineBuilder.cs

@@ -235,7 +235,7 @@ private bool GuardModuleVersion(string moduleName, string moduleVersion, string
 
         private static bool TryModuleVersion(string moduleVersion, string requiredVersion)
         {
-            if (!(SemanticVersion.TryParseVersion(moduleVersion, out SemanticVersion.Version version) && SemanticVersion.TryParseConstraint(requiredVersion, out SemanticVersion.Constraint constraint)))
+            if (!(SemanticVersion.TryParseVersion(moduleVersion, out SemanticVersion.Version version) && SemanticVersion.TryParseConstraint(requiredVersion, out SemanticVersion.IConstraint constraint)))
                 return false;
 
             return constraint.Equals(version);

src/PSRule/Pipeline/PipelineReciever.cs

@@ -4,7 +4,6 @@
 using Newtonsoft.Json;
 using PSRule.Data;
 using PSRule.Parser;
-using PSRule.Resources;
 using PSRule.Runtime;
 using System;
 using System.Collections;
@@ -17,7 +16,6 @@
 using YamlDotNet.Core.Events;
 using YamlDotNet.Serialization;
 using YamlDotNet.Serialization.NodeDeserializers;
-using YamlDotNet.Serialization.ValueDeserializers;
 
 namespace PSRule.Pipeline
 {

src/PSRule/Runtime/Assert.cs

@@ -8,7 +8,6 @@
 using PSRule.Pipeline;
 using PSRule.Resources;
 using System;
-using System.Collections;
 using System.IO;
 using System.Management.Automation;
 using System.Net;
@@ -571,7 +570,7 @@ public AssertResult TypeOf(PSObject inputObject, string field, string[] type)
         /// <summary>
         /// The object field value should match the version constraint. Only applies to strings.
         /// </summary>
-        public AssertResult Version(PSObject inputObject, string field, string constraint = null)
+        public AssertResult Version(PSObject inputObject, string field, string constraint = null, bool includePrerelease = false)
         {
             // Guard parameters
             if (GuardNullParam(inputObject, nameof(inputObject), out AssertResult result) ||
@@ -580,7 +579,7 @@ public AssertResult Version(PSObject inputObject, string field, string constrain
                 GuardSemanticVersion(fieldValue, out SemanticVersion.Version value, out result))
                 return result;
 
-            if (!Runtime.SemanticVersion.TryParseConstraint(constraint, out SemanticVersion.Constraint c))
+            if (!SemanticVersion.TryParseConstraint(constraint, out SemanticVersion.IConstraint c, includePrerelease))
                 throw new RuleException(string.Format(Thread.CurrentThread.CurrentCulture, PSRuleResources.VersionConstraintInvalid, value));
 
             // Assert

src/PSRule/Runtime/ObjectHelper.cs

@@ -385,7 +385,7 @@ private static IEnumerable<PropertyInfo> GetIndexerProperties(Type baseType)
             else
             {
                 var properties = baseType.GetProperties();
-                foreach(PropertyInfo pi in properties)
+                foreach (PropertyInfo pi in properties)
                 {
                     var p = pi.GetIndexParameters();
                     if (p.Length > 0)