rawsql-ts 0.24.4 → 0.26.0

package/dist/src/index.d.ts

@@ -42,6 +42,8 @@ export * from './transformers/CTEDependencyAnalyzer';
 export * from './transformers/CTETableReferenceCollector';
 export * from './transformers/CTEQueryDecomposer';
 export type { CTERestorationResult } from './transformers/CTEQueryDecomposer';
+export * from './transformers/NamedQueryDefinitionExtractor';
+export * from './transformers/AstCommentAttachmentExtractor';
 export * from './transformers/CTEComposer';
 export * from './transformers/CTERenamer';
 export * from './transformers/AliasRenamer';
@@ -50,6 +52,7 @@ export * from './formatters/OriginalFormatRestorer';
 export * from './transformers/SqlIdentifierRenamer';
 export type { ScopeRange } from './transformers/SqlIdentifierRenamer';
 export * from './transformers/ColumnReferenceCollector';
+export * from './transformers/ClauseScopedColumnReferenceCollector';
 export * from './transformers/Formatter';
 export * from './transformers/SqlFormatter';
 export * from './transformers/QueryBuilder';
@@ -64,6 +67,9 @@ export * from './transformers/SimulatedSelectConverter';
 export * from './transformers/DDLToFixtureConverter';
 export * from './transformers/DDLGeneralizer';
 export * from './transformers/DDLDiffGenerator';
+export * from './transformers/SelectBodyExtractor';
+export * from './transformers/SelectOutputCollector';
+export * from './transformers/WildcardColumnInferenceCollector';
 export * from './transformers/SelectValueCollector';
 export * from './transformers/SelectableColumnCollector';
 export { DuplicateDetectionMode } from './transformers/SelectableColumnCollector';
@@ -71,6 +77,8 @@ export * from './transformers/FilterableItemCollector';
 export { FixtureCteBuilder, FixtureTableDefinition, FixtureColumnDefinition } from './transformers/FixtureCteBuilder';
 export * from './transformers/DynamicQueryBuilder';
 export * from './transformers/SSSQLFilterBuilder';
+export * from './transformers/ConditionOptimization';
+export * from './transformers/ParameterConditionPlacementOptimizer';
 export * from './transformers/PruneOptionalConditionBranches';
 export { SchemaInfo, optimizeUnusedLeftJoins, optimizeUnusedLeftJoinsToFixedPoint, optimizeUnusedCtes, optimizeUnusedCtesToFixedPoint } from './transformers/OptimizeUnusedLeftJoins';
 export * from './transformers/TableColumnResolver';

package/dist/src/parsers/FunctionExpressionParser.d.ts

@@ -6,6 +6,7 @@ export declare class FunctionExpressionParser {
      */
     private static readonly AGGREGATE_FUNCTIONS_WITH_ORDER_BY;
     private static readonly SQL_JSON_CONSTRUCTORS;
+    private static readonly QUANTIFIED_COMPARISON_FUNCTIONS;
     /**
      * Parse ARRAY expressions - handles both ARRAY[...] (literal) and ARRAY(...) (query) syntax
      * @param lexemes Array of lexemes to parse
@@ -31,6 +32,8 @@ export declare class FunctionExpressionParser {
      */
     private static parseBetweenUpperBound;
     private static parseFunctionCall;
+    private static isSubqueryArgumentStart;
+    private static parseSubqueryArgumentWithComments;
     /**
      * Captures SQL/JSON constructor arguments as RawString while preserving closing
      * comments via getClosingComments. Empty argument lists still use ValueList.

package/dist/src/parsers/SqlPrintTokenParser.d.ts

@@ -211,6 +211,7 @@ export declare class SqlPrintTokenParser implements SqlComponentVisitor<SqlPrint
     private visitValueList;
     private visitColumnReference;
     private visitFunctionCall;
+    private isQuantifiedComparisonFunction;
     private relocateGroupingSetComments;
     private isGroupingSetsFunction;
     private extractPositionedComments;

package/dist/src/transformers/AstCommentAttachmentExtractor.d.ts

@@ -0,0 +1,61 @@
+import { SqlComponent } from "../models/SqlComponent";
+/**
+ * Source span for a comment when parser metadata is available.
+ *
+ * @remarks The current parser stores comment text on AST nodes but does not
+ * retain reliable per-comment source spans, so extractors usually omit this.
+ */
+export interface AstCommentSourceRange {
+    start: number;
+    end: number;
+}
+/**
+ * Conservatively describes where an AST comment fact appears relative to syntax.
+ */
+export type AstCommentPlacement = "leading" | "trailing" | "inner" | "detached";
+/**
+ * Generic comment fact extracted from SQL AST comment metadata.
+ *
+ * @remarks `targetNode` is optional because SQL comments do not always have a
+ * strict syntactic owner. Ambiguous legacy buckets are emitted as detached.
+ */
+export interface AstCommentAttachment {
+    text: string;
+    sourceOrder: number;
+    placement: AstCommentPlacement;
+    targetNode?: SqlComponent;
+    range?: AstCommentSourceRange;
+}
+/**
+ * Extracts comment attachment facts already represented in the SQL AST.
+ *
+ * @remarks This API does not infer product-specific meanings or rewrite
+ * comments. It returns a deterministic flat list without mutating the input AST.
+ */
+export declare class AstCommentAttachmentExtractor {
+    private readonly attachments;
+    private readonly visited;
+    private readonly suppressedDetachedCommentArrays;
+    /**
+     * Extract comment attachment facts from a SQL AST component.
+     */
+    static extract(input: SqlComponent | null | undefined): AstCommentAttachment[];
+    private visit;
+    private visitSqlComponent;
+    private visitFallbackProperties;
+    private shouldSkipProperty;
+    private emitHeaderComments;
+    private emitLegacyComments;
+    private emitPositionedComments;
+    private emitSelectItemKeywordComments;
+    private emitKeywordPositionedComments;
+    private emitDetachedComments;
+    private emitComments;
+    private isSelectQuery;
+    private suppressWithClauseTrailingCommentsAlreadyCopiedToQuery;
+    private containsCommentSequence;
+}
+/**
+ * Extract comment attachment facts from a SQL AST component.
+ */
+export declare function extractAstCommentAttachments(input: SqlComponent | null | undefined): AstCommentAttachment[];

package/dist/src/transformers/ClauseScopedColumnReferenceCollector.d.ts

@@ -0,0 +1,47 @@
+import { SimpleSelectQuery } from "../models/SimpleSelectQuery";
+import { ColumnReference, ValueComponent } from "../models/ValueComponent";
+export type ClauseScopedColumnReferenceClause = "select" | "where" | "joinOn" | "groupBy" | "having" | "orderBy" | "window" | "limitOffset";
+export interface ClauseScopedColumnReferenceInfo {
+    clause: ClauseScopedColumnReferenceClause;
+    reference: ColumnReference;
+    qualifiedName: string;
+    namespaces: string[];
+    namespace: string | null;
+    column: string;
+    expression: ValueComponent;
+}
+export interface ClauseScopedColumnReferences {
+    select: ClauseScopedColumnReferenceInfo[];
+    where: ClauseScopedColumnReferenceInfo[];
+    joinOn: ClauseScopedColumnReferenceInfo[];
+    groupBy: ClauseScopedColumnReferenceInfo[];
+    having: ClauseScopedColumnReferenceInfo[];
+    orderBy: ClauseScopedColumnReferenceInfo[];
+    window: ClauseScopedColumnReferenceInfo[];
+    limitOffset: ClauseScopedColumnReferenceInfo[];
+}
+/**
+ * Collects ColumnReference nodes grouped by the root SimpleSelectQuery clause that owns them.
+ *
+ * Subquery and CTE bodies are intentionally not traversed because they have their own query-body
+ * ownership. Use ColumnReferenceCollector when comprehensive tree traversal is required.
+ */
+export declare class ClauseScopedColumnReferenceCollector {
+    collect(query: SimpleSelectQuery): ClauseScopedColumnReferences;
+    private createEmptyResult;
+    private collectFromSelectClause;
+    private collectFromJoinClauses;
+    private collectFromWhereClause;
+    private collectFromGroupByClause;
+    private collectFromHavingClause;
+    private collectFromOrderByClause;
+    private collectFromLimitClause;
+    private collectFromOffsetClause;
+    private collectFromFetchClause;
+    private collectFromWindowsClause;
+    private collectFromValueComponent;
+    private collectFromFunctionCall;
+    private collectFromWindowFrameExpression;
+    private createInfo;
+    private getNameText;
+}

package/dist/src/transformers/ConditionOptimization.d.ts

@@ -0,0 +1,66 @@
+import { SelectQuery, SimpleSelectQuery } from "../models/SelectQuery";
+import { ParameterConditionMove, ParameterConditionOptimizationError, ParameterConditionOptimizationOptions, ParameterConditionOptimizationWarning, ParameterConditionSkipped } from "./ParameterConditionPlacementOptimizer";
+import { OptionalConditionPruningParameters } from "./PruneOptionalConditionBranches";
+export type ConditionOptimizationInput = string | SelectQuery | SimpleSelectQuery;
+export type ConditionOptimizationPhaseKind = "sssql_optional_condition" | "parameter_condition_placement";
+export interface ConditionOptimizationOptions extends ParameterConditionOptimizationOptions {
+    /**
+     * Explicit opt-in values for SSSQL optional branch pruning.
+     * Only listed parameter names are considered, and only null/undefined values
+     * are pruned by the safe-only SSSQL phase.
+     */
+    optionalConditionParameters?: OptionalConditionPruningParameters;
+}
+export interface ConditionOptimizationPhaseSummary {
+    kind: ConditionOptimizationPhaseKind;
+    appliedCount: number;
+    skippedCount: number;
+    warningCount: number;
+    errorCount: number;
+}
+export interface SssqlOptionalConditionApplied {
+    phaseKind: "sssql_optional_condition";
+    kind: "prune_optional_branch" | "refresh_optional_branch";
+    conditionSql: string;
+    parameterName: string;
+    reason: string;
+    previousConditionSql?: string;
+}
+export interface SssqlOptionalConditionSkipped {
+    phaseKind: "sssql_optional_condition";
+    kind: "optional_branch_skipped";
+    conditionSql: string;
+    parameterName: string;
+    code: string;
+    reason: string;
+}
+export type ConditionOptimizationApplied = SssqlOptionalConditionApplied | (ParameterConditionMove & {
+    phaseKind: "parameter_condition_placement";
+});
+export type ConditionOptimizationSkipped = SssqlOptionalConditionSkipped | (ParameterConditionSkipped & {
+    phaseKind: "parameter_condition_placement";
+});
+export type ConditionOptimizationWarning = (ParameterConditionOptimizationWarning & {
+    phaseKind: ConditionOptimizationPhaseKind;
+});
+export type ConditionOptimizationError = (ParameterConditionOptimizationError & {
+    phaseKind: ConditionOptimizationPhaseKind;
+});
+export interface ConditionOptimizationSafety {
+    mode: "safe_only";
+    unsafeRewriteApplied: false;
+    dryRun: boolean;
+    formatterGeneratedSource: boolean;
+}
+export interface ConditionOptimizationResult {
+    ok: boolean;
+    sql: string;
+    phases: readonly ConditionOptimizationPhaseSummary[];
+    applied: readonly ConditionOptimizationApplied[];
+    skipped: readonly ConditionOptimizationSkipped[];
+    warnings: readonly ConditionOptimizationWarning[];
+    errors: readonly ConditionOptimizationError[];
+    safety: ConditionOptimizationSafety;
+}
+export declare const planConditionOptimization: (input: ConditionOptimizationInput, options?: ConditionOptimizationOptions) => ConditionOptimizationResult;
+export declare const optimizeConditions: (input: ConditionOptimizationInput, options?: ConditionOptimizationOptions) => ConditionOptimizationResult;

package/dist/src/transformers/NamedQueryDefinitionExtractor.d.ts

@@ -0,0 +1,53 @@
+import { CTEQuery } from "../models/Clause";
+import { SqlComponent } from "../models/SqlComponent";
+/**
+ * Source span for a named query definition when parser position metadata is available.
+ *
+ * @remarks The current extractor does not synthesize ranges. `range` and `nameRange`
+ * are returned as `null` until AST nodes expose reliable definition spans.
+ */
+export interface NamedQueryDefinitionSourceRange {
+    start: number;
+    end: number;
+}
+/**
+ * DTO-style representation of a named query definition from a SQL AST.
+ */
+export interface NamedQueryDefinition {
+    /** The stable definition name, such as a CTE alias. */
+    name: string;
+    /** The AST query node that defines the named query. */
+    query: CTEQuery;
+    /** Whether the definition belongs to a `WITH RECURSIVE` clause, when that context is available. */
+    recursive?: boolean;
+    /** Full definition source range when available. Currently `null`. */
+    range: NamedQueryDefinitionSourceRange | null;
+    /** Definition-name source range when available. Currently `null`. */
+    nameRange: NamedQueryDefinitionSourceRange | null;
+}
+/**
+ * Extracts named query definitions, starting with CTE definitions from `WITH` clauses.
+ *
+ * @remarks Definitions are emitted in SQL source order. For nested CTEs, the outer
+ * CTE definition is emitted when its name is encountered, then definitions inside
+ * that CTE body are emitted before later sibling CTE definitions.
+ */
+export declare class NamedQueryDefinitionExtractor {
+    private readonly definitions;
+    private readonly visited;
+    /**
+     * Extract named query definitions from an AST component.
+     */
+    static extract(input: SqlComponent | null | undefined): NamedQueryDefinition[];
+    private visit;
+    private visitSelectQuery;
+    private visitSimpleSelectQuery;
+    private visitInsertQuery;
+    private visitUpdateQuery;
+    private visitDeleteQuery;
+    private visitMergeQuery;
+    private visitWithClause;
+    private visitCommonTable;
+    private visitKnownSqlComponent;
+    private visitKnownValueComponent;
+}

package/dist/src/transformers/ParameterConditionPlacementOptimizer.d.ts

@@ -0,0 +1,85 @@
+import { SelectQuery, SimpleSelectQuery } from "../models/SelectQuery";
+export type ParameterConditionOptimizationInput = string | SelectQuery | SimpleSelectQuery;
+/**
+ * First-phase safe-only placement for ordinary parameter predicates.
+ *
+ * The optimizer intentionally handles only root top-level AND predicates and one
+ * CTE/derived-table hop where the destination output is a direct column reference.
+ * Unsupported boundaries such as OR, UNION, DISTINCT, GROUP BY, WINDOW, OUTER
+ * JOIN, expression outputs, and function predicates are reported as skipped.
+ */
+export interface ParameterConditionOptimizationOptions {
+    dryRun?: boolean;
+}
+export interface ParameterConditionOptimizationWarning {
+    code: string;
+    message: string;
+    detail?: unknown;
+}
+export interface ParameterConditionOptimizationError {
+    code: string;
+    message: string;
+    detail?: unknown;
+}
+export interface ParameterConditionMove {
+    kind: "move_condition";
+    conditionSql: string;
+    fromScopeId: string;
+    toScopeId: string;
+    reason: string;
+    parameterNames: readonly string[];
+    columnReferences: readonly string[];
+}
+export interface ParameterConditionSkipped {
+    conditionSql: string;
+    scopeId: string;
+    reason: string;
+    code: string;
+}
+export interface ParameterConditionOptimizationSafety {
+    mode: "safe_only";
+    unsafeRewriteApplied: false;
+    dryRun: boolean;
+    formatterGeneratedSource: boolean;
+}
+export interface ParameterConditionOptimizationResult {
+    ok: boolean;
+    sql: string;
+    applied: readonly ParameterConditionMove[];
+    skipped: readonly ParameterConditionSkipped[];
+    warnings: readonly ParameterConditionOptimizationWarning[];
+    errors: readonly ParameterConditionOptimizationError[];
+    safety: ParameterConditionOptimizationSafety;
+    conditionMoves: readonly ParameterConditionMove[];
+}
+export declare class ParameterConditionPlacementOptimizer {
+    plan(input: ParameterConditionOptimizationInput, options?: ParameterConditionOptimizationOptions): ParameterConditionOptimizationResult;
+    optimize(input: ParameterConditionOptimizationInput, options?: ParameterConditionOptimizationOptions): ParameterConditionOptimizationResult;
+    private parseInput;
+    private analyzeCandidate;
+    private findUnsupportedExpression;
+    private isSupportedInPredicate;
+    private resolveTarget;
+    private findCurrentQueryBoundary;
+    private findTargetQueryBoundary;
+    private resolveSourceBinding;
+    private resolveUpstreamQuery;
+    private resolveTargetColumn;
+    private verifyColumnResolvableInQuery;
+    private rebaseCondition;
+    private getSourceBindings;
+    private findNullableSideBoundary;
+    private hasOuterJoin;
+    private getOutputColumnMatchCount;
+    private resolveSourceQueryForColumns;
+    private getSelectItemOutputName;
+    private findCte;
+    private countTableSourceReferences;
+    private hasWindowUsage;
+    private collectColumnReferences;
+    private collectParameterNames;
+    private makeSkipped;
+    private buildResult;
+}
+export declare const planParameterConditionOptimization: (input: ParameterConditionOptimizationInput, options?: ParameterConditionOptimizationOptions) => ParameterConditionOptimizationResult;
+export declare const optimizeParameterConditionPlacement: (input: ParameterConditionOptimizationInput, options?: ParameterConditionOptimizationOptions) => ParameterConditionOptimizationResult;

package/dist/src/transformers/SelectBodyExtractor.d.ts

@@ -0,0 +1,21 @@
+import { SelectQuery } from "../models/SelectQuery";
+import { SqlComponent } from "../models/SqlComponent";
+export type SelectBodyWrapperKind = "create-table-as" | "create-view" | "create-materialized-view" | "insert-select";
+export interface SelectBodyExtractionResult {
+    supported: boolean;
+    kind: SelectBodyWrapperKind | null;
+    targetName: string | null;
+    selectQuery: SelectQuery | null;
+    reason?: string;
+}
+export declare class SelectBodyExtractor {
+    static extract(input: string | SqlComponent): SelectBodyExtractionResult;
+    private static extractFromSql;
+    private static extractFromStatement;
+    private static extractCreateViewFromLexemes;
+    private static isCreateViewStatement;
+    private static consumeBalancedParentheses;
+    private static createTableTargetName;
+    private static insertTargetName;
+    private static unsupported;
+}

package/dist/src/transformers/SelectOutputCollector.d.ts

@@ -0,0 +1,47 @@
+import { CommonTable } from "../models/Clause";
+import { SqlComponent } from "../models/SqlComponent";
+import { ValueComponent } from "../models/ValueComponent";
+import { TableColumnResolver } from "./TableColumnResolver";
+export interface SelectOutputColumn {
+    name: string;
+    value: ValueComponent;
+    outputIndex: number;
+    sourceAlias: string | null;
+    sourceName: string | null;
+    sourceColumnName: string | null;
+}
+/**
+ * Collects SELECT output columns without collapsing duplicate output names.
+ *
+ * This collector is intended for callers that need stable SELECT-list positions.
+ * It keeps output order and assigns outputIndex after supported wildcard expansion.
+ */
+export declare class SelectOutputCollector {
+    private tableColumnResolver;
+    private commonTableCollector;
+    private commonTables;
+    constructor(tableColumnResolver?: TableColumnResolver | null, initialCommonTables?: CommonTable[] | null);
+    collect(arg: SqlComponent): SelectOutputColumn[];
+    private collectRaw;
+    private collectSimpleSelectQuery;
+    private collectSelectItem;
+    private expandWildcard;
+    private collectFromClause;
+    private collectJoinClause;
+    private getJoinSourceName;
+    private collectSourceExpression;
+    private findCommonTable;
+    private collectTableSource;
+    private collectNestedSelectQuery;
+    private collectCteQuery;
+    private collectReturningOutputs;
+    private extractReturningOutputs;
+    private extractSelectItemName;
+    private qualifyOutputs;
+    private createExplicitOutput;
+    private resolveColumnSourceMetadata;
+    private getSourceMatchNames;
+    private getColumnReferenceSourceAlias;
+    private getColumnReferenceSourceName;
+    private isSelectQuery;
+}

package/dist/src/transformers/SelectValueCollector.d.ts

@@ -16,7 +16,8 @@ export declare class SelectValueCollector implements SqlComponentVisitor<void> {
     private commonTableCollector;
     private commonTables;
     initialCommonTables: CommonTable[] | null;
-    constructor(tableColumnResolver?: TableColumnResolver | null, initialCommonTables?: CommonTable[] | null);
+    private preserveDuplicateSelectItems;
+    constructor(tableColumnResolver?: TableColumnResolver | null, initialCommonTables?: CommonTable[] | null, preserveDuplicateSelectItems?: boolean);
     /**
      * Get all collected SelectItems as an array of objects with name and value properties
      * @returns An array of objects with name (string) and value (ValueComponent) properties
@@ -50,11 +51,18 @@ export declare class SelectValueCollector implements SqlComponentVisitor<void> {
     private processFromClause;
     private processJoinClause;
     private processSourceExpression;
+    private expandWildcardValue;
+    private collectFromClauseValues;
+    private collectJoinClauseValues;
+    private getJoinSourceName;
+    private collectSourceExpressionValues;
     private visitSelectClause;
     private processSelectItem;
     private visitSourceExpression;
     private visitFromClause;
     private addSelectValueAsUnique;
+    private addSelectValue;
+    private addSelectValueFromSelectItem;
     private collectValuesFromCteQuery;
     private collectValuesFromReturning;
     private extractValuesFromReturningClause;

package/dist/src/transformers/WildcardColumnInferenceCollector.d.ts

@@ -0,0 +1,129 @@
+import { SelectQuery } from "../models/SelectQuery";
+import { ClauseScopedColumnReferenceClause } from "./ClauseScopedColumnReferenceCollector";
+/** Kind of named query boundary whose wildcard output is being inferred. */
+export type WildcardColumnInferenceTargetKind = "cte" | "derivedTable";
+/** Syntax form of the wildcard SELECT item that may supply required columns. */
+export type WildcardColumnInferenceWildcardKind = "qualified" | "unqualified";
+/** Conservative reason why a downstream requirement could not be assigned to one wildcard supplier. */
+export type WildcardColumnInferenceUnresolvedReason = "duplicateOutputOwnership" | "multipleWildcardSuppliers" | "unqualifiedWildcardMultipleSources" | "noWildcardSupplier" | "unsupportedQueryShape";
+/** Clause-scoped downstream reference that requires an output column from the target. */
+export interface WildcardColumnInferenceRequiredBy {
+    /** Clause that owns the downstream reference. */
+    clause: ClauseScopedColumnReferenceClause;
+    /** SQL text form of the downstream column reference. */
+    qualifiedName: string;
+    /** Namespace or alias used by the downstream reference, if present. */
+    namespace: string | null;
+    /** Output column name required by the downstream reference. */
+    column: string;
+}
+/** Metadata for a wildcard SELECT item inside the target query. */
+export interface WildcardColumnInferenceWildcard {
+    /** Whether the wildcard was written as `*` or as a qualified form such as `a.*`. */
+    kind: WildcardColumnInferenceWildcardKind;
+    /** SELECT-list position of the wildcard item. */
+    outputIndex: number;
+    /** Source alias that the wildcard can safely be associated with, when known. */
+    sourceAlias: string | null;
+    /** Physical source name for the wildcard source, when it is statically visible. */
+    sourceName: string | null;
+}
+/** Explicit non-wildcard output preserved alongside inferred wildcard requirements. */
+export interface WildcardColumnInferenceExplicitColumn {
+    /** Output name exposed by the explicit SELECT item. */
+    outputName: string;
+    /** Source alias for a simple qualified column expression, when uniquely known. */
+    sourceAlias: string | null;
+    /** Physical source name for a simple qualified column expression, when uniquely known. */
+    sourceName: string | null;
+    /** Source column name for a simple qualified column expression, when uniquely known. */
+    sourceColumnName: string | null;
+}
+/** Resolved required column supplied by a single unambiguous wildcard. */
+export interface WildcardColumnInferenceResolvedColumn {
+    /** Output column name required from the target. */
+    outputName: string;
+    /** Source alias selected as the wildcard supplier. */
+    sourceAlias: string | null;
+    /** Physical source name selected as the wildcard supplier, when known. */
+    sourceName: string | null;
+    /** Source column name inferred from the downstream output requirement. */
+    sourceColumnName: string;
+    /** Wildcard SELECT item that supplies this required column. */
+    wildcard: WildcardColumnInferenceWildcard;
+    /** Distinct downstream clauses that required this column. */
+    requiredByClause: ClauseScopedColumnReferenceClause[];
+    /** Clause-scoped downstream references that required this column. */
+    requiredBy: WildcardColumnInferenceRequiredBy[];
+}
+/** Required output column that could not be assigned to a single wildcard supplier. */
+export interface WildcardColumnInferenceUnresolvedColumn {
+    /** Output column name required from the target. */
+    outputName: string;
+    /** Conservative reason why inference did not choose a supplier. */
+    reason: WildcardColumnInferenceUnresolvedReason;
+    /** Candidate wildcard suppliers visible for this requirement. */
+    candidateWildcards: WildcardColumnInferenceWildcard[];
+    /** Distinct downstream clauses that required this column. */
+    requiredByClause: ClauseScopedColumnReferenceClause[];
+    /** Clause-scoped downstream references that required this column. */
+    requiredBy: WildcardColumnInferenceRequiredBy[];
+}
+/** Metadata-only wildcard inference result for one CTE or derived table target. */
+export interface WildcardColumnInferenceResult {
+    /** Kind of target whose wildcard output was inspected. */
+    targetKind: WildcardColumnInferenceTargetKind;
+    /** CTE name for CTE targets, otherwise null. */
+    targetName: string | null;
+    /** Alias used by the downstream consumer when available. */
+    targetAlias: string | null;
+    /** Wildcard SELECT items found inside the target query. */
+    wildcards: WildcardColumnInferenceWildcard[];
+    /** Explicit non-wildcard outputs found inside the target query. */
+    explicitColumns: WildcardColumnInferenceExplicitColumn[];
+    /** Downstream requirements assigned to exactly one wildcard supplier. */
+    requiredColumns: WildcardColumnInferenceResolvedColumn[];
+    /** Downstream requirements that were intentionally left unresolved. */
+    unresolvedColumns: WildcardColumnInferenceUnresolvedColumn[];
+}
+/**
+ * Infers the subset of wildcard columns required by downstream references.
+ *
+ * This collector only returns metadata. It does not rewrite SQL and does not attempt full
+ * table-column discovery. When ownership is ambiguous, the requirement is reported as unresolved.
+ */
+export declare class WildcardColumnInferenceCollector {
+    private readonly clauseCollector;
+    private readonly requirements;
+    private readonly visitedQueries;
+    private nextObjectId;
+    private objectIds;
+    /**
+     * Collect wildcard column inference metadata for CTEs and derived tables visible in a SELECT query.
+     */
+    collect(query: SelectQuery): WildcardColumnInferenceResult[];
+    private collectFromSelectQuery;
+    private collectCteQuery;
+    private collectConsumerRequirements;
+    private collectConsumerTargets;
+    private createCteTarget;
+    private createDerivedTableTarget;
+    private collectNestedSources;
+    private addRequirement;
+    private inferTarget;
+    private collectTargetOutputMetadata;
+    private collectWildcardMetadata;
+    private createUnresolved;
+    private flattenReferences;
+    private createRequiredBy;
+    private collectRequiredByClauses;
+    private getTargetMatchNames;
+    private getUniqueTarget;
+    private getUniqueSource;
+    private getSourceMatchNames;
+    private getSourceName;
+    private collectLeadingCommonTables;
+    private mergeCommonTables;
+    private getObjectId;
+    private isSelectQuery;
+}