Added sub-selectors for YAML and JSON #1024 #1045 (#1238)

.markdownlint.json

@@ -20,7 +20,7 @@
     "no-reversed-links": true,
     "no-multiple-blanks": true,
     "line-length": {
-        "line_length": 100,
+        "line_length": 120,
         "code_blocks": false,
         "tables": false,
         "headers": true

.vscode/settings.json

@@ -22,14 +22,16 @@
         "./schemas/PSRule-language.schema.json": [
             "/tests/PSRule.Tests/**.Rule.yaml",
             "/tests/PSRule.Tests/**/**.Rule.yaml",
-            "/docs/scenarios/*/*.Rule.yaml"
+            "/docs/scenarios/*/*.Rule.yaml",
+            "/docs/expressions/**/*.Rule.yaml"
         ]
     },
     "json.schemas": [
         {
             "fileMatch": [
                 "/tests/PSRule.Tests/**.Rule.jsonc",
                 "/tests/PSRule.Tests/**/**.Rule.jsonc",
+                "/docs/expressions/**/*.Rule.jsonc"
             ],
             "url": "./schemas/PSRule-resources.schema.json"
         }

docs/CHANGELOG-v2.md

@@ -13,10 +13,26 @@ See [upgrade notes][1] for helpful information when upgrading from previous vers
 
 **Experimental features**:
 
-- Functions within YAML expressions can be used to perform manipulation prior to testing a condition.
+- Functions within YAML and JSON expressions can be used to perform manipulation prior to testing a condition.
+  See [functions][3] for more information.
+- Sub-selectors within YAML and JSON expressions can be used to filter rules and list properties.
+  See [sub-selectors][4] for more information.
+
+  [3]: expressions/functions.md
+  [4]: expressions/sub-selectors.md
 
 ## Unreleased
 
+What's changed since pre-release v2.4.0-B0039:
+
+- New features:
+  - **Experimental**: Added support for sub-selectors YAML and JSON expressions by @BernieWhite.
+    [#1024](https://github.com/microsoft/PSRule/issues/1024)
+    [#1045](https://github.com/microsoft/PSRule/issues/1045)
+    - Sub-selector pre-conditions add an additional expression to determine if a rule is executed.
+    - Sub-selector object filters provide an way to filter items from list properties.
+    - See [sub-selectors][4] for more information.
+
 ## v2.4.0-B0039 (pre-release)
 
 What's changed since pre-release v2.4.0-B0022:
@@ -27,6 +43,7 @@ What's changed since pre-release v2.4.0-B0022:
     - Added conversion functions `boolean`, `string`, and `integer`.
     - Added lookup functions `configuration`, and `path`.
     - Added string functions `concat`, `substring`.
+    - See [functions][3] for more information.
 - Bug fixes:
   - Fixed reporting of duplicate identifiers which were not generating an error for all cases by @BernieWhite.
     [#1229](https://github.com/microsoft/PSRule/issues/1229)

docs/expressions/SubSelectors.Rule.jsonc

@@ -0,0 +1,74 @@
+[
+  {
+    // Synopsis: A rule with a sub-selector precondition.
+    "apiVersion": "github.com/microsoft/PSRule/v1",
+    "kind": "Rule",
+    "metadata": {
+      "name": "Json.Subselector.Precondition"
+    },
+    "spec": {
+      "where": {
+        "field": "kind",
+        "equals": "api"
+      },
+      "condition": {
+        "field": "resources",
+        "count": 10
+      }
+    }
+  },
+  {
+    // Synopsis: A rule with a sub-selector filter.
+    "apiVersion": "github.com/microsoft/PSRule/v1",
+    "kind": "Rule",
+    "metadata": {
+      "name": "Json.Subselector.Filter"
+    },
+    "spec": {
+      "condition": {
+        "field": "resources",
+        "where": {
+          "type": ".",
+          "equals": "Microsoft.Web/sites/config"
+        },
+        "allOf": [
+          {
+            "field": "properties.detailedErrorLoggingEnabled",
+            "equals": true
+          }
+        ]
+      }
+    }
+  },
+  {
+    // Synopsis: A rule with a sub-selector filter.
+    "apiVersion": "github.com/microsoft/PSRule/v1",
+    "kind": "Rule",
+    "metadata": {
+      "name": "Json.Subselector.FilterOr"
+    },
+    "spec": {
+      "condition": {
+        "anyOf": [
+          {
+            "field": "resources",
+            "where": {
+              "type": ".",
+              "equals": "Microsoft.Web/sites/config"
+            },
+            "allOf": [
+              {
+                "field": "properties.detailedErrorLoggingEnabled",
+                "equals": true
+              }
+            ]
+          },
+          {
+            "field": "resources",
+            "exists": false
+          }
+        ]
+      }
+    }
+  }
+]

docs/expressions/SubSelectors.Rule.yaml

@@ -0,0 +1,57 @@
+# Copyright (c) Microsoft Corporation.
+# Licensed under the MIT License.
+
+#
+# YAML-based rules for documentation
+#
+
+---
+# Synopsis: A rule with a sub-selector precondition.
+apiVersion: github.com/microsoft/PSRule/v1
+kind: Rule
+metadata:
+  name: Yaml.Subselector.Precondition
+spec:
+  where:
+    field: 'kind'
+    equals: 'api'
+  condition:
+    field: resources
+    count: 10
+
+---
+# Synopsis: A rule with a sub-selector filter.
+apiVersion: github.com/microsoft/PSRule/v1
+kind: Rule
+metadata:
+  name: Yaml.Subselector.Filter
+spec:
+  condition:
+    field: resources
+    where:
+      type: '.'
+      equals: 'Microsoft.Web/sites/config'
+    allOf:
+    - field: properties.detailedErrorLoggingEnabled
+      equals: true
+
+---
+# Synopsis: A rule with a sub-selector filter.
+apiVersion: github.com/microsoft/PSRule/v1
+kind: Rule
+metadata:
+  name: Yaml.Subselector.FilterOr
+spec:
+  condition:
+    anyOf:
+
+    - field: resources
+      where:
+        type: '.'
+        equals: 'Microsoft.Web/sites/config'
+      allOf:
+      - field: properties.detailedErrorLoggingEnabled
+        equals: true
+
+    - field: resources
+      exists: false

docs/expressions/functions.md

@@ -1,16 +1,22 @@
-# Expression functions
+# Functions
 
 !!! Abstract
-    Functions are an advanced lanaguage feature specific to YAML and JSON resources.
+    _Functions_ are an advanced lanaguage feature specific to YAML and JSON expressions.
     That extend the language to allow for more complex use cases with expressions.
+    Functions don't apply to script expressions because PowerShell already has rich support for complex manipulation.
 
 !!! Experimental
-    Functions are a work in progress and subject to change.
+    _Functions_ are a work in progress and subject to change.
     We hope to add more functions, broader support, and more detailed documentation in the future.
     [Join or start a disucssion][1] to let us know how we can improve this feature going forward.
 
   [1]: https://github.com/microsoft/PSRule/discussions
 
+Functions cover two (2) main scenarios:
+
+- **Transformation** — you need to perform minor transformation before a condition.
+- **Configuration** — you want to configure an input into a condition.
+
 ## Using functions
 
 It may be necessary to perform minor transformation before evaluating a condition.