vscode-xreferee

Validate cross references throughout a git repo.

This vscode extension is an adapter for the xreferee CLI tool.

Overview

It's often useful to link two different locations in a codebase, and it might not always be possible to enforce it by importing a common source of truth. Some examples:

• Keeping two constants in sync across files in two different languages
• Linking an implementation to markdown files or comments documenting the design
• Referencing an invariant documented on a field definition at the call-site

See GHC's wiki on how they've found cross references helpful: https://gitlab.haskell.org/ghc/ghc/-/wikis/commentary/coding-style#2-using-notes.

You can use this tool to validate that cross references across a repository are valid. For example:

This is a _markdown_ **file** documenting a feature.
We can mark this as a source of truth with a Markdown comment:
<!-- #(ref:my-feature) -->

# In my Python code, add a reference to the markdown document, where
# you know you can just search for a matching anchor tag
# See @(ref:my-feature)
def my_feature():
    pass

# Maybe the Python file is also the source of truth for a constant:
# #(ref:my-version-123)
MY_VERSION = 123

// Then in my Javascript file, we can use a cross reference to ensure they're
// kept in sync. If the label above is updated to `my-version-124`, then this
// cross reference will be broken, and xreferee will flag it.
// @(ref:my-version-123)
const MY_VERSION = 123

Features

• Go To Definition: navigate from a reference to its anchor.
• Find All References: navigate from an anchor to its references.
• Diagnostics: reports warnings/errors for unused anchors, duplicate anchors, and broken references.
• Rename labels, updating all associated anchors/references.

These features are provided by the xreferee LSP server. This extension automatically downloads the latest release if the lsp-xreferee binary is not found in your PATH.

Extension Settings

This extension contributes the following setting:

• xreferee.serverArgs: Additional command-line arguments passed to the lsp-xreferee process.

Example:

{
	"xreferee.serverArgs": "--log-file <file>"
}

Release Notes

See CHANGELOG.md for release history.