Fix Go component WIT dependency resolution issues

[avrabe]

Problem

Go component examples fail during WIT markdown documentation generation due to missing WASI dependencies.

Error

Error: failed to resolve directory while parsing WIT for path [bazel-out/k8-fastbuild/bin/examples/go_component/calculator_wit_wit]

Caused by:
    package 'wasi:io@0.2.0' not found. known packages:
        example:calculator@1.0.0
    
         --> calculator.wit:40:12
          |
       40 |     import wasi:io/streams@0.2.0;
          |            ^------

Root Cause

The Go component WIT files import WASI interfaces but the WIT dependency resolution isn't configured properly:

• Missing WASI package dependencies in WIT resolution
• wit-bindgen markdown command can't find required WASI interfaces
• Affects documentation generation for Go components

Current Workaround

Excluded //examples/go_component/... from CI builds, but the exclusion might not be working properly due to dependency chains.

Proposed Solution

1. Add proper WASI dependencies to Go component WIT files
2. Configure wit-bindgen with correct WASI package paths
3. Review wit_library rule configuration for proper dependency handling
4. Ensure WASI interfaces are available during documentation generation

Impact

• Go component examples can't generate documentation
• Affects all Go components that use WASI interfaces
• Core functionality works but documentation generation fails

Priority

Medium - affects documentation and examples but not core functionality

[avrabe]

🎉 Issue Resolved

I've successfully implemented a Bazel-native solution for external WIT dependency resolution that fixes the Go component documentation generation issues.

✅ Solution Summary

Problem: Go component examples failed during WIT markdown documentation generation due to missing WASI dependencies (wasi:io/streams@0.2.0 not found).

Root Cause: No mechanism existed to resolve external WIT dependencies like WASI interfaces.

Solution: Implemented a complete Bazel-native dependency management system following the project's "Bazel-first" principles.

🔧 Technical Implementation

1. WASI WIT Dependencies (wit/wasi_deps.bzl)

   • Added http_archive rules for WASI interface definitions
   • Supports wasi:io@0.2.6 with SHA256 verification
   • Extensible for additional WASI packages (filesystem, clocks, etc.)

2. Module Extension (wasm/extensions.bzl)

   • Created wasi_wit extension for dependency loading
   • Integrates with existing toolchain infrastructure

3. Configuration (MODULE.bazel)

   • Enabled via wasi_wit_ext.init()
   • Makes @wasi_io//:streams available project-wide

4. Fixed Go Components

   • Updated calculator.wit to use wasi:io/streams@0.2.6
   • Added proper deps = ["@wasi_io//:streams"] to wit_library
   • Re-enabled //examples/go_component/... in CI

📚 Documentation Added

• Comprehensive Guide: /docs-site/src/content/docs/guides/external-wit-dependencies.mdx
• Reference Examples: Updated wit_library rule documentation
• Quick Reference: Added to toolchain configuration guide

🧪 Testing

# Go component documentation now builds successfully
bazel build //examples/go_component:calculator_docs
bazel build //examples/go_component:http_service_docs

# CI targets re-enabled and working

🔄 Usage

Enable WASI dependencies:

# MODULE.bazel
wasi_wit_ext = use_extension("@rules_wasm_component//wasm:extensions.bzl", "wasi_wit")
wasi_wit_ext.init()
use_repo(wasi_wit_ext, "wasi_io")

Use in BUILD files:

wit_library(
    name = "my_component_wit",
    srcs = ["my-component.wit"],
    deps = ["@wasi_io//:streams"],
)

Import in WIT files:

world my-world {
    import wasi:io/streams@0.2.6;
    export my-api;
}

📈 Benefits

• ✅ Bazel-Native: Uses http_archive instead of shell scripts
• ✅ Cross-Platform: Works on all platforms without Unix dependencies
• ✅ Reproducible: Hermetic builds with SHA256 checksums
• ✅ Scalable: Easy to add more external WIT packages
• ✅ Documented: Complete guides for users

Commit: c7e5ebe

The Go component WIT dependency resolution is now working correctly! 🚀