package gudusoft.gsqlparser.pp2.render;

import gudusoft.gsqlparser.pp.logger.PPLogger;
import gudusoft.gsqlparser.pp2.Pp2FormatOptions;
import gudusoft.gsqlparser.pp2.token.SourceSpanLedger;
import gudusoft.gsqlparser.pp2.zone.CommentPolicy;

import java.util.List;

/**
 * Assembles per-region rendered texts into a single output string, bridging
 * gaps between regions with the original inter-region trivia extracted from
 * the {@link SourceSpanLedger}.
 *
 * <h2>Why the ledger owns inter-region trivia</h2>
 *
 * <p>Every {@link RegionRenderer} intentionally omits the leading whitespace
 * for the <em>first</em> token of its range (see {@link RenderedRegion}).
 * The bytes between adjacent regions — whitespace, comments, blank lines,
 * {@code --BEGIN_NO_FORMAT}/{@code --END_NO_FORMAT} blocks — live in the
 * original source at positions {@code [r_i.endOffset, r_{i+1}.startOffset)}.
 * The assembler is the counterparty that places those bytes into the output,
 * so they reach the caller byte-for-byte regardless of which renderer handled
 * the surrounding statements.
 *
 * <h2>Assembly model</h2>
 *
 * <p>Given an ordered, non-overlapping list of {@link RenderedRegion}s:
 * <ol>
 *   <li><b>Preamble</b> — {@code source[0, first.startOffset)}</li>
 *   <li>For each region {@code r_i}:
 *     <ol>
 *       <li>Emit {@code r_i.getText()} (the renderer's output)</li>
 *       <li>Emit {@code source[r_i.endOffset, r_{i+1}.startOffset)}
 *           (inter-region gap; the final region skips this step)</li>
 *     </ol>
 *   </li>
 *   <li><b>Trailer</b> — {@code source[last.endOffset, source.length())}</li>
 * </ol>
 *
 * <p>An empty regions list returns the entire source string unchanged — all
 * bytes come from the preamble/trailer path.
 *
 * <h2>Comment policy</h2>
 *
 * <p>Phase-2 MVP implements only {@link CommentPolicy#PRESERVE}: inter-region
 * bytes are always emitted verbatim. {@link CommentPolicy#REANCHOR} and
 * {@link CommentPolicy#REFLOW} log a notice and fall back to PRESERVE; the
 * Phase-3 island pipeline will provide real semantics.
 *
 * <h2>Defensive behaviour</h2>
 *
 * <p>Overlapping or out-of-order region offsets (which should never occur when
 * {@code StatementBoundaryDetector} S11 produces the list) are detected and
 * logged; overlap bytes are skipped rather than emitted twice. Out-of-bounds
 * source-slice requests are also guarded — no byte is lost due to an offset
 * arithmetic bug in the caller.
 *
 * <p>Plan reference: §7.3/S15, §7.4/S15, §10.4.
 */
public final class RegionAssembler {

    /**
     * Assemble rendered regions into a final output string.
     *
     * @param regions ordered (source position), non-overlapping list of
     *                rendered regions; empty list is allowed
     * @param ledger  the source-span ledger for the original SQL;
     *                {@link SourceSpanLedger#getSource()} is the byte authority
     * @param opts    pp2 format options;
     *                {@link Pp2FormatOptions#commentPolicy} governs how
     *                inter-region trivia is emitted
     * @return the assembled output string; never null
     * @throws NullPointerException if any argument is null
     */
    public String assemble(List<RenderedRegion> regions,
                           SourceSpanLedger ledger,
                           Pp2FormatOptions opts) {
        if (regions == null) throw new NullPointerException("regions");
        if (ledger == null) throw new NullPointerException("ledger");
        if (opts == null) throw new NullPointerException("opts");

        String source = ledger.getSource();

        if (regions.isEmpty()) {
            // All bytes are inter-region trivia; return source unchanged.
            return source;
        }

        if (opts.commentPolicy != CommentPolicy.PRESERVE) {
            PPLogger.info("RegionAssembler: commentPolicy="
                + opts.commentPolicy
                + " is not yet implemented in the Phase-2 MVP; "
                + "falling back to PRESERVE (verbatim inter-region trivia)");
        }

        StringBuilder out = new StringBuilder(source.length());

        // Preamble: source bytes before the first region's first token.
        int firstStart = regions.get(0).getRange().getStartOffset();
        appendSourceSlice(out, source, 0, firstStart, "preamble");

        for (int i = 0; i < regions.size(); i++) {
            RenderedRegion region = regions.get(i);
            int rStart = region.getRange().getStartOffset();
            int rEnd   = region.getRange().getEndOffset();

            // Emit the renderer's output for this region.
            out.append(region.getText());

            if (i + 1 < regions.size()) {
                int nextStart = regions.get(i + 1).getRange().getStartOffset();
                if (rEnd > nextStart) {
                    // Overlapping regions — the boundary detector should never
                    // produce this, but log and skip rather than double-emit.
                    PPLogger.info("RegionAssembler: region[" + i + "].endOffset="
                        + rEnd + " > region[" + (i + 1) + "].startOffset="
                        + nextStart + " — overlapping ranges; skipping gap");
                } else {
                    // Inter-region gap: whitespace, comments, blank lines, etc.
                    appendSourceSlice(out, source, rEnd, nextStart,
                        "gap[" + i + "->" + (i + 1) + "]");
                }
            }
        }

        // Trailer: source bytes after the last region's last token.
        int lastEnd = regions.get(regions.size() - 1).getRange().getEndOffset();
        appendSourceSlice(out, source, lastEnd, source.length(), "trailer");

        return out.toString();
    }

    /**
     * Append {@code source[from..to)} to {@code out}. Guards against
     * out-of-bounds indices: an invalid range logs a warning and emits
     * nothing rather than throwing, so a single bad region cannot corrupt the
     * rest of the assembly.
     */
    private static void appendSourceSlice(StringBuilder out,
                                          String source,
                                          int from, int to,
                                          String label) {
        if (from >= to) return;  // empty or zero-width slice
        if (from < 0 || to > source.length()) {
            PPLogger.info("RegionAssembler: " + label + " source slice ["
                + from + ".." + to + ") is out of bounds "
                + "(sourceLen=" + source.length() + "); skipping");
            return;
        }
        out.append(source, from, to);
    }
}