package gudusoft.gsqlparser.dlineage.dataflow.model;

/**
 * Structural identity of one lineage graph node — a single column slot inside one
 * table or result set (stage S0 of
 * docs/refactor/identifier_identity_display_separation_plan.md).
 *
 * <h3>Why a name cannot do this job</h3>
 * The lineage walker currently keys nodes by {@code (parent display name, column display
 * name)}. Duplicate output names are legal SQL: {@code SELECT a AS [x], b AS x} on SQL
 * Server has two projection slots, two distinct source dependencies — and one published
 * name. Keying by name therefore conflates them, which is why
 * {@link ResultColumn} today lowercases its alias and appends a {@code (1)} suffix to break
 * the tie. That workaround mutates a published name to carry identity.
 *
 * <p>Note what is <em>not</em> the fix: making the name key case-sensitive. The two aliases
 * {@code [x]} and {@code x} are genuinely the same identifier under SQL Server's rules, so
 * a correct case-sensitive key still merges them. The slots are distinct for a structural
 * reason — they are different positions in the projection — so identity must be structural.
 *
 * <h3>What the ids are</h3>
 * Every analysis-model node ({@link Table}, {@link ResultSet}, {@link TableColumn},
 * {@link ResultColumn}) takes its {@code id} from one shared counter,
 * {@code ModelBindingManager.get().TABLE_COLUMN_ID}, and none of them exposes a setter, so
 * within one analysis an id is unique across kinds and immutable. A column id alone is
 * therefore already unique; the parent id is carried as well so an index can bucket by
 * container.
 *
 * <p><strong>No value is treated as "unassigned".</strong> The counter starts from
 * {@code Option.getStartId()}, which callers may set to zero or a negative number — with
 * {@code startId = -100} the published ids really are negative — so there is no sentinel this
 * class could reject. That is also why the factories take model objects wherever possible:
 * deriving both ids from one object is what prevents a mismatched pair, since no validation
 * can.
 *
 * <p><strong>Do not build this from the serialized model.</strong> The XML/JSON DTOs
 * ({@code dataflow.model.xml.table} and friends) carry {@code String} ids that are
 * <em>renumbered</em> at output time (see {@code DataFlowAnalyzer}'s table-merge pass), so
 * they are a presentation concern and are not stable identity.
 *
 * <p>There are therefore TWO identity domains and this type covers only the first:
 *
 * <ul>
 *   <li><strong>internal analysis model</strong> — immutable {@code long} ids from one shared
 *       counter. This class.</li>
 *   <li><strong>post-serialization graph</strong> — XML {@code String} {@code parent_id} and
 *       column {@code id}. Walkers that run on the serialized model, such as
 *       {@code RoutineSummaryExtractor}, live there and cannot use this type. They need
 *       {@link SerializedNodeKey}, whose whole point is that it keys on the column ID and
 *       never on the column NAME.</li>
 * </ul>
 */
public final class LineageNodeKey {

    private final long parentId;
    private final long columnId;

    private LineageNodeKey(long parentId, long columnId) {
        this.parentId = parentId;
        this.columnId = columnId;
    }

    /**
     * Key for a result-set projection slot. The container is read from the column itself, so
     * the pair cannot be mismatched.
     *
     * @throws IllegalArgumentException if the column is null or has no result set
     */
    public static LineageNodeKey of(ResultColumn column) {
        requireNonNull(column, "column");
        ResultSet parent = column.getResultSet();
        requireNonNull(parent, "result set of column " + column.getId());
        return new LineageNodeKey(parent.getId(), column.getId());
    }

    /**
     * Key for a column of a table endpoint. The container is read from the column itself.
     *
     * @throws IllegalArgumentException if the column is null or has no table
     */
    public static LineageNodeKey of(TableColumn column) {
        requireNonNull(column, "column");
        Table parent = column.getTable();
        requireNonNull(parent, "table of column " + column.getId());
        return new LineageNodeKey(parent.getId(), column.getId());
    }

    /**
     * Key for a {@link RelationRows} pseudo-node — whole-row flow through a result set. It is a
     * real graph node with its own id from the same counter, so it needs a node key; the text
     * label {@code "RelationRows"} is a different thing and belongs to {@link ModelLabelKey}.
     */
    public static LineageNodeKey of(ResultSetRelationRows rows) {
        requireNonNull(rows, "relation rows");
        requireNonNull(rows.getHolder(), "result set of relation rows " + rows.getId());
        return new LineageNodeKey(rows.getHolder().getId(), rows.getId());
    }

    /** Key for a table's {@link RelationRows} pseudo-node. */
    public static LineageNodeKey of(TableRelationRows rows) {
        requireNonNull(rows, "relation rows");
        requireNonNull(rows.getHolder(), "table of relation rows " + rows.getId());
        return new LineageNodeKey(rows.getHolder().getId(), rows.getId());
    }

    /**
     * Key from raw ids. <strong>Deliberately not public.</strong> It cannot check that the
     * column belongs to the parent, so a stale parent id paired with a live column id would
     * compile and produce a key for a node that does not exist — which defeats the whole point
     * of deriving the container from the column. A caller that holds a parent and a column
     * separately should call the model overload and ASSERT its own parent matches, rather than
     * passing both in.
     */
    static LineageNodeKey ofUncheckedIds(long parentId, long columnId) {
        return new LineageNodeKey(parentId, columnId);
    }

    public long getParentId() {
        return parentId;
    }

    public long getColumnId() {
        return columnId;
    }

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

    @Override
    public int hashCode() {
        int result = (int) (parentId ^ (parentId >>> 32));
        return 31 * result + (int) (columnId ^ (columnId >>> 32));
    }

    @Override
    public String toString() {
        return "LineageNodeKey{" + parentId + "#" + columnId + "}";
    }

    private static void requireNonNull(Object value, String what) {
        if (value == null) {
            throw new IllegalArgumentException(what + " is null");
        }
    }
}