feat(dependency-injection): startup validation, eager singleton initialization (#32)

Author: deer

dependency-injection/pom.xml

@@ -34,6 +34,12 @@
             <version>${base.version}</version>
         </dependency>
 
+        <dependency>
+            <groupId>build.base</groupId>
+            <artifactId>base-graph</artifactId>
+            <version>${base.version}</version>
+        </dependency>
+
         <dependency>
             <groupId>build.codemodel</groupId>
             <artifactId>codemodel-foundation</artifactId>

dependency-injection/src/main/java/build/codemodel/injection/Context.java

@@ -111,6 +111,37 @@ <T> T create(TypeUsage typeUsage)
     <T> T create(Dependency dependency)
         throws InjectionException;
 
+    /**
+     * Validates the current set of registered bindings before any objects are created. Performs three checks:
+     * <ol>
+     *   <li><strong>Cycle detection</strong> — throws {@link CyclicDependencyException} with the full cycle
+     *       path if a dependency cycle is found among class bindings.</li>
+     *   <li><strong>Unsatisfied dependency detection</strong> — collects every class binding whose injected
+     *       dependencies have no corresponding binding and throws {@link ValidationException} listing them
+     *       all at once.</li>
+     *   <li><strong>Scope violation detection</strong> — flags edges where a wider-scoped binding (e.g.
+     *       {@link jakarta.inject.Singleton}) depends on a narrower-scoped one (e.g. prototype).</li>
+     * </ol>
+     *
+     * @return this {@link Context} for fluent chaining (e.g. {@code context.validate().initializeEagerSingletons()})
+     * @throws CyclicDependencyException if a dependency cycle is detected
+     * @throws ValidationException       if unsatisfied dependencies or scope violations are found
+     */
+    Context validate();
+
+    /**
+     * Pre-creates all {@link jakarta.inject.Singleton}-scoped class bindings in dependency order, using
+     * {@link build.base.graph.Graphs#parallelizableGroups} to initialize independent groups in parallel.
+     *
+     * <p>Typically called immediately after {@link #validate()}:
+     * <pre>{@code
+     * context.validate().initializeEagerSingletons();
+     * }</pre>
+     *
+     * @return this {@link Context} for fluent chaining
+     */
+    Context initializeEagerSingletons();
+
     /**
      * Creates a new {@link Context} with the this {@link Context} as a parent solver.
      *

dependency-injection/src/main/java/build/codemodel/injection/CyclicDependencyException.java

@@ -9,9 +9,9 @@
  * 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.
@@ -20,12 +20,16 @@
  * #L%
  */
 
+import java.util.List;
+import java.util.stream.Collectors;
+
 /**
  * Thrown when a cyclic dependency has been detected between {@link Class}es.
  *
  * @author brian.oliver
  * @since Jun-2018
  */
+@SuppressWarnings("java:S2166")
 public class CyclicDependencyException
     extends InjectionException {
 
@@ -39,6 +43,11 @@ public class CyclicDependencyException
      */
     private final Dependency causedByDependency;
 
+    /**
+     * The full cycle path produced by static graph analysis, or {@code null} when detected at runtime.
+     */
+    private final List<Dependency> cyclePath;
+
     /**
      * Constructs a {@link CyclicDependencyException} based on a {@link Dependency} that has a {@link Dependency} on
      * itself.
@@ -58,14 +67,35 @@ public CyclicDependencyException(final Dependency dependency) {
     public CyclicDependencyException(final Dependency detectedInDependency, final Dependency causedByDependency) {
         this.detectedInDependency = detectedInDependency;
         this.causedByDependency = causedByDependency;
+        this.cyclePath = null;
+    }
+
+    /**
+     * Constructs a {@link CyclicDependencyException} with the full cycle path discovered by static graph
+     * analysis (e.g. from {@link Context#validate()}). The path starts and ends with the same
+     * {@link Dependency} (e.g. {@code [A, B, C, A]}).
+     *
+     * @param cyclePath the full cycle path including the repeated start/end node
+     */
+    public CyclicDependencyException(final List<Dependency> cyclePath) {
+        this.cyclePath = List.copyOf(cyclePath);
+        // for backwards-compat fields: use first/last unique nodes in path
+        this.detectedInDependency = cyclePath.isEmpty() ? null : cyclePath.getFirst();
+        this.causedByDependency = cyclePath.size() > 1 ? cyclePath.get(cyclePath.size() - 2) : this.detectedInDependency;
     }
 
     @Override
     public String getMessage() {
+        if (this.cyclePath != null) {
+            return "Cyclic dependency detected: "
+                + this.cyclePath.stream()
+                .map(Object::toString)
+                .collect(Collectors.joining(" \u2192 "));
+        }
         return "Detected a Cyclic Dependency. " + this.detectedInDependency + " defines a "
             + (this.detectedInDependency == this.causedByDependency
             ? "dependency on itself."
             : "(transitive) dependency on " + this.causedByDependency + ", which defines a dependency on "
-                + this.detectedInDependency);
+            + this.detectedInDependency);
     }
 }

dependency-injection/src/main/java/build/codemodel/injection/InjectionContext.java

@@ -21,6 +21,8 @@
  */
 
 import build.base.foundation.Lazy;
+import build.base.graph.Graph;
+import build.base.graph.Graphs;
 import build.codemodel.foundation.usage.GenericTypeUsage;
 import build.codemodel.foundation.usage.NamedTypeUsage;
 import build.codemodel.foundation.usage.TypeUsage;
@@ -422,6 +424,122 @@ public <T> T create(final Dependency dependency)
             .orElseThrow(() -> new UnsatisfiedDependencyException(dependency));
     }
 
+    @Override
+    public Context validate() {
+        // Build a directed dependency graph over all ClassBindings.
+        // Edge: binding.dependency() → each of its injected dependencies.
+        final var graphBuilder = Graph.<Dependency>directed();
+
+        this.bindingsByDependency.values().stream()
+            .filter(ClassBinding.class::isInstance)
+            .map(b -> (ClassBinding<?>) b)
+            .forEach(classBinding -> {
+                final var bindingDep = classBinding.dependency();
+                graphBuilder.addVertex(bindingDep);
+                this.injectionFramework.getInjectableDescriptor(classBinding.concreteClass())
+                    .injectionPoints()
+                    .flatMap(InjectionPoint::dependencies)
+                    .forEach(dep -> graphBuilder.addEdge(bindingDep, dep));
+            });
+
+        final var graph = graphBuilder.build();
+
+        // 1. Cycle detection
+        Graphs.findCycle(graph)
+            .ifPresent(cycle -> {
+                throw new CyclicDependencyException(cycle);
+            });
+
+        // 2. Unsatisfied dependency and 3. Scope violation detection
+        final var problems = new ArrayList<String>();
+
+        graph.edges().forEach(edge -> {
+            final var dep = edge.to();
+
+            // Unsatisfied: no explicit binding and not auto-resolvable
+            if (!isResolvable(dep)) {
+                problems.add("Unsatisfied dependency: [" + dep + "]"
+                    + " required by [" + edge.from() + "]");
+            }
+
+            // Scope violation: @Singleton depends on NonSingletonClassBinding (prototype)
+            final var fromBinding = this.bindingsByDependency.get(edge.from());
+            final var toBinding = this.bindingsByDependency.get(dep);
+            if (fromBinding instanceof LazySingletonClassBinding
+                && toBinding instanceof NonSingletonClassBinding) {
+                problems.add("Scope violation: singleton [" + edge.from()
+                    + "] depends on prototype-scoped [" + dep + "]");
+            }
+        });
+
+        if (!problems.isEmpty()) {
+            throw new ValidationException(problems);
+        }
+
+        return this;
+    }
+
+    /**
+     * Returns {@code true} if the given {@link Dependency} can be satisfied — either by an explicit or
+     * multibinding already registered, or by an auto-bindable {@link jakarta.inject.Singleton} class.
+     */
+    private boolean isResolvable(final Dependency dependency) {
+        if (resolver().resolve(dependency).isPresent()) {
+            return true;
+        }
+        // auto-singleton: a @Singleton class that can be bound on-demand
+        if (dependency.typeUsage() instanceof NamedTypeUsage namedTypeUsage) {
+            try {
+                final var clazz = Class.forName(namedTypeUsage.typeName().canonicalName());
+                return this.injectionFramework.codeModel()
+                    .getJDKTypeDescriptor(clazz)
+                    .map(this.injectionFramework::isSingleton)
+                    .orElse(false);
+            } catch (final ClassNotFoundException ignored) {
+                return false;
+            }
+        }
+        return false;
+    }
+
+    @Override
+    @SuppressWarnings("unchecked")
+    public Context initializeEagerSingletons() {
+        // Collect all explicitly-bound singleton class bindings
+        final var singletonBindings = this.bindingsByDependency.values().stream()
+            .filter(LazySingletonClassBinding.class::isInstance)
+            .map(b -> (LazySingletonClassBinding<Object>) b)
+            .collect(Collectors.toList());
+
+        if (singletonBindings.isEmpty()) {
+            return this;
+        }
+
+        // Build a dependency graph limited to singleton vertices so we can find initialization order
+        final var singletonDeps = singletonBindings.stream()
+            .map(Binding::dependency)
+            .collect(Collectors.toSet());
+
+        final var graphBuilder = Graph.<Dependency>directed();
+        singletonBindings.forEach(b -> {
+            final var bindingDep = b.dependency();
+            graphBuilder.addVertex(bindingDep);
+            this.injectionFramework.getInjectableDescriptor(b.concreteClass())
+                .injectionPoints()
+                .flatMap(InjectionPoint::dependencies)
+                .filter(singletonDeps::contains)
+                .forEach(dep -> graphBuilder.addEdge(bindingDep, dep));
+        });
+
+        final var graph = graphBuilder.build();
+
+        // Initialize each parallelizable layer; within a layer, initialize concurrently
+        Graphs.parallelizableGroups(graph).forEach(layer ->
+            layer.parallelStream().forEach(dep -> create(dep)));
+
+        return this;
+    }
+
     @Override
     public Context newContext() {
         return this.injectionFramework.newContext(this.resolver());

dependency-injection/src/main/java/build/codemodel/injection/ValidationException.java

@@ -0,0 +1,68 @@
+package build.codemodel.injection;
+
+/*-
+ * #%L
+ * Dependency Injection
+ * %%
+ * 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 java.util.List;
+import java.util.stream.Collectors;
+
+/**
+ * Thrown by {@link Context#validate()} when one or more validation problems are found. Unlike exceptions
+ * thrown during injection, this collects <em>all</em> detected problems and reports them together so the
+ * caller can fix multiple issues in a single iteration.
+ *
+ * @author reed.vonredwitz
+ * @see Context#validate()
+ * @since Apr-2026
+ */
+public class ValidationException
+    extends InjectionException {
+
+    /**
+     * The list of human-readable problem descriptions detected during validation.
+     */
+    private final List<String> problems;
+
+    /**
+     * Constructs a {@link ValidationException} with the specified list of problems.
+     *
+     * @param problems the list of problem descriptions; must not be empty
+     */
+    public ValidationException(final List<String> problems) {
+        this.problems = List.copyOf(problems);
+    }
+
+    /**
+     * Returns the list of problems detected during validation.
+     *
+     * @return an unmodifiable list of problem descriptions
+     */
+    public List<String> problems() {
+        return this.problems;
+    }
+
+    @Override
+    public String getMessage() {
+        return "Validation failed with " + this.problems.size() + " problem(s):\n"
+            + this.problems.stream()
+            .map(p -> "  - " + p)
+            .collect(Collectors.joining("\n"));
+    }
+}

dependency-injection/src/main/java/module-info.java

@@ -32,6 +32,7 @@
     requires transitive build.base.transport;
     requires transitive build.base.telemetry;
     requires build.base.configuration;
+    requires build.base.graph;
 
     requires transitive build.codemodel.foundation;
     requires build.codemodel.expression;