Document how imports work & avoid printing invalid JS in the error message

[bakkot]

Suppose you have the following WIT:

package local:hello;
world hello {
  import foo: func() -> string;
  export hello: func(name: string) -> string;
}

and you want to create and componentize a JS module which provides that interface.

The first thing that trips you up is that nothing tells you want module specifier to use for the import. If you pick one at random:

import { foo } from '??';
export function hello(name) {
  return `hello ${name} here is your value: ${foo()}`;
}

That produces

Import '??' in source.js is not defined as a world import. Only component-defined imports can be used.
Unable to link the source code. Imports should be:

  import { default } from "foo";

which at least suggests that the module specifier should match the import name. (Though it's confusing that it says the error is in source.js given that my file is in fact named hello.js.) Great! Ideally that would be documented outside of the error message.

Unfortunately, the code it suggests is a syntax error (since default is not a valid identifier name in JS). You actually want a default import, as in:

import nameOfYourChoice from "foo";
export function hello(name) {
  return `hello ${name} here is your value: ${nameOfYourChoice()}`;
}

which does in fact work once you provide the right bindings, for example with JCO:

jco componentize hello.js --wit hello.wit -n hello -o hello.wasm
jco transpile hello.wasm --instantiation sync --out-dir out

can be run with

import fs from 'node:fs';
import { instantiate } from './out/hello.js';
let x = instantiate(
  n => new WebAssembly.Module(fs.readFileSync('out/' + n)),
  { foo: { default: () => 'xyz' } },
);
console.log(x.hello('alice'));

[12101111]

When handling resources, it also suggest invalid js code:

 . import { filesystemErrorCode, [method]descriptor.readViaStream, [method]descriptor.writeViaStream, [method]descriptor.appendViaStream, [method]descriptor.advise, [method]descriptor.syncData, [method]descriptor.getFlags, [method]descriptor.getType, [method]descriptor.setSize, [method]descriptor.setTimes, [method]descriptor.read, [method]descriptor.write, [method]descriptor.readDirectory, [method]descriptor.sync, [method]descriptor.createDirectoryAt, [method]descriptor.stat, [method]descriptor.statAt, [method]descriptor.setTimesAt, [method]descriptor.linkAt, [method]descriptor.openAt, [method]descriptor.readlinkAt, [method]descriptor.removeDirectoryAt, [method]descriptor.renameAt, [method]descriptor.symlinkAt, [method]descriptor.unlinkFileAt, [method]descriptor.isSameObject, [method]descriptor.metadataHash, [method]descriptor.metadataHashAt, [method]directoryEntryStream.readDirectoryEntry, [resourceDrop]descriptor, [resourceDrop]directoryEntryStream } from "wasi:filesystem/types@0.2.0";