package gudusoft.gsqlparser.dlineage.dynamicsql;

import java.util.Collections;
import java.util.Set;
import java.util.TreeSet;

/**
 * One boundary→boundary symbolic edge of a {@link RoutineSummary}
 * (design {@code routine-summary-scc-design.md} §2.2): the reachability
 * quotient of the routine's analyzed relation graph, interior nodes
 * (locals, cursor/record columns, intermediate result sets, function hops)
 * composed away.
 *
 * <p>Relation semantics mirror the inline engine: a boundary pair connected
 * by at least one all-{@code fdd} path carries an {@code fdd} edge, and a
 * pair connected by at least one path containing an {@code fdr} hop carries
 * an {@code fdr} edge — the two COEXIST exactly as dlineage's own fdd/fdr
 * relationships do (never OR-merged; §4.1 ROW-dominates applies per chain,
 * not per pair).
 */
public final class RoutineSummaryEdge {

    /** B5 advisory-metadata top: observed function names exceeded the finite
     *  bound. The candidate edge survives widening; function order/path
     *  attribution was never claimed. */
    public static final String OBSERVED_FUNCTIONS_TOP = "OBSERVED_FUNCTIONS_TOP";
    /** @deprecated use {@link #OBSERVED_FUNCTIONS_TOP}. */
    @Deprecated
    public static final String TRANSFORM_TOP = OBSERVED_FUNCTIONS_TOP;

    /** Boundary endpoint classes of the B2 quotient (§2.2 endpoint table). */
    public enum EndpointKind {
        /** Declared formal parameter of the routine (any mode). */
        FORMAL,
        /** Physical (catalog) table column. */
        TABLE_COLUMN,
        /** Caller-visible temporary / table-variable column. */
        TEMP_COLUMN,
        /** Terminal result-set column identified by its recorded output name.
         *  Positional projection is allowed only after a unique-shape preflight. */
        RESULT_SET_COLUMN
    }

    /** One boundary endpoint: kind + resolved parent name + column name. */
    public static final class Endpoint implements Comparable<Endpoint> {
        private final EndpointKind kind;
        private final String parent;
        private final String column;

        public Endpoint(EndpointKind kind, String parent, String column) {
            this.kind = kind;
            this.parent = parent == null ? "" : parent;
            this.column = column == null ? "" : column;
        }

        public EndpointKind getKind() { return kind; }
        public String getParent() { return parent; }
        public String getColumn() { return column; }

        @Override
        public boolean equals(Object o) {
            if (this == o) {
                return true;
            }
            if (!(o instanceof Endpoint)) {
                return false;
            }
            Endpoint e = (Endpoint) o;
            // Names here are the analyzer's resolved display names captured
            // from ONE model instance — string-identical by construction, so
            // plain equality is correct (no re-normalization of identifiers).
            return kind == e.kind && parent.equals(e.parent) && column.equals(e.column);
        }

        @Override
        public int hashCode() {
            return (kind.hashCode() * 31 + parent.hashCode()) * 31 + column.hashCode();
        }

        @Override
        public int compareTo(Endpoint o) {
            int c = kind.compareTo(o.kind);
            if (c != 0) return c;
            c = parent.compareTo(o.parent);
            if (c != 0) return c;
            return column.compareTo(o.column);
        }

        @Override
        public String toString() {
            return kind + ":" + parent + "." + column;
        }
    }

    private final Endpoint source;
    private final Endpoint target;
    /** {@code "fdd"} (value path) or {@code "fdr"} (row-affecting path). */
    private final String relationType;
    /**
     * Function hops observed on contributing value paths. ADVISORY ONLY in
     * B2: an unordered union across all paths is not a composable transform
     * descriptor (it loses order, multiplicity, and per-path attribution).
     * Never use this field for equality, caching, or application decisions.
     * B5 bounds this advisory union and
     * widens it to {@link #OBSERVED_FUNCTIONS_TOP}; ordered, per-path transform
     * descriptors remain future work.
     */
    private final Set<String> observedFunctions;

    public RoutineSummaryEdge(Endpoint source, Endpoint target, String relationType,
            Set<String> functions) {
        this.source = source;
        this.target = target;
        this.relationType = relationType;
        this.observedFunctions = functions == null
                ? Collections.<String>emptySet()
                : Collections.unmodifiableSet(new TreeSet<String>(functions));
    }

    public Endpoint getSource() { return source; }
    public Endpoint getTarget() { return target; }
    public String getRelationType() { return relationType; }
    /** Unordered advisory union of function names observed on contributing
     *  value paths. It is not an ordered transform descriptor. */
    public Set<String> getObservedFunctions() { return observedFunctions; }

    /** @deprecated use {@link #getObservedFunctions()}; retained for source
     *  compatibility with the B2/B3 summary API. */
    @Deprecated
    public Set<String> getFunctions() { return observedFunctions; }

    public boolean isObservedFunctionsTop() {
        return observedFunctions.contains(OBSERVED_FUNCTIONS_TOP);
    }

    /** @deprecated use {@link #isObservedFunctionsTop()}. */
    @Deprecated
    public boolean isTransformTop() {
        return isObservedFunctionsTop();
    }

    /**
     * Join value metadata for two edges with the same edge identity. The
     * identity itself deliberately excludes advisory function metadata; once the finite
     * advisory-name bound is exceeded the value widens to
     * {@link #OBSERVED_FUNCTIONS_TOP} and can never narrow again. This gives
     * recursive summary composition finite metadata height while preserving
     * the lineage edge. No function order or per-path attribution is implied.
     */
    RoutineSummaryEdge joinMetadata(RoutineSummaryEdge other,
            int maxObservedFunctions) {
        if (!equals(other)) {
            throw new IllegalArgumentException("cannot join different summary edges");
        }
        if (isObservedFunctionsTop() || other.isObservedFunctionsTop()) {
            return new RoutineSummaryEdge(source, target, relationType,
                    Collections.singleton(OBSERVED_FUNCTIONS_TOP));
        }
        Set<String> joined = new TreeSet<String>(observedFunctions);
        joined.addAll(other.observedFunctions);
        if (joined.size() > maxObservedFunctions) {
            joined = Collections.singleton(OBSERVED_FUNCTIONS_TOP);
        }
        return new RoutineSummaryEdge(source, target, relationType, joined);
    }

    /** Identity is (source, target, relationType) — §2.5 edge identity; the
     *  observed-function set is advisory metadata joined by union, not identity. */
    @Override
    public boolean equals(Object o) {
        if (this == o) {
            return true;
        }
        if (!(o instanceof RoutineSummaryEdge)) {
            return false;
        }
        RoutineSummaryEdge e = (RoutineSummaryEdge) o;
        // non-identifier-compare: relationType is a fixed enum-like token
        return source.equals(e.source) && target.equals(e.target)
                && relationType.equals(e.relationType);
    }

    @Override
    public int hashCode() {
        return (source.hashCode() * 31 + target.hashCode()) * 31 + relationType.hashCode();
    }

    @Override
    public String toString() {
        return source + " -" + relationType + "-> " + target
                // Preserve the established rendering; the accessor/Javadoc carry
                // the stricter advisory-only semantics without breaking logs.
                + (observedFunctions.isEmpty() ? "" : " via " + observedFunctions);
    }
}