[analysis_server] Add support for LSP Document Links for example/api links

This extracts the code that finds "examples/api" paths in code from the navigation code so that it can be re-used by LSP's DocumentLink request.

This allows the links to be more visible in the editor (they are underlined and clearly clickable like hyperlinks, whereas definition required you to hover and hold Ctrl before you'd seen an underline in VS Code).

Example: https://github.com/Dart-Code/Dart-Code/assets/1078012/be9db467-dbc9-4206-9dd5-f8ca72d95596

There may be an argument for making this more general (so that links other than example/api could be detected) but for now the goal was to make these existing links more obvious.

Fixes Dart-Code/Dart-Code#4186

Change-Id: Id00425175b24394e565e13406ea4bac5691d2c72
Reviewed-on: https://dart-review.googlesource.com/c/sdk/+/333082
Commit-Queue: Brian Wilkerson <[email protected]>
Reviewed-by: Samuel Rawlins <[email protected]>
Reviewed-by: Brian Wilkerson <[email protected]>

Author: DanTup

pkg/analysis_server/lib/src/handler/legacy/analysis_get_navigation.dart

@@ -51,10 +51,9 @@ class AnalysisGetNavigationHandler extends LegacyHandler
       var allResults = <AnalysisNavigationParams>[];
       var result = await server.getResolvedUnit(file);
       if (result != null) {
-        var unit = result.unit;
         var collector = NavigationCollectorImpl();
         computeDartNavigation(
-            server.resourceProvider, collector, unit, offset, length);
+            server.resourceProvider, collector, result, offset, length);
         collector.createRegions();
         allResults.add(AnalysisNavigationParams(
             file, collector.regions, collector.targets, collector.files));

pkg/analysis_server/lib/src/legacy_analysis_server.dart

@@ -1035,7 +1035,7 @@ class ServerContextManagerCallbacks
         _notificationManager.recordNavigationParams(
             NotificationManager.serverId,
             path,
-            _computeNavigationParams(path, unit));
+            _computeNavigationParams(path, result));
       });
     }
     if (analysisServer._hasAnalysisServiceSubscription(
@@ -1093,9 +1093,9 @@ class ServerContextManagerCallbacks
   }
 
   server.AnalysisNavigationParams _computeNavigationParams(
-      String path, CompilationUnit unit) {
+      String path, ParsedUnitResult result) {
     var collector = NavigationCollectorImpl();
-    computeDartNavigation(resourceProvider, collector, unit, null, null);
+    computeDartNavigation(resourceProvider, collector, result, null, null);
     collector.createRegions();
     return server.AnalysisNavigationParams(
         path, collector.regions, collector.targets, collector.files);

pkg/analysis_server/lib/src/lsp/handlers/handler_definition.dart

@@ -56,10 +56,9 @@ class DefinitionHandler extends LspMessageHandler<TextDocumentPositionParams,
     final collector = NavigationCollectorImpl();
 
     final result = await server.getResolvedUnit(path);
-    final unit = result?.unit;
-    if (unit != null) {
+    if (result != null) {
       computeDartNavigation(
-          server.resourceProvider, collector, unit, offset, 0);
+          server.resourceProvider, collector, result, offset, 0);
       if (supportsLocationLink) {
         await _updateTargetsWithCodeLocations(collector);
       }

pkg/analysis_server/lib/src/lsp/handlers/handler_document_link.dart

@@ -0,0 +1,75 @@
+// Copyright (c) 2023, the Dart project authors. Please see the AUTHORS file
+// for details. All rights reserved. Use of this source code is governed by a
+// BSD-style license that can be found in the LICENSE file.
+
+import 'package:analysis_server/lsp_protocol/protocol.dart' hide Element;
+import 'package:analysis_server/src/lsp/constants.dart';
+import 'package:analysis_server/src/lsp/handlers/handlers.dart';
+import 'package:analysis_server/src/lsp/mapping.dart';
+import 'package:analysis_server/src/lsp/registration/feature_registration.dart';
+import 'package:analyzer/source/line_info.dart';
+import 'package:analyzer_plugin/utilities/navigation/document_links.dart';
+
+class DocumentLinkHandler
+    extends LspMessageHandler<DocumentLinkParams, List<DocumentLink>?>
+    with LspPluginRequestHandlerMixin {
+  DocumentLinkHandler(super.server);
+
+  @override
+  Method get handlesMessage => Method.textDocument_documentLink;
+
+  @override
+  LspJsonHandler<DocumentLinkParams> get jsonHandler =>
+      DocumentLinkParams.jsonHandler;
+
+  @override
+  Future<ErrorOr<List<DocumentLink>?>> handle(DocumentLinkParams params,
+      MessageInfo message, CancellationToken token) async {
+    if (!isDartDocument(params.textDocument)) {
+      return success(const []);
+    }
+
+    final path = pathOfDoc(params.textDocument);
+    final parsedUnit = await path.mapResult(requireUnresolvedUnit);
+
+    return parsedUnit.mapResult((unit) async {
+      /// Helper to convert using LineInfo.
+      DocumentLink convert(DartDocumentLink link) {
+        return _convert(link, unit.lineInfo);
+      }
+
+      final visitor = DartDocumentLinkVisitor(server.resourceProvider, unit);
+      final links = visitor.findLinks(unit.unit);
+
+      return success(links.map(convert).toList());
+    });
+  }
+
+  DocumentLink _convert(DartDocumentLink link, LineInfo lineInfo) {
+    return DocumentLink(
+      range: toRange(lineInfo, link.offset, link.length),
+      target: Uri.file(link.targetPath).toString(),
+    );
+  }
+}
+
+class DocumentLinkRegistrations extends FeatureRegistration
+    with SingleDynamicRegistration, StaticRegistration<DocumentLinkOptions> {
+  DocumentLinkRegistrations(super.info);
+
+  @override
+  ToJsonable? get options => DocumentLinkRegistrationOptions(
+        documentSelector: [dartFiles],
+        resolveProvider: false,
+      );
+
+  @override
+  Method get registrationMethod => Method.textDocument_documentLink;
+
+  @override
+  DocumentLinkOptions get staticOptions =>
+      DocumentLinkOptions(resolveProvider: false);
+
+  @override
+  bool get supportsDynamic => clientDynamic.documentLink;
+}

pkg/analysis_server/lib/src/lsp/handlers/handler_references.dart

@@ -47,9 +47,10 @@ class ReferencesHandler
             unit.result, offset, params, unit.result, performance)));
   }
 
-  List<Location> _getDeclarations(CompilationUnit unit, int offset) {
+  List<Location> _getDeclarations(ParsedUnitResult result, int offset) {
     final collector = NavigationCollectorImpl();
-    computeDartNavigation(server.resourceProvider, collector, unit, offset, 0);
+    computeDartNavigation(
+        server.resourceProvider, collector, result, offset, 0);
 
     return convert(collector.targets, (NavigationTarget target) {
       final targetFilePath = collector.files[target.fileIndex];
@@ -99,11 +100,10 @@ class ReferencesHandler
     final referenceResults = performance.run(
         'convert', (_) => convert(results, toLocation).whereNotNull().toList());
 
-    final compilationUnit = unit.unit;
     if (params.context.includeDeclaration == true) {
       // Also include the definition for the symbol at this location.
-      referenceResults.addAll(performance.run('_getDeclarations',
-          (_) => _getDeclarations(compilationUnit, offset)));
+      referenceResults.addAll(performance.run(
+          '_getDeclarations', (_) => _getDeclarations(unit, offset)));
     }
 
     return success(referenceResults);

pkg/analysis_server/lib/src/lsp/handlers/handler_states.dart

@@ -19,6 +19,7 @@ import 'package:analysis_server/src/lsp/handlers/handler_definition.dart';
 import 'package:analysis_server/src/lsp/handlers/handler_document_color.dart';
 import 'package:analysis_server/src/lsp/handlers/handler_document_color_presentation.dart';
 import 'package:analysis_server/src/lsp/handlers/handler_document_highlights.dart';
+import 'package:analysis_server/src/lsp/handlers/handler_document_link.dart';
 import 'package:analysis_server/src/lsp/handlers/handler_document_symbols.dart';
 import 'package:analysis_server/src/lsp/handlers/handler_execute_command.dart';
 import 'package:analysis_server/src/lsp/handlers/handler_exit.dart';
@@ -76,6 +77,7 @@ class InitializedLspStateMessageHandler extends InitializedStateMessageHandler {
     CompletionHandler.new,
     CompletionResolveHandler.new,
     DefinitionHandler.new,
+    DocumentLinkHandler.new,
     SuperHandler.new,
     ReferencesHandler.new,
     CodeActionHandler.new,

pkg/analysis_server/lib/src/lsp/registration/feature_registration.dart

@@ -13,6 +13,7 @@ import 'package:analysis_server/src/lsp/handlers/handler_completion.dart';
 import 'package:analysis_server/src/lsp/handlers/handler_definition.dart';
 import 'package:analysis_server/src/lsp/handlers/handler_document_color.dart';
 import 'package:analysis_server/src/lsp/handlers/handler_document_highlights.dart';
+import 'package:analysis_server/src/lsp/handlers/handler_document_link.dart';
 import 'package:analysis_server/src/lsp/handlers/handler_document_symbols.dart';
 import 'package:analysis_server/src/lsp/handlers/handler_execute_command.dart';
 import 'package:analysis_server/src/lsp/handlers/handler_folding.dart';
@@ -85,6 +86,7 @@ class LspFeatures {
   final CodeActionRegistrations codeActions;
   final CompletionRegistrations completion;
   final DefinitionRegistrations definition;
+  final DocumentLinkRegistrations documentLink;
   final DocumentColorRegistrations colors;
   final DocumentHighlightsRegistrations documentHighlight;
   final DocumentSymbolsRegistrations documentSymbol;
@@ -116,6 +118,7 @@ class LspFeatures {
         colors = DocumentColorRegistrations(context),
         completion = CompletionRegistrations(context),
         definition = DefinitionRegistrations(context),
+        documentLink = DocumentLinkRegistrations(context),
         format = FormattingRegistrations(context),
         documentHighlight = DocumentHighlightsRegistrations(context),
         formatOnType = FormatOnTypeRegistrations(context),
@@ -145,6 +148,7 @@ class LspFeatures {
         codeActions,
         completion,
         definition,
+        documentLink,
         colors,
         documentHighlight,
         documentSymbol,

pkg/analysis_server/lib/src/lsp/server_capabilities_computer.dart

@@ -77,6 +77,9 @@ class ClientDynamicRegistrations {
       _capabilities.textDocument?.documentHighlight?.dynamicRegistration ??
       false;
 
+  bool get documentLink =>
+      _capabilities.textDocument?.documentLink?.dynamicRegistration ?? false;
+
   bool get documentSymbol =>
       _capabilities.textDocument?.documentSymbol?.dynamicRegistration ?? false;
 
@@ -170,6 +173,7 @@ class ServerCapabilitiesComputer {
       hoverProvider: features.hover.staticRegistration,
       signatureHelpProvider: features.signatureHelp.staticRegistration,
       definitionProvider: features.definition.staticRegistration,
+      documentLinkProvider: features.documentLink.staticRegistration,
       implementationProvider: features.implementation.staticRegistration,
       referencesProvider: features.references.staticRegistration,
       documentHighlightProvider: features.documentHighlight.staticRegistration,

pkg/analysis_server/test/lsp/document_link_test.dart

@@ -0,0 +1,41 @@
+// Copyright (c) 2023, the Dart project authors. Please see the AUTHORS file
+// for details. All rights reserved. Use of this source code is governed by a
+// BSD-style license that can be found in the LICENSE file.
+
+import 'package:analyzer/src/test_utilities/test_code_format.dart';
+import 'package:test/test.dart';
+import 'package:test_reflective_loader/test_reflective_loader.dart';
+
+import '../utils/test_code_extensions.dart';
+import 'server_abstract.dart';
+
+void main() {
+  defineReflectiveSuite(() {
+    defineReflectiveTests(DocumentLinkTest);
+  });
+}
+
+@reflectiveTest
+class DocumentLinkTest extends AbstractLspAnalysisServerTest {
+  Future<void> test_exampleLink() async {
+    final exampleFolderPath = join(projectFolderPath, 'examples', 'api');
+    final exampleFileUri = Uri.file(join(exampleFolderPath, 'foo.dart'));
+
+    final code = TestCode.parse('''
+/// {@tool dartpad}
+/// ** See code in [!examples/api/foo.dart!] **
+/// {@end-tool}
+class A {}
+''');
+
+    newFolder(exampleFolderPath);
+    newFile(mainFilePath, code.code);
+
+    await initialize();
+    final links = await getDocumentLinks(mainFileUri);
+
+    final link = links!.single;
+    expect(link.range, code.range.range);
+    expect(link.target, exampleFileUri.toString());
+  }
+}

pkg/analysis_server/test/lsp/initialization_test.dart

@@ -281,6 +281,10 @@ class InitializationTest extends AbstractLspAnalysisServerTest {
       assertDynamicRegistration(
           'documentHighlight', {Method.textDocument_documentHighlight});
 
+  Future<void> test_dynamicRegistration_config_documentLink() =>
+      assertDynamicRegistration(
+          'documentLink', {Method.textDocument_documentLink});
+
   Future<void> test_dynamicRegistration_config_documentSymbol() =>
       assertDynamicRegistration(
           'documentSymbol', {Method.textDocument_documentSymbol});

pkg/analysis_server/test/lsp/request_helpers_mixin.dart

@@ -319,6 +319,17 @@ mixin LspRequestHelpersMixin {
         request, _fromJsonList(DocumentHighlight.fromJson));
   }
 
+  Future<List<DocumentLink>?> getDocumentLinks(Uri uri) {
+    final request = makeRequest(
+      Method.textDocument_documentLink,
+      DocumentLinkParams(textDocument: TextDocumentIdentifier(uri: uri)),
+    );
+    return expectSuccessfulResponseTo(
+      request,
+      _fromJsonList(DocumentLink.fromJson),
+    );
+  }
+
   Future<Either2<List<DocumentSymbol>, List<SymbolInformation>>>
       getDocumentSymbols(Uri uri) {
     final request = makeRequest(

pkg/analysis_server/test/lsp/test_all.dart

@@ -23,6 +23,7 @@ import 'diagnostic_test.dart' as diagnostic;
 import 'document_changes_test.dart' as document_changes;
 import 'document_color_test.dart' as document_color;
 import 'document_highlights_test.dart' as document_highlights;
+import 'document_link_test.dart' as document_link;
 import 'document_symbols_test.dart' as document_symbols;
 import 'file_modification_test.dart' as file_modification;
 import 'flutter_outline_test.dart' as flutter_outline;
@@ -73,6 +74,7 @@ void main() {
     document_changes.main();
     document_color.main();
     document_highlights.main();
+    document_link.main();
     document_symbols.main();
     file_modification.main();
     flutter_outline.main();