package gudusoft.gsqlparser.dlineage.dataflow.model;

/**
 * Identity of a dlineage model name that is <strong>not</strong> a SQL identifier — an
 * expression rendering, a literal constant, a pseudo-rows marker, a function display label
 * (stage S0 of docs/refactor/identifier_identity_display_separation_plan.md).
 *
 * <h3>Why these need their own key</h3>
 * dlineage's name-keyed indexes hold a mixture: some entries are identifiers (a column, a
 * table) and some are labels the analyzer invented to describe a computation. Running a
 * label through identifier normalization applies the wrong rules to it: a constant
 * {@code 'Ab'} is not an Oracle identifier that folds to {@code 'AB'}, and two different
 * expressions are not the same expression because a vendor happens to be
 * case-insensitive. Conversely, comparing an identifier with {@code equals} is wrong in the
 * other direction.
 *
 * <p>So labels compare <strong>exactly</strong> — byte-for-byte, no case folding, no
 * delimiter stripping, no vendor rules — and they carry a {@link Kind} so that a label can
 * never collide with an identifier key or with a label of another kind in the same index.
 * The root {@code CLAUDE.md} allows {@code equalsIgnoreCase} for "dlineage display names"
 * precisely because they are not identifiers; this type is the positive form of that rule:
 * if a name is a label, key it here, and the question of which vendor folding applies never
 * arises.
 *
 * <p>This type deliberately does <em>not</em> decide whether a given model name is an
 * identifier or a label — that is a per-call-site judgement made when the index is
 * migrated in stage S3. It only makes the two representable as different things.
 */
public final class ModelLabelKey {

    /** What kind of non-identifier name this is. */
    public enum Kind {
        /** A rendered expression, e.g. {@code a + b} or {@code CASE WHEN …}. */
        EXPRESSION,
        /** A literal value, e.g. {@code 'Ab'}, {@code 42}. */
        CONSTANT,
        /** A {@link RelationRows} pseudo-column standing for whole-row flow. */
        RELATION_ROWS,
        /** A function's display label, as distinct from its resolvable routine name. */
        FUNCTION_LABEL,
        /** Anything the analyzer synthesised that is none of the above. */
        SYNTHETIC
    }

    private final Kind kind;
    private final String text;

    private ModelLabelKey(Kind kind, String text) {
        this.kind = kind;
        this.text = text;
    }

    /**
     * @param kind what sort of label this is; labels of different kinds never compare equal
     * @param text the label exactly as the model holds it — not normalized, not trimmed
     * @throws IllegalArgumentException if either argument is null. An empty string IS a
     *         legal label (an empty expression rendering is a real, distinguishable state);
     *         null is not, because a null label in an index is a bug, not a value.
     */
    public static ModelLabelKey of(Kind kind, String text) {
        if (kind == null) {
            throw new IllegalArgumentException("label kind is null");
        }
        if (text == null) {
            throw new IllegalArgumentException("label text is null for kind " + kind);
        }
        return new ModelLabelKey(kind, text);
    }

    public Kind getKind() {
        return kind;
    }

    /** The label text, exactly as supplied. */
    public String getText() {
        return text;
    }

    @Override
    public boolean equals(Object o) {
        if (this == o) {
            return true;
        }
        if (o == null || getClass() != o.getClass()) {
            return false;
        }
        ModelLabelKey that = (ModelLabelKey) o;
        // Exact comparison is the point of this type: see the class comment.
        return kind == that.kind && text.equals(that.text);
    }

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

    @Override
    public String toString() {
        return "ModelLabelKey{" + kind + ":" + text + "}";
    }
}