package gudusoft.gsqlparser.resolver2.binding;

import gudusoft.gsqlparser.nodes.TObjectName;
import gudusoft.gsqlparser.nodes.TTable;
import gudusoft.gsqlparser.resolver2.ResolutionStatus;
import gudusoft.gsqlparser.resolver2.namespace.INamespace;

/**
 * Immutable record of HOW one name reference was bound during the final
 * resolver pass (design: {@code dynamic-sql-fragment-provenance-design.md},
 * R3 / R4 step 3).
 *
 * <p>The dynamic-SQL per-edge publication proof (P3) needs the full binding
 * chain of every evidence reference, and its rule is fail-closed on
 * completeness: {@code trace == null || !trace.complete} ⇒ the reference is
 * unprovable. A missing trace is therefore always SAFE — it can only shrink
 * the published-edge set, never let an unproven edge through. This is why the
 * many direct {@code setSourceTable} sites in ScopeBuilder do not all need
 * instrumenting at once: uninstrumented paths simply yield no trace.
 *
 * <p>Captured today:
 * <ul>
 *   <li>the scope-machinery choke point ({@code NameResolver.resolve}) —
 *       records the winning match's namespace, scope, resolve path and the
 *       climb depth from the starting scope (correlated references);</li>
 *   <li>the typed direct-binding clusters review round 2 named: OUTPUT
 *       {@code INSERTED}/{@code DELETED}, trigger pseudo-tables, MERGE
 *       target/SET/INSERT columns and MERGE USING values.</li>
 * </ul>
 *
 * <p>Capture is off by default ({@code TSQLResolverConfig.captureBindingTrace})
 * and observation-only: nothing in resolution reads a trace.
 */
public final class BindingTrace {

    /** What kind of binder resolved the reference. */
    public enum BinderKind {
        /** Resolved through the scope machinery (namespace recorded). */
        SCOPE_RESOLUTION,
        /** Directly bound to a DML target pseudo-table (OUTPUT INSERTED/DELETED, trigger). */
        DML_TARGET,
        /** Directly bound to the MERGE target (SET / INSERT column list). */
        MERGE_TARGET,
        /** Directly bound to the MERGE USING source (VALUES expressions). */
        MERGE_USING
    }

    /** The reference this trace describes (identity key in the registry). */
    public final TObjectName reference;
    public final BinderKind binderKind;
    /** Scope-machinery outcome; {@code null} for direct bindings. */
    public final ResolutionStatus status;
    /** Winning namespace; {@code null} for direct bindings or failed resolution. */
    public final INamespace namespace;
    /** Direct-binding target table; {@code null} for scope resolution. */
    public final TTable directTarget;
    /**
     * The AST node that DEFINES the binder: the {@code TTable} of a table
     * namespace, the {@code TCTE} of a CTE namespace (header column lists
     * included), the {@code TSelectSqlStatement} of a derived table, or the
     * direct-binding target table. This is what the publication proof checks
     * spans against; a trace without it cannot be complete.
     */
    public final Object definitionNode;
    /**
     * The reference's {@code sourceTable} AS OF capture time. Two roles:
     * (a) staleness signal — post-resolution correction handlers (QUALIFY /
     * USING / subquery-alias / MERGE restores) may change or clear it, and the
     * registry invalidates the trace when the current value differs by
     * identity; (b) the FROM-reference wrapper node of the binding chain — for
     * CTE and derived-table binds this is the {@code TTable} carrying the
     * {@code AS alias}, whose span the definition node alone does not cover.
     * A complete scope trace requires it.
     */
    public final TTable observedSourceTable;
    /** Scope-type name where resolution started; {@code null} for direct bindings. */
    public final String startingScope;
    /** Scope-type name where the winning match lives; {@code null} when unknown. */
    public final String matchedScope;
    /** The winning match's resolve path (display form); {@code null} when unknown. */
    public final String resolvePath;
    /** Number of matches the scope machinery reported (1 for a clean bind). */
    public final int matchCount;
    /**
     * Parent-scope hops from the starting scope to the matched scope; 0 for a
     * local bind, &gt; 0 for correlated references, -1 when the matched scope
     * was not on the starting scope's parent chain (unknown — incomplete).
     */
    public final int scopeClimbDepth;
    /**
     * TRUE iff the ENTIRE binding chain is known: an exact single-match scope
     * resolution with a recorded namespace, fully consumed name parts and a
     * known climb path — or a typed direct binding with a known target. The
     * P3 rule refuses anything else.
     */
    public final boolean complete;

    private BindingTrace(TObjectName reference, BinderKind binderKind, ResolutionStatus status,
            INamespace namespace, TTable directTarget, Object definitionNode,
            TTable observedSourceTable, String startingScope,
            String matchedScope, String resolvePath, int matchCount, int scopeClimbDepth,
            boolean complete) {
        this.reference = reference;
        this.binderKind = binderKind;
        this.status = status;
        this.namespace = namespace;
        this.directTarget = directTarget;
        this.definitionNode = definitionNode;
        this.observedSourceTable = observedSourceTable;
        this.startingScope = startingScope;
        this.matchedScope = matchedScope;
        this.resolvePath = resolvePath;
        this.matchCount = matchCount;
        this.scopeClimbDepth = scopeClimbDepth;
        this.complete = complete;
    }

    /**
     * Scope-machinery capture (NameResolver choke point). Complete only for an
     * exact single match with a recorded namespace AND its definition node, at
     * most the terminal column segment unconsumed, a known climb path, and NO
     * fallback involved (a struct-field fallback replaces the result after the
     * recorded match, so the match data no longer describes the binding).
     */
    public static BindingTrace scopeResolution(TObjectName reference, ResolutionStatus status,
            INamespace namespace, Object definitionNode, TTable observedSourceTable,
            String startingScope, String matchedScope,
            String resolvePath, int matchCount, int scopeClimbDepth, boolean fullyConsumed,
            boolean exactMatch, boolean fallbackUsed) {
        // observedSourceTable is ALSO the FROM-reference wrapper node (the
        // TTable carrying "AS alias") — the alias is part of the binding
        // chain, and the definition node alone (TCTE / derived-table SELECT)
        // does not cover its span. A complete chain requires BOTH.
        boolean complete = exactMatch && matchCount == 1 && namespace != null
                && definitionNode != null && observedSourceTable != null
                && fullyConsumed && scopeClimbDepth >= 0
                && !fallbackUsed;
        return new BindingTrace(reference, BinderKind.SCOPE_RESOLUTION, status, namespace, null,
                definitionNode, observedSourceTable, startingScope, matchedScope, resolvePath,
                matchCount, scopeClimbDepth, complete);
    }

    /** Typed direct-binding capture (ScopeBuilder clusters). */
    public static BindingTrace direct(TObjectName reference, BinderKind kind, TTable target) {
        return new BindingTrace(reference, kind, null, null, target, target, target,
                null, null, null, 1, 0, target != null);
    }

    @Override
    public String toString() {
        return "BindingTrace{" + binderKind + ", complete=" + complete
                + (status != null ? ", status=" + status : "")
                + (resolvePath != null ? ", path=" + resolvePath : "")
                + (directTarget != null ? ", target=" + directTarget.getName() : "")
                + ", climb=" + scopeClimbDepth + ", matches=" + matchCount + '}';
    }
}