@blokjs/lsp-server 0.2.0

package/src/__tests__/hover.test.ts

@@ -0,0 +1,227 @@
+import { describe, expect, it } from "vitest";
+import { getHover } from "../hover";
+
+describe("WorkflowHoverProvider (LSP)", () => {
+	describe("trigger type hover", () => {
+		it("should show hover for http trigger key", () => {
+			const text = '{\n  "trigger": {\n    "http": {\n      "method": "GET"\n    }\n  }\n}';
+			// Line 2: '    "http": {'  - cursor on "http"
+			const hover = getHover(text, 2, 6);
+			expect(hover).not.toBeNull();
+			expect(hover!.contents).toHaveProperty("value");
+			const value = (hover!.contents as { value: string }).value;
+			expect(value).toContain("HTTP Trigger");
+		});
+
+		it("should show hover for cron trigger key", () => {
+			const text = '{\n  "trigger": {\n    "cron": {\n      "schedule": "* * * * *"\n    }\n  }\n}';
+			const hover = getHover(text, 2, 6);
+			expect(hover).not.toBeNull();
+			const value = (hover!.contents as { value: string }).value;
+			expect(value).toContain("Cron Trigger");
+		});
+
+		it("should show hover for queue trigger key", () => {
+			const text = '{\n  "trigger": {\n    "queue": {\n      "provider": "kafka"\n    }\n  }\n}';
+			const hover = getHover(text, 2, 6);
+			expect(hover).not.toBeNull();
+			const value = (hover!.contents as { value: string }).value;
+			expect(value).toContain("Queue Trigger");
+		});
+
+		it("should show hover for webhook trigger key", () => {
+			const text = '{\n  "trigger": {\n    "webhook": {\n      "source": "github"\n    }\n  }\n}';
+			const hover = getHover(text, 2, 6);
+			expect(hover).not.toBeNull();
+			const value = (hover!.contents as { value: string }).value;
+			expect(value).toContain("Webhook Trigger");
+		});
+
+		it("should show hover for websocket trigger key", () => {
+			const text = '{\n  "trigger": {\n    "websocket": {\n      "path": "/ws"\n    }\n  }\n}';
+			const hover = getHover(text, 2, 6);
+			expect(hover).not.toBeNull();
+			const value = (hover!.contents as { value: string }).value;
+			expect(value).toContain("WebSocket Trigger");
+		});
+
+		it("should show hover for sse trigger key", () => {
+			const text = '{\n  "trigger": {\n    "sse": {\n      "path": "/events"\n    }\n  }\n}';
+			const hover = getHover(text, 2, 6);
+			expect(hover).not.toBeNull();
+			const value = (hover!.contents as { value: string }).value;
+			expect(value).toContain("SSE Trigger");
+		});
+	});
+
+	describe("workflow field hover", () => {
+		it("should show hover for name field", () => {
+			const text = '{\n  "name": "my-workflow"\n}';
+			const hover = getHover(text, 1, 4);
+			expect(hover).not.toBeNull();
+			const value = (hover!.contents as { value: string }).value;
+			expect(value).toContain("Workflow Name");
+		});
+
+		it("should show hover for version field", () => {
+			const text = '{\n  "version": "1.0.0"\n}';
+			const hover = getHover(text, 1, 5);
+			expect(hover).not.toBeNull();
+			const value = (hover!.contents as { value: string }).value;
+			expect(value).toContain("Workflow Version");
+		});
+
+		it("should show hover for steps field", () => {
+			const text = '{\n  "steps": []\n}';
+			const hover = getHover(text, 1, 5);
+			expect(hover).not.toBeNull();
+			const value = (hover!.contents as { value: string }).value;
+			expect(value).toContain("Workflow Steps");
+		});
+
+		it("should show hover for nodes field", () => {
+			const text = '{\n  "nodes": {}\n}';
+			const hover = getHover(text, 1, 5);
+			expect(hover).not.toBeNull();
+			const value = (hover!.contents as { value: string }).value;
+			expect(value).toContain("Node Configurations");
+		});
+
+		it("should show hover for inputs field", () => {
+			const text = '{\n  "nodes": {\n    "step1": {\n      "inputs": {}\n    }\n  }\n}';
+			const hover = getHover(text, 3, 8);
+			expect(hover).not.toBeNull();
+			const value = (hover!.contents as { value: string }).value;
+			expect(value).toContain("Node Inputs");
+		});
+
+		it("should show hover for conditions field", () => {
+			const text = '{\n  "nodes": {\n    "router": {\n      "conditions": []\n    }\n  }\n}';
+			const hover = getHover(text, 3, 10);
+			expect(hover).not.toBeNull();
+			const value = (hover!.contents as { value: string }).value;
+			expect(value).toContain("Conditional Branches");
+		});
+	});
+
+	describe("step field hover", () => {
+		it("should show hover for node field in step", () => {
+			const text = '{\n  "steps": [\n    {\n      "node": "@blokjs/api-call"\n    }\n  ]\n}';
+			const hover = getHover(text, 3, 8);
+			expect(hover).not.toBeNull();
+			const value = (hover!.contents as { value: string }).value;
+			expect(value).toContain("Step Node Reference");
+		});
+
+		it("should show hover for type field in step", () => {
+			const text = '{\n  "steps": [\n    {\n      "type": "module"\n    }\n  ]\n}';
+			const hover = getHover(text, 3, 8);
+			expect(hover).not.toBeNull();
+			const value = (hover!.contents as { value: string }).value;
+			expect(value).toContain("Step Type");
+		});
+
+		it("should show hover for runtime field in step", () => {
+			const text = '{\n  "steps": [\n    {\n      "runtime": "python3"\n    }\n  ]\n}';
+			const hover = getHover(text, 3, 9);
+			expect(hover).not.toBeNull();
+			const value = (hover!.contents as { value: string }).value;
+			expect(value).toContain("Step Runtime");
+		});
+	});
+
+	describe("value hover", () => {
+		it("should show hover for HTTP method value", () => {
+			const text = '{\n  "trigger": {\n    "http": {\n      "method": "POST"\n    }\n  }\n}';
+			// "POST" is at position after "method": "
+			const hover = getHover(text, 3, 20);
+			expect(hover).not.toBeNull();
+			const value = (hover!.contents as { value: string }).value;
+			expect(value).toContain("HTTP Method: POST");
+		});
+
+		it("should show hover for runtime type value", () => {
+			const text = '{\n  "steps": [\n    {\n      "type": "runtime.go"\n    }\n  ]\n}';
+			const hover = getHover(text, 3, 18);
+			expect(hover).not.toBeNull();
+			const value = (hover!.contents as { value: string }).value;
+			expect(value).toContain("Runtime Type: go");
+		});
+
+		it("should show hover for @blokjs/api-call value", () => {
+			const text = '{\n  "steps": [\n    {\n      "node": "@blokjs/api-call"\n    }\n  ]\n}';
+			const hover = getHover(text, 3, 18);
+			expect(hover).not.toBeNull();
+			const value = (hover!.contents as { value: string }).value;
+			expect(value).toContain("api-call");
+			expect(value).toContain("HTTP API calls");
+		});
+
+		it("should show hover for @blokjs/if-else value", () => {
+			const text = '{\n  "steps": [\n    {\n      "node": "@blokjs/if-else"\n    }\n  ]\n}';
+			const hover = getHover(text, 3, 18);
+			expect(hover).not.toBeNull();
+			const value = (hover!.contents as { value: string }).value;
+			expect(value).toContain("if-else");
+			expect(value).toContain("Conditional");
+		});
+	});
+
+	describe("no hover", () => {
+		it("should return null for unknown keys", () => {
+			const text = '{\n  "unknown_key": "value"\n}';
+			const hover = getHover(text, 1, 5);
+			expect(hover).toBeNull();
+		});
+
+		it("should return null for plain string values", () => {
+			const text = '{\n  "name": "my-workflow"\n}';
+			// Hover on the value "my-workflow"
+			const hover = getHover(text, 1, 14);
+			expect(hover).toBeNull();
+		});
+
+		it("should return null when cursor is not on a quoted string", () => {
+			const text = '{\n  "steps": []\n}';
+			// Hover on []
+			const hover = getHover(text, 1, 12);
+			expect(hover).toBeNull();
+		});
+
+		it("should return null for empty line", () => {
+			const text = "{\n\n}";
+			const hover = getHover(text, 1, 0);
+			expect(hover).toBeNull();
+		});
+	});
+
+	describe("hover includes examples", () => {
+		it("should include code example for trigger types with examples", () => {
+			const text = '{\n  "trigger": {\n    "http": {}\n  }\n}';
+			const hover = getHover(text, 2, 6);
+			expect(hover).not.toBeNull();
+			const value = (hover!.contents as { value: string }).value;
+			expect(value).toContain("```json");
+			expect(value).toContain("method");
+		});
+
+		it("should include code example for inputs field", () => {
+			const text = '{\n  "inputs": {}\n}';
+			const hover = getHover(text, 1, 5);
+			expect(hover).not.toBeNull();
+			const value = (hover!.contents as { value: string }).value;
+			expect(value).toContain("```json");
+		});
+	});
+
+	describe("hover range", () => {
+		it("should return correct range for hovered word", () => {
+			const text = '{\n  "name": "my-workflow"\n}';
+			const hover = getHover(text, 1, 4);
+			expect(hover).not.toBeNull();
+			expect(hover!.range).toBeDefined();
+			expect(hover!.range!.start.line).toBe(1);
+			expect(hover!.range!.end.line).toBe(1);
+		});
+	});
+});

package/src/completion.ts

@@ -0,0 +1,308 @@
+import { type CompletionItem, CompletionItemKind, InsertTextFormat, MarkupKind } from "vscode-languageserver";
+import {
+	NODE_PACKAGES,
+	PUBSUB_PROVIDERS,
+	QUEUE_PROVIDERS,
+	VALID_HTTP_METHODS,
+	VALID_RUNTIMES,
+	VALID_STEP_TYPES,
+	VALID_TRIGGERS,
+	WEBHOOK_SOURCES,
+} from "./constants";
+
+/**
+ * Provides contextual auto-completion for Blok workflow JSON files via LSP.
+ *
+ * Offers completions for:
+ * - Trigger types, HTTP methods, step types, runtime kinds
+ * - Queue/pubsub providers, webhook sources
+ * - Node packages, condition types
+ * - Top-level and context-specific keys
+ */
+export function getCompletions(text: string, offset: number): CompletionItem[] {
+	const lines = text.split("\n");
+	const pos = offsetToLineChar(text, offset);
+	const lineText = lines[pos.line] || "";
+	const textBefore = lineText.substring(0, pos.character);
+
+	// Detect which key we're providing a value for
+	const keyMatch = textBefore.match(/"(\w+)"\s*:\s*"?$/);
+	const parentKey = keyMatch?.[1];
+
+	// Detect enclosing context
+	const context = detectContext(text, offset);
+
+	const items: CompletionItem[] = [];
+
+	// Trigger type completions
+	if (context === "trigger" || parentKey === "trigger") {
+		items.push(...createTriggerTypeCompletions());
+	}
+
+	// HTTP method completions
+	if (parentKey === "method" && (context === "trigger" || context === "http")) {
+		items.push(...createHttpMethodCompletions());
+	}
+
+	// Step type completions
+	if (parentKey === "type" && context === "steps") {
+		items.push(...createStepTypeCompletions());
+	}
+
+	// Runtime completions
+	if (parentKey === "runtime") {
+		items.push(...createRuntimeCompletions());
+	}
+
+	// Node package completions
+	if (parentKey === "node") {
+		items.push(...createNodeCompletions());
+	}
+
+	// Queue provider completions
+	if (parentKey === "provider" && context === "queue") {
+		items.push(...createQueueProviderCompletions());
+	}
+
+	// Pubsub provider completions
+	if (parentKey === "provider" && context === "pubsub") {
+		items.push(...createPubsubProviderCompletions());
+	}
+
+	// Webhook source completions
+	if (parentKey === "source" && context === "webhook") {
+		items.push(...createWebhookSourceCompletions());
+	}
+
+	// Condition type completions
+	if (parentKey === "type" && context === "conditions") {
+		items.push(...createConditionTypeCompletions());
+	}
+
+	// Top-level key completions
+	if (textBefore.match(/^\s*"$/)) {
+		items.push(...createTopLevelKeyCompletions(context));
+	}
+
+	return items;
+}
+
+function detectContext(text: string, offset: number): string {
+	let depth = 0;
+	for (let i = offset - 1; i >= 0; i--) {
+		if (text[i] === "}" || text[i] === "]") depth++;
+		if (text[i] === "{" || text[i] === "[") {
+			if (depth === 0) {
+				const before = text.substring(Math.max(0, i - 100), i);
+				const keyMatch = before.match(/"(\w+)"\s*:\s*$/);
+				if (keyMatch) return keyMatch[1];
+				const arrayMatch = before.match(/"(\w+)"\s*:\s*\[[\s\S]*$/);
+				if (arrayMatch) return arrayMatch[1];
+			}
+			depth--;
+		}
+	}
+	return "root";
+}
+
+function offsetToLineChar(text: string, offset: number): { line: number; character: number } {
+	let line = 0;
+	let character = 0;
+	for (let i = 0; i < offset && i < text.length; i++) {
+		if (text[i] === "\n") {
+			line++;
+			character = 0;
+		} else {
+			character++;
+		}
+	}
+	return { line, character };
+}
+
+function createTriggerTypeCompletions(): CompletionItem[] {
+	const triggers: Array<{ label: string; detail: string; docs: string }> = [
+		{ label: "http", detail: "HTTP trigger", docs: "Trigger on HTTP requests (GET, POST, PUT, DELETE)" },
+		{ label: "grpc", detail: "gRPC trigger", docs: "Trigger on gRPC method calls" },
+		{ label: "manual", detail: "Manual trigger", docs: "No auto-trigger, invoke programmatically" },
+		{ label: "cron", detail: "Cron trigger", docs: "Scheduled execution with cron expressions" },
+		{ label: "queue", detail: "Queue trigger", docs: "Message queue consumer (Kafka, RabbitMQ, SQS)" },
+		{ label: "pubsub", detail: "Pub/Sub trigger", docs: "Pub/Sub subscriber (GCP, AWS, Azure, Redis, NATS)" },
+		{ label: "worker", detail: "Worker trigger", docs: "Background job processing with retries" },
+		{ label: "webhook", detail: "Webhook trigger", docs: "External webhook events (GitHub, Stripe, Shopify)" },
+		{ label: "websocket", detail: "WebSocket trigger", docs: "Real-time bidirectional communication" },
+		{ label: "sse", detail: "SSE trigger", docs: "Server-Sent Events streaming" },
+	];
+
+	return triggers.map((t) => ({
+		label: t.label,
+		kind: CompletionItemKind.Enum,
+		detail: t.detail,
+		documentation: { kind: MarkupKind.Markdown, value: t.docs },
+	}));
+}
+
+function createHttpMethodCompletions(): CompletionItem[] {
+	const methods = [
+		{ label: "GET", docs: "Retrieve resources" },
+		{ label: "POST", docs: "Create resources" },
+		{ label: "PUT", docs: "Replace resources" },
+		{ label: "DELETE", docs: "Delete resources" },
+		{ label: "PATCH", docs: "Partially update resources" },
+		{ label: "ANY", docs: "Match any HTTP method" },
+	];
+
+	return methods.map((m) => ({
+		label: m.label,
+		kind: CompletionItemKind.EnumMember,
+		documentation: m.docs,
+	}));
+}
+
+function createStepTypeCompletions(): CompletionItem[] {
+	const types = [
+		{ label: "module", docs: "Node from npm package (e.g., @blokjs/api-call)", priority: "1" },
+		{ label: "local", docs: "Node defined locally in the project (e.g., ./nodes/my-node)", priority: "2" },
+		{ label: "runtime.nodejs", docs: "Execute using Node.js runtime adapter", priority: "3" },
+		{ label: "runtime.python3", docs: "Execute using Python 3 runtime adapter (via gRPC)", priority: "4" },
+		{ label: "runtime.go", docs: "Execute using Go runtime adapter (Docker container)", priority: "5" },
+		{ label: "runtime.java", docs: "Execute using Java runtime adapter (Docker container)", priority: "6" },
+		{ label: "runtime.rust", docs: "Execute using Rust runtime adapter (Docker/WASM)", priority: "7" },
+		{ label: "runtime.php", docs: "Execute using PHP runtime adapter (Docker container)", priority: "8" },
+		{ label: "runtime.csharp", docs: "Execute using C#/.NET runtime adapter", priority: "9" },
+		{ label: "runtime.ruby", docs: "Execute using Ruby runtime adapter", priority: "a" },
+	];
+
+	return types.map((t) => ({
+		label: t.label,
+		kind: CompletionItemKind.EnumMember,
+		documentation: t.docs,
+		sortText: t.priority,
+	}));
+}
+
+function createRuntimeCompletions(): CompletionItem[] {
+	const runtimes = [
+		{ label: "nodejs", docs: "Node.js in-process execution (fastest)" },
+		{ label: "bun", docs: "Bun runtime execution" },
+		{ label: "python3", docs: "Python 3 via gRPC protocol" },
+		{ label: "go", docs: "Go via Docker container" },
+		{ label: "java", docs: "Java via Docker container" },
+		{ label: "rust", docs: "Rust via Docker container or WASM" },
+		{ label: "php", docs: "PHP via Docker container" },
+		{ label: "csharp", docs: "C#/.NET via Docker container" },
+		{ label: "ruby", docs: "Ruby via Docker container" },
+		{ label: "docker", docs: "Generic Docker container runtime" },
+		{ label: "wasm", docs: "WebAssembly runtime" },
+	];
+
+	return runtimes.map((r) => ({
+		label: r.label,
+		kind: CompletionItemKind.EnumMember,
+		documentation: r.docs,
+	}));
+}
+
+function createNodeCompletions(): CompletionItem[] {
+	return NODE_PACKAGES.map((n) => ({
+		label: n.name,
+		kind: CompletionItemKind.Module,
+		documentation: n.description,
+	}));
+}
+
+function createQueueProviderCompletions(): CompletionItem[] {
+	const providers = [
+		{ label: "kafka", docs: "Apache Kafka distributed event streaming" },
+		{ label: "rabbitmq", docs: "RabbitMQ message broker (AMQP)" },
+		{ label: "sqs", docs: "AWS Simple Queue Service" },
+		{ label: "redis", docs: "Redis-based queue (BullMQ)" },
+		{ label: "beanstalk", docs: "Beanstalk work queue" },
+	];
+
+	return providers.map((p) => ({
+		label: p.label,
+		kind: CompletionItemKind.EnumMember,
+		documentation: p.docs,
+	}));
+}
+
+function createPubsubProviderCompletions(): CompletionItem[] {
+	const providers = [
+		{ label: "gcp", docs: "Google Cloud Pub/Sub" },
+		{ label: "aws", docs: "AWS SNS (Simple Notification Service)" },
+		{ label: "azure", docs: "Azure Service Bus" },
+		{ label: "redis", docs: "Redis Pub/Sub" },
+		{ label: "nats", docs: "NATS messaging system" },
+	];
+
+	return providers.map((p) => ({
+		label: p.label,
+		kind: CompletionItemKind.EnumMember,
+		documentation: p.docs,
+	}));
+}
+
+function createWebhookSourceCompletions(): CompletionItem[] {
+	const sources = [
+		{ label: "github", docs: "GitHub webhook events (push, PR, issues, etc.)" },
+		{ label: "stripe", docs: "Stripe payment events (checkout, invoice, etc.)" },
+		{ label: "shopify", docs: "Shopify e-commerce events (order, product, etc.)" },
+		{ label: "custom", docs: "Custom webhook source with HMAC verification" },
+	];
+
+	return sources.map((s) => ({
+		label: s.label,
+		kind: CompletionItemKind.EnumMember,
+		documentation: s.docs,
+	}));
+}
+
+function createConditionTypeCompletions(): CompletionItem[] {
+	return [
+		{
+			label: "if",
+			kind: CompletionItemKind.Keyword,
+			documentation: "Conditional branch - executes steps when condition is true",
+		},
+		{
+			label: "else",
+			kind: CompletionItemKind.Keyword,
+			documentation: "Default branch - executes when no 'if' condition matches",
+		},
+	];
+}
+
+function createTopLevelKeyCompletions(context: string): CompletionItem[] {
+	if (context === "root") {
+		const keys = [
+			{ label: "name", docs: "Workflow name" },
+			{ label: "description", docs: "Workflow description" },
+			{ label: "version", docs: "Semantic version (e.g., 1.0.0)" },
+			{ label: "trigger", docs: "Workflow trigger configuration" },
+			{ label: "steps", docs: "Ordered list of execution steps" },
+			{ label: "nodes", docs: "Node configuration map" },
+		];
+
+		return keys.map((k) => ({
+			label: k.label,
+			kind: CompletionItemKind.Property,
+			documentation: k.docs,
+		}));
+	}
+
+	if (context === "http") {
+		return ["method", "path", "accept", "jwt_secret"].map((k) => ({
+			label: k,
+			kind: CompletionItemKind.Property,
+		}));
+	}
+
+	if (context === "steps") {
+		return ["name", "node", "type", "runtime"].map((k) => ({
+			label: k,
+			kind: CompletionItemKind.Property,
+		}));
+	}
+
+	return [];
+}