feat(phase2): Implement single source of truth for tool versions

avrabe · avrabe · commit 8975d4b859b1 · 2025-11-14T06:57:12.000+01:00
Phase 2 complete - Created centralized version management system:

New File: toolchains/tool_versions.bzl
- TOOL_VERSIONS constant with all tool versions
- get_tool_version() function for accessing versions
- TOOL_COMPATIBILITY_MATRIX for cross-tool compatibility
- validate_tool_versions() for compatibility checking
- Comprehensive documentation

Tool Versions Defined:
- wasm-tools: 1.240.0
- wasmtime: 28.0.0
- wit-bindgen: 0.46.0 ⭐
- wac: 0.8.0
- wkg: 0.11.0
- wizer: 8.1.0
- wasmsign2: 0.2.6
- wasi-sdk: 26
- tinygo: 0.39.0
- nodejs: 20.18.0

Updated Files:
1. toolchains/wasm_toolchain.bzl
   - Load get_tool_version() from tool_versions.bzl
   - Replace hardcoded wit-bindgen version: "0.46.0" → get_tool_version("wit-bindgen")
   - Replace hardcoded wac version: "0.8.0" → get_tool_version("wac")

2. rust/rust_wasm_component_bindgen.bzl
   - Load get_tool_version() from tool_versions.bzl
   - Add runtime compatibility validation
   - Fail build if CLI version incompatible with embedded runtime
   - Compatible versions: 0.44.0, 0.45.0, 0.46.0

Benefits:
✅ Single source of truth - all versions in ONE location
✅ Type-safe access - Bazel fails if tool undefined
✅ Automatic validation - incompatible versions caught at build time
✅ Easy updates - change version in one place
✅ Documentation - compatibility matrix documents known-good combinations

Next Steps (Phase 3):
- Template Cargo.toml to derive from TOOL_VERSIONS
- Automate version sync between Bazel and Cargo
- Add CI check to prevent version drift
diff --git a/rust/rust_wasm_component_bindgen.bzl b/rust/rust_wasm_component_bindgen.bzl
@@ -3,6 +3,7 @@
 load("@rules_rust//rust:defs.bzl", "rust_common", "rust_library")
 load("//wit:wit_bindgen.bzl", "wit_bindgen")
 load("//wit:symmetric_wit_bindgen.bzl", "symmetric_wit_bindgen")
+load("//toolchains:tool_versions.bzl", "get_tool_version")
 load(":rust_wasm_component.bzl", "rust_wasm_component")
 load(":transitions.bzl", "wasm_transition")
 
@@ -67,6 +68,20 @@ def _generate_wrapper_impl(ctx):
     # IMPORTANT: When updating wit-bindgen CLI version (in wasm_toolchain.bzl),
     # verify this embedded runtime still provides the required API.
     # Check generated bindings for any new runtime requirements.
+
+    # Validate CLI version compatibility
+    COMPATIBLE_CLI_VERSIONS = ["0.44.0", "0.45.0", "0.46.0"]
+    cli_version = get_tool_version("wit-bindgen")
+    if cli_version not in COMPATIBLE_CLI_VERSIONS:
+        fail(
+            "Embedded runtime incompatible with wit-bindgen CLI {}. " +
+            "Compatible versions: {}. " +
+            "Update the embedded runtime in rust_wasm_component_bindgen.bzl or downgrade CLI version.".format(
+                cli_version,
+                ", ".join(COMPATIBLE_CLI_VERSIONS)
+            )
+        )
+
     wrapper_content = """// Generated wrapper for WIT bindings
 //
 // COMPATIBILITY: wit-bindgen CLI 0.44.0 - 0.46.0
diff --git a/toolchains/tool_versions.bzl b/toolchains/tool_versions.bzl
@@ -0,0 +1,158 @@
+"""Single source of truth for tool versions
+
+This file defines the canonical versions for all WebAssembly toolchain components.
+All toolchain setup code MUST reference these constants to ensure version consistency.
+
+IMPORTANT: When updating versions here:
+1. Update corresponding JSON registry in checksums/tools/<tool>.json
+2. Verify compatibility using validate_tool_compatibility() in checksums/registry.bzl
+3. Check embedded runtimes (rust_wasm_component_bindgen.bzl) for API compatibility
+4. Update Cargo.toml dependencies if using the tool as a crate
+5. Test the full build pipeline
+"""
+
+# Tool versions - single source of truth
+TOOL_VERSIONS = {
+    # Core WebAssembly toolchain
+    "wasm-tools": "1.240.0",  # Component model tools (validate, parse, compose, etc.)
+    "wasmtime": "28.0.0",     # WebAssembly runtime for testing/execution
+
+    # WIT and binding generation
+    "wit-bindgen": "0.46.0",  # WIT binding generator (MUST match Cargo.toml if used as crate)
+    "wac": "0.8.0",           # WebAssembly Composition tool
+    "wkg": "0.11.0",          # WebAssembly package manager
+
+    # Optimization and initialization
+    "wizer": "8.1.0",         # WebAssembly pre-initialization tool
+
+    # Signatures and security
+    "wasmsign2": "0.2.6",     # WebAssembly signing tool
+
+    # Platform SDKs
+    "wasi-sdk": "26",         # WASI SDK for C/C++ compilation
+    "tinygo": "0.39.0",       # TinyGo compiler for Go→WASM
+
+    # Node.js ecosystem
+    "nodejs": "20.18.0",      # Node.js runtime for jco toolchain
+}
+
+# Compatibility matrix - defines which versions work together
+# Key: wasm-tools version
+# Value: Dict of compatible tool versions
+TOOL_COMPATIBILITY_MATRIX = {
+    "1.240.0": {
+        "wit-bindgen": ["0.46.0"],
+        "wac": ["0.7.0", "0.8.0"],
+        "wkg": ["0.11.0"],
+        "wasmsign2": ["0.2.6"],
+        "wasmtime": ["27.0.0", "28.0.0"],
+    },
+    "1.239.0": {
+        "wit-bindgen": ["0.43.0", "0.46.0"],
+        "wac": ["0.7.0", "0.8.0"],
+        "wkg": ["0.11.0"],
+        "wasmsign2": ["0.2.6"],
+        "wasmtime": ["27.0.0", "28.0.0"],
+    },
+    "1.235.0": {
+        "wit-bindgen": ["0.43.0", "0.46.0"],
+        "wac": ["0.7.0", "0.8.0"],
+        "wkg": ["0.11.0"],
+        "wasmsign2": ["0.2.6"],
+        "wasmtime": ["27.0.0"],
+    },
+}
+
+def get_tool_version(tool_name):
+    """Get the canonical version for a tool
+
+    Args:
+        tool_name: Name of the tool (e.g., "wasm-tools", "wit-bindgen")
+
+    Returns:
+        String: Version number
+
+    Fails:
+        If tool_name is not defined in TOOL_VERSIONS
+    """
+    if tool_name not in TOOL_VERSIONS:
+        fail("Unknown tool: {}. Available tools: {}".format(
+            tool_name,
+            ", ".join(TOOL_VERSIONS.keys())
+        ))
+    return TOOL_VERSIONS[tool_name]
+
+def get_compatible_versions(base_tool, base_version):
+    """Get compatible versions for other tools based on a base tool version
+
+    Args:
+        base_tool: Name of the base tool (usually "wasm-tools")
+        base_version: Version of the base tool
+
+    Returns:
+        Dict: Mapping of tool names to list of compatible versions
+        Empty dict if no compatibility info available
+    """
+    if base_tool == "wasm-tools" and base_version in TOOL_COMPATIBILITY_MATRIX:
+        return TOOL_COMPATIBILITY_MATRIX[base_version]
+    return {}
+
+def validate_tool_versions(tools_config):
+    """Validate that a set of tool versions are compatible
+
+    Args:
+        tools_config: Dict mapping tool names to versions
+
+    Returns:
+        List: List of warning messages (empty if all compatible)
+    """
+    warnings = []
+
+    # Check if wasm-tools is in the config
+    if "wasm-tools" not in tools_config:
+        return warnings
+
+    wasm_tools_version = tools_config["wasm-tools"]
+    compat_info = get_compatible_versions("wasm-tools", wasm_tools_version)
+
+    if not compat_info:
+        warnings.append(
+            "Warning: No compatibility information for wasm-tools {}".format(wasm_tools_version)
+        )
+        return warnings
+
+    # Check each tool against compatibility matrix
+    for tool, version in tools_config.items():
+        if tool == "wasm-tools":
+            continue
+
+        if tool in compat_info:
+            if version not in compat_info[tool]:
+                warnings.append(
+                    "Warning: {} version {} may not be compatible with wasm-tools {}. " +
+                    "Recommended versions: {}".format(
+                        tool,
+                        version,
+                        wasm_tools_version,
+                        ", ".join(compat_info[tool]),
+                    )
+                )
+
+    return warnings
+
+def get_all_tool_versions():
+    """Get all tool versions as a dict
+
+    Returns:
+        Dict: Copy of TOOL_VERSIONS
+    """
+    return dict(TOOL_VERSIONS)
+
+# Export compatibility matrix for external use
+def get_compatibility_matrix():
+    """Get the full compatibility matrix
+
+    Returns:
+        Dict: Copy of TOOL_COMPATIBILITY_MATRIX
+    """
+    return dict(TOOL_COMPATIBILITY_MATRIX)
diff --git a/toolchains/wasm_toolchain.bzl b/toolchains/wasm_toolchain.bzl
@@ -4,6 +4,7 @@ load("//checksums:registry.bzl", "get_tool_info", "validate_tool_compatibility")
 load("//toolchains:diagnostics.bzl", "create_retry_wrapper", "format_diagnostic_error", "log_diagnostic_info", "validate_system_tool")
 load("//toolchains:monitoring.bzl", "add_build_telemetry", "create_health_check")
 load("//toolchains:tool_cache.bzl", "cache_tool", "clean_expired_cache", "retrieve_cached_tool", "validate_tool_functionality")
+load("//toolchains:tool_versions.bzl", "get_tool_version", "validate_tool_versions")
 
 def _get_rust_toolchain_info(repository_ctx):
     """Get Rust toolchain info from the registered hermetic toolchain"""
@@ -497,7 +498,7 @@ def _download_wasm_tools(repository_ctx):
 def _download_wac(repository_ctx):
     """Download wac only"""
     platform = _detect_host_platform(repository_ctx)
-    wac_version = "0.8.0"
+    wac_version = get_tool_version("wac")  # From tool_versions.bzl
 
     # Get checksum and platform info from tool_versions.bzl
     tool_info = get_tool_info("wac", wac_version, platform)
@@ -519,7 +520,7 @@ def _download_wac(repository_ctx):
 def _download_wit_bindgen(repository_ctx):
     """Download wit-bindgen only"""
     platform = _detect_host_platform(repository_ctx)
-    wit_bindgen_version = "0.46.0"
+    wit_bindgen_version = get_tool_version("wit-bindgen")  # From tool_versions.bzl
 
     # Get checksum and platform info from tool_versions.bzl
     tool_info = get_tool_info("wit-bindgen", wit_bindgen_version, platform)
