// Copyright (c) StellaOps. All rights reserved.
// Licensed under BUSL-1.1. See LICENSE in the project root.

namespace StellaOps.BinaryIndex.Disassembly;

/// <summary>
/// Abstraction over binary disassembly engine plugins.
/// Each plugin implements this interface to provide disassembly capabilities.
/// </summary>
public interface IDisassemblyPlugin
{
    /// <summary>
    /// Gets the capabilities of this disassembly plugin.
    /// </summary>
    DisassemblyCapabilities Capabilities { get; }

    /// <summary>
    /// Loads a binary from a stream and detects format/architecture.
    /// </summary>
    /// <param name="stream">The binary stream to load.</param>
    /// <param name="archHint">Optional hint for architecture detection.</param>
    /// <param name="formatHint">Optional hint for format detection.</param>
    /// <returns>Binary information including format, architecture, and metadata.</returns>
    BinaryInfo LoadBinary(Stream stream, CpuArchitecture? archHint = null, BinaryFormat? formatHint = null);

    /// <summary>
    /// Loads a binary from a byte array.
    /// </summary>
    /// <param name="bytes">The binary data.</param>
    /// <param name="archHint">Optional hint for architecture detection.</param>
    /// <param name="formatHint">Optional hint for format detection.</param>
    /// <returns>Binary information including format, architecture, and metadata.</returns>
    BinaryInfo LoadBinary(ReadOnlySpan<byte> bytes, CpuArchitecture? archHint = null, BinaryFormat? formatHint = null);

    /// <summary>
    /// Gets executable code regions (sections) from the binary.
    /// </summary>
    /// <param name="binary">The loaded binary information.</param>
    /// <returns>Enumerable of code regions.</returns>
    IEnumerable<CodeRegion> GetCodeRegions(BinaryInfo binary);

    /// <summary>
    /// Gets symbols (functions) from the binary.
    /// </summary>
    /// <param name="binary">The loaded binary information.</param>
    /// <returns>Enumerable of symbol information.</returns>
    IEnumerable<SymbolInfo> GetSymbols(BinaryInfo binary);

    /// <summary>
    /// Disassembles a code region to instructions.
    /// </summary>
    /// <param name="binary">The loaded binary information.</param>
    /// <param name="region">The code region to disassemble.</param>
    /// <returns>Enumerable of disassembled instructions.</returns>
    IEnumerable<DisassembledInstruction> Disassemble(BinaryInfo binary, CodeRegion region);

    /// <summary>
    /// Disassembles starting at a specific address for a given length.
    /// </summary>
    /// <param name="binary">The loaded binary information.</param>
    /// <param name="startAddress">Virtual address to start disassembly.</param>
    /// <param name="length">Maximum number of bytes to disassemble.</param>
    /// <returns>Enumerable of disassembled instructions.</returns>
    IEnumerable<DisassembledInstruction> Disassemble(BinaryInfo binary, ulong startAddress, ulong length);

    /// <summary>
    /// Disassembles a specific symbol/function.
    /// </summary>
    /// <param name="binary">The loaded binary information.</param>
    /// <param name="symbol">The symbol to disassemble.</param>
    /// <returns>Enumerable of disassembled instructions.</returns>
    IEnumerable<DisassembledInstruction> DisassembleSymbol(BinaryInfo binary, SymbolInfo symbol);
}

/// <summary>
/// Registry for disassembly plugins. Manages plugin discovery and selection.
/// </summary>
public interface IDisassemblyPluginRegistry
{
    /// <summary>
    /// Gets all registered plugins.
    /// </summary>
    IReadOnlyList<IDisassemblyPlugin> Plugins { get; }

    /// <summary>
    /// Finds the best plugin for the given architecture and format.
    /// </summary>
    /// <param name="architecture">Target CPU architecture.</param>
    /// <param name="format">Target binary format.</param>
    /// <returns>The best matching plugin, or null if none found.</returns>
    IDisassemblyPlugin? FindPlugin(CpuArchitecture architecture, BinaryFormat format);

    /// <summary>
    /// Finds all plugins that support the given architecture.
    /// </summary>
    /// <param name="architecture">Target CPU architecture.</param>
    /// <returns>All matching plugins ordered by priority.</returns>
    IEnumerable<IDisassemblyPlugin> FindPluginsForArchitecture(CpuArchitecture architecture);

    /// <summary>
    /// Finds all plugins that support the given format.
    /// </summary>
    /// <param name="format">Target binary format.</param>
    /// <returns>All matching plugins ordered by priority.</returns>
    IEnumerable<IDisassemblyPlugin> FindPluginsForFormat(BinaryFormat format);

    /// <summary>
    /// Gets a plugin by its unique identifier.
    /// </summary>
    /// <param name="pluginId">The plugin identifier.</param>
    /// <returns>The plugin if found, null otherwise.</returns>
    IDisassemblyPlugin? GetPlugin(string pluginId);
}

/// <summary>
/// Facade service for disassembly operations. Automatically selects the best plugin.
/// </summary>
public interface IDisassemblyService
{
    /// <summary>
    /// Loads a binary and automatically selects the best plugin.
    /// </summary>
    /// <param name="stream">The binary stream to load.</param>
    /// <param name="preferredPluginId">Optional preferred plugin ID.</param>
    /// <returns>Binary information and the plugin used.</returns>
    (BinaryInfo Binary, IDisassemblyPlugin Plugin) LoadBinary(Stream stream, string? preferredPluginId = null);

    /// <summary>
    /// Loads a binary from bytes and automatically selects the best plugin.
    /// </summary>
    /// <param name="bytes">The binary data.</param>
    /// <param name="preferredPluginId">Optional preferred plugin ID.</param>
    /// <returns>Binary information and the plugin used.</returns>
    (BinaryInfo Binary, IDisassemblyPlugin Plugin) LoadBinary(ReadOnlySpan<byte> bytes, string? preferredPluginId = null);

    /// <summary>
    /// Gets the plugin registry.
    /// </summary>
    IDisassemblyPluginRegistry Registry { get; }
}