Merge pull request #164 from sapientpants/feat/156-unified-versioning

feat: implement unified versioning system with single source of truth

Author: sapientpants

.changeset/unified-versioning.md

@@ -0,0 +1,23 @@
+---
+'deepsource-mcp-server': minor
+---
+
+Add unified versioning system with single source of truth
+
+- Created central `version.ts` module that reads from package.json
+- Added CLI support for `--version` and `-v` flags to display version
+- Added `--help` and `-h` flags with comprehensive help text
+- Replaced all hardcoded version strings with VERSION constant
+- Added version to startup logging for better debugging
+- Created build script to inject version at build time
+- Added comprehensive version utilities (parsing, validation, comparison)
+- Exported VERSION constant and helper functions for programmatic access
+- Added fallback to "0.0.0-dev" when package.json is unavailable
+
+This ensures consistent version reporting across:
+
+- CLI output
+- Server metadata
+- Startup logs
+- Error messages
+- MCP protocol responses

.deepsource.toml

@@ -22,7 +22,8 @@ exclude_patterns = [
   "jest.setup.ts",
   "vitest.setup.ts",
   "docs/**",
-  "examples/**"
+  "examples/**",
+  "scripts/**"
 ]
 
 [[analyzers]]

package.json

@@ -27,7 +27,7 @@
   },
   "scripts": {
     "build:watch": "tsc -p tsconfig.build.json --watch",
-    "build": "tsc -p tsconfig.build.json",
+    "build": "tsc -p tsconfig.build.json && node scripts/build-with-version.js",
     "changeset:status": "changeset status --since=main",
     "changeset": "changeset",
     "ci:local:fast": "./scripts/ci-local.sh --fast",

scripts/build-with-version.js

@@ -0,0 +1,93 @@
+#!/usr/bin/env node
+
+/* eslint-disable no-console */
+
+/**
+ * Build script that injects the version from package.json into the compiled code
+ * This ensures the version is available even when package.json is not accessible at runtime
+ */
+
+import { readFileSync, writeFileSync, readdirSync, statSync } from 'fs';
+import { join, dirname } from 'path';
+import { fileURLToPath } from 'url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+// Read version from package.json
+const packageJsonPath = join(__dirname, '..', 'package.json');
+const packageJson = JSON.parse(readFileSync(packageJsonPath, 'utf-8'));
+const version = packageJson.version;
+
+console.log(`Build script: Injecting version ${version} into compiled files...`);
+
+// Function to recursively find all JavaScript files in dist
+function findJsFiles(dir, files = []) {
+  const items = readdirSync(dir);
+
+  for (const item of items) {
+    const fullPath = join(dir, item);
+    const stat = statSync(fullPath);
+
+    if (stat.isDirectory()) {
+      findJsFiles(fullPath, files);
+    } else if (item.endsWith('.js')) {
+      files.push(fullPath);
+    }
+  }
+
+  return files;
+}
+
+// Path to dist directory
+const distDir = join(__dirname, '..', 'dist');
+
+try {
+  // Find all JavaScript files in dist
+  const jsFiles = findJsFiles(distDir);
+
+  // Look for version.js specifically
+  const versionFile = jsFiles.find((file) => file.endsWith('version.js'));
+
+  if (versionFile) {
+    // Read the file
+    let content = readFileSync(versionFile, 'utf-8');
+
+    // Replace the placeholder with the actual version
+    const originalContent = content;
+    content = content.replace(/__BUILD_VERSION__/g, version);
+
+    // Only write if something changed
+    if (content !== originalContent) {
+      writeFileSync(versionFile, content, 'utf-8');
+      console.log(`✓ Injected version ${version} into ${versionFile}`);
+    } else {
+      console.log(`✓ Version already set correctly in ${versionFile}`);
+    }
+  } else {
+    console.warn('Warning: version.js not found in dist directory');
+  }
+
+  // Also update any other files that might reference __BUILD_VERSION__
+  let filesUpdated = 0;
+  for (const file of jsFiles) {
+    if (file === versionFile) continue; // Already handled
+
+    let content = readFileSync(file, 'utf-8');
+    if (content.includes('__BUILD_VERSION__')) {
+      content = content.replace(/__BUILD_VERSION__/g, version);
+      writeFileSync(file, content, 'utf-8');
+      filesUpdated++;
+      console.log(`✓ Updated version in ${file}`);
+    }
+  }
+
+  if (filesUpdated > 0) {
+    console.log(`✓ Updated version in ${filesUpdated} additional file(s)`);
+  }
+
+  console.log('✓ Build version injection complete');
+} catch (error) {
+  console.error('Error during version injection:', error);
+  process.exit(1);
+}

src/__tests__/cli-version.test.ts

@@ -0,0 +1,118 @@
+/**
+ * @fileoverview Tests for CLI version flag functionality
+ */
+
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { VERSION, getVersion, getVersionInfo, parseVersion } from '../version.js';
+import { handleCliArgs } from '../index.js';
+
+describe('CLI Version Module', () => {
+  describe('Version exports', () => {
+    it('should export VERSION constant matching expected format', () => {
+      expect(VERSION).toMatch(/^\d+\.\d+\.\d+(-.*)?$/);
+    });
+
+    it('should return version from getVersion function', () => {
+      expect(getVersion()).toBe(VERSION);
+    });
+
+    it('should return version info from getVersionInfo', () => {
+      const info = getVersionInfo();
+      expect(info.version).toBe(VERSION);
+
+      const parsed = parseVersion(VERSION);
+      if (parsed) {
+        expect(info.major).toBe(parsed.major);
+        expect(info.minor).toBe(parsed.minor);
+        expect(info.patch).toBe(parsed.patch);
+      }
+    });
+  });
+
+  describe('CLI argument handling', () => {
+    let consoleLogSpy: ReturnType<typeof vi.spyOn>;
+    let logOutput: string[];
+
+    beforeEach(() => {
+      logOutput = [];
+      // Mock console.log to capture output
+      consoleLogSpy = vi.spyOn(console, 'log').mockImplementation((...args) => {
+        logOutput.push(args.join(' '));
+      });
+    });
+
+    afterEach(() => {
+      consoleLogSpy.mockRestore();
+    });
+
+    it('should display version with --version flag', () => {
+      const result = handleCliArgs(['--version']);
+
+      expect(result).toBe(true);
+      expect(logOutput).toContain(`deepsource-mcp-server version ${VERSION}`);
+    });
+
+    it('should display version with -v flag', () => {
+      const result = handleCliArgs(['-v']);
+
+      expect(result).toBe(true);
+      expect(logOutput).toContain(`deepsource-mcp-server version ${VERSION}`);
+    });
+
+    it('should display help with --help flag', () => {
+      const result = handleCliArgs(['--help']);
+
+      expect(result).toBe(true);
+      expect(logOutput.join('\n')).toContain(`DeepSource MCP Server v${VERSION}`);
+      expect(logOutput.join('\n')).toContain('Usage: deepsource-mcp-server [options]');
+      expect(logOutput.join('\n')).toContain('Options:');
+      expect(logOutput.join('\n')).toContain('-v, --version  Display version information');
+      expect(logOutput.join('\n')).toContain('-h, --help     Display this help message');
+    });
+
+    it('should display help with -h flag', () => {
+      const result = handleCliArgs(['-h']);
+
+      expect(result).toBe(true);
+      expect(logOutput.join('\n')).toContain(`DeepSource MCP Server v${VERSION}`);
+      expect(logOutput.join('\n')).toContain('Usage: deepsource-mcp-server [options]');
+    });
+
+    it('should handle --version flag at any position', () => {
+      const result = handleCliArgs(['some', 'args', '--version']);
+
+      expect(result).toBe(true);
+      expect(logOutput).toContain(`deepsource-mcp-server version ${VERSION}`);
+    });
+
+    it('should return false for non-CLI arguments', () => {
+      const result = handleCliArgs(['some', 'other', 'args']);
+
+      expect(result).toBe(false);
+      expect(logOutput).toEqual([]);
+    });
+
+    it('should handle empty arguments', () => {
+      const result = handleCliArgs([]);
+
+      expect(result).toBe(false);
+      expect(logOutput).toEqual([]);
+    });
+
+    it('should work without DEEPSOURCE_API_KEY for version flag', () => {
+      // Remove DEEPSOURCE_API_KEY if present
+      const originalApiKey = process.env.DEEPSOURCE_API_KEY;
+      delete process.env.DEEPSOURCE_API_KEY;
+
+      const result = handleCliArgs(['--version']);
+
+      expect(result).toBe(true);
+      expect(logOutput).toContain(`deepsource-mcp-server version ${VERSION}`);
+
+      // Restore API key if it was set
+      if (originalApiKey) {
+        process.env.DEEPSOURCE_API_KEY = originalApiKey;
+      }
+    });
+  });
+});