refactor: consolidate command and diagnostic constants into a single file, update imports across the codebase

garrytrinder · garrytrinder · commit 2aa8c5a2b899 · 2026-01-19T17:06:30.000Z
diff --git a/AGENTS.md b/AGENTS.md
@@ -8,18 +8,18 @@ This file provides instructions for AI coding assistants (GitHub Copilot, Claude
 src/
 ├── commands/        # Add new commands here (one file per feature group)
 ├── services/        # Business logic, API clients
-├── constants/       # All IDs, keys, URLs (commands.ts)
 ├── data/            # Plugin metadata (plugins.json) - edit JSON, not code
-├── utils/           # Pure helper functions
+├── utils/           # Pure helper functions + getDiagnosticCode, getSchemaUrl
 ├── test/            # Tests split by domain (*.test.ts)
+├── constants.ts     # All IDs, keys, URLs
 └── *.ts             # Core extension modules
 ```
 
 ## Common Tasks
 
 ### Adding a New Command
 
-1. **Register the command ID** in `src/constants/commands.ts`:
+1. **Register the command ID** in `src/constants.ts`:
    ```typescript
    export const Commands = {
      // ... existing
@@ -38,6 +38,8 @@ src/
 
 3. **Create/update command file** in `src/commands/`:
    ```typescript
+   import { Commands } from '../constants';
+   
    export function registerMyCommands(context: vscode.ExtensionContext) {
      context.subscriptions.push(
        vscode.commands.registerCommand(Commands.MY_NEW_COMMAND, async () => {
@@ -72,7 +74,7 @@ src/
 
 ### Adding a Diagnostic
 
-1. Add diagnostic code to `DiagnosticCodes` in `src/constants/commands.ts`
+1. Add diagnostic code to `DiagnosticCodes` in `src/constants.ts`
 2. Add diagnostic creation in `src/diagnostics.ts`
 3. Add code action (quick fix) in `src/code-actions.ts`
 4. Add test in `src/test/schema.test.ts` or `src/test/plugins.test.ts`
@@ -86,8 +88,8 @@ src/
 ### Imports
 - Use barrel exports from `index.ts` files:
   ```typescript
-  import { Commands, DiagnosticCodes } from './constants';
-  import { DevProxyApiClient } from './services';
+  import { Commands, DiagnosticCodes } from '../constants';
+  import { getDiagnosticCode, getSchemaUrl } from '../utils';
   ```
 
 ### Testing
@@ -115,7 +117,7 @@ src/
 | File | Purpose |
 |------|---------|
 | `src/extension.ts` | Entry point, activation |
-| `src/constants/commands.ts` | All command IDs, context keys, URLs |
+| `src/constants.ts` | All command IDs, context keys, URLs |
 | `src/data/plugins.json` | Plugin metadata (editable without code) |
 | `src/services/api-client.ts` | All Dev Proxy HTTP API calls |
 | `src/test/helpers.ts` | Test utilities, mock factories |
diff --git a/src/commands/config.ts b/src/commands/config.ts
@@ -1,5 +1,5 @@
 import * as vscode from 'vscode';
-import { Commands } from '../constants/commands';
+import { Commands } from '../constants';
 import { executeCommand } from '../utils/shell';
 import { getDevProxyExe } from '../detect';
 import { VersionPreference } from '../enums';
diff --git a/src/commands/discovery.ts b/src/commands/discovery.ts
@@ -1,5 +1,5 @@
 import * as vscode from 'vscode';
-import { Commands } from '../constants/commands';
+import { Commands } from '../constants';
 import { TerminalService } from '../services/terminal';
 import { getDevProxyExe } from '../detect';
 import { VersionPreference } from '../enums';
diff --git a/src/commands/docs.ts b/src/commands/docs.ts
@@ -1,5 +1,5 @@
 import * as vscode from 'vscode';
-import { Commands } from '../constants/commands';
+import { Commands } from '../constants';
 import { pluginDocs } from '../data';
 import parse from 'json-to-ast';
 import { getASTNode, getRangeFromASTNode } from '../utils/ast';
diff --git a/src/commands/install.ts b/src/commands/install.ts
@@ -1,5 +1,5 @@
 import * as vscode from 'vscode';
-import { Commands, Urls } from '../constants/commands';
+import { Commands, Urls } from '../constants';
 import {
   executeCommand,
   getPackageIdentifier,
diff --git a/src/commands/jwt.ts b/src/commands/jwt.ts
@@ -1,5 +1,5 @@
 import * as vscode from 'vscode';
-import { Commands } from '../constants/commands';
+import { Commands } from '../constants';
 import { executeCommand } from '../utils/shell';
 import { getDevProxyExe } from '../detect';
 import { VersionPreference } from '../enums';
diff --git a/src/commands/proxy.ts b/src/commands/proxy.ts
@@ -1,5 +1,5 @@
 import * as vscode from 'vscode';
-import { Commands, ContextKeys } from '../constants/commands';
+import { Commands, ContextKeys } from '../constants';
 import { DevProxyApiClient } from '../services/api-client';
 import { TerminalService } from '../services/terminal';
 import { isConfigFile } from '../utils';
diff --git a/src/commands/recording.ts b/src/commands/recording.ts
@@ -1,5 +1,5 @@
 import * as vscode from 'vscode';
-import { Commands, ContextKeys } from '../constants/commands';
+import { Commands, ContextKeys } from '../constants';
 import { DevProxyApiClient } from '../services/api-client';
 
 /**
diff --git a/src/constants.ts b/src/constants.ts
@@ -88,23 +88,3 @@ export const Urls = {
   schemaBase: 'https://raw.githubusercontent.com/dotnet/dev-proxy/main/schemas',
   diagnosticsDoc: 'https://learn.microsoft.com/microsoft-cloud/dev/dev-proxy/technical-reference/toolkit-diagnostics',
 } as const;
-
-/**
- * Get a diagnostic code object with a clickable documentation link.
- * @param code The diagnostic code from DiagnosticCodes
- * @returns An object with value and target for VS Code diagnostic code
- */
-export function getDiagnosticCode(code: string): { value: string; target: import('vscode').Uri } {
-  const vscode = require('vscode');
-  return {
-    value: code,
-    target: vscode.Uri.parse(`${Urls.diagnosticsDoc}#${code.toLowerCase()}`),
-  };
-}
-
-/**
- * Build a schema URL for a specific version.
- */
-export function getSchemaUrl(version: string): string {
-  return `${Urls.schemaBase}/v${version}/rc.schema.json`;
-}
diff --git a/src/constants/index.ts b/src/constants/index.ts
diff --git a/src/diagnostics.ts b/src/diagnostics.ts
@@ -3,7 +3,8 @@ import parse from 'json-to-ast';
 import { pluginSnippets } from './data';
 import { getASTNode, getRangeFromASTNode } from './utils';
 import {DevProxyInstall, PluginConfig} from './types';
-import { DiagnosticCodes, getDiagnosticCode } from './constants';
+import { DiagnosticCodes } from './constants';
+import { getDiagnosticCode } from './utils';
 import * as semver from 'semver';
 
 export const updateConfigFileDiagnostics = (
diff --git a/src/test/code-actions.test.ts b/src/test/code-actions.test.ts
@@ -7,7 +7,8 @@ import * as sinon from 'sinon';
 import * as vscode from 'vscode';
 import { registerCodeActions } from '../code-actions';
 import { getExtensionContext, createDevProxyInstall } from './helpers';
-import { getDiagnosticCode, DiagnosticCodes } from '../constants';
+import { DiagnosticCodes } from '../constants';
+import { getDiagnosticCode } from '../utils';
 
 suite('Code Actions', () => {
   let sandbox: sinon.SinonSandbox;
@@ -87,7 +88,11 @@ suite('Code Actions', () => {
 
       // Create diagnostic
       const range = new vscode.Range(1, 14, 1, 45);
-      const diagnostic = new vscode.Diagnostic(range, 'Invalid schema', vscode.DiagnosticSeverity.Warning);
+      const diagnostic = new vscode.Diagnostic(
+        range,
+        'Invalid schema',
+        vscode.DiagnosticSeverity.Warning
+      );
       diagnostic.code = getDiagnosticCode(DiagnosticCodes.invalidSchema);
 
       // Get code actions
diff --git a/src/test/constants.test.ts b/src/test/constants.test.ts
@@ -3,7 +3,8 @@
  * Tests for utility functions in constants.
  */
 import * as assert from 'assert';
-import { getSchemaUrl, Commands, ContextKeys, DiagnosticCodes, Urls } from '../constants';
+import { Commands, ContextKeys, DiagnosticCodes, Urls } from '../constants';
+import { getSchemaUrl } from '../utils';
 
 suite('getSchemaUrl', () => {
   test('should build correct schema URL for version', () => {
diff --git a/src/test/extension.test.ts b/src/test/extension.test.ts
@@ -27,4 +27,3 @@ suite('Commands', () => {
     assert.ok(jwtCreateCommand, 'JWT create command should be registered');
   });
 });
-
diff --git a/src/test/notifications.test.ts b/src/test/notifications.test.ts
@@ -4,11 +4,7 @@
  */
 import * as assert from 'assert';
 import { handleStartNotification } from '../notifications';
-import {
-  testDevProxyInstall,
-  getExtensionContext,
-  createDevProxyInstall,
-} from './helpers';
+import { testDevProxyInstall, getExtensionContext, createDevProxyInstall } from './helpers';
 
 suite('notifications', () => {
   suiteSetup(async () => {
diff --git a/src/test/schema.test.ts b/src/test/schema.test.ts
@@ -80,14 +80,16 @@ suite('schema', () => {
       code: 'emptyUrlsToWatch',
     };
     const diagnostic = diagnostics.find(d => {
-      const code = typeof d.code === 'object' && d.code !== null
-        ? (d.code as { value: string }).value
-        : d.code;
+      const code =
+        typeof d.code === 'object' && d.code !== null
+          ? (d.code as { value: string }).value
+          : d.code;
       return code === 'emptyUrlsToWatch';
     });
-    const diagnosticCode = typeof diagnostic?.code === 'object' && diagnostic?.code !== null
-      ? (diagnostic.code as { value: string }).value
-      : diagnostic?.code;
+    const diagnosticCode =
+      typeof diagnostic?.code === 'object' && diagnostic?.code !== null
+        ? (diagnostic.code as { value: string }).value
+        : diagnostic?.code;
     const actual = {
       message: diagnostic?.message,
       severity: diagnostic?.severity,
diff --git a/src/test/shell.test.ts b/src/test/shell.test.ts
@@ -4,7 +4,12 @@
  */
 import * as assert from 'assert';
 import { getPackageIdentifier } from '../utils/shell';
-import { PackageManager, VersionPreference, HomebrewPackageIdentifier, WingetPackageIdentifier } from '../enums';
+import {
+  PackageManager,
+  VersionPreference,
+  HomebrewPackageIdentifier,
+  WingetPackageIdentifier,
+} from '../enums';
 
 suite('getPackageIdentifier', () => {
   test('should return stable Homebrew package for stable preference', () => {
@@ -28,7 +33,10 @@ suite('getPackageIdentifier', () => {
   });
 
   test('should return undefined for unknown package manager', () => {
-    const result = getPackageIdentifier(VersionPreference.Stable, 'unknown' as unknown as PackageManager);
+    const result = getPackageIdentifier(
+      VersionPreference.Stable,
+      'unknown' as unknown as PackageManager
+    );
     assert.strictEqual(result, undefined);
   });
 });
diff --git a/src/test/status-bar.test.ts b/src/test/status-bar.test.ts
@@ -8,11 +8,7 @@ import * as sinon from 'sinon';
 import * as detect from '../detect';
 import { VersionPreference } from '../enums';
 import { handleStatusBarUpdate, statusBarLoop } from '../status-bar';
-import {
-  testDevProxyInstall,
-  getExtensionContext,
-  createDevProxyInstall,
-} from './helpers';
+import { testDevProxyInstall, getExtensionContext, createDevProxyInstall } from './helpers';
 
 suite('statusbar', () => {
   suiteSetup(async () => {
diff --git a/src/test/task-provider.test.ts b/src/test/task-provider.test.ts
@@ -177,15 +177,23 @@ suite('DevProxyTaskProvider', () => {
       const tasks = await provider.provideTasks();
 
       const startTask = tasks!.find(t => t.name.includes('Start'));
-      assert.strictEqual(startTask?.group, vscode.TaskGroup.Build, 'Start task should be in build group');
+      assert.strictEqual(
+        startTask?.group,
+        vscode.TaskGroup.Build,
+        'Start task should be in build group'
+      );
     });
 
     test('stop task should be in build group', async () => {
       const provider = new DevProxyTaskProvider(mockContext);
       const tasks = await provider.provideTasks();
 
       const stopTask = tasks!.find(t => t.name.includes('Stop'));
-      assert.strictEqual(stopTask?.group, vscode.TaskGroup.Build, 'Stop task should be in build group');
+      assert.strictEqual(
+        stopTask?.group,
+        vscode.TaskGroup.Build,
+        'Stop task should be in build group'
+      );
     });
   });
 });
diff --git a/src/utils/ast.ts b/src/utils/ast.ts
@@ -1,10 +1,30 @@
 import * as vscode from 'vscode';
 import parse from 'json-to-ast';
+import { Urls } from '../constants';
 
 /**
  * Utilities for working with json-to-ast nodes.
  */
 
+/**
+ * Get a diagnostic code object with a clickable documentation link.
+ * @param code The diagnostic code from DiagnosticCodes
+ * @returns An object with value and target for VS Code diagnostic code
+ */
+export function getDiagnosticCode(code: string): { value: string; target: vscode.Uri } {
+  return {
+    value: code,
+    target: vscode.Uri.parse(`${Urls.diagnosticsDoc}#${code.toLowerCase()}`),
+  };
+}
+
+/**
+ * Build a schema URL for a specific version.
+ */
+export function getSchemaUrl(version: string): string {
+  return `${Urls.schemaBase}/v${version}/rc.schema.json`;
+}
+
 /**
  * Find a property node by its key type and value.
  */
@@ -23,7 +43,12 @@ export function getASTNode(
  * and properly excludes quotes from string literal ranges.
  */
 export function getRangeFromASTNode(
-  node: parse.PropertyNode | parse.LiteralNode | parse.ObjectNode | parse.ValueNode | parse.IdentifierNode
+  node:
+    | parse.PropertyNode
+    | parse.LiteralNode
+    | parse.ObjectNode
+    | parse.ValueNode
+    | parse.IdentifierNode
 ): vscode.Range {
   const startLine = node?.loc?.start.line ?? 0;
   const endLine = node?.loc?.end.line ?? 0;
@@ -55,7 +80,12 @@ export function getRangeFromASTNode(
  * Get the start position of an AST node.
  */
 export function getStartPositionFromASTNode(
-  node: parse.PropertyNode | parse.LiteralNode | parse.ObjectNode | parse.ValueNode | parse.IdentifierNode
+  node:
+    | parse.PropertyNode
+    | parse.LiteralNode
+    | parse.ObjectNode
+    | parse.ValueNode
+    | parse.IdentifierNode
 ): vscode.Position {
   const startLine = node?.loc?.start.line ?? 0;
   const startColumn = node?.loc?.start.column ?? 0;
diff --git a/src/utils/index.ts b/src/utils/index.ts
@@ -7,7 +7,13 @@
  */
 
 // AST utilities
-export { getASTNode, getRangeFromASTNode, getStartPositionFromASTNode } from './ast';
+export {
+  getASTNode,
+  getRangeFromASTNode,
+  getStartPositionFromASTNode,
+  getDiagnosticCode,
+  getSchemaUrl,
+} from './ast';
 
 // Config file detection
 export { isConfigFile, isProxyFile } from './config-detection';
diff --git a/src/utils/shell.ts b/src/utils/shell.ts
@@ -1,6 +1,6 @@
 import { exec, ExecOptions } from 'child_process';
 import * as vscode from 'vscode';
-import { Urls } from '../constants/commands';
+import { Urls } from '../constants';
 import {
   HomebrewPackageIdentifier,
   PackageManager,
