Provide a smart run/debug command for loose files

[digitarald]

tl;dr: Running a single file without a workspace open is a common pain point in usertesting. It should not just be easier, but also take the opportunity to check the user's environment and guide through the installation/configuration of missing dependencies.

Context

VS Code is used by many as their first editor while learning to code. Other editors in the space make it a lot easier to run a single file to see the output, which puts expectations on how VS Code should work. VS Code's latest improvements with auto-attach and JS debug terminal show how the setup time for debugging can be cut dramatically with smart affordances.

End to End Scenario

1. User is interested in learning about TS, but doesn't have the NPM packages installed.
2. To start, they create a single TS file in VS Code, without opening a folder.
3. Rich TS editing works out of the box, so they start typing up a short script that logs some values.
4. Then they try run the file to see if it compiles and logs the output.
5. With a helpful hand from VS Code, the user installs the required TS dependencies.
6. Finally, running the file works.
7. [Out of scope] Later, after the user adds a a second file to use modules, VS Code guides the user to initialize a project with a tsconfig file (picking browser and/or node.js as target).

Alternative Scenerios

How the user is set up:

• While many devs have node.js installed, support the ones that don't.
• Some users might have an older node.js installed from prior projects

How the file is opened

• User opens a folder with a set of TS files (like the TS samples) and opens one file.
• User renames a JS file to TS in a folder to migrate some code.

Improvement ideas

• For loose files that VS Code knows how to debug, show a Run button on the file.
  • Without a workspace open, the Run & Debug view should ask the user to select which file to run.
• Could/should VS Code …
  • ship with a basic TS compiler,
  • install one behind the scenes,
  • guide the user through installation (via terminal?),
  • or point to the right website for the user to complete the installation?
• Offer the guided environment setup during a getting started walkthrough for TS
• While we sweat the details, keep in mind how the same flows would work for Python, C++, Java, etc

Next steps

• Converging discussion on scope and clarify open questions
• UX & PoC for TS files (maybe as extension)
• Usertest & Experiment
• Ship it

cc @gcrev93 @DanielRosenwasser @connor4312 @misolori @JacksonKearl @kieferrm @mattbierner

[connor4312]

I think 'running' should == debugging in this scenario.

Yes, for the new user I would want to skip step 5. VS Code already ships with Typescript, which has compilation and transpilation. It should be possible to leverage that to install a loader in Node.js (e.g. from the js-debug bootloader) so that they can run TS files without any installation/setup.

There's still the question of how we get users from there to a 'proper' Typescript setup, but (a) that may not be needed for all cases, especially people in CS101 writing their first hello world/quicksort and (b) it moves a choke point of the funnel much later.

[weinand]

VS Code already supports "smart run/debug command for loose files" if the corresponding extension is smart enough.

Here is the flow if "Java Extension Pack" is installed in VS Code:

• make sure VS Code is not running
• open "loose Java file" with VS Code
• press "Run" button in editor header: file is compiled and run in integrated terminal
• set a breakpoint and select "debug" from "Run/debug" dropdown item: breakpoint is hit

Please note: VS Code is not in folder mode and Java compiles, runs, and debugs the file without problems (thanks @akaroml).

And here the equivalent for Python (@luabud Python is not yet using our "editor/title/run" menu contribution point but contributing just a "loose" run button):

Doing the same for TS/JS just requires to contribute a "Run" and a "Debug" command to the "editor/title/run" menu contribution point.

[isidorn]

Agree with @weinand here. I do not think a lot is missing in order to make this experience butter smooth.
So the first step is for the TS/JS to contribute a command as Andre says. After that is done, we can try to compile a list of any other potential blockers and try to tackle them - though I do not see any looking from the outside in.

As for users with nothing installed. Installing extensions should be tackled via our automatic language detection and extension recommendations. For installing dependencies and compiling I would create a separate issue for that as that seems language specific and not something that Debug can solve imho.

[connor4312]

There's a few paths for TS compilation:

• If there's a tsconfig already configured, just compile with it normally. (also, force sourceMaps: true?)
• If there's not a tsconfig... the default behavior of tsc is to place compiled files beside source files (and sourcemaps aren't on by default). This is pretty messy, should it compile to a tmpdir instead and then run it, with absolute paths in the generated sourcemaps?
• Or we could have js-debug's bootloader inject ts-loader-like logic to do the compilation. This is probably more complex than triggering a normal compilation, but it's a path I'd be willing to take.

For TS there should not be any additional extension installations needed.

[DanielRosenwasser]

also, force sourceMaps: true?

This is pretty messy, should it compile to a tmpdir instead and then run it, with absolute paths in the generated sourcemaps?

One idea is to run with inlineSourceMaps to avoid creating extra files if neither inlineSourceMaps nor sourceMaps are specified. If you want to compile to an temporary output directory, you can compile with inlineSources to avoid having to figure absolute paths, though that could create a lot of duplication in the worst case.

If there's a tsconfig already configured, just compile with it normally.

Things get weird if you have noEmit, emitDeclarationsOnly, and potentially other options. It's still doable, I just think we'd want to be mindful of a user's options here.

[isidorn]

After syncing with @connor4312 here's our thinking:

• The TS extension should contribute a start debug / run button in the editor title area (only when there is no launch.json, we can recommend a good context key to use)
• This command should do the compiling and call vscode.debug.startDebugger to trigger js-debug when ready.
• Compiling of the files can be done in os.tmpdir() and pass the cwd and program path to it to VS Code in the launch configuration.
• If there is not tsconfig.json the TS Extension can use default compiler options. Probably transpileOnly , target ES2020, emit commonjs.

@DanielRosenwasser @gcrev93 what do you think?

[isidorn]

Also js-debug would no longer say it is interested in typescript files, and TS extension would instead say it is interested in typescript files. The TS extension would then handle these files in a super simple way just by forwarding startDebugging to js-debug.
That way F5 would also work for typescript files when there is no launch.json.

fyi @mjbvz

[DanielRosenwasser]

I think that's fine as a starting point - I wonder if there should be a special case when a tsconfig.json points to one file, but for now it's probably fine.

[isidorn]

@DanielRosenwasser great! What should be the best way to go forward. Should I file an issue in the Typescript repo with our recommendation on how to do this or what do you think is best? Thanks

[DanielRosenwasser]

As far as I can tell, it's just work that needs to happen on the TS extension side. If there's any places where the extension doesn't have the right information and needs to consult the server, we can try to figure that out and bring it to one of the editor syncs.

[isidorn]

Great, then we should plan work on the TS extension side.
@mjbvz @JacksonKearl @connor4312 would anyone be interested in implementing this on the TS extension side in November?

Thanks

[connor4312]

I would be happy to but I have a bunch of work in the pipeline and will need to discuss scheduling with Kai

[isidorn]

@connor4312 great 👏
Let's move this to On-Deck, and then to a specific milestone once you find time. Thanks!

[byehack]

loose files cannot have configured debug button in python: microsoft/vscode-python-debugger#525

It would be great to configure run/debug button for loose files:

1. If file is in workspace but there is no launch.json: use Workspace launch settings(if it's set else ask to use LS provided settings or create/set new one. )
2. If file is not in workspace: use launch in user settings (if it's set else ask to use LS provided settings or create/set new one. )

by these cases the priority is launch.json > Workspace > User
If none of them were set, it should show these items in quick input menu:

• use language provided settings
• use and remember language provided settings
• new configuration in user settings
• new configuration in workspace settings
• new configuration in launch.json settings (if file isn't loose)

[weinand]

@byehack thanks for your proposal.

Please note that VS Code knows nothing (cannot make assumptions) about debugging loose files because there is no generic way to associate a launch configuration (from a launch.json or workspace/user setting) with a specific file. Debugging loose files can only be handled by a debugger extension which knows the language specific details about debugging.

Having said that, I think your proposal can be easily implemented by a specific debugger extension, but not by VS Code.

[isidorn]

Moving to next milestone since we did not find time in January.