Merge branch 'implement-powershell-discover' of https://github.com/Gijsreyn/operation-methods into implement-powershell-discover

Author: Gijsreyn

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'
 }
@@ -177,6 +180,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..."
@@ -235,7 +271,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"
         }
@@ -296,39 +336,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", "extensions/powershell")
     $macOS_projects = @("resources/brew", "extensions/powershell")
@@ -386,7 +393,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
@@ -419,7 +430,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
 ```

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

@@ -94,7 +94,7 @@ resources:
   type: Microsoft.DSC.Debug/Echo
   properties:
     output:
-      hasFeature: "[indexOf(array(createObject('name','Preview'), createObject('name','Beta')), createObject('name','Beta'))]"
+      hasFeature: "[indexOf(array(createObject('name','Beta')), createObject('name','Beta'))]"
 ```
 
 ```bash
@@ -108,7 +108,7 @@ results:
   result:
     actualState:
       output:
-        hasFeature: 1
+        hasFeature: 0
 messages: []
 hadErrors: false
 ```

docs/reference/schemas/metadata/Microsoft.DSC/properties.md

@@ -13,7 +13,19 @@ Metadata properties used and returned by DSC for configuration and resource oper
 
 ## Description
 
-Blah
+The `Microsoft.DSC` metadata object captures execution details that DSC adds to
+command output and, when applicable, to resource results. It describes what
+operation ran, when it started and finished, how long it took, the security
+context DSC ran under, and the DSC version that produced the output. These
+properties are informational and help with diagnostics, auditing, and tooling.
+
+Not every property is present for every operation. For example, `executionType`
+is only meaningful for `Set` (and is `WhatIf` when you invoke DSC with
+`--whatIf`), while `operation` is always provided. Timestamps use RFC 3339
+`date-time` format, and durations use the ISO 8601 `duration` format.
+
+Consumers should tolerate additional, future metadata fields. Producers should
+preserve unknown metadata they do not interpret.
 
 ## Properties