package gudusoft.gsqlparser.resolver2.namespace;

import gudusoft.gsqlparser.nodes.TTable;
import gudusoft.gsqlparser.resolver2.ColumnLevel;
import gudusoft.gsqlparser.resolver2.model.ColumnSource;
import gudusoft.gsqlparser.resolver2.model.FieldPath;
import gudusoft.gsqlparser.stmt.TSelectSqlStatement;

import java.util.List;
import java.util.Map;
import java.util.Set;

/**
 * Represents a namespace that exposes columns.
 * A namespace can be a table, subquery, CTE, etc.
 *
 * Key responsibilities:
 * 1. Provide column existence checks (hasColumn)
 * 2. Resolve column names to ColumnSource
 * 3. Support SELECT * expansion
 * 4. Track data lineage (getFinalTable)
 *
 * Design based on Apache Calcite's SqlValidatorNamespace
 */
public interface INamespace {

    /**
     * Get a display name for this namespace (for debugging/error messages)
     */
    String getDisplayName();

    /**
     * Check if a column exists in this namespace.
     * Returns a three-level answer: EXISTS, MAYBE, NOT_EXISTS
     *
     * @param columnName Column name to check
     * @return Column existence level
     */
    ColumnLevel hasColumn(String columnName);

    /**
     * Resolve a column name to its source.
     *
     * @param columnName Column name to resolve
     * @return ColumnSource if found, null otherwise
     */
    ColumnSource resolveColumn(String columnName);

    /**
     * Resolve a column path (column.field.subfield...) to its source.
     *
     * <p>This method supports deep/record field access patterns like
     * {@code customer.address.city} where:</p>
     * <ul>
     *   <li>path[0] is the base column name (e.g., "customer")</li>
     *   <li>path[1..n] are field paths (e.g., ["address", "city"])</li>
     * </ul>
     *
     * @param path The column path segments
     * @return ColumnSource with fieldPath set, or null if base column not found
     */
    default ColumnSource resolveColumnPath(List<String> path) {
        if (path == null || path.isEmpty()) {
            return null;
        }

        // Single segment: simple column resolution
        if (path.size() == 1) {
            return resolveColumn(path.get(0));
        }

        // Multiple segments: resolve base column and attach fieldPath
        String baseColumnName = path.get(0);
        ColumnSource baseSource = resolveColumn(baseColumnName);
        if (baseSource == null) {
            return null;
        }

        // Attach field path (segments beyond base column)
        List<String> fieldSegments = path.subList(1, path.size());
        return baseSource.withFieldPath(FieldPath.of(fieldSegments), "struct_field_access");
    }

    /**
     * Get all column sources exposed by this namespace.
     * Used for SELECT * expansion and smart completion.
     *
     * @return Map of column name -> ColumnSource
     */
    Map<String, ColumnSource> getAllColumnSources();

    /**
     * Get the final physical table this namespace represents.
     * For tables: returns the table itself
     * For subqueries/CTEs: recursively traces back to physical table(s)
     *
     * @return Physical table, or null if not determinable
     */
    TTable getFinalTable();

    /**
     * Get all final physical tables this namespace depends on.
     * For simple table namespace: returns single table
     * For subquery/CTE: returns all tables in the query tree
     *
     * @return List of all physical tables
     */
    List<TTable> getAllFinalTables();

    /**
     * Check if this namespace is validated/resolved.
     * Some namespaces require resolution before they can provide column info.
     *
     * @return true if validated
     */
    boolean isValidated();

    /**
     * Validate/resolve this namespace.
     * For subqueries: resolve the SELECT list
     * For tables: load metadata if needed
     */
    void validate();

    /**
     * Get the associated AST node (TTable, TSelectSqlStatement, etc.)
     *
     * @return AST node, or null if not applicable
     */
    Object getNode();

    // ========== Star Column Inference Support ==========

    /**
     * Get the underlying SELECT statement for this namespace.
     * For CTENamespace: returns the CTE's subquery
     * For SubqueryNamespace: returns the subquery
     * For TableNamespace: returns null
     *
     * @return the SELECT statement, or null if not applicable
     */
    default TSelectSqlStatement getSelectStatement() {
        return null;
    }

    /**
     * Check if this namespace contains a star column (SELECT *).
     * Used to identify namespaces that may need star column inference.
     *
     * @return true if the namespace has SELECT *, false otherwise
     */
    default boolean hasStarColumn() {
        return false;
    }

    /**
     * Add an inferred column to this namespace.
     * Used by star column push-down to add columns discovered from outer queries.
     *
     * @param columnName the column name to add
     * @param confidence the confidence score (0.0 to 1.0)
     * @param evidence description of why this column was inferred
     * @return true if the column was added, false if already exists
     */
    default boolean addInferredColumn(String columnName, double confidence, String evidence) {
        // Default implementation does nothing - override in subclasses that support inference
        return false;
    }

    /**
     * Get all columns that were inferred (not from SELECT list directly).
     * These are columns discovered through star column push-down.
     *
     * @return set of inferred column names, empty if none
     */
    default Set<String> getInferredColumns() {
        return java.util.Collections.emptySet();
    }

    /**
     * Check if this namespace supports dynamic column inference.
     * DynamicStarSource and similar namespaces return true.
     *
     * @return true if this namespace can have columns added dynamically
     */
    default boolean supportsDynamicInference() {
        return false;
    }

    /**
     * Get the star column (SELECT *) from this namespace if one exists.
     * Used to track the sourceColumn for columns inferred from a star.
     *
     * @return The star column TResultColumn, or null if no star column exists
     */
    default gudusoft.gsqlparser.nodes.TResultColumn getStarColumn() {
        return null;
    }

    // ========== Legacy Compatibility Support ==========

    /**
     * Get the TTable that this namespace is associated with.
     * Used for legacy sync to set TObjectName.sourceTable.
     *
     * For TableNamespace: returns the table itself
     * For SubqueryNamespace: returns the TTable wrapping the subquery
     * For CTENamespace: returns the CTE referencing table
     * For others: returns null
     *
     * @return The source TTable, or null if not applicable
     */
    default TTable getSourceTable() {
        return null;
    }
}