laburnum 1.17.1

// Copyright Two Neutron Stars Incorporated and contributors
// SPDX-License-Identifier: BlueOak-1.0.0

//! Corresponds to the [Basic JSON Structure] section of the specification.
//!
//! [Basic JSON Structure]: https://microsoft.github.io/language-server-protocol/specifications/lsp/3.17/specification/#basicJsonStructures

use {
  crate::{
    Uri,
    protocol::{
      lsp::{
        ChangeAnnotationIdentifier,
        DocumentChanges,
        NumberOrString,
        OneOf,
        TextEdit,
        WorkspaceFolder,
      },
      macros::lsp_enum,
    },
  },
  serde::{
    Deserialize,
    Serialize,
  },
  std::collections::HashMap,
};

// URI
// See module `laburnum::uri`.

// Regular Expression

/// Client capabilities specific to regular expressions.
#[derive(Debug, Default, Clone, PartialEq, Eq, Deserialize, Serialize)]
#[serde(rename_all = "camelCase")]
pub struct RegularExpressionsClientCapabilities {
  /// The engine's name.
  pub engine: String,

  /// The engine's version
  #[serde(skip_serializing_if = "Option::is_none")]
  pub version: Option<String>,
}

// Text Documents

// Position

/// Position in a text document expressed as zero-based line and character
/// offset. A position is between two characters like an `insert` cursor in a
/// editor.
#[derive(
  Debug,
  Clone,
  Copy,
  Default,
  PartialEq,
  Eq,
  PartialOrd,
  Ord,
  Hash,
  Deserialize,
  Serialize,
)]
pub struct Position {
  /// Line position in a document (zero-based).
  pub line:      u32,
  /// Character offset on a line in a document (zero-based). The meaning of
  /// this offset is determined by the negotiated `PositionEncodingKind`.
  ///
  /// If the character value is greater than the line length it defaults back
  /// to the line length.
  pub character: u32,
}

impl Position {
  #[must_use]
  pub const fn new(line: u32, character: u32) -> Self {
    Self { line, character }
  }
}

/// A type indicating how positions are encoded,
/// specifically what column offsets mean.
///
/// @since 3.17.0
#[derive(
  Debug, Clone, PartialEq, Eq, PartialOrd, Deserialize, Serialize, Hash,
)]
pub struct PositionEncodingKind(std::borrow::Cow<'static, str>);

impl PositionEncodingKind {
  /// Character offsets count UTF-16 code units.
  ///
  /// This is the default and must always be supported
  /// by servers
  pub const UTF16: Self = Self::new("utf-16");

  /// The LSP-specified default encoding (UTF-16).
  ///
  /// Per the LSP specification, if no encoding is negotiated during
  /// initialization, UTF-16 must be assumed.
  pub const DEFAULT: Self = Self::UTF16;
  /// Character offsets count UTF-32 code units.
  ///
  /// Implementation note: these are the same as Unicode code points,
  /// so this `PositionEncodingKind` may also be used for an
  /// encoding-agnostic representation of character offsets.
  pub const UTF32: Self = Self::new("utf-32");
  /// Character offsets count UTF-8 code units.
  pub const UTF8: Self = Self::new("utf-8");

  #[must_use]
  pub const fn new(tag: &'static str) -> Self {
    Self(std::borrow::Cow::Borrowed(tag))
  }

  #[must_use]
  pub fn as_str(&self) -> &str {
    &self.0
  }
}

impl From<String> for PositionEncodingKind {
  fn from(from: String) -> Self {
    Self(std::borrow::Cow::from(from))
  }
}

impl From<&'static str> for PositionEncodingKind {
  fn from(from: &'static str) -> Self {
    Self::new(from)
  }
}

// Range

/// A range in a text document expressed as (zero-based) start and end
/// positions. A range is comparable to a selection in an editor. Therefore the
/// end position is exclusive.
#[derive(
  Debug, Default, Clone, Copy, PartialEq, Eq, Deserialize, Serialize, Hash,
)]
pub struct Range {
  /// The range's start position.
  pub start: Position,
  /// The range's end position.
  pub end:   Position,
}

impl Range {
  #[must_use]
  pub const fn new(start: Position, end: Position) -> Self {
    Self { start, end }
  }
}

// Patterns

/// The glob pattern to watch relative to the base path. Glob patterns can have
/// the following syntax:
/// - `*` to match one or more characters in a path segment
/// - `?` to match on one character in a path segment
/// - `**` to match any number of path segments, including none
/// - `{}` to group conditions (e.g. `**​/*.{ts,js}` matches all TypeScript and
///   JavaScript files)
/// - `[]` to declare a range of characters to match in a path segment (e.g.,
///   `example.[0-9]` to match on `example.0`, `example.1`, …)
/// - `[!...]` to negate a range of characters to match in a path segment (e.g.,
///   `example.[!0-9]` to match on `example.a`, `example.b`, but not
///   `example.0`)
///
/// @since 3.17.0
pub type Pattern = String;

/// A relative pattern is a helper to construct glob patterns that are matched
/// relatively to a base URI. The common value for a `baseUri` is a workspace
/// folder root, but it can be another absolute URI as well.
///
/// @since 3.17.0
#[derive(
  Debug, Clone, PartialEq, Eq, PartialOrd, Ord, Deserialize, Serialize,
)]
#[serde(rename_all = "camelCase")]
pub struct RelativePattern {
  /// A workspace folder or a base URI to which this pattern will be matched
  /// against relatively.
  pub base_uri: OneOf<WorkspaceFolder, Uri>,
  /// The actual glob pattern.
  pub pattern:  Pattern,
}

/// The glob pattern. Either a string pattern or a relative pattern.
///
/// @since 3.17.0
#[derive(
  Debug, Clone, PartialEq, Eq, PartialOrd, Ord, Deserialize, Serialize,
)]
#[serde(untagged)]
pub enum GlobPattern {
  String(Pattern),
  Relative(RelativePattern),
}

impl From<Pattern> for GlobPattern {
  #[inline]
  fn from(from: Pattern) -> Self {
    Self::String(from)
  }
}

impl From<RelativePattern> for GlobPattern {
  #[inline]
  fn from(from: RelativePattern) -> Self {
    Self::Relative(from)
  }
}

/// Represents a location inside a resource, such as a line inside a text file.
#[derive(Debug, Clone, PartialEq, Eq, Deserialize, Serialize, Hash)]
pub struct Location {
  pub uri:   Uri,
  pub range: Range,
}

impl Location {
  #[must_use]
  pub const fn new(uri: Uri, range: Range) -> Self {
    Self { uri, range }
  }
}

// Location Link

/// Represents a link between a source and a target location.
#[derive(Debug, Clone, PartialEq, Eq, Deserialize, Serialize)]
#[serde(rename_all = "camelCase")]
pub struct LocationLink {
  /// Span of the origin of this link.
  ///
  /// Used as the underlined span for mouse interaction. Defaults to the word
  /// range at the mouse position.
  #[serde(skip_serializing_if = "Option::is_none")]
  pub origin_selection_range: Option<Range>,
  /// The target resource identifier of this link.
  pub target_uri:             Uri,
  /// The full target range of this link.
  pub target_range:           Range,
  /// The span of this link.
  pub target_selection_range: Range,
}

// Command

/// Represents a reference to a command. Provides a title which will be used to
/// represent a command in the UI.
///
/// Commands are identified by a string identifier. The recommended way to
/// handle commands is to implement their execution on the server side if the
/// client and server provides the corresponding capabilities. Alternatively the
/// tool extension code could handle the command. The protocol currently doesn’t
/// specify a set of well-known commands.
#[derive(Debug, Default, Clone, PartialEq, Eq, Deserialize, Serialize)]
pub struct Command {
  /// Title of the command, like `save`.
  pub title:     String,
  /// The identifier of the actual command handler.
  pub command:   String,
  /// Arguments that the command handler should be
  /// invoked with.
  #[serde(skip_serializing_if = "Option::is_none")]
  pub arguments: Option<Vec<serde_json::Value>>,
}

impl Command {
  #[must_use]
  pub const fn new(
    title: String,
    command: String,
    arguments: Option<Vec<serde_json::Value>>,
  ) -> Self {
    Self {
      title,
      command,
      arguments,
    }
  }
}

// MarkupContent

/// Describes the content type that a client supports in various
/// result literals like `Hover`, `ParameterInfo` or `CompletionItem`.
///
/// Please note that `MarkupKinds` must not start with a `$`. These kinds
/// are reserved for internal usage.
#[derive(Default, Debug, Clone, PartialEq, Eq, Deserialize, Serialize)]
#[serde(rename_all = "lowercase")]
pub enum MarkupKind {
  /// Plain text is supported as a content format.
  #[default]
  PlainText,
  /// Markdown is supported as a content format.
  Markdown,
}

/// A `MarkupContent` literal represents a string value whose content can be
/// represented in different formats.
///
/// Currently `plaintext` and `markdown` are supported formats. A
/// `MarkupContent` is usually used in documentation properties of result
/// literals like `CompletionItem` or `SignatureInformation`. If the format
/// is `markdown` the content should follow the [GitHub Flavored Markdown Specification](https://github.github.com/gfm/).
///
/// Here is an example how such a string can be constructed using JavaScript /
/// TypeScript:
///
/// ```typescript
/// let markdown: MarkupContent = {
///     kind: MarkupKind::Markdown,
///     value: [
///         "# Header",
///         "Some text",
///         "```typescript",
///         "someCode();",
///         "```"
///     ]
///     .join("\n"),
/// };
/// ```
///
/// Please *Note* that clients might sanitize the returned markdown. A client
/// could decide to remove HTML from the markdown to avoid script execution.
#[derive(Default, Debug, Clone, PartialEq, Eq, Deserialize, Serialize)]
pub struct MarkupContent {
  /// The type of the Markup.
  pub kind:  MarkupKind,
  /// The content itself
  pub value: String,
}

#[derive(Debug, Default, Clone, PartialEq, Eq, Deserialize, Serialize)]
#[serde(rename_all = "camelCase")]
pub struct MarkdownClientCapabilities {
  /// The name of the parser.
  pub parser: String,

  /// The version of the parser.
  #[serde(skip_serializing_if = "Option::is_none")]
  pub version: Option<String>,

  /// A list of HTML tags that the client allows / supports in
  /// Markdown.
  ///
  /// @since 3.17.0
  #[serde(skip_serializing_if = "Option::is_none")]
  pub allowed_tags: Option<Vec<String>>,
}

// File Resource changes

/// Options to create a file.
#[derive(Debug, Clone, PartialEq, Eq, Deserialize, Serialize)]
#[serde(rename_all = "camelCase")]
pub struct CreateFileOptions {
  /// Overwrite existing file. Overwrite wins over `ignoreIfExists`
  #[serde(skip_serializing_if = "Option::is_none")]
  pub overwrite:        Option<bool>,
  /// Ignore if exists.
  #[serde(skip_serializing_if = "Option::is_none")]
  pub ignore_if_exists: Option<bool>,
}

/// Create file operation
#[derive(Debug, Clone, PartialEq, Eq, Deserialize, Serialize)]
#[serde(rename_all = "camelCase")]
pub struct CreateFile {
  /// The resource to create.
  pub uri:     Uri,
  /// Additional options
  #[serde(skip_serializing_if = "Option::is_none")]
  pub options: Option<CreateFileOptions>,

  /// An optional annotation identifier describing the operation.
  ///
  /// @since 3.16.0
  #[serde(skip_serializing_if = "Option::is_none")]
  pub annotation_id: Option<ChangeAnnotationIdentifier>,
}

/// Rename file options
#[derive(Debug, Clone, PartialEq, Eq, Deserialize, Serialize)]
#[serde(rename_all = "camelCase")]
pub struct RenameFileOptions {
  /// Overwrite target if existing. Overwrite wins over `ignoreIfExists`
  #[serde(skip_serializing_if = "Option::is_none")]
  pub overwrite:        Option<bool>,
  /// Ignores if target exists.
  #[serde(skip_serializing_if = "Option::is_none")]
  pub ignore_if_exists: Option<bool>,
}

/// Rename file operation
#[derive(Debug, Clone, PartialEq, Eq, Deserialize, Serialize)]
#[serde(rename_all = "camelCase")]
pub struct RenameFile {
  /// The old (existing) location.
  pub old_uri: Uri,
  /// The new location.
  pub new_uri: Uri,
  /// Rename options.
  #[serde(skip_serializing_if = "Option::is_none")]
  pub options: Option<RenameFileOptions>,

  /// An optional annotation identifier describing the operation.
  ///
  /// @since 3.16.0
  #[serde(skip_serializing_if = "Option::is_none")]
  pub annotation_id: Option<ChangeAnnotationIdentifier>,
}

/// Delete file options
#[derive(Debug, Clone, PartialEq, Eq, Deserialize, Serialize)]
#[serde(rename_all = "camelCase")]
pub struct DeleteFileOptions {
  /// Delete the content recursively if a folder is denoted.
  #[serde(skip_serializing_if = "Option::is_none")]
  pub recursive:            Option<bool>,
  /// Ignore the operation if the file doesn't exist.
  #[serde(skip_serializing_if = "Option::is_none")]
  pub ignore_if_not_exists: Option<bool>,
}

/// Delete file operation
#[derive(Debug, Clone, PartialEq, Eq, Deserialize, Serialize)]
#[serde(rename_all = "camelCase")]
pub struct DeleteFile {
  /// The file to delete.
  pub uri:     Uri,
  /// Delete options.
  #[serde(skip_serializing_if = "Option::is_none")]
  pub options: Option<DeleteFileOptions>,

  /// An optional annotation identifier describing the operation.
  ///
  /// @since 3.16.0
  #[serde(skip_serializing_if = "Option::is_none")]
  pub annotation_id: Option<ChangeAnnotationIdentifier>,
}

#[derive(Debug, Default, Clone, PartialEq, Eq, Deserialize, Serialize)]
#[serde(rename_all = "camelCase")]
pub struct WorkspaceEditClientCapabilities {
  /// The client supports versioned document changes in `WorkspaceEdit`s
  #[serde(skip_serializing_if = "Option::is_none")]
  pub document_changes: Option<bool>,

  /// The resource operations the client supports. Clients should at least
  /// support `create`, `rename` and `delete` files and folders.
  #[serde(skip_serializing_if = "Option::is_none")]
  pub resource_operations: Option<Vec<ResourceOperationKind>>,

  /// The failure handling strategy of a client if applying the workspace edit
  /// fails.
  #[serde(skip_serializing_if = "Option::is_none")]
  pub failure_handling: Option<FailureHandlingKind>,

  /// Whether the client normalizes line endings to the client specific
  /// setting.
  /// If set to `true` the client will normalize line ending characters
  /// in a workspace edit to the client specific new line character(s).
  ///
  /// @since 3.16.0
  #[serde(skip_serializing_if = "Option::is_none")]
  pub normalizes_line_endings: Option<bool>,

  /// Whether the client in general supports change annotations on text edits,
  /// create file, rename file and delete file changes.
  ///
  /// @since 3.16.0
  #[serde(skip_serializing_if = "Option::is_none")]
  pub change_annotation_support:
    Option<ChangeAnnotationWorkspaceEditClientCapabilities>,

  /// Whether the client supports `WorkspaceEditMetadata` in `WorkspaceEdit`s.
  ///
  /// @since 3.18.0
  /// @proposed
  #[serde(skip_serializing_if = "Option::is_none")]
  pub metadata_support: Option<bool>,

  /// Whether the client supports snippets as text edits.
  ///
  /// @since 3.18.0
  /// @proposed
  #[serde(skip_serializing_if = "Option::is_none")]
  pub snippet_edit_support: Option<bool>,
}

#[derive(Debug, Default, Clone, PartialEq, Eq, Deserialize, Serialize)]
#[serde(rename_all = "camelCase")]
pub struct ChangeAnnotationWorkspaceEditClientCapabilities {
  /// Whether the client groups edits with equal labels into tree nodes,
  /// for instance all edits labelled with "Changes in Strings" would
  /// be a tree node.
  #[serde(skip_serializing_if = "Option::is_none")]
  pub groups_on_label: Option<bool>,
}

/// The kind of resource operations supported by the client.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Deserialize, Serialize)]
#[serde(rename_all = "lowercase")]
pub enum ResourceOperationKind {
  /// Supports creating new files and folders.
  Create,
  /// Supports renaming existing files and folders.
  Rename,
  /// Supports deleting existing files and folders.
  Delete,
}

#[derive(Debug, Clone, Copy, PartialEq, Eq, Deserialize, Serialize)]
#[serde(rename_all = "camelCase")]
pub enum FailureHandlingKind {
  /// Applying the workspace change is simply aborted if one of the changes
  /// provided fails. All operations executed before the failing operation
  /// stay executed.
  Abort,
  /// All operations are executed transactionally. That means they either all
  /// succeed or no changes at all are applied to the workspace.
  Transactional,
  /// If the workspace edit contains only textual file changes they are
  /// executed transactionally. If resource changes (create, rename or delete
  /// file) are part of the change the failure handling strategy is abort.
  TextOnlyTransactional,
  /// The client tries to undo the operations already executed. But there is
  /// no guarantee that this is succeeding.
  Undo,
}

// Work Done Progress
// Client Initiated Progress
// Server Initiated Progress
// Partial Result Progress
// Partial Result Params
//
// See module `laburnum::protocol::lsp::progress`.

// Trace Value

/// A `TraceValue` represents the level of verbosity with which the server
/// systematically reports its execution trace using `LogTrace` notifications.
///
/// The initial trace value is set by the client at initialization and can be
/// modified later using the `SetTrace` notification.
#[derive(
  Debug, Default, Clone, Copy, PartialEq, Eq, Deserialize, Serialize,
)]
#[serde(rename_all = "camelCase")]
pub enum TraceValue {
  /// The server should not send any `$/logTrace` notification
  #[default]
  Off,
  /// The server should not add the 'verbose' field in the `LogTraceParams`
  Messages,
  Verbose,
}