Merge pull request #150 from glennsarti/add-debug-adapter

(GH-100) Add debug adapter

Author: jpogran

client/README.md

@@ -37,6 +37,7 @@ Create or open any Puppet manifest with the extension `.pp` or `.epp` and the ex
 - Import from `puppet resource` directly into manifests
 - Node graph preview
 - Puppet Development Kit integration
+- (Experimental) Local debugging of Puppet manifests
 
 ## Feature information
 
@@ -99,6 +100,32 @@ To use any of the above commands, open the command palette and start typing a co
 
 `PDK New Module` is available even if the extension isn't loaded, the rest of the commands are only available when the extension is loaded.
 
+### Locally debugging Puppet manifests
+
+**Note - This is an experimental feature**
+
+The Puppet extension is able to debug the compilation of a Puppet manifest, much like a Go, PowerShell, C# etc.  The debugger supports:
+
+* Line breakpoints but not conditions on those breakpoints
+* Function breakpoints
+* Exception breakpoints
+* Call stack
+* Variables, but only at the top stack frame
+* Limited interactive debug console.  For example, you can assign a variable a value, but just as in regular Puppet you can't change its value later
+* Step In, Out, Over
+
+You may be presented with a Launch Configuration on first use.  Please see the [VSCode Debugging link](https://code.visualstudio.com/docs/editor/debugging) for instructions on how to set this up.
+
+Settings:
+
+`manifest` - The manifest to apply.  By default this is the currently open file in the editor
+
+`noop` - Whether the `puppet apply` sets No Operation (Noop) mode.  By default, this is set to false.  This means when runing the debugger it can make changes to your system
+
+`args` - Additional arguements to pass to `puppet apply`, for example `['--debug']` will output debug information
+
+![Puppet Debug Adapter](https://raw.githubusercontent.com/jpogran/puppet-vscode/master/client/docs/assets/puppet_debug.gif)
+
 ## Installing the Extension
 
 You can install the official release of the Puppet extension by following the steps

client/docs/assets/puppet_debug.gif

@@ -16,6 +16,7 @@ gulp.task('clean', function () {
 gulp.task('copy_language_server', function () {
   return gulp.src(['../server/lib/**/*',
                    '../server/vendor/**/*',
+                   '../server/puppet-debugserver',
                    '../server/puppet-languageserver'
                   ], { base: '../server'})
              .pipe(gulp.dest('./vendor/languageserver'));

client/gulpfile.js

@@ -27,7 +27,8 @@
     "Linters",
     "Languages",
     "Snippets",
-    "Formatters"
+    "Formatters",
+    "Debuggers"
   ],
   "keywords": [
     "puppet",
@@ -309,7 +310,70 @@
           "description": "The fully qualified path to the Puppet agent install directory. For example: 'C:\\Program Files\\Puppet Labs\\Puppet' or '/opt/puppetlabs/puppet'"
         }
       }
-    }
+    },
+    "breakpoints": [
+      {
+        "language": "puppet"
+      }
+    ],
+    "debuggers": [
+      {
+        "type": "Puppet",
+        "label": "Puppet Debugger",
+        "program": "./out/src/debugAdapter.js",
+        "runtime": "node",
+        "languages": [
+          "puppet"
+        ],
+        "configurationSnippets": [
+          {
+            "label": "Puppet: Apply Current File",
+            "description": "Apply current file (in active editor window) under debugger",
+            "body": {
+              "type": "Puppet",
+              "request": "launch",
+              "name": "Puppet Apply current file",
+              "manifest": "^\"\\${file}\"",
+              "args": [],
+              "noop": false,
+              "cwd": "^\"\\${file}\""
+            }
+          }
+        ],
+        "configurationAttributes": {
+          "launch": {
+            "properties": {
+              "program": {
+                "type": "string",
+                "description": "Deprecated. Please use the 'manifest' property instead to specify the absolute path to the Puppet manifest to launch under the debugger."
+              },
+              "manifest": {
+                "type": "string",
+                "description": "Optional: Absolute path to the Puppet manifest to launch under the debugger."
+              },
+              "noop": {
+                "type": "boolean",
+                "description": "Optional: Whether the the Puppet run is in NoOp mode. Default is false.",
+                "default": false
+              },
+              "args": {
+                "type": "array",
+                "description": "Command line arguments to pass to Puppet.",
+                "items": {
+                "type": "string"
+                },
+                "default": []
+              },
+              "cwd": {
+                "type": "string",
+                "description": "Absolute path to the working directory. Default is the current workspace.",
+                "default": "${workspaceRoot}"
+              }
+            }
+          }
+        }
+      }
+    ]
   },
   "scripts": {
     "vscode:prepublish": "node node_modules/gulp/bin/gulp.js build",
@@ -333,6 +397,8 @@
   "dependencies": {
     "vscode-languageclient": "~3.3.0",
     "vscode-extension-telemetry": "^0.0.6",
-    "viz.js":"~1.8.0"
+    "viz.js":"~1.8.0",
+    "vscode-debugprotocol": "^1.19.0",
+    "vscode-debugadapter": "^1.19.0"
   }
 }

client/package.json

@@ -3,15 +3,15 @@
 import * as vscode from 'vscode';
 import * as cp from 'child_process';
 import ChildProcess = cp.ChildProcess;
-import { Logger } from '../../logging';
+import { ILogger } from '../../logging';
 import { reporter } from '../../telemetry/telemetry';
 import * as messages from '../../messages';
 
 export class pdkNewClassCommand {
-  private logger: Logger = undefined;
+  private logger: ILogger = undefined;
   private terminal: vscode.Terminal = undefined;
 
-  constructor(logger: Logger, terminal: vscode.Terminal) {
+  constructor(logger: ILogger, terminal: vscode.Terminal) {
     this.logger = logger;
     this.terminal = terminal;
   }

client/src/commands/pdk/pdkNewClassCommand.ts

@@ -1,15 +1,15 @@
 'use strict';
 
 import * as vscode from 'vscode';
-import { Logger } from '../../logging';
+import { ILogger } from '../../logging';
 import { reporter } from '../../telemetry/telemetry';
 import * as messages from '../../messages';
 
 export class pdkNewModuleCommand {
-  private logger: Logger = undefined;
+  private logger: ILogger = undefined;
   private terminal: vscode.Terminal = undefined;
 
-  constructor(logger: Logger, terminal: vscode.Terminal) {
+  constructor(logger: ILogger, terminal: vscode.Terminal) {
     this.logger = logger;
     this.terminal = terminal;
   }

client/src/commands/pdk/pdkNewModuleCommand.ts

@@ -3,15 +3,15 @@
 import * as vscode from 'vscode';
 import * as cp from 'child_process';
 import ChildProcess = cp.ChildProcess;
-import { Logger } from '../../logging';
+import { ILogger } from '../../logging';
 import { reporter } from '../../telemetry/telemetry';
 import * as messages from '../../messages';
 
 export class pdkTestUnitCommand {
-  private logger: Logger = undefined;
+  private logger: ILogger = undefined;
   private terminal: vscode.Terminal = undefined;
 
-  constructor(logger: Logger, terminal: vscode.Terminal) {
+  constructor(logger: ILogger, terminal: vscode.Terminal) {
     this.logger = logger;
     this.terminal = terminal;
   }

client/src/commands/pdk/pdkTestCommand.ts

@@ -3,15 +3,15 @@
 import * as vscode from 'vscode';
 import * as cp from 'child_process';
 import ChildProcess = cp.ChildProcess;
-import { Logger } from '../../logging';
+import { ILogger } from '../../logging';
 import { reporter } from '../../telemetry/telemetry';
 import * as messages from '../../messages';
 
 export class pdkValidateCommand {
-  private logger: Logger = undefined;
+  private logger: ILogger = undefined;
   private terminal: vscode.Terminal = undefined;
 
-  constructor(logger: Logger, terminal: vscode.Terminal) {
+  constructor(logger: ILogger, terminal: vscode.Terminal) {
     this.logger = logger;
     this.terminal = terminal;
   }

client/src/commands/pdk/pdkValidateCommand.ts

@@ -1,14 +1,14 @@
 import * as vscode from 'vscode';
 import * as messages from '../../src/messages';
 import { IConnectionManager } from '../../src/connection';
-import { Logger } from '../../src/logging';
+import { ILogger } from '../../src/logging';
 import { pdkNewModuleCommand } from './pdk/pdkNewModuleCommand';
 import { pdkNewClassCommand } from './pdk/pdkNewClassCommand';
 import { pdkNewTaskCommand } from './pdk/pdkNewTaskCommand';
 import { pdkValidateCommand } from './pdk/pdkValidateCommand';
 import { pdkTestUnitCommand } from './pdk/pdkTestCommand';
 
-export function setupPDKCommands(langID: string, connManager: IConnectionManager, ctx: vscode.ExtensionContext, logger: Logger, terminal: vscode.Terminal) {
+export function setupPDKCommands(langID: string, connManager: IConnectionManager, ctx: vscode.ExtensionContext, logger: ILogger, terminal: vscode.Terminal) {
   let newModuleCommand = new pdkNewModuleCommand(logger, terminal);
   ctx.subscriptions.push(newModuleCommand);
   ctx.subscriptions.push(vscode.commands.registerCommand(messages.PDKCommandStrings.PdkNewModuleCommandId, () => {

client/src/commands/pdkcommands.ts

@@ -1,8 +1,9 @@
 'use strict';
 
 import * as vscode from 'vscode';
-import { IConnectionManager, ConnectionStatus } from '../../connection';
-import { Logger } from '../../logging';
+import { ConnectionStatus } from '../../interfaces';
+import { IConnectionManager } from '../../connection';
+import { ILogger } from '../../logging';
 import { reporter } from '../../telemetry/telemetry';
 import * as messages from '../../messages';
 
@@ -13,9 +14,9 @@ class RequestParams implements messages.PuppetResourceRequestParams {
 
 export class puppetResourceCommand {
   private _connectionManager: IConnectionManager = undefined;
-  private logger: Logger = undefined;
+  private logger: ILogger = undefined;
 
-  constructor(connMgr: IConnectionManager, logger: Logger) {
+  constructor(connMgr: IConnectionManager, logger: ILogger) {
     this._connectionManager = connMgr;
     this.logger = logger;
   }