Needlr Analyzers¶

Needlr includes optional Roslyn analyzers to help developers avoid common mistakes and ensure best practices.

Core Analyzers (NexusLabs.Needlr.Analyzers)¶

These analyzers are included with the NexusLabs.Needlr package.

Rule ID	Severity	Description
NDLRCOR001	Error	Reflection API used in AOT project
NDLRCOR002	Warning	Plugin has constructor dependencies
NDLRCOR003	Error	[DeferToContainer] attribute in generated code is ignored
NDLRCOR004	Warning	Injectable type in global namespace may not be discovered
NDLRCOR005	Warning	Lifetime mismatch: longer-lived service depends on shorter-lived service
NDLRCOR006	Error	Circular dependency detected
NDLRCOR007	Error	Intercept type must implement IMethodInterceptor
NDLRCOR008	Warning	[Intercept] applied to class without interfaces
NDLRCOR009	Info	Lazy references undiscovered type
NDLRCOR010	Info	IEnumerable has no discovered implementations
NDLRCOR011	Info	[FromKeyedServices] keyed service usage tracking
NDLRCOR012	Error	Disposable captive dependency
NDLRCOR015	Error	[RegisterAs] type T not implemented by class

MAF Analyzers (NexusLabs.Needlr.AgentFramework.Analyzers)¶

These analyzers are included with the NexusLabs.Needlr.AgentFramework.Analyzers package.

Rule ID	Severity	Description
NDLRMAF001	Error	[AgentHandoffsTo] target type is not a declared agent
NDLRMAF002	Error	Group chat has fewer than two members
NDLRMAF003	Warning	[AgentHandoffsTo] source class is not a declared agent
NDLRMAF004	Warning	Cyclic handoff chain detected
NDLRMAF005	Warning	FunctionGroups references an unregistered group name
NDLRMAF006	Error	Duplicate Order value in sequential pipeline
NDLRMAF007	Warning	Gap in sequential pipeline Order values
NDLRMAF008	Info	Agent participates in no topology declaration
NDLRMAF009	Warning	[WorkflowRunTerminationCondition] declared on a non-agent class
NDLRMAF010	Error	Termination condition type does not implement IWorkflowTerminationCondition
NDLRMAF011	Info	Prefer [AgentTerminationCondition] over [WorkflowRunTerminationCondition] for group chat members

Graph Workflow Analyzers (NexusLabs.Needlr.AgentFramework.Analyzers)¶

These analyzers validate DAG graph topologies declared via [AgentGraphEntry], [AgentGraphEdge], and [AgentGraphNode] attributes.

Rule ID	Severity	Description
NDLRMAF016	Error	Cycle detected in agent graph
NDLRMAF017	Error	Graph has no entry point
NDLRMAF018	Error	Graph has multiple entry points
NDLRMAF019	Error	Graph edge target is not a declared agent
NDLRMAF020	Warning	Graph edge source is not a declared agent
NDLRMAF021	Warning	Graph entry point is not a declared agent
NDLRMAF022	Warning	Graph contains unreachable agents
NDLRMAF024	Warning	All edges from fan-out node are optional
NDLRMAF025	Error	CreateGraphWorkflow incompatible with GraphJoinMode.WaitAny
NDLRMAF027	Error	Terminal node has outgoing edges
NDLRMAF028	Error	Condition method not found or has wrong signature
NDLRMAF029	Error	Reducer method not found or has wrong signature

SignalR Analyzers(NexusLabs.Needlr.SignalR.Analyzers)¶

These analyzers are included with the NexusLabs.Needlr.SignalR package.

Rule ID	Severity	Description
NDLRSIG001	Warning	HubPath must be a constant expression
NDLRSIG002	Warning	HubType must be a typeof expression

Generator Diagnostics (NexusLabs.Needlr.Generators)¶

These diagnostics are emitted by the source generator to detect configuration issues at compile time.

Rule ID	Severity	Description
NDLRGEN001	Error	Internal type in referenced assembly cannot be registered
NDLRGEN002	Error	Referenced assembly has internal plugin types but no type registry
NDLRGEN003	Warning	[GenerateFactory] all parameters are injectable
NDLRGEN004	Warning	[GenerateFactory] no parameters are injectable
NDLRGEN005	Error	[GenerateFactory] type T not implemented by class
NDLRGEN006	Error	[OpenDecoratorFor] type must be an open generic interface
NDLRGEN007	Error	[OpenDecoratorFor] decorator must be an open generic class
NDLRGEN008	Error	[OpenDecoratorFor] decorator must implement the interface
NDLRGEN014	Error	[Options] Validator type has no validation method
NDLRGEN015	Error	[Options] Validator type mismatch
NDLRGEN016	Error	[Options] Validation method not found
NDLRGEN017	Error	[Options] Validation method has wrong signature
NDLRGEN018	Warning	[Options] Validator won't run (ValidateOnStart is false)
NDLRGEN019	Warning	[Options] Validation method won't run (ValidateOnStart is false)
NDLRGEN020	Error	[Options] is not compatible with Native AOT
NDLRGEN021	Warning	[Options] Positional record must be partial
NDLRGEN022	Error	Disposable captive dependency (uses inferred lifetimes)
NDLRGEN031	Error	[Provider] on class requires partial modifier
NDLRGEN032	Error	[Provider] interface has invalid member
NDLRGEN033	Warning	[Provider] property uses concrete type
NDLRGEN034	Error	[Provider] circular dependency detected

HttpClient Diagnostics (NexusLabs.Needlr.Generators)¶

These diagnostics are emitted by the HttpClientOptionsAnalyzer to catch misuse of the [HttpClientOptions] attribute at compile time.

Rule ID	Severity	Description
NDLRHTTP001	Error	[HttpClientOptions] target must implement INamedHttpClientOptions
NDLRHTTP002	Error	HttpClient name sources conflict (attribute Name vs ClientName property)
NDLRHTTP003	Error	ClientName property body is not a literal expression
NDLRHTTP004	Error	Resolved HttpClient name is empty
NDLRHTTP005	Error	Duplicate HttpClient name across the compilation
NDLRHTTP006	Error	ClientName property has the wrong shape (must be instance `string` with getter)

Diagnostic ID Naming Convention¶

Needlr uses a component-based naming convention for diagnostic IDs:

Component	Prefix	Example
Core Analyzers	`NDLRCOR`	`NDLRCOR001`
MAF Analyzers	`NDLRMAF`	`NDLRMAF001`
SignalR Analyzers	`NDLRSIG`	`NDLRSIG001`
Source Generators	`NDLRGEN`	`NDLRGEN001`
HttpClient Analyzers	`NDLRHTTP`	`NDLRHTTP001`

Suppressing Warnings¶

To suppress a specific analyzer warning, use pragma directives:

#pragma warning disable NDLRCOR001
// Code that triggers the warning
#pragma warning restore NDLRCOR001

Or suppress in your project file for the entire project:

<PropertyGroup>
  <NoWarn>$(NoWarn);NDLRCOR002</NoWarn>
</PropertyGroup>

Or configure severity in .editorconfig (recommended):

# .editorconfig
[*.cs]
# Disable a diagnostic
dotnet_diagnostic.NDLRCOR009.severity = none

# Promote to warning
dotnet_diagnostic.NDLRCOR010.severity = warning

# Promote to error
dotnet_diagnostic.NDLRCOR005.severity = error

Resolution Validation Analyzers¶

NDLRCOR009, NDLRCOR010, and NDLRCOR011 are resolution validation analyzers that help catch potential issues with service resolution patterns.

These analyzers:

Only activate when [assembly: GenerateTypeRegistry] is present
Default to Info severity (non-blocking)
Can be promoted to Warning or Error via .editorconfig

Analyzer	Purpose
NDLRCOR009	Validates `Lazy<T>` references discoverable types
NDLRCOR010	Validates `IEnumerable<T>` has implementations
NDLRCOR011	Tracks `[FromKeyedServices]` keyed service usage

To see which analyzers are active in your project, enable diagnostics output:

<PropertyGroup>
  <NeedlrDiagnostics>true</NeedlrDiagnostics>
</PropertyGroup>

This generates AnalyzerStatus.md in your output directory showing all analyzers and their current severity.

Configuration¶

Analyzers are automatically enabled when you reference the Needlr packages. No additional configuration is required.

For AOT projects, ensure your project has the appropriate settings for the analyzers to detect AOT mode:

<PropertyGroup>
  <PublishAot>true</PublishAot>
  <!-- or -->
  <IsAotCompatible>true</IsAotCompatible>
</PropertyGroup>