feat(jco): added warning when using fallback ComponentizeJS

Author: EngoDev

docs/src/troubleshooting/common-issues.md

@@ -1 +1,36 @@
 # Common issues
+
+## componentize-js 0.19.3 fallback
+
+### Symptom
+
+While running `jco componentize`, you may see a warning like this:
+
+```text
+warning Falling back to componentize-js 0.19.3 because this component requests Preview 2 WASI packages older than 0.2.10.
+```
+
+If that component is then run on newer Wasmtime releases, especially Wasmtime 42 or newer, you may hit the same isolate crash that was fixed upstream in `componentize-js` 0.20.0.
+
+### Root cause
+
+`jco` normally uses `componentize-js` 0.20.0 or newer, which includes the upstream fix for [ComponentizeJS issue #224](https://github.com/bytecodealliance/ComponentizeJS/issues/224).
+
+When the component's WIT still depends on Preview 2 WASI packages older than `0.2.10`, `jco` must fall back to `componentize-js` `0.19.3` for compatibility. In practice this usually shows up as `wasi:http` older than `0.2.10`, but related dependencies such as `wasi:clocks`, `wasi:random`, and `wasi:io` can force the same fallback. The older `componentize-js` version does not include the upstream fix, so the crash can reappear.
+
+For background, see [jco issue #1415](https://github.com/bytecodealliance/jco/issues/1415).
+
+### Solution
+
+Update `wasi:http` and any related Preview 2 WASI dependencies to `0.2.10` or newer, then re-run `jco componentize`.
+
+If you manage your WIT dependencies with [`wkg`](https://github.com/bytecodealliance/wasm-pkg-tools), fetching the updated packages can look like this:
+
+```bash
+wkg get --format wit wasi:http@0.2.10
+wkg get --format wit wasi:clocks@0.2.10
+wkg get --format wit wasi:random@0.2.10
+wkg get --format wit wasi:io@0.2.10
+```
+
+After updating the packages, make sure your entry WIT file and any vendored dependency files reference the newer versions before componentizing again.

package-lock.json

@@ -66,6 +66,9 @@ export async function componentize(jsSource, opts) {
         // NOTE: if we were to use a version of componentize-js 0.20.0 or newer here,
         // the build would fail, as newer versions do not support wasi:http < 0.2.10
         // for fetch.
+        console.error(
+            `${styleText(["yellow", "bold"], "warning")} Falling back to componentize-js 0.19.3 because this component requests Preview 2 WASI packages older than 0.2.10. See https://bytecodealliance.github.io/jco/troubleshooting/common-issues.html#componentize-js-0193-fallback for details and upgrade steps.`,
+        );
         componentizeJSModule = await eval('import("@bytecodealliance/componentize-js-0-19-3")');
     } else {
         componentizeJSModule = await eval('import("@bytecodealliance/componentize-js")');

packages/jco/src/cmd/componentize.js

@@ -117,7 +117,14 @@ suite(`Transpiler codegen`, async () => {
                     "-o",
                     outFile,
                 );
-                assert.strictEqual(stderr, "");
+                assert.match(
+                    stderr,
+                    /Falling back to componentize-js 0\.19\.3 because this component requests Preview 2 WASI packages older than 0\.2\.10\./,
+                );
+                assert.match(
+                    stderr,
+                    /https:\/\/bytecodealliance\.github\.io\/jco\/troubleshooting\/common-issues\.html#componentize-js-0193-fallback/,
+                );
                 const outDir = fileURLToPath(new URL(`./output/${runtimeName}`, import.meta.url));
                 {
                     const { stderr } = await exec(jcoPath, "transpile", outFile, "--name", runtimeName, "-o", outDir);

packages/jco/test/codegen.js

@@ -18,7 +18,14 @@ suite("componentize", () => {
         const outputDir = await getTmpDir();
         const outputPath = join(outputDir, "component.wasm");
         const { stderr } = await exec(jcoPath, "componentize", jsPath, "-w", witPath, "-o", outputPath);
-        assert.strictEqual(stderr, "");
+        assert.match(
+            stderr,
+            /Falling back to componentize-js 0\.19\.3 because this component requests Preview 2 WASI packages older than 0\.2\.10\./,
+        );
+        assert.match(
+            stderr,
+            /https:\/\/bytecodealliance\.github\.io\/jco\/troubleshooting\/common-issues\.html#componentize-js-0193-fallback/,
+        );
     });
 
     test.concurrent("detect newer wasi:http", async () => {