fix: correct expression hierarchy, cycle detection, and AST capture (#6)

Author: deer

codemodel-foundation/src/main/java/build/codemodel/foundation/usage/WildcardTypeUsage.java

@@ -33,6 +33,7 @@
 import build.codemodel.foundation.naming.TypeName;
 
 import java.lang.invoke.MethodHandles;
+import java.util.Objects;
 import java.util.Optional;
 import java.util.stream.Stream;
 
@@ -135,7 +136,7 @@ public boolean equals(final Object object) {
 
     @Override
     public int hashCode() {
-        return java.util.Objects.hash(lowerBound(), upperBound());
+        return Objects.hash(lowerBound(), upperBound());
     }
 
     /**

codemodel-foundation/src/test/java/build/codemodel/foundation/usage/GenericTypeUsageTests.java

@@ -10,6 +10,7 @@
 import org.junit.jupiter.api.BeforeEach;
 import org.junit.jupiter.api.Test;
 
+import java.util.List;
 import java.util.Optional;
 import java.util.Spliterator;
 
@@ -68,7 +69,7 @@ void shouldCompareSameTypes() {
     void shouldNotBeEqualWhenParametersAreDifferent() {
         final var codeModel = new ConceptualCodeModel(this.naming);
 
-        final var listTypeName = this.naming.getTypeName(java.util.List.class);
+        final var listTypeName = this.naming.getTypeName(List.class);
         final var stringTypeName = this.naming.getTypeName(String.class);
         final var integerTypeName = this.naming.getTypeName(Integer.class);
 
@@ -88,7 +89,7 @@ void shouldNotBeEqualWhenParametersAreDifferent() {
     void shouldBeEqualWhenBothHaveNoParameters() {
         final var codeModel = new ConceptualCodeModel(this.naming);
 
-        final var listTypeName = this.naming.getTypeName(java.util.List.class);
+        final var listTypeName = this.naming.getTypeName(List.class);
 
         final var rawList1 = GenericTypeUsage.of(codeModel, listTypeName);
         final var rawList2 = GenericTypeUsage.of(codeModel, listTypeName);

dependency-injection/src/test/java/build/codemodel/injection/DefaultOptionResolverTests.java

@@ -6,6 +6,9 @@
 import jakarta.inject.Inject;
 import org.junit.jupiter.api.Test;
 
+import java.util.Optional;
+import java.util.stream.Stream;
+
 import static org.assertj.core.api.Assertions.assertThat;
 
 /**
@@ -74,7 +77,7 @@ void shouldReturnEmptyWhenNoDefaultAnnotationPresent() {
         final var resolver = DefaultOptionResolver.of(framework);
 
         final var typeUsage = framework.codeModel().getTypeUsage(OptionWithNoDefault.class);
-        final var dependency = IndependentDependency.of(typeUsage, _ -> java.util.stream.Stream.empty());
+        final var dependency = IndependentDependency.of(typeUsage, _ -> Stream.empty());
 
         assertThat(resolver.resolve(dependency)).isEmpty();
     }
@@ -89,7 +92,7 @@ void shouldNotResolveNonOptionTypes() {
         // add a fallback for String so creation doesn't fail
         final var context = framework.newContext(
             DefaultOptionResolver.of(framework),
-            dep -> java.util.Optional.of(new ValueBinding<Object>() {
+            dep -> Optional.of(new ValueBinding<Object>() {
                 @Override public Object value() { return "fallback"; }
                 @Override public Dependency dependency() { return dep; }
             }));

dependency-injection/src/test/java/build/codemodel/injection/ProvidesResolverTests.java

@@ -4,6 +4,7 @@
 import org.junit.jupiter.api.Test;
 
 import java.util.Optional;
+import java.util.stream.Stream;
 
 import static org.assertj.core.api.Assertions.assertThat;
 
@@ -57,7 +58,7 @@ void shouldReturnEmptyWhenNoProvidesMethodMatchesDependency() {
         // EmptyProvider has no @Provides for String
         final var dependency = IndependentDependency.of(
             framework.codeModel().getTypeUsage(String.class),
-            _ -> java.util.stream.Stream.empty());
+            _ -> Stream.empty());
 
         final Optional<?> result = resolver.resolve(dependency);
         assertThat(result).isEmpty();
@@ -77,7 +78,7 @@ void shouldIgnoreVoidProvidesMethod() {
         // nothing should be registered, so any dependency comes back empty
         final var dependency = IndependentDependency.of(
             framework.codeModel().getTypeUsage(String.class),
-            _ -> java.util.stream.Stream.empty());
+            _ -> Stream.empty());
 
         assertThat(resolver.resolve(dependency)).isEmpty();
     }

expression-codemodel/src/main/java/build/codemodel/expression/BinaryArithmeticExpression.java

@@ -27,7 +27,7 @@
  * @since Sep-2024
  */
 public interface BinaryArithmeticExpression
-    extends LogicalExpression {
+    extends ArithmeticExpression {
 
     /**
      * Obtains the left-hand-side of the {@link Expression} for the <i>Arithmetic Operand</i>.

expression-codemodel/src/main/java/build/codemodel/expression/UnaryArithmeticExpression.java

@@ -27,7 +27,7 @@
  * @since Sep-2024
  */
 public interface UnaryArithmeticExpression
-    extends LogicalExpression {
+    extends ArithmeticExpression {
 
     /**
      * Obtains the {@link Expression} for the <i>ArithmeticOperand</i>.

expression-codemodel/src/test/java/build/codemodel/expression/ExpressionHierarchyTests.java

@@ -0,0 +1,60 @@
+package build.codemodel.expression;
+
+/*-
+ * #%L
+ * Expression Code Model
+ * %%
+ * Copyright (C) 2026 Workday, Inc.
+ * %%
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ * #L%
+ */
+
+import build.codemodel.foundation.ConceptualCodeModel;
+import build.codemodel.foundation.naming.NonCachingNameProvider;
+import org.junit.jupiter.api.Test;
+
+import static org.junit.jupiter.api.Assertions.assertFalse;
+import static org.junit.jupiter.api.Assertions.assertInstanceOf;
+
+/**
+ * Tests for the {@link Expression} type hierarchy.
+ *
+ * @author reed.vonredwitz
+ * @since Apr-2026
+ */
+class ExpressionHierarchyTests {
+
+    @Test
+    void unaryArithmeticExpressionShouldBeArithmeticNotLogical() {
+        final var codeModel = new ConceptualCodeModel(new NonCachingNameProvider());
+        final var operand = NumericLiteral.of(codeModel, 1);
+        final var negative = Negative.of(operand);
+
+        assertInstanceOf(UnaryArithmeticExpression.class, negative);
+        assertInstanceOf(ArithmeticExpression.class, negative);
+        assertFalse(negative instanceof LogicalExpression, "UnaryArithmeticExpression must not be a LogicalExpression");
+    }
+
+    @Test
+    void binaryArithmeticExpressionShouldBeArithmeticNotLogical() {
+        final var codeModel = new ConceptualCodeModel(new NonCachingNameProvider());
+        final var left = NumericLiteral.of(codeModel, 1);
+        final var right = NumericLiteral.of(codeModel, 2);
+        final var addition = Addition.of(left, right);
+
+        assertInstanceOf(BinaryArithmeticExpression.class, addition);
+        assertInstanceOf(ArithmeticExpression.class, addition);
+        assertFalse(addition instanceof LogicalExpression, "BinaryArithmeticExpression must not be a LogicalExpression");
+    }
+}

hierarchical-codemodel/src/main/java/build/codemodel/hierarchical/descriptor/HierarchicalTypeDescriptor.java

@@ -26,8 +26,10 @@
 import build.codemodel.foundation.usage.NamedTypeUsage;
 import build.codemodel.hierarchical.HierarchicalCodeModel;
 
+import java.util.HashSet;
 import java.util.LinkedHashSet;
 import java.util.Optional;
+import java.util.Set;
 import java.util.function.Predicate;
 import java.util.stream.Collectors;
 import java.util.stream.Stream;
@@ -129,11 +131,22 @@ default <T> Stream<T> parents(final Class<T> typeDescriptorClass) {
      * @return the level of the {@link HierarchicalTypeDescriptor}
      */
     default int level() {
-        return parents()
-            .map(HierarchicalTypeDescriptor::level)
-            .max(Integer::compareTo)
-            .map(level -> level + 1)
-            .orElse(0);
+        return level(new HashSet<>());
+    }
+
+    private int level(final Set<TypeName> visited) {
+        if (!visited.add(typeName())) {
+            throw new IllegalStateException("Cycle detected in type hierarchy at: " + typeName());
+        }
+        try {
+            return parents()
+                .map(p -> p.level(visited))
+                .max(Integer::compareTo)
+                .map(level -> level + 1)
+                .orElse(0);
+        } finally {
+            visited.remove(typeName());
+        }
     }
 
     /**
@@ -200,26 +213,37 @@ default <T> Stream<T> ancestors(final Class<T> typeDescriptorClass) {
      * @return the {@link Optional}ly found <i>first</i> <i>ancestor</i>, otherwise {@link Optional#empty()}
      */
     default Optional<HierarchicalTypeDescriptor> getAncestor(final Predicate<? super HierarchicalTypeDescriptor> predicate) {
+        return getAncestor(predicate, new HashSet<>());
+    }
 
+    private Optional<HierarchicalTypeDescriptor> getAncestor(final Predicate<? super HierarchicalTypeDescriptor> predicate,
+                                                             final Set<TypeName> visited) {
         if (!hasParents()) {
             return Optional.empty();
         }
 
-        // first attempt to locate a parent that satisfies the Predicate
-        final var optional = parents()
-            .filter(predicate)
-            .findFirst();
-
-        if (optional.isPresent()) {
-            return optional;
+        if (!visited.add(typeName())) {
+            throw new IllegalStateException("Cycle detected in type hierarchy at: " + typeName());
+        }
+        try {
+            // first attempt to locate a parent that satisfies the Predicate
+            final var optional = parents()
+                .filter(predicate)
+                .findFirst();
+
+            if (optional.isPresent()) {
+                return optional;
+            }
+
+            // now attempt to locate a parent of the parent that satisfies the Predicate
+            return parents()
+                .map(parent -> parent.getAncestor(predicate, visited))
+                .filter(Optional::isPresent)
+                .map(Optional::orElseThrow)
+                .findFirst();
+        } finally {
+            visited.remove(typeName());
         }
-
-        // now attempt to locate a parent of the parent that satisfies the Predicate
-        return parents()
-            .map(parent -> parent.getAncestor(predicate))
-            .filter(Optional::isPresent)
-            .map(Optional::orElseThrow)
-            .findFirst();
     }
 
     /**

hierarchical-codemodel/src/test/java/build/codemodel/hierarchical/HierarchicalCodeModelTests.java

@@ -17,6 +17,7 @@
 import java.util.stream.Stream;
 
 import static org.assertj.core.api.Assertions.assertThat;
+import static org.assertj.core.api.Assertions.assertThatThrownBy;
 
 /**
  * Tests for {@link HierarchicalCodeModel}s.
@@ -696,4 +697,57 @@ private void assertIsOnlyAssignableTo(final HierarchicalCodeModel codeModel,
                     () -> "Type: " + fromEncodedTypeName + " is assignable to type: " + toTypeName)
                 .isFalse());
     }
+
+    /**
+     * Ensure that {@link HierarchicalTypeDescriptor#level()} throws {@link IllegalStateException}
+     * when a cycle exists in the type hierarchy instead of causing a {@link StackOverflowError}.
+     */
+    @Test
+    void levelShouldThrowOnCyclicHierarchy() {
+        final var codeModel = createEmptyCodeModel();
+        final var nameProvider = codeModel.getNameProvider();
+
+        final var nameA = nameProvider.getTypeName("CycleA");
+        final var nameB = nameProvider.getTypeName("CycleB");
+
+        final var usageA = SpecificTypeUsage.of(codeModel, nameA);
+        final var usageB = SpecificTypeUsage.of(codeModel, nameB);
+
+        final var descriptorA = codeModel.createTypeDescriptor(nameA, (_, n) -> new ClassTypeDescriptor(codeModel, n));
+        final var descriptorB = codeModel.createTypeDescriptor(nameB, (_, n) -> new ClassTypeDescriptor(codeModel, n));
+
+        // A extends B and B extends A — a direct cycle
+        descriptorA.addTrait(Extends.of(usageB));
+        descriptorB.addTrait(Extends.of(usageA));
+
+        assertThatThrownBy(descriptorA::level)
+            .isInstanceOf(IllegalStateException.class)
+            .hasMessageContaining("Cycle");
+    }
+
+    /**
+     * Ensure that {@link HierarchicalTypeDescriptor#getAncestor} throws {@link IllegalStateException}
+     * when a cycle exists in the type hierarchy instead of causing a {@link StackOverflowError}.
+     */
+    @Test
+    void getAncestorShouldThrowOnCyclicHierarchy() {
+        final var codeModel = createEmptyCodeModel();
+        final var nameProvider = codeModel.getNameProvider();
+
+        final var nameA = nameProvider.getTypeName("AncCycleA");
+        final var nameB = nameProvider.getTypeName("AncCycleB");
+
+        final var usageA = SpecificTypeUsage.of(codeModel, nameA);
+        final var usageB = SpecificTypeUsage.of(codeModel, nameB);
+
+        final var descriptorA = codeModel.createTypeDescriptor(nameA, (_, n) -> new ClassTypeDescriptor(codeModel, n));
+        final var descriptorB = codeModel.createTypeDescriptor(nameB, (_, n) -> new ClassTypeDescriptor(codeModel, n));
+
+        descriptorA.addTrait(Extends.of(usageB));
+        descriptorB.addTrait(Extends.of(usageA));
+
+        assertThatThrownBy(() -> descriptorA.getAncestor(_ -> false))
+            .isInstanceOf(IllegalStateException.class)
+            .hasMessageContaining("Cycle");
+    }
 }

jdk-codemodel/src/main/java/build/codemodel/jdk/JDKCodeModel.java

@@ -250,10 +250,19 @@ else if (type instanceof TypeVariable<?> typeVariable) {
             typeUsage = TypeVariableUsage.of(this, typeName, Optional.empty(), upperBound);
         }
         else if (type instanceof WildcardType wildcardType) {
+            final java.lang.reflect.Type[] lowers = wildcardType.getLowerBounds();
+            final java.lang.reflect.Type[] uppers = wildcardType.getUpperBounds();
 
-            // TODO: determine lower and upper bounds from the WildcardType?
+            final Optional<Lazy<TypeUsage>> optLower = lowers.length > 0
+                ? Optional.of(Lazy.of(getTypeUsage(lowers[0])))
+                : Optional.empty();
 
-            typeUsage = WildcardTypeUsage.create(this);
+            // getUpperBounds() returns [Object] for unbounded `?` — treat that as no explicit upper bound
+            final Optional<Lazy<TypeUsage>> optUpper = uppers.length > 0 && !uppers[0].equals(Object.class)
+                ? Optional.of(Lazy.of(getTypeUsage(uppers[0])))
+                : Optional.empty();
+
+            typeUsage = WildcardTypeUsage.of(this, optLower, optUpper);
         }
         else if (type instanceof GenericArrayType genericArrayType) {
             typeUsage = ArrayTypeUsage.of(