Better support for code fixers

Oct 13, 2025 by pynkocean.com 147 views

Introduction

The language server is a crucial component of many development tools, providing real-time diagnostics, visual aids, and other features to enhance the coding experience. However, the language server's behavior regarding updates can be a subject of debate. Currently, the language server updates its cache of diagnostics and visual aids only on a fresh document open or when the document is saved. This means that a user only gets updates when the file in buffer is saved. In this article, we will explore the implications of turning on textDocument/didChange for the language server and discuss the potential benefits and drawbacks.

The Current Behavior

For most editing practices, the current behavior of the language server is sufficient. The user doesn't want their tool to constantly be updating, as this can be annoying or cause some diagnostics to break. However, there are other ways a file's buffer may change without a save event, where the user wants the diagnostics to update. For example:

Git operations: Git operations routinely change the underlying file, but the language server doesn't count that as a save event. It does count it as a change event.
Code fixers: Tools like chplcheck --fixit will cause the file to change without the language server updating.

This can result in diagnostic artifacts, where the lint no longer applies because the file has changed. For instance, consider the following scenario:

A user runs chplcheck --fixit on a file, which changes the file's contents.
The language server doesn't update its cache, so the diagnostics remain outdated.
The user tries to lint the file again, but the diagnostics no longer apply because the file has changed.

The Proposed Change

I am inclined to update the language server to update on textDocument/didChange (which is a small code change to support it). This would allow the language server to update its cache in real-time, even when the file's buffer changes without a save event. However, in the past, I recall some opposition to this for specific reasons I don't recall, hence this issue.

Potential Benefits

Turning on textDocument/didChange for the language server could bring several benefits:

Improved diagnostics: The language server would update its cache in real-time, ensuring that the diagnostics remain accurate and up-to-date.
Enhanced user experience: Users would no longer have to wait for the file to be saved to get updates on their diagnostics.
Better support for code fixers: Tools like chplcheck --fixit would work seamlessly with the language server, allowing users to fix issues in their code without worrying about outdated diagnostics.

Potential Drawbacks

However, there are also potential drawbacks to consider:

Performance impact: Updating the language server in real-time could impact performance, especially for large files or complex projects.
Annoyance: Some users might find the constant updates annoying, especially if they are not used to it.
Diagnostic breakage: In some cases, the diagnostics might break if the language server updates too frequently, causing issues for users.

Conclusion

In conclusion, turning on textDocument/didChange for the language server is a complex issue that requires careful consideration. While it could bring several benefits, such as improved diagnostics and enhanced user experience, it also poses potential drawbacks, such as performance impact and annoyance. Ultimately, the decision to update the language server to update on textDocument/didChange depends on the specific needs and requirements of the project.

Recommendations

Based on the discussion above, I recommend the following:

Conduct thorough testing: Before making any changes, conduct thorough testing to ensure that the language server updates correctly and doesn't cause any issues.
Gather user feedback: Gather feedback from users to understand their needs and preferences regarding the language server's behavior.
Monitor performance: Monitor the performance of the language server to ensure that it doesn't impact the user experience.

By following these recommendations, we can make an informed decision about whether to turn on textDocument/didChange for the language server and ensure that it meets the needs of our users.

Future Work

If we decide to turn on textDocument/didChange for the language server, we will need to:

Implement the change: Update the language server to update on textDocument/didChange.
Test and validate: Thoroughly test and validate the change to ensure that it works correctly and doesn't cause any issues.
Monitor and maintain: Monitor the performance of the language server and make any necessary adjustments to ensure that it continues to meet the needs of our users.

Introduction

In our previous article, we discussed the implications of turning on textDocument/didChange for the language server. We explored the potential benefits and drawbacks of this change and provided recommendations for moving forward. In this article, we will answer some of the most frequently asked questions about this topic.

Q: What is `textDocument/didChange`?

A: textDocument/didChange is a notification sent by the language server to the client when the text document has changed. This notification is part of the Language Server Protocol (LSP) and is used to update the client's view of the document.

Q: Why do we need to turn on `textDocument/didChange`?

A: We need to turn on textDocument/didChange to ensure that the language server updates its cache in real-time, even when the file's buffer changes without a save event. This is particularly important for code fixers like chplcheck --fixit, which can change the file's contents without saving it.

Q: What are the potential benefits of turning on `textDocument/didChange`?

A: The potential benefits of turning on textDocument/didChange include:

Improved diagnostics: The language server would update its cache in real-time, ensuring that the diagnostics remain accurate and up-to-date.
Enhanced user experience: Users would no longer have to wait for the file to be saved to get updates on their diagnostics.
Better support for code fixers: Tools like chplcheck --fixit would work seamlessly with the language server, allowing users to fix issues in their code without worrying about outdated diagnostics.

Q: What are the potential drawbacks of turning on `textDocument/didChange`?

A: The potential drawbacks of turning on textDocument/didChange include:

Performance impact: Updating the language server in real-time could impact performance, especially for large files or complex projects.
Annoyance: Some users might find the constant updates annoying, especially if they are not used to it.
Diagnostic breakage: In some cases, the diagnostics might break if the language server updates too frequently, causing issues for users.

Q: How can we mitigate the potential drawbacks of turning on `textDocument/didChange`?

A: We can mitigate the potential drawbacks of turning on textDocument/didChange by:

Conducting thorough testing: Before making any changes, conduct thorough testing to ensure that the language server updates correctly and doesn't cause any issues.
Gathering user feedback: Gather feedback from users to understand their needs and preferences regarding the language server's behavior.
Monitoring performance: Monitor the performance of the language server to ensure that it doesn't impact the user experience.

Q: What is the next step if we decide to turn on `textDocument/didChange`?

A: If we decide to turn on textDocument/didChange, the next step would be to:

Implement the change: Update the language server to update on textDocument/didChange.
Test and validate: Thoroughly test and validate the change to ensure that it works correctly and doesn't cause any issues.
Monitor and maintain: Monitor the performance of the language server and make any necessary adjustments to ensure that it continues to meet the needs of our users.

Conclusion

In conclusion, turning on textDocument/didChange for the language server is a complex issue that requires careful consideration. While it could bring several benefits, such as improved diagnostics and enhanced user experience, it also poses potential drawbacks, such as performance impact and annoyance. By answering these frequently asked questions, we hope to provide a better understanding of the implications of this change and help inform our decision-making process.