package gudusoft.gsqlparser.pp2.region;

import gudusoft.gsqlparser.TCustomSqlStatement;
import gudusoft.gsqlparser.TGSqlParser;
import gudusoft.gsqlparser.TStatementList;
import gudusoft.gsqlparser.TSyntaxError;

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

/**
 * Immutable per-region outcome produced by {@link ParseRecoveryEngine}.
 *
 * <p>The outcome carries one of three statuses:
 *
 * <ul>
 *   <li>{@link Status#AST_OK} — the region's source slice parsed cleanly.
 *       {@link #getStatement()} returns the AST root captured from the
 *       parser. The {@link #getSyntaxErrors()} list is empty.</li>
 *   <li>{@link Status#AST_ERROR} — parse failed (or was skipped by the
 *       {@code maxRegionParseChars} safety valve, or the parser threw).
 *       {@link #getStatement()} is {@code null}. {@link #getSyntaxErrors()}
 *       carries the parser's diagnostics (possibly empty if the engine
 *       could not capture them — e.g., after a {@code Throwable}). The
 *       optional {@link #getEngineNote()} field carries a short message
 *       describing why this region was marked {@code AST_ERROR} when the
 *       parser itself did not report a diagnostic (e.g., region too large,
 *       parser threw).</li>
 *   <li>{@link Status#TRIVIA} — the region contains no solid tokens (only
 *       whitespace and / or comments). No parse was attempted.
 *       {@link #getStatement()} is {@code null}, {@link #getSyntaxErrors()}
 *       is empty.</li>
 * </ul>
 *
 * <p><b>AST lifetime contract.</b> Every {@code AST_OK} outcome carries a
 * reference to the {@link TGSqlParser} that produced it. That parser owns the
 * captured AST (statement tree, source-token list, error list) and is the
 * input S13 ({@code GuardedAstDelegate}) and S16 ({@code Pp2Engine}) hand to
 * {@code FormatterFactory.pp(parser, opt)} via {@link #getParser()}.
 * Two scenarios:
 *
 * <ul>
 *   <li><b>{@link ParseRecoveryEngine#parseRegion(StatementRange) parseRegion}:</b>
 *       the parser is the pool's single instance. Its state is overwritten
 *       on the <i>next</i> {@code parseRegion} / {@code parseAll} call.
 *       Consume the AST <i>before</i> requesting the next region.</li>
 *   <li><b>{@link ParseRecoveryEngine#parseAll(List) parseAll}:</b> every
 *       {@code AST_OK} outcome carries a freshly-allocated parser
 *       dedicated to that region (the engine probes each range via the
 *       pool, and on success re-parses the slice into a new
 *       {@code TGSqlParser} so {@code parser.sqlstatements} holds exactly
 *       one statement). Outcomes are mutually valid: a caller may iterate
 *       the returned list in any order and consume each AST without
 *       invalidating the rest. The contract is broken by the next
 *       {@code parseAll} / {@code parseRegion} call on the same engine
 *       only for outcomes produced via {@code parseRegion} (which share
 *       the pool); {@code parseAll}'s dedicated parsers outlive the engine
 *       call.</li>
 * </ul>
 *
 * <p>Plan reference: §7.3/S12, §7.4/S12.
 */
public final class RegionParseOutcome {

    public enum Status {
        /** Parse succeeded; {@link #getStatement()} is non-null. */
        AST_OK,
        /** Parse failed, was skipped, or the parser threw. */
        AST_ERROR,
        /** Region contains no solid tokens. No parse was attempted. */
        TRIVIA
    }

    private final StatementRange range;
    private final Status status;
    private final String parsedSql;
    private final TCustomSqlStatement statement;     // nullable
    private final TGSqlParser parser;                // nullable; non-null iff AST_OK
    private final List<TSyntaxError> syntaxErrors;
    private final String engineNote;                 // nullable

    private RegionParseOutcome(StatementRange range,
                               Status status,
                               String parsedSql,
                               TCustomSqlStatement statement,
                               TGSqlParser parser,
                               List<TSyntaxError> syntaxErrors,
                               String engineNote) {
        if (range == null) throw new NullPointerException("range");
        if (status == null) throw new NullPointerException("status");
        if (parsedSql == null) throw new NullPointerException("parsedSql");
        this.range = range;
        this.status = status;
        this.parsedSql = parsedSql;
        this.statement = statement;
        this.parser = parser;
        // Defensive copy: callers (including ParseRecoveryEngine) often
        // pass the parser's live list; without a copy, a subsequent parse()
        // that mutates that list would silently change this outcome's
        // visible diagnostics.
        this.syntaxErrors = (syntaxErrors == null || syntaxErrors.isEmpty())
            ? Collections.<TSyntaxError>emptyList()
            : Collections.unmodifiableList(new ArrayList<TSyntaxError>(syntaxErrors));
        this.engineNote = engineNote;
    }

    /**
     * Build a successful outcome. The first statement of {@code stmts} is
     * captured as the AST root for this region; the caller's per-region parse
     * is expected to yield exactly one top-level statement, but the engine
     * tolerates parsers that wrap output in additional containers by reading
     * {@code stmts.get(0)} and ignoring extras. {@code stmts} may be
     * {@code null} or empty, in which case the outcome is treated as
     * {@code AST_ERROR} (parser claimed success but produced no statement).
     *
     * <p>{@code parser} is the {@link TGSqlParser} instance that produced the
     * statement. It is exposed via {@link #getParser()} for S13's
     * {@code GuardedAstDelegate} which feeds it to
     * {@code FormatterFactory.pp(parser, opt)}.
     */
    static RegionParseOutcome astOk(StatementRange range, String parsedSql,
                                    TStatementList stmts, TGSqlParser parser) {
        int stmtCount = (stmts == null) ? 0 : stmts.size();
        if (stmtCount == 0) {
            return new RegionParseOutcome(range, Status.AST_ERROR, parsedSql,
                null, null, null,
                "parser reported success but produced no statement");
        }
        if (stmtCount > 1) {
            // Defensive: S13 hands the outcome's parser to
            // FormatterFactory.pp(parser, opt) which iterates EVERY
            // statement in parser.sqlstatements. If a single region's
            // source slice somehow parses into multiple top-level
            // statements (e.g. the boundary detector's known DECLARE-clause
            // limitation per the S11 resume), routing this through the AST
            // path would render siblings the caller did not ask for. Force
            // the lexical fallback instead.
            return new RegionParseOutcome(range, Status.AST_ERROR, parsedSql,
                null, null, null,
                "region parsed into " + stmtCount + " statements; AST path "
                    + "expects exactly one — routing to lexical fallback");
        }
        if (parser == null) throw new NullPointerException("parser");
        return new RegionParseOutcome(range, Status.AST_OK, parsedSql,
            stmts.get(0), parser, null, null);
    }

    /**
     * Build an {@code AST_ERROR} outcome. Used by the engine for parse
     * failures and safety-valve skips; also useful to tests and downstream
     * stages that need to package a synthetic error outcome (e.g., a
     * region the boundary detector emitted but parsing was bypassed).
     *
     * <p>{@code errors} may be {@code null} or empty.
     */
    public static RegionParseOutcome astError(StatementRange range,
                                              String parsedSql,
                                              List<TSyntaxError> errors,
                                              String note) {
        return new RegionParseOutcome(range, Status.AST_ERROR, parsedSql,
            null, null, errors, note);
    }

    /**
     * Build a {@code TRIVIA} outcome (region with no solid tokens — only
     * whitespace and/or comments).
     */
    public static RegionParseOutcome trivia(StatementRange range,
                                            String parsedSql) {
        return new RegionParseOutcome(range, Status.TRIVIA, parsedSql,
            null, null, null, null);
    }

    public StatementRange getRange() { return range; }
    public Status getStatus() { return status; }

    /** The source text that was (or would have been) handed to the parser. */
    public String getParsedSql() { return parsedSql; }

    /**
     * The captured AST root for {@code AST_OK} outcomes; {@code null}
     * otherwise. See the class Javadoc for the AST lifetime contract.
     */
    public TCustomSqlStatement getStatement() { return statement; }

    /**
     * The {@link TGSqlParser} that produced the AST for this outcome.
     * Non-null only when {@link #getStatus()} is {@link Status#AST_OK};
     * {@code null} otherwise. See the class Javadoc for the lifetime
     * contract; in particular, after the next
     * {@link ParseRecoveryEngine#parseRegion(StatementRange)} or
     * {@link ParseRecoveryEngine#parseAll(List)} call the parser handed back
     * here may have been overwritten in place (for outcomes produced via
     * the pool) and must not be reused.
     */
    public TGSqlParser getParser() { return parser; }

    /** Immutable list of syntax errors. Empty for {@code AST_OK} and {@code TRIVIA}. */
    public List<TSyntaxError> getSyntaxErrors() { return syntaxErrors; }

    /**
     * Short engine-level note explaining the outcome when the parser itself
     * did not report a diagnostic. Examples: "region exceeds
     * maxRegionParseChars", "parser threw: NullPointerException".
     * {@code null} when not applicable.
     */
    public String getEngineNote() { return engineNote; }

    @Override
    public String toString() {
        return "RegionParseOutcome{" + status + " " + range
            + (statement != null ? " ast=" + statement.getClass().getSimpleName() : "")
            + " errs=" + syntaxErrors.size()
            + (engineNote != null ? " note='" + engineNote + "'" : "")
            + "}";
    }
}