feat(completion): configurable SQL completion trigger modes

This commit is contained in:
Abeautifulsnow authored and GitHub committed 2026-08-08 12:00:50 +08:00
1 parent bad7f6b472
commit 5b85f9eae8
18 files changed
+457 -18

No files matched your search

@@ -2,6 +2,7 @@ import { describe, expect, it } from "vitest";
import { buildSelectStarExpansion, buildSqlCompletionItems, getSqlCompletionContext, selectStarResultColumnsMatch, shouldAutoOpenSqlCompletion } from "@/lib/sql/sqlCompletion";
import { sqlCompletionContextFromSemantic } from "@/lib/sql/semantic/completion";
import { buildSqlSemanticModel } from "@/lib/sql/semantic/model";
import { originForSqlCompletionProvider, originForTypedSqlCompletionStart, shouldAllowSqlCompletionTrigger, type SqlCompletionTriggerFacts } from "@/lib/sql/sqlCompletionTriggerPolicy";
describe("sqlCompletion keyword snippets", () => {
it("auto-opens and suggests SELECT when typing sel", () => {
@@ -700,3 +701,109 @@ describe("sqlCompletion scoped metadata ranking", () => {
expect(sqlServerItems).toEqual([expect.objectContaining({ label: "Orders", apply: "Orders" })]);
});
});
describe("shouldAllowSqlCompletionTrigger", () => {
const typingFacts = (overrides: Partial<SqlCompletionTriggerFacts> = {}): SqlCompletionTriggerFacts => ({
origin: "typing",
hasIdentifierPrefix: false,
qualifierTriggered: false,
useDatabasePrefix: null,
...overrides,
});
const explicitFacts = (overrides: Partial<SqlCompletionTriggerFacts> = {}): SqlCompletionTriggerFacts => ({
origin: "explicit",
hasIdentifierPrefix: false,
qualifierTriggered: false,
useDatabasePrefix: null,
...overrides,
});
describe("explicit", () => {
it("allows explicit completion in any mode", () => {
expect(shouldAllowSqlCompletionTrigger("manual", explicitFacts())).toBe(true);
expect(shouldAllowSqlCompletionTrigger("require-prefix", explicitFacts())).toBe(true);
expect(shouldAllowSqlCompletionTrigger("positional", explicitFacts())).toBe(true);
});
});
describe("manual", () => {
it("rejects all typing completions", () => {
expect(shouldAllowSqlCompletionTrigger("manual", typingFacts())).toBe(false);
expect(shouldAllowSqlCompletionTrigger("manual", typingFacts({ hasIdentifierPrefix: true }))).toBe(false);
expect(shouldAllowSqlCompletionTrigger("manual", typingFacts({ qualifierTriggered: true }))).toBe(false);
expect(shouldAllowSqlCompletionTrigger("manual", typingFacts({ useDatabasePrefix: "m" }))).toBe(false);
expect(shouldAllowSqlCompletionTrigger("manual", typingFacts({ positionalEligible: true }))).toBe(false);
});
});
describe("require-prefix", () => {
it("allows when identifier prefix is non-empty", () => {
expect(shouldAllowSqlCompletionTrigger("require-prefix", typingFacts({ hasIdentifierPrefix: true }))).toBe(true);
});
it("allows when qualifier is triggered (dot with qualifier)", () => {
expect(shouldAllowSqlCompletionTrigger("require-prefix", typingFacts({ qualifierTriggered: true }))).toBe(true);
});
it("allows when useDatabasePrefix is non-empty", () => {
expect(shouldAllowSqlCompletionTrigger("require-prefix", typingFacts({ useDatabasePrefix: "m" }))).toBe(true);
expect(shouldAllowSqlCompletionTrigger("require-prefix", typingFacts({ useDatabasePrefix: "Bar" }))).toBe(true);
});
it("rejects empty prefix, no qualifier, no useDatabasePrefix", () => {
expect(shouldAllowSqlCompletionTrigger("require-prefix", typingFacts())).toBe(false);
});
it("rejects empty useDatabasePrefix (USE<space> without prefix)", () => {
expect(shouldAllowSqlCompletionTrigger("require-prefix", typingFacts({ useDatabasePrefix: "" }))).toBe(false);
});
it("does not use positionalEligible", () => {
// Even if positionalEligible is true, require-prefix ignores it.
expect(shouldAllowSqlCompletionTrigger("require-prefix", typingFacts({ positionalEligible: true }))).toBe(false);
});
});
describe("positional", () => {
it("allows when positionalEligible is true", () => {
expect(shouldAllowSqlCompletionTrigger("positional", typingFacts({ positionalEligible: true }))).toBe(true);
});
it("allows when useDatabasePrefix is set (even empty)", () => {
expect(shouldAllowSqlCompletionTrigger("positional", typingFacts({ useDatabasePrefix: "" }))).toBe(true);
expect(shouldAllowSqlCompletionTrigger("positional", typingFacts({ useDatabasePrefix: "m" }))).toBe(true);
});
it("rejects when positionalEligible is false and no useDatabasePrefix", () => {
expect(shouldAllowSqlCompletionTrigger("positional", typingFacts({ positionalEligible: false }))).toBe(false);
});
it("rejects when positionalEligible is undefined and no useDatabasePrefix", () => {
expect(shouldAllowSqlCompletionTrigger("positional", typingFacts())).toBe(false);
});
});
});
describe("originForTypedSqlCompletionStart", () => {
it("starts a new automatic session as typing", () => {
expect(originForTypedSqlCompletionStart(null)).toBe("typing");
});
it("preserves the origin of an active completion session", () => {
expect(originForTypedSqlCompletionStart("typing")).toBe("typing");
expect(originForTypedSqlCompletionStart("explicit")).toBe("explicit");
});
});
describe("originForSqlCompletionProvider", () => {
it("classifies an unmarked provider call from CodeMirror", () => {
expect(originForSqlCompletionProvider(null, false)).toBe("typing");
expect(originForSqlCompletionProvider(null, true)).toBe("explicit");
});
it("preserves the active session independently of the current provider flag", () => {
expect(originForSqlCompletionProvider("typing", true)).toBe("typing");
expect(originForSqlCompletionProvider("explicit", false)).toBe("explicit");
});
});
@@ -49,6 +49,10 @@ describe("EDITOR_SETTINGS_DRAFT_KEYS", () => {
it("includes the data-tab reuse mode", () => {
expect(EDITOR_SETTINGS_DRAFT_KEYS).toContain("dataTabReuseMode");
});
it("includes completionTriggerMode", () => {
expect(EDITOR_SETTINGS_DRAFT_KEYS).toContain("completionTriggerMode");
});
});
describe("editorSettingsDraftFromSettings", () => {
@@ -71,6 +75,16 @@ describe("editorSettingsDraftFromSettings", () => {
it("maps the saved SQL open target mode", () => {
expect(editorSettingsDraftFromSettings(makeSettings({ savedSqlOpenTargetMode: "current" })).savedSqlOpenTargetMode).toBe("current");
});
it("maps completionTriggerMode from settings", () => {
const draft = editorSettingsDraftFromSettings(makeSettings({ completionTriggerMode: "require-prefix" } as Partial<EditorSettings>));
expect(draft.completionTriggerMode).toBe("require-prefix");
});
it("normalizes invalid completionTriggerMode to positional", () => {
const draft = editorSettingsDraftFromSettings(makeSettings({ completionTriggerMode: "always" as unknown } as Partial<EditorSettings>));
expect(draft.completionTriggerMode).toBe("positional");
});
});
describe("normalizeTableOpenPageSizeDraft", () => {
@@ -127,6 +141,21 @@ describe("editorSettingsDraftChanged", () => {
draft.dataTabReuseMode = "active-tab";
expect(editorSettingsDraftChanged(draft, base)).toBe(true);
});
it("detects completionTriggerMode change", () => {
const settings = makeSettings({ completionTriggerMode: "positional" } as Partial<EditorSettings>);
const draft = editorSettingsDraftFromSettings(settings);
const base = editorSettingsDraftFromSettings(settings);
draft.completionTriggerMode = "manual";
expect(editorSettingsDraftChanged(draft, base)).toBe(true);
});
it("detects no change when completionTriggerMode matches", () => {
const settings = makeSettings({ completionTriggerMode: "require-prefix" } as Partial<EditorSettings>);
const draft = editorSettingsDraftFromSettings(settings);
const base = editorSettingsDraftFromSettings(settings);
expect(editorSettingsDraftChanged(draft, base)).toBe(false);
});
});
describe("editorSettingsPatchFromDraft", () => {
@@ -170,6 +199,23 @@ describe("editorSettingsPatchFromDraft", () => {
draft.dataTabReuseMode = "always-new";
expect(editorSettingsPatchFromDraft(draft, base).dataTabReuseMode).toBe("always-new");
});
it("includes completionTriggerMode in patch when changed", () => {
const settings = makeSettings({ completionTriggerMode: "positional" } as Partial<EditorSettings>);
const draft = editorSettingsDraftFromSettings(settings);
const base = editorSettingsDraftFromSettings(settings);
draft.completionTriggerMode = "manual";
const patch = editorSettingsPatchFromDraft(draft, base);
expect(patch.completionTriggerMode).toBe("manual");
});
it("omits completionTriggerMode when unchanged", () => {
const settings = makeSettings({ completionTriggerMode: "require-prefix" } as Partial<EditorSettings>);
const draft = editorSettingsDraftFromSettings(settings);
const base = editorSettingsDraftFromSettings(settings);
const patch = editorSettingsPatchFromDraft(draft, base);
expect(patch.completionTriggerMode).toBeUndefined();
});
});
describe("EDITOR_SETTINGS_DRAFT_KEYS - tabLayout", () => {
@@ -137,6 +137,7 @@ describe("settings search", () => {
{ titleKey: "toolbar.theme", category: "appearance", targetId: "appearance" },
{ titleKey: "settings.sidebarObjectInfoMode", category: "navigation", targetId: "navigation" },
{ titleKey: "settings.insertSpaceAfterCompletion", category: "editor", targetId: "editor" },
{ titleKey: "settings.completionTriggerMode", category: "editor", targetId: "editor" },
{ titleKey: "settings.autoAliasTables", category: "editor", targetId: "editor" },
{ titleKey: "settings.clickTableNavigationTarget", category: "editor", targetId: "editor" },
{ titleKey: "settings.sqlFormatterKeywordCase", category: "formatter", targetId: "formatter" },
@@ -1,5 +1,6 @@
import type { EditorSettings } from "@/stores/settingsStore";
import { normalizeResultPageSize } from "@/lib/dataGrid/paginationPageSize";
import { normalizeCompletionTriggerMode } from "@/lib/sql/sqlCompletionTriggerPolicy";
export const EDITOR_SETTINGS_DRAFT_KEYS = [
"fontFamily",
@@ -66,6 +67,7 @@ export const EDITOR_SETTINGS_DRAFT_KEYS = [
"sqlVariableSyntaxOverrides",
"continueOnErrorOnBatch",
"clickTableNavigationTarget",
"completionTriggerMode",
] as const satisfies readonly (keyof EditorSettings)[];
export type EditorSettingsDraftKey = (typeof EDITOR_SETTINGS_DRAFT_KEYS)[number];
@@ -83,6 +85,7 @@ export function normalizeTableOpenPageSizeDraft(value: unknown): number {
function normalizedDraftValue(key: EditorSettingsDraftKey, value: unknown): unknown {
if (key === "tableOpenPageSize") return normalizeTableOpenPageSizeDraft(value);
if (key === "completionTriggerMode") return normalizeCompletionTriggerMode(value);
return value;
}
@@ -114,6 +114,7 @@ export const SETTINGS_SEARCH_DEFINITIONS: readonly SettingsSearchDefinition[] =
{ id: "editor-vim", category: "editor", titleKey: "settings.vimMode", descriptionKey: "settings.vimModeDescription", targetId: "editor" },
{ id: "editor-brackets", category: "editor", titleKey: "settings.autoCloseBrackets", descriptionKey: "settings.autoCloseBracketsDescription", targetId: "editor" },
{ id: "editor-completion-spacing", category: "editor", titleKey: "settings.insertSpaceAfterCompletion", descriptionKey: "settings.insertSpaceAfterCompletionDescription", targetId: "editor" },
{ id: "editor-completion-trigger-mode", category: "editor", titleKey: "settings.completionTriggerMode", descriptionKey: "settings.completionTriggerModeDescription", targetId: "editor" },
{ id: "editor-auto-alias", category: "editor", titleKey: "settings.autoAliasTables", descriptionKey: "settings.autoAliasTablesDescription", targetId: "editor" },
{ id: "editor-unsaved-close", category: "editor", titleKey: "settings.confirmUnsavedSqlClose", descriptionKey: "settings.confirmUnsavedSqlCloseDescription", targetId: "editor" },
{ id: "editor-prefill-query", category: "editor", titleKey: "settings.prefillNewQueryWithSelect", descriptionKey: "settings.prefillNewQueryWithSelectDescription", targetId: "editor" },
@@ -0,0 +1,61 @@
export type SqlCompletionTriggerMode = "manual" | "require-prefix" | "positional";
export type SqlCompletionTriggerOrigin = "typing" | "explicit";
export const SQL_COMPLETION_TRIGGER_MODES: readonly SqlCompletionTriggerMode[] = ["manual", "require-prefix", "positional"];
export function originForTypedSqlCompletionStart(activeOrigin: SqlCompletionTriggerOrigin | null): SqlCompletionTriggerOrigin {
// Programmatic refreshes can run while a shortcut-opened session is active.
// Preserve that explicit origin so typing and metadata refreshes do not make
// the session subject to automatic-trigger mode gates.
return activeOrigin ?? "typing";
}
export function originForSqlCompletionProvider(activeOrigin: SqlCompletionTriggerOrigin | null, explicit: boolean): SqlCompletionTriggerOrigin {
// Programmatic starts set their origin before calling CodeMirror, while
// activate-on-typing calls the provider with explicit=false. Therefore an
// otherwise unmarked explicit call is always the manual shortcut session.
return activeOrigin ?? (explicit ? "explicit" : "typing");
}
export function normalizeCompletionTriggerMode(value: unknown): SqlCompletionTriggerMode {
if (typeof value === "string" && (value === "manual" || value === "require-prefix" || value === "positional")) {
return value;
}
return "positional";
}
export interface SqlCompletionTriggerFacts {
/** typing (DBX programmatic start / implicit) vs explicit (manual completion shortcut) */
origin: SqlCompletionTriggerOrigin;
/** completion context context.prefix.length > 0 (not trailing '.') */
hasIdentifierPrefix: boolean;
/** previousChar === "." && context.qualifier != null */
qualifierTriggered: boolean;
/** resolveSqlServerUseDatabaseCompletion().prefix ('m' / 'Bar' / '') */
useDatabasePrefix: string | null;
/** Only computed for positional mode: existing shouldAutoOpenSqlCompletion(sql, cursor, options) result */
positionalEligible?: boolean;
}
/**
* Pure trigger policy decision (the single gate, without sql/position itself).
*
* Decision rules (priority order):
* 1. suppressed context (comment / string literal) -> reject first (including explicit)
* 2. explicit -> allow directly (manual shortcut available in any mode)
* 3. manual -> false (return before any semantic model / metadata read)
* 4. require-prefix -> hasIdentifierPrefix || qualifierTriggered || (useDatabasePrefix != null && useDatabasePrefix.length > 0)
* 5. positional -> positionalEligible || useDatabasePrefix != null
*/
export function shouldAllowSqlCompletionTrigger(mode: SqlCompletionTriggerMode, facts: SqlCompletionTriggerFacts): boolean {
// Suppressed context (comment / string literal) is checked by the caller before
// constructing facts, so this function treats the caller as already gate-kept.
// However, for safety, explicit still bypasses mode checks.
if (facts.origin === "explicit") return true;
if (mode === "manual") return false;
if (mode === "require-prefix") {
return facts.hasIdentifierPrefix || facts.qualifierTriggered || (facts.useDatabasePrefix != null && facts.useDatabasePrefix.length > 0);
}
// positional
return (facts.positionalEligible ?? false) || facts.useDatabasePrefix != null;
}