Getting started walkthrough updates #1099 #1093 (#1100)

CHANGELOG.md

@@ -30,11 +30,15 @@ Continue reading to see the changes included in the latest version.
 What's changed since v2.8.0:
 
 - New features:
+  - Getting started walkthrough in Visual Studio Code is now generally available by @BernieWhite
+    [#1099](https://github.com/microsoft/PSRule-vscode/issues/1099)
   - Added configuration to tune logging for excluded or suppressed rules by @BernieWhite.
     [#1068](https://github.com/microsoft/PSRule-vscode/issues/1068)
     - Use these options to reduce output noise when testing in Visual Studio Code.
     - The `PSRule.execution.ruleExcluded` setting configures excluded rules.
     - The `PSRule.execution.ruleSuppressed` setting configures suppressed rules.
+  - Add running analysis to getting started walkthrough by @BernieWhite.
+    [#1093](https://github.com/microsoft/PSRule-vscode/issues/1093)
 - Engineering:
   - Updated PSRule schema files.
     [#1092](https://github.com/microsoft/PSRule-vscode/pull/1092)

media/walkthroughs/getStarted/01_configureOptions.md

@@ -26,6 +26,9 @@ For example, the `PSRule.Rules.Azure` module has the following options:
 
 ```yaml
 configuration:
+  # Enable expansion of Azure Template parameter files.
   AZURE_PARAMETER_FILE_EXPANSION: true
+
+  # Enable expansion of Azure Bicep files.
   AZURE_BICEP_FILE_EXPANSION: true
 ```

media/walkthroughs/getStarted/03_runTasks.md

@@ -0,0 +1,17 @@
+# Run analysis
+
+Run tasks within Visual Studio Code to analyze the Infrastructure as Code within your workspace.
+
+## Run tasks
+
+- Open the **Command Palette** (Ctrl+Shift+P) and select **Tasks: Run Task**.
+- Choose or type **PSRule**.
+- Then select **PSRule: Run analysis**.
+- Optionally, select **PSRule** to scan the task output to collect error or warnings.
+
+![Run tasks](03_runTasks.svg)
+
+## Configuring tasks
+
+Additional configuration options can be set on the **PSRule: Run analysis** task.
+Such as the input path, modules, baseline, and additional environment variables by configuring the `tasks.json`.

media/walkthroughs/getStarted/snippets.json

@@ -11,7 +11,10 @@
     "name": "01_configureAzure",
     "snippet": [
       "configuration:",
+      "  # Enable expansion of Azure Template parameter files.",
       "  AZURE_PARAMETER_FILE_EXPANSION: true",
+      "",
+      "  # Enable expansion of Azure Bicep files.",
       "  AZURE_BICEP_FILE_EXPANSION: true"
     ]
   }

package.json

@@ -83,6 +83,17 @@
         "title": "Copy walkthrough snippet",
         "enablement": "false",
         "category": "PSRule"
+      },
+      {
+        "command": "PSRule.runAnalysisTask",
+        "title": "Run analysis",
+        "category": "PSRule"
+      },
+      {
+        "command": "PSRule.showTasks",
+        "title": "Show tasks",
+        "enablement": "false",
+        "category": "PSRule"
       }
     ],
     "configuration": [
@@ -373,7 +384,6 @@
         "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",
@@ -398,14 +408,32 @@
               "onCommand:PSRule.configureSettings"
             ]
           },
+          {
+            "id": "runTasks",
+            "title": "Run analysis",
+            "description": "Tasks can be used to run analysis on files within your current Visual Studio Code workspace.\n[Show tasks](command:PSRule.showTasks)\nOr you can run the [analysis](command:PSRule.runAnalysisTask) task directly from the command palette.",
+            "media": {
+              "markdown": "media/walkthroughs/getStarted/03_runTasks.md"
+            },
+            "completionEvents": [
+              "command:PSRule.runAnalysisTask",
+              "command:PSRule.showTasks"
+            ]
+          },
           {
             "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"
+              "markdown": "media/walkthroughs/getStarted/04_learnMore.md"
             }
           }
+        ],
+        "featuredFor": [
+          "**/ps-rule.yaml",
+          "**/*.Rule.yaml",
+          "**/*.Rule.ps1",
+          "**/*.Rule.jsonc"
         ]
       }
     ]

snippets/options.json

@@ -1,28 +1,28 @@
 {
-    "PSRule options": {
-        "prefix": "ps-rule-options",
-        "description": "Default PSRule options file",
-        "body": [
-            "#",
-            "# PSRule configuration",
-            "#",
-            "",
-            "# Please see the documentation for all configuration options:",
-            "# https://aka.ms/ps-rule/options",
-            "",
-            "requires:",
-            "  PSRule: '@pre >=2.6.0'",
-            "",
-            "output:",
-            "  culture:",
-            "  - en-US",
-            "",
-            "input:",
-            "  pathIgnore:",
-            "  - '*.md'",
-            "  - '.vscode/'",
-            "  - 'docs/'",
-            ""
-        ]
-    }
+  "PSRule options": {
+    "prefix": "ps-rule-options",
+    "description": "Default PSRule options file",
+    "body": [
+      "#",
+      "# PSRule configuration",
+      "#",
+      "",
+      "# Please see the documentation for all configuration options:",
+      "# https://aka.ms/ps-rule/options",
+      "",
+      "requires:",
+      "  PSRule: '@pre >=2.8.1'",
+      "",
+      "output:",
+      "  culture:",
+      "  - en-US",
+      "",
+      "input:",
+      "  pathIgnore:",
+      "  - '*.md'",
+      "  - '.vscode/'",
+      "  - 'docs/'",
+      ""
+    ]
+  }
 }

src/commands/configureSettings.ts

@@ -5,6 +5,10 @@ import { commands } from 'vscode';
 import { logger } from '../logger';
 import { ext } from '../extension';
 
+/**
+ * Open settings automatically filtered to PSRule specific settings.
+ * @returns A promise for the task.
+ */
 export async function configureSettings(): Promise<void> {
     const extensionId = (await ext.info).id
     logger.verbose(`Opening settings for ${extensionId}`);

src/commands/createOptionsFile.ts

@@ -7,6 +7,11 @@ import { Position, TextDocument, Uri, window, workspace } from 'vscode';
 import { logger } from '../logger';
 import { getActiveOrFirstWorkspace, readOptionsSnippet } from '../utils';
 
+/**
+ * Create a new options file.
+ * @param path The path to the options file.
+ * @returns A promise for the task.
+ */
 export async function createOptionsFile(path: string | undefined): Promise<void> {
     let defaultUri: Uri | undefined = getActiveOrFirstWorkspace()?.uri;
     if (defaultUri) {

src/commands/createOrEditDocumentation.ts

@@ -11,6 +11,11 @@ import { configuration } from '../configuration';
 const validNameExpression =
     /[^<>:/\\|?*"'`+@._\-\x00-\x1F][^<>:/\\|?*"'`+@\x00-\x1F]{1,126}[^<>:/\\|?*"'`+@._\-\x00-\x1F]+/g;
 
+/**
+ * Create or edit documentation for a rule.
+ * @param name The name of the rule.
+ * @returns A promise for the task.
+ */
 export async function createOrEditDocumentation(name: string | undefined): Promise<void> {
     if (name === '' || name === undefined) {
         name = await window.showInputBox({

src/commands/openOptionsFile.ts

@@ -6,6 +6,11 @@ import { RelativePattern, TextDocument, Uri, window, workspace, WorkspaceFolder
 import { logger } from '../logger';
 import { getActiveOrFirstWorkspace } from '../utils';
 
+/**
+ * Open an existing options file.
+ * @param path The path to the options file.
+ * @returns A promise for the task.
+ */
 export async function openOptionsFile(path: string | undefined): Promise<void> {
     const optionFilePath = await getOptionFile(path);
     if (optionFilePath === '' || optionFilePath === undefined) return;

src/commands/runAnalysisTask.ts

@@ -0,0 +1,26 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
+
+import { Task, tasks } from 'vscode';
+import { getActiveOrFirstWorkspace } from '../utils';
+import { ext } from '../extension';
+
+/**
+ * Runs the PSRule analysis task.
+ * @returns A promise for the task.
+ */
+export async function runAnalysisTask(): Promise<void> {
+    const workspace = getActiveOrFirstWorkspace();
+    if (!workspace) return;
+    const t = await ext.tasks?.getWorkspaceTasks(workspace);
+
+    if (!t) return;
+
+    const result: Task[] = [];
+    t.forEach(task => {
+        if (task.name === 'Run analysis' && task.source === 'PSRule') {
+            result.push(task);
+        }
+    });
+    await tasks.executeTask(result[0]);
+}

src/commands/showTasks.ts

@@ -0,0 +1,12 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
+
+import { commands } from 'vscode';
+
+/**
+ * Shows the quick pick list of available tasks.
+ * @returns A promise for the task.
+ */
+export async function showTasks(): Promise<void> {
+    commands.executeCommand('workbench.action.tasks.runTask');
+}

src/commands/walkthroughCopySnippet.ts

@@ -7,6 +7,11 @@ import { env } from 'vscode';
 import { logger } from '../logger';
 import { ext } from '../extension';
 
+/**
+ * Copy a walkthrough snippet to the clipboard by name.
+ * @param name The name of a snippet to copy.
+ * @returns A promise for the task.
+ */
 export async function walkthroughCopySnippet(name: string | undefined): Promise<void> {
     // Clear the clipboard and load snippets.
     env.clipboard.writeText('');

src/extension.ts

@@ -14,6 +14,8 @@ import { createOptionsFile } from './commands/createOptionsFile';
 import { openOptionsFile } from './commands/openOptionsFile';
 import { walkthroughCopySnippet } from './commands/walkthroughCopySnippet';
 import { configureSettings } from './commands/configureSettings';
+import { runAnalysisTask } from './commands/runAnalysisTask';
+import { showTasks } from './commands/showTasks';
 
 export let taskManager: PSRuleTaskProvider | undefined;
 export let docLensProvider: DocumentationLensProvider | undefined;
@@ -30,7 +32,7 @@ export class ExtensionManager implements vscode.Disposable {
     private _info!: ExtensionInfo;
     private _context!: vscode.ExtensionContext;
 
-    constructor() {}
+    constructor() { }
 
     /**
      * Information about the extension.
@@ -114,6 +116,16 @@ export class ExtensionManager implements vscode.Disposable {
                     walkthroughCopySnippet(args.snippet);
                 })
             );
+            this._context.subscriptions.push(
+                vscode.commands.registerCommand('PSRule.runAnalysisTask', () => {
+                    runAnalysisTask();
+                })
+            );
+            this._context.subscriptions.push(
+                vscode.commands.registerCommand('PSRule.showTasks', () => {
+                    showTasks();
+                })
+            );
         }
     }
 
@@ -221,14 +233,14 @@ export class ExtensionManager implements vscode.Disposable {
                 `You may experience issues running the ${extensionChannel} version of PSRule, side-by-side with the stable version. Please uninstall one of ${extensionChannel} or stable version and reload Visual Studio Code for the best experience.`,
                 showExtension,
             )
-            .then((choice) => {
-                if (choice === showExtension) {
-                    vscode.commands.executeCommand(
-                        'workbench.extensions.search',
-                        'PSRule'
-                    );
-                }
-            });
+                .then((choice) => {
+                    if (choice === showExtension) {
+                        vscode.commands.executeCommand(
+                            'workbench.extensions.search',
+                            'PSRule'
+                        );
+                    }
+                });
         }
 
         const result: ExtensionInfo = {

src/tasks.ts

@@ -314,7 +314,7 @@ export class PSRuleTaskProvider implements vscode.TaskProvider {
         }
 
         // Return the task instance.
-        return new vscode.Task(
+        const t = new vscode.Task(
             definition,
             folder ?? vscode.TaskScope.Workspace,
             taskName,
@@ -326,6 +326,8 @@ export class PSRuleTaskProvider implements vscode.TaskProvider {
             }),
             matcher
         );
+        t.detail = 'Run analysis for current workspace.';
+        return t;
     }
 }