refactor: clarify Scope internals, replace index with depth

Author: benbellick

core/src/main/java/io/substrait/expression/LambdaBuilder.java

@@ -45,8 +45,7 @@ public Expression.Lambda lambda(List<Type> paramTypes, Function<Scope, Expressio
     Type.Struct params = Type.Struct.builder().nullable(false).addAllFields(paramTypes).build();
     pushLambdaContext(params);
     try {
-      int index = lambdaContext.size() - 1;
-      Scope scope = new Scope(index);
+      Scope scope = new Scope(params);
       Expression body = bodyFn.apply(scope);
       return ImmutableExpression.Lambda.builder().parameters(params).body(body).build();
     } finally {
@@ -83,14 +82,14 @@ public Expression.Lambda lambdaFromStruct(
    * @throws IllegalArgumentException if stepsOut exceeds the current nesting depth
    */
   public Type.Struct resolveParams(int stepsOut) {
-    int index = lambdaContext.size() - 1 - stepsOut;
-    if (index < 0 || index >= lambdaContext.size()) {
+    int targetDepth = lambdaContext.size() - stepsOut;
+    if (targetDepth <= 0 || targetDepth > lambdaContext.size()) {
       throw new IllegalArgumentException(
           String.format(
               "Lambda parameter reference with stepsOut=%d is invalid (current depth: %d)",
               stepsOut, lambdaContext.size()));
     }
-    return lambdaContext.get(index);
+    return lambdaContext.get(targetDepth - 1);
   }
 
   /**
@@ -115,24 +114,26 @@ private void popLambdaContext() {
    * parameter references.
    */
   public class Scope {
-    private final int index;
+    private final Type.Struct params;
+    private final int depth;
 
-    private Scope(int index) {
-      this.index = index;
+    private Scope(Type.Struct params) {
+      this.params = params;
+      this.depth = lambdaContext.size();
     }
 
     /**
      * Creates a validated reference to a parameter of this lambda. The correct {@code stepsOut}
-     * value is computed automatically.
+     * value is computed automatically as the difference between the current nesting depth and the
+     * depth at which this scope was created.
      *
      * @param paramIndex index of the parameter within this lambda's parameter struct
      * @return a {@link FieldReference} pointing to the specified parameter
      * @throws IndexOutOfBoundsException if paramIndex is out of bounds
      */
     public FieldReference ref(int paramIndex) {
-      int stepsOut = lambdaContext.size() - 1 - index;
-      return FieldReference.newLambdaParameterReference(
-          paramIndex, lambdaContext.get(index), stepsOut);
+      int stepsOut = lambdaContext.size() - depth;
+      return FieldReference.newLambdaParameterReference(paramIndex, params, stepsOut);
     }
   }
 }