Toolchain: Better out-of-the-box experience in VS Code

[p2edwards]

The goal of this PR is to enable a good out-of-the-box experience in at least one text editor, supporting all of the tools we currently use:

• EditorConfig
• Black (python formatter)
• ESLint
• Prettier (ts/js formatter)
• Stylelint
• CoffeeLint
• TypeScript language server not crashing :)

This branch contains work for VS Code. The kpi.code-workspace will suggest all needed extensions when opened. Everything ought to work from a fresh install without additional config needed.

Description

Add a kpi.code-workspace file that developers can use to configure VS Code with recommended extensions, including code linters and autoformatters.

📄 Usage

Launch the kpi.code-workspace with VS Code. Install the Workspace Recommended extensions when prompted.

The settings in kpi.code-workspace should make the extensions work without any additional configuration in VS Code. To run all the linters and formatters, you'll need to install npm packages.

• ✨ Works when installed
  • EditorConfig
  • Black
  • CoffeeLint
• 📦 Relies on local npm install
  • ESLint
  • Prettier
  • Stylelint
• 🐍 Relies on virtualenv in .venv for best results
  • Python (Microsoft)

To turn on Format and Auto Fix on Save, use the Formatting toggle ✔, bottom right.

To view output from ESLint, Stylelint, Coffeelint, and the Python and TypeScript/JavaScript error checkers, see the "Problems" tab.

[p2edwards]

This is review-ready, further support could be added in another PR.

[p2edwards]

Troubleshooting extensions

If something breaks in the future, it's worth committing fixes to kpi.code-workspace so that new developers can count on an out-of-the-box config that is known to work.

When an extension doesn't seem to be working:

• Try restarting VS Code once. (That fixes things more often than it really ought to.)
• Check the "Output" tab. There's a dropdown selector to see logs from different features and extensions. It's easy to miss, but useful.
• Check the extension readme to see if it's updated or stale. It may need a new config setting or require an update to our npm packages.
• Check for conflicts in User Settings (JSON). In VS Code, Language-specific user settings override Workspace settings.¹

Footnotes

1. Settings precedence in VS Code ↩

[p2edwards]

Performance

The Jupyter extension is installed and enabled by default along with the Python tools. You can disable it manually with the VS Code UI.

You may also wish to add these settings to your User config:

// Preferences: Open User Settings (JSON)
{
  // ...
  // Performance-oriented changes
  "files.exclude": {
    "**/*.pyc": {
      "when": "$(basename).py"
    },
    "**/__pycache__": true,
  },
  "files.watcherExclude": {
    "**/locale/**": true,
    "**/node_modules": true
  },
  // ...
}

[p2edwards]

CoffeeLint in VS Code

The CoffeeLint plugin I recommended, freewil.vscode-coffeelint2 (gh)

• doesn't show warnings in the Problems tab (unmerged PR)
• is archived with that bug and is not being updated

I'm considering switching the recommended CoffeeLint plugin to lkytal.coffeelinter (gh), since it seems to:

• read our coffeelint.json more reliably
• show both "warnings" and "errors" in the Problems tab

On the other hand,

• It seems to show warnings for files you don't even have open (which is inconvenient)
• It's not actively developed, either.

For now, I think I'll leave kpi.code-workspace as-is. If you're working on CoffeeScript code and you're using VS Code, consider using the lkytal.coffeelinter while you're doing the work, and maybe disable it if it's acting weird and you're working on something else.