feat: warn when using --unstable, prefer granular flags (#21452)

This commit deprecates "--unstable" flag. 

When "--unstable" flag is encountered a warning like this is printed:
```
The `--unstable` flag is deprecated, use granular `--unstable-*` flags instead.
Learn more at: https://docs.deno.com/runtime/manual/tools/unstable_flags
```
When "--unstable" flag is used and an unstable API is called an
additional warning like this is printed for each API call:
```
The `Deno.dlopen` API was used with `--unstable` flag. The `--unstable` flag is deprecated, use granular `--unstable-ffi` instead. 
Learn more at: https://docs.deno.com/runtime/manual/tools/unstable_flags
```
When no "--unstable-*" flag is provided and an unstable API is called
following
warning is issued before exiting:
```
Unstable API 'Deno.dlopen'. The `--unstable-ffi` flag must be provided.
```

---------

Signed-off-by: Divy Srivastava <dj.srivastava23@gmail.com>
Signed-off-by: Bartek Iwańczuk <biwanczuk@gmail.com>
Co-authored-by: Divy Srivastava <dj.srivastava23@gmail.com>
Co-authored-by: Asher Gomez <ashersaupingomez@gmail.com>

1 files changed, 86 insertions, 0 deletions

diff --git a/runtime/lib.rs b/runtime/lib.rs
index 5aa4e21a1..fd791974d 100644
--- a/runtime/lib.rs
+++ b/runtime/lib.rs
@@ -43,3 +43,89 @@ pub use worker_bootstrap::WorkerLogLevel;
 
 mod shared;
 pub use shared::runtime;
+
+// NOTE(bartlomieju): keep IDs in sync with `runtime/90_deno_ns.js` (search for `unstableFeatures`)
+pub static UNSTABLE_GRANULAR_FLAGS: &[(
+  // flag name
+  &str,
+  // help text
+  &str,
+  // id to enable it in runtime/99_main.js
+  i32,
+)] = &[
+  (
+    deno_broadcast_channel::UNSTABLE_FEATURE_NAME,
+    "Enable unstable `BroadcastChannel` API",
+    1,
+  ),
+  (
+    deno_cron::UNSTABLE_FEATURE_NAME,
+    "Enable unstable Deno.cron API",
+    2,
+  ),
+  (
+    deno_ffi::UNSTABLE_FEATURE_NAME,
+    "Enable unstable FFI APIs",
+    3,
+  ),
+  (
+    deno_fs::UNSTABLE_FEATURE_NAME,
+    "Enable unstable file system APIs",
+    4,
+  ),
+  (
+    ops::http::UNSTABLE_FEATURE_NAME,
+    "Enable unstable HTTP APIs",
+    5,
+  ),
+  (
+    deno_kv::UNSTABLE_FEATURE_NAME,
+    "Enable unstable Key-Value store APIs",
+    6,
+  ),
+  (
+    deno_net::UNSTABLE_FEATURE_NAME,
+    "Enable unstable net APIs",
+    7,
+  ),
+  (
+    "temporal",
+    "Enable unstable Temporal API",
+    // Not used in JS
+    8,
+  ),
+  (
+    "unsafe-proto",
+    "Enable unsafe __proto__ support. This is a security risk.",
+    // This number is used directly in the JS code. Search
+    // for "unstableIds" to see where it's used.
+    9,
+  ),
+  (
+    deno_webgpu::UNSTABLE_FEATURE_NAME,
+    "Enable unstable `WebGPU` API",
+    10,
+  ),
+  (
+    ops::worker_host::UNSTABLE_FEATURE_NAME,
+    "Enable unstable Web Worker APIs",
+    11,
+  ),
+];
+
+#[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);
+  }
+}