Added API version date comparison microsoft#1356 (microsoft#1365)

BernieWhite · Dec 2, 2022 · a56520f · a56520f
1 parent 1f878e9
commit a56520f
Show file tree

Hide file tree

Showing 16 changed files with 1,370 additions and 12 deletions.
diff --git a/README.md b/README.md
@@ -173,6 +173,7 @@ The following commands exist in the `PSRule` module:
 The following conceptual topics exist in the `PSRule` module:
 
 - [Assert](https://microsoft.github.io/PSRule/v2/concepts/PSRule/en-US/about_PSRule_Assert/)
+  - [APIVersion](https://microsoft.github.io/PSRule/v2/concepts/PSRule/en-US/about_PSRule_Assert/#apiversion)
   - [Contains](https://microsoft.github.io/PSRule/v2/concepts/PSRule/en-US/about_PSRule_Assert/#contains)
   - [Count](https://microsoft.github.io/PSRule/v2/concepts/PSRule/en-US/about_PSRule_Assert/#count)
   - [EndsWith](https://microsoft.github.io/PSRule/v2/concepts/PSRule/en-US/about_PSRule_Assert/#endswith)
@@ -235,6 +236,7 @@ The following conceptual topics exist in the `PSRule` module:
 - [Expressions](https://microsoft.github.io/PSRule/v2/concepts/PSRule/en-US/about_PSRule_Expressions/)
   - [AllOf](https://microsoft.github.io/PSRule/v2/concepts/PSRule/en-US/about_PSRule_Expressions/#allof)
   - [AnyOf](https://microsoft.github.io/PSRule/v2/concepts/PSRule/en-US/about_PSRule_Expressions/#anyof)
+  - [APIVersion](https://microsoft.github.io/PSRule/v2/concepts/PSRule/en-US/about_PSRule_Expressions/#apiversion)
   - [Contains](https://microsoft.github.io/PSRule/v2/concepts/PSRule/en-US/about_PSRule_Expressions/#contains)
   - [Count](https://microsoft.github.io/PSRule/v2/concepts/PSRule/en-US/about_PSRule_Expressions/#count)
   - [EndsWith](https://microsoft.github.io/PSRule/v2/concepts/PSRule/en-US/about_PSRule_Expressions/#endswith)

diff --git a/docs/CHANGELOG-v2.md b/docs/CHANGELOG-v2.md
@@ -32,6 +32,9 @@ See [upgrade notes][1] for helpful information when upgrading from previous vers
 
 What's changed since pre-release v2.7.0-B0016:
 
+- New features:
+  - Added API version date comparison assertion method and expression by @BernieWhite.
+    [#1356](https://github.com/microsoft/PSRule/issues/1356)
 - Bug fixes:
   - Fixes CLI failed to load required assemblies by @BernieWhite.
     [#1361](https://github.com/microsoft/PSRule/issues/1361)

diff --git a/docs/concepts/PSRule/en-US/about_PSRule_Assert.md b/docs/concepts/PSRule/en-US/about_PSRule_Assert.md
@@ -20,6 +20,7 @@ Each `$Assert` method returns an `AssertResult` object that contains the result
 
 The following built-in assertion methods are provided:
 
+- [APIVersion](#apiversion) - The field value must be a date version string.
 - [Contains](#contains) - The field value must contain at least one of the strings.
 - [Count](#count) - The field value must contain the specified number of items.
 - [EndsWith](#endswith) - The field value must match at least one suffix.
@@ -138,6 +139,88 @@ Notable differences between object paths and JSONPath are:
   However member names can not start or end with a dash.
   i.e. `Properties.dashed-name` and `Properties.'-dashed-name'` are valid.
 
+### APIVersion
+
+The `APIVersion` assertion method checks the field value is a valid date version.
+A constraint can optionally be provided to require the date version to be within a range.
+
+A date version uses the format `yyyy-MM-dd` (`2015-10-01`).
+Additionally an optional string prerelease identifier can be used `yyyy-MM-dd-prerelease` (`2015-10-01-preview.1`).
+
+The following parameters are accepted:
+
+- `inputObject` - The object being checked for the specified field.
+- `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:
+
+- `version` - Must match version exactly. This also accepts the prefix `=`.
+  - e.g. `2015-10-01`, `=2015-10-01`
+- `>version` - Must be greater than version.
+  - e.g. `>2015-10-01`
+- `>=version` - Must be greater than or equal to version.
+  - e.g. `>=2015-10-01`
+- `<version` - Must be less than version.
+  - e.g. `<2022-03-01`
+- `<=version` - Must be less than or equal to version.
+  - e.g. `<=2022-03-01`
+
+An empty, null or `*` constraint matches all valid date 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:
+
+- `2014-01-01 || >=2015-10-01 <2022-03-01` results in:
+  - Pass: `2014-01-01`, `2015-10-01`, `2019-06-30`, `2022-02-01`.
+  - Fail: `2015-01-01`, `2022-09-01`.
+
+Handling for prerelease versions:
+
+- Constraints and versions containing prerelease identifiers are supported.
+  i.e. `>=2015-10-01-preview` or `2015-10-01-preview`.
+- A version containing a prerelease identifer follows similar ordering to semantic versioning.
+  i.e. `2015-10-01-preview` < `2015-10-01-preview.1` < `2015-10-01` < `2022-03-01-preview` < `2022-03-01`.
+- A constraint without a prerelease identifer will only match a stable version by default.
+  Set `includePrerelease` to `$True` to include prerelease versions.
+  Alternatively use the `@pre` or `@prerelease` flag in a constraint.
+
+Reasons include:
+
+- _The parameter 'inputObject' is null._
+- _The parameter 'field' is null or empty._
+- _The field '{0}' does not exist._
+- _The field value '{0}' is not a version string._
+- _The version '{0}' does not match the constraint '{1}'._
+
+Examples:
+
+```powershell
+Rule 'ValidAPIVersion' {
+    $Assert.APIVersion($TargetObject, 'apiVersion')
+}
+
+Rule 'MinimumAPIVersion' {
+    $Assert.APIVersion($TargetObject, 'apiVersion', '>=2015-10-01')
+}
+
+Rule 'MinimumAPIVersionWithPrerelease' {
+    $Assert.APIVersion($TargetObject, 'apiVersion', '>=2015-10-01-0', $True)
+}
+
+Rule 'MinimumAPIVersionWithFlag' {
+    $Assert.APIVersion($TargetObject, 'apiVersion', '@pre >=2015-10-01-0')
+}
+```
+
 ### Contains
 
 The `Contains` assertion method checks the field value contains the specified string.

diff --git a/docs/concepts/PSRule/en-US/about_PSRule_Expressions.md b/docs/concepts/PSRule/en-US/about_PSRule_Expressions.md
@@ -18,6 +18,7 @@ Expressions are comprised of nested conditions, operators, and comparison proper
 
 The following conditions are available:
 
+- [APIVersion](#apiversion)
 - [Contains](#contains)
 - [Count](#count)
 - [Equals](#equals)
@@ -158,6 +159,54 @@ spec:
       exists: true
 ```
 
+### APIVersion
+
+The `apiVersion` condition determines if the operand is a valid date version.
+A constraint can optionally be provided to require the date version to be within a range.
+Supported version constraints for expression are the same as the `$Assert.APIVersion` assertion helper.
+
+Syntax:
+
+```yaml
+apiVersion: <string>
+includePrerelease: <bool>
+```
+
+For example:
+
+```yaml
+---
+apiVersion: github.com/microsoft/PSRule/v1
+kind: Rule
+metadata:
+  name: 'ExampleAPIVersion'
+spec:
+  condition:
+    field: 'engine.apiVersion'
+    apiVersion: '>=2015-10-01'
+
+---
+apiVersion: github.com/microsoft/PSRule/v1
+kind: Selector
+metadata:
+  name: 'ExampleAnyAPIVersion'
+spec:
+  if:
+    field: 'engine.apiVersion'
+    apiVersion: ''
+
+---
+apiVersion: github.com/microsoft/PSRule/v1
+kind: Selector
+metadata:
+  name: 'ExampleAPIVersionIncludingPrerelease'
+spec:
+  if:
+    field: 'engine.apiVersion'
+    apiVersion: '>=2015-10-01'
+    includePrerelease: true
+```
+
 ### Contains
 
 The `contains` condition can be used to determine if the operand contains a specified sub-string.

diff --git a/schemas/PSRule-language.schema.json b/schemas/PSRule-language.schema.json
@@ -913,6 +913,9 @@
         {
           "$ref": "#/definitions/expressions/definitions/conditions/definitions/version"
         },
+        {
+          "$ref": "#/definitions/expressions/definitions/conditions/definitions/apiVersion"
+        },
         {
           "$ref": "#/definitions/expressions/definitions/conditions/definitions/hasDefault"
         },
@@ -1280,6 +1283,9 @@
             {
               "$ref": "#/definitions/expressions/definitions/conditions/definitions/version"
             },
+            {
+              "$ref": "#/definitions/expressions/definitions/conditions/definitions/apiVersion"
+            },
             {
               "$ref": "#/definitions/expressions/definitions/conditions/definitions/hasDefault"
             },
@@ -2638,6 +2644,41 @@
               "additionalProperties": false,
               "minProperties": 2
             },
+            "apiVersion": {
+              "type": "object",
+              "properties": {
+                "apiVersion": {
+                  "type": "string",
+                  "title": "API Version",
+                  "description": "Must be a valid date version. A constraint can optionally be provided to require the date version to be within a range.",
+                  "markdownDescription": "Must be a valid date version. A constraint can optionally be provided to require the date version to be within a range. [See help](https://microsoft.github.io/PSRule/v2/concepts/PSRule/en-US/about_PSRule_Expressions/#apiversion)",
+                  "default": ""
+                },
+                "includePrerelease": {
+                  "type": "boolean",
+                  "title": "Include pre-release",
+                  "description": "Determines if pre-release versions are included. By default, pre-release versions are not included.",
+                  "markdownDescription": "Determines if pre-release versions are included. By default, pre-release versions are not included. [See help](https://microsoft.github.io/PSRule/v2/concepts/PSRule/en-US/about_PSRule_Expressions/#apiversion)",
+                  "default": false
+                },
+                "field": {
+                  "$ref": "#/definitions/expressions/definitions/properties/definitions/field"
+                },
+                "value": {
+                  "$ref": "#/definitions/expressions/definitions/properties/definitions/value"
+                }
+              },
+              "required": [
+                "apiVersion"
+              ],
+              "oneOf": [
+                {
+                  "$ref": "#/definitions/expressions/definitions/properties"
+                }
+              ],
+              "additionalProperties": false,
+              "minProperties": 2
+            },
             "hasDefault": {
               "type": "object",
               "properties": {