fix: display unstable flags at bottom of help text (#21468)

Moves the unstable flags to be at the bottom of the help text. They were
previously all over the place for some reason.

4 files changed, 62 insertions, 38 deletions

diff --git a/cli/args/flags.rs b/cli/args/flags.rs
index 4801737a8..5a77c8bb2 100644
--- a/cli/args/flags.rs
+++ b/cli/args/flags.rs
@@ -946,6 +946,8 @@ fn clap_root() -> Command {
     .max_term_width(80)
     .version(crate::version::deno())
     .long_version(long_version)
+    // cause --unstable flags to display at the bottom of the help text
+    .next_display_order(1000)
     .arg(
       Arg::new("unstable")
         .long("unstable")
@@ -992,6 +994,8 @@ fn clap_root() -> Command {
   }
 
   cmd
+    // reset the display order after the unstable flags
+    .next_display_order(0)
     .arg(
       Arg::new("log-level")
         .short('L')
diff --git a/cli/main.rs b/cli/main.rs
index bd29dc532..c95e5dc37 100644
--- a/cli/main.rs
+++ b/cli/main.rs
@@ -271,7 +271,7 @@ fn unwrap_or_exit<T>(result: Result<T, AnyError>) -> T {
   }
 }
 
-// NOTE(bartlomieju): keep IDs in sync with `runtime/90_deno_ns.js`.
+// NOTE(bartlomieju): keep IDs in sync with `runtime/90_deno_ns.js` (search for `unstableFeatures`)
 pub(crate) static UNSTABLE_GRANULAR_FLAGS: &[(
   // flag name
   &str,
@@ -286,43 +286,45 @@ pub(crate) static UNSTABLE_GRANULAR_FLAGS: &[(
     1,
   ),
   (
-    deno_runtime::deno_ffi::UNSTABLE_FEATURE_NAME,
-    "Enable unstable FFI APIs",
+    deno_runtime::deno_cron::UNSTABLE_FEATURE_NAME,
+    "Enable unstable Deno.cron API",
     2,
   ),
   (
-    deno_runtime::deno_fs::UNSTABLE_FEATURE_NAME,
-    "Enable unstable file system APIs",
+    deno_runtime::deno_ffi::UNSTABLE_FEATURE_NAME,
+    "Enable unstable FFI APIs",
     3,
   ),
   (
-    deno_runtime::deno_kv::UNSTABLE_FEATURE_NAME,
-    "Enable unstable Key-Value store APIs",
+    deno_runtime::deno_fs::UNSTABLE_FEATURE_NAME,
+    "Enable unstable file system APIs",
     4,
   ),
   (
-    deno_runtime::deno_net::UNSTABLE_FEATURE_NAME,
-    "Enable unstable net APIs",
+    deno_runtime::ops::http::UNSTABLE_FEATURE_NAME,
+    "Enable unstable HTTP APIs",
     5,
   ),
   (
-    deno_runtime::ops::http::UNSTABLE_FEATURE_NAME,
-    "Enable unstable HTTP APIs",
+    deno_runtime::deno_kv::UNSTABLE_FEATURE_NAME,
+    "Enable unstable Key-Value store APIs",
     6,
   ),
   (
-    deno_runtime::ops::worker_host::UNSTABLE_FEATURE_NAME,
-    "Enable unstable Web Worker APIs",
+    deno_runtime::deno_net::UNSTABLE_FEATURE_NAME,
+    "Enable unstable net APIs",
     7,
   ),
   (
-    deno_runtime::deno_cron::UNSTABLE_FEATURE_NAME,
-    "Enable unstable Deno.cron API",
+    "unsafe-proto",
+    "Enable unsafe __proto__ support. This is a security risk.",
+    // This number is used directly in the JS code. Search
+    // for "unstableFeatures" to see where it's used.
     8,
   ),
   (
-    "unsafe-proto",
-    "Enable unsafe __proto__ support. This is a security risk.",
+    deno_runtime::ops::worker_host::UNSTABLE_FEATURE_NAME,
+    "Enable unstable Web Worker APIs",
     9,
   ),
 ];
@@ -402,3 +404,20 @@ pub fn main() {
 
   std::process::exit(exit_code);
 }
+
+#[cfg(test)]
+mod test {
+  use super::*;
+
+  #[test]
+  fn unstable_granular_flag_names_sorted() {
+    let flags = UNSTABLE_GRANULAR_FLAGS
+      .iter()
+      .map(|(name, _, _)| name.to_string())
+      .collect::<Vec<_>>();
+    let mut sorted_flags = flags.clone();
+    sorted_flags.sort();
+    // sort the flags by name so they appear nicely in the help text
+    assert_eq!(flags, sorted_flags);
+  }
+}
diff --git a/runtime/js/90_deno_ns.js b/runtime/js/90_deno_ns.js
index bd664d2ea..5ab56d8d7 100644
--- a/runtime/js/90_deno_ns.js
+++ b/runtime/js/90_deno_ns.js
@@ -159,8 +159,12 @@ const denoNsUnstableById = {
   // BroadcastChannel is always available?
   // 1: {},
 
-  // FFI
   2: {
+    cron: cron.cron,
+  },
+
+  // FFI
+  3: {
     dlopen: ffi.dlopen,
     UnsafeCallback: ffi.UnsafeCallback,
     UnsafePointer: ffi.UnsafePointer,
@@ -169,7 +173,7 @@ const denoNsUnstableById = {
   },
 
   // FS
-  3: {
+  4: {
     flock: fs.flock,
     flockSync: fs.flockSync,
     funlock: fs.funlock,
@@ -177,8 +181,17 @@ const denoNsUnstableById = {
     umask: fs.umask,
   },
 
+  // HTTP
+  5: {
+    HttpClient: httpClient.HttpClient,
+    createHttpClient: httpClient.createHttpClient,
+    // TODO(bartlomieju): why is it needed?
+    http,
+    upgradeHttp: http.upgradeHttp,
+  },
+
   // KV
-  4: {
+  6: {
     openKv: kv.openKv,
     AtomicOperation: kv.AtomicOperation,
     Kv: kv.Kv,
@@ -187,29 +200,17 @@ const denoNsUnstableById = {
   },
 
   // net
-  5: {
+  7: {
     listenDatagram: net.createListenDatagram(
       ops.op_net_listen_udp,
       ops.op_net_listen_unixpacket,
     ),
   },
+  // Unsafe proto
+  // 8: {},
 
-  // HTTP
-  6: {
-    HttpClient: httpClient.HttpClient,
-    createHttpClient: httpClient.createHttpClient,
-    // TODO(bartlomieju): why is it needed?
-    http,
-    upgradeHttp: http.upgradeHttp,
-  },
   // Worker options
-  // 7: {}
-
-  8: {
-    cron: cron.cron,
-  },
-  // Unsafe proto
-  // 9: {},
+  // 9: {}
 };
 
 // when editing this list, also update unstableDenoProps in cli/tsc/99_main_compiler.js
diff --git a/runtime/js/99_main.js b/runtime/js/99_main.js
index 67667427f..6e43da085 100644
--- a/runtime/js/99_main.js
+++ b/runtime/js/99_main.js
@@ -567,7 +567,7 @@ function bootstrapMainRuntime(runtimeOptions) {
     }
   }
 
-  if (!ArrayPrototypeIncludes(unstableFeatures, /* unsafe-proto */ 9)) {
+  if (!ArrayPrototypeIncludes(unstableFeatures, /* unsafe-proto */ 8)) {
     // Removes the `__proto__` for security reasons.
     // https://tc39.es/ecma262/#sec-get-object.prototype.__proto__
     delete Object.prototype.__proto__;
@@ -672,7 +672,7 @@ function bootstrapWorkerRuntime(
     }
   }
 
-  if (!ArrayPrototypeIncludes(unstableFeatures, /* unsafe-proto */ 9)) {
+  if (!ArrayPrototypeIncludes(unstableFeatures, /* unsafe-proto */ 8)) {
     // Removes the `__proto__` for security reasons.
     // https://tc39.es/ecma262/#sec-get-object.prototype.__proto__
     delete Object.prototype.__proto__;