feat: Added diagnostic links to error messages

cspell.config.js

@@ -119,7 +119,8 @@ export default {
     'shlv',
     'shrv',
     'sqrtv',
-    'hypot'
+    'hypot',
+    'mdocumentation'
   ],
   ignorePaths: [
     'node_modules/**',

docs/en/get-started/quick-usage.md

@@ -24,6 +24,53 @@ For Rust projects, configure `VmConfig` before creating the VM.
 
 :::
 
+## Diagnostic links
+
+Formatted VM errors include a `documentation:` metadata row by default. Its URL is derived from the error's `LVM` code and points to the matching page in the [error-code reference](/api-reference/error-codes/lvm001-code).
+
+Disable the row through the constructor configuration or the fluent API:
+
+::: code-group
+
+```rust [Native configuration]
+let vm = LightVM::new(VmConfig {
+  error_options: Some(ErrorOptions {
+    diagnostic_links: false,
+    ..Default::default()
+  }),
+  ..Default::default()
+});
+
+let vm = LightVM::new(VmConfig::default())
+  .with_diagnostic_links(false);
+```
+
+```ts [Node.js]
+const vm = new LightVM({
+  errorOptions: {
+    backtrace: false,
+    explain: false,
+    hint: true,
+    diagnosticLinks: false,
+  },
+});
+
+vm.withDiagnosticLinks(false);
+```
+
+```ts [WASM]
+const vm = new LightVM({
+  caps: [],
+  errorOptions: { diagnosticLinks: false },
+});
+
+vm.withDiagnosticLinks(false);
+```
+
+:::
+
+The same setting is retained by `tools()` and applies to errors from tool operations, including bytecode optimization.
+
 ## Expected result
 
 You have a configured VM instance ready to load bytecode. Continue with the [Run Method](/api-reference/method-functions/run-method), or review [Capabilities](/api-reference/capabilities) before granting access.

docs/examples/getStarted/builderPattern.ts

@@ -14,6 +14,7 @@ const vm = new LightVM({ caps: [Capability.Observe, Capability.Control] })
   .withNightly(false) // Allow nightly features (default: false)
   .withBacktrace(false) // Display backtrace details in error messages (default: false)
   .withExplain(false) // Display a more detailed hint in the error message (default: false)
-  .withHint(true); // Display a hint on error messages (default: true)
+  .withHint(true) // Display a hint on error messages (default: true)
+  .withDiagnosticLinks(false); // Hide links to error-code documentation (default: true)
 
 const tools = vm.tools();

docs/examples/getStarted/builder_pattern.rs

@@ -19,7 +19,8 @@ fn main() {
   .with_nightly(false) // Allow nightly features (default: false)
   .with_backtrace(false) // Display backtrace details in error messages (default: false)
   .with_explain(false) // Display a more detailed hint in the error message (default: false)
-  .with_hint(true); // Display a hint on error messages (default: true)
+  .with_hint(true) // Display a hint on error messages (default: true)
+  .with_diagnostic_links(false); // Hide links to error-code documentation (default: true)
 
   let tools = vm.tools();
-}
+}

docs/examples/getStarted/objectPattern.ts

@@ -9,6 +9,7 @@ const vm = new LightVM({
     backtrace: false, // Display backtrace details in error messages (default: false)
     explain: false, // Display a more detailed hint in the error message (default: false)
     hint: true, // Display a hint on error messages (default: true)
+    diagnosticLinks: false, // Hide links to error-code documentation (default: true)
   },
   securityConfig: {
     maxIo: 100, // Maximum number of I/O operations allowed (default: 100)

docs/examples/getStarted/object_pattern.rs

@@ -17,7 +17,8 @@ fn main() {
     error_options: Some(ErrorOptions {
       backtrace: false, // Display backtrace details in error messages (default: false)
       explain: false, // Display a more detailed hint in the error message (default: false)
-      hint: true // Display a hint on error messages (default: true)
+      hint: true, // Display a hint on error messages (default: true)
+      diagnostic_links: false // Hide links to error-code documentation (default: true)
     }),
     security_config: Some(SecurityConfig {
       max_io: 100, // Maximum number of I/O operations allowed (default: 100)
@@ -34,4 +35,4 @@ fn main() {
   });
 
   let tools = vm.tools();
-}
+}

docs/id/get-started/quick-usage.md

@@ -24,6 +24,53 @@ Untuk proyek Rust, konfigurasikan `VmConfig` sebelum membuat VM.
 
 :::
 
+## Tautan diagnostik
+
+Error VM yang diformat menyertakan baris metadata `documentation:` secara default. URL-nya berasal dari kode `LVM` error dan mengarah ke halaman yang sesuai dalam [referensi kode error](/id/api-reference/error-codes/lvm001-code).
+
+Nonaktifkan baris tersebut melalui konfigurasi konstruktor atau API fluent:
+
+::: code-group
+
+```rust [Native configuration]
+let vm = LightVM::new(VmConfig {
+  error_options: Some(ErrorOptions {
+    diagnostic_links: false,
+    ..Default::default()
+  }),
+  ..Default::default()
+});
+
+let vm = LightVM::new(VmConfig::default())
+  .with_diagnostic_links(false);
+```
+
+```ts [Node.js]
+const vm = new LightVM({
+  errorOptions: {
+    backtrace: false,
+    explain: false,
+    hint: true,
+    diagnosticLinks: false,
+  },
+});
+
+vm.withDiagnosticLinks(false);
+```
+
+```ts [WASM]
+const vm = new LightVM({
+  caps: [],
+  errorOptions: { diagnosticLinks: false },
+});
+
+vm.withDiagnosticLinks(false);
+```
+
+:::
+
+Pengaturan yang sama dipertahankan oleh `tools()` dan berlaku untuk error dari operasi alat, termasuk optimasi bytecode.
+
 ## Hasil yang diharapkan
 
 Anda memiliki instance VM terkonfigurasi yang siap memuat bytecode. Lanjutkan ke [Metode Run](/id/api-reference/method-functions/run-method), atau tinjau [Kapabilitas](/id/api-reference/capabilities) sebelum memberikan akses.

rust/src/interfaces/interface.rs

@@ -74,6 +74,7 @@ pub struct LightVM {
   pub backtrace: bool,
   pub explain: bool,
   pub hint: bool,
+  pub diagnostic_links: bool,
 }
 impl LightVM {
   pub fn new_node(
@@ -82,6 +83,7 @@ impl LightVM {
     backtrace: bool,
     explain: bool,
     hint: bool,
+    diagnostic_links: bool,
   ) -> Self {
     use crate::types::value::Value;
     use crate::types::vmstate::VmState;
@@ -114,6 +116,7 @@ impl LightVM {
       backtrace,
       explain,
       hint,
+      diagnostic_links,
     }
   }
   #[inline(always)]
@@ -126,8 +129,13 @@ impl LightVM {
     }
     Ok(())
   }
-  pub fn set_mode(&self, backtrace: bool, explain: bool, hint: bool) {
-    crate::modules::vmerror::config::set_thread_error_config(backtrace, explain, hint);
+  pub fn set_mode(&self, backtrace: bool, explain: bool, hint: bool, diagnostic_links: bool) {
+    crate::modules::vmerror::config::set_thread_error_config(
+      backtrace,
+      explain,
+      hint,
+      diagnostic_links,
+    );
   }
   pub fn index_metadata(&mut self) {
     self.functions.clear();
@@ -169,7 +177,12 @@ impl LightVM {
     get_versions()
   }
   pub fn load_internal(&mut self, source: String) -> Result<(), VMError> {
-    self.set_mode(self.backtrace, self.explain, self.hint);
+    self.set_mode(
+      self.backtrace,
+      self.explain,
+      self.hint,
+      self.diagnostic_links,
+    );
     crate::modules::vmerror::get_backtrace::clear_backtrace();
     if self.backtrace {
       crate::modules::vmerror::get_backtrace::capture_backtrace();
@@ -229,7 +242,12 @@ impl LightVM {
     Ok(())
   }
   pub fn run_internal(&mut self, options: Option<RunOptions>) -> Result<String, VMError> {
-    self.set_mode(self.backtrace, self.explain, self.hint);
+    self.set_mode(
+      self.backtrace,
+      self.explain,
+      self.hint,
+      self.diagnostic_links,
+    );
     crate::modules::vmerror::get_backtrace::clear_backtrace();
     if self.backtrace {
       crate::modules::vmerror::get_backtrace::capture_backtrace();
@@ -280,7 +298,12 @@ impl LightVM {
   }
   #[inline]
   pub fn compile_internal(&mut self, config: CompileConfig) -> Result<(), VMError> {
-    self.set_mode(self.backtrace, self.explain, self.hint);
+    self.set_mode(
+      self.backtrace,
+      self.explain,
+      self.hint,
+      self.diagnostic_links,
+    );
     crate::modules::vmerror::get_backtrace::clear_backtrace();
     if self.backtrace {
       crate::modules::vmerror::get_backtrace::capture_backtrace();
@@ -498,7 +521,12 @@ impl LightVM {
     bytecode_raw: serde_json::Value,
   ) -> Result<String, VMError> {
     self.require(Capability::Control)?;
-    self.set_mode(self.backtrace, self.explain, self.hint);
+    self.set_mode(
+      self.backtrace,
+      self.explain,
+      self.hint,
+      self.diagnostic_links,
+    );
     crate::modules::vmerror::get_backtrace::clear_backtrace();
     if self.backtrace {
       crate::modules::vmerror::get_backtrace::capture_backtrace();
@@ -642,6 +670,7 @@ mod tests {
       backtrace: false,
       explain: false,
       hint: true,
+      diagnostic_links: true,
     }
   }
   #[test]
@@ -904,7 +933,7 @@ mod tests {
     vm.backtrace = true;
     vm.explain = true;
     vm.hint = false;
-    set_thread_error_config(false, false, true);
+    set_thread_error_config(false, false, true, true);
     let before = get_thread_or_global_config();
     let result = vm.optimize_bytecode_internal(serde_json::json!([["noop"]]));
     let after = get_thread_or_global_config();

rust/src/interfaces/napi_interface.rs

@@ -103,6 +103,7 @@ impl NodeLightVM {
         backtrace: error_options.backtrace.unwrap_or(false),
         explain: error_options.explain.unwrap_or(false),
         hint: error_options.hint.unwrap_or(true),
+        diagnostic_links: error_options.diagnostic_links.unwrap_or(true),
       },
     })
   }
@@ -187,6 +188,11 @@ impl NodeLightVM {
     self.inner.hint = enabled;
     Ok(())
   }
+  #[napi(js_name = "withDiagnosticLinks")]
+  pub fn with_diagnostic_links(&mut self, enabled: bool) -> Result<()> {
+    self.inner.diagnostic_links = enabled;
+    Ok(())
+  }
   #[napi]
   pub fn info(&mut self) -> Result<JSInfoVM> {
     let info_vm = self.inner.info_internal();
@@ -561,6 +567,7 @@ impl NodeLightVM {
       is_backtrace,
       is_explain,
       is_hint,
+      self.inner.diagnostic_links,
     );
     vm_instance.caps = self
       .inner
@@ -599,6 +606,7 @@ impl NodeLightVM {
 #[cfg(test)]
 mod tests {
   use super::*;
+  use crate::types::js::js_error_options::JSErrorOptions;
   #[test]
   fn unknown_capability_uses_vm_error_display() {
     let config = VmNapiConfig {
@@ -717,4 +725,22 @@ mod tests {
       r#"[["stop"]]"#
     );
   }
+  #[test]
+  fn diagnostic_links_can_be_configured_and_updated() {
+    let mut vm = NodeLightVM::napi_new(VmNapiConfig {
+      error_options: Some(JSErrorOptions {
+        diagnostic_links: Some(false),
+        ..Default::default()
+      }),
+      ..Default::default()
+    })
+    .expect("expected a VM");
+    assert!(!vm.inner.diagnostic_links);
+    vm.with_diagnostic_links(true)
+      .expect("expected the setting to update");
+    assert!(vm.inner.diagnostic_links);
+    vm.with_diagnostic_links(false)
+      .expect("expected the setting to update");
+    assert!(!vm.inner.diagnostic_links);
+  }
 }