schema: SQLNamespace,

tableRefs: Set<string>,

): SQLNamespace {

if (tableRefs.size === 0) {

// If no tables are referenced, return empty schema to avoid showing irrelevant columns

return {};

}

if (isObjectNamespace(schema)) {

const filtered: { [key: string]: SQLNamespace } = {};

for (const [key, value] of Object.entries(schema)) {

// Check if this table is referenced (case-insensitive)

const isReferenced = Array.from(tableRefs).some(

(refTable) => refTable.toLowerCase() === key.toLowerCase(),

);

if (isReferenced) {

// This table is referenced in the query

filtered[key] = value;

} else if (isObjectNamespace(value)) {

// Check if any child tables are referenced

const filteredChild = filterSchemaByTableRefs(value, tableRefs);

if (Object.keys(filteredChild).length > 0) {

filtered[key] = filteredChild;

}

}

}

return filtered;

}

// For other namespace types, return as-is (they might contain columns from referenced tables)

return schema;

description?: string;

syntax?: string;

example?: string;

metadata?: Record<string, string>;

item: ResolvedNamespaceItem;

/** The word being hovered over */

word: string;

/** The resolved schema context */

resolvedSchema: SQLNamespace;

/**

aliasFor?: string;

word: string;

view: EditorView;

pos: number;

tooltipType: "keyword" | "namespace";

keywordData?: KeywordTooltipData;

namespaceData?: NamespaceTooltipData;

/**

schema?: SQLNamespace | ((view: EditorView) => SQLNamespace);

/** SQL dialect for keyword information */

dialect?: SQLDialect | ((view: EditorView) => SQLDialect);

/** Custom keyword information */

keywords?:

| Record<string, SqlKeywordInfo>

| ((view: EditorView) => Promise<Record<string, SqlKeywordInfo>>);

/** Hover delay in milliseconds (default: 300) */

hoverTime?: number;

/** Enable hover for keywords (default: true) */

enableKeywords?: boolean;

/** Enable hover for tables (default: true) */

enableTables?: boolean;

/** Enable hover for columns (default: true) */

enableColumns?: boolean;

/** Enable fuzzy search for namespace items (default: false) */

enableFuzzySearch?: boolean;

/** Custom SQL parser instance to use for query analysis */

parser?: SqlParser;

/**

contextAnalyzer?: QueryContextAnalyzer;

/** Custom tooltip render function - highest priority, returns HTMLElement or null for fallback */

tooltipRender?: (word: string, view: EditorView, pos: number) => HTMLElement | null;

/** Custom tooltip renderers for different item types */

tooltipRenderers?: {

/** Custom renderer for SQL keywords */

keyword?: (data: KeywordTooltipData) => string;

/** Custom renderer for namespace items (database, schema, generic namespace) */

namespace?: (data: NamespaceTooltipData) => string;

/** Custom renderer for table items */

table?: (data: NamespaceTooltipData) => string;

/** Custom renderer for column items */

column?: (data: NamespaceTooltipData) => string;

};

/** Custom CSS theme for hover tooltips */

theme?: Extension;

config: SqlHoverConfig = {},

): (view: EditorView, pos: number, side: number) => Promise<Tooltip | null> {

const {

schema,

keywords = {},

enableKeywords = true,

enableTables = true,

enableColumns = true,

enableFuzzySearch = true,

parser = new NodeSqlParser(),

tooltipRender,

tooltipRenderers = {},

} = config;

const structureAnalyzer = new SqlStructureAnalyzer(parser);

const contextAnalyzer = config.contextAnalyzer ?? new QueryContextAnalyzer(parser);

let keywordsPromise: Promise<Record<string, SqlKeywordInfo>> | null = null;

return async (view: EditorView, pos: number, side: number): Promise<Tooltip | null> => {

const { from, to, text } = view.state.doc.lineAt(pos);

let start = pos;

let end = pos;

if (keywordsPromise === null) {

keywordsPromise =

typeof keywords === "function" ? keywords(view) : Promise.resolve(keywords);

}

let resolvedKeywords: Record<string, SqlKeywordInfo>;

try {

resolvedKeywords = await keywordsPromise;

} catch (error) {

// Don't cache a failed fetch; retry on the next hover

keywordsPromise = null;

debug("failed to resolve keywords", error);

resolvedKeywords = {};

}

// Find word boundaries (including dots for table.column syntax)

while (start > from && /[\w.]/.test(text[start - from - 1] ?? "")) start--;

while (end < to && /[\w.]/.test(text[end - from] ?? "")) end++;

// Validate pointer position within word

if ((start === pos && side < 0) || (end === pos && side > 0)) {

return null;

}

const word = text.slice(start - from, end - from).toLowerCase();

if (!word || word.length === 0) {

return null;

}

const resolvedSchema = resolveSqlSchema(schema, view) ?? {};

let createData: TooltipCreateData | null = null;

debug(`hover word: '${word}'`);

// Implement preference order:

// 1. Look in keywords if it exists

// 2. Look for it in SQLNamespace as is

// 3. If neither, look in SQLNamespace and try to guess (fuzzy match)

// Step 1: If no namespace match, try keywords

// Own-property check so Object.prototype members don't match

const keywordInfo = Object.hasOwn(resolvedKeywords, word)

? resolvedKeywords[word]

: undefined;

if (!createData && enableKeywords && keywordInfo) {

debug("keywordResult", word, keywordInfo);

const keywordData: KeywordTooltipData = { keyword: word, info: keywordInfo };

createData = {

word,

view,

pos,

tooltipType: "keyword",

keywordData,

};

}

// Step 2: Try to resolve directly in SQLNamespace (query-aware)

if (!createData && (enableTables || enableColumns) && resolvedSchema) {

// Scope the analysis to the statement containing the hover position, so

// tables from other statements in a multi-statement doc don't leak in

const statement = await structureAnalyzer.getStatementAtPosition(view.state, pos);

const statementSql = statement

? view.state.doc.sliceString(statement.from, statement.to)

: view.state.doc.toString();

const queryContext = await contextAnalyzer.getContext(statementSql, {

state: view.state,

});

// Rewrite alias-qualified words through the statement's alias map:

// `u` -> `users`, `u.name` -> `users.name`

const [firstSegment = "", ...restSegments] = word.split(".");

const aliasTarget = queryContext.aliases.get(firstSegment);

const lookupWord = aliasTarget

? [aliasTarget, ...restSegments].join(".").toLowerCase()

: word;

const aliasTable = queryContext.tables.find(

(table) => table.alias?.toLowerCase() === firstSegment,

);

const quotedAliasPath = aliasTable?.path.some((segment) => segment.includes("."))

? [...aliasTable.path, ...restSegments]

: null;

const tableRefs = new Set(queryContext.tables.map((table) => table.name.toLowerCase()));

// Filter schema to only include tables referenced in the current statement

const filteredSchema = filterSchemaByTableRefs(resolvedSchema, tableRefs);

// Try to resolve in the filtered schema first (query-aware)

let namespaceResult = quotedAliasPath

? traverseNamespacePath(filteredSchema, quotedAliasPath)

: resolveNamespaceItem(filteredSchema, lookupWord, { enableFuzzySearch });

// If no result in filtered schema and no tables were found in the

// statement, fall back to the full schema to show any relevant information

if (!namespaceResult && tableRefs.size === 0) {

namespaceResult = resolveNamespaceItem(resolvedSchema, lookupWord, {

enableFuzzySearch,

});

}

// Gate by the resolved semantic type so disabling only tables (or only

// columns) actually disables that kind of tooltip

if (namespaceResult) {

const { semanticType } = namespaceResult;

if (

(semanticType === "table" && !enableTables) ||

(semanticType === "column" && !enableColumns)

) {

namespaceResult = null;

}

}

if (namespaceResult) {

debug(

"namespaceResult (query-aware)",

word,

namespaceResult,

"tableRefs:",

Array.from(tableRefs),

);

const namespaceData: NamespaceTooltipData = {

item: namespaceResult,

word,

resolvedSchema: tableRefs.size > 0 ? filteredSchema : resolvedSchema,

...(aliasTarget ? { aliasFor: aliasTarget } : {}),

};

createData = {

word,

view,

pos,

tooltipType: "namespace",

namespaceData,

};

} else {

debug("No namespace item found for:", word);

}

}

// Step 3: Fuzzy matching is handled by resolveNamespaceItem if enableFuzzySearch is true

if (!createData) {

return null;

}

const tooltipData = createData;

return {

pos: start,

end,

above: true,

create(createView: EditorView) {

// Priority 1: Custom tooltipRender function

if (tooltipRender) {

const customElement = tooltipRender(word, createView, pos);

if (customElement) {

return { dom: customElement };

}

}

// Priority 2: Custom renderers and default renderers

let tooltipContent: string | null = null;

if (tooltipData.tooltipType === "keyword" && tooltipData.keywordData) {

tooltipContent = tooltipRenderers.keyword

? tooltipRenderers.keyword(tooltipData.keywordData)

: createKeywordTooltip(tooltipData.keywordData);

} else if (tooltipData.tooltipType === "namespace" && tooltipData.namespaceData) {

const namespaceData = tooltipData.namespaceData;

const { semanticType } = namespaceData.item;

if (semanticType === "table" && tooltipRenderers.table) {

tooltipContent = tooltipRenderers.table(namespaceData);

} else if (semanticType === "column" && tooltipRenderers.column) {

tooltipContent = tooltipRenderers.column(namespaceData);

} else if (

(semanticType === "database" ||

semanticType === "schema" ||

semanticType === "namespace") &&

tooltipRenderers.namespace

) {

tooltipContent = tooltipRenderers.namespace(namespaceData);

} else {

// Fallback to default renderer

tooltipContent = createNamespaceTooltip(namespaceData.item);

if (namespaceData.aliasFor) {

// Alias targets come from document text, so escape them

const aliasName = escapeHtml(namespaceData.word.split(".")[0] ?? "");

tooltipContent =

`<div class="sql-hover-alias"><code>${aliasName}</code> is an alias for <code>${escapeHtml(namespaceData.aliasFor)}</code></div>` +

tooltipContent;

}

}

}

if (!tooltipContent) {

return { dom: document.createElement("div") };

}

const dom = document.createElement("div");

dom.className = "cm-sql-hover-tooltip";

dom.innerHTML = tooltipContent;

return { dom };

},

};

};

return text

.replace(/&/g, "&amp;")

.replace(/</g, "&lt;")

.replace(/>/g, "&gt;")

.replace(/"/g, "&quot;");

const pathStr = item.path.join(".");

const name = item.completion?.label || item.value || item.path[item.path.length - 1] || "unknown";

let html = `<div class="sql-hover-${item.semanticType}">`;

html += `<div class="sql-hover-header"><strong>${name}</strong> <span class="sql-hover-type">${item.semanticType}</span></div>`;

// Add semantic-specific descriptions and information

switch (item.semanticType) {

case "database":

html += `<div class="sql-hover-description">Database${item.completion?.detail ? `: ${item.completion.detail}` : ""}</div>`;

if (item.namespace) {

const childCount = countNamespaceChildren(item.namespace);

if (childCount > 0) {

html += `<div class="sql-hover-children">Contains ${childCount} schema${childCount !== 1 ? "s" : ""}</div>`;

}

}

break;

case "schema":

html += `<div class="sql-hover-description">Schema${item.completion?.detail ? `: ${item.completion.detail}` : ""}</div>`;

if (pathStr) {

html += `<div class="sql-hover-path"><strong>Path:</strong> <code>${pathStr}</code></div>`;

}

if (item.namespace) {

const childCount = countNamespaceChildren(item.namespace);

if (childCount > 0) {

html += `<div class="sql-hover-children">Contains ${childCount} table${childCount !== 1 ? "s" : ""}</div>`;

}

}

break;

case "table":

html += `<div class="sql-hover-description">Table${item.completion?.detail ? `: ${item.completion.detail}` : ""}</div>`;

if (pathStr) {

const pathParts = item.path;

if (pathParts.length > 1) {

html += `<div class="sql-hover-path"><strong>Schema:</strong> <code>${pathParts.slice(0, -1).join(".")}</code></div>`;

}

}

// Show column information for tables

if (item.namespace && isArrayNamespace(item.namespace)) {

const columns = item.namespace;

if (columns.length > 0) {

html += `<div class="sql-hover-columns"><strong>Columns (${columns.length}):</strong><br>`;

const displayColumns = columns.slice(0, 8);

const columnNames = displayColumns.map((col) =>

typeof col === "string" ? col : col.label,

);

html += columnNames.map((col) => `<code>${col}</code>`).join(", ");

if (columns.length > 8) {

html += `, <em>and ${columns.length - 8} more...</em>`;

}

html += `</div>`;

}

}

break;

case "column":

html += `<div class="sql-hover-description">Column${item.completion?.detail ? `: ${item.completion.detail}` : ""}</div>`;

if (pathStr) {

const pathParts = item.path;

if (pathParts.length > 1) {

html += `<div class="sql-hover-path"><strong>Table:</strong> <code>${pathParts.slice(0, -1).join(".")}</code></div>`;

}

}

break;

default:

html += `<div class="sql-hover-description">Namespace${item.completion?.detail ? `: ${item.completion.detail}` : ""}</div>`;

if (pathStr) {

html += `<div class="sql-hover-path"><strong>Path:</strong> <code>${pathStr}</code></div>`;

}

if (item.namespace) {

const childCount = countNamespaceChildren(item.namespace);

if (childCount > 0) {

html += `<div class="sql-hover-children">Contains ${childCount} item${childCount !== 1 ? "s" : ""}</div>`;

}

}

break;

}

// Add completion-specific info if available

if (item.completion?.info && typeof item.completion.info === "string") {

html += `<div class="sql-hover-info">${item.completion.info}</div>`;

}

html += `</div>`;

return html;

if (Array.isArray(namespace)) {

return namespace.length;

} else if (typeof namespace === "object" && namespace !== null) {

if ("self" in namespace && "children" in namespace) {

return 1 + countNamespaceChildren(namespace.children);

} else {

return Object.keys(namespace).length;

}

}

return 0;

const { keyword, info } = opts;

let html = `<div class="sql-hover-keyword">`;

html += `<div class="sql-hover-header"><strong>${keyword.toUpperCase()}</strong> <span class="sql-hover-type">keyword</span></div>`;

html += `<div class="sql-hover-description">${info.description}</div>`;

if (info.syntax) {

html += `<div class="sql-hover-syntax"><strong>Syntax:</strong> <code>${info.syntax}</code></div>`;

}

if (info.example) {

html += `<div class="sql-hover-example"><strong>Example:</strong><br><code>${info.example}</code></div>`;

}

if (info.metadata && typeof info.metadata === "object" && Object.keys(info.metadata).length > 0) {

html += `<div class="sql-hover-metadata">`;

for (const [key, value] of Object.entries(info.metadata)) {

html += `<span class="sql-hover-tag" title="${key}">${value}</span> `;

}

html += `</div>`;

}

html += `</div>`;

return html;

tableName: string;

columns: string[];

metadata?: Record<string, string>;

}): string {

const { tableName, columns, metadata } = opts;

let html = `<div class="sql-hover-table">`;

html += `<div class="sql-hover-header"><strong>${tableName}</strong> <span class="sql-hover-type">table</span></div>`;

html += `<div class="sql-hover-description">Table with ${columns.length} column${columns.length !== 1 ? "s" : ""}</div>`;

if (columns.length > 0) {

html += `<div class="sql-hover-columns"><strong>Columns:</strong><br>`;

const displayColumns = columns.slice(0, 10); // Show max 10 columns

html += displayColumns.map((col) => `<code>${col}</code>`).join(", ");

if (columns.length > 10) {

html += `, <em>and ${columns.length - 10} more...</em>`;

}

html += `</div>`;

}

if (metadata && typeof metadata === "object" && Object.keys(metadata).length > 0) {

html += `<div class="sql-hover-metadata">`;

for (const [key, value] of Object.entries(metadata)) {

html += `<span class="sql-hover-tag" title="${key}">${value}</span> `;

}

html += `</div>`;

}

html += `</div>`;

return html;

tableName: string;

columnName: string;

schema: SqlSchema;

metadata?: Record<string, string>;

}): string {

const { tableName, columnName, schema, metadata } = opts;

let html = `<div class="sql-hover-column">`;

html += `<div class="sql-hover-header"><strong>${columnName}</strong> <span class="sql-hover-type">column</span></div>`;

html += `<div class="sql-hover-description">Column in table <code>${tableName}</code></div>`;

const allColumns = schema[tableName];

if (allColumns && allColumns.length > 1) {

const otherColumns = allColumns.filter((col) => col !== columnName);

if (otherColumns.length > 0) {

html += `<div class="sql-hover-related"><strong>Other columns in ${tableName}:</strong><br>`;

const displayColumns = otherColumns.slice(0, 8); // Show max 8 other columns

html += displayColumns.map((col) => `<code>${col}</code>`).join(", ");

if (otherColumns.length > 8) {

html += `, <em>and ${otherColumns.length - 8} more...</em>`;

}

html += `</div>`;

}

}

if (metadata && typeof metadata === "object" && Object.keys(metadata).length > 0) {

html += `<div class="sql-hover-metadata">`;

for (const [key, value] of Object.entries(metadata)) {

html += `<span class="sql-hover-tag" title="${key}">${value}</span> `;

}

html += `</div>`;

}

html += `</div>`;

return html;

// Theme-dependent color variables

const lightTheme = {

tooltipBg: "#ffffff",

tooltipBorder: "#e5e7eb",

tooltipText: "#374151",

tooltipTypeBg: "#f3f4f6",

tooltipTypeText: "#6b7280",

tooltipChildren: "#6b7280",

codeBg: "#f9fafb",

codeText: "#1f2937",

strong: "#111827",

em: "#6b7280",

header: "#111827",

info: "#374151",

related: "#374151",

path: "#374151",

example: "#374151",

columns: "#374151",

syntax: "#374151",

};

const darkTheme = {

tooltipBg: "#1f2937",

tooltipBorder: "#374151",

tooltipText: "#f9fafb",

tooltipTypeBg: "#374151",

tooltipTypeText: "#9ca3af",

tooltipChildren: "#9ca3af",

codeBg: "#374151",

codeText: "#f3f4f6",

strong: "#ffffff",

em: "#9ca3af",

header: "#ffffff",

info: "#d1d5db",

related: "#d1d5db",

path: "#d1d5db",

example: "#d1d5db",

columns: "#d1d5db",

syntax: "#d1d5db",

};

const colors = theme === "dark" ? darkTheme : lightTheme;

return EditorView.theme({

".cm-sql-hover-tooltip": {

padding: "8px 12px",

backgroundColor: colors.tooltipBg,

border: `1px solid ${colors.tooltipBorder}`,

borderRadius: "6px",

boxShadow: "0 4px 6px -1px rgba(0, 0, 0, 0.1), 0 2px 4px -1px rgba(0, 0, 0, 0.06)",

fontSize: "13px",

lineHeight: "1.4",

maxWidth: "320px",

fontFamily: "system-ui, -apple-system, sans-serif",

color: colors.tooltipText,

},

".cm-sql-hover-tooltip .sql-hover-header": {

marginBottom: "6px",

display: "flex",

alignItems: "center",

gap: "6px",

color: colors.header,

},

".cm-sql-hover-tooltip .sql-hover-type": {

fontSize: "11px",

padding: "2px 6px",

backgroundColor: colors.tooltipTypeBg,

color: colors.tooltipTypeText,

borderRadius: "4px",

fontWeight: "500",

},

".cm-sql-hover-tooltip .sql-hover-description": {

color: colors.info,

marginBottom: "8px",

},

".cm-sql-hover-tooltip .sql-hover-syntax": {

marginBottom: "8px",

color: colors.syntax,

},

".cm-sql-hover-tooltip .sql-hover-example": {

marginBottom: "4px",

color: colors.example,

},

".cm-sql-hover-tooltip .sql-hover-columns": {

marginBottom: "4px",

color: colors.columns,

},

".cm-sql-hover-tooltip .sql-hover-related": {

marginBottom: "4px",

color: colors.related,

},

".cm-sql-hover-tooltip .sql-hover-path": {

marginBottom: "4px",

color: colors.path,

},

".cm-sql-hover-tooltip .sql-hover-info": {

marginBottom: "4px",

color: colors.info,

},

".cm-sql-hover-tooltip .sql-hover-alias": {

marginBottom: "6px",

color: colors.tooltipChildren,

fontSize: "12px",

},

".cm-sql-hover-tooltip .sql-hover-children": {

marginBottom: "4px",

color: colors.tooltipChildren,

fontSize: "12px",

},

".cm-sql-hover-tooltip code": {

backgroundColor: colors.codeBg,

padding: "1px 4px",

borderRadius: "3px",

fontSize: "12px",

fontFamily: "ui-monospace, 'SF Mono', 'Monaco', 'Cascadia Code', 'Roboto Mono', monospace",

color: colors.codeText,

},

".cm-sql-hover-tooltip strong": {

fontWeight: "600",

color: colors.strong,

},

".cm-sql-hover-tooltip em": {

fontStyle: "italic",

color: colors.em,

},

});