Added static analysis doc. Skip Analysis option added. Unused trigger detected.

Author: leeoades

FunctionalStateMachine.Core.Tests/StateMachineAnalysisTests.cs

@@ -231,6 +231,25 @@ public void Validate_AllowsComplexReachableStateMachine()
         Assert.NotNull(machine);
     }
 
+    [Fact]
+    public void Validate_WarnsOnUnusedTriggers()
+    {
+        // State machine that doesn't use all defined trigger types
+        var machine = StateMachine<State, Trigger, Data, CommandBase>.Create()
+            .StartWith(State.A)
+            .For(State.A)
+                .On<Trigger.T1>()  // T1 is used
+                    .TransitionTo(State.B)
+            .For(State.B)
+                .On<Trigger.T1>()
+                    .TransitionTo(State.A)
+            // T2 and T3 are never used
+            .Build();
+
+        // Should not throw, but warnings should be logged
+        Assert.NotNull(machine);
+    }
+
     private enum State
     {
         A,
@@ -242,6 +261,8 @@ private enum State
     private abstract record Trigger
     {
         public sealed record T1 : Trigger;
+        public sealed record T2 : Trigger;  // Unused trigger
+        public sealed record T3 : Trigger;  // Unused trigger
     }
 
     private sealed record Data(int Value);

FunctionalStateMachine.Core/StateMachine.cs

@@ -201,7 +201,7 @@ private bool HandleUnhandled(
         return false;
     }
 
-    internal void Validate()
+    internal void Validate(bool skipAnalysis = false)
     {
         foreach (var definition in _states.Values)
         {
@@ -293,24 +293,27 @@ internal void Validate()
             ResolveInitialLeaf(_initialState!);
         }
 
-        // Run static analysis
-        var analysis = StateMachineAnalyzer<TState, TTrigger, TData, TCommand>.Analyze(_states, _initialState!);
-        
-        // Errors are treated as validation failures
-        if (!analysis.IsValid)
+        // Run static analysis (unless skipped)
+        if (!skipAnalysis)
         {
-            throw new InvalidOperationException(
-                "State machine validation detected errors:\n" + 
-                string.Join("\n", analysis.Errors.Select(e => $"  - {e}")));
-        }
+            var analysis = StateMachineAnalyzer<TState, TTrigger, TData, TCommand>.Analyze(_states, _initialState!);
+            
+            // Errors are treated as validation failures
+            if (!analysis.IsValid)
+            {
+                throw new InvalidOperationException(
+                    "State machine validation detected errors:\n" + 
+                    string.Join("\n", analysis.Errors.Select(e => $"  - {e}")));
+            }
 
-        // Warnings are logged/reported (we could use ILogger here if needed)
-        if (analysis.Warnings.Count > 0)
-        {
-            System.Diagnostics.Debug.WriteLine("State machine analysis detected warnings:");
-            foreach (var warning in analysis.Warnings)
+            // Warnings are logged/reported (we could use ILogger here if needed)
+            if (analysis.Warnings.Count > 0)
             {
-                System.Diagnostics.Debug.WriteLine($"  - {warning}");
+                System.Diagnostics.Debug.WriteLine("State machine analysis detected warnings:");
+                foreach (var warning in analysis.Warnings)
+                {
+                    System.Diagnostics.Debug.WriteLine($"  - {warning}");
+                }
             }
         }
     }

FunctionalStateMachine.Core/StateMachineAnalysis.cs

@@ -47,6 +47,9 @@ public static AnalysisResult Analyze(
         // Analyze dead-end states
         AnalyzeDeadEndStates(states, initialState, result);
 
+        // Analyze unused triggers
+        AnalyzeUnusedTriggers(states, result);
+
         return result;
     }
 
@@ -277,6 +280,89 @@ private static void AnalyzeDeadEndStates(
         }
     }
 
+    /// <summary>
+    /// Detect trigger types that are defined but never used in any transition.
+    /// </summary>
+    private static void AnalyzeUnusedTriggers(
+        IReadOnlyDictionary<TState, StateMachine<TState, TTrigger, TData, TCommand>.StateDefinition> states,
+        AnalysisResult result)
+    {
+        // Collect all used trigger types
+        var usedTriggers = new HashSet<object>();
+        
+        foreach (var definition in states.Values)
+        {
+            foreach (var triggerKey in definition.Transitions.Keys)
+            {
+                usedTriggers.Add(triggerKey);
+            }
+        }
+
+        // Get all possible trigger types from the TTrigger type
+        var triggerType = typeof(TTrigger);
+        
+        // If TTrigger is a sealed record hierarchy, find all derived types
+        var allTriggerTypes = GetAllTriggerTypes(triggerType);
+        
+        // Find unused trigger types
+        foreach (var possibleTrigger in allTriggerTypes)
+        {
+            // Check if this trigger type is used
+            bool isUsed = usedTriggers.Any(t => 
+            {
+                // Handle both type-based and value-based triggers
+                if (t is Type)
+                    return (Type)t == possibleTrigger;
+                return t.GetType() == possibleTrigger;
+            });
+
+            if (!isUsed)
+            {
+                result.AddWarning(
+                    $"Trigger type '{possibleTrigger.Name}' is defined but never used in any transition. " +
+                    "Consider removing it or adding transitions that use it.");
+            }
+        }
+    }
+
+    private static HashSet<Type> GetAllTriggerTypes(Type triggerType)
+    {
+        var types = new HashSet<Type>();
+        
+        // Add the base trigger type if it's abstract/record
+        if (triggerType.IsAbstract || IsRecordType(triggerType))
+        {
+            // Find all derived types in the same assembly
+            var assembly = triggerType.Assembly;
+            foreach (var type in assembly.GetTypes())
+            {
+                // Check if it's a record/sealed record deriving from the trigger type
+                if (type != triggerType && 
+                    triggerType.IsAssignableFrom(type) && 
+                    !type.IsAbstract &&
+                    IsRecordType(type))
+                {
+                    types.Add(type);
+                }
+            }
+        }
+        
+        // Always add the trigger type itself as a fallback
+        if (types.Count == 0)
+        {
+            types.Add(triggerType);
+        }
+
+        return types;
+    }
+
+    private static bool IsRecordType(Type type)
+    {
+        // Records are detected by checking for the generated 'EqualityContract' property
+        return type.GetProperty("EqualityContract", 
+            System.Reflection.BindingFlags.NonPublic | System.Reflection.BindingFlags.Instance) != null;
+    }
+
     private static string GetTriggerTypeName(object triggerKey)
     {
         // triggerKey is typically the trigger type or trigger value

FunctionalStateMachine.Core/StateMachineBuilder.cs

@@ -5,6 +5,7 @@ public sealed class StateMachineBuilder<TState, TTrigger, TData, TCommand>
     where TTrigger : notnull
 {
     private readonly StateMachine<TState, TTrigger, TData, TCommand> _machine = new();
+    private bool _skipAnalysis = false;
 
     public StateMachineBuilder<TState, TTrigger, TData, TCommand> StartWith(TState state)
     {
@@ -24,9 +25,18 @@ public StateConfiguration For(TState state)
         return new StateConfiguration(this, _machine.For(state));
     }
 
+    /// <summary>
+    /// Skip static analysis when building. Use with caution - analysis catches real configuration errors.
+    /// </summary>
+    public StateMachineBuilder<TState, TTrigger, TData, TCommand> SkipAnalysis()
+    {
+        _skipAnalysis = true;
+        return this;
+    }
+
     public StateMachine<TState, TTrigger, TData, TCommand> Build()
     {
-        _machine.Validate();
+        _machine.Validate(skipAnalysis: _skipAnalysis);
         return _machine;
     }
 

FunctionalStateMachine.sln

@@ -28,6 +28,9 @@ Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "_", "_", "{919D74CB-8078-40
 		docs\no-data.md = docs\no-data.md
 		docs\state-data.md = docs\state-data.md
 		docs\packages.md = docs\packages.md
+		docs\conditional-steps.md = docs\conditional-steps.md
+		docs\immediate-transitions.md = docs\immediate-transitions.md
+		docs\static-analysis.md = docs\static-analysis.md
 	EndProjectSection
 EndProject
 Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "FunctionalStateMachine.CommandRunner", "FunctionalStateMachine.CommandRunner\FunctionalStateMachine.CommandRunner.csproj", "{A0A6A44F-CD8C-49F6-B659-5BA7B77A2BB4}"

docs/index.md

@@ -18,6 +18,10 @@ Welcome to the Functional State Machine docs. Each guide introduces a feature, w
 - Hierarchical states: `hierarchical-states.md`
 - No-data builder: `no-data.md`
 
+## Validation and analysis
+
+- Static analysis and configuration validation: `static-analysis.md`
+
 ## Tooling and integrations
 
 - Mermaid diagram generation: `diagrams.md`