EventViewerX: add BuildFromEvents/AddRange helpers for security reports

[PrzemyslawKlys]

• Add AddRange(...) + BuildFromEvents(...) helpers to:
  • SecurityFailedLogonsReportBuilder
  • SecurityAccountLockoutsReportBuilder
  • SecurityUserLogonsReportBuilder

This lets host repos (IntelligenceX.Tools) avoid per-tool event loops and keep parsing/aggregation logic in the engine.

[claude]

Claude finished @PrzemyslawKlys's task —— View job

---

Code Review for PR #219

Todo List:

• Read repository guidelines (CLAUDE.md)
• Examine SecurityAccountLockoutsReportBuilder.cs changes
• Examine SecurityFailedLogonsReportBuilder.cs changes
• Examine SecurityUserLogonsReportBuilder.cs changes
• Analyze code quality and best practices
• Check for potential bugs or issues
• Evaluate performance considerations
• Review security concerns
• Assess test coverage needs
• Provide final review feedback

---

Review Summary ✅

This PR adds consistent AddRange and BuildFromEvents helper methods to three security report builders. The implementation follows good practices and provides valuable convenience methods for host applications.

Positives 👍

• Consistent API: All three builders now have identical helper method signatures
• Proper null handling: AddRange safely handles null input with early return
• Cancellation support: Both methods properly support CancellationToken with ThrowIfCancellationRequested()
• Clean static factory: BuildFromEvents provides a convenient one-liner for common use cases
• Defensive programming: Uses Math.Max(0, sampleSize) and null coalescing (?? Array.Empty<int>())
• Code reuse: Leverages existing Add() logic without duplication

Code Quality 📋

• Documentation: XML comments are comprehensive and follow existing conventions
• Naming: Method names clearly indicate their purpose (AddRange, BuildFromEvents)
• Consistency: Implementation is nearly identical across all three builders (good pattern)
• Error handling: Appropriate use of cancellation tokens for long-running operations

No Issues Found ✅

• Security: No security concerns - methods handle input data safely
• Performance: Efficient implementation using existing aggregation logic
• Memory: Proper handling of collections and no obvious leaks
• Thread safety: Builders are not thread-safe by design (documented behavior)

Minor Observations 💡

1. SecurityUserLogonsReportBuilder.cs:167: Parameter order differs slightly from other builders (eventIds comes second vs bool parameters first), but this matches the existing constructor signature ✅

2. Null handling pattern: The events is null check could use events == null for consistency with the codebase's style, but is null is fine and more modern ✅

Test Coverage Recommendation 🧪

Consider adding unit tests for the new methods:

• AddRange with null/empty collections
• AddRange with cancellation token
• BuildFromEvents end-to-end scenarios

Verdict ✅

APPROVE - This is a clean, well-implemented addition that improves the API usability without introducing risks. The helper methods follow established patterns and provide genuine value to consuming code.

---