com.wallstop-studios.dxmessaging 2.1.9 → 3.0.1

package/Editor/CustomEditors/MessageAwareComponentFallbackEditor.cs

@@ -0,0 +1,81 @@
+namespace DxMessaging.Editor.CustomEditors
+{
+#if UNITY_EDITOR
+    using DxMessaging.Unity;
+    using UnityEditor;
+
+    /// <summary>
+    /// Primary CustomEditor for every <see cref="MessageAwareComponent"/> subclass. Renders the
+    /// DxMessaging warning HelpBox above an inspector body that is byte-for-byte identical to
+    /// Unity's default <c>GenericInspector</c> (achieved via
+    /// <see cref="Editor.DrawDefaultInspector"/>).
+    /// </summary>
+    /// <remarks>
+    /// We register as a non-fallback (primary) editor with
+    /// <c>editorForChildClasses: true</c>. Several alternatives were tried and rejected:
+    ///
+    /// <list type="number">
+    /// <item>
+    /// <b><c>isFallback = true</c>:</b> Unity selects this editor only when no other matches.
+    /// In practice that meant Unity's <c>GenericInspector</c> handled every
+    /// <see cref="MessageAwareComponent"/> subclass and the warning HelpBox vanished entirely
+    /// (Unity 2021's <see cref="Editor.finishedDefaultHeaderGUI"/> hook did not reliably fire
+    /// for those types). This regressed the analyzer warning surface.
+    /// </item>
+    /// <item>
+    /// <b>Manual <see cref="SerializedObject"/> iteration that skips <c>m_Script</c>:</b> the
+    /// rationale was to avoid a "duplicate Script row," but Unity does NOT draw <c>m_Script</c>
+    /// in the component header -- <see cref="Editor.DrawDefaultInspector"/> draws the same
+    /// disabled "Script" row that <c>GenericInspector</c> draws. Skipping it produced a visible
+    /// vertical gap below the header for empty subclasses, because the row Unity reserves for
+    /// the script reference was left blank.
+    /// </item>
+    /// </list>
+    ///
+    /// <para>
+    /// The current design is the simple one: be the primary editor, prepend the overlay's
+    /// HelpBox via <see cref="MessageAwareComponentInspectorOverlay.RenderInsideOnInspectorGUI"/>,
+    /// then call <see cref="Editor.DrawDefaultInspector"/>. The body therefore matches
+    /// <c>GenericInspector</c> exactly: no missing Script row, no extra vertical gap. To avoid
+    /// double-rendering when the header hook ALSO fires for our editor instance (Unity 2022+),
+    /// <see cref="MessageAwareComponentInspectorOverlay"/> unconditionally skips the header path
+    /// for <see cref="MessageAwareComponentFallbackEditor"/> instances.
+    /// </para>
+    ///
+    /// <para>
+    /// We do NOT short-circuit <see cref="OnInspectorGUI"/> on event type. Unity invokes
+    /// editors twice per frame (Layout + Repaint), and both passes MUST emit identical control
+    /// counts, otherwise the inspector window's layout cache is corrupted and adjacent
+    /// components fail to render. See
+    /// <see cref="MessageAwareComponentInspectorOverlay.RenderInsideOnInspectorGUI"/> for the
+    /// matching invariant on the overlay side.
+    /// </para>
+    ///
+    /// <para>
+    /// User-defined custom editors for specific <see cref="MessageAwareComponent"/> subclasses
+    /// still win precedence: a <c>[CustomEditor(typeof(MySpecificSubclass))]</c> is more
+    /// specific than our <c>editorForChildClasses</c> registration, so Unity selects the user's
+    /// editor for that subclass. The header-hook overlay still surfaces the warning above the
+    /// user's editor in that case.
+    /// </para>
+    /// </remarks>
+    [CustomEditor(typeof(MessageAwareComponent), true)]
+    [CanEditMultipleObjects]
+    public sealed class MessageAwareComponentFallbackEditor : Editor
+    {
+        public override void OnInspectorGUI()
+        {
+            // Render the overlay BEFORE the default body so the warning appears prominently at
+            // the top of the inspector. The overlay's render body has identical Layout/Repaint
+            // control counts, so we can call it unconditionally here.
+            MessageAwareComponentInspectorOverlay.RenderInsideOnInspectorGUI(target);
+
+            // Match Unity's GenericInspector exactly; including the disabled "Script" row that
+            // every MonoBehaviour inspector shows. This is intentional: skipping the script row
+            // creates a visible empty gap below the header for subclasses with no
+            // [SerializeField] fields.
+            DrawDefaultInspector();
+        }
+    }
+#endif
+}

package/Editor/CustomEditors/MessageAwareComponentFallbackEditor.cs.meta

@@ -0,0 +1,11 @@
+fileFormatVersion: 2
+guid: 0d8deac538fe4f5da0a0cffe1a7ee670
+MonoImporter:
+  externalObjects: {}
+  serializedVersion: 2
+  defaultReferences: []
+  executionOrder: 0
+  icon: {instanceID: 0}
+  userData: 
+  assetBundleName: 
+  assetBundleVariant: 

package/Editor/CustomEditors/MessageAwareComponentInspectorOverlay.cs

@@ -0,0 +1,420 @@
+namespace DxMessaging.Editor.CustomEditors
+{
+#if UNITY_EDITOR
+    using System.Collections.Generic;
+    using System.Linq;
+    using DxMessaging.Editor.Analyzers;
+    using DxMessaging.Editor.Settings;
+    using DxMessaging.Unity;
+    using UnityEditor;
+    using UnityEditorInternal;
+    using UnityEngine;
+
+    /// <summary>
+    /// Header-injection overlay for every Inspector showing a <see cref="MessageAwareComponent"/> subclass.
+    /// </summary>
+    /// <remarks>
+    /// We hook <see cref="Editor.finishedDefaultHeaderGUI"/> rather than registering a
+    /// <c>[CustomEditor(typeof(MessageAwareComponent), editorForChildClasses: true)]</c> so we never
+    /// clobber a user's own custom editor. The overlay reads its data from
+    /// <see cref="DxMessagingConsoleHarvester"/> (which reflects directly into Unity's
+    /// <c>UnityEditor.LogEntries</c> console store) and from <see cref="DxMessagingSettings"/>
+    /// (project-wide ignore list and master toggle).
+    ///
+    /// <para>
+    /// <b>Layout/Repaint control-count invariant.</b> When the overlay renders from inside an
+    /// <see cref="Editor.OnInspectorGUI"/> body (the fallback CustomEditor path), Unity invokes
+    /// us TWICE per frame: once with <c>Event.current.type == EventType.Layout</c> (where every
+    /// <c>EditorGUILayout.*</c> call REGISTERS a control) and once with <c>EventType.Repaint</c>
+    /// (where the registered controls are drawn). The two passes MUST emit identical control
+    /// counts, otherwise Unity's layout cache for the entire inspector window is corrupted and
+    /// adjacent components fail to render. That is why we expose two entry points:
+    /// </para>
+    /// <list type="bullet">
+    /// <item>
+    /// <see cref="DrawHeader"/> (registered to <see cref="Editor.finishedDefaultHeaderGUI"/>) is
+    /// post-body and Unity has already settled layout for the inspector by the time it fires --
+    /// gating on <c>EventType.Repaint</c> there is safe.
+    /// </item>
+    /// <item>
+    /// <see cref="RenderInsideOnInspectorGUI"/> is called from inside an editor body and CANNOT
+    /// gate on event type. It must call the same <c>EditorGUILayout</c> sequence on both passes.
+    /// </item>
+    /// </list>
+    /// </remarks>
+    [InitializeOnLoad]
+    public static class MessageAwareComponentInspectorOverlay
+    {
+        // Per-Repaint latch keyed on instanceID for the header-hook entry point. We render once
+        // per Repaint event per target. EventType.Layout marks the start of a fresh GUI cycle, so
+        // we clear the set then; rendering happens on EventType.Repaint, which Unity guarantees
+        // fires once per visible inspector per frame.
+        //
+        // NOTE: cross-path dedupe between the header hook and the OnInspectorGUI hook is
+        // accomplished by an UNCONDITIONAL skip at the top of <see cref="DrawHeader"/> when the
+        // target editor is our fallback CustomEditor; see that method's comment. We do NOT use
+        // a per-frame "header drew" set, because such a set would necessarily be populated only
+        // on the Repaint pass of the header hook, while OnInspectorGUI runs on BOTH the Layout
+        // and Repaint passes; that asymmetry would corrupt the inspector's layout cache.
+        private static readonly HashSet<int> _renderedThisRepaint = new();
+
+        static MessageAwareComponentInspectorOverlay()
+        {
+            Editor.finishedDefaultHeaderGUI += DrawHeader;
+            DxMessagingConsoleHarvester.ReportUpdated += RepaintAllInspectors;
+        }
+
+        private static void RepaintAllInspectors()
+        {
+            try
+            {
+                // InternalEditorUtility.RepaintAllViews is the cheap path: it walks the
+                // existing GUIView list once. Resources.FindObjectsOfTypeAll<Editor>() allocates
+                // a fresh array of every Editor instance Unity has loaded, which is wasteful
+                // when we just want a redraw signal.
+                InternalEditorUtility.RepaintAllViews();
+            }
+            catch (System.Exception ex)
+            {
+                Debug.LogWarning(
+                    $"[DxMessaging] Failed to repaint inspectors after analyzer report update: {ex.Message}"
+                );
+            }
+        }
+
+        private static void DrawHeader(Editor editor)
+        {
+            if (editor == null)
+            {
+                return;
+            }
+            // If our own fallback CustomEditor is the editor instance, skip the header path
+            // entirely; the editor's OnInspectorGUI will call RenderInsideOnInspectorGUI and we
+            // would otherwise render twice. Unconditional skip (not gated on EventType) keeps
+            // control counts balanced on both Layout and Repaint passes.
+            if (editor is MessageAwareComponentFallbackEditor)
+            {
+                return;
+            }
+            RenderForHeaderHook(editor.target);
+        }
+
+        /// <summary>
+        /// Header-hook entry point. Fires after Unity's default header has been drawn, so the
+        /// inspector's layout pass for this editor has already completed. Safe to gate on
+        /// <see cref="EventType.Repaint"/> here -- we are not inside an OnInspectorGUI body.
+        /// </summary>
+        private static void RenderForHeaderHook(Object target)
+        {
+            if (target == null)
+            {
+                return;
+            }
+            if (target is not MessageAwareComponent messageAwareComponent)
+            {
+                return;
+            }
+
+            Event currentEvent = Event.current;
+            if (currentEvent == null)
+            {
+                return;
+            }
+            if (currentEvent.type == EventType.Layout)
+            {
+                // Start of a fresh GUI cycle; wipe the per-Repaint latch.
+                _renderedThisRepaint.Clear();
+                return;
+            }
+            if (currentEvent.type != EventType.Repaint)
+            {
+                return;
+            }
+            int instanceId = messageAwareComponent.GetInstanceID();
+            if (!_renderedThisRepaint.Add(instanceId))
+            {
+                return;
+            }
+
+            BuildAndRenderOverlay(messageAwareComponent);
+        }
+
+        /// <summary>
+        /// OnInspectorGUI entry point. Called from inside the fallback CustomEditor's
+        /// <see cref="Editor.OnInspectorGUI"/>, where Unity invokes the editor on BOTH the Layout
+        /// pass and the Repaint pass. This method MUST emit the same <c>EditorGUILayout</c> calls
+        /// on both passes, so it does NOT gate on <see cref="EventType"/> and does NOT latch.
+        /// Cross-path dedupe with the header-hook path is handled inside
+        /// <see cref="DrawHeader"/>, which unconditionally skips when the editor is our fallback.
+        /// </summary>
+        internal static void RenderInsideOnInspectorGUI(Object target)
+        {
+            if (target is not MessageAwareComponent messageAwareComponent)
+            {
+                return;
+            }
+            BuildAndRenderOverlay(messageAwareComponent);
+        }
+
+        /// <summary>
+        /// Rendering body shared by both entry points. Performs ALL gating decisions up-front
+        /// before any <c>EditorGUILayout.*</c> call, then runs straight-line layout calls. This
+        /// guarantees the function emits an identical sequence of layout calls on the Layout and
+        /// Repaint passes when invoked from within <see cref="Editor.OnInspectorGUI"/>.
+        /// </summary>
+        /// <returns>True if the HelpBox + buttons were drawn; false if we drew nothing.</returns>
+        private static bool BuildAndRenderOverlay(MessageAwareComponent messageAwareComponent)
+        {
+            // ---- Gating phase: every "should we draw?" decision happens here, before any
+            // EditorGUILayout call. The result is a single bool: shouldRender. ----
+
+            // Mid-compile / mid-import is the worst time to dereference the settings asset:
+            // AssetDatabase may be in a transitional state. Bail and let the next OnGUI redraw
+            // pick up where we left off.
+            if (EditorApplication.isCompiling || EditorApplication.isUpdating)
+            {
+                return false;
+            }
+
+            DxMessagingSettings settings;
+            try
+            {
+                settings = DxMessagingSettings.GetOrCreateSettings();
+            }
+            catch (System.Exception ex)
+            {
+                Debug.LogWarning(
+                    $"[DxMessaging] Inspector overlay could not load settings: {ex.Message}"
+                );
+                return false;
+            }
+
+            if (settings == null || !settings._baseCallCheckEnabled)
+            {
+                return false;
+            }
+
+            // S6: System.Type.FullName renders nested types as `Outer+Nested`, but the analyzer's
+            // `containingType.ToDisplayString()` (which produces the FQN we key the snapshot by)
+            // renders them as `Outer.Nested`. Without this normalization the lookup misses for
+            // every nested MessageAwareComponent subclass and the HelpBox never shows.
+            System.Type targetType = messageAwareComponent.GetType();
+            string fullName = (targetType.FullName ?? string.Empty).Replace('+', '.');
+            if (string.IsNullOrEmpty(fullName))
+            {
+                return false;
+            }
+
+            // Decide which of the three render shapes (if any) to draw.
+            // 0 = render nothing; 1 = harvester-unavailable info; 2 = ignored-type info; 3 = warning.
+            int shape = 0;
+            BaseCallReportEntry entry = null;
+            bool isIgnored = false;
+
+            if (!DxMessagingConsoleHarvester.IsAvailable)
+            {
+                shape = 1;
+            }
+            else
+            {
+                isIgnored =
+                    settings._baseCallIgnoredTypes != null
+                    && settings._baseCallIgnoredTypes.Any(e =>
+                        string.Equals(e, fullName, System.StringComparison.Ordinal)
+                    );
+                if (isIgnored)
+                {
+                    shape = 2;
+                }
+                else if (
+                    DxMessagingConsoleHarvester.TryGetEntry(fullName, out entry)
+                    && entry != null
+                    && entry.missingBaseFor != null
+                    && entry.missingBaseFor.Count > 0
+                )
+                {
+                    shape = 3;
+                }
+            }
+
+            if (shape == 0)
+            {
+                // "Render nothing" branch: emit ZERO EditorGUILayout calls. This must hold on
+                // both Layout and Repaint passes when called from OnInspectorGUI, so Unity's
+                // layout cache stays consistent.
+                return false;
+            }
+
+            // ---- Render phase: straight-line EditorGUILayout calls, identical sequence on
+            // every pass. Wrapped in a vertical group so any internal mismatch we missed cannot
+            // propagate to sibling inspectors. ----
+            EditorGUILayout.BeginVertical();
+            try
+            {
+                switch (shape)
+                {
+                    case 1:
+                        EditorGUILayout.HelpBox(
+                            "DxMessaging inspector overlay is disabled on this Unity version. "
+                                + "Check the console for DXMSG006/007/009 warnings instead.",
+                            MessageType.Info
+                        );
+                        break;
+                    case 2:
+                        DrawIgnoredBox(messageAwareComponent, settings, fullName);
+                        break;
+                    case 3:
+                        DrawWarningBox(messageAwareComponent, settings, fullName, entry);
+                        break;
+                }
+            }
+            finally
+            {
+                EditorGUILayout.EndVertical();
+            }
+
+            return true;
+        }
+
+        private static void DrawWarningBox(
+            MessageAwareComponent component,
+            DxMessagingSettings settings,
+            string fullName,
+            BaseCallReportEntry entry
+        )
+        {
+            string missingMethods = string.Join(", ", entry.missingBaseFor);
+            // Per-method consequence lines mirror the analyzer's DXMSG006 message text. Reading
+            // the dictionary on BaseCallTypeScannerCore keeps the overlay copy in lockstep with
+            // the analyzer; both are updated together when a new guarded method is added.
+            System.Text.StringBuilder consequenceBuilder = new();
+            foreach (string missingMethod in entry.missingBaseFor)
+            {
+                consequenceBuilder.Append("\n- ");
+                consequenceBuilder.Append(
+                    BaseCallTypeScannerCore.GetMissingBaseConsequenceLine(missingMethod, fullName)
+                );
+            }
+            string consequenceLines = consequenceBuilder.ToString();
+
+            // Cached-vs-fresh suffix is appended to the SAME HelpBox string rather than emitted
+            // as a sibling control, which keeps the Layout and Repaint passes emitting an
+            // identical sequence of EditorGUILayout.* calls regardless of harvester freshness.
+            // The suffix only appears when the harvester is showing entries loaded eagerly from
+            // `Library/DxMessaging/baseCallReport.json` and the first post-reload scan has not
+            // yet completed; once the scan flips IsFreshThisSession to true and RepaintAllInspectors
+            // fires, the overlay redraws without the suffix.
+            string freshnessSuffix = DxMessagingConsoleHarvester.IsFreshThisSession
+                ? string.Empty
+                : "\n(cached from previous session; refreshing...)";
+            string message =
+                $"{fullName} has lifecycle methods that don't chain to MessageAwareComponent ({missingMethods}); DxMessaging will not function on this component."
+                + consequenceLines
+                + "\nSee docs/reference/analyzers.md."
+                + freshnessSuffix;
+
+            EditorGUILayout.HelpBox(message, MessageType.Warning);
+            using (new EditorGUILayout.HorizontalScope())
+            {
+                if (GUILayout.Button("Open Script"))
+                {
+                    OpenScriptForComponent(component, entry);
+                }
+                if (GUILayout.Button("Ignore this type"))
+                {
+                    TryAddIgnoredType(settings, fullName);
+                }
+            }
+        }
+
+        private static void DrawIgnoredBox(
+            MessageAwareComponent component,
+            DxMessagingSettings settings,
+            string fullName
+        )
+        {
+            EditorGUILayout.HelpBox(
+                $"{fullName} is excluded from the DxMessaging base-call check.",
+                MessageType.Info
+            );
+            using (new EditorGUILayout.HorizontalScope())
+            {
+                if (GUILayout.Button("Stop ignoring"))
+                {
+                    TryRemoveIgnoredType(settings, fullName);
+                }
+            }
+        }
+
+        private static void OpenScriptForComponent(
+            MessageAwareComponent component,
+            BaseCallReportEntry entry
+        )
+        {
+            try
+            {
+                MonoScript monoScript = MonoScript.FromMonoBehaviour(component);
+                if (monoScript == null)
+                {
+                    return;
+                }
+                if (entry != null && entry.line > 0)
+                {
+                    AssetDatabase.OpenAsset(monoScript, entry.line);
+                }
+                else
+                {
+                    AssetDatabase.OpenAsset(monoScript);
+                }
+            }
+            catch (System.Exception ex)
+            {
+                Debug.LogWarning($"[DxMessaging] Failed to open script: {ex.Message}");
+            }
+        }
+
+        private static void TryAddIgnoredType(DxMessagingSettings settings, string fullName)
+        {
+            // Defer the mutation to AFTER the current frame's Layout/Repaint pair completes.
+            // Mutating settings._baseCallIgnoredTypes synchronously inside a button handler
+            // would flip the overlay's shape between Layout and Repaint passes of the SAME
+            // frame, corrupting Unity's per-window layout cache. delayCall fires AFTER the
+            // current GUI cycle, so the next frame's Layout pass sees the new state and
+            // both passes emit consistent control counts.
+            EditorApplication.delayCall += () =>
+            {
+                try
+                {
+                    settings.AddIgnoredType(fullName);
+                }
+                catch (System.Exception ex)
+                {
+                    Debug.LogWarning(
+                        $"[DxMessaging] Failed to add ignored type '{fullName}': {ex.Message}"
+                    );
+                }
+            };
+        }
+
+        private static void TryRemoveIgnoredType(DxMessagingSettings settings, string fullName)
+        {
+            // Same reasoning as TryAddIgnoredType: defer mutation past the current GUI cycle so
+            // the overlay's shape gating remains identical on Layout and Repaint passes of THIS
+            // frame. The next frame's Layout pass observes the new state; both passes agree.
+            EditorApplication.delayCall += () =>
+            {
+                try
+                {
+                    settings.RemoveIgnoredType(fullName);
+                }
+                catch (System.Exception ex)
+                {
+                    Debug.LogWarning(
+                        $"[DxMessaging] Failed to remove ignored type '{fullName}': {ex.Message}"
+                    );
+                }
+            };
+        }
+    }
+#endif
+}

package/Editor/CustomEditors/MessageAwareComponentInspectorOverlay.cs.meta

@@ -0,0 +1,11 @@
+fileFormatVersion: 2
+guid: b2e06a6b39994b51bc06b0131c49428e
+MonoImporter:
+  externalObjects: {}
+  serializedVersion: 2
+  defaultReferences: []
+  executionOrder: 0
+  icon: {instanceID: 0}
+  userData: 
+  assetBundleName: 
+  assetBundleVariant: 

package/Editor/CustomEditors/MessagingComponentEditor.cs

@@ -8,7 +8,7 @@ namespace DxMessaging.Editor.CustomEditors
     using Core.MessageBus;
     using Core.Messages;
     using DxMessaging.Editor.Testing;
-    using Unity;
+    using DxMessaging.Unity;
     using UnityEditor;
     using UnityEngine;
     using Object = UnityEngine.Object;

package/Editor/CustomEditors/MessagingComponentEditor.cs.meta

@@ -1,3 +1,3 @@
-fileFormatVersion: 2
-guid: e078b310572343318b79a3c00d0f274d
+fileFormatVersion: 2
+guid: e078b310572343318b79a3c00d0f274d
 timeCreated: 1749666380

package/Editor/CustomEditors.meta

@@ -1,3 +1,3 @@
-fileFormatVersion: 2
-guid: 652cab55c8444567a5101966444e9071
+fileFormatVersion: 2
+guid: 652cab55c8444567a5101966444e9071
 timeCreated: 1749666371

package/Editor/DxMessagingEditorInitializer.cs

@@ -26,7 +26,7 @@ namespace DxMessaging.Editor
         {
             if (
                 stateChange == PlayModeStateChange.EnteredEditMode
-                || stateChange == PlayModeStateChange.EnteredPlayMode
+                || stateChange == PlayModeStateChange.ExitingEditMode
             )
             {
                 ApplyEditorSettings();

package/Editor/DxMessagingEditorInitializer.cs.meta

@@ -1,3 +1,3 @@
-fileFormatVersion: 2
-guid: b5eeb11bcc9d4d70861d5dc7084daae5
+fileFormatVersion: 2
+guid: b5eeb11bcc9d4d70861d5dc7084daae5
 timeCreated: 1749668189

package/Editor/DxMessagingMenu.cs.meta

@@ -1,11 +1,11 @@
-fileFormatVersion: 2
-guid: 517da34a8f694371b843ba34f89077d3
-MonoImporter:
-  externalObjects: {}
-  serializedVersion: 2
-  defaultReferences: []
-  executionOrder: 0
-  icon: {instanceID: 0}
-  userData: 
-  assetBundleName: 
-  assetBundleVariant: 
+fileFormatVersion: 2
+guid: 517da34a8f694371b843ba34f89077d3
+MonoImporter:
+  externalObjects: {}
+  serializedVersion: 2
+  defaultReferences: []
+  executionOrder: 0
+  icon: {instanceID: 0}
+  userData: 
+  assetBundleName: 
+  assetBundleVariant: 

package/Editor/DxMessagingSceneBuildProcessor.cs.meta

@@ -1,11 +1,11 @@
-fileFormatVersion: 2
-guid: ec8789213f7f4c30a9353e90fb4345c8
-MonoImporter:
-  externalObjects: {}
-  serializedVersion: 2
-  defaultReferences: []
-  executionOrder: 0
-  icon: {instanceID: 0}
-  userData: 
-  assetBundleName: 
-  assetBundleVariant: 
+fileFormatVersion: 2
+guid: ec8789213f7f4c30a9353e90fb4345c8
+MonoImporter:
+  externalObjects: {}
+  serializedVersion: 2
+  defaultReferences: []
+  executionOrder: 0
+  icon: {instanceID: 0}
+  userData: 
+  assetBundleName: 
+  assetBundleVariant: