package gudusoft.gsqlparser.pp2.engine;

import gudusoft.gsqlparser.EDbVendor;
import gudusoft.gsqlparser.TBaseType;
import gudusoft.gsqlparser.TGSqlParser;
import gudusoft.gsqlparser.TSourceTokenList;
import gudusoft.gsqlparser.pp.logger.PPLogger;
import gudusoft.gsqlparser.pp2.FormatDiagnostic;
import gudusoft.gsqlparser.pp2.FormatStatus;
import gudusoft.gsqlparser.pp2.Pp2FormatOptions;
import gudusoft.gsqlparser.pp2.Pp2FormatResult;
import gudusoft.gsqlparser.pp2.RendererId;
import gudusoft.gsqlparser.pp2.region.ParseRecoveryEngine;
import gudusoft.gsqlparser.pp2.region.RegionParseOutcome;
import gudusoft.gsqlparser.pp2.overlay.AstOverlayAnnotator;
import gudusoft.gsqlparser.pp2.region.StatementBoundaryDetector;
import gudusoft.gsqlparser.pp2.region.StatementRange;
import gudusoft.gsqlparser.pp2.render.ConservativeTokenRenderer;
import gudusoft.gsqlparser.pp2.render.GuardedAstDelegate;
import gudusoft.gsqlparser.pp2.render.LexicalIslandRenderer;
import gudusoft.gsqlparser.pp2.render.RegionAssembler;
import gudusoft.gsqlparser.pp2.render.RenderedRegion;
import gudusoft.gsqlparser.pp2.token.Pp2TokenStream;
import gudusoft.gsqlparser.pp2.token.Pp2TokenStreamBuilder;
import gudusoft.gsqlparser.pp2.token.SourceSpanLedger;
import gudusoft.gsqlparser.pp2.token.TokenEquivalence;
import gudusoft.gsqlparser.pp2.zone.ProtectedZoneDetector;

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

/**
 * Fault-tolerant SQL formatter engine — Phase-2 MVP orchestrator.
 *
 * <h2>Whole-document fast path (tried first)</h2>
 *
 * <p>Before any of the stages below, and unless
 * {@link Pp2FormatOptions#wholeDocumentFastPath} is switched off, the engine
 * parses the whole input and — if that succeeds — formats it with
 * {@code FormatterFactory.pp}, returning <b>pp's output unchanged</b> once it
 * passes the {@link TokenEquivalence} guard. So for SQL that parses, pp2 is a
 * call to pp plus a guard; the regional pipeline below exists for the input pp
 * cannot handle. See {@link #wholeDocumentFastPath(String, EDbVendor,
 * Pp2FormatOptions)}.
 *
 * <h2>Pipeline summary (regional path)</h2>
 *
 * <p>When the fast path does not apply, each
 * {@link #format(String, EDbVendor, Pp2FormatOptions)} call runs the
 * following stages in order:
 *
 * <ol>
 *   <li><b>Tokenize</b> — {@link TGSqlParser#tokenizeSqltext()} produces a
 *       raw {@link TSourceTokenList}.</li>
 *   <li><b>Token spine</b> — {@link Pp2TokenStreamBuilder} adapts the token
 *       list into a {@link Pp2TokenStream}: folds whitespace into
 *       {@code precedingBlanks} / {@code precedingLinebreaks} counts,
 *       preserves comments as first-class tokens.</li>
 *   <li><b>Ledger</b> — {@link SourceSpanLedger} records every byte of the
 *       original input so the assembler can restore inter-region trivia
 *       verbatim.</li>
 *   <li><b>Zone annotation</b> — {@link ProtectedZoneDetector} annotates
 *       {@code NO_FORMAT_ZONE}, {@code COMMENT_LINE}, {@code COMMENT_BLOCK},
 *       and template-placeholder roles onto the token stream.</li>
 *   <li><b>Boundary detection</b> — {@link StatementBoundaryDetector} walks
 *       the annotated stream and emits one {@link StatementRange} per
 *       statement.</li>
 *   <li><b>Parse recovery</b> — {@link ParseRecoveryEngine#parseAll(List)}
 *       attempts per-region parsing. Each outcome is tagged
 *       {@code AST_OK | AST_ERROR | TRIVIA}.</li>
 *   <li><b>Dispatch</b> — {@link EngineDispatch} routes each outcome to the
 *       appropriate renderer (plan §5.2 three-tier strategy):
 *       {@code AST_OK} → {@link GuardedAstDelegate}, which formats that
 *       region with {@code FormatterFactory.pp} as well (falling through on
 *       guard failure); {@code AST_ERROR} →
 *       {@link LexicalIslandRenderer}, then {@link ConservativeTokenRenderer};
 *       {@code TRIVIA} → passthrough.
 *       Each rendered text is wrapped in a {@link RenderedRegion}.</li>
 *   <li><b>Assembly</b> — {@link RegionAssembler} interleaves the rendered
 *       texts with the original inter-region trivia from the ledger,
 *       producing the final output string.</li>
 *   <li><b>Result</b> — a {@link Pp2FormatResult} carrying the assembled
 *       text, {@link FormatStatus}, per-region {@link Pp2FormatResult.Region}
 *       records, and all diagnostics accumulated across the pipeline.</li>
 * </ol>
 *
 * <h2>Defensive behaviour</h2>
 *
 * <p>The engine never throws for non-null inputs. Any {@link Throwable} that
 * escapes the pipeline — from the tokenizer, ledger builder, boundary
 * detector, or assembler — is caught, logged via {@link PPLogger}, and the
 * engine falls back to returning the original SQL unchanged with
 * {@link FormatStatus#FAILED} and a {@link FormatDiagnostic.Severity#FATAL}
 * diagnostic.
 *
 * <h2>Thread safety</h2>
 *
 * <p>The engine instance is stateless (all mutable objects are allocated per
 * {@code format} call). Concurrent calls with different inputs are safe. The
 * inner {@link ParseRecoveryEngine} allocates a fresh
 * {@link gudusoft.gsqlparser.pp2.region.ParserPool} per call.
 *
 * <p>Plan reference: §5.1, §7.3/S16, §7.4/S16, §10.4.
 */
public final class Pp2Engine {

    /**
     * Format the given SQL string using the supplied database vendor and
     * options. Never throws for non-null inputs.
     *
     * @param sql    the raw SQL to format; must not be null
     * @param vendor the database dialect; governs tokenization, keyword
     *               recognition, and boundary detection
     * @param opts   formatting options; must not be null
     * @return a {@link Pp2FormatResult} carrying the formatted text and
     *         per-region metadata; never null
     * @throws NullPointerException if any argument is null
     */
    public Pp2FormatResult format(String sql, EDbVendor vendor,
                                   Pp2FormatOptions opts) {
        if (sql == null) throw new NullPointerException("sql");
        if (vendor == null) throw new NullPointerException("vendor");
        if (opts == null) throw new NullPointerException("opts");

        // Trial-build size gate. The formatter is deliberately fault-tolerant
        // (parse failures degrade to verbatim output with a success status), so
        // without this explicit refusal an oversized input would be echoed back
        // as OK instead of rejected. Always false in full builds.
        if (gudusoft.gsqlparser.TrialInputGuard.checkText(sql).isRefused()) {
            List<FormatDiagnostic> diags = Collections.singletonList(
                new FormatDiagnostic(FormatDiagnostic.Severity.FATAL, 0, sql.length(),
                    TBaseType.trialSizeMessage()));
            return new Pp2FormatResult(sql, FormatStatus.FAILED,
                Collections.<Pp2FormatResult.Region>emptyList(), diags);
        }

        try {
            if (opts.wholeDocumentFastPath) {
                Pp2FormatResult whole = wholeDocumentFastPath(sql, vendor, opts);
                if (whole != null) return whole;
            }
            return formatInternal(sql, vendor, opts);
        } catch (Throwable t) {
            // Top-level safety net: if anything escaped the pipeline, return
            // the original SQL unchanged so the caller never gets an exception.
            PPLogger.error(t);
            PPLogger.info("Pp2Engine: unhandled throwable escaped pipeline; "
                + "returning original SQL unchanged. vendor=" + vendor
                + " sqlLen=" + sql.length());
            List<FormatDiagnostic> diags = Collections.singletonList(
                new FormatDiagnostic(FormatDiagnostic.Severity.FATAL, 0, sql.length(),
                    "Pp2Engine: pipeline threw " + t.getClass().getSimpleName()
                        + (t.getMessage() != null ? ": " + t.getMessage() : "")));
            return new Pp2FormatResult(sql, FormatStatus.FAILED,
                Collections.<Pp2FormatResult.Region>emptyList(), diags);
        }
    }

    /**
     * Whole-document fast path: when the input parses as a whole and
     * {@code FormatterFactory.pp} formats it with the same options without
     * changing a token, that text is the pp2 result ({@code OK}, one
     * {@code GUARDED_AST} region). The regional pipeline reparses statement
     * ranges independently and its reassembled text was not byte-identical to
     * whole-document pp on 60 of 1000 parseable corpus inputs.
     *
     * @return the result, or {@code null} when the regional pipeline must run
     */
    private static Pp2FormatResult wholeDocumentFastPath(String sql, EDbVendor vendor,
                                                         Pp2FormatOptions opts) {
        try {
            TGSqlParser parser = new TGSqlParser(vendor);
            parser.sqltext = sql;
            if (parser.parse() != 0 || parser.sqlstatements == null || parser.sqlstatements.size() == 0) {
                return null;
            }
            gudusoft.gsqlparser.pp.para.GFmtOpt option = opts.toGFmtOpt();
            // pp() fills this session's mediator and then drops it from the
            // registry; holding it here keeps its verdict readable.
            gudusoft.gsqlparser.pp.mediator.type.NameCaseMediator names =
                gudusoft.gsqlparser.pp.mediator.type.NameCaseMediator.isUsedBy(option)
                    ? gudusoft.gsqlparser.pp.mediator.MediatorFactory.getMediator(
                        gudusoft.gsqlparser.pp.mediator.type.NameCaseMediator.class, option.sessionId)
                    : null;
            String text = gudusoft.gsqlparser.pp.stmtformatter.FormatterFactory.pp(parser, option);
            if (text == null || text.isEmpty()) {
                return null;
            }
            if (!gudusoft.gsqlparser.pp2.token.TokenEquivalence.equalsModuloFormatting(sql, text, opts, vendor, true)) {
                PPLogger.info("Pp2Engine: whole-document pp output is not token-equivalent; using the regional pipeline. vendor="
                    + vendor + " sqlLen=" + sql.length());
                return null;
            }
            // one region per parsed statement, so the region list still describes the input
            List<Pp2FormatResult.Region> regions = new java.util.ArrayList<Pp2FormatResult.Region>();
            for (int i = 0; i < parser.sqlstatements.size(); i++) {
                gudusoft.gsqlparser.TCustomSqlStatement st = parser.sqlstatements.get(i);
                if (st == null || st.getStartToken() == null || st.getEndToken() == null) continue;
                int start = (int) Math.max(0, Math.min(sql.length(), st.getStartToken().offset));
                int end = (int) Math.max(start, Math.min(sql.length(),
                    gudusoft.gsqlparser.pp2.token.TokenCoverage.endOffset(st.getEndToken())));
                regions.add(new Pp2FormatResult.Region(start, end, RendererId.GUARDED_AST, FormatStatus.OK));
            }
            if (regions.isEmpty()) {
                regions.add(new Pp2FormatResult.Region(0, sql.length(), RendererId.GUARDED_AST, FormatStatus.OK));
            }
            return new Pp2FormatResult(text, FormatStatus.OK, regions,
                Collections.<FormatDiagnostic>emptyList(), true, names != null && names.isApplied());
        } catch (Throwable t) {
            PPLogger.info("Pp2Engine: whole-document pp threw " + t.getClass().getSimpleName()
                + "; using the regional pipeline. vendor=" + vendor + " sqlLen=" + sql.length());
            return null;
        }
    }

    private Pp2FormatResult formatInternal(String sql, EDbVendor vendor,
                                            Pp2FormatOptions opts) {
        // All collaborators are allocated per call so the no-shared-mutable-state
        // (and therefore thread-safety) guarantee holds unconditionally, even if
        // a detector later grows internal scratch/cache state.
        Pp2TokenStreamBuilder streamBuilder = new Pp2TokenStreamBuilder();
        StatementBoundaryDetector boundaryDetector = new StatementBoundaryDetector();
        ProtectedZoneDetector zoneDetector = new ProtectedZoneDetector();
        RegionAssembler assembler = new RegionAssembler(vendor);

        // Stage 1: tokenize.
        TGSqlParser parser = new TGSqlParser(vendor);
        parser.sqltext = sql;
        parser.tokenizeSqltext();
        TSourceTokenList tokenList = parser.getSourcetokenlist();

        // Stage 2: build token spine.
        Pp2TokenStreamBuilder.BuildResult buildResult = streamBuilder.build(tokenList);
        Pp2TokenStream stream = buildResult.getStream();

        // Stage 3: build source-span ledger (byte authority).
        SourceSpanLedger ledger = SourceSpanLedger.build(sql, tokenList);

        // Stage 4: annotate protected zones (NO_FORMAT_ZONE, comments, etc.).
        zoneDetector.annotate(stream);

        // Stage 5: detect statement boundaries.
        List<StatementRange> ranges = boundaryDetector.detect(stream, vendor);

        // Empty stream → no regions; return source unchanged.
        if (ranges.isEmpty()) {
            return new Pp2FormatResult(sql, FormatStatus.OK,
                Collections.<Pp2FormatResult.Region>emptyList(),
                new ArrayList<FormatDiagnostic>(ledger.getDiagnostics()));
        }

        // Stages 6+7 INTERLEAVED — parse and render each region in turn.
        //
        // Memory: an AST_OK region carries a live TGSqlParser (parse tables +
        // AST). Parsing every region up front (parseAll) and only then
        // rendering would keep N parsers alive simultaneously — on a script
        // with thousands of valid statements that exhausts the heap (root-caused
        // in S36: ~300KB/parser × N → OOM even at -Xmx2g). Interleaving keeps at
        // most ONE region's parser/AST live at a time: each region is parsed,
        // rendered, and then discarded before the next region's parse resets the
        // shared pool. This also removes the need to promote AST_OK outcomes to
        // a dedicated fresh parser (parseAll's strategy), cutting allocation
        // further. The rendered output is identical — the AST content a region
        // parses to is the same whichever parser instance holds it.
        ParseRecoveryEngine recovery = new ParseRecoveryEngine(
            vendor, sql, stream, opts);
        GuardedAstDelegate astDelegate = new GuardedAstDelegate(vendor);
        LexicalIslandRenderer lexicalIsland = new LexicalIslandRenderer(vendor);
        ConservativeTokenRenderer conservative = new ConservativeTokenRenderer();
        EngineDispatch dispatch = new EngineDispatch(astDelegate, lexicalIsland, conservative);

        List<RenderedRegion> renderedRegions = new ArrayList<RenderedRegion>(ranges.size());
        List<FormatDiagnostic> allDiags = new ArrayList<FormatDiagnostic>(ledger.getDiagnostics());
        List<Pp2FormatResult.Region> regionRecords =
            new ArrayList<Pp2FormatResult.Region>(ranges.size());

        // S33 AST overlay (v3 bridge): off by default. When enabled, annotate
        // each cleanly-parsed region's tokens with AST-derived roles. v2 does
        // not render from these roles, so this never changes output here — it
        // lands the annotation infrastructure a v3 renderer will consume.
        AstOverlayAnnotator overlay = opts.astOverlayEnabled
            ? new AstOverlayAnnotator() : null;

        for (StatementRange range : ranges) {
            RegionParseOutcome outcome = recovery.parseRegion(range);
            if (overlay != null) {
                applyAstOverlay(overlay, outcome, stream);
            }
            EngineDispatch.DispatchResult result = dispatch.dispatch(outcome, stream, opts);
            renderedRegions.add(new RenderedRegion(
                outcome.getRange(), result.text, result.rendererId));
            allDiags.addAll(result.diagnostics);
            regionRecords.add(toRegionRecord(outcome, result.rendererId));
            // outcome is dropped here; the next parseRegion() resets the pool,
            // freeing this region's parser/AST. At most one is ever live.
        }

        // Stage 8: assemble into final output.
        String assembled = assembler.assemble(renderedRegions, ledger, opts);

        // Stage 8b: the whole output must keep the input's tokens. Each AST or
        // island region was checked on its own text, but the conservative renderer
        // has no check, a vendor's tokenizer may have rewritten a token's text (so
        // a renderer that prints tokens prints the rewrite), and inserting a
        // newline between two statements that shared a physical line can, in
        // SQL*Plus-aware dialects, reclassify a following bare identifier as a
        // SQL*Plus command (ttidentifier -> ttsqlpluscmd). A statement-break
        // difference is undone with verbatim inter-region trivia, which is byte-
        // (and therefore token-) preserving; any other difference was made inside
        // a region, and an output that changes the input is never returned.
        boolean preserved = TokenEquivalence.equalsModuloFormatting(sql, assembled, opts, vendor, true);
        if (!preserved && opts.breakStatementsOnNewLine && renderedRegions.size() >= 2) {
            PPLogger.info("Pp2Engine: statement-break normalization altered the "
                + "token stream (vendor=" + vendor + "); falling back to verbatim "
                + "inter-region trivia to preserve content.");
            assembled = assembler.assemble(renderedRegions, ledger, opts, false);
            preserved = TokenEquivalence.equalsModuloFormatting(sql, assembled, opts, vendor, true);
        }
        if (!preserved) {
            PPLogger.info("Pp2Engine: the regions' output changes the input's tokens "
                + "(vendor=" + vendor + "); returning the input unchanged.");
            List<FormatDiagnostic> diags = new ArrayList<FormatDiagnostic>(allDiags);
            diags.add(new FormatDiagnostic(FormatDiagnostic.Severity.FATAL, 0, sql.length(),
                "Pp2Engine: the formatted regions change the input's tokens; the input is returned unchanged"));
            // no region's rendering is used
            return new Pp2FormatResult(sql, FormatStatus.FAILED,
                Collections.<Pp2FormatResult.Region>emptyList(), diags);
        }

        // Stage 9: compute overall status and build result.
        FormatStatus status = computeStatus(renderedRegions, allDiags);

        return new Pp2FormatResult(assembled, status, regionRecords, allDiags);
    }

    /**
     * Run the {@link AstOverlayAnnotator} on a single AST_OK region, stamping
     * AST-derived roles directly onto the engine's whole-script {@code stream}
     * (the tokens every renderer sees). The region was parsed from
     * {@code originalSql.substring(range.getStartOffset(), ...)}, so the region
     * AST's token offsets are region-relative; passing the range's start offset
     * as the adjustment translates them onto the absolute-offset stream.
     *
     * <p>Best-effort: any failure is logged and swallowed so the feature flag
     * can never break formatting. In v2 no renderer consumes these roles, so
     * this stamping has no effect on output — it is the v3 evolution seam.
     */
    private static void applyAstOverlay(AstOverlayAnnotator overlay,
                                        RegionParseOutcome outcome,
                                        Pp2TokenStream stream) {
        if (outcome.getStatus() != RegionParseOutcome.Status.AST_OK
            || outcome.getStatement() == null) {
            return;
        }
        try {
            overlay.annotate(outcome.getStatement(), stream,
                outcome.getRange().getStartOffset());
        } catch (Throwable t) {
            PPLogger.error(t);
            PPLogger.info("Pp2Engine: AST overlay annotation failed for region "
                + outcome.getRange() + "; continuing without overlay roles.");
        }
    }

    /**
     * Compute the overall {@link FormatStatus}:
     * <ul>
     *   <li>{@link FormatStatus#OK} — every region used {@link RendererId#GUARDED_AST};
     *       no diagnostics at WARNING or above.</li>
     *   <li>{@link FormatStatus#OK_WITH_RECOVERY} — at least one region used
     *       the conservative renderer, or at least one WARNING/ERROR diagnostic
     *       was emitted (but no FATAL).</li>
     *   <li>{@link FormatStatus#FAILED} — at least one FATAL diagnostic.</li>
     * </ul>
     */
    private static FormatStatus computeStatus(List<RenderedRegion> regions,
                                               List<FormatDiagnostic> diags) {
        for (FormatDiagnostic d : diags) {
            if (d.getSeverity() == FormatDiagnostic.Severity.FATAL) {
                return FormatStatus.FAILED;
            }
        }
        for (RenderedRegion r : regions) {
            if (isRecoveryRenderer(r.getRendererId())) {
                return FormatStatus.OK_WITH_RECOVERY;
            }
        }
        for (FormatDiagnostic d : diags) {
            if (d.getSeverity() == FormatDiagnostic.Severity.WARNING
                || d.getSeverity() == FormatDiagnostic.Severity.ERROR) {
                return FormatStatus.OK_WITH_RECOVERY;
            }
        }
        return FormatStatus.OK;
    }

    /** A region was recovered (not the clean AST path) if it used the island or conservative renderer. */
    private static boolean isRecoveryRenderer(RendererId id) {
        return id == RendererId.CONSERVATIVE || id == RendererId.LEXICAL_ISLAND;
    }

    /**
     * Build one per-region {@link Pp2FormatResult.Region} record from a parse
     * outcome and the renderer that produced its text. The region-local status
     * is {@code OK} for {@code GUARDED_AST} and {@code OK_WITH_RECOVERY} for the
     * island / conservative recovery renderers (or any AST_ERROR region).
     * Called per region in the interleaved loop, so it never needs to retain
     * the full outcome list.
     */
    private static Pp2FormatResult.Region toRegionRecord(RegionParseOutcome outcome,
                                                          RendererId rendererId) {
        FormatStatus regionStatus;
        if (isRecoveryRenderer(rendererId)) {
            regionStatus = FormatStatus.OK_WITH_RECOVERY;
        } else if (outcome.getStatus() == RegionParseOutcome.Status.AST_ERROR) {
            // Shouldn't happen (AST_ERROR → island/conservative), but be safe.
            regionStatus = FormatStatus.OK_WITH_RECOVERY;
        } else {
            regionStatus = FormatStatus.OK;
        }
        return new Pp2FormatResult.Region(
            outcome.getRange().getStartOffset(),
            outcome.getRange().getEndOffset(),
            rendererId,
            regionStatus);
    }
}