Интеграция с сервером языковых инструментов

Совет

Если вы ищете информацию о том, как использовать LSP Deno с различными редакторами, посетите страницу настройки среды.

В состав Deno CLI входит встроенный сервер языковых инструментов, который обеспечивает интеллектуальное редактирование, а также упрощает доступ к другим встроенным инструментам Deno. Большинство пользователей работает с сервером языковых инструментов через редактор, например Visual Studio Code или другие редакторы.

Эта страница предназначена для тех, кто разрабатывает интеграции с сервером языковых инструментов или предоставляет реестр пакетов для Deno с интеллектуальной интеграцией.

Сервер языковых инструментов Deno реализует протокол Language Server Protocol и специально адаптирован для предоставления представления кода в контексте Deno. Он интегрирован в командную строку и может быть запущен с помощью подкоманды lsp.

Структура

При запуске сервера языковых инструментов создается экземпляр LanguageServer, в котором хранится все состояние сервера. Он также определяет все методы, вызываемые клиентом через протокол RPC Language Server.

Настройки

Сервер языковых инструментов поддерживает ряд настроек рабочей области:

deno.enable
deno.enablePaths
deno.cache
deno.certificateStores
deno.config
deno.importMap
deno.internalDebug
deno.codeLens.implementations
deno.codeLens.references
deno.codeLens.referencesAllFunctions
deno.codeLens.test
deno.suggest.completeFunctionCalls
deno.suggest.names
deno.suggest.paths
deno.suggest.autoImports
deno.suggest.imports.autoDiscover
deno.suggest.imports.hosts
deno.lint
deno.tlsCertificate
deno.unsafelyIgnoreCertificateErrors
deno.unstable

Также сервер языковых инструментов поддерживает следующие настройки для отдельных ресурсов:

deno.enable
deno.enablePaths
deno.codeLens.test

Deno анализирует эти настройки на нескольких этапах работы сервера языковых инструментов. Сначала, когда от клиента поступает запрос initialize, предполагается, что initializationOptions — это объект, представляющий пространство имен параметров deno. Например, следующее значение включит Deno с нестабильными API для этого экземпляра сервера языковых инструментов.

{
  "enable": true,
  "unstable": true
}

Получив уведомление workspace/didChangeConfiguration, сервер языковых инструментов проверит, указал ли клиент наличие возможности workspaceConfiguration. Если да, он отправит запрос workspace/configuration, содержащий запрос конфигурации рабочей области, а также конфигурации всех URI, которые сервер языковых инструментов отслеживает в данный момент.

Если клиент поддерживает возможность workspaceConfiguration, сервер языковых инструментов отправит запрос конфигурации для URI при получении уведомления textDocument/didOpen, чтобы получить настройки для конкретного ресурса.

Если клиент не поддерживает возможность workspaceConfiguration, сервер языковых инструментов будет считать, что настройки рабочей области применяются ко всем ресурсам.

Команды

Сервер языковых инструментов может отправлять клиенту несколько команд, которые клиент должен реализовать:

.cache

deno.cache отправляется как действие для разрешения кода, когда в модуль импортируется спецификатор модуля, отсутствующий в кэше. Вместе с командой передается аргумент, содержащий разрешенный спецификатор в виде строки для добавления в кэш.

showReferences

deno.showReferences передается как команда для некоторых линз кода, чтобы показать расположение ссылок. Аргументы содержат спецификатор, к которому относится команда, начальную позицию целевого объекта и расположения ссылок, которые нужно показать.

test

deno.test отправляется в составе линзы кода для теста. Клиент должен запустить тест на основе аргументов, которыми являются спецификатор, содержащий тест, и имя теста, используемое для фильтрации тестов.

Запросы

В настоящее время LSP поддерживает следующие пользовательские запросы. Для полноценной интеграции с Deno клиенту следует реализовать эти запросы:

/cache

deno/cache указывает Deno попытаться добавить в кэш модуль и все его зависимости. Если передан только referrer, будут загружены все зависимости спецификатора модуля. Если в uris есть значения, в кэш будут добавлены только эти uris.

Ожидаемые параметры:

interface CacheParams {
  referrer: TextDocumentIdentifier;
  uris: TextDocumentIdentifier[];
}

performance

deno/performance запрашивает средние значения времени, полученные с помощью внутренней системы инструментирования Deno. Параметры не требуются.

reloadImportRegistries

deno/reloadImportRegistries перезагружает все кэшированные ответы реестров импорта. Параметры не требуются.

virtualTextDocument

deno/virtualTextDocument запрашивает у LSP виртуальный текстовый документ — доступный только для чтения документ, который можно отобразить в клиенте. Это позволяет клиентам получать доступ к документам в кэше Deno, например к удаленным модулям и файлам библиотеки TypeScript, встроенным в Deno. Сервер языковых инструментов Deno кодирует все внутренние файлы с использованием пользовательской схемы deno:, поэтому клиенты должны перенаправлять все запросы для схемы deno: обратно в API deno/virtualTextDocument.

Также поддерживается специальный URL deno:/status.md, который предоставляет текстовый документ в формате Markdown со сведениями о состоянии LSP для отображения пользователю.

Ожидаемые параметры:

interface VirtualTextDocumentParams {
  textDocument: TextDocumentIdentifier;
}

task

deno/task запрашивает список доступных задач Deno. См. раздел task_runner. Параметры не требуются.

Уведомления

В настоящее время сервер отправляет клиенту одно пользовательское уведомление — deno/registryState. Когда deno.suggest.imports.autoDiscover имеет значение true и источник добавляемого в документ импорта явно не указан в deno.suggest.imports.hosts, источник проверяется, а клиенту отправляется уведомление о результате.

При получении уведомления, если параметр suggestion имеет значение true, клиент должен предложить пользователю разрешить источник и добавить его в конфигурацию для deno.suggest.imports.hosts. Если suggestion имеет значение false, клиент должен добавить его в конфигурацию как false, чтобы сервер языковых инструментов не пытался определить, поддерживаются ли подсказки.

Параметры уведомления:

interface RegistryStatusNotificationParams {
  origin: string;
  suggestions: boolean;
}

Идентификаторы языков

Сервер языковых инструментов поддерживает диагностику и форматирование для следующих идентификаторов языков текстовых документов:

"javascript"
"javascriptreact"
"jsx" нестандартный, соответствует javascriptreact
"typescript"
"typescriptreact"
"tsx" нестандартный, соответствует typescriptreact

Сервер языковых инструментов поддерживает только форматирование для следующих идентификаторов языков:

"json"
"jsonc"
"markdown"

Тестирование

Сервер языковых инструментов Deno поддерживает набор пользовательских API для тестирования. Они предназначены для предоставления сведений, необходимых для работы API тестирования VS Code, но могут использоваться и другими клиентами сервера языковых инструментов для реализации аналогичного интерфейса.

И клиент, и сервер должны поддерживать экспериментальную возможность testingApi:

interface ClientCapabilities {
  experimental?: {
    testingApi: boolean;
  };
}

interface ServerCapabilities {
  experimental?: {
    testingApi: boolean;
  };
}

Когда версия Deno с поддержкой API тестирования обнаруживает клиент, поддерживающий эту возможность, она инициализирует код обработки обнаружения тестов и начинает отправлять необходимые для этого уведомления.

Следует также отметить, что при включенных возможностях API тестирования линзы кода для тестирования больше не отправляются клиенту.

Настройки тестирования

Поведение сервера языковых инструментов изменяют следующие настройки:

deno.testing.args — массив строк, которые будут переданы как аргументы при запуске тестов. Работает так же, как подкоманда deno test.
deno.testing.enable — двоичный флаг, включающий или отключающий сервер тестирования.

Уведомления о тестировании

При определенных условиях сервер будет отправлять клиенту уведомления.

deno/testModule

Когда сервер обнаруживает модуль, содержащий тесты, он уведомляет клиента, отправляя уведомление deno/testModule с данными TestModuleParams.

Структура Deno устроена следующим образом:

Модуль может содержать n тестов.
Тест может содержать n шагов.
Шаг может содержать n шагов.

При статическом анализе тестового модуля Deno пытается обнаружить все тесты и шаги тестов. Из-за динамического способа объявления тестов в Deno их не всегда можно обнаружить статически; некоторые тесты можно выявить только при выполнении модуля. Уведомление предназначено для обработки обоих случаев при обновлении данных клиента. Если тесты обнаружены статически, уведомление kind будет иметь значение "replace"; если тесты или шаги обнаружены во время выполнения, уведомление kind будет иметь значение "insert".

Когда тестовый документ редактируется в редакторе и поступают уведомления textDocument/didChange от клиента, сервер выполняет статический анализ этих изменений и уведомляет клиента, если тесты изменились.

Получив уведомление "replace", клиент может безопасно «заменить» представление тестового модуля. Получив "insert", клиент должен рекурсивно попытаться добавить данные к существующим представлениям.

Для тестовых модулей в качестве уникального идентификатора любого представления следует использовать textDocument.uri (это строковый URL уникального модуля). Элементы TestData содержат уникальную строку id. Эта строка id представляет собой хеш SHA-256 идентификационной информации, которую сервер отслеживает для теста.

interface TestData {
  /** The unique ID for this test/step. */
  id: string;

  /** The display label for the test/step. */
  label: string;

  /** Any test steps that are associated with this test/step */
  steps?: TestData[];

  /** The range of the owning text document that applies to the test. */
  range?: Range;
}

interface TestModuleParams {
  /** The text document identifier that the tests are related to. */
  textDocument: TextDocumentIdentifier;

  /** A indication if tests described are _newly_ discovered and should be
   * _inserted_ or if the tests associated are a replacement for any existing
   * tests. */
  kind: "insert" | "replace";

  /** The text label for the test module. */
  label: string;

  /** An array of tests that are owned by this test module. */
  tests: TestData[];
}

deno/testModuleDelete

Если наблюдаемый сервером тестовый модуль удален, сервер отправляет уведомление deno/testModuleDelete. Получив это уведомление, клиент должен удалить представление тестового модуля и все вложенные в него тесты и шаги тестов.

interface TestModuleDeleteParams {
  /** The text document identifier that has been removed. */
  textDocument: TextDocumentIdentifier;
}

deno/testRunProgress

Когда клиент отправляет запрос deno/testRun, сервер сообщает о ходе выполнения тестов с помощью уведомления deno/testRunProgress.

Клиенту следует обрабатывать эти сообщения и обновлять соответствующее представление в пользовательском интерфейсе.

Изменение состояния отображается в свойстве .message.kind объекта TestRunProgressParams. Возможны следующие состояния:

"enqueued" — тест или шаг теста добавлен в очередь на выполнение.
"skipped" — тест или шаг теста пропущен. Это происходит, если для теста Deno задан параметр ignore со значением true.
"started" — тест или шаг теста начат.
"passed" — тест или шаг теста успешно пройден.
"failed" — тест или шаг теста завершился неудачно. Это состояние предназначено для обозначения ошибки тестового окружения, а не самого теста, но в настоящее время Deno не поддерживает это различие.
"errored" — при выполнении теста или шага теста произошла ошибка. Дополнительные сведения об ошибке находятся в свойстве .message.messages.
"end" — выполнение тестов завершено.

interface TestIdentifier {
  /** The test module the message is related to. */
  textDocument: TextDocumentIdentifier;

  /** The optional ID of the test. If not present, then the message applies to
   * all tests in the test module. */
  id?: string;

  /** The optional ID of the step. If not present, then the message only applies
   * to the test. */
  stepId?: string;
}

interface TestMessage {
  /** The content of the message. */
  message: MarkupContent;

  /** An optional string which represents the expected output. */
  expectedOutput?: string;

  /** An optional string which represents the actual output. */
  actualOutput?: string;

  /** An optional location related to the message. */
  location?: Location;
}

interface TestEnqueuedStartedSkipped {
  /** The state change that has occurred to a specific test or test step.
   *
   * - `"enqueued"` - the test is now enqueued to be tested
   * - `"started"` - the test has started
   * - `"skipped"` - the test was skipped
   */
  type: "enqueued" | "started" | "skipped";

  /** The test or test step relating to the state change. */
  test: TestIdentifier;
}

interface TestFailedErrored {
  /** The state change that has occurred to a specific test or test step.
   *
   * - `"failed"` - The test failed to run properly, versus the test erroring.
   *   currently the Deno language server does not support this.
   * - `"errored"` - The test errored.
   */
  type: "failed" | "errored";

  /** The test or test step relating to the state change. */
  test: TestIdentifier;

  /** Messages related to the state change. */
  messages: TestMessage[];

  /** An optional duration, in milliseconds from the start to the current
   * state. */
  duration?: number;
}

interface TestPassed {
  /** The state change that has occurred to a specific test or test step. */
  type: "passed";

  /** The test or test step relating to the state change. */
  test: TestIdentifier;

  /** An optional duration, in milliseconds from the start to the current
   * state. */
  duration?: number;
}

interface TestOutput {
  /** The test or test step has output information / logged information. */
  type: "output";

  /** The value of the output. */
  value: string;

  /** The associated test or test step if there was one. */
  test?: TestIdentifier;

  /** An optional location associated with the output. */
  location?: Location;
}

interface TestEnd {
  /** The test run has ended. */
  type: "end";
}

type TestRunProgressMessage =
  | TestEnqueuedStartedSkipped
  | TestFailedErrored
  | TestPassed
  | TestOutput
  | TestEnd;

interface TestRunProgressParams {
  /** The test run ID that the progress message applies to. */
  id: number;

  /** The message*/
  message: TestRunProgressMessage;
}

Запросы тестирования

Сервер обрабатывает два типа запросов:

deno/testRun

Чтобы запросить выполнение набора тестов, клиент отправляет запрос deno/testRun, содержащий идентификатор запуска тестов, который будет использоваться в последующих ответах клиенту, тип запуска тестов, а также тестовые модули или тесты, которые нужно включить или исключить.

В настоящее время Deno поддерживает только тип запуска тестов "run". Поддержка типов "debug" и "coverage" планируется в будущем.

Если тестовые модули или тесты не включены в запрос, предполагается, что нужно выполнить все обнаруженные тестовые модули и тесты. Если тестовый модуль включен, но идентификаторы тестов не указаны, предполагается, что нужно включить все тесты в этом модуле. После обнаружения всех тестов исключенные тесты удаляются, а разрешенный набор тестов возвращается в ответе как "enqueued".

С помощью этого API нельзя включать или исключать шаги тестов из-за динамического характера их объявления и выполнения.

interface TestRunRequestParams {
  /** The id of the test run to be used for future messages. */
  id: number;

  /** The run kind. Currently Deno only supports `"run"` */
  kind: "run" | "coverage" | "debug";

  /** Test modules or tests to exclude from the test run. */
  exclude?: TestIdentifier[];

  /** Test modules or tests to include in the test run. */
  include?: TestIdentifier[];
}

interface EnqueuedTestModule {
  /** The test module the enqueued test IDs relate to */
  textDocument: TextDocumentIdentifier;

  /** The test IDs which are now enqueued for testing */
  ids: string[];
}

interface TestRunResponseParams {
  /** Test modules and test IDs that are now enqueued for testing. */
  enqueued: EnqueuedTestModule[];
}

deno/testRunCancel

Чтобы отменить выполняющийся запуск тестов, клиент отправляет запрос deno/testRunCancel с идентификатором теста для отмены. В ответ возвращается логическое значение true, если тест отменен, или false, если отменить его не удалось. Во время отмены теста продолжают отправляться соответствующие уведомления о ходе выполнения.

interface TestRunCancelParams {
  /** The test id to be cancelled. */
  id: number;
}