feat: add lockfile and registry packages for BCR compatibility

Add two new packages to support Bazel Central Registry integration:

lockfile/: MODULE.bazel.lock compatibility
- Parse, write, merge lockfiles matching Bazel's format
- Exhaustive Bazel-to-lockfile version mapping (all releases 6.2.0-9.0.0)
- Bazel uses exact version matching (no forward/backward compat)
- Deterministic JSON output for reproducibility

registry/: BCR JSON Schema validation
- Embedded schemas for metadata.json and source.json
- Type-safe structs matching BCR format
- HTTP client with caching support

Complete version mapping (from BazelLockFileValue.java):
- v1:  6.2.x, 6.3.x (lockfile introduced in 6.2)
- v3:  6.4.x-6.6.x, 7.0.x
- v6:  7.1.x
- v11: 7.2.x-7.4.x (incremental format)
- v13: 7.5.x-7.7.x
- v16: 8.0.x (LTS)
- v18: 8.1.x-8.4.x
- v24: 8.5.x
- v26: 9.0.x

Author: albertocavalcante

lockfile/doc.go

@@ -0,0 +1,38 @@
+// Package lockfile provides types and operations for Bazel's MODULE.bazel.lock file.
+//
+// The lockfile captures the resolved state of module dependencies, ensuring
+// reproducible builds across machines and time. This package implements
+// Bazel's lockfile format (version 26+) for reading, writing, and manipulation.
+//
+// # Lockfile Structure
+//
+// A Bazel lockfile contains:
+//   - lockFileVersion: Schema version for format compatibility
+//   - registryFileHashes: Integrity hashes for registry files fetched
+//   - selectedYankedVersions: Explicitly allowed yanked versions
+//   - moduleExtensions: Cached results of module extension evaluations
+//   - facts: Additional facts about module extensions
+//
+// # Usage
+//
+// Read an existing lockfile:
+//
+//	lf, err := lockfile.ReadFile("MODULE.bazel.lock")
+//	if err != nil {
+//	    log.Fatal(err)
+//	}
+//	fmt.Printf("Lockfile version: %d\n", lf.Version)
+//
+// Create a new lockfile:
+//
+//	lf := lockfile.New()
+//	lf.SetRegistryHash("https://bcr.bazel.build/modules/rules_go/0.50.1/MODULE.bazel", hash)
+//	if err := lf.WriteFile("MODULE.bazel.lock"); err != nil {
+//	    log.Fatal(err)
+//	}
+//
+// # Compatibility
+//
+// This package targets lockfile version 26 (Bazel 7.x/8.x). Older versions
+// may have different schemas and are not fully supported.
+package lockfile

lockfile/io.go

@@ -0,0 +1,240 @@
+package lockfile
+
+import (
+	"bytes"
+	"encoding/json"
+	"fmt"
+	"io"
+	"os"
+	"sort"
+)
+
+// lockfilePermissions is the file permission mode for lockfiles.
+// Using 0600 for security (owner read/write only).
+const lockfilePermissions = 0o600
+
+// ReadFile reads and parses a lockfile from the given path.
+func ReadFile(path string) (*Lockfile, error) {
+	data, err := os.ReadFile(path)
+	if err != nil {
+		return nil, fmt.Errorf("failed to read lockfile: %w", err)
+	}
+	return Parse(data)
+}
+
+// Parse parses lockfile JSON data.
+func Parse(data []byte) (*Lockfile, error) {
+	var lf Lockfile
+	if err := json.Unmarshal(data, &lf); err != nil {
+		return nil, fmt.Errorf("failed to parse lockfile JSON: %w", err)
+	}
+
+	// Initialize nil maps to empty maps for consistency
+	if lf.RegistryFileHashes == nil {
+		lf.RegistryFileHashes = make(map[string]string)
+	}
+	if lf.SelectedYankedVersions == nil {
+		lf.SelectedYankedVersions = make(map[string]string)
+	}
+	if lf.ModuleExtensions == nil {
+		lf.ModuleExtensions = make(map[string]ModuleExtensionEntry)
+	}
+	if lf.Facts == nil {
+		lf.Facts = make(map[string]json.RawMessage)
+	}
+
+	return &lf, nil
+}
+
+// WriteFile writes the lockfile to the given path with deterministic formatting.
+func (l *Lockfile) WriteFile(path string) error {
+	data, err := l.Marshal()
+	if err != nil {
+		return err
+	}
+	return os.WriteFile(path, data, lockfilePermissions)
+}
+
+// WriteTo writes the lockfile to the given writer.
+func (l *Lockfile) WriteTo(w io.Writer) (int64, error) {
+	data, err := l.Marshal()
+	if err != nil {
+		return 0, err
+	}
+	n, err := w.Write(data)
+	return int64(n), err
+}
+
+// Marshal serializes the lockfile to JSON with deterministic key ordering.
+func (l *Lockfile) Marshal() ([]byte, error) {
+	// Use a custom marshaling approach for deterministic output
+	return marshalDeterministic(l)
+}
+
+// MarshalIndent serializes the lockfile with indentation for readability.
+func (l *Lockfile) MarshalIndent(prefix, indent string) ([]byte, error) {
+	data, err := l.Marshal()
+	if err != nil {
+		return nil, err
+	}
+
+	var buf bytes.Buffer
+	if err := json.Indent(&buf, data, prefix, indent); err != nil {
+		return nil, err
+	}
+	return buf.Bytes(), nil
+}
+
+// marshalDeterministic produces JSON with sorted keys for reproducibility.
+func marshalDeterministic(l *Lockfile) ([]byte, error) {
+	// Create ordered representation
+	ordered := orderedLockfile{
+		Version:                l.Version,
+		RegistryFileHashes:     sortedStringMap(l.RegistryFileHashes),
+		SelectedYankedVersions: sortedStringMap(l.SelectedYankedVersions),
+		ModuleExtensions:       sortedExtensions(l.ModuleExtensions),
+		Facts:                  sortedFacts(l.Facts),
+	}
+
+	var buf bytes.Buffer
+	encoder := json.NewEncoder(&buf)
+	encoder.SetEscapeHTML(false)
+	encoder.SetIndent("", "  ")
+	if err := encoder.Encode(ordered); err != nil {
+		return nil, err
+	}
+	return buf.Bytes(), nil
+}
+
+// orderedLockfile is used for deterministic JSON output.
+type orderedLockfile struct {
+	Version                int                  `json:"lockFileVersion"`
+	RegistryFileHashes     orderedStringMap     `json:"registryFileHashes"`
+	SelectedYankedVersions orderedStringMap     `json:"selectedYankedVersions"`
+	ModuleExtensions       orderedExtensionMap  `json:"moduleExtensions"`
+	Facts                  orderedRawMessageMap `json:"facts"`
+}
+
+// orderedStringMap maintains insertion order for JSON marshaling.
+type orderedStringMap struct {
+	keys   []string
+	values map[string]string
+}
+
+func sortedStringMap(m map[string]string) orderedStringMap {
+	keys := make([]string, 0, len(m))
+	for k := range m {
+		keys = append(keys, k)
+	}
+	sort.Strings(keys)
+	return orderedStringMap{keys: keys, values: m}
+}
+
+func (o orderedStringMap) MarshalJSON() ([]byte, error) {
+	if len(o.keys) == 0 {
+		return []byte("{}"), nil
+	}
+
+	var buf bytes.Buffer
+	buf.WriteByte('{')
+	for i, k := range o.keys {
+		if i > 0 {
+			buf.WriteByte(',')
+		}
+		keyJSON, _ := json.Marshal(k)
+		valJSON, _ := json.Marshal(o.values[k])
+		buf.Write(keyJSON)
+		buf.WriteByte(':')
+		buf.Write(valJSON)
+	}
+	buf.WriteByte('}')
+	return buf.Bytes(), nil
+}
+
+// orderedExtensionMap maintains insertion order for module extensions.
+type orderedExtensionMap struct {
+	keys   []string
+	values map[string]ModuleExtensionEntry
+}
+
+func sortedExtensions(m map[string]ModuleExtensionEntry) orderedExtensionMap {
+	keys := make([]string, 0, len(m))
+	for k := range m {
+		keys = append(keys, k)
+	}
+	sort.Strings(keys)
+	return orderedExtensionMap{keys: keys, values: m}
+}
+
+func (o orderedExtensionMap) MarshalJSON() ([]byte, error) {
+	if len(o.keys) == 0 {
+		return []byte("{}"), nil
+	}
+
+	var buf bytes.Buffer
+	buf.WriteByte('{')
+	for i, k := range o.keys {
+		if i > 0 {
+			buf.WriteByte(',')
+		}
+		keyJSON, _ := json.Marshal(k)
+		valJSON, err := json.Marshal(o.values[k])
+		if err != nil {
+			return nil, err
+		}
+		buf.Write(keyJSON)
+		buf.WriteByte(':')
+		buf.Write(valJSON)
+	}
+	buf.WriteByte('}')
+	return buf.Bytes(), nil
+}
+
+// orderedRawMessageMap maintains insertion order for facts.
+type orderedRawMessageMap struct {
+	keys   []string
+	values map[string]json.RawMessage
+}
+
+func sortedFacts(m map[string]json.RawMessage) orderedRawMessageMap {
+	keys := make([]string, 0, len(m))
+	for k := range m {
+		keys = append(keys, k)
+	}
+	sort.Strings(keys)
+	return orderedRawMessageMap{keys: keys, values: m}
+}
+
+func (o orderedRawMessageMap) MarshalJSON() ([]byte, error) {
+	if len(o.keys) == 0 {
+		return []byte("{}"), nil
+	}
+
+	var buf bytes.Buffer
+	buf.WriteByte('{')
+	for i, k := range o.keys {
+		if i > 0 {
+			buf.WriteByte(',')
+		}
+		keyJSON, _ := json.Marshal(k)
+		buf.Write(keyJSON)
+		buf.WriteByte(':')
+		buf.Write(o.values[k])
+	}
+	buf.WriteByte('}')
+	return buf.Bytes(), nil
+}
+
+// Exists returns true if a lockfile exists at the given path.
+func Exists(path string) bool {
+	_, err := os.Stat(path)
+	return err == nil
+}
+
+// DefaultPath returns the default lockfile path relative to a workspace root.
+func DefaultPath(workspaceRoot string) string {
+	if workspaceRoot == "" {
+		return "MODULE.bazel.lock"
+	}
+	return workspaceRoot + "/MODULE.bazel.lock"
+}