sprints completion. new product advisories prepared

src/Scanner/__Libraries/StellaOps.Scanner.AiCodeGuard/IAiCodeGuardService.cs

@@ -0,0 +1,214 @@
+// -----------------------------------------------------------------------------
+// IAiCodeGuardService.cs
+// Sprint: SPRINT_20260112_010_SCANNER_ai_code_guard_core
+// Task: SCANNER-AIGUARD-002/006
+// Description: AI Code Guard service interface for Scanner.
+// -----------------------------------------------------------------------------
+
+using System.Collections.Immutable;
+
+namespace StellaOps.Scanner.AiCodeGuard;
+
+/// <summary>
+/// Service for AI Code Guard analysis.
+/// </summary>
+public interface IAiCodeGuardService
+{
+    /// <summary>
+    /// Analyzes changed hunks for AI-generated code issues.
+    /// </summary>
+    /// <param name="request">Analysis request with hunks and options.</param>
+    /// <param name="cancellationToken">Cancellation token.</param>
+    /// <returns>Analysis result with findings and verdict.</returns>
+    Task<AiCodeGuardAnalysisResult> AnalyzeAsync(
+        AiCodeGuardAnalysisRequest request,
+        CancellationToken cancellationToken = default);
+}
+
+/// <summary>
+/// Analysis request for AI Code Guard.
+/// </summary>
+public sealed record AiCodeGuardAnalysisRequest
+{
+    /// <summary>
+    /// Repository URI.
+    /// </summary>
+    public required string RepositoryUri { get; init; }
+
+    /// <summary>
+    /// Commit SHA being analyzed.
+    /// </summary>
+    public required string CommitSha { get; init; }
+
+    /// <summary>
+    /// Branch name (optional).
+    /// </summary>
+    public string? Branch { get; init; }
+
+    /// <summary>
+    /// Base commit for diff comparison (optional, for PR analysis).
+    /// </summary>
+    public string? BaseCommitSha { get; init; }
+
+    /// <summary>
+    /// Changed hunks to analyze.
+    /// </summary>
+    public required IReadOnlyList<CodeHunk> Hunks { get; init; }
+
+    /// <summary>
+    /// Analysis timestamp (input, not wall-clock for determinism).
+    /// </summary>
+    public required DateTimeOffset AnalysisTimestamp { get; init; }
+
+    /// <summary>
+    /// Optional options override (uses defaults if null).
+    /// </summary>
+    public AiCodeGuardOptions? Options { get; init; }
+}
+
+/// <summary>
+/// A code hunk to analyze.
+/// </summary>
+public sealed record CodeHunk
+{
+    /// <summary>
+    /// File path relative to repository root.
+    /// </summary>
+    public required string FilePath { get; init; }
+
+    /// <summary>
+    /// Programming language (detected or specified).
+    /// </summary>
+    public required string Language { get; init; }
+
+    /// <summary>
+    /// Start line in the file (1-based).
+    /// </summary>
+    public required int StartLine { get; init; }
+
+    /// <summary>
+    /// End line in the file (1-based).
+    /// </summary>
+    public required int EndLine { get; init; }
+
+    /// <summary>
+    /// Hunk content (source code).
+    /// </summary>
+    public required string Content { get; init; }
+
+    /// <summary>
+    /// Whether this is new code (added) vs existing.
+    /// </summary>
+    public required bool IsNew { get; init; }
+
+    /// <summary>
+    /// SHA-256 hash of normalized content for deterministic hunk ID.
+    /// </summary>
+    public string? ContentHash { get; init; }
+}
+
+/// <summary>
+/// AI Code Guard analysis result.
+/// </summary>
+public sealed record AiCodeGuardAnalysisResult
+{
+    /// <summary>
+    /// Whether analysis completed successfully.
+    /// </summary>
+    public required bool Success { get; init; }
+
+    /// <summary>
+    /// Scanner configuration used.
+    /// </summary>
+    public required AiCodeGuardScannerConfigResult ScannerConfig { get; init; }
+
+    /// <summary>
+    /// Files analyzed.
+    /// </summary>
+    public required ImmutableList<AiCodeGuardFileResult> Files { get; init; }
+
+    /// <summary>
+    /// Detected findings.
+    /// </summary>
+    public required ImmutableList<AiCodeGuardFindingResult> Findings { get; init; }
+
+    /// <summary>
+    /// Overall verdict.
+    /// </summary>
+    public required AiCodeGuardVerdictResult Verdict { get; init; }
+
+    /// <summary>
+    /// Total lines analyzed.
+    /// </summary>
+    public required long TotalLinesAnalyzed { get; init; }
+
+    /// <summary>
+    /// Error message if Success is false.
+    /// </summary>
+    public string? Error { get; init; }
+
+    /// <summary>
+    /// Content digest for the analysis result (SHA-256).
+    /// </summary>
+    public string? ContentDigest { get; init; }
+}
+
+/// <summary>
+/// Scanner configuration in result.
+/// </summary>
+public sealed record AiCodeGuardScannerConfigResult
+{
+    public required string ScannerVersion { get; init; }
+    public required string ModelVersion { get; init; }
+    public required double ConfidenceThreshold { get; init; }
+    public required ImmutableList<string> EnabledCategories { get; init; }
+    public ImmutableList<string>? RuleSets { get; init; }
+}
+
+/// <summary>
+/// File analyzed in result.
+/// </summary>
+public sealed record AiCodeGuardFileResult
+{
+    public required string Path { get; init; }
+    public required string Digest { get; init; }
+    public required int LineCount { get; init; }
+    public string? Language { get; init; }
+}
+
+/// <summary>
+/// Finding in result.
+/// </summary>
+public sealed record AiCodeGuardFindingResult
+{
+    public required string Id { get; init; }
+    public required string Category { get; init; }
+    public required string Severity { get; init; }
+    public required double Confidence { get; init; }
+    public required string FilePath { get; init; }
+    public required int StartLine { get; init; }
+    public required int EndLine { get; init; }
+    public int? StartColumn { get; init; }
+    public int? EndColumn { get; init; }
+    public string? Snippet { get; init; }
+    public required string Description { get; init; }
+    public required string RuleId { get; init; }
+    public string? DetectionMethod { get; init; }
+    public ImmutableList<string>? Indicators { get; init; }
+    public double? PerplexityScore { get; init; }
+    public ImmutableList<string>? PatternMatches { get; init; }
+    public string? Remediation { get; init; }
+}
+
+/// <summary>
+/// Verdict in result.
+/// </summary>
+public sealed record AiCodeGuardVerdictResult
+{
+    public required string Status { get; init; }
+    public required int TotalFindings { get; init; }
+    public required ImmutableDictionary<string, int> FindingsBySeverity { get; init; }
+    public double? AiGeneratedPercentage { get; init; }
+    public required string Message { get; init; }
+    public string? Recommendation { get; init; }
+}