Merge branch 'main' into issue_121

.gitignore

@@ -2,3 +2,11 @@ Cargo.lock
 target
 bin/
 .DS_Store
+
+# Node.js generated files for tree-sitter
+build/
+node_modules/
+tree-sitter-dscexpression/bindings/
+tree-sitter-dscexpression/src/
+tree-sitter-dscexpression/parser.*
+tree-sitter-dscexpression/binding.gyp

.vscode/settings.json

@@ -6,10 +6,10 @@
         "./ntstatuserror/Cargo.toml",
         "./ntuserinfo/Cargo.toml",
         "./osinfo/Cargo.toml",
-        "./pal/Cargo.toml",
         "./registry/Cargo.toml",
         "./tools/test_group_resource/Cargo.toml",
         "./tools/dsctest/Cargo.toml",
+        "./tree-sitter-dscexpression/Cargo.toml",
         "./y2j/Cargo.toml"
     ],
     "rust-analyzer.showUnlinkedFileNotification": true,

CHANGELOG.md

@@ -2,11 +2,13 @@
 title: "Desired State Configuration changelog"
 description: >-
   A log of the changes for releases of DSCv3.
-ms.date: 09/27/2023
+ms.date: 10/05/2023
 ---
 
 # Changelog
 
+<!-- markdownlint-disable-file MD033 -->
+
 All notable changes to DSCv3 are documented in this file. The format is based on
 [Keep a Changelog][m1], and DSCv3 adheres to [Semantic Versioning][m2].
 
@@ -24,6 +26,106 @@ changes since the last release, see the [diff on GitHub][unreleased].
 
 <!-- Add entries between releases under the appropriate section heading here  -->
 
+### Changed
+
+- Replaced the `_ensure` well-known property with the boolean [_exist][21] property. This improves
+  the semantics for users and simplifies implementation for resources, replacing the string enum
+  values `Present` and `Absent` with `true` and `false` respectively.
+
+  <details><summary>Related work items</summary>
+
+  - Issues: [#202][#202]
+  - PRs: [#206][#206]
+
+  </details>
+
+- Updated the `Microsoft.Windows/Registry` resource to use the `_exist` property instead of
+  `_ensure` and updated the output to be idiomatic for a DSC Resource.
+
+  <details><summary>Related work items</summary>
+
+  - Issues: [#162][#162]
+  - PRs: [#206][#206]
+
+  </details>
+
+- When a user presses the <kbd>Ctrl</kbd>+<kbd>C</kbd> key combination, DSC now recursively
+  terminates all child processes before exiting. This helps prevent dangling processes that were
+  previously unhandled by the interrupt event.
+
+  <details><summary>Related work items</summary>
+
+  - PRs: [#213][#213]
+
+  </details>
+
+### Added
+
+- Added the [--input][22] and [--input-file][23] global options to the root `dsc` command. Now, you
+  can pass input to DSC from a variable or file instead of piping from stdin.
+
+  <details><summary>Related work items</summary>
+
+  - Issues: [#130][#130]
+  - PRs: [#217][#217]
+
+  </details>
+
+- Added the `arg` value as an option for defining how a command-based DSC Resource expects to
+  receive input. This enables resource authors to define resources that handle DSC passing the
+  instance JSON as an argument.
+
+  <details><summary>Related work items</summary>
+
+  - PRs: [#213][#213]
+
+  </details>
+
+- Added the new [completer][24] command enables users to add shell completions for DSC to their
+  shell. The command supports completions for Bash, Elvish, fish, PowerShell, and ZSH.
+
+  <details><summary>Related work items</summary>
+
+  - Issues: [#186][#186]
+  - PRs: [#216][#216]
+
+  </details>
+
+- DSC now emits tace logging to the stderr stream. This can make it easier to understand what DSC
+  is doing. This doesn't affect the data output. In this release, there's no way to opt out of the
+  logging.
+
+  <details><summary>Related work items</summary>
+
+  - Issues:
+    - [#107][#107]
+    - [#158][#158]
+  - PRs: [#211][#211]
+
+  </details>
+
+### Fixed
+
+- The `--format` option now works as users expect when the output is redirected or saved to a
+  variable. Before this fix, DSC always returned JSON output, even when the user wanted to save
+  the output as YAML. With this fix, the specified format is respected.
+
+  <details><summary>Related work items</summary>
+
+  - PRs: [#215][#215]
+
+  </details>
+
+- The `DSC/PowerShellGroup` resource now correctly returns the _labels_ for enumerations instead of
+  their integer value, making it easier to understand and compare results.
+
+  <details><summary>Related work items</summary>
+
+  - Issues: [#159][#159]
+  - PRs: [#208][#208]
+
+  </details>
+
 ## [v3.0.0-alpha.3][release-v3.0.0-alpha.3] - 2023-09-26
 
 This section includes a summary of changes for the `alpha.3` release. For the full list of changes
@@ -291,11 +393,22 @@ For the full list of changes in this release, see the [diff on GitHub][compare-v
 [19]: docs/reference/schemas/resource/manifest/set.md#input
 [20]: docs/reference/schemas/resource/manifest/test.md#input
 
+<!-- alpha.4 links -->
+[21]: docs/reference/schemas/resource/properties/exist.md
+[22]: docs/reference/cli/dsc.md#-i---input
+[23]: docs/reference/cli/dsc.md#-p---input-file
+[24]: docs/reference/cli/completer/command.md
+
 <!-- Issue and PR links -->
+[#107]: https://github.com/PowerShell/DSC/issues/107
 [#127]: https://github.com/PowerShell/DSC/issues/127
+[#130]: https://github.com/PowerShell/DSC/issues/130
 [#133]: https://github.com/PowerShell/DSC/issues/133
 [#150]: https://github.com/PowerShell/DSC/issues/150
 [#156]: https://github.com/PowerShell/DSC/issues/156
+[#158]: https://github.com/PowerShell/DSC/issues/158
+[#159]: https://github.com/PowerShell/DSC/issues/159
+[#162]: https://github.com/PowerShell/DSC/issues/162
 [#163]: https://github.com/PowerShell/DSC/issues/163
 [#168]: https://github.com/PowerShell/DSC/issues/168
 [#171]: https://github.com/PowerShell/DSC/issues/171
@@ -306,9 +419,18 @@ For the full list of changes in this release, see the [diff on GitHub][compare-v
 [#177]: https://github.com/PowerShell/DSC/issues/177
 [#181]: https://github.com/PowerShell/DSC/issues/181
 [#182]: https://github.com/PowerShell/DSC/issues/182
+[#186]: https://github.com/PowerShell/DSC/issues/186
 [#197]: https://github.com/PowerShell/DSC/issues/197
 [#198]: https://github.com/PowerShell/DSC/issues/198
 [#199]: https://github.com/PowerShell/DSC/issues/199
+[#202]: https://github.com/PowerShell/DSC/issues/202
+[#206]: https://github.com/PowerShell/DSC/issues/206
+[#208]: https://github.com/PowerShell/DSC/issues/208
+[#211]: https://github.com/PowerShell/DSC/issues/211
+[#213]: https://github.com/PowerShell/DSC/issues/213
+[#215]: https://github.com/PowerShell/DSC/issues/215
+[#216]: https://github.com/PowerShell/DSC/issues/216
+[#217]: https://github.com/PowerShell/DSC/issues/217
 [#45]:  https://github.com/PowerShell/DSC/issues/45
 [#73]:  https://github.com/PowerShell/DSC/issues/73
 [#98]:  https://github.com/PowerShell/DSC/issues/98

build.ps1

@@ -92,8 +92,21 @@ New-Item -ItemType Directory $target > $null
 
 # make sure dependencies are built first so clippy runs correctly
 $windows_projects = @("pal", "ntreg", "ntstatuserror", "ntuserinfo", "registry")
-$projects = @("dsc_lib", "dsc", "osinfo", "process", "tools/test_group_resource", "y2j", "powershellgroup", "tools/dsctest")
+$projects = @(
+    "dsc",
+    "dsc_lib",
+    "file_lib",
+    "osinfo",
+    "powershellgroup",
+    "process",
+    "tools/dsctest",
+    "tools/test_group_resource",
+    "tree-sitter-dscexpression",
+    "y2j"
+)
 $pedantic_unclean_projects = @("ntreg")
+$clippy_unclean_projects = @("tree-sitter-dscexpression")
+$skip_test_projects_on_windows = @("tree-sitter-dscexpression")
 
 if ($IsWindows) {
     $projects += $windows_projects
@@ -106,10 +119,17 @@ foreach ($project in $projects) {
     try {
         Push-Location "$PSScriptRoot/$project" -ErrorAction Stop
 
+        if ($project -eq 'tree-sitter-dscexpression') {
+            ./build.ps1
+        }
+
         if (Test-Path "./Cargo.toml")
         {
             if ($Clippy) {
-                if ($pedantic_unclean_projects -contains $project) {
+                if ($clippy_unclean_projects -contains $project) {
+                    Write-Verbose -Verbose "Skipping clippy for $project"
+                }
+                elseif ($pedantic_unclean_projects -contains $project) {
                     Write-Verbose -Verbose "Running clippy for $project"
                     cargo clippy @flags -- -Dwarnings
                 }
@@ -198,23 +218,21 @@ if ($Test) {
         Install-Module Pester -WarningAction Ignore
     }
 
-    "For debug - env:PATH is:"
-    $env:PATH
-
     foreach ($project in $projects) {
-        ## Build format_json
+        if ($IsWindows -and $skip_test_projects_on_windows -contains $project) {
+            Write-Verbose -Verbose "Skipping test for $project on Windows"
+            continue
+        }
+
         Write-Host -ForegroundColor Cyan "Testing $project ..."
         try {
             Push-Location "$PSScriptRoot/$project"
             if (Test-Path "./Cargo.toml")
             {
-                if (Test-Path "./Cargo.toml")
-                {
-                    cargo test
+                cargo test
 
-                    if ($LASTEXITCODE -ne 0) {
-                        $failed = $true
-                    }
+                if ($LASTEXITCODE -ne 0) {
+                    $failed = $true
                 }
             }
         } finally {

docs/reference/cli/completer/command.md

@@ -0,0 +1,108 @@
+---
+description: Command line reference for the 'dsc completer' command
+ms.date:     10/05/2023
+ms.topic:    reference
+title:       dsc schema
+---
+
+# dsc schema
+
+## Synopsis
+
+Generates a shell completion script.
+
+## Syntax
+
+```sh
+dsc completer [Options] <SHELL>
+```
+
+## Description
+
+The `completer` command returns a shell script that, when executed, registers completions for the
+given shell. DSC can generate completion scripts for the following shells:
+
+- [Bourne Again SHell (BASH)][01]
+- [Elvish][02]
+- [Friendly Interactive SHell (fish)][03]
+- [PowerShell][04]
+- [Z SHell (ZSH)][05]
+
+The output for this command is the script itself. To register completions for DSC, execute the
+script.
+
+> [!WARNING]
+> Always review scripts before executing them, especially in an elevated execution context.
+
+## Examples
+
+### Example 1 - Register completions for Bash
+
+```sh
+completer=~/dsc_completion.bash
+# Export the completion script
+dsc completer bash > $completer
+# Review the completion script
+cat $completer
+# Add the completion script to your profile
+echo "source $completer" >> ~/.bashrc
+# Execute the completion script to register completions for this session
+source $completer
+```
+
+### Example 2 - Register completions for PowerShell
+
+```powershell
+$Completer = '~/dsc_completion.ps1'
+# Export the completion script
+dsc completer powershell | Out-File $Completer
+# Review the completion script
+Get-Content $completer
+# Add the completion script to your profile
+Add-Content -Path $PROFILE ". $Completer"
+# Execute the completion script to register completions for this session
+. $Completer
+```
+
+## Arguments
+
+### SHELL
+
+This argument is mandatory for the `completer` command. The value for this option determines which
+shell the application returns a completion script for:
+
+- `bash` - [Bourne Again SHell (BASH)][01]
+- `elvish` - [Elvish][02]
+- `fish` - [Friendly Interactive SHell (fish)][03]
+- `powershell` - [PowerShell][04]
+- `zsh` - [Z SHell (ZSH)][05]
+
+```yaml
+Type:        String
+Mandatory:   true
+ValidValues: [
+               bash,
+               elvish,
+               fish,
+               powershell,
+               zsh,
+             ]
+```
+
+## Options
+
+### -h, --help
+
+Displays the help for the current command or subcommand. When you specify this option, the
+application ignores all options and arguments after this one.
+
+```yaml
+Type:      Boolean
+Mandatory: false
+```
+
+[01]: https://www.gnu.org/software/bash/
+[02]: https://elv.sh/
+[03]: https://fishshell.com/
+[04]: https://learn.microsoft.com/powershell/scripting/overview
+[05]: https://zsh.sourceforge.io/