feat: add scope completion in VSCode extension (#35)

* feat: add scope completion in VSCode extension

* build: replace xvfb-run command with setup-xvfb action for headless testing

Author: jpoehnelt

.changeset/eleven-laws-care.md

@@ -0,0 +1,5 @@
+---
+"google-workspace-developer-tools": minor
+---
+
+Implement code completion for OAuth2 scopes.

.github/actions/setup-xvfb/action.yml

@@ -0,0 +1,29 @@
+# Copyright 2025 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+name: "Setup Xvfb"
+description: "Install and start Xvfb virtual display server for headless testing"
+runs:
+  using: "composite"
+  steps:
+    - name: Install Xvfb
+      shell: bash
+      run: |
+        sudo apt-get update
+        sudo apt-get install -y xvfb
+    - name: Start Xvfb
+      shell: bash
+      run: |
+        Xvfb :99 -screen 0 1024x768x24 > /dev/null 2>&1 &
+        echo "DISPLAY=:99.0" >> $GITHUB_ENV

.github/workflows/release.yml

@@ -37,6 +37,7 @@ jobs:
       - run: pnpm build
       - run: pnpm lint
       - run: pnpm check
+      - uses: ./.github/actions/setup-xvfb
       - run: pnpm test
       - run: pnpm ci:package
       - run: |

.github/workflows/test.yml

@@ -31,5 +31,6 @@ jobs:
       - run: pnpm build
       - run: pnpm lint
       - run: pnpm check
+      - uses: ./.github/actions/setup-xvfb
       - run: pnpm test
       - run: pnpm ci:package

.github/workflows/update.yml

@@ -31,6 +31,7 @@ jobs:
       - run: pnpm ci:update
       - run: pnpm lint
       - run: pnpm check
+      - uses: ./.github/actions/setup-xvfb
       - run: pnpm test
       - name: Check for changes
         id: changes

packages/vscode-extension/.vscode-test.mjs

@@ -18,4 +18,6 @@ import { defineConfig } from "@vscode/test-cli";
 
 export default defineConfig({
 	files: "out/test/**/*.test.cjs",
+	launchArgs: ["--user-data-dir=/tmp/vscode-test-user-data"],
+	version: "insiders",
 });

packages/vscode-extension/README.md

@@ -17,7 +17,9 @@ Automatically validate and document Google Workspace OAuth2 scopes in your code:
 - **Hover Documentation**: See scope descriptions, associated APIs, and documentation links on hover
 - **Multi-API Support**: Coverage for all Google Workspace APIs (Gmail, Drive, Calendar, Chat, Admin, and more)
 
-![OAuth2 Scope Linting](https://raw.githubusercontent.com/googleworkspace/vscode-extension/main/packages/vscode-extension/assets/scope-diagnostics.png)
+Get code completions for all Google OAuth2 scopes:
+
+![OAuth2 Scope Linting & Completions](https://raw.githubusercontent.com/googleworkspace/vscode-extension/main/packages/vscode-extension/assets/scope-completion.gif)
 
 **Scope Classifications:**
 

packages/vscode-extension/assets/scope-completion.gif

@@ -2,7 +2,7 @@
   "name": "google-workspace-developer-tools",
   "displayName": "Google Workspace Developer Tools",
   "description": "Lint Google Workspace OAuth2 scopes and more.",
-  "version": "0.5.4",
+  "version": "0.5.6",
   "publisher": "google-workspace",
   "license": "Apache-2.0",
   "private": true,
@@ -54,13 +54,13 @@
   "scripts": {
     "build": "tsup",
     "check": "tsc --noEmit",
-    "ci:package": "vsce package",
+    "ci:package": "vsce package --no-dependencies",
     "ci:publish": "ovsx publish --skip-duplicate && vsce publish --skip-duplicate",
     "ci:version": "changeset version && pnpm i --lockfile-only --engine-strict=false",
     "ci:update": "tsx scripts/fetch-apis.ts",
     "dev": "tsup --watch",
     "pretest": "pnpm build",
-    "test": "xvfb-run -a vscode-test",
+    "test": "vscode-test",
     "vscode:prepublish": "tsup"
   },
   "devDependencies": {
@@ -76,5 +76,8 @@
     "tsup": "catalog:",
     "tsx": "catalog:",
     "typescript": "catalog:"
+  },
+  "dependencies": {
+    "vitest": "^4.0.4"
   }
 }

packages/vscode-extension/package.json

@@ -17,6 +17,35 @@
 import * as vscode from "vscode";
 import { SCOPES, ScopeClassification, getScopeMarkdown } from "./scopes.js";
 
+export function scopeCompletion(
+	document: vscode.TextDocument,
+	position: vscode.Position,
+): vscode.CompletionItem[] {
+	const completionItems: vscode.CompletionItem[] = [];
+
+	const lineText = document.lineAt(position.line).text;
+	const textBeforeCursor = lineText.substring(0, position.character);
+
+	const match = textBeforeCursor.match(
+		/(https:\/\/www\.googleapis\.com\/auth\/[a-zA-Z._-]*)$/,
+	);
+
+	if (!match) {
+		return completionItems;
+	}
+
+	for (const [scope] of SCOPES.entries()) {
+		if (scope.startsWith(match[1])) {
+			const item = new vscode.CompletionItem(scope.split("/").pop() ?? scope);
+			item.insertText = scope.replace(match[1], "");
+			completionItems.push(item);
+		}
+	}
+	return completionItems.sort((a, b) =>
+		String(a.label).localeCompare(String(b.label)),
+	);
+}
+
 export function activate(context: vscode.ExtensionContext) {
 	if (vscode.lm.registerMcpServerDefinitionProvider) {
 		context.subscriptions.push(
@@ -77,6 +106,20 @@ export function activate(context: vscode.ExtensionContext) {
 		vscode.languages.createDiagnosticCollection("scopes");
 	context.subscriptions.push(scopeDiagnostics);
 
+	const scopeCompletionProvider =
+		vscode.languages.registerCompletionItemProvider(
+			{ scheme: "file" },
+			{
+				provideCompletionItems(document, position) {
+					console.log(position);
+					return scopeCompletion(document, position);
+				},
+			},
+			"/",
+			".",
+		);
+	context.subscriptions.push(scopeCompletionProvider);
+
 	function updateDiagnostics(
 		document: vscode.TextDocument,
 		collection: vscode.DiagnosticCollection,