git.stella-ops.org/src/Cli/StellaOps.Cli/Commands/DriftExitCodes.cs

// -----------------------------------------------------------------------------
// DriftExitCodes.cs
// Sprint: SPRINT_3600_0005_0001_policy_ci_gate_integration
// Description: Exit codes for stella scan drift command for CI/CD integration.
// -----------------------------------------------------------------------------

namespace StellaOps.Cli.Commands;

/// <summary>
/// Exit codes for the drift detection command.
/// Designed for CI/CD pipeline integration.
/// </summary>
public static class DriftExitCodes
{
    // Success codes (0-9)

    /// <summary>
    /// No material reachability changes detected.
    /// </summary>
    public const int Success = 0;

    /// <summary>
    /// New paths detected but not to affected sinks (informational drift).
    /// </summary>
    public const int SuccessWithInfoDrift = 1;

    /// <summary>
    /// Hardening detected - previously reachable paths now unreachable.
    /// </summary>
    public const int SuccessHardening = 2;

    /// <summary>
    /// Previously mitigated paths now reachable again (regression).
    /// </summary>
    public const int HardeningRegression = 2;

    /// <summary>
    /// Known Exploited Vulnerability now reachable.
    /// </summary>
    public const int KevReachable = 3;

    /// <summary>
    /// Affected vulnerability now reachable.
    /// </summary>
    public const int AffectedReachable = 4;

    /// <summary>
    /// Policy gate blocked the drift.
    /// </summary>
    public const int PolicyBlocked = 5;

    // Error codes (10-19)

    /// <summary>
    /// Input error - invalid scan ID, missing parameters.
    /// </summary>
    public const int InputError = 10;

    /// <summary>
    /// Analysis error - call graph extraction failed.
    /// </summary>
    public const int AnalysisError = 11;

    /// <summary>
    /// Storage error - database/cache unavailable.
    /// </summary>
    public const int StorageError = 12;

    /// <summary>
    /// Policy error - gate evaluation failed.
    /// </summary>
    public const int PolicyError = 13;

    /// <summary>
    /// Network error - unable to reach required services.
    /// </summary>
    public const int NetworkError = 14;

    /// <summary>
    /// Unknown error.
    /// </summary>
    public const int UnknownError = 99;

    /// <summary>
    /// Gets the exit code name for display purposes.
    /// </summary>
    public static string GetName(int exitCode) => exitCode switch
    {
        Success => "SUCCESS",
        SuccessWithInfoDrift => "SUCCESS_INFO_DRIFT",
        SuccessHardening => "SUCCESS_HARDENING",
        KevReachable => "KEV_REACHABLE",
        AffectedReachable => "AFFECTED_REACHABLE",
        PolicyBlocked => "POLICY_BLOCKED",
        InputError => "INPUT_ERROR",
        AnalysisError => "ANALYSIS_ERROR",
        StorageError => "STORAGE_ERROR",
        PolicyError => "POLICY_ERROR",
        NetworkError => "NETWORK_ERROR",
        _ => "UNKNOWN_ERROR"
    };

    /// <summary>
    /// Gets a description for the exit code.
    /// </summary>
    public static string GetDescription(int exitCode) => exitCode switch
    {
        Success => "No material reachability changes detected",
        SuccessWithInfoDrift => "New paths detected but not to affected sinks",
        SuccessHardening => "Hardening detected - previously reachable paths now unreachable",
        KevReachable => "Known Exploited Vulnerability now reachable",
        AffectedReachable => "Affected vulnerability now reachable",
        PolicyBlocked => "Policy gate blocked the drift",
        InputError => "Input error - invalid scan ID or missing parameters",
        AnalysisError => "Analysis error - call graph extraction failed",
        StorageError => "Storage error - database or cache unavailable",
        PolicyError => "Policy error - gate evaluation failed",
        NetworkError => "Network error - unable to reach required services",
        _ => "Unknown error occurred"
    };

    /// <summary>
    /// Determines if the exit code represents a success condition.
    /// </summary>
    public static bool IsSuccess(int exitCode) => exitCode >= 0 && exitCode < 10;

    /// <summary>
    /// Determines if the exit code represents an error condition.
    /// </summary>
    public static bool IsError(int exitCode) => exitCode >= 10;

    /// <summary>
    /// Determines if the exit code represents a blocking condition.
    /// </summary>
    public static bool IsBlocking(int exitCode) => exitCode is KevReachable or AffectedReachable or PolicyBlocked;
}

/// <summary>
/// Result of drift analysis for CLI output.
/// </summary>
public sealed record DriftCommandResult
{
    /// <summary>
    /// Exit code for the command.
    /// </summary>
    public required int ExitCode { get; init; }

    /// <summary>
    /// Human-readable message.
    /// </summary>
    public required string Message { get; init; }

    /// <summary>
    /// Number of newly reachable paths.
    /// </summary>
    public int DeltaReachable { get; init; }

    /// <summary>
    /// Number of newly unreachable paths.
    /// </summary>
    public int DeltaUnreachable { get; init; }

    /// <summary>
    /// Whether a KEV is now reachable.
    /// </summary>
    public bool HasKevReachable { get; init; }

    /// <summary>
    /// Policy gate that blocked (if any).
    /// </summary>
    public string? BlockedBy { get; init; }

    /// <summary>
    /// Suggestion for resolving the block.
    /// </summary>
    public string? Suggestion { get; init; }

    /// <summary>
    /// SARIF output path (if generated).
    /// </summary>
    public string? SarifOutputPath { get; init; }
}