Cleanup enum values, allow using identifier+value as an alternative to @codegen_name

[swallez]

This PR allows using the standard TypeScript enum syntax to define custom identifiers for enum members, in addition to the existing @codegen_name jsdoc tag.

Also cleans up the numeric values that existed on some enums for historical reasons (they were required in the early days of the API spec compiler) and refine the docs related to defining enums in the API spec.

Concretely, both definitions below are now equivalent (previously the z-score value was discarded, leading to a wrong declaration):

enum MyEnum {
    percent_of_sum,
    mean,
    softmax,
    /** @codegen_name z_score */
    'z-score'
}

and

enum MyEnum {
    percent_of_sum,
    mean,
    softmax,
    z_score = 'z-score'
}

Validation: compiling the API spec after these changes only produces specLocation changes in output/schema.json becaused of the removed jsdoc tags.

[ezimuel]

LGTM

[davidkyle]

ML changes LGTM

Thanks for updating

[github-actions]

Following you can find the validation results for the APIs you have changed.

API	Status	Request	Response
cat.transforms	🟢	5/5	5/5
ccr.follow_info	⚪	Missing test	Missing test
cluster.allocation_explain	🔴	5/5	1/5
enrich.execute_policy	🟢	7/7	7/7
eql.search	🔴	32/32	31/32
indices.add_block	🟢	2/2	2/2
indices.analyze	🟢	20/20	20/20
indices.clear_cache	🟢	4/4	4/4
indices.clone	🟢	5/5	5/5
indices.close	🔴	46/46	45/46
indices.create_data_stream	🔴	28/28	27/28
indices.create	🔴	815/830	826/830
indices.data_streams_stats	🟢	4/4	4/4
indices.delete_alias	🔴	15/15	11/15
indices.delete_data_lifecycle	⚪	Missing test	Missing test
indices.delete_data_stream	🔴	28/28	26/28
indices.delete_index_template	🟢	1/1	1/1
indices.delete_template	🟢	9/9	9/9
indices.delete	🔴	104/104	100/104
indices.disk_usage	🟢	5/5	5/5
indices.downsample	🟢	1/1	1/1
indices.exists_alias	🟢	36/36	36/36
indices.exists_index_template	⚪	Missing test	Missing test
indices.exists_template	🟢	15/15	15/15
indices.exists	🟢	39/39	39/39
indices.explain_data_lifecycle	⚪	Missing test	Missing test
indices.field_usage_stats	🟢	5/5	5/5
indices.flush	🟢	10/10	10/10
indices.forcemerge	🔴	5/5	4/5
indices.get_alias	🔴	83/83	70/83
indices.get_data_lifecycle	⚪	Missing test	Missing test
indices.get_data_stream	🔴	12/12	2/12
indices.get_field_mapping	🔴	15/15	13/15
indices.get_index_template	🔴	18/18	1/18
indices.get_mapping	🔴	90/90	80/90
indices.get_settings	🔴	56/56	54/56
indices.get_template	🟢	30/30	30/30
indices.get	🔴	53/53	41/53
indices.migrate_to_data_stream	⚪	Missing test	Missing test
indices.modify_data_stream	⚪	Missing test	Missing test
indices.open	🟢	18/18	18/18
indices.promote_data_stream	⚪	Missing test	Missing test
indices.put_alias	🟢	56/56	56/56
indices.put_data_lifecycle	⚪	Missing test	Missing test
indices.put_index_template	🔴	47/50	47/50
indices.put_mapping	🔴	73/74	73/74
indices.put_settings	🔴	54/57	57/57
indices.put_template	🔴	40/46	42/46
indices.recovery	🔴	9/9	8/9
indices.refresh	🟢	230/230	230/230
indices.reload_search_analyzers	🟢	2/2	2/2
indices.resolve_index	🔴	6/6	5/6
indices.rollover	🟢	26/26	26/26
indices.segments	🔴	6/6	4/6
indices.shard_stores	🔴	5/5	3/5
indices.shrink	🟢	5/5	5/5
indices.simulate_index_template	🟢	7/7	7/7
indices.simulate_template	🔴	5/5	4/5
indices.split	🟢	11/11	11/11
indices.stats	🔴	101/101	32/100
indices.unfreeze	🟢	1/1	1/1
indices.update_aliases	🔴	22/22	21/22
indices.validate_query	🟢	7/7	7/7
inference.delete_model	⚪	Missing test	Missing test
inference.get_model	🔴	1/1	0/1
inference.inference	⚪	Missing test	Missing test
inference.put_model	⚪	Missing test	Missing test
ingest.delete_pipeline	🟢	11/11	11/11
ingest.geo_ip_stats	⚪	Missing test	Missing test
ingest.get_pipeline	🔴	22/22	6/22
ingest.processor_grok	🟢	1/1	1/1
ingest.put_pipeline	🔴	33/42	40/42
ingest.simulate	🔴	0/7	6/7
license.delete	🟢	3/3	3/3
license.get_basic_status	🟢	3/3	3/3
license.get_trial_status	🟢	3/3	3/3
license.get	🟢	6/6	6/6
license.post_start_basic	🟢	5/5	5/5
license.post_start_trial	🟢	2/2	2/2
license.post	🟢	1/1	1/1
migration.deprecations	🟢	2/2	2/2
ml.clear_trained_model_deployment_cache	🟢	1/1	1/1
ml.close_job	🔴	64/64	59/63
ml.delete_calendar_event	🔴	4/4	3/4
ml.delete_calendar_job	🟢	3/3	3/3
ml.delete_calendar	🟢	5/5	5/5
ml.delete_data_frame_analytics	🔴	2/2	1/2
ml.delete_datafeed	🟢	3/3	3/3
ml.delete_expired_data	🔴	5/5	4/5
ml.delete_filter	🔴	27/27	24/27
ml.delete_forecast	🟢	3/3	3/3
ml.delete_job	🔴	47/47	46/47
ml.delete_model_snapshot	🔴	2/2	1/2
ml.delete_trained_model_alias	🔴	3/3	1/3
ml.delete_trained_model	🔴	3/3	2/3
ml.estimate_model_memory	🟢	16/16	16/16
ml.evaluate_data_frame	🔴	15/15	14/15
ml.explain_data_frame_analytics	🔴	7/7	6/7
ml.flush_job	🟢	15/15	15/15
ml.forecast	🟢	1/1	1/1
ml.get_buckets	🔴	14/14	11/14
ml.get_calendar_events	🔴	17/17	16/17
ml.get_calendars	🔴	17/17	15/17
ml.get_categories	🔴	12/12	11/12
ml.get_data_frame_analytics_stats	🔴	12/12	9/12
ml.get_data_frame_analytics	🔴	17/17	10/17
ml.get_datafeed_stats	🔴	27/27	25/27
ml.get_datafeeds	🔴	20/20	15/20
ml.get_filters	🔴	13/13	12/13
ml.get_influencers	🔴	11/11	10/11
ml.get_job_stats	🔴	32/32	30/32
ml.get_jobs	🔴	31/31	28/31
ml.get_memory_stats	🟢	6/6	6/6
ml.get_model_snapshot_upgrade_stats	🔴	3/3	1/3
ml.get_model_snapshots	🔴	18/18	17/18
ml.get_overall_buckets	🔴	16/16	13/15
ml.get_records	🔴	8/8	7/8
ml.get_trained_models_stats	🔴	17/17	8/17
ml.get_trained_models	🔴	31/37	29/37
ml.infer_trained_model	🔴	10/10	6/10
ml.info	🔴	10/10	2/10
ml.open_job	🔴	83/83	81/83
ml.post_calendar_events	🟢	21/21	21/21
ml.post_data	🔴	9/11	14/18
ml.preview_data_frame_analytics	🔴	3/3	2/3
ml.preview_datafeed	🔴	10/17	15/17
ml.put_calendar_job	🔴	11/12	12/12
ml.put_calendar	🔴	135/135	133/135
ml.put_data_frame_analytics	🔴	32/33	21/33
ml.put_datafeed	🔴	70/71	59/71
ml.put_filter	🟢	27/27	27/27
ml.put_job	🔴	219/227	224/225
ml.put_trained_model_alias	🔴	12/12	6/12
ml.put_trained_model_definition_part	⚪	Missing test	Missing test
ml.put_trained_model_vocabulary	⚪	Missing test	Missing test
ml.put_trained_model	🔴	10/14	5/14
ml.reset_job	🔴	2/2	1/2
ml.revert_model_snapshot	🔴	2/2	1/2
ml.set_upgrade_mode	🟢	6/6	6/6
ml.start_data_frame_analytics	🔴	1/1	0/1
ml.start_datafeed	🔴	24/24	19/24
ml.start_trained_model_deployment	🔴	13/13	0/13
ml.stop_data_frame_analytics	🔴	5/5	2/5
ml.stop_datafeed	🔴	17/17	14/17
ml.stop_trained_model_deployment	🔴	10/10	9/10
ml.update_data_frame_analytics	🔴	2/2	1/2
ml.update_datafeed	🔴	7/7	6/7
ml.update_filter	🔴	3/3	2/3
ml.update_job	🔴	4/5	5/5
ml.update_model_snapshot	🔴	3/3	1/3
ml.update_trained_model_deployment	🟠	Missing type	Missing type
ml.upgrade_job_snapshot	🔴	3/3	0/3
ml.validate_detector	🟢	2/2	2/2
ml.validate	🟢	3/3	3/3
rollup.get_jobs	🟢	12/12	12/12
search	🔴	1785/1849	1755/1831
searchable_snapshots.cache_stats	⚪	Missing test	Missing test
searchable_snapshots.clear_cache	🟢	1/1	1/1
searchable_snapshots.mount	🟢	4/4	4/4
searchable_snapshots.stats	🔴	1/1	0/1
security.activate_user_profile	🟢	8/8	8/8
security.authenticate	🔴	29/29	23/29
security.bulk_update_api_keys	🟠	Missing type	Missing type
security.change_password	🟢	9/9	9/9
security.clear_api_key_cache	🟢	13/13	13/13
security.clear_cached_privileges	🟢	3/3	3/3
security.clear_cached_realms	🟢	1/1	1/1
security.clear_cached_roles	🟢	2/2	2/2
security.clear_cached_service_tokens	🟢	4/4	4/4
security.create_api_key	🟢	55/55	46/46
security.create_cross_cluster_api_key	🟠	Missing type	Missing type
security.create_service_token	🟢	3/3	3/3
security.delete_privileges	🟢	6/6	6/6
security.delete_role_mapping	🟢	9/9	9/9
security.delete_role	🟢	8/8	8/8
security.delete_service_token	⚪	Missing test	Missing test
security.delete_user	🔴	9/9	8/9
security.disable_user_profile	🟢	1/1	1/1
security.disable_user	🟢	3/3	3/3
security.enable_user_profile	🟢	1/1	1/1
security.enable_user	🟢	4/4	4/4
security.enroll_kibana	⚪	Missing test	Missing test
security.enroll_node	⚪	Missing test	Missing test
security.get_api_key	🔴	37/37	12/37
security.get_builtin_privileges	🟢	2/2	2/2
security.get_privileges	🔴	12/12	11/12
security.get_role_mapping	🟢	18/18	18/18
security.get_role	🟢	20/20	20/20
security.get_service_accounts	⚪	Missing test	Missing test
security.get_service_credentials	🟢	1/1	1/1
security.get_settings	🟠	Missing type	Missing type
security.get_token	🟢	25/25	24/24
security.get_user_privileges	🟢	7/7	7/7
security.get_user_profile	🟢	8/8	8/8
security.get_user	🟢	25/25	25/25
security.grant_api_key	🔴	7/7	5/7
security.has_privileges_user_profile	🟢	3/3	3/3
security.has_privileges	🔴	24/24	22/24
security.invalidate_api_key	🔴	12/12	10/12
security.invalidate_token	🟢	11/11	11/11
security.oidc_authenticate	🟠	Missing type	Missing type
security.oidc_logout	🟠	Missing type	Missing type
security.oidc_prepare_authentication	🟠	Missing type	Missing type
security.put_privileges	🔴	10/10	9/10
security.put_role_mapping	🟢	11/11	11/11
security.put_role	🟢	39/39	38/38
security.put_user	🔴	48/48	46/47
security.query_api_keys	🔴	13/13	0/13
security.saml_authenticate	⚪	Missing test	Missing test
security.saml_complete_logout	⚪	Missing test	Missing test
security.saml_invalidate	⚪	Missing test	Missing test
security.saml_logout	⚪	Missing test	Missing test
security.saml_prepare_authentication	⚪	Missing test	Missing test
security.saml_service_provider_metadata	⚪	Missing test	Missing test
security.suggest_user_profiles	🟢	1/1	1/1
security.update_api_key	🟢	5/5	5/5
security.update_cross_cluster_api_key	🟠	Missing type	Missing type
security.update_settings	🟠	Missing type	Missing type
security.update_user_profile_data	🟢	1/1	1/1
snapshot.cleanup_repository	🟢	3/3	3/3
snapshot.clone	🟢	5/5	5/5
snapshot.create_repository	🟢	29/29	29/29
snapshot.create	🔴	26/26	25/26
snapshot.delete_repository	🟢	10/10	10/10
snapshot.delete	🟢	20/20	20/20
snapshot.get_repository	🟢	19/19	19/19
snapshot.get	🟢	13/13	13/13
snapshot.repository_analyze	🟠	Missing type	Missing type
snapshot.restore	🔴	5/5	3/5
snapshot.status	🟢	2/2	2/2
snapshot.verify_repository	🟢	2/2	2/2
watcher.ack_watch	🟢	1/1	1/1
watcher.activate_watch	🟢	1/1	1/1
watcher.deactivate_watch	🟢	1/1	1/1
watcher.delete_watch	🟢	2/2	2/2
watcher.execute_watch	🟢	7/7	7/7
watcher.get_settings	🟠	Missing type	Missing type
watcher.get_watch	🟢	9/9	9/9
watcher.put_watch	🔴	29/38	38/38
watcher.query_watches	⚪	Missing test	Missing test
watcher.start	🟢	1/1	1/1
watcher.stats	🟢	1/1	1/1
watcher.stop	🟢	1/1	1/1
watcher.update_settings	🟠	Missing type	Missing type

You can validate these APIs yourself by using the make validate target.

[github-actions]

The backport to 8.12 failed:

The process '/usr/bin/git' failed with exit code 1

To backport manually, run these commands in your terminal:

# Fetch latest updates from GitHub
git fetch
# Create a new working tree
git worktree add .worktrees/backport-8.12 8.12
# Navigate to the new working tree
cd .worktrees/backport-8.12
# Create a new branch
git switch --create backport-2379-to-8.12
# Cherry-pick the merged commit of this pull request and resolve the conflicts
git cherry-pick -x --mainline 1 7e140693f2bbd392b95f54f2cd2b0c0895db2e5d
# Push it to GitHub
git push --set-upstream origin backport-2379-to-8.12
# Go back to the original working tree
cd ../..
# Delete the working tree
git worktree remove .worktrees/backport-8.12

Then, create a pull request where the base branch is 8.12 and the compare/head branch is backport-2379-to-8.12.