Provide an API to track a position in a document across edits

[DanTup]

I've come across a few places where this'd be handy lately. Most recently, I run some tests for my user and I get back positions in the document of where each test is - this allows them to click on the test in the runner/results to jump directly to it.

Unfortunately, if the user modifies their test file then this location information becomes out of date and now jumps the user to the wrong location when they click it. This can be really common - you run your tests; 5 of them fail; you start working through them - working on the first test shifts the position of the tests below such that it's now difficult to jump to them from the test list.

VS Code is presumably already tracking things like this for things like decorations so it'd be nice if we could use it too. For example, imagine an API like this:

// Get some token that represents a live position in the document
const loc = document.trackLocation(position);

// User makes some edits

// Request the new position
console.log(document.positionOf(loc));

[PEZ]

@DanTup , in #48364 you mention you have code for tracking changes in the document such that you can work around the lack of a more direct VS Code API for it. Is it something you can share?

[DanTup]

@PEZ Sure - the code is in an experimental feature that nobody currently uses so I can't guarantee how well it works, but it's here:

https://github.com/Dart-Code/Dart-Code/blob/d996c73d6a455135b8e532ac266ef1f33704b0e7/src/decorations/hot_reload_coverage_decorations.ts#L54

Of interest are probably lines 73-83 which enumerates the changes and 130-145 which updates the internal model based on the changes. We track ranges of lines, so we offset any that were after the edit, leave any that were before, and drop any that are eclipsed by the edit. If you need exact offsets, you'd need to improve this somewhat.

[PEZ]

Oh, that is wonderful, @DanTup! I will need exact offsets, but it looks like I'll be able to adapt that code. Thanks for sharing!

[chestozo]

I see that internally there is a method that we would really appreciate - https://github.com/microsoft/vscode/blob/master/src/vs/editor/browser/widget/codeEditorWidget.ts#L1118 - getLineDecorations but it is not exposed to public usage.

I was trying to reach to it via

vscode.window.activeTextEditor._proxy
vscode.window.activeTextEditor._runOnProxy

but I couldn't.

Any plans to make it public?

[lovettchris]

I would propose this api instead:

https://github.com/leanprover/vscode-lean4/blob/clovett/bookmarks/vscode-lean4/src/utils/bookmarks.ts

I needed this not only to track a selection, but multiple pinned positions, and I need to know when the user deletes the span containing the bookmark - so they need a "onremoved" event also. This implementation sucks because I have to track the "before" state of the text buffer since that information doesn't come in the TextDocumentContentChangeEvent. If TextDocumentContentChangeEvent did provide the "original text" then that would solve the problem too.

[KarimGhallab]

Still no intention of adding this feature in future release ? 🤔

[srares13]

vscode-position-tracking

From what I understand there is no API provided by VS Code, nor there is an algorithm that effectively tracks a location, whatever the scenario, using the existing VS Code API. Correct me if I'm wrong.

I had some reasons for starting building such an algorithm. I tested it and improved it until I couldn't find any more situations where it wouldn't correctly update the locations. But what I would want is others to try and find situations where the updated locations are not correct.

This algorithm is served under the form of a library and its API: https://www.npmjs.com/package/vscode-position-tracking?activeTab=readme

And here is the library's repository: https://github.com/srares13/vscode-position-tracking

No delay

There is another thing. I don't know how are the decorations drown here: #73780 , but from my testing, while I was constantly updating ranges through the vscode-position-tracking library and setting decorations based on those updated ranges, it happened real time, with no flicker.

However, I noticed something, that as soon as I enabled some logs on the debug console of the development window, there was some very serious delay for me. Unfortunately, I don't know why the action of logging to debug console causes delay. Instead, if you log to the output channel of the extension (situated in the terminal's output tab of the host window / end user window), there is no issue.

Library improvements

In the future there could be added:

• Comprehensive comments to the code, explaining why each part of the code is there.
• More options regarding what happens when a document change intersects with a location that has to be updated.
• Efficiency improvements.

But I think that now the most important thing is to test the library's ability to effectively calculate the updated locations, in every scenario, according to document changes.