package gudusoft.gsqlparser.util;

import java.util.Arrays;
import java.util.Collections;
import java.util.HashSet;
import java.util.Locale;
import java.util.Set;

/**
 * The single place that decides whether an Oracle identifier is a documented
 * <em>pseudocolumn</em> rather than a reference to a column of a table.
 *
 * <p>Every caller that either publishes a classification
 * ({@code TCustomSqlStatement.linkColumnReferenceToTable}) or answers a lookup
 * ({@code TObjectName.isValidColumnName}, {@code resolver2.ScopeBuilder}) must
 * go through this class. Keeping two hand-synchronised copies of the list is
 * what let {@code NEXTVAL} and {@code CURRVAL} drift apart in Mantis #4675: the
 * lookup path knew about {@code NEXTVAL} and the publish path did not, so the
 * two answered differently for the same expression.</p>
 *
 * <h3>Why the list is split into groups instead of being flat</h3>
 *
 * <p>Oracle documents 18 pseudocolumns, but only some of those names are
 * reserved words. A name that is <em>not</em> reserved is a perfectly legal
 * column name, and several are common ones: {@code OBJECT_ID} is a real column
 * of {@code ALL_OBJECTS} and {@code DBA_OBJECTS}. Classifying such a name as a
 * pseudocolumn on sight would delete correct lineage for
 * {@code SELECT OBJECT_ID FROM ALL_OBJECTS} while producing no error anywhere -
 * exactly the silent false negative the project forbids.</p>
 *
 * <p>So a name is only treated as a pseudocolumn when that is <em>provable</em>
 * from the statement itself:</p>
 *
 * <ul>
 *   <li>{@link #isReservedPseudoColumn} - the name is an Oracle reserved word,
 *       so an unquoted occurrence can never be a column. Always safe.</li>
 *   <li>{@link #isConnectByPseudoColumn} - only meaningful under a
 *       {@code CONNECT BY}; the caller supplies that fact.</li>
 *   <li>{@link #isSequencePseudoColumn} - only meaningful when qualified by
 *       something that is not a table or alias in scope.</li>
 * </ul>
 *
 * <p>Names that are neither reserved nor context-provable ({@code ORA_ROWSCN},
 * {@code OBJECT_ID}, {@code OBJECT_VALUE}, {@code XMLDATA},
 * {@code COLUMN_VALUE}) are deliberately absent. Without catalog metadata there
 * is no way to tell them from a real column of the same name, and guessing in
 * either direction is a defect.</p>
 *
 * @see <a href="https://docs.oracle.com/en/database/oracle/oracle-database/19/sqlrf/Pseudocolumns.html">Oracle SQL Language Reference - Pseudocolumns</a>
 */
public final class OraclePseudoColumnUtil {

    private OraclePseudoColumnUtil() {
    }

    /**
     * Reserved-word pseudocolumns that belong to the <em>query</em>, not to any
     * one table. Nothing sensible can be said about which table a
     * {@code ROWNUM} came from, so these are detached from the FROM clause
     * entirely.
     */
    private static final Set<String> DETACHED_RESERVED_PSEUDO_COLUMNS = unmodifiableUpperSet(
            "ROWNUM",
            "LEVEL");

    /**
     * Reserved-word pseudocolumns that belong to one specific table. A
     * {@code ROWID} is the physical address of a row <em>of a particular
     * table</em>, so unlike {@code ROWNUM} the table attribution is real
     * information and is kept.
     */
    private static final Set<String> TABLE_SCOPED_PSEUDO_COLUMNS = unmodifiableUpperSet(
            "ROWID");

    /**
     * Pseudocolumns of the hierarchical query clause. These names are not
     * reserved, so they are only pseudocolumns when the query actually has a
     * {@code CONNECT BY}.
     */
    private static final Set<String> CONNECT_BY_PSEUDO_COLUMNS = unmodifiableUpperSet(
            "CONNECT_BY_ISLEAF",
            "CONNECT_BY_ISCYCLE");

    /**
     * Sequence pseudocolumns, written {@code [schema.]sequence.NEXTVAL|CURRVAL}.
     * Not reserved, so they are only pseudocolumns when the qualifier is not a
     * table or alias in scope.
     */
    private static final Set<String> SEQUENCE_PSEUDO_COLUMNS = unmodifiableUpperSet(
            "NEXTVAL",
            "CURRVAL");

    /**
     * Pseudocolumns of the flashback {@code VERSIONS BETWEEN} clause. Not
     * reserved, so they are only pseudocolumns when the FROM clause carries a
     * version query.
     */
    private static final Set<String> VERSIONS_PSEUDO_COLUMNS = unmodifiableUpperSet(
            "VERSIONS_STARTSCN",
            "VERSIONS_STARTTIME",
            "VERSIONS_ENDSCN",
            "VERSIONS_ENDTIME",
            "VERSIONS_XID",
            "VERSIONS_OPERATION");

    /**
     * True when {@code nameOnly} is a pseudocolumn whose name is an Oracle
     * reserved word, and therefore never a legal unquoted column name.
     *
     * <p>The caller is responsible for checking that the identifier was not
     * quoted: {@code "ROWID"} is a distinct, legal, case-sensitive column
     * name.</p>
     *
     * @param nameOnly the single unqualified name segment, without quotes
     * @return true if this is always a pseudocolumn
     */
    public static boolean isReservedPseudoColumn(String nameOnly) {
        return isDetachedReservedPseudoColumn(nameOnly)
                || isTableScopedPseudoColumn(nameOnly);
    }

    /**
     * True for a reserved-word pseudocolumn that belongs to the query rather
     * than to a table ({@code ROWNUM}, {@code LEVEL}). These carry no table
     * attribution at all.
     *
     * @param nameOnly the single unqualified name segment, without quotes
     * @return true if this pseudocolumn has no owning table
     */
    public static boolean isDetachedReservedPseudoColumn(String nameOnly) {
        return contains(DETACHED_RESERVED_PSEUDO_COLUMNS, nameOnly);
    }

    /**
     * True for a reserved-word pseudocolumn that belongs to one specific table
     * ({@code ROWID}).
     *
     * <p>These keep {@code getSourceTable()} and their entry in the table's
     * linked columns - a {@code ROWID} really did come from that table, and
     * dropping the attribution would lose information lineage consumers use.
     * What changes is the reported {@link gudusoft.gsqlparser.EDbObjectType}:
     * {@code notAColumn} rather than {@code column}, so nothing tries to
     * resolve the name against a catalog that will never contain it.</p>
     *
     * @param nameOnly the single unqualified name segment, without quotes
     * @return true if this pseudocolumn is scoped to a single table
     */
    public static boolean isTableScopedPseudoColumn(String nameOnly) {
        return contains(TABLE_SCOPED_PSEUDO_COLUMNS, nameOnly);
    }

    /**
     * True when {@code nameOnly} is a hierarchical-query pseudocolumn
     * ({@code CONNECT_BY_ISLEAF}, {@code CONNECT_BY_ISCYCLE}).
     *
     * <p>Callers must additionally establish that the enclosing query has a
     * {@code CONNECT BY} clause; without one the same name is an ordinary
     * identifier and may well be a real column.</p>
     *
     * @param nameOnly the single unqualified name segment, without quotes
     * @return true if this is a CONNECT BY pseudocolumn name
     */
    public static boolean isConnectByPseudoColumn(String nameOnly) {
        return contains(CONNECT_BY_PSEUDO_COLUMNS, nameOnly);
    }

    /**
     * True when {@code nameOnly} is a sequence pseudocolumn
     * ({@code NEXTVAL}, {@code CURRVAL}).
     *
     * <p>Callers must additionally establish that the qualifier is a sequence
     * rather than a table or alias in scope; {@code x.CURRVAL} where {@code x}
     * is a table alias is a reference to a column named {@code CURRVAL}.</p>
     *
     * @param nameOnly the single unqualified name segment, without quotes
     * @return true if this is a sequence pseudocolumn name
     */
    public static boolean isSequencePseudoColumn(String nameOnly) {
        return contains(SEQUENCE_PSEUDO_COLUMNS, nameOnly);
    }

    /**
     * True when {@code nameOnly} is a flashback version query pseudocolumn
     * ({@code VERSIONS_STARTSCN} and friends).
     *
     * <p>Callers must additionally establish that the FROM clause carries a
     * {@code VERSIONS BETWEEN} clause.</p>
     *
     * @param nameOnly the single unqualified name segment, without quotes
     * @return true if this is a version query pseudocolumn name
     */
    public static boolean isVersionsPseudoColumn(String nameOnly) {
        return contains(VERSIONS_PSEUDO_COLUMNS, nameOnly);
    }

    private static boolean contains(Set<String> names, String nameOnly) {
        if (nameOnly == null || nameOnly.length() == 0) return false;
        return names.contains(nameOnly.toUpperCase(Locale.ROOT));
    }

    private static Set<String> unmodifiableUpperSet(String... names) {
        return Collections.unmodifiableSet(new HashSet<String>(Arrays.asList(names)));
    }
}