com.wallstop-studios.dxmessaging 2.2.0 → 3.0.1

package/CHANGELOG.md

@@ -1,67 +1,106 @@
-# Changelog
-
-All notable changes to this project will be documented in this file.
-
-The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
-and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
-
-## [Unreleased]
-
-## [2.2.0]
-
-### Fixed
-
-- Fixed a bug where no messages would get received by any listeners due to specifics in Unity play mode timings
-
-## [2.1.8]
-
-### Fixed
-
-- Added npmignore for proper npm publishing (incorrectly packaging some items)
-
-## [2.1.7]
-
-### Changed
-
-- Improved README with prominent Mental Model section
-- Added Mermaid diagrams and decision flowchart for choosing message types
-- Added Common Mistakes callout with troubleshooting link
-- Updated performance comparison table with accurate benchmark range (10-17M ops/sec)
-
-### Fixed
-
-- Regenerated corrupted meta files in `scripts/wiki`
-
-## [2.1.6]
-
-### Added
-
-- Concepts index page and Mental Model documentation for understanding DxMessaging's design principles
-
-### Fixed
-
-- Orphaned documentation pages in Concepts section now included in mkdocs.yml navigation
-- Burst compiler assembly resolution errors when using DxMessaging as a package on disk and building for player platforms. Benchmarks and integration test assembly definitions now specify Editor-only platform to prevent Burst from attempting to resolve these assemblies during player builds.
-
-## [2.1.5]
-
-### Added
-
-- GitHub Pages documentation deployment with MkDocs Material theme
-- Wiki synchronization workflow that automatically syncs documentation to GitHub Wiki
-- Documentation validation workflow that runs on pull requests and pushes
-- MkDocs build validation in pre-push hooks
-- Searchable documentation site at <https://wallstop.github.io/DxMessaging/>
-- Theme-aware Mermaid diagrams with automatic light/dark mode switching for GitHub Pages
-- User-visible error messages when Mermaid diagrams fail to render
-
-### Changed
-
-- Updated `documentationUrl` in package.json to point to GitHub Pages site
-- Enhanced README.md with links to documentation site, wiki, and changelog
-- Mermaid diagrams now use neutral theme fallback for GitHub/VSCode markdown preview compatibility
-
-### Fixed
-
-- Comprehensive syntax highlighting for C# code blocks in documentation with distinct colors for keywords, types, functions, strings, numbers, comments, namespaces, and attributes
-- WCAG AA accessibility compliance for code syntax highlighting in both light and dark themes
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [3.0.1]
+
+### Added
+
+- New Roslyn base-call analyzer (`MessageAwareComponentBaseCallAnalyzer`) that flags `MessageAwareComponent` subclasses whose lifecycle overrides forget to invoke `base.Awake()`, `base.OnEnable()`, `base.OnDisable()`, `base.OnDestroy()`, or `base.RegisterMessageHandlers()`. Introduces diagnostics `DXMSG006` (missing base call), `DXMSG007` (lifecycle method hidden with `new`), `DXMSG008` (opt-out marker), `DXMSG009` (method implicitly hides a lifecycle method without `override`/`new`), and `DXMSG010` (`base.{method}()` chains into an override that does not reach `MessageAwareComponent`). DXMSG006's diagnostic message is now per-method: each guarded method emits a sentence describing the runtime consequence (registration token never created, handlers not re-enabled, memory leak, etc.) so users immediately see what breaks. The inspector overlay HelpBox renders the same per-method sentences. Severity is tunable per project via `.editorconfig` (e.g. `dotnet_diagnostic.DXMSG006.severity = error`). Ships as a separate `WallstopStudios.DxMessaging.Analyzer.dll` deployed alongside the existing source-generator DLL by `SetupCscRsp` so it loads under both Unity 2021's Roslyn 3.8 analyzer host and newer Unity versions. Diagnostic help links now open the current analyzer reference page in the DxMessaging repository.
+- Runtime self-check breadcrumb on `MessageAwareComponent`: `OnEnable` now logs a one-time `Debug.LogError` per instance when the registration token is null, with a link to the DXMSG006 reference. Gated on `UNITY_EDITOR || DEBUG`, so release builds pay no cost. Catches the case where the analyzer DLL was disabled or did not run, surfacing the silent failure as a loud editor error instead.
+- New public `[DxIgnoreMissingBaseCall]` attribute (`DxMessaging.Core.Attributes`) for source-level opt-out of the base-call analyzer. Applied to a class, every guarded lifecycle method on that class is exempt; applied to a single method, only that method is exempt. The analyzer still emits an Info-level `DXMSG008` at the suppression site so opt-outs remain auditable, and the inspector overlay's snapshot honours the same scoping (method-level suppresses only the annotated method, type-level opts out the entire type). Not inherited -- derived classes must opt out explicitly.
+- New inspector overlay (`MessageAwareComponentInspectorOverlay`) for every `MessageAwareComponent` subclass: missing-base-call warnings reported by the analyzer or harvested from the Unity console are surfaced as a HelpBox in the inspector header without clobbering user-defined `[CustomEditor]`s (the overlay hooks `Editor.finishedDefaultHeaderGUI`). The overlay restores the previous session's report immediately on Unity Editor startup (loaded from `Library/DxMessaging/baseCallReport.json`) instead of waiting for the first post-reload scan to complete; the HelpBox is annotated `(cached from previous session -- refreshing...)` until the first scan refreshes it. A companion fallback editor (`MessageAwareComponentFallbackEditor`) hosts the overlay for subclasses with no other custom editor and renders the body via `DrawDefaultInspector()` so subclasses with no serialized fields no longer leave an empty vertical gap below the inspector header.
+- New DxMessaging project-wide settings asset (`DxMessagingSettings`, stored at `Assets/Editor/DxMessagingSettings.asset`) accessible from Unity's Project Settings. Controls diagnostics targets applied to `IMessageBus.GlobalDiagnosticsTargets`, the editor message buffer size, the domain-reload warning suppression, the base-call analyzer toggle, the project-wide base-call ignore list, and the optional Unity console bridge that feeds the inspector overlay.
+- New `docs/reference/analyzers.md` reference page documenting every `DXMSG###` diagnostic the package emits, with severity, source generator/analyzer, trigger conditions, message text, and code samples for each. Added to the Reference section of the documentation site navigation.
+- Added `llms.txt` plus README onboarding guidance so users can connect AI assistants with accurate DxMessaging package context.
+- Test-suite hardening: parameterized scenario fixture (`MessageScenario`, `MessageScenarios`, `ScenarioHarness`, `AllocationAssertions`) under `Tests/Runtime/TestUtilities/` enabling kind-parameterized tests.
+- Behavioural gap closures: `HandlerExceptionTests`, `ReentrantEmissionTests`, `NullAndInvalidInputTests`, `SingleThreadContractTests` pinning exception-in-handler, re-entrancy, null-input, and threading contracts.
+- `AllocationMatrixTests` covering zero-GC dispatch across kinds, interceptors, post-processors, diagnostics, and priority-based dispatch.
+- Expanded coverage now pins source-generator and analyzer behaviour that users rely on: generic / record struct / nested partial / nullable annotation cases for `DxMessageIdGenerator`; `[DxOptionalParameter]` permutations and DXMSG005 boundary cases for `DxAutoConstructorGenerator`; positive opt-out cases for `DxIgnoreMissingBaseCallAttribute`. No runtime API change.
+- Three new public read-only registration counters on `IMessageBus`: `RegisteredInterceptors`, `RegisteredPostProcessors`, and `RegisteredGlobalAcceptAll`. Lets diagnostic and leak-check tooling distinguish interceptor / post-processor / global accept-all leaks from regular handler leaks, and lets external monitors aggregate the bus's registration footprint without reflecting on internals. `MessageBus` aggregates the counters on each read by walking the per-message-type caches; consumers polling these properties in tight loops should snapshot at region boundaries.
+- Runtime memory-reclamation foundations: `DxMessagingRuntimeSettings` loads from `Resources/DxMessagingRuntimeSettings` and hot-reloads eviction cadence, enablement, trim opt-out, and pool-cap changes without recreating the bus. Pooled internal collections and typed/bus slot registries preserve existing dispatch APIs while making empty handler and interceptor slots reclaimable. `IMessageBus.Trim(force)` and `MessageHandler.TrimAll(force)` reset dirty empty slots and trim shared pools on demand, `OccupiedTypeSlots` / `OccupiedTargetSlots` expose the retained bus and dirty typed-handler slot footprint for diagnostics, and idle sweeps run from emits and Unity's PlayerLoop. New user-facing reference and tuning docs ship at `docs/reference/runtime-settings.md` (per-setting reference table) and `docs/guides/memory-reclamation.md` (forced trim, idle sweep, and pool tuning narrative).
+- New explicit-factory registration helpers across all three DI integrations: `VContainerRegistrationExtensions.RegisterDxMessagingBus`, `ReflexRegistrationExtensions.AddDxMessagingBus`, and `ZenjectRegistrationExtensions.BindDxMessagingBus`. Each helper exposes the bus under both the concrete `MessageBus` contract and the `IMessageBus` interface, accepts an overloadable lifetime where the container supports it, accepts a user-supplied `Func<TResolver, MessageBus>` factory, and accepts an `IDxMessagingClock` overload that constructs the bus through the new internal-only `MessageBus.CreateForInternalUse` factory so test-side clocks (for example `FakeClock`) can be injected through the container. The VContainer helper registers both contracts in one registration call, avoiding VContainer environments where chained `.AsSelf().As<IMessageBus>()` drops the concrete contract and fails with `No such registration of type: DxMessaging.Core.MessageBus.MessageBus`; the DI samples either call the helper directly or document the corresponding helper preference for their container shape.
+
+### Changed
+
+- Mutation tests now exercise every messaging kind (Untargeted/Targeted/Broadcast) via a single parameterized fixture (`[ValueSource(MessageScenarios.AllKinds)]`) across `MutationDuringEmissionTests`, `MutationInterceptorTests`, and `MutationDestructionTests`. Users get tighter cross-kind parity guarantees; no runtime API change. (~720 lines of duplication removed; test count preserved.)
+- Renamed `UntargetedTests`, `TargetedTests`, `BroadcastTests` to `EmitUntargetedSpecificTests`, `EmitTargetedSpecificTests`, `EmitBroadcastSpecificTests` to clarify that kind-common tests live in `EmitTests` and kind-specific tests live in the renamed files. (Test-suite hardening is test-only; no `Runtime/` behavior was modified.)
+- Documentation now warns up front that `MessageAwareComponent` subclasses must call `base.Awake()`, `base.OnEnable()`, `base.OnDisable()`, `base.OnDestroy()`, and `base.RegisterMessageHandlers()` from any override; admonitions added to the Quick Start, Getting Started Guide, Visual Guide, README, FAQ, and Troubleshooting pages all link to [`DXMSG006`](docs/reference/analyzers.md#dxmsg006-missing-base-call) (issue #195).
+
+### Fixed
+
+- Cross-priority deregistration during in-flight emit no longer drops handlers from the current dispatch.
+  - Previously, when a handler at one priority removed a handler at a later priority of the same emission, the later priority's typed-handler stack was rebuilt from the now-mutated registry on first touch and the scheduled-for-removal handler was silently skipped, breaking the documented "frozen handler list per emission" contract.
+  - This affected sourced-broadcast, broadcast-without-source, and targeted-without-targeting dispatch (the targeted/untargeted paths already pre-froze every bucket up-front).
+  - The bus now pre-freezes every priority bucket's typed-handler caches up-front for every dispatch surface (sourced-broadcast, broadcast-without-source, targeted-without-targeting) and uses the per-emission snapshot count for the dispatch-loop early-out.
+  - The sourced-broadcast and broadcast-without-source dispatch loops also no longer short-circuit on the live `cache.handlers.Count == 0` when the per-emission snapshot still holds the deregistered handler.
+  - Post-processor prefreeze no longer takes a single-bucket/single-entry fast-path that skipped pre-freezing per-MessageHandler post-processor caches; a regular handler that registers a new post-processor on the same MessageHandler+priority during its own callback now sees the new post-processor on the next emission, not the in-flight one.
+  - The same fix extends to cross-`MessageHandler` post-processor dispatch: the inner per-handler `RunFastHandlers` overload used by `TargetedWithoutTargeting`/`BroadcastWithoutSource` post-processors now consults the per-emission snapshot list directly instead of bailing on the live `cache.entries` count, so a sibling `MessageHandler` removing a not-yet-dispatched post-processor no longer silently skips the snapshot-pinned invocation.
+  - `RegisterGlobalAcceptAll` (`HandleGlobalUntargeted`/`HandleGlobalTargeted`/`HandleGlobalBroadcast`) is intentionally NOT covered by this fix. The bus's global accept-all dispatch path prefreezes lazily per-entry inside the dispatch loop, so a sibling `MessageHandler` that removes another's global registration mid-emit causes the removed handler to be skipped on the in-flight emission. The behavior is pinned by `MutationPostProcessorAcrossHandlersTests.RemoveOtherGlobalAcceptAllAcrossHandlersDuringDispatch`; if a future change introduces upfront global-handler prefreeze, that test must be updated to expect the snapshot semantics that the per-kind paths already provide.
+- `DxMessagingStaticState.Reset` is now race-safe against deferred deregistrations. Previously, when a message-aware component was destroyed but its disable callback had not yet run (Unity defers Object.Destroy to end of frame) and Reset ran in between, the deferred token teardown would log spurious "Received over-deregistration of {type} for {handler}" errors against the user's Unity console. The bus now stamps each captured deregister closure with a generation counter and silently no-ops closures captured before a Reset. Applied uniformly across every register entry point (untargeted, targeted, broadcast, GlobalAcceptAll, and all three interceptor kinds). The same race-safety guarantee is now propagated to user-installed custom global buses via `MessageBus.BumpResetGeneration()`, which `DxMessagingStaticState.Reset` invokes on the active global bus when it differs from the built-in default; the custom bus's sinks are intentionally left intact to avoid clobbering state the user installed it to preserve. User code is unaffected except that previously-spurious error logs disappear.
+- `MessageRegistrationToken.RemoveRegistration(handle)` no longer leaks the staged registration entry, so a `Disable()`/`Enable()` cycle after `RemoveRegistration` no longer silently re-registers the removed handler. The fix also drops the matching metadata and call-count entries so diagnostic mode does not accumulate stale handles.
+- Resolved [issue #204](https://github.com/wallstop/DxMessaging/issues/204) (build artifacts and orphaned `.meta` files leaking into the npm tarball) and prevented its regression: `scripts/validate-npm-meta.js` now runs `validateNoBuildArtifactsInTarball` (rejects `bin/`, `obj/`, `*.pdb`, `*.tmp`, `*.csproj.user`, `.vs/`, `.idea/`, `*.suo`, and `*.DotSettings.user` paths in the tarball) and `validatePublishedFilesArePairedWithMetas` (every shipped Unity-relevant file has its `.meta` neighbour and every shipped directory has its directory `.meta`), wired into `prepack` and the `validate-npm-meta` workflow so the next publish cannot reintroduce the regression.
+
+## [2.2.0]
+
+### Fixed
+
+- Fixed a bug where no messages would get received by any listeners due to specifics in Unity play mode timings
+
+## [2.1.8]
+
+### Fixed
+
+- Added npmignore for proper npm publishing (incorrectly packaging some items)
+
+## [2.1.7]
+
+### Changed
+
+- Improved README with prominent Mental Model section
+- Added Mermaid diagrams and decision flowchart for choosing message types
+- Added Common Mistakes callout with troubleshooting link
+- Updated performance comparison table with accurate benchmark range (10-17M ops/sec)
+
+### Fixed
+
+- Regenerated corrupted meta files in `scripts/wiki`
+
+## [2.1.6]
+
+### Added
+
+- Concepts index page and Mental Model documentation for understanding DxMessaging's design principles
+
+### Fixed
+
+- Orphaned documentation pages in Concepts section now included in mkdocs.yml navigation
+- Burst compiler assembly resolution errors when using DxMessaging as a package on disk and building for player platforms. Benchmarks and integration test assembly definitions now specify Editor-only platform to prevent Burst from attempting to resolve these assemblies during player builds.
+
+## [2.1.5]
+
+### Added
+
+- GitHub Pages documentation deployment with MkDocs Material theme
+- Wiki synchronization workflow that automatically syncs documentation to GitHub Wiki
+- Documentation validation workflow that runs on pull requests and pushes
+- MkDocs build validation in pre-push hooks
+- Searchable documentation site at <https://wallstop.github.io/DxMessaging/>
+- Theme-aware Mermaid diagrams with automatic light/dark mode switching for GitHub Pages
+- User-visible error messages when Mermaid diagrams fail to render
+
+### Changed
+
+- Updated `documentationUrl` in package.json to point to GitHub Pages site
+- Enhanced README.md with links to documentation site, wiki, and changelog
+- Mermaid diagrams now use neutral theme fallback for GitHub/VSCode markdown preview compatibility
+
+### Fixed
+
+- Comprehensive syntax highlighting for C# code blocks in documentation with distinct colors for keywords, types, functions, strings, numbers, comments, namespaces, and attributes
+- WCAG AA accessibility compliance for code syntax highlighting in both light and dark themes

package/CHANGELOG.md.meta

@@ -1,7 +1,7 @@
-fileFormatVersion: 2
-guid: 341323775e849a648922d928083dda86
-TextScriptImporter:
-  externalObjects: {}
-  userData: 
-  assetBundleName: 
-  assetBundleVariant: 
+fileFormatVersion: 2
+guid: 341323775e849a648922d928083dda86
+TextScriptImporter:
+  externalObjects: {}
+  userData: 
+  assetBundleName: 
+  assetBundleVariant: 

package/Editor/Analyzers/BaseCallIlInspector.cs

@@ -0,0 +1,277 @@
+// The Unity Editor assembly that hosts this file does not enable nullable annotations; the
+// dotnet-test project that compiles a linked copy DOES (`<Nullable>enable</Nullable>`). Pin the
+// nullable state per-file so behavior is identical in both compilation contexts.
+#nullable disable
+namespace DxMessaging.Editor.Analyzers
+{
+    using System;
+    using System.Reflection;
+    using System.Reflection.Emit;
+
+    /// <summary>
+    /// Pure (Unity-API-free) IL inspector that decides whether a given <see cref="MethodInfo"/>'s
+    /// IL body invokes a parent's same-named method (i.e. the IL emit shape of <c>base.X()</c>).
+    /// Extracted from <c>BaseCallTypeScanner</c> so the dotnet-test project can cover the byte
+    /// walker without depending on Unity APIs.
+    /// </summary>
+    /// <remarks>
+    /// <para>
+    /// <b>Why does this exist?</b> The console-scrape harvester is non-deterministic across Unity
+    /// 2021 cache hits (Unity skips routing analyzer warnings to <c>LogEntries</c> /
+    /// <c>CompilerMessage[]</c> on incremental compiles where Bee/csc reused a cached output).
+    /// IL reflection over the loaded assemblies in the AppDomain is deterministic -- the bytes do
+    /// not depend on Unity's compile-pipeline state. <see cref="BaseCallTypeScanner"/> uses this
+    /// helper to classify every loaded <c>MessageAwareComponent</c> subclass on every domain
+    /// reload.
+    /// </para>
+    /// <para>
+    /// <b>Proper OpCodes-table walker.</b> The walker decodes every CIL instruction by looking up
+    /// its <see cref="OpCode"/> in the static tables built from <see cref="OpCodes"/> reflection
+    /// (single-byte and two-byte 0xFE-prefix forms) and steps the operand-size that the opcode
+    /// declares (<see cref="OpCode.OperandType"/>). Misalignment past multi-byte-operand opcodes
+    /// (<c>switch</c> jump tables, <c>ldstr</c> 4-byte tokens, 8-byte literal constants, etc.) is
+    /// therefore impossible -- the walker either consumes every byte correctly or stops at the
+    /// first unrecognised opcode. Phantom DXMSG006 from a misread <c>0x28</c> inside a wider
+    /// operand is no longer a failure mode.
+    /// </para>
+    /// <para>
+    /// <b>Defensive bias.</b> When we cannot reason at all (null method, empty name, inaccessible
+    /// IL body, <c>GetMethodBody()</c> returns null on abstract / P/Invoke / IL2CPP-stripped
+    /// targets, or any reflection exception), the inspector returns <c>true</c>
+    /// ("assume clean -- calls base") so the scanner never invents a phantom warning. The
+    /// compile-time analyzer is the authoritative source for CI builds (DXMSG006/007/009/010 via
+    /// full Roslyn semantic-model precision); the IL scanner exists only to make the editor
+    /// overlay light up at edit-time, where a missed warning is far worse than a phantom one.
+    /// </para>
+    /// </remarks>
+    public static class BaseCallIlInspector
+    {
+        // CIL opcode tables, indexed by the low byte of OpCode.Value. Built once by reflecting over
+        // System.Reflection.Emit.OpCodes; every public static OpCode field there represents a
+        // canonical CIL instruction. The two-byte form of the table is used when a 0xFE prefix is
+        // observed in the IL stream; otherwise we use the single-byte form. Because CIL specifies
+        // exactly two prefix bytes (single-byte = direct, two-byte = 0xFE prefix), this division
+        // covers every defined opcode.
+        private static readonly OpCode[] s_singleByteOps = BuildOpCodeTable(twoByte: false);
+        private static readonly OpCode[] s_twoByteOps = BuildOpCodeTable(twoByte: true);
+
+        private static OpCode[] BuildOpCodeTable(bool twoByte)
+        {
+            OpCode[] table = new OpCode[256];
+            foreach (
+                FieldInfo field in typeof(OpCodes).GetFields(
+                    BindingFlags.Public | BindingFlags.Static
+                )
+            )
+            {
+                if (field.GetValue(null) is not OpCode op)
+                {
+                    continue;
+                }
+                ushort value = (ushort)op.Value;
+                bool isTwoByte = (value & 0xFF00) == 0xFE00;
+                bool isSingleByte = (value & 0xFF00) == 0;
+                if (twoByte && isTwoByte)
+                {
+                    table[value & 0xFF] = op;
+                }
+                else if (!twoByte && isSingleByte)
+                {
+                    table[value & 0xFF] = op;
+                }
+            }
+            return table;
+        }
+
+        /// <summary>
+        /// Returns <c>true</c> if <paramref name="method"/>'s IL body contains a
+        /// <c>call</c>/<c>callvirt</c> to a parent type's same-named method. Defensive:
+        /// returns <c>true</c> (assume-clean) if the IL body is null/inaccessible to avoid
+        /// false-positive warnings on platforms or methods where reflection on bodies is
+        /// restricted (abstract methods, P/Invoke, IL2CPP-stripped bodies, etc.).
+        /// </summary>
+        /// <param name="method">The override on the descendant type whose IL we wish to inspect.</param>
+        /// <param name="methodName">The expected base method name (e.g. <c>"OnEnable"</c>).</param>
+        /// <returns>
+        /// <c>true</c> if the IL contains a base-call shape, OR the IL was inaccessible (safe
+        /// default -- assume clean). <c>false</c> only when IL was readable AND no call/callvirt
+        /// targeting a parent same-named method was found.
+        /// </returns>
+        public static bool MethodIlContainsBaseCall(MethodInfo method, string methodName)
+        {
+            if (method == null || string.IsNullOrEmpty(methodName))
+            {
+                // Defensive: treat as clean when we don't have enough information to reason. This
+                // ensures the scanner never emits a phantom warning on a degenerate input.
+                return true;
+            }
+
+            try
+            {
+                MethodBody body = method.GetMethodBody();
+                if (body == null)
+                {
+                    // Abstract / extern / runtime-implemented / IL2CPP-stripped; cannot inspect.
+                    return true;
+                }
+
+                byte[] il = body.GetILAsByteArray();
+                if (il == null || il.Length == 0)
+                {
+                    return true;
+                }
+
+                Module module = method.Module;
+                Type[] genericTypeArgs =
+                    method.DeclaringType?.IsGenericType == true
+                        ? method.DeclaringType.GetGenericArguments()
+                        : null;
+                Type[] genericMethodArgs = method.IsGenericMethod
+                    ? method.GetGenericArguments()
+                    : null;
+
+                int i = 0;
+                while (i < il.Length)
+                {
+                    OpCode op;
+                    if (il[i] == 0xFE)
+                    {
+                        // Two-byte (0xFE-prefixed) opcode. Without a following byte we cannot
+                        // decode the instruction; bail out conservatively. Truncated IL is not a
+                        // shape Roslyn ever emits, so reaching this path means we mis-stepped and
+                        // the safest answer is the assume-clean default.
+                        if (i + 1 >= il.Length)
+                        {
+                            return true;
+                        }
+                        op = s_twoByteOps[il[i + 1]];
+                        i += 2;
+                    }
+                    else
+                    {
+                        op = s_singleByteOps[il[i]];
+                        i += 1;
+                    }
+
+                    // Unrecognised opcode (zero-initialised slot in the table); abandon the walk
+                    // rather than risk the rest of the stream getting misread. Returning the
+                    // assume-clean default keeps the scanner from inventing a phantom warning.
+                    if (op.Size == 0)
+                    {
+                        return true;
+                    }
+
+                    if (op == OpCodes.Call || op == OpCodes.Callvirt)
+                    {
+                        if (i + 4 > il.Length)
+                        {
+                            return true;
+                        }
+                        int token = BitConverter.ToInt32(il, i);
+                        try
+                        {
+                            MethodBase target = module.ResolveMethod(
+                                token,
+                                genericTypeArgs,
+                                genericMethodArgs
+                            );
+                            if (
+                                target != null
+                                && string.Equals(target.Name, methodName, StringComparison.Ordinal)
+                            )
+                            {
+                                Type declaring = method.DeclaringType;
+                                Type resolved = target.DeclaringType;
+                                // Guard against false-positives: the resolved method must live on a
+                                // STRICT base type of the declaring class (not the declaring class
+                                // itself, not a sibling, not a generic-arg shadow). IsAssignableFrom
+                                // checks "is `declaring` assignable TO `resolved`"; i.e. is
+                                // `resolved` an ancestor of `declaring`.
+                                if (
+                                    declaring != null
+                                    && resolved != null
+                                    && declaring != resolved
+                                    && resolved.IsAssignableFrom(declaring)
+                                )
+                                {
+                                    return true;
+                                }
+                            }
+                        }
+                        catch
+                        {
+                            // ResolveMethod throws on tokens that don't bind in our generic-arg
+                            // context (e.g. a MemberRef into a closed generic we can't resolve).
+                            // The OpCodes-table walker means we can no longer land on a misaligned
+                            // 0x28 inside a wider operand, so this catch only protects against
+                            // legitimate-but-unbindable tokens; we swallow and continue scanning.
+                        }
+                        i += 4;
+                        continue;
+                    }
+
+                    // Step over the operand based on the opcode's declared operand type. Every
+                    // CIL operand size is decided by OperandType, which is exactly why the table
+                    // walker is misalignment-proof.
+                    i += GetOperandSize(op, il, i);
+                }
+                return false;
+            }
+            catch
+            {
+                // Any reflection failure → assume clean. We never want the scanner itself to
+                // become the source of a phantom warning.
+                return true;
+            }
+        }
+
+        // Returns the number of operand bytes that follow an opcode of the given OperandType,
+        // given the operand-start offset (needed for InlineSwitch's variable-length jump table).
+        private static int GetOperandSize(OpCode op, byte[] il, int operandStart)
+        {
+            switch (op.OperandType)
+            {
+                case OperandType.InlineNone:
+                    return 0;
+                case OperandType.ShortInlineBrTarget:
+                case OperandType.ShortInlineI:
+                case OperandType.ShortInlineVar:
+                    return 1;
+                case OperandType.InlineVar:
+                    return 2;
+                case OperandType.InlineBrTarget:
+                case OperandType.InlineField:
+                case OperandType.InlineI:
+                case OperandType.InlineMethod:
+                case OperandType.InlineSig:
+                case OperandType.InlineString:
+                case OperandType.InlineTok:
+                case OperandType.InlineType:
+                case OperandType.ShortInlineR:
+                    return 4;
+                case OperandType.InlineI8:
+                case OperandType.InlineR:
+                    return 8;
+                case OperandType.InlineSwitch:
+                    // 4-byte case count, then N × 4-byte branch targets. Truncated stream → bail
+                    // by consuming the rest defensively (the outer loop's bounds check then ends
+                    // the walk).
+                    if (operandStart + 4 > il.Length)
+                    {
+                        return il.Length - operandStart;
+                    }
+                    int caseCount = BitConverter.ToInt32(il, operandStart);
+                    if (caseCount < 0)
+                    {
+                        // Negative case-count is malformed IL; bail conservatively.
+                        return il.Length - operandStart;
+                    }
+                    return 4 + caseCount * 4;
+                default:
+                    // Unknown OperandType; bail conservatively by consuming the rest of the
+                    // stream so the outer loop terminates without misaligning further.
+                    return il.Length - operandStart;
+            }
+        }
+    }
+}

package/Editor/Analyzers/BaseCallIlInspector.cs.meta

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