Проблемы

sdk.problems предоставляет данные для Problems: расширение сообщает об обнаруженных проблемах — вместе с решениями, которые пользователь может применить в один клик.

Регистрация

report(input: SdkProblemInput): Promise<SdkProblemHandle | undefined>

| Поле | Обязательно | Описание | | --- | --- | --- | | code | да | Машиночитаемый код проблемы. Не может быть пустым. | | message | да | Короткое человекочитаемое описание. Не может быть пустым. | | severity | да | ProblemSeverity: HINT, INFO, WARNING, ERROR. | | solutions | да | Массив решений — минимум одно. | | id | | Стабильный id. По умолчанию — сгенерированный uuid. | | description | | Развёрнутое пояснение. | | source | | Откуда проблема. По умолчанию — displayName вашего расширения или его id. | | tags | | Строки для группировки и фильтрации. | | metadata | | Любые дополнительные данные (Dictionary). |

Вызов report завершается с ошибкой, если code или message пустые, если solutions пуст или если проблема с таким id уже существует. Чтобы получить актуальную информацию о проблеме, сначала вызовите remove, затем снова report.

Решения

Решение — { id?, title, description?, execute }:

| Поле | Обязательно | Описание | | --- | --- | --- | | title | да | Название действия. | | execute | да | () => undefined \| boolean \| Promise<undefined \| boolean> — выполняется, когда пользователь выбирает решение. | | id | | Стабильный id. По умолчанию — сгенерированный uuid. | | description | | Что делает решение. |

execute не принимает аргументов. Верните true, чтобы отметить проблему как решённую, Fragmenta удалит её автоматически. Любой другой результат — false, undefined или ошибка — оставляет проблему на месте.

Дескриптор

report резолвится в SdkProblemHandle:

| Элемент | Описание | | --- | --- | | id | ProblemId зарегистрированной проблемы. | | remove() | Удаляет проблему. Резолвится в true, если она ещё существовала. | | dispose() | То же, что remove(), без ожидания — handle можно положить в context.subscriptions. |

Проблемы, о которых сообщило ваше расширение, удаляются автоматически при его деактивации.

const handle = await sdk.problems.report({
  code: 'docker-not-running',
  message: 'Docker не запущен',
  severity: ProblemSeverity.ERROR,
  solutions: [
    {
      title: 'Проверить ещё раз',
      // true решает проблему и удаляет её
      execute: async () => (await sdk.docker.isDockerInstalled()) !== false,
    },
  ],
})

// позже, если проблема решилась другим путём:
await handle?.remove()

interface SdkProblemInput {
  readonly id?: string
  readonly code: string
  readonly message: string
  readonly description?: string
  readonly severity: ProblemSeverity
  readonly source?: string
  readonly tags?: ReadonlyArray<string>
  readonly metadata?: Dictionary
  readonly solutions: ReadonlyArray<SdkProblemSolutionInput>
}

interface SdkProblemSolutionInput {
  readonly id?: string
  readonly title: string
  readonly description?: string
  readonly execute: () => undefined | boolean | Promise<undefined | boolean>
}

interface SdkProblemHandle extends IDisposable {
  readonly id: ProblemId
  remove(): Promise<boolean>
}

enum ProblemSeverity {
  HINT = 'HINT',
  INFO = 'INFO',
  WARNING = 'WARNING',
  ERROR = 'ERROR',
}

Управление

remove(id: ProblemId): Promise<boolean>
clear(): Promise<void>
list(): Promise<ReadonlyArray<SdkProblemDescriptor>>
applySolution(problemId: ProblemId, solutionId: SolutionId): Promise<boolean>

| Метод | Описание | | --- | --- | | remove(id) | Удаляет проблему по id. Резолвится в true, если она существовала. Работает с любой проблемой в IDE, не только с вашими. | | clear() | Удаляет проблемы, зарегистрированные через report(). | | list() | Все проблемы, которые сейчас есть в Problems, — от IDE и от всех расширений. | | applySolution(problemId, solutionId) | Выполняет решение любой проблемы. Резолвится в true, только если решение решило проблему — тогда она удаляется; false — если проблемы или решения нет или решение её не решило. |

list() и onDidAdd возвращают дескрипторы — данные о проблеме без execute плюс время добавления проблемы:

interface SdkProblemDescriptor {
  readonly id: ProblemId
  readonly code: string
  readonly message: string
  readonly description?: string
  readonly severity: ProblemSeverity
  readonly source?: string
  readonly tags?: ReadonlyArray<string>
  readonly metadata?: Dictionary
  readonly createdAt: number // мс с начала эпохи
  readonly solutions: ReadonlyArray<SdkSolutionDescriptor>
}

interface SdkSolutionDescriptor {
  readonly id: SolutionId
  readonly title: string
  readonly description?: string
}

События

События глобальные: они срабатывают для проблем от IDE и от всех расширений.

| Событие | Payload | Когда срабатывает | | --- | --- | --- | | onDidAdd | SdkProblemDescriptor | Проблема добавлена. | | onDidRemove | ProblemId | Проблема удалена — в том числе каждая, удалённая через clear() или решением, которое её решило. | | onDidClear | — | Весь список проблем очищен разом. clear() его не вызывает. | | onDidChange | — | После любого добавления, удаления или очистки. |