package de.gecheckt.pdf.umbenenner.application.validation.technicaltest;

/**
 * Outbound-Port für technische Pfad- und Dateisystemprüfungen.
 * <p>
 * Dieser Port ist <strong>ausschließlich lesend</strong>. Er prüft den Zustand von Pfaden,
 * ohne Dateien, Ordner oder andere Ressourcen anzulegen, zu verändern oder zu löschen.
 * Schreibende Korrekturen sind über {@link ResourceCreationPort} zu initiieren.
 * <p>
 * <strong>Pfad-Konvention:</strong> Alle Pfade werden als {@code String} übergeben, analog
 * zur Konvention der übrigen Outbound-Ports dieses Projekts (z. B. {@code TargetFolderPort}).
 * Der Adapter-Out ist für die Konvertierung in plattformspezifische Pfadobjekte zuständig.
 * <p>
 * <strong>Windows- und Netzlaufwerke:</strong> Implementierungen müssen gemappte
 * Laufwerksbuchstaben wie {@code S:\} oder {@code H:\} im Windows-Kontext ausdrücklich
 * akzeptieren. Solche Pfade dürfen nicht allein deshalb abgelehnt werden, weil dahinter
 * technisch ein UNC-Pfad stehen könnte.
 * <p>
 * <strong>Fehlerbehandlung:</strong> Implementierungen werfen keine geprüften oder
 * ungeprüften Ausnahmen für erwartete Fehlerbedingungen (Pfad nicht vorhanden,
 * keine Leseberechtigung). Alle solchen Zustände werden als {@code boolean}-Ergebnis
 * oder über separate Methoden kommuniziert.
 */
public interface PathCheckPort {

    /**
     * Prüft, ob der angegebene Pfad auf einen vorhandenen, lesbaren Ordner zeigt.
     *
     * @param path  zu prüfender Pfad als String; darf nicht {@code null} oder leer sein
     * @return {@code true} wenn der Ordner existiert und gelesen werden kann
     */
    boolean isDirectoryReadable(String path);

    /**
     * Prüft, ob der angegebene Pfad auf einen vorhandenen, schreibbaren Ordner zeigt
     * oder ob dieser Ordner technisch anlegbar wäre.
     * <p>
     * Gibt {@code true} zurück, wenn:
     * <ul>
     *   <li>der Ordner existiert und schreibbar ist, oder</li>
     *   <li>der Ordner noch nicht existiert, aber sein Elternpfad erreichbar und
     *       schreibbar ist (anlegbar).</li>
     * </ul>
     *
     * @param path  zu prüfender Pfad als String; darf nicht {@code null} oder leer sein
     * @return {@code true} wenn der Ordner vorhanden und schreibbar oder anlegbar ist
     */
    boolean isDirectoryWritableOrCreatable(String path);

    /**
     * Prüft, ob der angegebene Pfad auf eine vorhandene, lesbare Datei zeigt.
     *
     * @param path  zu prüfender Pfad als String; darf nicht {@code null} oder leer sein
     * @return {@code true} wenn die Datei existiert und gelesen werden kann
     */
    boolean isFileReadable(String path);

    /**
     * Prüft, ob der angegebene Pfad als SQLite-Datenbankpfad technisch nutzbar ist.
     * <p>
     * Gibt {@code true} zurück, wenn:
     * <ul>
     *   <li>die Datei existiert und les- und schreibbar ist, oder</li>
     *   <li>die Datei noch nicht existiert, aber ihr übergeordneter Ordner vorhanden
     *       und schreibbar ist (Datei wäre anlegbar).</li>
     * </ul>
     *
     * @param path  zu prüfender Pfad als String; darf nicht {@code null} oder leer sein
     * @return {@code true} wenn der SQLite-Pfad nutzbar oder anlegbar ist
     */
    boolean isSqlitePathUsable(String path);
}
