fix(wit-parser)!: preserve docs on world interface imports/exports

[ricochet]

Doc comments attached to a world's by-reference interface import/export statements (e.g. the comments above import wasi:cli/stdout; and export handler; in wasi:http's world service) were silently dropped when a WIT package was encoded to its binary component form.

Fix this by:

• adding a docs field to WorldItem::Interface and threading the statement docs through the resolver and world elaboration,
• extracting/injecting those docs via the package-docs section, mirroring the existing per-interface stability mechanism,
• printing them for WorldKey::Interface items, preferring the statement docs and only falling back to the interface definition's docs for inline interfaces.

Docs on include statements remain unsupported. Includes are flattened into imports/exports on encode, so they cannot survive the binary round-trip.

Adds a world-interface-docs round-trip test and updates the wasi-http snapshots to include the previously-dropped docs.

Important

This is a breaking change. Backward compatibility with newer wasm-tools decoding old WIT-only components works, but forward compatibility will hard error (old wasm-tools reading new WIT-only component).

[alexcrichton]

Looks like a re-bless may be needed, but otherwise looks good to me, thanks!

[alexcrichton]

A possible wrinkle that I just remembered this morning as well -- deserialization here uses deny_unknown_fields which means that serializing existing worlds today will not be deserializable by older versions of wasm-tools. I originally thought that might make this change too risky to land, but in retrospect I think that's probably ok because this only affects wit-encoded-as-wasm. That means that a brand-new WASI snapshot would require a newer wasm-tools to decode but it's also not the most common right now to sling wits-as-wasms around into bindgen/linkers/etc. So while this will be a risk for older wasm-tools versions, I think it shouldn't cause widespread issues (e.g. rust stable not being able to compile the latest wit-bindgen-generated-things or something like that)

[ricochet]

I ran through a couple manual sanity checks.

Verified that we don't impact guest components (non-WIT-only) by embedding a world (with import/export statement docs) into a core module the way wit-bindgen does then decoded. That worked since guest components never carry package-docs, and they're decoded via encode_world/decode_world.

I installed wasm-tools 1.251.0 and pointed it at a new-encoded wasi-http. This is the failure folks will see:

error: unknown field `interface_import_docs`, expected one of `docs`, `stability`, `interfaces`, `types`, `funcs`, `interface_exports`, `func_exports`, `interface_import_stability`, `interface_export_stability`   (exit 1)

[alexcrichton]

Thanks for double-checking! I don't think that's necessarily a discoverable/debuggable error, but I suspect that it'll be rare enough that it'll be fine 👍