package gudusoft.gsqlparser.pp2.island;

import gudusoft.gsqlparser.ETokenType;
import gudusoft.gsqlparser.TSourceToken;
import gudusoft.gsqlparser.pp2.token.Pp2Token;
import gudusoft.gsqlparser.pp2.token.Pp2TokenStream;

import java.util.ArrayDeque;
import java.util.ArrayList;
import java.util.Arrays;
import java.util.Collections;
import java.util.Deque;
import java.util.HashSet;
import java.util.List;
import java.util.Locale;
import java.util.Set;

/**
 * Computes, for every token in a {@link Pp2TokenStream}, the lexical block
 * nesting depth and the kind of block it sits directly inside
 * (parenthesised group or {@code BEGIN ... END} block).
 *
 * <h2>Iterative, never recursive</h2>
 *
 * <p>Traversal uses an explicit {@link ArrayDeque} of open frames — never
 * recursion — so a 2000-deep nested input cannot {@code StackOverflowError}
 * (CLAUDE.md "CRITICAL: Iterative Traversal"; plan §10.1, §13/R3). The whole
 * pass is a single left-to-right walk: O(n) time, O(maxDepth) stack space.
 *
 * <h2>Read-only</h2>
 *
 * <p>The detector does not mutate any {@link Pp2Token}, its roles, or the
 * wrapped {@link TSourceToken}. It returns a {@link BlockScopeResult} side
 * structure indexed by token position (consistent with S18's match list).
 * S19 is not one of the designated role-annotator stages (S9/S21/S33), so it
 * deliberately keeps its output off the token.
 *
 * <h2>Depth convention</h2>
 *
 * <p>An opener ({@code (} or {@code BEGIN}) and its matching closer
 * ({@code )} or {@code END}) both report the <i>enclosing</i> depth; tokens
 * strictly between them report enclosing depth + 1. A token's
 * {@link BlockKind} is the kind of the frame it belongs to at that depth
 * ({@link BlockKind#NONE} at depth 0).
 *
 * <h2>BEGIN/END handling</h2>
 *
 * <p>{@code BEGIN} pushes a {@link BlockKind#BEGIN_END} frame. An <i>unqualified</i>
 * {@code END} (not immediately followed by {@code IF/LOOP/WHILE/REPEAT/FOR/CASE})
 * pops the top {@code BEGIN_END} frame. Qualified ends ({@code END IF}, etc.)
 * close inner constructs that this detector does not track, so they do not pop
 * the block frame — mirroring {@code StatementBoundaryDetector}. {@code CASE}
 * blocks are out of S19 scope (handled by the S27 layout rules); mixing a bare
 * {@code CASE ... END} inside a {@code BEGIN} block is a known limitation.
 *
 * <p>Plan reference: §7.3/S19, §7.4/S19, §10.1, §13/R3.
 */
public final class BlockScopeDetector {

    /** Keywords that, immediately after {@code END}, mark a qualified end. */
    private static final Set<String> END_QUALIFIERS;
    static {
        Set<String> q = new HashSet<String>(Arrays.asList(
            "IF", "LOOP", "WHILE", "REPEAT", "FOR", "CASE"));
        END_QUALIFIERS = Collections.unmodifiableSet(q);
    }

    /**
     * Annotate block depth + kind for every token in {@code stream}.
     *
     * @param stream the token stream; must not be null
     * @return a {@link BlockScopeResult} indexed by token position; never null
     * @throws NullPointerException if {@code stream} is null
     */
    public BlockScopeResult detect(Pp2TokenStream stream) {
        if (stream == null) throw new NullPointerException("stream");

        int n = stream.size();
        int[] depth = new int[n];
        BlockKind[] kind = new BlockKind[n];

        Deque<Frame> stack = new ArrayDeque<Frame>();
        List<BlockScope> scopes = new ArrayList<BlockScope>();
        int maxDepth = 0;

        for (int i = 0; i < n; i++) {
            Pp2Token t = stream.get(i);
            TSourceToken st = t.getSourceToken();
            ETokenType type = st.tokentype;
            String text = t.getText();

            if (type == ETokenType.ttleftparenthesis) {
                // Opener belongs to the enclosing scope, then we descend.
                record(depth, kind, i, stack);
                stack.push(new Frame(BlockKind.PAREN, i));
            } else if (type == ETokenType.ttrightparenthesis) {
                // Closer belongs to the enclosing scope: pop first (if matching).
                if (!stack.isEmpty() && stack.peek().kind == BlockKind.PAREN) {
                    Frame f = stack.pop();
                    scopes.add(new BlockScope(f.kind, f.openIndex, i, stack.size()));
                }
                record(depth, kind, i, stack);
            } else if (isKeyword(type, text, "BEGIN")) {
                record(depth, kind, i, stack);
                stack.push(new Frame(BlockKind.BEGIN_END, i));
            } else if (isKeyword(type, text, "END") && !isQualifiedEnd(stream, i)) {
                if (!stack.isEmpty() && stack.peek().kind == BlockKind.BEGIN_END) {
                    Frame f = stack.pop();
                    scopes.add(new BlockScope(f.kind, f.openIndex, i, stack.size()));
                }
                record(depth, kind, i, stack);
            } else {
                record(depth, kind, i, stack);
            }

            if (depth[i] > maxDepth) maxDepth = depth[i];
        }

        // Any frames still open at EOF are unclosed (incomplete) blocks.
        int unclosed = stack.size();
        while (!stack.isEmpty()) {
            Frame f = stack.pop();
            scopes.add(new BlockScope(f.kind, f.openIndex, -1, stack.size()));
        }

        return new BlockScopeResult(depth, kind, maxDepth, unclosed,
            Collections.unmodifiableList(scopes));
    }

    /** Record token i's depth+kind from the current stack state (after open/close). */
    private static void record(int[] depth, BlockKind[] kind, int i, Deque<Frame> stack) {
        depth[i] = stack.size();
        kind[i] = stack.isEmpty() ? BlockKind.NONE : stack.peek().kind;
    }

    private static boolean isKeyword(ETokenType type, String text, String upper) {
        return type == ETokenType.ttkeyword
            && text != null
            && text.toUpperCase(Locale.ROOT).equals(upper);
    }

    /**
     * True if the END at index {@code i} is followed by a qualifier keyword,
     * skipping any intervening comment tokens (e.g. {@code END /*c*&#47; IF}).
     * Comments are first-class tokens in the stream, so a naive
     * {@code i + 1} check would misclassify {@code END &lt;comment&gt; IF} as
     * unqualified and pop the block prematurely.
     */
    private static boolean isQualifiedEnd(Pp2TokenStream stream, int i) {
        int j = nextSolidIndex(stream, i);
        if (j < 0) return false;
        Pp2Token next = stream.get(j);
        if (next.getSourceToken().tokentype != ETokenType.ttkeyword) return false;
        String nextText = next.getText();
        if (nextText == null) return false;
        return END_QUALIFIERS.contains(nextText.toUpperCase(Locale.ROOT));
    }

    /** Index of the first non-comment token after {@code from}, or -1 if none. */
    private static int nextSolidIndex(Pp2TokenStream stream, int from) {
        for (int j = from + 1; j < stream.size(); j++) {
            if (!isComment(stream.get(j).getSourceToken().tokentype)) return j;
        }
        return -1;
    }

    private static boolean isComment(ETokenType type) {
        return type == ETokenType.ttsimplecomment
            || type == ETokenType.ttbracketedcomment
            || type == ETokenType.ttCPPComment;
    }

    /** A single open block frame, kept on the explicit traversal stack. */
    private static final class Frame {
        final BlockKind kind;
        final int openIndex;
        Frame(BlockKind kind, int openIndex) {
            this.kind = kind;
            this.openIndex = openIndex;
        }
    }

    /**
     * Per-token block depth + kind, plus the list of detected scopes. Indexed
     * by the same token positions as the source {@link Pp2TokenStream}.
     */
    public static final class BlockScopeResult {
        private final int[] depth;
        private final BlockKind[] kind;
        private final int maxDepth;
        private final int unclosedCount;
        private final List<BlockScope> scopes;

        BlockScopeResult(int[] depth, BlockKind[] kind, int maxDepth,
                         int unclosedCount, List<BlockScope> scopes) {
            this.depth = depth;
            this.kind = kind;
            this.maxDepth = maxDepth;
            this.unclosedCount = unclosedCount;
            this.scopes = scopes;
        }

        /** Number of tokens covered. */
        public int size() { return depth.length; }

        /** Block nesting depth at token {@code index} (0 = top level). */
        public int depthAt(int index) { return depth[index]; }

        /** Kind of block the token at {@code index} sits directly inside. */
        public BlockKind kindAt(int index) { return kind[index]; }

        /** Maximum nesting depth observed across the stream. */
        public int getMaxDepth() { return maxDepth; }

        /** Number of frames still open at end of input (unbalanced openers). */
        public int getUnclosedCount() { return unclosedCount; }

        /**
         * All detected scopes, in close order (then unclosed frames). Each
         * carries its opener index, closer index ({@code -1} if never closed),
         * kind, and the enclosing depth at which it sits.
         */
        public List<BlockScope> getScopes() { return scopes; }
    }

    /** An immutable detected block span. */
    public static final class BlockScope {
        private final BlockKind kind;
        private final int openIndex;
        private final int closeIndex;   // -1 if unclosed
        private final int enclosingDepth;

        BlockScope(BlockKind kind, int openIndex, int closeIndex, int enclosingDepth) {
            this.kind = kind;
            this.openIndex = openIndex;
            this.closeIndex = closeIndex;
            this.enclosingDepth = enclosingDepth;
        }

        public BlockKind getKind() { return kind; }
        public int getOpenIndex() { return openIndex; }
        public int getCloseIndex() { return closeIndex; }
        public boolean isClosed() { return closeIndex >= 0; }
        public int getEnclosingDepth() { return enclosingDepth; }

        @Override
        public String toString() {
            return "BlockScope[" + kind + " open=" + openIndex
                + " close=" + closeIndex + " depth=" + enclosingDepth + "]";
        }
    }
}