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

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.

Signed-off-by: Bailey Hayes <bailey@cosmonic.com>

Author: ricochet

crates/wit-component/src/printing.rs

@@ -452,14 +452,26 @@ impl<O: Output> WitPrinter<O> {
         cur_pkg: PackageId,
         import_or_export_keyword: &str,
     ) -> Result<()> {
-        // Print inline item docs
-        if matches!(name, WorldKey::Name(_)) {
-            self.print_docs(match item {
-                WorldItem::Interface { id, .. } => &resolve.interfaces[*id].docs,
-                WorldItem::Function(f) => &f.docs,
-                // Types are handled separately
-                WorldItem::Type { .. } => unreachable!(),
-            });
+        // Print docs for this import/export statement. For interfaces, prefer
+        // the docs attached to the statement itself (`WorldItem::Interface`'s
+        // `docs`); for an inline `import x: interface { .. }` with no statement
+        // docs fall back to the interface definition's docs.
+        let docs = match item {
+            WorldItem::Interface { id, docs, .. } => {
+                if docs.contents.is_some() {
+                    Some(docs)
+                } else if matches!(name, WorldKey::Name(_)) {
+                    Some(&resolve.interfaces[*id].docs)
+                } else {
+                    None
+                }
+            }
+            WorldItem::Function(f) => Some(&f.docs),
+            // Types are handled separately
+            WorldItem::Type { .. } => unreachable!(),
+        };
+        if let Some(docs) = docs {
+            self.print_docs(docs);
         }
 
         self.print_stability(item.stability(resolve));

crates/wit-component/tests/interfaces/wasi-http.wat

@@ -559,13 +559,25 @@ world proxy {
   import wasi:io/error@0.2.0-rc-2023-11-10;
   import wasi:io/poll@0.2.0-rc-2023-11-10;
   import wasi:io/streams@0.2.0-rc-2023-11-10;
+  /// Proxies have standard output and error streams which are expected to
+  /// terminate in a developer-facing console provided by the host.
   import wasi:cli/stdout@0.2.0-rc-2023-12-05;
   import wasi:cli/stderr@0.2.0-rc-2023-12-05;
+  /// TODO: this is a temporary workaround until component tooling is able to
+  /// gracefully handle the absence of stdin. Hosts must return an eof stream
+  /// for this import, which is what wasi-libc + tooling will do automatically
+  /// when this import is properly removed.
   import wasi:cli/stdin@0.2.0-rc-2023-12-05;
   import wasi:clocks/monotonic-clock@0.2.0-rc-2023-11-10;
   import types;
+  /// This is the default handler to use when user code simply wants to make an
+  /// HTTP request (e.g., via `fetch()`).
   import outgoing-handler;
   import wasi:clocks/wall-clock@0.2.0-rc-2023-11-10;
 
+  /// The host delivers incoming HTTP requests to a component by calling the
+  /// `handle` function of this exported interface. A host may arbitrarily reuse
+  /// or not reuse component instance when delivering incoming HTTP requests and
+  /// thus a component must be able to handle 0..N calls to `handle`.
   export incoming-handler;
 }

crates/wit-component/tests/interfaces/wasi-http/http.wit.print

@@ -0,0 +1,54 @@
+(component
+  (type (;0;)
+    (component
+      (type (;0;)
+        (instance
+          (type (;0;) (func))
+          (export (;0;) "f" (func (type 0)))
+        )
+      )
+      (export (;0;) "foo:foo/imported" (instance (type 0)))
+    )
+  )
+  (export (;1;) "imported" (type 0))
+  (type (;2;)
+    (component
+      (type (;0;)
+        (instance
+          (type (;0;) (func))
+          (export (;0;) "g" (func (type 0)))
+        )
+      )
+      (export (;0;) "foo:foo/exported" (instance (type 0)))
+    )
+  )
+  (export (;3;) "exported" (type 2))
+  (type (;4;)
+    (component
+      (type (;0;)
+        (component
+          (type (;0;)
+            (instance
+              (type (;0;) (func))
+              (export (;0;) "f" (func (type 0)))
+            )
+          )
+          (import "foo:foo/imported" (instance (;0;) (type 0)))
+          (type (;1;)
+            (instance
+              (type (;0;) (func))
+              (export (;0;) "g" (func (type 0)))
+            )
+          )
+          (export (;1;) "foo:foo/exported" (instance (type 1)))
+        )
+      )
+      (export (;0;) "foo:foo/the-world" (component (type 0)))
+    )
+  )
+  (export (;5;) "the-world" (type 4))
+  (@custom "package-docs" "\01{\22docs\22:\22doc comments on by-reference interface imports/exports\5cninside a world (attached to the `import`/`export` statement itself, as\5cnopposed to the interface's own definition) must survive the binary WIT\5cnpackage round-trip via the `package-docs` custom section.\22,\22worlds\22:{\22the-world\22:{\22interface_import_docs\22:{\22foo:foo/imported\22:\22docs on the by-reference interface import statement\22},\22interface_export_docs\22:{\22foo:foo/exported\22:\22docs on the by-reference interface export statement\22}}},\22interfaces\22:{\22imported\22:{\22docs\22:\22the imported interface's own definition docs\22},\22exported\22:{\22docs\22:\22the exported interface's own definition docs\22}}}")
+  (@producers
+    (processed-by "wit-component" "$CARGO_PKG_VERSION")
+  )
+)

crates/wit-component/tests/interfaces/world-interface-docs.wat

@@ -0,0 +1,23 @@
+/// doc comments on by-reference interface imports/exports
+/// inside a world (attached to the `import`/`export` statement itself, as
+/// opposed to the interface's own definition) must survive the binary WIT
+/// package round-trip via the `package-docs` custom section.
+package foo:foo;
+
+/// the imported interface's own definition docs
+interface imported {
+  f: func();
+}
+
+/// the exported interface's own definition docs
+interface exported {
+  g: func();
+}
+
+world the-world {
+  /// docs on the by-reference interface import statement
+  import imported;
+
+  /// docs on the by-reference interface export statement
+  export exported;
+}

crates/wit-component/tests/interfaces/world-interface-docs.wit

@@ -0,0 +1,23 @@
+/// doc comments on by-reference interface imports/exports
+/// inside a world (attached to the `import`/`export` statement itself, as
+/// opposed to the interface's own definition) must survive the binary WIT
+/// package round-trip via the `package-docs` custom section.
+package foo:foo;
+
+/// the imported interface's own definition docs
+interface imported {
+  f: func();
+}
+
+/// the exported interface's own definition docs
+interface exported {
+  g: func();
+}
+
+world the-world {
+  /// docs on the by-reference interface import statement
+  import imported;
+
+  /// docs on the by-reference interface export statement
+  export exported;
+}

crates/wit-component/tests/interfaces/world-interface-docs.wit.print

@@ -87,6 +87,7 @@ fn run_one(u: &mut Unstructured<'_>) -> Result<()> {
                 WorldItem::Interface {
                     id: *id,
                     stability: Default::default(),
+                    docs: Default::default(),
                     span: Default::default(),
                 },
             )
@@ -200,6 +201,7 @@ fn run_one(u: &mut Unstructured<'_>) -> Result<()> {
         WorldItem::Interface {
             id: alloc,
             stability: Default::default(),
+            docs: Default::default(),
             span: Default::default(),
         },
     );
@@ -208,6 +210,7 @@ fn run_one(u: &mut Unstructured<'_>) -> Result<()> {
         WorldItem::Interface {
             id: alloc,
             stability: Default::default(),
+            docs: Default::default(),
             span: Default::default(),
         },
     );

crates/wit-dylib/tests/roundtrip.rs

@@ -758,26 +758,31 @@ impl<'a> Resolver<'a> {
                 Ok(WorldItem::Interface {
                     id,
                     stability,
+                    docs: Default::default(),
                     span: name.span,
                 })
             }
             ast::ExternKind::Path(path) => {
                 let stability = self.stability(attrs)?;
+                let docs = self.docs(docs);
                 let (item, name, item_span) = self.resolve_ast_item_path(path)?;
                 let id = self.extract_iface_from_item(&item, &name, item_span)?;
                 Ok(WorldItem::Interface {
                     id,
                     stability,
+                    docs,
                     span: item_span,
                 })
             }
             ast::ExternKind::NamedPath(name, path) => {
                 let stability = self.stability(attrs)?;
+                let docs = self.docs(docs);
                 let (item, iface_name, item_span) = self.resolve_ast_item_path(path)?;
                 let id = self.extract_iface_from_item(&item, &iface_name, item_span)?;
                 Ok(WorldItem::Interface {
                     id,
                     stability,
+                    docs,
                     span: name.span,
                 })
             }

crates/wit-parser/src/ast/resolve.rs

@@ -748,6 +748,7 @@ impl WitPackageDecoder<'_> {
             WorldItem::Interface {
                 id,
                 stability: Default::default(),
+                docs: Default::default(),
                 span: Default::default(),
             },
         ))

crates/wit-parser/src/decoding.rs

@@ -523,6 +523,12 @@ pub enum WorldItem {
             serde(skip_serializing_if = "Stability::is_unknown")
         )]
         stability: Stability,
+        /// Documentation attached to the `import`/`export` statement.
+        #[cfg_attr(
+            feature = "serde",
+            serde(default, skip_serializing_if = "Docs::is_empty")
+        )]
+        docs: Docs,
         #[cfg_attr(feature = "serde", serde(skip))]
         span: Span,
     },