wit_parser/

decoding.rs

use crate::*;
use alloc::string::{String, ToString};
use alloc::vec;
use alloc::vec::Vec;
use anyhow::Result;
use anyhow::{Context, anyhow, bail};
use core::mem;
use std::io::Read;
use wasmparser::Chunk;
use wasmparser::{
    ComponentExternalKind, Parser, Payload, PrimitiveValType, ValidPayload, Validator,
    WasmFeatures,
    component_types::{
        ComponentAnyTypeId, ComponentDefinedType, ComponentEntityType, ComponentItem,
        ComponentType, ComponentValType,
    },
    names::{ComponentName, ComponentNameKind},
    types,
    types::Types,
};

/// Represents information about a decoded WebAssembly component.
struct ComponentInfo {
    /// Wasmparser-defined type information learned after a component is fully
    /// validated.
    types: types::Types,
    /// List of all imports and exports from this component.
    externs: Vec<(String, Extern)>,
    /// Decoded package metadata
    package_metadata: Option<PackageMetadata>,
}

enum Extern {
    Import(ComponentItem),
    Export(ComponentItem),
}

#[derive(Debug, Clone, Copy, PartialEq, Eq)]
enum WitEncodingVersion {
    V1,
    V2,
}

impl ComponentInfo {
    /// Creates a new component info by parsing the given WebAssembly component bytes.
    fn from_reader(mut reader: impl Read) -> Result<Self> {
        let mut validator = Validator::new_with_features(WasmFeatures::all());
        let mut externs = Vec::new();
        let mut depth = 1;
        let mut types = None;
        let mut _package_metadata = None;
        let mut cur = Parser::new(0);
        let mut eof = false;
        let mut stack = Vec::new();
        let mut buffer = Vec::new();

        loop {
            let chunk = cur.parse(&buffer, eof)?;
            let (payload, consumed) = match chunk {
                Chunk::NeedMoreData(hint) => {
                    assert!(!eof); // otherwise an error would be returned

                    // Use the hint to preallocate more space, then read
                    // some more data into our buffer.
                    //
                    // Note that the buffer management here is not ideal,
                    // but it's compact enough to fit in an example!
                    let len = buffer.len();
                    buffer.extend((0..hint).map(|_| 0u8));
                    let n = reader.read(&mut buffer[len..])?;
                    buffer.truncate(len + n);
                    eof = n == 0;
                    continue;
                }

                Chunk::Parsed { consumed, payload } => (payload, consumed),
            };
            match validator.payload(&payload)? {
                ValidPayload::Ok => {}
                ValidPayload::Parser(_) => depth += 1,
                ValidPayload::End(t) => {
                    depth -= 1;
                    if depth == 0 {
                        types = Some(t);
                    }
                }
                ValidPayload::Func(..) => {}
            }

            match payload {
                Payload::ComponentImportSection(s) if depth == 1 => {
                    for import in s {
                        let import = import?;
                        let ty = validator
                            .types(0)
                            .unwrap()
                            .component_item_for_import(import.name.name)
                            .unwrap();
                        externs.push((import.name.name.to_string(), Extern::Import(ty.clone())));
                    }
                }
                Payload::ComponentExportSection(s) if depth == 1 => {
                    for export in s {
                        let export = export?;
                        let ty = validator
                            .types(0)
                            .unwrap()
                            .component_item_for_export(export.name.name)
                            .unwrap();
                        externs.push((export.name.name.to_string(), Extern::Export(ty.clone())));
                    }
                }
                #[cfg(feature = "serde")]
                Payload::CustomSection(s) if s.name() == PackageMetadata::SECTION_NAME => {
                    if _package_metadata.is_some() {
                        bail!("multiple {:?} sections", PackageMetadata::SECTION_NAME);
                    }
                    _package_metadata = Some(PackageMetadata::decode(s.data())?);
                }
                Payload::ModuleSection { parser, .. }
                | Payload::ComponentSection { parser, .. } => {
                    stack.push(cur.clone());
                    cur = parser.clone();
                }
                Payload::End(_) => {
                    if let Some(parent_parser) = stack.pop() {
                        cur = parent_parser.clone();
                    } else {
                        break;
                    }
                }
                _ => {}
            }

            // once we're done processing the payload we can forget the
            // original.
            buffer.drain(..consumed);
        }

        Ok(Self {
            types: types.unwrap(),
            externs,
            package_metadata: _package_metadata,
        })
    }

    fn is_wit_package(&self) -> Option<WitEncodingVersion> {
        // all wit package exports must be component types, and there must be at
        // least one
        if self.externs.is_empty() {
            return None;
        }

        if !self.externs.iter().all(|(_, item)| {
            let export = match item {
                Extern::Export(e) => e,
                _ => return false,
            };
            match export.ty {
                ComponentEntityType::Type { created, .. } => {
                    matches!(created, ComponentAnyTypeId::Component(_))
                }
                _ => false,
            }
        }) {
            return None;
        }

        // The distinction between v1 and v2 encoding formats is the structure of the export
        // strings for each component. The v1 format uses "<namespace>:<package>/wit" as the name
        // for the top-level exports, while the v2 format uses the unqualified name of the encoded
        // entity.
        match ComponentName::new(&self.externs[0].0, 0).ok()?.kind() {
            ComponentNameKind::Interface(name) if name.interface().as_str() == "wit" => {
                Some(WitEncodingVersion::V1)
            }
            ComponentNameKind::Label(_) => Some(WitEncodingVersion::V2),
            _ => None,
        }
    }

    fn decode_wit_v1_package(&self) -> Result<(Resolve, PackageId)> {
        let mut decoder = WitPackageDecoder::new(&self.types);

        let mut pkg = None;
        for (name, item) in self.externs.iter() {
            let export = match item {
                Extern::Export(e) => e,
                _ => unreachable!(),
            };
            if pkg.is_some() {
                bail!("more than one top-level exported component type found");
            }
            let name = ComponentName::new(name, 0).unwrap();
            pkg = Some(
                decoder
                    .decode_v1_package(&name, export)
                    .with_context(|| format!("failed to decode document `{name}`"))?,
            );
        }

        let pkg = pkg.ok_or_else(|| anyhow!("no exported component type found"))?;
        let (mut resolve, package) = decoder.finish(pkg);
        if let Some(package_metadata) = &self.package_metadata {
            package_metadata.inject(&mut resolve, package)?;
        }
        Ok((resolve, package))
    }

    fn decode_wit_v2_package(&self) -> Result<(Resolve, PackageId)> {
        let mut decoder = WitPackageDecoder::new(&self.types);

        let mut pkg_name = None;

        let mut interfaces = IndexMap::default();
        let mut worlds = IndexMap::default();
        let mut fields = PackageFields {
            interfaces: &mut interfaces,
            worlds: &mut worlds,
        };

        for (_, item) in self.externs.iter() {
            let export = match item {
                Extern::Export(e) => e,
                _ => unreachable!(),
            };
            let component = match export.ty {
                ComponentEntityType::Type {
                    created: ComponentAnyTypeId::Component(id),
                    ..
                } => &self.types[id],
                _ => unreachable!(),
            };

            // The single export of this component will determine if it's a world or an interface:
            // worlds export a component, while interfaces export an instance.
            if component.exports.len() != 1 {
                bail!(
                    "Expected a single export, but found {} instead",
                    component.exports.len()
                );
            }

            let name = component.exports.keys().nth(0).unwrap();

            let item = &component.exports[name];
            let name = match item.ty {
                ComponentEntityType::Component(_) => {
                    let package_name = decoder.decode_world(name.as_str(), item, &mut fields)?;
                    package_name
                }
                ComponentEntityType::Instance(_) => {
                    let package_name = decoder.decode_interface(
                        name.as_str(),
                        &component.imports,
                        item,
                        &mut fields,
                    )?;
                    package_name
                }
                _ => unreachable!(),
            };

            if let Some(pkg_name) = pkg_name.as_ref() {
                // TODO: when we have fully switched to the v2 format, we should switch to parsing
                // multiple wit documents instead of bailing.
                if pkg_name != &name {
                    bail!("item defined with mismatched package name")
                }
            } else {
                pkg_name.replace(name);
            }
        }

        let pkg = if let Some(name) = pkg_name {
            Package {
                name,
                docs: Docs::default(),
                interfaces,
                worlds,
            }
        } else {
            bail!("no exported component type found");
        };

        let (mut resolve, package) = decoder.finish(pkg);
        if let Some(package_metadata) = &self.package_metadata {
            package_metadata.inject(&mut resolve, package)?;
        }
        Ok((resolve, package))
    }

    fn decode_component(&self) -> Result<(Resolve, WorldId)> {
        assert!(self.is_wit_package().is_none());
        let mut decoder = WitPackageDecoder::new(&self.types);
        // Note that this name is arbitrarily chosen. We may one day perhaps
        // want to encode this in the component binary format itself, but for
        // now it shouldn't be an issue to have a defaulted name here.
        let world_name = "root";
        let world = decoder.resolve.worlds.alloc(World {
            name: world_name.to_string(),
            docs: Default::default(),
            imports: Default::default(),
            exports: Default::default(),
            package: None,
            includes: Default::default(),
            stability: Default::default(),
            span: Default::default(),
        });
        let mut package = Package {
            // Similar to `world_name` above this is arbitrarily chosen as it's
            // not otherwise encoded in a binary component. This theoretically
            // shouldn't cause issues, however.
            name: PackageName {
                namespace: "root".to_string(),
                version: None,
                name: "component".to_string(),
            },
            docs: Default::default(),
            worlds: [(world_name.to_string(), world)].into_iter().collect(),
            interfaces: Default::default(),
        };

        let mut fields = PackageFields {
            worlds: &mut package.worlds,
            interfaces: &mut package.interfaces,
        };

        for (name, item) in self.externs.iter() {
            match item {
                Extern::Import(i) => {
                    decoder.decode_component_import(name, i, world, &mut fields)?
                }
                Extern::Export(e) => {
                    decoder.decode_component_export(name, e, world, &mut fields)?
                }
            }
        }

        let (mut resolve, pkg) = decoder.finish(package);
        if let Some(package_metadata) = &self.package_metadata {
            package_metadata.inject(&mut resolve, pkg)?;
        }
        Ok((resolve, world))
    }
}

/// Result of the [`decode`] function.
pub enum DecodedWasm {
    /// The input to [`decode`] was one or more binary-encoded WIT package(s).
    ///
    /// The full resolve graph is here plus the identifier of the packages that
    /// were encoded. Note that other packages may be within the resolve if any
    /// of the main packages refer to other, foreign packages.
    WitPackage(Resolve, PackageId),

    /// The input to [`decode`] was a component and its interface is specified
    /// by the world here.
    Component(Resolve, WorldId),
}

impl DecodedWasm {
    /// Returns the [`Resolve`] for WIT types contained.
    pub fn resolve(&self) -> &Resolve {
        match self {
            DecodedWasm::WitPackage(resolve, _) => resolve,
            DecodedWasm::Component(resolve, _) => resolve,
        }
    }

    /// Returns the main packages of what was decoded.
    pub fn package(&self) -> PackageId {
        match self {
            DecodedWasm::WitPackage(_, id) => *id,
            DecodedWasm::Component(resolve, world) => resolve.worlds[*world].package.unwrap(),
        }
    }
}

/// Decode for incremental reading
pub fn decode_reader(reader: impl Read) -> Result<DecodedWasm> {
    let info = ComponentInfo::from_reader(reader)?;

    if let Some(version) = info.is_wit_package() {
        match version {
            WitEncodingVersion::V1 => {
                log::debug!("decoding a v1 WIT package encoded as wasm");
                let (resolve, pkg) = info.decode_wit_v1_package()?;
                Ok(DecodedWasm::WitPackage(resolve, pkg))
            }
            WitEncodingVersion::V2 => {
                log::debug!("decoding a v2 WIT package encoded as wasm");
                let (resolve, pkg) = info.decode_wit_v2_package()?;
                Ok(DecodedWasm::WitPackage(resolve, pkg))
            }
        }
    } else {
        log::debug!("inferring the WIT of a concrete component");
        let (resolve, world) = info.decode_component()?;
        Ok(DecodedWasm::Component(resolve, world))
    }
}

/// Decodes an in-memory WebAssembly binary into a WIT [`Resolve`] and
/// associated metadata.
///
/// The WebAssembly binary provided here can either be a
/// WIT-package-encoded-as-binary or an actual component itself. A [`Resolve`]
/// is always created and the return value indicates which was detected.
pub fn decode(bytes: &[u8]) -> Result<DecodedWasm> {
    decode_reader(bytes)
}

/// Decodes the single component type `world` specified as a WIT world.
///
/// The `world` should be an exported component type. The `world` must have been
/// previously created via `encode_world` meaning that it is a component that
/// itself imports nothing and exports a single component, and the single
/// component export represents the world. The name of the export is also the
/// name of the package/world/etc.
pub fn decode_world(wasm: &[u8]) -> Result<(Resolve, WorldId)> {
    let mut validator = Validator::new_with_features(WasmFeatures::all());
    let mut exports = Vec::new();
    let mut depth = 1;
    let mut types = None;

    for payload in Parser::new(0).parse_all(wasm) {
        let payload = payload?;

        match validator.payload(&payload)? {
            ValidPayload::Ok => {}
            ValidPayload::Parser(_) => depth += 1,
            ValidPayload::End(t) => {
                depth -= 1;
                if depth == 0 {
                    types = Some(t);
                }
            }
            ValidPayload::Func(..) => {}
        }

        match payload {
            Payload::ComponentExportSection(s) if depth == 1 => {
                for export in s {
                    exports.push(export?);
                }
            }
            _ => {}
        }
    }

    if exports.len() != 1 {
        bail!("expected one export in component");
    }
    if exports[0].kind != ComponentExternalKind::Type {
        bail!("expected an export of a type");
    }
    if exports[0].ty.is_some() {
        bail!("expected an un-ascribed exported type");
    }
    let types = types.as_ref().unwrap();
    let world = match types.as_ref().component_any_type_at(exports[0].index) {
        ComponentAnyTypeId::Component(c) => c,
        _ => bail!("expected an exported component type"),
    };

    let mut decoder = WitPackageDecoder::new(types);
    let mut interfaces = IndexMap::default();
    let mut worlds = IndexMap::default();
    let ty = &types[world];
    assert_eq!(ty.imports.len(), 0);
    assert_eq!(ty.exports.len(), 1);
    let name = ty.exports.keys().nth(0).unwrap();
    let name = decoder.decode_world(
        name,
        &ty.exports[0],
        &mut PackageFields {
            interfaces: &mut interfaces,
            worlds: &mut worlds,
        },
    )?;
    let (resolve, pkg) = decoder.finish(Package {
        name,
        interfaces,
        worlds,
        docs: Default::default(),
    });
    // The package decoded here should only have a single world so extract that
    // here to return.
    let world = *resolve.packages[pkg].worlds.iter().next().unwrap().1;
    Ok((resolve, world))
}

struct PackageFields<'a> {
    interfaces: &'a mut IndexMap<String, InterfaceId>,
    worlds: &'a mut IndexMap<String, WorldId>,
}

struct WitPackageDecoder<'a> {
    resolve: Resolve,
    types: &'a Types,
    foreign_packages: IndexMap<String, Package>,
    iface_to_package_index: HashMap<InterfaceId, usize>,
    named_interfaces: HashMap<String, InterfaceId>,

    /// A map which tracks named resources to what their corresponding `TypeId`
    /// is. This first layer of key in this map is the owner scope of a
    /// resource, more-or-less the `world` or `interface` that it's defined
    /// within. The second layer of this map is keyed by name of the resource
    /// and points to the actual ID of the resource.
    ///
    /// This map is populated in `register_type_export`.
    resources: HashMap<TypeOwner, HashMap<String, TypeId>>,

    /// A map from a type id to what it's been translated to.
    type_map: HashMap<ComponentAnyTypeId, TypeId>,
}

impl WitPackageDecoder<'_> {
    fn new<'a>(types: &'a Types) -> WitPackageDecoder<'a> {
        WitPackageDecoder {
            resolve: Resolve::default(),
            types,
            type_map: HashMap::new(),
            foreign_packages: Default::default(),
            iface_to_package_index: Default::default(),
            named_interfaces: Default::default(),
            resources: Default::default(),
        }
    }

    fn decode_v1_package(&mut self, name: &ComponentName, item: &ComponentItem) -> Result<Package> {
        let ty = match item.ty {
            ComponentEntityType::Type {
                created: ComponentAnyTypeId::Component(id),
                ..
            } => &self.types[id],
            _ => unreachable!(),
        };

        // Process all imports for this package first, where imports are
        // importing from remote packages.
        for (name, item) in ty.imports.iter() {
            self.register_import(name, item)
                .with_context(|| format!("failed to process import `{name}`"))?;
        }

        let mut package = Package {
            // The name encoded for packages must be of the form `foo:bar/wit`
            // where "wit" is just a placeholder for now. The package name in
            // this case would be `foo:bar`.
            name: match name.kind() {
                ComponentNameKind::Interface(name) if name.interface().as_str() == "wit" => {
                    name.to_package_name(item)?
                }
                _ => bail!("package name is not a valid id: {name}"),
            },
            docs: Default::default(),
            interfaces: Default::default(),
            worlds: Default::default(),
        };

        let mut fields = PackageFields {
            interfaces: &mut package.interfaces,
            worlds: &mut package.worlds,
        };

        for (name, ty) in ty.exports.iter() {
            match ty.ty {
                ComponentEntityType::Instance(_) => {
                    self.register_interface(name.as_str(), ty, &mut fields)
                        .with_context(|| format!("failed to process export `{name}`"))?;
                }
                ComponentEntityType::Component(idx) => {
                    let ty = &self.types[idx];
                    self.register_world(name.as_str(), ty, &mut fields)
                        .with_context(|| format!("failed to process export `{name}`"))?;
                }
                _ => bail!("component export `{name}` is not an instance or component"),
            }
        }
        Ok(package)
    }

    fn decode_interface<'a>(
        &mut self,
        name: &str,
        imports: &wasmparser::collections::IndexMap<String, ComponentItem>,
        item: &ComponentItem,
        fields: &mut PackageFields<'a>,
    ) -> Result<PackageName> {
        let component_name = self
            .parse_component_name(name)
            .context("expected world name to have an ID form")?;

        let package = match component_name.kind() {
            ComponentNameKind::Interface(name) => name.to_package_name(item)?,
            _ => bail!("expected world name to be fully qualified"),
        };

        for (name, ty) in imports.iter() {
            self.register_import(name, ty)
                .with_context(|| format!("failed to process import `{name}`"))?;
        }

        let _ = self.register_interface(name, item, fields)?;

        Ok(package)
    }

    fn decode_world<'a>(
        &mut self,
        name: &str,
        item: &ComponentItem,
        fields: &mut PackageFields<'a>,
    ) -> Result<PackageName> {
        let ty = match item.ty {
            ComponentEntityType::Component(ty) => &self.types[ty],
            _ => unreachable!(),
        };
        let kebab_name = self
            .parse_component_name(name)
            .context("expected world name to have an ID form")?;

        let package = match kebab_name.kind() {
            ComponentNameKind::Interface(name) => name.to_package_name(item)?,
            _ => bail!("expected world name to be fully qualified"),
        };

        let _ = self.register_world(name, ty, fields)?;

        Ok(package)
    }

    fn decode_component_import<'a>(
        &mut self,
        name: &str,
        item: &ComponentItem,
        world: WorldId,
        package: &mut PackageFields<'a>,
    ) -> Result<()> {
        log::debug!("decoding component import `{name}`");
        let owner = TypeOwner::World(world);
        let (name, item) = match item.ty {
            ComponentEntityType::Instance(_) => self
                .decode_world_instance(name, item, package)
                .with_context(|| format!("failed to decode WIT from import `{name}`"))?,
            ComponentEntityType::Func(_) => {
                let func = self
                    .convert_function(name, item, owner)
                    .with_context(|| format!("failed to decode function from import `{name}`"))?;
                (WorldKey::Name(name.to_string()), WorldItem::Function(func))
            }
            ComponentEntityType::Type { .. } => {
                let id = self
                    .register_type_export(name, item, owner)
                    .with_context(|| format!("failed to decode type from export `{name}`"))?;
                (
                    WorldKey::Name(name.to_string()),
                    WorldItem::Type {
                        id,
                        span: Default::default(),
                    },
                )
            }
            // All other imports do not form part of the component's world
            _ => return Ok(()),
        };
        self.resolve.worlds[world].imports.insert(name, item);
        Ok(())
    }

    fn decode_component_export<'a>(
        &mut self,
        name: &str,
        item: &ComponentItem,
        world: WorldId,
        package: &mut PackageFields<'a>,
    ) -> Result<()> {
        log::debug!("decoding component export `{name}`");
        let (name, item) = match item.ty {
            ComponentEntityType::Func(_) => {
                let func = self
                    .convert_function(name, item, TypeOwner::World(world))
                    .with_context(|| format!("failed to decode function from export `{name}`"))?;

                (WorldKey::Name(name.to_string()), WorldItem::Function(func))
            }
            ComponentEntityType::Instance(_) => self
                .decode_world_instance(name, item, package)
                .with_context(|| format!("failed to decode WIT from export `{name}`"))?,
            _ => {
                bail!("component export `{name}` was not a function or instance")
            }
        };
        self.resolve.worlds[world].exports.insert(name, item);
        Ok(())
    }

    /// Decodes a component instance import/export name into a
    /// `(WorldKey, WorldItem)` pair.
    ///
    /// Handles three name forms:
    /// - `ns:pkg/iface` — qualified interface name, keyed by `InterfaceId`
    /// - `plain-name` — unqualified name for an inline or local interface
    /// - `plain-name (implements "...")` - reference to a preexisting interface
    ///   elsewhere
    fn decode_world_instance<'a>(
        &mut self,
        name: &str,
        item: &ComponentItem,
        package: &mut PackageFields<'a>,
    ) -> Result<(WorldKey, WorldItem)> {
        let (key, id) = match &item.implements {
            Some(i) => {
                let id = self.register_import(i, item)?;
                (WorldKey::Name(name.to_string()), id)
            }
            None => match self.parse_component_name(name)?.kind() {
                ComponentNameKind::Interface(i) => {
                    let id = self.register_import(i.as_str(), item)?;
                    (WorldKey::Interface(id), id)
                }
                _ => self.register_interface(name, item, package)?,
            },
        };
        Ok((
            key,
            WorldItem::Interface {
                id,
                stability: Default::default(),
                docs: Default::default(),
                span: Default::default(),
                external_id: item.external_id.clone(),
            },
        ))
    }

    /// Registers that the `name` provided is either imported interface from a
    /// foreign package or  referencing a previously defined interface in this
    /// package.
    ///
    /// This function will internally ensure that `name` is well-structured and
    /// will fill in any information as necessary. For example with a foreign
    /// dependency the foreign package structure, types, etc, all need to be
    /// created. For a local dependency it's instead ensured that all the types
    /// line up with the previous definitions.
    fn register_import(&mut self, name: &str, item: &ComponentItem) -> Result<InterfaceId> {
        let ty = match item.ty {
            ComponentEntityType::Instance(idx) => &self.types[idx],
            _ => bail!("import `{name}` is not an instance"),
        };
        let (is_local, interface) = match self.named_interfaces.get(name) {
            Some(id) => (true, *id),
            None => (false, self.extract_dep_interface(name, item)?),
        };
        let owner = TypeOwner::Interface(interface);
        for (name, item) in ty.exports.iter() {
            log::debug!("decoding import instance export `{name}`");
            match item.ty {
                ComponentEntityType::Type {
                    referenced,
                    created,
                } => {
                    match self.resolve.interfaces[interface]
                        .types
                        .get(name.as_str())
                        .copied()
                    {
                        // If this name is already defined as a type in the
                        // specified interface then that's ok. For package-local
                        // interfaces that's expected since the interface was
                        // fully defined. For remote interfaces it means we're
                        // using something that was already used elsewhere. In
                        // both cases continue along.
                        //
                        // Notably for the remotely defined case this will also
                        // walk over the structure of the type and register
                        // internal wasmparser ids with wit-parser ids. This is
                        // necessary to ensure that anonymous types like
                        // `list<u8>` defined in original definitions are
                        // unified with anonymous types when duplicated inside
                        // of worlds. Overall this prevents, for example, extra
                        // `list<u8>` types from popping up when decoding. This
                        // is not strictly necessary but assists with
                        // roundtripping assertions during fuzzing.
                        Some(id) => {
                            log::debug!("type already exist");
                            match referenced {
                                ComponentAnyTypeId::Defined(ty) => {
                                    self.register_defined(id, &self.types[ty])?;
                                }
                                ComponentAnyTypeId::Resource(_) => {}
                                _ => unreachable!(),
                            }
                            let prev = self.type_map.insert(created, id);
                            assert!(prev.is_none());
                        }

                        // If the name is not defined, however, then there's two
                        // possibilities:
                        //
                        // * For package-local interfaces this is an error
                        //   because the package-local interface defined
                        //   everything already and this is referencing
                        //   something that isn't defined.
                        //
                        // * For remote interfaces they're never fully declared
                        //   so it's lazily filled in here. This means that the
                        //   view of remote interfaces ends up being the minimal
                        //   slice needed for this resolve, which is what's
                        //   intended.
                        None => {
                            if is_local {
                                bail!("instance type export `{name}` not defined in interface");
                            }
                            let id = self.register_type_export(name.as_str(), item, owner)?;
                            let prev = self.resolve.interfaces[interface]
                                .types
                                .insert(name.to_string(), id);
                            assert!(prev.is_none());
                        }
                    }
                }

                // This has similar logic to types above where we lazily fill in
                // functions for remote dependencies and otherwise assert
                // they're already defined for local dependencies.
                ComponentEntityType::Func(_) => {
                    if self.resolve.interfaces[interface]
                        .functions
                        .contains_key(name.as_str())
                    {
                        // TODO: should ideally verify that function signatures
                        // match.
                        continue;
                    }
                    if is_local {
                        bail!("instance function export `{name}` not defined in interface");
                    }
                    let func = self.convert_function(name.as_str(), item, owner)?;
                    let prev = self.resolve.interfaces[interface]
                        .functions
                        .insert(name.to_string(), func);
                    assert!(prev.is_none());
                }

                _ => bail!("instance type export `{name}` is not a type"),
            }
        }

        Ok(interface)
    }

    fn find_alias(&self, id: ComponentAnyTypeId) -> Option<TypeId> {
        // Consult `type_map` for `referenced` or anything in its
        // chain of aliases to determine what it maps to. This may
        // bottom out in `None` in the case that this type is
        // just now being defined, but this should otherwise follow
        // chains of aliases to determine what exactly this was a
        // `use` of if it exists.
        let mut prev = None;
        let mut cur = id;
        while prev.is_none() {
            prev = self.type_map.get(&cur).copied();
            cur = match self.types.as_ref().peel_alias(cur) {
                Some(next) => next,
                None => break,
            };
        }
        prev
    }

    /// This will parse the `name_string` as a component model ID string and
    /// ensure that there's an `InterfaceId` corresponding to its components.
    fn extract_dep_interface(
        &mut self,
        name_string: &str,
        item: &ComponentItem,
    ) -> Result<InterfaceId> {
        let name = ComponentName::new(name_string, 0).unwrap();
        let name = match name.kind() {
            ComponentNameKind::Interface(name) => name,
            _ => bail!("package name is not a valid id: {name_string}"),
        };
        let package_name = name.to_package_name(item)?;
        // Lazily create a `Package` as necessary, along with the interface.
        let package = self
            .foreign_packages
            .entry(package_name.to_string())
            .or_insert_with(|| Package {
                name: package_name.clone(),
                docs: Default::default(),
                interfaces: Default::default(),
                worlds: Default::default(),
            });
        let interface = *package
            .interfaces
            .entry(name.interface().to_string())
            .or_insert_with(|| {
                self.resolve.interfaces.alloc(Interface {
                    name: Some(name.interface().to_string()),
                    docs: Default::default(),
                    types: IndexMap::default(),
                    functions: IndexMap::default(),
                    package: None,
                    stability: Default::default(),
                    span: Default::default(),
                    clone_of: None,
                })
            });

        // Record a mapping of which foreign package this interface belongs to
        self.iface_to_package_index.insert(
            interface,
            self.foreign_packages
                .get_full(&package_name.to_string())
                .unwrap()
                .0,
        );
        Ok(interface)
    }

    /// A general-purpose helper function to translate a component instance
    /// into a WIT interface.
    ///
    /// This is one of the main workhorses of this module. This handles
    /// interfaces both at the type level, for concrete components, and
    /// internally within worlds as well.
    ///
    /// The `name` provided is the contextual ID or name of the interface. This
    /// could be a kebab-name in the case of a world import or export or it can
    /// also be an ID. This is used to guide insertion into various maps.
    ///
    /// The `ty` provided is the actual component type being decoded.
    ///
    /// The `package` is where to insert the final interface if `name` is an ID
    /// meaning it's registered as a named standalone item within the package.
    fn register_interface<'a>(
        &mut self,
        name: &str,
        item: &ComponentItem,
        package: &mut PackageFields<'a>,
    ) -> Result<(WorldKey, InterfaceId)> {
        let ty = match item.ty {
            ComponentEntityType::Instance(i) => &self.types[i],
            _ => unreachable!(),
        };
        // If this interface's name is already known then that means this is an
        // interface that's both imported and exported.  Use `register_import`
        // to draw connections between types and this interface's types.
        if self.named_interfaces.contains_key(name) {
            let id = self.register_import(name, item)?;
            return Ok((WorldKey::Interface(id), id));
        }

        // If this is a bare kebab-name for an interface then the interface's
        // listed name is `None` and the name goes out through the key.
        // Otherwise this name is extracted from `name` interpreted as an ID.
        let interface_name = self.extract_interface_name_from_component_name(name)?;

        let mut interface = Interface {
            name: interface_name.clone(),
            docs: Default::default(),
            types: IndexMap::default(),
            functions: IndexMap::default(),
            package: None,
            stability: Default::default(),
            span: Default::default(),
            clone_of: None,
        };

        let owner = TypeOwner::Interface(self.resolve.interfaces.next_id());
        for (name, item) in ty.exports.iter() {
            match item.ty {
                ComponentEntityType::Type { .. } => {
                    let ty = self
                        .register_type_export(name.as_str(), item, owner)
                        .with_context(|| format!("failed to register type export '{name}'"))?;
                    let prev = interface.types.insert(name.to_string(), ty);
                    assert!(prev.is_none());
                }

                ComponentEntityType::Func(_) => {
                    let func = self
                        .convert_function(name.as_str(), item, owner)
                        .with_context(|| format!("failed to convert function '{name}'"))?;
                    let prev = interface.functions.insert(name.to_string(), func);
                    assert!(prev.is_none());
                }
                _ => bail!("instance type export `{name}` is not a type or function"),
            };
        }
        let id = self.resolve.interfaces.alloc(interface);
        let key = match interface_name {
            // If this interface is named then it's part of the package, so
            // insert it. Additionally register it in `named_interfaces` so
            // further use comes back to this original definition.
            Some(interface_name) => {
                let prev = package.interfaces.insert(interface_name, id);
                assert!(prev.is_none(), "duplicate interface added for {name:?}");
                let prev = self.named_interfaces.insert(name.to_string(), id);
                assert!(prev.is_none());
                WorldKey::Interface(id)
            }

            // If this interface isn't named then its key is always a
            // kebab-name.
            None => WorldKey::Name(name.to_string()),
        };
        Ok((key, id))
    }

    fn parse_component_name(&self, name: &str) -> Result<ComponentName> {
        ComponentName::new(name, 0)
            .with_context(|| format!("cannot extract item name from: {name}"))
    }

    fn extract_interface_name_from_component_name(&self, name: &str) -> Result<Option<String>> {
        let component_name = self.parse_component_name(name)?;
        match component_name.kind() {
            ComponentNameKind::Interface(name) => Ok(Some(name.interface().to_string())),
            ComponentNameKind::Label(_name) => Ok(None),
            _ => bail!("cannot extract item name from: {name}"),
        }
    }

    fn register_type_export(
        &mut self,
        name: &str,
        item: &ComponentItem,
        owner: TypeOwner,
    ) -> Result<TypeId> {
        let (referenced, created) = match item.ty {
            ComponentEntityType::Type {
                referenced,
                created,
            } => (referenced, created),
            _ => unreachable!(),
        };
        let kind = match self.find_alias(referenced) {
            // If this `TypeId` points to a type which has
            // previously been defined, meaning we're aliasing a
            // prior definition.
            Some(prev) => {
                log::debug!("type export for `{name}` is an alias");
                TypeDefKind::Type(Type::Id(prev))
            }

            // ... or this `TypeId`'s source definition has never
            // been seen before, so declare the full type.
            None => {
                log::debug!("type export for `{name}` is a new type");
                match referenced {
                    ComponentAnyTypeId::Defined(ty) => self
                        .convert_defined(&self.types[ty])
                        .context("failed to convert unaliased type")?,
                    ComponentAnyTypeId::Resource(_) => TypeDefKind::Resource,
                    _ => unreachable!(),
                }
            }
        };
        let ty = self.resolve.types.alloc(TypeDef {
            name: Some(name.to_string()),
            kind,
            docs: Default::default(),
            stability: Default::default(),
            owner,
            span: Default::default(),
            external_id: item.external_id.clone(),
        });

        // If this is a resource then doubly-register it in `self.resources` so
        // the ID allocated here can be looked up via name later on during
        // `convert_function`.
        if let TypeDefKind::Resource = self.resolve.types[ty].kind {
            let prev = self
                .resources
                .entry(owner)
                .or_insert(HashMap::new())
                .insert(name.to_string(), ty);
            assert!(prev.is_none());
        }

        // A duplicate mapping here comes from a valid component that WIT cannot
        // represent (for example an imported resource re-exported under a new
        // name), not an internal invariant, so report it instead of asserting.
        let prev = self.type_map.insert(created, ty);
        if prev.is_some() {
            bail!(
                "cannot represent this component in WIT: the type `{name}` appears \
                 more than once (for example, when an imported instance is \
                 re-exported under a new name)"
            );
        }
        Ok(ty)
    }

    fn register_world<'a>(
        &mut self,
        name: &str,
        ty: &ComponentType,
        package: &mut PackageFields<'a>,
    ) -> Result<WorldId> {
        let name = self
            .extract_interface_name_from_component_name(name)?
            .context("expected world name to have an ID form")?;
        let mut world = World {
            name: name.clone(),
            docs: Default::default(),
            imports: Default::default(),
            exports: Default::default(),
            includes: Default::default(),
            package: None,
            stability: Default::default(),
            span: Default::default(),
        };

        let owner = TypeOwner::World(self.resolve.worlds.next_id());
        for (name, item) in ty.imports.iter() {
            let (name, item) = match item.ty {
                ComponentEntityType::Instance(_) => {
                    self.decode_world_instance(name, item, package)?
                }
                ComponentEntityType::Type { .. } => {
                    let ty = self.register_type_export(name.as_str(), item, owner)?;
                    (
                        WorldKey::Name(name.to_string()),
                        WorldItem::Type {
                            id: ty,
                            span: Default::default(),
                        },
                    )
                }
                ComponentEntityType::Func(_) => {
                    let func = self.convert_function(name.as_str(), item, owner)?;
                    (WorldKey::Name(name.to_string()), WorldItem::Function(func))
                }
                _ => bail!("component import `{name}` is not an instance, func, or type"),
            };
            world.imports.insert(name, item);
        }

        for (name, item) in ty.exports.iter() {
            let (name, item) = match item.ty {
                ComponentEntityType::Instance(_) => {
                    self.decode_world_instance(name, item, package)?
                }

                ComponentEntityType::Func(_) => {
                    let func = self.convert_function(name.as_str(), item, owner)?;
                    (WorldKey::Name(name.to_string()), WorldItem::Function(func))
                }

                _ => bail!("component export `{name}` is not an instance or function"),
            };
            world.exports.insert(name, item);
        }
        let id = self.resolve.worlds.alloc(world);
        let prev = package.worlds.insert(name, id);
        assert!(prev.is_none());
        Ok(id)
    }

    fn convert_function(
        &mut self,
        name: &str,
        item: &ComponentItem,
        owner: TypeOwner,
    ) -> Result<Function> {
        let ty = match item.ty {
            ComponentEntityType::Func(i) => &self.types[i],
            _ => unreachable!(),
        };
        let name = ComponentName::new(name, 0).unwrap();
        let params = ty
            .params
            .iter()
            .map(|(name, ty)| {
                Ok(Param {
                    name: name.to_string(),
                    ty: self.convert_valtype(ty)?,
                    span: Default::default(),
                })
            })
            .collect::<Result<Vec<_>>>()
            .context("failed to convert params")?;
        let result = match &ty.result {
            Some(ty) => Some(
                self.convert_valtype(ty)
                    .context("failed to convert anonymous result type")?,
            ),
            None => None,
        };
        Ok(Function {
            docs: Default::default(),
            stability: Default::default(),
            external_id: item.external_id.clone(),
            kind: match name.kind() {
                ComponentNameKind::Label(_) => {
                    if ty.async_ {
                        FunctionKind::AsyncFreestanding
                    } else {
                        FunctionKind::Freestanding
                    }
                }
                ComponentNameKind::Constructor(resource) => {
                    FunctionKind::Constructor(self.resources[&owner][resource.as_str()])
                }
                ComponentNameKind::Method(name) => {
                    if ty.async_ {
                        FunctionKind::AsyncMethod(self.resources[&owner][name.resource().as_str()])
                    } else {
                        FunctionKind::Method(self.resources[&owner][name.resource().as_str()])
                    }
                }
                ComponentNameKind::Static(name) => {
                    if ty.async_ {
                        FunctionKind::AsyncStatic(self.resources[&owner][name.resource().as_str()])
                    } else {
                        FunctionKind::Static(self.resources[&owner][name.resource().as_str()])
                    }
                }

                // Functions shouldn't have ID-based names at this time.
                ComponentNameKind::Interface(_)
                | ComponentNameKind::Url(_)
                | ComponentNameKind::Hash(_)
                | ComponentNameKind::Dependency(_) => unreachable!(),
            },

            // Note that this name includes "name mangling" such as
            // `[method]foo.bar` which is intentional. The `FunctionKind`
            // discriminant calculated above indicates how to interpret this
            // name.
            name: name.to_string(),
            params,
            result,
            span: Default::default(),
        })
    }

    fn convert_valtype(&mut self, ty: &ComponentValType) -> Result<Type> {
        let id = match ty {
            ComponentValType::Primitive(ty) => return Ok(self.convert_primitive(*ty)),
            ComponentValType::Type(id) => *id,
        };

        // Don't create duplicate types for anything previously created.
        let key: ComponentAnyTypeId = id.into();
        if let Some(ret) = self.type_map.get(&key) {
            return Ok(Type::Id(*ret));
        }

        // Otherwise create a new `TypeDef` without a name since this is an
        // anonymous valtype. Note that this is invalid for some types so return
        // errors on those types, but eventually the `bail!` here  is
        // more-or-less unreachable due to expected validation to be added to
        // the component model binary format itself.
        let def = &self.types[id];
        let kind = self.convert_defined(def)?;
        match &kind {
            TypeDefKind::Type(_)
            | TypeDefKind::List(_)
            | TypeDefKind::Map(_, _)
            | TypeDefKind::FixedLengthList(..)
            | TypeDefKind::Tuple(_)
            | TypeDefKind::Option(_)
            | TypeDefKind::Result(_)
            | TypeDefKind::Handle(_)
            | TypeDefKind::Future(_)
            | TypeDefKind::Stream(_) => {}

            TypeDefKind::Resource
            | TypeDefKind::Record(_)
            | TypeDefKind::Enum(_)
            | TypeDefKind::Variant(_)
            | TypeDefKind::Flags(_) => {
                bail!("unexpected unnamed type of kind '{}'", kind.as_str());
            }
            TypeDefKind::Unknown => unreachable!(),
        }
        let ty = self.resolve.types.alloc(TypeDef {
            name: None,
            docs: Default::default(),
            stability: Default::default(),
            owner: TypeOwner::None,
            kind,
            span: Default::default(),
            external_id: None,
        });
        let prev = self.type_map.insert(id.into(), ty);
        assert!(prev.is_none());
        Ok(Type::Id(ty))
    }

    /// Converts a wasmparser `ComponentDefinedType`, the definition of a type
    /// in the component model, to a WIT `TypeDefKind` to get inserted into the
    /// types arena by the caller.
    fn convert_defined(&mut self, ty: &ComponentDefinedType) -> Result<TypeDefKind> {
        match ty {
            ComponentDefinedType::Primitive(t) => Ok(TypeDefKind::Type(self.convert_primitive(*t))),

            ComponentDefinedType::List(t) => {
                let t = self.convert_valtype(t)?;
                Ok(TypeDefKind::List(t))
            }

            ComponentDefinedType::Map(k, v) => {
                let k = self.convert_valtype(k)?;
                let v = self.convert_valtype(v)?;
                Ok(TypeDefKind::Map(k, v))
            }

            ComponentDefinedType::FixedLengthList(t, size) => {
                let t = self.convert_valtype(t)?;
                Ok(TypeDefKind::FixedLengthList(t, *size))
            }

            ComponentDefinedType::Tuple(t) => {
                let types = t
                    .types
                    .iter()
                    .map(|t| self.convert_valtype(t))
                    .collect::<Result<_>>()?;
                Ok(TypeDefKind::Tuple(Tuple { types }))
            }

            ComponentDefinedType::Option(t) => {
                let t = self.convert_valtype(t)?;
                Ok(TypeDefKind::Option(t))
            }

            ComponentDefinedType::Result { ok, err } => {
                let ok = match ok {
                    Some(t) => Some(self.convert_valtype(t)?),
                    None => None,
                };
                let err = match err {
                    Some(t) => Some(self.convert_valtype(t)?),
                    None => None,
                };
                Ok(TypeDefKind::Result(Result_ { ok, err }))
            }

            ComponentDefinedType::Record(r) => {
                let fields = r
                    .fields
                    .iter()
                    .map(|(name, ty)| {
                        Ok(Field {
                            name: name.to_string(),
                            ty: self.convert_valtype(ty).with_context(|| {
                                format!("failed to convert record field '{name}'")
                            })?,
                            docs: Default::default(),
                            span: Default::default(),
                        })
                    })
                    .collect::<Result<_>>()?;
                Ok(TypeDefKind::Record(Record { fields }))
            }

            ComponentDefinedType::Variant(v) => {
                let cases = v
                    .cases
                    .iter()
                    .map(|(name, case)| {
                        Ok(Case {
                            name: name.to_string(),
                            ty: match &case.ty {
                                Some(ty) => Some(self.convert_valtype(ty)?),
                                None => None,
                            },
                            docs: Default::default(),
                            span: Default::default(),
                        })
                    })
                    .collect::<Result<_>>()?;
                Ok(TypeDefKind::Variant(Variant { cases }))
            }

            ComponentDefinedType::Flags(f) => {
                let flags = f
                    .iter()
                    .map(|name| Flag {
                        name: name.to_string(),
                        docs: Default::default(),
                        span: Default::default(),
                    })
                    .collect();
                Ok(TypeDefKind::Flags(Flags { flags }))
            }

            ComponentDefinedType::Enum(e) => {
                let cases = e
                    .iter()
                    .cloned()
                    .map(|name| EnumCase {
                        name: name.into(),
                        docs: Default::default(),
                        span: Default::default(),
                    })
                    .collect();
                Ok(TypeDefKind::Enum(Enum { cases }))
            }

            ComponentDefinedType::Own(id) => {
                let key: ComponentAnyTypeId = (*id).into();
                let id = self.type_map[&key];
                Ok(TypeDefKind::Handle(Handle::Own(id)))
            }

            ComponentDefinedType::Borrow(id) => {
                let key: ComponentAnyTypeId = (*id).into();
                let id = self.type_map[&key];
                Ok(TypeDefKind::Handle(Handle::Borrow(id)))
            }

            ComponentDefinedType::Future(ty) => Ok(TypeDefKind::Future(
                ty.as_ref().map(|ty| self.convert_valtype(ty)).transpose()?,
            )),

            ComponentDefinedType::Stream(ty) => Ok(TypeDefKind::Stream(
                ty.as_ref().map(|ty| self.convert_valtype(ty)).transpose()?,
            )),
        }
    }

    fn convert_primitive(&self, ty: PrimitiveValType) -> Type {
        match ty {
            PrimitiveValType::U8 => Type::U8,
            PrimitiveValType::S8 => Type::S8,
            PrimitiveValType::U16 => Type::U16,
            PrimitiveValType::S16 => Type::S16,
            PrimitiveValType::U32 => Type::U32,
            PrimitiveValType::S32 => Type::S32,
            PrimitiveValType::U64 => Type::U64,
            PrimitiveValType::S64 => Type::S64,
            PrimitiveValType::Bool => Type::Bool,
            PrimitiveValType::Char => Type::Char,
            PrimitiveValType::String => Type::String,
            PrimitiveValType::F32 => Type::F32,
            PrimitiveValType::F64 => Type::F64,
            PrimitiveValType::ErrorContext => Type::ErrorContext,
        }
    }

    fn register_defined(&mut self, id: TypeId, def: &ComponentDefinedType) -> Result<()> {
        Registrar {
            types: &self.types,
            type_map: &mut self.type_map,
            resolve: &self.resolve,
        }
        .defined(id, def)
    }

    /// Completes the decoding of this resolve by finalizing all packages into
    /// their topological ordering within the returned `Resolve`.
    ///
    /// Takes the root package as an argument to insert.
    fn finish(mut self, package: Package) -> (Resolve, PackageId) {
        // Build a topological ordering is then calculated by visiting all the
        // transitive dependencies of packages.
        let mut order = IndexSet::default();
        for i in 0..self.foreign_packages.len() {
            self.visit_package(i, &mut order);
        }

        // Using the topological ordering create a temporary map from
        // index-in-`foreign_packages` to index-in-`order`
        let mut idx_to_pos = vec![0; self.foreign_packages.len()];
        for (pos, idx) in order.iter().enumerate() {
            idx_to_pos[*idx] = pos;
        }
        // .. and then using `idx_to_pos` sort the `foreign_packages` array based
        // on the position it's at in the topological ordering
        let mut deps = mem::take(&mut self.foreign_packages)
            .into_iter()
            .enumerate()
            .collect::<Vec<_>>();
        deps.sort_by_key(|(idx, _)| idx_to_pos[*idx]);

        // .. and finally insert the packages, in their final topological
        // ordering, into the returned array.
        for (_idx, (_url, pkg)) in deps {
            self.insert_package(pkg);
        }

        let id = self.insert_package(package);
        assert!(self.resolve.worlds.iter().all(|(_, w)| w.package.is_some()));
        assert!(
            self.resolve
                .interfaces
                .iter()
                .all(|(_, i)| i.package.is_some())
        );
        (self.resolve, id)
    }

    fn insert_package(&mut self, package: Package) -> PackageId {
        let Package {
            name,
            interfaces,
            worlds,
            docs,
        } = package;

        // Most of the time the `package` being inserted is not already present
        // in `self.resolve`, but in the case of the top-level `decode_world`
        // function this isn't the case. This shouldn't in general be a problem
        // so union-up the packages here while asserting that nothing gets
        // replaced by accident which would indicate a bug.
        let pkg = self
            .resolve
            .package_names
            .get(&name)
            .copied()
            .unwrap_or_else(|| {
                let id = self.resolve.packages.alloc(Package {
                    name: name.clone(),
                    interfaces: Default::default(),
                    worlds: Default::default(),
                    docs,
                });
                let prev = self.resolve.package_names.insert(name, id);
                assert!(prev.is_none());
                id
            });

        for (name, id) in interfaces {
            let prev = self.resolve.packages[pkg].interfaces.insert(name, id);
            assert!(prev.is_none());
            self.resolve.interfaces[id].package = Some(pkg);
        }

        for (name, id) in worlds {
            let prev = self.resolve.packages[pkg].worlds.insert(name, id);
            assert!(prev.is_none());
            let world = &mut self.resolve.worlds[id];
            world.package = Some(pkg);
            for (name, item) in world.imports.iter().chain(world.exports.iter()) {
                if let WorldKey::Name(_) = name {
                    if let WorldItem::Interface { id, .. } = item {
                        let iface = &mut self.resolve.interfaces[*id];
                        if iface.name.is_none() {
                            iface.package = Some(pkg);
                        }
                    }
                }
            }
        }

        pkg
    }

    fn visit_package(&self, idx: usize, order: &mut IndexSet<usize>) {
        if order.contains(&idx) {
            return;
        }

        let (_name, pkg) = self.foreign_packages.get_index(idx).unwrap();
        let interfaces = pkg.interfaces.values().copied().chain(
            pkg.worlds
                .values()
                .flat_map(|w| {
                    let world = &self.resolve.worlds[*w];
                    world.imports.values().chain(world.exports.values())
                })
                .filter_map(|item| match item {
                    WorldItem::Interface { id, .. } => Some(*id),
                    WorldItem::Function(_) | WorldItem::Type { .. } => None,
                }),
        );
        for iface in interfaces {
            for dep in self.resolve.interface_direct_deps(iface) {
                let dep_idx = self.iface_to_package_index[&dep];
                if dep_idx != idx {
                    self.visit_package(dep_idx, order);
                }
            }
        }

        assert!(order.insert(idx));
    }
}

/// Helper type to register the structure of a wasm-defined type against a
/// wit-defined type.
struct Registrar<'a> {
    types: &'a Types,
    type_map: &'a mut HashMap<ComponentAnyTypeId, TypeId>,
    resolve: &'a Resolve,
}

impl Registrar<'_> {
    /// Verifies that the wasm structure of `def` matches the wit structure of
    /// `id` and recursively registers types.
    fn defined(&mut self, id: TypeId, def: &ComponentDefinedType) -> Result<()> {
        match def {
            ComponentDefinedType::Primitive(_) => Ok(()),

            ComponentDefinedType::List(t) => {
                let ty = match &self.resolve.types[id].kind {
                    TypeDefKind::List(r) => r,
                    // Note that all cases below have this match and the general
                    // idea is that once a type is named or otherwise identified
                    // here there's no need to recurse. The purpose of this
                    // registrar is to build connections for anonymous types
                    // that don't otherwise have a name to ensure that they're
                    // decoded to reuse the same constructs consistently. For
                    // that reason once something is named we can bail out.
                    TypeDefKind::Type(Type::Id(_)) => return Ok(()),
                    _ => bail!("expected a list"),
                };
                self.valtype(t, ty)
            }

            ComponentDefinedType::Map(k, v) => {
                let (key_ty, value_ty) = match &self.resolve.types[id].kind {
                    TypeDefKind::Map(k, v) => (k, v),
                    TypeDefKind::Type(Type::Id(_)) => return Ok(()),
                    _ => bail!("expected a map"),
                };
                self.valtype(k, key_ty)?;
                self.valtype(v, value_ty)
            }

            ComponentDefinedType::FixedLengthList(t, elements) => {
                let ty = match &self.resolve.types[id].kind {
                    TypeDefKind::FixedLengthList(r, elements2) if elements2 == elements => r,
                    TypeDefKind::Type(Type::Id(_)) => return Ok(()),
                    _ => bail!("expected a fixed-length {elements} list"),
                };
                self.valtype(t, ty)
            }

            ComponentDefinedType::Tuple(t) => {
                let ty = match &self.resolve.types[id].kind {
                    TypeDefKind::Tuple(r) => r,
                    TypeDefKind::Type(Type::Id(_)) => return Ok(()),
                    _ => bail!("expected a tuple"),
                };
                if ty.types.len() != t.types.len() {
                    bail!("mismatched number of tuple fields");
                }
                for (a, b) in t.types.iter().zip(ty.types.iter()) {
                    self.valtype(a, b)?;
                }
                Ok(())
            }

            ComponentDefinedType::Option(t) => {
                let ty = match &self.resolve.types[id].kind {
                    TypeDefKind::Option(r) => r,
                    TypeDefKind::Type(Type::Id(_)) => return Ok(()),
                    _ => bail!("expected an option"),
                };
                self.valtype(t, ty)
            }

            ComponentDefinedType::Result { ok, err } => {
                let ty = match &self.resolve.types[id].kind {
                    TypeDefKind::Result(r) => r,
                    TypeDefKind::Type(Type::Id(_)) => return Ok(()),
                    _ => bail!("expected a result"),
                };
                match (ok, &ty.ok) {
                    (Some(a), Some(b)) => self.valtype(a, b)?,
                    (None, None) => {}
                    _ => bail!("disagreement on result structure"),
                }
                match (err, &ty.err) {
                    (Some(a), Some(b)) => self.valtype(a, b)?,
                    (None, None) => {}
                    _ => bail!("disagreement on result structure"),
                }
                Ok(())
            }

            ComponentDefinedType::Record(def) => {
                let ty = match &self.resolve.types[id].kind {
                    TypeDefKind::Record(r) => r,
                    TypeDefKind::Type(Type::Id(_)) => return Ok(()),
                    _ => bail!("expected a record"),
                };
                if def.fields.len() != ty.fields.len() {
                    bail!("mismatched number of record fields");
                }
                for ((name, ty), field) in def.fields.iter().zip(&ty.fields) {
                    if name.as_str() != field.name {
                        bail!("mismatched field order");
                    }
                    self.valtype(ty, &field.ty)?;
                }
                Ok(())
            }

            ComponentDefinedType::Variant(def) => {
                let ty = match &self.resolve.types[id].kind {
                    TypeDefKind::Variant(r) => r,
                    TypeDefKind::Type(Type::Id(_)) => return Ok(()),
                    _ => bail!("expected a variant"),
                };
                if def.cases.len() != ty.cases.len() {
                    bail!("mismatched number of variant cases");
                }
                for ((name, ty), case) in def.cases.iter().zip(&ty.cases) {
                    if name.as_str() != case.name {
                        bail!("mismatched case order");
                    }
                    match (&ty.ty, &case.ty) {
                        (Some(a), Some(b)) => self.valtype(a, b)?,
                        (None, None) => {}
                        _ => bail!("disagreement on case type"),
                    }
                }
                Ok(())
            }

            ComponentDefinedType::Future(payload) => {
                let ty = match &self.resolve.types[id].kind {
                    TypeDefKind::Future(p) => p,
                    TypeDefKind::Type(Type::Id(_)) => return Ok(()),
                    _ => bail!("expected a future"),
                };
                match (payload, ty) {
                    (Some(a), Some(b)) => self.valtype(a, b),
                    (None, None) => Ok(()),
                    _ => bail!("disagreement on future payload"),
                }
            }

            ComponentDefinedType::Stream(payload) => {
                let ty = match &self.resolve.types[id].kind {
                    TypeDefKind::Stream(p) => p,
                    TypeDefKind::Type(Type::Id(_)) => return Ok(()),
                    _ => bail!("expected a stream"),
                };
                match (payload, ty) {
                    (Some(a), Some(b)) => self.valtype(a, b),
                    (None, None) => Ok(()),
                    _ => bail!("disagreement on stream payload"),
                }
            }

            // These have no recursive structure so they can bail out.
            ComponentDefinedType::Flags(_)
            | ComponentDefinedType::Enum(_)
            | ComponentDefinedType::Own(_)
            | ComponentDefinedType::Borrow(_) => Ok(()),
        }
    }

    fn valtype(&mut self, wasm: &ComponentValType, wit: &Type) -> Result<()> {
        let wasm = match wasm {
            ComponentValType::Type(wasm) => *wasm,
            ComponentValType::Primitive(_wasm) => {
                assert!(!matches!(wit, Type::Id(_)));
                return Ok(());
            }
        };
        let wit = match wit {
            Type::Id(id) => *id,
            _ => bail!("expected id-based type"),
        };
        let prev = match self.type_map.insert(wasm.into(), wit) {
            Some(prev) => prev,
            None => {
                let wasm = &self.types[wasm];
                return self.defined(wit, wasm);
            }
        };
        // If `wit` matches `prev` then we've just rediscovered what we already
        // knew which is that the `wasm` id maps to the `wit` id.
        //
        // If, however, `wit` is not equal to `prev` then that's more
        // interesting. Consider a component such as:
        //
        // ```wasm
        // (component
        //   (import (interface "a:b/name") (instance
        //      (type $l (list string))
        //      (type $foo (variant (case "l" $l)))
        //      (export "foo" (type (eq $foo)))
        //   ))
        //   (component $c
        //     (type $l (list string))
        //     (type $bar (variant (case "n" u16) (case "l" $l)))
        //     (export "bar" (type $bar))
        //     (type $foo (variant (case "l" $l)))
        //     (export "foo" (type $foo))
        //   )
        //   (instance $i (instantiate $c))
        //   (export (interface "a:b/name") (instance $i))
        // )
        // ```
        //
        // This roughly corresponds to:
        //
        // ```wit
        // package a:b
        //
        // interface name {
        //   variant bar {
        //     n(u16),
        //     l(list<string>),
        //   }
        //
        //   variant foo {
        //     l(list<string>),
        //   }
        // }
        //
        // world module {
        //   import name
        //   export name
        // }
        // ```
        //
        // In this situation first we'll see the `import` which records type
        // information for the `foo` type in `interface name`. Later on the full
        // picture of `interface name` becomes apparent with the export of a
        // component which has full type information. When walking over this
        // first `bar` is seen and its recursive structure.
        //
        // The problem arises when walking over the `foo` type. In this
        // situation the code path we're currently on will be hit because
        // there's a preexisting definition of `foo` from the import and it's
        // now going to be unified with what we've seen in the export. When
        // visiting the `list<string>` case of the `foo` variant this ends up
        // being different than the `list<string>` used by the `bar` variant. The
        // reason for this is that when visiting `bar` the wasm-defined `(list
        // string)` hasn't been seen before so a new type is allocated. Later
        // though this same wasm type is unified with the first `(list string)`
        // type in the `import`.
        //
        // All-in-all this ends up meaning that it's possible for `prev` to not
        // match `wit`. In this situation it means the decoded WIT interface
        // will have duplicate definitions of `list<string>`. This is,
        // theoretically, not that big of a problem because the same underlying
        // definition is still there and the meaning of the type is the same.
        // This can, however, perhaps be a problem for consumers where it's
        // assumed that all `list<string>` are equal and there's only one. For
        // example a bindings generator for C may assume that `list<string>`
        // will only appear once and generate a single name for it, but with two
        // different types in play here it may generate two types of the same
        // name (or something like that).
        //
        // For now though this is left for a future refactoring. Fixing this
        // issue would require tracking anonymous types during type translation
        // so the decoding process for the `bar` export would reuse the
        // `list<string>` type created from decoding the `foo` import. That's
        // somewhat nontrivial at this time, so it's left for a future
        // refactoring.
        let _ = prev;
        Ok(())
    }
}

pub(crate) trait InterfaceNameExt {
    fn to_package_name(&self, item: &ComponentItem) -> Result<PackageName>;
}

impl InterfaceNameExt for wasmparser::names::InterfaceName<'_> {
    fn to_package_name(&self, item: &ComponentItem) -> Result<PackageName> {
        Ok(PackageName {
            namespace: self.namespace().to_string(),
            name: self.package().to_string(),
            version: self.version(item.version_suffix.as_deref())?,
        })
    }
}