Integrate fingerprint validation into Visual Studio Code

[dabdine]

Description

Adds a configuration for Visual Studio Code to integrate errors and warnings from recog_verify directly into the IDE.

Motivation and Context

Updating, adding or removing fingerprints is a tedious process of adding some XML, then running recog_verify, identifying issues, and repeating until you can clear problems. By integrating that loop more tightly into the fingerprint development cycle, it should be easier for those using Visual Studio Code to add contributions.

How Has This Been Tested?

Locally using runs of the editor.

Types of changes

• New feature (non-breaking change which adds functionality)

Checklist:

• [x] I have updated the documentation accordingly (or changes are not required).
• [x] I have added tests to cover my changes (or new tests are not required).
• [x] All new and existing tests passed.

[dabdine]

One caveat: VS Code only shows one error/warning per line, whereas recog_verify can show multiple errors/warnings on the same line (if one fingerprint does not test several match group fields, for example). So, the number of errors/warnings seen in the UI will be less than or equal to the number of errors/warnings reported by recog_verify. However, in practice this won't matter, because as one warning/error is fixed, the "masked" error will then be visible.

See: https://github.com/microsoft/vscode/issues/105159#issuecomment-750345316

[dabdine]

Making a few more improvements here, so feel free to hold off on a merge.

[dabdine]

I've updated the PR to introduce new filesystem watching capabilities for recog_verify. This allows someone to leave recog_verify running in the background while editing XML fingerprint files to automatically analyze them. It's used in vscode to automatically update errors in the UI.

One caveat: recog_verify doesn't handle XML parse errors gracefully, so that's one last thing I'll look into.

[dabdine]

Yeah, forgot to run tests -- seems like our tests checking stdout output are causing a hassle again since they make assumptions about the path (relative) passed in. My changes canonicalized paths to absolute paths, so i'll poke at this a bit more.

[dabdine]

Thanks to @mkienow-r7, this should be good to review. I've made a minor update to the CONTRIBUTING.md file since the task now does not use the built-in build shortcut and instead runs constantly in the background to lint xml files.

[dabdine]

Moved all the logic out of recog_verify into a separate bash script that is run by the editor now. The bash script can also be run manually. The fswatch package on Ubuntu/MacOS is required to monitor the filesystem, but the task can still be used by rerunning it manually if it isn't installed.

[dabdine]

Eh need to update the contributing doc to mention the fswatch req

[dabdine]

This is ready for review, thanks!

[mkienow-r7]

Testing using vscode version 1.63.2 on macOS with fswatch installed and the task started via the command palette. I'm seeing an error that states I do not have fswatch installed and therefore the file system isn't being watched for updates. Is this how you start the task initially?

'fswatch' is required to monitor fingerprint files for changes and update the editor.
See: https://emcrisostomo.github.io/fswatch/ or install with:
 MacOS Homebrew: brew install fswatch
 Ubuntu/Debian:  apt install fswatch

Otherwise, you can re-run this task using the Visual Studio Code command palette
The terminal process ".vscode/bin/monitor-recog-fingerprints.sh '/recog/xml'" terminated with exit code: 1.

[dabdine]

Is fswatch in your $PATH (did you restart vscode after install)?

[mkienow-r7]

Is fswatch in your $PATH (did you restart vscode after install)?

Yes, the program is in my path and I restarted vscode after installation.

$ which fswatch
/usr/local/bin/fswatch

$ fswatch --version
fswatch 1.16.0
...

[mkienow-r7]

When the task is run via the command palette I see problem numbers quickly added to the side of the xml files, however, once the script completes execution the only problem number that remains is alongside the last file that recog_verify reported an error / warning on.

[dabdine]

@mkienow-r7 which version of vscode are you using?

Woops, 1.63.2, saw that above. Hmm.

[mkienow-r7]

Testing using vscode version 1.63.2 on macOS with fswatch installed and the task started via the command palette. I'm seeing an error that states I do not have fswatch installed and therefore the file system isn't being watched for updates. Is this how you start the task initially?

This concern was resolved during a Slack discussion with @dabdine. When restarting vscode I noticed a notification I must have dismissed before that stated the following. Unable to resolve your shell environment in a reasonable time. Please review your shell configuration.

Per the Visual Studio Code FAQ: Resolving shell environment fails suggestions, I started vscode from the repo directory using code . and the task ran without the fswatch install message.

[dabdine]

VScode doesn't allow you to reuse problemMatcher blocks, so I just copied them. The only way to "reuse" this is to make a full-blown extension, for now. I validated this via their documentation, as well as issues in the vscode github issue tracker: https://github.com/microsoft/vscode-makefile-tools/pull/221#discussion_r744930824

[mkienow-r7]

Thank you for the contribution @dabdine!