Merge branch 'fix-metadata-version' of https://github.com/Gijsreyn/operation-methods into fix-metadata-version

Author: Gijsreyn

.vscode/docs.code-snippets

@@ -1,9 +1,9 @@
 {
-	// Place your DSCv3 workspace snippets here. Each snippet is defined under a snippet name and has a scope, prefix, body and 
-	// description. Add comma separated ids of the languages where the snippet is applicable in the scope field. If scope 
-	// is left empty or omitted, the snippet gets applied to all languages. The prefix is what is 
-	// used to trigger the snippet and the body will be expanded and inserted. Possible variables are: 
-	// $1, $2 for tab stops, $0 for the final cursor position, and ${1:label}, ${2:another} for placeholders. 
+	// Place your DSCv3 workspace snippets here. Each snippet is defined under a snippet name and has a scope, prefix, body and
+	// description. Add comma separated ids of the languages where the snippet is applicable in the scope field. If scope
+	// is left empty or omitted, the snippet gets applied to all languages. The prefix is what is
+	// used to trigger the snippet and the body will be expanded and inserted. Possible variables are:
+	// $1, $2 for tab stops, $0 for the final cursor position, and ${1:label}, ${2:another} for placeholders.
 	// Placeholders with the same ids are connected.
 	"Configuration function template": {
 		"scope": "markdown",
@@ -140,7 +140,7 @@
 			"  </details>",
 			""
 		]
-	}
+	},
 	"Changelog Entry Multi Item": {
 		"scope": "markdown",
 		"prefix": "docs-changelog-entry-multi-issue-pr",
@@ -158,7 +158,7 @@
 			"  </details>",
 			""
 		]
-	}
+	},
 	"Changelog release heading": {
 		"scope": "markdown",
 		"prefix": "docs-changelog-release-heading",
@@ -173,14 +173,22 @@
 			"[release-${1:v3.0.0-${2:alpha.5}}]: https://github.com/PowerShell/DSC/releases/tag/${1:v3.0.0-${2:alpha.5}} \"Link to the DSC ${1:v3.0.0-${2:alpha.5}} release on GitHub\"",
 			"[compare-${1:v3.0.0-${2:alpha.5}}]: https://github.com/PowerShell/DSC/compare/v3.0.0-alpha.4...${1:v3.0.0-${2:alpha.5}}"
 		]
-	
-	}
+	},
 	"Github Work Item Link": {
 		"scope": "markdown",
 		"prefix": "docs-gh-link",
 		"description": "Template for a DSC Github work item link",
 		"body": [
 			"[#${1:work item id}]: https://github.com/PowerShell/DSC/issues/${1:work item id}"
 		]
-	}
+	},
+	"RFC table entry": {
+		"scope": "markdown",
+		"prefix": "rfc-table-entry",
+		"description": "Template for an entry in the RFC History table",
+		"body": [
+			"| RFC${1:NNNN} | ${2:Title} | ${3|Accepted,Rejected,Final|} | ${4:#123} |"
+		]
+	},
+	
 }

build.ps1

@@ -15,23 +15,26 @@ param(
     [switch]$GetPackageVersion,
     [switch]$SkipLinkCheck,
     [switch]$UseX64MakeAppx,
-    [switch]$UseCratesIO,
+    [switch]$UseCFS,
     [switch]$UpdateLockFile,
     [switch]$Audit,
     [switch]$UseCFSAuth,
     [switch]$Clean,
     [switch]$Verbose
 )
 
-$env:RUSTC_LOG=$null
-$env:RUSTFLAGS='-Dwarnings'
-$usingADO = ($null -ne $env:TF_BUILD)
-
 trap {
     Write-Error "An error occurred: $($_ | Out-String)"
     exit 1
 }
 
+$env:RUSTC_LOG=$null
+$env:RUSTFLAGS='-Dwarnings'
+$usingADO = ($null -ne $env:TF_BUILD)
+if ($usingADO -or $UseCFSAuth) {
+    $UseCFS = $true
+}
+
 if ($Verbose) {
     $env:RUSTC_LOG='rustc_codegen_ssa::back::link=info'
 }
@@ -171,6 +174,39 @@ if ($null -ne (Get-Command msrustup -CommandType Application -ErrorAction Ignore
 if ($null -ne $packageType) {
     $SkipBuild = $true
 } else {
+    if ($UseCFS) {
+        Write-Host "Using CFS for cargo source replacement"
+        ${env:CARGO_SOURCE_crates-io_REPLACE_WITH} = $null
+        $env:CARGO_REGISTRIES_CRATESIO_INDEX = $null
+
+        if ($UseCFSAuth) {
+            if ($null -eq (Get-Command 'az' -ErrorAction Ignore)) {
+                throw "Azure CLI not found"
+            }
+
+            if ($null -ne (Get-Command az -ErrorAction Ignore)) {
+                Write-Host "Getting token"
+                $accessToken = az account get-access-token --query accessToken --resource 499b84ac-1321-427f-aa17-267ca6975798 -o tsv
+                if ($LASTEXITCODE -ne 0) {
+                    Write-Warning "Failed to get access token, use 'az login' first, or use '-useCratesIO' to use crates.io.  Proceeding with anonymous access."
+                } else {
+                    $header = "Bearer $accessToken"
+                    $env:CARGO_REGISTRIES_POWERSHELL_TOKEN = $header
+                    $env:CARGO_REGISTRIES_POWERSHELL_CREDENTIAL_PROVIDER = 'cargo:token'
+                    $env:CARGO_REGISTRIES_POWERSHELL_INDEX = "sparse+https://pkgs.dev.azure.com/powershell/PowerShell/_packaging/powershell~force-auth/Cargo/index/"
+                }
+            }
+            else {
+                Write-Warning "Azure CLI not found, proceeding with anonymous access."
+            }
+        }
+    } else {
+        # this will override the config.toml
+        Write-Host "Setting CARGO_SOURCE_crates-io_REPLACE_WITH to 'crates-io'"
+        ${env:CARGO_SOURCE_crates-io_REPLACE_WITH} = 'CRATESIO'
+        $env:CARGO_REGISTRIES_CRATESIO_INDEX = 'sparse+https://index.crates.io/'
+    }
+
     ## Test if Rust is installed
     if (!$usingADO -and !(Get-Command 'cargo' -ErrorAction Ignore)) {
         Write-Verbose -Verbose "Rust not found, installing..."
@@ -229,7 +265,11 @@ if ($null -ne $packageType) {
     ## Test if tree-sitter is installed
     if ($null -eq (Get-Command tree-sitter -ErrorAction Ignore)) {
         Write-Verbose -Verbose "tree-sitter not found, installing..."
-        cargo install tree-sitter-cli --config .cargo/config.toml
+        if ($UseCFS) {
+            cargo install tree-sitter-cli --config .cargo/config.toml
+        } else {
+            cargo install tree-sitter-cli
+        }
         if ($LASTEXITCODE -ne 0) {
             throw "Failed to install tree-sitter-cli"
         }
@@ -290,39 +330,6 @@ if (!$SkipBuild) {
     }
     New-Item -ItemType Directory $target -ErrorAction Ignore > $null
 
-    if ($UseCratesIO) {
-        # this will override the config.toml
-        Write-Host "Setting CARGO_SOURCE_crates-io_REPLACE_WITH to 'crates-io'"
-        ${env:CARGO_SOURCE_crates-io_REPLACE_WITH} = 'CRATESIO'
-        $env:CARGO_REGISTRIES_CRATESIO_INDEX = 'sparse+https://index.crates.io/'
-    } else {
-        Write-Host "Using CFS for cargo source replacement"
-        ${env:CARGO_SOURCE_crates-io_REPLACE_WITH} = $null
-        $env:CARGO_REGISTRIES_CRATESIO_INDEX = $null
-
-        if ($UseCFSAuth) {
-            if ($null -eq (Get-Command 'az' -ErrorAction Ignore)) {
-                throw "Azure CLI not found"
-            }
-
-            if ($null -ne (Get-Command az -ErrorAction Ignore)) {
-                Write-Host "Getting token"
-                $accessToken = az account get-access-token --query accessToken --resource 499b84ac-1321-427f-aa17-267ca6975798 -o tsv
-                if ($LASTEXITCODE -ne 0) {
-                    Write-Warning "Failed to get access token, use 'az login' first, or use '-useCratesIO' to use crates.io.  Proceeding with anonymous access."
-                } else {
-                    $header = "Bearer $accessToken"
-                    $env:CARGO_REGISTRIES_POWERSHELL_TOKEN = $header
-                    $env:CARGO_REGISTRIES_POWERSHELL_CREDENTIAL_PROVIDER = 'cargo:token'
-                    $env:CARGO_REGISTRIES_POWERSHELL_INDEX = "sparse+https://pkgs.dev.azure.com/powershell/PowerShell/_packaging/powershell~force-auth/Cargo/index/"
-                }
-            }
-            else {
-                Write-Warning "Azure CLI not found, proceeding with anonymous access."
-            }
-        }
-    }
-
     # make sure dependencies are built first so clippy runs correctly
     $windows_projects = @("pal", "registry_lib", "registry", "reboot_pending", "wmi-adapter", "configurations/windows", 'extensions/appx')
     $macOS_projects = @("resources/brew")
@@ -380,7 +387,11 @@ if (!$SkipBuild) {
                 else {
                     if ($Audit) {
                         if ($null -eq (Get-Command cargo-audit -ErrorAction Ignore)) {
-                            cargo install cargo-audit --features=fix --config .cargo/config.toml
+                            if ($UseCFS) {
+                                cargo install cargo-audit --features=fix --config .cargo/config.toml
+                            } else {
+                                cargo install cargo-audit --features=fix
+                            }
                         }
 
                         cargo audit fix
@@ -413,7 +424,11 @@ if (!$SkipBuild) {
                     else {
                         if ($Audit) {
                             if ($null -eq (Get-Command cargo-audit -ErrorAction Ignore)) {
-                                cargo install cargo-audit --features=fix --config .cargo/config.toml
+                                if ($UseCFS) {
+                                    cargo install cargo-audit --features=fix --config .cargo/config.toml
+                                } else {
+                                    cargo install cargo-audit --features=fix
+                                }
                             }
 
                             cargo audit fix

docs/reference/schemas/config/functions/array.md

@@ -9,32 +9,31 @@ title:       array
 
 ## Synopsis
 
-Creates an array from the given elements (strings, numbers, arrays, or objects).
+Wraps a single value (string, number, array, or object) in an array.
 
 ## Syntax
 
 ```Syntax
-array(<element1>, <element2>, ...)
+array(<value>)
 ```
 
 ## Description
 
-The `array()` function creates an array from the provided arguments, allowing
-mixed data types within the same array. Unlike `createArray()` which requires
-all elements to be the same type, `array()` accepts any combination of strings,
-numbers, arrays, and objects as arguments.
+The `array()` function returns a new array containing the single input value.
+The value can be a string, number, array, or object. Use
+`createArray()` to construct arrays with multiple elements of the same type.
 
-This function is useful when you need to combine different types of data into a
-single collection, such as mixing configuration values, computed results, and
-structured metadata in deployment scenarios.
+This function is useful when a schema expects an array, but you only have a
+single value, or when you need to nest an existing array or object inside an
+outer array.
 
 ## Examples
 
-### Example 1 - Build a deployment plan
+### Example 1 - Wrap an existing array as a single element
 
-This example demonstrates combining different data types to create a comprehensive
-deployment configuration. The array contains an existing server list, a numeric
-batch size, and a configuration object with deployment strategy details.
+This example demonstrates wrapping an existing server list into a single array
+element, producing a nested array. This can be useful when a downstream schema
+expects an array of arrays.
 
 ```yaml
 # array.example.1.dsc.config.yaml
@@ -52,7 +51,7 @@ resources:
 - name: Deployment Plan
   type: Microsoft.DSC.Debug/Echo
   properties:
-    output: "[array(parameters('webServers'), parameters('batchSize'), createObject('strategy', 'blue-green'))]"
+    output: "[array(parameters('webServers'))]"
 ```
 
 ```bash
@@ -68,17 +67,14 @@ results:
       output:
       - - web01
         - web02
-      - 2
-      - strategy: blue-green
 messages: []
 hadErrors: false
 ```
 
-### Example 2 - Compose mixed telemetry payload parts
+### Example 2 - Wrap a single object for payloads
 
-This example shows how to construct a telemetry payload by combining a string
-identifier, structured metadata object, and numeric status code into a single
-array for logging or monitoring systems.
+This example shows how to wrap a structured metadata object into an array for
+logging or monitoring systems that expect arrays.
 
 ```yaml
 # array.example.2.dsc.config.yaml
@@ -92,7 +88,7 @@ resources:
   type: Microsoft.DSC.Debug/Echo
   properties:
     output:
-      payload: "[array(parameters('correlationId'), createObject('severity', 'info'), 200)]"
+      payload: "[array(createObject('severity', 'info'))]"
 ```
 
 ```bash
@@ -107,18 +103,15 @@ results:
     actualState:
       output:
         payload:
-        - ABC123
         - severity: info
-        - 200
 messages: []
 hadErrors: false
 ```
 
-### Example 3 - Combine generated and literal collections
+### Example 3 - Wrap generated collections
 
-This example demonstrates nesting arrays and objects within a parent array,
-showing how `array()` can combine results from other DSC functions like
-`createArray()` and `createObject()` with literal values.
+This example demonstrates wrapping a generated collection (like one from
+`createArray()` or `createObject()`) into an outer array.
 
 ```yaml
 # array.example.3.dsc.config.yaml
@@ -128,7 +121,8 @@ resources:
   type: Microsoft.DSC.Debug/Echo
   properties:
     output:
-      combined: "[array(createArray('a','b'), array(1,2), createObject('k','v'))]"
+      combinedArray: "[array(createArray('a','b'))]"
+      combinedObject: "[array(createObject('k','v'))]"
 ```
 
 ```bash
@@ -142,31 +136,31 @@ results:
   result:
     actualState:
       output:
-        combined:
+        combinedArray:
         - - a
           - b
-        - - 1
-          - 2
+        combinedObject:
         - k: v
 messages: []
 hadErrors: false
 ```
 
 ## Parameters
 
-### element1, element2, ...
+### value
 
-The elements to include in the array.
+The single value to wrap in the array.
 
 ```yaml
 Type:         string, number, array, or object
 Required:     false
-Multiplicity: 0 or more
+MinimumCount: 1
+MaximumCount: 1
 ```
 
-Each element provided as an argument will be added to the resulting array in the
-order specified. All elements must be one of the four accepted types: string,
-number (integer), array, or object. Boolean and null values are not supported.
+The provided value will be wrapped into the resulting array. The value must be
+one of the four accepted types: string, number (integer), array, or object.
+Boolean and null values are not supported.
 
 ## Output
 

docs/reference/schemas/config/functions/first.md

@@ -109,7 +109,8 @@ hadErrors: false
 ### Example 3 - Chain with array construction
 
 This example shows how `first()` can be combined with `array()` to get the
-first element from a dynamically constructed array containing mixed data types.
+first element from a dynamically constructed array, by wrapping a single
+generated collection.
 
 ```yaml
 # first.example.3.dsc.config.yaml
@@ -119,7 +120,7 @@ resources:
   type: Microsoft.DSC.Debug/Echo
   properties:
     output:
-      firstMixed: "[first(array(createArray('a','b'), createObject('k','v')))]"
+      firstMixed: "[first(array(createArray('a','b')))]"
 ```
 
 ```bash
@@ -133,9 +134,7 @@ results:
   result:
     actualState:
       output:
-        firstMixed:
-        - a
-        - b
+  firstMixed: a
 messages: []
 hadErrors: false
 ```