Codegen: add --vscode-extension flag to inline extraImports wiring (#116)

Closes #105.

The Node-CJS codegen emitted a shim with an empty extraImports hook that
every consumer hand-wired in a separate index.cjs to install the concrete
vscode-API bindings. That boilerplate was 100% mechanical and identical
across consumers.

Add a --vscode-extension codegen flag that inlines the wiring so the
generated .cjs is directly loadable as a VS Code extension's `main`:
installs exports.extraImports calling the @hyperpolymath/affine-vscode
adapter. Sub-flags --vscode-extension-adapter (override the require
specifier) and --vscode-extension-no-lc (no language client; pass null)
cover the documented variants.

Migrate the editors/vscode pilot off the would-be hand-written index.cjs:
its compile script now passes --vscode-extension and the regenerated
out/extension.cjs carries the inline glue; package.json declares the
adapter dependency.

https://claude.ai/code/session_01FkzAgzpZFSGxzorVNZ9FUF

Co-authored-by: Claude <noreply@anthropic.com>

Author: hyperpolymath

bin/main.ml

@@ -477,7 +477,8 @@ let repl_cmd_fn () =
 (** Compile a file.  With [--json], emits diagnostics for any
     compilation errors.  With [--wasm-gc], targets the WebAssembly GC
     proposal instead of WASM 1.0 linear memory. *)
-let compile_file face json wasm_gc path output =
+let compile_file face json wasm_gc vscode_ext vscode_adapter vscode_no_lc
+    path output =
   let face = resolve_face ~quiet:json face path in
   if json then begin
     let diags = ref [] in
@@ -659,7 +660,13 @@ let compile_file face json wasm_gc path output =
                         (Affinescript.Codegen.show_codegen_error e);
                       span = Affinescript.Span.dummy; help = None; labels = [] }
               | Ok wasm_module ->
-                let cjs = Affinescript.Codegen_node.emit_node_cjs wasm_module in
+                let cjs =
+                  Affinescript.Codegen_node.emit_node_cjs
+                    ~vscode_extension:vscode_ext
+                    ?vscode_extension_adapter:vscode_adapter
+                    ~vscode_extension_no_lc:vscode_no_lc
+                    wasm_module
+                in
                 let oc = open_out output in
                 output_string oc cjs;
                 close_out oc
@@ -873,11 +880,18 @@ let compile_file face json wasm_gc path output =
                   (Affinescript.Codegen.show_codegen_error e);
                 `Error (false, "Node-CJS codegen error")
               | Ok wasm_module ->
-                let cjs = Affinescript.Codegen_node.emit_node_cjs wasm_module in
+                let cjs =
+                  Affinescript.Codegen_node.emit_node_cjs
+                    ~vscode_extension:vscode_ext
+                    ?vscode_extension_adapter:vscode_adapter
+                    ~vscode_extension_no_lc:vscode_no_lc
+                    wasm_module
+                in
                 let oc = open_out output in
                 output_string oc cjs;
                 close_out oc;
-                Format.printf "Compiled %s -> %s (Node-CJS)@." path output;
+                Format.printf "Compiled %s -> %s (Node-CJS%s)@." path output
+                  (if vscode_ext then ", --vscode-extension" else "");
                 `Ok ())
             else
               let optimized_prog = Affinescript.Opt.fold_constants_program prog in
@@ -1141,6 +1155,29 @@ let wasm_gc_arg =
           Requires a runtime that supports the GC proposal: V8/Chrome ≥ 119, \
           SpiderMonkey/Firefox ≥ 120, or Wasmtime with --wasm-features gc.")
 
+(* Issue #105: --vscode-extension and its sub-flags. Only meaningful when
+   the output is a [.cjs] Node-CJS shim; ignored for other targets. *)
+let vscode_ext_arg =
+  Arg.(value & flag & info ["vscode-extension"]
+    ~doc:"When emitting a Node-CJS shim (.cjs output), inline the vscode-API \
+          wiring so the generated file is directly loadable as a VS Code \
+          extension's `main` — no hand-written index.cjs or vendored adapter. \
+          Installs exports.extraImports calling the \
+          @hyperpolymath/affine-vscode adapter.")
+
+let vscode_adapter_arg =
+  Arg.(value & opt (some string) None & info ["vscode-extension-adapter"]
+    ~docv:"SPECIFIER"
+    ~doc:"Override the require() specifier for the vscode adapter used by \
+          --vscode-extension (default: @hyperpolymath/affine-vscode). Useful \
+          for testing against a local checkout or vendoring a custom adapter.")
+
+let vscode_no_lc_arg =
+  Arg.(value & flag & info ["vscode-extension-no-lc"]
+    ~doc:"With --vscode-extension, omit the vscode-languageclient/node \
+          dependency for extensions that ship no language client; the \
+          wiring passes null in its place.")
+
 (** Shared --face flag: select the parser surface-syntax face. *)
 let face_arg =
   let faces = Arg.enum [
@@ -1486,7 +1523,9 @@ let repl_cmd =
 let compile_cmd =
   let doc = "Compile a file to WebAssembly (1.0 or GC proposal), Julia (.jl), JavaScript (.js), C (.c), a WGSL compute kernel (.wgsl), a Faust DSP program (.dsp), or an ONNX model (.onnx)" in
   let info = Cmd.info "compile" ~doc in
-  Cmd.v info Term.(ret (const compile_file $ face_arg $ json_arg $ wasm_gc_arg $ path_arg $ output_arg))
+  Cmd.v info Term.(ret (const compile_file $ face_arg $ json_arg $ wasm_gc_arg
+    $ vscode_ext_arg $ vscode_adapter_arg $ vscode_no_lc_arg
+    $ path_arg $ output_arg))
 
 let fmt_cmd =
   let doc = "Format a file" in

editors/vscode/out/extension.cjs

@@ -94,3 +94,15 @@ exports.deactivate = async function deactivate() {
 exports._registerHandle = _registerHandle;
 exports._getHandle = _getHandle;
 exports._freeHandle = _freeHandle;
+
+// Inserted by --vscode-extension (issue #105): auto-generated glue so this
+// file is directly loadable as a VS Code extension's `main`. Replaces the
+// previously hand-written index.cjs + vendored adapter boilerplate.
+const _makeVscodeBindings = require("@hyperpolymath/affine-vscode");
+exports.extraImports = function() {
+  return _makeVscodeBindings(
+    require("vscode"),
+    require("vscode-languageclient/node"),
+    exports,
+  );
+};

editors/vscode/package.json

@@ -135,7 +135,7 @@
   },
   "scripts": {
     "vscode:prepublish": "npm run compile",
-    "compile": "affinescript compile src/extension.affine -o out/extension.cjs",
+    "compile": "affinescript compile src/extension.affine -o out/extension.cjs --vscode-extension",
     "watch": "echo 'watch mode not implemented for AffineScript source — re-run npm run compile'",
     "guard": "../../tools/check-no-extension-ts.sh",
     "package": "vsce package",
@@ -146,6 +146,7 @@
     "vsce": "^2.15.0"
   },
   "dependencies": {
+    "@hyperpolymath/affine-vscode": "^0.1.0",
     "vscode-languageclient": "^9.0.0"
   }
 }

lib/codegen_node.ml

@@ -96,16 +96,85 @@ let encode_module_to_bytes (m : wasm_module) : bytes =
   ) m.custom_sections;
   Bytes.of_string (Buffer.contents buf)
 
+(** Escape a string for embedding inside a JS double-quoted literal. Only
+    the characters that would break out of (or corrupt) the literal are
+    escaped — sufficient for require() specifiers and module paths. *)
+let js_string_escape (s : string) : string =
+  let buf = Buffer.create (String.length s + 8) in
+  String.iter (fun c ->
+    match c with
+    | '\\' -> Buffer.add_string buf "\\\\"
+    | '"'  -> Buffer.add_string buf "\\\""
+    | '\n' -> Buffer.add_string buf "\\n"
+    | '\r' -> Buffer.add_string buf "\\r"
+    | c    -> Buffer.add_char buf c
+  ) s;
+  Buffer.contents buf
+
+(** Default npm specifier for the vscode-API adapter (issue #105). Callers
+    can override it via [~vscode_extension_adapter]. *)
+let default_vscode_adapter = "@hyperpolymath/affine-vscode"
+
+(** Build the [--vscode-extension] wiring block (issue #105).
+
+    Returns the JS that installs [exports.extraImports] so the generated
+    [.cjs] is directly loadable as a VS Code extension's [main] — no
+    hand-written [index.cjs], no vendored adapter. [adapter] is the
+    require() specifier for the adapter; when [no_lc] is set the extension
+    ships no language client, so the [vscode-languageclient/node] require
+    is skipped and [null] is passed in its place. *)
+let vscode_extension_wiring ~(adapter : string) ~(no_lc : bool) : string =
+  let lc_arg =
+    if no_lc then "null"
+    else {|require("vscode-languageclient/node")|}
+  in
+  Printf.sprintf {|
+// Inserted by --vscode-extension (issue #105): auto-generated glue so this
+// file is directly loadable as a VS Code extension's `main`. Replaces the
+// previously hand-written index.cjs + vendored adapter boilerplate.
+const _makeVscodeBindings = require("%s");
+exports.extraImports = function() {
+  return _makeVscodeBindings(
+    require("vscode"),
+    %s,
+    exports,
+  );
+};
+|} (js_string_escape adapter) lc_arg
+
 (** Wrap [m] in a Node-CJS shim. The shim is a single self-contained
-    JavaScript string suitable for writing to a [.cjs] file. *)
-let emit_node_cjs ?(extra_imports_js : string option) (m : wasm_module) : string =
+    JavaScript string suitable for writing to a [.cjs] file.
+
+    When [~vscode_extension:true] (issue #105), the shim additionally
+    installs [exports.extraImports] inline so the output is directly
+    loadable as a VS Code extension's [main]. [~vscode_extension_adapter]
+    overrides the adapter require() specifier (default
+    {!default_vscode_adapter}); [~vscode_extension_no_lc] omits the
+    [vscode-languageclient/node] dependency for extensions that ship no
+    language client. *)
+let emit_node_cjs
+    ?(extra_imports_js : string option)
+    ?(vscode_extension : bool = false)
+    ?(vscode_extension_adapter : string option)
+    ?(vscode_extension_no_lc : bool = false)
+    (m : wasm_module) : string =
   let wasm_bytes = encode_module_to_bytes m in
   let b64 = base64_encode wasm_bytes in
   let extra =
     match extra_imports_js with
     | Some js -> js
     | None -> "{}"
   in
+  let vscode_block =
+    if vscode_extension then
+      let adapter =
+        match vscode_extension_adapter with
+        | Some a -> a
+        | None -> default_vscode_adapter
+      in
+      vscode_extension_wiring ~adapter ~no_lc:vscode_extension_no_lc
+    else ""
+  in
   Printf.sprintf {|// Generated by AffineScript. Do not edit.
 // Node-CJS shim wrapping the compiled .wasm module so VS Code's extension
 // host (or any CJS consumer) can require() it directly.
@@ -202,4 +271,4 @@ exports.deactivate = async function deactivate() {
 exports._registerHandle = _registerHandle;
 exports._getHandle = _getHandle;
 exports._freeHandle = _freeHandle;
-|} b64 extra
+%s|} b64 extra vscode_block

test/test_e2e.ml

@@ -2822,9 +2822,89 @@ let test_node_cjs_base64_roundtrip () =
   Alcotest.(check string) "matches RFC 4648 §10 vector"
     "TWFueSBoYW5kcyBtYWtlIGxpZ2h0IHdvcmsu" b64
 
+(* ---- Issue #105: --vscode-extension inline wiring ----
+
+   Verifies that emit_node_cjs ~vscode_extension:true inlines the
+   exports.extraImports glue (calling the @hyperpolymath/affine-vscode
+   adapter) so the generated .cjs is directly loadable as a VS Code
+   extension's `main` — no hand-written index.cjs / vendored adapter. *)
+
+let contains s sub =
+  let n = String.length sub and m = String.length s in
+  let rec scan i = i + n <= m && (String.sub s i n = sub || scan (i + 1)) in
+  n = 0 || scan 0
+
+let cjs_of ?vscode_extension ?vscode_extension_adapter
+    ?vscode_extension_no_lc src =
+  let prog = parse_string_for_gc src in
+  match Codegen.generate_module prog with
+  | Error e -> Alcotest.failf "wasm codegen failed: %s" (Codegen.show_codegen_error e)
+  | Ok wasm_module ->
+    Codegen_node.emit_node_cjs ?vscode_extension ?vscode_extension_adapter
+      ?vscode_extension_no_lc wasm_module
+
+let activate_src =
+  {|pub fn activate(ctx_handle: Int) -> Int { return 0; }
+    pub fn deactivate() -> Int { return 0; }|}
+
+let test_vscode_extension_off_by_default () =
+  let cjs = cjs_of activate_src in
+  Alcotest.(check bool) "no extraImports assignment without the flag"
+    false (contains cjs "exports.extraImports = function");
+  Alcotest.(check bool) "no adapter require without the flag"
+    false (contains cjs "@hyperpolymath/affine-vscode")
+
+let test_vscode_extension_inlines_wiring () =
+  let cjs = cjs_of ~vscode_extension:true activate_src in
+  Alcotest.(check bool) "installs exports.extraImports"
+    true (contains cjs "exports.extraImports = function");
+  Alcotest.(check bool) "requires the default adapter"
+    true (contains cjs {|require("@hyperpolymath/affine-vscode")|});
+  Alcotest.(check bool) "requires the vscode module"
+    true (contains cjs {|require("vscode")|});
+  Alcotest.(check bool) "requires the language client"
+    true (contains cjs {|require("vscode-languageclient/node")|});
+  Alcotest.(check bool) "passes exports as the host shim"
+    true (contains cjs "exports,\n  );");
+  (* The base shim (use strict, activate, handle table) is still present. *)
+  Alcotest.(check bool) "base shim still intact"
+    true (contains cjs "exports._registerHandle")
+
+let test_vscode_extension_adapter_override () =
+  let cjs = cjs_of ~vscode_extension:true
+      ~vscode_extension_adapter:"../local/adapter.cjs" activate_src in
+  Alcotest.(check bool) "uses the overridden adapter specifier"
+    true (contains cjs {|require("../local/adapter.cjs")|});
+  Alcotest.(check bool) "does not fall back to the default adapter"
+    false (contains cjs "@hyperpolymath/affine-vscode")
+
+let test_vscode_extension_no_lc () =
+  let cjs = cjs_of ~vscode_extension:true ~vscode_extension_no_lc:true
+      activate_src in
+  Alcotest.(check bool) "skips the language-client require"
+    false (contains cjs "vscode-languageclient/node");
+  Alcotest.(check bool) "passes null in its place"
+    true (contains cjs "    null,\n");
+  Alcotest.(check bool) "still requires vscode + adapter"
+    true (contains cjs {|require("vscode")|}
+          && contains cjs {|require("@hyperpolymath/affine-vscode")|})
+
+let test_vscode_extension_adapter_escaped () =
+  (* A specifier containing a double quote must not break out of the JS
+     string literal. *)
+  let cjs = cjs_of ~vscode_extension:true
+      ~vscode_extension_adapter:{|a"b\c|} activate_src in
+  Alcotest.(check bool) "double quote and backslash are escaped"
+    true (contains cjs {|require("a\"b\\c")|})
+
 let codegen_node_tests = [
   Alcotest.test_case "Node-CJS shim has all anchors (use strict, exports.activate, ...)" `Quick test_node_cjs_shim_shape;
   Alcotest.test_case "base64 encoder matches RFC 4648 vector"                              `Quick test_node_cjs_base64_roundtrip;
+  Alcotest.test_case "--vscode-extension off by default"                                   `Quick test_vscode_extension_off_by_default;
+  Alcotest.test_case "--vscode-extension inlines extraImports wiring"                      `Quick test_vscode_extension_inlines_wiring;
+  Alcotest.test_case "--vscode-extension-adapter overrides the require specifier"          `Quick test_vscode_extension_adapter_override;
+  Alcotest.test_case "--vscode-extension-no-lc skips the language client"                  `Quick test_vscode_extension_no_lc;
+  Alcotest.test_case "--vscode-extension-adapter specifier is JS-escaped"                  `Quick test_vscode_extension_adapter_escaped;
 ]
 
 (* ---- Stdlib parse + Core import regression ----