git.stella-ops.org/src/Scanner/__Libraries/StellaOps.Scanner.VulnSurfaces/CallGraph/IInternalCallGraphBuilder.cs

// -----------------------------------------------------------------------------
// IInternalCallGraphBuilder.cs
// Sprint: SPRINT_3700_0003_0001_trigger_extraction
// Description: Interface for building internal call graphs from package sources.
// -----------------------------------------------------------------------------

using System.Threading;
using System.Threading.Tasks;

namespace StellaOps.Scanner.VulnSurfaces.CallGraph;

/// <summary>
/// Builds internal call graphs from package/assembly sources.
/// Implementations exist for different ecosystems (.NET, Java, Node.js, Python).
/// </summary>
public interface IInternalCallGraphBuilder
{
    /// <summary>
    /// Ecosystem this builder supports (e.g., "nuget", "maven", "npm", "pypi").
    /// </summary>
    string Ecosystem { get; }

    /// <summary>
    /// Checks if this builder can handle the given package.
    /// </summary>
    /// <param name="packagePath">Path to package archive or extracted directory.</param>
    bool CanHandle(string packagePath);

    /// <summary>
    /// Builds an internal call graph from a package.
    /// </summary>
    /// <param name="request">Build request with package details.</param>
    /// <param name="cancellationToken">Cancellation token.</param>
    /// <returns>Internal call graph for the package.</returns>
    Task<InternalCallGraphBuildResult> BuildAsync(
        InternalCallGraphBuildRequest request,
        CancellationToken cancellationToken = default);
}

/// <summary>
/// Request to build an internal call graph.
/// </summary>
public sealed record InternalCallGraphBuildRequest
{
    /// <summary>
    /// Package identifier (PURL or package name).
    /// </summary>
    public required string PackageId { get; init; }

    /// <summary>
    /// Package version.
    /// </summary>
    public required string Version { get; init; }

    /// <summary>
    /// Path to the package archive or extracted directory.
    /// </summary>
    public required string PackagePath { get; init; }

    /// <summary>
    /// Whether to include private methods in the graph.
    /// Default is false (only public API surface).
    /// </summary>
    public bool IncludePrivateMethods { get; init; }

    /// <summary>
    /// Maximum depth for call graph traversal.
    /// </summary>
    public int MaxDepth { get; init; } = 20;
}

/// <summary>
/// Result of building an internal call graph.
/// </summary>
public sealed record InternalCallGraphBuildResult
{
    /// <summary>
    /// Whether the build succeeded.
    /// </summary>
    public bool Success { get; init; }

    /// <summary>
    /// The built call graph (null if failed).
    /// </summary>
    public InternalCallGraph? Graph { get; init; }

    /// <summary>
    /// Error message if build failed.
    /// </summary>
    public string? Error { get; init; }

    /// <summary>
    /// Build duration.
    /// </summary>
    public TimeSpan Duration { get; init; }

    /// <summary>
    /// Number of assemblies/files processed.
    /// </summary>
    public int FilesProcessed { get; init; }

    /// <summary>
    /// Creates a successful result.
    /// </summary>
    public static InternalCallGraphBuildResult Ok(InternalCallGraph graph, TimeSpan duration, int filesProcessed) =>
        new()
        {
            Success = true,
            Graph = graph,
            Duration = duration,
            FilesProcessed = filesProcessed
        };

    /// <summary>
    /// Creates a failed result.
    /// </summary>
    public static InternalCallGraphBuildResult Fail(string error, TimeSpan duration) =>
        new()
        {
            Success = false,
            Error = error,
            Duration = duration
        };
}