// Copyright 2025 The Go Authors. All rights reserved.
// Use of this source code is governed by a BSD-style
// license that can be found in the LICENSE file.

// This file defines types for an experimental feature (golang/go#76331,
// microsoft/language-server-protocol#1164). As an experimental feature,
// these types are not yet included in tsprotocol.go.

package protocol

import "encoding/json"

// FormFieldTypeString defines a text input.
//
// It is defined as a struct to allow for future extensibility, such as
// adding regex validation or file URI constraints.
type FormFieldTypeString struct {
	// Kind must be "string".
	Kind string `json:"kind"`
}

// FileExistence whether the file denoted by a DocumentURI exists.
//
// It is a bit set allowing combinations of existence states. For
// example, New|Existing allows either state.
type FileExistence uint32

const (
	// New indicates that file has not yet been created.
	FileExistenceNew FileExistence = 1 << 0
	// Existing indicates that the file exists already.
	FileExistenceExisting FileExistence = 1 << 1
)

// FileType represents the expected filesystem resource type.
//
// It is a bit set allowing combinations of file types. For example, Regular|Directory
// allows either types.
type FileType uint32

const (
	// Regular indicates the resource could be a regular file.
	FileTypeRegular FileType = 1 << 0
	// Directory indicates the resource could be a directory.
	FileTypeDirectory FileType = 1 << 1
)

// FormFieldTypeFile defines an input for a file or directory URI.
//
// The client determines the best mechanism to collect this information from
// the user (e.g., a graphical file picker, a text input with autocomplete, etc).
//
// The value returned by the client must be a valid "DocumentUri" as defined
// in the LSP specification:
// https://microsoft.github.io/language-server-protocol/specifications/lsp/3.17/specification/#documentUri
type FormFieldTypeFile struct {
	// Kind must be "file".
	Kind string `json:"kind"`

	// Existence constraint.
	Existence FileExistence `json:"existence"`

	// Type specifies the set of allowed file types (regular file, directory, etc).
	//
	// Only applicable against existing file.
	Type FileType `json:"type"`
}

// FormFieldTypeBool defines a boolean input.
type FormFieldTypeBool struct {
	// Kind must be "bool".
	Kind string `json:"kind"`
}

// FormFieldTypeNumber defines a numeric input.
//
// It is defined as a struct to allow for future extensibility, such as
// adding range constraints (min/max) or precision requirements.
type FormFieldTypeNumber struct {
	// Kind must be "number".
	Kind string `json:"kind"`
}

// FormEnumEntry represents a single option in an enumeration.
type FormEnumEntry struct {
	// Value is the unique string identifier for this option.
	//
	// This is the value that will be sent back to the server in
	// 'FormAnswers' if the user selects this option.
	Value string `json:"value"`

	// Description is the human-readable label presented to the user.
	Description string `json:"description"`
}

// FormFieldTypeEnum defines a selection from a set of values.
//
// Use this type when:
// - The number of options is small (e.g., < 20).
// - All options are known at the time the form is created.
type FormFieldTypeEnum struct {
	// Kind must be "enum".
	Kind string `json:"kind"`

	// Entries is the list of allowable options.
	Entries []FormEnumEntry `json:"entries"`
}

// FormFieldTypeLazyEnum defines a selection from a large or dynamic enum entry set.
//
// Use this type when:
//  1. The dataset is too large to send efficiently in a single payload
//     (e.g., thousands of workspace symbols, file uri or cloud resources).
//  2. The available options depend on the user's input (e.g., semantic search).
//  3. Generating the list is expensive and should only be done if requested.
//
// The client is expected to render a search interface (e.g., a combo box with
// a text input) and query the server via 'interactive/listEnum' as the user types.
type FormFieldTypeLazyEnum struct {
	// Kind must be "lazyEnum".
	Kind string `json:"kind"`

	// TODO(hxjiang): consider make debounce configurable since fetching
	// cloud resources could be expensive and slow.

	// Source identifies the data source on the server.
	//
	// Examples: "workspace/symbol", "database/schema", "git/tags".
	Source string `json:"source"`

	// Config contains the static settings for the source.
	// The client treats this as opaque data and echoes it back in the
	// 'interactive/listEnum' request.
	Config json.RawMessage `json:"config,omitempty"`
}

// FormFieldTypeList defines a homogeneous list of items.
type FormFieldTypeList struct {
	// Kind must be "list".
	Kind string `json:"kind"`

	// ElementType specifies the type of the items in the list.
	// It must be one of the FormFieldType* structs (e.g., FormFieldTypeString).
	ElementType any `json:"elementType"`
}

// FormField describes a single question in a form and its validation state.
type FormField struct {
	// Description is the text content of the question (the prompt) presented
	// to the user.
	Description string `json:"description"`

	// Type specifies the data type and validation constraints for the answer.
	//
	// It must be one of the FormFieldType* structs. The Kind field within the
	// struct determines the expected data type.
	//
	// The language client is expected to render an input appropriate for this
	// type. If the client does not support the specified type, it should
	// fall back to a string input.
	Type any `json:"type"`

	// Default specifies an optional initial value for the answer.
	//
	// If Type is FormFieldTypeEnum, this value must be present in the enum's
	// Values slice.
	Default any `json:"default,omitempty"`

	// Error provides a validation message from the language server.
	// If empty, the current answer is considered valid.
	Error string `json:"error,omitempty"`
}

// InteractiveParams facilitates a multi-step, interactive dialogue between the
// client and server during a Language Server Protocol (LSP) request.
//
// It implements a non-standard protocol extension microsoft/language-server-protocol#1164
// . By embedding this type into standard request parameters (such as
// [ExecuteCommandParams] or [RenameParams]) and pairing them with dedicated
// resolution methods (like [Server.ResolveCommand] or other ResolveXXX handlers),
// standard operations can be transformed into interactive workflows.
//
// Standard LSP resolution methods (like "codeAction/resolve") cannot be used
// for these interactive forms because editors often trigger them eagerly to
// render previews, which would prematurely present UI forms to the user.
// The dedicated ResolveXXX pattern ensures the interactive dialogue strictly
// begins only *after* the user has explicitly indicated intent (for example,
// by clicking a specific Code Action).
//
// The following sequence illustrates the typical handshake, using a code action
// that resolves to a command as an example:
//
//  1. The client requests code actions for the current text selection.
//  2. The server responds with a code action containing a standard LSP Command
//     (title, command, and arguments).
//  3. The client calls [Server.ResolveCommand] with the initial command details
//     wrapped in an [ExecuteCommandParams] to determine if the execution requires
//     interactive input.
//  4. The server responds with an [ExecuteCommandParams]. If user input is
//     required, the server populates the FormFields array with the required schema.
//  5. The client observes the non-empty FormFields and presents a corresponding
//     user interface.
//  6. The user submits their input, and the client issues another
//     [Server.ResolveCommand] request, this time populating the FormAnswers array.
//  7. The server validates the answers. If invalid, it returns a form with error
//     messages attached to specific FormFields. Steps 5-7 repeat until the server
//     omits FormFields entirely, indicating the answers are valid and complete.
//  8. The client calls [Server.ExecuteCommand] with the finalized FormAnswers to
//     execute the action.
//
// The server populates FormFields to define the input schema. If FormFields is
// omitted or empty, the interactive phase is considered complete and the provided
// FormAnswers have been fully validated.
//
// The server may optionally populate FormAnswers alongside FormFields to preserve
// previous user input or provide default values for the client to render.
type InteractiveParams struct {
	// FormFields defines the questions and validation errors in previous
	// answers to the same questions.
	//
	// This is a server-to-client field. The language server defines these, and
	// the client uses them to render the form.
	//
	// The interactive phase is considered complete when the server returns a
	// response where this slice is omitted.
	//
	// Note: This is a non-standard protocol extension. See microsoft/language-server-protocol#1164.
	FormFields []FormField `json:"formFields,omitempty"`

	// FormAnswers contains the values for the form questions.
	//
	// When sent by the language server, this field is optional but recommended
	// to support editing previous values.
	//
	// When sent by the language client as part of the ResolveXXX request, this
	// field is required. The slice must have the same length as FormFields (one
	// answer per question), where the answer at index i corresponds to the
	// field at index i.
	//
	// Note: This is a non-standard protocol extension. See microsoft/language-server-protocol#1164.
	FormAnswers []any `json:"formAnswers,omitempty"`
}

// InteractiveListEnumParams defines the parameters for the
// 'interactive/listEnum' request.
type InteractiveListEnumParams struct {
	// Source identifies the data source on the server.
	//
	// The client treats this as opaque data and echoes it back in the
	// 'interactive/listEnum' request.
	//
	// Examples: "workspace/symbol", "database/schema", "git/tags".
	Source string `json:"source"`

	// Config contains the static settings for the specified source.
	//
	// The client treats this as opaque data and echoes it back in the
	// 'interactive/listEnum' request.
	Config json.RawMessage `json:"config,omitempty"`

	// A query string to filter enum entries by.
	//
	// The exact interpretation of this string (e.g., fuzzy matching, exact
	// match, prefix search, or regular expression) is entirely up to the
	// server and may vary depending on the source. This follows the similar
	// semantics as the standard 'workspace/symbol' request. Clients may
	// send an empty string here to request a default set of enum entries.
	Query string `json:"query"`
}