WIT: Implement @since and @unstable annotations

[alexcrichton]

This PR is an implementation of WebAssembly/component-model#332 for wasm-tools. This is a pretty big feature for WIT so it's a pretty large PR as well. I've tried to split out separate commits where each commit passes test to more easily digest the changes that are happening here.

At a high level:

• Most items in WIT can now be tagged with @since and @unstable.
• When tagged with @unstable items do not appear in Resolve by default
• Features are enabled through the set at Resolve::features to control whether unstable items appear
• WIT items always retain their stability annotations throught processing, e.g. in Resolve
• Round-tripping a WIT document through the WebAssembly component encoding preserves stability annotations

The intention is that this will be a building block for WASI's release processes. Namely all APIs will start as @unstable and only become ungated with @since once they're voted to be at such a phase. @unstable APIs will be available to all consumers but only on an opt-in basis which will enable everyone to have proper gates and processes around ensuring that unstable APIs aren't relied on without knowing that things may change.

[ydnar]

Would this PR update the JSON fixtures in the wit-parser crate?

[alexcrichton]

It does, yes. You can see examples in the *.json files in this PR diff.

[yoshuawuyts]

I spoke with Alex last week - in order to move this forward we want to at a minimum have a reference of what this would look like when applied to the existing WASI WIT definitions. So I'll be doing that next, and share a link to that back here.

[yoshuawuyts]

Okay, I ported all of WASI to use @since, and added the timezones API using @unstable in a PR here: WebAssembly/WASI#604. This all seems to work as expected with wasm-tools. I think with that we can consider this implementation to be working as intended, and ready to merge?

edit (2024-05-28): I also went ahead and filed PRs against the individual specifiations:

• wasi:cli - Document per-item versions using @since gates WebAssembly/wasi-cli#43
• wasi:clocks - Document per-item versions using @since gates WebAssembly/wasi-clocks#66
• wasi:filesystem - Document per-item versions using @since gates WebAssembly/wasi-filesystem#148
• wasi:http - Document per-item versions using @since gates WebAssembly/wasi-http#114
• wasi:io - Document per-item versions using @since gates WebAssembly/wasi-io#78
• wasi:random - Document per-item versions using @since gates WebAssembly/wasi-random#43
• wasi:sockets - Document per-item versions using @since gates WebAssembly/wasi-sockets#102

[ydnar]

I finally got to updating wasm-tools-go to support the new JSON schema.

Q: why was the schema for the WorldItem Interface case changed? But not the others?

Should the gating attributes be present on the Interface?

[alexcrichton]

For types/functions the attributes were already present on the type/function itself, but for interfaces it was intended to help disambiguate:

@unstable(feature = "a")
interface foo {}

world bar {
    @unstable(feature = "b")
    import foo;
}

Here there's two different features that need to be modeled, but in the case of functions/types there's never two features to model.