package de.gecheckt.pdf.umbenenner.application.port.out;

import java.util.List;

import de.gecheckt.pdf.umbenenner.domain.model.SourceDocumentCandidate;

/**
 * Outbound port for loading PDF document candidates from the source folder.
 * <p>
 * This interface abstracts filesystem access, allowing the application layer
 * to remain independent of how candidates are discovered or retrieved.
 * <p>
 * Responsibilities of the implementing adapter:
 * <ul>
 *   <li>Scan the configured source folder</li>
 *   <li>Identify only PDF files (by extension or content type)</li>
 *   <li>Ignore non-PDF files and directories</li>
 *   <li>Return candidates in deterministic order (e.g., alphabetical by filename)</li>
 *   <li>Convert filesystem objects to {@link SourceDocumentCandidate} records</li>
 *   <li>Encapsulate all filesystem access details (no Path or File leakage)</li>
 * </ul>
 * <p>
 * Architecture note:
 * <ul>
 *   <li>The adapter implementation is the ONLY place where java.nio.file.Path or java.io.File appears</li>
 *   <li>The application never sees or handles raw filesystem objects</li>
 *   <li>This enforces the hexagonal boundary and allows easy adapter swapping (e.g., cloud storage)</li>
 * </ul>
 *
 */
public interface SourceDocumentCandidatesPort {

    /**
     * Loads all PDF candidates from the configured source folder.
     * <p>
     * Returns a list of candidates representing discovered PDF files.
     * The list is guaranteed to be in deterministic order to enable reproducible runs.
     * <p>
     * Non-goal: This method does NOT filter candidates by any fachlich criteria
     * (such as file size, corruption checks, or content validation).
     * It delivers raw candidates from the filesystem; fachlich evaluation happens later.
     *
     * @return a list of discovered PDF candidates in deterministic order (may be empty if no PDFs found)
     * @throws SourceDocumentAccessException if the source folder cannot be read or accessed
     * @see SourceDocumentCandidate
     */
    List<SourceDocumentCandidate> loadCandidates() throws SourceDocumentAccessException;
}
