package gudusoft.gsqlparser.ir.semantic;

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

/**
 * One projected column in the SELECT list. {@link #sources} is the list of
 * input columns this output depends on; {@link #derived} distinguishes a
 * direct column reference (e.g. {@code SELECT id}) from a computed
 * expression (e.g. {@code SELECT salary*2 AS doubled} or
 * {@code SELECT a.x + a.y}); {@link #aggregate} marks the output as the
 * result of an aggregate function call (e.g. {@code COUNT(*)},
 * {@code SUM(salary)}); {@link #windowSpec} (slice 13) carries
 * PARTITION BY / OVER ORDER BY refs when the projection is a window
 * function.
 *
 * <p>Slice 4 introduced {@code derived}; slice 6 added {@code aggregate}
 * and lifted the empty-sources restriction for aggregates only (e.g.
 * {@code COUNT(*)} has no column refs); slice 13 added {@code windowSpec}
 * and lifts the empty-sources restriction for window functions
 * (e.g. {@code ROW_NUMBER() OVER (...)} has no column refs).
 *
 * <p><b>Note on flag propagation:</b> {@code derived}, {@code aggregate},
 * and {@code windowSpec} are local to a single statement's output. They
 * are <i>not</i> propagated transitively. If a CTE defines
 * {@code total = SUM(salary)}, that CTE's output has
 * {@code aggregate=true}; an outer query that re-projects the CTE's
 * {@code total} column ({@code SELECT total FROM cte}) is a direct
 * reference and so the outer's output has {@code aggregate=false} (and
 * {@code derived=false}). Consumers that need a transitive view should
 * walk {@link gudusoft.gsqlparser.ir.semantic.SemanticProgram#getLineage()}
 * and inspect each upstream {@code OutputColumn}.
 *
 * <p><b>Window-function invariant (slice 13):</b> when {@code windowSpec
 * != null}, {@code aggregate} MUST be {@code false}. Window functions
 * are row-preserving (analytic), not row-collapsing, so the per-output
 * aggregate flag stays false even when the window function is a name
 * that overlaps with an aggregate (e.g. {@code AVG(salary) OVER (...)}).
 * The constructor enforces this invariant.
 */
public final class OutputColumn {

    private final String name;
    private final boolean derived;
    private final boolean aggregate;
    private final List<ColumnRef> sources;
    private final WindowSpec windowSpec;
    private final String expressionText;
    private final SourceSpan expressionSpan;

    /**
     * Backwards-compatible constructor delegating to the 5-arg form with
     * {@code windowSpec=null}. Slice 13 added the 5-arg constructor; this
     * overload preserves source-compatibility for downstream callers that
     * were already using {@link OutputColumn} from a published version of
     * the library.
     */
    public OutputColumn(String name, boolean derived, boolean aggregate,
                        List<ColumnRef> sources) {
        this(name, derived, aggregate, sources, null);
    }

    public OutputColumn(String name, boolean derived, boolean aggregate,
                        List<ColumnRef> sources, WindowSpec windowSpec) {
        this(name, derived, aggregate, sources, windowSpec, null, null);
    }

    /**
     * Full constructor (US-021a). {@code expressionText} and
     * {@code expressionSpan} are optional projection-expression provenance
     * (see {@link #getExpressionText()} / {@link #getExpressionSpan()});
     * both default to {@code null} via the shorter overloads, preserving
     * full behavioural compatibility for every existing caller.
     */
    public OutputColumn(String name, boolean derived, boolean aggregate,
                        List<ColumnRef> sources, WindowSpec windowSpec,
                        String expressionText, SourceSpan expressionSpan) {
        if (name == null || name.isEmpty()) {
            throw new IllegalArgumentException("name must be non-empty");
        }
        if (sources == null) {
            throw new IllegalArgumentException("sources must not be null");
        }
        if (windowSpec != null && aggregate) {
            throw new IllegalArgumentException(
                    "windowSpec is non-null but aggregate=true; window functions are "
                            + "row-preserving and must carry aggregate=false");
        }
        this.name = name;
        this.derived = derived;
        this.aggregate = aggregate;
        this.sources = Collections.unmodifiableList(new ArrayList<>(sources));
        this.windowSpec = windowSpec;
        this.expressionText = expressionText;
        this.expressionSpan = expressionSpan;
    }

    /**
     * Copy of this output column with the projection-expression provenance
     * attached (US-021a). Every other field is preserved verbatim. Returns
     * {@code this} when both arguments are {@code null} (nothing to attach).
     */
    public OutputColumn withExpression(String expressionText, SourceSpan expressionSpan) {
        if (expressionText == null && expressionSpan == null) {
            return this;
        }
        return new OutputColumn(name, derived, aggregate, sources, windowSpec,
                expressionText, expressionSpan);
    }

    public String getName() {
        return name;
    }

    /** {@code true} when the projection is an expression rather than a direct column reference. */
    public boolean isDerived() {
        return derived;
    }

    /**
     * {@code true} when the projection is an aggregate function call
     * (COUNT, SUM, AVG, MIN, MAX, etc.). Always implies {@link #isDerived()}.
     * Always {@code false} when {@link #getWindowSpec()} is non-null
     * (window functions are row-preserving).
     */
    public boolean isAggregate() {
        return aggregate;
    }

    public List<ColumnRef> getSources() {
        return sources;
    }

    /**
     * Per-output analytic dependencies (slice 13). Non-null iff this
     * projection is a window function (e.g. {@code FUNC(arg) OVER (...)});
     * null otherwise.
     */
    public WindowSpec getWindowSpec() {
        return windowSpec;
    }

    /**
     * Original source text of the projection expression this output was
     * built from (US-021a), reconstructed from the parser's token stream so
     * multi-line expressions keep their newlines. {@code null} when no
     * single projection expression exists for this output — e.g. star
     * expansion (one {@code *} produces many outputs), synthetic outputs
     * (predicate-body scaffolding, UPDATE SET shells), or columns built by
     * paths that have not been wired yet. Null-safe: never throws.
     */
    public String getExpressionText() {
        return expressionText;
    }

    /**
     * Source span of the projection expression (US-021a), half-open per
     * {@link SourceSpan}. {@code null} under the same conditions as
     * {@link #getExpressionText()}, and additionally when the expression's
     * boundary tokens cannot anchor a span. Null-safe: never throws.
     */
    public SourceSpan getExpressionSpan() {
        return expressionSpan;
    }
}