using System.Collections.Immutable;

namespace StellaOps.Scanner.EntryTrace;

/// <summary>
/// Represents a layered read-only filesystem snapshot built from container layers.
/// </summary>
public interface IRootFileSystem
{
    /// <summary>
    /// Attempts to resolve an executable by name using the provided PATH entries.
    /// </summary>
    bool TryResolveExecutable(string name, IReadOnlyList<string> searchPaths, out RootFileDescriptor descriptor);

    /// <summary>
    /// Attempts to read the contents of a file as UTF-8 text.
    /// </summary>
    bool TryReadAllText(string path, out RootFileDescriptor descriptor, out string content);

    /// <summary>
    /// Returns descriptors for entries contained within a directory.
    /// </summary>
    ImmutableArray<RootFileDescriptor> EnumerateDirectory(string path);

    /// <summary>
    /// Checks whether a directory exists.
    /// </summary>
    bool DirectoryExists(string path);
}

/// <summary>
/// Describes a file discovered within the layered filesystem.
/// </summary>
public sealed record RootFileDescriptor(
    string Path,
    string? LayerDigest,
    bool IsExecutable,
    bool IsDirectory,
    string? ShebangInterpreter);