package gudusoft.gsqlparser.resolver2;

import gudusoft.gsqlparser.EDbVendor;
import gudusoft.gsqlparser.TBaseType;
import gudusoft.gsqlparser.resolver2.binding.BindingDiagnosticCode;
import gudusoft.gsqlparser.resolver2.binding.BindingDiagnosticSeverity;
import gudusoft.gsqlparser.resolver2.format.DisplayNameMode;
import gudusoft.gsqlparser.resolver2.format.DisplayNamePolicy;
import gudusoft.gsqlparser.resolver2.matcher.DefaultNameMatcher;
import gudusoft.gsqlparser.resolver2.matcher.INameMatcher;
import gudusoft.gsqlparser.resolver2.matcher.VendorNameMatcher;
import gudusoft.gsqlparser.sqlenv.ESQLDataObjectType;
import gudusoft.gsqlparser.sqlenv.IdentifierProfile;
import gudusoft.gsqlparser.sqlenv.IdentifierService;

import java.util.EnumMap;
import java.util.Map;

/**
 * Configuration for TSQLResolver2.
 * Controls various aspects of name resolution behavior.
 */
public class TSQLResolverConfig {

    /** Name matcher for case sensitivity and matching rules */
    private INameMatcher nameMatcher = new DefaultNameMatcher();

    /** Database vendor for vendor-specific name matching */
    private EDbVendor vendor = null;

    /** Whether to enable legacy compatibility mode (sync results to TTable.linkedColumns) */
    private boolean legacyCompatibilityEnabled = true;

    /**
     * Minimum confidence threshold for syncing to legacy structures.
     *
     * Recommended values:
     * - 1.0 (default): Only sync definite results (safest, for SQL validation)
     * - 0.7: Include high-confidence inferences (for data lineage analysis)
     * - 0.5: Include all inferences (may mislead legacy code, not recommended)
     *
     * Use cases:
     * - Data lineage tools may want 0.7 inference results
     * - SQL formatters only need 1.0 definite results
     */
    private double legacySyncMinConfidence = 1.0;

    /** Maximum iterations for iterative resolution */
    private int maxIterations = 10;

    /** Minimum progress rate to continue iteration (0.0 - 1.0) */
    private double minProgressRate = 0.01;  // 1%

    /** Number of stable passes required to declare convergence */
    private int stablePassesForConvergence = 2;

    /** Whether to collect full candidates for ambiguous columns */
    private boolean collectFullCandidates = true;

    /** Whether to enable legacy evidence collection (deprecated, use NamespaceEnhancer) */
    private boolean evidenceCollectionEnabled = false;

    /**
     * Whether to show datatype information for columns from CREATE TABLE statements.
     * When enabled, columns from CREATE TABLE will include datatype info in format:
     * columnName:datatypeName:length or columnName:datatypeName:precision:scale
     */
    private boolean showDatatype = false;

    /**
     * Whether to show CTE (Common Table Expression) tables and their columns in output.
     * When enabled, CTE tables are included in the tables list and CTE columns
     * are included in the fields list with "(CTE)" suffix.
     * Default is false for backward compatibility.
     */
    private boolean showCTE = false;

    // ========== DISPLAY NAME Configuration ==========
    // Controls how identifier names are rendered for output

    /**
     * Display name mode - controls how identifiers are rendered.
     * <ul>
     *   <li>DISPLAY: Strip delimiters, preserve original case (default, recommended for debugging)</li>
     *   <li>SQL_RENDER: Preserve delimiters for valid SQL regeneration</li>
     *   <li>CANONICAL: Apply vendor-specific case folding</li>
     * </ul>
     */
    private DisplayNameMode displayNameMode = DisplayNameMode.DISPLAY;

    /**
     * Display name policy - controls which occurrence to use when same object
     * appears multiple times with different spellings.
     * <ul>
     *   <li>PREFER_DEFINITION_SITE: Use spelling from definition (CTE def, CREATE TABLE, etc.)</li>
     *   <li>PREFER_FIRST_OCCURRENCE: Use first occurrence in SQL text</li>
     *   <li>PREFER_METADATA: Use spelling from database metadata</li>
     * </ul>
     */
    private DisplayNamePolicy displayNamePolicy = DisplayNamePolicy.PREFER_DEFINITION_SITE;

    /**
     * Whether to strip delimiters (quotes, backticks, brackets) from identifier display.
     * Only applies when displayNameMode is DISPLAY.
     * Default is true.
     */
    private boolean stripDelimitersForDisplay = true;

    // ========== GUESS_COLUMN_STRATEGY Configuration ==========
    // Strategy for handling ambiguous columns (when a column could belong to multiple tables)

    /** Pick the first candidate table (nearest in FROM clause order) */
    public static final int GUESS_COLUMN_STRATEGY_NEAREST = TBaseType.GUESS_COLUMN_STRATEGY_NEAREST;

    /** Pick the last candidate table (farthest in FROM clause order) */
    public static final int GUESS_COLUMN_STRATEGY_FARTHEST = TBaseType.GUESS_COLUMN_STRATEGY_FARTHEST;

    /** Do not pick any candidate, leave as unresolved/ambiguous */
    public static final int GUESS_COLUMN_STRATEGY_NOT_PICKUP = TBaseType.GUESS_COLUMN_STRATEGY_NOT_PICKUP;

    /** Human-readable names for strategy values */
    public static final String[] GUESS_COLUMN_STRATEGY_NAMES = TBaseType.GUESS_COLUMN_STRATEGY_MSG;

    /**
     * Strategy for handling ambiguous columns.
     * Default: reads from TBaseType.GUESS_COLUMN_STRATEGY for backward compatibility.
     * Can be overridden per-config instance.
     */
    private Integer guessColumnStrategy = null; // null means use TBaseType default

    // ========== CONFIDENCE THRESHOLD Configuration ==========
    // Controls when resolutions are considered "definite" vs "inferred" and when guessing is allowed

    /**
     * Minimum confidence threshold for a resolution to be considered "definite".
     *
     * <p>Resolutions with confidence >= this threshold are treated as having
     * strong evidence (e.g., DDL metadata, qualified references). Resolutions
     * below this threshold are considered "inferred" or "uncertain".</p>
     *
     * <p>Recommended values:</p>
     * <ul>
     *   <li>0.9 (default): High bar - only high-confidence resolutions are definite</li>
     *   <li>0.7: Include more inferred resolutions as definite</li>
     *   <li>1.0: Only metadata-backed resolutions are definite</li>
     * </ul>
     */
    private double minDefiniteConfidence = 0.9;

    /**
     * Minimum confidence threshold to allow guessing from ambiguous candidates.
     *
     * <p>When multiple candidates exist and GUESS_COLUMN_STRATEGY is not NOT_PICKUP,
     * at least one candidate must have confidence >= this threshold for guessing
     * to be allowed. If all candidates are below this threshold, the column
     * remains AMBIGUOUS regardless of strategy.</p>
     *
     * <p>Recommended values:</p>
     * <ul>
     *   <li>0.95 (default): Very high bar - only guess with strong evidence</li>
     *   <li>0.9: Allow guessing with high-confidence candidates</li>
     *   <li>0.7: Allow guessing with inferred candidates (not recommended)</li>
     * </ul>
     */
    private double minConfidenceToGuess = 0.95;

    /**
     * Whether to allow guessing when all candidates are inferred (no DDL metadata).
     *
     * <p>When false (default), if all candidates have confidence below
     * {@link #minDefiniteConfidence}, the column remains AMBIGUOUS even if
     * GUESS_COLUMN_STRATEGY would normally pick one. This prevents guessing
     * based on uncertain evidence.</p>
     *
     * <p>When true, guessing is allowed even when all candidates are inferred,
     * as long as the GUESS_COLUMN_STRATEGY is not NOT_PICKUP. Use with caution
     * as this may produce misleading lineage results.</p>
     */
    private boolean allowGuessWhenAllInferred = false;

    // ========== Binding Diagnostic Configuration (plan §5.3, S2) ==========

    /**
     * When {@code true}, the resolver2 binding-diagnostic post-pass runs once
     * after iterative convergence and populates {@link
     * gudusoft.gsqlparser.resolver2.binding.BindingResult}. Default {@code
     * false} — accessors return the {@link
     * gudusoft.gsqlparser.resolver2.binding.BindingResult#empty()} singleton
     * with zero parse-time overhead.
     */
    private boolean emitBindingDiagnostics = false;

    /**
     * When {@code true} (and {@link #emitBindingDiagnostics} is on), strict
     * catalog mode emits {@code UNKNOWN_TABLE} / {@code UNKNOWN_ALIAS} /
     * {@code CATALOG_METADATA_UNAVAILABLE}. Default {@code false} so that
     * tables without authoritative metadata are silent (plan §5.5).
     */
    private boolean bindingStrictCatalogValidation = false;

    /**
     * When {@code true}, successful {@link
     * gudusoft.gsqlparser.resolver2.binding.BindingReference} entries are
     * included in the result. Default {@code false} — IDE/lint consumers opt
     * in; non-IDE consumers avoid the payload bloat.
     */
    private boolean bindingIncludeSuccessfulReferences = false;

    /**
     * When {@code true}, the resolver records a
     * {@link gudusoft.gsqlparser.resolver2.binding.BindingTrace} for every
     * reference it binds (the dynamic-SQL publication proof's P3 input).
     * Default {@code false}: no registry is created and the capture hooks are
     * a single null check — zero overhead and zero behavior change on the
     * normal path. Observation-only when enabled.
     */
    private boolean captureBindingTrace = false;

    /**
     * Lazy map of per-code severity overrides. Allocated only when {@link
     * #setBindingSeverityFor(BindingDiagnosticCode, BindingDiagnosticSeverity)}
     * is first called so that the default-off path stays allocation-free.
     */
    private EnumMap<BindingDiagnosticCode, BindingDiagnosticSeverity> bindingSeverityOverrides;

    public TSQLResolverConfig() {
        // Default configuration
    }

    public INameMatcher getNameMatcher() {
        return nameMatcher;
    }

    public void setNameMatcher(INameMatcher nameMatcher) {
        if (nameMatcher == null) {
            throw new IllegalArgumentException("Name matcher cannot be null");
        }
        this.nameMatcher = nameMatcher;
    }

    public boolean isLegacyCompatibilityEnabled() {
        return legacyCompatibilityEnabled;
    }

    public void setLegacyCompatibilityEnabled(boolean enabled) {
        this.legacyCompatibilityEnabled = enabled;
    }

    public double getLegacySyncMinConfidence() {
        return legacySyncMinConfidence;
    }

    public void setLegacySyncMinConfidence(double threshold) {
        if (threshold < 0.0 || threshold > 1.0) {
            throw new IllegalArgumentException("Confidence threshold must be in [0.0, 1.0]");
        }
        this.legacySyncMinConfidence = threshold;
    }

    public int getMaxIterations() {
        return maxIterations;
    }

    public void setMaxIterations(int maxIterations) {
        if (maxIterations < 1) {
            throw new IllegalArgumentException("Max iterations must be at least 1");
        }
        this.maxIterations = maxIterations;
    }

    public double getMinProgressRate() {
        return minProgressRate;
    }

    public void setMinProgressRate(double minProgressRate) {
        if (minProgressRate < 0.0 || minProgressRate > 1.0) {
            throw new IllegalArgumentException("Progress rate must be in [0.0, 1.0]");
        }
        this.minProgressRate = minProgressRate;
    }

    public int getStablePassesForConvergence() {
        return stablePassesForConvergence;
    }

    public void setStablePassesForConvergence(int stablePasses) {
        if (stablePasses < 1) {
            throw new IllegalArgumentException("Stable passes must be at least 1");
        }
        this.stablePassesForConvergence = stablePasses;
    }

    public boolean isCollectFullCandidates() {
        return collectFullCandidates;
    }

    public void setCollectFullCandidates(boolean collectFullCandidates) {
        this.collectFullCandidates = collectFullCandidates;
    }

    /**
     * @deprecated Use NamespaceEnhancer instead
     */
    public boolean isEvidenceCollectionEnabled() {
        return evidenceCollectionEnabled;
    }

    /**
     * @deprecated Use NamespaceEnhancer instead
     */
    public void setEvidenceCollectionEnabled(boolean enabled) {
        this.evidenceCollectionEnabled = enabled;
    }

    /**
     * Check if datatype information should be shown for columns from CREATE TABLE statements.
     *
     * @return true if datatype information should be included in column names
     */
    public boolean isShowDatatype() {
        return showDatatype;
    }

    /**
     * Set whether to show datatype information for columns from CREATE TABLE statements.
     * When enabled, columns from CREATE TABLE will include datatype info in format:
     * columnName:datatypeName:length or columnName:datatypeName:precision:scale
     *
     * @param showDatatype true to include datatype information
     */
    public void setShowDatatype(boolean showDatatype) {
        this.showDatatype = showDatatype;
    }

    /**
     * Check if CTE (Common Table Expression) tables and columns should be shown in output.
     *
     * @return true if CTE tables and columns should be included
     */
    public boolean isShowCTE() {
        return showCTE;
    }

    /**
     * Set whether to show CTE (Common Table Expression) tables and columns in output.
     * When enabled, CTE tables are included in the tables list and CTE columns
     * are included in the fields list with "(CTE)" suffix.
     *
     * @param showCTE true to include CTE tables and columns
     */
    public void setShowCTE(boolean showCTE) {
        this.showCTE = showCTE;
    }

    // ========== Display Name Getters and Setters ==========

    /**
     * Get the display name mode.
     *
     * @return the current display name mode
     */
    public DisplayNameMode getDisplayNameMode() {
        return displayNameMode;
    }

    /**
     * Set the display name mode.
     *
     * @param mode the display name mode
     */
    public void setDisplayNameMode(DisplayNameMode mode) {
        this.displayNameMode = mode != null ? mode : DisplayNameMode.DISPLAY;
    }

    /**
     * Get the display name policy.
     *
     * @return the current display name policy
     */
    public DisplayNamePolicy getDisplayNamePolicy() {
        return displayNamePolicy;
    }

    /**
     * Set the display name policy.
     *
     * @param policy the display name policy
     */
    public void setDisplayNamePolicy(DisplayNamePolicy policy) {
        this.displayNamePolicy = policy != null ? policy : DisplayNamePolicy.PREFER_DEFINITION_SITE;
    }

    /**
     * Check if delimiters should be stripped for display.
     *
     * @return true if delimiters should be stripped
     */
    public boolean isStripDelimitersForDisplay() {
        return stripDelimitersForDisplay;
    }

    /**
     * Set whether to strip delimiters for display.
     *
     * @param stripDelimiters true to strip delimiters
     */
    public void setStripDelimitersForDisplay(boolean stripDelimiters) {
        this.stripDelimitersForDisplay = stripDelimiters;
    }

    /**
     * Get the strategy for handling ambiguous columns.
     * Returns the configured value, or TBaseType.GUESS_COLUMN_STRATEGY if not set.
     *
     * @return One of GUESS_COLUMN_STRATEGY_NEAREST, GUESS_COLUMN_STRATEGY_FARTHEST,
     *         or GUESS_COLUMN_STRATEGY_NOT_PICKUP
     */
    public int getGuessColumnStrategy() {
        return guessColumnStrategy != null ? guessColumnStrategy : TBaseType.GUESS_COLUMN_STRATEGY;
    }

    /**
     * Set the strategy for handling ambiguous columns.
     *
     * @param strategy One of GUESS_COLUMN_STRATEGY_NEAREST, GUESS_COLUMN_STRATEGY_FARTHEST,
     *                 or GUESS_COLUMN_STRATEGY_NOT_PICKUP
     */
    public void setGuessColumnStrategy(int strategy) {
        if (strategy < GUESS_COLUMN_STRATEGY_NEAREST || strategy > GUESS_COLUMN_STRATEGY_NOT_PICKUP) {
            throw new IllegalArgumentException("Invalid strategy: " + strategy +
                ". Must be GUESS_COLUMN_STRATEGY_NEAREST (0), GUESS_COLUMN_STRATEGY_FARTHEST (1), " +
                "or GUESS_COLUMN_STRATEGY_NOT_PICKUP (2)");
        }
        this.guessColumnStrategy = strategy;
    }

    /**
     * Check if a custom guess column strategy has been set on this config.
     * If false, the strategy from TBaseType.GUESS_COLUMN_STRATEGY will be used.
     *
     * @return true if a custom strategy is set
     */
    public boolean hasCustomGuessColumnStrategy() {
        return guessColumnStrategy != null;
    }

    /**
     * Clear any custom guess column strategy, reverting to TBaseType.GUESS_COLUMN_STRATEGY.
     */
    public void clearGuessColumnStrategy() {
        this.guessColumnStrategy = null;
    }

    /**
     * Get the human-readable name for the current strategy.
     *
     * @return Strategy name (e.g., "GUESS_COLUMN_STRATEGY_NEAREST")
     */
    public String getGuessColumnStrategyName() {
        int strategy = getGuessColumnStrategy();
        if (strategy >= 0 && strategy < GUESS_COLUMN_STRATEGY_NAMES.length) {
            return GUESS_COLUMN_STRATEGY_NAMES[strategy];
        }
        return "UNKNOWN(" + strategy + ")";
    }

    // ========== Confidence Threshold Getters and Setters ==========

    /**
     * Get the minimum confidence threshold for definite resolutions.
     *
     * @return Threshold value [0.0, 1.0]
     */
    public double getMinDefiniteConfidence() {
        return minDefiniteConfidence;
    }

    /**
     * Set the minimum confidence threshold for definite resolutions.
     *
     * @param threshold Threshold value [0.0, 1.0]
     */
    public void setMinDefiniteConfidence(double threshold) {
        if (threshold < 0.0 || threshold > 1.0) {
            throw new IllegalArgumentException("Confidence threshold must be in [0.0, 1.0]");
        }
        this.minDefiniteConfidence = threshold;
    }

    /**
     * Get the minimum confidence threshold to allow guessing.
     *
     * @return Threshold value [0.0, 1.0]
     */
    public double getMinConfidenceToGuess() {
        return minConfidenceToGuess;
    }

    /**
     * Set the minimum confidence threshold to allow guessing.
     *
     * @param threshold Threshold value [0.0, 1.0]
     */
    public void setMinConfidenceToGuess(double threshold) {
        if (threshold < 0.0 || threshold > 1.0) {
            throw new IllegalArgumentException("Confidence threshold must be in [0.0, 1.0]");
        }
        this.minConfidenceToGuess = threshold;
    }

    /**
     * Check if guessing is allowed when all candidates are inferred.
     *
     * @return true if guessing is allowed with inferred candidates
     */
    public boolean isAllowGuessWhenAllInferred() {
        return allowGuessWhenAllInferred;
    }

    /**
     * Set whether to allow guessing when all candidates are inferred.
     *
     * @param allow true to allow guessing with inferred candidates
     */
    public void setAllowGuessWhenAllInferred(boolean allow) {
        this.allowGuessWhenAllInferred = allow;
    }

    /**
     * Check if a confidence value represents a definite resolution.
     *
     * @param confidence The confidence value to check
     * @return true if the confidence is >= minDefiniteConfidence
     */
    public boolean isDefiniteConfidence(double confidence) {
        return confidence >= minDefiniteConfidence;
    }

    /**
     * Check if a confidence value is sufficient to allow guessing.
     *
     * @param confidence The confidence value to check
     * @return true if the confidence is >= minConfidenceToGuess
     */
    public boolean canGuessWithConfidence(double confidence) {
        return confidence >= minConfidenceToGuess;
    }

    // ========== Binding Diagnostic Getters and Setters (plan §5.3, S2) ==========

    /**
     * @return whether the binding-diagnostic post-pass is enabled
     */
    public boolean isEmitBindingDiagnostics() {
        return emitBindingDiagnostics;
    }

    /**
     * Enable or disable the binding-diagnostic post-pass.
     *
     * <p>Default {@code false}. When off, the post-pass is not invoked and
     * accessors return {@link
     * gudusoft.gsqlparser.resolver2.binding.BindingResult#empty()}.</p>
     *
     * @param on whether to emit binding diagnostics
     * @return this config (fluent)
     */
    public TSQLResolverConfig setEmitBindingDiagnostics(boolean on) {
        this.emitBindingDiagnostics = on;
        return this;
    }

    /**
     * @return whether strict catalog validation is enabled
     */
    public boolean isBindingStrictCatalogValidation() {
        return bindingStrictCatalogValidation;
    }

    /**
     * Enable or disable strict catalog validation. Default {@code false}.
     *
     * @param on whether to enable strict mode
     * @return this config (fluent)
     */
    public TSQLResolverConfig setBindingStrictCatalogValidation(boolean on) {
        this.bindingStrictCatalogValidation = on;
        return this;
    }

    /**
     * @return whether successful binding references are included in the
     *         result payload
     */
    public boolean isBindingIncludeSuccessfulReferences() {
        return bindingIncludeSuccessfulReferences;
    }

    /**
     * Enable or disable successful-reference emission. Default {@code false}
     * (payload bloat for non-IDE consumers).
     *
     * @param on whether to include successful references
     * @return this config (fluent)
     */
    public TSQLResolverConfig setBindingIncludeSuccessfulReferences(boolean on) {
        this.bindingIncludeSuccessfulReferences = on;
        return this;
    }

    /** @see #captureBindingTrace */
    public boolean isCaptureBindingTrace() {
        return captureBindingTrace;
    }

    /** @see #captureBindingTrace */
    public TSQLResolverConfig setCaptureBindingTrace(boolean on) {
        this.captureBindingTrace = on;
        return this;
    }

    /**
     * Override the severity emitted for a given binding diagnostic code.
     *
     * <p>The override map is allocated lazily so callers that never customize
     * severities pay no allocation cost.</p>
     *
     * @param code the diagnostic code (must not be null)
     * @param severity the severity to emit for this code (must not be null)
     * @return this config (fluent)
     * @throws IllegalArgumentException if either argument is null
     */
    public TSQLResolverConfig setBindingSeverityFor(BindingDiagnosticCode code,
                                                   BindingDiagnosticSeverity severity) {
        if (code == null) {
            throw new IllegalArgumentException("BindingDiagnosticCode is required");
        }
        if (severity == null) {
            throw new IllegalArgumentException("BindingDiagnosticSeverity is required");
        }
        if (bindingSeverityOverrides == null) {
            bindingSeverityOverrides = new EnumMap<BindingDiagnosticCode, BindingDiagnosticSeverity>(
                BindingDiagnosticCode.class);
        }
        bindingSeverityOverrides.put(code, severity);
        return this;
    }

    /**
     * Resolve the configured severity for a diagnostic code. Returns the
     * override when one is set, otherwise the code's frozen default
     * severity (plan §5.4).
     *
     * @param code the diagnostic code (must not be null)
     * @return the configured or default severity for this code
     */
    public BindingDiagnosticSeverity getBindingSeverityFor(BindingDiagnosticCode code) {
        if (code == null) {
            throw new IllegalArgumentException("BindingDiagnosticCode is required");
        }
        if (bindingSeverityOverrides != null) {
            BindingDiagnosticSeverity override = bindingSeverityOverrides.get(code);
            if (override != null) {
                return override;
            }
        }
        return code.defaultSeverity();
    }

    /**
     * @return whether any per-code severity override has been configured.
     *         Used to keep the default-off path allocation-free in tests.
     */
    public boolean hasBindingSeverityOverrides() {
        return bindingSeverityOverrides != null && !bindingSeverityOverrides.isEmpty();
    }

    /**
     * @return an immutable view of the configured severity overrides, or an
     *         empty map when none are configured. Never null.
     */
    public Map<BindingDiagnosticCode, BindingDiagnosticSeverity> getBindingSeverityOverrides() {
        if (bindingSeverityOverrides == null || bindingSeverityOverrides.isEmpty()) {
            return java.util.Collections.<BindingDiagnosticCode, BindingDiagnosticSeverity>emptyMap();
        }
        return java.util.Collections.unmodifiableMap(bindingSeverityOverrides);
    }

    /**
     * Create a default configuration
     */
    public static TSQLResolverConfig createDefault() {
        return new TSQLResolverConfig();
    }

    /**
     * Create configuration for case-sensitive matching
     */
    public static TSQLResolverConfig createCaseSensitive() {
        TSQLResolverConfig config = new TSQLResolverConfig();
        config.setNameMatcher(new DefaultNameMatcher(true));
        return config;
    }

    /**
     * Create configuration for standalone mode (no legacy sync)
     */
    public static TSQLResolverConfig createStandalone() {
        TSQLResolverConfig config = new TSQLResolverConfig();
        config.setLegacyCompatibilityEnabled(false);
        return config;
    }

    /**
     * Create configuration with showDatatype enabled.
     * This configuration includes datatype information for columns from CREATE TABLE statements.
     */
    public static TSQLResolverConfig createWithDatatype() {
        TSQLResolverConfig config = new TSQLResolverConfig();
        config.setShowDatatype(true);
        return config;
    }

    /**
     * Create configuration with showCTE enabled.
     * This configuration includes CTE tables and columns in the output.
     */
    public static TSQLResolverConfig createWithCTE() {
        TSQLResolverConfig config = new TSQLResolverConfig();
        config.setShowCTE(true);
        return config;
    }

    /**
     * Create configuration for a specific database vendor.
     *
     * <p>This factory method creates a configuration with vendor-specific
     * name matching rules. The VendorNameMatcher uses IdentifierService
     * to properly handle case sensitivity and quote handling for each vendor.</p>
     *
     * <p>Example vendor behaviors:</p>
     * <ul>
     *   <li>Oracle: Unquoted identifiers fold to UPPER, quoted are case-sensitive</li>
     *   <li>PostgreSQL: Unquoted identifiers fold to LOWER, quoted are case-sensitive</li>
     *   <li>MySQL: Depends on lower_case_table_names setting</li>
     *   <li>BigQuery: Table names are case-sensitive, column names are case-insensitive</li>
     * </ul>
     *
     * @param vendor the database vendor
     * @return configuration with vendor-specific name matcher
     */
    public static TSQLResolverConfig createForVendor(EDbVendor vendor) {
        TSQLResolverConfig config = new TSQLResolverConfig();
        config.vendor = vendor;
        config.nameMatcher = new VendorNameMatcher(vendor);
        return config;
    }

    /**
     * Create configuration whose name matching runs under ONE analysis's identifier
     * configuration instead of the vendor default.
     *
     * @param profile the effective identifier configuration for this resolution
     * @return configuration whose matcher observes {@code profile}
     */
    public static TSQLResolverConfig createForProfile(IdentifierProfile profile) {
        if (profile == null) {
            throw new IllegalArgumentException(
                "TSQLResolverConfig.createForProfile: profile is required");
        }
        TSQLResolverConfig config = new TSQLResolverConfig();
        config.setIdentifierProfile(profile);
        return config;
    }

    /**
     * Create configuration for a specific database vendor with datatype display enabled.
     *
     * @param vendor the database vendor
     * @return configuration with vendor-specific name matcher and datatype display
     */
    public static TSQLResolverConfig createForVendorWithDatatype(EDbVendor vendor) {
        TSQLResolverConfig config = createForVendor(vendor);
        config.setShowDatatype(true);
        return config;
    }

    /**
     * Get the database vendor, if set.
     *
     * @return the database vendor, or null if not set
     */
    public EDbVendor getVendor() {
        return vendor;
    }

    /**
     * Set the database vendor and update name matcher accordingly.
     *
     * @param vendor the database vendor
     */
    public void setVendor(EDbVendor vendor) {
        this.vendor = vendor;
        if (vendor != null) {
            if (identifierProfile != null && identifierProfile.getVendor() != vendor) {
                throw new IllegalArgumentException("TSQLResolverConfig.setVendor: vendor " + vendor
                        + " conflicts with the identifier profile already set for "
                        + identifierProfile.getVendor());
            }
            // Keep an explicitly configured profile: setVendor is called unconditionally by
            // TGSqlParser on every parse, and rebuilding a vendor-default matcher here would
            // silently discard the caller's configuration right before resolution starts.
            this.nameMatcher = identifierProfile != null
                    ? new VendorNameMatcher(identifierService(), ESQLDataObjectType.dotColumn)
                    : new VendorNameMatcher(vendor);
        }
    }

    /** Explicit identifier configuration for this resolution; null means the vendor default. */
    private IdentifierProfile identifierProfile = null;
    private IdentifierService identifierServiceCache = null;

    /**
     * Set the identifier configuration this resolution compares and keys names under.
     *
     * <p>Replaces the name matcher with one running on that configuration, so resolver2's
     * scopes and namespaces observe the same per-category rules the catalog was indexed with.
     * Passing null restores the vendor default.
     *
     * @param profile the effective identifier configuration, or null for the vendor default
     */
    public void setIdentifierProfile(IdentifierProfile profile) {
        this.identifierProfile = profile;
        this.identifierServiceCache = null;
        if (profile == null) {
            if (this.vendor != null) {
                this.nameMatcher = new VendorNameMatcher(this.vendor);
            }
            return;
        }
        if (this.vendor != null && this.vendor != profile.getVendor()) {
            throw new IllegalArgumentException("TSQLResolverConfig.setIdentifierProfile: profile is"
                    + " for vendor " + profile.getVendor() + " but this config is " + this.vendor);
        }
        this.vendor = profile.getVendor();
        this.nameMatcher = new VendorNameMatcher(identifierService(), ESQLDataObjectType.dotColumn);
    }

    /**
     * The identifier configuration of this resolution, or null when it is the vendor default.
     *
     * @return the effective identifier profile, or null
     */
    public IdentifierProfile getIdentifierProfile() {
        return identifierProfile;
    }

    /**
     * The single comparison engine this resolution uses — configured when
     * {@link #setIdentifierProfile} was called, else the vendor's default service.
     *
     * @return the identifier service; never null once a vendor or profile is set
     */
    public IdentifierService identifierService() {
        IdentifierService cached = identifierServiceCache;
        if (cached == null) {
            cached = identifierProfile != null
                    ? IdentifierService.forProfile(identifierProfile)
                    : IdentifierService.defaultServiceFor(
                            vendor != null ? vendor : EDbVendor.dbvgeneric);
            identifierServiceCache = cached;
        }
        return cached;
    }

    /**
     * Check if vendor-specific name matching is enabled.
     *
     * @return true if a vendor is configured
     */
    public boolean hasVendor() {
        return vendor != null;
    }

    @Override
    public String toString() {
        return String.format(
            "TSQLResolverConfig{vendor=%s, nameMatcher=%s, legacyCompat=%s, minConfidence=%.2f, maxIter=%d, guessStrategy=%s, " +
            "minDefiniteConf=%.2f, minGuessConf=%.2f, allowGuessInferred=%s, showDatatype=%s, showCTE=%s, displayMode=%s, displayPolicy=%s}",
            vendor,
            nameMatcher,
            legacyCompatibilityEnabled,
            legacySyncMinConfidence,
            maxIterations,
            getGuessColumnStrategyName(),
            minDefiniteConfidence,
            minConfidenceToGuess,
            allowGuessWhenAllInferred,
            showDatatype,
            showCTE,
            displayNameMode,
            displayNamePolicy
        );
    }
}