feat: centralize scattered literals into comprehensive constants structure (#30) (#53)

• Expanded src/utils/constants.ts with 15 organized constant categories:
  - COMMANDS: All stepzen.* command identifiers
  - CONFIG_KEYS: VSCode configuration keys
  - UI: Component names, view types, panel titles
  - FILE_PATTERNS: Schema files, config files, operations directory
  - TEMP_FILE_PATTERNS: Temporary file prefixes and extensions
  - TIMEOUTS: File cleanup delays and timeouts
  - GRAPHQL: Root operation types, scalar types, patterns
  - ERROR_CODES: Standardized error code constants
  - LOG_LEVELS: Logger level constants
  - URLs: External links (CLI installation, etc.)
  - MENU_GROUPS: VSCode menu group identifiers
  - LANGUAGE_IDS: Language identifier constants
  - WHEN_CONDITIONS: VSCode when clause conditions
  - PROGRESS_MESSAGES: User-facing progress messages
  - MESSAGES: All user-facing messages and error strings

• Updated 16 files to use centralized constants:
  - extension.ts: Command IDs, config keys, messages, language IDs
  - codelensProvider.ts: Command identifiers
  - resultsPanel.ts: View type and title constants
  - logger.ts: Configuration keys, output channel names
  - cli.ts: Temporary file patterns, timeouts
  - initializeProject.ts: URLs, file patterns, messages
  - deploy.ts: Progress and user messages
  - runRequest.ts: GraphQL patterns, scalar types, messages
  - generateOperations.ts: File patterns, messages
  - safeRegisterCommand.ts: Error messages
  - projectResolver.ts: File patterns, user messages
  - schemaVisualizerPanel.ts: View types, titles, file patterns
  - executeStepZenRequest.ts: Temp file patterns, config files
  - openExplorer.ts: View types, titles, file patterns
  - stepzenProjectScanner.ts: GraphQL type imports

• Added TypeScript type definitions for better type safety:
  - CommandId, ConfigKey, ErrorCode, LogLevel
  - GraphQLOperationType, GraphQLScalarType

• Fixed 4 TypeScript compilation errors:
  - Removed unused imports in schemaVisualizerPanel.ts
  - Fixed type mismatches in stepzenProjectScanner.ts

• Added required copyright headers to all modified files

• Benefits achieved:
  - Single source of truth for all constants
  - Improved maintainability and consistency
  - Enhanced type safety with TypeScript types
  - Better discoverability and reusability
  - Safer refactoring with centralized changes

✅ All tests pass (101/101)
✅ TypeScript compilation successful
✅ ESLint validation passed

Author: carloseberhardt

src/commands/deploy.ts

@@ -1,6 +1,12 @@
+/**
+ * Copyright IBM Corp. 2025
+ * Assisted by CursorAI
+ */
+
 import * as vscode from "vscode";
 import { services } from "../services";
 import { handleError } from "../errors";
+import { MESSAGES, PROGRESS_MESSAGES } from "../utils/constants";
 
 /**
  * Deploys the current StepZen project to StepZen service
@@ -11,9 +17,8 @@ import { handleError } from "../errors";
 export async function deployStepZen() {
   // Check workspace trust first
   if (!vscode.workspace.isTrusted) {
-    const message = "StepZen deployment is not available in untrusted workspaces. Open this folder in a trusted workspace to enable deployment.";
-    vscode.window.showWarningMessage(message);
-    services.logger.warn(`Deploy failed: ${message}`);
+    vscode.window.showWarningMessage(MESSAGES.FEATURE_NOT_AVAILABLE_UNTRUSTED);
+    services.logger.warn(`Deploy failed: ${MESSAGES.FEATURE_NOT_AVAILABLE_UNTRUSTED}`);
     return;
   }
 
@@ -29,7 +34,7 @@ export async function deployStepZen() {
 
     try {
       // Use the CLI service to perform the deployment
-      progress.report({ increment: 50, message: "Uploading schema to StepZen..." });
+      progress.report({ increment: 50, message: PROGRESS_MESSAGES.UPLOADING_SCHEMA });
       await services.cli.deploy();
 
       // Show success message to the user

src/commands/executeStepZenRequest.ts

@@ -7,7 +7,7 @@ import { resolveStepZenProjectRoot } from "../utils/stepzenProject";
 import { clearResultsPanel, openResultsPanel } from "../panels/resultsPanel";
 import { summariseDiagnostics, publishDiagnostics } from "../utils/runtimeDiagnostics";
 import { runtimeDiag } from "../extension";
-import { UI, TIMEOUTS } from "../utils/constants";
+import { UI, TIMEOUTS, TEMP_FILE_PATTERNS, FILE_PATTERNS } from "../utils/constants";
 import { services } from "../services";
 import { StepZenResponse, StepZenDiagnostic } from "../types";
 import { ValidationError, NetworkError, handleError } from "../errors";
@@ -36,7 +36,7 @@ function createTempGraphQLFile(content: string): string {
   const tempDir = os.tmpdir();
   const timestamp = new Date().getTime();
   const randomPart = Math.random().toString(36).substring(2, 10);
-  const filename = `stepzen-query-${timestamp}-${randomPart}.graphql`;
+  const filename = `${TEMP_FILE_PATTERNS.QUERY_PREFIX}${timestamp}-${randomPart}${TEMP_FILE_PATTERNS.GRAPHQL_EXTENSION}`;
   const filePath = path.join(tempDir, filename);
 
   try {
@@ -139,7 +139,7 @@ export async function executeStepZenRequest(options: {
   if (documentId) {
     try {
       // Get StepZen config to build the endpoint URL
-      const configPath = path.join(projectRoot, "stepzen.config.json");
+      const configPath = path.join(projectRoot, FILE_PATTERNS.CONFIG_FILE);
       services.logger.debug(`Looking for config file at: ${configPath}`);
 
       // Verify config file exists

src/commands/generateOperations.ts

@@ -1,3 +1,8 @@
+/**
+ * Copyright IBM Corp. 2025
+ * Assisted by CursorAI
+ */
+
 import * as vscode from "vscode";
 import * as path from "path";
 import * as fs from "fs";
@@ -9,7 +14,7 @@ import {
 } from "../utils/stepzenProjectScanner";
 import { resolveStepZenProjectRoot } from "../utils/stepzenProject";
 import { services } from "../services";
-import { FILE_PATTERNS, GRAPHQL } from "../utils/constants";
+import { FILE_PATTERNS, GRAPHQL, MESSAGES, TEMP_FILE_PATTERNS } from "../utils/constants";
 import { handleError, StepZenError } from "../errors";
 
 // Maximum depth for field traversal
@@ -46,7 +51,7 @@ export async function generateOperations() {
     }
 
     // Ensure operations directory exists
-    const operationsDir = path.join(projectRoot, "operations");
+    const operationsDir = path.join(projectRoot, FILE_PATTERNS.OPERATIONS_DIR);
     if (!fs.existsSync(operationsDir)) {
       fs.mkdirSync(operationsDir, { recursive: true });
       services.logger.info(`Created operations directory at: ${operationsDir}`);
@@ -106,12 +111,12 @@ export async function generateOperations() {
           fieldInfo,
           fieldIdx,
         );
-        const fileName = `query_${fieldName}.graphql`;
+        const fileName = `query_${fieldName}${TEMP_FILE_PATTERNS.GRAPHQL_EXTENSION}`;
         const filePath = path.join(operationsDir, fileName);
 
         // If file already exists, create a versioned one
         if (fs.existsSync(filePath)) {
-          const versionedFileName = `query_${fieldName}_${timestamp}.graphql`;
+          const versionedFileName = `query_${fieldName}_${timestamp}${TEMP_FILE_PATTERNS.GRAPHQL_EXTENSION}`;
           const versionedFilePath = path.join(operationsDir, versionedFileName);
           fs.writeFileSync(versionedFilePath, queryContent);
           generatedFiles.push(versionedFilePath);
@@ -379,7 +384,7 @@ function updateSdlDirective(
     } else if (sdlWithoutExecutablesMatch) {
       // SDL directive exists but doesn't have executables
       services.logger.info(
-        "Found SDL directive without executables in index.graphql. Adding executables array.",
+        MESSAGES.FOUND_SDL_WITHOUT_EXECUTABLES,
       );
 
       try {
@@ -430,9 +435,9 @@ function updateSdlDirective(
       }
     } else {
       // No SDL directive found at all
-      services.logger.warn("Could not find SDL directive in index.graphql.");
+      services.logger.warn(MESSAGES.COULD_NOT_FIND_SDL_DIRECTIVE);
       vscode.window.showWarningMessage(
-        "Could not find @sdl directive in index.graphql. Please add the generated operations manually.",
+        MESSAGES.COULD_NOT_FIND_SDL_DIRECTIVE,
       );
     }
   } catch (err) {

src/commands/initializeProject.ts

@@ -1,9 +1,14 @@
+/**
+ * Copyright IBM Corp. 2025
+ * Assisted by CursorAI
+ */
+
 import * as vscode from "vscode";
 import * as fs from "fs";
 import * as path from "path";
 import { execSync } from "child_process";
 import { StepZenError, handleError } from "../errors";
-import { FILE_PATTERNS } from "../utils/constants";
+import { FILE_PATTERNS, URLS, MESSAGES } from "../utils/constants";
 import { services } from "../services";
 
 /**
@@ -27,7 +32,7 @@ async function checkStepZenCLI(): Promise<boolean> {
 
       if (installOption === "Install Instructions") {
         vscode.env.openExternal(
-          vscode.Uri.parse("https://stepzen.com/docs/stepzen-cli/install"),
+          vscode.Uri.parse(URLS.STEPZEN_CLI_INSTALL),
         );
       }
 
@@ -233,18 +238,18 @@ async function createProject(
     }
 
     // Create operations directory
-    const operationsDir = path.join(projectDir, "operations");
+    const operationsDir = path.join(projectDir, FILE_PATTERNS.OPERATIONS_DIR);
     if (!fs.existsSync(operationsDir)) {
       await vscode.workspace.fs.createDirectory(vscode.Uri.file(operationsDir));
     }
 
     // Create stepzen.config.json
-    const configPath = path.join(projectDir, "stepzen.config.json");
+    const configPath = path.join(projectDir, FILE_PATTERNS.CONFIG_FILE);
     const configContent = JSON.stringify({ endpoint }, null, 2);
     fs.writeFileSync(configPath, configContent);
 
     // Create index.graphql
-    const indexPath = path.join(projectDir, "index.graphql");
+    const indexPath = path.join(projectDir, FILE_PATTERNS.MAIN_SCHEMA_FILE);
     const indexContent = `schema
   @sdl(
     files: [
@@ -266,8 +271,8 @@ extend type Query {
     // Create operations/example.graphql
     const sampleOperationPath = path.join(
       projectDir,
-      "operations",
-      "example.graphql",
+      FILE_PATTERNS.OPERATIONS_DIR,
+      FILE_PATTERNS.EXAMPLE_GRAPHQL_FILE,
     );
     const sampleOperationContent = `# Example GraphQL operations for your StepZen API
 # This query works with the default schema
@@ -431,12 +436,12 @@ export async function initializeProject() {
     // Step 5: Open project in editor
     const openOption = await vscode.window.showInformationMessage(
       `StepZen project created successfully at ${targetLocation}`,
-      "Open index.graphql",
+      MESSAGES.OPEN_INDEX_GRAPHQL,
       "Open Project Folder",
     );
 
-    if (openOption === "Open index.graphql") {
-      const indexPath = path.join(targetLocation, "index.graphql");
+    if (openOption === MESSAGES.OPEN_INDEX_GRAPHQL) {
+      const indexPath = path.join(targetLocation, FILE_PATTERNS.MAIN_SCHEMA_FILE);
       if (fs.existsSync(indexPath)) {
         const document = await vscode.workspace.openTextDocument(indexPath);
         await vscode.window.showTextDocument(document);

src/commands/openExplorer.ts

@@ -10,6 +10,7 @@ import { execSync } from "child_process";
 import { StepZenError, handleError } from "../errors";
 import { StepZenConfig } from "../types";
 import { services } from "../services";
+import { FILE_PATTERNS, MESSAGES, UI } from "../utils/constants";
 
 /**
  * Helper function to get StepZen configuration information
@@ -29,7 +30,7 @@ function getStepZenInfo(workspaceFolderPath: string): {
     const domain = execSync("stepzen whoami --domain").toString().trim();
     const apiKey = execSync("stepzen whoami --apikey").toString().trim();
 
-    const configPath = path.join(workspaceFolderPath, "stepzen.config.json");
+    const configPath = path.join(workspaceFolderPath, FILE_PATTERNS.CONFIG_FILE);
     if (!fs.existsSync(configPath)) {
       throw new StepZenError(
         `StepZen configuration file not found at: ${configPath}`, 
@@ -73,8 +74,8 @@ export function openQueryExplorer(context: vscode.ExtensionContext) {
     services.logger.info("Starting Open Query Explorer command");
 
     const panel = vscode.window.createWebviewPanel(
-      "stepzenExplorer",
-      "StepZen Query Explorer",
+      UI.EXPLORER_VIEW_TYPE,
+      UI.EXPLORER_TITLE,
       vscode.ViewColumn.Beside,
       {
         enableScripts: true,
@@ -84,10 +85,10 @@ export function openQueryExplorer(context: vscode.ExtensionContext) {
     const workspaceFolders = vscode.workspace.workspaceFolders;
     if (!workspaceFolders) {
       const error = new StepZenError(
-        "No workspace open", 
+        MESSAGES.NO_WORKSPACE_OPEN, 
         "WORKSPACE_ERROR"
       );
-      vscode.window.showErrorMessage("No workspace open");
+      vscode.window.showErrorMessage(MESSAGES.NO_WORKSPACE_OPEN);
       services.logger.warn("Open Query Explorer failed: No workspace open");
       handleError(error);
       return;

src/commands/runRequest.ts

@@ -13,6 +13,7 @@ import { services } from "../services";
 // Import executeStepZenRequest from separate file
 import { executeStepZenRequest } from "./executeStepZenRequest";
 import { handleError, ValidationError } from "../errors";
+import { GRAPHQL, MESSAGES } from "../utils/constants";
 
 /* -------------------------------------------------------------
  * Helpers
@@ -28,8 +29,7 @@ function extractOperationNames(query: string): string[] {
     return [];
   }
 
-  const regex = /(query|mutation|subscription)\s+(\w+)/g;
-  return [...query.matchAll(regex)].map(([, , name]) => name);
+  return [...query.matchAll(GRAPHQL.OPERATION_TYPE_PATTERN)].map(([, , name]) => name);
 }
 
 /**
@@ -58,7 +58,7 @@ function extractOperationNames(query: string): string[] {
 //   return tmp;
 // }
 
-const SCALARS = new Set(["String", "ID", "Int", "Float", "Boolean"]);
+const SCALARS = new Set<string>(GRAPHQL.SCALAR_TYPES);
 
 /* -------------------------------------------------------------
  * Helper – ask user for variable values / file
@@ -167,15 +167,14 @@ export async function runGraphQLRequest() {
 
     // Check workspace trust first
     if (!vscode.workspace.isTrusted) {
-      const message = "Running GraphQL requests is not available in untrusted workspaces. Open this folder in a trusted workspace to enable this feature.";
-      vscode.window.showWarningMessage(message);
+      vscode.window.showWarningMessage(MESSAGES.FEATURE_NOT_AVAILABLE_UNTRUSTED);
       services.logger.warn("Run GraphQL Request failed: Workspace not trusted");
       return;
     }
 
     const editor = vscode.window.activeTextEditor;
     if (!editor) {
-      vscode.window.showErrorMessage("No active editor with GraphQL request.");
+      vscode.window.showErrorMessage(MESSAGES.NO_ACTIVE_EDITOR);
       services.logger.warn("Run GraphQL Request failed: No active editor");
       return;
     }
@@ -203,7 +202,7 @@ export async function runGraphQLRequest() {
     const ops = extractOperationNames(query);
     if (ops.length > 1) {
       operationName = await vscode.window.showQuickPick(ops, {
-        placeHolder: "Multiple operations found. Select one to execute.",
+        placeHolder: MESSAGES.SELECT_OPERATION_TO_EXECUTE,
       });
       if (!operationName) {
         services.logger.info("Run GraphQL Request cancelled by user");