package gudusoft.gsqlparser.dlineage.dynamicsql;

import gudusoft.gsqlparser.TCustomSqlStatement;
import gudusoft.gsqlparser.nodes.TObjectName;

import java.util.Collections;
import java.util.List;
import java.util.Map;

/**
 * B0 CONTRACT (design {@code docs/designs/sp/routine-summary-scc-design.md}
 * §2.3): the one canonical call-site binding interface. Implementations
 * arrive in slice B3 by adapting the existing vendor extractors (P5
 * literal/EXEC/USE/DBMS_SQL machinery becomes the lower layer); B0 ships the
 * contract only, so that B2 summary extraction and B3 application code are
 * written against a stable shape.
 *
 * <p>Binding rules the contract encodes (normative, from the design):
 * <ul>
 * <li>expression actuals bind as a FAN-IN of all leaf source columns plus a
 *     transform — never a single-column substitution;</li>
 * <li>OUT/INOUT/RETURN targets must be validated writable lvalues; an invalid
 *     OUT actual is diagnosed and causes summary application to quarantine
 *     the whole non-executable call, never fabricate a partial effect;</li>
 * <li>literal actuals produce no source (matching the inline engine);</li>
 * <li>INSERT…EXEC result-set consumption maps positionally, not via
 *     formals;</li>
 * <li>an unresolved or ambiguous callee binds NOTHING — ambiguity is
 *     reported, never guessed through.</li>
 * </ul>
 */
public interface RoutineCallBinder {

    /**
     * Resolve and bind one call site against the candidate definitions
     * visible to the analysis.
     *
     * @param callSite   the call statement (EXEC / CALL / function reference)
     * @param callerContext effective caller context (USE database, schema)
     * @return never null; {@link BindingResult#getStatus()} reports failures
     */
    BindingResult bind(TCustomSqlStatement callSite, CallerContext callerContext);

    /** Effective ambient context of the caller at the call site. */
    final class CallerContext {
        private final String database;
        private final String schema;

        public CallerContext(String database, String schema) {
            this.database = database;
            this.schema = schema;
        }

        public String getDatabase() { return database; }
        public String getSchema() { return schema; }
    }

    /** Outcome status of a bind attempt. */
    enum BindingStatus {
        /** Unique callee resolved; maps populated per the contract. */
        RESOLVED,
        /** Multiple compatible definitions — nothing bound, candidates reported. */
        AMBIGUOUS,
        /** Callee known only by signature (metadata) — binding maps populated, no body. */
        EXTERNAL,
        /** No candidate definition found. */
        UNRESOLVED
    }

    /** Completeness of the produced maps for a RESOLVED/EXTERNAL bind. */
    enum BindingCompleteness {
        COMPLETE,
        /** Some arguments could not be bound; reasons in diagnostics. */
        PARTIAL
    }

    /** Diagnostic codes surfaced by binding (design §2.1b/§2.3). */
    enum BindingDiagnosticCode {
        PROC_CALL_AMBIGUOUS_OVERLOAD,
        PROC_CALL_UNRESOLVED,
        PROC_CALL_OUT_TARGET_NOT_WRITABLE,
        /** Call-site OUTPUT was supplied for a formal not declared OUTPUT. */
        PROC_CALL_OUTPUT_MODE_MISMATCH,
        PROC_CALL_ARGUMENT_UNBOUND,
        PROC_CALL_EXTERNAL_SIGNATURE_ONLY
    }

    /** One structured diagnostic attached to a bind. */
    final class BindingDiagnostic {
        private final BindingDiagnosticCode code;
        private final String detail;

        public BindingDiagnostic(BindingDiagnosticCode code, String detail) {
            this.code = code;
            this.detail = detail == null ? "" : detail;
        }

        public BindingDiagnosticCode getCode() { return code; }
        public String getDetail() { return detail; }
    }

    /**
     * The leaf sources feeding one IN/INOUT formal: zero or more source
     * column references (zero for a pure literal actual) plus the actual
     * expression text when the actual is not a bare column/variable
     * (the transform carrier of the fan-in rule).
     */
    final class ActualSources {
        private final List<TObjectName> leafSources;
        private final String expressionText;

        public ActualSources(List<TObjectName> leafSources, String expressionText) {
            this.leafSources = leafSources == null
                    ? Collections.<TObjectName>emptyList()
                    : Collections.unmodifiableList(leafSources);
            this.expressionText = expressionText;
        }

        public List<TObjectName> getLeafSources() { return leafSources; }
        /** Null when the actual is a bare column/variable or literal. */
        public String getExpressionText() { return expressionText; }
    }

    /** A validated writable lvalue receiving an OUT/INOUT/RETURN/status flow. */
    final class WritableTarget {
        private final TObjectName target;

        public WritableTarget(TObjectName target) {
            this.target = target;
        }

        public TObjectName getTarget() { return target; }
    }

    /**
     * Positional mapping of a consumed result set (INSERT…EXEC and friends):
     * ordinal position in the routine's result-set shape → target column.
     */
    final class ResultSetMapping {
        private final List<TObjectName> positionalTargets;

        public ResultSetMapping(List<TObjectName> positionalTargets) {
            this.positionalTargets = positionalTargets == null
                    ? Collections.<TObjectName>emptyList()
                    : Collections.unmodifiableList(positionalTargets);
        }

        public List<TObjectName> getPositionalTargets() { return positionalTargets; }
    }

    /**
     * Canonical result of binding one call site (design §2.3). Formals are
     * addressed by declaration position (index into the resolved identity's
     * parameter lists) so the result never depends on name spelling.
     */
    final class BindingResult {
        private final BindingStatus status;
        private final RoutineIdentity resolved;
        private final List<RoutineIdentity> candidates;
        private final Map<Integer, ActualSources> inputs;
        private final Map<Integer, WritableTarget> outputs;
        private final WritableTarget returnTarget;
        private final ResultSetMapping resultSets;
        private final BindingCompleteness completeness;
        private final List<BindingDiagnostic> diagnostics;

        public BindingResult(BindingStatus status, RoutineIdentity resolved,
                List<RoutineIdentity> candidates,
                Map<Integer, ActualSources> inputs,
                Map<Integer, WritableTarget> outputs,
                WritableTarget returnTarget, ResultSetMapping resultSets,
                BindingCompleteness completeness,
                List<BindingDiagnostic> diagnostics) {
            this.status = status;
            this.resolved = resolved;
            this.candidates = candidates == null
                    ? Collections.<RoutineIdentity>emptyList()
                    : Collections.unmodifiableList(candidates);
            this.inputs = inputs == null
                    ? Collections.<Integer, ActualSources>emptyMap()
                    : Collections.unmodifiableMap(inputs);
            this.outputs = outputs == null
                    ? Collections.<Integer, WritableTarget>emptyMap()
                    : Collections.unmodifiableMap(outputs);
            this.returnTarget = returnTarget;
            this.resultSets = resultSets;
            this.completeness = completeness == null
                    ? BindingCompleteness.PARTIAL : completeness;
            this.diagnostics = diagnostics == null
                    ? Collections.<BindingDiagnostic>emptyList()
                    : Collections.unmodifiableList(diagnostics);
        }

        public BindingStatus getStatus() { return status; }
        /** Non-null only when status is RESOLVED or EXTERNAL. */
        public RoutineIdentity getResolved() { return resolved; }
        /** Populated when status is AMBIGUOUS. */
        public List<RoutineIdentity> getCandidates() { return candidates; }
        /** Formal position → sources feeding it (IN/INOUT reads). */
        public Map<Integer, ActualSources> getInputs() { return inputs; }
        /** Formal position → validated caller target (OUT/INOUT writes). */
        public Map<Integer, WritableTarget> getOutputs() { return outputs; }
        /** Null unless a function return / status flows to a caller target. */
        public WritableTarget getReturnTarget() { return returnTarget; }
        /** Null unless the call site consumes a result set positionally. */
        public ResultSetMapping getResultSets() { return resultSets; }
        public BindingCompleteness getCompleteness() { return completeness; }
        public List<BindingDiagnostic> getDiagnostics() { return diagnostics; }
    }
}