<?php
/**
 * SeekQuarry/Yioop --
 * Open Source Pure PHP Search Engine, Crawler, and Indexer
 *
 * Copyright (C) 2009 - 2026  Chris Pollett chris@pollett.org
 *
 * LICENSE:
 *
 * This program is free software: you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation, either version 3 of the License, or
 * (at your option) any later version.
 *
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License
 * along with this program.  If not, see <https://www.gnu.org/licenses/>.
 *
 * END LICENSE
 *
 * @author Chris Pollett chris@pollett.org
 * @license https://www.gnu.org/licenses/ GPL3
 * @link https://www.seekquarry.com/
 * @copyright 2009 - 2026
 * @filesource
 */
namespace seekquarry\yioop\tests;

use seekquarry\yioop\library\mail\ImapListing;
use seekquarry\yioop\library\UnitTest;

/**
 * Unit tests for ImapListing, the socket-free decision and shaping
 * logic behind a mailbox view. Each case checks one rule that keeps a
 * folder listing correct, fast, or resilient, with no live mail
 * server needed.
 *
 * @author Chris Pollett
 */
class ImapListingTest extends UnitTest
{
    /**
     * No setUp needed; every method under test is a pure static
     */
    public function setUp()
    {
    }
    /**
     * No tearDown
     */
    public function tearDown()
    {
    }
    /**
     * searchCriteria should return ALL when nothing narrows the view,
     * stack the unread and flagged toggles as space-separated terms,
     * and turn a free-text term into an OR over subject and sender
     * with the term safely quoted.
     */
    public function searchCriteriaTestCase()
    {
        $this->assertEqual('ALL',
            ImapListing::searchCriteria('', false, false),
            "no filter and no toggles matches everything");
        $this->assertEqual('UNSEEN',
            ImapListing::searchCriteria('', true, false),
            "unread-only becomes UNSEEN");
        $this->assertEqual('FLAGGED',
            ImapListing::searchCriteria('', false, true),
            "flagged-only becomes FLAGGED");
        $this->assertEqual('UNSEEN FLAGGED',
            ImapListing::searchCriteria('', true, true),
            "both toggles stack as space-separated AND terms");
        $this->assertEqual('OR SUBJECT "hi" FROM "hi"',
            ImapListing::searchCriteria('hi', false, false),
            "a term searches subject or sender");
        $this->assertEqual(
            'UNSEEN OR SUBJECT "hi" FROM "hi"',
            ImapListing::searchCriteria('hi', true, false),
            "toggle and term combine");
        $this->assertEqual(
            'OR SUBJECT "a\\"b" FROM "a\\"b"',
            ImapListing::searchCriteria('a"b', false, false),
            "a quote in the term is escaped so it cannot break out");
    }
    /**
     * sortSignature should give each distinct sort-and-toggle
     * combination its own tag so cached orderings do not collide.
     */
    public function sortSignatureTestCase()
    {
        $this->assertEqual('date',
            ImapListing::sortSignature(['key' => 'date',
            'reverse' => false], false, false),
            "plain date sort");
        $this->assertEqual('date-rev',
            ImapListing::sortSignature(['key' => 'date',
            'reverse' => true], false, false),
            "reversed date sort is distinct");
        $this->assertEqual('subject-unread-flagged',
            ImapListing::sortSignature(['key' => 'subject',
            'reverse' => false], true, true),
            "key and both toggles all appear in the tag");
    }
    /**
     * serverSortPlan should ask for no SORT in the common newest-
     * first-by-date case and otherwise return the exact SORT
     * arguments, getting the per-key direction right so date and the
     * text fields each come out the way a reader expects.
     */
    public function serverSortPlanTestCase()
    {
        $this->assertEqual(['mode' => 'search'],
            ImapListing::serverSortPlan(['key' => 'date',
            'reverse' => false]),
            "newest-first date needs no SORT command");
        $this->assertEqual(['mode' => 'sort', 'args' => 'DATE'],
            ImapListing::serverSortPlan(['key' => 'date',
            'reverse' => true]),
            "oldest-first date sorts ascending with no REVERSE");
        $this->assertEqual(['mode' => 'sort', 'args' => 'SUBJECT'],
            ImapListing::serverSortPlan(['key' => 'subject',
            'reverse' => false]),
            "A-to-Z subject sorts ascending with no REVERSE");
        $this->assertEqual(
            ['mode' => 'sort', 'args' => 'REVERSE SUBJECT'],
            ImapListing::serverSortPlan(['key' => 'subject',
            'reverse' => true]),
            "Z-to-A subject asks the server to REVERSE");
        $this->assertEqual(['mode' => 'sort', 'args' => 'FROM'],
            ImapListing::serverSortPlan(['key' => 'from',
            'reverse' => false]),
            "A-to-Z sender sorts ascending with no REVERSE");
        $this->assertEqual(
            ['mode' => 'sort', 'args' => 'REVERSE FROM'],
            ImapListing::serverSortPlan(['key' => 'from',
            'reverse' => true]),
            "Z-to-A sender asks the server to REVERSE");
    }
    /**
     * fallbackDateOrder should treat sequence numbers as arrival
     * order, returning newest-first by default and oldest-first when
     * the view asks for it.
     */
    public function fallbackDateOrderTestCase()
    {
        $this->assertEqual([3, 2, 1],
            ImapListing::fallbackDateOrder([1, 2, 3], false),
            "default is newest-first (highest sequence first)");
        $this->assertEqual([1, 2, 3],
            ImapListing::fallbackDateOrder([1, 2, 3], true),
            "reverse keeps oldest-first order");
    }
    /**
     * fallbackFieldOrder should order by the chosen header value
     * case-insensitively, break ties by sequence number for a stable
     * result, use the sender display name for the from key, and flip
     * the whole order when reversed.
     */
    public function fallbackFieldOrderTestCase()
    {
        $values = [1 => "Banana", 2 => "apple", 3 => "Cherry"];
        $this->assertEqual([2, 1, 3],
            ImapListing::fallbackFieldOrder([1, 2, 3], $values,
            'subject', false),
            "case-insensitive A-to-Z by subject");
        $this->assertEqual([3, 1, 2],
            ImapListing::fallbackFieldOrder([1, 2, 3], $values,
            'subject', true),
            "reverse gives Z-to-A");
        $tie = [5 => "same", 2 => "same", 9 => "same"];
        $this->assertEqual([2, 5, 9],
            ImapListing::fallbackFieldOrder([5, 2, 9], $tie,
            'subject', false),
            "equal values fall back to sequence-number order");
        $from = [1 => '"Zara Young" <zara@example.com>',
            2 => 'Abe <abe@example.com>'];
        $this->assertEqual([2, 1],
            ImapListing::fallbackFieldOrder([1, 2], $from, 'from',
            false),
            "from sort compares the display name, not the address");
    }
    /**
     * extractFromName should return a quoted or unquoted display
     * name when present and otherwise fall back to the local part of
     * the address.
     */
    public function extractFromNameTestCase()
    {
        $this->assertEqual('Ada Lovelace',
            ImapListing::extractFromName(
            '"Ada Lovelace" <ada@example.com>'),
            "quoted display name is unwrapped");
        $this->assertEqual('Bob',
            ImapListing::extractFromName('Bob <bob@example.com>'),
            "unquoted display name is returned");
        $this->assertEqual('carol',
            ImapListing::extractFromName('carol@example.com'),
            "bare address falls back to the local part");
        $this->assertEqual('dave',
            ImapListing::extractFromName('<dave@example.com>'),
            "angle-bracketed bare address falls back to local part");
        $this->assertEqual('',
            ImapListing::extractFromName('   '),
            "blank input yields the empty string");
    }
    /**
     * The batch-size policy should start modest and capped by the
     * total, double on each success up to the amount still wanted,
     * and halve on failure without dropping below one.
     */
    public function batchPolicyTestCase()
    {
        $this->assertEqual(0, ImapListing::initialBatch(0),
            "no messages means a zero first batch");
        $this->assertEqual(10, ImapListing::initialBatch(10),
            "a small total is taken whole");
        $this->assertEqual(25, ImapListing::initialBatch(100),
            "a large total is capped at the initial batch size");
        $this->assertEqual(2, ImapListing::growBatch(100, 1),
            "after one success the batch is two");
        $this->assertEqual(8, ImapListing::growBatch(100, 3),
            "the batch doubles with the success streak");
        $this->assertEqual(5, ImapListing::growBatch(5, 3),
            "growth never exceeds the number still wanted");
        $this->assertEqual(5, ImapListing::shrinkBatch(10),
            "a failed batch is halved");
        $this->assertEqual(1, ImapListing::shrinkBatch(3),
            "halving rounds down");
        $this->assertEqual(1, ImapListing::shrinkBatch(1),
            "the batch never drops below one");
    }
    /**
     * orderBySequence should return fetched messages in the requested
     * order and quietly drop any sequence number that was never
     * gathered, leaving no holes.
     */
    public function orderBySequenceTestCase()
    {
        $by_seq = [3 => ['SEQ' => 3], 1 => ['SEQ' => 1]];
        $this->assertEqual(
            [['SEQ' => 1], ['SEQ' => 3]],
            ImapListing::orderBySequence($by_seq, [1, 2, 3]),
            "requested order kept; the missing seq 2 is dropped");
        $this->assertEqual([],
            ImapListing::orderBySequence([], [1, 2, 3]),
            "nothing gathered yields an empty list");
    }
    /**
     * placeholderRow should build a row shaped like a fetched message,
     * marked as a placeholder, carrying the passed-in subject text and
     * never doing a language lookup of its own.
     */
    public function placeholderRowTestCase()
    {
        $row = ImapListing::placeholderRow(7, "Unreadable message");
        $this->assertEqual(7, $row['SEQ'],
            "the sequence number is carried so the row can be placed");
        $this->assertEqual("Unreadable message", $row['SUBJECT'],
            "the caller-supplied subject text is used as-is");
        $this->assertTrue($row['IS_PLACEHOLDER'],
            "the row is marked as a placeholder");
        $this->assertEqual(0, $row['UID'],
            "there is no real message, so the UID is zero");
    }
}
