// <copyright file="IFacet.cs" company="StellaOps">
// Copyright (c) StellaOps. Licensed under BUSL-1.1.
// </copyright>

namespace StellaOps.Facet;

/// <summary>
/// Represents a trackable slice of an image.
/// </summary>
/// <remarks>
/// <para>
/// A facet defines a logical grouping of files within a container image
/// that can be tracked independently for sealing and drift detection.
/// </para>
/// <para>
/// Examples of facets: OS packages, language dependencies, binaries, config files.
/// </para>
/// </remarks>
public interface IFacet
{
    /// <summary>
    /// Gets the unique identifier for this facet type.
    /// </summary>
    /// <remarks>
    /// Format: "{category}-{specifics}" e.g., "os-packages-dpkg", "lang-deps-npm".
    /// </remarks>
    string FacetId { get; }

    /// <summary>
    /// Gets the human-readable name.
    /// </summary>
    string Name { get; }

    /// <summary>
    /// Gets the facet category for grouping.
    /// </summary>
    FacetCategory Category { get; }

    /// <summary>
    /// Gets the glob patterns or path selectors for files in this facet.
    /// </summary>
    /// <remarks>
    /// <para>Selectors support:</para>
    /// <list type="bullet">
    /// <item><description>Glob patterns: "**/*.json", "/usr/bin/*"</description></item>
    /// <item><description>Exact paths: "/var/lib/dpkg/status"</description></item>
    /// <item><description>Directory patterns: "/etc/**"</description></item>
    /// </list>
    /// </remarks>
    IReadOnlyList<string> Selectors { get; }

    /// <summary>
    /// Gets the priority for conflict resolution when files match multiple facets.
    /// </summary>
    /// <remarks>
    /// Lower values = higher priority. A file matching multiple facets
    /// will be assigned to the facet with the lowest priority value.
    /// </remarks>
    int Priority { get; }
}