Annotation Linker for VS Code

Annotation Linker is a VS Code extension that turns structured annotation values into clickable links.

The first supported use case is Java annotations:

@YouTrack("ADV-3981")

When the extension is active, the ADV-3981 value behaves like a regular editor link:

• hover shows the generated URL;
• Ctrl+Click opens the generated URL in the default browser;
• no CodeLens or extra visual row is rendered above the code.

Why

Teams often want to keep short issue IDs in code instead of full URLs:

@YouTrack("ADV-3981")

That is cleaner for test metadata and custom tooling, but editors do not know how to open the short ID. Annotation Linker bridges that gap with configurable rules.

Configuration

Rules are configured through the standard VS Code setting annotationLinker.rules.

You can define rules globally in User Settings or per project in .vscode/settings.json.

{
  "annotationLinker.rules": [
    {
      "language": "java",
      "annotation": "YouTrack",
      "valuePattern": "[A-Z]+-\\d+",
      "urlPattern": "https://youtrack.example.com/issue/{}"
    }
  ]
}

Fields:

• language: VS Code language id. The MVP registers providers for java.
• annotation: annotation name without @.
• valuePattern: regular expression that the annotation value must fully match.
• urlPattern: generated URL pattern. It must contain {} as the placeholder for the annotation value.

For the default rule, @YouTrack("ADV-3981") becomes:

https://youtrack.example.com/issue/ADV-3981

Example

@interface YouTrack {
    String value();
}

class ExampleTest {
    @YouTrack("ADV-3981")
    void shouldShowClickableIssueLink() {
    }
}

Development

Install dependencies:

npm install

Compile:

npm run compile

Run tests:

npm test

Debug in VS Code:

1. Open this repository in VS Code.
2. Select Run Annotation Linker Extension in the Run and Debug panel.
3. Press F5 to open an Extension Development Host.

Packaging

Build a local VSIX package:

npm run package

Install the generated package:

code --install-extension .\annotation-linker-vscode-0.0.13.vsix

Current MVP Scope

Included:

• Java annotation scanning.
• Hover tooltip with the generated URL.
• Ctrl+Click through VS Code DocumentLinkProvider.
• Configurable annotation name, value regex, and URL pattern.
• Validation for invalid rules and non-http(s) URLs.

Not included yet:

• CodeLens.
• YouTrack API integration.
• Authentication.
• Issue status rendering.
• Comment fallback.
• Java AST parsing.
• Non-Java providers.