package gudusoft.gsqlparser.ir.semantic.binding;

import gudusoft.gsqlparser.nodes.TObjectName;
import gudusoft.gsqlparser.nodes.TTable;
import gudusoft.gsqlparser.stmt.TSelectSqlStatement;

import java.util.Set;

/**
 * Boundary between the SQL parser/resolver world and the Semantic IR world.
 *
 * <p>The Semantic IR builder never reads {@code TObjectName.getResolution()}
 * directly; it always asks a {@code NameBindingProvider}. This makes it
 * possible to swap implementations (current: TSQLResolver2; future:
 * Bound IR; tests: stub).
 *
 * <p><b>API status: advanced/preview SPI.</b> Implementing or calling this
 * interface is outside Join Analysis Consumption Profile v1. Prefer
 * {@link gudusoft.gsqlparser.ir.semantic.SqlSemanticAnalyzer} unless the
 * integration deliberately owns the low-level builder pipeline.
 */
public interface NameBindingProvider {

    /**
     * Resolve a FROM-clause relation reference to a {@link RelationBinding}.
     * Returns {@code null} when the binding is not available (e.g. unresolved).
     */
    RelationBinding bindRelation(TTable table);

    /**
     * Resolve a column-typed {@link TObjectName} to a {@link ColumnBinding}.
     * Returns {@code null} when the binding is not available; callers must
     * then decide whether to treat that as a hard error.
     */
    ColumnBinding bindColumn(TObjectName columnRef);

    /**
     * Return a new provider configured for a CTE scope. The default returns
     * the same instance, which means callers without CTE context behave
     * unchanged. Implementations that distinguish CTE references from base
     * tables should override this and return a per-scope copy.
     *
     * <p>The set is treated as case-insensitive by convention; callers
     * should pass already-lowercased CTE names.
     */
    default NameBindingProvider withCteContext(Set<String> cteNamesInScope) {
        return this;
    }

    /**
     * Slice 19 (alias-bound PARTITION BY discriminator). True when
     * {@code columnRef} is an unqualified column reference whose binding
     * lacks definite FROM-scope evidence AND whose name (case-insensitive)
     * matches a calculated-expression alias in the directly-enclosing
     * SELECT's result-column list.
     *
     * <p>Used by the IR builder to reject alias-bound PARTITION BY refs
     * that today bind heuristically to a base table (e.g.
     * {@code salary*2 AS doubled, PARTITION BY doubled} → resolver
     * synthesises {@code employees.doubled} via {@code inferred_from_usage}).
     * Without schema metadata the resolver cannot tell whether the name is
     * an alias or a real shadowing column; slice 19 chooses conservative
     * rejection over silent guess.
     *
     * <p>The default returns {@code false} so providers without resolver
     * state fall through transparently. {@code Resolver2NameBindingProvider}
     * overrides this with the real check (unqualified-only +
     * {@code !hasDefiniteEvidence()} + AST walk over
     * {@code enclosingSelect.getResultColumnList()} for a calculated alias
     * of the same name).
     *
     * @param columnRef        the column-typed AST node being inspected
     * @param enclosingSelect  the SELECT statement whose result columns
     *                         define the alias scope; the builder already
     *                         holds this and passes it in (avoids
     *                         context-dependent walks inside the resolver
     *                         layer)
     * @return true to reject this reference as alias-bound; false otherwise
     */
    default boolean isCalculatedProjectionAliasFallback(TObjectName columnRef,
                                                        TSelectSqlStatement enclosingSelect) {
        return false;
    }

    /**
     * Slice 60 — return a new provider scoped with a map of "in-scope
     * relation alias → published column names" for the current
     * consuming SELECT. Used by {@code SemanticIRBuilder.tryExpandStar}
     * to expand {@code SELECT *} / {@code SELECT alias.*} when the
     * FROM-clause relation binds to a CTE or a FROM-subquery body
     * already built earlier in the same {@code build()} invocation.
     *
     * <p>Semantics are REPLACE, not merge: callers always pass the
     * complete visible map for the scope. Implementations must
     * defensively copy and lower-case keys; values should be made
     * unmodifiable. The default returns the same instance (no-op).
     *
     * <p>{@link #withCteContext(Set)} and
     * {@code withInScopeRelationColumns} are independent facets of the
     * same per-scope provider context. Implementations must preserve
     * the other facet's state across each narrower call.
     */
    default NameBindingProvider withInScopeRelationColumns(
            java.util.Map<String, java.util.List<String>> nameToColumns) {
        return this;
    }

    /**
     * Slice 60 — return the in-scope relation column map last set via
     * {@link #withInScopeRelationColumns}. Default returns an empty
     * map.
     */
    default java.util.Map<String, java.util.List<String>> getInScopeRelationColumns() {
        return java.util.Collections.emptyMap();
    }

    /**
     * Slice 58 — catalog-known column names for {@code table} in catalog
     * declaration order, or {@code null} when no catalog information is
     * available for this relation.
     *
     * <p>Used by {@code SemanticIRBuilder.tryExpandStar} to expand
     * {@code SELECT *} and {@code SELECT alias.*} projections into per-
     * column {@link gudusoft.gsqlparser.ir.semantic.OutputColumn}s, each
     * carrying a {@link gudusoft.gsqlparser.ir.semantic.ColumnRef} to the
     * underlying base column.
     *
     * <p>Default returns {@code null} so providers without catalog access
     * fall through transparently and the builder emits a structured
     * unsupported diagnostic. {@code Resolver2NameBindingProvider}
     * overrides this when constructed with a non-null {@code TSQLEnv}.
     *
     * <p>Implementations must not return an empty list to mean
     * &quot;catalog known but no columns&quot;; an empty list is treated
     * identically to {@code null} (no usable catalog) by the builder.
     *
     * @param table the FROM-clause relation node being expanded; never
     *              null in practice (the builder filters out null tables
     *              before calling)
     * @return column-name list in declaration order, or null when no
     *         catalog metadata is available
     */
    default java.util.List<String> getRelationColumnNames(TTable table) {
        return null;
    }

    /**
     * Slice 65 — return a new provider scoped with the {@link UsingScope}
     * for the current SELECT body. Used by collectors and
     * {@code SemanticIRBuilder.expandBareStarOverUsing} to resolve
     * unqualified merged-key references to the merged source list.
     *
     * <p>Semantics are REPLACE, not merge: each
     * {@code buildSelectStatementImpl} invocation MUST call this with
     * {@link UsingScope#EMPTY} at entry so an enclosing SELECT's USING
     * cannot leak into recursive nested builds (predicate-subquery
     * bodies, scalar-subquery bodies, set-op branch bodies, CTE bodies,
     * FROM-subquery bodies all see only their own scope).
     *
     * <p>{@link #withCteContext(java.util.Set)},
     * {@link #withInScopeRelationColumns(java.util.Map)}, and
     * {@code withUsingScope} are independent facets of the same
     * per-scope provider context. Implementations must preserve the
     * other facets' state across each narrower call.
     *
     * <p>Default returns the same instance (no-op).
     */
    default NameBindingProvider withUsingScope(UsingScope scope) {
        return this;
    }

    /**
     * Slice 65 — return the using scope last set via
     * {@link #withUsingScope}. Default returns {@link UsingScope#EMPTY}.
     */
    default UsingScope getUsingScope() {
        return UsingScope.EMPTY;
    }

    /**
     * Return a new provider that records whether the current SELECT body has a
     * <em>fully-built join graph</em> — i.e. its FROM clause resolved two or
     * more join endpoints from explicit {@code ON} / {@code CROSS} / comma
     * predicates. This is the structural anchor that lets the IR builder
     * degrade an otherwise-fatal {@link
     * gudusoft.gsqlparser.ir.semantic.DiagnosticCode#COLUMN_BINDING_NON_EXACT}
     * for an unqualified, catalog-less column to a non-fatal warning: when the
     * join structure is fully known, the only thing missing without a catalog
     * is <em>which side</em> the unqualified column belongs to — the same
     * non-fatal case the {@code JOIN ... USING} merged-key anchor already
     * tolerates ({@link #getUsingScope()}).
     *
     * <p>REPLACE semantics: each {@code buildSelectStatementImpl} invocation
     * resets this at entry (passing {@code false}) so a parent SELECT's anchor
     * cannot leak into a recursive nested build, then installs the value for
     * its own FROM clause after relations are bound. The default returns the
     * same instance (no-op).
     */
    default NameBindingProvider withJoinStructureAnchor(boolean anchored) {
        return this;
    }

    /**
     * Return whether the current SELECT body carries a fully-built join-graph
     * structural anchor (see {@link #withJoinStructureAnchor(boolean)}).
     * Default returns {@code false} so providers without this state keep the
     * strict (fatal) {@code COLUMN_BINDING_NON_EXACT} behavior.
     */
    default boolean hasJoinStructureAnchor() {
        return false;
    }

    /**
     * Slice 93 — return a new provider that trusts Phase 1's
     * {@code linkColumnToTable}-set {@code TObjectName.getSourceTable()}
     * as an EXACT_MATCH when Phase 2 (TSQLResolver2) left
     * {@code TObjectName.getResolution()} null. Used for Hive multi-insert
     * sub-SELECT bodies whose secondary branches are not traversed by
     * Resolver2 during {@code TGSqlParser.parse()}; without the fallback,
     * those branches would universally fail with {@code NOT_FOUND}.
     *
     * <p>Safety: the fallback fires only when {@code resolution == null}
     * (proves Phase 2 did not run, NOT that it explicitly rejected) AND
     * the column's SQL-written qualifier (if any) is consistent with
     * Phase 1's chosen source table — the implementation verifies the
     * qualifier matches the source's name or alias case-insensitively
     * before promoting.
     *
     * <p>Default returns the same instance (no-op).
     */
    default NameBindingProvider withSourceTableFallback(boolean enabled) {
        return this;
    }

    /**
     * Slice 117 — return a new provider that admits qualified outer-scope
     * column references as synthetic EXACT_MATCH bindings instead of
     * letting them surface as {@code NOT_FOUND}. Used by the UPDATE
     * SET-RHS scalar-subquery extractor so a correlated outer reference
     * like {@code t.k} (where {@code t} is the UPDATE target or a
     * FROM-side outer relation, NOT inside the inner SELECT's FROM list)
     * survives {@code appendMergedOrBoundColumnRef}'s strict
     * non-EXACT_MATCH reject. The slice-11
     * {@code promoteCorrelatedRefsToOuterReference} then sees the ref's
     * alias and synthesises an {@code OUTER_REFERENCE} relation.
     *
     * <p>The {@code innerLocalAliasesLower} argument scopes the fallback:
     * a qualified ref whose qualifier IS in the inner local aliases is
     * NOT promoted (typos like {@code t.bad_col} where {@code t} is the
     * inner FROM alias still reject with {@code COLUMN_BINDING_NON_EXACT}
     * — they are real errors). Unqualified refs are NOT promoted (their
     * binding remains ambiguous between inner and outer).
     *
     * <p>Passing an empty or null set disables the fallback (no-op).
     *
     * <p>Default returns the same instance (no-op).
     */
    default NameBindingProvider withTolerantOuterBinding(
            Set<String> innerLocalAliasesLower) {
        return this;
    }
}