Merge pull request #228 from DTStack/next

Sync next to main

Author: Cythia828

README-zh_CN.md

@@ -205,6 +205,45 @@ npm install monaco-sql-languages
 
 <br/>
 
+## 运行语句按钮
+
+在每条 SQL 语句前显示 gutter 运行图标。创建编辑器后调用 `createRunStatementButton`，编辑器销毁时调用 `dispose()`。
+
+```typescript
+import {
+    LanguageIdEnum,
+    createRunStatementButton,
+    getStatementRangesByLanguage
+} from 'monaco-sql-languages';
+
+const controller = createRunStatementButton({
+    editor,
+    languageId: LanguageIdEnum.FLINK,
+    glyphMarginHoverMessage: '运行此语句',
+    preprocessCode: (code) => code,
+    onRun: ({ statement, editor, model }) => {
+        console.log(statement.text);
+    }
+});
+
+// controller.refresh(); // 需要时手动刷新图标
+// controller.dispose(); // 编辑器卸载时调用
+```
+
+**说明**
+
+- 建议显式传入 `languageId`，以便内置拆分器使用正确的 parser。
+- 自定义 `getStatementRanges` 只需提供准确的 `startLineNumber` 和 `text`，`executableLineNumber` 会自动归一化。
+- 编辑器只读时不显示图标，且忽略点击。
+- 若只需内置拆分逻辑，可单独使用 `getStatementRangesByLanguage(code, languageId, preprocessCode)`。
+- `preprocessCode` 必须与编辑器 model 保持行号对齐（不要增删行导致行号偏移）；装饰是打在原始 model 上的。
+- 默认情况下，仅空白或仅分号的片段（如 `;;;`）不显示运行图标。
+- `executableLineNumber` 会跳过 leading 注释，但不解析字符串字面量；若 leading 字符串内含 `/*` 或 `--` 可能误判（实际场景较少见）。
+- 多条语句的 `executableLineNumber` 相同时会输出 console 警告，gutter 点击以最后一条为准。
+- 编辑器销毁时请调用 `controller.dispose()`（每个编辑器实例对应一个 controller）。
+
+<br/>
+
 ## 代码片段
 我们为每种SQL语言内置了一部分代码片段, 帮助我们快速编写SQL。
 

README.md

@@ -205,6 +205,45 @@ npm install monaco-sql-languages
 
 <br/>
 
+## Run Statement Button
+
+Add a gutter run icon before each SQL statement. Call `createRunStatementButton` after creating the editor and dispose the controller when the editor is destroyed.
+
+```typescript
+import {
+    LanguageIdEnum,
+    createRunStatementButton,
+    getStatementRangesByLanguage
+} from 'monaco-sql-languages';
+
+const controller = createRunStatementButton({
+    editor,
+    languageId: LanguageIdEnum.FLINK,
+    glyphMarginHoverMessage: 'Run this statement',
+    preprocessCode: (code) => code,
+    onRun: ({ statement, editor, model }) => {
+        console.log(statement.text);
+    }
+});
+
+// controller.refresh(); // recompute icons manually when needed
+// controller.dispose(); // on editor unmount
+```
+
+**Notes**
+
+- Pass `languageId` explicitly so the built-in splitter uses the correct parser.
+- Custom `getStatementRanges` only needs accurate `startLineNumber` and `text`; `executableLineNumber` is normalized automatically.
+- Icons are hidden and clicks are ignored when the editor is read-only.
+- Use `getStatementRangesByLanguage(code, languageId, preprocessCode)` if you need the built-in splitter outside the button.
+- `preprocessCode` must keep the same line mapping as the editor model (no insert/delete that shifts lines); decorations are applied to the original model.
+- By default, blank or semicolon-only fragments (e.g. `;;;`) do not show a run icon.
+- `executableLineNumber` detection skips leading comments but does not parse string literals; a leading string that contains `/*` or `--` may be misidentified (rare in practice).
+- When multiple statements share the same `executableLineNumber`, a console warning is emitted and the last one wins for gutter clicks.
+- Call `controller.dispose()` when the editor is destroyed (one controller per editor instance).
+
+<br/>
+
 ## SQL Snippets
 
 We provide some built-in SQL snippets for each SQL language, which helps us to write SQL quickly.

package.json

@@ -104,6 +104,6 @@
 		]
 	},
 	"dependencies": {
-		"dt-sql-parser": "4.5.0"
+		"dt-sql-parser": "4.5.1"
 	}
 }

pnpm-lock.yaml

@@ -1,10 +1,16 @@
+export interface DebouncedFunction<T extends (...args: unknown[]) => unknown> {
+	(...args: Parameters<T>): unknown;
+	cancel: () => void;
+}
+
 export function debounce<T extends (...args: unknown[]) => unknown>(
 	func: T,
 	timeout: number,
 	immediate?: boolean
-): (...args: Parameters<T>) => unknown {
+): DebouncedFunction<T> {
 	let timer: NodeJS.Timeout | null = null;
-	return (...args) => {
+
+	const debounced = (...args: Parameters<T>) => {
 		if (timer) {
 			clearTimeout(timer);
 		}
@@ -18,4 +24,13 @@ export function debounce<T extends (...args: unknown[]) => unknown>(
 			func?.(...args);
 		}, timeout);
 	};
+
+	debounced.cancel = () => {
+		if (timer) {
+			clearTimeout(timer);
+			timer = null;
+		}
+	};
+
+	return debounced;
 }

src/common/utils.ts

@@ -145,6 +145,33 @@ function toDiagnostics(_resource: Uri, diag: ParseError): editor.IMarkerData {
 	};
 }
 
+interface TokenizationTextModel {
+	tokenization?: {
+		tokenizeLinesAt?: (
+			lineNumber: number,
+			lines: string[]
+		) => Array<{
+			findTokenIndexAtOffset: (offset: number) => number;
+			getStandardTokenType: (tokenIndex: number) => number;
+		}> | null;
+	};
+}
+
+function isPositionInComment(model: editor.IReadOnlyModel, position: Position): boolean {
+	const lineContent = model.getLineContent(position.lineNumber);
+	const tokenizationModel = model as editor.IReadOnlyModel & TokenizationTextModel;
+	// 在光标处追加哨兵字符，避免将刚结束的块注释误判为仍在注释中
+	const tokenizedLine = tokenizationModel.tokenization?.tokenizeLinesAt?.(position.lineNumber, [
+		`${lineContent.slice(0, position.column - 1)}x`
+	])?.[0];
+	if (!tokenizedLine) {
+		return false;
+	}
+
+	const tokenIndex = tokenizedLine.findTokenIndexAtOffset(position.column - 1);
+	return tokenizedLine.getStandardTokenType(tokenIndex) === 1;
+}
+
 export class CompletionAdapter<T extends BaseSQLWorker>
 	implements languages.CompletionItemProvider
 {
@@ -165,6 +192,10 @@ export class CompletionAdapter<T extends BaseSQLWorker>
 		context: languages.CompletionContext,
 		_token: CancellationToken
 	): Promise<languages.CompletionList> {
+		if (isPositionInComment(model, position)) {
+			return Promise.resolve({ suggestions: [] });
+		}
+
 		const resource = model.uri;
 		return this._worker(resource)
 			.then((worker) => {

src/languageFeatures.ts

@@ -5,6 +5,7 @@ export * from './setupLanguageFeatures';
 export * from './common/constants';
 export * from './theme';
 export * as snippets from './snippets';
+export * from './runStatementButton';
 
 export { EntityContextType, StmtContextType } from 'dt-sql-parser';