package gudusoft.gsqlparser.pp2.island;

import gudusoft.gsqlparser.EDbVendor;
import gudusoft.gsqlparser.pp2.island.MultiWordKeywordTable.Phrase;
import gudusoft.gsqlparser.pp2.token.Pp2Token;
import gudusoft.gsqlparser.pp2.token.Pp2TokenStream;

import java.util.ArrayList;
import java.util.Collections;
import java.util.List;

/**
 * Identifies runs of consecutive tokens that form a multi-word SQL keyword
 * (e.g. {@code LEFT OUTER JOIN}, {@code UNION ALL}, {@code GROUP BY}) so the
 * lexical island pipeline can treat each run as a single keyword unit.
 *
 * <h2>What it does and does NOT do</h2>
 *
 * <p>The merger is <b>read-only</b>: it returns a list of {@link Match}
 * spans and does not mutate any {@link Pp2Token} or its roles. (Role mutation
 * is reserved for the designated annotator stages — S9 zone detector, S21
 * clause annotator, S33 overlay — not this slice.) Later pipeline stages
 * consume the match list to know which token indices belong to one keyword.
 *
 * <h2>Matching rules</h2>
 *
 * <ul>
 *   <li><b>Allowlist, not word-count.</b> Only phrases present in
 *       {@link MultiWordKeywordTable} merge. {@code GROUP BY} merges;
 *       {@code LEFT JOIN} does not (only the three-word {@code LEFT OUTER JOIN}
 *       form is in the table).</li>
 *   <li><b>Left-to-right, longest-match-at-each-position, non-overlapping.</b>
 *       The scan walks tokens in source order; at each position the longest
 *       applicable phrase wins and its tokens are skipped. This is a local
 *       (per-position) greedy match, not a global longest-set optimisation —
 *       it mirrors the Delphi {@code TSQLion} lexical scan. The curated
 *       {@link MultiWordKeywordTable} allowlist contains no phrases where an
 *       earlier shorter match would preclude a later longer one, so the two
 *       agree here. If a future table introduces such overlaps, revisit this
 *       to a candidate-generate-then-select-by-length strategy.</li>
 *   <li><b>Directly consecutive tokens, case-insensitive text.</b> A comment
 *       or any other token between two phrase words breaks the match (its text
 *       will not equal the expected keyword word, so it naturally fails). Quoted
 *       identifiers and string literals never match because their text carries
 *       the surrounding quotes.</li>
 * </ul>
 *
 * <p>Plan reference: §7.3/S18, §7.4/S18.
 */
public final class MultiWordKeywordMerger {

    /**
     * Find all multi-word keyword spans in {@code stream} for {@code vendor}.
     *
     * @param stream the token stream to scan; must not be null
     * @param vendor the dialect whose phrase table to use; must not be null
     * @return an immutable, source-ordered, non-overlapping list of matches
     *         (possibly empty); never null
     * @throws NullPointerException if {@code stream} or {@code vendor} is null
     */
    public List<Match> findMatches(Pp2TokenStream stream, EDbVendor vendor) {
        if (stream == null) throw new NullPointerException("stream");
        if (vendor == null) throw new NullPointerException("vendor");

        List<Phrase> phrases = MultiWordKeywordTable.forVendor(vendor); // longest-first
        if (phrases.isEmpty() || stream.isEmpty()) {
            return Collections.emptyList();
        }

        List<Match> matches = new ArrayList<Match>();
        int n = stream.size();
        int i = 0;
        while (i < n) {
            Phrase hit = longestPhraseAt(stream, i, phrases);
            if (hit != null) {
                int end = i + hit.getWords().size() - 1;
                matches.add(new Match(i, end, hit.getCanonical()));
                i = end + 1; // non-overlapping: skip the consumed run
            } else {
                i++;
            }
        }
        return Collections.unmodifiableList(matches);
    }

    /**
     * The longest phrase that matches starting exactly at {@code start}, or
     * {@code null} if none does. {@code phrases} is assumed longest-first, so
     * the first match wins.
     */
    private static Phrase longestPhraseAt(Pp2TokenStream stream, int start,
                                          List<Phrase> phrases) {
        for (Phrase p : phrases) {
            if (matchesAt(stream, start, p)) return p;
        }
        return null;
    }

    /** True iff each phrase word equals (case-insensitive) the consecutive token text. */
    private static boolean matchesAt(Pp2TokenStream stream, int start, Phrase phrase) {
        List<String> words = phrase.getWords();
        int end = start + words.size();
        if (end > stream.size()) return false;
        for (int k = 0; k < words.size(); k++) {
            Pp2Token t = stream.get(start + k);
            String text = t.getText();
            if (text == null || !text.equalsIgnoreCase(words.get(k))) {
                return false;
            }
        }
        return true;
    }

    /**
     * An immutable multi-word keyword span over a {@link Pp2TokenStream}:
     * the inclusive token-index range and the canonical upper-cased phrase.
     */
    public static final class Match {
        private final int startIndex;       // inclusive
        private final int endIndex;         // inclusive
        private final String canonical;

        public Match(int startIndex, int endIndex, String canonical) {
            if (startIndex < 0) {
                throw new IllegalArgumentException("startIndex < 0: " + startIndex);
            }
            if (endIndex < startIndex) {
                throw new IllegalArgumentException(
                    "endIndex < startIndex: " + endIndex + " < " + startIndex);
            }
            if (canonical == null) throw new NullPointerException("canonical");
            this.startIndex = startIndex;
            this.endIndex = endIndex;
            this.canonical = canonical;
        }

        /** First token index of the phrase (inclusive). */
        public int getStartIndex() { return startIndex; }

        /** Last token index of the phrase (inclusive). */
        public int getEndIndex() { return endIndex; }

        /** Number of tokens the phrase spans. */
        public int getLength() { return endIndex - startIndex + 1; }

        /** Upper-cased canonical phrase, e.g. {@code "LEFT OUTER JOIN"}. */
        public String getCanonical() { return canonical; }

        @Override
        public String toString() {
            return "Match[" + startIndex + ".." + endIndex + " " + canonical + "]";
        }
    }
}