feat(jco): add flag to enable tracing details (#150)

* feat(js-component-bindgen): add tracing flag

* feat(jco): add tracing flag

* chore: add test coverage for tracing flag

* chore: disable array buffer in stringify

* Update crates/js-component-bindgen/src/intrinsics.rs

---------

Co-authored-by: Eduardo Rodrigues <[email protected]>
Co-authored-by: Guy Bedford <[email protected]>

Author: eduardomourar

bin/self_build.rs

@@ -51,6 +51,7 @@ fn main() -> Result<()> {
             base64_cutoff: 5000_usize,
             tla_compat: true,
             valid_lifting_optimization: false,
+            tracing: false,
         };
 
         let transpiled = js_component_bindgen::transpile(&adapted_component, opts)?;

build.rs

@@ -35,6 +35,7 @@ fn main() -> Result<()> {
                 tla_compat: false,
                 valid_lifting_optimization: false,
                 base64_cutoff: 0,
+                tracing: false,
             };
 
             let files = generate_types(name, resolve, world, opts)?;

crates/js-component-bindgen-component/src/lib.rs

@@ -59,6 +59,7 @@ impl Guest for JsComponentBindgenComponent {
                 .tla_compat
                 .unwrap_or(options.compat.unwrap_or(false)),
             valid_lifting_optimization: options.valid_lifting_optimization.unwrap_or(false),
+            tracing: options.tracing.unwrap_or(false),
         };
 
         let js_component_bindgen::Transpiled {
@@ -129,6 +130,7 @@ impl Guest for JsComponentBindgenComponent {
             tla_compat: opts.tla_compat.unwrap_or(false),
             valid_lifting_optimization: false,
             base64_cutoff: 0,
+            tracing: false,
         };
 
         let files = generate_types(name, resolve, world, opts).map_err(|e| e.to_string())?;

crates/js-component-bindgen-component/wit/js-component-bindgen.wit

@@ -36,6 +36,9 @@ world js-component-bindgen {
     /// Disable verification of component Wasm data structures when
     /// lifting as a production optimization
     valid-lifting-optimization: option<bool>,
+
+    /// Whether or not to emit `tracing` calls on function entry/exit.
+    tracing: option<bool>,
   }
 
   variant wit {

crates/js-component-bindgen/src/function_bindgen.rs

@@ -62,6 +62,7 @@ pub struct FunctionBindgen<'a> {
     pub memory: Option<&'a String>,
     pub realloc: Option<&'a String>,
     pub post_return: Option<&'a String>,
+    pub tracing_prefix: Option<&'a String>,
     pub encoding: StringEncoding,
     pub callee: &'a str,
 }
@@ -1001,11 +1002,26 @@ impl Bindgen for FunctionBindgen<'_> {
             Instruction::IterBasePointer => results.push("base".to_string()),
 
             Instruction::CallWasm { sig, .. } => {
-                self.bind_results(sig.results.len(), results);
+                let sig_results_length = sig.results.len();
+                self.bind_results(sig_results_length, results);
                 uwriteln!(self.src, "{}({});", self.callee, operands.join(", "));
+
+                if let Some(prefix) = self.tracing_prefix {
+                    let to_result_string = self.intrinsic(Intrinsic::ToResultString);
+                    uwriteln!(
+                        self.src,
+                        "console.trace(`{prefix} return {}`);",
+                        if sig_results_length > 0 || !results.is_empty() {
+                            format!("result=${{{to_result_string}(ret)}}")
+                        } else {
+                            "".to_string()
+                        }
+                    );
+                }
             }
 
             Instruction::CallInterface { func } => {
+                let results_length = func.results.len();
                 if self.err == ErrHandling::ResultCatchHandler {
                     let err_payload = self.intrinsic(Intrinsic::GetErrorPayload);
                     uwriteln!(
@@ -1022,10 +1038,23 @@ impl Bindgen for FunctionBindgen<'_> {
                     );
                     results.push("ret".to_string());
                 } else {
-                    self.bind_results(func.results.len(), results);
+                    self.bind_results(results_length, results);
                     uwriteln!(self.src, "{}({});", self.callee, operands.join(", "));
                 }
 
+                if let Some(prefix) = self.tracing_prefix {
+                    let to_result_string = self.intrinsic(Intrinsic::ToResultString);
+                    uwriteln!(
+                        self.src,
+                        "console.trace(`{prefix} return {}`);",
+                        if results_length > 0 || !results.is_empty() {
+                            format!("result=${{{to_result_string}(ret)}}")
+                        } else {
+                            "".to_string()
+                        }
+                    );
+                }
+
                 // after a high level call, we need to deactivate the component resource borrows
                 if self.cur_resource_borrows.len() > 0 {
                     let resource_symbol = self.intrinsic(Intrinsic::ResourceSymbol);

crates/js-component-bindgen/src/intrinsics.rs

@@ -31,6 +31,7 @@ pub enum Intrinsic {
     ToInt32,
     /// Implementation of https://tc39.es/ecma262/#sec-toint8.
     ToInt8,
+    ToResultString,
     /// Implementation of https://tc39.es/ecma262/#sec-tostring.
     ToString,
     /// Implementation of https://tc39.es/ecma262/#sec-touint16.
@@ -96,6 +97,19 @@ pub fn render_intrinsics(
                 const hasOwnProperty = Object.prototype.hasOwnProperty;
             "),
 
+            Intrinsic::ToResultString => output.push_str("
+                function toResultString(obj) {
+                    return JSON.stringify(obj, (_, v) => {
+                        if (v && Object.getPrototypeOf(v) === Uint8Array.prototype) {
+                            return `[${v[Symbol.toStringTag]} (${v.byteLength})]`;
+                        } else if (typeof v === 'bigint') {
+                            return v.toString();
+                        }
+                        return v;
+                    });
+                }
+            "),
+
             Intrinsic::GetErrorPayload => {
                 let hop = Intrinsic::HasOwnProperty.name();
                 uwrite!(output, "
@@ -116,10 +130,10 @@ pub fn render_intrinsics(
                 }
             "),
 
-          Intrinsic::DataView => output.push_str("
-              let dv = new DataView(new ArrayBuffer());
-              const dataView = mem => dv.buffer === mem.buffer ? dv : dv = new DataView(mem.buffer);
-          "),
+            Intrinsic::DataView => output.push_str("
+                let dv = new DataView(new ArrayBuffer());
+                const dataView = mem => dv.buffer === mem.buffer ? dv : dv = new DataView(mem.buffer);
+            "),
 
             Intrinsic::FetchCompile => if !no_nodejs_compat {
                 output.push_str("
@@ -396,6 +410,7 @@ impl Intrinsic {
             Intrinsic::ToInt16 => "toInt16",
             Intrinsic::ToInt32 => "toInt32",
             Intrinsic::ToInt8 => "toInt8",
+            Intrinsic::ToResultString => "toResultString",
             Intrinsic::ToString => "toString",
             Intrinsic::ToUint16 => "toUint16",
             Intrinsic::ToUint32 => "toUint32",

crates/js-component-bindgen/src/transpile_bindgen.rs

@@ -56,6 +56,8 @@ pub struct TranspileOpts {
     /// Disable verification of component Wasm data structures when
     /// lifting as a production optimization
     pub valid_lifting_optimization: bool,
+    /// Whether or not to emit `tracing` calls on function entry/exit.
+    pub tracing: bool,
 }
 
 struct JsBindgen<'a> {
@@ -736,6 +738,11 @@ impl<'a> Instantiator<'a, '_> {
         self.bindgen(
             nparams,
             false,
+            if import_name.is_empty() {
+                None
+            } else {
+                Some(import_name)
+            },
             &callee_name,
             options,
             func,
@@ -850,6 +857,7 @@ impl<'a> Instantiator<'a, '_> {
         &mut self,
         nparams: usize,
         this_ref: bool,
+        module_name: Option<&str>,
         callee: &str,
         opts: &CanonicalOptions,
         func: &Function,
@@ -888,6 +896,26 @@ impl<'a> Instantiator<'a, '_> {
         }
         uwriteln!(self.src.js, ") {{");
 
+        let tracing_prefix = format!(
+            "[module=\"{}\", function=\"{}\"]",
+            module_name.unwrap_or("<no module>"),
+            func.name
+        );
+
+        if self.gen.opts.tracing {
+            let event_fields = func
+                .params
+                .iter()
+                .enumerate()
+                .map(|(i, (name, _ty))| format!("{name}=${{arguments[{i}]}}"))
+                .collect::<Vec<String>>();
+            uwriteln!(
+                self.src.js,
+                "console.trace(`{tracing_prefix} call {}`);",
+                event_fields.join(", ")
+            );
+        }
+
         if self.gen.opts.tla_compat && matches!(abi, AbiVariant::GuestExport) {
             let throw_uninitialized = self.gen.intrinsic(Intrinsic::ThrowUninitialized);
             uwrite!(
@@ -920,6 +948,11 @@ impl<'a> Instantiator<'a, '_> {
             tmp: 0,
             params,
             post_return: post_return.as_ref(),
+            tracing_prefix: if self.gen.opts.tracing {
+                Some(&tracing_prefix)
+            } else {
+                None
+            },
             encoding: match opts.string_encoding {
                 component::StringEncoding::Utf8 => StringEncoding::UTF8,
                 component::StringEncoding::Utf16 => StringEncoding::UTF16,
@@ -1100,6 +1133,7 @@ impl<'a> Instantiator<'a, '_> {
                         func,
                         existing_resource_def,
                         *ty,
+                        export_name,
                     );
                     if let FunctionKind::Constructor(ty)
                     | FunctionKind::Method(ty)
@@ -1156,6 +1190,7 @@ impl<'a> Instantiator<'a, '_> {
                             func,
                             existing_resource_def,
                             *ty,
+                            export_name,
                         );
 
                         if let FunctionKind::Constructor(ty)
@@ -1198,6 +1233,7 @@ impl<'a> Instantiator<'a, '_> {
         func: &Function,
         existing_resource_def: bool,
         ty_func_idx: TypeFuncIndex,
+        export_name: &String,
     ) {
         let resource_map = self.create_resource_map(func, ty_func_idx);
         match func.kind {
@@ -1247,6 +1283,11 @@ impl<'a> Instantiator<'a, '_> {
         self.bindgen(
             func.params.len(),
             matches!(func.kind, FunctionKind::Method(_)),
+            if export_name.is_empty() {
+                None
+            } else {
+                Some(export_name)
+            },
             &callee,
             options,
             func,

src/cmd/transpile.js

@@ -67,6 +67,7 @@ async function wasm2Js (source) {
  *   instantiation?: bool,
  *   map?: Record<string, string>,
  *   validLiftingOptimization?: bool,
+ *   tracing?: bool,
  *   noNodejsCompat?: bool,
  *   tlaCompat?: bool,
  *   base64Cutoff?: bool,
@@ -107,6 +108,7 @@ export async function transpileComponent (component, opts = {}) {
     map: Object.entries(opts.map ?? {}),
     instantiation: opts.instantiation || opts.js,
     validLiftingOptimization: opts.validLiftingOptimization ?? false,
+    tracing: opts.tracing ?? false,
     noNodejsCompat: !(opts.nodejsCompat ?? true),
     noTypescript: opts.noTypescript || false,
     tlaCompat: opts.tlaCompat ?? false,
@@ -369,4 +371,4 @@ function asmMangle (name) {
     }
   }
   return name;
-}
+}

src/jco.js

@@ -37,6 +37,7 @@ program.command('transpile')
   .option('-O, --optimize', 'optimize the component first')
   .option('--no-typescript', 'do not output TypeScript .d.ts types')
   .option('--valid-lifting-optimization', 'optimize component binary validations assuming all lifted values are valid')
+  .option('--tracing', 'emit `tracing` calls on function entry/exit')
   .option('-b, --base64-cutoff <bytes>', 'set the byte size under which core Wasm binaries will be inlined as base64', myParseInt)
   .option('--tla-compat', 'enables compatibility for JS environments without top-level await support via an async $init promise export')
   .option('--no-nodejs-compat', 'disables compatibility in Node.js without a fetch global')

test/cli.js

@@ -54,6 +54,21 @@ export async function cliTest (fixtures) {
       }
     });
 
+    test('Transpile with tracing', async () => {
+      try {
+        const name = 'flavorful';
+        const { stderr } = await exec(jcoPath, 'transpile', `test/fixtures/components/${name}.component.wasm`, '--name', name, '--map', 'testwasi=./wasi.js', '--tracing', '--base64-cutoff=0', '-o', outDir);
+        strictEqual(stderr, '');
+        const source = await readFile(`${outDir}/${name}.js`, 'utf8');
+        ok(source.includes('function toResultString('));
+        ok(source.includes('console.trace(`[module="test:flavorful/test", function="f-list-in-record1"] call a'));
+        ok(source.includes('console.trace(`[module="test:flavorful/test", function="list-of-variants"] return result=${toResultString(ret)}`);'));
+      }
+      finally {
+        await cleanup();
+      }
+    });
+
     test('Transpile to JS', async () => {
       try {
         const name = 'flavorful';