feat: auto-convert Go library deps to weak dependencies

Go packages with packaging: library are now automatically treated as
weak dependencies when referenced. This means:

- Source files are copied to _deps/ (not built artifacts)
- go.mod replace directives are added
- Builds run in parallel (don't block dependent package)
- Version tracking ensures cache invalidation when libraries change

This improves build parallelism for Go monorepos where libraries
are used for source code via go.mod replace, not for built artifacts.

Co-authored-by: Ona <no-reply@ona.com>

Author: iQQBot

README.md

@@ -108,6 +108,8 @@ srcs:
 - "glob/**/path"
 # Deps list dependencies to other packages which must be built prior to building this package. How these dependencies are made
 # available during build depends on the package type.
+# NOTE: Go packages with `packaging: library` are automatically treated as "weak dependencies" - their source files
+# are copied (not built artifacts), and they don't block the build. See "Go Library Dependencies" section below.
 deps:
 - some/other:package
 # Argdeps makes build arguments version relevant. I.e. if the value of a build arg listed here changes, so does the package version.
@@ -125,6 +127,8 @@ config:
 ```YAML
 config:
   # Packaging method. See https://godoc.org/github.com/gitpod-io/leeway/pkg/leeway#GoPackaging for details. Defaults to library.
+  # IMPORTANT: Packages with `packaging: library` are treated as "weak dependencies" when referenced by other packages.
+  # This means their source files are copied (not built artifacts), and they build in parallel rather than blocking.
   packaging: library
   # If true leeway runs `go generate -v ./...` prior to testing/building. Defaults to false.
   generate: false
@@ -144,6 +148,43 @@ config:
   goMod: "../go.mod"
 ```
 
+#### Go Library Dependencies (Weak Dependencies)
+
+When a Go package with `packaging: library` is listed as a dependency, leeway automatically treats it as a "weak dependency". This behavior is optimized for Go's module system:
+
+| Aspect | Regular Dependency | Go Library (Weak) Dependency |
+|--------|-------------------|------------------------------|
+| Affects package version | ✅ | ✅ |
+| Must be built first | ✅ | ❌ |
+| What's copied to `_deps/` | Built artifact | Source files |
+| `go.mod replace` added | ✅ | ✅ |
+| Added to build queue | ✅ | ✅ |
+
+**Why this matters:**
+- Go libraries are typically used for their source code via `go.mod replace` directives
+- The library's tests can run in parallel with the dependent package's build
+- Changes to the library still trigger rebuilds of dependent packages (version tracking)
+- Build times improve because packages don't wait for library builds to complete
+
+**Example:**
+```yaml
+# my-lib/BUILD.yaml
+packages:
+- name: lib
+  type: go
+  config:
+    packaging: library  # This makes it a weak dependency when referenced
+
+# my-app/BUILD.yaml  
+packages:
+- name: app
+  type: go
+  deps:
+    - my-lib:lib  # Automatically treated as weak dep - sources copied, builds in parallel
+  config:
+    packaging: app
+```
+
 ### Yarn packages
 ```YAML
 config:

pkg/leeway/build.go

@@ -687,6 +687,23 @@ func Build(pkg *Package, opts ...BuildOption) (err error) {
 	requirements := pkg.GetTransitiveDependencies()
 	allpkg := append(requirements, pkg)
 
+	// Add weak dependencies to the build queue (they'll be built in parallel, not as blockers)
+	// Weak deps are version-tracked and have sources copied, but don't block the main package build
+	weakDeps := collectWeakDependencies(pkg)
+	for _, wd := range weakDeps {
+		// Only add if not already in allpkg (avoid duplicates)
+		found := false
+		for _, p := range allpkg {
+			if p.FullName() == wd.FullName() {
+				found = true
+				break
+			}
+		}
+		if !found {
+			allpkg = append(allpkg, wd)
+		}
+	}
+
 	pkgsInLocalCache := make(map[*Package]struct{})
 	var pkgsToCheckRemoteCache []*Package
 	for _, p := range allpkg {
@@ -872,7 +889,25 @@ func Build(pkg *Package, opts ...BuildOption) (err error) {
 		return nil
 	}
 
-	buildErr := pkg.build(ctx)
+	// Start weak dependency builds in parallel with the main package build
+	// Weak deps don't block the main build but should run concurrently
+	var buildGroup errgroup.Group
+
+	// Build weak dependencies in parallel
+	for _, wd := range weakDeps {
+		weakDep := wd // capture for goroutine
+		buildGroup.Go(func() error {
+			return weakDep.build(ctx)
+		})
+	}
+
+	// Build the main package (and its hard dependencies)
+	buildGroup.Go(func() error {
+		return pkg.build(ctx)
+	})
+
+	// Wait for all builds to complete
+	buildErr := buildGroup.Wait()
 
 	// Check for build errors immediately and return if there are any
 	if buildErr != nil {
@@ -1462,6 +1497,53 @@ func (p *Package) packagesToDownload(inLocalCache map[*Package]struct{}, inRemot
 	}
 }
 
+// collectWeakDependencies collects all weak dependencies from a package and its dependency tree.
+// This includes:
+// - Direct weak deps of the package
+// - Weak deps of hard deps (recursively)
+// - Weak deps of weak deps (recursively) - e.g., Go library depending on another Go library
+// - Hard deps of weak deps (they need to be built for the weak dep to work)
+func collectWeakDependencies(pkg *Package) []*Package {
+	seen := make(map[string]struct{})      // tracks packages we've added to result
+	visited := make(map[string]struct{})   // tracks packages we've visited (to avoid infinite loops)
+	var result []*Package
+
+	var collectFromPackage func(p *Package)
+	collectFromPackage = func(p *Package) {
+		if _, ok := visited[p.FullName()]; ok {
+			return
+		}
+		visited[p.FullName()] = struct{}{}
+
+		// Collect weak deps from this package
+		for _, wd := range p.GetWeakDependencies() {
+			if _, ok := seen[wd.FullName()]; !ok {
+				seen[wd.FullName()] = struct{}{}
+				result = append(result, wd)
+			}
+
+			// Always recurse into weak dep to collect its deps (even if we've seen it)
+			collectFromPackage(wd)
+
+			// Also collect hard deps of weak deps (they need to be built)
+			for _, td := range wd.GetTransitiveDependencies() {
+				if _, ok := seen[td.FullName()]; !ok {
+					seen[td.FullName()] = struct{}{}
+					result = append(result, td)
+				}
+			}
+		}
+
+		// Recurse into hard dependencies (they may have weak deps too)
+		for _, dep := range p.GetDependencies() {
+			collectFromPackage(dep)
+		}
+	}
+
+	collectFromPackage(pkg)
+	return result
+}
+
 // validateDependenciesAvailable checks if all required dependencies of a package are available.
 // A dependency is considered available if it's in the local cache OR will be built (PackageNotBuiltYet).
 // Returns true if all dependencies are available, false otherwise.
@@ -2068,43 +2150,72 @@ func (p *Package) buildGo(buildctx *buildContext, wd, result string) (res *packa
 	}
 
 	transdep := p.GetTransitiveDependencies()
-	if len(transdep) > 0 {
+	weakdeps := p.GetTransitiveWeakDependencies() // Get ALL weak deps including nested ones
+	needsDepsDir := len(transdep) > 0 || len(weakdeps) > 0
+
+	if needsDepsDir {
 		commands[PackageBuildPhasePrep] = append(commands[PackageBuildPhasePrep], []string{"mkdir", "_deps"})
+	}
 
-		for _, dep := range transdep {
-			if dep.Ephemeral {
-				continue
-			}
+	// Handle hard dependencies (extract built artifacts)
+	for _, dep := range transdep {
+		if dep.Ephemeral {
+			continue
+		}
 
-			builtpkg, ok := buildctx.LocalCache.Location(dep)
-			if !ok {
-				return nil, PkgNotBuiltErr{dep}
-			}
+		builtpkg, ok := buildctx.LocalCache.Location(dep)
+		if !ok {
+			return nil, PkgNotBuiltErr{dep}
+		}
 
-			tgt := filepath.Join("_deps", p.BuildLayoutLocation(dep))
-			untarCmd, err := BuildUnTarCommand(
-				WithInputFile(builtpkg),
-				WithTargetDir(tgt),
-				WithAutoDetectCompression(true),
-			)
-			if err != nil {
-				return nil, err
-			}
+		tgt := filepath.Join("_deps", p.BuildLayoutLocation(dep))
+		untarCmd, err := BuildUnTarCommand(
+			WithInputFile(builtpkg),
+			WithTargetDir(tgt),
+			WithAutoDetectCompression(true),
+		)
+		if err != nil {
+			return nil, err
+		}
 
-			commands[PackageBuildPhasePrep] = append(commands[PackageBuildPhasePrep], [][]string{
-				{"mkdir", tgt},
-				untarCmd,
-			}...)
+		commands[PackageBuildPhasePrep] = append(commands[PackageBuildPhasePrep], [][]string{
+			{"mkdir", tgt},
+			untarCmd,
+		}...)
 
-			if dep.Type != GoPackage {
-				continue
-			}
+		if dep.Type != GoPackage {
+			continue
+		}
 
-			if isGoWorkspace {
-				commands[PackageBuildPhasePrep] = append(commands[PackageBuildPhasePrep], []string{"go", "work", "use", tgt})
-			} else {
-				commands[PackageBuildPhasePrep] = append(commands[PackageBuildPhasePrep], []string{"sh", "-c", fmt.Sprintf("%s mod edit -replace $(cd %s; grep module go.mod | cut -d ' ' -f 2 | head -n1)=./%s", goCommand, tgt, tgt)})
-			}
+		if isGoWorkspace {
+			commands[PackageBuildPhasePrep] = append(commands[PackageBuildPhasePrep], []string{"go", "work", "use", tgt})
+		} else {
+			commands[PackageBuildPhasePrep] = append(commands[PackageBuildPhasePrep], []string{"sh", "-c", fmt.Sprintf("%s mod edit -replace $(cd %s; grep module go.mod | cut -d ' ' -f 2 | head -n1)=./%s", goCommand, tgt, tgt)})
+		}
+	}
+
+	// Handle weak dependencies (copy source files, don't require built artifacts)
+	for _, dep := range weakdeps {
+		if dep.Type != GoPackage {
+			log.WithField("package", p.FullName()).WithField("weakdep", dep.FullName()).
+				Warn("weak dependencies are only supported for Go packages, skipping")
+			continue
+		}
+
+		tgt := filepath.Join("_deps", p.BuildLayoutLocation(dep))
+		srcDir := dep.C.Origin
+
+		// Copy source files from the weak dependency's component
+		commands[PackageBuildPhasePrep] = append(commands[PackageBuildPhasePrep], [][]string{
+			{"mkdir", "-p", tgt},
+			{"sh", "-c", fmt.Sprintf("cp -r %s/* %s/", srcDir, tgt)},
+		}...)
+
+		// Add go.mod replace directive for the weak dependency
+		if isGoWorkspace {
+			commands[PackageBuildPhasePrep] = append(commands[PackageBuildPhasePrep], []string{"go", "work", "use", tgt})
+		} else {
+			commands[PackageBuildPhasePrep] = append(commands[PackageBuildPhasePrep], []string{"sh", "-c", fmt.Sprintf("%s mod edit -replace $(cd %s; grep module go.mod | cut -d ' ' -f 2 | head -n1)=./%s", goCommand, tgt, tgt)})
 		}
 	}