package gudusoft.gsqlparser.catalog.runtime;

import gudusoft.gsqlparser.sqlenv.IdentifierComponentRole;

import java.util.ArrayList;
import java.util.EnumSet;
import java.util.List;
import java.util.Set;

/**
 * Whole-shape validation of a catalog name (stage S0R of
 * docs/refactor/identifier_identity_display_separation_plan.md).
 *
 * <h3>Why whole-shape, and why two entry points</h3>
 * A pairwise "may this role follow that one" predicate cannot express the rules that matter — at
 * most one of each container, the terminal agreeing with the declared kind, kind-dependent nesting,
 * and above all whether the name is COMPLETE. Completeness is not a property of adjacent pairs; it
 * is a property of the component list measured against the topology the namespace declares.
 *
 * <p>A resolved IDENTITY and a LOOKUP are different languages. A lookup may omit levels — {@code t},
 * {@code s.t} and {@code db..t} are all normal. An identity may not: every level its topology
 * declares must be named, because an unresolved level inside a key silently binds to whatever the
 * session default happened to be, and then collides with the same name in another schema.
 */
public final class CatalogNameGrammar {

    /** Kinds that own columns. */
    private static final Set<CatalogObjectKind> RELATIONS = EnumSet.of(
            CatalogObjectKind.TABLE, CatalogObjectKind.VIEW, CatalogObjectKind.MATERIALIZED_VIEW);

    /** Kinds that own routines. */
    private static final Set<CatalogObjectKind> ROUTINE_CONTAINERS = EnumSet.of(
            CatalogObjectKind.PACKAGE);

    /** Kinds a routine container may own. */
    private static final Set<CatalogObjectKind> ROUTINE_MEMBERS = EnumSet.of(
            CatalogObjectKind.ROUTINE, CatalogObjectKind.FUNCTION, CatalogObjectKind.PROCEDURE);

    /** Kinds a relation may own as a child object. */
    private static final Set<CatalogObjectKind> RELATION_CHILDREN = EnumSet.of(
            CatalogObjectKind.INDEX, CatalogObjectKind.CONSTRAINT);

    /**
     * Kinds an {@link IdentifierComponentRole#OBJECT} component may carry. CATALOG, SCHEMA and
     * COLUMN are excluded: those have their own roles, and allowing them as OBJECT kinds would give
     * one entity two spellings of its identity — {@code OBJECT(COLUMN)} also slips past the rule
     * that a bare column is not a complete identity.
     */
    private static final Set<CatalogObjectKind> OBJECT_KINDS;

    static {
        Set<CatalogObjectKind> kinds = EnumSet.allOf(CatalogObjectKind.class);
        kinds.remove(CatalogObjectKind.CATALOG);
        kinds.remove(CatalogObjectKind.SCHEMA);
        kinds.remove(CatalogObjectKind.COLUMN);
        OBJECT_KINDS = java.util.Collections.unmodifiableSet(kinds);
    }

    private CatalogNameGrammar() {
    }

    /** Whether this kind owns columns. */
    public static boolean isRelation(CatalogObjectKind kind) {
        return kind != null && RELATIONS.contains(kind);
    }

    /** Whether a kind may be carried by an OBJECT component. */
    public static boolean isObjectKind(CatalogObjectKind kind) {
        return kind != null && OBJECT_KINDS.contains(kind);
    }

    /**
     * Whether {@code container} may directly contain {@code child} as an object — the ONE transition
     * table, shared by resolved identities and lookups so the two cannot disagree about what nests.
     */
    public static boolean mayContainObject(CatalogObjectKind container, CatalogObjectKind child) {
        if (container == null || child == null) {
            return false;
        }
        return (ROUTINE_CONTAINERS.contains(container) && ROUTINE_MEMBERS.contains(child))
                || (RELATIONS.contains(container) && RELATION_CHILDREN.contains(child));
    }

    /**
     * The family a NESTED object of this kind must have as its parent.
     *
     * <p><strong>This does not decide whether the object IS nested.</strong> That is a property of
     * the name's shape, not of the kind: a FUNCTION may sit directly in a schema or inside a package,
     * and an INDEX may be named at schema level or under its relation. An earlier version used this
     * method to decide existence, which rejected every schema-level function and — because a TABLE
     * is not a "child kind" — accepted {@code PACKAGE.TABLE} without ever examining the extra
     * component.
     *
     * @return the required family, or null when no nesting of this kind is modelled
     */
    public static CatalogParentConstraint nestedParentFamilyFor(CatalogObjectKind childKind) {
        if (childKind == CatalogObjectKind.COLUMN || RELATION_CHILDREN.contains(childKind)) {
            return CatalogParentConstraint.RELATION;
        }
        if (ROUTINE_MEMBERS.contains(childKind)) {
            return CatalogParentConstraint.ROUTINE_CONTAINER;
        }
        return null;
    }

    /** @deprecated renamed to {@link #nestedParentFamilyFor}, which says what it actually answers. */
    @Deprecated
    public static CatalogParentConstraint parentConstraintFor(CatalogObjectKind childKind) {
        return nestedParentFamilyFor(childKind);
    }

    // ------------------------------------------------------------------ resolved identity

    /**
     * Validates a RESOLVED identity: legal roles, legal nesting, and COMPLETE against the declared
     * topology.
     *
     * @param roles        one role per component, outermost first
     * @param kinds        the entity kind at each position; null except at OBJECT positions
     * @param terminalKind what the name denotes as a whole
     * @param hierarchy    which container levels the namespace HAS — declared by the caller, because
     *                     the component list cannot distinguish "this dialect has no schema" from
     *                     "the schema was not resolved"
     * @throws IllegalArgumentException naming the first rule broken
     */
    public static void validateResolvedIdentity(List<IdentifierComponentRole> roles,
                                                List<CatalogObjectKind> kinds,
                                                CatalogObjectKind terminalKind,
                                                CatalogHierarchy hierarchy) {
        if (roles == null || roles.isEmpty()) {
            throw new IllegalArgumentException("an identity needs at least one component");
        }
        if (kinds == null || kinds.size() != roles.size()) {
            throw new IllegalArgumentException("every component needs a kind slot (null for "
                    + "non-OBJECT roles): " + roles.size() + " roles, "
                    + (kinds == null ? "no" : String.valueOf(kinds.size())) + " kinds");
        }
        if (terminalKind == null) {
            throw new IllegalArgumentException("an identity must declare what it denotes");
        }
        if (hierarchy == null) {
            throw new IllegalArgumentException("an identity must declare its namespace topology: "
                    + "whether db.t is complete depends on whether the namespace has a schema level, "
                    + "and the component list cannot say");
        }

        Set<IdentifierComponentRole> containersSeen = EnumSet.noneOf(IdentifierComponentRole.class);
        for (int i = 0; i < roles.size(); i++) {
            IdentifierComponentRole role = roles.get(i);
            CatalogObjectKind kind = kinds.get(i);
            if (role == null) {
                throw new IllegalArgumentException("component " + i + " has no role");
            }
            if (role == IdentifierComponentRole.DATABASE_LINK) {
                throw new IllegalArgumentException("a database link is a postfix qualifier, not an "
                        + "ordered component; pass it separately");
            }
            if (role == IdentifierComponentRole.STRUCT_FIELD) {
                throw new IllegalArgumentException("a struct field belongs to a column path, not to "
                        + "a catalog identity");
            }
            if ((role == IdentifierComponentRole.OBJECT) != (kind != null)) {
                throw new IllegalArgumentException("component " + i + " is " + role
                        + " but " + (kind == null ? "has no kind" : "carries kind " + kind)
                        + "; exactly the OBJECT components carry a kind");
            }
            if (role == IdentifierComponentRole.OBJECT && !isObjectKind(kind)) {
                throw new IllegalArgumentException("component " + i + ": " + kind + " is not an "
                        + "object kind — a catalog, a schema and a column each have their own role, "
                        + "so carrying one as an OBJECT kind would give it a second identity");
            }
            if (role == IdentifierComponentRole.SERVER || role == IdentifierComponentRole.CATALOG
                    || role == IdentifierComponentRole.SCHEMA) {
                if (!containersSeen.add(role)) {
                    throw new IllegalArgumentException("two " + role + " components");
                }
                // SERVER is an endpoint qualifier, not a topology level, so it is never contradicted.
                if (role != IdentifierComponentRole.SERVER && !hierarchy.has(role)) {
                    throw new IllegalArgumentException("the declared topology " + hierarchy
                            + " has no " + role + " level, so naming one is a contradiction");
                }
            }
            if (i > 0) {
                requireLegalStep(roles.get(i - 1), kinds.get(i - 1), role, kind, i);
            } else if (role == IdentifierComponentRole.BASE_COLUMN) {
                throw new IllegalArgumentException("a bare column is not a complete catalog "
                        + "identity: a column is scoped by its relation. Key it inside that "
                        + "relation, or build a lookup instead");
            }
        }

        requireTerminalAgrees(roles, kinds, terminalKind);
        requireComplete(roles, containersSeen, terminalKind, hierarchy);
    }

    /**
     * Every container level the topology declares, and that sits ABOVE the terminal's own level,
     * must be named. This is the completeness rule: it is what makes {@code db.t} a complete MySQL
     * table identity and an INCOMPLETE Oracle one.
     *
     * <p>SERVER is exempt: its absence means the local server, not a missing level.
     */
    private static void requireComplete(List<IdentifierComponentRole> roles,
                                        Set<IdentifierComponentRole> containersSeen,
                                        CatalogObjectKind terminalKind,
                                        CatalogHierarchy hierarchy) {
        IdentifierComponentRole outermostNeeded = outermostRequiredContainer(roles);
        for (IdentifierComponentRole container : hierarchy.containers()) {
            if (!isAbove(container, outermostNeeded)) {
                continue;
            }
            if (!containersSeen.contains(container)) {
                throw new IllegalArgumentException("the declared topology " + hierarchy
                        + " has a " + container + " level and this " + terminalKind
                        + " identity does not name it. An unnamed level is not resolved, and an "
                        + "identity containing an unresolved level silently binds to whatever the "
                        + "session default happened to be — build a CatalogLookupName instead");
            }
        }
    }

    /**
     * The level the name's own content starts at: a catalog identity needs nothing above it, a
     * schema identity needs the catalog, an object or column identity needs both.
     */
    private static IdentifierComponentRole outermostRequiredContainer(List<IdentifierComponentRole> roles) {
        IdentifierComponentRole first = roles.get(0);
        for (IdentifierComponentRole role : roles) {
            if (role == IdentifierComponentRole.OBJECT
                    || role == IdentifierComponentRole.BASE_COLUMN) {
                return IdentifierComponentRole.SCHEMA;
            }
            if (role == IdentifierComponentRole.SCHEMA) {
                return IdentifierComponentRole.CATALOG;
            }
        }
        return first == IdentifierComponentRole.CATALOG || first == IdentifierComponentRole.SERVER
                ? null : IdentifierComponentRole.CATALOG;
    }

    /** Whether {@code container} is at or above {@code level}; a null level requires nothing. */
    private static boolean isAbove(IdentifierComponentRole container, IdentifierComponentRole level) {
        if (level == null) {
            return false;
        }
        if (container == IdentifierComponentRole.CATALOG) {
            return true;
        }
        return container == IdentifierComponentRole.SCHEMA
                && level == IdentifierComponentRole.SCHEMA;
    }

    private static void requireTerminalAgrees(List<IdentifierComponentRole> roles,
                                              List<CatalogObjectKind> kinds,
                                              CatalogObjectKind terminalKind) {
        IdentifierComponentRole lastRole = roles.get(roles.size() - 1);
        CatalogObjectKind lastKind = kinds.get(kinds.size() - 1);
        if (lastRole == IdentifierComponentRole.BASE_COLUMN) {
            if (terminalKind != CatalogObjectKind.COLUMN) {
                throw new IllegalArgumentException("the name ends in a column but the key declares "
                        + terminalKind);
            }
            return;
        }
        if (lastRole == IdentifierComponentRole.OBJECT) {
            if (lastKind != terminalKind) {
                throw new IllegalArgumentException("the terminal component is " + lastKind
                        + " but the key declares " + terminalKind);
            }
            return;
        }
        CatalogObjectKind expected = lastRole == IdentifierComponentRole.CATALOG
                ? CatalogObjectKind.CATALOG
                : lastRole == IdentifierComponentRole.SCHEMA ? CatalogObjectKind.SCHEMA : null;
        if (expected == null) {
            throw new IllegalArgumentException("a name cannot end with " + lastRole);
        }
        if (terminalKind != expected) {
            throw new IllegalArgumentException("the name ends in a " + lastRole
                    + " but the key declares " + terminalKind);
        }
    }

    private static void requireLegalStep(IdentifierComponentRole previous, CatalogObjectKind previousKind,
                                         IdentifierComponentRole role, CatalogObjectKind kind, int at) {
        switch (previous) {
            case SERVER:
                if (role != IdentifierComponentRole.CATALOG) {
                    throw new IllegalArgumentException("component " + at + ": only a catalog may "
                            + "follow a server in a resolved identity, not " + role
                            + " (a skipped level is an omission, and omissions belong to a lookup)");
                }
                return;
            case CATALOG:
                if (role != IdentifierComponentRole.SCHEMA && role != IdentifierComponentRole.OBJECT) {
                    throw new IllegalArgumentException("component " + at + ": a catalog contains a "
                            + "schema, or an object on schemaless dialects, not " + role);
                }
                return;
            case SCHEMA:
                if (role != IdentifierComponentRole.OBJECT) {
                    throw new IllegalArgumentException("component " + at + ": a schema contains "
                            + "objects, not " + role);
                }
                return;
            case OBJECT:
                if (role == IdentifierComponentRole.BASE_COLUMN) {
                    if (!isRelation(previousKind)) {
                        throw new IllegalArgumentException("component " + at + ": a " + previousKind
                                + " has no columns; only a table, view or materialized view does");
                    }
                    return;
                }
                if (role == IdentifierComponentRole.OBJECT) {
                    boolean routineMember = ROUTINE_CONTAINERS.contains(previousKind)
                            && ROUTINE_MEMBERS.contains(kind);
                    boolean relationChild = isRelation(previousKind)
                            && RELATION_CHILDREN.contains(kind);
                    if (!routineMember && !relationChild) {
                        throw new IllegalArgumentException("component " + at + ": a " + previousKind
                                + " does not contain a " + kind
                                + "; only PACKAGE->ROUTINE/FUNCTION/PROCEDURE and "
                                + "relation->INDEX/CONSTRAINT nest");
                    }
                    return;
                }
                throw new IllegalArgumentException("component " + at + ": an object cannot contain "
                        + role);
            case BASE_COLUMN:
                throw new IllegalArgumentException("component " + at + ": a column contains nothing "
                        + "in a catalog identity (a struct path belongs to a column-path key)");
            default:
                throw new IllegalArgumentException("component " + at + ": " + previous
                        + " cannot contain anything");
        }
    }

    // ------------------------------------------------------------------------ lookup

    /**
     * Validates a LOOKUP. Unlike the identity form it accepts omissions, but it still has to be a
     * name that could denote something: the slots must be in hierarchy order, each role may appear
     * once, every applicable level must have an explicit state, a PRESENT slot must actually carry
     * text and provenance, and the terminal must be PRESENT and agree with what is being sought.
     *
     * <p>The previous version of this method received only a list of slot STATES, so it could check
     * nothing but "is something present" — it admitted a schema before a catalog, a duplicate
     * catalog, {@code OBJECT(TABLE)} under terminal {@code PROCEDURE}, and an omitted terminal.
     *
     * @param slots        the slots, outermost first
     * @param terminalKind what is being looked for
     * @param hierarchy    the declared topology
     * @param databaseLink the link text, or null
     * @param linkForm     the link's provenance; required when the link is present
     */
    public static void validateLookup(List<CatalogLookupName.Slot> slots,
                                      CatalogObjectKind terminalKind,
                                      CatalogHierarchy hierarchy,
                                      String databaseLink,
                                      gudusoft.gsqlparser.sqlenv.IdentifierInputForm linkForm,
                                      CatalogParentConstraint parentConstraint) {
        if (slots == null || slots.isEmpty()) {
            throw new IllegalArgumentException("a lookup needs at least one slot");
        }
        if (terminalKind == null) {
            throw new IllegalArgumentException("a lookup must say what kind it is looking for");
        }
        if (hierarchy == null) {
            throw new IllegalArgumentException("a lookup must declare its namespace topology");
        }

        Set<IdentifierComponentRole> seen = EnumSet.noneOf(IdentifierComponentRole.class);
        int lastRank = -1;
        int objectSlots = 0;
        for (int i = 0; i < slots.size(); i++) {
            CatalogLookupName.Slot slot = slots.get(i);
            if (slot == null) {
                throw new IllegalArgumentException("slot " + i + " is null; use absent(role)");
            }
            IdentifierComponentRole role = slot.getRole();
            if (role == IdentifierComponentRole.DATABASE_LINK
                    || role == IdentifierComponentRole.STRUCT_FIELD) {
                throw new IllegalArgumentException("slot " + i + ": " + role + " is never an "
                        + "ordered catalog slot");
            }
            // OBJECT is the one role that may repeat, and only once: a relation plus its index or
            // constraint, or a package plus its routine. Every other role names a single level.
            if (role == IdentifierComponentRole.OBJECT) {
                if (++objectSlots > 2) {
                    throw new IllegalArgumentException("more than two object slots: a catalog name "
                            + "nests at most a container object and one child");
                }
            } else if (!seen.add(role)) {
                throw new IllegalArgumentException("two " + role + " slots");
            }
            int rank = rankOf(role);
            boolean repeatedObject = role == IdentifierComponentRole.OBJECT && objectSlots == 2;
            if (rank < lastRank || (rank == lastRank && !repeatedObject)) {
                throw new IllegalArgumentException("slot " + i + ": " + role + " is out of "
                        + "hierarchy order");
            }
            lastRank = rank;

            boolean present = slot.getState() == CatalogLookupName.SlotState.PRESENT;
            boolean hasText = slot.getText() != null && !slot.getText().isEmpty();
            if (present != hasText) {
                throw new IllegalArgumentException("slot " + i + " (" + role + ") is "
                        + slot.getState() + " but " + (hasText ? "carries text" : "has no text"));
            }
            if (present && slot.getForm() == null) {
                throw new IllegalArgumentException("slot " + i + " (" + role + ") is PRESENT "
                        + "without provenance");
            }
            if (!present && slot.getForm() != null) {
                throw new IllegalArgumentException("slot " + i + " (" + role + ") is "
                        + slot.getState() + " but carries provenance");
            }
            if (!present && slot.getKind() != null) {
                throw new IllegalArgumentException("slot " + i + " (" + role + ") is "
                        + slot.getState() + " but carries a kind");
            }
            boolean terminalSlot = i == slots.size() - 1;
            if (role == IdentifierComponentRole.OBJECT && present) {
                if (slot.getKind() == null) {
                    // A non-terminal object whose exact kind resolution has not established yet.
                    // The request must then carry the FAMILY it is constrained to, because
                    // "some object" with no constraint at all names nothing in particular.
                    if (terminalSlot) {
                        throw new IllegalArgumentException("slot " + i + ": the terminal object "
                                + "must state its kind — that is what the lookup is seeking");
                    }
                    if (parentConstraint == null) {
                        throw new IllegalArgumentException("slot " + i + ": a container object with "
                                + "no exact kind needs a parent constraint stating its family; a "
                                + "flat name cannot say whether a column's parent is a table, a "
                                + "view or a materialized view, and guessing is the defect");
                    }
                } else if (!isObjectKind(slot.getKind())) {
                    throw new IllegalArgumentException("slot " + i + ": " + slot.getKind()
                            + " is not an object kind");
                }
            }
            boolean topologyLevel = role == IdentifierComponentRole.CATALOG
                    || role == IdentifierComponentRole.SCHEMA;
            if (slot.getState() == CatalogLookupName.SlotState.ABSENT && topologyLevel
                    && hierarchy.has(role)) {
                throw new IllegalArgumentException("slot " + i + ": " + role + " is marked ABSENT "
                        + "but the declared topology " + hierarchy + " has that level; an existing "
                        + "level that was not named is OMITTED, not ABSENT");
            }
            if (slot.getState() != CatalogLookupName.SlotState.ABSENT && topologyLevel
                    && !hierarchy.has(role)) {
                throw new IllegalArgumentException("slot " + i + ": the declared topology "
                        + hierarchy + " has no " + role + " level, so it can only be ABSENT");
            }
        }

        CatalogLookupName.Slot terminal = slots.get(slots.size() - 1);
        if (terminal.getState() != CatalogLookupName.SlotState.PRESENT) {
            throw new IllegalArgumentException("the terminal slot (" + terminal.getRole()
                    + ") is " + terminal.getState() + "; a lookup with no named leaf names nothing");
        }
        // The terminal question comes FIRST: "your name ends in a catalog but you say you seek a
        // schema" is a more fundamental contradiction than any missing level, and reporting the
        // missing level instead would send the reader after the wrong problem.
        requireTerminalSlotAgrees(terminal, terminalKind);

        // Every applicable container level AT OR ABOVE the terminal must have an explicit state,
        // scoped to match what the builder emits: a catalog lookup has no schema level to state, and
        // requiring one made the validator contradict the builder.
        for (IdentifierComponentRole container : hierarchy.containers()) {
            if (levelAppliesTo(container, terminalKind) && !seen.contains(container)) {
                throw new IllegalArgumentException("the declared topology " + hierarchy + " has a "
                        + container + " level with no slot; state it as PRESENT or OMITTED rather "
                        + "than leaving it unrepresented");
            }
        }

        requireChildStructure(slots, terminalKind, parentConstraint);

        if (databaseLink != null) {
            if (databaseLink.isEmpty()) {
                throw new IllegalArgumentException("a database link with no text is not a link");
            }
            if (linkForm == null) {
                throw new IllegalArgumentException("a database link needs its provenance");
            }
            requireLinkableLookupTerminal(slots, terminalKind, parentConstraint);
        }
    }

    /**
     * Which LOOKUP shapes may carry a database link.
     *
     * <p>A remote relation, synonym or routine obviously may. A COLUMN may too — {@code TObjectName}
     * documents {@code schema.object.part@dblink} as a real AST shape, and {@code SELECT c FROM
     * t@remote} makes the column reachable — but only when the request actually names a relation
     * parent for it. Resolution then attaches the link to the relation identity and composes the
     * column onto it, which is how the resolved side already works. COLUMN is NOT declared linkable
     * in general: a column with no relation parent has nothing for the link to qualify.
     */
    private static void requireLinkableLookupTerminal(List<CatalogLookupName.Slot> slots,
                                                      CatalogObjectKind terminalKind,
                                                      CatalogParentConstraint parentConstraint) {
        if (terminalKind != CatalogObjectKind.COLUMN) {
            requireLinkableTerminal(terminalKind);
            return;
        }
        CatalogLookupName.Slot relation = null;
        for (CatalogLookupName.Slot slot : slots) {
            if (slot.getRole() == IdentifierComponentRole.OBJECT) {
                relation = slot;
            }
        }
        // The relation must be NAMED, not merely modelled: an omitted relation means the link has
        // nothing concrete to attach to yet, and a resolver must supply the relation first.
        if (relation == null || relation.getState() != CatalogLookupName.SlotState.PRESENT
                || parentConstraint == null
                || !CatalogParentConstraint.RELATION.allowedKinds()
                        .containsAll(parentConstraint.allowedKinds())) {
            throw new IllegalArgumentException("a database link on a column qualifies the column's "
                    + "RELATION, so the request must name that relation; a column with no relation "
                    + "parent has nothing for the link to qualify");
        }
    }

    /**
     * The container roles in scope for a name seeking this kind, outermost first — the SINGLE source
     * of that rule (stage S0R).
     *
     * <p>Topology answers which levels EXIST; this answers which are in scope for a particular
     * terminal, which is a grammar question. The two lived in two copies for one round and disagreed
     * once, caught only by a test: the builder stopped the vector at the terminal while the validator
     * still demanded every level. Both now consume this.
     *
     * <p>{@link IdentifierComponentRole#SERVER} is not here: it qualifies the endpoint rather than
     * occupying a level, and is handled separately.
     */
    static List<IdentifierComponentRole> scopedContainerRoles(CatalogObjectKind terminalKind) {
        if (terminalKind == CatalogObjectKind.CATALOG) {
            return java.util.Collections.singletonList(IdentifierComponentRole.CATALOG);
        }
        return java.util.Collections.unmodifiableList(java.util.Arrays.asList(
                IdentifierComponentRole.CATALOG, IdentifierComponentRole.SCHEMA));
    }

    /** Whether a container level is in scope for a name seeking this kind. */
    static boolean levelAppliesTo(IdentifierComponentRole container, CatalogObjectKind terminalKind) {
        return container == IdentifierComponentRole.SERVER
                || scopedContainerRoles(terminalKind).contains(container);
    }

    /** The terminal slot's role and kind must agree with what the lookup says it seeks. */
    private static void requireTerminalSlotAgrees(CatalogLookupName.Slot terminal,
                                                  CatalogObjectKind terminalKind) {
        switch (terminal.getRole()) {
            case BASE_COLUMN:
                if (terminalKind != CatalogObjectKind.COLUMN) {
                    throw new IllegalArgumentException("the lookup ends in a column but seeks "
                            + terminalKind);
                }
                return;
            case OBJECT:
                if (terminal.getKind() != terminalKind) {
                    throw new IllegalArgumentException("the terminal slot is " + terminal.getKind()
                            + " but the lookup seeks " + terminalKind);
                }
                return;
            case CATALOG:
                if (terminalKind != CatalogObjectKind.CATALOG) {
                    throw new IllegalArgumentException("the lookup ends in a catalog but seeks "
                            + terminalKind);
                }
                return;
            case SCHEMA:
                if (terminalKind != CatalogObjectKind.SCHEMA) {
                    throw new IllegalArgumentException("the lookup ends in a schema but seeks "
                            + terminalKind);
                }
                return;
            default:
                throw new IllegalArgumentException("a lookup cannot end with " + terminal.getRole());
        }
    }

    /**
     * Validates nesting from the name's SHAPE rather than from its terminal kind.
     *
     * <p>The shape says whether the terminal is nested; the kind only says which family the parent
     * must then belong to. Reading it the other way round produced two opposite errors at once: a
     * schema-level {@code FUNCTION} was rejected for lacking a package, and {@code PACKAGE.TABLE} was
     * accepted because a table is not a "child kind" and the surplus component was never examined.
     */
    private static void requireChildStructure(List<CatalogLookupName.Slot> slots,
                                              CatalogObjectKind terminalKind,
                                              CatalogParentConstraint parentConstraint) {
        List<CatalogLookupName.Slot> objects = new ArrayList<CatalogLookupName.Slot>();
        for (CatalogLookupName.Slot slot : slots) {
            if (slot.getRole() == IdentifierComponentRole.OBJECT) {
                objects.add(slot);
            }
        }
        CatalogLookupName.Slot terminal = slots.get(slots.size() - 1);

        if (terminal.getRole() == IdentifierComponentRole.BASE_COLUMN) {
            // A column is always nested: it needs exactly one relation-parent object.
            if (objects.size() != 1) {
                throw new IllegalArgumentException("a column needs exactly one object slot for its "
                        + "relation, even an OMITTED one; found " + objects.size());
            }
            requireFamily(terminalKind, parentConstraint, CatalogParentConstraint.RELATION);
            requireParentAdmitted(objects.get(0), parentConstraint);
            return;
        }

        if (terminal.getRole() != IdentifierComponentRole.OBJECT) {
            // A container terminal has no object nesting to check.
            if (parentConstraint != null) {
                throw new IllegalArgumentException("a " + terminal.getRole() + " terminal is not a "
                        + "nested object, so a parent constraint (" + parentConstraint
                        + ") is meaningless here");
            }
            return;
        }

        if (objects.size() == 1) {
            // A top-level object: legal for ANY object kind, including a function or an index named
            // directly in its schema.
            if (parentConstraint != null) {
                throw new IllegalArgumentException("this name has one object component, so " + terminalKind
                        + " is named at container level and has no object parent; the constraint "
                        + parentConstraint + " describes a nesting that is not in the name");
            }
            return;
        }

        // Two object components: the terminal IS nested, so the nesting must be one the model knows.
        CatalogParentConstraint required = nestedParentFamilyFor(terminalKind);
        if (required == null) {
            throw new IllegalArgumentException("a " + terminalKind + " is never contained in another "
                    + "object, so a name with two object components cannot denote one");
        }
        requireFamily(terminalKind, parentConstraint, required);
        CatalogLookupName.Slot parent = objects.get(objects.size() - 2);
        requireParentAdmitted(parent, parentConstraint);
        if (parent.getKind() != null && !mayContainObject(parent.getKind(), terminalKind)) {
            throw new IllegalArgumentException("a " + parent.getKind() + " does not contain a "
                    + terminalKind);
        }
    }

    private static void requireFamily(CatalogObjectKind terminalKind,
                                      CatalogParentConstraint supplied,
                                      CatalogParentConstraint required) {
        if (supplied == null) {
            throw new IllegalArgumentException("a nested " + terminalKind + " needs a " + required
                    + " parent constraint: without it the request does not say what it is a child OF");
        }
        if (!required.allowedKinds().containsAll(supplied.allowedKinds())) {
            throw new IllegalArgumentException("a nested " + terminalKind + " requires a " + required
                    + " parent; " + supplied + " admits kinds it cannot legally have");
        }
    }

    private static void requireParentAdmitted(CatalogLookupName.Slot parent,
                                              CatalogParentConstraint constraint) {
        if (parent.getKind() != null && constraint != null && !constraint.admits(parent.getKind())) {
            throw new IllegalArgumentException("the parent slot is a " + parent.getKind()
                    + ", which " + constraint + " does not admit");
        }
    }

    /**
     * Only shapes a remote reference is actually known to take may carry a DIRECTLY declared database
     * link. Allowing it on a catalog, schema, index or constraint would be generalizing past the
     * evidence. An INHERITED link is not re-judged: a column of a remote table is reachable as
     * {@code t@remote.c}, so rejecting it would mean a remote relation could have no remote columns.
     */
    static void requireLinkableTerminal(CatalogObjectKind terminalKind) {
        boolean linkable = RELATIONS.contains(terminalKind)
                || terminalKind == CatalogObjectKind.SYNONYM
                || ROUTINE_MEMBERS.contains(terminalKind);
        if (!linkable) {
            throw new IllegalArgumentException("a database link qualifies a relation, a synonym or "
                    + "a routine; " + terminalKind + " is not a shape a remote reference is known "
                    + "to take, and generalizing past the evidence is how a wrong identity is built");
        }
    }

    private static int rankOf(IdentifierComponentRole role) {
        switch (role) {
            case SERVER:
                return 0;
            case CATALOG:
                return 1;
            case SCHEMA:
                return 2;
            case OBJECT:
                return 3;
            case BASE_COLUMN:
                return 4;
            default:
                throw new IllegalArgumentException(role + " has no position in a catalog name");
        }
    }
}