package gudusoft.gsqlparser.dlineage.dynamicsql;

/**
 * One provenance-tagged fragment of a materialized dynamic-SQL string.
 *
 * <p>A materialized string is an ordered fragment sequence whose concatenated
 * {@link #text} equals the rendered SQL exactly. Each fragment is either:
 * <ul>
 *   <li>{@link Kind#LITERAL} — text proven to be the exact runtime characters:
 *       a string literal, or the output of a transform proven byte-exact for
 *       the vendor;</li>
 *   <li>{@link Kind#HOLE} — text standing in for a value the evaluator could
 *       not prove exactly: an unbound variable's own token, an unfoldable
 *       expression's placeholder, or the output of a transform that is folded
 *       for display but NOT proven byte-exact ({@link HoleOrigin#INEXACT_TRANSFORM}).</li>
 * </ul>
 *
 * <p>Consumers (the per-edge publication proof, design doc
 * {@code dynamic-sql-fragment-provenance-design.md}) must treat every HOLE as
 * arbitrary runtime text; no lineage evidence may rest on HOLE characters. The
 * legacy {@code SqlStringValue.state}/{@code text} contract is unchanged —
 * fragments are additional provenance carried alongside it.
 */
public final class SqlFragment {

    /** Fragment class: exact literal text vs. unproven stand-in text. */
    public enum Kind { LITERAL, HOLE }

    /** Why a HOLE exists — which producer limitation created it. */
    public enum HoleOrigin {
        /** A variable/parameter never bound and never assigned a foldable value. */
        UNBOUND_VARIABLE,
        /** A bare (non-variable) identifier used as a value — data-dependent. */
        NON_VARIABLE_IDENT,
        /** A function call the evaluator does not fold. */
        OPAQUE_CALL,
        /** An expression form the evaluator does not model. */
        UNSUPPORTED_EXPR,
        /** Evaluation hit a configured resource bound. */
        RESOURCE_LIMIT,
        /**
         * A transform was folded for display but its output is not proven
         * byte-exact against vendor runtime semantics (CAST/CONVERT padding and
         * styles, collation-aware REPLACE/UPPER/LOWER, whitespace-class TRIM,
         * non-default QUOTENAME delimiters, numeric rendering).
         */
        INEXACT_TRANSFORM,
        /**
         * A variable whose last visible assignment read from a query
         * ({@code SELECT @v = col FROM t ...}): its value is runtime data. The
         * hole keeps the assignment's own rendering (the source column name as a
         * placeholder) but is named after the VARIABLE, and {@link #valueOrigin}
         * describes the column / expression the value would come from.
         */
        QUERY_ASSIGNED_VARIABLE,
        /**
         * A variable whose value depends on control flow the evaluator cannot
         * decide: assigned inside an undecidable IF / WHILE branch, declared
         * there, or assigned by a driver loop whose iteration is unknown.
         */
        FLOW_DEPENDENT_VARIABLE
    }

    public final Kind kind;
    /** Exact rendered text this fragment contributes to the materialized SQL. Never null. */
    public final String text;
    /** HOLE only: why the hole exists; null for LITERAL. */
    public final HoleOrigin origin;
    /** HOLE only: the variable/function/expression name that caused it; may be null. */
    public final String originName;
    /** HOLE only: human-readable cause; null for LITERAL. */
    public final String reason;
    /**
     * HOLE only: true when the hole's runtime VALUE is unknown (an unbound variable, or a
     * transform applied to one). False for an {@code INEXACT_TRANSFORM} computed entirely
     * from literals, where the value is known and only its byte-exactness against vendor
     * runtime semantics is unproven. The distinction matters to consumers deciding whether
     * a folded identifier is a runtime TEMPLATE ({@code UPPER(@X)} — unknown) or merely an
     * unproven rendering of a known name ({@code UPPER('src')} — known). Always false for
     * LITERAL fragments.
     */
    public final boolean valueUnknown;
    /**
     * Where the value came from. LITERAL: the seed of an exact value — null for
     * ordinary SQL string fragments; constant-relation values use a stable
     * description such as {@code INSERT VALUES row 2 of @Source}. HOLE: the
     * data source the unknown value would be read from, when the evaluator saw
     * it ({@code dbo.SSF_Entity.Entity} for a {@link HoleOrigin#QUERY_ASSIGNED_VARIABLE});
     * null when unknown.
     */
    public final String valueOrigin;
    /**
     * Source offsets, end-exclusive, of the fragment's origin in the analyzed
     * text: for a LITERAL the seeding expression; for a HOLE the place the
     * value was last defined — the assignment target of a query-assigned or
     * flow-dependent variable, the declaration of an unbound parameter or of a
     * declared-but-unassigned variable, otherwise the reference that produced
     * the hole. {@code -1} when the origin is not in the analyzed text.
     */
    public final long sourceStartOffset;
    public final long sourceEndOffset;
    /**
     * The same origin span as line / column: 1-based, end-exclusive end column,
     * in the coordinate system of {@code TSourceToken.lineNo / columnNo}.
     * {@code -1} when unknown. Populated for HOLE fragments whose origin is a
     * source node; LITERAL fragments carry offsets only.
     */
    public final int sourceStartLine;
    public final int sourceStartColumn;
    public final int sourceEndLine;
    public final int sourceEndColumn;

    private SqlFragment(Kind kind, String text, HoleOrigin origin, String originName, String reason,
            boolean valueUnknown, String valueOrigin, long sourceStartOffset,
            long sourceEndOffset) {
        this(kind, text, origin, originName, reason, valueUnknown, valueOrigin,
                sourceStartOffset, sourceEndOffset, -1, -1, -1, -1);
    }

    private SqlFragment(Kind kind, String text, HoleOrigin origin, String originName, String reason,
            boolean valueUnknown, String valueOrigin, long sourceStartOffset,
            long sourceEndOffset, int sourceStartLine, int sourceStartColumn,
            int sourceEndLine, int sourceEndColumn) {
        this.kind = kind;
        this.text = text == null ? "" : text;
        this.origin = origin;
        this.originName = originName;
        this.reason = reason;
        this.valueUnknown = valueUnknown;
        this.valueOrigin = valueOrigin;
        this.sourceStartOffset = sourceStartOffset;
        this.sourceEndOffset = sourceEndOffset;
        this.sourceStartLine = sourceStartLine;
        this.sourceStartColumn = sourceStartColumn;
        this.sourceEndLine = sourceEndLine;
        this.sourceEndColumn = sourceEndColumn;
    }

    public static SqlFragment literal(String text) {
        return new SqlFragment(Kind.LITERAL, text, null, null, null, false,
                null, -1L, -1L);
    }

    /** Exact literal value with its procedure-body seed provenance. */
    public static SqlFragment literal(String text, String valueOrigin,
            long sourceStartOffset, long sourceEndOffset) {
        return new SqlFragment(Kind.LITERAL, text, null, null, null, false,
                valueOrigin, sourceStartOffset, sourceEndOffset);
    }

    /**
     * Hole with the default value-knowledge for its origin: every origin except
     * {@code INEXACT_TRANSFORM} stands in for a value nobody knows; an inexact transform
     * defaults to value-known (computed from literals). A transform over a PARTIAL input
     * must use the explicit overload with {@code valueUnknown=true}.
     */
    public static SqlFragment hole(String renderedText, HoleOrigin origin, String originName, String reason) {
        HoleOrigin resolved = origin == null ? HoleOrigin.UNSUPPORTED_EXPR : origin;
        return new SqlFragment(Kind.HOLE, renderedText, resolved, originName, reason,
                resolved != HoleOrigin.INEXACT_TRANSFORM, null, -1L, -1L);
    }

    public static SqlFragment hole(String renderedText, HoleOrigin origin, String originName, String reason,
            boolean valueUnknown) {
        return new SqlFragment(Kind.HOLE, renderedText,
                origin == null ? HoleOrigin.UNSUPPORTED_EXPR : origin, originName, reason, valueUnknown,
                null, -1L, -1L);
    }

    /**
     * Hole with full provenance: the data source its value would come from
     * ({@code valueOrigin}, may be null) and the origin span in the analyzed
     * text (see {@link #sourceStartOffset} / {@link #sourceStartLine}; pass
     * {@code -1} for unknown).
     */
    public static SqlFragment hole(String renderedText, HoleOrigin origin, String originName, String reason,
            boolean valueUnknown, String valueOrigin, long sourceStartOffset, long sourceEndOffset,
            int sourceStartLine, int sourceStartColumn, int sourceEndLine, int sourceEndColumn) {
        return new SqlFragment(Kind.HOLE, renderedText,
                origin == null ? HoleOrigin.UNSUPPORTED_EXPR : origin, originName, reason, valueUnknown,
                valueOrigin, sourceStartOffset, sourceEndOffset,
                sourceStartLine, sourceStartColumn, sourceEndLine, sourceEndColumn);
    }

    /** True when the origin span is known in line / column form. */
    public boolean hasSourceSpan() {
        return sourceStartLine > 0 && sourceStartColumn > 0;
    }

    public boolean isLiteral() {
        return kind == Kind.LITERAL;
    }

    boolean hasSameLiteralProvenance(SqlFragment other) {
        if (other == null || !isLiteral() || !other.isLiteral()) {
            return false;
        }
        if (valueOrigin == null ? other.valueOrigin != null : !valueOrigin.equals(other.valueOrigin)) {
            return false;
        }
        return sourceStartOffset == other.sourceStartOffset
                && sourceEndOffset == other.sourceEndOffset;
    }

    @Override
    public String toString() {
        return kind == Kind.LITERAL
                ? "L[" + text + "]"
                : "H[" + text + " <" + origin + (originName != null ? ":" + originName : "") + ">]";
    }
}