package gudusoft.gsqlparser.lineage2.engine;

import gudusoft.gsqlparser.EDbVendor;
import gudusoft.gsqlparser.EExpressionType;
import gudusoft.gsqlparser.ESetOperatorType;
import gudusoft.gsqlparser.TSourceToken;
import gudusoft.gsqlparser.ir.semantic.AnalysisResult;
import gudusoft.gsqlparser.ir.semantic.RelationKind;
import gudusoft.gsqlparser.ir.semantic.RelationSource;
import gudusoft.gsqlparser.ir.semantic.SqlSemanticAnalyzer;
import gudusoft.gsqlparser.ir.semantic.StatementGraph;
import gudusoft.gsqlparser.ir.semantic.catalog.Catalog;
import gudusoft.gsqlparser.ir.semantic.catalog.CatalogColumn;
import gudusoft.gsqlparser.ir.semantic.catalog.CatalogTable;
import gudusoft.gsqlparser.lineage2.api.LineageConfig;
import gudusoft.gsqlparser.lineage2.contract.CaseBranch;
import gudusoft.gsqlparser.lineage2.contract.ContractEdge;
import gudusoft.gsqlparser.lineage2.contract.EdgeIdentity;
import gudusoft.gsqlparser.lineage2.contract.Endpoint;
import gudusoft.gsqlparser.lineage2.contract.GuidEncoder;
import gudusoft.gsqlparser.lineage2.contract.LineageAxis;
import gudusoft.gsqlparser.lineage2.contract.LineageRole;
import gudusoft.gsqlparser.lineage2.contract.ObjectKind;
import gudusoft.gsqlparser.lineage2.contract.ResolutionStatus;
import gudusoft.gsqlparser.lineage2.contract.SourceLocation;
import gudusoft.gsqlparser.lineage2.contract.Transformation;
import gudusoft.gsqlparser.nodes.TAliasClause;
import gudusoft.gsqlparser.nodes.TCaseExpression;
import gudusoft.gsqlparser.nodes.TExpression;
import gudusoft.gsqlparser.nodes.TExpressionList;
import gudusoft.gsqlparser.nodes.TFunctionCall;
import gudusoft.gsqlparser.nodes.TJoin;
import gudusoft.gsqlparser.nodes.TJoinItem;
import gudusoft.gsqlparser.nodes.TObjectName;
import gudusoft.gsqlparser.nodes.TOrderBy;
import gudusoft.gsqlparser.nodes.TOrderByItem;
import gudusoft.gsqlparser.nodes.TParseTreeNode;
import gudusoft.gsqlparser.nodes.TPartitionClause;
import gudusoft.gsqlparser.nodes.TResultColumn;
import gudusoft.gsqlparser.nodes.TSortBy;
import gudusoft.gsqlparser.nodes.TTable;
import gudusoft.gsqlparser.nodes.TWhenClauseItem;
import gudusoft.gsqlparser.nodes.TWindowDef;
import gudusoft.gsqlparser.stmt.TSelectSqlStatement;

import java.util.ArrayDeque;
import java.util.ArrayList;
import java.util.Arrays;
import java.util.Collections;
import java.util.Deque;
import java.util.HashMap;
import java.util.HashSet;
import java.util.LinkedHashMap;
import java.util.LinkedHashSet;
import java.util.List;
import java.util.Locale;
import java.util.Map;
import java.util.Set;

/**
 * US-021 — role-tagged edge extraction for a single {@code SELECT}
 * statement (contract §5 two-pass decision procedure).
 *
 * <p>The extractor wraps {@link SqlSemanticAnalyzer#analyze} as the
 * semantic gate and relation-binding source (alias → base table), and
 * walks the already-parsed resolver2-annotated AST for everything the
 * Semantic IR does not yet carry (expression text, alias/expression
 * source spans, CASE branch attribution, per-conjunct predicate
 * decomposition — the IR side arrives with US-021a).
 *
 * <p><b>Pass 1 — axis.</b> VALUE contributions come from the SELECT list
 * (one edge per distinct source column per output), ROW contributions
 * from WHERE / HAVING conjuncts (R1) and JOIN ON conjuncts (R2), each
 * targeting the statement's result set as a whole (null target column).
 * A source appearing on both axes yields two edges (identity layer
 * requirement).
 *
 * <p><b>Pass 2 — role within axis.</b> ROW: FILTER (R1) beats JOIN (R2);
 * a source in both WHERE and ON yields the FILTER edge only. VALUE:
 * AGGREGATE (V1, incl. reducing window functions, excl. ranking) beats
 * CONDITION (V2, CASE/IIF condition branch) beats TRANSFORM (V3); a
 * bare-column projection is DIRECT (V5); an output with no column
 * sources at all is DERIVED with a null source endpoint (V6). LOOKUP
 * (V4) requires catalog key metadata and is never guessed — it always
 * falls through until the BindingGate story (US-025) supplies key facts.
 *
 * <p>Out-of-scope statement shapes (set operators, star projections,
 * multi-block queries with CTEs/subqueries, non-TABLE relations) yield
 * no edges — their extraction stories are US-022+.
 *
 * <p>Internal API: not part of the public gsqlparser surface.
 */
public final class StatementLineageExtractor {

    /** Contract §4 record type for engine-emitted occurrences. */
    private static final String RECORD_TYPE = "INCOMING";

    /** Result relation object name of a top-level SELECT (gold convention). */
    private static final String RESULTSET = "RESULTSET";

    /**
     * Reducing aggregate function names (contract §5 V1). Window
     * functions count only when reducing — ranking/navigation functions
     * (ROW_NUMBER, RANK, LAG, …) are deliberately absent so they
     * classify as TRANSFORM.
     */
    private static final Set<String> AGGREGATE_FUNCTIONS =
            Collections.unmodifiableSet(new HashSet<String>(Arrays.asList(
                    "sum", "avg", "count", "count_big", "min", "max",
                    "string_agg", "stdev", "stdevp", "var", "varp",
                    "variance", "stddev", "checksum_agg", "grouping",
                    "grouping_id", "approx_count_distinct")));

    private StatementLineageExtractor() {
        // utility — no instances
    }

    /**
     * Extract contract edges for one parsed SELECT statement.
     *
     * @param stmt             resolver2-annotated AST from the unit parse
     * @param statementText    verbatim statement slice (trailing separator
     *                         excluded — the FINGERPRINT-V1 slice)
     * @param statementIndex   1-based source-order index
     * @param queryFingerprint FINGERPRINT-V1 of {@code statementText}
     * @param unitText         full unit text (token offsets index into it)
     * @return contract edges in deterministic construction order
     *         (final ordering is the exporter's documented sort); empty
     *         for out-of-scope shapes or semantic-gate rejections
     */
    public static List<ContractEdge> extract(TSelectSqlStatement stmt,
                                             String statementText,
                                             int statementIndex,
                                             String queryFingerprint,
                                             EDbVendor vendor,
                                             Catalog catalog,
                                             LineageConfig config,
                                             String artifactLocator,
                                             String unitText) {
        if (stmt == null || statementText == null) {
            return Collections.emptyList();
        }
        if (stmt.getSetOperatorType() != ESetOperatorType.none) {
            return Collections.emptyList(); // set operators: R3 story (US-02x)
        }
        if (stmt.getResultColumnList() == null
                || stmt.getResultColumnList().size() == 0) {
            return Collections.emptyList();
        }
        for (int i = 0; i < stmt.getResultColumnList().size(); i++) {
            TExpression expr = stmt.getResultColumnList()
                    .getResultColumn(i).getExpr();
            if (expr != null && isStar(expr)) {
                return Collections.emptyList(); // star expansion story
            }
        }

        // Semantic gate (the wrapped analyzer): rejects shapes the IR does
        // not support and supplies the alias → base-table binding map.
        AnalysisResult analysis =
                SqlSemanticAnalyzer.analyze(statementText, vendor, catalog);
        if (!analysis.isSuccessful() || analysis.getProgram() == null) {
            return Collections.emptyList();
        }
        List<StatementGraph> graphs = analysis.getProgram().getStatements();
        if (graphs.size() != 1) {
            return Collections.emptyList(); // CTE / subquery stories (US-02x)
        }
        Map<String, String> aliasToTable = new HashMap<String, String>();
        for (RelationSource relation : graphs.get(0).getRelations()) {
            if (relation.getBinding().getKind() != RelationKind.TABLE) {
                return Collections.emptyList();
            }
            aliasToTable.put(relation.getAlias().toLowerCase(Locale.ROOT),
                    relation.getBinding().getQualifiedName());
        }

        Extraction extraction = new Extraction(statementIndex,
                queryFingerprint, catalog, config, artifactLocator, unitText,
                aliasToTable);
        extraction.valueEdges(stmt);
        extraction.rowEdges(stmt);
        return extraction.edges;
    }

    /** Per-statement extraction state. */
    private static final class Extraction {
        final List<ContractEdge> edges = new ArrayList<ContractEdge>();
        final int statementIndex;
        final String queryFingerprint;
        final Catalog catalog;
        final LineageConfig config;
        final String artifactLocator;
        final String unitText;
        final Map<String, String> aliasToTable;

        Extraction(int statementIndex, String queryFingerprint,
                   Catalog catalog, LineageConfig config,
                   String artifactLocator, String unitText,
                   Map<String, String> aliasToTable) {
            this.statementIndex = statementIndex;
            this.queryFingerprint = queryFingerprint;
            this.catalog = catalog;
            this.config = config;
            this.artifactLocator = artifactLocator;
            this.unitText = unitText;
            this.aliasToTable = aliasToTable;
        }

        // -------------------------------------------------------------
        // VALUE axis (contract §5 pass 2, V1–V7).
        // -------------------------------------------------------------

        void valueEdges(TSelectSqlStatement stmt) {
            for (int i = 0; i < stmt.getResultColumnList().size(); i++) {
                TResultColumn rc =
                        stmt.getResultColumnList().getResultColumn(i);
                TExpression expr = rc.getExpr();
                if (expr == null) {
                    continue;
                }
                Endpoint target = resultsetEndpoint(targetName(rc, expr),
                        targetLocation(rc, expr));
                if (expr.getExpressionType()
                        == EExpressionType.simple_object_name_t) {
                    // V5 — pure column copy: no transformation object.
                    Endpoint source =
                            sourceEndpoint(expr.getObjectOperand());
                    if (source != null) {
                        addEdge(LineageRole.DIRECT, LineageAxis.VALUE,
                                source, target, null, null);
                    }
                    continue;
                }
                Transformation tf = transformationOf(expr);
                List<Ref> refs = collectRefs(expr);
                if (refs.isEmpty()) {
                    // V6 — constant-only / synthesized target: null source.
                    addEdge(LineageRole.DERIVED, LineageAxis.VALUE, null,
                            target, tf, null);
                    continue;
                }
                Set<String> seen = new LinkedHashSet<String>();
                for (Ref ref : refs) {
                    Endpoint source = sourceEndpoint(ref.node);
                    if (source == null) {
                        continue;
                    }
                    LineageRole role = ref.aggregate ? LineageRole.AGGREGATE
                            : (ref.branch == CaseBranch.CONDITION
                                    ? LineageRole.CONDITION
                                    : LineageRole.TRANSFORM);
                    String key = endpointKey(source) + "|" + role.name()
                            + "|" + (ref.branch == null ? ""
                                    : ref.branch.name());
                    if (!seen.add(key)) {
                        continue;
                    }
                    addEdge(role, LineageAxis.VALUE, source, target, tf,
                            ref.branch);
                }
            }
        }

        // -------------------------------------------------------------
        // ROW axis (contract §5 pass 2, R1–R4).
        // -------------------------------------------------------------

        void rowEdges(TSelectSqlStatement stmt) {
            // R1 — WHERE / HAVING conjuncts, in clause order.
            List<TExpression> filterConjuncts = new ArrayList<TExpression>();
            if (stmt.getWhereClause() != null
                    && stmt.getWhereClause().getCondition() != null) {
                filterConjuncts.addAll(
                        conjunctsOf(stmt.getWhereClause().getCondition()));
            }
            if (stmt.getGroupByClause() != null
                    && stmt.getGroupByClause().getHavingClause() != null) {
                filterConjuncts.addAll(conjunctsOf(
                        stmt.getGroupByClause().getHavingClause()));
            }
            // Sources with an R1 edge suppress their R2 edges (R1 beats R2:
            // one ROW edge per source for the same target, role FILTER).
            Set<String> filtered = new HashSet<String>();
            for (TExpression conjunct : filterConjuncts) {
                for (Map.Entry<String, Endpoint> entry
                        : uniqueSources(conjunct).entrySet()) {
                    filtered.add(entry.getKey());
                    addEdge(LineageRole.FILTER, LineageAxis.ROW,
                            entry.getValue(), resultsetEndpoint(null, null),
                            transformationOf(conjunct), null);
                }
            }
            // R2 — JOIN ON conjuncts.
            if (stmt.getJoins() != null) {
                for (int i = 0; i < stmt.getJoins().size(); i++) {
                    TJoin join = stmt.getJoins().getJoin(i);
                    if (join.getJoinItems() == null) {
                        continue;
                    }
                    for (int j = 0; j < join.getJoinItems().size(); j++) {
                        TJoinItem item = join.getJoinItems().getJoinItem(j);
                        if (item.getOnCondition() == null) {
                            continue;
                        }
                        for (TExpression conjunct
                                : conjunctsOf(item.getOnCondition())) {
                            for (Map.Entry<String, Endpoint> entry
                                    : uniqueSources(conjunct).entrySet()) {
                                if (filtered.contains(entry.getKey())) {
                                    continue;
                                }
                                addEdge(LineageRole.JOIN, LineageAxis.ROW,
                                        entry.getValue(),
                                        resultsetEndpoint(null, null),
                                        transformationOf(conjunct), null);
                            }
                        }
                    }
                }
            }
        }

        /** Distinct source endpoints of one predicate, in source order. */
        Map<String, Endpoint> uniqueSources(TExpression predicate) {
            Map<String, Endpoint> out = new LinkedHashMap<String, Endpoint>();
            for (Ref ref : collectRefs(predicate)) {
                Endpoint source = sourceEndpoint(ref.node);
                if (source == null) {
                    continue;
                }
                String key = endpointKey(source);
                if (!out.containsKey(key)) {
                    out.put(key, source);
                }
            }
            return out;
        }

        // -------------------------------------------------------------
        // Edge / endpoint assembly.
        // -------------------------------------------------------------

        void addEdge(LineageRole role, LineageAxis axis, Endpoint source,
                     Endpoint target, Transformation tf,
                     CaseBranch caseBranch) {
            String factGuid = GuidEncoder.factGuid(config.getWorkspaceId(),
                    source == null ? null : source.getDatabase(),
                    source == null ? null : source.getSchema(),
                    source == null ? null : source.getObject(),
                    source == null ? null : source.getColumn(),
                    target.getDatabase(), target.getSchema(),
                    target.getObject(), target.getColumn(), role.name());
            // Draft variantGuid convention (gen_fixtures.py): VALUE-axis
            // edges hash the normalized expression into the transformation
            // component, ROW-axis edges into the predicate component.
            String exprHash = (tf == null) ? ""
                    : GuidEncoder.textHash(tf.getNormalizedExpression());
            String transformationHash =
                    (axis == LineageAxis.VALUE) ? exprHash : "";
            String predicateHash = (axis == LineageAxis.ROW) ? exprHash : "";
            String variantGuid = GuidEncoder.variantGuid(
                    config.getWorkspaceId(), factGuid, role.name(),
                    transformationHash, predicateHash, queryFingerprint);
            String occurrenceGuid = GuidEncoder.occurrenceGuid(
                    config.getWorkspaceId(), factGuid, variantGuid,
                    RECORD_TYPE, "", "", queryFingerprint, artifactLocator,
                    statementIndex);
            edges.add(ContractEdge.builder()
                    .source(source)
                    .target(target)
                    .role(role)
                    .axis(axis)
                    .caseBranch(caseBranch)
                    .statementIndex(statementIndex)
                    .transformation(tf)
                    .identity(new EdgeIdentity(factGuid, variantGuid,
                            occurrenceGuid))
                    .build());
        }

        /**
         * Physical source endpoint for a column reference, fully expanded
         * per the D-15 qualification promise. Returns {@code null} when
         * the reference cannot be bound to a base relation (the binding
         * stories US-025+ replace this with non-RESOLVED endpoints).
         */
        Endpoint sourceEndpoint(TObjectName ref) {
            if (ref == null) {
                return null;
            }
            String column = ref.getColumnNameOnly();
            if (column == null || column.isEmpty() || "*".equals(column)) {
                return null;
            }
            String tableName = null;
            TTable sourceTable = ref.getSourceTable();
            if (sourceTable != null) {
                tableName = sourceTable.getFullName();
            }
            if (tableName == null || tableName.isEmpty()) {
                String qualifier = ref.getObjectString();
                if (qualifier != null && !qualifier.isEmpty()) {
                    tableName = aliasToTable.get(
                            qualifier.toLowerCase(Locale.ROOT));
                }
            }
            if ((tableName == null || tableName.isEmpty())
                    && aliasToTable.size() == 1) {
                // Unqualified reference in a single-relation scope.
                tableName = aliasToTable.values().iterator().next();
            }
            if (tableName == null || tableName.isEmpty()) {
                return null;
            }
            String[] parts = tableName.split("\\.");
            String database = null;
            String schema = null;
            String object;
            if (parts.length >= 3) {
                database = parts[parts.length - 3];
                schema = parts[parts.length - 2];
                object = parts[parts.length - 1];
            } else if (parts.length == 2) {
                schema = parts[0];
                object = parts[1];
            } else {
                object = parts[0];
            }
            if (schema == null && !config.getDefaultSchema().isEmpty()) {
                schema = config.getDefaultSchema();
            }
            if (database == null && !config.getDefaultDatabase().isEmpty()) {
                database = config.getDefaultDatabase();
            }
            return Endpoint.builder(object)
                    .database(database)
                    .schema(schema)
                    .column(column)
                    .objectKind(ObjectKind.TABLE)
                    .resolutionStatus(resolutionStatus(database, schema,
                            object, column))
                    .sourceLocation(locationOf(ref))
                    .build();
        }

        /**
         * Resolution status against the catalog snapshot (contract §4.1
         * precedence; the BindingGate story US-025 extends this with
         * AMBIGUOUS / PARSER_UNSUPPORTED facts).
         */
        ResolutionStatus resolutionStatus(String database, String schema,
                                          String object, String column) {
            if (catalog == null) {
                return ResolutionStatus.GUESSED;
            }
            String bare = object.toLowerCase(Locale.ROOT);
            String qualified = ((database == null ? "" : database + ".")
                    + (schema == null ? "" : schema + ".")
                    + object).toLowerCase(Locale.ROOT);
            for (CatalogTable table : catalog.getTables()) {
                String name = table.getName() == null ? ""
                        : table.getName().toLowerCase(Locale.ROOT);
                if (!name.equals(qualified) && !name.equals(bare)
                        && !name.endsWith("." + bare)) {
                    continue;
                }
                for (CatalogColumn catalogColumn : table.getColumns()) {
                    if (column.equalsIgnoreCase(catalogColumn.getName())) {
                        return ResolutionStatus.RESOLVED;
                    }
                }
                return ResolutionStatus.PARTIAL;
            }
            return ResolutionStatus.UNRESOLVED_SOURCE;
        }

        Endpoint resultsetEndpoint(String column, SourceLocation location) {
            return Endpoint.builder(RESULTSET)
                    .column(column)
                    .objectKind(ObjectKind.UNKNOWN)
                    .resolutionStatus(ResolutionStatus.RESOLVED)
                    .sourceLocation(location)
                    .build();
        }

        String targetName(TResultColumn rc, TExpression expr) {
            TAliasClause alias = rc.getAliasClause();
            if (alias != null && alias.getAliasName() != null) {
                return alias.getAliasName().toString();
            }
            if (expr.getExpressionType()
                    == EExpressionType.simple_object_name_t
                    && expr.getObjectOperand() != null) {
                return expr.getObjectOperand().getColumnNameOnly();
            }
            return sliceText(expr);
        }

        SourceLocation targetLocation(TResultColumn rc, TExpression expr) {
            TAliasClause alias = rc.getAliasClause();
            if (alias != null && alias.getAliasName() != null) {
                return locationOf(alias.getAliasName());
            }
            return locationOf(expr);
        }

        Transformation transformationOf(TParseTreeNode node) {
            String original = sliceText(node);
            if (original == null || original.isEmpty()) {
                return null;
            }
            return Transformation.of(original, locationOf(node), null);
        }

        /** Verbatim unit-text slice spanned by the node's tokens. */
        String sliceText(TParseTreeNode node) {
            TSourceToken startToken = node.getStartToken();
            TSourceToken endToken = node.getEndToken();
            if (startToken == null || endToken == null) {
                return null;
            }
            int start = (int) startToken.offset;
            String endText = endToken.astext == null ? "" : endToken.astext;
            int end = (int) endToken.offset + endText.length();
            if (start < 0 || end < start || end > unitText.length()) {
                return null;
            }
            return unitText.substring(start, end);
        }

        /**
         * Half-open 1-based contract location from the node's boundary
         * tokens (unit coordinates — the AST comes from the unit parse).
         */
        SourceLocation locationOf(TParseTreeNode node) {
            TSourceToken startToken = node.getStartToken();
            TSourceToken endToken = node.getEndToken();
            if (startToken == null || endToken == null) {
                return null;
            }
            String endText = endToken.astext == null ? "" : endToken.astext;
            int newlines = 0;
            for (int i = 0; i < endText.length(); i++) {
                if (endText.charAt(i) == '\n') {
                    newlines++;
                }
            }
            int endLine = (int) endToken.lineNo + newlines;
            int endCol = (newlines == 0)
                    ? (int) endToken.columnNo + endText.length()
                    : endText.length() - endText.lastIndexOf('\n');
            return new SourceLocation(artifactLocator, statementIndex,
                    (int) startToken.lineNo, (int) startToken.columnNo,
                    endLine, endCol);
        }

        String endpointKey(Endpoint endpoint) {
            return (lower(endpoint.getDatabase()) + "|"
                    + lower(endpoint.getSchema()) + "|"
                    + lower(endpoint.getObject()) + "|"
                    + lower(endpoint.getColumn()));
        }

        private String lower(String s) {
            return s == null ? "" : s.toLowerCase(Locale.ROOT);
        }
    }

    // -----------------------------------------------------------------
    // Expression analysis (shared, stateless).
    // -----------------------------------------------------------------

    /** A column reference with its V1/V2 classification context. */
    private static final class Ref {
        final TObjectName node;
        final boolean aggregate;
        final CaseBranch branch;

        Ref(TObjectName node, boolean aggregate, CaseBranch branch) {
            this.node = node;
            this.aggregate = aggregate;
            this.branch = branch;
        }
    }

    /** Work item for the iterative expression walk. */
    private static final class Frame {
        final TExpression expr;
        final boolean aggregate;
        final CaseBranch branch;

        Frame(TExpression expr, boolean aggregate, CaseBranch branch) {
            this.expr = expr;
            this.aggregate = aggregate;
            this.branch = branch;
        }
    }

    /**
     * Collect column references with aggregate-path / CASE-branch flags.
     * Iterative (explicit stack) per the repo's no-recursion rule for
     * expression trees; children are pushed in reverse so references pop
     * in source order. Subqueries are skipped (their lineage belongs to
     * their own scope — multi-block stories).
     */
    private static List<Ref> collectRefs(TExpression root) {
        List<Ref> out = new ArrayList<Ref>();
        Deque<Frame> stack = new ArrayDeque<Frame>();
        stack.push(new Frame(root, false, null));
        while (!stack.isEmpty()) {
            Frame frame = stack.pop();
            TExpression e = frame.expr;
            if (e == null) {
                continue;
            }
            EExpressionType type = e.getExpressionType();
            if (type == EExpressionType.simple_object_name_t) {
                TObjectName name = e.getObjectOperand();
                if (name != null && name.getColumnNameOnly() != null
                        && !"*".equals(name.getColumnNameOnly())) {
                    out.add(new Ref(name, frame.aggregate, frame.branch));
                }
            } else if (type == EExpressionType.simple_constant_t) {
                // literal — no source
            } else if (type == EExpressionType.subquery_t) {
                // inner scope — out of single-block extraction scope
            } else if (type == EExpressionType.function_t
                    && e.getFunctionCall() != null) {
                pushFunction(stack, e.getFunctionCall(), frame);
            } else if (type == EExpressionType.case_t
                    && e.getCaseExpression() != null) {
                pushCase(stack, e.getCaseExpression(), frame);
            } else {
                // Generic operator/list node: reverse-push so the leftmost
                // child is processed first.
                List<TExpression> children = new ArrayList<TExpression>();
                if (e.getLeftOperand() != null) {
                    children.add(e.getLeftOperand());
                }
                if (e.getBetweenOperand() != null) {
                    children.add(e.getBetweenOperand());
                }
                if (e.getRightOperand() != null) {
                    children.add(e.getRightOperand());
                }
                if (e.getExprList() != null) {
                    for (int i = 0; i < e.getExprList().size(); i++) {
                        children.add(e.getExprList().getExpression(i));
                    }
                }
                for (int i = children.size() - 1; i >= 0; i--) {
                    stack.push(new Frame(children.get(i), frame.aggregate,
                            frame.branch));
                }
            }
        }
        return out;
    }

    /**
     * Function call: arguments inherit the aggregate flag when the
     * function reduces (plain aggregate, or a reducing window function —
     * contract §5 V1 counts windows "only when reducing, not ranking");
     * OVER-clause partition/order keys are value-shaping, never
     * aggregating (V3 TRANSFORM path).
     */
    private static void pushFunction(Deque<Frame> stack, TFunctionCall call,
                                     Frame frame) {
        String name = functionName(call);
        boolean reducing = AGGREGATE_FUNCTIONS.contains(name);
        boolean argAggregate = frame.aggregate || reducing;
        List<Frame> children = new ArrayList<Frame>();
        if (call.getArgs() != null) {
            for (int i = 0; i < call.getArgs().size(); i++) {
                children.add(new Frame(call.getArgs().getExpression(i),
                        argAggregate, frame.branch));
            }
        }
        if (call.getCastOperand() != null) {
            children.add(new Frame(call.getCastOperand(), argAggregate,
                    frame.branch));
        }
        TWindowDef window = call.getWindowDef();
        if (window != null) {
            TPartitionClause partition = window.getPartitionClause();
            if (partition != null && partition.getExpressionList() != null) {
                TExpressionList list = partition.getExpressionList();
                for (int i = 0; i < list.size(); i++) {
                    children.add(new Frame(list.getExpression(i),
                            frame.aggregate, frame.branch));
                }
            }
            TSortBy sortBy = window.getSortBy();
            if (sortBy != null && sortBy.getItems() != null) {
                for (int i = 0; i < sortBy.getItems().size(); i++) {
                    TOrderByItem item = (TOrderByItem)
                            sortBy.getItems().getElement(i);
                    children.add(new Frame(item.getSortKey(),
                            frame.aggregate, frame.branch));
                }
            }
            TOrderBy orderBy = window.getOrderBy();
            if (orderBy != null && orderBy.getItems() != null) {
                for (int i = 0; i < orderBy.getItems().size(); i++) {
                    children.add(new Frame(
                            orderBy.getItems().getOrderByItem(i)
                                    .getSortKey(),
                            frame.aggregate, frame.branch));
                }
            }
        }
        for (int i = children.size() - 1; i >= 0; i--) {
            stack.push(children.get(i));
        }
    }

    /**
     * CASE/IIF: WHEN conditions (and the comparand of a simple CASE)
     * flow through the condition branch (V2); THEN/ELSE results flow
     * through the value branch (V3). The innermost CASE decides the
     * branch of a nested reference.
     */
    private static void pushCase(Deque<Frame> stack, TCaseExpression ce,
                                 Frame frame) {
        List<Frame> children = new ArrayList<Frame>();
        if (ce.getInput_expr() != null) {
            children.add(new Frame(ce.getInput_expr(), frame.aggregate,
                    CaseBranch.CONDITION));
        }
        if (ce.getWhenClauseItemList() != null) {
            for (int i = 0; i < ce.getWhenClauseItemList().size(); i++) {
                TWhenClauseItem item = (TWhenClauseItem)
                        ce.getWhenClauseItemList().getElement(i);
                if (item.getComparison_expr() != null) {
                    children.add(new Frame(item.getComparison_expr(),
                            frame.aggregate, CaseBranch.CONDITION));
                }
                if (item.getReturn_expr() != null) {
                    children.add(new Frame(item.getReturn_expr(),
                            frame.aggregate, CaseBranch.VALUE));
                }
            }
        }
        if (ce.getElse_expr() != null) {
            children.add(new Frame(ce.getElse_expr(), frame.aggregate,
                    CaseBranch.VALUE));
        }
        for (int i = children.size() - 1; i >= 0; i--) {
            stack.push(children.get(i));
        }
    }

    /** Bare lower-cased function name (qualifier stripped). */
    private static String functionName(TFunctionCall call) {
        if (call.getFunctionName() == null) {
            return "";
        }
        String name = call.getFunctionName().toString();
        int dot = name.lastIndexOf('.');
        if (dot >= 0) {
            name = name.substring(dot + 1);
        }
        return name.toLowerCase(Locale.ROOT);
    }

    /**
     * Top-level AND conjuncts of a predicate, in source order. Iterative
     * left-chain descent (left-leaning tree from the left-recursive
     * grammar); parentheses around a conjunction are transparent.
     */
    private static List<TExpression> conjunctsOf(TExpression condition) {
        List<TExpression> out = new ArrayList<TExpression>();
        Deque<TExpression> stack = new ArrayDeque<TExpression>();
        stack.push(condition);
        while (!stack.isEmpty()) {
            TExpression e = stack.pop();
            if (e == null) {
                continue;
            }
            if (e.getExpressionType() == EExpressionType.logical_and_t) {
                if (e.getRightOperand() != null) {
                    stack.push(e.getRightOperand());
                }
                if (e.getLeftOperand() != null) {
                    stack.push(e.getLeftOperand());
                }
                continue;
            }
            if (e.getExpressionType() == EExpressionType.parenthesis_t
                    && e.getLeftOperand() != null
                    && e.getLeftOperand().getExpressionType()
                            == EExpressionType.logical_and_t) {
                stack.push(e.getLeftOperand());
                continue;
            }
            out.add(e);
        }
        return out;
    }

    /** {@code *} or {@code t.*} projection? */
    private static boolean isStar(TExpression expr) {
        if (expr.getExpressionType() != EExpressionType.simple_object_name_t
                || expr.getObjectOperand() == null) {
            return false;
        }
        String column = expr.getObjectOperand().getColumnNameOnly();
        return "*".equals(column);
    }
}