fix: address PR review comments for shared variables fix

- Explicitly check relation count before GetOneByType in variables.go
  to make the multiple-parents guard more readable and future-safe
- Add unit test for order-dependent scenario (variables config first
  in Loaded) that previously caused the fatal crash
- Fix typo: lintRelations → linkRelations in link.go comment
- Fix doc directory layout: variables/variables/ → variables/values/

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: Matovidlo

docs/relations-validation.md

@@ -8,7 +8,7 @@ In the Keboola platform, variable configs (`keboola.variables` component) belong
 my-transformation/
   variables/
     config.json         ← keboola.variables config
-    variables/
+    values/
       default/          ← variables values row
 ```
 

internal/pkg/mapper/relations/link.go

@@ -77,7 +77,7 @@ func (m *relationsMapper) AfterRemoteOperation(ctx context.Context, changes *mod
 	return nil
 }
 
-// lintRelations finds the other side of the relation and create a corresponding relation on the other side.
+// linkRelations finds the other side of the relation and create a corresponding relation on the other side.
 func (m *relationsMapper) linkRelations(object model.ObjectWithRelations, allObjects model.Objects) error {
 	errs := errors.NewMultiError()
 	relations := object.GetRelations()

internal/pkg/mapper/relations/link_test.go

@@ -4,6 +4,7 @@ import (
 	"strings"
 	"testing"
 
+	"github.com/keboola/keboola-sdk-go/v2/pkg/keboola"
 	"github.com/stretchr/testify/assert"
 	"github.com/stretchr/testify/require"
 
@@ -66,6 +67,68 @@ func TestRelationsMapperLinkRelations(t *testing.T) {
 	}, object2.Local.Relations)
 }
 
+// TestRelationsMapperVariablesSharedAcrossConsumers verifies that when a variables config
+// is loaded before its consumers in changes.Loaded(), the two-pass approach still produces
+// exactly one warning instead of crashing with "multiple parents defined by relations".
+func TestRelationsMapperVariablesSharedAcrossConsumers(t *testing.T) {
+	t.Parallel()
+	state, d := createStateWithMapper(t)
+	logger := d.DebugLogger()
+
+	branchID := keboola.BranchID(1)
+	consumerCompID := keboola.ComponentID("ex-generic-v2")
+
+	// Variables config (Y) — added to state and loaded FIRST to exercise the ordering
+	// that previously caused a fatal "multiple parents" crash in PathsGenerator.
+	varsKey := model.ConfigKey{BranchID: branchID, ComponentID: keboola.VariablesComponentID, ID: "vars"}
+	varsConfig := &model.ConfigState{
+		ConfigManifest: &model.ConfigManifest{ConfigKey: varsKey},
+		Remote:         &model.Config{ConfigKey: varsKey},
+	}
+	require.NoError(t, state.Set(varsConfig))
+
+	// Consumer 1 — variablesFrom relation pointing to varsKey.
+	consumer1Key := model.ConfigKey{BranchID: branchID, ComponentID: consumerCompID, ID: "consumer1"}
+	consumer1 := &model.ConfigState{
+		ConfigManifest: &model.ConfigManifest{ConfigKey: consumer1Key},
+		Remote: &model.Config{
+			ConfigKey: consumer1Key,
+			Relations: model.Relations{
+				&model.VariablesFromRelation{VariablesID: varsKey.ID},
+			},
+		},
+	}
+	require.NoError(t, state.Set(consumer1))
+
+	// Consumer 2 — also variablesFrom relation pointing to the same varsKey.
+	consumer2Key := model.ConfigKey{BranchID: branchID, ComponentID: consumerCompID, ID: "consumer2"}
+	consumer2 := &model.ConfigState{
+		ConfigManifest: &model.ConfigManifest{ConfigKey: consumer2Key},
+		Remote: &model.Config{
+			ConfigKey: consumer2Key,
+			Relations: model.Relations{
+				&model.VariablesFromRelation{VariablesID: varsKey.ID},
+			},
+		},
+	}
+	require.NoError(t, state.Set(consumer2))
+
+	// Variables config is first in Loaded() — the ordering that previously caused the crash.
+	changes := model.NewRemoteChanges()
+	changes.AddLoaded(varsConfig)
+	changes.AddLoaded(consumer1)
+	changes.AddLoaded(consumer2)
+
+	// Must return nil — the duplicate is a warning, not a fatal error.
+	require.NoError(t, state.Mapper().AfterRemoteOperation(t.Context(), changes))
+
+	// Exactly one warning about the duplicate variablesFor relation.
+	// WarnAndErrorMessages() returns raw JSON; the formatter capitalises sentence starts.
+	msgs := logger.WarnAndErrorMessages()
+	assert.Equal(t, 1, strings.Count(msgs, "variablesFor"))
+	assert.Empty(t, logger.ErrorMessages())
+}
+
 func TestRelationsMapperOtherSideMissing(t *testing.T) {
 	t.Parallel()
 	state, d := createStateWithMapper(t)

internal/pkg/model/variables.go

@@ -178,12 +178,15 @@ func (t *VariablesValuesForRelation) NewOtherSideRelation(relationDefinedOn Obje
 		return nil, nil, errors.Errorf(`%s not found, referenced from %s, by relation "%s"`, variablesConfigKey.Desc(), relationDefinedOn.Desc(), t.Type())
 	}
 	variablesConfig := variablesConfigRaw.(*Config)
+	// When the variables config temporarily holds multiple variablesFor relations (shared
+	// across consumers), skip linking here — Pass 2 validation will detect and warn about
+	// the duplicates and remove them.
+	if len(variablesConfig.Relations.GetByType(VariablesForRelType)) > 1 {
+		return nil, nil, nil
+	}
 	variablesForRaw, err := variablesConfig.Relations.GetOneByType(VariablesForRelType)
 	if err != nil {
-		// Multiple variablesFor relations exist on the variables config (shared across consumers).
-		// Pass 2 validation will detect and warn about the duplicates; skip linking here to avoid
-		// a redundant error before the cleanup runs.
-		return nil, nil, nil //nolint:nilerr
+		return nil, nil, errors.PrefixErrorf(err, "invalid %s", variablesConfig.Desc())
 	}
 	if variablesForRaw == nil {
 		return nil, nil, errors.NewNestedError(