Debugging - UI/protocol support for "blackbox script"/"Just my code"

[roblourens]

Chrome devtools calls this "Blackboxed scripts" and VS/F12 use "Library code" and "Just my code".

This feature has been requested several times - examples,

• Make debugger respect "files.exclude" or introduce a hiding mechanic #3215
• Support debugging "Just my code" vscode-chrome-debug-core#7
• blackbox/ignore modules for debugging in node vscode-node-debug#16.

It could be implemented entirely in the debug adapter, with a new option in the launch config, and I hope to do that to try it out. But when I've used it, I've found it most useful when I can mark a script as "library code" on the fly. For this, we would need a context menu option on the callstack which can mark/unmark a particular script as library code, debug protocol support, and a toggle button to globally enable/disable the feature. (For the last item, we could use the 'exceptionBreakpointFilters' - is there anything wrong with reusing that for something besides exception breakpoints?) We also need to persist these.

This is implemented by the chrome debugging protocol. For reference it looks like this - https://chromedevtools.github.io/debugger-protocol-viewer/v8/Debugger/#method-setBlackboxPatterns - but we really just need a message that includes a DebugProtocol.Source and the library code state. I think this is of general interest since VS implements it for Javascript, C++, C# and other languages.

Thoughts/comments?

[octref]

My use case is mostly black-boxing everything required from node_modules.

[weinand]

@roblourens makes sense, I'll look into this. Protocol change should be possible for November.

[roblourens]

Cool. I can write something more comprehensive if needed. Another optional UI feature that I didn't mention is that VS and F12 collapse library code frames into one, so that you see

myCode.js
[library code]
myCode.js

instead of

myCode.js
react.js
react.js
react.js
myCode.js

but you can double-click to expand

[weinand]

@roblourens as you've pointed out, there are two 'UIs' possible for this feature request:

• a static launch.json based configuration option (e.g. glob patterns) and
• an interactive UI based on stack frames.

All feature requests from above ask only for the static mechanism ('black box everything').
And my own experience confirms this: I would blacklist 'node_modules' and other folders with low level code. But on top of that I would like to exclude additional files and/or functions on a case by case basis.

Having only the interactive UI available would require to exclude each and every file manually (which would be a pain).
Having only the launch.json based configuration option available, would result in the same functionality as the interactive approach, but adding individual files to the launch.json would be laborious.

I propose that we first implement the static launch config based approach for node-debug and node-debug2 (Nov) and then add the interactive UI (Dec/Jan) after we have resolved the following questions/issues:

• Are the blackbox items persisted across sessions? If yes:
  • where and how?
  • how is the persisted list cleared?
• What is the granularity of the items added to the blackbox list? Files or functions?

The CDP API for Blackbox patterns is marked as experimental. So node-debug2 has to deal with the situation that the API might disappear in newer versions of node.

[roblourens]

I think it's unlikely that they'd remove the API entirely, but if they did, I think it would be easy to implement the same as smartStep. I think the remaining work on the debug adapter (without adding anything to the protocol) is-

• Resolve patterns for sourcemapped files to a region inside a script
• Use glob patterns instead of regexes

And another UI thing to think about is that if we blackblox a script via the call stack, how do we unmark it? In other tools you do this by finding it in the file explorer, but that doesn't feel like the right model for us. Plus there are scripts that don't show up in our file explorer.

Another option would be to add another section to the debug viewlet (like call stack, breakpoints, etc) where patterns could be added and removed.

[roblourens]

Protocol issue here - microsoft/vscode-debugadapter-node#87

Let's use this issue for the context menu item on the call stack.

It could say "Library code" with a checkmark, or "Mark as library code"/"Unmark ...". Or something else. I like the "library code" terminology over the "blackbox script" terminology.

[isidorn]

'Mark as library code' might be a bit cryptic to the user as to how that changes the debugging experience for him. 'Blackbox' is more intuitive.
If we go into the 'Library' wording we should gray out the stack frames and on hover provide an explenation to the user as to what is going on

[roblourens]

'Library' is what's used by VS and F12 - it might be useful to match them. Some web developers will be more familiar with 'blackbox', but if we go that direction, we shouldn't use 'scripts'.

[weinand]

@roblourens since the UI for this feature will be mostly based on context menu actions, I suggest that we try to build this first as a pure extension (and not as a generic VS Code debugger UI).
This approach helps us in two ways: first we are forced to open our extension API to support this and second we can experiment with the UI for one debug extension before we are adding more generic functionality to VS Code.
As a consequence of this approach we do not have to extend the debug protocol officially but we can just start with some private protocol that is only known to the corresponding extension.

However, before we can do this, the following problems must be solved:

• an extension can contribute a context menu action to the CALL STACK view of the debug viewlet and this action is only visible and/or enabled if there is a debug session with a specific type (Support context menu action contributions for debug viewlet views #15657).
• debug adapter API (official and private) can be called from an extension (Support to call debug adapter API from extension #15656).

What do you think?

/cc @isidorn

[roblourens]

Good idea, sounds like a good time to solve those problems.

[weinand]

This feature request is for January 2017 and depends on #15657 and #15656.

Let's use #3215 for the static "blackbox script" feature which relies on an option in the launch configuration. This will be the item to put on the November 2016 plan.