Add more context on preflight mode

tooling/nargo_cli/src/cli/dap_cmd.rs

@@ -27,7 +27,6 @@ use noir_debugger::errors::{DapError, LoadError};
 
 #[derive(Debug, Clone, Args)]
 pub(crate) struct DapCommand {
-    /// Write the execution witness to named file
     #[clap(long)]
     preflight_check: bool,
 
@@ -111,9 +110,7 @@ fn load_and_compile_project(
     let (inputs_map, _) =
         read_inputs_from_file(&package.root_dir, prover_name, Format::Toml, &compiled_program.abi)
             .map_err(|_| {
-                LoadError::Generic(
-                    format!("Failed to read program inputs from {}", prover_name),
-                )
+                LoadError::Generic(format!("Failed to read program inputs from {}", prover_name))
             })?;
     let initial_witness = compiled_program
         .abi
@@ -242,6 +239,18 @@ pub(crate) fn run(
     args: DapCommand,
     _config: NargoConfig,
 ) -> Result<(), CliError> {
+    // When the --preflight-check flag is present, we run Noir's DAP server in "pre-flight mode", which test runs
+    // the DAP initialization code without actually starting the DAP server.
+    //
+    // This lets the client IDE present any initialization issues (compiler version mismatches, missing prover files, etc)
+    // in its own interface.
+    //
+    // This was necessary due to the VS Code project being reluctant to let extension authors capture
+    // stderr output generated by a DAP server wrapped in DebugAdapterExecutable.
+    //
+    // Exposing this preflight mode lets us gracefully handle errors that happen *before*
+    // the DAP loop is established, which otherwise are considered "out of band" by the maintainers of the DAP spec.
+    // More details here: https://github.com/microsoft/vscode/issues/108138
     if args.preflight_check {
         return run_preflight_check(backend, args).map_err(CliError::DapError);
     }