package gudusoft.gsqlparser.pp2.engine;

import gudusoft.gsqlparser.EDbVendor;
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.zone.ProtectedZoneDetector;

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

/**
 * Fault-tolerant SQL formatter engine — Phase-2 MVP orchestrator.
 *
 * <h2>Pipeline summary</h2>
 *
 * <p>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} (fallback to
 *       conservative on guard failure); {@code AST_ERROR} →
 *       {@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");

        try {
            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);
        }
    }

    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();

        // 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 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);
    }
}