feat(module): report unattributable types from ReflectionUtil, throttled

The three ReflectionUtil sites were left alone in the previous commit because a null module is a documented, usually-legitimate outcome there — every non-module class loaded by the app classloader takes that branch, so reporting each one would drown the log in a path that runs per type, per serialization.

But a module class that fails attribution lands in exactly the same branch and silently loses its module qualifier, which is the failure this whole effort started from. Saying nothing is the wrong trade too.

So: report, throttled. ModuleAttribution.reportUnattributedOnce names at most 20 distinct classes, says so when it stops, and resets after 60s of quiet. Same shape as the discarded-write throttle in WorldProviderCoreImpl.

The throttle is documented as temporary scaffolding rather than furniture — it exists to make an invisible problem visible without making it unbearable, and should go once the underlying failures are fixed. Its state is static, which is a real wart: a long test run building many engines could have one engine's reports suppressed by another's. The 60s reset bounds that.

A single audit at environment switch would be better than all of this — walk the indexed classes once and report the whole set as it becomes true, instead of scattered surprises later, with no throttle needed by construction. Proposed rather than built, since it is a design change rather than a review follow-up.

Verified no reports fire during a healthy engine startup (ExampleTest), so this is a fault signal rather than background noise.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_019pXw6g6JWNGP6eAyDJ1Cf8

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

Author: Cervator

engine/src/main/java/org/terasology/engine/core/module/ModuleAttribution.java

@@ -3,21 +3,78 @@
 
 package org.terasology.engine.core.module;
 
+import org.slf4j.Logger;
 import org.terasology.gestalt.module.ModuleEnvironment;
 import org.terasology.gestalt.naming.Name;
 
 import java.util.ArrayList;
 import java.util.List;
+import java.util.Set;
+import java.util.concurrent.ConcurrentHashMap;
+import java.util.concurrent.atomic.AtomicBoolean;
 
 /**
  * Helpers for reporting when a {@link ModuleEnvironment} cannot say which module a class came from.
  */
 public final class ModuleAttribution {
 
+    /** How many distinct classes {@link #reportUnattributedOnce} names before it falls quiet. */
+    private static final int DISTINCT_CLASS_REPORT_LIMIT = 20;
+
+    /**
+     * How long the throttle stays quiet before reporting afresh.
+     * <p>
+     * Long enough that one startup's worth of failures counts as a single burst, short enough that
+     * a later unrelated one is still heard.
+     */
+    private static final long REPORT_RESET_MS = 60_000;
+
+    private static final Set<String> reportedClasses = ConcurrentHashMap.newKeySet();
+    private static final AtomicBoolean limitAnnounced = new AtomicBoolean();
+    private static volatile long lastReportMs;
+
     private ModuleAttribution() {
         // static utility class, no instance needed
     }
 
+    /**
+     * Report a class the environment cannot attribute, at most once per class and not many times.
+     * <p>
+     * For callers on paths hot enough that reporting every occurrence would drown the log - type
+     * handling runs this per type, per serialization - or where a null is usually legitimate and
+     * only occasionally a real fault. Names at most {@value #DISTINCT_CLASS_REPORT_LIMIT} distinct
+     * classes, says so when it stops, and starts over after {@value #REPORT_RESET_MS}ms of quiet.
+     * <p>
+     * The throttle is deliberately crude, and deliberately static: it exists to make a
+     * currently-invisible problem visible without making it unbearable, and should go away once
+     * the underlying attribution failures are fixed rather than becoming permanent furniture.
+     *
+     * @param logger the caller's logger, so the message is attributed to where it happened
+     * @param what a short description of what could not be done, e.g. "build a type URI"
+     * @param type the class that could not be attributed
+     * @param environment the environment that was asked
+     */
+    public static void reportUnattributedOnce(Logger logger, String what, Class<?> type, ModuleEnvironment environment) {
+        long now = System.currentTimeMillis();
+        if (now - lastReportMs > REPORT_RESET_MS) {
+            reportedClasses.clear();
+            limitAnnounced.set(false);
+        }
+        lastReportMs = now;
+
+        if (!reportedClasses.add(type.getName())) {
+            return;
+        }
+        if (reportedClasses.size() > DISTINCT_CLASS_REPORT_LIMIT) {
+            if (limitAnnounced.compareAndSet(false, true)) {
+                logger.warn("More than {} classes could not be attributed to a module. Further reports are"
+                        + " suppressed until this stops happening.", DISTINCT_CLASS_REPORT_LIMIT);
+            }
+            return;
+        }
+        logger.warn("Could not {} - no module provides {}", what, describeUnattributedClass(type, environment));
+    }
+
     /**
      * Describe a class the environment turned up but cannot attribute to any of its modules.
      * <p>

engine/src/main/java/org/terasology/engine/utilities/ReflectionUtil.java

@@ -7,7 +7,10 @@
 import com.google.common.collect.Lists;
 import com.google.common.collect.Sets;
 import org.reflections.ReflectionUtils;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
 import org.terasology.engine.core.SimpleUri;
+import org.terasology.engine.core.module.ModuleAttribution;
 import org.terasology.gestalt.module.ModuleEnvironment;
 import org.terasology.gestalt.naming.Name;
 import org.terasology.nui.UIWidget;
@@ -35,6 +38,8 @@
 
 
 public final class ReflectionUtil {
+    private static final Logger logger = LoggerFactory.getLogger(ReflectionUtil.class);
+
     private ReflectionUtil() {
     }
 
@@ -653,6 +658,10 @@ public static String getTypeUri(Type type, ModuleEnvironment moduleEnvironment)
         Name moduleProvidingType = moduleEnvironment.getModuleProviding(getRawType(type));
 
         if (moduleProvidingType == null) {
+            // Usually legitimate - plenty of non-module classes reach here - but a module class
+            // that fails attribution lands in the same branch and silently loses its module
+            // qualifier, so the URI stops matching. Throttled because this runs per type.
+            ModuleAttribution.reportUnattributedOnce(logger, "build a type URI", getRawType(type), moduleEnvironment);
             return typeSimpleName;
         }
 
@@ -674,6 +683,7 @@ public static SimpleUri getSimpleUriFor(Type type, ModuleEnvironment environment
         Name moduleProviding = environment.getModuleProviding(clazz);
 
         if (moduleProviding == null) {
+            ModuleAttribution.reportUnattributedOnce(logger, "build a simple URI", clazz, environment);
             return null;
         }
 
@@ -695,6 +705,7 @@ public static SimpleUri getFullyQualifiedSimpleUriFor(Type type, ModuleEnvironme
         Name moduleProviding = environment.getModuleProviding(clazz);
 
         if (moduleProviding == null) {
+            ModuleAttribution.reportUnattributedOnce(logger, "build a fully qualified URI", clazz, environment);
             return null;
         }