From be3b9274275bd6dc3654c76679d2b9778d4636e4 Mon Sep 17 00:00:00 2001 From: Quentin Pradet Date: Mon, 17 Nov 2025 15:14:51 +0400 Subject: [PATCH 1/2] Configure UpdateForV10 tag with eslint-plugin-jsdoc We sometimes want to make breaking changes but have to wait until the next major version. To not forget about those, this commit introduces an UpdateForV10 JSDoc tag that can be used in any commment. There are a few benefits of using JSDoc instead of a simple TODO comment: * With the allowlist of tags in our eslint config, we can't make typos * We enforce a proper description to explain why the breaking change needs to be made Note that this tag has the same name as the Elasticsearch UpdateForV10 annotation, as we'll migrate to Elasticsearch in the future. --- docs/modeling-guide.md | 9 + specification/_global/index/IndexRequest.ts | 4 +- .../search_template/SearchTemplateRequest.ts | 3 +- .../update_by_query/UpdateByQueryResponse.ts | 12 +- specification/_spec_utils/UserDefinedValue.ts | 6 +- specification/_types/Knn.ts | 12 +- specification/_types/Retriever.ts | 14 +- specification/_types/TokenPruningConfig.ts | 9 +- .../_types/aggregations/Aggregate.ts | 3 +- .../aggregations/AggregationContainer.ts | 1 - specification/_types/analysis/StopWords.ts | 2 +- .../_types/analysis/token_filters.ts | 111 +++++--- .../_types/query_dsl/TextExpansionQuery.ts | 3 +- specification/_types/query_dsl/compound.ts | 3 +- specification/cat/_types/CatBase.ts | 23 +- .../CatComponentTemplatesRequest.ts | 3 +- .../CatDataFrameAnalyticsRequest.ts | 3 +- .../cat/transforms/CatTransformsRequest.ts | 3 +- specification/ccr/_types/FollowIndexStats.ts | 3 +- .../GetAutoFollowPatternRequest.ts | 3 +- .../cluster/stats/ClusterStatsRequest.ts | 3 +- specification/eslint.config.js | 242 +++++++++++------- .../IndicesPutDataStreamMappingsRequest.ts | 3 +- .../IndicesPutDataStreamSettingsRequest.ts | 3 +- .../put_settings/IndicesPutSettingsRequest.ts | 3 +- .../IndicesSimulateIndexTemplateRequest.ts | 3 +- .../put_hugging_face/PutHuggingFaceRequest.ts | 2 +- .../put_voyageai/PutVoyageAIRequest.ts | 22 +- .../PutGeoipDatabaseRequest.ts | 3 +- specification/ml/_types/Authorization.ts | 9 +- specification/ml/_types/Bucket.ts | 3 +- specification/ml/_types/CalendarEvent.ts | 6 +- specification/ml/_types/Datafeed.ts | 3 +- specification/ml/_types/TrainedModel.ts | 3 +- specification/ml/_types/inference.ts | 12 +- .../MlGetCalendarEventsRequest.ts | 6 +- .../ml/get_calendars/MlGetCalendarsRequest.ts | 6 +- specification/package-lock.json | 237 +++++++++++++++-- specification/package.json | 3 +- .../GetServiceCredentialsResponse.ts | 3 +- .../security/has_privileges/types.ts | 6 +- .../security/oidc_authenticate/Request.ts | 3 +- .../FindMessageStructureRequest.ts | 3 +- .../put_transform/PutTransformRequest.ts | 3 +- 44 files changed, 587 insertions(+), 233 deletions(-) diff --git a/docs/modeling-guide.md b/docs/modeling-guide.md index 73db4512a5..569c95ca5f 100644 --- a/docs/modeling-guide.md +++ b/docs/modeling-guide.md @@ -785,3 +785,12 @@ class Foo { #### `@stability` and `@visibility` These annotations have been removed, use `@availability` instead. + +#### `@UpdateForV10` + +We sometimes want to make breaking changes but have to wait until the next major version. +To not forget about those change, you can use the UpdateForV10 JSDoc tag in any commment. +There are a few benefits of using JSDoc instead of a simple TODO comment: + + * With the allowlist of tags in our eslint config, we can't make typos + * We enforce a proper description to explain why the breaking change needs to be made \ No newline at end of file diff --git a/specification/_global/index/IndexRequest.ts b/specification/_global/index/IndexRequest.ts index 6a4dae61ec..9b01acb328 100644 --- a/specification/_global/index/IndexRequest.ts +++ b/specification/_global/index/IndexRequest.ts @@ -146,12 +146,14 @@ import { Duration } from '@_types/Time' * "id": "elkbee" * } * } - * + * ``` + * * In this example, the operation will succeed since the supplied version of 2 is higher than the current document version of 1. * If the document was already updated and its version was set to 2 or higher, the indexing command will fail and result in a conflict (409 HTTP status code). * * A nice side effect is that there is no need to maintain strict ordering of async indexing operations run as a result of changes to a source database, as long as version numbers from the source database are used. * Even the simple case of updating the Elasticsearch index using data from a database is simplified if external versioning is used, as only the latest version will be used if the index operations arrive out of order. + * * @rest_spec_name index * @availability stack stability=stable * @availability serverless stability=stable visibility=public diff --git a/specification/_global/search_template/SearchTemplateRequest.ts b/specification/_global/search_template/SearchTemplateRequest.ts index e50e784834..640aadcb6d 100644 --- a/specification/_global/search_template/SearchTemplateRequest.ts +++ b/specification/_global/search_template/SearchTemplateRequest.ts @@ -122,7 +122,8 @@ export interface Request extends RequestBase { */ scroll?: Duration /** - * The type of the search operation. */ + * The type of the search operation. + */ search_type?: SearchType /** * If `true`, `hits.total` is rendered as an integer in the response. diff --git a/specification/_global/update_by_query/UpdateByQueryResponse.ts b/specification/_global/update_by_query/UpdateByQueryResponse.ts index 7a8488fcbe..af7a8e86be 100644 --- a/specification/_global/update_by_query/UpdateByQueryResponse.ts +++ b/specification/_global/update_by_query/UpdateByQueryResponse.ts @@ -32,7 +32,8 @@ export class Response { * If this is non-empty then the request ended because of those failures. * Update by query is implemented using batches. * Any failure causes the entire process to end, but all failures in the current batch are collected into the array. - * You can use the `conflicts` option to prevent reindex from ending when version conflicts occur. */ + * You can use the `conflicts` option to prevent reindex from ending when version conflicts occur. + */ failures?: BulkIndexByScrollFailure[] /** The number of documents that were ignored because the script used for the update by query returned a noop value for `ctx.op`. */ noops?: long @@ -43,7 +44,8 @@ export class Response { /** * The number of retries attempted by update by query. * `bulk` is the number of bulk actions retried. - * `search` is the number of search actions retried. */ + * `search` is the number of search actions retried. + */ retries?: Retries task?: TaskId /** If true, some requests timed out during the update by query. */ @@ -60,8 +62,10 @@ export class Response { /** The number of milliseconds the request slept to conform to `requests_per_second`. */ throttled_millis?: DurationValue throttled_until?: Duration - /** This field should always be equal to zero in an _update_by_query response. - * It only has meaning when using the task API, where it indicates the next time (in milliseconds since epoch) a throttled request will be run again in order to conform to `requests_per_second`. */ + /** + * This field should always be equal to zero in an _update_by_query response. + * It only has meaning when using the task API, where it indicates the next time (in milliseconds since epoch) a throttled request will be run again in order to conform to `requests_per_second`. + */ throttled_until_millis?: DurationValue } } diff --git a/specification/_spec_utils/UserDefinedValue.ts b/specification/_spec_utils/UserDefinedValue.ts index c87df54325..871cc535ab 100644 --- a/specification/_spec_utils/UserDefinedValue.ts +++ b/specification/_spec_utils/UserDefinedValue.ts @@ -17,6 +17,8 @@ * under the License. */ -/** Rather then documenting `object` this specifies places in the response that depend on the mapping and or request - * e.g the result of a script can be anything from value types to objects */ +/** + * Rather then documenting `object` this specifies places in the response that depend on the mapping and or request + * e.g the result of a script can be anything from value types to objects + */ export class UserDefinedValue {} diff --git a/specification/_types/Knn.ts b/specification/_types/Knn.ts index 541411301f..422cf4d27e 100644 --- a/specification/_types/Knn.ts +++ b/specification/_types/Knn.ts @@ -43,7 +43,8 @@ export interface KnnSearch { k?: integer /** The number of nearest neighbor candidates to consider per shard */ num_candidates?: integer - /** The percentage of vectors to explore per shard while doing knn search with bbq_disk + /** + * The percentage of vectors to explore per shard while doing knn search with bbq_disk * @availability stack since=9.2.0 * @availability serverless */ @@ -59,7 +60,8 @@ export interface KnnSearch { * @doc_id knn-inner-hits */ inner_hits?: InnerHits - /** Apply oversampling and rescoring to quantized vectors + /** + * Apply oversampling and rescoring to quantized vectors * @availability stack since=8.18.0 * @availability serverless */ @@ -78,7 +80,8 @@ export interface KnnQuery extends QueryBase { query_vector_builder?: QueryVectorBuilder /** The number of nearest neighbor candidates to consider per shard */ num_candidates?: integer - /** The percentage of vectors to explore per shard while doing knn search with bbq_disk + /** + * The percentage of vectors to explore per shard while doing knn search with bbq_disk * @availability stack since=9.2.0 * @availability serverless */ @@ -89,7 +92,8 @@ export interface KnnQuery extends QueryBase { filter?: QueryContainer | QueryContainer[] /** The minimum similarity for a vector to be considered a match */ similarity?: float - /** Apply oversampling and rescoring to quantized vectors + /** + * Apply oversampling and rescoring to quantized vectors * @availability stack since=8.18.0 * @availability serverless */ diff --git a/specification/_types/Retriever.ts b/specification/_types/Retriever.ts index afb6ac3214..d5b70076c1 100644 --- a/specification/_types/Retriever.ts +++ b/specification/_types/Retriever.ts @@ -124,14 +124,16 @@ export class KnnRetriever extends RetrieverBase { k: integer /** Number of nearest neighbor candidates to consider per shard. */ num_candidates: integer - /** The percentage of vectors to explore per shard while doing knn search with bbq_disk + /** + * The percentage of vectors to explore per shard while doing knn search with bbq_disk * @availability stack since=9.2.0 * @availability serverless */ visit_percentage?: float /** The minimum similarity required for a document to be considered a match. */ similarity?: float - /** Apply oversampling and rescoring to quantized vectors + /** + * Apply oversampling and rescoring to quantized vectors * @availability stack since=8.18.0 * @availability serverless */ @@ -144,7 +146,10 @@ export class KnnRetriever extends RetrieverBase { export class RRFRetrieverComponent { /** The nested retriever configuration. */ retriever: RetrieverContainer - /** Weight multiplier for this retriever's contribution to the RRF score. Higher values increase influence. Defaults to 1.0 if not specified. Must be non-negative. @server_default 1.0 */ + /** + * Weight multiplier for this retriever's contribution to the RRF score. Higher values increase influence. Defaults to 1.0 if not specified. Must be non-negative. + * @server_default 1.0 + */ weight?: float } @@ -176,7 +181,8 @@ export class TextSimilarityReranker extends RetrieverBase { inference_text: string /** The document field to be used for text similarity comparisons. This field should contain the text that will be evaluated against the inference_text. */ field: string - /** Whether to rescore on only the best matching chunks. + /** + * Whether to rescore on only the best matching chunks. * @availability stack since=9.2.0 stability=beta * @availability serverless stability=beta */ diff --git a/specification/_types/TokenPruningConfig.ts b/specification/_types/TokenPruningConfig.ts index 424f535464..07ee5dbbc1 100644 --- a/specification/_types/TokenPruningConfig.ts +++ b/specification/_types/TokenPruningConfig.ts @@ -20,15 +20,18 @@ import { float, integer } from '@_types/Numeric' export class TokenPruningConfig { - /** Tokens whose frequency is more than this threshold times the average frequency of all tokens in the specified field are considered outliers and pruned. + /** + * Tokens whose frequency is more than this threshold times the average frequency of all tokens in the specified field are considered outliers and pruned. * @server_default 5 */ tokens_freq_ratio_threshold?: integer - /** Tokens whose weight is less than this threshold are considered nonsignificant and pruned. + /** + * Tokens whose weight is less than this threshold are considered nonsignificant and pruned. * @server_default 0.4 */ tokens_weight_threshold?: float - /** Whether to only score pruned tokens, vs only scoring kept tokens. + /** + * Whether to only score pruned tokens, vs only scoring kept tokens. * @server_default false */ only_score_pruned_tokens?: boolean diff --git a/specification/_types/aggregations/Aggregate.ts b/specification/_types/aggregations/Aggregate.ts index 68f6f6ccc0..ed62c51c25 100644 --- a/specification/_types/aggregations/Aggregate.ts +++ b/specification/_types/aggregations/Aggregate.ts @@ -451,7 +451,8 @@ export class HistogramBucket extends MultiBucketBase { key: double } -/** @variant name=date_histogram +/** + * @variant name=date_histogram * @ext_doc_id search-aggregations-bucket-datehistogram-aggregation */ export class DateHistogramAggregate extends MultiBucketAggregateBase {} diff --git a/specification/_types/aggregations/AggregationContainer.ts b/specification/_types/aggregations/AggregationContainer.ts index b874786a71..e895a80bc7 100644 --- a/specification/_types/aggregations/AggregationContainer.ts +++ b/specification/_types/aggregations/AggregationContainer.ts @@ -457,7 +457,6 @@ export class AggregationContainer { * Sampling provides significant speed improvement at the cost of accuracy. * @ext_doc_id search-aggregations-random-sampler-aggregation * @availability stack since=8.1.0 stability=experimental - */ random_sampler?: RandomSamplerAggregation /** diff --git a/specification/_types/analysis/StopWords.ts b/specification/_types/analysis/StopWords.ts index 70d52e351a..57d47f4e1e 100644 --- a/specification/_types/analysis/StopWords.ts +++ b/specification/_types/analysis/StopWords.ts @@ -61,6 +61,6 @@ export enum StopWordLanguage { * Language value, such as _arabic_ or _thai_. Defaults to _english_. * Each language value corresponds to a predefined list of stop words in Lucene. See Stop words by language for supported language values and their stop words. * Also accepts an array of stop words. - * @class_serializer: StopWordsFormatter + * @class_serializer StopWordsFormatter */ export type StopWords = StopWordLanguage | string[] diff --git a/specification/_types/analysis/token_filters.ts b/specification/_types/analysis/token_filters.ts index fc34cac69d..6fc5424fe3 100644 --- a/specification/_types/analysis/token_filters.ts +++ b/specification/_types/analysis/token_filters.ts @@ -51,12 +51,16 @@ export class CompoundWordTokenFilterBase extends TokenFilterBase { min_word_size?: integer /** If `true`, only include the longest matching subword. Defaults to `false`. */ only_longest_match?: boolean - /** A list of subwords to look for in the token stream. If found, the subword is included in the token output. - * Either this parameter or `word_list_path` must be specified.*/ + /** + * A list of subwords to look for in the token stream. If found, the subword is included in the token output. + * Either this parameter or `word_list_path` must be specified. + */ word_list?: string[] - /** Path to a file that contains a list of subwords to find in the token stream. If found, the subword is included in the token output. + /** + * Path to a file that contains a list of subwords to find in the token stream. If found, the subword is included in the token output. * This path must be absolute or relative to the config location, and the file must be UTF-8 encoded. Each token in the file must be separated by a line break. - * Either this parameter or `word_list` must be specified. */ + * Either this parameter or `word_list` must be specified. + */ word_list_path?: string } @@ -66,8 +70,10 @@ export class DictionaryDecompounderTokenFilter extends CompoundWordTokenFilterBa export class HyphenationDecompounderTokenFilter extends CompoundWordTokenFilterBase { type: 'hyphenation_decompounder' - /** Path to an Apache FOP (Formatting Objects Processor) XML hyphenation pattern file. - * This path must be absolute or relative to the `config` location. Only FOP v1.2 compatible files are supported. */ + /** + * Path to an Apache FOP (Formatting Objects Processor) XML hyphenation pattern file. + * This path must be absolute or relative to the `config` location. Only FOP v1.2 compatible files are supported. + */ hyphenation_patterns_path: string /** If `true`, do not match sub tokens in tokens that are in the word list. Defaults to `false`. */ no_sub_matches?: boolean @@ -130,8 +136,10 @@ export class StopTokenFilter extends TokenFilterBase { remove_trailing?: boolean /** Language value, such as `_arabic_` or `_thai_`. Defaults to `_english_`. */ stopwords?: StopWords - /** Path to a file that contains a list of stop words to remove. - * This path must be absolute or relative to the `config` location, and the file must be UTF-8 encoded. Each stop word in the file must be separated by a line break. */ + /** + * Path to a file that contains a list of stop words to remove. + * This path must be absolute or relative to the `config` location, and the file must be UTF-8 encoded. Each stop word in the file must be separated by a line break. + */ stopwords_path?: string } @@ -153,7 +161,8 @@ export class SynonymTokenFilterBase extends TokenFilterBase { synonyms_path?: string /** Provide a synonym set created via Synonyms Management APIs. */ synonyms_set?: string - /** Controls the tokenizers that will be used to tokenize the synonym, this parameter is for backwards compatibility for indices that created before 6.0. + /** + * Controls the tokenizers that will be used to tokenize the synonym, this parameter is for backwards compatibility for indices that created before 6.0. * @deprecated 6.0.0 */ tokenizer?: string /** If `true` allows reloading search analyzers to pick up changes to synonym files. Only to be used for search analyzers. Defaults to `false`. */ @@ -183,8 +192,10 @@ export class WordDelimiterTokenFilterBase extends TokenFilterBase { preserve_original?: Stringified /** Array of tokens the filter won’t split. */ protected_words?: string[] - /** Path to a file that contains a list of tokens the filter won’t split. - * This path must be absolute or relative to the `config` location, and the file must be UTF-8 encoded. Each token in the file must be separated by a line break. */ + /** + * Path to a file that contains a list of tokens the filter won’t split. + * This path must be absolute or relative to the `config` location, and the file must be UTF-8 encoded. Each token in the file must be separated by a line break. + */ protected_words_path?: string /** If `true`, the filter splits tokens at letter case transitions. For example: camelCase -> [ camel, Case ]. Defaults to `true`. */ split_on_case_change?: boolean @@ -218,19 +229,25 @@ export class AsciiFoldingTokenFilter extends TokenFilterBase { export class CommonGramsTokenFilter extends TokenFilterBase { type: 'common_grams' - /** A list of tokens. The filter generates bigrams for these tokens. - * Either this or the `common_words_path` parameter is required. */ + /** + * A list of tokens. The filter generates bigrams for these tokens. + * Either this or the `common_words_path` parameter is required. + */ common_words?: string[] - /** Path to a file containing a list of tokens. The filter generates bigrams for these tokens. + /** + * Path to a file containing a list of tokens. The filter generates bigrams for these tokens. * This path must be absolute or relative to the `config` location. The file must be UTF-8 encoded. Each token in the file must be separated by a line break. - * Either this or the `common_words` parameter is required. */ + * Either this or the `common_words` parameter is required. + */ common_words_path?: string /** If `true`, matches for common words matching are case-insensitive. Defaults to `false`. */ ignore_case?: boolean - /** If `true`, the filter excludes the following tokens from the output: + /** + * If `true`, the filter excludes the following tokens from the output: * - Unigrams for common words * - Unigrams for terms followed by common words - * Defaults to `false`. We recommend enabling this parameter for search analyzers. */ + * Defaults to `false`. We recommend enabling this parameter for search analyzers. + */ query_mode?: boolean } @@ -244,14 +261,18 @@ export class ConditionTokenFilter extends TokenFilterBase { export class ElisionTokenFilter extends TokenFilterBase { type: 'elision' - /** List of elisions to remove. + /** + * List of elisions to remove. * To be removed, the elision must be at the beginning of a token and be immediately followed by an apostrophe. Both the elision and apostrophe are removed. - * For custom `elision` filters, either this parameter or `articles_path` must be specified. */ + * For custom `elision` filters, either this parameter or `articles_path` must be specified. + */ articles?: string[] - /** Path to a file that contains a list of elisions to remove. + /** + * Path to a file that contains a list of elisions to remove. * This path must be absolute or relative to the `config` location, and the file must be UTF-8 encoded. Each elision in the file must be separated by a line break. * To be removed, the elision must be at the beginning of a token and be immediately followed by an apostrophe. Both the elision and apostrophe are removed. - * For custom `elision` filters, either this parameter or `articles` must be specified. */ + * For custom `elision` filters, either this parameter or `articles` must be specified. + */ articles_path?: string /** If `true`, elision matching is case insensitive. If `false`, elision matching is case sensitive. Defaults to `false`. */ articles_case?: Stringified @@ -269,11 +290,15 @@ export class HunspellTokenFilter extends TokenFilterBase { type: 'hunspell' /** If `true`, duplicate tokens are removed from the filter’s output. Defaults to `true`. */ dedup?: boolean - /** One or more `.dic` files (e.g, `en_US.dic`, my_custom.dic) to use for the Hunspell dictionary. - * By default, the `hunspell` filter uses all `.dic` files in the `<$ES_PATH_CONF>/hunspell/` directory specified using the `lang`, `language`, or `locale` parameter. */ + /** + * One or more `.dic` files (e.g, `en_US.dic`, my_custom.dic) to use for the Hunspell dictionary. + * By default, the `hunspell` filter uses all `.dic` files in the `<$ES_PATH_CONF>/hunspell/` directory specified using the `lang`, `language`, or `locale` parameter. + */ dictionary?: string - /** Locale directory used to specify the `.aff` and `.dic` files for a Hunspell dictionary. - * @aliases lang, language */ + /** + * Locale directory used to specify the `.aff` and `.dic` files for a Hunspell dictionary. + * @aliases lang, language + */ locale: string /** If `true`, only the longest stemmed version of each token is included in the output. If `false`, all stemmed versions of the token are included. Defaults to `false`. */ longest_only?: boolean @@ -294,14 +319,18 @@ export class KeepTypesTokenFilter extends TokenFilterBase { export class KeepWordsTokenFilter extends TokenFilterBase { type: 'keep' - /** List of words to keep. Only tokens that match words in this list are included in the output. - * Either this parameter or `keep_words_path` must be specified. */ + /** + * List of words to keep. Only tokens that match words in this list are included in the output. + * Either this parameter or `keep_words_path` must be specified. + */ keep_words?: string[] /** If `true`, lowercase all keep words. Defaults to `false`. */ keep_words_case?: boolean - /** Path to a file that contains a list of words to keep. Only tokens that match words in this list are included in the output. + /** + * Path to a file that contains a list of words to keep. Only tokens that match words in this list are included in the output. * This path must be absolute or relative to the `config` location, and the file must be UTF-8 encoded. Each word in the file must be separated by a line break. - * Either this parameter or `keep_words` must be specified. */ + * Either this parameter or `keep_words` must be specified. + */ keep_words_path?: string } @@ -309,15 +338,21 @@ export class KeywordMarkerTokenFilter extends TokenFilterBase { type: 'keyword_marker' /** If `true`, matching for the `keywords` and `keywords_path` parameters ignores letter case. Defaults to `false`. */ ignore_case?: boolean - /** Array of keywords. Tokens that match these keywords are not stemmed. - * This parameter, `keywords_path`, or `keywords_pattern` must be specified. You cannot specify this parameter and `keywords_pattern`. */ + /** + * Array of keywords. Tokens that match these keywords are not stemmed. + * This parameter, `keywords_path`, or `keywords_pattern` must be specified. You cannot specify this parameter and `keywords_pattern`. + */ keywords?: string | string[] - /** Path to a file that contains a list of keywords. Tokens that match these keywords are not stemmed. + /** + * Path to a file that contains a list of keywords. Tokens that match these keywords are not stemmed. * This path must be absolute or relative to the `config` location, and the file must be UTF-8 encoded. Each word in the file must be separated by a line break. - * This parameter, `keywords`, or `keywords_pattern` must be specified. You cannot specify this parameter and `keywords_pattern`. */ + * This parameter, `keywords`, or `keywords_pattern` must be specified. You cannot specify this parameter and `keywords_pattern`. + */ keywords_path?: string - /** Java regular expression used to match tokens. Tokens that match this expression are marked as keywords and not stemmed. - * This parameter, `keywords`, or `keywords_path` must be specified. You cannot specify this parameter and `keywords` or `keywords_pattern`. */ + /** + * Java regular expression used to match tokens. Tokens that match this expression are marked as keywords and not stemmed. + * This parameter, `keywords`, or `keywords_path` must be specified. You cannot specify this parameter and `keywords` or `keywords_pattern`. + */ keywords_pattern?: string } @@ -517,8 +552,10 @@ export class MinHashTokenFilter extends TokenFilterBase { bucket_count?: integer /** Number of ways to hash each token in the stream. Defaults to `1`. */ hash_count?: integer - /** Number of hashes to keep from each bucket. Defaults to `1`. - * Hashes are retained by ascending size, starting with the bucket’s smallest hash first. */ + /** + * Number of hashes to keep from each bucket. Defaults to `1`. + * Hashes are retained by ascending size, starting with the bucket’s smallest hash first. + */ hash_set_size?: integer /** If `true`, the filter fills empty buckets with the value of the first non-empty bucket to its circular right if the `hash_set_size` is `1`. If the `bucket_count` argument is greater than 1, this parameter defaults to `true`. Otherwise, this parameter defaults to `false`. */ with_rotation?: boolean diff --git a/specification/_types/query_dsl/TextExpansionQuery.ts b/specification/_types/query_dsl/TextExpansionQuery.ts index 7d55520c5e..4051f88ed6 100644 --- a/specification/_types/query_dsl/TextExpansionQuery.ts +++ b/specification/_types/query_dsl/TextExpansionQuery.ts @@ -28,7 +28,8 @@ export class TextExpansionQuery extends QueryBase { model_id: string /** The query text */ model_text: string - /** Token pruning configurations + /** + * Token pruning configurations * @availability stack since=8.13.0 stability=experimental * @availability serverless stability=experimental */ diff --git a/specification/_types/query_dsl/compound.ts b/specification/_types/query_dsl/compound.ts index 26f1463e57..f9542b2423 100644 --- a/specification/_types/query_dsl/compound.ts +++ b/specification/_types/query_dsl/compound.ts @@ -128,7 +128,8 @@ export class FunctionScoreQuery extends QueryBase { * A query that determines the documents for which a new score is computed. */ query?: QueryContainer - /** Specifies how the computed scores are combined + /** + * Specifies how the computed scores are combined * @server_default multiply */ score_mode?: FunctionScoreMode diff --git a/specification/cat/_types/CatBase.ts b/specification/cat/_types/CatBase.ts index 247c62f09d..7812de95e7 100644 --- a/specification/cat/_types/CatBase.ts +++ b/specification/cat/_types/CatBase.ts @@ -79,7 +79,8 @@ export enum CatAnomalyDetectorColumn { 'data.earliest_record', /** * The number of buckets which did not contain any data. - * @aliases deb, dataEmptyBuckets */ + * @aliases deb, dataEmptyBuckets + */ 'data.empty_buckets', /** * The number of bytes of input data posted to the anomaly detection job. @@ -129,7 +130,8 @@ export enum CatAnomalyDetectorColumn { * The number of input documents that are missing a field that the anomaly * detection job is configured to analyze. Input documents with missing fields * are still processed because it is possible that not all fields are missing. - * @aliases dmf, dataMissingFields */ + * @aliases dmf, dataMissingFields + */ 'data.missing_fields', /** * The number of input documents that have a timestamp chronologically @@ -282,7 +284,8 @@ export enum CatAnomalyDetectorColumn { 'model.categorization_status', /** * The number of documents that have had a field categorized. - * @aliases mcdc, modelCategorizedDocCount */ + * @aliases mcdc, modelCategorizedDocCount + */ 'model.categorized_doc_count', /** * The number of categories created by categorization that will never be @@ -298,7 +301,8 @@ export enum CatAnomalyDetectorColumn { * not track which specific categories failed to be created. Therefore, you * cannot use this value to determine the number of unique categories that * were missed. - * @aliases mdcc, modelFailedCategoryCount */ + * @aliases mdcc, modelFailedCategoryCount + */ 'model.failed_category_count', /** * The number of categories that match more than 1% of categorized documents. @@ -350,7 +354,8 @@ export enum CatAnomalyDetectorColumn { 'model.timestamp', /** * The number of categories created by categorization. - * @aliases mtcc, modelTotalCategoryCount */ + * @aliases mtcc, modelTotalCategoryCount + */ 'model.total_category_count', /** * The network address of the node that runs the job. This information is @@ -447,7 +452,8 @@ export enum CatDatafeedColumn { sba, /** * The number of searches run by the datafeed. - * @aliases search.count, searchCount */ + * @aliases search.count, searchCount + */ sc, /** * The exponential average search time per hour, in milliseconds. @@ -456,7 +462,8 @@ export enum CatDatafeedColumn { seah, /** * The total time the datafeed spent searching, in milliseconds. - * @aliases search.time, searchTime */ + * @aliases search.time, searchTime + */ st, /** * The status of the datafeed: `starting`, `started`, `stopping`, or `stopped`. @@ -2127,7 +2134,7 @@ export enum CatNodeattrsColumn { id, /** * The process ID. - * * @aliases p + * @aliases p */ pid, /** diff --git a/specification/cat/component_templates/CatComponentTemplatesRequest.ts b/specification/cat/component_templates/CatComponentTemplatesRequest.ts index 7f131988b7..3fb2864181 100644 --- a/specification/cat/component_templates/CatComponentTemplatesRequest.ts +++ b/specification/cat/component_templates/CatComponentTemplatesRequest.ts @@ -50,7 +50,8 @@ export interface Request extends CatRequestBase { /** * The name of the component template. * It accepts wildcard expressions. - * If it is omitted, all component templates are returned. */ + * If it is omitted, all component templates are returned. + */ name?: string } query_parameters: { diff --git a/specification/cat/ml_data_frame_analytics/CatDataFrameAnalyticsRequest.ts b/specification/cat/ml_data_frame_analytics/CatDataFrameAnalyticsRequest.ts index 44138f5ba6..c24b43f132 100644 --- a/specification/cat/ml_data_frame_analytics/CatDataFrameAnalyticsRequest.ts +++ b/specification/cat/ml_data_frame_analytics/CatDataFrameAnalyticsRequest.ts @@ -61,7 +61,8 @@ export interface Request extends CatRequestBase { * @server_default create_time,id,state,type */ h?: CatDfaColumns - /** Comma-separated list of column names or column aliases used to sort the + /** + * Comma-separated list of column names or column aliases used to sort the * response. */ s?: CatDfaColumns diff --git a/specification/cat/transforms/CatTransformsRequest.ts b/specification/cat/transforms/CatTransformsRequest.ts index 5d8b01947c..043ff37c5e 100644 --- a/specification/cat/transforms/CatTransformsRequest.ts +++ b/specification/cat/transforms/CatTransformsRequest.ts @@ -72,7 +72,8 @@ export interface Request extends CatRequestBase { * @server_default changes_last_detection_time,checkpoint,checkpoint_progress,documents_processed,id,last_search_time,state */ h?: CatTransformColumns - /** Comma-separated list of column names or column aliases used to sort the response. + /** + Comma-separated list of column names or column aliases used to sort the response. */ s?: CatTransformColumns /** diff --git a/specification/ccr/_types/FollowIndexStats.ts b/specification/ccr/_types/FollowIndexStats.ts index 0e0b992b0d..8660b2a18e 100644 --- a/specification/ccr/_types/FollowIndexStats.ts +++ b/specification/ccr/_types/FollowIndexStats.ts @@ -87,7 +87,8 @@ export class ShardStats { /** The number of bulk write requests run on the follower.*/ successful_write_requests: long time_since_last_read?: Duration - /** The number of milliseconds since a read request was sent to the leader. + /** + * The number of milliseconds since a read request was sent to the leader. * When the follower is caught up to the leader, this number will increase up to the configured `read_poll_timeout` at which point another read request will be sent to the leader. */ time_since_last_read_millis: DurationValue diff --git a/specification/ccr/get_auto_follow_pattern/GetAutoFollowPatternRequest.ts b/specification/ccr/get_auto_follow_pattern/GetAutoFollowPatternRequest.ts index 976fd20d32..998fc6baac 100644 --- a/specification/ccr/get_auto_follow_pattern/GetAutoFollowPatternRequest.ts +++ b/specification/ccr/get_auto_follow_pattern/GetAutoFollowPatternRequest.ts @@ -45,7 +45,8 @@ export interface Request extends RequestBase { path_parts: { /** * The auto-follow pattern collection that you want to retrieve. - * If you do not specify a name, the API returns information for all collections. */ + * If you do not specify a name, the API returns information for all collections. + */ name?: Name } query_parameters: { diff --git a/specification/cluster/stats/ClusterStatsRequest.ts b/specification/cluster/stats/ClusterStatsRequest.ts index ac8d40db01..39479a10b2 100644 --- a/specification/cluster/stats/ClusterStatsRequest.ts +++ b/specification/cluster/stats/ClusterStatsRequest.ts @@ -55,7 +55,8 @@ export interface Request extends RequestBase { /** * Period to wait for each node to respond. * If a node does not respond before its timeout expires, the response does not include its stats. - * However, timed out nodes are included in the response’s `_nodes.failed` property. Defaults to no timeout. */ + * However, timed out nodes are included in the response’s `_nodes.failed` property. Defaults to no timeout. + */ timeout?: Duration } } diff --git a/specification/eslint.config.js b/specification/eslint.config.js index 36aa810de6..46029ad68c 100644 --- a/specification/eslint.config.js +++ b/specification/eslint.config.js @@ -19,103 +19,151 @@ import parser from '@typescript-eslint/parser' import validator from 'eslint-plugin-es-spec' import { defineConfig } from 'eslint/config' +import { jsdoc } from 'eslint-plugin-jsdoc'; -export default defineConfig({ - files: ['**/*.ts'], - languageOptions: { - parser, - parserOptions: { - projectService: true, - tsconfigRootDir: import.meta.dirname - } - }, - plugins: { 'es-spec-validator': validator }, - rules: { - 'es-spec-validator/single-key-dictionary-key-is-string': 'error', - 'es-spec-validator/dictionary-key-is-string': 'error', - 'es-spec-validator/no-native-types': 'error', - 'es-spec-validator/invalid-node-types': 'error', - 'es-spec-validator/no-generic-number': 'error', - 'es-spec-validator/request-must-have-urls': 'error', - 'es-spec-validator/no-variants-on-responses': 'error', - 'es-spec-validator/no-inline-unions': 'error', - 'es-spec-validator/prefer-tagged-variants': 'error', - 'es-spec-validator/no-duplicate-type-names': [ - 'error', - { - ignoreNames: ['Request', 'Response', 'ResponseBase'], - existingDuplicates: { - Action: [ - 'indices.modify_data_stream', - 'indices.update_aliases', - 'watcher._types' - ], - Actions: ['ilm._types', 'security.put_privileges', 'watcher._types'], - ComponentTemplate: ['cat.component_templates', 'cluster._types'], - Context: [ - '_global.get_script_context', - '_global.search._types', - 'nodes._types' - ], - DatabaseConfigurationMetadata: [ - 'ingest.get_geoip_database', - 'ingest.get_ip_location_database' - ], - Datafeed: ['ml._types', 'xpack.usage'], - Destination: ['_global.reindex', 'transform._types'], - Feature: ['features._types', 'indices.get', 'xpack.info'], - Features: ['indices.get', 'xpack.info'], - Filter: ['_global.termvectors', 'ml._types'], - IndexingPressure: ['cluster.stats', 'indices._types', 'nodes._types'], - IndexingPressureMemory: ['indices._types', 'nodes._types'], - Ingest: ['ingest._types', 'nodes._types'], - MigrationFeature: [ - 'migration.get_feature_upgrade_status', - 'migration.post_feature_upgrade' - ], - Operation: ['_global.mget', '_global.mtermvectors'], - ResponseBody: ['_global.search', 'ml.evaluate_data_frame'], - Phase: ['ilm._types', 'xpack.usage'], - Phases: ['ilm._types', 'xpack.usage'], - Pipeline: ['ingest._types', 'logstash._types'], - Policy: ['enrich._types', 'ilm._types', 'slm._types'], - RequestItem: ['_global.msearch', '_global.msearch_template'], - ResponseItem: ['_global.bulk', '_global.mget', '_global.msearch'], - RoleMapping: ['security._types', 'xpack.usage'], - RuntimeFieldTypes: ['cluster.stats', 'xpack.usage'], - ShardsStats: ['indices.field_usage_stats', 'snapshot._types'], - ShardStats: ['ccr._types', 'indices.stats'], - Source: ['_global.reindex', 'transform._types'], - Token: [ - '_global.termvectors', - 'security.authenticate', - 'security.create_service_token', - 'security.enroll_kibana' - ] - } +export default defineConfig([ + { + files: ['**/*.ts'], + languageOptions: { + parser, + parserOptions: { + projectService: true, + tsconfigRootDir: import.meta.dirname } - ], - 'es-spec-validator/no-all-string-literal-unions': 'error', - 'es-spec-validator/jsdoc-endpoint-check': [ - 'error', - { - markdownlint: { - default: true, - MD041: false, // first-line-heading - MD013: false, // line-length - MD033: false, // no-inline-html - MD034: false, // no-bare-urls - MD047: false, // single-trailing-newline - MD036: false, // no-emphasis-as-heading - MD040: false, // fenced-code-language - MD032: false, // blanks-around-lists - MD031: false, // blanks-around-fences - MD038: false, // no-space-in-code - MD060: false, // table-column-style - MD010: false, // no-hard-tabs - MD022: false // blanks-around-headers + }, + plugins: { 'es-spec-validator': validator }, + rules: { + 'es-spec-validator/single-key-dictionary-key-is-string': 'error', + 'es-spec-validator/dictionary-key-is-string': 'error', + 'es-spec-validator/no-native-types': 'error', + 'es-spec-validator/invalid-node-types': 'error', + 'es-spec-validator/no-generic-number': 'error', + 'es-spec-validator/request-must-have-urls': 'error', + 'es-spec-validator/no-variants-on-responses': 'error', + 'es-spec-validator/no-inline-unions': 'error', + 'es-spec-validator/prefer-tagged-variants': 'error', + 'es-spec-validator/no-duplicate-type-names': [ + 'error', + { + ignoreNames: ['Request', 'Response', 'ResponseBase'], + existingDuplicates: { + Action: [ + 'indices.modify_data_stream', + 'indices.update_aliases', + 'watcher._types' + ], + Actions: ['ilm._types', 'security.put_privileges', 'watcher._types'], + ComponentTemplate: ['cat.component_templates', 'cluster._types'], + Context: [ + '_global.get_script_context', + '_global.search._types', + 'nodes._types' + ], + DatabaseConfigurationMetadata: [ + 'ingest.get_geoip_database', + 'ingest.get_ip_location_database' + ], + Datafeed: ['ml._types', 'xpack.usage'], + Destination: ['_global.reindex', 'transform._types'], + Feature: ['features._types', 'indices.get', 'xpack.info'], + Features: ['indices.get', 'xpack.info'], + Filter: ['_global.termvectors', 'ml._types'], + IndexingPressure: ['cluster.stats', 'indices._types', 'nodes._types'], + IndexingPressureMemory: ['indices._types', 'nodes._types'], + Ingest: ['ingest._types', 'nodes._types'], + MigrationFeature: [ + 'migration.get_feature_upgrade_status', + 'migration.post_feature_upgrade' + ], + Operation: ['_global.mget', '_global.mtermvectors'], + ResponseBody: ['_global.search', 'ml.evaluate_data_frame'], + Phase: ['ilm._types', 'xpack.usage'], + Phases: ['ilm._types', 'xpack.usage'], + Pipeline: ['ingest._types', 'logstash._types'], + Policy: ['enrich._types', 'ilm._types', 'slm._types'], + RequestItem: ['_global.msearch', '_global.msearch_template'], + ResponseItem: ['_global.bulk', '_global.mget', '_global.msearch'], + RoleMapping: ['security._types', 'xpack.usage'], + RuntimeFieldTypes: ['cluster.stats', 'xpack.usage'], + ShardsStats: ['indices.field_usage_stats', 'snapshot._types'], + ShardStats: ['ccr._types', 'indices.stats'], + Source: ['_global.reindex', 'transform._types'], + Token: [ + '_global.termvectors', + 'security.authenticate', + 'security.create_service_token', + 'security.enroll_kibana' + ] + } } - } - ] - } -}) + ], + 'es-spec-validator/no-all-string-literal-unions': 'error', + 'es-spec-validator/jsdoc-endpoint-check': [ + 'error', + { + markdownlint: { + default: true, + MD041: false, // first-line-heading + MD013: false, // line-length + MD033: false, // no-inline-html + MD034: false, // no-bare-urls + MD047: false, // single-trailing-newline + MD036: false, // no-emphasis-as-heading + MD040: false, // fenced-code-language + MD032: false, // blanks-around-lists + MD031: false, // blanks-around-fences + MD038: false, // no-space-in-code + MD060: false, // table-column-style + MD010: false, // no-hard-tabs + MD022: false // blanks-around-headers + } + } + ] + } + }, + jsdoc({ + config: 'flat/recommended-typescript-error', + rules: { + // Allow custom tags used in Elasticsearch specification + 'jsdoc/check-tag-names': ['error', { + definedTags: [ + 'UpdateForV10', + 'aliases', + 'availability', + 'behavior', + 'behavior_meta', + 'class_serializer', + 'cluster_privileges', + 'codegen_name', + 'codegen_names', + 'doc_id', + 'doc_tag', + 'doc_url', + 'es_quirk', + 'ext_doc_id', + 'index_privileges', + 'non_exhaustive', + 'prop_serializer', + 'rest_spec_name', + 'server_default', + 'shortcut_property', + 'variant', + 'variants' + ], + }], + // Require UpdateForV10 tags to have an associated description/name + "jsdoc/match-name": ["error", { + match: [{ + "allowName":"/.+/","tags":["UpdateForV10"], + "message": "Please provide a reason for the breaking change" + }] + }], + // Allow Markdown formatting + 'jsdoc/tag-lines': 'off', + 'jsdoc/no-multi-asterisks': 'off', + // server_default values aren't parsed by jsdoc correctly + 'jsdoc/valid-types': 'off', + + }, + }) +]) diff --git a/specification/indices/put_data_stream_mappings/IndicesPutDataStreamMappingsRequest.ts b/specification/indices/put_data_stream_mappings/IndicesPutDataStreamMappingsRequest.ts index 9bd642367c..ff351e0085 100644 --- a/specification/indices/put_data_stream_mappings/IndicesPutDataStreamMappingsRequest.ts +++ b/specification/indices/put_data_stream_mappings/IndicesPutDataStreamMappingsRequest.ts @@ -70,7 +70,8 @@ export interface Request extends RequestBase { */ timeout?: Duration } - /** Mappings to be applied to the data stream. + /** + * Mappings to be applied to the data stream. * @codegen_name mappings */ body: TypeMapping } diff --git a/specification/indices/put_data_stream_settings/IndicesPutDataStreamSettingsRequest.ts b/specification/indices/put_data_stream_settings/IndicesPutDataStreamSettingsRequest.ts index c09dcda447..7dc6a91b7b 100644 --- a/specification/indices/put_data_stream_settings/IndicesPutDataStreamSettingsRequest.ts +++ b/specification/indices/put_data_stream_settings/IndicesPutDataStreamSettingsRequest.ts @@ -71,7 +71,8 @@ export interface Request extends RequestBase { */ timeout?: Duration } - /** Settings to be applied to the data stream. + /** + * Settings to be applied to the data stream. * @codegen_name settings */ body: IndexSettings } diff --git a/specification/indices/put_settings/IndicesPutSettingsRequest.ts b/specification/indices/put_settings/IndicesPutSettingsRequest.ts index 1fc5a3e4f2..e080545f5f 100644 --- a/specification/indices/put_settings/IndicesPutSettingsRequest.ts +++ b/specification/indices/put_settings/IndicesPutSettingsRequest.ts @@ -159,7 +159,8 @@ export interface Request extends RequestBase { */ timeout?: Duration } - /** Configuration options for the index. + /** + * Configuration options for the index. * @codegen_name settings */ body: IndexSettings diff --git a/specification/indices/simulate_index_template/IndicesSimulateIndexTemplateRequest.ts b/specification/indices/simulate_index_template/IndicesSimulateIndexTemplateRequest.ts index f9b95367c4..62b95fc22d 100644 --- a/specification/indices/simulate_index_template/IndicesSimulateIndexTemplateRequest.ts +++ b/specification/indices/simulate_index_template/IndicesSimulateIndexTemplateRequest.ts @@ -49,7 +49,8 @@ export interface Request extends RequestBase { * @server_default false */ create?: boolean - /** User defined reason for dry-run creating the new template for simulation purposes + /** + * User defined reason for dry-run creating the new template for simulation purposes * @server_default false */ cause?: string diff --git a/specification/inference/put_hugging_face/PutHuggingFaceRequest.ts b/specification/inference/put_hugging_face/PutHuggingFaceRequest.ts index 62f47a6846..e74fd19773 100644 --- a/specification/inference/put_hugging_face/PutHuggingFaceRequest.ts +++ b/specification/inference/put_hugging_face/PutHuggingFaceRequest.ts @@ -36,7 +36,7 @@ import { InferenceChunkingSettings } from '@inference/_types/Services' * * To configure the endpoint, first visit the Hugging Face Inference Endpoints page and create a new endpoint. * Select a model that supports the task you intend to use. - + * * For Elastic's `text_embedding` task: * The selected model must support the `Sentence Embeddings` task. On the new endpoint creation page, select the `Sentence Embeddings` task under the `Advanced Configuration` section. * After the endpoint has initialized, copy the generated endpoint URL. diff --git a/specification/inference/put_voyageai/PutVoyageAIRequest.ts b/specification/inference/put_voyageai/PutVoyageAIRequest.ts index 99ec97c36b..7ed94f49cc 100644 --- a/specification/inference/put_voyageai/PutVoyageAIRequest.ts +++ b/specification/inference/put_voyageai/PutVoyageAIRequest.ts @@ -29,17 +29,17 @@ import { import { InferenceChunkingSettings } from '@inference/_types/Services' /** - * Create a VoyageAI inference endpoint. - * - * Create an inference endpoint to perform an inference task with the `voyageai` service. - - * Avoid creating multiple endpoints for the same model unless required, as each endpoint consumes significant resources. - * @rest_spec_name inference.put_voyageai - * @availability stack since=8.19.0 stability=stable visibility=public - * @availability serverless stability=stable visibility=public - * @cluster_privileges manage_inference - * @doc_id inference-api-put-voyageai - */ + * Create a VoyageAI inference endpoint. + * + * Create an inference endpoint to perform an inference task with the `voyageai` service. + * + * Avoid creating multiple endpoints for the same model unless required, as each endpoint consumes significant resources. + * @rest_spec_name inference.put_voyageai + * @availability stack since=8.19.0 stability=stable visibility=public + * @availability serverless stability=stable visibility=public + * @cluster_privileges manage_inference + * @doc_id inference-api-put-voyageai + */ export interface Request extends RequestBase { urls: [ { diff --git a/specification/ingest/put_geoip_database/PutGeoipDatabaseRequest.ts b/specification/ingest/put_geoip_database/PutGeoipDatabaseRequest.ts index 3bef6ac897..a8562298f6 100644 --- a/specification/ingest/put_geoip_database/PutGeoipDatabaseRequest.ts +++ b/specification/ingest/put_geoip_database/PutGeoipDatabaseRequest.ts @@ -58,7 +58,8 @@ export interface Request extends RequestBase { body: { /** The provider-assigned name of the IP geolocation database to download. */ name: Name - /** The configuration necessary to identify which IP geolocation provider to use to download the database, as well as any provider-specific configuration necessary for such downloading. + /** + * The configuration necessary to identify which IP geolocation provider to use to download the database, as well as any provider-specific configuration necessary for such downloading. * At present, the only supported provider is maxmind, and the maxmind provider requires that an account_id (string) is configured. */ maxmind: Maxmind diff --git a/specification/ml/_types/Authorization.ts b/specification/ml/_types/Authorization.ts index 0f25905553..eb9ab7af51 100644 --- a/specification/ml/_types/Authorization.ts +++ b/specification/ml/_types/Authorization.ts @@ -34,7 +34,8 @@ export class DatafeedAuthorization { */ api_key?: ApiKeyAuthorization /** - * If a user ID was used for the most recent update to the datafeed, its roles at the time of the update are listed in the response. */ + * If a user ID was used for the most recent update to the datafeed, its roles at the time of the update are listed in the response. + */ roles?: string[] /** * If a service account was used for the most recent update to the datafeed, the account name is listed in the response. @@ -48,7 +49,8 @@ export class DataframeAnalyticsAuthorization { */ api_key?: ApiKeyAuthorization /** - * If a user ID was used for the most recent update to the job, its roles at the time of the update are listed in the response. */ + * If a user ID was used for the most recent update to the job, its roles at the time of the update are listed in the response. + */ roles?: string[] /** * If a service account was used for the most recent update to the job, the account name is listed in the response. @@ -62,7 +64,8 @@ export class TransformAuthorization { */ api_key?: ApiKeyAuthorization /** - * If a user ID was used for the most recent update to the transform, its roles at the time of the update are listed in the response. */ + * If a user ID was used for the most recent update to the transform, its roles at the time of the update are listed in the response. + */ roles?: string[] /** * If a service account was used for the most recent update to the transform, the account name is listed in the response. diff --git a/specification/ml/_types/Bucket.ts b/specification/ml/_types/Bucket.ts index 0f7eb5013d..62cd883274 100644 --- a/specification/ml/_types/Bucket.ts +++ b/specification/ml/_types/Bucket.ts @@ -92,7 +92,8 @@ export class BucketInfluencer { influencer_field_name: Field /** * The score between 0-100 for each bucket influencer. This score is the initial value that was calculated at the - * time the bucket was processed. */ + * time the bucket was processed. + */ initial_anomaly_score: double /** * If true, this is an interim result. In other words, the results are calculated based on partial input data. diff --git a/specification/ml/_types/CalendarEvent.ts b/specification/ml/_types/CalendarEvent.ts index b45fe77a30..081a52fb2f 100644 --- a/specification/ml/_types/CalendarEvent.ts +++ b/specification/ml/_types/CalendarEvent.ts @@ -31,11 +31,13 @@ export class CalendarEvent { end_time: DateTime /** The timestamp for the beginning of the scheduled event in milliseconds since the epoch or ISO 8601 format. */ start_time: DateTime - /** When true the model will not create results for this calendar period. + /** + * When true the model will not create results for this calendar period. * @server_default true */ skip_result?: boolean - /** When true the model will not be updated for this calendar period. + /** + * When true the model will not be updated for this calendar period. * @server_default true */ skip_model_update?: boolean diff --git a/specification/ml/_types/Datafeed.ts b/specification/ml/_types/Datafeed.ts index a0288aa9e7..59d4049b6c 100644 --- a/specification/ml/_types/Datafeed.ts +++ b/specification/ml/_types/Datafeed.ts @@ -74,7 +74,8 @@ export class DatafeedConfig { * Datafeeds might be required to search over long time periods, for several months or years. This search is split into time chunks in order to ensure the load on Elasticsearch is managed. Chunking configuration controls how the size of these time chunks are calculated and is an advanced configuration option. */ chunking_config?: ChunkingConfig - /** A numerical character string that uniquely identifies the datafeed. This identifier can contain lowercase alphanumeric characters (a-z and 0-9), hyphens, and underscores. It must start and end with alphanumeric characters. The default value is the job identifier. + /** + A numerical character string that uniquely identifies the datafeed. This identifier can contain lowercase alphanumeric characters (a-z and 0-9), hyphens, and underscores. It must start and end with alphanumeric characters. The default value is the job identifier. */ datafeed_id?: Id /** diff --git a/specification/ml/_types/TrainedModel.ts b/specification/ml/_types/TrainedModel.ts index 51e2157ef0..1b17c371d5 100644 --- a/specification/ml/_types/TrainedModel.ts +++ b/specification/ml/_types/TrainedModel.ts @@ -92,7 +92,8 @@ export class TrainedModelDeploymentStats { * trained model deployment API. */ rejected_execution_count?: integer - /** The reason for the current deployment state. Usually only populated when + /** + * The reason for the current deployment state. Usually only populated when * the model is not deployed to a node. */ reason?: string diff --git a/specification/ml/_types/inference.ts b/specification/ml/_types/inference.ts index 4f0c21caac..95b9903448 100644 --- a/specification/ml/_types/inference.ts +++ b/specification/ml/_types/inference.ts @@ -217,7 +217,8 @@ export class TextClassificationInferenceOptions { export class ZeroShotClassificationInferenceOptions { /** The tokenization options to update when inferring */ tokenization?: TokenizationConfigContainer - /** Hypothesis template used when tokenizing labels for prediction + /** + * Hypothesis template used when tokenizing labels for prediction * @server_default "This example is {}." */ hypothesis_template?: string @@ -228,7 +229,8 @@ export class ZeroShotClassificationInferenceOptions { classification_labels: string[] /** The field that is added to incoming documents to contain the inference prediction. Defaults to predicted_value. */ results_field?: string - /** Indicates if more than one true label exists. + /** + * Indicates if more than one true label exists. * @server_default false **/ multi_label?: boolean @@ -283,11 +285,13 @@ export class NerInferenceOptions { /** Fill mask inference options */ export class FillMaskInferenceOptions { - /** The string/token which will be removed from incoming documents and replaced with the inference prediction(s). + /** + * The string/token which will be removed from incoming documents and replaced with the inference prediction(s). * In a response, this field contains the mask token for the specified model/tokenizer. Each model and tokenizer * has a predefined mask token which cannot be changed. Thus, it is recommended not to set this value in requests. * However, if this field is present in a request, its value must match the predefined value for that model/tokenizer, - * otherwise the request will fail. */ + * otherwise the request will fail. + */ mask_token?: string /** Specifies the number of top class predictions to return. Defaults to 0. */ num_top_classes?: integer diff --git a/specification/ml/get_calendar_events/MlGetCalendarEventsRequest.ts b/specification/ml/get_calendar_events/MlGetCalendarEventsRequest.ts index 06b6762bf8..95b4eb6ed1 100644 --- a/specification/ml/get_calendar_events/MlGetCalendarEventsRequest.ts +++ b/specification/ml/get_calendar_events/MlGetCalendarEventsRequest.ts @@ -46,13 +46,15 @@ export interface Request extends RequestBase { query_parameters: { /** Specifies to get events with timestamps earlier than this time. */ end?: DateTime - /** Skips the specified number of events. + /** + * Skips the specified number of events. * @server_default 0 */ from?: integer /** Specifies to get events for a specific anomaly detection job identifier or job group. It must be used with a calendar identifier of `_all` or `*`. */ job_id?: Id - /** Specifies the maximum number of events to obtain. + /** + * Specifies the maximum number of events to obtain. * @server_default 100 */ size?: integer diff --git a/specification/ml/get_calendars/MlGetCalendarsRequest.ts b/specification/ml/get_calendars/MlGetCalendarsRequest.ts index 1ac5239d4f..11eb9c6e09 100644 --- a/specification/ml/get_calendars/MlGetCalendarsRequest.ts +++ b/specification/ml/get_calendars/MlGetCalendarsRequest.ts @@ -48,11 +48,13 @@ export interface Request extends RequestBase { calendar_id?: Id } query_parameters: { - /** Skips the specified number of calendars. This parameter is supported only when you omit the calendar identifier. + /** + * Skips the specified number of calendars. This parameter is supported only when you omit the calendar identifier. * @server_default 0 */ from?: integer - /** Specifies the maximum number of calendars to obtain. This parameter is supported only when you omit the calendar identifier. + /** + * Specifies the maximum number of calendars to obtain. This parameter is supported only when you omit the calendar identifier. * @server_default 10000 */ size?: integer diff --git a/specification/package-lock.json b/specification/package-lock.json index dd53efddba..3e819dc5be 100644 --- a/specification/package-lock.json +++ b/specification/package-lock.json @@ -10,7 +10,8 @@ "dependencies": { "@typescript-eslint/parser": "^8.32.1", "eslint": "^9.26.0", - "eslint-plugin-es-spec": "file:../validator" + "eslint-plugin-es-spec": "file:../validator", + "eslint-plugin-jsdoc": "^61.2.1" } }, "../validator": { @@ -19,6 +20,8 @@ "license": "Apache-2.0", "dependencies": { "@typescript-eslint/utils": "^8.32.1", + "eslint-plugin-jsdoc": "^61.2.1", + "markdownlint": "^0.39.0", "typescript": "^5.8.3" }, "devDependencies": { @@ -28,6 +31,44 @@ "eslint": ">=9.0.0" } }, + "node_modules/@es-joy/jsdoccomment": { + "version": "0.76.0", + "resolved": "https://registry.npmjs.org/@es-joy/jsdoccomment/-/jsdoccomment-0.76.0.tgz", + "integrity": "sha512-g+RihtzFgGTx2WYCuTHbdOXJeAlGnROws0TeALx9ow/ZmOROOZkVg5wp/B44n0WJgI4SQFP1eWM2iRPlU2Y14w==", + "license": "MIT", + "dependencies": { + "@types/estree": "^1.0.8", + "@typescript-eslint/types": "^8.46.0", + "comment-parser": "1.4.1", + "esquery": "^1.6.0", + "jsdoc-type-pratt-parser": "~6.10.0" + }, + "engines": { + "node": ">=20.11.0" + } + }, + "node_modules/@es-joy/jsdoccomment/node_modules/@typescript-eslint/types": { + "version": "8.46.4", + "resolved": "https://registry.npmjs.org/@typescript-eslint/types/-/types-8.46.4.tgz", + "integrity": "sha512-USjyxm3gQEePdUwJBFjjGNG18xY9A2grDVGuk7/9AkjIF1L+ZrVnwR5VAU5JXtUnBL/Nwt3H31KlRDaksnM7/w==", + "license": "MIT", + "engines": { + "node": "^18.18.0 || ^20.9.0 || >=21.1.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/typescript-eslint" + } + }, + "node_modules/@es-joy/resolve.exports": { + "version": "1.2.0", + "resolved": "https://registry.npmjs.org/@es-joy/resolve.exports/-/resolve.exports-1.2.0.tgz", + "integrity": "sha512-Q9hjxWI5xBM+qW2enxfe8wDKdFWMfd0Z29k5ZJnuBqD/CasY5Zryj09aCA6owbGATWz+39p5uIdaHXpopOcG8g==", + "license": "MIT", + "engines": { + "node": ">=10" + } + }, "node_modules/@eslint-community/eslint-utils": { "version": "4.7.0", "resolved": "https://registry.npmjs.org/@eslint-community/eslint-utils/-/eslint-utils-4.7.0.tgz", @@ -311,10 +352,22 @@ "node": ">= 8" } }, + "node_modules/@sindresorhus/base62": { + "version": "1.0.0", + "resolved": "https://registry.npmjs.org/@sindresorhus/base62/-/base62-1.0.0.tgz", + "integrity": "sha512-TeheYy0ILzBEI/CO55CP6zJCSdSWeRtGnHy8U8dWSUH4I68iqTsy7HkMktR4xakThc9jotkPQUXT4ITdbV7cHA==", + "license": "MIT", + "engines": { + "node": ">=18" + }, + "funding": { + "url": "https://github.com/sponsors/sindresorhus" + } + }, "node_modules/@types/estree": { - "version": "1.0.7", - "resolved": "https://registry.npmjs.org/@types/estree/-/estree-1.0.7.tgz", - "integrity": "sha512-w28IoSUCJpidD/TGviZwwMJckNESJZXFu7NBZ5YJ4mEUnNraUn9Pm8HSZm/jDF1pDWYKspWE7oVphigUPRakIQ==", + "version": "1.0.8", + "resolved": "https://registry.npmjs.org/@types/estree/-/estree-1.0.8.tgz", + "integrity": "sha512-dWHzHa2WqEXI/O1E9OjrocMTKJl2mSrEolh1Iomrv6U+JuNwaHXsXx9bLu5gG7BUWFIN0skIQJQ/L1rIex4X6w==", "license": "MIT" }, "node_modules/@types/json-schema": { @@ -460,9 +513,9 @@ } }, "node_modules/acorn": { - "version": "8.14.1", - "resolved": "https://registry.npmjs.org/acorn/-/acorn-8.14.1.tgz", - "integrity": "sha512-OvQ/2pUDKmgfCg++xsTX1wGxfTaszcHVcTctW4UJB4hibJx2HXxxO5UmVgyjMa+ZDsiaf5wWLXYpRWMmBI0QHg==", + "version": "8.15.0", + "resolved": "https://registry.npmjs.org/acorn/-/acorn-8.15.0.tgz", + "integrity": "sha512-NZyJarBfL7nWwIq+FDL6Zp/yHEhePMNnnJ0y3qfieCrmNvYct8uvtiV41UvlSe6apAfk0fY1FbWx+NwfmpvtTg==", "license": "MIT", "bin": { "acorn": "bin/acorn" @@ -511,6 +564,15 @@ "url": "https://github.com/chalk/ansi-styles?sponsor=1" } }, + "node_modules/are-docs-informative": { + "version": "0.0.2", + "resolved": "https://registry.npmjs.org/are-docs-informative/-/are-docs-informative-0.0.2.tgz", + "integrity": "sha512-ixiS0nLNNG5jNQzgZJNoUpBKdo9yTYZMGJ+QgT2jmjR7G7+QHRCc4v6LQ3NgE7EBJq+o0ams3waJwkrlBom8Ig==", + "license": "MIT", + "engines": { + "node": ">=14" + } + }, "node_modules/argparse": { "version": "2.0.1", "resolved": "https://registry.npmjs.org/argparse/-/argparse-2.0.1.tgz", @@ -587,6 +649,15 @@ "integrity": "sha512-dOy+3AuW3a2wNbZHIuMZpTcgjGuLU/uBL/ubcZF9OXbDo8ff4O8yVp5Bf0efS8uEoYo5q4Fx7dY9OgQGXgAsQA==", "license": "MIT" }, + "node_modules/comment-parser": { + "version": "1.4.1", + "resolved": "https://registry.npmjs.org/comment-parser/-/comment-parser-1.4.1.tgz", + "integrity": "sha512-buhp5kePrmda3vhc5B9t7pUQXAb2Tnd0qgpkIhPhkHXxJpiPJ11H0ZEU0oBpJ2QztSbzG/ZxMj/CHsYJqRHmyg==", + "license": "MIT", + "engines": { + "node": ">= 12.0.0" + } + }, "node_modules/concat-map": { "version": "0.0.1", "resolved": "https://registry.npmjs.org/concat-map/-/concat-map-0.0.1.tgz", @@ -608,9 +679,9 @@ } }, "node_modules/debug": { - "version": "4.4.1", - "resolved": "https://registry.npmjs.org/debug/-/debug-4.4.1.tgz", - "integrity": "sha512-KcKCqiftBJcZr++7ykoDIEwSa3XWowTfNPo92BYxjXiyYEVrUQh2aLyhxBCwww+heortUFxEJYcRzosstTEBYQ==", + "version": "4.4.3", + "resolved": "https://registry.npmjs.org/debug/-/debug-4.4.3.tgz", + "integrity": "sha512-RGwwWnwQvkVfavKVt22FGLw+xYSdzARwm0ru6DhTVA3umU5hZc28V3kO4stgYryrTlLpuvgI9GiijltAjNbcqA==", "license": "MIT", "dependencies": { "ms": "^2.1.3" @@ -706,6 +777,34 @@ "resolved": "../validator", "link": true }, + "node_modules/eslint-plugin-jsdoc": { + "version": "61.2.1", + "resolved": "https://registry.npmjs.org/eslint-plugin-jsdoc/-/eslint-plugin-jsdoc-61.2.1.tgz", + "integrity": "sha512-Htacti3dbkNm4rlp/Bk9lqhv+gi6US9jyN22yaJ42G6wbteiTbNLChQwi25jr/BN+NOzDWhZHvCDdrhX0F8dXQ==", + "license": "BSD-3-Clause", + "dependencies": { + "@es-joy/jsdoccomment": "~0.76.0", + "@es-joy/resolve.exports": "1.2.0", + "are-docs-informative": "^0.0.2", + "comment-parser": "1.4.1", + "debug": "^4.4.3", + "escape-string-regexp": "^4.0.0", + "espree": "^10.4.0", + "esquery": "^1.6.0", + "html-entities": "^2.6.0", + "object-deep-merge": "^2.0.0", + "parse-imports-exports": "^0.2.4", + "semver": "^7.7.3", + "spdx-expression-parse": "^4.0.0", + "to-valid-identifier": "^1.0.0" + }, + "engines": { + "node": ">=20.11.0" + }, + "peerDependencies": { + "eslint": "^7.0.0 || ^8.0.0 || ^9.0.0" + } + }, "node_modules/eslint-scope": { "version": "8.3.0", "resolved": "https://registry.npmjs.org/eslint-scope/-/eslint-scope-8.3.0.tgz", @@ -723,9 +822,9 @@ } }, "node_modules/eslint-visitor-keys": { - "version": "4.2.0", - "resolved": "https://registry.npmjs.org/eslint-visitor-keys/-/eslint-visitor-keys-4.2.0.tgz", - "integrity": "sha512-UyLnSehNt62FFhSwjZlHmeokpRK59rcz29j+F1/aDgbkbRTk7wIc9XzdoasMUbRNKDM0qQt/+BJ4BrpFeABemw==", + "version": "4.2.1", + "resolved": "https://registry.npmjs.org/eslint-visitor-keys/-/eslint-visitor-keys-4.2.1.tgz", + "integrity": "sha512-Uhdk5sfqcee/9H/rCOJikYz67o0a2Tw2hGRPOG2Y1R2dg7brRe1uG0yaNQDHu+TO/uQPF/5eCapvYSmHUjt7JQ==", "license": "Apache-2.0", "engines": { "node": "^18.18.0 || ^20.9.0 || >=21.1.0" @@ -757,14 +856,14 @@ } }, "node_modules/espree": { - "version": "10.3.0", - "resolved": "https://registry.npmjs.org/espree/-/espree-10.3.0.tgz", - "integrity": "sha512-0QYC8b24HWY8zjRnDTL6RiHfDbAWn63qb4LMj1Z4b076A4une81+z03Kg7l7mn/48PUTqoLptSXez8oknU8Clg==", + "version": "10.4.0", + "resolved": "https://registry.npmjs.org/espree/-/espree-10.4.0.tgz", + "integrity": "sha512-j6PAQ2uUr79PZhBjP5C5fhl8e39FmRnOjsD5lGnWrFU8i2G776tBK7+nP8KuQUTTyAZUwfQqXAgrVH5MbH9CYQ==", "license": "BSD-2-Clause", "dependencies": { - "acorn": "^8.14.0", + "acorn": "^8.15.0", "acorn-jsx": "^5.3.2", - "eslint-visitor-keys": "^4.2.0" + "eslint-visitor-keys": "^4.2.1" }, "engines": { "node": "^18.18.0 || ^20.9.0 || >=21.1.0" @@ -962,6 +1061,22 @@ "node": ">=8" } }, + "node_modules/html-entities": { + "version": "2.6.0", + "resolved": "https://registry.npmjs.org/html-entities/-/html-entities-2.6.0.tgz", + "integrity": "sha512-kig+rMn/QOVRvr7c86gQ8lWXq+Hkv6CbAH1hLu+RG338StTpE8Z0b44SDVaqVu7HGKf27frdmUYEs9hTUX/cLQ==", + "funding": [ + { + "type": "github", + "url": "https://github.com/sponsors/mdevils" + }, + { + "type": "patreon", + "url": "https://patreon.com/mdevils" + } + ], + "license": "MIT" + }, "node_modules/ignore": { "version": "5.3.2", "resolved": "https://registry.npmjs.org/ignore/-/ignore-5.3.2.tgz", @@ -1044,6 +1159,15 @@ "js-yaml": "bin/js-yaml.js" } }, + "node_modules/jsdoc-type-pratt-parser": { + "version": "6.10.0", + "resolved": "https://registry.npmjs.org/jsdoc-type-pratt-parser/-/jsdoc-type-pratt-parser-6.10.0.tgz", + "integrity": "sha512-+LexoTRyYui5iOhJGn13N9ZazL23nAHGkXsa1p/C8yeq79WRfLBag6ZZ0FQG2aRoc9yfo59JT9EYCQonOkHKkQ==", + "license": "MIT", + "engines": { + "node": ">=20.0.0" + } + }, "node_modules/json-buffer": { "version": "3.0.1", "resolved": "https://registry.npmjs.org/json-buffer/-/json-buffer-3.0.1.tgz", @@ -1154,6 +1278,12 @@ "integrity": "sha512-OWND8ei3VtNC9h7V60qff3SVobHr996CTwgxubgyQYEpg290h9J0buyECNNJexkFm5sOajh5G116RYA1c8ZMSw==", "license": "MIT" }, + "node_modules/object-deep-merge": { + "version": "2.0.0", + "resolved": "https://registry.npmjs.org/object-deep-merge/-/object-deep-merge-2.0.0.tgz", + "integrity": "sha512-3DC3UMpeffLTHiuXSy/UG4NOIYTLlY9u3V82+djSCLYClWobZiS4ivYzpIUWrRY/nfsJ8cWsKyG3QfyLePmhvg==", + "license": "MIT" + }, "node_modules/optionator": { "version": "0.9.4", "resolved": "https://registry.npmjs.org/optionator/-/optionator-0.9.4.tgz", @@ -1213,6 +1343,21 @@ "node": ">=6" } }, + "node_modules/parse-imports-exports": { + "version": "0.2.4", + "resolved": "https://registry.npmjs.org/parse-imports-exports/-/parse-imports-exports-0.2.4.tgz", + "integrity": "sha512-4s6vd6dx1AotCx/RCI2m7t7GCh5bDRUtGNvRfHSP2wbBQdMi67pPe7mtzmgwcaQ8VKK/6IB7Glfyu3qdZJPybQ==", + "license": "MIT", + "dependencies": { + "parse-statements": "1.0.11" + } + }, + "node_modules/parse-statements": { + "version": "1.0.11", + "resolved": "https://registry.npmjs.org/parse-statements/-/parse-statements-1.0.11.tgz", + "integrity": "sha512-HlsyYdMBnbPQ9Jr/VgJ1YF4scnldvJpJxCVx6KgqPL4dxppsWrJHCIIxQXMJrqGnsRkNPATbeMJ8Yxu7JMsYcA==", + "license": "MIT" + }, "node_modules/path-exists": { "version": "4.0.0", "resolved": "https://registry.npmjs.org/path-exists/-/path-exists-4.0.0.tgz", @@ -1281,6 +1426,18 @@ ], "license": "MIT" }, + "node_modules/reserved-identifiers": { + "version": "1.2.0", + "resolved": "https://registry.npmjs.org/reserved-identifiers/-/reserved-identifiers-1.2.0.tgz", + "integrity": "sha512-yE7KUfFvaBFzGPs5H3Ops1RevfUEsDc5Iz65rOwWg4lE8HJSYtle77uul3+573457oHvBKuHYDl/xqUkKpEEdw==", + "license": "MIT", + "engines": { + "node": ">=18" + }, + "funding": { + "url": "https://github.com/sponsors/sindresorhus" + } + }, "node_modules/resolve-from": { "version": "4.0.0", "resolved": "https://registry.npmjs.org/resolve-from/-/resolve-from-4.0.0.tgz", @@ -1324,9 +1481,9 @@ } }, "node_modules/semver": { - "version": "7.7.2", - "resolved": "https://registry.npmjs.org/semver/-/semver-7.7.2.tgz", - "integrity": "sha512-RF0Fw+rO5AMf9MAyaRXI4AV0Ulj5lMHqVxxdSgiVbixSCXoEmmX/jk0CuJw4+3SqroYO9VoUh+HcuJivvtJemA==", + "version": "7.7.3", + "resolved": "https://registry.npmjs.org/semver/-/semver-7.7.3.tgz", + "integrity": "sha512-SdsKMrI9TdgjdweUSR9MweHA4EJ8YxHn8DFaDisvhVlUOe4BF1tLD7GAj0lIqWVl+dPb/rExr0Btby5loQm20Q==", "license": "ISC", "bin": { "semver": "bin/semver.js" @@ -1356,6 +1513,28 @@ "node": ">=8" } }, + "node_modules/spdx-exceptions": { + "version": "2.5.0", + "resolved": "https://registry.npmjs.org/spdx-exceptions/-/spdx-exceptions-2.5.0.tgz", + "integrity": "sha512-PiU42r+xO4UbUS1buo3LPJkjlO7430Xn5SVAhdpzzsPHsjbYVflnnFdATgabnLude+Cqu25p6N+g2lw/PFsa4w==", + "license": "CC-BY-3.0" + }, + "node_modules/spdx-expression-parse": { + "version": "4.0.0", + "resolved": "https://registry.npmjs.org/spdx-expression-parse/-/spdx-expression-parse-4.0.0.tgz", + "integrity": "sha512-Clya5JIij/7C6bRR22+tnGXbc4VKlibKSVj2iHvVeX5iMW7s1SIQlqu699JkODJJIhh/pUu8L0/VLh8xflD+LQ==", + "license": "MIT", + "dependencies": { + "spdx-exceptions": "^2.1.0", + "spdx-license-ids": "^3.0.0" + } + }, + "node_modules/spdx-license-ids": { + "version": "3.0.22", + "resolved": "https://registry.npmjs.org/spdx-license-ids/-/spdx-license-ids-3.0.22.tgz", + "integrity": "sha512-4PRT4nh1EImPbt2jASOKHX7PB7I+e4IWNLvkKFDxNhJlfjbYlleYQh285Z/3mPTHSAK/AvdMmw5BNNuYH8ShgQ==", + "license": "CC0-1.0" + }, "node_modules/strip-json-comments": { "version": "3.1.1", "resolved": "https://registry.npmjs.org/strip-json-comments/-/strip-json-comments-3.1.1.tgz", @@ -1392,6 +1571,22 @@ "node": ">=8.0" } }, + "node_modules/to-valid-identifier": { + "version": "1.0.0", + "resolved": "https://registry.npmjs.org/to-valid-identifier/-/to-valid-identifier-1.0.0.tgz", + "integrity": "sha512-41wJyvKep3yT2tyPqX/4blcfybknGB4D+oETKLs7Q76UiPqRpUJK3hr1nxelyYO0PHKVzJwlu0aCeEAsGI6rpw==", + "license": "MIT", + "dependencies": { + "@sindresorhus/base62": "^1.0.0", + "reserved-identifiers": "^1.0.0" + }, + "engines": { + "node": ">=20" + }, + "funding": { + "url": "https://github.com/sponsors/sindresorhus" + } + }, "node_modules/ts-api-utils": { "version": "2.1.0", "resolved": "https://registry.npmjs.org/ts-api-utils/-/ts-api-utils-2.1.0.tgz", diff --git a/specification/package.json b/specification/package.json index 59cd4de2b9..89534a95dc 100644 --- a/specification/package.json +++ b/specification/package.json @@ -8,6 +8,7 @@ "dependencies": { "@typescript-eslint/parser": "^8.32.1", "eslint": "^9.26.0", - "eslint-plugin-es-spec": "file:../validator" + "eslint-plugin-es-spec": "file:../validator", + "eslint-plugin-jsdoc": "^61.2.1" } } diff --git a/specification/security/get_service_credentials/GetServiceCredentialsResponse.ts b/specification/security/get_service_credentials/GetServiceCredentialsResponse.ts index f2f4550342..7aee1212f9 100644 --- a/specification/security/get_service_credentials/GetServiceCredentialsResponse.ts +++ b/specification/security/get_service_credentials/GetServiceCredentialsResponse.ts @@ -28,7 +28,8 @@ export class Response { count: integer tokens: Dictionary /** - * Service account credentials collected from all nodes of the cluster. */ + * Service account credentials collected from all nodes of the cluster. + */ nodes_credentials: NodesCredentials } } diff --git a/specification/security/has_privileges/types.ts b/specification/security/has_privileges/types.ts index 9b34d20063..517c0fad30 100644 --- a/specification/security/has_privileges/types.ts +++ b/specification/security/has_privileges/types.ts @@ -24,8 +24,10 @@ import { Dictionary } from '@spec_utils/Dictionary' export class ApplicationPrivilegesCheck { /** The name of the application. */ application: string - /** A list of the privileges that you want to check for the specified resources. - * It may be either application privilege names or the names of actions that are granted by those privileges */ + /** + * A list of the privileges that you want to check for the specified resources. + * It may be either application privilege names or the names of actions that are granted by those privileges + */ privileges: string[] /** A list of resource names against which the privileges should be checked. */ resources: string[] diff --git a/specification/security/oidc_authenticate/Request.ts b/specification/security/oidc_authenticate/Request.ts index 4e4bb7c32c..394fa748f0 100644 --- a/specification/security/oidc_authenticate/Request.ts +++ b/specification/security/oidc_authenticate/Request.ts @@ -45,7 +45,8 @@ export interface Request extends RequestBase { nonce: string /** * The name of the OpenID Connect realm. - * This property is useful in cases where multiple realms are defined. */ + * This property is useful in cases where multiple realms are defined. + */ realm?: string /** * The URL to which the OpenID Connect Provider redirected the User Agent in response to an authentication request after a successful authentication. diff --git a/specification/text_structure/find_message_structure/FindMessageStructureRequest.ts b/specification/text_structure/find_message_structure/FindMessageStructureRequest.ts index 58b0a5c8f4..af123f0d66 100644 --- a/specification/text_structure/find_message_structure/FindMessageStructureRequest.ts +++ b/specification/text_structure/find_message_structure/FindMessageStructureRequest.ts @@ -56,7 +56,8 @@ interface Request extends RequestBase { } ] query_parameters: { - /** If the format is `delimited`, you can specify the column names in a comma-separated list. + /** + * If the format is `delimited`, you can specify the column names in a comma-separated list. * If this parameter is not specified, the structure finder uses the column names from the header row of the text. * If the text does not have a header role, columns are named "column1", "column2", "column3", for example. */ diff --git a/specification/transform/put_transform/PutTransformRequest.ts b/specification/transform/put_transform/PutTransformRequest.ts index 0c8ef045a8..f507f82f24 100644 --- a/specification/transform/put_transform/PutTransformRequest.ts +++ b/specification/transform/put_transform/PutTransformRequest.ts @@ -70,7 +70,8 @@ export interface Request extends RequestBase { } ] path_parts: { - /** Identifier for the transform. This identifier can contain lowercase alphanumeric characters (a-z and 0-9), + /** + * Identifier for the transform. This identifier can contain lowercase alphanumeric characters (a-z and 0-9), * hyphens, and underscores. It has a 64 character limit and must start and end with alphanumeric characters. */ transform_id: Id From 3951a3f82c84c0d97ac65d491aeca60cd90f8f72 Mon Sep 17 00:00:00 2001 From: Quentin Pradet Date: Mon, 17 Nov 2025 16:11:32 +0400 Subject: [PATCH 2/2] Run make spec-format-fix --- specification/_global/index/IndexRequest.ts | 4 +- specification/eslint.config.js | 92 ++++++++++++--------- specification/ml/_types/inference.ts | 2 +- 3 files changed, 57 insertions(+), 41 deletions(-) diff --git a/specification/_global/index/IndexRequest.ts b/specification/_global/index/IndexRequest.ts index 9b01acb328..a00ed9af2f 100644 --- a/specification/_global/index/IndexRequest.ts +++ b/specification/_global/index/IndexRequest.ts @@ -147,13 +147,13 @@ import { Duration } from '@_types/Time' * } * } * ``` - * + * * In this example, the operation will succeed since the supplied version of 2 is higher than the current document version of 1. * If the document was already updated and its version was set to 2 or higher, the indexing command will fail and result in a conflict (409 HTTP status code). * * A nice side effect is that there is no need to maintain strict ordering of async indexing operations run as a result of changes to a source database, as long as version numbers from the source database are used. * Even the simple case of updating the Elasticsearch index using data from a database is simplified if external versioning is used, as only the latest version will be used if the index operations arrive out of order. - * + * * @rest_spec_name index * @availability stack stability=stable * @availability serverless stability=stable visibility=public diff --git a/specification/eslint.config.js b/specification/eslint.config.js index 46029ad68c..3579aa3315 100644 --- a/specification/eslint.config.js +++ b/specification/eslint.config.js @@ -18,8 +18,8 @@ */ import parser from '@typescript-eslint/parser' import validator from 'eslint-plugin-es-spec' +import { jsdoc } from 'eslint-plugin-jsdoc' import { defineConfig } from 'eslint/config' -import { jsdoc } from 'eslint-plugin-jsdoc'; export default defineConfig([ { @@ -52,7 +52,11 @@ export default defineConfig([ 'indices.update_aliases', 'watcher._types' ], - Actions: ['ilm._types', 'security.put_privileges', 'watcher._types'], + Actions: [ + 'ilm._types', + 'security.put_privileges', + 'watcher._types' + ], ComponentTemplate: ['cat.component_templates', 'cluster._types'], Context: [ '_global.get_script_context', @@ -68,7 +72,11 @@ export default defineConfig([ Feature: ['features._types', 'indices.get', 'xpack.info'], Features: ['indices.get', 'xpack.info'], Filter: ['_global.termvectors', 'ml._types'], - IndexingPressure: ['cluster.stats', 'indices._types', 'nodes._types'], + IndexingPressure: [ + 'cluster.stats', + 'indices._types', + 'nodes._types' + ], IndexingPressureMemory: ['indices._types', 'nodes._types'], Ingest: ['ingest._types', 'nodes._types'], MigrationFeature: [ @@ -125,45 +133,53 @@ export default defineConfig([ config: 'flat/recommended-typescript-error', rules: { // Allow custom tags used in Elasticsearch specification - 'jsdoc/check-tag-names': ['error', { - definedTags: [ - 'UpdateForV10', - 'aliases', - 'availability', - 'behavior', - 'behavior_meta', - 'class_serializer', - 'cluster_privileges', - 'codegen_name', - 'codegen_names', - 'doc_id', - 'doc_tag', - 'doc_url', - 'es_quirk', - 'ext_doc_id', - 'index_privileges', - 'non_exhaustive', - 'prop_serializer', - 'rest_spec_name', - 'server_default', - 'shortcut_property', - 'variant', - 'variants' - ], - }], + 'jsdoc/check-tag-names': [ + 'error', + { + definedTags: [ + 'UpdateForV10', + 'aliases', + 'availability', + 'behavior', + 'behavior_meta', + 'class_serializer', + 'cluster_privileges', + 'codegen_name', + 'codegen_names', + 'doc_id', + 'doc_tag', + 'doc_url', + 'es_quirk', + 'ext_doc_id', + 'index_privileges', + 'non_exhaustive', + 'prop_serializer', + 'rest_spec_name', + 'server_default', + 'shortcut_property', + 'variant', + 'variants' + ] + } + ], // Require UpdateForV10 tags to have an associated description/name - "jsdoc/match-name": ["error", { - match: [{ - "allowName":"/.+/","tags":["UpdateForV10"], - "message": "Please provide a reason for the breaking change" - }] - }], + 'jsdoc/match-name': [ + 'error', + { + match: [ + { + allowName: '/.+/', + tags: ['UpdateForV10'], + message: 'Please provide a reason for the breaking change' + } + ] + } + ], // Allow Markdown formatting 'jsdoc/tag-lines': 'off', 'jsdoc/no-multi-asterisks': 'off', // server_default values aren't parsed by jsdoc correctly - 'jsdoc/valid-types': 'off', - - }, + 'jsdoc/valid-types': 'off' + } }) ]) diff --git a/specification/ml/_types/inference.ts b/specification/ml/_types/inference.ts index 95b9903448..f5399ca57a 100644 --- a/specification/ml/_types/inference.ts +++ b/specification/ml/_types/inference.ts @@ -285,7 +285,7 @@ export class NerInferenceOptions { /** Fill mask inference options */ export class FillMaskInferenceOptions { - /** + /** * The string/token which will be removed from incoming documents and replaced with the inference prediction(s). * In a response, this field contains the mask token for the specified model/tokenizer. Each model and tokenizer * has a predefined mask token which cannot be changed. Thus, it is recommended not to set this value in requests.