Added PSRule getting started walkthrough #771 (#832)

BernieWhite · web-flow · commit f371033a62b8 · 2022-08-28T00:18:19.000+10:00
diff --git a/.vscode/settings.json b/.vscode/settings.json
@@ -3,13 +3,23 @@
         "node_modules/": true
     },
     "search.exclude": {
-        "out": true
+        "out/": true,
+        "node_modules/": true
     },
     "files.associations": {
         "**/.azure-pipelines/*.yaml": "azure-pipelines",
         "**/.azure-pipelines/jobs/*.yaml": "azure-pipelines"
     },
+    "json.schemas": [
+        {
+            "url": ".vscode/walkthrough.schema.json",
+            "fileMatch": [
+                "**/media/walkthroughs/**/snippets.json"
+            ]
+        }
+    ],
     "editor.insertSpaces": true,
+    "files.insertFinalNewline": true,
     "editor.tabSize": 4,
     "[yaml]": {
         "editor.tabSize": 2
@@ -19,7 +29,7 @@
     },
     "[json]": {
         "editor.formatOnSave": true,
-        "editor.defaultFormatter": "esbenp.prettier-vscode"
+        "editor.defaultFormatter": "vscode.json-language-features"
     },
     "[jsonc]": {
         "editor.formatOnSave": true,
diff --git a/.vscode/walkthrough.schema.json b/.vscode/walkthrough.schema.json
@@ -0,0 +1,37 @@
+{
+    "$schema": "https://json-schema.org/draft-07/schema#",
+    "type": "array",
+    "items": {
+        "$ref": "#/definitions/snippet"
+    },
+    "definitions": {
+        "snippet": {
+            "type": "object",
+            "properties": {
+                "name": {
+                    "type": "string"
+                },
+                "snippet": {
+                    "type": "array",
+                    "items": {
+                        "type": "string"
+                    }
+                }
+            },
+            "additionalProperties": false,
+            "required": [
+                "name",
+                "snippet"
+            ],
+            "defaultSnippets": [
+                {
+                    "label": "New snippet",
+                    "body": {
+                        "name": "",
+                        "snippet": ""
+                    }
+                }
+            ]
+        }
+    }
+}
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -12,10 +12,26 @@ This extension is available in two release channels for Visual Studio Code from
   - Aligned to versioning of PSRule.
 Continue reading to see the changes included in the latest version.
 
+**Experimental features**:
+
+- CodeLens to create or edit documentation.
+  - Link from rules allows markdown documentation to be created or edited.
+  - When existing markdown documentation exists, file is opened in editor.
+  - When documentation for a rule does not exist, a new file is created from a snippet.
+  - Added settings to configure the location for storing documentation,
+    and the snippet used to create documentation.
+- Get started with PSRule walkthrough.
+  - Steps cover basic PSRule configuration and documentation.
+
 ## Unreleased
 
 What's changed since v2.3.0:
 
+- General improvements:
+  - **Experimental:** Added a walkthrough for getting started with PSRule by @BernieWhite.
+    [#771](https://github.com/microsoft/PSRule-vscode/issues/771)
+    - Added steps for basic configuration and documentation.
+    - To use try this feature, install the preview channel with experimental features enabled.
 - Engineering:
   - Updated PSRule schema files.
     [#812](https://github.com/microsoft/PSRule-vscode/pull/812)
@@ -62,7 +78,7 @@ What's changed since v2.1.0:
 What's changed since v2.0.0:
 
 - New features:
-  - **Experimental:** CodeLens provides links to open or create rule documentation.
+  - **Experimental:** CodeLens provides links to open or create rule documentation by @BernieWhite.
     [#227](https://github.com/microsoft/PSRule-vscode/issues/227)
     - Link from rules allows markdown documentation to be created or edited.
     - When existing markdown documentation exists, file is opened in editor.
diff --git a/README.md b/README.md
@@ -153,6 +153,4 @@ This project is [licensed under the MIT License][license].
 [contribution guide]: https://github.com/Microsoft/PSRule-vscode/blob/main/CONTRIBUTING.md
 [change log]: https://github.com/Microsoft/PSRule-vscode/blob/main/CHANGELOG.md
 [license]: https://github.com/Microsoft/PSRule-vscode/blob/main/LICENSE
-[chat]: https://gitter.im/PSRule/community?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge
-[chat-badge]: https://img.shields.io/static/v1.svg?label=chat&message=on%20gitter&color=informational&logo=gitter
-[ps-rule.yaml]: https://microsoft.github.io/PSRule/concepts/PSRule/en-US/about_PSRule_Options.html
+[ps-rule.yaml]: https://aka.ms/ps-rule/options
diff --git a/media/icon256.png b/media/icon256.png
diff --git a/media/walkthroughs/getStarted/01_configureOptions.md b/media/walkthroughs/getStarted/01_configureOptions.md
@@ -0,0 +1,31 @@
+# Configure an options file
+
+- First, type `requires` and press Tab or Enter to complete the suggestion.
+- Continue typing to replace `Module` with `PSRule` and press Tab or Enter to move to the version constraint.
+- Replace `'>=1.0.0'` with the minimum version of PSRule you want to use, such as `'>=2.3.2'`.
+
+## Configure additional modules
+
+Additional modules can be added to the options file.
+For example:
+
+[Copy snippet](command:PSRule.walkthroughCopySnippet?%7B%22snippet%22%3A%2201_requiresModules%22%7D)
+
+```yaml
+requires:
+  PSRule: '>=2.3.2'
+  PSRule.Rules.Azure: '>=1.18.1'
+```
+
+### Configure other options
+
+Rules often have additional configuration options that can be set.
+For example, the `PSRule.Rules.Azure` module has the following options:
+
+[Copy snippet](command:PSRule.walkthroughCopySnippet?%7B%22snippet%22%3A%2201_configureAzure%22%7D)
+
+```yaml
+configuration:
+  AZURE_PARAMETER_FILE_EXPANSION: true
+  AZURE_BICEP_FILE_EXPANSION: true
+```
diff --git a/media/walkthroughs/getStarted/02_configureSettings.md b/media/walkthroughs/getStarted/02_configureSettings.md
diff --git a/media/walkthroughs/getStarted/03_learnMore.md b/media/walkthroughs/getStarted/03_learnMore.md
diff --git a/media/walkthroughs/getStarted/snippets.json b/media/walkthroughs/getStarted/snippets.json
@@ -0,0 +1,18 @@
+[
+    {
+        "name": "01_requiresModules",
+        "snippet": [
+            "requires:",
+            "  PSRule: '>=2.3.2'",
+            "  PSRule.Rules.Azure: '>=1.18.1'"
+        ]
+    },
+    {
+        "name": "01_configureAzure",
+        "snippet": [
+            "configuration:",
+            "  AZURE_PARAMETER_FILE_EXPANSION: true",
+            "  AZURE_BICEP_FILE_EXPANSION: true"
+        ]
+    }
+]
diff --git a/package.json b/package.json
@@ -25,7 +25,7 @@
         "color": "#0072c6",
         "theme": "dark"
     },
-    "icon": "images/icon256.png",
+    "icon": "media/icon256.png",
     "repository": {
         "type": "git",
         "url": "https://github.com/Microsoft/PSRule-vscode.git"
@@ -38,12 +38,18 @@
     "activationEvents": [
         "onLanguage:powershell",
         "workspaceContains:/ps-rule.yaml",
+        "workspaceContains:**/ps-rule.yaml",
         "workspaceContains:**/*.Rule.yaml",
         "workspaceContains:**/*.Rule.yml",
         "workspaceContains:**/*.Rule.json",
         "workspaceContains:**/*.Rule.jsonc",
         "workspaceContains:**/*.Rule.ps1",
-        "onCommand:workbench.action.tasks.runTask"
+        "onCommand:workbench.action.tasks.runTask",
+        "onCommand:PSRule.createOrEditDocumentation",
+        "onCommand:PSRule.openOptionsFile",
+        "onCommand:PSRule.createOptionsFile",
+        "onCommand:PSRule.configureSettings",
+        "onCommand:PSRule.walkthroughCopySnippet"
     ],
     "main": "./out/dist/main.js",
     "capabilities": {
@@ -60,10 +66,27 @@
                 "shortTitle": "Edit documentation",
                 "category": "PSRule"
             },
+            {
+                "command": "PSRule.openOptionsFile",
+                "title": "Open options file",
+                "category": "PSRule"
+            },
             {
                 "command": "PSRule.createOptionsFile",
                 "title": "Create options file",
                 "category": "PSRule"
+            },
+            {
+                "command": "PSRule.configureSettings",
+                "title": "Configure settings",
+                "category": "PSRule"
+            },
+            {
+                "$comment": "Only used by walkthrough.",
+                "command": "PSRule.walkthroughCopySnippet",
+                "title": "Copy walkthrough snippet",
+                "enablement": "false",
+                "category": "PSRule"
             }
         ],
         "configuration": [
@@ -310,6 +333,47 @@
                     }
                 ]
             }
+        ],
+        "walkthroughs": [
+            {
+                "id": "PSRule.getStarted",
+                "title": "Get Started with PSRule",
+                "description": "Learn about and start using PSRule with Visual Studio Code.",
+                "when": "config.PSRule.experimental.enabled",
+                "steps": [
+                    {
+                        "id": "configureOptions",
+                        "title": "Configure an options file",
+                        "description": "The options file **ps-rule.yaml** is used to initialize a workspace and configure features of PSRule.\n[Open an options file](command:PSRule.openOptionsFile)\n[Create an options file](command:PSRule.createOptionsFile)\nTip: [Close the side bar for more space](command:workbench.action.closeSidebar)",
+                        "media": {
+                            "markdown": "media/walkthroughs/getStarted/01_configureOptions.md"
+                        },
+                        "completionEvents": [
+                            "onCommand:PSRule.openOptionsFile",
+                            "onCommand:PSRule.createOptionsFile"
+                        ]
+                    },
+                    {
+                        "id": "configureSettings",
+                        "title": "Configure settings",
+                        "description": "In addition to **ps-rule.yaml**, some settings that affect how PSRule runs within Visual Studio Code can be configured per user or per workspace.\n[Configure settings](command:PSRule.configureSettings)\nTip: __You can sync some of these settings across devices.__",
+                        "media": {
+                            "markdown": "media/walkthroughs/getStarted/02_configureSettings.md"
+                        },
+                        "completionEvents": [
+                            "onCommand:PSRule.configureSettings"
+                        ]
+                    },
+                    {
+                        "id": "learnMore",
+                        "title": "Learn more",
+                        "description": "Check out our [PSRule documentation](https://aka.ms/ps-rule) to learn more about features and customization.",
+                        "media": {
+                            "markdown": "media/walkthroughs/getStarted/03_learnMore.md"
+                        }
+                    }
+                ]
+            }
         ]
     },
     "scripts": {
diff --git a/schemas/PSRule-options.schema.json b/schemas/PSRule-options.schema.json
@@ -811,7 +811,7 @@
                 {
                     "label": "Version constraint",
                     "body": {
-                        "${1:Module}": "${2:'>=1.0.0'}"
+                        "${1:Module}": "'>=${2:1.0.0}'"
                     }
                 }
             ]
diff --git a/src/commands/configureSettings.ts b/src/commands/configureSettings.ts
@@ -0,0 +1,12 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
+
+import { commands } from 'vscode';
+import { logger } from '../logger';
+import { ext } from '../extension';
+
+export async function configureSettings(): Promise<void> {
+    const extensionId = (await ext.info).id
+    logger.verbose(`Opening settings for ${extensionId}`);
+    commands.executeCommand('workbench.action.openSettings', `@ext:${extensionId}`);
+}
diff --git a/src/commands/openOptionsFile.ts b/src/commands/openOptionsFile.ts
@@ -0,0 +1,45 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
+
+import * as fse from 'fs-extra';
+import { RelativePattern, TextDocument, Uri, window, workspace, WorkspaceFolder } from 'vscode';
+import { logger } from '../logger';
+import { getActiveOrFirstWorkspace } from '../utils';
+
+export async function openOptionsFile(path: string | undefined): Promise<void> {
+    const optionFilePath = await getOptionFile(path);
+    if (optionFilePath === '' || optionFilePath === undefined) return;
+
+    const uri = Uri.file(optionFilePath);
+    logger.verbose(`Using options path ${uri.fsPath}`);
+    const exists = await fse.pathExists(uri.fsPath);
+    if (!exists)
+        return;
+
+    const document: TextDocument = await workspace.openTextDocument(uri);
+    await window.showTextDocument(document);
+}
+
+async function getOptionFile(path: string | undefined): Promise<string | undefined> {
+    // Require an active workspace.
+    const active: WorkspaceFolder | undefined = getActiveOrFirstWorkspace();
+    if (!active) return Promise.resolve(undefined);
+    if (!(path === '' || path === undefined)) return Promise.resolve(path);
+
+    const workspaceUri: Uri = active.uri;
+    const searchPattern = new RelativePattern(workspaceUri, '**/ps-rule.yaml');
+    return new Promise<string | undefined>((resolve) => {
+        workspace.findFiles(searchPattern).then(files => {
+            if (files === undefined || files.length === 0)
+                resolve(undefined);
+
+            const names: string[] = [];
+            files.forEach(item => {
+                names.push(item.path);
+            });
+            window.showQuickPick(names, { title: 'Options file' }).then(item => {
+                return resolve(item);
+            });
+        });
+    });
+}
diff --git a/src/commands/walkthroughCopySnippet.ts b/src/commands/walkthroughCopySnippet.ts
@@ -0,0 +1,40 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
+
+import * as path from 'path';
+import * as fse from 'fs-extra';
+import { env } from 'vscode';
+import { logger } from '../logger';
+import { ext } from '../extension';
+
+export async function walkthroughCopySnippet(name: string | undefined): Promise<void> {
+    // Clear the clipboard and load snippets.
+    env.clipboard.writeText('');
+    const snippets = load('getStarted');
+
+    // Find the correct snippet and copy it to the clipboard.
+    snippets.then((value): void => {
+        value.forEach((element: { name: string; snippet: string[] | undefined; }) => {
+            if (name === element.name && element.snippet) {
+                logger.verbose(`Copying snippet for ${name} to the clipboard.`);
+                const text = element.snippet.join('\n');
+                env.clipboard.writeText(text);
+                return;
+            }
+        });
+    });
+}
+
+/**
+ * Load a snippet for a walkthrough.
+ * @param name The name of the walkthrough.
+ * @returns A list of named snippets for the walkthrough.
+ */
+async function load(name: string): Promise<any> {
+    const info = await ext.info;
+    const helpFile = info ? path.join(info.path, `media/walkthroughs/${name}/snippets.json`) : undefined;
+    if (helpFile && (await fse.pathExists(helpFile))) {
+        return await fse.readJson(helpFile, { encoding: 'utf-8' });
+    }
+    return Promise.resolve(undefined);
+}
diff --git a/src/configuration.ts b/src/configuration.ts
@@ -24,6 +24,10 @@ export interface ISetting {
     documentationPath: string | undefined;
     documentationLocalePath: string;
     executionNotProcessedWarning: boolean;
+
+    /**
+     * Determines if experimental features are enabled.
+     */
     experimentalEnabled: boolean;
     outputAs: OutputAs;
     notificationsShowChannelUpgrade: boolean;
diff --git a/src/extension.ts b/src/extension.ts
diff --git a/src/tasks.ts b/src/tasks.ts
