package gudusoft.gsqlparser.sqlenv;

import gudusoft.gsqlparser.EDbVendor;

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

/**
 * Canonical identity of a possibly-qualified SQL name — {@code db.schema.table},
 * {@code schema.table.column}, {@code t.c} — for use as a map or set key
 * (stage S0 of docs/refactor/identifier_identity_display_separation_plan.md).
 *
 * <p>It is the qualified counterpart of {@link CanonKey}: one {@code CanonKey} per
 * hierarchy level, each computed under the rules of <em>that level's</em> object type, plus
 * the terminal object type itself so that a table named {@code x} and a schema named
 * {@code x} cannot collide in one index. {@link CanonKey} carries an
 * {@link IdentifierProfile.ObjectGroup}, which is the right granularity for comparing
 * identifiers but deliberately coarser than the entity kind — hence the explicit terminal
 * discriminator here.
 *
 * <p><strong>There is no flattened identity string.</strong> The previous approach,
 * {@link IdentifierService#buildCompositeKey(String, ESQLDataObjectType)}, joins
 * already-normalized segment text; it cannot represent quote state, and its guard
 * {@link IdentifierService#canUseCompositeKey(String)} refuses every name containing a
 * quote character — which is exactly the case that loses lineage (MantisBT 4728). Joining
 * canonical segments back into a {@code String} would reintroduce both problems, so this
 * type keeps the segment keys as a list and nothing renders them.
 *
 * <h3>Equality</h3>
 * Two keys are equal iff they have the same terminal object type, the same number of levels, and
 * level-wise equal {@link CanonKey}s. Since {@code CanonKey} equality IS the canonical
 * single-segment equality relation (unification-plan stage P0d.1), each LEVEL compares correctly.
 *
 * <p><strong>That does not make the whole key agree with
 * {@link gudusoft.gsqlparser.util.SQLUtil#compareIdentifier}, and it does not make it correct.</strong>
 * Two things are still decided outside the per-level comparison: how the name is split into
 * segments, and which object type each position is compared as. The S0 proof test measures the
 * agreement over every vendor, every mapped object type and every ordered pair of shapes, and
 * pins each divergence with its cause — but agreement with {@code compareIdentifier} is not
 * proof of correctness, because both can be wrong together.
 *
 * <p>They ARE wrong together in one known case, which this type cannot currently fix: the role of
 * each position is inferred from the vendor, the terminal type and the arity alone. For a
 * two-segment column name that guesses {@code table.column}, but BigQuery
 * {@code customer.name} is a STRUCT field access — base column {@code customer} plus field
 * {@code name} (see {@code FieldPath} and {@code TestBigQueryNestedColumns}) — and the two read
 * the first segment under different case rules. Fixing it needs an explicit semantic role per
 * component, taken from resolution rather than from syntax; that is scheduled before S2 and is
 * why {@code compareIdentifier} must NOT be made to delegate to the planner first.
 *
 * <h3>Provenance</h3>
 * Build one through the explicitly named factories
 * {@link IdentifierService#qualifiedCanonKeyFromLexical(String, ESQLDataObjectType)} —
 * for a name as written in SQL — or
 * {@link IdentifierService#qualifiedCanonKeyFromStored(java.util.List, ESQLDataObjectType)} — for
 * a name already in the form a catalog stores, passed as one entry per level. The two are not interchangeable: keying a
 * Snowflake catalog object from an already-decoded {@code foo} is not the same as keying
 * the SQL lexical {@code "foo"}. There is deliberately no factory that guesses.
 *
 * <p><strong>In-process only</strong>, for the same reason as {@link CanonKey}: collation
 * payloads are stable only within one JVM and collator configuration. Use
 * {@link PersistentIdentifierKey} for anything persisted or exchanged.
 */
public final class QualifiedCanonKey {

    private final List<CanonKey> segmentKeys;
    private final ESQLDataObjectType terminalType;
    private final int hash;

    QualifiedCanonKey(List<CanonKey> segmentKeys, ESQLDataObjectType terminalType) {
        this.segmentKeys = Collections.unmodifiableList(new ArrayList<CanonKey>(segmentKeys));
        this.terminalType = terminalType;
        this.hash = 31 * this.segmentKeys.hashCode() + terminalType.hashCode();
    }

    /** The per-level canonical keys, outermost container first. Never empty. */
    public List<CanonKey> getSegmentKeys() {
        return segmentKeys;
    }

    /** The kind of object the whole name denotes — the entity-kind discriminator. */
    public ESQLDataObjectType getTerminalType() {
        return terminalType;
    }

    /** Number of hierarchy levels this name resolved to. */
    public int size() {
        return segmentKeys.size();
    }

    /** The vendor rule domain; all levels share it. */
    public EDbVendor getVendor() {
        return segmentKeys.get(0).getVendor();
    }

    /**
     * The key of the innermost level — the column of {@code t.c}, the table of
     * {@code s.t}. Useful for indexes that bucket by container and then by leaf name.
     */
    public CanonKey getLeafKey() {
        return segmentKeys.get(segmentKeys.size() - 1);
    }

    @Override
    public boolean equals(Object o) {
        if (this == o) {
            return true;
        }
        if (o == null || getClass() != o.getClass()) {
            return false;
        }
        QualifiedCanonKey that = (QualifiedCanonKey) o;
        return terminalType == that.terminalType && segmentKeys.equals(that.segmentKeys);
    }

    @Override
    public int hashCode() {
        return hash;
    }

    @Override
    public String toString() {
        StringBuilder sb = new StringBuilder("QualifiedCanonKey{").append(terminalType).append(' ');
        for (int i = 0; i < segmentKeys.size(); i++) {
            if (i > 0) {
                sb.append(" / ");
            }
            sb.append(segmentKeys.get(i));
        }
        return sb.append('}').toString();
    }
}