001package gudusoft.gsqlparser.resolver2.binding;
002
003/**
004 * Reasons that a {@code TObjectName} reference is intentionally excluded from
005 * binding-diagnostic emission.
006 *
007 * <p>Slice S3 introduces this enum as the deterministic input the
008 * {@code BindingDiagnosticPostPass} (S5+) uses to skip references that
009 * resolver2 either did not resolve (synthetic clones, syntax-error blocked) or
010 * that would be category errors to flag (definition sites, target columns,
011 * unsupported scopes, metadata-unavailable namespaces).</p>
012 *
013 * <p>The enum is exposed as {@code public} so it can be stored on
014 * {@link gudusoft.gsqlparser.resolver2.model.ResolutionContext} (different
015 * package) but is intentionally absent from any documented public binding API
016 * surface — see plan §5.7 ("Public {@code BindingDiagnostic.getSkipReason()}
017 * accessor — leaks resolver internals; rejected").</p>
018 */
019public enum BindingSkipReason {
020
021    /**
022     * Reference is a synthetic clone produced by star-column push-down /
023     * {@code createTracedColumnClones}. The clone has a {@code sourceTable}
024     * set but never goes through {@code NameResolver.resolve()}; the post-pass
025     * must skip it to avoid double-reporting and false {@code UNKNOWN_COLUMN}.
026     */
027    SYNTHETIC_STAR_CLONE,
028
029    /**
030     * Reference is a definition site (CTE column-list entry, alias clause,
031     * VALUES alias, pivot output, CTAS target column list, etc.) — not a use
032     * site. Wired by S13's {@code BindingReferenceClassifier}; reserved here.
033     */
034    DEFINITION_SITE,
035
036    /**
037     * Reference is a DML target column (e.g. {@code INSERT (a,b)} list, the
038     * LHS of {@code UPDATE SET}, MERGE INSERT target). Targets must not emit
039     * {@code UNKNOWN_COLUMN}. Wired by S13.
040     */
041    TARGET_COLUMN,
042
043    /**
044     * Reference resolved against a namespace whose authoritative metadata is
045     * unavailable. Strict mode upgrades this to a {@code WARNING} diagnostic in
046     * S6; non-strict mode stays silent.
047     */
048    METADATA_UNAVAILABLE,
049
050    /**
051     * Reference falls inside a binding scope resolver2 cannot yet model
052     * (e.g. NATURAL JOIN AST gaps for some dialects, dynamic struct fields).
053     * Strict mode upgrades to {@code UNSUPPORTED_BINDING_SCOPE} in S8/S12.
054     */
055    UNSUPPORTED_SCOPE,
056
057    /**
058     * Reference comes from a parse with a non-zero return code. Per plan §5.6.9
059     * binding diagnostics are silent on syntax-error parses; the trace records
060     * this skip reason so callers that inspect {@code ResolutionContext}
061     * directly can still tell intent from gap.
062     */
063    SYNTAX_ERROR_BLOCKED
064}